保贵AI大健康

要解决的问题

给已有小程序接 AI 能力，常见做法是两坨代码并行：页面逻辑留在主包，新增的原子接口去调主包的登录、云开发与全局状态。一旦接口被放进独立分包，getApp()、require('../../xxx')、主包初始化过的 wx.cloud / storage / 登录态全都拿不到，运行期直接崩。反过来逐条抄源码也容易漂移：多写一个 if 兜底、少传一个 header，后端校验是黑盒，线上就会 403 或空数据。

核心能力与关键步骤

wxa-skill-generate 按一条迁移流水线组织：分析源码 → 识别业务 → 提取接口与 JSAPI → 设计原子接口 → 生成代码 → 集成配置 → 交棒校验。

• 源码分析：扫描页面与调用链，按 references/ANALYSIS_PATTERNS.md 识别业务流程；鉴权参数按 references/AUTH_MIGRATION.md 的 auth-spec 契约复刻。
• 运行时探测：每个业务 api 默认全探，scripts/probe.mjs 依赖微信开发者工具与 miniprogram-automator（装在 skill 的 scripts/，不装源项目），用真实响应结构替代「猜字段」。
• 代码生成与集成：按 references/CODE_TEMPLATES.md 产出 mcp.json、SKILL.md、index.js、原子接口实现与工具模块，再更新 app.json / project.config.json。
• 生成期自检：每个阶段跑 node scripts/check-artifacts.mjs --stage <n>，叠加字段忠实自检、AUTH_MIGRATION.md §6 鉴权自检与硬性约束 C 一致性自检。

原子接口落在 skills/{skill}/apis/{name}.js；默认只返回文本 + structuredContent + handoff，原子组件仅在明确要求时产出，路径强约束 skills/{skill}/components/{name}/。

适用边界与注意点

• 入口必须是可读的源码目录，只给 appid / URL / 截图会阻断。依赖小程序插件、能力在源码中找不到对应接口或页面、候选实现全部依赖非白名单 JSAPI、静态分析与 probe 都拿不到响应，都会终止生成并告知用户。
• 独立分包禁用 getApp()、@/ 引用、主包的云开发 / storage / 登录态 / 全局组件；依赖要完整拷贝进分包，由 utils/util.js 自行 ensureCloudInit() / ensureStorageInit() / ensureLogin()。
• 不增不减的迁移：源码没有的 try/catch、默认值、输入校验一律不加；源码里的每个 header/query 必须保留。唯一例外是对数组字段调用 .map() / .filter() 前加类型保护，防止分包环境下响应结构异常抛 TypeError。
• 网络请求唯一入口是 utils/request.js，apis/*.js 直接调 wx.request 会丢鉴权参数。
• 每次生成都要对照 references/JSAPI_WHITELIST.md：接口侧与组件侧白名单不同，组件侧禁用 wx.cloud.* 与业务接口；wx.showToast / wx.navigateTo 等不可迁移，需改写为 content 回馈或删除。
• 接力进小程序走 handoff，需要接口 _meta.ui.pagePath、返回值顶层 handoff（对象或函数）、app.js 注册 wx.onAgentHandoff、接力页 onLoad(query) 四项配齐；wx.openAgent / wx.navigateBackAgent 当前基础库未打通，接力页内不要依赖。
• 生成过程内的自检不等于产物校验：静态规则、真机 execute、组件渲染核对由 wxa-skills-validate 负责，别因此跳过生成阶段的自检。