前言¶
在 DSH 里同时接 DeepSeek 官方 API、兼容中转和第三方搜索服务时，Search 和 Fetch 往往要各配一套地址和 Key；不同模型 Provider 还可能希望走不同渠道。失败后要换渠道、多个 Key 要轮换，用量和费用又散落在各家控制台里，很难在一次工具调用后回答「实际走了哪条路、试了几次、花了多少钱」。
dsh-search-ledger（维护者 gordan-code）是 DSH 原生 web_search / web_fetch 的渠道管理与费用统计插件。它把 Provider 绑定、Key 池、有序切换和本地账本放在同一设置页，统计的是经过插件后端的搜索与抓取请求，不是模型 Token；界面上的费用为本地估算，不能代替服务商账单。当前版本 0.5.1，适配 DSH 0.2.1-rc.2。插件属于社区目录中的「模型推理」分类；安装前请自行查看仓库源码与 MIT 许可证。插件在当前 DSH 进程权限下运行，Key 与账本数据落在本机，需按自己的安全策略保护 DSH_HOME。
这是什么¶
一句话：按模型 Provider 为 Search / Fetch 选择渠道，管理多 Key 与失败切换，并在本地记录每次 API 尝试的用量与估算费用。
与「只接入某个搜索 API」的插件相比，多出来的一层是把请求路由和费用记录连在一起。例如官方 DeepSeek Provider 的 Search 走官方 API，中转 Provider 的 Search 走中转，Fetch 统一走本地 HTTP——三者可各用各的价格和凭据。切换过程中失败的尝试也会入账；价格未填时显示未知，不会当成免费。
核心功能¶
路由与覆盖¶
- Search 和 Fetch 可选用不同渠道；也可按 Provider、全局或会话单独覆盖。覆盖顺序为：会话覆盖 → 全局覆盖 → Provider 绑定。
- 可开启有序切换：缺 Key 的引擎跳过；失败、限流或超时后按配置顺序尝试下一渠道；成功或合法空结果则停止。
- 安装 patch 会选用
web-search-metered/web-fetch-metered后端，更高优先级配置可能覆盖；插件不默认绑定模型 Provider，未绑定时不会自行选择收费渠道。
Key 池与轮换¶
- 每个渠道可保存多个 Key（每行一个，最多 32 个）。正常请求从轮换起点依次使用；单 Key 失败时先尝试同渠道其他 Key。
- Key 保存在宿主凭据存储中，按
DSH_HOME、Profile 和渠道隔离，不写入插件配置或账本明文。
本地账本¶
- 每次实际尝试单独记账；同一轮切换通过
operationId关联。历史记录使用请求当时的价格，不随当前配置重算。 - 用量可按日期、渠道、来源 Provider、会话和币种筛选。账本不保存 Key、Authorization、查询词或网页正文，数据目录为
$DSH_HOME/web-search-billing/（项目由dsh-web-search-billing更名而来，内部目录名保留旧名）。
支持的渠道¶
| 渠道 | Search | Fetch | 备注 |
|---|---|---|---|
| DeepSeek 官方 API | ✓ | ✓ | Search、Fetch 分别计价 |
| DeepSeek 兼容中转 | ✓ | ✓ | 需兼容工具 API |
| TinyFish | ✓ | ✓ | 使用对应操作的官方 API 地址 |
| 百度千帆 | ✓ | — | 仅 Search |
| Tavily | ✓ | ✓ | basic Search / Extract；credits 本地保守预留 |
| SearXNG | ✓ | — | 需启用 JSON 输出 |
| 本地 HTTP | — | ✓ | 复用 DSH 抓取后端 |
是否免费、配额多少取决于各服务商账户；SearXNG 与本地抓取仍有部署与网络成本。
安装与启用¶
需要 Node.js ≥ 22.19 与 DSH 0.2.1-rc.2；其他 DSH 版本未验证，不建议跳过兼容检查强行安装。
安装前停止共享该 DSH_HOME 的 DSH 进程，并备份目标 Profile 与插件数据。下面把 web 换成实际 Profile（桌面版常用 desktop）：
dsh plugin --profile web add "dsh-search-ledger@0.5.1" --ignore-scripts
dsh-search-ledger@0.5.1 已发布到 npm。普通 npm install dsh-search-ledger@0.5.1 只会把包加入当前 Node 项目，不会为 DSH 注册插件。更新前同样先退出 DSH，同一 Profile 不要混装旧包与新包。
若已安装旧包 dsh-web-search-billing，先退出 DSH，备份 Profile 与 $DSH_HOME/web-search-billing/，再移除旧包后安装新包，勿在同一 Profile 同时保留两个包：
dsh plugin --profile web remove dsh-web-search-billing
dsh plugin --profile web add "dsh-search-ledger@0.5.1" --ignore-scripts
卸载（不自动删除账本数据）：
dsh plugin --profile web remove dsh-search-ledger
典型用法：配置顺序¶
重启 DSH 后，在设置侧边栏打开 DSH 搜索账本，建议按下面顺序操作。
- 在 渠道管理 添加渠道，填写名称、地址和费率，保存。新建渠道默认停用，不会自动发请求。
- 展开渠道，在 API Key 区域每行一个 Key 并保存 Key 池。再次保存会替换整个池，不是追加；已保存的 Key 不会在界面回显。
- 在 渠道地址、费率与高级配置 勾选「启用」，再保存渠道配置。保存 Key 与启用渠道是两步。
- 到 Provider 与覆盖，为实际模型 Provider ID 分别选择 Search、Fetch 渠道并保存。
- 确认宿主 Web 工具使用
web-search-metered/web-fetch-metered后端，发起一次原生web_search或web_fetch，再到 用量与费用 查看最近记录。
需要自动切换时，在对应操作下打开「有序切换」，调整渠道顺序与超时预算。示例见仓库 provider-routing.patch.yml，其中的 Provider ID、地址和价格需按实际情况修改。
测试 Key¶
选择 Search 或 Fetch 后点击「测试 Key」。输入框有内容时测本次输入，为空时测已保存池。测试可能收费并写入账本；单 Key 最多 10 秒，整批最多 60 秒。Fetch 测试目标固定为 https://example.com/。
费用怎么理解¶
统计单位是实际 API 尝试，不是聊天轮数；一次工具调用含多个查询时可能对应多次底层请求。
DeepSeek 官方渠道默认给 Search 和 Fetch 各设 5 CNY／千次，按 HTTP 200 且结果非空确认计费——这是插件默认配置，不实时同步官网价。中转可独立填单价与计费口径（非空成功或所有 HTTP 200 等），需自行与服务商核对。
账本会区分计费成功、空结果、明确失败、未确认和未知价格。超时或响应无法解析时，不会默认按免费处理；前一次尝试失败、后一次切换成功时，两条记录都会保留。
插件只记录经过自己后端的请求；其他插件、设备或模型服务端内部搜索不在统计范围内。Tavily credits 仅为本地保护，不能保证整个账户不超支。
适用场景与注意¶
适合需要在多个 Provider 与搜索服务之间分配 Search / Fetch、或要追溯一次调用走了哪些渠道、费用为何增加的场景。它不做全账户账单同步，也不会自动挑选最便宜服务或悄悄启用收费接力。
有历史账目的渠道不能删除或更换地址归属；要换服务应新建渠道，旧渠道可停用。修改名称或价格不会重算历史。备份账本前停掉共享 $DSH_HOME/web-search-billing/ 的进程，并保留数据库相关文件与 installation-salt，不要只复制正在写入的主库。
DSH 生态强调「一切皆插件」；SkillHub 目录页 为社区站点，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-search-ledger 把 web_search / web_fetch 的渠道选择、Key 轮换、失败切换与本地费用账本集中在一处，便于在多 Provider 环境下可控地使用搜索与抓取。进一步了解可查看 GitHub 仓库 与 SkillHub 插件页。
