DeepSeek Harness

01这是什么

DeepSeek Harness（命令名 dsh）跑在 vendored 的 Cordis 依赖注入框架上。 docs/architecture.md 写得很直白：没有特权内核可以打补丁——模型适配器、工具注册表、 会话日志、agent 主循环全部是插件，都能从配置里替换。你扩展它的方式不是改核心，而是在旁边挂一个插件； 所有注册都是可回收的 effect，插件卸载时自动解除。

三个贯穿全局的概念

能力接缝：三个角色缺一不可

这是理解整个仓库最省力的一把钥匙。任何一项能力都被拆成三个角色，分别住在不同的包里； 只实现其中一个不叫接缝，添加一项能力意味着三个角色一起设计。

配置层叠：运行时是怎么被拼出来的

dsh 启动时不存在"默认配置文件"这种东西，它从空的插件树开始，按固定顺序叠加补丁层。 后面的层按行 id 覆盖前面的，且是整块替换 config——没有深合并。

主循环的形状

一个 step = 一次模型请求加上它触发的工具调用；一个 turn = 零或多个 step， 在第一份输入被认领前开启，在没有任何欠账时关闭。

agent-loop 是整个仓库里唯一含有具体循环逻辑的包，其余一律是挂在扩展点上的插件。 被拒绝或改写为空的首次认领仍然会关闭一个没有花费 step 的持久 turn——这样日志里保留了这次尝试。

02子系统全景

docs/subsystems/ 下有 44 篇子系统参考文档，每篇对应一个能力域。 下面按"平面"把它们归拢，并标出各自在 Cordis 容器上注册的服务键——看 ctx 键就知道谁提供什么、谁能被替换。 标 — 的表示该子系统不注册独立服务键，而是通过事件或既有服务参与。

控制骨架

模型请求的组织者。这一层被改动的代价最高，扩展点也最密集。

执行世界

agent 真正"动手"的地方。这一组 provider 换成远程实现，整个执行世界就整体搬家。

任务与编排

上下文与知识

数据面

人机协作

平台与集成

03包依赖结构

下面的数字是从仓库里 219 个 package.json 的 dependencies 与 peerDependencies 现算的，只统计 @deepseek-ai/dsh-* 内部依赖。 仓库自己也生成一份完整图：docs/module-graph.md（1638 行 mermaid）——那份是全量，这里是能一眼看懂的聚合。

分层与依赖方向

把 49 个包组按依赖方向压成四层后，结构非常干净：依赖只向下流，上层可以随意换，下层几乎不动。

最重的几条跨组依赖边（边权 = 该组内有多少个包依赖到目标组）：

谁被依赖得最多

排除掉那个人人依赖的 invariants 之后，扇入排名基本就是这个项目的"重心图"。 前四名 session / llm / agent / tools 就是核心骨架本身—— 这四个包的接口一变，全仓库跟着动。

04功能盘点

1. 内核骨架 packages/core/

2. 模型接入 packages/llm/

• llm-deepseek — DeepSeek 直连适配器
• llm-pi-ai — 多厂商适配：Anthropic、OpenAI、Bedrock、Vertex、Azure、Codex，以及任意 OpenAI 兼容的自建网关。手写的模型默认按纯文本处理，需要视觉能力时在 settings.yaml 里给该模型加 input: [text, image]
• llm-retry（provider 级重试策略）、token-meter（回放感知的 token 计量）

3. 模型可见的工具集

docs/tool-catalog.md 是自动生成的完整 JSON Schema 目录（1873 行）。生成器会真的启动每个工具插件再读 ctx.tools.schemas()，因为 schema 不是静态可知的；同时有一道 glob 门禁，新增工具包却漏进目录会直接失败。

4. 安全与执行环境

sandbox 接缝 + 本地后端（Linux bwrap / Landlock、macOS Seatbelt、Windows ACL 受限令牌）， sandbox-policy 解析按会话持久化的策略，fs-sandbox 在 ctx.fs 层拦截写入， permission-presets（新会话默认 workspace-write）、user-approval（人工批准接缝）。 仓库还自带 native/landlock-run 这个自研 Node 原生插件。

5. 会话数据面

JSONL / SQLite 双持久化后端、投影接缝、由日志生成的会话标题、fork / resume、 compaction（上下文压缩）、spill（超长工具结果外溢到存储）、 attachment（内容寻址附件）、session-telemetry（OTLP，默认关闭）。

