微信小程序 AI 开发模式入门：用一个咖啡点单例子讲清楚 SKILL、原子接口、原子组件

2012 年，第一批做公众号的人什么都没干，粉丝就自己涨。

2017 年，第一批上线小程序的商家，靠「附近的小程序」这个入口白捡了一波用户，什么推广费都没花。

这两次窗口开了多久？大概六个月。六个月之后，跑进来的人多了，红利就被稀释光了。

6 月 8 日，微信开放平台发布了《关于开发者接入微信 AI 生态的指引》，第三个窗口开了。

不同的是，这次门槛更高了一点：不是发文章，不是建页面，而是给你的小程序写一套 SKILL，让微信 AI 能调用你的业务能力。用户跟微信 AI 说"帮我买杯咖啡"，AI 直接调你的接口下单，整个过程用户不用打开你的小程序。

美团、携程、滴滴都已经官宣接入。头部品牌接入反而慢，因为体量大、流程复杂，联调就要好几周。

一个做细分场景的独立开发者，今天下午能把核心接口写完，明天就能提交内测。这是这轮窗口里少有的时间优势。

但大多数人卡在同一个地方：文档一打开，原子接口、原子组件、SKILL、小程序 MCP，这些词叠在一起，不知道从哪里下手，也不知道自己到底要做什么。

下面用一个咖啡店点单小程序，把所有概念在一个具体场景里讲清楚。

先搞懂四个概念

官方文档把这四个词定义为"基本概念"，但定义是抽象的，放到咖啡店点单这个场景里，每个词都能对应到一个具体的实体。

小程序 MCP 是一套协议，作用是把你小程序里能干的事暴露给微信 AI。它和标准 MCP 不一样的地方在于：你不用自己写一堆工具描述，只要按规范把一个完整的 SKILL 提供出来，微信 AI 就能自己推理、自己挑接口、自己执行。在咖啡店里，MCP 就是那本"菜单+操作手册"，告诉 AI"这家店能点单、能查询饮品、能下单"。

原子接口是这套模式里最小的执行单元，一个接口只干一件事，有固定的输入参数和输出结构，跑在微信客户端的一个独立 JS 环境里——注意，这个环境和你平时小程序的运行环境是分开的。咖啡店里的原子接口就是 searchDrinks（搜饮品）和 createOrder（下订单），每个接口只负责一件事，参数和返回都规规矩矩。

原子组件是原子接口的可视化外壳，把接口返回的结构化数据渲染成 GUI 卡片，直接显示在对话流里。用户说"有什么推荐"，searchDrinks 返回三款饮品的结构化数据，原子组件把它渲染成一张带图片、价格、规格选项的饮品卡片，用户在卡片上点一下就选中，不用打字。

SKILL 是把上面三样打包成一个完整能力的容器。一个小程序可以封装多个 SKILL，每个 SKILL 由三部分组成：业务说明（SKILL.md）、模型可调能力的声明（mcp.json）、原子接口和原子组件的实现代码。咖啡店的"点单 SKILL"就是把搜饮品、下订单两个接口、对应的饮品卡片和订单确认卡片、加上一份告诉 AI 这套流程怎么走的 SKILL.md，一起打包。

四个词的关系一句话串起来：你把业务拆成原子接口和原子组件，打包成 SKILL，通过小程序 MCP 协议交给微信 AI，AI 在对话里按需调用，最终在对话流里渲染成卡片给用户。

接入流程

官方给的步骤不复杂，但每一步都有要注意的地方。

第一步，申请开启。在「微信公众平台 - 基础功能 - AI 能力」里选「开发模式」申请。这一步目前是内测，需要等审核通过才能往下走。

第二步，封装 SKILL。这是工作量最大的一步。你需要把小程序里的业务功能抽象成原子接口，写好对应的原子组件，再写一份 SKILL.md 说明业务流程，一份 mcp.json 声明有哪些接口可调。这一步的难点不在写代码，在写描述文字——后面会专门讲。

第三步，调试。下载微信开发者工具的 Nightly Electron 版本（正式版没有这个能力），在「编译模式」里切到「小程序 AI 编译」，调试基础库切到 3.16.1。如果看不到「小程序 AI 编译」这个选项，先回到公众平台确认你的 AI 能力开发模式申请通过了。官方还提供了一个完整的示例 demo（github.com/wechat-miniprogram/ai-mode-demo），可以拿来当起点，但记得把 demo 里的 appid 改成你自己申请过开发模式的 appid。

第四步，等提审开放。目前内测阶段不开放代码提审，所以这一步暂时是"写好等着"。

文档没说清楚的几个地方

官方文档把接口定义、返回格式、目录结构都写得很清楚，但有几个决定成败的地方，文档只给了一个模板，没有告诉你为什么这样写、不这样写会出什么问题。没有现成的完整案例可以抄，官方 Demo 是咖啡店点单场景，但 SKILL.md 和 mcp.json 的写法细节都是一笔带过。

踩过坑才知道，这个框架里最难的部分是：你写的每一行描述文字，直接决定 AI 能不能正确调用你的接口。这不是在写注释，是在给模型写 prompt。

