> **来源：[研报客](https://pc.yanbaoke.cn)** # DeepSeek Harness 白皮书总结 ## 核心内容概览 DeepSeek Harness（dsh）是 DeepSeek 官方开源的 Agent 运行时，采用“一切皆插件”架构，基于 Cordis 插件容器构建。它为开发者提供了一个灵活、可定制的平台，使他们能够自由拼装各种功能插件，从而构建个性化的 Agent 系统。 ## 主要观点 - **dsh 是 Agent 的乐高底座**：提供运行时 + 核心插件，开发者可以自由拼装插件，定制行为。 - **harness 是模型外面的工程层**：包含会话管理、工具调用、上下文控制、错误恢复等，让模型在代码仓库中真正干活。 - **与 Claude Code 的区别**：Claude Code 是“整车”，而 dsh 是“底座 + 积木”，可定制性更高。 - **生态窗口**：2026 年 8 月 13 日开源，中文教程此前为零，现在是早期入场的时机。 - **适用人群**：适合想要深度定制、玩生态、在 CI 中运行 Agent 的开发者；开箱即用的选 Claude Code。 ## 关键信息 ### 功能与架构 - **支持的运行模式**：web（Web UI）、headless（CLI）、tui（终端 UI，需插件）、creator（插件开发）。 - **插件系统**：一切能力都是插件，开发者可以通过插件扩展功能。 - **配置结构**：通过 `settings.yaml` 配置模型和推理档位，通过 `cordis.patch.yml` 挂载插件。 - **扩展点**：包括 `agent/request`、`conversationEvents.register`、`ctx.slots.inject`、`settings` 服务等，用于改行为，而非 fork 核心。 ### 性能与生态 - **推理档位**：`off`（最快）、`low`（适合简单任务）、`high`（默认）、`max`（适合复杂推理）。 - **性能模型**：模型在每次工具调用前重新思考，占约 90% 的时间，调低档位可显著提速。 - **生态阶段**：目前处于早期阶段，但有官方鼓励社区参与，提供丰富的插件生态。 ### 与主流 Agent 的对比 | 维度 | dsh | Claude Code | OpenAI Codex | OpenCode | Gemini CLI | Kimi CLI | |--------------|-----------------------------------|--------------------------|--------------------------|--------------------------|----------------------|-----------------------| | 开源 | √ MIT | ✕ 闭源 | ✕ 闭源 | √ MIT | ✕ 闭源 | ✕ 闭源 | | 模型绑定 | 模型无关（适配 DeepSeek V4 系） | 绑定 Claude 模型 | 绑定 GPT 模型 | 可配任意模型 | 绑定 Gemini 模型 | 绑定 Kimi 模型 | | 插件体系 | 官方级：一切皆插件，60+ 官方包 | 配置/钩子为主 | 配置为主 | 配置为主 | 无 | 无 | | 自定义界面 | 支持（client 半） | 不支持 | 不支持 | 部分支持（TUI） | 不支持 | 支持 | | 自动化/CI | 支持（headless profile） | 支持 | 支持 | 支持 | 支持 | 支持 | | TUI | 插件可做 | 内置 | 内置 | 内置 | 内置 | 支持 | | 生态阶段 | 零日起步（2026-08-13） | 成熟 | 成熟 | 成熟 | 成熟 | 早期 | | 适合谁 | 想深度定制 + 玩生态 + 跑 CI 的开发者 | 开箱即用 | 开箱即用 | 熟悉 OpenCode 的用户 | Google 生态 | Kimi 生态 | ### 案例对比：任务执行方式 | Agent | 你会怎么做 | 体验 | |---------------|------------------------------------|--------------------------| | dsh (web) | dsh web → 输入指令 → 模型用 Grep/Read/Edit 工具完成 | Web UI + 插件侧边栏 | | dsh (headless)| dsh --profile headless "任务" → 打印结果退出 | 可进 CI，脚本友好 | | Claude Code | 打开 TUI → 输入指令 → 模型完成 | 终端 TUI，开箱即用 | | Cursor | 在 IDE 里选中代码 → 输入指令 | IDE 内嵌体验 | | Devin | 网页里建任务 → 云上完成 | 托管、有浏览器、数据出本机 | | Aider | 专注“改代码 + Git” | 极简主义者 | | Qwen Code | 阿里通义 coding agent CLI | 主打 Qwen 模型 | | GLM CLI | 智谱 coding agent CLI | 主打 GLM 模型 | | Grok CLI | xAI 终端 coding agent | 主打 Grok 模型 | ### 案例对比：真实工作流 | 场景 | dsh 实测 | 备注 | |--------------|--------------------------------------|-------------------------------| | 简单文件创建 | 冷启动 ~110s → 热缓存 ~1s | 思考占 ~90% 墙钟时间 | | 50 步工具链任务 | LLM 耗时 10m+，工具调用 9m+ | 提速插件价值在此 | | 插件开发 | 从零到可运行插件：1 天（含测试+实机验证） | 扩展点清晰（agent/request waterfall） | | 与 Claude Code 同任务 | dsh 配 V4-Flash 成本约为 Claude 的 1/10~1/30 | 价格维度 dsh 生态显著占优 | ## 学习路径与原则 ### 3 天学习计划 - **Day 1**：理解 dsh 是什么，能独立启动、对话、配置。 - **Day 2**：理解 profile/插件机制，写出第一个能跑的插件。 - **Day 3**：能评估插件质量、调优性能、理解生态玩法。 ### 学习原则 1. **动手 > 阅读**：每章命令都跑一遍，不看会后悔。 2. **先复制后理解**：第 4 章完整代码先跑通，再改参数理解机制。 3. **单测 + 实机双证据**：开发插件时两个都要过。 4. **善用 --dump-config**：疑惑时看合成配置，比猜快。 ## 安装与运行 ### 安装方式 1. **方式一：直接运行（推荐新手）** `npx -y @deepseek-ai/dsh web` → `http://127.0.0.1:3080` 2. **方式二：全局安装（推荐频繁使用）** `npm install -g @deepseek-ai/dsh` 3. **方式三：免装 Node 的安装包（新手可选）** 提供 mac DMG / Windows exe，自带 Node 运行时。 ### 常见安装坑 - **首次 npx 极慢（Windows）**：建议使用 `npm install -g`。 - **pnpm dlx 404**：建议使用 `npx` 或 `npm install -g`。 - **macOS 全局安装解析不到插件**：建议使用 `npm i -g` 或 `npx`。 - **Node < 22.19**：会触发两个致命缺失，建议升级 Node.js 到 ≥22.19。 ### 命令速查 | 命令 | 用途 | |---------------------------|------------------------------| | `dsh web` | 启动 Web UI | | `dsh --profile headless "任务"` | 一次性任务，打印结果退出 | | `dsh plugin --profile add` | 给 profile 安装插件 | | `dsh --dump-config` | 打印合成配置树 | | `dsh --profile tui` | TUI 模式（需先安装插件） | | `dsh --version` | 查看版本 | ### 排障速查 | 现象 | 原因与解法 | |------------------------------|--------------------------------------| | `dsh: profile "tui" does not exist` | tui profile 需插件创建 | | npx 极慢 | 首次下载包体大；建议使用 `npm install -g` | | 浏览器打不开 3080 | 端口被占：用 `netstat` 排查并 kill PID | | 模型无响应 | 检查 `settings.yaml` 模型配置 + API Key | | 插件装不上 (404) | 确认依赖用 `^0.1.0-rc.6` 线 | ## 总结 DeepSeek Harness 是一个开源、模型无关、插件化的 Agent 运行时，适合想要深度定制、玩生态、在 CI 中运行 Agent 的开发者。它提供了多种运行模式，包括 Web UI 和 Headless CLI，并且支持丰富的插件生态。虽然当前处于 rc 阶段，迭代快、有破坏性变更，但其开源和灵活性为开发者提供了巨大的定制空间。对于新手，从 0 到 1 仅需 3 天，即可掌握基本使用并开发第一个插件。