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

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

This is part of the DeepSeek Harness plugin series for Argo (踏雪寻仙), and the author has other excellent plugins: dsh-files (file upload and document reading) · dsh-snippets (snippet favorites) · dsh-healthcheck (read-only health check) · dsh-plugin-guard (plugin security audit) · taxue-dsh-artisan (prompt reverse-engineering and multi-provider image generation) — see the full plugin collection on the personal homepage

How Argo Beats "Built-in Model Search / AI Search / Aggregated Search"

In short: the first three solve "human information-finding"; Argo delivers a search-verification suite as a one-stop service. The gap isn't in the UI — it's in the deliverable: what humans get is a summary page or link list, while what Agents need is content that's rankable, re-checkable, context-friendly, and more reliable.

Dimension	Built-in Model Search	AI Search (Summary-style)	Aggregated Search / Search Engines	Argo
Result format	Assembled long text	Summary page for humans	SERP link list	Compact JSON: evidence candidates + credibility breakdown
Vertical questions (market data / chemical formulas)	Generic web search	Generic search then summarize	Generic web search	Direct vertical sources, answers first
Evidence credibility	No scoring	No structured scoring	No scoring	selection · absorption · freshness · consensus
Repeated queries	Hits the network every time	Hits the network every time	Relies on page cache	Two-tier cache (in-memory + SQLite), hot queries ~10ms
Cost control	Uncontrollable	Expensive per call	Free but a hassle	Budget mode, free-first, all keys optional
Multilingual	Follows the model	Follows the model	Follows the engine	Language detection + engine language parameter + multilingual support

Mechanically, Argo treats search as an evidence pipeline: language detection → domain routing → multi-engine recall → RRF fusion → evidence quick-scoring. The deliverable is material Agents can rank, fetch to re-verify, and that won't overflow context. No toolchain swap needed — just rethink "what search results should look like." One level deeper lies "the difference vs wrapping another search API," a comparison at the implementation level.

---

2026: What's Changing in Retrieval

The scale of what Agents do has changed, and retrieval has followed. Four shifts, each already coded into Argo:

1. Retrieval has moved from "giving links" to "giving evidence." Agents don't care about web page layout—they need structured material that can be ranked, re-verified, and won't blow up the context. That's why Argo delivers JSON with credibility breakdowns, not SERP lists.
2. Context is the first cost. A single web-page fetch can easily run into tens of thousands of tokens—Agents can't afford to burn that. Argo's Agent tier is ~3.7KB per call, with field sets and byte budgets guarded by checks, so upgrades don't quietly bloat.
3. Websites are starting to prepare for AI. The llms.txt standard and direct .md output are rapidly spreading on top-tier documentation sites—Argo's fetch pipeline probes these AI-friendly variants at level zero and skips the entire anti-bot chain on a hit; if both HTTP and TLS fail, there's still a reader-level fallback via r.jina.ai.
4. The free open ecosystem is enough. Open APIs from government, academic, standards, and security institutions plus key-free engines already cover most domains (194 zero-config sources); scarce free quotas (firecrawl 1,000 credits/month, stackexchange 300 calls/day) are tiered as "daily filler, critical backstop"—paywalls aren't the only answer.
5. Retrieval quality has moved from "feeling" to "measuring." Ranking has gold-standard baselines (MRR/nDCG floors), fusion has gain ablation checks, routing has a negative-control matrix—"is this version better than the last?" is now a numbers question, not a mystery.

v2.8.8 ships all of the above: 232 sources, 90 domains, 194 zero-config ready-to-use. Per-item details in docs/Why-choose-argo.md and the release notes.

---

What This Is

Argo is multilingual search infrastructure for AI Agents.

Real retrieval is never "one language + one search box": some ask about A-share quotes, some about the World Cup, some look for anime in Japanese, some want director info on IMDb. Argo's starting point is simple—route by domain, by language, by need, sending the question to the right source instead of blindly sweeping web page titles. Web search and local file search work as one integrated tool.

Output isn't a "link list" but "evidence candidates + credibility breakdown." Right routing keeps evidence firm.

The Difference from "Just Wrapping Another Search API"

Common approach	Argo
Locked to one engine, one Key	Multi-engine auto routing, free-first, budget configurable
Generic web search for everything	Vertical sources first: market data, film, sports, macro, chemistry, etc. give answer-type results
Optimized for English/Chinese only	Multilingual detection + engine language parameter + cross-language fallback
Paste a summary straight after search	Selection threshold × evidence density × freshness × multi-source consensus
One engine down takes the whole chain down	Circuit breakers, negative caching, staged recovery (prevents vertical-source bleed)
Hits the network on every query	Two-tier cache (memory + SQLite), hot queries ~10ms
Daily and research at the same pace	Daily: fewer engines; research: broaden
Agent context blown up by long JSON	MCP responses can be compact-trimmed, snippet controllable

