DeepSeek Harness白皮书：238个功能包怎么协作？框架梳理（附课件下载）

学Agent相关的知识，最容易掉进一个坑：今天记一个提示词技巧，明天装一个插件，回头一看脑子里还是一团乱。真正有用的做法是先找到一副完整的骨架，把零散的知识点挂上去。

这份114页的《DeepSeek Harness全景白皮书》恰好提供了这样一副骨架。作者是"AI学习的老章"，版本2026.08，内容从设计原理、源码架构、运行机制一路铺到安装部署、插件生态和开发实战。我读完之后按"整体框架—模块关系—重点深挖—边界与生态—落地路径"这条线重新梳理了一遍，产品岗和技术岗的朋友都能对着看。

一、知识体系整体框架：Agent = Model + Harness

整本书的立论就一个公式：Agent = Model + Harness。模型负责理解、推理和生成，Harness负责让模型看见正确的信息、拿到合适的工具、在安全边界内行动，并把一次行动变成可恢复、可检查、可继续的工作过程。这个公式的分量在于，同一个模型换一套编辑工具，任务成功率可能出现数量级的变化——模型再聪明也只能通过系统给它的接口观察世界，接口含糊、错误无法反馈，它就会在错误路径上不断消耗Token。

模型是千里马，Harness是缰绳、马鞍和马蹄铁。

这句话来自Martin Fowler在2026年4月发表的《Harness Engineering for Coding Agent Users》，也是白皮书里反复引用的一组视角：Guides前馈引导和Sensors反馈感知。前馈是任务开始前告诉Agent该怎么做，包括系统提示、Skills、项目规则；反馈是行动发生后把真实结果交回来，包括命令输出、测试结果、审批拒绝。只有前馈，Agent会把计划写得漂亮却看不见偏差；只有反馈，它会反复试错，成本极高。

围绕这个框架，白皮书给了三套坐标系：六个基础问题、三个层次、五个评估指标。其中「可观察、可恢复、可约束、可替换、可验证」这五个词，建议直接抄进团队的选型清单。

二、核心模块逻辑关系：一棵插件树怎么长出来

理解这套系统，最关键的一句话是：一切皆插件。它覆盖的不是界面小挂件，而是完整的Agent能力——模型、工具、技能、会话、沙箱、存储、循环、调度、UI，全部由插件组合而成，连负责"让模型继续思考并调用工具"的Agent Loop也只是插件树中的一员。

要读懂这棵树，先记住四个词。Plugin是一项可加载、可卸载的能力；Bundle是一组插件和配置的可分发组合；Profile决定整个进程有什么；Preset决定某次会话中的Agent会什么。白皮书给的比喻很清楚：Bundle是积木包，Profile决定整间工作室有什么，Preset决定这次任务给Agent哪些工具和做法，Plugin是实际运行的每一块积木。

规模上有个容易搞混的地方：白皮书给了两种都正确的口径，按pnpm工作区完整展开是238个workspace成员，而packages目录下的功能包是219个。能力切得很细，39个Client包、13个Session包，还有Subagent、Shell、Core、Host以及LLM、Storage、Sandbox、Compaction、Skill等小组。拆得细让依赖关系更清楚，也让单项能力可以单独替换和测试，代价是初读源码容易迷路，所以白皮书建议用五层地图来看：产品入口、客户端、Agent、基础设施、运行底座。

从一条命令到一棵插件树，白皮书把启动拆成七步：解析参数、确定DSH_HOME与Profile目录、读取Bundle、叠加补丁、交给Cordis按依赖加载、最后按Preset装配Agent平面。有个很实用的推论是：启动成功只代表Host和Web服务起来了，某个工具能不能进入会话，还取决于所选Preset和权限策略。

Profile隔离是这套设计里最贴心的一块，给web装的插件不会自动进入另一个自定义Profile，所以主力环境可以保持稳定，试验插件放进单独的demo Profile，出问题直接删掉就行。官方常见的Preset有三个：standard是完整编码Agent，code在它基础上增加Code Mode，minimal只保留少量核心编辑与Shell能力。

三、重点模块深度解读：Agent Loop、Session 与 Token 控制链

Agent Loop：一次任务里同时跑着两条线

一次用户任务通常构成一个Turn，Turn内可以包含零个或多个Step，一个Step对应一次模型请求加上该请求产生的一组工具调用。白皮书里我觉得最见功力的一点，是把一次Turn拆成了两条线：一条是持久化事实线，写进Session，记录"发生了什么"；另一条是实时控制线，用事件决定"现在应该怎样做"，压缩器可以在pre-step判断上下文压力，模型插件可以在agent/request调整请求，权限与审批包住工具执行，停止逻辑决定Turn是否继续。为什么要分两条？因为混在一起会导致重放历史时分不清某个事件是临时控制还是必须恢复的事实，插件想改策略时也容易直接篡改历史。

