微信小程序 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. 接入前置条件（实操清单）

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

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

{
  "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"
  }
}

SKILL 目录必备三件套：

4. mcp.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）

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

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

中间件机制：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. 硬性数字速查表

与本项目的落地点

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。