rm-Vstar/web-search-tinyfish

@rm-vstar/dsh-web-search-tinyfish

面向 harness web 能力 seam（ctx.web）的 TinyFish 后端 WebSearchProvider。它调用 TinyFish 专门的 搜索 REST 端点（GET {baseURL}?query=...），使用 X-API-Key 请求头完成鉴权——而不是 Bearer token——并把 TinyFish 返回的结构化 results[] 映射为 seam 标准化的 WebSearchResult。

这是实现型包：它向 ctx.web 注册 provider，每次搜索经可选的 ctx.credentials seam 解析凭据（默认引用 TINYFISH_API_KEY），不注册模型侧工具。与其它 web-search-* 包一致，它是 function/namespace 插件（inject: ['web']）。每次搜索只花一次轻量检索调用，而不是一次模型调用。

鉴权：X-API-Key，不是 Bearer

TinyFish 的 REST API 要求把 key 放在 X-API-Key 请求头中。本 provider 只发送该请求头，绝不发送 Authorization: Bearer（与发送后者的 Exa provider 不同）。

配置

| 键 | 默认值 | 含义 |
|---|---|---|
| apiKey | 省略 | 字面 TinyFish API key。优先使用 apiKeyEnv，避免密钥进入配置文件；非空字面值优先。 |
| apiKeyEnv | TINYFISH_API_KEY | 每次搜索经 ctx.credentials 解析的凭据引用，无该 seam 时回退到启动环境。缺失时调用以 WEB_PROVIDER_CREDENTIAL_MISSING 失败。 |
| baseURL | https://api.search.tinyfish.ai | TinyFish 搜索端点；追加 ?query=、&location= 与 &domain_type=。无法解析时 provider 不可用。 |
| location | US | location 查询参数（地区倾向）。 |
| domainType | web | domain_type 查询参数（搜索范围）。 |
| maxResults | 省略 | 请求未携带 maxResults 时的默认结果数；provider 在本地截断。 |

- id: web-search-tinyfish
name: '@rm-vstar/dsh-web-search-tinyfish'
config:
apiKeyEnv: TINYFISH_API_KEY
baseURL: https://gateway.internal/search

上述条目是 web-search-tinyfish Settings section 的 base 层：其上的用户层改动会作用到下一次搜索，因为 provider 每次调用都投影该 section，而非注册时捕获。因此端点变化不会让 seam 的 provider 选择出现闪烁。apiKey 带 role('secret')，任何层都不会出现在 describe() 响应中。

映射

TinyFish 不返回生成的答案文本，因此省略 content。sources[] 来自 results[]：url ← url、title ← title、snippet ← snippet；当 TinyFish 给出的摘录为空时，以宿主站点名 site_name 兜底作为 snippet——provider 绝不编造文案。maxResults 在本地强制执行，与 seam 返回时的强制逻辑一致：超额 sources 被截断并置 truncated。

provider 失败转为 WEB_PROVIDER_ERROR；调用方取消转为 WEB_ABORTED。HTTP 重定向在接触 Location 目标前被拒绝，并以 WEB_PROVIDER_ERROR 呈现。