清理低风险编译警告并修复构建检查脚本

清理冗余导入、可变绑定和赋值，将 AGC 默认编译警告从 231 条降至 195 条按测试和平台边界限定导入，保留兼容出口与待核查的业务参数修复预览部署器嵌套 npm 警告和移动端检查脚本的 Windows 启动错误更新警告清单、开发运维文档与共享开发流程，记录验证结果和剩余项
2026-09-23 10:58:19 +00:00
parent 07feed7511
commit 018697203f
31 changed files with 115 additions and 60 deletions
@@ -53,6 +53,8 @@

 ## 验证路由

+Windows 下的移动壳 smoke 通过 Node 启动从当前 workspace 包解析出的 Expo/EAS CLI，不直接 `spawnSync('npm.cmd')`；保留原配置与导出断言。具体入口和警告清理边界见本地开发运维文档。
+
 提示词外置变更运行 `runtime_prompt_bundle_build` 与 `prompt_source_boundaries` 两个 Rust 集成测试，验证编译期文本、目录登记和源码边界；现有 `agc-rust-shard-1` 本地/CI 入口先执行这组检查，再运行分片单测。

 提示词测试验证实际请求中的片段来源、动态参数和工具结构；措辞不作为逐字契约。已有行为测试覆盖的限制不再另设整段文案检查。Direct 回合测试复用生产的消息转换和文件投影函数，不维护仅供测试调用的回合编排副本。
@@ -7,7 +7,7 @@

 ## 1. 基线与范围

-本次仅检查和讨论，尚未实施警告清理。基线提交为 `016356e509f11a1a638ce45ed51b9e40ef3e36a2`，诊断时工作树干净。环境为 Windows x64、Rust `1.98.1`、Node `v24.15.0`、npm `12.0.2`。
+首次诊断的基线提交为 `016356e509f11a1a638ce45ed51b9e40ef3e36a2`，诊断时工作树干净。环境为 Windows x64、Rust `1.98.1`、Node `v24.15.0`、npm `12.0.2`。第 2～6 节和附录保留首次诊断快照；后续处理状态以第 7 节为准，不能将附录的全部条目视为仍未解决。

 AGC Rust 使用默认 features、dev profile；237 是本轮编译器诊断数，不代表 237 个独立根因，也不是所有平台、features 和 test targets 的总数。另有 5 条不带常规源码 span 的 ts-rs 宏提示，不计入 237。

@@ -104,8 +104,47 @@ three、FBX/GLTF loader、OrbitControls 已动态 import。不能把“改为动

 ## 7. 待办与关闭条件

