@240xu/dsh-websearch 2.8.0 → 2.8.2

package/README.md

@@ -115,6 +115,12 @@ pnpm install
 
 环境变量兜底：未在 credentials 配置时回退读同名环境变量；`DSH_UNIFIED_SEARCH_BACKENDS` 可逗号分隔强制指定启用集合。
 
+## v2.8.1 SettingsForms 适配 | What's new in v2.8.1
+
+- **0.2.0 设置面板表单**：Config 标记 `meta.volatile`——0.2.0 SettingsForms 从插件 Config 自动生成表单，但 volatileForm 只保留 volatile 字段（此前 websearch 表单为空）；现整棵 Config 成为 0.2.0 表单。裁决与考证见 dsh-plugin-hub/docs/reviews/cross-settings-forms.md。
+- 删除 0.2.0 线上与可见 UI 自相矛盾的 "no installSection" console.warn（0.1.5 路径不变）。
+- 补齐全部裸字段（×ApiKeyEnv/×BaseURL/×Model）的 description——0.2.0 表单渲染唯一用户可见文案来自 meta.description。
+
 ## v2.8.0 查全查多 | What's new in v2.8.0
 
 面向「查的多一点、查的全一点」的检索深度升级，全部 feature-gated、默认关：
@@ -247,3 +253,16 @@ v2.7.0 缓存/熔断/历史三项的依据与刻意取舍（含查证过的反
 ## License | 许可
 
 MIT © 2026 240xu
+
+## 2.8.2 · Bug 猎场修复（P1×3 + 回归测试）
+
+- **[P1] 零结果伪造失败**：所有后端成功但 0 命中时，原实现落进 `all enabled
+  backends failed (0) - `（计数自相矛盾、detail 空）并丢弃 mergedContent（Tavily
+  直答）。成功即空 → 正常返回 `{sources:[]}` + history 记录。
+- **[P1] limiter 死锁**：`Promise.resolve(fn())` 先执行 fn——同步抛出（如 baseURL
+  校验在建 timeout 前）逃出后 `running` 永不递减，泄漏 ≥ concurrency 后所有任务
+  永久排队且超时机制未武装（实测 HUNG exit=13）。改 `Promise.resolve().then(fn)`。
+- **[P1] exa category 漏门控**：tavily/searxng 的 deepCoverage 增强都门控，唯独
+  exa 漏了——默认关 deepCoverage 也注入 category 收窄结果，与 README 承诺相反。
+- 回归测试 3 条（零结果/limiter 不死锁带 HUNG 超时护栏/exa 双态门控）；
+  `createLimiter` 导出供测试。89/89。

package/cordis.patch.yml

@@ -1,3 +1,13 @@
+# Bundle patch layer:
+# 1. insert the plugin row (registers the unified search provider)
+# 2. wire the built-in web_search tool to the unified provider (the plugin's
+#    whole reason to exist — previously a manual cordis.patch.yml edit, now
+#    automatic; revert = remove this row or disable the plugin, the base
+#    default (deepseek-official) is one yaml line away).
 - insert:
     - id: dsh-websearch
       name: '@240xu/dsh-websearch'
+- id: web
+  name: '@deepseek-ai/dsh-web'
+  config:
+    searchProvider: unified

package/lib/backends/exa.js

@@ -42,10 +42,14 @@ export const exaBackend = {
       query: request.query,
       numResults: request.maxResults ?? 8,
     };
