JOJO
56697a04ed
- 修复窄屏 git clone 块横向溢出撑破整页（hero-clone max-width + code 块内横滚） - 顶栏：移动端保留 GitHub 入口；Astrion 标题改为星空开关按钮（停 rAF + 隐藏画布，卡顿排查用） - 演示区：废弃 IntersectionObserver 懒加载，改为「点击预览」手动触发（移动端卡顿定位） - 文档：沙箱平台口径——macOS/Windows 已实测，Linux 未测试未适配暂不可用（02/05 章中英四份） Co-authored-by: Astrion powered by Kimi-K3 <astrion-agent@users.noreply.github.com>
112 lines
8.3 KiB
Markdown
112 lines
8.3 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 模式同样有只读强制——受限档权限（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 | **未测试、未适配、当前不可用**。Linux 服务器上部署多用户服务请使用 Docker 模式（容器隔离在 Linux 宿主上已实测生效），不要依赖宿主机沙箱 |
|
||
|
||
这是官方对当前安全能力的如实说明：把沙箱当作「防误操作」的手段，macOS 与 Windows 都是可靠的；把它当作「防恶意窃取数据」的手段，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. 权限模式、执行环境、运行模式都是**对话级**状态：新对话继承当前输入栏的取值，个人空间里的「默认权限模式 / 默认运行模式」只影响首次构造。
|