oh-my-agent-web 0.7.0 → 1.0.2

package/README.md

@@ -2,80 +2,47 @@
 
 **中文** · [English](README.en.md)
 
-一句话：**给你正在跑的那个 agent 配一个外部操作页。** 引擎照旧自己跑在自己电脑上，你在网页里看着它干活、管它的工具和模型、随时插话纠正，需要时直接翻文件和开终端。
+一句话：**给你正在跑的那个 agent 配一个外部操作页。** 引擎照旧跑在自己电脑上，你在网页里看着它干活、管它的工具和模型、随时插话纠正，需要时直接翻文件、开终端、圈出一段话让它改。
 
-单用户、只听回环、会话事实源是引擎自己的落盘文件 —— 不引数据库、不建账号体系，`omaw` 起一个进程就是一个人的工作台。
+单用户、只听回环、**会话的事实源永远是引擎自己的落盘文件** —— 不引数据库、不建账号体系、不把会话复制一份到自己的库里。一个 `oh-my-agent-web` 进程就是一个人的工作台。
 
-![一次会话里并行开 4 个子代理：左侧项目与会话、中间过程与工具卡、右侧文件预览](docs/screenshots/01-chat.png)
+![一次真实会话：左侧项目与会话、中间过程里的思考段与工具卡、右侧同一个仓库的文件预览](docs/screenshots/01-chat.png)
 
-```
-npm ci && npm run build && npm start   →   http://127.0.0.1:25257
-```
+> 下面所有截图都是把本仓库（0.8.0 的构建）跑起来后的真实界面 —— pi 引擎 + DeepSeek，工作区是一个 `demo-app` 演示项目。
+> 目录、命令、`+6 −1` 的改动、token 与花费都是那次真实运行留下的，没有拼图也没有 mock。
+> 每张图的内容、拍法与压缩方式记在 [`docs/screenshots/README.md`](docs/screenshots/README.md)。
 
 ---
 
-## 模块一览
+## 安装
 
-顶栏那一排就是全部入口；侧栏管项目/会话/文件，右栏是预览与终端。
+要求 **Node.js ≥ 22.19** 与 **npm ≥ 9**（macOS / Linux / Windows 都行）。装完就有 `oh-my-agent-web` 这个命令（短别名 `aw`、`agent-web`，完全等价）。
 
-| 模块 | 入口 | 能做什么 |
-|---|---|---|
-| **对话** | 中间 | 流式正文 + 可折叠思考块 + 工具卡（参数 / 完整命令 / 输出 / 耗时 / 成败）+ 「过程 N 步」分块 + 用量尾注（token / 缓存 / 花费）+ 改动文件 chip |
-| **插队与排队** | 输入区 | 回合进行中可以 steer（下一条立刻生效）；排队的消息可撤回；发出去的消息可折叠进过程 |
-| **多引擎** | 顶栏「引擎」 | pi / Codex / DeepSeek Harness / opencode 各自的原生 loop（不是换皮的同一套 prompt）；每个会话记住自己的引擎、模型、思考档 |
-| **子代理** | 顶栏「子代理」+ 对话下方卡片条 | 主 agent 拿到 `Agent` 工具后可并行开多个**真实会话**；对话下方给运行卡（状态 / 耗时 / 工具次数 / token / 花费 / 就地看结果 / 单独停掉）；面板里管模板：工具白名单、模型、思考档、最大轮次、并发上限（1–12） |
-| **模型与供应商** | 顶栏「模型」 | 内置 pi 官方目录里的 41 家：**填一把 key 就能用**，不用抄 base url 与模型 id；自定义 provider 可改 api 形态（openai-completions / responses / anthropic-messages / codex / typesafe）、base url、自定义 headers；逐个勾选模型、批量测速、从 `/models` 拉清单、按勾选保存白名单；**key 不出服务端**（只回尾 4 位） |
-| **技能** | 顶栏「技能」 | 已装列表（工具市场装了 45 个就是 45 行）+ 启停 + 看 `SKILL.md` 与目录文件；**Skill Hub** 分类搜索与一键安装（索引 20 万+）、从 Git 仓库装、手动创建；启停 = 把 `SKILL.md` 改名，不留第二份状态 |
-| **MCP** | 顶栏「MCP」 | 全局与项目两份 `mcp.json` 可视化增删改（项目同名条目覆盖全局）、启停、exposure 四档（codemode / deferred / direct / hidden）、**测试连接**（真握手 + 列工具）、OAuth 登录、市场挑服务器 |
-| **插件** | 顶栏「插件」 | pi package（npm / git / 本地目录）四态一览（loaded / installed / missing / disabled）、按包停用、散装 `extensions/` 单文件扩展；状态来自 pi 自己解析，装/卸/更新才动磁盘 |
-| **文件管理** | 侧栏「文件管理」 | 目录树（可换根）、按文件名搜索、显示隐藏文件、全部收起、上传与下载、在 Finder 中显示；未提交改动在树上打点 |
-| **查看文件** | 右栏预览（多标签） | markdown / 源码带行号 / 图片 / PDF / 音视频流；按行选中后「添加到对话」直接当上下文；可全屏、可拖宽 |
-| **改动（diff）** | 预览页顶「改动」 | 与 HEAD 对比：`+285 −78` 概览、行级红绿高亮、可只看改动也可回到全文；从「改动过的文件」chip 点进来时直接落在 diff |
-| **git** | 文件区顶部 | 分支标签（点开切本地分支，脏工作区先确认）、文件后面标 `M` / `U` / `D` 状态 |
-| **终端** | 文件区 `>_`、右栏标签 | 真 PTY（`node-pty` + xterm.js），与会话共用 cwd，可自动执行初始命令；Linux 缺编译工具时会明确说装什么 |
-| **推送** | 顶栏「推送」 | Web Push 订阅（VAPID），回合结束推一条：标题=项目名、正文=会话名、失败 ❌ / 中断 ⏹ 带前缀；多设备管理、测试推送、一键清空；需要 https 或 localhost |
-| **语音** | 顶栏「语音」 | 四类事件提示音（开始 / 结束 / 出错 / 等待审批）可试听、音量可调；本地 TTS 播报（浏览器内置语音，不联网），可朗读最终回复、调语速与音色 |
-| **设置** | 顶栏「设置」 | 四页：**界面**（顶栏与状态栏显示哪些块）、**通用**（快捷短语等）、**外观**（聊天字号 4 档 / 内容宽度 4 档 / 6 套色板：清亮白、暖纸、雾青、东京夜、摩卡、北境）、**语言**（中文 / English，点了立刻生效） |
-| **会话** | 侧栏 | 按目录分组成「项目」、置顶、重命名、归档（可撤销）、删除（改名 `.deleted-<时间戳>`，文件还在）；会话就是引擎自己的文件，CLI 里看到的一致 |
-| **附件** | 输入框 | 拖拽上传、`@` 提及文件、图片粘贴；上传落在数据目录，不写进项目 |
-| **手机** | — | 窄屏自适应：侧栏变抽屉、过程块收成三角箭头、400px 以下自动切手机布局 |
-
-> 下面所有截图都来自**真实运行**的实例（就在本项目自己的会话上截的），不是拼的 mock。
-
----
+### npm 全局安装（推荐）
 
-## 界面与截图
+```bash
+npm -g install oh-my-agent-web
+```
 
-| | |
-|---|---|
-| ![回复：markdown 表格 + 改动文件 + 用量](docs/screenshots/02-answer.png) | ![文件预览的改动视图](docs/screenshots/03-files-diff.png) |
-| **回答**：markdown / 表格 / 代码高亮，尾注给 token 与花费 | **改动**：与 HEAD 对比，红绿行级高亮 |
-| ![内嵌终端](docs/screenshots/04-terminal.png) | ![模型与供应商](docs/screenshots/05-models.png) |
-| **终端**：真 PTY，与会话同 cwd | **模型**：内置 41 家填 key 即用，模型勾选即生效 |
-| ![技能面板](docs/screenshots/06-skills.png) | ![Skill Hub](docs/screenshots/07-skills-hub.png) |
-| **技能**：已装列表 + 启停 + 看 SKILL.md | **技能市场**：分类搜索，一键安装 |
-| ![MCP](docs/screenshots/08-mcp.png) | ![子代理](docs/screenshots/09-subagents.png) |
-| **MCP**：全局 / 项目两份配置、暴露方式、测试连接 | **子代理**：跑几个、看结果、模板与工具白名单 |
-| ![设置](docs/screenshots/10-settings.png) | ![插件](docs/screenshots/11-plugins.png) |
-| **设置 → 外观**：字号、内容宽度、6 套色板 | **插件**：pi package 的加载状态与启停 |
-
-另外两张：[语音（提示音 + 本地 TTS）](docs/screenshots/12-voice.png)、[推送（订阅与多设备）](docs/screenshots/13-push.png)。
+不带版本号装的就是当前发行版。要钉版本或用镜像：
 
