DeepSeek Harness 深入指南 / DeepSeek Harness Series

Geek-Chow2026-09-11 8:32

一个把「模型 + Harness = Agent 」这句口号拆到源码级别的中文系列。十二篇文章、一条主线：从"为什么光有模型不等于有 Agent"开始，拆开 Cordis 内核、组装层、会话日志、Agent Loop、系统提示装配、LLM 接缝、工具管线、能力接缝八个关键角色，最后带着全部深度重跑一遍开篇的示例。

对象：DeepSeek 于 2026 年 8 月开源的 deepseek-ai/deepseek-harness（命令名 dsh），MIT 协议，开发者预览版。本系列所有代码、配置、事件名均取自该仓库 docs/ 与 packages/ 的实际内容。

⚠️ 官方明确写着 THERE WILL BE COMPATIBILITY-BREAKING CHANGES （会有破坏性变更）。本系列讲的是设计骨架 ------骨架比 API 稳定得多；具体字段名请以仓库当时的 docs/architecture.md 为准。

姊妹系列：LLM 全景指南、多模态大模型。本系列默认你知道 token、上下文窗口、tool call 是什么；不清楚的话建议先读前者的 03 与 10。

缩写对照表

缩写 英文全称 中文
DSH DeepSeek Harness DeepSeek 智能体外壳（命令名 dsh）
LLM Large Language Model 大语言模型
API Application Programming Interface 应用程序编程接口
CLI Command Line Interface 命令行界面
UI User Interface 用户界面
TUI Terminal User Interface 终端用户界面
SDK Software Development Kit 软件开发工具包
MCP Model Context Protocol 模型上下文协议
ACP Agent Client Protocol 智能体客户端协议
HMR Hot Module Replacement 模块热替换
PTY Pseudo Terminal 伪终端
LSP Language Server Protocol 语言服务器协议
YAML YAML Ain't Markup Language 一种配置文件格式
JSON JavaScript Object Notation 一种数据交换格式
PTC Programmatic Tool Calling 程序化工具调用（code preset 的官方名）

一条主线：贯穿全篇的运行示例

你在自己的项目目录里敲下 npx @deepseek-ai/dsh web，浏览器打开 http://127.0.0.1:3080，填好 DeepSeek API key、选好工作区，然后发出一句话：

"读一下 package.json，给 README 补一个 Quick Start 小节，然后跑一次 pnpm lint 确认没问题。"

一分钟后：它读了 package.json、改写了 README.md、弹窗问你「是否允许执行 pnpm lint」、你点了允许、命令在沙箱里跑完、它回了一句总结。

这一分钟里，没有任何一行代码是"harness 的核心"------每一步都是一个可以被替换掉的插件。 这怎么做到的，以及为什么要这么做？

示例在第 3 篇完整定义并浅层追踪成 12 步，之后每篇结尾的 ⚓ 回到示例都会把当篇的深度接回它，第 12 篇带着全部深度重演一次。

全域思维导图

