DSH plugin 作用域注册:ScopeKey、注册上下文与注册表层到底如何决定可见性
同一段注册代码,在两个 scope 下解析出不同结果,这是设计如此,不是 bug。 DSH plugin 的 scope 包用一套很小的词汇,把“按 agent 可见”和“共享生命周期所有权”放进同一个注册上下文。问题通常出在你以为自己在 A 层注册,实际注册到了 B 层。 DSH插件 与 DeepSeek插件 作者最容易踩的坑,就是把这里的 scope 和设置、Slot 里的同名概念混为一谈。
为什么 scope 是库,不是服务
scope 包只提供身份、载体与作用域层词汇,不承载运行时状态,所以它被刻意做成库原语。(来源) 这个定位带来两个直接后果:
- 它没有对应的
ctx.scope服务,你无法从上下文上直接取一个“作用域管理器”; - 生命周期设计理由由 agent-scope 运行时设计 reference 规定,可调用 API 与过滤语义由包 README 规定。
源码分两处:packages/core/scope/src/index.ts 放身份与上下文原语,packages/core/scope/src/store.ts 放注册表层。看代码时先分清这两块,不然很容易把“创建一个 scope”和“往层里注册条目”混成一件事。
ScopeKey 与 Scoped:身份和载体要分开
ScopeKey 负责“是谁”,Scoped<T> 负责“发给谁”,两者都不携带业务数据。(来源)
ScopeKey 是一个不透明的对象身份标识,按身份比较。已交付的 agent loop 直接拿活跃的 Agent 对象当 key,但原语从不检视这个对象——它不读 id,也不读 status,只认引用。
/** An opaque, identity-compared scope key. */
type ScopeKey = object
Scoped<T> 是编译期品牌标记,标注在 scopeTarget(base, key) 返回的不透明路由接收器上。作用域过滤的事件声明要求以此载体作为 this 类型,而真正的事件主体仍作为显式参数传入。
type Scoped<T extends object> = object & { readonly [ScopedBrand]: T }
这段类型定义最容易误读。载体不暴露主体的任何属性,它只记录主体类型供分发检查;载荷里另有真正的 subject。你如果试着在 Scoped<T> 上读字段,类型系统会挡住你,这是故意的。
Scope 的三个面:ctx、rawDispose、dispose
一个 Scope 同时给出“往哪注册”“怎么嵌进复合 effect”“怎么等它彻底停稳”三个答案。(来源)
interface Scope {
ctx: Context
rawDispose: () => Promise<void> | void
dispose(): Promise<void>
}
三者的分工很清楚:
ctx是作用域自有的注册上下文,凡经它注册的内容都归这个 scope 所有;rawDispose保留 Cordis disposer 的确切身份,供你把该作用域按顺序嵌进复合 effect;dispose()是面向直接调用方与竞态调用方的公共完全停稳边界,竞态调用会等同一个完成。
这就是为什么拆 scope 时不能图省事只拿 dispose() 去拼数组:复合 effect 需要的是确切身份,不是“一个会停的东西”。而并发场景下想确认“真的都停了”,该等的是 dispose()。
ScopeLayer 与 ScopedLayers:全局层与惰性作用域层
注册表按“层”聚合,全局层立即可用,作用域层则在第一次注册时才出现。(来源)
ScopeLayer 表示一个注册表在全局或确切作用域层级的完整贡献。一个具体 layer 可以聚合多个具名与匿名 table;判断它是否有内容,只看一个方法:
interface ScopeLayer {
isEmpty(): boolean
}
ScopedLayers<L> 拥有立即创建的全局 layer,以及惰性创建的确切作用域 layer。三条容易踩空的规则:
- 读取不创建 layer —
peek(undefined)表示不存在作用域覆盖层,而不是“有一个空层”。 - 合并有固定顺序 —
merge()会依次物化按插入顺序排列的全局具名条目,再叠加带作用域的遮蔽项。 - 注册走同一个上下文 — 可见性与 Cordis effect 所有权由同一个
ctx表达,在可选通知前取得一个同步撤销函数。
注册函数的返回也值得注意:它返回 Cordis 的原始 disposer,并且只在带作用域 layer 的完整 ScopeLayer 为空时回收它。也就是说,单个 table 清空不会顺手把同层的兄弟 table 一起回收。这条规则直接决定你在插件卸载时的清理顺序是否安全。
NamedEntries 与 AnonymousEntries 的取值差异
具名表按插入顺序查找,匿名表按唯一标识独立存在,选错就会遇到“值相同却被当成同一条”。(来源)
NamedEntries<V> 提供按插入顺序的查找与动态迭代,重复项错误由调用方处理——注册表层不替你做去重决策。AnonymousEntries<V> 则为每次 append 分配唯一标识,因此值相等的条目仍彼此独立。
两者在迭代语义上是一致的:在同一轮非空 table 生命周期内,迭代器可以观察后续变化;但 table 被清空后,现有迭代器不会再观察后续插入。这个边界常被用来判断“插件卸载后还有没有人往里塞东西”。
两者也都返回幂等、精确对应相应条目的撤销函数。它们共享的实现接口 EntryValues 不对外公开,所以不要试图从类型上绕过条目身份去改值。
三处 scope 不是同一个 scope
同名不同义是这套体系里最常见的理解偏差,先确认你读的是哪一处。(来源)
- 本文这一处是
packages/core/scope的注册表层,按ScopeKey决定可见性与生命周期所有权; - 用户设置里的 scope 是 SettingsNamespace 的命名空间概念,解决配置项归属;
- 客户端 Slot 的 scope 解决组件注入的可见范围。
三者在代码里都叫 scope,但一个管注册条目,一个管配置键,一个管 UI 注入。排查“注册了却看不到”时,先问一句:这是注册表层的遮蔽,还是配置没读到,还是 slot 的 scope 不匹配。分清楚再动手,比改代码快得多。相关边界可以对照插件配置与客户端 Slot。
验证:同名服务放进两个 scope
验证可见性不要靠猜,构造两个 scope 各注册一次,然后依次读合并结果。(来源) 五步:
- 用两个不同对象作
ScopeKey,分别创建Scope,确认ctx各自独立。 - 在全局 layer 注册一个具名服务,断言
peek(undefined)在注册前后都反映真实状态。 - 只在 scope A 注册同名服务,调用
merge(),断言 A 看到遮蔽项、scope B 仍看到全局项。 - 清空 scope A 的同名 table,断言该层
isEmpty()为假时兄弟 table 仍可读。 - 调
dispose(),断言 A 的条目全部消失、全局项不受影响;竞态再调一次,确认等待同一次完成。
如果第 3 步结果反了,八成是把全局项与遮蔽项的合并顺序记错了:先全局具名,后带作用域遮蔽。这个顺序不是实现细节,而是可依赖的契约。
一句话收束: 身份用 ScopeKey,载体用 Scoped,注册走 Scope.ctx,读合并看 merge() 的顺序,拆干净只认 dispose()。
常见问题
因为它只提供身份、载体与作用域层的词汇,不承载运行时状态。DSH plugin 把 scope 定位成库原语,生命周期设计由 agent-scope 运行时负责,可调用 API 与过滤语义由包 README 规定。
代表当前没有作用域覆盖层,读取本身不会创建它。DSH plugin 的 ScopedLayers 只在注册时惰性创建确切作用域 layer,读取一律不物化新层,所以 peek 看到的是真实状态而不是占位。
不会,DSH plugin 只在带作用域 layer 的完整 ScopeLayer 为空时才回收它。DSH plugin 用 isEmpty() 判断整个 layer,因此单个 table 空了不会连累同一层里的其他 table。
不会,DSH plugin 为每次 append 分配唯一标识,值相等的条目仍然彼此独立。DSH plugin 的 NamedEntries 才按插入顺序查找,重复项错误交给调用方处理。
相关术语
- ScopeKey
- ScopeKey 是 DSH plugin 中的不透明对象身份标识,按身份比较,原语从不检视该对象本身。— packages/core/scope/src/index.ts
- Scoped<T>
- Scoped<T> 是编译期品牌标记,标注在 scopeTarget(base, key) 返回的不透明路由接收器上,只用于分发检查,不暴露主体属性。— packages/core/scope/src/index.ts
- rawDispose
- rawDispose 是 Scope 上保留的 Cordis disposer 确切身份,用于把该作用域嵌进有序复合 effect。— packages/core/scope/src/index.ts
- ScopedLayers<L>
- ScopedLayers<L> 拥有立即创建的全局 layer 与惰性创建的确切作用域 layer,merge 时先全局具名条目、后带作用域遮蔽项。— packages/core/scope/src/store.ts
来源
- DeepSeek Harness 官方参考 - 作用域注册· deepseek-ai
- packages/core/scope/src/store.ts· deepseek-ai