----
+```bash
+npm -g install oh-my-agent-web@latest
+npm -g install oh-my-agent-web@<版本号> --registry=https://registry.npmmirror.com
+```
 
-## 快速开始
+装出来的三个命令指向同一个入口，完全等价：**`oh-my-agent-web`**（下面统一用它）、`aw`（短别名，打字省事）、`agent-web`。
 
-要求 **Node.js ≥ 22.19**（`@earendil-works/pi-*` 1.x 的硬要求）与 **npm ≥ 9**。macOS / Linux / Windows 均可。
+升级与卸载：
 
 ```bash
-npm ci               # 推荐：按 lock 文件装精确版本（不重新解析版本范围）
-npm run build
-npm start            # 前台运行；Ctrl-C 退出
+oh-my-agent-web upgrade               # 等于 npm -g install oh-my-agent-web@latest
+npm -g uninstall oh-my-agent-web      # 卸载；~/.oh-my-agent-web 里的数据不动
 ```
 
-浏览器打开 <http://127.0.0.1:25257>。
+Linux 上 `node-pty`（内嵌终端）只给 macOS / Windows 带预编译产物，Linux 要就地编译：需要 `make` / `g++` / `python3`。缺工具时页面和安装脚本都会直说缺什么，装完终端才开得起来。
 
-### 一行命令安装（不碰系统全局 npm）
+### 一行脚本（不想碰系统全局 npm）
 
 macOS / Linux：
 
@@ -89,199 +56,441 @@ Windows（PowerShell）：
 powershell -c "irm https://raw.githubusercontent.com/duzhenxun/oh-my-agent-web/main/scripts/install.ps1 | iex"
 ```
 
-脚本做四件事：**找一个够新的 Node**（没有就下官方包到 `~/.omaw/node`，校验 sha256）、
-**`npm install -g --prefix ~/.omaw`**（不写系统全局目录、不需要 sudo）、
-**把 `omaw` 挂到 `~/.local/bin`**（必要时补 PATH）、**冒烟一次**（版本号 + node-pty 能否 require，即终端能不能开）。
+脚本做四件事：**找一个够新的 Node**（没有就下官方包到 `~/.oh-my-agent-web/node`，校验 sha256）、**`npm install -g --prefix ~/.oh-my-agent-web`**（不写系统全局目录、不要 sudo）、**把 `aw` / `agent-web` / `oh-my-agent-web` 挂到 `~/.local/bin`**（必要时补 PATH）、**冒烟一次**（版本号 + `node-pty` 能否 require，即终端能不能开）。
+
+装到的这个 `~/.oh-my-agent-web` 同时也是**数据目录**：装进去的 `node/`、`lib/`、`bin/` 和你的 `settings.json`、`password`、`uploads/`、`logs/` 并排放着。
 
 | 想改的东西 | 用法（`sh` 版；PowerShell 版用环境变量） |
 |---|---|
-| 版本 | `OMAW_VERSION=0.7.0`（或 `--version 0.7.0`） |
-| 装到别处 | `OMAW_HOME=/opt/omaw`（或 `--home /opt/omaw`） |
-| 镜像源 | `OMAW_REGISTRY=https://registry.npmmirror.com`（或 `--registry …`） |
-| 不动 PATH | `OMAW_NO_PATH=1`（或 `--no-modify-path`） |
-| 装编译工具 | `OMAW_BUILD_TOOLS=1`（或 `--with-build-tools`） |
-| 卸载 | `… \| sh -s -- --uninstall`（只删安装目录与软链，数据目录不动） |
-
-Linux 上额外查一次 `make` / `g++` / `python3`：`node-pty` 只给 macOS / Windows 带预编译产物，
-Linux 要就地编译 PTY。缺工具时脚本会说清楚装什么，或者直接 `--with-build-tools` 让它代劳。
+| 版本 | `OH_MY_AGENT_WEB_VERSION=<版本号>`（或 `--version <版本号>`） |
+| 装到别处 | `OH_MY_AGENT_WEB_HOME=/opt/oh-my-agent-web`（或 `--home /opt/oh-my-agent-web`） |
+| 镜像源 | `OH_MY_AGENT_WEB_REGISTRY=https://registry.npmmirror.com`（或 `--registry …`） |
+| 不动 PATH | `OH_MY_AGENT_WEB_NO_PATH=1`（或 `--no-modify-path`） |
+| 装编译工具 | `OH_MY_AGENT_WEB_BUILD_TOOLS=1`（或 `--with-build-tools`） |
+| 卸载 | `… \| sh -s -- --uninstall`（只删装进去的包与命令，`settings.json` / 密码 / 上传 / 日志不动） |
 
-> 装完在家目录里直接敲 `omaw` 也能用：家目录当工作区不安全（文件树 / 搜索 / agent 的 cwd 会是整个 home），
-> 所以这时会自动改用 `<数据目录>/workspace` 并打一行提示；真想指定项目就用 `AGENT_WEB_CWD=/path/to/project`。
+---
 
-### 装成全局命令
+## 命令
 
-`oh-my-agent-web` / `omaw` / `agent-web` 三个 bin 指向同一入口，完全等价：
+三个命令完全等价，下面统一写 `oh-my-agent-web`（`aw` 是它的短别名）。
 
-```bash
-npm i -g .
-omaw -d              # 后台启动（日志写到 <dataDir>/daemon.log）
-omaw status          # pid / 端口 / 运行时长 / 引擎 / 会话数
-omaw restart -d      # 改完代码重启
-omaw stop
-omaw version         # 当前版本；omaw upgrade 一键升级到最新发行版
-```
+| 命令 | 作用 |
+|---|---|
+| `oh-my-agent-web` | **启动（默认）**：后台跑起来 + 打开浏览器，终端立刻还给你；默认工作区 = 当前目录 |
+| `oh-my-agent-web start -f` | 前台运行，日志直接打在终端，`Ctrl-C` 退出 |
+| `oh-my-agent-web status` | 看状态：pid / 端口 / 已运行多久 / 引擎 / 会话数 / 工作区 |
+| `oh-my-agent-web restart` | 先停再起（默认仍后台；带 `-f` 则前台） |
+| `oh-my-agent-web stop` | 停掉正在跑的实例（前台、后台都行 —— 读的是数据目录里的锁文件，不靠猜端口） |
+| `oh-my-agent-web version` | 版本号（`-v` / `--version` 同义） |
+| `oh-my-agent-web upgrade` | 升级到最新发行版（内部就是 `npm -g install oh-my-agent-web@latest`） |
+| `oh-my-agent-web help` | 显示帮助（`-h` / `--help` 同义） |
 
-### 命令行参数
+### 参数
 
 | 参数 | 环境变量 | 默认 | 说明 |
-| --- | --- | --- | --- |
+|---|---|---|---|
 | `-p, --port` | `AGENT_WEB_PORT` | `25257` | 监听端口 |
 | `-H, --host` | `AGENT_WEB_HOST` | `127.0.0.1` | 监听地址；对外访问才需要改 |
