kai/ColaFlow

Fork 0

Files

Yaojia Wang 34a379750f

Code Coverage / Generate Coverage Report (push) Has been cancelled

Details

Tests / Run Tests (9.0.x) (push) Has been cancelled

Details

Tests / Docker Build Test (push) Has been cancelled

Details

Tests / Test Summary (push) Has been cancelled

Details

Clean up

2025-11-15 08:58:48 +01:00

30 KiB

Raw Blame History

AI + Human 协作 Demo 指南

概述

本文档演示 ColaFlow 的核心特性：AI 通过 MCP 协议安全地读写项目数据，人类通过审批机制保持对系统的控制权。

Demo 场景：AI 助手读取项目信息，提议创建一个新 Epic，人类审批后系统执行变更。

1. 环境准备

1.1 启动后端服务

cd colaflow-api
dotnet run

后端服务运行在 http://localhost:5000（或 https://localhost:5001）

1.2 启动前端服务

cd colaflow-web
npm run dev

前端服务运行在 http://localhost:3000

1.3 创建测试用户

# 注册测试用户
curl -X POST http://localhost:5000/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "demo_user",
    "email": "demo@colaflow.com",
    "password": "Demo@12345"
  }'

1.4 登录获取 JWT Token

curl -X POST http://localhost:5000/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "demo@colaflow.com",
    "password": "Demo@12345"
  }'

响应示例：

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-uuid",
    "username": "demo_user",
    "email": "demo@colaflow.com"
  }
}

保存返回的 token，后续所有请求需要使用。

1.5 创建测试项目

curl -X POST http://localhost:5000/api/projects \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ColaFlow Demo",
    "key": "DEMO",
    "description": "AI + Human 协作演示项目"
  }'

响应示例：

{
  "id": "project-uuid",
  "name": "ColaFlow Demo",
  "key": "DEMO",
  "description": "AI + Human 协作演示项目"
}

保存返回的 id，后续步骤需要使用。

1.6 创建 MCP API Key

curl -X POST http://localhost:5000/api/mcp/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "AI Assistant Demo",
    "description": "用于演示 AI 协作功能",
    "expiresInDays": 30
  }'

响应示例：

{
  "id": "key-uuid",
  "name": "AI Assistant Demo",
  "key": "mcp_live_1234567890abcdef",
  "createdAt": "2025-11-09T10:00:00Z",
  "expiresAt": "2025-12-09T10:00:00Z"
}

重要：保存返回的 key，这是 AI 调用 MCP 协议的凭证，只显示一次！

2. 完整 Demo 流程（7步）

Step 1: AI 连接和认证

AI 客户端使用 MCP API Key 连接到 ColaFlow MCP Server。

测试连接：

curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {
        "roots": {
          "listChanged": true
        }
      },
      "clientInfo": {
        "name": "ColaFlow AI Assistant",
        "version": "1.0.0"
      }
    },
    "id": 1
  }'

响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "resources": {},
      "tools": {}
    },
    "serverInfo": {
      "name": "ColaFlow MCP Server",
      "version": "1.0.0"
    }
  },
  "id": 1
}

Step 2: AI 读取项目数据

2.1 列出可用资源

curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "resources/list",
    "id": 2
  }'

响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "resources": [
      {
        "uri": "colaflow://projects/project-uuid",
        "name": "Project: ColaFlow Demo",
        "description": "项目详情和配置",
        "mimeType": "application/json"
      },
      {
        "uri": "colaflow://projects/project-uuid/epics",
        "name": "Epics in ColaFlow Demo",
        "description": "项目的所有 Epic",
        "mimeType": "application/json"
      }
    ]
  },
  "id": 2
}

2.2 读取项目详情

curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "resources/read",
    "params": {
      "uri": "colaflow://projects/project-uuid"
    },
    "id": 3
  }'

响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "contents": [
      {
        "uri": "colaflow://projects/project-uuid",
        "mimeType": "application/json",
        "text": "{\"id\":\"project-uuid\",\"name\":\"ColaFlow Demo\",\"key\":\"DEMO\",\"description\":\"AI + Human 协作演示项目\",\"epicCount\":0,\"storyCount\":0,\"taskCount\":0}"
      }
    ]
  },
  "id": 3
}

2.3 读取项目的 Epic 列表

curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "resources/read",
    "params": {
      "uri": "colaflow://projects/project-uuid/epics"
    },
    "id": 4
  }'

响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "contents": [
      {
        "uri": "colaflow://projects/project-uuid/epics",
        "mimeType": "application/json",
        "text": "{\"epics\":[]}"
      }
    ]
  },
  "id": 4
}

Step 3: AI 提议创建 Epic

AI 分析项目数据后，决定创建一个新的 Epic。

3.1 列出可用工具

curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 5
  }'

响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "create_issue",
        "description": "创建新的 Epic、Story 或 Task",
        "inputSchema": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": ["EPIC", "STORY", "TASK"],
              "description": "Issue 类型"
            },
            "title": {
              "type": "string",
              "description": "Issue 标题"
            },
            "description": {
              "type": "string",
              "description": "Issue 描述"
            },
            "project_id": {
              "type": "string",
              "description": "项目 ID（Epic 必需）"
            },
            "epic_id": {
              "type": "string",
              "description": "Epic ID（Story 必需）"
            },
            "story_id": {
              "type": "string",
              "description": "Story ID（Task 必需）"
            }
          },
          "required": ["type", "title"]
        }
      }
    ]
  },
  "id": 5
}

3.2 调用 create_issue Tool

curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "create_issue",
      "arguments": {
        "type": "EPIC",
        "title": "用户认证系统",
        "description": "实现用户注册、登录、JWT 认证和 OAuth 集成功能",
        "project_id": "project-uuid"
      }
    },
    "id": 6
  }'

Step 4: 系统生成 Diff Preview 和 PendingChange

系统接收到 AI 的创建请求后，不会立即执行，而是：

生成 Diff Preview：显示即将发生的变更
创建 PendingChange：等待人类审批
返回响应给 AI

响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "已创建待审批的变更请求。\n\nPendingChange ID: pending-change-uuid\n状态: PENDING\n\n变更预览:\n=== 新建 Epic ===\n标题: 用户认证系统\n描述: 实现用户注册、登录、JWT 认证和 OAuth 集成功能\n项目: ColaFlow Demo (DEMO)\n\n此变更需要人类审批后才会执行。"
      }
    ],
    "isError": false
  },
  "id": 6
}

系统内部流程：

创建 PendingChange 记录（状态：PENDING）
生成 Diff Preview JSON
触发 SignalR 实时通知到前端

Step 5: 前端收到 SignalR 实时通知

前端通过 SignalR 实时接收到新的 PendingChange 通知。

5.1 SignalR 连接示例（JavaScript）

// 在前端应用中建立 SignalR 连接
import * as signalR from "@microsoft/signalr";

const connection = new signalR.HubConnectionBuilder()
  .withUrl("http://localhost:5000/hubs/mcp", {
    accessTokenFactory: () => "YOUR_JWT_TOKEN"
  })
  .withAutomaticReconnect()
  .build();

// 监听 PendingChange 事件
connection.on("PendingChangeCreated", (pendingChange) => {
  console.log("新的待审批变更:", pendingChange);

  // 显示通知
  showNotification({
    title: "AI 提议新变更",
    message: `${pendingChange.operation}: ${pendingChange.metadata.title}`,
    action: "查看详情"
  });

  // 更新 UI
  updatePendingChangesList(pendingChange);
});

connection.on("PendingChangeApproved", (pendingChange) => {
  console.log("变更已审批:", pendingChange);
  showNotification({
    title: "变更已执行",
    message: `Epic "${pendingChange.metadata.title}" 已创建`,
    type: "success"
  });
});

connection.on("PendingChangeRejected", (pendingChange) => {
  console.log("变更已拒绝:", pendingChange);
  showNotification({
    title: "变更已拒绝",
    message: `AI 提议的变更已被拒绝`,
    type: "warning"
  });
});

// 启动连接
await connection.start();
console.log("SignalR 已连接");

5.2 前端 UI 显示

前端收到通知后，应显示：

PendingChange 列表项：

