同步master最新基线并准备画布修复PR

合入平台会话与主线测试修复保持画布交互、JSON识别和对话历史分页修复范围不变
2026-09-16 18:59:32 +08:00
parent 1b010fb1f8 d11c74212d
commit ac8a51ca79
31 changed files with 1588 additions and 488 deletions
@@ -0,0 +1,27 @@
+Version: 1.0
+Status: implemented; real-project runtime smoke pending
+Date: 2026-09-16
+Parent Milestone: docs/project-memory/plans/【里程碑】Direct三维请求自选技术栈-2026-09-16.md
+
+## 修改顺序
+
+1. 在 `agent/direct_runtime/mod.rs` 保留三维/引擎意图与工程归属识别（含伪 3D、2.5D、代码话题例外）。
+2. 用"三维请求自选技术栈"合同替换澄清合同、工具阻断、注册门禁与首页创建阻断代码路径。
+3. 在三处装配点前置注入合同：首页回合、项目回合与测试用的旧装配点。
+4. 把工程合同里的 Phaser 固定约束按二维/三维分层。
+5. 更新定向用例与文档，运行格式化、编码检查与 diff 检查。
+
+## 验证命令
+
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell three_dimensional`
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell agent::direct_runtime::tests::system_prompt`
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell agent::direct_tools_mcp`
+- `cargo fmt --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --check`
+- `npm run check:encoding`
+- `git diff --check`
+
+## 风险与回滚
+
+- 误判风险：关键词识别可能对"三维数组"这类代码话题误触发，已用游戏语义上下文词、平面化排除词与独立成词边界收敛，并用用例钉住例外。
+- 行为风险：解除 Phaser 固定约束后，三维交付可能落到 Three.js / Babylon.js 等新栈；回滚点是移除前置合同注入与常驻合同段，恢复原 Phaser 固定文案。
+- 已知环境限制：本机临时目录 owner ACL 与当前进程用户不一致，涉及 `init_local_game_project_at` 的既有用例（未改动模块同样如此）无法在本机执行；本轮证据为定向用例 + 格式 + 编码 + diff 检查，全量分片与真机 smoke 仍待补。
@@ -0,0 +1,47 @@
+# 【实施计划】平台会话身份与凭据分离
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】平台会话身份与凭据分离-2026-09-16.md` |
+| Status | done（待验收复核） |
+| Owner | Codex |
+
+## 修改边界
+
+- 允许修改：`apps/ai-game-creator-shell/src-tauri/src/platform_session.rs`、`commands.rs`、`runner/`（attach 参数与安装路径）、`project/external_editor_bindings.rs`、`project/resource_editor.rs`、`agent/generation/canvas_generation.rs`、`agent/direct_tools_mcp.rs`、`agent/direct_runtime/`、`assets.rs` 中与身份判据相关的调用点。
+- 允许修改：`apps/ai-game-creator-shell/src/services/platformSession.ts`、`clientAuth.ts`、`clientApi.ts`、`src/App.tsx` 及对应测试。
+- 允许修改：`src/services/apiClient.ts` 刷新收敛重试与对应测试。
+- 允许修改：`server-rs/crates/api-server/src/refresh_session.rs`、`auth_session.rs` 与对应测试。
+- 明确不修改：`/api/external/v1` 路由与 OpenAPI、`refresh_session` schema / 迁移 / 绑定、生成账本与计费、Provider 与 MCP 工具边界。
+
+## 实现顺序
+
+1. 原生会话状态拆分：`PlatformSessionSnapshot` 增加身份代次，`generation` 更名并明确为写入 revision；安装 / 清除 / 冻结校验按新判据重写，补单元用例。
+2. 逐个修正原生调用点（binding、生成 operation、MCP 会话、diagnostics、Runner attach），由编译器定位所有旧判据读取点。
+3. renderer：身份代次与 native revision 分离，续期走凭据更新路径；刷新失败只在权威失效时清会话；补前端用例。
+4. 刷新收敛：AGC 与网站前端在刷新 401 时用当前 cookie 重试一次。
+5. `api-server`：轮换失败不再下发清 cookie 响应，补定向用例。
+6. 回写主规范与共享记忆，删除临时计划。
+
+## 验证命令
+
+1. `npm run ai-game-creator-shell:check:rust`（或定向 `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml platform_session`）
+2. `npm --prefix apps/ai-game-creator-shell test -- src` 对应前端定向用例
+3. `npm run test -- src/services/apiClient.test.ts`
+4. `cargo test -p api-server refresh_session --manifest-path server-rs/Cargo.toml`
+5. `npm run typecheck`、`npm run check:encoding`、`git diff --check`
+
+## 风险与回滚点
+
+- 风险：身份代次判据改宽后，若换号路径仍复用旧代次，旧账号请求可能带着新账号 token 发出。缓解：换号、退出和 origin 变化必须先推进身份代次；Rust 侧对同代次不同主体的写入失败关闭，并用用例覆盖。
+- 风险：revision 与身份代次混用会让迟到写入复活旧会话。缓解：写入顺序只认 revision，身份只认身份代次，两者分别有用例。
+- 回滚点：先回滚 renderer 的续期路径与原生判据（第 1-3 步），再回滚服务端响应语义（第 5 步）；`refresh_session` schema 不在本次改动内，无需数据回滚。
+
+## 执行结果
+
+1. `platform_session.rs`：`PlatformSessionSnapshot` 拆成 `identity_generation` + `revision`，新增 `PlatformSessionIdentity`、身份租约与 `validate_frozen_platform_session`；安装 / 清除按"revision 排序 + 身份归属"双判据实现。
+2. 原生调用点：`external_editor_bindings.rs`、`resource_editor.rs`、`canvas_generation.rs`、`direct_tools_mcp.rs`、`direct_runtime`、`assets.rs`、`commands.rs` 全部改按身份判定；`commands.rs` 的 IPC 改为 `install_platform_account_session(userId, accessToken, apiBaseUrl, identityGeneration, revision)`、`clear_platform_account_session(identityGeneration, revision)`、`read_platform_account_session_state()`。
+3. Runner：attach 参数新增 `platform_auth_revision`，`platform_auth_generation` 只表达身份代次；`remember_*` / `validate_*` 按 revision 排序、按身份归属判定。
+4. renderer：`platformSession.ts` 拆分 `platformNativeIdentityGeneration` 与 `platformNativeRevision`，续期走 `commitPlatformCredentialRefresh`（不推进身份代次）；刷新失败结果新增 `authoritative`，`AuthenticatedClient` 只在权威失效时登出。
+5. 刷新收敛：AGC `clientAuth.refreshClientAuthAccessToken` 与网站 `apiClient.refreshAccessToken` 在 401 后用当前 cookie 再试一次；网站侧额外要求本代次仍是当前代次。
+6. `api-server`：`refresh_session` 失败不再下发清 cookie 响应（`map_refresh_error_with_clear_cookie` 删除），并更新两条 `app::tests` 断言。
@@ -0,0 +1,29 @@
+Version: 1.0
+Status: implemented; real-project runtime smoke pending
+Date: 2026-09-16
+Parent Spec: docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md
+
+## 目标
+
+用户要求做三维（3D）游戏时，DirectProject 不再把 Phaser 4.2.1 当作固定约束：由 Codex 自行选择三维技术栈并直接推进，客户端不要求先澄清引擎、不阻断工具、不拒绝登记产出。
+
+## 边界
+
+- 只读用户原文做确定性识别，不改写用户消息，不启动 Supervisor、专业 Agent、harness 或额外生成工作流。
+- 只对"说了三维、没有点名引擎"的回合注入自选栈合同；用户点名引擎时沿用既有工程合同（Cocos / Unity / Godot 等与当前目录不匹配时先说明不匹配）。
+- 用户明确选择"等轴 / 伪 3D / 2.5D"表现，或话题是代码里的三维概念时，不注入该合同。
+- 唯一保留的红线是诚实边界：不得用等轴伪 3D 或二维图集冒充三维交付而不说明。
+- 首页只加一行三维提示，不阻止创建项目；不改 `/api/external/v1` 契约、OpenAPI、DTO、SpacetimeDB schema 与前端投影协议。
+
+## 验收标准
+
+1. 常驻系统提示包含"三维请求合同"：三维请求不受 Phaser 固定约束，由 Codex 自选三维技术栈，可新增 npm 依赖，仍需说明选型。
+2. 命中三维请求时，系统提示前置一段自选栈合同（含当前工程识别结果），不被 16K 提示词上限截断。
+3. 点名引擎、主动选择伪 3D / 等轴 / 2.5D、代码话题（如"三维数组"、"value4"）不触发该合同。
+4. 引擎固定约束文案已按二维/三维分层：二维游戏仍固定 Phaser 4.2.1，三维请求不受该约束。
+5. 定向 Rust 用例覆盖识别、合同文本、工程识别与首页提示；格式化、编码检查与 `git diff --check` 通过。
+
+## 依赖
+
+- 现有 DirectProject 回合装配（`agent/direct_runtime/mod.rs`）。
+- 现有 Cocos / Godot 工程识别（`project::discover_local_cocos_project_root`、`project::discover_local_godot_project_root`）。
@@ -0,0 +1,54 @@
+# 【里程碑】平台会话身份与凭据分离
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | implemented（待验收复核） |
+| Date | 2026-09-16 |
+| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`（`2026-09-16 平台会话身份与凭据分离`） |
+
+## 目标
+
+同一账号在长回合内发生 access token 续期时，在途的生成、编辑、上传、确认和下载 operation 必须继续可用；只有登录主体、服务 origin 或登出状态真正变化时才允许中止它们。刷新失败与并发刷新不得把仍然有效的会话判成未登录。
+
+## 范围
+
+- AGC renderer 的平台会话状态机：身份代次与 native 写入 revision 的分离，续期不再推进身份代次。
+- 原生 Rust `platform_session` 会话状态：身份判据、token 判据、写入顺序判据的分离。
+- 冻结平台会话的校验语义（外部编辑器 binding、生成 operation、MCP 工具会话）。
+- 独立 Runner 的平台会话安装 / 清除与 attach 参数。
+- AGC 与网站前端的刷新失败语义、并发刷新收敛重试。
+- `api-server` `/api/auth/refresh` 轮换失败时的响应语义。
+
+## 不在范围内
+
+- 不改 `refresh_session` 的持久化 schema，不引入服务端轮换宽限表。
+- 不改 `/api/external/v1` 路由、OpenAPI 或共享 DTO。
+- 不改生成、计费、账本幂等键与恢复语义本身。
+- 不改 Provider、MCP 工具白名单、审批或项目锁。
+
+## 依赖与前置条件
+
+- 现有 native revision 与 durable GUI owner claim 语义保持不变。
+- 现有 `authentication-required` 错误分类保持不变，只收窄其触发条件。
+
+## 验收标准
+
+- [x] 同一账号续期后，续期前建立的在途冻结会话校验通过；换号、退出和 origin 变化后校验失败关闭。
+- [x] 同一账号续期不推进 renderer 身份代次，也不使 `AuthenticatedClient` / Direct 配置判据把会话判成 stale。
+- [x] 迟到或更旧的凭据写入被 revision 拒绝，不能覆盖更新的 token，也不能复活已清除的会话。
+- [x] 瞬时刷新失败（网络错误、5xx、网关错误、响应契约异常）不清除本地会话与 access token。
+- [x] 刷新返回 401 时先用当前 cookie 收敛重试一次；重试成功继续使用新凭据，重试仍 401 才清会话。
+- [x] `/api/auth/refresh` 轮换失败不下发清空 refresh cookie 的响应。
+
+## 证据要求
+
+- 自动化：AGC Rust 定向用例（身份判据、revision CAS、冻结会话）、AGC 前端用例（代次与刷新失败语义）、`api-server` 定向用例（轮换失败响应）、网站 `apiClient` 用例（收敛重试）。
+- 运行时：AGC shell Rust 定向测试与前端测试；`api-server` 定向 `cargo test`。
+- 边界：换号 / 退出失败关闭、迟到写入拒绝、并发刷新竞争、token 不出现在错误文本与持久化中。
+
+## 证据与未验证项
+
+- 已获得：AGC `platform_session::tests` 12/12、`runner::tests` 平台会话相关 5/5、`assets::tests` 平台路由 2/2；AGC `appSurface` 前端套件 468 项全通过；网站 `src/services/apiClient.test.ts` 33/33；`cargo test -p api-server refresh_session` 3/3。
+- 未验证：依赖项目夹具的 AGC Rust 用例（`project::resource_editor::tests`、`project::external_editor_bindings::tests` 等）在本机全部以同一条环境错误失败——测试临时目录属主是 `BUILTIN\Administrators`，而进程用户是 `kdletters\kdletters`，严格 ACL 校验在夹具初始化阶段失败关闭，与本次改动无关；需要非提权或属主正确的运行环境才能补齐。
+- 未验证：真实 Provider 的并发生图 + 长回合保活端到端 smoke 未执行（需要有效平台登录态与付费生成）。
@@ -2,7 +2,6 @@

 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 > 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
-
 ## 2026-09-16 AGC 同 AppData 多窗口共享 Agent Runner

 - 背景：双击或再次启动 AGC 客户端时报「应用启动失败」，启动日志为 `startup.runner.owner-lock.failed details=AI 游戏创作界面已由同一 AppData 目录中的其他进程运行`。原设计（2026-07-27 / 2026-08-23）要求同一 AppData 只有一个 GUI owner，第二个界面进程在 setup 阶段就失败退出。
@@ -14,6 +13,15 @@
 - 未验证 / 已知环境问题：真实安装包双开需要重新构建发布后才能验证；`durable_provider_handoff_prevents_shutdown_even_when_corrupt`、`durable_provider_retry_prevents_shutdown_and_reopens_writes`、`runtime_interrupt_for_true_steer_decision_only_interrupts_older_provider_cursor` 三条用例在本机改动前的基线上即失败（Windows 安全对象 owner 校验与 Provider 请求重复），与本决策无关。
 - 关联文档：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`（2026-09-16 节）、`docs/project-memory/plans/【里程碑】AGC同AppData多窗口共享Runner-2026-09-16.md`。

