From 0ac86f941c97a54251220fde516ed34e2bc31567 Mon Sep 17 00:00:00 2001 From: kdletters <61648117+kdletters@users.noreply.github.com> Date: Mon, 21 Sep 2026 07:55:04 +0800 Subject: [PATCH] =?UTF-8?q?=E4=BC=98=E5=8C=96=20Gitea=20CI=20Rust=20?= =?UTF-8?q?=E5=88=86=E7=89=87=E5=B9=B6=E5=8F=91?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将四个 AGC Rust shard 合并为两条 lane，减少重复预热与排队 同步 workflow 契约测试、分片说明和运维文档 --- .gitea/workflows/project-ci.yml | 86 +++---------------- .../scripts/run-rust-shell-test-shards.mjs | 3 +- deploy/container/README.md | 4 +- .../shared-memory/decision-log.md | 6 ++ .../shared-memory/development-workflow.md | 2 +- docs/project-memory/shared-memory/pitfalls.md | 4 +- ...发运维】本地开发验证与生产运维-2026-05-15.md | 12 +-- scripts/check-native-shells.mjs | 6 +- scripts/project-ci-workflow.test.ts | 42 ++++----- 9 files changed, 53 insertions(+), 112 deletions(-) diff --git a/.gitea/workflows/project-ci.yml b/.gitea/workflows/project-ci.yml index fa1c68d1d..52394b9a1 100644 --- a/.gitea/workflows/project-ci.yml +++ b/.gitea/workflows/project-ci.yml @@ -31,28 +31,26 @@ env: RUSTC_WRAPPER: '' CARGO_BUILD_RUSTC_WRAPPER: '' -# job 声明顺序就是 runner 领取顺序，因此把最长尾的客户端 Rust 门禁排在前面， +# job 声明顺序就是 runner 领取顺序，因此把两条最长尾的客户端 Rust lane 排在前面， # 让它在最少的等待下占用并发槽位；其余 job 按时长递减排列。 # # 客户端（微信壳 / Expo 移动壳 / Tauri 桌面壳 / AI 游戏创作壳）门禁原先全部串在 # `Native shell tests` 一个 job 里，实测 18 分 37 秒。现在按门禁组拆成一个分组一个 job： # `Native shell tests`（契约 + H5 / 微信 / 移动 / 桌面壳门禁 + 发布构建 smoke）、 # `AI game creator shell web tests`（typecheck + 壳内测试）、`AI game creator shell -# Rust shard 1/4` 到 `4/4`（AGC 壳 bin 单测按名单分 4 片）、`AI game creator shell -# Rust smoke`（agent-run smoke）与 `AI game creator shell Rust crates`（AGC 壳依赖的 +# Rust lane 1/2`、`lane 2/2`（每条 lane 顺序运行两片 AGC 壳 bin 单测）、`AI game creator +# shell Rust smoke`（agent-run smoke）与 `AI game creator shell Rust crates`（AGC 壳依赖的 # 共享 / 平台 crate 测试）。各自的命令与拆分前逐一对应，本地 # `npm run check:native-shells` 仍是同一条串行序列。 # -# AGC 壳的 bin 单测（2466 条）按名单分 4 片、一片一个 job：片内保持 `--test-threads=1` -# （当年线程并行会互相干扰的是进程内后台锁与异步终态），片与片之间靠 job 级并发摊开。 -# 不要改回「一个 job 里多进程并行这几片」：同一容器内它们会争抢共享 HOME、target 与固定 -# 临时路径，实测比整套串行还慢。每个分片 job 都会自校验「片并集等于全集且互斥」。 +# AGC 壳的 bin 单测（2466 条）仍按名单分 4 片、片内保持 `--test-threads=1`；两条 lane +# 各自顺序运行两片，让一次 job 只做一次依赖预热，同时避免同一容器内多进程并行争抢 +# 共享 HOME、target 与固定临时路径。每个分片调用仍会自校验「片并集等于全集且互斥」。 jobs: - # AGC 壳自身的 Rust bin 单测分片，4 片各自独立 job 并发执行、片内仍保持 - # `--test-threads=1`。这里不装 npm 依赖：壳 Rust 门禁只用 cargo 与 node 内建模块， - # 也只需要 AGC 壳自己那份锁定依赖。 - ai-game-creator-shell-rust-shard-1: - name: AI game creator shell Rust shard 1/4 + # AGC 壳自身的 Rust bin 单测由两条 lane 承载，每条 lane 顺序运行两片；这里不装 npm + # 依赖：壳 Rust 门禁只用 cargo 与 node 内建模块，也只需要 AGC 壳自己那份锁定依赖。 + ai-game-creator-shell-rust-lane-1: + name: AI game creator shell Rust lane 1/2 runs-on: genarrative-ci steps: - name: Checkout full history from Gitea @@ -87,41 +85,11 @@ jobs: - name: Run AI game creator shell Rust shard 1/4 run: npm run check:native-shells:agc-rust-shard-1 - ai-game-creator-shell-rust-shard-2: - name: AI game creator shell Rust shard 2/4 - runs-on: genarrative-ci - steps: - - name: Checkout full history from Gitea - env: - GENARRATIVE_GITEA_FETCH_DEPTH: '0' - GENARRATIVE_GITEA_TOKEN: ${{ github.token }} - run: genarrative-gitea-checkout - - - name: Validate preinstalled CI job image and sandbox - run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh - - - name: Prepare AI game creator shell Rust dependencies - shell: bash - run: | - set -euo pipefail - for attempt in $(seq 1 5); do - if cargo fetch --locked \ - --target x86_64-unknown-linux-gnu \ - --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml; then - break - fi - if [[ "${attempt}" -eq 5 ]]; then - echo 'AI game creator shell Cargo dependency fetch failed after 5 attempts.' >&2 - exit 1 - fi - sleep $((attempt * 2)) - done - - name: Run AI game creator shell Rust shard 2/4 run: npm run check:native-shells:agc-rust-shard-2 - ai-game-creator-shell-rust-shard-3: - name: AI game creator shell Rust shard 3/4 + ai-game-creator-shell-rust-lane-2: + name: AI game creator shell Rust lane 2/2 runs-on: genarrative-ci steps: - name: Checkout full history from Gitea @@ -153,36 +121,6 @@ jobs: - name: Run AI game creator shell Rust shard 3/4 run: npm run check:native-shells:agc-rust-shard-3 - ai-game-creator-shell-rust-shard-4: - name: AI game creator shell Rust shard 4/4 - runs-on: genarrative-ci - steps: - - name: Checkout full history from Gitea - env: - GENARRATIVE_GITEA_FETCH_DEPTH: '0' - GENARRATIVE_GITEA_TOKEN: ${{ github.token }} - run: genarrative-gitea-checkout - - - name: Validate preinstalled CI job image and sandbox - run: GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1 bash scripts/check-gitea-ci-job-image.sh - - - name: Prepare AI game creator shell Rust dependencies - shell: bash - run: | - set -euo pipefail - for attempt in $(seq 1 5); do - if cargo fetch --locked \ - --target x86_64-unknown-linux-gnu \ - --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml; then - break - fi - if [[ "${attempt}" -eq 5 ]]; then - echo 'AI game creator shell Cargo dependency fetch failed after 5 attempts.' >&2 - exit 1 - fi - sleep $((attempt * 2)) - done - - name: Run AI game creator shell Rust shard 4/4 run: npm run check:native-shells:agc-rust-shard-4 diff --git a/apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs b/apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs index 80c96fda2..86c70601a 100644 --- a/apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs +++ b/apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.mjs @@ -7,7 +7,8 @@ // 整套用例串行跑满 507 秒，占掉 CI 上 `AI game creator shell Rust tests` job 的大头。 // // 这里保留「片内串行」的既有口径，只把用例集合切成 N 片： -// - CI 用 `--shard-index=` 让**每个 job 只跑一片**，靠多个 job 并发把整套用例摊开； +// - CI 用 `--shard-index=` 让**每次分片调用只跑一片**，由两条 lane job 顺序承载两片， +// 在不重复预热依赖的前提下保留 job 级并发； // - 本地不传 `--shard-index` 时把 N 片放进 N 个**独立进程**并行（--concurrency 可调）， // 保留一条命令跑全量的入口。 // 片并集必须等于全集、且不得重复，数量不符即失败，防止分片规则改动后静默漏跑；该校验 diff --git a/deploy/container/README.md b/deploy/container/README.md index e5901466d..ee883f084 100644 --- a/deploy/container/README.md +++ b/deploy/container/README.md @@ -68,7 +68,7 @@ Jenkins 分支预览构建固定从宿主 `/data/jenkins/preview-secrets/.env.lo ### Gitea CI 预构建 Job 镜像 -`.gitea/workflows/project-ci.yml` 的四个 job 统一使用 `deploy/container/gitea-ci-job.Dockerfile` 构建的 `genarrative-ci` 环境。镜像固定 Ubuntu job base digest `sha256:58ea92624c7c09582e05594d95488331045053d3a3f34cf09649f2a32313a614` 和 Rust stage digest `sha256:93ce27a88655056a51dbdd8f5f2d7ddc071c7b0070fb288a37b5a285fc83971e`；Node `22.23.1` 发行包在解压前执行 SHA-256 校验，Google Linux 主签名指纹固定为 `EB4C1BFD4F042F6DDDCCEC917721F63BD38B4796`，Chrome 固定为 `153.0.8010.52-1`。镜像预装 Rust `1.98.1`、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖，并设置 `RUSTUP_AUTO_INSTALL=0`；仓库工具链变更时必须先重建镜像，不允许 job 现场下载补齐。 +`.gitea/workflows/project-ci.yml` 的所有 job 统一使用 `deploy/container/gitea-ci-job.Dockerfile` 构建的 `genarrative-ci` 环境。镜像固定 Ubuntu job base digest `sha256:58ea92624c7c09582e05594d95488331045053d3a3f34cf09649f2a32313a614` 和 Rust stage digest `sha256:93ce27a88655056a51dbdd8f5f2d7ddc071c7b0070fb288a37b5a285fc83971e`；Node `22.23.1` 发行包在解压前执行 SHA-256 校验，Google Linux 主签名指纹固定为 `EB4C1BFD4F042F6DDDCCEC917721F63BD38B4796`，Chrome 固定为 `153.0.8010.52-1`。镜像预装 Rust `1.98.1`、`rustfmt`、Chrome、`bwrap`、`rg`、`ffmpeg`、`clang/lld` 和 Tauri / 后端系统依赖，并设置 `RUSTUP_AUTO_INSTALL=0`；仓库工具链变更时必须先重建镜像，不允许 job 现场下载补齐。 构建、校验和装入 runner 内层 Docker： @@ -81,7 +81,7 @@ bash scripts/gitea-ci-job-image.sh load-runner 默认构建 tag 为 `genarrative/gitea-project-ci:20260920.2`。脚本通过 NUL 分隔白名单 tar 流只发送 Dockerfile、checkout 脚本、根 workspace 的唯一 npm lock 与全部 workspace manifest，以及 server-rs、桌面壳和 AI 游戏创作壳的 Cargo manifests/lock，外加 AI 游戏创作壳本地路径依赖的三个编辑器 bridge crate 源树；不会把业务源码、素材或本地私密文件发送给 Docker daemon。新镜像显式安装并精确校验 `npm 10.9.7`，不依赖 Node 发行包隐含的 npm 版本；除固定工具链外，还按一份 npm workspace lock 与三份 Cargo lock 预热下载缓存。npm 只执行一次忽略 lifecycle scripts 的 workspace `npm ci`（最多 5 次整命令级有界重试，处理 registry ECONNRESET），三个 `cargo fetch --locked` 最多执行 5 次整命令级有界重试，再分别以断网 `cargo fetch --locked` 验证缓存闭合，镜像不包含 `node_modules` 或 Cargo `target`。`build` 完成后会自动运行环境校验，`load-runner` 还会比对宿主和 runner 内层的完整 Image ID，并在内层执行 bwrap 与 Chrome headless canary。workspace lock 或 manifest 变化落地后必须按下述顺序重建并装载镜像；过渡期旧固定镜像缺少 `GENARRATIVE_GITEA_CI_NPM_VERSION` 时，校验只输出 `npm_version=partial` 和 Actions warning，继续由当前 job 的根 `npm ci` 验证唯一 lock，不能据此宣称 npm 版本或新依赖缓存已经闭合。执行这些命令不要求必须使用 root，但执行账号必须有权访问宿主 Docker API 并管理 runner 容器；没有该权限时交给 runner 运维人员执行。 -runner 配置保留原 `ubuntu-latest` 映射，`genarrative-ci` 继续映射到经 `build / verify / load-runner` 验证并写入配置的完整 Image ID。内层 Docker 数据必须持久化，`force_pull` 保持 `false`；该精确 Image ID 在内层不存在时 job 应直接失败，不回退到浮动 tag 或现场拉取。四个 job 使用镜像内 `genarrative-gitea-checkout` 直接从当前 Gitea 拉取事件 commit，带 5 次有界重试，不再运行时下载 GitHub checkout action；随后以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，同时校验工具链、一份 npm workspace 缓存锁、三份 Cargo 缓存锁、bwrap 和 Chrome headless。锁不匹配时校验会输出 `partial` 和醒目的 Actions warning，提示在可信分支落地后刷新镜像。各 job 仍各自运行一次干净的根 `npm ci`，以唯一 workspace lock 校验全部 App/package/tool 依赖并隔离 PR 依赖；统一通过 `scripts/ci-npm-ci-with-retry.sh` 最多执行 3 次整命令级有界重试，并使用镜像内 npm cache 和 `prefer-offline`。锁文件新增依赖时允许经受控网络补齐，本阶段不启用共享 Actions cache。 +runner 配置保留原 `ubuntu-latest` 映射，`genarrative-ci` 继续映射到经 `build / verify / load-runner` 验证并写入配置的完整 Image ID。内层 Docker 数据必须持久化，`force_pull` 保持 `false`；该精确 Image ID 在内层不存在时 job 应直接失败，不回退到浮动 tag 或现场拉取。各个 job 使用镜像内 `genarrative-gitea-checkout` 直接从当前 Gitea 拉取事件 commit，带 5 次有界重试，不再运行时下载 GitHub checkout action；随后以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，同时校验工具链、一份 npm workspace 缓存锁、三份 Cargo 缓存锁、bwrap 和 Chrome headless。锁不匹配时校验会输出 `partial` 和醒目的 Actions warning，提示在可信分支落地后刷新镜像。各 job 仍各自运行一次干净的根 `npm ci`，以唯一 workspace lock 校验全部 App/package/tool 依赖并隔离 PR 依赖；统一通过 `scripts/ci-npm-ci-with-retry.sh` 最多执行 3 次整命令级有界重试，并使用镜像内 npm cache 和 `prefer-offline`。锁文件新增依赖时允许经受控网络补齐，本阶段不启用共享 Actions cache。 更新顺序固定为： diff --git a/docs/project-memory/shared-memory/decision-log.md b/docs/project-memory/shared-memory/decision-log.md index aae019f90..411f0a3c8 100644 --- a/docs/project-memory/shared-memory/decision-log.md +++ b/docs/project-memory/shared-memory/decision-log.md @@ -306,6 +306,12 @@ Godot 编辑器操控复用既有 AGC 插件宿主、EditorAdapter、Runner 和 - 验证方式：`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` 坐标、按当前资源与拓扑整体重算」；新增一张素材必然改签名，于是既有自动卡全部跟着挪位，用户刚记住的位置就没了。画布上也没有任何显式整理入口（`复位资源视图` 只复位视口）。 diff --git a/docs/project-memory/shared-memory/development-workflow.md b/docs/project-memory/shared-memory/development-workflow.md index 65d4e4c47..7a3006746 100644 --- a/docs/project-memory/shared-memory/development-workflow.md +++ b/docs/project-memory/shared-memory/development-workflow.md @@ -94,4 +94,4 @@ SpacetimeDB 任务统一先读取 `.codex/skills/genarrative-spacetimedb/SKILL.m ## 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=` 只跑自己那片，片内保持 `--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=` 只跑自己那片，片内保持 `--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 镜像缓存，再重跑门禁。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index af56d5494..4136d4b7b 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -156,7 +156,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=` 只跑自己那片（`--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=` 只跑自己那片（`--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 内多进程并行多个片（实测比串行还慢）。 @@ -183,7 +183,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` 分支保护设置。 diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index cd0a026f1..0596085fc 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -282,7 +282,7 @@ npm run check ### Gitea Actions PR 门禁 -仓库级 Gitea Actions 工作流固定为 `.gitea/workflows/project-ci.yml`，在向 `master` 推送、创建或更新 PR，以及手工触发时运行。工作流拆成十一个必须通过的 job。job 声明顺序就是 runner 领取顺序，因此把 4 个 AGC 壳 Rust 分片 job 排在最前：并发槽位不足时它们必须最先开始，AGC 侧的关键路径才由自己而不是由排队决定。 +仓库级 Gitea Actions 工作流固定为 `.gitea/workflows/project-ci.yml`，在向 `master` 推送、创建或更新 PR，以及手工触发时运行。工作流拆成九个必须通过的 job。job 声明顺序就是 runner 领取顺序，因此把两条 AGC 壳 Rust lane 排在最前：并发槽位不足时它们必须最先开始，AGC 侧的关键路径才由自己而不是由排队决定。 所有 CI job 和 Jenkins Web Build 在根 workspace 安装前都必须确认 `npm --version` 为 `10.9.7`。Gitea job 使用预构建镜像内的固定版本；Jenkins Web Build 在每个独立 `bash -lc` 中 source `scripts/jenkins-prepare-npm-env.sh`，首次为 Jenkins 运行用户的版本隔离目录引导同版 npm，后续复用并把该 `bin` 放到 `PATH` 首位。旧固定镜像缺少版本元数据时只能报告 `npm_version=partial` 并由当前 job 的根 `npm ci` 继续校验 lock，不能把过渡状态当作工具链已闭合。 @@ -291,11 +291,11 @@ npm run check - `Backend tests`：先对 `server-rs/Cargo.lock` 执行带 5 次整命令级有界重试的 `cargo fetch --locked`，再执行 `npm run check:server-rs-ddd`、`cargo test --locked --workspace --exclude spacetime-module --no-fail-fast`、`cargo test --locked -p spacetime-module --no-fail-fast`、`api-server --all-targets` 编译和 `cargo check --locked -p spacetime-module`；普通 workspace host 测试排除 `spacetime-module` 以避免其 `spacetime-types` feature 统一污染领域 crate，模块自身的纯单元测试通过独立 package test 纳入门禁。`spacetime-module` 的 reducer / procedure 运行时行为仍必须通过真实 SpacetimeDB runtime/integration harness 验证，不能把 host 链接支持当作运行时替身。依赖准备必须位于会触发 Cargo build 的 DDD / 产物边界门禁之前，避免锁新增依赖未命中镜像缓存时绕过既有下载重试。runner 安装 `ffmpeg`，避免视频抽帧测试因工具缺失提前返回。依赖真实服务或密钥的测试必须显式 `ignored`，不能让普通 PR job访问现场环境。 - `Native shell tests`：按唯一根 workspace lockfile 安装全部 App 依赖后，用 `npm run check:native-shells:contract`、`npm run check:native-shells:shells` 和 `npm run check:native-shells:release` 分别执行静态契约、H5 / 微信 / Expo / Tauri 桌面壳运行时门禁，以及依赖发布产物的构建 smoke，最后确认桌面壳与 AI 游戏创作壳的 `Cargo.lock` 都没有被构建过程改写。 - `AI game creator shell web tests`：执行 `npm run check:native-shells:agc-web`（即 `npm run ai-game-creator-shell:check:web`：AGC 壳 typecheck 与壳内测试）。该分组不触碰 Cargo，因此不预热 Rust 依赖。 -- `AI game creator shell Rust shard 1/4` ~ `4/4`：四个片 job 各自只预热 AGC 壳自己那份锁定依赖（`apps/ai-game-creator-shell/src-tauri/Cargo.lock` 的 path 依赖已含 `platform-llm`、`platform-agent`、`agent-runtime-core` 与 `shared-contracts`），然后执行 `npm run check:native-shells:agc-rust-shard-`（即分片运行器的 `--shard-index=`）：AGC 壳 bin target 的 2466 条 Rust 单测按 `--list` 名单排序后切 4 片，每个 job 只跑自己那片，片内保持 `--test-threads=1`、各片独立 `TMPDIR`，片与片之间靠 job 级并发摊开；每个 job 都会自校验「片并集等于全集且互斥」。**不要**改回「一个 job 里多进程并行这几片」：同一容器内它们共享 `HOME`、target 与固定临时路径，实测（run 2102）比整套串行还慢。这些 job 只用 cargo 与 node 内建模块，因此不装 npm 依赖。 +- `AI game creator shell Rust lane 1/2`、`lane 2/2`：两条 lane 各自只预热一次 AGC 壳自己的锁定依赖（`apps/ai-game-creator-shell/src-tauri/Cargo.lock` 的 path 依赖已含 `platform-llm`、`platform-agent`、`agent-runtime-core` 与 `shared-contracts`），然后顺序执行两次 `npm run check:native-shells:agc-rust-shard-`（每次分片运行器使用对应的 `--shard-index=`）：AGC 壳 bin target 的 2466 条 Rust 单测按 `--list` 名单排序后切 4 片，片内保持 `--test-threads=1`、各片独立 `TMPDIR`，两条 lane 之间靠 job 级并发摊开；每次分片调用都会自校验「片并集等于全集且互斥」。**不要**改回「一个 job 里多进程并行这几片」：同一容器内它们共享 `HOME`、target 与固定临时路径，实测（run 2102）比整套串行还慢。这些 lane 只用 cargo 与 node 内建模块，因此不装 npm 依赖。 - `AI game creator shell Rust smoke`：同样只预热 AGC 壳那份锁定依赖，执行 `npm run check:native-shells:agc-rust-smoke`（即 `npm run ai-game-creator-shell:agent-run:smoke`）。smoke 会用 `src-tauri/Cargo.toml` spawn `cargo run`，单独一个 job 以免把已经压到分钟级的片 job 拖长；只用 cargo 与 node 内建模块（脚本只 import `node:*`），因此不装 npm 依赖。 - `AI game creator shell Rust crates`：预热 `server-rs/Cargo.toml` 与两个无锁独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`）后执行 `npm run check:native-shells:agc-rust-crates`（即 `npm run ai-game-creator-shell:check:rust:crates`），覆盖 `agent-runtime-core`、`agent-runtime-orchestration`、`platform-llm` 与 `shared-contracts`。这四条命令用的是 server-rs workspace 与独立 crate 的 manifest，属另一套依赖图，因此单独一个 job，也只跑 cargo、不装 npm 依赖。 -十一个 job 合起来覆盖根 `npm run check`，并补齐根检查没有包含的 BgFilter worker smoke harness、无密钥生产巡检 / 发布 / 部署行为 fixture、server-rs DDD、正式 workspace Rust 测试与现役后端编译门禁。客户端门禁的拆分口径是 `scripts/check-native-shells.mjs` 的 `--groups=`：十个分组（`contract`、`shells`、`agc-web`、`agc-rust-crates`、`agc-rust-shard-1` ~ `agc-rust-shard-4`、`agc-rust-smoke`、`release`）各自对应一个 `check:native-shells:` 根脚本，并在 workflow 的某个 job 里被恰好调用一次；不带 `--groups=` 时脚本仍然串行跑全部分组，本地语义不变。`scripts/project-ci-workflow.test.ts` 会同时校验分组清单、根脚本内容、job 覆盖与分片运行器，新增分组必须三处同步。普通 PR CI 不注入业务密钥，不启动真实 API、SpacetimeDB、OSS、支付、图片生成或生产 live smoke；需要现场环境、可变外部状态、Docker 编排或发布凭据的 `check:*` 继续按对应专题和 Jenkins 发布流程执行，不能遍历所有同名前缀脚本冒充 PR 门禁。 +九个 job 合起来覆盖根 `npm run check`，并补齐根检查没有包含的 BgFilter worker smoke harness、无密钥生产巡检 / 发布 / 部署行为 fixture、server-rs DDD、正式 workspace Rust 测试与现役后端编译门禁。客户端门禁的拆分口径是 `scripts/check-native-shells.mjs` 的 `--groups=`：十个分组（`contract`、`shells`、`agc-web`、`agc-rust-crates`、`agc-rust-shard-1` ~ `agc-rust-shard-4`、`agc-rust-smoke`、`release`）各自对应一个 `check:native-shells:` 根脚本，并在 workflow 的某个 lane/job 里被恰好调用一次；每个 Rust lane 顺序调用两组，不带 `--groups=` 时脚本仍然串行跑全部分组，本地语义不变。`scripts/project-ci-workflow.test.ts` 会同时校验分组清单、根脚本内容、lane/job 覆盖与分片运行器，新增分组必须三处同步。普通 PR CI 不注入业务密钥，不启动真实 API、SpacetimeDB、OSS、支付、图片生成或生产 live smoke；需要现场环境、可变外部状态、Docker 编排或发布凭据的 `check:*` 继续按对应专题和 Jenkins 发布流程执行，不能遍历所有同名前缀脚本冒充 PR 门禁。 PR checkout 必须保留完整 Git 历史，并把 PR base SHA 传给 `SPACETIME_SCHEMA_BASE_REF`。`check:spacetime-schema` 依赖该基线识别已有表字段删除、改名、重排和改类型；事件给出的基线缺失或本地不可解析时必须直接失败，不能退化为空差异检查。Gitea 的 PR checkout 是 PR head，不是与目标分支的预合并 commit，因此 workflow 还会验证 PR head 包含事件中的最新 base commit；分支保护必须继续开启“PR 过期禁止合并”，过期分支先更新再重跑。向 `master` 直接推送时使用 push before SHA；手工触发先尝试 `origin/master`，若它与 `HEAD` 相同则改用 `HEAD^`，仍无法得到不同提交时失败关闭。 @@ -314,13 +314,13 @@ bash scripts/gitea-ci-job-image.sh export /仓库外受控路径/genarrative-git bash scripts/gitea-ci-job-image.sh load-runner ``` -执行账号只要有权访问宿主 Docker API 并管理 runner 容器即可，不强制使用 root；无该权限时由 runner 运维人员执行。更新顺序必须是 `build/verify -> export 仓库外镜像归档与 SHA-256 sidecar -> load-runner -> 确认无活跃 job -> 备份当前 config -> 增加或替换 label -> docker restart --timeout 660 gitea-runner`。`--timeout 660` 只是停止宽限，不是 drain API；rootless DinD supervisor 可能同时停止内层 dockerd，因此重启前必须确认 Gitea 没有 `in_progress` run 且内层 `docker ps` 为空。config 和镜像归档只保存到仓库外受控位置，不在文档、仓库或日志中记录注册信息。重启后先重跑真实 PR 的十一个 job，复核隔离边界并确认全部通过，再清理旧镜像。回滚时先把 workflow 的 `runs-on` 改回 `ubuntu-latest`，再恢复 config 备份并重启 runner。 +执行账号只要有权访问宿主 Docker API 并管理 runner 容器即可，不强制使用 root；无该权限时由 runner 运维人员执行。更新顺序必须是 `build/verify -> export 仓库外镜像归档与 SHA-256 sidecar -> load-runner -> 确认无活跃 job -> 备份当前 config -> 增加或替换 label -> docker restart --timeout 660 gitea-runner`。`--timeout 660` 只是停止宽限，不是 drain API；rootless DinD supervisor 可能同时停止内层 dockerd，因此重启前必须确认 Gitea 没有 `in_progress` run 且内层 `docker ps` 为空。config 和镜像归档只保存到仓库外受控位置，不在文档、仓库或日志中记录注册信息。重启后先重跑真实 PR 的九个 job，复核隔离边界并确认全部通过，再清理旧镜像。回滚时先把 workflow 的 `runs-on` 改回 `ubuntu-latest`，再恢复 config 备份并重启 runner。 -十一个 job 先运行镜像内 `genarrative-gitea-checkout`，再以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，校验 Node 与 npm 固定版本、仓库 Rust toolchain、受信任 PATH、四份缓存锁命中状态、原生命令、pkg-config 依赖、完整 bwrap sandbox 和 Chrome headless。运行时发现锁不匹配时必须输出对应 `*_cache_lock=partial` 和 Actions warning，提示可信分支落地后刷新镜像，不能把陈旧缓存误报为闭合。`RUSTUP_AUTO_INSTALL=0`，因此仓库 `rust-toolchain.toml` 变更必须先更新镜像，不能让 job 现场下载。需要 `node_modules` 的 job 仍各自独立运行一次根 `npm ci`，以唯一 workspace lock 验证 PR 的全部 App 依赖；4 个 AGC 壳 Rust 分片 job、`AI game creator shell Rust smoke` 与 `AI game creator shell Rust crates` 是纯 cargo 门禁（只用 cargo 与 node 内建模块），显式不装 npm 依赖，这也由 `scripts/project-ci-workflow.test.ts` 钉住。`npm ci` 统一通过 `scripts/ci-npm-ci-with-retry.sh` 做最多 3 次整命令级有界重试，同时保留 `NPM_CONFIG_PREFER_OFFLINE=true` 和 npm 自身 10 次 fetch retry。命中镜像 cache 时只做干净解包，lock 变化时允许补齐差量。不在镜像内烘入 `node_modules`，也不挂载跨 PR 可写缓存。任何 job 的 sandbox canary 失败都必须停止，不允许跳过。Cargo 通过受控 proxy 下载 lock 差量时继续关闭 HTTP multiplexing，并设置 `CARGO_NET_RETRY=10`。 +九个 job 先运行镜像内 `genarrative-gitea-checkout`，再以 `GENARRATIVE_GITEA_CI_CHECK_RUNTIME=1` 执行 `scripts/check-gitea-ci-job-image.sh`，校验 Node 与 npm 固定版本、仓库 Rust toolchain、受信任 PATH、四份缓存锁命中状态、原生命令、pkg-config 依赖、完整 bwrap sandbox 和 Chrome headless。运行时发现锁不匹配时必须输出对应 `*_cache_lock=partial` 和 Actions warning，提示可信分支落地后刷新镜像，不能把陈旧缓存误报为闭合。`RUSTUP_AUTO_INSTALL=0`，因此仓库 `rust-toolchain.toml` 变更必须先更新镜像，不能让 job 现场下载。需要 `node_modules` 的 job 仍各自独立运行一次根 `npm ci`，以唯一 workspace lock 验证 PR 的全部 App 依赖；两条 AGC 壳 Rust lane、`AI game creator shell Rust smoke` 与 `AI game creator shell Rust crates` 是纯 cargo 门禁（只用 cargo 与 node 内建模块），显式不装 npm 依赖，这也由 `scripts/project-ci-workflow.test.ts` 钉住。`npm ci` 统一通过 `scripts/ci-npm-ci-with-retry.sh` 做最多 3 次整命令级有界重试，同时保留 `NPM_CONFIG_PREFER_OFFLINE=true` 和 npm 自身 10 次 fetch retry。命中镜像 cache 时只做干净解包，lock 变化时允许补齐差量。不在镜像内烘入 `node_modules`，也不挂载跨 PR 可写缓存。任何 job 的 sandbox canary 失败都必须停止，不允许跳过。Cargo 通过受控 proxy 下载 lock 差量时继续关闭 HTTP multiplexing，并设置 `CARGO_NET_RETRY=10`。 站点 stack 仍由宿主受控目录管理，`.env`、runner 注册文件和数据库凭据不进入仓库。Compose 必须在 helper/container 内把该目录挂到与宿主相同的绝对路径再执行；挂载到不同路径会让相对 bind source 被 Docker daemon 解析到错误的宿主目录并启动空数据。升级或 runner 迁移前先停止 Gitea 写入，并把 Gitea 冷快照、数据库导出、compose/env 与 runner config/.runner 保存到仓库外受控备份位置。备份文件、绝对宿主配置和注册 token 不得提交 Git，也不在共享文档中记录具体路径或注册内容。 -workflow 首次成功运行后，**不**把 Project CI 的 job 配成 Gitea `master` 分支保护的合并必需检查（2026-09-14 复核口径）：合并前由人工确认最近一次 Project CI 结果，因此 job 拆分或改名都不需要同步分支保护设置，代价是门禁 job 红了不会自动阻止合并。若将来改成"当前 head 全绿才能合并"，清单是 11 个完整 context：`Project CI / Repository checks (pull_request)`、`Project CI / Frontend tests (pull_request)`、`Project CI / Backend tests (pull_request)`、`Project CI / Native shell tests (pull_request)`、`Project CI / AI game creator shell web tests (pull_request)`、`Project CI / AI game creator shell Rust shard 1/4 (pull_request)` ~ `Project CI / AI game creator shell Rust shard 4/4 (pull_request)`、`Project CI / AI game creator shell Rust smoke (pull_request)`、`Project CI / AI game creator shell Rust crates (pull_request)`；必须用 Gitea 实际上报的 ` / ()`，不能只填裸 job 名，也不能让清单里残留已不再上报的旧 job 名（例如拆分前的 `AI game creator shell Rust tests`），否则 PR 会永远停在"等待该检查"。只提交 workflow 文件不会自动创建 runner；如果 Actions 长时间停留在等待状态，先到仓库或组织的 Actions runner 页面确认存在在线、带 `genarrative-ci` 标签的 runner，再检查精确 Image ID 是否已装入内层 Docker。 +workflow 首次成功运行后，**不**把 Project CI 的 job 配成 Gitea `master` 分支保护的合并必需检查（2026-09-14 复核口径）：合并前由人工确认最近一次 Project CI 结果，因此 job 拆分或改名都不需要同步分支保护设置，代价是门禁 job 红了不会自动阻止合并。若将来改成"当前 head 全绿才能合并"，清单是 9 个完整 context：`Project CI / Repository checks (pull_request)`、`Project CI / Frontend tests (pull_request)`、`Project CI / Backend tests (pull_request)`、`Project CI / Native shell tests (pull_request)`、`Project CI / AI game creator shell web tests (pull_request)`、`Project CI / AI game creator shell Rust lane 1/2 (pull_request)`、`Project CI / AI game creator shell Rust lane 2/2 (pull_request)`、`Project CI / AI game creator shell Rust smoke (pull_request)`、`Project CI / AI game creator shell Rust crates (pull_request)`；必须用 Gitea 实际上报的 ` / ()`，不能只填裸 job 名，也不能让清单里残留已不再上报的旧 job 名（例如拆分前的 `AI game creator shell Rust tests`），否则 PR 会永远停在"等待该检查"。只提交 workflow 文件不会自动创建 runner；如果 Actions 长时间停留在等待状态，先到仓库或组织的 Actions runner 页面确认存在在线、带 `genarrative-ci` 标签的 runner，再检查精确 Image ID 是否已装入内层 Docker。 master 日常交付必须禁止直接 push，只允许经 PR 在最近一次 Project CI 全绿后合并；本地 `pre-commit` 的 staged ESLint/Prettier 和 master `pre-push` 的 Repository checks parity 只用于提前发现问题，可被 `--no-verify` 绕过，不能充当服务端权威门禁。紧急直推白名单如需保留，应按人员和时限最小化，并要求执行同一 `npm run check:repository-ci ` 后回读 push CI。 diff --git a/scripts/check-native-shells.mjs b/scripts/check-native-shells.mjs index cef54877b..3912eaf8a 100644 --- a/scripts/check-native-shells.mjs +++ b/scripts/check-native-shells.mjs @@ -87,8 +87,8 @@ const aiGameCreatorViteConfigSource = fs.readFileSync( // - agc-web：AI 游戏创作壳的前端门禁（typecheck 与壳内测试，不触碰 Cargo）。 // - agc-rust-crates：AGC 壳依赖的共享 / 平台 crate 测试（server-rs workspace 加两个 // 无锁独立 crate），只需 server-rs 侧的依赖预热。 -// - agc-rust-shard-1..4：AGC 壳自身的 Rust bin target 单测，按名单切成 4 片，一片一个 -// 分组（CI 里就是一个 job），片内仍保持 `--test-threads=1`；每个分片分组都会做一次 +// - agc-rust-shard-1..4：AGC 壳自身的 Rust bin target 单测，按名单切成 4 片，片内仍保持 +// `--test-threads=1`；CI 由两条 lane job 各顺序运行两片，每个分片分组都会做一次 // 「片并集等于全集且互斥」的自校验。 // - agc-rust-smoke：会用 `src-tauri/Cargo.toml` spawn `cargo run` 的 agent-run smoke。 // 与分片分开，免得把已经压到 4 分钟级的片 job 拖长。 @@ -2321,7 +2321,7 @@ const steps = [ // AI 游戏创作壳原先一步串完 typecheck、壳内测试、共享 / 平台 crate 测试和 // 串行壳测试，CI 因此只有一条 10 分钟以上的长尾。这里按同一组命令切成 // web、rust-crates、rust 分片、smoke 四段，整体顺序与 `npm run ai-game-creator-shell:check` - // 完全一致；CI 把每段（以及每个 rust 分片）放进不同 job 并行执行，本地全量运行仍然是 + // 完全一致；CI 把各组放进 job，Rust 分片由两条 lane 顺序承载，本地全量运行仍然是 // web -> rust(crates -> shards) -> smoke 原顺序。 { group: 'agc-web', diff --git a/scripts/project-ci-workflow.test.ts b/scripts/project-ci-workflow.test.ts index 516fb6720..f55375b98 100644 --- a/scripts/project-ci-workflow.test.ts +++ b/scripts/project-ci-workflow.test.ts @@ -56,10 +56,8 @@ const jobNames = [ 'backend-tests', 'native-shell-tests', 'ai-game-creator-shell-web-tests', - 'ai-game-creator-shell-rust-shard-1', - 'ai-game-creator-shell-rust-shard-2', - 'ai-game-creator-shell-rust-shard-3', - 'ai-game-creator-shell-rust-shard-4', + 'ai-game-creator-shell-rust-lane-1', + 'ai-game-creator-shell-rust-lane-2', 'ai-game-creator-shell-rust-smoke', 'ai-game-creator-shell-rust-crates', ] as const; @@ -69,10 +67,8 @@ const jobNames = [ // 都不需要 node_modules。省掉这些 `npm ci`（各 1~3 分钟）是把客户端 Rust 关键路径 // 压到 7 分钟以内的前提，因此这里显式允许它们不装 npm 依赖。 const jobsWithoutNpmInstall: readonly string[] = [ - 'ai-game-creator-shell-rust-shard-1', - 'ai-game-creator-shell-rust-shard-2', - 'ai-game-creator-shell-rust-shard-3', - 'ai-game-creator-shell-rust-shard-4', + 'ai-game-creator-shell-rust-lane-1', + 'ai-game-creator-shell-rust-lane-2', 'ai-game-creator-shell-rust-smoke', 'ai-game-creator-shell-rust-crates', ]; @@ -465,26 +461,26 @@ describe('project CI workflow', () => { 'plugins/agc-godot-editor/src/entry.test.mjs', ); - // 壳 bin 单测按名单分 4 片，一片一个 job：每个片 job 只跑自己那片，且只预热 AGC 壳 - // 自己那份锁定依赖（server-rs 那份归 crate 级 job）。 - for (const [index, jobName] of [ - [1, 'ai-game-creator-shell-rust-shard-1'], - [2, 'ai-game-creator-shell-rust-shard-2'], - [3, 'ai-game-creator-shell-rust-shard-3'], - [4, 'ai-game-creator-shell-rust-shard-4'], + // 壳 bin 单测仍按名单分 4 片，但由两条 lane 各顺序运行两片；每条 lane 只预热 + // 一次 AGC 壳自己的锁定依赖（server-rs 那份归 crate 级 job）。 + for (const [laneName, indexes] of [ + ['ai-game-creator-shell-rust-lane-1', [1, 2]], + ['ai-game-creator-shell-rust-lane-2', [3, 4]], ] as const) { - const shardJob = jobSection(jobName); - expect(shardJob).toContain( - `run: npm run check:native-shells:agc-rust-shard-${index}`, - ); - expect(shardJob).toContain( + const laneJob = jobSection(laneName); + for (const index of indexes) { + expect(laneJob).toContain( + `run: npm run check:native-shells:agc-rust-shard-${index}`, + ); + } + expect(laneJob).toContain( 'apps/ai-game-creator-shell/src-tauri/Cargo.toml', ); - expect(shardJob).toContain('cargo fetch --locked'); - expect(shardJob).not.toContain('server-rs/Cargo.toml'); + expect(laneJob).toContain('cargo fetch --locked'); + expect(laneJob).not.toContain('server-rs/Cargo.toml'); } - // 整套用例不能再作为一条命令串行跑完：每个片 job 都必须落到分片运行器的 + // 整套用例不能再作为一条命令串行跑完：每个分片调用都必须落到分片运行器的 // `--shard-index` 上，4 个 index 各一次。 for (const index of [1, 2, 3, 4]) { expect(nativeShellGateScript).toContain(`'--shard-index=${index}'`);