建立 AGC 稳定版生命周期基础合同

新增 ClientOperation 状态、身份和 stale-result 规则让认证 refresh 与首页创建记录统一 operation phase 和 scope 为 dev-stack 与 AGC Vite marker 增加工作树和实例身份门禁补充稳定版切换主规范、里程碑计划和开发运维踩坑文档
2026-09-14 12:50:51 +08:00
parent 86c1187ddc
commit 3d5349057a
17 changed files with 460 additions and 14 deletions
@@ -0,0 +1,33 @@
+# 【实施计划】AGC 客户端稳定版生命周期基础切换
+
+| 字段 | 值 |
+| --- | --- |
+| Milestone | `docs/project-memory/plans/【里程碑】AGC客户端稳定版生命周期基础切换-2026-09-14.md` |
+| Status | ready |
+| Owner | Codex |
+
+## 修改边界
+
+- 允许修改：AGC client operation/auth/home、dev-stack snapshot/Vite marker、对应测试和稳定版主规范。
+- 明确不修改：公开 API/schema、项目 manifest/runtime durable schema、旧项目文件和真实 Provider 服务。
+
+## 实现顺序
+
+1. 补 ClientOperation 类型、转移函数和 stale/cancel 测试。
+2. 让 auth refresh 保留 operation 投影，首页自动创建记录 draft、phase 和项目 scope。
+3. 在 dev-stack snapshot 与 Vite marker 记录 instanceId、repoRoot、processId、port、dataDir，并补复用门禁。
+4. 运行 typecheck、定向测试、dev-stack 测试、编码、文档索引和 diff 检查。
+
+## 验证命令
+
+1. `npm --prefix apps/ai-game-creator-shell exec -- vitest run tests/clientOperation.test.ts tests/clientApi.test.ts tests/clientHttp.test.ts tests/recentProjectsModel.test.ts --reporter=dot`
+2. `npm --prefix apps/ai-game-creator-shell run typecheck`
+3. `npm --prefix apps/ai-game-creator-shell exec -- vitest run tests/start-dev-stack.test.ts tests/dev-port.test.ts --reporter=dot`
+4. `npm --prefix . exec -- vitest run scripts/dev.test.ts --reporter=dot`
+5. `npm run check:doc-index`
+6. `npm run check:encoding`
+7. `git diff --check`
+
+## 风险与回滚点
+
+旧 dev-stack 文件缺少 instanceId 时必须拒绝 AGC 后端复用而不是猜测；若 marker 字段导致既有 Vite 启动链不兼容，回滚只撤销 identity 投影，不回退已完成的 body timeout/home/recent 修复。
@@ -0,0 +1,33 @@
+# 【里程碑】AGC 客户端稳定版生命周期基础切换
+
+| 字段 | 值 |
+| --- | --- |
+| Version | 1.0 |
+| Status | ready |
+| Date | 2026-09-14 |
+| Parent Spec | `docs/【技术方案】AGC客户端稳定版生命周期大切换-2026-09-14.md` |
+
+## 目标
+
+落地 ClientOperation 基础合同，接入认证 refresh 与首页自动创建，并把 dev-stack snapshot/marker 的身份字段补齐。
+
+## 范围
+
+客户端 operation 类型与 stale 判定、认证 refresh 投影、首页创建 phase 投影、dev-stack instanceId/repoRoot/processId/port/dataDir 记录与验证测试。
+
+## 不在范围内
+
+本轮不删除持久化迁移、Runtime/资源账本或公开后端接口；不重写 Planning V2、DirectProject 和资源生成的 durable executor。
+
+## 验收标准
+
+- [ ] ClientOperation identity、phase、deadline、scope 和取消状态有定向测试。
+- [ ] 认证 refresh 和首页创建暴露 operation 投影，切页不会丢失 operation。
+- [ ] dev-stack snapshot 与 Vite marker 带工作树/进程身份字段。
+- [ ] 类型、定向测试、dev-stack 测试、编码和 diff 检查通过。
+
+## 证据要求
+
+- 自动化：clientOperation、clientAuth/clientApi、home、dev-stack 定向测试。
+- 运行时：只读端口归属探测；必要时 AGC Vite marker smoke。
+- 边界：旧状态缺字段拒绝复用，迟到 operation 不能写回，取消不自动重放。
@@ -5495,3 +5495,10 @@ Cocos Creator 根目录由 `package.json.creator.version` 与普通 `assets/`
 - **真机判据**：点进任一栏目（或展开「所有资源」）时，**每一张**卡片都从它那一摞的位置/尺寸位移并缩放到自己的位置，而不只是总览里那 3 张；同一栏目里不同类型的两摞各自飞各自的卡。`prefers-reduced-motion: reduce` 下仍不播放动画（口径未改）。
 - **已知未覆盖**：① 子画布内直接切到另一个栏目（分页画布换栏目）时目标栏目的卡片在该次 `begin` 时未渲染、拿不到任何 First，整段转场仍按旧口径跳过（`play` 的 `!captured.entries.size` 早退），本次未改；② 真机动画观感由浏览器渲染，jsdom 只覆盖几何与调用契约，需要按上面那条判据人工确认一次。
 - **关联**：`apps/ai-game-creator-shell/src/view/project-development/resourceBookController.ts`（`begin` 的堆锚点 / `syncNodes` 的合成 First）、`resourceBookLayout.ts`（`allOpen` 列号）、`index.tsx`（宿主 `data-resource-book-stack-*`）、`apps/ai-game-creator-shell/tests/{resourceBookController,resourceBookLayout}.test.ts`、`tests/appSurface/project-development.suite.ts`、`docs/technical/【技术方案】GameAgent资源自由画板与快速编辑-2026-08-20.md`。
+
+## 稳定版 AGC 复用开发栈必须核对 instance identity
+
+- 现象：端口和 `/healthz` 都正常，但 AGC 连接了另一个 worktree 的 API、SpacetimeDB 或旧 Vite，表现为登录、项目列表、Runner 状态与当前代码不一致。
+- 原因：健康检查只能证明“有服务响应”，不能证明服务属于当前工作树；旧 `.app/dev-stack.json` 可能没有当前 `repoRoot`、`instanceId` 和服务级 dataDir 身份。
+- 处理：先读取 `.app/dev-stack.json`，核对顶层 `repoRoot + instanceId`，再核对服务 `repoRoot + instanceId + dataDir + pid + port`；AGC Vite marker 还必须带 `repoRoot + processId + port`。任何字段缺失或不匹配都拒绝静默复用，改为启动当前工作树自己的服务或明确提示清理。
+- 验证：`scripts/dev.test.ts`、`apps/ai-game-creator-shell/tests/start-dev-stack.test.ts` 覆盖 snapshot identity 和旧状态拒绝复用；运行时记录实际端口、进程命令行和 dataDir，不要只记录 HTTP 200。