Merge remote-tracking branch 'origin/master' into feat/jenkins-mac-build

# Conflicts: # docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md
2026-09-20 17:45:38 +08:00
parent b1cadd0cc8 e230d9dc32
commit bb1df3c6da
296 changed files with 9718 additions and 11046 deletions
@@ -27,14 +27,14 @@

 - [AGC 资源 kind 枚举化契约](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#2026-09-15-gamecreationapp-资源-kind-枚举化当前权威口径)：GameCreationApp 资源 kind 的 Rust enum、ts-rs 绑定、Unknown 可观测性和 shell 内重构边界。

- [策划 Agent 生产迁移与工作区浏览](./technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)：实施中；以自由协作原型为行为基线，复用生产基建，采用阶段审批与用户工作区文件浏览。无旧 V2 会话的策划入口切换到新设计 Agent。
+- [策划 Agent 生产迁移与工作区浏览](./technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)：已完成；当前策划入口统一使用 Design Agent，采用阶段审批与用户工作区文件浏览。旧 V1/V2 会话、命令、专用展示和测试不再作为兼容目标。

 - [LLM 累计额度结算](./technical/【技术方案】LLM累计额度结算-2026-09-05.md)：Router 累计额度、首次基线与原子钱包结算。

 - [AI 游戏创作智能体 App 实施计划](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)：当前 DirectProject、受控语义工具、UI workflow、资源和运行时合同。
 - [AGC 异步操作可恢复闭环](./【技术方案】AGC异步操作可恢复闭环-2026-09-14.md)：认证响应体、最近项目检查和首页自动创建的超时、逐项恢复与跨页防重合同。
 - [AGC 客户端稳定版生命周期大切换](./【技术方案】AGC客户端稳定版生命周期大切换-2026-09-14.md)：统一 operation、认证/Runner、项目入口、本地恢复和 dev-stack 身份边界。
- [策划会话 Runtime V2 接入与旧链路退役方案](./technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md)：新单 Agent 策划会话、GDD 策略、未来 MCP/Skill 兼容插槽、阶段任务与退役验收合同。
+- [策划会话 Runtime V2 接入与旧链路退役方案](./technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md)：历史方案，仅用于追溯 V2 的实现与退役过程，不作为当前实现依据。
 - [DirectProject Codex 原始历史与异常恢复](<./technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md>)：原始 Responses item 持久化、线程注入与异常回合收尾。
 - [DirectProject 对话历史单一事实源](./adr/【ADR】DirectProject对话历史单一事实源-2026-09-16.md)：AGC 项目开发对话只以项目对话历史与运行态事件为真相源，聊天投影不落盘。
 - [GameAgent 对话工具调用卡片](./technical/【技术方案】GameAgent对话工具调用卡片-2026-09-14.md)：把右侧对话里的执行命令 / 写文件投影成 Codex 风格可折叠卡片，含采集、独立历史文件、事件字段与回读契约。
@@ -48,7 +48,7 @@
 - [Direct 回合行为审计账本](./technical/【技术方案】Direct回合行为审计账本-2026-08-31.md)：Direct GUI 回合把 native 读 / MCP / 写文件落成项目内有界时间线，用于判断有没有打开本轮附件。
 - [项目开发工作台 PRD](./prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md)：当前工作台页面和验收边界。
 - [AGC 错误报告与诊断上传](./technical/【技术方案】AGC错误报告与诊断上传-2026-08-31.md)：当前进程错误事件、应用级日志和管理员查看器合同。
- [立项策划 Agent（Fast GDD）](<./technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md>)：旧 `project-supervisor-plan` / `project-planning` 历史会话的入口、审批和恢复合同；V2 切换时未完成旧会话强制失败。
+- [立项策划 Agent（Fast GDD）](<./technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md>)：历史 V1 方案，仅用于追溯；旧 `project-supervisor-plan` / `project-planning` 入口、审批、恢复和测试均已删除。
 - [GameAgent 资源自由画板与快速编辑](./technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md)
 - [AGC 栏目画布底部工具栏入口矩阵](./technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md)：栏目画布底部工具栏的入口矩阵、可用条件与验收口径。
 - [AGC 资源工作台三处交互收口改动前对照图](./technical/assets/agc-resource-workbench-ui-before-20260914/README.md)：任务侧栏两个关闭入口、左侧贴边折叠把手、顶部播放按钮居中悬浮三张改动前截图与问题说明。
@@ -28,8 +28,8 @@

 1. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_thread -- --nocapture`
 2. `cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml export_bindings`（生成 `src/features/project-workspace/generated/`），随后用 `prettier --write` 格式化生成目录，避免未格式化的 ts-rs 输出混进提交
-3. `npx vitest run apps/ai-game-creator-shell/tests/directThreadChat.test.ts apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts apps/ai-game-creator-shell/tests/directHistoryPaging.test.ts`
-4. `npx vitest run apps/ai-game-creator-shell/tests/appSurface/project-development.suite.ts`
+3. `npm run test -- apps/ai-game-creator-shell/tests/directThreadChat.test.ts apps/ai-game-creator-shell/tests/directTurnPresentation.test.ts apps/ai-game-creator-shell/tests/directHistoryPaging.test.ts apps/ai-game-creator-shell/tests/directHistoryAnchorGate.test.ts`
+4. `npm run test -- apps/ai-game-creator-shell/tests/appSurface.test.ts`（`project-development.suite.ts` 由该入口注册，不能作为独立测试入口；同时验证现役 Design Agent 的会话恢复与审批界面。）
 5. TypeScript 类型检查与 ESLint（范围同前次 DirectProject 迁移）。
 6. `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`

@@ -0,0 +1,92 @@
+# 【实施计划】退役策划 Agent V1/V2 解耦清理
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】退役策划Agent V1V2解耦清理-2026-09-15.md` |
+| Status | ready |
+| Owner | Codex |
+
+## 一句话交付结果
+
+删除退役策划 V1/V2 及其耦合的 Supervisor 产品残留，让当前 Design Agent 独立运行、做游戏走 DirectCodex 并恢复仓库编译；保留通用 Supervisor 和做游戏 16 Agent DAG。
+
+## 验收判据
+
+当前分支能够通过 AGC 前端 typecheck 和受影响定向测试；Design Agent 的新建、恢复、澄清、阶段审批和 reasoning 展示仍由当前 Design Agent 链路完成；旧 V2 IPC、旧 GDD 类型和旧前端测试契约不再存在。
+
+## 修改边界
+
+允许修改：
+
+- `apps/ai-game-creator-shell/src/App.tsx` 中旧 V2 状态、helper、IPC 分支和旧 UI props。
+- `apps/ai-game-creator-shell/src/app/types.ts` 中旧 GDD 类型。
+- `apps/ai-game-creator-shell/src/features/project-workspace/planningSessionV2.ts` 及其直接调用方。
+- `apps/ai-game-creator-shell/tests/appSurface/harness.ts`、`home.suite.ts`、旧策划事件测试。
+- `apps/ai-game-creator-shell/src/styles.css` 中只属于旧 Plan GDD / planning lane 的样式。
+- 没有现役调用方的旧策划身份 fixture、注释和文档索引。
+- 为通过编译所需的最小共享残留删除或改名。
+
+明确不修改：
+
+- `directCodex` 主链路和当前 Design Agent。
+- 16 Agent DAG、`supervisor-swarm` 测试和通用 Runtime 编排；只处理删除策划耦合后直接造成的编译错误。
+- 当前 Design Agent Rust runtime、Design Agent 资源包和 Design Agent IPC 协议。
+- 公开 API、SpacetimeDB schema、迁移和历史持久化数据格式。
+
+## 实现顺序与提交拆分
+
+### 提交一：解耦 Design Agent 状态命名
+
+- 将新版 Design Agent 实际使用的 `planningV2*` transient reply、reasoning、active ref 和相关 lane 控制改成 Design Agent 专属状态。
+- 保持行为不变，不删除旧 V2 会话代码。
+- 验证：AGC typecheck、`git diff --check`。
+
+### 提交二：删除 App 旧 V2 会话控制流
+
+- 删除仅服务旧策划的 Supervisor 产品入口、恢复、轮询和聊天提交分支。
+- 删除旧 V2 session/GDD 状态和 helper。
+- 删除项目打开、消息发送、问询回答、审批和旧流式事件分支。
+- 将“做方案”只连接到当前 Design Agent hydrate/continue/decide 路径，将“做游戏/做素材”只连接到 DirectCodex。
+- 保留 `planningStartMode` 作为入口路由字段，避免无关扩大重命名。
+- 验证：AGC typecheck；必要时运行 App 启动相关定向 suite。
+
+### 提交三：删除旧 TypeScript 适配层和类型
+
+- 删除 `planningSessionV2.ts`。
+- 删除 `PlanGddDecisionAction`、`PlanGddStateViewV1` 及所有直接导入。
+- 重新执行旧符号检索，确认没有残留调用方。
+- 验证：AGC typecheck、`npm run check:encoding`、`git diff --check`。
+
+### 提交四：清理测试、事件契约和 CSS
+
+- 精确删除 harness 中旧 V2/GDD 工厂、mock、调用记录和导出。
+- 精确删除首页 suite 中旧 V2 IPC 断言。
+- 删除旧 `planning-session-v2-stream` 事件测试。
+- 删除 Plan GDD、GDD 审批卡和 planning lane 专属 CSS 及过时说明。
+- 验证：appSurface 定向测试、事件订阅定向测试、AGC typecheck、编码和 diff 检查。
+
+### 提交五：收口确定失效的身份残留和文档入口
+
+- 只处理因 V1/V2 退役而确定失效的旧身份展示、测试 fixture、注释和文档索引。
+- 不扫描或重构做游戏 DAG；共享代码只在其旧策划用途已确定死且删除能直接解决编译/测试问题时处理。
+- 验证：旧策划符号定向检索、相关测试、编码和 diff 检查。
+
+## 验证命令
+
+1. `npm --prefix apps/ai-game-creator-shell run typecheck`
+2. `npm run check:encoding`
+3. `git diff --check`
+4. `npm --prefix apps/ai-game-creator-shell exec vitest run tests/appSurface.test.ts`
+5. 受影响 Rust 文件变化后运行 `cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`
+6. 完成全部提交后再次执行旧策划符号检索，并核对 `git status` 与提交边界
+
+## 风险与回滚点
+
+- 最大风险是新版 Design Agent 复用了旧变量名；必须先完成提交一，再删除旧 helper。
+- `ProjectSupervisorView` 已经移除旧 GDD props，App 传参残留会在提交二中一并删除。
+- 测试 harness 同时服务通用总控和 Design Agent，必须局部删除旧 mock，不能整段重写。
+- 若某次提交导致 Design Agent 测试失败，只回滚该独立提交，不恢复旧 V2 兼容层。
+
+## 完成后的临时文档处理
+
+全部里程碑验收通过后，删除本里程碑和实施计划两份临时文档；把仍然有效的长期边界同步回现行 Design Agent 技术方案和项目记忆，不保留阶段性提交步骤。
@@ -0,0 +1,21 @@
+# 关联里程碑
+
+`【里程碑】退役策划V2 Rust Runtime清理-2026-09-14.md`
+
+# 修改顺序
+
+1. 从 `runtime_protocol.rs` 移除 V2 模块声明与导出。
+2. 从 `main.rs` / `commands.rs` 移除 V2 command 注册和仅供 V2 的导入。
+3. 删除 V2 Rust 模块及其专属单元测试；保留共享 GDD 模型或新版设计会话仍使用的类型。
+4. 用 `rg` 检查 V2 Rust 符号残留，修复编译引用。
+
+# 验证命令
+
+- `cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`
+- `npm run check:encoding`
+- `git diff --check`
+
+# 风险与回滚
+
+- 风险：V2 类型可能被共享测试或前端桥接代码引用。处理方式是按编译错误逐项判断，保留真正共享类型。
+- 回滚：按提交粒度回退本里程碑提交，不触碰前序 V1 清理提交。
@@ -0,0 +1,32 @@
+# 项目自动上传与后台工程下载实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】项目自动上传与后台工程下载-2026-09-19.md` |
+| Status | implemented-awaiting-runtime-validation |
+| Owner | 当前任务 Agent |
+
+## 修改边界
+
+- 客户端 project_snapshot 与实际窗口生命周期、相关定向测试。
+- shared-contracts 快照清单及后台 DTO、platform-oss 的受控清单枚举、api-server 管理员列表与 ZIP 下载、后台权限映射。
+- api-server 快照存储配置解析：默认目标与素材 bucket 分离，只有凭据可回退；不变更部署配置或搬迁对象。
+- admin-web 项目列表、现有路由/导航/API client 与相应测试。
+- 主规范、运维说明及必要共享约定。不修改 SpacetimeDB、External API、用户会话权威或线上配置。
+
+## 实现顺序
+
+1. 评审主规范与本里程碑，复现客户端项目枚举故障。
+2. 并行实现后台列表/ZIP、后台 UI；客户端只修已证实上传缺陷并补清单元数据。
+3. 集成契约、运行定向测试和 UI smoke，核查真实清单可还原目录；按证据更新验收状态。
+
+## 验证命令
+
+- `cargo test --locked -p platform-oss`、`cargo test --locked -p api-server project_snapshot`、`cargo test --locked -p shared-contracts`（server-rs）。
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml project_snapshot`。
+- `npm run admin-web:typecheck`、`npm run admin-web:build`、后台相关 Vitest。
+- `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
+
+## 风险与回滚
+
+旧清单无完整性声明，只能标记未知；完整工程含项目源码、素材和配置，排除依赖/构建缓存、凭据、会话与运行日志。下载失败不修改 OSS 或清单。本轮按用户授权提交推送，不部署；代码可独立回退。
@@ -0,0 +1,49 @@
+# 【里程碑】退役策划 Agent V1/V2 解耦清理
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | proposed |
+| Date | 2026-09-15 |
+| Parent Spec | `docs/technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md` |
+
+## 目标
+
+移除旧版策划 Agent V1、V2 的前端会话、审批、数据适配、测试契约和确定失效的展示残留；仅在删除策划链路时遇到已退役 Supervisor 功能耦合时一并删除该耦合，使“做方案”只使用当前 Design Agent、做游戏只使用 DirectCodex。
+
+## 范围
+
+- 解除当前 Design Agent 与旧 `planningV2` / `PlanGdd` 状态命名和控制流的耦合。
+- 删除仅服务旧策划的 Supervisor 产品入口、会话恢复、Runtime 轮询和聊天提交分支；保留通用 Supervisor 与做游戏 DAG。
+- 删除旧 V2 会话 hydrate、start、continue、审批和用户问询分支。
+- 删除旧 V2 TypeScript 会话适配层、旧 GDD 前端类型、测试 mock、旧事件契约和专属样式。
+- 清理确定没有现役调用方的旧策划身份说明、测试 fixture 和文档当前入口。
+- 保留当前 Design Agent 的会话、澄清、阶段审批、工作区浏览和 reasoning 展示行为。
+
+## 不在范围内
+
+- 不主动扫描、重构或整体删除做游戏 Agent 的 16 Agent DAG；只有策划删除直接造成编译或测试失败时才做最小修复。
+- 不删除 DirectCodex 或当前 Design Agent；必要时保留被两者复用的中性聊天表现组件。
+- 不为旧项目新增兼容层、迁移器、墓碑注释或退役行为测试。
+- 不修改 SpacetimeDB schema、公开 API、持久化迁移和现役 Design Agent 协议。
+
+## 依赖与前置条件
+
+- PR #159 的合并提交 `3d8e0211` 代表旧 Fast GDD / 策划 V1 的引入。
+- PR #305 的合并提交 `04128eb6` 同时包含 V1 大范围退役、策划 V2 会话链路和后续 Design Agent 迁移。
+- 当前分支已经删除 Rust V1/V2 Runtime 模块和旧审批组件，但前端仍残留旧 V2 调用方；实现前须保持工作树干净。
+
+## 验收标准
+
+- [ ] “做方案”入口和已有 Design Agent 项目只调用当前 Design Agent IPC，不再调用旧 `planning_*_v2` IPC。
+- [ ] 当前 Design Agent 的消息、reasoning、澄清、阶段审批和重试行为不依赖旧 V2 状态变量。
+- [ ] 源码中不再存在旧 V2 TypeScript 会话适配层、旧 `PlanGdd` 类型和旧前端审批契约。
+- [ ] 旧前端测试、事件测试和样式残留被删除或改为当前 Design Agent 契约。
+- [ ] 不主动修改做游戏 Supervisor + 16 Agent DAG；因共享退役代码删除产生的编译错误得到最小修复。
+- [ ] 前端 typecheck、相关定向测试、编码检查和 diff 检查通过；触及 Rust 时对应 cargo check 通过。
+
+## 证据要求
+
+- 自动化：`npm --prefix apps/ai-game-creator-shell run typecheck`、相关 appSurface 定向测试、`npm run check:encoding`、`git diff --check`。
+- 运行时：至少验证“做方案”新项目进入 Design Agent、已有 Design Agent 会话恢复、澄清/审批回合可继续。
+- 边界：确认 DirectCodex 和做游戏既有入口未被旧策划清理改动；确认旧 V2 IPC 字符串和旧事件契约不再进入现役前端。
@@ -0,0 +1,38 @@
+# Version
+
+V2-RUST-RETIRE-1
+
+# Status
+
+in-progress
+
+# Date
+
+2026-09-14
+
+# Parent Spec
+
+`docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md`
+
+# 目标
+
+删除已经被独立 Design Agent 取代的旧策划 V2 Rust Runtime、Tauri 命令注册和仅服务 V2 的模块导出，使桌面壳继续编译并保留做游戏 Agent 与新版 Design Agent。
+
+# 边界
+
+- 删除 `planning_policy_v2`、`planning_session_v2` 及仅供这两者使用的 V2 注册和调用。
+- 删除 V2 专属的 Tauri command 注册、模块导出和测试入口。
+- 保留 `design_runtime`、`design_tools`、`design_session`、通用 runtime、DirectProject 和做游戏 Agent。
+- 本里程碑不处理前端 V2 数据层、UI、文档索引和共享运行时中的可选清理。
+
+# 验收标准
+
+1. Rust 源码不再编译 `planning_policy_v2.rs` 或 `planning_session_v2.rs`。
+2. `main.rs`、`commands.rs` 和 runtime protocol 不再注册或导出 V2 命令。
+3. 新版 Design Agent 与做游戏 Agent 的 Rust 编译路径保持可用。
+4. 相关定向 Rust 测试和 `cargo check` 通过。
+
+# 依赖
+
+- 当前分支已包含 PR159 的 V1 清理。
+- 前端 V2 调用暂时保留，待后续里程碑同步删除。
@@ -0,0 +1,55 @@
+# 项目自动上传与后台工程下载
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | implemented-awaiting-runtime-validation |
+| Date | 2026-09-19 |
+| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的项目快照上传与后台工程下载合同 |
+
+## 目标与范围
+
+修复实际项目自动上传的已证实故障，并让有权限的后台管理员按项目查看远端快照、一键下载按原始目录还原的工程 ZIP。
+
+## 不在范围内
+
+客户端上传 UI、跨设备恢复、版本历史、数据库 schema、线上部署、自动补传全部未打开项目。
+
+## 依赖与前置条件
+
+延续现有私有 OSS 项目快照、平台会话与后台权限。真实 bucket 已只读确认只有两份历史模板清单；上传根因必须经确定性复现后修正。
+
+## 验收标准
+
+- [ ] 正式项目窗口可被同步调度识别；周期与关闭触发保持有界，失败有项目级诊断。
+- [ ] 未单独配置快照目标时仍使用 agc-dev，只复用资源存储凭据；显式快照目标保持有效，不迁移现存对象。
+- [ ] 后台列表显示项目名/ID、用户 ID、同步时间、文件数、体积和完整性，支持刷新与分页。
+- [ ] ZIP 按清单还原相对路径；不含对象存储摘要目录；空文件可上传与导出。
+- [ ] 清单名称/完整性变化在无内容差异时也提交，partial 可恢复 ready，历史缺字段不冒充 ready。
+- [ ] 缺失、损坏、越界路径和非完整清单失败关闭；历史未声明完整性的清单明确标记，允许导出已有文件但不称为完整工程。
+- [ ] 无后台权限不能读取项目或 ZIP；不泄漏凭据；ZIP 构建有体积、并发和临时文件清理边界。
+- [ ] 定向 Rust 测试、后台类型检查/构建、UI smoke、编码、文档索引和 diff 检查完成，运行时证据与未验证部分分别列出。
+
+## 证据要求
+
+自动化覆盖窗口身份、上传零字节、清单统计、目录还原、路径与校验和校验、后台路由权限。运行时优先只读现有 OSS 清单；测试不上传真实用户工程、不修改线上数据。
+
+## 已取得证据
+
+| 层次 | 结果 |
+| --- | --- |
+| 客户端 Rust `project_snapshot` | 22 通过、1 忽略（写入式真实上传 smoke 未运行）；含排队退出等待回归 |
+| 客户端前端生命周期与启动器 | 3 文件、10 测试通过；完整 AGC typecheck、skill-pack、check-config 通过 |
+| 后台页面、API client、路由与样式 | 44 测试通过；admin-web typecheck/build 通过 |
+| 后端快照与权限 | 14 定向测试通过；未认证路由矩阵与页签映射 2 测试通过 |
+| 默认存储目标 | 真实 AppConfig::from_env 配置回归 1 通过 |
+| OSS 存储层 | 全量 55 测试通过，含签名、特殊字符路径、读取上限与零字节 |
+| 真实 OSS 只读导出 | `project_snapshots_live_readonly_list_and_archive` 通过；limit=1 分页、2 清单、12 文件、73,424 字节，ZIP 解压路径/长度/摘要全匹配、临时文件清理通过；两份均为历史 unverified |
+| 浏览器 smoke | 模拟 API 的 1280 桌面与 390 窄屏通过；下载按钮可见，无整页横向溢出；中文 ZIP 文件名、Authorization、409 错误呈现通过 |
+| 通用门禁 | 编码、文档索引、production-ops、Rust 格式、客户端 Prettier 与 diff 检查通过 |
+
+## 剩余验证与环境边界
+
+`npm run dev:api-server -- --api-port 4198 --bgfilter-worker-port 4199 --api-timeout-seconds 600` 编译成功，但当前工作区配置的本地数据库 `xushi-p4wfr` 在 `127.0.0.1:3101` 返回 404，启动认证投影无法完成，故 `/healthz` 及完整 HTTP smoke 未通过。仅本任务启动的 API/worker 已停止；没有清库、迁移数据库、改 `.env` 或替换其它项目的验证目标。
+
+尚未替换安装版、构建新客户端发布包或部署；提交推送按用户本轮授权执行。当前条款已有上述自动化与只读存储证据，最终验收仍等待当前工作区数据库就绪后的 HTTP 联调，以及新客户端的隔离实机自动上传验证；完成后再关闭里程碑并清理两份计划。
@@ -1,7 +1,8 @@
 # 决策记录

 > 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
-> 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
+> 当前口径（2026-09-18）：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据。策划 Agent V1/V2 的 Runtime、专用命令、审批卡、展示适配和旧测试已删除；当前策划入口统一使用 Design Agent。如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
+
 ## 2026-09-17 GameCreationApp 资源 kind 只保留一份词汇表：严格解析 + `app_log!` 留痕

 - 背景：kind 曾经有三份实现——Rust 手写 `GAME_CREATION_APP_CANONICAL_ASSET_KINDS` + `canonical_game_creation_app_asset_kind()`（带 legacy 别名表与 `font → document` 特例）、TS 手写 `GAME_CREATION_APP_CANONICAL_ASSET_KINDS` + `GAME_CREATION_APP_LEGACY_ASSET_KINDS` + `canonicalGameCreationAppAssetKind()`、以及 ts-rs 生成的 TS union。两份手写表互相引用又各自收口，判据直接分叉（同一个 `"UI"` 一边归一成 `ui-design`、一边收口成 `unknown`），跨语言一致性只能靠正则解析源码的测试来钉。
@@ -223,7 +224,7 @@

 - 决策：待实施的生产迁移以自由协作策划原型为行为基线，仅复用 Provider、恢复、文件操作、审计和 UI 通信；不继承旧 Planning V2 的强制工具、问询轮数、GDD 内容校验和版本审批。保留五阶段与顾问态、当前阶段资源注入和产物存在性检查，系统阶段空必需清单不增加解析或登记功能。
 - 交互边界：正式审批由 ✅/❌ 决定；❌ 只取消待审批、不唤醒 Agent，等待审批时禁止发送消息但允许浏览工作区。用户可直接查看工作区，编辑可暂不做，不引入用户与 Agent 协同编辑锁或冲突合并。
- 影响范围：策划入口、会话与工具实现、资源打包、文件浏览；实施中。无旧 Planning V2 会话的策划项目走新设计 Agent，已有 V2 会话仍走原链路。
+- 影响范围：策划入口、会话与工具实现、资源打包、文件浏览；迁移已完成。当前入口统一使用新 Design Agent，旧 Planning V2 会话不再继续运行。
 - 关联文档：[策划 Agent 生产迁移与工作区浏览](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md)。

 ## 记录格式
@@ -8855,11 +8856,12 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 验证方式：`npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`（423 passed，含新增 6 条：栏目分流与总览不渲染、UI 栏 5 个入口载荷、前置缺失可点击说明且零请求、角色栏 2 个入口、音频入口走既有链路、上传 + 配对读清单，另 1 条工具栏与 Dock 的 CSS 几何契约）；`resourceCanvasBottomToolbar.test.tsx` 15 passed（新增）；`resourceCanvasGenerationEntry.test.tsx` 11 passed（新增单类型用例 1 条）；`projectResourceLiveIntegration.test.tsx` 25 passed（「生成素材」面板改名断言同步更新）；`npm run agc:typecheck` 全绿（**其中的 `check-config.mjs` 报错已因本轮落地调用方而消失**）、`npm run check:encoding`、`git diff --check` 干净。未 commit。
 - 关联文档：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（§3.10 / §7.9 / §8）、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`（S11 / S11a / §7.3）。

-## 2026-09-13 Cocos 插件按当前项目类型暴露
+## 2026-09-20 Cocos 与 Unity 插件独立于工程类型

- 决策：`agc-cocos-editor` 只有在当前受控项目通过 Cocos Creator 根目录识别（`package.json.creator.version` + 普通 `assets/`）时才暴露插件、面板和 Cocos 工具；无项目或其它项目类型均隐藏并失败关闭。
- 决策：项目切换离开 Cocos 时立即停止已运行的插件实例；启动、面板读取、插件 RPC、Runtime execute 和 DirectProject MCP 工具目录/执行入口全部再次校验项目类型。Cocos 编辑器操作优先经内置插件入口，禁止回退到项目 `extensions/`、`package.json` 插件或第三方 MCP。
- 验证：新增 builtin/plugin host 项目级门禁测试，Direct MCP fixture 补最小 Cocos 工程结构；Rust 定向测试、显式 `cocos-editor-execute` feature 编译、编码检查和 `git diff --check` 已执行。
+- 决策：`agc-cocos-editor` 与 `agc-unity-editor` 的插件列表、启动、面板、插件 RPC、Runtime 与 DirectProject 工具暴露不按当前工程类型过滤；无项目、普通 AGC、Godot、Cocos、Unity 上下文遵循同一套 enable、原生适配器、平台与 feature 规则。前端根据宿主列表中各插件状态分别自动启动，不按项目类型二选一，也不自动展开面板。
+- 决策：跨工程类型切换保留插件实例及管理能力，继续更新受控项目上下文、失效旧连接并隔离旧请求回执。实际编辑器操作仍要求当前受控项目匹配真实引擎工程与编辑器目标；显式跨项目路径、缺失项目、无目标进程、身份或握手不匹配均在派发前失败，权限、并发、期限与执行不确定阻断保持有效。
+- 边界：插件可见和工具可调用不能证明任意非引擎目录可成为编辑器执行目标；不改变项目类型、导入或持久数据。Cocos 编辑器操作继续使用内置插件，禁止回退到项目 `extensions/`、`package.json` 插件或第三方 MCP。
+- 验收口径：分别取得宿主/内置开关、工具目录、前端启动投影与真实目标拒绝证据；真实编辑器、安装包和 CI 与定向测试分层报告。

 ## 2026-09-14 DirectProject Codex 取消路径白名单并启用完整 sandbox

@@ -8984,3 +8986,13 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
 - 决策：`pick_local_project_directory` 增加可选 `title`（限 24 字符、无控制字符，其余回退默认标题），使「选择项目创建目录」不再冒用「选择游戏项目目录」文案。
 - 关联规范：`docs/project-memory/plans/【实施计划】AGC项目创建目录可选-2026-09-17.md`、`docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`。
 - 验证：`cargo test --bin genarrative-ai-game-creator-shell creation_root`（2 项）、模板库定向单测 14 项、偏好模型 3 项、`appSurface` 472 项（含设置页「工作区」选择/恢复目录与「设置里选目录后建项带 `projectsRoot`」两条场景）、`tsc`、`check:encoding` 与 `check-doc-index` 通过。
+
+## 2026-09-20 Rust 工具链升到 1.98.1：仓库侧四处同步 + runner 镜像必须重建
+
+- 背景：macOS 27（CLT for Xcode 27.0）冷构建时 proc-macro dylib 被链接成畸形 Mach-O（`mis-aligned LINKEDIT string pool`），上游 rust-lang/rust#157750 已修复，而仓库锁的 stable `1.96.0` 仍复现（Issue #431）。
+- 决策：根 `rust-toolchain.toml` 的 channel 由 `1.96.0` 改为 `1.98.1`；`deploy/container/gitea-ci-job.Dockerfile` 的 Rust stage 由 `rust:1.96-bookworm@sha256:19817ead…` 换成 `rust:1.98-bookworm@sha256:93ce27a88655056a51dbdd8f5f2d7ddc071c7b0070fb288a37b5a285fc83971e`（按 registry 配置实测该 digest 的 `RUST_VERSION=1.98.1`，与 channel 逐字一致）。
+- 决策（版本标签）：镜像 tag / label 一并从 `20260807.1`、`2026.08.07.1` 升为 `20260920.1`、`2026.09.20.1`（同一次核对发现 Dockerfile 里有两处 `org.opencontainers.image.version`：一处 `2026.07.23.1`、一处 `2026.08.07.1`，后写的覆盖先写的，本次一并统一为 `2026.09.20.1`）（`scripts/gitea-ci-job-image.sh`、`deploy/container/gitea-ci-job.Dockerfile`），`deploy/container/README.md` 与开发运维文档同步 digest、Rust 版本和归档示例名。镜像内容变了却沿用旧 tag，排障和回滚都会认错版本。
+- 不变口径：镜像继续 `RUSTUP_AUTO_INSTALL=0`，job 现场不下载工具链；`scripts/check-gitea-ci-job-image.sh` 仍按 `rust-toolchain.toml` 的 channel 逐字校验镜像内工具链名，所以基础镜像的 `RUST_VERSION` 必须与 channel 完全相同。`std::os::windows::fs::MetadataExt::number_of_links`（rust-lang#63010）在 `1.98.1` 上实测仍未稳定，`#[cfg(windows)]` 侧继续使用自行声明 `ByHandleFileInformation` 的实现。
+- 新增护栏：`scripts/project-ci-workflow.test.ts` 增加一条一致性用例——Dockerfile 的 `ARG RUST_IMAGE` 版本段必须等于 `rust-toolchain.toml` 的 channel 主次版本、其 digest 必须同时出现在两份运维文档里、镜像 tag 日期戳必须与 Dockerfile 的 `org.opencontainers.image.version` 一致，避免本次这种「改了 Dockerfile 忘了文档」的漂移。
+- 待办（不在本次仓库改动内）：在 station 上执行 `build / verify / export / load-runner`，备份 runner config 后把 `genarrative-ci` 映射切到新 Image ID 并 `docker restart --timeout 660 gitea-runner`；内层只有 1.96 时 PR 的 job 必然失败。macOS 与 Windows AGC 构建机（`jenkins/Jenkinsfile.ai-game-creator-shell-build`，preflight 只校验 rustc/cargo 是否存在）需确认已装 `1.98.1`，macOS 冷构建是本次问题的原始验证目标。`deploy/container/api-server.Dockerfile` 的 `FROM rust:1.93-bookworm` 是另一处未加 digest 的 Rust 版本 pin，本次未动。
+- 验证：分支 `chore/rust-toolchain-1-98` / PR #432；`npx vitest run scripts/project-ci-workflow.test.ts`、`npm run check:encoding`、`git diff --check` 通过。Windows：`1.98.1` 下 `npm run agc:build -- --debug` 的前端构建、Rust 编译与 NSIS 安装包生成成功（见 PR 描述记录）；macOS 与镜像重建后的 CI 结果仍待验证。
@@ -20,46 +20,48 @@

 完整规则和模板见 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](../../【协作规范】规范驱动开发工作流-2026-09-12.md)。小型局部修改仍直接使用下方轻量流程；执行中若触及公开行为，立即升级到 SDD。

