astrion-website/content/02-core-concepts.md

核心概念

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. 权限模式、执行环境、运行模式都是对话级状态：新对话继承当前输入栏的取值，个人空间里的「默认权限模式 / 默认运行模式」只影响首次构造。