argo-search 1.0.1 → 2.9.7

package/docs/RELEASE_NOTES_v2.8.6.md

@@ -0,0 +1,66 @@
+# Argo v2.8.6 发布说明
+
+**版本**：2.8.6（相对 2.8.5）
+**日期**：2026-09-07
+**主题**：搜索更快更准、长尾拖尾大幅收敛；知乎三源语义分工并解锁全部额度；新源接入从「改多处配置」变成「声明一次」，死源由门禁自动显形。
+
+## 主要改进
+
+### 1. 搜索速度
+
+- **首引擎宽限窗竞速（hedged racing）**：主引擎 2 秒宽限窗内出结果且合格 → 只付 1 次调用（旧竞速固定双发，成本回退消除）；窗内未完成才补发次引擎并行赛跑，先合格者赢。被弃置的慢线程改为 daemon 管理，CLI 单发不再被拖住退出。
+- **地理查询拖尾 −56%**（12.4s→5.5s）：OSM 的 6s 超时声明此前是死配置（被调用方超时整体覆盖 + YAML 同名键静默覆盖 + 引擎内重试翻倍，三层叠加），修复后为硬上限；引擎内连接级重试移除，重试语义上移到编排层（换引擎/熔断/救援链各司其职）。
+- **fast 模式 6 秒总墙钟预算对并行路径同样生效**：deadline 之后不再起新引擎、等待窗口按剩余预算收口，与串行路径同语义。
+
+### 2. 准确率
+
+- **live 多语言金标命中率 69%→100%**，此后连续多轮保持 100%（域命中/选择命中/零污染）：实体型引擎查询规范化——剥疑问前缀与属性词（「NASA founding year」→「NASA」），中文无空格连写同样覆盖（「周杰伦专辑」→「周杰伦」）。
+- **面查意图守卫 + 同构垃圾检测**：「pnpm file: dependency 重装问题」这类长主题句不再被 pypi/models_dev 词面误抢返回垃圾包；单 token 包名垃圾结果不再骗过早停守卫。
+- **中文正则词边界修复**（两处同根因）：`\b` 对 CJK 永不成立，「npm安装报错」这类连写意图词失配导致真实点查被误让位——中文备选统一移出词边界组。
+
+### 3. 搜索源利用率
+
+- **知乎三源语义分工**（一个 ZHIHU_ACCESS_SECRET 撬动 10500 次/天）：
+  - **站内搜索**（5000/天）：观点/经验/评测 UGC——配额此前按 1000/天误配，用到 20% 就被本地封禁，已对齐；
+  - **全网搜索**（5000/天）：中文时事/多域名泛资讯——此前因自适应降权 + 预算截断在自家主域永远轮不上（37 天仅 53 次），已修复防饿死并接入新闻域；
+  - **个人数据**（10000/天，新增）：本人创作内容/收藏/关注，`我的回答 点赞最多`、`我的收藏`、`我关注的人` 直接可查——查本人数据用 Access Secret 直调，无需 OAuth。
+- **UAPI 聚合搜索重新启用**（免 key，历史 521 次 0% 错误）；**DuckDuckGo 移出兜底链**（错误率 45%、实测 11 秒 0 条），UAPI 顶入。
+- **研究采集按子查询语言/学术意图分发**：中英混合研究的引擎参战数 2→13（英文源与 github 等全面参与）；学术查询按《学术检索协议》顺序接入 17 个学术源（Semantic Scholar 起步 → arXiv 补预印本 → openalex/crossref → Google Scholar 兜底）。
+- **密钥兼容同步**：`~/.config/argo/env` 在 CLI/MCP 入口单向同步进环境变量（只填缺失、不覆盖已有）——裸 shell、直跑进程、其他 Agent 集成的既有密钥读取方式零改动，未配环境变量的部署也能拿到密钥。
+
+### 4. 新能力
+
+- **zhihu_user 个人数据引擎**（新能力族 personal_data）：创作运营与素材回溯；互补回填排除——通用搜索 combo 永不混入个人收藏。
+- **声明式语言分发**：引擎语言能力（langs）进元数据，路由的语言重排/ja-ko 过滤由元数据派生（原四张手写冻结表删除）；`family_candidates(能力族, 语言, 模式)` 单一取源口。新源接入 = 注册 + 声明族与语言一次，全部分发路径自动生效。
+- **可达性门（WARN）**：enabled 引擎必须被 ≥1 条分发路径可达（域 combo / 兜底 / 选题 profile / 研究 boost / TF-IDF 语义画像），当前 8 个死源已显形待逐源接线。
+- **学术检索协议**（`references/academic-query.md`）：17 学术源查询构造、多库去重、相关性五因子排序、引用网络挖掘、18 条反模式、与证据体系（事实/推断/未知）对齐。
+- **配额口径对齐**：zhihu 5000/天、anysearch 2000/天、zhihu_global 5000/天；无限额引擎的计数周期归零（遥测不再永久累计）。
+- **小红书 REDSkill 技能检索域**：47650 个技能的全量检索与榜单（数据本地缓存）。
+
+### 5. 修复与加固
+
+- **YAML 同名键静默覆盖**：引擎块内 `timeout` 重复声明导致 6s 硬超时从未生效——新增 `test_config_dup_keys` 门，config 与 specs 全量拒绝重复键。
+- **hedged 竞速超时路径丢结果**：恰在末次轮询后完成的线程此前既不入账也不标超时（静默消失）；超时记账由「超时参数×1000」假值改为真实等待时长（遥测诚实化）。
+- **跨平台与安全加固**：Windows GBK 编码乱码修复（curl/mcp-jobs/子进程显式 UTF-8）；SSRF 重定向每一跳校验（起始白名单挡不住服务端 302 跳内网）；recompute 沙箱补封 os.open/os.fdopen 与 Path/bytes 开口；任务快照原子写；`--force` link 迁移前加副本软校验。
+- **SKILL.md 分层按需读取**：稳态 token 开销 −52%。
+
+## 默认关闭功能的打开方式
+
+- **MCP 14 工具**：默认关闭。DSH 用户在 profile patch 取消 `mcp-argo` 段注释后重启生效；非 DSH 用户见 README「MCP 接入」。
+- **原生一等工具**：默认仅 `argo_search`/`argo_fetch`；`nativeTools` 配置可按需启用全部 13 个（`argo_research` 除外——分钟级编排不适合 60s 单发超时）。
+- **TinyFish / Firecrawl**：配置 `TINYFISH_API_KEY` / `FIRECRAWL_API_KEY` 即启用（Firecrawl 匿名免费层当前已被上游限制，需注册 key）。
+- **recompute 数值重算器**：默认 fail-closed，`--allow-recompute` 或 `ARGO_ALLOW_RECOMPUTE=1` 显式授权。
+
+## 相关依赖
+
+- 无新增强制依赖；Python 3.10+，可选 `yaml/requests`（安装脚本自动选解释器）。
+- 引擎密钥统一走 `~/.config/argo/env`（600 权限）或环境变量；zhihu 系四引擎共用 `ZHIHU_ACCESS_SECRET`。
+- 已知环境级事实：iTunes cn storefront 接口当前上游返回空（media 域由 musicbrainz 兜底）；Nominatim 在部分网络不可达（geo 域由 wikidata/zh_wikipedia/anysearch 兜底，OSM 超时已收紧至 6s）。
+
+## 升级
+
+```bash
+npx github:taxueseek/argo        # 或 install.sh / install.ps1
+```
+
+无破坏性配置变更；引擎 `langs` 声明为可选项。DSH 插件用户随插件包升级自动生效。