- [ ] 第一批：核对并清理低风险导入、mut、注释、变量和赋值；修复预览部署器嵌套 npm 及移动 smoke 的 Windows 调用。
- [ ] 第二批：对 165 条 dead_code 核对测试、正式 features、平台及退役合同，逐项确定保留、条件编译或删除；涉及退役范围扩大时先补方案。
+### 2026-09-23 首批低风险清理
+
+清理前分支已合入上游，实际代码基线为 `07feed751`。重新运行默认 Windows dev 配置的 AGC `cargo check`，修复前为 **231 条**，修复后为 **195 条**，本次减少 **36 条**；首次记录的 237 与本轮修复前的 231 之间的差异来自上游合并，不计作本次修复。
+
+| 诊断类型 | 本轮修复前 | 本轮修复后 |
+| --- | ---: | ---: |
+| `dead_code` | 158 | 158 |
+| `unused_imports` | 45 | 27 |
+| `unused_variables` | 13 | 9 |
+| `unused_mut` | 11 | 0 |
+| `unused_assignments` | 3 | 1 |
+| `unused_doc_comments` | 1 | 0 |
+| **合计** | **231** | **195** |
+
+已完成的局部修改：
+
+- 清理普通未用导入，将测试和 Linux/Unix 分支专用导入限定在对应编译条件；未删除兼容重导出、业务实现或新增 allow。
+- 清理 11 处 mut、局部语句前的文档注释、两个必然被覆盖的赋值；去除远程导入中间元组的冗余 asset ID，保留原始稳定身份校验及路径计算。
+- HTML 导出仍校验设计图存在，只去除未读取的绑定；目录同步保留 Unix 行为，非 Unix 分支显式忽略参数。
+- 预览部署器 build 直接调用 TSC/Vite，原 npm 配置 warning 已消除。
+- 移动壳三个 smoke 通过包解析得到已安装 Expo/EAS 的 CLI 入口，再由当前 Node 启动；原 Windows EINVAL 已消除，配置、EAS 配置和 Android/iOS 导出 smoke 均通过，原断言与清理范围不变。
+
+对应首次清单已处理的编号为 W166、W167、W170～W174、W197、W198、W200、W202～W209、W217、W218、W220、W222～W233、W235～W237。合并后的新增导入 warning 是 `runtime_driver.rs` 中的 `start_game_creator_agent_background_task_for_session_at` 重导出，本轮按兼容边界保留。
+
+保留项包括：兼容 facade、涉及身份/锁/完成门禁的未使用参数、Direct 重试回合的 response 初始化、全部 dead_code，以及 5 条 ts-rs 提示和 AGC chunk 体积告警。这些项需要语义或合同核查，不能仅改名或屏蔽。
+
+验证通过：
+
+- AGC 默认 `cargo check --locked --offline` 及同一 package 的 `cargo check --locked --offline --tests`；均使用第 2 节的 manifest/package 参数。后者证明测试目标可编译，不代表已执行 Rust 单元测试，195 条仅统计普通 dev 构建。
+- `npm run preview-deployer:web:build`，无原 npm 配置 warning。
+- `npm run config:smoke -w @genarrative/mobile-shell`、`npm run build-config:smoke -w @genarrative/mobile-shell`、`npm run export:smoke -w @genarrative/mobile-shell`（Android/iOS）。
+- 修改 Rust 文件的 `rustfmt --check --edition 2021 --config skip_children=true`、三个移动脚本的 ESLint、脚本及预览 package 的 Prettier。
+- `npm run check:encoding`、`npm run check:doc-index`、`git diff --check`。
+
+未执行 Rust 单元/运行时测试、正式 editor features、Linux/macOS 原生编译或安装包。独立只读审查未发现这批局部修改的行为回归；仍需其他平台实际编译才能补齐平台验证。
+
+### 剩余工作
+
+- [x] 第一批：清理确认不改变行为的低风险项，修复预览部署器嵌套 npm 及移动 smoke 的 Windows 调用。
+- [ ] 单独核查保留的兼容重导出、身份/锁/门禁参数及 Direct 重试回合初始化，确认合同后再修改。
+- [ ] 第二批：对当前 158 条 dead_code（首次快照为 165 条）核对测试、正式 features、平台及退役合同，逐项确定保留、条件编译或删除；涉及退役范围扩大时先补方案。
 - [ ] 第三批：核实 5 条 ts-rs 提示的源类型及 TS 输出，保留现有反序列化约束。
 - [ ] 第四批：评估 AGC 主包拆分；为无法合理拆分且已有按需加载的依赖明确体积取舍。
 - [ ] 补充相关正式 features / 平台 / test targets 验证后更新剩余项，不用当前默认配置代表全部构建。
@@ -285,6 +285,8 @@ npm run check

 `npm run build` 由 `scripts/build-gate.mjs` 串行构建主站和后台；该门禁会把 Vite warning 当成失败处理。若看到 `Build gate failed because warnings were emitted`，先看 warning 原文，例如 chunk 体积超过 `vite.config.ts` / `apps/admin-web/vite.config.ts` 的 `chunkSizeWarningLimit`，不要先按 Rust 编译失败排查。

+编译警告的局部清理保持运行行为与验证断言不变：先在当前提交复现，再移除冗余导入、可变绑定及被无条件覆盖的赋值；仅测试或平台分支需要的导入按实际使用边界编译，兼容重导出和涉及锁、权限、持久化的参数单独核查。独立前端 build 可以直接执行本包已有的 TSC/Vite，避免嵌套 npm 传递配置警告；移动壳 smoke 使用 Node 直接启动本包解析出的已安装 Expo/EAS CLI，兼容 Windows，并保留原配置与导出断言。验收使用原构建入口及受影响的测试目标编译，不以全局屏蔽 warning、删除业务校验或提高包体积阈值代替修复。
+
 ### Gitea Actions PR 门禁

 Linux process-session 的 owner SIGKILL 用例必须在启动 owner 后立即建立测试清理 guard：正常退出或断言 panic 时终止、回收 owner，并在有界时间内清理其独立临时项目目录中的残留进程。原有「owner 退出后子进程自行消失」断言在兜底清理之前执行，不能由 guard 代替生产生命周期验证。清理覆盖 panic 路径及临时项目间隔离，且不得因清理失败再次 panic。