-任务开始时先写清一句话交付结果、验收判据和不做项，再按“必须项 / 风险项 / 可选项”排序。先完成修改、定向验证和边界检查组成的最小闭环；设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，否则记录为后续事项。不要让工具探测、历史整理或验证便利自行改变任务目标。
+任务开始时先写清一句话交付结果、验收判据和修改范围，再按“必须项 / 风险项 / 可选项”排序。先完成修改、定向验证和边界检查组成的最小闭环；设置时间盒和检查点，新增发现只有在影响交付判据时才扩大范围，其余记录为后续事项。

 ## 开始前

- worktree 复用 `node_modules` 时，测试与构建的 workspace alias 必须指向当前工作树源码，不能经依赖软链接读取另一工作树的共享包。遇到仅 worktree 出现的 JSX 编译错误时先核对解析路径，不用给组件补全局变量来掩盖错误来源。
+- worktree 复用 `node_modules` 时，测试与构建的 workspace alias 必须指向当前工作树源码。遇到仅 worktree 出现的 JSX 编译错误时先核对解析路径，修复错误的依赖解析。

 - 运行 `git status --short`，保留用户已有的未提交修改；不要在共享工作树中使用破坏性 Git 命令。
 - 复杂任务先读 `AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`、`docs/README.md` 和对应专题。
 - 需要完整 SDD 的任务先确认主规范位置和验收证据，再创建 `docs/project-memory/plans/` 下的里程碑规范与实现计划；计划完成、取消或合并后删除。
- 后端事实以 `server-rs/crates/api-server/src/app.rs`、`server-rs/crates/api-server/src/modules.rs`、Cargo manifest、SpacetimeDB schema 和源码为准；现役 API 不从未挂载模块推导。
+- 后端事实以 `server-rs/crates/api-server/src/app.rs`、`server-rs/crates/api-server/src/modules.rs`、Cargo manifest、SpacetimeDB schema 和源码为准；现役 API 按实际挂载路由核对。
 - External v1 以 `docs/openapi/genarrative-external-v1.openapi.json` 与 `modules/external_api.rs` 为准。
 - 本地端口的默认值只用于启动配置；实际运行端口以 `.app/dev-stack.json` 和启动日志为准。
- 任务涉及 SpacetimeDB schema 时，先读 `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 与现有 schema 检查脚本，不依赖仓库中已不存在的旧表目录或基线文件。
+- 任务涉及 SpacetimeDB schema 时，先读 `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` 与现有 schema 检查脚本。

 ## 修改边界

 - 后端路线固定为 `server-rs + Axum + SpacetimeDB`，访问 SpacetimeDB 统一经 `spacetime-client` facade。
 - `module-*` 放领域规则，`spacetime-module` 放表和事务，`api-server` 放 HTTP/SSE/BFF，`platform-*` 放外部副作用，`shared-contracts` 放 DTO 与公开契约。
- 前端不承接正式业务真相；页面状态必须来自后端投影、API 或持久化合同。
- 旧模板、旧公开作品、旧运行态、旧 Node/Express/PostgreSQL/Go/maincloud 路线和人工 `spacetime --root-dir` 命令不作为新实现目标。
- 已退役对象没有现役 caller、公开契约、持久化迁移或活跃实例时，不添加兼容代码、兼容测试、墓碑注释或墓碑文档。
- 修改中文文件优先局部补丁，保持 UTF-8；不把中文文案替换成英文。
+- 前端负责表现与交互；页面正式状态来自后端投影、API 或持久化合同。
+- 本地 SpacetimeDB 数据隔离使用项目脚本或 `--data-dir`，发布目标显式传 `--server` / `--server-url`。
+- 已退役对象没有现役 caller、公开契约、持久化数据、活跃实例或迁移要求时，清理实现、专属测试和说明，权威文档保持当前状态；公开契约、持久化数据和正式迁移按实际需求保留最小兼容及对应测试。
+- 修改中文文件优先局部补丁，保持中文与 UTF-8。

 ## 文档维护

 - 当前稳定合同进入 `docs/`；长期决策、通用流程、排障经验进入 `shared-memory/`。
 - 文档现行、历史、待复核、开放事项和活动计划的分类以 [`docs/【协作规范】文档生命周期与现状索引-2026-09-12.md`](../../【协作规范】文档生命周期与现状索引-2026-09-12.md) 为准；`historical` 和 `review` 文件开头保留状态头，不能直接作为实现依据。
 - `plans/` 只保存正在执行且有明确下一门禁的计划；`todos/` 只保存真实开放且有关闭条件的事项。完成或作废后删除或融合。
- 不把分支名、一次性测试轮次、提交流水账和个人路径写成长期规则。
+- 长期规则记录可复用的当前合同与验证方法，执行历史由 Git 保存。
 - H5 HostBridge 真实调用链的临时替身词扫描必须覆盖生产调用链；宿主壳真实能力以现行 HostBridge 协议与代码为准。

 ## 验证路由

+提示词外置变更运行 `runtime_prompt_bundle_build` 与 `prompt_source_boundaries` 两个 Rust 集成测试，验证编译期文本、目录登记和源码边界；现有 `agc-rust-shard-1` 本地/CI 入口先执行这组检查，再运行分片单测。
+
 AGC 运行时配置默认值调整时，同步核对 Rust 默认值、分发配置模板、设置弹窗默认草稿和 `runtime-settings.suite.ts` 的恢复默认断言；显式传入旧值的配置读取用例仍验证原值保留，不批量替换测试数据。

 AGC 测试构造单 HTML 项目时，必须在初始化之前写入 HTML，避免自动建立 npm 工程；npm 预览和导出测试应提供 dist 产物。已有图片生成 pending/operation 属于持久化恢复合同，修改工具默认参数后仍须验证旧动作恢复不重复提交、不因默认值变化被误判为新意图。

 SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.md`；该项目适配层按需调用已安装的官方 `spacetimedb` 插件 skill，插件提供通用 SDK/CLI/MCP 知识，项目 skill 负责 Genarrative 架构边界和验证门禁。

-按改动范围选择定向门禁，不以无关全量扫描代替契约验证：
+按改动范围选择定向门禁：

 | 范围                | 至少运行                                                                                                                           |
 | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
@@ -24,10 +24,10 @@
 AI 游戏创作 / DirectProject / UI workflow：

 1. `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`
-2. `docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md`
+2. `docs/technical/【技术方案】策划会话RuntimeV2接入与旧链路退役-2026-09-03.md`（历史方案，仅供追溯）
 3. `docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md`
 4. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`
-5. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`（仅存量旧链路）
+5. `docs/technical/【技术方案】立项策划Agent（Fast GDD）-2026-08-10.md`（历史 V1 方案，仅供追溯）
 2. `docs/technical/【技术方案】DirectProject Codex原始历史与异常恢复-2026-09-04.md`
 3. `docs/technical/【技术方案】DirectProject客户端Skill与MCP扩展导入方案-2026-08-31.md`
 4. `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`
@@ -1,5 +1,16 @@
 # 踩坑与排障记录

