KTeam/ktworkflow-mcp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
c7a74bda61
ktworkflow-mcp/README.md

225 lines
30 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# KT Workflow MCP
`ktWorkflow` 是 KT 工作区的可复用 MCP 能力包，用 TypeScript 封装工具入参、项目别名和返回结构，用来把根目录 `AGENTS.md` 的硬规则、`SKILLS.md` 的工作流索引、`TASKS.md` 的上下文记录和 `docs/` 的详细流程变成可调用工具。当前版本：`0.6.2`。
## 能力边界
- 读取 KT 工作区紧凑上下文：项目清单、硬性规则、skill registry、标准 skill 包索引、历史关键词、最近任务记录和详细文档入口；需要全量文档时显式开启。
- 读取 Obsidian 索引上下文：从 `docs/obsidian` 的总入口、模块索引、文档矩阵、工作流关系和 Canvas 摘要中按模块或关键词定位文档，并返回 `codeAnchors` / `ruleAnchors` 锚定到现有项目别名、源码路径、相关规则文档和后续上下文工具。
- 检查子项目环境：Git/SVN、包管理器、Node 版本、env 文件、Git 状态。
- 生成防偏差工作包：把开工前检查、禁止项、风险扫描、验证计划汇总成一份可执行清单。
- 生成验证建议：按后端、前端、样式、页面、部署、数据库、MCP 等变更类型给出轻量验证命令和迁移核验要点。
- 固化改动后 review：验证计划和提交清单都会提醒执行 `kt_global_code_review` / `pnpm run global-review`，并以 KT 全局审查证据作为唯一代码审查门禁。
- 生成任务收尾包：把状态、验证计划、可选验证执行、全局 review 和历史清理收成一份结果。
- 生成大方向完结闭环审计：确认开发目标、测试证据、KT 全局 review、问题记录、稳定解法和 ktWorkflow 升级是否齐备。
- 生成页面测试用例：内置“先写用例、可视化证据、事不过三”的测试闭环。
- 生成接口测试计划：接口改动后输出真实调用命令和统一返回结构断言。
- 生成业务链路测试计划：固化 Admin 登录、博客 CRUD、QQBot 扫码/自动回复、更新登录 SSE、FFLogs 命令、系统日志可视化、Web/Playground 回跳。
- 静态检查 NapCat 设备身份护栏：确认 API 仍保留 QQNT 可见 hostname、实体 OUI 风格 MAC、QQNT `machine-info` 写入、持久化 runtime dir 和 `DB_TIMEZONE` 默认值。
- 生成 NapCatQQ 上游同步与 runtime 发布自动化入口：MCP/CLI 默认 dry-run，覆盖 upstream audit、sync candidate review、runtime readiness、remote dev handoff 和 NAS Codex bootstrap plan；upstream audit 在显式 `execute=true` 且 `useCodex=true` 时可运行 Codex，NAS Codex bootstrap 在显式 `execute=true` 时只返回目录准备、nvm 管理的 Node 22.14.0 / pnpm 10.28.2 / Codex CLI 安装计划，不复制 secrets、不写 systemd、不触发发布。
- 生成卡点固化记录：把超时、卡进程、远程命令误写、重复失败整理成“问题点 / 稳定解法 / 后续入口 / 验证证据”，避免原样重试。
- 生成改动文档同步计划：按变更文件自动提示需要同步的 README、API、AGENTS、docs、Obsidian、skill 和 ktWorkflow 入口；MCP 不可用时用 `pnpm run change-doc-sync -- --project <project>` 作为 CLI fallback。
- 生成多仓库提交/推送计划：按仓库分组、建议提交信息、列出提交和推送前检查。
- 生成远程只读健康检查和数据库同步安全向导：覆盖飞牛 NAS 服务探测、GTID、`.kt-workspace/db-sync` 转储、备份库和行数校验。
- 生成或执行部署观测：把 Jenkins build、`build.xml` SCM revision/top-level result、日志尾部、K8s Deployment、Pod、`/health/runtime` 和任务 smoke 汇总成 `.kt-workspace/test-artifacts/deploy-observation` 下的运行态证据；Jenkins 状态优先取日志尾部最终 `Finished:`，没有最终行时回退到 `build.xml` 的顶层 result，result 为空才视为未完成。
- 生成专项组件工作流：KtTable、BlogArgon、AdminAuth、QQBot、FF14Plugin、NapCatLogin、SystemLog、Knife4jSwagger、FnosK8s 的防踩坑清单和验证点。
- 生成验证进程清理计划：按项目路径和端口给出 Debian Bash 的 `ps` / `ss` 只读检查命令，不直接杀进程。
- 清理历史产物：统一治理 `.kt-workspace` 下的测试/验证产物，按目录最近修改时间只保留最近 3 轮，模板目录永久保留；CLI 默认 dry-run，真实清理必须显式传 `--execute`。
- 检查 env 策略和变更风险：区分后端真实 env 与前端客户端 `.env*`，提醒锁文件、核心表格组件、API 时间序列化 KtDateTime 列/DTO 装饰器入口、部署链路和 Vue TSX 插槽写法等高风险改动。
- 全局 CodeReview 只读扫描：覆盖多仓 Git/敏感信息/冲突/调试输出、QQBot/NapCat 已固化回归点、Blog Live2D 语义 consumer 与反混淆清单、根目录生成物和 `TASKS.md` 结构。Live2D 旧 global 发布迁移态规则已退役；永久约束由全树 `@ts-nocheck`/短名 consumer 检查和独立 runtime coverage audit 共同承担。默认只扫描变更文件，并用 `--untracked-files=all` 展开未跟踪目录；`docs/`、README、Markdown 与 skill 只作为文档证据，不参与 runtime-debug 判定，源码目录中的 JSON 仍受扫描；任何文件改动后都要运行。
- 生成或写入 `TASKS.md` 最近记录：默认 `dryRun=true`，确认后再落盘。
- 生成提交前检查清单：校验 KT commit message 约定。
## 安装
```bash
cd /home/yemu2/KT/mcp/ktWorkflow
pnpm install
pnpm run typecheck
pnpm run self-test
pnpm run obsidian-context -- --module ktWorkflow
pnpm run obsidian-validate
pnpm run obsidian-sync
pnpm run change-doc-sync -- --project root
pnpm run workstream-closeout -- --title "发布闭环" --verification "Jenkins SUCCESS" --doc-sync "无需文档更新" --cleanup "cleanup-history dry-run deleted=0" --cleanup-final-deleted 0 --review "global-review findings=0" --problem "无新卡点" --solution "无新增稳定解法"
pnpm run napcat-upstream-audit -- --artifact-root .kt-workspace/test-artifacts/napcat-upstream-sync
pnpm run napcat-sync-candidate-review
pnpm run napcat-runtime-release-readiness
pnpm run napcat-remote-dev-handoff
pnpm run nas-codex-bootstrap
pnpm run napcat-device-profile-check
pnpm run cleanup-history -- --dry-run
pnpm run cleanup-history -- --execute
pnpm run deploy-observation -- --project api --job KT-Template/KT-Template-API/main --namespace kt-prod --deployment kt-template-online-api --container api --health-url http://127.0.0.1:48085/health/runtime --smoke "curl -fsS --max-time 8 http://127.0.0.1:48085/health/runtime"
pnpm run admin-login -- --url http://127.0.0.1:5999/#/auth/login
```
如果 Debian shell 内的 Node/npm/pnpm 版本不符合 `engines`，先执行 `nvm ls` 查看已安装版本，再用 `nvm use <version>` 切换到目标版本；不要引用 Windows Node 或 `/mnt/*` 下的平台依赖。
## Jenkins 入口模板
- `ci/jenkins/KT-NapCatQQ-Upstream-Sync.Jenkinsfile` 是 NapCatQQ 上游审计入口，默认只调用 ktWorkflow 的 `napcat-upstream-audit` dry-run，保留人工审查边界。
- Codex 上游审计必须同时设置 `RUN_CODEX_AUDIT=true` 并填写 `CONFIRM_CODEX_WORKSPACE_WRITE=RUN_CODEX_WORKSPACE_WRITE_AUDIT`；这是因为 Codex runner 使用 workspace-write sandbox，不能作为定时任务默认行为。
- `ci/jenkins/KT-NapCatQQ-Runtime-Release.Jenkinsfile` 是运行时发布入口，先调用 `napcat-runtime-release-readiness`，再通过显式参数触发运行时镜像构建和 API promotion；下游 job 使用白名单 choice，避免任意 Jenkins job 名被传入，并把 upstream release commit / NapCat base image digest 透传到镜像构建证据。
- `ci/jenkins/KT-NapCatQQ-Runtime-Image-Build.Jenkinsfile` 是运行时镜像构建下游，只从 NAS 本地裸仓库 clone 经过审查的 NapCatQQ fork ref，构建 `NapCat.Shell`，先要求 NAS API 工作区 clean，并从 Jenkins API main checkout 的只读 `.git` reference 做 `fetch + merge --ff-only`，再调用 API 仓库 `scripts/napcat-desktop-cn-stage-build.mjs` 生成 staged context，执行 `docker build` 和容器内 `/ci/napcat-desktop-cn/verify.sh`；由于该下游需要访问挂载的宿主 Docker socket，内层 runner 固定 `--user 0:0`，镜像验证容器按账号容器同款 `SYS_ADMIN` / seccomp / apparmor 参数和 `NAPCAT_REQUIRE_DEVICE_PROFILE=1` 启动，但它不触发 API promotion、不执行 `kubectl`、不合并或推送 Git。
- 生产 API promotion 除了 `PROMOTE_API_RUNTIME=true` 和明确 image/profile 参数外，还必须填写 `CONFIRM_API_PROMOTION_TARGET=PROMOTE_KT_TEMPLATE_API_MAIN`。
- 三个模板默认使用 NAS 工作区 `/vol1/docker/kt-codex/workspace/KT`，运行证据落在 `/vol1/docker/kt-codex/artifacts` 下。
- 模板只保存入口和参数形状，不记录 Jenkins credential、Token、SSH key 或其他真实凭据。
## MCP 客户端配置
Windows 上的 stdio MCP 客户端通过 `wsl.exe` 启动 Debian Bash；Node、依赖和工作区路径都留在 WSL2：
```json
{
"mcpServers": {
"ktWorkflow": {
"command": "wsl.exe",
"args": [
"-d",
"Debian",
"--",
"bash",
"-lc",
"cd /home/yemu2/KT/mcp/ktWorkflow && exec env KT_WORKSPACE_ROOT=/home/yemu2/KT node --import ./node_modules/tsx/dist/loader.mjs src/server.ts"
]
}
}
}
```
## 工具列表
| 工具 | 用途 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `kt_read_context` | 读取 KT 根目录紧凑上下文和最近任务记录，支持显式读取完整文档 |
| `kt_inspect_project` | 检查子项目仓库、包管理器、Node、env 和 Git 状态 |
| `kt_inspect_all_projects` | 一次性检查所有 KT 项目，适合多仓库联动任务 |
| `kt_guardrails` | 按任务类型生成开工、改动、禁止项和验证约束 |
| `kt_prepare_task` | 生成完整 work packet，降低开工偏差 |
| `kt_suggest_verification` | 生成轻量验证命令和注意事项 |
| `kt_create_page_test_case` | 生成页面级可视化测试用例 |
| `kt_api_test_plan` | 生成接口真实调用测试计划 |
| `kt_cleanup_history` | 清理 `.kt-workspace` 历史测试/验证产物，默认预览，执行时只保留最近 3 轮 |
| `kt_cleanup_process_plan` | 生成验证进程清理检查命令 |
| `kt_env_policy` | 检查 env 文件现状和提交策略 |
| `kt_risk_scan` | 扫描当前或传入变更文件的偏差风险 |
| `kt_global_code_review` | 对 KT 全部子仓库做只读全局 CodeReview 扫描，默认仅深扫变更文件 |
| `kt_finish_task` | 生成任务收尾包，可选执行验证和历史清理 |
| `kt_workstream_closeout` | 生成大方向完结闭环审计，检查测试证据、文档同步、历史清理、KT 全局 review、问题记录、稳定解法和 ktWorkflow 升级 |
| `kt_workflow_loop_audit` | 审计上下文锚定、测试证据、文档同步、历史清理最终 `deleted=0`、问题固化、ktWorkflow 升级和 KT 全局 review |
| `kt_change_doc_sync` | 根据改动路径生成 README/API/AGENTS/docs/Obsidian/skill/ktWorkflow 文档同步清单 |
| `kt_commit_plan` | 生成多仓库提交计划、建议 commit message 和检查项 |
| `kt_push_plan` | 生成多仓库推送计划和远程异常提醒 |
| `kt_business_test_plan` | 生成固化业务链路测试计划，包含 QQBot SSE、FFLogs 和系统日志 |
| `kt_napcat_upstream_audit` | 生成或执行 NapCatQQ upstream release 审计，默认 dry-run，显式 `execute/useCodex` 后才运行 Codex |
| `kt_napcat_sync_candidate_review` | 生成 NapCat sync candidate review 的 prompt/context/只读命令骨架，Task 5 不执行 Codex 或 Git 写操作 |
| `kt_napcat_runtime_release_readiness` | 生成 NapCat runtime release readiness 的 prompt/context/只读检查骨架，不自动构建或发布 |
| `kt_napcat_remote_dev_handoff` | 生成 NapCat 自动化远程开发 handoff 的 prompt/context 骨架，不创建线程或同步仓库 |
| `kt_nas_codex_bootstrap_plan` | 生成可信 NAS Codex bootstrap dry-run/execute command plan；execute 只规划目录准备和 nvm 管理的 Node/pnpm/Codex 安装，不复制 secrets、不写 systemd |
| `kt_napcat_device_profile_check` | 静态检查 API NapCat 设备身份护栏，覆盖 hostname、MAC、`machine-info`、runtime dir 和 DB timezone |
| `kt_blocker_resolution` | 生成或写入卡点固化记录，提醒停止原样重试 |
| `kt_remote_health_check` | 生成或执行远程只读健康检查命令 |
| `kt_deploy_observation` | 生成或执行 API 发布后的部署观测，汇总 Jenkins SCM revision、K8s、Pod、`/health/runtime` 和任务 smoke 证据 |
| `kt_db_sync_plan` | 生成数据库同步安全向导 |
| `kt_component_workflow` | 输出专项组件/链路防踩坑工作流，包含 FnosK8s |
| `kt_obsidian_context` | 读取 Obsidian 索引上下文，支持按 `module` / `query` 返回模块页、文档矩阵、Canvas 摘要、代码锚点和相关规则文档 |
| `kt_obsidian_validate` | 只读校验 Obsidian JSON、Canvas、Base、Wiki 链接、Markdown 相对链接和旧引用 |
| `kt_obsidian_sync` | 审计 Obsidian 工作流入口、书签、核心插件、忽略目录和校验结果 |
| `kt_append_task_record` | 预览或写入 `TASKS.md` 最近记录 |
| `kt_commit_checklist` | 生成提交前检查清单并校验 commit message |
## 可复用脚本
| 脚本 | 用途 |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `pnpm run admin-login` | 使用可见 Edge 打开 Admin 登录页，填写账号密码，拖动滑块，保存登录态和截图。默认账号来自初始化数据 `admin/123456`，生产或个人账号用 `KT_ADMIN_USERNAME` / `KT_ADMIN_PASSWORD` 或 CLI 参数覆盖。 |
| `pnpm run global-review` | 对 KT 子仓库和根治理文件做只读审查：默认深扫当前变更，检查凭据/调试/冲突/运行态专项回归，强制 `TASKS.md` 四段结构与三条最近记录，并约束 Live2D 反混淆 ledger 使用连续单行切片索引、禁止执行流水、单行不超过 520 字且总量不超过 128 KiB。 |
| `pnpm run napcat-upstream-audit` | 默认 dry-run 输出 NapCatQQ 上游 release 审计分类、只读 Git 命令和 artifact 路径；显式 `--execute --use-codex` 才运行 Codex。 |
| `pnpm run napcat-sync-candidate-review` | 输出 sync candidate review 的 prompt/context/只读命令骨架，不执行 Codex 或 Git 写操作。 |
| `pnpm run napcat-runtime-release-readiness` | 输出 runtime release readiness 的 prompt/context/只读检查骨架，不构建镜像、不调用 kubectl、不发布。 |
| `pnpm run napcat-remote-dev-handoff` | 输出远程开发 handoff 的 prompt/context 骨架，不创建线程、不同步仓库、不执行 Codex。 |
| `pnpm run nas-codex-bootstrap` | 输出可信 NAS Codex bootstrap dry-run plan；传 `--execute` 只生成目录准备和 nvm 管理的 Node/pnpm/Codex 安装命令计划，不真实执行 SSH、不复制 secrets、不写 systemd。 |
| `pnpm run napcat-device-profile-check` | 静态检查 API NapCat 设备身份护栏，防止回退到未知设备风险配置。 |
| `pnpm run deploy-observation` | 默认 dry-run 输出只读 NAS 观测命令；传 `--execute` 时执行 Jenkins/K8s/health/smoke 观测并写入 `.kt-workspace/test-artifacts/deploy-observation`。 |
| `pnpm run obsidian-context` | 输出 Obsidian 索引上下文；可传 `--module Admin`、`--query QQBot`、`--max-documents 10`。 |
| `pnpm run obsidian-validate` | 校验 KT Obsidian vault 结构和链接；默认 warning 不让脚本失败，需要严格模式时传 `--fail-on-warnings`。 |
| `pnpm run obsidian-sync` | 审计 Obsidian 工作流入口是否连通，并联动执行 validate。 |
| `pnpm run cleanup-history` | 预览 `.kt-workspace` 测试/验证历史产物清理；真实清理用 `pnpm run cleanup-history -- --execute`，只保留最近 3 轮，并保留模板、活动运行输入和 `.kt-workspace/toolchains`。 |
| `pnpm run test:unit` | 只运行显式登记的 Node 22 单元测试，不触发完整 evidence、Obsidian 或多仓集成构造。 |
| `pnpm run test:live2d` | 运行 Live2D analyzer、review schema、S192-S217 历史切片、完整调用目录、implementation-target、module migration、variable/identifier 与 runtime coverage 独立测试。 |
| `pnpm run test:integration` | 只运行 workflow closeout、Obsidian、cleanup、doc-sync 和 synthetic evidence writer 集成测试。 |
| `pnpm run self-test` | 由 16 行薄入口顺序运行三个显式测试索引；全部通过后只构造一次真实 evidence，再写 36-tool 成功摘要。 |
| `pnpm run validate-deobfuscation-anchors` | 校验反混淆 `renames-*.json` 的 `sourceAnchors` 是否全部存在于指定 min.js 源码切片，防止 evidence JSON 和源码锚点漂移。 |
| `pnpm run audit-live2d-minjs` | 从原始 Blog `live2d.min.js` 生成基于 SHA/UTF-8 byte span/SyntaxKind 的 627 个函数 ID 与 1411 个稳定调用 ID；读取 `function-name-decisions.json` 和可选 `call-resolutions.json`，分别输出完整函数目录与不改写 raw exact/unresolved 统计的调用 review 目录到 `.kt-workspace/deobfuscate/`。`--call-decisions` / `--call-review-catalog-output` 可覆盖调用输入输出；`--review-packet` 继续校验函数 packet 的 order/name/span/SyntaxKind/ID/snippet hash。 |
| `pnpm run audit-live2d-module-splits` | 从已闭合的函数/调用目录重算源码 binding、bootstrap、SCC、coupling、module draft 与三等分 209/209/209 owner review pack；生成 pack 前逐项验证 implementation module 可解析且 runtime symbol 真实存在，拒绝仅类型声明或已删除 target；传 `--final-output docs/live2d-deobfuscation/module-splits.json` 时严格校验三份 review seal，并生成 627 行 reviewed manifest。 |
| `pnpm run draft-live2d-module-migrations` | 从 immutable source、reviewed module manifest 和函数决策生成 source/implementation AST 双哈希迁移 draft；必须传 `--review-evidence`，需要重建全部 567 个 owned function 时再传 `--refresh-existing true`，避免局部旧 decision 保留失效 target。 |
| `pnpm run build-live2d-variable-decisions` | 从 A/B/C 变量审查证据生成 567 个函数、1747 条源码参数/局部 occurrence 的离线决策；丢弃有歧义的冗余 `sourceOccurrence`，只用 binding kind + ordinal/name 标识。 |
| `pnpm run audit-live2d-variable-names` | 先运行 567/60/0 module migration 前置，再验证 1747 条源码绑定、1392 条直属实现绑定、81 行 owner-helper、53 项字段/类型处置与 71 个生产脚本 AST 残留，并执行两份名称目录的 offline-only 门禁；禁止把决策 JSON 变成生产映射层。 |
| `pnpm run audit-live2d-runtime-coverage` | 从 immutable source 和全部 durable catalogs 重建 627 函数/1411 调用/567 迁移投影，并从 `runtimeCore.ts` 与真实 renderer consumers 联合构建 typed runtime 图；严格要求 38 owner + 5 sealed support、0 orphan、60 omitted 不可达、源码 tail export/初始化顺序一致、无 compatibility/global/min.js/短名残留，并锁定全页视线合同。 |
| `pnpm run workstream-closeout` | 生成大方向完结闭环审计；识别测试证据、文档同步、历史清理、KT 全局 review、问题记录、稳定解法和 ktWorkflow 升级缺口。 |
## 项目别名
| 别名 | 路径 |
| ------------ | ----------------------------------- |
| `root` | `/home/yemu2/KT` |
| `mcp` | `mcp/ktWorkflow` |
| `napcat` | `GitHub/NapCatQQ` |
| `networkAgent` | `Go/kt-network-agent` |
| `api` | `Node/kt-template-online-api` |
| `admin` | `Vue/kt-template-admin` |
| `blog` | `Vue/kt-blog-web` |
| `knife4j` | `Plugins/knife4j-swagger-vue3` |
| `fnosK8s` | `Plugins/fnos-k8s-dashboard-fpk` |
| `web` | `Vue/kt-template-online-web` |
| `playground` | `Vue/kt-template-online-playground` |
## 开发说明
- 主入口是 `src/server.ts`，只负责 CLI 分支和 MCP Server 汇聚启动。
- 工具入参类型集中在 `src/types.ts`，MCP 注册集中在 `src/registerTools.ts`。
- `src/core/*` 放项目别名、工作区路径、命令执行、仓库/包管理器识别等基础能力。
- `src/tools/*` 按功能拆分：检查、验证、测试、清理、风险、复审、任务记录和工作流计划。
- 根目录上下文分层遵守 `docs/kt-context-semantics.md`：`AGENTS.md` 是硬规则，`SKILLS.md` 是 registry，标准 skill 正文放在 `skills/*/SKILL.md`。
- MCP 客户端直接通过 `node --import tsx loader` 启动 TS 入口，不再保留旧的 `src/server.mjs`。
- Node/npm/pnpm 版本异常时优先走 `nvm ls` + `nvm use`，不要用扫盘路径作为第一选择。
## 使用建议
- 写代码前先调用 `kt_prepare_task`；只需要单项信息时再调用 `kt_read_context` 或 `kt_inspect_project`。`kt_read_context` 默认紧凑输出，只有确实需要完整 `TASKS.md` 时再传 `includeFullDocs=true`。
- 需要按知识图谱定位上下文时先调用 `kt_obsidian_context`，例如 `module=Admin` 或 `query=BangDream`；Obsidian 只做文档索引，返回的 `ruleAnchors` 用来读取相关规则文档，`codeAnchors` 必须继续搭配 `kt_inspect_project`、`kt_risk_scan`、`kt_suggest_verification` 锚定真实代码上下文。
- 多项目联动时先调用 `kt_inspect_all_projects`。
- 要收尾时调用 `kt_finish_task`，默认只生成计划和 review；需要执行验证时显式传 `runValidation=true`。
- 大方向结束前调用 `kt_workstream_closeout` 或 `pnpm run workstream-closeout`；必须传入 `--review` 的 KT 全局审查证据；如果识别到测试流、卡点、误报、清理、部署观测或命令模板，要先升级对应 ktWorkflow 规则再报告完成。
- 文件改动完成并验证后调用 `kt_global_code_review`，或运行 `pnpm run global-review`；它只读扫描，不删除文件、不提交代码。`findings` 先判定真实风险或工具误报，真实风险修业务代码，误报修 `mcp/ktWorkflow/src/tools/review.ts` 并复跑。
- QQBot NapCat 登录 review 会检查验证码 pending、Docker 日志窗口、API Pod 读取超时，以及 `needNewDevice/jumpUrl` 是否进入 `GetNewDeviceQRCode -> PollNewDeviceQR -> NewDeviceLogin` 或兼容的 `deviceVerifyUrl` pending 状态。
- QQBot NapCat 二维码刷新卡在生成阶段时，优先计数当前容器近 5-20 分钟日志里的“重置已失效登录服务后重新生成二维码”、`Login Error,ErrType: 7 ErrCode: 4` 和“二维码已保存/二维码解码URL”；如果 reset/error 数远高于二维码产出，按 `docs/qqbot-nas-runtime.md` 的 v5 稳定解法排查 NapCat native login service reset 风暴，先修 fork/镜像，再看 API SSE。
- 代码或配置改动后调用 `kt_change_doc_sync`，把需要同步的 README/API/AGENTS/docs/Obsidian/skill/ktWorkflow 入口补齐；无需同步时把原因写进收尾证据。
- 报告非平凡任务完成前调用 `kt_workflow_loop_audit`，确认测试证据、文档同步、历史清理最终 `deleted=0`、问题固化、ktWorkflow 升级和 KT 全局 review 都过门；清理证据必须显式传入，不能依赖缺省值。
- 要提交或推送时先调用 `kt_commit_plan` / `kt_push_plan`，按仓库分组确认范围。
- 要测真实业务链路时调用 `kt_business_test_plan`，选择 `admin-login`、`qqbot-auto-reply`、`qqbot-login-sse`、`fflogs-command`、`system-log-visualization` 等 flow。
- 遇到同一命令或同一远程步骤重复卡住时调用 `kt_blocker_resolution`；第二次仍失败时先写入 `TASKS.md` 或补成脚本，再继续。
- 远程服务排查先调用 `kt_remote_health_check`，默认只生成只读命令；需要执行时显式传 `execute=true`。
- API 推送触发 Jenkins/K8s 后先运行 `pnpm run deploy-observation -- --project api --job KT-Template/KT-Template-API/main --namespace kt-prod --deployment kt-template-online-api --container api --health-url http://127.0.0.1:48085/health/runtime --smoke "curl -fsS --max-time 8 http://127.0.0.1:48085/health/runtime"` 查看 dry-run 命令；确认需要线上只读观测时再加 `--execute`。Deployment/Pod 成功只算发布证据，功能完成还必须看 smoke 输出。
- 数据库同步前调用 `kt_db_sync_plan`，先确认源库、目标库、`.kt-workspace/db-sync` 转储目录、带时间戳的备份库和校验点。
- 改 KtTable、BlogArgon、AdminAuth、QQBot、FF14Plugin、NapCatLogin、SystemLog、Knife4jSwagger、FnosK8s 前调用 `kt_component_workflow`，先看专项禁区。
- 不确定任务边界时调用 `kt_guardrails`，先拿到“能做什么、不能做什么、怎么验证”。
- 验证前调用 `kt_suggest_verification`，避免盲跑全量构建。
- API/Jest 验证建议使用 `pnpm exec jest --runInBand`；指定测试文件时使用 `pnpm exec jest --runInBand --runTestsByPath test/path.spec.ts`，不要把 Jest 参数写成 `pnpm test` 的错误透传形式。
- 页面测试前调用 `kt_create_page_test_case`，再执行 Playwright/浏览器测试。
- Admin 页面测试前可先执行 `pnpm run admin-login -- --url <Admin登录页>` 固化登录态，输出的 `storageState` 可作为后续 Playwright 用例前置状态。
- 接口改动后调用 `kt_api_test_plan`，并真实请求一次接口。
- 验证启动过本地服务后调用 `kt_cleanup_process_plan`，用只读计划核对路径、端口和 PID，再只结束本轮启动的进程。
- 每轮测试/验证结束后先调用 `kt_cleanup_history`，或运行 `pnpm run cleanup-history -- --dry-run`；如果预览里 `deleted` 非空，确认范围后执行 `pnpm run cleanup-history -- --execute`，再复跑 dry-run 确认 `deleted=0`，让 `.kt-workspace` 历史产物只保留最近 3 轮并保留模板目录。Pio Live2D 的 `runtime-publish`、`runtime-export-moc-driven`、`probe-source-wordpress-parity`、`moc-runtime` 等活跃发布/基准输入和 `.kt-workspace/toolchains` 会被保留，不按历史轮次删除。`kt_workstream_closeout` / `kt_workflow_loop_audit` 只认可明确的 `deleted=0` / `deleted=[]` 文本证据或结构化 `cleanupFinalDeleted=0`。
- 更新 Obsidian 图谱、模块页、文档矩阵或 `.obsidian` 配置后运行 `kt_obsidian_validate` / `pnpm run obsidian-validate`；整理工作流入口时再跑 `kt_obsidian_sync`。
- 改完文件后用 `kt_append_task_record` 先 `dryRun` 预览记录，再决定是否写入。
- 提交前调用 `kt_commit_checklist`，确认文件范围和提交信息。
## 来源与许可证
| 一级来源 | 使用方式 | License |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | ------- |
| [multica-ai/andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) | `skills/karpathy-guidelines` 和 ktWorkflow 防偏差闭环的行为准则来源 | MIT |
| [kepano/obsidian-skills](https://github.com/kepano/obsidian-skills) | Obsidian Markdown、Canvas、Bases 和 CLI 工作流的归纳整理能力来源 | MIT |
Reference in New Issue View Git Blame Copy Permalink