-| `-P, --password` | `AGENT_WEB_PASSWORD` | 无 | 访问密码；不设 = 只允许本机 |
+| `-P, --password` | `AGENT_WEB_PASSWORD` | 无 | 访问密码；不设 = 只允许本机（远程首次打开会先让你设） |
+| `-f, --foreground` | — | 关（默认后台） | 前台运行，日志打在终端；`-d` / `--detach` 是旧写法，现在等于默认 |
+| `--no-open` | — | 开 | 不在浏览器里打开页面 |
 | `--allow-host` | `AGENT_WEB_ALLOWED_HOSTS` | 只认 loopback | 额外允许的域名 / 局域网 IP（可多次或逗号分隔） |
 | `--data-dir` | `AGENT_WEB_DATA_DIR` | `~/.oh-my-agent-web` | 设置、密码、上传、日志、锁文件都放这 |
 | — | `AGENT_WEB_CWD` | `process.cwd()` | 默认工作区（还没开会话时用） |
 | — | `AGENT_WEB_ENGINE` | `pi` | 默认引擎 |
-| — | `AGENT_WEB_APPROVAL_MODE` | `allow` | 新会话的默认审批模式；设 `ask` 则逐次确认 |
+| — | `AGENT_WEB_APPROVAL_MODE` | `allow` | 新会话默认审批模式；`ask` 则逐次确认 |
 | — | `AGENT_WEB_TURN_TIMEOUT_MS` | 20 分钟 | 单回合看门狗超时 |
 | — | `AGENT_WEB_LOG` | `info` | `debug` / `info` / `warn` / `error` |
 
-> 想从手机访问：`omaw -d -H 0.0.0.0 -P 你的密码 --allow-host 你的域名`，反代 / 隧道请带上 `X-Forwarded-For`（来源校验会看它）。
+### 常用例子
+
+```bash
+oh-my-agent-web                                    # 后台起 + 打开页面（最常用）
+oh-my-agent-web -f                                 # 前台起，日志直接看，Ctrl-C 退出
+oh-my-agent-web -p 25258                           # 换端口（25257 被占时）
+oh-my-agent-web status && oh-my-agent-web restart  # 看完状态再重启
+oh-my-agent-web stop                               # 停掉（前台/后台都行）
+oh-my-agent-web --data-dir ~/agent-web-data             # 换数据目录
+AGENT_WEB_CWD=~/code/my-proj oh-my-agent-web       # 指定默认工作区
+oh-my-agent-web -H 0.0.0.0 --allow-host agent.example.com   # 允许对外访问（首次打开会先让你设密码）
+```
+
+> **想从手机访问**：`oh-my-agent-web -H 0.0.0.0 --allow-host 你的域名`，首次在手机上打开会让你**设一个访问密码**（存到数据目录里的 `password`，之后就是输密码登录），反代 / 隧道请带上 `X-Forwarded-For`（来源校验会看它）。
+>
+> **在家目录直接敲 `oh-my-agent-web`** 也能用，但家目录当工作区不安全（文件树 / 搜索 / agent 的 cwd 会是整个 home），这时会自动改用 `<数据目录>/workspace` 并打一行提示；想指定项目就用 `AGENT_WEB_CWD=/path/to/project`。
+
+各引擎还有自己的逃生阀（都有默认值，通常不用配）：`AGENT_WEB_CODEX_BIN` / `_HOME`、`AGENT_WEB_DSH_BIN` / `_HOME` / `_MODEL` / `_PATCH`、`AGENT_WEB_OPENCODE_BIN` / `_ARGS` / `_MODEL`、`AGENT_WEB_CLAUDE_BIN` / `_ARGS` / `_MODEL`（默认自动探测 `claude-code-acp` / `claude-agent-acp`，没装就直说）。
+
+---
+
+## 它是什么，不是什么
+
+**是**：一个把 agent 的「过程」摊开给你看的前端。思考块、工具调用、改动文件、token 与花费，都在对话流里；你能在回合中途插话、把某段话圈出来提意见、另开一条不落盘的临时对话问一句就走。
+
+**不是**：不是新的 agent 引擎，也不是把会话搬到云上的 SaaS。它不重写 prompt、不接管工具实现 —— 你装的是 pi / Codex / Claude Code / opencode / DeepSeek Harness，工作台只是给它们配了一套能看的界面、能点的按钮和能落盘的会话列表。
+
+三条硬纪律：
+
+1. **不引数据库**：会话就是引擎写的 JSONL / thread，网页只读它、改它的名字、必要时删它。
+2. **不假装**：引擎没有的能力就在界面上藏起来（能力矩阵），面板拿不到数据就说清楚，不拿别的引擎的配置冒充。
+3. **不越界**：默认只听 `127.0.0.1`，远程暴露要显式给 `-H`、`-P`、`--allow-host` 三样。
+
+---
+
+## 对话
+
+**流式正文 + 可折叠思考块 + 工具卡**。工具卡上给参数、完整命令（可复制）、输出、耗时与成败；一次回合里的思考与工具调用按「过程 N 步」分块，点开才展开。
+
+![一条回复的尾注：markdown 表格、改动文件 chip、这一轮的 token / 缓存 / 花费](docs/screenshots/02-answer.png)
+
+每条回复的尾注是**这一轮**的用量：输入（未命中缓存）/ 输出 / 缓存命中 / 花费，点「复制」可以整段带走；整段会话的累计在状态栏的上下文环里点开看（子代理是独立会话、单独计费，不算在里面）。
+
+对话里还埋了几个能点的东西：
+
+- **改动文件 chip**：这条回复改过哪些文件（上图底部的 `改动 1 个文件 / store.ts`），点一下直接落到右栏的 diff。
+- **分支图标**：从这条消息「创建分支」，原对话一字不动。
+- **文件路径**：正文里的 `web/src/App.tsx` 这类路径可直接点开预览。
+
+### 插队、排队、停止
+
+回合正在跑的时候，输入框不会锁死：
+
+| 动作 | 含义 |
+|---|---|
+| **插队（steer）** | 立刻生效，作为下一条指令插进当前回合 |
+| **排队** | 排在本回合结束之后，队首是谁一目了然，随时可撤回 |
+| **停止** | 中断当前回合，保留已经产出的内容 |
+
+插队只有 pi 引擎支持（它的 SDK 有 `streamingBehavior: "steer"`）；别的引擎没有这个语义，宿主会**降级成排队**，而不是硬发第二条把活跃回合冲掉。
 
 ---
 
-## 界面导览
+## 注释：把一段话圈出来提意见
+
+在对话里**选中一段文字**，会浮出一个小工具条：`添加到会话` / `标注` / `在临时会话中提问`。
+
+<table><tr>
+<td width="50%"><img src="docs/screenshots/14-selection-toolbar.png" alt="选中一段回复后浮出的工具条"></td>
+<td width="50%"><img src="docs/screenshots/15-annotations.png" alt="标注之后：正文里留下编号徽标，输入框里多出「1 条注释」"></td>
+</tr></table>
+
+「标注」给这段文字挂一条评论，正文上会留一个 **①②③ 编号徽标**，输入框里多出一个「N 条注释」的胶囊 —— 点开能逐条看、改评论、删掉，或者「放进输入框」。
+
+发送时会自动拼成这样的块（也可以手动「放进输入框」，那就只发你自己写的话）：
 
 ```
-┌─ 顶栏：品牌 · 新会话 · 引擎选择 · 模型/技能/推送/语音/插件/MCP/子代理/设置 ──┐
-├────────────┬──────────────────────────────┬──────────────────────┤
-│ 侧栏       │ 对话                          │ 右栏                  │
-│ · 项目     │ · 消息流（思考段 + 工具卡）    │ · 文件预览（多标签）   │
-│ · 会话     │ · steer / 排队消息            │ · 终端                │
-│ · 归档     │ · 子代理运行卡片条            │ · 状态栏              │
-│ · 文件区   │ · 输入框（附件 / slash）       │                      │
-└────────────┴──────────────────────────────┴──────────────────────┘
+标注 1：
+> 面板从 y=0 开始，但顶栏的 z-index 是 45
+
+这里要再压缩一句
 ```
 
-侧栏与右栏都能拖宽 / 收起，宽度记在 `localStorage`。输入框支持 `/` 快捷指令、`@` 提及文件、拖拽附件与粘贴图片；上方那排 chip 是提示词模板、思考开关与建议动作。
+注释是**本地锚点**：按「原文 + 前后文」定位，所以正文重排、流式追加之后徽标仍能挂回原处；它存在当前浏览器的 `localStorage`（按会话隔离），不进服务端、不上云，换个设备看不到。
 
