DSH plugin 能力挂到哪个扩展点？DeepSeek Harness 主干、Seam 与组合边界

DSH plugin 的能力不会随便挂：官方把带服务声明的包分成核心主干服务（core）、可替换能力 Seam（seam）与组合包 / 组合点（bundle）三类，每一类对应一种扩展点和一套约束（来源）。 本文讲清这三类边界、单一实现约束的实际含义，以及新增能力时该挂到哪个扩展点；三角色（Definition / Provider / Consumer）本身已写在站内 DSH plugin 开发指南 里，这里不重复。

DSH plugin 的核心服务、Seam 与组合：三类扩展点的边界

官方按服务声明把包分成三类，其中 core 是流水线主干，seam 是可替换能力，bundle 是产品形态的组合层（来源）。 对照如下：

1. 主干是 agent loop 本身 — 官方把 agent-loop 标为「唯一的具体 loop 插件」，并明确扩展包应依赖 dsh-agent 的事件与服务，而不是依赖这个包。预期：改流程走事件，不动主干实现。
2. Seam 是能力边界 — 文件系统、Shell、LLM、工作流引擎等都以 Seam 暴露，Provider 可换。预期：换实现不改 Consumer。
3. 组合层负责选型 — profile 与 bundle 在装配时决定装载哪个 Provider。预期：产品差异体现在组合，而不是散落在代码分支里。

判据是「你要换的是什么」：换某个能力的实现，接入对应 Seam；扩展流水线环节，走事件而不是替换主干服务，事件写法见 DSH plugin 事件系统。

DSH plugin 的单一实现约束：一个 ctx key 只有一个活动实现

单一实现约束是 Cordis 的服务注册语义：同一个 context 内一个 ctx.<key> 只对应一个活动服务实例（来源）。 Service 子类在构造时以 super(ctx, name) 注册，注册立即生效，并随所属 fiber 卸载自动移除。三个直接推论：

1. Seam 的「可替换」是替换而不是并存 — 同一时刻只有当前装载的那个 Provider 在位，换实现改的是「装载谁」。预期：不要把两个 Provider 同时挂到同一个 key。
2. core 服务没有并列实现 — 官方表中 core 一类的 Implementations 列为空，它们是单一 owner。预期：要扩展主干能力就加事件或新服务，而不是新造一个同名实现。
3. 不兼容的 Host 与 Client 声明不能复用同一个 Context key — 即使二者使用独立运行时 context，TypeScript 声明合并仍会同时看到两种类型。预期：命名冲突在类型层面被避免。

由此得到插件作者的两条纪律：订阅与注册都放在 apply 内，随 fiber 卸载自动回滚；需要替代行为时不要并行挂载第二个实现，而应通过组合层去换 Provider。

DSH plugin 扩展点选型：新增能力该挂到哪个 Seam

新增能力时按「要换什么」选扩展点，优先接入既有 Seam 而不是新造平行体系。 判断步骤：

1. 换某个能力的实现 — 接入既有 Seam，例如 ctx.llm（模型能力，做法见 LLM 适配器开发）、ctx.fs 与 ctx.shell（文件与命令）、ctx.workflowEngine（工作流脚本引擎）、ctx.codeRuntime（代码执行）、ctx.sessionPersistence（会话持久化）。预期：上层工具零改动。
2. 扩展流水线流程本身 — 走事件，不替换主干服务。预期：扩展点可逆、可卸载。
3. 做产品形态装配 — 用组合包与 bundle point 在配置层选定 Provider。预期：换实现只改组合。
4. 都不属于以上三类 — 作为独立的内聚领域服务实现，例如按领域划分的 registry。预期：不与主干或 Seam 混淆。

选好扩展点后，写法与命名仍要守住约定：接口包用能力名，实现包加机制 / 协议 / 环境 / 厂商限定词；engine、runtime、policy 等单一服务用单数 ctx key，registry 与多成员服务用复数。写完自检三项：能力挂的是核心、Seam 还是组合，判断是否成立；是否存在两个实现抢同一个 key 的情况；是否接入了既有 Seam 而没有新造平行体系。想回顾底层框架，读 Cordis 三件套入门；想按同一 Seam 对照社区 DSH插件 实现，可在 DSH Plugin Hub 检索；包结构问题见 新增 workspace 包。