作用域与能力缝

dsh 一个进程里可以同时跑多个 Agent、多个会话。它们的工具为什么不会互相串？换一个文件系统提供方，为什么所有文件工具跟着换？答案分别是作用域和能力缝。这是官方架构的两根支柱，读懂了它们，--dump-config 打出的树就不再是一堆陌生名字。

作用域：注册归属哪个 Agent

scope（作用域） 是 core/scope 包提供的库原语——注意，它是库，不是 Cordis 服务，没有 ctx 键。它的核心是一个不透明标识 ScopeKey（按对象身份比较），已交付的 agent loop 直接用活跃的 Agent 对象作为 key。

规则只有一条：一项注册（工具、提示词段、监听器）要么是全局的，要么归属于恰好一个 scope key。ScopedLayers 为每个注册表维护一个全局层和若干惰性创建的作用域层；读取时按插入顺序合并全局条目，再由最近的带作用域条目遮蔽远端同名项。

可以想成酒店房间：你在房里做的事，隔壁房看不见；全局注册则是大堂公告栏，谁都能看到。

Agent 的视图解析链是：

agent → preset → global（近者遮蔽远者）

这就是多 Agent 不串扰的机制：同一个工具名，Agent A 的注册在 A 的作用域层，Agent B 在 B 的层，互不覆盖。挂到不带 agent scope 的上下文，注册就变成全局。preset 服务拒绝「无 scope 挂载」，正是为了防这个。

排查「我的工具怎么被别的 Agent 看到了」，先查注册时带没带 scope。

能力缝：可替换能力的三角色

seam（缝） 是一项可替换能力，由三种角色构成：

角色	负责什么	以 Bash 为例
Service Definition	声明接口与类型	dsh-shell（注册为 ctx.shell）
Service Provider	实现该能力	dsh-bash-local（本地执行）
Consumer	面向模型的工具	dsh-tool-bash（bash 工具）

三者都依赖 Definition，Provider 与 Consumer 互不依赖。单一角色不是 seam；完整能力才是。 判断标准只有一个：这些角色是否需要独立演进或替换。

人话版：一个 seam 就是「接口 + 实现 + 面向模型的工具」三件套。想换实现，只动 Provider 那一层配置。

seam 正是「换一个提供方就改变整个产品」的原因。文件系统与进程提供方共享同一个执行世界。把 ctx.fs 指向远程沙箱，Bash、PTY、LSP 也跟着搬过去。你不需要为每个工具写提供方专用分支。Consumer 只认接口，不关心背后是本地还是云端。

# 换提供方：替换下面一行即可，Definition 和 Consumer 都不用动
- name: '@deepseek-ai/dsh-bash-local'
# - name: '@deepseek-ai/dsh-bash-sandbox'

核心服务：ctx.* 清单

服务可以是核心主干、可替换的能力缝，也可以是组合点。下面是入门阶段最常用的 ctx 键：

ctx 键	拥有包	职责
ctx.sessions	core/session	仅追加会话事件日志与内存存储
ctx.systemPrompt	core/system-prompt	提示词片段与工具 schema 组装
ctx.tools	core/tools	作用域化工具注册表 + 把关执行流水线
ctx.agents	core/agent	Agent 接口、活跃 Agent 注册表、agent/* 事件
ctx.agentLoop	core/agent-loop	默认 Agent 驱动器
ctx.llm	llm/llm	消息/流式词汇 + 适配器缝
ctx.attachments	attachment	附件持久存储
ctx.sandbox	sandbox	进程沙箱缝
ctx.approval	approval	审批缝
ctx.credentials	credentials	凭据缝
ctx.settings	settings	用户设置缝
ctx.sessionTelemetry	session-telemetry	会话遥测缝
ctx.tokenMeter	token-meter	Token 计量
ctx.invariants	invariants	运行时不变量注册表
ctx.typert	typert-registry	运行时类型注册表
ctx.typertGateway	api-gateway	Typert Host 调用网关
ctx.apiProxy	apiproxy	Host API 分发
ctx.sessionPersistence	session-persistence	会话持久化缝

scope 包本身没有 ctx 键。更多的缝——ctx.fs、ctx.shell、ctx.subprocess、ctx.terminals、ctx.subagents、ctx.compaction、ctx.storage、ctx.sessionQuery、ctx.sessionTitle、ctx.agentPresets、ctx.commands、ctx.goals、ctx.jobs、ctx.skills、ctx.web、ctx.permissionPresets——见官方 capability-seams 参考文档的能力图，或直接看 --dump-config 输出的实际注册。

怎么查某个能力能不能换

三个问题追一项能力：

1. 契约由谁定义——找 Service Definition 包
2. 当前装了哪个 Provider——看 --dump-config 配置树
3. Consumer 在哪个作用域激活——看工具注册与 preset 组合

审计到这三件事，一项能力的可替换性就清楚了。

小结

• scope 是库原语：注册要么全局，要么归属于恰好一个作用域。
• Agent 视图解析链：agent → preset → global，近者遮蔽远者。
• seam 是三角色结构：Service Definition + Provider + Consumer。
• 换 Provider 不改 Consumer，产品行为全局切换。
• 「八层架构」是外部抽象；官方说法是 Capability Seams + Core Services。