argo-search 2.9.8 → 2.9.9

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

@@ -48,6 +48,9 @@ window.__ModuleLoader__.load({
         tabAdvanced: '高级',
         tabDashboard: '看板',
         dashboardTitle: '运行监控与健康态看板',
+        routeHealthTitle: '路由观测',
+        routeHealthHint: '最近的路由决策与引擎状态（宿主提供时显示）。',
+        routeHealthFallback: '在终端运行 `argo stats` 或 `argo engine list` 查看路由健康、引擎成功率与配额消耗。',
         dashboardHint: '实时监控常驻 MCP 连接池、上游搜索源拓扑与额度状态，提供一键预设与快速调优。',
         poolTitle: '常驻 MCP 连接池监控',
         poolStatusHealthy: '就绪（正常）',
@@ -83,6 +86,8 @@ window.__ModuleLoader__.load({
         concurrency: '并发连接数',
         toolsTitle: '原生工具',
         toolsHint: '勾选即注册为原生一等工具（CLI 单发，不依赖 MCP）。长尾工具只在需要时开，避免每轮工具面膨胀。',
+        toolPresetTitle: '推荐组合',
+        toolPresetHint: '按场景一键套用（会覆盖当前勾选）。工具分区见下方。',
         coreTools: '高频路径',
         longTools: '长尾取证',
         nativeTimeout: '单次调用超时 (ms)',
@@ -163,6 +168,9 @@ window.__ModuleLoader__.load({
         tabAdvanced: 'Advanced',
         tabDashboard: 'Dashboard',
         dashboardTitle: 'Runtime Monitoring & Health Dashboard',
+        routeHealthTitle: 'Routing telemetry',
+        routeHealthHint: 'Recent routing decisions and engine status (when provided by the host).',
+        routeHealthFallback: 'Run `argo stats` or `argo engine list` in a terminal to inspect routing health, engine success rates and quota usage.',
         dashboardHint: 'Real-time overview of the resident MCP connection pool, upstream search engine matrix, and quick workflow presets.',
         poolTitle: 'Resident MCP Pool Monitoring',
         poolStatusHealthy: 'Ready (Healthy)',
@@ -198,6 +206,8 @@ window.__ModuleLoader__.load({
         concurrency: 'Concurrent connections',
         toolsTitle: 'Native tools',
         toolsHint: 'Checked tools register as native first-class tools (single-shot CLI, no MCP). Enable long-tail tools only when needed.',
+        toolPresetTitle: 'Recommended sets',
+        toolPresetHint: 'Apply a scenario preset in one click (replaces current selection). See the grouped tools below.',
         coreTools: 'Hot path',
         longTools: 'Long tail',
         nativeTimeout: 'Per-call timeout (ms)',
@@ -259,25 +269,41 @@ window.__ModuleLoader__.load({
       },
     };
 
+    // 工具分区（场景化）：核心 / 取证 / 本地 / 长尾。
+    // 旧版只有 core/long 两组，16 个长尾工具平铺，新用户不知道该开哪些；
+    // 按使用场景分组后，配合下方「推荐组合」卡可以一键套用。
     const TOOLS = [
-      { id: 'argo_search', group: 'core', zh: '统一搜索', en: 'Unified search' },
-      { id: 'argo_fetch', group: 'core', zh: '智能抓取', en: 'Smart fetch' },
-      { id: 'argo_evidence', group: 'long', zh: '来源可信度评估', en: 'Source credibility' },
-      { id: 'argo_local_search', group: 'long', zh: '本机文件搜索', en: 'Local file search' },
-      { id: 'argo_local_read', group: 'long', zh: '本机文件读取', en: 'Local file read' },
-      { id: 'argo_recompute', group: 'long', zh: '可复算执行器', en: 'Recompute' },
-      { id: 'argo_clarify', group: 'long', zh: '意图消歧', en: 'Intent clarification' },
-      { id: 'argo_crawl', group: 'long', zh: '站点级爬取', en: 'Site crawl' },
-      { id: 'argo_social_search', group: 'long', zh: '社交平台搜索', en: 'Social search' },
-      { id: 'argo_article', group: 'long', zh: '公众号全文', en: 'WeChat article' },
-      { id: 'argo_job', group: 'long', zh: '招聘聚合', en: 'Job aggregation' },
-      { id: 'argo_extract', group: 'long', zh: '结构化提取', en: 'Structured extract' },
-      { id: 'argo_preflight', group: 'long', zh: '批量 URL 预检', en: 'URL preflight' },
-      { id: 'argo_pdf', group: 'long', zh: 'PDF 提取', en: 'PDF extract' },
-      { id: 'argo_screenshot', group: 'long', zh: '网页截图', en: 'Screenshot' },
-      { id: 'argo_answer', group: 'long', zh: '带引用直答', en: 'Cited answer' },
-      { id: 'argo_watch', group: 'long', zh: '网页变化监控', en: 'Page watch' },
-      { id: 'argo_cite', group: 'long', zh: 'DOI 引用生成', en: 'DOI citation' },
+      { id: 'argo_search', group: 'core', zh: '统一搜索', en: 'Unified search', sceneZh: '日常一问的首选', sceneEn: 'Default for everyday queries' },
+      { id: 'argo_fetch', group: 'core', zh: '智能抓取', en: 'Smart fetch', sceneZh: '读某个具体页面', sceneEn: 'Read a specific page' },
+      { id: 'argo_evidence', group: 'forensics', zh: '来源可信度评估', en: 'Source credibility', sceneZh: '高后果问题的证据分级', sceneEn: 'Grade evidence for high-stakes answers' },
+      { id: 'argo_clarify', group: 'forensics', zh: '意图消歧', en: 'Intent clarification', sceneZh: '查询有歧义时先消歧', sceneEn: 'Disambiguate an ambiguous query' },
+      { id: 'argo_crawl', group: 'forensics', zh: '站点级爬取', en: 'Site crawl', sceneZh: '整站/多页采集', sceneEn: 'Site-level or multi-page collection' },
+      { id: 'argo_extract', group: 'forensics', zh: '结构化提取', en: 'Structured extract', sceneZh: '从页面抽表格/字段', sceneEn: 'Extract tables/fields from a page' },
+      { id: 'argo_pdf', group: 'forensics', zh: 'PDF 提取', en: 'PDF extract', sceneZh: '读 PDF 正文', sceneEn: 'Read PDF text' },
+      { id: 'argo_screenshot', group: 'forensics', zh: '网页截图', en: 'Screenshot', sceneZh: '取证留档/看渲染结果', sceneEn: 'Archive or inspect a rendered page' },
+      { id: 'argo_article', group: 'forensics', zh: '公众号全文', en: 'WeChat article', sceneZh: '读公众号文章正文', sceneEn: 'Read a WeChat article' },
+      { id: 'argo_local_search', group: 'local', zh: '本机文件搜索', en: 'Local file search', sceneZh: '搜本机笔记/代码', sceneEn: 'Search local notes/code' },
+      { id: 'argo_local_read', group: 'local', zh: '本机文件读取', en: 'Local file read', sceneZh: '读本机文件', sceneEn: 'Read a local file' },
+      { id: 'argo_recompute', group: 'local', zh: '可复算执行器', en: 'Recompute', sceneZh: '本地可复算任务（需授权）', sceneEn: 'Local recompute (needs authorization)' },
+      { id: 'argo_social_search', group: 'longtail', zh: '社交平台搜索', en: 'Social search', sceneZh: '舆情/UGC 采集', sceneEn: 'Sentiment / UGC collection' },
+      { id: 'argo_job', group: 'longtail', zh: '招聘聚合', en: 'Job aggregation', sceneZh: '招聘/岗位聚合', sceneEn: 'Job aggregation' },
+      { id: 'argo_preflight', group: 'longtail', zh: '批量 URL 预检', en: 'URL preflight', sceneZh: '批量检查 URL 可达性', sceneEn: 'Batch-check URL reachability' },
+      { id: 'argo_answer', group: 'longtail', zh: '带引用直答', en: 'Cited answer', sceneZh: '在给定语料里直答', sceneEn: 'Answer from a given corpus' },
+      { id: 'argo_watch', group: 'longtail', zh: '网页变化监控', en: 'Page watch', sceneZh: '盯页面变化', sceneEn: 'Watch a page for changes' },
+      { id: 'argo_cite', group: 'longtail', zh: 'DOI 引用生成', en: 'DOI citation', sceneZh: '生成引用条目', sceneEn: 'Generate a citation' },
+    ];
+
+    // 分区展示名 + 推荐组合（场景化，让用户一键套用而不是逐个勾选）
+    const TOOL_GROUPS = [
+      { id: 'core', zh: '高频路径', en: 'Hot path' },
+      { id: 'forensics', zh: '取证与核验', en: 'Forensics' },
+      { id: 'local', zh: '本机', en: 'Local' },
+      { id: 'longtail', zh: '长尾', en: 'Long tail' },
+    ];
+    const TOOL_PRESETS = [
+      { id: 'daily', zh: '日常', en: 'Daily', tools: ['argo_search', 'argo_fetch'], descZh: '一问一搜，最快', descEn: 'Fastest for simple queries' },
+      { id: 'research', zh: '研究', en: 'Research', tools: ['argo_search', 'argo_fetch', 'argo_evidence', 'argo_clarify'], descZh: '加证据分级与消歧', descEn: 'Add evidence grading + disambiguation' },
+      { id: 'forensics', zh: '取证', en: 'Forensics', tools: ['argo_search', 'argo_fetch', 'argo_crawl', 'argo_pdf', 'argo_screenshot', 'argo_extract'], descZh: '整站/多页/PDF 留档', descEn: 'Site/multi-page/PDF archiving' },
     ];
 
     const KEYS = [
@@ -617,6 +643,8 @@ window.__ModuleLoader__.load({
       const [envBusy, setEnvBusy] = useState('');
       const [engineFilter, setEngineFilter] = useState('');
       const [keyFilter, setKeyFilter] = useState('');
+      // 路由观测（宿主经 remote 事件推送；无推送时卡片显示终端命令提示）
+      const [routeHealth, setRouteHealth] = useState(null);
 
       const dirty = useRef(new Set());
       // 读-改-写共享配置字段（keyRefs / nativeTools / argoEnv）时读实时快照，
@@ -672,10 +700,14 @@ window.__ModuleLoader__.load({
       useEffect(() => {
         if (props.view === 'summary') return undefined;
         void refreshCredentials();
-        const off = props.remote && typeof props.remote.$on === 'function'
-          ? props.remote.$on('credentials/reference-updated', () => { void refreshCredentials(); })
-          : undefined;
-        return typeof off === 'function' ? off : undefined;
+        const offs = [];
+        if (props.remote && typeof props.remote.$on === 'function') {
+          const offCreds = props.remote.$on('credentials/reference-updated', () => { void refreshCredentials(); });
+          const offRoute = props.remote.$on('route-health/updated', (data) => { setRouteHealth(data); });
+          if (typeof offCreds === 'function') offs.push(offCreds);
+          if (typeof offRoute === 'function') offs.push(offRoute);
+        }
+        return () => { for (const off of offs) off(); };
       }, [state]);
 
       const edit = (key, text) => {
@@ -778,6 +810,14 @@ window.__ModuleLoader__.load({
         void setField('nativeTools', ordered);
       };
 
+      // 推荐组合：一键套用一组工具（场景化分区之上的快捷入口）。
+      // 只增不减会覆盖用户已有勾选，所以是「设为这组」而非「追加这组」。
+      const applyToolPreset = async (tools) => {
+        const ordered = TOOLS.map((tool) => tool.id).filter((toolId) => tools.includes(toolId));
+        for (const extra of tools) if (!ordered.includes(extra)) ordered.push(extra);
+        await props.set('nativeTools', ordered);
+      };
+
       const saveKey = async (ref) => {
         const key = asString(keyDraft[ref]).trim();
         if (!key || !props.credentials) return;
@@ -975,8 +1015,8 @@ window.__ModuleLoader__.load({
         ? h('p', { style: error ? S.error : S.notice, role: 'status' }, message)
         : h('p', { style: S.status }, disabled ? t('readonly') : '');
 
-      const coreTools = TOOLS.filter((tool) => tool.group === 'core');
-      const longTools = TOOLS.filter((tool) => tool.group === 'long');
+      // 按 TOOL_GROUPS 顺序分组渲染（场景化分区，替代旧的 core/long 两分）
+      const toolsByGroup = (gid) => TOOLS.filter((tool) => tool.group === gid);
       const toolCheckbox = (tool) => h('label', { key: tool.id, style: S.check }, [
         h('input', {
           key: 'i',
@@ -1100,6 +1140,19 @@ window.__ModuleLoader__.load({
           ]),
         ]));
 
+        // 路由观测卡：宿主经 remote 事件推送 routeHealth 时展示最近路由决策；
+        // 未推送时给出终端命令提示——不让面板空白，也不假装有数据。
+        panel.push(h(Card, { key: 'route', title: t('routeHealthTitle'), hint: t('routeHealthHint') }, [
+          routeHealth && Array.isArray(routeHealth.samples) && routeHealth.samples.length > 0
+            ? h('div', { key: 'rows', style: { display: 'flex', flexDirection: 'column', gap: 6 } },
+                routeHealth.samples.slice(0, 5).map((row, i) =>
+                  h('div', { key: 'r' + i, style: S.keyRow }, [
+                    h('span', { key: 'q', style: S.label }, String(row.query || '').slice(0, 40)),
+                    h('span', { key: 'd', style: S.sub }, `${row.domain || '-'} · ${row.engine || '-'}`),
+                  ])))
+            : h('p', { key: 'hint', style: S.hint }, t('routeHealthFallback')),
+        ]));
+
         panel.push(h(Card, { key: 'presets', title: t('presetTitle'), hint: t('presetHint') }, [
           h('div', { key: 'grid', style: S.presetGrid }, [
             h('div', {
@@ -1219,15 +1272,27 @@ window.__ModuleLoader__.load({
       }
 
       if (tab === 'tools') {
+        panel.push(h(Card, { key: 'presets', title: t('toolPresetTitle'), hint: t('toolPresetHint') }, [
+          h('div', { key: 'grid', style: S.presetGrid }, TOOL_PRESETS.map((preset) =>
+            h('button', {
+              key: preset.id, type: 'button', disabled,
+              style: S.presetCard(false),
+              onClick: () => { void applyToolPreset(preset.tools); },
+            }, [
+              h('div', { key: 't', style: { display: 'flex', alignItems: 'center', justifyContent: 'space-between' } }, [
+                h('span', { key: 'title', style: S.label }, lang === 'en' ? preset.en : preset.zh),
+                h('span', { key: 'badge', style: S.badge('blue') }, String(preset.tools.length) + ' 工具'),
+              ]),
+              h('span', { key: 'd', style: S.sub }, lang === 'en' ? preset.descEn : preset.descZh),
+            ]))),
+        ]));
         panel.push(h(Card, { key: 'tools', title: t('toolsTitle'), hint: t('toolsHint') }, [
-          h('div', { key: 'core', style: { display: 'flex', flexDirection: 'column', gap: 4 } }, [
-            h('span', { key: 'l', style: S.label }, t('coreTools')),
-            h('div', { key: 'g', style: S.toolGrid }, coreTools.map(toolCheckbox)),
-          ]),
-          h('div', { key: 'div', style: S.divider }),
-          h('div', { key: 'long', style: { display: 'flex', flexDirection: 'column', gap: 4 } }, [
-            h('span', { key: 'l', style: S.label }, t('longTools')),
-            h('div', { key: 'g', style: S.toolGrid }, longTools.map(toolCheckbox)),
+          ...TOOL_GROUPS.map((grp, gi) => [
+            gi > 0 ? h('div', { key: 'div' + gi, style: S.divider }) : null,
+            h('div', { key: grp.id, style: { display: 'flex', flexDirection: 'column', gap: 4 } }, [
+              h('span', { key: 'l', style: S.label }, lang === 'en' ? grp.en : grp.zh),
+              h('div', { key: 'g', style: S.toolGrid }, toolsByGroup(grp.id).map(toolCheckbox)),
+            ]),
           ]),
           h('div', { key: 'g2', style: S.grid }, [
             h(NumberField, {
@@ -1526,6 +1591,7 @@ window.__ModuleLoader__.load({
     // 生成产物）同名同集合，ENGINE_TOGGLES 必须与 index.js 的 ARGO_ENV_SPECS
     // 同名同集合——两边任何一边增删而另一边没跟上，测试即红。
     exports.TOOLS = TOOLS;
+    exports.TOOL_GROUPS = TOOL_GROUPS;
     exports.ENGINE_TOGGLES = ENGINE_TOGGLES;
 
     return module.exports;

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

@@ -5,6 +5,49 @@
  * 避免状态探查逻辑与核心检索逻辑耦合。
  */
 
+import { existsSync, readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/**
+ * 读 argo 的本地使用日志，汇总成「路由观测」卡片数据。
+ *
+ * 数据来源与 stats_cli.py / usage_log.py 同一处（<state>/usage_log/*.jsonl），
+ * 只读、不写、不出本机。argo 未运行过（无日志）时返回 { samples: [] }，
+ * 面板据此显示终端命令提示——不假装有数据。
+ *
+ * @param {string} [stateDir] - argo 状态目录；缺省用 ARGO_STATE_DIR 或平台惯例
+ * @param {number} [limit] - 最近几条
+ */
+export function getRouteHealth(stateDir, limit = 10) {
+  const dir = stateDir
+    || process.env.ARGO_STATE_DIR
+    || join(homedir(), '.cache', 'unified-search')
+  const samples = []
+  try {
+    const routePath = join(dir, 'usage_log', 'route.jsonl')
+    if (existsSync(routePath)) {
+      const lines = readFileSync(routePath, 'utf8').split('\n').filter(Boolean)
+      for (const line of lines.slice(-limit)) {
+        try {
+          const row = JSON.parse(line)
+          if (row && typeof row === 'object') {
+            samples.push({
+              query: row.query || row.original_query || '',
+              engine: row.engine || (row.decision && row.decision.engine) || '',
+              domain: row.domain || (row.decision && row.decision.domain) || '',
+              confidence: row.confidence || (row.decision && row.decision.confidence) || '',
+              reason: row.reason || (row.decision && row.decision.reason) || '',
+              ts: row.ts || row.timestamp || '',
+            })
+          }
+        } catch { /* 单行坏数据不影响其余 */ }
+      }
+    }
+  } catch { /* 读不到就空 */ }
+  return { samples, source: 'usage_log/route.jsonl', stateDir: dir }
+}
+
 /**
  * 获取当前常驻 MCP 连接池的运行时指标。
  *

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

@@ -62,6 +62,7 @@ import {
 import {
   getMcpPoolStats,
   resetMcpPool,
+  getRouteHealth,
 } from './diagnostics.js'
 
 /**
@@ -450,6 +451,18 @@ export function apply(ctx, providedConfig = {}) {
   }
 
   const nativeRegistrations = new Map()
+  // 路由观测推送：原生工具执行后读 argo 使用日志，经 remote 事件推给设置面板。
+  // 失败静默（诊断是增值，不是依赖）；无 remote 事件总线时跳过。
+  const emitRouteHealth = () => {
+    try {
+      if (!ctx.remote || typeof ctx.remote.$emit !== 'function') return
+      const data = getRouteHealth()
+      if (Array.isArray(data.samples) && data.samples.length > 0) {
+        ctx.remote.$emit('route-health/updated', data)
+      }
+    } catch { /* ignore */ }
+  }
+
   const syncNativeTools = () => {
     const desired = asStringArray(config.nativeTools, 20)
     for (const [kind, dispose] of nativeRegistrations) {
@@ -459,7 +472,16 @@ export function apply(ctx, providedConfig = {}) {
     }
     for (const kind of desired) {
       if (nativeRegistrations.has(kind)) continue
-      nativeRegistrations.set(kind, ctx.tools.register(makeNativeTool(config, kind)))
+      const tool = makeNativeTool(config, kind)
+      const originalExecute = tool.execute
+      if (typeof originalExecute === 'function') {
+        tool.execute = async (args, exec) => {
+          const result = await originalExecute(args, exec)
+          emitRouteHealth()
+          return result
+        }
+      }
+      nativeRegistrations.set(kind, ctx.tools.register(tool))
     }
   }
   syncNativeTools()

package/packages/dsh-plugin/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@taxueseek/argo-dsh",
-  "version": "2.9.8",
-  "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",

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}`)
   }
 })
 

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:
     """自适应学习引擎：追踪引擎表现并输出推荐分数。"""
 
@@ -166,18 +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 保持旧调用方行为不变。
 
@@ -187,6 +217,8 @@ 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()
@@ -194,18 +226,64 @@ class AdaptiveLearner:
             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`）。
@@ -219,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]]: