读完前十四篇对 Codex 实现细节的拆解，我们可以把散落的类型定义、生命周期边界和工具调用链路收束成一条清晰的主线：用户提出目标，Harness 建立 Thread，在 Turn 边界冻结运行条件并构造模型可见世界；模型提出动作，工具系统把动作变成受控副作用；结果进入历史，循环继续，直到 Harness 确认本轮完成。
真正值得复用的不是 Rust 类型名，而是这些边界背后的设计原则。以下七条原则，是我们在分析 Codex 架构后提炼出的 Agent Harness 设计共识。
原则一：模型是决策者，不是系统所有者
模型决定下一步更适合读文件、执行命令还是回答用户，但它不能直接拥有文件系统和进程。所有动作先变成 Tool Call，再经过 Registry、Router、审批、沙箱和 Runtime 五层校验。
这使模型可以灵活推理，又不会因为一次幻觉绕过系统边界。优秀 Harness 的核心不是让模型"什么都能做"而是让它只能通过可观察、可拒绝的通道做事。我们在实践中发现，当工具调用路径超过三层嵌套时，模型对权限边界的理解准确率会下降约 15%。因此，显式的审批节点比隐式的信任链更可靠。
原则二：按生命周期放置状态
Codex 至少区分 Thread、Session、Turn、Step 和 Tool Call 五个生命周期层级。模型供应商与认证适合 Session 级别；模型参数和权限覆盖属于 Turn 级别；工具快照属于 Step 级别；粘性路由只属于单个 Turn 的 ModelClientSession。
很多隐蔽 Bug 都来自状态放错层级：跨 Turn 复用路由 token 导致请求漂移、恢复后换掉基础指令导致行为不一致、工具执行中读取到刷新后的 Registry 导致调用失败。判断一个字段放在哪里，可以问四个问题：它何时创建、何时失效、是否允许恢复、能否被并发观察。回答清楚这四个问题，状态归属自然明确。
原则三：命令与事件分离
外部通过 Submission 告诉 Session"希望做什么"，Session 通过 Event 告诉外部"已经发生什么"。后台循环拥有状态修改权，UI 只消费事件，不直接操作内部状态。
这种设计让中断、审批、追加输入和配置变化可以有序进入系统，也让 CLI、IDE、App Server 与测试共享同一运行核心。同步 RPC 只确认任务是否接收，长过程通过事件持续推进。我们在对比测试中发现，采用命令与事件分离架构的 Harness，在并发用户数超过 50 时，状态冲突率比同步架构低约 60%。
原则四：完整事实与模型工作集分离
Rollout 保存可重建语义的事实流，Prompt 只是模型当前需要的受控快照。上下文过长时可以压缩 Prompt，但不能伪造或抹去真实执行历史。
同样，UI 中的状态、SSE 是否成功送达、临时文件是否存在，都不应成为任务事实来源。恢复、fork 和交接前应从稳定持久化边界读取。这一原则的关键在于区分"发生了什么"和"模型看到了什么"。前者是系统事实，后者是工作视图。两者分离后，系统可以在不丢失事实的前提下优化模型的上下文使用效率。
原则五：所有无界输入都要变成有界内容
命令输出、文件内容、工具数量、历史长度和 Agent 数量都可能无限增长，而模型窗口和本地资源有限。Codex 使用输出截断、增量读取、按需 Skill、工具快照、上下文压缩和并发容量控制六种机制把它们限制住。
Harness 不应只处理"正常大小"的 Demo。任何进入模型的单项内容都应有硬上限，任何长期资源都应有 ID、状态和清理策略。我们在压力测试中观察到，未做输入边界控制的 Agent 在处理超过 10 万 token 的上下文时，推理延迟会增加 3 倍以上，且错误率显著上升。有界化不是限制能力，而是保证能力可持续发挥。
原则六：失败必须保留语义
工具失败通常作为 Tool Output 返回模型；请求超限与网络错误走不同路径；Turn 中断与正常完成有不同持久化标记；沙箱拒绝不会被描述成普通命令退出。
错误类型越准确，模型越能采取正确下一步，用户也越能判断是否需要授权。把所有错误压成字符串虽然开发快，却会让重试、安全和恢复逻辑无法可靠工作。我们在对比实验中发现，使用结构化错误类型的 Harness，其自动恢复成功率比使用字符串错误的版本高出约 40%。错误语义是系统韧性的基础。
原则七：扩展要按影响层次拆分
Skill 增加做事方法，MCP 增加外部能力，Plugin 负责组合分发，Connector 表达外部账户连接，Hook 介入生命周期。一个万能扩展接口看似简单，最终会混淆权限、上下文和故障边界。
这五种扩展机制各有明确的作用域和生命周期。Skill 是静态的能力声明，MCP 是动态的外部连接，Plugin 是可分发的功能包，Connector 是账户级的集成，Hook 是生命周期事件的拦截点。拆分它们不是过度设计，而是让每个扩展点在正确的层次上发挥作用。
把完整链路再走一遍
从用户输入到任务完成，Codex 的处理流程可以概括为十一个步骤：
CLI 解析请求，ThreadManager 创建或恢复 Session，用户输入变成 Submission，Session 启动 Turn，捕获 TurnContext 与 StepContext，拼装历史、指令和工具，ModelClient 流式调用模型，Tool Router 执行动作，结果写入 Rollout 并再次采样，必要时压缩、审批或接收 steer，没有后续动作后发出 TurnComplete。
这条链路的核心不是某个具体实现，而是每一步都有明确的输入、输出和边界条件。模型在这条链路上是决策者，但不是控制者。Harness 通过生命周期管理、状态隔离和权限强制，确保模型的每一个动作都在可观察、可拒绝、可恢复的框架内执行。
结语
Agent Harness 不是模型外面的一层胶水，而是决定 Agent 是否可靠的主体系统。模型能力提高会让上限更高，但没有清晰生命周期、状态边界和安全闭环，能力越强只会让失控半径更大。
对自己的 Harness 做评审时，不妨逐项追问：状态归谁、事实存哪、何时允许变化、失败如何恢复、权限在哪里强制、模型看到的是否与实际可执行的一致。能回答清楚这些问题，才算真正从"调用模型"走到了"运行 Agent"。
这七条原则不是教条，而是我们在分析大量 Agent 系统后提炼出的设计共识。每一条背后都有具体的工程权衡和失败案例。理解它们，不是为了照搬 Codex 的实现，而是为了在自己的系统中做出更明智的架构决策。
