Deep Research Agent 完整教學

1. 專案定位與核心價值

這是什麼？

Deep Research Agent（又名 Deep Science Writer）是一套工業等級的端到端 scientific research pipeline (科學研究管線)，專為 Hermes/ECC framework (Hermes/ECC 框架) 打造的 AI agent skill。它完全自動化學術 literature review (文獻回顧) 流程 — 從主題規劃、跨資料庫論文蒐集、全文深度閱讀、反幻覺驗證，到 APA 第 7 版 .docx 產出與知識庫匯入。

核心價值主張

誰適合用？

• 需要快速完成系統性文獻回顧的研究生與博士後
• 需要產出 Nature/Science 等級嚴謹度報告的研究團隊
• 使用 Hermes Agent 或相容 ECC/Claude Code 環境的 AI 使用者
• 重視引用可靠性、零幻覺容忍的學術寫作者

2. 安裝指南

2.1 前置需求

1系統需求:
2├── Hermes Agent（或相容 ECC/Claude Code runner）
3├── Node.js v18+（含 npx）
4├── Python 3.10+
5└── pip 套件: python-docx, PyMuPDF, requests, matplotlib, seaborn, pandas, duckduckgo_search

2.2 安裝步驟

 1# 1. Clone 到你的 agent skills 目錄
 2cd <AGENT_SKILLS_DIR>
 3git clone https://github.com/CYC2002tommy/Deep-Research-Agent.git
 4
 5# 2. 安裝 Python 依賴
 6pip install python-docx PyMuPDF requests matplotlib seaborn pandas duckduckgo_search
 7
 8# 3. 設定 MCP Servers（在 config.yaml 或 claude_desktop_config.json）
 9# 必要: scopus-mcp（需 Scopus API Key）
10# 必要: notebooklm-mcp-server（需 Google 帳號認證）
11# 建議: exa-search、github-mcp、playwright-mcp

2.3 環境變數

 1# 必要
 2export SCOPUS_API_KEY="your-elsevier-api-key"        # 申請: https://dev.elsevier.com/
 3export SEMANTIC_SCHOLAR_API_KEY="your-s2-api-key"     # Semantic Scholar API
 4
 5# Zotero 整合（Phase 4.6）
 6export ZOTERO_API_KEY="your-zotero-key"
 7export ZOTERO_LIBRARY_ID="16500033"                   # 注意：必須是數字 ID，不是使用者名稱
 8export ZOTERO_LIBRARY_TYPE="user"
 9
10# 路徑設定（建議用環境變數取代硬編碼路徑）
11export OBSIDIAN_VAULT_PATH="/path/to/your/vault"
12export RESEARCH_OUTPUT_DIR="/path/to/output"

2.4 NotebookLM 認證

1# 首次使用需在終端機執行一次 Google 帳號認證
2npx notebooklm-mcp-server auth

2.5 網路環境建議

Phase 4.6（Zotero 歸檔 + PDF 下載）使用 cloakbrowser 繞過 Cloudflare 與出版商付費牆。強烈建議在大學或學術機構網路環境下執行，利用機構 IP 授權存取 Wiley、Elsevier 等限制資料庫。

3. 核心架構解析

3.1 7 階段管線架構圖

