dsh-tinyfish-search

英文 | 中文

> 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[]（标题 / 摘要 / 链接 / 日期）归一化为缝接口的可移植来源结构
• 每次搜索不消耗一次模型调用——与 Anthropic 服务器工具方案不同，更快更省
• 内置原生 icon.svg 矢量图标与中英双语清单资源（locale/en.json、locale/zh.json），完全符合 DSH 0.2.1-alpha.2 插件管理器展示规范
• 源码、工具脚本与构建配置 100% 采用纯 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.1-alpha.2 上全面验证；插件声明 >=0.1.7-alpha.2 <0.3.0 peer，因此整条 0.1.7 预发行线与 0.2.x 线均可通过准入
• Node.js ^22.19.0 || >=24.0.0（与 harness 的引擎区间一致）
• 一个 TinyFish API key（免费创建；Search 免费）
• harness 凭据缝与启动环境（@deepseek-ai/dsh-credentials、@deepseek-ai/dsh-launch-environment）为必需 peer 依赖——所有 dsh profile 均已内置

宿主兼容性闸门

DeepSeek Harness 0.2.1-alpha.2 会在加载插件行之前，用正在运行的运行时版本校验插件的 @deepseek-ai/dsh* peerDependencies；不兼容的插件会被直接拒绝，而不是照常加载，且预发行版参与区间匹配。本发行版声明 >=0.1.7-alpha.2 <0.3.0，在 0.2.1-alpha.2、0.2.0-rc.2、0.2.0-rc.1 与整条 0.1.7 预发行线上均实际满足，因此无需任何豁免。由于 0.14.0 与 0.13.0 已声明了这一放宽后的区间，它们在 0.2.1-alpha.2 上同样被准入。但窄区间的 0.12.0 声明的是 ^0.1.7-alpha.2，不含 0.2.x，所以 harness 在 0.2.x 上仍会拒绝 0.12.0——此时应升级到 0.15.0，而不是授予豁免。若你在声明区间之外的 dsh 上运行，DSH 会拒绝该行并打印确切的插件/运行时组合；要显式接受该风险，请按提示对确切版本对授予豁免：

dsh plugin allow-version [email protected] --dsh-version <你的 dsh 版本> --accept-risk

文档导航

• 安装说明文档 (英文)
• 使用说明文档 (英文)
• 配置说明文档 (英文)
• 更新说明文档 (英文)
• 卸载说明文档 (英文)
• 更新日志 (英文)

安装

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.15.0.tgz
dsh plugin --profile web add github:maxwell-feng/dsh-tinyfish-search

> 命令行语法说明：根据 DeepSeek Harness 0.2.1-alpha.1 规范，--profile 必须置于 add、remove、update 等子命令之前。
>
> Git 安装拿到的是源码而非构建产物：pnpm 会运行包的 prepare 脚本，通过 tsc -p tsconfig.build.json 自动从源码编译构建 lib/。

详见安装说明：环境要求、全部安装方式与验证步骤。

配置

设置 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

完整 schema、凭据解析顺序与运行时设置界面见配置说明。

验证

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：设置 → 网页搜索 显示提供方 tinyfish 与 available: true（已配置 API key 时）。

错误与中断语义遵循 dsh-web 缝接口：无密钥时 WEB_PROVIDER_CREDENTIAL_MISSING，取消时 WEB_ABORTED，其他为 WEB_PROVIDER_ERROR。

提供方、凭据配置、完整示例与错误表见使用说明。

卸载

dsh plugin --profile web remove dsh-tinyfish-search

移除 bundle 层与 tinyfish 提供方注册，web / tool-web 行会恢复为底层 bundle 原本的组合值（移除插入层后，被插入行的覆盖即回到其自身默认）。重启 dsh --profile web 确认 web_search 回退到基础 deepseek-official 提供方（若未安装其他提供方则为空）。

升级

dsh plugin --profile web add dsh-tinyfish-search@latest
# 或走 git，在改动进入 npm 前先行取用：
dsh plugin --profile web add github:maxwell-feng/dsh-tinyfish-search

