argo-search 1.0.1 → 2.9.7

package/docs/MCP_SETUP.md

@@ -0,0 +1,106 @@
+# 设计：多客户端 MCP 一键注入（mcp/clients.yaml 声明式真源）
+
+> 状态：已实施（2026-08-26）。目标：让 argo 的 MCP 工具（argo_search/argo_fetch/argo_research 等）能被
+> 主流 AI 客户端一键接入，无需手动贴 JSON。客户端描述声明式化（改客户端不改代码），写入安全可逆。
+> `tools/list` 默认三件套（search/fetch/local_search）；全量 14 个设环境变量 `ARGO_MCP_TOOLS=all`。
+
+## 0. 背景与问题重定义
+
+Argo 的 MCP server（`scripts/mcp_server.py`，stdio）此前只有两条分发路径：
+
+- **DeepSeek Harness**（`packages/dsh-plugin`）—— 单一平台、硬件绑定。
+- **install.sh 结尾**贴一段手写 `mcpServers` 示例 —— 只给 Claude Code，需用户手动复制。
+
+缺口：没有「探测已装客户端 + 精细写对各客户端配置格式 + 可逆还原」的通用接入层。
+用户想在 Cursor / Windsurf / Codex / OpenCode / Cline 等用 argo 搜索，只能各自手工配。
+
+## 1. 设计原则（从第一性原理）
+
+Keenable 的同款能力（`configure-mcp`）用 **Rust 结构体硬编码客户端**：加一个客户端 = 改 Rust 代码 + 重新编译发布。学它思路、规避它的三个短板：
+
+1. **客户端描述硬编码** → 我们用**声明式真源** `mcp/clients.yaml`（对齐 Argo 已有的
+   `config.yaml` / `engines/specs/*.yaml`「配置真源」哲学）。加客户端 = YAML 一行，零改代码。
+2. **对 TOML 需要第三方库**（它将 TOML 用 `toml_edit` 全量重序列化，会重排注释）→ 我们用
+   **行级 append section**（`[mcp_servers.argo]` block）：精确追加、删除，**已存在内容一字不动**，
+   注释零破坏。纯 stdlib 可达，零新依赖。
+3. **不可逆性** → 我们做 **备份 + undo 双通道**：写入前备份到 `~/.argo/mcp-backup/<ts>_<file>`，
+   undo 精确移除 entry；无 entry 时从最近备份回滚。
+
+## 2. 分层架构
+
+| 层 | 职责 | 文件 |
+|---|---|---|
+| 真源 | 客户端描述（路径/servers_key/格式/detect/标准工具） | `mcp/clients.yaml` |
+| 引擎 | 探测 / 注入 / 诊断 / 还原 | `scripts/mcp_setup.py` |
+| 入口 | CLI 子命令 | `bin/argo mcp <sub>` |
+
+`mcp_setup.py` 全 stdlib（`sys/json/yaml/os/shutil/tempfile/datetime/pathlib`），
+不引入 `toml`/`tomlkit`，Windows/macOS/Linux 通吃。
+
+## 3. 写入安全模型（核心）
+
+### 3.1 原子写
+`atomic_write`：**同目录**临时文件（`tempfile.mkstemp`）→ `os.replace`。并发读者只见旧或新，绝无半截。
+见 `scripts/mcp_setup.py::atomic_write`。
+
+### 3.2 备份（可回滚）
+注入任何配置前 `backup_file` 原文件 COPY 到 `~/.argo/mcp-backup/<ts>_<name>`。
+undo 时若 entry 已不存在（比如被手动删了），从最近备份 `copy2` 恢复——回到我们写入前的安全态。
+
+### 3.3 权限收紧
+含密钥的配置（`.claude.json` / `config.toml` 可能含 API key）以 `os.chmod(0600)` 写入，
+避免其他用户可读。
+
+### 3.4 fail-loud 不覆盖用户文件
+- JSON 文件已存在但**非法** → 抛异常，**绝不**用空对象覆盖（避免毁掉用户 `~/.claude.json`）。
+- TOML 已含 `[mcp_servers.argo]` → 报错提示先 undo，**不重复追加**。
+- `read_config_for_write` 语义：读失败 = 提醒修复，不改文件。
+
+## 4. 双格式处理
+
+### JSON（Claude Code / Cursor / Windsurf / OpenCode / Cline）
+`_inject_json`：`config[servers_key][ENTRY_NAME] = entry`，其余子树**原样保留**（兄弟 entry 不动）。
+`_remove_json`：删 `ENTRY_NAME`，兄弟保留，无 entry 返回 None。
+
+### TOML（Codex `~/.codex/config.toml`，手维护含注释）
+`_inject_toml`：在文件尾**追加** `[mcp_servers.argo]` block（`command`/`args`/`env`）。
+`_remove_toml`：按 section 帧边界（行首 `[x]`）**只删该 block**，其余（含注释）一字不动。
+已有该 block 则报错不覆盖。
+
+## 5. 客户端描述真源（mcp/clients.yaml）
+
+关键字段：`id`（CLI 用）、`config_path`（相对 home）、`servers_key`（mcpServers/servers/mcp_servers/mcp）、
+`format`（json/toml）、`url_key`、`transport`、`detect`（探测目录，存在即"已安装"）、`standard_tools`（未用，预留）。
+
+当前支持：Claude Code、Cursor、Windsurf、Codex、OpenCode、Cline。
+
+## 6. 执行流程
+
+```
+argo mcp status        # 逐客户端：已安装/已配置/未安装
+argo mcp inject --all  # 对已安装客户端：备份 → patch（JSON merge 或 TOML append）→ 原子写
+argo mcp inject --cursor --dry-run  # 只预览
+argo mcp undo --all    # 精确移除 entry；无 entry 从备份回滚
+```
+
+`--client` 支持逗号分隔（`--client codex,cursor`）。未知 id 忽略并提示。
+
+## 7. 明确不做 / 边界
+
+- **不做 keyless / 认证管理**：本模块只写 MCP server entry，不涉及 API key 的登录/存储（那是
+  `engine_env.py` 的职责）。entry 里的 `env` 只放运行必需项。
+- **不做后台 daemon**：写入是同步原子操作，无需常驻进程。
+- **不覆盖用户手写配置**：任何可能破坏既有内容的路径都 fail-loud 报错而非静默重写。
+- **不引入第三方依赖**：TOML 用行级 append 而非 toml_edit 全量重序列化。
+
+## 8. 验收清单
+
+- [x] `status` 正确反映各客户端已安装/已配置。
+- [x] `inject` JSON：兄弟 entry 保留，原子写，备份生成。
+- [x] `inject` TOML：手写注释 + `model` 原样保留，仅追加 block。
+- [x] `undo` TOML：只删 block，注释保留。
+- [x] `undo` JSON：移除 entry，兄弟保留。
+- [x] 无 entry undo：从备份回滚。
+- [x] `atomic_write` 0600 权限。
+- [x] `--dry-run` 不写盘。
+- [x] 单测 `tests/test_mcp_setup.py`（12 例）全过。

