dsh-tinyfish-websearch 0.1.0

package/INSTALL.md

@@ -0,0 +1,93 @@
+# dsh-tinyfish-websearch 安装指南（接收方）
+
+把这个插件装进你的 DeepSeek Harness（DSH），默认 web 搜索就会替换为 **TinyFish**：
+免费搜索（30 次/分钟），模型无关、不消耗 LLM 额度，还带一个设置页可以随时改 API Key。
+
+> 本指南面向使用者。插件原理、配置项等完整说明见同目录的 [README.md](./README.md)。
+
+## 前提
+
+- 已安装 DSH，并已有 `web` profile（跑过 `dsh web`）。
+- 准备一个 TinyFish API Key：到 [tinyfish.ai](https://www.tinyfish.ai) 注册，**免费、不用绑卡**（注册后即可获取 key）。
+
+## 步骤 1：安装插件
+
+任选一种来源，在你的终端执行（不需要进任何目录）：
+
+```sh
+# npm 发布后
+dsh plugin --profile web add dsh-tinyfish-websearch
+
+# 或 GitHub 托管后
+dsh plugin --profile web add github:lijq3370/dsh-tinyfish-websearch
+
+# 或拿到的是插件文件夹（本地路径）
+dsh plugin --profile web add /绝对/路径/tinyfish-websearch
+```
+
+装完**不需要手动改任何配置文件**：插件会作为 bundle 自动进入 profile，并自动完成"注册 TinyFish provider + 把默认搜索切到 TinyFish"。
+
+## 步骤 2：重启 dsh web
+
+在你启动 dsh 的终端里 Ctrl+C 停掉，重新运行：
+
+```sh
+dsh web
+```
+
+重启后设置页侧边栏会出现 **「TinyFish 搜索」** 入口。
+
+## 步骤 3：配置 API Key
+
+任选一种（推荐第一种）：
+
+**方式 A：设置页填写（推荐）**
+打开 **设置 → TinyFish 搜索** → 在输入框粘贴 API Key → 保存。下次搜索立即生效，无需再重启。
+
+**方式 B：环境变量**
+在启动 `dsh web` 的环境里：
+
+```sh
+export TINYFISH_API_KEY=你的key
+```
+
+**方式 C：写入 `$DSH_HOME/.env`**
+
+```sh
+echo 'TINYFISH_API_KEY=你的key' >> ~/.dsh/.env
+```
+
+## 步骤 4：验证
+
+在任意会话里让 agent 搜一个话题（例如"DeepSeek Harness"）。能返回带来源链接的结果即成功。
+
+没配 key 时会看到明确报错：`TinyFish search has no API key; set it in Settings → TinyFish 搜索 or export TINYFISH_API_KEY`——按步骤 3 配置即可。
+
+## 常见问题
+
+| 现象 | 处理 |
+| --- | --- |
+| 设置页没有「TinyFish 搜索」入口 | 没有重启过 `dsh web`，重启即可 |
+| 搜索报 "has no API key" | 还没配置 key，见步骤 3 |
+| 搜索报 HTTP 429 | 超过免费档限速（30 次/分钟），稍等再试 |
+| 想换回 DSH 默认搜索 | 见下方"切回默认搜索" |
+
+## 切回默认搜索
+
+在你的 `~/.dsh/profiles/web/cordis.patch.yml` 末尾加：
+
+```yaml
+- id: web
+  config:
+    searchProvider: deepseek-official
+```
+
+重启 `dsh web` 即恢复 DSH 默认搜索（open-code-go / zen 原生搜索）。
+
+## 卸载
+
+```sh
+dsh plugin --profile web remove dsh-tinyfish-websearch
+```
+
+会同时从依赖和 bundle 层移除。卸载后默认搜索自动回到 `deepseek-official`（如果之前没覆盖过的话），重启 `dsh web` 生效。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lijq3370
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# dsh-tinyfish-websearch
+
+DeepSeek Harness **bundle 插件**：注册一个 **TinyFish** 驱动的 `web_search` provider 进 `ctx.web` 能力缝，并**把 DSH 默认搜索替换为 TinyFish**（默认引擎是 base bundle 的 `deepseek-official`，本插件的补丁层将其覆盖为 `tinyfish`）。模型无关，不消耗 LLM 额度；TinyFish 搜索免费，不消耗 credits。带一个**设置页表单**，可在界面里填/改/删 API Key。
+
+纯 ESM、零构建、**零 npm 运行时依赖**（provider 按 `ctx.web` 契约结构化实现，任何安装位置都能解析，不依赖模块兜底层）。
+
+## 安装（接收方：一条命令）
+
+```sh
+# 本地目录（开发/内部分发）
+pnpm dsh plugin --profile web add ./tinyfish-websearch
+
+# npm 发布后
+pnpm dsh plugin --profile web add dsh-tinyfish-websearch
+
+# GitHub 托管后
+pnpm dsh plugin --profile web add github:lijq3370/dsh-tinyfish-websearch
+```
+
+`dsh plugin` 只是 pnpm 转发器，等价于在 `$DSH_HOME/profiles/web` 里执行 `pnpm add <源>`；装完后自动完成两件事：
+
+1. 该包声明了 `dsh.bundle.patch`，自动加入 profile 的 bundle 层（`dsh.profile.bundles`）；
+2. bundle 补丁层（包内 `cordis.patch.yml`）自动插入 `tinyfish-websearch` 行，并把 `web` 行的 `searchProvider` 覆盖为 `tinyfish`。
+
+**无需手动改 cordis.patch.yml。** 重启 `dsh web` 后：
+
+- 设置页侧边栏出现 **「TinyFish 搜索」** 入口，界面填/改/删 API Key；
+- `web_search` 工具走 TinyFish（默认搜索已被替换）。
+
+## 切换回其他搜索引擎
+
+在你的 `$DSH_HOME/profiles/web/cordis.patch.yml`（应用顺序晚于 bundle 层，优先）加一行即可覆盖：
+
+```yaml
+- id: web
+  config:
+    searchProvider: deepseek-official   # DSH 默认（zen/go 搜索），或 tavily / exa 等已注册 provider
+```
+
+## API Key（界面配置）
+
+打开 **设置 → TinyFish 搜索**：密码框输入 key → 保存（写入 `$DSH_HOME/.credentials.yaml`，下次搜索立即生效，无需重启）；已配置时显示来源并可清除。
+
+解析优先级（每次搜索惰性解析）：
+
+1. 插件行的 `config.apiKey` 字面量（密钥落盘到配置）
+2. 凭据 seam `TINYFISH_API_KEY`：进程环境变量 → `$DSH_HOME/.credentials.yaml` → `$DSH_HOME/.env`
+
+注意：key 来自环境变量/.env 等只读层时，界面会提示不可修改（写会被凭据 seam 拒绝），需改环境变量。
+
+## 配置
+
+| 键 | 默认 | 含义 |
+| --- | --- | --- |
+| `apiKey` | 凭据 seam `TINYFISH_API_KEY` | TinyFish API key（字面量优先于界面/凭据） |
+| `baseURL` | `https://api.search.tinyfish.ai` | Search API 地址（GET 根路径即操作） |
+| `maxResults` | `5` | 结果数（1–20）；请求自带上限时以请求为准 |
+
+## 工作原理
+
+- **补丁层**（`cordis.patch.yml`，随 bundle 生效）：插入 `tinyfish-websearch` 行 + 覆盖 `web.searchProvider: tinyfish`。注意补丁按 id 整行替换 config，因此 `web` 行只 restate `searchProvider`；base bundle 当前也只设这一个键。
+- **宿主半**（`index.js`）：`apply(ctx, config)` 调用 `ctx.web.registerSearchProvider(new TinyFishSearchProvider({...}))`，与随包的 `web-search-perplexity` / `web-search-deepseek` 同一注册点；key 经 `ctx.credentials` 惰性解析。
+- **浏览器半**（`client.js`）：`settings.section` 槽位贡献「TinyFish 搜索」表单，经 `api.credentials.set/unset/describe`（RPC）读写凭据。
+- `GET {baseURL}?query=…`，`X-API-Key` 鉴权；凭据请求拒绝跟随重定向（`redirect: 'error'`）。响应映射：`results[]` → `sources[]`（url/title/snippet/date → publishedAt），`maxResults` 上限由能力缝在回程强制截断。
+
+## 手动验证
+
+```sh
+cd ~/.dsh/profiles/web/node_modules/dsh-tinyfish-websearch
+TINYFISH_API_KEY=tf-… node --input-type=module -e "
+  const m = await import('./index.js');
+  const p = new m.TinyFishSearchProvider({ apiKey: process.env.TINYFISH_API_KEY, baseURL: m.TINYFISH_DEFAULT_BASE_URL, maxResults: 3 });
+  console.log('available:', p.available());
+  console.log(await p.search({ query: 'DeepSeek Harness' }));
+"
+```
+
+## 限制
+
+- TinyFish 免费档限速 30 req/min（按 key 计）；搜索请求不消耗 credits，但账号需能访问 Search API（注册即有）。
+- 错误为带 `code` 属性的普通 `Error`（`WEB_PROVIDER_ERROR` / `WEB_ABORTED` / `WEB_PROVIDER_CREDENTIAL_MISSING`），非 `HarnessError` 类型；错误文本仍会透传模型，仅结构化错误元数据不完整。
+- 浏览器半由 `dsh.client` 声明自动发现；插件集变更（新增 `dsh.client`）需要重启才被 client-modules 扫描到。

package/client.js

@@ -0,0 +1,277 @@
+/**
+ * dsh-tinyfish-websearch — browser half.
+ *
+ * A classic script served at /plugins/dsh-tinyfish-websearch/client.js and
+ * executed by the client module system (the package.json `dsh.client`
+ * declaration makes client-modules pick the package up automatically). It
+ * registers a factory through window.__ModuleLoader__.load; the factory's
+ * exports become the cordis loader entry, so `apply(ctx)` runs as a
+ * browser-side plugin.
+ *
+ * Contribution: one `settings.section` entry — 「TinyFish 搜索」— with a form
+ * that writes the TinyFish API key through the credentials RPC
+ * (`ctx.remote.credentials.set`), which lands in `$DSH_HOME/.credentials.yaml`.
+ * The host half resolves the key per search through the credentials seam,
+ * so a key saved here takes effect on the next search without a restart.
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-tinyfish-websearch',
+  factory: function (require) {
+    'use strict';
+    var module = { exports: {} };
+    var exports = module.exports;
+    Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+    var React = require('react');
+
+    var NS = 'settings.tinyfish';
+    var inject = ['slots', 'locale', 'remote', 'remote.credentials'];
+    var REF = 'TINYFISH_API_KEY';
+
+    var zh = {
+      nav: 'TinyFish 搜索',
+      title: 'TinyFish 搜索设置',
+      loading: '加载中…',
+      notConfigured: '尚未配置 API Key。',
+      configuredFrom: '已配置（来源：{source}）。',
+      readOnly: '当前 Key 由只读层提供（环境变量 / .env），界面不可修改；请改环境变量后重启。',
+      keyLabel: 'API Key',
+      keyPlaceholder: 'TinyFish API Key',
+      save: '保存',
+      clear: '清除',
+      saved: '已保存，下次搜索立即生效。',
+      cleared: '已清除。',
+      retry: '重试',
+      hint: 'web_search 工具当前使用 TinyFish（searchProvider: tinyfish）。结果数等参数在 ~/.dsh/profiles/web/cordis.patch.yml 的 tinyfish-websearch 行配置。',
+    };
+    var en = {
+      nav: 'TinyFish Search',
+      title: 'TinyFish search settings',
+      loading: 'Loading…',
+      notConfigured: 'No API key configured yet.',
+      configuredFrom: 'Configured (source: {source}).',
+      readOnly: 'The key comes from a read-only layer (environment / .env); edit it there and restart.',
+      keyLabel: 'API Key',
+      keyPlaceholder: 'TinyFish API Key',
+      save: 'Save',
+      clear: 'Clear',
+      saved: 'Saved; the next search picks it up immediately.',
+      cleared: 'Cleared.',
+      retry: 'Retry',
+      hint: 'The web_search tool currently uses TinyFish (searchProvider: tinyfish). Result counts etc. live in the tinyfish-websearch row of ~/.dsh/profiles/web/cordis.patch.yml.',
+    };
+
+    var styles = {
+      wrap: { maxWidth: 560, display: 'flex', flexDirection: 'column', gap: 14, padding: '8px 0' },
+      title: { fontSize: 16, fontWeight: 600, margin: 0 },
+      hint: { color: 'var(--dsw-alias-label-tertiary)', fontSize: 13, lineHeight: 1.6, margin: 0 },
+      error: { color: 'var(--dsw-alias-state-error-primary)', fontSize: 13, lineHeight: 1.6, margin: 0 },
+      ok: { color: 'var(--dsw-alias-state-success-primary, #22c55e)', fontSize: 13, lineHeight: 1.6, margin: 0 },
+      row: { display: 'flex', alignItems: 'center', gap: 8 },
+      input: {
+        flex: 1, minWidth: 0, boxSizing: 'border-box', height: 32,
+        padding: '0 10px', font: 'inherit', fontSize: 14, lineHeight: 22,
+        color: 'var(--dsw-alias-label-primary)',
+        background: 'var(--dsw-alias-bg-layer-1)', border: '1px solid var(--dsw-alias-border-l2)',
+        borderRadius: 8,
+      },
+      button: {
+        border: '1px solid var(--dsw-alias-border-l2)', color: 'var(--dsw-alias-label-primary)',
+        font: 'inherit', fontSize: 13, cursor: 'pointer', background: 'transparent', borderRadius: 6, padding: '5px 12px',
+      },
+    };
+
+    /** One settings entry rendering the key form over the credentials RPC. */
+    function SettingsPanel(props) {
+      var describeCredential = props.describeCredential;
+      var storeCredential = props.storeCredential;
+      var removeCredential = props.removeCredential;
+      var t = typeof props.t === 'function' ? props.t : function (k) { return zh[k] || k; };
+
+      var viewPair = React.useState(null);
+      var view = viewPair[0];
+      var setView = viewPair[1];
+
+      var statusPair = React.useState('loading');
+      var status = statusPair[0];
+      var setStatus = statusPair[1];
+
+      var errorPair = React.useState(null);
+      var error = errorPair[0];
+      var setError = errorPair[1];
+
+      var valuePair = React.useState('');
+      var value = valuePair[0];
+      var setValue = valuePair[1];
+
+      var busyPair = React.useState(false);
+      var busy = busyPair[0];
+      var setBusy = busyPair[1];
+
+      var noticePair = React.useState(null);
+      var notice = noticePair[0];
+      var setNotice = noticePair[1];
+
+      var refresh = React.useCallback(function () {
+        if (typeof describeCredential !== 'function') {
+          setStatus('ready');
+          return;
+        }
+        describeCredential(REF).then(function (res) {
+          if (res && res.ok) {
+            setView(res.value ? res.value[REF] : null);
+            setStatus('ready');
+            setError(null);
+          } else {
+            setStatus('failure');
+            setError((res && res.error && res.error.message) || 'Failed to query credential status');
+          }
+        }).catch(function (e) {
+          setStatus('failure');
+          setError(String((e && e.message) || e));
+        });
+      }, [describeCredential, setView, setStatus, setError]);
+
+      React.useEffect(function () {
+        refresh();
+      }, [refresh]);
+
+      var save = function () {
+        if (value.length === 0 || busy || typeof storeCredential !== 'function') return;
+        setBusy(true);
+        storeCredential(REF, value).then(function (res) {
+          if (res && res.ok) {
+            setNotice({ kind: 'ok', text: t('saved') });
+            setValue('');
+            refresh();
+          } else {
+            setNotice({ kind: 'err', text: (res && res.error && res.error.message) || 'Failed to save credential' });
+          }
+        }).catch(function (e) {
+          setNotice({ kind: 'err', text: String((e && e.message) || e) });
+        }).finally(function () {
+          setBusy(false);
+        });
+      };
+
+      var clear = function () {
+        if (busy || typeof removeCredential !== 'function') return;
+        setBusy(true);
+        removeCredential(REF).then(function (res) {
+          if (res && res.ok) {
+            setNotice({ kind: 'ok', text: t('cleared') });
+            refresh();
+          } else {
+            setNotice({ kind: 'err', text: (res && res.error && res.error.message) || 'Failed to clear credential' });
+          }
+        }).catch(function (e) {
+          setNotice({ kind: 'err', text: String((e && e.message) || e) });
+        }).finally(function () {
+          setBusy(false);
+        });
+      };
+
+      if (status === 'loading') {
+        return React.createElement('div', { style: styles.wrap },
+          React.createElement('p', { style: styles.hint }, t('loading')));
+      }
+      if (status === 'failure') {
+        return React.createElement('div', { style: styles.wrap },
+          React.createElement('p', { style: styles.error }, error),
+          React.createElement('button', { style: styles.button, onClick: refresh }, t('retry')));
+      }
+
+      var configured = !!(view && view.configured);
+      var writable = !view || view.writable !== false;
+      var stateLine = configured
+        ? t('configuredFrom').replace('{source}', view.source || '?')
+        : t('notConfigured');
+
+      return React.createElement('div', { style: styles.wrap },
+        React.createElement('h2', { style: styles.title }, t('title')),
+        React.createElement('p', { style: styles.hint }, stateLine),
+        !writable
+          ? React.createElement('p', { style: styles.error }, t('readOnly'))
+          : React.createElement('div', { style: styles.row },
+              React.createElement('input', {
+                type: 'password',
+                placeholder: t('keyPlaceholder'),
+                value: value,
+                onChange: function (e) { setValue(e.target.value); },
+                style: styles.input,
+                autoComplete: 'off',
+              }),
+              React.createElement('button', {
+                style: styles.button,
+                onClick: save,
+                disabled: busy || value.length === 0,
+              }, t('save')),
+              configured
+                ? React.createElement('button', { style: styles.button, onClick: clear, disabled: busy }, t('clear'))
+                : null,
+            ),
+        notice
+          ? React.createElement('p', { style: notice.kind === 'ok' ? styles.ok : styles.error }, notice.text)
+          : null,
+        React.createElement('p', { style: styles.hint }, t('hint')));
+    }
+
+    /**
+     * Browser plugin body: register the dictionaries and the settings entry.
+     * @param ctx - the browser-side cordis context.
+     */
+    function apply(ctx) {
+      ctx.effect(function () {
+        ctx.locale.register(NS, { zh: zh, en: en });
+      }, 'tinyfish-websearch: dictionaries');
+      var t = ctx.locale.bind(NS);
+
+      var getRemote = function () {
+        return ctx.get('remote.credentials') || (ctx.remote && ctx.remote.credentials);
+      };
+
+      var describeCredential = function (ref) {
+        var remote = getRemote();
+        if (!remote) return Promise.resolve({ ok: false, error: { message: 'remote.credentials is unavailable' } });
+        return remote.describe([ref]);
+      };
+
+      var storeCredential = function (ref, val) {
+        var remote = getRemote();
+        if (!remote) return Promise.resolve({ ok: false, error: { message: 'remote.credentials is unavailable' } });
+        return remote.set(ref, val);
+      };
+
+      var removeCredential = function (ref) {
+        var remote = getRemote();
+        if (!remote) return Promise.resolve({ ok: false, error: { message: 'remote.credentials is unavailable' } });
+        return remote.unset(ref);
+      };
+
+      var injected = function () {
+        return {
+          describeCredential: describeCredential,
+          storeCredential: storeCredential,
+          removeCredential: removeCredential,
+          t: t,
+        };
+      };
+
+      ctx.slots.inject('settings.section', function () {
+        return ctx.slots.register({
+          name: 'settings.section',
+          id: 'tinyfish',
+          order: 50,
+          label: function () { return t('nav'); },
+          locale: NS,
+          inject: injected,
+        }, SettingsPanel);
+      });
+    }
+
+    exports.NS = NS;
+    exports.apply = apply;
+    exports.inject = inject;
+    return module.exports;
+  },
+});

