From c799d00a9394da38ad6e3454df55b2e10cb093ad Mon Sep 17 00:00:00 2001 From: kdletters Date: Mon, 14 Sep 2026 18:35:00 +0800 Subject: [PATCH] =?UTF-8?q?=E8=AE=B0=E5=BD=95=E5=88=86=E6=94=AF=E4=BF=9D?= =?UTF-8?q?=E6=8A=A4=E7=8E=B0=E7=8A=B6=EF=BC=9A=E4=B8=8D=E6=8A=8A=20Projec?= =?UTF-8?q?t=20CI=20=E9=85=8D=E6=88=90=E5=90=88=E5=B9=B6=E5=BF=85=E9=9C=80?= =?UTF-8?q?=E6=A3=80=E6=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 复核后确认本仓库不把 Project CI 的 context 配成 master 分支保护的合并必需检查，合并前由人工 确认最近一次结果。据此把文档里"必须设为合并必需检查 / 需补 6 个新 context"的强制口径改成 与现状一致，避免下次有人照着一个不执行的待办去逐个勾选 context： - 开发运维文档：说明当前不配 required context（代价是门禁红了不会自动阻止合并），把 11 个 context 清单降级为"将来若要启用时的清单"，并保留"不能残留已不再上报的旧 job 名，否则 PR 会永远停在等待该检查"这一条；master 交付口径里"当前 head 的七个 required context 全绿" 改为"最近一次 Project CI 全绿"。 - shared-memory/decision-log：AGC 壳分片那条的"影响范围"不再把它列为待补 context 的待办。 - shared-memory/pitfalls：置顶条目新增"分支保护口径"，并把旧条目里"要补齐两个新 AGC context"改成"确认没有残留旧 job 名"。 - .craft 的 gitea-ci-triage 技能同步为"改 job 集合或 job 名不需要同步分支保护"。 验证：prettier、check:encoding、check:doc-index 通过。 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 | 3 ++- docs/【开发运维】本地开发验证与生产运维-2026-05-15.md | 4 ++-- 3 files changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index 60d4694c4..91140b7a4 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -12,7 +12,7 @@ - 不变量：片并集必须等于 `--list` 的全集且互斥，数量或成员不符立即失败（`assertShardsCoverEveryTest`）；该校验与「只跑一片」无关，因此在每个分片 job 上都会执行，防止分片规则改动后静默漏跑门禁。 - 配套拆分：`npm run ai-game-creator-shell:check:rust` 拆成 `:rust:crates`（`agent-runtime-core`、`agent-runtime-orchestration`、`platform-llm`、`shared-contracts`）与 `:rust:shell`（分片运行器），聚合脚本保持同序，因而 `ai-game-creator-shell:check` 与本地 `npm run check:native-shells` 语义不变。AGC 相关门禁在 CI 里变成 6 个 job：`AI game creator shell Rust shard 1/4` ~ `4/4`、`AI game creator shell Rust smoke`、`AI game creator shell Rust crates`。 - 前置瘦身：AGC 壳有独立 `Cargo.lock`，其 path 依赖已包含 `platform-llm` / `platform-agent` / `agent-runtime-core` / `shared-contracts`，所以 4 个分片 job 与 smoke job 只需预热 AGC 壳这一份 manifest；这些 job 只用 cargo 与 node 内建模块，因此 **5 个壳 job 与 crates job 都不再执行 `npm ci`**（每个省 1~3 分钟）。 -- 影响范围：`.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 预热顺序断言）、开发运维文档与共享记忆。Gitea `master` 分支保护的 required context 是追加式的，需补上 6 个新 context（共十一个）。 +- 影响范围：`.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)。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index c1632f879..8f876bbe7 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -8,6 +8,7 @@ - **反面实验（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 内多进程并行多个片（实测比串行还慢）。 +- **分支保护口径**（2026-09-14 复核）：本仓库不把 Project CI 的 context 配成 `master` 分支保护的合并必需检查，合并前由人工确认最近一次结果；因此 job 拆分或改名不需要同步分支保护设置，代价是门禁红了不会自动阻止合并。 - **关联**：`apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs`、`.gitea/workflows/project-ci.yml`、`scripts/check-native-shells.mjs`（`agc-rust-shard-1..4` / `agc-rust-smoke` / `agc-rust-crates` 分组）、`package.json`。 ## 2026-09-14 根门禁的 `[check:native-shells]