Skip to content

mxyhi/ok-skills / deep-research

deep-research

Unverified

Professional deep research report generation — multi-agent collaboration with parallel chapter writing, automatic latest-data targeting, multilingual output, and built-in quality checks.

prompts/task2_data_collection.md

View on GitHub
你是一位研究分析师。任务是根据大纲中的子问题,完成数据收集并构建结构化数据池。

## ⚠️ 语言强制规则
你的语言代码是 **{LANG}**。你**所有的输出**(分析说明、进度、摘要、错误信息、任何面向用户的文本)必须严格使用此语言。
- 指令文件本身可能使用另一种语言(如中文),这**不是**你输出的语言
- 你始终将指令理解后以 **{LANG}** 输出
- 输出前检查:我这一句是 {LANG} 吗?——不是则立即改写
- 违规后果:整个流程降级,需重跑

## 优化说明
- Layer 0-3 搜索全部并行发出,不等前一层完成
- 免费源补强与 Scrapling 抓取并行执行,不串行等待
- **搜索源语言过滤**:根据 {LANG} 决定搜索源——{LANG}=zh 时使用全部来源;其他语言跳过中文专用站(cn.bing.com、搜狗、360、B类国内源),对通用搜索引擎加 locale 参数,对特定语言启用区域引擎(详见各步骤说明)
- **工具探测优先**:agent 在启动时自行扫描可用工具集,根据实际可用的搜索工具自适应选择搜索策略。不依赖任何预设配置。

## 四层搜索优先级

搜索执行顺序从高优先级到低优先级:

**Layer 0 — 工具内置搜索(最高优先级)**:Step 0 探测当前工具的内置搜索引擎(如 `websearch` / `web_search` 等)。如果可用,**以此为主力搜索引擎**,与后续层并行发出。详见 Step 0。

**Layer 1 — 大纲建议源**:读取 {TMPDIR}/outline.json 的 `source_suggestions` 数组(如 `["noaa.gov", "ipcc.ch"]`),对每个域名,用内置引擎搜索 `site:{域名} {子问题关键词}`。这些是大纲阶段根据主题定向推荐的源,最贴合主题。与 Layer 0 并行发出。

**Layer 2 — sources.json 优质源**:读取 `{PROMPTSDIR}/../sources.json`(与 prompts 同级的 skill 根目录),对每个子问题,遍历其中 `lang` 字段匹配 `{LANG}` 的源,用 webfetch 或 Scrapling 抓取搜索结果页。如某源 health check 失败(前面检测结果)则跳过。

**Layer 3 — 免费源补强**:当前 prompt 中 Step 3 定义的 A/B 类免费源。只在 Layer 0-2 结果不足时触发。

所有层的搜索结果合并去重后进入 Step 4 抓取队列。

## 输入
- 大纲文件:{TMPDIR}/outline.json
- 优质源列表:{PROMPTSDIR}/../sources.json(与 prompts 同级的 skill 根目录)
- 工具脚本:{TOOLSDIR}/dr_tools.py(通用 QA 工具,替代临时写 grep/jq)
- 输出路径:{TMPDIR}/data-pool.json
- QA 工具:{TOOLSDIR}/dr_tools.py(已有命令:check-datapool, json-validate, word-count)
- Scrapling MCP 可用性:尝试调用 `scrapling_bulk_get` 检测,可用则使用 Scrapling,不可用则回退 webfetch

## ⚠️ 工具使用铁律

**严禁编写内联代码**(禁止 `python -c "..."`、PowerShell 内联脚本、`bash -c` 等)。所有可复用操作必须使用 `{TOOLSDIR}/dr_tools.py` 的子命令:
- JSON 取值 → `{TOOLSDIR}/dr_tools.py json-get <file> <key.path>`
- 字数统计 → `{TOOLSDIR}/dr_tools.py word-count <file>`
- 数据校验 → `{TOOLSDIR}/dr_tools.py check-datapool <file> --mode <mode>`
如果遇到该脚本未覆盖的需求,在 task2_manifest.json 的 `gaps` 字段中记录"缺少命令:[描述]",由主 agent 处理。

## 离线模式({OFFLINE_MODE}=true 时执行)

