Appearance
Agent 设计哲学与决策框架
方向定位：Agent 工程的"价值观 + 决策树"双合一文档——既回答"为什么这样做"（克制哲学、铁律、反模式纪律），也回答"怎么选 A 还是 B"（立项 / 架构 / 技术栈 / 运行时的可操作决策框架）。本方向不涉及具体实现机制（→ 其他方向），但任何 Agent 项目从立项到上线的"价值观锚点 + 决策入口"都集中在这里。 当前版本：v1.0（合并自《Agent 设计哲学与铁律》v0.2 + 《Agent 决策框架手册》v0.3） 首次构建：2026-05-15 最近更新：2026-05-20 来源数：4 篇（横切提炼自 5 篇现有体系化文档 + 2 篇原始素材 + 多智能体协作调查长文 + Anthropic CU 最佳实践）
方向定位
本方向研究两个相互咬合的核心问题：
- Why（哲学）：Agent 工程实践中哪些原则是不可妥协的？为什么"克制比技巧更重要"？
- Which（决策）：从立项到上线的每个关键岔路口，该如何快速做出可辩护的决策？
边界：
- 包含：跨场景复用的设计原则（Anthropic 3 原则 / Barry 3 铁律 / 克制哲学 / ACI 投入论）、反模式纪律、立项哲学、人机分工范式；以及 8 类决策框架（要不要 Agent / 复杂度递进 / 单 vs 多 / 中心化 vs 去中心化 / 手搓 vs 框架 / NLU vs LLM / MCP 分层 / 反思 vs 评估）
- 不包含：具体的架构形态实现（→ Agent 架构与协作模式方向）、工具/记忆/评估机制细节（→ 对应方向）、工程落地的代码与配置（→ Agent 工程实践与落地方向）
- 与相邻方向的区别：相邻方向回答"How"与"What"；本方向回答"Why"与"Which"——是 Agent 工程的"操作系统层"和"导航总图"
知识图谱
- 哲学纲领（Why）
- Anthropic 3 原则：Simplicity / Transparency / ACI
- Barry 3 铁律：4 问筛场景 / 3 组件简单 / Agent 视角
- 阿里 OpenClaw + 郝建业派别：工程实现顺序 + 三大底层短板
- 核心哲学命题
- "Demo 不算落地，进生产系统才算落地"
- "克制比技巧更重要"——奥卡姆剃刀
- "复杂度只有在可证明改善结果时才该加"
- "约束不是限制，而是放大器"
- "Humans steer. Agents execute."
- ACI 投入论：工具描述/参数名/错误反馈 = 接口设计；Poka-yoke > 教模型不犯错；工具优化 > prompt 优化
- 决策框架（Which）
- 立项决策：4 问判断清单、复杂度递进决策树、预算反推法
- 架构决策：单 vs 多 Agent 四信号、中心化 vs 去中心化、五种工作流模式、多智能体 8 步决策树
- 技术栈决策：手搓 vs 框架矩阵、传统 NLU vs LLM 矩阵、MCP 接入分层、反思 vs 评估
- 运行时决策：Advisor Strategy 介入时机、Stopping Condition 三档、工具失败四类处理
- 思维练习：把自己塞进 Agent Context Window、让 Claude 看 Claude
- 反模式纪律：过早 multi-agent / 框架依赖症 / 上下文越长越好 / 工具失败让 agent 崩 / 靠模型聪明
第一章 Why——为什么这样做 Agent
本章回答 Agent 工程的"价值观与铁律"——所有具体方法论、架构选型、工程实践都跑在这套哲学之上。当你在两个看似合理的方案之间犹豫时，回到这些铁律往往能立刻得出答案。
1.1 Anthropic 构建 Agent 的 3 条核心原则
Anthropic 在《Building Effective Agents》文末把数十个客户共建经验浓缩成 3 条不可妥协的原则：
| # | 原则 | 含义 | 反例 |
|---|---|---|---|
| 1 | Maintain simplicity | Agent 本质就是"LLM 在循环里用工具"，不要为了显得复杂而加抽象层 | 用 5 层框架封装一个本该 50 行写完的任务 |
| 2 | Prioritize transparency | 显式展示 agent 的规划步骤，让人类能看到它在想什么、为什么这么决定 | 黑盒输出最终结果，调试时无从下手 |
| 3 | Carefully craft ACI | 投入 HCI 同等的工程精力到工具文档和测试上 | 工具描述一两句话就交付，期待模型自己脑补 |
核心反直觉：Anthropic 与数十个客户团队共建后得出的结论——最成功的实现都没用复杂框架，而是用"简单可组合的模式"。"Success in the LLM space isn't about building the most sophisticated system. It's about building the right system for your needs."
1.2 Barry 构建 Agent 的 3 条铁律
Barry 在 AI Engineer Summit 把 Anthropic 的客户共建经验进一步收敛成 3 条铁律：
| # | 铁律 | 一句话 |
|---|---|---|
| 1 | 别什么都用 agent 做 | 用 4 问判断清单逐条筛场景（具体清单见第二章 2.1） |
| 2 | 尽可能保持简单 | Agent 只有 3 个组件（环境 / 工具 / system prompt），迭代阶段别加复杂度 |
| 3 | 用 agent 视角去想 | 把自己塞进 10-20K token 的 context window，立刻能看到 agent 缺什么信息 |
与 Anthropic 3 原则的关系：Anthropic 3 原则是"设计完成后的检查清单"，Barry 3 铁律是"从立项到迭代的工作纪律"——两者是同一套哲学在不同阶段的展开。
1.3 "Demo 不算落地，进生产系统才算落地"
这是郝建业派别对 Agent 工程的核心判断标准。当前 Agent 行业的常见误区：
- Demo 跑通就宣告成功 → 真到生产系统短板暴露
- 实验室 benchmark 优秀 → 生产环境上下文/工具/记忆全是坑
- 一个任务能跑 → 100 个并发任务直接崩
底层判断：从 demo 走到生产系统的护城河是"工程的全栈深度"——包括但不限于记忆系统、安全、Harness、可观测性、ACI 设计。少一项都不算落地。
对项目立项的启示：评估一个 Agent 项目时，"能跑 demo"是必要条件不是充分条件。真正的评估锚点应该是"在生产负载/异常/对抗场景下是否仍能稳定工作"。
1.4 "克制比技巧更重要"——Agent 工程的奥卡姆剃刀
横跨 Anthropic 与阿里两个派别的共识哲学。所有具体表现都收敛到同一原则：
- 架构层面：能用 workflow 不用 single agent，能用 single agent 不用 multi-agent
- 复杂度层面：能用单次 LLM 调用不用 chain，能用 chain 不用 router
- 框架层面：能用 LLM API 起步不用框架
- 多智能体层面：能让一个 Critic Agent 解决的不用 N 个 Critic 并行
为什么克制比技巧重要：每加一层复杂度都要承担——更高 token 成本、更高延迟、更难调试、更可能复合错误。而这些代价往往在 demo 阶段感受不到，到生产环境放大 100 倍。
Anthropic 原话："Consistently, the most successful implementations weren't using complex frameworks or specialized libraries. Instead, they were building with simple, composable patterns."
1.5 "复杂度只有在可证明改善结果时才该加"
这是 PM/架构师立项时的最高约束。它派生出的工作纪律是按"单次 LLM 调用 → workflow → agent"复杂度递进升级，每升一级必须有可证明的收益（递进决策树见第二章 2.2）。
每加一层复杂度都要承担：
- 更高 token 成本（按倍数累积）
- 更高延迟（用户感知的真实痛感）
- 更难调试（每多一层抽象 = 一层错误来源）
- 更可能复合错误（链路越长，错误率越接近 1 - (1-p)^n）
反例：客服系统每单 10 美分预算 → 单次任务 token 上限约 3-5 万 → 常见情况用 workflow 就够，硬上 agent 会破产。
1.6 ACI 投入要比照 HCI 的工程纪律
ACI（Agent-Computer Interface）是 Agent 时代新引入的设计维度，对应 HCI 在传统软件中的位置：
| 维度 | HCI（传统） | ACI（Agent 时代） |
|---|---|---|
| 用户 | 人类 | LLM / Agent |
| 界面 | UI / UX | 工具描述 + 参数 schema + 错误反馈 |
| 设计师 | 设计师 + 前端 | PM + 后端 + 工具作者 |
| 检验 | 用户测试 | 模型在 workbench 多样本测试 |
| 工程比例 | 整体开发约 30-50% | Anthropic 实测：SWE-bench agent 工具优化时间 > 整体 prompt 优化时间 |
核心思想：Agent 的"用户"不只是人类，还有 LLM 自己。工具描述、参数名、错误反馈——这些都是 PM 应当像设计前端界面一样仔细打磨的"接口"。
Anthropic 原话："One rule of thumb is to think about how much effort goes into human-computer interfaces (HCI), and plan to invest just as much effort in creating good agent-computer interfaces (ACI)."
1.7 "约束不是限制，而是放大器"——多 Agent 协作哲学
多 Agent 工程的核心哲学，与单 Agent 工程的"自由派"形成强烈对比。
单 Agent 倾向：自由度越大、模型选择越多，能力越强。 多 Agent 现实：自由度越大、协作越混乱、调试越困难、生产可控性越差。
约束的几个具体形态：
- Spec-first 两段式人工确认：让 plan 必须人工签字才能 execute
- allowedPaths 软边界：限制每个 Agent 的修改范围
- claim 系统：避免多 Agent 抢占同一资源
- Observer Agent 频率限制：避免观察者本身失控
哲学要义：约束让多 Agent 的"协作行为"变得可预测、可调试、可回滚——没有约束的"自由协作"在生产系统里几乎一定崩盘。约束不是为了限制能力发挥，而是为了让能力沿着可控路径放大。
1.8 "Humans steer. Agents execute."——人机分工新范式
来自阿里 OpenClaw 团队的提炼。这句话定义了 Agent 时代工程师工作的本质重塑：
传统范式：工程师写代码 → 代码执行 → 工程师调试 Agent 范式：工程师定义意图 + 边界 + 约束 → Agent 执行 → 工程师 review
对工程师角色的影响：
- 大量"键盘操作"被 Agent 替代（编码、测试、文档）
- "判断力"无法替代——目标设定、边界划定、异常处理决策、价值判断
- 工程师工作从"做事的人"变成"管事的人"
对组织的影响：
- 大量个体工程师承担起类似 tech lead 的判断职责
- 团队规模可能不变但单兵产出量级上升
- 评估工程师的标准从"代码量"转向"判断质量"
1.9 思维练习 1：把自己塞进 Agent Context Window
来自 Barry 的实操技巧——所有 Agent debug / 设计阶段都应做一遍。
练习规则：
- 你只有 10-20K token
- 你只看得到一份 system prompt + 工具描述 + 最近 N 个 observation
- 你不知道任何"用户视角"看得到但 agent 视角看不到的信息
Barry 的 computer use agent 案例：
- 拿到一张静态截图 + 一段写得糟糕的任务描述，你点击一下
- 点击执行的 3-5 秒里，相当于你闭着眼睛操作电脑
- 睁开眼，看到下一张截图——你刚做的事可能成功，也可能把电脑关机了，你不知道
练习能立刻挖出的需求：屏幕分辨率信息、推荐动作 + 限制、进度状态、"上一步做了什么、结果是什么"的回放线索。
制度化落地：PRD / Spec 评审环节强制走一遍 agent 视角，把"用户视角才看得到、agent 视角看不到"的信息缺口列出来。
1.10 思维练习 2："让 Claude 看 Claude"的元调试惯例
Barry 团队高频使用——把 system prompt / 工具描述 / Agent 完整 trajectory 直接喂给 Claude，让它指出问题。
| 给 Claude 看的东西 | 问它什么 |
|---|---|
| system prompt | 里面有歧义吗？你能照着做吗？有没有矛盾的指令？ |
| 工具描述 | 这个工具的参数够不够？是不是缺什么？参数名是否容易误用？ |
| 完整 trajectory | 你为什么在这一步做了这个决定？我应该补什么信息让你做得更好？ |
| 失败的对话历史 | 这个对话哪一步开始走偏？为什么走偏？ |
与练习 1 的关系：两者互补——人脑做"塞进 context"练习 + Claude 做自评——覆盖人类视角和模型视角各自看不到的盲区。
1.11 Poka-yoke（防呆）工具设计法
来自 Anthropic SWE-bench agent 的真实经验——改参数让"犯错变难"，而不是依赖模型不犯错。
Poka-yoke 具体设计实践：
- 强制结构化输入：不接受自然语言模糊指令，要求 JSON Schema 严格约束
- 不可能歧义的参数名：
file_path优于name，absolute_path优于path - 错误的默认值不存在：要么必填要么明确合理默认值
- 副作用前置 confirmation：删除/写入类工具默认 dry-run，需显式
confirm=true才执行 - 错误反馈包含修复线索：错误信息直接告诉模型"应该怎么改"，而不只是"出错了"
衡量标准：拿一个"刚见到这个工具的模型"试 100 次，如果错误率 > 5%，工具设计有问题。
1.12 工具优化 > Prompt 优化的工程顺序
Anthropic 反直觉结论：构建 SWE-bench agent 时，优化工具花的时间比优化整体 prompt 还多。
| 优化对象 | 收益边际 | 调试可见性 |
|---|---|---|
| Prompt | 边际递减快（30→70 分容易，70+ 极难） | 改了不一定知道改对没改对 |
| 工具描述 | 边际更稳定（每次改进直接反映在调用准确率） | 工具调用日志直接可见 |
| 工具参数设计 | 一次改对可永久消除一类错误 | Poka-yoke 后整类错误消失 |
调试时的标准排查顺序：
- 工具描述是否有歧义
- 工具参数是否有 Poka-yoke 空间
- system prompt 是否遗漏关键约束
- 模型能力是否本身不够
反例：一上来就怀疑模型能力 → 换更强的模型 → 问题依旧 → 才发现是工具定义不清楚。
绝大多数"Agent 不好用"的案例，根因都在工具设计，不在模型能力。
1.13 Show, Don't Tell — Teach Mode 示教回放设计哲学
来自 Anthropic CU 最佳实践（2026-05-13）。当 Agent 面对复杂 UI 工作流时，录制一次人类操作让 Agent 回放比写一份详细的文字指令更高效——这是"给 Agent 看什么"比"给 Agent 说什么"更重要的又一个实证。
核心思想：用工作流录制代替文字指令。人类做一遍流程 → 系统录制每一步的截图 + 动作 + 选择器 + 坐标 + 视口尺寸 → Agent 在相同或相似场景中回放。
WorkflowStep 数据模型（每步记录 6 个字段）：
| 字段 | 作用 |
|---|---|
| action | 动作类型（click / type / scroll / select 等） |
| selector | 目标元素定位（CSS selector / XPath） |
| coordinates | 屏幕坐标（x, y） |
| screenshot | 带标注的截图（标记目标元素位置） |
| viewport_dimensions | 当前视口尺寸（适配分辨率差异） |
| description | 人类可读的步骤描述 |
三种回放模式（渐进放权）：
| 模式 | 行为 | 适用场景 |
|---|---|---|
| Strict | 严格复现每一步操作 | 合规审计、重复性高的表单填写 |
| Adaptive | 目标一致但允许路径偏差 | UI 布局变化时自适应 |
| Goal-oriented | 仅参考示教理解目标，自主规划路径 | 跨版本 / 跨平台迁移 |
设计哲学要点：
- 与 §1.9 思维练习的呼应：Teach Mode 正是"把自己塞进 Agent Context Window"的产品化——不是让 PM 写文字描述 Agent 该做什么，而是直接给 Agent 看人类做什么
- 示教 > 指令的本质：工作流录制是"上下文工程"的极致形态——用截图序列 + 结构化标注取代自然语言，消除指令歧义
- 反模式：把 Teach Mode 用于不稳定的 UI——如果 UI 每次都变，录制的示教很快过时。Adaptive/Goal-oriented 模式是对冲手段
（来源：Anthropic CU 最佳实践博客"Teach mode — show, don't tell"节，2026-05-13）
第二章 Which——决策框架
本章提供 8 类决策入口的可操作判断框架。决策结果指向哪个方向的哪个章节，每个决策框架背后的"为什么这么决"由第一章哲学层回答。
2.1 立项决策一：4 问判断清单——要不要用 Agent
来自 Barry 在 AI Engineer Summit 的提炼。所有 Agent 项目立项时必须逐条回答的第一道关：
| # | 问题 | 怎么用 | 反信号（别用 agent） |
|---|---|---|---|
| 1 | 任务复杂度 | 任务在"模糊问题空间"才用 agent | 能画出完整决策树 → 写 workflow，每个节点单独优化 |
| 2 | 任务价值 | 任务能 cover token 成本 | 客服系统每单预算 10 美分 → 3-5 万 token 上限，常见情况 workflow 就够 |
| 3 | 关键能力 de-risk | 主路径每一步模型都做得好 | 某一步是瓶颈，不会 fatal 但成本和延迟翻倍 |
| 4 | 错误成本 + 错误发现难度 | 错误便宜或容易发现，敢放手 | 错误贵 + 难发现 → 加 read-only / human-in-the-loop（但会限制 scale） |
判断锚点：如果你看到这个问题第一反应是"不计 token，把活干完"——这才是 agent 的甜蜜点。
经典四项全中的甜蜜点：Coding Agent——任务模糊 ✓、价值高 ✓、模型能力强 ✓、unit test + CI 让错误容易发现 ✓。
使用纪律：4 问要逐条问，缺一不可。任何一条是"反信号"都应该首选 workflow 而非 agent。
2.2 立项决策二：复杂度递进决策树——Anthropic 三档原则
单次 LLM 调用 + retrieval + few-shot
↓ 不够用？
五种 Workflow 模式
↓ 不够用？
Agent关键纪律：
- 每一档先用尽再升级，不要跳级
- 升级必须有可证明的收益（不是"理论上更强"，而是"实测指标提升"）
- 升级带来的成本（token / 延迟 / 调试难度）要进入决策权衡
Anthropic 原话："Workflows offer predictability and consistency for well-defined tasks, whereas agents are the better option when flexibility and model-driven decision-making are needed at scale."
与 4 问的关系：4 问回答"能不能用 agent"，本决策树回答"如果不上 agent，停在哪一档"。
2.3 立项决策三：预算反推法——把任务价值转成复杂度上限
来自 Barry 的实操技巧。
反推步骤：
- 业务侧给出"每单可接受成本上限"（如客服每单 10 美分）
- 按当前模型的 token 价格反推 token 预算（如 Sonnet 4.6 约 3-5 万 token）
- 按 token 预算判断可承载的复杂度档位：
- < 3K token → 单次 LLM 调用
- 3K - 30K token → workflow（2-5 步链式）
- 30K - 100K token → 小型 agent 或复杂 workflow
100K token → 完整 agent + 上下文管理
实战案例：
- 客服每单 10 美分 → 3-5 万 token → 常见情况用 workflow 就够，agent 只跑长尾
- 编程任务每次 1 美元 → 30 万 token → 完整 agent 没问题
- 内部数据分析每次 5 美元 → 150 万 token → 不在乎复杂度上限
使用纪律：所有 Agent 项目立项时都应做这个反推——很多"看起来应该上 agent"的项目，反推后发现 token 预算根本不够。
2.4 架构决策：单 Agent vs 多 Agent + 中心化 vs 去中心化
给定一个已确定要上 agent 的任务，架构层面需要做两个正交决策。
第一步：单 Agent vs 多 Agent
触发"多 Agent"的 4 个信号（命中 ≥ 2 个考虑多 Agent）：
- 任务可天然拆分为多个独立子任务（如不同领域 / 不同技能）
- 子任务可并行执行能显著降低延迟
- 不同子任务需要不同的 system prompt / 工具集，混在一起会冲突
- 任务复杂度超过单 Agent 的上下文窗口容量
第二步：中心化 Orchestrator vs 去中心化
| 维度 | 中心化（Orchestrator-Worker） | 去中心化 |
|---|---|---|
| 可控性 | 高，调度逻辑集中 | 低，依赖 Agent 间协议 |
| 调试难度 | 低，一个 Orchestrator 一目了然 | 高，分布式状态难追踪 |
| 生产可用性 | 当前唯一可用路径 | 几乎不用，仅学术 |
| 扩展性 | 中，Orchestrator 是瓶颈 | 高，理论可线性扩展 |
当前判断：中心化 Orchestrator-Worker 是 Multi-Agent 工程的唯一生产路径。
→ 详细机制见 Agent架构与协作模式 概念 5、方法 1
2.5 架构决策补充：五种工作流模式速查
来自 Anthropic《Building Effective Agents》。把这 5 种模式吃透，PM 评审技术方案时就有了"共同语言"：
| # | 模式 | 何时用 | 结构 | 典型案例 |
|---|---|---|---|---|
| 1 | Prompt Chaining（链式） | 任务可干净拆分成固定子任务，用延迟换准确性 | 顺序步骤 + 中间程序化 gate | 写文档大纲 → 校验 → 写文档 |
| 2 | Routing（路由） | 任务有明确几类，分开优化更好 | 先分类 → 分发到专门下游 | 简单问题 → Haiku，复杂 → Sonnet |
| 3 | Parallelization（并行） | 子任务可并行 / 多视角投票提升置信度 | Sectioning 或 Voting | 多 prompt 评估漏洞 |
| 4 | Orchestrator-Workers（编排-执行） | 子任务无法提前预测，由协调者动态分派 | 中心 LLM 拆任务 → workers 并行 → 综合 | Coding agent 多文件改 |
| 5 | Evaluator-Optimizer（评估-优化） | 反馈能可证明提升质量 + LLM 能给有用反馈 | 生成 → 评估 → 改进循环 | 文学翻译、复杂搜索 |
评审常用语：
- 听到"并行跑 3 个 LLM 做评估"→ Voting，问投票阈值
- 听到"大模型决定调哪个工具"→ Routing，问分类准确率
- 听到"主 agent 拆任务给子 agent"→ Orchestrator-Workers，问子任务边界
→ 详细机制见 Agent架构与协作模式 概念 2
2.6 架构决策补充：多智能体 8 步选择顺序决策树
设计任何多智能体方案前，按这个顺序逐条问——多数"看起来需要多 agent"的任务会在前 3 问就被劝退。
| 步 | 问题 | 决策 |
|---|---|---|
| 1 | 单 agent 能不能做？ | 小改动 / 强顺序 / 需求模糊 → 单 agent。能做就先别拆 |
| 2 | 主上下文会不会被污染？ | 长日志 / 大搜索 / 跨目录阅读 → 只读 explorer 或 subagent |
| 3 | 子任务能不能独立？ | 独立 → 星型 fan-out；强依赖 → pipeline 串行 |
| 4 | 结果是否必须在本轮返回？ | 必须 → fork/join；不必 → background job；跨天/重试/等人类 → durable queue / Kanban |
| 5 | worker 是否需要互相挑战？ | 只分头查 → 星型；需互相质疑 → team mesh |
| 6 | 是否会并行写文件？ | 会写 → 先写 ownership（按目录/模块/测试文件分边界）；分不出来 → 回 Step 3 改 pipeline |
| 7 | 是否需要入口隔离？ | 多渠道/多身份/多权限 → Gateway routing |
| 8 | 失败后如何恢复？ | retry / block / handoff / 子任务证据——没有这些约束就不要上长程多 agent |
核心纪律：先决定调度方式，再决定状态放哪里；先决定上下文和权限边界，再决定拓扑；先决定谁 reduce，再决定开几个 worker。
与 2.5 的关系：五种工作流模式是 Anthropic 视角的"形态菜单"；本决策树是从触发-拓扑两轴视角给出的"8 步入口"——两者互补。
→ 详细机制、四大 Harness 触发-拓扑对比矩阵、Delegation Contract 模板见 Agent架构与协作模式 方法 10、概念 17-19
2.7 技术栈决策一：手搓 vs 框架选型矩阵
来自阿里 OpenClaw 团队的工程经验。手搓与框架不是非此即彼，而是按阶段动态调整：
| 阶段 | 推荐 | 理由 |
|---|---|---|
| POC / 单任务原型 | 直接 LLM API 起步 | 框架的多层抽象会遮蔽 prompts 和 responses，调试困难 |
| 多 Agent 协作初期 | 框架 + 核心手写 | 框架管编排，核心逻辑（如 system prompt 迭代）必须手写 |
| 规模化生产 | 框架托底 + 核心模块完全手搓 | 框架在排查/运维/规模化三方面有痛点，核心模块必须自掌控 |
| 极致优化阶段 | 几乎完全手搓 | 框架的抽象层在性能/可控性上都是阻碍 |
Anthropic 的明确建议：直接用 LLM API 起步，很多模式几行代码就能写完。如果要用框架，必须看懂底层代码——"对底层假设错了"是客户最常见的错误来源。
反模式：选 LangChain 就一直跟着它升级、被框架推着走——这是框架依赖症。
→ 详细分析见 Agent工程实践与工具生态 方法 1
2.8 技术栈决策二：传统 NLU vs LLM 选型矩阵
意图识别场景下两种方案的选择：
| 维度 | 传统 NLU（BERT 类微调） | LLM（Function Calling） |
|---|---|---|
| 数据需求 | 大量标注数据 | 少量 few-shot 或零样本 |
| 泛化能力 | 弱，新意图需重新训练 | 强，prompt 改改就能加意图 |
| 准确率（封闭域） | 高（90%+） | 中高（85-92%） |
| 准确率（开放域） | 低 | 高 |
| 成本 | 训练贵推理便宜 | 训练免费推理贵 |
| 可控性 | 高，输出可枚举 | 中，需要 JSON Schema 约束 |
| 延迟 | 低（10-50ms） | 高（500-3000ms） |
选型决策树：
- 高并发 + 封闭域 + 容忍标注成本 → 传统 NLU
- 长尾意图多 + 快速迭代 + 容忍延迟 → LLM
- 混合方案（推荐）：传统 NLU 做高频意图分类（90%+ 流量）+ LLM 兜底长尾
→ 详细矩阵见 Agent工程实践与工具生态 方法 4
2.9 技术栈决策三：MCP 接入分层判断
来自 Anthropic 2026-04 的"分层互补"博客。给定一个外部能力，应该用哪一层接入？
| 层 | 适用场景 | 例子 |
|---|---|---|
| API | 高频、低延迟、纯数据 | 数据库查询、内部 RPC |
| CLI | 本地工具、文件系统、shell 操作 | git / kubectl / 文件读写 |
| MCP | 云端工具、第三方生态、需协议标准化 | Notion / Slack / GitHub MCP Server |
| Skills | 需要"教模型方法"而非"调用工具" | "如何写 PRD"、"如何做代码 review" |
| Plugin | Skills + MCP 的打包分发 | 完整的"客服 Agent Plugin" |
分层判断流程：
- 是纯数据查询吗 → API
- 是本地操作吗 → CLI
- 是云端工具且不需要"方法"吗 → MCP
- 主要是"教方法"吗 → Skills
- 需要打包分发吗 → Plugin
注意：MCP 并非"all in one"方案，三大生产痛点（Token 暴涨 4-32 倍、Schema 臃肿、缺乏编排）说明它不该被滥用。
→ 详细分析见 Agent工程实践与工具生态 方法 5
2.10 技术栈决策四：反思机制 vs 评估机制选型
两套机制看似都是"让 Agent 知道做得对不对"，但适用场景完全不同：
| 维度 | 反思机制（Self-Refine） | 评估机制（Evals） |
|---|---|---|
| 时机 | 任务执行过程中 | 任务执行之后 |
| 目的 | 让 agent 改进当前输出 | 度量 agent 整体能力 |
| 颗粒度 | 单次任务/单步 | 跨任务、跨版本 |
| 成本 | 增加单次任务成本（多次调用） | 离线运行，不影响在线 |
| 决策驱动 | 是否回头修改 | 是否上线、是否回滚 |
选型决策：
- 你要让 agent 当下做得更好 → 反思机制
- 你要让 agent 下个版本做得更好 → 评估机制
- 两者完全可以并行使用，互不冲突
反思机制内部二选一：单 Agent 自反思（成本低，有"自洽陷阱"）vs 多 Agent Critic（质量高，独立审查员）。生产建议：高质量场景用多 Agent Critic，常规场景用单 Agent 自反思。
→ 详细机制见 Agent评估与反思机制 概念 5、方法 2
2.11 运行时决策一：Advisor Strategy 介入时机
来自 Anthropic 的大小模型协作方案。在同一 Agent 内部用小模型主执行 + 大模型按需介入：
何时介入大模型：
- 决策点（routing / dispatch）：选下一个工具、决定子任务划分
- 复杂推理：跨多步证据综合、反直觉判断
- 质量校验：关键输出在交付前再次审视
- 错误恢复：遇到 ambiguous 错误时升级判断
何时不介入：纯执行步骤（如格式转换、字段提取）、高频/低价值任务、模型已表现稳定的环节。
预算控制：用 max_uses 参数限制大模型介入次数，避免无限升级。
Anthropic 实测数据：性能 +2.7%、成本 -11.9%。
API 级工程细节（Anthropic CU 最佳实践 2026-05-13 补充）：
- 20 轮提醒 nudge：对话超过 20 轮后，模型会收到系统提醒鼓励使用 advisor——解决"小模型忘了问大模型"的问题
- Orphaned block 清理：如果 advisor 调用结果未被使用（如被中断），系统自动清理残留 block，避免 context 污染
- Caching 策略：advisor 调用结果可被 prompt cache 缓存——多轮对话中重复使用同一 advisor 判断不会重复计费
- 与 Computer Use 的协同：CU 场景推荐 Sonnet 4.6 执行 + Opus 4.7 advisor，Sonnet 负责机械点击（精度高），Opus 负责决策判断（推理强）——是 CU 场景下成本效益最优的模型组合
→ 详细机制见 Agent工程实践与工具生态 概念 12、方法 6
2.12 运行时决策二：Stopping Condition 三档设计
所有自主 Agent 必须设置 Stopping Condition，三档组合使用：
| 档 | 触发条件 | 用途 |
|---|---|---|
| max_iter | 循环次数上限（如 50 步） | 兜底防失控 |
| budget | Token / 时间 / 钱预算上限 | 经济兜底 |
| checkpoint | 关键节点 human-in-the-loop | 质量兜底 |
设计原则：
- 三档全部都要，不能只设一档（max_iter 单档可能被巨型单步耗尽预算）
- 触发后的行为要明确：是中断报错、还是降级 fallback、还是 human approval
- 把 stopping condition 暴露给 agent 自己感知（如告诉它"还剩 5 步预算"），让它能主动调整策略
反例：让 agent 自由循环 → 资源失控、无限循环、API 账单爆炸。
2.13 运行时决策三：工具失败四类处理策略
调用工具失败时 agent 不应该崩，按以下四类策略处理（来自 DeepResearch 78%→91% 的实战经验）：
| 错误类型 | 处理策略 |
|---|---|
| 暂时性失败（网络、超时） | 把错误信息写回 Observation，让 agent 自己决定重试或换工具 |
| 参数错误（schema 不匹配） | 错误信息明确告诉 agent "参数 X 应该是 Y 格式" |
| 权限/资源不足 | 写回 Observation，让 agent 选择 fallback 或求 human |
| 工具本身不存在 | 引导 agent 用替代工具或承认能力边界 |
核心原则：try/except 把错误写回 Observation，把决策权交还给 agent。不要在工具层做"重试 agent"——会带来新的复杂度（重试几次？重试失败怎么办？）。
→ 详细案例见 Agent工程实践与工具生态 方法 2
2.14 决策框架之间的关系
立项 → 架构 → 技术栈 → 运行时——前置决策约束后续决策的空间。
- 立项 决定"上不上 agent"——决定了后续所有决策的存在意义
- 架构 决定"单/多/中心化"——影响技术栈选择和运行时配置
- 技术栈 决定"手搓/框架/接入层"——影响运行时的可控性边界
- 运行时 决定"stopping condition / advisor / 失败处理"——决定生产可用性
当不知道选哪个时，默认选更简单的那个（哲学层第 1.4 节的延伸）：
- 单 vs 多 Agent → 单
- 中心化 vs 去中心化 → 中心化
- 手搓 vs 框架 → 手搓
- 反思 vs 评估 → 评估（先离线优化再考虑在线反思）
反信号往往比正信号更可靠：评审时优先核对反信号，任何一个反信号触发 → 优先用 workflow。
第三章 案例库
案例 1：SWE-bench 绝对路径修复——Poka-yoke 的标杆案例
任务：Anthropic 构建 SWE-bench agent，需要 agent 修改多个文件解决 GitHub Issue。
早期问题：工具用相对路径 → agent 在执行过程中切换目录后，对文件的引用错乱。
直觉解法：在 system prompt 里反复强调"请使用绝对路径"。实测：错误率虽降但未消除。
最终解法：把工具改成强制要求绝对路径——相对路径直接拒绝，并返回"请使用绝对路径"的错误提示。结果：整类错误消失。
教训：
- 工具优化的收益比 prompt 优化大得多
- "让 agent 不能犯错"优于"教 agent 不要犯错"
- 工具设计的精雕细琢应享受与 prompt 同等的工程关注
案例 2：Coding Agent 四项全中——4 问框架的甜蜜点
背景：为什么 Coding 是当前所有 Agent 公司的主战场？
4 问逐条对照：
- 任务复杂度：✓ 模糊问题空间——同一个 bug 修复方式可以有无数种
- 任务价值：✓ 程序员单小时成本 50-200 美元，agent 每次任务花 1-2 美元完全划算
- 关键能力 de-risk：✓ 模型在 code 任务上已达到接近资深工程师水平
- 错误成本 + 错误发现难度：✓ unit test + CI 让错误立刻可见、且代码改错通常可回滚
四项全中 → Coding Agent 是 Agent 应用的"甜蜜点"。
对比反例（客服 Agent）：
- 任务复杂度：部分✓（长尾问题模糊，高频问题简单）
- 任务价值：✗（每单仅 10 美分预算，token 上限紧）
- 关键能力 de-risk：✓
- 错误成本 + 错误发现难度：✗（错误 expensive + 用户可能不会反馈）
结论：客服 Agent 不应该是"完整 agent"，应该是"workflow + agent 兜底"的混合架构。
案例 3：客服按"成功解决次数计费"——商业化哲学信号
事件：多家客服 Agent 公司从"按 token 计费 / 按调用次数计费"转向"按成功解决次数计费"。
为什么这是哲学信号：
- 这种收费方式只有当公司对 Agent 解决率有强信心时才敢推
- 商业模型从"卖能力"转向"卖结果"
- 暗含的承诺：Agent 真的能在客服场景做到与人类替代或超越
这种商业模式成立的 4 个前置条件：
- 对话流天然（客服场景）+ 需要外部信息和动作（拉用户数据、订单历史）
- 工具能拉取关键数据 + 执行动作（退款、改地址）
- 成功度量清晰（用户定义的"解决"）
- 错误可承受（人工兜底）
对 PM 的启示：评估"该不该上 agent"时，看商业模式能否承受"按结果付费"——能就上 agent，不能就用 workflow。
案例 4：Computer Use Agent 闭眼操作——Agent 视角的极致案例
Barry 在 AI Engineer Summit 的演示——把人放进 computer use agent 的体验：
- 你拿到一张电脑桌面静态截图 + 一段语焉不详的任务描述（如"帮我把这个文件传给 Sarah"）
- 你决定点击屏幕某个位置
- 点击执行的 3-5 秒里，你不能看到任何东西——相当于闭着眼睛
- 睁开眼，看到下一张截图——你刚刚的操作可能成功，也可能完全跑偏
- 循环
Barry 想说明的核心：agent 缺信息的程度超过开发者的想象。需要的不只是"任务描述"，而是：进度状态、环境信息（分辨率/可用动作/当前焦点）、推荐路径、错误回滚线索。
通用启示：所有 Agent 任务在设计时都应做一遍"闭眼操作"练习——通常会立刻暴露 5-10 个明显缺失的信息项。
案例 5：DeepResearch 工具失败处理 78%→91%——克制哲学的工程兑现
任务：DeepResearch 在执行研究任务时频繁遇到工具调用失败（如 search 工具超时、爬取失败）。
早期方案：工具失败 → 抛异常 → agent 流程中断 → 任务失败率 22%。
克制哲学下的修复：
- 不引入"重试 agent"、不引入"错误恢复 agent"
- 只做一件事：把工具失败用 try/except 包住，错误信息写回 Observation 让 agent 自己决策
- agent 看到失败信息后，可能换工具、换参数、跳过、改任务边界
结果：任务成功率从 78% → 91%。
为什么克制反而好：
- 引入"重试 agent"会带来新的复杂度（怎么判断该重试？重试几次？）
- 把决策权交还 agent 自己，反而触发了它的"错误恢复"能力
- "工具失败时不崩"应该是 Agent 工程的第一优先级，但实现方式应该是最朴素的
案例 6：模型路由的成本优化——Routing 模式实战
任务：客服系统每天处理 10 万次查询，按 token 计费成本占运营 30%+。
Routing 决策：
- 80% 简单 / 常见问题 → Claude Haiku 4.5（成本约 1/10）
- 20% 困难 / 罕见问题 → Claude Sonnet 4.5（能力强）
实测收益：总成本 ↓ 60%+，复杂问题准确率保持不变。
决策框架核对：任务有明确几类？✓；单一类型优化不该影响其它？✓；分类准确率可接受？✓ → 适用 Routing 模式。
案例 7：MCP 接入分层判断实战
场景：团队要给 Agent 增加"读取 Notion 文档"能力，怎么接入？
分层判断：
- 是纯数据查询吗？✗（需要复杂 schema + 权限）
- 是本地操作吗？✗（Notion 是云端）
- 是云端工具且不需要"方法"吗？✓ → 用 MCP
进一步判断"是否值得用 MCP"：
- Notion 调用频率：每天 50 次
- Token 开销估算：每次调用 schema ~2K tokens → 每天 100K tokens 额外
- 结论：低频可接受，高频要警惕 MCP Token 暴涨问题
反例对比：给 Agent 加"读取本地 git 状态"能力？是本地操作 ✓ → 用 CLI（git status），不应该用 MCP，否则徒增复杂度。
案例 8：阿里隔夜自优化闭环——反思 vs 评估的协同案例
任务：钉钉文档 MCP Agent 优化。
架构：
- 反思机制（在线）：Coding Agent 自己改完代码后，Self-Refine 检查一次
- 评估机制（隔夜）：评测 Agent 跑全量测试集，给出分数 + 失败案例
- 闭环：评测 Agent 把失败案例反馈给 Coding Agent，第二天 Coding Agent 据此改进
实测分数演进：90.7 → 97.4 → 99.1（三轮收敛）。
决策框架核对：
- 这是 Evaluator-Optimizer 模式的工业级实现
- 反思（在线）+ 评估（离线）协同使用，不冲突
- 三轮收敛说明：适合 90+ 分数往上爬，不适合 0-90
案例 9：Anthropic Advisor Strategy 性能数据
架构：Sonnet 主执行 + Opus 关键节点 advisor。
Advisor 介入条件（max_uses 3 次）：
- 任务起始：让 Opus 判断"该用什么策略"
- 关键决策点：让 Opus 判断"该不该升级到 multi-step"
- 输出前：让 Opus review 一次结果
实测数据：性能 +2.7%（端到端任务成功率）；成本 -11.9%（相比全程用 Opus）。
关键洞察：把"大模型能力"从执行层下沉为"按需调用的决策层"——这是 Agent 时代的"大小模型分工"标准范式。
案例 10：四大 Harness 触发方式对照——评审多智能体方案的速查表
背景：团队成员提出"用多智能体做 XX"时，PM/架构师如何 30 秒内判断方案是否合理。
速查矩阵：
| 提案表述 | 实际属于哪类触发 | 关键追问 | 适配 Harness |
|---|---|---|---|
| "让用户决定要不要并行" | 显式触发 | 用户在什么场景下会主动写"use parallel subagents"？写不出来就是伪需求 | Codex |
| "Agent 根据任务复杂度自动调用专家" | 语义触发 | 每个 subagent 的 description 能不能被改写成"何时调用我"？写得像愿望就会乱叫人 | Claude Code 普通 subagent |
| "不同渠道进不同助手" | 路由触发 | 入口绑定规则是否清晰？认证/权限/工具集是否分级？ | OpenClaw Gateway |
| "任务可能跨天/需要等人类反馈" | 队列触发 | 状态存哪里？谁拉起 worker？失败如何 retry？handoff 如何记录？ | Hermes Kanban |
评审三连问：
- 触发是哪一类？四类对应四种工程实现，混用就是混乱
- 拓扑是哪一种？星型 / 链式 / 树型 / 网状 / Gateway / Durable——拓扑选错，所有下游决策都错
- 谁是 reducer？没有明确的 reducer = 多 agent 只是"多份意见"
反例对照：
| 提案 | 问题 |
|---|---|
| "用 Hermes 做一个 PR review，几秒钟出三个 reviewer 的意见" | 短任务上 Kanban 笨重——应该用 Codex 显式 fan-out 或 Claude Code subagent |
| "用 Codex 多 agent 跑一个两天的调研报告" | 长任务用一次性 subagent 会丢状态——应该用 Hermes Kanban |
| "让 Agent Teams 互相 review 后写修复 patch" | 多 worker 写同一片代码无 ownership——应该先并行只读定位，再串行写 patch |
对方案评审的启示：当一个多智能体方案在"触发方式 / 拓扑形态 / reducer 责任"这三个维度有任何一个含糊，几乎可以断定它会在第二轮真实任务里翻车——把这三个维度问清楚，比讨论"用哪个框架"重要得多。
→ 完整对比矩阵见 Agent架构与协作模式 概念 19
案例 11：反模式速查表节选——纪律性反例
来自阿里 OpenClaw 团队的工程经验沉淀：
| 反模式 | 现象 | 后果 | 正解 |
|---|---|---|---|
| 过早上 multi-agent | 任务还没单 agent 跑通就拆 5 个 worker | 协作混乱、调试地狱 | 先把单 agent 跑稳，再考虑拆 |
| 框架依赖症 | 选 LangChain 就一直跟着升级、被框架推着走 | 排查/运维/规模化三重痛 | 核心手写，周边借用 |
| 上下文越长越好 | 把所有可能用到的信息全塞进去 | Context Rot，模型注意力稀释 | 分层管理 + 按需加载 |
| 工具失败让 agent 崩 | 任何工具异常直接 raise | 任务大面积失败 | try/except 写回 Observation |
| 靠模型聪明 | 工具定义模糊期待模型脑补 | 调用错误率高且难以归因 | Poka-yoke 工具设计 |
| 跳过 stopping condition | 让 agent 自由循环 | 资源失控、无限循环 | 必须设 max_iter + budget |
| 一次性写完美 prompt | 一开始就想出"完美 system prompt" | 反复改、覆盖式无穷尽 | 测试驱动迭代 |
速查表的价值：这些反模式都是"看起来合理但实际致命"的——打印贴在工位上，能避免 80% 的早期错误。
关键洞察（合并版）
哲学侧（Why）
- Agent 的最佳实现往往是最朴素的实现：技术决策应该问"我能用多简单的方案"，而不是"我能用多复杂的方案"
- 复杂度是技术债务，每加一层都要还：demo 阶段不疼，生产阶段加倍——立项纪律是按"单次 LLM → workflow → agent"逐级升级
- ACI 是 Agent 时代的"前端工程"：工具描述、参数名、错误反馈不是辅助产物，是核心产出
- Poka-yoke > 教模型不犯错：让 agent "不能犯错"比让它"不犯错"靠谱得多
- Agent 视角才是 debug 的真正起点：把自己塞进 Agent Context Window 一次，能挖出 5-10 个用户视角看不到的信息缺口
- 工具优化优先级 > Prompt 优化优先级：绝大多数"Agent 不好用"的案例，根因都在工具设计，不在模型能力
- "Humans steer. Agents execute." 重塑了工程师角色：评估工程师的标准从"代码量"转向"判断质量"
决策侧（Which）
- 决策框架的最大价值在"团队共同语言"：方案评审从"主观偏好对撞"变成"框架要点核对"
- 立项决策的优先级是绝对的：立项错了，后面所有优化都是在错误的方向上加速
- 决策树合集 ≠ 决策手册式僵化：8 个决策框架是"判断起点"，不是"判断终点"
- 反信号比正信号更可靠：评审时优先核对反信号，任何一个反信号触发 → 优先用 workflow
- 当不知道选哪个时，选更简单的那个：单 vs 多 / 中心化 vs 去中心化 / 手搓 vs 框架 / 反思 vs 评估，默认都选更简单一侧
待探索问题
哲学侧：
- ACI 标准化路径：HCI 经过 50 年发展形成了一套行业共识——ACI 是否会形成类似的标准化设计原则？
- 自主度与可控性的伦理边界：是否会演化出类似汽车 L0-L5 的"Agent 自主度评级"？
- 简单性原则的边界：随着模型能力跃迁，是否会出现"复杂架构反而更简单"的拐点？
- ACI 投入的产品化：是否会出现"工具描述质量检测器"、"Poka-yoke 自动建议器"等工程化产品？
- "Agent 视角思维练习"的工具化：是否能做成一个 IDE 插件，自动模拟"agent 此时此刻看到的状态"？
- 多 Agent 时代的"约束设计学"：约束作为放大器的具体设计语言尚未形成体系——是否需要"约束模式目录"？
决策侧：
- 决策框架的冲突解法：当不同框架给出相反建议时（如 4 问通过但预算反推不够），应该怎么仲裁？
- 决策框架的跨场景泛化：8 个决策框架在医疗/法律/金融/不同地区下是否需要调整？
- 决策的"机器辅助化"：是否能做"立项 Wizard"，输入任务描述自动给出 4 问得分 + 推荐复杂度档位？
- 框架版本化：当 Claude 5.x 发布后，4 问清单的"关键能力 de-risk"边界会显著外推——决策框架是否需要随模型版本演进？
- 决策框架的"反例库"：本手册多数案例是"框架适用"的正例——是否需要建立"框架不适用 / 边界外"的反例库？
来源索引
- Anthropic《Building Effective Agents》（Erik S. & Barry Zhang，2024-12-19）—— 原文
- 提供：3 条核心原则、五种 workflow 模式、ACI 设计原则、Augmented LLM 基础构件、复杂度递进决策树、SWE-bench 案例、模型路由案例、Poka-yoke 案例
- 注：原始素材笔记已根入本文档及现有 5 篇方向，原笔记已删除
- Barry《构建 Agent 三铁律》（AI Engineer Summit 2025）
- 提供：3 条铁律、4 问判断清单、Agent = 3 组件 + 循环、把自己塞进 Context Window 思维练习、让 Claude 看 Claude 调试法、预算反推法（10 美分客服锚点）、Coding agent 四项全中分析、3 个开放问题
- 注：原始素材笔记已根入本文档及现有 5 篇方向，原笔记已删除
- 多智能体协作调查长文（2026-05）
- 提供：多智能体 8 步选择顺序决策树、四大 Harness 触发-拓扑对照矩阵、评审三连问
- 横切提炼自现有 5 篇体系化文档：
- Agent架构与协作模式：克制哲学、约束是放大器、控制权归属、架构选型两步框架、五种控制模式、Single vs Multi 触发信号
- Agent工程实践与工具生态：Demo 不算落地、工具失败处理、反模式速查表、Humans steer Agents execute、手搓 vs 框架矩阵、Stopping Condition 设计
- Agent工程实践与工具生态：ACI 三代演进、决策与执行分离、Poka-yoke 工程实践、传统 NLU vs LLM 矩阵、MCP 接入分层、Advisor Strategy 实测数据
- Agent记忆系统：Memory = 决策通道
- Agent评估与反思机制：评估系统本身的问题比 Agent 出问题更难发现、反思 vs 评估机制选型、阿里隔夜自优化案例
演进记录
- 2026-05-15 v0.1（哲学篇） — 首次构建《Agent 设计哲学与铁律》，由 /route-knowledge 路由分析触发；横切提炼自 5 篇现有体系化文档 + 2 篇原始素材，定位为 Agent 工程的"价值观与铁律"维度集中沉淀。
- 2026-05-15 v0.1（决策篇） — 首次构建《Agent 决策框架手册》，与设计哲学方向呼应（哲学方向回答 Why，决策方向回答 Which）。
- 2026-05-19 v0.2（哲学篇） — 清理与决策框架手册的轻度重叠：4 问清单具体判断标准移交决策框架手册，本方向只保留"为什么要先筛场景"；复杂度递进决策步骤移交决策框架手册，本方向只保留"为什么必须按这个顺序递进"。
- 2026-05-19 v0.2（决策篇） — 由 /route-knowledge 整合"多智能体协作调查"长文触发：新增多智能体 8 步选择顺序决策树、四大 Harness 触发方式对照实战。
- 2026-05-19 v0.3（决策篇） — 与设计哲学方向同步去重：复杂度递进决策树补加哲学源头跳转引用；方向定位段补加"决策框架背后的为什么"指向哲学方向的说明。
- 2026-05-20 v1.0（合并） — 《Agent 设计哲学与铁律》v0.2 与《Agent 决策框架手册》v0.3 合并为《Agent 设计哲学与决策框架》，整合 Why 与 Which 两个维度。去重项：Anthropic 3 原则、Barry 3 铁律、单 vs 多 Agent 信号、MCP 分层判断、复杂度递进决策树等跨篇重复内容合并为单一表述；保留差异化要点：克制哲学叙事、Barry 3 铁律的 ACI 投入论、四问决策树、复杂度递进、手搓/框架判据矩阵、所有具体决策表。结构采用"第一章 Why / 第二章 Which / 第三章 案例库"三段式。