# 内容寻找 AI Agent 架构设计

## 系统架构

```
┌─────────────────────────────────────────────────────────────┐
│                     ContentFinderAgent                       │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐      │
│  │ AgentRunner  │  │ TraceStore   │  │ MemoryStore  │      │
│  └──────────────┘  └──────────────┘  └──────────────┘      │
└─────────────────────────────────────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
        ▼                     ▼                     ▼
┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   工具层      │      │   记忆层      │      │   技能层      │
├──────────────┤      ├──────────────┤      ├──────────────┤
│ 爬虫工具      │      │ 搜索历史      │      │ content-finder│
│ - douyin     │      │ 内容表现      │      │   skill       │
│ - kuaishou   │      │ 运营偏好      │      └──────────────┘
│              │      └──────────────┘
│ 评估工具      │
│ - evaluate   │
│              │
│ 反馈工具      │
│ - feedback   │
│ - performance│
│ - query      │
└──────────────┘
```

## 核心组件

### 1. ContentFinderAgent（主Agent）

**职责**：
- 协调整个内容搜索流程
- 管理搜索请求和结果
- 收集和处理反馈
- 优化搜索策略

**关键方法**：
- `search_content()`: 执行内容搜索
- `collect_feedback()`: 收集运营反馈
- `update_performance()`: 更新内容表现
- `optimize_strategy()`: 优化搜索策略

### 2. 工具层（Tools）

#### 2.1 爬虫工具（crawler.py）
- `douyin_search`: 抖音内容搜索
- `kuaishou_search`: 快手内容搜索

**特点**：
- 支持关键词、筛选条件
- 返回标准化的内容数据
- 可扩展到其他平台

#### 2.2 评估工具（content_eval.py）
- `evaluate_content`: 内容质量和相关性评估

**评估维度**：
- 质量分数：播放量、互动率、新鲜度
- 相关性分数：关键词匹配度

#### 2.3 反馈工具（feedback.py）
- `record_operator_feedback`: 记录运营反馈
- `update_content_performance`: 更新表现数据
- `query_historical_data`: 查询历史数据

### 3. 记忆层（Memory）

#### 3.1 搜索历史（search_history.py）
**功能**：
- 记录每次搜索的参数和结果
- 查询相似搜索记录
- 分析搜索模式

**数据结构**：
```json
{
  "timestamp": "2026-03-06T10:00:00",
  "keywords": ["美食", "探店"],
  "platforms": ["douyin", "kuaishou"],
  "filters": {"min_views": 10000},
  "results_count": 20,
  "trace_id": "trace_123"
}
```

#### 3.2 内容表现（content_perf.py）
**功能**：
- 记录内容在平台的表现数据
- 分析表现趋势
- 识别高表现内容

**数据结构**：
```json
{
  "content_id": "dy_123456",
  "timestamp": "2026-03-06T10:00:00",
  "platform_views": 150000,
  "platform_likes": 8000,
  "internal_views": 5000,
  "internal_engagement": 0.15,
  "conversion_rate": 0.08
}
```

#### 3.3 运营偏好（operator_pref.py）
**功能**：
- 记录运营人员反馈
- 分析运营偏好
- 提取学习洞察

**数据结构**：
```json
{
  "content_id": "dy_123456",
  "timestamp": "2026-03-06T10:00:00",
  "rating": "excellent",
  "notes": "内容质量很高",
  "operator_id": "operator_001",
  "content_features": {
    "keywords": ["美食"],
    "tags": ["探店"],
    "platform": "douyin"
  }
}
```

### 4. 技能层（Skills）

**content-finder skill**：
- 定义Agent的工作流程
- 提供最佳实践指南
- 规范工具使用方式

## 数据流程

### 搜索流程

```
用户需求
   ↓
1. 构建搜索请求（SearchRequest）
   ↓
2. 查询相似历史搜索
   ↓
3. 基于历史数据优化参数
   ↓
4. 并行调用爬虫工具
   │
   ├─→ douyin_search
   └─→ kuaishou_search
   ↓
5. 合并搜索结果
   ↓
6. 评估内容质量（evaluate_content）
   ↓
7. 排序并返回结果
   ↓
8. 保存搜索历史
```

### 反馈流程

```
运营人员反馈
   ↓
1. 记录反馈（record_operator_feedback）
   ↓
2. 保存到运营偏好数据
   ↓
3. 提取内容特征
   ↓
4. 更新偏好模型
```

### 优化流程

```
触发优化
   ↓
1. 获取历史数据
   │
   ├─→ 搜索历史
   ├─→ 运营反馈
   └─→ 内容表现
   ↓
2. 分析高表现内容特征
   │
   ├─→ 关键词分析
   ├─→ 标签分析
   ├─→ 平台权重分析
   └─→ 筛选条件分析
   ↓
3. 生成优化策略
   ↓
4. 应用到下次搜索
```

## 学习机制

### 1. 关键词优化
- 统计高表现内容的关键词
- 提取运营偏好的关键词
- 自动扩展相关关键词

### 2. 筛选条件优化
- 分析高表现内容的数值特征
- 动态调整播放量、点赞数阈值
- 优化时间范围设置

### 3. 平台权重优化
- 统计各平台的内容表现
- 计算平台权重系数
- 优先搜索高权重平台

### 4. 质量评估优化
- 学习运营反馈的评分标准
- 调整质量评估算法权重
- 提高内容匹配准确度

## 扩展性设计

### 1. 新增平台
```python
@tool(description="从新平台搜索视频内容")
async def new_platform_search(
    keywords: str,
    max_results: int = 20,
    ctx: ToolContext = None,
) -> ToolResult:
    # 实现新平台的搜索逻辑
    pass
```

### 2. 新增评估维度
```python
def _calculate_custom_score(item: Dict[str, Any]) -> float:
    # 添加自定义评估逻辑
    pass
```

### 3. 新增记忆类型
```python
class CustomMemoryManager:
    """自定义记忆管理器"""
    def __init__(self, storage_path: str):
        # 初始化存储
        pass
```

## 性能优化

### 1. 并行搜索
- 多个平台同时搜索
- 减少总体响应时间

### 2. 缓存机制
- 缓存相似搜索结果
- 减少重复爬取

### 3. 增量更新
- 只更新变化的数据
- 减少存储开销

## 安全考虑

### 1. 数据隐私
- 敏感信息脱敏
- 访问权限控制

### 2. 爬虫合规
- 遵守平台规则
- 控制请求频率

### 3. 内容审核
- 过滤违规内容
- 质量把关机制