diff --git a/docs/project-memory/shared-memory/development-workflow.md b/docs/project-memory/shared-memory/development-workflow.md index c4e72194e..3be5a39dd 100644 --- a/docs/project-memory/shared-memory/development-workflow.md +++ b/docs/project-memory/shared-memory/development-workflow.md @@ -57,7 +57,7 @@ AGC 生成准备只通过单目录 GET 确认当前账号绑定，不能重新 Windows 下的移动壳 smoke 通过 Node 启动从当前 workspace 包解析出的 Expo/EAS CLI，不直接 `spawnSync('npm.cmd')`；保留原配置与导出断言。具体入口和警告清理边界见本地开发运维文档。 -AGC 的纯桌面/生产接入按模块排除测试编译，共享实现与受测入口保持可测试；拆分后同时检查普通目标和测试目标，并保留原有行为断言。命令注册与退出接线的源码检查跟随真实模块位置更新，不能因移动文件而漏检；不通过全局允许死代码或虚假调用消除告警。具体边界见开发运维文档“编译告警的保留边界与待优化项”。 +AGC 的纯桌面/生产接入按模块排除测试编译，共享实现与受测入口保持可测试；拆分后同时检查普通目标和测试目标，并保留原有行为断言。命令注册与退出接线的源码检查跟随真实模块位置更新，不能因移动文件而漏检；不通过全局允许死代码或虚假调用消除告警。Rust 侧编译 warning 已纳入门禁：workspace 根 `[workspace.lints.rust] warnings = "deny"`，成员 crate 用 `[lints] workspace = true` 继承，被 `exclude` 或自带 manifest 的独立 crate 各自声明 `[lints.rust] warnings = "deny"`；能直接修的一律修掉、不用 `#[allow]` 掩盖，条件编译拆分不作为消警手段；例外清单与关闭条件见开发运维文档「Rust 编译告警门禁」。具体边界见开发运维文档“编译告警的保留边界与待优化项”。 提示词外置变更运行 `runtime_prompt_bundle_build` 与 `prompt_source_boundaries` 两个 Rust 集成测试，验证编译期文本、目录登记和源码边界；现有 `agc-rust-shard-1` 本地/CI 入口先执行这组检查，再运行分片单测。 diff --git a/docs/project-memory/shared-memory/pitfalls.md b/docs/project-memory/shared-memory/pitfalls.md index 0c6d227a4..c05053dcd 100644 --- a/docs/project-memory/shared-memory/pitfalls.md +++ b/docs/project-memory/shared-memory/pitfalls.md @@ -2,6 +2,23 @@ 这里只记录对当前开发仍有用的症状、根因、排查方法和风险边界。同一事实保留一个当前口径；退役对象的专属过程与单轮测试结果由 Git 历史追溯。遇到旧路径或版本时，以现行代码和专题文档为准。 +## 2026-10-06 AGC 壳新工作树缺 gitignored 随包/源码侧产物：`build.rs` 直报“未声明文件”，其实是**源码侧 allowed 集合为空** + +- **现象**：在 git worktree 下的 AGC 壳新工作树直接 `cargo check --features cocos-editor-execute,unity-editor-execute,godot-editor-execute --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml`，`build.rs` 依次失败：先是 `内置 Codex CLI 随包资源校验失败（x86_64-pc-windows-msvc）：随包清单不可读 …/src-tauri/resources/codex/win-x64/manifest.json：…`，接着是 `插件随包资源校验失败：随包插件存在未声明文件：…/resources/plugins/agc-unity-editor/dotnet/publish/win-x64/Agc.Unity.Attach.exe（目标 x86_64-pc-windows-msvc 与当前 feature 组合不允许；请先执行随包资源准备步骤）`。注意第二条**不是** feature 缺失：本次命令已带编辑器 feature，报的还是「未声明」。 +- **原因**：两层。① `resources/` 下多个子目录是 gitignored、由准备步骤产出（`.gitignore:43` `resources/plugins/`、`:59` `resources/claude-agent/`、`:38-42` `resources/codex/win-x64/{manifest.json,bin/,codex-resources/,codex-package.json}`），新工作树里它们不存在（`resources/codex` 目录本身入库，但 win-x64 的内容不入库，所以先撞 codex 清单那条）。② 更要紧的一层：`package_layout::validate_staged_plugins` 的允许集合是**从源码侧枚举**的——`source_subdirectory_files(source_directory)` 在该源码目录不存在时**返回空集**，于是 `dotnet/publish/win-x64` 这条 `origin: prepared` 声明在 allowed 里一个条目都没加，随后 `collect_tree_files(&staged)` 把随包目录下同一路径的全部文件判成「未声明文件」。所以 `plugins/agc-unity-editor/dotnet/publish`（`.gitignore:55`）也是**必须存在**的源码侧 gitignored 构建产物，`build.rs` 的只读校验才拿得到 allowed 集合（`build.rs` 的 `validate_staged_resources` → `validate_staged_plugin_workspace` → `package_layout::validate_staged_plugins`；校验顺序是 codex bundle → Claude Agent sidecar → plugins → prepared payloads，所以新工作树最先看到 codex 那条）。 +- **处理（现行最小做法）**：从已有「准备过」的检出里直接拷这几坨，比重跑随包资源准备步骤快： + + ```bash + cp -r /apps/ai-game-creator-shell/src-tauri/resources/{codex,claude-agent,plugins} \ + apps/ai-game-creator-shell/src-tauri/resources/ + cp -r /plugins/agc-unity-editor/dotnet/publish plugins/agc-unity-editor/dotnet/ + cp -r /plugins/agc-godot-editor/native/gdextension/bin plugins/agc-godot-editor/native/gdextension/ + ``` + + 其中 godot 那行按实测需要保留，成因待核实：`build.rs` 校验链里 `libraryStaging` 的 allowed 来自声明里的 `files`（`bin/win-x64/agc_godot_editor.dll` 等四项）而非源码侧枚举，`godot_bundle::validate(root)` 也只读随包目录，源码侧该路径的现役消费方是 `src/editor_adapters/startup.rs` 的运行期相对路径常量与 godot bridge 用例。同时记住 AGC 壳 `[features] default = []`：任何检查命令都必须显式带 `--features cocos-editor-execute,unity-editor-execute,godot-editor-execute`，否则随包资源校验会按 featureless 组合把编辑器产物判成「未声明文件」（见本文件 2026-10-03 那条）。 +- **验证**：上述拷贝后 `cargo check --features cocos-editor-execute,unity-editor-execute,godot-editor-execute --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml` 能进入正常编译（不再 panic 在 `build.rs`）；`npm run agc:bundled-resources:check`（`apps/ai-game-creator-shell/scripts/check-package-layout.mjs`）通过。反向判据：删掉 `plugins/agc-unity-editor/dotnet/publish` 再跑一次，必然复现「未声明文件 …Agc.Unity.Attach.exe」，可用来确认这条链的因果。 +- **关联**：`apps/ai-game-creator-shell/src-tauri/build.rs`（`validate_staged_resources` / `validate_staged_plugin_workspace` / `validate_prepared_payloads`）、`src-tauri/build_support/package_layout.rs`（`validate_staged_plugins`、`source_subdirectory_files`、`subdirectory_enabled`）、`src-tauri/build_support/package-layout.json`（`plugins.subdirectories` / `plugins.libraryStaging` / `plugins.prepareSteps`）、`src-tauri/Cargo.toml` 的 `[features]`；另见本文件「AGC 随包 plugins 的 feature 档位必须与消费方一致，且门禁会因 build.rs 未重跑而假通过」「随包资源的写入方按产物来源分界」「AGC 随包资源的布局只能改声明文件，生成物由门禁锁死」三条。 + ## 2026-10-05 PR #607 复核修复：档位点对齐/对比度、状态文案也走浮层、键盘去重、卸载 flush - **档位圆点已删除（D1 的收口）**：这一轮把档位圆点**整体删除**（半透明备选方案未采用）。现在滑块只剩轨道 + 圆钮：轨道 6px 圆头、已选段 `--platform-accent` 由 `--strength-ratio` 驱动、**终点落在圆钮中心**（`calc(10px + ratio * (100% - 20px))`）、圆钮 20px 实心暖白（`--platform-panel-fill` + `--platform-subpanel-border` 1px 描边 + `color-mix` 柔影）；强度区横向内边距 `4px 6px 2px` → `4px 0 2px`（滑块铺满卡片内容宽度，填充段与圆钮两端与轨道两端贴齐）；相关 CSS（`space-between` 排布 / `z-index: 2` 抬层 / `.is-active{opacity:0}` / 点的 `color-mix` 底色 / 只为点对齐的 `padding: 0 7px`）与渲染标记一并删除。**判据**：`chatDialogFrameLayout.test.ts` 反向守卫（样式表里不再有 `.project-chat-composer-strength-stops` 规则、组件源码不再渲染该类名；滑块契约仍在：宽 100% / 高 26 / 圆钮 20×20、强度区左右内边距 0）+ `home.suite.ts` 首页菜单里查不到那组点。实测（447 视口，像素扫描）：轨道 90..324（宽 234 = 卡片内容宽），档位 0 时圆钮左缘 90.5（距轨道左端 0.5px）、档位 4 时圆钮右缘 322.3（距右端 1.8px，扫描行不在圆钮正中所以略窄），填充段终点落在**圆钮中心**（`calc(10px + ratio * (100% - 20px))`，被圆钮盖住），因此圆钮右侧不会露出橙色（终点曾写成 `20px + …` = 圆钮右缘，4× 设备像素下能看到一小截溢出）。**历史成因（只留一句，细节由 Git 追溯）**：圆点此前被 6px 轨道盖住、且与圆钮两端错位 ±12.2px，曾用「抬到轨道之上 + space-between 对齐 + 浅暖色」修过一轮，最终整体删除。 diff --git a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md index b2450a6b5..958a6efce 100644 --- a/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md +++ b/docs/technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md @@ -81,7 +81,7 @@ UI 编辑器的“分析参考图”步骤、Rust 命令 `suggest_ui_design_sema ## OAuth 认证路线的契约冲突与待决边界 -**状态（2026-09-23）：明确暂缓，待决定 AGC 是否支持使用用户 Codex OAuth 登录态。** AuthBridge 认证桥尚未接通正式入口；既不能认定为现役已支持能力，也不能仅因生产无构造点而宣布整条链退役。 +**状态（2026-10-06）：已决策——AGC 不支持用户 Codex OAuth 登录态，认证统一走我们的中转站（平台代理 / 显式自定义 Key）。** 因此 AuthBridge 认证桥按「不支持」路线整体退役：删除 reader / variant、OAuth 专属目录分支、轮换链及专属测试，并撤销本方案中相关承诺；平台代理路由、共享模型目录与隔离运行环境保留。 ### 冲突事实与证据 @@ -90,18 +90,20 @@ UI 编辑器的“分析参考图”步骤、Rust 命令 `suggest_ui_design_sema - **时间顺序**：正式凭据 fallback 被限定测试的记录见 `2e15289264`（2026-09-02）；9 月 21 日提交新增下游 OAuth 处理，却仍保留该测试限定入口。因此不能简单把 OAuth 承诺当作早于现役路线的过期说明。 - **验证边界**：OAuth 目录测试使用真实 Codex 配合模拟认证和本地服务，轮换测试验证私有缓存及身份隔离；这些不能证明正式客户端已接通真实用户 OAuth 登录。每回合模型目录捕获也服务现役平台代理，不能随 OAuth 专属链整体删除。 -### 暂缓期间的处理 +### 执行动作（2026-10-06 起） -保留认证桥相关 warning、现有实现及待决记录，不新增 `allow`，不为清零把整条业务链继续移入 `cfg(test)`，不擅自接通用户登录态读取，也不把现状记录为“已支持 OAuth”。该待决项与其它已完成的 warning 清理独立，不阻止其它改动提交。 +- 决策：**不支持用户 Codex OAuth 登录态，统一走我们的中转站**（决策日期 2026-10-06）。 +- 执行：删除 AuthBridge reader / variant、OAuth 专属目录分支、轮换链及专属测试，并同步撤销相关文档承诺；每回合模型目录捕获等同时服务现役平台代理的部分保留，不能随 OAuth 专属链整条删除。 +- 保留：中转站（平台代理 / 显式自定义 Key）路由、共享模型目录、隔离运行环境不随之改动。 +- 不再保留认证桥相关 warning 与实现：链路删除后 3 条 AuthBridge warning 随之归零，门禁清单里唯一的实现层例外关闭（见[本地开发验证与生产运维](../【开发运维】本地开发验证与生产运维-2026-05-15.md#rust-编译告警门禁)）。 -### 下一决策点与关闭条件 +### 关闭条件与保留项 -| 决策 | 关闭条件 | +| 已选路线（2026-10-06） | 关闭条件 | | --- | --- | -| 不支持用户 Codex OAuth 登录态 | 同步撤销相关文档承诺，删除 AuthBridge reader / variant、OAuth 专属目录分支、轮换链及专属测试；保留现役平台 / 自定义 Key 路由、共享模型目录和隔离运行环境，完成定向验证。 | -| 支持用户 Codex OAuth 登录态 | 先明确入口、授权与凭据隔离合同，再接通正式构造路径；验证真实登录、模型目录来源、轮换续传、身份切换与错误恢复，不能仅凭模拟测试或取消编译告警关闭。 | +| 不支持用户 Codex OAuth 登录态，统一走中转站 | 删除 AuthBridge reader / variant、OAuth 专属目录分支、轮换链及专属测试，撤销相关文档承诺，并完成带编辑器 feature 的 AGC 壳定向验证；保留中转站（平台代理 / 自定义 Key）路由、共享模型目录和隔离运行环境。落地后本节的 3 条 AuthBridge warning 归零，该待决项关闭。 | -当前尚未选择上述任一路线。本节是该冲突的维护位置，不依赖临时编译警告清单；决定后在此更新为最终合同，决策历史由 Git 保留。记录冲突本身不构成功能接入或退役决定。 +本节是该决策的维护位置，不依赖临时编译警告清单。后续若要重启用户 Codex OAuth 登录态，必须先把「支持」路线重新立项：明确入口、授权与凭据隔离合同，并验证真实登录、模型目录来源、轮换续传、身份切换与错误恢复，不能仅凭模拟测试或取消编译告警恢复该链路。决策历史由 Git 保留。 ## 2026-09-23 Direct 宿主继续请求输入修复 @@ -253,7 +255,7 @@ UI 编辑器的“分析参考图”步骤、Rust 命令 `suggest_ui_design_sema ### SDK 串行工具的等价接入 -> OAuth 状态（2026-09-23）：下列 OAuth 目录与凭据轮换要求已有下游实现和测试，但正式凭据入口尚未接通 AuthBridge。是否支持用户 Codex OAuth 登录态仍待决，详见本方案的[契约冲突与待决边界](#oauth-认证路线的契约冲突与待决边界)。平台代理使用的共享模型目录能力继续有效。 +> OAuth 状态（2026-10-06）：**已决策不支持用户 Codex OAuth 登录态，认证统一走我们的中转站**。下列 OAuth 目录与凭据轮换要求按该决策退役（删除 AuthBridge reader / variant、OAuth 专属目录分支、轮换链及专属测试），详见本方案的[契约冲突与待决边界](#oauth-认证路线的契约冲突与待决边界)。平台代理使用的共享模型目录能力继续有效。 - DirectProject 对外保留完整补丁和计划能力，由宿主 MCP 提供 `agc_apply_patch` 与 `agc_update_plan`。精确关闭 SDK 的旧计划工具注册；缺少合法回包通道的原生问答工具不再声明可用，需要用户信息时使用现有聊天。 - 通过同一可信捆绑 Codex 和身份/路由隔离的 HOME 取得完整模型目录，只置空 `apply_patch_tool_type` 以移除 SDK 全局串行补丁处理器。不得修改模型名称或其它 metadata，不为未知模型伪造显式条目；匹配和 fallback 仍由 SDK 执行。 diff --git a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md index ab4f9d5ce..d7913ebb4 100644 --- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md +++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md @@ -345,12 +345,12 @@ 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、删除业务校验或提高包体积阈值代替修复。 +编译警告的局部清理保持运行行为与验证断言不变：先在当前提交复现，再移除冗余导入、可变绑定及被无条件覆盖的赋值；仅测试或平台分支需要的导入按实际使用边界编译，兼容重导出和涉及锁、权限、持久化的参数单独核查。独立前端 build 可以直接执行本包已有的 TSC/Vite，避免嵌套 npm 传递配置警告；移动壳 smoke 使用 Node 直接启动本包解析出的已安装 Expo/EAS CLI，兼容 Windows，并保留原配置与导出断言。验收使用原构建入口及受影响的测试目标编译，不以全局屏蔽 warning、删除业务校验或提高包体积阈值代替修复。Rust 侧 first-party 编译 warning 自本批起纳入门禁：能直接修的一律修掉，不用 `#[allow]` 掩盖；与既有口径冲突的优先修订口径（同批同步改文档），确实不能修的逐条登记原因与关闭条件。门禁落法与实测基线见本节「Rust 编译告警门禁」。 ### 编译告警的保留边界与待优化项 - 设计会话的水合、重置和调试快进通过共享核心验证损坏会话隔离、不确定批次恢复和事件失败后的落盘状态；仅 Tauri 包装限定生产编译，资源与模型客户端仍在原校验阶段之后按需加载。旧 UI 绑定、合并及语义建议命令已随现役 UI 工作流替换而删除；分离恢复测试验证已完成的绑定和图片不被重新生成，不代表首次生成全链路已覆盖。音频派发测试验证使用派发时的 revision、保留提交身份，并在远程上下文失败时保持 Prepared 账本及项目内容不变。 -- AGC 纯生产接入按模块限定 `cfg(not(test))`：桌面启动、Tauri 命令注册和没有测试消费者的命令接入集中到对应生产模块；共享业务实现、被测试直接调用的入口和现有断言仍参与测试编译。拆分不改变命令名、注册集合、权限校验或启动/退出顺序，也不新增 `allow(dead_code)`、虚假引用或仅为消警的测试。每批同时检查 AGC 普通目标和测试目标，源码结构检查跟随真实接线位置更新；不能用测试目标通过代替生产目标检查，也不以清零告警为由排除已有测试覆盖。 +- AGC 纯生产接入按模块限定 `cfg(not(test))`：桌面启动、Tauri 命令注册和没有测试消费者的命令接入集中到对应生产模块；共享业务实现、被测试直接调用的入口和现有断言仍参与测试编译。拆分不改变命令名、注册集合、权限校验或启动/退出顺序，不新增 `#[allow(dead_code)]`、不制造假引用、不为消警删除测试；`#[allow]` 仅在确无本地修法且有明确关闭条件时，经登记后以最窄范围使用（挂在具体项上、带理由注释，不得模块级 `#![allow]`）。每批同时检查 AGC 普通目标和测试目标，源码结构检查跟随真实接线位置更新；不能用测试目标通过代替生产目标检查，也不以清零告警为由排除已有测试覆盖。拆分只用于把「仅生产入口」移出测试构建，不作为消除告警的手段：仅测试或平台分支需要的导入按真实使用边界条件编译，失去调用方的测试 helper 与多余重导出直接删除，能直接修掉的一律直接修。 - 插件/客户端扩展、模板库和预览的桌面命令与所属模块的共享实现分离：插件进程及权限逻辑、扩展仓库、模板访问授权/归档校验/建项、预览注册表与生命周期继续由原测试验证。模板命令和普通建项命令共用的 AppData 根目录选择接入随生产模块编译，用户所选目录的安全校验仍保留在共享实现中。 - 编辑器适配器注册、随包资源定位和平台会话 fixture 加载属于桌面/Runner 启动接入，按生产模块编译；fixture 的发行版拒绝、路径边界、文件大小及凭据校验不得随拆分改变。配置 setup、Windows 提权 helper 的票据消费和 Runner bootId 初始化随其生产调用方限定范围，配置迁移、ACL 安全规则、平台身份/凭据轮换、编辑器执行回执及进程归属的已有测试继续编译。 - 项目快照的周期调度、窗口事件、退出等待和桌面命令与共享同步核心分离；Analytics 的服务初始化、窗口/退出事件、上传定时启动和启动时补投同样属于生产接入。窗口登记状态机、快照索引与同步事务、埋点状态机、上传轮次和补投资格处理继续参与测试，不能用移除这些测试的方式消除告警。 @@ -358,14 +358,53 @@ npm run check - MCP 的 STDIO 启动和 Tauri 命令包装限定生产编译；loopback 启停、服务注册表、析构与工具桥启动属于 Claude Direct 的共享依赖，必须参与测试编译。认证链路调用的 `validate_platform_session_input`、线程队列使用的 `DirectGameCreatorTurnUpdateEmitter::new` 同样保留在测试编译中；Direct/设计工具及 UI 编辑器的纯命令包装随桌面入口编译。Thread Manager 的订阅/消费同时服务 Unix 集成测试与跨平台取消回合回归，不限定为生产或 Unix。项目资源的生产命令 DTO 与读取接入按实际消费者限定范围；分类更新测试从正式 camelCase 请求解码后验证同一身份与 revision 的写入，音频提交测试核对派发 operationId 与账本任务一致、幂等键不被替换。业务编排、网络鉴权和持久化安全逻辑不能仅因没有直接测试而整段排除。 - Direct 取消入口必须验证错轮请求不取消、不释放、不发送终态；执行器退出后的残留守卫释放须返回原 clientTurnId，并发布对应 canonical userItemId 的 aborted 终态。旧守卫析构不能清掉随后启动的新回合。此类安全行为通过真实入口回归保留在测试构建，不以条件编译排除取消链。 - 预览测试使用系统临时目录，不依赖 Windows 未必提供的 `HOME`。Cocos 插件 RPC 往返测试在注册完成后，通过只读状态查询确认插件已接收启动时的项目上下文，再执行原有隐式项目路径断言；Unity 跨项目测试先等待项目事件订阅，再切换项目。不能把注册完成等同于项目订阅快照已到达，也不能重试写操作掩盖初始化竞态。 -- AGC 测试编译使用 `cargo check --locked --offline --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -p genarrative-ai-game-creator-shell --tests` 定向核对。GUI 主入口在测试构建中被排除，不能把测试目标的 `dead_code` 一律认定为废弃生产代码；仅生产入口使用的导入限定 `not(test)`，平台测试导入与对应 Unix/Linux 测试保持相同条件，失去调用方的测试 helper 和多余重导出直接删除。DirectHome 命令配置测试明确断言禁用 `shell_tool` 与 `unified_exec`；Windows 路径校验的测试分支不触发宿主提权修复，修复范围参数仅由生产分支消费。 +- AGC 测试编译必须带编辑器 feature 定向核对（AGC 壳 `[features] default = []`，不带 feature 时 `build.rs` 的随包资源校验会 panic）：`cargo check --locked --offline --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -p genarrative-ai-game-creator-shell --tests --features cocos-editor-execute,unity-editor-execute,godot-editor-execute`。GUI 主入口在测试构建中被排除，不能把测试目标的 `dead_code` 一律认定为废弃生产代码；仅生产入口使用的导入限定 `not(test)`，平台测试导入与对应 Unix/Linux 测试保持相同条件，失去调用方的测试 helper 和多余重导出直接删除。DirectHome 命令配置测试明确断言禁用 `shell_tool` 与 `unified_exec`；Windows 路径校验的测试分支不触发宿主提权修复，修复范围参数仅由生产分支消费。 - 测试 helper 的条件要覆盖真实使用范围：Unity delivery 观测 helper 限于 Windows x86_64 的 `unity-editor-execute` 测试，Agent DB 链接安全断言与 app-server 工作区启动包装限于 Unix 测试，模板假数据的环境变量读取限于 `template-library-fixtures` feature。底层生产实现与共享测试逻辑继续保留。仅检查完成阻塞协议固定中文措辞、且失去测试标记的遗留函数直接删除；现役自由执行请求使用短任务协议，不向其测试搬入标准模式的完成阻塞提示词要求，标准模式的生产协议保持不变。 -- AGC 默认 Windows dev 构建在 2026-09-23 清理后的 `cargo check --locked --offline --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -p genarrative-ai-game-creator-shell` 复核通过，剩余 3 条 AuthBridge 相关 Rust warning 和 5 条 ts-rs 提示。这是当次配置的检查结果，不代表后续提交、正式 editor features、其它平台、test targets、release 链接或安装包均无告警；后续按改动范围定向验证。 -- AuthBridge 的 3 条 warning 暂缓处理，支持或退役 OAuth 的决策仍未确定。完整证据、保留边界和关闭条件以 [AGC 主方案“OAuth 认证路线的契约冲突与待决边界”](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#oauth-认证路线的契约冲突与待决边界)为准。 -- ts-rs 12.0.1 的 5 条提示来自四个枚举（`DirectCodexUserItem`、`DirectCodexUserContentPart`、`DirectThreadItem`、`DirectThreadEvent`）的 `serde(deny_unknown_fields)` 和图片组件的 `serde(deserialize_with = "deserialize_fill_amount")`。已静态核对 TypeScript 类型形状及基础类型正确、Serde 运行时校验仍有效；暂保留提示，不引入依赖补丁、不改业务校验或全局屏蔽，待上游正式版本支持后再评估。 -- AGC 前端仍有超过 Vite 默认 `500 kB` 阈值的 chunk 体积提示；主包按页面/面板拆分与 three 体积取舍尚未完成。three 及其 loader 已按需加载，不能重复以“改成动态 import”作为修复；优化须验证首屏、页面切换、面板首次打开及加载失败表现，不以提高阈值代替优化。 +- AGC 默认 Windows dev 构建的复核使用带编辑器 feature 的命令（AGC 壳 `[features] default = []`，不带 feature 时 `build.rs` 的随包资源校验会因「随包插件存在未声明文件」panic）：`cargo check --locked --offline --manifest-path apps/ai-game-creator-shell/src-tauri/Cargo.toml -p genarrative-ai-game-creator-shell --features cocos-editor-execute,unity-editor-execute,godot-editor-execute`。2026-09-23 当次复核剩余 3 条 AuthBridge 相关 Rust warning 和 5 条 ts-rs 提示，这是当次配置的检查结果快照，不代表后续提交、其它平台、test targets、release 链接或安装包均无告警；当前实测基线见本节「Rust 编译告警门禁」。 +- AuthBridge 的 3 条 warning 属**已决策**项：2026-10-06 决定**不支持用户 Codex OAuth 登录态**，统一走我们的中转站，因此按 [AGC 主方案「OAuth 认证路线的契约冲突与待决边界」](./technical/【技术方案】AI游戏创作智能体App实施计划-2026-06-24.md#oauth-认证路线的契约冲突与待决边界) 决策表第一行执行——删除 AuthBridge reader / variant、OAuth 专属目录分支、轮换链及专属测试，并撤销相关文档承诺；保留中转站（平台代理 / 自定义 Key）路由、共享模型目录与隔离运行环境。链路删除后这 3 条 warning 随之归零，门禁清单里唯一的实现层例外关闭，本条在清理落地后即删除。 +- ts-rs 12.0.1 的 5 条提示属**待上游**项：来自四个枚举（`DirectCodexUserItem`、`DirectCodexUserContentPart`、`DirectThreadItem`、`DirectThreadEvent`）的 `serde(deny_unknown_fields)` 和图片组件的 `serde(deserialize_with = "deserialize_fill_amount")`；已静态核对 TypeScript 类型形状及基础类型正确、Serde 运行时校验仍有效。关闭条件：升级到包含该提示修复的 ts-rs 正式版本后重新复核这 5 条消失（升级只动依赖版本与生成绑定，不改业务校验）。期间不引入依赖补丁、不改业务校验、不做全局屏蔽。 +- AGC 前端超过 Vite 默认 `500 kB` 阈值的 chunk 体积提示属**待优化**项，不是 Rust 编译告警门禁的对象（门禁只覆盖 first-party Rust 编译 warning；`scripts/build-gate.mjs` 的 Vite warning-as-error 只作用于主站与后台）。关闭条件：主包按页面/面板拆分完成，且首屏、页面切换、面板首次打开与加载失败表现四项均已验证。three 及其 loader 保持按需加载，不能重复以“改成动态 import”作为修复，也不以提高 `chunkSizeWarningLimit` 代替优化。 - 嵌套 npm 的 `Unknown env config "global-ignore-file"` 属于工具链配置提示。已复现 npm 12 向脚本导出有效配置，而子进程切换到不认识该配置的 npm 11 后报错；应核对父子进程实际 npm 入口并统一版本，项目声明及 CI 使用的版本以 `package.json` 与当前 CI 配置为准。不要据此删除 npm 12 的有效配置，也不要把减少一层 npm 调用视为已统一本机工具链。 +### Rust 编译告警门禁 + +- 口径：全仓 Rust **first-party** 编译 warning 清零，能直接修的一律修掉，不用 `#[allow]` 掩盖；与既有文档口径冲突的优先修订口径（同批同步改文档）；确实不能修的逐条登记原因与关闭条件。仍然禁止：新增 `#[allow(dead_code)]`、假引用、仅为消警删除测试；生成代码不手改（要改就改生成器）。 +- 落法：workspace 根写 `[workspace.lints.rust] warnings = "deny"`，成员 crate 用 `[lints] workspace = true` 继承；被 `exclude` 或自带 manifest 的独立 crate 各自声明 `[lints.rust] warnings = "deny"`。 +- 依据：cargo 只对**目标 crate** 传 `--deny=warnings`，**不改 `RUSTFLAGS`**，因此不会让 CI 的 Rust 编译缓存整体失效（已用一个最小 crate 实证）。缓存边界见本节「Rust 测试组的隔离编译缓存」。 +- 覆盖范围：`server-rs` workspace（成员见 `server-rs/Cargo.toml` 的 `members`）、4 个被 `exclude` 的独立 crate（`agent-runtime-core`、`agent-runtime-orchestration`、`editor-adapter-api`、`platform-agent`）、`apps/desktop-shell/src-tauri`、三个编辑器 native bridge；AGC 壳（`apps/ai-game-creator-shell/src-tauri`）**批次清理中**（起始基线 613 条），清零后才启用 `[lints] warnings = "deny"`。 +- 实测基线（2026-10-06，Windows msvc / rustc 1.98.1，全新 target 目录；AGC 壳数字为清理前起始基线）： + +| 目标 | warning | +| --- | --- | +| `server-rs` workspace（`--all-targets`） | 1 → 0 | +| AGC 壳（编辑器 feature，bin 目标） | 613（`dead_code` 588 / `unused_imports` 22 / `unused_variables` 2 / `dropping_copy_types` 1），批次清理中 | +| AGC 壳同 feature + `--all-targets` | 1214 事件 / 1034 唯一，批次清理中 | +| `desktop-shell`、三个 bridge、4 个被 `exclude` 的独立 crate | 0 | + +- 检查命令（AGC 壳必须带编辑器 feature，否则 `build.rs` 的随包资源校验会 panic）： + +```bash +# server-rs workspace +cargo check --workspace --all-targets --manifest-path server-rs/Cargo.toml + +# 4 个被 exclude 的独立 crate +cargo check --all-targets --manifest-path server-rs/crates/agent-runtime-core/Cargo.toml +cargo check --all-targets --manifest-path server-rs/crates/agent-runtime-orchestration/Cargo.toml +cargo check --all-targets --manifest-path server-rs/crates/editor-adapter-api/Cargo.toml +cargo check --all-targets --manifest-path server-rs/crates/platform-agent/Cargo.toml + +# desktop-shell +cargo check --all-targets --manifest-path apps/desktop-shell/src-tauri/Cargo.toml + +# 三个编辑器 native bridge +cargo check --all-targets --manifest-path plugins/agc-cocos-editor/native/cocos-editor-bridge/Cargo.toml +cargo check --all-targets --manifest-path plugins/agc-unity-editor/native/unity-editor-bridge/Cargo.toml +cargo check --all-targets --manifest-path plugins/agc-godot-editor/native/godot-editor-bridge/Cargo.toml + +# AGC 壳（编辑器 feature 口径；批次清理中） +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 +``` + ### 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` 不能替代测试目标检查。