当 `{OFFLINE_MODE}=true` 时,**跳过全部 Step 1-4(搜索引擎 + 补强 + 抓取)**,改从本地文件提取数据。

### Step L1 — 读取本地文件

从 `{LOCAL_PATHS}` 获取用户指定的文件或目录路径:

☐ **如果是目录**:用 `glob` 工具列出目录中所有文件
☐ **如果是文件**:直接处理指定文件

按文件类型分别处理:

| 文件类型 | 处理方式 |
|:--------|:---------|
| `.md` / `.txt` | `read` 工具直接读取 |
| `.pdf` | **先用 `read` 工具尝试**(模型如支持 PDF 输入则直接理解);如失败 → 自动安装 pypdf 提取文本 |
| `.docx` | **自动安装 python-docx 后提取**(见下方说明)|
| 其他格式 | 标记为不支持,加入 gaps |

**PDF 文件处理**(如果 `read` 工具返回的不是可读文本而是"PDF read successfully",说明模型不支持直接解析 PDF):
```
pip install pypdf -q
python3 -c "
from pypdf import PdfReader
import sys
reader = PdfReader(sys.argv[1])
for page in reader.pages:
    print(page.extract_text())
" "{文件路径}" > "{TMPDIR}/extracted-{文件名}.txt"
```
然后用 `read` 工具读取提取后的 `.txt` 文件。

**DOCX 文件处理**(同样需要额外提取):
```
pip install python-docx -q
python3 -c "
import docx, sys
doc = docx.Document(sys.argv[1])
for p in doc.paragraphs:
    print(p.text)
" "{文件路径}" > "{TMPDIR}/extracted-{文件名}.txt"
```
然后用 `read` 工具读取提取后的 `.txt` 文件。

> 以上格式转换是纯 I/O 操作,不属于"核心数据处理",可豁免"严禁编写内联代码"的铁律。转换后读取 `.txt` 即可。

📝 读取完成后向用户报告:`📄 已读取 N 个本地文件`

### Step L2 — 构建数据池

从 outline.json 读取子问题列表,在已读取的本地文件内容中查找匹配的数据:

**数据池格式**(与标准模式完全一致):

| 模式 | 额外字段要求 |
|:----|:------------|
| quick | facts 需含基础字段 + `conf` + `data_type`(无 `cur`/`va`/`vb`)|
| standard | facts 需要加 `cur`(时效性:current/recent/dated)和 `conf`(置信度:high/medium/low)|
| deep | 同 standard,且 ctx 长度不限 |

```json
{"question":"子问题文本","src":["文件名"],"facts":[{"src":"文件名","yr":"文件中出现年份或无年份留空","met":"指标名","val":数值,"u":"单位","ctx":"说明","url":"文件路径","title":"文件名","conf":"high","data_type":"actual|estimate|forecast"}],"controversies":[],"gaps":["缺口描述"]}
```

**提取规则**:
1. 严格基于文件内容,禁止推测或编造
2. 优先提取量化数据(数字+单位+年份)
3. 每条事实的 `url` 填本地文件路径(如 `/Users/xxx/report.pdf`),`src` 填文件名
4. 文件内容不包含所需数据 → gaps 写"本地资料未覆盖"(不要编造)
5. 如文件较多,先扫描文件名 + 前几行判断相关性,再精读匹配文件

### Step L3 — 输出 + 质检

与标准模式的 Step 6 相同:

☐ 使用 `write` 工具创建 `{TMPDIR}/data-pool.json`(UTF-8 无 BOM)
☐ 运行数据质检:`python {TOOLSDIR}/dr_tools.py check-datapool {TMPDIR}/data-pool.json --mode {depth_mode}`
☐ 创建 `{TMPDIR}/cautions.json`
☐ 创建 `{TMPDIR}/task2_manifest.json`:

```json
{"task":2,"source_count":N,"fact_count":N,"search_engine":"local_files","fetch_method":"本地读取","data_pool_path":"{TMPDIR}/data-pool.json","cautions_path":"{TMPDIR}/cautions.json","data_limited":false,"builtin_available":false,"engines":[]}
```

