DeepSeek Harness (dsh) 整体架构解析

01项目定位

dsh 是一个 Agent 执行框架:围绕"一次模型请求 + 其引发的工具调用"的循环,把 会话存储、提示词组装、工具注册、模型适配、权限审批、Web UI 等全部产品能力组织成 一个可组合、可替换的插件树。运行时由 cordis.yml 描述,插件通过事件与服务协作, 没有特权核心需要打补丁 —— 要扩展 dsh,就挂一个插件,甚至可以用插件修改自身的运行时。

02核心思想:一切皆插件

这是整个架构的第一原则:模型适配器、工具注册表、会话日志、agent 循环本身 —— 全部是插件。插件贡献三类东西到共享的 Cordis Context:

03组合分层:Profile → Bundle → 插件树

一个运行的 dsh 是从空条目列表开始、按固定顺序叠加配置层得到的插件树。

验证你机器上实际启动的树:

dsh --profile web --dump-config — 打印的每一行都可以被你的 patch 覆盖。

04运行形态

05核心包:产品 API 脊梁

六个包构成主干,在 Cordis 树上挂出各自的 ctx 服务:

作用域(Scope)机制

每个活体 agent 拥有自己的 agent.ctx:通过它注册的贡献(工具、提示词区块、变量、限制、监听者)既是 scope 可见又是 scope 生命周期 —— 一个事实同时驱动两者。影子(shadowing)规则:同名注册时最具体者胜出, 一个 agent 可以拥有自己的 persona 与工具变体。作用域是扁平的(不向子 agent 继承),子树行为用 lineage 数据表达。

06回合流:step 与 turn

step = 一次模型请求 + 其响应引发的工具执行;turn = 零或多步,打开于首个输入被认领之前, 在不再欠任何响应时关闭。绿色 = 持久化会话事件(turn/* step/* user/message assistant/* tool/*), 紫色 = 活体扩展点。

07会话日志:模型可见 ⟺ 已落盘

会话日志是模型所看到上下文的唯一来源。核心不变量:

会话事件是带类型的(SessionEventMap 声明合并 + 可合并扩展映射),默认"读取即必须知晓"—— 构建时不知道其类型的组件拒绝写入日志,除非事件携带信封的 ignorable: true。 事件 JSDoc 需要 @mode 与 payload @param;只有结构性格式变更才提升 SESSION_FORMAT_VERSION(当前 0)。

08能力缝(Seam):Service Definition / Provider / Consumer

缝 = 可替换能力,恰有三个角色,三者齐备才算一条完整的缝,单独一个角色不是:

一条缝的换供换面:换一个 Provider 就换整个产品。FS 与子进程 Provider 共享同一个执行世界 —— 把它们指向远端沙箱,Bash / PTY / LSP 一起跟着走,无需分叉任何 Provider。Subagent Provider 家族同样如此: 从全新子 agent 到另一产品中的委托回合,共用同一个接口。

09事件域:三种扩展点

选对事件域是大多数改动的第一步:

带作用域的分派:关于某个 agent 活动的事件用该 agent 的 carrier 分派(只放行未打标签的监听者 + 该 agent 自身的); 关于注册表本身的事件(如"加了工具")保持不过滤。完整事件表见 docs/event-producer-consumer.md。

10与传统 Agent 框架的异同

以 LangChain / LangGraph、AutoGen、OpenAI Agents SDK 等为代表的主流框架作对照: 概念词汇高度对齐(loop、tools、LLM 适配、提示词、记忆、子 agent、人工介入一应俱全), 但每个组件在 dsh 里的地位不同 —— 没有任何一个组件是框架内置的"特权核心"。

循环本体的直观对比

while (用户有输入) {
  history = memory.load()
  prompt  = template.render(history)
  reply   = llm.chat(prompt)        // 框架内部
  if (reply.hasToolCall)
    result = tools.execute(reply.calls)
  memory.append(reply, result)
}
// 想改循环?fork 框架或在回调里绕

turn/start
  → agent/pre-step      // 瀑布:可改写/拒绝输入
  → deriveMessages()    // 从会话日志投影
  → agent/request       // 瀑布:请求前拦截
  → llm/stream          // 瀑布:流式对话
  → tools/pre→execute→post  // 瀑布:守卫管线
  → step/end
  → 欠请求?循环 : agent/turn-stopping → turn/end
// 每一环都是事件:监听者就是扩展点

11扩展点总表:新行为放哪里

12包分组一览

依赖方向铁律:扩展插件依赖 Service Definition,绝不依赖具体 Provider。dsh-agent-loop 可换; UI、hook、工具插件只用 dsh-agent。依赖图是生成的:docs/module-graph.md(pnpm run gen-module-graph,CI 门禁新鲜度)。

13工程约定(节选)

• 类型安全 — 处处 strict: true + noImplicitAny;跨类型化同进程边界的值不做运行时校验("信任 TS"),校验放在 parser/config、queued、模型/工具 JSON、持久化/文件、worker、进程、线等真实边界。
• 不透明跨边界 id 全部 branded(Branded<B>),绝不裸 string。
• 类型化事件用声明合并(merge-extensible maps);闭联合以 assertNever 收尾,可合并联合走文档化 default。
• 插件内无硬编码可调参数 — 部署可变的选项是 Config 字段,可从 cordis.yml 改;协议常量与安全不变量保持固定。
• 误配置大声失败 — 加载时即败(自包含场景),否则在最早可解析点失败;绝不静默跳过缺失引用。
• 显式 > 隐式 — 包边界上的默认值是拥有方实现中显式的 resolve(request): Spec 步骤,绝不是在 run() 里藏一个 ?? default。
• 发布状态的提交点 — 操作成功后才发出通知/更新派生状态;缓存、提示词、UI 回声、回放、查询视图都从一个权威源派生。
• 完整结果上施加边界 — 字节/词元/条目/时间限制施加在"完整发出或保留的值"(含包装与元数据)上。
• 包边界词汇 — 文档用"response fields / JSON validation / ESM exports"这类精确词,不用隐喻;注释写完整契约而非推理过程。
• ESM everywhere;本地相对导入用 .ts 后缀;包间用包名;源码启动经 tsx ESM hook。

14质量门槛

15术语速查

turn / step / round

turn — 会话中一次受纳输入的排空,模型与其工具停止或终态策略介入后结束;step — 一次模型请求 + 其响应引发的工具执行,turn 含零或多步;round — 外层策略的一次迭代(如 goal round 或 Ralph fresh-agent 尝试),round 计数属于该策略。

scope / scope key / shadowing

per-agent 注册单位;key 是活体 agent 自身(对象同一性比较);同名最具体者胜出,scoped 注册不向子 agent 继承。

goal / goal activation

附着于现有会话的一个持久完成目标,带修订版 active/paused/blocked/complete 相位与 round 上限;activation 故意不进入持久重放 —— resume/fork 需要后续人类授权。

human command

斜杠前缀的人类指令,经 ctx.commands 解释执行,不成为模型消息(与模型工具、shell 执行都不同)。

Ralph loop

面向不可变目标的 fresh-agent 工作流:每轮一个全新子会话、无父代/前轮的对话种子,共享工作区 + 有界结构化 handoff 传递跨轮状态。

Model Experience

每个产品包 README 的固定章节:从模型视角写提示词、工具 schema、结果与诊断,只含任务相关概念,不含 UI/传输/实现词汇;稳定模型可见文本逐字固定。

16资料来源

• docs/architecture.md — 架构总图(改动 packages/ 前必读)
• docs/glossary.md — 规范术语表
• docs/agent-lifecycle.md — 序列图; docs/tool-execution-pipeline.md — 工具管线
• docs/capability-seams.md — 能力缝图谱; docs/event-producer-consumer.md — 事件生产/消费表
• docs/subsystems/ — 每子系统一页的类型定义与语义
• packages/README.md — 包分组总表; vendor/README.md — vendored Cordis 同步流程