DeepSeek Harness 技术入门与架构原理

版权信息

书名：DeepSeek Harness技术入门与架构原理

ISBN：978-7-115-70748-2

本书由人民邮电出版社发行数字版。版权所有，侵权必究。

您购买的人民邮电出版社电子书仅供您个人使用，未经授权，不得以任何方式复制和传播本书内容。

我们愿意相信读者具有这样的良知和觉悟，与我们共同保护知识产权。

如果购买者有侵权行为，我们可能对该用户实施包括但不限于关闭该帐号等维权措施，并可能追究法律责任。

版  权

编  著 亦 凯

责任编辑 张 涛

人民邮电出版社出版发行　　北京市丰台区成寿寺路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运行时实现插件的动态挂载、生命周期管理与依赖重新解析。

全书按“先跑起来，再拆开看，最后自己动手”的路径展开，包括导读、8章正文和2个附录：先运行DSH，用4套Preset（预置组合）观察同一模型在不同能力组合下的行为；再拆解Skill、Tool、Hook 3个扩展层次，分清Guard、Approval、Sandbox的执行边界；随后进入Cordis，解释插件的动态组合、生命周期与热更新；最后从设计者视角讨论如何构建和验证自己的Harness。

书中提供多组动手实验与观察方法。主要实验可以使用兼容的本地模型完成；涉及特定Provider、图像输入或版本接口的实验，仍需按相应环境复核。

本书适合有一定大模型应用经验的开发者、AI应用工程师与架构师阅读，也适合所有想理解“Agent软件应当如何组织”这一问题的读者参考。

前  言

为什么要写一本关于Harness的书

写这本书之前，我先问了自己一个问题：DeepSeek Harness（DSH）值得单独写一本书吗？

市面上的大模型工具书已经很多了，讲提示词的、讲部署的、讲Agent框架的，随便一搜就有许多本。如果这本书只是把官方README翻译成中文，或者把命令行参数逐个抄一遍，那确实不值得出版——这类内容AI自己就能生成，而且读者上网查文档就够了。

所以这本书想回答的是另一个问题：当大模型开始拥有工具、状态、权限、执行环境、子代理和工作流以后，一个Agent软件究竟应该怎样组织？

把这句话拆开解释。模型的工作是生成Token，要让它真正干活，一个应用级的Agent至少要回答一连串问题：它能看到什么上下文？能调用哪些工具？工具在哪里执行？哪些操作需要授权？失败之后怎么继续？历史状态存在哪里？一轮对话什么时候结束？可不可以派生子代理？可不可以运行代码？出了问题怎么恢复、怎么审计、怎么调试？

这些问题的答案加起来，就是Agent软件的组织方式。过去一年多，行业里流行把答案简化成“Agent = Model + Tools”。这个公式在演示里够用，但是一旦进入生产环境，就会产生很多问题。因为真正落地需要的是一整套Agent System（Agent系统）：模型、上下文、工具、状态、循环、执行环境、策略、持久化、可观测性，一样都不能少。把这些部分组织起来的那一层就是本书的主角：Harness。

“Harness”这个词，原意是套具、线束——既连接，又约束。将它用在Agent领域非常贴切：它一边连接模型和外部世界，另一边约束模型能做什么、怎么做、做完之后留下什么状态。

那么，为什么偏偏选DSH来“解剖”？

因为它把Agent软件的组织方式公开得足够彻底。DSH的架构文档把Model Adapter（模型适配器）、Tool Registry（工具注册中心）、Session Log（会话日志）、Agent Loop（Agent循环）等产品能力放进插件体系，扩展这些能力不必先修改特权产品核心（privileged product core）。Context（上下文）、Loader（加载器）和生命周期等组合语义仍构成运行时内核，稳定的是组件如何组合与退出，而不是某个固定产品组件。

这就是本书反复强调的Agent Runtime（Agent运行时）视角。需要说明的是，DSH目前还是Developer Preview（开发者预览版），把它捧成“Agent操作系统”或“行业标准”还为时过早，本书也不打算做这种判断。这里说它值得研究是因为它提供了一个难得的样本：Agent产品可以不再是一个功能固定的应用，而是一套可扩展、可组合、按会话装配的Runtime。

为了把这件事讲清楚，本书不会逐条罗列功能，而是设计了一条“先跑起来，再拆开看，最后自己动手”的学习路径。

全书主要内容共8章，可以分为3个部分。

