docs: 补充Codex CLI自动化提示词设计

2026-06-24 21:13:37 +08:00 · 2026-06-24 21:13:37 +08:00 · 992efc3a0c
commit 992efc3a0c
parent 62ddd768b3
2 changed files with 328 additions and 0 deletions
--- a/docs/superpowers/specs/2026-06-24-napcatqq-upstream-sync-runtime-release-pipeline-design.md
+++ b/docs/superpowers/specs/2026-06-24-napcatqq-upstream-sync-runtime-release-pipeline-design.md
@ -40,6 +40,7 @@ Primary upstream metadata sources:
 7. Keep production release completion tied to online smoke evidence, not Jenkins/K8s success alone.
 8. Install and configure a NAS-resident Codex CLI environment with a full KT workspace so remote development can continue when the laptop is unavailable.
 9. Run scheduled upstream audits on the NAS through Jenkins or a NAS service timer, never from the laptop.
+10. Version Codex CLI automation prompts for upstream audit, sync candidate review, release readiness review, and remote-development handoff.

 ## Non-Goals

@ -52,6 +53,7 @@ Primary upstream metadata sources:
 - Do not automatically migrate existing production accounts to a new runtime image without explicit release confirmation.
 - Do not store copied Codex secrets, sessions, logs, SQLite state, browser state, or auth files in Git or release artifacts.
 - Do not run unattended Codex agent sessions that modify code or merge upstream without explicit human approval.
+- Do not let Codex CLI automation read live credentials unless the prompt task explicitly needs them. Upstream release auditing should run from Git metadata and generated context packets.

 ## Repositories and Ownership

@ -141,6 +143,18 @@ Codex configuration parity is logical parity, not a byte-for-byte copy of the Wi

 The scheduled upstream audit should be deterministic shell/Jenkins work by default. Codex CLI is installed for remote development, review, and manual takeover, not for silent unattended code modification. If a future job invokes Codex non-interactively, it must run in a throwaway branch/worktree, emit a full artifact report, and require human review before commit, push, merge, or deployment.

+The intended automation split is:
+
+```text
+deterministic collector
+  -> context packet with git/GitHub/build facts
+  -> Codex CLI prompt for reasoning and classification
+  -> structured JSON/Markdown report
+  -> human-approved follow-up action
+```
+
+This gives Codex CLI the parts it is good at: reading diffs, explaining risk, checking hot-zone interactions, drafting candidate actions, and writing handoff reports. It does not make Codex the authority that silently mutates production state.
+
 ## Pipeline Overview

 ```mermaid
@ -235,6 +249,7 @@ CREATE_CANDIDATE_BRANCH=false by default
   - Write reports under `/vol1/docker/kt-codex/artifacts/napcat-upstream-sync/<timestamp>`.
   - Jenkins must archive the same reports.
   - Reports must include the NAS runner hostname, Codex CLI version when available, Git version, and workspace manifest revision.
+   - If Codex CLI automation is enabled, archive the exact prompt, context packet, JSONL event log, final response, and output schema validation result.

 ### Hot Zones

@ -382,6 +397,135 @@ CANARY_ACCOUNT_ID=<optional>

 The runtime release job must use a clean NAS job workspace rather than the long-lived remote development workspace. This prevents a remote Codex session and a Jenkins release from modifying the same checkout at the same time.

+## Codex CLI Automation Prompt Pack
+
+Implementation should add a versioned prompt pack under the API repository, for example:
+
+```text
+ci/codex-prompts/
+  napcat-upstream-audit.md
+  napcat-sync-candidate-review.md
+  napcat-runtime-release-readiness.md
+  napcat-remote-dev-handoff.md
+  schemas/
+    napcat-upstream-audit.schema.json
+    napcat-runtime-release-readiness.schema.json
+```
+
+Prompts are source-controlled because they are part of the automation contract. Secrets are never embedded in prompts. Each prompt must accept a generated context packet path or stdin payload and must produce a structured JSON result plus a short Markdown explanation.
+
+### `napcat-upstream-audit.md`
+
+Purpose: classify a new upstream latest release from already-collected facts.
+
+Prompt contract:
+
+```text
+You are auditing whether KT's NapCatQQ fork can safely sync an upstream NapNeko/NapCatQQ release.
+
+Inputs:
+- Upstream release metadata.
+- Last accepted upstream base.
+- KT fork branch and head commit.
+- Upstream changed file list and commit list.
+- KT fork patch file list and commit list.
+- Hot-zone file list.
+- Dry merge or range-diff output.
+
+Rules:
+- Do not run merge, commit, push, deploy, or edit files.
+- Do not infer success from missing data.
+- Classify exactly one of: safe-candidate, manual-review, blocked.
+- Explain every reasonCode with file-level evidence.
+- Recommend next action: no-op, create candidate branch, request human review, or block.
+
+Output:
+- JSON matching ci/codex-prompts/schemas/napcat-upstream-audit.schema.json.
+- A concise Markdown summary safe for Jenkins artifacts.
+```
+
+Recommended command shape on 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 ci/codex-prompts/schemas/napcat-upstream-audit.schema.json \
+  --output-last-message "$ARTIFACT_DIR/codex-upstream-audit.md" \
+  - < "$CONTEXT_PACKET"
+```
+
+`workspace-write` is used so Codex can write only the requested report files under the job artifact directory. The prompt still forbids source edits and push/merge/deploy actions.
+
+### `napcat-sync-candidate-review.md`
+
+Purpose: review a generated `kt/sync/<release-tag>` candidate branch before any merge.
+
+Prompt contract:
+
+```text
+Review the candidate branch against KT's NapCat login/runtime requirements.
+
+Must inspect:
+- login service reset behavior
+- QR refresh and stale QR handling
+- WebUI login runtime state
+- captcha and new-device flow boundaries
+- package/build output structure
+- test delta and missing coverage
+
+Must not:
+- edit files
+- commit
+- push
+- mark production ready
+
+Output:
+- Critical/Important findings first.
+- Required tests before merge.
+- Whether this candidate can proceed to manual code review.
+```
+
+### `napcat-runtime-release-readiness.md`
+
+Purpose: decide whether a built runtime image can be promoted to API.
+
+Inputs:
+
+- NapCatQQ test/typecheck/build summaries.
+- `fork-artifact.json`.
+- Docker image inspect output.
+- `verify.sh` output.
+- API integration test output.
+- planned runtime image/profile values.
+
+Output must separate:
+
+- source validation
+- image validation
+- API promotion readiness
+- online smoke readiness
+- rollback pointer
+
+### `napcat-remote-dev-handoff.md`
+
+Purpose: create a safe handoff when a human opens NAS Codex CLI for remote development.
+
+It should summarize:
+
+- active branch and dirty status for each repo
+- relevant artifact directories
+- latest Jenkins job state
+- current blockers
+- exact commands that are safe to run next
+
+It must not ask Codex to modify files automatically.
+
 ## API Promotion Contract

 The API Jenkinsfile should gain optional parameters:
@ -433,6 +577,8 @@ sequenceDiagram
 - NAS runner lacks Node, pnpm, Docker, Git, Codex, or KT workspace manifest: mark setup incomplete and do not enable the scheduled trigger.
 - NAS Codex auth is missing: remote development is unavailable until interactive login or trusted auth-file sync completes; deterministic Jenkins audits may still run if they do not need Codex auth.
 - NAS Codex config drifts from the generated template: fail the remote-development smoke and require config regeneration.
+- Codex CLI automation prompt or schema is missing: deterministic audit may still run, but AI-assisted classification is marked unavailable.
+- Codex CLI output does not match the required schema: mark the audit `blocked` and archive the raw output for review.
 - Laptop is offline or away from the LAN: scheduled audits and runtime release jobs must continue on NAS.
 - Upstream release has no resolvable tag commit: mark `blocked`.
 - Fork writable remote points to upstream: fail before push.
@ -499,6 +645,23 @@ Remote development smoke:
 - A dry-run upstream audit can write reports into `/vol1/docker/kt-codex/artifacts`.
 - No laptop-only Windows path remains in the NAS `config.toml`.

+Codex automation prompt smoke:
+
+```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 ci/codex-prompts/schemas/napcat-upstream-audit.schema.json \
+  --output-last-message /vol1/docker/kt-codex/artifacts/smoke/codex-upstream-audit.md \
+  - < /vol1/docker/kt-codex/artifacts/smoke/context-packet.md
+```
+
+Expected result: schema-valid JSON, no source changes, and a Markdown report in the artifact directory.
+
 ### Runtime Release Job

 NapCatQQ:
@ -542,6 +705,7 @@ Online:
 - NAS has a resident Codex CLI and full KT workspace environment for scheduled audits and remote development.
 - A scheduled audit detects upstream latest releases and writes safe reports.
 - The scheduled audit runs from NAS service/Jenkins, not from the laptop.
+- Codex CLI automation prompts are versioned, schema-validated, and archived with every AI-assisted audit.
 - Upstream sync never auto-merges into KT maintenance branches.
 - Hot-zone conflicts are blocked or marked for manual review.
 - Runtime images are built from approved fork refs and verified inside containers.
