From f9bd0adae18d66f19166b3ba980eb6c2d5304d08 Mon Sep 17 00:00:00 2001
From: kdletters <kdletters@qq.com>
Date: Mon, 14 Sep 2026 16:47:35 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E9=BD=90=E5=AE=A2=E6=88=B7=E7=AB=AF?=
 =?UTF-8?q?=20CI=20=E6=8B=86=E5=88=86=E7=9A=84=E5=85=B1=E4=BA=AB=E8=AE=B0?=
 =?UTF-8?q?=E5=BF=86=EF=BC=9Alabel=20=E5=AD=97=E9=9D=A2=E9=87=8F=E5=A5=91?=
 =?UTF-8?q?=E7=BA=A6=E4=B8=8E=E5=AE=9E=E6=B5=8B=E8=80=97=E6=97=B6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- pitfalls：新增「根门禁的 [check:native-shells] <label> 是别处按字面量校验的契约」，
  记录 run 2095 里 desktop-shell typecheck 的失败根因（label 被抽进公共打印函数后，
  check-config 的字面量断言落空）、处置与本地验证方式。
- decision-log：把「预计收敛到约 13 分钟量级」换成 run 2097 实测——六个 job 全绿、
  wall-clock 15 分 27 秒（拆分前 run 2094 为 22 分 15 秒），关键路径转移到
  AI game creator shell Rust tests，壳体串行套件 507 秒是硬底。

Co-authored-by: DotCraft <273930855+dotcraft-ai@users.noreply.github.com>
---
 docs/project-memory/shared-memory/decision-log.md | 2 +-
 docs/project-memory/shared-memory/pitfalls.md     | 8 ++++++++
 2 files changed, 9 insertions(+), 1 deletion(-)

diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md
index 7ed8870b7..bbe0db8c0 100644
--- a/docs/project-memory/shared-memory/decision-log.md
+++ b/docs/project-memory/shared-memory/decision-log.md
@@ -9,7 +9,7 @@
 - 决策：`scripts/check-native-shells.mjs` 引入 `--groups=`，把门禁分成 `contract`（静态契约断言）、`shells`（H5 / 微信 / Expo / 桌面壳运行时门禁）、`agc-web`（AGC typecheck 与壳内测试）、`agc-rust`（共享 / 平台 crate 测试、AGC 串行壳测试、agent-run smoke）、`release`（AGC 与桌面壳发布构建 smoke、落盘产物断言）五组，每组暴露一个 `check:native-shells:<group>` 根脚本；不带 `--groups=` 时仍然串行跑全部分组，本地 `npm run check:native-shells` 语义不变。CI 据此把原客户端 job 拆成 `Native shell tests`（contract + shells + release）、`AI game creator shell web tests`（agc-web）、`AI game creator shell Rust tests`（agc-rust）三个 job，并把最长的 AGC Rust job 声明在最前，使 runner 领取顺序与关键路径一致。
 - 命令等价：`npm run ai-game-creator-shell:check` 拆成 `:check:web`（typecheck + 壳内测试）与 `:check:rust`（agent-runtime 两个独立 crate + `platform-llm` + `shared-contracts` + AGC 壳串行测试），聚合脚本仍是 `web && rust && agent-run:smoke` 同序同命令，本地与文档入口不变。`agent-run:smoke` 会用 `src-tauri/Cargo.toml` spawn `cargo`，因此归入 `agc-rust` 分组，与 AGC 依赖预热同 job。
 - 影响范围：`.gitea/workflows/project-ci.yml`（六个 job）、`scripts/check-native-shells.mjs`、根 `package.json` 门禁脚本、`scripts/project-ci-workflow.test.ts`（校验分组清单、根脚本内容与 job 覆盖，防止新增分组时静默漏跑）、开发运维文档与开发流程记忆。门禁覆盖不变，只有执行位置改变；Gitea `master` 分支保护的 required context 是追加式的（旧四个继续上报，需补上两个新 AGC context）。
