From 8d7ac9c8ce09121b5b81811930eace7be9eaf5b9 Mon Sep 17 00:00:00 2001 From: Suzumiya Date: Tue, 6 Oct 2026 20:30:18 +0800 Subject: [PATCH] =?UTF-8?q?docs(agc):=20=E6=8C=89=20CI=20=E5=AE=9E?= =?UTF-8?q?=E6=B5=8B=E4=BF=AE=E6=AD=A3=E3=80=8C=E9=9D=9E=20Windows=20cfg?= =?UTF-8?q?=20=E5=9D=97=E4=B8=8D=E8=A2=AB=E6=A3=80=E6=9F=A5=E3=80=8D?= =?UTF-8?q?=E7=9A=84=E9=94=99=E8=AF=AF=E8=A1=A8=E8=BF=B0=EF=BC=8C=E5=B9=B6?= =?UTF-8?q?=E5=86=99=E5=85=A5=20AGC=20=E5=A3=B3=E7=BC=96=E8=AF=91=E7=9F=A9?= =?UTF-8?q?=E9=98=B5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 纠错：原文写「本机与 CI 都只编译 Windows…非 Windows 块内的名字解析永远不会被编译器检查到」是错的——CI 的 Linux lane 确实在编译 AGC 壳并跑测试（本次四个红因里三个就是被 Linux 档抓到的）。 改为按矩阵的准确说法：本机（Windows + 编辑器 feature）不编译非 Windows 块；CI 的 lane 1/2、lane 2/2（Linux 原生 target、默认 feature、bin 测试 harness + `--test runtime_prompt_bundle_build --test prompt_source_boundaries`）与 Rust crates / Repository checks 的 `check:generated-bindings`（`cargo test --locked … export_bindings`）会编译并运行 unix / linux cfg 代码；`cfg(windows)` 块在 CI 从不编译；编辑器 feature 只在 Native shell tests 的 release 档（`tauri build --features 默认编辑器 features --release`）编译且不跑测试；两侧口径互不覆盖。 给「孤例」结论加脚注，并记录 M1（`command_exec.rs:9-13` 的 linux cfg 裸名）判定：`mod command_exec;`（`src/main.rs:92`）无 cfg 且落在 lane 的编译面内 → 若当初跑过 CI，Linux 档会抓到。 补写两条事实：AGC 壳门禁 predicate 为 `#![cfg_attr(all(not(test), windows), deny(warnings))]`；Linux 档在默认 feature 下对壳报出的 54 条 `never used`（Windows 专用实现被整块剔除的产物）不纳入门禁，CI 也不注入 RUSTFLAGS/-D warnings。同时修正旧「门禁现状」行里过时的 predicate。 新增「CI 对 AGC 壳的编译矩阵」表（8 个 job：命令原文 / target / feature / 是否 --all-targets|--test）与证据出处（workflow 行号、run 3612 job 日志、check-native-shells.mjs / check-generated-bindings.mjs / build-release.mjs 行号）。 自检：本提交只改这一个文档文件（1 file changed, +26/-4）；`npm run check:encoding` rc=0、`git diff --check` rc=0。 --- ...发运维】本地开发验证与生产运维-2026-05-15.md | 30 ++++++++++++++++--- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index 4fdc2f628..c92986e1d 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -412,10 +412,32 @@ cargo check --features cocos-editor-execute,unity-editor-execute,godot-editor-ex cargo check --all-targets --features cocos-editor-execute,unity-editor-execute,godot-editor-execute --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml ``` -- 非 Windows cfg 块的静态审计（2026-10-06，对 Windows 口径的补强）：本机与 CI 只编译 Windows（AGC 壳是 WebView2 交付面），所以 `#[cfg(target_os = "linux")]`、`#[cfg(target_os = "macos")]`、`#[cfg(unix)]` 等**非 Windows 块内的名字解析永远不会被编译器检查到**；`--all-targets` 的 test harness 实例告警又不按废弃代码处理，于是“删了一个 glob / 再导出，而只有非 Windows 块还在用”这类问题在 Windows 口径下不可见。实例：`command_exec.rs` 的 `#[cfg(target_os = "linux")]` 块在批次一删掉 crate 根 `use command_sandbox::*;` 之后，其中四个裸名引用只会在 Linux 目标下报 `E0425`。 -- 该次审计的覆盖面与结论：全 crate **463** 个非 Windows cfg 属性 / **68** 个文件 / **355** 个最外层块；块内共 **364** 个裸 crate 引用、**98** 个符号；提供方自带 cfg 的仅 **6** 行且全部消解；四类危险计数（悬空引用 / `not(test)` 越用 / windows-only `use` 被非 Windows 使用点依赖 / 跨平台谓词缺口）**全为 0** → 上述实例是孤例，当前无待修项。 -- 兜底条件（若成立才做）：若将来 AGC 出现 Linux / macOS 交付面，应在 CI 增加对应目标的 `cargo check --all-targets` 作业；当前不新增作业。 -- 门禁现状：AGC 壳用生产口径 `#![cfg_attr(not(test), deny(warnings))]`（`src/main.rs`），其余 crate 用 `[lints.rust] warnings = "deny"`。 +- 非 Windows cfg 块的检查面（2026-10-06 修正，依据是下面这张矩阵：「CI 对 AGC 壳的编译矩阵」）。**本机（Windows + 编辑器 feature 口径）不编译非 Windows 块**；**CI 的 Linux job 会编译并运行其中一部分**： + - `AI game creator shell Rust lane 1/2` 与 `lane 2/2`（`.gitea/workflows/project-ci.yml:54`/`:113`，`runs-on: genarrative-ci`，Linux 原生目标）跑 `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell --no-run --message-format=json-render-diagnostics`（**默认 feature**、bin 测试 harness；命令原文见 run 3612 的 `[rust-shards]` 日志）以及 shard-1 组的 `cargo test --locked … --test runtime_prompt_bundle_build --test prompt_source_boundaries`；随后按片运行同一测试二进制。 + - `AI game creator shell Rust crates`（`:166`）与 `Repository checks`（`:473` 经 `npm run lint`）还会经 `check:generated-bindings` 跑 `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml export_bindings`（同样默认 feature；见 `scripts/check-generated-bindings.mjs:55-62`）。 + - `Native shell tests`（`:376`）里的 `check:native-shells:release` 跑 `npm run ai-game-creator-shell:build -- --no-bundle`（= `tauri build` + 默认编辑器 features，release 档；见 `apps/ai-game-creator-shell/scripts/build-release.mjs:379-394`）——这是编辑器 feature 组合**唯一**被编译的地方，且是生产（非 test）口径。 +- 因此三类代码的检查面是：`#[cfg(unix)]` / `#[cfg(target_os = "linux")]` 等非 Windows、非 feature 门控的块**在 CI 被编译并跑测试**；`cfg(windows)` 块**在 CI 从不编译**（Linux runner 上被剔除）；编辑器 feature 代码只在 release 档编、且不跑测试。两侧口径**互不覆盖**。 +- 实例（M1）：`command_exec.rs` 的 `#[cfg(target_os = "linux")]` 块（`src/command_exec.rs:9-13`）在批次一删掉 crate 根 `use command_sandbox::*;` 之后裸名引用会报 `E0425`；`mod command_exec;` 在 `src/main.rs:92` **没有 cfg**，所以它落在上面两档 lane 的编译面内——**若当初跑过 CI，Linux 档会抓到**。 +- 该次审计的覆盖面与结论：全 crate **463** 个非 Windows cfg 属性 / **68** 个文件 / **355** 个最外层块；块内共 **364** 个裸 crate 引用、**98** 个符号；提供方自带 cfg 的仅 **6** 行且全部消解；四类危险计数（悬空引用 / `not(test)` 越用 / windows-only `use` 被非 Windows 使用点依赖 / 跨平台谓词缺口）**全为 0** → 就「AGC 壳非 Windows 块里的悬挂引用」而言，上述实例是孤例，当前无待修项。 + - 脚注（2026-10-06，随 CI 变绿过程补）：该结论只说明「当时没有第二处悬挂引用」，**不代表 Windows 口径可以替代 Linux 口径**。同日晚 CI 出现的四个红因里有三个——`plugins/agc-{godot,unity}-editor/native/*` 在 Linux 下被新门禁判 `-D dead-code`、AGC 壳在 Linux 下 54 条 `never used` 被生产门禁判死、Linux test harness 3×`E0599`（`CodexAppServerConnection::run_turn`）——**正是被 CI 的 Linux 档抓到、而 Windows 档完全看不见的**。 +- AGC 壳门禁 predicate 与 Linux 档告警的处置（与上一条「AGC 壳的门禁落法」一致）：门禁写成 `#![cfg_attr(all(not(test), windows), deny(warnings))]`（生产口径 + Windows 交付面）；Linux 档在**默认 feature**下会对壳报出一批 `never used`（2026-10-06 实测 54 条，ACL 修复、Windows 策略路径、编辑器 RPC、process session bridge 等在 Linux 被整块剔除后的产物），这批**不纳入门禁**，原因是它们不是废弃生产代码；CI 也不在外部注入 `RUSTFLAGS`/`-D warnings`，因此只作为普通 warning 存在。 +- 兜底条件（若成立才做）：若将来 AGC 出现 Linux / macOS 交付面，应在 CI 增加「Linux + 编辑器 feature + `--all-targets`」的检查作业（当前 Linux 档只覆盖默认 feature 的 bin 测试 harness 与 release 档的编辑器 feature 生产构建，两侧合起来仍不覆盖 `cfg(windows)` 块）；当前不新增作业。 +- 门禁现状：AGC 壳用生产口径 `#![cfg_attr(all(not(test), windows), deny(warnings))]`（`src/main.rs`；两个条件的来历见上），其余 crate 用 `[lints.rust] warnings = "deny"`。 + +#### CI 对 AGC 壳的编译矩阵（2026-10-06 实测；命令原文见 run 3612 job 日志与下述脚本） + +| job（`.gitea/workflows/project-ci.yml` 行） | runner | 走的命令原文 | target | feature 组合 | `--all-targets` / `--test` | +| --- | --- | --- | --- | --- | --- | +| AI game creator shell Rust lane 1/2（:54） | Linux（`runs-on: genarrative-ci`） | `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml --bin genarrative-ai-game-creator-shell --no-run --message-format=json-render-diagnostics`；同组另跑 `cargo test --locked … --test runtime_prompt_bundle_build --test prompt_source_boundaries` | native（无 `--target`） | 默认（不带编辑器 feature） | bin 测试 harness + `--test`；无 `--all-targets` | +| AI game creator shell Rust lane 2/2（:113） | Linux | 同上（shard 3/4 与 `--shard-index` 参数） | native | 默认 | 同上 | +| AI game creator shell Rust crates（:166） | Linux | `npm run agent-runtime-core:check`、`agent-runtime-orchestration:check`、`cargo test --locked -p platform-llm --manifest-path server-rs/Cargo.toml`、`cargo test --locked -p shared-contracts … game_creation_app`、`check:generated-bindings` → `cargo test --locked --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml export_bindings`、`agc:plugins:native-test` → 三个 bridge `cargo test` | native | 默认 | `-p` / `--test`；无 `--all-targets` | +| Native shell tests（:376） | Linux | `check:native-shells:contract` → `…:shells` → `…:release` → `npm run ai-game-creator-shell:build -- --no-bundle`（即 `tauri build --features <默认编辑器 features> --release`）；另 `git diff --exit-code -- apps/*/src-tauri/Cargo.lock` | native | **编辑器 features**（cocos/unity/godot-editor-execute） | release 构建（非 test、非 `--all-targets`） | +| Repository checks（:473） | Linux | `npm run check:repository-ci` → `npm run lint`（内含 `check:generated-bindings`，会编壳）+ 一个 vitest + `npm run build` | native | 默认 | 壳只经 `export_bindings` harness | +| Backend tests（:279） | Linux | server-rs workspace `cargo test`、`cargo check --locked -p api-server --all-targets`、`cargo check --locked -p spacetime-module`、`npm run check:server-rs-ddd`（**不含 AGC 壳**） | native | 默认 | 有 `--all-targets`，但对象是 api-server | +| AI game creator shell web tests（:532） | Linux | `check:native-shells:agc-web`（壳前端 typecheck / vitest；不触碰 Cargo） | — | — | — | +| Frontend tests（:442） | Linux | `npm run test:ci:frontend`、`bgfilter-worker:smoke-test`、`check:production-health-patrol`、`check:production-api-release`、`check:production-api-deploy`（TS，不触碰 Cargo） | — | — | — | + +证据出处：workflow 行号取自 `.gitea/workflows/project-ci.yml`；lane 与 crates 的命令原文取自 run 3612 的 job 日志（lane 日志的 `[rust-shards] cargo …` 行、crates 日志的脚本回显）；gate 表取自 `scripts/check-native-shells.mjs:2324-2400`；绑定检查取自 `scripts/check-generated-bindings.mjs:55-62`；release 构建的 feature 取自 `apps/ai-game-creator-shell/scripts/build-release.mjs:379-394`。 ### Gitea Actions PR 门禁