find_agent 产品需求文档（PRD）

文档版本：v1.0

基线日期：2026-07-23

文档状态：基于当前代码整理的产品基线，包含目标态要求

Agent 定位：老年受众高潜抖音视频发现 Agent

1. 文档目的

本文定义 find_agent 为什么存在、接收什么输入、如何搜索与判断、必须遵守哪些公理、如何保存过程与输出结果，以及如何验收。

本文以当前代码为事实基线，同时将以下两类内容明确分开：

当前实现：仓库中已经存在、运行时实际可用的能力；
目标要求：为了使 Agent 稳定、可审计地完成业务任务，产品必须达到的状态。

2. 产品概述

2.1 业务问题

平台已经拥有按需求分级的内容需求、参考视频和需求拓展点，但仍需要从抖音海量内容中找到真正可以承接需求的视频。

单纯按关键词或分享数排序无法回答三个关键问题：

视频是否真的回答了本次需求，而不只是标题中出现了相同词语；
视频实际或潜在受众是否偏向老年人；
视频是否具备被转发给家人、朋友或同龄人的传播价值。

find_agent 的任务是同时验证这三个问题，并保留完整的搜索、证据、评分和分池过程。

2.2 产品目标

针对一条 S/A 级需求，自动完成：

理解需求真实意图；
自主生成多个搜索假设；
从多个来源召回、翻页和扩展候选视频；
核验视频详情、互动数据、双侧年龄画像和真实内容；
对需求相关性、老年受众倾向和分享价值进行独立判断；
输出并持久化主推荐、补充推荐和淘汰候选；
保存可恢复、可解释、可审计的完整发现过程。

优先产出至少 5 条质量可靠的保留视频；5 条是探索目标，不是降低准入质量的硬指标。

2.3 核心价值

为内容供给侧提供可以直接使用的视频候选；
将“为什么搜索、为什么推荐、为什么淘汰”变为可查询的数据；
让推荐结论建立在内容与受众证据上，而不是题材刻板印象上；
为后续需求—内容—线上表现反馈闭环提供可追溯的内容承接记录。

3. 用户与使用场景

3.1 主要用户

用户/系统	需要解决的问题
内容供给运营	针对高优需求快速获得可用视频及推荐理由
业务分析人员	查看某条需求搜过什么、遗漏什么、为何保留或淘汰
SupplyAgent 调度任务	批量处理每日 S/A 需求并持久化结果
下游内容系统	消费结构化主推荐和补充推荐
开发与运维人员	定位外部接口、模型、持久化或流程提前结束问题

3.2 核心场景

每日批量发现：按业务日读取全部 S/A 需求及其参考视频点位，逐条执行找片；
单需求重跑：指定 demand_grade_id 或强制重跑某条需求；
交互式找片：直接向 Agent 提供需求词、参考视频和相关点；
长任务恢复：使用 run_id 查询已执行搜索和候选分池，继续未完成的探索；
结果审计：从数据库还原搜索树、证据和最终推荐，解释每个决策。

4. 产品范围

4.1 范围内

S/A 级需求上下文组装；
抖音关键词搜索、TikHub 搜索、作者作品扩展；
关键词翻页、标签扩展和作者扩展；
候选跨来源、跨页去重；
视频详情和播放地址核验；
视频点赞用户画像与作者粉丝画像；
年龄桶标准化；
视频内容解析；
R / E / S / V 评分、解释与分池；
搜索过程、候选证据和最终结果持久化；
双池结果报告和最终文字—数据库同步；
外部接口失败时的可解释降级。

4.2 范围外

生产或改写视频内容；
直接发布视频；
仅凭模型常识推断真实受众；
将点赞用户画像表述为转发用户画像；
替代上游需求分级；
当前阶段自动使用线上 ROV/VOV 重新训练或校准评分；
当前阶段对推荐视频进行人工审核排队。

5. 核心概念