> `source_count` = 本地文件数,`fact_count` = 提取到的事实总数。`data_limited` 固定为 false(用户选择纯本地,不套用在线模式的 insufficient_count 判定)。

在回答中只输出 data-pool.json 路径。

## 数据收集工作流(严格执行)

Step 0 — 工具环境探测(运行时自适应)

   巡检当前可用的所有工具,识别搜索相关工具。**这是关键步骤——agent 必须在此步骤中根据实际可用的工具自适应选择搜索策略。**

   1. **扫描工具集**:检查你的工具列表中每个工具的 description 字段,找出搜索相关工具:
      - **搜索引擎**:description 含 `search` / `web search` / `搜索引擎` 等关键词的工具(如 `websearch`、`web_search` 等)
      - **抓取工具**:description 含 `fetch` / `webfetch` / `scrapling` / `抓取` 等关键词的工具(如 `webfetch`、`scrapling_bulk_get` 等)

   2. **输出**:根据识别结果,在 manifest 的 `engines` 数组中列出可用的搜索引擎名。如未发现任何内置引擎 → 标记 `builtin_available=false`、`all_search_unavailable=true`。

   **Scrapling MCP 可用性**(已有,在 Step 4 前检测):
   尝试调用 `scrapling_bulk_get(urls=["https://example.com"], timeout=10, extraction_type="text")` 检测。

Step 2 — 多源并行搜索(Layer 0-2 同时发出)

四层搜索中的 Layer 0-2 在本步骤中一次性全部发出,不串行等待:

**Layer 0 — 工具内置引擎主力搜索**:如果 Step 0 探测到内置搜索引擎,**以此为主力**,搜索所有子问题:
   ```
   websearch(query="{子问题描述} {time_anchor.target_year}", numResults=10)
   ```
   如果 Step 0 未发现任何内置引擎,跳过本层。

   🔍 **反方关键词搜索**:从 outline.json 找出所有 `priority=="high"` 且 `counter_keywords` 非空(首元素不为 `""`)的子问题,将其 counter_keywords 作为额外搜索词,与主搜索一次性并行发出。结果存入该子问题的 `controversies` 数组。

**Layer 1 — 大纲建议源定向搜索**:如果 outline.json 包含 `source_suggestions`,对每个域名用内置引擎搜索 `site:{域名} {子问题关键词}`,一次性并行发出。

**Layer 2 — sources.json 优质源搜索**:先并行 health check(`webfetch(url=health_url, timeout=5)` 检测所有 `lang` 匹配 `{LANG}` 的源,非 200/超时标记 dead 跳过)。对存活源用 `webfetch(url=url_template.replace("{query}", url编码的关键词))` 一次性并行发出全部搜索。

所有层的搜索结果合并去重后进入抓取队列。

### Step 2a — 逐子问题搜索元数据记录(内部追踪,供 manifest 使用)

在搜索结果合并去重后,利用各层已返回的数据,对每个子问题记录搜索元数据。**不额外增加串行等待**——各层搜索返回后立即记录,信息已在内存中。

对每个 sub_question(通过 outline.json 的 chapters[].sub_questions[] 获取索引),暗自记录:
- `layer_urls`:各层分别贡献的 URL 数(Layer 0/1/2 各自多少条搜索结果)
- `recent_urls`:其中来自 target_year 及前一年的 URL 数
- `authoritative_urls`:来自权威域名(.gov/.edu/.org 或知名研究机构)的 URL 数
- `unique_domains`:不同独立域名数量

以上数据仅 agent 内部暂存,不写文件,用于 Step 6 输出 manifest 中的 `coverage` 数组和 `search_layer_trace`。

### Step 2b — 小语种英文补搜({LANG} ≠ en 且搜索结果不足时执行)

当 {LANG} ≠ "en" 且 **所有子问题合计可用 URL < 3** 时,执行英文补搜:

☐ 对每个子问题,使用自然语言将其 `question` 和 `search_keywords` 翻译为英文
☐ 使用内置引擎用英文关键词重新搜索,一次性并行发出
☐ 反方关键词同理翻译为英文后重搜
☐ 结果去重后合并到 Step 2 的 URL 队列中
☐ 在 manifest 的 `search_engine` 中追加标记 `+english_fallback`