flowchart TD
    subgraph "Phase 0: 計畫與核準"
        P0[研究計畫擬定] --> P0A[使用者明確核准]
    end

    subgraph "Phase 0.5: 背景蒐集"
        P05A[大規模摘要篩選
100+ 篇] --> P05B[全文下載
Top 20-30 篇]
        P05B --> P05C[深度閱讀 + 缺口分析報告]
        P05C --> P05D[使用者核准 Gap Report]
    end

    subgraph "Phase 1: 多代理人探索"
        P1A[Subagent 1
Scopus]
        P1B[Subagent 2
Exa Search]
        P1C[Subagent 3
OpenAlex]
        P1D[Subagent 4
Semantic Scholar]
    end

    subgraph "Phase 2: 深度提取"
        P2[CloakBrowser 全文提取
+ 交叉驗證]
    end

    subgraph "Phase 3: 結構化起草"
        P3[APA 7th 格式草稿
+ Mermaid/方程式]
    end

    subgraph "Phase 4/4.5: 反幻覺驗證"
        P4A[DOI 存活測試] --> P4B[聲明實證比對]
        P4B --> P4C{100% 驗證通過?}
        P4C -->|否| P4D[二次搜尋替代文獻]
        P4D --> P4A
        P4C -->|是| P46[Phase 4.6: Zotero 歸檔]
    end

    subgraph "Phase 5: Remi 同儕審查"
        P5A[10 維度嚴格審查] --> P5B{通過?}
        P5B -->|否| P5C[退回 Phase 1/2 補強]
        P5B -->|是| P6
    end

    subgraph "Phase 6: 最終產出"
        P6[python-docx 編譯 .docx
+ AntV 圖表]
    end

    subgraph "Phase 7: 知識圖"
        P7A[Obsidian Vault 更新]
        P7B[NotebookLM 來源匯入]
    end

    P0A --> P05A
    P05D --> P1A & P1B & P1C & P1D
    P1A & P1B & P1C & P1D --> P2
    P2 --> P3
    P3 --> P4A
    P46 --> P5A
    P5C --> P1A
    P6 --> P7A & P7B

3.2 檔案結構

 1Deep-Research-Agent/
 2├── skills/
 3│   ├── deep-science-writer/
 4│   │   ├── SKILL.md              ← 主要管線定義（150 行，7 個 Phase）
 5│   │   ├── scripts/
 6│   │   │   ├── mermaid_to_png.py      ← Mermaid 圖轉 PNG
 7│   │   │   ├── verify_urls.py         ← DOI/URL 驗證（DuckDuckGo + requests）
 8│   │   │   └── node/
 9│   │   │       ├── fetch_openalex_papers.js   ← OpenAlex 查詢（含 MDPI 過濾）
10│   │   │       ├── fetch_unpaywall_oa.js      ← Unpaywall OA PDF 定位
11│   │   │       ├── generate_docx.js           ← APA 7th DOCX 生成
12│   │   │       ├── scrape_html_fulltext.js    ← HTML 全文提取
13│   │   │       └── extract_pdf_text.js        ← PDF 文字提取
14│   │   └── references/
15│   │       ├── academic-api-patterns.md   ← Crossref/OpenAlex API 樣式
16│   │       └── python-docx-manipulation.md
17│   └── remi/
18│       └── SKILL.md              ← Remi 同儕審查 skill（10 維度框架）
19├── tests/
20│   ├── test_mermaid_to_png.py    ← Mermaid 轉換測試
21│   └── test_verify_urls.py       ← URL 驗證測試
22├── references/
23│   └── path-safety.md            ← 路徑安全防護文件
24├── requirements.txt              ← Python 依賴清單
25├── LICENSE                       ← MIT
26└── README.md

3.3 技術堆疊

4. 主要功能與 API 詳解

4.1 多代理人學術檢索（Phase 1）

管線強制派發 4 個並行子代理人，每個專責一個資料庫：

1delegate_task 調度:
2├── Subagent 1 → scopus-mcp（Elsevier 權威資料庫）
3├── Subagent 2 → exa-search（神經網路搜尋 + OA 探索）
4├── Subagent 3 → OpenAlex API（via Node.js，嚴格過濾 MDPI）
5└── Subagent 4 → Semantic Scholar API（需 API Key 繞過速率限制）

品質過濾規則：

• 僅收錄 Q1-Q2 期刊
• Q3 若為關鍵證據需明確標記 [Q3]
• 嚴格排除所有 Q4 與 MDPI 出版品（DOI prefix 10.3390、host_organization_name 含 “mdpi”）
• 結果必須以結構化 Markdown 表格呈現：| Title | Authors/Year | Key Finding | URL/DOI |

4.2 反幻覺驗證系統（Phase 4.5）

這是本專案最核心的差異化功能：