6. 上下文注入 packages/context/

重点是 agent-instructions：兼容 AGENTS.md / CLAUDE.md，从 $DSH_HOME/AGENTS.md 一路读到当前工作目录；并且在 read/write/edit 成功之后动态发现新进入目录的嵌套指令文件，报告变更与删除（渲染预算 65,536 字节）。 同目录下内容完全相同的 CLAUDE.md 与 AGENTS.md 会折叠成一份，不会重复计费。 另有 time-context、tmux-context、session-reference。

7. 互操作层

这一层是它和外部生态结合的关键，也是同类项目里比较少见的完整度。

• MCP 客户端：连接任意 MCP server，工具以 mcp__<server>__<tool> 注册；支持 stdio / streamable-http、断线指数退避重连、HMR 热插拔
• ACP server：把 harness agent 暴露给 Agent Client Protocol 客户端（编辑器类集成）
• SDK：JSON-RPC 协议 + TypeScript 客户端 + server 插件；Python SDK 自带 Node 运行时，宿主无需安装 Node
• Hook 桥：直接运行你已有的 Claude Code hooks.json 与 Codex hook 配置，映射到 harness 的类型化拦截点
• 子 agent 后端可以是别人家的 agent：subagent-claude-code（走官方 Claude Agent SDK）、subagent-codex、subagent-acp、subagent-dsh-sdk

8. 产品外壳

• apps/cli — dsh 命令：profile 启动 / web / headless / plugin 包管理 / --dump-config
• apps/web + packages/host/ + packages/client/ — 完整 Web UI，约 30 个 ui-* 浏览器端插件（会话、权限、模型设置、计划、待办、技能、子 agent、工作流、附件、主题……）
• packages/preset/ — 按会话组合 agent；apps/cli/config/agent-presets/ 下自带 minimal / standard / code / cordis 四套

9. 工程设施

typert（类型图生成器 + 运行时注册表）、guard（循环卫生 + 工具超时）、test-support， 以及 scripts/ 下大量文档与目录生成器和门禁。仓库自身的工程强度很高：逐文件 100% 覆盖率门禁、 无密钥的 snapshot 回放测试、双语文档同步、包级运行时不变量。

05可重建性：日志即真相

大多数 agent 框架里，日志是旁路产物——尽力而为地记一点，事后想复盘"模型当时到底看到了什么"，往往拼不回来。 dsh 把这件事反过来：日志是唯一真相，模型历史是从日志推导出来的，从不单独存储。 这条规约在仓库里叫 model-visible ⟺ logged，而且——这是关键——它不是文档里的承诺，是每次请求都实际执行的断言。

日志里存了什么

SessionEventMap 是 append-only 的事件词汇表，序号连续、无损 JSON，所以持久化后端可以逐字存原始日志。 其中有一对容易被忽略的区分：

两者同时在日志里，服务不同消费者：要逐字复现当时屏幕上的流式输出，读 chunk； 要重建下一次请求的 messages，读组装后的消息。这也是"回放 UI"和"重建请求"能各自精确的原因。

重建的两条折叠路径

路径 A：消息历史

deriveMessages() 沿"surface 节点"折叠一个纯投影函数 deriveEventMessage。 只有三类事件会投影成消息：

• user/message — 逐字通过。人类直接输入、agent.inject() 注入的上下文、目标续跑轮次，三者都原样投影，靠 source 字段区分
• assistant/message — 逐字通过，但空内容的会被跳过：那种事件只是用来承载 max-tokens step 的 usage，不能往对话里塞一条没内容的助手轮次
• tool/result — 逐字通过

投影层刻意不加任何框架。像 <system-reminder> 这种包装由生产者在写入 content 时就烤进去 （agent-instructions 就是这么做的），投影只做 verbatim pass-through。 这条约束的意义是：日志里长什么样，模型看到的就是什么样，中间不存在第二次加工。

上下文压缩也在同一套机制里：compaction 写入的是一个 replace 型 surface 节点，它遮蔽掉被替换的历史范围， 于是推导自动排除被压掉的部分——压缩不是删日志，是在日志上加一层遮蔽，原始事件仍在，人类转写仍能读到完整对话。

路径 B：请求头

request/header 记录 model、system、temperature、maxTokens、stop、tools 这些"这次请求在什么配置下发出"的事实。 它只在变化时写（用 headerEquals 判等，避免重复记账）， foldRequestHeader() 扫一遍日志取最后一个快照，就是当时生效的头。

断言长什么样

agent-loop 的不变量伴生包在每一次 llm/stream 上挂了一个检查 （global + prepend——前置是为了防止某个会短路的 replay 监听器把检查静默掉）。 对每个由主循环构造的请求，它逐项验证：

第五项是全部的核心：不是"结构相似"，是 JSON 序列化后逐字节相同。 任何让实际请求偏离日志推导的改动——某个插件偷偷往 messages 里塞了一条、某处绕过事件直接改了历史—— 都会在那一次请求上当场失败，并被指名为 log-reconstruction desync。

读取端：宁可失败，也不给你一份看起来对的错误重建

KNOWN_SESSION_EVENT_TYPES 是生成的常量，列出当前这个 build 认识的全部事件类型。 读日志时遇到不认识的类型，持久化读取路径拒绝解释整份日志——除非该事件自带 ignorable: true 标记。

理由写在源码注释里：这样的日志多半是更新版本的 harness 写的， 而静默跳过一个必需事件会重建出一个错误的会话。所以新增事件类型时，作者必须显式决定 "旧版本读到它可以跳过吗"，而不是让旧版本自己猜。

崩溃恢复：不截断，而是留下一个不可能自然产生的标记

重载一份崩在半路的日志时，会看到有 turn/start 却没有 turn/end。后端不截断—— 长任务的单个 turn 可能非常大，而那些事件在崩溃前已经安全落盘了。它补一个合成的 turn/end { reason: { kind: 'interrupted' } } 把 turn 配平。

妙处在于 interrupted 是唯一一个主循环永远不会发出的 TurnEndReason （取消走的是 aborted）。用一个不可能自然产生的值来标记合成事件， 读日志的人就永远不会把"崩溃恢复的痕迹"误认成"正常结束"。这是个很小的设计决定，但它保住了日志的诚实性。

这对你意味着什么，以及它的边界

06能够怎么用

A. 当成通用编码 agent（最省事）

npx @deepseek-ai/dsh web          # Web UI，默认 http://127.0.0.1:3080

Settings → Models 填 DeepSeek API key（存到 $DSH_HOME/.credentials.yaml，只写不读回， 页面拿到的是脱敏描述符）→ 选工作区 → 开会话。模型改动下一次请求即生效，不用重启。

从源码运行

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness && pnpm install && pnpm run build
pnpm dsh web

B. 一次性任务 / 无人值守

export DEEPSEEK_API_KEY=sk-...
dsh --profile headless "fix the failing test in this workspace"

创建一个持久化会话、跑完、把最后一条 assistant 文本打到 stdout，completed 退出 0，否则退出 1。 不起任何监听端口，成功时不写 stderr。

C. 程序化嵌入

Python

from deepseek_harness import DeepSeekHarness

with DeepSeekHarness(provider="deepseek-official", model="deepseek-v4-flash",
                     cwd="/abs/workspace", session_root="/abs/sessions",
                     cordis="examples/jsonrpc-agent/minimal.cordis.yml") as h:
    r = h.run("Inspect the repository and fix the failing tests.", session_id="job-001")
    print(r.final_response)

同一个 session_id 复用会保留会话独占的 bash 进程——工作目录、导出的环境变量、shell 函数都还在。 独立任务用新 id。TypeScript 走 SDK client，编辑器类客户端走 ACP。

D. 改配置定制（不写代码）

所有定制都是往 cordis.yml / cordis.patch.yml 叠一层。例如接一个 MCP server：

- id: mcp-github
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: github
    transport: stdio
    command: npx
    args: ['-y', '@modelcontextprotocol/server-github']
    env:
      GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN

dsh web --patch ./my.cordis.yml

仓库里已有现成 overlay 可以照抄：

• examples/web-schedule — 持久化的会话内定时提醒
• examples/mcp-memory — 通过通用 MCP 客户端接第三方记忆服务
• examples/headless-agent/e2b.cordis.yml — 把整个执行世界搬到 E2B 远程沙箱
• examples/acp-agent、examples/jsonrpc-agent、examples/web-cordis

E. 写插件并分发

一个 npm 包，package.json 里声明 bundle 清单，然后装进 profile：

