Electricitysheep/dsh-handbook · 上手攻略
- 仓库：Electricitysheep/dsh-handbook
- 链接：https://github.com/Electricitysheep/dsh-handbook
- 分类：Agent 运行时 / 开发框架
- 作者：Tom
- 更新：2026-08-15
是什么
DeepSeek Harness（dsh） 是 DeepSeek 官方于 2026-08-13 开源的 Agent 运行时框架，MIT 许可证，用 TypeScript 开发。其核心理念是"一切皆插件"（everything is a plugin）——整个系统由一个可插拔的 profile 骨架和 60+ 官方能力包组成，模型无关，支持 Claude、GPT、DeepSeek 等多种 LLM 后端。
dsh-handbook 则是一份与官方文档互补的中文上手白皮书（14 章 + 附录，含中文 PDF 和英文 PDF），填补了官方文档"架构视角为主、缺少从零上手路径"的空白。手册本身也以插件形式持续更新（社区 FAQ + 讨论区沉淀）。
⚠️ dsh 当前版本为 0.1.0-rc.6（预发布阶段），存在破坏性变更风险，生产环境请谨慎评估。
解决什么问题
官方 dsh 仓库的文档面向了解架构的开发者，而 handbook 解决了以下实际问题：
| 痛点 | dsh-handbook 对策 |
|---|---|
| 官方文档零散，没有上手路径 | 3 天学习计划 + 验收标准 |
| 不知道插件怎么写 | 完整可运行插件模板 + 实机验证 |
| 不清楚性能瓶颈在哪 | 工具链 90% 时间在思考的建模 + 降档策略 |
| 不知道选哪个 Agent | 同模型 3 Agent 实测 benchmark（deepseek-v4-flash） |
| 不知道怎么控制成本 | 缓存命中率实测 97% + 推理档位联动 |
| 完全没有中文资料 | 中文优先，英文同步 PDF |
快速安装
环境要求
- Node.js ≥ 22
- DeepSeek API Key（或等效兼容网关）
一条命令启动
# 安装并启动 Web UI
npx -y @deepseek-ai/dsh web
启动后浏览器打开 http://127.0.0.1:3080 即可对话。
Headless 模式（适合脚本 / CI）
dsh --profile headless "你好，请用一句话介绍自己"
⚠️ 需要提前配置
DEEPSEEK_API_KEY环境变量，或在~/.dsh/profiles/web/settings.yaml中配置。
核心用法
推理档位策略（性能调优核心）
dsh 支持三级推理档位，决定模型的思考深度：
| 档位 | 适用场景 | 说明 |
|---|---|---|
off / low |
简单轮次、快速问答 | 关闭或减少思考（官方适配器为 off） |
high（默认） |
日常大多数任务 | 平衡速度与质量 |
max |
复杂推理、多步工具链 | 最强推理能力 |
注：手册实测中，低档位为
low（本手册实测网关 pi-ai/opencode-go 的档位），而官方 DeepSeek 适配器用off（关闭思考/最快）。
核心性能洞察：工具链任务 90% 时间消耗在"模型思考"（每次工具调用前）。降低档位是最高杠杆的提速手段。
Profile 与插件系统
profile = bundle 栈 + patch 层，核心配置文件为 package.json + cordis.patch.yml。
挂载插件只需 2 处改动：
# cordis.patch.yml
- insert:
- id: my-plugin
name: my-plugin
// package.json
"dependencies": {
"my-plugin": "link:/path/to/my-plugin"
}
配置文件速查
# ~/.dsh/profiles/web/settings.yaml
agent-default-model:
model: deepseek-v4-flash # 或 deepseek-v4-pro
reasoningEffort: high # off / high / max
完整工作流：web 模式
# 1. 启动
cd ~/.dsh/profiles/web && pnpm install && dsh web
# 2. 浏览器打开 http://127.0.0.1:3080
# 3. 新建会话 → 选择模型 → 发送任务
插件开发模板
# 克隆官方模板
git clone https://github.com/Electricitysheep/dsh-handbook.git
cd dsh-handbook/examples/plugin-template/
核心开发纪律： 1. 先找扩展点（agent/request waterfall / ctx.slots / ctx.provide 等 5 大扩展点） 2. 决策逻辑抽为纯函数（单测毫秒级） 3. 实机验证不能省
典型适用场景
- 深度定制 Agent 行为：需要挂载自定义工具、对工具调用进行细粒度控制（如 Git 面板、数据清洗管线）
- 多步自动化任务：dsh 的 waterfall 机制天然适合"拉取→清洗→报表→校验"的多步编排
- CI 自动化：headless 模式 + API Key 配置，可编入脚本执行一次性任务
- 插件生态参与：dsh 官方明确表示外部贡献方式为插件生态（而非直接 PR），当前生态零门槛入场
- Agent 横向评测：用同一模型对比 dsh / opencode / omp 的效率差异
坑与注意
- rc 版本破坏性变更：0.1.0-rc.6 迭代快，
package.json依赖应锁定^0.1.0-rc.6而非latest - rc.1 依赖断裂：旧 profile 挂插件遇到 404，需降级到
rc.6线 - Windows 踩坑：Node 版本要求严格，Windows 家族有额外踩坑记录（见手册第 12 章）
- 缓存评测陷阱：当简单任务突然变快，可能是缓存命中而非 Agent 提速——benchmark 解读需排除此干扰项
- 端口 3080 占用：web 模式默认 3080 端口，如被占用可改配置
- 思考占工具链 90% 时间：不要试图通过"加工具"提速，降档策略才是主杠杆
与同类对比
| 维度 | dsh | Claude Code | OpenAI Codex | OpenCode | Gemini CLI | Kimi CLI |
|---|---|---|---|---|---|---|
| 开源 | ✅ MIT | ❌ | ❌ | ✅ MIT | ❌ | ❌ |
| 模型无关 | ✅ | ❌ Claude系 | ❌ GPT系 | ✅ 任意 | ❌ Gemini系 | ❌ Kimi系 |
| 插件体系 | ✅ 官方级 60+ | 配置/钩子 | 配置 | 配置 | 无 | 无 |
| 自定义界面 | ✅（client 半） | ❌ | ❌ | 部分 | ❌ | ❌ |
| Headless CI | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 生态阶段 | 零日（2026-08-13） | 成熟 | 成熟 | 成熟 | 成熟 | 早期 |
选型结论： - 深度定制 + 插件生态 → dsh - 开箱即用 → Claude Code
一句话推荐结论
dsh 是 2026 年最具野心的开源 Agent 运行时——"一切皆插件"的架构在灵活性上远超同类，适合想深度掌控 Agent 行为的开发者；但 rc 阶段 + 零日生态意味着稳定性不足，现在入局的最佳姿势是参与插件生态，而非直接上生产。
📖 在线阅读：https://electricitysheep.github.io/dsh-handbook/ 📄 中文 PDF：https://github.com/Electricitysheep/dsh-handbook/blob/main/DeepSeek-Harness-%E7%99%BD%E7%9A%AE%E4%B9%A6.pdf