《DeepSeek Harness 解构：可替换 Agent 运行时如何组装》目录

版本基线：deepseek-ai/deepseek-harness@47f943859bef60e4160492346772ded9b24f765a
拟定读者：Agent 平台与开发工具架构师、技术负责人、基础设施工程师，以及具备后端或全栈经验、希望转向 Agent 工程的开发者

读者定位

本书围绕 Agent 运行时如何组装展开，默认读者理解常见的服务端请求链、接口、持久化、并发和测试概念；不要求读者使用过 DSH，也不要求已经开发过 Agent。它不逐条复述 API，也不以零基础编程入门为目标。

它适合关心“怎么替换、怎么恢复、怎么上线”的工程团队；只想在现有服务里塞一个模型循环的场景，用不到本书的大部分机制。正文在首次引入 Agent 专有概念时，会同时说明它解决的工程问题、与常见后端概念的相似处及关键差异；类比只用于建立入口，最终结论以 DSH 的真实类型、事件、配置和运行证据为准。

阅读方式

正文按“工程问题 → 运行时机制 → 一次真实任务 → 能力替换 → 安全与证据 → 采用决策”的顺序推进，逐篇阅读即可；每章末尾有本章结论，可独立参考。正文不按读者角色划分章节，同一份内容在讲清实现事实的同时，覆盖边界与可替换性、投入与验收、运行条件、实现路径这几类关切。

读完后能做什么

读完后，读者可以完整追踪一次 Agent 任务从输入、模型请求、工具调用到持久化和恢复的链路；可以定位模型、工具、会话、权限或执行环境的替换边界，并判断变更影响范围；也可以为自己的团队设计一个有验收指标、失败阈值和退出条件的最小试点。

全书要回答的五个问题

1. DSH 比“模型调用 + 工具循环 + 消息数组”的轻量 Harness 多解决了什么问题？
2. Cordis、Profile、SessionEvent 和 capability seam 如何共同组成一个可替换的 Agent 运行时？
3. 这些机制在真实任务的执行、恢复、权限和多入口交付中是否形成闭环？
4. 哪类团队值得承担这套架构的复杂度，哪类团队不值得？
5. 已有后端或全栈经验如何迁移到 Agent 工程，哪些传统经验仍然成立，哪些会因模型输出不确定性和工具副作用而失效？

全篇按“工程问题 → 运行时机制 → 一次真实任务 → 能力替换 → 安全与证据 → 采用决策”推进，不按 package 逐个讲解。

贯穿全篇的同一验证任务

正文使用同一个 Headless 任务串联各章，避免每章换一个互不相干的示例：

在受限工作区内读取一个有缺陷的小项目，提出修改，经过审批后编辑文件并运行测试；中途注入一条 steer 消息，完成后持久化会话，再从同一会话恢复并核对结果。

这个任务沿组装、执行、事实、替换、安全、恢复六个观察点展开。若固定提交无法在无密钥环境完成某个观察点，正文会明确区分“源码路径已确认”“快照可重放”“真实 API 尚未验证”。

四篇结构

每篇同时回答一个转向 Agent 工程的实践问题：第一篇建立运行时心智模型；第二篇学会调试任务执行与状态；第三篇学会扩展能力并控制副作用；第四篇学会用工程证据评估、试点和交付 Agent 系统。

章节清单

00 技术决策摘要

一页给出定义、核心判断和选择条件，让不阅读全部实现细节的架构师、技术负责人和试点负责人也能判断是否值得进入技术试验：一句话定义、核心判断、决策速览，以及一张“采用 / 暂缓 / 不采用”决策卡。

第一篇 为什么这样组装

第一章 从最小 Agent Loop 到 Agent 运行时

• 1.1 从最小 Agent Loop 开始
• 1.2 DSH 把循环变为一种可替换实现
• 1.3 Turn、Step 与持久事实
• 1.4 本章结论

第二章 读懂 DSH 所需的 Cordis 核心

• 2.1 Context / Plugin / Fiber：定义、作用域与运行实例
• 2.2 Effect / disposer：把资源绑回插件生命周期
• 2.3 Service / inject：依赖变化会重跑 consumer
• 2.4 Cordis 事件：通知、短路与委托的语义差异
• 2.5 配置组合与 HMR：插件树级替换
• 2.6 本章结论

第三章 Profile、Bundle 与可检查的产品组装

• 3.1 从空根配置开始
• 3.2 base 是共享运行主干，能力默认未全部启用
• 3.3 Web 增加的是 Host、传输和浏览器控制面
• 3.4 Headless 只增加一次性驱动器
• 3.5 --dump-config 能审计什么、遗漏什么
• 3.6 本章结论