Session：整套系统真正的脊柱

这套系统没有把"给模型看的消息数组"当成唯一真相，而是保存一条追加式事件日志，模型消息由这条日志投影得到。这意味着同一份事件能生成多种视图：对话页面看到用户消息和工具卡片，模型上下文看到裁剪压缩后的消息，轨迹页面看到请求与耗时，分叉会话继承某个位置以前的事实。白皮书里有一条约束我印象很深：任何进入模型上下文的内容，都应该能在会话记录中找到来源。有了追加式日志，恢复、分叉、重放三类能力会自然出现，不过有个提醒很关键——重放历史事件不会自动重做外部副作用，真正的回退需要额外的文件快照或业务补偿机制。

工具执行与 Token 控制链

工具调用的管线是：模型提出调用、参数解析与工具查找、并行或独占分类、沙箱策略与审批、执行、结果标准化、写入Session。读取互不相关的文件通常可以并行，修改同一工作区或启动交互命令可能需要独占，标准配置中的最大并行工具调用数是10个。这里有一条关键规则：三个并行工具可能按C、A、B的顺序完成，但写进会话时仍要按模型提出的A、B、C顺序提交，因为模型下一轮会把工具结果与原来的调用一一对应，顺序漂移轻则理解错文件，重则把错误归到另一个调用上。

Token这一块更实用。真正昂贵的浪费有三类：工具返回一大段噪音，模型每轮都要重新阅读；稳定前缀不断变化，供应商缓存无法复用；工具接口不可靠，模型在失败和重试中反复打转。白皮书的方案是在整条运行链上设三道闸门：第一道是稳定前缀与缓存复用；第二道是工具结果裁剪，超过8192字符就裁剪，保留开头4096字符、结尾1024字符，更大的内容通过Spill落盘；第三道是延迟压缩，上下文压力达到窗口的80%时触发，默认保留最近16%的尾部原文。

四、安全边界与插件生态：这套东西能不能放心用

权限方面，Base Bundle最终提供三类常用预设：只读，适合陌生仓库和代码审查；工作区可写，可以修改指定工作区、敏感动作询问，适合日常开发；完全访问，可越过常规文件边界、审批关闭，只适合一次性隔离环境。默认沙箱策略是workspace-write，默认审批策略是ask。白皮书把两者分工说得很清楚：沙箱回答「进程能碰到哪里」，审批回答「这次动作是否需要人同意」，只用审批，一次确认可能影响很大范围；只用沙箱，工作区内的删除和网络动作仍可能造成损失。

更需要注意的是边界之外的部分。工具沙箱不能自动覆盖宿主插件，安装到Profile的第三方插件运行在dsh宿主进程里，Git构建脚本和MCP子进程也有各自独立的权限，所以社区插件必须按真实软件做供应链审查。社区入口目前是一张发现页，官网的"社区插件"会跳到GitHub的dsh-plugin Topic，页面里会混入Skill、主题、应用和模板等噪声，安装前要核对发布产物、版本、权限和维护状态。白皮书推荐的插件分两组：运行增强类有补上终端入口的dsh-TUI、让文本模型读懂图片的ModLens、让子Agent形成团队的dsh-agent-teams；工作流增强类有@文件回到输入框的dsh-at-file、在回答上直接批注的dsh-annotation，以及让回答长出交互界面的dsh-genui。

判断一个插件做完了没有，白皮书给的标准很硬：陌生环境可复现。作者的"王虹手写风格PPT"从WorkBuddy的1500多次下载走到DSH插件，真正费力的部分在路径、资源打包、字体、测试和干净Profile安装。仓库里能运行只是起点，用户一条命令能装好并得到同样结果，才算完成交付。

五、落地应用场景与进阶学习路径

落地入口有三种。Web适合普通用户和插件体验者，用来对话、选模型、看轨迹、管理工作区；Headless适合自动化和命令行流程，跑一次性任务、脚本、CI；Python SDK面向应用开发者，用JSON-RPC驱动打包好的运行时。想先跑起来，按白皮书的"十分钟跑起"那一章走一遍就行：环境准备、一行启动、配置API Key、选工作区、选Preset、设权限。

学习路径上，白皮书给了三条路线：快速上手路线是第3章加第13到15章再加第17到19章；源码研究路线是第4到12章加附录A和附录D；插件开发路线是第5到7章加第20到23章。想研究Agent运行机制、想为DeepSeek模型补齐特定工作流、想开发Agent插件的人，都能从这套开源实现里拿到东西；如果目标只是稳定完成日常编码，成熟的成品工具会更省心。

这本书的结语我很喜欢：真正的竞争，正在向模型之外移动。想系统补一补AI应用、Agent和产品方法论的知识，可以上运营动脉（www.yydm.cn）翻翻，站内有7万+份方案、报告和课件，每月更新超1000份，技术和产品方向的资料都挺全。