+## Rust 同步回调的测试记录按线程隔离
+
+- `shared-contracts` 的资源 kind reporter 是进程级回调。仅给注册和断言加锁，无法阻止其他并行 manifest 测试触发该回调，导致日志数量和内容断言偶发混入其他测试记录。
+- kind 解析与回调在调用线程同步执行，测试收集器使用线程局部存储，各用例开始时清空本线程记录；生产 reporter 保持不变。保留完整记录断言，并用两个线程分别解析和核对记录，验证隔离；不要通过全局串行测试或放宽断言掩盖干扰。
+
+## AGC 自动同步必须绑定真实项目生命周期
+
+- 正式客户端在单窗口中用 React 状态打开/切换工程，窗口 URL 不代表当前工程。原生后台同步应读取由当前窗口显式登记的活动工程；首次打开、离开、切换、关窗及退出等待分别验证，不能只用携带 `projectPath` 的独立测试窗口证明正式入口可用。
+- 增量文件没有变化不等于远端清单没有变化。项目名和完整性元数据也参与提交判据，避免临时跳过恢复后永久停留在 partial，或新出现超限文件后仍显示 ready。历史清单缺少完整性字段属于未知，不能默认成完整。
+- ZIP 导出按一次冻结清单恢复相对路径并逐文件核验；直接下载内容寻址的 OSS 目录不能得到可用工程。源码/素材归档不包含依赖缓存、凭据和 AGC 对话运行状态。
+
 ## 2026-09-19 资源 kind 词汇收敛后，前端判据与 fixture 必须一起按 canonical 成员重写

 - **现象**：工具栏入口的 `assetKind` 换成共享 `GameCreationAppAssetKind`（图集从平台词 `art-spritesheet` 改成 `icon-spritesheet`）后，「图集不接受用户参考」的判据仍写在旧的 `['art-spritesheet']` 字符串清单里，判据恒假：生成面板重新给图集渲染参考图选择器，原生提交再按合同显式拒绝多余参考。
@@ -354,7 +365,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 ## 2026-08-15 `#[cfg(windows)]` 里的代码不参与 Linux CI 编译，CI 绿不代表能构建

 - 现象：把 master（`9f5c84ee7`）合进 `feat/five_min_design` 后，`cargo check --all-targets` 在 Windows 上直接 `error[E0658]: use of unstable library feature 'windows_by_handle'`，位置是 `apps/ai-game-creator-shell/src-tauri/src/project/manifest.rs` 的 `metadata.number_of_links()`。该文件与 `origin/master` **逐字节相同**，即 master 自身在 Windows 上就构建不过。
- 原因：`std::os::windows::fs::MetadataExt::number_of_links` 至今未稳定（rust-lang#63010），而 `rust-toolchain.toml` 锁的是 stable `1.96.0`。引入它的提交是 `578f8019f`（优化 AGC 项目入口并识别 Godot 工作区），其中 unix 分支用 `MetadataExt::nlink()`（已稳定）、windows 分支用了未稳定的对应物。**Linux CI 上 `#[cfg(windows)]` 整块不参与编译，所以 CI 全绿。**
+- 原因：`std::os::windows::fs::MetadataExt::number_of_links` 至今未稳定（rust-lang#63010）；当时 `rust-toolchain.toml` 锁的 stable 是 `1.96.0`，2026-09-20 升到 `1.98.1` 后在同一台 Windows 机器上用该 stable 实测仍报 `error[E0658]: use of unstable library feature 'windows_by_handle'`（见 decision-log 同日条），因此本条的处置口径不变。引入它的提交是 `578f8019f`（优化 AGC 项目入口并识别 Godot 工作区），其中 unix 分支用 `MetadataExt::nlink()`（已稳定）、windows 分支用了未稳定的对应物。**Linux CI 上 `#[cfg(windows)]` 整块不参与编译，所以 CI 全绿。**
 - 更普遍的形状：只要一段代码只在某个 `#[cfg(target_os)]` 下编译，它就完全绕过了其它平台的 CI——不只是 unstable feature，还包括类型错误、借用错误、缺失 import。跨平台分支是「双写」，两侧都得有人真的编译过。
 - 处理：本仓库对「文件是不是无硬链接普通文件」统一自行声明 `ByHandleFileInformation` 并调用 `GetFileInformationByHandle`，见 `runner/endpoint.rs`、`tool_plan_handoff/storage_windows.rs`、`project/agent_db.rs`、`git_inspect.rs`、`image_inspect.rs`、`agent/generation/canvas_generation.rs`。`manifest.rs` 当前已采用同一实现，并保留 fail-closed 语义：无法取得句柄信息或确认存在硬链接时均拒绝，同时拒绝 directory / reparse point。
 - 验证：改后 `cargo check --offline --all-targets` 通过、`cargo fmt --check` 通过、`project::manifest` 与 godot 相关定向测试 65 passed / 0 failed。判断「是不是本次合并引入」的通用手法：`git diff origin/master -- <file>` 为空即说明该文件就是 master 原样，问题不在合并。
@@ -4624,7 +4635,7 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`

 - 现象：`Repository checks`、`Frontend tests`、`Backend tests` 和 `Native shell tests` 都从全新 job 容器开始，apt、setup-node、rustup 和原生系统库在不同 job 里重复安装；后端与原生壳的安装时间可达数分钟，并把软件源和代理瞬时失败放大为四份。
 - 原因：Gitea Actions job 彼此隔离，上一个 job 在容器内安装的包不会自动进入下一个 job；把同一套不随 PR 变化的工具链写在 workflow step 中，必然每次重做。
- 处理：用 `deploy/container/gitea-ci-job.Dockerfile` 预装 Node 22、固定 npm、Rust 1.96、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖，并按锁预热唯一根 npm workspace、server-rs、桌面壳与 AI 游戏创作壳 Cargo 四份下载缓存。四个 job 统一 `runs-on: genarrative-ci`，先用镜像内脚本直接从 Gitea checkout，再以 runtime 模式运行 `scripts/check-gitea-ci-job-image.sh`，同时检查四份缓存锁、工具链、完整 bwrap 与 Chrome headless。`RUSTUP_AUTO_INSTALL=0`；`rust-toolchain.toml` 变更时先重建镜像，不把下载 fallback 放回 job。
+- 处理：用 `deploy/container/gitea-ci-job.Dockerfile` 预装 Node 22、固定 npm、Rust 1.98.1、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖，并按锁预热唯一根 npm workspace、server-rs、桌面壳与 AI 游戏创作壳 Cargo 四份下载缓存。四个 job 统一 `runs-on: genarrative-ci`，先用镜像内脚本直接从 Gitea checkout，再以 runtime 模式运行 `scripts/check-gitea-ci-job-image.sh`，同时检查四份缓存锁、工具链、完整 bwrap 与 Chrome headless。`RUSTUP_AUTO_INSTALL=0`；`rust-toolchain.toml` 变更时先重建镜像，不把下载 fallback 放回 job。
 - 依赖边界：每个 job 仍必须各自执行 `npm ci`，让当前 lockfile 和 PR 依赖在干净环境中验证；区别是命中镜像 cache 时只做本地解包，锁新增依赖时才走受控网络。不要把 `node_modules` 或 Cargo `target` 烘进镜像，也不要向不受信任 PR 挂载跨 job 可写 cache。
 - 锁漂移边界：runtime 校验输出任一 `*_cache_lock=partial` 说明镜像内 lock 与当前 checkout 不同，不代表新增依赖已经缓存；必须同时输出 Actions warning，提示可信分支落地后刷新镜像。必须在新镜像中对 server-rs、桌面壳和 AI 游戏创作壳当前 lock 执行真实 `cargo fetch --locked --offline`；`cargo metadata --no-deps` 不会证明依赖 archive 可用，不能作为替代。
 - 构建网络边界：`CARGO_NET_RETRY` 只覆盖部分 crate 下载，registry `config.json` / index TLS 握手仍可能直接终止整次 fetch。Dockerfile 对每个 `cargo fetch --locked` 再做最多 5 次整命令级有界重试，最终仍执行断网 fetch，不能降低为无锁重试或省略离线闭合验证。
@@ -16,27 +16,33 @@

 ## 开发中

- AGC 思考与执行入口共用共享单行摘要骨架；Markdown 只在展开正文走既有安全渲染，折叠预览只取纯文本，不在 summary 嵌套链接或按钮。耗时统一复用中文时分秒格式（不足一分钟一位小数，达到分钟后整数秒），格式化与各层计时边界分离。过程行在运行中和完成后的折叠层内保持同一紧凑间距；失败状态按明确终态与非零退出码呈现红色，不由自然语言输出猜测。
+- AGC 主模型追溯保存在项目 `.agent/model-usage.jsonl`，请求目录标识与响应确认的型号分别记录；旧项目当前配置补录必须标注来源，不冒充历史事实。仅保存有界模型与回合身份字段，不保存配置、凭据或对话正文，不增加 UI 展示。详见 AGC 实施计划“项目主模型使用记录”。
+
+- Agent 提示词正文与工具说明放在所属组件的 `prompts/`；AGC 通过现有 Prompt Bundle 编译加载，服务端独立 crate 编译包含自己的提示词文件。代码负责变量填充、结构化 schema 与执行校验。
+
+- AGC 思考与执行入口共用共享单行摘要骨架；Markdown 在展开正文走既有安全渲染，折叠预览使用纯文本。耗时统一复用中文时分秒格式（不足一分钟一位小数，达到分钟后整数秒），格式化与各层计时边界分离。过程行在运行中和完成后的折叠层内保持同一紧凑间距；失败状态按明确终态与非零退出码呈现红色。

 - Direct 对话计时区分条目展示时间与生命周期事件时间：整轮用用户发送到明确终态的跨度，工具用各自开始/完成边界；运行时用 100ms 叶子时钟刷新一位小数，终态冻结，旧历史缺边界不推测。不得用整秒时间的大小比较取代 Thread Manager 的事件顺序判定新回合。

 - AGC 批量追加素材标签由原生在一次项目写锁与 revision CAS 下合并各项原标签，先校验全批再写 manifest；前端不能循环单素材分类命令，不回传展示层推导的分类或旧标签全集，以免部分写入或覆盖未编辑字段。

- AGC 平台服务固定为 `https://dev.genarrative.world`，会话凭据按 origin 隔离。官网通过同源公开 `/api/client-downloads` 汇总 Windows/Mac 渠道的首装 `downloads`，按真实平台/架构显示；未发布隐藏，单渠道失败不影响其它下载。发布先上传 EXE/DMG 再写本渠道清单，不维护会互相覆盖的共享 OSS 索引。主站 Vite 代理复用实际 `runtimeServerTarget`，浏览器不直接跨域读取 OSS 清单。完整约定见 AGC 客户端更新检查与下载专题。
+- AGC 平台服务固定为 `https://dev.genarrative.world`，会话凭据按 origin 隔离。发布渠道为 `dev/release/自定义名称`，Windows/Mac 是系统，OSS 的 `<channel>-win/mac` 仅是延续既有地址的分区。官网通过服务端 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`（默认 dev）选择渠道，公开同源 `/api/client-downloads` 汇总其各系统首装包与真实版本；未发布隐藏，单系统失败不影响其它下载，不跨渠道补齐。发布先上传 EXE/DMG 再写对应分区清单，不维护会互相覆盖的共享 OSS 索引。主站 Vite 代理复用实际 `runtimeServerTarget`。完整约定见 AGC 客户端更新检查与下载专题。
+- AGC 模板库灰度复用 `agc:template-library`：未配置关闭，已配置时遵循现有灰度启停、用户 ID/标签和比例规则；服务端返回权威结论，客户端入口和原生清单/下载/建项均执行门禁，主体切换丢弃旧异步结果。公开 OSS 不是保密边界，已创建项目不受影响。

 - 画布卡片类型与信息角标共用 `CanvasCardCornerActions`；菜单收纳共用 `OverflowActions`，宿主决定展示数量和资源命令。AGC 选中菜单前 5 项直显，Web 默认不折叠；浮层 portal 继续接入现有画布关闭与滚轮归属判据。
- 修改范围保持聚焦；优先扩展现有系统、页面、组件、DTO 和脚本，不新建平行入口或业务真相。
- UI 开发优先复用现有公共组件；跨页面或跨端重复的视觉/交互模式应沉淀到 `packages/shared`，由现有页面迁移使用，禁止在业务页复制同类 UI。共享组件只承载通用表现与交互，不下沉领域规则、后端副作用或正式业务状态。
- AGC 当前 Agent 与策划 Agent 的消息层级共用 `packages/shared` 的 `AgentMessageContent`：正文使用 `body`，思考、中间输出与工具调用使用 `process`；宿主不按 Agent 类型重新定义过程字号和颜色，错误状态保留语义色。
+- 修改范围保持聚焦；优先扩展现有系统、页面、组件、DTO 和脚本。
+- Agent 可见内容直接描述当前任务、输入和成功条件，细节按调用需要提供。
+- UI 开发优先复用现有公共组件；跨页面或跨端重复的视觉/交互模式应沉淀到 `packages/shared`，由现有页面迁移使用。共享组件承载通用表现与交互，领域规则、后端副作用和正式业务状态由后端负责。
+- AGC 当前 Agent 与策划 Agent 的消息层级共用 `packages/shared` 的 `AgentMessageContent`：正文使用 `body`，思考、中间输出与工具调用使用 `process`；过程字号和颜色由共享组件统一定义，错误状态保留语义色。
 - 后端遵循 `module-*`、`spacetime-module`、`spacetime-client`、`api-server`、`platform-*`、`shared-contracts` 的现役边界。
 - 前端只负责表现、交互和临时 UI 状态；正式状态来自后端投影、API 或持久化契约。
- 对已明确退役且无现役调用方、公开契约、持久化迁移或活跃实例的对象，不写兼容实现、维持旧行为的测试、墓碑注释或墓碑文档。
+- 对已明确退役且无现役调用方、公开契约、持久化数据、活跃实例或迁移要求的对象，直接清理实现、专属测试和说明，将权威文档更新为当前状态；历史由 Git 保存。公开契约、持久化数据和正式迁移按实际需求保留最小兼容及对应测试。
 - 修改 `/api/external/v1` 时，同批更新 `docs/openapi/genarrative-external-v1.openapi.json` 与契约测试。
 - 修改 SpacetimeDB schema 时遵守字段追加/default 约束，同步 migration、表目录、生成绑定，并运行 schema 检查；删除、改名、重排或改类型前先确认迁移计划。
 - 日志不递归输出完整配置、应用状态或 provider client；新增字段默认不进入安全摘要。
 - HTTP 横切能力集中在 Axum/Tower 中间件：正常与降级路由复用追踪层；指标与 trace 使用 `MatchedPath` 模板及固定兜底，不把请求 ID、实际资源 ID 或 query 放入指标标签。在途请求通过 RAII guard 覆盖 Future 取消与 panic unwind；请求执行和响应体存活分别计量，不能把 handler 耗时当作 SSE 全生命周期。
 - 业务依赖在组合根显式装配，Axum `FromRef` 只抽取可浅拷贝的窄能力。项目元数据与 External API 鉴权不持有完整 `AppState`，测试经相同接口注入替代依赖。集中鉴权仍保留方法级 fallback、公开入口、MCP 和 body limit 顺序；Provider span 跳过完整参数，不隐藏计费、重试、幂等或事务规则。
- 中文文案、注释和文档保持 UTF-8，优先局部补丁，不擅自翻译成英文。
+- 中文文案、注释和文档保持中文与 UTF-8，优先局部补丁。

 ## 文档生命周期

@@ -71,7 +71,7 @@ plugins/agc-cocos-editor/

 宿主按 `AGC_PLUGIN_WORKSPACE`、随包 `<resource_dir>/plugins`、开发构建仓库 `plugins/` 的顺序解析工作区；插件包内的 `native/payload` 由构建脚本随包映射，生成的 DLL 不入库。插件协议、权限和面板挂载全部复用通用宿主，Cocos 专属逻辑只存在于本插件包：进程名与 `--project` 解析、Creator 版本校验、named pipe 协议和 Windows 注入。

-该插件是**内置插件**：随客户端分发、不能卸载，只能通过 `set_agc_plugin_enabled` 控制是否可用。除开关和 feature 外，还必须满足“当前受控项目已识别为 Cocos Creator 项目”这一门禁；没有当前项目或项目类型不是 Cocos 时，插件不出现在插件列表、面板、Agent 工具目录或 MCP tools/list 中，启动、面板读取、RPC 和编辑器执行也会失败关闭。项目切换离开 Cocos 后，已运行实例立即停止。Cocos 编辑器操作统一优先通过该内置插件的 `cocos.editor.execute` / `cocos.editor.operation`（DirectProject 对应 `agc_cocos_execute`）；不得改走项目目录 `extensions/`、`package.json` 插件或第三方 MCP。开关状态保存在 AppData `extensions/builtin-plugins.json`，隔离 MCP 每次 tools/list 都向绑定宿主询问当前状态与项目门禁。
+该插件是**内置插件**：随客户端分发、不能卸载，只能通过 `set_agc_plugin_enabled` 控制是否可用。插件列表、启动、面板读取、插件 RPC、Agent 工具目录和 MCP tools/list 不按当前工程类型过滤；无当前项目或非 Cocos 项目仍沿用相同的开关、原生适配器、平台和 feature 规则。项目切换不因工程类型不同而停止插件，仍更新受控项目上下文并失效旧连接。实际编辑器操作必须取得当前受控项目对应的真实 Creator 目标并通过原有目录、PID、版本与握手校验；无项目或非引擎目录不能仅凭工具可见就通过执行校验。Cocos 编辑器操作统一优先通过该内置插件的 `cocos.editor.execute` / `cocos.editor.operation`（DirectProject 对应 `agc_cocos_execute`）；不得改走项目目录 `extensions/`、`package.json` 插件或第三方 MCP。开关状态保存在 AppData `extensions/builtin-plugins.json`，隔离 MCP 每次 tools/list 都向绑定宿主询问当前可用状态，不自行按工程类型过滤。

 ## AGC 项目打开入口

@@ -3,7 +3,7 @@
 > 文档状态：`current`
 > 规范关系：承接 AGC 通用插件宿主与编辑器适配主规范

-更新时间：`2026-09-18`
+更新时间：`2026-09-20`

 ## 目标与非目标

@@ -18,7 +18,7 @@
 ## 入口与行为合同

 - Unity 项目以当前受控根目录中的普通 `ProjectSettings/ProjectVersion.txt`、`Assets/` 和 `Packages/` 识别；复用现有打开项目入口，不创建平行工作台。
- 只有当前项目为 Unity、内置插件启用且平台适配器可用时才显示插件并向 Agent 暴露 Unity 工具。禁用或离开 Unity 项目后停止插件实例，执行入口再次检查开关和项目身份。
+- 插件列表、启动、面板、插件 RPC 和 Agent 工具暴露不按当前工程类型过滤；无项目或非 Unity 项目也沿用相同的内置开关及平台适配器规则。禁用会停止插件实例，跨工程类型切换保留插件管理能力并失效旧连接。前端按宿主列表中各插件自身状态投影自动启动，不因项目类型在 Cocos/Unity 之间二选一，也不自动展开面板。执行入口继续检查开关、权限和真实项目身份；工具可见不代表任意目录可作为 Unity 执行目标。
 - 探测只读取进程和项目身份。连接必须匹配规范化项目路径、PID、进程启动身份与实际握手；多个候选时失败，不选择任意实例。助手只接受受控项目、操作和代码，不接受任意可执行文件或 payload 路径。
 - 执行接收 UTF-8 C# 代码，最多 128 KiB，拒绝空值和 NUL。连接及执行有总期限，消息最多 2 MiB，并发执行直接拒绝，不积压写请求。
 - 成功仅由 Unity 真实执行回执决定；编译或运行错误返回结构化失败与脱敏诊断。主线程同步代码不承诺可硬中止。
@@ -51,7 +51,7 @@ helper 使用一行一条 JSON 请求/响应，请求包含 `id`、`method`、`p
 | 条款 | 必须取得的证据 |
 | --- | --- |
 | 来源与构建 | 固定源码版本、许可、helper 构建和自包含发布检查 |
-| 插件接入 | manifest/协议测试，发现、启停、开关和项目级工具过滤测试 |
+| 插件接入 | manifest/协议测试，发现、启停、开关、无项目/跨工程类型的工具暴露和前端启动投影测试 |
 | 执行闭环 | helper 与原生适配器定向测试，Agent 参数及结果映射测试 |
 | 失败边界 | 跨项目、并发、超时、损坏回执、不确定阻断、重启插件不解除阻断测试 |
 | 分发 | Windows 构建脚本准备 helper，staging 仅包含目标平台运行文件及许可 |
@@ -1,13 +1,21 @@
 # AGC 客户端更新检查与下载

