# ProjectFlow DAG MCP 2.2.1

[![CI](https://github.com/wjmiracle/projectflow-dag-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/wjmiracle/projectflow-dag-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js 20+](https://img.shields.io/badge/Node.js-20%2B-339933.svg)](https://nodejs.org/)

> A local, model-independent DAG task coordinator for AI coding agents, with a static visual UI, validated state machine, resumable JSON progress, and MCP tools.

ProjectFlow 是一个面向 AI Agent 的本地 DAG 任务编排器。它把任务依赖、执行状态、验证证据和恢复操作保存在工程图 JSON 中，由 MCP Server 统一控制状态转换；网页 UI 负责查看和手工维护工程图。

它不替 Agent 写代码，也不绑定某个模型。任何支持 MCP tools 的 Agent 都可以使用同一套执行协议。

![ProjectFlow 工程图界面](docs/images/project-graph.png)

本项目不是 Google、Anthropic、OpenAI、GitHub 或其他 Agent 平台的官方产品，也与已有的同名 ProjectFlow 项目无隶属关系。

## 组成

- `projectflow-mcp/`：状态机、并发锁、工程图校验和 Agent 执行协议。
- `dist/projectflow-mcp.cjs`：无需安装 npm 依赖的可分发 MCP bundle。
- `index.html`、`app.js`、`index.css`：工程图可视化界面。
- `plugin.json`、`mcp_config.json`、`skills/`：Antigravity 插件。
- `gemini-extension.json`、`GEMINI.md`、`commands/`：Gemini CLI Extension。
- `adapters/`：Codex、Claude、Copilot 和通用 Agent 的薄适配器。
- `examples/todo-tutorial.projectflow.json`：可直接跟随使用手册运行的完整教程图纸。

执行规则的唯一权威来源是 MCP tool `get_execution_protocol`。各平台 Skill/指令文件只负责触发它，避免多份流程逐渐不一致。

## 构建与检查

需要 Node.js 20 或更高版本。

```powershell
git clone https://github.com/wjmiracle/projectflow-dag-mcp.git
cd projectflow-dag-mcp
npm --prefix projectflow-mcp ci
npm run build
npm test
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Action Validate
```

## 安装

Antigravity CLI：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Client Antigravity -Action Install
```

Gemini CLI：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Client Gemini -Action Install
```

只更新独立 Skill，不安装完整插件：

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Action Validate -InstallAntigravitySkill
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1 -Action Validate -InstallCodexSkill
```

Claude、Copilot 和其他 MCP 客户端的配置样例见 `adapters/README.md`。

生成可上传到 GitHub Release、网盘或网站的精简发行包：

```powershell
npm run pack
```

输出位于 `release/projectflow-dag-mcp-2.2.1.zip`，同时生成 SHA-256 校验文件。用户解压后即可安装；发行包不包含 `node_modules` 和开发源码。

## 使用

1. 在网页点击“生成步骤 JSON”，填写项目名称、产出目录和需求。
2. 复制完整提示词并发送给任意 AI，把它返回的 JSON 保存到本地。
3. 将 JSON 导入网页，并向执行 Agent 提供该文件的绝对路径。
4. Agent 加载服务器协议，原子领取任务，真实执行并验证，然后写回结果和证据。
5. UI 重新读取 JSON 后显示实时进度。

推荐通过本地 HTTP 打开 UI：

```powershell
python -m http.server 8080
```

然后访问 `http://localhost:8080`。

## 发布边界

只把静态网页放到公网，并不会让访问者自动获得 MCP 能力。完整发布应同时提供：

- 在线 UI，或可下载的静态 UI；
- Antigravity/Gemini 插件包，或其他客户端的 MCP 配置；
- bundle 后的 `dist/projectflow-mcp.cjs`；
- 对应平台的薄 Skill/Agent 指令。

目前 MCP bundle 是本地 `stdio` 服务。若希望用户打开网页后无需本地安装，就还需要增加带认证和权限隔离的远程 HTTP MCP 服务。

详细格式、工具和排障说明见 `使用手册.md`。

## 文档与贡献

- [保姆级使用手册](使用手册.md)
- [教程工程图](examples/todo-tutorial.projectflow.json)
- [MCP Server 说明](projectflow-mcp/README.md)
- [贡献指南](CONTRIBUTING.md)
- [安全策略](SECURITY.md)
- [版本记录](CHANGELOG.md)

## License

MIT © 2026 [wjmiracle](https://github.com/wjmiracle)