概念	定义
`demand_word`	原始需求词，定义意图边界，但不强制成为实际搜索词
`seed_video_title`	已知相关视频标题，用于消除语义歧义
`relevant_points`	参考视频中与需求相关的灵感、目的或关键点
`reference_videos`	同一需求下的全部参考视频及各自点位
`run_id`	一次找片任务的稳定标识，贯穿所有搜索、候选和结果
搜索根节点	由需求、参考标题、相关点或混合语义形成的独立搜索假设
搜索扩展节点	由翻页、标签或作者形成的子搜索
候选	任一搜索页召回并按 `aweme_id` 幂等合并的视频
双侧画像	视频点赞用户年龄画像与作者粉丝年龄画像
主推荐	需求相关性、老年倾向、分享价值均有可靠证据的候选
补充推荐	相关性较弱或不成立，但老年倾向和分享价值同时很强的候选
淘汰候选	证据显示不应保留，或补证后仍不能满足任一保留池的候选

6. 决策对象与目标函数

对候选视频 v，定义三个互相独立的命题：

R(v)：需求相关性，取值 0~1；
E(v)：老年受众倾向，取值 0~1；
S(v)：分享价值，取值 0~1。

主推荐寻找的是联合事件：

G(v) = R(v) ∩ E(v) ∩ S(v)

综合价值使用加权几何关系：

V(v) = 100 × R(v)^0.40 × E(v)^0.35 × S(v)^0.25

V 用于保持候选排序一致，但不替代证据说明，也不应制造虚假精确性。最终报告以整数展示 R / E / S / V，数据库可保留更高精度。

7. 决策公理与定理

7.1 需求闸门公理

相关性是主推荐的准入条件，不是普通加分项。

高分享、老年受众明显但不回答本次需求的视频，不能进入主推荐；
若其 E 与 S 均强，应保留到补充推荐，而不是直接丢弃；
搜索词命中不等于内容相关，必须由标题、详情或内容核验提供相关性证据；
参考标题和相关点用于理解意图，不要求候选逐字匹配。

7.2 搜索词自主权公理

demand_word 不是必须原样提交搜索接口的命令。

Agent 应先提炼对象、事件、场景、用途、冲突、情绪和叙事角度；
应形成 2~3 个语义不同的根搜索假设；
搜索词价值由新增有效候选衡量，而不是由字面相似度衡量；
第一个关键词有结果不代表需求已经被充分覆盖。

7.3 搜索前沿扩展定理

搜索是可生长、可追踪的探索图，不是一次接口调用。

根节点来源：demand / seed / point / mixed；
子节点来源：tag / author / pagination；
has_more=true 且本页产生有效新增候选时，下一页是仍存在的信息前沿；
优质候选的话题、标题实体、作者和内容新角度可以触发子搜索；
每个搜索节点必须记录形成原因、来源、父节点和供应方分页状态；
根节点不得设置 parent_search_id，扩展节点应记录父节点。

7.4 分享—年龄不可替代定理

分享证据与年龄证据不能相互替代。

高 share_count 只说明内容已发生传播；
高老年占比或 TGI 只说明受众偏老；
只有同一候选同时具备两类证据，才可以表述为“老年人可能喜欢并分享”；
当前工具提供的是点赞用户画像，不是转发用户画像，禁止声称已经观察到老年分享者。

7.5 受众证据层级定理

老年倾向证据按以下优先级使用：

视频自身的点赞用户年龄画像；
作者粉丝年龄画像；
视频真实内容呈现出的适配特征；
标题、题材、画面人物或作者形象带来的直觉。

第 4 层不能单独形成结论。视频画像与作者画像冲突时，优先视频画像并降低置信度，不能静默平均。

明确覆盖 50 岁及以上的桶才是直接老年信号；40+ 只能作为成熟人群代理信号。 50- / 50+ / 50岁以上 / >=50 / 41-50 等表达必须先标准化。

7.6 相对传播定理

分享价值同时考虑规模、效率和动机：

规模：log(1 + share_count) 在同类候选中的相对位置；
效率：优先使用 share_count / play_count；
替代效率：播放数缺失时使用平滑后的 share_count / like_count，并标明其局限；
动机：实用提醒、家庭沟通、情感认同、共同记忆或谈资价值。

禁止跨不同题材机械比较原始分享数，也不能让低样本高比率候选自动排到最前。

7.7 联合短板定理

R / E / S 任一维度接近零都会显著压低 V。三个弱证据不能通过简单相加伪装成一个强结论。

