ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 作用域注册:ScopeKey、注册上下文与注册表层到底如何决定可见性

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek Harness作用域注册ScopeLayer可见性
同一个服务在两个 scope 下表现不一致,问题往往不在服务本身。本文从 ScopeKey、Scoped 载体、Scope 拆卸边界讲到 ScopedLayers 的全局层与惰性作用域层,并给出可见性验证方法。

同一段注册代码,在两个 scope 下解析出不同结果,这是设计如此,不是 bug。 DSH plugin 的 scope 包用一套很小的词汇,把“按 agent 可见”和“共享生命周期所有权”放进同一个注册上下文。问题通常出在你以为自己在 A 层注册,实际注册到了 B 层。 DSH插件 与 DeepSeek插件 作者最容易踩的坑,就是把这里的 scope 和设置、Slot 里的同名概念混为一谈。

为什么 scope 是库,不是服务

scope 包只提供身份、载体与作用域层词汇,不承载运行时状态,所以它被刻意做成库原语。(来源) 这个定位带来两个直接后果:

  1. 它没有对应的 ctx.scope 服务,你无法从上下文上直接取一个“作用域管理器”;
  2. 生命周期设计理由由 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,只认引用。

ts
/** An opaque, identity-compared scope key. */
type ScopeKey = object

Scoped<T> 是编译期品牌标记,标注在 scopeTarget(base, key) 返回的不透明路由接收器上。作用域过滤的事件声明要求以此载体作为 this 类型,而真正的事件主体仍作为显式参数传入。

ts
type Scoped<T extends object> = object & { readonly [ScopedBrand]: T }

这段类型定义最容易误读。载体不暴露主体的任何属性,它只记录主体类型供分发检查;载荷里另有真正的 subject。你如果试着在 Scoped<T> 上读字段,类型系统会挡住你,这是故意的。

Scope 的三个面:ctx、rawDispose、dispose

一个 Scope 同时给出“往哪注册”“怎么嵌进复合 effect”“怎么等它彻底停稳”三个答案。(来源)

ts
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;判断它是否有内容,只看一个方法:

ts
interface ScopeLayer {
  isEmpty(): boolean
}

ScopedLayers<L> 拥有立即创建的全局 layer,以及惰性创建的确切作用域 layer。三条容易踩空的规则:

  1. 读取不创建 layer — peek(undefined) 表示不存在作用域覆盖层,而不是“有一个空层”。
  2. 合并有固定顺序 — merge() 会依次物化按插入顺序排列的全局具名条目,再叠加带作用域的遮蔽项。
  3. 注册走同一个上下文 — 可见性与 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 各注册一次,然后依次读合并结果。(来源) 五步:

  1. 用两个不同对象作 ScopeKey,分别创建 Scope,确认 ctx 各自独立。
  2. 在全局 layer 注册一个具名服务,断言 peek(undefined) 在注册前后都反映真实状态。
  3. 只在 scope A 注册同名服务,调用 merge(),断言 A 看到遮蔽项、scope B 仍看到全局项。
  4. 清空 scope A 的同名 table,断言该层 isEmpty() 为假时兄弟 table 仍可读。
  5. 调 dispose(),断言 A 的条目全部消失、全局项不受影响;竞态再调一次,确认等待同一次完成。

如果第 3 步结果反了,八成是把全局项与遮蔽项的合并顺序记错了:先全局具名,后带作用域遮蔽。这个顺序不是实现细节,而是可依赖的契约。

一句话收束: 身份用 ScopeKey,载体用 Scoped,注册走 Scope.ctx,读合并看 merge() 的顺序,拆干净只认 dispose()。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 的 scope 包为什么不是 Cordis 服务?

因为它只提供身份、载体与作用域层的词汇,不承载运行时状态。DSH plugin 把 scope 定位成库原语,生命周期设计由 agent-scope 运行时负责,可调用 API 与过滤语义由包 README 规定。

DSH plugin 里 peek(undefined) 返回空代表什么?

代表当前没有作用域覆盖层,读取本身不会创建它。DSH plugin 的 ScopedLayers 只在注册时惰性创建确切作用域 layer,读取一律不物化新层,所以 peek 看到的是真实状态而不是占位。

DSH plugin 的 layer 为空时会回收兄弟 table 吗?

不会,DSH plugin 只在带作用域 layer 的完整 ScopeLayer 为空时才回收它。DSH plugin 用 isEmpty() 判断整个 layer,因此单个 table 空了不会连累同一层里的其他 table。

DSH plugin 的 AnonymousEntries 会去重相等值吗?

不会,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

来源