DSH Search Ledger
简体中文 · English
DSH 原生 web_search / web_fetch 的渠道管理和费用统计插件。
在 DSH 里同时用 DeepSeek 官方 API、中转和其他搜索服务时，搜索该走哪个渠道、失败后换谁、用了多少次，都需要分开配置和查看。这个插件把这些事放到一个页面里：按模型 Provider 绑定搜索渠道，管理每个渠道的 Key，再用本地账本记录实际请求。
当前版本为 0.6.2，清单只声明 DSH 版本下限 >=0.2.0-rc.2、不设上限，升级 DSH 不会因版本声明被拒。它统计的是经过插件的搜索和抓取请求，不是模型 Token 用量；显示的费用是本地估算，不能代替服务商账单。
功能
- Search 和 Fetch 可以选不同渠道，也可以按 Provider、全局或会话单独覆盖。
- 官方 API 和中转分别设置价格、币种及计费方式，不把它们混在一起算。
- 一个渠道可以保存多个 Key，每行一个。正常请求轮换起点，遇到失败先尝试同渠道的其他 Key。
- 可以开启有序切换。缺 Key 的引擎直接跳过，失败、限流或超时后按配置顺序尝试下一个渠道；成功或合法的空搜索结果会停止切换。
- 每次实际尝试都会单独记账。同一轮切换通过
operationId 关联，历史记录使用请求当时的价格，不会随当前配置重新计算。
- 用量可以按日期、渠道、来源 Provider、会话和币种筛选。界面支持深色、窄面板、键盘操作和长下拉列表。
- 诊断页可只读检查后端接管、Provider 路由与候选凭据状态，并按操作关联最近的账本尝试。它不会测试 Key 或发送搜索请求。
- 用量页支持导出 CSV / JSON；开发版本还包含可选的预算与渠道熔断状态，默认不启用。
Key 可以直接在界面填写，也可以逐个测试。测试需要先确认费用风险，不会自动保存输入或切换到别的渠道。
和只接入搜索 API 的插件有什么区别
这里多做的一层，是把请求路由和费用记录连起来。
例如，官方 DeepSeek Provider 的 Search 走官方 API，中转 Provider 的 Search 走中转，Fetch 则统一走本地 HTTP。三者可以各用各的价格和凭据，不必为了换一个操作而更换整套搜索配置。
失败后的账目也会保留。第一个渠道超时，第二个成功，不意味着只发生过一次请求。插件会留下前一次尝试，并把无法确认的结果单独标出来。价格没填时显示未知，不会因为金额暂时算不出来就显示成免费。
如果需要在多个 Provider 和搜索服务之间分配请求，或者想查清一次调用走了哪里、费用为什么增加，这些记录会比较有用。它不做全账户账单同步，也不会自动挑选最便宜的服务、搜集公共搜索实例或悄悄启用收费接力。这里介绍的是本插件的做法，不是对某个第三方插件的测试结论。
支持的渠道
| 渠道 | Search | Fetch | 备注 |
|---|
| DeepSeek 官方 API | ✓ | ✓ | Search、Fetch 分别计价 |
| DeepSeek 兼容中转 | ✓ | ✓ | 需要兼容工具 API，只支持聊天接口不够 |
| TinyFish | ✓ | ✓ | 使用对应操作的官方 API 地址 |
| 百度千帆 | ✓ | — | 只支持 Search |
| Tavily | ✓ | ✓ | basic Search / Extract；credits 在本地保守预留 |
| SearXNG | ✓ | — | 自建或获准使用的实例，需要启用 JSON 输出 |
| 本地 HTTP | — | ✓ | 复用 DSH 抓取后端，没有本插件按次收取的 API 费用 |
是否免费、能用多少次，要看服务商的账户计划。SearXNG 和本地抓取也有部署、网络及目标站点访问成本，不代表无限免费。
安装
本版本需要 Node.js ≥22.19 和 DSH ≥0.2.0-rc.2（只有下限，没有上限），DSH 升级后不会被判定为不兼容；开发与测试基线是 DSH 0.2.1-rc.2，其他版本未逐一验证。
从 npm 安装
安装前先退出共享 DSH_HOME 的 DSH 进程，备份目标 Profile 和插件数据：
dsh plugin --profile web add "dsh-search-ledger@0.6.2" --ignore-scripts
把 web 换成实际 Profile。普通 npm install 只会把包加入当前 Node 项目，不会替 DSH 注册插件或应用 patch。遇到 minimumReleaseAge 拒绝时，先检查依赖或等待版本满足时间要求，不要删除锁文件或全局关闭保护。
从 0.6.0 或更早版本升级
**此版本不会自动迁移旧配置、凭据和账本。**旧渠道配置与 Key 池不会自动迁移；升级后可能需要恢复配置并重新填写 Key。旧池 Key 不会在界面回显，如没有留存，请在服务商处重新生成；不要把 Key 写入配置文件。
- 完全退出共享该 DSH_HOME 的所有 DSH 进程，先备份整个 Profile、宿主凭据存储以及
$DSH_HOME/web-search-billing/。备份须包含数据库及相关文件和 installation-salt，不要只复制正在写入的数据库。
- 检查
$DSH_HOME/dsh-search-ledger/：目标目录已存在时停止，不要覆盖、删除或合并；其中可能已有新账本。保留两份数据并先确认迁移方案。
- 目标目录不存在且确认全部进程已停止时，可将旧目录完整复制到新目录，保留原目录作为备份。数据库及
installation-salt 必须一起保留；这一步只处理账本，不会迁移配置和 Key。
- 在 Profile 配置中检查旧的
web-search-billing 配置入口；备份后将相关渠道、Provider 绑定、覆盖和故障转移配置迁移到 dsh-search-ledger 对应入口。不要盲目替换其他插件的配置。
- 确认当前安装的包名：0.5.1 的包名已是
dsh-search-ledger，早期包可能是 dsh-web-search-billing。按实际情况升级或先移除旧包；不要在同一 Profile 中同时安装两个包。
- 重启后检查历史账本、渠道配置、路由与 Key 状态。旧池 Key 需要在新渠道中重新输入并保存；确认无误后再发起请求。原始备份应保留到验证完成。
此手动流程尚未覆盖所有宿主配置和冲突场景；迁移前如不确定配置来源或目标目录状态，先停止并保留备份，不要强制继续。
配置
重启 DSH 后，在设置侧边栏打开 DSH 搜索账本，按下面的顺序配置：
- 在 渠道管理 添加渠道，填写名称、地址和费率，保存渠道配置。新建渠道默认停用，不会自动发送请求。
- 展开渠道，在 API Key 区域每行输入一个 Key，保存 Key 池。之后再次保存会替换整个池，不是追加。已经保存的 Key 不会显示出来。
- 在 渠道地址、费率与高级配置 勾选“启用”，再保存渠道配置。保存 Key 和启用渠道是两件事。
- 到 Provider 与覆盖，为实际的模型 Provider ID 分别选择 Search、Fetch 渠道并保存。覆盖顺序是：会话覆盖 → 全局覆盖 → Provider 绑定。
- 确认宿主 Web 工具使用
web-search-metered / web-fetch-metered 后端，发起一次原生调用，再去 用量与费用 看最近记录。
安装 patch 会选择这两个后端，但其他更高优先级的配置可能覆盖它。插件不默认绑定模型 Provider，也不会在没有绑定时自行选择收费渠道。
需要自动切换时，在对应操作下打开“有序切换”，调整渠道顺序和超时预算。配置示例在 provider-routing.patch.yml，其中的 Provider ID、地址和价格都需要按实际情况修改。
测试 Key
选择 Search 或 Fetch，再点击“测试 Key”。输入框有内容时测本次输入，为空时测已保存池或兼容凭证引用。测试后输入会保留，需要自己点保存。
每个 Key 只试一次，单 Key 最多 10 秒，整批最多 60 秒。测试不切换渠道，但可能收费，也会写入账本。Fetch 的测试目标固定为 https://example.com/。超时、限流和网络错误不一定是 Key 无效，也不能说明服务商没有扣费。
Key 池最多支持 32 个 Key。正常请求的轮换游标在当前进程内共享，重启后重置。
诊断与导出
在“诊断”页选择 Provider 和 Search / Fetch，查看后端接管证据、默认路由及候选凭据状态。凭据可读取不等于认证有效；默认路由不包含会话覆盖。时间线最多读取最近 200 条尝试，达到上限时同一次操作可能显示不完整；没有记录的跳过或安装前调用不能推断。
诊断 JSON 导出需要确认，包含插件版本、自检状态、结果统计及最近尝试的操作、状态、时间和 HTTP 状态码，不包含渠道名、Provider ID、Key、查询词或网页正文。时间仍可能敏感，分享前请检查。用量页的 CSV / JSON 是另一个导出，包含渠道和来源 Provider 等元数据，每次最多 20,000 条。
预算与熔断设置目前通过宿主配置文件设置，界面提供状态查看和熔断复位。预算仅依据当前 Profile 的本地账本，金额只统计已确认费用；超时、其他客户端的用量及并发请求可能导致实际费用超过上限，不能代替服务商的账户限额。熔断或预算开启后可能改变派发行为，请先了解配置再启用。
费用怎么算
统计单位是实际 API 尝试，不是聊天轮数。一次工具调用里有多个查询时，可能发送多次底层请求。
DeepSeek 官方渠道默认给 Search 和 Fetch 各设置 5 CNY／千次，按 HTTP 200 且结果非空确认计费。这是插件的默认配置，不会实时同步服务商价格。中转可以独立填写单价，选择非空成功或所有 HTTP 200 计费，具体口径要自己与服务商核对。
例如，单价 5 元／千次，10 次计费成功就是 0.05 元。金额在内部用整数微单位累加，CNY 和 USD 分开显示，不自动换汇。
账本会分别显示计费成功、空结果、明确失败、未确认和未知价格。请求发出后超时、断连或响应无法解析时，可能无法确认服务端是否计费，因此不会直接按免费处理。后续切换成功，也不会删掉前面的尝试。
插件只能记录经过自己后端的请求。其他插件、设备、模型服务端内部搜索，以及安装前没有被观测到的调用，都不在统计范围内。
Tavily 的 credits 也只是本地保护。同一 DSH_HOME 下，相同 Key 在不同渠道和 Profile 间共享本地额度；其他工具、设备或 DSH_HOME 的消耗无法统计，不能据此保证整个账户不超支。
数据和备份
Key 池保存在宿主凭据存储中，按 DSH_HOME、Profile 和渠道隔离，不写进插件配置或账本，也不覆盖模型的同名凭证。宿主默认的本地存储不是加密保险箱，仍然需要保护本机账户和文件。
账本不保存 Key、Authorization、查询词或网页正文，只保留渠道身份、请求归属、时间、状态和价格等计量信息。数据目录是 $DSH_HOME/dsh-search-ledger/。
备份前停掉共享该目录的进程，把数据库及其相关文件和 installation-salt 一起保留。不要只复制正在写入的主数据库。旧账本升级前会先做一致性备份；失败不会自动删除账本。也不要在同一目录混跑新旧版本，或只修改数据库版本号来回退。
有历史账目的渠道仍能正常使用，只是不能删除或更换地址归属。要换服务就新建渠道，不再用的可以停用。修改名称或价格不会重算历史账目。
常见问题
渠道已经保存，为什么还是不能选？
先到渠道高级配置里勾选“启用”并保存。停用渠道会列出原因，但不能选择。千帆只支持 Search，不会出现在 Fetch 下拉框里。
搜索过了，为什么用量是空的？
检查宿主后端、Provider 绑定、Key 和渠道启用状态，再看看日期与币种筛选。配置看起来正确，不代表请求已经成功；没有经过插件的调用也不会入账。
“已有请求记录”是不是说渠道不能用了？
不是。这个提示是在保护历史账目，不是在停用渠道，也不是连通性检测。只要渠道启用、凭据和路由有效，就能继续使用。
卸载会删除账本吗？
不会。退出 DSH 后运行下面的命令，把 web 换成实际 Profile：
dsh plugin --profile web remove dsh-search-ledger
卸载不会自动擦除历史数据。
开发
node scripts/check.mjs # 类型检查、测试、构建和发布契约
node scripts/test.mjs # 只跑行为测试
node scripts/typecheck.mjs # 只检查 Host / Client 类型
0.5.1 功能基线通过了 235 项行为测试，仓库也包含打包、真实 Renderer Loader 和桌面安装入口的契约检查。浏览器检查覆盖保存后展开、窄面板、深色、缩放和 2000 项菜单。
这些验证使用合成 Key 和模拟响应，不代表所有服务商真实账户或所有 Electron 环境都已经测过。固定宿主开发依赖仍有已记录的安全限制，开发时不要处理不可信压缩文件，也不要为了本插件擅自替换宿主依赖。
反馈问题时，请附上版本、复现步骤和脱敏后的错误信息。不要上传 Key、完整诊断包或个人 Profile。
许可证
MIT。打包依赖的许可见 THIRD_PARTY_NOTICES.md。