-更新时间：`2026-09-19`
+更新时间：`2026-09-20`

 本文件是 AGC 客户端自动更新的主规范：更新能力由 Tauri 官方插件 `tauri-plugin-updater` 承担，并按下文渠道分发。

 ## 目标

 - 客户端自动更新改用 Tauri 官方 `tauri-plugin-updater`：清单请求、版本比较、更新包下载、签名校验、安装与退出全部在原生侧完成；前端只负责触发、展示和渠道选择。
- 更新按渠道分发。当前渠道集合为 `dev-win`（Windows x64）与 `dev-mac`（macOS）；构建管线按渠道产出并上传清单，客户端只读取自己渠道的清单。
+- 更新按渠道分发。渠道为 `dev`、`release` 或自定义名称；Windows/macOS 是独立的系统维度，每个渠道分别维护各系统已发布的版本、清单和安装包。客户端只读取构建时确定的渠道及系统对应的清单。
+
+## 渠道与网站配置合同
+
+- 构建参数 `AGC_UPDATE_CHANNEL` 默认 `dev`，支持 `release` 和自定义小写名称；名称符合 `[a-z][a-z0-9-]{0,31}`，不能以连字符结尾，不能为 `win/mac/windows/macos/darwin/linux` 或以 `-win/-mac` 结尾。构建目标独立决定系统和架构。
+- 为延续已发布客户端地址，OSS 继续使用 `agc/<channel>-win/` 和 `agc/<channel>-mac/` 作为物理分区；`dev-win/dev-mac` 是分区键，不是可填写的渠道。每个分区独立维护 `latest.json` 与版本目录，发布 release 不覆盖 dev。旧 `agc/latest.json` 迁移桥与其版本高水位仅属于 dev 的 Windows 分区。
+- 网站由服务端配置 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL` 选择检测渠道，默认 `dev`；更改后重启 API 服务生效。`GET /api/client-downloads` 返回该渠道 Windows/macOS 的真实已发布版本。请求参数不能覆盖配置或指定 URL；配置非法时失败关闭，不悄悄改读 dev。
+- 同一渠道中不同系统仍可具有不同 release 版本；未发布的系统隐藏，单系统失败不影响另一系统。不会从其他渠道补齐缺失版本。
+- 验收必须覆盖 dev/release/自定义渠道各自端点和对象地址、独立版本、非法名称、旧 dev 地址延续、release 不写旧迁移桥、网站配置贯通、跨渠道链接拒绝和部分失败。
 - 更新链路的信任来源从「清单里的 sha256 + 受信域名」升级为「发布签名 + 受信域名」：清单里的 `signature` 由构建期私钥生成，客户端用内置公钥校验，校验不过就拒绝安装。

 ## 非目标
@@ -33,11 +41,11 @@
 ### 官网下载与客户端服务地址

 - 官网首页提供无需登录的「下载客户端」入口，桌面和移动视口均可访问；入口打开独立下载面板，复用平台按钮、弹窗和状态组件。
- 每次打开下载面板请求同源公开 `GET /api/client-downloads`，后端并行读取固定 `dev-win/latest.json` 与 `dev-mac/latest.json` 并汇总已发布平台，网页和接口均禁用缓存。平台列表与每项版本完全来自清单；不在网页写死版本或猜测文件名。
+- 每次打开下载面板请求同源公开 `GET /api/client-downloads`，后端并行读取配置渠道的 `<channel>-win/latest.json` 与 `<channel>-mac/latest.json` 并汇总已发布平台，网页和接口均禁用缓存。平台列表与每项版本完全来自清单；不在网页写死版本或猜测文件名。
 - 接口返回 `{ downloads: [{ platform, architecture, version, downloadUrl }], unavailablePlatforms: [] }`，平台为 `windows` / `macos`，架构为 `x86_64` / `aarch64`；Windows 仅支持 x86_64，Mac 按清单实际提供的架构展示 Apple Silicon / Intel 下载项。DTO 由 `shared-contracts` 与 `packages/shared` 对齐，不接受请求参数指定上游 URL，不触及 SpacetimeDB。
 - 渠道清单新增可选 `downloads` 字典，键与 updater 平台键一致，值为 `{ url }`，只登记首装包。Windows `.exe` 可同时用于首装和更新；macOS 首装必须为 `.dmg`，不得将 `.app.tar.gz` 当首装包。已发布且没有 `downloads` 字段的 Windows 清单可读取既有 `platforms.windows-x86_64.url`；Mac 没有首装元数据时隐藏，不推导 DMG 地址。
 - 渠道 404 视为尚未发布并隐藏该平台；两端均未发布时显示空状态。单渠道请求失败、超时或格式非法时保留另一端有效下载项，同时提示部分平台暂不可用并允许重试；没有任何有效项且存在失败时返回可读 502。关闭面板取消请求，迟到响应不能覆盖下一次打开的状态。
- 每个上游请求总超时 10 秒、响应体上限 128 KiB、不跟随重定向、不附加用户凭据；返回的链接仅接受固定 OSS 来源、对应 `/agc/<channel>/<version>/` 下的 HTTPS `.exe` / `.dmg` 对象，架构键必须属于该渠道。不提供陈旧、未知来源或版本不匹配的下载地址，不泄露上游正文。
+- 每个上游请求总超时 10 秒、响应体上限 128 KiB、不跟随重定向、不附加用户凭据；返回的链接仅接受固定 OSS 来源、对应 `/agc/<channel>-win|mac/<version>/` 分区下的 HTTPS `.exe` / `.dmg` 对象，架构键必须属于对应系统。不提供陈旧、未知来源或版本不匹配的下载地址，不泄露上游正文。
 - AGC 开发态和正式包的平台服务地址统一固定为 `https://dev.genarrative.world`；登录页不提供服务器选择或自定义地址。旧的服务器偏好不能覆盖固定地址；已有会话仍按 origin 隔离，不能将其他服务的凭据迁往 dev。自定义 LLM 配置不属于平台服务器选择。
 - access token 与 origin 一起保存；已有 dev origin 的 token 保留。没有 origin 的旧 token 一律清除，因为旧版可以单独修改服务器偏好，偏好不能证明 token 来源。随后仅使用 dev 自己的 refresh cookie 恢复或重新登录；原生会话回写同样绑定 dev origin。
 - 验收覆盖固定 dev 的登录/会话与请求行为、旧服务器偏好、首页入口挂载、动态最新版本链接、清单失败与重试、关闭取消、桌面和移动布局，以及公开清单和安装包的真实可读性。
@@ -47,7 +55,7 @@
 - 正式包启动时检查一次渠道清单；仅当清单版本高于当前版本时显示更新提示，提示包含目标版本与发布说明。
 - 用户确认后下载更新包：下载期间显示进度与已下载字节数；下载完成后按平台安装。
 - Windows 使用静默安装模式（NSIS `quiet`），安装启动成功后客户端退出并由安装程序重启新版本；macOS 由客户端在安装完成后重启进程接管新版本。
- 渠道在构建期确定并烘焙进产物：`dev-win` 产物只读 `dev-win` 清单，`dev-mac` 产物只读 `dev-mac` 清单，同一份二进制不会在运行期跨渠道切换。
+- 渠道与系统在构建期确定并烘焙进产物：如 dev 的 Windows 产物只读 `dev-win` 分区，release 的 Mac 产物只读 `release-mac` 分区，同一份二进制不会在运行期跨渠道切换。
 - 开发态（`npm run agc` / `agc:serve` 由 Vite dev server 提供前端）不检查更新、不显示更新入口，也不下载任何更新包。

 ### 失败、重试与幂等
@@ -85,19 +93,19 @@
 }
 ```

- 渠道与平台映射：
+- 渠道与平台分区映射（`<channel>` 为 dev、release 或自定义名称）：

-| 渠道      | 构建目标                 | 清单平台键                                     | 更新包                   | 清单地址                             |
+| 系统      | 构建目标                 | 清单平台键                                     | 更新包                   | 清单地址                             |
 | --------- | ------------------------ | ---------------------------------------------- | ------------------------ | ------------------------------------ |
-| `dev-win` | `x86_64-pc-windows-msvc` | `windows-x86_64`                               | NSIS `.exe` + `.exe.sig` | `<OSS base>/agc/dev-win/latest.json` |
-| `dev-mac` | `universal-apple-darwin` | `darwin-aarch64` + `darwin-x86_64`（同一对象） | `*.app.tar.gz` + `.sig` | `<OSS base>/agc/dev-mac/latest.json` |
+| Windows | `x86_64-pc-windows-msvc` | `windows-x86_64`                               | NSIS `.exe` + `.exe.sig` | `<OSS base>/agc/<channel>-win/latest.json` |
+| macOS | `universal-apple-darwin` | `darwin-aarch64` + `darwin-x86_64`（同一对象） | `*.app.tar.gz` + `.sig` | `<OSS base>/agc/<channel>-mac/latest.json` |

- 对象布局：清单固定写成 `agc/<channel>/latest.json`；安装包与签名写成 `agc/<channel>/<version>/<file>` 与 `<file>.sig`。
- macOS 正式交付使用 universal 主程序，同时携带分目录的 arm64/x64 原生 Codex 组件；每个组件保持上游单架构布局与独立 SHA-256 清单，运行中的主程序切片只选择同架构目录。不得把两套原生包的元数据或辅助程序混装。
- universal 更新包的两个平台键指向同一个 `.app.tar.gz` 和签名。单架构构建仅登记本架构供诊断，不轮流覆盖 dev-mac 正式清单；正式双架构发布必须构建 universal。
+- 对象布局：清单固定写成 `agc/<channel>-win|mac/latest.json`；安装包与签名写成同一分区的 `<version>/<file>` 与 `<file>.sig`。
+- macOS 正式交付使用 universal 主程序：两个平台键指向同一个 `.app.tar.gz` 与签名，一份产物同时服务 Apple Silicon 与 Intel。单架构目标（`aarch64-apple-darwin` / `x86_64-apple-darwin`）只用于本机诊断，不登记正式分区清单——单架构构建不可轮流覆盖同一个 `latest.json` 并宣称双架构均可更新。
+- universal 主程序同时携带分目录的 arm64/x64 原生 Codex 组件：每个组件保持上游单架构布局与独立 SHA-256 清单，运行中的主程序切片只选择同架构目录，不得把两套原生包的元数据或辅助程序混装。
 - 构建期要求：打开 `bundle.createUpdaterArtifacts` 以生成 `.sig`；构建环境提供签名私钥与密码（私钥内容不得入库）；公钥写入客户端配置。公钥在首个带更新能力的版本发布后不可更换，更换等于放弃自动更新（只能手动重装）。
- 版本递增按渠道独立进行：发布脚本读取该渠道远端 `latest.json` 的 `version`，与本地版本取较高者递增 patch；两个渠道的版本号互不影响。
- 版本高水位：发布脚本取「渠道清单版本」与「旧协议迁移指针版本」（迁移窗口内）中的较大值再递增。只看渠道清单会在渠道启用初期把版本链改小 —— 2026-09-17 首次渠道发布即把旧指针的 0.1.57 退回 0.1.48，随后以显式 0.1.60 纠偏；迁移窗口结束（旧指针 404）后自动只剩渠道清单，`dev-mac` 不参与旧指针比较。
+- 版本递增按渠道及系统分区独立进行：发布脚本读取该分区远端 `latest.json` 的 `version`，与本地版本取较高者递增 patch；不同分区的远端版本互不影响。
+- 版本高水位：仅 dev 的 Windows 分区在迁移窗口内取「分区清单版本」与「旧协议迁移指针版本」较大值再递增，避免已发布旧客户端版本倒退。迁移窗口结束（旧指针 404）后只读分区清单；release、自定义渠道与所有 Mac 分区均不参与旧指针比较。
 - 迁移（旧协议 → 渠道清单）：
  - 迁移起点：已发布客户端（含当前线上版本）内置自研清单地址 `agc/latest.json`（sha256 格式），下载与安装由自研 Rust 命令完成。
  - 迁移策略见「未决问题与决策」。迁移完成后，自研清单解析、下载命令、下载进度事件以及为此放行的 CSP / HTTP 白名单条目按「四不写」整条删除，不留兼容分支与墓碑说明。
@@ -106,17 +114,19 @@

 - 发布入口：`npm run ai-game-creator-shell:release:upload`（构建 + 按渠道上传）；仅构建不发布的 smoke 使用 `--no-bundle` 分支，不读远端版本、不改版本、不生成清单。
 - 发布入口只解析一次目标，优先级为 CLI `--target value` / `--target=value` / `-t value`、`AGC_BUILD_TARGET`、Windows 默认值；重复/空目标与不支持目标失败关闭。版本高水位、构建 feature/渠道端点、bundle 路径、产物后缀、清单平台键及摘要必须消费同一个发布上下文，不能分别回读默认目标。
- 渠道由构建参数显式指定，并按目标平台校验：Windows 目标只允许 `dev-win`，macOS 目标只允许 `dev-mac`；未显式指定时按目标平台取默认渠道。
+- 渠道由 `AGC_UPDATE_CHANNEL` 显式指定，默认 dev；Windows 与 macOS 目标均支持 dev、release 和自定义渠道，目标校验独立进行。
 - 定时调度只在本轮到达的提交包含 AGC 相关路径（客户端、共享包、`server-rs/crates`、AGC 插件、桌面壳图标、根依赖清单）时才触发渠道发布；纯文档或流水线自身的提交只跑 Full Build，不推高客户端版本号。判定失败或勾选强制触发时按"需要发布"处理。
 - 更新摘要自动生成：发布脚本用渠道清单里的 `commit` 字段（上一次发布的提交）到本次提交之间、且只覆盖客户端相关路径的提交列表生成 `notes`（每条 `- 提交标题（短 SHA）`，最多 12 条、主题 80 字、整体 900 字，超出折叠或截断），同时写入旧协议清单的 `releaseNotes` 和归档文件 `release-notes.txt`。`AGC_UPDATE_RELEASE_NOTES` 非空时以手动文案为准；无法判定起点（缺少上次 `commit` 或本地没有该提交）时不写摘要。清单缺少 `commit` 时回退用上一次成功构建的 `COMMIT_HASH`（CI 通过 `AGC_UPDATE_PREVIOUS_COMMIT` 传入）作为锚点，因此首次启用摘要或更换渠道后也能立即产出摘要。锚点仍不可得（清单读取失败或没有 CI 锚点）时降级为「最近客户端改动」列表并注明可能与上一版重复 —— 摘要属于附注，任何情况下都不允许因为它让发布失败。
 - 清单里的 `commit` 是非标准字段：更新插件忽略未知字段，发布脚本用它定位下一次摘要的起点。
- 上传：安装包与 `.sig` 上传到 `agc/<channel>/<version>/`，清单以 `--force` 覆盖上传到 `agc/<channel>/latest.json`，保证 latest 指针与清单内 URL 指向已存在的对象。
+- 上传：安装包与 `.sig` 上传到 `agc/<channel>-win|mac/<version>/`，清单以 `--force` 覆盖上传到对应分区的 `latest.json`，保证 latest 指针与清单内 URL 指向已存在的对象。
 - 首装发布：发布脚本生成 `downloads`，Windows 复用已选 NSIS `.exe`，Mac 选择本次版本和目标架构匹配的非空 `.dmg`；缺失、歧义或版本/架构不匹配时失败，不发布带悬空地址的清单。上传顺序为更新包、签名及首装包全部成功后再更新渠道清单，Windows 相同对象只上传一次。`dry-run` 不写 OSS。各渠道独立写自己的清单，由 BFF 汇总，Windows 与 Mac 发布不会覆盖彼此的下载项；Mac 跨架构合并仍遵循现有单架构发布约束。
 - Jenkins 流水线需要新增渠道参数与签名凭据；签名私钥与密码只以受保护凭据注入当前进程，不写入 workspace、日志或归档产物。
 - 归档证据：安装包、`.sig`、渠道清单与源码 commit。

 ## 验收标准与证据

+渠道与系统分离的定向验证覆盖发布脚本、上传计划、网站配置贯通及跨渠道链接拒绝：`build-release.test.mjs`、`release-oss.test.mjs`、`platform-oss client_downloads` 和 `api-server client_download`。本地隔离数据库的 API smoke 验证 `/healthz` 成功、配置 release 时仅读取 release 分区、查询参数不能覆盖渠道、未发布版本返回空列表且 `no-store`；这不代表已构建或上传 release 安装包。真实 Windows/macOS 安装、签名和更新仍由发布验收单独执行。
+
 官网下载与固定服务地址已于 `2026-09-19` 完成源码验收：

 | 条款 | 验收方式 | 结果 |
@@ -161,11 +171,11 @@
 - macOS 采用 universal 包，两个平台键对应同一更新产物；主程序用 lipo 检查两种架构，Codex 资源分别做原生身份/摘要与启动验证。Rosetta 结果不代替 Intel 真机验收。
 - 旧客户端迁移桥：保留一个版本周期。渠道清单上线后，发布管线同时把旧的 `agc/latest.json`（sha256 格式）指向 `dev-win` 最新安装包，让已发布客户端自动升级到新协议；下个周期整条删除。
 - 签名密钥：由本仓库维护者生成并保管，私钥保存在仓库外（`%USERPROFILE%\.tauri\genarrative-agc-updater.key`），只有公钥进入客户端配置；Jenkins 用受保护凭据 `AgcUpdaterSigningKey` 与 `AgcUpdaterSigningKeyPassword` 注入为 Tauri 打包器读取的 `TAURI_SIGNING_PRIVATE_KEY` 与 `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，本机可用 `TAURI_SIGNING_PRIVATE_KEY_PATH` 指向同一私钥。当前密钥不带密码；首次发布前仍可重新生成，首次发布后不可更换。
- macOS 发布方式：已接入专用 macOS Jenkins 节点（label `genarrative-agc-macos`，EXCLUSIVE 单 executor），由 `Jenkinsfile.ai-game-creator-shell-macos-build` 执行 `scripts/build-macos-ci.mjs` 完成 universal 构建、双架构隔离 smoke、universal DMG、渠道清单生成、更新包验签与 OSS 上传。`AGC_RELEASE_DRY_RUN` 默认为开，只有显式关闭才会写入 OSS。
+- macOS 发布方式：已接入专用 macOS Jenkins 节点（label `genarrative-agc-macos`，EXCLUSIVE 单 executor），由 `Jenkinsfile.ai-game-creator-shell-macos-build` 执行 `scripts/build-macos-ci.mjs` 完成 universal 构建、双架构隔离 smoke、universal DMG、分区清单生成、更新包验签与 OSS 上传。`AGC_RELEASE_DRY_RUN` 默认为开，只有显式关闭才会写入 OSS。
 - macOS 代码签名与公证暂缺：产物为未签名 + 未公证，`--no-sign` 保留，构建清单与 `latest.json` 显式记录 `appleSigned=false` / `notarized=false`，首装需用户在 Gatekeeper 中手动放行。该限制作为已知未验证项记录，不静默通过；「安装 → 重启接管新版本」的自动更新闭环仍需实机验收。
 - 更新包验签门禁：构建完成、上传 OSS 之前，用产物内烘焙的 `plugins.updater.pubkey` 复核 `<更新包>.sig`（Tauri 使用 minisign 的 `ED` 预哈希模式）。keyId 不一致或校验失败立即失败关闭，禁止上传——客户端校验失败会直接拒绝安装，且公钥发布后不可更换。

 待办：

- macOS `dev-mac` 渠道已落地构建与发布能力：Mac Jenkins 节点、release 入口（更新包 + 签名 + 首装包 + 渠道清单）、验签门禁与 dry-run 默认开启均已就绪。
+- macOS 分区（`<channel>-mac`）已落地构建与发布能力：Mac Jenkins 节点、release 入口（更新包 + 签名 + 首装包 + 分区清单）、验签门禁与 dry-run 默认开启均已就绪。
 - 剩余待办：Apple 代码签名与公证凭据（未就绪期间以未验证项记录）、macOS 安装后重启接管新版本的实机验证、Intel 真机 smoke（当前 x86_64 侧为 Rosetta）。
@@ -8,6 +8,17 @@ AGC 客户端接入公共 OSS 上的**游戏模板库**（真·游戏模板，
 - 客户端侧：Rust `template_library` 模块（读清单、下载、安装、建项目）+ 模板库全屏页 + 首页模板推荐 + 左侧导航入口。
 - 不在本次范围：模板制作工具、模板审核、模板计费、增量更新、已建项目的模板回填。

