From 1e3e6e2f6c6c2ca67ee2dd7de7b748c74133f463 Mon Sep 17 00:00:00 2001 From: JOJO <1498581755@qq.com> Date: Fri, 4 Sep 2026 03:02:53 +0800 Subject: [PATCH] =?UTF-8?q?chore:=20=E5=AE=98=E7=BD=91=E5=86=85=E5=AE=B9?= =?UTF-8?q?=E7=A7=BB=E5=87=BA=E6=9C=AC=E4=BB=93=E5=BA=93=EF=BC=88website-d?= =?UTF-8?q?esign/=E3=80=81website-content/=20=E5=81=9C=E6=AD=A2=E8=BF=BD?= =?UTF-8?q?=E8=B8=AA=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 官网已独立为 astrion-website 仓库（git.cyjai.com/JOJO/astrion-website）， 线上 https://astrion.cyjai.com。本仓库不再维护官网内容。 Co-authored-by: Astrion powered by Kimi-K3 --- .gitignore | 4 + website-content/01-quick-start.md | 241 ---------------------- website-content/02-core-concepts.md | 111 ---------- website-content/03-conversations.md | 76 ------- website-content/04-input-context.md | 89 -------- website-content/05-execution-security.md | 86 -------- website-content/06-conversation-assets.md | 68 ------ website-content/07-agent-capabilities.md | 156 -------------- website-content/08-quick-dock.md | 33 --- website-content/09-settings.md | 154 -------------- website-content/10-cli.md | 36 ---- website-content/README.md | 31 --- 12 files changed, 4 insertions(+), 1081 deletions(-) delete mode 100644 website-content/01-quick-start.md delete mode 100644 website-content/02-core-concepts.md delete mode 100644 website-content/03-conversations.md delete mode 100644 website-content/04-input-context.md delete mode 100644 website-content/05-execution-security.md delete mode 100644 website-content/06-conversation-assets.md delete mode 100644 website-content/07-agent-capabilities.md delete mode 100644 website-content/08-quick-dock.md delete mode 100644 website-content/09-settings.md delete mode 100644 website-content/10-cli.md delete mode 100644 website-content/README.md diff --git a/.gitignore b/.gitignore index d378e1bb..952698a0 100644 --- a/.gitignore +++ b/.gitignore @@ -103,3 +103,7 @@ test/deepseek_ocr_tutorial.md # 运行态缓存 cache/ website-design/exp/static/dist/ + +# 官网已独立为单独仓库（astrion-website），本仓库不再追踪 +website-design/ +website-content/ diff --git a/website-content/01-quick-start.md b/website-content/01-quick-start.md deleted file mode 100644 index 5b73edf9..00000000 --- a/website-content/01-quick-start.md +++ /dev/null @@ -1,241 +0,0 @@ -# 快速上手 - -本章带你从零跑起 Astrion：克隆代码、完成初始化配置、启动服务，并根据你的使用场景选择正确的运行形态。 - ---- - -## 1. 系统要求 - -| 依赖 | 要求 | 说明 | -|------|------|------| -| Python | 3.9 及以上（推荐 3.11） | 后端运行环境 | -| Node.js | 18 及以上 | 构建前端、使用 CLI | -| Docker | 可选 | 仅 **web/docker 模式**需要，host 模式不需要 | -| WSL2 | 仅 Windows | Windows 上使用宿主机沙箱的前置条件 | - -macOS、Linux、Windows（WSL2）均可运行。三平台沙箱能力的差异见《核心概念》一章。 - ---- - -## 2. 安装 - -```bash -# 1. 克隆仓库 -git clone https://github.com/JOJO6618/astrion.git -cd astrion - -# 2. 初始化：创建 venv、安装依赖、运行交互式配置向导 -# 向导会依次询问：运行模式 → 监听地址/端口 → 管理员账户 → 模型 API → 生成密钥 -./setup.sh - -# 3. 构建前端 -npm install && npm run build - -# 4.（仅 web/docker 模式）构建沙箱镜像，见下文「选择运行模式」 -docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest . - -# 5. 启动 -./start.sh -# 或者手动启动： -python -m server.app --port 8091 --thinking-mode -``` - -启动后访问 `http://localhost:8091`，用向导中设置的管理员账户登录。 - -> `setup.sh` 向导会把配置写入仓库根目录的 `.env`。这是开发备用方式；生产部署建议改用「数据根目录下的 `settings.json`」或系统环境变量，见下文「配置优先级」。 - ---- - -## 3. 运行端口与监听地址 - -- **默认端口：`8091`**（`WEB_SERVER_PORT`）。 -- 监听地址（`WEB_SERVER_HOST`）： - - 单机自用：建议 `127.0.0.1`，只监听本机回环，局域网不可达； - - 多用户/服务器部署：用 `0.0.0.0`。 -- 启动命令行参数 `--port` 可以临时覆盖配置。 -- 调试模式 `WEB_SERVER_DEBUG=1`（同时开启 Flask reloader），生产环境保持 `0`。 - ---- - -## 4. 数据路径：数据都存在哪、怎么搬迁 - -Astrion 的运行态数据（对话记录、用户、日志、部署级配置）**默认全部放在用户主目录下，不污染源码树**： - -``` -~/.astrion/astrion/ ← 数据根目录（data_root） -├── settings.json ← 唯一配置文件（优先级最高） -├── config/ ← 部署级配置（模型库等，host/web 共享） -├── host/ ← host 模式的数据 -│ ├── data/ users/ logs/ api/ -└── web/ ← web/docker 模式的数据（结构同上） -``` - -按运行模式自动分流：`TERMINAL_SANDBOX_MODE=host` 时数据进 `host/`，否则进 `web/`。 - -### 路径相关环境变量（优先级从高到低） - -| 环境变量 | 作用 | -|----------|------| -| `DATA_DIR` / `LOGS_DIR` / `USER_SPACE_DIR` / `API_USER_SPACE_DIR` | 单独覆盖某一个目录（最高优先级） | -| `ASTRION_DATA_ROOT` | 整体搬迁数据根目录（默认 `~/.astrion/astrion`） | -| `DEPLOY_CONFIG_DIR` | 单独搬迁部署级配置目录（默认 `<数据根>/config/`） | - -具体目录变量支持相对路径（相对仓库根目录展开）、绝对路径与 `~`。 - -### 配置优先级 - -同名配置生效顺序：**`<数据根>/settings.json` ＞ 系统环境变量 ＞ 仓库根目录 `.env` ＞ 代码默认值**。 - -`.env` 加载时不覆盖已存在的系统环境变量；`settings.json` 是推荐的生产配置方式，例如： - -```json -{ - "server": { "port": 8091, "host": "127.0.0.1" } -} -``` - ---- - -## 5. 配置主智能体模型 - -主智能体的模型统一在 **`custom_models.json`** 中注册。 - -**放置位置**（按回退链查找，找到即止）： - -1. `<数据根>/config/custom_models.json`（生产推荐） -2. 仓库内 `config/custom_models.json` -3. 仓库内 `config/custom_models.json.example`（种子示例） - -**完整字段说明**： - -```json -{ - "models": [ - { - "model_name": "Kimi-K3", - "description": "展示给用户的模型描述", - "visible": true, - "url": "${API_BASE_KIMI}", - "apikey": "${API_KEY_KIMI}", - "multimodal": "image,video", - "reasoning_capability": "fast,thinking", - "reasoning_effort": true, - "context_window": 1048576, - "max_output_tokens": 64000, - "thinkmode_status": { - "type": "param_toggle", - "model_id": "k3", - "fast_extra_parameter": { "thinking": { "type": "disabled" } }, - "thinking_extra_parameter": { "thinking": { "effort": "max" } } - }, - "extra_parameter": {}, - "model_description": "注入系统提示词的模型自我描述" - } - ] -} -``` - -| 字段 | 必填 | 说明 | -|------|------|------| -| `model_name` | ✅ | 模型条目名，UI 中显示，也是各配置引用它的 key | -| `url` | ✅ | API 基础地址。**支持 `${环境变量}` 引用**，密钥不要写明文 | -| `apikey` | ✅ | API Key，同样支持 `${...}` | -| `description` | | 列表中展示的说明文字 | -| `visible` | | 是否在模型选择菜单中可见 | -| `multimodal` | | `image,video` 等；决定输入栏是否允许发图/视频 | -| `reasoning_capability` | | `fast,thinking`；决定思考模式可选项 | -| `reasoning_effort` | | 是否支持「推理强度」滑块 | -| `context_window` | | 上下文窗口大小（token），压缩阈值、用量统计以此为基准 | -| `max_output_tokens` | | 单次最大输出 token | -| `thinkmode_status` | | `param_toggle` 类型：`model_id` 为真实模型 ID；`fast/thinking_extra_parameter` 为两种模式下分别附加的请求参数 | -| `extra_parameter` | | 所有请求都附加的额外参数 | -| `model_description` | | 注入系统提示词的自我介绍 | - -**最小配置**只需要 4 个字段：`model_name` / `url` / `apikey` / `thinkmode_status.model_id`，其余字段均有默认值。 - -> 提醒：`setup.sh` 向导在第 5 步创建的模型条目就是最小配置——`multimodal` 为 `none`（不能发图/视频）、`context_window` 固定 128000、`max_output_tokens` 32768。如果你的模型支持多模态或更大上下文，配完向导后请手动编辑 `<数据根>/config/custom_models.json` 补齐字段。 - -**默认模型**：不设 `AGENT_DEFAULT_MODEL` 时使用列表中第一个可见模型；也可以在个人空间「模型与思考」页设置每用户默认模型。 - -> 注意：旧版的 `AGENT_API_*` / `AGENT_THINKING_*` / `AGENT_TITLE_*` 环境变量已从代码中移除，配置它们不再有任何效果。 - ---- - -## 6. 配置子智能体模型 - -子智能体（含三个审核智能体）使用**独立的模型库**：`sub_agent_models.json`。 - -**放置位置**：仅从部署配置目录读取——`<数据根>/config/sub_agent_models.json`（可用 `SUB_AGENT_MODELS_CONFIG_FILE` 单独覆盖）。**没有这个文件，子智能体将无法启动**，会直接报「未找到可用子智能体模型配置」。 - -**结构**： - -```json -{ - "default_model": "deepseek-v4-flash", - "models": [ - { - "name": "deepseek-v4-flash", - "url": "${SUB_AGENT_API_BASE}", - "apikey": "${SUB_AGENT_API_KEY}", - "model_id": "deepseek-v4-flash", - "modes": "fast,thinking", - "multimodal": "image", - "max_output": 32000, - "max_context": 128000, - "extra_parameter": {}, - "fast_extra_parameter": {}, - "thinking_extra_parameter": {} - } - ] -} -``` - -要点： - -- `default_model`：默认条目名；子智能体/审核智能体配置里 `model` 留空时用它。若指定的名字不存在，回退到列表中第一个可用条目。 -- 字段名做了宽松兼容：`name`/`model_name`/`model`、`url`/`base_url`、`apikey`/`api_key` 均可；`modes` 写 `fast,thinking` 表示支持思考模式，只写 `fast` 表示纯快速模式。 -- 也支持与主模型库相同的 `thinkmode_status` 结构，可以直接从 `custom_models.json` 复制条目改名字用。 -- `url` / `apikey` 同样支持 `${环境变量}` 引用。 - -**子智能体相关环境变量**： - -| 变量 | 默认 | 说明 | -|------|------|------| -| `SUB_AGENT_MAX_ACTIVE` | 5 | 同时运行的子智能体上限 | -| `SUB_AGENT_DEFAULT_TIMEOUT` | 180（秒） | 默认超时 | -| `SUB_AGENT_TASKS_BASE_DIR` | `<数据根>/<模式>/data/sub_agent_tasks` | 任务目录 | -| `SUB_AGENT_PROJECT_RESULTS_DIR` | `<工作区>/sub_agent_results` | 交付目录（有意放在工作区内） | - ---- - -## 7. 选择运行模式：host 还是 docker（web） - -由 `TERMINAL_SANDBOX_MODE` 决定，两种模式面向完全不同的场景： - -| | **host 模式** | **web/docker 模式** | -|---|---|---| -| 定位 | 本地个人使用 | 服务器多用户部署 | -| 命令执行 | 宿主机 OS 沙箱（macOS sandbox-exec / Linux bwrap / Windows WSL2） | 每个用户独立 Docker 容器，受限档权限下以非特权 uid 执行 | -| 数据目录 | `~/.astrion/astrion/host/` | `~/.astrion/astrion/web/` | -| 前置准备 | 无需镜像；Windows 需先装 WSL2 | 必须先构建镜像：`docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .`（构建上下文必须是仓库根） | -| 镜像名 | — | 由 `TERMINAL_SANDBOX_IMAGE` 指定，建议 `my-agent-shell:latest` | - -选择建议： - -- **一个人在自己电脑上用** → `host`。文件管理器、本地工具链直接可用，体验最好。 -- **部署到服务器给多人用** → `docker`。容器天然隔离用户之间的文件与进程。 -- host 模式可以同时读取 web 模式的数据（用户列表、工作区合并显示），反向不行。 - -沙箱镜像基于 `python:3.11-slim`，内置 LibreOffice / Pandoc / FFmpeg / Tesseract OCR（含中文）/ Chromium / Node 20 / docx / pptxgenjs 等常用工具链。**程序不会自动构建镜像**，web 模式启动前必须手动构建一次。 - ---- - -## 8. 首次启动检查清单 - -1. 浏览器打开 `http://localhost:8091`，用管理员账户登录； -2. 进入个人空间，确认「模型与思考」页能看到你配置的模型； -3. 随便发一条消息，确认主智能体能正常回复； -4. 让主智能体创建一个子智能体（或直接说「帮我查一下 xxx」触发），确认 `sub_agent_models.json` 配置正确； -5. 若是 web 模式，确认镜像已构建、终端容器能正常拉起。 - -到这里，你的 Astrion 已经可以正常工作了。接下来建议阅读《核心概念》，理解部署模式、权限模式、执行环境、运行模式这四组概念——它们决定了 Astrion 的行为边界。 diff --git a/website-content/02-core-concepts.md b/website-content/02-core-concepts.md deleted file mode 100644 index 15711fe7..00000000 --- a/website-content/02-core-concepts.md +++ /dev/null @@ -1,111 +0,0 @@ -# 核心概念 - -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. 权限模式、执行环境、运行模式都是**对话级**状态：新对话继承当前输入栏的取值，个人空间里的「默认权限模式 / 默认运行模式」只影响首次构造。 diff --git a/website-content/03-conversations.md b/website-content/03-conversations.md deleted file mode 100644 index 6c9c40e5..00000000 --- a/website-content/03-conversations.md +++ /dev/null @@ -1,76 +0,0 @@ -# 对话 - -本章讲「一个对话」本身的能力：对话类型、思考模式、目标模式，以及对话过程中可用的几个面板功能。 - ---- - -## 1. 对话类型：普通 vs 多智能体 - -创建对话时选定，**创建后不可变**： - -- **普通对话（智能体）**：你与一个主智能体对话，它可以按需在后台派出子智能体干活。 -- **多智能体对话**：主智能体固定为 **Team Leader**，不亲自干活，而是创建多个带角色的子智能体（如 Full-Stack Engineer、UI Operator），在它们之间派活、收汇报、做决策。子智能体之间也可以互相通信，但每次沟通都会同步汇报给 Team Leader，不存在"私下串通"。 - -切换入口：空对话时输入栏底行 `+` 右侧的对话类型选择器；侧边栏的列表过滤器则决定你在列表里看哪一类对话。 - -多智能体的完整玩法见《智能体能力》一章。 - -## 2. 思考模式与推理强度 - -两个独立开关，都作用于当前对话： - -- **思考模式**：`快速（fast）` / `思考（thinking）`。快速模式追求响应速度、跳过思考过程；思考模式整轮对话使用思考模型。输入栏可切换，个人空间可设默认值。 -- **推理强度（Effort）**：`默认 / 低 / 中 / 高` 滑块（需模型配置里 `reasoning_effort: true` 才会出现）。「默认」表示不指定强度，使用 API 自身默认行为；拖动滑块可实时调整思考的深度档位。 - -> 模型的多模态能力（能否发图片/视频）由 `custom_models.json` 中该模型的 `multimodal` 字段决定；思考模式可选项由 `reasoning_capability` 决定。 - -## 3. 目标模式（Beta） - -> ⚠️ 目标模式是 **beta 功能**：机制完整可用，但边界情况（多对话并发时的 token 统计、异常中断恢复等）仍在打磨，请带着预期使用并反馈问题。 - -普通对话里，AI 完成你交代的一轮任务就停了。**目标模式**让 AI 围绕一个长期目标**自动一轮一轮干下去**，直到目标达成或触顶停止。 - -**用法**： - -1. 输入栏 `+` 菜单 →「目标模式」，进入「已就绪」状态； -2. 你发送的下一条消息会被当作**目标**（而不是普通任务）； -3. AI 围绕目标自动连续工作：每轮结束后自我评估「目标达成了吗」，没达成就继续下一轮； -4. 达成、触顶或你手动取消时停止。 - -**结束条件**（个人空间可配，可多选）： - -- `max_turns`：最多自动续 N 轮（有默认值，可调）； -- `max_tokens`：累计（输入+输出）token 上限，默认不启用。注意该统计是**工作区级**的，多对话并发时是近似值。 - -**目标审核**：可选配一个目标审核智能体（个人空间「审核智能体」页的 `goal_review`），两种审核模式： - -- `readonly`（默认）：审核智能体只读对话内容来判断目标进度； -- `active`：允许它跑只读命令取证（比如检查文件是否真的生成了）再下结论。 - -目标状态按对话独立持久化（`goal_states/<对话ID>.json`），切换对话、上下文压缩、重启服务都不会丢失目标进度。 - -## 4. 对话面板：回顾 / 用量 / 实时终端 - -输入栏 `+` 菜单里的三个面板型功能（它们只是信息面板，**与安全机制无关**）： - -- **对话回顾**：打开当前对话的回顾视图，按时间线回看这次对话做了什么。 -- **用量统计**：上下文与 token 用量面板，看当前对话的上下文占用、累计消耗。 -- **实时终端**：打开实时终端面板，直接看到 AI 正在执行的终端会话实况——它正在跑什么命令、输出是什么。这是观察窗口，不是安全边界；真正的安全控制请看《执行与安全》。 - -## 5. 对话管理 - -- **搜索**：侧边栏顶部搜索框，按标题与内容检索对话。 -- **平铺 / 分组视图**：侧边栏可以平铺所有对话，也可以按工作区分组（个人空间「外观与显示」→ 侧边栏分组）。分组模式下支持工作区置顶与排序。 -- **类型过滤**：侧边栏的类型切换器（普通 / 多智能体）决定列表里显示哪类对话。 -- **新建对话按钮行为**：个人空间可选——点击 `+` 是「跳转到空白新对话页」（route）还是「立即创建空对话」（blank）。 -- **自动标题**：默认开启，首轮对话后自动生成标题；可在个人空间关闭。 - -## 6. 对话显示模式 - -个人空间「外观与显示」提供三种消息流显示模式： - -- **传统列表**：所有消息平铺； -- **堆叠动画**（默认）：工具调用等中间块堆叠收纳，主干对话更清爽； -- **极简模式**：最克制的显示，只看要点。 - -另有「完整信息 / 简略信息」控制简略消息的展开程度，以及助手状态形象（戳一戳有彩蛋）等显示开关。 diff --git a/website-content/04-input-context.md b/website-content/04-input-context.md deleted file mode 100644 index 4ffa33aa..00000000 --- a/website-content/04-input-context.md +++ /dev/null @@ -1,89 +0,0 @@ -# 输入与上下文 - -本章讲输入栏的两个菜单、文件引用、上传，以及 Astrion 的上下文管理体系——包括压缩机制的正确用法。 - ---- - -## 1. `+` 快捷菜单（完整功能清单） - -点击输入栏左侧 `+` 打开。完整功能一览： - -| 功能 | 说明 | -|------|------| -| 新建对话 | 开始一个新对话（等价 `new` / `clear`） | -| 上传文件 | 选择本地文件上传到工作区 | -| 发送图片 / 发送视频 | 附加到消息；**当前模型不支持多模态时禁用**（取决于 `multimodal` 配置） | -| 压缩对话 | 手动触发一次上下文压缩 | -| 选择 AgentSkill | 插入一个 Skill 引用（等价输入 `//` 快捷直达） | -| 工作流 | 激活一个工作流，让智能体按既定流程推进 | -| 对话类型 | 空对话时切换「智能体 / 多智能体」（创建后不可变） | -| 切换工作模式 | plan / ask / execute | -| 切换主题 | 经典 / 明亮 / 夜间 | -| 对话回顾 | 打开当前对话回顾 | -| 用量统计 | 上下文与 token 用量面板 | -| 目标模式 | 切换目标模式（Beta，见《对话》章） | -| 个人设置 | 打开个人空间 | -| 实时终端 | 打开实时终端面板 | -| 切换模型 | 选择本对话使用的模型 | -| 思考模式 | 切换 fast / thinking | -| 权限模式 | 切换 readonly / approval / auto / unrestricted | -| 网络权限 | 受限 / 完全开放（plan 模式下也可调） | -| 执行环境 | sandbox / direct（仅 host 模式） | -| 切换工作区 / 项目 | 切换当前对话绑定的工作区 | -| 版本控制 | 开/关本对话的版本控制 | -| Git 状态栏 | 显示/隐藏输入栏上方的 Git 状态条 | -| 路径授权 | 查看和管理沙箱路径授权 | -| 审批面板 | 查看审批记录 | - -## 2. `/` 斜杠菜单 - -在输入框输入 `/` 触发斜杠直达菜单，用关键字快速过滤并直达某一类选项，目前支持 12 类：AgentSkills（`//` 直达）、工作流、主题、权限模式、执行环境、模型、思考模式、网络权限、工作模式、工作区、对话类型等。 - -典型用法：`/skill` 选技能、`/workflow` 选工作流、`/model` 切模型——比在 `+` 菜单里翻要快。 - -## 3. `@` 文件引用 - -输入 `@` 唤起文件菜单，从工作区中选择文件/目录插入引用。被引用的文件会作为上下文提供给智能体，适合「就这个文件展开讨论」的场景。图片类文件引用会按多模态能力处理。 - -## 4. 上下文压缩：浅压缩与深压缩 - -长对话迟早会触及模型上下文上限，Astrion 提供两级自动压缩 + 手动压缩： - -### 浅压缩（默认关闭） - -- 机制：把较早的**工具调用结果替换为占位符**（保留最近 N 个工具结果不压），立刻腾出空间。 -- 触发：默认累计 80k tokens 触发（可调），另有「每 N 次工具调用」「每轮最多替换 N 个」「保留最近 N 次用户输入后的工具不压」等细调参数。 -- ⚠️ **重要代价：浅压缩会改动历史消息内容，从而破坏服务商侧的上下文缓存（prompt cache）**——压缩后的几轮请求将无法命中缓存，表现为响应变慢、费用上升。这是它默认关闭的原因。 - -### 深压缩（默认开启，推荐） - -- 机制：对整段历史做**深度总结**，旧上下文整体替换为浓缩摘要后轻装继续。 -- 产物形式可选（`deep_compress_form`）：`file`——总结写入文件，需要时随时回读（默认）；`inject`——直接把总结全文注入上下文。 -- 触发：默认 150k tokens。 - -### 自定义阈值的 80% 规则（务必遵守） - -如果你要自定义压缩触发阈值，**至少设为所用模型实际可用上下文的 80%**。 - -例如模型实际上下文是 128k，触发阈值不应低于约 102k。阈值设得太低会频繁触发压缩：既浪费 token，又频繁破坏上下文缓存，还会让 AI 过早丢失细节记忆。让对话尽量「用满窗口再压缩」才是性价比最高的用法。 - -> 模型的实际上下文窗口以 `custom_models.json` 中该模型的 `context_window` 为准；注意区分「标称上下文」与「实际可用上下文」（部分 API 会预留输出空间）。 - -### 手动压缩 - -`+` 菜单 →「压缩对话」随时可手动触发，适合你预判接下来要开新话题、主动腾空间的场景。 - -## 5. 上下文注入类功能 - -这些功能影响每轮对话自动携带的上下文，都在个人空间配置： - -- **最近对话提示**（默认关闭）：开启后，新对话自动把最近 N 条历史对话的摘要注入上下文（N 可配，1–30，默认 10）。适合「我最近一直在折腾同一个项目」的连续工作流；与「对话连续性」个性化设置配合使用。 -- **AGENTS.md 自动注入**（默认关闭）：开启后自动把项目根目录的 AGENTS.md 注入上下文，让 AI 始终带着项目规范工作。 -- **项目记忆索引注入**：AI 的项目记忆索引默认最多注入 20 条（5 起，可设为无上限）。记忆内容由 AI 在工作过程中主动沉淀。 -- **Skill 提示**（默认关闭）：根据当前任务动态提示可能相关的 Skill。 - -## 6. 上传与多模态 - -- **上传文件**：进入工作区，AI 后续可读取处理； -- **发送图片/视频**：随消息直接进入多模态上下文； -- 图片压缩档位（个人空间）：`原图 / 1080p / 720p / 540p`，默认原图。长对话里多发大图建议降档，节省上下文。 diff --git a/website-content/05-execution-security.md b/website-content/05-execution-security.md deleted file mode 100644 index 64ec270b..00000000 --- a/website-content/05-execution-security.md +++ /dev/null @@ -1,86 +0,0 @@ -# 执行与安全 - -本章讲 Astrion 如何安全地执行 AI 发起的操作：沙箱执行的实际行为、路径授权、审批机制。概念层面的四组开关（部署/权限/执行环境/运行模式）请先看《核心概念》，本章聚焦具体行为与日常管理。 - -> 范围说明：「实时终端」只是观察面板，与安全机制无关，见《对话》一章。 - ---- - -## 1. 命令是怎么被执行的 - -### run_command：两段式执行 - -以默认推荐的 `approval` 模式为例，一条 AI 发起的 shell 命令的实际旅程是： - -1. **先在只读身份下执行**——能读不能写（host 模式靠 OS 沙箱，docker 模式靠容器内的非特权用户）； -2. 如果命令没碰写操作，直接返回结果，全程无感； -3. 如果触发权限拒绝（要写文件、要改系统），**自动转为向你发起审批**； -4. 你批准后，**仅这一条命令**以可写身份重试；你拒绝或超时未处理，则本次不执行； -5. AI 拿到的是最终结果，中间过程不干扰它的思路。 - -`auto_approval` 模式把第 3 步的审批者换成自动审批智能体；`unrestricted` 模式跳过审批直接执行；`readonly` 模式下写入类请求直接拒绝。注意审批**只放大这一次写入、不放大读取范围**——想读工作区之外的文件，唯一途径是路径授权（见第 2 节）。 - -### 终端会话：身份钉死，切换即关闭 - -持久终端会话（terminal 系列工具）的读写身份在启动时按当时的权限档、执行环境与沙箱策略**钉死**：受限档（readonly/approval/auto_approval）下终端以只读身份运行，终端里的写入由系统直接拒绝（EPERM）；`unrestricted` 下才是可写身份。当你**切换执行环境（sandbox ⇄ direct）、权限档在受限档与无限制之间互切、切换工作区或容器**时，现有终端会话会被**直接关闭**——不会带着旧身份继续运行，后续操作在重新拉起的会话中按新策略执行。这也意味着：跑长任务时不要切换这些开关，任务会随会话一起终止。 - -### 子智能体与后台命令 - -子智能体的终端进程同样经过执行环境策略：sandbox 下经宿主机沙箱启动，direct 下直接宿主机启动；docker 模式则在容器内执行。后台命令（`run_in_background`）与前台命令走同一套只读/可写沙箱判定，**不会因为放后台就绕过权限**。 - -## 2. 路径授权的日常管理 - -入口：输入栏 `+` 菜单 →「路径授权」。 - -- **可读可写路径**：AI 的完整工作范围，通常就是你的项目目录； -- **仅可读路径**：允许 AI 参考但禁止修改，比如参考文档、线上配置样例、别的项目源码。 - -建议实践： - -1. 保持最小授权——只加当前任务需要的目录； -2. 敏感目录（`~/.ssh`、密钥库、系统目录）永远不要加入任何一类； -3. 任务性质变化时及时调整，授权是即时生效的（新终端会话除外，见上）。 - -## 3. 网络权限 - -输入栏权限菜单中独立的一组： - -- **受限**（默认）：仅本地回环，AI 无法访问外部网络——适合纯本地任务，也杜绝了数据外发； -- **完全开放**：允许出站/入站连接——需要 AI 联网搜索、调外部 API、装依赖时开启。 - -网络权限与文件沙箱相互独立，且在 plan 模式下也可调整。 - -## 4. 审批面板 - -入口：`+` 菜单 →「审批面板」。这里能看到审批记录：哪些命令/写入被提请审批、谁批的（人工或自动审批智能体）、结果如何。`auto_approval` 模式下如果不想让面板自动弹出打扰，个人空间有开关（默认不自动打开）。 - -## 5. 禁止命令清单 - -部署级配置 `forbidden_commands.json`（放 `<数据根>/config/`）可以配置**绝对禁止执行的命令特征**，命中即拒，与权限模式无关。这是兜底防线，适合在服务器部署时封死 `rm -rf /`、`shutdown` 这类命令。 - -## 6. 关于 direct 模式的忠告 - -`direct` = 命令直接在宿主机执行，**没有任何沙箱**。它与受限档权限（readonly/approval/auto_approval）硬互斥——只有 `unrestricted` 才能选 direct，从 direct 切入受限档时会被自动压回 sandbox。合理使用场景只有一个：某条命令在沙箱里确实跑不了（需要系统级权限），且没有替代方案。此时： - -1. 先把权限档切到 `unrestricted`，再临时切到 direct； -2. 跑完立即切回 sandbox（和原来的权限档）； -3. 注意 direct 切换后**永久生效、不会自动回退**——忘记切回等于长期裸奔。 - -## 7. docker 模式的安全现状 - -docker 模式下，用户之间的隔离边界是容器本身：每个用户的终端在独立容器中，互相不可见。容器**内部**的权限约束同样是真强制： - -- 受限档（readonly/approval/auto_approval）下，run_command、后台命令与持久终端都以**非特权用户（uid 10001）**在容器内执行——工作区属主是 root，写入由内核文件权限直接拒绝，不依赖对命令文本的识别；审批通过后，仅该条命令以 root 身份重试； -- 生效前提：工作区属主为 root、没有全局可写的文件、容器未挂载 docker.sock（按官方部署文档操作即满足）； -- 该强制仅在 **Linux 宿主机**上成立——macOS 本机的 Docker Desktop 不执行 uid 文件权限，本机开发时不要把容器内部权限当安全边界； -- 多用户部署时应配合容器资源限制、镜像最小化等常规容器安全实践。 - -## 8. 各平台安全水位 - -再次强调《核心概念》中的结论，因为它直接影响你该信任沙箱到什么程度： - -- **Windows（WSL2）**：可做到完全数据隔离，需先安装 WSL2； -- **macOS（sandbox-exec）**：白名单读模型，写入和读取都可限制——进程默认只能读系统目录、工作区与已授权路径；代价是授权路径的祖先目录顶层文件名可被列出（文件内容仍不可读）； -- **Linux（bwrap+seccomp）**：写入可限制，但读侧仍是全局可读、尚未对齐白名单，且**尚未实测**，不要依赖其隔离性。 - -无论哪个平台，沙箱的首要价值是**防误操作**；涉及真正的敏感数据，请叠加路径授权最小化、网络受限、readonly 权限等手段综合防护。 diff --git a/website-content/06-conversation-assets.md b/website-content/06-conversation-assets.md deleted file mode 100644 index 04a56185..00000000 --- a/website-content/06-conversation-assets.md +++ /dev/null @@ -1,68 +0,0 @@ -# 对话资产管理 - -AI 改了你工作区的文件之后，「改了什么、怎么回滚、坏到哪一版」就是核心问题。Astrion 提供三层资产保障：**版本控制**（对话级检查点）、**修改留痕**（任务级 diff）、**Git 状态栏**（实时感知）。它们相互独立、可叠加使用。 - ---- - -## 1. 版本控制 - -对话级的文件检查点系统，让 AI 的每一轮改动都有快照可回退。 - -### 开关与备份方式 - -- 新对话**默认开启**（个人空间可改默认值）； -- 单个对话可在 `+` 菜单 →「版本控制」临时开关； -- 备份方式二选一（个人空间）： - - **浅备份（默认）**：只追踪 AI 通过 **write_file / edit_file** 编辑的文件，每次编辑前自动备份当前内容——快、省空间，绝大多数场景够用。⚠️ 注意边界：**AI 用 run_command 执行命令改动的文件（如 sed、重定向、脚本写入）不在浅备份的追踪范围内**； - - **完全备份**：整工作区快照——最稳，但大项目下会明显变慢占空间。 - -### 检查点粒度：每条用户消息 - -- 你**每手动发送一条消息**，系统在该消息处理完成后记录一个检查点，引用当时所有已追踪文件的最新备份版本——也就是说，回溯的最小颗粒度是「一次用户手动发送的消息」，而不是单个文件编辑； -- 查看某个检查点的 diff = 该消息快照与上一条消息快照之间的差异； -- **回滚**到某个检查点 = 把所有已追踪文件恢复到该消息时的状态（覆盖式，回滚前请确认当前改动已另存或已提交）。 - -### 与其他机制的关系 - -- 版本控制追踪的是**文件系统状态**，与对话消息无关； -- 它与 Git 不冲突：AI 不会替你 commit，版本控制是 Git 之外的另一张安全网，适合「还没来得及 commit 就被改坏了」的场景。 - -## 2. 修改留痕（modify history） - -任务级的净修改记录，**默认开启**。 - -- 每完成一轮任务，本轮对话中 AI 编辑过的全部文件以 **unified diff** 形式落盘到：`<工作区>/.astrion/modify_history/<对话ID>/`； -- 每个任务一个 `.diff` 文件，文件名含该任务的用户输入摘要与开始时间； -- 对话中的「编辑摘要卡片」展示本轮编辑过的文件列表，点击可查看 diff；卡片的显示时机可在个人空间配置（默认工作完成后显示，也可改为运行期间实时显示）。 - -### 用 diff 文件手工恢复 - -留痕文件可直接用 git 工具操作： - -```bash -cd <工作区> -git apply # 重做这次修改 -git apply -R # 撤销这次修改 -``` - -典型场景：版本控制没开、Git 没 commit、`git checkout` 误覆盖了 AI 的劳动成果——去 modify_history 里找到对应任务的 diff，`git apply` 即可恢复。 - -> 该目录由系统自动维护，请勿手工增删其中文件；可在个人空间整体关闭（关闭后既不落盘也不注入提示）。 - -## 3. Git 状态栏 - -输入栏上方的状态条，实时显示当前工作区的 Git 状态摘要（当前分支、未提交改动量等），让你在不离开对话的情况下掌握「工作区现在脏不脏、AI 改了多少」。 - -- 默认显示；`+` 菜单 →「Git 状态栏」可快速显隐，个人空间有同款设置项； -- 工作区不是 Git 仓库时不显示。 - -## 4. 三层机制怎么选 - -| 需求 | 用哪层 | -|------|--------| -| 实时感知工作区改动 | Git 状态栏 | -| 回滚到对话中的某个时间点 | 版本控制 | -| 精确恢复/撤销某一轮任务的修改 | 修改留痕 diff | -| 长期、严肃的规模开发 | 仍然要 Git commit——前三级都是安全网，不是版本管理的替代品 | - -推荐姿势：重要项目保持「版本控制开 + 修改留痕开 + 勤 commit」，三张网叠加，AI 怎么折腾都丢不了东西。 diff --git a/website-content/07-agent-capabilities.md b/website-content/07-agent-capabilities.md deleted file mode 100644 index b3675cda..00000000 --- a/website-content/07-agent-capabilities.md +++ /dev/null @@ -1,156 +0,0 @@ -# 智能体能力 - -Astrion 的智能体能力分五块：**子智能体**（主智能体派出的分身）、**多智能体对话**（一个角色团队）、**工作流**（既定流程模板）、**Skills**（专业技能包）、**MCP**（外部工具接入）。本章讲每块怎么用、怎么配。 - ---- - -## 1. 子智能体 - -### 是什么 - -子智能体是主智能体在**同一进程内**派出的独立执行体：有自己的上下文、自己的模型配置、独立的生命周期。主智能体用它来**并行处理相互独立的任务**——典型场景：同时调研三个技术方案、边跑测试边整理文档。 - -它**不适合**什么：子智能体之间无法通信、看不到主对话历史，所以协作型任务（A 的输出是 B 的输入）应顺序执行或交给一个子智能体完成。代码编写/修改类任务默认由主智能体亲自完成。 - -### 怎么用 - -通常你不需要直接操作——告诉主智能体「同时帮我做 X 和 Y」，它会自己判断拆分成子智能体。两种运行方式： - -- **前台（阻塞）**：主智能体停下来等它完成，适合快任务、后续依赖结果的场景； -- **后台**：主智能体继续干活或与你聊天，子智能体完成后系统自动通知。 - -你可以通过对话区右侧**快捷窗口的「子智能体」窗**实时查看每个子智能体的状态与输出（见《快捷窗口》）。 - -### 生命周期与限制 - -- 状态：`running`（运行中）→ `idle`（空闲，上下文保留，可继续对话）/ 终态（完成/失败/超时/终止）； -- 并发上限默认 **5**（`SUB_AGENT_MAX_ACTIVE`）； -- 默认超时 **180 秒**，创建时可为单个任务指定更长超时（大规模分析建议 1800 秒以上）； -- 产出物约定放在工作区 `sub_agent_results/` 下。 - -### 怎么配（模型库） - -子智能体使用独立模型库 `sub_agent_models.json`，配置方法见《快速上手》第 6 节。创建单个任务时主智能体可指定：模型条目、思考模式、超时、最大轮数等。不配则用 `default_model` 条目。 - -## 2. 多智能体对话 - -### 是什么 - -一种**对话类型**（创建时选定，不可变）：主智能体固定为 Team Leader，负责理解你的需求、拆解任务、创建并指挥一组**带角色的子智能体**，汇总它们的产出。 - -### 角色系统 - -预置 5 个角色： - -| 角色 | 职责 | -|------|------| -| Full-Stack Engineer | 前后端代码实现、接口设计、调试联调 | -| UI Operator | 界面操作与视觉验证 | -| Code Reviewer | 代码审查 | -| Researcher | 调研与信息收集 | -| Brainstormer | 头脑风暴与方案发散 | - -角色 = `角色ID + 实例编号`，显示名如 `Full-Stack Engineer_1`，编号按角色内递增。 - -**自定义角色**：个人空间里有角色编辑器（角色列表 → 新建/编辑）。角色定义是一个带元信息的 Markdown 文件： - -```markdown ---- -id: full-stack-engineer # 角色ID -name: Full-Stack Engineer # 显示名 -description: 职责一句话 # Team Leader 据此派活 -model: "" # 指定模型（留空用子智能体模型库默认） -thinking_mode: thinking # fast / thinking ---- - -（正文是该角色的系统提示词：职责、工作原则、约束……） -``` - -### 通信机制（用起来需要知道的） - -- Team Leader 给子智能体发消息有两种：**派活**（不阻塞，继续干别的）和**询问**（阻塞等它回一轮）； -- 子智能体之间可以互相请教/回答，但**所有子间通信都会同步汇报给 Team Leader**； -- 子智能体每一轮输出都会实时汇报给 Team Leader 并展示在对话流里，你可以随时插话纠偏。 - -### 什么时候用多智能体 - -适合：一个小型项目需要「写代码的 + 审代码的 + 跑界面的」分工协作；不适合：单线程就能干完的任务（徒增协调开销）。 - -## 3. 工作流 - -### 是什么 - -把一套**既定流程**（阶段、审核点、分支、结束方式）写成 `WORKFLOW.md` 存为模板；激活后，智能体严格按流程逐阶段推进，每个阶段完成后向你或审核智能体汇报，审核通过才进入下一阶段。 - -### 怎么用 - -- 激活：`+` 菜单 →「工作流」，或输入 `/workflow` 选择； -- 推进：每个阶段完成后 AI 自动汇报并进入下一阶段（含审核节点时由审核智能体把关，驳回会带整改意见退回上一阶段）； -- 分支：流程到分支点时，AI 给出可选路径菜单让你拍板； -- 退出/查看进度：随时可以让 AI 退出工作流或汇报当前进展； -- 同一对话同时只能激活一个工作流。 - -### 内置工作流 - -| 工作流 | 用途 | -|--------|------| -| bug-fix-triage | 缺陷分诊与修复流程 | -| code-review-pipeline | 代码评审流水线 | -| feature-development | 功能开发全流程 | -| research-report | 调研报告生成流程 | - -### 自定义工作流 - -参照内置工作流的 `WORKFLOW.md` 格式编写，放入工作流库目录即可。建议直接用自然语言让 AI「按 workflow-authoring 技能帮我写一个 xx 流程」——系统内置了编写规范和格式校验，写完自动归档可激活。 - -工作流审核由**工作流审核智能体**（`workflow_review`）执行，配置见下文「审核智能体」。 - -## 4. Skills（技能包） - -### 是什么 - -Skill = 一个文件夹 + 一份 `SKILL.md`（带元信息的技能说明书）。它把「某类任务该怎么做」的经验沉淀下来，AI 遇到匹配场景时先读技能再动手——相当于给 AI 发岗位培训手册。 - -### 内置 Skills（12 个） - -`agent-build-standard`（Agent 架构教学）、`agents-md-writer`（写 AGENTS.md）、`docx`（Word 文档）、`pptx`（PPT）、`frontend-design`（前端设计）、`ui-aesthetic-design`（UI 美学）、`skill-creator`（创建新 Skill）、`workflow-authoring`（写工作流）、`run-command-guide`（命令执行规范）、`terminal-guide`（终端使用规范）、`sub-agent-guide`（子智能体规范）、`mcp-tool-config`（MCP 自助配置）。 - -### 怎么用 - -- 插入引用：输入 `//` 或 `+` 菜单 →「选择 AgentSkill」，把技能引用插进消息； -- 启用/停用：个人空间「工具与 Skills」页管理启用列表； -- **强约束开关**（默认全关）：可分别要求「用终端前先读 terminal-guide」「用 run_command 前/后台前先读规范」「派子智能体前先读 sub-agent-guide」——适合新手期防误用，熟练后可关； -- **Skill 提示**（默认关）：根据任务动态提示可能相关的技能。 - -### 自定义 Skill - -直接对 AI 说「把今天的流程沉淀成一个 skill」，它会按 `skill-creator` 规范创建、校验并归档，之后即可复用。用户技能存放在工作区 `.astrion/skills/`。 - -## 5. MCP 工具扩展 - -通过 [Model Context Protocol](https://modelcontextprotocol.io) 接入外部工具服务（数据库、浏览器自动化、第三方 SaaS……），接入后 AI 工具列表里会出现 `mcp__服务名__工具名` 形式的新工具。 - -- **配置文件**：`<数据根>/<模式>/data/mcp_servers.json`（可用 `MCP_SERVERS_FILE` 覆盖）； -- **总开关**：`MCP_TOOLS_ENABLED`（默认开）； -- 协议版本 `2025-06-18`，工具发现/调用默认超时 25 秒； -- **host 模式特色**：你可以直接让 AI「帮我配置 xxx MCP 服务」——内置 `mcp-tool-config` 技能会引导它自己写好配置并生效。 - -## 6. 审核智能体（三个） - -三个在关键节点替你把关的独立 AI，统一在个人空间「审核智能体」页配置，**模型复用子智能体模型库**： - -| 审核智能体 | 介入时机 | -|------------|----------| -| `auto_approval` 自动审批 | `auto_approval` 权限模式下，命令要写沙箱外/触发权限拒绝时自动审批 | -| `goal_review` 目标审核 | 目标模式下，评估每轮工作是否达成目标 | -| `workflow_review` 工作流审核 | 工作流的审核节点，决定放行还是驳回 | - -每个可配：`model`（留空用模型库默认）、`thinking`（思考模式）、`timeout_seconds`、`max_rounds`、`max_command_timeout`。 - -> 经验：审核智能体建议选**便宜但稳定**的模型——它们调用频繁、任务模式固定，没必要上旗舰。 - -## 7. 组合玩法示例 - -- **多智能体 + 工作流**：激活 feature-development 工作流后，Team Leader 按流程指挥角色团队逐阶段交付； -- **子智能体 + Skills**：调研任务前插入 `//frontend-design`，子智能体带着设计规范干活； -- **MCP + 快捷窗口**：浏览器自动化 MCP 跑长任务时，在「后台命令」窗口盯实时进度。 diff --git a/website-content/08-quick-dock.md b/website-content/08-quick-dock.md deleted file mode 100644 index ef581dcf..00000000 --- a/website-content/08-quick-dock.md +++ /dev/null @@ -1,33 +0,0 @@ -# 快捷窗口（Quick Dock） - -对话区右侧的一列浮动窗口，把「任务进行中产生的可交互产物」集中在一处，不用翻消息流就能盯住全局。 - ---- - -## 1. 五个窗口 - -自上而下依次是： - -| 窗口 | 显示什么 | 典型操作 | -|------|----------|----------| -| **工作流** | 当前激活的工作流：处于哪个阶段、审核状态、待决分支 | 查看流程进展，配合分支选择 | -| **待办** | AI 创建的任务清单（todo）：每件事的完成状态 | 看 AI 的执行计划推进到哪一步 | -| **子智能体** | 运行中/空闲的子智能体实例：状态、当前在做什么 | 点详情看输出时间线；⋯ 菜单**强制关闭**失控实例 | -| **后台命令** | 后台运行的命令任务：状态、耗时 | 点详情看完整输出；⋯ 菜单强制关闭 | -| **文件记录** | 本轮任务 AI 编辑/创建过的文件 | ⋯ 菜单：**下载** / **在文件管理器中打开**（host 模式）/ **复制路径** | - -### 详情面板 - -- 点击子智能体/后台命令条目 → 打开**运行器详情面板**：输出与工具调用按真实时间线混排，失控时可强制关闭； -- 点击文件条目 → 打开**文件预览面板**：直接查看文件内容。长行默认横向滚动，个人空间可改为按面板宽度自动换行。 - -## 2. 展开与收起 - -- **有内容时自动展开**（默认）：任何一个窗口有内容时，整列自动展开；全空时自动收起为边缘细条，不占地方； -- 个人空间可改为**仅手动展开**（`quick_dock_auto_expand`），或**整体隐藏**（`hide_quick_dock`）。 - -## 3. 使用心法 - -- **盯失控**：子智能体/后台命令行为异常时，不用在对话里喊话，直接 ⋯ → 强制关闭； -- **盯进度**：长任务期间，待办窗 + 子智能体窗就是项目看板； -- **收产物**：任务结束到文件记录窗批量下载或跳目录，比在消息流里翻卡片快得多。 diff --git a/website-content/09-settings.md b/website-content/09-settings.md deleted file mode 100644 index 7ef10ab6..00000000 --- a/website-content/09-settings.md +++ /dev/null @@ -1,154 +0,0 @@ -# 个人空间设置全解 - -个人空间（输入栏 `+` 菜单 →「个人设置」）共分 12 个标签页（管理员多 1 个）。本章**逐页逐项**说明每个设置的作用、默认值与使用场景——设置页面里一句话说不清的，都在这里讲透。 - -> 约定：「默认」指代码出厂默认值；如果你用过 `setup.sh` 向导，个别默认值可能被向导的选择覆盖。 - ---- - -## 1. 常规 - -| 设置项 | 默认 | 说明 | -|--------|------|------| -| 自动生成标题 | 开 | 首轮对话后自动生成对话标题。关闭后新对话保持「新对话」占位名，需手动重命名 | - -## 2. 个性化 - -这一页决定「AI 用什么人格与你相处」。 - -| 设置项 | 默认 | 作用与场景 | -|--------|------|------------| -| 启用个性化 | 关 | 本页总开关。关闭时下列配置不注入提示词 | -| AI 自称 | 空 | AI 如何称呼自己（≤20 字），如「小A」 | -| 称呼你 | 空 | AI 如何称呼你（≤20 字） | -| 职业 | 空 | 你的职业（≤20 字）。填了 AI 会按你的背景调整表达深浅——开发者给技术细节，业务人员讲人话 | -| 语气 | 空 | 8 个预设：健谈 / 幽默 / 直言不讳 / 鼓励性 / 诗意 / 企业商务 / 打破常规 / 同理心 | -| 注意事项 | 空 | **最强大的一项**：最多 10 条、每条 2000 字的长期指令，每轮对话都注入。适合写「回答必须用中文」「代码注释用英文」「我是色弱，图表避免红绿配色」这类长期偏好 | -| 交流风格 | 标准 | 标准 AI 风格 / 拟人聊天风格 / 自动（按场景切换） | -| 对话连续性 | 中 | 高：主动回顾历史对话与记忆；中：平衡；低：每轮对话尽量独立。**开了「最近对话提示」却觉得 AI 总是答非所问地提旧事，就把这里调低** | - -## 3. 模型与思考 - -| 设置项 | 默认 | 说明 | -|--------|------|------| -| 默认模型 | 模型库第一个可见项 | 新对话默认使用的模型，可选库中任意已注册模型 | -| 默认思考模式 | 思考 | fast / thinking。思考模式质量更高，快速模式响应更快 | -| 默认推理强度 | 默认（不传参） | 默认 / 低 / 中 / 高；需模型开启 `reasoning_effort` 才生效 | - -> 这里的「默认」都只影响**新建对话**；已有对话用输入栏的切换器单独调。 - -## 4. 外观与显示 - -| 设置项 | 默认 | 说明 | -|--------|------|------| -| 主题配色 | 经典 | 经典（暖奶油+暖橙）/ 明亮（冷白+近黑）/ 夜间（中性灰阶） | -| 消息流显示模式 | 堆叠动画 | 传统列表 / 堆叠动画 / 极简模式；极简模式另有「展开时限制最大高度」开关（默认开） | -| 简略消息显示 | 完整信息 | 完整原始内容 / 一行概要 | -| 堆叠块隐藏边线 | 关 | 堆叠模式下隐藏块间边线，更素净 | -| 显示助手状态形象 | 开 | 对话区的状态头像（可以戳，有彩蛋） | -| 显示 Git 状态栏 | 开 | 输入栏上方的 Git 状态条 | -| 显示自定义称呼 | 开 | 在界面中显示你设置的自称/称呼 | -| 增强工具显示 | 开 | 工具结果结构化渲染；关掉则更接近原始输出 | -| 自动打开终端面板 | — | 终端任务时自动展开实时终端面板 | -| 快捷窗口自动展开 | 开 | Quick Dock 有内容时自动展开；关闭则只能手动点开 | -| 隐藏快捷窗口 | 关 | 整体关闭 Quick Dock | -| 编辑摘要实时显示 | 关 | 开：AI 边改边显示编辑摘要卡片；关：一轮工作完成后统一显示 | -| 文件预览自动换行 | 关 | 开：预览面板按宽度换行；关：长行横向滚动 | -| 侧边栏按工作区分组 | 关 | 对话列表按工作区/项目分组；分组模式支持工作区置顶与排序 | -| 新建对话按钮行为 | 跳转空白页 | route：跳到空白新对话页 / blank：立即创建空对话 | - -## 5. 工作区与权限 - -| 设置项 | 默认 | 说明 | -|--------|------|------| -| 默认权限模式 | 无限制 | 新终端的初始权限模式。**强烈建议改为「批准」**，四档行为见《核心概念》 | -| 默认运行模式 | 计划 | 新终端的初始运行模式：计划 / 询问 / 执行 | -| 默认隐藏工作区 | 关 | 界面中默认收起工作区信息 | -| AGENTS.md 自动注入 | 关 | 开：每轮对话自动携带项目根 AGENTS.md，AI 始终带着项目规范干活。长期项目建议开 | -| 修改留痕 | 开 | 每轮任务结束后把净修改 diff 落盘到 `.astrion/modify_history/`。关闭后既不落盘也不注入提示 | -| 新对话默认开启版本控制 | 开 | 建议保持开启，这是文件安全网 | -| 版本控制备份方式 | 浅备份 | 浅备份：只备份 AI 编辑的文件；完全备份：整工作区快照（大项目慎用） | -| 目标审核模式 | 仅读对话 | 目标模式的审核方式：readonly 只读对话判断 / active 允许审核智能体跑只读命令取证 | -| 目标最大轮数 | 有默认值 | 目标模式自动续轮上限 | -| 目标 token 上限 | 不启用 | 累计输入+输出 token 达到即停（1k–100M）。注意是工作区级近似统计 | - -## 6. 上下文 - -这一页是长对话质量的关键，**改动前建议先读《输入与上下文》第 4 节**。 - -| 设置项 | 默认 | 说明 | -|--------|------|------| -| 最近对话提示 | 关 | 开：新对话自动注入最近 N 条历史对话摘要 | -| 最近对话数量 | 10 | 上面那项的 N，1–30 | -| 项目记忆索引上限 | 20 条 | 项目记忆索引最多注入条数（≥5，可设无上限） | -| 自动浅压缩 | 关 | ⚠️ **会破坏上下文缓存**，见《输入与上下文》。不推荐开 | -| 浅压缩触发 token | 80000 | 自定义时**至少为模型实际可用上下文的 80%** | -| 浅压缩保留最近工具数 | 15 | 最近 N 个工具结果不压 | -| 浅压缩保留用户轮次工具 | 3 | 最近 N 次用户输入之后的工具不压 | -| 浅压缩每轮最多替换 | 10 | 单次压缩最多替换多少个工具结果 | -| 浅压缩工具调用间隔 | 10 | 每 N 次工具调用检查一次是否触发 | -| 自动深压缩 | 开 | 推荐保持开启 | -| 深压缩触发 token | 150000 | 同样遵守 80% 规则 | -| 深压缩产物形式 | 生成文件 | file：总结写入文件随取随用（推荐）/ inject：直接注入总结全文 | - -## 7. 工具与 Skills - -| 设置项 | 默认 | 说明 | -|--------|------|------| -| 静默禁用工具 | 开 | 禁用某工具时不向模型插入提示，上下文更干净 | -| 隐藏工具审批面板 | 开 | auto_approval 模式下不自动弹出审批面板打扰你；关则有审批即弹 | -| 工具意图说明 | 开 | 工具调用卡片上显示「要做什么」的简述；关掉可让消息流更紧凑 | -| Skill 提示 | 关 | 根据当前任务动态提示可能相关的 Skill | -| 强约束：终端 | 关 | 开：AI 使用终端工具前必须先读 terminal-guide 规范 | -| 强约束：子智能体 | 关 | 开：派子智能体前必须先读 sub-agent-guide | -| 强约束：前台命令 | 关 | 开：run_command 前台模式前必须先读规范 | -| 强约束：后台命令 | 关 | 开：run_command 后台模式前必须先读规范 | -| 启用 Skills 列表 | 全部 | 勾选哪些 Skill 可被使用 | -| 禁用工具类别 | 无 | 按类别整体禁用工具（如禁用网页搜索类） | - -四个「强约束」是新手护栏：强迫 AI 在用高危工具前先读使用规范，显著降低误操作率；熟练后关掉可省 token。 - -## 8. 文件与图片 - -| 设置项 | 默认 | 说明 | -|--------|------|------| -| 图片压缩档位 | 原图 | 原图 / 1080p / 720p / 540p。长对话多发大图建议降档省上下文 | - -## 9. 数据管理 - -只读的**用量统计**页：累计输入/输出 token、总对话数、用户消息数、工具调用次数，支持手动刷新。用来回答「我这个月烧了多少 token」。 - -## 10. 语音模型 - -端侧语音识别模型（SenseVoice int8）的下载管理：约 228MB，**仅在手机本地运行、无需网络**，支持中英混说与自动标点。页面显示下载状态（未下载/下载中百分比/已下载/下载不完整），可重新下载或删除。此功能面向 Android 客户端。 - -## 11. 子智能体 - -多智能体**角色编辑器**：角色列表、新建角色、编辑角色。角色的字段与写法见《智能体能力》第 2 节。预置 5 个角色可查看参考，自定义角色随改随用。 - -## 12. 审核智能体 - -三个审核智能体（自动审批 / 目标审核 / 工作流审核）的统一配置页，各自可配： - -| 字段 | 说明 | -|------|------| -| 模型 | 子智能体模型库中的条目名；**留空 = 用模型库 `default_model`** | -| 思考模式 | fast / thinking | -| 超时时间 | 单次审核的最长等待 | -| 最大轮数 | 审核智能体自身的工作轮数上限 | -| 命令超时 | 审核中执行核查命令的单条超时 | - -配置建议：审核任务模式固定、调用频繁，选便宜稳定的模型即可，不必用旗舰。 - -## 13. 管理员（仅管理员可见） - -管理员专属页：用户与策略管理（`admin/` 相关界面）。普通用户看不到此页。 - ---- - -## 附：设置生效机制 - -- 所有设置存储在数据目录的 `personalization.json`，按用户隔离； -- 「默认 XX」类设置只影响新建对象（新对话/新终端），不改已有的； -- 显示类设置（主题、显示模式等）即时生效； -- 涉及提示词注入的设置（个性化、注意事项、AGENTS.md 注入等）从下一轮对话开始生效。 diff --git a/website-content/10-cli.md b/website-content/10-cli.md deleted file mode 100644 index 1545334f..00000000 --- a/website-content/10-cli.md +++ /dev/null @@ -1,36 +0,0 @@ -# CLI（开发中） - -> ⚠️ CLI 目前处于**重写中的开发状态**，功能与稳定性以 Web 端为准，本文仅介绍当前形态，所列行为后续可能变化。 - ---- - -## 1. 是什么 - -一个终端里的对话客户端：**React 19 + Ink 6 + TypeScript** 实现的 TUI，让你不打开浏览器也能与 Astrion 对话。 - -关键点：CLI **不是独立的 Agent 运行时**——它连接的是你本地正在运行的 Astrion Web 服务（默认 `127.0.0.1:8091`），所有对话、工具执行、权限控制都走后端，CLI 只是一个更轻的交互界面。 - -## 2. 启动 - -```bash -npm --prefix cli install # 首次安装依赖 -npm run cli # 启动，自动连接本地 8091 服务 -``` - -启动后会清屏、连接本地服务、创建新会话，输入区固定在底部。若当前目录不在任何已授权工作区中，会先询问是否添加为工作区。 - -## 3. 当前能力与边界 - -- 基础对话、流式输出、工具调用展示； -- `/` 指令体系（设计中，详见仓库 `docs/cli_slash_commands_spec.md`）； -- 思考内容默认折叠，只显示「思考中 / 思考完成」； -- 多模态、快捷窗口、版本控制等 Web 端能力在 CLI 中**尚未对齐**——需要完整功能时请用 Web 端。 - -## 4. 面向开发者 - -```bash -npm run cli:typecheck # 类型检查 -npm run cli:build # 构建（产物提供 agents / agents-cli 命令） -``` - -CLI 代码在 `cli/src/`（`App.tsx`、`components.tsx`、`eventMapper.ts`、`api.ts`），欢迎贡献。 diff --git a/website-content/README.md b/website-content/README.md deleted file mode 100644 index 67e68149..00000000 --- a/website-content/README.md +++ /dev/null @@ -1,31 +0,0 @@ -# Astrion 官网文档（中文版文案） - -本目录是 Astrion 官网的**中文文案底稿**，后续将迁入独立仓库并据此设计官网。 - -## 章节地图 - -| 文件 | 章节 | 读者 | -|------|------|------| -| `01-quick-start.md` | 快速上手：安装、端口、数据路径、模型与子智能体模型配置、host/docker 选择 | 新用户 | -| `02-core-concepts.md` | 核心概念：部署/权限/执行环境/运行模式四组正交概念，各平台沙箱安全水位 | 所有人（最重要的一章） | -| `03-conversations.md` | 对话：对话类型、思考模式与推理强度、目标模式（Beta）、对话面板、对话管理 | 用户 | -| `04-input-context.md` | 输入与上下文：`+` 菜单全项、`/` 斜杠菜单、`@` 引用、压缩机制与 80% 规则 | 用户 | -| `05-execution-security.md` | 执行与安全：两段式执行、路径授权、网络权限、审批、direct 忠告 | 用户/管理员 | -| `06-conversation-assets.md` | 对话资产管理：版本控制、修改留痕、Git 状态栏 | 用户 | -| `07-agent-capabilities.md` | 智能体能力：子智能体、多智能体、工作流、Skills、MCP、审核智能体 | 进阶用户 | -| `08-quick-dock.md` | 快捷窗口：五个窗口的用法与操作 | 用户 | -| `09-settings.md` | 个人空间设置全解：12 个标签页逐项说明 | 用户（工具书式查阅） | -| `10-cli.md` | CLI（开发中）：形态、启动、当前边界 | 用户/开发者 | - -## 写作约定 - -- 全部功能描述**以代码事实为准**（文件:行号级核实），不以界面描述文案为准； -- 安全性内容如实标注（macOS 全局可读、Linux 沙箱未实测、Windows WSL2 可完全隔离）； -- Beta/开发中功能明确标注； -- 每个设置项都给出「默认值 + 作用 + 什么场景要改」。 - -## 待补充（设计官网阶段） - -- 开发者文档线（架构/消息管线/多智能体内部机制等，以 AGENTS.md 为底重组） -- 首页 landing 文案与截图 -- 截图与演示素材（需运行实例采集）