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

wxa-skill-generate

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

职责边界

• ✅ 本 skill 做：源码分析、原子接口设计、按需使用 automator 获取真实响应、代码生成、app.json / project.config.json 集成
• 生成过程内的自检：字段来源自检（§5.8）、AUTH_MIGRATION.md §6 鉴权自检、硬性约束 C 代码一致性自检
• ❌ 本 skill 不做：对生成产物的独立校验（静态规则校验 V001~V021、真机 execute 跑通、组件渲染核对）——全部由 wxa-skills-validate 负责。生成阶段的自检是本 skill 的组成部分，不因"校验交给 validate"而跳过
• 📦 交付：skills/{skill-name}/（含 mcp.json、SKILL.md、index.js、原子接口实现文件、工具模块；组件目录仅生成组件时才有，见 D.3）+ 配置文件更新 + .ai-mode-skills/ 分析产物两份

分析产物（<源项目>/.ai-mode-skills/）

分析结果落盘两份，按读取频率拆分，避免单文件全量读入：

probe/plan.json（probe.mjs 的输入）与 probe/<run-id>.json（脚本写盘）由subagent脚本管理，不属于分析产物。

依赖

• 可读的源码目录（仅给 appid / URL / 截图 → 触发阻断）
• 开发者工具：微信开发者工具 + scripts/probe.mjs（miniprogram-automator 装 skill 的 scripts/，不装源项目）。只在阶段 3.7 的两种触发条件命中时才用，见 3.7 与 references/RUNTIME_PROBE.md

术语约定

• 原子接口：对外暴露给小程序 AI 的可调用能力。约定路径 skills/{skill}/apis/{name}.js（validator 也兼容 tools/services/ / tools/）
• 原子组件：用于渲染原子接口返回数据的 GUI 卡片（是否生成、componentPath 规则见 D.3）。
• 压缩代码：单行超 500 字符、变量名单字符的产物（含混淆）
• probe：本 skill 阶段 3.7 的运行时探测。用 automator（miniprogram-automator npm 包）连接开发者工具 WS 端口（9420），在源项目上触发请求、捕获真实响应，产物落盘 .ai-mode-skills/probe/。

参考资料索引

硬性约束

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

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

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

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

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

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

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

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

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

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

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

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

• 鉴权参数完整保留：见 references/AUTH_MIGRATION.md；生成后按 AUTH_MIGRATION §6 自检
• 依赖完整内联：阶段 3.2 追踪到的依赖，阶段 5 完整拷贝到分包
• 响应字段类型安全：对 API 响应中的数组字段进行处理前，加空保护（(x || []).method() 或 Array.isArray(x) ? x.method() : []）。

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）、界面反馈（showToast / hideToast）不在接口侧——见 D.2 / references/JSAPI_WHITELIST.md §2（组件侧）。其他场景（人脸核身、微信运动、加密、WiFi、蓝牙/BLE、WebSocket、TCP/UDP、mDNS、传感器等）查 `references/JSAPI_WHITELIST.md §1` 完整表。

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

D.2 组件侧白名单

"组件侧"指原子组件 Component({}) 内的代码及其引用的纯 JS 模块。_meta.ui.componentPath 是相对 skill 目录的组件基路径，对应 <componentPath>.{js,json,wxml,wxss}；默认模板使用 components/<name>/index。

完整清单见 `references/JSAPI_WHITELIST.md §2`（含小程序 AI getContext/getViewContext/setRelatedPage/updateModelContext/expireAllCards/expirePreviousCards、界面 previewMedia/showToast/hideToast、系统、缓存、文件、账号、位置 openLocation、设备、设置、分享、振动、隐私、地图 MapContext 全方法等）。组件侧禁用规则（wx.cloud.* 及白名单外 JSAPI 不可用、组件与接口全局变量不共享、上下文按使用点获取或 this._viewCtx 缓存）同见该文 §2 末段。

同步交互状态给模型：用户在卡片上改了选择（选规格、选时段等）时，在 tap handler 内调 wx.modelContext.getViewContext(this).updateModelContext({ content: [{ type: 'text', text: '用户选择了大杯' }] })，让模型感知最新状态。必须在用户的 tap 点击事件回调中调用，不可在异步逻辑或定时器中调用，短时间重复调用会被节流拒绝，content 须为非空数组且 text 非空。

D.3 组件配置（原子组件按需生成 + 关联页 + 实时动态能力）

