【实战四】给 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 的人设与分发说明
},
两个硬点:
instruction指向的就是它。没有这个字段,模型拿不到人设,只能根据各 skill 的 description 自由发挥------回答风格飘忽、边界形同虚设。- 尺寸 ≤ 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 的第一段永远是「身份」。这一段看似只是自我介绍,实际承担三个作用:
- 给跨小程序选择层提供品牌信号:用户在对话里提到品牌别名时,平台需要把你的品牌词和你的能力对上号(第 10 篇的第 1 层选择)。
- 统一对外口径:用户问「你们是谁」「你们是官方的吗」时怎么答,必须写死。
- 划定能力边界:我们提供什么、支持什么,一句话说清。
一个脱敏后的示例(刻意用通用品牌「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」的精细边界,只有写进顶层才守得住。
- 资质不编造:牌照 / 成立时间 / 合作方关系一律引导去官方渠道,模型「补全」一个看似合理的数字就是事故。
- 无关事务直接挡:天气、闲聊等不属于本平台能力的,如实说不在范围。
通用的三条红线也常驻这里:不承诺价格 / 库存 / 优惠结果 、不给购买决策建议 、不透露内部实现。
六、三个反直觉点
写到这里,把踩过的、值得单独强调的经验拎出来:
- AGENTS.md 不是「文档」,是「运行时人设」。它每轮对话都会被喂给模型,改一句话就能改变回答风格和分流准确度。很多人把它当 README 写,写完就再没碰过------其实它是调优「回答质量」性价比最高的地方。
- 写「禁止」比写「能干」更能提升质量 。模型的能力上限取决于你给了几个接口,但模型的下限取决于你划了几条红线。超范围清单、口径禁令、兜底禁令,都是在下限上做加法。
- 身份口径必须写死,否则模型会自由发挥。资质信息被编造出来一次,就是实打实的事故;与其事后审核,不如把「不能编」写在第一屏。
七、本篇小结
- AGENTS.md 是顶层 :
agent.instruction指向它,管「用不用、用哪个、什么态度」;SKILL.md 管单任务内部;mcp.json 管接口。尺寸 ≤10KB,每轮都进上下文,必须精炼。 - 身份定位要写全写死 :品牌别名罗列全(喂给跨小程序选择层 + 意图匹配);身份问题文本直答、禁调接口;禁止编造营业执照 / 资质 / 成立时间。
- 意图分发是命脉:用「能抽实体 → 搜索;无目标 → 浏览页;抽不到有效实体 → 不编关键词;指代不明 → 反问」这条决策流分拣;命中即「简短文本 + 卡片」,表外禁止硬套接口。分发错了,skill 写得再好也是答非所问。
- 兜底口径统一且不写死句式:四类异常各有原则,话术不限定句数/逐字措辞,否则触发评测的「文档质量 0 分」。
- 超范围清单是下限保障:把「不能干什么」写清楚,比罗列「能干什么」更能压住幻觉与合规风险。
至此「AI 侧」三部曲(skill 编写 → 接力接收 → 人设立设)补齐。下一篇进入上线关卡:评测------通过线是多少、用例怎么写才合规,以及那个让我们文档质量直接归零的坑。
参考
本文为实战经验整理(基于内测版本),官方能力与流程以微信开放文档及公众平台后台为准。