README.zh.md 6.2 KB
description: "面向插件作者与维护者的作用域注册库，用于构建按 agent 或按分组隔离贡献的注册表或事件表面。"
kind: "package-library"
@deepseek-ai/dsh-scope
English | 中文
概述
dsh-scope 让插件作者能够为每个 agent 或分组提供隔离的贡献集合与统一生命周期。子作用域继承祖先贡献，且较近的定义优先；祖先作用域可以观察后代活动，这两种关系均不反向成立。释放作用域会移除它拥有的一切。按 agent 或分组隔离必须脱离 agent loop 与 preset 工作时，请使用这个零依赖库。
目录
使用本包
插件作者使用 dsh-scope 为单个 agent（或单个分组）提供独立的注册世界。core 分组中的注册表都构建在它之上——通过 agent.ctx 注册的工具只对该 agent 可见——同样的原语也服务于任何自定义注册表或带作用域的事件。
创建作用域
createScope(ctx, key) 在 ctx 的 fiber 下创建作用域：其 ctx 携带作用域标签，通过它进行的每项注册既具备作用域可见性，也服从作用域生命周期。dispose() 撤销通过该作用域进行的每项注册；rawDispose 是确切 Cordis disposer，用于把 teardown 嵌套进有序组合 effect。
const scope = createScope(ctx, agent)
scope.ctx.on('agent/status', ({ agent, status }) => track(agent, status))
// later:
await scope.dispose() // unwinds every registration made through scope.ctx
路由带作用域的事件
scopeTarget(base, key) 构造带作用域事件分发所用的不透明载体。无标签监听器保持全局；标签为 key 的监听器接收该键及其后代的事件。载体只携带路由状态——真实主体由事件参数携带。
构建带作用域的注册表层
注册表作者使用 ScopedLayers、NamedEntries 与 AnonymousEntries 持有一个立即构造的全局层加惰性创建的精确作用域层：读取从不创建层，merge() 沿作用域链物化按插入序的具名遮蔽，effect() 从同一上下文推导可见性与所有权。只有当整个聚合为空时才回收作用域层。
理解实现
实现细节——点击展开
本节解释该包如何实现上述行为；可观察约定已在[使用本包](#use-this-package)中完整说明。 ### 设计理念 注册上下文同时决定可见性与所有权：通过带作用域上下文进行的注册在该作用域内可见、并随其 dispose，从而防止贡献在一个作用域中可见、却随另一个作用域拆除。该原语用于路由受信任的同进程插件；它不是沙箱或权限边界。交出带作用域的上下文，也会交出创建该上下文的插件的服务解析范围（解析沿创建者 fiber 的依赖链行进），因此作用域应由具备这些带作用域注册所需依赖的插件来创建。 ### 源码地图 | 文件 | 职责 | |---|---| | [`src/index.ts`](src/index.ts) | `createScope`、`scopeOf`、`scopeTarget`、`bindScopeParent`/`scopeParentOf`/`scopeChainOf`、载体标记 | | [`src/store.ts`](src/store.ts) | `ScopedLayers`、`NamedEntries`、`AnonymousEntries`、`ScopeLayer` | | [`src/invariant.ts`](src/invariant.ts) | 基于生成的作用域事件映射的不变式配套 | | [`src/scoped-events.generated.ts`](src/scoped-events.generated.ts) | 已声明带作用域事件的生成解析器映射 | ### 父链 一个关系支撑两个方向：注册视图沿链**向下**继承（子作用域看得见祖先的各层），事件放行沿链**向上**扩展（标签为祖先的监听器收到分发到后代键的事件）。绑定仅此一次——已有父级的键直接抛错，只有返回的绑定句柄才能重新绑定——且每次链接都拒绝闭环。`scopeChainOf` 返回 `[key, parent, …]`，最近者在前。 ### 事件筛选 `scopeTarget` 把基对象的现有 `Context.filter` 与作用域谓词组合起来：无标签监听器放行；有标签监听器仅当标签为分发键或其祖先时放行；`key === undefined` 只放行无标签监听器。带 `{ global: true }` 的监听器绕过筛选。`Scoped` brand 要求带作用域事件以载体作为 `this` 类型，因此用裸主体分发会产生编译错误。进一步探索
包级约定对大多数消费方已经足够；需要周边领域与设计原理时再阅读以下页面。
- 作用域注册子系统——身份、载体与层类型。
- agent 作用域上下文 Agent Note——安全非目标与上下文设计。
- agent 作用域 runtime 设计 Agent Note——循环如何构建按 agent 的作用域。
- core 分组地图——core 各包如何组合。
已知限制与延期工作
这些限制说明该原语何时需要特别留意。它们是当前包约束，不是任务积压。
- 只有感知作用域的表层才会隔离状态：注册表必须按
scopeOf()归档，事件必须通过scopeTarget()分发；仅仅通过带作用域的上下文调用任意 Cordis 服务，并不会改变该服务仍为上下文全局这一事实。 - 一个上下文只携带一个最近的作用域键：层级关系存在于键级父关系中而非上下文标签里；嵌套作用域上下文仍遮蔽为单一标签，多成员策略集仍不受支持。
- 服务可达性来自作用域创建者：交出
Scope.ctx也会交出创建插件注入的服务范围，因此，若作用域创建者提供的服务范围较宽，持有者之后也无法将其收窄。