#mermaid-svg-S55LVPBXIZ86uI7X{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-S55LVPBXIZ86uI7X .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-S55LVPBXIZ86uI7X .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-S55LVPBXIZ86uI7X .error-icon{fill:#552222;}#mermaid-svg-S55LVPBXIZ86uI7X .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-S55LVPBXIZ86uI7X .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-S55LVPBXIZ86uI7X .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-S55LVPBXIZ86uI7X .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-S55LVPBXIZ86uI7X .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-S55LVPBXIZ86uI7X .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-S55LVPBXIZ86uI7X .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-S55LVPBXIZ86uI7X .marker{fill:#333333;stroke:#333333;}#mermaid-svg-S55LVPBXIZ86uI7X .marker.cross{stroke:#333333;}#mermaid-svg-S55LVPBXIZ86uI7X svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-S55LVPBXIZ86uI7X p{margin:0;}#mermaid-svg-S55LVPBXIZ86uI7X .edge{stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .section--1 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section--1 path,#mermaid-svg-S55LVPBXIZ86uI7X .section--1 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section--1 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section--1 path{fill:hsl(240, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section--1 text{fill:#ffffff;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon--1{font-size:40px;color:#ffffff;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge--1{stroke:hsl(240, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth--1{stroke-width:17;}#mermaid-svg-S55LVPBXIZ86uI7X .section--1 line{stroke:hsl(60, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-0 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-0 path,#mermaid-svg-S55LVPBXIZ86uI7X .section-0 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-0 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section-0 path{fill:hsl(60, 100%, 73.5294117647%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-0 text{fill:black;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon-0{font-size:40px;color:black;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge-0{stroke:hsl(60, 100%, 73.5294117647%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth-0{stroke-width:14;}#mermaid-svg-S55LVPBXIZ86uI7X .section-0 line{stroke:hsl(240, 100%, 83.5294117647%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-1 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-1 path,#mermaid-svg-S55LVPBXIZ86uI7X .section-1 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-1 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section-1 path{fill:hsl(80, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-1 text{fill:black;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon-1{font-size:40px;color:black;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge-1{stroke:hsl(80, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth-1{stroke-width:11;}#mermaid-svg-S55LVPBXIZ86uI7X .section-1 line{stroke:hsl(260, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-2 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-2 path,#mermaid-svg-S55LVPBXIZ86uI7X .section-2 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-2 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section-2 path{fill:hsl(270, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-2 text{fill:#ffffff;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon-2{font-size:40px;color:#ffffff;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge-2{stroke:hsl(270, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth-2{stroke-width:8;}#mermaid-svg-S55LVPBXIZ86uI7X .section-2 line{stroke:hsl(90, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-3 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-3 path,#mermaid-svg-S55LVPBXIZ86uI7X .section-3 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-3 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section-3 path{fill:hsl(300, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-3 text{fill:black;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon-3{font-size:40px;color:black;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge-3{stroke:hsl(300, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth-3{stroke-width:5;}#mermaid-svg-S55LVPBXIZ86uI7X .section-3 line{stroke:hsl(120, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-4 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-4 path,#mermaid-svg-S55LVPBXIZ86uI7X .section-4 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-4 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section-4 path{fill:hsl(330, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-4 text{fill:black;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon-4{font-size:40px;color:black;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge-4{stroke:hsl(330, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth-4{stroke-width:2;}#mermaid-svg-S55LVPBXIZ86uI7X .section-4 line{stroke:hsl(150, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-5 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-5 path,#mermaid-svg-S55LVPBXIZ86uI7X .section-5 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-5 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section-5 path{fill:hsl(0, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-5 text{fill:black;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon-5{font-size:40px;color:black;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge-5{stroke:hsl(0, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth-5{stroke-width:-1;}#mermaid-svg-S55LVPBXIZ86uI7X .section-5 line{stroke:hsl(180, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-6 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-6 path,#mermaid-svg-S55LVPBXIZ86uI7X .section-6 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-6 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section-6 path{fill:hsl(30, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-6 text{fill:black;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon-6{font-size:40px;color:black;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge-6{stroke:hsl(30, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth-6{stroke-width:-4;}#mermaid-svg-S55LVPBXIZ86uI7X .section-6 line{stroke:hsl(210, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-7 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-7 path,#mermaid-svg-S55LVPBXIZ86uI7X .section-7 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-7 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section-7 path{fill:hsl(90, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-7 text{fill:black;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon-7{font-size:40px;color:black;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge-7{stroke:hsl(90, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth-7{stroke-width:-7;}#mermaid-svg-S55LVPBXIZ86uI7X .section-7 line{stroke:hsl(270, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-8 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-8 path,#mermaid-svg-S55LVPBXIZ86uI7X .section-8 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-8 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section-8 path{fill:hsl(150, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-8 text{fill:black;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon-8{font-size:40px;color:black;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge-8{stroke:hsl(150, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth-8{stroke-width:-10;}#mermaid-svg-S55LVPBXIZ86uI7X .section-8 line{stroke:hsl(330, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-9 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-9 path,#mermaid-svg-S55LVPBXIZ86uI7X .section-9 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-9 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section-9 path{fill:hsl(180, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-9 text{fill:black;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon-9{font-size:40px;color:black;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge-9{stroke:hsl(180, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth-9{stroke-width:-13;}#mermaid-svg-S55LVPBXIZ86uI7X .section-9 line{stroke:hsl(0, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-10 rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-10 path,#mermaid-svg-S55LVPBXIZ86uI7X .section-10 circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-10 polygon,#mermaid-svg-S55LVPBXIZ86uI7X .section-10 path{fill:hsl(210, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-10 text{fill:black;}#mermaid-svg-S55LVPBXIZ86uI7X .node-icon-10{font-size:40px;color:black;}#mermaid-svg-S55LVPBXIZ86uI7X .section-edge-10{stroke:hsl(210, 100%, 76.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .edge-depth-10{stroke-width:-16;}#mermaid-svg-S55LVPBXIZ86uI7X .section-10 line{stroke:hsl(30, 100%, 86.2745098039%);stroke-width:3;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled,#mermaid-svg-S55LVPBXIZ86uI7X .disabled circle,#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:lightgray;}#mermaid-svg-S55LVPBXIZ86uI7X .disabled text{fill:#efefef;}#mermaid-svg-S55LVPBXIZ86uI7X .section-root rect,#mermaid-svg-S55LVPBXIZ86uI7X .section-root path,#mermaid-svg-S55LVPBXIZ86uI7X .section-root circle,#mermaid-svg-S55LVPBXIZ86uI7X .section-root polygon{fill:hsl(240, 100%, 46.2745098039%);}#mermaid-svg-S55LVPBXIZ86uI7X .section-root text{fill:#ffffff;}#mermaid-svg-S55LVPBXIZ86uI7X .section-root span{color:#ffffff;}#mermaid-svg-S55LVPBXIZ86uI7X .section-2 span{color:#ffffff;}#mermaid-svg-S55LVPBXIZ86uI7X .icon-container{height:100%;display:flex;justify-content:center;align-items:center;}#mermaid-svg-S55LVPBXIZ86uI7X .edge{fill:none;}#mermaid-svg-S55LVPBXIZ86uI7X .mindmap-node-label{dy:1em;alignment-baseline:middle;text-anchor:middle;dominant-baseline:middle;text-align:center;}#mermaid-svg-S55LVPBXIZ86uI7X :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} DeepSeek