主推荐必须同时通过 R / E / S 的证据判断；
补充推荐不是“低质量主推荐”，而是相关性受限但 E / S 双强的独立池；
Agent 对分池负责，持久化工具不应偷偷重算评分或改写分池；
5 条是结果目标，不是放宽质量边界的理由。

7.8 反证优先公理

一个强反证比多个弱正向线索更重要。

真实内容明显围绕青少年校园、年轻圈层黑话或特定年轻文化时，应降低 E；
画像明显偏年轻时，应作为强反证；
快剪辑或网络表达等单一风格特征不能直接证明老年人不喜欢；
缺失数据是未知，不是负证据；接口失败不能计为零分。

7.9 多样性边际定理

推荐集合应提供新增价值。

高度重复的视频只保留证据更强的一条；
价值相近时，优先覆盖不同需求点、内容角度和分享动机；
不能用同质内容堆叠数量。

7.10 信息价值停止律

只有当额外搜索、详情、画像或内容解析可能改变准入、排序或置信度时，才继续调用。

证据足以区分候选时停止；
合理搜索前沿耗尽后，允许少于 5 条结束；
没有可靠候选时可以返回空结果；
不得为了凑数扩大到明显低质内容。

8. 产品设计原则

证据先于直觉：模型解释必须锚定搜索结果、详情、画像或内容解析；
事实与推断分离：明确区分接口事实、计算结果和模型判断；
未知不等于否定：缺失、失败和样本不足通过未知与置信度表达；
过程优先可审计：每次搜索、翻页、扩展、补证和分池都必须可还原；
决策权单一：Agent 负责最终分池，工具负责保存，不在多个位置重复解释规则；
状态可恢复：长任务可以通过 run_id 从数据库恢复，而不依赖单次模型上下文；
幂等去重：同一运行内以 (run_id, aweme_id) 唯一，同一搜索页重复保存不新增候选；
成本逐层增加：先搜索和互动预筛，再详情与画像，最后只解析最有信息价值的视频；
失败可降级：单一供应方失败不应让整次任务直接失去业务结果；
输出与数据库一致：最终报告中的主推荐/补充推荐必须与最终持久化分池一致。

9. 端到端流程

9.1 总流程图

flowchart TD
    A["读取业务日 S/A 需求"] --> B["聚合同一需求下全部参考视频与相关点"]
    B --> C{"是否已有 running / finished 运行"}
    C -->|"是且非强制重跑"| C1["跳过并记录原因"]
    C -->|"否或强制重跑"| D["预创建 video_discovery_run"]
    D --> E["Agent 复用 run_id 并解释真实需求意图"]
    E --> F["生成 2~3 个语义不同的根搜索词"]
    F --> G["内部搜索 / TikHub 搜索"]
    G --> H["保存搜索页并按 aweme_id 幂等并入候选"]
    H --> I["候选状态 pending_evaluation"]
    I --> J["按相关性、分享规模/效率、补充潜力廉价预筛"]
    J --> K["批量拉取详情，默认最多 8 条"]
    K --> L["批量获取视频点赞画像 + 作者粉丝画像"]
    L --> M["标准化年龄桶并识别一致、冲突或缺失"]
    M --> N["对最可能改变决策的候选做视频内容解析，默认最多 3 条"]
    N --> O["计算 R / E / S / V，形成证据理由与置信度"]
    O --> P{"分池判断"}
    P -->|"三维共同成立"| P1["primary"]
    P -->|"E/S 双强但 R 弱"| P2["backup"]
    P -->|"不满足保留条件"| P3["rejected"]
    P1 --> Q["保存候选证据与分池"]
    P2 --> Q
    P3 --> Q
    Q --> R{"是否仍有高信息价值前沿"}
    R -->|"翻页"| G
    R -->|"标签扩展"| G
    R -->|"作者扩展"| G
    R -->|"没有"| S["保存 finished 与停止原因"]
    S --> T["查询最终数据库状态"]
    T --> U["输出主推荐、补充推荐、淘汰候选、搜索树和缺失数据"]
    U --> V["按最终报告再次同步主/补充分池"]

9.2 阶段说明