package/docs/RELEASE_NOTES_v2.8.7.md

@@ -0,0 +1,65 @@
+# RELEASE_NOTES_v2.8.7
+
+相对 v2.8.6 的改进：搜索源 168 → 218（+50，其中 184 个免配置开箱可用），业务域 72 → 89；抓取链新增三条「拿正文」的直出通道；修掉一批真实场景里会空手而归、答非所问或整串失效的问题。
+
+## 新增能力：50 个数据源（全部免密钥或免费档）
+
+- **金融财经**：美股筛选 Finviz + Seeking Alpha、SEC EDGAR 官方申报文件全文、基金数据东方财富、宏观时序 FRED、世界银行 300+ 国家指标、欧盟统计局、国家统计局 nbs_stats、实时汇率 fx_rate、财联社电报 + 金十快讯、东财全球资讯、同花顺热点、巨潮资讯公告与研报。
+- **法律法规**（此前只有裁判文书，缺法条本身）：国家法律法规数据库 flk_law——问「民法典第 X 条」直接出官方条文；日本 e-Gov 法令、韩国法令检索；gov_regulations 补部门规章层。
+- **标准与合规**：全国标准信息平台 std_samr + openstd 全文预览——问「数据安全 国标」「GB/T 45577」不再只能翻网页。
+- **安全情报**：NVD 漏洞库 + crt.sh 证书透明度（子域名/钓鱼域情报）+ deps.dev 包依赖健康——「log4j 漏洞 CVSS 多少」「npm express 有没有已知风险」直查官方。
+- **学术科研**：OpenAlex、EuropePMC、OpenReview、bioRxiv、Semantic Scholar、DataCite + Zenodo 数据集、Google Patents 专利、PubMed/临床试验/药品标签（ClinicalTrials/OpenFDA）、化学 PubChem、蛋白 UniProt + RCSB PDB、物种 GBIF + OBIS。
+- **新闻舆情**：人民网、Google News RSS（多语言 + 时间窗 + site: 限定）、GDELT 全球事件库、知乎热榜免密钥通道（不再占开放平台配额）。
+- **生活文娱**：豆瓣电影、Bangumi 番剧、网易云音乐、Met Museum 藏品、NASA 图像库、Steam 游戏、汉典字源、维基文库古文、少数派、微信读书。
+- **能源/交通/空间**：电网发电结构与碳强度、航空气象 METAR、NOAA 空间天气、卫星轨道、共享单车 GBFS、NHTSA 车辆命名本体、USDA 土壤农业。
+- **其他**：预测市场 Polymarket、加密货币 CoinGecko、Hugging Face 模型库、Docker Hub、Openverse 开放版权图库、OpenCorporates 全球公司注册、UN Comtrade 双边贸易、WHO 公共卫生通报。
+- **twitter_syndication**：推文内容的合规直出通道。
+
+## 抓取链新增三条直出通道（自动生效，无需配置）
+
+- **站点根 `/llms.txt` 探测**：llms.txt 是站点为 AI 准备的自述索引（头部文档站采用中），抓文档站首页时自动探测命中。
+- **页面 `.md` 直出**：开发者文档站页面 URL 加 `.md` 即返回 markdown 正文，命中即跳过整条反爬链。
+- **r.jina.ai 阅读器级**：HTTP 直连和 TLS 指纹伪造都失败时，自动改走 jina 免费层（远端 JS 渲染转 markdown），省掉浏览器冷启动。只对公网 URL 生效，失败静默降级 Wayback/浏览器。
+
+## 既有能力升级
+
+- **stackexchange 引擎**：StackExchange 官方 API 一套接 180+ 问答站（此前 stackoverflow 引擎已支持 `site:` 站点族语法，行为不变）；编程问题类查询自动带上，匿名 300/天/IP，免费 key 可提额 10,000/天。
+- **doi 引擎**：DOI 号直出结构化论文元数据（CSL JSON），免 key 免限次，`argo search "10.1145/xxx" --engine doi`。
+- **知乎三源分工**：站内搜索 / 全网搜 / 个人数据（本人创作/收藏）三路语义分离，防饿死。
+- **hedged 竞速**：慢源不再拖垮整体延迟。
+- **路由依据可观测**：搜索输出新增 `route_reason` 讲清「为什么路由到这里」；不再报与实际执行无关的候选分。
+- **Agent 消费档 `--fields agent`**：单次输出约 3.7KB（原 15KB），fetch_required 纪律字段保留。
+- **本地搜索融合升级**：local-search 子技能接入主仓 RRF 融合与跨引擎去重，「同位次同分」退化修复。
+
+## 框架修复
+
+- **`--engine "a,b,c"` 逗号多引擎修复**：此前整串失效报「未知引擎」，现与 `--list-engines` 同口径拆分。
+- **宏观数据域零结果修复**：「中国 2025 年 GDP 总量」类查询此前 0 结果收场；现在中国宏观查询由国家统计局前置（世界银行有 1-2 年数据滞后），全域零结果时恢复链自动用域声明兜底源补搜，救援引擎如实记入 engines_used。
+- **HTTP 重定向中文修复**：部分站点 301 的 Location 带未编码中文（如汉典），二次请求不再报错。
+- **TimeoutError 跨 Python 版本兼容**（3.9–3.14）；深度补搜的配额记账修正。
+- **seek（本地文件搜索）降级链修复**：缺 rg 时正确落 grep，不再把「工具缺失」伪装成「没有结果」。
+- **URL 归一化单一真源**：子技能与主仓共用一套规则，跨源去重不再发散。
+- **失败显式化**：上游超时/被墙/欠费分型上报，不再「静默空结果」。
+
+## 质量体系（本版起内置的回归门禁）
+
+- 排序金标度量（MRR/nDCG 地板锁死）+ 融合增益消融门禁：多引擎融合相对最强单引擎的增益可量化（实测 +0.09 nDCG），排序改动「变好还是变坏」有数字可查。
+- 路由负向控制矩阵：泛查询（做菜/健身/园艺）不得误入行情/漏洞/影视等垂直源。
+- 上下文字节预算门禁覆盖主文档与全部子技能；可达性门 + 休眠台账防「新源接线了但永远选不中」。
+
+## 默认关闭功能的打开方式
+
+- **TinyFish 三引擎**（网页/新闻/论文，免费不限次）：配置 `ARGO_TINYFISH_API_KEY`（agent.tinyfish.ai/api-keys 申请）后 `--engine tinyfish[/_news/_paper]` 显式调用——设计上不进自动路由，护免费层。
+- **jina 阅读器级**：默认开，`ARGO_FETCH_JINA=0` 关；`.md`/llms.txt 探测 `ARGO_FETCH_MD_VARIANT=0` 关。
+- **stackexchange 提额**：免费注册 key 后在 engines/specs/stackexchange.yaml 的 extra_params 加 `key: "{ARGO_STACKEXCHANGE_API_KEY}"`。
+- **专业搜索模式**（浏览器态子技能 ego-search）：默认关，需用户明确要求并执行开启指令。
+- **Agent 消费档**：`argo search "..." --json --no-envelope --fields agent`。
+
+## 相关依赖与已知边界
+
+- 无新增第三方依赖（TLS 指纹伪造与 Chrome CDP 为可选增强，缺失自动降级）。
+- r.jina.ai 免费层有速率限制，只代理公网 URL；对 Cloudflare 人机验证页无能为力，会正确升级浏览器层。
+- stackexchange 匿名 300/天/IP 与全站共享（只作补位）；firecrawl 免费层 1000 credits/月（日常只当兜底）。
+- reddit 内容需浏览器态（对非浏览器 UA/IP 返回 403）。
+- FRED 上游偶发读超时（网络环境相关），恢复链自动换源补位。
+- HKEXnews（港股公告）未收录：服务端已停返回数据，待恢复后单独立项。