Harness
要解决的问题
模型不等于 Agent
能力被焊死在产品里
黑盒无法审计
换一个部件要换整个产品
核心概念
插件与上下文
服务与可撤销效果
类型化事件
Profile 与 Bundle
Agent Preset
会话日志
Turn 与 Step
能力接缝
关键角色
Cordis 内核
管挂载与依赖
组装层
决定启动什么树
会话日志
唯一真相源
Agent Loop
驱动回合与步骤
系统提示装配
决定模型看见什么
LLM 适配器
对接厂商协议
工具注册表
调度与放行工具
能力接缝
文件 命令 沙箱 审批
运行示例
一句话改 README 并跑 lint
关键流程
正常回合
审批与沙箱
失败与压缩恢复

阅读地图

#mermaid-svg-vWPO6nJ2bsFVMzHz{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-vWPO6nJ2bsFVMzHz .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-vWPO6nJ2bsFVMzHz .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-vWPO6nJ2bsFVMzHz .error-icon{fill:#552222;}#mermaid-svg-vWPO6nJ2bsFVMzHz .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-vWPO6nJ2bsFVMzHz .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-vWPO6nJ2bsFVMzHz .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-vWPO6nJ2bsFVMzHz .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-vWPO6nJ2bsFVMzHz .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-vWPO6nJ2bsFVMzHz .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-vWPO6nJ2bsFVMzHz .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-vWPO6nJ2bsFVMzHz .marker{fill:#333333;stroke:#333333;}#mermaid-svg-vWPO6nJ2bsFVMzHz .marker.cross{stroke:#333333;}#mermaid-svg-vWPO6nJ2bsFVMzHz svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-vWPO6nJ2bsFVMzHz p{margin:0;}#mermaid-svg-vWPO6nJ2bsFVMzHz .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-vWPO6nJ2bsFVMzHz .cluster-label text{fill:#333;}#mermaid-svg-vWPO6nJ2bsFVMzHz .cluster-label span{color:#333;}#mermaid-svg-vWPO6nJ2bsFVMzHz .cluster-label span p{background-color:transparent;}#mermaid-svg-vWPO6nJ2bsFVMzHz .label text,#mermaid-svg-vWPO6nJ2bsFVMzHz span{fill:#333;color:#333;}#mermaid-svg-vWPO6nJ2bsFVMzHz .node rect,#mermaid-svg-vWPO6nJ2bsFVMzHz .node circle,#mermaid-svg-vWPO6nJ2bsFVMzHz .node ellipse,#mermaid-svg-vWPO6nJ2bsFVMzHz .node polygon,#mermaid-svg-vWPO6nJ2bsFVMzHz .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-vWPO6nJ2bsFVMzHz .rough-node .label text,#mermaid-svg-vWPO6nJ2bsFVMzHz .node .label text,#mermaid-svg-vWPO6nJ2bsFVMzHz .image-shape .label,#mermaid-svg-vWPO6nJ2bsFVMzHz .icon-shape .label{text-anchor:middle;}#mermaid-svg-vWPO6nJ2bsFVMzHz .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-vWPO6nJ2bsFVMzHz .rough-node .label,#mermaid-svg-vWPO6nJ2bsFVMzHz .node .label,#mermaid-svg-vWPO6nJ2bsFVMzHz .image-shape .label,#mermaid-svg-vWPO6nJ2bsFVMzHz .icon-shape .label{text-align:center;}#mermaid-svg-vWPO6nJ2bsFVMzHz .node.clickable{cursor:pointer;}#mermaid-svg-vWPO6nJ2bsFVMzHz .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-vWPO6nJ2bsFVMzHz .arrowheadPath{fill:#333333;}#mermaid-svg-vWPO6nJ2bsFVMzHz .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-vWPO6nJ2bsFVMzHz .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-vWPO6nJ2bsFVMzHz .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-vWPO6nJ2bsFVMzHz .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-vWPO6nJ2bsFVMzHz .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-vWPO6nJ2bsFVMzHz .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-vWPO6nJ2bsFVMzHz .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-vWPO6nJ2bsFVMzHz .cluster text{fill:#333;}#mermaid-svg-vWPO6nJ2bsFVMzHz .cluster span{color:#333;}#mermaid-svg-vWPO6nJ2bsFVMzHz div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-vWPO6nJ2bsFVMzHz .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-vWPO6nJ2bsFVMzHz rect.text{fill:none;stroke-width:0;}#mermaid-svg-vWPO6nJ2bsFVMzHz .icon-shape,#mermaid-svg-vWPO6nJ2bsFVMzHz .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-vWPO6nJ2bsFVMzHz .icon-shape p,#mermaid-svg-vWPO6nJ2bsFVMzHz .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-vWPO6nJ2bsFVMzHz .icon-shape .label rect,#mermaid-svg-vWPO6nJ2bsFVMzHz .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-vWPO6nJ2bsFVMzHz .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-vWPO6nJ2bsFVMzHz .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-vWPO6nJ2bsFVMzHz :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 第三部分 · 缝合
12 完整重演

  • 动手练习
    第二部分 · 拆开八个角色
    04 Cordis 内核
    05 组装层
    06 会话日志
    07 Agent Loop
    08 系统提示装配
    09 LLM 接缝
    10 工具管线
    11 能力接缝
    第一部分 · 建立坐标系
    01 为什么需要 harness
    02 DSH 是什么
    03 概念地图

  • 运行示例

