修复 AGC NSIS 安装钩子在模板常量与插件目录之前编译导致的出包失败

- installer-hooks.nsh 顶层收敛为 !define / Var / !macro：迁移逻辑改成 !macro AgcMigrateLegacyIdentity，由 !macro NSIS_HOOK_POSTINSTALL 在模板插入点（Section Install，addplugindir 之后）展开，避免 include 时 INSTALLMODE 未定义走错分支、nsis_tauri_utils 插件目录还没 add 导致 makensis 报 Plugin not found 中断 - 旧展示名改走运行期变量 $AgcLegacyIdentity（替换 Push/Pop + Function），去掉 section 上下文里不可用的 Return 提前返回，清理与补建语义保持不变 - 文件头补编译期位置纪律：模板在 installer.nsi 第 28 行 include 本文件，早于 !define INSTALLMODE / MAINBINARYNAME 与 !addplugindir，顶层只能放声明 - build-release.test.mjs 新增守卫用例：顶层不得出现 Function、插件调用、模板常量引用或裸可执行语句（对修复前形态命中 36 条，含第 68 行顶层插件调用） - pitfalls 与 decision-log 记录该踩坑、根因、本机逐字复现与处理口径 - AGC 渠道安装身份隔离里程碑补 2026-09-29 钩子编译位置修正小节与本机探针取证
2026-09-29 17:59:36 +08:00
parent 4a0f18e8a2
commit 30a190d183
5 changed files with 159 additions and 47 deletions
@@ -1,5 +1,15 @@
 # 决策记录

+## 2026-09-29 安装钩子的可执行逻辑只允许待在 !macro 里
+
+- 背景：dev 渠道改名迁移钩子的第一版把迁移写成顶层 `Function`，并在函数体里调 `nsis_tauri_utils::KillProcess`；Jenkins 打 Windows 包时 makensis 在 `installer-hooks.nsh` 第 68 行报 `Plugin not found` 并中断（模板第 28 行 include 钩子，早于模板常量与 `!addplugindir`）。
+- 决策（形态）：`installer-hooks.nsh` 顶层只允许 `!define` / `Var` / `!macro`；所有可执行逻辑写进宏体，靠模板的 `!insertmacro NSIS_HOOK_*`（Section Install，插件目录已 add、模板常量已 define）展开求值；`${INSTALLMODE}` 这类模板常量只在宏体内引用。
+- 决策（传参）：旧展示名改用运行期变量 `$AgcLegacyIdentity` 传入，不再用 `Push`/`Pop` + `Function`——宏体在 section 上下文展开，既拿不到 include 期还不存在的模板常量，也不能用 `Return` 提前返回。
+- 决策（守卫）：把「顶层形态」写成用例（`build-release.test.mjs`：顶层不得出现 Function、插件调用、模板常量引用或裸可执行语句），让同形态回归在单测阶段就红，而不是等到构建机上的 makensis 中断。
+- 影响范围：`apps/ai-game-creator-shell/src-tauri/windows/installer-hooks.nsh`、`apps/ai-game-creator-shell/scripts/build-release.test.mjs`、pitfalls。
+- 验证：`node --test apps/ai-game-creator-shell/scripts/build-release.test.mjs` → 42 passed（含新增守卫用例）；本地按 Tauri 模板渲染 + 同一份 makensis 复现 Jenkins 原始报错并在修复后零 warning 通过；`currentUser` / `perMachine` 两种形态分别编出 `KillProcessCurrentUser` / `KillProcess`。
+- 边界（未验证）：真实 Jenkins dev 渠道出包与真机升级仍未执行，里程碑里的升级验收项保持打开。
+
 ## 2026-09-29 策划提示词写明工作区是相对路径根目录

 - 决策：常驻提示词用一句说明工作区是相对路径根目录 `.`。策划文件仍放在工作区内并使用相对路径。不命名 `design_artifacts`，不宣布可以访问绝对路径或工作区外路径。
@@ -1,5 +1,15 @@
 # 踩坑与排障记录

