qiming/qimingclaw/crates/agent-electron-client/docs/sandbox/README.md

沙箱方案文档

多平台 Agent 沙箱工作空间技术文档

---

文档索引

文档	说明
ARCHITECTURE.md	沙箱架构设计
IMPLEMENTATION.md	沙箱实现说明
API.md	通用 API 文档
SANDBOX-API.md	沙箱 API 接口文档
SANDBOX-COMMANDS.md	沙箱命令白名单
SANDBOX-SUBMODULE-INTEGRATION.md	三端沙箱子模块接入
TROUBLESHOOTING.md	故障排查
../operations/SANDBOX-SUBMODULE-UPDATE-RUNBOOK.md	子模块升级与回滚 Runbook

---

最近同步（2026-04-10）

• 已补充 PlatformAdapter 统一平台抽象层在 sandbox 主链路的接入说明
• 已同步 strict 语义：
  • macOS seatbelt strict 不包含 startup chain exec allowlist
  • Windows helper run strict 的 writable_roots 仅保留首个路径（workspace-first）
• 对应细节见：
  • ARCHITECTURE.md
  • ../operations/ACP-TERMINAL-SANDBOX.md

---

三区隔离模型

┌─────────────────────────────────────────────────────────────┐
│                     用户空间（User Space）                   │
│                                                              │
│   ┌─────────────────┐                                      │
│   │  应用核心区       │  只读、不可变                         │
│   ├─────────────────┤                                      │
│   │  Agent 工作区    │  可写、隔离                           │
│   ├─────────────────┤                                      │
│   │  用户系统区      │  只读访问                             │
│   └─────────────────┘                                      │
│                                                              │
└─────────────────────────────────────────────────────────────┘

---

平台支持

平台	主要沙箱	备选
macOS	sandbox-exec	Docker
Windows	Windows Sandbox helper	Docker
Linux	bubblewrap	Docker

---

阅读顺序

1. ARCHITECTURE.md - 了解沙箱核心架构
2. IMPLEMENTATION.md - 查看实现细节
3. SANDBOX-API.md - 参考 API 接口

---

相关文档

• ../architecture/ISOLATION.md - 三区隔离模型
• ../v2/01-ARCHITECTURE.md - 应用架构
• ../AGENTS.md - Agent 开发指南