package/docs/RELEASE_NOTES_v2.8.8.md

@@ -0,0 +1,67 @@
+# RELEASE_NOTES_v2.8.8
+
+相对 v2.8.7 的改进：修复两个真实用户报告的问题——按文档推荐名配置密钥后引擎静默失效（issue #12）、抓取链不走代理导致需代理站点必然失败（issue #13）；搜索源 218 → 232（免配置开箱 184 → 194）、领域 89 → 90；冷启动与热路径全面提速（命令冷启动 2.1s → 0.55s）；Windows / Linux / macOS 三平台惯例路径适配，支持 Python 3.9；新增「直答」与「网页观察」两个子命令。
+
+## 致谢
+
+- @adamqeqj003-dotcom：#12 提供了完整的根因分析与修复方案（本版采纳其方案 1，并按其影响面提示完成全量排查）；#13 提供了定位准确的报告与修复建议。
+
+## 修复（以前不行、现在能行）
+
+- **密钥别名静默失效（#12）**：以前，按文档推荐的新名（如 `ARGO_EXA_API_KEY`）配置密钥，状态显示就绪、引擎却永远返回 0 条且不报错——用户会怀疑自己的密钥有问题。根因是部分专用引擎只认不带前缀的旧名，状态层与执行层各说各话。现在 16 处同类读取全部统一走别名链，推荐名/旧名任一就绪都出结果，缺 key 显式报错；新增源码级一致性门禁防复发。
+- **抓取链不走代理（#13）**：以前，需要代理才能访问的站点（如 GitHub 网页）抓取必然挂满 60 秒预算后失败，且显式设置 `HTTP_PROXY`/`HTTPS_PROXY` 也不生效。现在新增统一出口调度层：`ARGO_PROXY` 环境变量、config 按域规则、标准代理环境变量三条路都生效，`NO_PROXY` 全程尊重；GitHub 网页抓取实测成功。
+- **env 文件缓存错位会让密钥永久失效**：多进程并发读写 `~/.config/argo/env` 时，缓存指纹与文件内容可能错位，之后每次读取都拿到旧内容——表现为刚配好的密钥「怎么改都不生效」。现在缓存与签名绑定，错位自动回源重读。
+- **URL 缓存返回截短正文**：以前同一 URL 先抓过一次小配额，之后再要更大配额时会直接拿到缓存的截短版。现在缓存记录抓取时的上限，请求更大时自动回源。
+- **一批会在真实环境触发的缺陷**：未定义名 `Any`（4 处，特定路径一跑就 NameError）、字典重复键（静默覆盖）、Windows 下内容指纹与文件锁行为差异、`migrate_legacy_state` 在无终端环境卡住等——共 9 处，均有对应回归测试。
+
+## 更快（每次查询省下的时间）
+
+- **命令冷启动 2.1s → 0.55s**：以前每次 CLI 调用都要在 import 阶段全量加载配置，现在配置按需加载；剩余固定开销也从 0.85s → 0.16s。对「每次提问都要起一个进程」的 Agent 场景，这是每问一次都省下的时间。
+- **配置跨进程缓存 50–82ms → 16–18ms**：同一份 config.yaml 反复读盘解析改为带指纹的进程间复用。
+- **让超时真正生效**：抽出有界并发模块——以前并发源超时后线程还挂着占位，现在到点即收；精排（rerank）端点连续失败自动熔断，不再每查一次都等它超时。
+- **QPP 平坦分早停**：查询信号分布尖锐（结果质量可预期）时允许提前停止补查，省下预算；分布平坦或结果数压线时拒绝早停，宁多勿漏。
+- **预算账单直接可见**：每次搜索输出自带 `timing` 各阶段耗时与 `timing.budget`（用了多少/总共多少），慢在哪不用再猜；`--explain-timing` 保留为别名。不想要用 `--no-timing`。
+- **`--list-engines --detail` 输出 152KB → 51KB**：无过滤时走瘦身投影（剥离嵌套诊断字段），查单个引擎用 `--engine <名>` 仍给全量诊断。
+
+## 新增能力
+
+- **搜索源 218 → 232，免配置开箱 184 → 194**（全部免密钥，接线走加槽不挤既有源）：
+  - 国内热榜与生活：`weibo_hot` 微博热搜、`douyin_hot` 抖音热榜、`csdn` 技术社区、`wallstreetcn` 华尔街见闻快讯、`weather_cn` 中国天气网（城市实况）
+  - 安全与法规：`osv` 按包名查漏洞及影响版本、`cisa_kev` 已知在野利用漏洞（修复优先级最高档）、`federal_register` 美国行政法规原文
+  - 学术开放获取：`unpaywall` 论文合法免费全文定位、`opencitations` 引用图谱溯源
+  - 技能目录：`skillsmp` / `clawhub`——「找 skill」原生可查，不必再开浏览器
+  - Agent 搜索：`parallel_free`（Parallel 免费端点，长摘录自带正文）、`seltz`（注册赠 2 万次，响应自带正文摘录）
+- **69 个引擎补归类，`web_general` 兜底占比 41% → 20%**：以前大量专用源因未归类被静默丢进通用搜索兜底——查「SEC 监管文件」掉进 `bocha+anysearch`，现在直达 `sec_edgar`；新增 `security` 领域（组件漏洞 ≠ 库用法，两种问题两种路由）；中文语义词补齐（「预印本」「CVE 漏洞」这类自然问法此前一个域都命中不了）。
+- **`argo answer`**：直答——带引用的合成答案（Seltz 通道），置信口径=引用数+唯一域名数，上游不造模拟分数。
+- **`argo watch`**：网页观察模式——本地快照 + 内容指纹变化检测，抓取失败不伪造结果；`argo watch check --json` 可直接挂 cron。
+- **CLI 与 MCP 工具面对齐**：`screenshot` / `pdf` / `fetch --focus` / `fetch --json` 补齐——CLI 能做的 MCP 也能做，反之亦然；`tools/list` 默认三件套（search/fetch/status），其余按需显式开。
+- **DSH 插件连接池按需增长**：以前全系统共用一条串行连接，多个 worker 并发研究时实际逐个搜索（实测两条并发搜索第二条干等 2.7s）。现在顺序调用仍是 1 条连接零额外开销，真发生并发才补开，空闲各自回收。
+
+## 更稳（跨平台与环境）
+
+- **三平台惯例路径**：Linux 走 XDG、Windows 走 `LOCALAPPDATA`/`APPDATA`、macOS 走 `~/Library`，不再全部堆在 `~` 下；新增 `argo paths` 自省命令，配置/缓存/状态到底在哪一条命令看清。
+- **支持 Python 3.9**：版本下限单一真源 + 跨解释器语法门禁（3.9 与最新版全量回归都跑）；解释器候选链补全（Windows 上没有 `python3` 这个名字也能找到可用运行时）。
+- **静默故障可见化**：降级、跳过、回源这类以前一声不吭的行为，现在在输出与日志里如实记账。
+
+## 默认关闭功能的打开方式
+
+- 代理默认跟随标准环境变量，什么都不配即为原行为；显式指定用 `ARGO_PROXY=http://127.0.0.1:7890`，或在 config.yaml `network.proxy` 按域分流（必须代理的域配 URL、直连更优的域配 `"direct"`，注释里有三档环境模板）。
+- parallel_free 无需配置，自动参与兜底补位；`ARGO_FETCH_PARALLEL=0` 可关闭该抓取级。
+- seltz 需在 `~/.config/argo/env` 写入 `SELTZ_API_KEY`；unpaywall 需写 `UNPAYWALL_EMAIL`（上游要求署名邮箱）。
+- 观察模式：`argo watch add <url>` 建快照，cron 里跑 `argo watch check --json`。
+- MCP 完整工具面：默认只挂 search/fetch/status 三件套，其余 11 个工具在客户端配置里按需声明。
+
+## 相关依赖与已知边界
+
+- 无新增第三方依赖（curl_cffi 仍为可选加速项）；Python ≥ 3.9。
+- seltz 中文覆盖未验证，中文查询暂不路由到它；其免费端点无官方配额承诺，已按低优先级保守看管。
+- `cisa_kev` 上游是 1.35MB 全量文件、不支持查询参数，采用本地过滤 + 进程内 TTL 缓存，首次调用偏慢属预期。
+- `weather_cn` 为城市实况两步查询（城市联想 → 实况），不支持历史天气与预报长尾。
+- 直答与观察为 CLI 子命令，未加入 MCP 工具面（MCP 工具数不变）。
+
+## 工程与质量（给关心维护性的人）
+
+- **搜索编排拆模块**：`search.py` 3351 → 2526 行，execute_search 按职责拆出四个模块——单文件不再继续膨胀。
+- **相关性回归金标**：22 个引擎的真实结果快照入库（`tests/golden/relevance_golden.json`），每次改动重放断言——「这版改完排序有没有变坏」从猜测变成逐位比对。
+- **静态缺陷门禁**：拦截「会跑错或静默失效」的写法（未定义名、重复键、fail-open 例外吞错等），扫描范围覆盖 scripts 与 tests；输出契约门禁锁字段集合与字节预算，升级不会悄悄变胖。
+- **自造黑话清理**：注释与人读文档统一换成日常说法，只动措辞不动行为。

package/docs/RELEASE_NOTES_v2.8.9.md

@@ -0,0 +1,67 @@
+# RELEASE_NOTES_v2.8.9
+
+相对 v2.8.8 的改进：搜索更快也更省——默认输出体积 −66%、重复查询整次耗时 −30%、慢网轮等待 −36%；拿到手的内容更完整——召回 +35%、抓取时延 −30%、正文结构保真 0/6 → 6/6；新增 5 个外媒与核查源（全部免密钥，源 232 → 237、领域 90 → 92）；修复六处「数字互相矛盾」的记账缺陷，报出来的命中率、耗时、漏斗从此自己能对上账；新增离线重跑对比工具，改完代码「变好了还是变坏了」不再靠等联网检查。
+
+## 更快更省（每次查询省下的时间与体积）
+
+- **默认输出 15.5KB → 5.2KB（−66%）**：以前同一段结果摘要在默认输出里重复写三遍（占全文 82%）。现在默认只给一份干净结果；要完整封套用 `--envelope` 显式打开，`--archive` 归档时自动保留，归档能力零损失。
+- **重复查询 168 → 118ms（−30%）**：路由决策加了一层缓存——同一个问题第二次搜，不再重付每次新进程都要交的「路由启动税」（103ms → 3.5ms）。指纹只在数据源真的挂掉或恢复时才失效，不会出现缓存永远不命中。
+- **慢网轮等待 −36%**：行情、天气、赛事这类串行查询，以前第一个源必须耗满自己的超时上限（5-8 秒）才轮到备选。现在主源卡过 0.8 秒就补发备选源并行跑——主源在窗内交付时仍然只付一次调用的钱。8 条慢查询实测 21.0s → 13.4s。
+- **杂项提速**：`--help` 输出 −28%；缓存驱逐从逐个扫描改为一次排序（O(N²) → O(N)）；进程启动不再为一个没人用的日志器付 12.5ms 的连带导入。
+
+## 内容更完整（拿到手的东西质量更高）
+
+- **召回 +35%、抓取时延 −30%、搜索长尾 P90 −8%**：取数链路五轮系统性优化——该改写的改写、该跟随的重定向跟随、该并发的并发、该提前放弃的提前放弃。
+- **正文结构不再被压平**：网页转正文时保留标题层级、列表、表格结构（HTML → Markdown），六类典型页面结构保真 0/6 → 6/6。以前抓回来一大坨字，表格行列全糊在一起。
+- **表格行列还原、章节号成词、URL 规范化**：抓取正文的三条低成本改进；顺带修了一个长期 bug——改写过的 URL 在链路后段被悄悄改回原始形态，导致重新访问旧地址。
+- **中文内容不再被系统性判为低质**：质量分的词数统计按英文习惯计算，中文按字计 vs 按词计差一个数量级，导致中文结果分数普遍虚低；现在分项依据随分输出，「这个分怎么来的」看得见。
+
+## 新增能力（5 个外媒与核查源，全部免密钥）
+
+- 源 232 → 237（免配置开箱 194 → 198），新增两个领域（90 → 92）：
+  - `guardian_rss` 卫报世界版（摘要长度是同侪的 3-9 倍）
+  - `france24` France 24 英语版（补法语区视角）
+  - `dw_news` 德国之声英语版（候选池最多）
+  - `factcheck_org` FactCheck.org（声明级真伪判定，美国口径）
+  - `full_fact` Full Fact（同能力，英国口径）
+  - 新领域：`intl_news_flash` 国际新闻实时流、`claim_check` 声明核验/辟谣
+- **下线死源 gdelt**：上游持续拒绝访问（连续重试全 429），却同时占着国际事件域的主力与备选三处——等于这个域的保底一直是空的。现在主备改指 google_news 与 em_global_news。
+
+## 数字可信（六处「看起来对、量起来错」的修复）
+
+这批缺陷的共同形态是不崩溃、但报出来的数字互相矛盾——读它的人会指着错误的对象做优化决策：
+
+- **缓存命中率口径**：L2 层每命中一次，都被同时记进分子和分母——L2 越有效，报出来的命中率反而越低。现在 miss 数恒等于真正落空的次数。
+- **交付了结果的引擎被自己毒掉**：「部分成功」（有结果也有报错）被当成了失败，既推高熔断计数、又写进 30 秒负缓存——同一个查询再搜时，刚交出结果的引擎反而被跳过。
+- **全引擎超时报「跑了 0 个引擎」**：超时路径漏记耗时账，而「各引擎跑了多久」的读数全从这笔账推出来——恰恰是最该被看见的一轮，读数却是空的。
+- **深度模式报出「用时超过总预算」**：全量并行分支不认总墙钟预算，自相矛盾的读数会误导下一轮判断。
+- **每次启动白付 15ms**：为读一张恒为空的表，付了整笔网络库导入（222 个引擎全量比对：路由结果 0 处差异，纯白付）。
+- **DSH 插件连接池四处收口**：失败的连接不再占着位置不还（否则全系统悄悄退化成单连接串行）；握手补上超时上界（离线或代理不通时，第一次搜索不再永远挂着）；「调用超时」与「连接坏了」可区分（超时不再触发对同一次慢调用的重发，省下双倍配额）；管道被关闭导致的截断不再被报成成功。
+
+## 看得清（归因）
+
+- **六格漏斗**：每次搜索输出自带「路由了几个 → 真正调用了几个 → 返回几个 → 去重后剩几个 → 过滤后剩几个 → 最终保留几个」，搜出 0 条时能定位到底塌在哪一层，而不是只看到一句「无结果」。
+- **耗时账拆出过滤与恢复两个阶段**：以前零结果恢复链打的网络调用被记在精排头上（实测 700ms 的「精排」里只有 3.6ms 是真精排）——想优化瓶颈，别再被指错方向。
+- **「浪费的时间」重新定义**：改为「答案就绪之后还在等的时间」，与有效时间之和恒等于总墙钟——旧口径并行时必然大于总时长，且把如实返回 0 条也算成浪费。
+
+## 默认关闭功能的打开方式
+
+- 完整输出封套：`--envelope` 显式打开；`--archive` 归档路径自动保留（无需设置）；旧参数 `--no-envelope` 兼容保留。
+- 路由决策缓存默认开；调试时可设 `ARGO_ROUTE_CACHE=0` 关闭。
+- 每次搜索的阶段耗时账默认开（`--no-timing` 可关）；本轮起新增 filter / recovery 两个独立阶段。
+- 备选源补发不产生新开关：串行域在主源超窗时自动补发，备选源全部免密钥，慢网轮调用数 +12% 换 1.2 秒的等待减少。
+- 离线重跑（开发者工具）：`python3 scripts/replay_eval.py` 录制一次真实搜索后，`--compare` 不上网重跑整条流程并列出与基准的差异——去重、合并、排序的改动效果当天可验证，不用等每周联网检查。
+
+## 相关依赖与已知边界
+
+- 无新增第三方依赖；Python ≥ 3.9 不变。
+- 卫报 / France 24 / 德国之声走 RSS 通道，内容为标题与摘要（卫报摘要中位 979 字），全文需另行抓取；两个核查源覆盖美英两法域的声明。
+- 实时流类新源（新闻快讯）按「热榜」语义工作：忽略查询词、返回最新条目，不参与话题检索的槽位竞争；核查源按「查询过滤」语义工作。
+- 主源 0.8 秒宽限窗按实测均值 1.9s 设定：网络正常时主源多在窗内交付、成本不变；极快网络下主源偶尔超窗，会多付一次免密钥调用。
+
+## 工程与质量（给关心维护性的人）
+
+- **离线重跑对比工具**（`scripts/replay_eval.py` + 十项检查）：录制 → 重跑 → 对比三段式，把「这次改动是不是变好了」从每周一次的联网检查变成随时可跑的本地比对。
+- **「策略施加后」部署形态门禁**：以前门禁只看「路由策略是什么」，看不到「策略真正施加到引擎清单之后长什么样」——部署形态零覆盖。补上之后顺带修掉一个真实路由缺陷（一个一词多义的词把查询劫持进单一引擎）。
+- **场景阈值契约**：「什么算不达预期」（域归属、引擎数量、重放保留数）写成机器可查的阈值表，不再靠人翻输出。
+- **本批新增回归门**：审查补丁 8 条 + 部署形态与场景阈值若干条，每条都在缺陷代码上失败过（变异即红）；全量 pytest 2511 passed / 21 skipped。