从 ≤ 0.14.0 升级到 0.15.0 无需任何手工步骤：本版完成与 DeepSeek Harness 0.2.1-alpha.2 的对齐——即本插件所遵循的插件开发文档的最新发行版。本版本封装了原生 icon.svg 矢量图标与中英双语展示资源（locale/en.json、locale/zh.json），优化了自包含 prepare 构建脚本，更新了 --profile 命令行语法，并将 USER_AGENT 标识头更新为 dsh-tinyfish-search/0.15.0。@deepseek-ai/dsh-* peer 保持 >=0.1.7-alpha.2 <0.3.0。

从 ≤ 0.13.0 升级到 0.14.0 无需任何手工步骤：本版完成与 DeepSeek Harness 0.2.0-rc.2 的对齐——即本插件所遵循的插件开发文档的当前发行版——且除 USER_AGENT 版本常量外不改动任何插件源码。@deepseek-ai/dsh-* peer 保持 >=0.1.7-alpha.2 <0.3.0，因此 0.13.0 在 0.2.0-rc.2 上本就被准入——本版并非强制升级，而是把 devDependencies 锁定到 0.2.0-rc.2，并针对它重新验证每一处消费的接缝。0.2.0-rc.2 的增量是纯新增的——Cordis Inspect 诊断、TypertGateway.hasLiveClient()，以及定时提问——均未触及本插件使用的任何接口。USER_AGENT 标识头更新为 dsh-tinyfish-search/0.14.0。

从 ≤ 0.12.0 升级到 0.13.0 无需任何手工步骤：本版完成与 DeepSeek Harness 0.2.0-rc.1 的对齐——即本插件所遵循的插件开发文档的当前发行版——且除 USER_AGENT 版本常量外不改动任何插件源码。@deepseek-ai/dsh-* peer 区间放宽为 >=0.1.7-alpha.2 <0.3.0：因为 0.2.0-rc.1 把 peer 兼容性做成了硬性拒绝，而原先的 ^0.1.7-alpha.2 区间不含 0.2.x——正是这次放宽让插件在 0.2.0-rc.1 上通过准入，同时保持整条 0.1.7 预发行线仍可安装。所消费的全部接缝在 0.1.7-rc.2 与 0.2.0-rc.1 之间源码完全一致，配置字段没有任何迁移。USER_AGENT 标识头更新为 dsh-tinyfish-search/0.13.0。

从 ≤ 0.11.1 升级到 0.12.0 无需任何手工步骤：本版完成与 DeepSeek Harness 0.1.7-rc.2 的对齐——即本插件所遵循的插件开发文档的当前发行版——且除 USER_AGENT 版本常量外不改动任何插件源码。@deepseek-ai/dsh-* peer 保持 ^0.1.7-alpha.2，因此插件在 0.1.7-alpha.2 至 0.1.7-rc.2 的每一个 0.1.7 预发行版上均可安装；所消费的全部接缝在 0.1.7-rc.1 与 0.1.7-rc.2 之间源码完全一致。USER_AGENT 标识头更新为 dsh-tinyfish-search/0.12.0。

从 ≤ 0.11.0 升级到 0.11.1 无需任何手工步骤：本版不改运行时逻辑、不改配置、不改工具接口。仓库只保留 TypeScript 源码——双语文档闸门现为 scripts/check-docs-language.ts，由 Node 直接剥离类型运行——并修正了若干文档排序缺陷。

从 ≤ 0.10.0 升级到 0.11.0 无需任何手工步骤，但这是一次宿主基线抬升：插件现在要求 DeepSeek Harness 0.1.7-alpha.2 或更新，并已在 0.1.7-rc.1 上验证。在 0.1.6 宿主上 DSH 会拒绝该行（见宿主兼容性闸门）。配置迁移到 0.1.7 的易变 schema——字段、取值、默认值完全一致，只是编辑它们的表单换了实现。USER_AGENT 标识头更新为 dsh-tinyfish-search/0.11.0。

从 ≤ 0.9.0 升级到 0.10.0 无需任何手工步骤：完成与 DeepSeek Harness 0.1.6-alpha.2 的对齐（@deepseek-ai/dsh-* peer 现为 ^0.1.6-alpha.2，Node ^22.19.0 || >=24.0.0），USER_AGENT 标识头更新为 dsh-tinyfish-search/0.10.0。

