DeepSeek Harness 深度分析报告

01项目基本盘分析

DeepSeek Harness(命令行入口 dsh)是 DeepSeek AI 于 2026 年开源的 agent harness(智能体运行环境),定位与 Claude Code、Codex CLI 类似 —— 一个由 LLM 驱动、可执行工具、面向终端或 Web 的对话式编程助手。但它在底层架构上做出了根本不同的选择。

与同类项目的根本差异

用一句话概括区别:Claude Code 给你一个产品;DeepSeek Harness 给你一个平台。

02核心理念与设计哲学

整个仓库的 AGENTS.md、architecture.md、glossary.md 围绕几条不可妥协的原则组织:

2.1 五条核心原则

2.2 工程语言层面的硬约束

• ESM 唯一 —— "type": "module";Node 原生 TS 模式不可用(因 engines 跨 22.19/24)。
• 严格类型 —— strict: true + noImplicitAny;剩余 any 必须解释为何无法收窄。
• 同进程信任 —— TS 已验证的内部接口不做运行期校验,只在 parser/config、queued、模型/工具 JSON、持久化、worker、process、wire 边界做。
• 品牌类型 —— 跨边界 id 全部 Branded<B>,绝不裸 string。
• 对称优先 —— 平行值用对称命名,不对称的形状通常是漏掉抽象。

03基础框架:Cordis 五大概念

dsh 整个运行时建立在 自带的 Cordis(vendor/cordis/)之上,Cordis 源自 Koishi/cosmonium 生态,被 dsh vendoring 进来并 rescope 为 @deepseek-ai/cordis。还附带 cosmokit、include、loader、logger-console、schemastery、timer 等子模块。

3.1 Cordis In Five Ideas

3.2 四种派发模式

3.3 Waterfall 中间件语义

// 监听器签名: (...args, next) => result
ctx.waterfall('agent/pre-step', async (messages, turn, next) => {
  // 1) 改写请求
  const filtered = messages.filter(m => !m.internal)
  // 2) 委托给下一个 listener
  return next(filtered, turn)
  // 不调 next() = 短路,后续 listener 看不到
})

04整体架构:三层关注点分离

dsh 把"扩展点"按域划分,新增功能第一件事就是选域:

4.1 单轮生命周期(Turn Flow)

一个 step = 一次模型请求 + 它引发的工具调用。一个 turn = 零或多个 step。Turn 在第一个 input 被 claim 时打开,在"什么都没欠"时关闭。

4.2 关键概念:Scope 与 Agent Context

每个 Agent 有自己的 agent.ctx(作用域上下文)。注册通过它贡献 = 作用域可见 AND 作用域生命周期。工具/提示段/变量在 agent 维度有"全局"和"作用域"两层。最具体者获胜(shadowing)。

05核心包与循环驱动

整个 dsh 只有一个包包含具体循环逻辑:packages/core/agent-loop/。其他全是抽象服务或扩展点插件。

5.1 包族谱

5.2 AgentLoop 是唯一的具体循环

// ctx.agentLoop.create() —— 同步无 setup 的创建
const agent = ctx.agentLoop.create(id, { cwd }, meta)
// driver 跑在 ctx.agents.withInitiator(agent, ...) 里
// Agent 拥有自己的会话;构造/恢复是一回滚事务
// —— 私有 session + concrete agent + scoped ctx,await setup,
// 同时 enter 两个 registry,宣布 session/created → agent/created
// → agent/session-start,然后才启动 driver

5.3 统一 send 原语

Loop 提供统一的 send() 原语,通过 (target × wakeup) 路由内容与唤醒:

• followup() → append next-turn FIFO + 唤醒 driver
• steer() → append next-step inbox + 唤醒 driver
• inject() → append next-step inbox + 不唤醒

5.4 Inbox 操作发布规范事件

每个 inbox 变化都先发归一化事件再改投影:

• agent/inbox/spliced —— 标准 splice 坐标
• agent/inbox/inserted · agent/inbox/discarded · agent/inbox/claimed
• MessageId 在两个 pending 列表间唯一;同步持久事件观察者能从 pre-splice 投影重构移除值

5.5 取消与唤醒闭锁(Wake Latch)

关键状态:idle → running → idle 过渡对,即便 message 已被 clear 也保留;disposed 取消永不 latch;持久 turn/end 对 user/parent 记录 aborted,对 disposal 记录 disposed。

5.6 内置请求重建不变量

每个 agent-loop/invariant companion 把请求注册到 ctx.invariants。loop 在 dsh-llm 拥有的进程内 identity 集合里记录每个精确的 frozen request,然后独立从日志重建消息边界 + folded request header。

06能力接缝(Capability Seams)

每个能力是一个 seam,由三角色组成:

6.1 重要接缝一览

6.2 单一接缝的角色分离原则

