wxa-skills-generate

wxa-skill-generate

从小程序源码生成符合 wx.modelContext 规范的技能分包（skills/）：分析源码 → 识别业务 → 提取接口与 JSAPI → 设计原子接口 → 生成代码 → 集成配置 → 交棒校验。

职责边界

• ✅ 本 skill 做：
  • 源码分析、原子接口设计、probe脚本获取真实响应、代码生成、app.json / project.config.json 集成
  • 生成过程内的自检（必做）：产物存在性检查（scripts/check-artifacts.mjs）、字段忠实自检（§5.8）、AUTH_MIGRATION.md §6 鉴权自检、硬性约束 C 代码一致性自检
• ❌ 本 skill 不做：
  • 对生成产物的独立校验：静态规则校验（V001~V018）、真机 execute 跑通、组件渲染核对——全部由 wxa-skills-validate 负责
  • 生成过程内的自检 ≠ 对产物的校验。前者是本 skill 的组成部分，后者是交棒目标。不要因"校验交给 validate"就跳过生成阶段的自检
• 📦 交付：skills/{skill-name}/（含 mcp.json、SKILL.md、index.js、原子接口实现文件、工具模块；组件目录仅在用户明确要求生成原子组件时才有）+ 配置文件更新 + .ai-mode-skills/ 源码忠实产物

依赖

• 可读的源码目录（仅给 appid / URL / 截图 → 触发阻断）
• 开发者工具 probe 阶段需微信开发者工具 + scripts/probe.mjs（依赖的miniprogram-automator 装 skill 的 scripts/，禁止装源项目）。SOP 见 references/RUNTIME_PROBE.md（每个业务 api 默认全探，环境不可用才回退静态）。

术语约定

• 原子接口：对外暴露给小程序 AI 的可调用能力。约定路径 skills/{skill}/apis/{name}.js（validator 也兼容 tools/services/ / tools/）
• 原子组件：用于渲染原子接口返回数据的 GUI 卡片。默认不生成——仅当用户明确要求生成原子组件时才产出；否则原子接口只返回文本 + 数据 + handoff（进接力页，见 D.6）。生成时强约束路径 skills/{skill}/components/{name}/（与 mcp.json._meta.ui.componentPath 严格相等）
• 压缩代码：单行超 500 字符、变量名单字符的产物（含混淆）

参考资料索引

---

硬性约束

A. 独立分包禁止项（必须改写）

B. 直接终止生成的阻断规则

出现以下任一情况，立即终止生成并告知用户：

C. 代码一致性（不增不减 + 封装层强制复用）

本 skill 的唯一目标：将参考源码迁移/转换为目标格式，保持逻辑、结构、行为与参考源码完全一致。

迁移 = 忠实搬移，不是重写。源码中存在的每一项逻辑都必须保留到产物中，源码中不存在的不得添加。