---

Ask It Naturally

How you ask	What happens (roughly)
python asyncio error handling	Coding Q&A domain → StackOverflow/StackExchange official APIs, with score and acceptance marks
AAPL / US stock pre-market	US equities domain, routed separately from A-shares
The Shawshank Redemption cast / Inception director	Film & TV domain → IMDb etc.
Messi club / Curry team	Sports domain → TheSportsDB etc.
Where is the Eiffel Tower / where is Eiffel Tower	Geographic entity → OpenStreetMap etc.
NASA founding year / State Council functions	Organizational entity → Wikidata etc.
Jay Chou albums / Taylor Swift album	Media domain → iTunes etc.
アニメ おすすめ / 한국 영화 추천	Detects Japanese/Korean → language-appropriate sources, avoids Chinese-only sites
US CPI, Japan inflation rate	Macro data domain; country-level routing (domestic authoritative sources preferred)
log4j vulnerability CVSS / nodejs 22 end of life	Security domain → NVD official; lifecycle domain → endoflife.date
attention is all you need	Academic domain → arXiv/OpenAlex/CrossRef, direct metadata and DOI
aspirin molecular formula	Chemistry domain → PubChem-style answers
TSMC valuation divergence (deep research)	Decomposes into sub-questions + parallel multi-source retrieval, vertical sources boosted

---

How It Works

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

Evidence Scoring (Simplified)

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

Result fields include selection, absorption, credibility_fast, evidence_flags, etc., so Agents can rank results directly.

Agent Usage Discipline (Recommended)

1. High-stakes questions (holdings, security, fact-checking): search → check fast scores → fetch top results → then draw conclusions
2. Numbers: state how they were computed; when sources conflict, present them side by side — don't force-merge
3. Search results pages / redirect links: don't treat them as primary sources
4. Social posts: treat them as sentiment and narrative, not as ground truth
5. Fact-checking: prefer one or two extra layered queries (source / comparison / subject)

---

Quick Start

Pick any one method. Treat GitHub as the sole install source (npx github:taxueseek/argo or install.sh / install.ps1); the current recommendation is v2.8.8. Do NOT use npm install argo-search — the copy on the npm registry is an unofficial stale v1.0.1 (not maintained by this repo; incomplete features, not updated with this project). This package's package.json sets private: true to prevent accidental publication to the npm registry.

Runs out of the box with zero config: without API keys it uses free engines + local local_* engines; sources with configured keys usually give better quality, and unconfigured ones are skipped automatically.

Option 1: One-Click Script (Recommended for Local Use)

macOS / Linux:

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

Windows (PowerShell):

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/taxueseek/argo/main/scripts/install.ps1 | iex"
# 或下载后执行：
# powershell -ExecutionPolicy Bypass -File scripts/install.ps1

Install to the target dir, wire up the Skill entry:

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

Verify:

python3 ~/.local/share/argo/scripts/search.py "python asyncio error handling" --json
python3 ~/.local/share/argo/scripts/search.py --list-engines

Option 2: Use GitHub Directly for MCP Without Installing a Package (Recommended for Quick Agent Mounting)

Requires Node.js 18+ and Python 3.9+; run this once on first use:

pip3 install pyyaml

npx -y github:taxueseek/argo

Client configuration example (Claude Code / Cursor / Kimi, etc.):

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

DeepSeek Harness One-Click Plugin (.dsh-plugin bundle)

Install in one line inside DeepSeek Harness (two ways):

# 装法 A：14 个 mcp__argo__* 工具（主包自带 bundle，与 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"

Takes effect after restarting dsh web. Bundle structure is in packages/dsh-plugin/; the same id mcp-argo / wide-research can be overridden at the user layer via cordis.patch.yml. The wide_research module in install method B only exists in the sub-package dependency tree; the main-package patch does not reference it, avoiding Cordis resolution failures when only the main package is installed.

Dependency List (Plain Version)

Dependency	Required?	What it does	What if not installed
PyYAML	✅ Required	Reads config files	Completely non-functional; install script auto-installs it
curl_cffi	❌ Optional (added in v2.7.3)	Simulates browser TLS fingerprint to pass anti-bot sites (Cloudflare etc.)	Lower success rate on anti-bot scraping; daily search unaffected
ddgs CLI	❌ Optional	10 local key-free search backend engines	Loses a batch of zero-cost local search sources; others unaffected
realtime-index CLI	❌ Optional	Real-time index engine (searches just-published content)	That engine auto-disables; explicit selection falls back to generic engine
Chrome	❌ Optional	Page screenshots, JS-rendered pages, logged-in scraping	Screenshot tool unavailable; rest normal
pdfplumber / PyMuPDF	❌ Optional	PDF extraction	argo_pdf unavailable; rest normal
Playwright	❌ Optional	Screenshot enhancement	Screenshot tool falls back to Chrome CDP; rest normal

The install script (install.sh) auto-installs only the first two; other optional dependencies can be installed on demand via pip install or brew install. A more stable approach, completely independent of Node: install the script first (Option 1), then point to local Python:

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

When the Python path is unusual: export ARGO_PYTHON=/path/to/python3 (only read by the npx entry).

Option 3: git clone (Development / Source Changes)

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

---

Platforms

Platform	Integration	Notes
Claude Code	MCP / Skill link	npx or mcp_server.py; link_source.py also works
Kimi / Grok Build	MCP Server	Same as above
Cursor / Cline / Continue	MCP	Any IDE plugin supporting MCP works
Command line	search.py / bin/argo	Scripts, scheduled tasks, manual debugging
Python projects	from search import super_search	Library call

Post-Install Self-Check

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

---

Capabilities

Five Capabilities, Plainly Put

1. General + vertical search, two-pronged

Everyday questions go through general web search; when you ask about markets, film/TV, sports, macro and other "standard-answer" topics, it automatically switches to vertical sources for direct answers instead of dumping a pile of links. Currently 232 sources (194 key-free out of the box), 90 business domains, with dedicated paths for finance / macro / film / sports / geography / organizations / media / chemistry / academic / code and more.

2. Caching: no repeat waste

For content with low timeliness (encyclopedia, historical data), the first lookup enters the cache; subsequent identical queries hit the cache directly instead of calling the API every time. Two-tier caching (memory + SQLite); hot queries return in ~10ms — saving both money and time.

3. Built for Agents, lighter on Tokens

Output is compact "evidence candidates + credibility breakdown" JSON, not long web pages; MCP responses can be trimmed on demand, snippets are controllable, so the Agent's context won't overflow. More specialized and token-efficient than the built-in search in typical model providers.

4. Deep research

Split a broad question into sub-questions, gather multi-source in parallel, end with a gap hint on missing evidence. For review/research that must be thorough.

5. Logged-in professional search (Pro mode, off by default)

For content that requires login (Zhihu, Xiaohongshu, WeChat official accounts) and for JS-rendered / anti-bot pages, uses a real browser with login state to search. Off by default; enable when needed. Depends on ego lite and WebBridge — see "Logged-in Professional Search" in the next section.

6. Time capabilities (time window + directional sort)

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

能力入口速查

能力	说明	入口
统一搜索	路由 → 召回 → 融合 → 快评	search.py / argo_search
本地文件搜索	本机代码/笔记/记忆（非联网）	argo_local_search
本地文本预览	白名单目录内预览（fail-closed）	argo_local_read
可复算	受限子进程重算数字（默认拒绝）	argo_recompute
深度研究	拆子问题、多源采集、缺口提示	research.py / argo_research
可信度评估	权威 / 证据密度 / 时效 / 交叉验证	evidence.py / argo_evidence
证据核验（完整链路）	高后果问题标记 fetch_required + 每条 fetch_suggested；--verify 一键抓正文核验、回填「核实后证据分」、核实过的链接自动记住	search.py --verify 3 / research.py --verify 3
意图消歧	多义词、品牌碰撞、策略建议	clarify.py / argo_clarify
页面抓取	HTTP 优先，必要时浏览器降级	argo_fetch（mode=extract 可结构化）
截图 / PDF	页面截图、PDF 结构化提取	argo_screenshot / argo_pdf
站点爬取	列表页批量抓取	argo_crawl
社交与舆情	微博 / 小红书 / B 站 / Reddit / X 等	argo_social_search
实时索引搜索	免 Key 实时索引源，结果带发布时间，适合「最近几天有什么新东西」	--engine realtime_index
时间窗过滤	--since / --until（7d 或 2026-08-01）限定发布时间范围；支持引擎下推 + 融合后过滤（time_filtered），CLI 与 MCP 均支持	--since 7d
时间方向排序	--sort newest|oldest 按发布时间重排（最新动态 / 最早出处）	--sort oldest
登录态专业搜索	知乎 / 小红书等登录墙正文、JS 渲染页、登录站点接口直取	sub-skills/ego-search/scripts/ego_search.py（默认关闭，见下）

