DeepSeek Harness 白皮书 · dsh-handbook

DeepSeek Harness 中文手册 × 生态观察中心——从 0 到 1 玩转 dsh，跟着 780 帖讨论区看懂生态 · 中文 · English

📖 在线阅读 · 📄 下载 PDF · ⭐ 点 Star 支持

1804 插件 · 780 帖讨论区 · 15 章手册 · 195 帖社区响应 · 280+ Stars

[!WARNING] dsh 当前为 0.1.0-rc.6（预发布阶段），生产环境请谨慎评估，详见 ℹ️ 版本说明。

🚀 快速体验（30 秒）

# 1. 安装（需要 Node.js ≥ 22）
npx -y @deepseek-ai/dsh web

# 2. 浏览器打开 http://127.0.0.1:3080，开始对话
# 3. 或跑一次性任务（适合脚本/CI）
dsh --profile headless "你好，请用一句话介绍自己"

想系统学？看 🗺 学习路径（3 天计划）；想先跑？第 2 章：五分钟快速上手；想速查？📇 一页速查卡

_{30 秒看懂 dsh Web UI：新建会话 → 输入任务 → 模型选择 → 发送 → AI 回复}

🎯 这是什么

DeepSeek Harness（dsh）是 DeepSeek 官方 2026-08-13 开源的 Agent 运行时——一个"一切皆插件"（everything is a plugin）的框架。

但官方文档以架构说明为主，缺少一条从零上手的路径。

这本白皮书补上这条路：从"什么是 Agent 运行时"讲起，到安装、使用、开发插件、性能调优——每一章都有可复制、可运行的命令，全部在本机实测验证。目标是：任何一个开发者，跟着这本书都能从 0 到 1 用起来、写起来。

为什么值得读（而不是只看官方文档）

🎁 这本能给你什么

🌟 感谢与社区

首先要感谢每一位 Star、回复和投稿——这本手册不是一个人的作品，是 dsh 社区一起"长"出来的。

发布两天，很幸运得到了这些反馈：

• ⭐ 280+ Stars——对一份刚发布的教程来说远超预期，感谢大家认可
• 💬 官方库 195 帖回应——我们持续在讨论区和大家一起踩坑、排障、交流
• 🧠 FAQ 里的 39 条问题大多来自真实提问——社区问什么，我们沉淀什么（#380/#817/#1052…）
• 📦 已向 awesome-dsh-plugin 提交收录 PR（#33，待合并）；阮一峰周刊自荐已提交
• 🤝 与 30+ 社区项目互链（dsh-usage / dsh-sgme / AgentSoul / dsh-vault / egress-guard / agentmemory…）

内容随讨论区持续更新（沉淀流水线，19 项可追踪）。如果你觉得有用，Star 是对我们最大的支持。

🔭 生态观察（第 15 章·全景报告）

把 1804 个插件仓库的数据盘点 × 780 帖讨论区定性观察交叉验证，5 个关键结论：

6 个能力缝（官方可优先建）：视觉通道 · 记忆 seam · 桌面 TUI 协议 · 评测闭环 · Windows 一等支持 · 插件 registry

完整报告（含对开发者/选型者/观望者的建议）：第 15 章

📚 目录（从 0 到 1）

🟢 阶段 1 · 入门：认知与上手

🔵 阶段 2 · 开发：骨架与插件

🟠 阶段 3 · 实战：场景与调优

🟣 阶段 4 · 生态：能力与编排

🔴 阶段 5 · 进阶：复杂案例与展望

📎 附录

💎 内容精华速览（点开即看，不止链接）

🖥 演示（Demo）—— 直接看效果

① Web UI 对话（dsh web）

dsh web    # → http://127.0.0.1:3080

② Headless CLI（一次性任务，适合脚本/CI）

运行 dsh --profile headless "你好，请用一句话介绍你自己"（命令见 🚀 快速体验）：

# → 你好！我是 DeepSeek 驱动的 AI 编程助手，可以帮你写代码、调试问题、
#    处理文件、搜索资料，以及完成各种开发和办公任务。

③ 插件生态（Git 面板，dsh-better-sidebar）

完整图文演示见 📺 30 秒看懂 dsh。

🧰 快速上手资产（精华直接看）

npx -y @deepseek-ai/dsh web          # 安装即启动 Web UI
dsh --profile headless "任务"        # 一次性任务（脚本/CI）

# ① package.json 加依赖
"my-plugin": "link:C:\\path\\to\\my-plugin"
# ② cordis.patch.yml 加挂载
- insert:
    - id: my-plugin
      name: my-plugin

cd ~/.dsh/profiles/web && pnpm install && dsh web

agent-default-model:
  model: deepseek-v4-flash    # 或 deepseek-v4-pro
  reasoningEffort: high       # off（关闭思考/最快）/ high（默认）/ max（最强）

⚖️ DSH vs 主流 Agent（能力矩阵）

实测案例、同模型多 Agent 对比数据见 第 1 章 与 benchmark 章节。

📊 同模型 × 不同 Agent 实测（2026-08-13）

模型统一 deepseek-v4-flash（同一网关、同一 key），只对比 Agent 工程层。5 任务全部正确完成，差异在效率：

5 任务 × 3 轮采样中位数（T1 创建文件 → T5 多文件重构），45/45 全对。完整方法/解读见 📊 Benchmark 附录。

📄 白皮书 PDF

• 中文完整版：DeepSeek-Harness-白皮书.pdf（15 章 + 附录 ABC，~130k+ 字符，5.5MB）
• 英文完整版：DeepSeek-Harness-Handbook.pdf（15 章 + 附录，83 页，约 160k 字符，1.7MB）

🌐 与生态联动

本白皮书的方法论来自真实开源实践： - DSH-better-sidebar —— 社区侧边栏插件（第 5 章案例）

🧩 社区插件推荐（来自官方讨论区 / awesome-dsh-plugin 精选）

完整列表见 awesome-dsh-plugin（122+ 插件）。想被收录？社区案例征集

📣 官方讨论区活跃响应

已在 deepseek-ai/deepseek-harness Discussions 持续活跃响应（100+ 帖）：插件踩坑 #380 / 安全审计 #817 / 缓存成本 #1052/#1234 / 生态洞察帖 #839 等（沉淀流水线 持续收录反馈）

🙏 贡献与反馈

• ⭐ 觉得有帮助？点个 Star 支持持续更新
• 📝 跑过真实案例？ 投稿收录进白皮书（署名 + 季度精选 PDF）：社区案例征集 ← 直接回帖，模板已备好
• 章节/命令失效？rc 版本迭代所致，欢迎 issue 指正
• 想参与？见 🤝 贡献指南（CONTRIBUTING） · 想看计划？🗺️ 路线图（ROADMAP） · 生态参与见 第 7 章

ℹ️ 版本说明

• 基于 dsh 0.1.0-rc.6 / DeepSeek-V4-Flash-0731（2026-08-13 开源）
• 示例环境：Windows 11 + Node 24

🔄 最近更新

• 15 章完整版（第 13 安全沙箱 / 第 14 缓存成本 / 第 15 生态全景报告）+ 附录 A/B/C
• 讨论区反馈持续沉淀：FAQ 39 条 / KVCache 规则 / 内置 Agent 预设 / run_code 异步坑（沉淀流水线）

📜 许可

内容 CC BY-NC-SA 4.0 · 示例代码 MIT