Agent 架构原则速查
用于设计、重构与 Code Review 时快速回忆取舍；不记录项目现状、完成进度或测试成绩。
总纲：以最少必要机制交付真实任务；事实和裁决有明确归属；新能力的代价尽量局部化，并保留未来撤退和替换的自由。
本文的“可插拔”首先指开发时的模块组合与实现替换，不要求运行时动态加载或热卸载；也不主张把所有函数都做成插件。
一、职责与裁决
- 模型负责语义，确定性系统负责客观事实。 模型理解意图、制定研究策略、综合证据；Runtime/Host 管理授权、执行状态、资源边界与真实回执。“能写一个 if”不代表代码有权判断自然语言的真实性或研究充分性。例：文本里出现“买入”不等于获得交易授权。
- 提议、批准、执行、实际效果和交付是不同的事实。 Tool Call 不等于获准；获准不等于已执行；函数返回不等于效果已提交；保存不等于用户收到。未知状态必须保留为未知，不能伪装成功或失败。
- 复杂度放在正确的 Owner，不是统统下沉 Runtime。 模型管语义，Runtime 管过程与生命周期，MCP/Tool 管可调用能力，Skill 管方法，Host/业务系统管其权威记录。例：研究 Skill 可以指导方法，但不应该维护第二份权限或预算账本。
- 真正的封装是收拢决定权，而不只是合并代码和状态。 每类事实与效果要有清晰 Owner；外围模块不得再次解释其内部状态并作影子裁决。例：有了 Publication 还允许上游预过滤正文，不算完成封装。
- 局部失败不能自动获得全局否决权。 模块只拒绝自己负责的效果；Run 的继续、恢复和终结由其生命周期 Owner 决定。例：公开引用不可用可降级链接，不应删掉独立合法正文；真实隐私、来源授权和执行权限仍须严格保护。
二、执行、恢复与交付
- 研究动态演进，避免过早固定编排。 尽量由简洁 Entry 和 Native Agent Loop 根据证据推进任务，不为所有查询强加复杂 Intent 分类、规划协议和固定阶段流水线。
- 隔离执行，不复制系统治理。 Subagent、Plugin 可以拥有独立工作上下文与局部结果，但不应另建一套 Run 授权、资源账本、生命周期或事实权威。
- Context 是有限投影，不是事实数据库。 工具结果、证据、历史与回执由其权威存储负责；模型上下文只装当前必要的可用材料。例：压缩上下文不应抹掉已提交的研究证据。
- 持久化记录已发生的事实，恢复不能重新创造事实。 恢复沿用原身份、授权、资源消耗和副作用回执；遇到 unknown 先核实，不能当作“没执行”就盲目重放。
- 预算是对可完成工作的资源承诺，而不只是计数器。 资源 Owner 统一裁决额度，区分已用、剩余和收尾所需能力；局部工具不维护影子账本。例：搜索预算耗尽，不应天然耗尽已经可以完成的最终交付。
- 生成答案不等于交付答案，系统成功不等于用户任务成功。 模型生成、发布接受、持久保存、客户端收到、研究结论正确是不同层次。验收最终看真实任务是否完成，而不只看工具调用、返回码或测试通过。
三、功能代价与持续演化
- 坚持最小充分机制。 新增模块、状态、校验或 Prompt 规则前，先解释它带来什么不可替代的收益，能删除或封装哪些旧复杂度；不要为了假想的扩展提前拆出多层接口。
- 独立能力优先具备开发时的引入、撤退、替换能力。 尽量在有限的组合入口接入实现；移除能力或把 A 换成 B，不应迫使无关模块修改。例：替换 Sandbox Provider，不要求 Research 知道它的具体类名。
- 依赖少量明确的公共契约，不维护四处散落的私有契约。 契约由明确 Owner 定义；消费者依赖能力与必要事实，不依赖提供者的内部标志、异常类别或隐藏调用顺序。避免“名义上是插件，实质上所有模块都要理解它的特殊分支”。
- 评估正常路径税和行为副作用。 一个只处理少数异常的机制，可能让所有任务增加 Token、延迟、状态组合、失败点；工具与 Prompt 的变化还可能让模型过度调用、过早放弃或更保守。让代价尽量由实际使用该能力的路径承担。
- 对经验性收益用反事实验证，而不是只证明功能可用。 对 Prompt、Skill、Reviewer 等效果取决于模型行为或真实任务质量、且值得额外验证的变更，按风险选择针对性观察或启用/停用对照，比较完成率、质量、成本与异常行为；不为可由架构不变量直接推导的 Owner 收拢强加质量 A/B。必要的授权、安全与真实业务不变量不能为做对照而关闭。
- 验证强度与决策不确定性及错误代价相匹配。 能由权威归属、系统不变量和确定性契约推导的设计，依靠工程判断、Code Review 与必要的边界回归，验证实现是否符合设计，不要求统计实验；依赖模型随机行为、实际研究质量或用户效果的判断，再按影响范围、错误代价与可撤退性选择直接小步迭代、定向测评或正式对照。例：收拢四散否定权，核对发布与权限边界即可；通用 Prompt 的大范围效果不明确时，才值得重复真实任务比较。验证本身也有研发路径税，只在预期净收益为正时加码，不设所有改动必做 A/B 的统一门槛。
新功能评审四问
- 归属： 新能力掌握哪些事实与决定？是否复制已有 Owner 的裁决？
- 演化： 引入、撤退、替换分别要改哪些模块？是否让私有契约向外扩散？
- 代价： 不使用它的正常任务承担什么成本？是否改变模型的行为倾向？
- 验收： 哪些最小充分证据能证明设计和实现正确？若主张经验性收益，是否值得用真实任务对比？必要的局部失败、无关路径和合法拒绝边界是否得到验证？
最终判断：好的架构不是功能最多，而是新增能力有净收益、旧机制能撤退、全局依赖不随功能数量失控。