阶段 1：任务装配

读取指定业务日的 S/A 级 demand_grade；
聚合该需求下全部 demand_video_expansion；
仅保留 inspiration / purpose / key 三类有效点位；
补充参考视频标题；
一个需求形成一条 FindDemandContext，而不是一个参考视频形成一条任务。

阶段 2：运行初始化

以 (biz_dt, demand_grade_id) 检查已有运行；
默认跳过 running / finished；
强制重跑时复用或重置对应运行；
预创建 video_discovery_run；
Agent 第一项动作必须复用系统给定 run_id。

阶段 3：意图理解与根搜索

综合 demand_word、全部参考视频和全部相关点；
输出一句清晰的真实意图解释；
形成 2~3 个不同语义方向的根搜索词；
为每个词写明希望验证的内容假设。

阶段 4：多源召回与搜索图扩展

内部关键词搜索作为基础来源；
TikHub 作为独立来源，失败时回退内部搜索；
TikHub 翻页必须同时复用 cursor / search_id / backtrace；
生产性首页默认最多继续一页；
高潜作者可按最热或最新扩展作品；
高价值话题可形成标签搜索分支；
每一页，无论成功、空结果或失败，都应保存状态。

阶段 5：候选并入与预筛

所有来源统一为 search_results；
以 aweme_id 做跨词、跨页、跨供应方幂等合并；
新候选进入 pending_evaluation；
先根据标题相关性、互动量和补充潜力预筛；
默认最多 8 条进入详情和双画像阶段。

阶段 6：证据补全

douyin_detail 核验标题、作者、互动数据、话题、页面链接和播放地址；
batch_fetch_portraits(fetch_account_portrait=true) 同时获取双侧画像；
批量画像自动输出标准化年龄结果；
内容画像缺失时，作者画像只能作为账号先验；
画像冲突、缺失和失败必须原样保存；
默认最多 3 条调用视频内容解析；
内容解析提示必须包含本次需求和相关点，并区分明确呈现与模型推断。

阶段 7：评分与分池

独立形成 R / E / S；
计算 V 并给出置信度；
输出每一维的正证、反证和限制；
分为 primary / backup / rejected；
对新增或证据变化的候选重新保存；
保留数量不足 5 条时，优先继续高价值搜索前沿。

阶段 8：停止、持久化与输出

无明显高信息价值前沿后，将运行保存为 finished；
保存停止原因；
查询最终状态，确保搜索与候选完整；
输出最终报告；
运行结束后，从最终报告的主推荐和补充推荐段提取 aweme_id，再次同步数据库分池。

10. 状态模型

10.1 运行状态

running ──正常完成──> finished
   │
   └────异常中止──> failed

同一业务日与 demand_grade_id 只保留一条调度运行身份。--force 允许重新执行。

10.2 候选状态

搜索召回
   ↓
pending_evaluation
   ↓ 详情、画像、内容、评分
   ├── primary
   ├── backup
   └── rejected

pending_evaluation 不能直接作为最终推荐；
候选补充新证据后允许重新评估和改变分池；
最终报告中的主推荐与补充推荐对数据库对应分池具有同步作用。

10.3 搜索图

`source_type`	类型	父节点规则
`demand`	需求语义根搜索	无父节点
`seed`	参考标题根搜索	无父节点
`point`	相关点根搜索	无父节点
`mixed`	多证据混合根搜索	无父节点
`tag`	标签扩展	记录父搜索
`author`	作者作品扩展	记录父搜索
`pagination`	同一搜索翻页	记录父搜索

11. 功能需求

FR-01 输入聚合

系统必须按需求粒度聚合全部参考视频和有效点位；
必须保留每个点位的来源视频、点位类型和描述；
无有效点位的需求不进入找片任务；
交互式输入至少应包含 demand_word，参考标题或相关点缺失时应明确降低意图置信度。

FR-02 运行身份与幂等

调度执行必须在 Agent 运行前预创建 run_id；
Agent 必须复用传入的 run_id；
所有持久化工具必须使用同一 run_id；
(biz_dt, demand_grade_id) 和 (run_id, aweme_id) 必须保持唯一；
重复保存同一搜索页不得重复增加候选。

