【agent应用】DeepSeek Harness (dsh)介绍及安装部署（Ubuntu24.04）使用指南

DeepSeek Harness (dsh) 是一个为构建、运行和调试 AI 智能体（Agent）而设计的开源框架 。它的核心理念是 "一切皆插件" ，旨在解决传统 Agent 框架"黑盒"且难以定制的问题。

🧩 核心架构：一切皆插件

传统 Agent 框架通常有一个固定的"核心"，你只能在外部添加工具，无法修改核心本身。而 DeepSeek Harness 的架构完全不同，它的"核心"只是一个空壳，所有能力都是可以自由替换和重组的插件。

1. 🏛️ Cordis 内核：一个"什么都不干"的底层框架

Harness 的底层是一个名为 Cordis 的插件框架。它就像一个精密的"接线板"和"调度中心"，只负责三件事：

加载与卸载插件。
管理插件之间的依赖关系。
提供服务与事件机制，让插件之间可以相互协作。

Cordis 本身不承载任何 AI 能力，从而保证了系统的极度灵活与纯净。

2. 🧱 插件提供能力：所有模块都可插拔

在 Cordis 内核之上，Harness 的所有功能都以插件形式存在。
#mermaid-svg-dlsQTcqsL510YAox{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-dlsQTcqsL510YAox .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-dlsQTcqsL510YAox .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-dlsQTcqsL510YAox .error-icon{fill:#552222;}#mermaid-svg-dlsQTcqsL510YAox .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-dlsQTcqsL510YAox .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-dlsQTcqsL510YAox .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-dlsQTcqsL510YAox .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-dlsQTcqsL510YAox .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-dlsQTcqsL510YAox .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-dlsQTcqsL510YAox .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-dlsQTcqsL510YAox .marker{fill:#333333;stroke:#333333;}#mermaid-svg-dlsQTcqsL510YAox .marker.cross{stroke:#333333;}#mermaid-svg-dlsQTcqsL510YAox svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-dlsQTcqsL510YAox p{margin:0;}#mermaid-svg-dlsQTcqsL510YAox .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-dlsQTcqsL510YAox .cluster-label text{fill:#333;}#mermaid-svg-dlsQTcqsL510YAox .cluster-label span{color:#333;}#mermaid-svg-dlsQTcqsL510YAox .cluster-label span p{background-color:transparent;}#mermaid-svg-dlsQTcqsL510YAox .label text,#mermaid-svg-dlsQTcqsL510YAox span{fill:#333;color:#333;}#mermaid-svg-dlsQTcqsL510YAox .node rect,#mermaid-svg-dlsQTcqsL510YAox .node circle,#mermaid-svg-dlsQTcqsL510YAox .node ellipse,#mermaid-svg-dlsQTcqsL510YAox .node polygon,#mermaid-svg-dlsQTcqsL510YAox .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-dlsQTcqsL510YAox .rough-node .label text,#mermaid-svg-dlsQTcqsL510YAox .node .label text,#mermaid-svg-dlsQTcqsL510YAox .image-shape .label,#mermaid-svg-dlsQTcqsL510YAox .icon-shape .label{text-anchor:middle;}#mermaid-svg-dlsQTcqsL510YAox .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-dlsQTcqsL510YAox .rough-node .label,#mermaid-svg-dlsQTcqsL510YAox .node .label,#mermaid-svg-dlsQTcqsL510YAox .image-shape .label,#mermaid-svg-dlsQTcqsL510YAox .icon-shape .label{text-align:center;}#mermaid-svg-dlsQTcqsL510YAox .node.clickable{cursor:pointer;}#mermaid-svg-dlsQTcqsL510YAox .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-dlsQTcqsL510YAox .arrowheadPath{fill:#333333;}#mermaid-svg-dlsQTcqsL510YAox .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-dlsQTcqsL510YAox .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-dlsQTcqsL510YAox .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-dlsQTcqsL510YAox .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-dlsQTcqsL510YAox .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-dlsQTcqsL510YAox .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-dlsQTcqsL510YAox .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-dlsQTcqsL510YAox .cluster text{fill:#333;}#mermaid-svg-dlsQTcqsL510YAox .cluster span{color:#333;}#mermaid-svg-dlsQTcqsL510YAox 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-dlsQTcqsL510YAox .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-dlsQTcqsL510YAox rect.text{fill:none;stroke-width:0;}#mermaid-svg-dlsQTcqsL510YAox .icon-shape,#mermaid-svg-dlsQTcqsL510YAox .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-dlsQTcqsL510YAox .icon-shape p,#mermaid-svg-dlsQTcqsL510YAox .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-dlsQTcqsL510YAox .icon-shape .label rect,#mermaid-svg-dlsQTcqsL510YAox .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-dlsQTcqsL510YAox .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-dlsQTcqsL510YAox .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-dlsQTcqsL510YAox :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-dlsQTcqsL510YAox .kernel>*{fill:#8B5CF6!important;stroke:#5B21B6!important;stroke-width:3px!important;color:#fff!important;font-weight:bold!important;}#mermaid-svg-dlsQTcqsL510YAox .kernel span{fill:#8B5CF6!important;stroke:#5B21B6!important;stroke-width:3px!important;color:#fff!important;font-weight:bold!important;}#mermaid-svg-dlsQTcqsL510YAox .kernel tspan{fill:#fff!important;}#mermaid-svg-dlsQTcqsL510YAox .plugin>*{fill:#3B82F6!important;stroke:#1E40AF!important;stroke-width:2px!important;color:#fff!important;}#mermaid-svg-dlsQTcqsL510YAox .plugin span{fill:#3B82F6!important;stroke:#1E40AF!important;stroke-width:2px!important;color:#fff!important;}#mermaid-svg-dlsQTcqsL510YAox .plugin tspan{fill:#fff!important;}#mermaid-svg-dlsQTcqsL510YAox .pluginAlt>*{fill:#10B981!important;stroke:#047857!important;stroke-width:2px!important;color:#fff!important;}#mermaid-svg-dlsQTcqsL510YAox .pluginAlt span{fill:#10B981!important;stroke:#047857!important;stroke-width:2px!important;color:#fff!important;}#mermaid-svg-dlsQTcqsL510YAox .pluginAlt tspan{fill:#fff!important;}#mermaid-svg-dlsQTcqsL510YAox .pluginSpecial>*{fill:#F59E0B!important;stroke:#B45309!important;stroke-width:2px!important;color:#fff!important;}#mermaid-svg-dlsQTcqsL510YAox .pluginSpecial span{fill:#F59E0B!important;stroke:#B45309!important;stroke-width:2px!important;color:#fff!important;}#mermaid-svg-dlsQTcqsL510YAox .pluginSpecial tspan{fill:#fff!important;} 🔌 DeepSeek Harness 插件化架构
⚙️ Cordis 内核

