《DeepSeek Harness 全景白皮书：从 0 到 1 详细拆解与实战教程》由 Ai 学习的老章著，2026 年 8 月 16 日发布。全书 25 章，从源码拆到实战落地，系统讲透 DeepSeek 开源的那套 Agent 运行系统。

一、抓骨架——模型之外决定上限

一句话核心：如果说模型是发动机，Harness 就是一辆可以自己改装的整车——DeepSeek 把 219 个功能包全部开放，一切皆插件，连 Agent Loop 也只是插件之一。

四个核心观点，像四根柱子撑起全书：

第一根柱子是"上限在模型之外"。模型负责理解、推理和生成；Harness 负责让模型看见正确的信息、获得合适的工具、在安全边界内行动，并把一次行动变成可恢复、可检查、可继续的工作过程。系统提示词、文件读取、工具调用、上下文压缩、权限审批、子 Agent、会话保存和用户界面，全都是 Harness 在做。

第二根柱子是"没有特权核心"。Agent Loop、工具、模型适配、会话、压缩、权限甚至界面都做成插件，接口契约相同就能换实现。若把某一代模型的脾气写死在核心里，升级时会留下一堆历史包袱。

第三根柱子是"一次任务两条线"。事实线按 turn/start 到 turn/end 的顺序写进 Session，保存"发生了什么"；控制线在运行时发 agent/pre-step、tools/execute 这类事件，实时改"接下来怎样执行"。一条供恢复与审计，一条供纠偏与停止。

第四根柱子是"Session 是脊柱"。会话是一条追加式事件日志，模型消息由日志投影得到。任何进入模型上下文的内容，都应该能在会话记录里找到来源。

二、挖精髓——八个细节

第一个细节，一条命令长成一棵插件树。用户只输入一行 npx @deepseek-ai/dsh web，背后要走七步：CLI 解析参数、Boot 层确定 DSH_HOME 与 Profile、读取 Bundle、按优先级叠加补丁、把最终树交给 Cordis、按依赖加载 Host 与 Web 插件、建会话时再按 Preset 装配 Agent 平面。启动成功只代表 Host 起来了，工具能不能进会话，还取决于 Preset。

第二个细节，配置补丁"后层获胜"。四层补丁按顺序叠加：Profile 声明的 Bundle Patch、Profile 的 cordis.patch.yml、$DSH_HOME 的用户配置、命令行 --patch。越靠后的优先级越高，而且 config 是整体替换、不是逐字段合并。这个细节不记住，改配置时会得到一堆"我以为改了其实没生效"。

第三个细节，一次任务两条线各记各的。事实线保存 turn/start、step/start、user/message、tool/call、tool/result 直到 turn/end，供界面投影、会话恢复、审计和分叉；控制线在运行时发 agent/pre-step、llm/stream、tools/pre-execute、agent/turn-stopping 等事件，让插件能在执行中途介入纠偏。"修复这个测试并验证"是一个 Turn 三个 Step：读文件、改代码、跑测试。Step 是一次模型请求加一组工具调用。

第四个细节，Session 用追加式日志加投影，而不是"给模型看的消息数组"。事件日志保留原始事实，Projection 生成对话页面、模型上下文、轨迹、审计等不同视图。供应商格式只是一种投影，换模型供应商不用动历史数据。压缩历史时也不删旧事件，另加一层替换 Surface 告诉后续模型"这段旧历史用这份摘要表示"——审计与推理上下文兼得。

第五个细节，省 Token 来自整条运行链，没有神奇开关。三件套：工具结果超过 8192 字符时裁剪，保留开头 4096 和结尾 1024，中间换成裁剪说明；超过 50,000 字节内联上限的大内容走 Spill 落盘，会话只留路径与摘要；上下文用到窗口 80% 时自动压缩，保留最近 16% 尾部原文，旧历史生成最多 8192 Token 摘要。稳定前缀尽量不变，还能换来 KV Cache 复用。

第六个细节，沙箱与审批各管一层。沙箱回答"进程能碰到哪里"，审批回答"这次动作是否需要人同意"。即使模型同一次回答提出十个高风险命令，每个调用仍单独落到权限预设上，不因前一个获批就放行后一个。官方默认组合是工作区可写加逐次询问。

