Agent/examples/content_finder

内容寻找 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. 安装依赖

pip install -r requirements.txt

2. 配置环境变量

cp examples/content_finder/.env.example examples/content_finder/.env

编辑 .env，至少填写：

OPEN_ROUTER_API_KEY=your_api_key_here

3. 运行

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

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

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

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 — 创建任务

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

响应：

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

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

GET /health — 健康检查

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，避免超出上下文