commerce-app-review

自查 App Builder 应用

根据 Adobe Commerce 提交指南检查本地应用目录，并逐项引导用户审查发现的问题——先处理必须解决的阻碍项，再查看建议优化项。

输入

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

流程

1. 验证路径和应用类型

如果未提供 APP_PATH，则使用当前工作目录。确认该路径存在且为目录。否则，停止并报告：

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

如果未提供 APP_TYPE，请询问：

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

• 可下载 — 商家下载源代码包并自行部署
• 不可下载 — 商家可直接通过 Adobe Exchange 一键安装

在确认两项信息之前，不要继续。

检查是否已安装 aio（例如，command -v aio）。这仅用于检查是否存在——此时不要尝试进行身份验证。如果未找到 aio，只需提示一次：

注意：尚未安装 aio。第 8 步的逐项审查补充内容将使用备用知识， 除非届时已安装并完成身份验证。

无论结果如何，都继续。

2. 加载本地参考资料

读取 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. 获取指南

使用 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. 阅读应用文件

按以下顺序读取这些文件：

1. app.config.yaml — 扩展点、操作、输入、注释、productDependencies
2. package.json — name、description、author、version、dependencies、scripts
3. env.dist / env.example / 根目录下的任何 env.* — 已记录的环境变量
4. README.md — 安装说明、事件、API 要求
5. deploy.yaml — 应用 ID、API、工作区
6. install.yaml — 扩展点（如果检测到 Admin UI SDK）
7. src/ 和 actions/ 下的所有 *.config.yaml 和 ext.config.yaml
8. actions/ 下的所有 index.js
9. web-src/src/ — UI 代码、innerHTML、路由
10. extension-manifest.json — 如果检测到 Admin UI SDK

如果文件不存在，请记录并继续。

5. 审查

根据模式文件和获取的指南，整理出完整的检查项清单。然后逐项默默检查，不要跳过任何一项。

完全排除以下内容——不要检查：

• npm audit、npx npm-check 或任何需要运行 npm 的检查
• Exchange 列表页面 URL、仓库可见性、Exchange 列表页面中的屏幕截图
• 任何需要访问实时 Exchange 列表页面、已部署环境或外部 URL 的检查

对于每一项：

• 根据第 4 步读取的文件进行检查
• 如果确认 → 记录为 FINDING，并注明严重程度、文件和行号
• 如果 references/exceptions/ 中的例外适用 → 忽略该项
• 如果不适用于 APP_TYPE → 跳过

记录任何 FINDING 之前，先在实际文件中核实。如果无法指出具体文件和行号，就不要标记。

标记缺失的软件包之前，请确认源文件中直接导入了该软件包，而不只是将其作为传递依赖。

完成所有项目的检查后，收集所有 FINDING，并分配代码：MUST-<n> 和 NICE-<n>。分配代码前，合并密切相关的 FINDING。

对于每个 finding，记录：

• SEVERITY — MUST 或 NICE
• DESCRIPTION — 一句话说明具体且可执行的建议
• FILE_PATH — 相关文件的绝对路径；一般性问题则留空。渲染为 Markdown 链接：[relative/path](file:///absolute/path)
• LINE_NUMBER — 具体行号；一般性问题填 0
• CATEGORY — 以下类别中的一个或多个：security · documentation · code · dependencies · other

6. 展示原始 findings 列表

打印简洁的 findings 列表——暂不补充细节。格式：

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: …

如果某个分组为空，则省略该组标题。若 FILE_PATH 为空，则省略文件引用。

列表后显示：

输入 walkthrough 逐项查看 · 输入 MUST-n 或 NICE-n 深入了解某一项 · 或提出任何问题。

然后等待用户回复。

7. 回复用户

• “walkthrough”（或含义相同的请求）→ 转到第 8 步
• finding 代码（例如 “MUST-2”、“NICE-1”）→ 补充该 finding 的细节并展示；再次显示操作提示行，然后等待
• 其他内容 → 回答用户；再次显示操作提示行，然后等待

重复此流程，直到用户结束会话或所有 findings 均已逐项查看。

8. 逐项查看模式

按顺序逐项查看所有 findings——先 MUST，再 NICE。开始前，获取 IMS 令牌（见下文）。

• 如果某个分组为空，请说明并继续。
• 对于每个 finding，按代码顺序执行：
  1. 显示带编号的标题（例如 --- MUST issue [n/N] ---）
  2. 补充该 finding 的细节并打印
  3. 显示：回复 **"resolve it"** 与你一起处理此项 · 回复 **"next"** 继续 · 或提出任何问题
  4. 等待用户回复

查看完最后一项后，以简短的鼓励语收尾，说明已解决的 findings 数量（例如“已解决 X 项，共 N+M 项 findings”），并祝开发者好运。

---

获取 IMS 令牌

在本次会话中，首次需要补充细节时运行一次：

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

• 如果 $IMS_TOKEN 不为空 → 使用文档 Agent 补充细节。
• 如果为空 → 警告用户；请其运行 aio login 并重启，以获得最佳体验；询问是否要在不补充细节的情况下继续，或停止。

补充 finding 的细节

1. 如果 IMS 令牌可用，查询文档 Agent：

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}'

根据类别选择 index：

• security、deployment、code → app-builder-docs
• documentation、dependencies → commerce-extensibility-docs
• 默认 → 省略 index

2. 在 FILE_PATH 和 LINE_NUMBER 指定的位置读取实际文件。针对开发者的代码生成具体的修改前/修改后修复方案，而非通用示例。

3. 使用 references/finding.md 中的格式编写补充细节后的 finding。

如果 Agent 未返回结果，则使用 App Builder / Commerce 知识作为后备，并继续。

失败模式

• 未找到路径 → 停止并报告；不要继续
• 无法访问指南页面 → 说明哪个页面访问失败；继续使用另一个页面；提醒用户覆盖范围不完整
• 未安装 aio 或未通过身份验证 → 警告用户，指导他们运行 aio login，并询问是继续（不进行信息补充）还是停止
• 文档 Agent 未返回结果 → 回退到 App Builder / Commerce 知识；不要停止