hecailiaoPFS/firecrawl-research-engine

Firecrawl 研究引擎（DSH 技能）

面向 LLM 智能体的技术研究与验证技能。它先用 Firecrawl 搜索，跨来源交叉核对事实，并在不可用时优雅降级到内置网页搜索——从而让答案准确、可追溯、且不易产生幻觉。

中文说明见文末 / Chinese README at the bottom ↓

这是什么

一个 DSH（DeepSeek Harness） 技能，可将 LLM 智能体转变为技术研究与验证引擎。当用户询问具体参数、版本、代码细节或近期发布时，该技能会：

1. 优先搜索：使用 Firecrawl 的 Search API（而非仅抓取）——返回 Top-N 结果，并附带完整页面 Markdown 正文
2. 可选重新抓取：对 1-2 个最权威的 URL 重新抓取，以补齐缺失细节
3. 优雅降级：当 Firecrawl 不可用时，降级到内置的 web_search
4. 回退：当网络上无相关内容时，回退到本地知识，并给出明确的 ⚠️ 警告
5. 验证并引用：跨 ≥2 个来源交叉核对硬事实，始终内联引用 [来源: 标题 + URL]，并将矛盾之处并排呈现

其目标是在技术问题上最大程度减少幻觉，同时控制成本（每次对话 ≤10 次 Firecrawl 调用）并限制延迟（请求超时 15 秒）。

该技能可与任何能够加载 SKILL.md 并调用 MCP 工具的智能体配合使用——DSH、Claude Code、Codex、Cursor 等。参见 references/INSTALLATION.md。

为什么选择 Firecrawl（而非仅普通搜索）

| | 内置 web_search | Firecrawl Search |
| :--- | :--- | :--- |
| 搜索 + 摘要片段 | ✅ | ✅ |
| 完整页面 Markdown 正文 | ❌ | ✅（自动抓取 Top-N 结果） |
| JS 渲染 / 反爬 | ❌ | ✅ |
| 免费额度 | ✅ | ✅（有速率限制，可免费起步） |

Firecrawl 的 Search API 返回 data.web[]——每个条目包含 title、url、description，以及 markdown 中的完整页面正文（单个文档页面可达数十 KB）。这正是该技能所围绕的“更多技术细节”。完整 API 参考（已对照线上 v2 API 验证）：references/FIRECRAWL-API.md。

实战踩坑（Windows）

在实际部署过程中遇到并验证了两个不明显的问题。在 Windows 上安装或首次配置 MCP 服务器之前，请先阅读本节。完整说明见 docs/TROUBLESHOOTING.md。

1. Windows 沙箱会破坏 shell 内 HTTPS 调用的 TLS

DSH 的 Windows 沙箱在 WRITE_RESTRICTED 受限令牌下执行命令，该令牌仅允许在工作区内和私有临时目录中写入。TLS 握手需要写入用户的证书/密钥缓存（%APPDATA%\Microsoft\Crypto\RSA、%APPDATA%\Microsoft\SystemCertificates）；这些写入被拒绝，因此每次 HTTPS 调用都会失败并报 SEC_E_NO_CREDENTIALS (0x8009030e)——而纯 TCP 和 DNS 仍然正常。
这是对令牌的内核级访问检查，不是防病毒问题。禁用 Windows 安全中心没有帮助。可靠的修复方法是使用 Firecrawl MCP 服务器，它由 DSH 宿主进程在命令沙箱之外启动，因此能正常执行 TLS。否则，沙箱内的直接 API 调用将需要 danger-full-access 模式（每次调用都会弹出一次批准提示）。

2. 首次启动 MCP 可能超过 60 秒的连接超时

首次运行 npx -y firecrawl-mcp 会下载该包以及大约 40 个依赖项（1-2 分钟），这超过了 MCP 客户端默认的 60 秒连接超时。客户端会断开连接，服务器进程也随之退出。这是时序问题，而非协议不兼容。

让首次尝试失败，然后触发一次 HMR 重载（编辑 cordis.patch.yml）或重启 DSH；此后 npx 缓存已预热，连接会在几秒内完成。不要删除 npx 缓存目录，否则超时会再次出现。

要求

- 任何加载 SKILL.md 技能的 agent（DSH、Claude Code、Codex、Cursor……）
- 可选但推荐：Firecrawl API 密钥（ 提供免费套餐）——设置为环境变量 FIRECRAWL_API_KEY
- 可选但在 Windows 上推荐：Firecrawl MCP 服务器（npm 上的 firecrawl-mcp）——参见上文的注意事项

安装

1. 安装技能指令

| 环境 | 位置 |
| :--- | :--- |
| DSH（用户级） | ~/.dsh/skills/firecrawl-research-engine.md（Windows：%USERPROFILE%\.dsh\skills\） |
| DSH（项目级） | /.dsh/skills/（优先） |
| Claude Code | ~/.claude/skills/firecrawl-research-engine/SKILL.md |
| Codex | ~/.codex/skills/firecrawl-research-engine/SKILL.md |
| Cursor | .cursor/skills/ 或全局技能目录 |

各环境的完整说明：references/INSTALLATION.md。

2. 配置 Firecrawl（任选其一）

选项 A —— Firecrawl MCP 服务器（推荐）：

any MCP-capable client
export FIRECRAWL_API_KEY=fc-xxxx
register the server: npx -y firecrawl-mcp

DSH 配置文件 cordis.patch.yml 示例——完整文件见 examples/cordis.patch.yml：

- insert:
- id: mcp-firecrawl
name: '@deepseek-ai/dsh-mcp-client'
config:
serverName: firecrawl
transport: stdio
command: npx.cmd        # Windows; use npx on macOS/Linux
args: ['-y', 'firecrawl-mcp']
toolCallTimeoutMs: 120000
env:
FIRECRAWL_API_KEY: !!js process.env.FIRECRAWL_API_KEY

随后该技能会看到 mcp__firecrawl__search / mcp__firecrawl__scrape 等（25 个工具），并使用它们，且无需每次调用都弹出批准提示。首次启动时，请参见上文注意事项部分中的超时说明。

选项 B —— 直接 API 调用（不使用 MCP）： 参见 references/FIRECRAWL-API.md（curl / pwsh / node 示例，已验证的响应结构 data.web[]）。
选项 C — 完全不配置： 该技能仍然可用——它会降级到内置的 web_search，并用 🔎 标注答案。反幻觉行为（引用、交叉验证、矛盾揭示）独立于 Firecrawl。

工作原理（层级阶梯）

用户提问（技术细节？）
│  触发条件匹配
▼
[0] 能力探测 → Firecrawl 是否可用？
├─ 是 ────────────────────────────────┐
│  1. 查询规划（1-4 个关键词）          │
│  2. Firecrawl 搜索（Top-N + 正文）    │
│  3. 重新抓取前 1-2 个页面（可选）      │
└──► 6. 清理与截断（动态）              │
7. 验证并综合，附引用 ─────────────┘
│
├─ 否 / 失败 ──► [4] 内置 web_search（标注 🔎）──► 6, 7
│                       │ 无结果
│                       ▼
└─────────────────► [5] 本地知识（⚠️ 警告）──► 回答

触发条件（满足任意一条即激活）

1. 精确数据：版本号、发布日期、性能指标、价格、配置参数
2. 代码细节：API 用法、SDK 示例、函数签名、配置语法
3. 时效敏感：“最新”、“近期”、“202X 年”
4. 权威敏感：官方建议、安全/合规规则
5. 截止后事实：模型训练数据截止之后发生的事件
6. 明确请求：“查一下 / 搜索 / 验证 XXX”

设计原则

- 可追溯性：每个答案都内联引用其来源；降级层级会被明显标注
- 验证：在可能的情况下，硬事实会跨 ≥2 个独立来源交叉核对
- 成本控制：每次对话 ≤10 次 Firecrawl 调用、≤4 轮搜索；请求超时 15 秒
- 韧性：缺少密钥 / 网络受阻 / 沙箱限制绝不会让流程走入死胡同
- 上下文感知截断：保留最相关的 3-5 个段落，而非固定的 128K 阈值
- 渐进式披露：SKILL.md 保持为紧凑的操作参考；深层细节放在 references/ 中

这与 Firecrawl 提供商插件的区别

诸如 dsh-web-search-firecrawl 之类的社区插件替换的是搜索后端（web_search 工具的底层提供商）。本技能是其上的一层工作流：它定义了研究方法论（查询规划 → 搜索 → 重新抓取 → 降级 → 验证 → 引用），并可与任何 Firecrawl 接口配合使用——MCP 工具、直接 API 或提供商插件。两者互补：安装提供商插件以升级引擎，安装本技能以升级方法论。

仓库结构

firecrawl-research-engine/
├── SKILL.md                    ← 技能本身（安装此项）
├── references/
│   ├── FIRECRAWL-API.md        ← Firecrawl v2 API 参考（已验证）
│   └── INSTALLATION.md         ← 跨平台安装指南（DSH/Claude Code/Codex/Cursor）
├── examples/
│   └── cordis.patch.yml        ← DSH MCP 配置示例
├── docs/
│   └── TROUBLESHOOTING.md      ← Windows 沙箱 TLS、首次启动超时等
├── LICENSE                     ← MIT
└── .gitignore

许可证

MIT © 2026 — 详见 LICENSE。

中文说明

这是什么

一个 DSH(DeepSeek Harness)技能,将 LLM 用作深度技术调研与验证引擎,也适用于任何能加载 SKILL.md 并调用 MCP 的 agent(Claude Code / Codex / Cursor)。

1. 搜索优先——使用 Firecrawl Search API(而非仅抓取 URL),一次返回 Top-N 结果及完整页面 Markdown 正文
2. 可选精抓——对最权威的 1-2 个 URL 再 scrape 补充细节
3. 优雅降级——Firecrawl 不可用时自动改用内置 web_search
4. 保底兜底——联网无结果时退回本地知识,并加 ⚠️ 明确警告
5. 验证与引用——硬事实尽量由 ≥2 个独立来源交叉确认,回答强制内联引用 [来源: 标题 + URL],矛盾并列展示

目标是在技术问题上减少幻觉,同时控制成本(单次对话 Firecrawl ≤10 次)和延迟(单请求 15s 超时)。

实战排障经验(Windows)

以下两个问题来自实际部署中踩过并验证的坑,在 Windows 上安装或首次配置 MCP 前建议先阅读。完整记录见 docs/TROUBLESHOOTING.md。

1. Windows 沙箱会导致沙箱内 HTTPS 调用 TLS 失败

DSH 的 Windows 沙箱以 WRITE_RESTRICTED 受限令牌执行命令,只允许在工作区和私有临时目录内写入。TLS 握手需要写入用户证书/密钥缓存(%APPDATA%\Microsoft\Crypto\RSA、%APPDATA%\Microsoft\SystemCertificates),这些写入被拒绝后,所有 HTTPS 调用都会报 SEC_E_NO_CREDENTIALS (0x8009030e),而普通 TCP 和 DNS 仍然正常。

这是令牌上的内核级访问检查,不是杀毒软件问题,关闭 Windows 安全中心也无法解决。可靠的做法是使用 Firecrawl MCP server——它由 DSH 宿主进程启动,位于命令行沙箱之外,TLS 正常;沙箱内直接调用 API 则需 danger-full-access 模式(每次调用触发一次审批)。

2. MCP 首次启动可能超过 60 秒连接超时

首次执行 npx -y firecrawl-mcp 需下载包及约 40 个依赖(1-2 分钟),超过 MCP 客户端默认的 60 秒连接超时,导致客户端断开、服务进程退出。这是时序问题,不是协议不兼容。

首次失败后,通过修改 cordis.patch.yml 触发 HMR 重连,或重启 DSH 即可;此后 npx 缓存已热,数秒内即可连接。不要删除 npx 缓存目录,否则超时问题会复现。

与 Firecrawl provider 插件的区别

社区插件(如 dsh-web-search-firecrawl)替换的是搜索后端;本技能是方法论工作流层(检索词规划 → 搜索 → 精抓 → 降级 → 验证 → 引用),与任何 Firecrawl 接入方式(MCP / 直接 API / provider 插件)兼容,可叠加使用。

安装

1. 将 SKILL.md 放入对应环境的技能目录(见上表或 references/INSTALLATION.md)
2. 配置 Firecrawl(三选一):
- A(推荐):Firecrawl MCP server,配置见 examples/cordis.patch.yml
- B:直接调用 v2 API(references/FIRECRAWL-API.md)
- C:不配置——自动降级内置 web_search,反幻觉机制仍生效

常见问题

详见 docs/TROUBLESHOOTING.md,重点覆盖:

- Windows 沙箱 TLS 失败(SEC_E_NO_CREDENTIALS):命令行沙箱的受限令牌无法访问证书存储 → 用 MCP 方案规避
- 首次 npx 下载超时:首次启动约 1-2 分钟 > MCP 60s 连接超时 → 缓存热后秒连,或触发 HMR 重连
- Firecrawl 无 Key 也能用:keyless 模式限流可用,配置 Key 获得更高限额

协议

MIT © 2026 — 详见 LICENSE。