dsh-free-search 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-free-search contributors
+
+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.en.md

@@ -0,0 +1,139 @@
+# dsh-free-search
+
+**Free web search provider for DeepSeek Harness — no API key required, multi-engine, zero cost.**
+
+A plugin that adds multi-engine search providers to DeepSeek Harness (dsh), registered into the `ctx.web` seam. The built-in `web_search` tool picks it up automatically. Includes a web settings page for engine switching and API key configuration, plus an engine test tool.
+
+[中文](./README.md) | English
+
+## Why
+
+dsh ships a DeepSeek-official search provider by default, which requires a valid `DEEPSEEK_API_KEY`. If you:
+- don't have (or don't want) a DeepSeek official API key,
+- already use a gateway like opencode-go (which does not expose a `web_search` tool),
+
+...then the built-in search always fails and the agent tells you "I can't access the internet."
+
+This plugin provides multiple free engines with automatic failover, fully independent of the DeepSeek official key.
+
+## Features
+
+- **Zero cost** — multiple free engines, no key, no registration
+- **Multi-engine**: DuckDuckGo (html/lite), Bing, SearXNG (meta-search, custom instances), Exa, Perplexity, DeepSeek Official
+- **Web settings UI** — engine switching + API key configuration (keys are redacted in the UI, shown as "configured")
+- **Engine test tool** — `free_search_test`, lets the agent verify every engine in one call
+- **Auto-failover** — free engines fall back to the next available one on failure/rate-limit
+- **System prompt injection** — the agent knows the current engine and which need keys
+- **FREE / API KEY badges** — green FREE badge for free engines, orange API KEY badge for paid ones
+- **Clean integration** — implements the official `WebSearchProvider` seam, coexists with official plugins
+- **web_fetch** — agent can fetch page content (official `dsh-web-fetch-http` provider, pure JS, zero extra deps)
+
+## Engines
+
+| id | Engine | Cost | Notes |
+|---|---|---|---|
+| `ddg` | DuckDuckGo HTML | Free | Occasionally rate-limited (anti-bot), recovers automatically |
+| `ddg-lite` | DuckDuckGo Lite | Free | Lightweight variant, same caveat |
+| `bing` | Bing | Free | **Default engine**, most stable, zh-CN optimized |
+| `searxng` | SearXNG meta-search | Free | Multi-instance failover, custom instances supported |
+| `exa` | Exa | Paid | Requires `EXA_API_KEY` |
+| `perplexity` | Perplexity | Paid | Requires `PERPLEXITY_API_KEY` |
+| `deepseek-official` | DeepSeek Official | Paid | Requires `DEEPSEEK_API_KEY` |
+
+Free engines auto-fallback to another free engine on failure. Paid engines fail with a clear error when their key is missing or invalid — never a silent switch.
+
+- **Default engine is `bing`** (free and most stable), works out of the box after install.
+- **Settings page has official links**: free engines show "访问官网 →", paid engines show "获取 API Key →" (opens in a new tab):
+  - Exa: <https://dashboard.exa.ai/api-keys>
+  - Perplexity: <https://www.perplexity.ai/settings/api>
+  - DeepSeek: <https://platform.deepseek.com/api_keys>
+
+## Install
+
+```sh
+git clone https://github.com/DDDMUC/dsh-free-search.git
+dsh plugin --profile web add /path/to/dsh-free-search
+```
+
+Then restart:
+
+```sh
+dsh web
+```
+
+## Usage
+
+### Web settings (recommended)
+
+After install, open **Settings → Plugins → Configurable** tab → **Free Search** card (official settings page, no dsh-web-ui needed):
+
+- **Search engine**: dropdown to switch engines, save to apply
+- **API keys**: fill keys for Exa / Perplexity / DeepSeek (password inputs; after save the UI only shows "configured")
+
+### Config file
+
+Configuration lives in `~/.dsh/settings.yaml`:
+
+```yaml
+free-search:
+  provider: bing              # ddg / ddg-lite / bing / searxng / exa / perplexity / deepseek-official
+  bingMarket: zh-CN           # Bing market
+  region: cn-zh               # DuckDuckGo region (optional)
+  searxngInstances:           # custom SearXNG instances (optional)
+    - https://your-instance.example
+  exaApiKey: ...              # or configure via the settings page
+  perplexityApiKey: ...
+  deepseekApiKey: ...
+```
+
+### Have the agent test all engines
+
+Ask the agent to "test all search engines" — it calls the `free_search_test` tool and reports:
+
+```
+Search engine test:
+- ddg: FAIL - DuckDuckGo is rate-limited right now (anti-bot challenge, usually temporary) - Bing works
+- bing: OK (2 results, e.g. "DeepSeek Harness developer preview...")
+- exa: FAIL - EXA_API_KEY not configured
+```
+
+### Fetch page content (web_fetch)
+
+After search, ask the agent to **read a page** (e.g. "open the first link and summarize it"). The `web_fetch` tool is enabled (official `dsh-web-fetch-http` provider):
+
+- Follows redirects, decodes body (HTML to text)
+- Timeout and size limits
+- ⚠️ Note: `web_fetch` has no SSRF protection — the agent could reach internal addresses. Use deliberately.
+
+## Local engine switcher (tools/)
+
+Prefer a local tool over the web UI? The `tools/` directory ships a zero-dependency switcher:
+
+- **`启动搜索引擎切换器.cmd`** (Windows) — double-click to start a local Node server (`http://127.0.0.1:4789`) and open the picker page in your browser
+- **`switch-engine.html`** — the picker UI: shows the current engine, one-click switch
+- **`server.mjs`** — local server that reads/writes `~/.dsh/profiles/web/cordis.patch.yml`
+- **`switch-engine.ps1`** — headless CLI: `powershell -File tools/switch-engine.ps1 -Engine bing`
+
+Restart `dsh web` after switching.
+
+> The settings card mounts on the official `settings.plugin.item` slot (built into dsh); config reads/writes go through the plugin's own bridge. **No dsh-web-ui dependency — the plugin works standalone.**
+
+## Proxy note
+
+DuckDuckGo and some engines may be blocked and need a proxy. Node.js `fetch` does not use the system proxy by default — set these environment variables for the dsh process (Node 24+):
+
+```sh
+export NODE_USE_ENV_PROXY=1
+export HTTPS_PROXY=http://127.0.0.1:7897   # your proxy
+export HTTP_PROXY=http://127.0.0.1:7897
+```
+
+## How it works
+
+- `lib/index.js`: host side. Implements `WebSearchProvider` (`id` / `available()` / `search()`), multi-engine routing + auto-failover; registers the `free-search` settings namespace; serves the `/api/dsh-free-search-settings` read/write bridge; registers the `free_search_test` tool; injects the engine list into the system prompt.
+- `lib/client.js`: browser side. React settings card (engine select + key inputs), mounted on the official `settings.plugin.item` slot (Settings → Plugins → Configurable), no dsh-web-ui dependency.
+- `cordis.patch.yml`: plugin loader config.
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,140 @@
+# dsh-free-search
+
+**DeepSeek Harness 免费搜索插件 —— 无需 API key，零成本，多引擎可切换。**
+
+一个给 DeepSeek Harness (dsh) 添加多引擎搜索 provider 的插件，注册进 `ctx.web` seam。内置 `web_search` 工具自动选用，支持网页设置页切换引擎、配置 API key、一键测试所有引擎。
+
+[English](./README.en.md) | 中文
+
+## 为什么需要它
+
+dsh 默认的搜索 provider 依赖 DeepSeek 官方 API key（`DEEPSEEK_API_KEY`）。如果你：
+- 没有（或不想用）DeepSeek 官方 key，
+- 用的是 opencode-go 这类网关（其 OpenAI 兼容端点不支持 `web_search` 工具），
+
+……那么内置搜索必然失败，agent 会告诉你"无法联网"。
+
+这个插件提供多个免费引擎 + 自动回退，彻底摆脱 DeepSeek 官方 key 的依赖。
+
+## 特性
+
+- **零成本** —— 多个免费引擎，无需 key、无需注册
+- **多引擎可选**：DuckDuckGo（html/lite）、Bing、SearXNG（元搜索，支持自定义实例）、Exa、Perplexity、DeepSeek 官方
+- **网页设置页** —— 引擎切换 + API key 配置（UI 中 key 脱敏显示"已配置"）
+- **引擎测试工具** —— `free_search_test`，让 agent 一键测试所有引擎可用性
+- **自动回退** —— 免费引擎失败/限流时自动切换到下一个可用引擎
+- **系统提示词注入** —— agent 知道当前用哪个引擎、哪些需要 key
+- **免费标注** —— 设置页中免费引擎带绿色 `FREE` 徽章，付费引擎带橙色 `API KEY` 徽章
+- **网页抓取（web_fetch）** —— 让 agent 抓取网页内容（官方 `dsh-web-fetch-http` provider，纯 JS，零额外依赖）
+- **干净集成** —— 实现官方 `WebSearchProvider` seam 接口，与官方插件共存
+
+## 引擎列表
+
+| id | 引擎 | 费用 | 说明 |
+|---|---|---|---|
+| `ddg` | DuckDuckGo HTML | 免费 | 偶发限流（反爬），解封自动恢复 |
+| `ddg-lite` | DuckDuckGo Lite | 免费 | 轻量版，同上 |
+| `bing` | Bing | 免费 | **默认引擎**，最稳定，中文优化（zh-CN） |
+| `searxng` | SearXNG 元搜索 | 免费 | 多实例自动切换，支持自定义实例 |
+| `exa` | Exa | 付费 | 需 `EXA_API_KEY` |
+| `perplexity` | Perplexity | 付费 | 需 `PERPLEXITY_API_KEY` |
+| `deepseek-official` | DeepSeek 官方 | 付费 | 需 `DEEPSEEK_API_KEY` |
+
+- **默认引擎为 `bing`**（免费且最稳定），安装后开箱即用。
+- 免费引擎失败会自动回退到其他免费引擎；付费引擎缺 key 或 key 无效时报清晰错误，不会静默切换。
+- **设置页有官网链接**：免费引擎显示"访问官网 →"，付费引擎显示"获取 API Key →"（新标签页打开）：
+  - Exa：<https://dashboard.exa.ai/api-keys>
+  - Perplexity：<https://www.perplexity.ai/settings/api>
+  - DeepSeek：<https://platform.deepseek.com/api_keys>
+
+## 安装
+
+```sh
+git clone https://github.com/DDDMUC/dsh-free-search.git
+dsh plugin --profile web add /path/to/dsh-free-search
+```
+
+然后重启：
+
+```sh
+dsh web
+```
+
+## 使用
+
+### 网页设置（推荐）
+
+安装后，打开 **设置 → 插件 → 可配置** 标签页 → **Free Search** 卡片（官方设置页，无需 dsh-web-ui）：
+
+- **Search engine**：下拉框切换引擎，保存即生效
+- **API keys**：为 Exa / Perplexity / DeepSeek 填写 key（密码框，保存后只显示"已配置"）
+
+### 命令行 / 配置文件
+
+配置存在 `~/.dsh/settings.yaml`：
+
+```yaml
+free-search:
+  provider: bing              # ddg / ddg-lite / bing / searxng / exa / perplexity / deepseek-official
+  bingMarket: zh-CN           # Bing 市场
+  region: cn-zh               # DuckDuckGo 区域（可选）
+  searxngInstances:           # 自定义 SearXNG 实例（可选）
+    - https://your-instance.example
+  exaApiKey: ...              # 或通过设置页填写
+  perplexityApiKey: ...
+  deepseekApiKey: ...
+```
+
+### 让 agent 测试所有引擎
+
+对 agent 说"测试一下所有搜索引擎"，它会调用 `free_search_test` 工具，逐个测试并报告：
+
+```
+Search engine test:
+- ddg: FAIL - DuckDuckGo is rate-limited right now (anti-bot challenge, usually temporary) - Bing works
+- bing: OK (2 results, e.g. "DeepSeek Harness developer preview...")
+- exa: FAIL - EXA_API_KEY not configured
+```
+
+### 抓取网页内容（web_fetch）
+
+搜索到 URL 后，可以让 agent **读取网页全文**（如"打开第一个链接看看内容"）。`web_fetch` 工具已启用（官方 `dsh-web-fetch-http` provider）：
+
+- 自动跟随重定向、解码正文（HTML 转文本）
+- 支持超时和大小限制
+- ⚠️ 注意：`web_fetch` 无 SSRF 防护，agent 理论上可访问内网地址——按需使用
+
+## 本地引擎切换工具（tools/）
+
+不想用网页设置页？`tools/` 目录附带了一个本地切换小工具（零依赖）：
+
+- **`启动搜索引擎切换器.cmd`**（Windows）——双击启动本地 Node 服务（`http://127.0.0.1:4789`）并自动打开浏览器选择页面
+- **`switch-engine.html`** —— 选择页面：显示当前引擎，点选新引擎，一键写入配置
+- **`server.mjs`** —— 本地服务，负责读写 `~/.dsh/profiles/web/cordis.patch.yml`
+- **`switch-engine.ps1`** —— 无界面命令行版：`powershell -File tools/switch-engine.ps1 -Engine bing`
+
+切换后重启 `dsh web` 生效。
+
+> 配置卡片挂在官方设置页的 `settings.plugin.item` 插槽（dsh 自带），配置读写走插件自建 bridge，**不依赖 dsh-web-ui**，插件可独立使用。
+
+## 代理说明（国内用户）
+
+DuckDuckGo 等引擎可能需要代理才能访问，而 Node.js 的 `fetch` 默认不走系统代理。需要给 dsh 进程设置（Node 24+）：
+
+```sh
+export NODE_USE_ENV_PROXY=1
+export HTTPS_PROXY=http://127.0.0.1:7897   # 你的代理地址
+export HTTP_PROXY=http://127.0.0.1:7897
+```
+
+Windows 用户：桌面快捷方式已内置此配置（`set NODE_USE_ENV_PROXY=1&& set HTTPS_PROXY=...`）。
+
+## 工作原理
+
+- `lib/index.js`：host 端。实现 `WebSearchProvider`（`id` / `available()` / `search()`），多引擎路由 + 自动回退；注册 `free-search` settings namespace；提供 `/api/dsh-free-search-settings` 读写桥；注册 `free_search_test` 工具；注入引擎清单到系统提示词。
+- `lib/client.js`：浏览器端。React 配置卡片（引擎选择 + key 输入），挂载到官方设置页的 `settings.plugin.item` 插槽（设置 → 插件 → 可配置），不依赖 dsh-web-ui。
+- `cordis.patch.yml`：插件 loader 配置。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,17 @@
+# dsh-free-search — free web search providers (no API key needed)
+# Registers the free-search plugin into ctx.web + a settings bridge
+# (/api/dsh-free-search-settings) that serves the "free-search" namespace.
+# The engine (ddg / ddg-lite / bing) is chosen from the web Settings page
+# (Settings > Plugins > Web UI plugins > Free Search) or settings.yaml:
+#   free-search:
+#     provider: bing
+#     region: cn-zh        # DuckDuckGo region
+#     bingMarket: zh-CN    # Bing market
+# Failed/empty engines automatically fall back to the next free engine.
+# web.searchProvider must point at this plugin's provider id (ddg).
+- insert:
+    - id: web-search-free
+      name: dsh-free-search
+      config:
+        provider: bing
+        bingMarket: zh-CN

