# 经验方法总结

> aigc-idea-impression 的经验方法总结库。使用中发现的问题、失误、经验教训与成功方法，统一记录于此，形成「发现问题 → 沉淀规避 → 固化红线/规范」的闭环。
> 编号规则：#0XX，按主题归档（合并同类项），不按时间堆叠。沉淀后须同步评估是否升级到 POLICIES.md 或操作规范。

---

## 分类索引

| # | 主题 | 核心结论 |
|---|------|---------|
| #001 | 浏览器优先 + 模拟用户操作 | 数据获取浏览器优先；读取页面数据≠代替用户行为 |
| #002 | 付费 API 成本红线 + 执行约束 | 红狐等付费接口未获允许禁调用；经验须写入 SKILL.md 才生效 |
| #003 | 抖音作品数据获取（Fiber 首选） | React Fiber 提取 awemeInfo 是最优解；先查技能库再动手 |
| #004 | 风控规避 | 触发风控立即停止，冷却 15-30 分钟，一次只处理一个 |
| #005 | 数据归档与结构规范 | 数据落 MCNSkill项目；技能用 subskill 组织 |
| #006 | 视频抽帧规范必须加载 | 抽帧先读《视频抽帧与字幕规范.md》；反推≠规则 |
| #010 | 抽帧规则须内联展示 + OCR 须逐帧 | 规则只链接不入 SKILL.md＝不明显＝没写；字幕禁只对代表帧 OCR |

---

## #001 浏览器优先 + 模拟用户操作（合并 #001/#004，2026-08-30）

**背景**：获取抖音账号「雨菲啊」数据时先用了红狐 API，用户纠正应走浏览器；后又明确要求必须**模拟真实用户操作**（搜索/点击/滚动），禁止内置脚本直跑代替浏览器行为。

**铁律：**
1. **账号/作品数据浏览器优先**：browser-harness 打开抖音网页版提取，第三方 API 仅兜底并注明来源
2. **模拟用户操作**：输入（type_text）+ 点击（click_at_xy）+ 滚动（scroll）构成行为序列；内置脚本/API 仅浏览器不可达时降级
3. **读取数据 ≠ 代替行为**：读取已渲染数据（如 Fiber 提取）不违反红线——红线禁止的是"脚本代替用户写操作/抓取行为"，不是禁止读数据
4. **未登录态限制**：搜索卡片仅公开信息，如实告知能力边界
5. 固化 → [POLICIES.md](POLICIES.md) P0-3、[获取抖音账号数据操作规范.md](references/操作规范/获取抖音账号数据操作规范.md)

## #002 付费 API 成本红线 + 执行约束（#009，2026-08-30）

**背景**：多次沉淀的"浏览器优先、红狐仅兜底"经验，执行时又用了红狐 API（付费消耗积分）。根因：经验只写在 md 文档，**执行时未加载 SKILL.md → 红线不在上下文 → 零约束**。

**铁律：**
1. **付费 API = 成本红线（P0-8）**：红狐 API 消耗积分（花钱），未获用户明确允许**禁止调用**；浏览器优先首先是成本问题
2. **经验必须可加载**：关键 SOP/红线写入总控 SKILL.md「执行前强制检查」节，被加载即进入执行上下文
3. **执行前自检三问**：① 技能库有无现成方法（先查库）？② 浏览器能否完成（Fiber 优先）？③ 付费 API 是否获用户允许？
4. 固化 → POLICIES.md P0-8、SKILL.md「执行前强制检查」节

## #003 抖音作品数据获取：React Fiber 首选（#007/#008，2026-08-30）

**背景**：曾用 hover 读时长（触发预览节流）、网络层/全局变量（均碰壁）；参考 mcn-dou-analysis 才发现 **React Fiber 提取 awemeInfo**——遍历 `a[href*="/video/"]` 向上查 Fiber 中 `awemeInfo`，一次拿全字段（id/标题/时长毫秒），实测与 ffprobe 完全一致，无 hover 不触发风控。

**铁律：**
1. **Fiber 提取首选**：`__reactFiber$`/`__reactInternalInstance` 向上 30 层内查 `awemeInfo`/`data`/`item`/`aweme`（命中 `v.aweme_id || v.video`）
2. **duration 为毫秒**：筛 ≥60s 用 `>= 60000`；js 返回值有截断，用 `slice(START, START+8)` 分页取
3. **滚动容器**：`.route-sc`/`route-scroll-container`（非 window），scrollTop=scrollHeight 触发懒加载，随机 1~3s
4. **操作优先级**：Fiber 读取 > hover/点击交互 > 网络层 > 第三方 API（最后兜底且注明来源）
5. **先查库再动手**：数据获取先查技能库现成方案（mcn-dou-analysis 即答案库），禁止重复造轮子
6. 固化 → 获取抖音账号数据操作规范.md 步骤 5（hover 降为备选）

## #004 风控规避（#006/#005，2026-08-30）

**背景**：批量连续 hover 46 卡片（机器扫描特征）→ 预览节流 + CDP 连续超时 + 页面 title 变「🐴」验证页。真人只对感兴趣卡片停留，批量扫描必被识别。

