前言¶

DeepSeek Harness（dsh）是 DeepSeek 开源的 Agent 运行时，官方仓库第一句就是：everything is a plugin——模型适配器、工具注册表、会话日志，连 Agent 循环本身都是插件，由 Cordis 装配。它目前仍处于开发者预览阶段，官方 README 写明会有破坏兼容的变更。

官方文档适合「查」：想知道某个事件名、某个 profile 怎么启动，去仓库和文档站点检索即可。但很多人第一次碰到这套架构时，缺的是「学」：Cordis 的五个概念怎么落到代码里？headless 和 web 两个 profile 差在哪？怎样不接真实模型也能把 turn / step / 工具循环跑通？

社区维护者 yanhua1010 做了一份中文教程仓库 dsh-harness-tutorial：VitePress 站点讲原理和源码，8 个 Demo 对着真实 dsh 包动手，最后再亲手写一个教学版 mini-harness（React 前端 + Node.js TypeScript 后端）。本文按社区目录页、GitHub 仓库 README 与教程正文交叉核对后整理。

这是什么¶

dsh-harness-tutorial 是一份面向计算机本科毕业生和想读懂 dsh 源码的工程师的渐进式中文教程，由 yanhua1010 维护，许可证为 MIT（LICENSE 文件版权年份为 2026）。GitHub 仓库在 2026-08-17 显示 46 颗星；社区目录页收录时标注为 39 星。主要语言是 TypeScript。

它解决的不是「给正在跑的 Agent 加一个新工具」，而是把「一切皆插件」拆成能跟着做的课：

• 先建立心智模型：Harness、Cordis、接缝、turn / step
• 再对照真实仓库逐包看实现
• 然后用 8 个已验证的 Demo 把机制跑通
• 最后从零实现一个诚实简化的教学版 Agent

它被收录在社区站点 DeepSeek Harness 插件库 的「工具与能力」分类，收录日期为 2026-08-15。需要说明：该目录是独立社区站点，与 DeepSeek / 幻方没有官方从属关系，不是官方应用商店。

还有一点边界要先写清。仓库根目录的 package.json 是 VitePress 教学站点（private: true，脚本是 docs:dev / docs:build），没有声明 dsh.bundle。README 给出的用法是克隆后用 npm 跑站点、Demo 和教学项目，而不是把它当作运行时能力插件挂进现有 profile。目录页仍然提供了 dsh plugin add 命令，下文会原样记录；真正跟着学，以仓库 README 为准。

GitHub 上另有一份 ht426/deepseek-harness-tutorial，也是中文教程，但是另一份资料，不要和本文介绍的 yanhua1010/dsh-harness-tutorial 混用。

课程结构¶

教程站点把内容分成四篇，对应仓库里的四个目录。

原理篇（docs/guide/，8 章）¶

按教程首页的路线，这一篇要建立的是心智模型，而不是 API 清单：

教程正文引用官方架构文档的原意：产品的每个部分都是插件，因此每个部分都可以从配置里替换。功能之间的耦合发生在运行时的注册，而不是源码里的 import。

源码拆解篇（docs/source/，6 章）¶

这一篇对照真实仓库逐包拆：仓库地图、Cordis 内核、session、agent、llm、tools。教程自己的定位是：讲清楚「为什么这么设计」「每一步在解决什么问题」，而不是罗列 API。需要精确类型或事件签名时，仍应回到 deepseek-ai/deepseek-harness。

实战 Demo 篇（demos/，8 个）¶

8 个 Demo 全部基于真实 npm 包，版本锁定为：

• DeepSeek Harness：@deepseek-ai/dsh@0.1.0-rc.6（以及同版本的 dsh-llm、dsh-tools）
• Cordis：@deepseek-ai/cordis@4.0.1

demos/README.md 写明：Demo 4 起使用 Mock 适配器，不发网络请求，也不需要 API Key。

教程把 Demo 5 标成分水岭：第一次让真实的 dsh agent 循环跑起来，只是模型被换成自己写的 Mock 插件。Demo 5–8 通过 --patch 覆盖层，把本地插件挂进 dsh --profile headless，并用各自的 DSH_HOME 隔离会话目录。

教学版项目（final-project/）¶

读过之后再写一遍。docs/project/overview.md 写明：核心库约 900 行 TypeScript、零运行时依赖；再配 Express + SSE 的 Node 后端，以及带聊天和实时事件面板的 React 前端。教程首页把整份教学实现合计约 1500 行。

它保留骨架：插件三形态、可逆 effect、四种事件分发、LLM 接缝、turn / step、工具四道闸门。砍掉的是生产级复杂度，例如 fiber / HMR、schemastery 配置校验、JSONL / SQLite 持久化、沙箱与审批面、subagent。教程要求每砍一项都说明「真实 dsh 为什么需要它」。

安装与启用¶

社区目录页给出的安装命令如下，在 DeepSeek Harness 终端中运行：

dsh plugin add github:yanhua1010/dsh-harness-tutorial

如需可复现安装，目录页建议固定 commit 哈希。当前 main 最新提交为 2a29d03a83859f79e0c93d66fad2d5b405780b0b（2026-08-13）：

dsh plugin add github:yanhua1010/dsh-harness-tutorial#2a29d03a83859f79e0c93d66fad2d5b405780b0b

目录页同时提示：插件以当前 dsh 进程的权限运行，安装时可能执行代码；安装前应检查源代码仓库和许可证。

如前所述，这份仓库的设计用法是当教程来读和跑，而不是当能力插件来装。仓库 README 的快速开始如下。

先克隆：