package/cordis.patch.yml

@@ -0,0 +1,18 @@
+# dsh-tinyfish-websearch bundle patch: installing this package registers the
+# TinyFish search provider AND makes it the active search provider (replacing
+# the DSH default, which the base bundle sets to deepseek-official).
+#
+# A patch replaces the targeted row's whole `config`, so the `web` row below
+# restates every key it owns (searchProvider). The base bundle inserts the
+# `web` row with `searchProvider: deepseek-official`; this layer overrides it.
+# A deployment that wants a different provider overrides searchProvider in its
+# own cordis.patch.yml (applied after bundle layers).
+- insert:
+    - id: tinyfish-websearch
+      name: dsh-tinyfish-websearch
+      config:
+        maxResults: 5
+
+- id: web
+  config:
+    searchProvider: tinyfish

package/index.js

@@ -0,0 +1,224 @@
+/**
+ * dsh-tinyfish-websearch — host half.
+ *
+ * Registers a TinyFish-backed WebSearchProvider into the `ctx.web` seam, the
+ * same seam the shipped `web-search-perplexity` / `web-search-deepseek`
+ * providers and the `dsh-tavily-websearch` plugin use. The browser tool
+ * (`dsh-tool-web`) keeps working unchanged: the active provider is pinned by
+ * the `web` row's `searchProvider` config, which the profile patch sets to
+ * `tinyfish`.
+ *
+ * Zero runtime imports and no build step: the provider implements the seam's
+ * contract structurally (id / available() / search(request, signal)) and
+ * errors are plain `Error`s carrying a `code` property (`WEB_PROVIDER_ERROR`
+ * / `WEB_ABORTED` / `WEB_PROVIDER_CREDENTIAL_MISSING`). Thrown messages still
+ * surface to the model; the `HarnessError`-typed structured metadata the
+ * shipped providers emit is the only thing not reproduced. This keeps the
+ * package fully portable — it resolves from any install location without
+ * depending on the profile module fallback.
+ *
+ * The API key resolves lazily per search through the credentials seam
+ * (`ctx.credentials`), which reads process env → `$DSH_HOME/.credentials.yaml`
+ * → `.env`. The browser half (./client.js) provides a Settings → 「TinyFish 搜索」
+ * form that writes the key through `credentials.set`, so a key saved in the
+ * GUI is picked up by the next search without a restart.
+ *
+ * Wire format (https://docs.tinyfish.ai/search-api/reference): one GET on the
+ * base URL with `query` as a query parameter, `X-API-Key` bearer-style header
+ * auth. Search requests consume no credits (free tier: 30 req/min).
+ */
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'dsh-tinyfish-websearch'
+
+/** The web seam and the credentials seam this plugin reads. */
+export const inject = ['web', 'credentials']
+
+/** Stable provider id; the `web` row's `searchProvider` must name it. */
+export const TINYFISH_PROVIDER_ID = 'tinyfish'
+
+/** Default TinyFish Search endpoint; the operation is a GET on the root. */
+export const TINYFISH_DEFAULT_BASE_URL = 'https://api.search.tinyfish.ai'
+
+/** Default result count; the seam truncates to the request's bound regardless. */
+export const TINYFISH_DEFAULT_MAX_RESULTS = 5
+
+/** Attribution header sent on every request. */
+const USER_AGENT = 'dsh-tinyfish-websearch/0.1.0'
+
+/** Config defaults; the row config overrides them wholesale. */
+const CONFIG_DEFAULTS = Object.freeze({
+  baseURL: TINYFISH_DEFAULT_BASE_URL,
+  maxResults: TINYFISH_DEFAULT_MAX_RESULTS,
+})
+
+/**
+ * Validate and normalize the row config. Unknown shapes fail loud at load
+ * (never a silent skip).
+ * @param raw - the cordis.yml `config` for this row.
+ * @returns the normalized config.
+ */
+export function resolveConfig(raw) {
+  const cfg = { ...CONFIG_DEFAULTS, ...(raw ?? {}) }
+  if (cfg.apiKey !== undefined && typeof cfg.apiKey !== 'string') {
+    throw new Error('tinyfish-websearch: config.apiKey must be a string')
+  }
+  if (typeof cfg.baseURL !== 'string' || cfg.baseURL.length === 0 || !URL.canParse(cfg.baseURL)) {
+    throw new Error(`tinyfish-websearch: config.baseURL must be a valid URL, got "${String(cfg.baseURL)}"`)
+  }
+  if (!Number.isInteger(cfg.maxResults) || cfg.maxResults < 1 || cfg.maxResults > 20) {
+    throw new Error('tinyfish-websearch: config.maxResults must be an integer in 1..20')
+  }
+  return cfg
+}
+
+/**
+ * Map a TinyFish search response to the seam's normalized result shape.
+ * TinyFish returns no generated answer, so `content` is always omitted; each
+ * `results[]` entry becomes a citeable source (URL always, title/snippet/date
+ * when present).
+ *
+ * @param payload - the parsed TinyFish response body.
+ * @returns the normalized result.
+ */
+export function mapTinyFishResponse(payload) {
+  const results = Array.isArray(payload?.results) ? payload.results : []
+  const sources = []
+  for (const item of results) {
+    if (item === null || typeof item !== 'object') continue
+    const url = typeof item.url === 'string' ? item.url : ''
+    if (url.length === 0) continue
+    const source = { url }
+    if (typeof item.title === 'string' && item.title.length > 0) source.title = item.title
+    if (typeof item.snippet === 'string' && item.snippet.length > 0) source.snippet = item.snippet
+    if (typeof item.date === 'string' && item.date.length > 0) source.publishedAt = item.date
+    sources.push(source)
+  }
+  return {
+    sources,
+    truncated: false,
+  }
+}
+
+/** Build a plain provider error carrying the seam's machine-routable code. */
+function webError(message, code, cause) {
+  const error = new Error(message)
+  error.code = code
+  if (cause !== undefined) error.cause = cause
+  return error
+}
+
+/** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */
+function isAbortError(error) {
+  return error instanceof DOMException && error.name === 'AbortError'
+}
+
+/** The TinyFish-backed search provider; HTTP redirects fail as `WEB_PROVIDER_ERROR`. */
+export class TinyFishSearchProvider {
+  id = TINYFISH_PROVIDER_ID
+
+  constructor(options) {
+    this.options = options
+  }
+
+  /** Cheap local usability check; must not make network calls. */
+  available() {
+    const { apiKey, resolveApiKey, baseURL, maxResults } = this.options
+    const hasKey = (typeof apiKey === 'string' && apiKey.length > 0)
+      || typeof resolveApiKey === 'function'
+    return hasKey
+      && URL.canParse(baseURL)
+      && Number.isInteger(maxResults) && maxResults > 0
+  }
+
+  /**
+   * Resolve one operation's key: a literal row config wins, then the
+   * credentials seam (env → $DSH_HOME/.credentials.yaml → .env). Resolved per
+   * search so a key saved in the Settings GUI takes effect without a restart.
+   * @returns the resolved key.
+   * @throws the missing-credential error when no layer supplies one.
+   */
+  async #resolveApiKey() {
+    const literal = this.options.apiKey
+    if (typeof literal === 'string' && literal.length > 0) return literal
+    if (typeof this.options.resolveApiKey === 'function') {
+      const resolved = await this.options.resolveApiKey()
+      if (typeof resolved === 'string' && resolved.length > 0) return resolved
+    }
+    throw webError(
+      'TinyFish search has no API key; set it in Settings → TinyFish 搜索 or export TINYFISH_API_KEY',
+      'WEB_PROVIDER_CREDENTIAL_MISSING',
+    )
+  }
+
+  /** Run one TinyFish search; honor `signal` for cancellation. */
+  async search(request, signal) {
+    const apiKey = await this.#resolveApiKey()
+    const url = new URL(this.options.baseURL)
+    url.searchParams.set('query', request.query)
+    let response
+    try {
+      response = await fetch(url, {
+        method: 'GET',
+        redirect: 'error',
+        headers: {
+          'x-api-key': apiKey,
+          'accept': 'application/json',
+          'user-agent': USER_AGENT,
+        },
+        ...(signal !== undefined ? { signal } : {}),
+      })
+    } catch (error) {
+      if (isAbortError(error)) {
+        throw webError('TinyFish search aborted', 'WEB_ABORTED', error)
+      }
+      throw webError(`TinyFish search request failed: ${String(error)}`, 'WEB_PROVIDER_ERROR', error)
+    }
+
+    if (!response.ok) {
+      const status = response.status
+      let message = `TinyFish API error (HTTP ${status})`
+      try {
+        const parsed = await response.json()
+        const detail = parsed?.detail?.error ?? parsed?.error?.message ?? parsed?.detail ?? parsed?.message
+        if (typeof detail === 'string' && detail.length > 0) message = detail
+      } catch (error) {
+        // An abort fired mid-body must surface as WEB_ABORTED, not be swallowed
+        // into a generic HTTP-error message — cancellation is not a provider
+        // error (the seam's cancellation contract).
+        if (isAbortError(error)) {
+          throw webError('TinyFish search aborted', 'WEB_ABORTED', error)
+        }
+        // Otherwise: the HTTP status is already captured in `message` above; a
+        // malformed/non-JSON error body can only cost a richer message.
+      }
+      throw webError(message, 'WEB_PROVIDER_ERROR')
+    }
+
+    try {
+      const payload = await response.json()
+      return mapTinyFishResponse(payload)
+    } catch (error) {
+      if (isAbortError(error)) {
+        throw webError('TinyFish search aborted', 'WEB_ABORTED', error)
+      }
+      throw webError(`TinyFish returned an unprocessable response body: ${String(error)}`, 'WEB_PROVIDER_ERROR', error)
+    }
+  }
+}
+
+/**
+ * Plugin body: register the TinyFish provider with `ctx.web`.
+ * @param ctx - cordis context with the injected `web` and `credentials` services.
+ * @param rawConfig - the cordis.yml row config.
+ */
+export function apply(ctx, rawConfig) {
+  const config = resolveConfig(rawConfig)
+  ctx.web.registerSearchProvider(new TinyFishSearchProvider({
+    // Literal row config wins; otherwise the credentials seam resolves
+    // `TINYFISH_API_KEY` (env → .credentials.yaml → .env) per search.
+    apiKey: config.apiKey ?? '',
+    resolveApiKey: () => ctx.credentials.resolve('TINYFISH_API_KEY').then((cred) => cred?.value),
+    baseURL: config.baseURL,
+    maxResults: config.maxResults,
+  }))
+}

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "dsh-tinyfish-websearch",
+  "version": "0.1.0",
+  "description": "dsh bundle plugin: replaces the default web_search provider with TinyFish (ctx.web seam), with a Settings → TinyFish 搜索 key form",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "INSTALL.md"
+  ],
+  "exports": {
+    ".": "./index.js",
+    "./client": "./client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lijq3370/dsh-tinyfish-websearch.git"
+  },
+  "homepage": "https://github.com/lijq3370/dsh-tinyfish-websearch",
+  "bugs": {
+    "url": "https://github.com/lijq3370/dsh-tinyfish-websearch/issues"
+  },
+  "author": {
+    "name": "lijq3370",
+    "url": "https://github.com/lijq3370"
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "web-search",
+    "tinyfish",
+    "search"
+  ],
+  "license": "MIT",
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-api-remotes",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-ui-settings",
+        "@deepseek-ai/dsh-client-locale"
+      ],
+      "platform": "web"
+    }
+  }
+}