feat(sandbox-policy): describe enforced file families

2026-07-30 18:51:29 +08:00
parent d3323494ba
commit 87a4aaa32e
48 changed files with 623 additions and 140 deletions
@@ -12,11 +12,13 @@ Status: implemented

 `dsh-sandbox-policy` 负责解析模式与工作区根目录，并注册一个 `sandbox:policy` 系统提示词段落。每次 agent（智能体）请求都通过 `ctx.sandboxPolicy.resolve({ session })` 直接解析当前会话；不存在拒绝历史扫描、差量叙述器或内存中的「上次告知」状态。

-该段落说明当前文件操作模式，且只说明归其所有的后果。`read-only` 表明普通写入、编辑和会修改文件的 shell 操作会被拒绝，但必要的写入目标可能仍可写。`workspace-write` 会列出共享 `writableRoots()` 策略返回的规范化可写根目录：不可变的会话工作区根目录、`/tmp` 与平台临时目录，并在规范化后去重。`danger-full-access` 表明 DSH 文件沙箱不会额外施加文件限制。每种形式都说明主机权限或后端可用性可能施加更多限制，且网络和进程访问不属于该策略的管辖范围。
+强制执行后端会向策略归属方注册可独立释放的 `filesystem`、`bash` 或 `terminal` 家族贡献。该段落只按规范顺序列出已注册家族，没有家族时为空。这是当前需求，而不是未来扩展：已交付的 headless inheritance 组合将沙箱化文件系统工具与不受围栏约束的一次性 bash 结合，而 persistent-tools 组合则包含沙箱化文件系统工具与终端命令，却没有沙箱化的一次性 bash 执行器。笼统声明在这两种组合中都会失实。
+
+该段落只说明每个已注册家族的所有强制执行方言所共有的事实。`read-only` 表明这些操作无法修改文件。`workspace-write` 用非排他措辞说明规范化的会话工作区，并概述某些平台临时区域可能也可写，而不逐一列举。`danger-full-access` 表明 DSH 文件沙箱不会限制这些操作。后端选择的临时路径、`/dev/null`、runner 就绪状态和其他策略领域都不会出现，因为 `resolve()` 无法在请求组装时确定它们。

 提供方在正常请求组装期间运行：此时 `/permission` 切换已经提交既有 `sandbox/mode` 事件，`request/header` 尚未记录。因此，渲染后的系统文本就是模型所见确切事实的持久化重建结果。会话状态不变时，重复组装会产生完全相同的字节；恢复与回放会折叠同一条持久模式事件和不可变的 `SessionHeader.cwd`，无需追赶状态。

-归属范围保持收敛。批准策略仍由独立的 `approval:policy` 段落负责，计划模式仍由 `plan:policy` 负责，工具插件也继续负责各自的 schema 与操作引导。提示词负责说明策略；bash 与文件系统后端仍是强制执行边界。
+归属范围保持收敛。批准策略仍由独立的 `approval:policy` 段落负责，计划模式仍由 `plan:policy` 负责，工具插件也继续负责各自的 schema，以及尝试、拒绝与升级引导。提示词负责说明常驻策略；文件系统、一次性 bash 与终端后端仍是强制执行边界。

 ## 曾考虑的替代方案

@@ -28,10 +30,14 @@ Status: implemented

 **在该段落中重复工具 schema，或批准与计划引导。** 不予采用，因为这些接口已有各自归属方和独立生命周期。重复内容会造成相互矛盾的请求前缀，并扩大缓存失效范围。

-**继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 后续 Web 证据与已经完成的跨工具族策略否决了这一方案。先前的句子只提到 bash 沙箱，没有说明实际的写入／编辑边界，因此可能与可见工具和升级引导冲突。由归属方派生的段落会说明完整的当前文件操作后果、规范化的工作区范围，并明确说明不作哪些保证，同时不重复工具指令。这只取代[沙箱 Agent Note](2026-07-06-sandbox.md) 中关于省略策略的决策；其中的强制执行与升级边界仍然有效。
+**继续省略沙箱模式，因为常驻模式标签曾引发预防性拒绝。** 不予采用，因为新的 Web 请求否则会暴露变更工具，却隐去这些工具的常驻策略，导致模型在首次操作前错误声称自身能力。先前的线上测量仍是必须执行的反证测试：使用 `Bash commands run under the "read-only" file sandbox.` 时，十二个轮次中有五个没有调用工具。已提交的工具归属方尝试引导晚于该测量，因此应通过当前工具契约下的新阳性对照实验选择替代文案，而不能假设旧条件与当前条件相同。
+
+**独立的模型上下文包。** 不予采用，因为 Cordis 服务可以直接观察当前运行时贡献，而批准与计划策略段落也已经与各自归属方放在一起。新包会为了一个内部适配器引入浅层组合 seam 和额外的文档／门禁表面。
+
+**枚举可写临时根目录。** 不予采用，因为后端要到稍后的 `confine()` 才会选定：bwrap、Landlock、Seatbelt 和进程内文件系统围栏并不授予一套共同的临时路径。常驻请求中的主机特定路径既不稳定，也会作出过度承诺。

 ## 后果

-模型可以在试探工具前回答当前可能执行哪些文件操作，且 `/permission` 后的下一个请求会反映已提交的模式。这会增加一个小型动态系统段落，并在策略变化时有意使请求前缀缓存失效；状态不变时仍保持缓存稳定。该声明是引导，而不是强制执行护栏：运行时安全仍来自 `dsh-bash-sandbox` 与 `dsh-fs-sandbox` 消费同一项解析完成的策略。
+模型可以在试探工具前回答常驻模式管辖哪些已注册文件操作，且 `/permission` 后的下一个请求会反映已提交的模式。这会增加一个小型动态系统段落，并在策略或强制执行家族组合变化时有意使请求前缀缓存失效；状态不变时仍保持缓存稳定。该声明是引导，而不是强制执行护栏：运行时安全仍来自已注册的文件系统、一次性 bash 与终端后端消费同一项解析完成的策略。

-聚焦的 sandbox-policy 测试固定了三种文本、规范化根目录、切换时机、字节稳定性与回放。无密钥的组装 ACP 快照通过真实 Loader 组合固定请求 header；Web 浏览器场景则驱动 `/permission` 在所有模式之间切换，检查每个确切的 `request/header`，并验证模型无需试探性工具调用即可完成；录制模式会使用真实提供方。
+聚焦测试固定了所有模式、家族组合、贡献释放、规范化根目录、切换时机，以及不同 `TMPDIR` 值下的字节稳定性。无密钥的组装快照通过真实 Loader 组合固定请求 header，包括全部三个家族。真实提供方选型使用预先登记的行为终点指标选择措辞，无密钥回放则负责固定选定的拒绝到升级轨迹。