FR-03 意图解释

Agent 必须先形成对真实需求的简短解释；
解释必须引用需求词、参考视频或相关点；
解释必须明确内容对象、场景或用途；
不能把原始需求词直接等同于唯一搜索词。

FR-04 自主搜索

默认形成 2~3 个语义不同的根搜索词；
每个搜索词必须包含 query_reason；
搜索结果必须统一返回视频 ID、标题、链接、作者和互动数据；
TikHub 缺少密钥或请求失败时，必须记录失败并回退内部搜索；
不得混用不同供应方的分页游标。

FR-05 搜索页持久化

每次搜索调用后必须保存搜索页；
空页应保存为成功空结果，而不是伪装成失败；
失败页应保存错误原因；
必须保存实际查询词、供应方、筛选条件、游标、页码、是否有下一页和新增候选数；
标签、作者和翻页扩展必须能回溯父搜索。

FR-06 候选召回与去重

新召回候选必须进入 pending_evaluation；
同一视频在多个搜索中出现时合并来源词、来源搜索 ID 和标签；
互动数据可由详情核验结果更新；
已评估候选再次被召回时不得无条件重置为待评估。

FR-07 详情核验

正式保留候选必须尝试核验详情；
单次详情工具最多处理 8 条；
部分视频失败时必须返回成功项与失败项，不因单项失败丢弃整批；
详情应尽量提供页面链接、播放地址、作者、话题和互动数据。

FR-08 双侧年龄画像

正式候选必须尝试视频点赞用户画像；
正式候选应同时尝试作者粉丝画像；
批量画像单次最多处理 8 条；
必须保存每一侧是否尝试、是否有数据和失败原因；
画像必须执行确定性年龄桶标准化；
仅有作者画像时，E 置信度必须受限；
双侧冲突时必须明确标注并降低置信度。

FR-09 视频内容核验

有可用播放地址且内容核验会影响决策时，应调用视频解析；
默认最多解析 3 条最有信息价值的候选；
解析提示必须包含本次需求与相关点；
内容解析不能代替年龄画像；
超长视频默认截断到 180 秒，截断失败或依赖缺失必须返回明确错误。

FR-10 评分与解释

每个已评估候选应包含 R / E / S / V；
每一维应有独立理由；
必须保存命中需求点、分享动机、正向证据、主要限制和置信度；
分数缺失时不得伪造；
缺失证据不应自动变成零分。

FR-11 双池分流

primary：R / E / S 三个命题均成立；
backup：不满足主推荐，但 E / S 同时强，并明确相关性限制；
rejected：不满足任一保留池，或强反证足以否定；
backup 不得在报告中伪装成主推荐；
低相关但高传播候选必须在淘汰前先评估其补充潜力。

FR-12 探索与停止

保留候选不足 5 条时，应优先继续不同根搜索、生产性首页翻页或高价值标签/作者扩展；
达到 5 条后，没有明显更高价值前沿时应优先结束；
第二页仍明显产生高价值新增候选时，可继续深挖，但不得无界翻页；
少于 5 条结束时，必须说明前沿已耗尽或继续探索价值较低；
空结果允许结束，但必须能证明不是模型提前停止。

FR-13 持久化与恢复

必须保存运行、搜索页和候选三个粒度的数据；
候选记录必须包含详情、互动、双侧画像、标准化结果、内容分析、评分、理由和分池；
查询状态必须可恢复搜索树与候选池；
数据库不可用时只尝试一次初始化写入，之后以内存结构继续业务流程；
降级结果必须醒目标注“未持久化”及原因。

FR-14 最终输出

最终报告必须按以下顺序输出：

一句话需求意图理解；
主推荐；
补充推荐；
最有竞争力但被淘汰的候选；
搜索树；
缺失数据、画像冲突、未继续前沿和接口失败。

每条主推荐或补充推荐必须包含：

排名、标题、作者、抖音页面链接、aweme_id；
命中的需求点与相关性证据；
原始 share_count；
可计算时的分享率或替代指标；
视频点赞年龄画像证据；
作者粉丝年龄画像证据；
老年人可能愿意分享的内容动机；
R / E / S / V 整数分；
高/中/低置信度；
同时包含正证和主要限制的一句话理由。