从 glossary.md:

• 角色通常按独立演化的需要分到不同包;一个包可以承担多个角色,如果是一回事(dsh-llm 同时拥有 SD 和 Consumer)。
• seam 是完整能力,绝不是单一角色;术语 seam 保留为这层意思。
• 反 smell:一个 Service 公开方法只有一个内部 caller —— 用私有 capability closure 替代。

07会话日志即真相(Model-visible ⟺ Logged)

这是整个 dsh 最深的不变式 —— 它解释了为什么 dsh 与 Claude Code 在工程上完全分道扬镳。

7.1 为什么日志是"唯一真相"

7.2 SessionEvent 类型与版本化

// dsh-session 保持 SESSION_FORMAT_VERSION = 0,无兼容承诺
interface SessionEventMap {
  'session/created': { sessionId: SessionId, ... }
  'turn/start':      { turnId: TurnId, ... }
  'step/start':      { stepId: StepId, turnId: TurnId, ... }
  'user/message':    { messageId, role, content }
  'assistant/chunk': { seq, delta, ... }
  'assistant/message': { messageId, content, sourceEventSeqs, usage }
  'tool/call':       { callId, name, args }
  'tool/result':     { callId, content, error? }
  'turn/end':        { reason: 'completed' | 'aborted' | 'disposed' }
  ...
}

事件 member 默认 require-on-read:build 不知其类型时拒绝 log,除非事件携带信封的 ignorable: true;只有结构性格式变更才升 SESSION_FORMAT_VERSION。

7.3 KV-Cache 友好的 Append-only

从 agent-loop/README.md 的 Model Experience 节:

• 系统文本/工具 schema: 每步重发;若装配字节相同则 KV cache 复用。
• 历史增长: append-only 直至 compaction shadow;普通增长不破坏复用。
• 取消后重放: 每个未派发的 tool call 收到 ABORTED_BEFORE_DISPATCH 合成结果,append-only 跟随复用前缀。

08插件组合模型:Profile + Bundle + Patch

一个运行的 dsh 是一棵按有序层组合的插件树。

8.1 三个术语

8.2 加载顺序(从空 entry list 开始)

1. profile 列出的每个 bundle(按 dsh.profile.bundles 顺序)
2. profile 的 cordis.patch.yml
3. home 级别的 cordis.patch.yml
4. 任何 --patch <path> overlay(可重复)

8.3 dsh-base 是所有 profile 的第一层

它通过 cordis.patch.yml 插入所有基础插件:模型适配器、共享 agent-default-model 选择、工具、持久化、策略、settings/credentials、telemetry、host-level subagent providers。Codex/Claude provider 装载但休眠。

它通过平台 gate 实现 POSIX/Windows 单 shell stack:

# 同一 patch 文件,一个平台一份 shell stack
bash-sandbox:  disabled: !!js process.platform === 'win32'
tool-bash:     disabled: !!js process.platform === 'win32'
pwsh-sandbox:  disabled: !!js process.platform !== 'win32'
tool-pwsh:     disabled: !!js process.platform !== 'win32'

8.4 用户诊断命令

$ dsh --profile web --dump-config        # 看实际启动的树
$ dsh --profile web --dump-default-config # 不含用户层和 --patch overlay
$ dsh web --help                          # web app 自己的 flag
$ dsh plugin --profile tui add <pkg>      # 给 profile 装插件

8.5 Loader 配置的细节

@deepseek-ai/cordis-plugin-include 解析 !!js 为表达式节点。Loader 在该插件上下文(已声明 injection 激活后,作用于 ctx.serviceName)插值 entry 的 config;disabled 在每次装载决策时对 loader 上下文求值。其他 entry 元数据保留字面值。

09事件系统与三种派发模式

9.1 关键 domain 事件清单

Session Events(durable)

Agent Events(live coordination)

9.2 事件命名 / 文档约束

• 事件 JSDoc 必须标 @mode 和 payload 的 @param
• scoped key 在 payload 缺失时标 @dshScopeScan unsupported
• 生成器(gen-cordis-catalog)从源头生成 fresh 列表;手编辑被门禁拒绝

10自我修改(Self-Modification)能力

这是 dsh 区别于 Claude Code 最戏剧化的能力 —— 模型可以读写自己运行的 Cordis 运行时。packages/extensions/ 提供此功能,Agent Note 2026-07-08-self-referential-cordis-toolset 详述设计。

10.1 实际能力

• Inspect: 列已装载插件、服务 API、活动事件
• Define: 模型可写一个 cordis 配置,在 node:vm 沙箱中编译为插件
• Mount/Unmount: 装载插件 + 卸载时自动 dispose 所有贡献
• Retract: 撤回自己写过的定义,清理由其产生的副作用

10.2 安全护栏