1. DOI 存活測試：對參考文獻中每個 DOI/URL 執行 HTTP HEAD 請求
2. 聲明實證比對：將草稿中的聲明與 Phase 1/2 蒐集的原始資料交叉驗證
3. 嚴格文字主義：禁止過度延伸發現（不可將全球研究套用到單一城市）
4. 連續替換迴圈：死連結不是刪除，而是觸發二次搜尋找到替代的 Q1/Q2 論文
5. 通過條件：零死連結、零假 DOI、零無根據聲明、100% 引用驗證通過

 1# verify_urls.py 核心邏輯（簡化版）
 2import requests
 3from duckduckgo_search import DDGS
 4
 5def verify_doi(doi: str) -> bool:
 6    """透過 Crossref API 驗證 DOI 是否存活"""
 7    resp = requests.get(
 8        f"https://api.crossref.org/works/{doi}",
 9        timeout=10
10    )
11    return resp.status_code == 200
12
13def find_replacement(claim: str) -> dict:
14    """DOI 失效時，用 DuckDuckGo 搜尋替代文獻"""
15    with DDGS() as ddgs:
16        results = ddgs.text(claim, max_results=5)
17        return results[0] if results else None

4.3 Remi 同儕審查（Phase 5）

內建以指導教授 Remi Chauvy 命名的 AI 審查員，採用 10 維度框架：

1. 科學品質與新穎性
2. 方法論與假設
3. 一致性與連貫性
4. 結果與詮釋
5. 圖表與呈現
6. 文獻回顧完整性
7. 影響力與相關性
8. 元敘述與語氣（嚴格剝離 AI 贅詞）
9. 重大與次要問題清單
10. 最終建議（Accept / Minor / Major / Reject）

禁用 AI 詞彙清單：delve、tapestry、in conclusion、crucial、testament、realm、fosters、underscores、moreover

4.4 DOCX 生成（Phase 6）

最終產出不是 Markdown，而是程式化建構的 Word 文件：

 1// generate_docx.js 核心邏輯（APA 7th 格式）
 2const { Document, Paragraph, TextRun } = require('docx');
 3
 4// APA 7th hanging indent
 5new Paragraph({
 6    text: referenceText,
 7    indent: {
 8        left: 720,      // 0.5 inch left indent
 9        hanging: 720    // 0.5 inch hanging indent
10    }
11});

4.5 Zotero 整合（Phase 4.6）

• Unpaywall API 優先取得 OA PDF
• CloakBrowser 繞過 Cloudflare/付費牆下載受限 PDF
• pyzotero 建立 Parent Item（title、authors、year、DOI）
• 自動上傳 PDF 附件到 Zotero

5. 應用場景與實戰範例

場景 1：系統性文獻回顧

 1使用者: "Please use the deep-science-writer skill to research the sociological 
 2and psychological acceptance of sustainability policies, segmented by age (public) 
 3and firm size (SMEs vs Large Enterprises)."
 4
 5Agent 執行流程:
 61. Phase 0: 擬定研究計畫 → 呈現藍圖 → 等待核准
 72. Phase 0.5: 背景抓取 100+ 篇 → 篩選 25 篇全文深讀 → Gap Report
 83. Phase 1: 4 個子代理人平行查詢 → 結構化表格
 94. Phase 2-4.5: 深度提取 → 起草 → 反幻覺驗證
105. Phase 5: Remi 審查 2-3 輪
116. Phase 6: 輸出 APA 7th .docx + AntV 圖表
127. Phase 7: 更新 Obsidian + NotebookLM

場景 2：氣候變遷都市影響比較研究

此為 README 中引述的實際案例，研究巴黎、福岡等城市的乾旱韌性。管線特別處理：

• 地理過度外推防護：不將全球乾地研究結果套用到單一城市
• 植物功能類型區分：嚴格區分淺根草本與深根喬木的乾旱反應
• 概念拼接禁止：不將巨觀研究（如行星邊界）與區域分析混為一談

場景 3：跨學科多變數研究

當研究涉及 4+ 個獨立變數（如比較 4 個城市）：

• 禁止合併搜尋（“Paris AND Fukuoka AND Singapore drought” → 零結果）
• 拆解為原子搜尋（“Paris drought NPP”、“Singapore UHI NPP”）
• 個別蒐集後再合成比較

