commerce-app-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Self-review an App Builder app

App Builder应用自审查

Reviews a local app directory against Adobe's Commerce submission guidelines and walks through each finding interactively — MUST-have blockers first, then NICE-to-have recommendations.

针对Adobe Commerce提交指南审查本地应用目录，并交互式地引导用户排查每个问题——优先处理必须解决的阻塞问题，再给出建议优化项。

Inputs

输入参数

```
APP_PATH
```
(optional) — path to the app root. Defaults to the current working directory.
```
APP_TYPE
```
(required) —
```
downloadable
```
or
```
non-downloadable
```
. A downloadable app allows merchants to download the source package; a non-downloadable app is installed directly from Adobe Exchange with one click.

```
APP_PATH
```
（可选）——应用根目录路径，默认值为当前工作目录。
```
APP_TYPE
```
（必填）——
```
downloadable
```
或
```
non-downloadable
```
。可下载应用允许商家下载源码包；不可下载应用可直接从Adobe Exchange一键安装。

Procedure

流程步骤

1. Validate the path and app type

1. 验证路径与应用类型

APP_PATH

is not provided, use the current working directory. Confirm it exists and is a directory. If not, stop and report:

Path not found. Please provide the path to the root of your app codebase.

APP_TYPE

is not provided, ask:

Is this app downloadable or non-downloadable?

Downloadable — merchants download the source package and deploy it themselves

Non-downloadable — merchants install directly from Adobe Exchange with one click

Do not proceed until both are confirmed.

Check whether

aio

is installed (e.g.

command -v aio

). This is a presence check only — do not attempt to authenticate at this stage. If

aio

is not found, note it once:

Note:
aio
isn't installed. Walkthrough enrichment (Step 8) will use fallback knowledge unless
aio
is installed and authenticated before then.

Continue either way.

若未提供

APP_PATH

，则使用当前工作目录。确认该路径存在且为目录，若不存在则停止并报告：

路径未找到。请提供应用代码库的根目录路径。

若未提供

APP_TYPE

，则询问：

此应用是可下载还是不可下载类型？

可下载——商家下载源码包并自行部署

不可下载——商家直接从Adobe Exchange一键安装

需在确认两个参数后再继续。

检查

aio

是否已安装（例如执行

command -v aio

）。仅检查是否存在，此阶段不尝试认证。若未找到

aio

，则仅提示一次：

注意：未安装
aio
。除非在步骤8前安装并认证
aio
，否则排查增强环节（步骤8）将使用备用知识库。

无论是否安装

aio

，均继续后续流程。

2. Load local references

2. 加载本地参考文件

Read

references/finding.md

and all files under

references/exceptions/

(paths relative to this skill file).

Load pattern files conditionally:

references/patterns/cors-storefront-actions.md — always
references/patterns/accs-rest-api-dependency.md — always
references/patterns/aio-commerce-sdk.md — always
references/patterns/admin-ui-sdk.md — only if commerce/backend-ui/1 is in app.config.yaml or ext.config.yaml, or @adobe/uix-guest/@adobe/uix-core in package.json

Pattern files take precedence over fetched guidelines. Exception files suppress findings from both.

If any file is not found, skip and continue.

读取

references/finding.md

以及

references/exceptions/

下的所有文件（路径相对于本技能文件）。

有条件地加载模式文件：

references/patterns/cors-storefront-actions.md ——始终加载
references/patterns/accs-rest-api-dependency.md ——始终加载
references/patterns/aio-commerce-sdk.md ——始终加载
references/patterns/admin-ui-sdk.md ——仅当app.config.yaml或ext.config.yaml中包含commerce/backend-ui/1，或package.json中包含@adobe/uix-guest/@adobe/uix-core时加载

模式文件优先级高于获取的指南文件，例外文件可屏蔽来自两者的问题提示。

若任何文件未找到，则跳过并继续。

3. Fetch the guidelines

3. 获取官方指南

Fetch both pages using

curl

. Use raw GitHub URLs — the rendered developer.adobe.com pages are not reliably accessible:

Submission guidelines:

https://raw.githubusercontent.com/AdobeDocs/commerce-extensibility/refs/heads/main/src/pages/app-development/app-submission-guidelines.md

