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

23 KiB
Raw Blame History

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、稳定 02:42:* MAC、QQNT machine-info 写入、持久化 runtime dir 和 DB_TIMEZONE 默认值。
  • 生成卡点固化记录：把超时、卡进程、远程命令误写、重复失败整理成“问题点 / 稳定解法 / 后续入口 / 验证证据”，避免原样重试。
  • 生成改动文档同步计划：按变更文件自动提示需要同步的 README、API、AGENTS、docs、Obsidian、skill 和 ktWorkflow 入口。
  • 生成多仓库提交/推送计划：按仓库分组、建议提交信息、列出提交和推送前检查。
  • 生成远程只读健康检查和数据库同步安全向导：覆盖飞牛 NAS 服务探测、GTID、.kt-workspace/db-sync 转储、备份库和行数校验。
  • 生成或执行部署观测：把 Jenkins build、build.xml SCM revision、日志尾部、K8s Deployment、Pod、/health/runtime 和任务 smoke 汇总成 .kt-workspace/test-artifacts/deploy-observation 下的运行态证据；Jenkins 状态以日志尾部最终 Finished: 为准，日志存在但缺少最终态时不认定发布完成。
  • 生成专项组件工作流：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 最近记录字段结构和当前变更风险；默认只对变更文件做内容扫描，并放过短中文显示标签和明显测试占位 token，避免历史误报污染上下文；任何文件改动后都要跑一遍。
  • 生成或写入 TASKS.md 最近记录：默认 dryRun=true，确认后再落盘。
  • 生成提交前检查清单：校验 KT commit message 约定。

安装

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 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-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 路径。

MCP 客户端配置

把下面配置加入支持 stdio MCP 的客户端配置里：

{
  "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_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 最近记录只保留范围、关键词、验证字段、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-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 状态。
  • 代码或配置改动后调用 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 skills/karpathy-guidelines 和 ktWorkflow 防偏差闭环的行为准则来源 MIT
kepano/obsidian-skills Obsidian Markdown、Canvas、Bases 和 CLI 工作流的归纳整理能力来源 MIT