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 对应一个可完成的业务场景。

好例子：外卖点单 SKILL、酒店预订 SKILL、医院挂号 SKILL、课程报名 SKILL、订单售后 SKILL。

坏例子：首页 SKILL、用户中心 SKILL、工具集合 SKILL、所有功能 SKILL。

一个原子接口只做一件事。

好例子：

• searchProducts：搜索商品列表。
• selectProduct：查看某商品详情与规格。
• confirmSku：确认规格并生成待支付订单。
• payOrder：发起支付。

坏例子：

• handleOrderFlow：搜索、选品、下单、支付全包。模型无法稳定规划，也无法审计。

5. 推荐目录结构

miniprogram-root/
├── app.json
├── AGENTS.md          （可选，全局提示词，最大 10000 字节）
├── page-meta.json     （可选，文字链/页面元数据，最大 8000 字节）
├── pages/
├── services/
└── skills/            （独立分包 root）
    └── <business-skill>/
        ├── SKILL.md   （必需，最大 16000 字节，不支持引用其他 md）
        ├── mcp.json   （必需，最大 24000 字节，计算时排除 outputSchema 和空白）
        ├── index.js
        ├── apis/
        │   ├── searchItems.js
        │   ├── selectItem.js
        │   ├── confirmOrder.js
        │   └── payOrder.js
        └── components/  （按需；绑定 GUI 卡片时实现）
            ├── item-list-card/
            ├── order-confirm-card/
            └── result-card/

硬限制（按 2026-06 官方文档）：

文件	是否必需	大小上限	备注
AGENTS.md	可选	10000 字节	全局提示词
微信 AI SKILL.md	每个 SKILL 必需	16000 字节	不支持引用其他 md
mcp.json	每个 SKILL 必需	24000 字节	排除 outputSchema 和空白后计算
page-meta.json	可选	8000 字节	文字链/页面元数据

一个小程序最多声明 30 个微信 AI SKILL。一个微信 AI SKILL 只能属于一个分包；一个分包可以放多个 SKILL。

6. app.json 配置模板

按项目实际路径调整：

{
  "lazyCodeLoading": "requiredComponents",
  "subPackages": [
    {
      "root": "skills",
      "pages": [],
      "independent": true
    }
  ],
  "agent": {
    "skills": [
      {
        "name": "order",
        "description": "订单查询、确认、支付等业务",
        "path": "skills/order-skill"
      }
    ],
    "instruction": "AGENTS.md",
    "pageMetadata": "page-meta.json"
  }
}

注意：

• lazyCodeLoading: "requiredComponents" 是必需的。
• SKILL 目录必须在独立分包下。
• name 用短英文，description 用业务语言，不要写“这是一个 Skill”。
• path 必须与 wx.modelContext.createSkill(path) 的入参完全一致。

7. 微信 AI SKILL.md 写法

微信 AI SKILL.md 只写“整个业务怎么跑”。单接口功能、参数语义、字段默认值，应写在 mcp.json，不要在两处重复。

推荐结构：

# <skill-name> <业务场景>

## 业务流程
写“用户意图 -> 原子接口 -> 用户操作 -> 原子接口 -> 卡片/结果”。

## 原子接口依赖关系
| 接口 | 作用 | 绑定组件 | 前置条件 |
| --- | --- | --- | --- |

## 跨接口业务约束
- 输出形态：什么时候必须出卡片，什么时候可以纯文本。
- 执行顺序：动作类接口成功前，不能向用户宣称已经完成。
- 并发限制：订单、支付等变更类接口通常要串行。
- 数据来源：ID、枚举、订单状态必须来自上游真实返回，禁止从用户自然语言猜测。

## 模型禁止行为
- 列出不可由模型自主执行的动作（支付、下单、删除、修改敏感信息等）。
- 说明高风险动作的确认机制。

## 用户意图分流
- 列出典型用户表达对应的首个原子接口。
- 标出哪些情况必须反问澄清。

## 错误处理与澄清策略
- 参数缺失时如何反问。
- 接口失败时给用户什么提示。
- 哪些情况应引导用户跳转到小程序页面完成。

