wxa-skills-generate

name wxa-skills-generate description 分析小程序项目源代码（含压缩/混淆），识别核心业务步骤，提取网络接口与 JSAPI 调用，生成符合 wx.modelContext 规范的技能分包（含原子接口 + 原子组件），并完成 app.json / project.config.json 配置集成。在以下场景触发：把小程序页面能力改造为小程序 AI 原子接口、生成 skills/ 分包代码、从源项目派生 MCP 工具、小程序 AI 的开发模式代码生成。仅负责静态生成，生成完成后必须交棒 wxa-skills-validate 做校验。 metadata {"author":"Tencent","version":"0.2.2"} 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~V019）、真机 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 字符、变量名单字符的产物（含混淆） probe ：阶段名（本 skill 阶段 3.7）。用 automator 在 源项目 上触发请求、捕获真实响应，产物落盘 .ai-mode-skills/probe/ 。属于 生成阶段 automator ：工具名（ miniprogram-automator npm 包）。probe 阶段用它连接开发者工具 WS 端口（9420）操控源项目抓真实请求响应。 仅在 generate 阶段 3.7 使用 execute ：阶段名（ wxa-skills-validate 阶段 4）。用 CLI agent tool 在 已集成的 skills 分包 上真实调用原子接口跑通业务，产物落盘 cli-agent-run/ 。属于 校验阶段 CLI agent ：工具名（微信开发者工具 CLI 的 agent 子命令）。execute 阶段用它通过 agent 模式调用注册的原子接口。 仅在 validate 阶段 4 使用 参考资料索引 文件 用途 加载时机 不加载条件 references/ANALYSIS_PATTERNS.md 业务流程识别、接口/JSAPI 搜索模式 阶段 2 / 3 扫描源码时 用户已明确全部能力且无需再扫页面结构时 references/JSAPI_WHITELIST.md wx API 白名单完整清单（接口侧 / 组件侧 / 不可迁移）；D 节只列高频项 阶段 1 / 3 / 5（D 节未覆盖目标 API 时必查） 无（建议每次对照，不要凭印象） references/CODE_TEMPLATES.md 代码与配置模板（ index.js / utils / apis / mcp.json / skill SKILL.md / app.json ） 阶段 5 / 6 纯改已有单行逻辑、不涉及模板结构时 references/COMPONENT_TEMPLATES.md 原子组件模板 阶段 5（ 仅用户要求生成组件时 ） 用户未要求生成原子组件（默认） references/ATOMIC_COMPONENT_DESIGN.md 组件设计规范（尺寸 / 主题 / 边距 / 字体 / 布局） 同上（强制前置，优先级最高） 同上 references/ATOMIC_COMPONENT_CSS.md 组件 WXSS 实现规范 同上（写样式时） 同上 references/STYLE_MIGRATION.md 源样式提取 + 字段映射工作流 同上（写 WXML/WXSS 前强制前置） 同上 references/HALF_SCREEN.md 半屏页 API 与禁用清单 按需（源业务确有详情/补充信息语义） 默认不生成半屏时 references/RUNTIME_PROBE.md probe SOP、plan/result 格式、失败兜底、合并规则；每个业务 api 默认全探 阶段 3.7 无（有业务 api 即要探；环境不可用走文档兜底路径） references/AUTH_MIGRATION.md auth-spec 契约、鉴权复刻、ensureXxx、§6 自检 阶段 1.2 / 3（interface-spec authRefs ）/ 5.6 无（「无登录」≠「无鉴权」，通用 header/query 仍要读） references/SUBAGENT_PROTOCOL.md 大项目 subagent 分工、源码忠实铁律（interface-spec / plan）、回传纪律、校验 subagent 隔离 大项目：阶段 1（能力索引）/ 1.2（鉴权 subagent）/ 3（§2.3–§2.4）/ 收尾校验（§2.6） 小项目（页面 ≤~30 且无多分包） 硬性约束 A. 独立分包禁止项（必须改写） 禁止项 正确做法 getApp() 分包内自行管理状态（模块变量 / wx.storage ） require('../../xxx') 引用主包/兄弟分包 / import ... from '@/' 把依赖 完整拷贝 到当前分包：单 skill 私有放 {skill}/utils/ ，多 skill 复用放 skills/_shared/ 依赖主包 wx.cloud.init() utils/util.js 中 ensureCloudInit() 自行初始化 依赖主包 app.js 初始化 storage utils/util.js 中 ensureStorageInit() 自行初始化 从 getApp().globalData 读配置 baseUrl / env 硬编码在分包 utils/util.js 依赖主包登录态 每次执行接口前 ensureLogin() 主动走一遍登录流程 使用主包注册的全局组件 在分包 JSON 中重新声明 usingComponents B. 直接终止生成的阻断规则 出现以下任一情况，立即终止生成并告知用户： 阻断情况 检测时机 告知文案 依赖小程序插件（ plugin:// / requirePlugin / app.json 的 plugins ） 阶段 1/3 "该功能依赖小程序插件，当前暂不支持自动生成，需手动接入" 用户声明的能力在源码中找不到任何对应接口或页面 阶段 3 "未能在源码中定位到 <能力名> ，无法生成，请确认能力名称或补充源码" 未提供可读的源码目录（只给 appid / URL / 截图） 阶段 1 前 "请提供小程序完整源码目录，当前无法基于非源码资产生成" 所有候选实现都依赖非白名单 JSAPI 且无替代方案 阶段 3 "该能力依赖非白名单 JSAPI（如 <api> ），无法自动生成" app.json 缺 "lazyCodeLoading": "requiredComponents" 配置 阶段 1 "项目 app.json 顶层缺少 \"lazyCodeLoading\": \"requiredComponents\" ，否则独立分包内的原子接口被小程序 AI 路由调用时无法正确加载执行。请在 app.json 顶层添加该字段后重新触发生成" 静态分析 + probe 均无法获取真实响应结构 阶段 3 "接口 <api> 无法通过静态分析或运行时探测获取真实接口信息，无法生成" 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/ / 自定义名）不限。 作用域以"是否在原子接口处理函数链路上"判定，不以目录名判定 。 分类 高频接口 小程序 AI wx.modelContext.registerAPI 、 wx.modelContext.createSkill （返回 { use, registerAPI } ）、 wx.modelContext.expireAllCards 、 wx.modelContext.getSessionId （获取会话 ID） 登录 wx.login 、 wx.checkSession 网络 wx.request 、网络状态 getNetworkType / on*NetworkStatusChange 云开发 wx.cloud.init / callFunction / database 位置 wx.getLocation / getFuzzyLocation （ 不含 chooseLocation / openLocation ） 系统 wx.getDeviceInfo 、 wx.getAppBaseInfo 、 wx.getWindowInfo 数据缓存 wx.{get,set,remove,clear,batchGet,batchSet}Storage （含 Sync ）、 wx.getStorageInfo 上传下载 wx.uploadFile 、 wx.downloadFile 订阅消息 wx.requestSubscribeMessage 授权设置 wx.authorize 、 wx.getSetting （ 不含 openSetting ） 图片 wx.getImageInfo 手机号 wx.getPhoneNumber 、 wx.getRealtimePhoneNumber 账号 wx.getAccountInfoSync （接口与组件均可调） 支付类、系统选择器/采集（ 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 接力页" 节）： mcp.json ：在该接口 apis[]._meta.ui 加 pagePath （接力页 path， 不含 query ；与 componentPath 同级， componentPath 仅在生成组件时才有）。 原子接口返回值 ：顶层（与 content / structuredContent 同级）增加 handoff ， 兼容两种形态 ： 对象（立即模式，更快） ： handoff: { query, payload?, card? } ——模型无需筛选数据时直接返回对象，平台即时生成 handoff，链路更短、更快。 函数（延迟模式） ： handoff: ({ result }) => ({ query, payload?, card? }) ——需要用 模型修改后的 result 时返回函数，入参对象的 result 即模型修改后的完整 result。 字段： query 为 string （页面 query 字符串，如 'drugId=xxx' ，原样注入 onLoad(query) 与 wx.onAgentHandoff 回调，宜短）； payload 可选（接力页首屏加速数据）； card 可选（卡片展示信息，如 { title } ）。 app.js ： onLaunch 内注册 wx.onAgentHandoff(cb) （须早于 handoff 触发的 onBeforeAppRoute ），把 { path, query, payload } 按 pageId 暂存。 接力业务页 ： onLoad(query) 中 query 为 string（与 handoff.query 一致），按页面原有方式解析 query 字符串；若 wx.onAgentHandoff 投递了 payload 则先 setData 加速首屏。 平台代做（无需自己实现路由）：按 pagePath 打开目标页 → 把 handoff.query （string）原样注入 onLoad(query) 与 wx.onAgentHandoff 回调 → 通过 wx.onAgentHandoff 按 pageId 投递 payload 。 禁用 ： wx.openAgent / wx.navigateBackAgent 当前基础库侧未打通，调用会失败——接力页内 不要 依赖"打开 Agent / 返回 Agent 对话"，后续流程由业务页自行完成。 D.7 不可迁移 JSAPI（接口与组件均禁用，高频示例；完整清单见 references/JSAPI_WHITELIST.md §3 ） 不可用 API 替代策略 wx.showToast / showModal / showLoading / showActionSheet 等 UI 反馈 结果通过 content / structuredContent 回馈，小程序 AI 无 loading/modal 概念