┌─────────────────────────────────────────────────┐
│ 🤖 AI 提议新变更 - 等待审批                     │
├─────────────────────────────────────────────────┤
│ 操作: CREATE_EPIC                                │
│ 标题: 用户认证系统                               │
│ 描述: 实现用户注册、登录、JWT 认证和 OAuth...   │
│ 项目: ColaFlow Demo (DEMO)                       │
│ 时间: 2025-11-09 10:30:25                        │
│                                                   │
│ [查看详情] [批准] [拒绝]                         │
└─────────────────────────────────────────────────┘

Diff Preview 对话框：

{
  "operation": "CREATE_EPIC",
  "before": null,
  "after": {
    "title": "用户认证系统",
    "description": "实现用户注册、登录、JWT 认证和 OAuth 集成功能",
    "project_id": "project-uuid",
    "project_name": "ColaFlow Demo",
    "status": "TODO"
  },
  "changes": [
    "+ Epic: 用户认证系统",
    "+ 项目: ColaFlow Demo (DEMO)",
    "+ 状态: TODO"
  ]
}

Step 6: 人类审批变更

用户在前端点击 "批准" 或 "拒绝" 按钮。

6.1 获取 PendingChange 列表

curl -X GET http://localhost:5000/api/mcp/pending-changes \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

响应示例：

