argo-search 2.9.7 → 2.9.8

package/packages/dsh-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taxueseek/argo-dsh",
-  "version": "2.9.7",
+  "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\"",
   "license": "Apache-2.0",
   "type": "module",
@@ -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

@@ -149,6 +149,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 +237,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 +286,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

@@ -92,11 +92,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 +125,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:
@@ -152,6 +171,7 @@ class AdaptiveLearner:
         )
         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,
@@ -168,6 +188,9 @@ class AdaptiveLearner:
         """
         q = 0.0 if quality is None else max(0.0, min(1.0, float(quality)))
         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 "

package/scripts/article_meta.py

@@ -0,0 +1,131 @@
+#!/usr/bin/env python3
+"""article_meta.py — 从已抓取的 HTML 里提取文章级元数据与正文链接。
+
+为什么要单独一层（2026-10-22，对标 open-websearch 的 includeLinks/byline）：
+`readability_extract` 只交付正文文本，链接、作者、站点名、摘要这些**结构化
+线索**在提取时被丢掉。Agent 要顺着文章里的引用继续取证，只能再抓一次页面；
+研究/报告场景里作者与站点名也是引用格式的必需字段。它们都在同一份 HTML 里，
+一次解析就能拿到，不该让调用方付第二次网络往返。
+
+边界：
+  - 纯标准库 HTMLParser，毫秒级；不做正文判定（那是 readability 的职责）。
+  - 链接只取 <article>/<main> 内。没有语义容器时宁可不给，也不把
+    nav/header/footer 的导航链接当正文引用；相对链接按页面 URL 解析。
+  - 标题/摘要/站点名只读 meta，不从正文猜；猜错比缺失更糟。
+  - 全部字段都可能缺失，调用方按 key 是否存在判断，不返回空字符串占位。
+"""
+
+from __future__ import annotations
+
+from html.parser import HTMLParser
+from urllib.parse import urljoin, urlparse
+
+MAX_LINKS = 30
+MAX_TEXT = 300
+_SKIP_TAGS = {"nav", "header", "footer", "aside", "script", "style", "noscript"}
+_META_KEYS = {
+    "author": "byline",
+    "article:author": "byline",
+    "og:article:author": "byline",
+    "og:site_name": "site_name",
+    "application-name": "site_name",
+    "og:description": "excerpt",
+    "description": "excerpt",
+    "twitter:description": "excerpt",
+    "article:published_time": "published_at",
+}
+
+
+class _MetaParser(HTMLParser):
+    def __init__(self) -> None:
+        super().__init__(convert_charrefs=True)
+        self.meta: dict[str, str] = {}
+        self.article_links: list[dict[str, str]] = []
+        self._in_article = 0
+        self._skip = 0
+        self._href: str | None = None
+        self._text: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:
+        tag = tag.lower()
+        if tag == "meta":
+            data = {k.lower(): (v or "") for k, v in attrs if k}
+            key = (data.get("property") or data.get("name") or "").strip().lower()
+            value = data.get("content") or ""
+            field = _META_KEYS.get(key)
+            if field and value and field not in self.meta:
+                self.meta[field] = value.strip()[:MAX_TEXT]
+            return
+        if tag in _SKIP_TAGS:
+            self._skip += 1
+            return
+        if tag in ("article", "main"):
+            self._in_article += 1
+        elif tag == "a" and self._skip == 0:
+            href = ""
+            for k, v in attrs:
+                if k.lower() == "href" and v:
+                    href = v.strip()
+                    break
+            if href:
+                self._href = href
+                self._text = []
+
+    def handle_endtag(self, tag: str) -> None:
+        tag = tag.lower()
+        if tag in _SKIP_TAGS:
+            self._skip = max(0, self._skip - 1)
+            return
+        if tag in ("article", "main"):
+            self._in_article = max(0, self._in_article - 1)
+        elif tag == "a" and self._href is not None:
+            text = " ".join("".join(self._text).split())[:120]
+            if self._in_article:
+                self.article_links.append({"url": self._href, "text": text})
+            self._href = None
+            self._text = []
+
+    def handle_data(self, data: str) -> None:
+        if self._href is not None and self._skip == 0:
+            self._text.append(data)
+
+
+def extract_article_meta(html: str, base_url: str,
+                         max_links: int = MAX_LINKS) -> dict:
+    """返回 {byline, excerpt, site_name, published_at, links}，缺失的键不出现。
+
+    links: [{"url": 绝对 URL, "text": 锚文本}]，按出现顺序去重，最多 max_links。
+    同页锚点、javascript/mailto、非 http(s)、空文本一律丢弃。
+    """
+    if not html:
+        return {}
+    p = _MetaParser()
+    try:
+        p.feed(html)
+        p.close()
+    except Exception:
+        return {}
+    out: dict = dict(p.meta)
+    raw_links = p.article_links
+    if raw_links:
+        links: list[dict[str, str]] = []
+        seen: set[str] = set()
+        for item in raw_links:
+            href = item["url"].strip()
+            if not href or href.startswith(("#", "javascript:", "mailto:", "tel:")):
+                continue
+            url = urljoin(base_url, href)
+            if urlparse(url).scheme not in ("http", "https"):
+                continue
+            if url.split("#", 1)[0] == base_url.split("#", 1)[0]:
+                continue
+            text = item["text"]
+            if len(text) < 2 or url in seen:
+                continue
+            seen.add(url)
+            links.append({"url": url, "text": text})
+            if len(links) >= max(1, int(max_links)):
+                break
+        if links:
+            out["links"] = links
+    return out