新增 AGC 渲染层下沉与最新 master 对齐的里程碑与实施计划

- 新增【里程碑】AGC渲染层下沉与最新master对齐-2026-09-28.md，明确活动回合事实源统一、封面队列回填、维护态出口三项验收 - 新增【实施计划】AGC渲染层下沉与最新master对齐-2026-09-28.md，列出五步任务与证据要求
2026-09-28 14:28:16 +08:00
parent 2b06394bcc
commit 74b83aa1a8
2 changed files with 83 additions and 0 deletions
@@ -0,0 +1,36 @@
+# 【实施计划】AGC 渲染层下沉与最新 master 对齐
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC渲染层下沉与最新master对齐-2026-09-28.md` |
+| Status | ready |
+| Owner | Codex |
+
+## 一句话交付结果
+
+`codex/agc-renderer-io-downshift` 合入 `origin/master` 后，AGC 渲染层仍然是「只做展示与交互」的离线前端，
+网络 IO 与正式数据仍全部在 Rust 侧，且首页「运行中的项目」、封面生成队列与维护态提示三种能力在合并后
+行为正确、有定向测试证明。
+
+## 任务清单
+
+1. 冲突收口：机械冲突按「本分支退役渲染层传输」取舍（nginx SPA 白名单、`.gitignore`、mobile 脚本、
+   capabilities 描述、已退役计划随 master 删除、测试保留双方）。
+2. 活动回合事实源统一：删除 `direct_runtime` 里的重复快照函数；把 `emit_direct_active_turns_changed()`
+   移到 Direct 线程管理器的登记 / 进度 / 收口变更点；迁移对应的 Rust 用例。
+3. 封面生成补 `generationInputs`，并为「队列未完成 → 轮询 → 拿到素材 ID」保留 Rust 侧用例。
+4. 维护态：Rust 给出稳定分类标记，渲染层在统一的 invoke 边界消费该标记并广播 `CLIENT_MAINTENANCE_EVENT`；
+   `MaintenanceNotice.tsx` 与 `tests/maintenanceNotice.test.tsx` 跟着新入口更新。
+5. 文档收口：保留双方条目的冲突文档合并；`decision-log` / `pitfalls` 追加本轮结论；实施计划与里程碑
+   回写取证。
+
+## 证据要求
+
+- 每个任务都要有可复跑的定向用例，并在本计划内写明命令与结果。
+- 涉及行为变化的用例必须做变异验证：拿掉修复后用例变红。
+- 区分「源码级通过」与「需要真实客户端 / 真实 Provider 才能取得的运行时证据」。
+
+## 完成后的临时文档处理
+
+本里程碑验收通过后，把仍然有效的长期边界同步回现行技术方案与项目记忆，再删除本里程碑与实施计划两份
+临时文档。
@@ -0,0 +1,47 @@
+# 【里程碑】AGC 渲染层下沉与最新 master 对齐
+
+Version: `v1`
+Status: `ready`
+Date: `2026-09-28`
+Parent Spec: `docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md`
+
+## 目标
+
+把 `codex/agc-renderer-io-downshift` 上「渲染层只做展示与交互，网络 IO 与正式数据归 Rust」的改造，
+重新落到 `origin/master` 已经演进出的新形状上：同一批能力在 master 侧换了承载方（活动回合注册表改由
+Direct 线程管理器持有、封面生成增加了队列回填契约、新增了维护态统一弹窗）。本里程碑只做对齐，不新增
+产品能力。
+
+## 范围
+
+- 活动回合事实源统一：`list_direct_active_turns` 以 Direct 线程管理器为唯一导出口；渲染层
+  `DIRECT_ACTIVE_TURNS_CHANGED_EVENT` 由新的变更点发出，首页「运行中的项目」仍先订阅再读一次快照。
+- 封面生成队列回填契约：Rust 侧 `/api/editor/images/generations` 请求补 `generationInputs.source`，
+  保证队列完成后能拿到平台素材 ID。
+- 维护态出口：Rust 对平台维护响应给出稳定分类，渲染层由该分类触发唯一的「系统维护中」弹窗。
+- 计划文档、共享记忆与冲突文档的收口。
+
+## 非目标
+
+- 不改公开 HTTP API、SpacetimeDB schema、项目 manifest 或 Agent Runtime 持久化格式。
+- 不恢复任何被本分支退役的渲染层 HTTP 能力（`clientApi.ts`、`fetchClientHttp`、`http:default` 权限）。
+- 不改变发布、钱包、认证的既有业务语义。
+
+## 验收标准
+
+1. `list_game_creator_direct_active_turns` 读且只读 Direct 线程管理器的活动回合快照；`direct_runtime`
+   不再导出第二份同名快照函数。
+2. 活动回合登记、进度更新、终态收口三处变更都会发出 `DIRECT_ACTIVE_TURNS_CHANGED_EVENT`；无内容变化的
+   重复更新不重复发出。
+3. 渲染层进入首页时先订阅事件再读一次快照；事件重复或内容未变时不产生新的数组引用；卸载后迟到事件不写回。
+4. Rust 生成游戏封面的请求体包含 `generationInputs`，且队列未完成时仍能轮询到平台素材 ID。
+5. 平台维护响应在渲染层触发唯一「系统维护中」弹窗；同一批并发失败只弹一次，关闭后业务页仍可重试。
+6. 渲染层不新增任何直接 HTTP 调用与 HTTP 权限；`clientApi.ts` 保持删除。
+7. 定向 Web/Rust 测试、`npm run check:encoding`、`git diff --check`、`npm run check:doc-index` 通过。
+
+## 风险与回滚
+
+- 活动回合事实源切换必须一次到位：事件从旧注册表发、快照从新注册表读会表现为首页「运行中」列表不刷新或
+  长期不消失，因此两类改动必须同一个提交落地。
+- 维护态分类依赖服务端 envelope 的 `code` 与 `message`；分类失败时按普通错误展示，不阻塞业务。
+- 回滚：本里程碑只在本地分支上进行，`git reset --hard 2b06394bc` 可退回对齐前的分支状态，master 不受影响。