dgagf111/dsh-hydrasearch

dsh-hydrasearch

TinyFish + AnySearch 双后端搜索插件（DeepSeek Harness）。 注册进 ctx.web seam，让内置的 web_search / web_fetch 走两个可自动故障切换的后端。优先级可在插件页拖动调整，两个后端各自支持其 API 的全部参数，全部配置持久化。

兼容 DSH 0.1.6-alpha.2（@deepseek-ai/ 0.1.0-rc.6）。

- 它做什么
- 安装
- 优先级与故障切换
- 配置
- API Key 来源
- 开发

它做什么

插件只向 ctx.web 注册一个 provider —— hydrasearch，同时承担 search 与 fetch。两个后端的全部逻辑都封闭在它内部：故障切换链、各自的参数、凭据解析、配置卡片。TinyFish 与 AnySearch 对 seam 不可见。

实际生效的能力：

- web_search → 按优先级依次尝试两个后端，返回归一化的 {url, title, snippet, publishedAt}
- web_fetch → 同上
- 插件页配置卡片：拖动优先级、填 key、调每个后端的全部 API 参数
- 要把某个能力钉死在单一后端，用 searchBackend / fetchBackend（默认 auto 即走链）

安装

dsh plugin --profile web add github:dgagf111/dsh-hydrasearch

然后重启 dsh web。

从源码安装 / 手动部署

用 DSH 自带的 node 运行部署脚本：它会把包镜像进 profile 并按 bundle 接线
$node = "$env:USERPROFILE\.dsh\dsh-runtimes\dsh-primary-runtime\dependencies\node\bin\node.exe"
& $node scripts\deploy.mjs --profile desktop

脚本会把包装成 bundle 镜像到 profile（真实目录，非 symlink），并写入 dsh.profile.bundles 与 dependencies——这两条是插件页能列出它的前提。

然后在 profile 的用户层 cordis.patch.yml 里把 web seam 指过来（两个 id 必须一起写，只写一个会静默抹掉另一个）：

- id: web
config:
searchProvider: hydrasearch
fetchProvider: hydrasearch

插件只注册 hydrasearch 这一个 id，所以这里没有别的可选值。要换后端请改 searchBackend / fetchBackend，而不是改 provider。

重启 DeepSeek Harness，然后打开 插件页 → 已安装 → dsh-hydrasearch → 行内配置入口。

$DSH_HOME 默认是 Windows 的 %USERPROFILE%\.dsh、macOS/Linux 的 ~/.dsh；profile 布局为 $DSH_HOME/profiles//。上面是 PowerShell，其他 shell 请自行调整路径写法。

为什么必须作为 bundle 安装、为什么不能用 symlink——见 集成笔记。

凭据（可选但推荐）

TinyFish 需要 key，AnySearch 无 key 可用匿名档（额度较低）。两种方式：

tinyfish auth login          # 写入 ~/.tinyfish/config.json
或在插件卡片里直接填，会存进凭据中心 ~/.dsh/.credentials.yaml

优先级与故障切换

config.priority 是持久化的有序后端 id 列表，例如 ["tinyfish", "anysearch"]。

- 拖动卡片里的行即可调序（也支持 ↑/↓ 与 Alt+↑/Alt+↓）
- 拖动只改草稿，点"保存"才落盘，与其他字段共用一次 revision 校验
- 每次搜索都重新读取，所以改序后下一次搜索立即生效，无需重启
- 未知 id 会被丢弃、重复去重、缺失的后端按默认序补回——所以手改坏的 settings.yaml 也不会让某个后端凭空消失

搜索时自上而下遍历：

1. available() 为假（没 key / 被禁用 / 端点非法）→ 记 skipped-unavailable，跳过，不尝试
2. 尝试 → 失败 → 记 failed + 原因 → 切下一个
3. 成功 → 返回结果，并附注实际服务的后端与前面失败/跳过的原因

两条诚实性规则：

- "没试" 与 "试了并失败" 严格区分。前者只说明本地缺配置，后者才是后端有问题的证据。
- 取消（AbortSignal）不触发切换。用户中止请求必须停下，不能偷偷换个后端重试。

关闭 failover 后只使用顺序里第一个可用后端，它的失败就是最终结果。全部失败时抛第一个失败（让运维看到根因），不合成模糊的聚合错误。

要把某个能力完全钉死在一个后端（不参与切换），把 searchBackend / fetchBackend 从 auto 改成后端 id 即可。填了不存在的 id 会退回正常的链式遍历，不会让能力失效。

配置

全部字段持久化在 settings 命名空间 hydrasearch，每个字段用独立路径写入（如 ['tinyfish','language']），所以编辑一个后端永远不会覆盖另一个。

链（顶层）