第二篇 一次任务如何运行

第四章 从输入到 idle：默认 Agent 执行链

• 4.1 Agent 的运行区间：从唤醒到再次 idle
• 4.2 Turn 在领取输入前打开
• 4.3 一个 Step 如何形成请求
• 4.4 工具可以并发执行，但结果按模型顺序提交
• 4.5 取消、dispose 与“完成”的证明范围
• 4.6 本章结论与调试检查

第五章 会话事实与可回放状态

• 5.1 “模型可见即已记录”的机制与边界
• 5.2 一条事件账本同时保留语义、原始流和边界
• 5.3 Surface 是模型视图
• 5.4 写入、checkpoint 与恢复分别保证什么
• 5.5 Resume、fork 与 compaction 的语义不能互换
• 5.6 本章结论与恢复演练

第三篇 能力、产品与信任

第六章 可替换能力体系

• 6.1 判断“可替换”的验收标准
• 6.2 模型 seam：从 provider 目录到冻结请求
• 6.3 工具 seam：定义、策略、执行与结果归一化
• 6.4 执行世界 seam：文件、进程、Shell 与沙箱
• 6.5 上下文能力的组合方式
• 6.6 长任务能力的事实归属

第七章 自扩展与多端产品形态

• 7.1 先划开运行时扩展与产品入口
• 7.2 动态 Cordis Package 的完整生命周期
• 7.3 Host—Gateway—Client 的协议边界
• 7.4 Web 是事实投影加控制面
• 7.5 自动化入口的所有权差异
• 7.6 多入口一致性验收

第八章 权限、安全与信任边界

• 8.1 工具策略链中的最终强制点
• 8.2 文件与进程：策略声明不等于操作系统隔离
• 8.3 凭据、启动环境与配置求值
• 8.4 会话、附件、spill 与遥测的数据路径
• 8.5 动态扩展与供应链边界
• 8.6 当前可以声称和不能声称的安全结论

第四篇 证据与采用

第九章 工程可信度与维护成本

• 9.1 先给主张分级，再选择测试
• 9.2 仓库门禁分别证明什么
• 9.3 Agent 结果必须由外部世界验证
• 9.4 不变式、文档门禁和 postmortem 的证据价值
• 9.5 可组合架构的维护半径
• 9.6 当前基线的可复现证据包

第十章 DSH 在真实 Agent 技术栈中的位置

• 10.1 比较方法：先读控制流，再谈功能
• 10.2 Codex：产品级运行时
• 10.3 Pi：低层循环已经可用，新 Harness 仍在形成
• 10.4 OpenAI Agents SDK：应用 SDK 的 Runner 与可恢复 RunState
• 10.5 LangGraph：图状态编排与 Agent 运行环境是两层问题
• 10.6 同一任务的逐步对照
• 10.7 采用判断

第十一章 采用路线

• 11.1 先定义边际价值与对照组
• 11.2 贯穿试点的最小验收任务
• 11.3 四阶段 Gate
• 11.4 指标必须有分母和采集方式
• 11.5 Go / Hold / Stop 与回滚
• 11.6 角色责任与签字证据

第十二章 结论

• 12.1 已由固定提交建立的技术事实
• 12.2 DSH 的边际价值成立条件
• 12.3 按现有技术栈选择
• 12.4 仍需目标环境证伪或证实的主张
• 12.5 即使不采用也可保留的设计原则
• 12.6 最终判断的有效期

附录

• A 能力地图：可替换能力的全量枚举
• B 事件与生命周期地图：时序图、状态表和事件名的检索底稿
• C 采用检查表：试点判断与记录的表格
• D 资料与证据索引：每项关键主张的提交、文件定位、核验日期与证据类型

交付结构

deepseek-harness-deep-dive/
├── 00-executive-brief.md
├── 01-deep-dive.md
├── appendices/
│   ├── A-capability-map.md
│   ├── B-event-and-lifecycle-map.md
│   ├── C-adoption-checklist.md
│   └── D-sources-and-evidence.md
└── OUTLINE.md

证据边界

正文中的判断分为四类：实现事实（可以由源码、配置或生成文档直接确认）、设计意图（来自架构文档、Cordis 论文或 Agent Note）、运行证据（来自测试、快照、可运行示例和发布入口）、采用建议（基于前三类证据的推论，正文会单独标注）。

当前版本处于开发者预览阶段。兼容性、生产稳定性、性能和规模化交付能力没有被写成已获证明的结论。

外部对照资料只引用读者可以访问的官方仓库、官方文档或原始论文，不引用本机文件路径。每项外部事实记录核验日期；产品定位发生变化时，以最新官方资源为准。