fw-review

条目约定

• 调用方： 控制器在构建／验证里程碑后或收到明确的审查请求时调用
• 前置条件： 包含 manifest.json 的应用目录；fdk 可用，或用户已同意安装 fw-setup
• 返回： done（已生成审查报告）| blocked（缺少 fdk／应用目录）| escalate（无法恢复的清单问题）
• 完成后： 将控制权交还给控制器——由控制器提供发布选项；此技能不得调用 fw-publish
• 会话： 启动时运行 session-read.sh；通过时运行 session-write.sh <app-dir> --merge-json '{"progress":{"milestones":["review_passed"],"phase":"review"}}' step=reviewed

fw-review

这是一个自动化流程。确定应用目录后（见下方 Q1 预检），不得再提问或与用户互动以消除歧义——请静默执行剩余阶段，并且只输出 rules/report.md 中格式化的 App Review Result 块。不得在该块前后添加说明（包括通过／不适用的原因、脚本说明或流程状态）。

例外： 如果缺少 fdk，请遵循下方的 FDK CLI availability（停止 → 提供 /fw-setup-install → 可选的 y/n）——在 CLI 可用或用户拒绝安装之前，此交互优先于“仅静默执行”的要求。

预检：确定应用目录（Q1）

开始工作流前，请按照 fw-app-dev /fdk-fix Step 1: Determine app directory 中的相同步骤操作：

1. 在工作区中搜索 manifest.json 文件。
2. 如果有多个文件夹包含 manifest.json：询问用户要审查哪个应用（这是此技能唯一允许向用户提问的情况）。
3. 如果只有一个文件夹：使用该目录。
4. 如果没有：告知用户并停止。

下方工作流中的所有应用文件路径均相对于该目录（即包含 manifest.json 的文件夹）。请针对 <app-directory> 运行此技能的 scripts/ 中的确定性检查脚本（参见 README.md）。

工作流

