The DeepSeek Harness Field Guide
A hands-on guide for learning dsh, building plugins, and evaluating where it fits.
- Source repo
- Electricitysheep/dsh-handbook
- Stars
- ★ 942
- Last updated
- 1d ago
- Primary language
- HTML
- FA score
- 54/100 · Major gaps
At a glance
- How it runs
- Works with
- Universal · cross-platform
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A developer new to dsh follows the three-day learning path to install it and complete the listed milestones.
- Not a fit if
- Teams that require a stable production release
- Source review
- 54/100 · Major gaps
What does this agent do, and when should you use it?
This bilingual handbook and ecosystem survey covers DeepSeek Harness (dsh), from first setup through plugin development, performance tuning, security, and cost. It contains 15 chapters, appendices, and a cloneable plugin template, with online reading and Chinese and English PDFs. Its examples use dsh's Web UI and headless CLI, and explain profiles, plugin extension points, MCP, subagents, and workflows. The guide includes commands, case studies, and same-model multi-agent benchmarks, with the stated test environment and dsh's prerelease status. It is aimed at developers evaluating or customizing dsh; the handbook itself is not the runtime.
The handbook starts with installing and launching dsh using npx -y @deepseek-ai/dsh web, then opening http://127.0.0.1:3080, or running a one-off task with dsh --profile headless "task". It explains adding a plugin dependency in package.json and mounting it through cordis.patch.yml; Chapter 4 uses the agent/request waterfall to demonstrate plugin logic. Later chapters cover built-in tools, context compaction, MCP connections, parallel subagents, workflows, security, and cost. Case studies and benchmarks report task times, outputs, validation methods, and results from different agents using the same model.
- A developer new to dsh follows the three-day learning path to install it and complete the listed milestones.
- A plugin author uses the template to learn dependency setup, plugin mounting, and the
agent/requestextension point. - An engineer evaluating dsh for a team toolchain reviews its documented limits, case studies, and same-model benchmark.
- A user diagnosing tool-chain speed or inference costs consults the reasoning-effort guidance and cache measurements.
- A maintainer reviewing plugin security uses the sandbox chapter and its third-party plugin audit checklist.
How do you install or deploy this agent?
The handbook is available to read online and as Chinese and English PDFs. To run the dsh example, the README requires Node.js ≥ 22:
npx -y @deepseek-ai/dsh webThis command starts the Web UI. The quickstart material here does not specify API key setup.
How do you use this agent?
Open http://127.0.0.1:3080 in a browser to start a conversation. The README also documents a headless one-off task:
dsh --profile headless "Hello, introduce yourself in one sentence"For plugin development, the examples add a dependency in package.json, then insert the plugin configuration in cordis.patch.yml. Install dependencies in the profile directory and launch it with:
cd ~/.dsh/profiles/web && pnpm install && dsh webWhat are this agent's strengths and limitations?
- Its 15 chapters cover setup, profiles, plugin development, performance, security, cost, and ecosystem research.
- It provides a cloneable plugin template with pure-function and waterfall examples plus tests.
- It includes complex case studies and same-model multi-agent benchmarks with reported timings and validation details.
- Chinese-first content is accompanied by English material and PDFs in both languages.
- The handbook says dsh is prerelease software, so version changes may be breaking.
- The documented tests use Windows 11, Node 24, and particular dsh/model versions; results for other environments are not established in this material.
- The guide says dsh conversations incur usage charges; it describes cache discounts and cost tools but gives no fixed total cost.
- Although the handbook says commands were tested locally, the supplied material does not independently verify every test result.
How does this agent compare with similar options?
The handbook compares dsh with Claude Code, OpenAI Codex, OpenCode, Gemini CLI, and Kimi CLI. It positions dsh for deep customization and ecosystem extensions, while describing Claude Code and others as more ready to use out of the box. It also reports a five-task test using deepseek-v4-flash: omp took 70 seconds, dsh 130 seconds, and opencode 172 seconds; all three completed 45/45 checks. These are the handbook's reported medians across three runs, not a general result for every task or environment.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| The DeepSeek Harness Field Guide This agent | 54 · Major gaps | Web appFree + model costs | ★ 942 | 1d ago | HTML | — |
| AgenC Core | 74 · Some gaps | CLIFree + model costs | ★ 107 | today | TypeScript | — |
| OpenAI Agents SDK | 64 · Some gaps | Library / SDKFree + model costs | ★ 30k | today | Python | OpenAI API |
| Orca | 59 · Major gaps | CLIFree + model costs | ★ 512 | 1d ago | Rust | — |
How does FollowAgents rate this agent?
Why each dimension lost points
The materials explain the boundaries among the sandbox, permission presets, and approvals, and recommend workspace-write + ask, loopback, and plugin-source checks. This gives useful coverage of least privilege, confirmation, and external effects. Sensitive-data handling is weakened by executable plugins, reads outside the workspace, approval-loop reports, plaintext session residue, and other documented boundary cases. Dependency security is limited to source-trust advice, with no shown signature validation or dependency audit. Rollback mainly means keeping work under version control, without a general recovery procedure. Attribution relies chiefly on official-document names and discussion numbers, while publisher maintenance identity is unclear.
The materials provide installation troubleshooting and platform failure signatures, but the Chinese and English quickstarts differ on minimum Node version, install commands, and some capability details. The README review also records table and ordering problems, lowering self-consistency. Dependency versions and npm release information are described, but the project is in an rc stage and plugin dependency breakage is reported. Failure symptoms are paired with fairly concrete remedies, though the evidence is not enough for full marks.
The handbook covers beginner installation, Web, headless, CI, plugin development, and team security baselines. It also states that the sandbox excludes network and process controls and marks some modes as untested. Scenario guidance is present, but precise triggers and decision rules for choosing capabilities are limited. It gives some environment-specific guidance for Node, Windows, and WSL2.
The chapters, configuration reference, quickstart, FAQ, and exercises support practical navigation, but the README review identifies a weak first-screen action path, buried selling points, ordering issues, and malformed tables. Installation notes are detailed, terminology and commands are mostly stable, and known limitations are covered thoroughly. License metadata is unknown, so that criterion receives zero. Several rc versions and verification dates appear, but no complete changelog or clear maintenance responsibility is shown.
The quickstart, configuration examples, troubleshooting tables, and security baseline are usable for readers. The described scope includes installation, plugins, tuning, and measured cases; the supplied security analysis and plugin-template tests suggest potential value beyond architectural documentation. Deductions reflect the README review's findings of repetition and poor prioritization, and the fact that some value and measurement claims are asserted without supporting material in this source set.
The security chapter links claims to named official documents, discussion numbers, and an in-repository research report; it labels inferred recommendations and items pending measurement. This supports a strong separation of fact and inference. Chinese and English material broadly corroborate each other and cite multiple source types, but the supplied files do not include the underlying source code or official document text for independent checking, so traceability and corroboration are partial.
- Treat security conclusions as a low-confidence static assessment; the chapter says some community reports date from rc.6 and may have changed.
- Check the applicable Node version and npm release line before installing; plugins are executable code and should be reviewed for source and permissions.
- Do not treat the sandbox as network or process isolation, or assume workspace-write prevents deletion inside the workspace.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v1.8.0 dsh-handbook 白皮书 v1.8（15 章完整版）
Release notes excerpt
DeepSeek Harness 白皮书 v1.8 15章节 · 附录 A/B/C · 中英双语 · PDF 全文可搜索（4.2MB） 本轮新增（v1.7 → v1.8） - 第 13 章 安全与沙箱模型：沙箱机制 / 权限模型 / 审批流 / 插件安全审计清单 / 企业安全基线（引用官方安全审计 #817） - 第 14 章 缓存与成本工程：缓存命中率实测 97% / 成本模型 / 推理档位联动 / 预算实战 / dsh-usage 工具推荐 - 附录 B 官方包速查大全：33 个核实包清单 + 能力域分组 - 讨论区反馈二次迭代：FAQ 收录插件六坑（#380 作者授权）/ 免装 Node 安装包 / 子代理模型缺口标注 - 英文版完整同步：14 章全双语 + README.en 全量同步 在线文档 https://electricitysheep.github.io/dsh-handbook/（侧边栏 + 全文搜索） 社区 - 官方库讨论区持续活跃（33 帖响应） - 社区案例征集中：跑过 dsh 真实案例？欢迎投稿收录View on GitHub ↗ -
v1.7.0 dsh-handbook 白皮书 v1.7（未来展望版）
Release notes excerpt
DeepSeek Harness 白皮书 v1.7 14 章节 · 中文 118k 字符 · 中英双语 PDF 本轮新增 - 第 11 章：未来展望——六角度演进预测（技术/生态/竞争/行业/机会/风险）+ 时间线（1-3 月 / 1 年 / 2-3 年）+ 给读者的建议 - 第 5 章：高缓存命中率专题（实测 97%，98% 缓存折扣成本分析）+ 行业视角（金融/教育/销售/运营/研究，含合规提醒） - 第 5 章英文版同步（应用场景版） 资产 - [中文 PDF](./DeepSeek-Harness-白皮书.pdf) - [英文 PDF](./DeepSeek-Harness-Handbook.pdf)View on GitHub ↗ -
v1.6.0 dsh-handbook 白皮书 v1.6（行业标准版）
Release notes excerpt
DeepSeek Harness 白皮书 v1.6 13 章节 · 中文 110k 字符 · 中英双语 PDF · 5 个真实复杂案例 内容总览 - 学习路径：3 天从 0 到 1（每日目标 + 验收标准） - 第 1-2 章：认识 dsh + 快速上手（TL;DR + mermaid 架构图 + 练习） - 第 3-4 章：profile/插件系统 + 插件开发实战（完整代码） - 第 5 章：应用场景全景（5 大场景 + 高缓存命中率专题 + 5 行业视角） - 第 6-7 章：性能调优 + 生态资源 - 第 8-9 章：工具/上下文系统 + MCP/子代理/工作流 - 第 10 章：5 个真实复杂案例（数据清洗/修 bug/HTML 解析/代码重构/API 文档） - 附录：术语表 30+ 术语 + 命令速查 + 同模型 3 Agent benchmark 亮点 - 高缓存命中率专题（实测 97%，98% 缓存折扣的成本分析） - 每个案例含真实耗时/产物/验证（合成数据，隐私安全） - 同模型 × 不同 Agent 实测（omp 36s / dsh 85s / opencode 114s） 资产 …View on GitHub ↗
FAQ
Is the handbook itself an agent?
What do I need to run the examples?
npx -y @deepseek-ai/dsh web. The supplied quickstart does not explain API key setup.Is using dsh completely free?
Is it ready for production use?
What plugin development material is included?
agent/request extension example, and documented security constraints and practical cases.