package/docs/PLATFORM_PATHS.md

@@ -0,0 +1,111 @@
+# 设计：跨平台路径与惯例（macOS / Linux / BSD / Windows）
+
+> 状态：已实施（2026-09-15）。`python3 scripts/argo_paths.py [--json]`（或 `argo paths`）
+> 会直接打印下列路径的**实际来源**——支持类问题的第一问是「你到底在读哪个文件」。
+> 想让存量安装改用惯例目录：`argo paths --migrate`（默认只报告，见 §4）。
+
+## 0. 问题重定义
+
+argo 需要在四类系统上找到两样东西：**状态目录**（搜索缓存、配额计数、准入记录、
+健康库）与**密钥文件**。此前两处都是写死的：
+
+- 状态目录兜底 `~/.cache/unified-search`：Windows 上不符合 `%LOCALAPPDATA%` 惯例，
+  Linux 上无视 `XDG_CACHE_HOME`；
+- 密钥文件写死 `~/.config/argo/env`：Windows 该用 `%APPDATA%`，自定义
+  `XDG_CONFIG_HOME` 的用户无处安放密钥。
+
+写死的代价不是「不够好看」，而是**平台约定的两处收益同时丢失**：备份/清理工具
+按惯例知道该动哪个目录；容器与 CI 镜像按惯例只挂载一个路径。
+
+**同等重要的一个前提**：`config.yaml` 里曾经写死 `cache.db_path`。它优先级高于平台
+惯例，等于让上面这套解析永远轮不到生效——所以那一行现在是注释状态（要固定位置再
+启用，见文件内说明）。
+
+
+## 0.1 一条命令核对（任何平台）
+
+```sh
+argo paths --check          # 人读；有 fail 时退出码非 0（可直接进脚本/CI）
+argo paths --check --json   # 机器读
+```
+
+它在这台机器上**实测**七件事：平台与惯例变量、状态目录解析（含来源）、状态目录
+**可写性**、密钥文件候选与可解析性（只报键数量，不回显值）、配置加载、解释器候选
+最终落到谁，以及**跨进程锁是否真的互斥**（起一个子进程握住锁，父进程再抢一次并测量
+等待时间——Windows 的 msvcrt 分支在开发机上只能用假模块测契约，只有真机跑这一条才算
+验过）。
+
+真机验证清单（Windows / BSD / 容器）：
+
+```sh
+argo paths --check                 # 目录解析 + 锁 + 解释器，一条够
+argo paths --check --json | ...    # CI 里断言 status 没有 fail
+```
+
+## 1. 状态目录的解析顺序（存量优先）
+
+| 优先级 | 来源 | 说明 |
+|--------|------|------|
+| 1 | `ARGO_STATE_DIR` | 显式覆盖：测试隔离、只读环境、想换目录的用户都用它 |
+| 2 | `config.yaml` 的 `cache.db_path` 父目录 | 与主缓存同域，保持既有语义 |
+| 3 | 历史目录 `~/.cache/unified-search`（**已存在**） | 继续用，**不迁移** |
+| 4 | 平台惯例目录 | Windows `%LOCALAPPDATA%/unified-search`；POSIX `$XDG_CACHE_HOME/unified-search` |
+| 5 | 兜底 `~/.cache/unified-search` | 即 POSIX 的 XDG 默认值，与历史一致 |
+
+**为什么「已存在的历史目录」排在平台惯例之前**：`LOCALAPPDATA` 在 Windows 上恒有值，
+`XDG_CACHE_HOME` 在部分 Linux 桌面也常被设置。若它们无条件优先，存量用户升级后会
+发现搜索缓存、配额计数、准入记录**全部「归零」**——那比「目录不够惯例」严重得多。
+想换目录的用户用 `ARGO_STATE_DIR` 或 `cache.db_path` 显式指定，一步到位且可预期。
+
+## 2. 密钥文件的解析顺序（候选合并）
+
+| 优先级 | 来源 | 说明 |
+|--------|------|------|
+| 1 | `ARGO_ENV_FILE` | 显式指定，**只读这一个**，不合并 |
+| 2 | 平台惯例 | Windows `%APPDATA%/argo/env`；POSIX `$XDG_CONFIG_HOME/argo/env`（设置了才有） |
+| 3 | 历史路径 `~/.config/argo/env` | POSIX 上它就是 XDG 默认值 |
+
+读取时**合并全部候选**（靠前者逐键优先），而不是只认第一个存在的文件。理由是本仓
+反复踩过的一类故障：`同几个变量的两套名字/两处位置` 会导致「一部分读得到、一部分
+读不到」——引擎按状态层判定可用、实际拿不到 key，表现为静默 0 结果（「装了没通电」）。
+缓存签名覆盖全部候选的 `(路径, mtime_ns, size)`，改任意一份都会触发重读。
+
+## 3. 其它平台细节
+
+| 事项 | 做法 |
+|------|------|
+| 跨进程文件锁 | POSIX `fcntl.flock`；Windows `msvcrt.locking`（锁首字节，空文件先写占位）。都不可用时 fail-open，绝不阻断主路径 |
+| 解释器探测 | `bin/argo`：`python3.x` → `py -3` / `py` / `python` / `python.exe`；`py` 是启动器，先解析成真实路径再入缓存 |
+| 配置缓存指纹 | config.yaml 用**内容摘要**（blake2b/16，0.47 ms）：`mtime` 可被 `cp -p`/`touch -r` 还原，`st_ctime` 在 Windows 是**创建时间**，两者都不能作为跨平台的失效判据 |
+| 归档脱敏 | 家目录三家平台都认：`/Users/<x>`、`/home/<x>`、`C:\Users\<x>` |
+| 临时文件 | `tempfile.gettempdir()`；不用 `/tmp` 字面量 |
+| 编码 | 显式 UTF-8（`PYTHONUTF8=1` + 全部 `read_text(encoding="utf-8")`），规避 Windows GBK |
+| 控制台 | 不依赖 ANSI 颜色；无 TTY 时输出纯文本/JSON |
+
+## 4. 存量安装怎么改成惯例目录（可选）
+
+`argo paths --migrate` 把历史目录里的状态搬到平台惯例目录，并让惯例**立即生效**：
+
+```sh
+argo paths --migrate --dry-run     # 先看会搬什么（只读，随时可跑）
+argo paths --migrate --yes         # 确认执行（不使用 TTY 探测做交互确认）
+```
+
+安全边界（这是会动用户数据的命令，默认什么都不做）：
+
+- 只在根目录由**历史默认**决定时才迁移；`ARGO_STATE_DIR` 或 `cache.db_path` 说了算时
+  直接拒绝——那是用户明确指定的位置。
+- 目标目录已有内容 → 拒绝（绝不覆盖）。
+- 不用 TTY 探测做确认：无论交互与否都要求显式 `--yes`——数据搬迁命令在脚本里
+  该有完全一致的行为（本仓也有专门门禁挡 `isatty`）。
+- 搬完清掉空的历史目录。这一步是关键：留着空目录会让 `state_root()` 继续判
+  「历史存在」而停在旧路径，用户会以为数据丢了。个别文件搬不动时保留目录并写入
+  `MIGRATED_TO.txt` 说明去处，绝不假装成功。
+
+## 5. 给贡献者的两条约束
+
+1. **状态路径只能由 `argo_paths` 派生**（各模块只声明文件名）。历史上 11 个模块各自
+   拼 `~/.cache/unified-search`，导致 `config.yaml` 管不住这些文件、测试无法整体隔离。
+2. **候选位置只能由 `argo_paths._platform_cache_root` / `engine_env._envfile_paths`
+   解析**。任何新增候选都改这两个函数，不要在别处再写一份判断——那正是「两套口径」
+   的开端，而两套口径最终一定会漂移。