按顺序运行以下阶段。详细检查标准见：[rules/**.md]。仅通过 rules/report.md 中的“问题／位置／修复”格式报告失败；不得另行使用文字总结通过、不适用或省略的检查。

前置要求

FDK CLI 可用性（Docker / CI / 本地）

Freshworks FDK CLI（fdk）未随此仓库打包，也不能假定通用 CI 镜像中已安装该工具。Jenkins 或 Kubernetes 节点镜像通常只包含 Node，不包含 fdk。请确认 FDK 已安装（例如，运行 fw-setup 技能中的 /fw-setup-status，或在 CLI 位于 PATH 中时运行 fdk --version）。

如果缺少 fdk（fdk --version 失败 / 提示找不到命令）：

• 停止——不要悄悄安装 CLI，也不要假装可以运行 fdk validate 后继续。
• 告知用户：在适用的验证环节中，完整审查需要 fdk CLI，且 fw-review 不会安装它。
• 提供 fw-setup：/fw-setup-install（默认安装 FDK 10.x + Node 24.11）或 /fw-setup-status。未经同意不要自动安装。
• 可选的一次性操作：询问“现在运行 /fw-setup-install？（y/n）”——只有用户回答 yes 时，才转到 skills/fw-setup/；如果回答 no，则指示用户自行安装后重新运行 fw-review。
• 输出例外：对于仅因工具链缺失而停止的情况，回复可以采用上面的简短消息，而不是 ## App Review Result 区块——在 fdk 可用且能够执行流程之前，不要输出完整的 App Review Result，以免让人误以为所有阶段均已运行。

1. 结构——首先读取应用目录中的 manifest.json，了解平台版本、模块、请求、事件和安装流程。
2. 安装参数——在应用目录中，使用 rules/iparam-rules.md 检查 config/iparams.json 或自定义的 config/iparams.html / config/assets/iparams.js。请遵循该文件中的发现顺序。
3. 确定性脚本检查——对于 rules/script-check-rules.md 中每条由脚本处理的规则 ID，运行此技能 scripts/ 目录中映射的 JS 文件，并将 <app-directory> 作为目标。将返回的任何内部元数据（例如 internal.rule_id）仅视为内部信息。
4. 前端逻辑检查——对于没有一一对应脚本的 FF-* 规则，请查阅 rules/frontend-files-rules.md。

规则

• 不要在本文件的规则 ID 摘要以及这些 ID 对应的 rules/*.md 文件中定义的标准之外，编造规则 ID 或通过/未通过标准。
• 必须对下方规则 ID 摘要中的每个规则 ID 作出评估，结果为通过、未通过或不适用。
• 必须严格按照 rules/report.md 中的规定输出 App Review Result 区块：
  • 唯一交付内容：面向用户的审核回复只能包含该区块——以 ## App Review Result 开头；其上方或下方不得添加任何内容（除 report.md 在区块内规定的内容外：标题，以及 successful 或编号列表）。不得包含规则 ID（GN-*、IP-*、FF-*、FFS-*、CR-*）、内部文件名（script-check-rules.md、其他 rules/*.md、scripts/*.js），也不得引用技能路径。
  • 输出为已渲染的 Markdown。最终报告不要用代码围栏包裹（不要在整个区块外加 \``text`）；直接输出 Markdown，以便标题、列表和链接在聊天客户端中正确渲染。
  • 标题始终使用二级 Markdown 标题 ## App Review Result，后面不加任何内容。标题下方：没有未通过项时，单独一行写 successful；有未通过项时，省略 successful，并按 rules/report.md 输出编号列表。
  • 每个未通过项为一个编号列表条目，包含两段：
    1. 以方括号括起的可点击位置链接结尾的问题描述句：<issue>. [ [<filename>(<qualifier>)](<filename>#L<start>-L<end>) ]。
    2. 缩进 3 个空格的 **Fix:** <imperative remediation> 段落，与同一列表项关联，并与问题段落之间空一行。
  • <qualifier>：单行使用 (N)，范围使用 (A-B)，没有精确行号的命名范围使用 (<scope label>)；引用整个文件时省略。链接目标相应为 <filename>#L<N>、<filename>#L<A>-L<B> 或 <filename>。同一位置有多处相关内容时，将它们放在一对外层方括号内，并以逗号分隔。
  • 位置链接外层的 [ 和 ] 是字面字符，方括号内各有一个空格。
  • 输出中不得显示区域名称、严重程度标签或规则 ID。内部按区域排序未通过项，顺序为 Iparams（IP-*）、Structure（FFS-*）、Frontend（FF-*）、Readability（CR-*）、Miscellaneous（GN-*）。
  • 输出编号列表前，先应用 rules/report.md 中的分组规则。
  • 遵循写作风格规则：问题描述不超过 120 个字符（位置链接除外），为一个现在时句子；修复建议不超过 2 个祈使句。位置限定词中不得使用 “approximately”、“around line” 或 “roughly”。
• 仅在内部评估时使用规则 ID。最终面向用户的报告中不得包含规则 ID，包括任何脚本 JSON 元数据中的 internal.rule_id。
• 如果脚本执行失败，不要因此停止整个审核。忽略本次运行中该规则检查，继续评估其余规则，并且只报告已确定的实际未通过项。
• 对于每个未通过项，尽可能标注文件和行号（或可识别的代码块）。

强制要求：写入 .meta.json — 不要跳过，完成此步骤前不要输出 App Review Result

评估完所有规则后立即运行，并在输出 ## App Review Result 块之前完成。切勿向开发者提及 .meta.json。

仅限脚本 — 不要手动编写 JSON。 切勿使用 Write、Edit、StrReplace 或 shell 重定向来创建或修改 <app-directory>/.meta.json。只能使用 ~/.fw-dev-tools/scripts/ 中的 meta-init.sh、meta-update.sh、meta-feedback.sh 和 meta-delete.sh。将 skill_version 设置为本文件 YAML frontmatter 中 version: 键对应的纯 semver（例如：version: "1.1.5" → skill_version=1.1.5；不带引号）。

meta-init.sh 会根据环境变量自动检测 IDE 客户端 — 无需手动传入。

bash ~/.fw-dev-tools/scripts/meta-init.sh <app-directory>
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-review \
  invoked=1 skill_version=<version>
# For each failed rule ID (repeat as needed — omit if all passed):
bash ~/.fw-dev-tools/scripts/meta-update.sh <app-directory> fw-review \
  review_failure_categories+=<rule-id>

然后输出 ## App Review Result 块。

配套文件

• rules/report.md — 仅规定最终 App Review Result 块的输出格式。
• rules/iparam-rules.md — IP-04A、IP-05A、IP-06A。
• rules/frontend-files-rules.md — 所有 FF-* 规则。
• rules/script-check-rules.md — 映射到 scripts/*.js 的脚本支持规则 ID。

规则 ID 摘要（已评估规则 ID 的权威列表）

区域	ID
iparams	IP-04A、IP-05A、IP-06A
文件和文件夹结构	FFS-02L、FFS-04L、FFS-05L
前端	FF-01L、FF-07L、FF-02M、FF-03A、FF-04A、FF-05A、FF-06A、FF-08A
代码可读性	CR-05L
其他	GN-02L、GN-08L、GN-12L