diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index c92986e1d..5944ae757 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -415,13 +415,13 @@ cargo check --all-targets --features cocos-editor-execute,unity-editor-execute,g - 非 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 档编、且不跑测试。两侧口径**互不覆盖**。 + - `Native shell tests`(`:376`)里的 `check:native-shells:release` 跑 `npm run ai-game-creator-shell:build -- --no-bundle`(`tauri build`,release 档)。注意:编辑器 feature 由 `defaultEditorFeatures(target)` 决定(`apps/ai-game-creator-shell/scripts/cargo-features.mjs:47-51`)——**只有 target 是 Windows 时才注入 `cocos/unity/godot-editor-execute`,CI 的 Linux runner 上该列表为空**。Linux 上被编到的是**插件 bridge**(godot / unity / cocos 三个 native crate):它们由该 release gate 的插件随包 staging 与 Rust crates job 的 `agc:plugins:native-test` 编译,本次 bridge 的 Linux `-D dead-code` 红因就在这里暴露。 +- 因此三类代码的检查面是:`#[cfg(unix)]` / `#[cfg(target_os = "linux")]` 等非 Windows、非 feature 门控的块**在 CI 被编译并跑测试**;`cfg(windows)` 块**在 CI 从不编译**(Linux runner 上被剔除);编辑器 feature(`cocos/unity/godot-editor-execute`)代码**在 CI 也从不编译**(该组合只对 Windows target 注入,而 CI 只有 Linux runner),只由本机「Windows + 编辑器 feature」口径覆盖。两侧口径**互不覆盖**。 - 实例(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 出现 Linux / macOS 交付面,应在 CI 增加「Linux + 编辑器 feature + `--all-targets`」的检查作业(现状:Linux 档只覆盖默认 feature 的 bin 测试 harness 与插件 bridge 的编译;`cfg(windows)` 块与编辑器 feature 代码两边都不覆盖);当前不新增作业。 - 门禁现状: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 日志与下述脚本) @@ -431,7 +431,7 @@ cargo check --all-targets --features cocos-editor-execute,unity-editor-execute,g | 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`) | +| Native shell tests(:376) | Linux | `check:native-shells:contract` → `…:shells` → `…:release` → `npm run ai-game-creator-shell:build -- --no-bundle`(`tauri build --release`;编辑器 feature 由 `defaultEditorFeatures(target)` 决定,**Linux 上为空**,见 `cargo-features.mjs:47-51`;该 gate 的插件随包 staging 会编 godot / unity / cocos bridge);另 `git diff --exit-code -- apps/*/src-tauri/Cargo.lock` | native | **空**(编辑器 features 仅 Windows target 注入) | 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) | — | — | — |