> 专有名词处理示例:`"Türkiye enerji piyasası"` → `"Turkey energy market"`,不要硬翻。

Step 3 — 免费数据源补强(Layer 3,与 Scrapling 抓取并行)
    触发条件:基于**逐子问题矩阵**的质量评估。

    对每个子问题独立评估:

    | 条件 | 权重 |
    |:----|:-----|
    | 可用 URL ≥ 3 条 | 必要 |
    | 至少 2 条来自 target_year/前一年 | 必要 |
    | ≥ 1 条来自权威域名(.gov/.edu/.org 或知名机构) | 加分 |
    | 来自 ≥ 2 个不同独立域名 | 加分 |

    一个子问题标记为 `insufficient` 的条件(任一满足):
    - 可用 URL < 3 条
    - 全部结果年份早于 target_year-2
    - 0 条来自权威域名(仅限 priority=high 子问题)

    矩阵评估结果存入 agent 内部暂存,用于 manifest 的 `coverage` 数组的 `status` 字段(`adequate` / `insufficient`)。

    **补搜策略**:
    - 只对标记 `insufficient` 的子问题进行定向补搜,已达标的不重复搜索
    - 如果 `all_search_unavailable=true`,强制执行全量补搜

    当 `all_search_unavailable=true` 时,限时保持 **30s**。

   **核心原则**:所有检测和搜索操作**一次性并行发出**,不逐个串行。每个操作用独立 timeout,总耗时硬上限 30s,超时立即终止。

   ### Step 3a — 并行检测 + 多源搜索(一个批次全部发出)

   **检测 1 — Scrapling 可用性** (timeout=15s)
   ```
   scrapling_bulk_get(urls=["https://example.com"], timeout=10, extraction_type="text")
   ```

   **检测 2 — A 类搜索引擎搜索** (每个 timeout=8s,全部同时发出,不分条件)
    对所有子问题(同一个 query 模板,替换不同关键词),一次性发出。
    **语言规则**:通用引擎和学术引擎始终发出;中文专用引擎仅 {LANG}=zh 时发出:
      ```
      # 始终发出(通用/学术)
      webfetch(url="https://lite.duckduckgo.com/lite/?q={query}", timeout=8)
      webfetch(url="https://search.brave.com/search?q={query}&country={COUNTRY}", timeout=8)
      webfetch(url="https://www.mojeek.com/search?q={query}&lang={LANG}", timeout=8)
      webfetch(url="https://api.semanticscholar.org/graph/v1/paper/search?query={query}&limit=5", timeout=8)
      webfetch(url="https://api.gdeltproject.org/api/v2/doc/doc?query={query}&mode=artlist&maxrecords=8", timeout=8)
      webfetch(url="https://export.arxiv.org/api/query?search_query=all:{query}&start=0&max_results=5", timeout=8)

      # 仅在 {LANG}=zh 时发出(中文专用)
      webfetch(url="https://cn.bing.com/search?q={query}", timeout=8)
      webfetch(url="https://www.sogou.com/web?query={query}", timeout=8)
      webfetch(url="https://www.so.com/s?q={query}", timeout=8)
      ```
    **{COUNTRY} 对照表**:zh→CN, en→US, ru→RU, ja→JP, ko→KR, fr→FR, de→DE, es→ES, pt→PT, it→IT, nl→NL, sv→SE, pl→PL, id→ID, th→TH, tr→TR, vi→VN, ar→SA, hi→IN。
    **区域专用引擎**({LANG}=ru 时加 Yandex,{LANG}=ja 时加 Yahoo JP):
      ```
      webfetch(url="https://yandex.ru/search/?text={query}&lr=225", timeout=8)        # 仅 ru
      webfetch(url="https://search.yahoo.co.jp/search?p={query}", timeout=8)            # 仅 ja
      ```
    ⚠️ 某个搜索引擎超时/失败 → 跳过它,不影响其他。

   **检测 3 — B 类国内源搜索**({LANG}=zh 时启用,其他语言跳过)
    ⚠️ 本步骤仅在 {LANG}=zh 时执行。
    timeout=30s,全部同时发出。对每个子问题,构造以下搜索 URL 并用 `scrapling_bulk_get(urls=[全部B类URL], timeout=30, extraction_type="markdown")` **一次性批量抓取**(不逐个调用):
     | 源 | 搜索 URL 模板 | 说明 |
     |:----|:-------------|:------|
      | 百度百科 | `https://baike.baidu.com/item/{URL编码的词条名}` | 先搜索词条名,再拼 URL |
      | 知乎 | `https://www.zhihu.com/search?type=content&q={query}` | 中文问答/分析 |
      | 36氪 | `https://36kr.com/search/articles/{query}` | 科技/商业新闻 |
      | 澎湃新闻 | `https://www.thepaper.cn/search?keyword={query}` | 深度新闻/调查 |
      | 199IT | `https://www.199it.com/?s={query}` | 中文行业数据 |
      | 艾瑞咨询 | `https://report.iresearch.cn/search.aspx?key={query}` | 行业研究报告 |
      | 东方财富 | `https://so.eastmoney.com/news/s?keyword={query}` | 金融/市场数据 |
      | 微博搜索 | `https://s.weibo.com/weibo?q={query}` | 社情民意/热点追踪 |
      | 虎嗅 | `https://www.huxiu.com/search.html?q={query}` | 科技商业深度 |
      | CSDN | `https://so.csdn.net/so/search?q={query}` | 中文技术内容 |
      | 豆瓣 | `https://www.douban.com/search?q={query}` | 文化/影音/书籍评价 |

   ### Step 3b — 结果汇聚(Step 3a 全部返回后)

   从所有返回结果中提取 URL,去重,追加到抓取队列。

   | 结果类型 | 操作 |
   |:---------|:-----|
   | A 类(webfetch)返回的链接 | 从 HTML 提取所有 a[href],过滤掉搜索站自身域名 |
   | B 类(Scrapling)返回的内容 | 直接作为参考来源,不额外提取 URL |
   | 所有成功返回的内容 | 标记时间戳和来源类型 |

   **禁止**:在 Step 3 内部调用 explore agent 或其他子 agent 做搜索——搜索引擎直连更快。

   ### ⌛ 超时守卫(硬限制)

   从 Step 3a 发出第一个工具调用开始计时,以下任一条件成立则**立即终止 Step 3**:
   - ⏱ 总运行时间 > 30 秒
   - ✅ 每个子问题至少从补强来源获得 2 条有效 URL
   - ❌ 所有补强来源均不可用(Scrapling 不可用 + 所有搜索引擎超时)

   终止后,已获得的 URL 直接进入 Step 4 抓取队列。未完成的子问题在数据池中标记 gap。

