kenny2077/dsh-web-search-doubao

dsh-web-search-doubao

为 DeepSeek Harness 提供由豆包搜索（火山引擎）驱动的网络搜索。

CI
npm version
License: MIT

它是什么

dsh-web-search-doubao 是 DeepSeek Harness 的社区插件，把豆包搜索作为搜索提供方接入 harness 的 ctx.web 能力接缝。一条 dsh plugin add，你的 harness 即可通过字节跳动的独立豆包搜索 API 检索网络——无需修改基础 bundle，更改设置无需重启。

这不是方舟（Ark）聊天侧的联网内容插件：这里的一切都不经过豆包对话模型，搜索与模型推理完全解耦。

更偏好智谱/GLM？本插件有一个姊妹项目：dsh-web-search-zai——面向 ZAI 独立网络搜索 API 的同一套提供方模式，设计语言一脉相承。

核心价值：独立于模型支出的搜索计费

- 计费独立。 豆包搜索是独立服务、独立密钥：每月 500 次免费搜索，超出后按量后付费（custom 版亦可购买月度套餐）。搜索不消耗任何模型 token，费用不会与你的方舟/大模型账单混在一起。
- 字节系信源。 后端与豆包 App 搜索同源，覆盖头条/抖音系公开内容——中文互联网覆盖出色，且发布时间可精确到秒（信源提供时）。
- 运行时可配置。 服务版本、端点、摘要长度、权威度过滤都是普通配置项——提交后即在下一次搜索生效，无需重启。
- 贴合接缝而非绕开它。 提供方以与内置 DeepSeek 提供方完全相同的方式注册进 ctx.web，dsh-tool-web 及其上层全部原样工作。
- 不虚构字段。 只映射 API 真正返回的内容——信源没有发布时间时，publishedAt 保持缺省。

工作原理

搜索路径 —— 提供方以与内置 DeepSeek 提供方完全相同的方式注册进 ctx.web，dsh-tool-web 及其上层全部原样工作：

┌────────────────────────────────────────────────┐
│                DeepSeek Harness                │
│                                                │
│  model ──▶ web_search 工具 ──▶ ctx.web 接缝    │
└───────────────────────────────────────────┬────┘
│
▼
┌──────────────────────────────┐
DOUBAO_SEARCH_API_KEY ─────▶│      web-search-doubao       │
（凭据存储——               │        （本插件）             │
每次搜索时解析）          └───────────────┬──────────────┘
│  POST {baseURL}/search_api/web_search
▼        或 /search_api/global_search
┌──────────────────────────────┐
│   豆包搜索（火山引擎）        │
└───────────────┬──────────────┘
│  Result.WebResults[] / Documents[]
▼
归一化的 WebSearchResult
（sources + truncated，
信源提供时含 publishedAt）
──▶ 原样返回给你的模型

设置路径 —— 本插件的独到之处：设置界面中的专属卡片，把取值存入凭据服务，任何密钥都不会进入配置文件：

┌────────────────────────────────────────────────────┐
│  设置界面 ──「网页搜索（豆包搜索）」卡片            │
│  API Key（掩码，附「获取 API Key ↗」控制台链接）   │
│  接口地址 · 服务版本 · 已配置徽标                  │
└───────────────────────┬────────────────────────────┘
│  保存 / 清空
▼
┌────────────────────────────────────┐
│  DSH 凭据服务                      │
│  ~/.dsh/.credentials.yaml          │
│   DOUBAO_SEARCH_API_KEY            │
│   DOUBAO_SEARCH_BASE_URL           │
│   DOUBAO_SEARCH_EDITION            │
└────────────────────┬───────────────┘
│  每次搜索重新解析——
▼  下一次搜索即生效，无需重启
上面的搜索路径

服务有两个版本，报文格式不同，由 edition 选择：

custom（默认——服务端遵循结果数）

| 豆包字段 | 接缝字段 | 说明 |
|---|---|---|
| Url | url | 缺失则丢弃该条 |
| Title | title | 为空则省略 |
| Content ‖ Summary ‖ Snippet | snippet | 取第一个非空；全空则丢弃该条 |
| PublishTime | publishedAt | 信源未提供时省略 |
| SiteName、AuthInfoDes | — | 不映射 |

global（更长的正文，结构化 Parts[]）

| 豆包字段 | 接缝字段 | 说明 |
|---|---|---|
| Url | url | 缺失则丢弃该条 |
| Title | title | 为空则省略 |
| Parts[]（Type: "text"） | snippet | 文本片段拼接；无则丢弃该条 |
| DocumentInfo.PublishTime | publishedAt | 缺失时省略 |
| HostInfo、ContentTokenCount、图片片段 | — | 不映射；不请求图片 |

失败以标准 WebError 码暴露：WEB_PROVIDER_ERROR（HTTP/网络/响应体异常）、WEB_ABORTED（取消）、WEB_PROVIDER_CREDENTIAL_MISSING（无密钥）。经由 dsh-tool-web，这些错误按消费方惯用的包装送达模型。

快速开始

需要已安装 DeepSeek Harness（dsh CLI 可用）和一个豆包搜索 API 密钥。

1. 获取密钥：打开豆包搜索 API Key 页面，登录火山引擎账号，开通服务，然后创建 API Key。该密钥与 ARK_API_KEY 相互独立——只授权豆包搜索服务。每个账号每月 500 次免费额度；超出后在同一控制台开通按量付费。

这不是火山方舟（Ark）控制台的密钥。方舟聊天侧联网搜索插件是另一个产品、另一套计费。

豆包搜索控制台 —— 每月 500 次免费额度

请妥善保存密钥，避免写入配置文件——直接粘贴到 harness 设置界面中的网页搜索（豆包搜索）卡片（见下文）、在 $DSH_HOME/.credentials.yaml 中添加 DOUBAO_SEARCH_API_KEY 条目，或通过启动环境变量提供。

2. 安装插件：

dsh plugin add dsh-web-search-doubao        # 来自 npm
dsh plugin add github:kenny2077/dsh-web-search-doubao   # 来自 git（已预构建，无需构建步骤）

cordis.patch.yml 覆盖层会注册提供方，并把激活的 searchProvider 从 deepseek-official 一步切换为 doubao。想换回去：dsh plugin remove dsh-web-search-doubao。

3. 搜索。 问 harness 一件时效性强的事，观察 web_search 工具返回豆包搜索结果。

设置界面卡片

网页搜索（豆包搜索）设置卡片 —— harness 设置界面实况

安装后，harness 设置侧边栏会新增网页搜索（豆包搜索）分区，包含三个字段——API Key（掩码输入，附可点击的获取 API Key ↗链接直达豆包搜索 API Key 页面）、接口地址、服务版本。保存会把它们写入 DSH 凭据服务（引用名分别为 DOUBAO_SEARCH_API_KEY、DOUBAO_SEARCH_BASE_URL、DOUBAO_SEARCH_EDITION）；清空会移除全部三个。API Key 旁的徽标在存入密钥后变为已配置，密钥变化时实时刷新。保存的值在下一次搜索即生效——无需重启。

卡片底部的存储说明标注了取值的实际去向，无需猜测：卡片保存的值 → ~/.dsh/.credentials.yaml（凭据服务），绝不写入 settings.yaml；settings.yaml 中的 web-search-doubao 分区仅在你以文件方式编辑同一批字段时才会出现。

由于卡片以凭据引用存储取值，其优先级高于配置文件字段与环境变量：

| 优先级 | 来源 |
|---|---|
| 1 | 凭据服务（卡片写入的值） |
| 2 | web-search-doubao 设置（apiKey、baseURL、edition） |
| 3 | 环境变量（DOUBAO_SEARCH_API_KEY、DOUBAO_SEARCH_BASE_URL） |
| 4 | 内置默认值 |

maxSnippetLength 与 authLevel 仍仅通过配置文件设置（很少调整）。卡片本身由可复用、配置驱动的工厂（src/client/card.tsx）构建——未来的搜索密钥提供方（ZAI、Kimi、Qwen 等）可以用各自的引用与文案实例化同一个组件。

配置

所有字段均可通过设置界面（web-search-doubao 命名空间）在运行时修改；下一次搜索即生效。网页搜索（豆包搜索）设置卡片写入的凭据引用取值优先于下列所有字段——见设置界面卡片。

