本地化 Deep Research（SearXNG + 知识库混合）

基于自部署 Dify 1.16.x 工作流的深度研究系统：本地 SearXNG 搜索（零付费搜索 API）＋ 企业知识库混合证据源，通过「识别缺口 → 搜索 → 抓取 → 提炼 → 累积」的多轮迭代，产出带引用溯源的深度研究报告。配套纯标准库 MCP Server，可一键调用。

dify marketplace：https://marketplace.dify.ai/template/hyarinth/%E6%9C%AC%E5%9C%B0%E5%8C%96%20Deep%20Research%EF%BC%88SearXNG%20%2B%20%E7%9F%A5%E8%AF%86%E5%BA%93%E6%B7%B7%E5%90%88%EF%BC%89?templateId=25f43e17-ac77-42ab-9e79-c5df4a2ea4d6&creationType=templates

---

✨ 特性

• 🔍 零付费搜索：搜索走本地 SearXNG，不依赖 Tavily / Exa 等商业 API
• 📚 双证据源：网页实证 + 企业知识库补充，按证据顺序同流累积
• 🔁 迭代式深研：反思引擎识别缺口 → 生成查询 → 抓取提炼 → 多轮收敛
• 📎 引用可核验：报告 [n] 引用与 sources（URL + 文档名）一一对应
• 🛡️ 反爬自愈：直连抓取遇 403/4xx 自动经 Jina Reader 回退，不中断
• 🧩 MCP 一键接入：STDIO MCP Server，回调 Dify /v1/workflows/run

---

📁 目录结构

deep-research-dify/
├── workflows/                          # DSL（导入 Dify 使用）
│   ├── deep-research-searxng-serial.yml     # ✅ 串行版（推荐，已验证）
│   ├── deep-research-searxng-serial-en.yml  # 🌐 串行版·英文（⚠️ 未测试，理论可行）
│   ├── deep-research-searxng.yml            # ⚠️ 并行版（仅存档，不可用）
│   └── minimal-test.yml                     # 导入连通性最小测试
├── mcp-server/
│   ├── dify_mcp_stdlib.py               # ✅ 推荐：纯标准库，零依赖
│   └── dify_mcp_server.py               # 旧版：需 mcp SDK ≥1.4（不推荐）
├── docs/
│   ├── 交付说明.md                       # 交付细节 / 决策记录
│   └── test-英语学习.txt                 # 验收运行示例产物
├── README.md                            # 本文件（中文）
├── README.en.md                         # 英文版
├── LICENSE                              # MIT License
└── .gitignore

---

🚀 快速开始

环境要求

依赖	说明
Dify 自部署 1.16.x	工作流运行时（DSL version: "0.7.0"）
SearXNG（推荐 Docker）	本地搜索；Docker 网络内名 searxng，宿主机映射 127.0.0.1:8080
大模型 API	≥1 个强推理模型（Claude / DeepSeek-R1 / GPT），供 5 个 LLM 节点
企业知识库（可选）	无知识库也可运行，仅弱化知识来源

1. 导入 DSL

Dify →「创建应用」→「导入 DSL」→ 选择 workflows/deep-research-searxng-serial.yml。

🚫 请勿导入 deep-research-searxng.yml（并行版）——受 Dify 前端缺陷影响，仅存档、不可用。

2. 导入后必做配置（按顺序）

1. 5 个 LLM 节点重选模型（占位 openai/gpt-4o 不能直接用）；

2. 2 个知识检索节点重选知识库（kr_baseline / kr_refine，dataset_ids 为空占位）；

3. 环境变量（应用 → 开发 → 环境变量）：

   • searxng_base_url：Docker 网络内 http://searxng:8080；宿主机直连 http://127.0.0.1:8080；
   • user_agent：抓取请求 UA（已预置 Chrome 桌面 UA）。

4. SearXNG 前置：settings.yml 的 search.formats 含 json；自测：

   curl "http://127.0.0.1:8080/search?q=test&format=json"

3. 冒烟验证

• Dify 画布：右侧「运行」输入 topic（如 什么是大语言模型），end 输出 report + sources 即成功；
• MCP 客户端：调用 run_deep_research（见下）。

---

🧩 MCP 集成

工具	参数	返回
run_deep_research	topic（必填）· language（默认 中文）· max_iterations（默认 4，1~8）· user（默认 mcp-user）	{ok, task_id, status, outputs:{report, sources}, error}，阻塞等待完成

接入配置（Cherry Studio / claude 类通用）：

{
  "mcpServers": {
    "dify-deep-research": {
      "command": "python",
      "args": ["C:\\MyData\\Projects\\deep-research-dify\\mcp-server\\dify_mcp_stdlib.py"],
      "env": {
        "DIFY_BASE_URL": "http://127.0.0.1/v1",
        "DIFY_API_KEY": "<你的API-Key>",
        "DIFY_API_TIMEOUT": "600"
      }
    }
  }
}

