# 微信小程序 AI 开发模式：官方 MCP 接入全解

> **来源**: https://developers.weixin.qq.com/miniprogram/dev/ai/guide.html
> **出处**: 微信官方文档「小程序 AI 开发模式」系列（能力介绍 / 接入方式 / 运行机制 / 调试 / 组件与 API 支持），含同目录子页 integration.html、operating-mechanism.html、debugging.html、reference/component.html、reference/api.html
> **归档日期**: 2026-06-11
> **owner 原话**: 「深度学习一下这篇文章 放到知识库 以后为接入做准备」（法国是冠军，桑群交办）
> **用途**: 为小M 后续接入微信小程序 AI 能力做准备（owner 2026-06-11 交办）

## 核心论点

微信把「小程序 AI」做成了官方 agent 运行时：用户在微信内与 AI 对话，AI 通过**小程序 MCP 协议**调用开发者声明的能力。开发者不再写页面流程，而是把业务拆成「**原子接口**（最小执行单元，标准化输入输出）+ **原子组件**（结构化数据渲染成 GUI 卡片）」，打包成 **SKILL**（业务说明 SKILL.md + 能力声明 mcp.json + 实现代码）。这套设计与 Anthropic 的 MCP/Skills 思想同构——工具用 JSON Schema 声明、文档与实现分离、LLM 负责编排——等于微信给 13 亿用户装了个内置 agent harness，小程序从「APP 形态」变成「AI 可调用的工具集」。当前处于**内测 beta**，暂未开放代码提审，但申请入口已开放，是提前布局的窗口期。

## 要点摘录

### 1. 能力总览与核心概念（官方原文定义）

- **小程序 MCP**：「向小程序 AI 暴露可调用能力的一套协议」，适配小程序开发特性
- **原子接口**：「此模式的最小执行单元，封装单一的业务功能，具有标准化输入参数和输出结构」
- **原子组件**：「原子接口的可视化展示单元，将原子接口返回的结构化数据渲染为 GUI 卡片」
- **SKILL**：「完成特定场景任务的完整能力封装」= 业务文档 + MCP 声明 + 实现
- 用户登录身份与原小程序一致（复用 `wx.login` 体系）
- 官方 demo：https://github.com/wechat-miniprogram/ai-mode-demo

### 2. 接入前置条件（实操清单）

| 条件 | 要求 |
|------|------|
| 申请入口 | 微信公众平台 → 基础功能 → AI 能力，或小程序「微信开发者助手」→ 管理 → 微信AI管理，接入模式选「**开发模式**」 |
| 开发者工具 | 微信开发者工具 **Nightly Electron Build 最新版** |
| 调试基础库 | **3.16.1** 及以上 |
| 真机预览 | 微信 **8.0.74 及以上，目前仅 iOS** 支持；扫预览码后右上角胶囊出现「小程序 AI 开发模式」入口 |
| 阶段限制 | **内测 beta，暂未开放代码提审**；官方明示「不建议把此模式代码合入正式版送审」 |
| 资质/类目 | 文档未列出额外资质要求（隐含前提：已有小程序主体）；「实时动态组件」权限需单独审核 |

### 3. 工程结构：app.json + SKILL 目录

`app.json` 新增 `agent` 字段，SKILL 放独立分包，并要求 `"lazyCodeLoading": "requiredComponents"`：

```json
{
  "lazyCodeLoading": "requiredComponents",
  "subPackages": [{ "root": "packageA/weather-skill", "independent": true, "pages": [] }],
  "agent": {
    "skills": [{ "name": "weather", "description": "天气查询", "path": "packageA/weather-skill" }],
    "instruction": "AGENTS.md",
    "pageMetadata": "page-meta.json"
  }
}
```

| 配置对象 | 限制 |
|------|------|
| skills 数量 | 最多 **30 个** |
| AGENTS.md 全局提示词 | 最大 **10000 字节**（可选） |
| page-meta.json 页面元数据 | 最大 **8000 字节**（可选，声明可跳转页面及其 query JSON Schema） |

SKILL 目录必备三件套：

| 文件 | 必填 | 作用 | 限制 |
|------|------|------|------|
| SKILL.md | 是 | 给 LLM 看的业务详细说明 | 最大 **16000 字节**，仅单文件 |
| mcp.json | 是 | 模型可调用能力声明 | 最大 **24000 字节**（不含 outputSchema 和空格） |
| index.js | 是 | 原子接口注册入口 | - |

