微信小微AI-【实战四】给 Agent 立人设|一份 AGENTS.md,决定小微是靠谱助手还是满嘴跑火车

【实战四】给 Agent 立人设|一份 AGENTS.md,决定小微是靠谱助手还是满嘴跑火车

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

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

脱敏说明 :本文做了两层脱敏------① 公司名、产品名、产品代码、接口名全部占位符化;② 意图分发表的示例不照搬真实项目的业务能力清单,而是复用本系列实战一 / 二 / 三已讲过的通用能力(「搜索产品」与「打开页面 / 接力」)来演示分发,避免暴露真实业务功能。文件定位、人设结构、分发设计、边界与兜底的思路仍可直接作模板参考。


写在前面

前三篇实战各解决「某一端怎么做」:工程怎么落地、skill 怎么写、用户点卡片进来之后怎么做。但把它们拼到一起,会冒出一个新问题:

用户说「帮我搜索 XX 型号」和「随便看看」,可能都能沾上边------谁来拍板这次到底走哪个能力、用什么口吻回答、哪些诉求该直接拒绝?

答案是每个 AI 开发模式项目里那个最容易被忽视、却处在最顶层的文件:AGENTS.md 。它不是某个 skill 的说明,而是整个 Agent 的「人格 + 总调度」------身份怎么介绍、什么意图走哪个接口(意图分发)、边界之外怎么拒绝、出错了怎么兜底,全写在这一个文件里。

这一篇的重点是意图分发:它决定了「用户一句话,模型能不能把它正确送到对的那个 skill / 接口」。围绕它展开 AGENTS.md 放在哪、怎么被加载、四个组成部分怎么写,以及三个只有踩过才知道的反直觉点。


一、AGENTS.md 是什么,凭什么在最顶层

先理清 Agent 的「三层结构」,这是理解 AGENTS.md 位置的前提:

层级 文件 回答什么问题 作用范围
顶层 AGENTS.md 我是谁?什么意图走哪个 skill?什么不做? 全局(整个人设 + 意图分发)
中层 各 skill 的 SKILL.md 这个任务内部的分流、流程、边界 单个 skill
底层 mcp.json + apis/ 能力怎么声明、接口怎么实现 单个原子接口

三层的分工可以一句话记住:AGENTS.md 决定「用不用你、用哪个、什么态度」,SKILL.md 决定「这个任务内部怎么走」,mcp.json 决定「接口长什么样」。第 4 篇讲的 SKILL.md 是「中层」,本篇的 AGENTS.md 是「顶层」。

放在哪、怎么被加载

AGENTS.md 放在 AI 独立分包的根目录(第 3 篇的 MiniAI/ 结构里那个 AGENTS.md),再由 app.config.ts 的 agent.instruction 字段指过去:

ts 复制代码
// src/app.config.ts(节选)
agent: {
  skills: [ /* ... 各 skill,见第 3 篇 ... */ ],
  instruction: "MiniAI/AGENTS.md",   // ← 整个 Agent 的人设与分发说明
},

两个硬点:

  1. instruction 指向的就是它。没有这个字段,模型拿不到人设,只能根据各 skill 的 description 自由发挥------回答风格飘忽、边界形同虚设。
  2. 尺寸 ≤ 10000 字节(内测版本数值,截至 2026-11)。它是四个 AI 文件里上限最小的(mcp.json ≤24KB、SKILL.md ≤16KB、AGENTS.md ≤10KB),因为它是每轮对话都要装进模型上下文的东西,必须精炼。

一个容易忽略的事实:AGENTS.md 的权重在「命中调优」里排在第 3 位------高于 SKILL.md、低于 skill description 和 mcp.json 的接口 description(第 10 篇详谈)。也就是说,改它对「回答靠不靠谱」影响很大,但对「能不能被选中」影响有限。别把命中率的希望全押在它身上。

AGENTS.md 的整体骨架

先把整份文件的骨架看清------它通常就四段。后面四节,我们按文件顺序把每一段代码贴出来逐行讲解:

markdown 复制代码
# 小微 Agent 行为规范

## 零、身份与服务定位            ← 我是谁、品牌别名、身份问答口径          (第二节)
## 一、能力与分发(意图 → 接口)   ← 意图 → 接口 的映射表 + 关键约束(本文重点,第三节)
## 二、失败兜底                  ← 报错 / 缺参 / 空命中 / 都不匹配 的统一口径 (第四节)
## 三、真正超范围                ← 如实拒绝、禁止硬套接口的清单            (第五节)

二、身份与服务定位:先教会模型「我是谁」

AGENTS.md 的第一段永远是「身份」。这一段看似只是自我介绍,实际承担三个作用:

  1. 给跨小程序选择层提供品牌信号:用户在对话里提到品牌别名时,平台需要把你的品牌词和你的能力对上号(第 10 篇的第 1 层选择)。
  2. 统一对外口径:用户问「你们是谁」「你们是官方的吗」时怎么答,必须写死。
  3. 划定能力边界:我们提供什么、支持什么,一句话说清。

一个脱敏后的示例(刻意用通用品牌「XX」,不涉及任何具体业务实体):

markdown 复制代码
## 零、身份与服务定位

- 我服务于「XX」小程序------XX 是面向普通用户的官方产品服务与购买平台。
  品牌别名:XX、XX 商城、XX 官方。
  我负责帮用户在本平台内找到商品、浏览页面、了解基础信息。

### 身份问答统一口径

用户问「你们是谁」「你们是官方的吗」「你们卖的是正品吗」时,
先直接文本回答,禁止调用任何原子接口、禁止出卡片。标准口径:

> 我是 XX 小程序的智能助手,XX 是本平台的官方平台。
> 具体商品、价格与售后以商品详情页和官方客服为准。

- 禁止表述:编造营业执照号 / 资质证书 / 成立时间 / 合作方关系。
- 回答完即止,不顺势引导到搜索卡片,除非用户紧接着自己给出具体商品名 / 编号。

三个细节值得单独说:

  • 品牌别名要罗列全 :XX / XX 商城 / XX 官方 都写进去。用户不会用你的全称,越接近口语的别名越要覆盖。
  • 身份问题必须「文本直答、禁调接口」:否则模型容易顺手调一个搜索接口,把「你们是谁」答成一张商品卡------文不对题。
  • 禁止编造资质信息:模型很擅长「补全」一个看起来合理的营业执照号、资质、成立年份,一旦编错就是事故。所以不光写「怎么说」,更要写「哪些不能编」。

三、能力与分发:一张「意图 → 接口」的表(本篇重点)

如果只记住 AGENTS.md 的一件事,那就是意图分发:把用户这一句话,正确送到「对的那个能力 / 接口」上。分发错了,后面 skill 写得再好、卡片再漂亮,用户拿到的都是答非所问------所以这一节是整份文件的命脉。

多能力并存时,模型每轮都要先做一次选择:这句话属于哪个能力?有没有可抽取的实体(商品名 / 编号)?抽不到怎么办?完全在能力外怎么体面拒绝?这些判断模型不会「自己想清楚」,它只会照着你给的表分拣。 表模糊,它就自由发挥:把「随便看看」硬塞进搜索接口、凭空编关键词、或拿「浏览」能力回答「你们是谁」。第 4 篇那些「卡片出不来 / 答非所问」的坑,一大半最后都回到这一层。

3.1 AGENTS.md 原文(能力与分发段,脱敏)

把这一段从上到下贴出来------分发意图就写在这张表里。示例刻意只用实战二「搜索产品」与实战三「打开页面 / 接力」这两个通用能力来演示,不引入任何真实业务功能:

markdown 复制代码
## 一、能力与分发(意图 → 接口)

> 命中下表即出「简短文本 + 卡片」;表外诉求一律如实说明暂不支持,
> 禁止硬套任一原子接口凑动作。

| 能力 | 触发(用户说) | 接口与参数 |
|------|----------------|-----------|
| 搜索产品 | 具体产品名 / 编号(「帮我搜索 XX 型号」「查 000001」) | `searchProduct(keyword=产品名/编号实体)`;命中一只即出卡接力详情,不做多选 |
| 打开首页 | 「打开首页」「回到首页」 | `openPage(target=home)`;仅首页,其他页如实说明暂不支持 |
| 逛一逛 / 浏览 | 「看看列表」「随便逛逛」「挑几个」 | `openPage(target=list)`;进浏览页,不编造关键词、不承诺具体结果 |

### 关键约束
- 有具体产品名 / 编号 → searchProduct;抽不到有效实体 → 不编关键词
- 意图模糊(「随便看看」「推荐个」)→ openPage(target=list),禁编造产品名 / 编号
- 指代不明(「那个怎么样」「刚说的那只」)→ 反问澄清,禁止猜测
- 搜索未命中 / 仅有相近结果 → 纯文本如实说明,不出卡、不接力
- 只做页面引导的接口不直接回答页内具体数据(价格 / 库存等),让用户进页面看
- 不承诺价格 / 优惠、不给购买决策建议、不透露内部实现

3.2 逐行拆解

先看表里每一行(意图 → 接口):

  • searchProduct(keyword=产品名/编号实体) ------参数是「实体」不是「原文」。这是实战二最大的坑:context.query 给的是用户原话(「帮我搜索 XX 型号」),带满了意图词;产品名 / 编号必须由模型从 inputSchema 抽取后再传进来(第 4 篇坑 2)。
  • openPage(target=home) ------「打开首页」用 target 枚举,而不是为每个页面单开一个接口。
  • openPage(target=list) ------「逛一逛 / 浏览」复用同一个 openPage,只换 target。用 target 参数收敛多个弱意图,避免为每个页面单开接口;H5 落地页仍走实战三的 WebView 承载。
  • 「命中一只即出卡接力详情,不做多选」------搜索命中就直接出卡;相近结果只做文本说明、不列一堆让用户猜(实战二相关度校验的延伸)。

再看两条写在表头的总则:

  • 「命中下表即出「简短文本 + 卡片」」------命中不是长篇大论,是一句话 + 一张卡;卡片点击交给接力(实战三)。
  • 「表外诉求一律如实说明暂不支持,禁止硬套任一原子接口凑动作」 ------这是防硬凑的总闸:表外的问题宁如实说「暂不支持」,也不许模型拉一个接口硬凑动作。

最后看「关键约束」那 6 条(逐条对应实战):

  • 实体优先走 searchProduct、抽不到别编关键词 → 治实战二「乱编关键词」的根因;
  • 模糊意图走浏览页、禁编造 → 把「随便看看」挡在编关键词之外;
  • 指代不明先反问 → 多轮补全不了实体就不猜;
  • 未命中 / 相近结果不出卡、不接力 → 拦实战二「谎称已找到」;
  • 引导接口只「打开页面」、不答页内数据 → 能力边界;
  • 不承诺价格 / 优惠、不给购买建议、不透露实现 → 合规红线。

3.3 一张「分发决策流」

光有表还不够,真正难的是边界。把判断顺序写成流程,模型分拣才稳定:

scss 复制代码
用户这句话
   │
   ├── 句子里能抽出「具体商品名 / 编号」吗?
   │        ├── 能  → searchProduct(keyword=实体)
   │        │         → 命中:出卡 → 用户点卡 → 接力详情页
   │        │         → 未命中 / 仅有相近结果:纯文本如实说明,不出卡(实战二的相关度校验)
   │        └── 不能 → 是想「逛一逛 / 打开某页」吗?
   │                 ├── 是   → openPage(target) 进首页 / 列表 / 专题页
   │                 └── 不是 → 意图模糊,反问澄清或引导到浏览页
   │
   └── 完全在能力之外 → 如实说明暂不支持,禁止硬套任一接口

这张流里有三个关键知识点,全部来自实战:

  • 「能抽实体」优先于「打开页面」 :用户给了具体名称 / 编号,就是要搜索,别给他丢一个浏览页(实战二:实体放 inputSchema 抽,context.query 只兜底)。
  • 抽不到有效实体,优先引导浏览,而不是编关键词 :这正是实战二「相关度校验」的延伸------searchProduct 没匹配上就纯文本不出卡,绝不硬塞一个相近的产品(分级匹配:精确 > 全文连续子串 > 不命中)。
  • 命中出卡 = 交给接力 :真正的页面跳转发生在用户点卡之后(实战三的 handoff / openDetailPage / WebView),AGENTS.md 只管「把话分到对的能力」,不管「怎么跳页」。

3.4 为什么写在 AGENTS.md,而不是各自 SKILL.md

因为这些约束跨能力生效:「无实体别编关键词」对搜索和浏览都成立、红线对所有接口都成立。写一遍放顶层,比每个 SKILL 抄一遍更不容易漂移------这也正是实战一说的「按用户意图拆 skill、意图内多分支用接口」。


四、失败兜底:给所有接口一个统一口径

再往下,是「出问题怎么办」。AGENTS.md 要给所有接口一个统一的兜底口径,否则每个 skill 各写各的,用户会收到风格割裂的报错话术------这是 AGENTS.md 的第 2 段代码。

4.1 AGENTS.md 原文(失败兜底段,脱敏)

markdown 复制代码
## 二、失败兜底

- 接口报错 → 简短安抚 +「请稍后再试试」,禁止立即重复调用;
  禁止复述错误详情 / 错误码 / 内部字段
- 参数缺失 / 意图歧义 → 反问澄清,不硬凑关键词
- 空命中 → 引导换关键词,禁止同词重试
- 都不匹配 → 如实告知暂不支持,礼貌请用户换种表达

4.2 逐条拆解

  • 接口报错:「安抚 + 稍后重试」是给用户看的;「禁止立即重复调用」是防止模型在失败时反复重试、放大故障;「禁止复述错误详情 / 错误码 / 内部字段」是防泄露内部实现。
  • 参数缺失 / 意图歧义:直接反问澄清,别硬猜一个关键词去调接口。
  • 空命中 :引导换关键词、禁止同词重试------同词反复重试只会一直空命中。
  • 都不匹配:诚实说「暂不支持」,礼貌请用户换个说法,而不是硬套一个接口。

这里有一个和第 7 篇(评测)直接相关的坑:兜底话术不要写成固定句式、不要限定句数。

失败时简短告知 用户「系统/入口暂时不可用、建议稍后重试」,禁止复述接口返回的错误详情 / 错误码 / 内部字段;句数与措辞由 Agent 结合具体失败场景自然组织,不限定固定句式。

如果你在 AGENTS.md 或 SKILL.md 里写了「只用一句『请稍后再试』」这种同时限定句数 + 逐字措辞的话,平台「文档质量」评测会直接判该接口缺陷------全部接口中招,文档质量直接归零(第 7 篇复盘了整个 0 分事故)。


五、「真正超范围」:把不该做的写死,比写该做的更重要

新手写 AGENTS.md 的本能是「把我能干的都列出来」。实际经验恰恰相反:把「我不能干什么」写清楚,对回答质量的提升往往更大。

原因很直接------模型有强烈的「完成任务」倾向。你不明确禁止,它就会想办法「帮上忙」:查不到实时价格就估一个、问资质就编个执照号、问详情就借别的商品类比。每一条都是幻觉 / 合规坑,也都会反过来污染第三节的意图分发(模型为了「帮上忙」而硬套接口)。

5.1 AGENTS.md 原文(真正超范围段,脱敏)

markdown 复制代码
## 三、真正超范围(如实说明暂不支持,禁止硬套接口)

- 下单 / 支付 / 退款 / 售后等交易操作(只做引导,不代办)
- 实时价格、库存、物流、涨跌幅等需要后台实时确认的数据
- 资质、牌照、成立时间、合作方关系等官方信息(引导去官方渠道,禁止编造)
- 天气、新闻、闲聊等与本平台无关的事务

