212 lines
28 KiB
Markdown
212 lines
28 KiB
Markdown
# 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`；大方向收尾必须同时提供 Superpowers code review 证据。
|
||
- 生成任务收尾包：把状态、验证计划、可选验证执行、全局 review 和历史清理收成一份结果。
|
||
- 生成大方向完结闭环审计：确认开发目标、测试证据、KT 全局 review、Superpowers code 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 的防踩坑清单和验证点。
|
||
- 生成验证进程清理计划：按项目路径和端口给出 PowerShell 检查命令，不直接杀进程。
|
||
- 清理历史产物：统一治理 `.kt-workspace` 下的测试/验证产物，按目录最近修改时间只保留最近 3 轮，模板目录永久保留；CLI 默认 dry-run，真实清理必须显式传 `--execute`。
|
||
- 检查 env 策略和变更风险：区分后端真实 env 与前端客户端 `.env*`，提醒锁文件、核心表格组件、API 时间序列化 KtDateTime 列/DTO 装饰器入口、部署链路和 Vue TSX 插槽写法等高风险改动。
|
||
- 全局 CodeReview 只读扫描：汇总全部 KT 子仓库的 Git 状态、敏感文件跟踪、冲突标记、运行时调试输出、疑似凭据字面量、NapCat `latest` 镜像漂移风险、QQBot 重型服务单测导入风险、QQBot 插件 registry/controller smoke 未 mock 具体插件实现风险、QQBot OneBot/QQ 登录态边界回归、NapCat 密码登录验证码 wait 阶段、日志窗口锚点、验证码状态早于日志 URL 的短轮询、验证码 pending 被状态轮询误清理、API Pod SSH 日志读取超时和清理前 pending 回归、普通处理中状态误吃旧验证码日志回归、根目录生成产物、`TASKS.md` 最近记录字段结构、最近记录 3 条上限和当前变更风险；默认只对变更文件做内容扫描，并放过短中文显示标签和明显测试占位 token，避免历史误报污染上下文；任何文件改动后都要跑一遍。
|
||
- 生成或写入 `TASKS.md` 最近记录：默认 `dryRun=true`，确认后再落盘。
|
||
- 生成提交前检查清单：校验 KT commit message 约定。
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
cd D:/MyFiles/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" --superpowers-review "Superpowers reviewer completed; no Critical/Important findings" --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
|
||
```
|
||
|
||
如果本机 Node/npm/pnpm 版本不对，先执行 `nvm ls` 查看已安装版本，再用 `nvm use <version>` 切换到目标版本；不要先扫盘找 `node.exe` 路径。
|
||
|
||
## 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 客户端配置
|
||
|
||
把下面配置加入支持 stdio MCP 的客户端配置里：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"ktWorkflow": {
|
||
"command": "node",
|
||
"args": [
|
||
"--import",
|
||
"file:///D:/MyFiles/KT/mcp/ktWorkflow/node_modules/tsx/dist/loader.mjs",
|
||
"D:/MyFiles/KT/mcp/ktWorkflow/src/server.ts"
|
||
],
|
||
"env": {
|
||
"KT_WORKSPACE_ROOT": "D:/MyFiles/KT"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
## 工具列表
|
||
|
||
| 工具 | 用途 |
|
||
| -------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
||
| `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、Superpowers code review、问题记录、稳定解法和 ktWorkflow 升级 |
|
||
| `kt_workflow_loop_audit` | 审计上下文锚定、测试证据、文档同步、历史清理最终 `deleted=0`、问题固化、ktWorkflow 升级、KT 全局 review 和 Superpowers code 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 全部子仓库做只读全局 CodeReview 扫描，默认仅对变更文件做内容深扫，输出 JSON 复审报告，并校验 `TASKS.md` 最近记录只保留最新 3 条详细记录，以及每条记录只保留范围、关键词、验证字段；同时校验 NapCat `latest` 漂移、QQBot 重型服务单测导入风险、QQBot 插件 registry/controller smoke 未 mock 具体插件实现风险、OneBot/QQ 登录态边界、NapCat 密码登录验证码 wait 阶段、日志窗口锚点、验证码状态早于日志 URL 的短轮询、验证码 pending 被状态轮询误清理、API Pod SSH 日志读取超时及清理前 pending 回归，以及普通处理中状态误吃旧验证码日志回归；明显测试占位 token 不报凭据风险，确认误报时优先升级 `src/tools/review.ts`，不要把误报沉积到上下文。 |
|
||
| `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 轮并保留模板目录。 |
|
||
| `pnpm run workstream-closeout` | 生成大方向完结闭环审计；识别测试证据、文档同步、历史清理、KT 全局 review、Superpowers code review、问题记录、稳定解法和 ktWorkflow 升级缺口。 |
|
||
|
||
## 项目别名
|
||
|
||
| 别名 | 路径 |
|
||
| ------------ | ----------------------------------- |
|
||
| `root` | `D:/MyFiles/KT` |
|
||
| `mcp` | `mcp/ktWorkflow` |
|
||
| `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 全局审查证据和 `--superpowers-review` 的 Superpowers code review 证据；如果识别到测试流、卡点、误报、清理、部署观测或命令模板，要先升级对应 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 和 Superpowers code 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`，清掉本次进程。
|
||
- 每轮测试/验证结束后先调用 `kt_cleanup_history`，或运行 `pnpm run cleanup-history -- --dry-run`；如果预览里 `deleted` 非空，确认范围后执行 `pnpm run cleanup-history -- --execute`，再复跑 dry-run 确认 `deleted=0`，让 `.kt-workspace` 历史产物只保留最近 3 轮并保留模板目录。`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 |
|