# find_agent：老年受众高潜视频发现

## 输入与结果

输入由 `demand_word`、`seed_video_title`、`relevant_points` 组成。需求词只负责表达原始
需求，不限定实际搜索词；Agent 根据参考视频和点位判断真实内容意图，自主生成并扩展
多个搜索词。

搜索来源包括：

- `douyin_search`：现有内部关键词搜索；
- `douyin_search_tikhub`：TikHub 关键词搜索，保留完整分页状态和视频标签；
- `douyin_user_videos`：按最热/最新扩展候选作者的历史作品。

三个工具统一返回 `search_results`，每项包含 `aweme_id、desc、url、author、
statistics`；新增工具还返回 `duration_ms、topics、collect_count、play_count`。
TikHub 翻页必须同时沿用 `next_cursor、search_id、backtrace`。
使用 TikHub 前需在项目 `.env` 配置 `TIKHUB_API_KEY`；未配置时 Agent 会记录失败并
回退到内部关键词搜索。

另外注册了一个无外部依赖的决策辅助工具：

- `normalize_age_portraits`：识别真实接口中的 `50-` 等年龄桶，统一视频和作者证据；

当前流程明确不使用视频理解，不调用视频画面、语音、字幕或多模态解析工具。内容相关性
与分享动机仅依据标题、描述、话题、详情文本、互动数据和画像判断。数据库不保存视频
播放地址、内容分析结论或视频理解核验标记。

最终结果只分为两个等级：

- `primary`：与需求相关，且老年倾向、分享价值达到主推荐边界；
- `rejected`：未满足 `primary` 的候选。

`pending_evaluation` 只是搜索召回后的过程状态，不是最终等级。不存在 `backup`、
补充推荐或人工备选。最终优先产出至少 5 条 `primary`，可以更多；5 条不是硬门槛，
合理搜索后不足时可以少于 5 条结束，不会为了凑数降低准入标准。

## 已实现的搜索记忆

执行 `.venv/bin/python -m supply_infra.db` 后会创建三张表：

已有表升级时执行 `sql/video_discovery_drop_unused_columns.sql`，删除不再使用的
`backup_count、video_url、content_analysis、content_analysis_verified`。

| 表 | 粒度 | 用途 |
|---|---|---|
| `video_discovery_run` | 一次找片任务 | 保存输入、意图解释、状态、搜索数和分池数量 |
| `video_discovery_search` | 一个关键词或作者的一页结果 | 保存 Agent 实际搜索词、形成原因、标签/作者/翻页来源、供应方分页状态和新增候选数 |
| `video_discovery_candidate` | 一次任务中的一条视频 | 保存详情、来源关键词、标签、互动量、双侧年龄证据、R/E/S/V 和 Agent 分池 |

已注册五个持久化与审计工具：

- `create_video_discovery_run`：创建运行并取得 `run_id`；
- `record_video_search_page`：保存每次搜索和翻页，幂等合并 `aweme_id`；
- `batch_save_video_candidate_evaluations`：原样保存 Agent 给出的证据、评分和分池；
- `audit_video_discovery_run`：从数据库读取完整运行状态并执行确定性完成审计；
- `query_video_discovery_state`：恢复搜索树、主推荐和淘汰候选；

候选分池完全由 Agent 决定：

- `pending_evaluation`：搜索已经召回，但 Agent 尚未完成详情、画像和评分；
- `primary`：Agent 决定的主推荐；
- `rejected`：Agent 决定淘汰的候选。

状态流固定为：

`搜索召回 → pending_evaluation → Agent补证和评分 → primary / rejected`。

`pending_evaluation` 不能作为最终结果。

保存工具不会重算 `R/E/S/V`、限制年龄分，也不会修改 Agent 给出的
`decision_bucket`；它只校验最终等级必须是 `primary / rejected`。

运行时 completion guard 强制结束前最后阶段为：

`最后搜索并保存 → 证据获取与整理 → 候选评估保存 → 审计 → 最终状态查询 → 报告`

审计后如果又发生搜索、取证或评估，必须重新审计并重新查询状态。最终报告只读取数据库
中的 `primary / rejected`，报告之后不再反向修改分池。

当 Agent 根据任务上下文和已尝试方案判断工具故障已导致任务无法继续时，可以停止重复
调用，输出以 `任务未完成（工具故障）` 开头的失败摘要。完成守卫只识别该失败声明，
不解析工具返回结构、错误字段或错误文案，也不替 Agent 判断错误是否可恢复。

## 建议补充的外部数据工具

以下工具依赖抖音爬虫或热点宝增加接口，当前仓库无法自行补出真实数据。建议按优先级
评估能否实现。

### P0：直接提升结论可靠性

1. `get_video_share_user_portrait(content_id)`

   返回实际转发用户的年龄桶、占比、TGI、样本量和统计周期。当前只有点赞用户画像，
   这是“老年人是否真的分享”最大的证据缺口。

2. `batch_douyin_search(requests)`

   一次接收多个 `{keyword, cursor, sort_type, publish_time}`，逐项返回结果和下一游标，
   服务端负责限流。当前单接口约 10 秒间隔，多词、多页探索会很慢。

3. `get_video_audience_retention(content_id)`

   返回各年龄段的曝光、有效播放、完播率、平均观看时长。它能区分“老年人点赞过”
   和“老年人真正看完并喜欢”。

### P1：提升扩词与搜索覆盖

4. `get_similar_videos(content_id, cursor)`

   返回平台相关推荐及相似原因，用优质候选直接扩展同类视频，比纯关键词更容易找到
   标题表达不同的内容。

5. `get_video_topics(content_ids)`

   批量返回标准化话题标签、挑战标签、实体和标签热度。详情接口已有 `topic_list`，
   但如果它不稳定或没有热度，这个独立接口能支持可靠的标签前沿扩展。

6. 作者作品列表已由 `douyin_user_videos` 实现；如果内部接口后续能返回更完整的
   `topic_list、play_count、publish_timestamp`，可直接增强当前工具。

### P2：改善分享分的跨主题可比性

7. `get_topic_engagement_baseline(topic, publish_window)`

   返回同主题、相近发布时间视频的播放/点赞/分享分位数，使原始分享数能按题材和曝光
   归一化。

8. `get_video_comment_signals(content_id)`

   返回脱敏后的高频评论意图、@家人朋友、收藏提醒、求链接等分享动机统计。不要返回
   用户身份信息；该工具只作为内容动机证据，不能代替年龄画像。

每个画像或基线接口都应返回 `sample_size`、`stat_period`、`data_source` 和缺失原因。
没有样本量与统计周期的百分比，不适合用于高置信判断。