10bb6dc4fe
Review fix (ds-review-bot on #623): the READMEs and JSDoc still stated the pre-baseline formulas — resolve() outranking 'the session's last sandbox/mode event', 'effective = explicit grant ?? fold(events) ?? deployment default', and the approval README's 'last approval/policy event' opener — which contradict the shipped semantics for a delegated fork whose seed tail differs from its header baseline. Every statement now names the override chain (own post-seed switches ?? inherited header baseline): both READMEs (both languages), resolve()'s JSDoc, the session-mode module and event-declaration docs, the raw folds re-scoped as building blocks, and the regenerated catalogs.
43 lines
5.0 KiB
Markdown
43 lines
5.0 KiB
Markdown
# dsh-sandbox-policy：沙箱策略归属位置（`ctx.sandboxPolicy`）
|
||
|
||
[English](README.md) | 中文
|
||
|
||
沙箱策略解析的唯一 owner：部署默认 [`SandboxMode`](../sandbox/README.md) 与回退根目录，加上每个会话的持久模式覆盖和不可变 Workspace 根。每个执行强制限制的能力家族在每次调用时收到一项解析完成的模式与根策略。
|
||
|
||
## 为何需要共享归属位置
|
||
|
||
两个家族强制执行同一套模式词汇：沙箱化 bash 执行器（`@deepseek-ai/dsh-bash-sandbox`）与沙箱化文件系统提供方（`@deepseek-ai/dsh-fs-sandbox`）。如果两者各自解析 `mode` + `workspaceRoot`，就可能漂移成分裂世界：bash 限制在一个根目录，fs 却隔离另一个根目录，正是[沙箱 RFC](../../../.agents/notes/implemented/feature/2026-07-06-sandbox.md)所警告的情况。两个工具层都通过 `ctx.sandboxPolicy` 解析策略，两个执行后端也都消费完整的逐调用结果。[跨家族 fs 沙箱 RFC](../../../.agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md)记录了共享策略决策。
|
||
|
||
## 配置
|
||
|
||
- `mode`：部署默认 `SandboxMode`（`read-only`／`workspace-write`／`danger-full-access`），加载时验证。默认为 `read-only`（故障安全）。
|
||
- `workspaceRoot`：agentless 调用或没有 cwd 的会话在 `workspace-write` 下可写入的回退目录。默认为 `process.cwd()`，两种情况下都会解析为其绝对文件系统标识。普通 agent 调用改用其会话头中不可变的 `cwd`。
|
||
|
||
## 表层
|
||
|
||
- `ctx.sandboxPolicy.resolve({ session?, mode? })`：解析一项完整的逐调用策略。显式批准的模式优先于会话的覆盖链（见下文 `overrideOf`），后者又优先于 `defaultMode`；会话不可变的 `cwd` 会先按文件系统语义规范化，再成为 `workspaceRoot`，否则使用配置的回退值。规范化先于词法归一化，因此 `symlink/..` 与进程工作目录解析保持一致。
|
||
- `ctx.sandboxPolicy.defaultMode`／`ctx.sandboxPolicy.workspaceRoot`：`resolve()` 使用的部署默认值与回退根。
|
||
- `effectiveSandboxMode(events)`：对一段 `sandbox/mode` 事件切片的纯折叠（最后一次切换胜出，没有则为 `undefined`），是 `sandboxOverrideOf` 与种子边界和会话头基线进行组合时所用的基础构件。
|
||
- `setSandboxMode(session, mode)`：逐会话覆盖的唯一写入路径：恰好追加一条 `sandbox/mode` 事件。切换本身就是事件；不会在带外修改模式。
|
||
- `ctx.sandboxPolicy.overrideOf(session)`（即纯函数导出 `sandboxOverrideOf`，也供权限 preset 消费）：会话的覆盖链，绝不包含部署默认值：当存在继承的 `sandboxMode` 会话头基线时（即委派子 agent），先折叠会话自己在 `SessionHeader.seedLength` 之后的切换，否则取该基线，读取时按封闭词汇校验（遇到词汇之外的值即抛出异常——这是一条持久边界）；没有基线时（顶层会话或通用的 `SessionStore.fork` 子会话），折叠覆盖完整日志，因此种子携带的切换仍是回放所得的继承事实。进程内 subagent 驱动器在委派时捕获该值，并写入每个子 agent 创建时的会话头，使发起委派的父级收紧后的模式约束其子 agent，且不存在任何第一轮次的时序窗口（参见[设计原理](../../../.agents/notes/implemented/feature/2026-07-25-subagent-policy-inheritance.md)）。
|
||
- `SANDBOX_MODES`：所有模式，用于选项展示与运行时验证。
|
||
|
||
可选的 `./invariant` 配套组件会拒绝伪造的持久 `sandbox/mode` 事件，只要其值不在该封闭词汇中；Session 与其配套组件拥有周围的存储与轮次封闭规则。
|
||
|
||
## 逐会话 store
|
||
|
||
运行时切换是在对应会话日志中追加的一条 `sandbox/mode` 事件。`effective = explicit grant ?? override chain ?? deployment default`，其中覆盖链（override chain）是 `sandboxOverrideOf` 折叠会话自己在种子之后的切换所得，否则取继承的会话头基线——因此覆盖会通过回放跨重启保留，委派子 agent 会在其父级捕获的策略下启动，两个会话也绝不会看到彼此状态。Workspace 标识无需另一条事件：创建时记录的不可变 `SessionHeader.cwd` 是该会话每次调用使用的根。该事件只进入日志（沿用 `approval/*` 先例）：模型通过强制执行工具的拒绝标记获知模式，绝不会从事件获知。
|
||
|
||
## 模型体验
|
||
|
||
通过 `dsh-tool-bash` 和 `dsh-tool-fs` 间接影响；它们会在 `[sandbox: …]` 拒绝标记和升权提示词中渲染该服务持有的有效模式，`sandbox/mode` 事件本身绝不会到达模型。
|
||
|
||
#### KV Cache 影响
|
||
|
||
不会直接失效；请求前缀变更由命名消费方负责，且提示词有意不包含模式。
|
||
|
||
## 已知限制与暂缓事项
|
||
|
||
- **每个会话只有一个主要 Workspace 根**：策略解析 `SessionHeader.cwd`；额外可写根不属于 `SandboxExecutionPolicy`。
|
||
- **只有文件 effect 模式**：`SandboxMode` 治理文件 effect；网络和进程策略不在其词汇中，因此这里没有限制它们的旋钮。
|