微信小微AI-接入模式与开通准备|两种模式选错,后面全白干——小微接入的隐藏门槛

接入模式与开通准备|两种模式选错,后面全白干------小微接入的隐藏门槛

系列《小微(微信小程序 AI)实战》第 2 篇

⚠️ 版本声明:本文基于小微内测版本(截至 2026-11-18 的官方文档与团队实测),微信官方尚未推出正式版本,文中能力、配置、版本号、入口路径均可能随版本迭代调整,正式版发布后请以官方文档为准。


写在前面

上一篇讲了小微是什么、用户说一句话背后的链路。这一篇解决「怎么开始接入」:

  1. 微信提供了哪两种接入模式,各自适合谁?
  2. 如何开通 AI 能力?
  3. 那些不提前确认、后面会被卡死的版本门槛(我们团队全部踩过)。

本系列聚焦 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 阅读顺序建议

按这个顺序读,效率最高:

  1. 接入方式(上面的链接)------两种模式的接入步骤总览,建立全局认知
  2. 目录结构说明------AI 代码要求的目录组织(AGENTS.md / skills / mcp.json),第三篇会讲我们怎么把它放进 Taro 工程
  3. 基础语法:SKILL 与 mcp.json ------这是开发模式的核心:怎么声明一个技能、怎么写接口的 description / inputSchema、怎么配卡片组件
  4. 官方 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 字段等)请直接看官方文档,本文不复制粘贴------内测阶段文档变化快,与其抄进文章,不如给读者指路。


六、本篇小结

  1. 两种模式:自动模式 (零代码、平台解析)vs AI 开发模式(skill + mcp、精准可控),可同时开启,开发模式优先级更高
  2. 开通入口:公众平台 → 基础功能 → AI 能力,建议双开
  3. 版本门槛是内测期最大的坑:客户端 8.0.79+ (仅 iOS/Android)、基础库 3.16.2 / 3.17.5+ (注意 private 配置覆盖)、工具最新 Nightly
  4. 区分「AI 开发模式」和「AI 页面交互模式(自主思考)」------后者命不中你时才出现
  5. 动手前先读官方接入文档(integration.html),按第 4 节的带读地图过一遍并自检 5 个问题,再进实战篇

下一篇进入实战:AI 开发模式怎么在工程里落地------独立分包、app.config.ts 的 agent 配置,以及原生 AI 代码和 Taro 主工程共存的方案。


参考

本文为实战经验整理(基于内测版本),官方能力与流程以微信开放文档及公众平台后台为准。

相关推荐
htzyl20610 分钟前
CSS中,`:has()` 能帮你删掉的 4 类 JS
前端·css
verohh15 分钟前
(四)配置驱动与动态渲染——从固定页面到可组合的前端架构
前端
颜进强19 分钟前
认识小微|一句话就能直接调起你小程序的微信 AI,多数人第一眼就理解错了
前端·ai编程·全栈
锐影用AI做小程序26 分钟前
uni-app X + Spring Boot 做在线工具站:6 个真实踩坑与解法
前端
掘金挖土26 分钟前
前端手摸手跑路之 AI 应用开发(十二)
前端·后端
颜进强27 分钟前
微信里冒出一个新 AI 入口,我们把接入它的每一步坑都写下来了
前端·ai编程
不要试图纠正别人27 分钟前
178 个 IPC 通道不可怕,可怕的是 preload 里那一行
前端·electron
bai27330 分钟前
Node 22 里的等待:从回调到 Promise,一次上传流程的最小记录
前端
__sjfzllv___30 分钟前
在职前端Leader学习/转行 AI Agent -DAY104
前端