-窄屏（手机 UA 或 ≤400px）自动切成覆盖抽屉，点会话后延迟收起；顶栏与状态栏里显示哪些块、过程块展开与否，都在设置里能关掉。
+**文件的行引用**是另一条路：在预览里选中行（`Shift+点` 连选、`Ctrl/Cmd+点` 加选、右键出行菜单），「追加到对话」写进草稿的是 `@web/src/App.tsx:120-138` 这样的**路径 + 行号**，让 agent 自己去读。
 
 ---
 
-## 引擎
+## 临时对话：问一句就走
+
+![右边这条「临时聊天」是独立通道：不落盘，主对话照旧在跑](docs/screenshots/13-tempchat.png)
+
+顶栏那颗「临时会话」（或右栏工作区落地页的第一张卡）会在**右栏**另开一条聊天：
+
+- **不落盘**：会话只存在内存里，关掉标签就销毁，不进侧栏、不留文件；
+- 主对话照旧跑，两边互不打断；
+- 想留下就点 `保存为正式对话`，此时才写出会话文件（临时会话没有的历史也能保住）；
+- 可以同时开多条，每条一个独立通道、独立标签。
+
+> 该能力依赖引擎的「内存会话」：pi 支持；Codex 的 thread 本身就在它自己的库里，所以没有「保存」按钮。它不是「换皮的新会话」，也不等于子代理 —— **临时对话是人开的窗口，子代理是 agent 派出去的子任务**。
+
+---
+
+## 文件、改动、git、搜索
+
+文件区在侧栏底部，也能在右栏当标签用。**网页端是只读的**：看、比、引用、搜，都能做；原地改文件并保存不在这一层 —— 改文件交给 agent 的工具或终端，这里用 diff 复核。
+
+| 能力 | 说明 |
+|---|---|
+| 目录树 | 可换根（跟随会话 / 指定项目）、懒加载、单目录最多 500 项、默认不列 `node_modules`/`.git`/`dist`，可「显示隐藏文件」看 `.env` 之类 |
+| 按文件名搜 | 只匹配名字，不读内容，防抖 250ms，最多 200 条 |
+| 预览 | markdown（表格 / 代码高亮 / mermaid）、源码带行号、图片、PDF、音视频流；多标签、拖拽换序、右键关闭左/右/全部、可铺开占满 |
+| 行引用 | 选中行 → 「追加到对话」写 `@path:行号`；拖选文字还能「复制选中的文字」 |
+| 在 Finder 中显示 | macOS `open -R`、Windows `explorer.exe /select,`、Linux 打开父目录 |
+| 未提交改动 | 文件树上的状态点、文件后面的 `M` / `U` / `D` |
 
-| 引擎 | 说明 |
-| --- | --- |
-| **pi**（默认） | 完整的插件 / 技能生态、工具延迟加载、审批门禁、目标模式与子代理；模型与 provider 由本工作台管理 |
-| **Codex** | codex 官方 agent（app-server JSON-RPC），独立 loop 与沙箱，会话与 Codex Desktop / CLI 共用；审批是命令 / 文件级的 |
-| **DeepSeek Harness** | DeepSeek 官方 agent（ACP），模型与思考档可切，权限逐次确认 |
-| **opencode** | opencode 官方 agent（ACP），自带工具 / MCP / 插件生态；会话与 opencode CLI / TUI 共用。**审批取决于 opencode 自身的 `permission` 配置**（配成全局 allow 时不会询问） |
-| **fake** | 零 token 的脚本化引擎，只用来验证协议 / 工具 / 审批流程（`AGENT_WEB_ENGINE=fake`，默认不进切换面板） |
+### 改动（diff）
 
-能力差异（`server/engine/registry.ts` 的能力矩阵）：
+![改动视图：与 HEAD 对比，`+6 −1` 概览 + 行级红绿](docs/screenshots/03-diff.png)
 
-| 能力 | pi | codex | dsh | opencode |
-| --- | :-: | :-: | :-: | :-: |
-| 审批 | ✅ | ✅ | ✅ | 看配置 |
-| 模型 / 思考档 | ✅ | ✅ | ✅ | ✅ |
-| 恢复历史会话 | ✅ | ✅ | ✅ | ✅ |
-| 插队（steer） | ✅ | — | — | — |
-| 子代理面板 | ✅ | — | — | — |
-| 本工作台管 provider | ✅ | — | — | — |
+预览页顶部切「改动」就是与 `HEAD` 的对比：`+285 −78` 概览、行级红绿高亮、可「只看改动」也可回到全文。从回答里的「改动文件」chip 点进来会直接落在 diff。
 
-装没装的引擎不影响启动：只有切到它时才会报「没找到」。
+### git
 
-各引擎的逃生阀（都有默认值，通常不用配）：
+文件区顶部有分支标签，点开切本地分支（工作区脏会先要确认）。它只调 `git` 命令做读与切分支，不做提交 —— 提交还是交给 agent 或你自己在终端里做。
 
-| 变量 | 作用 |
-| --- | --- |
-| `AGENT_WEB_OPENCODE_BIN` / `_ARGS` / `_MODEL` | opencode 可执行文件、额外参数（如 `--pure` 跳过外部插件）、新会话优先模型（`provider/model`） |
-| `AGENT_WEB_DSH_BIN` / `_HOME` / `_MODEL` / `_PATCH` | DSH 可执行文件、数据目录、模型、补丁开关 |
-| `AGENT_WEB_CODEX_BIN` / `_HOME` | codex 可执行文件与数据目录 |
+### 内容搜索
+
+工具栏的「搜文件内容」是全文检索：可以加**路径掩码**（如 `web/src/**`）收窄范围，结果显示 `文件:行号` + 原文片段，点一下跳到那行；命中太多时按上限截断并明说。
 
 ---
 
-## 会话与落盘
+## 终端
 
-不引数据库，**会话的事实源永远是引擎自己写的文件**。网页只是读它、改它的名字、必要时删它。
+![右栏的终端是真 PTY：zsh、颜色、git 输出、cwd 与会话一致](docs/screenshots/04-terminal.png)
 
-| 内容 | 位置 |
-| --- | --- |
-| pi 会话 | `~/.pi/agent/sessions/<编码后的 cwd>/<ISO>_<uuid>.jsonl`（首行 `{type:"session",id,timestamp,cwd}`） |
-| Codex 会话 | Codex 自己的 thread 存储（走 `thread/list \| resume \| delete`） |
-| opencode / DSH 会话 | 各自的数据目录（opencode 按 cwd `session/list`；DSH 读 `~/.dsh` 的 workspace 投影） |
-| 会话标题 | pi 取首条 user 消息（只读头 60 行）；改名 = 往 jsonl 末尾追加 `session_info.name` |
-| 工作台状态 | `<dataDir>/settings.json`、`approval-rules.json`、`server.lock`、`logs/`、`uploads/`、`push-subscriptions.json`、`vapid-keys.json` |
+右栏的终端是**真 PTY**（`node-pty` + xterm.js）：vim / top / Ctrl-C / 颜色 / 行编辑都正常，cwd 与会话所在项目一致，可带一条初始命令（升级流程就用它）。
+
+刷新页面不会恢复终端会话（PTY 随页面卸载退出），切标签则不会断。Linux 上 `node-pty` 需要就地编译，缺工具时界面会直接说装什么。
 
