微信小程序 AI 能力最佳实践：SKILL 封装与产品设计指南

本文整理自微信小程序 AI 能力官方文档的最佳实践章节，从产品设计和 SKILL 封装两个维度，系统梳理如何构建高质量的小程序 AI 体验。

一、产品设计

以下以 WeStoreCafe 点单 SKILL 为参考案例，梳理此模式下的核心设计点：

对话承接用户的模糊意图

当用户表达"想喝点清爽的""最近有什么推荐"这类非结构化需求时，由 AI 完成理解和推荐，再引导至原子组件完成确认和下单。关键在于让 AI 充当"翻译层"，把模糊意图转化为可执行的操作路径。

可通过自然语言修改内容

用户无需跳出对话，可直接通过自然语言修改规格、时间、地点等枚举值或明确实体的字段内容。这降低了操作门槛，让修改流程更顺畅。

历史数据与个人资产可查询、可操作

高频消费场景下的核心诉求是效率。"再来一杯上次喝的""用积分兑换一张优惠券"这类指令可被执行，能显著提升使用效率。AI 需要能够访问和操作历史数据。

服务进程动态实时更新

订单或服务原子组件随状态推进动态更新，而非静态展示，防止用户错过关键更新。例如订单状态从"已下单"→"制作中"→"已完成"的实时反馈。

二、SKILL 封装

1、信息源与分工

小程序 AI 在决定调用哪个原子接口、生成什么参数、回复什么内容时，会综合多个上下文信息源做判断。这些信息源在权重和职责上各有侧重，写在错误的位置会显著降低准确率。

1.1 注意力权重

1.2 内容分工

1.3 常见错位

• 把"接口本身的功能"写到 SKILL.md：长文膨胀、与 mcp.json 易不一致。SKILL.md 中的接口清单只写"前置条件 + 上下游关系"。
• 把"跨多接口的业务规则"写到单个接口的 description：仅在调用该接口时生效，其他接口决策时模型读不到。应写在 SKILL.md。
• 把"接口功能描述"写到 content：content 只承载本次调用结果与下一步动作，功能描述属于 description。

2、通用写作原则

适用于上述所有信息源：

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

3、原子接口声明（mcp.json）

3.1 接口 description

• 接口名使用语义化名称。searchDrinks 优于 search。
• 首句声明「业务对象」，而非「入参」。
  • 反例："按关键词、温度、杯型搜索商品列表（仅饮品）……"——首句强调入参，且"商品"语义过宽。
  • 推荐："搜索饮品。按关键词、温度、杯型检索……"——首句先点明业务对象，再描述入参维度。
• 不写内部实现细节。实现细节对模型选择接口没有帮助，会挤占真正重要的"使用边界"信息。
• 职责单一，描述互不重叠。接口之间避免包含关系；描述面向模型而非用户，措辞简洁即可。
• 同名字段统一命名。同一含义的字段在不同接口保持一致，例如饮品 ID 始终用 drinkId，不要混用 itemId。

3.2 字段 description

入参字段选取：优先传 ID 而非自然语言。例如门店传 storeId 而非省市街道，饮品传 drinkId 而非饮品名称、类目。模型不必再从自然语言中反复提取和匹配，参数歧义更少，推理也更快、更稳。

普通字段写法：举例时给多个不同样本（避免被当默认值），并配明确的缺省处理。

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

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

ID 类字段：声明取值来源接口。业务 ID 容易被按格式凑出，需在 description 中显式声明来源。

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

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

4、原子接口返回 content

content 直接面向小程序 AI，承载本次调用结果并约束下一步动作。

4.1 通用规则

• 输入校验：小程序 AI 生成的参数不保证正确，原子接口需校验类型与有效性（如 drinkId 是否存在）。
• 返回内容：structuredContent 与 content 都会提供给小程序 AI：前者承载结构化数据（卡片展示内容），后者承载结果说明与决策约束，两者避免重复。渲染需要但小程序 AI 无需理解的内容（如图片地址、后台冗余字段）通过 _meta 传递。
• 错误处理：返回明确的错误原因与下一步指引。缺信息："缺少收货地址，需用户补充"；无结果："未找到相关饮品，可换关键词重试"。

4.2 事实 + 动作两段式

content 应先陈述本次返回的客观状态，再给出下一步动作。仅有动作没有事实时，模型可能把"展示卡片"理解为"准备调下一步接口"而跳过等待用户确认。

// 反例：仅给动作，缺少事实
"接下来请务必为用户展示订单确认卡片。"

// 推荐：事实 + 动作
"已根据所选规格生成订单。请展示订单确认卡片，并用一句话引导用户核对后下单。"

4.3 失败 / 空结果

失败或空结果分支的 content 应包含三件事：

1. 陈述具体事实：把问题原因写清楚，如"未在饮品库中匹配到名为「圣诞限定款」的饮品"
2. 给出下一步出口：接下来应该做什么
3. 指出不应做的动作：如禁止再重复尝试调用此原子接口（须与第 2 条配对出现）

示例：

未匹配到「圣诞限定款」，已附带「本店热销饮品」兜底数据。 请先告诉用户"未找到「圣诞限定款」"，并引导用户在以下本店热销饮品中挑选。 不要再以相同关键词重复调用本接口。

5、SKILL.md

mcp.json 描述"单个接口怎么用"，SKILL.md 描述"整个业务怎么跑"：业务流程、接口依赖、跨接口约束。

5.1 业务流程

把"用户意图 → 原子接口 → 用户操作 → 原子接口"梳理清楚，便于模型理解整体编排。书写要点：

• 节点用接口名，接口名与 mcp.json 的原子接口完全一致（含大小写）
• 从用户意图入口分支，每个分支对应一类典型表达（模糊 / 明确关键词 / 特定场景）
• 标注用户操作节点（如"用户选择某款""用户确认"），用以区分由谁触发下一步
• 标注分支，对"无 X 时先走兜底接口、补全后回到主流程"这类场景

5.2 接口依赖关系

业务流程描述整体走向，依赖关系表则按接口维度列出触发前置条件，便于模型在调用前快速判断当前是否满足条件。

5.3 业务约束

跨多个接口生效的强约束写在 SKILL.md，常见类型：

• 输出形态：何时必须出卡片、何时才能出纯文本
• 执行顺序：动作类接口必须确认原子接口执行成功，未调用前不应向用户宣称"已为您完成"
• 并发串行：如订单支付原子接口不应并发，须等上一笔结束（成功、失败或取消）后再发起
• 数据来源：业务 ID 应取自上游接口的真实返回，不要从用户语言推断或编造

6、上行消息文案撰写建议

用户在原子卡片及半屏进行操作，有时会自动上行一条消息至对话区。这条消息将直接展示给 C 端用户，本质上是系统代替用户发出的一条对话内容。

6.1 基本原则

• 用户视角出发：文案应以用户口吻表达，让用户看到后不会产生"系统在替我说话"的感受
• 操作语义准确：文案应准确反映用户刚刚完成的实际操作，不扩大、不缩减、不歪曲用户意图
• 会话承接自然：文案进入对话流后，应能被后续服务自然承接，不造成语义突兀或流程割裂
• 对话简洁清晰：文案应避免系统播报感、技术描述感和字段拼接感，控制信息量

6.2 具体撰写原则

总结

微信小程序 AI 能力的最佳实践核心可以概括为三点：信息源各司其职（content/description/SKILL.md 各有分工）、约束写在最有效的位置（硬约束靠近决策点）、给模型可执行的出口（每条禁令配一个替代动作）。遵循这些原则，能显著提升小程序 AI 的准确率和用户体验。