# Workflow MCP

**把复杂 AI 任务组织成可确认、可追踪、可恢复的工作流。**

Workflow MCP 是面向 AI 开发环境的工作流工具。通过 MCP 提交目标，由当前主线程编写脚本、安排子代理协作；打开 WebUI，就能查看同一次任务的执行阶段、子代理记录、脚本结果和交付产物。

适合代码审阅、资料整理、业务分析及需要多步协作的任务。服务独立运行，默认沿用主线程的模型选择，无需在工作流服务中另外配置模型供应商。

[快速开始](#快速开始) · [使用指南](docs/user-guide.md) · [产品介绍](docs/product-brief.md) · [验收记录](docs/verification.md)

![Workflow MCP 工作流阶段、实例详情和产物](docs/screenshots/run-detail-light.png)

*功能验收截图：实际引擎运行，子代理结果由测试程序回填。真实宿主子代理的独立验收见下方记录。*

## 你可以用它做什么

| 能力 | 使用方式 |
| --- | --- |
| 从目标生成工作流 | 用自然语言描述目标，主线程生成 TypeScript 草稿，先编译，再确认执行 |
| 安排多代理协作 | 将任务按阶段拆分；独立步骤并行推进，有依赖的步骤按顺序执行 |
| 查看全过程 | 在同一页面查看阶段图、实例状态、子代理转录和脚本步骤的输入、结果与错误 |
| 随时介入执行 | 回答阻塞问题、停止任务、调整并发；确认修订后继续推进 |
| 接续中断的任务 | 使用持久化执行记录恢复实例，复用已完成的步骤 |
| 交付多种产物 | 预览 Markdown、文件、图表、表格、指标和看板；下载文件类产物 |
| 保存常用流程 | 将脚本保存到项目或全局范围，再次运行时传入新参数 |
| 指定模型与环境 | 默认继承主线程；按本次任务的要求，为指定子代理或执行环境设置覆盖 |

MCP 和 WebUI 共享会话、运行实例与事件记录。你可以在主线程发起任务，在网页确认和查看进度，再回到主线程继续处理。

## 快速开始

需要 **Node.js 24+、pnpm 10**。使用 Git 读取能力时，还需要安装 Git。目前主要在 Windows 上完成验收。

仓库当前为私有，仅具有访问权限的账号可以克隆：

```sh
git clone https://github.com/zero36kai/workflow-mcp.git
cd workflow-mcp
pnpm install --frozen-lockfile
pnpm build
pnpm start
```

打开 [本机 WebUI](http://127.0.0.1:8830)。首次启动会创建 `data/`，用于保存会话、工作目录、执行记录和 MCP 访问凭证。

### 连接 MCP

在支持 HTTP MCP 的调用端加入以下配置，将占位符替换为本机 `data/api-key.txt` 中的内容：

```json
{
  "mcpServers": {
    "workflow": {
      "url": "http://127.0.0.1:8830/mcp",
      "headers": {
        "x-api-key": "<本机 data/api-key.txt 的内容>"
      }
    }
  }
}
```

为调用端安装随项目提供的 [dynamic-workflows 技能](skills/dynamic-workflows/SKILL.md)，或让主线程遵循 MCP 初始化返回的调度说明。调用端需要具备创建、继续、等待和停止子代理的能力。

然后在主线程中提出目标，例如：

> 用工作流审阅当前项目：并行检查代码变更和测试覆盖，汇总需要处理的问题，生成 Markdown 报告。先让我确认方案。

主线程生成草稿后，WebUI 显示确认卡。确认后即可查看阶段进度、打开子代理记录，并在完成卡中阅读产物。网页中也可以新建目标；草稿生成和模型任务需要已连接的主线程继续处理。

### 本机设置

| 环境变量 | 默认值 | 用途 |
| --- | --- | --- |
| `WORKFLOW_PORT` | `8830` | 服务端口 |
| `WORKFLOW_DATA_DIR` | 项目下的 `data/` | 会话、工作目录和访问凭证所在目录 |

服务默认监听 `127.0.0.1`。PowerShell 7 下可用 `$env:WORKFLOW_PORT = '8831'` 设置其他端口，再运行 `pnpm start`。

## 执行与模型

主线程负责把目标写成脚本、领取待办任务、调用宿主子代理并回填结果。Workflow MCP 负责脚本编译、执行调度、状态保存和可视化。详细调用顺序和工具清单见 [使用指南](docs/user-guide.md)。

子代理默认继承主线程模型。只有用户明确指定时，主线程才通过 `routing` 传递模型或环境覆盖；实际执行能力由宿主提供。WebUI 展示宿主回报的模型和用量，未回报时保留为未知。

恢复任务会复用已完成步骤，中断时尚未完成的命令或外部写入可能重试。停止实例后，主线程还需停止对应的宿主子代理。

## 界面与验收

![Workflow MCP 深色界面](docs/screenshots/run-detail-dark.png)

*同一功能验收实例的深色界面。支持明暗主题和窄屏布局。*

已验证独立构建、SQLite 持久化、服务与视图回归、MCP 调用以及浏览器交互。另完成了一次真实宿主子代理的算术任务，核对了同一实例中的转录、结果和产物。完整范围、证据与已知性能测试问题见 [验收记录](docs/verification.md)。

## 开发

```sh
pnpm build           # 构建全部组件
pnpm test            # 存储、服务与视图测试
pnpm test:upstream   # 核心编译、调度与运行器测试
pnpm check:source    # 第三方分发文件校验
pnpm check:e2e       # 官方 MCP SDK 与隔离浏览器验收，需要 Chrome
pnpm dev             # 同时启动服务与前端开发环境
```

```text
packages/engine       编译器与调度核心
packages/runtime      子进程运行器
packages/storage      SQLite 执行记录
packages/projection   状态归并与图投影
packages/server       MCP、HTTP 与主线程任务接入
packages/web          会话、阶段、实例、子代理与产物界面
skills/               主线程调度技能
docs/                 使用、验收和发布文档
third_party/          组件来源、许可证与文件校验清单
```

维护者：**zero36kai**。当前采用私有仓库管理，上传方法见 [私有发布说明](docs/release.md)。

项目新增接入层和 WebUI 采用 [MIT 许可](LICENSE)；所含第三方组件保留各自许可，详见 [组件与许可说明](third_party/UPSTREAM.md)。