DeepSeek Harness 能力 Seams 全景：可替换能力清单与三角色
本文是 dsh 官方参考「能力 Seams 与核心服务」的导读：先讲清 seam 的三角色，再解释 seam / core / bundle 三种分类，最后给出一份按子系统组织的完整 ctx.* 服务清单与「我要做 X 该动哪里」对照表。
〇、先记住一个定义：seam 与它的三个角色
上一篇《架构入门》里我们说过，连「模型」本身都不是硬编码的，而是一个 seam（可替换能力）。这一篇把 seam 这个概念讲透。
一个 seam 由三个角色构成：
| |
|---|
| Service Definition（服务定义） | |
| Service Provider（服务提供方） | |
| Consumer（消费方） | |
两条容易踩的坑：
- 一个包可以合并承担多个角色——例如
llm 包既是接口声明方，又注册着适配器； - 单一角色本身不是 seam——只有「接口 + 实现 + 消费方」三者齐备，才算一条可替换能力。
这解释了为什么 seam 是「替换一个提供方，就能改变整个产品」的原因：消费方只面向接口编程，永远看不到提供方的实现细节。
一、三种角色：seam / core / bundle
在官方清单里，每个 ctx.* 服务都被标注了角色。角色一共三类：
| | | |
|---|
| seam | | | ctx.llm（llm-deepseek / llm-replay）、ctx.fs、ctx.shell |
| core | | | ctx.sessions、ctx.tools、ctx.systemPrompt |
| bundle | | 唯一的具体实现，其他包依赖它的事件与服务，而不依赖它本身 | ctx.agentLoop |
三个概念里，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 内核与作用域
| | | |
|---|
ctx.invariants | | | 配套子路径注册所属包本地的检查；负责选择、唯一性、子 fiber 与失败归属 |
ctx.typert | | | 插件直接或经 dsh-typert-loader 注册实时 zod 贡献 |
ctx.typertGateway | | | 把生成的 Remote 描述符与实时 Cordis 服务关联，提供一元调用 |
3.2 会话与持久化
| | | |
|---|
ctx.sessions | | | 仅追加的 Session 实例，发出持久会话事件流 |
ctx.sessionPersistence | | | 各后端持久化同一套 SessionEvent 词汇；组合时选择后端 |
ctx.sessionQuery | | | 精确读取、过滤与追踪；后端提供全文、排序、摘要与游标 |
ctx.sessionReferenceResolver | | | |
ctx.sessionTitle | | first-prompt-llm / all-prompts-llm | 确定性回退 + 最新标题折叠区 + 唯一可选异步提供方 |
ctx.sessionProjections | | | |
ctx.sessionProjectionCache | | | 按会话持久保存投影单元状态，冷读取阶梯无需加载完整日志 |
ctx.spillStore | | | 保存过大工具文本，返回面向模型的定位信息与取回提示 |
3.3 模型与上下文
| | | |
|---|
ctx.llm | | llm-deepseek / llm-pi-ai / llm-replay | 适配器注册提供方实现；agent loop 与压缩调用提供方无关的流服务 |
ctx.tokenMeter | | | 按会话隔离的回放折叠区；压力消费方共享不可变测量结果 |
ctx.toolResultPruner | | compaction-tool-result-pruner | |
ctx.systemPrompt | | | 为每个步骤收集提示词各部分与面向模型的工具 schema |
ctx.compaction | | | |
3.4 执行与工具
| | | |
|---|
ctx.tools | | | 注册能力、负责 Code Mode 传输与带把关的执行流水线 |
ctx.subprocess | | subprocess-local / subprocess-e2b | 进程坐标、进程树/会话生命周期、stdio 处置、kill 升级 |
ctx.shell | | bash-local / bash-sandbox / pwsh-local | 面向模型的 shell 工具与钩子桥接消费此 seam |
ctx.shellEnv | | | 声明限定于 effect 作用域的 DSH_* 事实 |
ctx.terminals | | | |
ctx.sandbox | | | 按每次调用的策略包装 spawn 的 argv 并报告强制执行 |
ctx.sandboxPolicy | | | |
ctx.codeRuntime | | | |
ctx.fs | | fs-local / fs-sandbox / fs-e2b | |
ctx.lsp | | | 提供方注册与选择 + 恰好四种操作的标准化查询执行 |
ctx.web | | web-search-* / web-fetch-http | |
ctx.workflowEngine | | | 每个上下文一个引擎；agent() 调用经 ctx.subagents 扇出 |
3.5 策略与交互
| | | |
|---|
ctx.approval | | | 一次性权限决策经 approval/request waterfall 分派 |
ctx.permissionPresets | | | 预设表 workspace-write / danger-full-access |
ctx.userQuestions | | | |
ctx.planMode | | | |
ctx.commands | | | |
ctx.goals | | | |
ctx.directoryPicker | | | |
3.6 子代理
| | | |
|---|
ctx.subagents | | spawn/fork-in-process、acp、codex、claude-code、dsh-sdk | 提供方实现传输；负责基于 Activation 的延续编排 |
ctx.agents | | | 实时 Agent 句柄、创建/恢复工厂 seam、发起方传播 |
ctx.agentDefaultModel | | | 经 settings 分层默认 ModelSelection |
ctx.agentPresets | | | 发现 preset 目录，在创建期挂载 preset cordis.yml 到 agent 作用域 |
ctx.agentLoop | | | |
ctx.jobs | | | 登记正在运行的工作；tool-jobs 负责读取/列出/终止 |
ctx.skills | | skill-badge / skill-filesystem | |
3.7 存储、平台与接入
| | | |
|---|
ctx.storage | | storage-json / storage-sqlite | 各后端并列注册；类型化操作转为不透明 KV 单元原语 |
ctx.storageDomain | | | |
ctx.settings | | | |
ctx.credentials | | | |
ctx.workspaceRegistry | | | |
ctx.messageFeedback | | | 本地逐 assistant 消息反馈，不进入会话历史或遥测 |
ctx.attachments | | | |
ctx.sessionTelemetry | | | |
ctx.apiProxy | | | |
ctx.webServer | | | node:http |
ctx.clientModules | | | |
ctx.dynamicCordisRunner | | | 内存定义注册表 + Host 侧 vm 沙箱 + request-run |
ctx.cordisInspect | | | 注册 Host inspect 提供方、镜像 Client manifest |
四、「我要做 X」对照表（seam 视角）
| |
|---|
| |
| 注册 ctx.sessionPersistence 新后端 |
| 替换 ctx.shell / ctx.sandbox / ctx.terminals 提供方 |
| 让 ctx.fs 与 ctx.subprocess 指向同一远程沙箱 |
| 在 ctx.tools 注册；schema 加入提示词组装 |
| 消费 ctx.sandbox；统一策略写 ctx.sandboxPolicy |
| 监听 approval/request waterfall 提供回答方 |
| 在 ctx.jobs 注册；job_* 工具负责收集或停止 |
| |
| 注册唯一的 ctx.sessionTitle 提供方 |
| |
| |
| |
五、总结
最后把本文要点压成四句话：
- seam = 三角色：Service Definition、Service Provider、Consumer 三者齐备，才是一条可替换能力。
- 三种分类：
seam（多实现）、core（单实现主干）、bundle（唯一组合点，全库只有 ctx.agentLoop）。 - 共享执行世界：
ctx.fs 与 ctx.subprocess 指向同一世界，搬一次就把 Bash、PTY、LSP 全部带走。 - 清单是活文档：接口、实现、消费方角色由代码生成并设完整性守卫，查它比猜它可靠。
掌握了这四点，再配合文中的两张速查表，你就能在 dsh 里精准定位任何一个可替换能力的位置——这正是「一切皆插件」从口号变成工程现实的关键。
粤ICP备14082021号
免费POC，
零成本试错
