DeepSeek Harness 能力 Seams 全景：可替换能力清单与三角色

本文是 dsh 官方参考「能力 Seams 与核心服务」的导读：先讲清 seam 的三角色，再解释 seam / core / bundle 三种分类，最后给出一份按子系统组织的完整 ctx.* 服务清单与「我要做 X 该动哪里」对照表。

〇、先记住一个定义：seam 与它的三个角色

上一篇《架构入门》里我们说过，连「模型」本身都不是硬编码的，而是一个 seam（可替换能力）。这一篇把 seam 这个概念讲透。

一个 seam 由三个角色构成：

两条容易踩的坑：

• 一个包可以合并承担多个角色
  
  ——例如 llm 包既是接口声明方，又注册着适配器；
• 单一角色本身不是 seam
  
  ——只有「接口 + 实现 + 消费方」三者齐备，才算一条可替换能力。

这解释了为什么 seam 是「替换一个提供方，就能改变整个产品」的原因：消费方只面向接口编程，永远看不到提供方的实现细节。

一、三种角色：seam / core / bundle

在官方清单里，每个 ctx.* 服务都被标注了角色。角色一共三类：

三个概念里，bundle 最少见：整个 dsh 只有 ctx.agentLoop 一个 bundle——它是「唯一的具体循环插件」，扩展包都依赖 dsh-agent 的事件与服务，而非直接依赖 agent-loop 这个包。

官方特别注明「维护模式：混合模式」：服务从 Cordis 声明中发现；接口、实现和消费方角色由 scripts/gen-doc-graphs.ts 自动分类，并设有完整性守卫。也就是说，下面这张清单不是手写维护的，而是从代码里生成出来的——它本身就是一份活文档。

二、最强例证：共享执行世界

理解 seam 威力的最好入口，是「执行世界」这一组服务：

• ctx.fs
  
  （文件系统）与 ctx.subprocess（子进程）的提供方共享同一个执行世界；
• 把它们指向远程沙箱，也就把 Bash、PTY 和 LSP 一并搬了过去，无需为每个能力单独写 fork；
• ctx.e2b
  
   持有共享的 E2B SDK 句柄、远程工作目录与最终沙箱处置，让 fs-e2b 与 subprocess-e2b 两个提供方落在同一个 Linux 运行时里。

再看 ctx.sandbox 与 ctx.sandboxPolicy 的分工：

• ctx.sandbox
  
  ：消费方交出即将执行 spawn 的确切 argv；与宿主共享文件系统和内核的后端，按每次调用的策略包装这个 argv，并报告强制执行情况。
• ctx.sandboxPolicy
  
  ：统一保存部署默认模式和工作区根目录；只有沙箱执行器和提供方读取它——因此 bash 与 fs 不会限制到不同的根目录。

这组设计体现了一个贯穿全库的原则：能力做「是什么」，策略做「允许什么」，两者彻底解耦。

三、完整清单：按子系统速查

以下按官方侧边栏的子系统分组，列出全部 ctx.* 服务。seam 标注 ★，bundle 标注 ◆，其余为 core。

3.1 内核与作用域

3.2 会话与持久化

3.3 模型与上下文

3.4 执行与工具

3.5 策略与交互

3.6 子代理

3.7 存储、平台与接入

四、「我要做 X」对照表（seam 视角）

五、总结

最后把本文要点压成四句话：

1. seam = 三角色
   
   ：Service Definition、Service Provider、Consumer 三者齐备，才是一条可替换能力。
2. 三种分类
   
   ：seam（多实现）、core（单实现主干）、bundle（唯一组合点，全库只有 ctx.agentLoop）。
3. 共享执行世界
   
   ：ctx.fs 与 ctx.subprocess 指向同一世界，搬一次就把 Bash、PTY、LSP 全部带走。
4. 清单是活文档
   
   ：接口、实现、消费方角色由代码生成并设完整性守卫，查它比猜它可靠。

掌握了这四点，再配合文中的两张速查表，你就能在 dsh 里精准定位任何一个可替换能力的位置——这正是「一切皆插件」从口号变成工程现实的关键。