--- a/docs/superpowers/specs/2026-06-24-napcatqq-upstream-sync-runtime-release-pipeline-design.zh-CN.md
+++ b/docs/superpowers/specs/2026-06-24-napcatqq-upstream-sync-runtime-release-pipeline-design.zh-CN.md
@ -40,6 +40,7 @@ kt-napcat-desktop-cn:<profile>
 7. 线上完成标准必须包含真实 smoke，不把 Jenkins/K8s 成功当成功能闭环。
 8. 在 NAS 上安装并配置常驻 Codex CLI 与 KT 全量 workspace，保证笔记本不在线时仍可远程开发。
 9. 上游定时审计必须跑在 NAS 的 Jenkins 或 NAS 服务定时器中，不能跑在笔记本。
+10. 把 Codex CLI 自动化提示词版本化，覆盖上游审计、候选分支审查、运行时发布就绪审查和远程开发交接。

 ## 非目标

@ -52,6 +53,7 @@ kt-napcat-desktop-cn:<profile>
 - 不在没有明确确认时自动迁移线上账号到新运行时镜像。
 - 不把同步到 NAS 的 Codex secrets、sessions、logs、SQLite 状态、浏览器状态或 auth 文件写入 Git 或 release artifact。
 - 不运行会在无人值守状态下修改代码或合并 upstream 的 Codex agent。
+- 不让 Codex CLI 自动化读取实时凭据，除非该提示词任务明确需要。上游 release 审计应只基于 Git 元数据和生成的 context packet。

 ## 仓库职责

@ -141,6 +143,18 @@ Codex 配置一致指“逻辑一致”，不是把 Windows profile 原样复制

 上游定时审计默认只运行确定性的 shell/Jenkins 逻辑。Codex CLI 安装的目的，是远程开发、人工审查和接管，不是默默无人值守改代码。未来如果需要非交互调用 Codex，也必须在一次性分支/worktree 中运行，产出完整 artifact，并在 commit、push、merge 或 deployment 前要求人工审查。

+自动化分工如下：
+
+```text
+确定性采集脚本
+  -> 包含 git/GitHub/build 事实的 context packet
+  -> Codex CLI 提示词负责推理和分类
+  -> 结构化 JSON/Markdown 报告
+  -> 人工确认后的后续动作
+```
+
+这样 Codex CLI 做它擅长的部分：读 diff、解释风险、检查 hot-zone 交互、草拟候选动作、写交接报告。它不成为无人值守修改生产状态的最终权威。
+
 ## 流水线总览

 ```mermaid
@ -235,6 +249,7 @@ CREATE_CANDIDATE_BRANCH=false
   - 报告写入 `/vol1/docker/kt-codex/artifacts/napcat-upstream-sync/<timestamp>`。
   - Jenkins 归档同一份报告。
   - 报告必须包含 NAS runner hostname、可用时的 Codex CLI version、Git version、workspace manifest revision。
+   - 启用 Codex CLI 自动化时，必须归档精确 prompt、context packet、JSONL event log、final response 和 output schema 校验结果。

 ### Hot Zone

@ -382,6 +397,135 @@ CANARY_ACCOUNT_ID=<可选>

 运行时发布 job 必须使用干净的 NAS job workspace，而不是长期远程开发 workspace，避免远程 Codex 会话和 Jenkins 发布同时修改同一个 checkout。

+## Codex CLI 自动化提示词包
+
+实现阶段应在 API 仓库增加版本化提示词包，例如：
+
+```text
+ci/codex-prompts/
+  napcat-upstream-audit.md
+  napcat-sync-candidate-review.md
+  napcat-runtime-release-readiness.md
+  napcat-remote-dev-handoff.md
+  schemas/
+    napcat-upstream-audit.schema.json
+    napcat-runtime-release-readiness.schema.json
+```
+
+提示词属于自动化契约，所以需要进 Git。secret 绝不写进 prompt。每个 prompt 接收生成好的 context packet 路径或 stdin payload，并输出结构化 JSON 加短 Markdown 解释。
+
+### `napcat-upstream-audit.md`
+
+用途：根据已采集事实，对上游 latest release 做同步风险分类。
+
+提示词契约：
+
+```text
+You are auditing whether KT's NapCatQQ fork can safely sync an upstream NapNeko/NapCatQQ release.
+
+Inputs:
+- Upstream release metadata.
+- Last accepted upstream base.
+- KT fork branch and head commit.
+- Upstream changed file list and commit list.
+- KT fork patch file list and commit list.
+- Hot-zone file list.
+- Dry merge or range-diff output.
+
+Rules:
+- Do not run merge, commit, push, deploy, or edit files.
+- Do not infer success from missing data.
+- Classify exactly one of: safe-candidate, manual-review, blocked.
+- Explain every reasonCode with file-level evidence.
+- Recommend next action: no-op, create candidate branch, request human review, or block.
+
+Output:
+- JSON matching ci/codex-prompts/schemas/napcat-upstream-audit.schema.json.
+- A concise Markdown summary safe for Jenkins artifacts.
+```
+
+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 ci/codex-prompts/schemas/napcat-upstream-audit.schema.json \
+  --output-last-message "$ARTIFACT_DIR/codex-upstream-audit.md" \
+  - < "$CONTEXT_PACKET"
+```
+
+这里用 `workspace-write` 是为了允许 Codex 只写 job artifact 目录下的报告文件。prompt 仍禁止源码编辑、push、merge 和 deployment。
+
+### `napcat-sync-candidate-review.md`
+
+用途：在任何 merge 之前审查生成的 `kt/sync/<release-tag>` 候选分支。
+
+提示词契约：
+
+```text
+Review the candidate branch against KT's NapCat login/runtime requirements.
+
+Must inspect:
+- login service reset behavior
+- QR refresh and stale QR handling
+- WebUI login runtime state
+- captcha and new-device flow boundaries
+- package/build output structure
+- test delta and missing coverage
+
+Must not:
+- edit files
+- commit
+- push
+- mark production ready
+
+Output:
+- Critical/Important findings first.
+- Required tests before merge.
+- Whether this candidate can proceed to manual code review.
+```
+
+### `napcat-runtime-release-readiness.md`
+
+用途：判断已构建运行时镜像是否可以推广到 API。
+
+输入：
+
+- NapCatQQ test/typecheck/build 摘要。
+- `fork-artifact.json`。
+- Docker image inspect 输出。
+- `verify.sh` 输出。
+- API integration test 输出。
+- 计划发布的 runtime image/profile 值。
+
+输出必须拆开：
+
+- source validation
+- image validation
+- API promotion readiness
+- online smoke readiness
+- rollback pointer
+
+### `napcat-remote-dev-handoff.md`
+
+用途：人工打开 NAS Codex CLI 远程开发前，生成安全交接。
+
+需要总结：
+
+- 每个仓库的当前分支和 dirty 状态。
+- 相关 artifact 目录。
+- 最新 Jenkins job 状态。
+- 当前 blocker。
+- 下一步可安全执行的精确命令。
+
+它不能要求 Codex 自动修改文件。
+
 ## API 推广契约

 API Jenkinsfile 增加可选参数：
