@orion-agents/orion-code 0.3.1 → 0.3.2

package/docs/plan/v0.3.2-web-workbench-layout-and-composer-plan.md

@@ -0,0 +1,869 @@
+# Orion Code v0.3.2 Web Workbench 布局与 Composer Control Center 开发计划
+
+> 版本：v0.3.2
+> 状态：Proposed / 待评审
+> 日期：2026-08-30
+> 基线：`v0.3.1` 分支，`2274639bfc9b50e17cf7fbcd6fa6d1846fd18515`
+> 交付类型：Web Workbench 产品增量，不改变 Orion Code 的本地优先和单活动 Runtime 边界
+
+## 0. 决策摘要
+
+v0.3.2 把 v0.3.1 的“专业三栏工作台”继续向可控、可解释的 Agent 工作台推进，核心交付为：
+
+1. 左侧项目导航升级为可折叠的 48px rail 与 `240–480px` 可变宽面板；宽屏支持鼠标/触控板直接拖动，窄屏自动成为抽屉；
+2. Composer 底部改造成统一 Control Center：工作模式、权限、模型/推理强度、Context 和发送操作集中在一行；
+3. `BUILD / PLAN / AUTO` 从三枚并排按钮改为带说明和状态的下拉菜单；
+4. 新增会话级权限下拉框，清楚显示 `Ask / Allow / Deny`、有效来源和 AUTO 的覆盖关系；
+5. 新增会话级模型与推理强度切换，复用 Runtime 的事务式 ModelCoordinator，不修改项目默认模型；
+6. 新增精确 Context 占用环与详情弹层，区分 provider 计数和估算值；
+7. 纳入四项对标优化：结构化 Context 引用、Plan 审核闸门、可编辑队列、会话草稿恢复；
+8. 所有控制 mutation 使用 requestId、workspace/session/context/control revision，失败不产生跨项目或半提交副作用；
+9. 以真实安装包、真实 Chrome、真实 Runtime/ToolGateway 和确定性双模型 provider 完成 E2E，不能以静态截图代替行为证明。
+
+本计划只定义 v0.3.2 的产品、架构和验收合同。版本号、分支、源码、OpenAPI、测试与发布配置在计划评审通过后分阶段实施。
+
+## 1. 输入、对标与借鉴边界
+
+### 1.1 Orion v0.3.1 真实基线
+
+本计划建立在当前源码上，而不是从设计稿重新想象：
+
+- `web/src/App.tsx` 已支持左栏整体展开/隐藏以及右侧工作面板偏好；
+- `web/src/state/layout-preferences.ts` 已有右栏 `320–720px` clamp、持久化和中栏最小宽度约束；
+- `web/src/components/Conversation.tsx` 仍用三枚按钮展示 BUILD/PLAN/AUTO；
+- 当前 Composer 没有会话级权限、模型和 Context 控制；
+- `src/runtime/model-coordinator.ts` 已提供模型 prepare/commit/rollback，以及切换到小窗口模型前的 compact preflight；
+- `src/services/model-context.ts` 已提供 `ContextUsageSnapshot`，包含 used、window、safe budget、阈值、来源和 auto-compact 状态；
+- `docs/architecture/agent-mode-permission-contract.md` 已冻结“工作模式与权限是两个独立轴”；
+- `docs/architecture/v0.3.1-web-api.yaml` 已有 context/session CAS、幂等命令与恢复快照，可作为 v0.3.2 扩展基础。
+
+### 1.2 用户提供的 Codex 视觉参考
+
+用户提供的截图只作为交互层级参考，不是隐藏需求或可复制资产。可借鉴点是：
+
+- Composer 是一个连续卡片，输入区和控制行属于同一视觉容器；
+- 左侧是“添加 Context/附件”和权限状态；
+- 右侧是模型/推理强度、语音入口和发送；
+- 当前选择以短标签显示，详细解释放在弹层，而不是把所有选项平铺在主界面。
+
+Orion 不复制 Codex 的商标、图标、颜色、文案或未公开协议。截图中的麦克风不自动进入 v0.3.2；没有可靠语音输入链路前不展示无效按钮。
+
+### 1.3 DeepSeek Harness 固定源码参考
+
+参考仓库：`/Users/hope/ai-project/deepseek-harness`，固定提交 `b150a55`。
+
+已核验并可借鉴：
+
+- `packages/client/ui-layout/src/client/AppFrame.tsx`：左右 splitter 使用 pointer capture 和 rAF 节流；
+- `packages/client/ui-layout/src/client/columns.ts`：左栏 56px rail、264–420px 拖动和中栏保护的 concession chain；
+- `packages/client/ui-conversation/src/client/skeleton/InputBar.tsx`：权限、Plan、模型、Context 与发送处于同一工具行；
+- `packages/client/ui-conversation/src/client/skeleton/PermissionSelect.tsx`：权限菜单和高风险确认；
+- `packages/client/ui-model-selection/src/client/ModelSelect.tsx`：模型与 effort 二级菜单、Host 目录、失败保留 last-good；
+- `packages/client/ui-conversation/src/client/skeleton/ContextMeter.tsx`：Context 占用环与详情弹层；
+- `packages/client/ui-user-questions/src/client/PlanReviewPanel.tsx`：Plan 批准、继续规划和反馈的交互分离；
+- `apps/web/tests/reference-composer.e2e.ts`、`queue-actions.e2e.ts`：结构化引用和可编辑队列的真实浏览器合同。
+
+Orion 不照搬 DSH 的 Cordis 插件、两条下行 WebSocket 或权限 preset。Orion 继续使用自己的 React shell、POST control、可重放 SSE、ToolGateway 和 Ask/Allow/Deny 语义。
+
+### 1.4 WorkBuddy 产品参考
+
+本机只读核验 `/Applications/WorkBuddy.app` v5.3.14。其闭源 bundle 只能作为产品观察，不能作为源码权威或复制来源。可借鉴的原则是：
+
+- Chat input 将 mode、permission、model、expert/skill、mention、command、attachment 作为可组合 provider；
+- Ask/Craft/Expert 等工作姿态在输入区可见，而详细能力由 Runtime/模板承载；
+- Skills、专家、连接器和自动化不是散落设置，而是任务 Context 的可选择来源；
+- 长任务以明确状态、历史和可恢复控制呈现。
+
+v0.3.2 只借鉴“可组合输入控制面”和“Context 来源可见”这两个原则，不引入 WorkBuddy 自动化平台、专家市场或云端账号体系。
+
+## 2. 问题定义
+
+### 2.1 左侧导航仍是固定宽度
+
+v0.3.1 已能隐藏左栏，但展开宽度固定为 280px：
+
+- 长项目名、分支、Session 标题容易截断；
+- 小屏笔记本上又会占用过多中栏；
+- 左右面板的交互不一致；
+- 折叠后完全消失，缺少 IDE 常见的常驻 rail 和恢复位置。
+
+### 2.2 Composer 控制分散且缺乏解释
+
+当前模式在 Composer 中平铺，权限只在 header/Settings 显示，模型切换依赖 `/model`，Context 只在诊断页展示。用户在发送前无法快速回答：
+
+- 这一条请求会以 BUILD、PLAN 还是 AUTO 运行？
+- 当前工具策略来自 Session、Project 还是 AUTO？
+- 下一轮实际使用哪个模型和 effort？
+- Context 已使用多少，是否即将 compact？
+- 当前草稿附带了哪些文件、Diff、Skill 或历史 Session Context？
+
+### 2.3 PLAN 仍缺少真正的人机审核节点
+
+模式选择如果只改变提示词，而生成 Plan 后继续自动进入执行，会让“PLAN”在用户心智上不可信。对标 Codex/DSH 后，v0.3.2 应让 Plan 成为可审核的 durable state，而不是一段普通回复。
+
+### 2.4 长任务控制仍不完整
+
+当前已经有 queue、Steer、Goal 和工具活动，但还缺：
+
+- 编辑或重新排序排队消息；
+- 刷新后的草稿恢复；
+- 结构化 Context 的增删和 token 成本可见；
+- 控制切换失败后的 last-good 与重试路径。
+
+## 3. 目标、指标与非目标
+
+### 3.1 P0 目标
+
+- 左栏可以展开、折叠、鼠标/触控板拖动，桌面偏好刷新后恢复；
+- 左栏拖动范围 `240–480px`，默认 `280px`，折叠 rail `48px`；
+- 中栏在正常桌面布局保持至少 `560px`；不足时先收缩/折叠右栏，再进入抽屉布局；
+- 模式、权限、模型/effort 和 Context 都能在 Composer 控制行查看和操作；
+- 模型切换复用事务式 Runtime 路径，小上下文切换需要 compact preflight；失败恢复原模型；
+- Context 百分比和 token 数来自 Host typed projection，不由浏览器分析 transcript 猜测；
+- 所有操作在活动会话、workspace 和 context revision 不匹配时 409 且零副作用；
+- 320、390、760、1024、1180、1440px 均无页面级横向滚动；
+- 真实 E2E 的 console error、page error、HTTP 5xx、secret finding、dropped event 均为 0。
+
+### 3.2 同版本必交付的优化项
+
+以下不是未来愿望，而是 v0.3.2 的 Required scope：
+
+1. 结构化 Context launcher 与可移除 Context tray；
+2. durable Plan review gate；
+3. queue 编辑、删除和上下移动；
+4. 同一浏览器标签页内的 Session 草稿恢复；
+5. Composer 控制失败的 last-good、pending、retry 和 rollback 反馈；
+6. 命令、Context 与能力入口的统一 `+` 菜单。
+
+### 3.3 非目标
+
+v0.3.2 不包含：
+
+- 语音输入或语音转写；
+- 任意本机文件上传、workspace 外文件引用；
+- 多模型并行比较或自动路由；
+- 多 Agent Runtime 同时运行；
+- WorkBuddy 式自动化、专家市场或云同步；
+- 自由停靠、任意拆分的 IDE 布局；
+- 浏览器端编辑文件、stage/commit/push；
+- 把 `Allow` 重命名为“完全访问”。Orion 的 Allow 仍受 workspace containment、硬拒绝、sandbox 和 capability policy 约束；
+- 把 PLAN 当作安全模式。PLAN 与 BUILD 使用同一工具注册表和权限轴；
+- 把 UI Context breakdown 通过分析 transcript 或工具文案伪造出来。
+
+## 4. 目标信息架构
+
+### 4.1 桌面布局
+
+```text
+┌────┬───────────────────────┬─┬──────────────────────────────────────┬─┬──────────────┐
+│rail│ Project / Session nav │││ Conversation                         ││ Work panel   │
+│48px│ 240–480px             │││ min 560px                            ││ 320–720px    │
+│    │ pointer resize        │││                                      ││ or 48px rail │
+└────┴───────────────────────┴─┴──────────────────────────────────────┴─┴──────────────┘
+```
+
+展开左栏时，48px rail 与内容合并为一个 `240–480px` 面板，不额外占 48px。折叠时保留 48px rail。
+
+### 4.2 Composer
+
+```text
+┌─────────────────────────────────────────────────────────────────────────────┐
+│ [Context: file.ts] [Review: hunk 2]                          [remove all]    │
+│ 描述任务，或输入 / 查看命令…                                                  │
+│                                                                             │
+│ [+] [BUILD ▾] [ASK ▾]                 [GLM-5.2 · High ▾] [◔ 42%] [↑/■]    │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+控制顺序体现发送前的决策路径：
+
+- 左侧：添加 Context、选择工作模式、选择权限；
+- 右侧：选择实际模型/effort、检查 Context 压力、发送/停止；
+- running 时保留 Stop、Steer 和 Queue，不让控制行被审批卡或队列撑出视口。
+
+### 4.3 窄屏
+
+- `≤ 760px`：左导航和右工作面板都成为互斥 modal drawer；
+- Composer 控制行保持一行，低优先级说明收进 `…`，模式/权限/模型仍可达；
+- Context tray 横向滚动，不增高到覆盖输入框；
+- drawer 打开时主区 inert，Escape、scrim、关闭按钮均可关闭并恢复焦点；
+- 进入窄屏不改写桌面左/右宽度和展开偏好。
+
+## 5. 左侧项目导航设计
+
+### 5.1 三种状态
+
+| 状态      | 宽度      | 内容                                                                          |
+| --------- | --------- | ----------------------------------------------------------------------------- |
+| Expanded  | 240–480px | 品牌、项目搜索、Project/Session tree、创建 Session、Runtime 状态、设置        |
+| Collapsed | 48px      | 展开按钮、新建 Session、活动项目入口、设置、Runtime 状态；全部有 tooltip/名称 |
+| Drawer    | 自适应    | `min(storedWidth, viewport - 42px)`，完整内容；移动端状态不覆盖桌面偏好       |
+
+### 5.2 拖动行为
+
+- 分隔条是 8px 透明 hit strip，视觉线保持 1px；
+- 仅主鼠标按钮开始拖动，使用 pointer capture；
+- pointer move 经 rAF 合帧，只修改 CSS variable，不在每一帧写 storage；
+- pointerup/cancel/lost capture 时提交一次偏好；
+- 双击恢复 280px；
+- 拖动期间关闭 grid transition，防止边缘落后于指针；
+- 折叠状态不显示 splitter；
+- 不提供键盘逐像素调宽。键盘用户通过可访问的展开/折叠按钮使用完整功能；
+- `prefers-reduced-motion` 下移除折叠动画，不移除状态变化。
+
+### 5.3 宽度求解
+
+新增纯函数 `computeWorkbenchColumns()`，输入 viewport、左右偏好和展开状态，输出三栏实际宽度。求解顺序：
+
+1. 保留展开左栏的合法偏好；
+2. 右栏从偏好收缩至 320px；
+3. 仍不足时把右栏收成 48px rail；
+4. 保持中栏至少 560px；
+5. 达到 760px 以下时左栏自动进入 drawer；
+6. 任一 derived collapse 不改写已保存偏好，窗口重新变宽后自动恢复。
+
+### 5.4 偏好迁移
+
+新增 `WorkbenchLayoutPreferenceV2`：
+
+```ts
+interface WorkbenchLayoutPreferenceV2 {
+  schemaVersion: 2;
+  projectNavigation: {
+    expanded: boolean;
+    widthPx: number;
+  };
+  workPanel: {
+    expanded: boolean;
+    widthPx: number;
+    activePanel: 'agent' | 'review' | 'terminal' | 'files' | 'git';
+    agentPanel: 'goal' | 'activity' | 'integrations' | 'diagnostics';
+  };
+}
+```
+
+- 从 `orion.web.work-panel.v1` 迁移右栏值；
+- 左栏无旧偏好时使用 280px + expanded；
+- 非法 JSON、NaN、越界值回退默认；
+- localStorage 失败不影响 Workbench；
+- 偏好只存尺寸/面板 ID，不存项目路径、Session 文本或草稿。
+
+## 6. Composer Control Center
+
+### 6.1 工作模式下拉框
+
+触发器显示 `BUILD`、`PLAN` 或 `AUTO`，菜单用 `menuitemradio` 展示：
+
+| 模式  | 用户文案             | Runtime 语义                                                     |
+| ----- | -------------------- | ---------------------------------------------------------------- |
+| BUILD | 实现、修改和验证     | 完整工具集；遵循当前权限策略和 durable grants                    |
+| PLAN  | 调研并生成可审核计划 | 完整工具集；不自动执行生成的 Plan；进入 Plan review gate         |
+| AUTO  | 无人值守执行         | 硬拒绝、显式 deny 和安全边界仍优先；其余 invocation 不弹交互审批 |
+
+规则：
+
+- 模式与权限保持两个独立控件；
+- idle 时立即生效，active turn 时显示 `BUILD → PLAN` 等 pending 状态，并在下一逻辑请求边界生效；
+- 进入 AUTO 需要风险确认，文案明确“prompt-free 不等于 policy-free”；
+- mutation 失败恢复 Host last-good，不保留客户端乐观值；
+- 菜单 footer 提供“查看模式与权限说明”，打开本地帮助，不跳外部网页。
+
+### 6.2 权限下拉框
+
+P0 采用“当前 Session override + Project default”的明确作用域：
+
+- `Use project default`：清除 Session override；
+- `Ask`：需要时询问；
+- `Allow`：减少常规询问，但仍受硬拒绝、workspace、sandbox 和 capability policy 约束；
+- `Deny`：默认拒绝没有更强显式授权的工具调用。
+
+触发器显示有效值和来源，例如：
+
+- `ASK · Project`
+- `ALLOW · Session`
+- `DENY · Session`
+- `AUTO · hard policy active`
+
+规则：
+
+- 选择 Allow 必须经过与 Settings 相同的风险确认；
+- Session override durable 保存，恢复 Session 后保持；
+- Settings 继续管理 Project default；二者不能互相伪装；
+- 已经弹出的 approval 不因切换 policy 自动通过或拒绝；
+- active turn 中的新 policy 从下一次工具 admission 生效；
+- AUTO 下仍展示保存的 Ask/Allow/Deny，但明确当前调用由 AUTO precedence 决定；显式 Deny 仍应高于 AUTO；
+- 每个 tool card 继续显示 authorization provenance。
+
+### 6.3 模型与推理强度下拉框
+
+触发器显示 `模型名 · Effort`，弹层分两层：
+
+1. 根层：Model、Reasoning effort 两行；
+2. Model 层：按 provider 分组，显示名称、说明、上下文窗口和 capability；
+3. Effort 层：只显示该模型由 Host 声明的选项，不在浏览器维护私有枚举；
+4. 模型超过 8 个时提供本地过滤；不可用 provider 分组显示错误和 Retry，其他分组仍可使用。
+
+权威规则：
+
+- current selection、catalog、effort 和 capability 均来自 Host；
+- Composer 切换只更新当前 Session，不修改 Settings 中的 Project default；
+- 选择成功后更新 Session metadata、LLM client、effort context 和 context budget；
+- active turn 中不替换正在执行的模型，切换进入 pending 并在逻辑边界提交；
+- 切换到更小上下文窗口时必须运行 ModelCoordinator compact preflight；
+- compact、provider client、metadata 任一步失败都回滚到原 selection；
+- 浏览器只收到 credential slot 状态，不收到 API key、base auth header 或 secret；
+- subagent/不支持切换的 Session 显示原因并禁用，而不是静默隐藏选择结果。
+
+### 6.4 Context Meter
+
+控制行使用 14–16px 环形占用指示器，点击打开 264–300px 弹层。
+
+P0 展示 Host 已有的精确字段：
+
+- `usedTokens / safeInputBudget` 和百分比；
+- raw model context window；
+- reserved output tokens 与 safety margin；
+- 数据来源：provider、provider-adjusted 或 estimated；
+- warning/auto-compact 阈值和 auto-compact 是否启用；
+- 当前模型 ID；
+- 最近一次 compact 状态和“立即压缩”操作（只有 Runtime 支持时出现）。
+
+显示规则：
+
+- provider 计数直接显示；estimated 值使用 `~` 和“估算”说明；
+- 没有 capacity 时不画 0% 假环，显示不可用状态；
+- 模型切换期间清除旧 capacity，不能短暂把旧模型窗口显示为新模型；
+- 接近 warning 阈值改变文字/图标，不只依赖颜色；
+- breakdown 只有 Runtime 提供 system/tools/messages 的同一 revision 计数时才展示；v0.3.2 不从 transcript 反推；
+- Context 数据不得包含 prompt 原文、工具参数、绝对路径或 secret。
+
+### 6.5 `+` Context Launcher
+
+`+` 菜单统一当前分散入口：
+
+- 引用 workspace 内文件或目录；
+- 引用 Review 中的文件/hunk；
+- 引用一个历史 Session 的受控摘要；
+- 选择 user-invocable Skill；
+- 打开命令菜单；
+- 清除当前草稿 Context。
+
+所有项目都生成结构化 `ContextReferenceV1`，而不是把不透明 Markdown 直接拼进 textarea：
+
+```ts
+type ContextReferenceV1 =
+  | { kind: 'file'; id: string; label: string; revision: string }
+  | { kind: 'folder'; id: string; label: string; revision: string }
+  | { kind: 'review'; id: string; label: string; gitRevision: string }
+  | { kind: 'session'; id: string; label: string; digest: string }
+  | { kind: 'skill'; id: string; label: string; digest: string };
+```
+
+Context tray 显示 chip、来源、stale 状态和删除按钮；Host 在 submit admission 时重新校验 workspace、revision、digest 和权限。失效引用应阻止发送并给出修复选项，不能静默发送旧内容。
+
+### 6.6 Running、Steer 与 Queue
+
+- primary action 在 idle 为 Send，在 running 为 Stop；
+- running 时普通 Enter 依当前偏好 Queue，显式 Steer 保留独立按钮；
+- queue 面板固定在 Composer 上方的受限高度内，不能把 textarea 推出视口；
+- queue item 支持编辑、删除、上移和下移；
+- 所有 queue mutation 带 item revision 和 expected session；
+- queue/Steer 切换模式、模型或权限时，必须冻结每条消息实际使用的控制快照，或明确标记“执行时采用最新控制”；v0.3.2 决定采用后者，并在队列头显示说明；
+- interrupted/removed Session 的 queue 不跨 Session 迁移。
+
+## 7. 同版本新增优化
+
+### 7.1 Durable Plan Review Gate
+
+PLAN turn 生成有效 Plan 后进入 `awaiting_review`，不自动排队执行。用户有三个明确操作：
+
+1. `批准并进入 BUILD`：对 exact plan digest 提交 approve，切 BUILD，并从新逻辑请求开始执行；
+2. `继续规划`：保留 PLAN，把反馈作为新用户消息；
+3. `取消计划`：关闭 review，不执行。
+
+Plan review 必须：
+
+- 由 Thread durable event/TurnCommit authority 驱动，刷新/重连后恢复；
+- 包含 plan digest、revision、创建模型、创建时间和当前状态；
+- stale digest 返回 409，绝不批准新 Plan 的旧按钮；
+- 不把“HTTP 202”当批准成功，UI 等待 durable state；
+- approval、Plan review 和 permission approval 是三种不同状态，不共用 requestId 或按钮语义。
+
+### 7.2 会话草稿恢复
+
+- 以 opaque workspaceId + sessionId 保存当前标签页草稿和 ContextReference ID；
+- 使用 `sessionStorage`，不跨浏览器重启或设备同步；
+- 每个草稿上限 256KiB，最多保留 20 个 Session，LRU 淘汰前清除引用对象 URL；
+- send 成功后删除，send 失败保留；
+- Session 删除、workspace 移除或用户“清除草稿”时删除；
+- 草稿不进入 Host 日志、SSE、release receipt 或 telemetry；
+- UI 明示“此标签页草稿”，避免被误解为 durable Session 内容。
+
+### 7.3 控制状态与恢复
+
+- 所有下拉框都显示 loading、pending、last-good、error、retry；
+- Host restart/replay reset 后关闭菜单、暂停 mutation、加载 matching snapshot 后恢复；
+- 多标签页发生 CAS conflict 时，不自动重放高风险选择；刷新 control state 后让用户确认；
+- 控制状态变化写入可审计事件，但不进入模型 transcript；
+- header 只保留运行状态与 Session 名，避免与 Composer 重复显示模式/权限。
+
+### 7.4 快捷键与命令一致性
+
+- `Cmd/Ctrl+B` 继续展开/折叠左栏；
+- 模式、权限、模型的菜单入口有 command palette action，但不增加键盘调宽；
+- `/model`、`/effort`、`/permission` 与 Composer 必须共用相同 service 和 state，不允许两套写入链；
+- Composer 改动后 slash command 的成功/失败会立即投影回 dropdown；
+- `?` 或帮助菜单展示实际可用快捷键，避免靠 placeholder 记忆。
+
+## 8. 响应式与视觉状态
+
+### 8.1 断点
+
+| 容器宽度     | 左栏                          | 右栏                          | Composer                   |
+| ------------ | ----------------------------- | ----------------------------- | -------------------------- |
+| `> 1180px`   | Dock，48px rail 或 240–480px  | Dock/rail，按 concession 求解 | 全控制行                   |
+| `761–1180px` | Dock，必要时 clamp            | modal drawer                  | 完整控件，说明收进 tooltip |
+| `≤ 760px`    | modal drawer，桌面偏好不变    | modal drawer，互斥            | 紧凑触发器 + overflow      |
+| `≤ 390px`    | drawer 宽 `viewport - 42px`   | drawer 宽 `viewport - 42px`   | Context tray 横向滚动      |
+| `320px`      | 无页面横向滚动，44px 控件目标 | 无隐藏关闭按钮                | textarea 和 Send 始终可见  |
+
+优先使用 Workbench 容器的 ResizeObserver，而不是只读取 `window.innerWidth`，使浏览器侧栏、缩放和嵌入窗口都能触发正确求解。
+
+### 8.2 状态矩阵
+
+每个 Composer 控件至少覆盖：
+
+- ready；
+- loading；
+- disabled with reason；
+- pending current → target；
+- success；
+- conflict/stale；
+- provider unavailable；
+- runtime busy/deferred；
+- offline/replay-required；
+- Host restart/recovered；
+- read-only/unconfigured。
+
+## 9. API 与状态合同
+
+### 9.1 新增只读合同
+
+建议新增：
+
+- `GET /api/v1/sessions/{sessionId}/composer-state`
+  - query 必须包含 `workspaceId`、`expectedContextRevision`；
+  - 返回 `controlRevision`、mode、permission、model selection、context usage、plan review、queue summary；
+- `GET /api/v1/sessions/{sessionId}/model-catalog`
+  - cursor 分页；按 provider 分组；返回 Host 声明的 effort/capability/context window；
+  - partial provider failure 不丢弃 last-good 组。
+
+`SessionSnapshot` 同时携带同一 `controlRevision` 的 composer baseline，避免刷新必须先接 SSE 才知道当前控制状态。
+
+### 9.2 新增 mutation 合同
+
+建议新增统一入口：
+
+`POST /api/v1/sessions/{sessionId}/composer-actions`
+
+公共字段：
+
+```ts
+interface ComposerActionBaseV1 {
+  requestId: string; // UUID
+  workspaceId: string;
+  expectedContextRevision: string;
+  expectedSessionId: string;
+  expectedControlRevision: string;
+}
+```
+
+body 使用 `oneOf` + discriminator：
+
+- `set_agent_mode`；
+- `set_permission_override` / `clear_permission_override`；
+- `select_model`，含 modelId + optional effort；
+- `compact_context`；
+- `review_plan`，含 planDigest + approve/continue/cancel；
+- `edit_queue_item` / `move_queue_item` / `remove_queue_item`。
+
+响应必须返回：
+
+- requestId；
+- 新 controlRevision；
+- accepted/deferred/applied；
+- matching composer state；
+- model switch 或 plan review 的 typed receipt；
+- 失败时 RFC 9457 problem code。
+
+### 9.3 错误码
+
+至少冻结：
+
+- `context_revision_conflict`；
+- `active_session_changed`；
+- `composer_control_conflict`；
+- `runtime_busy`；
+- `model_unavailable`；
+- `model_effort_unsupported`；
+- `model_compaction_required`；
+- `model_switch_rolled_back`；
+- `permission_override_rejected`；
+- `plan_review_stale`；
+- `context_reference_stale`；
+- `context_reference_forbidden`；
+- `queue_item_conflict`。
+
+### 9.4 SSE 事件
+
+新增 typed event：
+
+- `composer_state_changed`；
+- `context_usage_changed`；
+- `plan_review_requested`；
+- `plan_review_resolved`。
+
+要求：
+
+- 每个 event 带 sessionId、workspaceId、contextRevision、controlRevision；
+- stale Session event 不得更新当前 Composer；
+- replay_reset 是硬屏障，之后 live event 不能越过 snapshot recovery；
+- Context 高频更新可以 coalesce，但 finalize/阈值跨越必须送达；
+- transient delta 不得挤掉 durable control event 的恢复窗口。
+
+## 10. Runtime 与持久化
+
+### 10.1 Model
+
+- 抽出 Web/TUI 共用 `SessionModelSelectionServiceV1`；
+- 复用 ModelCoordinator 的 resolve、client validation、compact preflight、commit 和 rollback；
+- `updateSessionModel` 与 effort metadata 在同一逻辑事务内提交；
+- 新模型 selection 以 revision/digest 绑定；
+- 恢复 Session 时按 session override > project default > global default 重建。
+
+### 10.2 Permission
+
+- SessionMeta 或 Thread durable state 新增 optional tool-confirmation override；
+- effective policy 同时返回 value 和 source；
+- Project default 仍由 SettingsCoordinator 管理；
+- ToolGateway 每次 admission 捕获 exact policy receipt；
+- 切换不能修改已经 started/pending 的 invocation。
+
+### 10.3 Plan review
+
+- 引入 `PlanReviewStateV1` durable event family；
+- authority 为最新有效 Plan digest + review transition；
+- `approve` 只创建新的执行 logical request，不在 review mutation 内直接跑工具；
+- restart、resume、fork 的继承规则写入迁移文档；fork 默认复制已批准前的 Plan 内容，但不复制 pending approval。
+
+### 10.4 Context references
+
+- 浏览器只持 opaque ID；
+- Host 在 prompt assembly 时解析为 bounded、sanitized、workspace-contained content；
+- file/folder 使用 file read model；review 使用 exact Git revision；Session 引用使用受控摘要；Skill 使用 digest；
+- prompt manifest 记录引用 digest 和 token/byte budget，不记录 secret 原文；
+- stale/forbidden 引用 fail closed。
+
+## 11. 安全与隐私
+
+- Allow/AUTO 风险确认不能用默认 checked checkbox；
+- 权限菜单不得暗示绕过 sandbox、workspace containment 或硬拒绝；
+- 模型目录不包含 API key、auth header、raw provider error body；
+- Context popover不显示 prompt 原文、工具参数、绝对路径或环境变量；
+- Context 引用不能读取 workspace 外 symlink、`.env`、key、credential 或受保护 artifact；
+- 所有 mutation 在 action 前完成 context/session/control CAS；
+- requestId ledger 满时在副作用前 503，不静默淘汰旧幂等记录；
+- SSE、snapshot、problem detail、截图和 E2E evidence 统一运行 secret sentinel 扫描；
+- Draft 只放 sessionStorage；不进入 localStorage、Host、telemetry 或 release evidence；
+- 不从 WorkBuddy bundle复制代码、图标、文案或闭源资源。
+
+## 12. 可访问性
+
+- 下拉触发器使用 button + `aria-haspopup="menu"` + `aria-expanded`；
+- 选项使用 `menuitemradio`/`aria-checked`，不是只改变颜色；
+- Escape 从子层返回根层，再关闭并恢复触发器焦点；
+- Allow/AUTO 风险确认使用 `alertdialog`，首焦点落在说明/确认框；
+- Context popover使用 dialog 语义，百分比有完整 accessible name；
+- left rail 图标全部有名称和 tooltip；
+- 折叠左栏时，若焦点在即将隐藏的内容中，焦点返回 toggle；
+- drawer 主区 inert，Tab 不逃逸，关闭后返回触发器；
+- 控件目标至少 44×44 CSS px；高密度桌面视觉按钮可为 28–32px，但必须有不重叠的 44px hit area；
+- 200% zoom、forced colors、reduced motion、light/dark 均纳入 gate；
+- pointer splitter 不加入伪 slider 语义；键盘替代是展开/折叠，不是逐像素调整。
+
+## 13. 性能与预算
+
+- splitter pointer-to-paint p95 ≤ 16ms，目标 55–60fps；
+- 菜单首次打开 p95 ≤ 100ms，model catalog warm open ≤ 50ms；
+- model catalog 只在首次打开/失效时请求，不能每次 render 请求；
+- Composer state baseline p95 ≤ 250ms，不随 transcript 长度增长；
+- Context event 到 UI p95 ≤ 250ms；
+- Context meter 更新不触发 transcript 列表重渲染；
+- 100 个模型时菜单 DOM ≤ 80 个 option，使用分组窗口或 virtualization；
+- 20 个 Context chip 时 Composer 高度有上限，tray 横向滚动；
+- draft autosave debounce 250ms，单标签总量 ≤ 5MiB；
+- session switch 不预取全部模型 catalog、Context 内容或历史 transcript；
+- release evidence 记录 RPC count、DOM nodes、drag frames、menu latency、SSE dropped events。
+
+## 14. 实施阶段
+
+### Phase 0：版本与合同冻结
+
+交付：
+
+- 评审并冻结本计划；
+- 在干净、已验证的 v0.3.1 release baseline 上创建 `v0.3.2` 实施分支；
+- 对现有 dirty/untracked 文件逐项确认归属，不覆盖用户改动；
+- 更新 OpenAPI 草案、状态机和 error code；
+- 写失败优先的 protocol/layout/model/permission/plan tests。
+
+退出条件：需求—API—测试 ID 一一对应，OpenAPI parse/ref/discriminator/security/CAS 检查通过。
+
+### Phase 1：统一布局求解与左栏
+
+交付：
+
+- WorkbenchLayoutPreferenceV2 与迁移；
+- `computeWorkbenchColumns()`；
+- 共用 pointer splitter primitive；
+- 左栏 48px rail、展开/折叠、240–480px drag、双击复位；
+- 760px drawer 和焦点管理。
+
+退出条件：layout unit + 真实 Chrome 指针拖动、刷新恢复、断点/200% zoom 全通过。
+
+### Phase 2：Composer state 与 UI shell
+
+交付：
+
+- ComposerControlStateV1、snapshot/SSE baseline；
+- mode/permission/model/context 四个触发器；
+- menu primitive、nested pane、pending/last-good/error/retry；
+- header 去除重复 mode/permission chip；
+- 320–1440px responsive toolbar。
+
+退出条件：纯 UI fixture 和 Host-backed state round-trip 通过，无跨 Session stale update。
+
+### Phase 3：模型、权限与 Context Runtime
+
+交付：
+
+- SessionModelSelectionServiceV1；
+- Session permission override + source；
+- typed ContextUsageViewV1；
+- model catalog、model/effort mutation、compact preflight/rollback；
+- AUTO/Allow risk flow与 authorization provenance。
+
+退出条件：双模型真实 provider、真实 ToolGateway、切小窗口 compact、rollback、restart restore 全通过。
+
+### Phase 4：结构化 Context 与 Plan review
+
+交付：
+
+- `+` launcher、Context tray、file/review/session/skill reference；
+- Host prompt assembly validation 与 token budget；
+- durable PlanReviewStateV1 和三种操作；
+- queue edit/move/remove；
+- sessionStorage 草稿恢复。
+
+退出条件：stale/forbidden/secret/refresh/reconnect/多标签 CAS 和 Plan digest race 全通过。
+
+### Phase 5：可访问性、性能与发布证据
+
+交付：
+
+- light/dark/forced-colors/reduced-motion/axe；
+- 性能 budgets 与 counters；
+- source-clean exact tgz；
+- Node 22.12/24/26 同一 tgz 的 critical Chrome evidence；
+- README、CHANGELOG、migration、OpenAPI 和截图。
+
+退出条件：第 17 节 release gate 全部 GO。
+
+## 15. 文件级实施建议
+
+预计新增或重构：
+
+- `web/src/layout/WorkbenchShell.tsx`
+- `web/src/layout/PanelResizeHandle.tsx`
+- `web/src/state/layout-preferences.ts`
+- `web/src/components/projects/ProjectNavigator.tsx`
+- `web/src/components/composer/Composer.tsx`
+- `web/src/components/composer/ComposerControlBar.tsx`
+- `web/src/components/composer/AgentModeMenu.tsx`
+- `web/src/components/composer/PermissionMenu.tsx`
+- `web/src/components/composer/ModelMenu.tsx`
+- `web/src/components/composer/ContextMeter.tsx`
+- `web/src/components/composer/ContextTray.tsx`
+- `web/src/components/composer/PlanReviewCard.tsx`
+- `web/src/components/composer/QueueEditor.tsx`
+- `web/src/state/composer-controls.ts`
+- `web/src/state/draft-store.ts`
+- `src/web/protocol.ts`
+- `src/web/workbench-controller.ts`
+- `src/runtime/session-model-selection-service.ts`
+- `src/runtime/model-coordinator.ts`
+- `src/runtime/agent-runtime-controller.ts`
+- `src/runtime/runtime-protocol-v1.ts`
+- `src/services/session-storage.ts`
+- `src/services/model-context.ts`
+- `docs/architecture/v0.3.2-web-api.yaml`
+- `docs/architecture/agent-mode-permission-contract.md`
+- `docs/migration/v0.3.1-to-v0.3.2.md`
+
+优先拆分 `Conversation.tsx`，避免继续把 timeline、approval、queue 和所有 Composer 控制堆在一个组件中。
+
+## 16. 测试方案
+
+### 16.1 单元与合同
+
+- `tests/web-layout-preferences-v2.test.ts`：迁移、clamp、concession、derived drawer；
+- `tests/web-composer-protocol.test.ts`：oneOf、UUID、CAS、problem code、unknown field rejection；
+- `tests/web-session-model-selection.test.ts`：provider/effort、compact、rollback、metadata；
+- `tests/web-session-permission.test.ts`：override/default/AUTO precedence、pending approval；
+- `tests/web-context-usage.test.ts`：provider/estimated、safe budget、threshold、model reset；
+- `tests/web-context-reference.test.ts`：opaque ID、revision、symlink、sensitive file、budget；
+- `tests/web-plan-review.test.ts`：durable state、approve/continue/cancel、stale digest；
+- `tests/web-queue-editor.test.ts`：edit/move/remove、item revision、wrong Session；
+- `tests/web-draft-store.test.ts`：scope、limit、LRU、send/delete cleanup；
+- reducer tests：replay_reset barrier、stale Session/control revision、last-good rollback。
+
+### 16.2 组件与可访问性
+
+- left rail expanded/collapsed focus and accessible names；
+- pointer splitter drag/double-click/lost capture；
+- nested model/effort menu keyboard and focus return；
+- permission/AUTO alertdialog；
+- Context meter dialog and threshold text；
+- Context tray removal and horizontal overflow；
+- queue editor at 320px；
+- Plan review card screen-reader order；
+- light/dark/forced-colors/reduced-motion/200% zoom。
+
+### 16.3 真实 E2E 场景
+
+| 场景 ID     | 真实旅程                                                                                      |
+| ----------- | --------------------------------------------------------------------------------------------- |
+| WEB32-P0-01 | 左栏 mouse-pointer min/default/max 拖动、双击复位、48px rail、refresh persistence             |
+| WEB32-P0-02 | 左右偏好同时最大时 concession 保持 center ≥560；扩窄窗口自动恢复                              |
+| WEB32-P0-03 | 320/390/760/1024/1180/1440 drawer、互斥、焦点和桌面偏好不被覆盖                               |
+| WEB32-P0-04 | BUILD/PLAN/AUTO 菜单 immediate/deferred、AUTO risk、模式与权限独立                            |
+| WEB32-P0-05 | Session Ask/Allow/Deny/default、Allow risk、AUTO/explicit deny、真实 ToolGateway side effect  |
+| WEB32-P0-06 | 双模型 catalog + effort，切小窗口触发真实 compact；provider/metadata 失败完整 rollback        |
+| WEB32-P0-07 | provider/estimated Context、阈值、auto-compact、模型切换清旧值、手动 compact                  |
+| WEB32-P0-08 | file/review/session/skill Context add/remove/stale/forbidden/secret=0，prompt manifest digest |
+| WEB32-P0-09 | PLAN 生成后不执行；approve/continue/cancel；refresh/restart；stale digest 409                 |
+| WEB32-P0-10 | queue edit/move/remove、Steer、Session 草稿切换/刷新、无跨 Session 串线                       |
+| WEB32-P0-11 | 双 tab control CAS、Host restart、replay_reset、matching snapshot 前 Composer disabled        |
+| WEB32-P0-12 | normal CSP、axe、light/dark/reduced-motion/200% zoom、console/page/HTTP5xx/secret/dropped=0   |
+
+E2E 必须：
+
+- 从 source-clean tgz 安装，不导入源码 Host；
+- 使用真实 Chrome 和 normal CSP，axe 可使用单独 context，但核心旅程不得 `bypassCSP`；
+- 使用 loopback deterministic provider，至少提供大/小两种 context window 和多个 effort；
+- 真实调用 Runtime、ModelCoordinator、compact transaction、ToolGateway、Session storage 和 Thread journal；
+- side effect 以文件、durable event、receipt digest 和 snapshot 核验，不以 UI 文案自证；
+- screenshot 只截 Workbench，对绝对路径和敏感内容脱敏并绑定 manifest digest；
+- 不允许 skip、expected-fail 或 DOM 注入伪造状态。
+
+### 16.4 性能与规模
+
+- 100 项目 × 200 Session，左栏 drag/search 不因列表规模卡顿；
+- 100 model entries、10 provider group、2 partial failure；
+- 20 Context refs、256KiB draft、10 queued messages；
+- 500 次 Context update，验证 coalesce、finalize 和 durable event retention；
+- 50k-turn Session 的 composer-state/context GET 不重放完整 transcript；
+- slow provider + active turn + model pending，验证 UI 和 admission 不死锁。
+
+## 17. 验收标准与 Release Gate
+
+### 17.1 Given / When / Then
+
+#### AC-01 左栏
+
+Given 桌面 Workbench，When 用户用鼠标拖动左侧分隔条，Then 宽度在 240–480px 内跟随指针；中栏不小于 560px；双击恢复 280px；折叠为 48px rail；刷新和窄屏往返后恢复桌面偏好。
+
+#### AC-02 Composer 控制
+
+Given 一个活动 Session，When 用户打开模式、权限、模型和 Context 控件，Then 每个控件显示 Host current/last-good、来源、说明和 pending/error；控件不会遮住 textarea 或发送按钮。
+
+#### AC-03 模型
+
+Given 一个大上下文模型和一个小上下文模型，When 当前 Context 超过小模型 safe budget 并请求切换，Then Host 先提交可验证 compact，再原子切换；compact 或 persistence 失败时原模型、effort、Session metadata 和下一次请求完全不变。
+
+#### AC-04 权限
+
+Given Project default Ask，When Session 选择 Allow，Then该 Session 显示 Allow/Session，其他 Session 仍显示 Ask/Project；硬拒绝、workspace escape 和显式 deny 仍失败，receipt 的 authorization provenance 正确。
+
+#### AC-05 Context
+
+Given provider usage，When turn 流式执行并结束，Then Context 环和 token 详情按 Host projection 更新；estimated 数据有 `~`；模型切换不显示旧 capacity；敏感内容出现 0 次。
+
+#### AC-06 Plan
+
+Given PLAN mode，When模型提交 Plan，Then Runtime 进入 awaiting_review 且没有执行副作用；只有 exact digest 的“批准并进入 BUILD”能创建执行请求；继续规划和取消不会执行。
+
+#### AC-07 结构化引用
+
+Given workspace 文件、Diff hunk、历史 Session 和 Skill，When用户加入 Context 并发送，Then prompt manifest 绑定 exact ID/revision/digest；stale、敏感或越界引用阻止发送且无泄漏。
+
+#### AC-08 恢复
+
+Given两个标签页和一次 Host restart/replay reset，When另一个标签页改变 Session/控制状态，Then stale mutation 409、零副作用；当前页先恢复 matching snapshot，再开放发送；不会自动重放高风险操作。
+
+### 17.2 发布必须同时满足
+
+- `npm run lint`、`npm run build`、完整 Jest、Web/E2E TypeScript、Prettier、`git diff --check`；
+- OpenAPI parse/ref/operationId/discriminator/security/requestId/revision/cursor 自动检查；
+- WEB32-P0-01..12 全部真实 Chrome GO，无 skip/expected-fail；
+- Node 22.12、24.0、26.0 使用同一个 source-clean tgz，critical Web journey 全 GO；
+- console error、warning、page error、HTTP 5xx、secret finding、dropped event、orphan process 均为 0；
+- axe blocking 0，320–1440px 与 200% zoom 无页面横向滚动；
+- package version、README、CHANGELOG、migration、OpenAPI、截图、receipt digest 一致；
+- 本地源码 build 或旧 v0.3.1 运行页面不能作为 v0.3.2 发布证明。
+
+## 18. 风险与缓解
+
+| 风险                           | 影响                          | 缓解                                                                                |
+| ------------------------------ | ----------------------------- | ----------------------------------------------------------------------------------- |
+| 左右都可拖动导致中栏被挤压     | Composer 不可用、控件遮挡     | 纯 column solver、center floor、先让右栏 concession、窄屏 drawer                    |
+| 模型切换跨越 active turn       | 同一 turn 使用两套模型/预算   | logical-boundary pending、exact selection revision、compact preflight、rollback     |
+| 权限 scope 语义混乱            | 一个 Session 操作改变整个项目 | Session override 与 Project default 分层显示，source 进入合同                       |
+| AUTO 被误解为绕过安全          | 高风险工具被错误授权          | 风险确认、explicit deny/hard policy 优先、receipt provenance                        |
+| Context 数字看似精确但实际估算 | 用户对预算产生错误判断        | source 字段、estimated `~`、不做浏览器端 breakdown 推断                             |
+| Plan review 只做 UI 假闸门     | 刷新后继续自动执行            | durable PlanReviewState、digest CAS、执行作为独立 logical request                   |
+| Context reference 读取敏感文件 | 本地秘密泄漏到模型/浏览器     | opaque ID、realpath containment、sensitive deny、sanitized derivative、sentinel E2E |
+| 高频 Context 事件挤掉恢复窗口  | 重连后状态过期                | coalesce transient、durable control retention、snapshot hard barrier                |
+| sessionStorage 草稿含敏感文本  | 同一浏览器 profile 可读取     | 仅当前 tab、上限、显式清除、不跨重启；设置中提供关闭草稿恢复                        |
+| 对标导致范围膨胀               | v0.3.2 无法按期发布           | 非目标冻结；不做语音、自动化、专家市场、多 Runtime、任意上传                        |
+
+## 19. 需求追踪
+
+| 用户需求               | 设计章节       | 主要测试        |
+| ---------------------- | -------------- | --------------- |
+| 左栏展开/折叠          | 5.1            | WEB32-P0-01     |
+| 左栏鼠标拖动           | 5.2            | WEB32-P0-01/02  |
+| 窄屏自动抽屉           | 4.3、8.1       | WEB32-P0-03     |
+| BUILD/PLAN/AUTO 改下拉 | 6.1            | WEB32-P0-04     |
+| 权限下拉               | 6.2            | WEB32-P0-05     |
+| Context                | 6.4、6.5       | WEB32-P0-07/08  |
+| 模型切换               | 6.3            | WEB32-P0-06     |
+| 对齐 Codex             | 1.2、4.2       | WEB32-P0-04..07 |
+| 对齐 DSH               | 1.3、5、6、7.1 | WEB32-P0-01..09 |
+| 对齐 WorkBuddy         | 1.4、6.5、7    | WEB32-P0-08/10  |
+| 其他优化进入 v0.3.2    | 7              | WEB32-P0-08..10 |
+
+## 20. Definition of Done
+
+v0.3.2 只有同时满足以下条件才可称完成：
+
+- 本计划中的 Required scope 全部落地，没有用静态占位控件代替 Host 行为；
+- 左栏、模式、权限、模型、Context、Plan review、Context refs、queue 和 draft 均有失败路径；
+- Web/TUI/slash command 共用同一 model/permission/mode service；
+- OpenAPI、TypeScript 类型、Runtime state、snapshot、SSE 和 UI 文案语义一致；
+- 所有高风险 mutation 具备 context/session/control CAS、幂等和 zero-side-effect negative test；
+- 真实浏览器在 exact installed tgz 上完成 WEB32-P0-01..12；
+- Node 22.12/24/26 同一 artifact 的证据进入最终 release receipt；
+- 文档、迁移、截图和用户帮助完成；
+- 没有覆盖当前工作树中用户拥有的未提交文件；
+- 计划、代码 diff 或本地页面看起来正常，都不能替代最终 GO receipt。