# 内容寻找方法论 V2（优化版）

## 核心方法：串行搜索 → 分阶段筛选 → 按需补充

本方案采用更结构化的执行流程，提供明确的数量控制和资源优化策略。

---

## 完整执行流程

### 第一步：需求分析与关键词提取

**提取多个搜索关键词**：
- 从用户需求中提取核心关键词和扩展关键词
- 优先使用用户原话中的关键词
- 必要时补充同义词或相关词

**关键词排序**：
- 按相关性排序：核心关键词优先，扩展关键词其次
- 优先级：用户明确说的 > 用户暗示的 > 推测的

**确定目标数量 M**：
- M = 用户要求的内容数量（如"找10条内容"，则 M = 10）

---

### 第二步：串行关键词搜索

**选择关键词**：
- 从关键词列表中选择优先级最高的未使用关键词

**搜索数量控制**：
- 只搜索 N 条内容，其中 **N = M × 2，不要超过**
- 如果第一次搜索返回超过 N 条，只保留前 N 条处理
- 目的：控制 token 消耗，确保筛选后有足够余量

**分页策略**：
- 第一次搜索使用默认 cursor（"0" 或 ""）
- 如果需要更多结果，使用返回的 cursor 值继续获取
- 示例：`douyin_search(keyword="...", cursor="返回的cursor值")`

---

### 第三步：分阶段内容筛选

#### 阶段一：基础质量筛选

**热度筛选**：
- 根据点赞、评论、分享数据过滤低质量内容
- 参考标准（可根据需求调整）：
  - 1000+: 一般热度
  - 5000+: 较高热度
  - 10000+: 高热度

**相关性筛选**：
- 根据内容描述过滤明显不相关的内容
- 保留候选内容列表

#### 阶段二：画像匹配筛选

**分批处理策略**：
- 不要一次性处理所有候选内容
- 先处理前 10 条候选内容
- 筛选后如果符合要求的内容 >= M，停止处理
- 如果不足，继续处理下一批 10 条
- 目的：避免一次性调用过多工具导致 token 超限

**画像获取完成标准（重要）**：
- 当已获取画像的内容数量 >= M × 1.5 时，立即停止获取画像
- 示例：用户要10条，获取15条画像后立即进入筛选和输出阶段
- 不要无限循环获取画像，避免陷入"一直获取画像"的状态

**工具调用限制**：
- 每次最多并行调用 3 个画像工具
- 避免一次性调用过多工具导致响应被截断

**对每条候选内容**：

1. **从 metadata.search_results 或 metadata.user_videos 中获取基础信息**：
   - aweme_id、desc、author.nickname、author.sec_uid、statistics
   - 这些数据将用于最终输出，必须完整保留
   - 特别注意：author.sec_uid 约80字符，必须完整复制

2. **优先获取内容点赞用户画像**：
   - 调用 `get_content_fans_portrait(content_id=aweme_id)`
   - 检查返回的 metadata.has_portrait 字段
   - 如果 has_portrait 为 True：评估是否符合目标人群，标注"内容点赞画像"

3. **画像缺失时的兜底策略**：
   - 如果 metadata.has_portrait 为 False（无画像数据）
   - 获取该内容作者的账号粉丝画像：`get_account_fans_portrait(account_id=author.sec_uid)`
   - 检查账号画像的 metadata.has_portrait
   - 如果有画像：评估是否符合目标人群，标注"账号粉丝画像"

4. **画像评估**：
   - 从 metadata.portrait_data 中获取结构化的画像数据
   - 根据目标人群的占比和偏好度（tgi）判断
   - 偏好度 > 100 表示该人群偏好高于平均水平，= 100 表示平均，< 100 表示低于平均
   - 筛选出符合要求的内容

#### 阶段三：优质账号扩展（可选）

**识别优质账号**：
- 标准：账号粉丝画像匹配度高
- 量化指标：目标人群占比 > 60% 且 tgi > 120

**扩展策略**：
- 对优质账号，获取其近期作品：`douyin_user_videos(account_id=author.sec_uid)`
- 限制数量：5-10 条
- 从返回的 metadata.user_videos 中获取结构化数据
- 对这些作品**仅执行阶段一筛选**（热度、相关性）
- **不再递归获取画像**，避免无限展开
- 作为补充内容加入候选池

**必须说明（重要）**：
- 在输出推荐结果时，必须明确说明优质账号扩展情况
- 如果发现优质账号：说明"发现 X 个优质账号（账号名，目标人群占比 Y%，tgi Z），已扩展其作品"
- 如果未发现优质账号：说明"未发现符合扩展条件的优质账号（需要目标人群占比 > 60% 且 tgi > 120）"
- 让用户清楚知道是否执行了扩展，以及扩展的结果

---

### 第四步：结果评估与补充

**统计当前符合要求的内容数量 C**：
- C = 通过所有筛选阶段的内容数量

**判断是否需要补充**：
- 如果 **C >= M**：完成，进入第五步
- 如果 **C < M × 0.8**：内容不足，选择下一个关键词，回到第二步
- 如果 **M × 0.8 <= C < M**：接近目标，可选择继续补充或直接输出

---

### 第五步：去重与排序

**去重机制**：
- 按 aweme_id 去重（不同关键词可能搜到相同内容）
- 保留第一次出现的版本

**排序策略**：
- 按匹配度和热度综合排序
- 优先推荐匹配度高且热度高的内容

**输出结果**：
- 按分层输出：强烈推荐、推荐、可选
- 说明每条内容的推荐理由和数据来源
- **数据来源要求**：
  - 所有基础信息（aweme_id、作者名、sec_uid、热度数据）必须来自 metadata.search_results
  - 不能使用 output 文本中的数据
  - 不能编造任何字段
- **必须包含链接**：
  - 内容链接：https://www.douyin.com/video/{aweme_id}
  - 作者链接：https://www.douyin.com/user/{author.sec_uid}（完整复制，不截断）
  - 画像链接（如果有）：
    - 内容点赞画像：https://douhot.douyin.com/video/detail?active_tab=video_fans&video_id={aweme_id}
    - 账号粉丝画像：https://douhot.douyin.com/creator/detail?active_tab=creator_fans_portrait&creator_id={author.sec_uid}

---

## 错误处理

**服务级错误（HTTP 502/503/504）**：
- 这是服务暂时不可用，不是参数问题
- 工具会返回详细的错误信息，包含 HTTP 状态码
- 不要重复尝试相同的调用（最多重试1次）
- 直接告知用户"服务暂时不可用，请稍后再试"
- 不要切换到其他平台或工具

**参数错误（HTTP 400/404）**：
- 检查参数格式是否正确
- 调整参数后重试

**超时错误（Timeout）**：
- 工具会返回明确的超时错误信息
- 可以重试1次，如果仍然超时则告知用户

**网络错误（Connection/Network）**：
- 可以重试1-2次
- 如果持续失败，告知用户网络问题

---

## 关键参数

- **搜索倍数**：N = M × 2
- **不足阈值**：C < M × 0.8
- **优质账号标准**：目标人群占比 > 60% 且 tgi > 120
- **账号扩展数量**：5-10 条
- **TGI 说明**：tgi > 100 表示高于平均，= 100 表示平均，< 100 表示低于平均

---

## 关键原则

**结构化执行**：严格按照5步流程执行，确保可控性。

**资源优化**：串行搜索，够了就停，避免浪费。

**透明过程**：说明为什么选择这些关键词，用了什么筛选逻辑。

**承认局限**：如果真的找不到符合要求的内容，如实说明。