设计原理
持续修订的思考草稿。
本文建立 Agent 研究与工程的基本思考体系，应当独立自洽；其他专题从这里展开具体问题、机制与方案。
核心期望：从决定下一步到完成目标
Agent 不断决定下一步，但我们希望它持续围绕目标完成任务。
每一步合理，不保证整体完成。 Agent 设计要解决的，就是怎样让一步步行动最终达成目标。
设计四问：条件、推进、实现、评价
要把这个期望变成一个 Agent，需要先想清楚完成任务的条件，再组织推进过程、选择实现机制，最后检验结果。由此得到四个相互衔接的问题：
| 问题 | 需要考虑什么 |
|---|---|
| 完成任务需要具备什么？ | 所需的智力、行动能力与上下文，以及目标、约束和完成依据 |
| 怎样持续推进到完成？ | 如何保持目标、记录进展、选择行动、利用反馈，以及处理失败和判断结束 |
| 工程上怎样实现？ | 从工程位置选择实现方式，明确模型、程序和人的分工 |
| 怎样评价和改进？ | 如何判断任务效果、衡量速度与成本，根据执行证据定位问题并验证改进 |
设计时，从目标推导实现；排查时，从结果追溯原因。
人机协作：明确期望与掌握边界
准确表达期望，共同澄清需求
结果不符合预期，不一定是 Agent 做不到，也可能是我们没有把想要的结果说清楚。 判断能力之前，先检查：我们心中的目标、偏好和判断标准，是否已经成为 Agent 能获得的信息？
最近的使用中，有两个例子体现了这种差别：
- 界面设计：给出风格倾向或设计变量。 让 Agent 自由设计时，结果可能不合心意；明确风格倾向，或给出颜色、字体、间距等 design tokens（设计变量），它就能做出更符合预期的界面。例如，可以用“采用瑞士风格，强调网格、对齐、留白与清楚的字体层级”表达方向，也可以直接指定背景色、字体和间距值。前者借助风格名称传达整体倾向，后者把具体选择交代清楚，都减少了 Agent 猜测偏好的空间。
- 文档写作：点明已有的表达规范。 我们也观察到，提醒 Agent 参照 ASD-STE100（简化技术英语规范）的表达原则，就能得到较好的改写，不必逐句教它怎样表达。
document-writing的《文档写作原则》引用了这份规范，中文写作借用其中的句子结构原则，英文词汇与时态规则不直接套用。
这两个例子提示我们：模型可能已经具备相应能力，准确的风格或规范名称能帮助它运用已有知识。让它自行选择方向，与让它按明确方向执行，对能力的要求不同。
准确描述需求的关键，是把影响结果的期待表达出来。 有时一个恰当的名称就能传达许多要求，需要精确控制时再补充具体参数或示例。已有明确偏好，就说明偏好与标准；尚未确定方向，就通过候选方案、小样和反馈共同澄清，而不是让 Agent 猜测，再用未曾表达的标准判断它。Agent 也应主动帮助澄清关键需求，不要求用户一次写完规格。
人掌握系统演化，Agent 承担执行
把工作交给 Agent 的同时，人仍需掌握系统的目标、核心概念、边界和关键取舍，并保有审查与收回改动的能力。 这一点同样适用于 Skill、提示词设计和 Vibe Coding；不要求人亲自处理每个实现细节。
在已理解、已认可的边界内，可以充分委托 Agent 实现、修改和验证。新增概念、规则、依赖或工作流程时，人需要理解它为什么存在、与现有体系如何衔接，以及增加了什么长期成本，再决定是否接受。
局部改动都有理由，不代表整体值得保留。 当人已经说不清某个机制的必要性，只能依赖 Agent 自己解释和验证时，应先理解、整合或删减，再继续扩展，避免系统复杂度超出人的掌握。
测试能够验证行为效果，但不能替人决定系统应该如何演化。即使测试通过，也仍需判断新增复杂度是否值得承担。
基本原理：智力、能力、上下文
先看完成任务需要具备什么。Agent 要根据掌握的信息作出判断，并把判断变成行动，因此可以从智力、能力和上下文三个角度检查必要条件。
| 角度 | 核心判断 |
|---|---|
| 智力 | 能否理解目标、推理、规划、选择行动、根据反馈纠错 |
| 能力 | 是否存在可执行的行动路径；单个能力不足时能否组合；权限、环境与可靠性是否允许 |
| 上下文 | 决策所需信息是否进入上下文，是否准确、相关、及时；是否不足或过载 |
判断依赖信息，行动依赖能力。 信息不足可能表现为判断错误，知道怎么做也不等于能执行。
尤其在上下文上，信息存在、系统保存、模型本轮可见，是三件事。 检查信息是否充分，要看它是否真正进入了当前决策。
工程实现：让行动与反馈持续走向目标
具备这些条件之后，还要把一次次判断和行动组织成持续推进的过程，让行动结果成为下一步的依据：
目标与当前状态 → 判断下一步 → 行动 → 反馈 → 更新状态与判断。
这个循环要持续围绕目标推进，就需要回答：
- 目标：怎样记住目标和约束，避免行动跑偏？
- 进展：怎样知道已完成什么、还差什么？
- 恢复：失败后，怎样选择重试、换路、等待或求助？
- 结束：凭什么判断任务已完成？
工程位置
这些问题明确了推进过程需要承担的责任。落实时，要决定哪些交给模型判断、哪些由程序保证、哪些需要人参与，再从以下工程位置选择实现方式或排查问题：
| 工程位置 | 要辨别的问题 |
|---|---|
| 模型 | 理解、推理、规划与指令遵循是否满足任务要求，速度和成本是否可接受 |
| 核心机制 | 组织与推进方式是否适合任务，包括但不限于核心循环、多Agent组织方式 |
| 运行时 | 执行能否持续，异常后能否恢复 |
| 工具 | 缺能力、接口难用、执行失败，还是返回的结果有问题 |
| 上下文管理 | 信息有没有找到、保留并正确送到决策处 |
| 自反馈 | 能否观察真实结果、发现偏差、验证完成 |
同一种表现可能有不同原因，先定位原因，再选择改动。
每个方案都要说清：解决什么问题、依赖什么条件、付出什么代价。
结果三指标：速度、成本、效果
机制能运行，是否就达到了最初的期望？需要回到整个任务，看它完成得怎样，以及用了多少时间和成本。
| 指标 | 评价什么 | 从哪些因素分析 |
|---|---|---|
| 速度 | 完成任务用了多久 | 推理延迟、推理步数、执行时长 |
| 成本 | 完成任务花费多少 | 模型费率、上下文长度、推理步数、工具/API 调用成本 |
| 效果 | 是否完成、质量如何、是否遵守约束、能否稳定做到 | 智力、能力、上下文 |
我们最终追求的是任务效果，影响效果的是智力、能力、上下文及其配合；工程实现则通过配置和组织这三者来改善效果。速度和成本，是取得这些效果的代价与约束。
局部收益不等于整体收益。 每次改动都要检验整个任务的速度、成本和效果。
在此基础上，继续阅读设计地图，把这些判断展开为可选的优化方向，再进入对应专题。