firecrawl/dsh-firecrawl

适用于 DeepSeek Harness 的 Firecrawl

此插件将 DeepSeek Harness 内置的 web_search 和 web_fetch
工具指向 Firecrawl。它不添加任何新工具——模型
仍像以前一样请求查询或 URL，由 Firecrawl 来应答。

它支持 Node.js ^22.19.0 || >=24.0.0 上的 @deepseek-ai/dsh@0.1.0-rc.6。
DeepSeek Harness 仍处于开发者预览阶段，因此后续版本可能需要
更新插件。

为什么需要 fetch，而不仅仅是 search

基础 Harness 捆绑包附带 web_fetch 且处于禁用状态，并且不挂载任何 fetch
提供程序。原因就在其自身的配置注释中：唯一的 fetch 后端是一个
本地 HTTP 客户端，它“推迟了 SSRF 防护，而模型会选择
请求目标”。启用它会把模型选择的 URL 指向你的
机器能够访问的任何地址，包括你的私有网络。

Firecrawl 从其自身的基础设施进行检索。Harness 进程从不
打开模型选择的连接——它向 API POST 一个 URL 并取回
markdown。这与启用本地提供程序是不同的风险决策，这
正是此插件在基础捆绑包不启用 web_fetch 的情况下启用它的原因。你还可以
获得 JS 渲染、反机器人处理和 PDF 解析，这些都不是本地
提供程序所能做到的。

仍然值得了解的是：Firecrawl 可以访问模型请求的任何公共 URL。
它无法访问你的私有网络，但可以抓取你未
选择的页面。如果这对你的部署来说不可接受，请保持 web_fetch 关闭
（参见可选设置）。

开始之前

你需要：

- pnpm 10 或更新版本；
- 一个 Firecrawl API 密钥；以及
- 一个已在 DeepSeek Harness 中配置好的模型提供程序。

你不需要全局安装 dsh——下面的命令会通过 npx
运行受支持的版本。

安装

首先，在你将要运行 Harness 的终端中使你的 Firecrawl API 密钥可用：

export FIRECRAWL_API_KEY="fc-your-key"

然后将插件安装到 web 配置文件中：

npx --yes @deepseek-ai/dsh@0.1.0-rc.6 \
plugin --profile web add @firecrawl/dsh-firecrawl

停止任何正在运行的 Harness 进程，然后再次启动它：

npx --yes @deepseek-ai/dsh@0.1.0-rc.6 web

改为从 Git 安装

已发布的包附带预构建的 lib/，因此安装时无需额外
标志。Git 安装则不然——它必须运行此包的 prepare 脚本
来构建，而 pnpm 11 会阻止 Git 依赖项的构建脚本，直到你准确指定
该依赖项。

--allow-build=@firecrawl/dsh-firecrawl 并不足够：pnpm 需要完全
解析后的 Git 键，包括提交 SHA。运行一次安装，让 pnpm
打印出该键：

npx --yes @deepseek-ai/dsh@0.1.0-rc.6 \
plugin --profile web add "github:firecrawl/dsh-firecrawl#main"

它会失败并显示 ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED，并打印出要添加到
~/.dsh/profiles/web/pnpm-workspace.yaml 中 allowBuilds 下的确切行：

allowBuilds:
"@firecrawl/dsh-firecrawl@git+https://github.com/firecrawl/dsh-firecrawl.git#": true

添加它，重新运行同一条命令，即可成功。注意该键是 SHA 固定的，
因此每次更新时它都会变化——这就是为什么上面提到的 npm install 是
推荐的方式。

检查是否生效

检查组合后的配置：
sh
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 \
--profile web --dump-config | \
grep -E 'searchProvider: firecrawl|fetchProvider: firecrawl|@firecrawl/dsh-firecrawl'

你应该会看到两个 provider 固定项以及两行插件：

searchProvider: firecrawl
fetchProvider: firecrawl
- id: web-search-firecrawl
name: "@firecrawl/dsh-firecrawl"
- id: web-fetch-firecrawl
name: "@firecrawl/dsh-firecrawl/fetch"

同时看到内置的 web-search-deepseek 插件也是正常的——
searchProvider 固定项决定由哪个 provider 处理搜索。

然后向 agent 询问一些需要实时网络的问题（“本周 Firecrawl 更新日志有什么变化？”）。
记录中出现 web_search 或 web_fetch 卡片，就说明该工具运行了。

可选设置

默认设置无需额外配置即可工作。若要调整，请编辑
~/.dsh/profiles/web/cordis.patch.yml——它会在本 bundle 的
层之后应用，因此你在其中放置的任何内容都会优先生效。

搜索
yaml
- id: web-search-firecrawl
config:
sources: [web, news]
scrapeContent: true
maxCharsPerResult: 4000

| 设置 | 默认值 | 控制内容 |
| --- | --- | --- |
| apiKey | $FIRECRAWL_API_KEY | Firecrawl 密钥。为空 → provider 不可用。 |
| baseURL | https://api.firecrawl.dev | 端点基础地址；会追加 /v2/search。 |
| sources | [web] | 添加 news 可同时搜索新闻，这是唯一带有发布日期来源的源。 |
| limit | （未设置） | 当调用未携带限制时的默认结果数量。 |
| scrapeContent | false | 抓取每个结果，并使用其 markdown 作为摘要，而不是搜索引擎的描述。内容更丰富，但会消耗额度和增加延迟。 |
| maxCharsPerResult | （未设置） | 每个结果摘要字符数的上限。与 scrapeContent 搭配使用。 |
| includeDomains / excludeDomains | （未设置） | 主机名允许/拒绝列表。 |
| tbs | （未设置） | 时间过滤器：qdr:d、qdr:w、qdr:m、qdr:y。 |
| country / location | （未设置） | 地理定位。 |
| timeoutMs | 60000 | Firecrawl 侧搜索超时。 |

抓取
yaml
- id: web-fetch-firecrawl
config:
proxy: stealth
maxAgeMs: 0

| 设置 | 默认值 | 控制内容 |
| --- | --- | --- |
| apiKey | $FIRECRAWL_API_KEY | Firecrawl 密钥。为空 → provider 不可用。 |
| baseURL | https://api.firecrawl.dev | 端点基础地址；会追加 /v2/scrape。 |
| format | markdown | markdown（按 seam 的 text 类型解码）或 html。 |
| onlyMainContent | true | 去除导航、页眉和页脚等界面元素。 |
| maxAgeMs | 172800000 | 提供比此时间更新的缓存页面。0 强制进行全新抓取。 |
| waitForMs | 0 | 捕获前的延迟，用于客户端渲染较慢的页面。 |
| mobile | false | 模拟移动设备。 |
| blockAds | true | 屏蔽广告和 cookie 横幅。 |
| proxy | auto | basic、auto 或 stealth —— stealth 会以更高的额度消耗重试反机器人页面。 |
| timeoutMs | 60000 | Firecrawl 侧的抓取超时时间。 |
| maxBodyChars | 100000 | 解码后正文字符数的上限；结果会标记截断。 |
| maxUrlLength | 2048 | 可接受的请求 URL 最大长度。 |

要保留搜索但重新关闭 web_fetch：
yaml
- id: tool-web
config:
fetch: false

将 FIRECRAWL_API_KEY 保留在环境变量中，而不是放在此文件里，因为此文件
以可读文本形式存储。

如果出现问题

- 找不到 dsh： 使用上面的 npx @deepseek-ai/dsh 命令。
- 端口 3080 已被占用： 先停止较旧的 Harness 进程。
- 提供程序仍然是 deepseek-official： 重启 Harness 并检查
你自己的 cordis.patch.yml 是否包含更晚的 searchProvider
覆盖 —— 用户层最后应用。
- WEB_PROVIDER_CONFIGURED_UNAVAILABLE： 启动 Harness 的同一个终端中
未设置 FIRECRAWL_API_KEY。
- WEB_PROVIDER_AMBIGUOUS： 在多个提供程序可用时，有东西移除了
searchProvider 固定项。请恢复它。
- ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED： 你正在从 Git 安装。请参阅
从 Git 安装 —— npm 安装完全避免了
此问题。
- pnpm 报告缺少 DSH 对等依赖： 这是预期行为。Harness 会从
profile 运行时提供这些包。
- Harness 不搜索就回答： 模型决定何时调用
web_search。请尝试一个明显需要最新信息的提示。

移除
sh
npx --yes @deepseek-ai/dsh@0.1.0-rc.6 \
plugin --profile web remove @firecrawl/dsh-firecrawl

移除插件后重启 Harness。

它如何映射

两个提供程序都注册在 ctx.web 能力
接缝
上，id 为 firecrawl，每个注册表一个。它们注册到该接缝中；它们
不拥有该接缝，也不注册面向模型的工具 —— 那些仍由
@deepseek-ai/dsh-tool-web 负责。

搜索（POST /v2/search）→ WebSearchResult。每个 data.web[] 条目将
url → url、title → title，以及 description（或当 scrapeContent 开启时抓取的 markdown）
→ snippet。每个 data.news[] 条目将 snippet
→ snippet、date → publishedAt；网页结果不携带日期，因此
对它们省略 publishedAt。没有 URL 的条目会被丢弃，而不是
赋予一个编造的 URL。content 被省略 —— Firecrawl 搜索不返回
生成的答案。请求的 maxResults 会作为 Firecrawl 的 limit 发送，以
优化成本；接缝会强制执行最终边界。

抓取（POST /v2/scrape）→ WebFetchResult。metadata.statusCode →
statusCode、metadata.url → url，以及 markdown（或 HTML）正文 → body，
以 maxBodyChars 为上限截断，并设置 truncated。非 2xx 页面是结果，而不是
错误 —— Firecrawl 会成功返回 statusCode: 404 以及服务器所提供的任何内容，
而该接缝将状态定义为已获取资源状态的一部分。

错误。 提供方失败会以 WebError WEB_PROVIDER_ERROR 的形式出现，
并在 Firecrawl 自身有错误码时携带该错误码（SCRAPE_DNS_RESOLUTION_ERROR、
SEARCH_TIMEOUT）。取消会以 WEB_ABORTED 的形式出现。不是
http/https、过长或带有内嵌凭据的 URL 会在任何携带凭据的请求离开进程之前
被拒绝为 WEB_INVALID_URL。API 请求上的 HTTP 重定向会在联系 Location
目标之前被拒绝，因此 API 密钥永远不会被转发到另一个源。

开发
sh
pnpm install
pnpm run check        # typecheck, unit tests, build, manifest and package guards
FIRECRAWL_API_KEY=fc-... pnpm run test:e2e   # live API, spends credits

pnpm run check 是 CI 运行的内容。实时测试套件被排除在 pnpm test 之外，
因此默认路径不产生任何费用。

MIT 许可。如需帮助，请联系 help@firecrawl.dev。