DeepSeek Harness 官方仓库与架构

一句话摘要：DeepSeek Harness 是 DeepSeek AI 于 2026-08-13 开源的 agent harness（智能体框架），采用”一切皆插件”（everything is a plugin）架构，由 Cordis 插件框架驱动——模型适配器、工具注册表、会话日志乃至 agent loop 本身都是可替换的插件，开发者可在配置里选择/替换/扩展任何能力，而不改源码。

---

一、这是什么

DeepSeek Harness（dsh）是 DeepSeek AI 开发的开源 agent harness，MIT 协议，TypeScript 实现。开源约 10 天即达 18 万+ stars。当前处于 developer preview（开发者预览）阶段，官方明确声明：

“DeepSeek Harness is currently in developer preview and is iterating rapidly. THERE WILL BE COMPATIBILITY-BREAKING CHANGES.”

官方公告页给出定位：它面向 agent harness 开发者（而非终端用户），目标是让开发者能像搭积木一样组合出一个 Agent 环境。

二、核心命题：一切皆插件

官方公告原文：

“Every capability is a plugin that can be swapped or recomposed: models, tools, skills, sessions, sandboxes, storage, loops, scheduling, and the UI.”

每一项能力都是一个可以替换、可以重组的插件：模型、工具、技能、会话、沙箱、存储、循环、调度，乃至界面本身。

架构文档的表述更彻底：

“Every part of the product is a plugin, including the model adapter, the tool registry, the session log, and the agent loop itself, so every part is replaceable from configuration.”

产品的每一个部分都是插件，包括模型适配器、工具注册表、会话日志，以及智能体循环本身——所以每个部分都能通过配置来替换。

“There is no privileged core to patch: you extend dsh by mounting a plugin beside the others, and registrations are effects that unwind when their plugin unloads.”

这意味着与 Claude Code 那种”硬编码核心 + Hook 挂载点”的模型有本质区别：DSH 里没有不可修改的核心。连 agent loop 都是 core/agent-loop 这个插件，可以整块换掉。

三、Agent = Model + Harness

官方公告页沿用了一个与 Harness工程 页面一致的公式：

“Agent = Model + Harness”

“The model is the soul of an agent. A harness lets an agent understand its environment, use tools, and keep working in real-world settings.”

**模型是智能体的灵魂。**而框架让智能体能理解环境、使用工具，并在真实场景中持续工作下去。

四、Cordis：底层插件框架

DSH 由 Cordis 驱动，Cordis 的五个核心思想（primer 原文归纳）：

1. 插件是对象：一个插件是实现了 Service 的对象（可以是带 inject/apply(ctx) 的函数，或 Service 子类）
2. 上下文是服务仓库：服务在 context 上占用稳定的 ctx.<key>（如 ctx.tools、ctx.llm、ctx.sessions）
3. 用 inject 声明依赖：加载顺序由服务依赖表达，而非手动启动序列
4. Typed events 通信：事件按 emit / waterfall / parallel / serial 四种模式分发
5. 注册是可逆 effect：通过 ctx.effect() / ctx.on() 安装，卸载时可预测地回退

事件分发模式：

Mode	是否 await	顺序	有返回值
emit	否	注册顺序	否
waterfall	否	注册顺序	是
parallel	是	并行	否
serial	是	注册顺序	是

Waterfall 是”环绕式中间件”：监听器收到 (...args, next)，调 next() 委派给下一个服务；直接 return 则短路。

五、组合机制：Profile 与 Bundle

一个运行中的 dsh 是一棵在启动时按序分层组装出来的插件树：

• Profile：命名组合，存在 Harness home；列出所堆叠的 bundles、持有的外置插件、用户的 cordis.patch.yml。web 与 headless 是内置模板。
• Bundle：Cordis config rows + 代码的分发格式，dsh.profile 列 bundles、dsh.bundle 指向 patch 文件。
• 分层顺序：各 bundle 按序 → profile 的 patch → home 级 patch → --patch 覆盖层。patch 按 row id 定位并整体替换。

