DeepSeek Harness Registry 与 Service 都能查找:什么时候该用哪一个
Registry 和 Service 都能「按名字找东西」,所以经常被混用。 但它们的重心不同:Registry 管的是一个 key 下的集合,Service 给的是一项能力。选错不会立刻报错,却会在「多实现」「枚举」「替换后端」这些场景里暴露(来源)。
DeepSeek Harness 两个原语:Registry 存集合,Service 给能力
一句话区分:Registry 回答「有哪些」,Service 回答「用哪个」。 Registry 关注条目集合,适合注册多个同 key 的实现、按作用域枚举、按条件过滤;Service 关注单一能力,消费方注入一个名字,拿到一个可用的实现。(来源)
这个区别决定了两者的形状:
- Registry — 注册项是数据,查找返回集合;同一个 key 可以有多条,顺序与作用域有意义;
- Service — 注册项是能力,查找返回一个实现;同一个名字通常只有一个生效提供方。
如果把 Service 当 Registry 用,想注册多个实现,就会遇到「后注册覆盖前一个」或「消费方只拿到一个」的问题;如果把 Registry 当 Service 用,消费方每次都要从集合里选,增加了不必要的复杂度。
判断方法:问一句「消费方需要看到多个,还是只需要一个?」多个用 Registry,一个用 Service。
DeepSeek Harness 查找模型对照
两者的查找模型不同,导致消费方写法不同。 对照如下(来源):
| 维度 | Registry | Service |
|---|---|---|
| 查找结果 | 集合(可能为空) | 单个实现或不可用 |
| 同名多实现 | 支持 | 通常不支持 |
| 枚举 | 支持 | 不需要 |
| 作用域过滤 | 支持 | 受注入作用域影响 |
| 消费方关注点 | 选哪个条目 | 有没有可用能力 |
Registry 的空结果和 Service 的不可用,含义也不同:前者是「集合里没有匹配项」,后者是「这项能力没有提供方」。排查时不要把两者混为一谈。
查找模型还影响消费方的降级策略。Registry 空集合可以降级为空操作;Service 不可用通常要拒绝请求或等待提供方加载,因为消费方没有替代实现。
查找时机也要一致:Registry 适合在操作开始时取一次集合快照,Service 适合在注入时拿到稳定句柄。两者都不要在每次调用时重新查找,除非你确实需要感知动态变化。
DeepSeek Harness 生命周期对照
两者的注册都是副作用,但撤销的粒度不同。 在 Cordis 里,注册随插件 fiber 卸载撤销;Registry 撤销的是某一条目,Service 撤销的是整项能力的提供方(来源)。
这意味着:
- Registry 可以逐个增删 — 适合动态发现、按条件注册;
- Service 通常整体替换 — 换后端时先撤旧提供方,再注册新提供方;
- 两者都不要在 apply 外持有注册句柄 — 否则会出现「已卸载但仍可查找」的假象。
Service 的整体替换有一个常见坑:新旧提供方短暂并存时,消费方可能拿到旧实现。正确做法是先撤旧、再注册新,或者在切换期间让消费方等待。
Registry 的逐条增删也有坑:删除顺序不确定时,消费方可能看到中间状态。需要一致快照的消费方,应一次性读取集合,而不是边遍历边期待稳定。
DeepSeek Harness 三个选型例:工具注册、多后端、单例服务
三个例子覆盖大多数选型场景。 对照它们的需求,就能判断该用哪个(来源):
- 工具注册 — 每个工具是一个条目,模型需要看到全部工具,按名称调用。适合 Registry:多条目、可枚举、按名字查找。
- 多后端 — 文件系统、shell、终端可能有多个提供方,消费方按当前选择使用一个。适合 Service:一项能力,一个生效提供方,可替换。
- 单例服务 — 设置、会话、凭据这类全局能力,通常只有一个实现。适合 Service:消费方注入名称,不关心有几个实现。
工具注册这个例子最容易被误用成 Service。把工具做成 Service,会导致「只能有一个工具」或「后注册覆盖前一个」;工具本质上是集合,不是单例能力。
多后端这个例子最容易被误用成 Registry。把后端做成 Registry,消费方每次都要选一个,增加了选择逻辑;如果部署只允许一个后端,Service 更直接。
还有一种组合场景:能力本身是单例,但能力内部维护一个集合。例如一个「工具注册表服务」,Service 提供查找方法,内部用 Registry 存条目。这种组合很常见,判断时看「消费方是否需要枚举」:需要,就在 Service 上暴露枚举方法,而不是让消费方直接依赖 Registry。
DeepSeek Harness 常见误用
三种误用最常见,表现也最典型。 记住它们,能省很多排查时间(来源):
- 用 Service 注册集合 — 后注册覆盖前一个,消费方只看到一个;表现是「工具/插件少了一个」。
- 用 Registry 注册单例 — 消费方要从集合里选,选错或为空;表现是「能力时有时无」。
- 在 apply 外持有注册句柄 — 卸载后仍可查找;表现是「插件已禁用,功能还在」。
三种误用的共同点是「把集合与能力混为一谈」。选型时先回答「消费方需要几个」,再决定原语。
还有一种隐蔽误用:用 Registry 存有状态的对象,并在外面修改它。Registry 管的是注册与查找,不负责对象状态;状态应由提供方自己管理,并通过 Service 暴露方法。
DeepSeek Harness 验证:从消费方看是否可替换
验证选型是否正确,不要看注册代码,要看消费方能否替换与降级。 三步(来源):
- 替换测试 — 换一个提供方,消费方是否需要改代码?Service 应该不需要,Registry 通常需要重新选择。
- 枚举测试 — 消费方是否需要列出全部条目?需要,选 Registry;不需要,选 Service。
- 卸载测试 — 卸载提供方后,消费方是否得到明确的不可用或空集合?如果还能拿到旧对象,说明注册句柄泄漏。
三步都过,选型基本正确。只过注册、不过消费方,很容易出现「代码能跑,但换一个部署就坏」。
旧文 develop-scope-registry 讲 scope 与可见性,develop-plugin-service-definition 讲服务拆分;本篇补的是 Registry 与 Service 的选型对照。先分清集合与能力,再谈注册细节。
选型没有绝对对错,只有「消费方是否需要多个」这个判据。判据清楚,代码就不会在两种原语之间反复摇摆。
先定消费方,再定原语,顺序不要反。
常见问题
DeepSeek Harness 的 Registry 管理按 key 组织的集合,适合多实现与枚举;Service 提供一项命名能力,适合单例或可替换的后端。前者重集合,后者重能力。
DeepSeek Harness 里,应该用 Registry。DeepSeek Harness 的 Registry 支持同名多条目与枚举;Service 更适合一个能力一个实现,多个实现应通过 Service 的提供方选择而不是同名覆盖。
DeepSeek Harness 的服务注册是插件副作用,随 fiber 卸载撤销;不要在 apply 之外手工保留注册句柄,否则会出现服务已卸载但仍可查找的假象。
DeepSeek Harness 的 Registry 按 key 与 scope 过滤,空数组通常表示没有匹配条目、作用域不对或提供方尚未加载,不一定代表注册失败。
相关术语
- Registry
- Registry 是 Cordis 中按 key 管理多条注册项的原语,适合需要枚举、同名多实现或按作用域过滤的场景。— DeepSeek Harness 官方文档 - Plugin Registry
- Service
- Service 是 Cordis 中向共享上下文提供一项命名能力的原语,消费方按名称注入,提供方可以替换。— DeepSeek Harness 官方文档 - Service
- 作用域
- 作用域是 Cordis 中限定注册可见性的范围,Registry 与 Service 的查找都可能受作用域影响。— DeepSeek Harness 官方文档 - Plugin Registry
- 消费方
- 消费方是使用某项能力的插件或代码;从消费方视角看,Service 是否可替换比注册方式更重要。— DeepSeek Harness 官方文档 - Service
来源
- DeepSeek Harness 官方文档 - Plugin Registry· deepseek-harness
- DeepSeek Harness 官方文档 - Service· deepseek-harness