-「删除会话」是**改名到 `.deleted-<时间戳>`**（引擎自带删除接口时优先用原生的），文件还在磁盘上，能捞回来。
+### 内置网页
+
+右栏还能开网页：输入网址在 iframe 里看，请求走**本机代理**（`/web/p/<url>`）—— 把文档取回来、去掉 `X-Frame-Options` / CSP 的嵌入限制，所以百度这类站点也能开。代理有边界：只代理 HTML/CSS 文档、**不带 cookie 过去也不带回**、上游 12MB 上限、iframe 沙箱不含 `allow-same-origin`。需要登录或重 JS 的站点点 `⧉` 跳系统浏览器。
+
+---
+
+## 多引擎：各跑各的原生 loop
+
+引擎不是「同一个 prompt 换个皮」，每个都是官方 agent 自己的循环：
+
+| 引擎 | 接入方式 | 说明 |
+|---|---|---|
+| **pi**（默认） | 原生 SDK | 完整插件 / 技能生态、工具延迟加载、审批门禁、子代理、插队；模型与 provider 由本工作台管理 |
+| **Codex** | app-server（JSON-RPC） | 独立 loop 与沙箱，会话与 Codex Desktop / CLI 共用；审批是命令 / 文件级的 |
+| **DeepSeek Harness** | ACP | 模型与思考档可切，权限逐次确认 |
+| **opencode** | ACP | 自带工具 / MCP / 插件生态，会话与 opencode CLI / TUI 共用；审批取决于 opencode 自己的 `permission` 配置 |
+| **Claude Code** | ACP（`claude-code-acp` 适配器） | 模型可切、工具逐次确认，会话与 `claude` CLI 共用；这套 ACP 面不暴露思考档与子代理 |
+| **fake** | 内置脚本化引擎 | 零 token，只用来验证协议 / 工具 / 审批流程（默认不出现在切换面板） |
+
+能力差异（`server/engine/registry.ts` 的能力矩阵，界面据此隐藏按钮）：
+
+| 能力 | pi | codex | dsh | opencode | claude |
+|---|:-:|:-:|:-:|:-:|:-:|
+| 审批 | ✅ | ✅ | ✅ | 看配置 | ✅ |
+| 模型 / 思考档 | ✅ | ✅ | ✅ | ✅ | 模型可切 / 无档位 |
+| 恢复历史会话 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 插队（steer） | ✅ | — | — | — | — |
+| 子代理面板 | ✅ | — | — | — | — |
+| 本工作台管 provider | ✅ | — | — | — | — |
+| 临时会话（内存） | ✅ | — | — | — | — |
+
+**模型 / 插件 / MCP 三块跟着当前引擎走**：切到 Codex，面板读的就是 Codex 自己的东西（`model/list`、`plugin/list`、`config/read`）；claude 读 `~/.claude.json` 与 `~/.claude/settings.json`；opencode 读 `opencode.json`。没接的面板会直说，不拿 pi 的配置冒充。
+
+引擎在**底部状态栏**切换（不是顶栏），每个会话各自记住自己的引擎、模型与思考档。
 
 ---
 
 ## 模型与供应商
 
-「模型」面板左栏分两组：**官方内置服务商**（pi 自带目录里有模型的那批）与**自定义服务商**。
+![模型面板：左边是当前有 key / 已登录的服务商，右边是该 provider 的端点、API 形态、模型白名单](docs/screenshots/05-models.png)
+
+- **订阅服务**：OAuth 登录（9 家），登录后直接能用，不用手抄 key。
+- **官方内置**：pi 目录里带模型的那批，**填一把 key 就能用**，端点与模型表由目录提供。
+- **自己输入**：可改 API 形态（openai-completions / responses / anthropic-messages / codex / typesafe）、base url、自定义 headers，逐个加模型。
+- 逐个勾选模型（只保存勾上的）、批量试连、从 `/models` 拉清单、按勾选保存白名单。
 
-- 内置那批只要**填一把 API key** 就能用 —— 端点与模型表都由 pi 的目录提供。
-- 自定义可以逐个加模型、改 base url、从别的客户端**导入**（实际是拉 `GET {baseUrl}/models` 勾选写回）、逐个**试连**。
-- **key 不出服务端**：接口只返回 `hasKey` 与尾 4 位；写操作在进程内串行化，避免并发写坏文件。
+**key 不出服务端**：接口只返回 `hasKey` 与尾 4 位；写操作在进程内串行化，避免并发写坏文件。
 
-配置真相分散在三处 + 引擎目录：`~/.pi/agent/models.json`（pi 自己的 provider 目录，可写）、
-`models-store.json`（历史位置）、`auth.json`（`api_key` 或 oauth 订阅凭据），白名单在 `settings.json.enabledModels`。
+配置真相分散在 `~/.pi/agent/models.json`（provider 目录）、`models-store.json`（历史位置）、`auth.json`（`api_key` 或 OAuth 凭据），白名单在 `settings.json.enabledModels`。
 
 ---
 
-## 审批与安全模型
+## 技能
 
-- 默认只监听 `127.0.0.1`，并校验 `Origin` / `Host`（含 `AGENT_WEB_ALLOWED_HOSTS` 白名单、vite 端口、局域网地址）。
-- 身份判定：对端是回环 **且** Host 是回环 → 放行；未设密码时远程一律 403；设了密码则走 cookie（`agent-web-auth`，7 天 HttpOnly）或 HTTP Basic；登录失败按 20 次 / 10 分钟节流。
-- 工具与命令走审批：**只读工具**（read / grep / find / ls）与只读命令自动放行，其余按 `scopeKey`（工具 + 可执行名或目标目录）询问；点「总是允许」就把规则写进 `approval-rules.json`（原子写，坏文件当空）。
-- 会话回合结束时清掉该会话所有悬置审批，不会挂在那等下一个人点。
-- 上传的临时文件、会话缓存都在数据目录里，不写进你的项目目录。
+![技能面板：已装 / 启用 / 禁用三档，右边是这个技能的 SKILL.md 摘要与目录文件](docs/screenshots/06-skills.png)
 
-> 远程暴露是显式操作：必须同时给 `-H`、`-P`、`--allow-host`，缺一个都不通。
+读 `~/.agents/skills/<目录>/SKILL.md`，列表只解析 frontmatter（不引 yaml 依赖）。**启停 = 把 `SKILL.md` 改名成 `.SKILL.md.disabled`**，没有第二份状态文件 —— 所以在 CLI 里看到的一致。
+
+**Skill Hub**：分类搜索 + 一键安装（索引 20 万+），也能从 Git 仓库装指定 `skills/<name>`，或手动建一个。
 
 ---
 
-## 子代理（并行 + 可管理）
+## MCP
 
-pi 引擎带一套自己的子代理实现（**不依赖 pi-subagents 插件**）：
+![MCP 面板：全局与项目两份配置、启停与暴露方式、测试连接、OAuth](docs/screenshots/07-mcp.png)
 
-- **怎么开**：主 Agent 拿到 `Agent` 工具（`subagent_type` / `prompt` / `description` / `run_in_background`），一次可以并行开好几个；每次委派都是**一个真实的 pi 会话**（自己的上下文、会话文件、工具白名单）。
-- **在哪看**：运行卡片在对话下方（输入区上方那条「子代理」卡片条）：状态、耗时、工具次数、token 与花费，点开原地展开结果原文与会话文件路径，随时停掉某一个；切会话自动换成本会话的那批。顶栏徽标保留一眼概览。
-- **怎么管**：面板里管的是**模板**（内置 explore / general-purpose / plan，可停用；可新建 / 编辑 / 删除）。模板落 `~/.pi/agent/agents/*.md`，frontmatter 写 `name / display_name / description / tools / model / thinking / max_turns`，正文就是系统指令 —— 与 pi 的 agent 文件同一套格式，可读可改可进 git。
-- **并发**：面板可设上限（1–12，默认 4），超出的排队；总开关关掉后模型不再看到 `Agent` 工具。
-- **隔离**：子代理默认不加载技能 / 插件 / 主题 / 上下文文件（快、可预期）；模型不跟随父会话时沿用父会话的模型。有的模型由扩展注册 provider，这类模型在子代理里会失败并提示「在模板里指定模型」。
+读写两份配置：`~/.pi/agent/mcp.json`（全局）与 `<workspace>/.pi/mcp.json`（项目），**项目同名条目覆盖全局**，写回保留缩进与 CRLF。
 
-子代理会话文件紧挨着父会话归档（`<父会话目录>/<父会话名>/subagents/`），不进侧栏的项目清单。
+- exposure 四档：**代码模式（默认）/ 搜索后声明 / 直接声明 / 不暴露**；
+- **测试连接**：真握手 + `tools/list` 后即断，报连接状态与工具数；
+- OAuth 登录、市场挑服务器、粘贴命令 / URL / JSON 自动解析；
+- **配置即真相**：pi 会话启动时自己连，改完对**新会话**生效。
 
 ---
 
-## MCP · 插件 · 技能
+## 插件
 
