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）
- [ ] 产出"目标业务场景 + 期望原子能力"清单

阶段 1 — 项目扫描
- [ ] 首检 `lazyCodeLoading`（缺则阻断 B）
- [ ] 提取 app.json / app.js / project.config.json 关键字段
- [ ] 产出云开发 / 插件 / storage 初始化清单
- [ ] 落盘 `analysis-auth.md`（鉴权事实 + 逐字代码片段，见 `AUTH_MIGRATION.md` §2/§3；大项目派 subagent ① 鉴权分析，三类中最先）
- [ ] 大项目：先产能力索引坐标（见 1.0）

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

阶段 3 — 接口与 JSAPI 提取 + 可行性校验
- [ ] 逐接口分析（小项目直读 / 大项目派 **subagent ② api 分析**，须在 ① 完成后，见 3.2），追加到 `analysis-apis.md`
- [ ] 按需 probe（两个触发条件，见 3.7）：派 **subagent ③**（须在 ①② 完成后），跑了的回填真实响应到 `analysis-apis.md`

阶段 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 自检清单逐条过
- [ ] 每写完一个 `apis/<name>.js` 做字段来源自检（见 5.8）
- [ ] （生成组件时）组件走 5.1–5.4 前置与模板；`components[]` 每条都填了 `relatedPage`
- [ ] `skills/{skill-name}/` 目录完整（mcp.json / SKILL.md / index.js / apis/* / utils/*；仅生成组件时含 components/*）；SKILL.md 按 `CODE_TEMPLATES.md` 第五节 5 节结构写完

阶段 6 — 配置集成
- [ ] app.json 加 agent.skills（每项含 `{ name, description, path }`）+ subPackages
- [ ] project.config.json 的 packOptions.include 加 skills
- [ ] （按需）AGENTS.md + `agent.instruction`；page-meta.json + `agent.pageMetadata`（见 6.1 / 6.2）
- [ ] 体积与数量上限自查（上限表见 `CODE_TEMPLATES.md` 6.3）

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

跨阶段跳转规则

核心原则：

1. 业务场景不明确时，必须先澄清后生成
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 卡片）：是/否

阶段 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/analysis-auth.md（鉴权事实结构化 + 逐字代码片段，签名函数体不写成步骤数组）。

• 小项目：主 agent 读 app.js/request 封装/登录文件，自行填写
• 大项目：派 subagent ①（鉴权分析） 深读 app.js / request 封装 / 登录文件 / 签名模块，回传结论摘要（见 references/SUBAGENT_PROTOCOL.md §3.1）

analysis-auth.md 落盘后即为"可信事实"，后续阶段 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 使用）

mcp.json 只注册用户直接使用的原子能力（硬约束）：

以下接口不收集为原子能力、不写 mcp.json、不生成 apis/*.js：

1. 鉴权/登录类：wx.login / wx.checkSession / ensureLogin() / token 刷新 / 获取 sessionId 等——这些是基础设施，由 utils/ 内 ensureLogin() 等函数在每次接口调用前自动执行，不是用户直接使用的能力
2. 系统级/生命周期接口：app 初始化（onLaunch / onShow）、storage 初始化、配置获取、全局状态读取等——这些是框架/运行时行为，不是用户主动触发的业务功能
3. 内部辅助接口：被其他原子接口调用但不直接面向用户的 API（如"获取子列表"被"搜索"内部调用但用户不直接用）——只收集用户视角的功能入口
4. 工具函数：utils/ 中的纯函数（格式化、计算、URL 拼接等）——这些是代码组织，不是独立能力
5. 敏感接口（不可逆副作用）：注销/删除/解绑等——见下方专门规则
6. 管理端接口：管理端操作（如"导出数据"、"管理成员"、"删除商品"、"发布公告"等）——这些是管理端操作，不是用户直接使用的能力

判定标准：问自己"用户会对小程序 AI 说'帮我做 X'吗？"——会 → X 是原子能力；"系统自动做的"或"另一个接口内部调的" → 不是。

敏感接口默认不收集为原子能力（硬约束）：

会产生不可逆副作用的接口，默认不收集为原子能力、不写 mcp.json、不生成 apis/*.js。理由：这类接口风险高（误触发不可恢复）、低频、应由用户在原生页面主动操作，不适合 AI agent 自动调用。

判定原则：

• 不可逆的状态变更：注销账号、删除数据、清空记录等执行后无法撤销的操作，解绑、退订、解散团队、踢出成员、退出等无法恢复的操作

关键词提示清单（命中≠一定敏感，仍需结合语义判断；用于辅助筛选，非穷尽）： log_off / 注销 / 销户 / cancel / delete / 删除 / remove / 移除 / unbind / 解绑 / dissolve / 解散 / kick / 踢出

处理方式：识别到敏感接口时，跳过不选，并在功能清单 JSON 里标注 "skipped": "destructive"（附原因）。这些功能由用户在小程序原生页面自己实现，不暴露给 AI agent。若用户明确要求把某个敏感接口做成原子能力，才收集，并在 probe/plan.json 对应 api 项标 "destructive": true + "destructiveReason"

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

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

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