# 核心概念

Astrion 有四组**相互正交**的概念，理解它们是理解整个系统的钥匙。它们两两组合决定了一次任务「能做什么、在哪跑、做到什么程度」：

| 概念组 | 取值 | 决定什么 | 在哪里切换 |
|--------|------|----------|------------|
| **部署模式** | host / docker(web) | 数据存哪、命令在宿主机还是容器里跑 | 环境变量（部署时确定） |
| **权限模式** | readonly / approval / auto_approval / unrestricted | AI 的工具调用要不要经过批准 | 输入栏权限菜单（对话级） |
| **执行环境** | sandbox / direct | 命令是否经过 OS 沙箱 | 输入栏权限菜单（对话级，仅 host 模式） |
| **运行模式** | plan / ask / execute | AI 与你的交互节奏：先出计划还是直接干活 | 输入栏运行模式切换器（对话级） |

---

## 1. 部署模式：host vs docker（web）

部署模式在**启动前**由环境变量 `TERMINAL_SANDBOX_MODE` 决定，运行中不可切换。

- **host 模式**：面向本地个人使用。命令通过宿主机 OS 沙箱执行，AI 可以直接操作你授权的本机目录（比如真实的项目仓库），文件管理器、本地 Node/Python 工具链直接可用。
- **docker 模式（web 模式）**：面向服务器多用户部署。每个用户的终端命令在独立的 Docker 容器里执行，用户之间文件与进程天然隔离。需要先构建沙箱镜像（见《快速上手》）。

两者的数据目录完全分开（`~/.astrion/astrion/host/` 与 `web/`），但 host 模式会**合并读取** web 模式的用户与工作区列表——同一台机器上两种模式的历史数据都能看到。

> 注意：docker 模式同样有只读强制——受限档权限（readonly/approval/auto_approval）下，命令以非特权用户（uid 10001）在容器内执行，写入由内核文件权限直接拒绝，「只读→审批→单次可写重试」两段式流程与 host 模式一致（详见《执行与安全》）。

## 2. 权限模式：AI 能做什么

权限模式是**产品层**开关，决定工具调用是否被拦截、是否需要批准。按对话切换，随时可改。

### readonly（只读）

- `run_command` 允许调用，但在**只读沙箱**中执行；一旦触发写入，操作系统直接返回权限拒绝（如 `Operation not permitted`）。
- `write_file` / `edit_file` 等写入类工具**直接拒绝**。
- 适用：让 AI 只做代码审查、只读分析、回答问题时。

### approval（批准，推荐默认）

- `run_command` 走**两段式**：先在只读沙箱执行 → 若出现权限拒绝，向前端发起审批 → 你批准后，**仅该条命令**以可写沙箱重试一次。
- 工具返回的是重试后的最终结果，AI 不会看到中间的拒绝过程。
- 审批拒绝或超时：本次不执行，不写入。

### auto_approval（自动审核）

- 与 approval 相同的「只读优先」流程，但审批者是**自动审批智能体**（一个独立的 AI，可在个人空间配置它的模型与参数）。
- `write_file` / `edit_file`：目标在工作区内直接执行；工作区外进入自动审批。
- 自动审批拒绝时，AI 收到「被拒绝 + 理由」后继续尝试别的路径，不会中断整轮任务。
- 你可以随时人工接管：同意 / 拒绝 / 切换为无限制。

### unrestricted（无限制）

- 权限层不做任何拦截，工具直接执行。
- 此时安全边界完全由执行环境决定（见下节）：sandbox 下仍有 OS 沙箱兜底，direct 下等于裸奔。

## 3. 执行环境：sandbox vs direct

执行环境是**系统层**开关（仅 host 模式可切换），决定命令最终是否经过 OS 沙箱：

- **sandbox（默认）**：命令在 OS 沙箱中执行，读写边界由「路径授权」限定。沙箱不可用时关键执行路径会**拒绝执行**，不会静默回退到裸宿主机。
- **direct（高风险）**：命令直接在宿主机执行，无任何沙箱限制。仅 `unrestricted` 权限可选——受限档（readonly/approval/auto_approval）与 direct 硬互斥，在受限档下切 direct 会被拒绝，从 direct 切入受限档会被自动压回 sandbox。仅建议明确需要系统级权限时**短时**开启，用完立即切回。切换后一直生效，没有自动回退机制。

