DreamRift/dsh-web-search-pool

dsh-web-search-pool

License: MIT DSH: 0.1.1-rc.x / 0.1.2+

多供应商搜索负载均衡插件，为 DeepSeek Harness 提供 web_search 能力：把多个 Tavily / Exa key 组成一个智能池，按各自限流调度，失败自动切换。

✨ 特性

- 🔑 多 key 池 — 统一管理任意数量的 Tavily / Exa key，key 只以凭据引用形式存在
- ⚖️ 限流感知调度 — smooth weighted round-robin（按 rpm 加权）或 least-used
- 🔄 自动故障转移 — 429 / 额度耗尽 / 网络错误 / 超时自动换 key，供应商间（Tavily ↔ Exa）自动兜底
- 📊 用量仪表盘 — 设置页卡片显示 Tavily 已用/总额度与「立即刷新」，额度耗尽自动长冷却
- 🆓 Exa 匿名免费层 — 不填 key 即用官方托管 MCP（1 req/s），有 key 走 REST 提配额
- 🧩 原生 Bundle — 官方 cordis.patch.yml 装配 + 设置页卡片，兼容 DSH 0.1.1-rc.x 与 0.1.2+

📦 安装

npm pack
dsh plugin --profile web add ./dsh-web-search-pool-.tgz
dsh --profile web --dump-config      # 期望：searchProvider: search-pool

前置：DSH 0.1.1-rc.x / 0.1.2+，pnpm 在 PATH，至少一个搜索 key（Exa 可用匿名免费层）。
完整步骤、升级、回滚与排障见 安装与升级。

⚙️ 配置

Settings → Plugins → 「搜索 Key 池」 卡片：添加 key（环境变量名 / 限流 RPM / 备注）→ 保存。

密钥只经 DSH credentials 服务保存，不写入 settings.yaml；Exa 的环境变量名留空即启用匿名免费层。
字段与默认值全表见 架构与机制 §6。

🛠️ 使用

安装后自动接管 web_search，无需手动选择 provider：按当前限流与额度选 key → 失败自动换 key / 换供应商 → 返回结构化结果与错误（不暴露密钥）。

🧪 测试

node scripts/run-tests.mjs        # 112 个 node:test 用例（免 spawn，跨平台）
npm test                          # 等价入口：node --test tests/
node --check src/dsh/index.js     # 语法检查
npm pack --dry-run                # 打包内容校验

📄 文档

| 文档 | 内容 |
|---|---|
| 安装与升级 | 安装 / 验证 / 配置 / 升级 / 回滚 / 故障排查 |
| 架构与机制 | DSH seam 与 Bundle 装配、调度核心、配置模型、错误映射、扩展路径 |
| 开发规范与事故复盘 | 五类真实事故的根因与教训、开发检查清单、发布流程 |
| CHANGELOG | 版本变更历史 |

🔧 故障排查

| 现象 | 处理 |
|---|---|
| 设置页没有卡片 / keyed slot requires options.key | 升级到 0.2.0+ 并重启 DSH |
| Web UI 报 Failed to load plugins / dsh-web-search-pool | 升级到 0.2.1+（client 需声明 remote 命名空间 inject） |
| 仍走官方搜索 | dump-config 检查 include:web 的 searchProvider |
| 点击「立即刷新」无变化 | 重启 DSH，查看 usageDiagnostic |

完整排查表见 安装与升级 §9。

🔐 安全

- 无硬编码密钥；key 只经 DSH credentials 服务读写，每次操作 resolve，不缓存明文
- 日志只记 provider/keyId/ok/code，不含密钥；错误信息不泄露凭据
- 不写未注册的会话事件（避免污染会话历史）

📜 许可证

MIT — 见 LICENSE。

为 DeepSeek Harness 社区构建 · 原生插件生态的一部分