# 内容寻找 Agent

基于 AI Agent 的抖音内容寻找工具，根据用户需求智能搜索和筛选符合目标受众的视频内容。支持命令行和 HTTP 服务两种运行方式。

## 平台背景

- **载体**：微信小程序
- **核心用户群**：95% 是 50 岁以上中老年人
- **增长方式**：微信分享裂变
- **核心指标**：分享率、DAU

## 核心功能

1. **智能搜索**：解析用户需求，提取关键词，调用抖音搜索 API
2. **画像筛选**：基于热点宝画像数据，分析内容受众年龄分布和偏好度（TGI）
3. **深度挖掘**：对优质账号（目标人群占比 > 60% 且 TGI > 120）获取更多作品
4. **分层推荐**：按强烈推荐 / 推荐 / 可选三档输出，附完整链接和数据来源

## 项目结构

```
content_finder/
├── run.py                         # 命令行入口（流式输出）
├── server.py                      # HTTP 服务入口（FastAPI + APScheduler）
├── core.py                        # 共享 Agent 执行逻辑
├── content_finder.prompt          # System Prompt + User Prompt 模板
├── .env.example                   # 环境变量模板
├── SERVICE.md                     # 服务模式详细说明
├── tools/                         # 自定义工具
│   ├── __init__.py
│   ├── douyin_search.py           # 抖音关键词搜索
│   ├── douyin_user_videos.py      # 账号作品列表
│   └── hotspot_profile.py         # 热点宝画像数据
├── skills/                        # Agent 方法论（注入 System Prompt）
│   ├── content_finding_strategy.md    # 内容寻找 5 步流程
│   └── content_filtering_strategy.md  # 内容筛选分阶段策略
└── .cache/                        # 运行时目录（gitignore）
    ├── traces/                    # Trace 存储
    ├── agent.log                  # 命令行模式日志
    └── server.log                 # 服务模式日志
```

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置环境变量

```bash
cp examples/content_finder/.env.example examples/content_finder/.env
```

编辑 `.env`，至少填写：

```bash
OPEN_ROUTER_API_KEY=your_api_key_here
```

### 3. 运行

**命令行模式**（交互式，流式输出）：

```bash
# 在项目根目录执行，trace 存储在根目录 .trace/
python examples/content_finder/run.py
```

**服务模式**（HTTP API + 定时调度）：

```bash
python examples/content_finder/server.py
```

## 环境变量说明

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `OPEN_ROUTER_API_KEY` | 必填 | OpenRouter API Key |
| `MODEL` | `anthropic/claude-sonnet-4.6` | 使用的模型 |
| `TEMPERATURE` | `0.3` | 模型温度 |
| `MAX_ITERATIONS` | `30` | Agent 最大迭代轮数 |
| `TRACE_DIR` | `.cache/traces` | Trace 存储目录 |
| `PORT` | `8080` | 服务端口（服务模式） |
| `MAX_CONCURRENT_TASKS` | `3` | 最大并发任务数（服务模式） |
| `SCHEDULE_QUERY_API` | 空 | 定时任务外部 API 地址（留空则不启动定时任务） |
| `SCHEDULE_QUERY_API_KEY` | 空 | 定时任务外部 API 认证 Key |
| `SCHEDULE_QUERY_API_TIMEOUT` | `10.0` | 定时任务外部 API 超时（秒） |

## 服务模式 API

服务启动后监听 `PORT`（默认 8080）。

### POST /api/tasks — 创建任务

```bash
curl -X POST http://localhost:8080/api/tasks \
  -H "Content-Type: application/json" \
  -d '{"query": "找15个和广场舞相关的视频，热度要高"}'
```

响应：

```json
{
  "trace_id": "20260317_103046_xyz789",
  "status": "started",
  "query": "找15个和广场舞相关的视频，热度要高",
  "message": "任务已启动，结果将保存到 .cache/traces/20260317_103046_xyz789/"
}
```

`query` 不传则使用默认需求（养老服务与政策扶持相关内容）。

### GET /health — 健康检查

```bash
curl http://localhost:8080/health
```

响应包含当前并发数、定时任务状态和累计统计。

### 定时任务

配置 `SCHEDULE_QUERY_API` 后，服务每 10 分钟自动调用该接口获取 query 并执行任务。外部接口规范：

