makemd/docs/05_AI/AI_Strategy.md

# AI Strategy (Crawlful Hub)

> **定位**：Crawlful Hub AI 策略文档 - 描述多 AI 协作方案、任务分配策略及决策流程。
> **更新日期**: 2026-03-18
> **注意**：本文档不重复 Task_Overview.md 中的任务列表，仅描述 AI 协作策略。

---

## 1. 多 AI 协作架构

### 1.1 架构概览

```
┌─────────────────────────────────────────────────────────────┐
│                     Brain (调度中心)                         │
│                  全局调度与决策                              │
└─────────────────────────────────────────────────────────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│   AI Agent 1    │  │   AI Agent 2    │  │   AI Agent N    │
│  (前端/插件)    │  │  (后端/数据)    │  │  (分析/决策)    │
└─────────────────┘  └─────────────────┘  └─────────────────┘
          │                   │                   │
          └───────────────────┼───────────────────┘
                              ▼
                    ┌──────────────────┐
                    │   Task Queue     │
                    │   (BullMQ)       │
                    └──────────────────┘
```

### 1.2 角色定义

| 角色 | 职责 | 能力范围 |
|------|------|----------|
| **Brain** | 全局调度、任务分配、冲突解决 | 不直接生成代码 |
| **AI Agent** | 原子任务包闭环开发 | 代码生成、测试、部署 |
| **AI Analyst** | 数据分析、报告生成 | 数据处理、可视化 |
| **AI Decision** | 决策支持、策略优化 | 算法、预测 |

### 1.3 协作原则

1. **一次性分发**：每轮下发完整任务包（P0/P1/P2）
2. **连续执行**：任务包内连续执行到"完成或明确阻塞"
3. **文件占用锁**：同目录协作先声明归属，"谁领取谁编辑"
4. **冲突处理**：后写入方必须先 Read 最新内容，增量合并

---

## 2. 任务分配策略

### 2.1 动态分配机制

```typescript
// 任务分配算法
interface TaskAssignment {
  taskId: string;
  agentId: string;
  priority: 'P0' | 'P1' | 'P2' | 'P3';
  capability: string[];
  estimatedTime: number;
}

// 分配策略
const assignmentStrategy = {
  // 能力匹配
  matchCapability: (task: Task, agent: Agent): boolean => {
    return task.requiredCapabilities.every(cap => 
      agent.capabilities.includes(cap)
    );
  },
  
  // 负载均衡
  balanceLoad: (agents: Agent[]): Agent => {
    return agents.reduce((min, agent) => 
      agent.activeTasks < min.activeTasks ? agent : min
    );
  },
  
  // 优先级排序
  sortByPriority: (tasks: Task[]): Task[] => {
    const priorityOrder = { P0: 0, P1: 1, P2: 2, P3: 3 };
    return tasks.sort((a, b) => 
      priorityOrder[a.priority] - priorityOrder[b.priority]
    );
  },
};
```

### 2.2 能力标签

| 能力标签 | 说明 | 适用任务 |
|----------|------|----------|
| `frontend` | 前端开发 | React, UI组件 |
| `backend` | 后端开发 | API, Service |
| `plugin` | 插件开发 | Chrome Extension |
| `database` | 数据库 | Schema, Query |
| `ai-analysis` | AI分析 | 数据分析, 报告 |
| `ai-decision` | AI决策 | 算法, 策略 |
| `devops` | 运维 | 部署, 监控 |

---

## 3. 决策流程

### 3.1 决策层级

```
Level 1: AI Agent 自主决策
  ├─ 代码实现细节
  ├─ 单元测试用例
  └─ 局部重构

Level 2: Brain 协调决策
  ├─ 跨模块接口设计
  ├─ 任务优先级调整
  └─ 资源冲突解决

Level 3: 人工确认决策
  ├─ 核心业务数据修改（调价、退款）
  ├─ 架构重大变更
  └─ 生产环境部署
```

### 3.2 决策流程门禁

```
SUGGESTED -> PENDING_REVIEW -> EXECUTED/REJECTED
```

**严禁**：AI 直接修改核心业务数据（调价、退款、下单）
**必须**：人工在 Console 端确认后方可执行

---

## 4. 自省与上报

### 4.1 自省要求

AI Agent 必须在以下阶段上报"自我问题"：

1. **对话开始时**
   - 当前任务理解
   - 依赖任务状态
   - 潜在风险点

2. **执行过程中**
   - 进度更新
   - 阻塞问题
   - 需要协调的事项

3. **交付前**
   - 功能验证结果
   - 测试覆盖率
   - 已知限制

### 4.2 上报格式

```typescript
interface SelfReport {
  stage: 'start' | 'progress' | 'delivery';
  taskId: string;
  agentId: string;
  status: 'normal' | 'blocked' | 'at-risk';
  progress: number; // 0-100
  issues: {
    type: 'dependency' | 'conflict' | 'technical' | 'resource';
    description: string;
    severity: 'low' | 'medium' | 'high';
  }[];
  nextSteps: string[];
}
```

---

## 5. 质量保障

### 5.1 代码质量门禁

| 指标 | 目标值 | 检查方式 |
|------|--------|----------|
| 测试覆盖率 | ≥ 80% | 自动化测试 |
| 类型安全 | 100% | TypeScript strict |
| 代码规范 | 0 警告 | ESLint |
| 文档完整 | 100% | JSDoc |

### 5.2 验证流程

```
代码生成
    │
    ▼
静态检查 (ESLint/TypeScript)
    │
    ▼
单元测试
    │
    ▼
集成测试
    │
    ▼
人工 Review (关键模块)
    │
    ▼
部署验证
```

---

## 6. 与 Task_Overview.md 的关系

### 6.1 职责划分

| 文档 | 职责 | 内容 |
|------|------|------|
| **Task_Overview.md** | 任务追踪 | 所有任务的详细列表、状态、依赖 |
| **AI_Strategy.md** | 策略描述 | AI 协作机制、决策流程、质量保障 |

### 6.2 避免重复

- **Task_Overview.md** 是唯一的任务源
- **AI_Strategy.md** 不重复定义任务
- **AI_Strategy.md** 描述如何执行任务的策略

---

## 7. 相关文档

- [Task Overview](../00_Business/Task_Overview.md) - 任务追踪（唯一任务源）
- [Business ClosedLoops](../00_Business/Business_ClosedLoops.md) - 业务闭环
- [System Architecture](../01_Architecture/System_Architecture.md) - 系统架构

---

*本文档描述 AI 协作策略，不重复任务列表，最后更新: 2026-03-18*