@orion-agents/orion-code 0.2.2 → 0.3.1

package/docs/plan/v0.3.1-web-workbench-professional-shell-plan.md

@@ -0,0 +1,848 @@
+# v0.3.1 Web Workbench 专业工作台优化计划
+
+- 版本：v0.3.1
+- 状态：待实施
+- 日期：2026-08-29
+- 范围：Web Workbench 左侧项目导航、右侧工作面板、布局系统、专业化 UI
+- 参考：Codex 的工作台信息架构与交互密度；不复制其品牌、视觉资产或私有实现
+
+## 0. 决策摘要
+
+v0.3.1 将当前的“三栏页面”升级为可长期承载工程能力的专业工作台：
+
+1. 左侧由“当前工作区 + 当前工作区会话”升级为**多项目导航器**，可同时看到和展开多个已知项目；
+2. 中间继续是唯一的会话、流式消息、审批和 Composer 主工作区；
+3. 右侧由固定宽度的“工作详情”升级为**可变宽工作面板**，一级入口为：
+   **Agent、审阅、终端、文件、Git**；
+4. 当前 Goal、活动、能力、诊断不被删除，而是收进 Agent 面板的二级导航；
+5. 文件和 Git 在 v0.3.1 以安全、可分页的只读能力为主；审阅支持差异阅读和将反馈送回对话；
+   终端必须是真实 PTY，而不是工具输出的伪终端；
+6. Host 仍只有一个 active workspace/runtime。多项目是导航与只读概览能力，不虚构多个 Agent
+   Runtime 同时运行；跨项目会话激活必须是一次原子 Context transition；
+7. 所有新能力遵循当前 loopback Host、nonce、Origin/Host 校验、幂等 mutation、工作区 containment、
+   安全分页和恢复语义。
+
+本计划的完成定义不是“画出新布局”，而是：四项用户需求全部由真实 Host 数据驱动，并通过
+source-clean exact-tarball、真实 Chrome、Node 22.12/24/26 和无障碍门禁。
+
+## 1. 背景与当前基线
+
+### 1.1 当前实现
+
+源码基线以 v0.3.1 当前工作树为准：
+
+- `web/src/App.tsx` 使用固定三栏 Grid；右侧在 `1180px` 以下切换为 modal drawer；
+- `web/src/styles.css` 将左栏固定为 `264px`，右栏固定为 `336px`，折叠态为 `48px`；
+- `web/src/components/Inspector.tsx` 只有 Goal、活动、能力、诊断四个标签；
+- `web/src/components/WorkspaceRail.tsx` 只渲染当前工作区卡片及其 Session 列表；
+- `src/web/protocol.ts::WebWorkspaceSummaryV1` 仅包含 path、label、active、sessionCount；
+- `src/web/workbench-controller.ts::listWorkspaces()` 从当前目录和历史 Session 推导工作区，尚无独立、
+  持久的项目注册表；
+- Web API 已有工作区/Session、快照、Skills、MCP、tool details、settings 和 SSE，但没有文件树、
+  文件预览、Git 状态/历史/差异或 PTY 合同；
+- `src/services/workspace-state.ts` 和 `src/services/workspace-diff.ts` 已有可复用的 Git 只读基础，
+  `src/tools/git.ts` 也已有受控 Git 工具，但不能直接当成浏览器 API；
+- 当前依赖中没有 Web terminal emulator 或 Node PTY backend。
+
+### 1.2 当前问题
+
+- 右侧 336px 固定宽度无法同时适配 Goal 卡片、长 Diff、文件内容和终端；
+- 将更多能力继续塞进当前四标签会造成一级导航过载；
+- 工作区切换藏在 modal 中，无法形成“多个项目并列、每个项目下有会话”的稳定心智模型；
+- 现有 UI 的正文、元数据和状态字号跨度过大，部分 8.5–10px 文本不利于长期阅读；
+- 当前卡片较多而信息层级不够统一，工程状态、空态、加载态和错误态没有一套跨面板规范；
+- 文件、Git 和终端尚未形成独立的安全 read model，不能只靠解析 Tool 输出拼装 UI。
+
+## 2. 目标、成功指标与非目标
+
+### 2.1 产品目标
+
+| ID  | 目标                     | v0.3.1 结果                                                        |
+| --- | ------------------------ | ------------------------------------------------------------------ |
+| G1  | 右侧具备工程工作面板能力 | Agent、审阅、终端、文件、Git 均有真实数据和完整状态                |
+| G2  | 右侧宽度可调整           | 通过 IDE 式分隔条用鼠标或触控板拖动；刷新后恢复；窄屏自动切 drawer |
+| G3  | 左侧支持多工作区/项目    | 多项目可见、可展开、可搜索、可切换，每个项目显示会话和 Git 摘要    |
+| G4  | UI 更专业                | 统一 tokens、组件、状态、密度、响应式、键盘与 WCAG 2.2 AA          |
+
+### 2.2 可量化成功指标
+
+- 首屏已有项目列表在本地 warm Host 下 p95 ≤ 250ms；
+- 展开一个项目的首个 Session page p95 ≤ 250ms，不预取所有项目的全部 Session；
+- 右侧面板切换视觉响应 ≤ 100ms；拖动调整宽度在目标设备上保持 55–60fps；
+- 本地终端按键到回显 p95 ≤ 80ms，持续输出不阻塞对话滚动；
+- Git status p95 ≤ 500ms，单文件 Diff 首屏 p95 ≤ 400ms；
+- 文件树首次 page p95 ≤ 250ms，目录规模超过 500 项时仍不一次性渲染全部节点；
+- 320px、390px、760px、1180px、1440px 五档无页面级横向滚动；
+- 关键文本对比度 ≥ 4.5:1，控件边界/状态 ≥ 3:1，目标触控区域 ≥ 44×44 CSS px；
+- axe blocking violations = 0；键盘可以完成项目切换、面板切换、Diff 导航和终端退出；精细调宽是
+  指针交互，键盘用户仍可使用展开/折叠操作；
+- 真实 E2E 中 console error、page error、HTTP 5xx、secret finding、dropped event 均为 0。
+
+### 2.3 非目标
+
+v0.3.1 不包含：
+
+- 同时运行多个 Agent Runtime；
+- 完整 IDE、LSP 编辑器或 Monaco 替换会话主区；
+- GitHub/GitLab PR 网络审阅、远端 Issue 或 CI 管理；
+- 浏览器直接访问文件系统、直接执行 shell、直接读取 `.git` 内部文件；
+- Git checkout、merge、rebase、push、reset、discard file 等破坏性 Git 操作；
+- 文件面板内直接编辑任意文件；
+- 把 Tool 输出解析为 Git、文件或终端的权威状态；
+- 复制 Codex 的商标、文案、图标、色板或未公开内部协议。
+
+## 3. 用户与核心场景
+
+### 3.1 主要用户
+
+- 同时维护多个本地仓库的独立开发者；
+- 在对话、代码变更、命令输出和仓库状态之间频繁切换的 Agent 用户；
+- 需要键盘、高对比度、缩放或窄屏使用的开发者；
+- 需要确认 Agent 实际修改内容、验证结果和当前 Git 状态的审阅者。
+
+### 3.2 核心任务流
+
+1. 用户从左侧展开两个或以上项目，查看各自 Session、分支和脏状态；
+2. 用户点击非活动项目的 Session，Host 原子切换 workspace + session，主会话和右侧上下文同步；
+3. Agent 修改文件后，审阅面板显示变更集合、验证摘要和逐文件 Diff；
+4. 用户选中 Diff 片段并“发送到对话”，要求 Orion 修正，而不是浏览器直接重写文件；
+5. 用户在文件面板中浏览安全的项目树和只读文件内容；
+6. 用户在 Git 面板查看 branch、HEAD、ahead/behind、staged/unstaged/untracked/conflict 和提交历史；
+7. 用户明确点击“启动终端”，进入真实 PTY；刷新后可在 Host 仍存活时重新连接；
+8. 用户像在 Codex 或 IDE 中一样拖动左右分隔条改变右侧宽度，刷新页面后宽度和当前面板保持；
+9. 在窄屏下，左/右面板变成互斥 drawer，主会话没有水平压缩或焦点丢失。
+
+## 4. 信息架构
+
+### 4.1 桌面布局
+
+```text
+┌──────────────────────┬─────────────────────────────────────┬─┬──────────────────────────┐
+│ Projects             │ Conversation                        │↔│ Work panel               │
+│                      │                                     │ │                          │
+│ Search projects      │ Session header                      │ │ Agent Review Terminal   │
+│                      │ Transcript                          │ │ Files Git                │
+│ ▾ orion-code  main • │                                     │ │                          │
+│   ● Session A        │                                     │ │ Active panel content     │
+│     Session B        │                                     │ │                          │
+│ ▸ orion-studio       │                                     │ │                          │
+│ ▾ agents-www feat/x  │                                     │ │                          │
+│     Session C        │ Approval / queue / composer         │ │ status / actions         │
+└──────────────────────┴─────────────────────────────────────┴─┴──────────────────────────┘
+```
+
+默认尺寸：
+
+- 左侧：280px，v0.3.1 不提供拖动，避免同时引入两个 resize 轴；
+- 中间：`minmax(560px, 1fr)`，始终拥有优先空间；
+- 右侧：默认 420px，可调整 320–720px；实际可用上限同时受 viewport 的 55% 和中间列 560px
+  最小宽度约束，足够宽的桌面（当前三栏参数下为 1560px 及以上）才能达到完整 720px；
+- 右侧折叠轨：48px；
+- 分隔手柄：视觉 1px、命中区域 9px。
+
+### 4.2 右侧一级导航
+
+| 一级面板 | 目的                         | 权威数据源                                  | v0.3.1 范围                                    |
+| -------- | ---------------------------- | ------------------------------------------- | ---------------------------------------------- |
+| Agent    | Goal、Plan、活动、能力、诊断 | Runtime snapshot/SSE/TurnCommit             | 保留现有能力，改为二级导航                     |
+| 审阅     | 当前工作区变更和验证结果     | Git read model + Tool/verification receipts | 文件列表、Diff、反馈回对话、刷新               |
+| 终端     | 用户控制的真实本地 PTY       | Host PTY owner + dedicated stream           | 多 tab、输入/输出/resize/reconnect/close       |
+| 文件     | 项目树和文件内容             | workspace-contained file service            | 懒加载树、搜索、只读分页预览                   |
+| Git      | 仓库事实和历史               | bounded Git service                         | status、branch、HEAD、upstream、log、Diff 入口 |
+
+Agent 面板内部二级导航保持 Goal、活动、能力、诊断，避免丢失 v0.3.0 功能，也避免把九个入口平铺到同一行。
+
+### 4.3 窄屏布局
+
+```text
+┌──────────────────────────────────┐
+│ [Projects] Session       [Panel] │
+├──────────────────────────────────┤
+│                                  │
+│ Conversation                     │
+│                                  │
+├──────────────────────────────────┤
+│ Composer                         │
+└──────────────────────────────────┘
+
+Projects 或 Work panel 打开时：
+┌──────────────────────────────────┐
+│ modal drawer              [Close]│
+│ 完整面板内容                     │
+└──────────────────────────────────┘
+```
+
+- `> 1180px`：三栏 Dock，右侧可调整宽度；
+- `761–1180px`：左栏 Dock，右侧 modal drawer；
+- `≤ 760px`：左右均为互斥 modal drawer；
+- drawer 状态不覆盖桌面宽度偏好，返回桌面时恢复；
+- 打开 drawer 后主区 `inert`，焦点进入面板；Escape、关闭按钮和 scrim 均关闭并把焦点还给触发器。
+
+## 5. 右侧工作面板详细设计
+
+### 5.1 共用 Panel shell
+
+所有面板共用：
+
+- 标题、当前项目/Session 上下文、刷新和折叠操作；
+- 一级 icon rail + 文字标签；宽度不足 380px 时只显示 icon + accessible tooltip；
+- loading skeleton、empty state、stale state、offline state、permission state、error state；
+- 独立滚动容器，不能推动页面或 Composer；
+- 面板内容缓存按 `{workspaceId, sessionId?, resourceRevision}` 分区；
+- workspace/session 改变后旧请求通过 generation/AbortController 取消，旧响应不得覆盖新上下文；
+- 每个数据面板显示“更新于”和明确刷新，不用静默无限轮询。
+
+### 5.2 Agent 面板
+
+迁移当前 `Inspector` 内容：
+
+- Goal：Goal 状态、预算、criteria、evidence、Plan receipt；
+- 活动：工具、子任务、研究、验证和安全的 tool detail；
+- 能力：Skills、MCP 和模型可用性；
+- 诊断：连接、cursor、Runtime、上下文和脱敏诊断。
+
+迁移要求：
+
+- 数据合同不因重排而改变权威来源；
+- Goal/Plan 仍来自最新有效 TurnCommit，不创造虚构步骤或审核状态；
+- tool detail 仍读取预先生成的安全 derivative；
+- 现有 collapsed shortcut badge 迁移到新的一级 icon rail。
+
+### 5.3 审阅面板
+
+审阅面板由三层组成：
+
+1. **Overview**：分支、HEAD、变更文件数、staged/unstaged/untracked/conflict、最近验证结论；
+2. **Changed files**：按状态分组、按路径过滤、显示增删行数；
+3. **Diff viewer**：统一 Diff、hunk 导航、行号、空白字符开关、复制、选区送入对话。
+
+P0 操作：
+
+- 刷新变更；
+- 在文件之间导航；
+- 折叠/展开 hunk；
+- 选择一个文件或 hunk，生成结构化 `review_context` 并附加到 Composer；
+- “请 Orion 修复此处”只产生用户可见草稿，用户确认发送后才成为 Agent 输入；
+- 查看与当前 workspace revision 绑定的验证 receipt。
+
+P0 明确不做浏览器端 accept/reject/revert/stage。若未来增加，必须作为幂等 mutation，经 ToolGateway、
+明确 expected revision 和审批，不得用直接文件写入实现。
+
+### 5.4 终端面板
+
+终端必须满足真实 terminal 语义：PTY、ANSI、resize、交互程序和进程生命周期，不以 `exec_command`
+工具卡代替。
+
+#### 前端
+
+- 使用维护中的 Web terminal emulator；优先评估 `@xterm/xterm` 及 fit/accessibility addon；
+- 支持 1–4 个 terminal tab，显示 shell、cwd、running/exited 状态；
+- 支持复制、清屏、重连、关闭；粘贴多行命令时二次确认；
+- `Ctrl/Cmd+K` 等快捷键仅在 terminal 获得焦点时生效，不劫持全局；
+- 屏幕阅读器模式、光标对比度和 reduced motion 纳入门禁。
+
+#### Host
+
+- 新建 `TerminalManagerV1`，每个 terminal 强绑定 workspaceId 和 canonical cwd；
+- 使用真正的 PTY backend。优先评估 `node-pty`，但只有在 Node 22.12/24/26 的 source-clean
+  exact-tarball 安装、ABI 和运行门禁通过后才能纳入生产依赖；
+- 默认启动不读取登录 profile 的安全交互 shell，继承环境使用 allowlist，并删除 token/key/secret/auth
+  等变量；用户 profile 模式不属于 v0.3.1；
+- terminal 是用户显式启动的特权表面，模型、Skill、MCP 和页面自动化不得创建 terminal 或写入输入；
+- 输出不进入 Workbench SSE、日志、release receipt 或 transcript；保留最多 2MiB 内存滚动窗口；
+- Host 重启后 terminal 明确变为 `lost`，不伪造进程恢复；
+- workspace 切换时旧 terminal 可保持 detached，但受全局 4 个 PTY/每项目 2 个 PTY 限额；
+- Host shutdown、workspace 移除和显式 close 必须终止 child process tree。
+
+#### 传输
+
+Workbench 原有事件继续使用 SSE；PTY 使用独立同源 WebSocket，避免每个按键一个 HTTP mutation：
+
+1. `POST /terminals` 通过 nonce 创建 terminal，并返回短期、单次使用的 stream ticket；
+2. WebSocket URL 只带 opaque terminalId，不把 ticket 放入 URL；
+3. 升级时先校验 loopback Host 和 exact Origin；连接后第一帧必须在 5 秒内提交 ticket；
+4. ticket 使用后立即失效；input/resize/output 有 monotonic sequence；
+5. gap、buffer overflow 或 ticket 失效都进入明确 reconnect/lost 状态，禁止静默丢字符。
+
+真实终端可能显示用户主动访问的敏感信息，因此 UI 必须有一次性风险说明；它不能借“脱敏”之名破坏
+terminal 字节语义，也不能把原始输出复制到普通 Web 诊断或证据文件。
+
+### 5.5 文件面板
+
+P0 能力：
+
+- 以项目根为唯一 root 的懒加载树；
+- 目录展开、文件名搜索、Git 状态 decoration；
+- 只读文本预览、行号、换行、复制、跳到指定行；
+- 大文件按行/字节分页，二进制文件只显示元数据；
+- 默认忽略 `.git`、`node_modules`、构建缓存和 Orion 自身私有存储；
+- `.env`、credential、keychain、SSH key 等敏感模式不返回内容；
+- symlink 显示为 symlink，只有 realpath 仍位于 workspace 内才可继续读取。
+
+服务端返回 opaque nodeId/fileId。浏览器不得把任意路径拼到 URL，也不得使用 nodeId 绕过 active
+workspace。文件内容响应包含 content revision；翻页时 revision 不一致返回 409，前端重新载入第一页。
+
+文件搜索 P0 只搜索文件名和已加载路径，不承诺全仓内容索引。全仓内容搜索和文件编辑列入 P1。
+
+### 5.6 Git 面板
+
+P0 展示：
+
+- 是否为 Git repository、repo root 的安全显示名；
+- branch/detached HEAD、short SHA、最近 commit；
+- upstream、ahead/behind；
+- staged、unstaged、untracked、conflicted 分组；
+- 最近 commit log 的 cursor page；
+- 选择文件进入审阅 Diff；
+- refresh 和 stale revision 提示。
+
+实现复用 `workspace-state.ts`/`workspace-diff.ts` 的解析思想，但抽出 `GitReadModelServiceV1`，统一：
+
+- 仅用 `execFile` + argv，不经 shell；
+- `-c core.quotepath=false`、固定 timeout、maxBuffer 和条目上限；
+- canonical repo root 必须位于 active workspace 内或等于 active workspace；
+- 不返回包含凭证的 remote URL；只返回 remote 名称和 sanitized host（可选）；
+- branch/status/diff/log 共用 `repositoryRevision`，不能跨 revision 拼接；
+- 非 Git 目录是正常 empty state，不作为 Host 错误。
+
+stage、unstage、commit、push、checkout 等 mutation 延后至 P1，并需要单独安全方案。
+
+## 6. 右侧宽度调整
+
+### 6.1 状态模型
+
+```ts
+interface WorkPanelLayoutPreferenceV1 {
+  expanded: boolean;
+  widthPx: number; // clamp 320..min(720, viewport * 0.55)
+  activePanel: 'agent' | 'review' | 'terminal' | 'files' | 'git';
+  agentTab: 'goal' | 'activity' | 'integrations' | 'diagnostics';
+}
+```
+
+- 宽度和一级面板属于设备 UI preference，保存在 localStorage；
+- Agent 二级 tab 可同样本地保存；
+- 项目/Session 数据不写入 localStorage；
+- localStorage 不可用时回退默认值，不阻断启动；
+- preference schema 有版本，非法/超界值被丢弃；
+- mobile drawer 使用 viewport 安全宽度，但不覆盖桌面 `widthPx`。
+
+### 6.2 IDE 式指针拖动
+
+Resize handle：
+
+- 分隔线本身保持轻量，不做成可聚焦按钮；hover/drag 时显示 `col-resize` 光标和高亮线；
+- 鼠标或触控板按下后使用 pointer capture，左右拖动即时改变宽度并禁止误选文字；
+- 双击分隔线恢复 420px 默认宽度；
+- 精细调宽不提供键盘操作；键盘用户继续通过既有“展开/折叠工作面板”按钮控制面板显隐；
+- 拖动期间只更新 CSS custom property，pointerup 后再持久化，避免每帧 React 全树重渲染；
+- reduced-motion 下关闭 grid transition；
+- 中间列将小于 560px 时自动进入 overlay 模式，不能继续挤压对话。
+
+## 7. 左侧多项目导航
+
+### 7.1 项目模型
+
+当前从 Session 历史推导工作区会丢失“已打开但还没有 Session”的项目。v0.3.1 新增持久
+`WorkspaceRegistryV1`：
+
+```ts
+interface WorkspaceRegistryEntryV1 {
+  id: string; // opaque stable id
+  canonicalPath: string; // Host only authority
+  label: string;
+  lastActivatedAt: string;
+  pinnedOrder?: number;
+}
+```
+
+- 注册表位于 Orion config root，原子写入并使用锁/CAS；
+- 只记录用户显式打开过的目录，不扫描 HOME 或磁盘；
+- path 不作为 mutation identity；API 使用 opaque workspaceId；
+- 已删除、不可读和安全边界失败的目录显示 unavailable，可从列表移除；
+- 从现有 Session catalog 一次性迁移已知项目，迁移幂等；
+- 当前 workspace 即使无 Session 也必须保留。
+
+### 7.2 左栏结构
+
+```text
+ORION CODE
+
+[Search projects and sessions]
+
+PINNED
+▾ orion-code             main  M12
+   ● Optimize Web shell        running
+     Session 3840b3fe          90 msgs
+
+RECENT
+▸ orion-studio           main  clean
+▾ orion-agents-www       feat  M2
+     Website release           idle
+
+[Open project] [Settings]
+Runtime connected · v0.3.1
+```
+
+行为：
+
+- 项目可独立展开/折叠；展开时懒加载该项目的第一个 Session page；
+- 当前 active 项目和 active Session 有唯一、清晰的 `aria-current`；
+- 项目摘要显示 branch、dirty count、Session count、running/approval 标记；
+- 搜索同时匹配已加载项目和 Session；结果区域明确提示是否仍有未加载页；
+- “打开项目”复用受控本地目录输入/选择流程；
+- 置顶和最近分组属于 P0；拖动重排属于 P1，P0 用菜单“置顶/取消置顶”；
+- 多项目树使用虚拟列表或 windowing；DOM 不随历史项目数线性无限增长；
+- 项目切换期间旧项目仍可见，但主区显示明确 transition，Composer 禁用。
+
+### 7.3 原子 Context transition
+
+为避免先切 workspace、再切 Session 的中间态，新建统一 mutation：
+
+```text
+POST /context/activate
+{
+  requestId,
+  expectedContextRevision,
+  workspaceId,
+  sessionId: string | null
+}
+```
+
+Host 在同一 transition owner 中：
+
+1. 校验 workspaceId 和可访问性；
+2. 校验 Session 属于目标 workspace；
+3. drain 当前 Runtime；
+4. 安装目标 workspace Runtime；
+5. 可选恢复 Session；
+6. 返回新的 bootstrap snapshot 与 `contextRevision`；
+7. 发出一个 authoritative `workbench_state` edge。
+
+失败时恢复旧 context；无法恢复则进入明确 fatal recovery state。客户端不得自动重放可能有副作用的命令。
+
+## 8. 专业 UI 设计系统
+
+### 8.1 设计原则
+
+- **工程信息优先**：路径、分支、状态和结果比装饰性卡片更重要；
+- **安静的层级**：减少大面积渐变和重复边框，靠间距、字体、分组和轻量 surface 建立层次；
+- **高密度但可读**：body 不低于 12px，关键 meta 不低于 11px；
+- **状态可辨识**：颜色不是唯一信号，配合 icon、文案和形状；
+- **同构状态**：所有列表和面板使用同一 loading/empty/error/stale/offline 模式；
+- **本地优先**：不加载外部字体、图标或遥测资源。
+
+### 8.2 Tokens
+
+扩展当前 CSS variables 为语义 tokens：
+
+- surfaces：canvas、rail、panel、raised、hover、selected、terminal；
+- text：primary、secondary、muted、disabled、inverse；
+- borders：subtle、default、strong、focus、danger；
+- status：success、warning、danger、info、running、conflict、untracked；
+- spacing：4/8/12/16/24/32；
+- radius：6/8/12，减少无差别大圆角；
+- typography：title、section、body、meta、code、badge；
+- motion：120ms micro、180ms panel，reduced motion = 0ms。
+
+Light/Dark/System 共用语义 token，不在组件里写散落色值。所有组合在自动 contrast test 中验证。
+
+### 8.3 组件边界
+
+建议拆分：
+
+```text
+WorkbenchShell
+├── ProjectNavigator
+│   ├── ProjectSearch
+│   ├── ProjectTree
+│   └── SessionTree
+├── ConversationWorkspace
+└── WorkPanelDock
+    ├── WorkPanelRail
+    ├── WorkPanelResizeHandle
+    ├── AgentPanel
+    ├── ReviewPanel
+    ├── TerminalPanel
+    ├── FileExplorerPanel
+    └── GitPanel
+```
+
+共享基础组件：`PanelHeader`、`ResourceList`、`VirtualTree`、`StatusBadge`、`EmptyState`、
+`LoadingSkeleton`、`ErrorState`、`RevisionBanner`、`SplitView`、`CodeViewport`、`IconButton`。
+
+`Inspector.tsx` 不继续膨胀。每个业务面板拥有独立 reducer/query hook；Shell 只管理布局、选择和焦点。
+
+### 8.4 视觉与交互状态矩阵
+
+每个面板必须实现并截图：
+
+- normal with data；
+- empty；
+- initial loading；
+- incremental loading；
+- stale revision；
+- recoverable error；
+- offline/Host closed；
+- permission/capability unavailable；
+- light/dark；
+- 320/390/760/1180/1440；
+- 100% 和 200% zoom。
+
+## 9. API 与数据合同
+
+### 9.1 新增/调整的只读资源
+
+最终路径在实现前写入 `docs/architecture/v0.3.1-web-api.yaml`，至少覆盖：
+
+| 资源            | 建议路由                                 | 关键合同                                              |
+| --------------- | ---------------------------------------- | ----------------------------------------------------- |
+| 项目            | `GET /workspaces`                        | registry page、Git 摘要、revision-bound cursor        |
+| 项目 Session    | `GET /workspaces/{workspaceId}/sessions` | inactive project 可读、分页、无 Runtime side effect   |
+| Context         | `POST /context/activate`                 | requestId + expectedContextRevision + 原子切换        |
+| 文件树          | `GET /files?parentId&cursor`             | opaque id、懒加载、root containment                   |
+| 文件内容        | `GET /files/{fileId}/content?cursor`     | content revision、文本分页、binary metadata           |
+| Git status      | `GET /git/status`                        | repositoryRevision、bounded groups                    |
+| Git log         | `GET /git/log?cursor`                    | keyset page、sanitized author metadata                |
+| Git diff        | `GET /git/diff/{fileId}?cursor`          | revision-bound hunks、输出预算                        |
+| 审阅摘要        | `GET /review`                            | change set + verification receipt refs                |
+| Terminal list   | `GET /terminals`                         | active workspace terminal metadata only               |
+| Terminal create | `POST /terminals`                        | requestId、expectedContextRevision、single-use ticket |
+| Terminal close  | `DELETE /terminals/{id}`                 | requestId、幂等、process-tree termination             |
+
+### 9.2 统一合同规则
+
+- 所有 mutation 都有 UUID requestId、body digest 冲突检测和 admission cap；
+- 所有 session-bound command 保留 expectedSessionId；workspace-bound mutation 增加 expectedContextRevision；
+- 所有 collection cursor 绑定 route、workspace、revision、排序键和页边界；
+- 所有文件/Git/审阅响应都有资源 revision；跨 revision continuation 返回 409；
+- 所有响应限制 items、bytes、lines、depth 和执行时间；
+- 任何 path 只作为 display metadata 返回，操作使用 opaque ID；
+- SSE 新增 `workspace_resource_invalidated`，只表示需重取，不携带完整 Diff/文件内容；
+- terminal output 永远不进入 SSE；
+- capability flags 增加 review/files/git/terminal，缺少 backend 时 UI 显示 unavailable，不伪装为空数据。
+
+### 9.3 刷新策略
+
+- 正确性依赖 revisioned GET，不依赖 watcher；
+- ToolGateway write/edit receipt、terminal command completion、context activation 触发 resource invalidation；
+- 面板获得焦点时若数据超过 2 秒可刷新；
+- 外部编辑可用 bounded watcher 提示刷新，但 watcher 丢事件不能破坏正确性；
+- Git 和文件请求每 workspace 最多一个并发 refresh，新请求取消旧请求；
+- 不在后台对所有已知项目轮询 Git status。
+
+## 10. 安全、隐私与权限边界
+
+### 10.1 文件与 Git
+
+- 每次读取都以 canonical active workspace 重新做 realpath containment；
+- symlink、rename、删除并发按 fail-closed 处理；
+- 拒绝绝对路径、`..`、NUL、Git pathspec magic 和超长路径；
+- 文件树不跟随 workspace 外 symlink；
+- 敏感文件名 blocklist 与文本 redaction 共用 `src/services/redaction.ts`，避免多套规则漂移；
+- Git 使用 argv，不执行用户提供的 shell string；
+- diff/log/status 输出在 Host 截断、解析和脱敏后才进入浏览器；
+- remote credential、环境变量、authorization、terminal ticket 不进入页面诊断或日志。
+
+### 10.2 终端
+
+- terminal 只接受真实用户手势创建；Agent API 没有 terminal input 能力；
+- 同源 WebSocket 校验 Host、Origin、单次 ticket、连接超时和 terminal ownership；
+- inherited env 采用 allowlist；Host 不把 provider secrets 注入 PTY；
+- terminal 输出不持久化；复制由用户明确触发；
+- 资源上限：4 PTY、2MiB scrollback/PTY、输出速率和 frame size 上限、idle timeout 可配置；
+- 关闭和 Host shutdown 杀死完整 process tree，测试无 orphan；
+- PTY backend 的 native binary、安装脚本和 Node ABI 纳入供应链与 exact-tarball 门禁。
+
+### 10.3 浏览器边界
+
+- 继续只监听 loopback；
+- CSP 保持 `script-src 'self'`，不引入 CDN；
+- 新 WebSocket 不放宽普通 HTTP 的 nonce、Origin、Host 和 content-type 校验；
+- 所有用户可见错误只返回稳定 code + 安全文案，本地详细错误留在 Host diagnostics；
+- E2E 对 HTML、SSE、WS、截图、manifest 和 Host stdout/stderr 执行 opaque secret sentinel 扫描。
+
+## 11. 性能与可恢复性
+
+- 项目、Session、文件、Git log、Diff hunks 均分页，禁止客户端自动 drain 全部页；
+- 左侧项目树和长文件列表使用 windowing；
+- Diff viewer 只渲染 viewport 附近 hunk；单响应默认 ≤ 256KiB；
+- 文件预览单响应默认 ≤ 128KiB，完整读取由显式分页完成；
+- Git status 默认 ≤ 2,000 entries，超出时返回 truncated + nextCursor；
+- Terminal output 使用独立流和 backpressure，不与 transcript/SSE retention 竞争；
+- 面板切换不销毁仍在运行的 terminal，但普通只读面板可释放大对象；
+- 页面刷新从 bootstrap + active context snapshot 重建；无 active Session 时文件/Git 仍可基于 active workspace 工作；
+- `replay_reset` 继续是普通 Workbench SSE 的硬屏障；terminal stream 使用独立 sequence/gap 恢复；
+- Host restart 后只恢复 durable workspace registry 和 UI 可重取状态，不宣称恢复 PTY 进程。
+
+## 12. 无障碍与键盘
+
+### 12.1 必须支持
+
+- `Cmd/Ctrl+B`：切换项目导航；
+- `Cmd/Ctrl+Shift+B`：切换右侧工作面板；
+- `Cmd/Ctrl+Shift+1..5`：Agent/审阅/终端/文件/Git；
+- 工作面板展开/折叠按钮保持完整键盘能力；精细宽度调整只由鼠标/触控板分隔条拖动完成；
+- Project tree 使用标准 tree/treeitem 或语义等价的 disclosure + list，方向键行为一致；
+- 面板 tab 使用 roving tabindex；
+- Diff hunk、文件行和 terminal toolbar 均有可感知名称；
+- drawer focus trap、Escape、scrim、焦点恢复；
+- loading/status 用 `aria-live`，持续 terminal output 不逐字播报；
+- 200% zoom 后控件不重叠，主要功能不丢失；
+- reduced motion、forced colors/high contrast 有专门测试。
+
+### 12.2 可读性门槛
+
+- 正文最小 12px/1.5；辅助文字最小 11px/1.4；
+- 代码和 terminal 默认 12–13px，可在设置中调整到 11–18px；
+- 不用只靠红/绿区分 staged、unstaged、conflict；
+- icon-only control 必须有 accessible name 和 tooltip；
+- selected、focus、running、warning 均有不同视觉轮廓。
+
+## 13. 实施切片
+
+### Phase 0：合同与风险验证（P0）
+
+交付：
+
+- 冻结本计划和 `docs/architecture/v0.3.1-web-api.yaml`；
+- 记录当前 320/390/760/1180/1440 截图和性能基线；
+- 完成 PTY dependency spike，验证 Node 22.12/24/26 exact-tarball install/run；
+- 定义 WorkspaceRegistry、ContextRevision、RepositoryRevision、FileRevision、Terminal protocol；
+- threat model：path traversal、symlink escape、Git argv、terminal ticket、secret output、orphan process。
+
+退出条件：协议引用全部解析；PTY backend 在三条 Node 线均有真实 proof；否则 v0.3.1 terminal 不能标记完成。
+
+### Phase 1：Shell 与可变宽右栏（P0）
+
+交付：
+
+- `WorkbenchShell`、`WorkPanelDock`、一级 icon rail、Agent 二级导航；
+- 320–720px IDE 式指针 resize、local preference、断点切 drawer；
+- 从 `Inspector.tsx` 拆出 Agent 子面板；
+- 统一 panel states 和焦点管理；
+- 视觉 regression：expanded/collapsed/min/default/max/overlay。
+
+退出条件：现有 Goal/活动/能力/诊断不回归；桌面/移动所有交互键盘可达。
+
+### Phase 2：多项目左栏与原子 Context（P0）
+
+交付：
+
+- WorkspaceRegistryV1 与迁移；
+- 多项目 ProjectTree、lazy Session pages、search、pin/recent；
+- inactive workspace Session read endpoint；
+- 原子 `/context/activate` 与恢复；
+- virtualized list 和 active/running/approval/Git summary badges。
+
+退出条件：至少三个真实项目可同时展示；跨项目 Session 激活无中间错误归属或命令误投。
+
+### Phase 3：文件、Git 与审阅（P0）
+
+交付：
+
+- FileReadService、GitReadModelService、ReviewService；
+- 文件树/预览、Git status/log、Review overview/diff；
+- revision-bound paging、stale recovery、output budgets；
+- “发送审阅反馈到 Composer”；
+- Git/file invalidation 与手动 refresh。
+
+退出条件：真实仓库的 staged/unstaged/untracked/conflict、large diff、binary、symlink 和非 Git 项目均验证。
+
+### Phase 4：真实 PTY 终端（P0）
+
+交付：
+
+- TerminalManagerV1、PTY backend、同源 WebSocket ticket handshake；
+- terminal tabs、fit/resize、copy/paste guard、reconnect/lost/close；
+- env scrub、process tree cleanup、buffer/backpressure/resource limits；
+- terminal accessibility 与 light/dark tokens。
+
+退出条件：交互 shell、ANSI、resize、长输出、刷新重连、Host shutdown、workspace switch、无 orphan 全部通过。
+
+### Phase 5：专业 UI 收口与发布证据（P0）
+
+交付：
+
+- semantic tokens、字号/间距/密度、全状态矩阵；
+- light/dark/forced colors/reduced motion；-真实 installed-tarball Chrome E2E 和截图；
+- Node 22.12/24/26 同一 tgz receipt；
+- README、CHANGELOG、迁移和操作说明。
+
+退出条件：第 15 节所有 release gate 为 GO。
+
+### P1（v0.3.1 后续，不阻塞本计划 P0）
+
+- 左侧拖动排序、自定义分组；
+- 文件全文搜索和只读 symbol outline；
+- Git stage/unstage/commit 的独立受控 mutation 方案；
+- Diff inline comment 持久化；
+- terminal command history preference；
+- 左栏宽度调整；
+- 项目级面板布局 profile。
+
+### P2
+
+- 远端 PR/Issue/CI 集成；
+- 多 Runtime 并发项目；
+- 内置代码编辑器和 LSP；
+- 可自由停靠的多面板布局；
+- terminal session durable checkpoint。
+
+## 14. 测试方案
+
+### 14.1 单元与合同测试
+
+建议新增：
+
+- `tests/web-workspace-registry.test.ts`：迁移、CAS、删除目录、并发写；
+- `tests/web-context-transition.test.ts`：workspace + session 原子切换、rollback、TOCTOU；
+- `tests/web-file-service.test.ts`：containment、symlink、sensitive file、binary、paging、stale cursor；
+- `tests/web-git-read-model.test.ts`：unicode/rename/conflict/detached/upstream/large status；
+- `tests/web-review-service.test.ts`：Diff budget、revision、verification receipts；
+- `tests/web-terminal-manager.test.ts`：ticket、ownership、env scrub、buffer、close、orphan；
+- `tests/web-layout-preferences.test.ts`：schema、clamp、invalid local value；
+- `tests/web-protocol.test.ts`：全部新增 discriminated schema 和拒绝路径。
+
+### 14.2 组件与可访问性测试
+
+- ProjectTree 键盘、展开/折叠、virtualization、active identity；
+- Resize gutter 的鼠标/触控板 drag、双击复位和边界 clamp；
+- Work panel tab/focus/persistence；
+- Diff viewer hunk navigation；
+- terminal toolbar 和 screen-reader mode；
+- 主题、200% zoom、reduced motion、forced colors。
+
+### 14.3 真实 E2E
+
+建议新建：
+
+| 场景 ID     | 真实旅程                                                                                |
+| ----------- | --------------------------------------------------------------------------------------- |
+| WEB31-P0-01 | packaged bootstrap + 三项目可见 + lazy Session page                                     |
+| WEB31-P0-02 | 跨项目 Session 原子切换 + 命令只落目标 Session                                          |
+| WEB31-P0-03 | 鼠标/触控板分隔条 min/default/max 拖动 + 双击复位 + refresh persistence；无键盘调宽入口 |
+| WEB31-P0-04 | Agent 旧能力迁移无回归                                                                  |
+| WEB31-P0-05 | 文件树、文本分页、binary、敏感文件和 symlink escape                                     |
+| WEB31-P0-06 | Git clean/dirty/staged/untracked/conflict/log/detached                                  |
+| WEB31-P0-07 | Review Diff + selected hunk 送入 Composer                                               |
+| WEB31-P0-08 | 真实 PTY input/output/ANSI/resize/tab/close                                             |
+| WEB31-P0-09 | terminal refresh reconnect、gap、Host restart lost、无 orphan                           |
+| WEB31-P0-10 | SSE/WS 并存、对话流不被 terminal 长输出挤掉                                             |
+| WEB31-P0-11 | 1180/760/390/320 drawer、焦点、200% zoom                                                |
+| WEB31-P0-12 | light/dark/reduced-motion/axe/secret sentinel                                           |
+
+E2E 必须从同一个 source-clean tgz 安装，使用真实 Chrome、真实 Git fixture、真实 PTY 和真实 Host；
+不能用 DOM 注入伪造 Git/文件/terminal 状态。截图裁剪到产品窗口，不记录绝对路径、terminal 原始输出或 secret。
+
+### 14.4 性能测试
+
+- 100 项目 × 每项目 200 Session 的列表与搜索；
+- 100k 文件的合成树，验证 lazy page 和 DOM 上限；
+- 2,000 changed files、50MiB raw diff，验证首屏预算和 pagination；
+- 10MiB terminal burst，验证 backpressure、UI 帧率和 transcript 独立性；
+- cold Host / warm Host 分别记录 workspaces、sessions、Git、files、diff；
+- 计数器包括 Git process count、bytes read、items parsed、DOM nodes、WS buffered bytes。
+
+## 15. 验收标准与 Release Gate
+
+### 15.1 Given / When / Then
+
+#### AC-01 右侧工程能力
+
+Given 一个有 Git 变更、文件、验证结果和可用 shell 的真实项目，When 用户依次打开右侧 Agent、审阅、
+终端、文件和 Git，Then 每个入口展示对应 Host 权威数据，终端可真实交互，且没有通过解析 transcript
+或 Tool 文本伪造状态。
+
+#### AC-02 可变宽右栏
+
+Given 桌面布局，When 用户用鼠标或触控板拖动分隔条，Then 右栏在
+`320..min(720, viewport - 280 - 560)` 的合法范围内变化；1440px 下上限为 600px，1560px 及以上可达
+720px，中间列始终不小于 560px；刷新后恢复偏好，切到窄屏变 drawer，返回桌面仍恢复该偏好宽度。
+
+#### AC-03 多工作区左栏
+
+Given 至少三个已注册项目，其中一个无 Session、一个非 active、一个含运行 Session，When 页面启动，
+Then 三个项目都可见；展开项目只加载该项目 Session；点击非 active 项目 Session 后 workspace + session
+原子切换，Composer 在完成前禁用，任何命令都不会落到错误 Session。
+
+#### AC-04 专业 UI
+
+Given dark/light、320–1440px、100%/200% zoom 和键盘/屏幕阅读器，When 用户完成项目切换、面板切换、
+Diff 导航、terminal 创建/关闭和发送消息，Then 无横向溢出、焦点丢失、不可达操作、低对比度阻断或
+只有颜色的状态表达。
+
+#### AC-05 安全边界
+
+Given workspace 外 symlink、sensitive filename、恶意 Git path、过期 terminal ticket 和 secret sentinel，
+When 请求文件/Git/terminal API，Then Host fail-closed，浏览器、SSE、WS 普通诊断、截图和证据中 sentinel
+出现 0 次，且无 workspace 外读取或 orphan process。
+
+#### AC-06 性能
+
+Given 第 14.4 节的规模 fixture，When 打开项目、Git、文件、Diff 和终端，Then 满足第 2.2 节 p95、DOM、
+bytes 和帧率门槛，不预取全部集合，不把 terminal output 放入 Workbench SSE。
+
+### 15.2 发布必须同时满足
+
+- `npm run lint`、`npm run build`、完整 Jest、Web/E2E TypeScript、Prettier、`git diff --check`；
+- OpenAPI parse/ref/operationId/security/requestId/cursor/revision 自动检查；
+- WEB31-P0-01..12 全部真实 Chrome GO，无 skip/expected-fail；
+- Node 22.12、24.0、26.0 使用**同一个** source-clean tgz，runtime + critical Web/PTY journey 全 GO；
+- terminal native dependency 在三线都能 clean install，不依赖开发机已有 binary；
+- axe blocking 0，console/page/HTTP5xx/secret/dropped event/orphan process 计数 0；
+- package version、README、CHANGELOG、migration、截图、receipt digest 一致；
+- 当前 live v0.3.0 不作为 v0.3.1 发布证明。
+
+## 16. 风险与缓解
+
+| 风险                                 | 影响                             | 缓解                                                                        |
+| ------------------------------------ | -------------------------------- | --------------------------------------------------------------------------- |
+| PTY native dependency 不支持 Node 26 | v0.3.1 无法正式支持真实 terminal | Phase 0 先做 exact-tarball spike；失败即 release NO_GO，不降级成伪终端      |
+| 多项目 UI 被误解为多 Runtime         | 命令落错项目或资源竞争           | 单 active context、原子 activate、contextRevision、清晰 running 状态        |
+| 文件/Git API 扩大本地数据暴露        | workspace 外读取或 secret 泄漏   | opaque ID、realpath containment、敏感文件策略、统一 redaction、sentinel E2E |
+| 大仓库使 Git/文件树阻塞 Host         | 对话和 Composer 卡顿             | worker/service 隔离、timeout、分页、取消、并发 1、性能 counters             |
+| 右侧功能过多                         | 导航复杂、窄宽不可用             | 一级 5 入口，现有四项收进 Agent；窄宽 icon rail；统一面板 shell             |
+| resize 导致布局抖动                  | 输入体验下降                     | CSS variable + pointer capture；pointerup 才持久化；最小中栏门槛            |
+| terminal 输出含敏感信息              | 浏览器/证据泄漏                  | 明示特权表面、env scrub、非持久、禁入日志/receipt、截图不捕获原始输出       |
+| watcher 丢事件                       | stale Git/文件状态               | revisioned GET 为权威；watcher 只 invalidation；focus/explicit refresh 收敛 |
+
+## 17. 文件级实施建议
+
+预计新增或重构：
+
+- `web/src/layout/WorkbenchShell.tsx`
+- `web/src/layout/WorkPanelDock.tsx`
+- `web/src/layout/WorkPanelResizeHandle.tsx`
+- `web/src/components/projects/ProjectNavigator.tsx`
+- `web/src/components/agent/AgentPanel.tsx`
+- `web/src/components/review/ReviewPanel.tsx`
+- `web/src/components/terminal/TerminalPanel.tsx`
+- `web/src/components/files/FileExplorerPanel.tsx`
+- `web/src/components/git/GitPanel.tsx`
+- `web/src/components/shared/*`
+- `web/src/state/layout-preferences.ts`
+- `src/services/workspace-registry.ts`
+- `src/web/workspace-file-service.ts`
+- `src/web/git-read-model-service.ts`
+- `src/web/review-service.ts`
+- `src/web/terminal-manager.ts`
+- `src/web/terminal-server.ts`
+- `docs/architecture/v0.3.1-web-api.yaml`
+- `docs/test/v0.3.1-web-workbench-e2e-plan.md`
+- `docs/migration/v0.3.0-to-v0.3.1.md`
+
+现有 `WorkspaceRail.tsx` 和 `Inspector.tsx` 应迁移为薄入口或删除，不能保留两套同时维护的 Shell。
+`App.tsx` 只做 composition、global dialog 和 recovery boundary，不继续承载面板业务状态。
+
+## 18. 需求追踪矩阵
+
+| 用户要求                                  | 方案位置      | 验收证据                                    |
+| ----------------------------------------- | ------------- | ------------------------------------------- |
+| 右侧参考 Codex，支持审阅、终端、文件、Git | 第 4、5、9 节 | WEB31-P0-04..10、AC-01、AC-05               |
+| 右侧边栏可变宽                            | 第 6 节       | WEB31-P0-03、AC-02                          |
+| 左侧参考 Codex，支持多工作区/项目展示     | 第 7 节       | WEB31-P0-01..02、AC-03                      |
+| UI 更专业                                 | 第 8、12 节   | WEB31-P0-11..12、AC-04、视觉状态矩阵        |
+| 方案写入 docs                             | 本文件        | 文件存在、Markdown/链接/whitespace 检查通过 |
+
+只有当以上五行都有当前 source、真实运行和 release receipt 证据时，v0.3.1 Web Workbench 优化才算完成。