### 各平台沙箱实现与安全水位（请务必阅读）

| 平台 | 实现 | 安全水位 |
|------|------|----------|
| **Windows** | WSL2 | **可以做到完全的数据隔离**——命令跑在独立的 WSL2 文件系统中。前提是**先自行安装 WSL2**，未安装时沙箱不可用 |
| **macOS** | sandbox-exec | **白名单读模型，读写都可限制**——进程默认只能读系统目录、工作区与已授权路径，越界读取会被直接拒绝。固有代价：授权路径的祖先目录顶层文件名可被列出（文件内容仍不可读） |
| **Linux** | bubblewrap (bwrap) + seccomp | 写入可限制（只读档全局只读），但**读侧仍是全局可读**、尚未对齐白名单；且尚未经过实际测试，不建议在生产环境依赖其隔离性 |

这是官方对当前安全能力的如实说明：把沙箱当作「防误操作」的手段，三个平台都是可靠的；把它当作「防恶意窃取数据」的手段，macOS（白名单）与 Windows（WSL2）可以信赖，Linux 暂时不行。

### 路径授权

host 模式下，沙箱的文件访问边界由路径授权决定，分两类：

- **可读可写路径**：AI 可以读也可以改；
- **仅可读路径**：AI 能看但不能改。

关系：`可读集合 = 可读可写 + 仅可读`；`可写集合 = 可读可写`。在输入栏 `+` 菜单 →「路径授权」中维护。推荐保持最小授权：工作区 + 临时目录。

> 终端会话（terminal 系列工具）的读写身份在启动时按当时的权限档、执行环境与沙箱策略**钉死**：受限档下终端以只读身份运行，`unrestricted` 下才是可写身份。**切换执行环境（sandbox ⇄ direct）、权限档在受限档与无限制之间互切、切换工作区或容器时，现有终端会话会被直接关闭**，随后在重新拉起的会话中按新策略执行。

### 网络权限

独立于文件沙箱的另一组开关（plan 模式下也可调）：

- **受限**（默认）：仅允许本地回环访问，外部网络不可达；
- **完全开放**：允许所有出站/入站连接。

## 4. 运行模式：AI 与你的交互节奏

运行模式控制 AI **什么时候动手、什么时候先问你**，与权限完全正交。仅空闲时可切换（任务运行中切换会收到 409 提示）。

- **plan（计划）**：只制定计划并与你讨论，不实际改东西。此模式下权限被**锁定为只读**、执行环境**锁定为沙箱**（UI 禁用 + 后端双重强制，网络权限除外）。唯一例外是写 `.astrion/plan/*.md` 计划文档。计划写完后 AI 会调用 `submit_plan` 请你批准；**批准即自动切换到 execute** 并恢复你之前的权限设置。
- **ask（询问）**：先讨论后开工。AI 把方案、疑问写在回复里与你来回确认，关键细节拍板后才动手。执行层面与 execute 无差异，只是交互节奏不同。
- **execute（执行）**：AI 自行梳理计划、补全细节，直接开工，只有遇到硬阻塞（缺信息、需要账号密码等）才提问。

### 常见组合

| 场景 | 推荐组合 |
|------|----------|
| 让 AI 改你正在维护的重要项目 | plan + approval + sandbox |
| 日常随手用、追求效率 | execute + auto_approval + sandbox |
| 纯问答/代码评审，绝不许动文件 | 任意模式 + readonly（执行环境自动锁沙箱） |
| 服务器多用户部署 | docker 模式（执行环境概念不适用） |

## 5. 四组概念的联动规则速查

1. plan 模式 → 权限强制 readonly、执行环境强制 sandbox（网络权限仍可调）；
2. 受限档权限（readonly/approval/auto_approval）→ 执行环境自动锁定为 sandbox，direct 仅 unrestricted 可用；
3. 批准 plan 计划 → 自动切 execute 并恢复进入 plan 前的权限与执行环境；
4. docker 模式下没有 sandbox/direct 之分，容器即边界；
5. 权限模式、执行环境、运行模式都是**对话级**状态：新对话继承当前输入栏的取值，个人空间里的「默认权限模式 / 默认运行模式」只影响首次构造。