虽然模型可以改自己的运行时,但仍受沙箱约束:

• 动态代码在 node:vm 隔离上下文求值,无法直接访问 Node 全局
• 所有插件依然要经过 Service Definition 的服务契约校验
• 外部模型注入依然走 agent/pre-step 中间件,可被策略层拦截
• 权限预设(permission-preset)约束工具调用

10.3 与 Claude Code 对比

Claude Code / Codex 都没有自我修改能力。dsh 把"agent 修改自己的运行时"作为头等公民 —— 与 preset/(per-session 预设)、guard/(循环卫生)、extensions/(自修改)三者并列,构成 dsh 的"agent 元能力栈"。

11多语言、多面、多 UI 矩阵

11.1 三种语言

11.2 两面构建(host + client)

构建矩阵确保编译 face 显式:每个包用一个聚合(tsconfig.base.json 或 tsconfig.base.client.json),只有 api/remotes 拆为两个 face(因为它有生成的对外合约)。

11.3 五种部署形态

12测试与质量门禁体系

dsh 把"质量"做成可执行门禁而非文档。仓库根 scripts/run-gates.ts 编排大量 verify-* 脚本,CI 拥有完整信号。

12.1 测试体系

12.2 静态生成 & Freshness 门禁

以下目录/文件由源生成,且由 --check 模式 freshness-gated:

• docs/subsystems/ 的 cordis-surface 区域(每页)
• docs/cordis-api/(Cordis 核心 API + 继承 tier)
• docs/tool-catalog.md · docs/config-catalog.md · docs/persistence-catalog.md · docs/module-graph.md

12.3 Hygiene 全套

$ pnpm run hygiene
   ↳ rescope-vendor:check    # Cordis 是否仍 rescope 正确
   ↳ knip                    # 未用导出 / 死代码
   ↳ publint                 # package.json 导出契约正确
   ↳ constraints             # workspace 约束
   ↳ verify-dsh-package-licenses
   ↳ verify-package-invariants
   ↳ verify-built-package-invariants
   ↳ verify-cordis-config    # raw/plugins 必须在 resolver manifest 的 dependencies
   ↳ verify-node-next-types
   ↳ verify-runtime-closure
   ↳ verify-vendored-links

12.4 文档门禁

• verify-doc-budgets —— 每个 doc 有字数上限,超限拒绝(根 AGENTS.md ≤1600,architecture.md ≤1800 等)
• verify-md-wrap —— 一段一行,软换行
• verify-md-links —— 链接存活 + 锚点正确
• verify-export-jsdoc —— 每个 export 有 JSDoc 覆盖
• verify-type-equiv —— doc 里贴的 TS 类型不能漂移
• verify-package-readme-model-experience —— 强制 Model Experience 节存在
• verify-package-readme-limitations —— 限制要么写,要么进 allowlist

12.5 测试理念(摘自 testing.md 链)

13与 Claude Code / Codex 详细对比

为避免与公开产品做无证据比较,下表只对比公开架构属性。

13.1 架构差异带来的影响

14优势、局限与适用场景

14.1 工程优势

14.2 局限与代价

14.3 适用场景

15结论与未来展望

15.1 一句话总结

把 agent harness 当作可组合平台来设计,而非可调用产品来提供 —— 这是 dsh 与现有竞品最根本的分野。它付出了陡峭学习曲线和文档密度的代价,但换来了"任何层都可被替换"的根本自由度。

15.2 设计哲学的五个"先于"

• 正确性先于兼容性(pre-release stance)
• 插件先于核心(everything is a plugin)
• 数据先于产品(Model-visible ⟺ Logged)
• 契约先于实现(capability seam 三角色)
• 门禁先于流程(每个机制都有机器可执行信号)

15.3 关键里程碑(自观察到的 Agent Notes)

15.4 未来值得关注的演进方向

• 正式 1.0 发布(pre-release stance 移除,意味着兼容性承诺)
• SCHEMA_VERSION / SESSION_FORMAT_VERSION 跃迁与兼容性策略
• BENCHMARK.md 内容沉淀(目前是骨架)
• Python SDK 与进程外 JSON-RPC 的扩展
• E2B(已在 packages/e2b/)走向产品级
• 更多 IDE 集成(目前只有 hook 桥)

15.5 给不同身份读者的"读这份仓库"建议

报告基于 v0.1.0-rc.5 源码 + Agent Notes + 文档快照;所有特性与数据来自仓库 /Users/wangzhikui/github/deepseek-harness,日期 2026-08-15。
随着 dsh 持续迭代,文档层级与 seam 设计可能演进,请以最新版的 architecture.md + glossary.md 为权威。

16模块依赖图与门禁链(可视化)

最后用两张动态图把前面 15 章的工程结构再"看一眼":包拓扑与构建/测试门禁链。