预算模式

模式	适合	行为
fast	简单问题、要速度	免费引擎优先，跳过付费精排
auto	默认日常	成本感知，质量与花费折中
deep	调研、综述	质量优先，可多用引擎
budget	额度紧	配额控制，用完降级

当前大致能力（v2.8.8）

• DSH 插件工具原生化（v2.8.5 新增）：argo_search / argo_fetch 原生一等工具默认可用（CLI 单发，不依赖 MCP 连接）；schema 由 gen_native_tools.py 从 mcp_tools.py 唯一来源生成（漂移检查测试把关）；nativeTools 配置可按需启用全部 13 个工具（argo_research 除外）

• MCP 默认关闭（v2.8.5 变更）：三形态接入——MCP 按需挂载（profile patch）/ 原生工具（默认入口）/ 原生 web_search seam；平时零常驻 token 开销

• Windows 全平台兼容（v2.8.5 增强，社区贡献）：临时路径走 tempfile.gettempdir()；解析映射显式 UTF-8（根治 GBK 静默失效）；解释器运行时解析（python3 → python → sys.executable）；symlink 无权限退化 junction；PowerShell 一键安装 install.ps1；--spotlight 无 mdfind 自动退化 rg

• 配额自愈完整链路（v2.8.5 新增）：HTTP 200 业务错误封套识别（火山/知乎风格）；远端配额耗尽自动标记 → 路由全模式排除 → 备用源接管 → 周期边界自愈回归；配额/鉴权错误不毒化自适应分数与熔断

• 抓取全局 deadline（v2.8.5 新增）：ARGO_FETCH_DEADLINE_S（默认 60s）封顶降级链总耗时；429/503 停止信号；tinyfish 渲染层（TINYFISH_API_KEY）+ {url}.md 变体探测；移动 UA 首发身份记忆

• 本地数据融合（v2.8.4 新增，深度研究 L1）：工作包可带 file_inputs（本地一手数据白名单入账，登记 sha256/来源记录）与 recompute（可复算执行器，受限子进程安全重算，重算值与检索数字冲突触发 recompute_conflict）；dossier 输出 local_sources，本地一手计入一手命中（防 no_sources 假阴性）

• 多客户端 MCP 一键接入（v2.8.4 新增）：argo mcp inject 一键给 Claude Code / Cursor / Windsurf / Codex / OpenCode / Cline 注入 argo MCP（原子写 + 备份 + 可逆，客户端来源 mcp/clients.yaml）

• 结构化搜索增强（v2.8.4 新增）：查询归一化（全角→半角、点号版本拆斜杠）+ 检索变体 + 复杂度门控（低复杂度查询不放行高价多轮）；social 域语法优先（from:/subreddit:/lang: 命中提前）+ TF-IDF 检索修复（丢弃中文引擎后继续看 top-2/3）；--include-local 本机命中并入（默认关）

• Keenable（v2.8.4 新增）：接入通用网页搜索引擎（L1 声明式 HTTP，免费体验期，ARGO_KEENABLE_API_KEY）

• 多语言路由修复（v2.8.3 新增）：ja/ko 查询返回目标语言（不再被中文引擎污染）；德法西意等多语言走 anysearch 返回对应语言；weighted RRF 弱源降权（weakest-link，论文 2508.01405）；anysearch 进程内 builder（更快更稳）

• Windows 全平台可用（v2.8.2 新增）：移除 npm os 限制；全链路 UTF-8 防线（PYTHONUTF8 + -X utf8 + 6 处 JSON read_bytes）根治 GBK 崩溃；工具探测改 shutil.which；Chrome/Edge 自动发现；Ctrl+C 干净退出

• DSH 插件两种装法（v2.8.2 新增）：主包自带 dsh.bundle，dsh plugin add github:taxueseek/argo 即得 14 个 MCP 工具；子包再加 wide_research 并行研究调度

• wide_research 证据检查（v2.8.2 新增）：输出自带 quality_gate_results（conclusion_cap low/medium/high），与 dossier 同一套语义；depends_on 依赖分阶段；仅 http(s) 入证据账本；worker 不可调 argo_research（防研究套研究）

• 取证协议化（v2.8.2）：深度研究只产 dossier（来源/覆盖/缺口/检查），判断稿归 Agent；--work-packages 按 depends_on 分阶段

• 证据完整链路（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 优雅降级

