# 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；输出契约门禁锁字段集合与字节预算，升级不会悄悄变胖。
- **自造黑话清理**：注释与人读文档统一换成日常说法，只动措辞不动行为。