Dsh Architecture

DeepSeek Harness 架构（源码级审计）

Overview

DeepSeek Harness（dsh）是 DeepSeek AI 的开源 agent harness（@deepseek-ai/dsh，MIT，developer preview，版本迭代快、有破坏性变更）。核心信条："Everything is a plugin"——没有特权核心，包括 agent loop 本身都是插件。底层是 vendored 的 Cordis 插件框架（设计论文《A Programming Paradigm for Spatiotemporal Composability》）。

本技能记录源码审计结论（基于仓库 master 源码），用于理解 dsh 行为、评估插件、与 Hermes 对照。

When to Use

• 理解 dsh 的架构决策（为什么这样设计）
• 评估/编写 dsh 插件（事件、service、seam 选择）
• 排查 dsh 行为异常（会话日志、子代理、工具调用）
• 与 Hermes 架构对照（身份系统 vs 插件哲学）

仓库布局

vendor/            # Cordis 及周边 vendored 包（插件框架本体）
packages/core/     # session / system-prompt / tools / agent / agent-loop / scope
packages/web/      # web seam（web / tool-web / web-search-* / web-fetch-http）
packages/subagent/ # subagent seam（subagent + 6 个 provider 包）
packages/bundle/   # 分发格式（base / web-app / headless）
packages/boot/     # 启动装配（app-boot）
packages/client/   # Web UI（浏览器端）
docs/              # 官方文档（architecture.md 等，质量高）

Cordis 插件框架（vendor/cordis/src，9 文件 2693 行）

五件套（源码逐行确认）：

核心机制：

1. Context 是 Proxy：构造时 new Proxy(this, ReflectService.handler)。属性读取走服务解析器；extend() 原型继承创建子上下文（父不变）；isolate(name, label) 给服务创建独立作用域（同 label 合并）；intercept() 注入服务级配置。
2. 5 种事件派发模式（events.ts，模式是事件公共契约，@mode 标注）：
   • emit：同步、不 await 返回值（观察）
   • parallel：Promise.allSettled 并发，聚合错误
   • serial：按序 await 直到 isBailed()（非 null/false/undefined）（决策）
   • bail：同步版 serial
   • waterfall：洋葱中间件——最后一个参数是 next，不调 next() 即 veto 整条链
3. Fiber 生命周期（fiber.ts）：

   PENDING → LOADING → ACTIVE → UNLOADING → DISPOSED
                ↑_________________↓
               (依赖变化触发 _reload/_unload)
   

   • 每个插件实例 = 一个 Fiber，持有 _disposables
   • 依赖即状态：_refresh() 把 inject 服务的 fiber uid 拼成 epoch 字符串；epoch 变化即重载/卸载——加载顺序由服务依赖声明驱动，无手动 boot 顺序
   • effect() 注册可逆副作用：disposer 按逆注册序执行；支持 generator/async iterable
   • update() 走 internal/update waterfall，HMR 插件可 veto
4. DI：ctx.inject(['agents'], cb) = 服务可用时运行，变化自动重跑；@Inject 装饰器（类/方法级）；插件形态统一 function/class/{apply} 三种，registry.resolve() 提取 callback 作为运行时身份键。

会话模型：Session Log 是唯一事实源

packages/core/session/src/index.ts（1157 行）：

• "Model-visible means logged"：任何到达模型请求的东西必须能从日志重建（运行时不变式断言）；新增模型可见输入必须扩展 SessionEventMap（declaration merging 可扩展）
• Session = append-only SessionEvent[] 日志，seq = log.length 连续性契约
• deriveMessages() 从日志派生 LLM 历史（带缓存：surface 节点每节点投影一次，compaction 失效重建；返回对象共享且 deep-frozen）
• firstLiveSeq 区分构造种子（replay/fork/resume）与进程内新事件；session/end-seed 标记持久化边界
• 种子验证严格：JSON 无损序列化 + envelope + seq 从 0 连续 + surface 转换合法（"坏 seed 不会晚到后端才爆"）
• invariant.ts：session-invariant 插件用 trace 状态机验证事件序列（如 tool/call 配对）