+## 模板库灰度访问
+
+- 后台现有灰度发布页登记 `agc:template-library`，控制整个模板库；复用用户 ID 白名单、用户标签、拒绝名单和稳定用户分桶比例，不新增数据库表或字段。未配置此 Gate 时默认关闭；已配置且停用灰度时遵循现有语义全量开放，启用灰度时拒绝名单优先于白名单及比例。
+- `/api/runtime/frontend-config` 增加 `agcTemplateLibraryEnabled`，按认证主体返回服务端权威结论。客户端尚未得到结果、匿名或请求失败时关闭入口；权限结果不作为离线缓存。
+- 登录、主体变化、窗口重新获得焦点和每次模板操作时刷新权限，不承诺后台修改的实时推送。未获准时首页模板推荐和左侧模板库导航隐藏，不读取 OSS 清单；已在模板页检测到失去权限时回到首页。原生命令明确拒绝或权限检查失败后同样清空并关闭入口。账号切换或退出后立即清空前一主体的清单、操作状态和可见性，旧异步响应不能恢复权限或导航。
+- 原生清单读取、下载和模板建项命令均独立核对当前平台会话及服务端权限，不能依靠前端隐藏；远端等待后的会话变化必须拒绝，安装和建项写入使用当前会话身份保护。已缓存清单和已安装模板不能绕过权限。
+- 此灰度控制当前客户端的产品功能，不承诺公开 OSS 模板内容的保密性，也不限制已创建项目的正常打开和编辑。旧客户端升级后才接入此控制。
+- 验收覆盖缺省关闭、明确全量、允许/拒绝名单、标签和比例、请求失败、缓存绕过、原生命令阻断、首页/导航/模板页以及账号切换竞态。
+- 验证入口：后台灰度页面测试、`useTemplateLibrary.test.tsx`、AppSurface 实际挂载的 template 用例、原生 `template_library` 测试和后端 `frontend_runtime_config` 测试。退出开始使用既有平台会话代次立即撤销，建项返回、revision 读取和预览核验后的旧回调均不得导航或登记最近项目；同主体 token 轮换不误撤销原生身份。
+- 本地隔离数据库已验证 Gate 经后台 API 保存后可重新读回，匿名运行时配置为 false；后台受控浏览器 smoke 验证桌面和 320px 布局及保存确认交互。线上 OSS 下载和正式安装包登录后的端到端操作不由这些测试替代。
+
 ## OSS 契约

 ```text
@@ -4,7 +4,7 @@
 > 规范关系：AGC 插件与编辑器适配主规范
 > 验收范围：插件 manifest、宿主生命周期、RPC、Capability/权限审计、UI 挂载和编辑器适配器边界

-更新时间：`2026-09-18`
+更新时间：`2026-09-20`

 ## 目标与边界

@@ -72,7 +72,16 @@ OpenAI 的标准模型是“Plugin 作为可安装包，组合 Skills、可选 M

 Windows 与 macOS 构建都将内置插件的清单、JS 入口与面板复制到应用资源目录；staging 每次重建，避免已删除插件或跨目标原生 payload 残留。macOS 不携带 Windows native payload。Cocos 进程桥接仍仅按既有 Windows 平台实现提供，插件文件可被发现不代表 macOS 已支持编辑器控制；JS 入口的系统 Node 前提不变。

-Cocos 插件对用户可见与可启动必须同时满足当前为 Cocos 项目、宿主已注册 `cocos-editor` 原生适配器；没有适配器时从插件/扩展列表隐藏，直接启动或读取面板也在产生子进程前拒绝。正式适配器仅在 Windows 且编译 `cocos-editor-execute` 时注册；Agent 工具使用相同平台与 feature 门禁。前端只按后端列表投影判断是否自动启动，不自行推断平台能力。
+Cocos 与 Unity 插件的可见性、启动、面板、插件 RPC 和 Agent 工具暴露不按当前工程类型过滤；无当前项目以及普通 AGC、Godot、Cocos、Unity 项目使用同一套插件可用性规则。宿主必须已注册插件声明的原生适配器；没有适配器时从插件/扩展列表隐藏，直接启动或读取面板也在产生子进程前拒绝。正式适配器与 Agent 工具继续受各自平台和编译 feature 约束，禁用开关继续阻止启动与工具执行。前端只按后端列表投影判断是否自动启动，不自行推断平台能力或再次按工程类型过滤。
+
+### 工程上下文与真实编辑器目标
+
+- 工程类型只用于工程识别及对应工程工作流，不作为 `agc-cocos-editor` / `agc-unity-editor` 的管理、面板或工具目录门禁。Runtime、DirectProject MCP、工具策略快照和模型上下文使用一致规则；工具已暴露不代表真实编辑器已连接或操作已成功。
+- 前端对宿主列表中的 Cocos 与 Unity 插件分别根据适配器支持、启用、Runtime 入口和运行状态投影自动启动，不按项目类型二选一；自动启动不自动展开编辑器面板。
+- 项目切换不因新工程类型不同而停止插件或隐藏工具；当前受控项目上下文仍须按既有顺序更新，旧编辑器连接失效。旧请求与回执保留原项目归属，不能更新新项目连接状态。
+- 实际编辑器操作仍须取得有效的当前受控项目和与之匹配的真实编辑器目标。宿主注入项目路径，显式路径必须与当前受控项目一致；适配器继续校验真实工程结构、目标 PID、进程身份、版本与握手。无项目、不匹配的工程目录、无编辑器或不支持的平台均应在发送编辑器操作前明确失败，不回退到其它项目或任意编辑器进程。
+- 插件启用状态、manifest 适配器绑定、`editor.rpc` 权限、超时与并发拒绝、执行结果不确定阻断均保持原合同。取消工程类型过滤不增加自动重试，不清除项目切换或重启插件前已经产生的不确定状态。
+- 不新增或迁移项目类型、内置插件开关、API/DTO、SpacetimeDB schema 或持久项目数据；不扩大 Cocos/Unity 原生适配器的平台支持，也不把任意非引擎目录解释为可执行的编辑器工程。

 ### 内置插件与可用开关

@@ -141,6 +150,7 @@ OpenAI 官方 Plugins 文档将 Skills、MCP Server 和可选 UI 定义为同一
 - Rust：manifest 路径/权限校验、目录扫描、权限拒绝和通用适配器 registry 边界单测；`cargo check --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`。
 - 前端：`agc-plugin-sdk` TypeScript 编译、宿主服务类型检查，以及 `PluginPanelHost` 的挂载/卸载测试。
 - 内置插件开关：`builtin_plugins` 单测覆盖默认值、持久化往返、坏文件失败关闭，以及“禁用后工具目录里不再出现该工具”；`plugin_host` 单测覆盖禁用后不能启动、启用后回到 stopped。
+- 工程类型独立性：覆盖无当前项目、普通 AGC、Godot、Cocos、Unity 上下文中的插件列表、启动、面板、RPC 与 Runtime/DirectProject 工具目录一致性；项目切换不因类型变化停止插件。保留禁用开关、缺失原生适配器、平台/feature、显式跨项目路径拒绝与真实编辑器目标校验的独立反例；非引擎目录不能仅因工具可见就通过实际操作校验。
 - 插件工作区：`cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml` 覆盖工作区扫描与 manifest 启用状态；`cargo test --manifest-path plugins/agc-cocos-editor/native/cocos-editor-bridge/Cargo.toml` 覆盖 Cocos 适配器；`node --test plugins/agc-cocos-editor/src/entry.test.mjs` 覆盖插件入口协议与 manifest 一致性。
 - 通用仓库门禁：`npm run check:encoding`、`git diff --check`；发布前仍需单独执行 AGC package smoke 和安装包 smoke。

@@ -1,5 +1,23 @@
 # AI 游戏创作智能体 App 实施计划

+## 项目主模型使用记录
+
+- 项目在 `.agent/model-usage.jsonl` 保存主模型记录，供复制或压缩完整项目后查询，不新增界面展示。每条只保存版本、记录时间、来源、请求模型标识、可确认的模型名称，以及可用的客户端回合和线程身份；不保存提示词、响应正文、连接地址或凭据。
+- DirectProject 每次提交回合前保存本次请求的模型快照，来源为 `turn-request`。官方目录标识与真实型号分开：官方标识只写 `requestedModel`，不能把 `platform-default`、目录 ID、`Direct Codex` 或 `codex-app-server` 当成模型名；自定义路由保存明确提交的型号。响应返回的模型名以 `provider-response` 追加，使用请求发出时冻结的项目/回合归属，后续切模型不会覆盖历史。
+- 模型名从成功 Responses JSON 的顶层 `model` 或 SSE `response.created` / `response.in_progress` / `response.completed` 中的 `response.model` 提取；只读取白名单字段，有界处理分块和异常数据，响应内容仍原样转发。上游没有返回型号时保留请求证据，不推测实际模型。
+- 旧项目通过 `project.status` 读取 manifest 成功后补录一次：在有界范围内优先恢复项目内可明确识别的主模型运行记录，超出历史扫描预算时跳过对应候选；没有找到可信历史型号时写入当前配置快照并标注 `current-config-backfill`，不声称其为历史事实。官方配置只有目录标识时保留标识，模型名为空；以后真实回合仍继续追加。补录幂等，不覆盖或改写原项目历史。
+- 记录复用项目受控路径与追加锁；无写权限、损坏或超限时保留已有文件并写安全诊断，不因此中断项目打开、模型响应或触发额外付费重试。响应记录在阻塞工作线程中追加，文件锁等待不阻塞响应原始块转发。补录仅发生在项目 `project.status` 命令和本次回合入口，不扫描机器上的其它项目或私人会话。
+- 验收覆盖：请求与响应的模型差异、跨回合/项目隔离、切模型保留历史、旧项目补录及幂等、分块 SSE/JSON、不含模型/失败响应不伪造型号，以及凭据/正文不落盘。使用本地 HTTP fixture 验证代理透传和落盘，真实供应商调用另行报告。
+
+| 合同 | 自动化证据入口 |
+| --- | --- |
+| 来源区分、切模型保留历史、补录幂等、损坏/超限保护 | `project::model_usage::tests` |
+| JSON/SSE 字节透传、模型落盘与跨回合归属 | `agent::codex_provider_proxy::tests::model_usage_proxy_*` |
+| 分块 UTF-8、换行、多行事件和有界解析 | `agent::codex_provider_proxy::model_usage::tests` |
+| 文件锁争用不阻塞响应、流中断仍保留已确认型号 | Provider 代理的锁争用与流错误 fixture |
+
+记录格式版本为 `schemaVersion: 1`。`recordedAtMs` 是记录时间，`historicalModelConfirmed` 仅在响应观测或可信历史恢复时为 `true`；它在请求快照和当前配置补录时为 `false`。上述本地 fixture 不替代真实供应商或安装包验收。
+
 ## 2026-09-17 GameCreationApp 资源 kind：唯一词汇表、严格解析与 `app_log!` 留痕

 本节覆盖 2026-09-15 节里关于「canonical 字符串列表 / legacy 别名表 / `tracing` 留痕 / ts-rs 生成路径」的表述；枚举成员集合、「不迁移、不静默转换」的总体口径不变。
@@ -468,6 +486,8 @@ V1.11 的受保护仓库控制目录同时包含 `.git / .agent / .agents / .cod

 Prompt 静态门禁必须断言上述 Bundle section 当前定义的权威语义与组合关系；身份文案调整后应同步更新旧断言，不得继续依赖已经退出 Bundle 的历史连续措辞，也不得在测试或 Provider builder 中复制一份平行 Prompt。

+Agent 可见的系统指令、工具与参数说明、恢复指引和上下文模板统一由外置提示词文件维护。AGC 沿用 `prompts/runtime/manifest.json`：已有 composition/section 保持原有组合关系，独立调用的文本按职责登记在 `textCatalogs`，目录为 `prompts/runtime/texts/`，每份 JSON 是稳定文本键到正文的映射。构建期校验目录、文件、重复键和空正文，并生成可供 `format!` 使用的编译期文本宏；变量填充沿用 Rust 格式语法。Runtime 状态、用户内容、schema 类型与枚举、权限和校验继续由代码生成。服务端 Agent 的独立 crate 使用各自 `prompts/` 中的编译期文本文件。迁移以当前组装结果和工具 schema 等价为验收依据，源码门禁检查各提示词入口的内联正文与外置引用。
+
 2026-07-12 起，通用开发能力的 Runtime V1.1 增量以 [`【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md`](<./【技术方案】AI游戏创作Agent Runtime V1.1-2026-07-12.md>) 为编码级事实源。它补充仓库启动上下文、同一发布二进制独立 Runner、受限本地预览浏览器验证、动态隔离子 Agent 和真实 Provider 全链路验收；本文件中“进程内 tokio task”“首轮不预加载项目内容”和“不创建动态执行实例”的旧口径由 V1.1 明确替代，未涉及能力继续沿用本文件。

 同一文档的“V1.2 对标 Codex CLI 增量”继续作为受控命令与推理档位的事实源。对一次性 `command.exec` 而言，只接受 Runtime 白名单内的固定 `program` 和逐项 `args` argv，默认 `confirm`，可执行文件解析为项目外绝对路径且子进程只使用安全 PATH；不解析 shell 字符串，不提供管道、重定向、PTY 或后台进程。这里对 PTY 和后台进程的排除仅适用于 `command.exec`，不能用来否定 V1.10 的独立持久进程工具，也不能把 `command.exec` 自身改成长驻入口。`command.exec` 的 action、stdout / stderr、退出码、超时与源码指纹结果统一进入现有 `action / observation`、project revision、verification gate 和 `needs-reconciliation` 链路；只有明确验证型命令且退出码、源码指纹、命令日志、manifest 与 Agent DB 审计全通过才签发 passed gate，Git / rg / cargo metadata / 普通 npm run 只作诊断。首版只请求终止受控进程组，安全等级与 `project.verify` 相同，不宣称已具备完整 OS sandbox 或 detached-process 隔离。
@@ -1371,12 +1391,12 @@ game-project/

 ## 2026-08-20 Direct Codex 审核 Skill Pack 与受控工具内核

- 普通项目对话只由一个 project-bound Codex app-server thread 执行。客户端系统提示词只放最小工程合同、当前游戏源码有界快照、项目 prompts 和审核 Skill 索引；不再批量读取项目 `.codex/.agents` Skill 正文，也不恢复 Supervisor、专业 Agent 或 harness。
- 首页恢复“做游戏 / 做素材 / 做方案”三个创作类型，默认“做游戏”。该选择与设置页的 Agent Runtime 模式无关；每次首页提交仍只自动创建一个新项目并进入项目工作台。用户正文原样进入项目对话，`game|art|doc` 仅作为受限结构化首轮上下文传给同一 Codex thread，不拼接“初始意图”文案、不产生首页对话、不切换 Provider 或恢复旧 Runtime 编排。
+- 普通项目对话由一个 project-bound Codex app-server thread 执行。客户端系统提示词包含最小工程合同、项目 prompts 和审核 Skill 索引；源码与 Skill 正文按任务需要读取。提示词、工具描述与 Skill 直接描述当前任务、输入和成功条件，细节按调用需要提供。
+- 首页提供“做游戏 / 做素材 / 做方案”三个创作类型，默认“做游戏”。每次首页提交自动创建一个新项目并进入项目工作台。用户正文原样进入项目对话，`game|art|doc` 作为受限结构化首轮上下文传给同一 Codex thread。
 - `agc-skill-pack.v1` 只包含项目结构、陶泥儿美术、Web 游戏实现、真实浏览器试玩、客户端资源投影五项 Skill。清单记录用途、触发条件、所需工具、版本和内容 SHA-256；审核文本按 UTF-8 读取并将 CRLF 规范为 LF 后计算指纹和安装，避免混合换行造成 Windows / Linux 构建结果漂移，语义内容变化时必须同步重算对应清单指纹并提升版本。同步统一运行 `npm run agc:skill-pack:sync`，只读校验由 AGC `typecheck` 和 release build 自动执行，发现漂移时直接列出 Skill 与实际摘要，不让失配内容进入构建产物。客户端把审核文件安装到隔离目录后通过 app-server `skills/extraRoots/set + skills/list` 注册并复核，完整正文由 Codex 原生 Skill 机制按意图加载，一层引用只能经 `agc_read_skill_resource` 读取清单内 Markdown。引用路径按平台无关规则拒绝反斜杠、盘符、UNC、绝对路径和 `..`，不能依赖当前宿主的 `std::path` 语义判断其它平台路径。
- DirectProject 始终连接客户端内置的 `agc_tools` STDIO MCP；2026-08-31 起还会在启动时接入客户端扩展仓库中用户已启用的独立第三方 STDIO/HTTP MCP 配置，但不读取用户全局 Codex MCP、不开启完整 Plugin Runtime。内置工具固定为审核引用读取、标准陶泥儿美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive 语义生成、已登记图片去背景、desktop/mobile 浏览器试玩和受控 `agc_web_search`。内置 MCP 进程只做协议；真实浏览器、付费 External v1 调用与受控搜索通过随机 loopback 地址回到客户端主进程，因此不复制 GUI 登录态、开发者 Key、项目路径、revision、operation 或幂等键到模型上下文。内置与用户启用的第三方 MCP 工具都沿用 DirectProject 自动批准方式，但付费资源工具仍由客户端绑定稳定回合身份、限制单回合请求数、串行执行并优先恢复匹配账本；通用 shell、Codex 原生 webSearch、任意原生命令网络、多 Agent 和完整插件能力继续关闭。`llm.webSearchEnabled` 只控制 DirectProject 的 AGC 受控搜索工具暴露与执行，Codex 原生 `web_search` 始终保持 disabled；Provider、ToolHost、DirectHome 不纳入本次联网主链路。
- 陶泥儿生成继续复用持久幂等账本、operation 恢复、来源/下载/PNG 解码和 manifest 登记；普通客户端优先使用当前 AGC 登录会话及账号路由，只有受控的 ExternalDeveloper 发布模式才在客户端内部使用按服务器 origin 隔离的私有 Key。用户和模型都不需要提供或配置 API Key；凭据失效、来源不明或结果未知时失败关闭，不能自动换 Key 或重新扣费。
- 自定义 LLM API Key 路由只在 DirectHome/DirectProject 经 loopback `/responses` 流式代理转发。代理不注入 Key，只要求请求自带 Bearer，并剥离开发网关错误携带的 `X-Codex-*` ChatGPT 账户额度头，防止隔离 app-server 把 API Provider 误判为余额 0；旧 ToolHost 保持原 Provider 行为。
+- DirectProject 连接客户端内置的 `agc_tools` STDIO MCP，并在启动时接入客户端扩展仓库中用户已启用的独立第三方 STDIO/HTTP MCP 配置。内置工具包括审核引用读取、图片生成、标准陶泥儿美术准备、已登记资源有界查询、视频 / 角色动画 / 音效 / BGM 的 create-or-derive 语义生成、已登记图片去背景、desktop/mobile 浏览器试玩和受控 `agc_web_search`。内置 MCP 进程负责协议；真实浏览器、付费平台调用与受控搜索通过随机 loopback 地址回到客户端主进程，GUI 登录态、开发者 Key、项目路径、revision、operation 与幂等键由客户端持有并隔离于模型上下文。内置与用户启用的第三方 MCP 工具沿用 DirectProject 自动批准方式；付费资源工具由客户端绑定稳定回合身份、串行执行并优先恢复匹配账本。`llm.webSearchEnabled` 控制 DirectProject 的 AGC 受控搜索工具暴露与执行。原生工具与审批权限以下方“DirectProject Codex 完整访问覆盖”为准。
+- 陶泥儿生成复用持久幂等账本、operation 恢复、来源/下载/PNG 解码和 manifest 登记；普通客户端使用当前 AGC 登录会话及账号路由，受控的 ExternalDeveloper 发布模式在客户端内部使用按服务器 origin 隔离的私有 Key。凭据失效、来源不明或结果未知时失败关闭，不能自动换 Key 或重新扣费。
+- 自定义 LLM API Key 路由在 DirectHome/DirectProject 经 loopback `/responses` 流式代理转发。代理使用请求自带的 Bearer，并剥离开发网关错误携带的 `X-Codex-*` ChatGPT 账户额度头，按实际 API Provider 响应判断请求结果。

 - 2026-08-12 计划拒绝恢复：结构化 `runtime.plan_update` 被 Runtime 拒绝后，下一轮 Provider 请求按请求级目录收窄到实际项目 mutation 与 `respond_to_user`（已进入协作编排的 Supervisor 保留 `agent.delegate / agent.run_status`），并明确禁止再次规划、读取、搜索或验证；后续已有真实 mutation observation 后解除临时目录，不改变持久 executable policy。