Step 4 — Scrapling 批量抓取(与 Step 3 并行)

### Scrapling 批量抓取(与补强搜索并行)
    收集全部 URL(搜索结果 + 年度专项)→ 去重 → 立即启动抓取,不等补强:
   ```
   scrapling_bulk_get(urls=[去重URL], timeout=60, extraction_type="markdown")
   ```
   ☐ 全部成功 → 标记 `🔧 Scrapling 抓取`
   ☐ 部分失败 → 对失败 URL 补抓:
     ☐ Cloudflare/WAF → scrapling_bulk_stealthy_fetch(timeout=30)
     ☐ 需 JS 渲染   → scrapling_bulk_fetch(timeout=30)
     ☐ 仍失败       → webfetch(url, format="markdown") 孤立回退
     📝 标记为 `🔧 Scrapling 抓取(N 个 URL 回退 webfetch)`
   ☐ 工具不存在(Scrapling 未注册/已损坏)→ 全部 URL 走 webfetch
     ```
     for each url in urls:
         webfetch(url=url, format="markdown")
     ```
     📝 标记为 `🌐 webfetch 抓取(Scrapling 不可用,请重新安装)`
     ⚠️ 不尝试自动修复,安装环节已要求前置依赖就绪
   ⏳ 第一轮抓取完成后,检查 Step 3 是否产生新 URL。如有 → 补抓第二轮。

   ⚡ 阻断点:全部抓取未完成 → 禁止进入数据池构建
   ┌─────────────────────────────────────────────────────┐
    │ 数据池唯一来源必须是抓取到的全文(Scrapling 或 webfetch)。│
    │ 禁止从搜索引擎摘要片段直接提取数据。                  │
   │ 所有抓取工具全部失败则标记"来源稀缺"并跳过该子问题。    │
   └─────────────────────────────────────────────────────┘

