deepseek-harness 学习手册
Developer Preview 最后核对于 v0.1.1-rc.2 · commit b150a55

别人开源的是 agent 产品,
dsh 开源的是一套
「agent harness 该怎么建」的观点。

227 个 npm 包、50 个包分组、742 篇双语决策记录,没有一个特权核心——连 agent loop 自己也只是插件树上的一行。这个站不复述官方文档,它把那套观点拆开:每条规则为什么这么定、代价是什么、哪些不依赖 dsh 也能直接抄回自己的项目。

227
个 npm 包,全部 @deepseek-ai/dsh-* 前缀
50
个包分组(package group)
742
篇 Agent Note 决策记录,739 篇有中文对照
0
个特权核心——连 agent loop 也是插件
Pick your path

你是哪一种读者?

三条路径共用同一批页面,只是顺序和详略不同。选一条,进到内容页后左栏会告诉你走到第几站。

你想知道 dsh 到底是什么、和 OpenCode / Codex CLI 差在哪,以及值不值得投时间。五站走完,你能在会议上把它讲清楚。

Figure 01

一张图:插件树是怎么叠出来的

一个跑起来的 dsh,是启动时按顺序叠出来的一棵插件树。三层各管一件事,后写的赢;每一层都只是在改同一份「entry 列表」。

profile
选形态:web / headless,或你自己 dsh plugin 创建的任何一个。它住在 $DSH_HOME/profiles/<name>,一个 package.json 加一个 cordis.patch.yml
bundle
可安装的能力包合集,成套挂载。dsh-base 是每个 profile 的第一层;dsh-web-app 加浏览器应用,dsh-headless 加一个不开端口的一次性 runner。
cordis.patch.yml
你的补丁层:按 id 定位某一行,替换它整个 config,或者 insert 新行。profile 一份、home 一份,最后还有命令行的 --patch overlay。
$ dsh --profile web --dump-config
ctx
├─ core/session 事件日志唯一真相
├─ core/system-prompt prompt section + 工具 schema 装配
├─ core/tools 带作用域的工具注册表
├─ core/agent-loop ◀ 连它自己也只是一行
├─ llm/llm-deepseek 模型适配器
├─ web/web-search-deepseek← 可换 exa / perplexity
├─ guard/repeat-tool-reminder
├─ spill/spill-policy 超长工具输出落盘
├─ compaction/compaction-basic
└─ … 节选
树的形状由三层配置决定,不由代码决定。Lab 1 会带你在自己机器上把这棵树真的打印出来。
镇站 Demo · M6

让 agent 现场给自己长出一个新工具

dsh Web UI 录屏:模型先被告知 cordis-plugin-development skill 加载失败,改用 cordis_inspect_query 查 API;定义动态插件 text_stats 并等待审批;三轮自修复后进入运行;调用刚长出来的 text_stats 得到字符数 25、行数 3、最长一行 13;最后 cordis_stop,卡片显示 Dynamic Plugin tst-1 is stopped。
真实录屏,不是合成动画。commit b150a55 的源码树 · 127.0.0.1:3081 · 真实模型轮次(DeepSeek-V4-Flash)· 全新的 DSH_HOME。 这段片子证明的是:模型自己定义插件、经三轮自修复与人工审批后挂载、调用它刚长出来的 text_stats、再干净地卸掉。 三处要说清楚的:① 出厂的 examples/web-cordis/cordis.yml 在这个 commit 上跑不起来,录屏用的是只补 tool-cordis 的修正 overlay(Lab 5); ② 第一帧那段提示词里写明了 schema 约定,看得见; ③ 到片尾浏览器面板那一半仍是「Client 待激活」——跑通的是 Host 侧的模型工具,UI 半体还在迭代(M6.3.5 算了这笔账)。
镇站 Demo · M6

让 agent 现场给自己长出一个新工具

dsh Web UI 录屏:模型依次调用 cordis_inspect_query 查 API、定义动态插件 text-stats、等待用户审批、批准后插件进入运行、调用刚长出来的 text_stats 工具,最后停掉它,Cordis 插件面板回到 0 running。
真实录屏,非合成动画。commit b150a55 的源码树 · 127.0.0.1:3081 · 真实模型轮次(DeepSeek-V4-Flash)· 全新的 DSH_HOME 与会话状态 · 审批那一步是人工点击「仅允许此版本」。
terminal
$ pnpm run demo:cordis

跑起来之后,模型先用 cordis_inspect_list 看清当前进程里有哪些 provider,再用 cordis_define 写一个插件、cordis_run 把它挂进当前 context——然后它立刻就能调用自己刚造出来的工具。

它之所以敢这么干,全靠 M2 那条规则:注册即 effect,卸载即撤销cordis_stop 一调,这棵子树连同它注册过的一切原样消失。

看 M6 逐个动词拆解 →

Site map

十一个模块,两根柱子

M2 回答「它凭什么灵活」,M4 是别处基本学不到的独家内容——这两根柱子撑住全站。M6 负责传播,M8 的普适价值最高:不用 dsh 也能抄。

M1 同类产品坐标系 20 min 六维对比表 + 形态之争 + 互操作姿态 + 一棵「我该用/该学哪个」的决策树。 M2 一切皆插件柱一 90 min · 全站主干 Cordis 的五个概念、capability seam 三件套、三层组合机制,以及这套纪律要付的账单。 M3 turn / step 与上下文防御 60 min turn / step 事件流全图、session log 唯一真相,以及三个可卸载的上下文防御插件。 M4 把 token 当公开契约柱二独家 70 min 每个包 README 必须写清模型看见什么、花多少 token、对 KV cache 有什么影响——而且 CI 会卡。 M5 图鉴 每页 5 min subagent 家族、Ralph、goal / plan / preset、skill、沙箱与信任、credentials 分层。 M6 agent 修改自己的运行时镇站 35 min 七个 cordis_* 工具逐个拆解,为什么 M2 的架构让它是安全的,以及一页不回避的信任边界。 M7 什么时候写插件,什么时候 fork 40 min 判断题、一个新 provider 到底要写哪些文件、守规矩的 delta 长什么样,以及 fork 维护的残酷算术。 M8 为 AI 协作而设计的仓库最普适 55 min AGENTS.md 逐条精读、四态 Agent Note、把工程约定写成 AI 可执行的 skill、质量门禁矩阵。 M9 五个 Lab 2.5 h 从跑起来读插件树,到零 fork 换 provider,再到让 agent 现场造工具。每个 Lab 结尾都有同题对比。 M10 抽象税、风险与常见问答 25 min 这套做法要付什么代价、现在上手有什么风险、跟 MCP 到底什么关系。 附录 术语表 · 包地图 · 时间线 工具页 术语中英对照、按 group 可视化的 227 包地图、上游关键节点时间线、外链库。
把丑话说在前面 · 诚实声明

这是一份个人学习笔记,不是官方文档,也不代表 DeepSeek。凡是出自本仓库的断言都能点到源码坐标;凡是关于 OpenCode / Codex CLI / Claude Code 的断言都挂了「待核对」标记,因为它们是二手整理。看到与仓库不一致的地方,以仓库为准。

dsh 本身处于 developer preview:接口随时会变,SESSION_FORMAT_VERSION 仍然是 0 且仓库明确写着不作兼容承诺,社区生态规模也远小于同类产品。这些不是免责条款,而是判断「要不要现在上手」的必要输入——M10 会把它们摊开算账。

目录
deepseek-harness 学习手册