@ -433,6 +577,8 @@ sequenceDiagram
 - NAS runner 缺 Node、pnpm、Docker、Git、Codex 或 KT workspace manifest：标记 setup incomplete，不启用定时触发。
 - NAS Codex auth 缺失：远程开发不可用，直到交互式登录或可信 auth 文件同步完成；如果确定性 Jenkins 审计不需要 Codex auth，则审计仍可运行。
 - NAS Codex config 与生成模板漂移：remote-development smoke 失败，要求重新生成配置。
+- Codex CLI 自动化 prompt 或 schema 缺失：确定性审计仍可运行，但 AI 辅助分类标记为 unavailable。
+- Codex CLI 输出不符合 schema：审计标记 `blocked`，并归档原始输出供人工查看。
 - 笔记本离线或不在局域网：定时审计和运行时发布仍必须在 NAS 继续运行。
 - 上游 release tag 无法解析 commit：标记 `blocked`。
 - fork 可写 remote 指向上游：push 前失败。
@ -499,6 +645,23 @@ pnpm --dir mcp/ktWorkflow run self-test
 - 上游审计 dry-run 能把报告写入 `/vol1/docker/kt-codex/artifacts`。
 - NAS `config.toml` 中没有笔记本 Windows-only 路径。

+Codex 自动化提示词 smoke：
+
+```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 ci/codex-prompts/schemas/napcat-upstream-audit.schema.json \
+  --output-last-message /vol1/docker/kt-codex/artifacts/smoke/codex-upstream-audit.md \
+  - < /vol1/docker/kt-codex/artifacts/smoke/context-packet.md
+```
+
+预期结果：JSON 符合 schema、源码无改动、Markdown 报告写入 artifact 目录。
+
 ### 运行时发布 Job

 NapCatQQ：
@ -542,6 +705,7 @@ docker tag "$IMMUTABLE_TAG" "$PROMOTION_TAG"
 - NAS 有常驻 Codex CLI 和 KT 全量 workspace 环境，可支撑定时审计和远程开发。
 - 定时审计能发现上游 latest release 并生成安全报告。
 - 定时审计从 NAS 服务/Jenkins 运行，不从笔记本运行。
+- Codex CLI 自动化提示词已版本化、schema 校验，并随每次 AI 辅助审计归档。
 - 上游同步不会自动合并进 KT 维护分支。
 - hot-zone 冲突会阻断或进入人工审查。
 - 运行时镜像只从已确认 fork ref 构建，并经过容器内 verify。