PRD.md 14 KB
find_agent 产品需求文档（PRD）
文档版本：v1.2
基线日期：2026-07-28
Agent 定位：老年受众高潜抖音视频发现 Agent
1. 文档目的与边界
本文只描述 find_agent 本身：
- 当前职责、输入、输出和能力；
- 当前使用的工具、判断规则和运行约束；
- 当前存在的问题及需要优化的点。
本文不描述 SupplyAgent 的整体业务流程，不涉及需求分级、日批调度、跨 Agent 协作、 下游生产发布、业务里程碑或平台级建设。
当前实现依据：
- Agent 组装：agent.py
- 核心提示词：prompt/system_prompt.md
- 工具注册：tools/init.py
- 对外调用：init.py
2. Agent 定位
find_agent 根据一条明确的内容需求，从抖音候选中寻找同时满足以下条件的视频：
- 与需求真实意图相关；
- 有证据支持其受众偏向较高年龄段；
- 具备可解释的分享价值。
Agent 对搜索词生成、候选补证、评分解释和最终分池负责。它不生产或改写视频，也不负责 需求优先级、任务调度、内容发布及其他 Agent 的行为。
当前版本明确不使用视频画面、语音、字幕或多模态理解。相关性与分享动机仅依据标题、 描述、话题、详情文本、互动数据和受众画像判断。
3. 输入与输出
3.1 输入
| 字段 | 必需性 | 含义 |
|---|---|---|
demand_word |
必需 | 本次找片的需求词和意图边界 |
seed_video_title |
可选 | 已知相关视频标题，用于消除需求歧义 |
relevant_points |
可选 | 参考视频中与需求相关的灵感、目的或关键点 |
reference_videos |
可选 | 多个参考视频及各自相关点 |
run_id |
可选 | 已创建的发现运行标识；存在时必须复用 |
输入信息不足时，Agent 可以继续搜索，但必须降低意图判断的置信度，不能用模型常识补全 未提供的业务要求。
3.2 输出
Agent 最终输出以下内容：
- 一句话需求意图理解；
primary主推荐；rejected淘汰候选及淘汰原因；- Agent 实际执行的搜索记录；
- 缺失数据、画像冲突、未继续搜索项和接口错误。
每条主推荐至少包含：
- 标题、作者、抖音页面链接和
aweme_id； - 命中的需求点及相关性证据；
- 原始分享数及可计算的分享效率；
- 视频点赞用户年龄画像；
- 作者粉丝年龄画像；
- 分享动机；
R / E / S / V整数分、置信度和主要限制。
最终分池只允许 primary / rejected。pending_evaluation 仅是处理中的临时状态，不得
出现在最终结果中。
4. 当前能力
4.1 需求理解与搜索规划
- 综合需求词、参考标题和相关点解释真实意图；
- 默认生成 2～3 个语义不同的根搜索词；
- 搜索词不要求逐字复用
demand_word； - 可根据高潜候选的话题、标题实体、作者和分页状态继续扩展；
- 以新增有效候选和潜在信息价值决定是否继续搜索。
4.2 候选召回
- 支持内部抖音关键词搜索；
- 支持 TikHub 独立搜索和分页；
- 支持按作者扩展最热或最新作品；
- 不同搜索词、页面和来源的候选按
aweme_id去重； - TikHub 不可用时可退回内部搜索，并保留错误原因；
- 每次搜索结果均可保存查询词、形成原因、分页状态和父搜索信息。
4.3 候选证据补全
- 批量获取视频详情，核验标题、作者、话题、链接和互动数据；
- 获取视频点赞用户画像；
- 获取作者粉丝年龄画像；
- 标准化不同年龄桶表达；
- 记录画像缺失、接口失败及视频画像与作者画像冲突；
- 先使用搜索结果进行低成本预筛，再为高潜候选补充详情和画像。
当前没有以下证据：
- 视频真实转发用户年龄画像；
- 分年龄曝光、播放、完播和观看时长；
- 视频画面、语音或字幕理解结果；
- 同题材、相近发布时间下的标准化传播基线。
4.4 评分与分池
Agent 对每个候选独立判断：
R：需求相关性；E：老年受众倾向；S：分享价值。
综合价值为：
V = 100 × R^0.40 × E^0.35 × S^0.25
V 用于保持排序一致，不替代证据判断。只有 R / E / S 三项均成立的候选才能进入
primary；任一项不成立时进入 rejected。
当前分池由模型根据提示词和证据作出，保存工具只保存结果，不重新计算分数或改变分池。
4.5 状态保存与完成控制
- 创建或复用
run_id； - 保存每个搜索页和去重后的候选；
- 批量保存候选证据、评分、理由和分池；
- 查询已保存的搜索与候选状态；
- 通过数据库审计检查搜索、证据、评估和最终状态；
- completion guard 强制最后阶段满足：
搜索页已保存 → 证据已获取 → 评估已保存 → 审计通过 → 查询最终状态 → 输出报告
最终报告只读取数据库最终状态，不通过文字反向修改候选分池。报告中的主推荐和淘汰 候选必须与数据库状态一致。
当 Agent 结合任务上下文、替代方案和工具反馈判断任务已经无法继续时，应停止无效重试，
输出以 任务未完成（工具故障） 开头的失败摘要。完成守卫只识别该声明，不解析工具
返回结构或错误文案，也不替 Agent 判断错误是否可恢复。
5. 当前判断规则
5.1 需求相关性是准入条件
- 搜索词命中不等于内容相关；
- 高分享或受众偏老不能弥补低相关；
- 参考标题和相关点用于理解意图，不要求候选逐字匹配。
5.2 年龄证据按强度使用
证据优先级为：
- 视频点赞用户年龄画像；
- 作者粉丝年龄画像；
- 标题、描述、话题和详情文本体现的内容适配特征；
- 题材、人物或作者形象带来的直觉。
第 4 类不能单独支持老年倾向。视频画像与作者画像冲突时，以视频画像为主并降低置信度。 明确覆盖 50 岁及以上的年龄桶才属于直接老年信号；只有 40 岁以上数据时，只能表述为 成熟人群代理信号。
5.3 分享证据与年龄证据不能互相替代
share_count说明传播规模，不说明分享者年龄；- 点赞用户或作者粉丝年龄画像说明受众倾向，不说明已经发生转发；
- 当前只能推断“老年人可能愿意分享”，不能声称已观察到老年分享者；
- 分享价值同时参考分享规模、分享效率和内容动机。
5.4 缺失不是负证据
- 数据缺失或接口失败应标记为未知；
- 未知会降低置信度，但不自动计为零分；
- 强反证优先于多个弱正向线索；
- 不得为了达到推荐数量而降低准入标准。
5.5 推荐集合需要新增价值
- 高度重复的视频只保留证据更强的一条；
- 价值接近时优先覆盖不同需求点和分享动机；
- 合理搜索后允许少于 5 条或返回空结果。
6. 当前工具
| 工具 | 当前用途 | 关键限制 |
|---|---|---|
douyin_search |
内部关键词召回 | 搜索结果不是最终事实 |
douyin_search_tikhub |
TikHub 搜索与分页 | 翻页必须复用供应方分页参数 |
douyin_user_videos |
扩展作者作品 | 作品仍需逐条补证和判断 |
douyin_detail |
批量核验视频详情 | 单次最多 8 条 |
get_content_fans_portrait |
获取单条视频点赞用户画像 | 不是分享用户画像 |
get_account_fans_portrait |
获取作者粉丝画像 | 只代表账号受众先验 |
batch_fetch_portraits |
批量获取视频和作者画像 | 单次最多 8 条 |
normalize_age_portraits |
标准化年龄桶 | 不负责业务评分 |
create_video_discovery_run |
创建或复用运行状态 | 传入 run_id 时必须复用 |
record_video_search_page |
保存搜索页并合并候选 | 每次搜索后均需调用 |
batch_save_video_candidate_evaluations |
保存证据、评分和分池 | 只接受 primary / rejected |
audit_video_discovery_run |
审计 Agent 最终状态 | can_finish=true 才能完成 |
query_video_discovery_state |
恢复或读取最终状态 | 最终查询必须晚于成功审计 |
qwen_video_analyze 未注册，不属于当前 Agent 能力。
7. 当前运行约束
| 项目 | 当前设置 |
|---|---|
| 模型 | 固定为 google/gemini-3-flash-preview |
| 最大迭代轮次 | 60 |
| 温度 | 0.2 |
| 搜索工具预算 | 10 次 |
| 详情工具预算 | 2 次 |
| 画像工具预算 | 3 次 |
| 候选保存预算 | 6 次 |
| 审计预算 | 4 次 |
| 状态查询预算 | 8 次 |
| 单批详情/画像候选数 | 最多 8 条 |
create_find_agent(..., model=...) 和 run_find_agent(..., model=...) 虽然暴露了模型参数，
当前工厂仍固定使用上述模型，传入参数不会生效。
8. 当前实现评价
| 能力 | 状态 | 当前判断 |
|---|---|---|
| 需求理解 | 可用 | 能结合需求词、参考标题和相关点形成搜索假设 |
| 多源搜索 | 可用 | 内部搜索、TikHub 和作者作品均已注册 |
| 候选去重 | 可用 | 支持跨词、跨页和跨来源按 aweme_id 合并 |
| 详情与画像 | 可用但有缺口 | 支持详情、双侧画像和年龄标准化，画像可能缺失 |
| 内容理解 | 受限 | 仅使用文本、互动和画像，不使用视频理解 |
| 评分与分池 | 部分可用 | 规则完整，但主要依赖模型遵守长提示词 |
| 状态保存 | 可用 | 可保存运行、搜索页和候选状态 |
| 完成审计 | 已接入 | 可校验完成顺序、审计新鲜度和报告分池 |
| 故障终止 | 已接入 | Agent 明确声明工具故障时允许失败结束 |
| 最终一致性 | 部分可用 | 报告只读并接受校验，尚无单一事务性最终化入口 |
| 运行恢复 | 部分可用 | 能查询旧状态，但缺少执行代次和自动恢复机制 |
| 可观测性 | 不完整 | 有日志和基础计数，缺少 Agent 级质量与成本指标 |
9. 需要优化的点
9.1 P0：提高 Agent 的确定性与一致性
增加事务性最终化
- 新增单一
finalize_video_discovery_run能力； - 仅允许最终化当前运行已召回且已评估的候选；
- 在一个事务内校验并写入候选分池、计数、完成状态和最终摘要；
- 最终化失败必须显式返回错误并支持安全重试。
- 新增单一
将关键约束从长提示词下沉到程序
- 用结构化节点控制搜索、补证、评估、审计和最终输出；
- 对必需证据、合法状态和工具调用顺序做程序校验；
- 保留 LLM 对意图、搜索词、语义相关性和解释的判断空间。
结构化模型输出
- 为搜索计划、候选评估和最终结果定义 JSON Schema；
- 校验
R / E / S取值、必填证据、置信度和分池； - 由程序计算
V，避免模型计算漂移； - 禁止模型输出未召回的候选 ID。
修复模型配置
- 让显式传入的
model参数真正生效； - 保存实际使用的模型、Prompt 和评分策略版本；
- 避免固定依赖预览模型。
- 让显式传入的
补齐 Agent 契约测试
- 覆盖未保存搜索页、证据晚于评估、审计失败、旧状态查询和报告分池不一致；
- 覆盖幻觉候选 ID、非法分池、缺失证据和工具预算耗尽；
- 用固定样例验证相关性闸门、年龄证据层级和未知数据处理。
9.2 P1：提高搜索与判断质量
优化搜索前沿选择
- 结构化记录每个搜索假设的预期价值、实际新增候选和耗时；
- 根据边际新增率决定翻页、标签扩展和作者扩展；
- 减少同义词重复搜索及低价值工具调用。
优化候选预筛与补证
- 将低成本预筛规则结构化；
- 优先为可能改变分池的候选补充详情和画像；
- 对重复详情和画像增加短期缓存；
- 记录每项缺失证据对置信度的具体影响。
建立评分评测集
- 建立覆盖不同题材的人工标注样例；
- 分别评估
R / E / S，避免只看最终分池； - 统计
primary / rejected混淆情况； - 按模型、Prompt 和策略版本回放对比。
增强 Agent 可观测性
- 记录搜索新增率、候选漏斗、证据缺失率、工具失败率和单次调用成本；
- 区分模型判断失败、外部接口失败、持久化失败和完成校验失败；
- 输出本次使用的模型、Prompt、策略和数据源版本。
改进运行恢复
- 为同一
run_id增加执行代次； - 恢复时明确区分已完成步骤、可复用证据和需要重试的失败项；
- 避免新一轮执行混用已过期的搜索或候选判断。
- 为同一
9.3 P2：升级 Agent 可用证据
- 接入真实转发用户年龄分布和样本量；
- 接入分年龄曝光、有效播放、完播率和观看时长；
- 建立同题材、同发布时间窗口的传播基线；
- 增加评论中的提醒、家庭沟通、收藏和求链接等结构化意图信号；
- 在获得明确授权和完整验证前，继续保持“不使用视频理解”的能力边界；
- 将新证据的计算规则、置信度上限和冲突处理策略版本化。
10. Agent 验收标准
一次 find_agent 运行满足以下条件，才视为 Agent 自身完成：
- 已创建或复用唯一
run_id； - 实际调用的搜索页均已保存；
- 候选已按
aweme_id去重； - 主推荐已尝试获取详情和双侧年龄画像；
- 年龄画像已标准化，缺失和冲突已披露；
- 每个已评估候选具有合法分池及对应理由；
- 最终不存在
pending_evaluation或其他非法分池； - 数据库审计返回
can_finish=true； - 审计后已重新查询最终状态；
- 最终报告与数据库
primary / rejected完全一致； - 不使用未注册的视频理解能力或编造缺失证据；
- 推荐不足 5 条时不降低质量标准。
若工具故障导致任务无法继续，则不适用上述成功条件，但必须满足：
- Agent 已根据上下文判断继续调用无法产生有效进展；
- Agent 已停止重复调用失败工具；
- 最终摘要明确标记
任务未完成（工具故障）； - 摘要包含失败工具、原始错误、已完成内容和未完成内容；
- 不输出看似有效的推荐结果。