FR-15 最终一致性

报告中主推荐的 ID 必须属于数据库 primary；
报告中补充推荐的 ID 必须属于数据库 backup；
淘汰候选不能出现在补充推荐段；
最终文字分池与数据库不一致时，系统必须阻止完成或产生显式错误；
最终分池同步必须可观测，失败不能静默吞掉。

12. 工具能力与证据含义

工具	产品用途	关键约束
`douyin_search`	内部关键词召回	支持筛选与游标翻页；结果不是最终事实
`douyin_search_tikhub`	独立 TikHub 召回	翻页必须复用 `cursor/search_id/backtrace`
`douyin_user_videos`	扩展高潜作者作品	作者优秀不代表作品自动合格
`douyin_detail`	批量核验详情与播放地址	单次最多 8 条
`get_content_fans_portrait`	单条视频点赞用户画像	不是分享用户画像
`get_account_fans_portrait`	单条作者粉丝画像	只作为账号受众先验
`batch_fetch_portraits`	批量获取双侧画像	单次最多 8 条；正式候选设置作者画像为真
`normalize_age_portraits`	确定性标准化年龄桶	不替代业务评分
`qwen_video_analyze`	核验真实内容与分享动机	默认最多 3 条；不能替代年龄画像
`create_video_discovery_run`	创建或复用运行	调度场景必须复用预创建 `run_id`
`record_video_search_page`	保存搜索页并合并候选	所有搜索页都必须保存
`batch_save_video_candidate_evaluations`	保存证据、评分和分池	原样保存，不重算、不改池
`query_video_discovery_state`	恢复和检查运行状态	可选择是否包含淘汰候选

当前共享基础工具还会注册 load_skill，但它不是本 Agent 的核心业务链路。

13. 数据模型

13.1 `video_discovery_run`

一次需求找片运行，保存：

业务日和需求 ID；
demand_word、参考视频和相关点输入快照；
Agent 的最终意图解释；
running / finished / failed 状态；
搜索页数、主推荐数、补充推荐数；
停止原因或失败原因。

13.2 `video_discovery_search`

搜索图中的一个具体页面，保存：

实际搜索词和形成原因；
根搜索/标签/作者/翻页来源；
父搜索 ID；
供应方与供应方分页状态；
筛选条件、游标和页码；
本页结果数、新增候选数、是否有下一页；
本页候选 ID；
成功、失败和错误信息。

13.3 `video_discovery_candidate`

一次运行中的一条视频，保存：

视频与作者身份；
来源词、来源搜索和标签；
互动数据；
视频点赞年龄证据、作者粉丝年龄证据和标准化结果；
详情、画像、年龄标准化和内容解析是否已执行；
内容分析和扩展价值标签；
R / E / S / V、置信度和各维理由；
primary / backup / rejected / pending_evaluation 分池。

14. 成本与运行预算

14.1 产品默认预算

项目	默认约束
Agent 最大迭代	60
搜索类工具调用	最多 10 次
详情工具调用	最多 2 次，每次最多 8 条
画像工具调用	最多 3 次，每批最多 8 条
视频内容解析	最多 3 次
候选评估保存	最多 6 次
状态查询	最多 8 次，且无状态变化时禁止无意义重复
根搜索词	默认 2~3 个
生产性首页翻页	默认继续 1 页
正式补证候选	默认最多 8 条
视频解析候选	默认最多 3 条

14.2 预算原则

预算是防止无界探索的上限，不是必须耗尽的配额；
优先使用批量详情和批量画像；
只有可能改变分池或置信度时才做视频解析；
外部接口存在串行限流，搜索深度必须服从信息价值。

15. 异常与降级策略

异常	处理要求
TikHub Key 缺失	保存错误，切换内部关键词搜索，不重复相同失败调用
某搜索源失败	保留失败页，尝试其他供应方或语义假设
搜索空页	保存空页并关闭对应无效前沿，不伪装为接口失败
详情部分失败	保留成功项和逐条失败原因
内容画像缺失	尝试作者画像，标记 `account_only`，降低置信度
双侧画像冲突	优先视频画像，显式标注冲突
视频无播放地址	不强制内容解析，保存缺失状态
视频解析失败	保留原始错误，不用模型常识补写内容
数据库不可用	一次失败后转内存流程，最终披露未持久化
Agent 或模型异常	运行标记 `failed` 并保存异常原因
最终分池同步失败	记录错误并将任务视为未完整完成