• DIFY_BASE_URL：Dify 应用 → 开发 → API 访问 → API 服务器 URL；
• DIFY_API_KEY：应用级 API Key（app-...）；
• 若客户端启动时 PATH 找不到 python，command 用绝对路径（Windows where python）。

对话示例：

用深度研究调研"2026 年 RAG 在金融行业的落地实践"，输出中文报告

---

⚙️ 工作流运行机制

• 循环变量（deep_loop）：findings（证据累积）、executed_queries（防重复）、visited_urls（去重）、current_iteration（轮次）、knowledge_gaps（缺口记录）；
• 提前收敛：skip_check 遇到无可执行查询的空轮时仅推进轮次、不搜索——break_conditions: [] 下的正常收敛；
• Assigner：assigner_full 合并网页+知识库要点；assigner_min 仅推进轮次；
• 引用溯源：网页素材按 [n] 编号，知识库素材标 [知识库: <文档标题>]，build_sources 汇总对照报告正文。

---

🛡️ 反爬与抓取失败回退（串行版内置）

问题：http_fetch 直连抓取首条结果时，目标站反爬会直接 403（实测 zh.wikipedia.org 的 Wikimedia 机器人策略按 TLS 指纹拦截 Python httpx；同 URL 用 curl 均为 200）。此前命中即整轮失败。

方案（Dify 1.16 fail-branch 写法，已验证）：

flowchart LR
    HF[http_fetch 直连] -->|成功| CH[clean_html] --> Rest[...]
    HF -->|"失败 4xx/5xx/超时"| JN[http_fetch_jina<br/>r.jina.ai 代抓] --> CH

Loading

• 新增 http_fetch_jina：GET https://r.jina.ai/{{#parse_results.first_url#}}，读超时 90s、不重试；
• http_fetch 设 data.error_strategy: fail-branch，失败边 sourceHandle: fail-branch；
• clean_html 加 raw_jina 变量，代码首行 raw = raw or raw_jina or ""。

---

💸 成本与调优

• 每轮成本 ≈ 1 次搜索 + 1 页抓取（串行）+ 3~4 次 LLM 调用；
• max_iterations 建议 24（串行每轮只抓 1 页，可放宽到 48）；
• ⚠️ deep_loop.loop_count 为常量 4：Dify 1.16 loop 上限不支持变量引用，MCP 默认 max_iterations=4 即满轮；改大需同时改 start 默认值与 loop_count；
• Jina 免费额度：约 20 请求/分钟、20k token/次，作回退层足够。

---

🚑 故障排查

现象	原因与处理
返回 error: "Request failed with status code 403"	抓取被反爬 → 串行版已自动回退 Jina，无需处理；手工改过节点则检查 error_strategy: fail-branch 与回退节点
搜索节点报错	SearXNG 不可达或 format=json 未开 → 检查 searxng_base_url 与 search.formats
知识库输出「未找到相关内容」	知识库为空/未选择 → 在 kr_baseline / kr_refine 重选
导入后画布崩溃（forEach 报错）	deep_loop 的 break_conditions 被省略 → 必须保留为 break_conditions: []

---

📦 版本状态

版本	文件	状态	说明
✅ 串行版（推荐）	workflows/deep-research-searxng-serial.yml	已验证可用	每轮串行抓 1 页；画布全绿、一键发布；含 Jina 反爬回退
🌐 串行版·英文	workflows/deep-research-searxng-serial-en.yml	⚠️ 未测试（理论可行）	提示词/注释/描述全英文化；id/拓扑与中文版 1:1 一致（脚本校验过），故判定理论等价；导入需重选模型/知识库
⚠️ 并行版（仅存档）	workflows/deep-research-searxng.yml	不可用	受 Dify 前端缺陷（getValidTreeNodes 对 loop 内嵌 iteration 只展开一层）影响，发布被阻塞且无法以合法 DSL 规避；仅作存档，不维护

---

⚠️ 已知限制

1. loop_count 写死 4：改大需同步 start 默认值 + deep_loop.loop_count；
2. 环境变量字段格式：Dify 1.16 需 id+name+value+value_type+description（旧版 variable: 已失效）；
3. loop_variables.value 必须为字符串：array 存 JSON 编码字符串（如 "[]"），否则 Loop 面板崩溃；
4. 5 个 LLM 节点为占位模型：导入后必须手动重选；
5. 并行版停用：Dify 前端缺陷致无法发布验证，仅存档。

---

📜 更新记录

日期	内容
2026-08-19	初版交付：并行 + 串行 DSL、MCP Server、交付说明；记录 Dify 1.16 导入排障
2026-08-21	串行版跑通全流程；新增 Jina 抓取回退（根治 403）；并行版标注【仅存档】；新增英文 DSL、README（中/英）、.gitignore、MIT LICENSE；目录结构整理为 workflows/ + docs/

---

📄 License

本项目采用 MIT License，详见 LICENSE。需修改版权署名或更换许可证请与项目所有者确认。

---

完整决策记录见 docs/交付说明.md。

项目使用了DeepSeek等AI辅助。

dify-deep-research