6. 資安掃描報告

掃描範圍

對 /tmp/Deep-Research-Agent 完整 clone 進行靜態分析，檢查 .py、.js、.ts、.sh 檔案中的敏感模式。

發現摘要

🔴 高風險（已由社群修復）

🟡 中風險（需注意）

🟢 低風險 / 良好實踐

安全建議

1. 務必在受信任網路（大學/機構）環境下執行全文下載管線
2. 將 fetch_openalex_papers.js 中的 email 改為環境變數
3. 考慮以 Crossref API 作為主要 DOI 驗證方式，減少第三方查詢洩漏
4. 執行前確認所有環境變數（SCOPUS_API_KEY、ZOTERO_API_KEY 等）已正確設定

7. FAQ 常見問題

Q1: Deep Research Agent 與 ChatGPT 的 Deep Research 功能有何不同？

Deep Research Agent 是一個開源、可自架的完整管線，特色在於：

• 強制全文閱讀（不只讀摘要）
• DOI 100% 存活驗證
• 嚴格的期刊等級過濾（Q1-Q2 only）
• 可整合 Zotero、Obsidian、NotebookLM 的知識管理生態
• 輸出為可編輯的 .docx，不是純文字

Q2: 一次研究管線需要多少時間和 API 額度？

取決於主題廣度。典型的 25 篇全文回顧約需：

• 執行時間：1-3 小時（含 Remi 審查迭代）
• Scopus API：~50-100 次查詢
• Semantic Scholar API：~50-100 次查詢（有 Key 可繞過速率限制）
• LLM token：因管線長度而大量消耗，建議監控 token 用量

Q3: 可以在 Windows 以外的環境執行嗎？

原始設計以 Windows + MSYS bash 為主，但核心邏輯為 Python + Node.js，理論上可在 Linux/macOS 執行。需注意：

• 路徑格式需調整（已有環境變數修復）
• CloakBrowser 需確認跨平台相容性
• py 命令在 Linux 需改為 python3

Q4: 沒有 Scopus API Key 可以用嗎？

可以部分使用。Phase 1 的 4 路搜尋中，OpenAlex 和 Semantic Scholar 不需付費 API Key。Exa Search 需要帳號但有免費額度。缺少 Scopus 會降低覆蓋率但管線仍可運作。

Q5: Remi 審查經常退回，如何改善？

• 確保 Phase 0.5 的 Gap Report 足夠詳盡
• 避免聲明過度延伸（嚴格文字主義）
• 移除所有 AI 贅詞後再送審
• Remi 迴圈已設上限 3 輪（Issue #2 修復）

8. 進階技巧與最佳實踐

8.1 搜尋策略優化

1✅ 正確做法: 原子搜尋 → 合成
2   "Paris drought NPP vegetation" → 10 篇
3   "Singapore UHI green infrastructure" → 12 篇
4   "Tokyo flood resilience urban planning" → 8 篇
5   → 合成比較表格
6
7❌ 錯誤做法: 合併搜尋
8   "Paris Singapore Tokyo drought UHI flood NPP" → 0 篇

8.2 品質過濾微調

在 Phase 1 子代理人中可額外設定：

• publication_year 過濾（建議近 10 年）
• has_abstract:true 確保有摘要可篩選
• type:article 排除會議論文或書籍章節
• OpenAlex host_organization_name 排除特定出版商

8.3 大規模研究的子代理人管理

• 每個子代理人處理 ≤ 5 個原子搜尋
• 使用 delegate_task 控制並行數量
• 背景任務使用 terminal(background=true, notify_on_complete=true)
• 監控每輪的 token 消耗，避免 context window 溢出

8.4 反幻覺驗證強化

 1# 進階: 使用 Crossref API 作為主要驗證（比 DuckDuckGo 更隱私）
 2import requests
 3
 4def verify_via_crossref(doi: str) -> dict:
 5    """驗證 DOI 並取得完整 metadata"""
 6    url = f"https://api.crossref.org/works/{doi}"
 7    resp = requests.get(url, timeout=10)
 8    if resp.status_code == 200:
 9        data = resp.json()['message']
10        return {
11            'valid': True,
12            'title': data.get('title', [''])[0],
13            'doi': data.get('DOI'),
14            'publisher': data.get('publisher')
15        }
16    return {'valid': False}

8.5 環境變數最佳實踐

建議使用 .env 檔案統一管理：

1# .env（不要提交到版本控制）
2SCOPUS_API_KEY=xxx
3SEMANTIC_SCHOLAR_API_KEY=xxx
4ZOTERO_API_KEY=xxx
5ZOTERO_LIBRARY_ID=12345678
6OBSIDIAN_VAULT_PATH=/home/user/vault
7RESEARCH_OUTPUT_DIR=/home/user/research

9. 整合進其他工作流

9.1 與 CI/CD 整合

可將 verify_urls.py 作為 CI 步驟，在每次文件更新時自動驗證所有引用：

 1# .github/workflows/verify-citations.yml
 2name: Verify Citations
 3on: [push]
 4jobs:
 5  verify:
 6    runs-on: ubuntu-latest
 7    steps:
 8      - uses: actions/checkout@v4
 9      - run: pip install requests duckduckgo_search
10      - run: python scripts/verify_urls.py --input refs.json

9.2 與 Zotero 生態整合

Phase 4.6 的 Zotero 整合使研究成果可直接進入：

• Zotero 引用管理器 → Word/Google Docs 自動插入引用
• ZotFile → PDF 自動重命名與組織
• Better BibTeX → LaTeX 引用匯出
• Zotero Groups → 團隊共享文獻庫

9.3 與 Obsidian 知識網路整合

Phase 7 將研究摘要寫入 Obsidian Vault，可搭配：

• Dataview 外掛查詢特定主題的所有研究
• Graph View 視覺化研究主題間的關聯
• Templater 自動化研究筆記模板

9.4 單獨使用子模組

不需要完整管線時，可獨立使用：

• verify_urls.py：任何專案的引用驗證工具
• fetch_openalex_papers.js：OpenAlex 論文搜尋 + MDPI 過濾
• fetch_unpaywall_oa.js：DOI → OA PDF URL 轉換
• mermaid_to_png.py：Mermaid 語法 → PNG 圖檔
• generate_docx.js：APA 7th 格式 Word 文件生成

10. 重點摘要 Checklist

• 確認 Node.js v18+ 與 Python 3.10+ 已安裝
• 安裝所有 Python 依賴（requirements.txt）
• 設定 MCP Servers（scopus-mcp 為必要）
• 配置環境變數（API Keys、路徑）
• 理解 7 Phase 管線架構與各階段職責
• Phase 1 強制 4 路子代理人平行查詢
• Phase 4.5 反幻覺驗證是核心差異化功能
• Remi 審查上限 3 輪（避免無限 API 成本）
• 搜尋策略使用原子搜尋，避免合併搜尋零結果
• 嚴格排除 MDPI/Q4，僅收錄 Q1-Q2 期刊
• 輸出為程式化 APA 7th .docx，非純 Markdown
• 建議在學術機構網路環境下執行全文下載
• 研究成果自動歸入 Obsidian + NotebookLM + Zotero

11. 進一步閱讀

專案相關

