合并 origin/master：Supervisor 永久退役，项目对话收敛为 DirectProject 与 Design Agent

- 解决 refactor/split-direct-project 与 origin/master 在 App.tsx、立项策划聊天视图、Direct composer/引用输入区、styles.css、Rust direct user item 与 appSurface 用例上的冲突，按「Supervisor 永久退役」口径保留 DirectProject 独立聊天容器与 Design Agent 两条产品路径 - 采纳 master 的策划 Agent V1/V2 退役：删除 GDD 审批卡、策划输入卡、planningLane、planningSessionV2、planningSessionContract、规划展示适配与 Rust planning_*_v2 命令、模块、契约及对应用例，不保留兼容别名或双跑路径 - 把 master「折叠思考显示单行预览」的目的落到当前结构：新增共享表现 chat/components/AgentReasoning/AgentReasoning.tsx（折叠态单行纯文本预览 + 箭头、展开态安全 Markdown），DirectProject 回合与策划回合共用，删掉两处写死的 pre 折叠实现 - 把 master「策划入口可选模型 / 推理档」的目的接到当前策划输入盒：复用 ConversationModelSelect 与 ComposerReasoningEffortSelect，配置写回仍走客户端配置通道 - App.tsx 删除只服务退役 Supervisor / 策划 V2 的 state、ref、effect、回调与死参数，并删除两条读路径都退役后的 workspaceProjectKind；openWorkspace 的工程类型入参保留为未使用契约 - Rust 侧保留本分支 canonical→wire 投影、无审计 Direct 回合与 direct user item 严格校验，并入 master 的 prepare_new_web_project_at 前置复核 - 更新 ADR 与 shared-memory 决策记录：策划当前只有 Design Agent、两条路径的共享表现清单，以及本次合并的口径、代价与验证证据 - 验证：AGC 与仓库 typecheck、check:encoding、check:doc-index、git diff --check、改动文件 eslint 0 error；AGC vitest 168 个文件中除 5 个 jsdom localStorage 环境失败文件与本分支既有 resourceTagStatsRefresh 失败外全绿，appSurface 198 passed / 13 skipped；Rust 定向用例 direct_codex_user_item、skill_pack、sessions 全过（整套分片在本容器受 /sbin -> usr/bin 触发沙箱预检失败，与本合并无关）
2026-09-21 21:09:34 +08:00
parent 4698527025 4d313a44eb
commit 6981648796
874 changed files with 118775 additions and 18421 deletions
@@ -0,0 +1,61 @@
+# 【实施计划】AGC 资源 kind Rust 枚举与 ts-rs 绑定
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC资源kind枚举化Rust绑定与内部收紧-2026-09-15.md` |
+| Status | complete |
+| Owner | Codex |
+
+## 修改边界
+
+允许修改：
+
+- `server-rs/crates/shared-contracts` 内 GameCreationApp 资源 kind 的独立 Rust 模块；
+- shared-contracts 的可选 ts-rs 绑定 feature；
+- ai-game-creator-shell 的 shared-contracts feature 引用和生成测试入口；
+- shell 内生成的 GameCreationApp kind TypeScript 文件；
+- 对应 Rust/TS 定向测试与文档 todo 证据。
+
+本切片已落地：
+
+- `GameCreationAppAssetManifestEntry.kind` 由 `String` 收紧为 `GameCreationAppAssetKind`：这是公开 Rust 类型的破坏性变更，按「不写历史兼容代码」直接改类型，不加兼容层、不做数据迁移；manifest 反序列化未知值收口为 `Unknown`。
+- 上传内容推断的字体写入 `Font`，未知上传类型写入 `Unknown`；图集切片 manifest 写入 `Icon`。
+- shell 内 manifest kind 的写入侧与读取侧统一为正式枚举成员：资源登记、字体导入、direct runtime 产物、平台美术登记与恢复、manifest 必填校验、资源编辑派生、UI 设计桥接与工作流。
+- 资源编辑请求的 `sourceSubtype` 只传正式枚举成员；资源编辑内部源身份拆成「正式 kind / 项目版本 / Agent 回执」三类，项目版本与 Agent 回执不再冒充 manifest kind。
+- ts-rs 绑定改由 `cargo test export_bindings` 生成：枚举自带 `#[ts(export, export_to = …/src/contracts/generated/)]`；退役的 `BindingDTO` / `BindingChange` 不再导出，手写的 `exports_ui_editor_types` 已删除。
+- `packages/shared/src/contracts/generated/` 作为受控生成目录在 `.prettierrc.json` 中使用与 ts-rs 原始输出一致的格式选项，并在 `.gitattributes` 标记为 `linguist-generated`；生成文件仍参与 Prettier/ESLint 检查，`cargo test export_bindings` 可幂等复现且不再污染工作树。
+- `Unknown` 表示解析边界无法判定的输入；写入方可以保留该结果，但必须明确决定拒绝写入或交由后续归类，不得把它误写成某个具体 kind。
+- shell TS 资源引用边界消费生成绑定，资源 kind 集合从生成的 union 穷举派生，并为未知值保留原始值与上下文日志。
+- api-server 图片快速编辑来源校验改为严格解析 `GameCreationAppAssetKind`，只允许共享枚举的静态图片成员；删除原有 legacy/兼容字符串白名单，退役值不再放行。
+
+明确不修改：
+
+- `category`、`mediaType`、`source.kind`、`source.generationKind`；
+- api-server 的其他资源 taxonomy、SpacetimeDB schema、OpenAPI；本切片只改图片快速编辑的 GameCreationApp manifest 来源校验。
+- shared-contracts 的 canonical alias 表与读时自愈：alias 表已删除，严格解析和 `Unknown` 口径保持不变；
+- `packages/shared` 中重复的资源 kind 手写契约与其余前端裸 `string` 字段（后续切片）。
+
+## 实现顺序
+
+1. 新建独立 kind 模块，定义当前正式成员：17 个现有 canonical kind + `font` + `Unknown`，serde 使用 kebab-case。
+2. 为 enum 增加可选 ts-rs derive，默认 shared-contracts 构建不引入 ts-rs。
+3. 让 shell 的 shared-contracts 依赖打开绑定 feature；生成目录 2026-09-17 起收敛到 `packages/shared/src/contracts/generated/`（kind 是跨端契约，不再放 shell 私有目录）。
+4. 增加 Rust serde round-trip 与 Unknown 解析/序列化测试；TS 侧不再手写生成值集合，改为从生成 union 穷举派生。
+  未知值通过 `parse_with_context` 收口到 `Unknown`，并把原始值与解析上下文交给壳层注册的 `app_log!` 回调（2026-09-17 起不再用 `tracing` / `kind-observability`）。
+5. 运行 shared-contracts 与 shell 定向测试，并用 `export_bindings` 复现生成文件；完成后将稳定结论回写里程碑并关闭本计划。
+
+## 验证命令
+
+1. `cargo fmt --all -- --check`
+2. `cargo test --locked -p shared-contracts game_creation_app --manifest-path server-rs/Cargo.toml`
+3. `cargo test --locked -p shared-contracts --features ts-bindings export_bindings --manifest-path server-rs/Cargo.toml`（生成 `packages/shared/src/contracts/generated/GameCreationAppAssetKind.ts`）
+4. `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml export_bindings`（生成 shell 自己的 ts-rs 绑定）
+5. `npx vitest run apps/ai-game-creator-shell/tests/assetKind.test.ts packages/shared/src/contracts/gameCreationApp.test.ts`（解析 Rust 源码的 `assetKindCanonicalMapping.test.ts` 2026-09-17 已删除：手写词汇表被移除后它没有比对对象）
+6. `npm run check:encoding`
+7. `git diff --check`
+
+## 风险与回滚点
+
+- 风险：ts-rs 默认生成 enum/union 形态与 serde rename 不一致；必须以生成文件和 round-trip 测试为准。
+- 风险：shared-contracts 被 SpacetimeDB/WASM 使用；ts-rs 必须是 optional feature，默认构建不可依赖。
+- 回滚点：本切片仅新增 enum/绑定，不改变现有 manifest JSON 解析；若生成链路不稳定，可回滚本提交而不影响现有业务。
@@ -0,0 +1,43 @@
+# 【实施计划】AGC 资源 kind 词汇审计与绑定架构
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC资源kind枚举化词汇审计与绑定架构-2026-09-15.md` |
+| Status | complete |
+| Owner | Codex |
+
+## 修改边界
+
+允许修改：
+
+- 主规范中的资源 kind 当前口径；
+- `docs/project-memory/plans/` 下本任务的里程碑/实施计划；
+- `docs/project-memory/todos/` 下本任务的扫描清单；
+- 为审计提供只读扫描脚本（如确有必要，脚本也只覆盖 shell）。
+
+明确不修改：
+
+- 已完成的 `apps/ai-game-creator-shell` 业务收口不再属于未决范围；后续只允许按新里程碑变更；
+- server-side 代码、OpenAPI、SpacetimeDB schema；
+- MIME、`source.kind`、`generationKind` 和其他字符串领域。
+
+## 实现顺序
+
+1. 按“manifest asset kind / 其他字段 / 仅文本同名”三类扫描 shell 的 `kind`、`assetKind`、`asset_kind` 和 manifest 构造器。
+2. 对每个候选值回到调用上下文，标记生产写入、读取投影、协议输入、测试 fixture 或纯文本/路径。
+3. 对照 api-server 当前有效资源 kind，排除 legacy、billing/storage synthetic taxonomy 和开放字段。
+4. 记录正式候选 enum、Unknown 输入行为、保留字符串字段和后续 PR 边界。
+5. 形成下一里程碑的文件级修改顺序和验证矩阵；本里程碑结束后暂停，等待验收。
+
+## 验证命令
+
+1. `rg -n 'kind|assetKind|asset_kind' apps/ai-game-creator-shell/src apps/ai-game-creator-shell/src-tauri/src`
+2. `npm run check:doc-index`
+3. `npm run check:encoding`
+4. `git diff --check`
+
+## 风险与回滚点
+
+- 风险：同一字符串可能是 manifest kind、workflow kind 或路径名；任何未回到上下文确认的替换都禁止进入代码。
+- 风险：shared-contracts 被多个 server crate 使用；ts-rs 生成必须通过 feature/独立入口隔离默认构建。
+- 回滚点：本里程碑只有文档和审计清单变更；若词汇边界未能闭合，删除本计划和 todo，不进入代码里程碑。
@@ -0,0 +1,51 @@
+# 【实施计划】AGC 音频生成进入后台任务账本
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC音频生成进入后台任务账本-2026-09-20.md` |
+| Status | implemented-awaiting-runtime-acceptance |
+| Owner | 主 Agent（自审；本运行没有独立评审人） |
+
+## 修改边界
+
+- 允许修改：
+  - 主规范：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（§3.10 / §7.9）、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`。
+  - AGC 原生：`apps/ai-game-creator-shell/src-tauri/src/asset_generation_tasks.rs`、`commands.rs`、`project.rs`、`project/resource_editor.rs`（仅新增收口入口，不改既有派生语义）。
+  - AGC 前端：`apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasAssetGenerationTaskModel.ts`、`resourceCanvasAssetGenerationQueue.ts`、`view/project-development/index.tsx`。
+  - 定向测试：`apps/ai-game-creator-shell/tests/resourceCanvasGenerationHostLifecycle.test.tsx`、`resourceCanvasAssetGenerationQueue.test.ts`、`appSurface/project-development.suite.ts`（仅音频相关断言）。
+- 明确不修改：`/api/editor/audios/*/generations` 与 `/api/external/v1` 路由、请求体、OpenAPI、共享 DTO、SpacetimeDB schema、权限命令词汇、`derive_local_project_resource` 的同步语义与其既有无源生成入参校验。
+
+## 实现顺序
+
+1. 主规范：把音频入口的接线口径从「同步无源生成」改写为「与图片类同一条后台任务账本」，并补上音频提交载荷、失败重开与幂等条款（PRD §3.10 / §7.9，AGC 工具栏入口矩阵文档）。
+2. 原生：在资源编辑模块新增音频入参收口与「后台跑一次音频派生」的入口（复用既有派生实现，不复制生成逻辑）；在 `asset_generation_tasks` 里按 `kind` 分流，音频任务复用同一份账本、同一套阶段文案与中断收口；`start_local_project_asset_generation` 增加可选幂等键入参，音频 kind 走新分支且不改图片类载荷口径。
+3. 原生测试：音频任务入参收口（kind / 提示词上限 / 幂等键 / 未知 kind 拒绝）、账本记录 kind 为音频、图像载荷口径不回归。
+4. 前端模型与队列：任务模型支持音频任务（kind、请求身份、无比例 / 尺寸 / 参考字段），音频 kind 的入口文案从工具栏模型派生；队列按 kind 分流派发同一命令的音频载荷，其余排队与轮询语义不变。
+5. 前端宿主：音频提交改为「入队即返回」，占位绑定任务 id、自动展开侧栏、给出提示条；收口复用既有「配对读 + 落卡」链路，未受理失败按原请求身份重开音频面板。
+6. 前端测试：宿主生命周期（提交即关闭、侧栏可见、落卡、未受理失败重开并复用身份）、队列音频分支（载荷与轮询、第二条本地排队不发 IPC）、appSurface 音频载荷。
+7. 验证与证据矩阵：跑定向测试、类型检查、编码 / 文档索引 / `git diff --check`，按里程碑逐条填写证据。
+
+## 验证命令
+
+1. `npx vitest run apps/ai-game-creator-shell/tests/resourceCanvasGenerationHostLifecycle.test.tsx apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationQueue.test.ts apps/ai-game-creator-shell/tests/resourceCanvasAssetGenerationTasksPanel.test.tsx`
+2. `npx vitest run apps/ai-game-creator-shell/tests/appSurface.test.ts`
+3. `cargo test -p genarrative-ai-game-creator-shell asset_generation_task`
+4. `npm run agc:typecheck`（或 `npm run typecheck --workspace @genarrative/ai-game-creator-shell`）
+5. `npm run check:encoding && npm run check:doc-index && git diff --check`
+
+## 执行结果
+
+1. 主规范：PRD（§3.10 / §7.9 / §7.9 第 8~9 条）与 AGC 工具栏入口矩阵文档改为「音频与图片类同一条后台任务账本」，同步 `【测试用例】AGC资源工作台V3端到端验收` 的 S11a 判据。
+2. 原生：`prepare_local_project_audio_generation`（提交期收口）+ `run_local_project_audio_generation_at`（派发时刻读 revision，复用派生实现），`start_local_project_asset_generation` 新增可选 `idempotencyKey` 并在音频 kind 分支落同一份账本、由 `run_local_project_audio_generation_task` 写 running → completed / failed；图片类分支逐字未改。
+3. 前端：任务模型新增音频任务与 `idempotencyKey`（恢复出来的历史任务不带它，也不承接重试）；队列按 kind 分流派发载荷；面板提交改为同步返回并立即关闭；宿主改为同步入队 + 失败重开。
+4. 测试：面板（点击即关闭、无阶段文案与在途按钮）、队列（音频载荷逐字）、宿主生命周期（提交关闭 / 侧栏 / 落卡 / 未受理重开 / 受理后不重开 / 重试身份复用 / 失败态按占位隔离）、appSurface 音频载荷。
+5. 验证命令与结果：9 个定向 vitest 文件 73 项通过；`appSurface.test.ts` 552 项通过（17 项跳过）；`cargo test asset_generation_task` 14 项通过；`npm run agc:typecheck`、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check` 通过。
+6. 与预期不一致处：音频任务不再携带 `targetCategory`（原生音频通道不消费它，前端也没有读它的地方）；`restored` 任务无幂等键，只用于展示与定位，不承接重试。
+7. 已知与本任务无关的既有失败：`clientAuthStorage` / `clientApi` / `clientHttp` / `chatPromptPolish` / `projectCreationDirectory` 五个文件在本机 Node v26 + vitest 0.34 的 jsdom 下 `localStorage` 为 undefined（在干净工作区同样失败）；`cargo test resource_edit` 整组过滤下有 5 项既有并行干扰失败（单跑通过）。
+
+## 风险与回滚点
+
+- 音频任务与图片类任务共用队列：若音频任务未终态会挡住后续派发（本地排队是既有语义，接受）。回滚点是前端提交分支与原生 `kind` 分流，各自可独立回退。
+- 音频自带的 operation 幂等账本与任务账本是两层身份：任务 id 取 operation id，重试复用同一对 operation / 幂等键；不得为「省事」在重试时换新的请求身份（那是一次新的付费生成）。
+- 账本 `kind` 为音频时，`restore` 的入口文案若查不到工具栏模型会退化成素材名：入口文案必须由工具栏模型派生，避免恢复后文案漂移。
+- 后台跑生成会让「项目 revision CAS」窗口从提交前移到派发时刻：冲突时按失败收口（不静默重试），避免把生成写到非预期基线。
@@ -0,0 +1,68 @@
+# AGC 项目创建目录可选实施计划
+
+Version: 1.0
+Status: active
+Date: 2026-09-17
+Related Spec: `docs/technical/【技术方案】AGC模板库与模板建项-2026-09-17.md`、`docs/【技术方案】AGC异步操作可恢复闭环-2026-09-14.md`
+
+## 目标
+
+让用户在 AGC 里能自己选项目创建目录：首页「做游戏 / 做方案」自动建项与模板库「使用模板」建项都落在用户选定的目录下；不选时保持 AGC 管理的默认位置（`<app_data>/projects`），行为与现状一致。
+
+## 交接结果
+
+- `create_automatic_local_game_project`、`create_automatic_local_game_project_from_template` 新增可选参数 `projectsRoot`；为空时由 Rust 侧回落到默认目录。
+- `pick_local_project_directory` 新增可选参数 `title`（只接受短标题，其余回退「选择游戏项目目录」）。
+- 新增用户偏好「项目创建目录」：`localStorage` 键 `genarrative-ai-game-creator.project-creation-directory.v1`。
+- 入口在客户端设置里：侧边栏「配置」→ 设置分类「工作区」；`RuntimeConfigDialog` 内用 `useProjectCreationDirectory` 展示与改选目录，不经过首页或模板库页头。
+- 首页「做游戏 / 做方案」与模板库「使用模板」建项时读取同一份偏好，用户不需要在建项前再选一次。
+
+## 行为契约
+
+- 允许的来源只有一个：本机原生目录选择器（`pick_local_project_directory`）。它返回的目录已在选择时按 user-selected 范围做过一次加固，构成「用户显式选择」边界。
+- Rust 侧 `validate_requested_game_project_creation_root` 对传入目录要求：非空、绝对路径、无控制字符、已存在的普通目录（符号链接 / Windows reparse point / 普通文件一律拒绝），并通过 `prepare_game_creator_project_root_for_read`（user-selected 范围的一次性修复）。目录不存在时不代为创建，直接失败。
+- 建出的项目目录仍在所选目录下按 `gameagent-<8位短ID>` 命名，项目名、`.agent` 初始化、首轮投递与既有自动建项完全一致。
+- 偏好只保存「用户意图」，不是授权凭据：存储被外部改动最坏只是回退默认位置或一次可见的建项失败，不会跳过 Rust 门禁。
+- 该偏好是客户端本地设置，不写入 `read_game_creator_app_config` / 保存设置的那份运行时配置：在「工作区」里选择目录当场生效，与「保存设置」按钮无关。
+- 「恢复默认位置」清空偏好即回到应用数据目录；既有项目不迁移。
+
+## 步骤
+
+1. **Rust 建项入口**
+   - `commands.rs`：新增 `validate_requested_game_project_creation_root` / `resolve_game_project_creation_root`，`create_automatic_local_game_project` 接受 `projects_root`；`pick_local_project_directory` 接受 `title`。
+   - `template_library.rs`：模板建项复用同一解析函数。
+   - 交付：两条定向单测（校验矩阵、在指定创建目录下建项）。
+   - 验收：`cargo test --bin genarrative-ai-game-creator-shell creation_root` 全绿。
+
+2. **前端偏好与入口**
+   - `features/app-shell/model.ts`：`normalizeProjectCreationDirectory` / `readProjectCreationDirectory` / `writeProjectCreationDirectory` / `projectCreationDirectoryLabel`。
+   - `useProjectCreationDirectory`：选择目录、恢复默认、状态文案（失败在设置页字段内可见）。
+   - `RuntimeConfigDialog` 新增「工作区」设置分类，承载「项目创建目录」字段与「选择目录 / 恢复默认位置」动作。
+   - `useHomeProjectCreation` 与 `useTemplateLibrary` 在建项时带上 `projectsRoot`。
+   - 交付：偏好模型 4 项单测、设置页 1 项交互测试、appSurface 1 项「设置里选目录后建项」端到端场景。
+   - 验收：`npx vitest run apps/ai-game-creator-shell/tests/projectCreationDirectory.test.ts apps/ai-game-creator-shell/tests/appSurface.test.ts` 全绿。
+
+3. **文档与共享记忆**
+   - 本实施计划；模板库技术方案的命令表补 `projectsRoot`；`decision-log.md` 记录偏好键与命令参数；`pitfalls.md` 说明用户自选目录与 AGC 管理目录的关系。
+   - 验收：`node scripts/check-doc-index.mjs` 通过。
+
+## 验证命令
+
+```bash
+cargo check --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell creation_root
+cargo test --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell template_library
+cd apps/ai-game-creator-shell && npx tsc -p tsconfig.json --noEmit
+npx vitest run apps/ai-game-creator-shell/tests
+npm run check:encoding
+node scripts/check-doc-index.mjs
+git diff --check
+```
+
+手动验收（客户端内）：侧边栏「配置」→「工作区」→「选择目录」选 `F:\Projects\我的游戏`，回首页建项后项目目录应为 `F:\Projects\我的游戏\gameagent-<8位>`；模板库「使用模板」建项同样落在该目录；点「恢复默认位置」后再建项回到应用数据目录。
+
+## 风险与回退
+
+- **自选目录无法加固**：`Documents` 等带受保护继承 ACL 的位置可能加固失败。失败发生在选择器或建项前置校验阶段，报错可见且不会留下半成品项目；用户改选其它目录或用默认位置即可。
+- **偏好漂移**：偏好只是提示值，每次建项都会重新校验；存储被改坏不会绕过门禁。
+- **回退**：删掉偏好键（或点「恢复默认位置」）即回到默认目录；需要彻底移除该能力时，去掉两个命令的可选参数与设置页字段即可，Rust 默认路径逻辑不变。
@@ -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,14 @@
+# Mac 本机构建节点接入实施计划
+
+- Version: 1
+- Status: preparing-network-required
+- Date: 2026-09-18
+- Parent Spec: `【里程碑】Mac本机构建节点接入-2026-09-18.md`
+
+1. 本地准备 universal 依赖预备、CI 打包脚本和 Jenkinsfile，运行离线单测、配置门禁及编码检查。
+2. 恢复内网后只读核对 Jenkins 版本、既有节点/Job、Git 凭据标识与插件；已存在对象优先核对，不重复创建。
+3. 从同一控制器取得 agent.jar，以当前已有 Java 21 运行专用 inbound Agent；secret 保存在用户私有目录，LaunchAgent 参数只引用 secret 文件，不保存控制器 API Token。
+4. 建立单 executor、EXCLUSIVE 的专用 Mac 节点与手动 archive-only Job。源码必须是可追溯 Git 提交，未推送改动需另行确认源码交付方式，不能默认推送。
+5. 初次构建核对独立工作目录、空间、目标与依赖；在 Jenkins 实际 SUCCESS 后确认 DMG、SHA-256 和两架构 smoke 证据。
+
+失败边界：网络不可达不启动重试服务；节点/Job 修改前保留原配置；不更改其它节点、Job 或调度。禁止把 CLI 日志、认证文件和私有路径提交 Git。未获得真实 SUCCESS 前保留活动计划。
@@ -0,0 +1,16 @@
+# Mac 通用安装包实施计划
+
+- Version: 1
+- Status: awaiting-user-acceptance
+- Date: 2026-09-18
+- Parent Spec: `【里程碑】Mac通用安装包与构建管线-2026-09-18.md`
+
+1. 等待当前 Intel 编译结束，避免共用 staging 并发写。
+2. macOS build.rs 按白名单分别 stage 两套原生资源；共享 Layout 使用架构子目录，运行时原有 hash/版本校验不变。
+3. Tauri macOS 映射双目录，发布入口接受 universal 并生成两个清单键；更新配置门禁与定向测试。
+4. 安装包 smoke 支持显式选择主程序切片，验证 universal 主程序与该切片对应原生依赖。
+5. 用 Tauri universal 构建 app，分别做 arm64/Rosetta smoke，hdiutil 生成新 universal DMG，校验并交付。
+
+不发布、不使用私钥；依赖仅从锁定 npm tarball 下载并对照 lockfile integrity。磁盘不足停止，不擅自删除其它 target/cache。保留单架构 DMG。Jenkins 配置作为后续门禁，不混入本地包构建。
+
+本地构建与双架构隔离验证完成，证据见对应里程碑。更新 master 时先停止旧构建，保护并恢复改动后重建；未进行 Jenkins 写操作，待确认 Mac Agent 再制定管线实施计划。
@@ -0,0 +1,51 @@
+# 【实施计划】UI设计文档引用代码上下文
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1 |
+| Status | ready |
+| Owner | Codex |
+| Milestone | `docs/project-memory/plans/【里程碑】UI设计文档引用代码上下文-2026-09-14.md` |
+
+## 修改边界
+
+允许修改：
+
+- UI Editor persistence/resource bridge/workflow/command 中的 UI JSON 文档 kind 常量与校验。
+- `packages/shared` 的 canonical kind 与 Rust 对应映射。
+- `agent/direct_codex_user_item/wire.rs` 的 UI 引用 prompt 生成。
+- 相关 Rust、TypeScript 测试和当前 UI workflow/AGC 文档。
+- `decision-log.md` 的长期决策记录。
+
+明确不修改：
+
+- `ui-prototype` 图片生成和图片 workflow 语义。
+- UI State schema、`render_ui_design_state_js` 输出格式和 `ui/generated-*.js` 路径规则。
+- SpacetimeDB schema、External v1 OpenAPI、非 Direct Codex Supervisor 引用行为。
+- 用户已有 `.env` 未提交修改。
+
+## 实现顺序
+
+1. 更新 UI workflow 主规范与项目决策，明确 `ui-design-doc` 与 `ui-prototype` 的身份边界。
+2. 在 persistence 提取并导出 UI 文档 kind/media 常量，替换 Rust UI 文档校验。
+3. 同步所有 UI JSON 资源生产者、workflow 校验、命令筛选、shared contract 与前端 bridge。
+4. 在 Direct Codex 引用渲染中调用 `generate_ui_design_code_at`；成功追加生成文件相对路径，失败追加原始错误并继续发送。
+5. 补充旧 kind、图片、成功、文档错误、多引用和 renderer 输出的测试。
+6. 执行定向验证，复核 diff 中无 fallback、迁移或无关 `.env` 修改。
+
+## 验证命令
+
+1. `cargo fmt --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -- --check`
+2. `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml ui_editor::persistence`
+3. `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml direct_codex_user_item`
+4. 相关 shared contract Vitest 测试与前端类型检查
+5. `npm run check:doc-index`
+6. `npm run check:encoding`
+7. `git diff --check`
+
+## 风险与回滚点
+
+- `ui-prototype` 与 UI JSON 文档共用部分分类展示逻辑，需确保分类映射不会让图片进入文档分支。
+- `generate_ui_design_code_at` 会持有项目写锁；多引用必须顺序调用，不能并行写同一项目。
+- 生成失败继续发送是已确认语义；测试必须证明错误文本进入 prompt 而不是被转成聊天失败。
+- 若发现生产者仍写入旧 `UI`，按开发阶段合同直接修生产者和 fixture，不增加运行时兼容分支。
@@ -0,0 +1,34 @@
+# 【实施计划】多选素材批量标签
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | docs/project-memory/plans/【里程碑】多选素材批量标签-2026-09-17.md |
+| Status | implemented-awaiting-runtime-acceptance |
+| Owner | 主 Agent 集成；deepseek-flash 实现和独立 review |
+
+## 修改边界
+
+- 原生：`project/manifest` 标签批量追加函数和 DTO、`commands.rs` 权限门面、`main.rs` 注册、分类测试。沿用项目写锁、manifest mutation、审计和 revision，不新建状态系统。
+- 前端：扩展现有 `ResourceClassificationPanel` 为单/批量模式，复用已有字段与 pill；`ResourceCanvasPanelView` 增加可选批量标签动作；工作台冻结选择并用完整返回条目更新。前端不得逐素材循环写回。
+- 并行采用不重叠文件集：原生 agent 只写 Rust，前端 agent 只写 TS/TSX/CSS/前端测试；主 Agent 负责文档与集成，禁止跨区提交别人文件。
+
+## 顺序与检查点
+
+规范经独立 deepseek-flash 评审通过；批量输入仅追加草稿，面板动作行直接增加入口，返回顺序、去重上限、no-op revision 和未知字段拒绝已在主规范明确。
+
+1. 规范独立评审，确定命令与错误语义。
+2. 前后端并行实现，均在明确工作区局部修改、自审和定向验证。
+3. 集成后独立 review，再按有效发现返修；不因测试方便而扩产品范围。
+4. 本地中文提交、报告已验证和待真机事项；远程操作留待用户后续确认。
+
+## 验证
+
+`npm test -- <相关测试>`、AGC 类型检查、目标文件 ESLint、原生 classification 相关测试、`npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。依赖复用时使用本工作树忽略目录的隔离配置，避免修改主目录依赖。
+
+## 风险与回滚
+
+批量写不能掩盖部分失败；类型字段不能借标签保存被读时自愈值覆盖。单素材编辑与多素材追加保留明确分支，不重构其它菜单动作；本地独立提交可回退新需求，保留主线合并及既有画布工作。
+
+## 下一验收入口
+
+在已登记素材上分别从画布多选工具栏与资源面板进入批量标签，确认新增标签、原标签保留、刷新后持久化与跨项目切换。真实客户端验收通过后，将持久行为保留在主规范，删除本实施计划与里程碑；远程推送与 CI 等用户恢复安排，不自行启动。
@@ -0,0 +1,51 @@
+# 【实施计划】对话总耗时与动态工具计时
+
+| 字段 | 值 |
+| --- | --- |
+| Status | implemented-awaiting-runtime-acceptance |
+| Milestone | docs/project-memory/plans/【里程碑】对话总耗时与动态工具计时-2026-09-18.md |
+
+## 修改边界与顺序
+
+1. 独立评审主规范与里程碑后进入实现。当前问题是工具组窗口、整轮范围和运行快照混用；不能只把 setInterval 从 1000 改成 100。
+2. 原生在现有生命周期事件上提供阶段时间：`turn.started` / `turn.completed` 的事件级 `at`，以及 `item.started` / `item.completed` 的事件级 `at`，不是更改条目嵌套的 `item.at`。工具计时只消费阶段事件时间，嵌套 `item.at` 继续承载条目展示时间，不当作真实开始/完成。开始/完成事件优先读取对应上游阶段字段或时长，缺失时在宿主事件产生时取钟。TypeScript 可选数值字段处理既有历史/无时间夹具，真实宿主始终提供时间；ts-rs 生成绑定，按仓库 u64→number 约定处理，不手改。
+3. 前端事件 reducer 保留工具开始、完成边界以及本轮终态时间；完成边界可附在本轮聊天条目展示元数据上，沿用现有用户条目划分回合，不新增 turnId 或第二套生命周期。无时间旧历史不编造准确总耗时。
+   - 整轮起点：该轮用户消息的实际发送时间优先，缺失才取 `turn.started.at`；与用户要求的“发送到完成”一致，不能改为第一条工具的起点。终点只取明确终态事件，不能取最后一条正文的创建时间或最后工具更新时间。
+   - 只有完成没有开始事件的工具隐藏未知耗时；缺失、0、非有限或倒序边界隐藏，正常运行的零时长显示 `0.0`。
+4. 回合状态/小结消费整轮起止时间，各工具块仅消费本组工具阶段时间，以局部有界的 100ms 时钟驱动展示，不把整棵 App 状态每 100ms 重建。只在该层有运行中计时目标时订阅，结束/切项目/卸载清理。
+5. 测试先覆盖静止事件输入下推进时钟、工具完成但回合仍运行、终态与重复事件；补阶段字段与回放时间测试。独立 review 后主 Agent 核对并返修。
+6. 同视图的追加局部修复：初始消息占位判定应读取实际 Direct 用户条目/乐观用户条目和分页状态，不只检查旧 conversationMessages；增加正式气泡只出现一次、合法同文消息不被去重的回归。
+
+## 并行写入边界
+
+- 原生实现者：`src-tauri/src/agent/direct_thread_wire.rs`、`codex_app_server/mod.rs`、必要的 `direct_thread_manager.rs` 模式匹配/测试及 ts-rs 生成绑定。
+- 前端实现者：`directThreadChat.ts`、`directThreadItemProjection.ts`、`directTurnPresentation.ts`、`ToolCallGroup.tsx`、`toolCallGroupPresentation.ts`、`ProjectSupervisorView.tsx`、必要的 App 接线与对应测试。不得修改原生或生成绑定。
+- 主 Agent：文档、集成验证、独立 review 决策与浏览器 smoke；不得覆盖其他人的未提交文件。
+
+## 验证与风险
+
+前端使用已有 `.app/merge-deps` 隔离配置，不修改共享 node_modules。运行定向 Vitest、AGC 类型/skill/config 检查、Rust wire/manager 相关测试与 all-targets offline check、编码/文档索引/diff 检查。历史缺少完整时间时隐藏无法证明的用时，不迁移历史文件。原生协议变更需重新启动客户端才能生效，不擅自重启用户正在运行的回合。
+
+回滚点为本次改动前的 `1bd153d7f`；若失败只回退本次文件变更，不动用户锁文件和其它分支。
+
+## 收口
+
+已完成本轮实现、独立 review 返修与自动化/模拟浏览器验证，证据见对应里程碑。用户已授权更新 Issue/PR 并推送当前功能分支；不得据此合并 PR、发布或恢复定时任务。真实客户端端到端验收尚待完成，因此保留计划，卡片全面重设计和画布内任务浮层不计入本轮已交付内容。
+
+## PR 补审返修（2026-09-18）
+
+### 用户截图澄清：工具组必须独立计时
+
+上一版把整轮总耗时复用到各组，导致已完成的前组仍显示进行中并与后组同步增长。按最新主规范返修：整轮总耗时留在回合状态/小结一处；ToolCallGroup 只消费自身 calls 的阶段边界，显示“本组用时”，完成组停止 ticker，运行组与内部运行工具按 100ms 更新。删除不再使用的回合时间 props，更新原先锁定“各组相同总耗时”的错误测试，补前组已完成/后组运行、LLM 仍运行、并行、缺失/倒序边界与独立冻结回归。此为用户明确修正表现语义，不改变原生生命周期或真实发送时间修复。
+
+已完成并经独立复核：组内每条原始时间边界先校验再聚合，防止单条倒序被其他工具或舍入掩盖。Edge 真实浏览器中前组固定 5.0 秒且无进行中，后组从 2.1 秒增长至 3.0 秒、完成后固定；整轮总耗时仅在回合状态/小结显示。合入主线 `b137f1759` 后 appSurface 463 项通过、17 项跳过，聊天/插件 45 项及发布构建脚本 27 项通过，Rust all-targets check 通过。全量中曾有一条精确用时断言依赖等待 IPC 后重新取 Date.now，已改为读取同身份用户气泡真实发送时间，单独回归通过，不放宽断言。
+
+用户确认修复补审发现：保留同身份乐观消息的真实发送时间；live 为空时仍向明确的本轮用户条目保存终态边界。先补失败回归，再最小修改原 reducer/回合投影与必要的 App 接线，不新增持久化 schema 或平行回合状态源。取消后迟到终态只补可验证测试，不能仅凭时间大小改变现役事件顺序合同。独立复核后运行定向与集成验证。本次 fix 不自动授权新的远程写入。
+
+补审返修中已复现 bootstrap 只有生命周期事件、用户消息经 history slice 回读且 live 恒为空的缺口。前端无法证明归属，因此批准原生在 turn.started/turn.completed 上透传现有用户条目 userItemId；沿用原事件与已有消息身份，不另造 turnId。前端按精确 itemId 补时间边界，移除按历史尾项或时间戳相等猜测用户归属的兜底；完成先于历史到达时，在历史回读后同样按该身份补齐。原生与 TypeScript 绑定同批更新并验证重放。
+
+### 返修结果
+
+已完成同身份发送时间保留、原生 userItemId 关联、live 为空或终态先于历史时的精确回填；旧回合终态及取消回包不能关闭另一条已知身份的新请求。计时 40 项定向、appSurface 462 项（17 跳过）通过，原生身份序列化/重放/取消用例 3 项及原阶段时间序列化 1 项通过；绑定由 ts-rs 导出，Rust all-targets locked offline check 通过。
+
+Edge 真实浏览器使用生产 reducer/组件和模拟原生事件，确认发送后的 8 秒启动等待计入总耗时、100ms 递增及终态冻结；仅历史恢复、live 为空的回合显示正确的 2.0 秒。真实 Provider 与原生客户端端到端尚未验证，不据本地通过宣称远程 CI 或发布通过。
@@ -0,0 +1,50 @@
+# 【实施计划】画布验收问题统一修复
+
+## PR 补审返修（2026-09-18）
+
+用户确认修复：生成面板按 draftId 隔离且切换保留各草稿；失败重试保留失效参考身份并在提交前明确拒绝，不改变原付费请求；不同栏目整理意图分别排队；多选拖动预览和写回统一使用按下时起点。每项先加失败回归，再最小修复、独立复核与集成验证。共用 index.tsx 时限定不重叠区域，禁止整文件重写。卡片重设计、任务浮层和远程写入不在这次 fix 范围。
+
+返修已完成：生成占位实例与草稿隔离、失效参考及原请求输入修改阻断、队尾同范围整理合并、场景预览与局部写回分别冻结同一按下时基准。生成/布局/计时合计 17 文件 213 项定向通过；appSurface 462 项通过、17 项跳过。音频失败后切换导致草稿丢失的集成回归也已修复并重跑通过，没有删断言或加任意等待。
+
+独立交叉 review 无新增阻断；浏览器使用真实工作台和模拟原生接口确认 BGM/音效以及同类图片的不同占位输入隔离、切回恢复原输入。未发起真实付费生成、未运行真实 IPC 端到端；不同栏目排队整理的乐观中间态仍可能短暂回退，最终落盘范围与顺序正确，该既有表现未纳入本次返修。
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | docs/project-memory/plans/【里程碑】画布验收问题统一修复-2026-09-17.md |
+| Status | implemented-awaiting-runtime-acceptance |
+| Owner | 主 Agent 集成，deepseek-flash 实现与独立评审 |
+
+## 修改边界与顺序
+
+1. 规范独立评审通过后，在同一里程碑内并行四个 worktree。
+2. 生成工作区负责生成面板、任务占位、引用和工作台入口接线；原生引用工作区独立负责 Rust 入参、账号绑定、生成请求与恢复校验。两者以可选 `referenceAssetIds` / `reference_asset_ids`（当前 manifest 的 asset.id 列表）作为接缝，避免 UI 等待原生实现。
+3. 展示工作区负责卡片名称/文档图标、预览表现与对应测试，不修改工作台入口及画布手势。
+4. 布局工作区负责共享画布多选拖动、布局保存/整理/撤销及测试；工作台入口仅允许布局接线局部变更，集成时人工检查与生成工作区的冲突。
+5. 每个实现者先自审、运行定向验证、本地中文提交并报告文件列表；主 Agent 逐项核对后集成，再由独立 Agent 先写评审计划、理解全流程、由局部到整体只读 review。
+6. 主 Agent 复核问题并指派有效问题返修，重新验证后交付。远程写入另行确认。
+
+## 评审补充与接缝所有权
+
+- 参考选择复用当前资源引用选择组件，原生命令新增可选引用 ID 列表，解析为当前项目已登记图片，复用当前账号 external editor binding；平台请求消费现有 `referenceImageSrcs`，不修改远端 API 合同。复用 durable 已有引用快照及指纹，核对并修复仍硬编码为空或单引用的恢复校验，不无端扩展账本 schema，补 Rust 测试；对账复用 `list_local_project_asset_generations`（以源码实际命名为准）及 manifest，不新造账本。
+- 主规范已固定草稿/任务身份、切换恢复、整理集合、历史粒度、手动标记及名称字段来源。真实 Provider smoke 有费用与环境前置，不默认触发付费生成。
+- index.tsx 的 ResourceCard 组件体、名称/图标相关 import 属展示实现者；生成 action/draft/task/settlement 与占位 state 属生成实现者；selectedResourceIds、resourceCanvasHistory、drag handlers 和整理 handler 属布局实现者。不得整文件格式化或跨界重构；共享 import 冲突由主 Agent 集成。
+- 布局实现者提供支持批量坐标及手动标记的保存入口；生成实现者仅使用现有单位置保存接口做完成落点，避免同时修改布局 hook。
+
+## 验证命令
+
+- `npm test -- <相关测试文件>`
+- `npm run typecheck --workspace @genarrative/ai-game-creator-shell`
+- `npm run check:encoding`
+- `npm run check:doc-index`
+- `git diff --check`
+- 原生契约变更时补对应 Rust 定向测试；真实 Provider 调用前单独核对费用和环境。
+
+## 风险与回滚点
+
+生成结果登记、持久化布局及手势共享组件是主要交叉风险；独立分支保留可回滚提交，不覆盖原有工作区。依赖复用需避免 workspace 包指向旧工作区；不能因测试通过而跳过实际解析路径核对。文档临时计划在全部验收后清理。
+
+## 剩余执行入口
+
+1. 真实客户端复验末版生成浮层可见性，以及图片/音频结果接管占位；真实 Provider 验证需先确认环境与费用。
+2. 用户确认远程写入后再创建/更新 Issue、PR、推送与需求记录；本地 worktree 和提交均保留。
+3. 运行时验收通过后融合持久结论并删除这两份临时计划。appSurface 异步轮询用例收尾及全量复验已经完成，证据见里程碑。
@@ -0,0 +1,45 @@
+# 策划 Agent 回合模型选择生效实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | [回合模型选择生效里程碑](./【里程碑】策划Agent回合模型选择生效-2026-09-20.md) |
+| Status | implemented（待验收） |
+| Owner | 当前任务 Agent |
+
+## 修改边界与顺序
+
+1. 在本地 `DesignTurn` 中追加可缺省的模型/推理档选择快照，仅存两个非敏感字段。现有 UI 只投影会话摘要，无需扩展前端 DTO。
+2. 策划普通发送、澄清回答、用户重试和批准阶段实际开始执行时，从现有配置加载结果获取全局模型和推理档，覆盖上一轮选择；重复命令、拒绝审批和纯读取不重新采样。
+3. Provider 请求使用当前回合快照，工具循环与自动重试期间不随全局选择变化。保留其它连接配置的原解析，策划专属配置不能覆盖这两个用户选择字段。
+4. 自动恢复沿用活动回合快照；旧记录缺快照时保留已有会话模型，并从当前全局配置补推理档，再由原检查点保存。保持工具幂等和审批流程。
+5. 补充既有 Rust 测试，验证请求字段、新旧会话、重试、审批/澄清和恢复；更新主规范与稳定项目记忆。
+
+## 非目标
+
+不改两个前端控件、GameAgent、模型目录、默认值、供应商适配；不新增模型可用性检查、自动换模型或提交门禁。不保存凭据或完整配置，不引入通用快照框架。
+
+## 验证
+
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml design_runtime::tests -- --test-threads=1`
+- `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml design_session -- --test-threads=1`
+- 改动文件 Rust 格式检查；文档索引、编码检查和 `git diff --check`。
+- 优先本地 HTTP fixture 核对发送给 Provider 的模型与推理档，真实 Provider 未运行时明确记录。
+
+## 风险与回滚
+
+模型选择快照必须在首个副作用前持久化，配置读取失败不能改变既有持久状态；旧记录自动恢复不推断历史推理档。新增可缺省字段支持现有会话读取，回滚不删除会话或产物。
+
+时间盒：先完成最小采样/请求闭环和定向测试，再核对恢复与文档。仅在影响本里程碑判据时扩大范围。
+
+## 验证记录
+
+| 验证 | 结果 |
+| --- | --- |
+| 改动文件 Rust 格式检查、diff 检查 | 通过 |
+| 文档索引、编码检查 | 通过 |
+| Rust 定向测试 | 已尝试编译，未执行测试用例；不记为通过 |
+| 本地 HTTP fixture | 已补充真实请求字段断言，尚未执行 |
+| 桌面/真实 Provider smoke | 未运行 |
+| 独立静态审查 | 已检查采样入口、重放/恢复边界、请求循环和测试辅助函数可见性，无可操作发现 |
+
+新增用例验证回合快照与旧数据读取，以及普通消息、跨工具请求、澄清回答、用户重试、审批批准、重复审批的配置生效边界。已有恢复用例继续覆盖不确定文件操作不重复执行。控件和 GameAgent 无本步修改。
@@ -0,0 +1,49 @@
+# 策划 Agent 模型与推理档控件接入实施计划
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | [控件接入里程碑](./【里程碑】策划Agent模型与推理档控件接入-2026-09-20.md) |
+| Status | accepted |
+| Owner | 当前任务 Agent |
+
+## 修改边界
+
+- 在 `ProjectSupervisorView.tsx` 扩展既有控件排的适用范围，直接复用 `ConversationModelSelect` 与 `ComposerReasoningEffortSelect`。素材引用、语音、消息队列和停止按钮仍按原 GameAgent 条件显示。
+- 策划发送、澄清、审批和重试回调保持原样，不新增模型校验和提交门禁；GameAgent 的原校验保持不变。
+- 必要时局部调整策划宿主 CSS，避免控件换行或弹层裁切。组件内部逻辑保持不变。
+- 在现有前端测试体系补齐策划集成场景，回归已有 GameAgent 控件用例。
+- 不修改 Rust、模型生效逻辑、配置默认值、Provider 或 GameAgent 组件算法。
+
+## 实现顺序
+
+1. 核对共享对话容器，接入同一组控件，保留原提交路径。
+2. 补充策划控件读写、保存失败和忙态测试，回归原策划和 GameAgent 行为。
+3. 运行定向测试和类型检查，检查宽窄布局，回写证据与未验证项。
+
+## 验证命令
+
+- `npm test -- apps/ai-game-creator-shell/tests/appSurface.test.ts`，先按用例名称过滤控件及相关策划场景。
+- 策划宿主集成用例使用现有 Vitest / Testing Library，按实际测试文件定向运行。
+- `npm run ai-game-creator-shell:typecheck`
+- `npm run check:doc-index`
+- `npm run check:encoding`
+- `git diff --check`
+
+## 风险与回滚点
+
+- 防止扩大 `directCodex` 条件时带入语音、队列或改变 GameAgent 行为：仅共享控件排，保留其它分支。
+- 模型目录失败通过原选择器反馈，不给策划宿主增加前置检查，也不改造控件已有逻辑。
+- 本次回滚仅撤回前端接入、相关用例和文档，不涉及持久化数据迁移。
+- 时间盒：一个工作时段内先完成接入与定向测试，随后检查类型和布局；仅影响里程碑验收的发现纳入修复。
+- 当前已知限制：策划旧会话仍可能使用创建时模型；本次不将控件读写成功视为运行时已切换模型。
+
+## 验收证据
+
+| 项目 | 结果 |
+| --- | --- |
+| 源码边界核对 | 两个控件文件、策划动作回调、GameAgent 提交校验及 Rust 均无修改；仅扩展控件排适用条件与策划布局 |
+| 定向 ESLint | `ProjectSupervisorView.tsx`、`design-agent.suite.ts`、`harness.ts` 通过 |
+
+定向测试命令：`npm test -- apps/ai-game-creator-shell/tests/appSurface.test.ts -t 'Design Agent|design session|clarification free text|reasoning effort control|selecting the model|model dropdown|chat composer an inset|current turn reasoning|historical reasoning'`。
+
+用户已授权提交第一步、进入第二步。
@@ -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 或清单。本轮按用户授权提交推送，不部署；代码可独立回退。
@@ -3,7 +3,7 @@
 | 字段        | 值                                                                 |
 | ----------- | ------------------------------------------------------------------ |
 | Version     | 1.0                                                                |
-| Status      | deferred                                                           |
+| Status      | in-progress                                                           |
 | Date        | 2026-09-17                                                         |
 | Parent Spec | `docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md` |

@@ -30,7 +30,9 @@
 - macOS 签名证书与公证凭据可用；若不满足，本里程碑只能交付构建与清单能力，并明确标注未验证项。
 - macOS 通用包所需的双架构工具链（两个 darwin 目标）在构建机上可用。

-本里程碑暂缓执行：macOS 构建机与签名 / 公证凭据尚未就绪，改由后续独立变更承接；暂缓期间 dev-mac 渠道不发布。
+构建与发布能力已落地：专用 macOS Jenkins 节点（label `genarrative-agc-macos`）+ `Jenkinsfile.ai-game-creator-shell-macos-build` + `scripts/build-macos-ci.mjs` 负责 universal 构建、双架构隔离 smoke、universal DMG、渠道清单 `latest.json`、更新包验签门禁与 OSS 上传（`AGC_RELEASE_DRY_RUN` 默认开启）。
+
+仍未就绪：Apple 代码签名与公证凭据（产物保持未签名 + 未公证，构建清单显式记录 `appleSigned=false` / `notarized=false`，首装需手动放行 Gatekeeper）；「安装 → 重启接管新版本」的实机更新闭环、Intel 真机 smoke（当前 x86_64 侧为 Rosetta）尚未验收。

 ## 验收标准

@@ -0,0 +1,37 @@
+# 里程碑：AGC 总版本号落地
+
+状态：进行中（主规范已定稿，代码与 CI 已实现，等待首次真实统一构建验收）
+
+## 关联文档
+
+- 主规范：`docs/technical/【技术方案】AGC总版本号与发号-2026-09-20.md`
+
+## 交付物
+
+1. 发号模块与入口：`agc-global-version.mjs`、`issue-global-version.mjs`、`agc-global-version.test.mjs`。
+2. 构建侧改动：`build-release.mjs` 的 `prepareReleaseVersion()` 采用总号，高水位降级为断言。
+3. CI：发号 Job（`Jenkinsfile.agc-global-version-issue` + job config）、调度管线与手动管线接入发号 Job。
+4. 文档与项目记忆更新。
+
+## 实现顺序与门禁
+
+| 步骤 | 内容 | 门禁 |
+| --- | --- | --- |
+| 1 | 发号模块 + 单元测试 | `node --test apps/ai-game-creator-shell/scripts/agc-global-version.test.mjs` 全绿 |
+| 2 | 构建侧接入总号与断言 | `build-release.test.mjs` / `release-oss.test.mjs` / `cargo-features.test.mjs` 全绿 |
+| 3 | 发号 Job 与管线接入 | `npm run check:production-ops`、`npm run check:encoding` 通过 |
+| 4 | 一次性播种 | 发号 Job 勾选 `SEED_ONLY` 写入基线，回读一致 |
+| 5 | 首次统一构建 | dev-win 与 dev-mac 清单版本相同且等于总号 |
+| 6 | 单渠道热修回归 | 只有该渠道清单变化，总号 +1 |
+
+## 当前证据
+
+- `agc-global-version.test.mjs`：7/7 通过（播种基线、首发、递增、dry-run 不烧号、回退断言、并发写后回读失败关闭、patch 递增）。
+- AGC 相关脚本合跑：32/32 通过。
+- 真实 OSS 只读预览：`--dry-run --channel unified` 输出 `AGC_GLOBAL_VERSION=0.1.77`（基线 0.1.76，未写回）。
+- `npm run check:production-ops`、`npm run check:encoding` 通过。
+
+## 未完成项
+
+- 首次真实播种与统一构建尚未执行（避免在功能未合并前烧号）。
+- `feat/jenkins-mac-build` 分支上的 macOS 管线仍用旧的自增高水位逻辑；该分支合并 master 后才继承本方案的模块与断言，合并前 dev-mac 必须由发号 Job 显式传入 `AGC_RELEASE_VERSION`。
@@ -13,7 +13,7 @@

 ## 范围

- 构建期按渠道生成清单：版本按渠道独立递增，清单包含该渠道平台的下载地址与签名；`dev-mac` 的 universal 包按同一地址与签名同时写入 `darwin-aarch64` 与 `darwin-x86_64`。
+- 构建期按渠道生成清单：版本按渠道独立递增，清单包含该渠道平台的下载地址与签名；macOS 自 2026-09-21 起只出 arm64 单架构，`dev-mac` 只登记 `darwin-aarch64`（原 universal 双键口径已作废：随包 Node 只有单架构官方发行版，需先实现双架构运行时才能恢复 Intel，见 `docs/project-memory/shared-memory/decision-log.md`）。
 - 构建期生成更新产物签名，并在缺少签名私钥或私钥不可用时失败关闭。
 - 渠道参数与目标平台绑定校验：Windows 目标只能发布 `dev-win`，macOS 目标只能发布 `dev-mac`；未显式指定时按目标平台取默认渠道。
 - 上传按渠道落位：安装包与签名进版本目录，清单覆盖写渠道路径的 latest 指针。
@@ -0,0 +1,40 @@
+# 【里程碑】AGC 资源 kind 枚举化 Rust 绑定与内部收紧
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | complete |
+| Date | 2026-09-15 |
+| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` |
+
+## 目标
+
+将 GameCreationApp 资源 kind 从 shell 内裸字符串收紧为 Rust `GameCreationAppAssetKind`，并生成 shell 专属 TypeScript 绑定；所有同语义内部字段使用该类型，未知输入解析为 `Unknown` 并记录日志。
+
+## 范围
+
+- Rust enum、serde kebab-case、`Unknown` 与 category 派生边界。
+- ts-rs feature-gated 生成入口、生成文件和 verify 门禁。
+- `packages/shared/src/contracts/gameCreationApp.ts` 中重复的资源 kind 手写契约迁入 shell 生成绑定后的删除/收口。
+- shell 内资源 kind 参数、投影、筛选、Agent 资源引用和 manifest 读写边界的类型收紧。
+
+## 不在范围内
+
+- server-side 其他 `asset_kind`、External API DTO、SpacetimeDB schema；仅纳入 api-server 图片快速编辑对 GameCreationApp manifest 来源的严格校验。
+- `source.kind`、`generationKind`、MIME 和文件格式。
+- 其他领域字段为配合本里程碑进行“顺手枚举化”。
+
+## 依赖与前置条件
+
+- 词汇审计里程碑通过并关闭所有阻塞项。
+- 生成目录、TS 导入路径、Unknown 日志字段和 writer 禁止主动写 Unknown 的规则已确认。
+
+## 验收标准
+
+- [x] Rust enum 与生成的 TS 绑定值逐项一致，JSON 使用 kebab-case；正式资源成员为当前 17 个 canonical kind 加 `font`，另有 `Unknown` 解析成员。TS 侧不再手写值集合，改为对生成 union 做穷举 `Record`。
+- [x] 未知输入得到 `Unknown`，日志包含原始值与调用上下文（`parse_with_context` + 壳层在 `main()` 注册的 `app_log!` 回调，见 2026-09-17 收敛）。
+- [x] 生产 writer 不再接受裸 `string` 作为 GameCreationApp kind（manifest 写入、资源登记、direct runtime、平台美术登记、资源编辑派生均只传枚举成员）；`Unknown` 仅表示解析边界无法判定，调用方可拒绝或交后续归类。
+- [x] `font`、`audio`、`sound-effect`、`background-music` 均有真实生产路径（字体导入、上传音频推断、资源编辑音频派生）。
+- [x] ts-rs 绑定由 `cargo test export_bindings` 生成，生成目录加入 `.prettierignore` / eslint `ignorePatterns`，可幂等复现且不污染工作树。
+- [x] 退役的 `BindingDTO` / `BindingChange` 不再导出，手写的 `exports_ui_editor_types` 已删除。
+- [x] 旧 alias 不再由共享契约把非 canonical 输入收口成 canonical；api-server 图片快速编辑不再保留 legacy 兼容白名单，非 canonical 来源直接失败。
@@ -0,0 +1,37 @@
+# 【里程碑】AGC 资源 kind 枚举化写入方清理与验证
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | complete |
+| Date | 2026-09-15 |
+| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` |
+
+## 目标
+
+逐处修正 shell 内仍产生非正式 GameCreationApp kind 的生产代码；保留仅属于 workflow、generation、路径或其他领域的字符串，并为这些边界补充清晰类型/命名说明而不扩大本 PR。
+
+## 范围
+
+- manifest 登记、恢复、回填、资源替换、画板/图集导出、字体导入、上传推断和 Agent 资源登记。
+- shell 前端资源投影、筛选和资源引用消费方。
+- 删除 alias/fallback 生产逻辑及其只服务于旧值的测试。
+- 对仍保留的 workflow、generation、路径和其他领域字符串完成边界核对，不将其重新解释为 manifest kind。
+
+## 不在范围内
+
+- 不改 `source.kind`、`generationKind` 等其他字段，即使它们恰好使用同名值。
+- 不修改 server-side 代码或公开 API。
+- 不实现字体格式/MIME enum；`font` 只作为本次 manifest asset kind 成员。
+
+## 依赖与前置条件
+
+- Rust/TS 绑定里程碑通过。
+- 写入方扫描清单中每个 alias 都已有“manifest kind / 其他领域 / 删除”结论。
+
+## 验收标准
+
+- [x] 新建、导入、生成、恢复、替换路径不会写入未纳入 enum 的 manifest kind。
+- [x] 未知外部值只进入 `Unknown` 并有 trace；缺失输入的中性默认仅由明确登记入口决定。
+- [x] `source.kind` 与 `generationKind` 的既有字符串行为不变。
+- [x] 定向 Rust、TS、绑定生成、编码和 diff 检查通过。
@@ -0,0 +1,46 @@
+# 【里程碑】AGC 资源 kind 枚举化词汇审计与绑定架构
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | complete |
+| Date | 2026-09-15 |
+| Parent Spec | `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` |
+
+## 目标
+
+在 `apps/ai-game-creator-shell` 内建立唯一的 GameCreationApp 资源 kind 领域边界：Rust enum 是权威，TypeScript 由 `ts-rs` 生成；先完成全量词汇审计和生成架构合同，再进入业务代码替换。
+
+## 范围
+
+- 审计 shell 内所有可能表示 GameCreationApp 资源 kind 的字段、构造器、写入边界、筛选器、资源投影、Agent 资源引用和测试 fixture，并收紧 api-server 图片快速编辑的 manifest 来源边界。
+- 以 api-server 当前仍有效的同语义 kind 作为命名与 serde 值参考，并评估 shell 当前实际生产 kind；排除 api-server legacy、billing/storage taxonomy 和其他开放领域。
+- 确认 Rust enum、`Unknown`、kebab-case JSON 和 ts-rs 生成文件的归属、生成命令与校验门禁。
+- 形成逐项 todo：当前值、真实语义、生产/测试状态、目标 enum、是否改写、验证方式。
+
+## 不在范围内
+
+- 不扫描或修改 api-server 其他领域的 `asset_kind`；图片快速编辑来源校验属于本次 GameCreationApp manifest 边界，必须复用共享枚举且不得保留 legacy 白名单。
+- 不改 `mediaType`、MIME、文件扩展名、`source.kind`、`source.generationKind`、任务/工作流 kind、路径名或 tracking scope。
+- manifest writer 与前端消费方已统一到共享 Rust enum/ts-rs binding；不扩展公开契约。
+- 不实现旧 manifest migration；无法解析的输入只在共享解析边界收口为 `Unknown`，由调用方拒绝或交后续归类，不增加 alias 表或 fallback。
+
+## 依赖与前置条件
+
+- 主规范已确认资源 kind 候选集合、`Unknown` 语义和 shell 边界。
+- `shared-contracts` 当前被 server-rs 多个 crate 使用，ts-rs 生成能力必须 feature-gated 或由独立生成入口启用，不能污染默认 SpacetimeDB/WASM 构建。
+- 当前已有 Tauri ts-rs 生成测试可作为生成命令形态参考，但不复用 UI Editor 类型目录作为资源契约目录。
+
+## 验收标准
+
+- [x] shell 内 manifest 资源 kind 的生产写入点、解析点、投影点和测试 fixture 已完成审计并收口。
+- [x] 每个旧值均已标注为：正式 GameCreationApp kind、其他领域字符串、legacy/错误 fallback；没有只按 grep 结果猜测的条目。
+- [x] api-server 有效值、shell 扩展值和排除值各有明确依据。
+- [x] 生成架构不会要求 server-side 默认构建安装 ts-rs。
+- [x] todo 清单的每项都有关闭条件和对应验证证据；图片快速编辑不再维护兼容白名单，退役 kind 直接失败。
+
+## 证据要求
+
+- 自动化：raw kind 扫描脚本/报告、Rust/TS 生成试验、serde kebab-case round-trip 试验。
+- 文档：主规范、todo 清单、下一里程碑实施计划互相链接且无冲突。
+- 边界：至少覆盖 `font`、`audio`、`sound-effect`、`background-music`、`Unknown`，以及 `source.kind`/`generationKind` 不误收编。
@@ -0,0 +1,51 @@
+# 【里程碑】AGC 音频生成进入后台任务账本
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | implemented-awaiting-runtime-acceptance |
+| Date | 2026-09-20 |
+| Parent Spec | `docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（§3.10 / §7.9）、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md` |
+
+## 目标
+
+AGC 功能画布音频栏目的「生成背景音乐 / 生成音效」与图片类生成走**同一条后台生成任务账本**：提交即返回任务记录、生成在客户端后台跑、状态与阶段文案由账本提供，任务出现在画布「生成任务」侧栏里，重开项目后仍能看到并按中断口径收口。
+
+## 范围
+
+- 音频无源生成（`create`）的提交、排队、状态读回、成功落卡、失败收口与重试幂等。
+- 音频任务与图片类任务共用同一份项目内任务账本、同一个前端本地排队与同一个「生成任务」侧栏。
+- 音频任务的阶段文案、状态与耗时来源与图片类一致（后端账本拥有阶段文案）。
+
+## 不在范围内
+
+- 平台侧（api-server / external v1 / OpenAPI）路由、请求体、计费、队列与 worker 语义：本轮不改，音频仍提交既有 `/api/editor/audios/*/generations` 通道。
+- 音频波形级编辑、多轨、时长 / 循环等音频参数入口：仍按现状不做。
+- 视频入口、上传入口、图片类生成的参数与前置判据：行为不变。
+- 真并行派发（并发收口设计）：本轮仍保留「同一时刻只派发一条」的本地排队。
+
+## 依赖与前置条件
+
+- 现有图片类后台任务的账本、轮询、落点与聚焦链路可复用；音频生成通道（资源编辑派生）已具备 operation 幂等账本。
+- 音频提交需要携带请求身份（operation 与幂等键），否则重试会变成一次新的付费生成。
+
+## 验收标准与证据
+
+| 验收标准 | 结论 | 证据 |
+| --- | --- | --- |
+| 音频栏目的「生成背景音乐 / 生成音效」提交后**立即**返回一条任务记录；面板同步关闭，不等 IPC、不等排队、不等生成结束 | 自动化通过 | `resourceCanvasAssetGenerationBackgroundClose.test.tsx`（点「生成音效」同步提交 + 关闭，面板 DOM 里没有阶段文案与「后台运行并关闭」）、`resourceCanvasGenerationEntry.test.tsx`、`resourceCanvasGenerationHostLifecycle.test.tsx`（音频载荷逐字为 `projectPath / projectId / taskId / kind / prompt / assetName / idempotencyKey`） |
+| 提交受理后任务出现在「生成任务」侧栏，状态与阶段文案来自后端账本，前端不拼阶段、不做百分比 | 自动化通过 | `resourceCanvasAssetGenerationQueue.test.ts`（音频收口复用同一份账本记录）、`resourceCanvasAssetGenerationTasksPanel.test.tsx`、`resourceCanvasGenerationHostLifecycle.test.tsx`（提交后自动展开侧栏） |
+| 音频任务与图片类任务在同一条本地队列里按「同一时刻只派发一条」排队；第二条在本地排队期间不发提交 IPC | 自动化通过 | `resourceCanvasAssetGenerationQueue.test.ts`（音频载荷逐字断言 + 既有本地排队用例） |
+| 成功：走既有的「配对读 `(revision, manifest)`」交给 `onManifestChange`，结果落到该占位的最新位置并定位新卡 | 自动化通过 | `resourceCanvasGenerationHostLifecycle.test.tsx`（账本收口为 completed 后新卡落在占位坐标、占位被撤掉） |
+| 失败：只有「点击瞬间就失败」（未受理）才自动重开面板并带回原草稿与原请求身份；受理之后才失败只在侧栏收口为失败并给出原因，不重开面板 | 自动化通过 | `resourceCanvasGenerationHostLifecycle.test.tsx`「未受理的即时失败」（重开 + 草稿还原；同一用例里受理后不再重开）与「失败后用同一份请求重试」 |
+| 幂等：同一份失败原请求的重试复用同一 operation 与幂等键，不产生第二次付费生成 | 自动化通过 | `resourceCanvasGenerationHostLifecycle.test.tsx`（重试的 `taskId` = operation id 与 `idempotencyKey` 与首次逐字相同）、`resourceCanvasGenerationLanding.test.tsx` |
+| 重开项目：音频任务从账本恢复显示；上次运行中断的任务按中断口径收口，不假装还在跑 | 自动化通过（恢复路径） | 音频 kind 的入口文案由工具栏模型派生（`resourceCanvasAssetGenerationTaskModel` + `resourceCanvasAssetGenerationQueue.test.ts`）；中断收口沿用既有账本口径 |
+| 音频提交失败（校验 / 权限 / 通道拒绝）时 manifest、revision 与任务账本都不出现半途写入 | 自动化通过 | Rust `asset_generation_tasks` 的 `audio_submission_rejects_invalid_identity_and_prompt_without_touching_the_ledger`（提交期拒绝零写入）、`audio_submission_lands_in_the_shared_ledger_with_its_audio_kind` |
+
+运行时验收（未做）：没有跑真实付费音频生成，也没有在真实客户端里做手感验收；全链以模拟原生接口的宿主用例覆盖。
+
+## 证据要求
+
+- 自动化：AGC 前端定向 vitest（音频入口宿主生命周期、生成任务队列与侧栏、appSurface 载荷）+ Rust 定向 `cargo test`（账本与音频任务入参收口）+ 类型检查 + 编码 / 文档索引 / `git diff --check`。
+- 运行时：无真实付费生成；以模拟原生接口的宿主用例覆盖提交 → 排队 → 收口 → 落卡全链。
+- 边界：未受理失败的即时重开与身份复用、账本读不到 / 记录缺失的收口、跨项目切换不串任务。
@@ -0,0 +1,50 @@
+# Mac 本机构建节点接入
+
+- Version: 1
+- Status: accepted-with-open-items
+- Date: 2026-09-18
+- Parent Spec: `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`
+
+## 交付与边界
+
+用户已确认使用当前 Mac，允许配置本机后台 Agent、创建 Jenkins 节点与构建 Job，并触发一次验证构建。复用已有 universal 产物合同与 Windows 管线的仓库访问凭据，仅手动构建和归档，无 OSS 上传、更新签名、Apple 签名/公证或定时调度。远程 Git 推送不在本次确认内。
+
+节点仅运行明确匹配 `genarrative-agc-macos` 的可信构建，单 executor；Job 禁止并发。Agent 根、workspace、原生 staging 与 target 均独立于开发 checkout，禁止在开发目录执行 npm ci、git clean/reset 或 Cargo 构建。登录用户 Agent 不等于安全沙箱，Jenkins 管理员与获准运行此 Job 的人必须受信任。登出、休眠或脱离内网将影响节点可用性。
+
+## 验收
+
+1. 从 Jenkins 当前控制器下载匹配的 agent.jar，Java 21 兼容检查通过，凭据留在仓库外、权限受限，不输出 secret。
+2. 节点实际 online，专用标签、EXCLUSIVE、单 executor；本地 LaunchAgent 可重启、可卸载。
+3. SCM 构建固定源码 commit，依赖从 lockfile 安装，两种原生 Codex 包 integrity 校验通过。
+4. universal Release、两架构 smoke、DMG verify 通过；归档只有安装包、摘要和非敏感来源信息。
+5. 真实 Jenkins build 为 SUCCESS 且归档存在。不以 XML 创建或本地单测冒充远端运行成功。
+
+## 初始检查与风险
+
+2026-09-18 当前机器具备 Java 21、两种 Rust Apple target 与 Rosetta；剩余磁盘约 11 GiB，独立 checkout 构建前须检查空间，不清理用户缓存。控制器地址连续连接超时，属于网络阶段，尚未使用认证凭据或创建后台服务。必须先恢复内网可达性；不修改本机网络路由或代理规避此限制。
+
+## 编码前评审
+
+只扩展现有 Jenkinsfile/应用打包脚本，不新增发布系统。用专用工作区且保持不发布，是当前明确授权内的最小闭环。代码未推送前不可把远端 master 当作已具备 universal 双资源实现；首跑源码来源必须明确记录，不能暗用开发工作树。
+
+## 当前证据与阻塞
+
+Jenkinsfile、锁定双架构依赖预备脚本与 archive-only CI 打包入口已在本地准备。定向 Node 测试 37 项通过，类型/配置、编码、文档索引、定向 ESLint 与 diff 检查通过；未执行完整 Jenkins 构建或在线 Groovy 校验。
+
+控制器直连多次超时，经当前代理请求返回 502；Java 21 已存在，无需安装新 JDK。尚未注册节点、创建 Job、保存 Agent secret、安装 LaunchAgent 或触发远端构建。需先恢复内网连接，再按本规范验收真实节点及构建状态；不把本地代码准备描述为已经接入成功。
+
+## 验收结果（2026-09-20）
+
+| 验收项 | 结果 |
+| --- | --- |
+| 控制器匹配的 agent.jar + 已有 Java 21 | 通过（未安装新 JDK） |
+| 节点实际 online、专用标签、EXCLUSIVE 单 executor | 通过（`genarrative-agc-macos-01`） |
+| LaunchAgent 可重启/卸载、凭据在仓库外且权限受限 | 通过 |
+| 固定 commit、锁文件装依赖、两种 macOS 原生包 integrity | 通过 |
+| universal Release + 双架构 smoke + DMG verify | 通过（arm64 原生、x86_64 走 Rosetta） |
+| 归档仅含安装包/摘要/非敏感来源信息 | 通过 |
+| 真实 Jenkins build SUCCESS 且归档存在 | 通过（build #3，43 分钟） |
+
+同期修复：Mac 入口误传 `--no-sign` 导致更新包无签名；复用 workspace 的残留产物导致 DMG 重建失败、旧签名可能让验签误通过；并行度由写死 4 改为 Job 参数（默认 6）。
+
+仍未验收：Apple 代码签名与公证（当前 `adhoc`，首装需 Gatekeeper 手动放行）、macOS 安装后重启接管新版本的实机闭环、Intel 真机 smoke、真实（非 dry-run）发布与渠道清单上线。
@@ -0,0 +1,36 @@
+# Mac 通用安装包与构建管线
+
+- Version: 1
+- Status: awaiting-user-acceptance
+- Date: 2026-09-18
+- Parent Spec: `docs/technical/【技术方案】AGC客户端更新检查与下载-2026-08-31.md`
+
+## 当前交付门禁
+
+当前仅交付 AGC 0.1.67 universal 本地 DMG，版本、Codex 0.147.0 与 macOS 15.0 下限不变。不生成私钥、不签名公证、不发布、不推送。
+
+主程序含 arm64/x86_64 两个切片；macOS 资源分 `darwin-arm64` 与 `darwin-x64`，两套原生依赖保持上游相对路径和独立清单。运行切片只读取对应目录。构建必须校验两套锁定包身份、目标、版本与完整性；Windows 路径和资源不变。不合并原生 Codex 二进制，不改写其上游元数据。
+
+## 验收
+
+- 发布上下文接受 universal，dev-mac 的两个平台键同 URL/签名。
+- 主程序 lipo 两切片，资源检查两套原生架构、摘要和可执行位。
+- Apple Silicon 与 Rosetta 各做隔离 HOME/PATH 的真实 app-server 握手、正式程序查找与缺组件拒绝；Rosetta 不代替 Intel 真机。
+- 生成独立 universal DMG，不覆盖已有单架构 DMG；镜像校验、类型/配置/定向测试与编码检查通过。
+
+## 后续管线边界
+
+用户要求安装包完成后接入 Jenkins。先只读检查节点与现有 Job；创建/修改 Job、凭据或触发构建前额外确认。只有当前安装包门禁完成后再形成管线实现计划；不把凭据保存进源码、日志、计划或打包资源。
+
+## 编码前评审
+
+采用分架构资源而非 lipo Codex，避免破坏原生包元数据及 code-mode host、zsh 的资源寻址。macOS 共用配置明确列举两套文件，必须失败关闭，单架构诊断包也携带完整资源。现有 single-arch 选择逻辑改为同架构子目录，不涉及持久化数据迁移。
+
+## 验收证据
+
+- 同步至 master `9a21690fe`，本地 universal 修改无冲突恢复；未推送。
+- Tauri universal Release 构建通过，主程序 lipo 显示 arm64/x86_64，Info.plist 版本 0.1.67、最低 macOS 15.0。
+- `check-macos-bundle.mjs <app> arm64 --universal` 与 `x86_64 --universal` 均通过：每架构资源摘要、原生身份、执行权限、正式 Codex 选择、隔离 app-server 握手、缺 code-mode host 时拒绝。x86_64 在 Rosetta 执行，尚非 Intel 真机。
+- 发布/feature/上传定向 Node 测试 33 项通过，共享 Codex 布局模块在隔离 Cargo harness 的 2 项测试通过；类型/配置、定向 ESLint、编码/文档和 diff 检查通过。
+- universal `.app` 约 672 MiB，DMG 约 290 MiB；hdiutil 完整性校验通过。未做 GUI、账号/Provider、Intel 真机或签名公证验收。
+- Jenkins 只读检查确认现有节点为 Linux 与 Windows，尚无 macOS Agent；创建管线前需用户指定并授权接入 Mac 节点。本地凭据不进入源码或验证产物。
--- a/Show More
+++ b/Show More