+## 2026-09-16 DirectProject 三维请求解除 Phaser 固定约束，由 Codex 自选技术栈
+
+- 背景：三维需求（"做个 3D 城市游戏"）在只有 Phaser 4 二维通道的工程里没有落点，而完成判定以"源码引用已登记平台图片 + 浏览器渲染到该图"为硬门禁，模型可推进的唯一动作退化成生成图集；真机侧表现为长时间生图与反复接线，等轴伪 3D 成了默认交付。产品决定不再用"先澄清引擎"卡住三维请求，改为放开选型。
+- 决策：用户消息表达三维（3D / 三维）且没有点名引擎时，本回合注入**自选技术栈合同**：不受"新 Web 游戏固定 Phaser 4.2.1"约束，由 Codex 自行选择三维技术栈（Three.js、Babylon.js 等 npm 运行时，或当前工程自带的引擎），可以按需新增 npm 依赖、调整工程结构，并在回复里说明选型；客户端不要求先澄清、不阻断任何工具、不拒绝登记产出。
+- 决策（常驻口径）：`DIRECT_AGC_ENGINEERING_GUIDANCE` 的 Phaser 固定约束按二维/三维分层——二维游戏仍是 Phaser 4.2.1，三维请求不受该约束。首页回合只加一行三维提示，仍允许按既有规则创建项目。
+- 边界：用户点名引擎时沿用既有工程合同（Cocos / Unity / Godot 等与当前目录不匹配时先说明不匹配）；用户主动选择"等轴 / 伪 3D / 2.5D"或话题是代码里的三维概念时不注入合同。唯一保留的红线是不得用等轴伪 3D 或二维图集冒充三维交付而不说明。识别只读用户原文，不改写消息、不触发额外工作流，也不做工具阻断或注册门禁。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_runtime/mod.rs`。**未改** `/api/external/v1` 契约 / OpenAPI / DTO、SpacetimeDB schema、AGC 工具桥行为、前端投影与资源工作台。
+- 验证方式：`three_dimensional_game_request_frees_the_engine_choice`、`explicit_flat_presentation_requests_do_not_trigger_three_dimensional_selection`、`named_engine_requests_keep_the_existing_engineering_rule`、`three_dimensional_contract_reports_the_current_project_engine`、`home_three_dimensional_note_keeps_project_creation_available`、`system_prompt_is_bounded_and_declares_direct_runtime`，以及 `agent::direct_tools_mcp` 17 passed；`cargo fmt --check` 通过。本机临时目录 owner ACL 与进程用户不一致，涉及 `init_local_game_project_at` 的既有用例（含未改动模块）在本机无法执行，全量分片与真机 smoke 未在本轮取得。
+- 关联文档：[里程碑](../plans/【里程碑】Direct三维请求自选技术栈-2026-09-16.md)、[实施计划](../plans/【实施计划】Direct三维请求自选技术栈-2026-09-16.md)。
 ## 2026-09-16 图标图集自动拆图上限提高到 256

 - 背景：AGC 图标图集自动连通域识别在一次生成中识别出 86 个区域，原有 64 片上限在后处理阶段阻断了请求；该上限同时影响 api-server 自动 / 手动切片、SpacetimeDB 批量落库和统一生成结果 item 数量。
@@ -8777,6 +8785,13 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策：新增 `agent/runtime_error.rs` 作为统一错误事件与有界诊断 sidecar 边界。DirectProject 失败、Agent Runtime terminal failure 均持久化 `.agent/runtime/errors/<eventId>.json`，并将脱敏 assistant 终态写回 `project.jsonl`；前端只通过 `read_agent_runtime_error_detail` 读取脱敏详情。旧 `failure.json` 保留兼容，不把原始 stderr、凭据、URL/query、宿主绝对路径写入用户文本。
 - 决策：错误使用稳定 `source / stage / code / retryable / publicText / recoveryHint / detailRef` 字段；试玩 attempt 越界返回终态错误并停止继续等待。素材完成门扫描实际 npm 源码模块，并把 manifest 中合法的自定义 art-spritesheet 路径纳入候选，构建和浏览器观察仍需通过既有完成门。
 - 关联规范：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-15 AGC 统一错误事件、诊断落库与验收反馈”；开发期计划见 `docs/project-memory/plans/【里程碑】AGC统一错误诊断与验收反馈-2026-09-15.md` 与对应实施计划。
+
+## 2026-09-16 平台会话身份与凭据分离
+
+- 背景：长回合保活和 401 续期每次签发新 access token，并推进 native generation 重新安装原生会话；冻结平台会话同时比对身份与 token 字节，于是同账号的正常续期被等价成换号，并发在途的生成 / 编辑 / 上传 / 确认 / 下载 operation 全部被判为“旧账号请求”失败。更彻底的一层是原生会话、Runner attach 与 renderer 代次都把“写入顺序”和“身份归属”压在同一个计数器上。
+- 决策：平台会话拆成身份（`userId + api origin + identity generation`）与凭据（当前 access token）。identity generation 只在登录、切号、登出或新的 GUI authority epoch 推进；同账号续期只更新凭据并推进只用于拒绝迟到写入的 revision。冻结会话校验、MCP 会话身份与 Runner attach 统一按身份判定，换号 / 退出仍然失败关闭。刷新失败只在服务端明确 401/403 且一次收敛重试后仍失败时清会话；`/api/auth/refresh` 的轮换失败不再下发清空 refresh cookie 的响应。
+- 关联规范：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-16 平台会话身份与凭据分离”；开发期计划见 `docs/project-memory/plans/【里程碑】平台会话身份与凭据分离-2026-09-16.md` 与对应实施计划。
+- 验证：AGC `platform_session::tests`、`runner::tests`、`assets::tests` 定向通过；AGC `appSurface` 前端套件 468 项通过；网站 `src/services/apiClient.test.ts` 33 项通过；`cargo test -p api-server refresh_session` 通过。项目夹具类 Rust 用例受本机临时目录属主为 `BUILTIN\Administrators` 的环境限制，未计入本次证据。
 ## 2026-09-15 Direct 回合跨页面继续运行与活动项目面板

 - 决策：采用后台继续运行语义。Direct 回合由进程内项目身份锁持有，页面离开不取消；重进项目通过活动回合只读快照与 Thread Manager bootstrap/consume 恢复忙碌态和进度。左上角面板复用同一快照列出正在运行的 Direct 项目并支持进入。
@@ -5637,3 +5637,10 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 验证：`git config --show-origin --get user.name` 出现 `file:.git/config  Git Hooks Test`、`git rev-parse --show-toplevel` 指向 `%TEMP%\genarrative-pre-push-*\repo` 都是被污染的确定性证据；被 `core.worktree` 劫持期间执行的 `git pull` 会把检出写进临时目录，真实工作树整体落后（本次 93 个文件），配置修好后用 `git checkout HEAD -- .` 回填。
 - Vitest 的 `toHaveBeenCalledWith` 匹配任意一次调用，失败输出会列出其它命令；应先定位相同命令的真实参数差异，不能由其它调用的序号推断时序故障。
 - 存在后台轮询的 IPC mock 不应要求目标命令占据全局最后一次调用。验证刷新时先记录调用边界，再筛选该边界之后的目标命令，严格核对其最后一次参数，避免后台查询影响断言，也避免旧调用掩盖刷新未执行。
+
+## 2026-09-16 并发生图遇到“登录态冲突”：身份代次与凭据轮换混用
+
+- **现象**：DirectProject 长回合里并发派发的生图 / 素材生成请求中途报 `authentication-required: 陶泥儿登录态已变化，旧账号请求已停止，请使用当前账号重试`，或平台工具返回 `HTTP 401 invalid-token`；账号并没有切换，重新登录后短时间内可复现。
+- **原因**：客户端把两件事压成了一个判据。原生冻结会话（`PlatformSessionSnapshot`）同时承担“身份归属”和“access token 字节比对”，而长回合保活与 401 续期每次都会签发新 token 并推进 native generation 重新安装会话；于是同账号的正常续期被等价成换号，续期窗口内所有在途生成、编辑、上传、确认和下载 operation 全部失配。保活定时器（回合 busy 时每 5 分钟一次）会稳定落在生图窗口内，所以并发越多越必现。另一层在服务端：`/api/auth/refresh` 是严格一次性轮换，且失败时下发清空 refresh cookie 的响应；两个窗口 / 实例并发续期时，输的一方会把赢家刚写入的有效 cookie 删掉。
+- **处理（现行口径）**：平台会话统一拆成**身份**（`userId + api origin + identity generation`）与**凭据**（当前 access token）。identity generation 只在登录、切号、登出和新的 GUI authority epoch 推进；同账号续期只更新凭据并推进写入 revision（revision 只用于拒绝迟到写入）。冻结会话校验只比身份，比 token 字节的判据已被取代。刷新失败语义收紧为：只有服务端明确返回 401/403 且经一次收敛重试后仍失败，才清本地会话；网络错误、5xx、网关错误和响应契约异常必须保留会话与 access token。`/api/auth/refresh` 的轮换失败不再下发清 cookie 响应。
+- **验证**：AGC `platform_session::tests` 覆盖“同身份 token 轮换后冻结会话仍有效”“换号 / 退出后失效”“迟到 install 被 revision 拒绝”；`appSurface` 前端用例覆盖“续期不推进身份代次且 native 写入 revision 递增”“瞬时刷新失败不清会话”；网站 `src/services/apiClient.test.ts` 覆盖“刷新 401 后收敛重试成功”与“两次都被拒绝才判权威失效”；`api-server` `refresh_session_*` 覆盖“轮换失败不下发清 cookie”。定位同类问题先看冻结会话判据里有没有 token 字节，再看服务端失败响应有没有 `Max-Age=0`。
@@ -48,9 +48,22 @@

 DirectProject 的 AGC 工具、构建、验证和浏览器试玩错误，若不属于鉴权、权限、余额、项目身份、历史损坏、传输断开、取消或付费操作状态不确定等安全终止边界，必须作为脱敏错误上下文回传同一 LLM 会话，由 LLM 读取当前项目、修改真实文件并重跑失败阶段。客户端最多连续反馈三次；每次保留 stage、工具 / 命令、错误正文和已有证据，不得静默吞错、伪造成功或用占位产物跳过阶段。达到三次仍失败后，才向用户投影终态错误和诊断引用。

+## 2026-09-16 平台会话身份与凭据分离（并发续期不再中断在途生成）
+
+平台会话在 AGC renderer、原生 Rust 层和独立 Runner 中统一拆成两个互不替代的概念：**身份**（`userId + api origin + identity generation`）与**凭据**（当前 access token）。身份代次只表达登录主体或服务 origin 的更换；凭据轮换必须保持身份代次不变。
+
+- 同一身份内的 access token 轮换 —— 长回合保活、`401` 续期、同一账号重新登录 —— 只更新凭据，不推进身份代次，也不得让任何在途生成、编辑、上传、确认或下载 operation 的冻结会话失效。此前把 token 字节和 native generation 一起当作身份判据，使一次正常续期被等价成换号，在途生图被判为 `authentication-required: 陶泥儿登录态已变化`；本条款取代该判据。
+- 冻结会话的校验判据只包含身份，不含 token 字节。换号、退出或 origin 变化仍然失败关闭：旧身份的 operation 后续一切 POST、poll、下载和结果安装都必须停止，只保留对账证据，不得改绑或重放。
+- 原生 install / clear 继续使用单调 revision 作为写入顺序判据，防止迟到写入复活旧状态；身份代次不参与写入排序，只参与身份归属判定。同身份凭据更新必须携带不小于当前 revision 的新 revision 且保持身份代次不变，才能替换 token。
+- `authentication-required` 只表达"当前 operation 对应的身份已不是权威身份"。同一身份的凭据轮换不得产生该错误。
+- 刷新失败语义：只有服务端明确返回 `401` / `403`，且收敛重试后仍然失败，才允许清除本地会话与 access token。网络错误、`5xx`、网关错误和响应契约异常必须保留既有会话与 access token，只让发起刷新的那个动作失败。
+- 并发刷新收敛：同一 origin 的 refresh 单飞；一次刷新返回 `401` 后允许用当前 refresh cookie 收敛重试一次，重试成功则继续使用新凭据，重试仍为 `401` 才判定登录态权威失效。
+- 服务端 `/api/auth/refresh` 的轮换失败不再下发清空 refresh cookie 的响应。refresh cookie 的失效只由会话吊销、过期或身份变更语义决定，不由一次轮换竞争决定；客户端以"收敛重试后仍 401"作为登出判据。
+- 证据要求：Rust 定向用例覆盖"同身份 token 轮换后冻结会话与在途 operation 仍有效""换号 / 退出后冻结会话失效""迟到 install 被 revision 拒绝"；AGC 前端用例覆盖"续期不推进身份代次""瞬时刷新失败不清会话""收敛重试成功不登出"；`api-server` 用例覆盖"刷新轮换失败不下发清 cookie"。
+
 ## 2026-09-15 DirectProject 长回合平台会话保活

-DirectProject 的生图、素材处理、构建和试玩可能跨越短生命周期 access token 的有效期。普通 `/api/*` 请求和 Codex app-server 已有 401 刷新路径，但 AGC 工具由 Rust 工具桥直接使用客户端当前会话，工具内部的 401 不会自动触发前端刷新。客户端在 DirectProject 回合处于 busy 状态时每 5 分钟调用现有 `requestPlatformSessionRefresh()`；刷新仍复用单飞请求、generation 校验和 native session 安装，不改变凭据来源，也不把 401 降级为成功。刷新失败保持静默，由原始 AGC 工具错误按现有鉴权失败合同返回，避免后台保活覆盖真实错误。
+DirectProject 的生图、素材处理、构建和试玩可能跨越短生命周期 access token 的有效期。普通 `/api/*` 请求和 Codex app-server 已有 401 刷新路径，但 AGC 工具由 Rust 工具桥直接使用客户端当前会话，工具内部的 401 不会自动触发前端刷新。客户端在 DirectProject 回合处于 busy 状态时每 5 分钟调用现有 `requestPlatformSessionRefresh()`；刷新复用单飞请求、身份判据和 native session 安装，不改变凭据来源，也不把 401 降级为成功。刷新失败保持静默，由原始 AGC 工具错误按现有鉴权失败合同返回，避免后台保活覆盖真实错误。2026-09-16 起，同一账号的保活续期只更新凭据、不推进身份代次，因此不得中断在途生成 operation。

 完成门禁同时允许已登记的普通平台图片作为运行时素材。此前只把 canonical art-spec、背景、图集和图集切片加入来源白名单；`agc_generate_image` 生成的 `assets/neon-*.png` 即使已经登记并被源码引用，也会被判成“未引用平台图片”，触发同一回合的重复修复。浏览器预览把本地图片 URL 改写成 UUID 路径时，验收按每个视口的已渲染本地图片数量与源码引用数量做有界匹配；仍要求两个视口都有对应观察，空视口继续进入修复。

@@ -66,6 +79,8 @@ DirectProject 自身的 `read_direct_project_conversation` 也必须在 blocking

 ## 图片生成恢复与测试边界

+App 界面测试中，关闭 Agent 弹窗后的迟到读取用例先等待「刷新 Agent」按钮启用，以项目已载入作为前置条件；该等待最多 5 秒，整条用例最多 10 秒，弹窗关闭后的状态断言保持不变。权限策略 deny/confirm 互斥用例保留连续命令写入与累计策略断言，因包含 12 次聊天提交，单独设置 15 秒预算。其余用例继续使用默认超时，不以固定 sleep 替代状态等待。
+
 已有持久生成账本的 Provider 待执行动作恢复时，若动作省略了旧视觉 Agent 自动补齐的参数，只在 Agent、动作身份、生成种类和冻结提示词均匹配旧合同后补齐缺省参数；显式参数不得被覆盖。新请求继续按当前自由图片合同执行，不能重新引入固定视觉产物门禁。恢复复用原 operation 与幂等账本，不因默认值变化重复提交已受理请求。

 单 HTML 测试须在项目初始化前准备 HTML；npm 项目的预览与导出测试须准备构建目录。图片测试按现行数量和布局合同验证资源、透明度、引用和持久恢复，不继续要求固定四切片。