wechat-miniprogram/ai-mode-skills/wxa-skills-validate

wxa-skills-validate

对小程序 AI SKILLs 产物执行"静态校验 → 原子接口执行 → 原子组件渲染 → 交付文档"的闭环校验，并在每一步失败时按错误类型分类就地修复 skill 源文件。

依赖

• Node.js ≥ 18（scripts/*.mjs 用到 node:crypto / 原生 fetch）
• 微信开发者工具（Nightly Electron Build 最新版）已安装，CLI 可执行：<DEVTOOLS_APP_PATH>/Contents/MacOS/cli -h（macOS 默认 <DEVTOOLS_APP_PATH>=/Applications/wechatwebdevtools.app）
• 开发者工具的服务端口必须开启：手动打开工具 → 设置 → 安全设置 → 打开「服务端口」。未开启时 CLI 连不上，execute / render 全部失败
• 调试基础库 ≥ 3.16.2；项目 AppID 已在「微信公众平台 - 基础功能 - AI 能力」申请通过「开发模式」
• 项目 project.config.json 含 appid；app.json 含 agent.skills；每个 skill 目录含 mcp.json + SKILL.md

运行过程中开发者工具可能弹授权窗，需手动授权；未授权会导致原子接口执行失败。

触发条件

出现下列任一情况时启动本技能：

• 显式要求对 skills 目录做 "校验 / 跑通 / 渲染 / 出交付文档" 中任一项
• 已有 skills 产物（无论来源）需要进入验证阶段
• 跑出 skills 的校验报错需要修复

必需信息

注：<skills-path> 已不再作为入参，脚本自动从 app.json 发现分包。

参考资料（按需加载）

进入"步骤 4：真机闭环"时必须先读 references/CLI_AGENT_REFERENCE.md，内含脚本用法、产物结构、读产物后的下一步动作、5 项核对对照表、失败回溯流程。

验收目标（不可降级）

• <project-path> 下 app.json 发现的每个 skill 分包，其 mcp.json 声明的所有原子接口必须跑通 execute（status === "ok" 且 invokeResult.isError !== true）。例外：敏感接口不真实执行——命中敏感关键词的接口由 V019 落盘 cli-agent-run/destructive-manifest.json，execute.mjs 读该 manifest 拦截（--confirm-destructive 放行）——只做静态校验，验收时视为「已跳过执行」而非未通过，需在报告标注 skipped_destructive。
• 所有带 _meta.ui.componentPath 的原子接口，必须跑通 render 且通过 5 项核对（见 references/CLI_AGENT_REFERENCE.md 第 2.3 节）。
• 单接口连续修复 3 轮仍不通过才允许挂起。不得跳过任何一项（敏感接口的执行跳过除外）。
• 静态/编译通过 ≠ 验收通过：须真机 execute + render 5 项核对；execute 未跑成时不得判通过、不产出 DELIVERY.md（见「不可修复类」与「终止条件 4」）。

执行清单（复制后勾选，逐项完成）

阶段 1 — 静态校验 + 编译校验
- [ ] 运行 `node validate.mjs <project-path>`（单参数，脚本自动发现 skill 分包并决定是否跑 preview）
- [ ] summary.errors === 0（含 V001~V021），否则按 T1~T9 分类修复后重跑
- [ ] summary.buildStatus === "pass"（静态 0 error 时 preview 会自动运行；
      若为 "skipped" 说明静态未过，先按上一项修复）
- [ ] 阅读 Build 行：若 stage=compile + FAIL，说明有语法/编译错误，必须修复
 
阶段 2 — 准备
- [ ] 确认 CLI 可执行：<DEVTOOLS_APP_PATH>/Contents/MacOS/cli -h
- [ ] （可选）显式启动 cli auto
 
阶段 3 — 构建执行计划
- [ ] 解析每个 <skill>/mcp.json 的 apis[]，按书写顺序 + 参数依赖做拓扑排序
- [ ] 建立"已知数据池"（空）
 
阶段 4 — execute 与 render（可独立执行）
对每个 {name}：
- [ ] execute 成功（status=ok 且 !isError）
- [ ] 若 mcp.json 有 _meta.ui.componentPath，render 可在任何时间点执行（不要求紧跟 execute）
- [ ] render 通过 --from-execute 复用最新的 execute 产物（args 取自 invokeResult.structuredContent）；
      structuredContent 缺失时必须先重跑 execute
- [ ] 5 项核对全部通过（主要依据：`consoleMessages.snapshotCard` 中的生命周期日志 + `[ai-mode] ... overflow monitor=on` 基线日志 + 不出现 `overflowed=true`；仅在具备图像读取能力时再辅助读截图）
 
阶段 5 — 交付
- [ ] 写 ./cli-agent-run/report.md
- [ ] 若全部通过，按 references/DELIVERY_TEMPLATE.md 写 ./DELIVERY.md 并回贴内容

工作目录

在 <project-path> 同级建 ./cli-agent-run/ 统一存放产物：

cli-agent-run/
├── validate-report.json                   # 阶段 1 产物
├── execute-result.<apiName>.json          # 阶段 4 execute 产物（含 invokeResult.structuredContent 供 render 继承）
├── render-result.<apiName>.json           # 阶段 4 render 产物（snapshot 摘要 + consoleMessages + elementTree）
├── render-result.<apiName>.snapshot.png   # 阶段 4 render 截图
├── execute-trace.json                     # 每次尝试的回溯日志
└── report.md                              # 阶段 5 执行报告
 
项目根目录/
└── DELIVERY.md                            # 全部通过时的最终交付文档

同一接口重跑时必须复用 --output（文件会被覆盖）；不同接口必须用不同文件名。

阶段 1 — 静态校验 + 编译校验（合并为一次运行）

运行：

node <skill-dir>/scripts/validate.mjs <miniprogram-project-path>

入参只需要一个——小程序项目根目录（含 project.config.json + app.json）。脚本自动：

1. 读 app.json 的 agent.skills[].path 发现 skill 分包（没配置时回退到顶层 metaServicePkg/ 或 skills/）
2. 静态规则只在 skill 分包目录内 执行，不触及主包代码
3. 把校验产物目录 cli-agent-run/ 写入 project.config.json 的 packOptions.ignore（打包忽略）和 watchOptions.ignore（监听忽略），避免开发者工具持续监听产物变更触发循环编译（已存在不会重复追加；产物落盘前完成同步，结果挂在报告 ignoreSync 字段）
4. 静态校验通过（errors === 0）后自动调用 cli preview 做编译校验；有 error 则跳过 preview
5. 报告落盘到 <project>/cli-agent-run/validate-report.json（可用 --output 覆盖）

可选参数：--rules <自定义规则 json> / --cli-path <CLI 路径> / --build-timeout <ms> / --output <path>。

退出码：0 通过；1 存在 error 或 build 失败；2 运行异常。

通过判据：

• summary.errors === 0（warning 允许带着进入阶段 2）
• summary.buildStatus === "pass"（静态 0 error 后会自动触发 build；"skipped" 意味着静态未过，先按修复决策表修复）
• Build 行 stage=compile + FAIL 说明有语法/编译错，必须修复

Build 编译报错时：优先检查集成配置，再动源码。对照 wxa-skills-generate SKILL.md 的"阶段 6 — 配置集成"与 references/CODE_TEMPLATES.md 的"六、app.json + project.config.json 配置"核对 app.json（agent.skills / subPackages）与 project.config.json（appid / packOptions.include）。集成无误后才按日志改源码，禁止用注释/删除源码的方式绕过集成问题。

CLI 未找到时的处理：若输出 Build: SKIPPED - 跳过：未找到微信开发者工具 CLI，说明脚本未能自动定位到 cli。自动探测顺序为：--cli-path > 环境变量 WECHAT_DEVTOOLS_CLI / WXA_CLI > macOS /Applications/wechatwebdevtools.app/Contents/MacOS/cli > 同路径的用户目录变体 > Windows C:\Program Files (x86)\Tencent\微信web开发者工具\cli.bat。此时应主动向用户询问微信开发者工具的安装路径，然后：

• 重跑：node validate.mjs <project-path> --cli-path <用户提供的绝对 cli 路径>
• 或建议用户设置环境变量：export WECHAT_DEVTOOLS_CLI=<绝对路径> 后重跑

CLI 缺失不影响静态规则的输出，只会让 build 阶段被 skip。

执行顺序（脚本内部闭环）：

1. 同步 project.config.json 的 packOptions.ignore + watchOptions.ignore（追加 cli-agent-run/）
2. 发现 skill 分包 → 只在分包内跑 V001~V021
3. 有 error → build=skipped（节省 preview 成本）；0 error → 调 cli preview
4. 到达 upload 阶段视为编译通过；即便上传失败（服务端校验、网络等），也不标记 build 失败

失败时的修复决策表（读完 validate-report.json 中 results[].id / message / fix 后匹配）：

V001~V021 规则详情见 references/VALIDATE_RULES.md。

判别口诀：文件内能改完 → T1~T6；需改 storage 清单或接口划分 → T7/T8；连修复方案都违规 → T9。

迭代规则：

阶段 2 — 准备 CLI agent 命令

确认 CLI 可执行：

<DEVTOOLS_APP_PATH>/Contents/MacOS/cli -h

失败则告知用户 "确认微信开发者工具已安装" 后停止，不要强行绕过。

（推荐）先 open 预热再 auto（约 10s，大项目可延长），减少 websocket 超时：

<DEVTOOLS_APP_PATH>/Contents/MacOS/cli open --project <PROJECT_PATH>
<DEVTOOLS_APP_PATH>/Contents/MacOS/cli auto \
  --project <PROJECT_PATH> --auto-port <AUTO_PORT> --trust-project

跳过此步时脚本会自动拉起 auto；遇超时或 agent compile mode is disabled 时按「不可修复类 / 工具不稳定」处理。

阶段 3 — 构建执行计划

读取 <project-path> 下 app.json 发现的每个 skill 分包的 mcp.json（validate-report.json 中的 skillDirs 字段给出了具体分包路径）：

1. 敏感接口初筛+模型判断（V019，execute 前必做）：阶段 1 静态校验的 V019 脚本初筛所有 mcp.json，把 name/description 命中敏感关键词的接口写入 cli-agent-run/destructive-manifest.json（destructive:null 待判断），报 error 阻断 build。模型逐个判断后编辑 manifest 填 destructive:true（真敏感，execute 跳过）或 false（误判，execute 放行）+ destructiveReason，重跑 validate 至 V019 pass。execute.mjs 读 manifest：true 拦截 / false 放行 / null 拦截（待判断）/ 不在 manifest 放行。生成侧阶段 2 已规定敏感接口默认不收集；V019 是兜底，catch 漏网的敏感接口名。
2. 汇总 apis[] 的 name / description / inputSchema / outputSchema / _meta.ui.componentPath。
3. 按入参依赖排序（拓扑序）：

• 无参接口（inputSchema.properties 为空或无 required）→ 最先执行
• 有参接口 → 排在其参数来源接口之后
• description 或 inputSchema 含 "需要先调用 X" 类表述时，将 X 前置

1. 维护"已知数据池"：每个接口成功后把 structuredContent 存入池中，供下游参数引用。
2. 有参接口的参数填充优先级：先查已知数据池（上游接口 structuredContent 的同义字段），池中没有才考虑用户指定或默认值——禁止在有数据池可用时直接用默认值测试有参接口。

阶段 4 — execute 与 render

术语澄清：execute 是校验阶段名（本阶段），用 CLI agent tool 调用 skills 分包的注册接口；不要与 probe 混淆——probe 是 generate 阶段 3.7 用 automator 在源项目上抓请求响应。两者工具不同（CLI agent vs automator）、对象不同（skills 分包 vs 源项目）、阶段不同（校验 vs 生成）。

execute 和 render 是两个独立可重入的命令：

• execute 调用原子接口，产出业务数据（invokeResult.structuredContent）。
• render 通过 --from-execute 把 execute 的 invokeResult.structuredContent 作为渲染数据源喂给组件；

也可以 --name + --args 独立指定。CLI 内部每次 render 会自动生成一次性 toolCallId / sessionId， 不依赖 execute 的运行时上下文。

执行灵活度：

• 可以一次 execute 所有原子接口、再统一批量 render
• 也可以"单接口 execute → render"交替进行
• render 的数据来源优先级：--args 显式指定 > --from-execute 读到的 invokeResult.structuredContent

硬约束（仅保留真正必要的）：