Tianyi Cui
a7a5be1703
Run the dsh-archive-agent-notes audit over every active Agent Note on current master, judging each record by whether its rationale still guides work rather than by size or age. - Archive 453 implemented bilingual triplets (417,882 English words): completed UI chrome, narrow adapters, closed bug fixes, implementation walkthroughs whose package READMEs, docs pages, generators, or successor notes now carry the useful behavior, and 51 records fully superseded by a later active note. Keep 201 implemented notes whose ownership rules, negative guarantees, durable or wire semantics, security rules, reintroduction conditions, or still-tempting rejected alternatives remain useful. - Reject 7 proposals whose premise is gone or whose work shipped in amended form under other records; delete 2 rejected notes that no longer prevent a plausible mistake. - Retarget every remaining inbound link to the archived path, and repair active prose that named an archived record as the owner of a live fact: parenthetical citations drop, ownership sentences redirect to the README, docs page, or active note that states the fact, and history citations say so. Chinese files link the English archived path because the pairing gate treats the frozen tree as outside the bilingual corpus. - Seal 1,359 new frozen artifacts; existing seals are unchanged and outbound links from archived notes are neither inspected nor repaired. - Regenerate docs/config-catalog.md after the hook-bridge comment edits shifted two source line numbers.
6.8 KiB
description, kind
| description | kind |
|---|---|
| 面向插件作者与维护者的作用域注册库，用于构建按 agent 或按分组隔离贡献的注册表或事件表面。 | package-library |
@deepseek-ai/dsh-scope
English | 中文
概述
零依赖的 dsh-scope 库让注册拥有按 agent 归属的家。用 createScope(ctx, key) 创建带标签的上下文，通过它进行的每项注册只在一个作用域内可见，并随该作用域 dispose（资源释放）而撤销；用 scopeOf(ctx) 读取上下文的作用域标签；用 scopeTarget(base, key) 把带作用域的事件路由到键相同的监听器，同时让无标签监听器保持全局可见。键可以构成父链：子作用域看得见祖先的各层（近者遮蔽远者），标签为祖先的监听器能收到子孙键的事件——反向永不成立。该机制与键的具体含义无关：agent loop（智能体循环）为每个存活的 agent 创建一个作用域，agent preset 的常驻挂载则是其 agent 们的父作用域，但底层包无需依赖两者即可使用。构建必须按 agent 或按分组隔离贡献的注册表或事件表面时，请选择本包。
目录
使用本包
插件作者使用 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() 从同一上下文推导可见性与所有权。只有当整个聚合为空时才回收作用域层。
理解实现
实现细节——点击展开
本节解释该包如何实现上述行为；可观察约定已在使用本包中完整说明。
设计理念
注册上下文同时决定可见性与所有权：通过带作用域上下文进行的注册在该作用域内可见、并随其 dispose，从而防止贡献在一个作用域中可见、却随另一个作用域拆除。该原语用于路由受信任的同进程插件；它不是沙箱或权限边界。交出带作用域的上下文，也会交出创建该上下文的插件的服务解析范围（解析沿创建者 fiber 的依赖链行进），因此作用域应由具备这些带作用域注册所需依赖的插件来创建。
源码地图
| 文件 | 职责 |
|---|---|
src/index.ts |
createScope、scopeOf、scopeTarget、bindScopeParent/scopeParentOf/scopeChainOf、载体标记 |
src/store.ts |
ScopedLayers、NamedEntries、AnonymousEntries、ScopeLayer |
src/invariant.ts |
基于生成的作用域事件映射的不变式配套 |
src/scoped-events.generated.ts |
已声明带作用域事件的生成解析器映射 |
父链
一个关系支撑两个方向：注册视图沿链向下继承（子作用域看得见祖先的各层），事件放行沿链向上扩展（标签为祖先的监听器收到分发到后代键的事件）。绑定仅此一次——已有父级的键直接抛错，只有返回的绑定句柄才能重新绑定——且每次链接都拒绝闭环。scopeChainOf 返回 [key, parent, …]，最近者在前。
事件筛选
scopeTarget 把基对象的现有 Context.filter 与作用域谓词组合起来：无标签监听器放行；有标签监听器仅当标签为分发键或其祖先时放行；key === undefined 只放行无标签监听器。带 { global: true } 的监听器绕过筛选。Scoped<T> brand 要求带作用域事件以载体作为 this 类型，因此用裸主体分发会产生编译错误。
进一步探索
包级约定对大多数消费方已经足够；需要周边领域与设计原理时再阅读以下页面。
- 作用域注册子系统——身份、载体与层类型。
- agent 作用域上下文 Agent Note——安全非目标与上下文设计。
- agent 作用域 runtime 设计 Agent Note——循环如何构建按 agent 的作用域。
- core 分组地图——core 各包如何组合。
已知限制与延期工作
这些限制说明该原语何时需要特别留意。它们是当前包约束，不是任务积压。
- 只有感知作用域的表层才会隔离状态：注册表必须按
scopeOf()归档，事件必须通过scopeTarget()分发；仅仅通过带作用域的上下文调用任意 Cordis 服务，并不会改变该服务仍为上下文全局这一事实。 - 一个上下文只携带一个最近的作用域键：层级关系存在于键级父关系中而非上下文标签里；嵌套作用域上下文仍遮蔽为单一标签，多成员策略集仍不受支持。
- 服务可达性来自作用域创建者：交出
Scope.ctx也会交出创建插件注入的服务范围，因此，若作用域创建者提供的服务范围较宽，持有者之后也无法将其收窄。
开发备注
维护者的工作上下文——点击展开
无。