用 dsh --profile web --dump-config 可查看本机实际启动的树，任何一行都能被自定义 patch 替换。这就是”配置即组合”（compose with configuration）的落点：

“Developers can select, swap, or extend any capability in configuration without changing the DeepSeek Harness source code.”

六、核心包：六个包组成一条 loop

一条 turn 流经六个核心包（packages/core/），每个都是 Cordis 树中的插件：

Package	职责	ctx key
session	append-only SessionEvent log + 内存 store	ctx.sessions
system-prompt	prompt-section 与 tool-schema 装配	ctx.systemPrompt
tools	scoped tool registry + guarded execution pipeline	ctx.tools
agent	Agent 接口、live registry、agent/* 事件	ctx.agents
agent-loop	默认 driver（Agent 契约的唯一具体实现）	ctx.agentLoop
scope	per-agent scoped-registration 原语（库，非服务）	—
llm（packages/llm）	message/stream 词汇 + adapter seam	ctx.llm

关键点：agent-loop 是 Agent 契约的一个具体实现，扩展插件依赖 agent 接口而非 agent-loop，“so the loop stays swappable”（循环保持可替换）。

七、Turn flow（回合流转）

step 与 turn 的定义：

“A step is one model request plus the tools it calls. A turn is zero or more steps: it opens before its first input is claimed and closes once nothing is owed.”

step（步） = 一次模型请求，加上这次请求所调用的工具。turn（回合） = 零个或多个 step：它在第一个输入被认领之前开启，在没有待处理事项时关闭。

流转链（原文缩写）：

turn/start → claim next-step input → assemble prompt + tool schemas
  → agent/pre-step (reject | enter) → step/start → append user/message
  → derive model history from the log → agent/request → llm/stream
  → assistant/chunk* → assistant/message → tool/call*
  → tools/pre-execute → tools/execute → tools/post-execute → tool/result*
  → step/end → (tools owe another request, or next input arrived) → claim → next step
  → agent/turn-stopping → turn/end

其中 agent/pre-step、agent/request、llm/stream、三个 tools/* 事件是 waterfall（监听器必须调 next()）；agent/turn-stopping 是 serial 且无 next()。

八、会话日志：单一真相源

这是 DSH 最重要的设计之一（详见 会话日志单一真相源）：

“The session log is the source of the context the model sees. deriveMessages() projects model history from it.”

“Model-visible means logged. Anything that reaches a model request must be reconstructable from the log, and a runtime invariant asserts it.”

官方公告页对用户侧可追溯性的表述：

“Everything the model sees is recorded in an append-only session log: system prompts, reasoning, tool calls and results, subagent scheduling, and every context injection. In the Trajectory view, you can inspect these records by source. Resume, fork, search, and replay all operate on the same event stream.”

模型看到的每一样东西都被记进一条只能追加（append-only）的会话日志里——系统提示词、推理过程、工具调用与返回结果、子智能体的调度，以及每一次上下文注入。在 Trajectory 视图里可以按来源逐条查看。恢复、分叉、搜索、重放，全都基于同一条事件流。

Session 文档原文：

“A Session is an append-only log of typed SessionEvents — the single source of truth… The LLM message history is derived from the log, never stored separately; replay is re-derivation from the same events.”

Session 是一条只能追加的、带类型的 SessionEvent 日志，是唯一真相源。给大模型的消息历史是从这条日志推导出来的，从不单独存一份；所谓重放，就是用同一批事件重新推导一遍。

九、能力接缝（Capability Seam）

“A seam is a swappable capability with three roles: a Service Definition declaring the interface, a Service Provider implementing it, and a Consumer using it, commonly a model-facing tool.”

一个「接缝」是一个可替换的能力，包含三个角色：服务定义（声明接口长什么样）、服务提供者（把它实现出来）、消费者（去用它，通常就是暴露给模型的那个工具）。

接缝的价值在于”一次 provider 替换改变整个产品”：

“Filesystem and subprocess providers share one execution world, so pointing them at a remote sandbox moves Bash, PTY, and LSP with them, with no provider forks.”

详见 能力接缝。

十、四种运行时模式

官方公告页列出四种模式，覆盖从”全功能工程派”到”极简派”到”自省”的光谱：

1. Standard mode：完整工具集（file editing、shell、file/web search、skills、planning、goals、subagents、workflows）
2. Code mode：Standard 全部能力，但工具通过 Code Mode SDK 暴露，“so the model can combine multi-step operations in one TypeScript program”
3. Minimal mode：只保留两个工具——persistent bash + str_replace_editor，“for benchmarking models in a minimal environment”
4. Creator mode：inspect 当前 runtime、内存中测试 Cordis 插件、组合成新模式

十一、Agent Notes 制度

DSH 仓库有一个独特的设计：.agents/notes/ 目录存放 Agent Notes——由 agent 自己撰写的、类 RFC 的设计决策记录。定义原文：

“An Agent Note records a decision or proposal that affects this codebase — the why and what we gave up, the parts code and docs can’t carry.”

强制要求：

“Every non-trivial change MUST add or update at least one Agent Note in the same PR.”

生命周期（proposed / implemented / rejected）、分类（feature / bug-fix / simplification / architecture / process / testing）、以及”被完全取代后合并删除”的归档策略都写在 .agents/notes/README.md。详见 Agent Notes。

十二、工程规约（AGENTS.md）要点

仓库级 AGENTS.md 揭示了几条硬性工程原则（原文摘录）：

“Registrations are effects: every contribution goes through ctx.effect() / ctx.on(); a registry’s register() returns the disposer.”

“Plugins, not loop changes: new behavior goes on documented extension points; changing agent-loop requires updating docs/architecture.md.”

用插件，不要改循环——新功能应该加在已有的扩展点上；如果非要改 agent-loop，就必须同步更新 docs/architecture.md。

“Model-visible ⟺ logged: anything that reaches a model request must be reconstructable from the session log.”

模型可见 ⟺ 已记录——任何进入模型请求的内容，都必须能从会话日志里重建出来。

测试标准极高：packages/*/*/src 每文件 100% 覆盖率是 CI 门（test:coverage）。

