makemd/docs/05_AI/01_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. AI节点自动决策体系

### 6.1 核心理念

1. **节点化设计**：每个决策动作是一个节点（Node），节点可以是 AI 生成建议、条件判断、执行动作、通知等
2. **数据驱动**：每个节点依赖历史数据 + 实时数据来生成建议
3. **自动推进**：节点间用逻辑流或条件流连接，AI 根据上下文和规则自动选择下一节点
4. **可回溯与干预**：每个节点都有日志，初期可允许人工干预，后期高置信度节点可完全自动执行

### 6.2 节点类型

| 节点类型 | 功能 | 输入数据 | 输出数据 |
|----------|------|----------|----------|
| **决策节点（Decision Node）** | AI 根据数据生成建议或选择动作 | 历史数据、实时数据、外部数据 | JSON动作方案 + 置信度 + 风险等级 |
| **条件节点（Condition Node）** | 根据规则或状态判断执行路径 | 决策节点输出 + 实时数据 | 执行路径（自动执行/人工确认/阻止执行） |
| **执行节点（Action Node）** | 调用 API、脚本或系统操作 | 确认后的动作方案 | 执行状态（成功/失败） |
| **人工确认节点（Human Approval Node）** | 人类对 AI 建议进行修改或确认 | 决策节点输出 + 条件判断结果 + 数据参考 | 最终动作方案 |
| **日志节点（Log Node）** | 记录整个节点数据、结果 | 所有节点输入输出 | 日志记录（唯一ID，全链路追踪） |
| **历史数据更新节点** | 将执行结果回写历史库 | 执行结果 | 历史数据库更新 |
| **报表分析节点（Report/Analytics Node）** | 生成报表和趋势分析 | 历史数据 + 节点日志 | 报表、趋势分析、总结 |

### 6.3 数据分类

| 数据类别 | 内容 | 用途 |
|----------|------|------|
| **历史数据** | 广告投放历史（CTR、CVR、ROI）、价格历史、销售历史、TOB批发订单历史 | 预测调价或预算策略、判断调价幅度 |
| **实时数据** | 当前库存、价格、预算、广告状态、实时ROI、异常指标 | 决定节点是否可执行、支持条件节点判断分支 |
| **外部数据** | 节假日、竞品价格、市场趋势、供应链状态、汇率 | 影响广告投放策略和定价 |

### 6.4 决策流程门禁

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

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

---

## 7. 业务闭环设计

### 7.1 TOC（零售单笔闭环）

```
[输入数据] → [AI决策节点] → [条件判断节点] → [人工确认节点] → [执行节点]
     ↓
[日志节点] → [历史数据更新节点] → [报表分析节点] → [优化反馈节点] → 回到 [AI决策节点]
```

1. **输入数据**：单笔订单、客户历史购买、库存状态、广告数据、市场趋势
2. **决策节点**：AI 生成动作建议（是否调价、是否推荐促销、广告曝光调整）
3. **条件节点**：检查库存、预算、置信度、风险
4. **人工确认节点**（可选）：处理低置信度或高风险动作
5. **执行节点**：系统执行调价、广告调整、库存扣减
6. **日志节点**：记录每个操作和决策过程
7. **历史数据更新节点**：更新库存、销售、广告效果、ROI
8. **报表分析节点**：生成订单收益、库存波动、广告转化报表
9. **优化反馈节点**：AI 根据报表优化下一轮决策

### 7.2 TOB（批发/整柜闭环）

1. **输入数据**：批发订单、客户等级、库存、供应商状态、市场趋势
2. **决策节点**：AI 生成分配方案、价格方案、库存调拨方案
3. **条件节点**：检查库存、供应商能力、风险等级
4. **人工确认节点**：处理库存紧张或低置信度分配
5. **执行节点**：系统生成订单、调拨库存、同步 ERP
6. **日志节点**：全链路记录决策与执行状态
7. **历史数据更新节点**：回写分配结果、客户反馈、库存变化
8. **报表分析节点**：生成分配效率、库存周转率、客户满意度报表
9. **优化反馈节点**：AI 根据历史表现优化分配策略

### 7.3 功能模块闭环示例

