# Agent 设计教条

> 给产品与业务读。**一条一句，不解释。**
> 完整论证与图示见 [agent-architecture.md](./agent-architecture.md)。

| | |
|---|---|
| **性质** | 通用设计原则，与具体业务无关 |
| **用法** | 评审时逐条对照；争议时引用编号 |
| **评级** | ★★★ 地基（不这样做必出问题，事后修改等于重做）· ★★ 必做（会出问题，但可后补）· ★ 看信号（有明确信号再做，提前做是浪费） |

---

## 只记五条

1. **能写成规则的交程序，写不出规则的才交模型。**
2. **模型报的每个数字都要指得到来源。**
3. **不可逆的动作必须有人点头——因为必须有人负责。**
4. **让人审四百条，等于没人在审。**
5. **提示词是最弱的手段，永远最后用。**

---

## A · 人、模型、程序的分工

| 级 | | 教条 |
|---|---|---|
| ★★★ | **A1** | 能写成规则的交程序，写不出规则的才交模型。判据是「能不能写成规则」，不是「谁能做」。 |
| ★★★ | **A2** | 模型报出的每个数字，都必须能指到**本轮**某次工具返回。⛔ 不许从上文抄、不许估、不许自己算派生量（百分比、差值、交叉人数）。<br>⚠️ 判据是「**数字要有锚**」，不是「不给数字」——模型的算力在变强，但「引用了没有来源的数」和「跨轮串用旧条件下的数」跟算力无关。 |
| ★★★ | **A3** | 不可逆的动作必须由人确认。理由不是模型会错，是必须有人负责。 |
| ★★★ | **A4** | 责任不可委托。「AI 决定的」不是一个解释。 |
| ★★ | **A5** | 明细直接呈现给人，不经过模型。 |
| ★★ | **A6** | 让人审四百条等于没人在审。每一步都要收敛规模，落到人面前的判断压到十位以内。 |
| ★★ | **A7** | 人的注意力是三方中最稀缺的资源，只花在只有人能做的判断上。 |
| ★ | **A8** | 模型变强只移动「模型与人」的分界，不移动「模型与程序」的分界。 |

## B · 模型的自主

| 级 | | 教条 |
|---|---|---|
| ★★★ | **B1** | 主线是给能力，不是加限制。不要用固定流程替换模型的判断。 |
| ★★ | **B2** | 「我不知道」必须是一个合法答案。不确定就停下来问，不要猜。 |
| ★★ | **B3** | 给模型验证手段，比给它规则有效。 |
| ★ | **B4** | 不要按阶段藏工具——走错一步之后它就无法自己纠回来。 |

## C · 可靠性

| 级 | | 教条 |
|---|---|---|
| ★★★ | **C1** | 防错分三级：让错误不可能 ≫ 让错误可见可撤 ≫ 事后校验。只能靠第三级实现的，多半是上游设计有问题。 |
| ★★★ | **C2** | 全程留痕、可回放。没有它，之后所有排查都是盲的。 |
| ★★★ | **C3** | 每条防错措施都要标明是「弥补模型」还是「业务要求」。前者随模型变强要拆掉，后者永远保留。 |
| ★★ | **C4** | 提示词是最弱的手段，永远最后用；而且规则越多，每条被遵守的概率越低。 |
| ★★ | **C5** | 没有回归测试，质量就是随机游走。判定看它做了哪些动作，不看它说了什么话。 |
| ★★ | **C6** | 批量动作必须可整体撤销。 |

## D · 身份与权限

| 级 | | 教条 |
|---|---|---|
| ★★★ | **D1** | 身份由登录决定，不由模型或提示词决定。提示词从来不是安全边界。 |
| ★★★ | **D2** | 权限不同的角色不能共用一个会话。上下文是单向的，进去的数据不会因为一句话就消失。 |
| ★★★ | **D3** | 模型不传就不会越权的参数，不要让它传。 |
| ★★ | **D4** | 角色不同，能看到的工具也要不同。看不见比看见了被拒更安全。 |
| ★ | **D5** | 同一套实现按身份参数化即可，不必做成两个 agent。 |

## E · 给模型看什么

| 级 | | 教条 |
|---|---|---|
| ★★★ | **E1** | **按量级决定给原文还是给摘要**：几十条给原文（摘要是有损的，损失的往往正是后面要追问的那部分）；几百条以上只给数量 + 入口；**量级未知时先取数量，再决定取不取**。 |
| ★★★ | **E2** | 给了摘要就必须给「怎么取到明细」，两者缺一不可。 |
| ★★ | **E9** | 多轮对话必须带上完整会话脉络，**但要分层带**：工具调用带「名字+关键参数+结果摘要」，大载荷只带 id + 一句话，失败只带错因。 |
| ★★ | **E3** | 任务状态存在库里，不存在对话里。对话只是当轮的工作台。 |
| ★★ | **E4** | 脏数据在源头就别产生，而不是事后清理。 |
| ★★ | **E5** | 对话历史只追加，不修改、不重排——这直接决定响应速度和成本。 |
| ★★ | **E6** | 固定不变的内容放前面，每次都变的放后面。当前时间这类东西绝不能写进固定部分。 |
| ★ | **E7** | 同一份数据换个呈现形式，模型的准确度会变；这件事几乎零成本，值得试。 |
| ★ | **E8** | 材料太多时，派一个只读助手去看，只把结论带回来。 |