package/docs/RELEASE_NOTES_v2.9.0.md

@@ -0,0 +1,64 @@
+# RELEASE_NOTES_v2.9.0
+
+相对 v2.8.9 的 62 个提交，一句话总览：**搜索源优化——新增 16 个源、替换部分质量不佳的源，净 237 → 253（免配置 198 → 219）；两个常青源修活；插件与 CLI 搜索能力首次完全持平（19 个 MCP 工具）；多语言小语种源 +14 并按语言自动配源；本地使用日志规范化（仅本机）并新增 `argo stats` 读出口；74 个功能开关成表可查。** 测试从 2365 个测试函数增至 2770+（全量 3082 通过），本发布包经密钥泄漏扫描，零命中。
+
+## 搜索源：先提质，再控量（237 → 253，免配置 198 → 219）
+
+- **新增**：14 个小语种本地新闻源、CORE 开放获取全文源、iPlant 植物智（中文植物名 → 学名+分类，补上「从中文俗名进生物数据库」的空白）、sov2ex 全文搜索（实测 48ms）、TinEye 反搜图、Bing RSS 稳定出口、Exa 免 key 匿名通道；PubMed 此前静默失效，已修复。
+- **替换部分质量不佳的源**：逐源按「结果质量、稳定性、可验证性」实测评估，未达标的源不再随版发布，腾出的预算位让给可用性更好的源。**原则：宁少勿死——源贵在每一条都能交付。**
+- **两个常青源修活**：百度与搜狗的历史低产真根因是「结果链接全是跳转壳、被聚合层整批滤掉」——现在引擎层逐条解析跳转链换真实 URL，并优化了连接身份管理。百度实测单次可稳定产出。
+- **出处可验证**：npm 引擎与技能目录源补齐发布时间与可验证出处链接。
+
+## 多语言：小语种不再二等
+
+- 新增 14 个本地语言新闻源（日/韩/俄/西/法德意之外的小语种：泰/阿拉伯/希伯来/希腊/印地/越南/土耳其/印尼等）。
+- **语言绑定选源**：按查询语言自动配「该语言真正可用」的源；非拉丁语查询由 local_bing 动态 setlang 承接多语言索引；被语言门剔除的引擎在输出的 `noise_dropped` 里可见——「为什么少了几个源」有账可查。
+- 日语零结果兜底、语言软排序数据驱动、多语言评估池同步更新。
+
+## 插件与 CLI 搜索能力持平（19 个 MCP 工具）
+
+- CLI 18 个命令与 MCP 19 个工具一一对应，本轮补齐 `argo_extract`（结构化提取）、`argo_preflight`（批量 URL 预检）、`argo_answer`（带引用直答）、`argo_watch`（网页变化监控）、`argo_cite`（DOI 四格式引用条目）。
+- 一致性由门禁锁定：CLI 能力命令 ↔ 工具一一映射、文案计数与真源相等——「插件又落后了」这类漂移从此测试就红。
+- DSH 插件三形态接入不变：原生工具默认入口（零常驻 token）、web_search seam、按需挂载 MCP（19 工具 ≈3.7K token/轮；默认只挂核心三件 ≈919 token）。
+
+## 性能：上一轮「冷启动 0.85s→0.16s」的同根因延续
+
+- 导入链 252ms → 35ms（−79%）：网络栈延迟导入全链收口；路由热路径再去掉 25 个模块的连带加载。
+- 重排序 K 相关剪枝：n=200 场景 33ms → 1.5ms；查询理解固定开销每查询再省 6-7ms。
+- 缓存键修正：从按「回答」算改回按「请求」算，命中率从六成到基本不 miss。
+- 深度研究整链墙钟 −28%（扩词层去掉不产生新信息的变体，消融实验驱动）。
+
+## 更可信（修复精选，全部带测试）
+
+- 早停被弃置的结果不再被误标成「超时」毒化自适应学习器（cancelled 分流）。
+- 兜底处理器自身缺陷不再让整次搜索崩溃；抓取链 deadline 击穿修复。
+- 限定符查询的缓存串味、域规则 32 例实测误判、HTML 假搜索页垃圾结果——各修各的根因。
+- 配额写路径跨进程丢数据（CLI/插件/评测三方并行时计数互相覆盖，数据损坏级）：7 处写路径全部补齐跨进程安全。
+- `--explain-timing` 的 import_ms 恒为 0（工具报不出自己最大的开销）：实测恢复 20-30ms 真值。
+
+## 规范的本地使用日志（仅本机，不外发）
+
+- 正名：这套机制叫**本地使用日志**（usage_log），不叫遥测——它不出本机，名字必须与信任边界一致。
+- 新命令 **`argo stats`**：命中率、平均时延、引擎频次、救援率、最近查询——搜索质量第一次有了自己的账本。
+- 四个 JSONL 流（查询总账/救援链/路由采样/融合去重），单流自动回缩（1MB/2000 行），总开关 `ARGO_USAGE_LOG=0`。
+- 隐私纪律：query 截断脱敏、仅本机存储、**用量统计不进任何对外材料**。
+
+## 功能开关成表（74 个，一份文档查全）
+
+`references/usage.md` 升级 v2.9.0：18 命令总览、全命令参数、**74 个 `ARGO_*` 开关按六类成表**（能力开关/密钥/行为调参/路径/MCP 运行配置/抓取降级分级），日志与反馈一章讲清「数据在哪、怎么读、怎么关、反馈闭环怎么工作」。文档受四件套门禁锁定——说的能力必真存在，真存在的能力必在文档。
+
+## 安全与脱敏
+
+- 密钥脱敏三形态（URL 查询串嵌的密钥 / 正文里贴的凭证 / 值级递归），唯一实现被失败归因、归档、引擎列表输出三处复用——凭证进不了任何持久化文件。
+- 本发布包与仓库经密钥泄漏扫描：本机 12 个真实密钥值逐一比对 + 常见密钥形态（sk-/ghp_/AKIA）全仓扫描，零命中。
+
+## 安装与 DSH 插件支持的版本
+
+- 安装：`npx -y github:taxueseek/argo`，或 `install.sh`；DSH 插件：`dsh plugin --profile web add "github:taxueseek/argo#main&path:packages/dsh-plugin"`。
+- **DSH 插件支持的版本**：Node.js ≥ 18；Python 3.10+（`pip install pyyaml`）；DSH 宿主的子代理 provider 需支持 `outputSchema` / `toolFilter` / `depthLimit`（标准 `spawn` 即可）——实测于 DSH 0.1.7-alpha.1。
+- 本发布包含打包产物 `argo-search-2.9.0.tgz`（406 个文件，解包 5.0MB，与仓库同源同扫描）。
+
+## 已知边界
+
+- 部分上游对访问频率有要求：内置限速、最小间隔与身份轮换，极端情况下返回诚实空（不伪装成功）。
+- 无新增第三方依赖；Python ≥ 3.9 不变（DSH 插件路径 3.10+）。