Pre-release 姿态：foundation over blast radius（基础优先于影响半径）——没有外部消费者时，优先选择正确的基础而非兼容性垫片。

十三、运行方式

• npx @deepseek-ai/dsh web（默认 http://127.0.0.1:3080，--no-open 仅启动服务器）
• 或源码：pnpm install → pnpm run build → pnpm dsh web
• 需要 DEEPSEEK_API_KEY（可配 DEEPSEEK_BASE_URL 接其他 OpenAI 兼容端点）

十四、与既有知识网络的对应

• 公式一致：官方 “Agent = Model + Harness” 与 Harness工程 页面的公式完全一致。
• 循环可替换：对比 learn-claude-code教程 “循环永远不变”——DSH 把循环本身也做成插件，但默认循环仍是一个稳定契约。
• 极简派被内置为模式：Minimal mode（两工具 + bash + str_replace_editor）正是 pi-coding-agent最小化设计 / Mario Zechner 路线的内置化。
• Subagent / Agent Team：DSH 用”能力接缝”统一实现，experimental Agent Teams 是 private opt-in 协调接缝。
• Hooks 桥接：packages/hooks 提供 Claude Code/Codex hook bridges，说明 DSH 选择”兼容既有生态”而非”另起炉灶”。

重要引用汇总

“Everything is a plugin.” —— 官方公告页副标题

“Every run is traceable.” —— 官方公告页设计取向

“There is no privileged core to patch.” —— docs/architecture.md

不存在一个需要你去打补丁的特权核心。（意思是：系统里每个部分都是平等的插件，没有一个「动不得」的内核。）

“The model is the soul of an agent.” —— 官方公告页

“A seam is a swappable capability with three roles: a Service Definition… a Service Provider… and a Consumer…” —— docs/architecture.md

接缝 = 一个可替换的能力 + 三个角色：服务定义 / 服务提供者 / 消费者。