## F · 工具

| 级 | | 教条 |
|---|---|---|
| ★★★ | **F1** | 工具的粒度等于用户会说的一句话。 |
| ★★★ | **F2** | 每个选项列表都要给全，并永远留一个「不确定」。缺一个值，模型必然填错，而且不会报错。 |
| ★★ | **F3** | 规则写在工具说明里，比写在提示词里管用。 |
| ★★ | **F4** | 错误提示要写成模型能据此改正的话。 |
| ★★ | **F5** | 每加一个会改数据的工具，先回答「它怎么知道自己做对了」。 |
| ★★ | **F6** | 写操作必须可重复执行而结果不变——模型会重试。 |
| ★★ | **F7** | 界面要的数据和模型要的数据分开返回。 |
| ★★ | **F8** | **高频做专用，长尾留一个受控的兜底工具。** 专用工具的名字就是意图，选错的空间小；没有兜底则未预见的需求只能回「做不到」。兜底的参数必须是枚举化的维度，⛔ 不能是自由查询语句。 |
| ★★ | **F9** | 每个列表类工具都要有「只回数量」的轻量对应物 —— 先问有多少，再决定取不取。 |
| ★ | **F10** | 只在特定场景才需要的解读规范，随该工具的**返回值**下发（`_guide`），⛔ 别常驻在工具说明或提示词里。这是按需加载最便宜的形态：零往返、必然到达。 |

## G · 表达与引导

| 级 | | 教条 |
|---|---|---|
| ★★ | **G1** | 可选的下一步由程序算出，模型只负责挑选和措辞。 |
| ★★ | **G2** | 模型不得建议系统做不到的事。 |
| ★★ | **G3** | 没有实质下一步时，不要凑一句建议。 |
| ★★ | **G4** | 预设默认值是在替人做决定，归程序管，且必须偏安全一侧 —— **默认永远是「不动」**。 |
| ★★ | **G5** | **布局可以交给模型，数据不行。** 模型写结构 / 样式 / 图表类型和占位符，真值在渲染时注入。⛔ 别让它把数据逐字抄进产物。 |
| ★★★ | **G6** | 给模型**结构化事实**，不要给成品句子；措辞由它组织，写作规范集中写一处。<br>⚠️ 成品句子有固定形状，模型学会形状就能凭空背出来（而且看不出真假）；结构化事实编不出来。⛔ 「照抄」也浪费了模型唯一不可替代的能力。 |
| ★★ | **G7** | 强引导的节点由程序确定性判定，⛔ 不由模型判断哪条该提。 |
| ★★ | **G8** | 引导节点**只陈述事实，不给建议**；选项中性并列；不阻塞用户直接完成。 |
| ★★ | **G9** | **有实际后果的节点必须全亮，⛔ 不许截断。** 防噪音靠**分层**（需处置的展开、纯信息的折叠），不靠丢弃 —— 藏起一条，用户就不知道有东西卡着。 |
| ★★ | **G10** | 引导选项做成**可直接点击执行的动作**，⛔ 不是让人照着打字；自由输入只作兜底。<br>⚠️ 打字 → 模型理解 → 翻译成动作，这条链每一环都可能错；点击是确定性的。两条路必须收敛到**同一个动作契约**。 |
| ★★ | **G11** | 「下一步做什么」必须是**确定性可答**的：当前状态 + 未处置的节点 + 默认路径，⛔ 不由模型即兴发挥。由此推出的下一步永远不会指向系统做不到的事。 |

## H · 要不要上

| 级 | | 教条 |
|---|---|---|
| ★★★ | **H1** | 任何手段进门前三问：解决什么问题、这个问题现在有多严重（有数据吗）、有没有更便宜的解法。答不出第二问就是在赶时髦。 |
| ★★ | **H2** | 清单是用来过一遍的，不是用来全打勾的。不做可以，但要知道自己没做。 |
| ★★ | **H3** | 为从未被测量过的问题写防御，就是过度设计。 |
| ★ | **H4** | 结构化的数据不要用语义检索——查询语言本身就是检索。 |
| ★ | **H5** | 「记不下」通常说明缺一张表。先建表，别做记忆。 |
| ★ | **H6** | 不要让模型自己积累经验并固化成规则——没法调试，出问题查不出是哪一条学坏的。 |
| ★ | **H7** | 只在出现第二个入口、或已列入能力开放计划时，才把工具做成通用封装。 |

---

## 一页速查

| 主题 | ★★★ |
|---|---|
| **分工** | A1 规则归程序 · A2 数字要有锚 · A3 不可逆动作过人 · A4 责任不可委托 |
| **自主** | B1 给能力而非加限制 |
| **可靠** | C1 防错三级 · C2 全程留痕 · C3 标明措施归属 |
| **权限** | D1 身份由登录定 · D2 角色不共用会话 · D3 越权参数不给模型 |
| **输入** | E1 按量级给原文/摘要 · E2 摘要配指针 |
| **工具** | F1 粒度=一句话 · F2 选项给全留兜底 |
| **表达** | G6 给事实不给成品句子 |
| **取舍** | H1 进门三问 |