封装层强制复用：utils/request.js 是网络请求唯一入口，所有 apis/*.js 必须通过它发请求，禁止 API 文件中直接调 wx.request 或自行拼 URL/header/query——否则鉴权参数全部丢失导致 403/空数据。

C.1 禁止添加（源码中不存在的逻辑）

• 添加参考源码中不存在的错误处理（try/catch、if 判断等）
• 添加参考源码中不存在的默认值或兜底逻辑
• 添加参考源码中不存在的输入校验
• 「优化」、「修正」、「补全」参考源码中看起来不完整的逻辑
• 任何形式的「我觉得这里应该加上...」

如果参考源码本身没有处理某种情况，输出也不应该处理。如果参考源码某处看起来像是 bug 或缺失，原样保留，不要修正。

唯一例外——响应字段类型安全：对 API 响应中的数组字段调用 .map()/.filter()/.some()/.every() 前，必须加类型保护（(x || []).method() 或 Array.isArray(x) ? x.method() : []）。分包环境下 API 响应可能因鉴权不完整等原因返回异常结构（字段为 null/对象而非数组），不加保护会抛 TypeError 崩溃。这不是"添加源码中不存在的逻辑"，而是保证源码逻辑在分包环境下不崩溃的必要防御。

C.2 禁止丢弃（源码中存在的逻辑）

核心原则：你无权判断"这个参数是否必要"。 后端校验规则对你是黑盒，源码 request 封装中每一个 header/query 都必须保留。

• 鉴权参数完整保留：见 references/AUTH_MIGRATION.md；生成后按 AUTH_MIGRATION §6 自检
• 依赖完整内联：阶段 3.2 追踪到的依赖，阶段 5 完整拷贝到分包

D. wx API 白名单（每次生成必须对照）

阶段 1 鉴权扫描、阶段 3 JSAPI 提取、阶段 5 代码生成时必须对照白名单。源码用到清单之外的 JSAPI → 按"不可迁移 JSAPI"处理。

完整清单（接口侧 / 组件侧 / 不可迁移）见 references/JSAPI_WHITELIST.md。下文 D.1 / D.2 / D.6 仅列高频条目，覆盖业务时必查 reference 完整列表，不要凭印象。

D.1 接口侧白名单

"接口侧"指通过 wx.modelContext.registerAPI() 注册的处理函数及其依赖的纯 JS 模块——常规放在 <skill>/apis/（也可放 tools/services/ / tools/，validator 会按这三个候选目录解析），引用的工具模块目录名（如 utils/ / services/ / helpers/ / 自定义名）不限。作用域以"是否在原子接口处理函数链路上"判定，不以目录名判定。

支付类、系统选择器/采集（choose* / scanCode / saveImageToPhotosAlbum）、主动打开原生页/面板（openLocation / makePhoneCall / openDocument / shareAppMessage / openSetting / openPrivacyContract）不在接口侧——见 D.2 / references/JSAPI_WHITELIST.md §2.1（动态组件）。其他场景（人脸核身、微信运动、加密、WiFi、蓝牙/BLE、WebSocket、TCP/UDP、mDNS、传感器等）查 references/JSAPI_WHITELIST.md §1 完整表。

源码用到清单之外的 JSAPI → 按 D.9 判定规则处理。阶段 1/3/5 每次对照白名单，不要凭印象。

D.2 组件侧白名单

"组件侧"指原子组件 Component({}) 内的代码及其引用的纯 JS 模块。组件目录路径强约束为 <skill>/components/<name>/index.{js,json,wxml,wxss}（与 mcp.json 中接口的 _meta.ui.componentPath 严格相等）。

完整清单见 references/JSAPI_WHITELIST.md §2（含小程序 AI getContext/getViewContext/expireAllCards/expirePreviousCards、界面 previewMedia/showToast、系统、缓存、文件、账号、位置 openLocation、设备、设置、分享、振动、隐私、地图 MapContext 全方法等）。

组件侧禁用：wx.cloud.* / 位置 / 登录 / 支付 / 其它任何接口侧业务接口。组件只能收数据（接口返回的 structuredContent / _meta）、做预览、读系统信息、读写本地缓存、读账号信息、操作 MapContext、发声明过能力的网络请求。组件与接口处于不同 JS 上下文，全局变量不共享。在 methods / tap handler / 异步回调里主动调 sendFollowUpMessage / getDimensions 时必须现取 wx.modelContext.getContext(this) / getViewContext(this)，不要通过 this._modelCtx 等缓存引用调（详见 references/COMPONENT_TEMPLATES.md）。

D.3 组件配置（原子组件按需生成 + 网络能力）

默认不生成原子组件。原子接口只返回文本 + structuredContent + handoff（进接力页，见 D.6）。仅当用户明确要求生成原子组件（GUI 卡片）时才生成：对应接口声明 _meta.ui.componentPath，并在 mcp.json 顶层 components[] 声明一条记录，path 必须与该接口 _meta.ui.componentPath 字符串完全相等（含末尾 /index，严格相等比对）。网络能力（permissions.scope.dynamic）按需声明。

{
  "components": [
    {
      "path": "components/order-list/index"
    },
    {
      "path": "components/weather-card/index",
      "permissions": { "scope.dynamic": { "desc": "声明使用场景" } }
    }
  ]
}

运行时若需要给关联页面附加 query 参数，在组件 created 里现取 viewCtx.setRelatedPage({ query })，示例代码见 references/CODE_TEMPLATES.md 第四节。该约束被静态规则强制校验。

D.4 组件过期态声明（按需，非强制）

默认不生成。仅当源业务上存在"卡片到某时刻作废、不应再被点"语义（成交、关店、活动结束、超时）时，在 components[] 记录上加 expirable: true + 业务化 expiredText。声明与调用必须配对。

触发 API 二选一（不要同时调）、精细过滤（componentPaths / match: 'latest'）、代码示例详见 references/COMPONENT_TEMPLATES.md "卡片过期"节。

D.5 半屏页面（按需，非强制，默认不生成）

仅当源业务确有"详情 / 用户补充信息"语义时挂上。入口仅在原子组件 methods 内（getViewContext(this).openDetailPage，原子接口无 this 不可调）。半屏内上行 sendFollowUpMessage、禁用清单（跳出类 / 页面路由 / 聊天工具 / 广告 / 导航组件等）、场景值、关闭按钮适配详见 references/HALF_SCREEN.md。

D.6 handoff 接力页（进小程序的主要方式）

进小程序统一走 handoff。默认流程：原子接口返回文本 + 小程序卡片，用户点卡片后由平台 handoff 进入小程序内的接力业务页继续操作。

何时必须配：若某原子接口执行完会停下等用户确认（展示小程序卡片、等用户点击进小程序），必须为它配置 pagePath，否则用户无法进入业务页。纯数据、无停顿接续的接口可不配。

四项适配（详见 references/CODE_TEMPLATES.md "handoff 接力页" 节）：

1. mcp.json：在该接口 apis[]._meta.ui 加 pagePath（接力页 path，不含 query；与 componentPath 同级，componentPath 仅在生成组件时才有）。
2. 原子接口返回值：顶层（与 content / structuredContent 同级）增加 handoff，兼容两种形态：
   • 对象（立即模式，更快）：handoff: { query, payload?, card? }——模型无需筛选数据时直接返回对象，平台即时生成 handoff，链路更短、更快。
   • 函数（延迟模式）：handoff: ({ result }) => ({ query, payload?, card? })——需要用模型修改后的 result 时返回函数，入参对象的 result 即模型修改后的完整 result。 字段：query 为对象（页面 query 键值对，如 { drugId }）；payload 可选（接力页首屏加速数据）；card 可选（卡片展示信息，如 { title }）。
3. app.js：onLaunch 内注册 wx.onAgentHandoff(cb)（须早于 handoff 触发的 onBeforeAppRoute），把 { path, query, payload } 按 pageId 暂存。
4. 接力业务页：onLoad(query) 中 query 为对象（键值对，同 handoff.query）；若 wx.onAgentHandoff 投递了 payload 则先 setData 加速首屏。

平台代做（无需自己实现路由）：按 pagePath 打开目标页 → 把 handoff.query 原样注入 onLoad(query) → 通过 wx.onAgentHandoff 回调投递 path / query / payload。

禁用：wx.openAgent / wx.navigateBackAgent 当前基础库侧未打通，调用会失败——接力页内不要依赖"打开 Agent / 返回 Agent 对话"，后续流程由业务页自行完成。

D.7 不可迁移 JSAPI（接口与组件均禁用，高频示例；完整清单见 references/JSAPI_WHITELIST.md §3）

其它老接口、Taro 特有不可迁移项（Hook、Pinia/Vuex、Vue setup 等）见 references/JSAPI_WHITELIST.md §3。

D.8 button 的 open-type 改写

组件内 button 禁用 open-type（share / getPhoneNumber / getRealtimePhoneNumber）→ 去掉 open-type，改 bindtap，在 tap handler 内调对应白名单 JSAPI（wx.shareAppMessage / wx.getPhoneNumber / wx.getRealtimePhoneNumber）。

D.9 判定规则

1. 能力仅能通过不可迁移 JSAPI 实现（如"扫码核验"且源码无网络 API 替代）→ 触发阻断规则 B
2. 能力核心逻辑可用网络请求实现 → 生成纯网络请求版本，丢掉不可迁移的 JSAPI 调用
3. 老接口有白名单内新接口替代（chooseImage → chooseMedia、previewImage → previewMedia）→ 自动替换

E. 原子组件约束

• 仅支持 tap 事件
• 支持的内置组件：view（含 hover-class）/ text（不含 user-select）/ image（仅网络地址）/ map / button（不含 open-type）/ canvas / scroll-view（仅横向滚动 scroll-x，禁纵向 scroll-y）
• 不支持的内置组件：swiper / swiper-item / input / textarea / picker / picker-view / checkbox / radio / form / label / slider / switch / editor / rich-text / icon / progress / navigator / web-view / movable-area / movable-view / root-portal / match-media 等
• button 用 open-type → 按 D.8 改写为 bindtap + 白名单 JSAPI
• 渲染容器：宽度随屏幕，宽高比 4:1（最小高） ~ 1:1（最大高），超出裁剪、不支持纵向滚动（横向超长内容用 <scroll-view scroll-x="true"> 包裹）
• 不支持打开小程序接口；不可声明为虚拟组件；组件与接口处于不同 JS 上下文，全局变量不共享
• 每个可交互元素必须绑 bindtap，tap handler 上行 content 数组（① 单 text 或 ② text + api/call 组合，推荐 ②）。详见阶段 5.3 + references/COMPONENT_TEMPLATES.md "上行消息"节
• 数据通道禁止 properties / observer / dataSource：必须通过 NotificationType.Result 取 structuredContent（详见 references/COMPONENT_TEMPLATES.md 与阶段 5.4）
• WXML 表达式限制：{{ }} 中不支持数组下标（如 [0]）、函数调用（如 .slice()）、模板字符串等复杂 JS。需要计算的字段一律在 index.js 归一化阶段预处理好再 setData

---

执行清单（复制后勾选）

产物检查脚本：每个阶段完成后运行 node scripts/check-artifacts.mjs <project-path> --stage <N> 做确定性检查——只验文件是否存在 + JSON 能解析 + 目录结构正确，不校验文件内容。有缺失 → 脚本退出码 1 并列出缺失项 + 该回哪个阶段补。禁止跳过此检查直接进入下一阶段。不传 --stage 时检查全部已应完成的阶段。

阶段 0 — 业务需求澄清（强制前置）
- [ ] 判定用户场景是否明确（两项判定）
- [ ] 不明确 → 最小扫描 + 引导澄清 + 等待确认
- [ ] 确认是否生成原子组件（用户未明确要求 → 默认不生成，只做原子接口 + handoff）
- [ ] 产出"目标业务场景 + 期望原子能力"清单

阶段 1 — 项目扫描
- [ ] **首检 `lazyCodeLoading`**（缺则阻断 B）
- [ ] 提取 app.json / app.js / project.config.json 关键字段
- [ ] 产出云开发 / 插件 / storage 初始化清单
- [ ] 产出 **auth-spec** 两份产物 + 鉴权核对 PASS（见 `AUTH_MIGRATION.md` §2/§3；大项目走 `SUBAGENT_PROTOCOL.md` §2.1/§2.2）
- [ ] 大项目：产出 `capability-index.json`（见 `SUBAGENT_PROTOCOL.md` §一）
- [ ] `node scripts/check-artifacts.mjs <project-path> --stage 1`

阶段 2 — 业务功能识别（用户已明确时跳过）
- [ ] 产出结构化功能清单 JSON
- [ ] 用户二次确认

阶段 3 — 接口与 JSAPI 提取 + 可行性校验
- [ ] 逐能力产 `interface-spec.<cap>.md`（大项目 `SUBAGENT_PROTOCOL.md` §2.3 subagent；小项目见阶段 3.2）
- [ ] 产 `probe/plan.json` → 执行 probe（每次落盘 `probe/<run-id>.json`）→ 合并 **一份** `merged-result.json`（见 `RUNTIME_PROBE.md`；大项目 plan 由 `SUBAGENT_PROTOCOL.md` §2.4 subagent）
- [ ] `node scripts/check-artifacts.mjs <project-path> --stage 3`

阶段 4 — 原子接口设计
- [ ] 原子接口清单（含 name / description / inputSchema / outputSchema；进小程序的接口配 _meta.ui.pagePath + 返回 handoff；_meta.ui.componentPath 仅当用户要求生成原子组件时才有）
- [ ] API 依赖图
- [ ] storage key 清单

阶段 5 — 代码生成
- [ ] 进小程序的接口已配 _meta.ui.pagePath + 返回值顶层 handoff（见 D.6）
- [ ] `utils/request.js` 按 `AUTH_MIGRATION.md` §5/§6 生成并自检
- [ ] 源码忠实度：interface-spec 符合 `SUBAGENT_PROTOCOL.md` 源码忠实铁律；`ensureXxx`/`await` 见 `AUTH_MIGRATION.md` §4/§6
- [ ] 字段忠实自检（每写完一个 apis/<name>.js 立即做，见 5.8）：其 structuredContent 字段集与 merged-result 该 api 的 probe 真实响应一致
- [ ] （仅当用户要求生成原子组件时）每个原子组件符合 `ATOMIC_COMPONENT_DESIGN.md` 并走完 `STYLE_MIGRATION.md` 7 步；可交互元素绑 `bindtap`，tap handler 优先上行 `content` 组合（text 简短中文、`name` 在 mcp.json 中存在、`arguments` 对齐 inputSchema），无法映射时退回单 `text`
- [ ] `skills/{skill-name}/` 目录完整（mcp.json / SKILL.md / index.js / apis/* / utils/*；仅生成组件时含 components/*）
- [ ] SKILL.md 按 `CODE_TEMPLATES.md` 第五节 5 节结构写完（路由说明，非接口手册）
- [ ] `node scripts/check-artifacts.mjs <project-path> --stage 5`

阶段 6 — 配置集成
- [ ] app.json 加 agent.skills（每项含 `{ name, description, path }`）+ subPackages
- [ ] project.config.json 的 packOptions.include 加 skills
- [ ] `node scripts/check-artifacts.mjs <project-path> --stage 6`

收尾 — 交棒给 wxa-skills-validate
- [ ] 明确告知用户："请使用 wxa-skills-validate 做校验"
- [ ] 提示 skills 路径与 project-path

---

跨阶段跳转规则

核心原则：

1. 业务场景不明确时，必须先澄清后生成，严禁跳过阶段 0
2. 每个阶段必须完整产出"产出物清单"中的全部项才能跳转到下一阶段

增量与重入

工作区已存在 skills/ 产物时：

重入时已生成且未触及的文件保持不变，只更新受影响的文件。

---

阶段 0 — 业务需求澄清（强制前置）

契约：

判定规则（必须同时满足 2 项才算"明确"）：

任一不满足 → 进入下方澄清流程。

不明确时的引导流程

1. 最小扫描：只读 app.json 的 tabBar.list、pages（一级路径）、subPackages.root。禁止读 JS/WXML/WXSS，禁止做依赖分析。
2. 归纳候选：基于路径关键词（见 references/ANALYSIS_PATTERNS.md 页面功能识别表）归纳 3~6 个候选场景。
3. 向用户提问（一次问完，别反复打断）：
   • 希望把哪些业务场景做成小程序 AI 的 SKILL？
   • 每个场景希望暴露给小程序 AI 的原子能力大致是什么？
   • 是否涉及登录态、支付、位置、云开发等敏感能力？
   • 是否需要生成原子组件（GUI 卡片）？默认不生成——只做原子接口 + handoff（点小程序卡片进接力页）；仅当你明确需要对话内卡片式 GUI 时才生成。用户未提及即按"不生成"处理。
4. 等用户回复后才能进入阶段 1。严禁在用户确认前扫描源码或生成代码。

澄清输出清单模板：

目标业务场景：
  - 场景 A：<名称> → 期望原子能力：<能力 1>、<能力 2>
  - 场景 B：<名称> → 期望原子能力：<能力 3>

技术约束：
  - 是否涉及支付/登录/位置：是/否
  - 是否使用云开发：待阶段 1 扫描确认
  - 是否生成原子组件（GUI 卡片）：是/否（用户未明确 → 默认否，只生成原子接口 + handoff）

---

阶段 1 — 项目扫描

项目结构速览 + 读取策略分流

读 app.json 映射阶段 0 目标到页面/分包。按规模分流：

契约：

1.1 配置扫描

读 app.json / app.js / project.config.json，提取 pages / subPackages / tabBar / 已有 agent / appid / packOptions；扫云开发（wx.cloud 调用 / cloudfunctions/ 目录）与云环境 ID（wx.cloud.init({ env })）。lazyCodeLoading 必检：缺 "lazyCodeLoading": "requiredComponents" → 阻断规则 B（不要"代为补全"）。云开发项目同时扫 cloudfunctionRoot/<fn>/index.js 的入参/返回结构。

1.2 鉴权逻辑扫描（必做）

按 references/AUTH_MIGRATION.md §2/§3 落盘 <源项目>/.ai-mode-skills/auth-spec.md + auth-spec.snippets.txt（事实结构化 + 代码 verbatim 拷贝，禁止把签名写成步骤数组）。

• 小项目：主 agent 读 app.js/request 封装/登录文件，自行填产物
• 任意规模：鉴权核对 subagent 回比源码 PASS 后才进阶段 3（大项目鉴权提取见 SUBAGENT_PROTOCOL.md §2.1/§2.2）

auth-spec 经核对 PASS 后才是"可信事实"。后续阶段 3 / 5.6 直接引用，不重读同一鉴权函数。

1.3 主包 storage 初始化扫描（必做）

扫 app.js 与主包 .js 中的 wx.{set,get,clear}Storage*，提取 key / defaultValue / initCondition / sourceFile。迁移：① setStorageSync 初始化值 → 分包 ensureStorageInit() 重建；② getApp().globalData 运行时缓存 → 模块级变量或按需写 storage；③ onLaunch 异步获取后写 storage → 分包首次调用时自行重发请求并缓存。形成 storage 初始化清单（与阶段 4 内部"接口间数据传递的 storage key 清单"不是同一张表）。

1.4 压缩代码处理

识别：单行 >500 字符 / 单双字符变量名 / 缺注释空行。处理顺序：① 优先问用户要未压缩源码；② 否则尝试 prettier 格式化后再提取；③ 格式化后关键字段仍全是 a.b.c.d → 阻断规则 B。禁止盲目猜变量名——猜出来的代码会在 validator 大量失败。

1.5 插件检测

扫 app.json 的 plugins 字段、页面/组件 JSON 的 usingComponents 中的 plugin:// 引用。目标能力依赖插件 → 阻断规则 B。

---

阶段 2 — 业务功能识别（用户已明确时跳过）

契约：

动作：

1. 针对阶段 0 选定的候选场景对应页面，按 references/ANALYSIS_PATTERNS.md 的模式分析页面用途、交互事件、数据流向
2. 从用户视角识别功能点（每个功能 = 一个原子接口）
3. 分析数据依赖（A 的返回值被 B 使用）

产出物 JSON（字段统一 camelCase）：

[
  {
    "functionName": "检索商品",
    "pages": ["pages/items/list", "pages/search/index"],
    "sourceApis": ["GET /api/items/search"],
    "suggestedAtomicInterfaces": ["searchItems"],
    "needsComponent": true
  }
]

必须将清单发给用户二次确认才能进入阶段 3。

---

阶段 3 — 接口与 JSAPI 提取 + 可行性校验

契约：

详细匹配模式见 references/ANALYSIS_PATTERNS.md。

3.1 提取范围：仅扫用户已确认能力对应的页面/模块，搜索网络调用（wx.request / wx.cloud.{callFunction,database,callContainer}）+ 白名单内 JSAPI（高频列表见"硬性约束 D"，完整清单见 references/JSAPI_WHITELIST.md）。

3.2 依赖追踪（读真实源码，逐字复刻）：

逐能力先定位承载它的真实交互入口——源码中触发该能力的那段代码（页面生命周期 onLoad/onShow、按钮 / 输入框等事件 handler，或对应业务函数）。该入口实际调用的接口，就是这个能力的唯一标准接口；连同它传入的分支参数（类型 / 模式标志位等）一起逐字复刻。能力与接口是一一对应关系，不要在多个名字相近的接口间"挑一个更好实现的"——一切以源码真实入口为准。

3.3 鉴权依赖确认：结合 auth-spec，对每个目标接口确认 ① 是否需要登录态 ② token 来源（storage 直读 / 需先登录）③ 登录方式（wx.login + 换 token / 其他）。interface-spec 只填 authRefs 引用 auth-spec（requiresLogin / signing / dynamicValues / 通用参数 inherit），不重新定义鉴权事实，避免与 auth-spec 漂移。详见 AUTH_MIGRATION.md §2/§5。

3.4 签名 / 可请求性：若接口请求含签名 / 反爬字段（sign / timestamp+nonce / 指纹等），记入 auth-spec §2.6（id / scope / 触发 / 密钥来源 / 输出字段 / 依赖模块 / 原文片段指针），函数体 verbatim 入 auth-spec.snippets.txt。不得因「更好实现」换接口或简化签名——签名一错全废。可请求性判定：依赖验证码/短信等运行时人机交互 → replicable: false + blockers → 阻断或人工接入。

3.5 插件依赖：依赖链路含 requirePlugin / require('../plugin/') / plugin:// → 阻断规则 B。

3.6 可行性三级校验：

中置信询问模板：

以下原子能力在源码中存在多个并列的真实入口，请确认对应哪一个：

能力：<能力名>
入口 1：<页面/事件> 调用 <接口/云函数> — 参数 <x>、返回 <y>（来自 pages/xxx.js 第 N 行）
入口 2：<页面/事件> 调用 <接口/云函数> — 参数 <x>、返回 <y>（来自 pages/yyy.js 第 M 行）

请按你实际想暴露的小程序功能确认对应哪个入口（接口由能力入口唯一确定，不以实现难易为取舍）。

3.7 运行时探测（probe）

🔴 生成阶段必做、非 validate 阶段的功能；跑源项目普通开发者工具即可（与agent无关）。完整 SOP 见 references/RUNTIME_PROBE.md。

注意，只有使用了 automator，捕获真实的请求响应，才能在生成的时候使用正确的数据结构，禁止猜测接口的返回字段。

要点：

1. 选出的每个业务 api_name 各一条 plan 条目 → 批量 probe（每次执行落盘 probe/<run-id>.json，重试可多个）→ 读成功 run 回填 interface-spec.response → 合并写一份 merged-result.json（阶段 4 只读此文件）
2. 大项目 plan 由 SUBAGENT_PROTOCOL.md §2.4 产出；小项目主 agent 从 interface-spec 写 plan
3. 执行顺序：cli open --project <源项目> → cli auto --auto-port 9420 --project <源项目> → 确认 9420 OPEN → probe.mjs --mode connect（省略 --output 时自动用 runId 文件名）
4. 连接失败：≥3 轮重试后才可标 verified:false / [ai-mode:UNVERIFIED] 并交棒声明；单次失败即回退属违规；禁止手写 probe/*.json 伪造探测结果
5. apis/<name>.js 顶部须 [ai-mode:static] + 成功时 [ai-mode:probe] 注释溯源

---

阶段 4 — 原子接口设计

契约：

4.1 技能划分：同业务域（商品/订单/地址）原子接口聚合到同一 skill；共享 storage 上下文的接口必须在同一 skill 内；每 skill 推荐 3-8 个原子接口（更多则按子业务拆分）。

4.2 接口字段：每条接口含 name（驼峰、全局唯一）/ description（含内部串联操作，帮助小程序 AI 决策）/ inputSchema（仅小程序 AI 需从用户获取的参数；无参用 {"type":"object","properties":{}}）/ outputSchema（对应 structuredContent）/ _meta.ui.pagePath（按需，接力页 path、不含 query；"执行完停下等用户确认"类接口需配，配合返回值 handoff，详见 D.6）/ _meta.ui.componentPath（仅当用户明确要求生成原子组件时才声明，格式 components/xxx/index；声明则组件目录必须 4 文件齐全）。

多模态入参：当接口需要用户上传图片（如 P 图、图像识别）时，对应 inputSchema.properties.<field> 加 "format": "image"，类型为 string（运行时填本地图片路径）。小程序 AI 输入框会据此识别为多模态字段、引导用户上传图片。

4.3 进小程序方式（默认 handoff，不默认生成组件）：默认不生成原子组件——需接续操作/查看详情的接口，配 _meta.ui.pagePath + 返回 handoff（见 D.6），用户点小程序卡片进接力页。仅当用户明确要求生成原子组件（GUI 卡片）时，才按返回值类型对照组件模板（详见 references/COMPONENT_TEMPLATES.md）：列表/卡片项 → 通用列表；详情/单对象 → 详情卡片；购物车/带数量总价 → 购物车；下单成功/支付结果/操作确认 → 状态结果。

4.4 产出物示例（默认形态：无组件，配 handoff）：

[{
  "skill": "business",
  "name": "searchItems",
  "title": "检索商品",
  "description": "根据关键词检索商品，返回商品列表",
  "inputSchema": { "type": "object", "properties": {} },
  "outputSchema": { "type": "object", "properties": { "items": { "type": "array" } } },
  "_meta": { "ui": { "pagePath": "/pages/goods/list" } }
}]

用户明确要求生成原子组件时，才在 _meta.ui 追加 componentPath: "components/item-list/index" 并生成组件目录。

API 依赖图（仅在通过 storage 传上下文时必备）：

searchProducts ──(storage: skills_shopping_lastSearchResult)──▶ addToCart
              └─(storage: skills_shopping_lastSearchResult)──▶ getProductDetail

storage key 命名统一 skills_{skillName}_{dataName}，列表含 key / 写入方 / 读取方 / 数据结构。

---

阶段 5 — 代码生成

契约：

代码模板见 references/CODE_TEMPLATES.md、组件模板见 references/COMPONENT_TEMPLATES.md、设计规范见 references/ATOMIC_COMPONENT_DESIGN.md（最高优先级）、CSS 实现规范见 references/ATOMIC_COMPONENT_CSS.md。

5.1–5.4 组件四个强制前置（仅当用户明确要求生成原子组件时适用；写任何组件 WXML/WXSS/JS 前必须按序走完）

默认不生成原子组件 → 本节整节跳过，只生成原子接口 + handoff。仅当用户明确要求生成 GUI 卡片时才执行。

一旦要生成组件，进入阶段 5 前模型必须完整阅读 references/COMPONENT_TEMPLATES.md 和 references/ATOMIC_COMPONENT_DESIGN.md，不得跳过。违反此条是导致"接口请求成功但组件不渲染"的常见根因。

tap handler 优先形态 2（text + api/call 组合）：

// 使用点必须现取 ctx；不要用 this._modelCtx 之类的缓存引用
wx.modelContext.getContext(this).sendFollowUpMessage({
  content: [
    { type: 'text', text: '<用户视角的简短中文，例如：选择拿铁>' },
    { type: 'api/call', data: { name: '<mcp.json 已声明的 api name>', arguments: { /* 对齐该接口 inputSchema */ } } },
  ],
})