-    // v2.8.0: category inference (feature-detect — only sent when confident;
-    // if the endpoint rejects it the fan-out demotes softly).
-    const category = inferExaCategory(request.query);
-    if (category) args.category = category;
+    // v2.8.0: category inference — deepCoverage-gated like tavily (searchDepth
+    // advanced) and searxng (category sweep): 2.8.1 审计发现此处漏了门控，
+    // 默认关着 deepCoverage 也注入 category，把结果悄悄收窄到单类目，与 README
+    // 「deepCoverage 深度覆盖」承诺相反。
+    if (request.deepCoverage === true) {
+      const category = inferExaCategory(request.query);
+      if (category) args.category = category;
+    }
     hooks.recordRequest?.({
       endpoint: EXA_ENDPOINT,
       toolName: EXA_TOOL,

package/lib/index.js

@@ -189,30 +189,48 @@ export const Config = z.object({
   enableOpenai: z.boolean().default(false).description(DEFAULT_LABELS.openai),
 
   // Credential refs (env-var names; secrets live in the credentials service)
-  braveApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.brave),
-  tavilyApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.tavily),
-  serperApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.serper),
-  mojeekApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.mojeek),
-  deepseekApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.deepseek),
-  anthropicApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.anthropic),
-  openaiApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.openai),
+  braveApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.brave)
+    .description("Brave API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  tavilyApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.tavily)
+    .description("Tavily API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  serperApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.serper)
+    .description("Serper API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  mojeekApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.mojeek)
+    .description("Mojeek API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  deepseekApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.deepseek)
+    .description("Deepseek API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  anthropicApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.anthropic)
+    .description("Anthropic API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
+  openaiApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_ENV.openai)
+    .description("Openai API Key 的凭证引用（填环境变量名，实际密钥存凭证库）"),
   searxngApiKeyEnv: z.string().role("credential-ref").default("SEARXNG_API_KEY")
-    .description("SearXNG 私有实例的 API Key（公共实例留空）"),
+    .description("SearXNG 私有实例的 API Key 凭证引用（公共实例留空）"),
 
   // Base URLs (defaults from built-in registry)
-  braveBaseURL: z.string().default(DEFAULT_BASE_URLS.brave),
-  tavilyBaseURL: z.string().default(DEFAULT_BASE_URLS.tavily),
-  serperBaseURL: z.string().default(DEFAULT_BASE_URLS.serper),
-  mojeekBaseURL: z.string().default(DEFAULT_BASE_URLS.mojeek),
-  searxngBaseURL: z.string().default(DEFAULT_BASE_URLS.searxng),
-  deepseekBaseURL: z.string().default(DEFAULT_BASE_URLS.deepseek),
-  anthropicBaseURL: z.string().default(DEFAULT_BASE_URLS.anthropic),
-  openaiBaseURL: z.string().default(DEFAULT_BASE_URLS.openai),
+  braveBaseURL: z.string().default(DEFAULT_BASE_URLS.brave)
+    .description("Brave API 端点（默认官方；自托管/代理实例改此项）"),
+  tavilyBaseURL: z.string().default(DEFAULT_BASE_URLS.tavily)
+    .description("Tavily API 端点（默认官方；自托管/代理实例改此项）"),
+  serperBaseURL: z.string().default(DEFAULT_BASE_URLS.serper)
+    .description("Serper.dev API 端点（默认官方；自托管/代理实例改此项）"),
+  mojeekBaseURL: z.string().default(DEFAULT_BASE_URLS.mojeek)
+    .description("Mojeek API 端点（默认官方；自托管/代理实例改此项）"),
+  searxngBaseURL: z.string().default(DEFAULT_BASE_URLS.searxng)
+    .description("SearXNG API 端点（默认官方；自托管/代理实例改此项）"),
+  deepseekBaseURL: z.string().default(DEFAULT_BASE_URLS.deepseek)
+    .description("DeepSeek API 端点（默认官方；自托管/代理实例改此项）"),
+  anthropicBaseURL: z.string().default(DEFAULT_BASE_URLS.anthropic)
+    .description("Anthropic API 端点（默认官方；自托管/代理实例改此项）"),
+  openaiBaseURL: z.string().default(DEFAULT_BASE_URLS.openai)
+    .description("OpenAI API 端点（默认官方；自托管/代理实例改此项）"),
 
   // Models
-  deepseekModel: z.string().default(DEFAULT_MODELS.deepseek),
-  anthropicModel: z.string().default(DEFAULT_MODELS.anthropic),
-  openaiModel: z.string().default(DEFAULT_MODELS.openai),
+  deepseekModel: z.string().default(DEFAULT_MODELS.deepseek)
+    .description("DeepSeek 后端使用的模型名"),
+  anthropicModel: z.string().default(DEFAULT_MODELS.anthropic)
+    .description("Anthropic 后端使用的模型名"),
+  openaiModel: z.string().default(DEFAULT_MODELS.openai)
+    .description("OpenAI 后端使用的模型名"),
   tavilySearchDepth: z.union(["basic", "advanced"]).default("basic")
     .description("Tavily 搜索深度"),
 
@@ -221,6 +239,15 @@ export const Config = z.object({
     .description("显式启用后端列表（优先于上方开关；留空则用开关）"),
 });
 
+// 0.2.0 SettingsForms adapter (cross-settings-forms.md ruling): the 0.2.0
+// settings service auto-generates its form from entry.fiber.runtime.Config —
+// but volatileForm (RT dsh-settings lib/index.js:122-138) keeps ONLY fields
+// with meta.volatile; a Config without any yields an empty form. Marking the
+// top object makes the whole Config the form. Direct meta assignment (not
+// .volatile(), which returns a NEW schema and throws on re-wrap) is
+// equivalent and idempotent on both the 0.1.5 and 0.2.0 schemastery lines.
+Config.meta = { ...Config.meta, volatile: true };
+
 /**
  * Per-field user-language labels (fe-ui W1 remainder): the settings renderer
  * falls back to camelCase keys when no label is present, so attach one to
@@ -368,6 +395,7 @@ export function apply(ctx, config) {
   ctx.inject(["settings"], (settingsCtx) => {
     const settings = settingsCtx.settings;
     if (typeof settings?.installSection === "function") {
+      // 0.1.5 SettingsProvider line: explicit section install (unchanged).
       settings.installSection(ctx, NAMESPACE, Config, config, {
         setSource: (source) => {
           current = source;
@@ -376,15 +404,10 @@ export function apply(ctx, config) {
       });
       return;
     }
-    // DSH 0.1.7+: the settings service is SettingsForms and has no
-    // installSection. The Config schema still resolves through cordis config
-    // (this file reads `current()`), so search keeps working; surface the gap
-    // once instead of silently swallowing it (compat-audit P1).
-    console.warn(
-      "[dsh-websearch] settings service has no installSection (DSH >= 0.1.7 SettingsForms line); " +
-      "the Settings panel section is not installed. Configure the unified-search namespace via cordis config " +
-      "or the client settings card; migration to the SettingsForms API is tracked for a future release.",
-    );
+    // 0.2.0 SettingsForms line: no installSection; the settings form is
+    // auto-generated from the volatile-marked Config above — no action and no
+    // warning here (the form IS the section; a warning would contradict the
+    // visible UI). Config values still resolve via cordis config.
   });
 
   // v2.7.0 stores: disk cache + append-only search history, both under

package/lib/provider.js

@@ -82,7 +82,8 @@ export function getBackendBreaker(id) {
  * Simple concurrency limiter using a semaphore pattern.
  * No external dependency needed.
  */
-function createLimiter(concurrency) {
+// 2.8.2: exported for P1 regression tests (limiter sync-throw deadlock)
+export function createLimiter(concurrency) {
   const queue = [];
   let running = 0;
   
@@ -95,7 +96,12 @@ function createLimiter(concurrency) {
         while (running < concurrency && queue.length > 0) {
           const { fn, resolve, reject } = queue.shift();
           running++;
-          Promise.resolve(fn()).then(resolve).catch(reject).finally(() => {
+          // 2.8.2（P1）：必须 .then(fn) 而非 Promise.resolve(fn())——后者先执行
+          // fn()，同步抛出（如 runBackend 的 baseURL 校验在创建 timeout 之前 throw）
+          // 会逃出本函数：running 已 ++ 却永不 --（finally 没挂上），leaked 计数
+          // ≥ concurrency 后所有后续任务永久排队，且 timeoutId 未创建 → 超时也救不了
+          // （实测全挂起 exit=13）。.then(fn) 把同步抛出转为 rejection 落进 finally。
+          Promise.resolve().then(fn).then(resolve).catch(reject).finally(() => {
             running--;
             process();
           });
@@ -435,6 +441,31 @@ export function createUnifiedSearchProvider({ ctx, resolveOptions, backends, cac
         };
       }
 
+      // 2.8.2（P1）：零结果 ≠ 全部失败。所有后端成功但确实 0 条命中（冷僻查询/
+      // 过滤后为空）时，原实现无条件落入下面的 throw，模型端拿到
+      // `all enabled backends failed (0) - `（detail 空、计数自相矛盾），且丢弃已
+      // 拿到的 mergedContent（如 Tavily 直答）。成功即空 → 正常返回空结果。
+      if (allFailures.length === 0) {
+        let emptyContent = perVariant.find((v) => v.mergedContent !== undefined)?.mergedContent;
+        if (opts.resultHeader !== false && emptyContent !== undefined) {
+          const header = resultHeader(typeof request?.query === "string" && /[\u4e00-\u9fff]/.test(request.query) ? "zh" : "en");
+          emptyContent = header + "\n\n" + emptyContent;
+        }
+        history?.record({
+          query: request?.query,
+          time: Date.now(),
+          resultCount: 0,
+          backendsOk: allTelemetry.filter((t) => t.ok).length,
+          backendsTotal: allTelemetry.length,
+        });
+        if (cacheKey && cache) cache.set(cacheKey, { sources: [], content: emptyContent, truncated: false });
+        return {
+          sources: [],
+          ...(emptyContent !== undefined ? { content: emptyContent } : {}),
+          truncated: false,
+        };
+      }
+
       // All enabled backends failed - synthesize one meaningful error that
       // names each backend's own reason so the caller (model or user) can act.
       const detail = allFailures.slice(0, 4)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@240xu/dsh-websearch",
-  "version": "2.8.0",
+  "version": "2.8.2",
   "description": "Unified web search provider for DeepSeek Harness (ctx.web): 11 backends — Exa + Parallel + DDG + SearXNG (keyless), DeepSeek + Anthropic + OpenAI + Brave + Tavily + Serper + Mojeek (key-gated via Settings credentials). Registers provider id \"unified\" for zero-config web_search. 统一网页搜索聚合：11 后端并发扇出、去重合并，零依赖。See CHANGELOG.md for version history.",
   "type": "module",
   "main": "lib/index.js",