从 ≤ 0.8.3 升级到 0.9.0 无需任何手工步骤：完成与 DeepSeek Harness 0.1.6-alpha.1 的对齐（@deepseek-ai/dsh-* peer 现为 ^0.1.6-alpha.1，Node ^22.19.0 || >=24.0.0），发布包现仅包含 lib/、cordis.patch.yml 与 LICENSE——各文档保留在本仓库中，不再随包安装进你的 profile。USER_AGENT 标识头更新为 dsh-tinyfish-search/0.9.0。

从 ≤ 0.8.1 升级到 0.8.3 无需任何手工步骤：内置企业级 SSRF 深度网络安全防御，并在 DeepSeek Harness 0.1.5-rc.2 上完成全量验证，USER_AGENT 标识头更新为 dsh-tinyfish-search/0.8.3。

从 ≤ 0.8.0 升级到 0.8.1 无需任何手工步骤：全面修复了 Dependabot 报告的 js-yaml 安全漏洞（CVE-2026-84375、GHSA-5p4m-2wfm-xmqj、CVE-2026-59869、CVE-2026-53550），维持纯 TypeScript 架构（零 JavaScript 残留），USER_AGENT 标识头更新为 dsh-tinyfish-search/0.8.1。

从 ≤ 0.7.0 升级到 0.8.0 无需任何手工步骤：设置节、补丁行与凭据引用都随 bundle 层携带，pnpm 会原地刷新包。插件采用纯 TypeScript 架构（零 JavaScript 残留），USER_AGENT 标识头更新为 dsh-tinyfish-search/0.8.0。

从 ≤ 0.6.1 升级到 0.7.0 无需任何手工步骤：设置节、补丁行与凭据引用都随 bundle 层携带，pnpm 会原地刷新包。插件代码遵循官方规范全面重构为模块化 TypeScript 架构，USER_AGENT 标识头更新为 dsh-tinyfish-search/0.7.0。

从 ≤ 0.5.0 升级到 0.6.1 无需任何手工步骤：设置节、补丁行与凭据引用都随 bundle 层携带，pnpm 会原地刷新包。可见的变化是 manifest 声明（manifestVersion: 1、@deepseek-ai/dsh-* peer 现为 ^0.1.5-rc.2、Node >=22）与 USER_AGENT 归属头（dsh-tinyfish-search/0.6.1）。

从 ≤ 0.4.0 升级到 0.5.0 无需任何手工步骤：设置节、补丁行与凭据引用都随 bundle 层携带，pnpm 会原地刷新包。唯一可见的变化是 harness 基线（@deepseek-ai/dsh-* peer 现为 ^0.1.5-rc.1，Node >=22）与 USER_AGENT 归属头（dsh-tinyfish-search/0.5.0）。

从 ≤ 0.2.1 升级到 0.3.0 无需任何手工步骤：设置节、补丁行与凭据引用都随 bundle 层携带，pnpm 会原地刷新包。唯一可见的变化是上文所述 web/tool-web 行的行为——若你本就自行覆盖过这两行，则一切保持你的覆盖不变。

开发

pnpm install
pnpm build     # tsc -> lib/
pnpm test      # node --test（mock fetch）
pnpm typecheck # tsc --noEmit，覆盖 src + test + scripts

仓库全量使用 TypeScript，没有需要同步维护的 JavaScript 源码。双语文档闸门为 scripts/check-docs-language.ts，CI 在安装依赖之前用裸 Node 直接运行它（无需任何依赖）：

node scripts/check-docs-language.ts

发布到 npm 通过 GitHub Actions 的 npm Trusted Publishing（OIDC）完成——见 .github/workflows/publish.yml 与 npm 文档。打 vX.Y.Z 标签（或手动触发工作流）即发布，构建溯源（provenance）自动生成。

更新说明

见 更新日志（中文）与 CHANGELOG.md（英文），以及 GitHub Releases 页面。

许可证

MIT — 见 LICENSE。