跳到主要内容
赞助推荐 搬瓦工怎么选:三网直连 CN2 GIA-E
核对于 2026-11-05
课程目录 · 11 节

Agent 框架源码

第 7 节:换两个提供方,四样能力一起搬家

核对 2026-11-05 更新 1 次 引用 0 个来源

seam 是三角色齐备:声明、提供方、消费方。把 fs 与 subprocess 指向远端,Bash、终端、LSP 会一起搬过去,工具一行不改。沙箱更进一步,只在 spawn 前包装 argv,所有进程自动受约束。

关键事实 · 3 条口径随行标注
seam 角色
三件齐备Service Definition、Provider、Consumer,缺一不算
沙箱模式
read-only·workspace-write·danger-full-access只管文件系统效果,不含网络与进程可见性
强制执行完整度
full 或 partial后端必须作为事实上报,消费方需拒绝或向上暴露

seam 是三角色,不是一个接口

dsh 文档把 seam(能力接缝) 定义得很严格:一项可替换能力必须同时有三个角色,缺一不算。

三角色齐了才叫 seam,只有一个接口叫「抽象泄漏」
角色 是什么 以 fs 为例
Service Definition 声明接口 ctx.fs 的读写编辑契约
Service Provider 实现接口 本地实现、SSH 远端实现、内存实现
Consumer 使用接口 read / write / grep 这些面向模型的工具

dsh 里大量包同时承担多个角色(一个包既提供 ctx.fs 又提供对应工具),但文档特意强调:单一角色本身不是 seam。加一项能力意味着三个角色一起设计,否则你只是又写了一个直接 import 的模块。

这套纪律真正的回报在组合时兑现。文件系统和进程提供方共享同一个「执行世界」——它们必须指向同一台机器,否则「读到的文件」和「bash 跑的地方」不是一回事。所以当两者配套指向远程沙箱,Bash、持久终端、LSP 会一起搬过去。

换一处,四样能力一起搬家

这是 seam 设计最有说服力的地方,也是「给每个工具写一份远程版」这种做法最直接的替代方案:

换成远程执行,只改两个提供方
  │
  ├─ ctx.fs         → 远程后端
  │     └─ 连带:read / write / edit / grep / glob / diff 卡片
  │
  └─ ctx.subprocess → 远程后端
        └─ 连带:bash / PTY 持久终端 / LSP 语言服务
              ↓
        所有消费方一行没改,全部在远端跑

对照组是常见的做法:给 bash 写一个远程版本,再给 read 写一个,再给 grep 写一个。工具越多,重复实现越多,而且这些版本之间的一致性没人保证——远程 read 支持 200KB 截断,远程 grep 忘了加,行为就分叉了。

沙箱走的是同一条路,但约束加在更前面。ctx.sandbox 提供的不是「一个能跑命令的后端」,而是在 spawn 前包装 argv 的策略。所以沙箱不需要知道有几个工具,它只处理「进程要被怎么启动」这一件事,所有经 ctx.subprocess 启动的进程自动受约束。

SandboxMode 只管文件系统效果,不管网络与进程可见性
模式 允许写哪里 后端实测
read-only 只允许 /dev/null 这类必需接收器 macOS Seatbelt、Linux bwrap/Landlock
workspace-write 工作区根、额外目录、临时区 同上,Windows 用 ACL 受限令牌
danger-full-access 不隔离 消费方直接 spawn 原始 argv,不经过 ctx.sandbox

注意最后一行:danger-full-access 的消费方根本不调用 ctx.sandbox。这个细节说明设计者不接受「策略对象存在但被绕过」这种半吊子实现——不隔离的模式下,连调用都不发生。

一个诚实的细节:强制执行完整度是要上报的

沙箱文档里有一段很多框架不会写的东西:强制执行完整度(enforcement integrity)必须作为事实上报。

full 表示后端确实管控了该模式承诺的所有文件效果;partial 表示当前后端或较旧的内核 ABI 只能管控其中一部分。dsh 明确要求:需要绝对保证的消费方必须拒绝或把这个区别向上暴露。

已知的部分强制执行情形写得很具体:较旧的 Landlock ABI;Windows ACL 后端在硬链接、读取不受限、AppContainer ACL 边界上的缺口。

这条设计比「支持沙箱」四个字有价值得多。安全能力最怕的不是没有,是以为有。一个返回 ok 但其实只拦了一半的沙箱,比明确报 partial 的沙箱危险得多——因为上层会基于错误的假设放行更危险的操作。

把这条和自己的系统对照一下:你对「隔离生效了」这件事,是有一个布尔值,还是有一个带完整度的上报?前者在跨平台时会骗你。

下一节往上下文方向走:提示词怎么装配,超长上下文怎么压,压掉的到底是哪一部分。

变更记录

日期类型改了什么范围
新建 用 fs/subprocess 链路验证连带迁移,并强调完整度上报 全页
赞助推荐 一键部署 AI 大模型
赞助推荐 一键部署 AI 大模型