文章列表与 CSDN 发布状态

第一部分 · 建立坐标系

01 · 为什么需要 harness：模型再强，也不会自己去读文件

模型交付的只有 token，可 Agent 需要的是"看环境、动手、还能接着干"；2023---2025 年这层壳是怎么长出来的、又是怎么被焊死在各家产品里的；为什么"换一个模型/换一个沙箱/换一个循环"这三件事在闭源产品里都做不到；以及评测复现这个被低估的痛点。

02 · DeepSeek Harness 是什么：定义、边界与生态位置

一句话定义拆解；"Everything is a plugin. Every run is traceable." 两句设计信条各自换来什么；它不是模型、不是 IDE、不是又一个 Agent 编排 SDK；与 Claude Code / Codex / LangGraph / MCP 的关系（它甚至可以把前两者当子代理调用）；四个 preset 的定位。

03 · 概念地图：八个概念、八个角色、一个运行示例

插件与上下文、服务与可撤销效果、类型化事件、Profile/Bundle、Agent Preset、会话日志、Turn/Step、能力接缝------八个概念按依赖顺序串起来；八个关键角色各自的"唯一职责 / 知道什么 / 刻意不做什么"；协作总览图；以及贯穿全系列的运行示例的完整定义与 12 步浅层追踪。

第二部分 · 拆开八个角色