-**MCP**：读写 `~/.pi/agent/mcp.json`（全局）与 `<workspace>/.pi/mcp.json`（项目），项目同名条目覆盖全局；写回保留缩进与 CRLF。
-exposure 四档 `codemode | deferred | direct | hidden`，工具命名空间 `mcp__<name>`。
-**配置即真相** —— pi 会话启动时自行连接，面板改完对**新会话**生效。测试连接走 `@earendil-works/pi-mcp` 真实握手 + `tools/list` 后即断；
-OAuth 走 `pi mcp login`。另有市场入口（registry / smithery / github）与「粘贴命令 / URL / JSON 自动解析」。
+![插件面板：pi package 的四态与按包停用](docs/screenshots/09-plugins.png)
 
-**插件**：就是 pi package —— `settings.json` 的 `packages`（npm / git / 本地）+ 散装 `~/.pi/agent/extensions/`、`<ws>/.pi/extensions/`。
-状态由 pi SDK 的 `resolve()` 决定（查询**不**触发 npm install），四态 `loaded / installed / missing / disabled`；停用写 `autoload:false`，不删文件。
+插件就是 pi package：`settings.json` 里的 `packages`（npm / git / 本地目录）+ 散装 `~/.pi/agent/extensions/`、`<ws>/.pi/extensions/`。
 
-**技能**：读 `~/.agents/skills/<目录>/SKILL.md`，列表只解析 frontmatter（不引 yaml 依赖），文件清单 ≤ 200 条。
-**启停 = 把 `SKILL.md` 改名成 `.SKILL.md.disabled`**，没有第二份状态文件。Skill Hub 支持分类搜索 + zip 安装，也支持 git clone 指定 `skills/<name>`。
+状态由 pi SDK 的 `resolve()` 决定（**查询不会触发 npm install**），四态 `loaded / installed / missing / disabled`；按包停用写 `autoload:false`，不删文件。
 
 ---
 
-## 架构：SSE + RPC，没有 WebSocket
+## 子代理：并行开，逐个管
+
+![子代理面板：内置模板、默认并发、启用开关](docs/screenshots/08-subagents.png)
+
+主 agent 拿到 `Agent` 工具后，可以一次并行开好几个子代理，每个都是**一个真实的会话**（自己的上下文、会话文件、工具白名单）。
+
+- **看**：输入框上方那条「子代理」卡片条 —— 状态、耗时、工具次数、token、花费，点「查看结果」原地展开结果原文与会话文件路径，可以单独停掉某一个；标题里给一眼概览（`2 个在跑` / `8 个已结束`）。
+- **管**：顶栏「子代理」面板管的是**模板**（内置 explore / general-purpose / plan，可停用；也能新建、编辑、删除）：`name / display_name / description / tools / model / thinking / max_turns`，落 `~/.pi/agent/agents/*.md`，与 pi 的 agent 文件同一套格式，可读可改可进 git。
+- **并发**：1–12（默认 4），超出的排队；关掉总开关后模型不再看到 `Agent` 工具。
+- **隔离**：子代理默认不加载技能 / 插件 / 主题 / 上下文文件（快、可预期）；模型不跟随父会话时沿用父会话的模型。
+
+子代理的会话文件紧挨着父会话归档（`<父会话目录>/<父会话名>/subagents/`），不进侧栏项目清单。
+
+---
+
+## 推送与语音
+
+<table><tr>
+<td width="50%"><img src="docs/screenshots/11-push.png" alt="推送：本机推送状态、目标设备、测试推送"></td>
+<td width="50%"><img src="docs/screenshots/10-voice.png" alt="语音：四类事件提示音 + 本地 TTS"></td>
+</tr></table>
+
+**推送**：Web Push（VAPID）订阅，回合结束推一条 —— 标题=项目名、正文=会话名，失败 ❌ / 中断 ⏹ 带前缀；多设备管理、测试推送、一键清空。需要 https 或 localhost。
+
+**语音**：四类事件提示音（开始 / 结束 / 出错 / 等待审批）可试听、音量可调；本地 TTS 用浏览器内置语音播报最终回复，可调语速与音色，不联网。
+
+---
+
+## 设置
+
+![设置 → 外观：三处字号、内容宽度 4 档、6 套色板](docs/screenshots/12-settings.png)
+
+顶栏那一排就是全部面板入口，**可以在「设置 → 界面」里逐项隐藏**（设置与分栏两颗不参与隐藏 —— 它们是恢复其它入口的唯一入口）；侧栏、右栏也都能拖宽、收起，宽度记在本机 `localStorage`。
+
+顶栏「设置」分五页：
+
+| 页 | 内容 |
+|---|---|
+| **界面** | 外框：顶栏显示哪些入口（文案 / 图标分开勾）、状态栏里显示哪些块（排队 / 工作中 / 上下文用量）、侧栏、对话里图片的最大宽度 |
+| **对话** | 对话区自己长什么样：输入框上方显示哪些块（模板 / 想想 / 快捷指令）、快捷短语的内容、想想（思考档）的默认值（这两项走服务端保存、多设备一致）、对话里是否显示花费、思考块与工具卡默认是否展开 |
+| **外观** | 只管尺寸：三处字号（聊天正文 / 侧栏项目名 / 侧栏会话名，滑杆 2–20px）、内容宽度 4 档（720 / 900 / 1100 / 满宽）、顶栏高度、顶栏名称与 logo（可隐藏、可改成自己的名字） |
+| **主题** | 6 套色板（清亮白、暖纸、雾青、东京夜、摩卡、北境），点一下立刻生效 |
+| **语言** | 中文 / English，点了立刻生效 |
+| **快捷键** | 11 个动作可改键、可清空、可恢复默认，另有速查表 |
+
+外观、主题、界面、语言这些偏好只存本机（`localStorage`，`agent-web.` 前缀），手机、平板、桌面各一份；「通用」里的快捷短语才多设备一致。
+
+---
+
+## 手机
+
+<table><tr>
+<td width="34%"><img src="docs/screenshots/16-mobile.png" alt="手机单栏：顶栏入口只留图标、输入框 18px"></td>
+<td width="34%"><img src="docs/screenshots/17-mobile-drawer.png" alt="手机上的项目侧栏是覆盖式抽屉"></td>
+</tr></table>
+
+窄屏（手机 UA 或 ≤400px）自动切成单栏：
+
+- 侧栏变覆盖式抽屉（宽度 `clamp(260px, 76vw, 340px)`，点遮罩关闭，点会话后自动收起）；
+- 顶栏允许换行、入口只留图标、可横向滑动；
+- 右栏工作区变成整屏第二页，用 `100dvh` 从顶栏下方开始（避开 iOS 工具栏）；
+- 输入框字号 18px，免得 iOS 聚焦时自动放大；模型菜单变底部抽屉；
+- 状态栏横向可滚，上下文用量浮层变整宽弹层。
+
+---
+
+## 会话：置顶、归档、分叉、换项目
+
+侧栏按目录把会话分组「项目」：
+
+| 动作 | 行为 |
+|---|---|
+| 置顶 | 会话或项目提到最上面 |
+| 重命名 | pi 会话 = 往 jsonl 末尾追加 `session_info.name` |
+| 归档 | 收进「已归档」，可撤销 |
+| 删除 | 改名成 `.deleted-<时间戳>`（引擎有原生删除接口时优先用它），**文件还在磁盘上** |
+| 分叉 | 从某条消息派生新会话（标题 `分支 · …`），原会话一字不动 |
+| 换项目 | 把会话行拖到另一个项目上，会话 id 与历史不变，只改文件头部的 `cwd` 并搬目录 |
+
+排序上有一个刻意的选择：**组内按创建时间倒序** —— 新会话在最上面，而更新一个旧会话不会让它跳位置（按最后活动排的话，在一个老会话里说一句话它就窜到顶，整个列表跟着挪）。
+
+---
+
+## 快捷键与斜杠指令
+
+**快捷键**都可以在「设置 → 快捷键」里改（必须带 `Mod`/`Alt`，不收裸字母）。macOS 上 `Mod` = ⌘，其它平台 = Ctrl。
+
+| 动作 | 默认键 | 动作 | 默认键 |
+|---|---|---|---|
+| 新会话 | `Mod+K` | 打开右侧边栏 | `Mod+Alt+O` |
+| 新项目 | `Mod+M` | 收起右侧边栏 | `Mod+Alt+W` |
+| 临时会话 | `Mod+Shift+K` | 收起 / 展开左侧栏 | `Mod+Alt+L` |
+| 设置 | `Mod+Alt+S` | 文件管理 | `Mod+Alt+F` |
+| 新建终端 | `Mod+Alt+T` | 搜索文件内容 | `Mod+Shift+F` |
+| 快捷键速查表 | `Mod+/` | | |
 
