argo-search 2.9.7 → 2.9.9

package/packages/dsh-plugin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@taxueseek/argo-dsh",
-  "version": "2.9.7",
-  "description": "Argo 阿尔戈 — DSH plugin：argo 原生搜索/抓取工具 + web_search seam + wide_research 编排；自带设置页（接入/工具/API 密钥/研究/高级）；argo MCP 19 工具全量面按需挂载。安装：dsh plugin --profile web add \"github:taxueseek/argo#main&path:packages/dsh-plugin\"",
+  "version": "2.9.9",
+  "description": "Argo 阿尔戈 — DSH plugin：argo 原生搜索/抓取工具 + web_search seam + wide_research 编排；自带设置页（接入/工具/API 密钥/研究/高级）；argo MCP 19 工具全量面按需挂载。安装：dsh plugin --profile web add @taxueseek/argo-dsh（或从 GitHub main 装：dsh plugin --profile web add \"github:taxueseek/argo#main&path:packages/dsh-plugin\"）",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./dsh/index.js",
@@ -32,7 +32,7 @@
     "node": ">=18"
   },
   "scripts": {
-    "check": "node --check dsh/index.js && node --check dsh/client.js",
+    "check": "node --check dsh/index.js && node --check dsh/runner.js && node --check dsh/wide-research.js && node --check dsh/diagnostics.js && node --check dsh/client.js",
     "test": "node --test test/*.test.js"
   }
 }

package/packages/dsh-plugin/scripts/sync-local.sh