• Deep Research Agent GitHub — 原始碼
• Security Audit (Issue #2) — 完整資安審計報告
• BGPT Evidence API 建議 (Issue #4)

API 文件

• Elsevier Developer Portal — Scopus API Key 申請
• OpenAlex API Docs — 開放學術資料庫
• Semantic Scholar API — AI 學術搜尋引擎
• Unpaywall API — OA PDF 定位服務
• Crossref API — DOI 驗證與 metadata

相關工具

• pyzotero — Zotero Python 客戶端
• python-docx — Word 文件程式化生成
• AntV Infographic — 資料視覺化框架
• CloakBrowser — 反偵測瀏覽器自動化

12. 與 AI-Knowledge Template (AIKT) 的關聯性

12.1 定位比較

Deep Research Agent 與 AIKT 的 Layer 18: research-pipeline-v2 (多管線研究工作流 v3) 在目標上高度重疊 — 兩者都致力於自動化嚴謹的學術研究流程。但方法論與架構哲學有顯著差異：

12.2 方法論差異深度分析

品質保證策略

Deep Research Agent 採用 Remi 模式 — 在管線末端設置一個擬人化的同儕審查者，以 Nature/Science 的 10 維度框架嚴格審查草稿。這是一種「先寫後審」的策略。

AIKT Layer 18 採用 superpowers chain 模式 — 在管線的每個節點都設有 gate（brainstorm gate → spec review → plan review → execution checkpoint）。這是一種「每步皆審」的策略，且 spec/plan 寫完需過 requesting-code-review skill 審核才送使用者。

反幻覺機制

Deep Research Agent 的 Phase 4.5 是主動驗證型 — 對每個 DOI 發 HTTP 請求確認存活，死連結觸發二次搜尋。這能確保引用的「連結有效性」，但不直接驗證「聲明與來源的語義一致性」（需靠人工交叉比對）。

AIKT 的 paper-qa-lite (Layer 10) 是 RAG 語義驗證型 — 將原始論文建立向量索引，每個聲明透過 retrieval 比對原文段落，附上 (pqac-xxx) 引文代碼。這能驗證「聲明是否真的出自該來源」，但不驗證 DOI 連結有效性。

互補整合點：兩套機制正好互補。理想管線應同時具備 DOI 存活驗證（Deep Research Agent 方式）+ RAG 語義引文驗證（AIKT 方式）。

搜尋覆蓋範圍

Deep Research Agent 主攻 4 個資料庫（Scopus、Exa、OpenAlex、Semantic Scholar），偏向 STEM 與環境科學。

AIKT Layer 9 (paper-search) 覆蓋 10 個資料庫，額外包含 PubMed、PMC（全文）、bioRxiv、medRxiv、arXiv、CORE、Unpaywall，偏向生物醫學與預印本生態。

12.3 可能的整合策略

策略 A：Deep Research Agent 作為 AIKT Layer 18 的子模組

將 Deep Research Agent 的 Remi 審查機制與 DOI 驗證系統整合進 AIKT Layer 18：

1AIKT Layer 18 (research-pipeline-v2)
2├── Stage 1: Brainstorm（既有）
3├── Stage 2-5: 並行 dispatch（既有）
4│   └── paper-search (Layer 9) + Deep Research Agent Phase 1 子代理人
5├── Stage 6: paper-qa-lite RAG 驗證（既有）
6├── Stage 6.5: Deep Research Agent Phase 4.5 DOI 驗證 ← 新增
7├── Stage 7: Remi 10 維度審查 ← 新增（取代或補充 code-review）
8├── Stage 8: quarkdown HTML 輸出（既有）
9└── Stage 9: Discord 打包（既有）

策略 B：引用驗證工具獨立移植

將 verify_urls.py 與 Crossref API 驗證邏輯移植為 AIKT 的獨立 Layer：

1# 可作為 paper-search (Layer 9) 或 paper-tutorial (Layer 15) 的後處理步驟
2python verify_urls.py --input inbox/Paper/2026-06-23/topic/references.json

策略 C：Remi Skill 移植為 AIKT 審查層

將 Remi 的 10 維度審查框架整合進 AIKT 的 requesting-code-review 或建立獨立的 academic-review skill，專用於學術內容的品質把關。

12.4 與其他 AIKT Layer 的關聯

12.5 整合建議總結

1. 最小整合：將 verify_urls.py 移植為 AIKT 工具函式，供 Layer 9/15/18 呼叫
2. 中度整合：引入 Remi 10 維度審查作為學術內容專用的品質 gate
3. 深度整合：將 Deep Research Agent 整個管線包裝為 AIKT Layer 23，以 dra: prefix 觸發，共享 inbox/projects 目錄結構與 Discord 打包流程
4. 互補使用：保持兩套系統獨立運作 — Deep Research Agent 用於需要 .docx 正式輸出的場景，AIKT Layer 18 用於需要 HTML 教學交付的場景