dsh-tinyfish-search

dsh plugin --profile web add dsh-tinyfish-search

dsh-tinyfish-search

本项目由 dsh-superagent 辅助维护。

英文 | 中文

DeepSeek Harness 插件，把内置 web_search 工具接到 TinyFish Search API。每次查询只需一次 GET，无模型调用——更快且免费（TinyFish Search 在任意钱包余额下免费）。

插件作用

DeepSeek Harness 内置的 web_search 工具默认走 DeepSeek 的 Anthropic 兼容端点（web-search-deepseek）。本插件在 ctx.web 能力缝上注册了一个网页搜索提供方：

• 稳定提供方 ID：tinyfish
• 每次 web_search 调用变成 GET https://api.search.tinyfish.ai?query=...，携带 X-API-Key 请求头
• 把 results[]（标题 / 摘要 / 链接 / 日期）归一化为缝接口的可移植来源结构
• 通过 WebSearchProvider.ready() 上报提供方就绪状态（DeepSeek Harness 0.2.2 起）：宿主在声明 web_search 之前会先询问它，因此没有可用 TinyFish 凭据的 profile 干脆不显示 web_search 工具，而不是显示一个每次调用都失败的工具
• 每次搜索都不会消耗模型轮次——与 Anthropic 服务器工具方案不同
• 内置原生 icon.svg 矢量图标与中英双语清单资源（locale/en.json、locale/zh.json），完全符合 DSH 0.2.2-rc.1 插件管理器展示规范
• 源码、脚本与构建配置均为纯 TypeScript 架构

安装本插件后，内置 web_search 会被自动接管：bundle patch 会覆盖 web 能力缝行（searchProvider: tinyfish，并重述 fetchProvider: http）——因为 dsh-base 把该行钉死为 deepseek-official，否则插件即使注册了 provider，工具仍会走 DeepSeek 后端。同时补丁还会重新启用宿主层 tool-web 行（disabled: false，并重述 search: true、fetch: true 及基础超时值）：dsh-web-app bundle 自带该行的禁用（Web 应用本应按 agent 预设逐会话组合 web 工具），缺了这一行，干净安装到 web profile 后模型根本看不到 web_search 工具。作用范围说明：重启用宿主行会让工具对本 profile 上的每一个 agent 预设可见——包括原本不带 web 工具的预设（如 minimal）；自带 tool-web 行的预设仍会以自己的注册遮蔽这个全局注册。若希望把工具限定在单个预设内，请在 profile 的 cordis.patch.yml 中覆盖或移除 tool-web 行，并把 tool-web 加入该预设的 agent 组合。更后层（profile / home cordis.patch.yml / --patch）仍可按 id 覆盖这两行。

配置以易变（volatile）schema 声明（DeepSeek Harness 0.1.7 起）：Host 读取本插件导出的 Config schema，并为 Plugins 页上的 dsh-tinyfish-search 行渲染配置表单。插件侧不再有设置注册，也不再需要自带浏览器半端。保存的修改无需重启即对下一次搜索生效。

环境要求

• DeepSeek Harness dsh CLI（任意带 web 缝的 profile，如 web）——构建基线为 0.2.2-rc.1（2026-11-04 发布于 npm 的 next 标签），并另在 0.2.1-rc.5（npm latest 标签、桌面版运行时）上验证通过；0.2.2 携带 WebSearchProvider.ready()，而 0.2.1-rc.* 维护线早于该契约，因此停留在该线上的 profile 运行本插件时不启用就绪闸门；插件声明 engines.dsh 为 >=0.1.7-alpha.2 <0.3.0，因此整条 0.1.7 预发行线与 0.2.x 线均可通过准入
• Node.js ^22.19.0 || >=24.0.0（与 harness 的引擎区间一致）——在 0.2.2-rc.1 宿主上实际门槛为 Node 24.9：该宿主把自己的最低要求提高到 24.9，低于此版本拒绝运行；本插件的 engines.node 未改动
• 一个 TinyFish API key（免费创建；Search 免费）
• 宿主的凭据缝与启动环境（@deepseek-ai/dsh-credentials、@deepseek-ai/dsh-launch-environment）是必需的 peer 依赖——每个 dsh profile 都已自带

宿主兼容性闸门

DeepSeek Harness 会在准入插件行之前，用宿主声明的运行时要求校验正在运行的运行时版本，不兼容的插件会被直接拒绝，而不是照常加载。从 0.2.1-alpha.4 起，判定规则有所变化： 包自身声明了 engines.dsh 区间时，就只按该区间判定，兼容性判断完全忽略 @deepseek-ai/dsh* 的 peerDependencies；只有在缺少 engines.dsh 时才回退到逐条检查这些 peer。两者都按预发行规则匹配（semver.satisfies(runtime, range, { includePrerelease: true })），因此预发行版运行时也参与区间比较，拒绝记录中报告的字段是 requirements 而非 peers。

