版权信息 书名：DeepSeek Harness 技术入门与架构原理
本书由人民邮电出版社发行数字版。版权所有，侵权必究。
您购买的人民邮电出版社电子书仅供您个人使用，未经授权，不得以任何方式复制和传播本书内容。
我们愿意相信读者具有这样的良知和觉悟，与我们共同保护知识产权。
如果购买者有侵权行为，我们可能对该用户实施包括但不限于关闭该帐号等维权措施，并可能追究法律责任。
版 权 编 著 亦 凯
责任编辑 张 涛
人民邮电出版社出版发行 北京市丰台区成寿寺路11号
邮编 100164 电子邮件 315@ptpress.com.cn
网址 http://www.ptpress.com.cn
读者服务热线： (010)81055410
反盗版热线： (010)81055315
内 容 提 要 本书以 DeepSeek Harness（DSH）为对象，讲解 Agent 软件的系统化组织方式。全书从“模型只会生成 Token，Agent 要完成任务”这一根本矛盾切入，围绕“一切皆插件”（Everything is a Plugin）架构，剖析 DSH 如何把模型适配、工具注册、会话记录、Agent 循环等能力组织进统一的插件组合体系，并借助 Cordis 运行时实现插件的动态挂载、生命周期管理与依赖重新解析。
全书按“先跑起来、再拆开看、最后自己动手”的路径展开，共八章加结语与附录：从零运行 DSH，用四套预置 Preset 观察同一模型在不同能力组合下的行为差异；拆解 Skill、Tool、Hook 三个扩展层次，分清 Guard、Approval、Sandbox 的执行边界；深入 Cordis，理解插件为何能够动态组合、热更新为何能建立在生命周期之上；最终完成从 Tool Call 到 Agent Runtime 的认知跃迁，并站在设计者视角讨论如何打造自己的 Harness。
书中配有大量可复现的动手实验与观察方法，不依赖特定云端模型，使用本地模型即可完成全部验证。
本书适合有一定大模型应用经验的开发者、AI 应用工程师与架构师阅读，也适合所有想理解“Agent 软件应当如何被组织”这一问题的技术读者。
前 言 为什么要写一本关于“马鞍”的书 写这本书之前，我们先问自己一个问题：DeepSeek Harness（以下简称 DSH）值得单独写一本书吗？
市面上的大模型工具书已经很多了。讲提示词的、讲部署的、讲 Agent 框架的，随便一搜就是几十本。如果这本书只是把官方 README 翻译成中文，或者把命令行参数逐个抄一遍，那确实不值得出版——这类内容 AI 自己就能生成，读者上网查文档就够了。
这本书想回答的是另一个问题：
当大模型开始拥有工具、状态、权限、执行环境、子代理和工作流以后，一个 Agent 软件究竟应该怎样被组织？
先把这句话拆开。模型的本事是生成 Token，但要让它真正干活，一个应用级的 Agent 至少要回答一连串问题：它能看到什么上下文？能调用哪些工具？工具在哪里执行？哪些操作需要授权？失败之后怎么继续？历史状态存在哪里？一轮对话什么时候结束？可不可以派生子代理？可不可以运行代码？出了问题怎么恢复、怎么审计、怎么调试？
这些问题的答案加起来，就是 Agent 软件的组织方式。过去一年多，行业里流行把答案简化成“Agent = Model + Tools”。这个公式在演示里够用，进了生产环境就露馅。真正落地需要的是一整套 Agent System——模型、上下文、工具、状态、循环、执行环境、策略、持久化、可观测性，一样都不能少。把这些部分组织起来的那一层，就是本书的主角：Harness。
“Harness”这个词，原意是马鞍、套具、线束——既连接，又约束。放在 Agent 领域非常贴切：它一边连接模型和外部世界，一边约束模型能做什么、怎么做、做完之后留下什么状态。
那么，为什么偏偏选 DSH 来解剖？
因为它把 Agent 软件的组织方式公开得足够彻底。DSH 的架构文档写得很明白：Model Adapter、Tool Registry、Session Log、Agent Loop 这些产品能力，全部放进插件体系；产品层没有任何一个组件是“必须改源码才能扩展”的特权核心。真正稳定的内核，是“组件如何组合”的规则，而不是某个具体的组件。
这就是本书反复强调的 Agent Runtime 视角。需要说明的是，DSH 目前还是 Developer Preview，把它捧成“Agent 操作系统”或“行业标准”都为时过早，本书也不打算做这种判断。它值得研究，是因为它提供了一个难得的样本：Agent 产品可以不再是一个功能固定的应用，而是一套可扩展、可组合、按会话装配的 Runtime。
为了把这件事讲透，本书不走“逐条罗列功能”的路线，而是设计了一条“先跑起来、再拆开看、最后自己动手”的学习路径。
全书共八章，可以分成三个部分。
第一部分（第1、2章）建立坐标。第1章先把“产品”和“Runtime”分开，说明 Harness 不只是又一个 Coding Agent；第2章从零把 DSH 跑起来，用四套预置 Preset（Standard、PTC、Minimal、Creative）做对照实验，让你亲眼看到：同一个模型、同一个进程，不同会话可以拥有完全不同的能力组合。
第二部分（第3、4、5章）进入内部。第3章拆解“一切皆插件”的真实含义——没有特权核心，但仍有 Kernel；第4章从 Skill、Tool、Hook 三个层次亲手改变 Harness，并分清 Guard、Approval、Sandbox 三件经常被混为一谈的事；第5章进入 Cordis，看插件为什么能够动态组合——生命周期如何跟踪、依赖如何重新成立、热更新为什么能建立在生命周期之上。
第三部分（第6、7、8章）走向设计与判断。第6章还原 Agent 一轮对话在 Runtime 里究竟发生了什么；第7章把 Tool Call 与 Agent Runtime 连成一条完整的链；第8章站到设计者的位置，讨论如何设计自己的 Harness，以及哪些取舍值得做。
每一章都尽量讲四层：它解决什么工程问题；官方实现把它放在哪里；运行时为什么这样工作；你怎样用实验验证，而不是只相信概念图。书中的实验成本很低——一个空目录、一个本地模型、几个会话，就能重复出关键结论。
如果你已经用过一些 Agent 工具，或者正在把大模型接入自己的产品，这本书会给你一套新的观察框架。下次再看到一个 Agent 系统，你会下意识地问：它的能力边界画在哪里？哪些东西可以替换、哪些是它的“内核规则”？它的生命周期由谁管理？
技术总会过时。DSH 的命令行参数会变，Preset 目录会变，API 也可能重写。但“Agent 软件应当如何被组织”这个问题，会在 Agent 成为基础设施的漫长时期里一直有效。这本书赌的，就是这一点。
最后，感谢 DeepSeek 团队把 DSH 开源，也感谢社区在项目早期贡献的大量讨论。本书所有命令与配置以 2026 年 8 月前后的官方文档为基线，凡是可能随版本变化的地方，正文里都做了提示——这正是学习“组织方式”而非“操作步骤”要付出的代价，也是收获。
导读 为什么现在需要Harness？ 0.1 Model只会生成Token，但Agent要完成任务如果只看现在的聊天系统，我们很容易产生一种错觉：大模型变的越来越聪明了，这样Agent 只要“给模型接几个工具”就可以做的很好。
其实并不是这么简单，真正把一个模型变成可工作的 Agent至少还需要解决下面这些问题：
Model
│
├─ 看到什么上下文？
├─ 能调用哪些工具？
├─ 工具在哪里执行？
├─ 哪些操作需要授权？
├─ 失败后如何继续？
├─ 历史状态保存在哪里？
├─ 一轮什么时候结束？
├─ 是否允许派生子 Agent？
├─ 是否允许运行代码？
└─ 如何恢复、审计和调试？ 因为模型只能负责生成下一段概率上合理的输出；而 Agent 系统则需要把这种输出放入一个可以持续行动的环境中，并确保这些行动能够被可靠地执行。
Agent 的核心问题并不只是“如何让模型想得更好”，而是“如何让模型的输出变成可执行、可验证、可纠错的行动”。模型提出一个计划，但Agent系统需要决定什么时候调用工具、如何保存状态、如何判断工具执行是否成功，以及在结果偏离预期时如何重新规划。
所以目前简单的定义：
Agent = Model + Tools 已经不足以应对生产环境中的复杂性。真正落地时我们需要的不是一个孤立的 Agent，而是一套完整的 Agent System 所以完整的定义为：
Agent System= Model+ Context+ Tools+ State+ Loop+ Execution Environment+ Policy+ Persistence+ Observability 把这些部分组织起来的那一层就是我们今天越来越频繁看到的 Harness 。
“Harness”（ 马鞍）这个词原意接近“套具、线束、连接与约束装置”。放在 Agent 领域里非常的贴切：它不仅连接模型和外部世界，还约束模型能做什么、怎样做、做完后留下什么状态。
0.2 为什么DSH值得单独写一本书今天已经有大量 Coding Agent、Agent Framework以及围绕 MCP 形成的工具生态。如果 DSH 只是“又一个能够修改代码的 Agent”那么它并不值得用一本书来讨论。真正值得研究的是它对“核心”的处理方式：DSH 的架构文档明确把 model adapter、tool registry、session log、agent loop 等都放进插件体系，并强调产品层没有一个必须通过修改源码才能扩展的 privileged core，如图1所示。
图1 传统的agent和DSH对比
注意，这并不是说 DSH “完全没有核心”。
Cordis 自己仍然定义了 Plugin、Context、Service、Event、Effect、Lifecycle 等组合语义。更准确的表述是：
DSH 尽量把具体 Agent 产品能力从不可替换的中心，降成可组合的插件；真正稳定的内核变成“组件如何组合”的规则。
这就是本书所说的 Agent Runtime 视角，如图2所示。
图2 从Model到Agent Runtime：Harness位于模型与执行世界之间
0.3 本书的学习路径具体学习路径，如图3所示。
图3 DeeSeek Harness学习路径
通过代码的实战来了解DSH的架构，在整个过程中我们会持续构建一个概念上的 Harness Lab ，如图4所示：
图4 Harness Lab最终架构图
对于本书的每一章节都会尽量讲到四层：
1.它解决什么工程问题；
2.当前官方实现把它放在哪里；
3.运行时为何这样工作；
4.你怎样用实验验证，而不是只相信概念图。
第1章 Harness不只是另一个Coding Agent 1.1 先把“产品”和“Runtime”分开如果只从用户角度看DSH 可以理解成一个 Agent 产品：选择 Workspace、输入任务、看模型思考与工具调用、批准敏感操作、得到最终结果。
但从架构角度看这只算是某一种组合的结果，因为DSH把“一个 Agent 应该具有什么能力”变成可以装配的问题。
例如一个会话可能需要：
• 完整文件系统工具；
• Shell；
• Skills；
• Plan；
• Subagent；
• Workflow；
• Sandbox；
• Approval。
另一个会话可能只需要：
• Bash；
• 一个文件编辑器；
• 固定 Prompt。
第三个会话甚至可能需要：
• 检查当前 Runtime；
• 临时挂载插件；
• 修改自己的 Preset。
在很多框架里这意味着你要写三个不同 Agent 配置，甚至三套不同 Loop。
而 DSH 当前官方就预置了四套 Agent Preset 来展示这种“按会话组合能力”的思路：
Standard
PTC
Minimal
Creative 这里只要记住它们的名字，我们会在第 3 章详细拆解它们。
1.2 “Everything is a Plugin”不是说所有东西都一样第一眼看到“一切皆插件”很容易被误读成：
所有模块都只是一个目录，可以随便删除。
DSH真正的要表现的重点有两个：
第一，没有哪个组件是不可替换的核心。
Model adapter 可以换，Tool Runtime 可以扩展，Session 可以替换，Agent Loop 本身也不是不可修改的。
第二，插件之间通过 Runtime 合同交互，而不是互相硬编码实现细节。
例如一个 Tool 依赖文件系统能力，它理想上关心的是：
“我需要 filesystem capability”
而不是：
“我一定要 import LocalFilesystemV3”
所以就可以有很多种实现：
Local FS
Remote FS
Container FS
... 这是代码层面的工作，但是对于使用者来说这个能力仍然只依赖同一个接口。这就是插件体系中 Service / Provider / Consumer 思想在 Agent Runtime 里的价值。
1.3 为什么这不只是“多加几个Tools”一个普通 Tool Framework 通常允许：
registerTool(...)
registerTool(...)
registerTool(...) 但是核心的 Loop 仍然固定：
while not done:
call_model()
if tool:
execute_tool() DSH做的事情则更进了一步：不仅 Tool 本身可以注册，Tool 如何被调用、执行以及参与整个 Agent Loop，也可以通过插件和事件机制进行扩展。
换句话说：它开放的不只是 Tool 层而是 Tool 周围的 Runtime。
官方 extension cookbook 展示的扩展面包括：
• Tool registration；
• tools/pre-execute 拦截；
• monotonic guard；
• execution wrapper；
• post-processing；
• UI 对 Session Event 的渲染；
• Agent follow-up / steer。
这些扩展点覆盖了 Tool 执行前后、Session 渲染乃至 Agent 控制流程，但它们有一个共同前提：扩展不以修改默认 Loop 为代价。 所以核心运行逻辑不再是一个只能由产品自身修改的封闭区域，而是通过明确的 Runtime contract 向插件开放。
1.4 这是否意味着DSH会成为行业标准？现在就把 DSH 称作“Agent 操作系统”或“微内核”还太早。但它确实已经呈现出一种值得注意的方向：插件、Preset、Code Mode、Subagent、Extensions 不再只是彼此独立的功能，而是以插件的形式被组织进同一个可扩展的 Runtime。
这种结构很容易让人联想到操作系统或微内核，但是从目前公开的信息来看还没有理由把它上升为“DeepSeek 正在制定 Agent 行业标准”，更没有依据把它描述成对其他产品的“降维打击”。
因此本书采用一个保守的判断：
DSH 值得研究并不是因为它已经成为某种事实标准，而是因为它把 Agent 软件内部的模块边界和扩展机制公开得足够彻底。即使 DSH 最终没有成为行业标准，这套架构仍然提供了一个很有价值的样本：Agent 产品可以不再只是一个功能固定的应用，而逐渐演化为一个可扩展、可组合的 Runtime。
1.5 Developer Preview目前源代码仓库仍把项目标记为 Developer Preview ，所以本书命令和具体配置以 2026-08-18 前后官方 master 文档为写作基线。正式执行时，请确认安装版本的 README、--help 和锁定 commit
所以本书中长期有效的内容是：
• Harness 的职责；
• Everything is a Plugin；
• per-session composition；
• Context / Service / Effect；
• Agent Loop；
• Tool Pipeline；
• Session Event Sourcing；
• Capability / Provider；
• Sandbox / Approval / Lifecycle 的区别。
可能会改变的内容：
• CLI 参数；
• package 名称；
• preset 目录；
• UI；
• 事件名；
• Code Mode API；
• Subagent backend；
• Extension API。
所以从这一章开始，你会看到一些类似上面的“版本提示”。
