第 7 章：工具与数据类能力

这一章覆盖「模型能直接调用、用来读世界、写世界、查资料」的能力族：文件系统、LSP、技能、Web、MCP、附件、溢出存储。它们大多是标准的能力接缝——Service Definition 拥有 ctx.，Provider 注册实现，Consumer（通常是 tool-* 包）面向模型暴露工具名。​

7.1 文件系统（fs）​

文件系统栈（packages/fs/）由四类零件组成：provider 契约、本地实现、策略门插件、面向模型的文件工具 + 执行器，以及 ripgrep 驱动的发现工具。​

​

​ 包​ ​	​ 角色​ ​	​ ctx key​ ​
​ dsh-fs​ ​	​ Service Definition：规范进程路径 / 文件 URI / 包含关系、文本 IO、原子变更原语；拥有 fs/* 策略事件​ ​	​ ctx.fs​ ​
​ dsh-fs-local​ ​	​ 本地文件系统 FileSystem 实现​ ​	​ （注册 ctx.fs）​ ​
​ dsh-fs-e2b​ ​	​ E2B 支撑的实现，共享 ctx.e2b 拥有的远程运行时​ ​	​ （注册 ctx.fs）​ ​
​ dsh-fs-sandbox​ ​	​ 沙箱强制的实现：继承 fs-local，按每次调用的 mode + workspace root 策略围住 write/edit（read-only 拒绝、workspace-write 限制在会话 workspace + temp 根内），read 透传​ ​	​ （注册 ctx.fs）​ ​
​ dsh-fs-observation-policy​ ​	​ 策略门插件：observed-state + read-before-edit + 带版本守卫的 write/edit，通过 fs/* 事件门参与​ ​	​ （无服务——fs/* 监听器）​ ​
​ dsh-tool-fs​ ​	​ 模型面 read/write/edit 工具 和 执行器（读走 ctx.fs，拥有读窗口化，派发 fs/*）​ ​	​ （注册在 ctx.tools）​ ​
​ dsh-tool-fs-search​ ​	​ 模型面 glob/grep 发现工具，走打包的 @vscode/ripgrep 二进制（通过 ctx.subprocess spawn），不是 ctx.fs provider 方法​ ​	​ （注册在 ctx.tools）​ ​

​

Service Definition 在 packages/fs/fs/src/index.ts。沙箱化、远程或项目作用域的文件系统后端可以替换 fs-local 而不碰 Service Definition、策略门或模型面 schema：fs-sandbox 提供共享沙箱模式上的进程内路径围栏，fs-e2b 把文件状态放进与 E2B 子进程 provider 共享的远程执行世界。​

策略（fs-observation-policy）是只通过 fs/* 事件门参与的插件，不是工具注入的服务——所以丢掉它只是优雅地失去策略、留下未约束的裸 provider，而不会弄坏工具。​

文件 IO 不带超时：read/write/edit 没有 timeoutMs，provider 契约也不布防 deadline——因为 deadline 会杀掉操作系统仍会完成的工作。取消仍通过工具执行 signal 传播，在系统调用边界做尽力而为的中止。细节见文件系统子系统。​

7.2 LSP（lsp）​

语言服务器能力接缝：Service Definition、通用 stdio provider、面向模型的 lsp 工具。​

​

​ 包​ ​	​ 角色​ ​	​ ctx key​ ​
​ dsh-lsp​ ​	​ Service Definition（按 branded id 的 provider 注册表 + 扩展映射、每次查询选择、词汇、LspError）​ ​	​ ctx.lsp​ ​
​ dsh-lsp-stdio​ ​	​ 基于 ctx.fs 与 ctx.subprocess 的通用多服务器 stdio 后端（JSON-RPC、瞬态打开查询）​ ​	​ （注册 provider 到 ctx.lsp）​ ​
​ dsh-tool-lsp​ ​	​ 模型面 lsp 工具（四种操作、从 1 开始的 UTF-16 游标坐标）​ ​	​ （注册在 ctx.tools）​ ​

​

接缝暴露恰好四种语义操作——goToDefinition、findReferences、goToImplementation、hover——且没有通用 JSON-RPC 逃生门。因此换 provider 不改变模型请求导航的方式，也不会有协议载荷或未经审查的变更进入模型契约。Provider 注册的是能力，不是工具；tool-lsp 是模型面名字、schema、prompt 指引与呈现的唯一拥有者。​

7.3 技能（skill）​

技能族发现可复用的 agent 指令，并通过 provider 无关的目录与加载器暴露给模型。​

​

​ 包​ ​	​ 角色​ ​	​ ctx key​ ​
​ dsh-skill​ ​	​ 定义 skill provider 注册与查找​ ​	​ ctx.skills​ ​
​ dsh-skill-badge​ ​	​ 提供可选的打包 dsh badge 技能​ ​	​ （注册在 ctx.skills）​ ​
​ dsh-skill-filesystem​ ​	​ 从本地文件系统发现技能​ ​	​ （注册在 ctx.skills）​ ​
​ dsh-tool-skill​ ​	​ 发布技能目录与模型面加载器​ ​	​ （注册在 ctx.tools）​ ​

​

技能能力在核心控制主轴之外，换本地 / 内嵌 / 远程 provider 都不改变模型面契约。细节见技能子系统（发现优先级、目录快照、skill 加载器）。​

7.4 Web（web）​

Web 能力族提供 provider 无关的搜索与抓取，加上消费它们的模型面工具。​

​

​ 包​ ​	​ 角色​ ​	​ ctx key​ ​
​ dsh-web​ ​	​ 定义 web provider 注册、选择与共享错误​ ​	​ ctx.web​ ​
​ dsh-web-search-exa​ ​	​ 经 Exa 提供搜索​ ​	​ （注册在 ctx.web）​ ​
​ dsh-web-search-perplexity​ ​	​ ​	​ ​
​ ​	​ ​	​ ​
​ ​	​ ​	​ ​
​ ​	​ ​	​ ​

​

搜索与抓取共享同一个 provider 选择服务。细节见web 子系统（WebSearchRequest/Result、WebFetchRequest/Result、WebError）。​

7.5 MCP（mcp）​

​

​ 包​ ​	​ 角色​ ​
​ dsh-mcp-client​ ​	​ MCP 客户端桥：把外部服务器工具注册到 ctx.tools​ ​

​

它把 harness 桥接到 MCP 生态——外部 MCP 服务器的工具，以模型面工具的形式出现在 ctx.tools 上。​

7.6 附件（attachment）​

持久二进制附件接缝与本地文件系统实现。​

​

​ 包​ ​	​ 角色​ ​	​ ctx key​ ​
​ dsh-attachment​ ​	​ 不可变附件引用、图片限制、存储服务​ ​	​ ctx.attachments​ ​
​ dsh-attachment-local​ ​	​ DSH_HOME 下内容寻址的私有存储​ ​	​ （注册在 ctx.attachments）​ ​

​

未发送的浏览器草稿有意处在该能力之外：字节只在用户 prompt 提交、或 provider 适配器提交结构化模型输出时才进入持久存储。细节见附件子系统。​

7.7 溢出存储（spill）​

溢出存储族把超大工具输出持久化，并用有界预览 + 检索定位器替换内联结果。​

​

​ 包​ ​	​ 角色​ ​	​ ctx key​ ​
​ dsh-spill​ ​	​ 定义溢出存储​ ​	​ ctx.spillStore​ ​
​ dsh-spill-local​ ​	​ 把溢出文本存进会话作用域的本地文件​ ​	​ （注册在 ctx.spillStore）​ ​
​ dsh-spill-policy​ ​	​ 应用执行后溢出策略​ ​	​ （监听在 ctx.tools）​ ​

​

细节见溢出子系统（SaveTextSpill、owner/source、branded SpillLocator）。​

7.8 这些接缝的共同点​

回顾一下，你会发现它们共享同一条规律（正是第 1 章「能力接缝」的定义）：​

Service Definition 声明接口与 ctx.（抽象类或注册表）。​

Provider 实现接口、注册到该 key；可以有多个 provider 并存。​

Consumer 注入该 key 并使用；模型面工具是 Consumer 的典型形态。​

换 provider 不碰 Service Definition 与 Consumer——这就是「换一个 provider，整个产品跟着变」在数据/工具层的体现。​

下一步​

这些是「单次调用」的能力。下一章第 8 章：编排看更高一层的组织能力：subagent 委派、工作流扇出、todo/plan/goal 的持久协作状态、jobs 后台任务与 compaction 压缩。​