Go to file

sunlei e715cca304 fix: 修复ktworkflow状态解析		2026-06-02 07:29:55 +08:00
config	refactor: 删除旧MCP启动入口	2026-05-27 23:35:11 +08:00
scripts	feat: 固化Admin登录冒烟脚本	2026-05-30 20:52:33 +08:00
src	fix: 修复ktworkflow状态解析	2026-06-02 07:29:55 +08:00
.gitignore	feat: 初始化KT工作流MCP	2026-05-27 18:04:36 +08:00
package.json	refactor: 拆分ktworkflow模块	2026-06-02 07:23:58 +08:00
pnpm-lock.yaml	feat: TS化工作流MCP并加入博客上下文	2026-05-27 23:11:18 +08:00
README.md	refactor: 拆分ktworkflow模块	2026-06-02 07:23:58 +08:00
tsconfig.json	feat: 固化Admin登录冒烟脚本	2026-05-30 20:52:33 +08:00

README.md

KT Workflow MCP

ktWorkflow 是 KT 工作区的可复用 MCP 能力包，用 TypeScript 封装工具入参、项目别名和返回结构，用来把根目录 AGENTS.md、SKILLS.md、TASKS.md 中的协作流程变成可调用工具。

能力边界

读取 KT 工作区上下文：项目清单、硬性规则、协作技能、最近任务记录。
检查子项目环境：Git/SVN、包管理器、Node 版本、env 文件、Git 状态。
生成防偏差工作包：把开工前检查、禁止项、风险扫描、验证计划汇总成一份可执行清单。
生成验证建议：按后端、前端、样式、页面、部署、MCP 等变更类型给出轻量验证命令。
固化改动后 review：验证计划和提交清单都会提醒执行 kt_global_code_review / pnpm run global-review。
生成任务收尾包：把状态、验证计划、可选验证执行、全局 review 和历史清理收成一份结果。
生成页面测试用例：内置“先写用例、可视化证据、事不过三”的测试闭环。
生成接口测试计划：接口改动后输出真实调用命令和统一返回结构断言。
生成业务链路测试计划：固化 Admin 登录、博客 CRUD、QQBot 扫码/自动回复、Web/Playground 回跳。
生成多仓库提交/推送计划：按仓库分组、建议提交信息、列出提交和推送前检查。
生成远程只读健康检查和数据库同步安全向导：覆盖飞牛 NAS 服务探测、GTID、备份和行数校验。
生成专项组件工作流：KtTable、BlogArgon、AdminAuth、QQBot 的防踩坑清单和验证点。
生成验证进程清理计划：按项目路径和端口给出 PowerShell 检查命令，不直接杀进程。
清理历史产物：按目录最近修改时间只保留最近 3 轮测试/验证产物，模板目录永久保留。
检查 env 策略和变更风险：提醒真实配置、锁文件、核心表格组件、部署链路等高风险改动。
全局 CodeReview 只读扫描：汇总全部 KT 子仓库的 Git 状态、敏感文件跟踪、冲突标记、运行时调试输出、疑似凭据字面量和当前变更风险；任何文件改动后都要跑一遍。
生成或写入 TASKS.md 改动记录：默认 dryRun=true，确认后再落盘。
生成提交前检查清单：校验 KT commit message 约定。

安装

cd D:/MyFiles/KT/mcp/ktWorkflow
pnpm install
pnpm run typecheck
pnpm run self-test
pnpm run cleanup-history -- --dry-run
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`	清理历史测试/验证产物，默认预览，执行时只保留最近 3 轮
`kt_cleanup_process_plan`	生成验证进程清理检查命令
`kt_env_policy`	检查 env 文件现状和提交策略
`kt_risk_scan`	扫描当前或传入变更文件的偏差风险
`kt_global_code_review`	对 KT 全部子仓库做只读全局 CodeReview 扫描
`kt_finish_task`	生成任务收尾包，可选执行验证和历史清理
`kt_commit_plan`	生成多仓库提交计划、建议 commit message 和检查项
`kt_push_plan`	生成多仓库推送计划和远程异常提醒
`kt_business_test_plan`	生成固化业务链路测试计划
`kt_remote_health_check`	生成或执行远程只读健康检查命令
`kt_db_sync_plan`	生成数据库同步安全向导
`kt_component_workflow`	输出专项组件/链路防踩坑工作流
`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 复审报告。

项目别名

别名	路径
`root`	`D:/MyFiles/KT`
`mcp`	`mcp/ktWorkflow`
`api`	`Node/kt-template-online-api`
`admin`	`Vue/kt-template-admin`
`blog`	`Vue/kt-blog-web`
`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/* 按功能拆分：检查、验证、测试、清理、风险、复审、任务记录和工作流计划。
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_inspect_all_projects。
要收尾时调用 kt_finish_task，默认只生成计划和 review；需要执行验证时显式传 runValidation=true。
文件改动完成并验证后调用 kt_global_code_review，或运行 pnpm run global-review；它只读扫描，不删除文件、不提交代码。
要提交或推送时先调用 kt_commit_plan / kt_push_plan，按仓库分组确认范围。
要测真实业务链路时调用 kt_business_test_plan，选择 admin-login、qqbot-auto-reply 等 flow。
远程服务排查先调用 kt_remote_health_check，默认只生成只读命令；需要执行时显式传 execute=true。
数据库同步前调用 kt_db_sync_plan，先确认源库、目标库、备份库和校验点。
改 KtTable、BlogArgon、AdminAuth、QQBot 前调用 kt_component_workflow，先看专项禁区。
不确定任务边界时调用 kt_guardrails，先拿到“能做什么、不能做什么、怎么验证”。
验证前调用 kt_suggest_verification，避免盲跑全量构建。
页面测试前调用 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 -- --keep=3，让历史产物只保留最近 3 轮。
改完文件后用 kt_append_task_record 先 dryRun 预览记录，再决定是否写入。
提交前调用 kt_commit_checklist，确认文件范围和提交信息。

README.md Unescape Escape