默认不生成原子组件。原子接口只返回文本 + structuredContent + handoff（进接力页，见 D.6）。仅当用户明确要求生成原子组件（GUI 卡片）时才生成：对应接口声明相对 skill 目录的 _meta.ui.componentPath，并在 mcp.json 顶层 components[] 声明一条记录，`path` 必须与该接口 `_meta.ui.componentPath` 字符串完全相等。

`relatedPage` 必填：卡片标题栏右上角的"进入小程序"入口靠它配置，缺失会导致 cli preview / 上传时被平台强校验拦下。取值必须以 / 开头（绝对路径），去掉前导 / 后是项目 app.json 中真实存在的页面（主包 pages[] 或分包 root + page）；业务上没有对应页面时兜底填首页 /<app.json.pages[0]>。通过该入口进小程序的场景值为 1442 / 1443。

permissions.scope.dynamic 仅在组件需要 wx.login / wx.checkSession / wx.request / 定时器时按需声明（规则见 references/JSAPI_WHITELIST.md §2.1）。

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

运行时给关联页附加 query 参数：可在组件 created 中保存 this._viewCtx = wx.modelContext.getViewContext(this)，收到 NotificationType.Result 或状态变化后调 this._viewCtx.setRelatedPage({ query })；组件可能关联多个页面时再额外传 path。也可按使用点获取 viewCtx 后调用。示例代码见 references/COMPONENT_TEMPLATES.md "关联小程序页面"节。该约束由静态规则校验（V015）。

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

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

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

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

本节说的半屏页面是另开一个小程序页面（openDetailPage），运行环境等同普通小程序页面；与原子组件自身展开成半屏的 collapsible-view 不是一回事，选用辨析见 references/HALF_SCREEN.md §4。

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

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

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

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

四项适配（mcp.json 配 _meta.ui.pagePath → 返回值顶层 handoff（对象立即 / 函数延迟两形态，字段 query / payload / path）→ 主包 app.js 注册 wx.onAgentHandoff → 接力页 onLoad(query) 消费）的字段规格与完整代码，见 references/CODE_TEMPLATES.md "handoff 接力页"节。

与文本混排链接的分工：handoff 是把当前对话流程整段接力进页面；只想在回复文字中间给一个可点的详情入口时用 outputSchema 的 format: "page-link"（见阶段 4.2），不要返回 handoff。两者可同时存在，互不替代。

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

D.7 不可迁移 JSAPI（接口与组件均禁用）

完整清单与替代策略见 `references/JSAPI_WHITELIST.md` §3（含 Taro 特有不可迁移项）。高频项：wx.showModal / showLoading 系、wx.navigateTo 系路由、chooseImage / chooseVideo / previewImage 老接口、setClipboardData / getClipboardData、getUserInfo / getUserProfile、createSelectorQuery / createCanvasContext、pageScrollTo / createAnimation、普通原子组件内 setTimeout / setInterval。

注意区分"两侧都不可用"与"只是换了一侧"：showToast / chooseMedia / scanCode / makePhoneCall 这类不是全禁，只是从接口侧移到了组件侧；一侧可用的查 D.1 / D.2 与 references/JSAPI_WHITELIST.md。

D.8 button 的 open-type 改写

组件内 button 禁用 open-type（share / getPhoneNumber / getRealtimePhoneNumber）→ 去掉 open-type，改 bindtap，在 tap handler 内调对应白名单 JSAPI（wx.shareAppMessage；手机号相关须放在原子接口侧完成，见 D.1 / D.2）。

D.9 判定规则

按 references/JSAPI_WHITELIST.md §4 三条执行（仅能不可迁移 JSAPI 实现且无替代 → 阻断 B；核心逻辑可用网络请求实现 → 纯网络请求版本；老接口有白名单内替代 → 自动替换）。自动替换时同时确认替代接口所在的一侧（多数只在组件侧可用）。

E. 原子组件约束

事件 / 内置组件白名单 / 渲染容器 / 实时动态能力 / 动画限制等完整约束，见 references/COMPONENT_TEMPLATES.md "重要限制"节；CSS 属性支持范围见 references/ATOMIC_COMPONENT_CSS.md。另有两条限制：

• 数据通道禁止 `properties` / `observer` / `dataSource`：必须通过 NotificationType.Result 取 structuredContent（详见 references/COMPONENT_TEMPLATES.md 与阶段 5.4）
• WXML 表达式限制：{{ }} 中不支持数组下标（如 [0]）、函数调用（如 .slice()）、模板字符串等复杂 JS。需要计算的字段一律在 index.js 归一化阶段预处理好再 setData

执行清单（复制后勾选）

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