package/docs/RELEASE_NOTES_v2.8.0.md

@@ -0,0 +1,71 @@
+# Argo v2.8.0 发布说明
+
+**版本**：2.8.0
+**定位**：从「帮你搜到」升级为「帮你核到」。新增证据闭环、求职搜索 v3、天气双源、通用搜索增强。
+
+---
+
+## 这次更新有什么（通俗版）
+
+### 1. 证据闭环：搜索完告诉你「哪些链接值得点开核实」
+
+**以前**：搜索给一堆结果和评分，但哪个能直接当依据、哪个得点进去看正文，全靠自己猜。核实过的链接，下次搜到也不会记得。
+
+**现在**：搜索输出会明确标记：
+
+- 金融、医疗、法律这类「说错会出事」的问题，结果自带 `fetch_required` 提示：先核验再下结论
+- 每条结果标注 `fetch_suggested`：这个链接建议点开核实（已核实过的自动跳过）
+- 用 `--verify` 一键核验：系统自动抓取正文、计算「核实前后的证据分变化」，告诉你哪些结果经得起推敲、哪些只是标题党
+- 核实过的链接会记住（URL→证据分缓存），**下次搜到同一链接自动回填核实结果**，不用重复核
+
+**实测效果**：搜「贵州茅台股价」→ 提示需要核验 → `--verify` 核验新浪财经页面 → 证据分从 0 提升到 0.42（正文里确实有数字）→ 下次再搜，系统直接显示已核实。
+
+**怎么用**：
+
+```bash
+python3 scripts/search.py "贵州茅台股价" --verify 3
+# [verify] 核验 3 条，improved=2 unchanged=1 degraded=0 mean_delta=0.18
+
+python3 scripts/research.py "台积电估值分歧" --verify 3
+```
+
+### 2. 求职搜索 v3：找工作更结构化
+
+**以前**：聚合搜索能搜到岗位，但信息散、重复多，追踪新岗位要手动反复查。
+
+**现在**（`argo job` 升级到 v3）：
+
+- **结构化字段**：岗位名称、公司、地点、薪资、发布时间统一字段，可直接喂给下游处理
+- **增量监控**：只关注新增岗位，重复的自动指纹去重
+- **更多源**：新增 Ashby ATS 免 key 后端（不少创业公司用它），补充应届生求职网与北京高校就业信息源
+
+### 3. 天气双源并行：问天气更稳
+
+**以前**：天气只有一个源，挂了就搜不到，而且不支持空气质量。
+
+**现在**：wttr.in 和 Open-Meteo 双源并行，一个挂了另一个顶上；支持地理编码（说「上海」自动定位）和空气质量查询。任何时候问天气都有结果。
+
+### 4. 通用搜索增强：多两个免 Key 可选引擎
+
+- **Parallel 搜索**（`PARALLEL_API_KEY`）：官方推荐 objective + search_queries 组合，多路召回；deep 模式自动切高级档，结果自带长文摘录
+- **You.com 搜索**（`YDC_API_KEY`）：网页 + 新闻合并，时效性强；发布时间按查询时效敏感度动态化
+
+两个引擎都接入时间窗过滤，无 Key 时自动降级不报错。
+
+### 5. 稳定性修复
+
+- `health_check` 崩溃修复（之前偶发崩溃会中断健康检查）
+- 日韩股票查询错配修复（日韩语股票查询不再串到中文行情源）
+
+---
+
+## 验证
+
+- 证据闭环：新增 `tests/test_evidence_loop.py` 20 项全过（证据提取 / 缓存隔离 / 回填 / 高后果门控 / verify 模式 / MCP 集成 / 边界守卫）
+- parallel/you：新增注册与无 Key 降级测试
+- 全量回归：810+ passed，18 skipped
+
+## 兼容性
+
+- 无破坏性变更，v2.7.x 配置与用法继续有效
+- 新能力默认开启（证据闭环随搜索输出），`--verify` 为显式触发不阻塞日常搜索

