research-anything

---
name: research-anything
description: 当用户抛出探索性想法（没做过、不知道成熟路径，如"做 AI 漫剧""搭 XX 工作流""视频转文字选型"），或明确要求"调研某方向/看看有没有成熟做法/收集资料/比较方案"时使用。适用于需要跨抖音/小红书/知乎/B站/YouTube/GitHub/Twitter/通用 web 收集市面方案的场景。
---

# research-anything — 全渠道调研 → 可执行方案

给一个探索性 idea，系统化跨渠道搜集信息、核实比较，产出**1-3 个可落地方案 + 报告**供用户审核。核心价值：**拿到各渠道的先进做法，避免闭门造车落后几代**；产出物是"默认路径+切换条件"的可执行方法论，不是一堆并列选项让人自己选。

## 路径口径（先读这节；后文所有 <占位符> 按此展开）

- `<SKILL_DIR>`：本 skill 安装目录的绝对路径。调用 skill 时 harness 已告知（"Base directory for this skill: …"），照抄即可。
- `<PROJECT_DIR>`：当前会话项目根的绝对路径（`pwd` 的结果）。
- `<OUT_DIR>`：本次调研全部产物的根目录 = `<PROJECT_DIR>/docs/research/<slug>`。
- 爬虫工具常驻 `~/tools/`（与本 skill 安装位置无关）。本 skill 可在任意项目使用，产物落当前项目的 `<OUT_DIR>`。
- **传给任何子 agent / 脚本的路径一律用展开后的绝对路径**，不许传相对路径或未展开的占位符——子 agent 对"当前目录在哪"不做任何假设。

## 执行拓扑（关键）

```
用户（说出 idea）
 └─ 主 agent：初始化 4 状态文件 → 读渠道文档 → 首轮计划待批 → 【 收集扇出 → 补充认知 → 决策 】自主循环 O 轮 → 与用户交互 →（交互可重开循环）→ 收束方案
      │  状态外置：主 agent 增量维护 <OUT_DIR> 根的 target/glossary/consensus/gaps（判断在脑内、状态在盘上，见 state-files.md）
      ├─ 收集扇出（workflow.js，每轮落 research_<i>/）：每渠道 1 agent 开工前读 target/glossary/consensus → 实搜落盘（每条打 relevance 四档，只标不裁剪）→ 独立证据复核 → 返回小指针（含各档计数）
      └─ 补充认知 + 决策（主 agent 本人，用投影脚本通读；不派总结 agent）：
           ├─ 派 sub：生词建卡 → 增量写 glossary.json（不设上限）
           ├─ 派 sub：定点核查（事实题问官方、品质题问口碑）→ verdicts.jsonl；多源共识增量写 consensus.json
           ├─ 决策：承重未答问题写 gaps.json；还有 open 就把它转成新词再搜一轮（round+1，轮间只通报不问）；gaps 全清才转交互
           ├─ 【必经】交互：先在 qa.md 写「名词速览(取自 glossary)+交叉印证(取自 consensus)」讲给用户、答疑到无疑惑，再出选择题；回答原话追加 qa.md、结构化约束增量写 target.json；新约束可重开循环
           └─ 收束：落盘 report.html + runbook.json，按文件呈现
```

**判断力集中在主 agent 本人**（每轮它必须亲自通读笔记投影后再综合，并增量维护 4 个状态文件）；收集 agent 只做忠实笔记员。**收集 agent 不加载本 SKILL.md**——其规程靠"必读原文文件"直达（渠道文档 + log-format.md），外加开工前读 target/glossary/consensus 三个状态文件获取全局认知，但**只读不写**、不做跨渠道综合。总结/收束规程（summarize.md + report-format.md）由主 agent 每轮开工前自读原文。

## 流程：初始化 + 【收集 → 补充认知 → 决策】×O + 交互 ×P + 收束

总流程：**初始化 + 【[并行搜索 + 补充认知×N] × O + 与用户交互】× P + 收束方案**（N≤1、O≥1、P≥1）。收集↔补充认知每轮循环，交互至少一次（必经），交互可重开循环。判断在脑内、状态一律外置到 4 个文件（见 `<SKILL_DIR>/references/state-files.md`）。

### 阶段 0 — 初始化 + 意图澄清
初始化 `<OUT_DIR>` 根的 4 个状态文件（照 `<SKILL_DIR>/references/state-files.md` 的模板写）：`target.json` 填 idea 原话 + 已知约束，`glossary.json`/`consensus.json`/`gaps.json` 写空壳（各带 `_doc`）。只问 **1 个问题**确认调研主题没理解偏，**其余问题一律留到交互步**（看完市面上有什么再问，问题才有质量）——不在调研前逼问用户还答不好的目标/预算。

### 阶段 0.5 — 【强制】读完所有渠道文档（不可跳过）
做搜集计划**之前**，你（主 agent）MUST 完整读完 `<SKILL_DIR>/references/channels/` 下的**每一个** `*.md`（douyin / xiaohongshu / zhihu / bilibili / youtube / github / twitter / web）+ `<SKILL_DIR>/references/log-format.md`。这些文档写明每个渠道用什么工具、能/不能返回什么、耗时、失败与处理、防封号、运行侧安全约束、真实示例。

### 阶段 1 — 首轮搜集计划待批
按 `<SKILL_DIR>/references/search-plan.md` 把 idea 拆成结构化计划（**含预计耗时**）。铁律：
- **8 渠道全覆盖，不许跳过任何渠道**（任何题目在任何平台都可能有人发布相关内容）。
- **无"权重"列**；深度统一（默认 15/渠道），用户可按渠道调深度但不删渠道。
- 每渠道给多角度关键词（正面/痛点/对标/英文同义）+ 要提取的信号。
- ASR（fun-asr 口播转写）**默认开启、不设时长/费用上限，无需单独授权**（当前参考价约 0.8 元/小时，仅供参考）；缺 `DASHSCOPE_API_KEY` 或调用失败时诚实降级为 `capture.video.status:"failed"`。
呈现表格 → 用户增删 → **等用户明确批准**再继续。
**批准后立即把最终计划回填 `<OUT_DIR>/research_1/manifest.json` 的 `plan` 字段**（channels 转英文标准名 + dimensions，加 `approved:true`）——下游只看 manifest，不回看对话；不回填，用户批准的对比维度就丢了。（用户诉求/约束在 `target.json`，不在这里。）

### 阶段 2 — 收集扇出（每轮落 research_<i>/）
用本轮计划调收集脚本（首轮 `round:1`；追搜轮 `round:<i>` 由决策步给出）：

    Workflow({ scriptPath: "<SKILL_DIR>/scripts/workflow.js",
               args: { idea: "<idea 原话>", slug: "<slug>",
                       skillDir: "<SKILL_DIR>", outDir: "<OUT_DIR>", round: 1,
                       channels: [{name,keywords,signals,depth}, …], dimensions: […] } })

- `channels[].name` 必须用英文标准名（douyin/xiaohongshu/zhihu/bilibili/youtube/github/twitter/web）。脚本会校验并归一常见中文别名，未知名直接报错。
- 脚本先让每渠道 1 agent 实搜落盘，再让独立复核 agent 逐条补齐证据。复核只补字幕/口播、评论、图片文字、许可证和处理状态，不改候选集合、不做跨渠道综合。
- schema_version=2 的 finding 必须按 log-format.md 写 `capture`：正文来自哪里、视频/评论/图片/许可证是否处理、失败原因和产物路径。标题或简介非空不等于视频处理完成。
- 每条 finding 必须带 `relevance`（对用户诉求参考价值四档 `high`/`partial`/`mention`/`unrelated`，收集 agent 打；**只标不裁剪**，即使 unrelated 也照常落盘）——见 log-format.md《relevance 字段规格》。它驱动决策的 gaps 与每轮通报仪表盘。
本轮（研究目录 `<OUT_DIR>/research_<i>`）收集完成后，主 agent 依次跑：
1. 格式 + 覆盖校验（首轮渠道清单填计划里实际批准的渠道；就近发现本轮 manifest）：
   `python3 <SKILL_DIR>/scripts/validate_log.py --raw-dir <OUT_DIR>/research_<i> --channels <本轮渠道逗号分隔> --manifest <OUT_DIR>/research_<i>/manifest.json`
   （追搜轮渠道少、可逐文件校验：`--file <OUT_DIR>/research_<i>/findings.<渠道>.jsonl`。）
2. 证据覆盖统计（传 OUT_DIR 得跨轮累计，落盘供收束）：
   `python3 <SKILL_DIR>/scripts/coverage_report.py --raw-dir <OUT_DIR> --out <OUT_DIR>/coverage.json`
3. 规模统计（补充认知的输入之一，用于熔断判断；传 OUT_DIR 读全轮次）：
   `python3 <SKILL_DIR>/scripts/project_notes.py --raw-dir <OUT_DIR> --mode stats`
4. ASR 费用记录（信息性）：合计 `<OUT_DIR>/artifacts/asr_ledger.jsonl` 各行 billed_seconds，换算成累计时长/费用供报告展示；**不设上限、不做拦截**。
不合格 → 报给用户并按 SOP 重派，**不静默容忍**。
**单渠道重派 SOP**：① 删掉半成品：`rm <OUT_DIR>/research_<i>/findings.<渠道>.jsonl`，并同步删除该渠道旧 artifact（`setopt null_glob; rm -f <OUT_DIR>/artifacts/<渠道id前缀>-*`，前缀见 log-format.md 前缀表；不删则新 finding 复用同 id 时 validate 可能对着旧残片误通过）；② 重调 Workflow，args 同前、round 不变、channels 只留该渠道；③ 重跑校验。

### 阶段 3 — 补充认知 + 决策 + 交互（每轮，主 agent 本人）
每轮收集校验通过后，主 agent 用 Read 完整阅读两份规程原文并严格执行，不接受记忆版（log-format.md / state-files.md 已在前面读过）：
- `<SKILL_DIR>/references/summarize.md`（补充认知/决策/收束规程）
- `<SKILL_DIR>/references/report-format.md`（交付物规范）

输入：`<OUT_DIR>/target.json` + 各轮 `research_<i>/findings.*.jsonl` + `coverage.json` + 规模统计。生词建卡与定点核查照旧派 sub agent 并行，但**通读、判断、综合、维护 4 个状态文件、与用户沟通、写报告全部由主 agent 本人完成**——与用户的沟通不经任何中转（2026-07-15 拍板：中转通信绕、且子 agent 进程退出会让对话续不上）。

**这是一个 gaps 驱动的收敛环**：每轮通读后 → 补充认知（生词增量写 `glossary.json`、承重存疑说法核查落 `verdicts.jsonl`、多源共识增量写 `consensus.json`）→ 决策（承重未答问题写 `gaps.json`；还有 `open` 就把它转成新词、写 `research_<i+1>/manifest.json`、调 `Workflow` `round:i+1` 再搜一轮，**轮间只发通报不问**；gaps 全清才转与用户交互）。**交互必经**；用户新约束可把新承重点写回 gaps（`open`）重开循环。**停止权在用户，绝不无限自搜。** 判据、模板、两段式先讲后问全部详见 summarize.md。
警告不变：禁止用 Read 直接读 findings.*.jsonl（超长行会被截断），一律用 `project_notes.py` 投影读取；熔断、绝不截断等规矩以 summarize.md 为准。

**问答存档铁律**：用户问答以 `<OUT_DIR>/qa.md` 为唯一权威记录（只许追加）——主 agent 先把「名词/地点速览」「交叉印证」两节与问题**原文**写入 qa.md，再呈现给用户；用户每次回答/追问，主 agent **立即一字不改**追加回 qa.md（防上下文被压缩后原话丢失）。禁止只在对话里问而不落盘；禁止改写/臆想/代答。

### 交付
主 agent 落盘 `report.html` / `runbook.json` 后，呈现方式：定位 report.html 的 `<section id="summary">`、`<section id="plans">`、`<section id="reco">` 三节并读取原文，**引用原文**呈现要点（不整读全文、不凭记忆复述），并给出两份文件路径供审核。呈现要点时，对首次出现的关键地名/术语附一行短释（取自 glossary 生词卡）——不许拿用户没见过的名词裸讲方案。注意：report.html 常为长行/压缩 HTML，Read 行区间对超长行会**静默截断**——一律用程序化切片提取（如 `python3` 正则取 `<section id="...">…</section>` 再剥标签），不要用 Read 行区间硬读（2026-07-13 实录）。

## 渠道路由表
| 渠道（标准名） | 文档 | 渠道（标准名） | 文档 |
|---|---|---|---|
| 抖音 douyin | channels/douyin.md | YouTube youtube | channels/youtube.md |
| 小红书 xiaohongshu | channels/xiaohongshu.md | GitHub github | channels/github.md |
| 知乎 zhihu | channels/zhihu.md | Twitter/X twitter | channels/twitter.md |
| B站 bilibili | channels/bilibili.md | 通用 web web | channels/web.md |

## 前置依赖（工具全部住在 ~/tools/）
- **收集派发前连通性预检（主 agent）**：`curl -sS -m 8 -o /dev/null -w '%{http_code}\n' https://x.com https://www.youtube.com`（常用代理时另测代理链路）。不可达的渠道不要静默空转：把结论告知用户，由用户选择照跑（渠道按规程申报失败）/ 修好网络再跑。2026-07-13 实录：代理上游节点故障导致 Twitter 整渠道 0 条、YouTube 全程降级。
- 小红书 MCP 服务：`~/tools/xiaohongshu-mcp/server.sh start`（未起则先起；**未登录时调研直接走 MediaCrawler 工具 B，禁止唤登录二维码**）。
- MediaCrawler 四平台登录态已持久化；Twitter 需 twscrape + 账号（见 twitter.md）。
- YouTube/B站字幕需 yt-dlp（已装 `/opt/homebrew/bin/yt-dlp`）。B站 ai-zh 字幕用已导出的 cookie 文件取（`~/tools/bili_cookies.txt`，2026-07-13 导出，零弹窗；**禁止 `--cookies-from-browser`**——每次触发钥匙串弹窗，仅 cookie 过期重导时用一次）。YouTube 字幕直取无需 cookie，批量拉注意限流。
- 视频口播提取（`<SKILL_DIR>/scripts/transcribe.py`，fun-asr）需环境变量 `DASHSCOPE_API_KEY`（阿里云百炼 API Key，放 `~/.zshrc`；**凭据绝不写进 skill/报告**）。计费按语音内容时长（约 0.8 元/时，开通后 90 天 10 小时免费）；2026-07-13 实测约 60 倍实时、抖音/小红书直链可免下载直传。**ASR 默认开启、不设时长/费用上限、无需单独授权**——视频需要就转；缺 `DASHSCOPE_API_KEY` 或调用失败时降级为 `capture.video.status:"failed"` 并写明原因。每次调用自动在输出目录追加费用台账 `asr_ledger.jsonl`（每行含 billed_seconds），仅作信息性记录、不做对账拦截。最终入选的抖音/小红书视频全量转写；B站优先 ai-zh 字幕、无字幕才转写；YouTube 优先原字幕；Twitter 所有带视频的入选推文均须字幕/ASR。用法见各视频渠道文档。
- 小红书配图文字用 `<SKILL_DIR>/scripts/ocr_images.py` 识别（macOS 系统文字识别，无额外 Python 依赖）。处理最终入选图文笔记的全部配图，视频封面不强制；结果写入 finding 的 content/note，并在 capture 记录处理数量和产物路径。

## 关键设计约束（不可违背）
- **绝不截断**：任何环节不许静默丢材料；笔记全集读不下→报错停止问用户，不取子集。
- **可追溯**：报告/runbook 每个结论必须带 finding id 或 verdict id（vd-xxx）引用。
- **证据完整性**：入选视频必须有字幕/ASR 或明确失败原因；入选社交内容必须抓前 10 条有用评论或明确不可用；小红书图文笔记配图必须全部识别或逐项报错；GitHub 许可证只认根目录实际 LICENSE 文件。validate_log.py 不通过就禁止进入补充认知。
- **ASR 默认开启**：付费 ASR（fun-asr）默认可用、不设时长/费用上限、无需单独授权；缺 `DASHSCOPE_API_KEY` 或调用失败时诚实降级为 `capture.video.status:"failed"` 并写明原因。台账 `asr_ledger.jsonl` 仅作信息性费用记录。**凭据绝不写进 skill/报告。**
- **核实分类**：事实题（价格/授权/接口）问官方即权威；品质题（准不准/好不好）**官方自评不算数**，必须搜口碑/独立评测，不够则进 runbook 的 to_test 待实测。
- **代际感**：生词建卡含发布时间，由卡片拼出方法/模型时间线，防"推荐落后几代还不自知"。
- **状态外置、单写多读**：调研状态一律落盘在 target/glossary/consensus/gaps 四个文件（判断在脑内）；**只有主 agent 写、且增量更新**，收集 sub 只读前三个。抗上下文压缩、可恢复、可审计。
- **迭代有界、gaps 驱动**：入 gaps 的判据是"承重（会改推荐/某步/否决点）＋现有资料没说清"两条**同时**满足；`open` gap 驱动下一轮搜索，全清即"该问的问清了"转交互；二次收集维持原样强度、轮间只通报，但**绝不无限自搜——停止权在用户**。
- **相关性只标不裁剪**：收集 agent 给每条 finding 打 `relevance` 四档，但**绝不因相关性删条**，与"绝不截断"同源。判断"哪条要回头搜、哪句承重"仍归读过全集的主 agent。
- **原话神圣**：本 skill 中标注"原话/一字不改"的引用块（log-format.md 的笔记目的句与京都三条示范、qa.md 的问答记录）在任何未来迭代中**禁止润色/概括/替换**——此前迭代中已发生过三次被 AI 顺手改写，勿重蹈。