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 动态插件演示:模型查询 API、定义 text_stats 插件、等待审批、修复并挂载插件、调用新工具,最后停止插件。
动态插件演示。模型查询 API、定义 text_stats 插件、等待人工审批、经过自我修复后挂载并调用新工具,最后停止插件。
镇站 Demo · M6

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

dsh Web UI 动态插件演示:模型查询 API、定义 text-stats 插件、等待用户审批、调用新工具,最后停止插件。
模型查询 API、定义插件、等待人工审批、挂载并调用新工具,最后停止插件。
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 学习手册