仅负责加载、卸载与依赖管理
🧠 模型适配器
🔧 工具注册表
💾 会话与存储
🔒 沙箱与权限
🔄 Agent 循环
📅 调度与任务
🖥️ 用户界面

Web / TUI
📦 更多插件...

3. ⚙️ 配置层自由组合：像搭乐高一样拼装 Agent

这是"一切皆插件"给开发者带来的最大便利：你无需修改 Harness 的任何一行源码，仅仅通过修改配置文件，就可以选择、替换或扩展任何一个插件。你可以像搭乐高积木一样，自由组合出符合自己需求的 Agent。

4. 📜 理论基石：Cordis 的"时空可组合性"

这套灵活的架构并非凭空而来，它有坚实的理论基础------Cordis 论文提出的 "时空可组合性" 编程范式：

时间可组合性 (可逆效应) ：当一个插件被卸载时，系统能完整地回滚它产生的所有副作用，就像它从未运行过一样。这为实现热插拔 和热替换 (HMR) 提供了安全保障。
空间可组合性 (反应式余效应)：当系统上下文发生变化时，能主动通知所有相关的组件。这让插件之间可以基于事件进行响应和协作。

👣 运行有迹可循：告别 Agent "黑盒"

Agent 的思考过程往往难以追踪，而 DeepSeek Harness 通过其会话日志系统解决了这个问题。

1. 📝 仅追加的会话日志

系统会以"仅追加"的方式，记录下一次运行中模型"看到"和"做过"的一切：

输入：系统提示词 (System Prompts)。
思考：模型的思维链 (Chain of Thought)。
行动：每一次工具调用及其结果。
调度：子 Agent 的调度情况。
上下文：每一次上下文注入的内容。

2. 🔍 Trajectory 视图

