Merge branch 'master' into fix/chat-status-lost

# Conflicts: # docs/project-memory/shared-memory/decision-log.md # docs/project-memory/shared-memory/pitfalls.md
2026-09-17 16:53:18 +08:00
parent 0a9cdf6395 b37d91882c
commit cb840c6e8c
126 changed files with 6746 additions and 955 deletions
@@ -60,6 +60,8 @@

 ## 图片画布与媒体

+- [AGC 抠图模式与背景色透传方案](./technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md)：External v1 与 AGC 客户端扩展 `flat`/`complex` 及 BgFilter `auto` 透传。
+
 - [共享基础组件库与展示页](./technical/【前端架构】共享基础组件库与展示页-2026-08-26.md)：网站与客户端复用的无业务 UI chrome、样式边界和 `/components` 展示页。
 - [Raw GPT Image 2 图片编辑代理](./technical/【技术方案】Raw GPT Image 2图片编辑代理-2026-09-07.md)：主站客户端调用的同步图片编辑代理、multipart 输入、预检查与计费边界。
 - [UI 编辑器自动切分素材工作流](./technical/【技术方案】UI编辑器自动切分素材工作流-2026-09-08.md)：UI 设计图素材切分、Raw GPT Image 2 调用与结果持久化边界。
@@ -103,7 +105,7 @@
 - [后台 Dashboard 运营看板方案](./technical/【后台管理】Dashboard运营看板方案-2026-06-23.md)
 - [后台多账号与 Tab 访问权限方案](./technical/【后台管理】多账号与Tab访问权限方案-2026-07-14.md)
 - [Pingora 独立网关试点](<./technical/【开发运维】Pingora独立网关试点-2026-06-11.md>)
- [AGC 后台模型别名与对话选择](./technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md)
+- [AGC 后台模型别名与对话选择](./technical/【技术方案】AGC后台模型别名与对话选择-2026-09-05.md)：官方目录、本地自定义 LLM 开关、端点模型勾选与预览。
 - [UI 编辑器工作流完成通知弹窗](./technical/【设计】UI编辑器工作流完成通知弹窗-2026-09-04.md)
 - [官网 SEO 地基实施约定](./technical/【SEO】官网SEO地基实施约定-2026-07-10.md)
 - [UI 编辑器拖动变换提交边界](./【UI编辑器】拖动变换提交边界-2026-09-03.md)
@@ -1122,7 +1122,7 @@
        "tags": ["Editor Images"],
        "operationId": "removeExternalEditorImageBackground",
        "summary": "去除编辑器图片背景",
-        "description": "提交已有静态图片素材的异步去背景任务。sourceImageSrc 只接受当前账号拥有的稳定 objectKey、项目资源 ID 或素材 ID；禁止 Data URL、Blob URL 和临时 signed URL。assetKind 只能表达静态图片，并且存在权威来源记录时必须与其类型一致；视频、音频、动画和图片序列在入队前返回 400。服务端固定使用 complex 去背景模式，不会在失败时切换到其它 provider。需要写入画布时提供 projectId 与 canvasCompletion；仅需原位替换既有图层时提供 projectId 与 targetLayerId，且来源与目标必须指向同一权威对象。",
+        "description": "提交已有静态图片素材的异步去背景任务。sourceImageSrc 只接受当前账号拥有的稳定 objectKey、项目资源 ID 或素材 ID；禁止 Data URL、Blob URL 和临时 signed URL。assetKind 只能表达静态图片，并且存在权威来源记录时必须与其类型一致；视频、音频、动画和图片序列在入队前返回 400。complex 使用语义分割识别前景，flat 用于纯色背景抠图；确定背景为纯色时优先使用 flat。需要写入画布时提供 projectId 与 canvasCompletion；仅需原位替换既有图层时提供 projectId 与 targetLayerId，且来源与目标必须指向同一权威对象。",
        "security": [
          {
            "ExternalApiKey": []
@@ -3211,6 +3211,17 @@
            "minLength": 1,
            "description": "当前账号拥有的稳定 objectKey、项目资源 ID 或素材 ID。禁止 Data URL、Blob URL 和临时 signed URL。"
          },
+          "backgroundMode": {
+            "type": ["string", "null"],
+            "enum": ["complex", "flat", null],
+            "default": "complex",
+            "description": "抠图模式。省略或 null 按 complex 处理；complex 使用语义分割识别前景，flat 用于纯色背景抠图。确定背景为纯色时优先使用 flat。"
+          },
+          "screenColor": {
+            "type": ["string", "null"],
+            "pattern": "^(auto|#[0-9A-Fa-f]{6})$",
+            "description": "仅 flat 模式使用。可传 auto、#RRGGBB 或省略；null 等同省略。auto 和省略由服务自动检测背景色。模式省略或 complex 时提供非 null 颜色返回 400；空字符串或非法颜色返回 400。"
+          },
          "projectId": {
            "type": ["string", "null"],
            "description": "可选项目上下文。提供 targetLayerId 时必须同时提供非空 projectId，否则在入队前返回 400。"
@@ -3249,6 +3260,14 @@
            "description": "画布生成占位完成指令。提供时优先按生成完成链路写入结果，targetLayerId 不参与原位替换。"
          }
        },