只有当点击动作无法映射到原子接口时才退回形态 1（单 text）。每次上行 api/call 前打一行 [ai-mode] {componentName} send api/call name=... args=... console.info。禁止：组件内直调业务接口、单独发 api/call 不带前导 text、arguments 用占位值、name 不在 mcp.json 中、只展示不响应的"死"按钮、用 this._modelCtx.sendFollowUpMessage(...) 缓存引用调方法。

5.5 目录结构

{项目根目录}/
├── app.json                              # 含 agent.skills 注册
└── skills/                               # 独立分包（多 skill 共用）
    ├── _shared/                          # 可选：≥2 个 skill 共用的工具函数才放这里
    └── {skill-name}/
        ├── mcp.json                      # 原子接口 Schema 定义
        ├── SKILL.md                      # skill 路由说明
        ├── index.js                      # 接口注册入口
        ├── apis/                         # 原子接口实现（推荐目录；validator 兼容 tools/services/、tools/）
        ├── utils/                        # 工具模块（目录名不强制，常见 utils/services/helpers）
        └── components/{component-name}/  # index.js/json/wxml/wxss（路径强约束，与 mcp.json _meta.ui.componentPath 严格相等）

目录分层：跨 skill 禁止 require('../../{otherSkill}/...')；多 skill 复用走 skills/_shared/（不在 mcp.json 注册、不调 registerAPI）。