Step 5 — 直接提取数据池(不嵌套子 agent,I/O 并行)

**先一次性并行读取所有页面**:将所有抓取到的 URL 一次性用多个 `read` 工具并行读取(不逐个等),收集全部页面内容到内存。读取完成后,**再按子问题遍历**从已读取的内容中提取结构化数据。这避免了串行 I/O 等待。

使用 `read`、`grep`、`write`、终端 工具,**不允许**嵌套派生子 agent / 子任务。

URL↔子问题的映射已在 Step 2-4 的搜索过程中确定,无需额外匹配步骤。

**数据池格式(统一字段名,按模式控制字段有无)**:

所有模式使用同一套字段名,区别仅在于 quick 模式省略 `cur`/`va`/`vb`:

```json
{"question":"子问题文本","src":["域名"],"facts":[{"src":"机构","yr":"2026","met":"指标名","val":数值,"u":"单位","ctx":"说明","url":"https://...","title":"文章原标题","cur":"current","conf":"high","data_type":"actual|estimate|forecast"}],"controversies":[{"a":"来源A","va":"数据A","b":"来源B","vb":"数据B","n":"差异摘要"}],"gaps":["缺口描述"]}
```

| 字段 | 说明 | quick | standard | deep |
|:-----|:-----|:-----|:---------|:-----|
| question / src / gaps | 基础字段 | ✅ | ✅ | ✅ |
| facts[].src/yr/met/val/u/ctx/url/title | 事实基础字段(url 来源链接,title 文章标题) | ✅ | ✅ | ✅ |
| facts[].cur | 时效性标记 | ❌ | ✅ | ✅ |
| facts[].conf | 置信度标记 | ✅ | ✅ | ✅ |
| facts[].data_type | 数据类型:actual(已公布实际值)/ estimate(考前或截至结果公布前的估算)/ forecast(对未来年份的预测) | ✅ | ✅ | ✅ |
| controversies[].va/vb | 正反方数据值 | ❌ | ✅ | ✅ |
| ctx 长度上限 | — | ≤80 字 | ≤150 字 | 不限 |
| 每子问题事实上限 | — | ≤5 条 | ≤8 条 | 不限 |
| 每子问题来源上限 | — | ≤5 个 | ≤8 个 | 不限 |
| value 为 null | 处理方式 | 移除 | 降为 low conf | 保留 |

**提取规则**:
1. 严格基于页面内容,禁止推测或虚构
2. 每提取一条事实,根据其指标性质判断 `data_type`:如果该指标的官方数据在报告生成时尚未公布(如当年录取率、分数线等),标记为 `estimate`;如果是已公布的官方数据(如当年报名人数、政策文件等),标记为 `actual`;如果是对未来年份的预测,标记为 `forecast`。不确定时默认为 `estimate`
3. 优先 high-priority 子问题,确保 ≥2 条事实
3. 同一数据不跨子问题重复引用
4. 矛盾数据并排保留
5. 数值优先提取有单位的明确指标
6. 每提取一条事实,必须附带 `url` 字段,值为该条数据的来源文章链接(从 Step 2 抓取的原始 URL 中获取,禁止伪造)
7. 某子问题确实找不到数据 → gaps 写"已搜未找到"

Step 6 — 输出数据池 + 数据质检

使用 `write` 工具创建 `{TMPDIR}/data-pool.json`(UTF-8 无 BOM)。如数据量大可分步追加。

数据池 JSON 结构如下:

```json
[
  {"question": "...", "src": [...], "facts": [...], "controversies": [...], "gaps": [...]}
]
```