关键原则：凡是“不能错”的规则，不能只写在自然语言说明里，要尽量下沉到 mcp.json 的接口 description、参数 description、枚举、required、outputSchema 中。

8. mcp.json 设计规范

每个 API 必须包含：

• name：英文动词 + 业务对象，具体清晰。避免 search、handle 这类含糊命名。
• description：首句说明业务对象；包含调用前置条件；包含禁止调用场景；必要时说明下一步边界。
• inputSchema：所有参数来源必须明确，禁止模型编造 ID、金额、手机号、地址。
• outputSchema：返回结构化数据，供组件渲染和后续接口引用；建议填写。
• _meta.ui.componentPath：如果该 API 要展示 GUI 卡片，必须绑定组件。

inputSchema.description 推荐写法：

{
  "orderId": {
    "type": "string",
    "description": "订单唯一标识，必须来自 confirmOrder 或 searchOrders 返回的 orderId 原值。禁止从用户自然语言推断；上下文无 orderId 时先调用 searchOrders。"
  }
}

避免写法：

{ "orderId": { "type": "string", "description": "订单 ID" } }

精简 mcp.json 示例，实际项目按业务扩展字段：

{
  "apis": [
    {
      "name": "searchOrders",
      "description": "搜索用户历史订单。调用前置条件：用户询问历史订单或指定订单关键词。禁止场景：用户正在确认支付时不要调用本接口。调用后：展示订单列表卡片，等待用户选择具体订单。",
      "_meta": { "ui": { "componentPath": "components/order-list/index" } },
      "inputSchema": {
        "type": "object",
        "properties": {
          "keyword": { "type": "string", "description": "订单关键词，取自用户原话；未提供时留空，不要编造。" }
        }
      },
      "outputSchema": {
        "type": "object",
        "properties": { "items": { "type": "array" } }
      }
    }
  ],
  "components": [{ "path": "components/order-list/index", "relatedPage": "/pages/orders/index" }]
}

组件声明必须包含 relatedPage。没有完全对应页面时，可配置上一级页面或首页。只有确实需要网络请求、定时器等动态能力时，才声明 permissions.scope.dynamic.desc。

9. 原子接口返回协议

每个原子接口都应返回稳定对象。content 必须是数组格式，不可用纯字符串。

async function handler(args = {}) {
  if (!args.requiredId) {
    return {
      isError: true,
      content: [
        {
          type: 'text',
          text: '缺少 requiredId。请先引导用户选择目标对象，不要编造 requiredId。'
        }
      ]
    }
  }

  return {
    isError: false,
    content: [
      {
        type: 'text',
        text: '已生成确认信息。请展示确认卡片，并引导用户核对后点击确认继续。'
      }
    ],
    structuredContent: {
      requiredId: args.requiredId,
      status: 'confirmed'
    },
    _meta: {
      imageUrl: 'https://example.com/render-only.png'
    }
  }
}

规则：

• content 为数组，每项 { type: 'text', text: '...' }，写成“事实 + 下一步动作”。
• 失败或空结果时，content 必须包含具体事实、正确出口、需要避免的错误动作。
• structuredContent 给模型和组件看，不要放只用于渲染的字段，例如图片 URL、样式参数。
• _meta 对模型不可见，仅给组件渲染使用。
• isError: true 时不渲染 GUI 卡片，structuredContent 会被忽略。
• isError: false 且绑定组件时，AI 倾向渲染 GUI 卡片；可在 content 中明确“请展示某某卡片”。
• 接口不要做大段 UI 逻辑、多步骤隐式流程、无确认支付、无来源生成 ID、静默吞错。

10. 注册与中间件模板

const searchOrders = require('./apis/searchOrders')
const confirmOrder = require('./apis/confirmOrder')
const payOrder = require('./apis/payOrder')
const skill = wx.modelContext.createSkill('skills/order-skill')

