# Super Search

> 通用网页搜索、爬取、交叉验证与研究报告生成。用户说 search、搜索、查一下、帮我搜、调研、collect information、find sources、verify facts、交叉比对、验证真实性、收集资料、整理信息、查证某个说法、看看网上怎么说、有没有证据支持、信息可信度如何时触发。自动搜索多源内容，抓取并缓存，分析内容质量（评分仅作参考，低质直接舍弃），交叉比对事实一致性，对高严谨度内容（医学、法律、金融等）自动触发对抗性审查。最终输出结构化研究报告到指定目录。≠ hv-analysis（那是深度产品/公司分析框架）。

- Skill: `caomeiyouren/super-search` (Agent Skill, multi-file: 27 files)
- Install (CLI): `npx skillmds@latest add caomeiyouren/super-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/caomeiyouren/super-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: caomeiyouren (https://skillmd.com/u/caomeiyouren)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/caomeiyouren/super-search

---


# Super Search

IRON LAW: NEVER GENERATE ANSWERS FROM TRAINING DATA. Every factual claim in the report must be traceable to at least one URL fetched during this session.

## 核心定位

通用网页调研与事实核查工具。与 `hv-analysis`（强制横纵轴框架、产出 10K-30K 字 PDF 的深度产品/公司研究）的关键差异：

| | hv-analysis | Super Search |
|---|---|---|
| 研究框架 | 纵轴+横轴+交叉洞察（强制） | 无预设框架，按需灵活 |
| 适用范围 | 产品/公司/概念/人物 | 任意主题 |
| 报告深度 | 10K-30K 字 PDF | 轻量到中等，按需 |
| 对抗审查 | 鼓励批评思考（非系统化） | 所有主题通用：时效性+真实性双重审查 |
| 缓存 | 无 | 内置 TTL 缓存层 |

## Workflow

### ⚡ Fast Path（90% 搜索用此路径）

大多数搜索不需要完整 9 步流程。实际执行模式：

```
加载 skill → 领域探测(references/domain-detector.md) → 3-4 并行搜索 → 1-2 并行抓取 → 手动写报告 → 交付
```

脚本（env-check/search/fetch/analyze/report/review）仅在 deep 模式或需要缓存时运行。

### 完整 Deep Path（金融/医学/法律或 2+ 领域探测器命中时）

Copy this checklist and check off items as you complete them:

Super Search Progress:

- [ ] Step 0: Domain Detect ⚠️ REQUIRED — 回答 5 个领域探测器问题，确定验证深度
- [ ] Step 1: Environment Check — 仅在 deep 模式运行 `node dist/env-check.mjs`
- [ ] Step 2: Plan — 解析用户意图、扩展多语言关键词、确定搜索深度
- [ ] Step 3: Search — 多源搜索，收集结果 URL
- [ ] Step 4: Fetch — 批量抓取内容，先查缓存
- [ ] Step 5: Analyze — 质量评分（仅参考，低质舍弃），排序整理
- [ ] Step 6: Cross-Reference — 多源比对，矛盾标注
- [ ] Step 7: Review ⚠️ REQUIRED — 时效性+真实性双重审查所有关键数据
- [ ] Step 7.5: Template Selection ⚠️ REQUIRED — 根据主题特征选择报告模板
- [ ] Step 8: Report — 按选定模板生成结构化报告写入文件
- [ ] Step 9: Verify — 交付前检查

## Step 0: Domain Detect ⚠️ REQUIRED — 进入搜索前的强制决策门

回答以下 5 个问题，确定搜索深度和验证策略（详见 `references/domain-detector.md`）：

| # | 探测问题 | 命中关键词 | 命中后强制动作 |
|---|---------|-----------|--------------|
| Q1 | 涉及 GitHub/开源项目？ | github、开源项目、repo、star、fork | 抓取原始 repo 确认 ⭐/license/activity + 扫 Issues |
| Q2 | 涉及金融/投资/金钱？ | 金融、股票、投资、基金、trading、定价、pricing | 完整对抗审查 + 风险矩阵 + 免责声明 |
| Q3 | 涉及医学/法律/安全？ | 医学、医疗、法律、安全漏洞、vulnerability | 完整对抗审查 + 置信度标注 |
| Q4 | 涉及产品/工具/竞品对比？ | 对比、比较、哪个好、排行、推荐、选型、vs、竞品、替代品、为什么选、migrate | 官方页面对比抓取 + 工具对比 → **触发安全审计调查**（`references/competitive-analysis.md`） |
| Q5 | 时效性敏感？ | 最新、2026、近期、latest、trending | 标注所有数据日期 + 6 月过期警告 |

**在进入 Step 3 搜索之前**，必须输出决策 JSON：

```json
{
  "topic": "用户搜索主题",
  "domains": ["github", "ai"],
  "triggers_fired": ["github-verification"],
  "depth": "normal",
  "multi_language": ["en"],
  "counter_queries": ["...反面搜索词..."],
  "verification_actions": ["抓取所有引用 GitHub repo", "标注 ⭐ 获取日期"],
  "source_priority": "github-projects"
}
```

`source_priority` 根据 domains 自动匹配 `references/source-priority.md` 中对应领域的高优先级信源表，搜索时优先从这些信源获取。

**深度映射**：0 命中 → Quick | 1 命中（非金融）→ Normal | 命中金融或 2+ → Deep

⚠️ 未输出决策 JSON 前不得进入 Step 3 搜索。

## Step 1: Environment Check

仅 Deep 模式运行。Normal/Quick 模式直接使用可用工具。

**工具可用性铁律**：记录所有可用工具的完整列表（如 tinyfish-search_search、webfetch、gh api 等）。后续每个搜索/抓取操作优先使用主要工具；失败时依次切换到列表中的下一个工具，直到成功或全部尝试完毕。

## Step 2: Plan

解析用户输入，确定：
- 核心主题与搜索关键词
- 搜索深度：`quick`（3-5 源）、`normal`（8-12 源）、`deep`（15-20 源）
- 是否需要对抗审查（见 `references/review-triggers.md`）
- 信源优先级：按 `references/source-priority.md` 确定搜索路径，**先搜 L0-L2 高信源，再下探**
- 输出文件路径（用户指定或默认 `./research-output/{date}-{topic-slug}.md`，若文件已存在自动追加 `-v2`/`-v3` 后缀）
- 缓存目录（用户指定或默认 `~/.super-search-cache/`）

Ask: "对以下问题，我应该额外搜索哪些对立面/反面/批评性关键词？"
例如：搜索"AI 取代程序员"时，同时搜索"AI 不会取代程序员的理由""AI 编程工具的局限性"。

### 多语言关键词扩展 ⚠️ 必须执行

识别主题所属领域，推断可能的原始信息语言，使用多语言关键词扩大搜索范围。扩展规则：

| 领域 | 扩展语言 | 说明 |
|---|---|---|
| 科技/AI/编程 | + 英文 | 科技内容主要信息源为英文，多数研究论文、官方文档和一手资料首发于英文 |
| 动漫/ACG/日式游戏 | + 日文 + 英文 | 日本动漫内容的原始来源为日文，使用日文关键词可获取一手资料（如官网、访谈、制作组发布）；英文社区也有大量讨论 |
| 日本文化/任天堂/JRPG | + 日文 + 英文 | 同上，日本文化相关信息的原始来源为日文 |
| 韩国流行文化/K-pop | + 韩文 + 英文 | 韩国文娱内容原始来源为韩文 |
| 其他/通用 | + 英文（最低） | 英文为互联网主要语言，至少添加英文搜索扩展 |

**扩展策略**：
- 中文关键词 → 翻译为目标语言关键词（使用内置术语映射表）
- 添加混语言查询（如 `"中文词" site:en.wikipedia.org`、`"translated topic" Reddit`）
- 在 `deep` 模式下添加学术搜索维度（如 `"translated topic" research paper`、`"translated topic" arXiv`）
- 对日本动漫使用罗马音和日文汉字双重搜索

运行 `node dist/search.mjs --topic '...' --depth normal` 时，脚本会自动生成 `multiLanguageQueries` 字段。AI 在执行搜索时，必须对每类多语言查询执行搜索，不可跳过。

## Step 3: Search

**搜索条目数量**：
- `quick` → 每个查询 `limit=10`
- `normal` → 每个查询 `limit=10`，关键维度追加翻页 `page=2`
- `deep` → 每个查询 `limit=20`，翻页 `page=2`，学术搜索追加 `page=3`

根据计划执行搜索。**搜索执行顺序**：
1. 先执行主查询（`queries` 字段）
2. 再执行多语言查询（`multiLanguageQueries` 字段），**不可跳过**
3. 最后执行对抗查询（`counterQueries` 字段）

### GitHub 项目数据直接查证 ⚠️ Q1 命中时必须执行

当 Q1（涉及 GitHub/开源项目）触发时，在完成网页搜索和抓取后，**必须额外使用 GitHub API 直接查询每个引用项目的精确数据**，不得仅依赖网页搜索片段中的近似值。优先使用 `gh api`（已认证的 GitHub CLI），无 gh 或认证失败时使用 webfetch 抓 `api.github.com/repos/{owner}/{repo}`（匿名限流 60/h，足够查证）。

**必须查证的项目维度**：
| 维度 | 方式 | 原因 |
|------|------|------|
| ⭐ Stars（精确值） | `gh api repos/{owner}/{repo}` 或抓 api.github.com | 网页搜索 snippet 常隐去或四舍五入 stars |
| 🕐 最后推送日期（pushed_at） | 同上 | web search 不展示此字段 |
| 🍴 Forks 数 | 同上 | 同上 |
| 📋 Open Issues 数量 + 内容 | `gh api repos/{owner}/{repo}/issues?state=open` | 网页抓取只能看到首页，需翻页确认 |
| 📌 Open PRs 数量 + 内容 | `gh api repos/{owner}/{repo}/pulls?state=open` | 评估项目活跃度和方向 |
| 🔖 最新发布版号 | `gh api repos/{owner}/{repo}/releases/latest` | 确认项目是否仍在发布新版本 |
| 许可证 | repo 接口 license 字段 | 确认合规 |
| 是否归档（archived） | repo 接口 archived 字段 | 确认项目是否存活 |

**执行时机**：完成网页搜索和内容抓取后、进入 Step 5 Analyze 之前。对所有报告中引用/对比的 GitHub 项目，逐条使用 API 查证。

**API 失败降级**：GitHub API 返回 401/403/rate-limit 时（token 失效、未认证、超限），改用网页抓取 repo 页（tinyfish fetch 或 webfetch），渲染后的页面顶部导航+About 区含 ⭐/forks/license/archived 信息，Issue/PR 页同样可抓——足以完成大部分查证。

**反模式**：仅凭 web search snippet 中的 star 数（常被缩写为 "k" 或省略）就写入报告；或只抓取 README 页面而不使用 API 查询实际 metrics。

### 社区工具/插件安全验证 ⚠️ 推荐社区方案时必须执行

当调研结果中包含对第三方社区工具、插件、库的推荐时（如搜索"有没有支持 X 的插件"并列出候选），在写入报告前必须对**每个候选项目**进行安全与真实性验证：

| 验证维度 | 方法 | 排查目标 |
|---|---|---|
| ⭐ Stars 数 | GitHub API `stargazers_count` | 排除刷星或极小项目 |
| 📋 Open Issues | `issues?state=open` 查看内容 | 是否有未修复的安全/数据丢失 bug |
| 🔖 License | `license.spdx_id` | 无许可证的项目谨慎推荐（法律风险） |
| 🧑‍💻 Owner 类型 | `owner.type` (User vs Organization) | 个人项目 vs 组织级维护 |
| 🕐 活跃度 | `pushed_at` 对比 `created_at` | 是否仍在维护，还是已弃坑 |
| 🚫 Archived | `archived` | 归档项目不可推荐 |
| 🛡️ 网络请求审计 | 扫描源码中 fetch/axios/curl/http 调用 | 是否有向第三方服务器上报数据 |
| 🔍 权限审计 | 扫描源码的文件读写、数据库操作 | 是否只读访问本地数据，还是可能篡改 |

**执行时机**：在 Step 5 Analyze 之前，对候选列表中的每个 GitHub 项目使用 API 逐条查证。

**判定标准**：
- **安全**：MIT/Apache/GPL 等明确许可证 + 仅本地只读操作 + 无数据外泄网络请求 + 活跃维护
- **需留意**：有主动上传/提交数据到远程服务器的功能（需 opt-in 才接受）、或缺少许可证
- **不推荐**：无许可证 + 不可见源码（预编译二进制）+ 已归档 + 有可疑网络请求

**工具降级策略**：
- 优先使用主要 search 工具（如 tinyfish-search_search）
- 该工具返回错误/超时/无结果 → 自动切换到下一可用 search 工具
- 全部 search 工具失败 → 将搜索词作为 URL 尝试直接 fetch（如 site:xxx 搜索变体），或跳过该关键词并记录
- 每个搜索词至少尝试 2 种不同的工具或查询变体

**数据充分性铁律**：每个关键维度（如"价格""规格""政策"）至少需要 2 个来源覆盖。不足时立即触发**搜索引擎补充发现**——使用所有可用 search 工具，变换关键词（加"对比""排行""价格表""2026"等后缀），迭代搜索直到找到足够数据或确认该维度确实没有公开可查的数据。禁止在数据不足时直接跳过该维度。

**多语言搜索结果合并**：不同语言搜索返回的结果按同一标准纳入质量分析流程，来源权威度评估会考虑是否为该领域的原始信息语言。例如，日文官方页面在动漫相关主题中的权威权重高于中文转载页面。

### 搜索终止条件

满足以下条件时停止搜索并进入抓取阶段：
1. 每个关键维度至少有 **2 个来源**覆盖，且来源类型 ≥2 种（详见 `references/source-priority.md`）
2. 官方页面已全部尝试抓取（成功获取数据或确认无法获取并记录原因）
3. 已执行 **2 轮**关键词变体搜索，新增结果趋于重复（>80% 重复）
4. 对高风险主题（医学/法律/金融）已执行对抗性搜索
5. GitHub 项目类搜索 → 已抓取所有引用项目的 Issues 页面（前 2 页）

**信源质量检查**：在终止搜索前，确认：
- □ 至少 1 个一手/官方来源（GitHub repo、官方文档）
- □ 涉及的 GitHub 项目已抓取原始 repo 页面（非第三方文章中的转述）
- □ 聚合/转载类来源 ≤ 总来源的 30%

不满足时继续触发搜索引擎补充发现，不可在数据不足时跳过。

## Step 4: Fetch

运行 `node dist/fetch.mjs --cache-dir '...'` 检查缓存。

- 命中缓存 → 直接使用缓存内容（`node dist/cache.mjs get --url "..." --type fetch`）
- 未命中 → 抓取内容。**工具降级策略**：
  1. 优先使用主要 fetch 工具（如 webfetch 或 tinyfish-search_fetch）
  2. 返回 403/404/Transport Error/JS 空壳/工具不可达 → 自动切换到下一个可用 fetch 工具
  3. 全部 MCP fetch 工具失败 → **使用 terminal + curl 回退**：

     **优先尝试 `Accept: text/markdown` 头**（适合文档站）：
     许多文档站点（Cloudflare、GitHub 等）支持直接以 Markdown 格式返回内容。加上该 header 后 curl 输出即为纯净 Markdown，无需 HTML 剥离：
     ```bash
     curl -sL -H "Accept: text/markdown" "https://developers.cloudflare.com/cache/how-to/tiered-cache/"
     ```
     部分站点还提供 `.md` URL 后缀变体（如 Cloudflare 官方文档会在 HTML 页面提示 `append index.md`），可一并尝试。

     **回退到 HTML 剥离**（文档站无 Markdown 支持时）：
     ```bash
     curl -sL "https://example.com" | python3 -c "
     import sys, re
     content = sys.stdin.read()
     text = re.sub(r'<[^>]+>', '', content)  # 去 HTML 标签
     text = re.sub(r'\\s+', ' ', text).strip()
     print(text[:3000])  # 限制长度
     "
     ```
     也可搭配 `sed -n 's/<[^>]*>//gp'` 做简单剥离，或 `html2text` 做更干净的转换。

     ⚠️ 注意：curl 输出的 HTML 可能包含 JS 引导的验证墙（如 Cloudflare Challenge），此时需确认使用浏览器工具替代。

     **基础设施/云服务类调研的补充验证**：
     对于 CDN、DNS、代理等基础设施类服务，在回读文档之外还可以**直接测试其诊断端点**以获取实时运行数据。详见 `references/cdn-infrastructure-research.md`。
  4. terminal+curl 也失败 → 进入 **搜索引擎替代抓取** 流程（见下方）
- 抓取后**必须立即**回写缓存：

默认 TTL：搜索结果 30min，网页内容 24h。

## Step 5: Analyze

对每条内容按 `references/source-priority.md` 标注质量层级（🥇/🥈/🥉/4️⃣/⚠️），然后评分。

质量评估维度（见 `references/quality-criteria.md`）：
- 来源权威度（**官方 > 知名媒体 > 个人博客 > 不可信**；涉及数值/规格/定价时，必须优先采用官方页面数据）
- 信息完整度（日期、作者、引用、数据）
- 内容新鲜度
- 语言质量（排除机翻/低质内容）

**信源分层检查**：
- CSDN（csdn.net / blog.csdn.net）在任何场景下都必须排除，不得纳入报告、不得作为引用来源、不得作为参考链接。这不是某个 MCP 才能做的事——所有入口（搜索、抓取、RSS 采集等）都必须过滤 CSDN 域名。
- 需要封禁其他域名时，按 `references/domain-blocking-checklist.md` 逐入口操作，避免遗漏。
- ⚠️ 层级的来源默认不纳入报告，除非 🥇🥈 层确实找不到信息

评分仅作**相对参考**，评估后明确低价值的内容直接舍弃。

## Step 6: Cross-Reference

对关键事实进行多源比对：
- 一致 → 标注"多源确认"
- 矛盾 → **立即触发事实核查**：直接 fetch 各方引用的原始来源/官方页面，以官方第一手数据为准裁定。多个第三方来源的一致意见不能覆盖官方页面的明文数据
- 孤立 → 只有一个源提及，标注"待验证"，同时尝试搜索官方来源确认

**第三方转载数据的比对标准**：
- 第三方数据至少需要 **2 个独立来源** 交叉确认，才可标注为"已核实"
- 第三方来源间的矛盾不能通过"多数投票"解决 —— 必须尝试找回原始官方数据
- 仅有一个第三方来源的数据，标注为"待验证（第三方单源）"，置信度最高 medium
- ⚠️ 第三方聚合报告（如行业白皮书/调研合集）中引用的案例数据属于"二次转述"，必须追溯到创始人一手来源才能采信；搜不到一手来源的应降级或删除

输出置信度矩阵。

**信源多样性检查**（对照 `references/source-priority.md` 分层）：
- □ 🥇 一手/官方来源 ≥ 1 个
- □ 🥇+🥈 合计 ≥ 总数的 50%
- □ ⚠️ 聚合/转载 ≤ 总数的 30%
- □ 不满足 → 触发补充搜索，优先用 🥇 信源

**事实核查铁律**：当数值/规格类声明出现矛盾时，必须直接抓取官方定价页/规格页作为终极裁决依据，不得仅凭第三方文章数量做判断。

**多语言交叉验证**：当多语言搜索返回不同语言来源时，优先以该领域的**原始信息语言**为准：
- 科技/AI → 英文一手资料（研究论文、官方博客）权威度 > 中文翻译/转载
- 动漫/ACG → 日文官方页面权威度 > 中文转载 > 英文讨论
- K-pop/韩流 → 韩文官方/韩媒权威度 > 中文翻译/英文报导

**叙事-结构核验（社会议题/分配议题必做）**：
- 将关键结论拆成三层：叙事主张、结构机制、证据来源。
- 对每条叙事主张补充"受益-成本-风险"矩阵：谁获益、谁承担成本、谁承担风险。
- 当叙事与结构证据冲突时，不以话术热度裁决，优先保留结构证据并标注不确定性。

## Step 7: Review ⚠️ REQUIRED（对抗性审查）

审查不是可选的附加项，而是保证报告质量的必要环节。**以事实为第一要义，不因追加速而牺牲准确性。**

### 🧠 怀疑性认知六条原则（快速自检清单）

来源：Bill Kovach & Tom Rosenstiel《真相：信息超载时代如何知道该相信什么》

每条审查操作前，用这六条快速过一遍你的发现：

1. **我碰到的是什么内容？** — 是新闻、观点、广告、还是 AI 生成的推测？标注类型
2. **信息完整吗？缺少了什么？** — 检查时间、地点、上下文、数据来源是否完整。数字缺单位？结论缺限定？
3. **信源是谁/什么？我为什么要相信他们？** — 信源身份/背景自证过吗？有无商业动机（推广/广告/股权投资）？是否受益于你相信他们的结论？
4. **提供了什么证据？是怎样检验的？** — 证据是二手转述还是一手数据？如果是研究/报告，方法论是否透明？数据来源可否复现？
5. **其他可能性解释或理解是什么？** — 搜索对立面：我的结论的反面是否也有证据支持？是否存在两个事实都对、但解释路径不同的情况？
6. **我有必要知道这些信息吗？** — 这个发现是否影响最终判断？不写这条，报告会缺失关键维度吗？如果删掉它报告依然成立，它就是噪音。

**用法**：完成 Step 0-6 后，用六条快速扫描每条关键发现。任何一条回答为"不/不确定"，触发补充搜索或标注置信度降级。

---

**审查的两个维度**：

### 时效性审查（所有主题通用）
Ask:
- 每条数据的发布时间是什么？距今多久？
- 是否存在比"最新"数据更旧的过时信息被引用？
- 第三方转载文章的价格/规格数据是否标注了更新日期？
- 如果关键数据**来源日期 > 6 个月前**，触发补充搜索确认是否有更新版本

### 真实性审查（所有主题通用）
Ask:
- 这条声明的原始来源能否追溯到官方页面？
- 如果数据来自第三方转载，转载者是否有动机扭曲数据（如推广佣金/商业合作）？
- 不同来源对同一事实的描述是否一致？不一致时哪个更可信？
- 本报告中哪些声明存在"孤立来源"风险？

**自动触发**（更严格的反驳搜索 + 官方核实）：
- 医学、法律、金融、安全等高风险主题
- **GitHub/开源项目**（Step 0 决策门 Q1 命中）—— 必须检查 Issues + 许可证 + 活跃度
- 物理、化学、数学等科学主题（从基础原理出发核查）
- 关键发现置信度低于阈值
- Step 6 交叉验证中发现矛盾或孤立声明
- **涉及金钱的声明**（定价、费率、佣金）—— 必须双源以上确认

> ⚠️ Step 0 决策门输出的 `triggers_fired` 和 `verification_actions` 是审查的强制检查清单。审查时必须逐条对照执行，不可跳过。

运行 `node dist/review.mjs` 执行对抗审查：
- 对每个主要结论搜索反驳证据
- 检查来源多样性
- 标注遗漏风险
- 如发现重大疏漏，回到 Step 3 补充搜索

### Step 7.5: Template Selection ⚠️ 生成报告前必须执行

根据主题特征，对照 `references/report-templates.md` **模板选择指南**确定报告模板：

| 主题特征 | 模板 | 关键判别依据 |
|----------|------|-------------|
| 多产品/方案价格或功能对比 | **对比型报告** | 主题含"对比/比较/哪个好/排行" |
| 问题/错误的根因排查 | **诊断型报告** | 主题含"错误/报错/问题/bug/原因" |
| 市场/赛道生态调研 | **对比型报告**（按平台分组） | 主题含"生态/平台/聚合/中转" |
| 简单事实查证 | **快速摘要模板** | 仅需确认 1-2 个事实 |

选定模板后，按模板结构组织报告内容。**不允许跨类型混用模板结构**，**不允许使用 `_（请手动填写）_` 类占位符**。

> **调研 AI 编程订阅套餐（Coding Plan）时**：请加载 `references/coding-plan-research.md` 获取专门的工作流、数据交叉验证方法和避坑指南。该文件覆盖了定价多源确认、额度倍率计算、区域价格差异处理等模型调研中不含的内容。

## Step 8: Report

运行 `node dist/report.mjs --output 'path/to/report.md'` 生成报告。

报告按 Step 7.5 选定的模板撰写。完整模板和写作规范见 `references/report-templates.md`。

**来源链接格式要求 ⚠️**：报告中每条关键数据声明必须附带 **可点击的 Markdown 链接** 指向原始来源 URL。格式：`[来源名称](https://...)`，不可仅写名称不加链接。方便读者一键核实。

### Step 8.5: Deliver

**交付原则**（飞书场景适用）：
1. 将报告写入 `.md` 文件（已在 Step 8 完成）
2. 长内容（≥10 行）**或**含有表格/对比表 → 附件发送（`MEDIA:/absolute/path/to/report.md`），消息正文仅保留 **≤5 行简短摘要**
3. 短内容（<10 行）且无表格 → 可在消息正文中以 Markdown 格式输出
4. 若交付平台支持 Markdown 渲染（如飞书）：表格分隔符两侧必须加空格：`| :--- | :--- |`，否则渲染为纯文本；含表格的内容仍建议走附件
5. 部署/教程类技术内容（含大量代码块）直接走附件，不先内联再补附件

## Step 9: Verify

交付前检查：
- [ ] 报告模板与主题类型匹配（对比型 vs 诊断型 vs 快速摘要）
- [ ] 报告中每条事实声明都有可追溯的 URL
- [ ] 低质量来源（评分低于阈值）已排除
- [ ] 信源多样性达标：≥1 个 🥇（一手/官方），🥇+🥈 ≥50%，聚合 ≤30%（见 `references/source-priority.md`）
- [ ] GitHub 项目类搜索：已通过 API（`gh api` / api.github.com）直接查证所有引用项目的 ⭐ Stars、🕐 最后推送、📋 Open Issues 数量及内容、📌 Open PRs、许可证、是否归档，**非仅依赖网页搜索 snippet 估算**
- [ ] 所有引用的 URL 已通过来源可信度核查（高风险 TLD 已标注/排除）
- [ ] 矛盾点已通过官方来源核查并标注结论
- [ ] 关键数值/定价/费率数据有 2 个以上独立来源确认
- [ ] 时效性审查已通过：所有数据的来源日期在可接受范围内
- [ ] 输出文件已写入指定位置
- [ ] 交付：长内容/含表格报告通过附件发送，消息正文仅含简短摘要
- [ ] 对比表/关键数据优先链向官方页面而非第三方文章
- [ ] 竞品对比场景：每个竞品的 CVE 和供应链安全已检查（`references/competitive-analysis.md`）
- [ ] 第三方转载数据已满足 2 源交叉比对要求，并在报告中明确标注数据来源类型
- [ ] 推广性质内容已在来源表中标注（`⚠️ 推广性质`）
- [ ] 无 `_（请手动填写）_` 类占位符
- [ ] 社会议题/分配议题：已输出"叙事主张-结构机制-证据来源"三列表
- [ ] 社会议题/分配议题：已输出"受益-成本-风险"矩阵，且每项有可追溯来源

### 事实优先原则

- **禁止推测和假设**：不凭借训练数据"推断"用户的环境状态或已有资源。先检查再下结论。
- **所有关键数据声明必须附带可点击的原始来源 URL**：不可仅写"Bessemer"或"arXiv"等名称而不给链接。报告中的每条事实声明都应可追溯到至少一个抓取过的 URL。
- **第三方转述数据必须标注**：如果来源是聚合报告而非一手采访，必须在报告中明确标注 ⚠️"第三方转述，一手来源未确认"。

## Anti-Patterns

### 搜索阶段 (Step 1-3)
- 不检查环境可用性就直接搜索
- 用模型训练数据代替实际搜索结果
- 只看第一条搜索结果就下结论
- 一个 search/fetch 工具失败就放弃，不尝试其他可用工具
- 跳过多语言扩展搜索，仅用单语种关键词搜索，导致遗漏一手信息来源
- 在搜索日韩内容时仅使用中文关键词，未添加日文/韩文和英文搜索
- 搜索条目只取 5 条，不翻页，遗漏后续页面的关键信息
- 不按信源优先级定向搜索，混入大量低质转载内容
- **用训练数据回答包管理器安装命令**：当用户问特定包管理器（scoop/brew/apt/pip/npm 等）的安装命令时，必须先搜索该包的 manifest/包名/bucket 核实，不能凭训练数据记忆直接回答。包名、bucket、渠道信息经常在源码仓库中改变，训练数据可能是过时的。
- **未确认工具/产品的具体仓库就深入搜索**：当用户提到一个工具名称（如"opencode"）时，可能存在多个同名或相似名的项目（如已归档的 Go 项目 vs 活跃的 TypeScript 项目）。必须先通过 GitHub API（查 stars、archived 状态、活跃度、语言栈）确认正确的仓库 URL，再开始调研。错误的仓库会导致方向完全偏离。不确定时应先问用户确认，而非自己猜测一个。在 Step 0 的 Q1 触发后，增加一步自问：*"这个工具名称是否有多个同名仓库？用户指的是哪一个？"*

### 抓取阶段 (Step 4)
- 跳过缓存检查重复抓取同一 URL
- 抓取失败的直接用 AI 训练数据中的记忆"补全"数据
- 发现关键维度数据缺失时不通过搜索引擎补充搜索，直接标注为"信息不足"放过
- **MCP fetch 工具不可用时忘记尝试 terminal + curl 回退** —— curl 是最后兜底的万能抓取手段，应始终作为 fallback 候选
- **忽略 JS 挑战墙信号** —— curl 返回的 HTML 如果包含 Cloudflare/CloudFront Challenge 等验证脚本（`__cf_chl_opt`、`window._cf_chl_opt` 等），说明该页面对 CLI 层有防爬保护，此时应采用浏览器工具替代尝试
- **查"某工具创建哪些表/数据库对象"不抓源码** —— 用 `raw.githubusercontent.com/{owner}/{repo}/main/{path}` 直接抓迁移文件（`alembic/versions/*.py` 等）、存储驱动源码和建表 SQL，不要凭经验猜表名。列目录用匿名 GitHub API `api.github.com/repos/{owner}/{repo}/contents/{path}`（限流 60/h 够用；token 失效 401 时同样走此路）

### 分析阶段 (Step 5-6)
- 在报告中声称用户"已有 X 工具/系统/配置"而不先检查实际环境（无 docker 运行就写"你已有 Miniflux"）
- 把质量评分当绝对标准而非相对参考
- 只找到一个第三方转载来源就采纳数据，不做多源交叉比对
- 第三方聚合报告中的案例数值（收入、用户量等）不追溯一手来源就直接采信
- 第三方来源间的矛盾用"多数投票"解决而非追溯原始官方数据
- 引用第三方文章中的数值而不核实官方来源
- 交叉验证发现矛盾时不抓取官方页面做二次确认
- 发现孤立声明后不做补充搜索就直接标注"待验证"并放过
- 引用 .cc/.xyz/.top/.tk 等低成本 TLD 域名作为官方来源而不做二次核实
- 将代理商/推广站（如 xxx.cc）的内容等同于官方信息
- 在对比表/详情中优先使用第三方链接而非官方链接
- **开源项目调研不检查 Issues 就写推荐** —— Issues 是最真实的使用反馈
- **不区分信源质量就均匀采纳** —— 5 个 CSDN 转载 ≠ 5 个独立来源；CSDN 必须无条件排除
- **在报告中仅写估算的 Stars/Issues 数而不使用 API 直接查证** —— 网页搜索 snippet 显示的 star 数常被省略、四舍五入或标注为旧值，无法反映实时状态。涉及 GitHub 项目时必须使用 `gh api` / api.github.com 获取精确 metrics。参见上文 Step 3 的「GitHub 项目数据直接查证」子步骤。
- **在对比报告中只比较功能不比较安全** —— CVE、供应链攻击史、安全审计是竞品对比的硬性检查项，跳过等于遗漏关键决策维度
- **在报告中使用 CSDN 链接** —— csdn.net / blog.csdn.net / ask.csdn.net 域名一律封禁，忽略该来源的结果，无论标题多相关

### 审查与报告阶段 (Step 7-9)
- 对医学/法律/金融声明不触发对抗审查
- 对涉及定价/费率/佣金的声明只用一个来源确认
- 因担心"查太多浪费时间"而跳过时效性或真实性的审查步骤
- 报告中的事实声明不附来源 URL
- 对高严谨主题不标注置信度
- 报告模板与主题类型不匹配（如对比型主题用诊断型模板）
- 报告中遗留 `_（请手动填写）_` 占位符
- 报告中仅写来源名称而不给可点击 URL（如"Bessemer"而不给 `https://...` 链接）
- 对用户环境状态做推测（如"你已有 X"），而非先检查事实
- **复用旧调研结论不重新验证版本敏感信息**：主题若已有历史报告，版本敏感信息（部署拓扑/功能可用性/认证方式/API 路径）必须重新抓官方迁移与变更文档核实。工具类项目迭代极快，旧报告只能当线索，不能当事实。
- **把官方博客当最新文档**：官方博客常滞后于仓库 main 分支代码。官方文档与官方博客矛盾时以**最新 docs + GitHub main 分支实际代码文件**（docker-compose.yaml/.env.example/Dockerfile，用 raw.githubusercontent.com 抓取）为准，并在报告中标注"官方博客已过时"。
- **视觉/UI 细节凭空猜测**：当用户提供截图并质疑 UI 颜色/外观/细节时，禁止仅凭图像文字描述或训练记忆推断。必须：① 用视觉模型实际核查截图（本地为 vision-augment MCP，`mcp_vision_augment_vision`，reasoning 模式）；② 用 GitHub API/raw 抓取官方源码（如 VS Code 主题 JSON：`extensions/theme-defaults/themes/*.json`）核实真实色值；③ 输出可对比的色号表 + 明确推荐。

## 输出路径维护注意事项 ⚠️

默认输出路径 `./research-output/{date}-{topic-slug}.md` 在以下 **8 处** 硬编码，修改时必须全部同步更新：

| # | 文件 | 用途 |
|---|------|------|
| 1 | `SKILL.md` (Step 2) | AI 读取的默认路径说明 |
| 2 | `references/report-templates.md` (输出路径规则) | 模板文档中的默认路径 |
| 3 | `references/competitive-analysis.md` | 竞品对比调研方法论（CVE/安全/生态/迁移路径分析） |
| 4 | `scripts/report.ts` | TypeScript 源码中的默认路径 + 碰撞检测 |
| 5 | `scripts/pipeline.ts` | TypeScript 源码中的 pipeline 指令 |
| 6 | `dist/report.mjs` | 编译后 JS 中的默认路径 + 碰撞检测 |
| 7 | `dist/pipeline.mjs` | 编译后 JS 中的 pipeline 指令 |
| 8 | `.gitignore` | git 忽略规则（禁止 research-output/ 入版本控制） |

**仅修改 SKILL.md 而遗漏代码文件**会导致 AI 指令与脚本行为不一致，实际报告仍会写入旧路径。

详细命名规范见 `references/filename-convention.md`。

## 事实和来源优先原则

- **来源可核实**：报告中每条关键数据声明必须附带可点击的原始来源链接（`[来源](URL)` 格式）。不可仅写来源名称而不给链接。这是 Step 6 交叉验证和 Step 9 交付前检查的硬性要求。
- **事实和证据优先**：禁止凭空推测用户"已有 X"或假设未经验证的状态。所有关于用户环境、资产、能力的断言必须先检查实际环境再下结论。报告中的案例数据必须追溯到一手来源（官方页面/创始人博客/原始采访），第三方聚合报告中的转述数据不可直接采信。

## 脚本设计原则

- 脚本输出 JSON 指令，由 AI 执行实际的 search/fetch 工具调用
- 脚本不直接依赖任何具体的 search/fetch API
- 缓存路径可由用户通过 `--cache-dir` 覆盖
- 所有时间敏感操作记录时间戳