{
  "items": [
    {
      "id": "pending-change-uuid",
      "mcpApiKeyId": "key-uuid",
      "operation": "CREATE_EPIC",
      "status": "PENDING",
      "metadata": {
        "type": "EPIC",
        "title": "用户认证系统",
        "description": "实现用户注册、登录、JWT 认证和 OAuth 集成功能",
        "project_id": "project-uuid"
      },
      "diffPreview": "{\"operation\":\"CREATE_EPIC\",\"after\":{...}}",
      "createdAt": "2025-11-09T10:30:25Z"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

6.2 获取 PendingChange 详情

curl -X GET http://localhost:5000/api/mcp/pending-changes/pending-change-uuid \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

6.3 批准变更

curl -X POST http://localhost:5000/api/mcp/pending-changes/pending-change-uuid/approve \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

响应示例：

{
  "id": "pending-change-uuid",
  "status": "APPROVED",
  "approvedAt": "2025-11-09T10:35:00Z",
  "approvedBy": "user-uuid",
  "executedAt": "2025-11-09T10:35:00Z",
  "resultData": {
    "epic_id": "epic-uuid",
    "epic_key": "DEMO-1",
    "title": "用户认证系统"
  }
}

6.4 拒绝变更（可选）

curl -X POST http://localhost:5000/api/mcp/pending-changes/pending-change-uuid/reject \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "需要更详细的需求描述"
  }'

响应示例：

{
  "id": "pending-change-uuid",
  "status": "REJECTED",
  "rejectedAt": "2025-11-09T10:35:00Z",
  "rejectedBy": "user-uuid",
  "rejectionReason": "需要更详细的需求描述"
}

Step 7: 系统执行变更并通知 AI

人类批准后，系统自动执行以下流程：

执行变更：调用业务逻辑创建 Epic
更新 PendingChange 状态：APPROVED + 记录执行结果
SignalR 通知前端：PendingChangeApproved 事件
（可选）通知 AI：通过回调机制通知 AI 变更已执行

系统内部流程：

// PendingChangeService.ApproveAsync()
public async Task<PendingChange> ApproveAsync(Guid id, Guid userId)
{
    var pendingChange = await GetByIdAsync(id);

    // 1. 执行变更
    var result = await _changeExecutor.ExecuteAsync(pendingChange);

    // 2. 更新状态
    pendingChange.Approve(userId, result);
    await _repository.UpdateAsync(pendingChange);

    // 3. 通知前端
    await _hubContext.Clients.User(userId.ToString())
        .SendAsync("PendingChangeApproved", pendingChange);

    return pendingChange;
}

AI 可以查询执行结果：

curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "resources/read",
    "params": {
      "uri": "colaflow://projects/project-uuid/epics"
    },
    "id": 7
  }'

响应示例：

{
  "jsonrpc": "2.0",
  "result": {
    "contents": [
      {
        "uri": "colaflow://projects/project-uuid/epics",
        "mimeType": "application/json",
        "text": "{\"epics\":[{\"id\":\"epic-uuid\",\"key\":\"DEMO-1\",\"title\":\"用户认证系统\",\"description\":\"实现用户注册、登录、JWT 认证和 OAuth 集成功能\",\"status\":\"TODO\",\"createdAt\":\"2025-11-09T10:35:00Z\"}]}"
      }
    ]
  },
  "id": 7
}

3. 演示要点

3.1 安全性：Human-in-the-Loop

核心机制：

AI 不能直接修改数据，所有写操作必须经过人类审批
PendingChange 作为安全隔离层
审批权限基于用户角色和项目权限

演示重点：

展示 AI 调用 create_issue 后，数据库中没有立即创建 Epic
展示 PendingChange 表中的待审批记录（状态：PENDING）
展示人类审批后，Epic 才真正创建

SQL 查询示例：

-- 查看 PendingChange
SELECT * FROM PendingChanges WHERE Status = 'PENDING';

-- 查看 Epics（审批前应为空）
SELECT * FROM Epics WHERE ProjectId = 'project-uuid';

-- 人类批准后再查看
SELECT * FROM Epics WHERE ProjectId = 'project-uuid';
-- 应该看到新创建的 Epic

3.2 透明性：Diff Preview

核心机制：

每个 PendingChange 都包含 diffPreview JSON
清晰展示变更前后的对比
支持复杂变更（UPDATE、DELETE）

Diff Preview 结构：

{
  "operation": "CREATE_EPIC",
  "before": null,  // CREATE 操作 before 为 null
  "after": {
    "title": "用户认证系统",
    "description": "实现用户注册、登录、JWT 认证和 OAuth 集成功能",
    "project_id": "project-uuid",
    "project_name": "ColaFlow Demo",
    "status": "TODO"
  },
  "changes": [
    "+ Epic: 用户认证系统",
    "+ 项目: ColaFlow Demo (DEMO)",
    "+ 状态: TODO"
  ]
}

UPDATE 操作示例：

{
  "operation": "UPDATE_EPIC",
  "before": {
    "title": "用户认证系统",
    "status": "TODO"
  },
  "after": {
    "title": "用户认证系统 v2.0",
    "status": "IN_PROGRESS"
  },
  "changes": [
    "~ 标题: 用户认证系统 → 用户认证系统 v2.0",
    "~ 状态: TODO → IN_PROGRESS"
  ]
}

3.3 实时性：SignalR

核心机制：

前端通过 SignalR 实时接收变更通知
支持多用户协作场景
减少轮询，提升性能

演示场景：

单用户场景：
- 用户 A 创建 API Key 给 AI
- AI 提议变更
- 用户 A 立即收到通知（浏览器右上角弹窗）
多用户场景：
- 用户 A 创建 API Key 给 AI
- AI 提议变更
- 用户 A 和用户 B（同一项目成员）都收到通知
- 用户 B 先批准
- 用户 A 看到变更已执行的通知

SignalR 事件流程：

AI 调用 Tool
    ↓
PendingChange 创建
    ↓
SignalR: PendingChangeCreated → 前端显示通知
    ↓
人类批准
    ↓
PendingChange 执行
    ↓
SignalR: PendingChangeApproved → 前端更新 UI

3.4 多租户隔离

核心机制：

每个 MCP API Key 关联一个用户
PendingChange 只能由 Key 的所有者审批
跨项目隔离（用户只能访问自己的项目）

演示验证：

# 用户 A 创建 API Key
curl -X POST http://localhost:5000/api/mcp/keys \
  -H "Authorization: Bearer USER_A_JWT_TOKEN" \
  -d '{"name": "AI Key A"}'

# AI 使用 Key A 创建变更
curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_key_a" \
  -d '{...}'

# 用户 B 尝试批准（应该失败 - 403 Forbidden）
curl -X POST http://localhost:5000/api/mcp/pending-changes/{id}/approve \
  -H "Authorization: Bearer USER_B_JWT_TOKEN"

# 用户 A 批准（成功）
curl -X POST http://localhost:5000/api/mcp/pending-changes/{id}/approve \
  -H "Authorization: Bearer USER_A_JWT_TOKEN"

4. 前端界面演示建议

4.1 MCP Dashboard 页面

位置：/mcp/dashboard

功能区域：

API Keys 管理
- 列表显示所有 API Keys
- 创建新 Key 按钮
- 删除/禁用 Key 操作
待审批变更列表
- 实时更新（SignalR）
- 过滤：ALL / PENDING / APPROVED / REJECTED
- 排序：创建时间、状态
变更详情对话框
- Diff Preview 可视化
- 批准/拒绝按钮
- 变更历史记录

截图建议：

截图1：MCP Dashboard 主界面（显示 3 个 API Keys，2 个待审批变更）
截图2：点击 "查看详情" 后的 Diff Preview 对话框
截图3：批准后的成功通知（右上角 Toast）

4.2 PendingChange 卡片设计

┌─────────────────────────────────────────────────────────────┐
│ 🤖 AI Assistant Demo                      ⏰ 2 分钟前       │
├─────────────────────────────────────────────────────────────┤
│ 操作: CREATE_EPIC                           状态: ⏳ 待审批  │
│                                                               │
│ 📝 标题: 用户认证系统                                        │
│ 📋 描述: 实现用户注册、登录、JWT 认证和 OAuth 集成功能      │
│ 📁 项目: ColaFlow Demo (DEMO)                                │
│                                                               │
│ ┌─────────────────────────────────────────┐                 │
│ │ Diff Preview:                            │                 │
│ │ + Epic: 用户认证系统                    │                 │
│ │ + 项目: ColaFlow Demo (DEMO)            │                 │
│ │ + 状态: TODO                             │                 │
│ └─────────────────────────────────────────┘                 │
│                                                               │
│ [🔍 查看详情]  [✅ 批准]  [❌ 拒绝]                          │
└─────────────────────────────────────────────────────────────┘

4.3 实时通知设计

Toast 通知（右上角）：

新变更通知：

┌─────────────────────────────────────┐
│ 🤖 AI 提议新变更                    │
│ CREATE_EPIC: 用户认证系统           │
│ [查看] [批准] [关闭]                │
└─────────────────────────────────────┘

批准成功通知：

┌─────────────────────────────────────┐
│ ✅ 变更已执行                       │
│ Epic "用户认证系统" 已创建          │
│ [查看 Epic] [关闭]                  │
└─────────────────────────────────────┘

5. 高级演示场景

5.1 批量操作：AI 创建多个 Story

场景描述： AI 读取 Epic "用户认证系统" 后，提议创建 3 个 Story。

AI 调用：

# Story 1: 用户注册
curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "create_issue",
      "arguments": {
        "type": "STORY",
        "title": "用户注册功能",
        "description": "实现邮箱注册、密码强度验证、邮箱验证",
        "epic_id": "epic-uuid"
      }
    },
    "id": 10
  }'