第一部分（第1、2章）建立坐标。第1章先把“产品”和“Runtime”区分开，说明Harness不是又一个Coding Agent（代码智能体）；第2章从零运行DSH，用4套Preset（Standard、PTC、Minimal、Creative）做对照实验，观察同一个模型在不同会话级能力组合下的执行差异。

第二部分（第 3、4、5章）进入Agent内部。第3章拆解“一切皆插件”的真实含义——没有特权产品核心，但仍有 Kernel（内核）；第4章从Skill （技能）、Tool（工具）、Hook（钩子）3个层次动手改变 Harness，并分清Guard（安全规则检查）、Approval（审批）、Sandbox（沙箱）这3个经常被混为一谈的概念；第5章介绍Cordis，看插件为什么能够动态组合——生命周期如何跟踪、依赖如何重新成立、热更新如何以及为什么能建立在生命周期之上。

第三部分（第 6、7、8章）走向设计与判断。第6章还原在Agent 一轮对话的过程中，Runtime里究竟发生了什么；第7章把Tool Call（工具调用）与Agent Runtime连成一条完整的链；第8章讨论如何设计自己的Harness，以及哪些取舍值得做。

每章尽量回答4个问题：它解决什么工程问题？当前官方实现把它放在哪里？运行时为什么这样工作？怎样通过实验核对，而不只是接受概念？大部分实验只需要空目录、兼容模型和几个独立会话；书中没有执行记录的部分会提供实验步骤，而不把预期结果当作实测事实。

如果你已经用过一些Agent工具，或者正在把大模型接入自己的产品，这本书会给你一套新的观察框架。下次再看到一个Agent系统，你会下意识地问：它的能力边界在哪里？哪些东西可以替换、哪些是它的“内核规则”？它的生命周期由谁管理？

技术总会过时。DSH的命令行参数会变，Preset目录会变，API（Application Programming Interface，应用程序编程接口）也可能会被重写。但“Agent软件应当如何组织”会是Agent作为基础设施的漫长时期里始终绕不开的命题。

最后，感谢DeepSeek 团队开源DSH，也感谢社区在项目早期开展的讨论与实践。本书以2026年8月24日为技术冻结日，并将DSH版本敏感的命令、字段和插件状态单独标明。

注：本书更新信息、答疑服务的网址为https://www.zhihu.com/column/c_2081428172088910871。

编者

资源与支持

资源获取

本书提供如下资源：

• 官方源代码和参考资料；

• 异步社区7天VIP会员。

要获得以上资源，您可以扫描下方二维码，根据指引领取。

提交勘误信息

作者和编辑尽最大努力来确保书中内容的准确性，但难免会存在疏漏。欢迎您将发现的问题反馈给我们，帮助我们提升图书的质量。

当您发现错误时，请登录异步社区（https://www.epubit.com），按书名搜索，进入本书页面，点击“发表勘误”，输入勘误信息，点击“提交勘误”按钮即可（见下页图）。本书的作者和编辑会对您提交的勘误信息进行审核，确认并接受后，您将获赠异步社区的100积分。积分可用于在异步社区兑换优惠券、样书或奖品。

与我们联系

我们的联系邮箱是zhangtao@epubit.com.cn。

如果您对本书有任何疑问或建议，请您发邮件给我们，并在邮件标题中注明本书书名，以便我们更高效地做出反馈。

如果您有兴趣出版图书、录制教学视频，或者参与图书翻译、技术审校等工作，可以发邮件给我们。

如果您所在的学校、培训机构或企业，想批量购买本书或异步社区出版的其他图书，也可以发邮件给我们。

如果您在网上发现有针对异步社区出品图书的各种形式的盗版行为，包括对图书全部或部分内容的非授权传播，请您将怀疑有侵权行为的链接通过邮件发送给我们。您的这一举动是对作者权益的保护，也是我们持续为您提供有价值的内容的动力之源。

关于异步社区和异步图书

“异步社区”是由人民邮电出版社创办的IT专业图书社区，于2015年8月上线运营，致力于优质内容的出版和分享，为读者提供高品质的学习内容，为作译者提供专业的出版服务，实现作者与读者在线交流互动，以及传统出版与数字出版的融合发展。

“异步图书”是异步社区策划出版的精品IT图书的品牌，依托于人民邮电出版社在计算机图书领域四十余年的发展与积淀。异步图书面向各行业的信息技术用户。

导读
为什么现在需要Harness

