docs: 编写NapCatQQ自动化实施计划

2026-06-24 22:53:38 +08:00 · 2026-06-24 22:53:38 +08:00 · e6bc9e056e
commit e6bc9e056e
parent 18a74582f1
2 changed files with 1654 additions and 0 deletions
--- a/docs/superpowers/plans/2026-06-24-napcatqq-upstream-sync-runtime-release-pipeline-implementation-plan.md
+++ b/docs/superpowers/plans/2026-06-24-napcatqq-upstream-sync-runtime-release-pipeline-implementation-plan.md
--- a/docs/superpowers/plans/2026-06-24-napcatqq-upstream-sync-runtime-release-pipeline-implementation-plan.zh-CN.md
+++ b/docs/superpowers/plans/2026-06-24-napcatqq-upstream-sync-runtime-release-pipeline-implementation-plan.zh-CN.md
@ -0,0 +1,618 @@
+# NapCatQQ 上游同步与运行时发布流水线实施计划
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 把 NapCatQQ 上游 release 审计、Codex CLI 辅助审查、KT 派生运行时镜像构建、API 显式参数推广全部收敛到可验证的 ktWorkflow 自动化链路。
+
+**Architecture:** `mcp/ktWorkflow` 作为自动化控制面，负责确定性采集器、提示词、schema 校验、Codex CLI runner、artifact 归档、MCP tools 和 Jenkins/systemd 命令入口。API 仓库只负责运行时镜像构建契约和部署参数消费，Jenkins/NAS 定时器只调用 ktWorkflow，不复制审计算法。
+
+**Tech Stack:** TypeScript ESM、MCP SDK、zod、Node `child_process`、Codex CLI `exec`、Jenkins Pipeline、Docker、K8s、NestJS API runtime config、Jest。
+
+---
+
+## 文件结构
+
+### `D:\MyFiles\KT\mcp\ktWorkflow`
+
+- 新增 `prompts/napcat/upstream-audit.md`：上游 release 风险分类提示词。
+- 新增 `prompts/napcat/sync-candidate-review.md`：候选分支审查提示词。
+- 新增 `prompts/napcat/runtime-release-readiness.md`：运行时镜像发布就绪审查提示词。
+- 新增 `prompts/napcat/remote-dev-handoff.md`：NAS 远程开发交接提示词。
+- 新增 `prompts/napcat/schemas/upstream-audit.schema.json`：`codex exec --output-schema` 使用的 JSON Schema。
+- 新增 `prompts/napcat/schemas/runtime-release-readiness.schema.json`：运行时发布就绪报告 schema。
+- 新增 `src/tools/napcatAutomation.types.ts`：zod schema、输入输出类型、分类和 reason code 常量。
+- 新增 `src/tools/napcatAutomation.prompts.ts`：提示词路径解析和读取。
+- 新增 `src/tools/napcatAutomation.ts`：确定性采集器、Codex runner、artifact writer、MCP/CLI builder。
+- 修改 `src/types.ts`、`src/core/cli.ts`、`src/registerTools.ts`、`src/server.ts`、`src/core/constants.ts`、`src/selfTest.ts`、`package.json`、`README.md`。
+
+### `D:\MyFiles\KT\Node\kt-template-online-api`
+
+- 修改 `scripts/napcat-desktop-cn-stage-build.mjs`：写入 upstream release、base image digest、Jenkins URL 等 marker。
+- 修改 `test/modules/qqbot/napcat/napcat-desktop-cn-image.spec.ts`：覆盖 marker 与默认镜像契约。
+- 新增 `test/modules/qqbot/napcat/napcat-runtime-promotion.spec.ts`：覆盖 Jenkins/K8s runtime override。
+- 修改 `Jenkinsfile`：增加 `QQBOT_NAPCAT_IMAGE_OVERRIDE` 与 `QQBOT_NAPCAT_DESKTOP_PROFILE_VERSION_OVERRIDE`。
+- 修改 `k8s/prod/api.yaml`：保留安全默认值，由 Jenkins 在发布时显式覆盖。
+- 修改 `README.md`、`API.md`：记录发布和回滚契约。
+
+### `D:\MyFiles\KT\GitHub\NapCatQQ`
+
+- 新增 `ci/kt-runtime-release.md`：KT 运行时发布清单。
+- 本计划不改 NapCat 登录源码；如果上游同步撞到登录 hot zone，另起 NapCatQQ 专项计划。
+
+### `D:\MyFiles\KT`
+
+- 修改 `TASKS.md`：记录实施结果和验证证据。
+
+---
+
+### Task 1：ktWorkflow NapCat 自动化契约
+
+**Files:**
+- Create: `D:\MyFiles\KT\mcp\ktWorkflow\src\tools\napcatAutomation.types.ts`
+- Create: `D:\MyFiles\KT\mcp\ktWorkflow\prompts\napcat\schemas\upstream-audit.schema.json`
+- Create: `D:\MyFiles\KT\mcp\ktWorkflow\prompts\napcat\schemas\runtime-release-readiness.schema.json`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\selfTest.ts`
+
+- [ ] **Step 1：先写 RED self-test**
+
+覆盖三件事：`manual-review` 分类能被解析、`HOT_ZONE_CHANGED` reason code 存在、`upstreamAuditOutputSchema` 能校验最小输出。
+
+```ts
+import {
+  napcatAutomationReasonCodes,
+  parseNapcatAutomationClassification,
+  upstreamAuditOutputSchema,
+} from './tools/napcatAutomation.types.js';
+
+const napcatAuditSchemaSmoke = upstreamAuditOutputSchema.safeParse({
+  classification: 'manual-review',
+  reasonCodes: ['HOT_ZONE_CHANGED'],
+  recommendedAction: 'request-human-review',
+  summary: 'Login hot-zone changed.',
+});
+if (!napcatAuditSchemaSmoke.success) {
+  throw new Error('NapCat upstream audit schema self-check failed');
+}
+if (!napcatAutomationReasonCodes.includes('HOT_ZONE_CHANGED')) {
+  throw new Error('NapCat reason-code list self-check failed');
+}
+if (parseNapcatAutomationClassification('manual-review') !== 'manual-review') {
+  throw new Error('NapCat classification parser self-check failed');
+}
+```
+
+- [ ] **Step 2：确认 RED**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+```
+
+预期：因为 `napcatAutomation.types.js` 不存在而失败。
+
+- [ ] **Step 3：实现类型与 zod schema**
+
+实现 `safe-candidate`、`manual-review`、`blocked` 三类分类，以及 `NO_UPSTREAM_CHANGE`、`HOT_ZONE_CHANGED`、`FORK_PATCH_OVERLAP`、`DRY_MERGE_CONFLICT`、`BUILD_GRAPH_CHANGED`、`METADATA_UNAVAILABLE`、`CODEX_SCHEMA_INVALID` 七个 reason code。新增函数必须写 JSDoc，参数说明要解释来源和约束。
+
+- [ ] **Step 4：写 Codex CLI JSON Schema**
+
+`upstream-audit.schema.json` 必须要求 `classification`、`reasonCodes`、`recommendedAction`、`summary`，并禁止额外字段；`runtime-release-readiness.schema.json` 必须要求 `sourceValidation`、`imageValidation`、`apiPromotionReadiness`、`onlineSmokeReadiness`、`rollbackPointer`。
+
+- [ ] **Step 5：确认 GREEN**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run typecheck
+```
+
+- [ ] **Step 6：提交**
+
+```powershell
+git -C D:\MyFiles\KT\mcp\ktWorkflow add prompts/napcat src/tools/napcatAutomation.types.ts src/selfTest.ts
+git -C D:\MyFiles\KT\mcp\ktWorkflow commit -m "feat: 定义NapCat自动化审计契约"
+```
+
+---
+
+### Task 2：ktWorkflow 提示词包与安全读取器
+
+**Files:**
+- Create: `D:\MyFiles\KT\mcp\ktWorkflow\prompts\napcat\upstream-audit.md`
+- Create: `D:\MyFiles\KT\mcp\ktWorkflow\prompts\napcat\sync-candidate-review.md`
+- Create: `D:\MyFiles\KT\mcp\ktWorkflow\prompts\napcat\runtime-release-readiness.md`
+- Create: `D:\MyFiles\KT\mcp\ktWorkflow\prompts\napcat\remote-dev-handoff.md`
+- Create: `D:\MyFiles\KT\mcp\ktWorkflow\src\tools\napcatAutomation.prompts.ts`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\selfTest.ts`
+
+- [ ] **Step 1：先写 RED self-test**
+
+self-test 遍历所有提示词，要求每个 prompt 都包含安全边界：
+
+```md
+Do not edit files.
+Do not run merge, commit, push, deploy, or Docker mutation commands.
+Use only the supplied context packet.
+Return JSON that matches the requested schema.
+```
+
+- [ ] **Step 2：确认 RED**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+```
+
+- [ ] **Step 3：实现 prompt loader**
+
+`loadNapcatAutomationPrompt(name)` 只允许读取 `prompts/napcat/${name}.md` 中的固定 prompt 名称，不能接受任意路径。函数必须有 JSDoc，说明 `name` 来自稳定枚举，不是用户文件路径。
+
+- [ ] **Step 4：写四份提示词**
+
+四份 prompt 分别服务：
+
+- `upstream-audit.md`：只基于 context packet 做 release 风险分类。
+- `sync-candidate-review.md`：审查示例候选分支 `kt/sync/v4.8.0`，重点看登录态、二维码、WebUI auth、captcha/new-device。
+- `runtime-release-readiness.md`：拆开源码验证、镜像验证、API 推广、线上 smoke、回滚点。
+- `remote-dev-handoff.md`：输出 NAS 远程开发交接，不让 Codex 自动改代码。
+
+- [ ] **Step 5：确认 GREEN**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run typecheck
+```
+
+- [ ] **Step 6：提交**
+
+```powershell
+git -C D:\MyFiles\KT\mcp\ktWorkflow add prompts/napcat src/tools/napcatAutomation.prompts.ts src/selfTest.ts
+git -C D:\MyFiles\KT\mcp\ktWorkflow commit -m "feat: 增加NapCat自动化提示词包"
+```
+
+---
+
+### Task 3：确定性上游审计采集器
+
+**Files:**
+- Create: `D:\MyFiles\KT\mcp\ktWorkflow\src\tools\napcatAutomation.ts`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\tools\napcatAutomation.types.ts`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\selfTest.ts`
+
+- [ ] **Step 1：先写 hot-zone RED self-test**
+
+构造上游和 KT patch 同时命中 `packages/napcat-core/login/runtime.ts` 的输入，要求分类为 `manual-review`，reasonCodes 包含 `HOT_ZONE_CHANGED`。
+
+- [ ] **Step 2：确认 RED**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+```
+
+- [ ] **Step 3：实现 hot-zone 分类器**
+
+分类规则：
+
+- dry merge 冲突 -> `blocked` + `DRY_MERGE_CONFLICT`
+- 上游命中登录/二维码/WebUI/auth/OneBot/build hot zone -> `manual-review`
+- 上游文件与 KT fork patch 文件重叠 -> `manual-review`
+- 无 hot-zone、无重叠、无冲突 -> `safe-candidate`
+
+- [ ] **Step 4：生成只读审计命令**
+
+`buildNapcatUpstreamAudit(execute=false)` 只能生成只读命令：`git fetch`、`git diff --name-only`、`git merge-tree`、`git range-diff`。不能包含 `git merge`、`git push`、`docker build`、`kubectl`。
+
+- [ ] **Step 5：确认 GREEN**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run typecheck
+```
+
+- [ ] **Step 6：提交**
+
+```powershell
+git -C D:\MyFiles\KT\mcp\ktWorkflow add src/tools/napcatAutomation.ts src/tools/napcatAutomation.types.ts src/selfTest.ts
+git -C D:\MyFiles\KT\mcp\ktWorkflow commit -m "feat: 增加NapCat上游审计采集器"
+```
+
+---
+
+### Task 4：Codex CLI Runner 与 Artifact 捕获
+
+**Files:**
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\tools\napcatAutomation.ts`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\selfTest.ts`
+
+- [ ] **Step 1：先写 Codex 命令安全 RED self-test**
+
+测试 `buildNapcatCodexExecCommand()` 必须包含 `--ask-for-approval never`、`--json`、`--ephemeral`、`--output-schema`，且不能包含 `git push`、`kubectl`、`docker build`。
+
+- [ ] **Step 2：确认 RED**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+```
+
+- [ ] **Step 3：实现 Codex 命令封装**
+
+命令固定走 NAS 形态：
+
+```bash
+CODEX_HOME=/vol1/docker/kt-codex/home/.codex \
+codex exec \
+  --cd /vol1/docker/kt-codex/workspace/KT \
+  --profile-v2 automation \
+  --sandbox workspace-write \
+  --ask-for-approval never \
+  --json \
+  --ephemeral \
+  --output-schema /vol1/docker/kt-codex/workspace/KT/mcp/ktWorkflow/prompts/napcat/schemas/upstream-audit.schema.json \
+  --output-last-message "$ARTIFACT_DIR/codex-upstream-audit.md" \
+  - < "$CONTEXT_PACKET"
+```
+
+- [ ] **Step 4：实现 execute 模式**
+
+`execute=true && useCodex=true` 时写入 context packet，运行 Codex，捕获 JSONL，校验 zod schema。schema 失败时返回 `blocked` + `CODEX_SCHEMA_INVALID`，并保留原始输出 artifact。
+
+- [ ] **Step 5：确认 GREEN**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run typecheck
+```
+
+- [ ] **Step 6：提交**
+
+```powershell
+git -C D:\MyFiles\KT\mcp\ktWorkflow add src/tools/napcatAutomation.ts src/selfTest.ts
+git -C D:\MyFiles\KT\mcp\ktWorkflow commit -m "feat: 封装NapCat Codex审计执行器"
+```
+
+---
+
+### Task 5：MCP Tools 与 CLI Scripts
+
+**Files:**
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\types.ts`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\core\cli.ts`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\registerTools.ts`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\server.ts`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\core\constants.ts`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\package.json`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\README.md`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\selfTest.ts`
+
+- [ ] **Step 1：先写注册和 CLI parser RED self-test**
+
+要求 `registeredToolNames` 包含 `kt_napcat_upstream_audit`，`parseNapcatUpstreamAuditCliArgs()` 能解析 `--execute`、`--use-codex`、`--artifact-root`。
+
+- [ ] **Step 2：确认 RED**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+```
+
+- [ ] **Step 3：注册五个 MCP tools**
+
+- `kt_napcat_upstream_audit`
+- `kt_napcat_sync_candidate_review`
+- `kt_napcat_runtime_release_readiness`
+- `kt_napcat_remote_dev_handoff`
+- `kt_nas_codex_bootstrap_plan`
+
+所有 input schema 都要有默认值，且 `execute` 默认 `false`。
+
+- [ ] **Step 4：增加 package scripts**
+
+```json
+{
+  "napcat-upstream-audit": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --napcat-upstream-audit",
+  "napcat-sync-candidate-review": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --napcat-sync-candidate-review",
+  "napcat-runtime-release-readiness": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --napcat-runtime-release-readiness",
+  "nas-codex-bootstrap": "node --import ./node_modules/tsx/dist/loader.mjs src/server.ts --nas-codex-bootstrap"
+}
+```
+
+- [ ] **Step 5：确认 GREEN**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run napcat-upstream-audit -- --artifact-root .kt-workspace/test-artifacts/napcat-upstream-sync
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run typecheck
+```
+
+- [ ] **Step 6：提交**
+
+```powershell
+git -C D:\MyFiles\KT\mcp\ktWorkflow add package.json README.md src
+git -C D:\MyFiles\KT\mcp\ktWorkflow commit -m "feat: 接入NapCat自动化MCP工具和CLI"
+```
+
+---
+
+### Task 6：NAS Codex Bootstrap 工具
+
+**Files:**
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\tools\napcatAutomation.ts`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\src\selfTest.ts`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\README.md`
+
+- [ ] **Step 1：先写 Linux 路径 RED self-test**
+
+测试 dry-run 输出必须包含 `/vol1/docker/kt-codex/home/.codex`，且不能包含 `C:\Users`。
+
+- [ ] **Step 2：确认 RED**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+```
+
+- [ ] **Step 3：实现 dry-run**
+
+dry-run 只输出检查命令：
+
+```bash
+node --version
+corepack --version
+pnpm --version
+git --version
+docker --version
+codex --version
+test -d /vol1/docker/kt-codex/workspace/KT
+test -d /vol1/docker/kt-codex/home/.codex
+```
+
+- [ ] **Step 4：实现 execute 模式**
+
+`execute=true` 可以创建目录和安装运行环境，但不能 push、merge、deploy，也不能改业务仓库。敏感 Codex auth 只允许可信直连同步，不进入 Git、Jenkins artifact、Docker context 或日志。
+
+- [ ] **Step 5：确认 GREEN**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run nas-codex-bootstrap -- --dry-run
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run typecheck
+```
+
+- [ ] **Step 6：提交**
+
+```powershell
+git -C D:\MyFiles\KT\mcp\ktWorkflow add README.md src
+git -C D:\MyFiles\KT\mcp\ktWorkflow commit -m "feat: 增加NAS Codex环境引导工具"
+```
+
+---
+
+### Task 7：API 运行时 Artifact 元数据
+
+**Files:**
+- Modify: `D:\MyFiles\KT\Node\kt-template-online-api\scripts\napcat-desktop-cn-stage-build.mjs`
+- Modify: `D:\MyFiles\KT\Node\kt-template-online-api\test\modules\qqbot\napcat\napcat-desktop-cn-image.spec.ts`
+- Modify: `D:\MyFiles\KT\Node\kt-template-online-api\README.md`
+- Modify: `D:\MyFiles\KT\Node\kt-template-online-api\API.md`
+
+- [ ] **Step 1：先写 marker RED test**
+
+`napcat-desktop-cn-image.spec.ts` 要断言 stage-build 脚本包含：
+
+```ts
+expect(script).toContain('upstreamReleaseTag');
+expect(script).toContain('upstreamReleaseCommit');
+expect(script).toContain('napcatBaseImageDigest');
+expect(script).toContain('jenkinsBuildUrl');
+```
+
+- [ ] **Step 2：确认 RED**
+
+```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
+```
+
+- [ ] **Step 3：扩展 stage-build 参数和 marker**
+
+新增参数：
+
+- `--upstream-release-tag`
+- `--upstream-release-commit`
+- `--napcat-base-image-digest`
+- `--jenkins-build-url`
+
+写入 `fork-artifact.json`，和现有 `forkCommit`、`distSha256`、`napcatMjsSha256` 一起归档。
+
+- [ ] **Step 4：同步 README/API**
+
+文档必须写清楚：API 仓库不提交 `NapCat.Shell.zip`，生产镜像必须来自带完整 marker 的 staged context，base image 必须是 digest。
+
+- [ ] **Step 5：确认 GREEN**
+
+```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
+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
+```
+
+- [ ] **Step 6：提交**
+
+```powershell
+git -C D:\MyFiles\KT\Node\kt-template-online-api add scripts/napcat-desktop-cn-stage-build.mjs test/modules/qqbot/napcat/napcat-desktop-cn-image.spec.ts README.md API.md
+git -C D:\MyFiles\KT\Node\kt-template-online-api commit -m "feat: 扩展NapCat运行时构建元数据"
+```
+
+---
+
+### Task 8：API Jenkins 运行时推广 Override
+
+**Files:**
+- Create: `D:\MyFiles\KT\Node\kt-template-online-api\test\modules\qqbot\napcat\napcat-runtime-promotion.spec.ts`
+- Modify: `D:\MyFiles\KT\Node\kt-template-online-api\Jenkinsfile`
+- Modify: `D:\MyFiles\KT\Node\kt-template-online-api\k8s\prod\api.yaml`
+- Modify: `D:\MyFiles\KT\Node\kt-template-online-api\README.md`
+- Modify: `D:\MyFiles\KT\Node\kt-template-online-api\API.md`
+
+- [ ] **Step 1：先写 Jenkins/K8s RED test**
+
+测试 Jenkinsfile 必须有两个参数：
+
+- `QQBOT_NAPCAT_IMAGE_OVERRIDE`
+- `QQBOT_NAPCAT_DESKTOP_PROFILE_VERSION_OVERRIDE`
+
+并且 K8s deploy 阶段必须通过 `kubectl set env` 注入 `QQBOT_NAPCAT_IMAGE` 和 `QQBOT_NAPCAT_DESKTOP_PROFILE_VERSION`。
+
+- [ ] **Step 2：确认 RED**
+
+```powershell
+corepack pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api exec jest test/modules/qqbot/napcat/napcat-runtime-promotion.spec.ts --runTestsByPath --runInBand
+```
+
+- [ ] **Step 3：增加 Jenkins 参数**
+
+两个参数默认空字符串。为空时继续使用 manifest 默认值；非空时才覆盖运行时 env。
+
+- [ ] **Step 4：K8s deploy 阶段注入 env**
+
+在 `kubectl set image` 之后执行：
+
+```groovy
+def napcatImageOverride = params.QQBOT_NAPCAT_IMAGE_OVERRIDE?.trim()
+def napcatProfileOverride = params.QQBOT_NAPCAT_DESKTOP_PROFILE_VERSION_OVERRIDE?.trim()
+if (napcatImageOverride) {
+  runCmd("kubectl ${kubeConfigArg} ${namespaceArg} set env ${shellQuote("deployment/${deploymentName}")} ${shellQuote("QQBOT_NAPCAT_IMAGE=${napcatImageOverride}")}")
+}
+if (napcatProfileOverride) {
+  runCmd("kubectl ${kubeConfigArg} ${namespaceArg} set env ${shellQuote("deployment/${deploymentName}")} ${shellQuote("QQBOT_NAPCAT_DESKTOP_PROFILE_VERSION=${napcatProfileOverride}")}")
+}
+```
+
+- [ ] **Step 5：确认 GREEN**
+
+```powershell
+corepack pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api exec jest test/modules/qqbot/napcat/napcat-runtime-promotion.spec.ts test/modules/qqbot/napcat/napcat-desktop-cn-image.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
+```
+
+- [ ] **Step 6：提交**
+
+```powershell
+git -C D:\MyFiles\KT\Node\kt-template-online-api add Jenkinsfile k8s/prod/api.yaml README.md API.md test/modules/qqbot/napcat/napcat-runtime-promotion.spec.ts
+git -C D:\MyFiles\KT\Node\kt-template-online-api commit -m "feat: 支持NapCat运行时镜像参数推广"
+```
+
+---
+
+### Task 9：NapCatQQ 发布清单与 Jenkins 入口模板
+
+**Files:**
+- Create: `D:\MyFiles\KT\GitHub\NapCatQQ\ci\kt-runtime-release.md`
+- Create: `D:\MyFiles\KT\mcp\ktWorkflow\ci\jenkins\KT-NapCatQQ-Upstream-Sync.Jenkinsfile`
+- Create: `D:\MyFiles\KT\mcp\ktWorkflow\ci\jenkins\KT-NapCatQQ-Runtime-Release.Jenkinsfile`
+- Modify: `D:\MyFiles\KT\mcp\ktWorkflow\README.md`
+
+- [ ] **Step 1：写 NapCatQQ 发布清单**
+
+清单必须包含：origin 指向 KT 可写 fork/mirror、upstream 指向 `https://github.com/NapNeko/NapCatQQ.git`、运行 `pnpm install --frozen-lockfile`、聚焦登录测试、typecheck、build:webui/build:shell/build:framework、Docker 构建只走 ktWorkflow/Jenkins、不自动合并上游。
+
+- [ ] **Step 2：写上游审计 Jenkins 模板**
+
+模板只调用：
+
+```groovy
+sh '''
+  set -e
+  pnpm --dir /vol1/docker/kt-codex/workspace/KT/mcp/ktWorkflow run napcat-upstream-audit -- \
+    --execute \
+    --use-codex \
+    --artifact-root /vol1/docker/kt-codex/artifacts/napcat-upstream-sync
+'''
+```
+
+- [ ] **Step 3：写运行时发布 Jenkins 模板**
+
+模板调用 ktWorkflow readiness 和 API promotion 命令，不内联审计算法，不自动 merge，不自动 push。
+
+- [ ] **Step 4：验证模板**
+
+```powershell
+rg -n "napcat-upstream-audit|napcat-runtime-release-readiness|git merge|git push" D:\MyFiles\KT\mcp\ktWorkflow\ci\jenkins
+git -C D:\MyFiles\KT\mcp\ktWorkflow diff --check
+git -C D:\MyFiles\KT\GitHub\NapCatQQ diff --check
+```
+
+预期：能看到 ktWorkflow 调用，看不到自动 `git merge` 或 `git push`。
+
+- [ ] **Step 5：提交**
+
+```powershell
+git -C D:\MyFiles\KT\mcp\ktWorkflow add README.md ci/jenkins
+git -C D:\MyFiles\KT\mcp\ktWorkflow commit -m "docs: 增加NapCatQQ自动化Jenkins入口"
+git -C D:\MyFiles\KT\GitHub\NapCatQQ add ci/kt-runtime-release.md
+git -C D:\MyFiles\KT\GitHub\NapCatQQ commit -m "docs: 增加KT运行时发布清单"
+```
+
+---
+
+### Task 10：本地验证、审查和计划收口
+
+**Files:**
+- Modify: `D:\MyFiles\KT\TASKS.md`
+
+- [ ] **Step 1：跑本地验证**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run napcat-upstream-audit -- --artifact-root .kt-workspace/test-artifacts/napcat-upstream-sync
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run nas-codex-bootstrap -- --dry-run
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run self-test
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run typecheck
+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/napcat-runtime-promotion.spec.ts --runTestsByPath --runInBand
+corepack pnpm --dir D:\MyFiles\KT\Node\kt-template-online-api run typecheck
+git -C D:\MyFiles\KT\mcp\ktWorkflow diff --check
+git -C D:\MyFiles\KT\Node\kt-template-online-api diff --check
+git -C D:\MyFiles\KT\GitHub\NapCatQQ diff --check
+```
+
+- [ ] **Step 2：跑 KT global-review**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run global-review -- --content-scan-mode changed --max-findings-per-project 20
+```
+
+预期：`findings=[]`；如果是工具误报，修 ktWorkflow review 规则后复跑。
+
+- [ ] **Step 3：更新 TASKS**
+
+记录范围、关键词、验证证据：
+
+```md
+### 2026-06-24：NapCatQQ 上游同步与运行时发布流水线实施
+
+- 范围：mcp/ktWorkflow、Node/kt-template-online-api、GitHub/NapCatQQ。
+- 关键词：ktWorkflow NapCat 自动化、Codex CLI exec、上游 release 审计、NAS bootstrap、API runtime image/profile override。
+- 验证：self-test/typecheck/Jest/global-review/diff-check 通过；线上 Jenkins/NAS dry-run 等待下一阶段。
+```
+
+- [ ] **Step 4：清理历史产物预览**
+
+```powershell
+pnpm --dir D:\MyFiles\KT\mcp\ktWorkflow run cleanup-history -- --dry-run
+```
+
+如果 `deleted` 非空，执行 `--execute` 后复跑 dry-run，直到 `deleted=[]`。
+
+- [ ] **Step 5：提交 TASKS**
+
+```powershell
+git -C D:\MyFiles\KT add TASKS.md
+git -C D:\MyFiles\KT commit -m "docs: 记录NapCatQQ自动化实施结果"
+```
+
+---
+
+## 执行交接
+
+计划已保存到 `docs/superpowers/plans/2026-06-24-napcatqq-upstream-sync-runtime-release-pipeline-implementation-plan.zh-CN.md`。
+
+两种执行方式：
+
+1. **Subagent-Driven（推荐）**：每个 task 派一个新 subagent，父线程逐 task review，ktWorkflow/API/NapCatQQ 分仓提交。
+2. **Inline Execution**：本线程用 `superpowers:executing-plans` 批次执行，每个仓库边界做 review checkpoint。
+
+推荐选 **1**。这条线跨三个仓库和两个运行环境，用 task 级 subagent 更容易守住边界。