Admin UI SDK checklist:

https://raw.githubusercontent.com/AdobeDocs/commerce-extensibility/refs/heads/main/src/pages/admin-ui-sdk/app-review-checklist.md

— only if

commerce/backend-ui/1

is in

app.config.yaml

ext.config.yaml

, or

@adobe/uix-guest

@adobe/uix-core

package.json

If a page is unreachable, note which one failed, proceed with the other, and warn the user that coverage is partial.

使用

curl

获取以下两个页面，需使用GitHub原始URL——渲染后的developer.adobe.com页面无法保证稳定访问：

提交指南：

https://raw.githubusercontent.com/AdobeDocs/commerce-extensibility/refs/heads/main/src/pages/app-development/app-submission-guidelines.md

Admin UI SDK检查清单：
```
https://raw.githubusercontent.com/AdobeDocs/commerce-extensibility/refs/heads/main/src/pages/admin-ui-sdk/app-review-checklist.md
```
——仅当app.config.yaml或ext.config.yaml中包含commerce/backend-ui/1，或package.json中包含@adobe/uix-guest/@adobe/uix-core时获取

若某页面无法访问，需记录哪个页面获取失败，使用另一个页面继续，并警告用户检查覆盖范围不完整。

4. Read the app

4. 读取应用文件

Read these files in order:

```
app.config.yaml
```
— extension points, actions, inputs, annotations, productDependencies
```
package.json
```
— name, description, author, version, dependencies, scripts
```
env.dist
```
/
```
env.example
```
/ any
```
env.*
```
at the root — documented env vars
```
README.md
```
— installation instructions, events, API requirements
```
deploy.yaml
```
— app ID, APIs, workspaces
```
install.yaml
```
— extension points (if Admin UI SDK detected)

Every

*.config.yaml

and

ext.config.yaml

under

src/

and

actions/

Every
```
index.js
```
under
```
actions/
```
```
web-src/src/
```
— UI code, innerHTML, routing
```
extension-manifest.json
```
— if Admin UI SDK detected

If a file does not exist, note it and continue.

按以下顺序读取文件：

```
app.config.yaml
```
——扩展点、操作、输入、注解、产品依赖
```
package.json
```
——名称、描述、作者、版本、依赖、脚本
```
env.dist
```
/
```
env.example
```
/根目录下所有
```
env.*
```
文件——已文档化的环境变量
```
README.md
```
——安装说明、事件、API要求
```
deploy.yaml
```
——应用ID、API、工作区
```
install.yaml
```
——扩展点（若检测到Admin UI SDK）

src/

和

actions/

下的所有

*.config.yaml

和

ext.config.yaml

```
actions/
```
下的所有
```
index.js
```
```
web-src/src/
```
——UI代码、innerHTML、路由
```
extension-manifest.json
```
——若检测到Admin UI SDK

若某文件不存在，需记录并继续。

5. Review

5. 执行审查

Build a complete list of checks from the pattern files and fetched guidelines. Then work through every item silently, one by one. Do not skip any item.

Exclude the following entirely — do not check:

```
npm audit
```
,
```
npx npm-check
```
, or any check requiring running npm
Exchange listing URL, repository visibility, screenshots in Exchange listing
Any check requiring a live Exchange listing, deployed environment, or external URL

For each item:

Check it against the files read in Step 4
If confirmed → record as FINDING with severity, file, and line number
If an exception in
```
references/exceptions/
```
applies → suppress it
If not applicable to
```
APP_TYPE
```
→ skip it

Before recording any FINDING, verify it in the actual files. If you cannot point to a specific file and line number, do not flag it.

Before flagging a missing package — verify it is directly imported in source files, not just a transitive dependency.

After working through all items, collect all FINDINGs and assign codes:

MUST-<n>

and

NICE-<n>

. Merge closely related findings before assigning codes.

For each finding track:

```
SEVERITY
```
—
```
MUST
```
or
```
NICE
```
```
DESCRIPTION
```
— one sentence, specific and actionable
```
FILE_PATH
```
— absolute path to the relevant file; empty for general issues. Render as a markdown link:
```
[relative/path](file:///absolute/path)
```
```
LINE_NUMBER
```
— specific line; 0 for general issues

