wechat-miniprogram-ai

微信小程序 AI 接入开发指南

本 Skill 面向 Codex、Claude Code、Cursor、Qwen Code 等代码代理。代理应扫描项目、判断接入模式、拆解业务闭环，并直接生成合理的代码补丁，而不是只输出概念说明。

先区分两个概念：本文件是给代码代理使用的“开发指南 Skill”；微信运行时里每个业务能力也有一个 SKILL.md，下文统一称为“微信 AI SKILL.md”。

1. 官方状态护栏

• 默认把“小程序 AI 开发模式”视为 beta/内测能力，除非微信官方文档明确说明已开放正式提审。
• 涉及上线、审核、正式发布前，必须复查微信官方文档。按 2026-06 官方文档，当时暂未开放该模式代码提审，不应把相关代码合入正式版本提交审核。
• 优先依据微信官方文档和官方 Demo wechat-miniprogram/ai-mode-demo，不要以第三方博客作为规范来源。
• AI 模式代码应尽量隔离，避免影响普通小程序版本发布。
• 不要假设所有正式版微信开发者工具都支持调试 AI 开发模式；必要时提示使用支持该能力的 Nightly 版本。

2. 先判断接入模式

拿到项目后，先判断模式，再动手改造。不要默认直接做开发模式。

自动模式

适合：

• 小程序业务流程短，页面结构清晰。
• 团队希望低成本先接入，暂时无法投入微信 AI SKILL 开发。
• 主要目标是让 AI 能理解页面、辅助用户操作，而不是稳定编排核心交易链路。

处理方式：

• 优化页面标题、按钮文案、表单 label、空状态、错误提示、权限提示。
• 检查关键页面是否有明确用户动作路径：搜索、选择、填写、确认、支付、取消。
• 降低页面交互复杂度，避免隐藏入口、强运营位遮挡、流程依赖长链跳转。

风险：

• AI 可能绕过首页、运营位、品牌露出。
• 页面复杂时 GUI 操作不稳定。
• 开发者对 AI 执行顺序、参数来源、错误处理的控制较弱。

开发模式

适合：

• 交易、预约、下单、查询、售后、会员、内容检索等核心流程。
• 需要稳定、可审计、可控的 AI 执行。
• 需要在微信 AI 对话流里展示自定义业务卡片。

处理方式：把业务拆成若干微信 AI SKILL，每个 SKILL 包含业务说明、mcp.json、原子接口、按需实现的原子组件，并在 app.json 的 agent.skills 中注册。

推荐策略：自动模式用于通用页面兜底，开发模式承接核心业务闭环。pageMetadata 是文字链/页面元数据能力，可作为兜底补充，不要把它当成自动模式的必要配置。

3. 项目改造总流程

内部按以下顺序执行；除非用户只要方案，否则优先直接修改代码：

1. 审查项目现状：pages、components、services、api、store、utils、app.json、project.config.json。
2. 判断项目是原生小程序、Taro、uni-app 还是其他跨端框架。
3. 找到分包、业务 API/service、登录态、缓存、支付、地址、上传等关键流程。
4. 如果是 uni-app，检查是否会替换全局 wx 导致 wx.modelContext 丢失；必要时按官方 FAQ 给 @dcloudio/uni-mp-weixin 打补丁。
5. 找出 1-3 个最适合 AI 化的用户任务，不要贪多。
6. 将每个任务拆成“意图 -> 原子接口 -> 原子组件或文本结果 -> 后续动作”。
7. 新建独立 SKILL 目录，例如 skills/order-skill/。
8. 编写微信 AI SKILL.md：业务流程、接口依赖、禁止行为、意图分流、错误处理。
9. 编写 mcp.json：声明 APIs、inputSchema、outputSchema、按需绑定 UI 组件、相关页面。
10. 实现 index.js：创建 Skill、注册中间件、注册原子接口。
11. 实现 apis/*.js：每个接口只做一个最小业务动作。
12. 按需实现 components/*：只有需要 GUI 卡片的接口才必须绑定原子组件。
13. 修改 app.json：增加 agent.skills，按需增加 agent.instruction、agent.pageMetadata。
14. 编写或更新测试用例：正向路径、缺参数、越权、取消、支付失败、重复调用、上下文丢失。

4. SKILL 拆分原则

一个微信 AI SKILL 对应一个可完成的业务场景。