| 字段 | 默认 | 说明 |
| --- | --- | --- |
| priority | [tinyfish, anysearch] | 后端顺序，卡片拖动调整 |
| failover | true | 失败时是否切下一个 |
| takeOverSearch | true | 组合未指定 web.searchProvider 时接管 |
| takeOverFetch | true | 同上，针对 fetch |
| searchBackend | auto | auto 跟随优先级，或钉死某个后端 id |
| fetchBackend | auto | 同上，针对 web_fetch |

TinyFish（tinyfish.）

| 字段 | 默认 | 对应 API 参数 |
| --- | --- | --- |
| enabled | true | — |
| apiKey | '' | X-API-Key；空则回退 env / CLI 配置 |
| apiKeyEnv | TINYFISH_API_KEY | 凭据中心的引用名 |
| searchBaseURL | https://api.search.tinyfish.ai/ | 搜索端点 |
| fetchBaseURL | https://api.fetch.tinyfish.ai/ | 抓取端点 |
| purpose | '' | purpose 搜索意图提示 |
| language | '' | language |
| location | '' | location |
| domainType | '' | domain_type：web / news / research_paper |
| includeDomains | '' | include_domains（逗号分隔） |
| excludeDomains | '' | exclude_domains（逗号分隔） |
| afterDate | '' | after_date（YYYY-MM-DD） |
| beforeDate | '' | before_date（YYYY-MM-DD） |
| recencyMinutes | 0 | recency_minutes（0=不发） |
| pubYearMin | 0 | pub_year_min（0=不发） |
| pubYearMax | 0 | pub_year_max（0=不发） |
| maxPages | 3 | 每次搜索最多翻几页（1–10） |
| fetchFormat | markdown | 抓取格式：markdown / html / json |
| fetchLinks | false | 抓取时同时返回页面链接 |
| verbose | false | 打印每次搜索/抓取日志 |

AnySearch（anysearch.*）

| 字段 | 默认 | 对应 API 参数 |
| --- | --- | --- |
| enabled | true | — |
| apiKey | '' | Authorization: Bearer；空则匿名访问 |
| apiKeyEnv | ANYSEARCH_API_KEY | 凭据中心的引用名 |
| baseURL | '' | API 地址；空则用公共地址 |
| tag | '' | tag 垂直子域（如 finance.quote）；空=通用网页搜索 |
| params | '' | params 垂直参数（JSON 对象字符串）；需先填 tag |
| zone | '' | zone |
| language | '' | language |
| maxResults | 10 | max_results（1–10） |
| verbose | false | 打印日志 |

写路径会校验：端点必须是绝对 URL、maxPages 在 1–10、fetchFormat 合法、日期是 YYYY-MM-DD、params 是合法 JSON 对象且必须同时有 tag。坏值在卡片层就被拒，不会静默禁用某个后端直到重启。

API Key 来源

两个后端都是：插件配置 → 环境变量 → 本地文件 → 凭据中心

- TinyFish：TINYFISH_API_KEY env → ~/.tinyfish/config.json（tinyfish auth login 写入）
- AnySearch：ANYSEARCH_API_KEY env → ~/.agents/skills/anysearch/.env

也可以在卡片里“写入凭据中心”（~/.dsh/.credentials.yaml）。key 是每次调用现读、不缓存的，所以存了 key 下一次请求立即生效，无需重启。

注意：如果是在 shell 里 export 了 key 然后启动 dsh 的，凭据中心会拒绝写入并报
"... is supplied read-only by the launching environment, so set would be shadowed; unset it in the shell you start dsh from instead"。
这是正确的保护——否则写入会“看起来成功”但仍被环境变量遮蔽。想用凭据中心管理 key，先从 shell 里 unset。

开发

npm install --legacy-peer-deps
npm run verify              # 服务端单元 + 契约（无 key 时跳过真实网络段）
npm run verify:client       # 浏览器半
npm run verify:integration  # 进程内集成
npm run verify:all          # 全部
npm run deploy              # 部署进 profile

verify-profile.mjs 需要真实 profile，用 DSH 自带的 node 跑；其余三个可脱离 DSH 独立运行。

四个套件的覆盖范围、DSH 集成坑（bundle 安装、row 锚定、跨版本符号、symlink）以及依赖代际问题，见 集成笔记。

目录

dsh-hydrasearch/
├── lib/
│   ├── index.js      # 插件主体：hydrasearch provider、故障切换链、settings、bridge 路由、系统提示
│   ├── tinyfish.js   # TinyFish transport
│   ├── anysearch.js  # AnySearch transport
│   └── client.js     # 浏览器半：优先级拖动 + 各后端参数表单（无需构建）
├── scripts/          # deploy + 四个验证套件
├── docs/             # 集成笔记
├── cordis.patch.yml  # Bundle patch（含全部默认值说明）
└── package.json

许可证

MIT