Appearance
5.2 设计哲学与决策记录
本章概览：把散落在各章的设计原则收拢成一个"设计哲学"清单，并介绍 DSH 的决策记录体系——Agent Notes 如何让"为什么"可追溯。
六条贯穿性的设计原则
1. 一切皆插件，无特权内核
产品每一部分都是插件（含 agent loop 本身），都可以从配置替换。推论：扩展 = 挂载插件，永不修改内核；注册是可逆副作用。
出处：
docs/architecture.md（deepseek-harness-src/docs/architecture.md）
2. 事件就是扩展点，选对事件域是第一个决定
持久会话事件记录"必须存活的事实"；agent/* 实时事件协调"进行中的工作"；能力事件为 seam 附加"策略与适配器"。新行为归属见架构文档的映射表。
3. 模型可见 ⟺ 已记录（Model-visible ⟺ logged）
抵达模型请求的一切必须能从会话日志重建，由运行时不变量断言。这是事件溯源模型 + 持久化 + 压缩 + 恢复的基石。
4. 能力缝三角色一体设计
Definition / Provider / Consumer 三分离，让"换后端 = 改配置"。seam 是完整能力，绝不只是单个角色。
5. 契约双端遵守，结果正交报告
防御模式的精髓：公共 API 只暴露规范化的单一结果形态；正交事实独立报告；异步状态绝不当同步状态读。
6. Fail loud，绝不静默
配置/加载/组合错误在最早的解析点响亮失败：无后端可用的沙箱拒绝裸跑；组合缺失的 preset 以 broken 列出；不满足的注入在启动时报出每个未解析插件。
核心权衡（trade-offs）速览
| 设计 | 放弃什么 | 得到什么 |
|---|---|---|
| 只追加事件日志 | 就地编辑的便利 | 完整可回放历史、恢复/fork/投影统一 |
| patch 整体替换 config | 深层合并的便利 | 组合可预测、无隐式合并歧义 |
| 沙箱只表达文件效应 | 网络/进程/设备限制表达 | 简单、可移植、可 fail-closed |
| 协作式取消 | 强杀保证 | 无悬挂、可预测的清理 |
| 激活（goal activation）不持久化 | 自动续跑的便利 | 恢复/续跑需要显式人类授权 |
| subagent 绑定父组合 | 子代理自由配置 | 子代理能力与父一致、同步组合 |
| 压缩的 surface 替换 | 保留全部历史细节 | 长会话可持续、日志仍可回放 |
决策记录体系：Agent Notes
.agents/notes/ 是 DSH 的"为什么"档案，约 1300+ 篇：
| 目录 | 含义 |
|---|---|
implemented/architecture | 已实现的架构决策（现在时描述现状） |
implemented/feature | 已实现的功能设计 |
implemented/process / testing / bug-fix / simplification | 流程、测试、缺陷修复、简化决策 |
proposed/ | 提议中的设计 |
rejected/ | 被拒绝的方案（记录为何不做） |
archived/ | 已归档（冻结：不可编辑，不作为当前权威） |
阅读示例（贯穿本站引用的决策）
| 主题 | 笔记 |
|---|---|
| 能力缝拆分 | implemented/architecture/2026-06-13-capability-seams.md |
| 会话持久化写协调器 | implemented/architecture/2026-06-18-shared-persistence-write-coordinator.md |
| 沙箱设计 | implemented/feature/2026-07-06-sandbox.md |
| 作用域上下文与安全非目标 | implemented/architecture/2026-07-08-agent-scope-contexts.md |
| 工具输出 spill | implemented/architecture/2026-07-08-tool-output-spill-files.md |
| 协作式工具取消 | implemented/architecture/2026-07-19-cooperative-tool-cancellation.md |
| 同会话目标领域 | implemented/feature/2026-07-19-persisted-same-session-goal-domain.md |
| 后台任务运行时 | implemented/architecture/2026-06-20-generic-long-running-tool-runtime.md |
| 工具渲染意图联合 | implemented/architecture/2026-07-02-tool-render-intent-union.md |
出处：
.agents/notes/README.md（deepseek-harness-src/.agents/notes/README.md）
Agent Notes 的写作纪律
implemented/笔记用现在时描述已交付的现实；禁止迁移计划、验收清单、spec 用语（"should"）；- 非平凡变更必须带至少一篇 Agent Note；
- 归档笔记冻结：绝不编辑，不作为当前权威；
- 笔记是"为什么、放弃了什么、需要什么验证"，不是测试走查或实现叙述。
出处：
.agents/notes/implemented/AGENTS.md与.agents/notes/README.md
从哲学到代码的三条验证链
- 生成器防漂移：tool-catalog、config-catalog、capability-seams、module-graph 都由源码生成并有新鲜度门；
- 运行时不变式：
ctx.invariants断言日志关系（序列单调、配对、生命周期合法）； - 测试梯队：真实入口 + 世界验证 + 快照回放，覆盖产品级 transcript。
小结
DSH 的设计哲学可以压缩为一句："把产品做成可组合、可回放、可替换的插件树，并用纪律（事件溯源、契约规范化、生成器、不变式）守住组合的边界。" 决策记录体系（Agent Notes）让每个"为什么"都能在源码旁找到答案——这是它与其他框架最不同、也最值得学习的一点。
参考资料
- docs/architecture.md — 架构与扩展归属（
deepseek-harness-src/docs/architecture.md） - .agents/notes/README.md — Agent Notes 体系（
deepseek-harness-src/.agents/notes/README.md） - docs/defensive-patterns.md — 防御模式（
deepseek-harness-src/docs/defensive-patterns.md） - docs/glossary.md — 官方术语表（
deepseek-harness-src/docs/glossary.md）