0.1 Model只会生成Token，但Agent要完成任务

只看聊天界面，很容易产生一种错觉：模型（Model）能力越来越强，只要再接几个工具就能得到一个好用的Agent。但是实际系统没有这么简单，要让模型持续、可靠地完成任务，至少还要回答下面这些问题：

    Model
      │
      ├─ 能看到什么上下文？
      ├─ 能调用哪些工具？
      ├─ 工具在哪里执行？
      ├─ 哪些操作需要授权？
      ├─ 失败后如何继续？
      ├─ 历史状态保存在哪里？
      ├─ 一轮什么时候结束？
      ├─ 是否允许派生子Agent？
      ├─ 是否允许运行代码？
      └─ 如何恢复、审计和调试？
     

模型负责生成下一段概率上合理的输出。Agent系统则要把输出放进一个能够持续行动的环境，并保证模型的输出变成可执行、可验证和可纠错的行动。

Agent系统面对的核心问题并不只是“如何让模型更好地思考”，还有“如何让模型的输出变成可执行、可验证、可纠错的行动”。模型“提出”一个计划后，Agent系统需要决定什么时候调用工具、如何保存状态、如何判断工具执行是否成功，以及在结果偏离预期时如何重新规划。

下面这个常见定义只适合用来解释最小原型：

    Agent = Model + Tools
     

但是进入真实项目后，Agent系统还要处理上下文、状态、权限、持久化和可观测性。本书用下面这组要素描述它，但是不必把这个定义当成严格的公式：

    Agent System = Model + Context + Tools + State + Loop
                 + Execution Environment + Policy
                 + Persistence + Observability
     

Harness负责组织这些部分。

“Harness”在Agent领域，同时体现了两项职责：连接模型与外部世界（External World），并约束模型能做什么、怎样做以及留下什么状态。

0.2 为什么DSH值得单独写一本书

现在已经有大量Coding Agent、Agent Framework（Agent框架）和围绕MCP（Model Context Protocol，模型上下文协议）形成的工具生态。如果DSH只是又一个能够修改代码的Agent，就没有必要用一本书来讨论它。本书选择DSH是因为它公开展示了一种不同的组织方式：Model Adapter、Tool Registry、Session Log、Agent Loop等产品能力都进入插件体系，扩展这些能力不必先修改特权产品核心。图0-1对比了传统Agent和DSH。

“一切皆插件”不等于DSH完全没有核心。

Cordis定义了Plugin（插件）、Context（上下文）、Service（服务）、Event（事件）、Effect（可逆变更）、Lifecycle（生命周期）等组合语义，所以更准确的表述是：DSH把具体的Agent产品能力组织成可组合插件，相对稳定的核心负责规定组件如何组合和退出。

图0-1 传统Agent和DSH的对比

这就是本书所说的Agent Runtime视角，如图0-2所示。

图0-2 Agent Runtime视角：Harness位于模型与外部世界之间

0.3 本书的学习路径

本书采用“先跑起来，再拆开看，最后自己动手”的学习路径，如图0-3所示。

图0-3 DeepSeek Harness学习路径

全书会带领读者通过代码和小型实验逐步搭建一个概念上的Harness Lab（Harness实验环境），Harness Lab最终架构图如图0-4所示。

每章尽量回答以下4个问题：

• 它解决什么工程问题？

• 当前官方实现把它放在哪里？

• 运行时为什么这样工作？

• 怎样通过实验核对，而不是只接受概念？

图0-4 Harness Lab最终架构图

第1章
Harness不只是另一个Coding Agent

1.1 先把“产品”和“Runtime”区分开

从用户角度看，DSH很像一个完整的Agent产品：选择Workspace（工作空间），输入任务，查看模型输出与工具调用，批准敏感操作，最后取得结果。

如果从架构角度看，这算是某一种组件组合的运行结果，DSH把“一个Agent具备哪些能力”变成了装配问题。

例如，一个会话可能需要完整文件系统工具、Shell、Skills（技能集）、Plan（任务规划器）、Subagent（子代理）、Workflow（工作流）、Sandbox（沙箱）和Approval（审批）。另一个会话可能只需要Bash、一个文件编辑器和固定Prompt（提示词）。其他会话可能还需要检查当前Runtime、临时挂载插件或修改自己的Preset。

在许多框架中，这意味着维护3套Agent配置，甚至3套Loop。

DSH预置的4套Agent Preset展示了这种按会话组合能力的思路：

    Standard
    PTC
    Minimal
    Creative
     