5.6 鉴权代码生成

按 AUTH_MIGRATION.md §5/§6 生成 utils/request.js + index.js；模板见 CODE_TEMPLATES.md。生成后过 AUTH_MIGRATION §6 自检；interface-spec 忠实度见 SUBAGENT_PROTOCOL.md 源码忠实铁律。

5.7 mcp.json + 技能自身 SKILL.md + 返回值 + 日志

• mcp.json：顶层 { "apis": [...] }，每项必含 name / description / inputSchema / outputSchema；进小程序的接口按需加 _meta.ui.pagePath（配合返回值 handoff）；_meta.ui.componentPath 与 components[] 仅在用户明确要求生成原子组件时才有（components[] 声明组件网络能力，详见 D.3）。完整字段示例见 references/CODE_TEMPLATES.md 第四节
• 技能自身 SKILL.md（文件名严格全大写）定位"路由说明"，只允许 5 节按序：能力域定位 → 触发场景（用户原话 few-shot）→ 不适用范围 → 前置条件 → 使用顺序。通篇禁止：驼峰 apiName / inputSchema / outputSchema / 参数表 / 返回值表 / componentPath / storage key / 接口依赖图 / 安装 CLI 运维。完整模板见 references/CODE_TEMPLATES.md 第五节
• 返回值格式：{ isError?, content: [{type:'text', text}], structuredContent?, _meta?, handoff? }——content 给 LLM 文本，structuredContent 对应 outputSchema，_meta 对 LLM 不可见可传 UI 组件；handoff（进小程序按需，顶层与上述字段同级）为 { query: string, payload? }，承接卡片点击进接力页，详见 D.6
• 日志规范：原子接口必打 入口 / 入参 / 请求前后 / 出口 / catch；原子组件必打 created/attached / 收到 Result / setData / NotificationType.Overflow（必监听，用于校验裁剪）。统一前缀 [ai-mode]。日志不打够等于没日志——真机失败看不到关键节点 → 回阶段 5 补齐重跑