git clone https://github.com/yanhua1010/dsh-harness-tutorial.git
cd dsh-harness-tutorial

环境要求来自教程首页和 README：

• Node.js ≥ 20.19（推荐 22+）
• 包管理器用 npm，教程不要求 pnpm
• DeepSeek API Key 可选：全部 Demo 用 Mock 适配器即可运行，仅「接入真实模型」小节需要

只想先阅读、不在本地起站点，可以直接打开 GitHub Pages：

https://yanhua1010.github.io/dsh-harness-tutorial/

典型用法¶

下面的命令都来自仓库 README 和 demos/README.md，可以按原样复现。

1. 在本地打开教程站点¶

npm install
npm run docs:dev

开发服务器地址是 http://localhost:5173/dsh-harness-tutorial/（仓库用 GitHub Pages 的 base 路径，本地也走同一前缀）。建议按「原理篇 → 源码拆解 → Demo → 教学项目」的顺序读，Demo 页里也标明了与原理章节的对应关系，例如 Demo 1–3 对应 docs/guide/02-cordis-core.md。

2. 跑通 Demo 1–4（独立脚本）¶

cd demos
npm install
npm run demo:1
npm run demo:2
npm run demo:3
npm run demo:4

这四个脚本在 demos/package.json 里分别调用 tsx 执行各 Demo 目录下的 main.ts。Demo 1–3 只依赖 Cordis；Demo 4 引入 dsh-llm 包，用 Mock 适配器演示 StreamChunk 协议。

3. 用 headless overlay 跑 Demo 5¶

Demo 5–8 不再是独立 tsx 脚本，而是把本地插件 patch 进真实的 dsh 进程。以 Demo 5 为例：

cd demos/05-headless-mock
DSH_HOME="$PWD/.dsh-home" npx dsh --profile headless --patch mock.patch.yml "你好，介绍一下你自己"
node read-session.mjs

要点有两条，都写在 Demo 准备页里：

• DSH_HOME 必须指向该 Demo 自己的 .dsh-home，避免会话和设置串到本机其他 profile
• patch 里本地插件路径是 ../../../plugins/xxx.ts，因为 Loader 的 baseUrl 是 $DSH_HOME/profiles/headless/

Demo 6 验证工具循环，Demo 7 可用环境变量 DSH_DEMO_DENY_ECHO=1 走拒绝路径，Demo 8 换成自定义 profile demo8，并用 --dump-config 观察组合后的配置树：

cd demos/08-profile
DSH_HOME="$PWD/.dsh-home" npx dsh --profile demo8 "你好，自定义 profile"
DSH_HOME="$PWD/.dsh-home" npx dsh --profile demo8 --dump-config | tail -12

教程说明：headless 输出干净、生命周期一次到位，更适合观察；学完 Demo 8 后，可以把 --profile headless 换成 --profile web，在浏览器里走同一条 Mock 链路。

4. 启动教学版 mini-harness¶

cd final-project
npm install
npm run demo

npm run demo 是核心库冒烟测试。要看带界面的端到端效果，开两个终端：

npm run dev:server    # 后端 http://127.0.0.1:4317
npm run dev:web       # 前端 http://localhost:5174

项目总览里给了一段 npm run demo 的节选：Mock 适配器和 echo 工具注册后，一次任务会打出 turn/start → step/start → tool/call → tool/result → 再开第二个 step 做后续模型调用 → turn/end。这就是教学版要你亲手写出来的工具循环。

适用场景与注意事项¶

适合谁，教程首页写得很具体：

• 写过 TypeScript / JavaScript，了解 HTTP 与 JSON，听说过 Function Calling，但没见过 Agent 框架内部结构的计算机本科毕业生
• 想读懂 DeepSeek Harness 源码的工程师：官方文档以查为主，这份教程以学为主，两者配合
• 想自己搭一套 Agent 系统、需要一份约一千多行的诚实简化实现的人

不适合把它当成「装上立刻多一个工具」的生产插件。根包是教学站点；要给正在运行的 dsh 加工具，应去写带 dsh.bundle 的 bundle，或直接参考官方 插件发布文档。

使用前注意这几件事：

1. 版本锁定与预览阶段。 教程基于 0.1.0-rc.6 撰写，Demo 依赖已 pin，照着做可以跑通。DeepSeek Harness 官方仍标注 developer preview，架构思想相对稳定，API 细节以官方文档最新版为准。
2. 权限与许可证。 无论是 dsh plugin add 还是 npx dsh，代码都以当前进程权限运行。安装或运行前应阅读仓库源码和 MIT 许可证。
3. Windows 环境变量。 Demo 准备页给出的是 POSIX 写法；PowerShell 要用 $env:DSH_HOME = "$PWD\.dsh-home"，路径分隔符按 PowerShell 调整。
4. 常见运行问题。 npx dsh 找不到包时，确认已在 demos/ 下执行过 npm install；headless 是一次性进程，改完插件重新跑命令即可。
5. 社区目录不是官方商店。 插件库由社区维护，收录条目与 GitHub 星标可能不同步。

小结¶

dsh-harness-tutorial 把 DeepSeek Harness 的「一切皆插件」拆成一条能跟着做的中文路径：8 章原理、6 章源码对照、8 个锁定在 0.1.0-rc.6 上的 Demo，再加一个可运行的教学版 mini-harness。官方文档继续用来查接口，这份教程用来建立机制和动手经验。

目录页：https://deepseek-harness-plugin.com/zh-CN/plugins/dsh-harness-tutorial/

GitHub：https://github.com/yanhua1010/dsh-harness-tutorial

在线阅读：https://yanhua1010.github.io/dsh-harness-tutorial/