@orion-agents/orion-code 0.3.1 → 0.3.2

package/docs/migration/v0.3.1-to-v0.3.2.md

@@ -0,0 +1,94 @@
+# Orion Code v0.3.1 → v0.3.2 Web Workbench 迁移说明
+
+v0.3.2 在 v0.3.1 专业工作台基础上增加可调左侧项目栏、Composer Control Center、
+Session 级模型与权限、可解释 Context、结构化引用、durable Plan review、队列编辑和
+Session 草稿恢复。升级保留现有 Workspace、Session、Thread、Goal、Settings 和项目文件。
+
+## 升级前准备
+
+1. 停止旧 `orion web` Host；如有活动 terminal，先在页面中关闭并确认子进程已退出。
+2. 备份 `$ORION_CODE_CONFIG_DIR/orion.json` 和 Session/Thread 数据目录。
+3. 记录当前 Workspace、Session、模型与项目默认权限。不要把绝对路径、凭据或真实 terminal
+   输出粘贴到问题报告。
+4. 使用 Node 22.12+、24 或 26；安装后执行 `orion --version` 与 `orion doctor`。
+
+## 布局偏好迁移
+
+v0.3.2 将旧布局偏好迁移为 `WorkbenchLayoutPreferenceV2`：
+
+- 左栏展开宽度默认 280px，可用鼠标指针在 240–480px 范围拖动，双击分隔条复位；
+- 左栏可折叠为 48px rail；右栏继续使用 320–720px 桌面宽度；
+- 中央对话区最小 560px，空间不足时先收缩右栏，再切换为 drawer；
+- `<=760px` 时左右栏是互斥 drawer，窄屏不会覆盖保存的桌面宽度；
+- 旧值无效或越界时会被 clamp/忽略，不会阻止 Workbench 启动。
+
+精细调宽只有鼠标指针入口；键盘仍可展开、折叠、打开 drawer 并操作全部内容。
+
+## Composer Control Center
+
+原先独立的 BUILD/PLAN/AUTO 按钮改为 Composer 下拉控制，并新增权限、模型、Effort 和
+Context 入口。Host 是 current/last-good/pending/error 的权威源，浏览器不会自行推断运行态。
+
+- **模式**：BUILD、PLAN、AUTO 是工作流模式；不等同于权限。
+- **权限**：Session 可选 project default、Ask、Allow 或 Deny。Allow 需要风险确认，且不会绕过
+  hard policy、sandbox、capability 或 workspace containment。
+- **模型**：模型和 Effort 是 Session 偏好；active turn 中的变更延迟到下一个 logical request。
+- **Context**：显示 Runtime 提供的 token 使用量、容量和来源；estimated 数据带 `~`，模型切换后
+  不沿用旧模型容量。
+- **Compact**：切换到更小上下文模型前，Host 先执行可验证 compact；失败时模型、Effort、
+  Session metadata 和下一次请求保持原值。
+
+模式与权限是两个独立轴。AUTO 不能覆盖显式 Deny，也不能把权限提升为全局设置。
+
+## Durable Plan review
+
+这是 v0.3.2 最重要的行为变化：PLAN 提交后不再自动开始实现。
+
+1. Runtime 提交 PlanReceipt，并写入 `awaiting_review` 的 durable review state；
+2. 浏览器显示 exact plan digest；刷新或 Host restart 后仍可恢复；
+3. “批准并进入 BUILD”只接受当前 exact digest，并创建独立 BUILD logical request；
+4. “继续规划”要求反馈并创建新的 PLAN request；
+5. “取消”结束 review，不产生执行副作用；
+6. stale revision/digest 返回 409，客户端不得自动重放。
+
+TUI、slash command 与 Web 共享同一 Plan review authority；UI 文案不是审批真源。
+
+## Context 引用、队列和草稿
+
+- `+` 可添加 workspace 文件/目录、Review hunk、历史 Session 和 Skill 引用；
+- 引用只传 opaque id、revision 和 digest，Host 在组装 prompt 时重新验证 containment、敏感文件、
+  stale revision 与预算；单引用最大 64KiB，总引用最大 256KiB；
+- 队列项可编辑、移动和删除，每次 mutation 需要 item revision；冲突返回 409 且零副作用；
+- Steer 与 follow-up 保持不同 admission 语义；队列使用执行时的最新 Composer 控制；
+- 未发送草稿按 Session 存在当前 tab 的 `sessionStorage`，切换/刷新可恢复，发送或显式清除后删除；
+  草稿不是 durable Session history，也不会跨浏览器重启恢复。
+
+## API 客户端变化
+
+自定义 Web 客户端应升级到
+[`v0.3.2 OpenAPI`](../architecture/v0.3.2-web-api.yaml)并遵守以下规则：
+
+- composer control mutation 携带 `requestId`、`expectedSessionId`、`expectedContextRevision` 和
+  control revision；
+- queue edit/move/remove 携带 queue revision 与 item revision；
+- Plan review 携带 exact plan digest/revision，不接受 last-write-wins；
+- Context reference 是 discriminated union，未知类型和未知字段 fail-closed；
+- replay reset 是硬屏障；matching active snapshot 恢复前 Composer 保持禁用；
+- 409 后先重新读取 bootstrap/snapshot，再让用户确认目标，不自动重放高风险操作。
+
+## 回滚到 v0.3.1
+
+1. 停止 v0.3.2 Host，并关闭所有显式启动的 terminal。
+2. 备份 v0.3.2 布局偏好、Session composer preference 和 Thread events 供排查。
+3. 安装 exact v0.3.1 artifact，并显式选择原 Workspace/Session。
+4. v0.3.1 会忽略新的布局/Composer 投影，但不会删除项目文件或旧 Thread history。
+5. 不要在 v0.3.1 中批准 v0.3.2 创建的 pending Plan review；需要继续时重新在 v0.3.2 打开，
+   或明确取消后再回滚。
+
+回滚不会恢复已关闭/lost terminal，也不会把浏览器 `sessionStorage` 草稿写入 Session。
+
+## 升级验证
+
+按 [`v0.3.2 Web E2E 资格计划`](../test/v0.3.2-web-workbench-e2e-plan.md)执行
+WEB32-P0-01..12。只有 source-clean `@orion-agents/orion-code@0.3.2` exact tgz、真实 Chrome、
+Node 22.12/24/26 和最终 digest-bound receipt 全部 GO，才能把候选标记为发布完成。

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

@@ -1,7 +1,7 @@
 # v0.3.1 Web Workbench 专业工作台优化计划
 
 - 版本：v0.3.1
-- 状态：待实施
+- 状态：实施完成；发布资格以同一 source-clean 提交生成的 release receipt 为准
 - 日期：2026-08-29
 - 范围：Web Workbench 左侧项目导航、右侧工作面板、布局系统、专业化 UI
 - 参考：Codex 的工作台信息架构与交互密度；不复制其品牌、视觉资产或私有实现