CATEGORY

— one or more of:

security

documentation

code

dependencies

other

根据模式文件和获取的指南构建完整的检查项列表，然后逐一静默检查所有项，不得跳过任何项。

完全排除以下检查项——不进行检查：

```
npm audit
```
、
```
npx npm-check
```
或任何需要运行npm的检查
Exchange上架URL、仓库可见性、Exchange上架截图
任何需要已上架Exchange应用、已部署环境或外部URL的检查

针对每个检查项：

对照步骤4中读取的文件进行检查
若确认存在问题→记录为FINDING，包含严重级别、文件和行号
若
```
references/exceptions/
```
中的例外规则适用→屏蔽该问题
若不适用于当前
```
APP_TYPE
```
→跳过

记录任何FINDING前，需在实际文件中验证。若无法指向具体文件和行号，则不得标记该问题。

标记缺失的包前，需验证它是直接导入到源码文件中，而非仅为传递依赖。

完成所有项检查后，收集所有FINDING并分配代码：

MUST-<n>

和

NICE-<n>

。在分配代码前，合并密切相关的问题。

针对每个问题记录：

```
SEVERITY
```
——
```
MUST
```
（必须解决）或
```
NICE
```
（建议优化）
```
DESCRIPTION
```
——一句话描述，具体且可执行
```
FILE_PATH
```
——相关文件的绝对路径；通用问题留空。以Markdown链接形式呈现：
```
[relative/path](file:///absolute/path)
```
```
LINE_NUMBER
```
——具体行号；通用问题填0
```
CATEGORY
```
——以下一个或多个类别：
```
security
```
（安全）·
```
documentation
```
（文档）·
```
code
```
（代码）·
```
dependencies
```
（依赖）·
```
other
```
（其他）

6. Present the raw findings list

6. 展示原始问题列表

Print a concise findings list — no enrichment yet. Format:

Found N MUST-have issue(s) and M NICE-to-have recommendation(s).

**MUST — blockers**
- MUST-1: <one-line description> (`<FILE_PATH>`, line <LINE_NUMBER>)
- MUST-2: …

**NICE — recommendations**
- NICE-1: <one-line description> (`<FILE_PATH>`, line <LINE_NUMBER>)
- NICE-2: …

Omit a group heading if it is empty. Omit the file reference when

FILE_PATH

is empty.

After the list, show:

Type walkthrough to go through each finding · MUST-n or NICE-n to dig into a specific one · or ask anything.

Then wait for the user's response.

打印简洁的问题列表——暂不添加增强信息。格式如下：

发现N个必须解决的问题和M个建议优化项。

**MUST — 阻塞问题**
- MUST-1: <一行描述> (`<FILE_PATH>`, 第<LINE_NUMBER>行)
- MUST-2: …

**NICE — 建议优化**
- NICE-1: <一行描述> (`<FILE_PATH>`, 第<LINE_NUMBER>行)
- NICE-2: …

若某组无内容，则省略该组标题。若

FILE_PATH

为空，则省略文件引用。

列表展示后，显示：

输入walkthrough逐一排查每个问题 · 输入MUST-n或NICE-n深入查看特定问题 · 或提出其他问题。

然后等待用户响应。

7. Respond to the user

7. 响应用户操作

"walkthrough" (or equivalent intent) → go to Step 8
A finding code (e.g. "MUST-2", "NICE-1") → enrich that finding and present it; show the actions line again and wait
Anything else → answer it; show the actions line again and wait

Repeat until the user ends the session or all findings have been walked through.

输入"walkthrough"（或等效意图）→进入步骤8
输入问题代码（例如"MUST-2"、"NICE-1"）→增强该问题信息并展示，再次显示操作提示行并等待
其他输入→回答用户问题，再次显示操作提示行并等待

重复上述流程，直到用户结束会话或所有问题均已排查完毕。

8. Walkthrough mode

8. 交互式排查模式

Work through all findings sequentially — MUST first, then NICE. Before starting, obtain the IMS token (see below).

If the group is empty, say so and move on.
For each finding in code order:
1. Show a numbered header (e.g.
```
--- MUST issue [n/N] ---
```
  )
