dsh-handbook

这是什么？适合谁？

dsh-handbook（Electricitysheep/dsh-handbook，640 Stars）是《DeepSeek Harness 白皮书》——一本中文优先、英文同步的 DSH 手册 × 生态观察中心。DeepSeek Harness（dsh）是 DeepSeek 官方 2026-08-13 开源的 Agent 运行时（「一切皆插件」框架），但官方文档以架构说明为主，缺少一条从零上手的路径。这本白皮书补上这条路：从「什么是 Agent 运行时」讲到安装、使用、插件开发、性能调优，每章都有可复制、可运行的命令，全部本机实测验证。

内容覆盖（按仓库章节结构）：

• 从 0 到 1 上手：安装（Web UI / CLI 两种形态）、首次任务、配置模型
• 插件开发：DSH 的「一切皆插件」哲学——从写第一个插件到发布
• 性能调优：上下文管理、并发、token 消耗优化
• 实测案例：真实任务场景的完整跑通过程
• 同模型多 Agent 实测对比：同一 DeepSeek 模型在不同 Agent 框架下的横向表现
• 3 天学习计划 + 速查卡 + 1804 插件生态观察：学习路径与生态全景

中英双语 PDF 双发布，中文社区里 DSH 生态的头部系统性文档。

适合人群：

• 想系统学习 DeepSeek Harness 的中文开发者（官方文档之外的最佳补充）
• 打算给 DSH 写插件的工程师：插件开发章节是稀缺材料
• 从其他 Agent 框架（Claude Code/Codex）迁移过来的用户：多 Agent 对比章节直接可用
• 技术团队培训：3 天学习计划可直接作为内训大纲

不适合：想找「一分钟速览」的读者（这是深度手册不是 cheatsheet）；非 DSH 生态的用户。

使用前提：会基本的命令行操作；想跟练需要 Node.js ≥ 22 与（可选）DeepSeek API key。

准备工作

1. 获取手册：clone 仓库或从 Releases 下载中/英 PDF。
2. 跟练环境：Node.js ≥ 22；npx -y @deepseek-ai/dsh web 可跑 Web UI；CLI 一次性任务同样支持。
3. API key（可选）：DeepSeek API key 用于真实任务；无 key 也可读完前几章。
4. 成本：手册免费；跟练消耗自己 API tokens（DeepSeek 定价低，成本可控）。
5. 时间预算：通读约 3-5 小时；完整跟练按官方「3 天学习计划」走。

快速上手（3 步）

第一步：30 秒跑起 dsh

# 安装并启动 Web UI（需要 Node.js ≥ 22）
npx -y @deepseek-ai/dsh web
# 浏览器打开 http://127.0.0.1:3080 开始对话

第二步：或跑一次性任务

# CLI 一次性任务形态（详见手册安装章）
npx -y @deepseek-ai/dsh "解释这个仓库的架构并输出 Markdown 报告"

第三步：按 3 天计划系统学习

手册自带学习计划：Day 1 上手与核心概念 → Day 2 插件开发实战 → Day 3 性能调优与多 Agent 对比。每天 2-3 小时。

常见踩坑

踩坑 1：Node 版本不够

• 现象：npx @deepseek-ai/dsh 报错。
• 原因：需要 Node.js ≥ 22。
• 解决：nvm install 22 && nvm use 22（或对应包管理器升级）。

踩坑 2：无 API key 直接开工

• 现象：能起界面但任务失败。
• 原因：真实任务需要模型调用。
• 解决：配置 DeepSeek API key（手册配置章有逐步说明）；DeepSeek 定价显著低于海外模型，试错成本友好。

踩坑 3：插件目录结构放错

• 现象：自写插件不加载。
• 原因：DSH 插件有约定的目录与清单结构。
• 解决：照手册插件开发章的模板从复制开始，别凭感觉手搓。

踩坑 4：上下文管理不当导致 token 爆炸