本插件声明 engines.dsh: ">=0.1.7-alpha.2 <0.3.0"，该区间在 0.2.2-rc.1、0.2.1-rc.5、0.2.0-rc.2、0.2.0-rc.1 与整条 0.1.7 预发行线上均成立，因此无需任何豁免。0.14.0 与 0.13.0 的 engines.dsh 也已声明同一放宽区间，所以它们在 0.2.2-rc.1 上同样被准入。但窄区间的 0.12.0 声明的是 ^0.1.7-alpha.2，不含 0.2.x，所以 harness 在 0.2.x 上仍会拒绝 0.12.0——此时应升级到 0.19.0，而不是授予豁免。若你在声明区间之外的 dsh 上运行，DSH 会拒绝该行并打印确切的要求对；要显式接受该风险，请按提示对确切要求对授予豁免：

dsh plugin allow-version dsh-tinyfish-search@0.19.0 --dsh-version <your-dsh-version> --accept-risk

文档导航

• [安装说明文档](INSTALL.zh.md) ([英文](INSTALL.md))
• [使用说明文档](USAGE.zh.md) ([英文](USAGE.md))
• [配置说明文档](CONFIG.zh.md) ([英文](CONFIG.md))
• [更新说明文档](UPDATE.zh.md) ([英文](UPDATE.md))
• [卸载说明文档](UNINSTALL.zh.md) ([英文](UNINSTALL.md))
• [更新日志](CHANGELOG.zh.md) ([英文](CHANGELOG.md))

安装

dsh plugin --profile web add dsh-tinyfish-search

或者从仓库 / tarball 安装：

dsh plugin --profile web add ./dsh-tinyfish-search        # 源码目录
dsh plugin --profile web add ./dsh-tinyfish-search-0.19.0.tgz
dsh plugin --profile web add github:maxwell-feng/dsh-tinyfish-search

命令行语法说明：根据 DeepSeek Harness 0.2.1-alpha.1 规范，--profile <name> 必须置于 add、remove、update 等子命令之前。

Git 安装拿到的是源码而非构建产物：pnpm 会运行包的 prepare 脚本，通过 tsc -p tsconfig.build.json 自动从源码编译构建 lib/。

详见[安装说明](INSTALL.zh.md)：环境要求、全部安装方式与验证步骤。

配置

设置 API key（推荐——配置文件中不出现密钥）：

Linux / macOS：

export TINYFISH_API_KEY="your_api_key_here"                      # 仅当前 shell
echo 'export TINYFISH_API_KEY="your_api_key_here"' >> ~/.bashrc  # 永久生效（bash）
echo 'export TINYFISH_API_KEY="your_api_key_here"' >> ~/.zshrc   # 永久生效（zsh）
source ~/.bashrc                                                 # 或重开终端

Windows（PowerShell）：

setx TINYFISH_API_KEY "your_api_key_here"    # 永久生效——新开的终端生效
$env:TINYFISH_API_KEY = "your_api_key_here"  # 仅当前会话生效

或在 profile 的 cordis.yml / patch 层设置字段：

- insert:
    - id: dsh-tinyfish-search
      name: dsh-tinyfish-search
      config:
        # apiKey: "字面量密钥"          # 环境变量的替代方案；注意不要提交到仓库
        # apiKeyEnv: TINYFISH_API_KEY     # 默认值
        # baseURL: https://api.search.tinyfish.ai   # 默认值
        # location: US                    # 可选的地区定位，转发给 TinyFish 的 location
        # language: en                    # 可选的搜索语言，转发给 TinyFish 的 language

字段 · 默认值 · 含义

apiKey · — · TinyFish API key 字面量（secret 角色；优先于环境变量）

apiKeyEnv · TINYFISH_API_KEY · 承载 API key 的环境变量名

baseURL · https://api.search.tinyfish.ai · TinyFish Search API 端点基地址

location · — · 可选地区，转发为 TinyFish 的 location（如 US）；留空/未设置则不发送

language · — · 可选搜索语言，转发为 TinyFish 的 language（如 en）；留空/未设置则不发送

完整 schema、凭据解析顺序与运行时设置界面见[配置说明](CONFIG.zh.md)。

验证

dsh --profile web --dump-config | grep tinyfish   # 层已加载

在会话里调用 web_search，检查结果是否带 TinyFish 的链接/摘要。GUI 的「网页搜索」设置卡片会显示提供方状态。

使用

安装后无需代码改动。在任意带 web 能力的会话中：

1. 模型按常调用 web_search（如“搜索 TinyFish 文档”）。

2. 框架经 ctx.web → tinyfish → https://api.search.tinyfish.ai 路由请求。

3. 结果以 WebSearchSource[]（url / title / snippet / publishedAt）形式出现在工具结果中。

4. GUI：设置 → 网页搜索

…(truncated)