dsh-web-search-firecrawl

English | 中文

A Firecrawl-backed search provider for the DeepSeek Harness web capability seam (ctx.web): it makes the built-in web_search tool run on Firecrawl's search API instead of the shipped DeepSeek route.

The plugin is a Cordis function plugin that registers a WebSearchProvider (id: firecrawl) into the seam — it does not own ctx.web and does not register a model-facing tool (the tool schema stays with @deepseek-ai/dsh-tool-web). It calls Firecrawl's POST /v1/search endpoint and maps the flat data[] into the seam's normalized WebSearchResult.

Requirements

• A DeepSeek Harness installation on the 0.1.0-rc.6 line of the official packages (the plugin peers on @deepseek-ai/dsh-web ^0.1.0-rc.6 and friends — the current release line). On an older line, pnpm nests a second copy of the seam into the profile and error classification degrades (cross-copy WebError); check from the profile directory with npm ls @deepseek-ai/dsh-web.
• A Firecrawl API key. The provider reads it from $FIRECRAWL_API_KEY or the apiKey config below (API Key). Get one at firecrawl.dev.

Install

The steps below assume the dsh CLI is on your PATH (for example installed with npm install -g @deepseek-ai/dsh). If you run dsh differently — via npx without any install, or from a source checkout — replace every dsh ... below with the matching invocation; the CLI, the profile, and the plugin must come from the same installation:

1. Install the bundle (needs pnpm on PATH; pnpm 9.x through 11.x all work — see the -w note below):

   dsh plugin --profile web add -w @yangzhe1003/dsh-web-search-firecrawl

   dsh plugin forwards to pnpm inside the profile directory and appends the bundle to the profile's layer stack automatically. The profile is a single-package pnpm workspace (its pnpm-workspace.yaml declares packages: [.]), so -w explicitly targets the profile's own manifest: pnpm <10 refuses an unqualified add at a workspace root (ERR_PNPM_ADDING_TO_ROOT), while pnpm ≥10 accepts both forms. The bundle patch inserts the web-search-firecrawl plugin row and switches the web seam row to searchProvider: firecrawl (replacing the base bundle's deepseek-official).

2. Provide the API key — temporary or persistent, see API Key.

3. Restart dsh web — bundle layers are composed at boot, so a running instance does not pick up a newly installed bundle. Exit the current dsh web process completely, then start it again with the same invocation you used above (dsh web, npx @deepseek-ai/dsh web, or pnpm dsh web):

   dsh web

4. Verify — in a session, ask the agent to perform a web search; the request goes to Firecrawl. The composed tree can be inspected with dsh --profile web --dump-config. A missing key fails the search with WEB_PROVIDER_CONFIGURED_UNAVAILABLE.

To keep DeepSeek search as the default and enable Firecrawl per instance instead, restate the web row in your profile's own cordis.patch.yml afterwards — the last write wins per row. The base bundle pins searchProvider: deepseek-official, so $DSH_WEB_SEARCH_PROVIDER selects the provider only when the web row sets no searchProvider: restate web with an empty config (- id: web + config: {}) for env selection, or with searchProvider: deepseek-official to pin DeepSeek.

API Key

Provide the key either way:

Temporary — export it in the shell before launching dsh; it lasts only for the current terminal session:

export FIRECRAWL_API_KEY=fc-...
dsh --profile web

Persistent — write it to $DSH_HOME/.env (default ~/.dsh/.env) as one bare KEY=value line (no export prefix); dsh reads it at every boot, so it survives reboots. Keep the file private:

echo 'FIRECRAWL_API_KEY=fc-...' >> ~/.dsh/.env
chmod 600 ~/.dsh/.env

Config

# profile cordis.patch.yml
- id: web-search-firecrawl
  name: '@yangzhe1003/dsh-web-search-firecrawl'
  config:
    apiKey: !!js process.env.FIRECRAWL_API_KEY

Mapping

Firecrawl returns a flat data[] and no generated answer, so content is omitted. Each entry maps to a WebSearchSource: url ← url, title ← title, snippet ← description trimmed and bounded to maxSnippetChars (an entry without a non-blank description keeps its citeable URL-only source). A request's maxResults wins over the configured limit default and is sent as Firecrawl's limit for a cost/latency optimization; the final bound is enforced by the seam. Provider failures (HTTP errors, network failure, unparseable or wrong-shape bodies, a success: false envelope) surface as WebError WEB_PROVIDER_ERROR; an aborted request surfaces as WEB_ABORTED. HTTP redirects are rejected before the Location target is contacted.

Model Experience

Indirect, through @deepseek-ai/dsh-tool-web: the model sees the maxResults-bounded URLs, titles, and bounded descriptions, plus the consumer's error wrapper around Firecrawl search aborted, Firecrawl search request failed: <error>, and Firecrawl returned an unprocessable response body: <error>. Generated answers and provider-private fields stay out of context.

Known Limitations

• A snippet is Firecrawl's description excerpt, not a search-engine summary — it can be long page markdown, so the provider bounds it to maxSnippetChars; entries without a description carry no snippet at all (URL-only).
• Only limit/maxSnippetChars are exposed — Firecrawl's other controls (language, country, recency, location, targeting, scrape options) wait on provider-neutral Service Definition fields in @deepseek-ai/dsh-web.
• Abort classification is error-shape-based — only a DOMException named AbortError maps to WEB_ABORTED; an abort carrying a custom reason surfaces as WEB_PROVIDER_ERROR.

Development

pnpm install
pnpm run typecheck
pnpm test                            # unit suite (no network)
FIRECRAWL_API_KEY=... pnpm run test:e2e  # live-API smoke, self-skips without the key
pnpm run build                       # emits lib/ (ESM) + lib/types/ (d.ts)

Releasing

Pushing a v<semver> tag publishes that commit to npm automatically (.github/workflows/publish.yml): the tag name becomes the published version, so

git tag v0.1.3 && git push origin v0.1.3

builds, tests, and publishes 0.1.3 with SLSA provenance. Publishing uses npm Trusted Publishing (OIDC, no npm token stored anywhere). Once, on the package's settings page on npmjs.com (https://www.npmjs.com/package/@yangzhe1003/dsh-web-search-firecrawl → Settings → Trusted Publisher), add the trusted publisher:

• CI/CD provider: GitHub Actions
• Organization or user: yangzhe1003
• Repository: dsh-web-search-firecrawl
• Workflow filename: publish.yml
• Environment name: publish
• Allowed actions: npm publish

The workflow references the GitHub environment publish, which is created automatically on the first run. Trusted Publishing requires npm CLI ≥ 11.5.1 and Node ≥ 22.14 — the workflow's Node 24 runner bundles npm 11.13, so this is satisfied out of the box.

License

MIT