• 现象：长会话成本飙升。
• 原因：DSH 的一切皆插件意味着工具输出大量进上下文。
• 解决：手册性能调优章专门讲上下文裁剪与子任务隔离，重点读。

踩坑 5：拿 DSH 对比结论当万能

• 现象：照搬「多 Agent 对比」结论到自己的场景翻车。
• 原因：对比基于特定任务类型与模型版本。
• 解决：用手册方法论在自己任务上重测，结论会因负载而异。

踩坑 6：PDF 与仓库内容不同步

• 现象：按 PDF 操作报「命令不存在」。
• 原因：DSH 迭代快，PDF 是快照。
• 解决：以仓库最新 README/Release 为准，PDF 用于系统性阅读。

初级用法

1. 第一天只跑 Web UI：对话式熟悉 dsh 能力边界，再决定是否深入 CLI。
2. 速查卡打印贴桌：手册速查卡浓缩了常用命令，日常查阅效率高。
3. 跟写一个 echo 插件：插件开发章第一个示例，30 分钟理解「一切皆插件」。
4. 读生态观察章：1804 个插件的分类观察，帮你判断生态成熟度与选型。

高级玩法

1. 自建插件流水线：按手册模板写「代码审查→测试生成→提交」三插件串联，跑通个人工程流。
2. 同模型横评复刻：用手册的对比方法学，测 DSH vs 你现有框架在你自己任务上的差异。
3. 团队内训：3 天计划 + 实测案例直接作为组内 DSH 培训教材。
4. 贡献回上游：发现手册错误或新特性未覆盖，提 PR 参与生态共建。

小技巧

1. 中文版优先读：中文为第一写作语言，表达最准确；英文版用于分享给海外同事。
2. 命令逐条跑：手册命令全部实测过，逐条复制执行比跳读有效十倍。
3. 配合官方文档：手册讲路径、官方文档讲规范，两者互补不互替。
4. 关注 Release 勘误：DSH 更新快，手册勘误跟着 Release 走。
5. DeepSeek key 成本优势：调优实验放开跑，成本敏感度远低于海外模型。

常见问题 FAQ

Q1：手册免费吗？协议是什么？

A：仓库开放免费获取；具体内容协议以仓库 LICENSE/声明为准（GitHub API 显示无标准 SPDX 标识，引用转载前请自行确认授权条款）。

Q2：只有 PDF 吗？

A：仓库含 Markdown 源与中英 PDF 双格式；PDF 适合系统阅读，Markdown 适合检索。

Q3：手册覆盖最新版 dsh 吗？

A：手册为快照、DSH 迭代快；以仓库最新更新与官方文档为最终准绳。

Q4：没写过插件能跟上吗？

A：能。插件开发章从模板复制起步，逐步加码；有 JS/TS 基础即可。

Q5：和官方文档什么关系？

A：互补——官方文档讲架构与规范，手册讲「从零到一的路」，含大量官方文档没有的实测数据与对比。

进阶学习建议

• 按「插件思维」重构你的工具链：读完插件开发章后，把你在其他 Agent 框架里的自定义脚本改写成 DSH 插件——「一切皆插件」的架构会在这一步从口号变成肌肉记忆。
• 复刻多 Agent 对比实验：手册的同模型多 Agent 实测是方法论宝藏；用同一套任务集测你手头所有 Agent 框架，产出自己的横评数据，选型从此有据可依。
• 追踪 1804 插件生态演化：生态观察章是时间戳快照；每季度回头数一次插件数量与类目分布，你会对 Agent 生态的演化方向有超越新闻叙事的判断。

参考链接

• dsh-handbook GitHub 仓库
• DeepSeek Harness 官方仓库
• DeepSeek 官网

免责声明：本文基于官方仓库 README 与 GitHub 公开数据整理，AI 辅助生成，MagicNetWorld 尚未完成独立实测。DSH 更新较快，命令与特性请以官方最新文档为准；手册内容授权条款请自行核实。