@@ -1437,13 +1457,13 @@ game-project/

 ## DirectProject 工具权限现行覆盖（2026-08-24）

-本文早期关于“DirectProject 关闭通用 shell、原生网络和主动工具”的描述属于迁移前基线；2026-09-14 起，DirectProject 的 Codex sandbox 与审批规则由下方“完整访问覆盖”取代。其余 ToolHost/DirectHome 合同不变。客户端审核的 `agc_tools` MCP 继续承担平台美术、资源登记、去背景、浏览器试玩和受控搜索，并保留项目锁、幂等账本、下载校验、恢复与投影权威。
+DirectProject 的 Codex sandbox 与审批规则以下方“完整访问覆盖”为准。客户端审核的 `agc_tools` MCP 承担平台美术、资源登记、去背景、浏览器试玩和受控搜索，并持有项目锁、幂等账本、下载校验、恢复与投影权威。

 ## DirectProject Codex 完整访问覆盖（2026-09-14）

-DirectProject 现明确采用 Codex app-server 的 `danger-full-access` sandbox：thread 使用 `sandbox="danger-full-access"`，turn 使用 `sandboxPolicy.type="dangerFullAccess"`，不再发送 `workspaceWrite`、`writableRoots` 或项目根文件批准白名单。DirectProject 收到 app-server 的文件变更、命令执行和权限请求时直接接受，Codex 原生能力不再按项目路径做二次白名单裁剪；用户选择的项目目录仍作为 cwd 和 AGC 业务身份根，用于连接池、审计与客户端受控 MCP 的项目绑定。
+DirectProject 采用 Codex app-server 的 `danger-full-access` sandbox：thread 使用 `sandbox="danger-full-access"`，turn 使用 `sandboxPolicy.type="dangerFullAccess"`。DirectProject 收到 app-server 的文件变更、命令执行和权限请求时直接接受；用户选择的项目目录作为 cwd 和 AGC 业务身份根，用于连接池、审计与客户端受控 MCP 的项目绑定。

-这项覆盖只改变 Codex 原生 app-server 的 sandbox 与审批边界：首页只读对话、AGC `agc_tools` MCP 的业务授权、Provider 凭据隔离、Runtime 审计与客户端 `agc_write_file` 的产品契约继续有效。系统提示词不再把 `.agent/`、`.git/`、项目外路径等描述为 Codex 原生能力禁区，但仍要求不要把 Token、Cookie、auth.json、`.env` 或 Runtime 私有控制面主动输出到对话、工具参数和日志。
+首页按只读对话执行；AGC `agc_tools` MCP 按业务授权执行，Provider 凭据保持隔离，Runtime 审计与客户端 `agc_write_file` 遵守各自产品契约。Token、Cookie、auth.json、`.env` 或 Runtime 私有控制面禁止主动输出到对话、工具参数和日志。

 DirectProject 使用 `approvalPolicy=never`，避免每次原生调用再经过泛化 ToolHost 包装；原生命令网络随完整 sandbox 开放；联网资料仍可走受控 `agc_web_search`。多 Agent、Apps、完整插件 Runtime、hooks、Goals、Workspace Dependencies、Tool Suggestion 和原生浏览器/电脑控制仍关闭，避免绕过 AGC durable delegation、浏览器证据和副作用审计；图片生成通过客户端审核的 `agc_tools.agc_generate_image` 暴露普通单图、角色图、视觉规范图和 UI 设计图，完整游戏美术包继续使用 `agc_tools.taonier_prepare_game_art`，两者都复用同一客户端登录态、幂等账本、下载校验和 manifest/revision 投影，不开放 Codex 原生 image tool。app-server 使用隔离 `CODEX_HOME`：内置 `agc_tools` 由客户端启动参数注入，用户在客户端扩展列表启用的独立第三方 MCP 以原生配置写入该次隔离 home；全局 Codex MCP、禁用项、Plugin hooks/apps 和其它插件能力不进入 DirectProject。第三方项固定非 required，配置或启动失败只记录该项，不替换 `agc_tools`；provider session token、工具桥地址和受控搜索标记不得通过第三方 MCP 的环境转发字段泄露。配置了 AGC LLM Key 或可解析的 `OPENAI_API_KEY` 登录态时，真实 provider 凭据只由 AGC 本地 provider proxy 持有，Codex 仅使用连接级随机代理令牌；无法安全代理的 OAuth `auth.json` 继续关闭 native shell/unified exec。`agc_tools` 的平台授权由 AGC 客户端当前登录会话和受控后端完成，普通客户端不得把 DirectProject 请求改成外部 API Key 请求；401/403 只投影为客户端登录或权限异常，不向用户索要凭据或暴露内部 URL。shell 子进程采用 `shell_environment_policy` core 继承及 secret/proxy/bridge 排除，provider key 和桥接凭据不得进入命令环境。系统提示词不再预注入项目源码快照或 Skill 正文，Codex 按需读取当前 cwd 文件。
 ## 2026-08-24 AGC UI 原型桥接与自主 UI workflow
@@ -1616,23 +1636,23 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 ### 目标与非目标

 - 目标：AGC 在项目工作区打开期间按固定周期把用户项目增量上传到 OSS `agc-dev`，并在项目关闭时立即补一次同步；重复内容不重复上传，远端占用跟随当前清单收敛。
- 非目标：不做云端下载/恢复、不做跨设备合并、不保留多版本历史、不新增面向用户的上传界面、不修改 `/api/external/v1` 与 OpenAPI、不新增 SpacetimeDB 表。
+- 非目标：不做客户端云端恢复、不做跨设备合并、不保留多版本历史、不新增面向用户的上传界面、不修改 `/api/external/v1` 与 OpenAPI、不新增 SpacetimeDB 表。
 - 非目标：不把 OSS AccessKey 放进客户端；客户端不直连 OSS。

 ### 参与入口、状态与跨模块边界

- 触发入口有两个：工作区窗口 `main` 存活期间的周期定时器、工作区窗口关闭事件（`CloseRequested`）。两者共用同一个进程内同步器，同一项目的同步串行执行，周期触发在已有同步进行时直接让位，不排队堆积。
- 应用退出（`RunEvent::Exit`）不重复发起同步：该时刻窗口已销毁，按窗口重新枚举项目只会得到空集；退出路径只负责在有界预算（15 秒）内等待在途同步收尾，让关窗触发的那一次同步能写完索引再退出。
+- 触发入口为项目生命周期登记、已登记项目的周期定时器及窗口关闭事件（`CloseRequested`）。它们共用同一个进程内同步器，同一项目的同步串行执行，周期触发在已有同步进行时直接让位，不排队堆积。
+- 应用退出（`RunEvent::Exit`）不重复发起同步；退出路径只负责在有界预算（15 秒）内等待在途同步收尾，让关窗触发的那一次同步有机会写完索引再退出。超过预算不能声明最后状态已经上传。
 - 客户端扫描、差异对比、索引持久化与上传编排都在 Tauri Rust 进程（`src-tauri/src/project_snapshot/`）；WebView 只读状态，不参与差异计算。
 - 本地索引是增量对比的唯一依据：`<AppData>/project-snapshots/<projectId>/index.json` 保存上次成功同步的相对路径、校验和、字节数和修改时间。项目根使用现有 manifest 的稳定 `project_id` 作为远端身份，路径不再作为身份。
 - 可观测性按产品口径收敛到本机日志：同步结果、失败分类、延后与跳过计数只写入 AppData 诊断日志（`project_snapshot.sync.*` 前缀），客户端界面不暴露上传状态、时间线或入口按钮。`read_local_project_snapshot_state` 与 `sync_local_project_snapshot` 两条命令仅作为 native-only 的排障与联调入口登记，不在渲染层调用。
 - 远端写入经 `api-server`，客户端只持平台登录态 Access Token。两条登录态路由：`POST /api/agc/project-snapshots/files`（单文件，正文为原始字节，元数据走查询串）与 `POST /api/agc/project-snapshots/manifest`（本次同步后的完整清单）。
 - 对象键与清单由服务端决定：文件键为 `agc/project-snapshots/v1/{userId}/{projectId}/files/{sizeBytes}-{checksumDigest}/{relPath}`，清单键为 `agc/project-snapshots/v1/{userId}/{projectId}/manifest.json`。键里带字节数与摘要，因此"对象已存在且长度一致"可以作为内容一致的判据；路径按原始大小写保留，不走 `put_object` 的低位规范化。`agc` 前缀继续是服务端专用私有前缀，通用对象键解析与客户端直传票据都不覆盖它。
