dsh-exa-web-search 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,62 @@
+# dsh-exa-web-search
+
+![Plugin icon](icon.png)
+
+[中文说明](README.md)
+
+[![npm](https://img.shields.io/npm/v/dsh-exa-web-search)](https://www.npmjs.com/package/dsh-exa-web-search)
+[![downloads](https://img.shields.io/npm/dm/dsh-exa-web-search)](https://www.npmjs.com/package/dsh-exa-web-search)
+[![Check](https://github.com/Windsland52/dsh-exa-web-search/actions/workflows/check.yml/badge.svg)](https://github.com/Windsland52/dsh-exa-web-search/actions/workflows/check.yml)
+
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22.19.0-339933?logo=node.js&logoColor=white)](package.json)
+[![dsh](https://img.shields.io/badge/dsh-0.2.x-4c6)](package.json)
+
+Wires Exa into DeepSeek Harness's built-in web search: keep using the `web_search` tool as usual, but the results now come from Exa. **No extra tools, no system-prompt changes.**
+
+## Two channels, switched automatically
+
+| Mode | When | Route |
+| --- | --- | --- |
+| `auto` (default) | a key is available (configured, or in an environment variable) | official Exa API |
+| `auto` | no key | keyless public channel |
+| `anonymous` | chosen manually | force the public channel; any key is ignored |
+| `keyed` | chosen manually | force the official API; unavailable without a key |
+
+The public channel (labelled "anonymous" in the UI) is a free shared service: at most 2 queries run at once, the rest queue and retry once, and heavy use may be rate-limited. Use a key on the official API when you need reliability.
+
+A rejected key (401) reports `INVALID_CREDENTIAL` instead of switching to the public channel.
+
+## Install
+
+**Desktop app**: open **Plugins** → **+ Add plugin** (top right) → enter the package name `dsh-exa-web-search` → install.
+
+**Command line**:
+
+```bash
+dsh plugin add dsh-exa-web-search
+```
+
+No settings to change afterwards: web search goes through Exa by default. Uninstalling restores everything and leaves no trace in your config. To switch to another search source, change it in your own settings.
+
+## Configuration (optional)
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `mode` | `auto` | `auto` / `anonymous` / `keyed`; behaviour in the table above |
+| `apiKey` | — | the key typed in directly; when empty, read from the variable named by `apiKeyEnv` |
+| `apiKeyEnv` | `EXA_API_KEY` | which environment variable holds the key |
+| `baseURL` | `https://api.exa.ai` | official API address (keyed channel) |
+| `mcpURL` | `https://mcp.exa.ai/mcp?tools=web_search_advanced_exa,web_search_exa` | public channel address (keyless) |
+| `searchType` | `auto` | Exa search type (keyed only): `auto` / `keyword` / `neural` / `lite` / `deep-lite` / `deep` / `deep-reasoning` |
+
+You normally don't edit config files by hand: open **Plugins**, find `dsh-exa-web-search`, and type the key into the **Exa API Key** card (masked, and never echoed back after saving). The card carries only the key; **open the plugin's row** for the rest — mode, endpoint addresses, and search type.
+
+## How it differs from the official Exa plugin
+
+The official Exa plugin only registers the search source; you still have to make it the default yourself.
+
+This plugin registers as the `exa` search source itself (replacing the official implementation), so it is the default on install, is undone on uninstall, and leaves your other config alone:
+
+- **Search even without a key**: with a key it uses the official API, without one the keyless public channel, and `auto` switches for you.
+- **Zero intrusion**: no new tools, no system-prompt changes; keep using `web_search` as usual.

package/README.md

@@ -1,3 +1,62 @@
-# Temporary Holding Version
+# dsh-exa-web-search
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+![插件图标](icon.png)
+
+[English](README.en.md)
+
+[![npm](https://img.shields.io/npm/v/dsh-exa-web-search)](https://www.npmjs.com/package/dsh-exa-web-search)
+[![downloads](https://img.shields.io/npm/dm/dsh-exa-web-search)](https://www.npmjs.com/package/dsh-exa-web-search)
+[![Check](https://github.com/Windsland52/dsh-exa-web-search/actions/workflows/check.yml/badge.svg)](https://github.com/Windsland52/dsh-exa-web-search/actions/workflows/check.yml)
+
+[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Node](https://img.shields.io/badge/node-%3E%3D22.19.0-339933?logo=node.js&logoColor=white)](package.json)
+[![dsh](https://img.shields.io/badge/dsh-0.2.x-4c6)](package.json)
+
+把 Exa 接入 DeepSeek Harness 的内置联网搜索：`web_search` 工具照常用，只是搜索结果改由 Exa 提供。**没有额外工具，不改系统提示词。**
+
+## 两个通道，自动切换
+
+| 模式 | 什么情况 | 走哪条路 |
+| --- | --- | --- |
+| `auto`（默认） | 有 Key（填在配置里，或环境变量里） | Exa 官方 API |
+| `auto` | 没有 Key | 免 Key 的公共通道 |
+| `anonymous` | 手动选择 | 强制公共通道，忽略 Key |
+| `keyed` | 手动选择 | 强制官方 API；没有 Key 时不可用 |
+
+公共通道（界面里显示为「匿名」）是免费的共享服务，同时只跑 2 个查询，超出的排队等待并重试一次；量大时可能被限流。要求稳定就用 Key 走官方 API。
+
+Key 被拒（401）时直接报 `INVALID_CREDENTIAL`，不会改用公共通道。
+
+## 安装
+
+**桌面版**：打开 **插件** 页 → 右上角 **+ 添加插件** → 输入包名 `dsh-exa-web-search` → 安装。
+
+**命令行**：
+
+```bash
+dsh plugin add dsh-exa-web-search
+```
+
+装好后**不用改任何设置**：联网搜索默认就走 Exa。卸载时自动还原，不会在你的配置里留下痕迹。想换成别的搜索源，在你自己的设置里改即可。
+
+## 配置（可选）
+
+| 字段 | 默认 | 说明 |
+| --- | --- | --- |
+| `mode` | `auto` | `auto` / `anonymous` / `keyed`，行为见上表 |
+| `apiKey` | — | 直接填入的 Key；留空则从 `apiKeyEnv` 指定的环境变量读取 |
+| `apiKeyEnv` | `EXA_API_KEY` | 从哪个环境变量读 Key |
+| `baseURL` | `https://api.exa.ai` | 官方 API 地址（带 Key 通道） |
+| `mcpURL` | `https://mcp.exa.ai/mcp?tools=web_search_advanced_exa,web_search_exa` | 公共通道地址（免 Key） |
+| `searchType` | `auto` | Exa 检索类型（仅带 Key 时生效）：`auto` / `keyword` / `neural` / `lite` / `deep-lite` / `deep` / `deep-reasoning` |
+
+平时不用手改配置文件：在**插件**页找到 `dsh-exa-web-search`，往 **Exa API Key** 卡片里填 Key 就行（界面自动打码，保存后不回显）。插件卡片上只放 Key；**点开这个插件的那一行**，行详情页还有模式、接口地址、检索类型等完整配置。
+
+## 和官方 Exa 插件的区别
+
+官方 Exa 插件只负责注册搜索源，装完还得自己把它设成默认。
+
+本插件直接以 `exa` 作为搜索源（顶替官方实现），装上即为默认，卸载即还原，不动你其它配置：
+
+- **没 Key 也能搜**：有 Key 走官方接口，没 Key 走免 Key 的公共通道，`auto` 自动切。
+- **零打扰**：不加新工具、不改系统提示词，`web_search` 照常用。

package/cordis.patch.yml

@@ -0,0 +1,24 @@
+# dsh-exa-web-search bundle patch.
+#
+# Two patches in this layer:
+#
+# 1. Insert this plugin's own row (registers provider id `exa`).
+# 2. Override the base `web` row to select it. A non-insert patch that names
+#    an existing row id replaces that row's fields — this is the same idiom
+#    official bundle layers use (`dsh-web-app` overrides base's `tool-web`
+#    and others). `config` is replaced wholesale, never merged; the `web`
+#    row only defines `searchProvider`/`fetchProvider`, so restating both is
+#    complete.
+#
+# Because selection lives in THIS bundle's patch — not a runtime write and
+# not the user's own cordis.patch.yml — uninstalling the bundle removes the
+# pin automatically. No `searchProvider`/`fetchProvider` residue is left
+# behind in the user layer the way dsh-free-search's runtime takeover did.
+- insert:
+    - id: exa-web-search
+      name: dsh-exa-web-search
+
+- id: web
+  config:
+    searchProvider: exa
+    fetchProvider: http

package/lib/client.js

@@ -0,0 +1,271 @@
+/**
+ * Client half of dsh-exa-web-search: two Plugins-page configuration cards.
+ * The bundle page carries just the API key; the row page carries the whole
+ * deployment section — mode, URLs, retrieval knobs — so the unobtrusive page
+ * is the one that has everything. `apiKey` is a `role('secret')` config
+ * field: the card learns only whether one is set (from the describe mirror's
+ * sidecar) and writes it like any other field; the literal never rides back.
+ * The card dictionaries live in the on-demand `client.locales.js` chunk.
+ */
+
+window.__ModuleLoader__.load({
+  id: 'dsh-exa-web-search',
+  factory(require) {
+    const React = require('react');
+    const {
+      SettingsForm, SettingsSecretField, SettingsValueField,
+      SettingsFormModel, settingsTextField,
+      Menu, IconChevronDownOutlineRegular,
+    } = require('@deepseek-ai/dsh-client-ui-primitives');
+
+    const h = React.createElement;
+    const NS = 'exaWebSearch';
+    /** The row id the bundle patch declares; also its settings namespace. */
+    const ENTRY_NS = 'exa-web-search';
+    /** The package-level slot key the bundle page dispatches under. */
+    const BUNDLE_KEY = 'dsh-exa-web-search';
+    /** `<package>#<row>` key the Plugins page dispatches row config slots by. */
+    const SLOT_KEY = `${BUNDLE_KEY}#exa-web-search`;
+    /** Exa search reference, linked from the retrieval-mode hint. */
+    const DOCS_URL = 'https://exa.ai/docs/reference/search';
+    /** On-demand dictionaries chunk; see client.locales.js. */
+    const loadLocales = () => require.async('./client.locales.js');
+
+    installStyles();
+
+    /** One-time styling for the enum dropdown; the module system owns and removes this tag. */
+    function installStyles() {
+      if (typeof document === 'undefined' || document.querySelector('style[data-exa-styles="1"]') !== null) return;
+      const el = document.createElement('style');
+      el.setAttribute('data-exa-styles', '1');
+      el.textContent = [
+        '.exa-field{margin:14px 0;display:flex;flex-direction:column;gap:6px}',
+        '.exa-head{display:flex;align-items:center;justify-content:space-between;gap:8px}',
+        '.exa-label{font-size:13px;font-weight:600;line-height:1.3}',
+        '.exa-reset{background:none;border:none;padding:0;color:inherit;opacity:.65;font:inherit;font-size:12px;cursor:pointer}',
+        '.exa-reset:hover{opacity:1}',
+        '.exa-trigger{display:flex;align-items:center;justify-content:space-between;gap:8px;width:100%;box-sizing:border-box;padding:7px 10px;border:1px solid rgba(128,128,128,.35);border-radius:8px;background:transparent;color:inherit;font:inherit;text-align:left;cursor:pointer}',
+        '.exa-trigger:focus-visible{outline:2px solid rgba(80,140,255,.6);outline-offset:1px}',
+        '.exa-trigger:disabled{opacity:.5;cursor:default}',
+        '.exa-value{overflow:hidden;text-overflow:ellipsis;white-space:nowrap}',
+        '.exa-hint{font-size:12px;line-height:1.4;opacity:.7;margin:0}',
+        '.exa-doclink{margin-left:6px;color:inherit;text-decoration:underline;text-underline-offset:2px}',
+      ].join('\n');
+      document.head.appendChild(el);
+    }
+
+    /**
+     * Whether the row's `apiKey` currently holds a value, read from the shared
+     * describe mirror's secret sidecar (`path` + `set`), never from the section.
+     * @param view - the shared describe snapshot's namespaces list.
+     * @returns true when the effective section reports a stored key.
+     */
+    function apiKeyConfigured(view) {
+      const entry = (view?.namespaces ?? []).find(item => item.ns === ENTRY_NS);
+      return (entry?.secrets ?? []).some(secret => secret.path.length === 1 && secret.path[0] === 'apiKey' && secret.set) === true;
+    }
+
+    /**
+     * A field accepting one of a fixed set of strings; anything else is an
+     * invalid draft that blocks the save. An empty draft clears the override.
+     * @param field - section field name.
+     * @param values - the accepted values.
+     * @returns the field's conversion spec.
+     */
+    function enumField(field, values) {
+      return {
+        field,
+        format: value => typeof value === 'string' ? value : '',
+        parse: (text) => {
+          const trimmed = text.trim();
+          if (trimmed === '') return { kind: 'clear' };
+          return values.includes(trimmed) ? { kind: 'set', value: trimmed } : undefined;
+        },
+      };
+    }
+
+    /** Form frame copy, read from this page's dictionary. */
+    function formLabels(t) {
+      return {
+        unavailable: t('unavailable'), readOnly: t('readOnly'),
+        saveFailed: t('saveFailed'), save: t('save'), saving: t('saving'),
+      };
+    }
+
+    /** One editable section field control bound to the shared form. */
+    function valueField(t, state, actions, field, id, label, hint, extra) {
+      return h(SettingsValueField, {
+        id, label, hint,
+        overriddenLabel: t('overridden'),
+        resetLabel: t('reset'),
+        invalidLabel: t('invalidNumber'),
+        disabled: !state.writable || state.saving,
+        ...state[field],
+        ...(extra === 'numeric' ? { numeric: true } : {}),
+        onEdit: (text) => { actions.edit(field, text) },
+        onReset: () => { actions.resetField(field) },
+      });
+    }
+
+    /**
+     * A dropdown for one enumerated section field, matching the Plugins page's
+     * own provider menu (a value button that opens a Menu). Picking a value
+     * stages it; the reset affordance clears the override back to the default.
+     * The hint explains the selected value and links its documentation.
+     */
+    function enumControl(t, state, actions, field, id, label, choices, hints, link) {
+      const current = state[field];
+      const value = current.text === '' ? choices[0] : current.text;
+      return h(EnumDropdown, {
+        id, label, choices, value,
+        disabled: !state.writable || state.saving,
+        overridden: current.overridden === true,
+        invalid: current.invalid === true,
+        resetLabel: t('reset'),
+        invalidLabel: t('invalidEnum'),
+        hint: hints?.[value],
+        link,
+        onSelect: (next) => { actions.edit(field, next) },
+        onReset: () => { actions.resetField(field) },
+      });
+    }
+
+    /** The enum dropdown body: a controlled Menu anchored to its value button. */
+    function EnumDropdown(props) {
+      const [open, setOpen] = React.useState(false);
+      const trigger = React.useRef(null);
+      const shown = open && !props.disabled;
+      const items = props.choices.map(choice => ({ id: choice, label: choice }));
+      const anchor = h('button', {
+        ref: trigger, id: props.id, type: 'button', className: 'exa-trigger', disabled: props.disabled,
+        'aria-haspopup': 'menu', 'aria-expanded': shown,
+        onClick: () => { setOpen(value => !value) },
+      },
+        h('span', { className: 'exa-value' }, props.value),
+        h(IconChevronDownOutlineRegular, { size: 12 }),
+      );
+      return h('div', { className: 'exa-field' },
+        h('div', { className: 'exa-head' },
+          h('label', { htmlFor: props.id, className: 'exa-label' }, props.label),
+          props.overridden
+            ? h('button', { type: 'button', className: 'exa-reset', disabled: props.disabled, onClick: props.onReset }, props.resetLabel)
+            : null,
+        ),
+        h(Menu, {
+          open: shown,
+          onClose: () => { setOpen(false) },
+          items,
+          selectedId: props.value,
+          onSelect: (next) => {
+            if (trigger.current) trigger.current.focus({ preventScroll: true });
+            setOpen(false);
+            if (next !== props.value) props.onSelect(next);
+          },
+          portal: true, autoFocus: true, minWidthFromAnchor: true, anchor,
+        }),
+        props.invalid ? h('p', { className: 'exa-hint', role: 'status' }, props.invalidLabel) : null,
+        (props.hint || props.link)
+          ? h('p', { className: 'exa-hint' },
+              props.hint ? h('span', null, props.hint) : null,
+              props.link ? h('a', { className: 'exa-doclink', href: props.link.href, target: '_blank', rel: 'noopener noreferrer' }, props.link.label) : null,
+            )
+          : null,
+      );
+    }
+
+    /** The API-key control shared by both cards. */
+    function keyField(t, state, actions) {
+      return h(SettingsSecretField, {
+        id: 'plugin-config-exa-api-key',
+        label: t('apiKey'),
+        hint: t('apiKeyHint'),
+        text: state.apiKey.text,
+        disabled: !state.writable || state.saving,
+        configured: state.apiKeyConfigured,
+        stateLabel: state.apiKeyConfigured ? t('apiKeySet') : t('apiKeyUnset'),
+        onEdit: (text) => { actions.edit('apiKey', text) },
+      });
+    }
+
+    /**
+     * The bundle-page card: just the key. `summary` renders the one-liner the
+     * row detail shows where a row has no description; `page` renders here.
+     */
+    function ExaKeyCard(props) {
+      const t = props.t;
+      if (props.view === 'summary') return t('summary');
+      const actions = props.exaActions;
+      const state = props.useExaForm(value => value);
+      return h(SettingsForm, { labels: formLabels(t), state, onSave: actions.save, onDiscard: actions.discard },
+        keyField(t, state, actions),
+      );
+    }
+
+    /** The row-page card: the key plus every deployment-level section field. */
+    function ExaConfigCard(props) {
+      const t = props.t;
+      if (props.view === 'summary') return t('summary');
+      const actions = props.exaActions;
+      const state = props.useExaForm(value => value);
+      return h(SettingsForm, { labels: formLabels(t), state, onSave: actions.save, onDiscard: actions.discard },
+        keyField(t, state, actions),
+        enumControl(t, state, actions, 'mode', 'plugin-config-exa-mode', t('mode'),
+          ['auto', 'anonymous', 'keyed'],
+          { auto: t('modeAuto'), anonymous: t('modeAnonymous'), keyed: t('modeKeyed') }, null),
+        enumControl(t, state, actions, 'searchType', 'plugin-config-exa-search-type', t('searchType'),
+          ['auto', 'keyword', 'neural', 'lite', 'deep-lite', 'deep', 'deep-reasoning'],
+          { auto: t('searchTypeAuto'), keyword: t('searchTypeKeyword'), neural: t('searchTypeNeural'), lite: t('searchTypeLite'), 'deep-lite': t('searchTypeDeepLite'), deep: t('searchTypeDeep'), 'deep-reasoning': t('searchTypeDeepReasoning') },
+          { href: DOCS_URL, label: t('docsLink') }),
+        valueField(t, state, actions, 'apiKeyEnv', 'plugin-config-exa-key-env', t('apiKeyEnv'), t('apiKeyEnvHint')),
+        valueField(t, state, actions, 'baseURL', 'plugin-config-exa-base-url', t('baseURL'), t('baseURLHint')),
+        valueField(t, state, actions, 'mcpURL', 'plugin-config-exa-mcp-url', t('mcpURL'), t('mcpURLHint')),
+      );
+    }
+
+    return {
+      inject: ['slots', 'locale', 'configForms'],
+      async apply(ctx) {
+        const LOCALES = await loadLocales();
+        ctx.effect(() => ctx.locale.register(NS, LOCALES), 'exa-web-search: dictionaries');
+        const scope = ctx.configForms.get(ENTRY_NS);
+        const describe = ctx.configForms.describe();
+        const form = new SettingsFormModel(scope, [
+          enumField('mode', ['auto', 'anonymous', 'keyed']),
+          enumField('searchType', ['auto', 'keyword', 'neural', 'lite', 'deep-lite', 'deep', 'deep-reasoning']),
+          settingsTextField('apiKeyEnv'),
+          settingsTextField('baseURL'),
+          settingsTextField('mcpURL'),
+        ], [{
+          field: 'apiKey',
+          write: (text) => scope.mutate([{ op: 'set', path: ['apiKey'], value: text }]),
+        }]);
+        ctx.effect(() => () => { form.dispose() }, 'exa-web-search: form model');
+        const project = () => ({
+          ...form.shell(),
+          apiKey: form.field('apiKey'),
+          apiKeyConfigured: apiKeyConfigured(describe.getSnapshot().view),
+          mode: form.field('mode'),
+          searchType: form.field('searchType'),
+          apiKeyEnv: form.field('apiKeyEnv'),
+          baseURL: form.field('baseURL'),
+          mcpURL: form.field('mcpURL'),
+        });
+        const formStore = form.bind(project);
+        // Secret presence lives outside the section, so a key written or
+        // cleared elsewhere would never republish the form on its own.
+        ctx.effect(() => describe.subscribe(() => { formStore.set(project()) }), 'exa-web-search: secret presence');
+        const actions = form.actions();
+        ctx.effect(() => ctx.configForms.whileServed([ENTRY_NS], () => {
+          const inject = () => ({ hooks: { exaForm: formStore }, exaActions: actions });
+          const key = ctx.slots.inject('plugins.bundle.config', () => ctx.slots.register(
+            { name: 'plugins.bundle.config', key: BUNDLE_KEY, locale: NS, inject },
+          ExaKeyCard));
+          const row = ctx.slots.inject('plugins.row.config', () => ctx.slots.register(
+            { name: 'plugins.row.config', key: SLOT_KEY, locale: NS, inject },
+          ExaConfigCard));
+          return () => { key(); row(); };
+        }), 'exa-web-search: config cards');
+      },
+    };
+  },
+});