+## 2026-09-29 NSIS 安装钩子被 include 在模板常量与插件目录之前（Jenkins 打包在 makensis 处中断）
+
+- **现象**：`Genarrative-Agc-Windows-Build` 打 dev 渠道 Windows 包时，Rust 编译过了，makensis 却报 `Plugin not found, cannot call nsis_tauri_utils::KillProcess`、`!include: error in script: "...\installer-hooks.nsh" on line 68`、`Error in script "...\installer.nsi" on line 28 -- aborting creation process`，Tauri 最后只补一句 `failed to bundle project 'The system cannot find the file specified. (os error 2)'`，退出码 1。
+- **原因**：Tauri 2.11 的 NSIS 模板把钩子放在 `installer.nsi` **第 28 行**（`{{#if installer_hooks}} !include "..." {{/if}}`，紧跟 `StrFunc.nsh`），早于 `!define INSTALLMODE`（第 37 行）与 `!define MAINBINARYNAME`（第 44 行），更早于第 89 行的 `!addplugindir "${ADDITIONALPLUGINSPATH}"`。钩子文件的第一版是顶层 `Function`，于是三件事同时踩雷：① include 时 `${INSTALLMODE}` 还是空值，`!if "${INSTALLMODE}" == "currentUser"` 走 `!else` 分支——编出来的正是报错里的第 68 行 `nsis_tauri_utils::KillProcess`；② 插件目录此时还没 add，makensis 找不到 `nsis_tauri_utils.dll`，直接中断整个打包；③ 同一函数体里的 `${MAINBINARYNAME}` / `${PRODUCTNAME}` / `${MANUFACTURER}` 也未定义（makensis warning 6000，字符串被静默替换成空文本）。只有第 29–94 行的顶层 `Function` 会这样，因为它跟着 include 立刻编译；`!macro` 体是插入时才展开的，所以放进宏里就没问题。
+- **本机复现**：从本地 `@tauri-apps/cli` 2.11.2 的二进制里取出内嵌模板，渲染出与构建机同一份 `installer.nsi`（钩子 include 正好落在第 28 行，与 Jenkins 日志一致），再用同一份 `src-tauri/target/.tauri/NSIS/makensis.exe` 编译 → 得到与 Jenkins **逐字相同**的三行报错；修复后同一份脚本零 warning 通过并产出安装包。修好的包字符串表里，`currentUser` 形态只命中 `KillProcessCurrentUser`、`perMachine` 形态只命中 `KillProcess`，证明 `${INSTALLMODE}` 分支现在是在宏展开时求值的。
+- **处理（现行口径）**：`installer-hooks.nsh` 顶层只允许 `!define` / `Var` / `!macro`；可执行逻辑全部待在宏里——迁移逻辑是 `!macro AgcMigrateLegacyIdentity`，旧展示名改用运行期变量 `$AgcLegacyIdentity` 传入（原来的 `Push`/`Pop` + `Function` 形态在 section 上下文里既拿不到模板常量、也不能用 `Return` 提前返回），由 `!macro NSIS_HOOK_POSTINSTALL` 在模板插入点（Section Install，addplugindir 之后）展开。
+- **判据/取证**：① `apps/ai-game-creator-shell/scripts/build-release.test.mjs` 新增守卫用例「安装钩子的可执行逻辑必须全在 !macro 内，顶层不得引用模板常量或插件」——对修复前的钩子文件跑同一解析逻辑命中 36 条顶层违规（含「第 68 行 顶层调用插件」），修复后 0 条；② 上面那份模板复现 + 双 `INSTALLMODE` 形态编译；③ 探针安装器（探针专属旧身份名 + 探针注册表键，全程不碰真实安装）实跑四组：旧目录不存在 → 卸载项与厂商键一个不动；旧目录 + 指向旧 exe 的桌面/开始菜单图标 → 旧目录、旧图标、旧卸载项被清，开始菜单图标补建、桌面图标只在原来就有时补建；桌面同名图标指向 `notepad.exe` → 图标保留且不补建桌面图标。
+- **不要踩的坑**：① 钩子顶层任何"本地看着能编译"的可执行逻辑都可能在构建机上炸掉整条发布，改钩子后必须至少跑一次真实 NSIS 打包或上面那条守卫用例；② 顶层引用 `${INSTALLMODE}` 这类模板常量不会报错，只会静默走错分支；③ 模板的 `${MAINBINARYNAME}` 是**不带 `.exe`** 的名字（模板自己拼 `.exe`），钩子里不要再加一次扩展名；④ 钩子文件含中文身份字面量，必须存成 UTF-8 with BOM。
+- **关联**：`apps/ai-game-creator-shell/src-tauri/windows/installer-hooks.nsh`、`apps/ai-game-creator-shell/scripts/build-release.mjs`、`apps/ai-game-creator-shell/scripts/build-release.test.mjs`、`docs/project-memory/plans/【里程碑】AGC渠道安装身份隔离-2026-09-21.md`。
+
 ## 2026-09-29 Codex 隔离用户目录被系统临时目录的符号链接拦下

 - **现象**：Game Agent 回合还没改项目文件就失败。卡片是 `direct-codex-failure:v2 stage=code-generation code=runtime-failure`，摘要为「创建 Codex app-server 隔离用户目录失败：Codex 隔离用户目录 路径不能包含符号链接：<absolute-path>」。诊断文件同样把路径脱敏，看不出是哪一级目录。