package/docs/SEARCH_ARCHIVE.md

@@ -0,0 +1,115 @@
+# 搜索成果归档与复用（v2.4.5）
+
+## 为什么要归档（以及何时不要）
+
+Argo 的热路径返回 `results[]` + `candidates[]` + `sources[]` 适合当次决策，但：
+
+1. Agent 会话结束后候选易丢，后续分析无法复现  
+2. 多次同类查询没有可比对的 run 级快照  
+3. 「发现」与「吸收正文」混在同一响应时，容易把 snippet 当事实  
+
+归档层只做一件事：**把当次发现 envelope 以不可覆盖的 run 目录写入工作区**，供复用、对比与后续核验。
+
+### 分层默认（重要）
+
+| 入口 | 默认归档 | 原因 |
+|------|----------|------|
+| `search.py` 日常 | **否** | 快问多、价值密度低；存则噪声淹没研究档案 |
+| `research.py` 深度 | **是** | 多跳发现成本高，默认需要可复现 |
+
+日常搜索只有用户明确「存一下 / 后续对比」时才 `--archive`。
+
+## 硬边界
+
+| 允许 | 禁止 |
+|------|------|
+| 落盘 query / results / candidates / coverage / limitations | 自动抓正文、下载媒体 |
+| 新 run 目录（永不静默覆盖） | 把归档当成「已核验事实库」 |
+| 从归档再触发 fetch/extract（需明确动作） | 搜索自动升级为登录态或私有读取 |
+| known-url 仍 handoff，不写入「伪搜索 run」 | 把互动量当事实正确性 |
+
+**发现 ≠ 吸收**。吸收正文用 `argo_fetch` / `extract` / 内容打包工具；搜索归档只保留发现层。
+
+## 默认路径
+
+```
+<workspace>/数据/argo-search-archive/
+  index.jsonl
+  runs/
+    YYYY-MM-DD/
+      <run_id>/
+        run-summary.json
+        envelope.json
+        candidates.jsonl
+        results.jsonl
+        coverage.json
+        INDEX.md
+```
+
+解析顺序：
+
+1. `--archive-dir`  
+2. 环境变量 `ARGO_ARCHIVE_ROOT`  
+3. 含 `AGENTS.md` 的工作区 → `数据/argo-search-archive`  
+4. 否则 `./数据/argo-search-archive`
+
+## CLI
+
+```bash
+cd <argo-root>
+
+# 日常搜索：默认不归档；需要时再开
+python3 scripts/search.py "贵州茅台 估值" --archive --archive-tag invest --json
+
+# 深度研究：默认归档
+python3 scripts/research.py "…议题…" --json
+python3 scripts/research.py "…议题…" --no-archive   # 关闭
+
+# 仅归档已有 JSON（stdin）
+python3 scripts/search.py "q" --json | python3 scripts/archive_run.py write --tag adhoc
+
+# 列出近期 run
+python3 scripts/archive_run.py list --limit 20
+python3 scripts/archive_run.py list --tag invest --query 茅台
+
+# 查看某一 run
+python3 scripts/archive_run.py show <run_dir>
+python3 scripts/archive_run.py root
+```
+
+JSON 输出时，`archive` 字段包含 `run_id` / `run_dir` / `paths` / `counts`。
+
+## 复用与分析
+
+1. **复现检索上下文**：读 `run-summary.json` + `envelope.json`  
+2. **候选池去重**：对多份 `candidates.jsonl` 按 `canonical_url` / `candidate_id` 合并  
+3. **覆盖审计**：对比 `coverage.json` 的 backend 返回数与 truncated  
+4. **核验流水线**：筛选高 `credibility_fast` / 权威域名候选 → `argo_fetch` → 更新本地笔记（**不改原 run**）  
+5. **口径冲突**：同一 query 的多次 run 并列，禁止未对齐口径就合并数字  
+
+示例（只读聚合）：
+
+```bash
+# 最近 5 次 run 的 query 与候选数
+python3 scripts/archive_run.py list --limit 5 --json
+```
+
+## Agent 纪律
+
+1. 需要可复现/可对比时加 `--archive`（或用户要求「存一下/归档搜索」）  
+2. 日常轻问可不归档，避免磁盘噪声  
+3. 归档后交付路径，不重贴大段 JSON  
+4. 引用结论前：`verification.status` 仍为 `candidate` 的必须 fetch  
+5. 隐私：默认不写 Cookie/Token；敏感 query 谨慎入库  
+
+## 与已有能力的关系
+
+| 能力 | 层 |
+|------|----|
+| `plan.py` / `input_kind` | 执行前分流 |
+| `candidate_envelope` | 当次响应结构 |
+| `archive_run` | 跨会话持久化 |
+| `evidence` / `fetch` | 吸收与可信度 |
+| L1/L2 cache | 加速重复查询，**不是**分析用 run 档案 |
+
+Cache 可淘汰；archive run **默认永久保留**（清理由用户手动）。