- 目标 bucket 使用独立配置 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET` / `_ENDPOINT` / `_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`，默认 `agc-dev` + `oss-rg-china-mainland.aliyuncs.com`，未配置时回退 `ALIYUN_OSS_*`；与"资源 bucket 与备份 bucket 分离"的既有口径一致。
+- 目标 bucket 使用独立配置 `GENARRATIVE_AGC_PROJECT_SNAPSHOT_OSS_BUCKET` / `_ENDPOINT` / `_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`，默认 `agc-dev` + `oss-rg-china-mainland.aliyuncs.com`。只允许凭据回退 `ALIYUN_OSS_ACCESS_KEY_ID` / `_ACCESS_KEY_SECRET`；bucket 与 endpoint 不跟随资源存储的 `ALIYUN_OSS_BUCKET` / `_ENDPOINT`，避免默认写入其它 bucket。显式快照目标配置继续优先；不自动搬迁其它 bucket 的现存数据。

 ### 正常、失败、重试与幂等行为

- 差异对比口径：先按 `相对路径 + 字节数 + 修改时间` 判定是否候选变更，命中旧记录则复用已存 `sha256`，只有 `(size, mtime)` 变化才重算摘要。产出新增、修改、删除三类集合，只上传新增与修改的文件。
+- 差异对比口径：先按 `相对路径 + 字节数 + 修改时间` 判定是否候选变更，命中旧记录则复用已存 `fnv1a64`，只有 `(size, mtime)` 变化才重算摘要。产出新增、修改、删除三类集合，只上传新增与修改的文件；清单元数据变化单独提交。
 - 每次成功同步的最后一步上传该项目的 `manifest.json`（当前全量文件清单：相对路径、摘要、字节数、同步序号）。清单描述的是项目当前全量内容，因此清单体积就是该项目在 OSS 上的常驻占用。
 - 远端回收：清单写入成功后，服务端读取上一版清单，按 `(路径, 字节数, 摘要)` 反推出不再被当前清单引用的对象键并删除。只处理上一版清单登记过的键，不做 LIST，因此不可能误删其它项目或其它功能的对象；单次最多回收 2000 个对象，剩余部分留到下一次清单写入继续；上一版清单读不到或解析失败时整轮跳过回收（fail-closed）。单个删除失败只记日志，不影响本次同步语义。
 - 因此本功能是"当前状态镜像 + 清单"，不保留历史版本：同一路径的内容变化会覆盖式替换远端对象，回滚能力不在本轮范围内。
@@ -1656,6 +1676,18 @@ Direct 回合的所有权属于进程内项目身份锁，不属于当前页面
 - 运行时 smoke：AGC 开发态打开项目、观察索引写入与同步日志、关闭工作区窗口后确认关闭触发的那次同步执行；报告为"客户端 diff 已验证 / 服务端已配置环境联调"两层，不合并成一句"已通"。
 - 边界：新增日志与错误文案不含 Access Token、AccessKey、绝对路径与项目内容。

+### 后台工程列表与下载
+
+- 正式客户端在单窗口内切换启动器和项目，不以窗口 URL 判断活动项目。前端把当前窗口的已打开项目登记给原生同步器；打开后发起首轮同步，离开/切换项目和物理关窗为旧项目补同步，周期扫描只读这份窗口登记。重复登记同一路径不重复发起；注册失败写诊断，不能假装已登记。
+- 清单补充可选 `projectName` 与 `pendingFiles`：名称来自本地 manifest；`pendingFiles` 是本轮失败、延后、并发变动与非策略排除的跳过文件数量。`0` 表示扫描范围已同步；大文件等被跳过不能标成完整。旧清单字段缺失表示完整性未知，维持可读取兼容，不反写旧清单。
+- 项目名称或完整性发生变化时，即使文件内容没有差异也要提交新清单；本机索引记录上次已提交的这两个字段。实际客户端下一次正常同步可补齐历史清单元数据；后台只读访问不迁移旧清单。缺失 `pendingFiles` 不能默认成 0，临时跳过原因消失后允许无文件上传的 `partial → ready` 转换。
+- 后台增加“项目工程”入口，仅 owner 及拥有 `project-snapshots` 页签权限的管理员可访问。`GET /admin/api/project-snapshots?cursor=&limit=20` 读取私有 OSS 清单并返回 `{items,nextCursor}`；单页最多 100 个，游标由服务端校验，目录与清单读取有界。条目为 `{userId,projectId,projectName,syncRevision,syncedAtMs,fileCount,totalBytes,status}`，状态为 `ready / partial / unverified`，名称缺失时显示 projectId。
+- `GET /admin/api/project-snapshots/{userId}/{projectId}/download` 只读取该用户/项目的固定清单与其引用对象，返回 `application/zip` 附件。ZIP 中路径直接使用原始相对路径，不包含 userId、摘要目录或 OSS 前缀；名称使用经过安全处理的项目名和 revision。下载固定本次读到的清单，远端并发回收导致对象缺失则整体失败，不能静默遗漏。
+- `partial` 快照下载返回 409；`unverified` 历史快照可导出已同步文件，列表明确显示“完整性未知”，动作称“下载已存文件”。`ready` 才显示“下载完整工程”。ZIP 构建核验每一文件的长度与 fnv1a64 摘要，拒绝穿越、绝对路径、重复/大小写冲突路径、非法项目身份；缺失或损坏整体失败，不返回成功的残缺 ZIP。
+- ZIP 使用服务端临时文件并限制并发，不将 2 GiB 工程整体驻留内存；成功、失败、客户端取消均清理临时文件。单文件、总量、文件数沿用上传上限，超限明确拒绝。零字节工程文件可以上传和导出。OSS 凭据与签名不下发浏览器，列表失败保留错误而非伪造空列表。
+- 工程归档范围与上传策略一致：源码、素材及引擎配置按原路径保存，依赖/构建缓存、凭据、`.agent` 会话与运行日志排除；此 ZIP 不声明能恢复 AGC 对话历史。后台读取需要目标前缀的 ListObjects 与 GetObject 权限，不新增数据库表，不改 External API。
+- 验收覆盖真实单窗口生命周期登记、首次/增量/零字节上传、后台列表分页和权限、ZIP 解压目录及摘要、部分/历史清单、缺失对象、路径拒绝、下载取消清理，并分别报告定向测试和真实环境证据。
+
 ### 未决问题

 - 用户侧看不到同步状态与失败原因（界面按产品口径不暴露），排障只能读 AppData 诊断日志或调用 native-only 命令；如果后续要支持用户自助排查，需要先确认是否允许在客户端出现上传相关 UI。
@@ -1,7 +1,9 @@
 # 策划 Agent 生产迁移与工作区浏览方案

 更新时间：2026-09-10
-状态：实施中
+状态：已完成（2026-09-18）
+
+> 现状说明（2026-09-18）：本文记录的迁移已完成，当前策划入口统一使用 Design Agent。旧 Planning V1/V2 会话、专用命令、审批卡和展示适配已删除；文中提到的 V2 文件仅代表迁移时的参考来源，不得作为现行实现、回退路径或测试迁移目标。

 ## 1. 目标

@@ -23,11 +25,11 @@

 生产侧复用 Provider、会话恢复、文件读写、审计和 UI 通信等基建，不复用现有立项策划 Agent 的行为协议。

-原型行为是新的策划 Agent 契约。现有 `Planning V2` 只作为 Provider 调用、持久化和恢复实现的参考来源，不作为行为、提示词、产物或审批契约。
+原型行为是新的策划 Agent 契约。已退役的 `Planning V2` 仅作为迁移历史中的 Provider 调用、持久化和恢复参考来源，不作为行为、提示词、产物、审批契约或回退路径。

 常驻提示词、阶段提示、速览卡结构说明、工具名称与参数、资源目录和注入映射以迁移时核对的原型文件为基线。迁移不顺便重写提示词，不增加模型输出内容门禁。旧需求文档中已明确舍弃的行为不恢复。

-本方案描述生产迁移目标。当前已接入独立设计会话、自由工具循环、阶段审批命令和工作区浏览命令；生产入口对无旧 Planning V2 会话的策划项目切换到新设计 Agent，已有 V2 会话仍走原链路。旧 Planning V2 专用展示尚未清理。
+本方案描述已完成的生产迁移。当前入口使用独立设计会话、自由工具循环、阶段审批命令和工作区浏览命令；旧 Planning V2 会话不再继续运行，旧专用展示和命令已删除。历史项目按当前 Design Agent 入口重新开始，不做旧会话转换或旧测试迁移。

 ## 3. 复用与丢弃清单

@@ -66,16 +68,17 @@

 路径穿越、绝对路径、控制目录访问和凭据泄露防护属于安全边界，可以保留；它们不能扩展成限制正常策划创作的业务门禁。

-现有参考入口如下。复用对象是其中的可用函数和通信机制，不是整个模块：
+当前实现入口如下：

-| 代码入口 | 参考内容与注意点 |
+| 代码入口 | 职责与边界 |
 | --- | --- |
-| `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/planning_session_v2.rs` | Provider 配置、请求、重试、会话恢复；丢弃问询计数策略、强制工具和输出纠错协议 |
-| `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_tools/file_ops.rs` | 读写、补丁和删除实现；不可原封不动继承 owner、产物和任务门禁 |
+| `apps/ai-game-creator-shell/src-tauri/src/agent/design_runtime.rs` | Provider 请求、工具循环、重试、阶段审批与会话恢复 |
+| `apps/ai-game-creator-shell/src-tauri/src/agent/runtime_protocol/design_session.rs` | 设计会话、阶段状态与待交互请求的持久化 |
+| `apps/ai-game-creator-shell/src-tauri/src/agent/design_tools.rs` | 固定资源包、工作区文件读写、补丁、删除、搜索与路径安全边界 |
 | `apps/ai-game-creator-shell/src-tauri/src/project/filesystem.rs` | 路径解析、文件列出和读取、基础写入；内部绝对路径字段不得传给模型 |
-| `apps/ai-game-creator-shell/src/App.tsx` | Tauri 事件订阅、文件刷新、会话恢复入口；不把旧策划状态投影当作新契约 |
-| `apps/ai-game-creator-shell/src/features/project-workspace/ProjectWorkspaceChatPane.tsx` | Game Agent 文件列表与读取入口；新的文件浏览应直接打开文件视图，不往聊天中追加文件正文 |
-| `apps/ai-game-creator-shell/src/features/project-workspace/GddApprovalCard.tsx` | 仅参考现有面板和通用交互样式；不沿用结构化 GDD 展示及三按钮决定模型 |
+| `apps/ai-game-creator-shell/src/App.tsx` | Design Agent IPC、事件订阅、文件刷新、会话恢复与输入提交 |
+| `apps/ai-game-creator-shell/src/features/project-workspace/DesignWorkspacePanel.tsx` | 策划工作区文件浏览与正文展示，直接打开文件视图 |
+| `apps/ai-game-creator-shell/src/features/project-workspace/DesignAgentSurface.tsx` | 消息、reasoning、澄清与阶段审批交互 |

 不为此次迁移先建设通用 Agent 框架。已有函数能够直接使用就直接使用，只有确实需要拆除业务耦合时才做局部拆分。

@@ -239,6 +242,8 @@ UI 使用“批准”和“继续修改”两个文字按钮，分别配 Lucide

 澄清卡提供独立的选项回答和自由文本回答。点击选项只提交请求身份和所选选项，不携带文本框草稿；Runtime 根据已保存的问题/选项形成明确的回答内容，不只传递“3”之类的序号。用户也可不选择任何选项，直接填写文本并点击“提交回答”，发送请求身份、`optionIndex: null` 和文本正文，Runtime 将其表述为“用户回答”，不将它当作某个选项的补充。新澄清请求出现时清空上一题的文本草稿。不沿用生产旧问题数量上限和固定问答字段。澄清卡待回答状态应可在重启后恢复。

+用户向上滚动查看策划历史时暂停自动跟随；发送新的普通消息后恢复跟随最新消息和回复，仅编辑输入内容不改变历史阅读位置。
+
 ## 8. 用户工作区浏览

 `design_artifacts` 同时是 Agent 工作区和用户查看策划资料的文件区。用户不需要通过聊天请求 Agent 才能看到文件。
@@ -307,7 +312,7 @@ UI 使用“批准”和“继续修改”两个文字按钮，分别配 Lucide

 实现落在生产 Rust 会话/工具层与现有 React 策划入口，不随应用再启动 Python 原型进程。保持单一用户入口，不为迁移建设第二套工作台。

-切换前盘点旧 Planning V2 活跃会话和持久化数据。旧结构化 GDD 不能直接推断为新五阶段中的某个阶段，不自动转换或覆盖已有项目。旧会话的继续运行或只读保留方式需在实际盘点后明确，再处理入口退役；这不要求新 Agent 兼容旧 GDD 行为。
+迁移时不把旧 Planning V2 会话或结构化 GDD 转换为新五阶段状态。旧命令、旧展示和旧测试已删除；当前入口不读取旧 V2 authority，也不要求新 Agent 兼容旧 GDD 行为。

 ## 12. 验收标准

@@ -340,7 +345,7 @@ UI 使用“批准”和“继续修改”两个文字按钮，分别配 Lucide
 - 外部搜索；
 - 多个策划身份提示词同时存在；
 - 多 Agent 协作；
- 旧 Fast GDD 展示和 GDD schema 兼容。
+- 不迁移旧 Fast GDD 展示、V2 schema 或旧测试；新 Design Agent 使用自己的会话和阶段产物测试。

 ## 14. 开发调试入口

@@ -1,10 +1,10 @@
 # 策划会话 Runtime V2 接入与旧链路退役方案

 - 日期：2026-09-03
- 状态：P0 合同冻结、P1 内核、P2 产物闭环、P3 入口/UI 接入、P4 灰度回归验收与 P5 旧链路退役均已完成；本文是新生产实现的目标方案与阶段验收合同
- 适用范围：AGC 桌面 App 的“做方案”入口、策划会话、GDD 产物与审批
+- 状态：**历史方案，已完成并退役**。Runtime V2 及其专用入口、命令、展示和测试已在 2026-09 按四不写原则删除；当前“做方案”统一使用独立 Design Agent。
+- 适用范围：历史 AGC“做方案”入口、策划会话、GDD 产物与审批设计

-> 本文规定新策划 Agent 的生产接入和旧链路退役方式。P3 开始修改正式 AGC 入口与工作台，但旧 `project-supervisor-plan` / `project-planning` 源码仍保留，直到 P5 完成退役；V2 切换时旧链路直接封存，所有未完成旧会话强制失败，旧 Fast GDD 文档之后只作为历史记录依据。
+> 本文只用于追溯 Runtime V2 的设计和退役过程，不是现行实现依据。不要恢复 `planning_session_v2`、`planning_policy_v2`、`hydrate_planning_session_v2` 或 V2 专用 UI；当前行为以 Design Agent 生产迁移方案和代码为准。

 ## 1. 决策摘要

@@ -24,53 +24,51 @@

 - `docs/`：当前 PRD、架构、开发运维、设计和测试口径。
 - `docs/project-memory/shared-memory/`：长期团队记忆、决策、流程和踩坑摘要。
- `.codex/`：Codex 工具资源，不作为项目知识库。
+- `.codex/`：Codex 工具资源。
 - `.codex/skills/`：Codex 可复用技能；只在任务命中时读取。
 - `scripts/rag/`：Agent 本地检索入口，只提供候选上下文。

-RAG 默认不安装运行时依赖，也不把 LanceDB、Transformers.js 或本地 embedding 模型写入根 `package.json`。需要启用时，先询问用户；用户确认后只安装到 gitignored 的 `.rag/runtime/`，模型缓存和向量库留在 `.rag/`。
+启用 RAG 运行时依赖前先询问用户；用户确认后只安装到 gitignored 的 `.rag/runtime/`，模型缓存和向量库留在 `.rag/`。

 ## 执行风格

- 修改范围保持聚焦，不做无关重构。
+- 修改范围围绕交付结果与验收判据保持聚焦。
+- Agent 可见内容直接描述当前任务、输入和成功条件，细节按调用需要提供。
 - 跨模块、公开契约、SpacetimeDB schema、AGC/Runtime 和复杂 UI 状态链路按 [`docs/【协作规范】规范驱动开发工作流-2026-09-12.md`](./【协作规范】规范驱动开发工作流-2026-09-12.md) 执行主规范、里程碑、实现计划和逐里程碑验收；局部修复继续使用轻量流程。
 - 优先复用现有系统、页面、组件、脚本、DTO 和文档位置。
- 不新增平行入口、平行作品架、平行公开列表、平行业务真相或临时兼容层。
- 不把前端临时状态当正式业务事实；正式状态以后端投影、后端 API 或当前架构文档为准。
- 涉及中文内容时保持中文，不擅自翻译成英文。
- 发现中文乱码时先确认真实编码，不直接沿用乱码，也不用英文替换。
- 含中文文件优先局部补丁；非必要不要整文件重写。
+- 正式状态以后端投影、后端 API 或当前架构文档为准。
+- 涉及中文内容时保持中文；发现乱码时先确认真实编码并恢复正确中文。
+- 含中文文件优先局部补丁。
 - 阶段性大任务完成后，整理当前上下文、剩余风险和下一步入口，降低后续接手噪音。

 ## 文档规则

 - 工程修改必须同步更新对应 `docs/` 文档。
 - 没有合适文档时，新文档放入 `docs/` 下合适位置，文件名使用 `【标签名】中文标题-日期.md`。
- PRD 或技术方案要具体到能指导编码，不写会导致落地漂移的泛泛描述。
+- PRD 或技术方案要具体到能指导字段、契约、状态和验收的实现。
 - 长期有效的架构约定、接口变化、排障经验、开发流程或协作规则写入 `docs/project-memory/shared-memory/`。
 - 阶段性计划放入 `docs/project-memory/plans/`；确定但未实施的共享 TODO 放入 `docs/project-memory/todos/`。
 - 不提交个人配置、密钥、Token、Cookie、会话记录、认证文件、本地私密路径、构建产物、日志、缓存和数据库 dump。

 ## UI 与前端规则

- UI 面板保持清爽，不默认写功能说明、规则说明、键盘快捷键说明或开发解释文本。
+- UI 面板优先呈现任务内容与操作，说明按当前操作需要提供。
 - 移动端优先，同时保证桌面端体验完整。
- 弹出独立面板的交互使用弹窗、抽屉、popover 或页面级 portal，不在当前面板下面追加内容。
- 页面展示以后端返回状态为准，不在前端自行计算结论型业务状态。
- 现役平台入口固定为 `/creation`、`/project`、`/profile`：创作主页只读取图片编辑器项目与公开编辑器素材，个人页只复用账号、钱包和公共设置能力。旧 `/api/creation-entry/config` 及模板工作台、公开作品和专属运行态已经退役，不得因历史表仍在而恢复前端入口或后端接口。
- 优先扩展现有公共组件，例如平台弹窗、图片输入、媒体预览、状态提示和动作按钮，不在业务页复制通用逻辑。
+- 弹出独立面板的交互使用弹窗、抽屉、popover 或页面级 portal。
+- 页面展示以后端返回状态为准。
+- 现役平台入口固定为 `/creation`、`/project`、`/profile`：创作主页读取图片编辑器项目与公开编辑器素材，个人页复用账号、钱包和公共设置能力。
+- 优先扩展现有公共组件，例如平台弹窗、图片输入、媒体预览、状态提示和动作按钮。

 ## 后端与数据真相

 - 后端路线固定为 `server-rs + Axum + SpacetimeDB`。
- 旧 `server-node`、Express、PostgreSQL、Go 服务端、`maincloud` 相关脚本、环境变量、测试和文档要求均为历史残留。
 - 领域规则沉到 `module-*`；SpacetimeDB 表、reducer、procedure、事务 adapter 和 row mapper 留在 `spacetime-module`。
 - 后端访问 SpacetimeDB 统一经 `spacetime-client` facade。
 - HTTP / SSE / BFF 和外部副作用编排留在 `api-server`；OSS、LLM、认证、语音等外部平台能力留在 `platform-*`。
- 前后端 DTO、公开契约和跨页面复用的无业务真相 TypeScript 代码留在 `shared-contracts` / `packages/shared`；共享 UI 组件与纯工具可留在 `packages/shared`，但领域规则、后端副作用和正式状态不得下沉。
+- 前后端 DTO、公开契约留在 `shared-contracts` / `packages/shared`；共享 UI 组件与纯工具留在 `packages/shared`，领域规则、后端副作用和正式状态由后端对应层负责。
 - 契约、路由、DTO 去留和 breaking change 以当前后端架构文档、`api-server/src/app.rs`、`shared-contracts` 和 `packages/shared` 为准。

-后端修改后按当前 DDD 文档执行验收。涉及 API smoke 时，使用 `npm run dev:api-server` 重新拉起后端并检查 `/healthz`；不要使用旧 `maincloud` 启动口径。
+后端修改后按当前 DDD 文档执行验收。涉及 API smoke 时，使用 `npm run dev:api-server` 重新拉起后端并检查 `/healthz`。

 ## SpacetimeDB 规则

@@ -106,7 +104,7 @@ RAG 默认不安装运行时依赖，也不把 LanceDB、Transformers.js 或本

 ## 默认验证

-按修改范围选择验证，不追求无意义全量扫：
+按修改范围选择验证：

 - 文档 / 中文文本：`npm run check:encoding`、`git diff --check`
 - 前端：定向测试、`npm run typecheck`、必要的页面交互 smoke 和移动端视口检查
@@ -64,11 +64,18 @@ npm run check:server-rs-ddd

 ## API 路由分组

+### AGC 项目工程后台读取
+
+`GET /admin/api/project-snapshots` 与 `GET /admin/api/project-snapshots/{userId}/{projectId}/download` 复用后台鉴权，要求 owner 或 `project-snapshots` 页签权限。数据来自私有 OSS 项目清单，不复用图片编辑器项目表、不新增 SpacetimeDB schema。`platform-oss` 只提供固定 AGC 前缀下的有界目录枚举和对象读取，`api-server` 负责列表投影、归档与下载响应，后台 DTO 留在 `shared-contracts/admin`。
+
+列表按清单中的 `pendingFiles` 区分 `ready / partial / unverified`；历史字段缺失必须为 `unverified`。下载冻结本次清单，按原始目录构造 ZIP；逐项核对长度和摘要，部分同步、对象缺失、损坏或危险路径不能返回完整工程。客户端不接触 OSS 凭据。完整契约见 [AGC 实施计划](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md) 的“后台工程列表与下载”。
+
 路由树由 `server-rs/crates/api-server/src/app.rs` 统一构造。当前主要分组：

 - 健康检查：`GET /healthz`、`GET /readyz`。
 - 后台管理：`/admin/api/*`，现役路由包括登录与账号管理、Dashboard / 概览、HTTP debug、埋点、表查询、通用 feature gate、编辑器定价与素材 / 精选管理，以及账号侧兑换码、邀请码、任务、钱包、充值与退款管理；不再挂载旧创作入口配置、旧作品互动或旧玩法运营路由。环境变量管理员固定作为 owner，持久化 member 每次请求按当前 `enabled`、`token_version` 和一级 Tab 权限实时校验；账号管理仅 owner 可访问，未登记权限映射的新后台路由对 member 默认拒绝。完整权限矩阵见 [`docs/technical/【后台管理】多账号与Tab访问权限方案-2026-07-14.md`](./technical/【后台管理】多账号与Tab访问权限方案-2026-07-14.md)，Dashboard 指标口径见 [`docs/technical/【后台管理】Dashboard运营看板方案-2026-06-23.md`](./technical/【后台管理】Dashboard运营看板方案-2026-06-23.md)。
 - 通用灰度控制面固定为后台 `#gray-release` 与 `GET/PUT /admin/api/feature-gates`；页面固定目标只登记现役功能，不读取旧 `/admin/api/creation-entry/config`，也不恢复 `creation-entry:*` 动态目标。
+- AGC 模板库使用 `agc:template-library`，不新增 schema；`GET /api/runtime/frontend-config` 追加账号相关的 `agcTemplateLibraryEnabled`，匿名和 Gate 缺失为 false，存在配置时复用通用灰度规则。响应设置 `Cache-Control: no-store` 与 `Vary: Authorization`，客户端原生操作独立检查权限。官网公开 `GET /api/client-downloads` 则读取服务端 `GENARRATIVE_CLIENT_DOWNLOAD_CHANNEL`（默认 dev）对应的 Windows/macOS 分区，渠道与系统独立，不从请求 query 接受 URL 或渠道覆盖。
 - 认证与账号：`/api/auth/*`、`/api/profile/me`，包括短信、密码、微信、refresh session、多端会话和登出。
 - 个人中心：`/api/profile/*`，包括钱包流水、任务、领奖、充值、反馈、邀请和兑换等账号侧能力。
 - 平台基础能力：`/api/llm/*`、`/api/speech/volcengine/*`，只保留通用 LLM 和语音代理。
@@ -299,18 +299,18 @@ npm run check

 PR checkout 必须保留完整 Git 历史，并把 PR base SHA 传给 `SPACETIME_SCHEMA_BASE_REF`。`check:spacetime-schema` 依赖该基线识别已有表字段删除、改名、重排和改类型；事件给出的基线缺失或本地不可解析时必须直接失败，不能退化为空差异检查。Gitea 的 PR checkout 是 PR head，不是与目标分支的预合并 commit，因此 workflow 还会验证 PR head 包含事件中的最新 base commit；分支保护必须继续开启“PR 过期禁止合并”，过期分支先更新再重跑。向 `master` 直接推送时使用 push before SHA；手工触发先尝试 `origin/master`，若它与 `HEAD` 相同则改用 `HEAD^`，仍无法得到不同提交时失败关闭。

-启用或注册执行 PR job 的 runner 前，Gitea 服务端必须至少升级到 `1.26.4`；不得在 `1.26.2` 上执行不受信任 PR 代码。runner 保留 `ubuntu-latest` 标签作为已有固定 digest Ubuntu 24.04 级环境，同时提供专用 `genarrative-ci` 标签，并将后者映射到已装入 runner 内层 Docker 的完整 Image ID；两者均不得映射到 host 执行器，job 不得获得 Docker socket、业务环境变量、业务密钥或不必要的内网。workflow 不再现场运行 apt、`actions/setup-node` 或 rustup 安装；Node 22、Rust 1.96.0、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖都由预构建镜像提供。checkout 由镜像内 `genarrative-gitea-checkout` 直接从当前 Gitea 拉取事件 commit，并执行 5 次有界重试；不得恢复为运行时从 GitHub 克隆 action。当前锁命中时，npm 与 Linux 目标 Cargo 下载可完全使用镜像内预热缓存；锁文件新增依赖时才经受控 proxy 补齐。构建 CI 镜像仍需访问固定基础镜像、Ubuntu / Google Chrome 软件源、nodejs.org、npm registry 和 crates.io。本阶段不使用共享 Actions cache，避免不受信任 PR 污染跨 job 可写缓存。当前 Runner 2.0.0 已支持 job 级 `timeout-minutes`，但 runner 全局 `3h` 仍是所有任务的硬上限。
+启用或注册执行 PR job 的 runner 前，Gitea 服务端必须至少升级到 `1.26.4`；不得在 `1.26.2` 上执行不受信任 PR 代码。runner 保留 `ubuntu-latest` 标签作为已有固定 digest Ubuntu 24.04 级环境，同时提供专用 `genarrative-ci` 标签，并将后者映射到已装入 runner 内层 Docker 的完整 Image ID；两者均不得映射到 host 执行器，job 不得获得 Docker socket、业务环境变量、业务密钥或不必要的内网。workflow 不再现场运行 apt、`actions/setup-node` 或 rustup 安装；Node 22、Rust 1.98.1、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖都由预构建镜像提供。checkout 由镜像内 `genarrative-gitea-checkout` 直接从当前 Gitea 拉取事件 commit，并执行 5 次有界重试；不得恢复为运行时从 GitHub 克隆 action。当前锁命中时，npm 与 Linux 目标 Cargo 下载可完全使用镜像内预热缓存；锁文件新增依赖时才经受控 proxy 补齐。构建 CI 镜像仍需访问固定基础镜像、Ubuntu / Google Chrome 软件源、nodejs.org、npm registry 和 crates.io。本阶段不使用共享 Actions cache，避免不受信任 PR 污染跨 job 可写缓存。当前 Runner 2.0.0 已支持 job 级 `timeout-minutes`，但 runner 全局 `3h` 仍是所有任务的硬上限。

 当前 `genarrative-station` 使用 Gitea `1.26.4` 和基于 Gitea Runner `2.0.0-dind-rootless` 的固定 digest 修补镜像。Runner 2.0.0 会先把 `systempaths=unconfined` 解析为空 `MaskedPaths` / `ReadonlyPaths`，再被 `mergo.WithOverride` 当成 empty value 丢失；站点修补只在 merge 后保留这两个显式空 slice，不改其它 runner 行为。真实 job inspect 必须看到 `MaskedPaths=[]`、`ReadonlyPaths=[]`、`SecurityOpt=[seccomp=unconfined]`、`Privileged=false`、无 CapAdd 且 `Binds=[]`。外层 runner 以 `rootless` 用户运行，`privileged=false`、不增加 `CAP_SYS_ADMIN`，只映射 `/dev/net/tun`，内部 Docker 只监听私有 Unix socket；runner 配置保持 `docker_host: "-"`、`valid_volumes: []`、`bind_workdir: false` 和 `force_pull: false`，防止内部 Docker socket 或宿主 bind mount 进入 job。job 只连接 `gitea-actions` internal network：`genarrative-station` 由只转发 `/git` 到 Gitea 的内部 gateway 解析，公网依赖只经拒绝私网、保留地址和 metadata 的 80/443 egress proxy；绕过 proxy 的公网和 Postgres/Redis 数据网都必须不可达。完整 bwrap canary 需要 rootless DinD 外层的 rootlesskit AppArmor/userns 边界，以及内层 job 的 namespace/proc 挂载支持；相关 `seccomp/systempaths` 放宽只允许存在于这个无宿主 socket 的 rootless DinD 内层，禁止复制回控制宿主 rootful Docker 的 runner。

-CI job 镜像由 `deploy/container/gitea-ci-job.Dockerfile` 定义：Ubuntu job base 固定为 `sha256:58ea92624c7c09582e05594d95488331045053d3a3f34cf09649f2a32313a614`，Rust stage 固定为 `sha256:19817ead3289c8c631c73df281e18b59b172f6a31f4f563290f69cddd06c30e9`，Node `22.23.1` 发行包执行 SHA-256 校验，Google Linux 主签名指纹固定，Chrome 固定为 `150.0.7871.181-1`。构建脚本以 NUL 分隔白名单 tar 流发送 Dockerfile、checkout 脚本、根 lock、全部 workspace manifests，以及 server-rs、桌面壳和 AI 游戏创作壳 Cargo manifests/lock。镜像按唯一根 npm workspace 锁、server-rs 锁、桌面壳锁和 AI 游戏创作壳 Cargo 锁预热四份下载缓存，不包含 `node_modules` 或 Cargo `target`；三个 `cargo fetch --locked` 在 Cargo 自身重试之外再执行最多 5 次整命令级有界重试，处理 registry index 握手失败，最终仍分别以断网 `cargo fetch --locked` 关闭验证。CI 镜像定义或根 lock/workspace manifests 变化后必须重建并发布新的固定 Image ID；不得继续沿用旧镜像 digest。runner 标签保留 `ubuntu-latest`，并将 `genarrative-ci` 映射到当前已验证的完整 Image ID。内层 Docker 数据必须持久化；`force_pull: false` 表示只使用已装载的精确内容，Image ID 缺失时 job 必须失败关闭，不得回退浮动 tag 或临时连 registry。
+CI job 镜像由 `deploy/container/gitea-ci-job.Dockerfile` 定义：Ubuntu job base 固定为 `sha256:58ea92624c7c09582e05594d95488331045053d3a3f34cf09649f2a32313a614`，Rust stage 固定为 `sha256:93ce27a88655056a51dbdd8f5f2d7ddc071c7b0070fb288a37b5a285fc83971e`，Node `22.23.1` 发行包执行 SHA-256 校验，Google Linux 主签名指纹固定，Chrome 固定为 `150.0.7871.181-1`。构建脚本以 NUL 分隔白名单 tar 流发送 Dockerfile、checkout 脚本、根 lock、全部 workspace manifests，以及 server-rs、桌面壳和 AI 游戏创作壳 Cargo manifests/lock。镜像按唯一根 npm workspace 锁、server-rs 锁、桌面壳锁和 AI 游戏创作壳 Cargo 锁预热四份下载缓存，不包含 `node_modules` 或 Cargo `target`；三个 `cargo fetch --locked` 在 Cargo 自身重试之外再执行最多 5 次整命令级有界重试，处理 registry index 握手失败，最终仍分别以断网 `cargo fetch --locked` 关闭验证。CI 镜像定义或根 lock/workspace manifests 变化后必须重建并发布新的固定 Image ID；不得继续沿用旧镜像 digest。runner 标签保留 `ubuntu-latest`，并将 `genarrative-ci` 映射到当前已验证的完整 Image ID。内层 Docker 数据必须持久化；`force_pull: false` 表示只使用已装载的精确内容，Image ID 缺失时 job 必须失败关闭，不得回退浮动 tag 或临时连 registry。

 镜像更新命令：

 ```bash
 bash scripts/gitea-ci-job-image.sh build
 bash scripts/gitea-ci-job-image.sh verify
-bash scripts/gitea-ci-job-image.sh export /仓库外受控路径/genarrative-gitea-project-ci-20260807.1.tar.zst
+bash scripts/gitea-ci-job-image.sh export /仓库外受控路径/genarrative-gitea-project-ci-20260920.1.tar.zst
 bash scripts/gitea-ci-job-image.sh load-runner
 ```

@@ -392,7 +392,7 @@ npm run spacetime:generate
 npm run check:spacetime-schema
 ```

-仓库根目录的 `rust-toolchain.toml` 固定 Rust `1.96.0` 并要求 `rustfmt` 组件，
+仓库根目录的 `rust-toolchain.toml` 固定 Rust `1.98.1` 并要求 `rustfmt` 组件，
 `rustfmt.toml` 固定 Edition 2024 的格式化口径。Rust 源码分属两个独立 Cargo
 workspace，必须分别执行以下格式化命令：

@@ -548,6 +548,12 @@ curl -fsS --max-time 5 http://127.0.0.1/api/editor/showcase/resources >/dev/null

 ### AGC 项目快照上传目标

+后台“项目工程”（`/admin/#project-snapshots`）按项目列出远端快照。完整快照提供“下载完整工程”，按原始目录返回 ZIP；未完成同步的项目暂不可下载，旧清单缺少完整性声明时显示“完整性未知”，只能“下载已存文件”。不要直接把 OSS 的 `files/{size}-{digest}/` 目录下载当成工程。
+
+自动上传以原生登记的活动工程为准：打开即首传、每 300 秒周期同步、切换/关闭补传。排障同时核对 AppData `project-snapshots` 索引、`project_snapshot.sync.*` 日志和远端清单；只有测试项目的历史清单不能证明现役项目同步生效。前端在同一窗口内切项目时必须登记生命周期，不能只检查 URL 是否包含 `projectPath`。
+
+后台枚举另外需要 AGC 私有前缀的 `ListObjects`（RAM `oss:ListObjects`，限制 prefix）与 `GetObject` 权限；下载不需要写入权限。客户端修复、后台页面与 api-server 必须分别发布才能在安装版和线上后台使用。本地定向测试及页面模拟不能代替发布后的真实上传与 ZIP 下载验收。
+
 AGC 客户端按周期与项目关闭时机把用户项目增量上传到 `agc-dev`。客户端只持有平台登录态 Access
 Token，经 `POST /api/agc/project-snapshots/files`（单文件原始字节）与
 `POST /api/agc/project-snapshots/manifest`（本次同步清单）交给 `api-server`，由服务端写入私有前缀
@@ -724,9 +730,11 @@ Pingora current release 自审脚本 `scripts/ops/pingora-current-release-audit.

 Mac universal 构建脚本位于 `jenkins/Jenkinsfile.ai-game-creator-shell-macos-build`，只对专用 `genarrative-agc-macos` 标签运行。节点按 EXCLUSIVE、单 executor 配置，Job 禁止并发且不设置 trigger；不接入现有每小时版本调度，不改 Windows 发布职责。它使用独立 Jenkins workspace，禁止指向开发 checkout 或共享其可写 target/node_modules。

-该 Job 的职责是构建并发布 `dev-mac` 渠道更新：执行 `npm ci` 后使用锁文件校验并补齐两种 macOS Codex 原生依赖，再调用 `scripts/build-macos-ci.mjs`（AGC 应用目录下）生成 universal app、arm64/x86_64 隔离 smoke、universal DMG 与渠道清单 `latest.json`，用产物内烘焙的公钥复核更新包签名（`verify-updater-signature.mjs`），最后按 `AGC_RELEASE_DRY_RUN` 决定是否上传 OSS。归档限 `artifacts/` 下的 DMG、SHA-256、`latest.json`、更新包签名、更新摘要、非敏感构建清单和源码 commit；不归档用户 HOME、Jenkins secret、原始工作目录或全量日志。
+Job 名为 `Genarrative-Agc-MacOS-Build`，SCM 直接读取仓库内上述 Jenkinsfile，参数为 `SOURCE_BRANCH`、`COMMIT_HASH`、`AGC_UPDATE_CHANNEL`、`AGC_RELEASE_VERSION`、`AGC_RELEASE_DRY_RUN`、`AGC_UPDATE_RELEASE_NOTES`、`OSSUTIL_BIN`。渠道参数是基础名（不含系统，默认 `dev`），脚本不接受 `dev-mac` 这类系统后缀，写入分区固定推导为 `<channel>-mac`：这与 Windows Job 的 `<channel>-win` 对称，也延续已发布客户端的端点。

-发布凭据全部走 Jenkins 全局凭据，并在 `withCredentials` 内注入当前进程：`AgcUpdaterSigningKey`（与 `AgcUpdaterSigningKeyPassword`）映射为 `TAURI_SIGNING_PRIVATE_KEY` / `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，`AliyunAccessKeyId` / `AliyunaccessKeySecret` 映射为 `AGC_OSS_ACCESS_KEY_ID` / `AGC_OSS_ACCESS_KEY_SECRET`；私钥与凭据不写入 workspace、日志或归档产物。上传顺序为更新包、签名、首装包，三者全部成功后才覆盖 `agc/dev-mac/latest.json` 指针；`AGC_RELEASE_DRY_RUN` 默认开启，dry-run 只打印将上传的对象、不写任何 OSS 对象。Mac 节点需要 `ossutil`（实测 1.7.19 原生 arm64 可用，装在 `~/.local/bin`，已在 Job 的 PATH 内），可用 `OSSUTIL_BIN` 指定命令名或绝对路径。首次发布建议显式指定 `AGC_RELEASE_VERSION`，避免按渠道高水位递增时出现版本链回退。
+该 Job 的职责是构建并发布 `<channel>-mac` 分区更新：执行 `npm ci` 后使用锁文件校验并补齐两种 macOS Codex 原生依赖，再调用 `scripts/build-macos-ci.mjs`（AGC 应用目录下）生成 universal app、arm64/x86_64 隔离 smoke、universal DMG 与分区清单 `latest.json`，用产物内烘焙的公钥复核更新包签名（`verify-updater-signature.mjs`），最后按 `AGC_RELEASE_DRY_RUN` 决定是否上传 OSS。归档限 `artifacts/` 下的 DMG、SHA-256、`latest.json`、更新包签名、更新摘要、非敏感构建清单和源码 commit；不归档用户 HOME、Jenkins secret、原始工作目录或全量日志。
+
+发布凭据全部走 Jenkins 全局凭据，并在 `withCredentials` 内注入当前进程：`AgcUpdaterSigningKey`（与 `AgcUpdaterSigningKeyPassword`）映射为 `TAURI_SIGNING_PRIVATE_KEY` / `TAURI_SIGNING_PRIVATE_KEY_PASSWORD`，`AliyunAccessKeyId` / `AliyunaccessKeySecret` 映射为 `AGC_OSS_ACCESS_KEY_ID` / `AGC_OSS_ACCESS_KEY_SECRET`；私钥与凭据不写入 workspace、日志或归档产物。上传顺序为更新包、签名、首装包，三者全部成功后才覆盖 `agc/<channel>-mac/latest.json` 指针；`AGC_RELEASE_DRY_RUN` 默认开启，dry-run 只打印将上传的对象、不写任何 OSS 对象。Mac 节点需要 `ossutil`（实测 1.7.19 原生 arm64 可用，装在 `~/.local/bin`，已在 Job 的 PATH 内），可用 `OSSUTIL_BIN` 指定命令名或绝对路径。首次发布建议显式指定 `AGC_RELEASE_VERSION`，避免按渠道高水位递增时出现版本链回退。

 产物边界：macOS 代码签名与公证暂缺，构建保持 `--no-sign`，构建清单显式记录 `appleSigned=false` / `notarized=false`。用户首次安装需要在 Gatekeeper 中手动放行；更新包校验本身只依赖 minisign 签名，因此未签名不阻断自动更新的校验环节，但「安装 → 重启接管新版本」的实机闭环仍未验证，不得以构建成功替代。

@@ -24,9 +24,9 @@
 | 生成背景音乐                  | `POST /api/editor/audios/background-music/generations` |

 - 意图解析与工具编排在后端 api-server，前端只渲染状态，不承接业务规则。
- 下面的工具选择口径属于 Agent 规划 prompt / function-calling 约束，不是侧边栏 UI 说明文案；侧边栏面板不展示这些规则解释。
+- 工具选择规则写入 Agent 规划 prompt / function-calling；提示词与工具描述直接说明适用任务、输入、单次产出和成功条件，侧边栏展示对话内容与操作。
 - 用户要求“规范图 / 视觉规范图 / 风格规范图 / 素材规范展板”时，规划默认选择 `generate_image`，并在 prompt 中明确要求生成规范展板，包含统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等可落地的视觉规范元素。
- 用户要求“角色规范图”且语义是角色的规范展板、风格展板或设定板时，仍走 `generate_image`，不要误分流到 `generate_character`；只有实际生成角色立绘、角色主形象或角色视觉资产时才走 `generate_character`。用户要求多个图标素材、图集或 spritesheet 时才走 `generate_icon_spritesheet`。
+- 用户要求角色规范展板、风格展板或设定板时，选择 `generate_image`；生成角色立绘、角色主形象或角色视觉资产时，选择 `generate_character`；生成多个图标素材、图集或 spritesheet 时，选择 `generate_icon_spritesheet`。
 - 画布 Agent 的 `generate-icon-spritesheet` 不暴露切分模式参数，链路固定显式传 `sliceMode=connected-components`；等分网格或固定槽位需求必须由外部 API 调用方显式传 `sliceMode=grid` 与来自需求的 `gridX`/`gridY`，画板工具栏的 `拆分图集` 仍只做连通域拆分。禁止在工具描述、确认卡或回复里承诺按 `2×2` 等网格切分。
 - 所有生成必须走 `execute_billable_asset_operation_with_cost` 与模型定价配置，禁止绕过定价收口。
 - function-calling 的 JSON Schema 必须与参数默认值和运行时校验保持一致，不能只在 description 中提示会被运行时拒绝的组合。`generate-ui-design` 固定 `gpt-image-2`，因此 `image_size` 只暴露 `1K / 2K`；其它可切换图片模型的工具通过共享条件 schema 在显式选择 `gpt-image-2` 时同样把 `image_size` 限制为 `1K / 2K`，省略模型时仍按默认 nanobanana2 允许 `0.5K`。`generate-video` 省略 `model` 时按默认 `seedance2.0-fast` 约束 `resolution` 为 `480p / 720p`，显式选择其它模型时仍使用其现有分辨率范围。运行时强类型校验继续作为最终防线。
@@ -112,13 +112,14 @@
 - 每个用户回合必须由 LLM 返回结构化计划；单次 completion 不是有效 JSON 时，runner 先把无效原文作为 assistant message 追加到当前 staged turn，再追加 system 纠正消息，明确要求下一轮只按既定 JSON Response Format 重试；下一次 completion 必须同时看到该无效原文和纠正指令。无效原文只是重试上下文，不进入对外 `PromptOutput` 或用户可见的会话增量；后续规划成功时随 staged turn 一并提交，无工具活动且最终失败时按下文事务规则整体回滚。LLM 未配置、连接已经断开、请求明确失败、达到最终安全上限或多轮重试后仍不可解析时，后端写入正文为 `ERROR <错误内容>` 的 system 消息，不使用本地关键词或“收到：...”回显兜底。面向用户的规划错误使用中文语义，不暴露 `completion error` 等 framework 内部前缀或原始配置/定价诊断；原始错误只记录在后端日志。该错误消息与其它 system 消息一样进入后续 LLM memory，使 Agent 能看到上一轮失败上下文。普通 JSON POST 尚未结束只表示 provider request future 仍在等待，不能伪装成已持久化失败。
 - 工具参数中的图片 ID 是由真实 object key 或图片地址计算的稳定 SHA-256 标识；真实 data key 仅存于 api-server 的工具上下文映射，所有图片工具在执行时查表恢复，不能把 object key 或图片地址作为 LLM 可见的工具 ID。
 - 规划 prompt 必须显式区分“规范展板”和“实际素材产出”：规范图、视觉规范图、风格规范图、素材规范展板、角色规范图等规范展板请求走 `generate-image`，并补齐统一视角、线条粗细、色卡、材质、阴影、圆角、状态层级、尺寸标注等要求；实际角色立绘才走 `generate-character`，多个图标素材 / 图集才走 `generate-icon-spritesheet`。
- 用户的当前消息确实在确认或取消一条已存在且仍为 pending 的工具调用时，画布 Agent 只引导使用该卡片的确认 / 取消按钮，本条确认 / 取消意图不产生新 tool call。这条边界必须使用“匹配 pending 调用时如何处理”的正向、条件化描述，不得改写成“不得重新发起相同工具调用”一类全局否定话术：实测中模型会把这类否定句过度泛化为拒绝后续新请求。已 cancelled 的卡片不再处理；用户明确要求修改、重做或发起新任务时必须允许新 tool call，pending 卡片也不阻塞无关的新请求。
+- 用户通过当前消息确认或取消已有工具调用时，Agent 先读取历史状态：pending 调用引导使用对应卡片的确认 / 取消按钮；cancelled 调用视为已结束。用户明确要求修改、重做或发起新任务时提交新 tool call。独立调用可并列存在，并在一次回答的 `tool_calls[]` 中尽量批量提交。图片 ID 从用户引用或历史工具结果的 system message 获取；上下文确实缺少对应图片时，请用户重新引用图片。
 - 画布 Agent 规划请求使用 Chat Completions 和 1024 生成 token 预算；VectorEngine 专用 client 发送 `max_completion_tokens`，预算包含可见输出与隐藏 reasoning token，不等于可见正文长度。发送后 120 秒是前端软提示阈值，不是 provider 失败 deadline：若普通 JSON POST 仍 pending，消息流临时显示“仍在处理中，请耐心等待”并继续等待，提示不写入 OSS 消息历史；连接或请求明确失败则立即按正式错误收口。provider 单 attempt 保留 8 分钟 hard timeout；请求发起阶段的 timeout、连接失败、`408`、`429` 与 `5xx` 读取 `GENARRATIVE_LLM_MAX_RETRIES`，但画布 Agent 最多重试 1 次，专用重试退避最多 60 秒。消息规划生命周期从 handler 入口开始计入 18 分钟总 deadline，进入 `agent.prompt(...)` 时使用扣除会话锁和上下文准备后的剩余预算；该 deadline 必须作为 runner 内部 deadline future 参与 completion await，并在每个 tool 开始前、返回后检查，不能用外层 `tokio::timeout` 丢弃整个 prompt future，也不能中途 drop 已开始的工具。工具一旦开始就等待其返回，再按 deadline 携带结果收口；当前八类画布工具只做同步参数校验并返回待确认，因此不会延长正式生成链。deadline 命中时仍按 `PromptRunError` 返回已经完成的工具结果、提交对应 staged memory 并追加终态错误。该 deadline 覆盖非法 JSON/工具校验失败触发的后续规划轮，并为错误持久化和 HTTP 返回保留约 2 分钟，不再让前端 20 分钟 transport timeout 先触发。已收到成功响应头后的响应体读取或解析失败直接按明确失败收口，错误计数/日志使用该响应所属的真实 attempt。规划重试发生在任何生成工具执行之前，不会重复提交生成任务或扣费；生成图片/编辑图片仍走对应生成工具和模型计费。
 - function-calling runner 必须把“等待用户确认”作为显式工具语义：当本批所有工具都校验成功并进入待确认状态时，立即以成功结果结束当前规划回合并持久化助手文本与待确认卡，不得继续依赖 LLM 自行停止；未知工具、参数错误、普通连续工具和不可解析响应仍受 `max_turns` 保护。
 - runner 失败必须返回显式的 `PromptRunError { error, partial_outputs }`，不得只返回终态错误而丢弃本轮已产生的文本或工具事实。prompt 执行使用 `AgentMemory::begin_staged` 创建行为等价且写入隔离的 `StagedAgentMemory` 事务，限长、摘要、脱敏等 append 规则必须在本轮 completion 前生效；成功或已发生工具活动时必须显式调用 `commit()`，直接 drop staged transaction 表示回滚，不得统一复制成 `VecMemory` 或仅替换 box 冒充持久化提交。本轮无工具活动失败时回滚 staged 用户消息、助手文本和不可解析响应；已有工具活动时在末尾追加 terminal error closure 后提交。外部 drop / abort 若尚无工具活动则回滚并保持原 committed memory；若工具已完成则提交结果与取消闭环，若工具仍在执行则提交“已启动、结果未知”事实与取消闭环，后续必须先 reconcile 再决定是否重试。
 - `ToolFailure` 必须以结构化工具失败输出暴露给 harness 调用方：调用方能读取 `kind`、`retryable`、`fatal` 和工具返回的原始 `output`；不得把它们压成单一错误字符串。这些字段只提供流程决策与诊断事实，是否重试、如何展示或持久化仍由业务调用方决定。
 - api-server 收到带 `partial_outputs` 的终态失败时，必须先按原顺序把其中已成功工具转成 `status=not_completed` 待确认消息并写入同一会话增量，再追加 `ERROR <错误内容>` 终态 system 消息；不得因后续轮次、其它工具或 `max_turns` 失败而吞掉已经执行并返回的工具结果。
- 通用 JSON function-calling 协议、工具 schema 注入、memory / hook、`max_turns` 和“全部工具待确认即结束回合”统一由现役 `platform-agent-harness` 承载；无工具时也必须输出同一 JSON 响应格式。画布角色 prompt、规范展板 / 已有图路由、模型与超时 profile、八类工具、计费、OSS 会话和 external job 编排继续留在 `platform-editor-agent` / `api-server`，不得回流已退役的旧 `platform-agent`。
+- 通用 JSON function-calling 协议、工具 schema 注入、memory / hook、`max_turns` 和“全部工具待确认即结束回合”统一由 `platform-agent-harness` 承载；纯文本回复使用相同 JSON 格式并设置 `tool_calls: []`，独立工具调用在同一批次提交并顺序执行。画布角色 prompt、规范展板 / 已有图路由、模型与超时 profile、八类工具、计费、OSS 会话和 external job 编排由 `platform-editor-agent` / `api-server` 承载。
+- 画布角色提示词、共享路由规则、工具与参数说明维护在 `server-rs/crates/platform-editor-agent/prompts/`；通用 JSON function-calling 提示词、工具条目模板与纠正消息维护在 `server-rs/crates/platform-agent-harness/prompts/`。Rust 使用 `include_str!` 编译包含正文，负责变量填充、schema 结构和执行校验。
 - **对话回合免费**（聊天、分析回复不扣泥点），仅 Agent 实际触发生成工具时按对应模型定价扣泥点。
 - 工具调用前后端校验泥点余额；不足时该次生成失败并在对话中以明确错误气泡告知，对话本身可继续。