-- 验证方式：`npx vitest run scripts/project-ci-workflow.test.ts`（11 条）；`node scripts/check-native-shells.mjs --groups=contract` 本地 0.6 秒通过；`--groups=` 未知组与空组都要报错关闭。实测耗时按拆分前同一 run 的日志时间戳折算：关键路径从 18 分 37 秒收敛到 AGC Rust job 的约 13 分钟量级（若 runner 并发槽位 ≥ 6，可压缩到约 10.5 分钟）。
+- 验证方式：`npx vitest run scripts/project-ci-workflow.test.ts`（11 条）；`node scripts/check-native-shells.mjs --groups=contract` 本地 0.6 秒通过；`--groups=` 未知组与空组都要报错关闭。拆分前同一类运行的 wall-clock 是 22 分 15 秒（run 2094，`Native shell tests` 单 job 19 分 50 秒）；拆分后 run 2097 六 job 全绿、wall-clock 15 分 27 秒，关键路径转移到 `AI game creator shell Rust tests`（15 分 27 秒 = 前置 5 分 30 秒 + 门禁 11 分 43 秒），其余五个 job 3 分 45 秒 ~ 8 分 36 秒。AGC 壳内串行套件（2451 用例）实测 507 秒，是这条关键路径的硬底，再切 job 只会重复 `npm ci` 与 Cargo 预热。
 - 关联文档：[开发运维](../../【开发运维】本地开发验证与生产运维-2026-05-15.md)、[踩坑记录](pitfalls.md)。
 
 ## 2026-09-10 策划 Agent 迁移只复用生产基建
diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md
index 24af67d1b..3cdcc4871 100644
--- a/docs/project-memory/shared-memory/pitfalls.md
+++ b/docs/project-memory/shared-memory/pitfalls.md
@@ -1,5 +1,13 @@
 # 踩坑与排障记录
 
+## 2026-09-14 根门禁的 `[check:native-shells] <label>` 是别处按字面量校验的契约
+
+- **现象**：客户端 CI 拆成六个 job 后，`Native shell tests` 在 `desktop-shell:typecheck` 步骤红了：`Error: root native shell gate must keep desktop release artifact check console.log('[check:native-shells] desktop-release-binary-artifact')`。
+- **原因**：拆分时给 `scripts/check-native-shells.mjs` 加了公共打印函数 `runNativeShellGate(group, label, gate)`，把各门禁的 `console.log('[check:native-shells] <label>')` 换成了模板字符串。而 `apps/desktop-shell/scripts/check-config.mjs` 与 `apps/mobile-shell/scripts/check-config.mjs` 会读取根门禁脚本源码，对这类 label 做**字面量**断言（含 `assertDesktopReleaseBinaryArtifact();` 调用本身），label 一变形断言就失败。
+- **处理**：`runNativeShellGate` 收窄为 `(group, gate)`，label 回到各门禁执行体里以字面量打印；分组能力与 `--groups=` 语义不变。脚本内已注明"不要把 label 抽成变量"，外部壳的 `check-config` 是它的消费者。
+- **验证**：`node apps/mobile-shell/scripts/check-config.mjs` exit 0；`node apps/desktop-shell/scripts/check-config.mjs` 已越过第 740–777 行的根脚本断言段（本机随后卡在本机不存在的 Tauri 生成产物目录，与本次改动无关）；`--groups=contract`、vitest `scripts/project-ci-workflow.test.ts`、eslint 均通过。修复后 run 2097 六个 job 全绿。
+- **关联**：`scripts/check-native-shells.mjs`（`runNativeShellGate`）、`apps/desktop-shell/scripts/check-config.mjs`、`apps/mobile-shell/scripts/check-config.mjs`。
+
 ## 2026-09-14 客户端 CI 拆分后，选组运行会跳过未选分组，且必须同步分支保护
 
 - **现象**：把 `Native shell tests` 拆成客户端三个 job 后，如果只跑 `npm run check:native-shells:release`，静态契约和壳运行时门禁都不会执行；如果只跑 `--groups=contract`，`desktop-release-binary-artifact` 又会因为缺少 `build/native/desktop/` 产物而失败。