### 4. mcp.json：接口与组件声明

```json
{
  "apis": [{
    "name": "getWeather",
    "description": "查询天气",
    "inputSchema": { "type": "object", "properties": {}, "required": [] },
    "outputSchema": { },
    "_meta": { "ui": { "componentPath": "components/weather-card/index" } }
  }],
  "components": [{
    "path": "components/weather-card/index",
    "relatedPage": "/pages/weather/detail",
    "expirable": true,
    "expiredText": "服务已过期",
    "permissions": { "scope.dynamic": { "desc": "实时刷新天气" } }
  }]
}
```

- `inputSchema`/`outputSchema` 即 JSON Schema；图片/文件入参用 `"format": "image"` / `"format": "file"` 标注，AI 会让用户选图后传本地路径
- `_meta.ui.componentPath` 把接口结果绑定到渲染卡片——**数据与渲染声明式分离**

### 5. 原子接口运行时（index.js）

```javascript
const getWeather = require('./apis/getWeather')
const skill = wx.modelContext.createSkill('packageA/weather-skill')
skill.registerAPI('getWeather', getWeather)
```

返回值结构（MCP tool result 同款）：

| 字段 | 类型 | 必填 | 限制 |
|------|------|------|------|
| isError | boolean | 否（默认 false） | - |
| content | ContentBlock[]（type: "text"） | 是 | ≤ **200 KB** |
| structuredContent | object | 否 | ≤ **200 KB** |
| _meta | object（LLM 不可见） | 否 | ≤ **200 KB** |

**中间件机制**：`skill.use(async (ctx, next) => {...})`，ctx 含 `name / skillPath / arguments`，可做统一登录态、埋点、错误捕获；多个中间件成链，**与原子接口共享 300 秒超时上限**。

### 6. 原子组件（卡片）

- 自研卡片渲染引擎（**非 WebView/Skyline**），WXSS 子集：rpx 以 **750 分点**为基准、opacity 0~1、支持 calc()/env(safe-area-inset-*)/@media/@font-face
- 尺寸：宽随屏幕；高度初始化决定后**不可变**，最小 **4:1**（宽:高）、最大 **1:1**
- 事件仅支持 **tap、image load/error**；默认**禁网络请求、禁定时器**（需 `scope.dynamic` 单独审核解锁）；不支持动画、竖向滚动、打开小程序接口
- 数据流：`wx.modelContext.getContext(this)` 监听 `NotificationType.Input / Result`；`getViewContext(this)` 拿 `getDimensions()` 与 `Overflow` 事件
- **过期态**：声明 `expirable: true` 后可调 `wx.modelContext.expireAllCards({componentPaths, match: 'latest'})` 或组件内 `viewCtx.expirePreviousCards()`，卡片置灰显示 expiredText——解决「历史卡片信息过时」问题

### 7. 半屏页面与双向消息

- 卡片点击 `viewCtx.openDetailPage({url})` 打开半屏页（运行环境同小程序但部分能力受限）；可 `preloadDetailPage` 预加载
- 半屏页上行消息回 AI 对话流：`ctx.sendFollowUpMessage({content: [{type:'text',...},{type:'api/call',data:{name,arguments}}]})`，**arguments ≤ 1000 字符**；H5 页经 `WeixinJSBridge.invoke('invokeMiniProgramAPI',...)` 同样可发
- 半屏内 `modelCtx.reapplyApiCall({arguments})` 重跑原子接口刷新卡片
- 小程序 ↔ 小程序 AI 互通：`wx.checkIsSupportAgent` / `wx.openAgent({followUpMessage, context})` / `wx.onAgentOpen` / `wx.navigateBackAgent`
- 场景值：卡片关联页 **1442/1443**、半屏页 **1433/1434**、文字链拉起 **1435/1436**

### 8. 运行机制（三层架构）

```
用户消息 → 小程序 AI 后台（加载 SKILL，LLM 推理选接口）
        → 客户端运行时执行原子接口（可调第三方服务）
        → 结果回传后台 → 下发渲染指令 → 客户端渲染原子卡片
```

- 原子接口、原子组件、实时动态组件跑在**三个互相隔离的 JS 上下文**，不共享全局变量
- 客户端运行时回收：退后台 **30 分钟**主动结束 / 内存告警清理 / 用户重启；会话结束后下次进入是**全新会话**
- 支付：原子接口内可直接 `wx.requestPayment` 拉起收银台

### 9. API / 组件支持矩阵（节选）

**原子接口环境支持**：wx.login/checkSession、wx.request 及全部网络/上传下载、云开发（cloud.callFunction/database）、定位四件套、全部 Storage、wx.requestPayment 全家、requestSubscribeMessage、getPhoneNumber、chooseMedia、scanCode、蓝牙/WiFi/传感器/TCP/UDP、getWeRunData、人脸检测、隐私授权。**不支持**：振动、MapContext.openMapApp、previewMedia。

**原子组件环境仅支持**：env/设备信息、Storage、showToast、openLocation、makePhoneCall、shareAppMessage（需 tap 回调内）、下载、地图（除 openMapApp）、振动、previewMedia/openDocument、隐私授权——多数需 scope 声明。

**内置组件**：view 完整；text（无 user-select）、image（仅网络地址 + **png/jpg**）、button（**不支持任何 open-type**）、canvas（仅 **2d**）、scroll-view（仅**横向**）、map（不可拖动缩放）。

### 10. 配套：官方知识库（RAG）

公众平台 → 基础功能 → AI 能力 → 知识库可直接上传资料增强问答：支持 PDF/DOC/DOCX/PPT/PPTX/TXT/MD/XLSX，**单文件 ≤ 10MB，总数 ≤ 10 个**；效果目前仅开发版/体验版可体验。

### 11. 硬性数字速查表

| 项 | 限制 |
|------|------|
| SKILL 数 | ≤ 30 |
| AGENTS.md / SKILL.md / mcp.json / page-meta.json | 10000 / 16000 / 24000 / 8000 字节 |
| 接口返回 content / structuredContent / _meta | 各 ≤ 200 KB |
| 中间件+接口执行超时 | 300 s |
| followUpMessage arguments | ≤ 1000 字符 |
| 后台保活 | 30 min |
| 知识库 | 10 文件 × 10 MB |
| 卡片宽高比 | 4:1 ~ 1:1 |
| 微信客户端 / 基础库 | ≥ 8.0.74（仅 iOS）/ ≥ 3.16.1 |
| 场景值 | 1433/1434、1435/1436、1442/1443 |

## 与本项目的落地点

1. **路线定位**：小M 现在走的是 PC 端「外挂路径」（ingest_daemon 读消息库 + sender.py UI 自动化），灰色且脆弱；小程序 AI 开发模式是微信**官方 agent 路径**。两者不冲突——群聊陪伴继续用现路径，对外提供 AI 服务（健身报告、桑学档案查询等）应走官方路径。**第一步行动**：owner 注册/复用小程序主体，到公众平台「基础功能-AI能力」申请「开发模式」内测资格，占住窗口期；开发机备一台 iOS + 微信 ≥8.0.74。
2. **概念已对齐，迁移成本低**：mcp.json 的 name/description/inputSchema 就是 Claude 的 MCP tool 声明；SKILL.md(≤16000字节) + 实现 ≈ 本项目 .claude/skills 的 SKILL.md 体系；AGENTS.md(≤10000字节) ≈ CLAUDE.md。小M 的 plugins（天气、新闻、健身周报）天然就是「原子接口」形态，把每个 plugin 的入参出参补成 JSON Schema 即可平移。
3. **值得抄·中间件链**：官方在每个工具调用外包一层 `skill.use(ctx, next)` 做统一登录态/埋点/错误捕获（共享 300s 超时）。小M 的 plugin 调用目前各管各的，可在 plugin 注册表外加同构 middleware 层，统一日志和降级。
4. **值得抄·卡片过期态**：`expirable + expireAllCards({match:'latest'})` 专治「旧卡片信息过时」。小M 群里发的新闻/天气消息同样会过时，可借鉴：消息库记 message_id + 失效时间，早报引用旧数据前先查有效性。
5. **值得抄·预算式声明**：微信给每层文档设硬字节预算（10000/16000/24000/8000），强制「常驻薄、按需厚」——与已归档的 harness 纪律笔记（CLAUDE.md ≤8K + 分层加载）完全互证，本项目 bot_rules/skills 继续按此预算瘦身。
6. **知识库联动**：readytodie.cc 知识库的 md 笔记可直接作为小程序 AI 知识库语料（MD 在支持格式内，10 文件×10MB 上限），等于本管线产出未来能一键喂给官方 RAG。