package/docs/RELEASE_NOTES_v2.8.2.md

@@ -0,0 +1,63 @@
+# Argo v2.8.2 发布说明
+
+**版本**：2.8.2
+**定位**：Windows 全平台可用 + 证据语义统一（dossier 与 wide_research 同一套门禁）。
+
+---
+
+## 这次更新有什么（通俗版）
+
+### 1. Windows 彻底可用
+
+**以前**：Windows 上 `npx -y github:taxueseek/argo` 直接报 `EBADPLATFORM` 装不上；绕过平台检查后，中文查询又会因 GBK 编码崩溃，本地搜索工具探测（`command -v` / `mdfind`）在 Windows 全失效。
+
+**现在**：
+
+- 移除 npm `os` 限制，Windows 直接安装
+- 全链路 UTF-8 防线：Node 入口注入 `PYTHONUTF8=1`，Python 入口 `-X utf8` 重启动，6 处含中文 JSON 读取改为二进制安全解析
+- 工具探测改 `shutil.which`（跨平台），无 rg 时经 Git 自带 grep 兜底
+- Ctrl+C 干净退出，不再刷 KeyboardInterrupt traceback
+- Chrome 自动发现：新增 `CHROME_PATH` 环境变量 + Windows Chrome/Edge 五个常见安装路径
+
+### 2. DSH 插件两种装法
+
+**以前**：主包没有 `dsh.bundle` 声明，`dsh plugin add github:taxueseek/argo` 只当普通依赖装，MCP 工具不激活。
+
+**现在**：
+
+```bash
+# 装法 A：仅 10 个 MCP 搜索工具
+dsh plugin --profile web add "github:taxueseek/argo"
+# 装法 B：搜索工具 + wide_research 并行研究编排
+dsh plugin --profile web add "github:taxueseek/argo#main&path:packages/dsh-plugin"
+```
+
+### 3. 证据语义统一：wide_research 也能判定「能不能下结论」
+
+**以前**：CLI/MCP 的深度研究（`argo_research`）输出自带 `quality_gate_results` 门禁，但 DSH 插件的 `wide_research` 没有，Agent 无法判断报告置信度。
+
+**现在**：`wide_research` 输出新增 `quality_gate_results`（`passed` / `conclusion_cap`：low/medium/high），与 dossier 同一套语义；`passed=false` 时必须降级表述。同时支持 `depends_on` 依赖分阶段（有定义/基线依赖的轨道不再盲目并行），并做了 SSRF 防线（仅 http(s) URL 入证据账本）与研究递归硬保护（worker 不可调用 `argo_research`）。
+
+### 4. 取证协议化（research 重构）
+
+**以前**：深度研究输出像「研究报告」，机器把检索头条当结论，Agent 容易被误导。
+
+**现在**：机器只产出 **dossier**（来源 / 覆盖 / 缺口 / 门禁 / 待核验 URL），判断稿由 Agent 按 `references/research-protocol.md` 写（事实 / 推断 / 建议 / 未知 分开）。工作包支持 `--work-packages` 按 `depends_on` 分阶段取证，不再靠扩词充问题树。
+
+### 5. 打包与供应链加固
+
+- npm 包补 `engines/`、`data/`（此前漏打包，垂直源与地理数据在 npm 安装下缺失）
+- 安装脚本新增 `ARGO_PIN` 固定 commit（curl|bash 供应链加固）
+
+---
+
+## 验证
+
+- 证据门禁 / 工作包分阶段 / 门禁谓词：python 23 项 + node 13 项全过
+- MCP initialize 握手正常，serverInfo.version = 2.8.2
+- `npm pack` 实测 247 个文件完整入包
+
+## 兼容性
+
+- 无破坏性变更，v2.8.x 配置与用法继续有效
+- 默认行为不变；新能力随输出附带，不阻塞日常搜索

package/docs/RELEASE_NOTES_v2.8.3.md

@@ -0,0 +1,55 @@
+# Argo v2.8.3 发布说明
+
+**版本**：2.8.3
+**定位**：多语言路由修复 + anysearch 进程化 + weighted RRF 融合强化。
+
+---
+
+## 这次更新有什么（通俗版）
+
+### 1. anysearch 主力引擎不再「每次启动个 Python 进程」
+
+**以前**：`anysearch` 走 `type: cli`，每次搜索都 `subprocess` 拉起一个 `python3`（解释器启动 + 模块导入约 0.2-0.3s 纯开销），且用裸 `urllib` 无 UA 轮换、无重试、无退避，高失败（限流/网络）时 error 频发。
+
+**现在**：
+
+- 改为进程内 builder（`_build_anysearch_engine`），直接复用 `HttpClient.post`（新增 JSON-RPC POST 方法，带 UA 轮换 / 指数退避 / Retry-After / Cookie 积累）
+- 省掉每次 subprocess 启动；网络失败自动重试降错
+- 修复 quota 误判：正常结果正文里出现「quota / 429 / rate limit」等词不再被误判为配额耗尽而返回空
+
+### 2. 多语言查询终于返回「目标语言」结果
+
+**以前**：日语/韩语查询常被中文泛内容域或中文引擎「污染」——韩文「연준 금리」返回「皇室战争卖号」、日文「政策金利」返回「frb_百度百科」；德法西意查询依赖运气。
+
+**现在**：
+
+- **语言门控**：日/韩查询不再误入中文泛内容域（chinese_general / weather 单音节误爆等）
+- **中文引擎双层过滤**：域命中路径 + TF-IDF 路径都对 ja/ko 剔出中文内容/新闻/金融/技术引擎（octen / tencent_kline / gov_policy / bocha 等）
+- **anysearch 多语言兜底**：ja/ko 宏观返回日语「2026年FRB・ECB・日銀」、韩语「연준 금리 동결…FOMC」；德法西意走 anysearch 返回法语「BCE et taux d'intérêt」、意语「Calendario 2026 BCE」
+- **Bing `mkt` 市场码**：`local_bing` 追加市场码（比 `setlang` 更强制区域），辅助缓解 ja/ko 返回中文站
+- **语言偏好软排序**：ja/ko 查询前置含目标语言字符的结果，不误删
+
+### 3. 融合更看重「可靠」的引擎（weighted RRF + weakest-link）
+
+**以前**：RRF 融合虽有静态加权（权威提权、社交降权），但一个「弱引擎」（熔断中、高错误、空结果多）的结果仍会掺杂进融合，拖垮整体精度——论文 2508.01405 的「weakest-link 现象」。
+
+**现在**：`_engine_weight` 升级为 **静态基础权重 × 动态可靠性因子**：熔断（disabled/open/half_open）与高错误引擎自动降权（duckduckgo 熔断 0.5、健康权威源 wikipedia 1.4、社交 0.7），弱检索路径不再拖累融合。
+
+---
+
+## 技术细节
+
+- `HttpClient.post()`：JSON-RPC / JSON POST，`_do_post` 独立实现（不碰 GET 热路径），gzip/br 解压、重定向跟随、SSRF 防护、curl fallback
+- `_build_anysearch_engine`：POST `api.anysearch.com/mcp`，解析 Markdown 结果块，quota 沉底检测
+- `route.py _JA_KO_CN_ENGINES`：ja/ko 域命中路径过滤中文引擎
+- `search.py _single_reliability()`：30s TTL 缓存的断路器可靠性因子（weakest-link）
+- `lang_detect.py`：`ENGINE_LANG_PARAM_VALUES` 增补 `mkt`（Bing 市场码）
+- 引擎对比（多语言宏观 × 研报，32 次）：byted 最快（383-736ms 目标语言）、bocha 中文/韩语快、anysearch 稳健、local_bing 对 ja/ko 差（已用 anysearch 兜底）
+
+## 依赖
+
+不变（PyYAML 必需；curl_cffi / Chrome 可选）。
+
+## 测试
+
+核心测试全过（test_multilingual 70、test_multilingual_routing 10、route/engine/breaker 317）；全量 885+ passed（仅环境网络 SSL 波动的端到端测试可能 flaky，非代码回归）。

package/docs/RELEASE_NOTES_v2.8.4.md