```
GET {SCHEDULE_QUERY_API}
Authorization: Bearer {SCHEDULE_QUERY_API_KEY}

# 有任务时返回：
{"query": "找10个和健康养生相关的视频"}

# 无任务时返回：
{"query": null}
```

## 工具说明

Agent 只允许调用以下 4 个工具，其他工具（包括浏览器工具）均被禁止：

### douyin_search

通过关键词搜索抖音视频。

| 参数 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `keyword` | ✅ | — | 搜索关键词 |
| `content_type` | | `视频` | 内容类型 |
| `sort_type` | | `综合排序` | 排序方式 |
| `publish_time` | | `不限` | 发布时间范围 |
| `cursor` | | `0` | 分页游标 |
| `timeout` | | `60` | 超时秒数 |

结果通过 `metadata.search_results` 获取结构化数据。

### douyin_user_videos

获取账号历史作品列表。

| 参数 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `account_id` | ✅ | — | 账号 sec_uid（约 80 字符） |
| `sort_type` | | `最新` | 排序方式 |
| `cursor` | | `""` | 分页游标 |
| `timeout` | | `60` | 超时秒数 |

结果通过 `metadata.user_videos` 获取，格式与 `search_results` 一致。

### get_content_fans_portrait

获取视频点赞用户画像（热点宝）。

| 参数 | 必填 | 默认值 | 说明 |
|------|------|--------|------|
| `content_id` | ✅ | — | 视频 aweme_id |
| `need_age` | | `True` | 是否获取年龄分布 |
| `need_gender` | | `False` | 是否获取性别分布 |
| `need_province` | | `False` | 省份分布 |
| `timeout` | | `60` | 超时秒数 |

通过 `metadata.has_portrait` 判断是否有有效画像，数据从 `metadata.portrait_data` 获取。

### get_account_fans_portrait

获取账号粉丝画像（热点宝），作为内容画像缺失时的兜底。

参数与 `get_content_fans_portrait` 相同，`content_id` 替换为 `account_id`（传入 sec_uid）。

## Skills 策略

### content_finding_strategy — 内容寻找 5 步流程

1. **需求分析**：提取关键词，确定目标数量 M
2. **串行搜索**：每次搜索 N = M × 2 条，够了立即停止
3. **分阶段筛选**：基础质量（热度 + 相关性）→ 画像匹配 → 优质账号扩展
4. **结果评估**：符合数量 C ≥ M 则完成，否则换关键词补充
5. **去重排序**：按 aweme_id 去重，按画像匹配度 × 热度综合排序

### content_filtering_strategy — 内容筛选分阶段策略

- **阶段一**：热度筛选（1000+ 一般 / 5000+ 较高 / 10000+ 高 / 50000+ 爆款）
- **阶段二**：画像匹配（优先内容点赞画像，缺失时用账号粉丝画像兜底）
- **阶段三**：优质账号扩展（占比 > 60% 且 TGI > 120，获取 5-10 条作品）
- **阶段四**：去重排序（画像匹配度优先，其次热度，其次数据来源可靠性）
- **阶段五**：分层输出（强烈推荐 / 推荐 / 可选）

## 输出格式

每条推荐内容包含：

- 内容链接：`https://www.douyin.com/video/{aweme_id}`
- 作者链接：`https://www.douyin.com/user/{author.sec_uid}`（完整 sec_uid，约 80 字符）
- 热度数据：点赞 / 评论 / 分享（来自 `metadata.statistics`）
- 画像数据：50 岁以上占比 + TGI（来自 `metadata.portrait_data`）
- 画像链接：
  - 内容点赞画像：`https://douhot.douyin.com/video/detail?active_tab=video_fans&video_id={aweme_id}`
  - 账号粉丝画像：`https://douhot.douyin.com/creator/detail?active_tab=creator_fans_portrait&creator_id={author.sec_uid}`
- 数据来源标注："内容点赞画像" 或 "账号粉丝画像" 或 "无画像数据"

## 注意事项

- **数据真实性**：所有字段必须来自 `metadata`，禁止从 output 文本解析，禁止编造任何数据
- **sec_uid 完整性**：`author.sec_uid` 约 80 字符，必须完整复制，格式以 `MS4wLjABAAAA` 开头
- **工具限制**：只允许调用上述 4 个工具，浏览器工具已在 Prompt 中明确禁止
- **Token 控制**：搜索上限 N = M × 2，画像获取上限 M × 1.5，避免超出上下文