112 lines
7.6 KiB
Markdown
112 lines
7.6 KiB
Markdown
# 核心概念
|
||
|
||
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 模式目前**没有**与宿主机同等的 OS 级只读沙箱机制。容器本身就是隔离边界，但「只读沙箱→审批→单次可写重试」这套两段式流程是 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（高风险）**：命令直接在宿主机执行，无任何沙箱限制。仅建议明确需要系统级权限时**短时**开启，用完立即切回。切换后一直生效，没有自动回退机制。
|
||
|
||
### 各平台沙箱实现与安全水位（请务必阅读）
|
||
|
||
| 平台 | 实现 | 安全水位 |
|
||
|------|------|----------|
|
||
| **Windows** | WSL2 | **可以做到完全的数据隔离**——命令跑在独立的 WSL2 文件系统中。前提是**先自行安装 WSL2**，未安装时沙箱不可用 |
|
||
| **macOS** | sandbox-exec | **能限制写入，但无法保证数据不泄露**——macOS 沙箱策略下文件系统对进程全局可读，AI 执行的命令仍可能读到你的私人文件。涉及敏感数据时请谨慎 |
|
||
| **Linux** | bubblewrap (bwrap) + seccomp | **尚未经过实际测试**，不建议在生产环境依赖其隔离性 |
|
||
|
||
这是官方对当前安全能力的如实说明：把沙箱当作「防误操作」的手段是可靠的；把它当作「防恶意窃取数据」的手段，目前只有 Windows（WSL2）路径可以信赖。
|
||
|
||
### 路径授权
|
||
|
||
host 模式下，沙箱的文件访问边界由路径授权决定，分两类：
|
||
|
||
- **可读可写路径**：AI 可以读也可以改；
|
||
- **仅可读路径**：AI 能看但不能改。
|
||
|
||
关系：`可读集合 = 可读可写 + 仅可读`；`可写集合 = 可读可写`。在输入栏 `+` 菜单 →「路径授权」中维护。推荐保持最小授权：工作区 + 临时目录。
|
||
|
||
> 终端会话（terminal 系列工具）在启动时绑定当时的执行环境与沙箱策略；**切换执行环境（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 权限 → 执行环境自动锁定为 sandbox（direct 无意义）；
|
||
3. 批准 plan 计划 → 自动切 execute 并恢复进入 plan 前的权限与执行环境；
|
||
4. docker 模式下没有 sandbox/direct 之分，容器即边界；
|
||
5. 权限模式、执行环境、运行模式都是**对话级**状态：新对话继承当前输入栏的取值，个人空间里的「默认权限模式 / 默认运行模式」只影响首次构造。
|