Agent/examples/content_finder/ARCHITECTURE.md

内容寻找 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）

功能：

• 记录每次搜索的参数和结果
• 查询相似搜索记录
• 分析搜索模式

数据结构：

{
  "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）

功能：

• 记录内容在平台的表现数据
• 分析表现趋势
• 识别高表现内容

数据结构：

{
  "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）

功能：

• 记录运营人员反馈
• 分析运营偏好
• 提取学习洞察

数据结构：

{
  "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. 新增平台

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

2. 新增评估维度

def _calculate_custom_score(item: Dict[str, Any]) -> float:
    # 添加自定义评估逻辑
    pass

3. 新增记忆类型

class CustomMemoryManager:
    """自定义记忆管理器"""
    def __init__(self, storage_path: str):
        # 初始化存储
        pass

性能优化

1. 并行搜索

• 多个平台同时搜索
• 减少总体响应时间

2. 缓存机制

• 缓存相似搜索结果
• 减少重复爬取

3. 增量更新

• 只更新变化的数据
• 减少存储开销

安全考虑

1. 数据隐私

• 敏感信息脱敏
• 访问权限控制

2. 爬虫合规

• 遵守平台规则
• 控制请求频率

3. 内容审核

• 过滤违规内容
• 质量把关机制