2. Enrich the finding and print it
3. Show:
```
**"resolve it"**
```
  to work on this finding together ·
```
**"next"**
```
  to move on · or ask anything
4. Wait for the user's reply

After the last finding, close with a short encouraging message including how many findings were resolved (e.g. "X of N+M findings resolved") and wish the developer good luck.

按顺序排查所有问题——先处理MUST类，再处理NICE类。开始前，获取IMS令牌（见下文）。

若某组无问题，则告知用户并继续下一组。
针对每个按代码排序的问题：
1. 显示编号标题（例如
```
--- MUST问题 [n/N] ---
```
  ）
2. 增强问题信息并打印
3. 显示：
```
**"resolve it"**
```
  共同解决此问题 ·
```
**"next"**
```
  跳过此问题 · 或提出其他问题
4. 等待用户回复

所有问题排查完毕后，发送简短鼓励信息，说明已解决的问题数量（例如"已解决N+M个问题中的X个"），并祝开发者顺利。

Obtain IMS token

获取IMS令牌

Run once per session, the first time enrichment is needed:

bash

IMS_TOKEN=$(aio auth login --bare 2>/dev/null)

If
```
$IMS_TOKEN
```
is non-empty → use the documentation agent for enrichment.
If empty → warn the user; instruct them to run
```
aio login
```
and restart for the best experience; ask whether to continue without enrichment or stop.

首次需要增强信息时，在会话中执行一次：

bash

IMS_TOKEN=$(aio auth login --bare 2>/dev/null)

若
```
$IMS_TOKEN
```
非空→使用文档代理增强信息。
若为空→警告用户；指导用户运行
```
aio login
```
并重启以获得最佳体验；询问用户是否继续无增强信息的排查或停止。

Enrich a finding

增强问题信息

If IMS token is available, query the documentation agent:

bash

curl -s -X POST https://commerce-docs-prod-endpoint-d0ctgyebe7bec8e6.a02.azurefd.net/api/query \
  -H "Authorization: Bearer $IMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "<topic derived from the finding>", "count": 5}'

Pick the

index

based on category:

```
security
```
,
```
deployment
```
,
```
code
```
→
```
app-builder-docs
```

documentation

dependencies

→

commerce-extensibility-docs

default → omit
```
index
```

Read the actual file at
```
FILE_PATH
```
and
```
LINE_NUMBER
```
. Generate a concrete before/after fix specific to the developer's code — not a generic example.
Compose the enriched finding using the format in
```
references/finding.md
```
.

If the agent returns no results, fall back to App Builder / Commerce knowledge and continue.

若IMS令牌可用，查询文档代理：

bash

curl -s -X POST https://commerce-docs-prod-endpoint-d0ctgyebe7bec8e6.a02.azurefd.net/api/query \
  -H "Authorization: Bearer $IMS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "<从问题衍生的主题>", "count": 5}'

根据类别选择

index

：

```
security
```
、
```
deployment
```
、
```
code
```
→
```
app-builder-docs
```

documentation

、

dependencies

→

commerce-extensibility-docs

默认情况→省略
```
index
```

读取
FILE_PATH
和
LINE_NUMBER
对应的实际文件。生成针对开发者代码的具体修复前后示例——而非通用示例。
使用
references/finding.md
中的格式编写增强后的问题信息。

若代理未返回结果，则 fallback 到App Builder/Commerce知识库继续。

Failure modes

故障模式

Path not found → stop and report; do not proceed
Guidelines page unreachable → note which failed; proceed with the other; warn coverage is partial
aio
not installed or not authenticated → warn the user, instruct them to run
```
aio login
```
, and ask whether to continue without enrichment or stop
Documentation agent returns no results → fall back to App Builder / Commerce knowledge; do not stop

路径未找到→停止并报告；不继续后续流程
指南页面无法访问→记录哪个页面失败；使用另一个页面继续；警告用户检查覆盖范围不完整
aio
未安装或未认证→警告用户，指导用户运行
```
aio login
```
，并询问用户是否继续无增强信息的排查或停止
文档代理未返回结果→fallback 到App Builder/Commerce知识库；不停止流程