-早期版本用 WS，现在**只有两条 HTTP 通道**（ADR-0032）：
+**斜杠指令**在输入框里打 `/` 弹出，分两类 —— `本地` 由工作台自己执行，`发给 Agent` 原样作为消息交给引擎：
+
+| 指令 | 类型 | 作用 |
+|---|---|---|
+| `/new [首条消息]` | 本地 | 新建对话，可带上第一条消息 |
+| `/name <名称>` | 本地 | 重命名当前会话 |
+| `/model <名称>` | 本地 | 切模型（按 id 或显示名模糊匹配） |
+| `/thinking <档位>` | 本地 | 设思考强度（off / low / … / max） |
+| `/copy` | 本地 | 复制最后一条助手消息 |
+| `/session` | 本地 | 会话消息数 / token / 费用统计 |
+| `/resume` | 本地 | 刷新会话列表（别的终端刚开的会话） |
+| `/skill <技能名>` | 发给 Agent | 用某个技能（面板会列出已装的） |
+| `/compact [说明]` | 发给 Agent | 压缩上下文 |
+| `/plan [on\|off]` | 发给 Agent | 开关计划模式 |
+| `/cwd <路径>` | 发给 Agent | 切换工作目录 |
+
+---
+
+## 架构：SSE + RPC，没有 WebSocket
 
 ```
-浏览器 ──GET  /api/events（SSE）──▶ 服务端    快照 · message_delta · notice
-       ──POST /api/rpc  （JSON）──▶            ClientRequest → { reply } 就地消费
+浏览器 ──GET  /api/events（SSE）──▶ 服务端    首帧快照 · 其后只推增量
+       ──POST /api/rpc  （JSON）──▶           ClientRequest → { reply } 就地消费
 ```
 
-- **下行**：首帧一份完整快照，其后只推增量。正文走 `message_delta` 逐块追加；工具卡、错误、状态这类结构性变化推快照（60ms 窗口合并，快照可丢、事件不可丢）。SSE 25s 心跳，支持 gzip `Z_SYNC_FLUSH`。
-- **上行**：`send_message`（text / attachments / mode）、`interrupt`、`approve`、`new_chat`、`switch_conversation`、`set_engine` / `set_model` / `set_thinking_level` / `set_approval_mode`、`cancel_queued`、`rename_session`、provider 与子代理若干。
-- **协议单源**在 `server/protocol.ts`，前端复用类型，两端靠单测对齐。
-- **快照是唯一事实源**：前端 `store.ts` 用 `useSyncExternalStore`，快照一到整体替换；本地只留 `preview` / `draft` / `pendingActive` 这类乐观态。
+- **下行**：首帧一份完整快照，其后只推增量。正文走 `message_delta` 逐块追加；工具卡、错误、状态这类结构性变化推快照（60ms 窗口合并，快照可丢、事件不可丢）。SSE 25s 心跳。
+- **上行**：`send_message`、`interrupt`、`approve`、`new_chat`（可带 `ephemeral`）、`switch_conversation`、`set_engine` / `set_model` / `set_thinking_level` / `set_approval_mode`、`persist_conversation`、`close_ephemeral`、`fork_session`、`move_session`、`cancel_queued`、`rename_session` 等。
+- **协议单源**在 `server/protocol.ts`，前端复用类型，两端共用一份定义。
+- **快照是唯一事实源**：`store.ts` 用 `useSyncExternalStore`，快照一到整体替换；本地只留 `preview` / `draft` / `pendingActive` 这类乐观态。
+- **每个客户端各看各的会话**（ADR-0033）：同一个服务端，两台设备可以停在不同会话上；会话清单这类大块数据只在该客户端需要时下发。
+
+进程模型：`cli.ts` 解析参数 → `session/lock.ts` 抢 `<dataDir>/server.lock`（pid 活则拒绝启动、pid 死则接管陈旧锁）→ `runtime.init()` → `listen`。`SIGINT` / `SIGTERM` / `/api/shutdown` 走同一个优雅退出（flush、断开引擎、释放锁）。
+
+---
+
+## 数据落在哪
+
+| 内容 | 位置 |
+|---|---|
+| pi 会话 | `~/.pi/agent/sessions/<编码后的 cwd>/<ISO>_<uuid>.jsonl`（首行 `{type:"session",id,timestamp,cwd}`） |
+| Codex 会话 | Codex 自己的 thread 存储（`thread/list \| resume \| delete`） |
+| opencode / DSH / claude 会话 | 各自的数据目录（opencode 按 cwd `session/list`；DSH 读 `~/.dsh`；claude 读 `~/.claude`） |
+| 会话标题 | pi 取首条 user 消息（只读头 60 行）；改名 = 追加 `session_info.name` |
+| 工作台状态 | `<dataDir>/settings.json`、`approval-rules.json`、`server.lock`、`logs/`、`uploads/`、`push-subscriptions.json`、`vapid-keys.json` |
+| 技能 / 子代理模板 / MCP | `~/.agents/skills/`、`~/.pi/agent/agents/`、`~/.pi/agent/mcp.json` |
+| 本机界面偏好 | 浏览器 `localStorage`（`agent-web.` 前缀：主题、字号、宽度、快捷键、注释、标签页） |
+
+---
+
+## 安全模型
+
+- 默认只听 `127.0.0.1`，并校验 `Origin` / `Host`（含 `AGENT_WEB_ALLOWED_HOSTS` 白名单、vite 端口、局域网地址）。
+- 身份判定：对端是回环**且** Host 是回环 → 放行；未设密码时远程一律 403；设了密码则走 cookie（`agent-web-auth`，7 天 HttpOnly）或 HTTP Basic；登录失败按 20 次 / 10 分钟节流。
+- 工具与命令走审批：**只读工具**（read / grep / find / ls）与只读命令自动放行，其余按 `scopeKey`（工具 + 可执行名或目标目录）询问；点「总是允许」把规则写进 `approval-rules.json`（原子写，坏文件当空）。
+- 回合结束时清掉该会话所有悬置审批，不会挂在那等下一个人点。
+- 上传的临时文件、会话缓存都在数据目录里，不写进你的项目。
+- 内置网页的代理不带 cookie、iframe 沙箱不含 `allow-same-origin`（否则远端 JS 能摸到 localStorage 与 RPC）。
 
-**进程模型**：`cli.ts` 解析参数 → `session/lock.ts` 抢 `<dataDir>/server.lock`（`{pid,port,startedAt}`；pid 活则拒绝启动，pid 死则接管陈旧锁）→ `runtime.init()` → `listen`。`SIGINT/SIGTERM` 与 `/api/shutdown` 走同一个优雅退出（flush、断开引擎、释放锁）。
+> 远程暴露是显式操作：必须同时给 `-H`、`-P`、`--allow-host`，缺一个都不通。
 
 ---
 
 ## 开发
 
+在仓库根目录先 `npm install`，然后：
+
 ```bash
 npm run dev          # 一条命令起两个进程
 ```
@@ -291,8 +500,7 @@ npm run dev          # 一条命令起两个进程
 - 手机调试：`npm run dev -- --host 0.0.0.0`。
 
 | 命令 | 作用 |
-| --- | --- |
-| `npm test` | `node --test` 跑 `tests/unit/*.test.ts`（22 个文件，零额外依赖） |
+|---|---|
 | `npm run typecheck` | 服务端 + 前端两套 `tsc --noEmit` |
 | `npm run lint` | oxlint（`server` / `web/src` / `scripts`） |
 | `npm run format` | prettier 全仓格式化（`format:check` 只检查；`*.md` 故意跳过） |
@@ -301,88 +509,20 @@ npm run dev          # 一条命令起两个进程
 
 CI（`.github/workflows/ci.yml`）：`npm ci` → typecheck → lint → test → build，跑在 ubuntu + Node 22。
 
