argo

一句话定位

把 Argo 阿尔戈多语言搜索与证据核验 MCP 接入 DSH，让模型在对话里直接调用 10 个联网搜索、抓取、深度研究类工具，输出精简 JSON 而非长网页。

核心能力

• 统一搜索：按语言、领域、意图自动选路，多引擎并行召回、RRF 融合，输出带权威性、证据密度、时效性打分的精简 JSON
• 深度研究：把复杂问题拆成多个子问题，多源并行采集，给出还差什么证据的缺口提示
• 智能抓取与站点爬取：HTTP 优先、反爬时升级浏览器；支持 BM25 聚焦提取、表格与 JSON-LD 结构化抽取
• 文档与本地检索：把 PDF 转成 Markdown、把网页转成图片；非联网扫本机代码/笔记/技能库
• 社交平台搜索：覆盖 Hacker News、知乎、B 站、V2EX 等，支持帖子列表与舆情聚合两种模式
• 意图消歧：识别「苹果」「Python」等多义词，给出搜索策略建议

技术实现

• 语言: Python 3.10+（核心）+ Node.js 18+（仅作 npx 启动壳）
• 关键依赖: PyYAML（必需）、curl_cffi（可选）、pdfplumber 或 PyMuPDF（PDF 用）、Chrome / Playwright（截图与 JS 渲染页用）
• 架构模式: DSH 通过 @deepseek-ai/dsh-mcp-client 以 stdio 方式拉起 npx -y github:taxueseek/argo，Node 壳 bin/argo.js 再 spawn 出 Python scripts/mcp_server.py，10 个工具的 schema 唯一真源在 scripts/mcp_tools.py
• 入口文件: bin/argo.js（Node 启动器）/ scripts/mcp_server.py（MCP 协议聚合）/ packages/dsh-plugin/cordis.patch.yml（DSH bundle patch，唯一真源声明 10 个 mcp__argo__* 工具的注册 id mcp-argo）

适用场景

在 DSH 里做研究、查行情、看学术论文、抓反爬站点、跨语言问答时，把这个插件打开就行。如果你希望模型不要每次都泛搜网页标题，而是直接拿到带可信度评分的精简结果、并且能按需拆分子问题做深度调研，这套能力正好对应。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:taxueseek/argo

配置项

常见问题

Q: 安装后我能在 DSH 里看到什么？

A: 重启 dsh web 后，模型侧会多出 10 个以 mcp__argo__ 开头的能力，包括统一搜索、本地文件搜索、深度研究、可信度评估、意图消歧、页面抓取、站点爬取、页面截图、PDF 提取、社交平台搜索。

Q: 必须配置 API Key 才能用吗？

A: 不需要。Argo 内置大量免费与本地引擎，未配 Key 时自动走零成本路径；配了 Tavily、Bocha、Metaso 等 Key 后部分引擎结果质量更高。

Q: 它依赖 Python 吗？

A: 是的。Node 启动器只是个壳，真正跑逻辑的是 scripts/mcp_server.py 这个 Python 进程。本机需要 Python 3.10+ 并安装 PyYAML。macOS 自带 3.9 不可用时，用 ARGO_PYTHON 指向 3.10+ 解释器。

Q: 想用本地源码而不是从 GitHub 拉取，怎么做？

A: 在 profile 的 cordis.patch.yml 用户层用相同 id（mcp-argo）覆盖默认配置，把 command 从 npx 换成 python3 并指向本地 scripts/mcp_server.py 路径即可，Cordis 同 id 最后写入者胜。

Q: 数据存哪？怎么清缓存？

A: 查询缓存写到 ~/.cache/unified-search/cache.db（SQLite），TTL 按域分级（金融 5 分钟、新闻 10-15 分钟、研究 2-24 小时）。登录态结果单独隔离不进公共缓存。删除该文件即可清空缓存。

Q: 社交平台搜索为什么有时返回空？

A: Hacker News / 知乎、B 站、V2EX 零密钥即可用；Twitter、Reddit、微博、小红书需要外部登录态或第三方 API，未配置时会回退为空。社交结果不进入公共缓存，避免污染主搜索。

Q: argo_fetch 和 argo_pdf 是同一回事吗？

A: 不是。argo_fetch 抓 HTML 页面（HTTP 优先，反爬时升级浏览器），遇到 PDF Content-Type 会直接返回「PDF not supported」；PDF 请走 argo_pdf，它走 pdfplumber 或 PyMuPDF 把 PDF 转成 Markdown。

Q: 这个插件支持哪些平台？

A: package.json 的 os 字段声明了 darwin 和 linux；Windows 上 npx 入口会自动 fallback 到 python 命令，Python MCP 核心本身跨平台，但 Chrome 截图等可选能力依赖图形环境。

上手难度

入门 — 一行安装命令就能跑，免费引擎够日常使用；想进阶再去看预算模式、时间窗、深度研究、登录态子技能（ego-search，默认关闭）。

已知问题与限制

• 轻量 HTTP 抓取器（scripts/fetch.py）遇到 PDF Content-Type 会直接返回 PDF not supported 错误；要处理 PDF 必须使用独立的 argo_pdf 工具
• argo_social_search 中的 Twitter / Reddit / 微博 / 小红书依赖外部登录态或第三方 API，未配置时返回空；零密钥可用平台仅为 Hacker News、知乎、B 站、V2EX
• package.json 的 os 字段仅声明 macOS 与 linux；Windows 上 bin/argo.js 通过 process.platform === 'win32' 改用 python 命令兜底，但可选的浏览器抓取能力在无图形环境时不可用
• argo_fetch 走反检测浏览器降级（Patchright/Cloudflare 绕过）时，依赖系统安装的 Chrome 或 Playwright；缺失时会从 HTTP 抓取失败回退为空
• 源码中未发现 TODO / FIXME / HACK 注释；上述限制均来自 README、mcp_tools.py schema 说明与 package.json 字段声明

中文 · English · 日本語 · 한국어 · Español

介绍 · 对比 · 证明 · 机制 · 快速开始 · 能力 · 配置 · 更新

---

它和「模型自带搜索 / AI 搜索 / 聚合搜索」比，强在哪

简单来说：前三种方案解决「人找信息」，Argo 解决「Agent 及搜索核查于一身，具备一条龙的搜索服务」。差别不在界面，在交付物，给人看的叫总结页或链接清单，给 Agent 的应是能排序、能复核、不撑爆上下文的优质内容，更可靠的搜索信息。

机制上，Argo 把搜索当成一条证据管线：语言检测 → 领域路由 → 多引擎召回 → RRF 融合 → 证据快评，交付的是 Agent 可直接排序、可 fetch 复核、不撑爆上下文的材料。工具链不用换，需要换的是「搜索结果应该长什么样」——再往下一层，还有和「再包一层搜索 API 的差别」，那是实现细节的对比。

---

这是什么

Argo 是给 AI Agent 用的多语言搜索基础设施。

真实检索从来不是「一种语言 + 一个搜索框」：有人问 A 股行情，有人问 World Cup，有人用日文找动画，有人要 IMDb 上的导演信息。Argo 的出发点很朴素——按领域、按语言、按需求选路，把问题送到合适的源，而不是一律扫网页标题。联网搜索与本机文件搜索一体可用。

产出不是「链接清单」，而是「证据候选 + 可信度分解」。路选对了，证据才站得住。

和「再包一层搜索 API」的差别

---

问啥像啥

---

它怎么工作

查询
  ├─ 意图消歧（可选）
  ├─ 查询改写（可选；路由仍看原始意图）
  ├─ 语言检测 + 语言偏好
  ├─ 路由（域规则 + TF-IDF + 预算 + 语言补充源 + 热路径缓存）
  ├─ 多引擎召回（熔断 / 负缓存 / 并行）
  ├─ 空结果分阶恢复（放宽 → 换同族/通用 → 跨语言；防污染）
  ├─ RRF 融合 + 可选精排
  ├─ 证据快评（权威 · 证据密度 · 时效 · 共识）
  └─ 统一 JSON（含 engine_outcomes / recovery）

证据评分（简版）

selection  ≈ 域名权威，SERP/跳转链压到很低
absorption ≈ 数字 / 定义 / 对比 / 披露等证据密度
freshness  ≈ 发布时间（会忽略「2015 年以来」这类历史对比年）
综合       ≈ 0.40·selection + 0.35·absorption + 0.15·freshness + 0.10·引擎分

结果字段含 selection、absorption、credibility_fast、evidence_flags 等，方便 Agent 直接排序。

Agent 使用纪律（建议）

1. 高后果问题（持仓、安全、是否属实）：search → 看快评分 → 对 top 结果 fetch → 再下结论
2. 数字：写清口径，冲突时并列，不要硬合并
3. 搜索结果页 / 跳转链：不要当正文信源
4. 社交帖：当舆情与叙事，不当事实真值
5. 事实核查：宁可多一两条分层查询（来源 / 对比 / 主体）

---

快速开始

任选一种即可。不依赖 npm 官方包也能用最新版（v2.5.1 起以 GitHub 为安装真源；当前推荐 v2.8.0。npm registry 上的旧包可能滞后，可不走）。

零配置就能跑：不配 API Key 时走免费引擎 + 本地 local_* 引擎；配了 Key 的源质量通常更好，没配则自动跳过。

方式一：一键脚本（推荐本机长期用）

curl -fsSL https://raw.githubusercontent.com/taxueseek/argo/main/scripts/install.sh | bash

装到指定目录、并挂 Skill 入口：

curl -fsSL https://raw.githubusercontent.com/taxueseek/argo/main/scripts/install.sh \
  | bash -s -- --home "$HOME/.local/share/argo" --link "$HOME/.claude/skills/argo"

验证：

python3 ~/.local/share/argo/scripts/search.py "贵州茅台股价" --json
python3 ~/.local/share/argo/scripts/search.py --list-engines

方式二：MCP 不装包，直接用 GitHub（推荐 Agent 快速挂载）

需要 Node.js 18+ 和 Python 3.10+，首次执行一次：

pip3 install pyyaml

npx -y github:taxueseek/argo

客户端配置示例（Claude Code / Cursor / Kimi 等）：

{
  "mcpServers": {
    "argo": {
      "command": "npx",
      "args": ["-y", "github:taxueseek/argo"]
    }
  }
}

DeepSeek Harness 一键插件（.dsh-plugin bundle）

在 DeepSeek Harness 里一行安装，模型直接获得 10 个 mcp__argo__* 工具：

dsh plugin --profile web add "github:taxueseek/argo#main&path:packages/dsh-plugin"

重启 dsh web 后生效。包结构见 packages/dsh-plugin/；同 id mcp-argo 可在用户层 cordis.patch.yml 覆盖（如改用本地源码路径）。

依赖清单（通俗版）

安装脚本（install.sh）只自动装前两个；其余可选依赖按需 pip install 或 brew install 即可。 更稳、完全不依赖 Node 的写法：先装脚本（方式一），再指向本机 Python：

{
  "mcpServers": {
    "argo": {
      "command": "python3",
      "args": ["/path/to/argo/scripts/mcp_server.py"]
    }
  }
}

Python 路径特殊时：export ARGO_PYTHON=/path/to/python3（仅 npx 入口会读）。

方式三：git clone（开发 / 改源码）

git clone https://github.com/taxueseek/argo.git
cd argo
pip3 install pyyaml
bash scripts/install.sh --link ~/.claude/skills/argo   # 可选
python3 scripts/search.py --list-engines

---

适用平台

安装后自检

python3 --version          # 需要 3.10+
python3 -c "import yaml; print('PyYAML OK')"
python3 -m pytest tests/test_unit.py -q   # 可选
python3 scripts/search.py --list-engines

---

能做什么

五种能力，通俗说

1. 通用搜索 + 垂直搜索，双管齐下

日常问题走通用网页搜索；一问到行情、影视、体育、宏观这类「有标准答案」的问题，自动切到垂直源直接给答案，而不是扔给你一堆链接。目前约 120+ 个源、60+ 业务域，金融 / 宏观 / 影视 / 体育 / 地理 / 组织 / 媒体 / 化学 / 学术 / 代码等都有专门的路。

2. 缓存：不重复花冤枉钱

时效性没那么强的内容（百科类、历史数据这类），第一次查完会进缓存，之后同样的查询直接命中，不再每次都走一遍 API。双层缓存（内存 + SQLite），热查询约 10ms 级返回，既省钱也省时间。

3. 专为 Agent 设计，更省 Token

产出是「证据候选 + 可信度分解」的精简 JSON，不是长篇网页；MCP 响应可以按需裁剪，snippet 可控，不会撑爆 Agent 的上下文。比常规模型自带的搜索能力更专业、更省 Token。

4. 深度研究

把一个笼统的问题拆成多个子问题，多源并行采集，最后给出「还差什么证据」的缺口提示。适合综述、调研这类要全面、要扎实的场景。

5. 登录态专业搜索（专业模式，默认关闭）

知乎、小红书、公众号这类要登录才能看的内容，以及 JS 渲染页、反爬页，用真实浏览器配合登录态去搜。默认关闭，需要时开启，依赖 ego lite 和 WebBridge 两个东西，详见下节「登录态专业搜索」。

6. 时间能力（时间窗 + 方向排序）

要搜「最近几天刚发布的内容」，用 --since 7d 这类时间窗框住发布时间范围，判断新旧不再靠猜。支持引擎（如 realtime_index，免 Key 实时索引源，结果自带发布时间）把窗口下推给数据源；其余引擎的融合结果会按 published_at 兜底剔除明确超窗的条目（宽松策略，无时间字段的保留），返回包带 time_filtered 统计，CLI 与 MCP 均支持。--since 7d 与「7 天前的绝对日期」等价、共享缓存；--until 2026-08-01 含当天。配合 --sort newest|oldest 按发布时间重排——找最新动态用 newest，找最早出处用 oldest。

能力入口速查

预算模式

当前大致能力（v2.8.0）

• 证据闭环（v2.8.0 新增）：搜索输出自带证据门控——高后果问题（金融/医疗/法律）标 fetch_required，每条结果标 fetch_suggested；--verify 一键核验正文并回填「核实后证据分」，核实过的链接自动记住，下次搜索直接显示已核实
• 求职搜索 v3（v2.8.0 升级）：argo job 结构化字段 + 增量监控 + 指纹去重，新增 Ashby ATS 免 Key 后端与北京高校就业源
• 天气双源并行（v2.8.0 升级）：wttr.in + Open-Meteo 双源，地理编码 + 空气质量，问天气不落空
• 通用搜索增强（v2.8.0 新增）：Parallel 搜索（长文摘录、多路召回）与 You.com（网页+新闻合并、时效动态化），无 Key 优雅降级
• 约 150+ 个搜索源、70+ 业务域：通用网页 + 金融 / 宏观 / 影视 / 体育 / 地理 / 组织 / 媒体 / 化学 / 学术 / 代码等（真源：config.yaml）
• 垂直结构化模态卡：火车票 / 油价 / 贵金属 / 万年历 / 星座 / 手机参数 / 汽车 / 医疗挂号等查询返回实时结构化卡片（modal_card 域 → bocha_ai 原生引擎，失败自动回落 web 搜索）
• 双层缓存：内存 LRU + SQLite 持久化，时效性弱的内容不重复打 API；登录态结果单独隔离，不污染公共缓存
• 为 Agent 节省 Token：MCP 响应可紧凑裁剪、snippet 可控，输出为精简 JSON 而非整页文本
• 10 个 MCP 工具：搜索、研究、证据、消歧、抓取、截图、PDF、社交舆情、本地文件搜索、站点爬取
• 多语言搜索：中、英、日、韩、西里尔、泰、阿、希伯来、希腊、天城体等；路由与引擎参数跟着语言走；非中文查询避免误入知乎 / 搜狗微信 / A 股快照等中文专用源
• 登录态专业搜索：ego-search 子技能，登录墙正文 / JS 渲染页 / 登录站点接口直取（默认关闭，见上节）
• 垂直域门禁：空结果恢复时不把 pypi / npm / 快讯等无关源「串」进影视、体育查询
• 日常更快、研究更全：engine_policy 分层——日常 combo 收紧，deep / research 再放开长尾源
• 引擎层 HttpClient 接入（v2.7.3 追加）：HTTP/HTML 引擎 GET 统一走 UA 轮换 + 重试 + 重定向跟随层，arxiv 类 UA 敏感引擎从 5s 超时空返回变为 2s 内 10 条有效结果；ARGO_ENGINE_HTTP_CLIENT=0 回退 urllib
• TF-IDF 强语义注入（v2.7.3 追加）：marginalia / open_meteo / usda / gov_policy / cnii 等 25 个垂直引擎不再被正则域压制——「独立博客 长尾」路由到 marginalia、「营养成分 热量」路由到 usda、「国务院 政策」路由到 gov_policy
• 70 域 TTL 全覆盖（v2.7.3 追加）：实时卡片/快讯/行情缓存 5-15 分钟（此前 1 小时），学术稳定型放宽到 2 小时
• 垂直源中英双语（v2.7.3 追加）：worldbank / eurostat 英文国家与指标名（China GDP / US inflation / Japan population 实测命中）；快讯类引擎触发词放行全量榜单；百科条目页直接命中兜底

---

引擎与路由

当前配置大约 120+ 个源、60+ 业务域（以 config.yaml 与 --list-engines 为准）。

直连与垂类（节选）

本地零成本层（local_*）

不依赖独立的 SearXNG 服务。主路径用进程内 HTML / RSS / JSON 解析（如 local_bing、local_sogou、local_google、local_arxiv 等）。多语言查询时，路由会按语种动态改写引擎语言参数（例如 Bing setlang），并参与 RRF 融合。

登录态专业搜索（ego-search，默认关闭）

普通搜索拿不到知乎、小红书、微博、公众号等需要登录的内容，也常抓不回来 JS 渲染页 / 反爬页。ego-search 用真实浏览器去做这类搜索：继承登录态、抓登录墙后的正文、在已登录站点直接调接口取数据（如知乎搜索接口）。

默认关闭，需要时开启（在 argo 目录下运行）：

python3 sub-skills/ego-search/scripts/ego_search.py enable

常用命令：python3 sub-skills/ego-search/scripts/ego_search.py status（查看状态）、... disable（关闭）、search / fetch / api（分别对应浏览器搜索、抓正文、调站点接口）。

依赖（装好其中一个就能用，两个都装更好）：

登录态搜到的结果不写公共搜索缓存（避免污染共享缓存），需要融合时用 merge 命令把常规结果和登录态结果放一起分析。

---

使用示例

金融

python3 scripts/search.py "贵州茅台股价" --explain
# 典型：命中 stock_query → 行情快照源

学术

python3 scripts/search.py "transformer attention mechanism paper" --json
# domain 常为 academic，引擎组合含 arxiv 等

研究与核验

python3 scripts/research.py "2026 公募基金二季报 持仓结构" --depth deep --json

python3 scripts/search.py "同一查询" --json | \
  python3 scripts/evidence.py "同一查询" --stdin --json

MCP 工具一览（10）

---

安装与配置

环境要求

API Key（全部可选）

不配置则跳过对应引擎，免费引擎自动兜底。请用环境变量，不要把真实 Key 写进仓库或贴到 Issue。

# 推荐（提升搜索质量）
export TAVILY_API_KEY="你的密钥"
export BOCHA_API_KEY="你的密钥"
export METASO_API_KEY="你的密钥"
export ZHIHU_ACCESS_SECRET="你的密钥"

# 可选
export BRAVE_API_KEY="你的密钥"
export FELO_API_KEY="你的密钥"
export GITHUB_TOKEN="你的密钥"
export WEB_SEARCH_API_KEY="你的密钥"
export ANYSEARCH_API_KEY="你的密钥"
export OCTEN_API_KEY="你的密钥"

config.yaml 里只写 {ENV_NAME} 占位，不会提交明文密钥。

缓存

默认 SQLite 路径见 config.yaml 的 cache.db_path（一般为 ~/.cache/unified-search/cache.db）。

常见问题

不配 API Key 能用吗？
能。内置大量本地零成本引擎和免费 API 源，不配 Key 时自动走免费路径。

安装脚本和 npx 有什么区别？
安装脚本适合固定装在本机、改配置、挂 Skill；npx 适合快速把 MCP 挂进 Agent。两者底层同一套 Python 代码。

如何确认引擎是否正常？
python3 scripts/search.py --list-engines，或加 --explain。

会不会在仓库里复制多份代码？
不会。推荐「一份真源 + 符号链接」。用 link_source.py，不要 rsync 多副本。

---

CLI 常用参数

python3 scripts/search.py [选项] 查询词

  --engine, -e       引擎，默认 auto
  --max-results, -n  条数，默认 5
  --depth, -d        fast | balanced | deep
  --mode             fast | auto | deep | budget
  --no-cache         跳过缓存
  --explain          打印路由说明
  --json             JSON 输出
  --timeout, -t      超时秒数
  --list-engines     列出引擎

---

设计取舍

1. 先服务 Agent 吸收，再谈链接数量。
2. 免费与本地优先，付费可选增强。
3. 失败要可观测：空结果、超时、熔断分开标，不静默吞掉。
4. 配置驱动扩引擎，config.yaml 为单一真源。
5. 单一真源安装：链接入口、不 rsync 多副本。
6. 不把社交当真理库；社交内容适合扩维与舆情，不适合单独当真值。

---

适用场景

• Claude Code / Grok Build / Codex / Kimi 等 Agent 的搜索后端
• 多语言、多领域日常问答：中英日韩等 + 金融 / 影视 / 体育 / 学术 / 代码
• 脚本与流水线里需要 可复现、可缓存 的检索
• 事实核查、金融公开信息、实体与公开资料的 多源对照

不太适合单独承担：平台内高级互动定榜、需要长期养服务的最大召回聚合器（已用内嵌本地引擎替代外挂 SearXNG 主路径）。

---

目录结构（简）

argo/
├── README.md                # 中文介绍（默认）
├── README.en.md             # English
├── README.ja.md             # 日本語
├── README.ko.md             # 한국어
├── README.es.md             # Español
├── SKILL.md
├── package.json             # npx 入口
├── bin/argo.js              # Node 启动 MCP
├── bin/argo                 # Python CLI
├── config.yaml              # 引擎与域配置（真源）
├── assets/readme/           # README 视觉资源
├── backends/
├── scripts/                 # search / research / mcp / install …
├── sub-skills/local-search/
├── sub-skills/ego-search/      # 登录态专业搜索（默认关闭，开启命令见正文）
├── tests/
└── docs/

---

版本记录

更细说明见 docs/RELEASE_NOTES_v2.7.0.md 与 docs/OPTIMIZATION_ROADMAP_v2.4.md。

---

贡献

欢迎提 Issue 与 Pull Request。改路由或证据逻辑时，请尽量补对应测试：

python3 -m pytest tests/test_unit.py tests/test_multilingual.py -q
python3 scripts/regression_p0p1.py --offline
python3 scripts/matrix_search_eval.py --offline
python3 scripts/ab_eval_p0p1.py   # 可选，含在线实测

提交前请确认：不含真实 API Key、本机绝对路径、账号 cookie 等敏感信息。本机 Skill 路径请写在 installs.local.yaml（已忽略）。

License

MIT License © 2026 taxueseek

---

好的搜索不是让你看得更多，是让你更敢下结论——以及知道什么时候还不该下结论。