第二十五章：给自己的 Harness 写六份架构决策

25.1 先写约束，再选结构

架构决策不必很长，但应能回答：问题是什么、有哪些约束、选择了什么、为什么，以及何时重新评估。源码研究提供候选模式，自己的任务决定采用哪一种。

下面六份缩略记录以“单用户、本地文件修复、教学验证”为条件。若你的条件是远程多人协作或不可信输入，不能原封不动套用结果。

选择：模型只提供完整回复协议，宿主拥有工具与验收。理由：测试可以稳定注入失败，更换模型不会绕过策略。代价：需要维护事件解析与能力转换。重新评估条件：真实提供方需要增量工具调度，此时应补充更严格的完成与回退契约。

选择：教学实现顺序执行。理由：先把身份、权限、日志和恢复做清楚，避免把竞态引入第一个实验。代价：独立读取不能并行加速。重新评估条件：测得工具等待占主要耗时，且能表达并发安全与资源屏障。

借鉴 DeepSeek 的保守并发分类和 Pi 的有序结果，是下一阶段方案；不要只把 for 循环替换成 gather 就认为完成并发设计。DeepSeek Harness · index.ts L1309–1323 Pi · agent-loop.ts L644–658

选择：完整回复先落盘，工具开始先于副作用，结果随后结算。理由：恢复时能区分待执行与未知。代价：日志写入成为关键路径，仍不能消除外部动作与日志之间的不确定窗口。

重新评估条件：外部工具提供幂等键、事务或可查询操作 ID，可以实现更细恢复。否则坚持 unknown 停止，不用模型补猜缺少的事实。

选择：最终模型文字之后运行 acceptance。理由：完成应依据目标状态。代价：需要为任务类型编写评分器。重新评估条件：任务属于开放式创作时，增加人工确认或明确质量标准，而不是默默删除验收。

选择：大结果保存在受控附件，模型看到预览与哈希。理由：控制上下文体积，又保留完整证据。代价：附件生命周期、访问控制和失效处理需要管理。重新评估条件：工作跨机器恢复，必须把本地路径升级为有身份和权限的对象存储引用。

选择：实验用工作区路径检查，明确没有操作系统沙箱。理由：教学范围有限。代价：不能作为不可信通用执行服务。重新评估条件：接入任意 Shell、远程用户或第三方插件之前，先完成隔离与凭据设计。

练习：选择一个你想实现的代理场景，把六份记录中的约束替换掉。若你改变了任务假设，却保留所有结论不变，应重新检查自己是否真正做了决策。