| 键 | 默认值 | 含义 |
|---|---|---|
| apiKey | （来自凭据存储） | 字面量豆包搜索 API 密钥。建议用 apiKeyEnv，避免密钥进入配置文件。 |
| apiKeyEnv | DOUBAO_SEARCH_API_KEY | 每次搜索时解析的凭据引用。 |
| baseURL | https://open.feedcoopapi.com | 端点基址；按版本追加 /search_api/web_search 或 /search_api/global_search。 |
| edition | custom | custom 版服务端遵循请求结果数；global 版返回更长的正文。 |
| maxSnippetLength | （未设置） | 仅 global 版：单条正文摘要的最大字符数（max_snippet_length）。 |
| authLevel | （未设置） | 仅 custom 版：信源权威度下限 1–4（Filter.AuthInfoLevel；1 = 政府/头部机构）。 |

已知限制

- 没有链接或正文的条目会被丢弃，因此返回的条目可能少于请求数。
- global 版无论请求数量多少可能只返回约 10 条（服务端上限）；custom 版遵循 Count。无论哪种，接缝都会在返回时执行 maxResults 截断。
- 无时间窗口过滤——API 未提供公开的服务端 recency 参数。
- 仅当上游信源提供发布时间时才有 publishedAt。
- 从不请求图片（max_image_count_per_doc 保持未设置）；接缝没有图片字段。
- 只有名为 AbortError 的 DOMException 映射为 WEB_ABORTED；携带自定义原因的中断会表现为 WEB_PROVIDER_ERROR。
- 未实现聊天侧联网内容插件变体（方舟 web_search 工具 / Bot 端点）；本插件仅使用独立搜索 API。

仓库架构

一个包，两半：node 半对接 ctx.web 接缝；client 半在 harness 界面中渲染设置卡片。两者只在凭据服务处交汇。

dsh-web-search-doubao/
├── src/                          # ── 发布源码 ──
│   ├── index.ts                  #     node 入口：Config 模式、设置分区、
│   │                             #       凭据链解析、apply()
│   ├── provider.ts               #     DoubaoSearchProvider：每次搜索的选项快照
│   │                             #       + 凭据覆盖、两个版本的请求/响应映射、
│   │                             #       WebError 纪律
│   ├── types.ts                  #     两个豆包搜索版本的报文类型
│   ├── invariant.ts              #     包自有 invariant 伴随插件（no-op）
│   └── client/                   # ── 设置卡片半（浏览器 bundle）──
│       ├── card.tsx              #     createSearchProviderCard()：可复用、
│       │                         #       与提供方无关的卡片工厂
│       └── index.tsx             #     豆包实例化：凭据引用、控制台链接、
│                                 #       中英文文案
├── tests/
│   ├── doubao.spec.ts            #     node 套件：映射、请求、错误、注册、
│   │                             #       凭据优先级
│   ├── doubao.e2e.ts             #     真实 API 冒烟（无密钥自动跳过）
│   └── client-card.spec.ts       #     卡片套件：基于伪上下文的保存/清空/徽标
│                                 #       流程 + 构建产物的 ModuleLoader 加载冒烟
├── lib/                          # ── 构建产物（入库：git 安装无需构建）──
│   ├── index.js                  #     node 入口（ESM，tsc）
│   ├── client.js                 #     设置卡片（浏览器 bundle，tsdown），按壳的
│   │                             #       window.__ModuleLoader__ 约定包装
│   └── types/                    #     类型声明
├── cordis.patch.yml              # 安装覆盖层：一条 dsh plugin add 同时注册提供方
│                                 #   并选中 searchProvider: doubao
├── tsconfig.json                 # 严格 TS、ES2024 ESM、client 半使用 react-jsx
├── tsdown.config.ts              # client 构建配方（ModuleLoader 包装、react 外置）
├── vitest.config.ts
└── .github/workflows/ci.yml      # typecheck + build + test，node 22/24 × Linux/Windows

开发

pnpm install     # 全部依赖（包括 DSH 接缝包）均来自 npm
pnpm typecheck   # tsc --noEmit
pnpm build       # 产出 lib/.js + lib/types/.d.ts
pnpm test        # 单元测试

在线冒烟测试在没有密钥时自动跳过：

DOUBAO_SEARCH_API_KEY= pnpm exec vitest run tests/doubao.e2e.ts

贡献指南见 CONTRIBUTING.md。

许可证

MIT