DeepSeek Harness 能力三角色

三种角色各是什么

官方文档常出现 Service Definition、Service Provider、Consumer 三个词，它们合起来构成一项能力的 seam（可替换的能力接口）。当能力足够通用、需要可替换的提供方时（例如 Bash 执行），Harness 会把它拆成三个角色：

Definition 只声明「有什么能力、长什么样」；Provider 继承抽象类填上行为；Consumer 把能力包装成工具 schema。三个角色可同包也可拆包，判断标准只有一个：是否需要独立演进或替换。完整能力才构成 seam，任何单一角色都不是 seam。

依赖关系

Provider 继承实现 Definition，Consumer 通过 inject: ['shell'] 依赖它，两者彼此无依赖。因此更换 Provider 时，Definition 和 Consumer 一行都不用改。

以 Bash 为例：ctx.shell 的三角色

Definition 包 dsh-shell 定义请求类型 ShellExecRequest 与结果类型 ShellRunResult；Provider 除 dsh-bash-local 外，还有 dsh-bash-sandbox（沙箱执行）、dsh-pwsh-local（PowerShell）；Consumer 除 dsh-tool-bash 外，还包括 hooks-claude-code、hooks-codex 等钩子桥接插件，它们同样只认 ctx.shell 接口、不关心背后是哪个执行器。在 Bash seam 里，面向模型的请求 ShellExecRequest（workdir、timeoutMs 可选）与执行器使用的完全解析规格 ShellExecSpec（字段必填）是分开的，工具层在中间调用 ctx.shell.resolve(request)——这正是「包边界处显式优于隐式」。

为什么要拆成三个角色

第一，提供方可替换：同一 Definition 可有多个 Provider，通过 cordis.yml 选择：

# 文件：cordis.yml
# 本地执行
- name: '@deepseek-ai/dsh-bash-local'

# 想换提供方时，替换上面这一行即可：
# - name: '@deepseek-ai/dsh-bash-sandbox'

第二，独立演进：Definition 一旦有人依赖就很少改动，Provider 可独立优化性能与安全性，Consumer 可调整能力向模型呈现的方式。第三，依赖解耦：Provider 与 Consumer 都只依赖 Definition，彼此无依赖。

动手梳理

官方《能力 Seam 与核心服务》参考文档维护着完整服务清单，按「所属包 → 实现 → 直接消费方」三步即可梳理任意 seam。例如 ctx.llm 的实现是 llm-deepseek 与 llm-pi-ai，消费方是 agent-loop 与 compaction-basic；ctx.fs 的实现是 fs-local、fs-sandbox 与 fs-e2b，消费方是 tool-fs。

小结自测

能力 = Definition（接口与类型）+ Provider（实现）+ Consumer（面向模型的工具），三者合起来才是 seam。自测：Bash 的三角色各对应哪个包？更换 Provider 时哪些包保持不变？