skill.use(async (ctx, next) => {
  const start = Date.now()
  try {
    // 可在这里统一登录、埋点、错误监听。
    await next()
    // 上报成功：ctx.name、Date.now() - start。
  } catch (error) {
    // 上报失败后继续抛出，避免静默吞错。
    throw error
  }
})

skill.registerAPI('searchOrders', searchOrders)
skill.registerAPI('confirmOrder', confirmOrder)
skill.registerAPI('payOrder', payOrder)

中间件会在该 SKILL 的每次原子接口调用时执行。多个中间件按注册顺序形成外层到内层，再回到外层的调用链。

11. 原子组件规范

原子组件是 AI 对话流里的业务卡片，不是完整页面。只有绑定 GUI 卡片的 API 才必须实现组件。

Component({
  lifetimes: {
    created() {
      this._modelCtx = wx.modelContext.getContext(this)
      this._viewCtx = wx.modelContext.getViewContext(this)
      const { NotificationType } = wx.modelContext
      this._modelCtx.on(NotificationType.Result, (data) => {
        const result = data?.result || {}
        const sc = result.structuredContent || {}
        const meta = result._meta || {}
        this.setData({ ...sc, ...meta })
        if (sc.orderId) this._viewCtx.setRelatedPage({ query: `orderId=${sc.orderId}` })
      })
    }
  },
  methods: {
    onConfirm() {
      this._modelCtx.sendFollowUpMessage({
        content: [
          { type: 'text', text: '确认下单' },
          { type: 'api/call', data: { name: 'payOrder', arguments: { orderId: this.data.orderId } } }
        ]
      })
    },
    onViewDetail() {
      this._viewCtx.openDetailPage({ url: `/pages/order/detail?orderId=${this.data.orderId}` })
    }
  }
})

强制约束：

• 不要把原子组件声明成虚拟组件。
• 不要依赖与原子接口共享全局状态。
• 不要使用官方不支持的事件。
• 不要使用竖向滚动或动画。
• 不要在普通卡片里使用网络、云开发、定时器；确有必要时声明 scope.dynamic 并写清理由。
• 卡片高度必须适应官方最小/最大比例；高度在初始化时确定，后续不可再改变。
• 只使用官方支持的内置组件和 WXSS 能力。
• 用户可见的上行消息必须像用户自己说的话，不能像系统日志。

12. 半屏页面、高风险动作、卡片过期

半屏页面：

• 只有原子组件可以调用 getViewContext(this).openDetailPage({ url }) 打开半屏页面；原子接口不能打开。
• 半屏页面内不要使用页面路由、跳出半屏的接口、广告相关能力。
• 用 sendFollowUpMessage() 返回 AI 对话并继续流程。
• 如果半屏操作后需要刷新卡片，可调用 reapplyApiCall({ arguments }) 重新执行原调用链。

高风险动作必须显式确认，不得由 AI 静默执行：

• 支付、下单、取消订单。
• 修改地址、手机号、实名信息。
• 删除数据。
• 发送通知、发券、发消息。
• 授权隐私权限。

每一项高风险动作都应同时满足：

• mcp.json description 写明前置条件和禁止场景。
• inputSchema 约束关键 ID 来源，禁止模型编造。
• 原子接口内部做二次参数校验。
• 原子组件上显示确认按钮，由用户主动触发 api/call。
• 支付成功必须以接口返回结果为准，不以用户口述为准。

卡片过期：

• 对订单确认、支付、领券、预约等一次性操作卡片，优先声明组件 expirable: true。
• 可用 wx.modelContext.expireAllCards() 或 getViewContext(this).expirePreviousCards() 让旧卡片失效，避免重复点击。
• 组件收到 NotificationType.Expire 后应停止轮询、禁用按钮或清理状态。

13. pageMetadata、知识库、小程序与 AI 互跳

pageMetadata / page-meta.json：

• 用于文字链拉起小程序页面，是 AI 模式的兜底策略和页面元数据补充。
• 主流程优先在 AI 内用原子接口和卡片闭环；核心功能不要靠文字链导流。
• 页面描述写“用户能在页面完成什么”，不要只描述文件名或运营活动文案。
• 示例字段：path 写页面路径，name 写页面标题，description 写用户可完成的任务。

