ktworkflow-mcp/README.md

# KT Workflow MCP

`ktWorkflow` 是 KT 工作区的可复用 MCP 能力包，用 TypeScript 封装工具入参、项目别名和返回结构，用来把根目录 `AGENTS.md` 的硬规则、`SKILLS.md` 的工作流索引、`TASKS.md` 的上下文记录和 `docs/` 的详细流程变成可调用工具。当前版本：`0.6.1`。

## 能力边界

- 读取 KT 工作区紧凑上下文：项目清单、硬性规则、skill registry、标准 skill 包索引、历史关键词、最近任务记录和详细文档入口；需要全量文档时显式开启。
- 检查子项目环境：Git/SVN、包管理器、Node 版本、env 文件、Git 状态。
- 生成防偏差工作包：把开工前检查、禁止项、风险扫描、验证计划汇总成一份可执行清单。
- 生成验证建议：按后端、前端、样式、页面、部署、MCP 等变更类型给出轻量验证命令。
- 固化改动后 review：验证计划和提交清单都会提醒执行 `kt_global_code_review` / `pnpm run global-review`。
- 生成任务收尾包：把状态、验证计划、可选验证执行、全局 review 和历史清理收成一份结果。
- 生成页面测试用例：内置“先写用例、可视化证据、事不过三”的测试闭环。
- 生成接口测试计划：接口改动后输出真实调用命令和统一返回结构断言。
- 生成业务链路测试计划：固化 Admin 登录、博客 CRUD、QQBot 扫码/自动回复、更新登录 SSE、FFLogs 命令、系统日志可视化、Web/Playground 回跳。
- 生成多仓库提交/推送计划：按仓库分组、建议提交信息、列出提交和推送前检查。
- 生成远程只读健康检查和数据库同步安全向导：覆盖飞牛 NAS 服务探测、GTID、备份和行数校验。
- 生成专项组件工作流：KtTable、BlogArgon、AdminAuth、QQBot、FF14Plugin、NapCatLogin、SystemLog、Knife4jSwagger、FnosK8s 的防踩坑清单和验证点。
- 生成验证进程清理计划：按项目路径和端口给出 PowerShell 检查命令，不直接杀进程。
- 清理历史产物：统一治理 `.kt-workspace` 下的测试/验证产物，按目录最近修改时间只保留最近 3 轮，模板目录永久保留。
- 检查 env 策略和变更风险：区分后端真实 env 与前端客户端 `.env*`，提醒锁文件、核心表格组件、部署链路和 Vue TSX 插槽写法等高风险改动。
- 全局 CodeReview 只读扫描：汇总全部 KT 子仓库的 Git 状态、敏感文件跟踪、冲突标记、运行时调试输出、疑似凭据字面量、根目录生成产物和当前变更风险；默认只对变更文件做内容扫描，并放过短中文显示标签，避免历史误报污染上下文；任何文件改动后都要跑一遍。
- 生成或写入 `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 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 的客户端配置里：

```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_commit_plan` | 生成多仓库提交计划、建议 commit message 和检查项 |
| `kt_push_plan` | 生成多仓库推送计划和远程异常提醒 |
| `kt_business_test_plan` | 生成固化业务链路测试计划，包含 QQBot SSE、FFLogs 和系统日志 |
| `kt_remote_health_check` | 生成或执行远程只读健康检查命令 |
| `kt_db_sync_plan` | 生成数据库同步安全向导 |
| `kt_component_workflow` | 输出专项组件/链路防踩坑工作流，包含 FnosK8s |
| `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 复审报告；确认误报时优先升级 `src/tools/review.ts`，不要把误报沉积到上下文。 |

## 项目别名

| 别名 | 路径 |
| --- | --- |
| `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_inspect_all_projects`。
- 要收尾时调用 `kt_finish_task`，默认只生成计划和 review；需要执行验证时显式传 `runValidation=true`。
- 文件改动完成并验证后调用 `kt_global_code_review`，或运行 `pnpm run global-review`；它只读扫描，不删除文件、不提交代码。`findings` 先判定真实风险或工具误报，真实风险修业务代码，误报修 `mcp/ktWorkflow/src/tools/review.ts` 并复跑。
- 要提交或推送时先调用 `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_remote_health_check`，默认只生成只读命令；需要执行时显式传 `execute=true`。
- 数据库同步前调用 `kt_db_sync_plan`，先确认源库、目标库、备份库和校验点。
- 改 KtTable、BlogArgon、AdminAuth、QQBot、FF14Plugin、NapCatLogin、SystemLog、Knife4jSwagger、FnosK8s 前调用 `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`，让 `.kt-workspace` 历史产物只保留最近 3 轮。
- 改完文件后用 `kt_append_task_record` 先 `dryRun` 预览记录，再决定是否写入。
- 提交前调用 `kt_commit_checklist`，确认文件范围和提交信息。