04 · Cordis 内核：为什么"一切皆插件"不是口号

五个概念撑起整个内核：插件即服务、上下文即服务仓库、inject 声明依赖、类型化事件、注册即可撤销效果。emit/waterfall/parallel/serial 四种派发模式各自的语义；waterfall 的 next() 为什么是 around 中间件；以及"没有特权核心可打补丁"这句话的实际后果。

  • 中文版（本专栏尚未发布）

05 · 组装层：Profile、Bundle、Patch 与 Agent Preset

启动时的插件树是从空列表叠出来的：bundle 层 → profile 补丁 → home 补丁 → --patch 覆盖层。dsh --dump-config 为什么是这个项目最该先跑的命令；宿主平面 vs 代理平面 这条分界线（谁能拥有注册表、谁只能拥有工具）；一个 preset 为什么必须待在带 isolate 的 group 里。

  • 中文版（本专栏尚未发布）

06 · 会话日志：唯一真相源，以及"模型可见即已记录"

SessionEvent 事件表逐条读；消息历史是派生 出来的而不是存下来的；turn/*、step/*、user/message、assistant/chunk、assistant/message、tool/call、tool/result 各自记什么；为什么连原始流式分片都要落盘；以及那条运行时不变量：任何进入模型请求的东西都必须能从日志重建。

  • 中文版（本专栏尚未发布）

07 · Agent Loop：一个 turn 到底发生了什么

turn 与 step 的精确定义；inbox 的两条队列（next-turn / next-step）与 followup/steer/inject 三个别名；agent/pre-step 这个"决定模型看见什么"的 waterfall；工具调用的并发调度（barrier 与滚动池）；取消、错误恢复与压缩重试如何在同一条时间线上共存。

  • 中文版（本专栏尚未发布）

08 · 系统提示装配：模型看见的前缀是被"拼"出来的

PromptSection 的 order 约定（-100 身份、0 人格、100--199 工具指引）；complete 段落如何独占整个系统提示；PromptContext 为什么要和 section 分开------它关系到 KV Cache 命中率；工具 schema 如何在装配期被挑选、被 scope 遮蔽（shadowing）、被 restriction 过滤。

  • 中文版（本专栏尚未发布）

09 · LLM 接缝：把"厂商协议"关进一个可替换的盒子

LlmAdapter 的适配器契约逐条读：usage 必须在 finish 之前、工具参数全程保持原始 JSON 字符串、两条错误路径一个失败类型、一次适配器调用就是一次厂商尝试；llm/stream waterfall 为什么在适配器查找之前；空回复为什么被判定为可重试错误；以及 replay 状态（推理链复用）的归属规则。

  • 中文版（本专栏尚未发布）

10 · 工具注册表与执行管线：一次工具调用要过五道关

ToolDefinition 的字段分层（哪些给模型看、哪些绝不能泄漏进请求）；pre-execute → 单调守卫 → execute → post-execute → finalizeContent → result 五段管线各自能改什么；allow/deny/ask 三态决策与失败即拒绝；并发安全声明 isConcurrencySafe；Code Mode 下"模型直呼原生工具"为什么被直接拒绝。

  • 中文版（本专栏尚未发布）

11 · 能力接缝：文件、命令、沙箱、审批、子代理

接缝的三个角色（服务定义 / 提供者 / 消费者）为什么缺一不可；一次 provider 替换如何把 Bash、PTY、LSP 一起搬到远程沙箱；SandboxMode 三档策略与"部分执行"这个诚实的事实；审批为什么是 fail-closed 的；子代理接缝如何把 Claude Code 和 Codex 变成可调用的孩子。

  • 中文版（本专栏尚未发布）

第三部分 · 缝合

12 · 完整重演：一句话请求的完整旅程 + 动手练习

从你按下回车到它回出总结，一条连续时间线串起全部十一篇；随后是七个动手练习，每个验证一篇文章的一个具体论断；最后是一页速查卡片。

  • 中文版（本专栏尚未发布）

勾选框表示已完成中文稿。建议阅读顺序即编号顺序；只想知道"这东西值不值得看"的读者，读 01 + 02 即可；已经在做 Agent 框架的读者可以从 03 直接切入，再挑 04/07/10 三篇。

相关推荐
smartpi_ai1 小时前
空调内机做语音控制选哪颗?CI-03T 的红外码库优势、“5V 供电≠3.3V 串口“的电平误区与声学结构规范
人工智能·ci/cd·语音识别
白帽黑客-晨哥1 小时前
Copilot 能换成本地吗？本地化 AI 编程助手完全指南
数据库·人工智能·copilot
adaierya1 小时前
用 AI 解决音频转换编程问题
开发语言·人工智能·python·分类·ai编程
ai小陈1 小时前
PyTorch梯度累积与裁剪实战：小显存也能稳定训练大批次
人工智能·pytorch·python·深度学习·ai·gpu算力
心易行者1 小时前
用HTML在线运行搭后台管理系统：5个核心模块+0服务器，3天跑通完整业务
大数据·前端·网络·人工智能·python
CubeSandbox1 小时前
Cube Sandbox 受邀亮相 Arm Create 上海站：金峰将参与“领袖对谈”，共话 AI Agent 执行层
arm开发·人工智能·cube sandbox
通问AI1 小时前
【实战】多模态图像模型批量生成电商主图：Prompt 模板化与自动化质检方案
人工智能·自动化·prompt
易知微EasyV数据可视化1 小时前
从一个 SVG 清洗工具开始：设计师 howto 零帧起手开发 Figma 插件
人工智能·figma
kaixin_啊啊1 小时前
中国研究生数学建模竞赛（华为杯）学习笔记——数据预处理全流程
人工智能·笔记·学习·数学建模·ai·大模型·数据预处理
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02如何新建文件夹？ 电脑新建文件夹的4种方法03GitHub 镜像站点04历年考研数学一、数学二、数学三真题试卷及答案PDF05蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接06微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？08ZCode 周末送额度活动开启：3 亿 Token 免费领取09Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费10AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路