合并 master 并保留 GPT Image 2.5 与外置提示词行为
Project CI / AI game creator shell Rust crates (pull_request) Successful in 3m1s
Project CI / AI game creator shell Rust smoke (pull_request) Successful in 3m54s
Project CI / AI game creator shell Rust lane 1/2 (pull_request) Failing after 6m52s
Project CI / AI game creator shell Rust lane 2/2 (pull_request) Failing after 8m1s
Project CI / Native shell tests (pull_request) Successful in 9m25s
Project CI / Backend tests (pull_request) Successful in 10m37s
Project CI / Repository checks (pull_request) Successful in 7m52s
Project CI / Frontend tests (pull_request) Failing after 10m40s
Project CI / AI game creator shell web tests (pull_request) Failing after 5m25s
Project CI / AI game creator shell Rust crates (pull_request) Successful in 3m1s
Project CI / AI game creator shell Rust smoke (pull_request) Successful in 3m54s
Project CI / AI game creator shell Rust lane 1/2 (pull_request) Failing after 6m52s
Project CI / AI game creator shell Rust lane 2/2 (pull_request) Failing after 8m1s
Project CI / Native shell tests (pull_request) Successful in 9m25s
Project CI / Backend tests (pull_request) Successful in 10m37s
Project CI / Repository checks (pull_request) Successful in 7m52s
Project CI / Frontend tests (pull_request) Failing after 10m40s
Project CI / AI game creator shell web tests (pull_request) Failing after 5m25s
保留编辑器图片工具使用 gpt-image-2.5 业务模型名 保留工具参数说明从 prompts 外置文件读取 同步外置模型与尺寸文案并完成冲突验证
This commit is contained in:
@@ -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」窗口从提交前移到派发时刻：冲突时按失败收口（不静默重试），避免把生成写到非预期基线。
|
||||
@@ -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,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`。
|
||||
@@ -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 节点。本地凭据不进入源码或验证产物。
|
||||
@@ -0,0 +1,48 @@
|
||||
# 策划 Agent 回合模型选择生效
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
| Status | implemented（待验收） |
|
||||
| Date | 2026-09-20 |
|
||||
| Parent Spec | [策划 Agent 生产迁移与工作区浏览方案 §4.1](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#41-策划对话模型与推理档选择) |
|
||||
|
||||
## 目标
|
||||
|
||||
策划已有会话在后续执行时真正采用控件保存的模型和推理档，执行途中保持选择稳定，恢复不破坏既有工具副作用边界。
|
||||
|
||||
## 范围
|
||||
|
||||
- 新会话、旧会话后续消息、回答澄清、阶段审批继续和用户主动重试的选择生效。
|
||||
- 同一次执行中的工具循环、自动重试固定使用开始时的选择。
|
||||
- 活动回合自动恢复所需的最小模型、推理档快照及旧会话缺字段读取。
|
||||
- 模型切换保留策划上下文、阶段、审批和产物。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- 不改变 GameAgent Runtime 或既有配置控件算法。
|
||||
- 不调整模型目录、默认档位、供应商协议、提示词和阶段规则。
|
||||
- 不建立 Agent 专属设置、通用快照框架、历史转换器或平行账本。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- [控件接入里程碑](./【里程碑】策划Agent模型与推理档控件接入-2026-09-20.md) 已验收。
|
||||
- 主规范和本里程碑已评审，实施前编写仅覆盖本步的实现计划。
|
||||
- 生效时机、主动重试与自动恢复的区分遵循主规范，不通过重建会话实现切换。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 新策划会话和旧策划会话下一次执行都使用当前已保存选择；旧模型不再永久覆盖新选择。
|
||||
- [ ] 发送、澄清、审批继续与主动重试的实际 Provider 请求使用新选择。
|
||||
- [ ] 执行中改配置不影响本次后续工具请求或瞬态自动重试，下一次用户执行才生效。
|
||||
- [ ] 自动恢复优先使用已有活动回合快照；旧记录缺推理档时按主规范补齐，不重复已执行工具副作用。
|
||||
- [ ] 切换后上下文、阶段、产物和审批身份保留，纯读取不改历史模型信息。
|
||||
- [ ] 配置/Provider 失败沿用可见错误，不静默降级、换模型或清空历史。
|
||||
- [ ] GameAgent 既有选择和运行行为通过兼容回归，没有借机修正其本征不足。
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 自动化：本地 Provider fixture 捕获请求模型和推理档；覆盖跨工具调用、自动重试、用户重试、审批/澄清继续及旧会话恢复；运行相关 Rust 定向测试、必要类型检查、编码和文档索引检查。
|
||||
- 运行时：在现有策划项目选择另一模型及推理档，触发下一次执行核对实际请求；真实供应商是否接受跨模型历史需按环境记录实测或未验证。
|
||||
- 边界：验证恢复幂等和凭据不进入新增快照；无需新增通用权限或供应商测试体系。
|
||||
- 全部验收后将主规范提案改为当前行为，更新稳定项目记忆并删除本次已完成临时计划。
|
||||
@@ -0,0 +1,53 @@
|
||||
# 策划 Agent 模型与推理档控件接入
|
||||
|
||||
| 字段 | 值 |
|
||||
| --- | --- |
|
||||
| Version | 1.0 |
|
||||
| Status | accepted（用户已授权提交、进入第二步） |
|
||||
| Date | 2026-09-20 |
|
||||
| Parent Spec | [策划 Agent 生产迁移与工作区浏览方案 §4.1](../../technical/【技术方案】策划Agent生产迁移与工作区浏览-2026-09-10.md#41-策划对话模型与推理档选择) |
|
||||
|
||||
## 目标
|
||||
|
||||
策划对话复用已有模型和推理档控件，能够读取和保存全局选择，保持 GameAgent 兼容性。
|
||||
|
||||
## 范围
|
||||
|
||||
- 输入区域中控件的显隐、位置、策划面板布局与必要的宿主接线。
|
||||
- 复用原有目录、默认模型、保存和错误提示，不复制逻辑。
|
||||
- 策划发送、澄清、审批继续和主动重试保持原流程；不新增模型可用性检查或提交门禁。
|
||||
- 重新进入策划时显示保存值；执行中可以调整后续选择，但原输入与提交忙态维持不变。
|
||||
|
||||
## 不在范围内
|
||||
|
||||
- 不修改策划 Provider 的模型选择和推理档采样逻辑，不声称旧会话已能切模型。
|
||||
- 不检查、修复或重构 GameAgent 组件本征不足，不引入通用缓存、同步、保存、下拉或配置框架改造。
|
||||
- 不为策划引入队列、语音或素材引用，不更改默认推理档。
|
||||
|
||||
## 依赖与前置条件
|
||||
|
||||
- 主规范本节与本里程碑完成评审。
|
||||
- 实施前仅为本里程碑编写实现计划，确认现有 GameAgent 对应回归用例与策划宿主入口。
|
||||
- 本步作为内部接入结果；第二步完成前不单独发布为完整可切模型功能。
|
||||
|
||||
## 验收标准
|
||||
|
||||
- [ ] 策划入口显示原模型及推理档控件，没有重复实现或第二份设置。
|
||||
- [ ] 选择走原保存通道；重新进入显示已保存值；保存失败显示原有错误反馈。
|
||||
- [ ] 策划提交和报错流程保持原样，没有新增模型检查；原控件内部行为不改造。
|
||||
- [ ] 策划忙态、待审批/澄清行为保持；新增布局在宽/窄面板可操作。
|
||||
- [ ] GameAgent 原控件的显示、选择、发送校验、忙态和运行行为通过相关回归。
|
||||
- [ ] 交付明确记录旧策划会话仍沿用旧模型，留待下一里程碑解决。
|
||||
|
||||
## 证据要求
|
||||
|
||||
- 自动化：现有界面测试中增加策划入口的集成场景，复用 GameAgent 回归；运行 AGC 类型检查、文档索引、编码和 diff 检查。
|
||||
- 运行时：桌面与窄面板选择、保存、重新进入和一次策划发送 smoke；缺失环境如实标注。
|
||||
- 边界：只验证接入所需的失败和忙态，不扩展为现有组件全量审计。
|
||||
- 通过本步验收后，才准备并执行模型生效里程碑的实现计划。
|
||||
|
||||
## 当前交付
|
||||
|
||||
已接入原控件及策划布局，按用户最终要求保留策划提交、审批、澄清、重试与报错流程，没有新增模型检查。原控件与 GameAgent 的提交逻辑未修改；旧策划会话固定模型的限制仍由第二步解决。
|
||||
|
||||
新增三条控件集成用例（保存重进、运行中选择、保存失败反馈）。用户已授权提交第一步、进入第二步。
|
||||
@@ -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,101 @@
|
||||
# 决策记录
|
||||
|
||||
## 2026-09-21 图集切片上限：客户端结果门从 64 对齐到平台契约的 256
|
||||
|
||||
- 背景：现场（项目 `gameagent-6e53c9e8`，2026-09-21 07:54）「AI 生成图标素材」失败：`platform-generation-result-unknown: 异步生成完成结果无法绑定到 operationId：External Editor 旧同步结果的图集切片超过 64 个`。任务账本（`.agent/runtime/asset-generation-tasks/tasks.json`）显示它跑了 99 秒、`assetId` 为空、没有落任何素材；对应的持久化请求（`canvas-generation-requests/manual-canvas-asset-generate/slot-560175669f….json`）是 `sliceMode: connected-components` + `sliceCount: null`（自动切分）。也就是**平台已经生成并切完图了，是客户端在绑定结果这一步把整条结果判失败**，付费产物被丢弃。
|
||||
- 根因：同一条链路里存在两个不同的切片上限。平台切分是 256（`server-rs/crates/api-server/src/editor_project_icon.rs` 的 `EDITOR_ICON_SPRITESHEET_MAX_SLICES`），Agent 工具 schema 的 `sliceCount` 是 1..256（`agent_native_tools.rs` / `direct_tool_bridge.rs`），持久化产物批次也是 1..256，公开契约（`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`）写的更是「最多 256 个输出」；唯独客户端**两处结果绑定门**还是 `> 64` 就拒（`agent/generation/external_generation_state.rs` 与 `agent/generation/canvas_generation.rs`，由 `602723ea0` 于 2026-08-03 引入）。自动切分落在这个窗口里（65~256 片）时，客户端比平台更严，于是把合法产出整条丢掉。
|
||||
- 决策：两处门统一到 `PLATFORM_ART_SPRITESHEET_MAX_SLICES = 256`，并抽成同一条判据 `platform_art_spritesheet_slice_count_exceeds_limit` 与同一句拒绝文案 `platform_art_spritesheet_slice_limit_error`（数字由常量插值，不再手写）。注释里点名三处同值权威（平台切分常量、工具 schema `sliceCount`、公开契约），客户端不得比平台更严。
|
||||
- 原因：客户端这两处门的作用是「防止把不可信/超预算的结果写进本地」，不是产品上限；真正的产品上限属于平台切分契约。两处各写一个字面量就会再次漂移，所以值只留一份、判据只留一条。
|
||||
- 验证：新增 `canvas_generation_tests::spritesheet_slice_limit_matches_platform_and_tool_contract`（上限值、边界判据与文案）与 `external_generation_state_tests::legacy_result_accepts_slice_counts_up_to_platform_limit_and_rejects_beyond`（64/65/256 片必须能持久化且切片一条不少、257 片必须按同一句文案拒绝），两条都用**变异验证**确认过：把常量改回 64，回归用例立刻变红。定向执行 `cargo test -- spritesheet`（22 passed）、`cargo test -- external_generation_state_tests::`（10 passed）与两条新用例；`cargo fmt --check` 干净。
|
||||
- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/agent/generation/{canvas_generation.rs,external_generation_state.rs}`（+用例）。未动平台切分、OpenAPI、数据库或前端。
|
||||
- 已知未覆盖：真实客户端复验（重新生成一次图标素材）与远程 CI 未跑；256 片时的累计下载/像素预算未实测——平台自己的总像素上限是 2048×2048，客户端预算是 4096²，按切片是整图互不重叠子矩形推算不会先撞预算，且真撞了也只是给出明确错误而不是损坏数据。
|
||||
## 2026-09-21 本批自查（PR #441）：三处修正
|
||||
|
||||
- 背景：推 PR 后按「局部到整体」自查这一批（三需求 + 验收修正），查出三条：①拖动到对话的落点在 `pointermove` 上每帧都 `setState` 一个新对象；②替换面板相对 **stage** 写死 `top: 8.5rem`（与刚修的任务开关同一类隐患：工具条换行会压上去），且它和「生成任务」面板抢画布右上角同一个位置；③替换面板不显示「在替换哪张源素材」，而非模态化之后那点线索（画布上的源素材光环）会被一次空白点击清掉。
|
||||
- 决策①：落点状态改为**逐值比较**（`sameResourceCardReferenceDrop`：条数 + 对话栏矩形四值），只有真的变了才落 state——指针在对话栏上移动不再每帧重渲染整个工作台。
|
||||
- 决策②：面板从 stage 顶层移进**画布容器** `.game-resource-book-manager`（它本身就是 `position: relative`，与左下角工具栏、右下角 Dock 同一套锚定口径），`top: 3.2rem` 排在任务开关下方；并在打开替换会话时**收起「生成任务」面板**——画布右上角同一时刻只留一块浮层（任务照旧在账本里推进，收起只影响这个视图）。
|
||||
- 决策③：面板上方补一行「替换源素材：<显示名>」（投影显示名优先、manifest 资产名回落），源身份不再只靠画布光环。
|
||||
- 验证：`resourceVersionReplacement.test.tsx` 20 passed（新增「面板锚在画布容器里、写明源素材、并与任务面板互斥」）、`resourceCardReferenceDropModel.test.ts` 6 passed（新增逐值比较）、`resourceCanvasChatReferenceDrop.test.tsx` 4 passed；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit` 通过。
|
||||
- 影响范围：`apps/ai-game-creator-shell/src/view/project-development/{index.tsx,resourceCardReferenceDropModel.ts}`、`.../features/resource-canvas/resourceCanvasChrome.css`、用例 3 个文件、验收用例 C9 注脚。未动 Rust / SpacetimeDB / 共享组件行为（只新增了宿主的源素材行）。
|
||||
- 已知未覆盖：仍无真机目视；替换会话与任务面板的互斥是新行为，客户端需要复看一次（若产品希望两者能同时看，把这一句收紧即可）。
|
||||
|
||||
## 2026-09-21 验收现场修正：任务开关压在工具条上、开关与面板并排
|
||||
|
||||
- 背景：客户端验收截图两条：①画布右上角那枚「生成任务 · N」开关与工具条（打开项目目录 / 资源面板 / 整理画布 / 管理未完成编辑 / 依赖 · 类型）**重叠**；②「生成任务」面板展开时，开关与面板**并排**摆着，产品口径是「这俩不应该并排，出来详情以后入口就应该隐藏」。
|
||||
- 决策（重叠）：锚点不再用 `position: absolute` + 写死的 `top: 3.5rem`（工具条是 stage 第一行，高度随按钮换行变化，写死的偏移迟早压上去），改成 **stage 网格里与工作面同一个单元格的另一个条目**：`grid-row` 按 `placement` 分档（资源画布 3 / UI 编辑器 2 / 运行表现层 `2 / -1`）+ `grid-column: 1` + `justify-self: end` + `align-self: start` + `margin: 0.85rem`（运行那档上边距 3.5rem 让开右上角版本入口）。为此把同格的三处容器也显式钉住第 1 列（`.game-workbench-stage > .game-resource-manager`、`.…[data-resource-view-state='resources.ui-editor'] > .game-workbench-editor-shell`、`.game-run-surface`）——锚点是显式定位条目，画布若走自动列放置会被挤进隐式第二列、画布直接压窄一半。
|
||||
- 决策（并排）：开关只在**完全收起**时渲染（`!open && phase === 'idle'`，收起动画期间也不画，否则那 160ms 又会同框）；展开态画布右上角只有面板，收起走面板头部那枚 × 或点画布外部。原来「点画布外部自动收起」的判据里对开合按钮的排除保留（收起态仍靠它开合）。
|
||||
- 原因：验收口径优先于「照抄美术画布」——美术画布把开关常驻在面板旁边，但产品要的是「入口与详情不同时出现」。重叠那条的根因是**猜了一个绝对偏移量**：工具条高度不是常量，锚点必须由布局自己推导。
|
||||
- 验证：`resourceCanvasAssetGenerationTasksPanel.test.tsx` 12 passed（新增「展开时开关让位：同一时刻只有面板那枚 ×」；计数用例改为收起态查开关、展开态查面板头部）、`resourceCanvasAssetGenerationTasksSidebarStyle.test.ts` 11 passed（锚点改成网格条目坐标：`grid-row` / `grid-column` / `justify-self` / `align-self` / `margin` 与运行档上边距；窄屏改判 `justify-self: stretch`）、`resourceCanvasGenerationTasksSidebarDismiss.test.tsx` 5 passed（收起改走面板 ×、收起后开关回来能再打开、锚点仍在 stage 里）、`resourceCanvasAssetGenerationBackgroundClose.test.tsx` 5 passed；`appSurface.test.ts` 538 passed / 17 skipped / 0 failed。
|
||||
- 影响范围：`apps/ai-game-creator-shell/src/features/resource-canvas/{ResourceCanvasAssetGenerationTasksPanelView.tsx,resourceCanvasAssetGenerationTasksSidebar.css}`、`apps/ai-game-creator-shell/src/styles.css`、三个同场景用例文件、PRD §3.10 与更新时间。
|
||||
- 已知未覆盖：仍无真机目视（网格落点在 Tauri 里的实际观感、工具条换行时锚点是否仍贴画布顶边需要现场复核）。
|
||||
|
||||
## 2026-09-21 AGC 替换面板改为非模态浮层，支持在画布上点选目标
|
||||
|
||||
- 背景：`docs/project-memory/todos/【待办】画布验收后续修复-2026-09-18.md` 的「后续需求」要求「在替换面板中支持画布点选目标」。2026-09-13 那版做的是「候选弹窗 footer 一个『点选替换』按钮 → 关掉弹窗 → 进画布点选态 → 点中即提交」：面板与画布互斥（弹窗外壳是全屏遮罩，留着它画布上的卡点不到），用户要么在面板里筛、要么离开面板。
|
||||
- 决策：候选面板改成**非模态浮层**（共享组件新增 opt-in `nonModal`：不铺遮罩、不做焦点陷阱、面板自身限高 + 内部滚动、Esc 在 `document` 阶段截断后取消；网页端美术画布不传，弹窗行为逐字不变）。AGC 把它锚在画布**右上角、任务开关下方**（`.game-resource-replacement-panel` → `top: 8.5rem; right: 0.85rem`，壳样式在共享样式表里，宿主只负责锚定）。**面板开着时画布照常可点**：点中合法候选即落成面板里的当前选择（面板里随之 `aria-selected`），写入仍然只由面板「确认」发起；点中非法目标在面板里说明原因、零写入。旧的「点选替换」入口、画布提示条 `.game-resource-canvas-pick-hint` 与 `resourceReplacementPickMode` 随之退役（同一个功能不留两条 UI 路径）。
|
||||
- 决策（同步口径）：`selectedAssetIds` 的**数组引用不能当同步信号**（调用方每次渲染都会重建它，放进依赖会清掉用户在面板里的选择——组件里原本就为此写过一段注释），所以新增显式序号 `initialSelectionRevision`：只有宿主真的换了目标才重同步选择，搜索词与分类筛选保持原样。`confirmResourceVersionReplacement` 另外拿 `resourceReplacementPick` 兜底：点完画布当帧就按确认时不该报「请选择一个替换素材」。
|
||||
- 原因：面板与画布是同一屏的两半——目标本来就在画布上，「先把面板关掉再点」是弹窗外壳带来的妥协，不是产品意图。换成非模态之后，合法性判据仍是同一条 `resolveResourceReplacementPick`、写入仍是同一个 `confirm` 函数（载荷逐字一致），所以这是**外壳**的改动，不是第二套替换实现。
|
||||
- 已知取舍（相对旧口径的行为变化，均已随测试钉住）：面板开着时空白处点击不再被吞——画布恢复正常的清焦点 / 框选 / 平移语义（源身份在打开面板时就已冻结，替换不依赖画布选中）；「点中即提交」不再存在，提交一律由「确认」触发；关闭面板后卡片单击语义原样（一次性抑制照旧收尾）。
|
||||
- 验证：`resourceVersionReplacement.test.tsx` 19 passed（4 条旧点选用例改写为：非模态判据 + 点画布候选落进面板且零写入、面板确认才写入且载荷逐字一致+血缘、四类非法目标面板内报因零写入、Esc 只收面板不清选中；新增「画布点选不清掉面板搜索/分类」）、`projectAssetPickerDialogShellStyle.test.tsx` 7 passed（新增 nonModal 形态与浮层壳样式声明，含关掉即卸载）、`src/components/image-editor/ImageCanvasEditorView.test.tsx` 64 passed、`ImageCanvasEditorGenerationIntegration.test.tsx` 44 passed（网页端弹窗行为未变）；连同 `appSurface.test.ts`、`projectResourceLiveIntegration.test.tsx` 共 6 个文件 694 passed / 17 skipped / 0 failed；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit` 通过。
|
||||
- 影响范围：`src/components/image-editor/ImageCanvasProjectAssetPickerDialog.tsx`、`packages/shared/src/components/styles.css`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`.../features/resource-canvas/resourceCanvasChrome.css`、`apps/ai-game-creator-shell/tests/{resourceVersionReplacement.test.tsx,projectAssetPickerDialogShellStyle.test.tsx}`、PRD §5.3 / §7.8 第 8 条、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md` 的 S15a。未动 Rust、SpacetimeDB、external v1。
|
||||
- 已知未覆盖：真机观感（面板在画布右上角的落点、与任务开关同时打开时的间距）未在 Tauri 目视确认；面板里不显示「本次替换的是哪张源素材」，源身份只靠画布上那张卡的选中光环表达——点空白清掉选中后就只剩面板自己的候选列表。
|
||||
|
||||
## 2026-09-21 AGC 资源卡拖到对话实现批量 @ 引用
|
||||
|
||||
- 背景：`docs/project-memory/todos/【待办】画布验收后续修复-2026-09-18.md` 的「后续需求」要求「聊天拖拽批量引用」。改前只有两条入口：聊天输入框里输入 `@` 或点 `@` 按钮开素材选择面板，以及资源卡选中工具条上那枚「引用」按钮——都要先把素材找出来再点，多选批量引用没有一次成型的路径。
|
||||
- 决策：资源卡**按住拖到右侧 Agent 对话栏、松手即批量引用**。落点判据是「指针是否在对话栏矩形内」：pointermove 在对话栏上时语义从排版切成引用（卡片不再跟着指针走，改铺一层虚线落点浮层 + 「松手即可 @ 引用 N 项素材」），拖回画布内松手仍然是原来的排版语义（照旧写手动坐标）。批量范围与拖动位移**同一集合**（`drag.moves`）：多选后拖任意一张 = 整批引用，拖未选中的卡 = 只引用它自己。
|
||||
- 决策（引用构造与派发）：引用构造收敛成纯函数 `resourceCardReferenceDropReferences`，口径与工具条「引用」按钮**逐字一致**——只认已登记 manifest 的素材（`manifestAssetId`）、`source: 'resource-card'`、kind / 分类 / 标签取自资源投影，于是同一素材从两处进来是同一枚引用（去重键同样一致）。派发走新增的批量事件 `RESOURCE_REFERENCE_INSERT_MANY_EVENT`（`dispatchResourceReferenceInsertMany`）：N 条引用一次事务插进草稿、只聚焦一次，不逐条重建草稿。一条也构造不出来时（选中的素材都未登记）不静默：提示条说明原因。
|
||||
- 原因：拖动本来就在指针捕获下走，指针跑到画布外仍回到卡片 handler，因此「落点」只能自己量；不落盘是因为对话栏那一段没有画布坐标可言（写下去会得到跑到画布外的坐标），而且用户在对话栏上松手的意图本来就不是排版。`0 x 0` 的对话栏矩形必须判成「没有落点」：零面积矩形会让任何点都命中，画布内正常拖动会被整段跳过。
|
||||
- 验证：`resourceCardReferenceDropModel.test.ts` 5 passed（矩形/命中/构造/提示文案）、`resourceCanvasChatReferenceDrop.test.tsx` 4 passed（单卡拖到对话 → 1 条引用且零坐标写入、多选整批 → 2 条、拖回画布 → 照旧写手动坐标且零引用、pointercancel 收干净）、`resourceReferenceInput.test.tsx` 30 passed（新增批量事件一次派发且空批次不派发、一次 insertReferences 按序插入整批 chip）；连同 `appSurface.test.ts` 在内 7 个用例文件 660 passed / 17 skipped / 0 failed；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit` 通过。
|
||||
- 影响范围：`apps/ai-game-creator-shell/src/view/project-development/{index.tsx,resourceCardReferenceDropModel.ts}`、`.../features/project-workspace/resourceReferences.ts`、`apps/ai-game-creator-shell/src/App.tsx`、`apps/ai-game-creator-shell/src/styles.css`、`apps/ai-game-creator-shell/tests/{resourceCardReferenceDropModel.test.ts,resourceCanvasChatReferenceDrop.test.tsx,resourceReferenceInput.test.tsx}`、`docs/【功能说明】AGC聊天素材引用-2026-09-08.md`。未动 Rust、SpacetimeDB、`packages/`、共享弹窗组件。
|
||||
- 已知未覆盖：真实客户端里的手感（拖到对话栏的触发距离、提示条位置、多选整批的视觉反馈）未在 Tauri 目视确认；「复制对话保留有效引用」属于同一条后续需求里的另一半，本轮未做。
|
||||
|
||||
## 2026-09-21 AGC「生成任务」侧栏移到画布右上角（照抄美术画布，保留 AGC 样式）
|
||||
|
||||
- 背景：`docs/project-memory/todos/【待办】画布验收后续修复-2026-09-18.md` 的「后续需求」要求「生成任务列表移到画布右上角，进行中/已完成分组、失败可见、限高滚动及自动开合」。改前状态：侧栏本体是 `position: fixed; top: 4rem; bottom: 6rem; left: 0.75rem` 的左侧贴边面板，开合口只有工具条上那一枚「生成任务 · N」按钮（资源 / 运行两个页签各渲染一次），折叠态不留任何常驻入口；分组、失败可见、限高滚动、提交后自动展开这四条当时已经具备。
|
||||
- 决策：侧栏改挂**画布右上角的锚点**（`.game-resource-generation-tasks-anchor`），形态照抄网页端美术画布的任务侧栏（`ImageCanvasTaskSidebarView.tsx` + `src/index.css:6072+` 的 `.image-canvas-editor__task-sidebar*`）：**开关常驻右上角、面板在开关左侧展开**，收起态只剩那一枚开关；工具条上那两处重复入口删掉——同一个功能两个入口本身就是两处随时会漂移的状态。锚点是覆盖式的，仍然不 reflow 画布视口。颜色、圆角、字重、阴影**全部继续走 `--platform-*` token**，不照搬网页端的固定色值（该 CSS 文件头既有的口径）。
|
||||
- 原因：右上角是画布上唯一「不被右侧『智能创作』对话面板占、也不与左下角栏目工具栏 / 右下角缩放 Dock 打架」的稳定空位；折叠态仍留一枚开关以后，用户不必先想起工具条在哪一行，也不再需要「关掉以后打不开」的兜底（原设计正是靠工具条入口常驻来解决这个问题）。
|
||||
- 决策（分档坐标）：锚点由 view 的 `placement`（`canvas | run | editor`）落成 `data-generation-tasks-placement`，坐标在样式里分档：资源栏目画布与 UI 编辑器用画布顶边那一档（`top: 3.5rem; right: 0.85rem`），**运行表现层下移到 `top: 7rem`**——它右上角 `top: 20px; right: 20px` 被 C7 版本入口 `game-run-version-picker` 占着，不去抢那一块。
|
||||
- 实现要点：开关改由 view 自己渲染（`data-resource-generation-task-toggle` 与计数属性原样保留，可访问名 `生成任务` 唯一），在途计数只在 view 内算一次、开关与面板头部同源（宿主原先那份 `resourceAssetGenerationInFlightCount` 因此删除）；面板改由 `max-height: min(30rem, calc(100vh - 12rem))` 封顶 + 内部滚动，自己不再定位（坐标只由锚点一处决定）；进场 / 退场动画位移方向跟着锚点翻到正 X。宿主的「点外部收起」判据（排除侧栏本体与 `data-resource-generation-task-toggle`）与「提交受理后自动展开」均未改。
|
||||
- 验证：`resourceCanvasAssetGenerationTasksPanel.test.tsx` 11 passed（新增「折叠只剩右上角开关」「开关计数与面板头部同源」「锚点按工作面分档」）、`resourceCanvasAssetGenerationTasksSidebarStyle.test.ts` 11 passed（锚点坐标 / 运行档下移 / 面板不再自定位 / 开关走 token 且无硬编码色 / 窄屏占满宽度）、`resourceCanvasGenerationTasksSidebarDismiss.test.tsx` 5 passed（入口位置改为右上角锚点、工具条不再有生成任务按钮）、`resourceCanvasAssetGenerationBackgroundClose.test.tsx` 5 passed；`appSurface.test.ts` 538 passed / 17 skipped / 0 failed（与既有基线逐条一致）；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit` 通过。
|
||||
- 影响范围：`apps/ai-game-creator-shell/src/features/resource-canvas/{ResourceCanvasAssetGenerationTasksPanelView.tsx,resourceCanvasAssetGenerationTasksSidebar.css}`、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`apps/ai-game-creator-shell/tests/{resourceCanvasAssetGenerationTasksPanel.test.tsx,resourceCanvasAssetGenerationTasksSidebarStyle.test.ts,resourceCanvasGenerationTasksSidebarDismiss.test.tsx}`、PRD §3.10。未动 Rust、SpacetimeDB、`packages/`、共享弹窗组件。
|
||||
- 已知未覆盖：真实客户端观感（右上角坐标相对画布顶边的落点、与运行表现层版本入口的间距）未在 Tauri 里目视确认；窄屏（≤480px）只有声明级断言。
|
||||
|
||||
## Unity 与 Godot 常用操作指导
|
||||
|
||||
两种编辑器的操作指导复用客户端审核 Skill pack：DirectProject 通过原生 Skill 或既有审核资源读取入口按需取得，Agent Runtime 的对应执行工具说明嵌入同源参考。指南不改变插件可用性、执行授权或 Runner 回执；只读说明不能证明编辑器已连接。常用示例与执行失败/部分修改、保存、撤销边界在同一参考中维护，避免提示词和文档各存一份代码。
|
||||
|
||||
## 2026-09-20 Godot 编辑器执行接入
|
||||
|
||||
原生引导采用固定版本的官方 `godot-cpp` 和 MSVC x64 构建，绑定及 C++ runtime 静态链接。依赖归档和缓存源码须核验，安装目录仍只分发原生载荷及许可。EDITOR 阶段动态加载/卸载时显式清理 C++ 实例绑定与单例包装，保留纯 GDScript 的异步执行和原有协议；执行权限、项目身份与缓存归属继续由现有宿主处理。
|
||||
|
||||
可用性边界按引擎区分：Cocos/Unity 保持不按工程类型过滤，Godot 仍绑定当前 Godot 项目，切项目撤销旧插件上下文；前端统一根据宿主投影启动插件。Runtime 工具目录只对 Godot 追加项目条件，编辑器说明沿用外置提示词及审核 Skill 参考。
|
||||
|
||||
Godot 编辑器操控复用既有 AGC 插件宿主、EditorAdapter、Runner 和不确定执行回执合同，编辑器实现留在 `plugins/agc-godot-editor`。用户选择 DLL 原件随 AGC 安装资源分发，并确认按编辑器实例在 AGC 私有缓存准备临时加载副本，以满足 Godot Windows 加载器的同目录 `~DLL` 写入要求；项目内不复制 DLL，只用受管 `.gdextension` 引导。Godot 自动 UID 伴生文件必须记录归属并在确认卸载后按内容匹配清理。工作区根不迁移到 Godot 子目录，原始项目配置与场景只通过明确编辑操作修改。完整合同及验证范围见 [Godot 编辑器插件接入](<../../technical/【技术方案】AGC Godot编辑器插件接入-2026-09-20.md>)。
|
||||
|
||||
> 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。
|
||||
> 当前口径：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据；如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
|
||||
> 当前口径（2026-09-18）：历史条目的旧路径、旧版本和已退役对象只用于追溯，不构成现行实现依据。策划 Agent V1/V2 的 Runtime、专用命令、审批卡、展示适配和旧测试已删除；当前策划入口统一使用 Design Agent。如与当前代码或 `docs/README.md` 冲突，以当前代码和最新专题文档为准。
|
||||
|
||||
## 2026-09-20 DirectProject 工具并行与交付收敛
|
||||
|
||||
- 所有工具具备有界并行调度能力，MCP 每入口在途上限 8；独立图片在客户端进程内最多 2 个。只保留同资源冲突、编辑器实例、canonical 美术包和短提交事务的必要串行边界。同一付费动作必须在容量排队前取得原 durable 槽锁，不重写幂等算法。
|
||||
- Web 工程由客户端提供经完整性校验的 Node/npm 和浏览器健康预检，保留隔离 HOME；缺失或损坏不能静默退回项目或系统中的另一份 Node。
|
||||
- Direct 回合的合同、证据和预算以宿主私有账本为准，项目侧记录只作展示。GUI/CLI 共用入口；首次副作用前冻结非空验收合同，可信新 Web 工程由宿主补充构建和双端验证底线。普通无副作用聊天不强制构建。
|
||||
- 视觉、固定玩法和托管命令分层；`validation.maxRuns` 按执行/返修批次管理，正常开发命令共享批次；累计执行时间与整轮墙钟分别受 `maxExecutionSeconds` / `maxTurnSeconds` 约束，显式配置与 Provider 重试独立。源码、构建输出、环境输入与证据文件摘要分别复核，项目可编辑记录不能抬高预算或伪造成功。
|
||||
- 原生工具使用已验证的捆绑版本逐次审批能力，第三方 MCP 显式逐调用询问；所有 Direct 入口接受宿主同一状态，未知远端结果不得以本地进程退出代替。独立客户端 HTTP MCP 使用明确的 ExternalClient 来源，保留其既有边界，不借用另一 Direct 回合的预算。
|
||||
- 交付必须先封口、排空和取得执行器退出证明，再核对当前文件并提交完成；Windows 用自有 Job 约束进程树，托管命令在恢复主线程前绑定。完整退出证明不足时保持未完成，不把模型最终回复当作验收。非阻塞扩项进入新的用户回合。
|
||||
- 模型配置、实际请求标识和流分段耗时写入现有审计账本；统计采用并发区间并集，有界后台写入，详细条目截断后仍聚合。上游内部排队和推理耗时不可见时保持未知。
|
||||
- Direct 工具集中 SDK 原生 `apply_patch` / `update_plan` 是全局串行单例，按回合为每个 Direct 连接导出一份只把 `apply_patch_tool_type` 置空的完整模型目录即可移除该注册；其余 metadata、匹配与 fallback 不变，不得伪造 `readOnlyHint` 或改造 SDK。等价能力由宿主 MCP 的 `agc_apply_patch`（官方 parser、当前回合 Write 许可、受控进程树、短项目事务）与 `agc_update_plan`（宿主计划状态，不作为验收证据）提供；缺少合法回包通道的原生问答工具一并关闭。
|
||||
- 捆绑 Codex 固定版本只在 `build_support/codex_bundle.rs` 声明一次（当前 0.155.1），构建期侧车清单、宿主补丁执行器身份、逐次审批协议允许列表和模型目录捕获共同引用；升级原生依赖时同步重取同一 tag 的 vendor 解析源码与 UPSTREAM 证据，并复跑真实目录、补丁往返与并发夹具。0.155 起原生执行入口改为统一 exec（`exec_command` + `write_stdin`，旧 `shell_command` 不再注册），宿主许可与预算照常覆盖。
|
||||
- 付费许可按原回合原租约绑定并传递到实际提交点：容量与同动作锁等待可取消，每次新增 POST 前与封口共用短锁复核，封口/终止/耗尽后零新增提交；已越过提交边界的请求不丢弃，保留 operation ID 与不确定状态走 GET 对账。本地写入同理，等待项目锁后必须复核原许可，未结算或失败的写入围栏未恢复前不得封口。
|
||||
- 权威合同：[AI 游戏创作智能体 App 实施计划](../../technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md)。
|
||||
|
||||
## 2026-09-20 最近项目检查保持项目级隔离
|
||||
|
||||
- 背景：最近项目刷新会重新检查所有路径。若其中一个目录损坏、超时或不可读，清空整张状态表会让已确认正常的项目暂时全部显示“检查中”，用户只能移除坏项目后看到列表恢复。
|
||||
- 决策：最近项目状态按路径独立投影；刷新时保留仍在列表中的最后一次结果，只有新增或尚未检查的项目进入“检查中”。检查代次或列表成员变化后，迟到结果不得写回，单个项目的失败不能改变其它项目的可打开状态。
|
||||
- 验证：`recentProjectsHook.test.tsx` 覆盖“新增慢/坏项目刷新时保留正常项目”；`recentProjectsModel.test.ts`、`unityProjectOpen.test.tsx` 与前端类型检查一并执行。
|
||||
|
||||
## 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`），跨语言一致性只能靠正则解析源码的测试来钉。
|
||||
@@ -22,7 +116,6 @@
|
||||
- 决策（无写副作用）：只在生成本轮 prompt 时展开该上下文；历史 item 回读走 `direct_codex_user_item_to_response_item` 的纯投影，不得触发 UI 代码导出或任何项目写入。
|
||||
- 验证：`agent::direct_codex_user_item` 定向 16 条通过，覆盖成功注入、生成失败保留引用摘要、非 UI 文档不触发与历史回读不产生 `ui/generated-*.js`。
|
||||
|
||||
|
||||
## 2026-09-19 AGC Direct 删除每回合四项媒体资源请求上限
|
||||
|
||||
- 背景：2026-08-24 引入的单回合四项上限以「整个 agent run（一条用户消息到回合结束）」为窗口，计数只增不减、请求完成不释放额度；autonomous 游戏构建要求 agent 不停下跑完整局，额度耗尽后的报错实际是终态，与技能的三次重试纪律冲突，现场表现为长时间无效重试。2026-09-18 先将不计费的抠图豁免，但付费 create/derive 仍受同一窗口问题影响。
|
||||
@@ -36,6 +129,24 @@
|
||||
- 决策：`agc_remove_background` 不再经过 `resource_request_ids` 计数，直接按回合身份与请求指纹确定性派生 operation/idempotency id（与 map 复用结果一致），同指纹重试与 pending 对账语义不变。付费的 create/derive（含 `agc_edit_image` 委托）维持四项上限与原有报错文案，且抠图请求不再挤占其额度。
|
||||
- 验证方式：`cargo check`（ai-game-creator-shell src-tauri）与 `git diff --check` 通过；未新增测试。
|
||||
|
||||
## 2026-09-18 AGC 未提交快速编辑草稿按资源路径归属，正式恢复账本不动
|
||||
|
||||
- 背景：画布验收项 AGC-006/023 要求「点外部 / Esc 收起面板、或换素材卡」不再无条件丢弃用户刚写的提示词与 `@` 引用，于是宿主内存里多了一份未提交草稿表（`resourceCanvasQuickEditModel.ts` 的 `ResourceQuickEditDraftStore`），与原生 `list_pending_local_project_resource_edits` / `resume_local_project_resource_edit` 那条正式可恢复账本**并存**。
|
||||
- 决策：草稿键是投影的稳定身份 `ProjectResource.path`，不是投影 id。资源投影本来就按 path 去重（`resourceProjectionModel` 的 `uniqueByPath`），而 id 会变——任务产物经 `normalize_local_project_raster_resource` 登记成正式素材后，同一张卡从 `task:<任务>:<路径>` 变成 `asset:<id>`。用 id 当键时，任何**不是打开中这一笔快速编辑自身触发**的重投影（换素材卡收起面板、Agent 或外部编辑器把同一路径登记成资产）都会让草稿落到再也点不到的键上：恢复入口按 id 过滤后静默丢弃、重开面板按新 id 查不到。按路径归属后不需要任何「跟着投影搬家」的换键逻辑，那条逻辑本身就是搬丢的来源。
|
||||
- 决策：本地草稿是**会话内存态**——不落盘、不进账本、不参与对账；共享入口「管理未完成编辑」同时列出来源不同的两种条目，草稿条目显式标注「本会话未提交，关闭客户端不保留」，账本读取失败时仍报出本会话草稿条数，避免用户把两者当成同一种持久事实。
|
||||
- 决策：`ResourcePromptPolishSlot` 与共享聊天输入区（`ResourceReferenceInput`）共用 `usePromptPolish`；「与原文相同」以**规范化之后要写回宿主的文本**为准（回包被长度上限截回原文同样算没变化），此时不落原文快照、不回填宿主，只给提示，避免出现点了等于没点的「恢复原文」假入口。
|
||||
- 边界：发送前提醒面板里「AI 润色并发送」遇到原样回包仍按用户意图直接提交，本轮按产品取舍保留（记录在 `docs/project-memory/todos/【待办】画布验收后续修复-2026-09-18.md`）。
|
||||
- 落地：`apps/ai-game-creator-shell/src/features/resource-canvas/resourceCanvasQuickEditModel.ts`（工厂空表 / 按路径写入读取丢弃 / `listResourceQuickEditDraftEntries`）、`apps/ai-game-creator-shell/src/view/project-development/index.tsx`（草稿接线与恢复入口）、`apps/ai-game-creator-shell/src/features/resource-canvas/ResourcePromptPolishSlot.tsx`、`apps/ai-game-creator-shell/src/features/project-workspace/{usePromptPolish.ts,ResourceReferenceInput.tsx}`；回归见 `tests/resourceCanvasQuickEditModel.test.ts`、`tests/resourceCanvasQuickEditDraft.test.tsx`（含「面板收起后旁路重投影」用例，改回 id 作键即红灯）、`tests/usePromptPolish.test.tsx`、`tests/resourcePromptPolishSlot.test.tsx`、`tests/chatPromptPolish.test.tsx`。
|
||||
|
||||
## 2026-09-18 派生资源名称在前端镜像 Rust 门禁，宁可按原话拦下也不截断
|
||||
|
||||
- 背景：快速编辑（`-编辑版`）与角色动画（`-角色动画`）的派生资源名由前端按源资源 label 拼出，直接进 `derive_local_project_resource` 的 `input.assetName`；Rust `normalize_resource_edit_name`（`resource_editor.rs:802-808`）要求 `trim` 后非空、码点数 1..=120 且不含控制字符，任一不满足即整条请求失败。源 label 取任务标题（Agent 回执）或长生成文件名时，用户必须提交一次才看到「派生资源名称必须在 1..=120 字符内且不能包含控制字符」。这是画布验收遗留项 AGC-025 的成因之一。
|
||||
- 决策：前端只做镜像，不另造中文语义——上限 120、`Cc` 控制字符判定（C0 / DEL / C1，`Cf` 继续放行）、`trim` 后判空、按 Unicode 码点计长（Rust `chars().count()`，不是 JS UTF-16 `.length`）四条与 Rust 逐条对齐，提示文案与 Rust 返回串逐字相同；两份判定由跨语言测试直接读 Rust 源码对表。
|
||||
- 决策：名称不合法时**阻止并提示**，不截断。截到 120 会让同前缀的两个长源名塌成同一个名字，把一次可见失败换成一次静默重名；默认名函数因此保持返回不合法原名，由检查结果里的 `error` 让调用方先停下。
|
||||
- 落地：`apps/ai-game-creator-shell/src/view/project-development/resourceEditModel.ts` 的 `RESOURCE_EDIT_NAME_MAX_LENGTH` / `RESOURCE_EDIT_NAME_INVALID_NOTICE` / `resolveResourceEditNameCheck` / `resolveDerivedResourceNameCheck(resource, 'edit' | 'character-animation')`，纯函数与跨语言对表见 `tests/resourceEditModel.test.ts`；两种后缀共用同一张后缀表，避免「-编辑版」与「-角色动画」再次分叉。
|
||||
- 接线：`index.tsx` 的 `submitResourceQuickEdit` 与 `submitResourceCharacterAnimation` 都在**调 `resolveResourceDeriveSource` 之前**做检查（正规化写盘发生在那一步之后），不合法时只把 `status: 'failed'` 与 Rust 原话写进各自的浮层面板并 return，不发派生请求；`assetName` 用检查结果里的 `name`。回归见 `tests/projectResourceLiveIntegration.test.tsx` 的两条「源名超 120 码点」用例与既有的合法名校验 `source-art-编辑版` / `hero-角色动画`。
|
||||
- 边界：资源画布的图片类生成走另一条门禁（`commands.rs` 的 `LOCAL_PROJECT_ASSET_MAX_ASSET_NAME_CHARS`，文案「素材名称超出安全边界」），不在本条口径内；提示词上限仍是 `resourceEditPromptMaxLength` 那一份，本决策不动它。
|
||||
|
||||
## 2026-09-18 Provider 瞬态重试次数严格按设置执行（游戏开发 Agent 与策划 Agent 不再被档位收进区间）
|
||||
|
||||
- 背景：AGC 客户端此前把 `agentLlm.<agent>.maxRetries` 按运行档位重新收进固定区间——`autonomous-game-build` 档位（自主构建的游戏开发 Agent 及其继承档位的专业子 Agent）被抬到 12~16，`standard` 档位（含立项策划入口的策划 Agent 与普通 Agent 对话）被压到最多 3；瞬态分类里的上游 400 还在同一预算上再收窄到 2 次。现场把 `maxRetries` 设成 5 时，游戏开发与策划两条链路都不按设置执行。
|
||||
@@ -49,6 +160,7 @@
|
||||
- 背景：AGC 已通过本地项目 ID 建立并持久化本地项目到主站远端画布项目的绑定，但 `agc_remove_background` 提交请求仍把本地 `manifest.project_id` 放入 `projectId`；`assetFolderId` 已使用远端素材目录 ID。主站因此按项目不存在或不属于当前账号返回 404，主站抠图和 BgFilter 本身均正常。
|
||||
- 决策：抠图请求及工具回执统一使用 `prepare_external_canvas_generation_context` 返回的远端 `context.project_id`；本地 manifest 项目 ID 只用于绑定键和本地状态，不得作为主站业务请求的 `projectId`。
|
||||
- 验证：客户端定向 Rust 测试、格式、编码和 diff 检查通过；未修改主站路由或 BgFilter。
|
||||
|
||||
## 2026-09-17 图集切分模式改为显式声明
|
||||
|
||||
## 2026-09-17 DirectProject 首屏历史锚点只认订阅回执的 lastCompletedItemId
|
||||
@@ -70,6 +182,7 @@
|
||||
- 标准美术包：客户端显式声明 `sliceMode=connected-components` + `sliceCount=4`，本地按用途位置写四张 canonical 切片前再次校验数量正好为四，数量不符时失败关闭，禁止截断或补位。
|
||||
- 测试环境：在提权 shell 的 Windows 主机上，`%TEMP%` 下新建目录的默认所有者是 `BUILTIN\Administrators` 而不是当前 TokenUser，AGC 的所有者校验会拒绝测试自己创建的项目根；测试构建对该情形（仅限 `%TEMP%` 内、且失败原因为所有者不匹配）先按“本调用创建的对象”初始化所有者后重试，临时目录之外的越权所有者继续失败关闭。
|
||||
- 权威合同：[画板图标素材生成入口设计](../../【编辑器】画板图标素材生成入口设计-2026-06-15.md)。
|
||||
|
||||
## 2026-09-17 `agc_tools` 媒体资源提示词上限收敛为单一口径，并按 kind 暴露给模型
|
||||
|
||||
- 背景：有人反馈「客户端没法由 agent 调用图片快速编辑功能以及背景音乐生成功能」。核查后工具本身都在（`agc_edit_image` / `agc_create_or_derive_resource`），图片快速编辑在 2026-09-14 的真实项目日志里也有成功记录；但存在三类真实缺陷：① `agc_create_or_derive_resource` 的 `prompt` 在 schema 里只声明 4000，真实上限却是按 kind 分的（背景音乐 140、音效 1900、视频/角色动画 4000、图片 32000），MCP 层还额外写死了一条 140 判断，模型从 schema 与 skill 都看不出 140/1900，写一句正常长度的背景音乐描述就当场被拒；② 客户端 UI 用同一口径但会截断并提示，agent 侧却只有硬拒，形成「UI 能做、agent 调不动」的观感；③ `sourceLocalAssetId` 不是已登记资源时只报「不属于当前项目已登记资源」，模型会原地重试而不会先登记。
|
||||
@@ -167,7 +280,7 @@
|
||||
- 决策（槽身份 = 精确动作身份）：`run_id = slot-<sha256(动作身份材料)>`，材料为 `prompt / output_path / aspect_ratio / image_size / asset_kind / asset_label / replace_existing / require_slices`（`canvas_generation.rs`）。不同 prompt 或素材名 → 不同槽 → 不同进程锁键与不同 `.lock` 文件 → 可同时在途。**不用随机 uuid**：随机身份会让「同一精确动作重放」落到新路径，必须再造一层 action→ledger 索引才能保幂等；用动作指纹让「槽身份 ≡ 精确动作身份」，路径查找即幂等查找。
|
||||
- 决策（幂等不变）：同一精确动作 → 同一路径 → 命中已有 prepared/accepted 账本并复用原 `idempotencyKey` / `operationId`，不二次 POST；相同动作并发仍被拒的既有语义保持。
|
||||
- 决策（旧槽账本最小懒迁移）：旧槽账本形状可读、不 panic、不 fail-closed；在 durable guard 之后、任何远端 POST 之前，**仅当**旧槽账本的 `agentId / runId / actionFingerprint` 与本次精确动作一致时，把它迁移到新路径（保留 `idempotencyKey` / `operationId` / 状态）并删除旧文件；属于其他动作的旧账本一律不动。旧「固定槽」（`run_id == agent_id`）账本的 fail-closed 拒绝保持原样。
|
||||
- 已知边界：`slice_count` **不进**身份（保留升级前粒度，也是旧账本迁移可行的前提）→ 仅切片数不同的两条图集请求仍共槽、第二条失败关闭；当前所有 standalone 槽的生产调用方都把 `slice_count` 传成 `None`（唯一能传 sliceCount 的是 agent 工具通道，它不走 standalone 槽），该边界当前不可达，但**缺负向用例**。
|
||||
- 当前身份边界：精确动作指纹包含 `slice_count`，Agent 图片工具同样使用 standalone 动作槽；不同精确动作可并行，同一动作在容量排队前持有原跨进程槽锁。不得再依据早期“Agent 不走 standalone 槽”的说明拆除幂等或重复提交。
|
||||
- 前端口径：本批**仍保留单条在途的前端排队**（提交节流），真并行派发需要并发收口设计（配对读 + manifest CAS + 聚焦意图互不覆盖），留待下一批。
|
||||
- 影响范围：`apps/ai-game-creator-shell/src-tauri/src/agent/generation/canvas_generation.rs`、`.../external_generation_state.rs`。**未改** `/api/external/v1` 契约 / OpenAPI / DTO，未改 `recovery_scan.rs`（身份白名单与孤儿清理语义不变），账本 schema 仍是 v3、字段集不变，只改 `runId` 取值来源。
|
||||
- 验证方式：新增 `standalone_generation_binds_each_exact_request_to_its_own_stable_slot`、`distinct_standalone_actions_hold_independent_durable_output_slots`、`concurrent_distinct_standalone_generations_both_succeed_with_one_post_each`（端到端：两条 `outputPath=None` 的不同动作要求两条 POST 同时到达，各自 poll → read-url → 下载 → 落盘）、`legacy_output_slot_ledger_is_adopted_by_the_same_exact_action_only`。变异验证（已实测）：把 `run_id` 退回旧公式 → 4/4 红（含「durable 输出槽身份必须等于该精确动作的身份」与并发用例的「任何远端 POST 前拒绝并发请求」）；把懒迁移短路 → 旧账本用例红。定向 `agent::generation::` + `recovery_scan` 95 passed、`direct_runtime media` 195 passed。
|
||||
@@ -188,6 +301,7 @@
|
||||
- 决策：图片类生成接线改为 `start_local_project_asset_generation` + `list_local_project_asset_generations` 后，同步命令 `generate_local_project_asset` **已无生产调用方**，只剩 `src-tauri/src/tests/project.rs` 的三条集成用例与 `commands.rs` 的自身单测在调它；因此登记进 `scripts/check-config.mjs` 的 native-only 白名单（该门禁有「App invoke 与白名单互斥」断言，谁重新给它接调用方就必须同时删掉这条白名单项）。
|
||||
- 待办：它是**注册中的可调用 IPC**，一旦被将来代码调用就是一条绕过任务账本、单次阻塞最长 35 分钟的并行生成路径。下一批次应删除它，或改为转调 `start_local_project_asset_generation`（连带迁移那三条集成用例）。
|
||||
- 关联文档：[栏目画布底部工具栏入口矩阵](../../technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md)。
|
||||
|
||||
## 2026-09-14 AGC 壳 Rust 套件按「一片一 job」拆分，客户端 Rust 关键路径压到 7 分钟以内
|
||||
|
||||
- 背景：`AI game creator shell Rust tests` 是客户端 CI 的关键路径（run 2097 实测 15 分 27 秒）。拆开来看：前置 5 分 30 秒（checkout 10s + `npm ci` 2m45s + Cargo fetch 2m35s）、编译 1m39s、**AGC 壳 bin target 的 2466 条单测串行 507s**、`agent-run` smoke 51s。这 2466 条全在 `apps/ai-game-creator-shell/src-tauri` 的 bin target 里，一条 `cargo test … -- --test-threads=1` 跑完。
|
||||
@@ -200,6 +314,13 @@
|
||||
- 影响范围：`.gitea/workflows/project-ci.yml`（十一个 job）、`scripts/check-native-shells.mjs`（分组由五个到十个：新增 `agc-rust-crates`、`agc-rust-shard-1..4`、`agc-rust-smoke`，移除 `agc-rust` 与随后的 `agc-rust-shell`）、根 `package.json`、`scripts/project-ci-workflow.test.ts`（新增纯 cargo job 免 `npm ci`、分片运行器覆盖校验、crate 级 job 预热顺序断言）、开发运维文档与共享记忆。本仓库不把 Project CI 的 context 配成 `master` 分支保护的合并必需检查（2026-09-14 复核），合并前由人工确认结果，因此 job 拆分/改名不需要同步分支保护设置。
|
||||
- 验证方式：`npx vitest run scripts/project-ci-workflow.test.ts`；分片运行器本地以 `agent-runtime-core`（7 条 → 2/2/2/1）与 `platform-llm`（146 条 → 49/49/48）验证分片、`--exact` 与片 TMPDIR 隔离，负例 `--shard-index=5` 立即失败；`node scripts/check-native-shells.mjs --groups=contract` 回归。预期每个分片 job 收敛到 5 分钟以内（前置约 1 分 30 秒 + 编译约 1 分 39 秒 + 约 617 条用例）。
|
||||
- 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)、[踩坑记录](pitfalls.md)。
|
||||
|
||||
## 2026-09-20 AGC Rust 分片收敛为两条 lane，匹配 runner 有效并发
|
||||
|
||||
- 背景：四个独立 shard job 让每个 job 重复 checkout、Cargo 依赖预热和测试二进制编译；Gitea run 2105 的 11 个 job 时长合计约 39 分钟，而整轮 wall-clock 为 20 分 23 秒，反推有效并发约 1.9 个 job。继续按「一片一 job」拆分已经把新增 job 开销和排队时间重新放回关键路径。
|
||||
- 决策：保留 4 片名单、`--test-threads=1`、独立 `TMPDIR` 和每片的全集/互斥校验，但把 workflow 收敛为两条 Rust lane；lane 1 顺序运行 shard 1/4、2/4，lane 2 顺序运行 shard 3/4、4/4。每条 lane 只预热一次 AGC 壳 manifest，lane 之间仍保持 job 级并发；不在同一 job 内并行多个测试进程。
|
||||
- 影响范围：`.gitea/workflows/project-ci.yml`、`scripts/project-ci-workflow.test.ts`、`scripts/check-native-shells.mjs` 与 Rust 分片说明文档。job 名称改为 `AI game creator shell Rust lane 1/2`、`lane 2/2`；分组脚本与 4 片测试名单保持不变。
|
||||
- 验证方式：运行 `npx vitest run scripts/project-ci-workflow.test.ts`、`node --test apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.test.mjs`、`npm run check:encoding` 和 `git diff --check`；真实 Gitea run 需要确认两条 lane 均覆盖两片且 smoke、crates、Backend、Native、Frontend、Repository job 仍全部上报。
|
||||
## 2026-09-14 AGC 资源画布改为「手动整理」：新素材不再自动重排，整张重排只由「整理画布」发起
|
||||
|
||||
- 背景：生成一张新素材会让整张资源画布重排。两个 layout hook 都把 `rederiveAutomaticPositions` 打开（type 侧无条件 `true`，dependency 侧长期等于 `resourceGraphReady`），而该开关的语义是「每次资源协调签名变化就丢掉全部 `manuallyPlaced=false` 坐标、按当前资源与拓扑整体重算」；新增一张素材必然改签名，于是既有自动卡全部跟着挪位，用户刚记住的位置就没了。画布上也没有任何显式整理入口（`复位资源视图` 只复位视口）。
|
||||
@@ -223,7 +344,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 +8976,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
|
||||
|
||||
@@ -8886,7 +9008,6 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
|
||||
- 影响范围：新增 `apps/ai-game-creator-shell/src-tauri/src/asset_generation_tasks.rs`（+ `main.rs` 注册）、`src/features/resource-canvas/{resourceCanvasAssetGenerationTaskModel.ts,resourceCanvasAssetGenerationQueue.ts,ResourceCanvasAssetGenerationTasksPanelView.tsx}`；改动 `ResourceCanvasAssetGenerationPanelView.tsx` / `ResourceCanvasGenerationPanelView.tsx` / `src/view/project-development/index.tsx`；测试改动 `tests/{resourceCanvasAssetGenerationBackgroundClose.test.tsx,resourceCanvasAssetGenerationQueue.test.ts,resourceCanvasAssetGenerationTasksPanel.test.tsx}`（新增）与 `tests/appSurface/project-development.suite.ts`（把「每个入口一次 `generate_local_project_asset`」改成 `start_local_project_asset_generation` + `list_...` 轮询桩，载荷断言逐字不变）。**未动**：external v1 / OpenAPI、`packages/`、SpacetimeDB、音频入口的 pending-edit 账本语义、生成参数与 IPC 载荷字段名。
|
||||
- 关联文档：`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`（§4 / §4a / §8）、`docs/technical/【测试用例】AGC资源工作台V3端到端验收-2026-09-11.md`（S11a / §7.3）。
|
||||
|
||||
|
||||
## 2026-09-15 非 Suno 的 VectorEngine 能力切换到 Tiantoken
|
||||
|
||||
- 决策：新增本地私密环境变量 `TIANTOKEN_BASE_URL` / `TIANTOKEN_API_KEY`（图片 timeout 可独立配置），承载原 VectorEngine 的文本和图片；`VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 仅保留给 Suno 背景音乐与 Suno 音效。编辑器 SFX V2 继续走 ElevenLabs。
|
||||
@@ -8911,6 +9032,7 @@ CI 上 `background_agent_runtime_recovers_stale_running_before_pending_task` 在
|
||||
- 决策：平台会话拆成身份（`userId + api origin + identity generation`）与凭据（当前 access token）。identity generation 只在登录、切号、登出或新的 GUI authority epoch 推进；同账号续期只更新凭据并推进只用于拒绝迟到写入的 revision。冻结会话校验、MCP 会话身份与 Runner attach 统一按身份判定，换号 / 退出仍然失败关闭。刷新失败只在服务端明确 401/403 且一次收敛重试后仍失败时清会话；`/api/auth/refresh` 的轮换失败不再下发清空 refresh cookie 的响应。
|
||||
- 关联规范：`docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md` 的“2026-09-16 平台会话身份与凭据分离”；开发期计划见 `docs/project-memory/plans/【里程碑】平台会话身份与凭据分离-2026-09-16.md` 与对应实施计划。
|
||||
- 验证：AGC `platform_session::tests`、`runner::tests`、`assets::tests` 定向通过；AGC `appSurface` 前端套件 468 项通过；网站 `src/services/apiClient.test.ts` 33 项通过；`cargo test -p api-server refresh_session` 通过。项目夹具类 Rust 用例受本机临时目录属主为 `BUILTIN\Administrators` 的环境限制，未计入本次证据。
|
||||
|
||||
## 2026-09-15 Direct 回合跨页面继续运行与活动项目面板
|
||||
|
||||
- 决策：采用后台继续运行语义。Direct 回合由进程内项目身份锁持有，页面离开不取消；重进项目通过活动回合只读快照与 Thread Manager bootstrap/consume 恢复忙碌态和进度。左上角面板复用同一快照列出正在运行的 Direct 项目并支持进入。
|
||||
@@ -9009,3 +9131,51 @@ 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 结果仍待验证。
|
||||
|
||||
## 2026-09-20 AGC 客户端版本号收敛为单一发号源
|
||||
|
||||
- 客户端版本号唯一事实源改为 OSS `agc/global-version.json`；渠道清单只写本次拿到的号，仓库里 5 个版本文件只作构建输入参考。
|
||||
- 发号顺序固定「先写总号 → 再构建 → 再发渠道清单」，失败不回滚只烧号；统一构建发一次号供 `dev-win` / `dev-mac` 共用，单渠道热修只作用于该渠道。
|
||||
- 发号收口到 Jenkins Job `Genarrative-Agc-Global-Version-Issue`（`disableConcurrentBuilds()`；集群无 `lockable-resources`，以写后回读不一致即失败关闭兜底并发）。
|
||||
- 原渠道高水位逻辑降级为断言：请求号低于本渠道清单版本即失败关闭；`AGC_RELEASE_DRY_RUN` 只预览不烧号。
|
||||
|
||||
## 2026-09-20 AGC 音频生成并入图片类那份后台任务账本
|
||||
|
||||
- 背景：音频栏目的「生成背景音乐 / 生成音效」原先走同步派生通道（`derive_local_project_resource`），提交后前端一直等到生成结束（最长 35 分钟），所以它不出现在画布「生成任务」侧栏里，也没有本地排队；图片类早已改成「提交即返回 + 项目内任务账本」。
|
||||
- 决策：音频改走**同一条命令** `start_local_project_asset_generation`（新增可选入参 `idempotencyKey`，音频 kind 必带）；原生在 `kind` 上分叉一次（`is_audio_asset_generation_kind` 只放行 `sound-effect` / `background-music`），音频分支落**同一份**项目内账本 `.agent/runtime/asset-generation-tasks/tasks.json`，生成由 `run_local_project_audio_generation_task` 在后台跑并写 running → completed / failed。图片类载荷与分支逐字未改。
|
||||
- 决策：音频的**任务 id 就是这次生成的 operation id**，请求身份 = 面板铸造的 `operationId` + 幂等键。重试（含失败后点占位重开）必须复用同一对，否则会同一次生成变成第二次付费请求。账本不存幂等键，所以重开项目恢复出来的音频任务只用于展示与定位，不承接重试。
|
||||
- 决策（UI 口径）：音频面板与图片类一致——点「生成」**同步关闭**，面板里不存在「排队中。」「正在生成。」「提交中…」与「后台运行并关闭」这类阶段文案与在途按钮，阶段文案的唯一来源是后端账本、唯一去处是「生成任务」侧栏。只有「点击瞬间就失败」（校验 / 权限 / 提交 IPC 立即报错，即后端从未受理）才由宿主把面板连原草稿与原请求身份带回来；受理之后才失败只在侧栏收口为失败。
|
||||
- 决策（时机）：项目 revision 的 CAS 由「提交前读」改为「派发时刻读」（`run_local_project_audio_generation_at`）；冲突按失败收口，不静默重试，避免把生成写到用户没预期的基线上。
|
||||
- 不变口径：平台侧 `/api/editor/audios/*/generations` 路由、请求体、计费与 `/api/external/v1`、OpenAPI、共享 DTO、SpacetimeDB schema 一律未动；音频仍复用既有资源编辑派生实现，不复制生成逻辑。
|
||||
- 关联规范：`docs/prd/【AI游戏创作】项目开发工作台PRD-2026-07-20.md`（§3.10 / §7.9）、`docs/technical/【AGC】栏目画布底部工具栏入口矩阵-2026-09-13.md`、`docs/project-memory/plans/【里程碑】AGC音频生成进入后台任务账本-2026-09-20.md`。
|
||||
- 验证：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` 全部通过；未跑真实付费生成。
|
||||
|
||||
## 2026-09-20 派生/修改类任务并入「生成任务」侧栏（AGC-039 / AGC-040）
|
||||
|
||||
- 背景：客户端验收现场，快速编辑提交后画布右上角「生成任务」全程是「还没有生成任务」，同一条草稿又还挂在「管理未完成编辑」里，用户据此判断「点了没生成」；随后同一次修改被重复提交，同一张源图派生了两份一模一样的「-编辑版」。
|
||||
- 决策（取数）：派生/修改类任务（快速编辑、生成动画、视频 / 音效 / 背景音乐、抠图）进图片类生成任务**同一个**「生成任务」侧栏，数据源 = 原生资源编辑账本 `list_pending_local_project_resource_edits`（重开项目、别处提交、阶段文案以后端为首）+ 本会话**本地提交记录**（按下提交当帧即可见），两边按 `operationId` 合并去重。**不改**原生资源编辑账本 schema，也**不**把派生任务写进图片类生成账本 `.agent/runtime/asset-generation-tasks/tasks.json`——两套账本各管各的事实，只在视图层合并。
|
||||
- 决策（草稿口径）：提交进行中的那一笔不再列进「管理未完成编辑」；失败回落自动把它还回未完成列表，提示词与 `@` 引用不丢。
|
||||
- 决策（重复提交）：同一张素材存在在途提交时，重新打开面板再提交会被拦下（可见原因），不重铸 operation 身份。**未做**「同提示词成功后再提交」的去重——那是用户显式重复的付费动作，本批只消除误触来源。
|
||||
- 理由：用户对「生成」的心智是「交出去就得能看见它在跑」，而不是必须区分两条账本；而防重复必须在**身份重铸之前**拦，等到原生账本判重时已经派生过一次。
|
||||
- 验证：新增模型用例 9 条、快速编辑两组宿主用例（提交当帧进侧栏并收口 / 在途重复提交被拦），两处新判据做过变异验证；定向 7 个文件 97 条全绿。
|
||||
- 口径更正（2026-09-21）：当时记的「`appSurface` 16 条既有失败」是**从 `apps/ai-game-creator-shell` 目录跑**造成的 cwd 假红（`resolve(process.cwd(), 'apps/…')` 路径翻倍 → ENOENT），不是用例本身红。规范跑法是仓库根 `npm test`；现已用 `tests/repoPath.ts`（按 `import.meta.url` 反推仓库根）修掉 19 个文件的同类写法，从仓库根跑 `appSurface` 为 0 失败。远程 CI 与真实客户端验收仍未跑。
|
||||
|
||||
## 2026-09-21 卡片浮层改为「提交即关」：快速编辑 / 生成动画只负责交任务
|
||||
|
||||
- 背景：客户端验收反馈——「生成动画」这类卡片浮层在失焦时不会收起，而且这块的关闭判据一直是东一处西一处拼的（点画布空白、换选中卡、Esc、点画布以外各有一条）；动画面板在生成中还会被「生成中不关」判据锁在画布上。产品口径澄清：生成都归「生成任务」侧栏，**卡片浮层只用于提交任务，提交完生命周期就结束**。
|
||||
- 决策（提交即关）：快速编辑 / 生成动画点提交当帧即关面板，不等 IPC、不留等待态；阶段与结果只由「生成任务」侧栏承载（本地提交记录 + 原生待办按 `operationId` 合并，见 2026-09-20 那条）。只有**点击瞬间就失败**留在面板里；**受理之后才失败**把侧栏收口为失败 + 提示条并回落草稿，不重开面板。
|
||||
- 决策（身份跟着资源走）：按「入口 + 资源路径」记最后一次派生请求（`resourceEditRequestKey`）。重开面板再提交时提示词没变就沿用同一 `operationId` / 幂等键，重试仍命中同一 operation 账本；派生成成功即清掉，下一次编辑是新的一笔。原「按上次打开的 sourceLayerId 复用」在提交即关之后不再成立（面板重开时层 id 可能已被重投影换掉）。
|
||||
- 清理：`canDismissResourceCanvasQuickEdit`（生成中的浮层不参与清焦点）与宿主里两个只为它服务的面板状态 ref 一并删除；`clearResourceCanvasFocus` 恢复成「清选中 + 关两块浮层」的直线逻辑。
|
||||
- 影响面：`apps/ai-game-creator-shell/src/view/project-development/index.tsx`、`.../features/resource-canvas/resourceCanvasFocusModel.ts`、`tests/{projectResourceLiveIntegration,resourceCanvasQuickEditDraft,resourceCanvasFloatingDismiss}.test.tsx`、PRD §3.10。
|
||||
- 验证：定向 `projectResourceLiveIntegration`（32 条，三条断言面板留在失败态的用例按新口径改写为「重开面板再重试，身份不变」）、`resourceCanvasQuickEditDraft`（10 条）、`resourceCanvasFloatingDismiss`（18 条）全绿；`npm --prefix apps/ai-game-creator-shell run typecheck` 通过。
|
||||
- 合并前复核（2026-09-21）：合并 master 后按**仓库根**跑全量 `npx vitest run`，**373 个测试文件全过、4512 通过 / 34 跳过 / 0 失败**；PR #419 显示 `No Conflicts`。真实客户端观感与远程 CI 未复验（后者按用户要求不追，runner/镜像问题见 Issue #431）。
|
||||
|
||||
@@ -20,46 +20,54 @@
|
||||
|
||||
完整规则和模板见 [`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 入口先执行这组检查，再运行分片单测。
|
||||
|
||||
提示词测试验证实际请求中的片段来源、动态参数和工具结构；措辞不作为逐字契约。已有行为测试覆盖的限制不再另设整段文案检查。Direct 回合测试复用生产的消息转换和文件投影函数，不维护仅供测试调用的回合编排副本。
|
||||
|
||||
AGC 预览快捷操作的界面测试按独立命令或有状态短流程注册，每例重新建立 fixture、原生调用 mock 和页面，并等待项目打开后再记录调用计数。预览启停、导出确认与取消等连续行为保留在同一用例；互不依赖的只读命令不串成一条长对话，也不共享 DOM 或提高超时来容纳整组流程。
|
||||
|
||||
Rust 分片失败日志保留有界的失败详情，包括 panic 位置、断言和最终通过/失败数量；分片选中数量标为 selected，避免误读为失败数量。修改分片日志时运行 `node --test apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.test.mjs`，用最小 Rust fixture 验证失败详情和成功摘要。
|
||||
|
||||
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 架构边界和验证门禁。
|
||||
|
||||
按改动范围选择定向门禁，不以无关全量扫描代替契约验证：
|
||||
按改动范围选择定向门禁：
|
||||
|
||||
| 范围 | 至少运行 |
|
||||
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
||||
@@ -82,8 +90,8 @@ SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.m
|
||||
|
||||
## Jenkins 定时版本调度
|
||||
|
||||
定时与版本比较只保留在 `Genarrative-Scheduled-Revision-Trigger` 一处：每小时用 `git ls-remote` 解析 `SOURCE_BRANCH` 远端 HEAD，与上一次触发过的 revision 比较，变化时才把同一个 `COMMIT_HASH` 同时传给 `Genarrative-Full-Build-And-Deploy` 与 `Genarrative-Agc-Windows-Build`，保证两条管线构建同一个版本。`Genarrative-Full-Build-And-Deploy` 与 `Genarrative-Agc-Windows-Build` 不得自带 `triggers` / `cron`，也不得在管线内再做一套版本去重；`npm run check:production-ops` 会拦住这两类回退。调度状态与生效步骤见 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
定时与版本比较只保留在 `Genarrative-Scheduled-Revision-Trigger` 一处：每小时用 `git ls-remote` 解析 `SOURCE_BRANCH` 远端 HEAD，与上一次触发过的 revision 比较，变化时才把同一个 `COMMIT_HASH` 传给 `Genarrative-Full-Build-And-Deploy`，并先经 `Genarrative-Agc-Global-Version-Issue` 发号、再把同一个总版本号透传给 `Genarrative-Agc-Windows-Build` 与 `Genarrative-Agc-MacOS-Build`，保证两个客户端的平台分区发布同一个版本。这三个下游 Job 都不得自带 `triggers` / `cron`，也不得在管线内再做一套版本去重；`npm run check:production-ops` 会拦住这两类回退。macOS 节点是日常办公机，调度触发它时置 `SKIP_IF_SUPERSEDED=true`：节点离线期间排队的旧构建在恢复后会自行让位，不发布过期版本。调度状态与生效步骤见 `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
## Gitea CI 依赖闭合
|
||||
|
||||
`.gitea/workflows/project-ci.yml` 的客户端门禁拆成八个 job，每个 job 只预热自己会构建的那几份依赖：`AI game creator shell Rust shard 1/4` 到 `4/4` 各只预取 AGC 壳 manifest 并各跑一片（AGC 壳那份 `Cargo.lock` 的 path 依赖已含 `platform-llm`、`platform-agent`、`agent-runtime-core` 与 `shared-contracts`），`AI game creator shell Rust smoke` 同样只预取 AGC 壳 manifest（`agent-run` smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`），`AI game creator shell Rust crates` 预取 `server-rs/Cargo.toml` 与两个独立 crate，`Native shell tests` 预取桌面壳与 AGC 壳 manifest，`AI game creator shell web tests` 不触碰 Cargo，不预热。AGC 壳的 4 个分片 job、smoke job 与 crates job 只用 cargo 与 node 内建模块，因此不执行 `npm ci`。两个被 `server-rs/Cargo.toml` 排除、且没有提交 `Cargo.lock` 的独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）只能在 `AI game creator shell Rust crates` 里用不带锁标志的 fetch。AGC 壳的 bin target 单测（约 2466 条）由 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs` 编译一次后按 `--list` 名单分 4 片：CI 的每个分片 job 用 `--shard-index=<i>` 只跑自己那片，片内保持 `--test-threads=1` 并各自使用独立 `TMPDIR`，片与片之间靠 job 级并发摊开；本地不传 `--shard-index` 时仍是同一条命令把 4 片放进程里并行。不要改回「一个 job 内多进程并行这几片」——同一容器里它们会争抢共享 `HOME`、target 目录与固定临时路径，实测比整套串行还慢。每个分片 job 都会自校验「片并集等于全集且互斥」，因此改分片规则不会静默漏跑。Backend host workspace tests 使用 `cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`，避免 `spacetime-module` 的 `spacetime-types` feature 统一污染普通领域 crate 的 host 测试；随后单独执行 `cargo test --locked -p spacetime-module --no-fail-fast`，由 `spacetime-module/src/active.rs` 在 host 测试构建期间提供仅测试期的 SpacetimeDB ABI 链接支持，使该 crate 的纯单元测试也纳入 Backend 门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，host 链接支持不得被当作运行时替身。Backend 另外执行 `cargo check --locked -p spacetime-module` 验证模块源码。AGC 壳检查还会运行 `platform-llm` 与 `shared-contracts` 的 server-rs workspace 测试，这些命令以及 AGC 壳测试必须带 `--locked`，避免在测试阶段重新解析 registry index；锁文件发生变化时应先更新受信任 CI 镜像缓存，再重跑门禁。
|
||||
`.gitea/workflows/project-ci.yml` 的客户端门禁拆成 lane 与功能 job，每个 job 只预热自己会构建的那几份依赖：`AI game creator shell Rust lane 1/2`、`lane 2/2` 各自预取一次 AGC 壳 manifest，并顺序运行两片 Rust bin 单测；`AI game creator shell Rust smoke` 同样只预取 AGC 壳 manifest（`agent-run` smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`），`AI game creator shell Rust crates` 预取 `server-rs/Cargo.toml` 与独立 crate，`Native shell tests` 预取桌面壳与 AGC 壳 manifest，`AI game creator shell web tests` 不触碰 Cargo，不预热。两条 Rust lane、smoke job 与 crates job 只用 cargo 与 node 内建模块，因此不执行 `npm ci`。两个被 `server-rs/Cargo.toml` 排除、且没有提交 `Cargo.lock` 的独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）只能在 `AI game creator shell Rust crates` 里用不带锁标志的 fetch。AGC 壳的 bin target 单测（约 2466 条）由 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs` 编译后按 `--list` 名单分 4 片：每次分片调用用 `--shard-index=<i>` 只跑自己那片，片内保持 `--test-threads=1` 并使用独立 `TMPDIR`；两条 lane 之间并发，lane 内顺序运行两片，避免重复依赖预热和同一容器内多进程争抢。不要改回「一个 job 内多进程并行这几片」——同一容器里它们会争抢共享 `HOME`、target 目录与固定临时路径，实测比整套串行还慢。每个分片调用都会自校验「片并集等于全集且互斥」，因此改分片规则不会静默漏跑。Backend host workspace tests 使用 `cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`，避免 `spacetime-module` 的 `spacetime-types` feature 统一污染普通领域 crate 的 host 测试；随后单独执行 `cargo test --locked -p spacetime-module --no-fail-fast`，由 `spacetime-module/src/active.rs` 在 host 测试构建期间提供仅测试期的 SpacetimeDB ABI 链接支持，使该 crate 的纯单元测试也纳入 Backend 门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，host 链接支持不得被当作运行时替身。Backend 另外执行 `cargo check --locked -p spacetime-module` 验证模块源码。AGC 壳检查还会运行 `platform-llm` 与 `shared-contracts` 的 server-rs workspace 测试，这些命令以及 AGC 壳测试必须带 `--locked`，避免在测试阶段重新解析 registry index；锁文件发生变化时应先更新受信任 CI 镜像缓存，再重跑门禁。
|
||||
|
||||
@@ -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,48 @@
|
||||
# 踩坑与排障记录
|
||||
|
||||
## copyArtifacts 报「Unable to find project for artifact copy」的用户触发构建差异
|
||||
|
||||
Copy Artifact 插件在**非 SYSTEM 认证**下按「认证用户」判权：只有当被复制 Job 的 `CopyArtifactPermissionProperty`（仓库里由 Declarative 的 `copyArtifactPermission(...)` 维护）显式列出当前消费者，或者该 Job 对认证用户开放 Item.Read 时才放行；`ACL.SYSTEM2` 的定时构建会短路通过。因此会出现「定时调度一路成功、手动发布必挂」的现象（2026-09-21 手动发布 #6/#7 与同期的用户触发探测全部命中，定时调度 #104+ 正常）。`Genarrative-Agc-Global-Version-Issue` 生产权限模式的授权名单必须同时包含 `Genarrative-Scheduled-Revision-Trigger` 与 `Genarrative-Manual-Build-And-Deploy`；改完 `copyArtifactPermission` 后要先跑一次发号 Job 把 Job property 写回 Jenkins，只改仓库文件不生效。
|
||||
|
||||
## 同一条链路两处上限不一致：平台合法产出被客户端整条丢弃
|
||||
|
||||
- 现象：客户端报「生成素材失败：platform-generation-result-unknown: 异步生成完成结果无法绑定到 operationId：External Editor 旧同步结果的图集切片超过 64 个」，而平台侧这次生成**其实已经成功并切完图**（任务账本耗时正常、`assetId` 为空、没有任何素材落盘，付费产物被丢）。
|
||||
- 成因：图集切片上限在链路里存在两份字面量——平台切分、Agent 工具 schema `sliceCount` 与持久化产物批次都是 256，客户端结果绑定门写着 64（`agent/generation/{canvas_generation.rs,external_generation_state.rs}`）。自动切分（`connected-components` + `sliceCount=null`）切出 65~256 片是合法产出，客户端比平台更严就会把结果整条判失败。
|
||||
- 处理：客户端门统一到 `PLATFORM_ART_SPRITESHEET_MAX_SLICES = 256`，判据与文案各只留一份（数字由常量插值），并在注释里点名三处同值权威（平台切分常量、工具 schema、公开契约）。
|
||||
- 复用判据：凡是「平台产出 → 客户端校验后落盘」的链路，客户端门只能表达**安全 / 预算**约束，不得比平台的产品上限更严；两边上限要引同一个常量或同一份文档，改一边时必须同时改另一边，并补一条「上限之内必须能落盘」的回归用例。
|
||||
|
||||
## Jenkins Windows 节点的 PATH 白名单决定 Godot 原生扩展能否构建
|
||||
|
||||
`Genarrative-Agc-Windows-Build` 在阶段里用 `AGC_WINDOWS_PATH` 整体替换 PATH、不继承节点机器的 PATH，所以 Godot C++ 引导需要的 CMake 与 Python 必须显式写进这份白名单，装在机器 PATH 上并不生效。2026-09-21 的 #97–#99 连续失败都停在 `Get-Command cmake.exe`（#93–#96 是更早的手写 C ABI 在 MSVC C 模式下的对齐问题）：节点只有 Visual Studio Build Tools（`C:\BuildTools`）自带的 CMake 3.31，缺 Python 3。修复后白名单包含 `C:\BuildTools\Common7\IDE\CommonExtensions\Microsoft\CMake\CMake\bin`、`C:\Python312`、`C:\Python312\Scripts`，preflight 校验 CMake ≥3.25、Python 3 和 Visual Studio 17 2022 生成器；把 `cmake.exe` 单独复制到别的目录会丢掉 `share/cmake-*/Modules`，不能替代加入安装目录。新节点的 Python 用 `python-3.12.10-amd64.exe /quiet InstallAllUsers=1 TargetDir=C:\Python312 PrependPath=1 Include_launcher=1 InstallLauncherAllUsers=1` 静默安装即可，CMake 不必另装。
|
||||
|
||||
## Tauri `--no-sign` 会连带跳过 updater 签名
|
||||
|
||||
AGC macOS 发布入口一度传入 `--no-sign`（目的是绕过没有 Apple 证书的代码签名），结果 Tauri 打印 `Warn Updater signing is skipped due to --no-sign flag.`，产物只有 `*.app.tar.gz` 而没有 `.sig`，发布入口按设计在「缺少更新包签名」处失败关闭（2026-09-20 首次 Jenkins 实跑命中）。正确做法是不传 `--no-sign`，改为剥离 `APPLE_*` 凭据让 Tauri 跳过 Apple 签名——minisign 更新包签名与 Apple 代码签名这两个开关在 Tauri 里并不独立。Apple 签名状态要按 `codesign -dv` 实测记录，不能硬编码。
|
||||
|
||||
## 复用 workspace 的构建必须显式清理本次要写的产物
|
||||
|
||||
Jenkins workspace 跨构建保留：上一轮失败留下的同名 `陶泥儿_<version>_universal.dmg` 会让 `hdiutil create` 以「文件已经存在」失败，而上一轮遗留的 `*.app.tar.gz.sig` 更危险——本轮即使没签出签名，验签门禁也会读到旧签名而误判通过。构建入口必须在构建前删除本次将写出的确切路径（更新包、签名、同版本 DMG 及其校验文件、`latest.json`、`release-notes.txt`），`hdiutil create` 同时用 `-ov`，让「归档里的产物来自本次构建」成为结构性事实而非假设。
|
||||
|
||||
## AGC macOS 单次构建耗时集中在主 crate 重复编译
|
||||
|
||||
AGC 主 crate（`genarrative_ai_game_creator_shell`）单架构 codegen 约 15–20 分钟，而每次 Tauri 构建都会重新生成前端 `dist`，`build.rs` 对 `dist` 目录的 `rerun-if-changed` 因此每次都判定变化，导致两个架构各重编一次主 crate。实测：`CARGO_BUILD_JOBS=4` 时首次 Jenkins 构建 78 分钟，提到 6 后为 41–43 分钟且成功；依赖 crate 走 sccache 与 target 缓存，首轮 0 命中属预期。剩余优化空间在「不必要地重建 dist」这一层，需单独设计（例如按内容摘要决定是否重跑前端构建），不要在发布入口里用假缓存换取速度。
|
||||
|
||||
## Godot C++ 扩展构建与对象生命周期
|
||||
|
||||
- 原生引导通过官方 `godot-cpp` 管理 Variant、String 和 Ref，不自行维护 ABI 存储。Godot 类型必须在扩展终止回调内释放，不能依赖 DLL 静态对象析构；桥节点可能已经退出，应按实例 ID 核验存活再回调。
|
||||
- 正式 Windows 构建使用 CMake 的 Visual Studio x64 generator，并实际验证 MSVC 编译；不能用 GCC 成功替代 MSVC 验收。固定官方归档按 SHA256 校验，缓存源码被修改时拒绝构建并保留证据。
|
||||
|
||||
## 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']` 字符串清单里，判据恒假：生成面板重新给图集渲染参考图选择器，原生提交再按合同显式拒绝多余参考。
|
||||
@@ -12,6 +55,11 @@
|
||||
- **现象**：`GameCreationAppAssetKind` 的 ts-rs `export_to` 从 `apps/ai-game-creator-shell/src/contracts/generated/` 换到 `packages/shared/src/contracts/generated/` 后，任何 `cargo build` / `cargo test` 都会重写生成文件；若新目录没进 `.prettierignore` 与 `.eslintrc.cjs` 的 `ignorePatterns`，lint-staged / prettier 会把生成物重新格式化，于是每次提交都出现「生成物被改」，`cargo test export_bindings` 也不再幂等（跑完 `git diff` 不为空）。
|
||||
- **处理（现行口径）**：生成目录一律成对登记 `.prettierignore` + eslint `ignorePatterns`；改 `export_to` 时同步改这两处，并用 `cargo test --locked -p shared-contracts --features ts-bindings export_bindings --manifest-path server-rs/Cargo.toml` 后 `git diff` 为空来验证幂等。
|
||||
- **易错点**：旧的 `apps/ai-game-creator-shell/src/contracts/generated/` 目录下的同名文件不会自动删除，换目录后必须显式删除旧文件，否则会出现「两个同名 union，改动只落在一个目录」的假绿。
|
||||
|
||||
## universal 主程序必须配套双架构原生依赖
|
||||
|
||||
AGC macOS 主程序可合并为 universal，但 Codex 原生包的 `codex-package.json`、code-mode host 和 zsh 仍有架构身份。两套包应各自保留上游布局与摘要，放入 `coding-agent/mac-native/darwin-arm64/`、`darwin-x64/`，由正在运行的主程序切片选择；不能只把主程序用 lipo 合并后复用最后一次构建的单架构资源。Tauri universal 两次 Cargo 构建共用 staging，每次都必须 stage 完整的两套资源。发布清单两个平台键同 URL/签名，只在 universal 产物上成立；Rosetta 隔离 smoke 不代替 Intel 真机验收。
|
||||
|
||||
## 生成草稿与异步展示边界必须按身份隔离
|
||||
|
||||
非模态生成浮层切换占位时按 draftId 分实例，卸载保留未提交/失败草稿，成功提交不再复活草稿；旧项目占位不存在时丢弃其保存回调。失败重试保留原请求输入和引用身份，引用失效不能静默过滤；修改已绑定输入须明确另起请求，不伪装成原请求重试。
|
||||
@@ -119,7 +167,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
|
||||
|
||||
- **现象**：`AI game creator shell Rust tests` 一直是客户端 CI 的关键路径。run 2097 实测 15 分 27 秒，其中 `apps/ai-game-creator-shell/src-tauri` 的 bin target 单测（2466 条）一条 `cargo test -- --test-threads=1` 串行占 507 秒。
|
||||
- **为什么原本是整个 suite 串行**：2026-07-21 `a273377b1` 的判据是「共享 Agent Runtime 后台锁与异步终态在 libtest 并行调度下互相干扰」，即**同进程内**的全局后台锁、异步终态与进程级 static 被交叉触发；另有少数用例自身 spawn 当前测试二进制（`std::env::current_exe()`）跑 fixture，会碰容器里共享的 target 与固定临时路径。
|
||||
- **处理（现行口径）**：新增 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs`：`cargo test --no-run` 编译一次后用 `--list` 名单把用例按 `index % shards` 切成 4 片，CI 的每个分片 job 用 `--shard-index=<i>` 只跑自己那片（`--exact <名单> --test-threads=1`，片内串行），片与片之间靠 **job 级并发**摊开。配套把 `ai-game-creator-shell:check:rust` 拆成 `:rust:crates` 与 `:rust:shell`，AGC 相关门禁在 CI 里共 6 个 job（4 个分片 + smoke + crates）。
|
||||
- **处理（现行口径）**：新增 `apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs`：`cargo test --no-run` 编译后用 `--list` 名单把用例按 `index % shards` 切成 4 片，CI 的每次分片调用用 `--shard-index=<i>` 只跑自己那片（`--exact <名单> --test-threads=1`，片内串行）；两条 Rust lane 各顺序运行两片，lane 之间靠 **job 级并发**摊开，避免每片重复依赖预热。配套把 `ai-game-creator-shell:check:rust` 拆成 `:rust:crates` 与 `:rust:shell`，AGC 相关门禁在 CI 里由两条 lane、smoke 和 crates job 承载。
|
||||
- **反面实验（run 2102，勿重做）**：起先把 4 片放进**同一个 job** 内的 4 个进程并行，结果门禁步骤跑满 18 分钟仍未结束，比整套串行的 507 秒还慢——同一容器内这几片共享 `HOME`、target 目录与固定临时路径，会互相拖慢。因此 `--shard-index` 是 CI 的唯一入口；不带 `--shard-index` 的「单命令内多片并行」只留给本地全量自测。
|
||||
- **易错点**：① 分片规则必须自校验「片并集等于 `--list` 全集且互斥」，否则改分片方式会静默漏跑门禁；② 每片要拿独立 `TMPDIR`，`tempfile::tempdir()` 默认落在它下面（测试里的硬编码 `/tmp/...` 多是「必须拒绝」的负向断言，不是真实读写）；③ 不要给分片 job 装 `npm ci`——AGC 壳 Rust 门禁与 `agent-run` smoke 只用 cargo 与 node 内建模块，那些 `npm ci` 正是达标 7 分钟的主要障碍；④ 片 job 只需预热 AGC 壳自己的 manifest（其 `Cargo.lock` 的 path 依赖已覆盖 `platform-llm` / `platform-agent` / `agent-runtime-core` / `shared-contracts`），`server-rs` 那份预热属于 crate 级 job；⑤ 分片后 `--test-threads=1` 不再出现在 workflow 里，但它是分片运行器的片内参数，别再往 workflow 里补整套串行命令。
|
||||
- **不要做的事**：不要退回「整套 `--test-threads=1`」（507 秒长尾回来了），不要放开成整套并行（同进程内后台锁与异步终态会再互相干扰），也不要在单个 job 内多进程并行多个片（实测比串行还慢）。
|
||||
@@ -146,7 +194,7 @@ Direct 工具桥会 canonicalize 项目根，事件中的路径可能带 `\\?\`
|
||||
|
||||
- **现象**：把 `Native shell tests` 拆成客户端三个 job 后，如果只跑 `npm run check:native-shells:release`，静态契约和壳运行时门禁都不会执行；如果只跑 `--groups=contract`，`desktop-release-binary-artifact` 又会因为缺少 `build/native/desktop/` 产物而失败。
|
||||
- **原因**：分组是执行范围，不是"额外检查"。`desktop-release-binary-artifact` 断言依赖同 job 内的 `desktop-shell-stage-release-binary` 步骤，所以它归 `release` 组，不能放进 `contract`；反过来，任何"只跑一组"的命令都不能被当成完整门禁。
|
||||
- **处理**：分组与 job 的对应关系固定为 `contract`+`shells`+`release` → `Native shell tests`，`agc-web` → `AI game creator shell web tests`，`agc-rust-shard-1..4` → `AI game creator shell Rust shard 1/4 .. 4/4`，`agc-rust-smoke` → `AI game creator shell Rust smoke`，`agc-rust-crates` → `AI game creator shell Rust crates`；`scripts/project-ci-workflow.test.ts` 校验"每个分组恰好被一个 job 调用一次"和"CI 不再调用全量 `npm run check:native-shells`"，新增分组必须同步门禁脚本、根脚本与 workflow 三处。
|
||||
- **处理**：分组与 job 的对应关系固定为 `contract`+`shells`+`release` → `Native shell tests`，`agc-web` → `AI game creator shell web tests`，`agc-rust-shard-1..2` → `AI game creator shell Rust lane 1/2`，`agc-rust-shard-3..4` → `AI game creator shell Rust lane 2/2`，`agc-rust-smoke` → `AI game creator shell Rust smoke`，`agc-rust-crates` → `AI game creator shell Rust crates`；`scripts/project-ci-workflow.test.ts` 校验"每个分组恰好被一个 lane/job 调用一次"和"CI 不再调用全量 `npm run check:native-shells`"，新增分组必须同步门禁脚本、根脚本与 workflow 三处。
|
||||
- **易错点**：① 拆 job / 改 job 名后要确认分支保护里没有残留已不再上报的旧 job 名（本仓库现在不配 required context，只需人工确认 CI 结果，见置顶条目的「分支保护口径」）；② 每个 job 只预热自己会构建的 Cargo 依赖，`agent-run:smoke` 因为会 spawn `cargo` 必须与 AGC 壳的依赖预热同 job；③ 本地全量 `npm run check:native-shells` 仍会串行跑完所有分组，用它作为本地完整门禁，不要用单组脚本冒充。
|
||||
- **关联**：`.gitea/workflows/project-ci.yml`、`scripts/check-native-shells.mjs`、`scripts/project-ci-workflow.test.ts`、`.gitea` 分支保护设置。
|
||||
|
||||
@@ -349,7 +397,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 原样，问题不在合并。
|
||||
@@ -4619,7 +4667,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,25 +16,42 @@
|
||||
|
||||
## 开发中
|
||||
|
||||
- AGC 思考与执行入口共用共享单行摘要骨架；Markdown 只在展开正文走既有安全渲染，折叠预览只取纯文本，不在 summary 嵌套链接或按钮。耗时统一复用中文时分秒格式（不足一分钟一位小数，达到分钟后整数秒），格式化与各层计时边界分离。过程行在运行中和完成后的折叠层内保持同一紧凑间距；失败状态按明确终态与非零退出码呈现红色，不由自然语言输出猜测。
|
||||
- DirectProject 工具可并行调度，依赖由调用方等待，同资源事务与付费动作幂等不能放松。Web 创作先用客户端环境预检，分层验证共用持久的 `validation.maxRuns`，不改写 Provider 的 `llm.maxRetries`；成功证据按输入指纹复用，达标后交付。模型请求计时只保存安全元数据与可观测边界，未知不补零，写盘不能阻塞响应流。详见 AGC 主专题的“DirectProject 交付效率与可观测性”。
|
||||
|
||||
- DirectProject 源码修改走 `agc_apply_patch`、进度走 `agc_update_plan`：SDK 原生的 `apply_patch` / `update_plan` 注册会被按回合移除（全局串行单例），不要恢复它们或用伪造工具注解换取并发。补丁只在当前项目内、受当前回合 Write 许可和受控进程约束，失败可能已部分写入，未知结果不自动重放；计划完成不构成验收证据。
|
||||
|
||||
- 捆绑 Codex 版本只在 `build_support/codex_bundle.rs` 固定一次，不要在测试或脚本里另写字面量；升级 SDK 后必须重跑模型目录真实用例、宿主补丁往返、并发夹具与发行载荷 smoke。原生命令工具名随 SDK 版本变化（0.155 起为 `exec_command` / `write_stdin`），脚本与夹具应按真实目录取用，不要按旧名字硬编码。
|
||||
- AGC 主模型追溯保存在项目 `.agent/model-usage.jsonl`，请求目录标识与响应确认的型号分别记录；旧项目当前配置补录必须标注来源，不冒充历史事实。仅保存有界模型与回合身份字段，不保存配置、凭据或对话正文，不增加 UI 展示。详见 AGC 实施计划“项目主模型使用记录”。
|
||||
|
||||
- Agent 提示词正文与工具说明放在所属组件的 `prompts/`；AGC 通过现有 Prompt Bundle 编译加载，服务端独立 crate 编译包含自己的提示词文件。代码负责变量填充、结构化 schema 与执行校验。
|
||||
|
||||
- 策划 Agent 的顾问态由用户指示驱动，不自主推进项目、主动安排下一步或提交阶段审批；完成单次请求不结束顾问态。五个策划阶段的审批用于检阅已完成产物，关键选择先问询；过程文档按需记录且不重复正式正文。顶层设计按需保留易混淆方向及排除理由，提示词精简应保留这些行为与设计边界。详见策划 Agent 生产迁移与工作区浏览方案。
|
||||
|
||||
- 策划 Agent 复用现有模型/推理档控件，宿主不另加模型检查或自动换模型。用户发起执行时采样全局选择，同轮工具循环和自动重试固定使用回合快照；自动恢复复用该快照，旧记录保留已知模型并补齐一次推理档。只持久化模型和档位，不保存连接凭据；GameAgent 保持原逻辑。详见策划 Agent 生产迁移与工作区浏览方案 §4.1。
|
||||
|
||||
- AGC 思考与执行入口共用共享单行摘要骨架；Markdown 在展开正文走既有安全渲染，折叠预览使用纯文本。耗时统一复用中文时分秒格式（不足一分钟一位小数，达到分钟后整数秒），格式化与各层计时边界分离。过程行在运行中和完成后的折叠层内保持同一紧凑间距；失败状态按明确终态与非零退出码呈现红色。
|
||||
|
||||
- Direct 对话计时区分条目展示时间与生命周期事件时间：整轮用用户发送到明确终态的跨度，工具用各自开始/完成边界；运行时用 100ms 叶子时钟刷新一位小数，终态冻结，旧历史缺边界不推测。不得用整秒时间的大小比较取代 Thread Manager 的事件顺序判定新回合。
|
||||
|
||||
- AGC 批量追加素材标签由原生在一次项目写锁与 revision CAS 下合并各项原标签，先校验全批再写 manifest；前端不能循环单素材分类命令，不回传展示层推导的分类或旧标签全集，以免部分写入或覆盖未编辑字段。
|
||||
|
||||
- AGC 正式包的平台服务跟随构建渠道：`release` 连接 `https://www.genarrative.world`，`dev` 连接 `https://dev.genarrative.world`；本地 debug 态保留 release/dev/custom 服务器选择，会话凭据始终按 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，优先局部补丁。
|
||||
|
||||
## 文档生命周期
|
||||
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
# 画布验收后续修复
|
||||
|
||||
状态：待排查与方案确认。承接 Issue #411；首批修复已由 PR #412 合入，基准为 master `9a21690fe`。本提交仅登记后续范围，不代表以下问题已经修复。
|
||||
|
||||
## 优先排查
|
||||
|
||||
- 动画生成持续失败：读取具体操作错误及原请求状态后再定位，不盲目重复付费生成。
|
||||
- AI 润色无变化；恢复原文退出编辑面板、再次打开丢稿。
|
||||
- 文档全文预览入口不可用或不可发现，需在当前版本复验。
|
||||
- 标签面板无法查看更多标签；资源面板多选后卡死。
|
||||
- 未完成编辑缺少继续入口；快速编辑的素材名称校验报错。
|
||||
|
||||
## 进展
|
||||
|
||||
### 2026-09-20 第一批（已提交到本分支，待客户端验收）
|
||||
|
||||
已完成并在本机跑通：AI 润色原样回包提示与「恢复原文」不再丢稿（AGC-004/005）、快速编辑未提交草稿的保留与继续入口（AGC-006/023）、派生资源名称的前端镜像校验与提交前拦截（AGC-025）。
|
||||
|
||||
- 本机执行过：`npx vitest run` 定向 9 个文件（138 用例全绿）、`npm --prefix apps/ai-game-creator-shell run typecheck`、`npm run check:encoding`、`git diff --check`、改动文件的 prettier / eslint，以及 `appSurface` 等 20 个渲染工作台的用例文件。仅本地；远程 CI 与真实客户端验收都还没跑。
|
||||
- 本轮独立 review 的 4 条 P2 已处理：草稿身份改为资源路径（原先按投影 id，旁路重投影后草稿会静默消失）、润色判据改为「规范化后要写回的文本」、共享聊天输入区显示润色提示、本会话草稿与账本条目在入口上区分来源；P3 处理了名称预检的抛错兜底、恢复入口按钮对齐、提示随编辑失效、空表改工厂、跨语言用例按 `import.meta.url` 解析路径。
|
||||
- 明确保留未改：发送前提醒面板里「AI 润色并发送」遇到原样回包仍直接提交（按用户意图发出去，不做二次拦截）。
|
||||
- 仍未做：动画生成失败的真实复现与定位、文档全文入口、标签面板查看更多标签、多选卡死，以及卡片全类型重设计、画布内任务浮层、替换交互与聊天引用这批后续需求。
|
||||
|
||||
### 2026-09-20 第二批（AGC-039 / AGC-040，待客户端验收）
|
||||
|
||||
现场（项目 `gameagent-6e53c9e8`）：快速编辑提交后画布右上角「生成任务」全程是「还没有生成任务」，而「管理未完成编辑」里仍挂着同一条草稿——用户据此判断"点了没生成"；同一次修改在 22:05:16 与 22:05:34 各派生一次，manifest 多出两份重复的「-编辑版」。
|
||||
|
||||
- 交付三条口径（本批一起改）：① 派生/修改类任务进「生成任务」侧栏——本地提交记录负责"按下按钮当帧可见"，原生 `list_pending_local_project_resource_edits` 负责"重开项目 / 别处提交也看得见、阶段以后端为准"，两边按 `operationId` 合并去重；② 提交期间那一笔不再算「未完成编辑」（失败后自动回落，草稿不丢）；③ 同一张素材还有在途提交时，重开面板再提交会被拦下并给出原因，避免重复派生。
|
||||
- 已知未做：成功之后**再次提交**仍会再派生一次（按用户显式重复计费），前端没有做"同提示词去重"；原生账本 schema、Rust 门禁与请求载荷都没有改动。
|
||||
- 本机执行过：新增模型用例 9 条与快速编辑两套新用例（提交当帧进侧栏 / 收口为已完成、在途重复提交被拦），两处新判据都做过变异验证（改回旧实现即红灯）；定向 7 个文件 97 条全绿；`tests/appSurface.test.ts` 与本批基线逐条一致（16 失败均为本分支既有，未新增）；`npm --prefix apps/ai-game-creator-shell run typecheck` 通过。远程 CI 与真实客户端验收仍未跑。
|
||||
|
||||
### 2026-09-21 第三批（卡片浮层生命周期与画布样式，待客户端验收）
|
||||
|
||||
验收现场又报三条：①「生成动画」面板样式与美术画布不一致（缩略图、预设、提交按钮落回默认流）；② 该浮层失焦不收起；③ 生图弹窗里**点提示词输入框任意位置**都会弹出「选择素材」。
|
||||
|
||||
- 产品口径澄清后按「**卡片浮层只用于提交任务，提交完生命周期就结束**」改：快速编辑 / 生成动画点提交当帧即关面板（不等 IPC、不留等待态），进度与结果全在「生成任务」侧栏；受理后的失败不再重开面板（侧栏收口为失败 + 提示条、草稿回落到「未完成编辑」），只有点击瞬间就失败留在面板里。原「生成中不关」判据与此一并退役。
|
||||
- 派生请求身份改为按「入口 + 资源路径」记忆：重开面板再提交、提示词没变就沿用同一 `operationId` / 幂等键，重试仍命中同一 operation 账本。
|
||||
- 动画面板样式改为**按网页端整档照抄**：补上第二条同名规则（`.image-canvas-editor__generation-close` 的浮层内绝对定位——只搬第一条时关闭键会掉进网格流、跑到面板正中）、提示词聚焦 / `aria-invalid` 两档、composer 内参数簇底色，以及 `@media (max-width: 760px)` 整档；同时删掉面板里重复回显提示词的「动画描述」行。
|
||||
- 新增样式缺口守卫 `tests/resourceCanvasCharacterAnimationPanelStyle.test.tsx`：按 `src/main.tsx` 的真实 import 关系解析 AGC 加载的样式表，逐条比对「网页端命中该面板的规则（选择器 + 声明）AGC 是否都有一条」。第一版守卫只比选择器，漏掉了同名覆盖，已按现口径收紧。
|
||||
- 生图弹窗那个是 `<label>` 转发点击：`<label>` 会把点击交给内部第一个可标注控件，而这一格里第一个正是引用输入区的「插入素材引用」按钮。输入区改为 `<div>` 包裹（可访问名仍由控件自身 `aria-label` 提供），并补一条「点输入区不该自己弹出选择框、只有 @ 按钮才开」的用例——先用旧代码复现出红灯再修。
|
||||
- 本机执行过：定向 `projectResourceLiveIntegration` 32 条、`resourceCanvasQuickEditDraft` 10 条、`resourceCanvasFloatingDismiss` 18 条、样式守卫 3 条、`resourceCanvasAssetGenerationReferences` 10 条（含新增复现用例）等全绿；网页端 `ImageCanvasEditorGenerationIntegration` 44 条 + 面板 6 条全绿；`typecheck`、`check:encoding`、`git diff --check`、prettier、eslint 通过；`tests/appSurface.test.ts` 与基线逐条一致（16 失败均为本分支既有）。远程 CI 与真实客户端观感仍需复看。
|
||||
|
||||
### 2026-09-21 复核收口（review 修复 + 生图浮层美化）
|
||||
|
||||
- 在途拦截补齐**生成动画**：提交记录里「这笔属于哪张资源」从 `draftKey` 拆成 `resourcePath`，快速编辑与生成动画共用同一条 `…BlocksResource` 判据。此前动画这条键对不上拦不住——重开面板再提交会复用同一 `operationId` 卡在原生 per-operation 锁上，或（改了提示词）直接多出一笔付费生成。
|
||||
- 样式缺口守卫**扩到三块面板**（动画面板 / 快速编辑面板 / 生图面板），判据改为按「选择器分支 + 声明」逐条比对：只比类名会漏同名覆盖，只比整串选择器会逼宿主连不相干的兄弟支一起搬。实测把快速编辑面板的两条缺口一并照抄补上（其中两条按宿主差异显式登记：窄屏底栏与 `overflow: auto`）。
|
||||
- 网页端 `@media (max-width: 760px)` 只搬**动画面板**那一支：AGC 的快速编辑浮层是「居中贴资源卡」的绝对定位，跟随网页端改成整宽底栏会压住栏目工具栏与左侧「生成任务」侧栏。
|
||||
- **生图浮层紧凑化**（验收现场那条滚动条）：字段行改两列、比例与尺寸并排、提示词 6 行降到 3 行、润色 / 参考计数 / 两个动作收进同一行——面板高度回落到几何上界以内，滚动条物理上不再出现（`overflow` 只作极端窗口兜底）。相关卡片外形收敛到 `.game-project-workbench` 上的 `--game-canvas-card-*` 基类 token（取值照抄网页端画布面板），占位卡与生成浮层/弹窗共用一套圆角 / 描边 / 底色 / 投影。
|
||||
- **口径更正**：此前记的「`appSurface` 16 条既有失败」是**从 `apps/ai-game-creator-shell` 目录跑**造成的 cwd 假红（`resolve(process.cwd(), 'apps/…')` 路径翻倍 → ENOENT），不是用例本身红。规范跑法是仓库根 `npm test`；本次新增 `apps/ai-game-creator-shell/tests/repoPath.ts`（按 `import.meta.url` 反推仓库根）并把 19 个用例文件改成用它，另修掉 `HOST_STYLE_SHEETS.filter(existsSync)` 把仓库相对路径交给 cwd 解析的同类假红。改完从仓库根跑 `appSurface`：**538 通过 / 17 跳过 / 0 失败**。
|
||||
- 本机执行过（均在合并 master 之后）：`typecheck`、`check:encoding`、`git diff --check`、prettier、eslint 通过；AGC 定向 `projectResourceLiveIntegration` 32 + `resourceCanvasQuickEditDraft` 10 + `resourceCanvasFloatingDismiss` 18 + 样式守卫 5 + `resourceCanvasAssetGenerationReferences` 11 + 派生任务模型 9 等全绿；网页端 50 条全绿；`appSurface` 从仓库根 0 失败。真实客户端观感与远程 CI 仍需复看（CI 目前按用户要求不追）。
|
||||
|
||||
### 合并前复核（2026-09-21，PR #419）
|
||||
|
||||
- 合并 master（`cd98e0603`）后按**仓库根**跑全量 `npx vitest run`：**373 个测试文件全过，4512 通过 / 34 跳过 / 0 失败**；PR 显示 `No Conflicts`，分支与远端一致、工作区干净。
|
||||
- 范围核对：48 个改动文件全部落在 AGC 前端、3 个共享画布组件与 3 份文档；`server-rs` / `spacetime` / `docs/openapi` / `src-tauri` **零改动**（后端与契约无红线涉及），无 `.env`、密钥、构建产物或日志进入改动。
|
||||
- 合并后仍**未复验**的只有两类，且都不阻塞合并：① 真实客户端观感（本批动了动画面板样式、生图浮层紧凑排布与卡片基类 token——声明级与结构级都有守卫，真机要客户端验收确认）；② 远程 CI（runner/镜像问题仍在处理，见 Issue #431；按用户要求本批不追）。
|
||||
|
||||
### 2026-09-21 第四批（画布三项：生成任务侧栏右上角 / 拖到对话批量引用 / 替换面板画布点选，待客户端验收）
|
||||
|
||||
需求原文（本文件「后续需求」里那两条，三项一起做）：
|
||||
|
||||
- 「生成任务列表移到画布右上角（照抄美术画布，但是保留当前的样式）」。
|
||||
- 「聊天拖拽批量引用」→ 拖动素材到对话实现批量 @ 引用。
|
||||
- 「画布点选替换」→ 在替换面板中支持画布点选目标。
|
||||
|
||||
- 改前：侧栏本体是 `position: fixed; top: 4rem; bottom: 6rem; left: 0.75rem` 的左侧贴边面板，开合口只有工具条上那一枚「生成任务 · N」按钮（资源 / 运行两个页签各渲染一次）；分组、失败可见、限高滚动、提交受理后自动展开这四条本批之前已经具备，本轮只动**位置与开合形态**。
|
||||
- 改后：新增右上角锚点 `.game-resource-generation-tasks-anchor`（`position: absolute; top: 3.5rem; right: 0.85rem; z-index: 40`，挂在 `.game-workbench-stage` 里），**开关常驻右上角、面板在开关左侧展开、收起只剩那一枚开关**（与美术画布同一形态）；工具条上那两处重复入口删除；面板改由 `max-height: min(30rem, calc(100vh - 12rem))` 封顶 + 内部滚动，自己不再定位。
|
||||
- 颜色 / 圆角 / 字重 / 阴影仍全部走 `--platform-*` token（开关沿用原工具条那枚次级胶囊的外观，只多一档面板投影），没有照搬网页端的固定色值。
|
||||
- 分档坐标：view 的 `placement`（`canvas | run | editor`）落成 `data-generation-tasks-placement`；运行表现层下移到 `top: 7rem`，避开它右上角 `game-run-version-picker`（`top: 20px; right: 20px`）。
|
||||
- 本机执行过：`resourceCanvasAssetGenerationTasksPanel.test.tsx` 12 passed（含验收修正后的「展开时开关让位」）、`resourceCanvasAssetGenerationTasksSidebarStyle.test.ts` 11 passed、`resourceCanvasGenerationTasksSidebarDismiss.test.tsx` 5 passed、`resourceCanvasAssetGenerationBackgroundClose.test.tsx` 5 passed；仓库根 `tests/appSurface.test.ts` **538 passed / 17 skipped / 0 failed**（与既有基线逐条一致）；`tsc -p apps/ai-game-creator-shell/tsconfig.json --noEmit` 通过。
|
||||
- **本批第二项（拖到对话批量引用）**：资源卡按住拖到右侧 Agent 对话栏、松手即按这次拖动真正参与位移的那批（多选整批、单选只引用按住的那张）插入 `@` 引用；落点铺虚线框 + 「松手即可 @ 引用 N 项素材」，拖回画布内松手仍是排版语义；引用口径与工具条「引用」按钮逐字一致（只认已登记素材、`source: resource-card`），派发走新增的批量事件一次事务插入。
|
||||
- **本批第三项（替换面板画布点选）**：替换候选面板从全屏弹窗改为**画布右上角的非模态浮层**（共享组件新增 opt-in `nonModal`，网页端弹窗行为不变），面板开着时画布照常可点——点中合法候选即落成面板里的当前选择，写入仍只由「确认」发起；非法目标在面板里报因、零写入。旧的「点选替换」按钮、画布提示条与点选态随之退役（同一个功能不留两条 UI 路径）。
|
||||
- **验收现场修正（第四批内）**：截图两条——右上角「生成任务」开关与工具条**重叠**、展开时开关与面板**并排**。锚点改挂**画布那一格网格**（不再用写死 `top` 的绝对定位，工具条换行也不会压上去），开关只在完全收起时渲染（展开后由面板头部 × 或点外部收起）。
|
||||
- **PR #441 自查修正**：拖动落点改逐值比较（不再每帧重渲染工作台）；替换面板从 stage 顶层移进画布容器并排在任务开关下方，打开替换会话时收起任务面板（同一个角只留一块浮层）；面板上方补「替换源素材：<显示名>」一行（非模态之后源身份不再只靠画布光环）。
|
||||
|
||||
- 本机执行过（三项合计）：`resourceCanvasAssetGenerationTasksPanel` / `…SidebarStyle` / `…SidebarDismiss` / `…BackgroundClose`、`resourceCardReferenceDropModel`、`resourceCanvasChatReferenceDrop`、`resourceReferenceInput`、`resourceVersionReplacement`、`projectAssetPickerDialogShellStyle`、`ImageCanvasEditorView`、`ImageCanvasEditorGenerationIntegration`、`projectResourceLiveIntegration`、`appSurface` 全绿（定向批次多项合计 694 passed / 17 skipped）；`typecheck`、`check:encoding`、`git diff --check`、prettier / eslint 通过。
|
||||
- 仍未做：真实客户端目视（三项的真机手感与落点）与远程 CI 都没跑；窄屏（≤480px）只有声明级断言；「复制对话保留有效引用」未做。
|
||||
|
||||
## 后续需求
|
||||
|
||||
- 资源卡顶部独立名称区与全类型统一样式，确认 assetName/用户素材名的正式来源。
|
||||
- ~~生成任务列表移到画布右上角，进行中/已完成分组、失败可见、限高滚动及自动开合。~~ **2026-09-21 已处理**：侧栏改挂画布右上角锚点（开关常驻、面板在开关左侧展开，形态照抄美术画布，样式仍走 AGC 平台 token），工具条上的重复入口删除；`placement` 分档让运行表现层让开右上角版本入口。见下「2026-09-21 第四批」。
|
||||
- ~~素材替换关系与画布点选替换；聊天拖拽批量引用~~ **2026-09-21 已处理**：替换面板改为画布右上角的非模态浮层、可直接在画布上点选目标素材；资源卡可拖到对话栏批量 @ 引用。见下「2026-09-21 第四批」。「复制对话保留有效引用」仍未做（同一条需求里的另一半）。
|
||||
|
||||
## 边界与验收
|
||||
|
||||
先核对测试包/提交，避免旧包反馈与已合入修复混淆。每个问题先复现、明确原因与最小修复，再补回归和独立 review；复杂需求按现有规范驱动流程推进。首批本地通过不等于远程 CI 或真实 Provider 验收通过，遗留 Rust shard 2 失败仍需跟踪实际 SHA。不得为验证擅自提交付费生成、部署或修改他人项目。
|
||||
|
||||
完成条件：逐项记录修复提交、实际执行的检查和客户端验收；长期规则回归主规范，全部关闭后删除本待办。
|
||||
Reference in New Issue
Block a user