@@ -0,0 +1,79 @@
+# Argo v2.8.4 发布说明
+
+**版本**：2.8.4
+**定位**：深度研究本地数据融合 L1 + 多客户端 MCP 一键接入 + 结构化搜索增强 + Keenable 接入 + 安全加固。
+**相对上一版的改进**：本地一手数据能入账、MCP 接入从「手改配置」变成「一条命令」、搜索命中率与成本控制增强、引擎覆盖加一个、recompute 断网承诺真正成立。
+
+---
+
+## 这次更新有什么（通俗版）
+
+### 1. 深度研究终于能吃「你本地的数据」
+
+**以前**：`argo research` 只能吃 URL / 网页文本，你手里的一手数据（CSV / XLSX / 文献 PDF）进不了研究账本，也没法对数字做「可重算」核验。
+
+**现在**（P0-1 / P0-2，深度研究 L1 已落地）：
+
+- 工作包可带 `file_inputs`（本地一手数据，白名单制：仅显式声明文件可入账，内容不入账、只登记路径 / sha256 / 性质 / 角色，dossier 输出 `local_sources` 章节）
+- 工作包可带 `recompute`（可复算执行器：只读挂载输入 → 受限子进程执行计算脚本 → 输出 `{ok, exit_code, stdout, elapsed_ms}`，重算值进 dossier `recomputed_values`）
+- 门禁闭环：重算值能与检索到的手数字对上 → 标 `recomputed`；冲突命中 `recompute_conflict`（结论上限 medium）；声明可复算但没跑成 → `recompute_skipped`
+- 本地一手计入一手命中，修复「明明给了原始数据，却判 `no_sources`」的假阴性
+- 配合插件 `wide_research`：worker 侧 `file_inputs` 入账、recompute 契约执行、`quality_gate_results` 同步这些门禁
+
+### 2. 给各种 Agent 挂 MCP，一条命令搞定
+
+**以前**：要给 Claude Code / Cursor / Windsurf / Codex / OpenCode / Cline 挂 argo MCP，得人肉改各家 JSON/TOML 配置，容易写错、易覆盖、难还原。
+
+**现在**：
+
+- 客户端描述真源 `mcp/clients.yaml`（加一个客户端 = 加一行 YAML，不改代码）
+- `argo mcp status` 诊断各客户端（已安装 / 已配置 / 未安装）
+- `argo mcp inject --all` 一键注入所有已安装客户端（原子写 + 写前自动备份到 `~/.argo/mcp-backup/` + 含密钥配置 0600 权限）
+- `argo mcp undo --all` 精确移除 entry 或从备份回滚；`--dry-run` 只预览不写
+- JSON 走 patch 保留未改动子树、TOML 走行级 append 不破坏手写注释
+
+### 3. 简单问题不再被「多轮恢复」拖慢
+
+**以前**：搜索空结果时的恢复流程，对「简单查询」也可能一路放到高价多源 / 跨语言，浪费 token 和时间。
+
+**现在**：
+
+- 查询归一化：全角→半角、点号版本号拆斜杠、压多余空格，让型号 / 版本 / 分隔符更易被精确源命中
+- 复杂度门控：低复杂度查询只允许低成本放宽（L1/L2），禁掉高价多源 / 跨语言（L3/L4）
+- 检索变体：首轮多路召回，复杂问题才走多轮
+- social 域优先：`from:/subreddit:/lang:/filter:` 等平台语法命中时把社交域提前（不再被查询里的实体词抢走）
+- TF-IDF 检索修复：日 / 韩语查询丢弃中文引擎候选后继续看 top-2/3（旧逻辑只查 top-1，可能漏掉合格候选）
+- `--include-local`：联网结果尾部并入本机文件命中（默认关，零成本开）
+
+### 4. 引擎覆盖加一个（Keenable）
+
+接入通用网页搜索引擎（L1 声明式 HTTP，`ARGO_KEENABLE_API_KEY`）。当前为免费体验期、量较大、按 free 源对待（auto/fast 均可，不参与 budget 成本过滤）。免费期结束或出问题时直接置 `enabled: false` 停用即可，不做「到期自动切付费」的脆弱逻辑。
+
+### 5. 安全加固
+
+- **recompute 断网承诺真正成立**：此前纯 Python socket 层断网挡不住 `subprocess.run(['curl',…])` / `os.system(...)` 这类出网通道；现在 meta_path 拦截 `subprocess/multiprocessing/ctypes/pty/pexpect` 导入 + 覆盖 os 进程 / 执行入口，封死外部进程出网
+- **主机路径单真源化（安装感知、全链路无硬编码）**：清掉三处写死的主机路径——
+  1. **local-seek 发现收敛到一处**：曾散落在 `search.py`（只查仓库真源）与 `mcp_handlers.py`（硬编码 `~/.agents/skills/`、`~/.claude/skills/`）两处、各执一词易漂移。现抽成 `scripts/seek_locator.py` 统一发现：`ARGO_LOCAL_SEEK_PATH`（显式文件）> `ARGO_LOCAL_SEEK_ROOTS`（显式候选根，os.pathsep 分隔）> 打包子技能（`<ARGO_ROOT>/sub-skills/local-seek`，作兜底），`search.py` 与 `mcp_handlers._seek_py()` 共用。
+  2. **config.py DEFAULT_CONFIG 的 anysearch**：旧的 `type: cli` + `cmd: ~/.agents/skills/anysearch-skill/...` 是过时回退（anysearch 早已改进程内 `type: anysearch` builder），现对齐真源去掉主机路径。
+  3. **mcp_server.py `--test` 自测**：`argo_local_search` 的搜索目录从写死 `~/.agents/skills` 改为安装锚点（argo 根目录，恒存在）。
+- **install.sh 修正**：npx 入口从 `npx -y argo-search`（会拉到 npm registry 上的陈旧 v1.0.1）改为 `npx -y github:taxueseek/argo`（GitHub 唯一真源），与 README/SKILL/ARGO_INTRO 对齐
+
+---
+
+## 技术细节
+
+- `scripts/mcp_setup.py`：自研零第三方依赖的 MCP 注入/诊断/还原；`atomic_write`（同目录 temp + `os.replace`）、写前备份、TOML 行级 append、JSON patch 保留未改动子树
+- `data` 融合栈：`scripts/research_work_packages.py`（`file_inputs` / `recompute` schema + 归一化）、`scripts/research_dossier.py`（`local_sources` / `recomputed_values` 入账）、`scripts/research_gates.py`（`recompute_skipped` / `recompute_conflict` 门禁）
+- `scripts/recompute.py`：fail-closed 可复算执行器（默认拒绝，需显式授权；白名单只读输入、断网 + 禁外部进程、RLIMIT_AS 内存软限、进程组 killpg 超时硬杀、全新临时工作目录）
+- `scripts/query_enhance.py`：纯规则改写的查询归一化 + 变体 + 复杂度门控（无 LLM 依赖）
+- `scripts/single_flight.py`：线程版单飞合并，并发相同引擎调用只打一次上游
+- `packages/dsh-plugin/dsh/index.js`：新增 `argo_local_read` / `argo_recompute` 工具白名单、`local_sources` / `recomputed_values` schema、本地一手计数入一手命中、recompute 门禁
+- 引擎：`engines/specs/keenable.yaml`（L1 声明式 HTTP）
+
+## 依赖
+
+不变（PyYAML 必需；`curl_cffi` / openpyxl（读 xlsx 的可选）/ Chrome 可选）。
+
+## 测试
+
+全量 1000 项（982 passed + 18 skipped），新增：query_enhance 斜杠语义回归、recompute 外部进程/`os.system` 阻断等。仅依赖真实网络与 API Key 的端到端用例可能因环境波动 flaky，非代码回归。

package/docs/RELEASE_NOTES_v2.8.5.md

@@ -0,0 +1,102 @@
+# Argo v2.8.5 发布说明
+
+**版本**：2.8.5
+**定位**：DSH 插件工具原生化 + MCP 默认关闭 + Windows 全平台兼容（社区贡献）+ 配额自愈闭环 + 抓取降级链全局 deadline + 审查加固。
+**相对上一版的改进**：插件接入从「挂 MCP」变成「原生工具默认可用」；MCP 从「默认挂载」变成「按需开启」；Windows 从「能跑」变成「开箱即跑」；配额用尽自动切换备用源；抓取不再无限叠加超时。
+
+---
+
+## 这次更新有什么（通俗版）
+
+### 1. DSH 插件工具原生化：不挂 MCP 也能用上 argo 搜索
+
+**以前**：DeepSeek Harness（DSH）里要用 argo 的搜索/抓取，得先挂载 14 个 MCP 工具——常驻连接、占配置、开启有负担。
+
+**现在**：
+
+- `argo_search` / `argo_fetch` 以**原生一等工具**注册（`ctx.tools.register`），默认即可用，不依赖 MCP 连接——CLI 单发执行（`mcp_server.py --call` / `bin call`），与 MCP 同引擎、同压缩、同守卫
+- 工具 schema 由 `scripts/gen_native_tools.py` 从唯一真源（`scripts/mcp_tools.py`）自动生成，Python 与 JS 两侧措辞/参数零漂移（`tests/test_native_tools_sync.py` 门禁把关：改 schema 不重新生成，测试直接红）
+- 除 `argo_research` 外全部 13 个工具都可通过 `nativeTools` 配置按需启用为原生工具（默认只开 search/fetch，零常驻 token 开销；未知工具名 loud fail）
+
+### 2. MCP 默认关闭，三形态按需开启
+
+**以前**：DSH 主包默认挂 argo MCP，工具描述全部进系统提示词，不用也在花 token。
+
+**现在**：DSH 插件三形态接入、互为冗余，按宿主能力自动降级：
+
+1. `mcp__argo__*`：profile 按需挂载的 stdio MCP，完整 14 工具面（**默认关**，要用在 profile patch 里开）
+2. 原生一等工具 `argo_search` / `argo_fetch`：CLI 单发，不依赖 MCP 连接（**默认入口**）
+3. 原生 `web_search` seam：注册 "argo" provider，内置 web_search 经 argo 引擎链路由（默认启用）
+
+MCP 开关回归默认关闭——需要完整工具面时一条 profile patch 打开，平时零常驻开销。
+
+### 3. Windows 全平台兼容（社区贡献 PR #11，感谢 HiSeax）
+
+**以前**：不少路径与工具写死 macOS 假设——`/tmp` 直拼、`python3` 可执行名、locale 编码读 YAML、`os.symlink` 要权限，Windows 上要么崩要么静默失效。
+
+**现在**（Windows 10/11 + Python 3.13 实测）：
+
+- 临时文件统一走 `tempfile.gettempdir()`（Chrome 用户目录、截图输出）
+- HTML 引擎解析映射显式 `encoding="utf-8"` 读取（修复 Windows GBK 下静默失效）
+- CLI 引擎解释器运行时解析：`python3` → `python` → `sys.executable`
+- Skill 链接在无开发者模式时自动退化为 junction（`mklink /J`，无需管理员权限）
+- 新增 PowerShell 一键安装 `scripts/install.ps1`（与 install.sh 对齐）
+- local-seek 的 `--spotlight` 在无 mdfind 平台自动退化为 rg 正文搜索
+
+### 4. 配额自愈闭环：引擎用尽自动切备用源，周期结束自动回归
+
+**以前**：远端配额耗尽（如火山 10406 Free quota exhausted）以 HTTP 200 + 空结果静默通过，路由继续把流量打向死引擎，等人工改配置。
+
+**现在**：
+
+- HTTP 200 响应体里的业务错误封套（火山 `ResponseMetadata.Error`、知乎 `Code/Message`）被识别透出，不再「配额用完当没结果」
+- 识别为配额耗尽 → `quota.mark_remote_exhausted` 标记 → 路由全模式排除该引擎、备用源自然接管
+- 到配额周期边界惰性自愈，恢复后引擎自动回归；充值后可 `python3 scripts/quota.py reset <engine>` 提前恢复
+- 配额/鉴权类错误不再计入自适应学习分数（防止「配额期连败毒化分数、恢复后永远翻不了身」的死锁）与熔断统计
+
+### 5. 抓取降级链全局 deadline：延迟有一等公民约束
+
+**以前**：抓取降级是「延迟换成功率」，各级独立超时加法无上限（8+8+8+12+8+15≈59s+），可能击穿 MCP 客户端工具超时。
+
+**现在**：
+
+- 全局 deadline（`ARGO_FETCH_DEADLINE_S`，默认 60s，0 关闭）：每级升级前检查剩余预算，耗尽即停链返回当前最优结果并打 `deadline_exhausted` 标记
+- 429/503 明确停止信号：收到后不再升级重链，不无视服务器指示放大目标负载
+- tinyfish 免费渲染层（markdown 直出、含 JS 执行，`ARGO_FETCH_TINYFISH=0` 关闭，需 `TINYFISH_API_KEY`）：HTTP/指纹层失败时优先于本地 Chrome，爬取场景（need_html）自动跳过
+- 客户端形态分流：抖音类站点移动 UA 首发 + per-host 身份记忆（TTL 24h），减少风控试错
+- `{url}.md` AI 友好变体探测：头部文档站命中即跳过整条反爬降级链（`ARGO_FETCH_MD_VARIANT=0` 关闭）
+
+### 6. 密钥与状态基建（对用户透明，但值得知道）
+
+- **密钥热读**：`~/.config/argo/env` 作为 env 文件真源（os.environ 优先），改文件即生效无需重启；search 引擎与 fetch 渲染层同真源，修复「search 能用、fetch 渲染层静默禁用」的分裂
+- **本地状态目录单一真源**（`scripts/argo_paths.py`）：11 个模块各自拼 `~/.cache/unified-search` 的分裂拼法收敛为一处，`ARGO_STATE_DIR` 可整体隔离（测试/只读环境）
+- **热生效基建**（`scripts/hot_state.py`）：代码/配置变更指纹自检 + `os.execv` 自重启（stdio 跨 exec 继承不断连），密钥/配置/注册表 mtime 热读；`ARGO_NO_AUTORELOAD=1` 关闭
+- **缓存层降级不拖垮调用方**：目录不可写/数据库只读时缓存自动降级为 no-op（只该变慢，不该变错）
+
+### 7. 审查加固（本轮 code review 修复）
+
+- `mcp_handlers` 三处内联夹取统一走 `_clamp_int`（修复传 0 时语义不一致）
+- 配额错误关键词单一真源 `_QUOTA_ERROR_KEYWORDS`（熔断分类与自适应跳过共用，防口径漂移）
+- 语言感知排序的移尾形状提取 `_move_to_tail`
+- DSH 共享 MCP 连接的 `request` 内建超时并同步清理 pending entry（修复超时后 entry 泄漏到进程关闭）
+
+---
+
+## 升级方式
+
+```bash
+# macOS / Linux
+curl -fsSL https://raw.githubusercontent.com/taxueseek/argo/main/scripts/install.sh | bash
+
+# Windows（PowerShell，本版新增）
+# 建议先落盘再本地执行（RemoteSigned 放行本地脚本；远程 `irm|iex` 直接执行有供应链投毒面，
+# 且 `-ExecutionPolicy Bypass` 被微软安全基线反对）。
+irm -OutFile scripts/install.ps1 https://raw.githubusercontent.com/taxueseek/argo/main/scripts/install.ps1
+powershell -ExecutionPolicy RemoteSigned -File scripts/install.ps1
+# 若因下载文件 MOTW 被拦：Unblock-File scripts\install.ps1
+
+# 已装过：进仓库目录拉取即可
+git pull --ff-only
+```
+
+依赖不变：Python 3.10+（PyYAML），可选 curl_cffi（TLS 指纹伪造层）。已装 DSH 插件的，`dsh plugin add github:taxueseek/argo` 更新即得原生工具形态；MCP 想开回完整工具面在 profile patch 里挂 `mcp-argo` 即可。