接入模式与开通准备|两种模式选错,后面全白干------小微接入的隐藏门槛
系列《小微(微信小程序 AI)实战》第 2 篇
⚠️ 版本声明:本文基于小微内测版本(截至 2026-11-18 的官方文档与团队实测),微信官方尚未推出正式版本,文中能力、配置、版本号、入口路径均可能随版本迭代调整,正式版发布后请以官方文档为准。
写在前面
上一篇讲了小微是什么、用户说一句话背后的链路。这一篇解决「怎么开始接入」:
- 微信提供了哪两种接入模式,各自适合谁?
- 如何开通 AI 能力?
- 那些不提前确认、后面会被卡死的版本门槛(我们团队全部踩过)。
本系列聚焦 AI 开发模式 (skill + mcp),自动模式只做对比介绍;开发模式的语法细节请以官方文档为准------本文第四节会给一份官方文档的带读地图,请先照着它把接入方式和基础语法过一遍,再进入第三篇的实战。
一、两种接入模式
微信官方提供了两种让小微「认识」你小程序的方式(详见官方接入必读:developers.weixin.qq.com/miniprogram...
| 模式 | 代码门槛 | 原理 | 适合 |
|---|---|---|---|
| 自动模式 | 零代码 | 授权后平台读取源码、解析页面,自动供小微操作 | 展示类 / 短链路小程序,快速试点 |
| AI 开发模式 | 需要开发 | 把功能抽象为原子接口 + 原子组件 ,封装成 SKILL,通过「小程序 MCP」协议暴露给小微 | 需要精准控制触发条件、链路和体验的场景 |
两者不互斥,可以同时开启;开发模式控制力更强、调用优先级更高。
还有一个容易混淆的概念顺带澄清:团队内部我们曾把两种东西都叫「AI 模式」,实际要区分------
- AI 开发模式:即 skill + mcp 能力,按你注册的原子接口被调用(本系列主线)
- AI 页面交互模式:小微未命中任何小程序 mcp 时的「自主思考」回答------用户拿到的回答看起来也挺合理,但和你的小程序没有任何关系。很多「为什么小微不理我」的现象,本质就是落到了这一层(详见第 9 篇排查篇)
为什么本系列选开发模式
以我们的场景为例:用户说「帮我搜索 XX 先锋」,期望的是精准搜到这一只基金并直达详情页。自动模式做不到这种意图级的精准控制;开发模式可以通过接口描述精确声明「什么时候调我、什么时候别调我」,并且卡片、接力页、参数透传全部可控。
二、如何开通 AI 能力
操作路径(内测版本口径):
微信公众平台 → 基础功能 → AI 能力
在这里可以分别开启:
- 自动模式:授权即可
- 开发模式:开启后才能提交带 AI 代码的版本评测与提审
也可以在「微信开发者助手 → 管理 → 微信AI管理」操作(入口以官方后台实际为准)。
这是 0 号门槛 ------没开通,后面写的所有代码、跑的所有流程都不成立。我们强烈建议自动模式和开发模式同时开启:开发模式承接核心意图,自动模式覆盖长尾意图,两层叠加提高被命中的概率(第 10 篇展开)。
三、版本门槛:不提前确认必被卡死
这一节是我们用几天排查时间换来的,比开通步骤重要得多。以下每个数字都实际踩过:
3.1 微信客户端版本:8.0.79+
- mcp + skill 的召回能力仅支持 iOS 和 Android 微信 8.0.79 及以上
- 鸿蒙暂不支持
- 团队实测:同事反馈「始终命不中」,排查半天,最后发现是 iOS 微信版本低于 8.0.79------版本不满足时,mcp+skill 召回功能直接不可用,没有任何提示
3.2 调试基础库版本
| 能力 | 最低基础库版本 |
|---|---|
wx.modelContext.createSkill(开发模式入口 API) |
3.16.2+ |
context.query(用户原话透传) |
3.17.5+ |
典型报错:Skill code loading failed: wx.modelContext.createSkill is not a function------这不是你代码写错了,是基础库版本过低。
一个隐蔽的坑:基础库版本取值优先级是 project.private.config.json > project.config.json (private 覆盖 public)。我们曾把 project.config.json 改到 3.17.5,运行还是报错------最后发现 private 配置里写的是 3.15.2,把 public 覆盖了。排查时两个文件都要看。
3.3 开发者工具:必须最新
- 必须使用微信开发者工具 Nightly 版(最新 Electron Build)
- 旧版工具没有 AI 开发模式的调试与评测入口
- 内测阶段工具迭代很快,遇到诡异问题第一步:升级工具到最新 Nightly
3.4 版本检查清单(接入前过一遍)
- 微信公众平台已开启 AI 能力(自动模式 + 开发模式)
- 开发者工具为最新 Nightly 版
-
project.private.config.json与project.config.json的libVersion均 ≥ 3.17.5 - 真机验证用微信 8.0.79+(iOS / Android)
- 验证账号在小程序成员管理名单内(灰度相关,第 9 篇详述)
四、动手前,先去官方文档熟悉接入方式与基础语法
本篇不复制官方语法,而是给你一份带读地图。 请打开官方「接入方式」文档通读一遍:
👉 developers.weixin.qq.com/miniprogram...
为什么不抄进文章:内测阶段官方文档迭代很快,抄进来的语法随时会过期;而且这份文档本身就是最好的教材------官方还配了可运行的 demo,跟着敲一遍比看十篇文章都有效。
4.1 阅读顺序建议
按这个顺序读,效率最高:
- 接入方式(上面的链接)------两种模式的接入步骤总览,建立全局认知
- 目录结构说明------AI 代码要求的目录组织(AGENTS.md / skills / mcp.json),第三篇会讲我们怎么把它放进 Taro 工程
- 基础语法:SKILL 与 mcp.json ------这是开发模式的核心:怎么声明一个技能、怎么写接口的
description/inputSchema、怎么配卡片组件 - 官方 demo ------文档配套的示例工程,强烈建议本地跑通一遍(用 Nightly 工具),它就是你后续开发的脚手架
4.2 带着这 5 个问题去读(自检)
读完官方文档后,你应该能回答:
- 一个 SKILL 由哪几部分组成?(SKILL.md / mcp.json / apis / components 各管什么)
-
mcp.json里接口的description和inputSchema是给谁看的、起什么作用? - 原子接口的返回值里,
content/structuredContent/handoff各自对应什么(喂给模型的文本 / 卡片数据 / 点击接力)? - 原子组件(卡片)和接力页分别在哪里配置、什么关系?
-
AGENTS.md和SKILL.md的分工是什么?(整体人设边界 vs 单技能业务规则)
这 5 个问题答不上来,说明还没读透------不要跳到实战篇。第 3、4 篇会默认你已经掌握这些概念,只在「官方文档没讲清楚、我们踩过坑」的地方展开。
4.3 一个提前的心智准备
官方文档教的是「语法正确」,实战中真正花时间的往往是「语义写得好不好」:
- 同样语法正确的
description,写得准的能命中、写得差的不命中 - 同样能跑通的返回值,
handoff/ 错误处理的结构差异会直接决定卡片出不出、AI 说不说错话
这些「文档之下的经验」是本系列第 4、8 篇的主题,先把官方语法啃完,带着问题来。
五、开发模式能做什么(能力速览)
内测版本下,开发模式已提供的能力远比早期传闻丰富,按需了解、后续篇章实战展开:
- 原子接口 + 原子组件:接口返回结构化数据 + 对话流卡片,卡片由你自定义
- 接力(handoff):卡片点击后动态指定目标页并携带业务参数
- 用户原话透传(context.query):平台把用户本轮原文直接传给接口
- 文本混排链接(page-link):回复正文里嵌可点击链接
- 半屏页 + 折叠区(collapsible-view):轻量交互页与长列表折叠
- 卡片刷新与过期(reapplyApiCall / 原子组件过期):用户操作后刷新卡片、旧卡置灰
- 隐私授权卡片(requestAgentPrivacyAuthorization):涉私有数据的授权链路
- 多模态输入:接口入参支持图片 / 文件
具体语法(mcp.json 结构、inputSchema、handoff 字段等)请直接看官方文档,本文不复制粘贴------内测阶段文档变化快,与其抄进文章,不如给读者指路。
六、本篇小结
- 两种模式:自动模式 (零代码、平台解析)vs AI 开发模式(skill + mcp、精准可控),可同时开启,开发模式优先级更高
- 开通入口:公众平台 → 基础功能 → AI 能力,建议双开
- 版本门槛是内测期最大的坑:客户端 8.0.79+ (仅 iOS/Android)、基础库 3.16.2 / 3.17.5+ (注意 private 配置覆盖)、工具最新 Nightly
- 区分「AI 开发模式」和「AI 页面交互模式(自主思考)」------后者命不中你时才出现
- 动手前先读官方接入文档(integration.html),按第 4 节的带读地图过一遍并自检 5 个问题,再进实战篇
下一篇进入实战:AI 开发模式怎么在工程里落地------独立分包、app.config.ts 的 agent 配置,以及原生 AI 代码和 Taro 主工程共存的方案。
参考
本文为实战经验整理(基于内测版本),官方能力与流程以微信开放文档及公众平台后台为准。