{
  "name": "dsh-hello-plugin",
  "type": "module",
  "main": "index.js",
  "files": ["index.js", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

dsh plugin --profile myprofile add ./my-plugin     # 或 github:owner/repo
dsh --profile myprofile

官方建议给插件仓库打 dsh-plugin topic 便于被发现。

07和你的 GitHub 项目怎么结合

按投入从低到高分五层。前两层今天就能用，不改一行业务代码。

- uses: actions/setup-node@v4
  with: { node-version: 22 }
- run: npx -y @deepseek-ai/dsh@0.1.0-rc.5 --profile headless "${{ github.event.inputs.task }}"
  env:
    DEEPSEEK_API_KEY: ${{ secrets.DEEPSEEK_API_KEY }}
    DSH_PERMISSION_MODE: workspace-write

08拿它能做什么

前面几章讲的是"它是什么、怎么接"。这一章讲接完之后能换来什么，以及按什么顺序去换。 排序的依据是单位投入产出：越靠前的档位见效越快、退出成本越低。

再往外想一层

上面五档是"用它"。下面几条是"用它做别人还没做的事"——都建立在这次分析里确认过的能力上。

生态现状

因为官方不接受外部 PR，社区能量全部涌向了插件与技能，生态起步就不冷清。 完整的归类、数据与代表项目见下一章「生态地图」。

下一步：一条具体路径

如果这个项目让你有点心动但不知道从哪下手，按这个节奏走，每一步都有可验证的产出：

09生态地图

官方在 CONTRIBUTING.md 里把话说死了："我们目前无法接受外部 PR"。 公开仓库 deepseek-ai/deepseek-harness 的 PR 数确实是 0，而它有 12,293 个提交—— 开发在私有组织的仓库里进行，公开仓库是发布镜像。

于是社区的全部能量只有一个出口：做插件。这让 dsh 的生态呈现出一种少见的形状—— 它不是围绕"给上游修 bug"长出来的，而是围绕"在旁边造自己的东西"长出来的。官方对此的表述也很明确：

我们并不认为官方仓库中的包天然就比社区开发的包更重要……可以将本仓库看作一种理念、一份官方示例以及一处灵感来源， 而不是我们要求社区遵循的方向。

规模与语言分布

按方向归类

下面这张分布图取的是按 star 降序的前 40 个仓库（去掉官方仓库本身后 39 个）， 约占总量的 9%。长尾未抽样，所以它反映的是"生态的头部长什么样"，不是全量普查。

七个方向，各自在做什么

从这张地图能读出什么

10取舍与现状

和 Claude Code 最大的差异是：Claude Code 是封闭产品加扩展点，而 dsh 连主循环都是可替换的插件行。 代价是概念负担明显更重——profile / bundle / patch / capability seam 这四层概念要先理解，才能有效改它。

什么时候不该选它

• 只想要一个开箱即用的编码助手：成熟商业产品更省心，插件化带来的自由度你用不上，概念负担却要照付
• 需要长期稳定的 API 或磁盘格式：等第一个正式 tag 再说，现在的 pre-release 阶段明确允许破坏性变更
• 团队里没人愿意读 Cordis：不理解插件模型就只能把它当黑盒用，那等于付了定制化的成本却拿不到定制化的收益

11分析方法

本页结论来自对仓库源码与文档的静态阅读：docs/architecture.md、各 package 组的 README、 生成的 docs/tool-catalog.md、apps/cli/reference/README.md、 docs/user/ 下的用户指南，以及 packages/ 下的具体实现与配置清单。

没有构建或运行过这套系统（分析环境没有 API key），所以运行时行为、性能与实际模型效果不在本文的证据范围内； 涉及推测的地方（例如 GitHub Actions 那段 workflow）已在正文中标注。包数量与代码行数由 find 与 wc -l 统计得出。

图表的数据来源

「包依赖结构」一章的所有数字都是脚本现算的，不是抄文档：遍历 packages/<group>/<pkg>/package.json， 取 dependencies 与 peerDependencies 中以 @deepseek-ai/dsh- 开头的条目， 据此统计扇入、按组聚合跨组边权、统计各组包数。仓库自带的 docs/module-graph.md 只用 peerDependencies（它声明那是运行时依赖的规范信号），口径比这里窄，所以两边的绝对数会有出入； 本文取并集是为了反映"实际会被装进去的东西"。

分层图里的四层是我按依赖方向做的聚合判断，不是仓库里既有的分类——仓库官方的分组是 packages/README.md 里那 49 个组。配色经过色觉安全校验（对比度、色盲可分辨度）， 且所有色块都带可见文字标签，不依赖颜色单独传达信息。