-### 目录结构
-
-```
-oh-my-agent-web/
-├─ server/                 后端（Express 5，TypeScript ESM）
-│  ├─ cli.ts               命令入口：start / stop / restart / status / version / upgrade
-│  ├─ index.ts             进程装配：中间件、路由、静态产物、优雅退出
-│  ├─ protocol.ts          协议单源（前端复用类型）
-│  ├─ engine/              引擎适配层：pi（原生 SDK）/ codex / dsh / opencode（ACP）/ fake
-│  │                       + 能力矩阵 registry、catalog、wiring、pi-plugins
-│  ├─ session/             运行时：runtime、turn-*、审批桥、改名删除、锁、settings
-│  ├─ sessions/            会话删除的 HTTP 路由（扫描逻辑在 session/pi-sessions.ts）
-│  ├─ snapshot/            服务端状态快照：state、buildSnapshot、fan-out、60ms 合并
-│  ├─ http/                auth、live-routes（SSE + RPC）、aux-routes、压缩、文件响应头
-│  ├─ files/               文件树、预览、搜索、媒体流、git 分支
-│  ├─ terminal/            PTY 会话与 SSE 流
-│  ├─ approval/            审批作用域与规则
-│  ├─ providers/           供应商 / 模型清单 / 试连 / 导入 / 订阅 OAuth
-│  ├─ mcp/                 mcp.json 读写、连通性探测、OAuth、市场
-│  ├─ skills/              技能发现、启停、Hub 安装
-│  ├─ subagents/           子代理模板存储（`~/.pi/agent/agents/*.md`）
-│  ├─ plugins/             插件包 HTTP 路由
-│  ├─ push/                Web Push（VAPID）
-│  ├─ markers/             `[[action:suggest:…]]` 标记的解析与流式过滤
-│  └─ util/                env、paths、spawn-cli（跨平台）、origin 等
-├─ web/                    前端（React 19 + Vite + TypeScript）
-│  ├─ src/components/      ~70 个组件：侧栏、消息流、输入框、文件树、终端、各类面板
-│  ├─ src/styles/          ~45 个分区 CSS + 6 套主题变量（无 CSS 框架）
-│  ├─ src/ws.ts            SSE + RPC 客户端（名字是历史遗留）
-│  └─ src/store.ts         快照 store（useSyncExternalStore）
-├─ scripts/                dev 双进程、安装脚本、prebuild 裁剪、图标生成
-├─ tests/unit/             node:test 单测
-├─ docs/adr/README.md      ADR 索引
-└─ docs/screenshots/       README 用的真实截图（PNG 256 色，~1.4MB）
-```
-
-### 代码约定
-
-- prettier：**Tab 缩进**、`printWidth 120`；oxlint 用默认规则集。
-- 单文件 400 行是护栏，超了就拆（`cli-info.ts`、`snapshot/*` 都是这么来的）。
-- **ADR 正文写在它约束的那段代码的文件头注释里**，不在 `docs/` 单独立文 —— 改代码的人一定会读到；`docs/adr/README.md` 只是按编号索引到文件的表。改代码时顺手更新那张表。
-
----
-
-## 安装体积：按场景选命令
-
-依赖树里大头都在**前端构建期**（`mermaid` 121MB、react 等）与**只给本机用的构建工具**，服务器真正运行时只需要
-`express` / `web-push` / `node-pty` / `@earendil-works/pi-*` 这几样 —— 浏览器那一半已经打进 `web/dist` 了。
-所以 `react` / `mermaid` / `xterm` / `highlight.js` 这类包全部放在 `devDependencies`：
-
-| 场景 | 命令 | 包数 | 磁盘 |
-|---|---|---|---|
-| 开发 / 要自己构建 | `npm ci` | 456 | 547 MB |
-| 已有构建产物，只想跑 | `npm ci --omit=dev` | 192 | **158 MB**（~3 秒） |
-| 构建完顺手瘦身 | `npm ci && npm run build && npm prune --omit=dev` | 192 | **158 MB** |
-| 分发给另一台机器 | `npm pack` → `npm i -g ./oh-my-agent-web-*.tgz` | 193 | 223 MB（tarball 3.1 MB，含截图） |
-
-两个自动瘦身动作已经在 `postinstall` 里（`scripts/prune-prebuilds.mjs`）：
-
-- **只留当前平台的 `node-pty` 预编译产物**：它默认带四个平台的二进制，其中 Windows 那两份就占 58MB。macOS / Linux 上剪掉后 62MB → 5MB；`npm ci` 会原样装回来。
-- 修 `spawn-helper` 的可执行位。
-
-> 剩下的 158MB 里，基本全是 pi 的模型层：各家 provider 的官方 SDK（`openai` 17.6MB、`@google/genai` 10.8MB、`@anthropic-ai/sdk` 9.1MB、`@aws-sdk/*` + `@smithy/*` 5.2MB）——
-> 这些都是 `@earendil-works/pi-ai` 的硬依赖，不做供应商裁剪就绕不开。
-
 ---
 
 ## 排错
 
-> **为什么用 `npm ci` 而不是 `npm install`**：本项目的直接依赖普遍很新（多数在发布后一个月内）。
-> `npm install` 会拿 `package.json` 里的版本范围去 registry 重新解析，一旦用的镜像源（公司 Nexus、npmmirror 等）还没同步到那些版本，就会报 `npm error notarget No matching version found for …`。
-> `npm ci` 直接用锁文件里的精确版本，完全不走这一步。
-
-按这个顺序排查：
+> **为什么用 `npm ci` 而不是 `npm install`**：直接依赖普遍很新，`npm install` 会拿版本范围去 registry 重新解析，镜像源（公司 Nexus、npmmirror 等）没同步到那些版本就报 `npm error notarget`。`npm ci` 直接用锁文件里的精确版本。
 
-1. `npm error notarget No matching version found` → 镜像没同步。先 `npm config get registry`，再临时用官方源重试：`npm ci --registry=https://registry.npmjs.org/`。
-2. `EBADENGINE` / pi 启动即报 Node 版本 → 需要 Node ≥ 22.19（`node -v` 确认）。
-3. `node-pty` 编译失败（多见于 Linux）→ 它的预编译产物只随包提供 macOS / Windows，Linux 上会现场编译：需要 `python3`、`make`、`g++`。
-4. 起不来但 `omaw status` 说「陈旧锁」→ 之前进程没退干净，下次 `start` 会自动接管；确实僵着就删 `<dataDir>/server.lock`。
-5. 端口被占 → `omaw -p 25258`，或先 `omaw stop`。
+1. `npm error notarget No matching version found` → 镜像没同步。先 `npm config get registry`，再临时用官方源：`npm -g install oh-my-agent-web --registry=https://registry.npmjs.org/`。
+2. `EBADENGINE` / 启动即报 Node 版本 → 需要 Node ≥ 22.19（`node -v` 确认）。
+3. `node-pty` 编译失败（多见于 Linux）→ 先装 `python3` / `make` / `g++` 再 `npm -g install`，或用一行脚本的 `--with-build-tools` 让脚本代劳。
+4. 起不来但 `oh-my-agent-web status` 说「陈旧锁」→ 之前进程没退干净，下次 `start` 会自动接管；确实僵着就删 `<dataDir>/server.lock`。
+5. 端口被占 → `oh-my-agent-web -p 25258`，或先 `oh-my-agent-web stop`。
+6. 内置网页一片空白 → 该站点重登录 / 重脚本，代理不隧道 cookie；点 `⧉` 用系统浏览器。
 
-Windows 上踩过的坑（shell 解析、killTree、路径判断、chmod、CRLF）记在 `WINDOWS-COMPAT.md`，按 P0/P1/P2 分级。
+Windows 上的 shell 解析、进程树回收、路径判断、权限与 CRLF 差异已全部收口在三个模块里：`server/util/spawn-cli.ts`（PATH/PATHEXT、`.cmd` 走 `cmd.exe`、`killTree`）、`server/util/paths.ts` 与 `web/src/path-utils.ts`（分隔符与绝对路径）、`server/util/file-mode.ts`（Windows 走 `icacls`）。改跨平台相关的代码先看这三个文件头。
 
 ---