makesandcrafts/firecrawl-harness

firecrawl-harness

面向 DeepSeek Harness (DSH) 的本地网络研究集成：将你机器上自托管的
Firecrawl 栈（http://127.0.0.1:3002，无需认证）与你自己的自托管
SearXNG 实例（通过 SEARXNG_URL 配置——公共仓库仅附带占位符，绝不包含
任何人的个人端点）融合在一起。
无需云 API 密钥，无需 fork Firecrawl——胶水代码完全在此处。

关于此构建。 整个集成——架构、代码、测试
与部署接线——均由 qwen3.8-flash-next 自主构思并执行，
运行在单台 NVIDIA DGX Spark（GB10 Grace
Blackwell，128 GB 统一内存）上，端到端驱动 DeepSeek Harness：
从计划模式探索，到验收测试，再到实时
MCP 工具验证。一个小型推理节点，一个智能体，零云 API。

- 用途：为智能体会话提供一流的本地工具，用于搜索（SearXNG）、
阅读（Firecrawl 抓取）、侦察（map）和收集（crawl）网络内容；
自托管 Firecrawl 上的 /v1/search 需要 Google 密钥，因此在此层
由 SearXNG 承担搜索功能。
- 状态：活跃（创建于 2026-09-17，已针对栈构建 2343d7b 验证）。
- 来源：改编自 https://github.com/firecrawl/firecrawl（上游
容器保持原样；firecrawl-mcp 官方服务器固定为 3.24.0）。

重要文件

| 路径 | 作用 |
|---|---|
| scripts/fc_client.py | 共享标准库客户端：传输、重试、信封、任务轮询、环境配置 |
| scripts/fc_research.py | SearXNG → Firecrawl 研究融合摘要（招牌工具） |
| scripts/fc_scrape.py | 单 URL 抓取 → markdown（/v1/scrape） |
| scripts/fc_map.py | URL 发现（/v1/map） |
| scripts/fc_crawl.py | 小型礼貌异步爬取（/v1/crawl），上限：页面 ≤ 50，深度 ≤ 3 |
| scripts/healthcheck.py | PASS/FAIL 门禁，含抓取+搜索金丝雀；重启/事故后运行 |
| assets/blacklist.txt | 研究摘要的域名过滤（后缀匹配） |
| skill/SKILL.md | DSH 技能清单；符号链接为 ~/.agents/skills/firecrawl |
| tests/smoke.sh | 成文的验收运行（6 项检查，含降级退出码） |
| docs/ARCHITECTURE.md | 各部分如何协同；由探测确定的传输/API 事实；DSH 补丁语法教训 |
| docs/OPERATIONS.md | 安装、运行手册、故障→修复表、回滚、带日期的验证日志 |
| .cache/ | 生成的摘要/爬取输出（已 gitignore） |

常用命令

python3 scripts/healthcheck.py                # 全部正常？
./tests/smoke.sh                              # 验收套件
python3 scripts/fc_research.py "some topic" --scrape 3
python3 scripts/fc_scrape.py https://example.com --only-main-content
python3 scripts/fc_map.py https://docs.example.org --limit 30
python3 scripts/fc_crawl.py https://docs.example.org/guide --limit 10 --max-depth 2

环境/配置：SEARXNG_URL 为必填——你自己 SearXNG 的 JSON
端点（?q=x&format=json 必须返回结果列表）。解析
顺序：环境变量 → 仓库 .env（cp .env.example .env）→
~/.config/firecrawl-harness/config（KEY=VALUE 行；环境变量优先）。未配置的
脚本会快速失败并给出清晰的提示。FIRECRAWL_API_URL（默认
http://127.0.0.1:3002；除非 FC_ALLOW_REMOTE_API=1，否则受限于回环地址）。
退出码：2 表示 SearXNG 宕机，3 表示 Firecrawl 宕机，4 表示超时，5 表示任务/校验失败。

DSH 接线

1. 技能 — ln -s ~/projects/firecrawl-harness/skill ~/.agents/skills/firecrawl
（已就位）。新会话会在技能目录中列出 firecrawl。
2. 原生 MCP 工具 — 在
~/.dsh/profiles/web/cordis.patch.yml 中用一个无 id 的 insert: 列表
添加 @deepseek-ai/dsh-mcp-client
行（补丁中普通的 - id: … name: … config: 只会重定向现有
行，并警告 patch: entry … not found；新行必须插入——
这是从编译后的 cordis-plugin-include 中现场学到的，并由
dsh --profile web --dump-config 确认）。通过 stdio 运行官方 MCP 服务器：
npx -y firecrawl-mcp@3.24.0，并设置 FIRECRAWL_API_URL；工具
以 mcp__firecrawl__firecrawl_ 形式出现（npm 服务器的原始工具
名已经是 firecrawl_，因此桥接的命名空间会使前缀翻倍——已现场验证：
注册了 27 个工具，但实际可调用的集合是
mcp__firecrawl__firecrawl_scrape|map|crawl|check_crawl_status；
像 firecrawl_search 这样的裸名称在任何会话中都未注册
（unknown tool），而 firecrawl_search 背后的工具（需要 Google
密钥）以及仅限云端的 monitor_/research_*/agent/interact/
parse/developer_search/extract 按设计在此技术栈上会报错——
搜索通过 scripts/fc_research.py/SearXNG 进行，绝不使用那些工具）。
failOnStartupError: false 使 DSH 在 npx/registry 不可用时仍可启动。
移除那一个代码块即可回滚——配置文件的
patchReload: live 会热应用补丁编辑，因此原本（损坏的）
补丁被实时忽略，而这个修正后的行在无需重启服务的情况下生效。
宿主机的 ~/.npm 缓存包含 root 拥有的文件（既有的
npm bug 遗留问题），因此该条目注入了 npm_config_cache=…/.npm-cache——一个
仓库本地的临时缓存，已被证明可以冷安装该固定版本（如果
需要，chown -R 1000:1001 ~/.npm 可以全局修复宿主机缓存）。

相关链接

- Firecrawl 仓库 / 文档：https://github.com/firecrawl/firecrawl · https://docs.firecrawl.dev
- Firecrawl MCP 服务器：npm 上的 firecrawl-mcp（固定为 3.24.0）
- 技术栈检查：docker ps | grep firecrawl（api/redis/rabbitmq/postgres/playwright）
- 同级技能（原始搜索）：~/.agents/skills/local-web-search

备注

- 已验证异步任务的响应封装：{success, status, completed,
total, data:[{markdown, metadata}]}；未知的中间状态会继续轮询。
- /v1/extract 有意未封装：需要一个 LLM 服务，而该 compose
- 不进行配置（可能的未来变数：将其指向 DGX Spark
OpenAI 兼容端点）。
- 仅在连接错误/超时/5xx 时重试一次（2 秒退避）；4xx 从不
重试。重试的 POST 可能会在服务端重复一个抓取任务——接受此风险。
- 遵守 robots：委托给 Firecrawl 默认值；被阻止的页面会作为
可见的抓取错误呈现，绝不绕过。

后续行动

- 已完成 2026-09-17：技能已符号链接 + 冒烟测试套件通过；mcp-firecrawl 行
已组合（dump-config 干净）并通过 patchReload: live
热应用实时提供服务——stdio 子进程树 dsh → npm exec firecrawl-mcp 稳定，MCP
握手此前已直接验证（27 个工具）。实际上从未需要重启服务。
- 观察：27 工具 schema 的每请求 token 权重；如果影响明显，可通过移除
该块来精简（技能脚本独立于它）。
- 可选：chown -R 1000:1001 ~/.npm 以停用缓存变通方案；
在你自己的 ops-notes 位置添加一条部署说明。