package/lib/client.js

@@ -0,0 +1,348 @@
+window.__ModuleLoader__.load({
+  id: "dsh-free-search",
+  factory: (require) => {
+    var module = { exports: {} };
+    var exports = module.exports;
+
+    let react = require("react");
+    let react_jsx_runtime = require("react/jsx-runtime");
+
+    //#region css
+    const css = [
+      ".dshfs-card{border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-3);border-radius:8px;min-width:0;list-style:none;transition:border-color .16s,background .16s;overflow:hidden;margin-bottom:8px}",
+      ".dshfs-cardOpen{background:var(--dsw-alias-bg-layer-2);border-color:var(--dsw-alias-label-dimmed)}",
+      ".dshfs-header{width:100%;color:inherit;cursor:pointer;text-align:left;font:inherit;background:0 0;border:0;align-items:center;gap:8px;padding:10px 14px;display:flex}",
+      ".dshfs-header:hover:not(:disabled){background:var(--dsw-alias-interactive-bg-hover)}",
+      ".dshfs-headText{flex-direction:column;flex:1;gap:2px;min-width:0;display:flex;overflow:hidden}",
+      ".dshfs-name{color:var(--dsw-alias-label-primary);white-space:nowrap;text-overflow:ellipsis;font-weight:600;overflow:hidden}",
+      ".dshfs-description{color:var(--dsw-alias-label-tertiary);white-space:nowrap;text-overflow:ellipsis;font-size:12px;overflow:hidden}",
+      ".dshfs-pending{color:var(--dsw-alias-state-warn-primary);white-space:nowrap;flex:none;font-size:12px}",
+      ".dshfs-chevron{color:var(--dsw-alias-label-tertiary);flex:none;font-size:13px;transition:transform .12s}",
+      ".dshfs-chevronOpen{transform:rotate(180deg)}",
+      ".dshfs-body{flex-direction:column;gap:14px;padding:0 14px 14px;display:flex}",
+      ".dshfs-footer{justify-content:flex-end;align-items:center;gap:8px;display:flex}",
+      ".dshfs-failed{color:var(--dsw-alias-state-error-primary);margin:0 auto 0 0;font-size:12px}",
+      ".dshfs-field{flex-direction:column;gap:4px;min-width:0;display:flex}",
+      ".dshfs-label{color:var(--dsw-alias-label-primary);font-size:13px;font-weight:500}",
+      ".dshfs-select{border:1px solid var(--dsw-alias-border-l2);font:inherit;font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-primary);background:var(--dsw-specific-input-major);border-radius:6px;padding:6px 8px;font-size:13px;transition:border-color .13s,box-shadow .13s;width:100%}",
+      ".dshfs-select:hover:not(:disabled){border-color:var(--dsw-alias-label-dimmed)}",
+      ".dshfs-input{border:1px solid var(--dsw-alias-border-l2);font:inherit;font-variant-numeric:tabular-nums;color:var(--dsw-alias-label-primary);background:var(--dsw-specific-input-major);border-radius:6px;padding:6px 8px;font-size:13px;transition:border-color .13s,box-shadow .13s;width:100%}",
+      ".dshfs-input:hover:not(:disabled){border-color:var(--dsw-alias-label-dimmed)}",
+      ".dshfs-input:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:1px}",
+      ".dshfs-input:disabled{opacity:.6;cursor:default}",
+      ".dshfs-hint{color:var(--dsw-alias-label-secondary);margin:0;font-size:12px}",
+      ".dshfs-link{color:var(--dsw-alias-state-business-primary);font-size:12px;text-decoration:none;align-self:flex-start;padding:2px 0}",
+      ".dshfs-link:hover{text-decoration:underline}",
+      ".dshfs-btn{font:inherit;cursor:pointer;border-radius:6px;padding:5px 12px;font-size:13px;transition:background-color .13s,border-color .13s,color .13s}",
+      ".dshfs-save{border:1px solid var(--dsw-alias-button-info-fill);background:var(--dsw-alias-button-info-fill);color:var(--dsw-alias-label-primary-foreground)}",
+      ".dshfs-save:hover:not(:disabled){border-color:var(--dsw-alias-button-info-hover);background:var(--dsw-alias-button-info-hover)}",
+      ".dshfs-save:disabled{opacity:.5;cursor:default}",
+      ".dshfs-badge{background:var(--dsw-alias-interactive-bg-hover-accent);color:var(--dsw-alias-state-business-primary);white-space:nowrap;border-radius:999px;flex:none;padding:1px 6px;font-size:11px}",
+      ".dshfs-badgeFree{background:rgba(80,200,120,.15);color:#7ddb9c;border:1px solid rgba(80,200,120,.3);white-space:nowrap;border-radius:999px;flex:none;padding:1px 6px;font-size:11px}",
+      ".dshfs-badgeKey{background:rgba(240,170,80,.15);color:#f0b060;border:1px solid rgba(240,170,80,.3);white-space:nowrap;border-radius:999px;flex:none;padding:1px 6px;font-size:11px}",
+    ].join("");
+    const tagId = "dsh-free-search/card.css";
+    if (typeof document !== "undefined" && document.querySelector("style[data-plugin-css=" + JSON.stringify(tagId) + "]") === null) {
+      const tag = document.createElement("style");
+      tag.dataset.plugin = "dsh-free-search";
+      tag.dataset.pluginCss = tagId;
+      tag.textContent = css;
+      document.head.appendChild(tag);
+    }
+    //#endregion
+
+    const BRIDGE_PREFIX = "/api/dsh-free-search-settings";
+    const NS = "free-search";
+    const ENGINES = [
+      { id: "ddg", label: "DuckDuckGo · HTML", badge: "FREE", link: "https://duckduckgo.com" },
+      { id: "ddg-lite", label: "DuckDuckGo · Lite", badge: "FREE", link: "https://duckduckgo.com" },
+      { id: "bing", label: "Bing", badge: "FREE", link: "https://www.bing.com" },
+      { id: "searxng", label: "SearXNG · 元搜索", badge: "FREE", link: "https://github.com/searxng/searxng" },
+      { id: "exa", label: "Exa", badge: "API KEY", link: "https://dashboard.exa.ai/api-keys" },
+      { id: "perplexity", label: "Perplexity", badge: "API KEY", link: "https://www.perplexity.ai/settings/api" },
+      { id: "deepseek-official", label: "DeepSeek Official", badge: "API KEY", link: "https://platform.deepseek.com/api_keys" },
+    ];
+
+    async function bridgeDescribe() {
+      const response = await fetch(`${BRIDGE_PREFIX}/describe`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      });
+      return response.json();
+    }
+
+    async function bridgeMutate(payload) {
+      const response = await fetch(`${BRIDGE_PREFIX}/mutate`, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(payload),
+      });
+      return response.json();
+    }
+
+    function FreeSearchCard(props) {
+      const [open, setOpen] = react.useState(false);
+      const [state, setState] = react.useState({ status: "loading" });
+      const [provider, setProvider] = react.useState("bing");
+      const [exaKey, setExaKey] = react.useState("");
+      const [perplexityKey, setPerplexityKey] = react.useState("");
+      const [deepseekKey, setDeepseekKey] = react.useState("");
+      const [keysConfigured, setKeysConfigured] = react.useState({});
+      const [dirty, setDirty] = react.useState(false);
+      const [saving, setSaving] = react.useState(false);
+      const [failed, setFailed] = react.useState(false);
+
+      const load = react.useCallback(async () => {
+        try {
+          const result = await bridgeDescribe();
+          if (result.ok) {
+            const view = result.value.namespaces.find((n) => n.ns === NS);
+            if (view) {
+              const v = view.value ?? {};
+              setProvider(v.provider ?? "ddg");
+              setExaKey(v.exaApiKey ?? "");
+              setPerplexityKey(v.perplexityApiKey ?? "");
+              setDeepseekKey(v.deepseekApiKey ?? "");
+              // secrets 字段标记哪些 key 已配置（值被脱敏，仅显示"已配置"）
+              const configured = {};
+              for (const secret of view.secrets ?? []) {
+                if (secret.set) {
+                  const path = secret.path.join(".");
+                  if (path === "exaApiKey") configured.exa = true;
+                  if (path === "perplexityApiKey") configured.perplexity = true;
+                  if (path === "deepseekApiKey") configured.deepseek = true;
+                }
+              }
+              setKeysConfigured(configured);
+              setState({ status: "ready", writable: result.value.writable });
+            } else {
+              setState({ status: "unavailable" });
+            }
+          } else {
+            setState({ status: "unavailable" });
+          }
+        } catch {
+          setState({ status: "unavailable" });
+        }
+      }, []);
+
+      react.useEffect(() => {
+        load();
+      }, [load]);
+
+      const select = (value) => {
+        setProvider(value);
+        setDirty(true);
+        setFailed(false);
+      };
+
+      const save = async () => {
+        setSaving(true);
+        setFailed(false);
+        try {
+          const ops = [{ op: "set", path: ["provider"], value: provider }];
+          if (exaKey.trim()) ops.push({ op: "set", path: ["exaApiKey"], value: exaKey.trim() });
+          if (perplexityKey.trim()) ops.push({ op: "set", path: ["perplexityApiKey"], value: perplexityKey.trim() });
+          if (deepseekKey.trim()) ops.push({ op: "set", path: ["deepseekApiKey"], value: deepseekKey.trim() });
+          const result = await bridgeMutate({ ns: NS, ops });
+          if (result.ok) {
+            setDirty(false);
+            setProvider(result.value.value.provider ?? provider);
+            setFailed(false);
+            load();
+          } else {
+            setFailed(true);
+          }
+        } catch {
+          setFailed(true);
+        } finally {
+          setSaving(false);
+        }
+      };
+
+      const discard = () => {
+        load();
+        setDirty(false);
+        setFailed(false);
+      };
+
+      if (state.status === "loading") return null;
+      const ready = state.status === "ready";
+      const title = "Free Search";
+      const description = "Free web search — no API key needed (DuckDuckGo / Bing)";
+      const currentEngine = ENGINES.find((e) => e.id === provider) ?? ENGINES[0];
+      const badgeClass =
+        currentEngine.badge === "FREE" ? "dshfs-badge dshfs-badgeFree" : "dshfs-badge dshfs-badgeKey";
+
+      return react_jsx_runtime.jsx("li", {
+        className: open ? "dshfs-card dshfs-cardOpen" : "dshfs-card",
+        children: [
+          react_jsx_runtime.jsx("button", {
+            type: "button",
+            className: "dshfs-header",
+            "aria-expanded": open,
+            onClick: () => setOpen(!open),
+            children: [
+              react_jsx_runtime.jsx("span", {
+                className: "dshfs-headText",
+                children: [
+                  react_jsx_runtime.jsx("span", { className: "dshfs-name", children: title }),
+                  react_jsx_runtime.jsx("span", { className: "dshfs-description", children: description }),
+                ],
+              }),
+                          react_jsx_runtime.jsx("span", { className: badgeClass, children: currentEngine.badge }),
+              dirty ? react_jsx_runtime.jsx("span", { className: "dshfs-pending", children: "unsaved" }) : null,
+              react_jsx_runtime.jsx("span", {
+                className: open ? "dshfs-chevron dshfs-chevronOpen" : "dshfs-chevron",
+                children: "▾",
+              }),
+            ],
+          }),
+          open
+            ? react_jsx_runtime.jsx("div", {
+                className: "dshfs-body",
+                children: [
+                  react_jsx_runtime.jsx("div", {
+                    className: "dshfs-field",
+                    children: [
+                      react_jsx_runtime.jsx("div", {
+                        className: "dshfs-label",
+                        children: [
+                          "Search engine",
+              react_jsx_runtime.jsx("span", { className: badgeClass, children: currentEngine.badge }),
+                        ],
+                      }),
+                      react_jsx_runtime.jsx("select", {
+                        className: "dshfs-select",
+                        value: provider,
+                        disabled: !ready || saving,
+                        onChange: (e) => select(e.target.value),
+                        children: ENGINES.map((engine) =>
+                          react_jsx_runtime.jsx("option", { value: engine.id, children: `${engine.label} (${engine.badge})` }, engine.id)
+                        ),
+                      }),
+                      currentEngine.link
+                        ? react_jsx_runtime.jsx("a", {
+                            className: "dshfs-link",
+                            href: currentEngine.link,
+                            target: "_blank",
+                            rel: "noopener noreferrer",
+                            children:
+                              currentEngine.badge === "FREE"
+                                ? "访问官网 →"
+                                : "获取 API Key →",
+                          })
+                        : null,
+                      react_jsx_runtime.jsx("p", {
+                        className: "dshfs-hint",
+                        children:
+                          "Bing is the most stable FREE engine. DuckDuckGo may rate-limit on shared IPs. API KEY engines need credentials below.",
+                      }),
+                    ],
+                  }),
+                  react_jsx_runtime.jsx("div", {
+                    className: "dshfs-field",
+                    children: [
+                      react_jsx_runtime.jsx("div", {
+                        className: "dshfs-label",
+                        children: "API keys (optional)",
+                      }),
+                      react_jsx_runtime.jsx("input", {
+                        className: "dshfs-input",
+                        type: "password",
+                        placeholder: keysConfigured.exa ? "Exa API key (configured)" : "Exa API key (sk-...)",
+                        value: exaKey,
+                        disabled: !ready || saving,
+                        onChange: (e) => {
+                          setExaKey(e.target.value);
+                          setDirty(true);
+                          setFailed(false);
+                        },
+                      }),
+                      react_jsx_runtime.jsx("input", {
+                        className: "dshfs-input",
+                        type: "password",
+                        placeholder: keysConfigured.perplexity ? "Perplexity API key (configured)" : "Perplexity API key (pplx-...)",
+                        value: perplexityKey,
+                        disabled: !ready || saving,
+                        onChange: (e) => {
+                          setPerplexityKey(e.target.value);
+                          setDirty(true);
+                          setFailed(false);
+                        },
+                      }),
+                      react_jsx_runtime.jsx("input", {
+                        className: "dshfs-input",
+                        type: "password",
+                        placeholder: keysConfigured.deepseek ? "DeepSeek API key (configured)" : "DeepSeek API key (sk-...)",
+                        value: deepseekKey,
+                        disabled: !ready || saving,
+                        onChange: (e) => {
+                          setDeepseekKey(e.target.value);
+                          setDirty(true);
+                          setFailed(false);
+                        },
+                      }),
+                      react_jsx_runtime.jsx("p", {
+                        className: "dshfs-hint",
+                        children: "Keys are stored in settings.yaml (redacted in the UI). Enter a key for an engine to use it.",
+                      }),
+                    ],
+                  }),
+                  !ready
+                    ? react_jsx_runtime.jsx("p", {
+                        className: "dshfs-hint",
+                        children: "Settings unavailable — the free-search bridge is not exposed.",
+                      })
+                    : null,
+                  react_jsx_runtime.jsx("div", {
+                    className: "dshfs-footer",
+                    children: [
+                      failed ? react_jsx_runtime.jsx("p", { className: "dshfs-failed", children: "save failed" }) : null,
+                      react_jsx_runtime.jsx("button", {
+                        className: "dshfs-btn",
+                        type: "button",
+                        onClick: discard,
+                        disabled: saving || !dirty,
+                        children: "Discard",
+                      }),
+                      react_jsx_runtime.jsx("button", {
+                        className: "dshfs-btn dshfs-save",
+                        type: "button",
+                        onClick: save,
+                        disabled: saving || !dirty || !ready,
+                        children: saving ? "Saving…" : "Save",
+                      }),
+                    ],
+                  }),
+                ],
+              })
+            : null,
+        ],
+      });
+    }
+
+    const inject = ["slots"];
+
+    function apply(ctx) {
+      // 挂官方插槽 settings.plugin.item（设置 → 插件 → 可配置标签页）。
+      // 不依赖 dsh-web-ui：配置读写走自建 bridge（/api/dsh-free-search-settings）。
+      ctx.slots.inject("settings.plugin.item", () =>
+        ctx.slots.register(
+          {
+            name: "settings.plugin.item",
+            id: "dsh-free-search",
+            order: 120,
+            inject: () => ({}),
+          },
+          FreeSearchCard
+        )
+      );
+    }
+
+    exports.apply = apply;
+    exports.inject = inject;
+    return module.exports;
+  },
+});