# Story 2: 用户登录
curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "create_issue",
      "arguments": {
        "type": "STORY",
        "title": "用户登录功能",
        "description": "实现 JWT Token 登录、Remember Me、多端登录",
        "epic_id": "epic-uuid"
      }
    },
    "id": 11
  }'

# Story 3: OAuth 集成
curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "create_issue",
      "arguments": {
        "type": "STORY",
        "title": "OAuth 第三方登录",
        "description": "集成 GitHub、Google、Microsoft OAuth 登录",
        "epic_id": "epic-uuid"
      }
    },
    "id": 12
  }'

演示要点：

前端同时收到 3 个 PendingChange 通知
人类可以选择性批准（例如：批准 Story 1 和 2，拒绝 Story 3）
展示批量审批功能（勾选多个 → 批量批准）

5.2 UPDATE 操作：AI 更新 Epic 状态

场景描述： AI 检测到 Epic 下所有 Story 已完成，提议将 Epic 状态更新为 DONE。

AI 调用：

curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "update_issue",
      "arguments": {
        "issue_id": "epic-uuid",
        "status": "DONE"
      }
    },
    "id": 20
  }'

Diff Preview：

{
  "operation": "UPDATE_EPIC",
  "before": {
    "id": "epic-uuid",
    "key": "DEMO-1",
    "title": "用户认证系统",
    "status": "IN_PROGRESS",
    "completedStories": 3,
    "totalStories": 3
  },
  "after": {
    "id": "epic-uuid",
    "key": "DEMO-1",
    "title": "用户认证系统",
    "status": "DONE",
    "completedStories": 3,
    "totalStories": 3
  },
  "changes": [
    "~ 状态: IN_PROGRESS → DONE"
  ]
}

5.3 DELETE 操作：AI 删除重复 Task

场景描述： AI 检测到有重复的 Task，提议删除。

AI 调用：

curl -X POST http://localhost:5000/mcp \
  -H "Authorization: Bearer mcp_live_1234567890abcdef" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "delete_issue",
      "arguments": {
        "issue_id": "task-uuid"
      }
    },
    "id": 30
  }'

Diff Preview：

{
  "operation": "DELETE_TASK",
  "before": {
    "id": "task-uuid",
    "key": "DEMO-1-1",
    "title": "设计数据库 Schema",
    "status": "TODO",
    "story": "用户注册功能"
  },
  "after": null,
  "changes": [
    "- Task: 设计数据库 Schema (DEMO-1-1)",
    "- 从 Story: 用户注册功能 中删除"
  ]
}

安全考虑：

DELETE 操作应该有更严格的审批流程
可以设置规则：某些类型的变更需要多人审批
可以设置时间窗口：DELETE 操作需要等待 24 小时后才能执行

6. 监控和审计

6.1 Audit Log

所有 MCP 操作都应记录在 AuditLogs 表中。

查询示例：

curl -X GET "http://localhost:5000/api/audit-logs?entityType=PendingChange&page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

响应示例：

{
  "items": [
    {
      "id": "log-uuid-1",
      "entityType": "PendingChange",
      "entityId": "pending-change-uuid",
      "action": "CREATED",
      "performedBy": "AI Assistant Demo (MCP Key)",
      "performedAt": "2025-11-09T10:30:25Z",
      "metadata": {
        "operation": "CREATE_EPIC",
        "title": "用户认证系统"
      }
    },
    {
      "id": "log-uuid-2",
      "entityType": "PendingChange",
      "entityId": "pending-change-uuid",
      "action": "APPROVED",
      "performedBy": "demo_user",
      "performedAt": "2025-11-09T10:35:00Z",
      "metadata": {
        "approver_id": "user-uuid"
      }
    },
    {
      "id": "log-uuid-3",
      "entityType": "Epic",
      "entityId": "epic-uuid",
      "action": "CREATED",
      "performedBy": "System (via PendingChange)",
      "performedAt": "2025-11-09T10:35:00Z",
      "metadata": {
        "pending_change_id": "pending-change-uuid",
        "key": "DEMO-1",
        "title": "用户认证系统"
      }
    }
  ],
  "total": 3
}

6.2 MCP Analytics

Dashboard 指标：

总 API 调用次数
PendingChange 批准率
平均审批时长
AI 提议的准确率（被批准的比例）

查询示例：

curl -X GET "http://localhost:5000/api/mcp/analytics?startDate=2025-11-01&endDate=2025-11-30" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

响应示例：

{
  "totalApiCalls": 1523,
  "totalPendingChanges": 87,
  "approvedChanges": 72,
  "rejectedChanges": 10,
  "pendingChanges": 5,
  "approvalRate": 0.828,
  "averageApprovalTime": "00:05:32",
  "topOperations": [
    {"operation": "CREATE_TASK", "count": 45},
    {"operation": "UPDATE_TASK", "count": 20},
    {"operation": "CREATE_STORY", "count": 12}
  ]
}

7. 常见问题排查

7.1 SignalR 连接失败

问题：前端无法连接到 SignalR Hub

检查：

# 1. 检查后端 SignalR 配置
# Program.cs 中应该有：
builder.Services.AddSignalR();
app.MapHub<McpHub>("/hubs/mcp");

