Metadata-Version: 2.4
Name: mcp-ai-supervisor
Version: 0.1.0
Summary: AI Supervisor MCP server - desktop-based interactive feedback and task supervision for AI-assisted development.
Author: AI Supervisor Team
Keywords: ai,desktop-app,development,interactive,mcp,supervisor,tauri
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: mcp-supervisor-core>=0.1.0
Requires-Dist: mcp-supervisor-workbench>=0.1.0
Requires-Dist: mcp>=1.9.3
Requires-Dist: psutil>=7.0.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: websockets>=13.0.0
Description-Content-Type: text/markdown

# MCP AI Supervisor

> AI 智能监工系统 —— 让 AI 不再半途而废

MCP AI Supervisor 是一个基于 [MCP（Model Context Protocol）](https://modelcontextprotocol.io/) 的 AI 任务监督工具。它通过 `interactive_feedback` MCP 工具在 AI 和用户之间建立持续的反馈循环，确保 AI 完整地完成任务。

## 工作原理

```
AI 执行任务 → 调用 interactive_feedback → 监工系统处理 → 返回反馈 → AI 继续工作
   ↑                                                                |
   └────────────────────── 循环直到任务完成 ──────────────────────────┘
```

## 核心特性

- **三种运行模式** — `semi`（半自动，默认）/ `auto`（全自动）/ `manual`（手动）
- **Tauri 桌面弹窗** — 原生弹窗提醒（macOS / Linux / Windows），比浏览器更醒目
- **Workbench 控制台** — React + WebSocket 实时多项目管理面板（V4.0）
- **监工 Agent** — 可选的 AI 监工（qodercli），自动评估主 AI 的产出质量
- **Timeout 自动重试** — 超时不中断，自动提醒 AI 继续等待（可配置最大重试次数和退避策略）
- **消息队列** — AI 忙碌时消息自动排队，空闲时优先投递，支持置顶/编辑/重试
- **多 IDE 支持** — Cursor、Qoder、Claude Code
- **多语言界面** — 简体中文 / 繁体中文 / English

## 快速安装

### 方式一：PyPI 安装（推荐）

```bash
pip install mcp-ai-supervisor
```

安装后在 `~/.cursor/mcp.json` 中配置：

```json
{
  "mcpServers": {
    "mcp-ai-supervisor": {
      "command": "uvx",
      "args": ["mcp-ai-supervisor"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_DELEGATE_MODE": "semi",
        "MCP_LANGUAGE": "zh-CN"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}
```

也可以直接使用 `uvx`，无需预先安装：

```json
{
  "mcpServers": {
    "mcp-ai-supervisor": {
      "command": "uvx",
      "args": ["mcp-ai-supervisor"],
      "timeout": 600
    }
  }
}
```

### 方式二：脚本安装

```bash
# 一键远程安装
curl -fsSL https://gitlab.alibaba-inc.com/AIPlayer_TaoJp/mcp-ai-supervisor/raw/main/scripts/install.sh | bash

# 或本地安装
git clone https://gitlab.alibaba-inc.com/AIPlayer_TaoJp/mcp-ai-supervisor.git
cd mcp-ai-supervisor && ./scripts/install.sh
```

### 方式三：手动配置

编辑 `~/.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "mcp-ai-supervisor": {
      "command": "/path/to/mcp-ai-supervisor/.venv/bin/python",
      "args": ["-m", "mcp_ai_supervisor"],
      "timeout": 600,
      "env": {
        "MCP_DESKTOP_MODE": "true",
        "MCP_DELEGATE_MODE": "semi",
        "MCP_LANGUAGE": "zh-CN"
      },
      "autoApprove": ["interactive_feedback"]
    }
  }
}
```

**关键说明**：
- `command` 必须指向项目 `.venv/bin/python`（项目虚拟环境中的 Python）
- `args` 使用 `-m mcp_ai_supervisor` 启动 MCP Server
- 安装后运行 `bash scripts/verify.sh` 验证配置是否正确
- 完整环境变量参考见 [配置与部署文档](docs/项目介绍/08-配置与部署.md)

## 三种模式对比

| 模式 | 用户介入 | Agent 评估 | 适用场景 |
|------|----------|-----------|----------|
| **semi**（默认） | 弹窗倒计时，可随时介入 | 倒计时到期后自动触发 | 日常开发 |
| **auto** | 无 UI 弹窗 | 每轮必须评估 | 批量任务、夜间跑批 |
| **manual** | 每次等待用户输入 | 用户可选触发 | 精细控制场景 |

---

## 系统架构

系统分为 **MCP Server**、**Workbench 后端**、**Workbench 前端**、**桌面弹窗** 四大部分：

```
┌──────────────────────────────────────────────────────────┐
│                   Cursor / IDE 中的 AI                     │
│         调用 interactive_feedback MCP 工具                  │
└───────────────────────┬──────────────────────────────────┘
                        │ MCP Protocol (stdio)
┌───────────────────────▼──────────────────────────────────┐
│         MCP Server (packages/mcp-server)                   │
│   • interactive_feedback / get_system_info                 │
│   • DelegateManager 核心编排                                │
│   • WorkbenchClient → 上报消息到 Workbench                  │
└───────────────────────┬──────────────────────────────────┘
                        │ HTTP API
┌───────────────────────▼──────────────────────────────────┐
│      Workbench Server (packages/workbench-server)          │
│   ┌─────────────┬──────────────┬──────────────────────┐   │
│   │ AgentRegistry│ ProjectQueue │ ConversationStore    │   │
│   │ UnreadTracker│ WSManager    │ LogWriter/Parser     │   │
│   └─────────────┴──────────────┴──────────────────────┘   │
│   REST API: /api/projects, /api/messages, /api/queue ...   │
│   WebSocket: /ws (init_snapshot, new_message, ...)         │
└───────────────────────┬──────────────────────────────────┘
                        │ HTTP + WebSocket
┌───────────────────────▼──────────────────────────────────┐
│       Workbench UI (packages/workbench-ui)                 │
│   React 19 + TypeScript + Vite                              │
│   状态管理: useReducer + Context                             │
│   实时通信: WebSocket (自动重连/心跳)                          │
│   组件: ProjectList / MessageList / QueuePanel / LogViewer  │
└──────────────────────────────────────────────────────────┘
```

## 项目结构

```
mcp-ai-supervisor/                     # Monorepo (uv workspace)
├── packages/                          # 5 个子包
│   ├── core/                          # mcp-supervisor-core：基础设施（日志/路径/i18n/错误处理）
│   ├── mcp-server/                    # mcp-ai-supervisor：MCP Server 核心（交互反馈/Web UI）
│   ├── workbench-server/              # mcp-supervisor-workbench：Workbench 后端（多项目控制台）
│   ├── workbench-ui/                  # Workbench 前端（React 19 + TypeScript + Vite）
│   └── desktop/                       # Tauri 桌面应用（Rust + PyO3）
├── artifacts/desktop/                  # 预编译桌面应用二进制（构建产物）
├── tests/                             # 后端测试（pytest，1020+ 用例，~11s 并行）
├── scripts/                           # 安装/部署/工具脚本
│   ├── dev/                           # 开发工具（代码分析/对话提取/迁移）
│   └── test/                          # 测试工具（E2E 轮询/消息投递验证）
├── docs/                              # 项目文档
│   ├── 项目介绍/                     # 模块技术文档（渐进式阅读指南）
│   ├── 工程重构/                     # Monorepo 重构方案与进度
│   ├── 控制台方案/                   # Workbench V4.0 设计
│   ├── AI监工方案/                   # AI 监工功能设计
│   ├── 配置模板/                     # Cursor/Qoder Rule 和 Command 模板
│   ├── 相关资料/                     # 外部参考文档
│   └── temp/                         # 临时方案文档（实施完成后归档或删除）
└── .cursor/rules/                     # Cursor AI 规则配置
```

各子包的详细设计见：
- [`packages/core/README.md`](packages/core/README.md) — 基础设施包
- [`packages/mcp-server/README.md`](packages/mcp-server/README.md) — MCP Server
- [`packages/workbench-server/README.md`](packages/workbench-server/README.md) — Workbench 后端
- [`packages/workbench-ui/README.md`](packages/workbench-ui/README.md) — Workbench 前端
- [`packages/desktop/README.md`](packages/desktop/README.md) — 桌面应用

## Workbench 控制台（V4.0）

Workbench 是一个实时多项目管理面板，核心能力：

| 功能 | 说明 |
|------|------|
| **项目列表** | 实时显示在线/离线项目，WS 广播状态变化 |
| **对话消息** | AI/用户消息实时展示，支持历史翻页 |
| **消息队列** | Agent 忙碌时消息排队，空闲时自动投递，支持置顶 |
| **未读角标** | 按项目追踪未读数，切换自动标记已读 |
| **日志查看** | 多日志源、级别过滤、关键词搜索、日期切换 |
| **会话浏览** | 历史对话按日期/项目浏览，可打开本地文件夹 |
| **主题切换** | dark / light / system 三种主题 |
| **WebSocket** | init_snapshot、5 种上行、心跳保活、自动重连 |

详细架构文档见 [11-Workbench 控制台](docs/项目介绍/11-Workbench控制台.md)。

### 启动 Workbench

```bash
# 1. 启动后端服务（端口 9765）
.venv/bin/python3 -m mcp_supervisor_workbench --port 9765

# 2. 启动前端开发服务器（端口 9766）
cd packages/workbench-ui && npm run dev
```

前端通过 Vite proxy 将 `/api/*` 和 `/ws` 请求转发到后端。详见 [packages/workbench-ui/README.md](packages/workbench-ui/README.md)。

### Workbench 设计文档

| 文档 | 内容 |
|------|------|
| [总体设计](docs/控制台方案/技术方案/总体设计.md) | 架构总览与数据流 |
| [后端架构](docs/控制台方案/技术方案/后端架构/README.md) | 6 大核心模块设计 |
| [前端架构](docs/控制台方案/技术方案/前端架构/README.md) | 状态管理/组件/Hooks/WebSocket |
| [API 设计](docs/控制台方案/技术方案/API/README.md) | 8 组 API（A1-A8）规范 |
| [日志系统](docs/控制台方案/技术方案/日志系统/README.md) | LogWriter/Parser/Tailer/API |
| [落地实施顺序](docs/控制台方案/落地实施顺序.md) | 5 阶段实施路线图 |
| [系统集成分析](docs/控制台方案/系统集成完整性分析.md) | 端到端集成状态 |

## 测试

```bash
# 后端测试（pytest，1020+ 用例，~11s 并行执行）
cd /path/to/mcp-ai-supervisor
.venv/bin/python3 -m pytest          # 默认并行（-n auto）
.venv/bin/python3 -m pytest -n 0     # 串行执行
.venv/bin/python3 -m pytest -m unit  # 仅 unit 测试（876 个）

# 前端测试（vitest，210+ 用例）
cd packages/workbench-ui && npm test

# 测试优化详情见 docs/工程重构/09-后端测试优化方案.md
```

## 对话历史工具

`scripts/dev/conversation_extract.py` 用于提取、统计、搜索和管理对话历史，零外部依赖。

### 查看项目列表

```bash
python scripts/dev/conversation_extract.py list
```

### 提取对话内容

以 AI 问 + 用户答的成对方式清晰展示完整对话：

```bash
# 今天的对话（默认 pair 模式，AI/用户成对展示）
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --today

# 最近 3 天
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --days 3

# 只看用户回复
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --today --mode user

# 只看 AI 回复
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --today --mode ai

# 看原始任务列表
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --today --mode task

# 按日期范围
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --from 07-10 --to 07-15

# 输出到文件（支持 text / json / markdown / csv）
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --days 7 --format json -o output.json
python scripts/dev/conversation_extract.py extract mcp-ai-supervisor --days 7 --format markdown -o report.md

# 项目支持模糊匹配：名称、hash、序号均可
python scripts/dev/conversation_extract.py extract 1 --today          # 用序号
python scripts/dev/conversation_extract.py extract tao --days 3       # 模糊匹配
```

### 查看统计

```bash
# 项目统计（按天汇总会话数/轮次/来源分布/高频修改文件）
python scripts/dev/conversation_extract.py stats mcp-ai-supervisor --days 7

# 全局统计（所有项目活跃度排名 + 柱状图）
python scripts/dev/conversation_extract.py stats --days 7
```

### 搜索对话

```bash
# 全局搜索
python scripts/dev/conversation_extract.py search "心跳"

# 限定项目搜索
python scripts/dev/conversation_extract.py search "心跳" mcp-ai-supervisor --today

# 正则搜索
python scripts/dev/conversation_extract.py search "bug|fix" --regex
```

### 删除对话数据

```bash
# 删除整个项目数据（交互确认）
python scripts/dev/conversation_extract.py delete dir

# 删除指定日期范围
python scripts/dev/conversation_extract.py delete dir --days 30       # 删除最近 30 天
python scripts/dev/conversation_extract.py delete dir --from 07-01 --to 07-10

# 跳过确认
python scripts/dev/conversation_extract.py delete dir --days 30 -y
```

## 其他辅助工具

| 命令 | 说明 |
|------|------|
| `bash scripts/verify.sh` | 验证安装完整性 |
| `bash scripts/view_logs.sh` | 查看日志指引 |
| `bash scripts/uninstall.sh` | 完全卸载 |

## 深入了解

项目按模块组织了详细的技术文档，建议按以下顺序渐进式阅读：

| 顺序 | 文档 | 内容 | 建议阅读时机 |
|------|------|------|-------------|
| 0 | [项目概述](docs/项目介绍/README.md) | 架构总览、模块关系图 | 初次了解项目 |
| 1 | [MCP 服务层](docs/项目介绍/01-MCP服务层.md) | server.py、工具定义、编码初始化 | 理解入口和 MCP 协议 |
| 2 | [核心编排引擎](docs/项目介绍/02-核心编排引擎.md) | DelegateManager、TaskState、模式分发 | 理解核心逻辑 |
| 3 | [监工 Agent 系统](docs/项目介绍/03-监工Agent系统.md) | AgentBridge、AutoResponder、评估流程 | 理解 Agent 评估机制 |
| 4 | [Web 通信层](docs/项目介绍/04-Web通信层.md) | FastAPI、WebSocket、REST API | 理解前后端通信 |
| 5 | [前端 UI](docs/项目介绍/05-前端UI.md) | JS 模块架构、模板系统 | 需要修改弹窗 UI 时 |
| 6 | [桌面应用](docs/项目介绍/06-桌面应用.md) | Tauri、Rust-Python 桥接 | 需要修改桌面弹窗时 |
| 7 | [基础设施](docs/项目介绍/07-基础设施.md) | 资源管理、内存监控、日志、错误处理、i18n | 需要了解底层机制时 |
| 8 | [配置与部署](docs/项目介绍/08-配置与部署.md) | 环境变量、MCP 配置、安装脚本 | 部署或自定义配置时 |
| 11 | [Workbench 控制台](docs/项目介绍/11-Workbench控制台.md) | Workbench 后端/前端架构、消息队列、WebSocket | 需要了解 Workbench 时 |

## Cursor MCP 进程机制

Cursor 在启动时会为配置了 MCP 的项目创建 MCP 进程（通过 stdio 协议）。以下是关键机制：

- **进程共享**：同一个 Cursor 窗口中的多个 Agent 对话 **共享同一个 MCP 进程**。不同项目如果在同一个 Cursor 窗口中打开，也共享同一个 MCP 进程
- **Web Server 端口**：MCP 进程启动时会绑定一个动态端口（`port=0` 由 OS 分配），用于接收 Workbench 投递的用户消息。所有项目共用同一个 `web_url`
- **进程重启**：部署脚本 (`deploy.sh`) 通过修改 `~/.cursor/mcp.json` 中的 `MCP_RELOAD_TS` 环境变量触发 Cursor 重启 MCP 进程。旧进程会短暂残留，新进程逐步替代
- **Agent 注册**：每个项目在调用 `interactive_feedback` 时自动向 Workbench 注册 Agent，上报 `project_directory`、`agent_id`、`web_url` 等信息，Workbench 通过 `project_directory` 区分不同项目
- **心跳**：MCP 进程内的 `WorkbenchClient` 每 30 秒发送心跳；Workbench 的 `AgentRegistry` 在 90 秒无心跳后标记 Agent 为 offline

## 项目规则

1. **所有文档统一存放在 `docs/` 目录下**，按主题组织子目录
2. **文档采用渐进式写法**：主文档写概要并链接子文档，子文档详细展开
3. **文件名使用中文**，便于快速识别内容
4. **代码注释使用中文**，核心方法需要有注释，类文件头部要有注释

## 技术栈

- **后端**: Python 3.11+, FastMCP, FastAPI, WebSocket, aiohttp
- **Workbench 前端**: React 19, TypeScript, Vite 8, CSS Modules
- **原版弹窗前端**: HTML/CSS/JS（模块化 IIFE）
- **桌面**: Tauri (Rust), 预编译二进制
- **测试**: pytest (后端 1020+), vitest + @testing-library/react (前端 210+)
- **协议**: MCP (Model Context Protocol)

## 许可证

MIT License