16. 非功能需求

16.1 可解释性

每个搜索词必须有形成原因；
每个保留或淘汰候选必须有决策理由；
最终报告必须披露主要缺失与限制；
禁止无证据年龄结论。

16.2 可追溯性

输入、搜索树、候选证据、分数、分池和停止原因必须通过同一 run_id 关联；
供应方分页状态必须原样保存；
最终结果必须能回溯到召回页面。

16.3 一致性

搜索页与候选合并必须幂等；
运行计数应从真实搜索和分池状态刷新；
最终报告与数据库分池必须一致；
同一候选的重复来源必须合并而不是覆盖。

16.4 可用性

一个外部接口失败不应中止所有业务判断；
部分证据缺失时允许降置信度继续；
所有错误必须保留真实语义，不能编造缺失字段。

16.5 安全与配置

API Key、数据库密码和 OSS 密钥只能从环境配置读取；
日志和报告不得输出完整密钥；
长视频临时文件必须在处理后清理；
公网播放地址和 OSS 地址应遵守数据授权与访问控制要求。

17. 成功指标

17.1 业务指标

指标	定义
任务完成率	成功进入 `finished` 且输出完整报告的任务占比
主推荐需求准确率	抽检中真正承接需求的主推荐占比
老年证据有效率	保留候选中具有有效视频或作者年龄画像的占比
分享证据完整率	保留候选中同时具有分享规模/效率和内容动机说明的占比
有效保留数	每次运行 `primary + backup` 数量及分布
补充池有效率	补充候选经业务抽检确认值得保留的占比
推荐多样性	保留结果覆盖的不同需求点和分享动机数量

17.2 流程指标

指标	定义
搜索页持久化率	已调用搜索页中成功保存的占比
候选证据完整率	保留候选完成详情、双画像尝试、年龄标准化和必要内容核验的占比
最终分池一致率	最终报告与数据库分池完全一致的运行占比
重复候选率	去重前重复候选占比，用于观察搜索冗余
搜索新增效率	每个搜索页新增有效候选数
降级成功率	单供应方失败后仍成功完成任务的占比
平均运行时长	从运行创建到最终完成的耗时
单任务工具成本	各类搜索、详情、画像和解析调用次数

18. 验收标准

18.1 功能验收

一次运行满足以下条件才视为产品完成：

正确装配一条需求及其全部有效参考点；
创建或复用唯一 run_id；
执行并保存实际搜索页；
所有召回候选按 aweme_id 幂等合并；
最终保留候选具有足够的详情、画像和内容证据；
所有年龄画像已经标准化；
候选被明确分为主推荐、补充推荐、淘汰或待评估；
最终运行状态和停止原因已保存；
报告满足输出契约；
报告与数据库分池完全一致；
任何外部失败、证据缺失和画像冲突均被披露；
少于 5 条时没有为了凑数放宽质量标准。

18.2 负向验收

出现以下任一情况，运行不得被判定为稳定完成：

用题材或画面中出现老人代替受众年龄证据；
将点赞用户画像声称为分享用户画像；
把低相关高分享视频放入主推荐；
将符合补充池条件的候选直接丢弃且无理由；
pending_evaluation 直接出现在推荐结果；
新搜索或新证据产生后未重新保存受影响候选；
报告推荐 ID 与数据库分池不一致；
审计未通过仍输出过程性“接下来继续”的半截答案；
因数量不足而推荐明显低质视频；
接口失败后编造画像、详情或内容结论。

19. 当前实现状态

19.1 已实现

S/A 需求、参考视频和点位的任务装配；
业务日批量执行、并发 worker、跳过已运行任务和强制重跑；
内部关键词、TikHub 和作者作品三类召回；
多源统一候选结构与供应方分页状态；
搜索页和候选的幂等持久化；
详情批量核验；
视频点赞画像、作者粉丝画像和批量双侧画像；
年龄桶确定性标准化；
千问视频内容解析与长视频截断；
R / E / S / V、理由、完成标记和分池字段；
三张视频发现数据表及状态恢复；
最终报告 ID 提取和主/补充分池同步；
工具调用预算和无状态变化时的重复查询约束。