5.2 逐条拆解

  • 交易不代办:只把用户引到页面,下单 / 支付 / 退款等动作让用户自己完成,AI 不越权。
  • 实时数据不直接报 :用户「按编号找到商品」可以,但不直接报实时价格 / 库存------引导点卡片进详情页看。这类「可以做 A、但不要顺手做 B」的精细边界,只有写进顶层才守得住。
  • 资质不编造:牌照 / 成立时间 / 合作方关系一律引导去官方渠道,模型「补全」一个看似合理的数字就是事故。
  • 无关事务直接挡:天气、闲聊等不属于本平台能力的,如实说不在范围。

通用的三条红线也常驻这里:不承诺价格 / 库存 / 优惠结果 、不给购买决策建议 、不透露内部实现。


六、三个反直觉点

写到这里,把踩过的、值得单独强调的经验拎出来:

  1. AGENTS.md 不是「文档」,是「运行时人设」。它每轮对话都会被喂给模型,改一句话就能改变回答风格和分流准确度。很多人把它当 README 写,写完就再没碰过------其实它是调优「回答质量」性价比最高的地方。
  2. 写「禁止」比写「能干」更能提升质量 。模型的能力上限取决于你给了几个接口,但模型的下限取决于你划了几条红线。超范围清单、口径禁令、兜底禁令,都是在下限上做加法。
  3. 身份口径必须写死,否则模型会自由发挥。资质信息被编造出来一次,就是实打实的事故;与其事后审核,不如把「不能编」写在第一屏。

七、本篇小结

  1. AGENTS.md 是顶层 :agent.instruction 指向它,管「用不用、用哪个、什么态度」;SKILL.md 管单任务内部;mcp.json 管接口。尺寸 ≤10KB,每轮都进上下文,必须精炼。
  2. 身份定位要写全写死 :品牌别名罗列全(喂给跨小程序选择层 + 意图匹配);身份问题文本直答、禁调接口;禁止编造营业执照 / 资质 / 成立时间。
  3. 意图分发是命脉:用「能抽实体 → 搜索;无目标 → 浏览页;抽不到有效实体 → 不编关键词;指代不明 → 反问」这条决策流分拣;命中即「简短文本 + 卡片」,表外禁止硬套接口。分发错了,skill 写得再好也是答非所问。
  4. 兜底口径统一且不写死句式:四类异常各有原则,话术不限定句数/逐字措辞,否则触发评测的「文档质量 0 分」。
  5. 超范围清单是下限保障:把「不能干什么」写清楚,比罗列「能干什么」更能压住幻觉与合规风险。

至此「AI 侧」三部曲(skill 编写 → 接力接收 → 人设立设)补齐。下一篇进入上线关卡:评测------通过线是多少、用例怎么写才合规,以及那个让我们文档质量直接归零的坑。


参考

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

相关推荐
颜进强13 分钟前
微信小微AI - 【实战一】工程化落地|Taro 主工程里塞进一套原生 AI 代码,我们这样让它们共存
前端·ai编程·全栈
颜进强19 分钟前
微信小微AI-【实战三】接力落地|用户点完 AI 卡片跨进小程序,那几秒才是体验的生死线
前端·ai编程·全栈
费曼学习法20 分钟前
为什么你的 Subagent 拆完反而更慢?我把 12 万 token 的任务重做了一遍
前端
颜进强25 分钟前
微信小微AI-接入模式与开通准备|两种模式选错,后面全白干——小微接入的隐藏门槛
前端·ai编程·全栈
htzyl20628 分钟前
CSS中,`:has()` 能帮你删掉的 4 类 JS
前端·css
verohh33 分钟前
(四)配置驱动与动态渲染——从固定页面到可组合的前端架构
前端
颜进强37 分钟前
认识小微|一句话就能直接调起你小程序的微信 AI,多数人第一眼就理解错了
前端·ai编程·全栈
锐影用AI做小程序44 分钟前
uni-app X + Spring Boot 做在线工具站:6 个真实踩坑与解法
前端
掘金挖土44 分钟前
前端手摸手跑路之 AI 应用开发(十二)
前端·后端