| 功能模块 | 节点应用说明 |
|----------|--------------|
| 广告价格调节 | 决策节点生成调价方案 → 条件节点判断库存和预算 → 人工确认或自动执行 → 执行节点调整广告价格 → 日志 → 历史更新 → 报表分析 |
| 产品调价 | 决策节点生成价格建议 → 条件判断 ROI、库存 → 人工确认 → 执行调价 → 日志 → 历史更新 → 报表分析 |
| 批发订单分配 | 决策节点生成分配方案 → 条件节点判断库存和客户优先级 → 人工确认或自动分配 → 执行节点生成订单 → 日志 → 历史更新 → 报表分析 |
| 库存管理 | 决策节点预测缺货/过量 → 条件节点判断安全库存 → 人工确认 → 执行节点调拨或采购 → 日志 → 历史更新 → 报表分析 |
| 促销活动 | 决策节点生成活动策略 → 条件节点判断库存/ROI → 人工确认 → 执行节点发布活动 → 日志 → 历史更新 → 报表分析 |

---

## 8. 规则引擎（初期备用方案）

### 8.1 设计定位

- **目的**：在 AI 决策模型尚未充分训练或 token 不可用的情况下，保证业务能继续自动化运行
- **特点**：
  - 逻辑简单、可配置
  - 不依赖 token 调用
  - 作为 AI 决策节点的备用或初期执行层

### 8.2 规则引擎与 AI 决策的关系

```
[业务触发] → [规则引擎检查] → [规则命中?] 
                                    ├── 是 → [按规则执行] → [日志记录]
                                    └── 否 → [AI决策节点] → [条件判断] → [执行]
```

### 8.3 规则类型

| 规则类型 | 说明 | 示例 |
|----------|------|------|
| **阈值规则** | 基于数值阈值的判断 | 库存 < 安全库存 → 触发补货 |
| **时间规则** | 基于时间周期的判断 | 每日 00:00 检查广告预算 |
| **组合规则** | 多条件组合判断 | ROI > 1.5 且 库存充足 → 自动增加广告预算 |
| **异常规则** | 异常检测与处理 | CTR 下降 > 30% → 触发人工确认 |

### 8.4 规则配置示例

```typescript
interface Rule {
  id: string;
  name: string;
  condition: {
    type: 'threshold' | 'time' | 'composite' | 'anomaly';
    expression: string;
  };
  action: {
    type: 'auto_execute' | 'human_approval' | 'notification';
    payload: object;
  };
  priority: number;
  enabled: boolean;
}

// 示例规则
const rules: Rule[] = [
  {
    id: 'RULE-001',
    name: '库存不足自动补货',
    condition: {
      type: 'threshold',
      expression: 'inventory < safety_stock'
    },
    action: {
      type: 'human_approval',
      payload: { action: 'restock', quantity: 'suggested_amount' }
    },
    priority: 1,
    enabled: true
  },
  {
    id: 'RULE-002',
    name: '高ROI广告自动加预算',
    condition: {
      type: 'composite',
      expression: 'roi > 1.5 AND inventory > min_stock'
    },
    action: {
      type: 'auto_execute',
      payload: { action: 'increase_budget', amount: 100 }
    },
    priority: 2,
    enabled: true
  }
];
```

### 8.5 演进路径

| 阶段 | 规则引擎 | AI决策节点 |
|------|----------|------------|
| **初期** | 主导，处理大部分标准场景 | 辅助，处理复杂场景 |
| **中期** | 处理简单、确定性场景 | 主导，处理需要预测和优化的场景 |
| **后期** | 作为异常处理和兜底机制 | 全链路自动决策 |

---

## 9. 自动化程度演进

| 阶段 | 特征 | 人工干预 |
|------|------|----------|
| **初期** | AI建议 + 人审核，人工操作占主导 | 高干预，大部分决策需要人工确认 |
| **中期** | 对置信度高、低风险的操作可自动执行 | 中等，人工处理异常和低置信度决策 |
| **后期** | AI全链路决策 + 自动执行 | 低干预，仅异常或低置信度操作人工介入 |

### 阈值管理

- 置信度阈值、风险等级、操作类型均可配置
- 支持按业务模块（TOC/TOB）设置不同阈值
- 支持自适应阈值：系统根据历史执行效果自动调整

---

## 10. 与 Task_Overview.md 的关系

### 10.1 职责划分

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

### 10.2 避免重复

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

---

## 11. 相关文档

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

---

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