微信小程序 AI 开发最佳实践：让模型行为可预测的 5 层规范

引言

微信小程序 AI 能力让用户通过自然语言与小程序交互——说「想喝点清爽的」就能获得推荐并下单。但这种自由对话的背后，如果接口规范和业务编排写得草率，模型就会频繁选错接口、填错参数、输出机器人腔文案。

微信官方文档给出了一套完整的规范——从产品设计原则到 mcp.json 字段怎么写、content 怎么返回、SKILL.md 怎么编排，甚至上行消息的文案措辞都有细致约定。这套规范的核心思想很朴素：每一类信息有它唯一的归属位置，写错位置 = 模型行为不可控。

本文提炼这套规范的关键要点，结合开发场景给出可落地的检查清单。

产品设计原则概览

一、产品设计：AI 是对话参与者，不是填表工具

产品设计层面，微信给出 4 条核心原则，以 WeStoreCafe 点单 SKILL 为参考案例：

1. 承接模糊意图

用户说「想喝点清爽的」「最近有什么推荐」——这不是特定的查询参数，而是需要 AI 理解并翻译为搜索条件的自然语言。设计重点：入口是对话，不是表单。AI 完成理解和推荐后，再由原子组件完成确认和下单。

2. 自然语言修改内容

修改规格、时间、地点等枚举值或明确实体的字段时，用户不需要跳出对话回到表单页面。比如「把温度改成去冰」「换成大杯」直接在当前对话流中完成。

3. 历史数据可查询可操作

高频场景下，类似「再来一杯上次喝的」「用积分兑换一张优惠券」这种依赖历史资产的操作应该直通。这要求系统维护用户行为上下文，并将搜索结果与历史订单关联。

4. 服务进程动态实时更新

订单或服务原子组件随状态推进动态刷新——下单后卡片更新为「制作中」，制作完成后更新为「请取餐」。静态快照式的卡片会让用户错过关键状态变化。

这 4 条原则的落脚点是：让 AI 成为一个主动的对话协调者，而不是嵌在页面角落的被动问答 bot。

二、SKILL 封装：三层信息源的分工与约束

如果说产品设计解决「用户体感」，SKILL 封装解决「模型调用准确率」。这是整份文档含金量最高的部分。

SKILL 封装架构

2.1 信息源权重：写对位置比写多内容更重要

小程序 AI 决策时综合读取三个信息源，但注意力权重差异显著：

信息源	注意力	核心作用
原子接口返回的 `content`	★★★★★	离决策点最近，模型当「事实 + 动作」读
`mcp.json` 的 `description`	★★★★	决定模型「选不选这个接口」
`mcp.json` 的 `inputSchema.description`	★★★★	决定模型「怎么填参数」
`SKILL.md`	★★★	适合业务流程编排、跨接口规则、意图分流

关键推论：把接口功能写到 SKILL.md 里，把业务规则写到接口 description 里——都是常见的错误分派，会让模型在需要时读不到该读的信息。

信息源注意力权重

2.2 内容分工表

每类信息源有明确的「写什么」和「不该写什么」：

信息源	写什么	不该写什么
`content`	本次调用结果与下一步动作	接口功能描述（属于 description）
`mcp.json` description	接口本身的功能、调用时机、不适用场景	跨多接口的业务规则（属于 SKILL.md）
`mcp.json` inputSchema.description	参数语义、取值来源、缺省处理	—
`SKILL.md`	业务流程、跨接口约束、意图分流、通用规范	单接口功能描述（属于 mcp.json）

三条通用写作原则贯穿所有信息源：

同一约束只写一处——重复书写容易因措辞不一致引发冲突。
硬约束放在权重更高的位置——能在代码层面强校验的优先做代码校验。
每条禁令配一个明确的替代动作——只写「不要做 X」而不写「应做什么」，模型会缺少出口。

2.3 原子接口声明规范（mcp.json）

接口 description 编写要点：

接口名语义化：searchDrinks 而非 search。
首句声明业务对象，而非入参。反例：「按关键词、温度、杯型搜索商品列表」——首句强调入参，且「商品」语义过宽。正例：「搜索饮品。按关键词、温度、杯型检索…」——先点明业务对象。
不写内部实现细节，它挤占「使用边界」信息。
职责单一，接口间不重叠。
同名字段统一命名：如 drinkId 不混用 itemId。

字段 description 编写要点：

入参字段优先传 ID 而非自然语言——门店传 storeId，饮品传 drinkId，减少歧义、推理更快更稳。

普通字段需要多样化举例 + 缺省处理：

// 反例：只举一个例子，未说明缺省处理
"keyword": { "description": "饮品关键词，如『拿铁』" }