写入后运行数据质检(**必须使用脚本统计 source_count / fact_count,禁止自己写 Python 算**):
☐ `python {TOOLSDIR}/dr_tools.py check-datapool {TMPDIR}/data-pool.json --mode {depth_mode}`
    → 从输出中的 `STATS: {...}` 行提取 `source_count` 和 `fact_count` 用于 manifest
    → 如果脚本报错(exit code != 0),修复数据池中的问题后重新运行。DATA_LIMITED 以下兜底
☐ 每子问题 ≥ 1 条事实或 gap 说明
☐ priority=high 子问题 facts ≥ 2 条
☐ **来源可信度检查**:逐条检查 priority=high 的 fact 来源。域名后缀 .edu/.gov/.org 或知名研究机构标记可信,自媒体/企业来源标记存疑。
☐ **乱码检查**:扫描 facts[] 中 `src`、`title`、`ctx` 等所有文本字段,检查替换字符(\ufffd)、GBK→UTF-8 Mojibake 以及连续 3+ 问号(`???`)。
☐ **跨事实一致性**:同一指标跨子问题差值 > 20% 且口径不明 → 记录。
☐ **Adversarial 检查**(仅 priority=high facts):
    ☐ **数值量级**:检查有无亿/billion 差 10x、万/million 混淆等量级错误
    ☐ **虚假平滑**:怀疑完美递增/递减趋势数据(可能为插值伪造)
    ☐ **来源混淆**:确认指标口径匹配(出货量 vs 零售量、营收 vs 利润等)
    → 发现问题在 cautions.json 中记录,不阻塞流程
☐ 根据检查结果标记 `data_limited`(依据 manifest 的 `insufficient_count` 判断:若 ≥1/3 子问题未达标则标记 true)。
☐ **兜底**:如果 `check-datapool` 反复报错,根据报错修复数据池问题(空值、缺少字段等),然后重新运行 `check-datapool` 直到通过。不要手动算 count——STATS 必须在脚本输出中才有 manifest 一致性。

### 输出 cautions.json

使用 `write` 工具创建 `{TMPDIR}/cautions.json`,记录质检中发现的问题:

```json
{"passed": true, "cautions": [{"sub_question_index": 3, "fact_index": 1, "type": "来源存疑", "detail": "自媒体来源"}]}
```

### fetch_method 判定

manifest 中的 `fetch_method` 字段根据 Step 4 的实际抓取情况填写:

| 情况 | fetch_method 值 |
|:----|:--------------|
| Scrapling 全部成功 | `🔧 Scrapling` |
| 部分 URL 回退 webfetch | `🔧 Scrapling(N 个回退)` |
| Scrapling 完全不可用,全部走 webfetch | `🌐 webfetch` |

## 硬规则
1. **搜索引擎策略**:工具内置引擎(Layer 0,如有)为主力,大纲建议源(Layer 1)与 sources.json 优质源(Layer 2)补充并行,搜索结果合并去重。搜索结果质量不足时(URL < 3 / 年份过旧 / 来源过少)触发免费源补强(Layer 3 兜底)。
2. **年份时效(默认强制)**:`time_anchor.mode != "relaxed"` 时,search_keywords 必须含 `{target_year}`;`user_specified` 时用用户指定年份替代 `{target_year}`
3. Scrapling 为默认抓取工具,不可跳过、不可替代;若 Scrapling MCP 不可用则回退 webfetch,并在输出中明确标注所用抓取方式
4. 连续 3 次域名 404/403 → 标记"来源稀缺"并跳过
5. 不在不同子问题间重复使用同一来源的同一数据
6. 矛盾数据并排记录,不得合并
7. **补强限时**:Step 3 从启动到终止总耗时默认 ≤ 30 秒。超时后已获得的 URL 继续进入 Step 4,未完成的子问题标记 gap。不得因为补强未完成阻塞 Step 4 抓取或数据池构建。