19.2 部分实现

搜索图扩展、信息价值停止和双池判断主要依赖模型遵守提示词；
数据库不可用的内存降级由提示词要求，缺少统一的结构化运行时接管；
最终报告会反向同步分池，但同步失败当前只记录日志，不会让调用显式失败；
最终报告同步当前只更新报告中出现的 ID，不会自动清理报告中已省略的旧主/补充候选；
find_agent_completion_guard 已有实现与测试，但当前 Agent 配置为 completion_guard=None；
流程审计函数已经实现，但 audit_video_discovery_process 和 audit_video_discovery_run 当前没有注册给 Agent。

19.3 尚未实现或仍有关键证据缺口

实际转发用户年龄画像；
各年龄段曝光、完播率和观看时长；
同题材、相近发布时间的传播基线；
平台相似视频直接扩展；
标准话题热度与稳定批量话题服务；
评论中的转发动机结构化信号；
推荐内容上线后的真实表现回流与评分校准；
运行时确定性完成守卫；
正式的端到端 SLA、告警和仪表盘。

20. 当前主要风险

风险	影响	产品要求
点赞画像不等于转发画像	“老年人会分享”只能是概率推断	报告必须使用谨慎措辞，并优先建设转发画像
内容画像经常缺失	`E` 过度依赖作者先验	明确 `account_only` 和较低置信度
完成守卫暂停	模型可能在流程未闭合时提前结束	P0 恢复确定性完成约束
审计工具未注册	无法在 Agent 内主动验证流程	P0 注册并要求结束前审计
最终文字可反向改池	格式错误可能造成数据状态变化	同步前做严格校验并保证事务一致性
最终分池采用增量同步	报告中省略的旧候选可能仍留在主/补充池	改为一次运行内的原子全量对齐
外部接口串行限流	多词、多候选任务时延较高	更强预筛、批量接口和明确 SLA
原始分享数不可跨题材比较	`S` 排序可能偏向高曝光题材	建设同主题传播基线
TikHub 为可选依赖	环境遗漏时搜索覆盖下降	配置预检、清晰降级与环境样例补全
模型行为依赖长提示词	规则可能被遗漏	将硬性流程约束下沉到确定性代码

21. 迭代优先级

P0：稳定完成与数据一致性

注册数据库审计工具；
恢复并完善 find_agent_completion_guard；
强制最后一次搜索、证据变更、评估、审计和状态查询满足时序要求；
最终报告同步前校验 ID 与分池，并以一次运行为范围原子替换最终双池；
同步失败时显式返回未完成，而不是只写日志；
为所有外部依赖增加启动前配置检查；
增加端到端成功、提前停止、数据库降级和分池错位验收。

P1：提升结论可靠性

接入实际转发用户年龄画像；
接入受众留存、完播率和观看时长；
实现多关键词批量搜索与服务端限流；
接入平台相似视频；
接入标准话题与话题热度；
用同题材传播基线校准分享规模和效率。

P2：建立反馈闭环

建立需求—推荐视频—最终使用内容的映射；
回收真实 ROV/VOV 与内容质量信息；
分析主推荐、补充推荐和淘汰候选的后验表现；
基于历史样本校准 R / E / S 与置信度；
将校准参数纳入版本化策略，而不是继续写入提示词。

22. 产品完成定义

find_agent 达到产品化完成状态，需要同时满足：

对每日 S/A 需求可以稳定自动执行；
任务过程可恢复、可解释、可审计；
推荐建立在需求、年龄和分享三类独立证据上；
主推荐、补充推荐和淘汰候选的边界清晰；
合理前沿耗尽时能够停止，数量不足时不降低质量；
外部接口失败时可解释降级；
最终报告与持久化结果始终一致；
运行时能够确定性阻止提前结束和不完整输出；
后续可以将真实内容表现回流到需求供给闭环中。

PRD.md 35 KB История Исходник