**铁律：**
1. **触发即停**：预览节流/验证页/内容区封锁/CDP 超时任一信号 → 立即停止，禁止刷新重试（会加重）
2. **冷却**：≥15-30 分钟不操作；恢复前先手动正常访问一次确认无验证页
3. **一次一个**：多目标逐个串行，间隔自然（3-5s+），禁止 for 循环批量扫描
4. 固化 → 获取抖音账号数据操作规范.md「风控规避红线」节、POLICIES.md P0-7
5. 备注：hover 时长角标（#005 原内容）已并入此条背景——hover 只作直链捕获备选，时长提取走 Fiber

## #005 数据归档与结构规范（#002/#003 更新，2026-08-30）

**背景**：归档规则历经 RedFox数据→MCNSkill项目、时间层→账号名层演进；三技能统一为 subskill 组织。

**铁律：**
1. **数据根目录**：`D:\MCNSkill项目\`；榜单/信息源按月分，作品/视频按 `作品数据\{账号名称}\`
2. **视频文件夹**：`{标题清洗}_{发布时间YYYY-MM-DD}\`；账号层另存视频列表 Excel（13 列+封面）
3. **JSON 保留完整结构化字段**，文件名含实际数据日期；详见 [数据归档规范.md](references/操作规范/数据归档规范.md)
4. **技能结构**：aigc-idea-impression 为父技能总控，子技能入 `subskill/`（对齐 mcn-short-video 模式）；目录变动后立即死链检测

## #006 视频抽帧规范必须加载（2026-08-30）

**背景**：处理 B 站视频（BV1vcG36sEEr）抽帧时未读《视频抽帧与字幕规范.md》，凭历史产物（scene_*.txt / frames_combined / kf_*）反推"场景检测 + I 帧"当规则执行，**漏掉字幕区检测（crop + scene 0.1）→ 画面静止但字幕换句的帧全部丢失**，用户察觉"字幕丢了"后才暴露。且 `-ss` 逐点抽帧遇 Python CRLF 行尾全批失败。

**根因**：与 #002 同型——规范已沉淀但未进 SKILL.md「执行前强制检查」→ 执行时零约束；另叠加"从产物反推流程"误当规则。

**铁律：**
1. **视频下载/抽帧/字幕提取任务，先读** [视频抽帧与字幕规范.md](references/操作规范/视频抽帧与字幕规范.md)（细则以规范文档为准）；核心教训：**双因素抽帧（画面+字幕区），I 帧/固定节奏均漏字幕**
2. **反推 ≠ 规则**：从历史产物反推流程只用于理解产物，不用于定义执行流程；执行以 SOP 文档为准，文档缺失先补文档再执行
3. **时间戳文件 CRLF 防护**：Python/Windows 生成列表文件行尾带 `\r` 会导致 ffmpeg `-ss` 报 Invalid duration → 统一 `tr -d '\r'` 或 `newline='\n'`
4. 固化 → SKILL.md「执行前强制检查」1.1 节、视频抽帧与字幕规范.md「常见坑」
5. 扩展 → #010（规则须内联进 SKILL.md + 字幕必须逐帧 OCR，二者共同补足本教训的执行约束盲区）

## #010 抽帧规则须内联展示 + 字幕 OCR 须逐帧（2026-10-05）

**背景**：在 agent-product 工作区重做两视频（B站 BV1gsHn6AEk6 / YouTube jVHyoCYidLM）字幕时，明明已先读《视频抽帧与字幕规范.md》，仍出现大量字幕遗漏。根因有二：
1. **规则展示不明显**：#006 只把规范"链接"到 SKILL.md（"仅引用"），核心铁律未内联进「执行前强制检查」节，执行上下文里要"点开链接才看见"，极易凭旧产物的反推习惯（只对每簇代表帧 OCR）绕过。
2. **字幕 OCR 只对代表帧**：聚类后每簇只 OCR 一帧，代表帧一旦模糊/过渡/fade，整句字幕永久丢失——B站 45 条→重做 241 条、YouTube 98→253，直接印证"很多字幕没抓到"。

**根因**：与 #002 同型——规则进了规范文档 ≠ 进了执行上下文；且"代表帧 OCR"是历史产物的反推习惯，规范未明确禁止。

**铁律：**
1. **规则内联进 SKILL.md**：抽帧/字幕核心铁律（双因素+首尾+补帧、crop 按实际分辨率、CRLF、`-ss`、逐帧 OCR）直接写在总控「执行前强制检查」1.1 节，被加载即进入上下文，不靠"点开链接才看见"
2. **字幕 OCR 必须逐帧**：对每帧字幕区 OCR 后按时间滚动去重（相似度 ≥0.80 合并保留最长），禁止只 OCR 代表帧
3. **字幕区 crop 按实际分辨率**：先抽一帧确认字幕位置；1080p 横屏 `crop=1920:162:0:918`、720p `crop=1280:108:0:612`、竖屏 `crop=720:240:0:720`
4. **展示即约束**：规范文档顶部须有"核心铁律"速查块；规则不明显 = 等于没写
5. 固化 → SKILL.md 1.1 节（内联铁律）、视频抽帧与字幕规范.md 顶部核心铁律块 + 五（逐帧 OCR）、本 #010

---

## 使用方法

- 新经验按主题归类：已有同类条目 → 并入该条铁律；全新主题 → 追加 #0XX
- 涉及红线 → 同步升级 `POLICIES.md`；涉及操作细节 → 同步 `references/操作规范/`
- 过时内容 → 立即更新（如路径/方法变更），不留历史包袱