# 宿主机沙箱与权限系统说明（2026-05）

本文档用于完整说明当前项目在 **宿主机模式（`TERMINAL_SANDBOX_MODE=host`）** 下的安全执行机制，包括：

- OS 级沙箱执行
- 执行环境（Execution Mode）
- 权限模式（Permission Mode）
- 路径授权（Path Authorization）
- `run_command` / `terminal` / `sub_agent` 的实际行为

---

## 1. 设计目标

在保留宿主机开发效率的前提下，降低误操作与越权风险，核心目标是：

1. 默认命令执行必须经过系统沙箱（而非裸 host）
2. 权限控制尽量由执行层强制（减少“猜指令”误判）
3. 对高风险写操作引入用户审批与单次授权机制
4. 保持可运维：可配置、可回退、可解释

---

## 2. 两层控制模型

当前系统分为两层控制，且叠加生效：

### 2.1 权限模式（产品层）

- `readonly`
- `approval`
- `auto_approval`
- `unrestricted`

作用：决定工具是否允许调用、是否先只读执行、是否需要用户审批。

### 2.2 执行环境（系统层）

- `sandbox`（默认）
- `direct`

作用：决定进程最终在 OS 沙箱中执行，还是直接在宿主机执行。

> 推荐默认：`permission_mode=approval` + `execution_mode=sandbox`

---

## 3. OS 级沙箱方案

宿主机模式下，默认执行环境为 `sandbox`，各系统实现如下：

- **macOS**：`sandbox-exec`
- **Linux**：`bubblewrap (bwrap) + seccomp`
- **Windows**：`WSL2`

若宿主机沙箱不可用，关键执行路径会拒绝执行，不允许静默回退到裸 host。

---

## 4. 路径授权模型

路径授权分两类：

1. **可读可写路径（writable_paths）**
2. **仅可读路径（readable_extra_paths）**

语义：

- 可读集合 = 可读可写 + 仅可读
- 可写集合 = 可读可写

前端“路径授权”弹窗支持这两类路径的维护（新增/编辑/删除），并由后端策略模块统一读取。

---

## 5. 各权限模式的实际行为

## 5.1 readonly

- `run_command`：允许调用，但在**只读沙箱**执行
- 若命令触发写入：由系统返回权限拒绝（例如 `Operation not permitted`）
- `write_file` / `edit_file` / 其他写入类工具：直接拒绝

## 5.2 approval

- `run_command` 采用“两段式”：
  1) 先在只读沙箱执行  
  2) 若出现权限拒绝，再发起前端审批  
  3) 审批通过后，仅该次命令以可写沙箱重试
- 工具结果返回“最终执行结果”（即重试后结果），不会把中间权限拒绝作为最终结果返回给模型
- 审批拒绝或超时：返回 rejected，不执行写入重试

## 5.3 auto_approval

- `write_file` / `edit_file`：
  - 目标路径在当前工作区内：直接执行
  - 目标路径不在当前工作区内：进入审批流程
- `run_command` 采用“两段式”：
  1) 先在只读沙箱执行  
  2) 若出现权限拒绝，触发自动审批（审批智能体）  
  3) 自动审批通过后，仅该次命令可写重试
- 自动审批拒绝：返回“工具调用被拒绝 + 原因”，主智能体继续下一步（不强制中断整轮任务）
- 用户可随时人工接管审批结果（同意/拒绝/切换无限制）

## 5.4 unrestricted

- 权限模式层不拦截工具
- 是否沙箱执行取决于执行环境：
  - `sandbox`：仍在 OS 沙箱中执行
  - `direct`：宿主机直接执行

---

## 6. 执行环境（sandbox/direct）细节

## 6.1 sandbox（默认）

- 命令在 OS 沙箱执行
- 配合路径授权限制写边界（与读边界策略）
- 可结合权限模式实现只读优先与单次升级写权限

## 6.2 direct（高权限）

- 命令直接在宿主机执行
- 仅建议临时用于必须操作
- 支持 TTL 自动回退（会话级）到 `sandbox`

---

## 7. 关键工具与执行路径

### 7.1 run_command

- 支持权限模式联动（readonly/approval/unrestricted）
- 在 host + sandbox 下可走只读沙箱或可写沙箱
- 在 approval 模式可触发“权限拒绝 -> 审批 -> 单次可写重试”
- 在 auto_approval 模式可触发“权限拒绝 -> 自动审批 -> 单次可写重试”

### 7.2 terminal 系列

- 终端会话从启动时就在沙箱里（host+sandbox）
- 同一会话中的后续输入继承该会话沙箱上下文
- 若路径授权更新，需要新开终端会话才能让该会话使用新策略

### 7.3 子智能体（sub_agent）

- 宿主机下已接入执行环境策略：
  - `sandbox`：子智能体进程经宿主机沙箱启动
  - `direct`：直接宿主机启动
- Docker 模式维持容器执行

### 7.4 自动审批（approval agent）

- 自动审批由独立审批智能体执行（与主智能体分离）
- 配置文件：`config/auto_approval.json`
  - `name` / `url` / `key` / `model` / `extra_params`
  - `timeout_seconds` / `max_rounds` / `max_command_timeout`
- 审批智能体可调用能力：
  - `run_command`（用于只读核查）
  - 审批决策工具（approved / rejected + reason）
- 调试开关（代码变量）：
  - `modules/approval_agent.py` 中 `DEBUG_SAVE_APPROVAL_AGENT_TRANSCRIPT`
  - 开启后记录到 `logs/approval_agent/`

---

## 8. 配置与运行建议

## 8.1 推荐默认策略

1. `TERMINAL_SANDBOX_MODE=host`
2. 执行环境默认 `sandbox`
3. 权限模式默认 `approval`
4. 路径授权默认最小化（工作区 + 临时目录）

## 8.2 何时使用 direct

仅在以下场景短时开启：

- 明确需要系统级高权限访问
- 沙箱下无法完成且替代方案不可行

执行完成后应尽快回到 `sandbox`。

---

## 9. 已知权衡

1. `run_command` 若严格收紧读路径，可能导致大量系统命令可用性下降  
2. 权限拒绝识别基于错误特征，需持续优化误判/漏判边界  
3. 不同 OS 的沙箱能力不完全对齐（Windows 侧为 WSL2 路径）
4. Docker 模式下目前不存在与宿主机同等的 OS 只读沙箱机制；`sandbox_write_access=False` 不会提供同等级只读隔离（需后续补充容器侧只读策略）

---

## 10. 文案与产品约束

- 面向用户的提示词仅描述“能力边界”和“可操作建议”
- 不暴露内部实现细节（如内部判定逻辑、实现细节名称）
- 审批流程文案要强调“单次授权、最小权限、可回退”