# find_agent 产品需求文档（PRD）

> 文档版本：v1.2
>
> 基线日期：2026-07-28
>
> Agent 定位：老年受众高潜抖音视频发现 Agent

## 1. 文档目的与边界

本文只描述 `find_agent` 本身：

- 当前职责、输入、输出和能力；
- 当前使用的工具、判断规则和运行约束；
- 当前存在的问题及需要优化的点。

本文不描述 SupplyAgent 的整体业务流程，不涉及需求分级、日批调度、跨 Agent 协作、
下游生产发布、业务里程碑或平台级建设。

当前实现依据：

- Agent 组装：[agent.py](agent.py)
- 核心提示词：[prompt/system_prompt.md](prompt/system_prompt.md)
- 工具注册：[tools/__init__.py](tools/__init__.py)
- 对外调用：[__init__.py](__init__.py)

## 2. Agent 定位

`find_agent` 根据一条明确的内容需求，从抖音候选中寻找同时满足以下条件的视频：

1. 与需求真实意图相关；
2. 有证据支持其受众偏向较高年龄段；
3. 具备可解释的分享价值。

Agent 对搜索词生成、候选补证、评分解释和最终分池负责。它不生产或改写视频，也不负责
需求优先级、任务调度、内容发布及其他 Agent 的行为。

当前版本明确不使用视频画面、语音、字幕或多模态理解。相关性与分享动机仅依据标题、
描述、话题、详情文本、互动数据和受众画像判断。

## 3. 输入与输出

### 3.1 输入

| 字段 | 必需性 | 含义 |
|---|---|---|
| `demand_word` | 必需 | 本次找片的需求词和意图边界 |
| `seed_video_title` | 可选 | 已知相关视频标题，用于消除需求歧义 |
| `relevant_points` | 可选 | 参考视频中与需求相关的灵感、目的或关键点 |
| `reference_videos` | 可选 | 多个参考视频及各自相关点 |
| `run_id` | 可选 | 已创建的发现运行标识；存在时必须复用 |

输入信息不足时，Agent 可以继续搜索，但必须降低意图判断的置信度，不能用模型常识补全
未提供的业务要求。

### 3.2 输出

Agent 最终输出以下内容：

1. 一句话需求意图理解；
2. `primary` 主推荐；
3. `rejected` 淘汰候选及淘汰原因；
4. Agent 实际执行的搜索记录；
5. 缺失数据、画像冲突、未继续搜索项和接口错误。

每条主推荐至少包含：

- 标题、作者、抖音页面链接和 `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 年龄证据按强度使用

证据优先级为：

1. 视频点赞用户年龄画像；
2. 作者粉丝年龄画像；
3. 标题、描述、话题和详情文本体现的内容适配特征；
4. 题材、人物或作者形象带来的直觉。

第 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 的确定性与一致性

1. **增加事务性最终化**
   - 新增单一 `finalize_video_discovery_run` 能力；
   - 仅允许最终化当前运行已召回且已评估的候选；
   - 在一个事务内校验并写入候选分池、计数、完成状态和最终摘要；
   - 最终化失败必须显式返回错误并支持安全重试。

2. **将关键约束从长提示词下沉到程序**
   - 用结构化节点控制搜索、补证、评估、审计和最终输出；
   - 对必需证据、合法状态和工具调用顺序做程序校验；
   - 保留 LLM 对意图、搜索词、语义相关性和解释的判断空间。

3. **结构化模型输出**
   - 为搜索计划、候选评估和最终结果定义 JSON Schema；
   - 校验 `R / E / S` 取值、必填证据、置信度和分池；
   - 由程序计算 `V`，避免模型计算漂移；
   - 禁止模型输出未召回的候选 ID。

4. **修复模型配置**
   - 让显式传入的 `model` 参数真正生效；
   - 保存实际使用的模型、Prompt 和评分策略版本；
   - 避免固定依赖预览模型。

5. **补齐 Agent 契约测试**
   - 覆盖未保存搜索页、证据晚于评估、审计失败、旧状态查询和报告分池不一致；
   - 覆盖幻觉候选 ID、非法分池、缺失证据和工具预算耗尽；
   - 用固定样例验证相关性闸门、年龄证据层级和未知数据处理。

### 9.2 P1：提高搜索与判断质量

1. **优化搜索前沿选择**
   - 结构化记录每个搜索假设的预期价值、实际新增候选和耗时；
   - 根据边际新增率决定翻页、标签扩展和作者扩展；
   - 减少同义词重复搜索及低价值工具调用。

2. **优化候选预筛与补证**
   - 将低成本预筛规则结构化；
   - 优先为可能改变分池的候选补充详情和画像；
   - 对重复详情和画像增加短期缓存；
   - 记录每项缺失证据对置信度的具体影响。

3. **建立评分评测集**
   - 建立覆盖不同题材的人工标注样例；
   - 分别评估 `R / E / S`，避免只看最终分池；
   - 统计 `primary / rejected` 混淆情况；
   - 按模型、Prompt 和策略版本回放对比。

4. **增强 Agent 可观测性**
   - 记录搜索新增率、候选漏斗、证据缺失率、工具失败率和单次调用成本；
   - 区分模型判断失败、外部接口失败、持久化失败和完成校验失败；
   - 输出本次使用的模型、Prompt、策略和数据源版本。

5. **改进运行恢复**
   - 为同一 `run_id` 增加执行代次；
   - 恢复时明确区分已完成步骤、可复用证据和需要重试的失败项；
   - 避免新一轮执行混用已过期的搜索或候选判断。

### 9.3 P2：升级 Agent 可用证据

1. 接入真实转发用户年龄分布和样本量；
2. 接入分年龄曝光、有效播放、完播率和观看时长；
3. 建立同题材、同发布时间窗口的传播基线；
4. 增加评论中的提醒、家庭沟通、收藏和求链接等结构化意图信号；
5. 在获得明确授权和完整验证前，继续保持“不使用视频理解”的能力边界；
6. 将新证据的计算规则、置信度上限和冲突处理策略版本化。

## 10. Agent 验收标准

一次 `find_agent` 运行满足以下条件，才视为 Agent 自身完成：

1. 已创建或复用唯一 `run_id`；
2. 实际调用的搜索页均已保存；
3. 候选已按 `aweme_id` 去重；
4. 主推荐已尝试获取详情和双侧年龄画像；
5. 年龄画像已标准化，缺失和冲突已披露；
6. 每个已评估候选具有合法分池及对应理由；
7. 最终不存在 `pending_evaluation` 或其他非法分池；
8. 数据库审计返回 `can_finish=true`；
9. 审计后已重新查询最终状态；
10. 最终报告与数据库 `primary / rejected` 完全一致；
11. 不使用未注册的视频理解能力或编造缺失证据；
12. 推荐不足 5 条时不降低质量标准。

若工具故障导致任务无法继续，则不适用上述成功条件，但必须满足：

1. Agent 已根据上下文判断继续调用无法产生有效进展；
2. Agent 已停止重复调用失败工具；
3. 最终摘要明确标记 `任务未完成（工具故障）`；
4. 摘要包含失败工具、原始错误、已完成内容和未完成内容；
5. 不输出看似有效的推荐结果。