第七个细节，工具并行执行，提交顺序不能乱。标准配置最大并行 10 个调用；三个并行工具可能按 C、A、B 顺序完成，写进会话时仍按模型提出的 A、B、C 顺序提交，保证下一轮结果与调用一一对应。取消任务时，已启动的尽量中止，未执行的补一个合成跳过结果，每个调用都保持闭合状态。

第八个细节，王虹手写 PPT 从 Skill 变成插件的完整样本。作者先用 GPT Image 做了 4 页手写风格 PPT，扩成 19 页 HTML，整理成可复用 Skill 发布，到 2026 年 8 月超 1500 次下载。迁移成 DSH 插件时踩了三个坑：资源路径必须相对 import.meta.url 解析、19 页 HTML 与备注和 PNG 导出必须一一对应、"翩翩体-简"字体的家族名在不同环境不一致。最后代码层、成品层、分发层三层验证，五个 Topic 进社区聚合页。

三、查漏补缺

第一件，"启动成功只代表 Host 起来了"。很多人以为 dsh web 能打开就万事大吉，实际上工具能不能进会话，还取决于 Preset 怎么装配。排查问题先看这个层次。

第二件，Token 账单要拆分看。界面累计输入混含新增、缓存、Schema、历史与重试。作者实测《背影》综合任务：一次任务 14 个 Step，约 3 分 55 秒，累计输入约 680K、输出约 24.5K Token，缓存命中率 93%——680K 只是口径记录，按每个成功任务核算成本才对。

第三件，归档不等于删除。Session 可能保存用户消息、命令输出、路径与错误，归档只是从常用列表隐藏，不代表删除底层数据。远程部署官方主动收紧，因为 Web 背后连接的是具备文件与命令能力的 Agent。

四、批判质疑

第一点，安全责任外移，但解法停在人工清单（中）。作者明确"工具调用有审批，无法自动推导出插件代码也在同一个边界内"，第三方插件权限接近当前用户，可读环境变量、访问网络、改文件。书中给的社区插件审查清单仍是一步步人工核对，作者自己也承认供应链三个缺口（发现质量、证明、升级治理）未解决——痛点说清了，系统解法还没来。

第二点，实测样本不足以支撑全书反复引用（中，技术维度）。《背影》综合实测是一次运行记录，作者自己标注"仅作运行链路样本"，但全书多处用它佐证性能与 Token 论点。第 24 章给出了严格的评测方法论（固定九类变量、多次运行、拆 Token 账单），作者自己的实测却未完全按这套标准执行。

第三点，版本锚定风险高（中）。Developer Preview 阶段，仓库根版本 0.1.0-rc.5、npm 与 PyPI 已到 rc.6，核心 API 随时破坏性变化。书中大量插件版本号（dsh-web-ui-all@0.1.12、modsearch@5.4.1 等）会快速过时，按书操作需以"固定版本"为第一原则。

第四点，作者是生态深度参与者，缺第三方视角（弱）。作者自己开发了王虹手写 PPT 插件并进入社区聚合页，全书对官方架构的欣赏多于审视，与 Claude Code、Cursor 等主流 Agent 框架的横向对比着墨很少，读者难以判断 Harness 的相对位置。

五、延伸推荐

• 《ReAct: Synergizing Reasoning and Acting in Language Models》（Shunyu Yao 等，普林斯顿大学与谷歌研究院，ICLR 2023）——推理与行动交织的 Agent 循环奠基论文，本书"事实线+控制线"设计的上游思想来源。
• 《大模型应用开发 动手做 AI Agent》（黄佳，人民邮电出版社，2024）——从零动手实现 Agent 的入门书，适合先建立应用层手感，再读本书啃源码。
• 《AI Agent 应用与项目实战》（唐宇迪、尹泽明，电子工业出版社，2024）——覆盖 Agent 核心组件构建与项目落地，与本书的架构拆解互补。

六、金句

"模型决定能力上限，Harness 决定能力怎样落地。"

"同一个模型，换一套编辑工具，任务成功率可能出现数量级的变化。"

"对模型来说，模糊工具就是模糊的世界。"

"真正的竞争，正在向模型之外移动。"

七、思维导图