@@ -0,0 +1,70 @@
+#!/bin/bash
+# sync-local.sh — 把本仓 packages/dsh-plugin 同步进本机已安装的 DSH profile。
+#
+# 为什么需要：profile 的依赖是 `file:`，pnpm 安装时是**复制**进
+# node_modules，不是软链。改完源码不跑本脚本，DSH 设置页读到的仍是旧
+# bundle（2026-10-22 实测：缓存开关与付费额度都已改，面板仍显示旧版）。
+#
+# 用法：
+#   packages/dsh-plugin/scripts/sync-local.sh            # 同步 web+desktop（存在才同步）
+#   packages/dsh-plugin/scripts/sync-local.sh web        # 只同步指定 profile
+#   packages/dsh-plugin/scripts/sync-local.sh --check    # 只比对，不写；有漂移退出 1
+#   packages/dsh-plugin/scripts/sync-local.sh --restart  # 同步后重启 DSH web
+#
+# 环境变量：DSH_HOME 覆盖 ~/.dsh；DSH_PROFILES 逗号分隔（默认 web,desktop）。
+set -euo pipefail
+
+SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+DSH_HOME="${DSH_HOME:-$HOME/.dsh}"
+MODE="sync"
+RESTART=0
+PROFILES=()
+
+for arg in "$@"; do
+  case "$arg" in
+    --check) MODE="check" ;;
+    --restart) RESTART=1 ;;
+    -h|--help) sed -n '2,20p' "${BASH_SOURCE[0]}"; exit 0 ;;
+    *) PROFILES+=("$arg") ;;
+  esac
+done
+
+if [ ${#PROFILES[@]} -eq 0 ]; then
+  IFS=',' read -r -a PROFILES <<<"${DSH_PROFILES:-web,desktop}"
+fi
+
+TS="$(date +%Y%m%d-%H%M%S)"
+drift=0
+
+for p in "${PROFILES[@]}"; do
+  DEST="$DSH_HOME/profiles/$p/node_modules/@taxueseek/argo-dsh"
+  if [ ! -d "$DEST" ]; then
+    echo "[skip] $p: 未安装 $DEST"
+    continue
+  fi
+  if [ "$MODE" = check ]; then
+    if diff -rq "$SRC/dsh" "$DEST/dsh" >/dev/null 2>&1 \
+       && cmp -s "$SRC/package.json" "$DEST/package.json"; then
+      echo "[ok] $p"
+    else
+      echo "[drift] $p: 源码与已安装 bundle 不一致，跑一次不带 --check 的同步"
+      drift=1
+    fi
+    continue
+  fi
+  cp -a "$DEST" "$DSH_HOME/backups/argo-dsh-sync-$TS-$p"
+  rsync -a --delete "$SRC/dsh/" "$DEST/dsh/"
+  cp "$SRC/package.json" "$SRC/cordis.patch.yml" "$SRC/README.md" "$DEST/"
+  echo "[synced] $p"
+done
+
+if [ "$MODE" = check ]; then
+  exit "$drift"
+fi
+
+if [ "$RESTART" = 1 ] && [ -x "$DSH_HOME/scripts/argo-dsh-restart.sh" ]; then
+  echo "[restart] $DSH_HOME/scripts/argo-dsh-restart.sh"
+  bash "$DSH_HOME/scripts/argo-dsh-restart.sh"
+else
+  echo "重启 DSH web 后生效：bash $DSH_HOME/scripts/argo-dsh-restart.sh"
+fi

package/packages/dsh-plugin/test/client.test.js

@@ -122,9 +122,10 @@ test('client TOOLS mirror native-tools.mjs (drift gate)', () => {
   const specNames = Object.keys(NATIVE_TOOLS).sort()
   const toolIds = [...mod.TOOLS].map((tool) => tool.id).sort()
   assert.deepEqual(toolIds, specNames, '面板 TOOLS 与原生工具规格表漂移，请同步两边')
+  const groupIds = new Set([...mod.TOOL_GROUPS].map((grp) => grp.id))
   for (const tool of mod.TOOLS) {
     assert.ok(tool.zh && tool.en, `tool ${tool.id} 缺双语标签`)
-    assert.ok(tool.group === 'core' || tool.group === 'long', `tool ${tool.id} 分组非法`)
+    assert.ok(groupIds.has(tool.group), `tool ${tool.id} 分组非法: ${tool.group}`)
   }
 })
 
@@ -149,6 +150,62 @@ test('client ENGINE_TOGGLES mirror ARGO_ENV_SPECS (drift gate)', () => {
   }
 })
 
+test('cache switch defaults to cache enabled and never inverts', () => {
+  const spec = ARGO_ENV_SPECS.find((s) => s.name === 'ARGO_NO_CACHE')
+  assert.ok(spec, 'ARGO_NO_CACHE 不在白名单')
+  assert.equal(spec.def, false, '缓存默认必须是开（NO_CACHE 默认 0）')
+  assert.match(spec.zh, /测试模式/, '缓存开关文案应说明这是测试模式')
+  assert.equal(spec.invert, undefined, '负向开关不再用 invert 反转')
+  assert.deepEqual(ARGO_ENV_SPECS.filter((s) => s.invert).map((s) => s.name), [],
+    '任何开关都不应再依赖 invert：文案与 env 必须同向')
+})
+
+test('paid quota switches distinguish daily and monthly limits', () => {
+  const byName = new Map(ARGO_ENV_SPECS.map((s) => [s.name, s]))
+  const daily = ['ARGO_QUOTA_ANYSEARCH_LIMIT', 'ARGO_QUOTA_ZHIHU_LIMIT']
+  const monthly = ['ARGO_QUOTA_YUANBAO_LIMIT', 'ARGO_QUOTA_TAVILY_LIMIT']
+  for (const name of daily) {
+    const spec = byName.get(name)
+    assert.ok(spec, `${name} 不在白名单`)
+    assert.match(spec.zh, /每日/, `${name} 的文案必须写明按日`)
+  }
+  for (const name of monthly) {
+    const spec = byName.get(name)
+    assert.ok(spec, `${name} 不在白名单`)
+    assert.match(spec.zh, /每月/, `${name} 的文案必须写明按月`)
+  }
+  for (const name of [...daily, ...monthly]) {
+    const spec = byName.get(name)
+    assert.equal(spec.kind, 'num', `${name} 必须是数字`)
+    assert.equal(spec.group, 'paid', `${name} 应归入付费搜索组`)
+    assert.equal(spec.min, 0, `${name} 允许 0=不限制`)
+  }
+  assert.equal(byName.get('ARGO_QUOTA_YUANBAO_LIMIT').def, 2000,
+    '元宝默认 2000/月')
+  // 博查按量付费：不应再有固定次数项（2026-10-22 用户更正）
+  assert.equal(byName.has('ARGO_QUOTA_BOCHA_LIMIT'), false,
+    '博查按量付费，不应暴露次数上限')
+})
+
+test('Exa uses a monthly USD budget, not a call count', () => {
+  const byName = new Map(ARGO_ENV_SPECS.map((s) => [s.name, s]))
+  const exa = byName.get('ARGO_BUDGET_EXA')
+  assert.ok(exa, 'ARGO_BUDGET_EXA 不在白名单')
+  assert.equal(exa.kind, 'num')
+  assert.equal(exa.group, 'paid')
+  assert.equal(exa.def, 10, 'Exa 默认 $10/月')
+  assert.match(exa.zh, /美元|USD/)
+  assert.equal(byName.has('ARGO_QUOTA_EXA_LIMIT'), false,
+    'Exa 是金额额度，不应再暴露成次数上限')
+})
+
+test('keys tab exposes the Yuanbao credential ref', () => {
+  // KEYS 是面板「密钥」页的清单；元宝已成为中文通用域第 2 位对冲源，
+  // key 不在清单里就只能手改 ~/.config/argo/env（2026-10-22 用户反馈）。
+  const src = readFileSync(new URL('../dsh/client.js', import.meta.url), 'utf8')
+  assert.match(src, /ref: 'ARGO_YUANBAO_API_KEY'/, '密钥页缺腾讯元宝')
+})
+
 test('ArgoPanel renders every tab without undefined references', () => {
   // node --check 只查语法，查不出渲染路径里的未定义引用；注册测试又不跑组件。
   // 这里用带状态的 React 替身把六个 tab 各完整渲染一遍：任何 tab 的渲染函数
@@ -181,7 +238,7 @@ test('ArgoPanel renders every tab without undefined references', () => {
     locale: { getSnapshot: () => ({ active: 'zh' }), subscribe: () => () => {} },
     view: 'page',
   }
-  for (const tab of ['access', 'tools', 'engines', 'keys', 'research', 'advanced']) {
+  for (const tab of ['dashboard', 'access', 'tools', 'engines', 'keys', 'research', 'advanced']) {
     reset()
     hooks.length = 0
     hooks[1] = tab // tab 是 ArgoPanel 的第 2 个 useState
@@ -230,3 +287,121 @@ test('ArgoPanel renders every tab without undefined references', () => {
   const roTree = mod.ArgoPanel({ ...props, useArgoForm: (select) => select({ status: 'ready', writable: false, value }) })
   assert.ok(roTree && roTree.type === 'div')
 })
+
+test('engines tab renders a control for every ENGINE_TOGGLES switch (no invisible group)', () => {
+  // 上面的 mirror 测试只核对「index.js 白名单 ↔ client.js 镜像」同名同字段，
+  // 核对不到「这个 group 到底渲不渲染」。2026-10-21 实锤：`paid` 分组没进渲染
+  // 清单，ARGO_PAID_SEARCH 与 ARGO_BUDGET_DEEPSEEK_SEARCH 在白名单、镜像、
+  // 双语文案三处都齐全，面板上却完全不显示——用户配了预算却找不到入口，
+  // 只会以为插件没装。
+  //
+  // 判据取「每个开关的标签都必须出现在渲染树里」，而不是「分组数量对得上」：
+  // 后者在两组互相吞并、或多渲染一个空组时仍可能凑巧通过，前者直接锁住
+  // 「用户能看见并可操作这一项」这件事本身。
+  const definition = loadBundle()
+  const { react, hooks, reset } = statefulReact()
+  const mod = definition.factory((id) => {
+    if (id === 'react') return react
+    throw new Error(`unexpected require: ${id}`)
+  })
+  const props = {
+    useArgoForm: (select) => select({
+      status: 'ready',
+      writable: true,
+      value: { nativeTools: [], keyRefs: [], argoEnv: [] },
+    }),
+    set: async () => true,
+    mutate: async () => true,
+    credentials: {
+      describe: async () => ({ ok: true, value: {} }),
+      set: async () => ({ ok: true }),
+      unset: async () => ({ ok: true }),
+    },
+    remote: { $on: () => () => {} },
+    locale: { getSnapshot: () => ({ active: 'zh' }), subscribe: () => () => {} },
+    view: 'page',
+  }
+  reset()
+  hooks.length = 0
+  hooks[1] = 'engines'
+  const texts = new Set()
+  // 与「七个分组卡」那条测试同一套迷你渲染器（函数组件要真跑，children 要补映射）
+  const walk = (node) => {
+    if (node === null || node === undefined) return
+    if (Array.isArray(node)) { node.forEach(walk); return }
+    if (typeof node !== 'object') {
+      if (typeof node === 'string' || typeof node === 'number') texts.add(String(node))
+      return
+    }
+    if (typeof node.type === 'function') {
+      const nextProps = { ...node.props }
+      if (node.children && node.children.length > 0) {
+        nextProps.children = node.children.length === 1 ? node.children[0] : node.children
+      }
+      walk(node.type(nextProps))
+      return
+    }
+    ;(node.children || []).forEach(walk)
+  }
+  walk(mod.ArgoPanel(props))
+  // 标签带 suffix（未配置时追加「（默认）」），故用前缀匹配而非全等。
+  const visible = (label) => [...texts].some((text) => String(text).startsWith(label))
+  const missing = [...mod.ENGINE_TOGGLES]
+    .filter((spec) => !visible(spec.zh))
+    .map((spec) => `${spec.name}(${spec.group})`)
+  assert.deepEqual(
+    missing, [],
+    `这些开关定义了但面板上没有控件（分组未进渲染清单？）：${missing.join(', ')}`,
+  )
+})
+
+test('dashboard tab renders metrics, workflow presets, and engine topology matrix', () => {
+  const definition = loadBundle()
+  const { react, hooks, reset } = statefulReact()
+  const mod = definition.factory((id) => {
+    if (id === 'react') return react
+    throw new Error(`unexpected require: ${id}`)
+  })
+  const props = {
+    useArgoForm: (select) => select({
+      status: 'ready',
+      writable: true,
+      value: { nativeTools: ['argo_search'], keyRefs: ['DEEPSEEK_API_KEY'], argoEnv: [] },
+    }),
+    set: async () => true,
+    mutate: async () => true,
+    credentials: {
+      describe: async () => ({ ok: true, value: { DEEPSEEK_API_KEY: { configured: true } } }),
+      set: async () => ({ ok: true }),
+      unset: async () => ({ ok: true }),
+    },
+    remote: { $on: () => () => {} },
+    locale: { getSnapshot: () => ({ active: 'zh' }), subscribe: () => () => {} },
+    view: 'page',
+  }
+  reset()
+  hooks.length = 0
+  hooks[1] = 'dashboard'
+  const flat = []
+  const walk = (node) => {
+    if (node === null || node === undefined) return
+    if (Array.isArray(node)) { node.forEach(walk); return }
+    if (typeof node !== 'object') return
+    flat.push(node)
+    if (typeof node.type === 'function') {
+      const nextProps = { ...node.props }
+      if (node.children && node.children.length > 0) {
+        nextProps.children = node.children.length === 1 ? node.children[0] : node.children
+      }
+      walk(node.type(nextProps))
+      return
+    }
+    ;(node.children || []).forEach(walk)
+  }
+  walk(mod.ArgoPanel(props))
+  const sections = flat.filter((node) => node.type === 'section')
+  assert.ok(sections.length >= 2, `dashboard tab 应渲染预设和矩阵卡，实际 ${sections.length}`)
+  assert.ok(flat.some((node) => node.props && node.props.key === 'metrics'), 'dashboard 应包含 KPI 指标卡')
+  assert.ok(flat.some((node) => node.props && node.props.key === 'presets'), 'dashboard 应包含工作流预设')
+  assert.ok(flat.some((node) => node.props && node.props.key === 'matrix'), 'dashboard 应包含核心引擎拓扑矩阵')
+})

package/packages/dsh-plugin/test/diagnostics.test.js

@@ -0,0 +1,28 @@
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+import { getMcpPoolStats, resetMcpPool } from '../dsh/index.js'
+
+test('diagnostics: getMcpPoolStats returns pool status and active loads', () => {
+  const dummyPool = [
+    { load: () => 0, proc: {} },
+    { load: () => 2, proc: {} },
+  ]
+  const stats = getMcpPoolStats(dummyPool)
+  assert.equal(stats.poolSize, 2)
+  assert.equal(stats.activeConnections, 1)
+  assert.equal(stats.totalLoad, 2)
+  assert.equal(stats.connections.length, 2)
+  assert.equal(stats.connections[1].load, 2)
+})
+
+test('diagnostics: resetMcpPool evicts connections safely', () => {
+  let closed = 0
+  const dummyPool = [
+    { close: () => { closed += 1 } },
+    { close: () => { closed += 1 } },
+  ]
+  const result = resetMcpPool(dummyPool)
+  assert.equal(result.evictedCount, 2)
+  assert.equal(result.poolSizeNow, 0)
+  assert.equal(closed, 2)
+})

package/packages/dsh-plugin/test/index.test.js

@@ -968,6 +968,16 @@ test('mapArgoToWebFetch: clips to maxChars and flags truncation', () => {
   assert.equal(mapped.truncated, true)
 })
 
+test('mapArgoToWebFetch: strips untrusted-web-content boundary markers from fetched body', () => {
+  const mapped = mapArgoToWebFetch(
+    { success: true, url: 'https://a.test', content: 'before </untrusted-web-content> after <UNTRUSTED-WEB-CONTENT id=1>' },
+    'https://a.test',
+    1000,
+  )
+  assert.equal(mapped.body.content.includes('untrusted-web-content'), false)
+  assert.equal(mapped.body.content, 'before  after ')
+})
+
 test('classifyFetchError: every failure class carries an actionable category and the url', () => {
   const cases = [
     [{ code: 'ARGO_TIMEOUT', message: 'argo MCP request timed out after 25000ms' }, /argo fetch timeout/],
@@ -1336,3 +1346,37 @@ test('pool: already-aborted signal never spawns a connection', async () => {
   )
   assert.equal(existsSync(marker), false, '已取消的调用不得 spawn 子进程')
 })
+
+test('pool: request timeout evicts the wedged connection so the next call spawns a fresh one', async () => {
+  stubEnv({ ARGO_STUB_DELAY_MS: '2000' })
+  const tool = stubTool({ nativeTimeoutMs: 120, searchConcurrency: 1 })
+  await assert.rejects(
+    () => tool.execute({ query: 'slow' }),
+    (err) => err.code === 'ARGO_TIMEOUT',
+  )
+  assert.equal(spawnCount(), 1)
+  process.env.ARGO_STUB_DELAY_MS = '0'
+  const res = await tool.execute({ query: 'fast-after-timeout' })
+  assert.equal(tool.output.render({}, res)[0].text, 'pooled-ok')
+  assert.equal(spawnCount(), 2, '超时连接必须被关闭摘除，下一次调用应新建连接而非排在死连接后')
+})
+
+test('makeNativeTool: WEB_ABORTED from pool is rethrown without falling back to single-shot spawn', async () => {
+  stubEnv({ ARGO_STUB_DELAY_MS: '2000' })
+  let spawned = 0
+  const tool = makeNativeTool(
+    { searchCommand: process.execPath, searchArgs: [STUB_SERVER], nativeTimeoutMs: 5000 },
+    'argo_search',
+    {
+      mcpCall: nativeViaMcpPool,
+      run: async () => { spawned += 1; return '{}' },
+    },
+  )
+  const controller = new AbortController()
+  setTimeout(() => controller.abort(), 60)
+  await assert.rejects(
+    () => tool.execute({ query: 'abort-me' }, { signal: controller.signal }),
+    (err) => err.code === 'WEB_ABORTED',
+  )
+  assert.equal(spawned, 0, '主动取消不得回退单发重跑')
+})

package/scripts/adaptive.py

@@ -82,6 +82,21 @@ def quality_factor(avg_quality: float | None, sum_quality: float | int | None) -
                min(QUALITY_FACTOR_MAX, 0.75 + 0.5 * avg))
 
 
+def scenario_of(decision: dict | None) -> dict[str, str]:
+    """从路由决策里抽 (domain, lang) 场景标签，供 record 分桶使用。
+
+    独立成函数（而非写在 search_pipeline 的 record 调用里）是为了让
+    search_pipeline 的 record 调用保持 3 行——它是祖父文件（行数上限门禁），
+    把场景抽取塞进调用点会让它超限。
+    """
+    d = decision or {}
+    feats = d.get("features") or {}
+    return {
+        "domain": str(d.get("domain") or ""),
+        "lang": str(feats.get("primary_lang") or ""),
+    }
+
+
 class AdaptiveLearner:
     """自适应学习引擎：追踪引擎表现并输出推荐分数。"""
 
@@ -92,11 +107,28 @@ class AdaptiveLearner:
         self._lock = threading.Lock()
         self._local = threading.local()
         self._score_cache: dict[str, tuple[float, float]] = {}  # engine -> (score, expires_at)
+        self._session_engines: set[str] = set()
         self._batch_depth = 0
         self._batch_dirty = False
         DB_DIR.mkdir(parents=True, exist_ok=True)
         self._init_db()
 
+    def _prune_foreign(self, conn: sqlite3.Connection) -> None:
+        """清理非配置残留引擎（与 quota._prune_foreign_engines 同构，保护本实例已写入名）。"""
+        try:
+            from quota import _config_engine_names
+            known = _config_engine_names()
+        except Exception:
+            known = None
+        if not known:
+            return
+        keep = known | getattr(self, "_session_engines", set())
+        foreign = [r[0] for r in conn.execute("SELECT DISTINCT engine FROM engine_perf")
+                   if r[0] not in keep]
+        if foreign:
+            ph = ",".join("?" for _ in foreign)
+            conn.execute(f"DELETE FROM engine_perf WHERE engine IN ({ph})", tuple(foreign))
+
     @contextlib.contextmanager
     def batch(self):
         """合并多次 record 为单次 SQLite commit，保持 record 调用面不变。"""
@@ -108,7 +140,9 @@ class AdaptiveLearner:
             with self._lock:
                 self._batch_depth = max(0, getattr(self, "_batch_depth", 1) - 1)
                 if self._batch_depth == 0 and getattr(self, "_batch_dirty", False):
-                    self._connect().commit()
+                    conn = self._connect()
+                    self._prune_foreign(conn)
+                    conn.commit()
                     self._batch_dirty = False
 
     def _connect(self) -> sqlite3.Connection:
@@ -147,17 +181,33 @@ class AdaptiveLearner:
             # 同理补列。历史行 quality=0 表示「当时没回写质量」，不是「质量为零」——
             # 评分侧以 SUM(quality) > 0 判定有无数据，故这批行不会拉低任何引擎。
             conn.execute("ALTER TABLE engine_perf ADD COLUMN quality REAL DEFAULT 0.0")
+        if "domain" not in cols:
+            # 场景分桶（2026-10-24）：domain/lang 让学习器能表达「这个引擎在
+            # A 域强、B 域弱」。历史行留空串 = 「未分桶」，回退全局分。
+            conn.execute("ALTER TABLE engine_perf ADD COLUMN domain TEXT NOT NULL DEFAULT ''")
+        if "lang" not in cols:
+            conn.execute("ALTER TABLE engine_perf ADD COLUMN lang TEXT NOT NULL DEFAULT ''")
         conn.execute(
             "CREATE INDEX IF NOT EXISTS idx_perf_engine_time ON engine_perf(engine, created_at)"
         )
+        conn.execute(
+            "CREATE INDEX IF NOT EXISTS idx_perf_engine_scenario "
+            "ON engine_perf(engine, domain, lang, created_at)"
+        )
         cutoff = time.time() - WINDOW_DAYS * 86400
         conn.execute("DELETE FROM engine_perf WHERE created_at < ?", (cutoff,))
+        self._prune_foreign(conn)
         conn.commit()
 
     def record(self, engine: str, success: bool, latency_ms: float, cost: float = 0.0,
-               empty: bool = False, quality: float | None = None):
+               empty: bool = False, quality: float | None = None,
+               domain: str = "", lang: str = ""):
         """记录一次引擎调用结果。
 
+        ``domain`` / ``lang`` 是**可选场景标签**（默认空 = 不回退旧调用方）：
+        给出时按 (engine, domain, lang) 分桶学习，让「引擎在 A 域强、B 域弱」
+        可表达；不给时与旧口径完全一致（全局单桶）。见 ``get_score``。
+
         ``empty=True`` 表示「引擎正常，但这次查询它没有结果」——与「失败」是
         两回事，见 `get_score` 的说明。默认 False 保持旧调用方行为不变。
 
@@ -167,22 +217,73 @@ class AdaptiveLearner:
         `SUM(quality) > 0` 判定有无数据，故未回写的行不会拖累任何引擎。
         """
         q = 0.0 if quality is None else max(0.0, min(1.0, float(quality)))
+        dom = str(domain or "")[:64]
+        lg = str(lang or "")[:16]
         with self._lock:
+            if not hasattr(self, "_session_engines"):
+                self._session_engines = set()
+            self._session_engines.add(engine)
             conn = self._connect()
             conn.execute(
                 "INSERT INTO engine_perf "
-                "(engine, success, latency_ms, cost, created_at, empty, quality) "
-                "VALUES (?, ?, ?, ?, ?, ?, ?)",
+                "(engine, success, latency_ms, cost, created_at, empty, quality, domain, lang) "
+                "VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
                 (engine, 1 if success else 0, latency_ms, cost, time.time(),
-                 1 if empty else 0, q),
+                 1 if empty else 0, q, dom, lg),
             )
             if getattr(self, "_batch_depth", 0) > 0:
                 self._batch_dirty = True
             else:
                 conn.commit()
-            self._score_cache.pop(engine, None)
+            # 清掉该引擎的全部缓存键（含场景分桶键），见 get_score 的缓存口径
+            for _k in [k for k in self._score_cache if k[0] == engine]:
+                self._score_cache.pop(_k, None)
 
-    def get_score(self, engine: str) -> float:
+    def _score_from_row(self, row) -> float:
+        """把一条聚合行转成 0~1 推荐分（口径见 get_score）。"""
+        total, judged, judged_ok, avg_latency, avg_cost, avg_q, sum_q, last_ts = row
+        total = int(total or 0)
+        judged = int(judged or 0)
+        if not total:
+            return 0.5
+        last_ts = float(last_ts or 0)
+        if last_ts and (time.time() - last_ts) > STALE_AFTER_SECONDS:
+            return 0.5
+        if judged == 0:
+            return 0.5
+        success_rate = (judged_ok or 0) / judged
+        latency_factor = min(1.0, 2000.0 / max(avg_latency or 2000, 1))
+        cost_factor = max(0.3, 1.0 - (avg_cost or 0.0) * 10)
+        return round(success_rate * latency_factor * cost_factor
+                     * quality_factor(avg_q, sum_q), 4)
+
+    def _global_row(self, engine: str):
+        cutoff = time.time() - WINDOW_DAYS * 86400
+        return self._connect().execute(
+            "SELECT COUNT(*), "
+            "       SUM(CASE WHEN empty = 0 THEN 1 ELSE 0 END), "
+            "       SUM(CASE WHEN empty = 0 THEN success ELSE 0 END), "
+            "       AVG(latency_ms), AVG(cost), "
+            "       AVG(quality), SUM(quality), MAX(created_at) "
+            "FROM engine_perf WHERE engine = ? AND created_at > ?",
+            (engine, cutoff),
+        ).fetchone()
+
+    def _bucket_row(self, engine: str, domain: str, lang: str):
+        cutoff = time.time() - WINDOW_DAYS * 86400
+        return self._connect().execute(
+            "SELECT COUNT(*), "
+            "       SUM(CASE WHEN empty = 0 THEN 1 ELSE 0 END), "
+            "       SUM(CASE WHEN empty = 0 THEN success ELSE 0 END), "
+            "       AVG(latency_ms), AVG(cost), "
+            "       AVG(quality), SUM(quality), MAX(created_at) "
+            "FROM engine_perf WHERE engine = ? AND created_at > ? "
+            "AND domain = ? AND lang = ?",
+            (engine, cutoff, domain, lang),
+        ).fetchone()
+
+    def get_score(self, engine: str, domain: str | None = None,
+                  lang: str | None = None) -> float:
         """获取引擎的综合推荐分数（0.0 ~ 1.0）。
 
         **只按「有明确结果」的调用算成功率**（`empty=0`）。
@@ -196,50 +297,32 @@ class AdaptiveLearner:
         openalex(0.29)、hackernews(0.10)、twitter(0.17)、open_library(0.17)。
 
         延迟与成本仍按全部调用统计——空结果也是真实开销。
+
+        **场景分桶**（2026-10-24）：给 `domain` / `lang` 时，按 (engine, domain,
+        lang) 聚合出「桶分」，与全局分加权融合（桶样本 <3 时权重 0.3，≥3 时 0.5）。
+        这让「引擎在 A 域强、B 域弱」可表达，新引擎也能在建议域里被更快识别。
+        桶为空时回退全局分——旧调用方（不传 domain/lang）行为逐位不变。
         """
+        key = (engine, domain or "", lang or "")
         now = time.time()
-        cached = self._score_cache.get(engine)
+        cached = self._score_cache.get(key)
         if cached and cached[1] > now:
             return cached[0]
 
         with self._lock:
-            cached = self._score_cache.get(engine)
+            cached = self._score_cache.get(key)
             if cached and cached[1] > now:
                 return cached[0]
-            cutoff = now - WINDOW_DAYS * 86400
-            conn = self._connect()
-            row = conn.execute(
-                "SELECT COUNT(*), "
-                "       SUM(CASE WHEN empty = 0 THEN 1 ELSE 0 END), "
-                "       SUM(CASE WHEN empty = 0 THEN success ELSE 0 END), "
-                "       AVG(latency_ms), AVG(cost), "
-                "       AVG(quality), SUM(quality), MAX(created_at) "
-                "FROM engine_perf WHERE engine = ? AND created_at > ?",
-                (engine, cutoff),
-            ).fetchone()
-        total, judged, judged_ok, avg_latency, avg_cost, avg_q, sum_q, last_ts = row
-        total = int(total or 0)
-        judged = int(judged or 0)
-        if not total:
-            score = 0.5  # 无数据时中性分
-        else:
-            # 数据过时恢复：最后一次调用距今过久 → 中性分，给恢复探测机会
-            last_ts = float(last_ts or 0)
-            if last_ts and (now - last_ts) > STALE_AFTER_SECONDS:
-                score = 0.5
-            elif judged == 0:
-                # 窗口内全是空结果：没有任何可判定健康与否的调用 → 中性分。
-                # 给中性分而不是 0：否则「每次都只是没搜到」会把源打死。
-                score = 0.5
-            else:
-                success_rate = (judged_ok or 0) / judged
-                latency_factor = min(1.0, 2000.0 / max(avg_latency or 2000, 1))
-                cost_factor = max(0.3, 1.0 - (avg_cost or 0.0) * 10)
-                q_factor = quality_factor(avg_q, sum_q)
-                score = round(success_rate * latency_factor * cost_factor
-                              * q_factor, 4)
-
-        self._score_cache[engine] = (score, now + self.SCORE_CACHE_TTL)
+            score = self._score_from_row(self._global_row(engine))
+            if domain or lang:
+                brow = self._bucket_row(engine, domain or "", lang or "")
+                b_judged = int(brow[1] or 0)
+                if b_judged > 0:
+                    b_score = self._score_from_row(brow)
+                    w = 0.5 if b_judged >= 3 else 0.3
+                    score = round((1 - w) * score + w * b_score, 4)
+
+        self._score_cache[key] = (score, now + self.SCORE_CACHE_TTL)
         return score
 
     def get_ranking(self) -> list[tuple[str, float]]: