docs(agc): 记录非 Windows cfg 块的静态审计盲区与结论

dev 运维文档「Rust 编译告警门禁」段末尾追加四条事实说明： ①盲区：本机与 CI 只编 Windows，`#[cfg(target_os = "linux"/"macos")]`、`#[cfg(unix)]` 等非 Windows 块内的名字解析不会被编译器检查，`--all-targets` 的 test harness 实例告警又不按废弃代码处理，因此“删了 glob/再导出、只有非 Windows 块还在用”在 Windows 口径下不可见（实例：command_exec.rs 的 linux cfg 块在批次一删掉 crate 根 `use command_sandbox::*;` 后四个裸名只在 Linux 目标下 E0425）。 ②覆盖面与结论：全 crate 463 个非 Windows cfg 属性 / 68 文件 / 355 个最外层块；块内 364 个裸 crate 引用、98 个符号；提供方自带 cfg 的仅 6 行且全部消解；四类危险计数（悬空 / not(test) 越用 / windows-only use 被非 Windows 使用点依赖 / 跨平台谓词缺口）全为 0 → 本例是孤例，无待修项。 ③兜底条件（若成立才做）：若将来出现 Linux / macOS 交付面，CI 应增加对应目标的 `cargo check --all-targets` 作业；当前不新增作业。 ④门禁现状：AGC 壳用 `#![cfg_attr(not(test), deny(warnings))]`（src/main.rs），其余 crate 用 `[lints.rust] warnings = "deny"`。检查：`npm run check:encoding` rc=0（5408 文件）、`git diff --check` rc=0。注：本次不 push，等用户一并确认后再推。
2026-10-06 17:50:49 +08:00
parent 09cc0a55c6
commit 28373aabe3
1 changed files with 5 additions and 0 deletions
@@ -411,6 +411,11 @@ 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"`。
+
 ### Gitea Actions PR 门禁

 AGC 分片运行器编译测试二进制时使用 `--message-format=json-render-diagnostics`：stdout 的 JSON artifact 用于定位可执行文件，编译错误与 warning 由 Cargo 渲染到继承的 stderr，CI 必须保留错误编号、源码位置与具体原因。回归验证运行 `node --test apps/ai-game-creator-shell/scripts/run-rust-shell-test-shards.test.mjs`。函数签名变更合并后，还要编译 `cfg(test)` 调用方；普通 `cargo check` 不能替代测试目标检查。