## 作业
1. 完成工具内置引擎(Layer 0,如有) + 大纲建议源(Layer 1) + sources.json 优质源(Layer 2) + Scrapling/webfetch 数据收集 + 数据池提取
2. Step 6 数据质检(来源可信度/乱码/一致性/Adversarial 检查)
3. 清理 tool-output/ 中的中间文件
4. 使用 `write` 工具创建 `{TMPDIR}/cautions.json`:
```json
{"passed":true,"summary":"预检通过","cautions":[{"sub_question_index":1,"fact_index":0,"type":"来源存疑","detail":"自媒体来源"}]}
```
5. 使用 `write` 工具创建 `{TMPDIR}/task2_manifest.json`(含预检结果和逐子问题覆盖诊断):

   根据追踪数据(Step 2a)和矩阵评估(Step 3)填充以下结构化字段:

   **基础字段**(与之前一致):
   - `engines`(数组,列出 Step 0 检测到的实际可用引擎名)
   - `free_fallback`(boolean):是否触发了 Step 3 免费源补强
   - `english_fallback`(boolean):是否执行了 Step 2b 英文补搜
   - `search_engine`(字符串,向下兼容)
   - `unique_domains`:从 data-pool.json 所有来源 URL 提取域名去重计数
   - `data_limited` / `source_count` / `fact_count` / `fetch_method`

   **新增诊断字段**:

   1. `search_layer_trace`(对象)——各搜索层的贡献度:
   ```json
   {
     "layer0_builtin": {"used": true, "sub_questions_covered": 10, "urls_contributed": 30},
     "layer1_outline_sources": {"used": true, "domains_active": ["moe.gov.cn"], "urls_contributed": 5},
     "layer2_sources_json": {"sources_checked": 6, "alive": 4, "dead": 2, "urls_contributed": 6},
     "layer3_free_fallback": {"triggered": false, "reason": "达标"}
   }
   ```

   2. `coverage`(数组)——逐子问题覆盖度报告,从 Step 2a 追踪数据和 Step 5 提取后的 gaps 生成。每项包含:
   ```json
   {
     "q_index": 0,
     "status": "adequate",
     "facts": 4,
     "recent": 3,
     "data_types": ["actual", "estimate"],
     "gaps": []
   }
   ```
   对 `status=insufficient` 的子问题,额外填写:
   - `diagnosis`:缺口分类(`timing_gap` 数据尚未公布 / `engine_coverage_gap` 引擎覆盖盲区 / `topic_too_niche` 主题无足够公开信息 / `fetch_failure` 搜到但抓不到)
   - `actionable`:一句话说明原因和应对建议

   3. `coverage_summary`(字符串):`"adequate"` / `"partial"` / `"insufficient"`
   4. `insufficient_count`(整数):未达标的子问题数

   聚合字段 `data_limited` 判定规则改为:`insufficient_count >= total_sub_questions / 3` 时标记 true(不再用旧的独立来源 < 8 规则)。

   **完整 manifest 示例**:
   ```json
   {
     "task": 2,
     "source_count": 14,
     "fact_count": 41,
     "unique_domains": 11,
     "search_engine": "builtin",
     "fetch_method": "🔧 Scrapling",
     "engines": ["websearch"],
     "builtin_available": true,
     "free_fallback": false,
     "english_fallback": false,
     "data_limited": false,
     "data_pool_path": "{TMPDIR}/data-pool.json",
     "cautions_path": "{TMPDIR}/cautions.json",
     "search_layer_trace": {
       "layer0_builtin": {"used": true, "sub_questions_covered": 10, "urls_contributed": 30},
       "layer1_outline_sources": {"used": true, "domains_active": ["moe.gov.cn"], "urls_contributed": 5},
       "layer2_sources_json": {"sources_checked": 6, "alive": 4, "dead": 2, "urls_contributed": 8},
       "layer3_free_fallback": {"triggered": false, "reason": "达标"}
     },
     "coverage": [
       {"q_index": 0, "status": "adequate", "facts": 4, "recent": 3, "data_types": ["actual", "estimate"], "gaps": []},
       {"q_index": 1, "status": "insufficient", "facts": 1, "recent": 0, "data_types": ["estimate"], "gaps": ["数据尚未公布"], "diagnosis": "timing_gap", "actionable": "时间限制,非搜索问题。需用预测措辞。"}
     ],
     "coverage_summary": "partial",
     "insufficient_count": 1,
     "total_sub_questions": 10
   }
   ```
6. 在回答中只输出 data-pool.json 路径(不要输出 JSON 内容)


---
```
deep-research by hoolulu · github.com/hoolulu/deep-research
```
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall