dsh-tavily-firecrawl

Readme

# dsh-tavily-firecrawl

把 DeepSeek Harness 的联网能力换成 **Tavily 搜索 + Firecrawl 抓取** 的组合。一个 bundle 包，`dsh plugin add` 一条命令完成安装。

- `web_search` → **Tavily**（`POST /search`，专用检索端点，快且便宜）
- `web_fetch` → **Firecrawl**（`POST /v1/scrape`，返回 markdown 正文）
- 自动禁用内置的 DeepSeek 原生搜索（`web-search-deepseek`），无需 `DEEPSEEK_API_KEY`

纯 JavaScript ESM，无需编译；peer 依赖（`@deepseek-ai/dsh-web`、`@deepseek-ai/cordis` 等）从 dsh 安装自带的 fallback node_modules 解析，**接收者不需要额外安装任何依赖**（也不需要源码运行 DSH）。

## 安装（接收者视角，官方机制推荐）

前置：已安装 dsh CLI（≥ 0.1.0-rc.5，本包在该版本验证）和 pnpm（`dsh plugin` 需要）。

```bash
# 1. 安装 bundle（自动初始化 profile、自动应用 wiring patch）
dsh plugin --profile web add github:<作者>/dsh-tavily-firecrawl#v0.1.0

# 2. 填 API key（任选一种方式）
#    - 编辑 $DSH_HOME/.env（首次安装会自动生成模板）
#    - 或启动环境里 export TAVILY_API_KEY / FIRECRAWL_API_KEY

# 3. 重启 dsh（你的常用启动命令）
dsh web
```

重启后**新会话**即生效：

- `web_search` 立即可用（Tavily）
- `web_fetch`（Firecrawl）需要会话运行在开启 fetch 的预设上：设置 → 通用 → agent 预设里选 **standard-web**（本包附带的预设 = 官方 standard + `fetch: true`），或应用 [`enable-web-fetch-default.patch.yml`](./enable-web-fetch-default.patch.yml) 让它成为默认：

```bash
dsh web --patch ./enable-web-fetch-default.patch.yml
```

> 想用旧版（git URL 无 tag）？`dsh plugin --profile web add github:<作者>/dsh-tavily-firecrawl` 装默认分支。
> 想更新？`dsh plugin --profile web update dsh-tavily-firecrawl`。
> 想卸载？`dsh plugin --profile web remove dsh-tavily-firecrawl`，然后按本文末尾恢复 `web-search-deepseek`。

## 其他安装方式

**方式 B：本地 tgz**（无 GitHub/网络 git 依赖时）

```bash
npm pack    # 在仓库根目录生成 dsh-tavily-firecrawl-0.1.0.tgz
dsh plugin --profile web add ./dsh-tavily-firecrawl-0.1.0.tgz
```

**方式 C：`./install.sh`**（无需 pnpm / dsh CLI，一键全自动）

```bash
./install.sh                      # 默认装进 $DSH_HOME/profiles/web
./install.sh --enable-fetch-default   # 顺便让新会话默认走 web_fetch 预设
```

脚本幂等：复制 bundle 到 profile `vendor/` → 建 node_modules 符号链接 → 合并 wiring patch（带起止标记）→ 复制 standard-web 预设 → 生成 `.env` 模板。卸载用 `./uninstall.sh [--profile <名字>] [--keep-preset]`。

**方式 D：`--patch` 临时叠加**（不落盘、可随时去掉；要求包已能被 profile 解析）

```bash
dsh web --patch ./tavily-firecrawl.patch.yml
```

## 配置

patch 行的 `config:` 里覆盖（全部可选）：

```yaml
- insert:
    - id: web-tavily-firecrawl
      name: 'dsh-tavily-firecrawl'
      config:
        search:                 # Tavily 侧
          searchDepth: advanced # basic | advanced
          includeAnswer: true   # 让 Tavily 生成摘要（成为结果的 answer）
          maxResults: 8         # 无 maxResults 时的默认条数
          apiKey: tvly-xxx      # 字面 key（优先于环境变量）
          baseURL: https://api.tavily.com
        fetch:                  # Firecrawl 侧
          timeoutMs: 30000
          maxBodyChars: 200000  # 正文上限，超出截断并标记
          onlyMainContent: true
          apiKey: fc-xxx
          baseURL: https://api.firecrawl.dev
        searchEnabled: true     # false 则不注册搜索提供方
        fetchEnabled: true      # false 则不注册抓取提供方
```

Key 解析顺序：继承环境 → `<调用目录>/.env` → `$DSH_HOME/.env`。provider 每次调用实时解析凭据，改 key 无需重启；改 `.env` 文件需要重启进程。

## 验证

装好后让 agent 试：

- 「搜一下 <关键词>」→ 走 Tavily
- 「抓取 https://example.com」→ 走 Firecrawl（需要 standard-web 预设）

## 常见问题

- **改完配置不生效？** 插件与 patch 启动时加载，必须重启 dsh 进程。
- **搜索报 key 错误？** `TAVILY_API_KEY` 未解析，检查 `$DSH_HOME/.env` 或启动环境。
- **`web_fetch` 工具不存在？** 工具注册由预设的 `tool-web.fetch` 控制，选 standard-web 预设。
- **想换回 DeepSeek 搜索？** `dsh plugin remove` 后，手动把 profile 的 `cordis.patch.yml` 里标记块删掉（或跑 `./uninstall.sh`）。
- **patch 优先级？** bundle 层 < profile `cordis.patch.yml` < `$DSH_HOME/cordis.patch.yml` < `--patch` 叠加层，后层覆盖前层。

## 开发者：发布到 GitHub / npm

本仓库根目录即 npm 包（声明 `dsh.bundle.patch`），这是 `dsh plugin add` 官方机制识别的关键。

```bash
# 1. 推到 GitHub
git init -b main && git add . && git commit -m "dsh-tavily-firecrawl 0.1.0"
git remote add origin git@github.com:<作者>/dsh-tavily-firecrawl.git
git push -u origin main

# 2. 打 tag（接收者用 #v0.1.0 锁定版本）
git tag v0.1.0 && git push origin v0.1.0

# 3. （可选）发布到 npm —— 去掉 package.json 里的 "private": true、确保包名全局唯一
npm publish

# 4. （可选）GitHub Releases 附上 dist/*.tgz 和整个仓库 zip，方便不熟 git 的用户
```

发布 npm 后接收者直接：`dsh plugin --profile web add dsh-tavily-firecrawl`。

## 兼容性

- macOS / Linux（Windows 建议 WSL 或用方式 B/C）
- 需要带 web seam（`ctx.web`）的 DSH 版本（官方 `dsh-base` + `dsh-web-app` 组合均满足），已验证 0.1.0-rc.5