下面把最容易卡住的几个地方拎出来讲，配上官方文档没有的反例。

难点一：mcp.json 的 description 写法，差一句话 AI 就选错接口

官方文档给的示例是这样的：

"description": "查询当前位置或某地的未来一段时间的天气"

看起来没问题。但在实际场景里，一个小程序可能有十几个接口，AI 要从里面选一个调用。描述写得模糊，AI 就会选错。

有几个具体的坑：

首句要说「业务对象」，不要说「参数」。"搜索饮品。按关键词、温度检索……"比"按关键词、温度搜索商品……"要好，差别在于前者让 AI 一眼看出这个接口干什么，后者要 AI 自己推断。

接口描述里要写「不适用场景」。比如咖啡店同时有饮品搜索和食品搜索两个接口，如果饮品接口的描述里没有写"仅限饮品，不涉及食品"，AI 在用户说"来一份三明治"的时候可能也会调饮品搜索。

接口之间描述不能重叠。两个接口都写"根据用户需求返回商品"，AI 每次都在猜调哪个，准确率会明显下降。

难点二：ID 类字段不写来源，AI 会自己编一个

这是最容易出线上问题的地方，但官方文档只用一行带过了。

字段如果是业务 ID（比如 drinkId、orderId），description 里必须写清楚这个 ID 从哪个上游接口来：

"drinkId": {
  "description": "饮品唯一标识，取自 searchDrinks 或 getRecommendedDrinks 返回的 drinkId 原值。不要从用户自然语言推断，也不要使用示例值。上下文无可用 drinkId 时，应先调 searchDrinks。"
}

不这样写会发生什么？AI 拿到用户说的"拿铁"，会尝试从这个词推断出一个 drinkId 填进去。ID 格式如果是数字，AI 可能填 1、001 或者随机一个，调用必然失败，而且你很难从日志里看出是这个原因。

难点三：content 是给 AI 看的行动指令，不是给用户看的提示

官方文档讲了 content 的格式，但没有讲清楚它对 AI 行为的影响程度。

这里有一个很反直觉的事：原子接口执行完之后，AI 会读 content 里的文字，然后决定下一步做什么。

只写结果，AI 不知道下一步该干什么：

// 这样写，AI 可能直接把饮品列表以文字形式回复给用户，不渲染卡片
content: [{ type: "text", text: "已查询到3款饮品" }]

写上动作，AI 才会驱动渲染：

// 这样写，AI 才会触发卡片渲染
content: [{ type: "text", text: "已查询到3款饮品，请展示饮品卡片让用户选择" }]

两段代码逻辑完全一样，只有 content 里那句话不同，用户看到的界面却是两种完全不同的体验。

失败分支更要注意。不能只写"查询失败"，要写：失败的具体原因 + 下一步应该干什么 + 禁止重复调用。三件事缺一件，AI 就会在错误分支里绕圈子。

难点四：SKILL.md 到底写什么、写多少

官方给的定义是"SKILL 的详细说明"，最大长度 16000 字节。但没有说清楚哪些内容该写在这里，哪些不该写。

有一个实用的判断标准：影响单个接口调用的规则，写在 mcp.json 的 description 里；影响多个接口之间关系的规则，写在 SKILL.md 里。

比如"支付接口不能并发调用，必须等上一笔结束后再发起"，这条规则影响的是整个支付流程，写在某个单一接口的 description 里没用，因为调用其他接口的时候 AI 读不到它。

SKILL.md 里最值钱的内容是：用户意图的分支（说了关键词 A 走哪个接口，说了模糊需求走哪个接口），接口之间的依赖关系（必须先调 A 拿到 ID 才能调 B），以及哪些情况不应该调接口直接回复文字。

这些内容官方文档没有给模板，需要自己总结自己的业务流程来写。

内测限制，提前知道

官方在文档开头就写明了：当前处于内测阶段，暂未开放小程序 AI 开发模式的代码提审，提审时间另行通知。原话还加了一句——请勿将此模式相关代码合入正式版本提交审核，以免影响正常版本发布。

这句话的实际意思是：你可以开发、可以调试、可以本地跑通，但现在还没法上线给真实用户用。所以现阶段投入精力，更多是抢跑准备，等提审一开放就能第一时间上。

另一个限制是身份。用户在这个模式下的登录身份跟原小程序保持一致，开发者可以通过 storage 接口共享小程序里的登录凭证，也可以用 wx.login、wx.getPhoneNumber 等接口完成登录流程。这意味着你原来的登录体系不用重写，但要确认你的原子接口能正确拿到这些凭证。

写在最后

这个框架的核心，不是写代码难，是写描述文字难。你写下的每一段 description、每一句 content，都不是给人看的注释，而是给模型看的指令。模型理解错了，你代码写得再漂亮也没用。

如果你准备上手，建议先跑通官方的咖啡店 demo，把它当模板，然后把自己的业务一条一条替换进去。每替换一个接口，都用模糊的用户话术测一遍，看 AI 调得对不对——这比读十遍文档都有用。