+        "if": {
+          "required": ["screenColor"],
+          "properties": { "screenColor": { "type": "string" } }
+        },
+        "then": {
+          "required": ["backgroundMode"],
+          "properties": { "backgroundMode": { "const": "flat" } }
+        },
        "additionalProperties": false
      },
      "EditorImageGenerationResponse": {
@@ -0,0 +1,44 @@
+# AGC 画布交互稳定性修复实施计划
+
+- Date: 2026-09-16
+- Status: awaiting-runtime-acceptance
+- Milestone: [画布交互稳定性修复](./【里程碑】AGC画布交互稳定性修复-2026-09-16.md)
+
+## 修改顺序与边界
+
+1. 将临时诊断收敛成正式回归测试，覆盖窗口 Context 反馈、提示条件和鼠标/触摸板事件。
+2. 稳定工作台打开项目的转发回调，保持最新处理器语义，不改项目加载逻辑。
+3. 解耦运行提示与选择；在原有画布事件链加入右键平移、菜单边界和中断清理，不另建控制器。
+4. 执行定向验证并检查首次加载、平移和原有框选/卡片拖动回归。
+
+## 验证
+
+- 定向 Vitest：窗口工作台、画布交互、布局与原有导航用例。
+- 运行提示的源码契约与交互回归同时覆盖：提示仅取决于运行能力和 UI 编辑器路由，不依赖资源选择；选中资源后提示及 `aria-describedby` 保留，点击运行仍不能进入不可用视图。
+- AGC `tsc --noEmit`；`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
+- 真实客户端首次进入和触摸板操作无法以 jsdom 代替；未实测时保持待验收。
+
+## 风险与停止条件
+
+窗口反馈测试必须有更新次数上限，避免未修复代码让测试失控。右键仅接管画布背景/卡片，不抢输入控件与浮层。新增问题只有影响本次验收才扩大范围；不根据猜测修改 B01/B02 的布局与动画。
+
+回滚仅限本批局部补丁；不重置工作树，不覆盖其它修改。完成自动化验证后停在真实客户端验收，不推进额外功能。
+
+## 问题状态
+
+| 编号 | 问题 | 状态与证据 |
+| --- | --- | --- |
+| B01 | 刷新后首次进入画布元素抖动 | 已优化；用户在本轮反馈未再复现，按用户要求更新状态。不宣称所有布局/动画原因均已排除。 |
+| B02 | 初次进入双指平移无效，整理后恢复 | 已优化；用户在本轮反馈未再复现，按用户要求更新状态。隔离组件连续平移通过。 |
+| B03 | 快速平移触发更新深度错误 | 已修复已确认的窗口 Context 反馈循环，回归验证收敛；真实操作继续观察。 |
+| B04 | 资源选中后运行不可用提示消失 | 已修复，提示与选择解耦，自动化验证通过。 |
+| B05 | 对话记录偶发丢失 | 已定位历史分页卡点，尚未修改。只读复验用户提供的历史：558 条合法原始记录中有 44 条聊天消息；首屏原始 20 条只投影出一条助手消息，下一页原始 20 条没有聊天消息，按消息计算的游标不推进。已存用户提问和最终回答因此无法继续翻出；不能凭该文件排除其它未落盘记录。 |
+| B06 | JSON 文档未正确识别展示 | 已按用户确认完成本地修复：合法 UI State 由原生完整校验，卡片显示 UI 设计并进入现有编辑器；普通 JSON 显示 JSON 并可代码预览。自动化验证通过，待重建原生客户端验收；详见 JSON 语义识别实施计划。 |
+| C01 | 右键平移，保留左键框选 | 已实现，卡片左键拖动、框选、指针取消/失焦/捕获丢失及控件边界测试通过。 |
+
+## 已取得证据与剩余门禁
+
+- 修复前新增回归测试能检出外壳重复发布、运行提示消失和右键无效；修复后窗口/画布定向测试通过，现有导航、框选、指针点击/取消、UI 编辑器返回平移和素材定位用例通过。
+- AGC TypeScript、修改文件 ESLint、编码、文档索引及差异空白检查通过。
+- 测试仍有既有 React 列表 key、旧用例 act/IPC 桩告警，未作为本批功能修复扩大范围。
+- 用户反馈 B01/B02 本轮未再复现，记为已优化；右键手感与其它真实客户端细节继续观察。对话历史分页尚未修复；JSON 双路径已本地修复并通过自动化验证，待真实客户端验收。本计划保持开放。
@@ -0,0 +1,27 @@
+# AGC 资源 JSON 语义识别实施计划
+
+- Date: 2026-09-16
+- Status: awaiting-runtime-acceptance
+- Milestone: [AGC 资源 JSON 语义识别](./【里程碑】AGC资源JSON语义识别-2026-09-16.md)
+
+## 实施边界
+
+1. 原生 UI 持久化模块抽取可复用的内容解析与只读识别；文本预览返回可选的已验证 UI 资产身份。
+2. 保留新设计初始化的严格 UI 资产门禁；已有 State 的加载/保存/生成按登记资源和真实文档校验，不依赖标签精确大小写。
+3. 前端预览缓存透传识别结果；工作台卡片与编辑器入口消费同一结果，普通 JSON 详情使用代码块。
+4. 单元、组件与原生测试覆盖合法/普通/损坏/跨身份/未登记和保存边界；保持先前画布修复。
+
+## 验证与停止条件
+
+- 定向 Vitest、Tauri persistence/resource preview 定向 Rust 测试、AGC TypeScript、修改文件 ESLint、编码、文档索引及 `git diff --check`。
+- 不读取或修改用户项目原文件，不将日志或真实对话作为仓库测试夹具。
+- 原生构建/真实客户端受环境限制时记录实际证据，不能以 TS 测试代替原生验证。
+- 完成上述范围后停止；B05 已有分页卡点证据，本轮不顺带修改历史合同。
+
+## 验证结果
+
+- 92 个前端定向测试通过，覆盖原生结果驱动的卡片/编辑器路由、普通 JSON 代码预览、伪 UI 文本拒绝、读取失败、缓存切项目，以及原有画布导航与指针回归。
+- 14 个 UI 持久化原生测试通过，包含有效 State 对多种登记标签的识别/加载/保存、未知 schema/字段与坏结构拒绝、项目/资产身份、普通 JSON 防覆盖及原有恢复/CAS 边界。
+- 原生测试在 macOS 默认 `/var` 临时路径触发既有拒绝符号链接门禁；改用真实 `/private/tmp` 后通过，未放宽产品路径安全校验。
+- AGC TypeScript、修改文件 ESLint 已通过。测试仍有既有 React key/act 告警及 Rust 未使用代码警告，不影响本批断言。
+- 真实客户端的图片/UI State 体验仍待验收。本次包含 Rust 预览字段，必须重新构建并启动原生端，不能仅刷新前端就认为识别结果已更新。
@@ -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,14 @@
+# 抠图模式联调验收实施计划
+
+依据：[里程碑](./【里程碑】抠图模式联调验收-2026-09-16.md)。
+
+1. 主站修复 worker 对 auto/省略的门禁、空值契约和旧指纹；补接口、队列与 worker 定向测试。
+2. 客户端独立核对 schema、参数校验、幂等意图、Skill 与契约说明。
+3. 串行请求真实 BgFilter，凭据仅在进程内读取，不输出或落库。
+4. 运行 cargo test 的 background_removal、bgfilter、OpenAPI 定向过滤，客户端定向测试；运行 doc-index、encoding、diff 检查。
+5. 尝试 npm run dev:api-server 与 healthz smoke；记录真实登录/全链路未验证项。
+6. 收敛证据到主规范，删除临时计划。
+
+检查点：先通过契约测试，再开展运行时核验；不因环境缺失修改生产配置。回滚仅限本次局部补丁。
+
+当前收口：主站及客户端修复和定向检查已执行，真实 BgFilter 四组成功及自动检测失败分支已验证；本地 API 启动被现有数据库连接配置阻塞。仅完整登录/队列/资源回写运行时证据尚待补齐，测试凭据和临时日志不得提交。
@@ -0,0 +1,26 @@
+# AGC 画布交互稳定性修复
+
+- Version: 1
+- Status: reviewed
+- Date: 2026-09-16
+- Parent Spec: [AGC 实施计划：资源画布交互与工作台状态同步](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)
+
+## 目标与范围
+
+完成工作台标题栏状态更新循环、运行提示随选择消失、右键平移三项本地修复，保持左键框选与卡片拖动。不修改布局算法、持久化和后端；不开远程 Issue/PR、不推送。
+
+## 评审
+
+依据已完成的源码追踪、客户端错误日志及有界复现自检：状态归属仍在窗口与工作台原有边界内；交互修改只影响画布手势；没有数据迁移、权限或 API 变化。用户已确认右键平移及保留左键框选，并授权先尝试本地修复。真实客户端首次进入抖动与触摸板平移仍需另行验收。
+
+## 验收
+
+1. 工作台发布窗口状态后收敛；重复渲染不持续更新或清理，打开项目回调使用最新处理器，卸载清理有效。
+2. 选中资源后运行不可用提示仍在，运行能力不变。
+3. 子画布空白处及卡片右键平移不改变选择或坐标；左键框选与卡片拖动保留；总览支持右键平移。
+4. 指针取消、失去捕获、窗口失焦终止平移；控件与浮层保留原有交互。
+5. 连续平移测试、定向测试、类型检查、编码与文档门禁完成并记录限制；B01/B02 仅在真实复测后决定关闭。
+
+## 依赖
+
+当前源码与已安装测试依赖；真实 AGC 客户端验收环境。没有外部写操作依赖。
@@ -0,0 +1,26 @@
+# AGC 资源 JSON 语义识别
+
+- Version: 1
+- Status: reviewed
+- Date: 2026-09-16
+- Parent Spec: [AGC 实施计划：文档与代码素材预览](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)
+
+## 目标与边界
+
+按用户确认同时支持普通 JSON 与 UI 设计 JSON：前者显示 JSON 并可代码预览，后者显示 UI 设计并进入原有编辑器。原生侧复用现有文档校验，前端不推断正式状态。不修改 manifest 分类，不迁移用户文件，不改历史分页，不做远程写入。
+
+## 评审
+
+已核对原生受控文本预览、UI State 持久化合同和工作台卡片/编辑器路由。复用完整读取结果识别，未知 schema/坏结构/身份不符均不授予编辑入口；已有 UI 资产的大小写标签不应阻断真实合法 State。新增可选预览字段只承载原生识别结果；不引入新的状态文件或平行编辑器。
+
+## 验收标准
+
+1. 普通 JSON 显示 JSON，不渲染卡面原文，不出现 UI 编辑器入口，显式预览为 JSON 代码块。
+2. 完整合法且身份匹配的 UI State 显示 UI 设计并进入现有编辑器；大小写标签或文档标签不影响内容识别。
+3. 损坏 JSON、伪 schema、未知字段、坏 State、跨项目/资产、未登记文件不能获得 UI 编辑入口；原文查看或读取错误仍可见。
+4. 识别不产生写入；普通 JSON 不能通过编辑器保存或初始化被覆盖。有效已有设计仍支持原有 CAS 保存。
+5. 预览缓存能传递原生结果并随资源身份失效；原有卡片、框选/平移和图片预览回归通过。
+
+## 依赖
+
+本地前端与 Tauri 源码、现有测试依赖；真实客户端体验单独验收。
@@ -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 未执行（需要有效平台登录态与付费生成）。
@@ -0,0 +1,14 @@
+# 抠图模式联调验收
+
+Version: 1
+Status: 自动化与真实上游验收已执行；完整主站链路待本地数据库恢复
+Date: 2026-09-16
+Parent Spec: ../../technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md
+
+交付：证明客户端、External v1、队列和 BgFilter 的模式/颜色契约一致；修正范围内缺漏。
+不做：401 专题、部署、主站前端变化、生成角色与图集自动选色行为变化、数据库 schema 修改。
+
+验收：旧请求 complex；flat 三种颜色输入贯通；非法组合入队前 400；幂等包含新意图并保留旧请求指纹；真实服务返回可解码透明 PNG；实际证据与未验证环境分开记录。
+依赖：既有方案及前五步代码。
+
+剩余门禁：当前本地 SpacetimeDB 连接拒绝，导致 api-server 启动恢复未就绪。环境恢复后，用 npm run dev:api-server 验证 healthz，再以真实登录客户端提交三种 flat 请求及旧 complex 请求，确认队列完成和资源回写。不得用直连 BgFilter 测试替代此门禁；完成后将结论回写主规范并删除本计划和实施计划。
@@ -2,6 +2,41 @@

 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
 > 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
+## 2026-09-16 抠图模式与背景色契约
+
+- External v1 抠图和 AGC `agc_remove_background` 支持 `complex`（语义分割识别前景）与 `flat`（纯色背景抠图）；明确纯色背景优先 flat，模式缺省仍为 complex，主站前端保持现有行为。
+- flat 的颜色允许 `auto`、`#RRGGBB` 或省略，自动识别完全由 BgFilter 负责。主站只校验、透传，不调用视觉模型选色；complex 携带颜色、非法值和空字符串在入队前拒绝。
+- 来源、名称、模式与颜色共同区分客户端请求意图；旧参数调用及旧 External 请求的幂等指纹须保持稳定。
+- 权威合同：[AGC 抠图模式与背景色透传](../../technical/【技术方案】AGC抠图模式与背景色透传-2026-09-16.md)。
+
+## 2026-09-16 策划 Agent 工具执行退出项目级写锁并自动接续中断批次
+
+- 背景：策划 Agent 每个 `read_file` / `write_file` / `patch_file` 工具都在执行前竞争全局项目写锁，但同一会话已由 `.agent/design-agent/active.lock` 串行化，工具目标又限定在 `design_artifacts`；项目锁既不覆盖「工具 + 会话 checkpoint」事务，还把进程中断时的 `executing=true` 不确定窗口扩大到等锁与工具执行全程。真机项目出现 `pendingBatch.executing=true`、`function_call` 无配对 output、UI 只显示工作中且无错误的状态。
+- 决策：单次策划工具不再竞争项目级写锁，只保留策划命令锁与既有原子写入；GameAgent / DirectProject 的公共项目锁实现与调用不变。重开项目 hydrate 时，若命令锁可获取且当前批次处于 `executing=true`、当前 call 无 output，则自动续跑原回合：为该 call 补写「执行结果未保存」的工具错误、跳过剩余调用并交回 Provider 自愈；不得重放文件副作用，也不要求用户手动重试。
+- 验证：新增定向用例证明中断批次自动补齐工具 output、收到后续 assistant 回复、清空 pendingBatch 并结束原 turn，同时目标文件保持未修改（未重放 `patch_file`）；策划 Runtime 定向 14 条、策划工具 3 条通过，`cargo fmt --check`、`npm run check:encoding`、`git diff --check` 通过。
+- 关联文档：[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.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 阶段就失败退出。
+- 决策（锁语义）：`agent-runner.gui-owner.lock` 改为**界面参与锁** `agent-runner.gui-participant.lock`，以共享句柄打开，同一 AppData 的任意数量窗口可同时持有；Runner 的启动检查、attach 门禁与 watchdog 只用“能否独占取得该文件”判断是否仍有窗口存活。全部窗口退出后才关停 Runner 并清理 endpoint。
+- 决策（claim 采纳与发布）：窗口启动先**采纳**durable claim（同一 epoch/revision），只有 claim 缺失或不可读才发布新 claim；登录、refresh、退出或换号才发布新 claim（新 epoch + 本窗口 revision），成为新的登录态权威。同一 claim 的重复 attach 是幂等空操作，不再清空 Runner 登录态；只有 epoch 变化或携带明确登出参数才允许替换 / 清空。并发发布以最后一次成功写入的 claim 为准，落败窗口按最新 claim 有界重试。
+- 决策（事件与退出）：manifest 失效与 Runtime update relay 的接收端从单槽改为按 `event_sink_token` 去重的注册表并广播，发送失败只淘汰该接收端；GUI 退出先释放本窗口参与锁，仍有其它窗口时保留 Runner（`agent.runner.gui_exit.retained_for_other_windows`），最后一个窗口才请求关闭。Runner 启动失败时先按最新 endpoint 复用一次，避免两个窗口同时冷启动时的实例锁竞争被误报成启动失败。
+- 边界：本机 GUI ↔ Runner 协议方法与参数不变，不引入多 Runner、不做跨 AppData 会话共享；项目级 `.agent/project.lock` 不变，多窗口仍不能并行写同一项目；平台登录态 generation 单调与 claim 失配失败关闭语义保持不变；混用新旧版本二进制访问同一 AppData 不属于支持场景。
+- 验证：定向 Rust `runner::tests::gui_owner_*` 11 条与新增的参与锁多窗口 / 存活判定 / claim 采纳与轮换 / 同 claim 第二个窗口不清空登录态用例全部通过；真实 debug 二进制 Windows smoke 证明同一 AppData 两个 GUI 都完成 `startup.setup.complete`、只存在一个 `--agent-runner` 进程、关闭一个窗口后另一个窗口与 Runner 继续存活、最后一个窗口退出后 Runner 退出并删除 endpoint；`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。
+- 未验证 / 已知环境问题：真实安装包双开需要重新构建发布后才能验证；`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-17 DirectProject 历史分页的「可显示」口径定为前端回合反馈，一次翻页连拉上限 5 页

 - 背景：ADR 与里程碑要求「一次翻页操作在前端自动连拉，直到出现可显示条目或 `hasMore=false`，上限 5 页」，但实现只落地了后端锚点与文件尾回扫，前端仍是单发一页。历史切片的 `limit` 按原始条目计，一整页全是工具卡片 / 思考文本且落进同一个已渲染回合的折叠「执行过程」时，用户点「显示更早的对话」看不到任何变化。
@@ -8776,7 +8811,22 @@ 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 项目并支持进入。
 - 边界：快照不写项目文件、不进入公共 API、不跨应用重启恢复；读取失败保留上一份结果并单独提示，不改写成权限或审批失败。身份锁排他性、付费身份和项目写锁不变。
+
+## 2026-09-16 CI 宿主 CPU 上限：Jenkins 16 核 / Gitea Actions runner 12 核
+
+- 背景：`genarrative-station`（32 逻辑核）上 Jenkins Built-In Node 与 Gitea Actions runner 共用同一宿主。Jenkins `jenkins.service` 原先没有任何 CPU 限制（`cpu.max=max`），构建期 Web / Api / Stdb 三分支并行（Vitest 8 线程 + 两次默认 32 job 的 cargo）把整机顶到 80%~95%；`gitea-runner` 容器 `--cpus=24`（75%）在 push 触发的 CI 波峰里实测峰值 24.8~25.3 核，是同一时间窗里更大的单一消耗方。
+- 决策：两路 CI 都设硬上限。Jenkins 侧 `systemctl set-property jenkins.service CPUQuota=1600%`（16 核 / 50%，覆盖 Built-In Node 上所有子构建，立即生效、无需重启，drop-in 落 `/etc/systemd/system.control/jenkins.service.d/50-CPUQuota.conf`）。runner 侧把 `/opt/gitea-stack/compose.yml` 的 `cpus` 由 `"24.0"` 改为 `"12.0"`（12 核 / 37.5%），并用 `docker update --cpus=12 gitea-runner` 让运行中的容器立即生效，不重建容器、不中断在跑 job。
+- 边界：Deploy 阶段在远端 dev / release agent 执行，不受该上限约束。调整只动这两处：`systemctl set-property / revert jenkins.service`、`docker update --cpus=<n> gitea-runner` 加同步 compose（备份 `/opt/gitea-stack/compose.yml.bak-<时间戳>`）。
+- 验证：限速后 `Genarrative-Full-Build-And-Deploy` #289 / #290 SUCCESS；采样期 Jenkins 峰值 10.2~10.5 核、限流不足 2s（可忽略），runner 峰值 12.07 核且持续出现 throttling，整机回落到 2.6%~19.8%。
+- 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)。
@@ -4,6 +4,10 @@

 ## 标准流程

+前端测试稳定性验证使用根目录 `npm test`（与 Frontend tests job 相同），保留 Vitest 的 8 worker 上限。涉及异步资源展示时，组件测试必须 mock 所有会触发的网络请求，每次调用创建独立 `Response`，并等待最终 DOM 状态而非仅等待 fetch 被调用。换签 Hook 的测试通过 `vitest.config.ts` 的 include 纳入全量运行；新增测试文件后需确认实际执行名单，命令参数指定文件不会绕过 include 白名单。排查顺序依赖可使用 `npm test -- --sequence.shuffle --sequence.seed=9467`，但不能以重试成功替代失败原因分析。
+
+用例隔离必须包括浏览器状态与 mock 实现：修改 `window.history` 后恢复基线路由；`spyOn(window, 'getSelection')` 等 spy 在用例结束后 restore；`clearAllMocks` 仅清调用记录，不能恢复被上一个用例替换的返回值。顺序打乱暴露的失败应修复泄漏来源，保留原有业务断言。
+
 ```text
 确认工作树与目标分支 → 读取入口和当前专题 → 查代码真相 → 小步修改 → 定向验证 → 更新当前文档/记忆 → 检查提交边界
 ```
@@ -72,6 +76,10 @@ SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.m
 3. 确认相关当前文档与共享记忆已同步，且 docs 入口没有指向已删除或退役实现依据。
 4. 提交标题使用中文，标题后逐行写明本次变更。

+## Jenkins 定时版本调度
+
+定时与版本比较只保留在 `Genarrative-Scheduled-Revision-Trigger` 一处：每小时用 `git ls-remote` 解析 `SOURCE_BRANCH` 远端 HEAD，与上一次触发过的 revision 比较，变化时才把同一个 `COMMIT_HASH` 同时传给 `Genarrative-Full-Build-And-Deploy` 与 `Genarrative-Agc-Windows-Build`，保证两条管线构建同一个版本。`Genarrative-Full-Build-And-Deploy` 与 `Genarrative-Agc-Windows-Build` 不得自带 `triggers` / `cron`，也不得在管线内再做一套版本去重；`npm run check:production-ops` 会拦住这两类回退。调度状态与生效步骤见 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## Gitea CI 依赖闭合

 `.gitea/workflows/project-ci.yml` 的客户端门禁拆成八个 job，每个 job 只预热自己会构建的那几份依赖：`AI game creator shell Rust shard 1/4` 到 `4/4` 各只预取 AGC 壳 manifest 并各跑一片（AGC 壳那份 `Cargo.lock` 的 path 依赖已含 `platform-llm`、`platform-agent`、`agent-runtime-core` 与 `shared-contracts`），`AI game creator shell Rust smoke` 同样只预取 AGC 壳 manifest（`agent-run` smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`），`AI game creator shell Rust crates` 预取 `server-rs/Cargo.toml` 与两个独立 crate，`Native shell tests` 预取桌面壳与 AGC 壳 manifest，`AI game creator shell web tests` 不触碰 Cargo，不预热。AGC 壳的 4 个分片 job、smoke job 与 crates job 只用 cargo 与 node 内建模块，因此不执行 `npm ci`。两个被 `server-rs/Cargo.toml` 排除、且没有提交 `Cargo.lock` 的独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）只能在 `AI game creator shell Rust crates` 里用不带锁标志的 fetch。AGC 壳的 bin target 单测（约 2466 条）由 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs` 编译一次后按 `--list` 名单分 4 片：CI 的每个分片 job 用 `--shard-index=<i>` 只跑自己那片，片内保持 `--test-threads=1` 并各自使用独立 `TMPDIR`，片与片之间靠 job 级并发摊开；本地不传 `--shard-index` 时仍是同一条命令把 4 片放进程里并行。不要改回「一个 job 内多进程并行这几片」——同一容器里它们会争抢共享 `HOME`、target 目录与固定临时路径，实测比整套串行还慢。每个分片 job 都会自校验「片并集等于全集且互斥」，因此改分片规则不会静默漏跑。Backend host workspace tests 使用 `cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`，避免 `spacetime-module` 的 `spacetime-types` feature 统一污染普通领域 crate 的 host 测试；随后单独执行 `cargo test --locked -p spacetime-module --no-fail-fast`，由 `spacetime-module/src/active.rs` 在 host 测试构建期间提供仅测试期的 SpacetimeDB ABI 链接支持，使该 crate 的纯单元测试也纳入 Backend 门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，host 链接支持不得被当作运行时替身。Backend 另外执行 `cargo check --locked -p spacetime-module` 验证模块源码。AGC 壳检查还会运行 `platform-llm` 与 `shared-contracts` 的 server-rs workspace 测试，这些命令以及 AGC 壳测试必须带 `--locked`，避免在测试阶段重新解析 registry index；锁文件发生变化时应先更新受信任 CI 镜像缓存，再重跑门禁。
@@ -1,5 +1,19 @@
 # 踩坑与排障记录

+## JSON 卡片显示与 UI 编辑能力必须同源
+
+JSON 的文本读取分支不等于卡面应该展示原始 State 摘要。卡片、缩略图及编辑器入口共同消费受控文本预览的 `uiDesignAssetId`；只有原生复用 UI 持久化合同校验 schema、完整 State 和项目/资产身份后才设置它。普通 JSON 保留 JSON 代码预览，不按 `kind: UI/ui` 或 schema 字符串片段猜测编辑能力。已有合法 UI State 的加载/保存不依赖 kind 精确大小写，但新建初始化仍保留正式 UI 资产门禁；缓存与项目切换须保留现有身份隔离。
+
+## 窗口 Context 发布不得依赖每次渲染新建的业务回调
+
+工作台向窗口标题栏发布运行项目时，若 effect 依赖普通函数派生的回调，发布 Context 会重新渲染工作台，进而再次发布并清理，形成更新深度循环。转发入口须稳定，并在提交阶段更新实际处理器引用；发布数据变化与卸载清理分开。回归测试必须组合真实窗口 Provider 和工作台消费者，只有独立画布测试无法覆盖这条反馈链；回归时用有界发布次数阻止测试失控。画布快速操作时暴露的更新深度错误，也须检查外层状态同步，不能直接归因于滚轮频率。
+
+## 2026-09-16 从 Codex 里启动 AGC 客户端会看到被重定向的 `%APPDATA%`
+
+- **现象**：在 Codex 会话里用 `Start-Process` 启动 `genarrative-ai-game-creator-shell.exe` 做排障时，子进程写 `C:\Users\<user>\AppData\Roaming\world.genarrative.ai-game-creator\...` 的内容会落到 `C:\Users\<user>\AppData\Local\Packages\OpenAI.Codex_2p2nqsd0c76g0\LocalCache\Roaming\...`；同一个 `Test-Path` / `Get-ChildItem` 命中的是重定向视图，只有 `\\?\C:\Users\...` 形式能区分真实路径。
+- **影响**：用 agent 拉起的客户端复现「多开 / 登录态冲突 / 锁文件被占用」类问题时，可能与用户双击开始菜单快捷方式的真实进程不是同一份 AppData，从而得出「两个实例没有互相冲突」或「日志里没有那条失败」的错误结论。
+- **处理**：把用户双击快捷方式（或从 Codex 之外启动）的进程作为唯一用户侧证据；核对待查文件时同时比对真实 `AppData\Roaming` 路径与 `Packages\...\LocalCache\Roaming` 路径；排障结论里写明客户端是「谁启动的」。
+
 ## Windows 已登记生图资产未刷新

 Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\` / `\\?\UNC\`，而前端项目路径仍是普通盘符或 UNC。失效监听不能直接比较原始字符串；识别为同一项目后，用当前项目路径重读 manifest，保留项目切换与 revision 门禁。普通 `agc_generate_image` 成功提交也必须发出失效通知，不能依赖整轮 Agent 结束。回归需覆盖两种 Windows 前缀、其它项目事件拒收，以及 Agent 尚未结束和后续失败时已登记图片卡片仍可见。
@@ -3875,7 +3889,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - 现象：在 Jenkins Job 页面给 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 配了默认值，下一次加载 Declarative Pipeline 后又变空或恢复旧描述；04:00 Full Job 还可能因默认选择 `pause-after-stdb` 且 approvers 为空而失败。
 - 原因：这些 Job 使用 Pipeline script from SCM，`parameters {}` 和 `triggers {}` 会作为 Job property 回写现场配置；只改 UI 不是持久修复。构建编排如果不显式关闭下游 `PUBLISH_AFTER_BUILD`，还会受下游默认值漂移影响。
 - 处理：credential ID 和参数默认值写回三个 Jenkinsfile；仅供开发使用的 dev 定时 Full Job 默认 `STDB_API_ROLLOUT_MODE=normal`，三路 Build 调用显式传 `PUBLISH_AFTER_BUILD=false`，再由 Full Job 统一按 Stdb → API → Web 发布。Secret 原文只放 Jenkins Secret File，旧 Secret Text 保留给 Import / Export。
- 验证：推送后让 Full / Stdb Build 用不存在的源码分支在 checkout 阶段 fail-closed，让 Stdb Publish 用空构建版本在 Prepare 阶段 fail-closed，以安全刷新参数 schema；随后只读检查三个 live `config.xml` 的参数描述和默认值，确认 Full timer 仍为 `0 4 * * *`、rollout 默认值为 `normal`，并确认刷新运行未进入 publish / deploy stage。
+- 验证：推送后让 Full / Stdb Build 用不存在的源码分支在 checkout 阶段 fail-closed，让 Stdb Publish 用空构建版本在 Prepare 阶段 fail-closed，以安全刷新参数 schema；随后只读检查三个 live `config.xml` 的参数描述和默认值，确认 rollout 默认值为 `normal`、Full 与 AGC Job 都不再带 cron（定时只来自 `Genarrative-Scheduled-Revision-Trigger`），并确认刷新运行未进入 publish / deploy stage。
 - 关联：`jenkins/Jenkinsfile.production-full-build-and-deploy`、`jenkins/Jenkinsfile.production-stdb-module-build`、`jenkins/Jenkinsfile.production-stdb-module-publish`、`scripts/check-production-ops-guardrails.mjs`。

 ## 维护模式内网全站放行不能信任 X-Forwarded-For
@@ -5614,9 +5628,36 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`

 - 在 hook 内运行临时仓库测试时，`cwd` 不会覆盖继承的 `GIT_DIR`、`GIT_WORK_TREE` 或 `GIT_INDEX_FILE`。未隔离的 Git/lint-staged 子进程可能向真实仓库提交 fixture，甚至把测试版 ESLint、Prettier 配置带入主分支。
 - fixture 子进程统一清除 `GIT_*` 环境，并用一次性外层 linked worktree 验证引用、索引、配置不变；原有工程检查规则保持完整，不能用逐项关闭规则修复 fixture 污染。
+- 2026-09-16 复核：从链接工作树 `git push`/`git commit` 时，Git 注入 `GIT_DIR=<主仓库>/.git/worktrees/<name>`、`GIT_WORK_TREE`、`GIT_INDEX_FILE`，husky → npm → `check:repository-ci` → 夹具测试整链条继承。夹具 `git config user.name "Git Hooks Test"` 会写进共享 `.git/config`（此后所有提交 author 变成 `Git Hooks Test`）；夹具 `git init` 按是否带 `GIT_WORK_TREE` 分别写成 `core.bare=true`（`fatal: this operation must be run in a work tree`）或 `core.worktree=<临时夹具目录>`（`git status` 实际在操作临时目录）。
+- 处理：钩子与门禁入口先 `unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_COMMON_DIR GIT_PREFIX GIT_CONFIG_PARAMETERS GIT_CEILING_DIRECTORIES`；夹具 Git 调用在命令前自检 `rev-parse --show-toplevel` 等于夹具目录，落到外部仓库立即失败；守卫用例的子进程必须真的继承 `GIT_DIR`，否则断言会空转。
+- 验证：`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`。
+
+## 2026-09-16 同步 Tauri 命令里 `tokio::spawn`：点「终止」整个客户端 abort 闪退
+
+- **现象**：AGC 客户端（陶泥儿 0.1.46 安装包，`C:\Users\<用户>\AppData\Local\陶泥儿\genarrative-ai-game-creator-shell.exe`）在对话回合运行中点输入盒的「终止」后整个 App 直接消失。Windows 事件日志 `Application Error` 1000：异常代码 `0xc0000409`、出错模块就是该 exe、偏移 `0x3395066`；`%LOCALAPPDATA%\CrashDumps` 留下同名 minidump，其 ExceptionStream 为 `NumberParameters=1`、`Param[0]=7`（`FAST_FAIL_FATAL_APP_EXIT`）⇒ Rust `abort()`，既不是栈溢出（`0xC00000FD`）也不是访问违例（`0xC0000005`）。
+- **原因**：`cancel_direct_codex_turn` 是**同步** Tauri 命令，Tauri 把非 `async` 命令直接跑在 IPC 回调线程（Windows 上是 WebView2 的 UI 线程）；该线程没有进入任何 tokio runtime 上下文（`main` 只 `tauri::async_runtime::set(handle)` 加泄漏 Runtime，从未在调用线程 `enter()`）。终止链路 `cancel_direct_codex_turn_at → CodexTurnStartCancellation::cancel → maybe_interrupt` 却用 `tokio::spawn` 派发 `turn/interrupt`：在没有上下文的线程上 `tokio::spawn` 经 `Handle::current()` panic（"there is no reactor running"），panic 又跨不过 Tauri 的 IPC 回调边界，Rust 只能 abort 整个进程。同一模块的 `CodexThreadLease::drop`、`CodexTurnGuard::drop` 是同一形态。引入点是 2026-09-15 23:37 的 `76bbeb684 重构 DirectProject Agent 深模块`；既有覆盖只有 `#[cfg(unix)]` 的 `#[tokio::test]` 走 Drop 守卫路径，碰不到同步命令线程，所以 CI 全绿。
+- **处理**：`codex_app_server/mod.rs` 新增 `spawn_codex_app_server_task`，统一经 `tauri::async_runtime::spawn` 派发（生产环境就是 `main` 装的深栈 runtime）；终止、租约 Drop、回合 Drop 三处一起改走它。判据是「调用点可能位于没有 tokio 上下文的线程」，不是「这个函数看起来像异步」。
+- **验证**：新增 `codex_app_server_task_dispatch_needs_no_tokio_runtime_context`——在 `std::thread::spawn` 出来的无上下文线程里调用派发入口，若回退成 `tokio::spawn` 即失败（实测回退后报 `there is no reactor running, must be called from the context of a Tokio 1.x runtime`）。
+- **排障注意**：Release GUI 没有 panic hook、也没有 stderr，panic 文案不会落盘；`diagnostics/application.log` 只会停在崩溃前最后一行（本次停在 `agent.codex_app_server.remote_control disabled` 之后），所以「应用日志没有异常」不能当作「没有 Rust panic」，要结合 WER 事件、minidump 的 fail-fast 参数与调用线程上下文判断。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/codex_app_server/mod.rs`、`apps/ai-game-creator-shell/src-tauri/src/main.rs`（`install_agent_runtime_async_runtime_with_deep_stack`）、`apps/ai-game-creator-shell/src-tauri/src/commands.rs`（`cancel_direct_codex_turn`）。
+
+## 2026-09-16 AGC 壳跑过 `cargo test` 后前端 typecheck 必红：ts-rs 导出把 `generated/*.ts` 重写成另一种形状
+
+- **现象**：在 `apps/ai-game-creator-shell/src-tauri` 跑过 `cargo test` 之后，`npm run ai-game-creator-shell:typecheck` 报 10 条类型错（`src/features/project-workspace/resourceReferences.ts:106-112` 的 `string | undefined` 不能赋给 `string | null`；同文件 134 行的对象字面量带 `type: 'message'`，而 `DirectCodexUserMessageItem` 里没有该字段），`npm run ai-game-creator-shell:build` 也死在 `beforeBuildCommand` 的同一条 typecheck 上。
+- **原因**：crate 里的 ts-rs 导出会按**本机依赖版本**重写 `src/features/project-workspace/generated/DirectCodexUser*.ts`：注释头变成 "This file was generated…"、字符串改双引号、`DirectCodexUserMessageItem` 丢掉 `type: 'message'` 判别字段、并多出一个 `DirectCodexUserMessageEnvelope.ts`。仓库里提交的那份是前端真正依赖的形状（前端按带 `type` 的判别联合写），重写后两边就对不上——错在生成器版本漂移，不在前端。
+- **处理（现行口径）**：不要把重写结果当改动提交。跑过 `cargo test` 或构建后先 `git checkout -- apps/ai-game-creator-shell/src/features/project-workspace/generated`，再删掉多出来的 `DirectCodexUserMessageEnvelope.ts`，然后才做 typecheck / 打包；绑定与前端形状冲突时以**已提交的绑定 + 前端**为基准排查。
+- **验证**：恢复提交版本后 `npm run ai-game-creator-shell:typecheck` exit 0（`[skill-pack] OK`）；保留重写结果时同一条命令 exit 2。release 构建本身还会在 `src/features/ui-editor/types/` 落下 `BindingChange.ts` / `BindingDTO.ts` 两个无人引用的未跟踪文件，属同类生成产物。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/src/agent/direct_codex_user_item/`（ts-rs 导出源）、`apps/ai-game-creator-shell/src/features/project-workspace/resourceReferences.ts`、`apps/ai-game-creator-shell/scripts/build-release.mjs`（`beforeBuildCommand`）。
+
 ## 2026-09-16 Node 26 下 vitest 的 jsdom 用例拿不到 window.localStorage

 - **现象**：只声明 `@vitest-environment jsdom` 的用例里 `window.localStorage` 是 `undefined`（典型报错 `Cannot read properties of undefined (reading 'clear')`）；而 `appSurface.test.ts` 里同样访问 `window.localStorage` 却一切正常。
@@ -51,6 +51,8 @@ SpacetimeDB crate、SDK、CLI / standalone 与生成 bindings 按 `2.8.3` 对齐

 ## AGC DirectProject 与 UI workflow

+- AGC 的本地 `llm.customEnabled` 默认关闭，只能手动修改配置文件；开启后设置支持自定义 Responses 端点、读取 `/models`、勾选和预览 `visibleModels`。对话下拉只显示勾选项，LLM 请求经客户端凭据代理直连自定义上游；不会回退官方中转，平台资源服务仍使用账号权限。详见 AGC 后台模型别名与对话选择规范。
+
 - DirectProject 对话先在完整历史中按回合/原始 item 身份关联，再分页渲染；每个回合只有一个呈现入口。有流按 item `seq` 交替文本和工具，无流采用历史正文；禁止位置猜配或同时展示累计回复与 item 正文。流写入单调归并，收尾等待落盘任务，不按磁盘“最后一段”猜最终回复位置。详见 AGC 实施计划的“DirectProject 回合展示唯一归属”。
 - 回合生命周期只由活动 client 回合快照和 Direct 事件恢复；Provider 的历史终态通知不能创建活动 client 回合。消息发送时间保存在历史信封，原始 item 不混入宿主字段；完成后的中间文本和工具默认收进“执行过程”，最终回复及失败提示保持可见。

@@ -151,7 +151,7 @@ Authorization: Bearer <internal-token>
 - 当前部署只有一个配置内私有 OSS bucket，因此请求只传 `sourceObjectKey`，子 worker 从自身 OSS 配置取 bucket 并生成短期签名 URL。
 - 如果未来确实支持多个 bucket，新增字段也必须由服务端 allowlist 校验；不能接受调用方提供任意下载 URL。
 - `backgroundMode` 只允许 `flat / complex`；`segModel` 继续沿用当前 `birefnet / anime-seg` allowlist；complex 固定使用当前参数组合。
- `screenColor` 只对 flat 必填；complex 不得误接 flat 参数，两种模式的熔断状态必须隔离。
+- `screenColor` 在 flat 下可省略，也可传 `auto` 或 `#RRGGBB`；省略或 `auto` 由 BgFilter 自动识别。complex 不得携带背景色，两种模式的熔断状态必须隔离。生成角色、图集等既有链路继续传已确定的背景色。
 - `maxQueueWaitMs` 与 `callBudgetMs` 都是相对预算，不是跨机器绝对时间。前者从 admission 起约束排队阶段（worker 还会用 §5.2 的动态估计对其取 min）；后者从取得 provider permit 起计时，覆盖签名、两次 attempt、结果校验和响应构造。`callBudgetMs` 是父侧按 `N / est` 公式算出的“配置指纹”，仅作核对：worker 始终以自己按同一公式派生的值执行，不一致时不拒绝请求，而是记录 warn 日志并递增漂移指标。发布调优 N / est 时新旧进程共存的瞬态漂移因此不会误伤在途任务；持久性漂移的硬拦截由部署脚本的共享 env 对齐校验承担。
 - JSON body 设置很小的固定上限；源图字节不进入该 JSON。

@@ -1,6 +1,36 @@
 # AGC 后台模型别名与对话选择

-## 契约
+## 本地自定义 LLM
+
+- 本地 `game-creator.config.json` 的 `llm.customEnabled` 默认 `false`；显式设为 `true` 后，常用设置展示 API 地址、API Key、读取模型列表与勾选区域。DirectProject 沿用 OpenAI Responses 协议，地址填写 API 根地址（例如 `https://provider.example/v1`）。开关只由配置文件控制。
+- 点击读取后，客户端原生侧直接请求该地址下的 `GET /models`，使用自定义 Bearer Key，读取 OpenAI 兼容的 `data[].id`。请求有超时与响应大小上限，禁止携带平台登录凭据、禁止重定向；错误仅展示安全状态，不回显上游响应体或 Key。
+- 模型支持搜索、逐项勾选和独立的已勾选列表预览。`llm.visibleModels` 按勾选顺序保存模型 ID，第一项作为默认项。至少勾选一项才可保存；读取失败保留草稿和已勾选列表，不替用户清空或新增选择。
+- 首页与项目对话复用现有模型选择器；自定义模式只读取本地勾选目录，不请求平台模型目录。模型 ID 原样用于上游请求（允许 `/`、`.`、`:`），所选项被取消勾选时回退第一项。保存后刷新目录，下一回合使用新连接与模型，活动回合继续使用原快照。
+- 开启后，Codex 客户端凭据代理和 Rust LLM 调用均直连自定义端点，不走平台 `/api/llm` 或内置中转；配置缺失或请求失败明确报错，不回退官方路由。真实 Key 留在客户端，不进入 Codex 子进程环境、参数或模型上下文。平台图片、音频、账户和计费契约不变。
+- 配置加载、迁移和覆盖文件写入保留显式开启的连接和勾选列表；关闭时仍使用官方模型目录与官方路由。缓存不能跨自定义/官方目录或不同自定义连接复用。旧配置缺少新字段时保持官方行为。
+- 验收覆盖开关默认值、配置合并/保存/重载、直连凭据与模型传递、模型发现成功/失败/超时、勾选预览、仅显示勾选模型、目录切换、无平台目录请求和设置保存失败。自动化本地 HTTP 验证与真实供应商 smoke 分开报告。
+
+在设置页显示的本地配置文件路径中，手动把现有 `llm` 对象的 `customEnabled` 设为 `true`（保留其它字段），重新打开常用设置即可配置连接和读取模型。界面没有开启开关，保存设置也不能把关闭状态改为开启。配置文件也支持直接填写以下字段：
+
+```json
+{
+  "llm": {
+    "customEnabled": true,
+    "baseUrl": "https://provider.example/v1",
+    "apiKey": "填写自己的密钥",
+    "apiKind": "openai_responses",
+    "visibleModels": ["provider/model-name", "another-model"]
+  }
+}
+```
+
+`visibleModels` 可先留空，再从端点读取并勾选；未完成勾选前不能发起自定义 LLM 对话。关闭时手动改回 `false`，后续回合使用官方目录和路由。
+
+本地配置文件始终保留 `customEnabled`、`visibleModels`、`apiKey`、`baseUrl`、`model`、`apiKind`、`reasoningEffort` 七个键：官方路由下连接字段写官方地址与空 Key、协议写 `openai_responses`，便于手写自定义连接时对照；切换为自定义后这些值原样保留而不被启动清理。
+
+自定义连接固定使用 OpenAI Responses 协议（`apiKind` 只接受 `openai_responses`），设置页把协议展示为只读项；推理档沿用对话输入盒中按回合生效的选择器，设置页只读展示当前档位，不新增第二处写入入口。
+
+## 官方路由契约

 - 后台 owner 在“AGC 模型”维护列表；每项包含稳定 `id`、必填 `alias`、服务端 `modelId`、`enabled`。默认项必须启用。标识唯一，别名唯一，列表最多 32 项。
 - 配置保存到私有 `agc_model_catalog` 单例表，使用 revision 乐观锁，重启及多 api-server 实例共享同一事实。缺少配置时使用初始目录，高质量对应 `gpt-6-astra`，快速对应 `gpt-5.6-luna`。
@@ -14,7 +44,7 @@
 - `selectedModelIsDefault` 为真表示选择由平台默认项驱动（首次进入、默认项变化、所选模型失效回退），后台默认项变化时客户端跟随切换并提示；用户手动选择后置为假，不再被默认项变化覆盖。
 - 首页聊天框架的右下角同样提供模型选择入口（与项目对话右侧一致）。首页入口与项目对话共用同一份目录缓存、挂载即加载（失败时沿用上一次成功目录），选择仅影响后续创建/发送的轮次，不阻塞「开启创作」，因此模型目录不可用时仍可创建项目并使用后台默认项。
 - 项目右侧对话的模型选择器在对话进行中保持可交互：切换模型只写回客户端配置并作用于下一轮，当前回合不受影响；发送按钮仍由 `controlBusy` / `modelReady` 把关。
- 设置页恢复到布局改版前的官方代理版本，不包含模型管理或模型选择，保留配置安全清理和官方代理锁定。
+- 自定义开关关闭时，设置页不包含模型管理或模型选择，使用官方代理锁定。

 ## 验收

@@ -0,0 +1,104 @@
+# AGC 抠图模式与背景色透传方案
+
+## 目标
+
+主站编辑器保持现有前端行为（继续使用 `complex`），同时扩展 External v1 抠图接口和 AGC 客户端，使客户端可以选择 `complex` / `flat`，并把 `screenColor` 原样交给 BgFilter。`complex` 用语义分割识别前景，`flat` 用于纯色背景抠图；确定背景为纯色时优先使用 `flat`。`auto` 的背景色识别完全由下游服务负责，主站不读取图片、不调用模型决策颜色、不生成颜色兜底值。
+
+## 当前 BgFilter 契约
+
+已登录生产服务器核对 `/root/BGfilter`，当前代码版本为 `f1a0833`，运行进程为 `python -m uvicorn app:app --host 0.0.0.0 --port 6006 --workers 1 --no-access-log`。服务契约为 `POST /remove-background` multipart：
+
+- `background_mode`：可选，`flat` 或 `complex`；
+- `screen_color`：可选，支持 `#RRGGBB`、`auto` 或省略；省略/`auto` 时由 BgFilter 从图片边框自动检测；
+- `complex` 模式忽略 `screen_color`；
+- 自动检测失败由 BgFilter 返回 400。
+- 若配置 `BGFILTER_AUTH_TOKEN`，必须发送 `X-Genarrative-Image-Token`；缺失或错误返回 401；未配置时该接口不在服务层做 token 校验。
+
+主站向 BgFilter 发送 `#RRGGBB` 时保留 `#`，`auto` 也原样发送，不做所谓的“hex 转换”。
+
+服务器行为：`screen_color` 在 `auto` 或省略时由服务自动检测；`#RRGGBB` 用作指定背景色。`background_mode` 缺省在 BgFilter 侧为 `flat`，因此主站必须为 External v1 旧请求显式归一化为 `complex`，不能把下游服务的默认值直接当成主站默认值。
+
+## External v1 请求契约
+
+接口保持：
+
+```text
+POST /api/external/v1/editor/images/background-removals
+```
+
+新增可选字段：
+
+| 字段 | 取值 | 缺省/行为 |
+| --- | --- | --- |
+| `backgroundMode` | `complex`、`flat` | 不填按 `complex`，保证旧客户端兼容 |
+| `screenColor` | `auto` 或 `#RRGGBB` | 不填则不向 BgFilter 发送该字段 |
+
+组合规则：
+
+1. 不传新增字段：按 `complex` 执行。
+2. `complex` 不允许传 `screenColor`，返回 400。
+3. `flat` 可以传具体 `#RRGGBB`、`auto`，也可以省略颜色。
+4. 模式和颜色严格按原值校验；非法值、空字符串、前后空格和大写 `AUTO` / `FLAT` 返回 400。十六进制颜色的字母允许大小写。
+5. 主站只做格式和组合校验；`auto` 不在主站解析，直接转发给 BgFilter。
+6. HTTP 请求中的 `null` 视同省略；模式省略时提供非 null 颜色同样违反 complex 约束。客户端 MCP 可选参数应省略，不传 null。
+
+格式或组合错误在入队前返回 400；BgFilter 自动检测失败发生在异步执行阶段，任务通过既有失败状态收口，不把已接受的 202 改成同步 400，不启动其他抠图方式兜底。
+
+OpenAPI 与客户端工具的对外说明只描述模式用途、参数约束和调用方可见的结果；provider 选择与兜底策略保留在内部技术方案中，不写入对外 description。
+
+主站前端继续不传新增字段，因此用户行为不变。
+
+## AGC 客户端改动
+
+`agc_remove_background` 增加可选参数：
+
+```json
+{
+  "sourceLocalAssetId": "...",
+  "assetName": "...",
+  "backgroundMode": "flat",
+  "screenColor": "auto"
+}
+```
+
+客户端保留旧参数调用；新字段不填时不改变旧调用语义。客户端不读取图片、不自动选色、不把 `auto` 改写为具体颜色，使用原有 Bearer 认证、幂等键和队列返回模型。
+
+工具 schema、桥接参数校验和随包 `agc-client-projection` Skill/契约说明必须保持一致。模式与颜色属于请求意图，必须参与客户端幂等指纹；同一图片与名称的不同模式不能复用同一次请求。缺省 complex 且没有颜色时保留既有指纹。主站在默认值归一化之前计算 External 请求指纹，缺失的新字段不序列化，避免旧请求重放发生冲突。
+
+## 实施任务
+
+### 任务一：冻结 BgFilter 契约
+
+记录服务器已支持的模式、颜色格式、自动检测和错误行为。不得把 SSH 地址、服务器凭据写入客户端或公开契约。
+
+### 任务二：更新主站 DTO 与 OpenAPI
+
+为 External v1 和内部任务 DTO 增加可选字段，更新 `docs/openapi/genarrative-external-v1.openapi.json`，写明默认值、组合约束和 400 响应。
+
+### 任务三：更新主站归一化与队列
+
+缺省模式归一化为 `complex`；`complex + screenColor` 拒绝；`flat` 允许颜色、省略或 `auto`。队列保存字段，worker 始终发送 `background_mode`，仅在调用方提供颜色时发送 `screen_color`，值原样透传。
+
+### 任务四：更新 AGC 客户端
+
+增加参数 schema、请求体字段和本地校验，更新 Skill、projection contract 与测试。旧客户端请求必须继续有效。
+
+### 任务五：联调与验收
+
+覆盖旧请求、`flat + auto`、`flat + #RRGGBB`、`flat` 不传颜色、`complex`、`complex + screenColor` 和非法值；使用真实 BgFilter 验证 multipart 字段及自动检测错误传播。
+
+## 依赖、发布与回滚
+
+先发布兼容的新主站，再发布支持新参数的 AGC 客户端。主站前端无需发布改动。若联调失败，客户端可回退为只传旧字段，主站仍按 `complex` 处理；主站回滚时不改变旧字段语义。
+
+## 验收证据
+
+2026-09-16 实测：
+
+- 主站 `cargo test -p api-server background_removal`：36 项通过，覆盖非法请求入队前拒绝、缺省 complex、队列参数保留、旧请求指纹、父侧内部 RPC 和 provider multipart。
+- `cargo test -p api-server bgfilter`：52 项通过，包括 flat 的 auto/省略/具体颜色以及既有生成链路。
+- `exported_openapi_json_contains_external_editor_routes_and_security` 契约测试通过。
+- 客户端 `agent::direct_tools_mcp::tests` 18 项、`agent::skill_pack::tests` 4 项与抠图幂等指纹测试通过；Skill manifest 内容指纹已同步。主站与客户端 rustfmt、文档索引、编码及 diff 检查通过。
+- 真实 BgFilter（版本 `f1a0833`）：使用进程内凭据串行请求 `flat + auto`、flat 省略颜色、`flat + #CFEFFF`、complex；四组均返回 200、512×512 RGBA PNG，alpha 范围均为 0–255。
+- 无纯色背景的随机噪声图片使用 flat + auto 返回 400，确认自动识别失败要求调用方提供颜色。测试没有修改服务器代码或配置。
+- 本地 `npm run dev:api-server` 已尝试，但当前配置指向的 SpacetimeDB 不可连接，服务停留在启动恢复重试，`/healthz` 未通过；已结束本次启动。完整登录客户端 → 主站持久化队列 → 结果回写的运行时验收尚未完成，不能用真实 BgFilter 的独立测试代替。没有部署本次主站或客户端代码。
@@ -1,5 +1,14 @@
 # AI 游戏创作智能体 App 实施计划

+## 资源画布交互与工作台状态同步
+
+- 工作台向窗口标题栏发布正在运行的项目时，输入未变化不得形成重复发布与清理的渲染循环；打开项目动作始终使用当前工作台处理逻辑，退出工作台后清除其标题栏状态。
+- 资源子画布（含「所有资源」）保留空白处左键框选、资源卡左键选中/拖动、触摸板双指平移及捏合缩放；右键按住空白处或资源卡拖动时平移画布，不改变资源选择与布局。中键和空格抓手继续可用。总览保留既有左键平移，并支持右键平移。
+- 画布接管的右键手势不弹出原生菜单；输入框、媒体操作、工具条和独立浮层不被画布抢占。指针取消、捕获丢失或窗口失焦后终止平移，不能继续跟随指针。
+- 运行不可用提示只取决于运行能力与 UI 编辑器状态，不因资源选中、取消选中或框选而消失，且不改变运行入口的真实可用性。
+- 本次边界不包含布局算法、持久化坐标、预览读取预算或后端契约调整。首次进入抖动与平移异常须在更新循环消除后单独实测，不能仅凭状态循环修复宣称已解决。
+- 验收包含真实窗口 Context 与工作台的状态同步回归、运行提示与选中并存、左右键分流、平移中断及连续滚轮事件；真实客户端首次进入与触摸板手感为独立人工验收项。
+
 ## 资源卡选中工具栏与导出

 - 共享选中工具栏按实际显示的快速编辑、编辑动作、改造、导出与宿主动作组生成分隔线；空组不产生分隔线，不依赖宿主 CSS 隐藏重复线。
@@ -8,6 +17,10 @@

 ## 文档与代码素材预览

+- JSON 资源的卡片按内容语义分流：普通 JSON 显示 JSON 图标/标签，详情按 JSON 代码块显示；UI 设计 JSON 显示 UI 设计标识并提供现有 UI 编辑器入口，不再把 State 原文铺在卡面上。功能分类、manifest kind 和资产身份不因识别而改写。
+- UI 识别由原生文本预览在已登记、受控、完整读取的同一份 UTF-8 内容上完成，复用编辑器的 `game-creator-ui-design-state.v1` 契约解析、canonical 校验、revision/State 校验及项目/资产身份校验。前端只消费识别结果，不按文件名、kind 大小写或正文片段自行认定 UI；普通、损坏、未知 schema、跨项目或跨资产 JSON 不获得 UI 编辑能力。
+- JSON 为完成内容识别继续走现有受限预取队列、并发/容量和 2 MiB 原生文本读取上限。识别失败不写文件、不生成空 State、不做格式迁移；能读取的原文仍可按 JSON 查看，读取失败仍展示原有错误。非 JSON 代码卡继续仅按用户详情请求读取。
+- 编辑器加载/保存/代码生成复核当前项目的已登记 JSON 资产及完整文档，不以 kind 必须精确等于 `UI` 阻断合法已有设计；创建新 UI 状态仍要求正式 UI 资源，不能借普通 JSON 预览初始化或覆盖文件。现有 State 保存锁、CAS、revision 与恢复边界不变。
 - 文档与代码素材选中工具栏提供「预览」，打开独立、可滚动的只读弹窗；关闭、切换素材或项目后不残留旧内容。加载中、空文件与读取失败分别呈现，允许重试可重试的错误。
 - 复用资源预览队列、身份缓存、项目 scope、失效与权限校验，继续调用 `read_local_project_text_preview`。代码卡不做可见性预取，仅用户显式打开详情时读取；不新增 IPC，不扩大可读取文件范围，不增加编辑/保存能力。
 - 文档正文统一使用现有 Markdown 渲染器；代码文件以按扩展名标注语言的 Markdown 围栏代码块呈现。围栏必须长于正文内的反引号串，正文空行与缩进保持原样，不把源码当 Markdown 正文或 HTML 执行。
@@ -32,9 +45,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 路径时，验收按每个视口的已渲染本地图片数量与源码引用数量做有界匹配；仍要求两个视口都有对应观察，空视口继续进入修复。

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

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

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

 单 HTML 测试须在项目初始化前准备 HTML；npm 项目的预览与导出测试须准备构建目录。图片测试按现行数量和布局合同验证资源、透明度、引用和持久恢复，不继续要求固定四切片。
@@ -58,9 +86,11 @@ DirectProject 自身的 `read_direct_project_conversation` 也必须在 blocking

 ## 常用设置职责

+本地配置 `llm.customEnabled` 为 `true` 时，常用设置开放自定义 Responses 连接、端点模型发现与勾选预览；开关只允许手动修改配置文件。模型选择、直连与凭据边界以 [AGC 后台模型别名与对话选择](./【技术方案】AGC后台模型别名与对话选择-2026-09-05.md) 的“本地自定义 LLM”为准，默认仍使用官方服务。
+
 常用设置负责运行参数的读取、编辑和保存，配置读写独立于账号权限诊断。账号权限由登录会话与实际智能服务请求链路处理，设置面板只维护配置草稿与读写反馈。

-保存配置复用写入前读取的高优先级本地覆盖内容：常用设置同步覆盖文件中已有的对应配置项，并保留当前模型 ID 和默认模型标记；模型选择仅同步 `selectedModelId` 与 `selectedModelIsDefault`；无冲突时不写覆盖文件。所有内容先完成序列化，多文件写入前保存原始内容，任一写入失败时逆序恢复已变更文件，回滚失败须明确报告。各文件沿用现有原子写入，不提供断电或进程崩溃下的多文件事务保证。全部成功后直接返回规范化配置，不执行保存后回读或外部诊断；单文件保存保持原路径。
+保存配置复用写入前读取的高优先级本地覆盖内容：常用设置同步覆盖文件中已有的对应配置项，并保留当前模型 ID 和默认模型标记；自定义模式取消勾选当前模型时回退第一项，并同步覆盖文件中的选择。模型选择仅同步 `selectedModelId` 与 `selectedModelIsDefault`；无冲突时不写覆盖文件。所有内容先完成序列化，多文件写入前保存原始内容，任一写入失败时逆序恢复已变更文件，回滚失败须明确报告。各文件沿用现有原子写入，不提供断电或进程崩溃下的多文件事务保证。全部成功后直接返回规范化配置，不执行保存后回读或外部诊断；单文件保存保持原路径。

 ## 2026-09-09 manifest 资源功能分类与自定义标签（UI 与写入）

@@ -546,6 +576,7 @@ Agent Runtime 负责：
 - 2026-07-10 补充：`agent.delegate` 已形成可恢复的父子任务闭环。`delegationId` 由 durable pending action 的 `actionId` 派生，子任务记录会保存 `parentAgentId / parentRunId / delegationId`，终态记录额外保存经过统一凭据清洗和安全截断的 `terminalDetail`；同一委派的提交和回执分别受 delegation 级 OS 文件锁保护，同一目标 Agent 的 runId 分配与 pending 追加还受任务账本 OS 锁保护。子任务进入 `completed / failed / cancelled / budget-exhausted` 任一终态时，Runtime 按 `delegationId` 幂等生成且至多生成一次 `agent.delegate.result` 回执，失败、排队或活跃取消、预算耗尽都必须回传，不能只覆盖成功。回执会向父 Agent 既有队列追加固定 runId、`source=agent-delegate-receipt` 的续跑任务，把完整的已清洗 `terminalDetail` 交回父 run，不再只保留 80 字符 UI 摘要；回执 prompt 明确禁止重复同一委派，排队期间不提前写入父会话，真正开始执行时才幂等落盘，用户消息或回执消息落盘失败时不会进入 LLM。回执任务保留父 run 关联，并在真正开始或恢复前再次检查父 run 状态，关联缺失或父 run 不存在时失败关闭；该续跑仍受父 Agent 原有 FIFO、per-Agent OS 锁、权限确认、取消、恢复和 `needs-reconciliation` 屏障约束，不直接重入父 run、不插队、不新增独立 worker；父 run 已取消或普通失败时只保留 suppressed receipt 审计，不自动复活，父 Session 归档与切换会被未结束委派阻止，极端归档竞态下回执回落到父 Agent 当前可写 Session。恢复先恢复 pending action / reconciliation 屏障，再扫描“子任务终态已落盘但回执未提交”的窗口并补齐缺失回执；`needs-reconciliation` 本身不回执，只有人工核对后最终取消才回传 `cancelled`。
 - 历史记录（已由 V1.1 独立 Runner 替代）：Runtime 最初通过 `resume_game_creator_agent_runtime_tasks` 把本地 JSONL 队列重接到当前 App 进程。当前恢复入口仍保留权限、任务顺序和 `agent.runtime.background_task.recovered` 审计语义，但实际由独立 Runner 接管原 run / session；已发出的上游 LLM 请求仍不能从网络中间点续传。2026-07-27 起，Runner 归 Tauri GUI 生命周期所有，同一 AppData 只允许一个 GUI owner。GUI 启动子进程会显式声明 `--gui-owner-required` 并在就绪后 attach owner；Runner 若在启动检查前已发现 owner 释放则直接失败，不得退化成 CLI-owned Runner。Runner 使用独立 watchdog 线程每 100ms 监控 owner OS 锁，不依赖服务端主循环继续推进；owner 丢失后先触发 1.5 秒共享 deadline 的 draining、Provider 中断和 process session 回收，若主循环或排空链路卡死则在 1.75 秒后由 Runner 自身进程安全硬退出并清理匹配 bootId 的 endpoint。GUI 客户端还必须把完整 `runner.attach_gui_owner` 参数作为绑定规范化 AppData 的进程内登记保存；`ensure_external_agent_runner` 无论复用既有 endpoint 还是启动新 Runner，都要在把 endpoint 交给 Runtime 写请求前按新 `bootId` 补登记。同一登记 generation 在同一 boot 上幂等，补登记失败不得记录成功 boot 且本次 `ensure` 失败关闭；未建立 GUI 登记的普通 CLI 不执行该重放。OS owner 锁与 watchdog 已成立只代表进程受 GUI 生命周期约束，不能替代事件 sink 等进程内附加能力的逐 boot 恢复。因此正常最终退出、panic、SIGKILL 和 setup 中途失败都不会再因 busy 或主循环卡死而残留后台进程。endpoint 缺失 / 读取失败必须结合 Runner 实例锁判断；GUI 客户端强制兜底在 Linux 使用 pidfd、Windows 使用稳定进程 handle。macOS 没有等价稳定句柄，客户端不得在 start identity 检查后按裸 PID 强杀，而由跨平台 Runner 自身 watchdog 提供硬退出兜底。旧 endpoint 缺 start identity 时，只有认证 ping 精确匹配 PID + bootId 才允许迁移 busy 旧 Runner。未完成任务保持 durable 状态并在下一次启动走 reconciliation / recovery，不能伪造 completed 或重放副作用。关闭单个 WebView / 子窗口和普通 CLI 退出不触发该行为，版本切换与人工命令仍可使用只关闭空闲实例的 `runner.shutdown_if_idle`。
 - 2026-08-23 Runner 协议 v7 GUI owner 会话权威补充：GUI 取得 owner OS 锁时产生随机 `owner epoch`，并在私有 AppData 持久化只含 `owner epoch + session revision` 的 claim；每次登录、refresh、退出或换号都必须先单调推进 durable session revision，再同步 Runner。`runner.attach_gui_owner` 是 Runner 接受平台会话快照的唯一授权入口；只有 attach 携带的 epoch/revision 与 durable claim 完全一致才可安装或清除会话，新 GUI epoch 可替换旧进程留下的高 `authGeneration`，不用可在新 WebView 重置的 generation 猜测进程所有权。Runner 在 claim 缺失、不可读或与当前 attach 身份失配时立即清空进程内平台会话，并阻断除重新 attach 及必要管理请求以外的 Runtime 工作；旧 `platform.session.install/clear` 协议不再是授权入口。GUI 会话同步未得到完整 attach 确认时本地变更必须失败，并隔离或停止旧 Runner；即使进程终止失败，claim 失配门禁也不允许旧账号继续发起 Runtime 请求。claim 不保存 Access Token，Token 只随当次受保护的 attach IPC 进入 Runner 内存。
+- 2026-09-16 多窗口更正：同一 AppData 不再只允许一个 GUI 界面进程。原 owner OS 锁改为可被多个界面进程同时持有的参与者锁（`agent-runner.gui-participant.lock`），Runner 以“能否独占取得该锁”判断是否仍有界面进程存活，watchdog 与 attach 门禁都改用该判定。新增窗口默认只**采纳** durable claim（读同一 epoch/revision 并 attach），只有登录、refresh、退出或换号才发布新 claim（新 epoch + 本窗口 revision），因此同 claim 的重复 attach 不再清空平台会话，epoch 变化才允许强制替换。事件接收端从单槽改为按 token 去重的注册表并广播，保证第二个窗口 attach 后第一个窗口仍收到 manifest 失效与 Runtime update relay。claim 一致性与失败关闭语义不变。详见同文档「2026-09-16 AGC 同 AppData 多窗口共享 Agent Runner」。
 - 2026-08-05 GUI owner attachment 确认补充：登记参数必须保存 GUI manifest 事件接收端的真实 `event_sink_port` 与 `event_sink_token`，不得借用 actionId 等无关字段作为测试替身。每次 attach RPC 只有同时返回 `attached=true` 与 `eventSinkAttached=true` 才能把当前 `bootId` 标记为已登记；`eventSinkAttached` 缺失、为 false 或普通 RPC 失败都保持当前 boot 待重试。sink token 只留在私有进程内登记和 RPC 参数中，不进入日志、错误文本或公共状态。
 - 2026-07-10 补充，2026-07-16 由 V1.28 澄清：后台 planning 与预算内 final reply 使用专用最小上下文，只预置 Agent 身份、sessionId、runId、执行模式和工具策略；Agent 私有记忆、项目记忆、黑板、对话、资产、项目索引与文件正文只能经对应工具通过权限 gate 后作为 observation 进入下一轮。只有开发窗口的专业 Agent 前台直调可使用对应角色上下文；正式用户前台现已统一进入 `project-supervisor`。长黑板、记忆和对话按尾部截断，确保最新结论与最新定向消息优先保留。
 - 2026-07-10 补充，2026-07-16 由 V1.28 澄清：同一 Agent 的开发前台直调、流式调试和后台任务统一使用 `.agent/runtime/locks/<agentId>.lock` OS 文件锁。开发前台不再在整个 LLM 请求期间占用项目级写锁；同 Agent 后台任务在开发前台运行时只入队，前台成功或失败后把当前 Agent 锁直接移交给 drain，不重新抢锁，也不允许 drain 启动异常把已经完成的调试结果改判为失败。正式用户 GUI 不通过该入口直聊专业 Agent；不同 Agent 继续并行，真实项目写工具只在副作用执行期间短暂申请项目写锁。
@@ -1445,3 +1476,42 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - 运行中的正文和工具按原有唯一回合流实时显示；完成后，除最终回复和失败提示外，中间文本与所有工具调用统一放入默认收起的“执行过程”，允许手动展开，刷新或重新进入仍默认收起。
 - 最终回复沿用 Runtime 的最后一个 assistant item 合同，不按文本长度或相似度判断。失败回合不把最后一句过程输出伪装成最终回复。无流历史按同一用户消息边界划分，只保留最后一条 assistant 回复在外；用户消息与失败提示始终保留。
 - 验收覆盖已完成回合重进、真实活动回合恢复、跨项目迟到快照、运行到完成自动收起、历史无流、失败、发送时间刷新和旧记录时间缺失。不改变实际工具执行、鉴权、数据库或用户项目内容。
+
+## 2026-09-16 AGC 同 AppData 多窗口共享 Agent Runner
+
+### 目标与非目标
+
+- 目标：同一个 AppData 可以同时运行多个 AGC 界面进程，它们共享同一个 Agent Runner、同一份平台登录态权威和同一份项目事实，并且都继续收到 manifest 失效与 Runtime update relay。
+- 非目标：不引入多 Runner、不做跨 AppData 的会话共享、不改变渲染层 generation 语义、不修改平台 HTTP 契约、SpacetimeDB schema 与 `/api/external/v1`。
+
+### 参与入口、状态与跨模块边界
+
+- 界面进程持有的 OS 锁改为**参与者锁** `agent-runner.gui-participant.lock`：它以共享句柄打开，任意数量的界面进程可同时持有；Runner、watchdog 与 attach 门禁只做“能否独占取得该锁”的探测，独占成功即表示已无界面进程存活。
+- durable claim `agent-runner.gui-owner.claim.json` 仍是唯一的 owner 授权记录，内容仍为 `ownerEpoch + sessionRevision`；claim 不保存 Access Token。
+- 项目级 `.agent/project.lock` 不变：多窗口共享 Runner 不等于共享项目写权，同一项目同一时刻仍只有一个写者。
+
+### 正常、失败、重试与幂等行为
+
+- 采纳：窗口启动时先读取 durable claim 并以同一 `epoch/revision` attach；claim 缺失或不可读时才发布新 claim。采纳路径不写 claim。
+- 发布：登录、refresh、退出或换号时，窗口写入新 claim（新 epoch + 本窗口 revision）再 attach；同一次发布在多个窗口并发发生时以最后一次成功写入的 claim 为准，落败窗口按最新 claim 重试，重试仍有界失败时向用户暴露错误，不做隐式合并。
+- 幂等：同一 claim 的重复 attach 是空操作，不得清空或替换 Runner 平台登录态；只有 epoch 变化或携带明确登出参数的 attach 才允许替换 / 清空。
+- 失败关闭：attach 携带的 epoch/revision 与 durable claim 不一致、claim 不可读、或 claim 在 attach 提交期间变化时，Runner 继续清空进程内平台会话并阻断除重新 attach 与必要管理请求以外的 Runtime 工作。
+- 事件：manifest 失效与 Runtime update relay 广播到全部已登记接收端（按 `event_sink_token` 去重，发送失败即淘汰该接收端），单个窗口退出或接收端失效不得影响其它窗口。
+- 生命周期：Runner 跟随“是否仍有界面进程存活”，不跟随某一个窗口；全部窗口退出后必须在有界时间内关停并清理 endpoint、释放实例锁。
+
+### 契约与兼容
+
+- 本机 GUI ↔ Runner 协议方法与参数不变；变化只在参与锁语义、claim 采纳/发布时机与事件接收端注册表。
+- 已退役的“同一 AppData 只允许一个 GUI owner”行为不再保留兼容分支；`startup.runner.owner-lock.failed` 诊断分类改名为参与者锁失败，仅在真正无法建立参与锁时出现。
+- 混用新旧版本二进制访问同一 AppData 不属于支持场景：旧版本仍以独占方式持有旧锁文件，可能让新版本判定为“仍有界面进程存活”。
+
+### 验收标准与证据来源
+
+- 定向 Rust 测试：参与者锁可多进程同时持有、全部释放后存活判定为假；同 claim 重复 attach 不改写登录态；epoch 变化才强制替换；两个接收端都收到同一事件；claim 采纳与发布的失败关闭路径。
+- 运行时 smoke：同一 AppData 启动两个真实 GUI，两个进程都完成 `startup.setup.complete`，`--agent-runner` 进程只有一个，关闭其中一个后另一个仍可继续使用 Runner。
+- 边界：项目级写锁继续拒绝两个窗口同时写同一项目；新增日志与错误文案不含 Token、Access Token、API Key 与绝对路径。
+
+### 未决问题
+
+- 两个窗口同时对同一项目发起 Runtime 写请求时，用户体验仍由项目级写锁串行决定；本次不引入跨窗口排队提示。
+- 平台会话在窗口间传播依赖共享 localStorage 与 Runner 权威；渲染层不做跨窗口事件推送，另一个窗口在下一次会话校验或刷新时收敛。
@@ -132,6 +132,8 @@ Runtime 不维护文档版本号，不解析文档版本，不提供版本回退

 一轮有多个工具调用时沿用正常工具执行循环。澄清或审批进入等待后，不继续请求 Provider，也不执行同批剩余文件操作；未执行调用明确记录为因等待用户而未执行，不伪造成功结果。恢复历史必须保持工具调用与结果配对，避免出现缺少 tool output 的协议错误。这属于协议与暂停处理，不引入同轮调用次数门禁。

+单次策划工具不再竞争项目级写锁；策划命令锁与会话原子写入已保证同一会话内工具按批次顺序执行。若进程在工具执行标记与结果落盘之间中断，重开项目时的只读 hydrate 必须在拿到策划命令锁后自动续跑原回合，为不确定调用补写“执行结果未保存”的工具错误、跳过剩余调用，并把错误交回 Provider 自愈；不得重放文件副作用，也不要求用户手动恢复。
+
 迁移工具集合：

 ```text
@@ -150,7 +152,7 @@ get_workflow_status

 工具使用相对工作区路径。工具执行结果继续通过 Runtime 统一记录和展示，但不向 Agent 暴露宿主绝对路径。

-`patch_file` 保留原型按唯一原文匹配修改的语义、换行归一化和缺文件错误。正常工作区写入与删除不逐次请求用户审批；阶段审批不能被复用为文件操作许可。
+`patch_file` 保留原型按唯一原文匹配、范围不重叠、全部通过才原子写入的语义、换行归一化和缺文件错误。批量 edits 会一次性完成全部校验，并把未找到、多处匹配、重叠等失败项汇总返回；未找到时同时给出候选行号和可见化缩进提示，帮助 Provider 基于当前文件修正锚点。正常工作区写入与删除不逐次请求用户审批；阶段审批不能被复用为文件操作许可。

 `list_resources` 一次返回完整逻辑分类、资源 ID、标题和简介；`read_resource` 按一个资源 ID 读取一个文件。资源描述不增加 `required=true/false` 分类，也不增加引导同轮多次调用的说明。

@@ -4,6 +4,8 @@

 Git hook 的临时仓库测试必须清除子进程继承的仓库定位环境（例如 `GIT_DIR`、`GIT_WORK_TREE`、`GIT_INDEX_FILE`）；仅设置 `cwd` 不能隔离 Git。回归应从带这些变量的外层仓库运行，验证外层引用、索引与配置不变。临时测试文件必须留在独立目录并清理，不得通过测试生成主仓库提交或覆盖 ESLint、Prettier 配置。修复 lint 配置时保留原有规则、忽略范围与零警告门禁，不以关闭规则代替排障。

+链接工作树（`git worktree`）里执行 `git push`、`git commit` 时，Git 会把 `GIT_DIR`（指向该工作树的管理目录）、`GIT_WORK_TREE`、`GIT_INDEX_FILE` 注入 Hook，`npm`、`lint-staged` 与测试夹具整链条继承；夹具的 `git config` 会写到共享 `.git/config`（此后所有提交 author 变成夹具身份），夹具的 `git init` 会重写 `core.bare` 或 `core.worktree`。因此 `.husky/pre-commit`、`.husky/pre-push` 与 `scripts/check-repository-ci.sh` 入口必须 `unset GIT_DIR GIT_WORK_TREE GIT_INDEX_FILE GIT_COMMON_DIR GIT_PREFIX GIT_CONFIG_PARAMETERS GIT_CEILING_DIRECTORIES`，夹具 Git 调用还要自检 `git rev-parse --show-toplevel` 等于夹具目录，落到外部仓库时直接失败。真实仓库被污染后的修复顺序：备份 `.git/config` → `git config --unset core.worktree` → 确认 `core.bare=false` → `git config --unset user.name` 与 `user.email` 恢复全局身份 → 核对 `.git/worktrees/*/config.worktree` → 用 `git checkout HEAD -- .` 回填被劫持期间漏掉的检出（未跟踪文件不动）。
+
 Stdb 发布以 root 准备文件、再切换 `spacetimedb` 用户执行时，WASM 必须放在服务用户可遍历的父目录下。生产脚本在 `/var/tmp` 创建随机私有目录并移交给发布用户，退出时清理；不能仅修改子目录所有权后继续从 `/root` 下读取。发布成功的判据仍是完整 Full Build 的 Stdb、API、Web 发布及退出维护模式全部成功。

 更新时间：`2026-08-05`
@@ -133,7 +135,11 @@ BgFilter 对已经落入私有 OSS 的生成原图、动作抽取帧和手动去

 普通图片错误素材类型清理使用 `npm run spacetime:editor-image-asset-kind:clean -- --database <database> --server-url <url>`，只能由已授权 migration operator 执行。先进入维护模式并发布包含 `clean_editor_image_asset_kind_and_return` 的 SpacetimeDB module，并保持旧版本 API / controller / worker 停止；随后运行默认全量 dry-run，核对 `asset → project-resource → showcase → canvas` 各 scope 的扫描数、命中行数、字段数和 blocker 均符合预期，再追加 `--apply`。脚本对每批重新 dry-run、绑定包含画布迁移摘要、结构化 layer 与 generation-dialog 权威 JSON 的 SHA-256，最后自动从头复核零命中；任一画布数据异常都会只输出哈希化 ID、scope 与原因并停止，不能跳过。清理只处理精确业务旧值，不修改 `asset_object.asset_kind`、MIME 或媒体类型；project-resource scope 在清行前验证同工程 migration 并将其状态纳入批次 hash，layout version 0 的 legacy 画布可以没有 migration，但 structured 画布缺 migration 必须立即形成 blocker，资源行不得先被清空；清行后能保持原 status 不变量时立即刷新摘要，否则只允许留给后续精确 canvas 字段清理收口。canvas scope 在任何布局写入前再次按 active / backfilled / rolled_back 状态验证原 migration 凭证和双份 legacy / structured 不变量，将 `editor_canvas_generation_dialog.dialog_json` 与 layer rows 一并扫描并在同一事务 patch；只允许本批资源清零及精确字段删除造成的差异，写入后从全部结构化权威行重建 layout、再次复核新状态才受控重签摘要，同时保持业务 revision、migration status 与全部时间戳不变。新版本 API、SpacetimeDB storage 创建入口、legacy 画布元数据提取和项目资源落表边界都会将 trim 后精确等于 `image` 的 `assetKind` 归一为 `NULL`，防止旧页面、滞留请求或 legacy 保存重新制造废弃值。完成零残留复核，并分别确认 cleaned backfilled 可激活、active 可继续保存、rolled_back 可重复复检后恢复应用版本，最后退出维护。Stdb build artifact 和完整 release 包必须同时包含 `scripts/spacetime-clean-editor-image-asset-kind.mjs` 与 `scripts/spacetime-migration-common.mjs`。

-自 2026-07-11 起，`Genarrative-Full-Build-And-Deploy` 的每日 04:00 timer 默认以 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal` 对仅供开发使用的 dev 服务器执行 Stdb → API → Web 完整发布，不进入人工 rollout gate。三个下游 Build 都由 Full Job 显式传 `PUBLISH_AFTER_BUILD=false`，不得依赖下游 Job 默认值或提前各自发布；统一 Build 完成后仍由 Full Job 按固定顺序发布。人工维护窗口才选择 `pause-after-stdb`，且必须配置 `STDB_API_ROLLOUT_APPROVERS`。上文“定时构建缺少审批人时失败”的旧口径不再作为当前 dev 定时发布行为。
+`Genarrative-Scheduled-Revision-Trigger` 是唯一的定时入口，每小时检查一次（`H * * * *`，分钟由 Jenkins 按 Job 名散列，不等同于整点）。它只用 `git ls-remote` 解析 `SOURCE_BRANCH`（默认 `master`）的远端 HEAD，不 checkout 工作区；解析出的完整 commit 与上一次触发过的 revision 相同则标记 `NOT_BUILT` 并结束，不触发任何下游。
+
+revision 变化时，调度管线把同一个完整 commit 通过 `COMMIT_HASH` 同时传给 `Genarrative-Full-Build-And-Deploy` 与 `Genarrative-Agc-Windows-Build`，两条管线都按这个 commit 检出（Full Job 继续把 `env.SOURCE_COMMIT` 透传给 Web / API / Stdb 的 Build、Publish、Deploy），因此两个产物必然来自同一个版本，不会各自解析分支 HEAD 造成漂移。两条下游管线自身不带任何定时触发器，也不在管线内部做版本比较。Full Job 默认以 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal` 对仅供开发使用的 dev 服务器执行 Stdb → API → Web 完整发布，不进入人工 rollout gate；三个下游 Build 都由 Full Job 显式传 `PUBLISH_AFTER_BUILD=false`，统一 Build 完成后仍由 Full Job 按固定顺序发布。人工维护窗口才选择 `pause-after-stdb`，且必须配置 `STDB_API_ROLLOUT_APPROVERS`。
+
+调度状态是调度 Job 工作区里的 `.jenkins-last-triggered-revision`，构建描述同时回显本次 revision 与结果。工作区被清理（例如 `Wipe Out Workspace`）或状态文件缺失时，下一次运行按“版本变化”处理并触发一次，之后恢复稳定；需要重建同一版本时勾选 `FORCE_TRIGGER`。Job 按仓库内 `jenkins/scheduled-revision-trigger-job-config.xml` 创建：`scriptPath=jenkins/Jenkinsfile.scheduled-revision-trigger`、Git 入口 `ssh://git@127.0.0.1:2222/GenarrativeAI/Genarrative.git`、凭据 `genarrative-local-gitea-ssh`、`<triggers/>` 留空（定时器写在 Jenkinsfile 里）。推送后必须让三个 live Job 各自加载一次新 Jenkinsfile，并只读核对 `config.xml`：Full 与 AGC 不再有 cron，定时只来自新调度 Job；只改 Jenkinsfile 而不确认 live 配置时，旧 cron 仍会继续触发。

 Full Job 通过 `EXIT_MAINTENANCE_MODE_AFTER_COMPLETION` 明确选择完整发布成功后是否退出维护，默认勾选以保持历史行为。Full 对 Stdb Publish 和 API Deploy 两个下游阶段都固定传 `KEEP_MAINTENANCE_MODE=true`，让 maintenance marker 持续覆盖 Stdb → API → Web 整段发布；Web Deploy 成功后才进入独立 `Exit Maintenance` 阶段。该阶段只能通过 `agent none` 和显式 `node(...)` 分配目标机，直接执行 `/opt/genarrative/current/scripts/deploy/maintenance-off.sh`；目标机不得 checkout Git、挂载 Git SSH 凭据或依赖 Jenkins workspace 源码。取消勾选时跳过最终退出阶段，便于内网验收完成后人工恢复公网。`Genarrative-Api-Deploy` 也单独暴露 `KEEP_MAINTENANCE_MODE` 参数，并转换为随发布包脚本的 `--keep-maintenance-mode`；失败路径仍按既有 current 切换边界保留或退出维护，不受成功态选项覆盖。外部生成 queue 的 `warning` 由 API/worker 固化为可直接展示的完整文案，Web 不再补前缀，因此 API/worker 与 Web 必须在同一维护窗口按同一版本协调发布；分开运行 Job 时先保持维护态完成 API/worker，再发布 Web，二者完成后才能恢复公网，不得在公网可用期间只滚动其中一侧。

@@ -664,6 +670,12 @@ Pingora current release 自审脚本 `scripts/ops/pingora-current-release-audit.

 `Genarrative-Web-Build` 打包 `web.tar.gz` 前、`Genarrative-Web-Deploy` 解包后都会把 Web 静态目录规范为目录 `755`、文件 `644`。如果前端页面能打开但 public 图片、字体或音频返回 `403 Forbidden`，优先检查当前 `/srv/genarrative/web` 指向的 release 中对应文件权限是否被异常归档为 `600`，临时恢复可对该 release 的 `web` 目录执行目录 `755`、文件 `644` 的权限修正。

+### CI 宿主 CPU 上限（Jenkins 16 核 / Gitea Actions runner 12 核）
+
+`genarrative-station` 上 Jenkins Built-In Node 与 Gitea Actions runner 容器共用同一台 32 逻辑核宿主机，两路 CI 都必须有硬上限，避免构建期把机器顶满、让交互用户卡顿。Jenkins 固定 16 核（50%）：在宿主执行 `systemctl set-property jenkins.service CPUQuota=1600%`，立即生效且不需要重启 Jenkins，drop-in 落在 `/etc/systemd/system.control/jenkins.service.d/50-CPUQuota.conf`；该配额覆盖 Built-In Node 上所有子构建（Web / Api / Stdb 的 `npm ci`、Vitest、`tsc`、`cargo` 都跑在这台机器上），Deploy 阶段在远端 `genarrative-dev-deploy` / `genarrative-release-deploy` agent 执行，不受该上限约束。Gitea Actions runner 固定 12 核（37.5%）：`/opt/gitea-stack/compose.yml` 的 `runner.cpus` 为 `"12.0"`，调整运行中的容器用 `docker update --cpus=12 gitea-runner`（不重建容器、不中断在跑 job）；需要让容器配置与 compose 完全一致时，先确认 Gitea 没有 `in_progress` run，再 `cd /opt/gitea-stack && docker compose up -d runner`。
+
+核验与回滚：`cat /sys/fs/cgroup/system.slice/jenkins.service/cpu.max` 期望 `1600000 100000`，`docker inspect gitea-runner --format '{{.HostConfig.NanoCpus}}'` 期望 `12000000000`，`cat /sys/fs/cgroup/system.slice/docker-<runner 容器 ID>.scope/cpu.max` 期望 `1200000 100000`。两处 cgroup 的 `cpu.stat` 里 `nr_throttled` / `throttled_usec` 持续增长说明工作负载已经顶到上限，属预期而不是故障。放宽或回滚用 `sudo systemctl set-property jenkins.service CPUQuota=<n>%`、`sudo systemctl revert jenkins.service`、`docker update --cpus=<n> gitea-runner`，并同步 `/opt/gitea-stack/compose.yml`（改前先备份该文件）。
+
 ## 维护模式只拦截公网流量

 Nginx 与 Pingora 在维护 marker 存在时对内网来源绕过整站维护闸，主站页面与静态资源、普通 API、后台页面与 `/admin/api/**`、SpacetimeDB 路由均按非维护状态继续处理；公网应用主站、普通 API、后台和 SpacetimeDB 路由继续返回维护响应。内网范围为 IPv4 loopback / RFC1918 / link-local 和 IPv6 loopback / ULA / link-local。Nginx 只按 TCP `$remote_addr` 判定；Pingora 只按 TCP peer 判定，peer 为 loopback 的同机 Nginx 时才读取 Nginx 强制覆盖的 `X-Real-IP`，绝不能把客户端可伪造的 `X-Forwarded-For` 用作维护放行依据。应用本身的登录、管理员鉴权和其它业务鉴权不变。