docs: 补充NapCat源码fork中文实施计划

2026-06-23 11:39:41 +08:00 · 2026-06-23 11:39:41 +08:00 · 2a6f418a62
commit 2a6f418a62
parent ca0848ce82
1 changed files with 486 additions and 0 deletions
--- a/docs/superpowers/plans/2026-06-23-qqbot-napcat-source-fork-qr-refresh-implementation-plan.zh-CN.md
+++ b/docs/superpowers/plans/2026-06-23-qqbot-napcat-source-fork-qr-refresh-implementation-plan.zh-CN.md
@ -0,0 +1,486 @@
 # QQBot NapCat 源码 Fork 二维码刷新修复实施计划（中文）
 > **给执行代理的要求：** 实施时必须使用 `superpowers:subagent-driven-development`（推荐）或 `superpowers:executing-plans`，按任务逐项执行并用复选框追踪。英文计划 `2026-06-23-qqbot-napcat-source-fork-qr-refresh-implementation-plan.md` 是精确执行版，包含完整测试代码和源码片段；本文件是同任务、同顺序、同验收标准的中文审核版，供用户确认范围和节奏。
 **目标：** fork NapCatQQ 源码，在源代码层修复 WebUI 登录态 stale 导致二维码无法刷新的问题，并通过 KT `desktop-cn-v3` 派生镜像上线验证。
 **架构：** 先在 NapCatQQ fork 内修复登录态模型和 QR refresh 可观测性，再让 KT API 的中文桌面镜像消费源码构建产物，替换原来的 bundled JS 字符串补丁。API 侧继续保留旧二维码防护，作为 NapCat/QQ 内核异常时的第二道保护。
 **技术栈：** NapCatQQ monorepo、TypeScript、Vitest、Vite Shell build、NestJS API、Jest、Docker、NAS SSH、Jenkins/K8s。
 ---
 ## 文件结构
 ### NapCatQQ Fork
 目标仓库：`D:\MyFiles\KT\GitHub\NapCatQQ`
 - 修改 `packages/napcat-webui-backend/src/types/index.ts`
  - 增加登录运行态、QR revision、QR refresh 结果类型。
 - 修改 `packages/napcat-webui-backend/src/helper/Data.ts`
  - 登录运行态真相源：负责 `QQLoginStatus`、`selfInfo.online`、二维码缓存、revision、stale reconcile。
 - 修改 `packages/napcat-webui-backend/src/api/QQLogin.ts`
  - 所有登录 HTTP handler 改用统一真实在线态判断。
 - 修改 `packages/napcat-shell/base.ts`
  - Shell 模式 QR refresh callback 返回 `loginService.getQRCodePicture()` 的 accepted 状态。
 - 修改 `packages/napcat-framework/napcat.ts`
  - Framework 模式 QR refresh callback 同步返回 accepted 状态。
 - 修改 `packages/napcat-test/vitest.config.ts`
  - 增加 WebUI backend 测试 alias。
 - 新增 `packages/napcat-test/webuiLoginRuntime.test.ts`
  - 覆盖 stale 登录态 reconcile、QR revision、QR refresh accepted/updated。
 - 新增 `packages/napcat-test/webuiQQLoginHandlers.test.ts`
  - 覆盖 stale 登录态下 handler 不再返回 `QQ Is Logined`。
 - 新增 `packages/napcat-test/webuiLoginSourceWiring.test.ts`
  - 静态检查 Shell/Framework callback 是否返回内核 accepted 状态。
 ### KT API 仓库
 目标仓库：`D:\MyFiles\KT\Node\kt-template-online-api`
 - 新增 `scripts/napcat-desktop-cn-stage-build.mjs`
  - 把 NapCatQQ fork 的 Shell dist staged 成 Docker build context。
 - 修改 `ci/napcat-desktop-cn/Dockerfile`
  - 从 staged context 复制源码构建产物，生成 `/app/NapCat.Shell.zip`。
 - 修改 `ci/napcat-desktop-cn/verify.sh`
  - 校验 fork marker、artifact hash、locale、timezone、XDG、fontconfig 和源码修复 marker。
 - 删除 `ci/napcat-desktop-cn/patches/qq-login-real-online-guard.sh`
  - 不再做 bundled JS 字符串 patch。
 - 修改 `ci/napcat-desktop-cn/README.md`
  - 写清 v3 staging/build/verify 命令。
 - 修改 `src/modules/qqbot/napcat/application/runtime/napcat-runtime-profile.service.ts`
  - 默认 desktop profile 升级到 `desktop-cn-v3`。
 - 修改 `test/modules/qqbot/napcat/napcat-desktop-cn-image.spec.ts`
  - 旧 patch 断言改成源码 artifact 断言。
 - 修改 `test/modules/qqbot/napcat/runtime-protocol-profile.spec.ts`
  - 更新默认 runtime profile 版本断言。
 - 修改 `README.md`、`API.md`
  - 记录 v3 镜像和 `QQBOT_NAPCAT_IMAGE` 要求。
 ### KT Root 文档
 目标仓库：`D:\MyFiles\KT`
 - 修改 `docs/qqbot-nas-runtime.md`
  - 记录 NapCat 源码 fork 镜像、canary 证据和上线边界。
 - 修改 `TASKS.md`
  - 增加本轮双语计划和后续实施上下文。
 ## 执行规则
 - 不创建 `.worktree`，按用户要求使用普通 dev 分支。
 - canary 任务之前不改生产容器。
 - 不删除 API 侧旧二维码防护。
 - 不推送，除非用户明确要求。
 - KT 自有新增/触达函数必须有 JSDoc，参数说明要写用途，不复读变量名。
 - 每个代码任务必须先跑 RED，再实现，再跑 GREEN。
 ## Task 1：准备 NapCatQQ Fork 分支
 **文件：**
 - 创建或更新 `D:\MyFiles\KT\GitHub\NapCatQQ`
 - [ ] 拉取或克隆上游 `NapNeko/NapCatQQ`。
 - [ ] 从 `main` 创建 `codex/qr-refresh-login-state`。
 - [ ] 确认基线 commit 当前为 `5c18a62530d87dbadf53d267002894faa6ca7e90`；如上游前进，则记录实际 commit。
 - [ ] 确认 `package.json` 有 `typecheck`、`test`、`build:shell`。
 验证命令：
 ```powershell
 git -C 'D:\MyFiles\KT\GitHub\NapCatQQ' rev-parse HEAD
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --version
 ```
 预期：分支存在，脚本入口可用。
 ## Task 2：新增 NapCat 登录运行态失败测试
 **文件：**
 - 修改 `D:\MyFiles\KT\GitHub\NapCatQQ\packages\napcat-test\vitest.config.ts`
 - 新增 `D:\MyFiles\KT\GitHub\NapCatQQ\packages\napcat-test\webuiLoginRuntime.test.ts`
 - [ ] 在 Vitest config 增加 `napcat-webui-backend` alias。
 - [ ] 新增运行态测试，覆盖：
  - `QQLoginStatus=true` 且 `selfInfo.online=false` 时 reconcile 为离线。
  - `selfInfo.online=undefined` 时不误判离线。
  - QR URL 变化时 revision 增加，重复写同 URL 不增加。
  - refresh callback 返回 `true` 且 QR callback 更新 URL 时，结果是 `accepted=true, updated=true`。
  - refresh callback 返回 `false` 时，结果是 rejected。
 - [ ] 运行 RED 测试。
 验证命令：
 ```powershell
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --filter napcat-test exec vitest run webuiLoginRuntime.test.ts
 ```
 预期：第一次失败，原因是 `__resetForTest`、`getQQLoginRuntimeState`、`clearQQLoginQrcodeURL` 和带返回值的 `refreshQRCode` 还不存在。
 ## Task 3：实现 NapCat WebUI 登录运行态模型
 **文件：**
 - 修改 `packages/napcat-webui-backend/src/types/index.ts`
 - 修改 `packages/napcat-webui-backend/src/helper/Data.ts`
 - 测试 `packages/napcat-test/webuiLoginRuntime.test.ts`
 - [ ] 增加类型：
  - `QQLoginRuntimeStateOptions`
  - `QQLoginRuntimeState`
  - `QQRefreshQRCodeOptions`
  - `QQRefreshQRCodeResult`
 - [ ] `LoginRuntimeType` 增加：
  - `QQQRCodeRevision`
  - `QQQRCodeUpdatedAt`
  - `onRefreshQRCode: () => Promise<boolean>`
 - [ ] `Data.ts` 增加 helper：
  - `delay`
  - `getCoreOnlineState`
  - `buildQQLoginRuntimeState`
  - `clearQQLoginQrcodeURL`
 - [ ] `setQQLoginQrcodeURL` 只在 URL 变化时递增 revision。
 - [ ] `getQQLoginRuntimeState({ reconcile, clearStaleQRCode })` 统一表达真实在线态。
 - [ ] `refreshQRCode(options)` 返回 `accepted`、`updated`、`qrcodeRevision`、`qrcodeurl`。
 - [ ] 增加 `__resetForTest()` 测试辅助。
 验证命令：
 ```powershell
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --filter napcat-test exec vitest run webuiLoginRuntime.test.ts
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --filter napcat-webui-backend run typecheck
 ```
 预期：测试和 typecheck 通过。
 提交：
 ```powershell
 git -C 'D:\MyFiles\KT\GitHub\NapCatQQ' add packages/napcat-webui-backend/src/types/index.ts packages/napcat-webui-backend/src/helper/Data.ts packages/napcat-test/vitest.config.ts packages/napcat-test/webuiLoginRuntime.test.ts
 git -C 'D:\MyFiles\KT\GitHub\NapCatQQ' commit -m "fix: 修复WebUI登录态与二维码刷新状态"
 ```
 ## Task 4：修复 QQLogin handler 登录态短路
 **文件：**
 - 新增 `packages/napcat-test/webuiQQLoginHandlers.test.ts`
 - 修改 `packages/napcat-webui-backend/src/api/QQLogin.ts`
 - [ ] 新增 handler 测试，覆盖：
  - `CheckLoginStatus` 会清理 stale login state，不返回旧 QR。
  - `RefreshQRcode` 在 stale login state 下允许执行。
  - core 明确在线时 quick login 仍返回 `QQ Is Logined`。
  - stale 后 `GetQRcode` 不返回旧二维码。
 - [ ] 运行 RED 测试。
 - [ ] 在 `QQLogin.ts` 增加 helper：
  - `isActuallyLoggedIn(clearStaleQRCode = true)`
  - `buildLoginStatusPayload()`
 - [ ] 将以下 handler 的直接 `getQQLoginStatus()` 判断改为真实在线态判断：
  - `QQGetQRcodeHandler`
  - `QQSetQuickLoginHandler`
  - `QQRefreshQRcodeHandler`
  - `QQPasswordLoginHandler`
  - `QQCaptchaLoginHandler`
  - `QQNewDeviceLoginHandler`
 - [ ] `QQCheckLoginStatusHandler` 统一返回 helper payload。
 - [ ] `QQRefreshQRcodeHandler` 返回 refresh result；若 rejected，则返回明确错误。
 - [ ] 给触达的 exported handler 补 JSDoc。
 验证命令：
 ```powershell
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --filter napcat-test exec vitest run webuiQQLoginHandlers.test.ts
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --filter napcat-test exec vitest run webuiLoginRuntime.test.ts webuiQQLoginHandlers.test.ts
 ```
 预期：测试通过。
 提交：
 ```powershell
 git -C 'D:\MyFiles\KT\GitHub\NapCatQQ' add packages/napcat-webui-backend/src/api/QQLogin.ts packages/napcat-test/webuiQQLoginHandlers.test.ts
 git -C 'D:\MyFiles\KT\GitHub\NapCatQQ' commit -m "fix: 收敛QQ登录接口真实在线态判断"
 ```
 ## Task 5：打通 Shell/Framework QR refresh callback 返回值
 **文件：**
 - 新增 `packages/napcat-test/webuiLoginSourceWiring.test.ts`
 - 修改 `packages/napcat-shell/base.ts`
 - 修改 `packages/napcat-framework/napcat.ts`
 - [ ] 新增静态源码测试，确认 Shell/Framework 都包含 `return loginService.getQRCodePicture();`。
 - [ ] 运行 RED 测试。
 - [ ] Shell 模式的 `setRefreshQRCodeCallback` 返回 `loginService.getQRCodePicture()`。
 - [ ] Framework 模式同样返回 `loginService.getQRCodePicture()`。
 - [ ] 运行源码 wiring 测试和两包 typecheck。
 验证命令：
 ```powershell
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --filter napcat-test exec vitest run webuiLoginSourceWiring.test.ts
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --filter napcat-shell run typecheck
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --filter napcat-framework run typecheck
 ```
 预期：测试和 typecheck 通过。
 提交：
 ```powershell
 git -C 'D:\MyFiles\KT\GitHub\NapCatQQ' add packages/napcat-shell/base.ts packages/napcat-framework/napcat.ts packages/napcat-test/webuiLoginSourceWiring.test.ts
 git -C 'D:\MyFiles\KT\GitHub\NapCatQQ' commit -m "fix: 返回二维码刷新请求接收状态"
 ```
 ## Task 6：构建并验证 NapCatQQ Fork Artifact
 **文件：**
 - 无新增文件；除非验证暴露明确编译或测试问题。
 - [ ] 安装依赖。
 - [ ] 跑新增 WebUI 相关 Vitest。
 - [ ] 跑 NapCatQQ 现有测试。
 - [ ] 跑 monorepo typecheck。
 - [ ] 构建 WebUI frontend。
 - [ ] 构建 Shell artifact。
 - [ ] 记录 fork commit 与 `napcat.mjs` SHA256。
 验证命令：
 ```powershell
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' install --frozen-lockfile
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --filter napcat-test exec vitest run webuiLoginRuntime.test.ts webuiQQLoginHandlers.test.ts webuiLoginSourceWiring.test.ts
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --filter napcat-test exec vitest run
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' run typecheck
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' --filter napcat-webui-frontend run build
 corepack pnpm --dir 'D:\MyFiles\KT\GitHub\NapCatQQ' run build:shell
 Get-FileHash -Algorithm SHA256 'D:\MyFiles\KT\GitHub\NapCatQQ\packages\napcat-shell\dist\napcat.mjs'
 ```
 预期：`packages/napcat-shell/dist/napcat.mjs` 存在，所有测试/typecheck/build 通过。
 ## Task 7：新增 API 镜像 build-context staging 脚本
 **文件：**
 - 新增 `scripts/napcat-desktop-cn-stage-build.mjs`
 - 修改 `test/modules/qqbot/napcat/napcat-desktop-cn-image.spec.ts`
 - [ ] 在 API image test 中新增 staging script 静态断言，覆盖：
  - `napcatMjsSha256`
  - `forkCommit`
  - `upstreamBaseCommit`
  - `packages/napcat-shell/dist`
  - `fork-artifact.json`
  - `.kt-workspace/napcat-desktop-cn-build`
 - [ ] 运行 RED Jest。
 - [ ] 新增 staging 脚本：
  - 参数 `--napcat-root`
  - 参数 `--out`
  - 复制 `Dockerfile`、`verify.sh`、`NapCat.Shell` dist
  - 写入 `fork-artifact.json`
  - 计算 dist 与 `napcat.mjs` SHA256
  - 输出 marker 和 output root
 - [ ] 跑 Jest，确认新测试通过；旧 patch 测试会在 Task 8 更新。
 验证命令：
 ```powershell
 corepack pnpm --dir 'D:\MyFiles\KT\Node\kt-template-online-api' exec jest test/modules/qqbot/napcat/napcat-desktop-cn-image.spec.ts --runTestsByPath --runInBand
 ```
 预期：新增 staging 断言通过。
 ## Task 8：用源码 artifact 替换 bundled JS patch
 **文件：**
 - 修改 `ci/napcat-desktop-cn/Dockerfile`
 - 修改 `ci/napcat-desktop-cn/verify.sh`
 - 删除 `ci/napcat-desktop-cn/patches/qq-login-real-online-guard.sh`
 - 修改 `test/modules/qqbot/napcat/napcat-desktop-cn-image.spec.ts`
 - [ ] 把旧 patch 断言替换为源码 artifact 断言：
  - Dockerfile 包含 `COPY NapCat.Shell /tmp/NapCat.Shell`
  - Dockerfile 包含 `fork-artifact.json`
  - Dockerfile 仍生成 `/app/NapCat.Shell.zip`
  - Dockerfile 不再包含 `qq-login-real-online-guard.sh`
  - verify 包含 `napcatMjsSha256`
  - verify 包含 `getQQLoginRuntimeState`
  - verify 包含 `qrcodeRevision`
 - [ ] 运行 RED Jest。
 - [ ] Dockerfile 删除 patch block，改为复制 staged Shell dist 并 zip 到 `/app/NapCat.Shell.zip`。
 - [ ] verify.sh 校验：
  - locale/timezone/font/XDG
  - `/.dockerenv` 隐藏与 cgroup evidence
  - fork marker 存在
  - `NapCat.Shell.zip` 存在
  - 解压后 `napcat.mjs` hash 与 marker 一致
  - bundle 内存在 `getQQLoginRuntimeState` 与 `qrcodeRevision`
 - [ ] 删除旧 patch 脚本。
 - [ ] 跑 image Jest。
 验证命令：
 ```powershell
 git -C 'D:\MyFiles\KT\Node\kt-template-online-api' rm -- 'ci/napcat-desktop-cn/patches/qq-login-real-online-guard.sh'
 corepack pnpm --dir 'D:\MyFiles\KT\Node\kt-template-online-api' exec jest test/modules/qqbot/napcat/napcat-desktop-cn-image.spec.ts --runTestsByPath --runInBand
 ```
 预期：Jest 通过，旧 patch 脚本被删除。
 ## Task 9：更新 Runtime Profile 版本与文档
 **文件：**
 - 修改 `src/modules/qqbot/napcat/application/runtime/napcat-runtime-profile.service.ts`
 - 修改 `test/modules/qqbot/napcat/runtime-protocol-profile.spec.ts`
 - 修改 `ci/napcat-desktop-cn/README.md`
 - 修改 `README.md`
 - 修改 `API.md`
 - 修改 `D:\MyFiles\KT\docs\qqbot-nas-runtime.md`
 - [ ] 将测试预期从 `desktop-cn-v2` 改为 `desktop-cn-v3`，先跑 RED。
 - [ ] 将 service 默认值改为 `desktop-cn-v3`。
 - [ ] README 写清：
  - 先构建 NapCatQQ fork。
  - 再运行 staging 脚本。
  - 再 build `kt-napcat-desktop-cn:desktop-cn-v3`。
  - 再执行容器内 `verify.sh`。
 - [ ] API/README/root docs 写明：生产 `QQBOT_NAPCAT_IMAGE` 应指向验证过的 v3 digest。
 验证命令：
 ```powershell
 corepack pnpm --dir 'D:\MyFiles\KT\Node\kt-template-online-api' exec jest test/modules/qqbot/napcat/runtime-protocol-profile.spec.ts --runTestsByPath --runInBand --testNamePattern "resolves Chinese Desktop Runtime defaults"
 corepack pnpm --dir 'D:\MyFiles\KT\Node\kt-template-online-api' exec jest test/modules/qqbot/napcat/runtime-protocol-profile.spec.ts --runTestsByPath --runInBand
 ```
 预期：RED 后 GREEN，profile 默认版本为 `desktop-cn-v3`。
 ## Task 10：验证 API 镜像集成并提交
 **文件：**
 - Task 7 到 Task 9 的所有 API/root 改动。
 - [ ] 跑 API 聚焦 Jest。
 - [ ] 跑 API typecheck。
 - [ ] 跑 API/root diff check。
 - [ ] 跑 global-review。
 - [ ] API 仓库提交。
 - [ ] 根仓库提交 docs/TASKS。
 验证命令：
 ```powershell
 corepack pnpm --dir 'D:\MyFiles\KT\Node\kt-template-online-api' exec jest test/modules/qqbot/napcat/napcat-desktop-cn-image.spec.ts test/modules/qqbot/napcat/runtime-protocol-profile.spec.ts --runTestsByPath --runInBand
 corepack pnpm --dir 'D:\MyFiles\KT\Node\kt-template-online-api' run typecheck
 git -C 'D:\MyFiles\KT\Node\kt-template-online-api' diff --check
 git -C 'D:\MyFiles\KT' diff --check -- TASKS.md docs/qqbot-nas-runtime.md
 pnpm --dir 'D:\MyFiles\KT\mcp\ktWorkflow' run global-review
 ```
 预期：全部通过，`global-review findings=[]`。
 提交命令：
 ```powershell
 git -C 'D:\MyFiles\KT\Node\kt-template-online-api' add ci/napcat-desktop-cn scripts/napcat-desktop-cn-stage-build.mjs src/modules/qqbot/napcat/application/runtime/napcat-runtime-profile.service.ts test/modules/qqbot/napcat README.md API.md
 git -C 'D:\MyFiles\KT\Node\kt-template-online-api' commit -m "feat: 接入NapCat源码构建镜像"
 git -C 'D:\MyFiles\KT' add docs/qqbot-nas-runtime.md TASKS.md
 git -C 'D:\MyFiles\KT' commit -m "docs: 记录NapCat源码构建运行态"
 ```
 ## Task 11：构建镜像并执行本地或 NAS verify
 **文件：**
 - 无源码文件；只有验证证据。
 - [ ] 从 API 仓库运行 staging 脚本。
 - [ ] 用 pinned base image 构建 `kt-napcat-desktop-cn:desktop-cn-v3`。
 - [ ] 启动一次 verify 容器。
 - [ ] 容器内执行 `/ci/napcat-desktop-cn/verify.sh`。
 - [ ] 删除 verify 容器。
 - [ ] 记录 image id/digest。
 验证命令：
 ```powershell
 node scripts/napcat-desktop-cn-stage-build.mjs `
  --napcat-root D:\MyFiles\KT\GitHub\NapCatQQ `
  --out .kt-workspace\napcat-desktop-cn-build
 $baseImage = docker image inspect mlikiowa/napcat-docker:latest --format '{{index .RepoDigests 0}}'
 if (-not $baseImage) { docker pull mlikiowa/napcat-docker:latest; $baseImage = docker image inspect mlikiowa/napcat-docker:latest --format '{{index .RepoDigests 0}}' }
 docker build `
  --build-arg NAPCAT_BASE_IMAGE=$baseImage `
  -t kt-napcat-desktop-cn:desktop-cn-v3 `
  -f .kt-workspace/napcat-desktop-cn-build/ci/napcat-desktop-cn/Dockerfile `
  .kt-workspace/napcat-desktop-cn-build
 $name = "kt-napcat-v3-verify-$([DateTimeOffset]::UtcNow.ToUnixTimeSeconds())"
 docker run -d --name $name kt-napcat-desktop-cn:desktop-cn-v3
 docker exec $name sh /ci/napcat-desktop-cn/verify.sh
 docker rm -f $name
 docker image inspect kt-napcat-desktop-cn:desktop-cn-v3 --format '{{.Id}}'
 ```
 预期：镜像构建成功，verify 退出码为 0。
 ## Task 12：部署并进行线上 canary
 **文件：**
 - 无源码文件；除非线上验证暴露明确 bug。
 - [ ] 用户确认后再 push。
 - [ ] push NapCatQQ fork 分支。
 - [ ] push API main。
 - [ ] 观察 Jenkins/K8s。
 - [ ] 配置生产环境：
  - `QQBOT_NAPCAT_IMAGE=kt-napcat-desktop-cn:desktop-cn-v3`
  - `QQBOT_NAPCAT_DESKTOP_PROFILE_VERSION=desktop-cn-v3`
 - [ ] 只对一个用户确认账号做 canary。
 - [ ] 捕获完整证据：
  - NapCat fork commit
  - NapCat image id
  - scan session id
  - old QR hash prefix
  - new QR hash prefix
  - qrcode.png old/new mtime
  - `RefreshQRcode.accepted`
  - `RefreshQRcode.updated`
  - SSE 最终状态
 部署观测命令：
 ```powershell
 pnpm --dir 'D:\MyFiles\KT\mcp\ktWorkflow' run deploy-observation -- --project api --job KT-Template/KT-Template-API/main --execute
 ```
 canary 通过标准：
 - stale `QQLoginStatus=true + online=false` 不再返回 `QQ Is Logined`。
 - NapCat 生成新 QR，或返回 `accepted=true, updated=false` 且 API 不展示旧码。
 - `/app/napcat/cache/qrcode.png` hash/mtime 能证明是否真的产码。
 - API `scan/status` 不返回旧 QR hash。
 - Admin/SSE 显示新 QR 或明确 pending 原因。
 ## 自检清单
 - 源码 fork：Task 1-6 覆盖。
 - stale 登录态修复：Task 2-4 覆盖。
 - QR refresh 可观测：Task 2、3、5、12 覆盖。
 - WebUI handler 不回旧码：Task 4 覆盖。
 - API 防旧码保留：Task 7-10 不改 API 登录 service。
 - 源码 artifact 镜像：Task 7-11 覆盖。
 - 本地与线上验证：Task 6、10、11、12 覆盖。
 - 本中文计划已完成自检。