dsh-web-search-doubao
为 DeepSeek Harness 提供豆包搜索（火山引擎）网络搜索提供方——把 web_search 的后端切换为独立的豆包搜索 API，密钥与计费独立（每月 500 次免费），并内置专用设置卡片，经凭据服务保存密钥。
READMEdsh-web-search-doubao
为 DeepSeek Harness 提供由豆包搜索（火山引擎）驱动的网络搜索。
English | 中文
它是什么
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 及其上层全部原样工作：
▼text复制代码┌────────────────────────────────────────────────┐ │ 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） ──▶ 原样返回给你的模型
设置路径 —— 本插件的独到之处：设置界面中的专属卡片，把取值存入凭据服务，任何密钥都不会进入配置文件：
▼text复制代码┌────────────────────────────────────────────────────┐ │ 设置界面 ──「网页搜索（豆包搜索）」卡片 │ │ 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 密钥。
-
获取密钥：打开豆包搜索 API Key 页面，登录火山引擎账号，开通服务，然后创建 API Key。该密钥与
ARK_API_KEY相互独立——只授权豆包搜索服务。每个账号每月 500 次免费额度；超出后在同一控制台开通按量付费。这不是火山方舟（Ark）控制台的密钥。方舟聊天侧联网搜索插件是另一个产品、另一套计费。
请妥善保存密钥，避免写入配置文件——直接粘贴到 harness 设置界面中的**网页搜索（豆包搜索）**卡片（见下文）、在
$DSH_HOME/.credentials.yaml中添加DOUBAO_SEARCH_API_KEY条目，或通过启动环境变量提供。 -
安装插件：
▼sh复制代码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。 -
搜索。 问 harness 一件时效性强的事，观察
web_search工具返回豆包搜索结果。
设置界面卡片
安装后，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 界面中渲染设置卡片。两者只在凭据服务处交汇。
▼text复制代码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
开发
▼sh复制代码pnpm install # 全部依赖（包括 DSH 接缝包）均来自 npm pnpm typecheck # tsc --noEmit pnpm build # 产出 lib/*.js + lib/types/*.d.ts pnpm test # 单元测试
在线冒烟测试在没有密钥时自动跳过：
▼sh复制代码DOUBAO_SEARCH_API_KEY=<密钥> pnpm exec vitest run tests/doubao.e2e.ts
贡献指南见 CONTRIBUTING.md。
