Agent 框架源码
第 7 节:换两个提供方,四样能力一起搬家
seam 是三角色齐备:声明、提供方、消费方。把 fs 与 subprocess 指向远端,Bash、终端、LSP 会一起搬过去,工具一行不改。沙箱更进一步,只在 spawn 前包装 argv,所有进程自动受约束。
- seam 角色
- 三件齐备Service Definition、Provider、Consumer,缺一不算
- 沙箱模式
- read-only·workspace-write·danger-full-access只管文件系统效果,不含网络与进程可见性
- 强制执行完整度
- full 或 partial后端必须作为事实上报,消费方需拒绝或向上暴露
seam 是三角色,不是一个接口
dsh 文档把 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 启动的进程自动受约束。
| 模式 | 允许写哪里 | 后端实测 |
|---|---|---|
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 链路验证连带迁移,并强调完整度上报 | 全页 |