# Agent Note: 不依赖具体能力的沙箱策略上下文

Status: implemented

[English](2026-07-31-capability-neutral-sandbox-policy-context.md) | 中文

## 问题

当前策略上下文最初通过受强制执行家族与可升权家族两个独立注册表来映射运行时组合。后端、工具与示例中的六个调用点会贡献 `filesystem`、`bash` 或 `terminal`；策略服务保留 token 集合，以便独立释放各项注册，对两个注册表的内容求交集并排序，在每次生命周期变化时使提示词组装失效，并且需要测试覆盖所有家族组合。

这份清单既不是说明文件策略所必需的，也不能作为模型可见能力的权威依据。后端贡献可能声明某个家族，而该家族面向模型的工具并不存在，或被请求作用域隐藏；工具 schema 已经向模型准确说明哪些操作可用。因此，为了维护一句近似的英文说明，注册表扩大了公开服务与生命周期契约。

## 决策

`dsh-sandbox-policy` 为每个 agent（智能体）会话贡献一项不依赖具体能力的 `sandbox:policy` 上下文。上下文文本只根据 `resolve({ session })` 派生；不存在后端或工具家族注册 API、贡献映射、排序规则，也不会因注册变化而使提示词失效。

该文本将能力声明限定于 DSH 文件沙箱所强制执行的可用操作。在 `read-only` 下，它说明这类操作在常驻模式下无法修改文件，并指示模型正常尝试可用工具，随后遵循该工具返回的任何拒绝与升权引导。在 `workspace-write` 下，它说明规范化的会话工作区，以及带有适用条件的临时区域写入许可。在 `danger-full-access` 下，它说明 DSH 文件沙箱不会限制可用操作修改文件。

哪些操作可用仍以工具 schema 为准。针对具体操作的拒绝以及获批后的更宽松模式重试，仍以工具结果为准。文件系统、一次性 bash 与终端实现继续解析并强制执行相同的逐调用策略；移除的只有面向模型的冗余能力清单。

本决策取代了[当前沙箱策略上下文决策](../feature/2026-07-30-current-sandbox-policy-context.md)中关于家族注册与按组合条件化措辞的部分内容。缓存安全的上下文交付、持久快照具体化、措辞证据，以及引导与强制执行之间的边界，仍以该 Agent Note 为归属文档。

## 曾考虑的替代方案

**保留注册表，但减少对应测试。** 不予采用，因为公开方法、保留的生命周期状态、六个贡献点和近似的能力声明仍会存在。组合测试只是体现了这一设计成本，并非成本的成因。

**从工具注册表派生确切清单。** 不予采用，因为当前策略只需要一句符合事实的条件性声明，而确切的可用情况已经体现在组装后的工具 schema 中，并且可能随请求作用域变化。若再把每个 schema 映射回其强制执行后端，就会引入另一项派生关系，而当前没有消费方需要它。

**仅在后端声明会强制执行时提供策略上下文。** 不予采用，因为这会重现注册问题，并使策略是否可见取决于可选贡献方。即使没有可适用的操作，这段带条件的措辞仍然符合事实。

## 后果

策略服务只有一条由归属方直接派生的上下文路径，无需维护两个公开注册表及其释放生命周期。增加或移除能力不再导致运行时上下文快照反复变化，模式和工作区变化仍会触发快照更新。聚焦测试仍覆盖各模式的确切措辞、规范化根目录、模式切换、恢复、服务释放与无 agent 组装；家族组合与贡献生命周期测试则随其所保护的行为一同删除。

模型不再收到以自然语言列出的沙箱能力家族清单，而是收到确切的工具 schema 与一项常驻文件策略声明。未来若产品需要独立的能力清单，该清单必须从权威的逐请求组装结果中派生，不能通过后端注册这种旁路机制重建。