package/docs/assets/architecture.svg

@@ -0,0 +1,104 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 500" fill="none">
+  <defs>
+    <linearGradient id="bg2" x1="0" y1="0" x2="800" y2="500" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#0f172a"/>
+      <stop offset="100%" stop-color="#1e293b"/>
+    </linearGradient>
+    <linearGradient id="g-blue" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#38bdf8"/>
+      <stop offset="100%" stop-color="#0ea5e9"/>
+    </linearGradient>
+    <linearGradient id="g-purple" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#818cf8"/>
+      <stop offset="100%" stop-color="#6366f1"/>
+    </linearGradient>
+    <linearGradient id="g-green" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#34d399"/>
+      <stop offset="100%" stop-color="#10b981"/>
+    </linearGradient>
+    <linearGradient id="g-amber" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#fbbf24"/>
+      <stop offset="100%" stop-color="#f59e0b"/>
+    </linearGradient>
+    <linearGradient id="g-rose" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#fb7185"/>
+      <stop offset="100%" stop-color="#e11d48"/>
+    </linearGradient>
+  </defs>
+
+  <rect width="800" height="500" rx="12" fill="url(#bg2)"/>
+
+  <!-- Title -->
+  <text x="400" y="35" text-anchor="middle" font-family="system-ui, sans-serif" font-size="16" font-weight="600" fill="#e2e8f0">Argo 架构概览</text>
+
+  <!-- Input -->
+  <rect x="320" y="50" width="160" height="36" rx="8" fill="url(#g-blue)" opacity="0.9"/>
+  <text x="400" y="73" text-anchor="middle" font-family="system-ui, sans-serif" font-size="12" fill="white" font-weight="600">搜索查询</text>
+
+  <!-- Arrow down -->
+  <line x1="400" y1="86" x2="400" y2="110" stroke="#475569" stroke-width="1.5" marker-end="url(#arrowhead)"/>
+  <defs><marker id="arrowhead" markerWidth="8" markerHeight="6" refX="8" refY="3" orient="auto"><polygon points="0 0, 8 3, 0 6" fill="#475569"/></marker></defs>
+
+  <!-- Router box -->
+  <rect x="250" y="110" width="300" height="55" rx="10" fill="url(#g-purple)" opacity="0.15" stroke="url(#g-purple)" stroke-width="1.5"/>
+  <text x="400" y="132" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#c4b5fd" font-weight="600">TF-IDF 语义路由</text>
+  <text x="400" y="152" text-anchor="middle" font-family="system-ui, sans-serif" font-size="9" fill="#94a3b8">正则域 · 余弦相似度 · 配额感知</text>
+
+  <!-- Arrows from router -->
+  <line x1="330" y1="165" x2="200" y2="210" stroke="#475569" stroke-width="1" marker-end="url(#arrowhead)"/>
+  <line x1="400" y1="165" x2="400" y2="210" stroke="#475569" stroke-width="1" marker-end="url(#arrowhead)"/>
+  <line x1="470" y1="165" x2="600" y2="210" stroke="#475569" stroke-width="1" marker-end="url(#arrowhead)"/>
+
+  <!-- T1 box -->
+  <rect x="80" y="210" width="240" height="80" rx="10" fill="url(#g-purple)" opacity="0.1" stroke="url(#g-purple)" stroke-width="1"/>
+  <text x="200" y="232" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#a5b4fc" font-weight="600">T1 — 直连引擎</text>
+  <text x="200" y="250" text-anchor="middle" font-family="monospace" font-size="8" fill="#94a3b8">anysearch · zhihu · eastmoney</text>
+  <text x="200" y="264" text-anchor="middle" font-family="monospace" font-size="8" fill="#94a3b8">tavily · github · arxiv · byted</text>
+  <text x="200" y="280" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8" fill="#94a3b8">0.4–3.5s · 部分需 API Key</text>
+
+  <!-- Cache box -->
+  <rect x="340" y="210" width="120" height="80" rx="10" fill="url(#g-amber)" opacity="0.1" stroke="url(#g-amber)" stroke-width="1"/>
+  <text x="400" y="232" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#fcd34d" font-weight="600">缓存</text>
+  <text x="400" y="250" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8" fill="#94a3b8">L1 内存 LRU</text>
+  <text x="400" y="264" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8" fill="#94a3b8">L2 SQLite</text>
+  <text x="400" y="280" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8" fill="#94a3b8">分级 TTL</text>
+
+  <!-- T2 box -->
+  <rect x="480" y="210" width="240" height="80" rx="10" fill="url(#g-green)" opacity="0.1" stroke="url(#g-green)" stroke-width="1"/>
+  <text x="600" y="232" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#6ee7b7" font-weight="600">T2 — 本地引擎</text>
+  <text x="600" y="250" text-anchor="middle" font-family="monospace" font-size="8" fill="#94a3b8">bing · sogou · duckduckgo</text>
+  <text x="600" y="264" text-anchor="middle" font-family="monospace" font-size="8" fill="#94a3b8">github · stackoverflow · pubmed</text>
+  <text x="600" y="280" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8" fill="#94a3b8">0.6–5s · 零成本</text>
+
+  <!-- Fallback arrows -->
+  <path d="M 320 250 Q 330 250 330 250" stroke="#475569" stroke-width="1" stroke-dasharray="4,3" marker-end="url(#arrowhead)"/>
+  <path d="M 460 250 Q 470 250 470 250" stroke="#475569" stroke-width="1" stroke-dasharray="4,3" marker-end="url(#arrowhead)"/>
+
+  <!-- Labels for fallback -->
+  <text x="325" y="244" font-family="system-ui, sans-serif" font-size="7" fill="#64748b" text-anchor="end">T1 失败</text>
+  <text x="475" y="244" font-family="system-ui, sans-serif" font-size="7" fill="#64748b">T2 失败</text>
+
+  <!-- Arrows to merge -->
+  <line x1="200" y1="290" x2="350" y2="330" stroke="#475569" stroke-width="1" marker-end="url(#arrowhead)"/>
+  <line x1="400" y1="290" x2="400" y2="330" stroke="#475569" stroke-width="1" marker-end="url(#arrowhead)"/>
+  <line x1="600" y1="290" x2="450" y2="330" stroke="#475569" stroke-width="1" marker-end="url(#arrowhead)"/>
+
+  <!-- Merge / RRF box -->
+  <rect x="280" y="330" width="240" height="45" rx="10" fill="url(#g-rose)" opacity="0.15" stroke="url(#g-rose)" stroke-width="1"/>
+  <text x="400" y="350" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#fda4af" font-weight="600">RRF 融合 · 去重 · 精排</text>
+  <text x="400" y="368" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8" fill="#94a3b8">多源融合 → 可选语义精排</text>
+
+  <!-- Arrow to output -->
+  <line x1="400" y1="375" x2="400" y2="405" stroke="#475569" stroke-width="1.5" marker-end="url(#arrowhead)"/>
+
+  <!-- Output box -->
+  <rect x="280" y="405" width="240" height="50" rx="10" fill="url(#g-blue)" opacity="0.15" stroke="url(#g-blue)" stroke-width="1.5"/>
+  <text x="400" y="427" text-anchor="middle" font-family="system-ui, sans-serif" font-size="11" fill="#7dd3fc" font-weight="600">统一 JSON 输出</text>
+  <text x="400" y="445" text-anchor="middle" font-family="system-ui, sans-serif" font-size="8" fill="#94a3b8">结果 · 评分 · 域 · 引擎状态</text>
+
+  <!-- Side labels -->
+  <text x="45" y="260" font-family="monospace" font-size="9" fill="#6366f1" transform="rotate(-90, 45, 260)">TIER 1</text>
+  <text x="755" y="260" font-family="monospace" font-size="9" fill="#10b981" transform="rotate(90, 755, 260)">TIER 2</text>
+  <text x="315" y="255" font-family="monospace" font-size="7" fill="#f59e0b">→</text>
+  <text x="455" y="255" font-family="monospace" font-size="7" fill="#f59e0b">→</text>
+</svg>