知识库：

• 适合 FAQ、专业知识、企业智能助手等问答。
• 通常在用户问题属于知识查询且没有 SKILL 匹配时兜底。
• 如果希望优先或避免知识库，应在 AGENTS.md 或微信 AI SKILL.md 中明确引导。

小程序与 AI 互跳：

• 从小程序页面打开 AI：先用 wx.checkIsSupportAgent() 判断，再调用 wx.openAgent()。
• 胶囊入口打开 AI 时，可用 wx.onAgentOpen() 携带 followUpMessage 和 context。
• 从文字链或卡片右上角关联页回到 AI，可用 wx.navigateBackAgent() 携带 followUpMessage 和 context。

14. 调试与评测清单

完成后逐项检查：

• 已安装微信开发者工具 Nightly，编译模式切到“小程序 AI 编译”。
• 基础库使用 3.16.1，除非官方文档已有更新。
• 单个 SKILL 调试可用。
• 单个原子接口可用，并能手动输入参数。
• 单个原子组件可用，已检查不同宽度和最小/最大高度。
• 完整对话单步调试中，原子接口入参与出参正确。
• 使用校验/评测工具前，已在开发者工具“设置 -> 安全设置”开启服务端口。
• 评测用例覆盖：成功路径、缺信息、无效 ID、空结果、重复动作、支付/订单安全、卡片上行消息。
• 支付、发票、人脸识别等高风险流程使用测试号。
• 真机预览前确认当前微信客户端和基础库版本满足要求。

15. 审查阻断项

遇到以下问题应阻断或修复：

• 官方尚未开放提审时，把 AI 模式代码混入正式版本提交。
• app.json 缺少独立分包或 lazyCodeLoading。
• 微信 AI SKILL.md 缺少业务流程、依赖关系、跨接口约束。
• mcp.json 使用 search、handle 这类含糊 API 名，或 description 太泛。
• ID 字段没有说明来源接口和来源字段名。
• 动作类接口可以在缺少上游确认状态时调用。
• 原子接口没有校验模型生成的入参。
• 原子接口 content 用纯字符串而非数组格式。
• 成功 content 缺少“事实 + 下一步动作”。
• 错误 content 缺少原因和出口，或只写禁止动作。
• 渲染用字段放进 structuredContent 而不是 _meta。
• 绑定 GUI 卡片的 API 缺少对应组件，或组件缺少 relatedPage。
• 没有明确理由就声明动态组件权限。
• 半屏页面使用了禁用跳转、页面路由或广告能力。
• 用户可见的上行消息像系统日志，不像用户自己说的话。

16. 完成后的回复要求

实现完成后，向用户或项目负责人报告：

• 修改了哪些文件。
• 新增或修改了哪些微信 AI SKILL、原子接口、原子组件。
• 如何在微信开发者工具中打开和调试。
• 已验证什么，哪些无法在本地验证。
• 仍然存在的 beta、审核、上线风险。

17. 最小验收标准

一个合格接入至少满足：

• app.json 中有 agent.skills 注册，且 SKILL 目录在独立分包下。
• 每个微信 AI SKILL 有 SKILL.md、mcp.json、index.js、apis/。
• 绑定 GUI 卡片的 API 有 components/ 实现和 relatedPage。
• mcp.json 每个 API 都有清晰 description、inputSchema、参数来源说明和建议的 outputSchema。
• 高风险动作有前置条件声明、参数约束、接口二次校验和组件确认机制。
• 正向路径能从自然语言触发到卡片或文本结果。
• 错误路径能反问或提示，不会乱编结果。

18. 官方参考来源

遇到规范疑问，必须复查官方来源，不要依赖训练知识或第三方博客。优先查看：

• 微信小程序 AI 官方文档：guide.html、integration.html、operating-mechanism.html、debugging.html、best-practices.html、reference/api.html、reference/component.html、reference/detail-page.html、evaluation-guide.html、faq.html。
• 官方 Demo：https://github.com/wechat-miniprogram/ai-mode-demo