5.8 字段忠实自检

每写完一个 apis/<name>.js，就地拿它的 structuredContent 字段集与 merged-result.json 中该 api 的 probe 真实响应字段集比对，防止臆造字段。生成一个查一个，不要攒到收尾。如果没有probe产物，重新执行probe

• 字段一致 → 通过，继续下一个
• 缺少/多出字段 → 代码臆造或未忠实 probe，以 probe 为准修正 structuredContent 与 mcp.json outputSchema
• 该 api 标 verified:false / pendingProbe（probe 未成功）→ 跳过比对，但交棒时须声明未验证

阶段 6 — 配置集成

契约：

配置格式见 references/CODE_TEMPLATES.md 第六节。关键要点：

• agent.skills[].path 指向 skills/{skill-name} 目录
• subPackages 中 skills 整体作为 independent: true 的独立分包；多 skill 共用同一个分包——新增 skill 只在 agent.skills[] 里追加，不要为每个 skill 加一条 subPackages 条目
• project.config.json 的 packOptions.include 需含 { "type": "folder", "value": "skills" }
• handoff（按需）：若有接口配了 _meta.ui.pagePath 并返回 handoff，在主包 app.js 的 onLaunch 内注册 wx.onAgentHandoff（详见 D.6 与 references/CODE_TEMPLATES.md "handoff 接力页" 节）

---

收尾 — 交棒给 wxa-skills-validate（强制）

阶段 6 完成后，必须在回复中明确告知用户：

代码生成与配置集成已完成。下一步请使用 `wxa-skills-validate` skill 对产物进行校验与真机验证：

- skills 路径：<abs-path>/skills
- project-path：<abs-path>（含 project.config.json 的 appid 为 <appid>）

wxa-skills-validate 会依次执行：静态校验 → cli agent tool execute → cli agent render → 交付文档。

项目校验必须用 subagent 隔离：当本项目按 SUBAGENT_PROTOCOL.md 走 subagent 协议时，校验也必须派 subagent 执行（SUBAGENT_PROTOCOL.md §2.6），禁止在主 agent 上下文中直接运行 validate。

交棒步骤不可省略。仅输出代码不算完成，必须在对话中显式提示用户切换到校验 skill。

⚠️ 交棒时若有 verified:false / [ai-mode:UNVERIFIED] 接口，须逐条声明（见 RUNTIME_PROBE.md）。