这里只要记住它们的名字，我们会在第3章详细拆解它们。

1.2 “一切皆插件”

第一眼看到“一切皆插件”（Everything is a Plugin）时，大家容易产生一种误解：既然模型适配器、工具、会话、智能体循环等能力都被组织成插件，那么这些插件是不是想换就换、想删就删？

并不是！“Everything is a Plugin”描述的是这些能力如何参与整个系统的组合，但这并不代表它们能够随意更换或删除。

DSH的插件化，统一的是系统各功能组件的组织方式，而不是这些组件本身的职责。例如：

• 模型适配器负责连接不同的大模型；

• 工具运行时负责注册、组织和执行工具；

• 会话系统负责保存智能体运行过程中产生的状态和事件；

• 智能体循环负责推动模型推理、工具调用以及下一步行动；

• 文件系统、沙箱和子代理则分别提供不同类型的执行能力。

这些组件负责的事情完全不同。DSH所做的是让它们都遵循同一套插件组合规则，并由底层运行时统一管理它们的加载、依赖、作用域和生命周期。

在很多智能体系统中，模型调用、工具执行、会话管理和智能体循环往往直接写在核心程序里。如果开发者想改变其中某一部分，可能需要修改核心代码。DSH则尽量把这些能力拆成可以独立组合的组件，这些组件可以动态组合和替换，但它们仍然具有明确的职责、依赖关系和生命周期，一个组件可能依赖另外一个组件提供的能力，所以不是“想删就删”。如果一个组件依赖的能力消失，那么这个组件可能暂时无法运行，或者随着依赖关系的变化被卸载。

并且，组件依赖的是“能力”，而不是某个固定实现。假设一个工具需要读取文件，一般的写法可能是：这个工具必须使用“本地文件系统实现”。这样这个工具就和某个具体实现绑定在一起了。如果以后想把文件操作放进容器、远程服务器或者其他隔离环境，就需要修改工具本身。

而DSH的插件表达的是：我需要“文件系统”这种能力。至于这项能力最终由谁提供，可以根据当前运行环境决定：

    Local FS
    Remote FS
    Container FS
    ...
     

使用这项能力的工具并不需要知道底层是哪一种实现。

所以，DSH中的插件化就是让上层组件只关心“需要什么能力”，而不必关心“这个能力具体由谁、以什么方式实现”。具体的实现由当前插件组合决定，并由运行时负责连接和管理。

1.3 为什么这不只是“多加几个Tool”

一个普通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（User Interface，用户界面）对会话事件（Session Event）的渲染；

• Agent后续跟进/行为指导（follow-up/steer）。

这些扩展点覆盖Tool执行前后、Session渲染和Agent控制流程。它们通过明确的Runtime契约接入，不要求扩展者直接改写默认Loop。

1.4 这是否意味着DSH会成为行业标准？

现在把DSH称作“Agent操作系统”或“微内核”还太早。目前版本能够证明的是：插件、Preset、PTC、Subagent和Extensions（扩展能力）可以被组织进同一个可扩展Runtime。但是这并不代表这套设计会成为行业标准。

这套设计很容易让人联想到操作系统或微内核，但是从目前公开的信息来看，还没有理由把它上升为“DeepSeek正在制定Agent行业标准”，更没有依据把它描述成对其他产品的“降维打击”。

本书据此采纳一个保守的判断：DSH的研究价值来自其公开的模块边界和扩展机制，而不是尚未形成的行业地位。即使它最终没有成为事实标准，但它仍然提供了一套非常值得借鉴的Agent Runtime设计思路。

1.5 Developer Preview

目前官方README仍把项目标记为Developer Preview。本书以2026年8月24日为技术冻结日，并把DSH版本固定到提交b150a551b8d465e31e418e1b2eaf5e79bbb7d28e。读者实际执行命令时，应同时检查所装版本的README、--help输出。

相对稳定的是架构：Harness的职责、插件组合、Context/Service/Effect、Agent Loop、Tool Pipeline（工具流水线）、Session Event、Capability（能力）/Provider，以及Sandbox/Approval/Lifecycle的边界。

而容易发生变化的是CLI（命令行接口）参数、package（软件包）名称、Preset目录、UI、事件名、PTC Mode API、Subagent backend（子代理后端实现）和Extension API（扩展API）。

所以本书后文会把版本敏感事实与架构解释分开标注。