修复 AGC Ctrl+C 残留上个工作树后端导致切换工作树复用旧后端
closes #314 新增 scripts/dev-windows-process.mjs：提供按根 PID 遍历与按身份匹配（api-server.exe 绝对路径、SpacetimeDB --data-dir）两条独立清理路径 scripts/dev.mjs：直接子进程（cmd.exe 包装层）已退出时仍按记录 PID 清理后代，不再提前 return scripts/dev.mjs：退出时按身份兜底清扫本工作树 api-server 与自建 SpacetimeDB，复用他人 standalone 时跳过 scripts/dev.mjs：启动前清理旧 api-server 保留 Wait-Process 等待语义，避免 cargo 报 failed to remove file apps/ai-game-creator-shell/scripts/start-dev-stack.mjs：复用配套后端前校验端口监听进程归属，无法证明归属则改为启动本工作树后端并允许端口漂移 apps/ai-game-creator-shell/scripts/start-dev-stack.mjs：收到信号与 finally 各兜底清扫一次本工作树 api-server.exe，taskkill 失败时降级为按 PID 遍历 apps/ai-game-creator-shell/scripts/start-dev-stack.mjs：等待后端就绪时输出归属校验未通过的具体原因，避免只表现为 600 秒超时 新增 scripts/dev-windows-process.test.ts 并扩充 AGC 复用门禁用例：覆盖断链遍历、身份匹配、归属判定与探测不可用退化 同步 docs/project-memory/shared-memory/pitfalls.md 与本地开发运维文档的进程清理与复用归属口径
This commit is contained in:
@@ -34,6 +34,18 @@
|
||||
|
||||
主配置与 local overlay 的单文件原子写入不能保证整体成功；覆盖层写入失败会留下混合配置。保存前先序列化全部变更，多文件保存保留原内容，错误时逆序恢复并报告回滚失败；单文件保持原写入路径，成功后不回读、不触发外部诊断。此回滚仅处理可捕获错误，不承诺进程崩溃下的事务恢复。
|
||||
|
||||
## 2026-09-09 `npm run agc` 的 Ctrl+C 不能只依赖 shell 包装层与端口健康检查
|
||||
|
||||
- **现象**：`npm run agc` 按 Ctrl+C 后终端回到提示符，但上个工作树的 `api-server.exe` / SpacetimeDB 仍在监听 `8082` / `8083` / `3101`；切到另一个 worktree 再启动 AGC 时，前端仍然连到上个工作树的后端，在改过数据库 / schema 的工作树上会串库。
|
||||
- **原因**：
|
||||
1. Windows 下所有长驻服务都由 Node `shell: true` 经 `cmd.exe /d /s /c` 包装层启动，Ctrl+C 会先杀掉包装层（退出码 `0xC000013A`）。`scripts/dev.mjs` 的 `stopProcess` 见到直接子进程已退出就直接 `return`，`start-dev-stack.mjs` / `start-tauri-dev.mjs` 对已退出 PID 的 `taskkill /PID <pid> /T /F` 只会失败并返回 `stopped: false`，于是更深的 `cargo → api-server.exe` 没有任何人收。
|
||||
2. 即使走到按根 PID 遍历进程树，遍历依赖快照里的父子链；中间层（包装层）先消失时链路断开，遍历只能拿到根 PID，深处的后端不可达。
|
||||
3. 复用判据只看 `.app/dev-stack.json` 的 status 与 `/healthz`、`/readyz`、`/v1/ping`，从不校验端口上的进程属于哪个工作树；残留后端照样“健康”，因此被当成自己的后端复用。
|
||||
- **处理**：新增 `scripts/dev-windows-process.mjs`，同时提供按根 PID 遍历与按身份匹配（`server-rs/target/debug/api-server.exe` 绝对路径、SpacetimeDB `--data-dir`）两条独立清理路径。`dev.mjs` 在直接子进程已退出时也继续清理，并在退出时按身份兜底清扫本工作树后端（复用他人 standalone 时不清理）。`start-dev-stack.mjs` 在收到信号和 `finally` 各清扫一次本工作树 `api-server.exe`（仅限本次自己拉起后端的情况），复用前先校验端口监听进程归属，无法证明归属就不复用、改为启动自己的后端并允许端口漂移。
|
||||
- **排查顺序**：先看 `.app/dev-stack.json` 的 status 与实际监听端口是否一致，再用 `Get-CimInstance Win32_Process` 按本工作树 `server-rs\target\debug\api-server.exe` 路径与 SpacetimeDB `--data-dir` 核对残留进程；不要因为 `/healthz` 返回 200 就认定后端属于当前工作树。
|
||||
- **验证**：`node --check scripts/dev.mjs scripts/dev-windows-process.mjs apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`；`npx vitest run scripts/dev-windows-process.test.ts apps/ai-game-creator-shell/tests/start-dev-stack.test.ts scripts/dev.test.ts`；真机确认 Ctrl+C 后没有匹配本工作树 `api-server.exe` 路径的残留进程。
|
||||
- **关联**：`scripts/dev.mjs`、`scripts/dev-windows-process.mjs`、`apps/ai-game-creator-shell/scripts/start-dev-stack.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
## 2026-09-02 Tauri 事件桥在浏览器预览中必须 fail-safe
|
||||
|
||||
- **现象**：Vitest/jsdom 挂载 AGC 客户端时，错误报告通知调用 `@tauri-apps/api/event.listen`，因缺少 `window.__TAURI_INTERNALS__` 产生未处理拒绝；测试断言虽通过，CI 仍以 unhandled errors 失败。
|
||||
|
||||
@@ -62,9 +62,9 @@ Linux 本机多用户并发开发时，`npm run dev`、`npm run dev:*` 单模块
|
||||
|
||||
后端日志默认写入 `logs/api-server/`，独立 BgFilter worker 日志默认写入 `logs/bgfilter-worker/`。后端 API smoke 使用 `npm run dev:api-server`，先检查 BgFilter worker `/readyz`，再检查 API `/healthz`；需要确认 API 实例可接生产流量时检查 API `/readyz`。不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。
|
||||
|
||||
AI 游戏创作客户端使用 `npm run agc`。该入口由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 解析 AGC Vite 实际端口：Linux 默认取当前用户端口段的 `start + 5`，占用时只在本用户段内漂移；Windows / macOS 保留 `3080` 为兼容首选并允许统一漂移。最终端口通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，通过 Tauri CLI 动态 `build.devUrl` 配置传给 WebView，并通过 Vite CLI `--port` 启动严格监听；Vite 继续使用 `strictPort`，任何一层都不得自行改到另一个端口。AGC 配套后端的 `backend` 模式启动 SpacetimeDB、独立 `bgfilter-worker` 和 `api-server`，并在复用现有后端前同时检查三者状态及 `/v1/ping`、`/readyz`、`/healthz`；worker 缺失时不得把不完整的 API/数据库组合误判为 ready。任一配套服务在启动阶段进入 `failed` 时，外层启动器必须立即报告具体服务和退出原因，不能继续等待前端地址超时。启动器在创建原生窗口前预检最终地址；若竞态中该地址被 AGC Vite、无响应监听器或其它服务占用，一律失败关闭，不复用、也不擅自终止无法证明归属的进程。
|
||||
AI 游戏创作客户端使用 `npm run agc`。该入口由 `apps/ai-game-creator-shell/scripts/start-tauri-dev.mjs` 解析 AGC Vite 实际端口：Linux 默认取当前用户端口段的 `start + 5`，占用时只在本用户段内漂移；Windows / macOS 保留 `3080` 为兼容首选并允许统一漂移。最终端口通过 `GENARRATIVE_AGC_VITE_PORT` 传给 `beforeDevCommand` 和配套后端端口解析器，通过 Tauri CLI 动态 `build.devUrl` 配置传给 WebView，并通过 Vite CLI `--port` 启动严格监听；Vite 继续使用 `strictPort`，任何一层都不得自行改到另一个端口。AGC 配套后端的 `backend` 模式启动 SpacetimeDB、独立 `bgfilter-worker` 和 `api-server`，并在复用现有后端前同时检查三者状态及 `/v1/ping`、`/readyz`、`/healthz`；worker 缺失时不得把不完整的 API/数据库组合误判为 ready。任一配套服务在启动阶段进入 `failed` 时，外层启动器必须立即报告具体服务和退出原因，不能继续等待前端地址超时。端口健康不等于归属正确：复用前还必须证明端口上的监听进程属于当前工作树（Windows 按 `server-rs/target/debug/api-server.exe` 绝对路径与 SpacetimeDB `--data-dir` 校验，探测不可用时退化为旧行为），无法证明归属时一律不复用，改为启动本工作树自己的后端并在需要时端口漂移；否则上个工作树 Ctrl+C 残留的后端会被当成自己的后端复用，改了数据库的工作树会连到旧库。启动器在创建原生窗口前预检最终地址；若竞态中该地址被 AGC Vite、无响应监听器或其它服务占用，一律失败关闭，不复用、也不擅自终止无法证明归属的进程。
|
||||
|
||||
Tauri `beforeDevCommand` 默认与客户端构建并行，不能把上述检查只放在 `beforeDevCommand` 内：选定地址上若已有旧 Vite，Tauri 可能先创建加载旧前端的窗口，随后配套后端才因代理不匹配退出。外层启动器会把 Tauri CLI 放入受控进程树；CLI 正常退出、启动失败或收到终止信号后，POSIX 先向保留的 PGID 发送 `SIGTERM`、有界等待后升级 `SIGKILL`，Windows 使用 `taskkill /PID <pid> /T /F`。Linux 容器中的孤儿后代退出后可能暂时保留为 zombie，`kill(-PGID, 0)` 仍会返回成功；启动器必须结合 `/proc/<pid>/stat` 判断同组是否还存在非 zombie 成员，不能把等待 PID 1 回收误报为清理失败。配套后端和 Vite 仍由 `start-dev-stack.mjs` 各自持有，退出时同样有界收束，避免只剩客户端、Runner、Cargo 或旧订阅进程。排障时同时核对控制台输出的 AGC Vite 实际地址及其 marker、`.app/dev-stack.json` 的实际 API URL 和进程 cwd；不要把“终端已返回”当成客户端及其 Runner 已退出的证据。
|
||||
Tauri `beforeDevCommand` 默认与客户端构建并行，不能把上述检查只放在 `beforeDevCommand` 内：选定地址上若已有旧 Vite，Tauri 可能先创建加载旧前端的窗口，随后配套后端才因代理不匹配退出。外层启动器会把 Tauri CLI 放入受控进程树；CLI 正常退出、启动失败或收到终止信号后，POSIX 先向保留的 PGID 发送 `SIGTERM`、有界等待后升级 `SIGKILL`，Windows 使用 `taskkill /PID <pid> /T /F`。Windows 下每个长驻服务都经 `cmd.exe /d /s /c` 包装层启动，Ctrl+C 会先杀掉包装层（退出码 `0xC000013A`），因此清理不能只看直接子进程是否存活：`taskkill` 对已退出的 PID 只会失败，必须继续按记录下来的根 PID 遍历，并在退出时按本工作树 `api-server.exe` 绝对路径（以及本次自己拉起的 SpacetimeDB `--data-dir`）做一次身份兜底清扫；`scripts/dev-windows-process.mjs` 是这套判定的唯一实现。Linux 容器中的孤儿后代退出后可能暂时保留为 zombie，`kill(-PGID, 0)` 仍会返回成功；启动器必须结合 `/proc/<pid>/stat` 判断同组是否还存在非 zombie 成员，不能把等待 PID 1 回收误报为清理失败。配套后端和 Vite 仍由 `start-dev-stack.mjs` 各自持有，退出时同样有界收束，避免只剩客户端、Runner、Cargo 或旧订阅进程。排障时同时核对控制台输出的 AGC Vite 实际地址及其 marker、`.app/dev-stack.json` 的实际 API URL 和进程 cwd；不要把“终端已返回”当成客户端及其 Runner 已退出的证据。
|
||||
|
||||
Windows 本地 `npm run dev` / `npm run dev:api-server` / `npm run dev:bgfilter-worker` 会用空的 `RUSTC_WRAPPER` / `CARGO_BUILD_RUSTC_WRAPPER` 覆盖 `server-rs/.cargo/config.toml` 里的 `sccache`，从而直连真实 `rustc`。完整栈和 `dev:api-server` 把 API 与 BgFilter worker 作为一个 Rust 重启单元：源码变化时先停两个进程，再先启动并验活 worker、最后启动并验活 API，避免两个 `cargo run` 并发链接同一个 Windows 可执行文件。不要把 wrapper 绕过值写成 `rustc`；Cargo 会按 wrapper 协议调用 `rustc <真实rustc路径> - ...`，最终报 `multiple input filenames provided` 并导致 api-server 无法启动。排查本地启动失败时，先看 dev 日志是否出现该错误，再确认脚本注入的 wrapper 为空。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user