• 232 个搜索源（194 个免密钥开箱可用）、90 个业务域：通用网页 + 金融 / 宏观 / 影视 / 体育 / 地理 / 组织 / 媒体 / 化学 / 学术 / 代码等（来源：config.yaml 与 engines/specs/*.yaml）。逐源清单（费用 / 密钥 / 状态 / 域组合 / 特别能力）见 搜索源使用文档，该文档由脚本从声明生成、有检查防漂移；选源判断与语义分工见 references/engines.md

• 垂直结构化模态卡：火车票 / 油价 / 贵金属 / 万年历 / 星座 / 手机参数 / 汽车 / 医疗挂号等查询返回实时结构化卡片（modal_card 域 → bocha_ai 原生引擎，失败自动回落 web 搜索）

• 双层缓存：内存 LRU + SQLite 持久化，时效性弱的内容不重复打 API；登录态结果单独隔离，不污染公共缓存

• 为 Agent 节省 Token：MCP 响应可紧凑裁剪、snippet 可控，输出为精简 JSON 而非整页文本

• 14 个 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 实测命中）；快讯类引擎触发词放行全量榜单；百科条目页直接命中保底

---

引擎与路由

当前配置 232 个源（194 个免密钥开箱可用）、90 个业务域（以 config.yaml 与 --list-engines 为准）。

直连与垂类（节选）

引擎	场景	成本倾向
anysearch / duckduckgo	通用 / 技术	免费
sina_quote / tencent_quote / eastmoney	A 股行情 / 资金	免费
finviz / seeking_alpha	美股与海外金融	视配置
imdb / itunes / thesportsdb	影视 / 音乐 / 体育	免费为主
local_openstreetmap / wikidata / wikipedia	地理 / 组织 / 百科	免费
arxiv / semantic_scholar / openalex	学术	免费为主
pubchem / gbif / rfc_editor	化学 / 物种 / 标准	免费
github / stackoverflow / pypi / npm	代码与包	视配置
byted / bocha / octen	中文网页 / AI 搜索	API / 低成本
zhihu / wechat_sogou	中文观点 / 公众号	API / 免费
tavily / exa	国际 / 语义	付费或额度
stackexchange / doi / endoflife / nvd / flk_law	问答官方 API / 论文元数据 / 生命周期 / 漏洞 / 法规原文	免费
twitter / reddit / xiaohongshu / bilibili / weibo	社交 UGC	免费（部分需登录）

本地零成本层（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（分别对应浏览器搜索、抓正文、调站点接口）。

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

依赖	官方项目	是什么	什么时候用
ego lite	lite.ego.app	专门给 Agent 用的浏览器应用（仅 macOS），初始化后提供 ego-browser 命令	默认首选：独立空间，不抢你正在用的浏览器标签
WebBridge	Kimi WebBridge 官方帮助中心	浏览器扩展桥，复用 Chrome / Edge 里已登录的会话	ego lite 没装，或想直接沿用日常登录态时

登录态搜到的结果不写公共搜索缓存（避免污染共享缓存），需要融合时用 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 工具一览（12）

工具	用途
argo_search	统一搜索
argo_local_search	本地文件搜索（非联网）
argo_local_read	白名单本地文本预览（fail-closed）
argo_recompute	受限子进程可复算（默认拒绝，需授权）
argo_research	深度研究（含 social-sentiment 模式）
argo_evidence	可信度评估
argo_clarify	意图消歧
argo_fetch	智能抓取（mode=extract 结构化提取）
argo_crawl	站点爬取
argo_screenshot	页面截图
argo_pdf	PDF 提取
argo_social_search	多平台社交搜索（mode=sentiment 舆情聚合）

---

安装与配置

环境要求

项目	要求
Python	3.9+（命令行与 MCP 核心）
依赖	pip install pyyaml（仅此一个硬依赖）
可选增强	pip install curl_cffi（TLS 指纹伪造，MIT 许可）。装上后对指纹检测型反爬站（Cloudflare 等）免起浏览器即可抓取；缺失时自动降级，核心功能不受影响
Node.js	仅在使用 npx 入口时需要 18+
SearXNG	不需要（内置本地引擎替代）

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="你的密钥"
export ARGO_KEENABLE_API_KEY="你的密钥"   # 可选；Keenable 免费体验期

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

缓存

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

类型	大致 TTL
金融	约 5 分钟
新闻 / 实时	约 10–15 分钟
通用	约 1 小时
研究 / 常青	约 2–24 小时
空结果	很短（避免把失败固化）

常见问题

不配 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/
├── mcp/                     # 多客户端 MCP 注入配置（clients.yaml）
├── scripts/                 # search / research / mcp / install …
├── sub-skills/local-search/
├── sub-skills/ego-search/      # 登录态专业搜索（默认关闭，开启命令见正文）
├── tests/
└── docs/                    # 含 ENGINE_CATALOG.md（搜索源使用文档，生成）

---

最近更新

v2.8.8：真实用户问题修复 + 全面提速 + 搜索源 232 个

• 修复：按推荐名配密钥后引擎静默失效（#12）；抓取链不走代理，GitHub 等站点必然失败（#13）——现在 ARGO_PROXY、config 按域规则、标准代理环境变量都生效，NO_PROXY 尊重
• 提速：命令冷启动 2.1s → 0.55s；配置跨进程缓存 50–82ms → 16–18ms；每次搜索自带各阶段耗时与预算账单，慢在哪不用猜（--no-timing 可关）
• 新增：搜索源 218 → 232（免配置开箱 184 → 194，全部免密钥：国内热榜、安全漏洞、学术开放获取、技能目录、Agent 搜索）、argo answer 直答、argo watch 网页观察、CLI 与 MCP 工具面对齐
• 更稳：三平台惯例路径（新增 argo paths 自省）、支持 Python 3.9、静默故障如实记账；详见 发布说明

v2.8.7：数据源扩充到 218 个 + 一批修复

• 数据源扩充：168 → 218 个源、72 → 89 个领域（新增 StackExchange 问答、DOI 论文元数据、漏洞情报、产品生命周期等官方源），抓取链新增三条拿正文直出通道
• 一批修复：多引擎路由、零结果自动换源、中文重定向、本地搜索降级等；详见 发布说明

v2.8.6：检索提速 + 多源分工

• 引擎竞速、知乎三源分工、多语言与学术分发放宽、死源显形检查

v2.8.5：DSH 插件工具原生化 + MCP 默认关闭 + Windows 兼容

• DSH 插件工具原生化：argo_search / argo_fetch 以原生一等工具注册，默认可用，不依赖 MCP 连接；schema 从 mcp_tools.py 唯一来源自动生成，两侧零漂移；除 argo_research 外 13 个工具都可经 nativeTools 按需启用
• MCP 默认关闭：DSH 三形态接入（MCP 按需挂载 / 原生工具默认入口 / web_search seam），平时零常驻 token 开销，要完整 14 工具面时一条 profile patch 打开
• Windows 全平台兼容（社区贡献 PR #11）：临时路径走系统 temp、GBK 编码修复、python3/python 运行时解析、symlink 无权限自动退化 junction、新增 PowerShell 一键安装 install.ps1
• 配额自愈完整链路：远端配额耗尽（HTTP 200 藏错误）自动识别、路由排除该引擎切备用源，周期结束自动回归，无需人工改配置
• 抓取全局 deadline：ARGO_FETCH_DEADLINE_S（默认 60s）封顶降级链总耗时；429/503 停止信号尊重服务器指示；tinyfish 免费渲染层 + .md 变体探测命中即跳过反爬链

v2.8.4：本地数据融合 + 多客户端 MCP 一键接入

• 深度研究能吃你本地的数据了：以前 argo research 只吃网页，现在工作包能带 file_inputs（你的一手 CSV / XLSX / 文献，登记哈希、内容不入账）+ recompute（可复算执行器，安全地重算数字并和检索对账，对不上就提示）
• 挂 MCP 不再手改配置：argo mcp inject 一条命令把 argo 注入 Claude Code / Cursor / Windsurf / Codex / OpenCode / Cline（原子写 + 自动备份 + 可还原）
• 简单问题不被拖成多轮：查询归一化（全角→半角、版本号拆斜杠）+ 复杂度门控（低复杂度查询不放行高价多源）+ 社交/平台检索语法优先 + 丢了一个中文引擎会继续看备选
• 多接一个免费搜索源 Keenable（免费体验期、量较大，到期出问题直接停用即可）
• 安全加固：recompute 封死外部进程出网、主机路径全部改为安装感知（不再写死 ~/.agents 这类）、修了一处会把用户引向陈旧 npm 包的安装提示

完整变更见下表与各版发布说明。

---

版本记录

版本	说明
v2.8.8	真实用户报障修复（#12 密钥别名静默失效、#13 抓取链不走代理）+ 全面提速 + 搜索源 218 → 232：统一出口调度（ARGO_PROXY / 按域规则 / 标准代理变量，全程尊重 NO_PROXY）；16 处密钥读取统一走别名链；命令冷启动 2.1s→0.55s、配置跨进程缓存 50–82ms→16–18ms、QPP 平坦分早停、--list-engines --detail 瘦身 152KB→51KB；新增直答 argo answer 与网页观察 argo watch，14 个免密钥源（国内热榜与生活 / 安全漏洞 / 学术开放获取 / 技能目录 / Agent 搜索），69 引擎补归类（web_general 兜底 41%→20%，新增 security 领域）；三平台惯例路径（argo paths 自省）+ Python 3.9 + 有界并发让超时真正生效；search.py 拆模块 3351→2526 行、相关性回归金标 22 引擎、静态缺陷与输出契约门禁。详见 发布说明
v2.8.7	218 源 / 89 域 + 取信技巧三通道 + 路由触发纪律 + macro 零结果修复：批次七/八/九累计 50 个新源（法条/标准/安全情报/学术/新闻/文娱/能源交通/法律政务），stackexchange 与 doi 引擎；抓取链第零级 llms.txt 与 .md 直出探测、新增 r.jina.ai 阅读器级；--engine 逗号多引擎修复、tfidf 计算方式与 route_reason、负向路由控制矩阵、排序金标与融合增益消融检查；中国宏观查询国家统计局前置、全域零结果恢复链放行 L3、救援引擎如实记账。详见 发布说明
v2.8.6	hedged 竞速 + 知乎三源分工 + 声明式语言分发 + 可达性门 + 学术检索协议：首引擎宽限窗竞速（快引擎只付 1 次调用）、zhihu 全网搜/个人数据接入与防饿死、子查询语言/学术分发（英文源与 17 学术源接入研究采集）、引擎语言元数据与可达性检查（死源显形）、geo 尾链 −56%、学术检索查询构造协议。详见 发布说明
v2.8.5	DSH 插件工具原生化 + MCP 默认关闭 + Windows 兼容 + 配额自愈 + 抓取 deadline：argo_search/argo_fetch 原生一等工具默认可用（CLI 单发与 MCP 同引擎同守卫，schema 唯一来源生成 + 漂移检查）；DSH 三形态接入、MCP 按需挂载默认关；Windows 全平台兼容（临时路径 / GBK / 解释器解析 / junction / install.ps1，PR #11）；配额自愈完整链路（200 业务错误封套识别 + 路由排除 + 周期自愈）；抓取降级链全局 deadline（ARGO_FETCH_DEADLINE_S）+ tinyfish 渲染层 + .md 变体探测；密钥热读与状态目录唯一来源。详见 发布说明
v2.8.4	本地数据融合 + 多客户端 MCP 接入 + 结构化搜索增强 + Keenable：深度研究 L1 本地一手数据入账（file_inputs 白名单 + recompute 可复算执行器 + local_sources，no_primary_sources 计入本地一手）；argo mcp inject 多客户端 MCP 一键注入/诊断/还原（mcp/clients.yaml 声明式来源）；结构化搜索增强（查询归一化 + 检索变体 + 复杂度门控 + social 域优先 + TF-IDF 检索修复 + --include-local）；接入 Keenable 通用网页搜索（L1 声明式 HTTP，免费体验期）；安全加固（recompute 封死 subprocess/os.system 出网通道 + 主机路径单来源化）。详见 发布说明
v2.8.3	多语言路由修复 + anysearch 进程化 + weighted RRF：anysearch 从 subprocess 改为进程内 builder（省 python 启动开销 + HttpClient.post UA 轮换/重试/退避）；weighted RRF 新增动态可靠性因子（weakest-link 弱源降权，论文 2508.01405）；多语言路由修复——ja/ko 查询返回目标语言（韩语/日语），欧语言（德法西意）走 anysearch 返回目标语言，中文内容/金融/技术引擎双层过滤（域命中 + TF-IDF），Bing mkt 市场码 + 语言偏好软排序。详见 发布说明
v2.8.2	Windows 全平台 + 证据语义统一：移除 npm os 限制；全链路 UTF-8 防线（PYTHONUTF8 + -X utf8 + JSON read_bytes）根治 GBK 崩溃；工具探测改 shutil.which；Chrome/Edge 自动发现；Ctrl+C 干净退出。主包新增 dsh.bundle 声明（dsh plugin add github:taxueseek/argo 即得 MCP 工具）；npm 包补 engines/、data/。wide_research 输出新增 quality_gate_results 检查 + depends_on 分阶段 + SSRF 防线 + 研究递归硬保护；深度研究协议化（机器产 dossier、Agent 写判断稿，--work-packages 分阶段取证）。详见 发布说明
v2.8.0	证据完整链路 + 求职 v3 + 天气双源：搜索输出自带证据门控（高后果问题标 fetch_required、每条结果标 fetch_suggested、--verify 一键核验回填「核实后证据分」、核实过的链接自动记住下次搜索直接显示已核实）；argo job 求职搜索 v3（结构化字段 + 增量监控 + 指纹去重 + Ashby ATS / 北京高校源）；天气双源并行（wttr.in + Open-Meteo，地理编码 + 空气质量）；新增 Parallel / You.com 通用引擎；health_check 崩溃修复 + 日韩股票查询错配修复。详见 发布说明
v2.7.3	本轮修复 + 引擎激活：引擎层 HttpClient 接入（UA 轮换 / 重试 / 重定向跟随，arxiv 从 5s 超时空返回变为 2s 内 10 条有效结果）；TF-IDF 强语义注入激活 25 个垂直引擎（marginalia / open_meteo / usda / gov_policy / cnii 等，此前有 profile 但永远选不中）；env 占位缺失过滤（github 无 token 从 401 恢复匿名 API）；70 域 TTL 全覆盖（金价/快讯/行情缓存从 1 小时缩短到 5-15 分钟）；垂直源中英双语覆盖（worldbank / eurostat 英文国家与指标名，实测 China GDP / US inflation / Japan population 全部命中）；快讯类引擎触发词放行（「快讯」不再被当关键词滤空）；百科条目页直接命中保底（moegirl 等搜索跳转条目页不再空结果）；熔断 empty 语义修复（查询无结果不误判引擎故障）；国际引擎中文查询 URL 编码修复（18 处）；唯一来源文档修正（engines/specs/ 外置目录）。详见 发布说明
v2.7.2	登录态专业搜索：新增 ego-search 子技能（默认关闭，开启方法与依赖见上「登录态专业搜索」节）；搜索保底 / 多意图路由 / 统一健康视图；日韩文查询不再混入中文引擎、显式语言指定生效；MCP 服务拆三模块；具备安全防护（登录态结果与公共缓存隔离、URL 安全检查）。详见 发布说明
v2.7.1	安全加固 + 路由修复：SSRF 防护（URL 白名单 + IP 段检查）；路由健康状态语义漂移根因修复（只对 local_* 做健康判定）；深度研究 local_first 浪费修复；配置清理（唯一来源）。详见 发布说明
v2.7.0	垂直结构化模态卡：内建 bocha / bocha_ai 原生引擎，modal_card 域统一识别火车票 / 油价 / 贵金属 / 万年历 / 星座 / 手机 / 汽车 / 挂号等实时卡片；bocha web 解析缺陷修复。详见 发布说明
v2.6.2	合并独立改进线：网络环境感知 / 加权 RRF + 语义缓存 / 自适应引擎禁用 / 内容安全 + 查询变体 / 三大垂直引擎 / 日韩域路由补全；含 v2.6.1 路由修复。详见 发布说明
v2.6.1	v2.6.0 修复版：路由误伤修复（capital of 不再抢 fact_check）；版本同步。详见 发布说明
v2.6.0	多语言搜索（检测 / 引擎参数 / 跨语言回退）；影视·体育·地理·组织·媒体等垂直补全；recovery 防污染；能力族与矩阵回归；约 120+ 源。详见 发布说明
v2.5.1	金融/宏观/化学等垂直答案源加厚；引擎分层 + combo 预算；v2.5.1 说明
v2.5.0	安装脚本 + npx；查询改写与路由拆开；路由热路径缓存；MCP 紧凑响应
v2.4.0	路由低分回退与社交误吸过滤；缓存 depth / 柔性命中；熔断与负缓存；engine_outcomes
v2.2–v2.3	证据两阶段、中文信源表、content_signals、fetch 栈、引擎扩充
v2.1	社交引擎层（多平台 UGC）
v1.x	统一命名为 Argo，多引擎路由与双层缓存成型

更细说明见 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

---

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

---

生态联动：与 Invest 系列投资技能集成

本引擎的财经垂直源（eastmoney、nbs_stats、jin10、nbs、fred、eurostat、finviz 等）已接入 invest 系列投资技能。

invest-cli 通过 info（invest-cli info <词> --engine eastmoney）与 intent macro 直接复用 argo 的财经 / 宏观 / 资讯取数，用于环节配额、低成本、多源数据，与 invest-cli 的结构化数据层（Wind / 盈米 / 东财 / yfinance / 天天基金）协同。

最新版已完成 argo 数据与 invest 系列技能（v2.0.5）的集成。