SupplyAgent/agents/find_agent

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：与需求相关，且老年倾向、分享价值达到主推荐边界；
• backup：未进入主推荐，但老年倾向和分享价值达到保留线，由 Agent 自动保留。

最终结果优先保证至少 5 条，可以更多。优先使用 primary；不足 5 条时，由 Agent 按 V 从 backup 选择质量最好的补充项，并明确标注限制。

5 条是优先目标，不是硬性门槛。合理搜索后确实没有足够的合格视频时，可以少于 5 条 结束，不会为了凑数保留明显低质内容。流程不再等待人工审核。

已实现的搜索记忆

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

表	粒度	用途
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 给出的证据、评分和分池；
• query_video_discovery_state：恢复搜索树、主推荐池和补充候选池；

候选分池完全由 Agent 决定：

• pending_evaluation：搜索已经召回，但 Agent 尚未完成详情、画像、内容核验和评分；
• primary：Agent 决定的主推荐；
• backup：Agent 决定保留的补充推荐；
• rejected：Agent 决定淘汰的候选。

状态流固定为：

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

pending_evaluation 不能直接进入最终主推荐或补充推荐。

保存工具不会重算 R/E/S/V、限制年龄分，也不会修改 Agent 给出的 decision_bucket。最终报告中列为主推荐或补充推荐的视频会同步到对应数据库分池。

建议补充的外部数据工具

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

P0：直接提升结论可靠性

1. get_video_share_user_portrait(content_id)

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

1. batch_douyin_search(requests)

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

1. get_video_audience_retention(content_id)

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

P1：提升扩词与搜索覆盖

1. get_similar_videos(content_id, cursor)

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

1. get_video_topics(content_ids)

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

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

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

1. get_topic_engagement_baseline(topic, publish_window)

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

1. get_video_comment_signals(content_id)

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

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