deep-research
"Professional deep research report generation — multi-agent collaboration with parallel chapter writing, automatic latest-data targeting, multilingual output, and built-in quality checks."
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/hoolulu--deep-research)HTML
<a href="/listings/hoolulu--deep-research"><img src="/api/listings/hoolulu--deep-research/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
deep-research is an **all-platform** skill: one codebase, drop it into any AI tool that supports skill/command mechanisms — no per-tool rewrite needed.
🧠 Method 1: AI Auto-Install (Recommended)
Copy this prompt into your AI tool's chat, the AI will do everything automatically:
Please read the https://github.com/hoolulu/deep-research project and follow the documentation to: 1. Install prerequisites (determine method based on Scrapling docs and your OS) 2. Register the Scrapling MCP Server, verify it works after restart 3. Register the /research and /research-update entry points for your current tool Confirm each step, then read VERSION and summarize the installation status.
The AI reads the docs → understands your system → installs step by step → verifies. No manual commands needed.
📋 Method 2: Manual Entry Registration
Each tool registers skills/commands differently — drop the whole project into the right directory (common tools below):
| Tool | skill/entry location | Command form | |------|----------------------|--------------| | OpenCode | `~/.opencode/skills/deep-research/` | `/research`, `/research-update` (included in `command/`) | | Codex CLI | skill directory, `command/` files included | `/research`, `/research-update` | | Claude Code | `~/.claude/skills/deep-research/` | Use SKILL.md as an Agent Skill | | Cursor | `.cursor/skills/` or custom commands | Custom command pointing at SKILL.md | | DSH / others | Any directory that supports skill loading | Load SKILL.md, then enter a topic |
> This skill's SKILL.md is already written as **all-platform** instructions: no dependency on any tool-specific `task()` multi-agent syntax. Chapter writing is parallel by default (when a multi-agent tool is detected); tools without multi-agent support automatically fall back to sequential writing — same output, slightly slower. Search and scraping logic (Scrapling) is reused unchanged across platforms.
Prerequisites
| Component | Online mode | Offline mode | How to get | |-----------|:-----------:|:------------:|------------| | **AI tool runtime** (Claude Code / Codex CLI / Cursor / DSH / OpenCode etc.) | ✅ Required | ✅ Required | Pick your preferred tool | | **Scrapling** | ✅ Required | ❌ Not needed | For web scraping; offline mode doesn't need it |
> **Platform note**: Multi-agent-capable tools (OpenCode, Claude Code, Codex, DSH, etc.) naturally write chapters in parallel; tools without multi-agent support automatically write sequentially. Offline mode only needs the LLM's file-reading capability — no search/scraping components required.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 515 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- ---
- name: deep-research
- description: "Professional deep research report generation — multi-agent collaboration with parallel chapter writing, automatic latest-data targeting, multilingual output, and built-in quality checks."
- version: 6.0.0
- updated: 2026-08-28
- risk: medium
- author: hoolulu
- repository: https://github.com/hoolulu/deep-research
- ---
- # deep-research
- 生成对标券商/第三方研究机构标准的深度调研报告。
- - **架构**:主 agent 调度 4 个子 agent Task(大纲/数据/预检/装配)+ 1 轮主控并行派发章节,中间数据走临时文件
- - **数据源**:在线模式 → 工具内置引擎(Layer 0,如有)+ 大纲建议源定向搜索(Layer 1) + sources.json 优质源搜索(Layer 2)并行 → 按质量触发免费源补强(Layer 3 兜底)→ Scrapling 批量抓取;离线模式 → 用户指定的本地文件(md/txt/pdf/docx)
- - **安装**:见下方「安装与配置」
- - **输出**:`$TMPDIR/outline.json`(临时,非最终报告)
- - **最终报告**:保存到 skill 目录下的 `reports/`
- - **参考文件**:`RULES.md`(硬约束/反模式)、`TYPES.md`(分类标准/编号规范)、**`profiles.json`(三档模式参数,修改后重启软件即全局生效)**
- - **容错原则**:调研不阻塞。所有脚本/命令调用必须有兜底路径。主路径失败 → 自动尝试替代方案(换 `sys.executable`/检查路径/直接 Python 实现)→ 三次失败后向用户报告具体问题。详见「容错原则」。
- ---
- ## 0. 支付级质量标准(所有 Task 共用,缺任何一项即降级)
- | # | 标准 | 说明 |
- |---|------|------|
- | 1 | **结论先行** | 每章以 `> 引用格式` 核心判断开头 |
- | 2 | **来源可追溯** | 每个数字标注(机构,年份) |
- | 3 | **反方视角** | 至少 1 处呈现争议或反对观点 |
- | 4 | **三层深度** | 事实层 → 因果层 → 判断层 |
- | 5 | **零套话** | 无"近年来""值得注意的是"等填充词 |
- | 6 | **标题含判断** | "格局:高度集中"✅ \| "行业概况"❌ |
- | 7 | **可自包含** | 首章必须定义核心概念 |
- | 8 | **无内部编号** | 正文无任何流程编号,标题自解释 |
- | 9 | **时间戳正确** | 文件名和报告尾时间必须 `date` 命令获取 |
- | 10 | **目录源自大纲** | 目录从 outline.json 的第一级章节生成,不从正文提取 |
- | 11 | **强制目录** | 报告正文前必须包含 `## 目录` 标题及自动目录(TOC),列出所有章节标题 |
- | 12 | **元数据完整** | 报告头部必须包含 总字数、阅读时间、数据截至日期(精确到月)、报告生成具体时间(精确到秒)、调研模式、Skill版本 六个字段,用 ` · ` 隔开。另起一行 `> **参考来源**:{主要来源} 等 · 共引用 N 个来源`。报告末尾须附 `## 参考来源`(列出所有引用机构及链接)和 `## 免责声明`。版本号从本 skill 的 VERSION 文件读取。 |
- | 13 | **篇幅达标** | 见项目根目录 [`profiles.json`](profiles.json)。所有模式限制以 `profiles.json` 为准,修改后重启软件即全局生效。 |
- | 14 | **四段式结构** | 顺序固定为:报告标题 → 元数据块(含六字段 + 参考来源行) → `## 目录` → 正文各章 → 尾部(参考来源 + 免责声明) |
- | 15 | **编码洁净** | 所有中间文件(outline.json / data-pool.json / chapter-*.md)必须使用 **UTF-8 无 BOM** 编码写入,不得出现替换字符(\ufffd)或 GBK→UTF-8 Mojibake。子 agent 在写入前必须自行验证编码洁净,不得将编码问题遗留到主 agent |
- | 16 | **纯文本公式** | 报告中不得使用 LaTeX/math 公式语法(`$...$`、`$$...$$`、`\[...\]` 等)。公式必须用纯文本或 Unicode 符号表达,确保复制到任何编辑器都不产生渲染问题 |
- ### 时间锚定规则
- 所有主题默认以 `{CURRENT_YEAR}` 为目标搜索最新数据。时间锚定模式在 Task 1 中由大纲 agent 按以下规则判定:
- | 模式 | 符号 | 判定条件 | target_year | 验收 |
- |:----|:-----|:---------|:-----------|:-----|
- | `latest`(默认) | ⏳ | **所有主题的默认值**,除非符合 relaxed 或 user_specified | `{CURRENT_YEAR}` | 严格:≥50% 数据来自当年/前一年 |
- | `relaxed`(放宽) | 🔓 | 指南/教程/概念类主题,或用户问历史/原理("草书发展""起源""背景") | `{CURRENT_YEAR}` | 宽松:标记旧数据但不过滤 |
- | `user_specified` | 📌 | 用户提问显式指定了年份/月份("2025年""2026Q1""2020年至今") | **用户的指定年份** | 硬约束:>50% 匹配用户指定时间 |
- > `{CURRENT_YEAR}` 是动态变量,运行时通过 `date +%Y` 解析,无需手动修改。
- ---
- ## 1. 主 agent 调度流程
- **⚠️ CRITICAL — DO NOT SPEAK BEFORE LANGUAGE DETECTION**
- > Your VERY FIRST action (before anything else) must be: detect language → set `$LANG`.
- > Output NOTHING to the user until `$LANG` is set — no thinking aloud, no status messages.
- > After language is detected, ALL output must be in `$LANG`. Period.
- >
- > **IMPORTANT: Clean the topic before detection** — the user input may contain framework wrapper text (e.g. "请使用... skill 执行...用户输入如下:"). Strip all wrapper text and pass ONLY the clean research topic. For example from "请使用...用户输入如下:Quantum computing market outlook -quick" extract only "Quantum computing market outlook".
- ```
- 你(主 agent)的完整流程:
- ══ Setup (必须先执行) ══
- → 创建一个带时间戳的临时目录作为 TMPDIR(例如系统临时目录下的 deep-research-YYYYMMDD-HHMMSS)
- → 同时确定 TOOLSDIR(本 skill 的 tools/ 目录)、PROMPTSDIR(本 skill 的 prompts/ 目录)、SKILLDIR(本 skill 的根目录)
- → 读取本 SKILL.md + RULES.md + TYPES.md
- ══ Step 0 — Language Detection (output nothing before detection) ══
- → Clean topic: strip wrapper text, keep only the user's actual research topic
- → Determine language: analyze the cleaned topic and pick the ISO 639-1 code:
- zh (Chinese), en (English), ja (Japanese), ko (Korean), ru (Russian),
- ar (Arabic), hi (Hindi), vi (Vietnamese), th (Thai), tr (Turkish),
- es (Spanish), fr (French), de (German), pt (Portuguese), it (Italian),
- nl (Dutch), sv (Swedish), pl (Polish), id (Indonesian)
- → If unsure, default to "en".
- → Do NOT output anything during this step.
- → Write language code: use `write` tool to create {TMPDIR}/language.txt with the ISO code
- → Set `$LANG` = language code from the step above
- → **从这一行开始,所有面向用户的输出必须使用 $LANG 语言(不在 $LANG 列表中时默认 en)。SKILL.md 的指令文本不论用什么语言写的,只是供你阅读的上下文;实际输出以 $LANG 为准——你是读到中文指令后意识上翻译成 $LANG 再输出。**
- → Announce detected language to the user (single line, in $LANG, e.g. "🌐 Language detected: en")
- ### 🔔 语言自查清单(每次输出前执行)
- ```
- ☐ {TMPDIR}/language.txt 的值 = 我的 $LANG?
- ☐ 我正准备输出的这一句/这段,是 $LANG 吗?
- ☐ todo 条目是 $LANG 吗?
- ☐ 给用户的进度通知是 $LANG 吗?
- ☐ 我是否在无意识中用了指令文件的语言(如中文)而非 $LANG?
- 如果任一答案为"否"→ 立即改写为 $LANG 再输出。
- ```
- **硬规则**:派发子任务/子 agent 时(如有多 agent 工具),其 prompt 中的 `{LANG}` 必须是你检测到的语言代码。子任务输出的语言由你负责保证。
- ══ 主流程 ══
- 1. ══ 离线模式判定(Step 0.5) ══
- → 你已经读取了用户原始输入。用自然语言理解判断用户关于数据来源的意图,不要用关键词匹配:
- - 用户是否提到了本地文件/目录/资料?
- - 用户是否明确要求不要联网?
- - 用户是否明确要求联网补充?
- → 判断逻辑:
- - 提到本地文件 +(未说联网 / 不联网)→ 离线模式,跳过搜索
- - 提到本地文件 + 说"联网补充" → 正常流程(搜+读本地)
- - 未提本地文件 → 正常流程
- → 离线模式 + 有路径 → {TMPDIR}/offline_mode.txt,`offline_mode=true`,向用户报告单行说明
- → 离线模式 + 无路径 → 回复用户询问路径,不继续
- → 正常模式 → `offline_mode=false`
- → **模式解析**:从清洗后的主题中提取调研模式
- - 主题末尾是 ` -quick` → `$DEPTH_MODE=quick`,去除该后缀
- - 主题末尾是 ` -deep` → `$DEPTH_MODE=deep`,去除该后缀
- - 无上述后缀 → `$DEPTH_MODE=standard`(默认)
- 2. 记录任务开始时间到 {TMPDIR}/start_time.txt
- 3. 创建任务清单(使用 `todo_write` 或当前环境等价工具;无则用文本记录),使用 $LANG 语言
- 4. ══ Task 1 — 分析主题 + 生成大纲 ══
- → 读取 {PROMPTSDIR}/task1_outline.md,替换 {TMPDIR} {TOOLSDIR} {LANG} {CURRENT_YEAR} {MODE},注入 prompt
- → **只做变量替换,不添加语言、格式、报告结构等额外指令。语言已由 Step 0 判定为 $LANG 并在 prompt 中替换 {LANG}。**
- → 派发子任务(若有多 agent 工具则用之;否则由你本人直接执行本任务),等待完成
- → 用 `read` 确认 {TMPDIR}/outline.json 存在
- → 从 outline.json 读取 title + chapter_count + depth_mode
- → 任务清单标记完成
- → 向用户报告进度(使用 $LANG 语言)
- 6. ══ Task 2 — 数据收集 + 结构化数据池 ══
- → 读取 {PROMPTSDIR}/task2_data_collection.md
- → 替换标准变量 {TMPDIR} {TOOLSDIR} {LANG} {COUNTRY}
- → 如果 `offline_mode=true`,额外替换:
- {OFFLINE_MODE} → true
- {LOCAL_PATHS} → 读取 {TMPDIR}/offline_mode.txt 的内容(路径列表)
- → 如果 `offline_mode=false`,替换 {OFFLINE_MODE} → false,{LOCAL_PATHS} → 空字符串
- → 派发子任务(若有多 agent 工具则用之;否则由你本人直接执行本任务),等待返回
- → 如失败(子任务报错或 task2_manifest.json 不存在),**自动重试 1 次**,重新派发。第二次仍失败则向用户报告并终止
- → 读取 {TMPDIR}/task2_manifest.json,提取 source_count + fact_count + search_engine + fetch_method + engines + free_fallback + english_fallback + unique_domains
- → 任务清单标记完成
- → 向用户报告进度(使用 $LANG 语言)
- 7. ══ Task 3 — 派发章节撰写 ══
- → 读取 {TMPDIR}/outline.json 获取 chapters 数组;读取 {TMPDIR}/data-pool.json
- → **读取 `profiles.json` 获取当前模式的 `max_chars`**,计算 `per_chapter_chars = max_chars ÷ chapters.length`
- → 从 data-pool.json 提取所有唯一 (src, yr) 组合,按首次出现顺序预分配引用编号 [1], [2], [3]...,写入 {TMPDIR}/citation_map.json
- → 读取 `{PROMPTSDIR}/task3_chapter_agent.md` 模板
- → **根据 $LANG 裁剪 prompt 中的多语言段落**:
- - prompt 中的 `[LANG_en]` 段落:仅当 $LANG=en 时保留,其他语言删除
- - prompt 中的 `[LANG_zh]` 段落:仅当 $LANG=zh 时保留,其他语言删除
- - 删除标记文本本身(`[LANG_en]` `[/LANG_en]` 占位符行)
- - 无标记的段落全部语言通用,保留
- → **撰写方式(所有平台通用,默认并行、无多 agent 时串行)**:
- - **章节执笔者不做任何工具调用**(不跑 prepare-chapter、validate、manifest、word-count),只写文件
- - 探测当前环境是否存在多 agent / 子任务工具(如 `task`、`subagent`、`Task`、`agent` 等):
- - **有** → 为每章逐一构建 prompt,**并行**派发全部章节子任务,全部完成后进入 Round 2
- - **无** → 由你本人按章节顺序**逐一撰写**每章正文并落盘,全部写完后直接进入 Round 2
- - **不得因为无法并行派发而中断调研**:串行撰写与其余步骤完全等价,仅耗时略增
- → **并行派发章节**(仅当存在多 agent 工具时):
- - 初始化空列表 task_ids = []
- - For N = 1 to chapters.length:
- - 读取 outline.chapters[N] 的 title、sections
- - 从 data-pool.json 中筛选该章 sub_questions 对应的事实条目
- - **将事实直接嵌入 prompt**:每条事实前标注预分配的 `[N]` 编号
- - 用多 agent 工具的后台/并行模式派出每章
- - 记录每章子任务的句柄/ID 到 task_ids(无句柄可记录时,以章节文件路径为追踪依据)
- - 任务清单标记该章 in_progress
- - 将 task_ids 写入 {TMPDIR}/task3_bg_ids.json(持久化,防止主 agent 中断后丢失状态)
- - 向用户报告:"已并行派出 {N} 章,等待全部完成..."(使用 $LANG 语言)
- - 等待全部章节完成(本轮结束后收到全部完成提示再继续;单章完成通知可忽略)
- - 然后进入 Round 2:
- **Round 2 — 收集结果 + 失败重写**:
- - 读取 {TMPDIR}/task3_bg_ids.json 获取所有 task 句柄
- - 对每个子任务收集其章节结果(或直接读取产物文件)
- - 用 `read` 逐一确认 {TMPDIR}/chapters/chapter-{N}.md 是否存在且非空
- - 如果有章节缺失或内容为空:
- - 记录失败章节编号列表
- - **串行重写**:对每个失败章节逐一(同步)重新派发/执笔,等待完成
- - 再次用 `read` 确认
- - 任务清单标记每章 completed
- - 向用户报告最终章节完成情况(使用 $LANG 语言)
- 8. ══ Task 4 — 验证 + 装配 + QA(**主 agent 直接执行**) ══
- → **Step 0 — 清理残留**:删除 {SKILLDIR}/reports/ 目录下所有 0 字节文件(前次装配失败的空壳);创建 {SKILLDIR}/reports/$LANG/ 子目录(如果不存在)
- → **Step 1 — 批量验证**:`python {TOOLSDIR}/dr_tools.py validate-all-chapters --chapters-dir {TMPDIR}/chapters/ --chapters {chapter_count}`,内部 ThreadPoolExecutor 并行验证所有章节。从输出 JSON 的 `failed_chapters` 中找到失败章节,逐个重新生成(重新派发章节 agent → 重新验证该章)。
- → **Step 1b — 章节深度均衡检查**:`python {TOOLSDIR}/dr_tools.py depth-balance --chapters-dir {TMPDIR}/chapters/ --chapters {chapter_count}`。如果某章行数 < 平均值的 50%,标记告警(not blocking,仅提示)。
- → Step 1 或 Step 2 失败时,**先删除本次已写入的产物**(报告文件、中间文件等),再重新执行对应步骤,避免残留文件干扰下次运行
- → **Step 2 — 装配**:`python {TOOLSDIR}/dr_tools.py assemble-report --outline {TMPDIR}/outline.json --chapters-dir {TMPDIR}/chapters/ --datapool {TMPDIR}/data-pool.json --mode {depth_mode} --target-year {target_year} --output {SKILLDIR}/reports/$LANG/ --lang $LANG`
- → **$REPORT 提取**:从装配输出中提取 `Report assembled: ...` 行中冒号后的第一个路径,设为 `$REPORT` 变量
- → **Step 2b — 可信评估(数据层)**:`python {TOOLSDIR}/dr_tools.py generate-confidence-section --datapool {TMPDIR}/data-pool.json --manifest {TMPDIR}/task2_manifest.json --report "$REPORT" --lang $LANG`
- 从输出中解析 `CONFIDENCE:` 行获取 `conf_coverage`、`conf_total_facts`、`conf_high_pct`、`conf_medium_pct`、`conf_low_pct`、`conf_actual_pct`、`conf_est_pct`、`conf_fct_pct`、`conf_auth_pct`、`conf_data_limited`、`conf_controversies`、`conf_adequate_subq`、`conf_total_subq`、`conf_score` 共 14 个变量。
- → **Step 2c — 可信评估(LLM判断)**:使用上一步的 14 个统计变量 + 报告标题(从 outline.json 读取)在 LLM 上下文内直接生成定性评估意见。
- - 输出必须使用 $LANG 语言,2-4 句,纯定性判断,不重复逐项明细中的具体数字
- - **语气校准(重要)**:本工具是开源信息综合项目,非付费研究报告。评估意见应遵循以下原则:
- - **总分决定基调**:score≥75 → 正面肯定为主;50-74 → 中性平衡;<50 → 温和提醒
- - **不说"缺陷""不足""未能"等负面措辞** → 改为"可进一步关注的方面""仍有补充空间"
- - **不说"无法获取""受限于"** → 改为"部分高频量化指标因商业敏感性未纳入公开讨论范围"
- - **不自我贬低**:不出现"门槛高""可信度大打折扣"等损害报告公信力的表述
- - **正面收尾**:最后一句必须是肯定整体参考价值的结论
- - **定位准确**:强调"综合公开信息形成的参考判断"而非"严谨学术研究"
- - 写出到 `{TMPDIR}/llm_assessment.txt`
- - 用 `edit` 工具将评估意见插入到报告可信评估区的 `**{综合评级标签}**` 行之后(追加 "**{评估意见标签}**:\n\n{文本}"),然后用 `read` 确认插入正确
- - `{综合评级标签}` 和 `{评估意见标签}` 使用语言映射表中的翻译
- → **Step 3 — 数据受限处理**:读取 {TMPDIR}/task2_manifest.json 的 `data_limited` 字段。如果为 true,在报告标题后插入数据说明声明,**使用 $LANG 语言**。
- → **Step 4 — 引用处理**:`python {TOOLSDIR}/dr_tools.py convert-citations --datapool {TMPDIR}/data-pool.json "$REPORT" --lang $LANG`(从 data-pool 构建参考章节,验证正文 `[N]` 引用均有对应条目)
- → **Step 4b — 货币符号转义**:`python {TOOLSDIR}/dr_tools.py escape-currency "$REPORT"`(将 `$` 转义为 `\$`,避免被知乎/Obsidian/Typora 等渲染器错误解析为 LaTeX math mode)
- → **Step 5 — QA**:`python {TOOLSDIR}/dr_tools.py qa-report "$REPORT" --mode {depth_mode} --target-year {target_year} --lang $LANG`,解析 JSON 输出,从 `checks.word_count.count` 取字数,从 `checks.word_count.limit` 取上限
- → **Step 6 — 更新本地报告列表页**:`python {TOOLSDIR}/generate_pages.py --local`(刷新 reports-browser/index.html,将 reports/ 下所有报告打包为嵌入 JS 的可浏览页面)——需在 `{SKILLDIR}` 目录下执行,bash 命令须加 `workdir="{SKILLDIR}"` 参数
- → 任务清单标记完成
- → ⏱ **强制计算总耗时**(读取 start_time.txt + 当前时间算差值)
- → 从 outline.json + task2_manifest.json + qa-report 中提取数据,使用 $LANG 语言汇报最终结果。
- **语言自适应标签映射表**(以下所有 <词> 根据 $LANG 替换):
- | 中文 | en | ja | ko | fr | de | es | 其余语言 |
- |------|----|----|----|----|----|----|---------|
- | 执行总结 | Execution Summary | 実行サマリー | 실행 요약 | Résumé exécutif | Zusammenfassung | Resumen ejecutivo | Execution Summary |
- | 阶段 | Stage | 段階 | 단계 | Phase | Phase | Fase | Stage |
- | 详情 | Detail | 詳細 | 세부 | Détail | Detail | Detalle | Detail |
- | 大纲/Plan | Plan | 概要 | 개요 | Plan | Plan | Plan | Plan |
- | 观点速览/Insight | Insight | 洞察 | 인사이트 | Aperçu | Einblick | Perspectiva | Insight |
- | 数据/Data | Data | データ | 데이터 | Données | Daten | Datos | Data |
- | 报告/Report | Report | レポート | 보고서 | Rapport | Bericht | Informe | Report |
- | 章 | ch | 章 | 장 | chap. | Kap. | cap. | ch |
- | 来源 | sources | ソース | 출처 | sources | Quellen | fuentes | sources |
- | 事实 | facts | 事実 | 사실 | faits | Fakten | datos | facts |
- | 独立域名 | domains | ドメイン | 도메인 | domaines | Domains | dominios | domains |
- | 行 | lines | 行 | 줄 | lignes | Zeilen | líneas | lines |
- | 字 | chars | 語 | 단어 | mots | Wörter | palabras | chars |
- | 分钟 | min | 分 | 분 | min | Min. | min | min |
- | 生成时间 | Generated | 生成時刻 | 생성 시간 | Généré le | Erzeugt | Generado | Generated |
- | 搜索 | Search | 検索 | 검색 | Recherche | Suche | Búsqueda | Search |
- | 数据充足 | Adequate | 十分 | 충분 | Suffisantes | Ausreichend | Adecuado | Adequate |
- | 数据受限 ⚠ | Limited ⚠ | 制限 ⚠ | 제한 ⚠ | Limitées ⚠ | Eingeschränkt ⚠ | Limitado ⚠ | Limited ⚠ |
- | 可信评估 | Confidence | 信頼性評価 | 신뢰도 평가 | Évaluation de confiance | Vertrauensbewertung | Evaluación de confianza | Confidence |
- | 覆盖充足/部分覆盖/覆盖不足 | Full/Partial/Limited coverage | 完全/部分/不足カバー | 충분/부분/부족 | Couverture complète/partielle/limitée | Vollständige/Teilweise/Eingeschränkte Abdeckung | Cobertura completa/parcial/limitada | Adequate/Partial/Limited |
- | 统计 | Stats | 統計 | 통계 | Statistiques | Statistiken | Estadísticas | Stats |
- | 综合评级 | Rating | 総合評価 | 종합 평가 | Note globale | Gesamtbewertung | Calificación general | Rating |
- | 评估意见 | Assessment | 評価意見 | 평가 의견 | Avis d'évaluation | Bewertung | Opinión de evaluación | Assessment |
- | 耗时 | Duration | 所要時間 | 소요 시간 | Durée | Dauer | Duración | Duration |
- | 免费源补强 | free fallback | 無料補強 | 무료 보강 | sources gratuites | kostenlose Quellen | fuentes gratuitas | free fallback |
- | 本地文件 | local files | ローカル | 로컬 파일 | fichiers locaux | lokale Dateien | archivos locales | local files |
- **搜索策略描述拼接规则**(使用映射表中的翻译):
- ```
- IF offline_mode=true:
- <搜索词>:{offline_$LANG}
- ELSE:
- engines_names = engines 数组元素大写(["websearch"] → "Websearch")
- desc = engines_names
- IF free_fallback=true: desc += " (+{free_fallback_$LANG})"
- IF english_fallback=true: desc += " (+EN)"
- <搜索词>:{desc}
- ```
- **数据质量徽标规则**:
- ```
- IF data_limited=true: <质量词> = {limited_$LANG}
- ELSE: <质量词> = {adequate_$LANG}
- ```
- 严格按以下结构输出:
- ```
- 📊 **<执行总结词>**
- | <阶段词> | <详情词> |
- |:----|:------|
- | 📋 <Plan词> | {outline.title} · {outline.chapter_count} <章词> · {outline.depth_mode} |
- | 🎯 <Insight词> | {outline.chapters[0].description} |
- | 📡 <Data词> | {task2_manifest.source_count} <来源词> · {task2_manifest.unique_domains} <独立域名词> · {task2_manifest.fact_count} <事实词> · <搜索词>:{search_desc} · {task2_manifest.fetch_method} |
- | 📄 <Report词> | {REPORT} |
- | 🌐 <浏览器词/Report List> | {SKILLDIR}/reports-browser/index.html |
- | ✅ <可信评估词> | <覆盖_{coverage_summary}> · 高置信{conf_high_pct}% · 已公布{conf_actual_pct}% · {conf_score}/100 · {data_quality_badge} → {llm_verdict} |
- | 📊 <统计词> | {qa_report.line_count} <行词> · {qa_report.word_count} <字词> · <耗时词>⏱ {totalMin} <分钟词> · <生成时间词>:{gen_time} |
- ```
- 其中:
- - `{outline.chapters[0].description}` = 从 outline.json 读取第 1 章(核心观点)的 description 字段,作为观点速览摘要
- - `{gen_time}` = 读取 {TMPDIR}/start_time.txt 中的任务开始时间,格式化为 `YYYY-MM-DD HH:mm:ss`
- - `{REPORT}` 仅输出最终报告路径(`{SKILLDIR}/reports/{LANG}/xxx.md`),不包含任何 TMPDIR 中间路径
- - `{search_desc}` = 按搜索策略拼接规则生成,所有中文词根据 $LANG 翻译
- - `{data_quality_badge}` = 按数据质量徽标规则生成
- - `<覆盖_{coverage_summary}>` = 从 `task2_manifest.coverage_summary` 读取(adequate/partial/insufficient),用语言映射表中"覆盖充足/部分覆盖/覆盖不足"行对应翻译替换
- - `{conf_high_pct}`、`{conf_actual_pct}`、`{conf_score}` = 从 Step 2b 的 `CONFIDENCE:` 行解析对应的字段
- - `{llm_verdict}` = 读取 Step 2c 写入的 `{TMPDIR}/llm_assessment.txt` 完整内容
- → 任务清单全部完成
- **禁止**:主 agent 不得在 Task 调度之间自行执行搜索引擎调用或数据处理。搜索/抓取归 Task 2,大纲生成归 Task 1,章节撰写归 Task 3,装配验证归 Task 4。Task 间的 handoff 文件读取(outline.json、task2_manifest.json 等)不受此限。
- ---
- ## 2. Task 1 — 主题分析 + 大纲
- **工具**:多 agent / 子任务工具(如有)| 一次调用;无则主 agent 直接执行本任务
- **prompt 文件**:`prompts/task1_outline.md`
- **用法**:读取文件内容,替换 `{TMPDIR}` `{TOOLSDIR} {LANG} {CURRENT_YEAR}` 为实际值后注入 prompt。
- **输出**:大纲 agent 直接用 `write` 工具创建 `{TMPDIR}/outline.json`。主 agent 通过 `read` 确认文件存在。
- ---
- ## 3. Task 2 — 数据收集 + 结构化数据池
- **工具**:多 agent / 子任务工具(如有,建议用高并发/高思考 budget 分类);无则主 agent 直接执行本任务
- **prompt 文件**:`prompts/task2_data_collection.md`
- **用法**:读取文件内容,替换 `{TMPDIR}` `{TOOLSDIR}` `{LANG}` `{COUNTRY}` `{OFFLINE_MODE}` `{LOCAL_PATHS}` 为实际值后注入 prompt。
- **输出**:{TMPDIR}/data-pool.json + {TMPDIR}/task2_manifest.json(使用 `write` 工具创建)
- **LANG→COUNTRY 映射**(用于替换 `{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。未覆盖的语言用空字符串。
- ---
- ## 3. Task 3 — 章节撰写 & 章节 agent 指令模板
- 主 agent 为每章准备子任务 prompt 时,参数使用 `{PROMPTSDIR}/task3_chapter_agent.md` 模板。
- **用法**:读取 `{PROMPTSDIR}/task3_chapter_agent.md`,替换以下变量:
- - `[章节 title]` → 当前章的 title(从 outline.json chapters 数组读取)
- - `[N]` → 当前章节编号(第 1 章为 1,第 2 章为 2...)
- - `[total]` → chapters 数组总长度
- - `[sections 列表]` → 当前章的 sections 数组(逗号分隔)
- - `{per_chapter_chars}` → `profiles.json` 中当前模式的 `max_chars ÷ 总章数`(主 agent 一次性算好)
- - `{min_paragraphs}` → `profiles.json` 中当前模式的 `min_paragraphs`
- - `{调研模式}` → quick / standard / deep(当前调研模式)
- - `{TMPDIR}` → 运行时临时目录
- - `{TOOLSDIR}` → tools 目录
- **输出**:{TMPDIR}/chapters/chapter-{N}.md(使用 `write` 工具创建)
- ---
- ## 4. Task 4 — 验证 + 装配 + QA(主 agent 直接执行)
- 装配、引用转换、QA 检查均由主 agent 通过 bash 命令直接执行 `{TOOLSDIR}/dr_tools.py` 完成:
- 1. `validate-all-chapters` → 批量结构验证(并行)
- 2. `assemble-report` → 生成报告
- 3. `generate-confidence-section` → 可信评估(从 data-pool + manifest 聚合生成)
- 4. `convert-citations` → 引用转换
- 5. `escape-currency` → 货币符号转义
- 4. `qa-report` → 质量检查
- **清理**:装配完成后主 agent 执行 `Remove-Item -Recurse -Force "{TMPDIR}"` 清理临时文件。
- ---
- ## 6. 输出文件管理
- ### 路径优先级
- 最终报告保存路径按以下优先级判定:
- 1. **用户自定义路径** — 如果用户显式指定了输出目录(如 `D:\Reports\`),使用指定路径
- 2. **Skill 默认路径** — `{SKILLDIR}/reports/`(skill 根目录下的 reports/)
- 装配阶段(Step 3)根据实际使用的路径写入,文件名格式不变:`<主题>-YYYYMMDD-HHmmss.md`。
- ### QA 路径核验
- Step 4 QA 必须确认报告文件的保存路径为上述两者之一,如果路径不属于默认目录且非用户指定目录,标记"路径异常"不通过。
- ### 日期锚定
- 文件名中的日期用当前年月日。
- ### 清理机制
- ```
- Task 4 装配 + QA 通过后,内部已完成清理:
- 1. 清理中间文件 `{TMPDIR}` 目录:Windows 用 `Remove-Item -Recurse -Force "{TMPDIR}"`,Linux 用 `rm -rf {TMPDIR}`
- 2. 确认 tool-output/ 无残留
- ```
- ---
- ## 7. 工具依赖速查
- | 能力 | 用途 | 免费? | 国内源? |
- |:----|:-----|:-----:|:--------:|
- | 内置搜索(探测) | **主力**搜索引擎(当前工具的内置搜索,如 `websearch`/`web_search`,运行时探测) | 取决于环境 | 视引擎而定 |
- | 其他搜索引擎 | 不同工具的内置搜索(运行时自动适配) | 取决于环境 | — |
- | Scrapling MCP | 全文抓取(MCP,需注册到当前工具的 MCP 配置) | ✅ | **✅ 推荐,国内源主力** |
- | webfetch / fetch | 抓取回退(Scrapling 不可用时替代) | ✅ | ❌ 远端受限,国内源效果一般 |
- | bash / 终端 | date 时间戳 / 文件操作 / 运行 Python | ✅ | — |
- | write | 写文件 | ✅ | — |
- 搜索策略由 agent 在运行时根据工具集**自动适配**,不依赖预设的搜索引擎配置。
- **搜索链路**:
- ```
- Layer 0 — 工具内置引擎探测(扫描可用工具集)
- │
- ├─ 发现内置引擎 → 作为主力搜索,与后续层并行
- └─ 未发现 → 跳过此层,不影响后续
- Layer 1 — 大纲建议源定向搜索(site: 搜索,用内置引擎)
- ↓
- Layer 2 — sources.json 优质源搜索(并行)
- ↓
- 搜索结果质量评估(Step 3 质量门)
- ├─ 达标 → 直接进入抓取
- └─ 不达标 → Layer 3 免费源补强(A/B 类源 + 区域引擎)
- ↓
- 全部 URL → 检测 Scrapling MCP 可用性
- ├─ 🔧 可用 → Scrapling 批量抓取全文 → 数据池
- └─ 🌐 不可用 → webfetch 逐个抓取全文(标注回退)→ 数据池
- ```
- ---
- ## 8. 安装与配置
- ### 前置条件
- - Python 3.10+
- - Scrapling(安装方式由 AI 根据官方文档和当前系统自动适配)
- - Playwright(可选,用于 JS 渲染和反检测抓取)
- ### 注册 Scrapling MCP Server
- Scrapling 通过 MCP(Model Context Protocol)与 AI agent 通信,需注册到当前工具的 MCP 配置后才能被调用(各工具配置文件位置与键名不同:Claude Code 用 `mcpServers`,OpenCode 用 `mcp`,等等——让 AI 现场探测并适配)。
- **推荐方式**:运行一次 `/research`,Task 2 在检测到 Scrapling 未注册时,会自动完成安装和注册。
- **参考实现**:本项目提供了 `scrapling-mcp-server.py`(与本文件同目录),是一份标准 MCP Server 实现,覆盖了标准抓取、反检测抓取、JS 渲染抓取三种模式。AI 可根据本机环境参考此脚本,如有问题再参考 Scrapling 官方文档。
- **手动注册格式**(以 `mcpServers` 标准格式为例,供 AI 安装时参考;按你当前工具的配置键名与数组格式调整):
- ```json
- {
- "mcpServers": {
- "scrapling": {
- "command": "<python-path>",
- "args": ["<mcp-server-script-path>"]
- }
- }
- }
- ```
- ### 重启当前工具
- MCP Server 在工具启动时加载,注册后**必须重启**才能生效。
- ### 验证是否生效
- 运行 `/research` 调研时,Task 2 阶段如显示 `🔧 Scrapling 抓取` 则表示 MCP 工作正常。若显示 `🌐 webfetch 抓取(Scrapling 已自动安装,重启后生效)` 则表示 Scrapling 已自动安装,重启后下次生效。若显示 `🌐 webfetch 抓取` 则表示安装失败,需检查 Python 环境和网络连接。
- ### 抓取回退说明
- 若 Scrapling 抓取某 URL 失败(WAF/超时/JS 渲染需求),会自动回退到 webfetch 孤立抓取该 URL,不影响其他 URL 的 Scrapling 抓取。若 Scrapling MCP 完全不可用,则全部走 webfetch。调研**不会阻塞**。
- ---
- ## 9. 跨平台编码规范(Windows/macOS/Linux)
- ### 问题根因
- Windows PowerShell 5.1 控制台编码为 CP936(GBK 中文编码),**无法表示 18 种非英语语言**:
- 俄语西里尔字母、日语假名/汉字、韩语谚文、阿拉伯语、泰语、印地语天城文、越南语调号、
- 以及德语 äöüß、法语 éèêç、西班牙语 ñ 等拉丁扩展字符——通过 shell 传参/pipe 时全部损坏。
- macOS/Linux 的终端默认 UTF-8,无此问题。
- ### 硬性规则(所有 agent 必须遵守)
- | # | 规则 | 正确做法 | 错误做法 |
- |---|------|---------|---------|
- | 1 | **非 ASCII 文本不进 shell argv/pipe** | 用 `write` 工具写文件 → Python `--file` 读取 | Python 脚本 argv 传非 ASCII 文本 ❌ |
- | 2 | **所有文件读写用 UTF-8** | Python 统一 `encoding='utf-8-sig'`(BOM 容错) | 依赖 shell 编码 |
- | 3 | **写文件只用 `write` 工具** | `write` 工具 → UTF-8 无 BOM | PowerShell `Set-Content -Encoding UTF8` ❌(会加 BOM) |
- | 4 | **Python stdout 显式设 UTF-8** | `sys.stdout.reconfigure(encoding='utf-8')` | 依赖系统默认编码 |
- | 5 | **Python 子进程输出用 `--output` 文件** | `python script.py --input file --output result` | shell 重定向 `> result.txt` ❌(CP936 编码输出) |
- ### 一劳永逸方案:全链路编码安全架构
- ```
- ┌─ 数据来源 ──────────────────────────────────┐
- │ write 工具 / Python open(..., 'w', encoding) │ ← UTF-8 无 BOM
- └──────────────┬──────────────────────────────┘
- ▼
- ┌─ 中间文件 ──────────────────────────────────┐
- │ *.json / *.md : 全部 UTF-8(BOM 容错读取) │ ← utf-8-sig 代码编
- └──────────────┬──────────────────────────────┘
- ▼
- ┌─ Python 处理 ───────────────────────────────┐
- │ 所有脚本入口设 `stdout.reconfigure('utf-8')` │ ← 输出安全
- │ 所有文件读用 `encoding='utf-8-sig'` │ ← 输入安全
- │ Python 脚本统一用 `--input`/`--output` 参数 │ ← 完全绕过 shell
- └──────────────┬──────────────────────────────┘
- ▼
- ┌─ 最终输出 ──────────────────────────────────┐
- │ 报告文件 : UTF-8 无 BOM,任意语言均可正确显示 │
- └─────────────────────────────────────────────┘
- ```
- ### 当前防护状态
- | 文件 | 防护措施 | 状态 |
- |------|---------|:----:|
- | `dr_tools.py` | 入口 `stdout.reconfigure` + 所有读操作用 `utf-8-sig` | ✅ |
- | `dr_check.py` | 所有读操作用 `utf-8-sig` | ✅ |
- | `dr_gen.py` | 所有读操作用 `utf-8-sig`,写操作用 `utf-8`(无 BOM) | ✅ |
- ---
- **Created by [hoolulu](https://github.com/hoolulu)** · [github.com/hoolulu/deep-research](https://github.com/hoolulu/deep-research)
README.md · README · 655 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # deep-research Skill
- <p align="center"><b>English</b> · <a href="#chinese">中文</a></p>
- ---
- **Deep Research Report Generation Skill — One command, ten minutes, institutional-grade deep research report**
- Multi-agent autonomous search, scrape, write, and QA — feed it a topic, get a citable, browsable, exportable research report in Chinese or 19 other languages.
- Benchmarked against institutional research structure: conclusions-first, traceable sources, counter-arguments, scenario forecasting. Supports quick / standard / deep tiers, with automatic language detection across 19 languages.
- Built for industry research, trend foresight, competitive scanning, policy analysis, technology deep-dives, and investment memos — not a handful of search summaries, but a report you can actually use.
- > **Current version:** [View updates](https://github.com/hoolulu/deep-research/commits/main)
- >
- > 📂 **Browse all sample reports →** [H33研报· 深度调研报告集](https://www.h33.top)
- > — filter, sort, and browse by language and depth.
- ---
- ### ✨ At a Glance
- <table width="100%">
- <tr><td style="white-space: nowrap; width: 1%;"><b>🎯 One command</b></td><td><code>/research <topic></code> → fully automated research, zero manual intervention</td></tr>
- <tr><td style="white-space: nowrap;"><b>⏱ Report in ~10 min</b></td><td>quick mode ~8–12 min, standard ~10–15 min</td></tr>
- <tr><td style="white-space: nowrap;"><b>🌍 19 languages</b></td><td>Auto-detects topic language, generates report in the same language</td></tr>
- <tr><td style="white-space: nowrap;"><b>🔧 All platforms</b></td><td>Works with any AI coding tool (Claude Code, Codex CLI, Cursor, DSH, Windsurf, Cline and more)</td></tr>
- <tr><td style="white-space: nowrap;"><b>📁 Local file research</b></td><td>Also supports PDF/DOCX/TXT/MD, no internet needed, auto-parsed</td></tr>
- <tr><td style="white-space: nowrap;"><b>🖥️ Local report browser</b></td><td>Auto-refreshed as a local browser page after each run<br><code>reports-browser/index.html</code> — search, filter, sort, preview</td></tr>
- <tr><td style="white-space: nowrap;"><b>📄 PDF/DOCX export</b></td><td>Export reports as PDF or DOCX from the preview modal — fully client-side, no server required</td></tr>
- </table>
- <table width="100%">
- <tr><th>Command</th><th>Result</th></tr>
- <tr><td style="white-space: nowrap;"><code>/research 中国新能源汽车产业发展现状</code></td><td>中文报告</td></tr>
- <tr><td><code>/research Competitive landscape of AI cloud computing</code></td><td>English report</td></tr>
- <tr><td><code>/research Анализ рынка нефти и газа в России</code></td><td>Отчёт на русском</td></tr>
- <tr><td><code>/research 日本のアニメ産業のグローバル市場戦略</code></td><td>日本語レポート</td></tr>
- <tr><td><code>/research 한국 반도체 산업의 글로벌 경쟁력 분석</code></td><td>한국어 보고서</td></tr>
- <tr><td><code>local file research, see FAQ for prompts</code></td><td>offline mode, read local files</td></tr>
- </table>
- > It interacts with you entirely in the language you set and searches for materials in that target language — not a simple translation pipeline.
- ---
- ## 1. Why You Need This
- If you've ever asked AI to do research, you've likely hit these walls:
- - Search + summarize → too shallow, just a few bullet points
- - Industry reports at $50–500+ each → too expensive for individuals
- - Overseas tools → can't search Chinese sources like Baidu Baike, Zhihu, 199IT, iResearch
- - AI fabricates numbers → looks reasonable but has no traceable source
- This skill follows a **4-stage pipeline** before delivering a report. Not search-and-dump — it's analyze → search+verify → write → verify.
- ## 2. Who It's For
- **Indie developers**, **independent researchers**, **small teams**.
- People who need professional-grade research capabilities without relying on paid databases or research institutions.
- ## 3. Typical Output (Standard Mode)
- | Metric | Data (standard mode example) |
- |--------|------------------------------|
- | Report length | 500-700 lines / ~12,000-20,000 chars (varies by language) |
- | Data tables | 15-25, covering market size, competitive landscape, technical specs |
- | Analysis paragraphs | 80-120 (each with conclusion + data + causation + judgment) |
- | Unique sources cited | 15-25 (Chinese and international institutions) |
- | Opposing viewpoints | 3-8, at least one controversy per chapter |
- | Data collection | ~1-3 min |
- | Report generation | ~8-15 min |
- | Total time | ~10-20 min |
- > Above ranges for standard mode. Actual times vary by topic complexity and data availability.
- ### 📖 Featured Reports
- > All sample reports have moved to [H33研报· 深度调研报告集](https://www.h33.top) — filter, sort, and browse by language and type. Some featured topics:
- | Report | Tags |
- |--------|------|
- | <a href="https://www.h33.top" target="_blank">Global AI Chip Market Landscape and Competitive Dynamics 2026</a> | AI · Semiconductors |
- | <a href="https://www.h33.top" target="_blank">The Feasibility of Mars Colonization</a> | Space · Technology |
- | <a href="https://www.h33.top" target="_blank">Electric Vehicle Battery Supply Chain and Raw Material Geopolitics 2026</a> | Energy · Geopolitics |
- | <a href="https://www.h33.top" target="_blank">GenAI Enterprise Adoption Trends & ROI Measurement in 2026</a> | AI · Enterprise |
- | <a href="https://www.h33.top" target="_blank">Cross-border E-commerce Logistics Trends in Southeast Asia 2026</a> | E-commerce · Logistics |
- Click a report title to jump to the H33 report collection and search for the topic.
- ## 4. Cost
- | Component | Cost |
- |-----------|------|
- | **LLM (already using)** | **DeepSeek v4 Flash** baseline: quick ~100–150k tokens / < $0.03, standard ~150–300k / < $0.06, deep ~300–500k / < $0.10 |
- | **Scrapling fetching** | Runs locally, zero cost |
- | **Domestic sources** | Direct connection, zero cost, no proxy needed |
- | **AI tool runtime** | MIT open source, zero cost |
- > Estimates based on DeepSeek v4 Flash ($0.14/1M input, $0.28/1M output, source: `https://api-docs.deepseek.com/quick_start/pricing`). Actual costs vary by cache hit rate and topic complexity.
- ## 5. How It Works
- The pipeline runs in 4 automated stages:
- ```
- ① Analyze outline — Analyze topic, generate research framework and search plan
- ↓
- ② Collect data — ╭─ Online: four-layer parallel search (tool built-in engine → suggested sources → sources.json → free fallback) → Scrapling batch fetch → data pool
- ╰─ Offline: read local files directly (PDF/DOCX/TXT/MD) → data pool
- ↓
- ③ Parallel writing — All chapters in parallel (auto-sequential without multi-agent), facts embedded directly in prompts, no tool calls
- ↓
- ④ Validate & assemble — Batch validate → assemble-report → convert-citations → escape-currency → qa-report
- ```
- ## 6. Search Pipeline & Built-in Resources
- Search uses a **four-layer priority** strategy, all issued in parallel:
- ```
- Layer 0 — Tool built-in engine (auto-detected at runtime, e.g., `websearch` / `web_search`)
- Layer 1 — Outline-suggested sources (topic-targeted recommendations, e.g., arctic-council.org)
- Layer 2 — sources.json (30+ curated quality sources, health-checked on startup)
- Layer 3 — Free source reinforcement (A/B class search fallback)
- ```
- All layers are merged and deduplicated, then batch-fetched by Scrapling. Free source reinforcement is triggered only when Layer 0-2 fail the per-sub-question quality gate (URL < 3 / outdated year / no authoritative source for high-priority sub-questions).
- `sources.json` covers academic (Semantic Scholar / arXiv / PubMed / Nature), data (World Bank / IMF / Our World in Data), news (Reuters / BBC / Guardian), and Chinese sources (Baidu Baike / Zhihu / 36Kr / The Paper / iResearch / East Money / CSDN) — 30+ sources, auto health-checked on startup with dead sources skipped.
- ## 7. Report Highlights
- | Dimension | Description |
- |-----------|-------------|
- | **Multilingual native writing** | Auto-detects topic language, writes directly in 19 languages, no translation pipeline |
- | **Every number has a source** | `(N)` clickable citations in text, full reference list at end. No source = no number |
- | **Pros and cons coexist** | Every chapter presents controversies and opposing views |
- | **Confidence grading** | Final summary table (high/medium/low) shows what's reliable vs. disputed |
- | **Data anti-pitfall** | Auto-detects common data errors — wrong units, fabricated trends, misattributed sources |
- | **Paragraphs over padding** | 8-12 substantive paragraphs per chapter as core, tables can't pad the length |
- ## 8. Three Depth Modes
- | Command | Purpose | Min chapters | Min paragraphs/chapter | Target chars | Est. time |
- |---------|---------|-------------|----------------------|--------------|-----------|
- | `/research <topic>` | standard (default) | 8 | ≥ 5 | ≈ 25,000 | ~10–15 min |
- | `/research <topic> -quick` | Quick insight | 5 | ≥ 4 | ≈ 15,000 | ~8–12 min |
- | `/research <topic> -deep` | Maximum depth | 10 | ≥ 6 | ≈ 45,000 | ~15–25 min |
- > Parameters in `profiles.json`, restart to apply. Char count excludes whitespace and Markdown syntax.
- ## 9. Installation
- deep-research is an **all-platform** skill: one codebase, drop it into any AI tool that supports skill/command mechanisms — no per-tool rewrite needed.
- ### 🧠 Method 1: AI Auto-Install (Recommended)
- Copy this prompt into your AI tool's chat, the AI will do everything automatically:
- ```text
- Please read the https://github.com/hoolulu/deep-research project and follow the documentation to:
- 1. Install prerequisites (determine method based on Scrapling docs and your OS)
- 2. Register the Scrapling MCP Server, verify it works after restart
- 3. Register the /research and /research-update entry points for your current tool
- Confirm each step, then read VERSION and summarize the installation status.
- ```
- The AI reads the docs → understands your system → installs step by step → verifies. No manual commands needed.
- ### 📋 Method 2: Manual Entry Registration
- Each tool registers skills/commands differently — drop the whole project into the right directory (common tools below):
- | Tool | skill/entry location | Command form |
- |------|----------------------|--------------|
- | OpenCode | `~/.opencode/skills/deep-research/` | `/research`, `/research-update` (included in `command/`) |
- | Codex CLI | skill directory, `command/` files included | `/research`, `/research-update` |
- | Claude Code | `~/.claude/skills/deep-research/` | Use SKILL.md as an Agent Skill |
- | Cursor | `.cursor/skills/` or custom commands | Custom command pointing at SKILL.md |
- | DSH / others | Any directory that supports skill loading | Load SKILL.md, then enter a topic |
- > This skill's SKILL.md is already written as **all-platform** instructions: no dependency on any tool-specific `task()` multi-agent syntax. Chapter writing is parallel by default (when a multi-agent tool is detected); tools without multi-agent support automatically fall back to sequential writing — same output, slightly slower. Search and scraping logic (Scrapling) is reused unchanged across platforms.
- ### Prerequisites
- | Component | Online mode | Offline mode | How to get |
- |-----------|:-----------:|:------------:|------------|
- | **AI tool runtime** (Claude Code / Codex CLI / Cursor / DSH / OpenCode etc.) | ✅ Required | ✅ Required | Pick your preferred tool |
- | **Scrapling** | ✅ Required | ❌ Not needed | For web scraping; offline mode doesn't need it |
- > **Platform note**: Multi-agent-capable tools (OpenCode, Claude Code, Codex, DSH, etc.) naturally write chapters in parallel; tools without multi-agent support automatically write sequentially. Offline mode only needs the LLM's file-reading capability — no search/scraping components required.
- ## 10. Usage
- After installation and restart, type in the chat:
- | Command | Description | Est. time |
- |---------|-------------|-----------|
- | `/research <topic>` | standard mode (online search) | ~10-15 min |
- | `/research <topic> -quick` | quick mode (online search) | ~8-12 min |
- | `/research <topic> -deep` | deep mode (online search) | ~15-25 min |
- | `local file research` | offline mode (local files) | depends on file size |
- | `/research-update` | Check for updates | — |
- > Local file research: see FAQ §2 "How to use local materials for report generation?" for exact prompts.
- ### What Happens After You Send It
- The entire pipeline runs automatically — you don't need to do anything:
- ```
- ① Analyze outline — Analyze topic, generate framework and search plan
- ② Collect data — tool built-in engine + sources.json parallel search → quality-triggered reinforcement → Scrapling batch fetch → data pool → quality check
- ③ Parallel writing — All chapters simultaneously, facts embedded in prompts
- ④ Validate & assemble — Batch validate → assemble → citations → QA
- ```
- > Total ~10-20 minutes. Complex topics may take longer, simple ones may be faster.
- ### Output Files
- Reports are saved as Markdown files in the skill's `reports/` directory, with date-timestamped filenames:
- ```
- <your skill install dir>/deep-research/reports/
- ```
- Open with any Markdown reader (Typora / Obsidian / VS Code etc.).
- You can also specify a custom output path — ask AI to configure it.
- **Local report browser page**: After each research run, AI auto-refreshes `reports-browser/index.html`. Open it directly in your browser (file:// protocol works) — all reports displayed in a searchable, filterable table with click-to-preview modal.
- ## 11. FAQ
- **1. Search quotas? How to ensure uninterrupted searching?**
- The system uses a **four-layer priority search** architecture (tool built-in engine → outline-suggested sources → sources.json → free source fallback), all issued in parallel, each layer auto-degrades on failure:
- - **Layer 0 — Tool built-in engine**: Auto-detects the tool's built-in search engine at runtime (e.g., `websearch` / `web_search`). If available, used as primary, runs in parallel with subsequent layers. No additional configuration needed.
- - **Layer 1 — Outline-suggested sources**: Task 1 recommends authoritative domains per topic (e.g., arctic-council.org, stats.gov.cn), searched first.
- - **Layer 2 — sources.json quality sources**: 30+ curated sources (Semantic Scholar / arXiv / Nature / World Bank / IMF / Reuters / BBC / Baidu Baike / Zhihu / 36Kr / iResearch / East Money etc.). Auto health check on startup, dead sources skipped.
- - **Layer 3 — Free source reinforcement (final fallback)**: triggered only when Layer 0-2 fail the per-sub-question quality gate (URL < 3 / outdated / no authoritative source for high-priority). DuckDuckGo / Bing / Brave / Mojeek / Semantic Scholar / GDELT / arXiv + 20+ Chinese sources. No API keys required, always available.
- **2. How to use local materials for report generation?**
- The skill has a built-in offline mode that generates fully-formatted reports (TOC, citations, metadata) from local files. Supported formats: **MD / TXT** (native read), **PDF** (AI auto-installs pypdf for text extraction), **DOCX** (AI auto-installs python-docx).
- Choose your scenario:
- **Scenario 1: Local materials + online supplement** (recommended for most complete research)
- ```
- Use the deep-research skill with my local files in D:\notes\projectA to generate a research report on XX (quick mode). Prioritize local content, search online for anything missing.
- ```
- **Scenario 2: Local materials only, no internet** (when you have sufficient data and don't want online distractions)
- ```
- Use the deep-research skill with my local files in D:\notes\projectA to generate a research report on XX (quick mode). Use only local materials, do not search online.
- ```
- The system skips the search/scraping pipeline and reads local files directly. Task 3 (chapter writing) and Task 4 (assembly/QA) run normally. The final output includes metadata, `[N]` citations, and TOC.
- **Scenario 3: Pure local, no skill** (lightweight, no professional format needed)
- ```
- Help me organize the materials in D:\notes\projectA into a structured research report with table of contents and chapter headings.
- ```
- > **Scenario guide**: Incomplete materials → Scenario 1 (online supplement); Sufficient materials + need professional format → Scenario 2 (offline mode); Quick summary only → Scenario 3 (lightweight).
- **3. How to update to the latest version?**
- **Version strategy**: `main` branch always has the latest code. GitHub Releases are only for milestone markers.
- All tools:
- - **Auto**: Type `/research-update`, AI auto-runs `git pull`
- - **Manual**: `cd <skill install dir>/deep-research && git pull`
- Check version: `cat <skill install dir>/deep-research/VERSION`
- **4. Can other tools auto-update?**
- Yes. All tools share the same all-platform codebase — just `git pull` in the install directory (or ask your AI to do it). There are no platform-specific changes to preserve, so updates never conflict.
- **5. Is my data safe?**
- All processing is done locally. No data is collected or uploaded.
- **6. How do I view my generated reports?**
- After each research run, the AI outputs both the report file path and the local report browser page path.
- - **Report file**: `{SKILLDIR}/reports/{LANG}/xxx.md` — open with any Markdown reader
- - **Local report browser page**: `{SKILLDIR}/reports-browser/index.html` — **open directly in your browser** (works with file:// protocol). All reports are displayed in a table with search, language/depth filtering, sorting, and click-to-preview in a modal
- You can also manually refresh the browser page anytime by running `python tools/generate_pages.py --local` in the skill directory.
- ## 12. Screenshot
- <img width="1532" height="836" alt="Screenshot 2026-06-09 at 11-28-17" src="https://github.com/user-attachments/assets/736b0113-f054-4dba-b018-e656a51a9fb4" />
- <img width="1532" height="932" alt="Screenshot 2026-06-09 at 11-30-13" src="https://github.com/user-attachments/assets/a88cbf27-7b6c-4ea3-8b51-424f48bf9906" />
- <img width="1524" height="846" alt="Screenshot 2026-06-09 at 11-30-55" src="https://github.com/user-attachments/assets/ef10865d-3a72-4658-ac9c-28b2221e77f5" />
- <img width="1528" height="840" alt="Screenshot 2026-06-09 at 11-32-13" src="https://github.com/user-attachments/assets/506e91eb-1d5d-4312-aceb-9280d357e264" />
- <img width="1438" height="842" alt="Screenshot 2026-06-09 at 11-35-03" src="https://github.com/user-attachments/assets/75acd450-9349-4024-923d-f9b14ea601dd" />
- ---
- <a id="chinese"></a>
- **深度调研报告生成 Skill — 一条命令,十分钟出券商级深度调研报告**
- 多 Agent 自动搜索、抓取、撰写、质检——输入主题,输出可引用、可浏览、可导出的中文/多语言调研报告。
- 对标券商/第三方研究机构结构:结论先行、来源可追溯、反方视角、情景预测。支持 quick / standard / deep 三档模式,19 种语言随主题自动切换。
- 适合行业研究、趋势前瞻、竞品扫描、政策解读、技术专题、投研备忘——不是搜几条摘要,是交付一份能拿去用的报告。
- > **当前版本:** [查看更新](https://github.com/hoolulu/deep-research/commits/main)
- >
- > 📂 **浏览所有示例报告 →** [H33研报· 深度调研报告集](https://www.h33.top)
- > 可筛选、排序、按语言和类型浏览所有示例报告。
- ---
- ### ✨ 一分钟看懂
- <table width="100%">
- <tr><td style="white-space: nowrap; width: 1%;"><b>🎯 一个命令</b></td><td><code>/research 你的主题</code> → 全自动调研,无需人工干预</td></tr>
- <tr><td style="white-space: nowrap;"><b>⏱ 十分钟出报告</b></td><td>quick 模式约 8–12 分钟,standard 约 10–15 分钟</td></tr>
- <tr><td style="white-space: nowrap;"><b>🌍 19 种语言</b></td><td>主题用什么语言写,报告就用什么语言出,自动检测</td></tr>
- <tr><td style="white-space: nowrap;"><b>🔧 所有平台通用</b></td><td>任何 AI 编程工具均可使用(Claude Code、Codex CLI、Cursor、DSH、Windsurf、Cline 等)</td></tr>
- <tr><td style="white-space: nowrap;"><b>📁 本地文件调研</b></td><td>也可支持本地 PDF/DOCX/TXT/MD,不联网,AI 自动解析</td></tr>
- <tr><td style="white-space: nowrap;"><b>🖥️ 本地报告浏览页</b></td><td>每次报告生成后自动刷新为本地浏览器页面<br><code>reports-browser/index.html</code>,支持搜索/筛选/排序/弹窗预览</td></tr>
- <tr><td style="white-space: nowrap;"><b>📄 PDF/DOCX 导出</b></td><td>本地浏览页弹窗中可导出 PDF、DOCX 格式,浏览器端直接转换下载</td></tr>
- </table>
- <table width="100%">
- <tr><th>命令</th><th>说明</th></tr>
- <tr><td style="white-space: nowrap;"><code>/research 中国新能源汽车产业发展现状</code></td><td>中文报告</td></tr>
- <tr><td><code>/research Competitive landscape of AI cloud computing</code></td><td>English report</td></tr>
- <tr><td><code>/research Анализ рынка нефти и газа в России</code></td><td>Отчёт на русском</td></tr>
- <tr><td><code>/research 日本のアニメ産業のグローバル市場戦略</code></td><td>日本語レポート</td></tr>
- <tr><td><code>/research 한국 반도체 산업의 글로벌 경쟁력 분석</code></td><td>한국어 보고서</td></tr>
- <tr><td><code>本地资料调研,详细命令见 FAQ</code></td><td>离线模式,读本地文件</td></tr>
- </table>
- > 是全程以设定语言与你交互,并搜索目标语言的资料,不是简单的翻译输出。
- ---
- ## 一、为什么你需要这个
- 让 AI 帮你做调研,你大概率碰过这些坑:
- - 搜索 + 总结 → 太浅,出来几条摘要,没有纵深
- - 行业报告按份收费 $50–500+ → 太贵,个人用不起
- - 海外工具 → 搜不到国内资源如:百度百科、知乎、199IT、艾瑞
- - AI 编数字 → 看起来合理,但找不到来源
- 这个 skill 走完 **4 层流程**才交报告。不是搜完就出,是析→搜验→写→验。
- ## 二、谁适合用
- **独立开发者**、**独立研究者**、**小团队**。
- 需要专业级调研能力,但不想依赖付费数据库或研究机构的人。
- ## 三、一次标准模式调研的输出
- | 指标 | 数据(standard 模式示例) |
- | ------- | ------------------------------------------- |
- | 报告长度 | 500-700 行 / 约 12,000-20,000 字(视语言浮动) |
- | 数据表 | 15-25 张,覆盖市场规模、竞争格局、技术参数等多个维度 |
- | 分析段落 | 80-120 段(每段含结论 + 数据 + 因果 + 判断) |
- | 引用的独立机构 | 15-25 家(中国信通院、艾瑞咨询、国家统计局、百度百科、知乎、36氪、澎湃新闻等) |
- | 反方观点 | 3-8 处,每章至少呈现一个争议或反对角度 |
- | 数据收集 | ~1-3 分钟 |
- | 报告生成 | ~8-15 分钟 |
- | 总耗时 | ~10-20 分钟 |
- > 以上为 standard 模式典型范围,实际因主题复杂度、数据可获取性、搜索引擎响应等因素有所浮动。|
- ### 📖 精选报告展示
- > 所有示例报告已迁移至 [H33研报· 深度调研报告集](https://www.h33.top),可筛选、排序、按语言和类型浏览。以下为部分精选主题:
- | 报告主题 | 话题标签 |
- |---------|---------|
- | <a href="https://www.h33.top" target="_blank">长江三角洲与珠江三角洲:中国两大经济引擎的地理比较</a> | 地理 · 经济 |
- | <a href="https://www.h33.top" target="_blank">郑和下西洋:为什么中国在 15 世纪放弃了海洋?</a> | 历史 · 航海 |
- | <a href="https://www.h33.top" target="_blank">玛雅文明崩溃之谜:干旱、战争还是生态超载?</a> | 历史 · 文明 |
- | <a href="https://www.h33.top" target="_blank">2026年中国新能源汽车行业展望</a> | 汽车 · 产业 |
- | <a href="https://www.h33.top" target="_blank">火星移民的工程现实:从 SpaceX 到 ISRU 到辐射防护</a> | 航天 · 科技 |
- 点击报告标题跳转到 H33 研报集,在站内搜索对应主题即可阅读。
- ## 四、成本
- | 组件 | 费用 |
- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
- | **LLM(你已经在用的)** | **DeepSeek v4 Flash** 基准:quick 约 10–15 万 token / < 0.2 元,standard 约 15–30 万 / < 0.4 元,deep 约 30–50 万 / < 0.7 元 |
- | **Scrapling 抓取** | 纯本地运行,零费用 |
- | **国内源(百度百科/维基百科/知乎/36氪/澎湃/199IT/艾瑞/东方财富/国统局等)** | 直连零费用,不要代理 |
- | **AI 工具运行时** | 开源免费,零费用 |
- > 以上估算基于 DeepSeek v4 Flash($0.14/百万输入、$0.28/百万输出,来源:`https://api-docs.deepseek.com/quick_start/pricing`)。实际因缓存命中率与主题复杂度浮动。
- ## 五、工作逻辑
- 整个流程分 4 个阶段,按顺序自动执行:
- ```
- ① 分析大纲 — 分析主题,生成调研框架和搜索计划
- ↓
- ② 采集数据 — ╭─ 在线模式:四层搜索并行(工具内置引擎 → 建议源 → sources.json → 免费源)→ Scrapling 批量抓取 → 数据池
- ╰─ 离线模式:直接读取本地文件(PDF/DOCX/TXT/MD)→ 数据池
- ↓
- ③ 并行撰写 — 所有章节同时撰写,事实直接嵌入 prompt,不做工具调用
- ↓
- ④ 验收装配 — 批量 validate → assemble-report → convert-citations → escape-currency → qa-report
- ```
- ## 六、搜索链路与内置资源
- 搜索采用 **四层优先级** 策略,全部并行发出:
- ```
- Layer 0 — 工具内置引擎(如 `websearch` / `web_search`,运行时自适应)
- Layer 1 — 大纲建议源(按主题定向推荐,如 arctic-council.org)
- Layer 2 — sources.json(skill 内置 30+ 优质源,启动时健康检测)
- Layer 3 — 免费源补强(A/B 类搜索兜底)
- ```
- 所有层的结果合并去重,由 Scrapling 统一抓取全文。免费源补强仅在 Layer 0-2 结果未通过逐子问题质量门时触发(子问题可用 URL < 3 / 结果年份过旧 / high 优先级子问题无权威来源)。
- `sources.json` 覆盖学术(Semantic Scholar / arXiv / PubMed / Nature)、数据(World Bank / IMF / Our World in Data)、新闻(Reuters / BBC / Guardian)、中文(百度百科 / 知乎 / 36氪 / 澎湃 / 艾瑞 / 东方财富 / CSDN 等)30+ 个源,启动时自动健康检测,死源跳过。
- ## 七、报告独特亮点
- | 维度 | 说明 |
- | ----------- | --------------------------------------- |
- | **多语言专业行文** | 自动检测主题语言,以 19 种语言直接撰写报告,非翻译模式 |
- | **每个数字有来源** | 正文标注 `(N)` 可点击引用,文末附参考来源列表。找不到来源的数字不写 |
- | **正反观点并存** | 每章呈现争议和反对观点,不回避矛盾 |
- | **置信度分级** | 末章汇总表(高/中/低),什么可靠什么有争议一目了然 |
- | **数据防坑机制** | 自动识别常见数据错误——单位搞混、数据造假、张冠李戴,不让有问题的数据混进报告 |
- | **段落重于行数** | 每章 8-12 段正文为核心,表格和空行灌不了水 |
- ## 八、三种深度
- | 命令 | 用途 | 最少章数 | 最少段落/章 | 参考字数(字符) | 参考耗时 |
- | --------------------- | ----------- | ---- | ------ | -------- | ---------- |
- | `/research 主题` | standard 默认 | 8 | ≥ 5 | ≈ 25,000 | ~10–15 min |
- | `/research 主题 -quick` | 快速洞察 | 5 | ≥ 4 | ≈ 15,000 | ~8–12 min |
- | `/research 主题 -deep` | 极致深度 | 10 | ≥ 6 | ≈ 45,000 | ~15–25 min |
- > 参数见 `profiles.json`,修改后重启生效。字数为去空格和 Markdown 语法的纯字符数。
- ## 九、安装
- deep-research 是**所有平台通用**的 skill:一套文件,放入任意支持 skill/命令机制的 AI 工具即可使用,无需按工具改写流程。
- ### 🧠 方式一:AI 傻瓜安装(推荐)
- 把下面这段提示词复制到你的 AI 工具聊天框发送,AI 会自动完成一切:
- ```text
- 请调研 https://github.com/hoolulu/deep-research 项目,按照文档要求依次完成:
- 1. 安装前置依赖(根据 Scrapling 官方文档和你的操作系统确定安装方式)
- 2. 注册 Scrapling MCP Server,确保重启工具后正常使用
- 3. 把本 skill 注册为当前工具的 skill / 命令入口(/research 和 /research-update)
- 每完成一步都确认结果,完成后读取 VERSION 确认版本号,并总结安装状态。
- ```
- AI 会读取项目文档→理解系统类型→逐项安装→验证可用性。不需要手动执行任何命令。
- ### 📋 方式二:手动注册命令入口
- 各工具的 skill/命令注册方式不同,把整个项目放进对应目录即可(以下为常见工具):
- | 工具 | skill/入口位置 | 命令形式 |
- |------|--------------|---------|
- | OpenCode | `~/.opencode/skills/deep-research/` | `/research`、`/research-update`(`command/` 已含) |
- | Codex CLI | skill 目录,`command/` 已含命令文件 | `/research`、`/research-update` |
- | Claude Code | `~/.claude/skills/deep-research/` | 用 SKILL.md 作为 Agent Skill |
- | Cursor | `.cursor/skills/` 或自定义命令 | 自定义命令指向 SKILL.md |
- | DSH / 其他 | 任意支持 skill 加载的目录 | 加载 SKILL.md 后输入主题 |
- > 本 skill 的 SKILL.md 已写成**所有平台通用**指令:不再依赖任何工具专属的 `task()` 等多 agent 语法。章节撰写默认并行(探测到多 agent 工具时),没有多 agent 能力的工具会自动降级为串行撰写,产物一致,仅耗时略增。搜索与抓取逻辑(Scrapling)各平台原样复用。
- ### 前置依赖
- | 组件 | 在线模式 | 离线模式 | 获取方式 |
- |:----|:--------|:--------|:--------|
- | **AI 工具运行时**(Claude Code / Codex CLI / Cursor / DSH / OpenCode 等) | ✅ 必须 | ✅ 必须 | 选择你习惯的工具即可 |
- | **Scrapling** | ✅ 必须 | ❌ 不需要 | 网页抓取用,离线模式不涉及 |
- > **平台说明**:支持多 agent 的工具(OpenCode、Claude Code、Codex、DSH 等)天然并行撰写章节;不支持多 agent 的工具自动串行撰写。离线模式下仅依赖 LLM 的文件读取能力,无需搜索/抓取组件。
- ## 十、使用方法
- 安装并重启你的 AI 工具后,在聊天框输入:
- | 命令 | 说明 | 参考耗时 |
- | ---------------------------------------------------------- | ----------- | ---------- |
- | `/research 你的主题` | standard 模式(在线搜索) | ~10-15 min |
- | `/research 你的主题 -quick` | quick 模式(在线搜索) | ~8-12 min |
- | `/research 你的主题 -deep` | deep 模式(在线搜索) | ~15-25 min |
- | `本地资料调研` | 离线模式(读本地文件) | 取决于文件大小 |
- | `/research-update` | 检查更新 | — |
- > 本地资料调研:具体指令词见 FAQ 第 2 节《如何使用本地资料生成报告?》。
- ### 发送后会发生什么
- 整个流程自动运行,你不需要做任何操作:
- ```
- ① 分析大纲 — 分析主题,生成调研框架和搜索计划(含 source_suggestions 定向源推荐)
- ② 采集数据 — 四层搜索并行(工具内置引擎→建议源→sources.json→免费源)→ Scrapling 批量抓取 → 数据池提取 → 数据质检
- ③ 并行撰写 — 所有章节同时撰写,事实直接嵌入 prompt,不做额外工具调用
- ④ 装配验收 — 批量 validate → assemble-report → convert-citations → escape-currency → qa-report
- ```
- > 以上累计 ~10-20 分钟。复杂主题可能延长,简单主题可能缩短。
- ### 输出文件
- 报告以 Markdown 格式保存到 skill 目录下的 `reports/` 文件夹,文件名包含日期时间戳:
- ```
- <你的 skill 安装目录>/deep-research/reports/
- ```
- 可以用任何 Markdown 阅读器(Typora / Obsidian / VS Code 等)打开。
- 你也可以指定报告的存放路径,让 AI 帮你修改。
- **本地报告列表页**:每次调研完成后,AI 自动刷新 `reports-browser/index.html`。直接用浏览器打开(支持 file:// 协议),所有报告以表格展示,支持搜索、按语言/深度筛选、排序,点击标题在弹窗中预览。
- ## 十一、FAQ
- **1. 搜索额度?怎么保证搜索不中断?**
- 系统采用 **四层搜索 + 质量触发补强** 架构:
- - **Layer 0 — 工具内置引擎(新增)**:运行时自动探测当前工具的内置搜索引擎(如 `websearch` / `web_search`)。如果可用,以此为主力搜索引擎,与后续层并行发出。无需额外配置。
- - **Layer 1 — 大纲建议源**:阶段1 根据主题定向推荐权威域名(如 moe.gov.cn、stats.gov.cn),用内置引擎做 `site:` 定向搜索。
- - **Layer 2 — sources.json 优质源**:skill 内置 30+ 精选源(Semantic Scholar / arXiv / Nature / World Bank / IMF / Reuters / BBC / 百度百科 / 知乎 / 36氪 / 艾瑞 / 东方财富 等)。启动时自动健康检测,死源跳过。
- - **Layer 3 — 免费源补强(兜底)**:当 Layers 0-2 合计结果质量不足(URL < 3 / 年份过旧 / 来源过少)时触发。DuckDuckGo / Bing / Brave / Mojeek / Semantic Scholar / GDELT / arXiv + 百度百科 / 知乎 / 199IT / 艾瑞 / 36氪 / 澎湃 / 东方财富 / 微博 / CSDN / 虎嗅 / 豆瓣 等 20+ 源。不依赖任何 API Key,永远可用。
- **2. 如何使用本地资料生成报告?**
- Skill 内置了离线模式,可以根据本地文件直接生成带有完整格式(目录/引用/元数据)的调研报告。支持的文件格式:**MD / TXT**(原生读取)、**PDF**(AI 自动安装 pypdf 提取文本)、**DOCX**(AI 自动安装 python-docx 解析)。
- 根据你的需要选择以下场景:
- **场景 1:本地资料 + 联网补充**(推荐,调研最完整)
- ```
- 请使用 deep-research 这个 skill,根据 D:\我的笔记\项目A 的本地资料,生成一份关于 XX 的研究报告(quick 模式)。本地资料里的内容优先作为素材,不够的你在网上搜索补充。
- ```
- **场景 2:只用本地资料,不联网**(适合资料足够、担心联网干扰主题的情况)
- ```
- 请使用 deep-research 这个 skill,根据 D:\我的笔记\项目A 的本地资料,生成一份关于 XX 的研究报告(quick 模式)。只看本地资料,不要联网搜索。
- ```
- 系统会跳过搜索/抓取流程,直接从指定文件提取数据,后续的章节撰写和装配 QA 正常执行。最终输出带有元数据、`[N]` 引用、目录的标准报告。
- **场景 3:纯本地,不用 skill**(最轻量,适合不需要专业报告格式的快速总结)
- ```
- 根据 D:\我的笔记\项目A 的资料,帮我整理成一份结构化的研究报告,要有目录和章节标题。
- ```
- > **场景选择建议**:资料不够全 → 场景 1(联网补充);资料足够且需要专业报告格式 → 场景 2(离线模式);只需快速总结 → 场景 3(最轻量)。
- **3. 如何更新到最新版本?**
- **版本策略**:`main` 分支始终是最新代码,日常小修改直接推送。GitHub Releases 仅用于里程碑版本标记(如 v2.1.0 → v2.2.0),不必等到新 Release 才更新。
- 任意工具的用户:
- - **自动**:输入 `/research-update`,AI 自动执行 `git pull` 获取最新
- - **手动**:`cd <skill 安装目录>/deep-research && git pull`
- 版本号可通过 `cat <skill 安装目录>/deep-research/VERSION` 查看。
- **4. 其他工具能自动更新吗?**
- 可以。所有工具共用同一套所有平台通用代码,直接在安装目录 `git pull` 即可(或让 AI 帮你执行)。没有平台特定的适配改动需要保留,因此更新不会产生冲突。
- **5. 数据安全吗?**
- 所有处理在本地完成。不收集、不上传任何用户数据。
- ## 十二、运行截图
- <img width="1532" height="836" alt="Screenshot 2026-06-09 at 11-28-17" src="https://github.com/user-attachments/assets/736b0113-f054-4dba-b018-e656a51a9fb4" />
- <img width="1532" height="932" alt="Screenshot 2026-06-09 at 11-30-13" src="https://github.com/user-attachments/assets/a88cbf27-7b6c-4ea3-8b51-424f48bf9906" />
- <img width="1524" height="846" alt="Screenshot 2026-06-09 at 11-30-55" src="https://github.com/user-attachments/assets/ef10865d-3a72-4658-ac9c-28b2221e77f5" />
- <img width="1528" height="840" alt="Screenshot 2026-06-09 at 11-32-13" src="https://github.com/user-attachments/assets/506e91eb-1d5d-4312-aceb-9280d357e264" />
- <img width="1438" height="842" alt="Screenshot 2026-06-09 at 11-35-03" src="https://github.com/user-attachments/assets/75acd450-9349-4024-923d-f9b14ea601dd" />
- ---
- ## License / 协议
- MIT
- This project uses MIT instead of GPL/CC because its core value is a portable methodology and pipeline design, not a copyrighted product. MIT maximizes reuse and adaptation across different platforms and toolchains, consistent with the "all-platform" positioning.
- 本项目采用 MIT 协议。选择 MIT 而非 GPL/CC 等更严格的协议,是因为本项目的核心是一套可移植的方法论和管道设计,而非需要保护版权的成品库。MIT 能让它在不同平台和工具链中被最大化地复用和改造,与"所有平台通用"的定位一致。
- ---
- ## Star History / 星标历史
- <a href="https://www.star-history.com/?repos=hoolulu%2Fdeep-research">
- <picture>
- <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=hoolulu/deep-research&type=date&theme=dark&legend=top-left" />
- <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=hoolulu/deep-research&type=date&legend=top-left" />
- <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=hoolulu/deep-research&type=date&legend=top-left" />
- </picture>
- </a>
- ---
- **Created by [hoolulu](https://github.com/hoolulu)** · [github.com/hoolulu/deep-research](https://github.com/hoolulu/deep-research)
- > Community discussion · 社区讨论:[LINUX DO](https://linux.do/t/topic/2312664)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.