# 2. 检查 CORS 配置
# 确保允许 SignalR 所需的 Headers
app.UseCors(policy => policy
    .WithOrigins("http://localhost:3000")
    .AllowAnyHeader()
    .AllowAnyMethod()
    .AllowCredentials()); // SignalR 需要

# 3. 测试连接
# 浏览器控制台应该看到：
# SignalR: Connection started

7.2 MCP API Key 认证失败

问题：AI 调用 MCP 接口返回 401 Unauthorized

检查：

# 1. 验证 Key 格式
# 正确格式: mcp_live_xxxxxxxxxxxx
# 错误格式: xxxxxxxxxxxx (缺少前缀)

# 2. 验证 Key 是否过期
curl -X GET http://localhost:5000/api/mcp/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
# 检查 expiresAt 字段

# 3. 验证 Authorization Header
# 正确: Authorization: Bearer mcp_live_xxxxxxxxxxxx
# 错误: Authorization: mcp_live_xxxxxxxxxxxx (缺少 Bearer)

7.3 PendingChange 执行失败

问题：批准 PendingChange 后返回 500 错误

检查：

# 1. 查看后端日志
# 应该有详细的错误堆栈

# 2. 检查数据完整性
# 例如：Epic 关联的 Project 是否存在
SELECT * FROM Projects WHERE Id = 'project-uuid';

# 3. 检查业务逻辑验证
# 例如：Story 必须关联到 Epic
# Task 必须关联到 Story

8. 总结

本 Demo 展示了 ColaFlow 的核心创新：AI + Human 协作的项目管理模式。

关键价值：

安全可控：Human-in-the-Loop 确保 AI 不会失控
透明可信：Diff Preview 让人类清晰了解 AI 的提议
高效协作：实时通知让人类快速响应 AI 的请求
可审计性：完整的操作日志确保合规性

下一步：

集成 Claude/ChatGPT MCP 客户端
实现更复杂的 Prompt 工程（智能拆解需求）
支持批量审批和审批规则引擎
实现 AI 自主学习（根据历史审批记录优化提议）

演示清单：

环境准备（后端、前端、数据库）
创建测试用户和项目
创建 MCP API Key
AI 读取项目数据
AI 提议创建 Epic
前端收到 SignalR 通知
人类查看 Diff Preview
人类批准变更
验证 Epic 已创建
查看 Audit Log

预计演示时长：15-20 分钟

30 KiB Raw Blame History Unescape Escape

AI + Human 协作 Demo 指南

概述

1. 环境准备

1.1 启动后端服务

1.2 启动前端服务

1.3 创建测试用户

1.4 登录获取 JWT Token

1.5 创建测试项目

1.6 创建 MCP API Key

2. 完整 Demo 流程（7步）

Step 1: AI 连接和认证

Step 2: AI 读取项目数据

2.1 列出可用资源

2.2 读取项目详情

2.3 读取项目的 Epic 列表

Step 3: AI 提议创建 Epic

3.1 列出可用工具

3.2 调用 create_issue Tool

Step 4: 系统生成 Diff Preview 和 PendingChange

Step 5: 前端收到 SignalR 实时通知

5.1 SignalR 连接示例（JavaScript）

5.2 前端 UI 显示

Step 6: 人类审批变更

6.1 获取 PendingChange 列表

6.2 获取 PendingChange 详情

6.3 批准变更

6.4 拒绝变更（可选）

Step 7: 系统执行变更并通知 AI

3. 演示要点

3.1 安全性：Human-in-the-Loop

3.2 透明性：Diff Preview

3.3 实时性：SignalR

3.4 多租户隔离

4. 前端界面演示建议

4.1 MCP Dashboard 页面

4.2 PendingChange 卡片设计

4.3 实时通知设计

5. 高级演示场景

5.1 批量操作：AI 创建多个 Story

5.2 UPDATE 操作：AI 更新 Epic 状态

5.3 DELETE 操作：AI 删除重复 Task

6. 监控和审计

6.1 Audit Log

6.2 MCP Analytics

7. 常见问题排查

7.1 SignalR 连接失败

7.2 MCP API Key 认证失败

7.3 PendingChange 执行失败

8. 总结

30 KiB

Raw Blame History