# WorkFlow MCP — 多阶段 AI 研发编排与控制台使用文档

WorkFlow MCP 是一个集成了 **Wails v2 桌面管理控制台 (Go + Vue 3)** 与 **Model Context Protocol (MCP) Server (Node.js/TypeScript)** 的智能研发编排系统。

它允许你针对软件研发的不同阶段（架构定制、代码开发、测试覆盖、代码审查）分别配置不同的第三方 AI 模型（如用高级模型做深度架构，用标准模型做代码开发，用专用轻量模型做测试生成），并在 Claude Code 终端中通过自定义指令随时调用。

---

## 📋 前置环境要求 (Prerequisites)

开始打包前，请确保本机已安装以下工具链（脚本会自动探测，缺失则给出安装提示而非黑屏报错）：

| 工具 | 最低版本 | 安装方式 |
|---|---|---|
| **Go** | ≥ 1.23（见 `desktop/go.mod`） | https://go.dev/dl/ |
| **Node.js** | ≥ 18（含 npm） | https://nodejs.org/ |
| **Wails CLI** | v2 | `go install github.com/wailsapp/wails/v2/cmd/wails@latest` |
| **NSIS** | — | https://nsis.sourceforge.io/ （仅 `wails build -nsis` 出安装包需要） |

> 终端用户（只跑安装包，不需要自己构建）**无需**安装以上任何工具——安装包已自带便携 `node.exe` 与网关 sidecar 运行时。前置工具链仅面向从源码构建/二次开发的开发者。

---

## ⚡ 一键打包与安装 (One-Click Build & Install)

如果你刚克隆或更新了本项目，可通过以下方式进行**依赖初始化安装**与**全自动编译打包**：

### 🛠️ 步骤一：依赖初始化 (Init Dependencies)

首次克隆项目或新增依赖包后，可以通过以下任一命令一键自动安装 `mcp-server` 与 `desktop/frontend` 两个子项目的依赖：

- **双击运行批处理**：`init.bat`
- **PowerShell 运行**：`.\init.ps1`
- **npm 命令**：`npm run init`

> 💡 *注：`build-and-install.bat` 与 `build-and-install.ps1` 在打包时也会自动检查 `node_modules`，若尚未安装会自动触发依赖安装。*

### 步骤二：编译打包与注册 (Build & Register)

在完成依赖初始化后，可通过以下任一方式**编译桌面端 + 打包 NSIS 安装包 + 自动注册 MCP Server**：

#### 方式一：Windows 批处理一键运行 (`build-and-install.bat`) 🏆推荐

在 Windows 资源管理器中**直接双击运行 `build-and-install.bat`**，或者在 cmd / 终端中运行：

```cmd
build-and-install.bat
```

> **该 BAT 批处理会自动完成：**
> 1. 自动检查并安装缺失的 `node_modules` 依赖包
> 2. 编译 `mcp-server` TypeScript 脚本生成 `dist/index.js`
> 3. 编译构建 `desktop` 生成 Windows 原生轻量桌面应用 `desktop/build/bin/WorkFlow-MCP.exe` 与安装包
> 4. 归整网关 sidecar 运行时（`dist` + 生产 `node_modules` + 便携 `node.exe`）随 NSIS 安装包一并打包
> 5. 自动向 Claude Code 注册 `workflow` MCP Server

---

### 方式二：PowerShell 脚本运行 (`build-and-install.ps1`)

在 PowerShell 终端中执行：

```powershell
.\build-and-install.ps1
```

---

### 方式三：npm 命令运行

在项目根目录下直接运行：

```bash
# 一键编译桌面端 + MCP Server
npm run build

# 一键向 Claude Code 注册 MCP 服务
npm run register

# 一键运行全部单元测试
npm run test
```

---

## 🌟 核心特性

1. **角色定位与提示词定制 (Role Management)**
   - 内置 4 个核心角色阶段：**架构师** (`architect`)、**开发者** (`developer`)、**测试工程师** (`tester`)、**代码审查员** (`reviewer`)。
   - 支持自定义添加新角色、修改角色定位、配置温度与 Token 限制，以及复制克隆角色。

2. **多模型节点配置 (Model Configurations)**
   - 支持 **OpenAI 兼容 API**（OpenAI, DeepSeek, Moonshot, Ollama, Qwen 等）、**Anthropic Claude** 原生 API 以及 **自定义 HTTP 接口**。
   - 提供桌面端 **一键 API 连通性测试** 按钮，验证网络与 Key 有效性。
   - API Key 采用 AES-256-GCM 算法本地加密存储在 SQLite 中。

3. **可视化流水线设计 (Pipeline Designer)**
   - 自由选择和排列多个角色，组装为全流程自动递进流转的 AI 研发流水线。
   - 阶段间自动传递上下文（前一个阶段的输出自动作为下一阶段的输入）。

4. **审计日志与成本追踪 (Audit Dashboard)**
   - 自动记录每次调用的完整输入/输出、Prompt Tokens、Completion Tokens、响应延迟（ms）与预估美元成本。
   - 提供多条件筛选与日志明细弹窗，支持一键清理历史旧数据。

5. **配置全量导入与导出 (Import & Export)**
   - 支持将所有模型配置、角色定义、流水线排布和提示词模板全量导出为 YAML 配置文件，或从备份一键恢复。

---

## 🚀 常用启动与运维

### 1. 启动桌面控制台

已构建好的桌面控制台位于 `desktop/build/bin/desktop.exe`，直接双击运行：

```bash
# 开发模式运行桌面控制台（支持 Vite 热重载）
cd desktop
wails dev
```

控制台使用引导：
1. 打开控制台后，前往 **模型配置** 页面，添加你的第三方 AI API 密钥（如 DeepSeek、OpenAI、Claude 等），点击“测试连接”验证。
2. 前往 **角色管理** 页面，为架构师、开发者、测试工程师选择绑定的模型节点。
3. 前往 **流水线设计** 页面，查看或自定义流水线的执行顺序。

---

### 2. 手动注册 MCP Server 到 Claude Code

如果你需要手动注册或指定路径注册（**请替换为你的实际仓库克隆路径**，不要照抄示例绝对路径）：

```bash
# Windows / 通用:用 -s user 作用域注册,把 <REPO> 换成你克隆到的目录
claude mcp add -s user workflow -- node "<REPO>/mcp-server/dist/index.js"

# 例 (仓库克隆到 D:\code\workFlowMCP):
claude mcp add -s user workflow -- node "D:/code/workFlowMCP/mcp-server/dist/index.js"
```

> 安装桌面端并启用「出口接管 / 配置覆盖」后，桌面应用会自动接管 Claude Code 的 `settings.json`，不必手动注册也可工作。手动注册仅用于绕过桌面端或排错。

验证注册状态：在 Claude Code 交互界面中输入 `/mcp`，确认 `workflow` 显示在在线 Server 列表中。

---

## 🛠️ MCP Tools 指令说明

注册成功后，你可以在 Claude Code 中使用以下工具：

### 1. 单阶段调用工具

- `workflow_plan`
  - **描述**: 调用架构师模型进行需求分析与技术实施方案定制。
  - **示例**: `请使用 workflow_plan 帮我针对“支持百万并发的日志收集系统”定制架构方案`

- `workflow_develop`
  - **描述**: 调用开发者模型根据方案或研发任务编写完整可运行的代码。
  - **示例**: `请使用 workflow_develop 根据上述架构方案编写 Golang 实现代码`

- `workflow_test`
  - **描述**: 调用测试工程师模型生成单元测试、集成测试与覆盖率报告。
  - **示例**: `请使用 workflow_test 为 src/user_service.ts 编写 Vitest 单元测试`

- `workflow_review`
  - **描述**: 调用代码审查员模型审查代码的安全性、性能与架构规范。
  - **示例**: `请使用 workflow_review 审查以下并发代码的线程安全问题`

---

### 2. 流水线与管理工具

- `workflow_pipeline`
  - **描述**: 一键按序执行全流程 AI 研发流水线（方案 -> 开发 -> 测试 -> 审查），前一阶段的结果将作为后一阶段的输入上下文。
  - **示例**: `请使用 workflow_pipeline 自动完成“实现 JWT 用户鉴权中间件”的全流程研发`

- `workflow_config`
  - **描述**: 查看当前已注册的角色定位、模型节点或流水线信息。
  - **示例**: `workflow_config({ category: "roles" })`

- `workflow_status`
  - **描述**: 查看 WorkFlow MCP 引擎的运行状态、累计 Token 消耗与预估 API 成本。
  - **示例**: `workflow_status({})`

---

## 💬 MCP Prompts 快捷指令

你也可以在 Claude Code 聊天框中使用 `/` 快捷启动模板：

- `/mcp__workflow:plan` — 快速触发方案定制
- `/mcp__workflow:develop` — 快速触发代码开发
- `/mcp__workflow:test` — 快速触发测试生成
- `/mcp__workflow:review` — 快速触发代码审查
- `/mcp__workflow:full-pipeline` — 快速触发全流程流水线

---

## 📂 项目目录结构

```
workFlowMCP/
├── README.md                           # 使用文档（本文件）
├── build-and-install.bat               # Windows 双击一键打包编译与 MCP 自动注册批处理
├── build-and-install.ps1               # PowerShell 一键打包编译与 MCP 自动注册脚本
├── package.json                        # 根目录一键脚本配置文件
├── prompts/                            # 共享角色系统提示词模板
│   ├── architect-system.md
│   ├── developer-system.md
│   ├── tester-system.md
│   └── reviewer-system.md
├── desktop/                            # Wails v2 桌面控制台 (Go + Vue 3)
│   ├── build/bin/desktop.exe           # 打包生成的桌面可执行文件 (~10MB)
│   ├── main.go & app.go                # Wails 初始化与服务绑定
│   ├── internal/                       # GORM SQLite 数据库、Service 业务逻辑与 AES 加密
│   └── frontend/                       # Vue 3 + TypeScript 响应式管理界面
└── mcp-server/                         # MCP Server 执行引擎 (Node.js/TypeScript)
    ├── src/index.ts                    # Stdio 传输层入口
    ├── src/model/                      # ModelRouter 与 OpenAI/Anthropic/Custom 适配器
    ├── src/pipeline/                   # 动态流水线引擎与上下文传递
    └── dist/index.js                   # 编译生成的 MCP 入口脚本
```