Subagent Seam（多代理）

packages/subagent/subagent/src/（4531 行）核心文件：

关键设计：

1. 子代理是可选的 capability seam，不属于 agent loop——多 provider 共存按名注册（in-process / fork / ACP / Codex / Claude Code / dsh-sdk）
2. Fail loud：provider 静态 descriptor 宣告能力（outputSchema/depthLimit/toolFilter/persona），请求缺能力 → 启动时 typed error（UNSUPPORTED_CAPABILITY），绝不静默降级
3. Continuable children：

   持久化 Session → 至多一个 live Activation → 一个 AgentHandle
   → Agent inbox 唯一 turn FIFO → 零或多个 owned child Activations
   

   • Activation 状态（running/waiting/settled）从 Agent quiescence + owned-child 集合派生，不维护第二状态机
   • followup() 路由：running 入队 / waiting 唤醒 / 无 Activation 冷恢复（重放持久化事件）
   • 每个 continuation 消息 = 一个 FIFO turn；child-first 销毁顺序
4. 状态从唯一事实派生是贯穿性设计原则（Activation 不另建状态机）

Web Seam（搜索/抓取）

packages/web/web/src/：

• 单选无回退：resolveProvider() 配置 id 或唯一可用；多可用无配置 → WEB_PROVIDER_AMBIGUOUS；无 fallback/retry（fail-loud 哲学）
• 三角色：Service Definition（ctx.web）/ Service Provider（各搜索后端）/ Consumer（tool-web 的 web_search/web_fetch）
• WebSearchProvider 接口：{ id, available(), search(request, signal) }（极简）
• provider 注册 = 能力注册，工具可见性独立于 backend 可用性（执行时才解析，错误结构化：WEB_PROVIDER_CONFIGURED_MISSING 等）
• 工具卡片呈现链路：result.content → searchMetaFromValue → meta.answer → presentSearchResult card:'web' → client WebBlock（answer 显示在引用列表上方）

插件加载与配置（loader）

vendor/loader/ + packages/boot/app-boot/：

• Profile = 命名组合（web/headless 模板），Bundle = 分发格式；层级：bundle 序 → profile 的 cordis.patch.yml → home 级 → --patch overlay
• ctx.baseUrl = profile 目录（pathToFileURL(dirname(configPath)).href + '/'）
• loader import(name, baseUrl)：支持 cordis: 内建 / 相对路径（. 开头按 baseUrl）/ 裸包名——本地插件无需 pnpm，patch 写相对路径即可
• patch 语义：按 id 替换整行 config；插入新行用 - insert: 数组（直接写 id 会 entry not found）
• dsh --profile web --dump-config 查看实际启动的插件树

与 Hermes 对照（推断，dsh 侧以源码为准）

反差点：dsh 把"persona"做成可插拔能力；Hermes 把身份系统作为第一公民——两种身份架构哲学。

Common Pitfalls

1. 文档与源码有出入时以源码为准：文档描述设计意图，源码是最终事实（如 subagent 的 Activation 状态派生在 continuation.ts 实现）。
2. npm 安装版无法注册自定义 UI 节点：ConversationNodeDefinition 需 client 插件编译进 Web bundle（cookbook 明示），运行时插件只能影响后端行为。
3. 改 bundle/源码会被升级覆盖：优先 profile patch 层 + 本地插件（相对路径加载），不要改 packages/bundle/ 或 node_modules。
4. dsh 迭代快：架构文档标注的机制可能随版本变化，重大决策前核对 --dump-config 实际树。

Verification Checklist

• 能画出 Cordis 五件套职责与 Fiber 生命周期状态机
• 能解释 "Model-visible means logged" 不变式的含义与后果
• 能说明 subagent seam 与 web seam 的三角色结构与 fail-loud 哲学
• 能写出插件安装的三种 name 形式（cordis: / 相对路径 / 裸包名）及适用场景
• 需要最新行为时用 dsh --profile web --dump-config 核对实际插件树