|
|
@@ -1,10 +1,10 @@
|
|
|
# find_agent 产品需求文档（PRD）
|
|
|
|
|
|
-> 文档版本：v1.0
|
|
|
+> 文档版本：v1.1
|
|
|
>
|
|
|
-> 基线日期：2026-07-23
|
|
|
+> 基线日期：2026-07-28
|
|
|
>
|
|
|
-> 文档状态：基于当前代码整理的产品基线，包含目标态要求
|
|
|
+> 文档状态：基于当前代码、近期提交与定向测试整理的产品基线，包含优化项与后续方向
|
|
|
>
|
|
|
> Agent 定位：老年受众高潜抖音视频发现 Agent
|
|
|
|
|
|
@@ -16,7 +16,8 @@
|
|
|
本文以当前代码为事实基线，同时将以下两类内容明确分开：
|
|
|
|
|
|
- **当前实现**：仓库中已经存在、运行时实际可用的能力；
|
|
|
-- **目标要求**：为了使 Agent 稳定、可审计地完成业务任务，产品必须达到的状态。
|
|
|
+- **目标要求**：为了使 Agent 稳定、可审计地完成业务任务，产品必须达到的状态；
|
|
|
+- **后续方向**：需要额外数据、服务或业务闭环才能实现的中长期能力。
|
|
|
|
|
|
相关实现入口：
|
|
|
|
|
|
@@ -28,6 +29,47 @@
|
|
|
- 当前说明：[README.md](README.md)
|
|
|
- 验证记录：[VALIDATION.md](VALIDATION.md)
|
|
|
|
|
|
+### 1.1 当前结论摘要
|
|
|
+
|
|
|
+截至 2026-07-28，`find_agent` 已具备“需求装配—多源搜索—详情与双侧画像—评分分池—
|
|
|
+过程落库—下游发布”的主体链路，数据库模型、搜索去重和批量画像等基础能力较完整，
|
|
|
+但仍处于**可运行、未达到稳定无人值守**的阶段。
|
|
|
+
|
|
|
+当前最关键的产品判断如下：
|
|
|
+
|
|
|
+1. **召回与证据基础已经具备**：支持内部搜索、TikHub、作者作品扩展、详情、视频点赞
|
|
|
+ 用户画像、作者粉丝画像和年龄桶标准化；
|
|
|
+2. **完成闭环尚未可靠**：完成守卫当前关闭，数据库审计工具没有注册给 Agent，模型
|
|
|
+ 可以在证据或流程未闭合时自行结束；
|
|
|
+3. **明确不使用视频理解**：当前相关性和分享动机只依据标题、描述、话题、详情文本、
|
|
|
+ 互动数据和画像判断；`qwen_video_analyze.py` 与历史字段即使保留，也不属于在线
|
|
|
+ 能力；
|
|
|
+4. **吞吐能力主动收敛**：每日任务固定单线程串行执行，单需求核心运行超时 1800 秒，
|
|
|
+ 当日 `primary` 去重视频达到 200 条后停止；稳定性优先于吞吐；
|
|
|
+5. **最终一致性是“尽力而为”而非强保证**：最终文字会再次反向同步数据库分池，但
|
|
|
+ 发布或同步超时/失败只写日志，主调用仍可能返回成功；
|
|
|
+6. **最终等级已经收敛**：`pending_evaluation` 仅为过程状态，最终只允许
|
|
|
+ `primary / rejected`，不再设置 `backup`、补充推荐或人工备选。
|
|
|
+
|
|
|
+因此，下一阶段不应继续堆叠新召回源，而应先完成四项 P0：统一当前产品契约、恢复
|
|
|
+确定性完成约束、实现最终结果原子对齐、补齐运行恢复与回归测试。完成 P0 后再扩大
|
|
|
+并发或建设更强的受众与传播数据。
|
|
|
+
|
|
|
+### 1.2 文档边界
|
|
|
+
|
|
|
+- 本文的“已实现”仅指当前 Agent 实际注册、调度或持久化链路可以触达的能力；
|
|
|
+- 代码文件存在但未注册、未启用或无法被当前流程调用的能力，统一标为“保留代码/
|
|
|
+ 暂停能力”，不计入现状完成度；
|
|
|
+- 指标中的目标值是产品上线门槛，不代表当前已经达到；
|
|
|
+- 外部接口真实可用性仍需以对应环境的密钥、网络和数据权限为准。
|
|
|
+
|
|
|
+### 1.3 修订记录
|
|
|
+
|
|
|
+| 版本 | 日期 | 说明 |
|
|
|
+|---|---|---|
|
|
|
+| v1.0 | 2026-07-23 | 建立产品目标、决策公理、工具、数据模型与验收基线 |
|
|
|
+| v1.1 | 2026-07-28 | 按近期代码更新视频理解、单线程、超时与最终同步现状；补充风险、优化优先级、指标、里程碑和待确认决策 |
|
|
|
+
|
|
|
## 2. 产品概述
|
|
|
|
|
|
### 2.1 业务问题
|
|
|
@@ -50,9 +92,9 @@
|
|
|
1. 理解需求真实意图；
|
|
|
2. 自主生成多个搜索假设；
|
|
|
3. 从多个来源召回、翻页和扩展候选视频；
|
|
|
-4. 核验视频详情、互动数据、双侧年龄画像和真实内容；
|
|
|
+4. 核验视频详情、互动数据、双侧年龄画像和可验证的内容字段；
|
|
|
5. 对需求相关性、老年受众倾向和分享价值进行独立判断；
|
|
|
-6. 输出并持久化主推荐、补充推荐和淘汰候选；
|
|
|
+6. 输出并持久化主推荐和淘汰候选；
|
|
|
7. 保存可恢复、可解释、可审计的完整发现过程。
|
|
|
|
|
|
优先产出至少 5 条质量可靠的保留视频；5 条是探索目标，不是降低准入质量的硬指标。
|
|
|
@@ -73,7 +115,7 @@
|
|
|
| 内容供给运营 | 针对高优需求快速获得可用视频及推荐理由 |
|
|
|
| 业务分析人员 | 查看某条需求搜过什么、遗漏什么、为何保留或淘汰 |
|
|
|
| SupplyAgent 调度任务 | 批量处理每日 S/A 需求并持久化结果 |
|
|
|
-| 下游内容系统 | 消费结构化主推荐和补充推荐 |
|
|
|
+| 下游内容系统 | 消费结构化主推荐 |
|
|
|
| 开发与运维人员 | 定位外部接口、模型、持久化或流程提前结束问题 |
|
|
|
|
|
|
### 3.2 核心场景
|
|
|
@@ -95,10 +137,10 @@
|
|
|
- 视频详情和播放地址核验；
|
|
|
- 视频点赞用户画像与作者粉丝画像；
|
|
|
- 年龄桶标准化；
|
|
|
-- 视频内容解析；
|
|
|
+- 基于标题、描述、话题和详情字段的内容判断；
|
|
|
- `R / E / S / V` 评分、解释与分池；
|
|
|
- 搜索过程、候选证据和最终结果持久化；
|
|
|
-- 双池结果报告和最终文字—数据库同步；
|
|
|
+- `primary / rejected` 结果报告和最终文字—数据库同步；
|
|
|
- 外部接口失败时的可解释降级。
|
|
|
|
|
|
### 4.2 范围外
|
|
|
@@ -109,7 +151,8 @@
|
|
|
- 将点赞用户画像表述为转发用户画像；
|
|
|
- 替代上游需求分级；
|
|
|
- 当前阶段自动使用线上 ROV/VOV 重新训练或校准评分；
|
|
|
-- 当前阶段对推荐视频进行人工审核排队。
|
|
|
+- 当前阶段对推荐视频进行人工审核排队；
|
|
|
+- 当前在线链路中的视频画面、语音或字幕理解；相关工具代码仍保留，但已暂停注册。
|
|
|
|
|
|
## 5. 核心概念
|
|
|
|
|
|
@@ -125,8 +168,7 @@
|
|
|
| 候选 | 任一搜索页召回并按 `aweme_id` 幂等合并的视频 |
|
|
|
| 双侧画像 | 视频点赞用户年龄画像与作者粉丝年龄画像 |
|
|
|
| 主推荐 | 需求相关性、老年倾向、分享价值均有可靠证据的候选 |
|
|
|
-| 补充推荐 | 相关性较弱或不成立，但老年倾向和分享价值同时很强的候选 |
|
|
|
-| 淘汰候选 | 证据显示不应保留，或补证后仍不能满足任一保留池的候选 |
|
|
|
+| 淘汰候选 | 补证后仍不能满足 `primary` 准入条件的候选 |
|
|
|
|
|
|
## 6. 决策对象与目标函数
|
|
|
|
|
|
@@ -154,7 +196,7 @@
|
|
|
相关性是主推荐的准入条件，不是普通加分项。
|
|
|
|
|
|
- 高分享、老年受众明显但不回答本次需求的视频，不能进入主推荐；
|
|
|
-- 若其 `E` 与 `S` 均强，应保留到补充推荐，而不是直接丢弃；
|
|
|
+- 即使 `E` 与 `S` 均强，只要 `R` 不成立，也必须进入 `rejected`；
|
|
|
- 搜索词命中不等于内容相关，必须由标题、详情或内容核验提供相关性证据；
|
|
|
- 参考标题和相关点用于理解意图，不要求候选逐字匹配。
|
|
|
|
|
|
@@ -218,8 +260,8 @@
|
|
|
`R / E / S` 任一维度接近零都会显著压低 `V`。三个弱证据不能通过简单相加伪装成一个
|
|
|
强结论。
|
|
|
|
|
|
-- 主推荐必须同时通过 `R / E / S` 的证据判断；
|
|
|
-- 补充推荐不是“低质量主推荐”，而是相关性受限但 `E / S` 双强的独立池；
|
|
|
+- `primary` 必须同时通过 `R / E / S` 的证据判断；
|
|
|
+- 未同时通过三项判断的候选必须进入 `rejected`，不设中间等级；
|
|
|
- Agent 对分池负责，持久化工具不应偷偷重算评分或改写分池；
|
|
|
- 5 条是结果目标，不是放宽质量边界的理由。
|
|
|
|
|
|
@@ -242,7 +284,7 @@
|
|
|
|
|
|
### 7.10 信息价值停止律
|
|
|
|
|
|
-只有当额外搜索、详情、画像或内容解析可能改变准入、排序或置信度时，才继续调用。
|
|
|
+只有当额外搜索、详情或画像可能改变准入、排序或置信度时，才继续调用。
|
|
|
|
|
|
- 证据足以区分候选时停止；
|
|
|
- 合理搜索前沿耗尽后，允许少于 5 条结束；
|
|
|
@@ -251,24 +293,24 @@
|
|
|
|
|
|
## 8. 产品设计原则
|
|
|
|
|
|
-1. **证据先于直觉**：模型解释必须锚定搜索结果、详情、画像或内容解析；
|
|
|
+1. **证据先于直觉**：模型解释必须锚定搜索结果、详情、画像或可验证的内容字段；
|
|
|
2. **事实与推断分离**：明确区分接口事实、计算结果和模型判断；
|
|
|
3. **未知不等于否定**：缺失、失败和样本不足通过未知与置信度表达；
|
|
|
4. **过程优先可审计**：每次搜索、翻页、扩展、补证和分池都必须可还原；
|
|
|
5. **决策权单一**：Agent 负责最终分池，工具负责保存，不在多个位置重复解释规则；
|
|
|
6. **状态可恢复**：长任务可以通过 `run_id` 从数据库恢复，而不依赖单次模型上下文；
|
|
|
7. **幂等去重**：同一运行内以 `(run_id, aweme_id)` 唯一，同一搜索页重复保存不新增候选；
|
|
|
-8. **成本逐层增加**：先搜索和互动预筛，再详情与画像，最后只解析最有信息价值的视频；
|
|
|
+8. **成本逐层增加**：先搜索和互动预筛，再只为高潜候选补充详情与画像；
|
|
|
9. **失败可降级**：单一供应方失败不应让整次任务直接失去业务结果；
|
|
|
-10. **输出与数据库一致**：最终报告中的主推荐/补充推荐必须与最终持久化分池一致。
|
|
|
+10. **输出与数据库一致**：最终报告中的主推荐和淘汰候选必须与最终持久化分池一致。
|
|
|
|
|
|
## 9. 端到端流程
|
|
|
|
|
|
-### 9.1 总流程图
|
|
|
+### 9.1 当前实现主流程图
|
|
|
|
|
|
```mermaid
|
|
|
flowchart TD
|
|
|
- A["读取业务日 S/A 需求"] --> B["聚合同一需求下全部参考视频与相关点"]
|
|
|
+ A["读取业务日全部 S/A 需求"] --> B["聚合同一需求下全部参考视频与相关点"]
|
|
|
B --> C{"是否已有 running / finished 运行"}
|
|
|
C -->|"是且非强制重跑"| C1["跳过并记录原因"]
|
|
|
C -->|"否或强制重跑"| D["预创建 video_discovery_run"]
|
|
|
@@ -277,27 +319,25 @@ flowchart TD
|
|
|
F --> G["内部搜索 / TikHub 搜索"]
|
|
|
G --> H["保存搜索页并按 aweme_id 幂等并入候选"]
|
|
|
H --> I["候选状态 pending_evaluation"]
|
|
|
- I --> J["按相关性、分享规模/效率、补充潜力廉价预筛"]
|
|
|
- J --> K["批量拉取详情，默认最多 8 条"]
|
|
|
+ I --> J["按相关性、分享规模/效率、主推荐潜力廉价预筛"]
|
|
|
+ J --> K["批量拉取详情，每批最多 8 条"]
|
|
|
K --> L["批量获取视频点赞画像 + 作者粉丝画像"]
|
|
|
L --> M["标准化年龄桶并识别一致、冲突或缺失"]
|
|
|
- M --> N["对最可能改变决策的候选做视频内容解析，默认最多 3 条"]
|
|
|
+ M --> N["基于标题、描述、话题、详情和画像形成内容判断"]
|
|
|
N --> O["计算 R / E / S / V，形成证据理由与置信度"]
|
|
|
O --> P{"分池判断"}
|
|
|
P -->|"三维共同成立"| P1["primary"]
|
|
|
- P -->|"E/S 双强但 R 弱"| P2["backup"]
|
|
|
- P -->|"不满足保留条件"| P3["rejected"]
|
|
|
+ P -->|"任一维不成立"| P2["rejected"]
|
|
|
P1 --> Q["保存候选证据与分池"]
|
|
|
P2 --> Q
|
|
|
- P3 --> Q
|
|
|
Q --> R{"是否仍有高信息价值前沿"}
|
|
|
R -->|"翻页"| G
|
|
|
R -->|"标签扩展"| G
|
|
|
R -->|"作者扩展"| G
|
|
|
R -->|"没有"| S["保存 finished 与停止原因"]
|
|
|
S --> T["查询最终数据库状态"]
|
|
|
- T --> U["输出主推荐、补充推荐、淘汰候选、搜索树和缺失数据"]
|
|
|
- U --> V["按最终报告再次同步主/补充分池"]
|
|
|
+ T --> U["输出主推荐、淘汰候选、搜索树和缺失数据"]
|
|
|
+ U --> V["按最终报告再次同步 primary/rejected（当前为尽力而为）"]
|
|
|
```
|
|
|
|
|
|
### 9.2 阶段说明
|
|
|
@@ -318,6 +358,13 @@ flowchart TD
|
|
|
4. 预创建 `video_discovery_run`；
|
|
|
5. Agent 第一项动作必须复用系统给定 `run_id`。
|
|
|
|
|
|
+当前限制：
|
|
|
+
|
|
|
+- `running` 与 `finished` 都会被默认跳过，缺少运行租约和心跳，异常遗留的
|
|
|
+ `running` 记录可能长期阻塞重试；
|
|
|
+- `--force` 复用原 `run_id` 并重置运行状态，但不会先创建新的执行代次，也不会清空
|
|
|
+ 旧搜索页和旧候选，存在新旧证据混合的风险。
|
|
|
+
|
|
|
#### 阶段 3：意图理解与根搜索
|
|
|
|
|
|
1. 综合 `demand_word`、全部参考视频和全部相关点；
|
|
|
@@ -340,7 +387,7 @@ flowchart TD
|
|
|
1. 所有来源统一为 `search_results`；
|
|
|
2. 以 `aweme_id` 做跨词、跨页、跨供应方幂等合并；
|
|
|
3. 新候选进入 `pending_evaluation`；
|
|
|
-4. 先根据标题相关性、互动量和补充潜力预筛；
|
|
|
+4. 先根据标题相关性、互动量和主推荐潜力预筛；
|
|
|
5. 默认最多 8 条进入详情和双画像阶段。
|
|
|
|
|
|
#### 阶段 6：证据补全
|
|
|
@@ -350,15 +397,16 @@ flowchart TD
|
|
|
3. 批量画像自动输出标准化年龄结果；
|
|
|
4. 内容画像缺失时，作者画像只能作为账号先验；
|
|
|
5. 画像冲突、缺失和失败必须原样保存；
|
|
|
-6. 默认最多 3 条调用视频内容解析；
|
|
|
-7. 内容解析提示必须包含本次需求和相关点，并区分明确呈现与模型推断。
|
|
|
+6. 当前仅使用标题、描述、话题、正文等文本字段理解内容；
|
|
|
+7. 当前不得把未观看的视频画面、语音或字幕写成已经核验的事实；
|
|
|
+8. `qwen_video_analyze` 即使保留代码也不属于当前能力，流程不得调用。
|
|
|
|
|
|
#### 阶段 7：评分与分池
|
|
|
|
|
|
1. 独立形成 `R / E / S`；
|
|
|
2. 计算 `V` 并给出置信度；
|
|
|
3. 输出每一维的正证、反证和限制；
|
|
|
-4. 分为 `primary / backup / rejected`；
|
|
|
+4. 最终只分为 `primary / rejected`；
|
|
|
5. 对新增或证据变化的候选重新保存；
|
|
|
6. 保留数量不足 5 条时，优先继续高价值搜索前沿。
|
|
|
|
|
|
@@ -368,7 +416,10 @@ flowchart TD
|
|
|
2. 保存停止原因；
|
|
|
3. 查询最终状态，确保搜索与候选完整；
|
|
|
4. 输出最终报告；
|
|
|
-5. 运行结束后，从最终报告的主推荐和补充推荐段提取 `aweme_id`，再次同步数据库分池。
|
|
|
+5. 运行结束后，从最终报告的主推荐和淘汰候选段提取 `aweme_id`，再次同步数据库分池。
|
|
|
+
|
|
|
+第 5 步当前不是事务性提交：同步超时或异常只记录日志，调用方仍会取得 Agent 结果；
|
|
|
+目标态必须改为可校验、可重试、可原子提交的最终化流程。
|
|
|
|
|
|
## 10. 状态模型
|
|
|
|
|
|
@@ -388,15 +439,14 @@ running ──正常完成──> finished
|
|
|
搜索召回
|
|
|
↓
|
|
|
pending_evaluation
|
|
|
- ↓ 详情、画像、内容、评分
|
|
|
+ ↓ 详情、画像、文本证据、评分
|
|
|
├── primary
|
|
|
- ├── backup
|
|
|
└── rejected
|
|
|
```
|
|
|
|
|
|
- `pending_evaluation` 不能直接作为最终推荐；
|
|
|
- 候选补充新证据后允许重新评估和改变分池；
|
|
|
-- 最终报告中的主推荐与补充推荐对数据库对应分池具有同步作用。
|
|
|
+- 最终报告中的主推荐与淘汰候选对数据库对应分池具有同步作用。
|
|
|
|
|
|
### 10.3 搜索图
|
|
|
|
|
|
@@ -462,7 +512,7 @@ pending_evaluation
|
|
|
- 正式保留候选必须尝试核验详情；
|
|
|
- 单次详情工具最多处理 8 条；
|
|
|
- 部分视频失败时必须返回成功项与失败项，不因单项失败丢弃整批；
|
|
|
-- 详情应尽量提供页面链接、播放地址、作者、话题和互动数据。
|
|
|
+- 详情应尽量提供页面链接、作者、话题、文本和互动数据；播放地址不用于视频理解。
|
|
|
|
|
|
### FR-08 双侧年龄画像
|
|
|
|
|
|
@@ -474,13 +524,16 @@ pending_evaluation
|
|
|
- 仅有作者画像时，`E` 置信度必须受限；
|
|
|
- 双侧冲突时必须明确标注并降低置信度。
|
|
|
|
|
|
-### FR-09 视频内容核验
|
|
|
+### FR-09 内容核验
|
|
|
+
|
|
|
+当前版本要求：
|
|
|
|
|
|
-- 有可用播放地址且内容核验会影响决策时，应调用视频解析；
|
|
|
-- 默认最多解析 3 条最有信息价值的候选；
|
|
|
-- 解析提示必须包含本次需求与相关点；
|
|
|
-- 内容解析不能代替年龄画像；
|
|
|
-- 超长视频默认截断到 180 秒，截断失败或依赖缺失必须返回明确错误。
|
|
|
+- 相关性与分享动机依据搜索描述、详情标题、正文、话题标签和互动数据判断；
|
|
|
+- 必须区分接口返回的事实、由文本计算出的指标和模型推断；
|
|
|
+- 当前不使用视频画面、语音、字幕或多模态解析，不得声称已经看见某个画面、听见某句
|
|
|
+ 话或核验完整剧情；
|
|
|
+- 文本信息不足以支持高置信相关性时，应降低 `R` 或置信度，而不是用常识补全；
|
|
|
+- 持久化契约不保存视频播放地址、内容分析结论或视频理解核验标记。
|
|
|
|
|
|
### FR-10 评分与解释
|
|
|
|
|
|
@@ -490,13 +543,13 @@ pending_evaluation
|
|
|
- 分数缺失时不得伪造；
|
|
|
- 缺失证据不应自动变成零分。
|
|
|
|
|
|
-### FR-11 双池分流
|
|
|
+### FR-11 最终分流
|
|
|
|
|
|
- `primary`：`R / E / S` 三个命题均成立；
|
|
|
-- `backup`：不满足主推荐，但 `E / S` 同时强，并明确相关性限制；
|
|
|
-- `rejected`：不满足任一保留池，或强反证足以否定；
|
|
|
-- `backup` 不得在报告中伪装成主推荐；
|
|
|
-- 低相关但高传播候选必须在淘汰前先评估其补充潜力。
|
|
|
+- `rejected`：未满足 `primary` 的任一候选；
|
|
|
+- `pending_evaluation` 仅用于搜索后的过程状态，`finished` 时不得残留；
|
|
|
+- 不存在 `backup`、补充推荐、人工备选或其他中间等级；
|
|
|
+- 低相关但高传播、偏老年的候选仍必须进入 `rejected`。
|
|
|
|
|
|
### FR-12 探索与停止
|
|
|
|
|
|
@@ -509,7 +562,7 @@ pending_evaluation
|
|
|
### FR-13 持久化与恢复
|
|
|
|
|
|
- 必须保存运行、搜索页和候选三个粒度的数据；
|
|
|
-- 候选记录必须包含详情、互动、双侧画像、标准化结果、内容分析、评分、理由和分池；
|
|
|
+- 候选记录必须包含详情、互动、双侧画像、标准化结果、文本证据、评分、理由和分池；
|
|
|
- 查询状态必须可恢复搜索树与候选池；
|
|
|
- 数据库不可用时只尝试一次初始化写入，之后以内存结构继续业务流程；
|
|
|
- 降级结果必须醒目标注“未持久化”及原因。
|
|
|
@@ -520,12 +573,11 @@ pending_evaluation
|
|
|
|
|
|
1. 一句话需求意图理解；
|
|
|
2. 主推荐；
|
|
|
-3. 补充推荐；
|
|
|
-4. 最有竞争力但被淘汰的候选；
|
|
|
-5. 搜索树；
|
|
|
-6. 缺失数据、画像冲突、未继续前沿和接口失败。
|
|
|
+3. 淘汰候选及淘汰理由；
|
|
|
+4. 搜索树；
|
|
|
+5. 缺失数据、画像冲突、未继续前沿和接口失败。
|
|
|
|
|
|
-每条主推荐或补充推荐必须包含：
|
|
|
+每条主推荐必须包含：
|
|
|
|
|
|
- 排名、标题、作者、抖音页面链接、`aweme_id`；
|
|
|
- 命中的需求点与相关性证据；
|
|
|
@@ -541,8 +593,8 @@ pending_evaluation
|
|
|
### FR-15 最终一致性
|
|
|
|
|
|
- 报告中主推荐的 ID 必须属于数据库 `primary`；
|
|
|
-- 报告中补充推荐的 ID 必须属于数据库 `backup`；
|
|
|
-- 淘汰候选不能出现在补充推荐段；
|
|
|
+- 报告中淘汰候选的 ID 必须属于数据库 `rejected`；
|
|
|
+- `finished` 运行不得包含 `backup` 或 `pending_evaluation`；
|
|
|
- 最终文字分池与数据库不一致时，系统必须阻止完成或产生显式错误；
|
|
|
- 最终分池同步必须可观测，失败不能静默吞掉。
|
|
|
|
|
|
@@ -558,7 +610,6 @@ pending_evaluation
|
|
|
| `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` | 保存证据、评分和分池 | 原样保存，不重算、不改池 |
|
|
|
@@ -566,6 +617,9 @@ pending_evaluation
|
|
|
|
|
|
当前共享基础工具还会注册 `load_skill`，但它不是本 Agent 的核心业务链路。
|
|
|
|
|
|
+`qwen_video_analyze` 的历史实现文件即使仍在仓库中，也未注册到 `find_agent`，没有
|
|
|
+`video_analysis` 工具预算，当前 Prompt、状态恢复、审计和测试均不得依赖它。
|
|
|
+
|
|
|
## 13. 数据模型
|
|
|
|
|
|
### 13.1 `video_discovery_run`
|
|
|
@@ -576,7 +630,7 @@ pending_evaluation
|
|
|
- `demand_word`、参考视频和相关点输入快照；
|
|
|
- Agent 的最终意图解释；
|
|
|
- `running / finished / failed` 状态；
|
|
|
-- 搜索页数、主推荐数、补充推荐数；
|
|
|
+- 搜索页数和主推荐数；
|
|
|
- 停止原因或失败原因。
|
|
|
|
|
|
### 13.2 `video_discovery_search`
|
|
|
@@ -600,10 +654,12 @@ pending_evaluation
|
|
|
- 来源词、来源搜索和标签；
|
|
|
- 互动数据；
|
|
|
- 视频点赞年龄证据、作者粉丝年龄证据和标准化结果；
|
|
|
-- 详情、画像、年龄标准化和内容解析是否已执行；
|
|
|
-- 内容分析和扩展价值标签；
|
|
|
+- 详情、画像、年龄标准化是否已执行；
|
|
|
+- 扩展价值标签；
|
|
|
- `R / E / S / V`、置信度和各维理由；
|
|
|
-- `primary / backup / rejected / pending_evaluation` 分池。
|
|
|
+- 最终 `primary / rejected` 分池，以及过程状态 `pending_evaluation`。
|
|
|
+
|
|
|
+当前模型不包含视频播放地址、内容分析结论或视频理解核验标记。
|
|
|
|
|
|
## 14. 成本与运行预算
|
|
|
|
|
|
@@ -612,23 +668,26 @@ pending_evaluation
|
|
|
| 项目 | 默认约束 |
|
|
|
|---|---|
|
|
|
| Agent 最大迭代 | 60 |
|
|
|
+| 单需求核心运行超时 | 1800 秒（环境变量可配） |
|
|
|
+| 日志生成/OSS 发布等待 | 最多 120 秒，当前失败后继续返回 |
|
|
|
| 搜索类工具调用 | 最多 10 次 |
|
|
|
| 详情工具调用 | 最多 2 次，每次最多 8 条 |
|
|
|
| 画像工具调用 | 最多 3 次，每批最多 8 条 |
|
|
|
-| 视频内容解析 | 最多 3 次 |
|
|
|
| 候选评估保存 | 最多 6 次 |
|
|
|
| 状态查询 | 最多 8 次，且无状态变化时禁止无意义重复 |
|
|
|
| 根搜索词 | 默认 2~3 个 |
|
|
|
| 生产性首页翻页 | 默认继续 1 页 |
|
|
|
| 正式补证候选 | 默认最多 8 条 |
|
|
|
-| 视频解析候选 | 默认最多 3 条 |
|
|
|
+| 每日批处理并发 | 固定 1；`workers` 参数当前被忽略 |
|
|
|
+| 每日停止上限 | `primary` 按 `aweme_id` 去重达到 200 条 |
|
|
|
|
|
|
### 14.2 预算原则
|
|
|
|
|
|
- 预算是防止无界探索的上限，不是必须耗尽的配额；
|
|
|
- 优先使用批量详情和批量画像；
|
|
|
-- 只有可能改变分池或置信度时才做视频解析；
|
|
|
-- 外部接口存在串行限流，搜索深度必须服从信息价值。
|
|
|
+- 外部接口存在 1 秒或约 10.1 秒的进程内串行限流，搜索深度必须服从信息价值；
|
|
|
+- 单需求最长 30 分钟且每日单线程执行，当前无法据此承诺每日全量 S/A 都能在固定
|
|
|
+ 时间窗内完成，P0 后必须先测基线再制定吞吐 SLA。
|
|
|
|
|
|
## 15. 异常与降级策略
|
|
|
|
|
|
@@ -640,11 +699,12 @@ pending_evaluation
|
|
|
| 详情部分失败 | 保留成功项和逐条失败原因 |
|
|
|
| 内容画像缺失 | 尝试作者画像，标记 `account_only`，降低置信度 |
|
|
|
| 双侧画像冲突 | 优先视频画像，显式标注冲突 |
|
|
|
-| 视频无播放地址 | 不强制内容解析，保存缺失状态 |
|
|
|
-| 视频解析失败 | 保留原始错误，不用模型常识补写内容 |
|
|
|
+| 文本字段不足 | 降低相关性置信度，不用模型常识补写视频内容 |
|
|
|
| 数据库不可用 | 一次失败后转内存流程，最终披露未持久化 |
|
|
|
| Agent 或模型异常 | 运行标记 `failed` 并保存异常原因 |
|
|
|
-| 最终分池同步失败 | 记录错误并将任务视为未完整完成 |
|
|
|
+| 运行超时 | 关闭异步客户端并将调度运行标记为 `failed` |
|
|
|
+| 发布或最终分池同步失败 | 当前仅记录日志并返回；目标态必须将任务标记为未完整完成 |
|
|
|
+| 遗留 `running` 运行 | 当前默认跳过；目标态通过租约过期与恢复机制接管 |
|
|
|
|
|
|
## 16. 非功能需求
|
|
|
|
|
|
@@ -678,12 +738,21 @@ pending_evaluation
|
|
|
|
|
|
- API Key、数据库密码和 OSS 密钥只能从环境配置读取；
|
|
|
- 日志和报告不得输出完整密钥；
|
|
|
-- 长视频临时文件必须在处理后清理；
|
|
|
- 公网播放地址和 OSS 地址应遵守数据授权与访问控制要求。
|
|
|
|
|
|
## 17. 成功指标
|
|
|
|
|
|
-### 17.1 业务指标
|
|
|
+### 17.1 北极星指标
|
|
|
+
|
|
|
+**需求级有效供给率**：
|
|
|
+
|
|
|
+`至少产生 1 条经人工抽检可直接进入后续供给链路的 primary 视频的 finished 需求数
|
|
|
+/ 完成抽检的 finished 需求数`
|
|
|
+
|
|
|
+该指标同时约束“是否找到”“是否相关”“是否偏老年”“是否值得传播”，比单纯统计每次
|
|
|
+保留 5 条更能代表产品价值。
|
|
|
+
|
|
|
+### 17.2 业务指标
|
|
|
|
|
|
| 指标 | 定义 |
|
|
|
|---|---|
|
|
|
@@ -691,22 +760,53 @@ pending_evaluation
|
|
|
| 主推荐需求准确率 | 抽检中真正承接需求的主推荐占比 |
|
|
|
| 老年证据有效率 | 保留候选中具有有效视频或作者年龄画像的占比 |
|
|
|
| 分享证据完整率 | 保留候选中同时具有分享规模/效率和内容动机说明的占比 |
|
|
|
-| 有效保留数 | 每次运行 `primary + backup` 数量及分布 |
|
|
|
-| 补充池有效率 | 补充候选经业务抽检确认值得保留的占比 |
|
|
|
+| 有效保留数 | 每次运行 `primary` 数量及分布 |
|
|
|
| 推荐多样性 | 保留结果覆盖的不同需求点和分享动机数量 |
|
|
|
|
|
|
-### 17.2 流程指标
|
|
|
+### 17.3 流程指标
|
|
|
|
|
|
| 指标 | 定义 |
|
|
|
|---|---|
|
|
|
| 搜索页持久化率 | 已调用搜索页中成功保存的占比 |
|
|
|
-| 候选证据完整率 | 保留候选完成详情、双画像尝试、年龄标准化和必要内容核验的占比 |
|
|
|
+| 候选证据完整率 | 保留候选完成详情、双画像尝试、年龄标准化和必要文本核验的占比 |
|
|
|
| 最终分池一致率 | 最终报告与数据库分池完全一致的运行占比 |
|
|
|
| 重复候选率 | 去重前重复候选占比，用于观察搜索冗余 |
|
|
|
| 搜索新增效率 | 每个搜索页新增有效候选数 |
|
|
|
| 降级成功率 | 单供应方失败后仍成功完成任务的占比 |
|
|
|
| 平均运行时长 | 从运行创建到最终完成的耗时 |
|
|
|
-| 单任务工具成本 | 各类搜索、详情、画像和解析调用次数 |
|
|
|
+| 单任务工具成本 | 各类搜索、详情、画像、保存和查询调用次数 |
|
|
|
+
|
|
|
+### 17.4 P0 上线门槛
|
|
|
+
|
|
|
+下列是目标值，不代表当前已达到：
|
|
|
+
|
|
|
+| 指标 | P0 上线门槛 | 统计要求 |
|
|
|
+|---|---:|---|
|
|
|
+| 定向与回归测试通过率 | 100% | 禁止保留与当前产品契约冲突的旧断言 |
|
|
|
+| 最终分池一致率 | 100% | 报告、候选表、运行计数三方一致 |
|
|
|
+| 搜索页持久化率 | 100% | 成功、空页、失败页均计入 |
|
|
|
+| `finished` 运行待评估清零率 | 100% | 不允许 `pending_evaluation` 遗留 |
|
|
|
+| 保留候选详情尝试率 | 100% | 成功或明确失败均视为已尝试 |
|
|
|
+| 保留候选双侧画像尝试率 | 100% | 缺少作者 ID 时必须有明确跳过原因 |
|
|
|
+| 年龄标准化完成率 | 100% | 所有保留候选必须有标准化状态 |
|
|
|
+| 提前结束拦截率 | 100% | 构造不完整流程时守卫必须拒绝完成 |
|
|
|
+| 超时运行正确失败率 | 100% | 运行状态为 `failed`，异步资源被释放 |
|
|
|
+
|
|
|
+### 17.5 P1 质量目标
|
|
|
+
|
|
|
+先以不少于 100 个需求、每个需求至少抽检 Top 5 的标注集建立基线，再冻结目标。建议
|
|
|
+首版门槛如下：
|
|
|
+
|
|
|
+| 指标 | 建议目标 |
|
|
|
+|---|---:|
|
|
|
+| 主推荐需求相关准确率 | ≥ 85% |
|
|
|
+| 主推荐三类证据完整率 | ≥ 95% |
|
|
|
+| Top 5 至少 1 条业务可用率 | ≥ 90% |
|
|
|
+| 相同内容重复占位率 | ≤ 10% |
|
|
|
+| 单需求超时率 | ≤ 2% |
|
|
|
+
|
|
|
+吞吐 SLA 需要在 P0 稳定后实测确定。当前“单任务最多 1800 秒、每日单线程、最多 200
|
|
|
+条通过视频”的组合只是一组保护边界，不等于已经具备可承诺的日批完成时间。
|
|
|
|
|
|
## 18. 验收标准
|
|
|
|
|
|
@@ -718,9 +818,9 @@ pending_evaluation
|
|
|
2. 创建或复用唯一 `run_id`；
|
|
|
3. 执行并保存实际搜索页；
|
|
|
4. 所有召回候选按 `aweme_id` 幂等合并；
|
|
|
-5. 最终保留候选具有足够的详情、画像和内容证据；
|
|
|
+5. 最终保留候选具有足够的详情、画像和文本内容证据；
|
|
|
6. 所有年龄画像已经标准化；
|
|
|
-7. 候选被明确分为主推荐、补充推荐、淘汰或待评估；
|
|
|
+7. 候选被明确分池，且 `finished` 运行不遗留 `pending_evaluation`；
|
|
|
8. 最终运行状态和停止原因已保存；
|
|
|
9. 报告满足输出契约；
|
|
|
10. 报告与数据库分池完全一致；
|
|
|
@@ -734,7 +834,7 @@ pending_evaluation
|
|
|
- 用题材或画面中出现老人代替受众年龄证据；
|
|
|
- 将点赞用户画像声称为分享用户画像；
|
|
|
- 把低相关高分享视频放入主推荐；
|
|
|
-- 将符合补充池条件的候选直接丢弃且无理由；
|
|
|
+- 将未满足 `R / E / S` 联合条件的候选放入主推荐；
|
|
|
- `pending_evaluation` 直接出现在推荐结果；
|
|
|
- 新搜索或新证据产生后未重新保存受影响候选；
|
|
|
- 报告推荐 ID 与数据库分池不一致；
|
|
|
@@ -744,34 +844,78 @@ pending_evaluation
|
|
|
|
|
|
## 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 尚未实现或仍有关键证据缺口
|
|
|
+### 19.1 能力成熟度
|
|
|
+
|
|
|
+| 能力域 | 当前等级 | 现状判断 |
|
|
|
+|---|---|---|
|
|
|
+| 需求输入装配 | 可用 | 能按需求聚合全部参考视频和有效点位 |
|
|
|
+| 多源召回 | 可用 | 内部搜索、TikHub、作者作品均已接入 |
|
|
|
+| 候选去重与搜索记忆 | 可用 | 搜索页和候选具备数据库幂等键 |
|
|
|
+| 详情与年龄证据 | 可用但有缺口 | 支持详情、双侧画像和年龄桶标准化；内容画像可能缺失 |
|
|
|
+| 内容理解 | 文本证据 | 当前明确只基于文本、互动和画像，不使用视频理解 |
|
|
|
+| 评分与分池 | 部分可用 | 字段和规则齐全，但主要依赖模型遵守长提示词 |
|
|
|
+| 完成审计 | 未上线 | 审计与守卫代码存在，但没有接入当前 Agent |
|
|
|
+| 最终一致性 | 高风险 | 文字反向同步为尽力而为，不是原子提交 |
|
|
|
+| 日批调度 | 可用但低吞吐 | 固定单线程，达到 200 条保留视频后停止 |
|
|
|
+| 运行恢复 | 部分可用 | 可查状态，但缺少租约、执行代次和自动续跑 |
|
|
|
+| 下游供给衔接 | 已接入 | 仅 `primary` 进入 AIGC 计划分配 |
|
|
|
+| 监控与质量评估 | 不完整 | 有日志和基础计数，没有正式 SLA、质量集和仪表盘 |
|
|
|
+
|
|
|
+### 19.2 已实现
|
|
|
+
|
|
|
+- 按业务日读取具备拓展点位的 S/A 需求，聚合同一需求的全部参考视频与点位；
|
|
|
+- Agent 运行前按 `(biz_dt, demand_grade_id)` 预创建唯一运行记录；
|
|
|
+- 内部关键词、TikHub、作者作品三类召回与统一候选结构；
|
|
|
+- 内部搜索约 10.1 秒、TikHub 1 秒、作者/详情约 10.1 秒的进程内限流；
|
|
|
+- 搜索页、分页状态、父子搜索关系和失败原因落库；
|
|
|
+- 以 `(run_id, aweme_id)` 做跨词、跨页、跨来源候选去重；
|
|
|
+- 单次最多 8 条的批量详情与批量双侧画像；
|
|
|
+- 对 `50- / 50+ / 50岁以上 / 41-50` 等年龄桶做确定性标准化；
|
|
|
+- `R / E / S / V`、各维理由、置信度、分池和停止原因字段；
|
|
|
+- `video_discovery_run / search / candidate` 三张表和状态查询；
|
|
|
+- 单需求 60 轮、搜索/详情/画像/保存/查询工具预算；
|
|
|
+- 单需求核心流程 1800 秒超时、异步客户端清理和线程事件循环清理；
|
|
|
+- 日批单线程执行、跳过已有 `running / finished`、支持 `--force`；
|
|
|
+- 当日主推荐去重视频达到 200 条时提前结束；
|
|
|
+- Agent 日志/可视化发布设置 120 秒等待边界；
|
|
|
+- 最终报告中主推荐/淘汰候选 ID 的提取与数据库回写；
|
|
|
+- 下游只读取 `primary` 并创建 AIGC 爬取、生产和发布计划关联。
|
|
|
+
|
|
|
+### 19.3 部分实现或暂停能力
|
|
|
+
|
|
|
+- 搜索图扩展、信息价值停止和最终分流主要依赖模型，不是确定性编排；
|
|
|
+- 数据库不可用的内存降级仅由提示词约束，没有统一结构化状态容器；
|
|
|
+- `find_agent_completion_guard` 已实现但配置为 `completion_guard=None`；
|
|
|
+- `audit_video_discovery_process` 与 `audit_video_discovery_run` 已实现但未注册；
|
|
|
+- 视频理解历史实现和兼容字段仍保留，但不注册、不进入工具输入、状态恢复、审计和测试；
|
|
|
+- 最终报告反向同步失败只写日志，不改变主调用结果；
|
|
|
+- 最终同步只更新报告出现的 ID，不会原子清理被省略的旧候选；
|
|
|
+- `run_find_agent(..., model=...)` 和 `create_find_agent(..., model=...)` 暴露了模型参数，
|
|
|
+ 但工厂当前固定使用 `google/gemini-3-flash-preview`，传参不会生效；
|
|
|
+- `--force` 会复用原 `run_id`，旧搜索和候选不会自动隔离；
|
|
|
+- 批任务文档意图是“S 优先于 A、同等级按分数”，当前排序键实际先比较分数再比较
|
|
|
+ 等级，契约与实现需要统一。
|
|
|
+
|
|
|
+### 19.4 测试与验证基线
|
|
|
+
|
|
|
+2026-07-28 对当前分支执行：
|
|
|
+
|
|
|
+```text
|
|
|
+.venv/bin/pytest -q \
|
|
|
+ tests/test_find_agent.py \
|
|
|
+ tests/supply_infra/scheduler/test_discover_videos_from_demands.py
|
|
|
+```
|
|
|
+
|
|
|
+当前契约测试 `tests/test_find_agent.py` 为 `14 passed`。视频理解注册/预算的旧断言已
|
|
|
+删除，并新增“审计不要求视频理解”“最终只接受 primary/rejected”“最终文字按
|
|
|
+primary/rejected 解析”的测试。
|
|
|
+
|
|
|
+调度测试为 `1 passed, 1 failed`。剩余失败是既有测试夹具使用普通 `object()` 代替
|
|
|
+`FindDemandContext`，日志读取 `demand_grade_id / demand_name` 时失败；它与本次两项
|
|
|
+确定性修改无关，按范围约束未顺带修复。`VALIDATION.md` 的真实接口与数据库验证日期为
|
|
|
+2026-07-23，不能替代当前版本的完整 Agent 干跑。
|
|
|
+
|
|
|
+### 19.5 尚未实现或仍有关键证据缺口
|
|
|
|
|
|
- 实际转发用户年龄画像；
|
|
|
- 各年龄段曝光、完播率和观看时长；
|
|
|
@@ -780,63 +924,189 @@ pending_evaluation
|
|
|
- 标准话题热度与稳定批量话题服务；
|
|
|
- 评论中的转发动机结构化信号；
|
|
|
- 推荐内容上线后的真实表现回流与评分校准；
|
|
|
-- 运行时确定性完成守卫；
|
|
|
-- 正式的端到端 SLA、告警和仪表盘。
|
|
|
+- 运行时确定性完成守卫和事务性最终化；
|
|
|
+- 运行租约、心跳、自动恢复和执行代次；
|
|
|
+- 正式的端到端 SLA、告警、质量数据集和仪表盘。
|
|
|
|
|
|
## 20. 当前主要风险
|
|
|
|
|
|
-| 风险 | 影响 | 产品要求 |
|
|
|
+| 优先级 | 风险 | 触发与影响 | 产品要求 |
|
|
|
+|---|---|---|---|
|
|
|
+| P0 | 完成守卫关闭 | 模型可在未评估、未审计或未查最终状态时结束 | 恢复确定性守卫，结束前强制状态机校验 |
|
|
|
+| P0 | 最终文字可创建无证据候选 | 当前回写会对报告中的新 ID 补建候选，模型误写 ID 可能直接进入通过池 | 只允许对本次已召回、已评估候选做最终化 |
|
|
|
+| P0 | 最终分池非原子、增量同步 | 同步异常只记日志；报告省略的旧候选仍可能留在通过池 | 使用事务一次性校验、替换分池并完成运行 |
|
|
|
+| P0 | 遗留 `running` 永久被跳过 | 进程异常后任务没有租约过期机制 | 增加 heartbeat、lease_expires_at 和可恢复状态 |
|
|
|
+| P0 | 强制重跑污染旧状态 | `--force` 复用原运行和子记录，新旧证据混合 | 引入 attempt_id 或创建新 run，并保留父子关系 |
|
|
|
+| P0 | 回归测试漂移 | 产品变更后测试仍验证旧能力，无法提供发布信心 | 先冻结 v1.1 契约，再恢复定向与全量测试全绿 |
|
|
|
+| P1 | 模型参数无效 | 调用方以为可以切模型，实际始终使用固定预览模型 | 尊重显式参数并记录 model/prompt/strategy 版本 |
|
|
|
+| P1 | 排序契约不一致 | S/A 优先级与代码排序键不一致，可能改变日批处理顺序 | 用测试固定业务优先级并修正排序 |
|
|
|
+| P1 | 单线程与串行限流 | 全量 S/A 可能无法在日批窗口内完成 | 建立耗时基线，批量化接口后再逐步增加并发 |
|
|
|
+| P1 | 点赞画像不等于转发画像 | “老年人会分享”只能是概率推断 | 使用谨慎措辞，并优先建设转发画像 |
|
|
|
+| P1 | 内容画像经常缺失 | `E` 可能过度依赖作者先验 | 明确 `account_only`、样本量与置信度上限 |
|
|
|
+| P1 | 文本内容证据有限 | 标题党、口播和画面信息可能被误判 | 明确降低置信度，不引入未授权的视频理解 |
|
|
|
+| P1 | 原始分享数不可跨题材比较 | `S` 排序偏向高曝光题材 | 建设同主题、同时间窗传播基线 |
|
|
|
+| P1 | 硬编码 HTTP 外部地址 | 迁移、证书、权限和环境隔离困难 | 配置化服务地址，生产优先使用受控 HTTPS |
|
|
|
+| P2 | 模型行为依赖长提示词 | 规则迭代难测、易遗漏 | 将流程硬约束下沉，LLM 只负责语义与解释 |
|
|
|
+
|
|
|
+## 21. 需要优化点与迭代优先级
|
|
|
+
|
|
|
+### 21.1 P0：稳定完成与数据一致性
|
|
|
+
|
|
|
+建议周期：1~2 个迭代。P0 完成前不建议扩大日批并发。
|
|
|
+
|
|
|
+1. **恢复确定性完成控制**
|
|
|
+ - 注册 `audit_video_discovery_run`；
|
|
|
+ - 启用并简化 `find_agent_completion_guard`；
|
|
|
+ - 强制顺序为：最后搜索 → 证据保存 → 候选评估 → 审计 → 最终状态查询 → 报告。
|
|
|
+2. **实现事务性最终化**
|
|
|
+ - 新增单一 `finalize_video_discovery_run` 服务；
|
|
|
+ - 只接受本次运行已召回、已评估的候选 ID；
|
|
|
+ - 原子对齐 `primary / rejected`、运行计数、`finished` 和最终摘要；
|
|
|
+ - 禁止从最终文字补建陌生候选；
|
|
|
+ - 同步失败必须对调用方可见并可重试。
|
|
|
+3. **修正运行生命周期**
|
|
|
+ - 增加执行代次、心跳、租约过期时间和失败类型；
|
|
|
+ - 遗留 `running` 可安全接管；
|
|
|
+ - `--force` 创建新 attempt 或显式清理当前 attempt，禁止静默混入旧证据；
|
|
|
+ - 区分 Agent 核心成功、日志发布成功和最终化成功。
|
|
|
+4. **恢复测试门禁**
|
|
|
+ - 增加报告幻觉 ID、旧候选残留、审计不通过、超时、同步失败、强制重跑、
|
|
|
+ stale-running 恢复等负向测试；
|
|
|
+ - 用当前模型与真实依赖完成至少 3 个不同需求的端到端干跑；
|
|
|
+ - 发布门禁要求定向测试和相关全量回归 100% 通过。
|
|
|
+5. **修复配置与优先级契约**
|
|
|
+ - 使 `model` 参数真正生效并记录实际模型版本；
|
|
|
+ - 统一“S 优先还是 score 优先”的业务规则并补测试；
|
|
|
+ - 启动前检查数据库表、TikHub Key、外部服务地址和必要日志配置。
|
|
|
+
|
|
|
+### 21.2 P1：提升质量、效率与可观测性
|
|
|
+
|
|
|
+建议周期：P0 后 2~4 个迭代。
|
|
|
+
|
|
|
+1. **结构化决策**
|
|
|
+ - LLM 输出固定 JSON Schema，程序计算 `V` 并校验 `R/E/S` 范围；
|
|
|
+ - 将搜索计划、候选预筛、证据补全和分池拆成可测试节点；
|
|
|
+ - 为 Prompt、评分策略和模型增加版本号。
|
|
|
+2. **质量评估体系**
|
|
|
+ - 建立不少于 100 个需求的人工标注集；
|
|
|
+ - 分别标注需求相关、老年受众证据、分享动机和最终可用性；
|
|
|
+ - 建立 primary/rejected 混淆矩阵和按题材切片指标。
|
|
|
+3. **搜索与补证效率**
|
|
|
+ - 建设 `batch_douyin_search` 与服务端限流；
|
|
|
+ - 对详情、作者画像和视频画像做短期缓存；
|
|
|
+ - 使用新增有效候选/耗时作为搜索前沿优先级；
|
|
|
+ - 在数据库连接、供应方配额和限流隔离通过压测后逐步恢复并发。
|
|
|
+4. **召回覆盖**
|
|
|
+ - 接入相似视频、稳定话题服务和话题热度；
|
|
|
+ - 将作者扩展、标签扩展、翻页的触发条件改为结构化策略；
|
|
|
+ - 用不同根搜索的边际新增率控制停止。
|
|
|
+5. **可观测性**
|
|
|
+ - 提供需求级耗时瀑布、工具成功率、候选漏斗、证据缺失率和失败类型；
|
|
|
+ - 对超时、stale-running、最终化失败、零结果和单日未达吞吐目标告警；
|
|
|
+ - 展示当前运行使用的模型、Prompt、策略和数据源版本。
|
|
|
+### 21.3 P2：证据升级与业务反馈闭环
|
|
|
+
|
|
|
+建议周期：中长期。
|
|
|
+
|
|
|
+1. 接入实际转发用户年龄画像与样本量；
|
|
|
+2. 接入分年龄曝光、有效播放、完播率和观看时长；
|
|
|
+3. 建设同题材、同发布时间窗口的传播基线；
|
|
|
+4. 接入评论中的提醒、@亲友、收藏和求链接等脱敏意图信号；
|
|
|
+5. 建立需求—推荐视频—AIGC 计划—发布内容—线上 ROV/VOV 的稳定映射；
|
|
|
+6. 分析 primary/rejected 的后验表现，校准评分与置信度；
|
|
|
+7. 将校准参数、特征和阈值版本化，支持回放、灰度和回滚。
|
|
|
+
|
|
|
+## 22. 后续方向
|
|
|
+
|
|
|
+### 22.1 产品形态：从“单个大 Agent”演进为“可控发现工作流”
|
|
|
+
|
|
|
+目标架构应把确定性步骤从 Prompt 中移出：
|
|
|
+
|
|
|
+```text
|
|
|
+需求装配
|
|
|
+ → 搜索计划生成（LLM）
|
|
|
+ → 多源召回（程序）
|
|
|
+ → 候选去重与廉价预筛（程序）
|
|
|
+ → 证据补全（程序）
|
|
|
+ → 语义判断与理由生成（LLM）
|
|
|
+ → 规则校验与分池（程序 + LLM）
|
|
|
+ → 原子最终化（程序）
|
|
|
+ → 质量回流（数据）
|
|
|
+```
|
|
|
+
|
|
|
+LLM 继续负责意图理解、搜索词生成、复杂语义相关性和解释；运行身份、预算、证据完整性、
|
|
|
+状态转换、阈值校验和最终提交由程序控制。这样可以降低模型更换、Prompt 变长和供应方
|
|
|
+异常对流程正确性的影响。
|
|
|
+
|
|
|
+### 22.2 证据体系：从“代理信号”演进为“行为闭环”
|
|
|
+
|
|
|
+证据建设按以下顺序推进：
|
|
|
+
|
|
|
+1. 当前：点赞用户年龄 + 作者粉丝年龄 + 分享数/替代效率 + 文本动机；
|
|
|
+2. 下一步：真实转发用户年龄、样本量、统计周期；
|
|
|
+3. 再下一步：分年龄观看、完播、留存、收藏与评论意图；
|
|
|
+4. 最终：推荐视频进入供给链路后的真实 ROV/VOV 与内容质量回流。
|
|
|
+
|
|
|
+在直接证据补齐前，产品文案必须坚持“更可能观看和分享”，不能升级成“老年人已经在
|
|
|
+分享”的确定性结论。
|
|
|
+
|
|
|
+### 22.3 策略体系：从固定 Prompt 评分演进为版本化策略
|
|
|
+
|
|
|
+- 保留 `R/E/S` 三维可解释框架，但将计算、阈值、证据上限和冲突处理配置化；
|
|
|
+- 每次运行记录 `model_version / prompt_version / strategy_version / data_version`；
|
|
|
+- 用标注集离线评测，再对小流量需求灰度；
|
|
|
+- 所有策略变化支持回放历史 run，并比较候选召回、分池和最终使用差异；
|
|
|
+- 避免把所有新规则继续追加到系统提示词。
|
|
|
+
|
|
|
+### 22.4 平台方向：从抖音单点能力演进为供给发现服务
|
|
|
+
|
|
|
+当抖音链路稳定后，可抽象：
|
|
|
+
|
|
|
+- 统一的搜索供应方协议；
|
|
|
+- 统一的内容、作者、受众和传播证据模型；
|
|
|
+- 跨平台内容去重与相似度；
|
|
|
+- 面向不同人群或业务目标的可配置评分策略；
|
|
|
+- 为运营提供人工复核、原因筛选、重新运行和结果对比界面。
|
|
|
+
|
|
|
+扩平台不是近期 P0。只有当单平台的完成率、准确率、成本和反馈闭环达到门槛后，抽象才
|
|
|
+有稳定依据。
|
|
|
+
|
|
|
+### 22.5 里程碑
|
|
|
+
|
|
|
+| 里程碑 | 核心交付 | 退出条件 |
|
|
|
|---|---|---|
|
|
|
-| 点赞画像不等于转发画像 | “老年人会分享”只能是概率推断 | 报告必须使用谨慎措辞，并优先建设转发画像 |
|
|
|
-| 内容画像经常缺失 | `E` 过度依赖作者先验 | 明确 `account_only` 和较低置信度 |
|
|
|
-| 完成守卫暂停 | 模型可能在流程未闭合时提前结束 | P0 恢复确定性完成约束 |
|
|
|
-| 审计工具未注册 | 无法在 Agent 内主动验证流程 | P0 注册并要求结束前审计 |
|
|
|
-| 最终文字可反向改池 | 格式错误可能造成数据状态变化 | 同步前做严格校验并保证事务一致性 |
|
|
|
-| 最终分池采用增量同步 | 报告中省略的旧候选可能仍留在主/补充池 | 改为一次运行内的原子全量对齐 |
|
|
|
-| 外部接口串行限流 | 多词、多候选任务时延较高 | 更强预筛、批量接口和明确 SLA |
|
|
|
-| 原始分享数不可跨题材比较 | `S` 排序可能偏向高曝光题材 | 建设同主题传播基线 |
|
|
|
-| TikHub 为可选依赖 | 环境遗漏时搜索覆盖下降 | 配置预检、清晰降级与环境样例补全 |
|
|
|
-| 模型行为依赖长提示词 | 规则可能被遗漏 | 将硬性流程约束下沉到确定性代码 |
|
|
|
-
|
|
|
-## 21. 迭代优先级
|
|
|
-
|
|
|
-### P0：稳定完成与数据一致性
|
|
|
-
|
|
|
-1. 注册数据库审计工具；
|
|
|
-2. 恢复并完善 `find_agent_completion_guard`；
|
|
|
-3. 强制最后一次搜索、证据变更、评估、审计和状态查询满足时序要求；
|
|
|
-4. 最终报告同步前校验 ID 与分池，并以一次运行为范围原子替换最终双池；
|
|
|
-5. 同步失败时显式返回未完成，而不是只写日志；
|
|
|
-6. 为所有外部依赖增加启动前配置检查；
|
|
|
-7. 增加端到端成功、提前停止、数据库降级和分池错位验收。
|
|
|
-
|
|
|
-### P1：提升结论可靠性
|
|
|
-
|
|
|
-1. 接入实际转发用户年龄画像；
|
|
|
-2. 接入受众留存、完播率和观看时长；
|
|
|
-3. 实现多关键词批量搜索与服务端限流；
|
|
|
-4. 接入平台相似视频；
|
|
|
-5. 接入标准话题与话题热度；
|
|
|
-6. 用同题材传播基线校准分享规模和效率。
|
|
|
-
|
|
|
-### P2：建立反馈闭环
|
|
|
-
|
|
|
-1. 建立需求—推荐视频—最终使用内容的映射；
|
|
|
-2. 回收真实 ROV/VOV 与内容质量信息；
|
|
|
-3. 分析主推荐、补充推荐和淘汰候选的后验表现；
|
|
|
-4. 基于历史样本校准 `R / E / S` 与置信度；
|
|
|
-5. 将校准参数纳入版本化策略，而不是继续写入提示词。
|
|
|
-
|
|
|
-## 22. 产品完成定义
|
|
|
+| M0 契约对齐 | 不使用视频理解、仅 `primary/rejected`、测试/审计/文档统一 | 相关回归全绿 |
|
|
|
+| M1 稳定版 | 完成守卫、原子最终化、运行租约、可重试 | P0 上线门槛全部达标 |
|
|
|
+| M2 质量版 | 标注集、结构化决策、批量搜索、仪表盘 | P1 质量目标达到并稳定两周 |
|
|
|
+| M3 证据版 | 转发画像、观看质量、传播基线 | 老年与分享结论具备更直接证据 |
|
|
|
+| M4 闭环版 | AIGC/发布表现回流、策略校准与灰度 | 可以用后验表现持续优化策略 |
|
|
|
+
|
|
|
+## 23. 待确认的业务决策
|
|
|
+
|
|
|
+| 决策项 | 当前行为 | 推荐默认口径 |
|
|
|
+|---|---|---|
|
|
|
+| 每日 200 条统计范围 | `primary` 去重计数 | 保持只统计可直接消费的 `primary` |
|
|
|
+| 日批优先级 | 代码实际先按 score，再按 S/A | 先 S 后 A，同等级按 score 降序 |
|
|
|
+| 200 条达标后的覆盖策略 | 达标即停止，后续需求不处理 | 至少完成全部 S 级，或为需求设置覆盖配额后再按总量停止 |
|
|
|
+| 最终结果权威源 | 模型文字可反向修改数据库 | 结构化最终化结果是权威源，文字仅由该结果渲染 |
|
|
|
+| 5 条目标 | 每个需求优先保留至少 5 条 | 保持软目标；任何证据门槛不得因数量降低 |
|
|
|
+| 模型选择 | 固定预览模型，传参无效 | 可配置稳定模型，并为模型/Prompt/策略版本留痕 |
|
|
|
+
|
|
|
+日批优先级和 200 条达标后的覆盖策略会直接改变业务产出，应由产品、供给运营和下游
|
|
|
+AIGC 负责人共同确认。其他项可按推荐默认口径推进。
|
|
|
+
|
|
|
+## 24. 产品完成定义
|
|
|
|
|
|
`find_agent` 达到产品化完成状态，需要同时满足：
|
|
|
|
|
|
- 对每日 S/A 需求可以稳定自动执行；
|
|
|
- 任务过程可恢复、可解释、可审计；
|
|
|
- 推荐建立在需求、年龄和分享三类独立证据上；
|
|
|
-- 主推荐、补充推荐和淘汰候选的边界清晰；
|
|
|
+- 主推荐和淘汰候选的边界清晰，不存在中间等级；
|
|
|
- 合理前沿耗尽时能够停止，数量不足时不降低质量；
|
|
|
- 外部接口失败时可解释降级；
|
|
|
- 最终报告与持久化结果始终一致；
|
|
|
- 运行时能够确定性阻止提前结束和不完整输出；
|
|
|
+- 强制重跑、进程异常和超时不会产生永久阻塞或新旧状态混合；
|
|
|
+- 当前功能契约、测试、Prompt、文档和监控口径保持一致；
|
|
|
- 后续可以将真实内容表现回流到需求供给闭环中。
|
xueyiming