这些记录会形成一个完整的事件流，你可以在 Web UI 的 Trajectory 视图 中清晰地按来源查看这些信息。更重要的是，会话恢复、分叉、检索与回放 等功能都基于这同一份数据，确保了 Agent 行为的完全可审计、可复现。
#mermaid-svg-chn77uv06UinZIJI{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-chn77uv06UinZIJI .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-chn77uv06UinZIJI .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-chn77uv06UinZIJI .error-icon{fill:#552222;}#mermaid-svg-chn77uv06UinZIJI .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-chn77uv06UinZIJI .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-chn77uv06UinZIJI .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-chn77uv06UinZIJI .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-chn77uv06UinZIJI .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-chn77uv06UinZIJI .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-chn77uv06UinZIJI .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-chn77uv06UinZIJI .marker{fill:#333333;stroke:#333333;}#mermaid-svg-chn77uv06UinZIJI .marker.cross{stroke:#333333;}#mermaid-svg-chn77uv06UinZIJI svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-chn77uv06UinZIJI p{margin:0;}#mermaid-svg-chn77uv06UinZIJI .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-chn77uv06UinZIJI .cluster-label text{fill:#333;}#mermaid-svg-chn77uv06UinZIJI .cluster-label span{color:#333;}#mermaid-svg-chn77uv06UinZIJI .cluster-label span p{background-color:transparent;}#mermaid-svg-chn77uv06UinZIJI .label text,#mermaid-svg-chn77uv06UinZIJI span{fill:#333;color:#333;}#mermaid-svg-chn77uv06UinZIJI .node rect,#mermaid-svg-chn77uv06UinZIJI .node circle,#mermaid-svg-chn77uv06UinZIJI .node ellipse,#mermaid-svg-chn77uv06UinZIJI .node polygon,#mermaid-svg-chn77uv06UinZIJI .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-chn77uv06UinZIJI .rough-node .label text,#mermaid-svg-chn77uv06UinZIJI .node .label text,#mermaid-svg-chn77uv06UinZIJI .image-shape .label,#mermaid-svg-chn77uv06UinZIJI .icon-shape .label{text-anchor:middle;}#mermaid-svg-chn77uv06UinZIJI .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-chn77uv06UinZIJI .rough-node .label,#mermaid-svg-chn77uv06UinZIJI .node .label,#mermaid-svg-chn77uv06UinZIJI .image-shape .label,#mermaid-svg-chn77uv06UinZIJI .icon-shape .label{text-align:center;}#mermaid-svg-chn77uv06UinZIJI .node.clickable{cursor:pointer;}#mermaid-svg-chn77uv06UinZIJI .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-chn77uv06UinZIJI .arrowheadPath{fill:#333333;}#mermaid-svg-chn77uv06UinZIJI .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-chn77uv06UinZIJI .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-chn77uv06UinZIJI .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-chn77uv06UinZIJI .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-chn77uv06UinZIJI .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-chn77uv06UinZIJI .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-chn77uv06UinZIJI .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-chn77uv06UinZIJI .cluster text{fill:#333;}#mermaid-svg-chn77uv06UinZIJI .cluster span{color:#333;}#mermaid-svg-chn77uv06UinZIJI 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-chn77uv06UinZIJI .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-chn77uv06UinZIJI rect.text{fill:none;stroke-width:0;}#mermaid-svg-chn77uv06UinZIJI .icon-shape,#mermaid-svg-chn77uv06UinZIJI .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-chn77uv06UinZIJI .icon-shape p,#mermaid-svg-chn77uv06UinZIJI .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-chn77uv06UinZIJI .icon-shape .label rect,#mermaid-svg-chn77uv06UinZIJI .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-chn77uv06UinZIJI .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-chn77uv06UinZIJI .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-chn77uv06UinZIJI :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 运行过程记录
Agent 运行
系统提示词
思维链
工具调用与结果
子 Agent 调度
上下文注入
📄 仅追加的

会话日志
Trajectory 视图
会话恢复
执行分叉
过程回放

🎮 四种运行模式：应对不同场景

DeepSeek Harness 内置了四种运行模式，本质上是四种不同的插件组合预设。

模式	核心特点	适用场景
标准模式	功能完整的编码 Agent，包含文件编辑、Shell、文件与网页检索、Skills、计划、子代理等全套工具。	日常的复杂编程与自动化任务。
PTC 模式	具备标准模式的全部能力，并允许模型生成一个 TypeScript 程序来组合多步工具调用。	需要模型进行复杂规划和逻辑编排的任务。
极简模式	仅提供持久 bash 与 str_replace_editor 两个核心工具。	最小化环境下的模型基准测试。
创造模式	用于创建自定义 Agent 预设。具备标准模式能力，并提供运行时检查、插件实验和创作指导。	高级开发者探索和构建自己的专属模式。

🚀 快速开始（Ubuntu24.04上安装了下）

1. 快速体验 (通过 npx)

这是最快捷的方式，适合初步体验。在已安装 Node.js 的环境中，直接运行以下命令即可启动 Web UI：

bash 复制代码

npx @deepseek-ai/dsh web

该命令会启动 Web UI，默认访问地址为 http://127.0.0.1:3080。

如下图所示：

注如果下载时网络超时可以做如下配置。

bash 复制代码

npm config set registry https://registry.npmmirror.com

2. 源码安装 (推荐开发者)

如果你想进行深度开发或阅读源码，推荐从源码安装：

bash 复制代码

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

💎 总结

DeepSeek Harness 不仅仅是一个工具，更是一种构建 Agent 的新范式 。它将控制权完全交还给开发者，通过"一切皆插件"的架构，让你能够精确掌控 Agent 的每一个环节，并清晰地洞察其运行的每一步。

对开发者：它提供了一个极致灵活、可定制的"工坊"。
对社区：它开创了一个真正由社区驱动、共同演进的生态系统。