// 正例：多样化举例 + 缺省处理
"keyword": {
  "description": "饮品关键词，例如『拿铁』『美式』『奶茶』。
    用户未说出具体饮品时，不要填写本字段，应改走饮品推荐接口。"
}

ID 类字段需要标注取值来源：

// 反例
"drinkId": { "description": "饮品 ID" }

// 正例
"drinkId": {
  "description": "饮品唯一标识，取自上游接口 searchDrinks 或
    getRecommendedDrinks 返回的 drinkId 原值。不要从用户自然语言
    （如『那个拿铁』）推断，也不要使用示例值。
    上下文无可用 drinkId 时，应先调 searchDrinks。"
}

2.4 content 返回规范：事实 + 动作两段式

content 是离模型决策最近的信息源，错误话术在此会直接覆盖 SKILL.md 的约定。

核心规则：先陈述客观状态，再给出下一步动作。仅有动作没有事实时，模型可能误解意图：

content 两段式对比

失败或空结果的 content 必须包含三件事：

陈述具体事实——「未匹配到『圣诞限定款』饮品，已附带本店热销饮品兜底数据」
给出下一步出口——「请先告诉用户未找到，并引导用户在热销饮品中挑选」
指出不应做的动作——「不要再以相同关键词重复调用本接口」

另外需注意：

原子接口需校验参数有效性（如 drinkId 是否存在），因为 AI 生成的参数不保证正确。
structuredContent 承载卡片展示数据，content 承载结果说明与决策约束，避免重复。
渲染需要但 AI 无需理解的数据（如图片地址、后台冗余字段）通过 _meta 传递。

2.5 SKILL.md 编排规范

mcp.json 描述「单个接口怎么用」，SKILL.md 描述「整个业务怎么跑」。

业务流程梳理要点：

节点用接口名，与 mcp.json 完全一致（含大小写）。
从用户意图入口分支，每个分支对应典型表达（模糊/明确关键词/特定场景）。
标注用户操作节点和执行分支逻辑（如「无 X 时先走兜底接口、补全后回到主流程」）。
补充接口依赖关系表——按接口维度列出触发前置条件，便于模型调用前快速判断。

跨接口业务约束写在 SKILL.md：

输出形态规则：何时出卡片、何时出纯文本。
执行顺序：动作类接口必须确认执行成功后方可向用户宣称。
并发串行：支付类接口不应并发。
数据来源：业务 ID 应取自上游接口的真实返回，不要从用户语言推断或编造。

2.6 上行消息文案

用户在原子卡片操作时系统自动上行一条消息代替用户发言。如果措辞带有系统播报感、技术描述感或字段拼接感，体验会瞬间出戏。

撰写原则：

原则	说明
用户视角出发	第一人称，不以系统口吻叙述
不上行系统消息	异常消息也需转换成用户操作的语言
自然语言表达	摒弃字段罗列、编码格式
生活化用语	优先生活化口语，规避专业术语
仅限已表达信息	信息仅限当前操作可推导，不擅自补充
简洁但不歧义	多选场景规避「这个」「那个」

三、落地检查清单

以下 9 条检查项覆盖从产品设计到文案上线的全链路，逐项核查即可快速定位规范盲区：

落地检查清单

逐项说明：

界面能承接模糊意图——入口是对话而非表单，AI 主动理解并推荐。
自然语言可修改内容——规格/时间/地点可对话修改。
历史资产可查询可操作——「再来一杯上次的」可直通。
服务状态动态实时更新——卡片随状态推进而变。
接口名语义化——searchDrinks，首句声明业务对象。
字段 description 多样化举例 + 缺省处理——含多示例，明确缺省行为，ID 标注取值来源。
content 事实+动作两段式——失败返回含三条要素（事实/出口/禁止事项）。
SKILL.md 只写流程编排——不膨胀为接口功能手册。
上行消息用户视角——第一人称，无系统播报感。

总结

微信小程序 AI 最佳实践给出了一套少而精的规范体系，它的内在逻辑很清晰：

产品层：让 AI 成为对话的主动协调者，而非被动问答 bot。
协议层：mcp.json 负责「选接口 + 填参数」，content 负责「当前结果 + 下一步」，SKILL.md 负责「流程走向 + 跨接口约束」——三层各有边界。
体验层：上行消息从用户视角出发，卡片状态动态更新，让 AI 对话不「出戏」。

回看所有规则，一句话可以概括：每一类信息有它唯一的归属位置，写错位置意味着模型在需要它的时候读不到它。把这个原则内化，开发效率和对齐效果都会显著提升。

「真诚赞赏，手留余香」