官方文档常出现 Service Definition、Service Provider、Consumer 三个词，它们合在一起构成一项能力的 seam（可替换的能力接口）。
三种角色各是什么
当一项能力足够通用、需要支持可替换的提供方时（例如 Bash 执行），harness 会把能力拆成三种角色：
| 角色 | 负责什么 | 以 Bash 为例 |
|---|---|---|
| Service Definition 接口 + 类型 | 定义 Cordis 服务，以及请求 Request 和结果 Result 的类型 | dsh-shell（注册为 ctx.shell） |
| Service Provider 实现 | 真正实现该能力，通常针对一种运行环境 | dsh-bash-local（本地执行） |
| Consumer 面向模型的工具 | 把能力公开为模型可调用的工具 | dsh-tool-bash（bash 工具） |
三个角色可以放在同一个包里，也可以拆进不同包。判断标准只有一个：这些角色是否需要独立演进或替换。
三角色关系
三个角色都依赖 Definition，而 Provider 与 Consumer 互不依赖。Definition 在中间，Provider 继承实现 Definition，Consumer 通过 inject: ['shell'] 依赖它。因此换 Provider 时，Definition 和 Consumer 一行都不用改。
以 Bash 为例：ctx.shell 的三角色
- Service Definition 是
dsh-shell包，注册为ctx.shell服务，定义请求类型ShellExecRequest和结果类型ShellRunResult。 - Service Provider 是
dsh-bash-local，在本地计算机上执行命令。同一份 Definition 还有其它 Provider：dsh-bash-sandbox（沙箱执行）、dsh-pwsh-local（PowerShell）。 - Consumer 是
dsh-tool-bash，把能力包装成模型可调用的 bash 工具。tool-bash通过inject声明依赖ctx.shell，再在execute里调用ctx.shell.run(...)。
| ctx 键 | 角色 | Definition | Provider | Consumer |
|---|---|---|---|---|
| ctx.shell | seam | shell | bash-local / bash-sandbox / pwsh-local | tool-bash / tool-pwsh / hooks-claude-code / hooks-codex |
消费方还包括 hooks-claude-code 与 hooks-codex 两个钩子桥接插件，它们和 tool-bash 一样只认 ctx.shell 接口，不关心背后是哪个执行器。
在 Bash seam 里，面向模型的请求
ShellExecRequest（workdir、timeoutMs 可选）与执行器实际使用的完全解析后的规格ShellExecSpec（字段必填）被分开。工具层在二者之间调用ctx.shell.resolve(request)，这就是「包边界处显式优于隐式」。
为什么要拆成三个角色
好处一：提供方可替换。同一个 Service Definition 可以有多个提供方，通过 cordis.yml 选择：
1# 文件路径：cordis.yml
2# 本地执行
3- name: '@deepseek-ai/dsh-bash-local'
4
5# 想换提供方时，替换上面这一行即可
6# - name: '@deepseek-ai/dsh-bash-sandbox'
好处二：三个角色可以独立演进：
| 角色 | 独立演进的自由度 |
|---|---|
| Service Definition | 一旦调用方开始依赖它的约定，就很少改动 |
| Service Provider | 可以独立优化性能和安全性 |
| Consumer | 可以调整能力向模型呈现的方式 |
好处三：依赖解耦：
| 依赖关系 | 是否成立 |
|---|---|
| Provider → Definition | 是 |
| Consumer → Definition | 是 |
| Provider → Consumer | 否 |
| Consumer → Provider | 否 |
动手梳理已有 seam
按三步梳理任意熟悉的 seam（如 ctx.fs 或 ctx.llm）：①找出 Definition 包；②找出 Provider 包；③找出 Consumer。
- ctx.llm：Definition 是
llm包，实现是llm-deepseek与llm-pi-ai，直接消费方是agent-loop与compaction-basic。 - ctx.fs：Definition 是
fs包，实现是fs-local、fs-sandbox与fs-e2b，直接消费方是tool-fs。
要点
- Bash 能力：Definition=
dsh-shell，Provider=dsh-bash-local，Consumer=dsh-tool-bash。 - 更换 Bash Provider 时，Definition 与 Consumer 包保持不变。
- 单一角色只是接口/实现/工具之一，三者合起来才是完整的 seam。