argo-search 1.0.1 → 2.9.7

package/docs/engines/openreview.md

@@ -0,0 +1,27 @@
+# 引擎：`openreview`
+
+- 准入时间: 2026-09-12T16:37:55+08:00
+- 状态: admitted
+- cost_tier: free
+- type: http
+- quality_score: 0.96
+- avg_latency_ms: 775.3
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=501.2ms · count=10
+- quality: pass · score=0.96 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine openreview
+python3 scripts/engine_validate.py --engine openreview --stage health
+```

package/docs/engines/openstd.md

@@ -0,0 +1,27 @@
+# 引擎：`openstd`
+
+- 准入时间: 2026-09-12T21:19:30+08:00
+- 状态: admitted
+- cost_tier: free
+- type: openstd
+- quality_score: 1.0
+- avg_latency_ms: 1855.9
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=2005.1ms · count=10
+- quality: pass · score=1.0 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine openstd
+python3 scripts/engine_validate.py --engine openstd --stage health
+```

package/docs/engines/parallel_free.md

@@ -0,0 +1,27 @@
+# 引擎：`parallel_free`
+
+- 准入时间: 2026-09-14T14:42:32+08:00
+- 状态: admitted
+- cost_tier: free
+- type: parallel_free
+- quality_score: 0.996
+- avg_latency_ms: 1583.6
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=1400.1ms · count=10
+- quality: pass · score=0.996 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine parallel_free
+python3 scripts/engine_validate.py --engine parallel_free --stage health
+```

package/docs/engines/people_daily.md

@@ -0,0 +1,27 @@
+# 引擎：`people_daily`
+
+- 准入时间: 2026-09-12T21:19:39+08:00
+- 状态: admitted
+- cost_tier: free
+- type: people_daily
+- quality_score: 1.0
+- avg_latency_ms: 446.8
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=542.8ms · count=10
+- quality: pass · score=1.0 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine people_daily
+python3 scripts/engine_validate.py --engine people_daily --stage health
+```

package/docs/engines/realtime_index.md

@@ -0,0 +1,27 @@
+# 引擎：`realtime_index`
+
+- 准入时间: 2026-08-08T14:55:14+08:00
+- 状态: admitted
+- cost_tier: free
+- type: cli
+- quality_score: None
+- avg_latency_ms: 812.8
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=812.8ms · count=10
+- quality: None · score=None · empty_rate=None
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine realtime_index
+python3 scripts/engine_validate.py --engine realtime_index --stage health
+```

package/docs/engines/sec_edgar.md

@@ -0,0 +1,27 @@
+# 引擎：`sec_edgar`
+
+- 准入时间: 2026-08-05T21:55:38+08:00
+- 状态: admitted
+- cost_tier: free
+- type: http
+- quality_score: 0.8
+- avg_latency_ms: 956.6
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=860.8ms · count=3
+- quality: pass · score=0.8 · empty_rate=0.2
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine sec_edgar
+python3 scripts/engine_validate.py --engine sec_edgar --stage health
+```

package/docs/engines/seltz.md

@@ -0,0 +1,27 @@
+# 引擎：`seltz`
+
+- 准入时间: 2026-09-14T16:32:34+08:00
+- 状态: admitted
+- cost_tier: api
+- type: seltz
+- quality_score: 1.0
+- avg_latency_ms: 1919.2
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| `SELTZ_API_KEY` | 是 |
+
+## 最近验证
+
+- health: pass · latency=1560.2ms · count=2
+- quality: pass · score=1.0 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine seltz
+python3 scripts/engine_validate.py --engine seltz --stage health
+```

package/docs/engines/skillsmp.md

@@ -0,0 +1,27 @@
+# 引擎：`skillsmp`
+
+- 准入时间: 2026-09-15T17:02:58+08:00
+- 状态: admitted
+- cost_tier: free
+- type: http
+- quality_score: 1.0
+- avg_latency_ms: 2010.8
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=4385.5ms · count=10
+- quality: pass · score=1.0 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine skillsmp
+python3 scripts/engine_validate.py --engine skillsmp --stage health
+```

package/docs/engines/sspai.md

@@ -0,0 +1,27 @@
+# 引擎：`sspai`
+
+- 准入时间: 2026-09-12T21:18:48+08:00
+- 状态: admitted
+- cost_tier: free
+- type: http
+- quality_score: 1.0
+- avg_latency_ms: 944.1
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=1064.1ms · count=10
+- quality: pass · score=1.0 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine sspai
+python3 scripts/engine_validate.py --engine sspai --stage health
+```

package/docs/engines/std_samr.md

@@ -0,0 +1,27 @@
+# 引擎：`std_samr`
+
+- 准入时间: 2026-09-12T21:19:24+08:00
+- 状态: admitted
+- cost_tier: free
+- type: std_samr
+- quality_score: 1.0
+- avg_latency_ms: 382.0
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=518.0ms · count=10
+- quality: pass · score=1.0 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine std_samr
+python3 scripts/engine_validate.py --engine std_samr --stage health
+```

package/docs/engines/train.md

@@ -0,0 +1,27 @@
+# 引擎：`train`
+
+- 准入时间: 2026-10-06T08:42:42+08:00
+- 状态: admitted
+- cost_tier: free
+- type: cli
+- quality_score: 1.0
+- avg_latency_ms: 414.1
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=414.1ms · count=10
+- quality: None · score=None · empty_rate=None
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine train
+python3 scripts/engine_validate.py --engine train --stage health
+```

package/docs/engines/un_comtrade.md

@@ -0,0 +1,27 @@
+# 引擎：`un_comtrade`
+
+- 准入时间: 2026-09-12T16:38:15+08:00
+- 状态: admitted
+- cost_tier: free
+- type: un_comtrade
+- quality_score: 1.0
+- avg_latency_ms: 2776.1
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=2547.1ms · count=10
+- quality: pass · score=1.0 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine un_comtrade
+python3 scripts/engine_validate.py --engine un_comtrade --stage health
+```

package/docs/engines/wikisource.md

@@ -0,0 +1,27 @@
+# 引擎：`wikisource`
+
+- 准入时间: 2026-09-12T21:19:43+08:00
+- 状态: admitted
+- cost_tier: free
+- type: wikisource
+- quality_score: 1.0
+- avg_latency_ms: 613.4
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=736.4ms · count=10
+- quality: pass · score=1.0 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine wikisource
+python3 scripts/engine_validate.py --engine wikisource --stage health
+```

package/docs/engines/zdic.md

@@ -0,0 +1,27 @@
+# 引擎：`zdic`
+
+- 准入时间: 2026-09-12T21:19:37+08:00
+- 状态: admitted
+- cost_tier: free
+- type: zdic
+- quality_score: 1.0
+- avg_latency_ms: 127.6
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=125.4ms · count=1
+- quality: pass · score=1.0 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine zdic
+python3 scripts/engine_validate.py --engine zdic --stage health
+```

package/docs/engines/zenodo.md

@@ -0,0 +1,27 @@
+# 引擎：`zenodo`
+
+- 准入时间: 2026-08-05T21:55:49+08:00
+- 状态: admitted
+- cost_tier: free
+- type: http
+- quality_score: 1.0
+- avg_latency_ms: 1873.1
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=1554.0ms · count=3
+- quality: pass · score=1.0 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine zenodo
+python3 scripts/engine_validate.py --engine zenodo --stage health
+```

package/docs/engines/zhihu_hot_app.md

@@ -0,0 +1,27 @@
+# 引擎：`zhihu_hot_app`
+
+- 准入时间: 2026-09-12T21:18:44+08:00
+- 状态: admitted
+- cost_tier: free
+- type: http
+- quality_score: 1.0
+- avg_latency_ms: 990.2
+- blocked: False
+
+## 环境变量
+
+| 变量 | 必填 |
+|------|------|
+| （无） | 否 |
+
+## 最近验证
+
+- health: pass · latency=262.6ms · count=10
+- quality: pass · score=1.0 · empty_rate=0.0
+
+## 调用
+
+```bash
+python3 scripts/search.py "查询词" --engine zhihu_hot_app
+python3 scripts/engine_validate.py --engine zhihu_hot_app --stage health
+```

package/docs//344/270/272/344/273/200/344/271/210/351/200/211/346/213/251argo.md

@@ -0,0 +1,176 @@
+# 为什么选择 Argo？——写给被搜索坑过的人
+
+> 一句话：Argo 是给 AI Agent 和终端用的「统一搜索层」。你问一个问题，它自动挑对的数据源、并行去查、交叉验证，把带出处的答案给你——**220 个数据源、89 个领域，其中 185 个免配置开箱可用**。
+
+---
+
+## 先看七个真实场景
+
+同样一个问题，传统网页搜索和 Argo 的差别（以下全部是 Argo 实测真实输出，非宣传语）：
+
+| 你问 | 传统网页搜索给你 | Argo 给你 |
+|---|---|---|
+| 「python asyncio error handling」（英文·调试） | SEO 博客农场混着论坛搬运，答案还要注册登录才能看 | **StackOverflow 官方 API**：按社区得分排序、标采纳状态的问题直连 |
+| 「log4j 漏洞 CVSS 评分」（中英·运维安全） | 各种博客的转述文章，版本对不对要自己核 | **NVD 官方漏洞库**的结构化条目：评分、影响版本、修复建议 |
+| 「attention is all you need 相关论文」（英文·科研） | 学术站广告墙、引用数要挨个点进去数 | **arXiv + CrossRef 官方元数据**：标题、作者、DOI 直连一条龙 |
+| 「Inception movie director」（英文·追剧） | 站内推荐流、广告、盗版站混排 | **IMDb 权威条目**：主条目与同名剧集自动区分 |
+| 「宮崎駿 アニメ 映画」（日文·二次元） | 机器翻译的二手文章混在结果里 | **纯日文一手来源**：日本动画媒体与百科，五源并行不掺翻译腔 |
+| 「김치찌개 레시피」（韩文·下厨） | 韩语内容在通用搜索里权重低、难命中 | **纯韩文原生结果**：Naver 博客与韩国媒体菜谱 |
+| 「qué ver en Sevilla」（西文·旅行规划） | 西语攻略被英文机翻页淹没、中介广告混排 | **纯西文本土指南**：西班牙旅游媒体的深度攻略 |
+| 「深蹲膝盖疼怎么恢复」（中文·日常健康） | 医疗广告与营销号 | **中文健康社区的真实讨论帖**，泛查询不误入行情/漏洞等垂直源 |
+| 「nodejs 22 什么时候停止维护」（英文·运维） | 论坛讨论、过时博客说法不一 | **endoflife.date 生命周期表**：每个版本的维护截止日 |
+
+九个场景横跨开发、运维、科研、娱乐、下厨、健身、日常，覆盖**中、英、日、韩、西五种语言**——共同点是：**每类问题都有「对口的一手来源」，但传统网页搜索够不着它们，或给了你也埋在噪声里**。Argo 做的事，就是把 220 个这样的源头接起来，按问题自动挑对的去查（阿拉伯语、泰语及德法西葡意等拉丁语系同样支持识别与回退）。
+
+## 数据源版图：220 个源、89 个领域
+
+| 领域 | 代表源 | 能答什么 |
+|---|---|---|
+| **通用检索** | anysearch、bocha、byted、duckduckgo、octen、exa 等 7 族 | 日常什么都查，中英日韩西泰多语言 |
+| **金融行情** | 新浪/腾讯行情、Finviz、东财资金流、SEC EDGAR、FRED、世界银行、汇率、财联社/金十快讯 | 股价、资金流、财报、宏观指标、快讯 |
+| **技术开发** | GitHub、MDN、StackOverflow + 180 个问答站、PyPI/npm/crates、deps.dev、endoflife、NVD + crt.sh | 代码、文档、依赖健康、生命周期、漏洞情报 |
+| **学术科研** | arXiv、OpenAlex、Semantic Scholar、PubMed、临床试验库、专利、数据集 | 论文、引用、试验、专利尽调 |
+| **法律政务** | 国家法律法规库、裁判文书、日本 e-Gov、韩国法令、美国判例库 | 法律法规原文、判例、规章 |
+| **知识百科** | 维基百科（中英）、百度百科、维基数据、萌娘百科、词典 | 实体、词条、词源、梗 |
+| **生活文娱** | IMDb、豆瓣、Bangumi、网易云音乐、iTunes、Steam、微信读书、汉典、Met 博物馆、NASA 图 | 影视书乐游艺收藏 |
+| **科学数据** | 化学物质、蛋白质结构、物种、地震遥感、空间天气、电网碳强度、土壤农业、标准检索 | 结构化科学数据，网页搜不到的那种 |
+| **本地与隐私** | 本机文件/代码/笔记搜索（rg/grep 级），微信读书个人数据 | 你自己的数据，不出本机 |
+
+**185 个免配置**：不用注册、不用填 key，装完就能用。其余要么是免费注册一把 key（20 个），要么装个后端工具（3 个），清单和状态一条命令看全：`argo search --list-engines`。
+
+## 重点源推荐：三档怎么选
+
+### 第一档：免 key 就很好用的精选源（185 个里挑最常用的）
+
+| 用途 | 源 | 免费额度与限速 |
+|---|---|---|
+| 通用多语言主力 | **anysearch**（中英日韩西泰全吃，结果质量稳定） | 2000 次/天 |
+| 编程问答 | **stackoverflow + stackexchange**（180+ 问答站官方 API） | 300 次/天/IP |
+| 代码与包 | **github**（1000 次/天）、MDN、npm、PyPI、Hugging Face、deps.dev | 开放接口，QPS 限速 |
+| 学术科研 | **arXiv、OpenAlex**（2.5 亿+ 论文索引）、Semantic Scholar、OpenReview、bioRxiv | 开放接口，QPS 限速 |
+| 安全情报 | **NVD**（CVE 编号/CVSS 评分官方源）、crt.sh 证书透明度 | 开放接口（NVD 限速 5 请求/30 秒） |
+| 百科事实 | 中英文维基百科、维基数据、百度百科 | 开放接口，QPS 限速 |
+| 新闻舆情 | **Google News RSS**（多语言+时间窗）、人民网、GDELT 全球事件库 | 开放接口，QPS 限速 |
+| 软件生命周期 | **endoflife.date**（200+ 产品 EOL 时间表） | 开放接口，QPS 限速 |
+| 法律文本 | 国家法律法规数据库（权威法条全文） | 开放接口，QPS 限速 |
+| 生活娱乐 | 豆瓣电影、网易云音乐、Met 博物馆、NASA 图像库 | 开放接口，QPS 限速 |
+| 天气 | wttr.in + Open-Meteo 双源 | 开放接口，QPS 限速 |
+| 网页兜底 | **firecrawl**（JS 渲染 + 全文 markdown） | 1000 credits/月 |
+
+### 第二档：免费注册一把 key，质量再上一个台阶
+
+| 源 | 强项 | 免费额度 |
+|---|---|---|
+| **TinyFish**（网页/新闻/论文三引擎） | 浏览器渲染、结果带原文摘要、新闻含发布时间 | 免费，QPS 限速 |
+| **bocha** 博查 | 中文搜索质量标杆，按时效动态调参 | 按次计费 |
+| **byted** 字节搜索 | 中文通用与新闻 | 按次计费 |
+| **zhihu 知乎三源** | 站内观点/评测、全网搜、个人创作数据 | 5000 次/天 |
+| **exa** | 语义搜索（embedding 匹配，适合模糊描述找内容） | $10 月度赠金（约 1400 次） |
+| **tavily** | AI 搜索管线，LLM 友好摘要 | 1000 credits/月 |
+| **octen** | 英文技术高速搜索（技术域主搜之一） | 按量计费（新户赠 $5） |
+| **weread** 微信读书 | 支持这个数据源 | 开放接口，QPS 限速 |
+
+配置方式统一：去各家官网免费注册，把 key 写进 `~/.config/argo/env` 一行（`export ARGO_XXX_API_KEY=...`），热生效不用重启。
+
+### 第三档：免费给得最大方的 API（大额度清单）
+
+| 源 | 免费额度 | Argo 里的用法 |
+|---|---|---|
+| zhihu / zhihu_global | **各 5000 次/天** | 中文观点与全网搜索的量级担当 |
+| anysearch | **2000 次/天** | 通用主力，多语言兜底 |
+| github | **1000 次/天** | 代码与模型库搜索 |
+| firecrawl | **1000 credits/月** | keyless 直接用，JS 页兜底 |
+| exa / tavily | $10 月度赠金（约 1400 次）/ 1000 credits | 语义与 AI 搜索增强 |
+| stackexchange | 300 次/天/IP（key 后 **10000/天**） | 问答补位 |
+| 维基百科/arXiv/NVD/endoflife/法律法规库/Google News/GDELT/deps.dev 等 | 无月度配额，但一律 QPS 限速 | 官方开放接口，保持克制使用 |
+
+**大额度源的保护策略**（值得说明的设计）：免费额度大不等于随便烧。Argo 给每个源配了记账与分层——大额度通用源做主力，稀缺额度源（如 firecrawl、stackexchange）标记为「日常只补位」，预算截断时优先省着，故障兜底的关键时刻才顶上；每次调用都记账，配额耗尽自动熔断换源，恢复后自动回归。
+
+## 给 Agent 的使用纪律（必读，避免误解）
+
+1. **没有「真的不限」的源。** 表里写「开放接口」的只是没有月度配额，但全部有 QPS/并发限制——这是对公共服务的基本礼貌。Argo 内置节流（多数源 1–2 请求/秒）与结果缓存，**默认参数即可，不要绕过**。
+2. **重复问题别重查。** 相同查询会命中缓存（输出里 `cached: true`），除非明确要新数据，不要用 `--no-cache` 强刷。
+3. **额度单位不要换算错。** 有的是「次/天」，有的是「credits/月」，有的是「赠金（$10 ≈ 1400 次搜索）」——计量口径各不相同，按各自单位估算。
+4. **配额耗尽 ≠ 数据源坏了。** 额度用完或触发限速时，Argo 会熔断该源并自动换源补位，结果里的 `engine_outcomes` 会标注原因（429/403/quota）——看到这些标记应该退避等待，而不是加大并发重试。
+5. **高频调用前先看状态。** `argo search --list-engines --detail --engine <名>` 查看该源当前可达性与配额，再决定调用节奏。
+6. **免费额度是公共资源。** 按 key/IP/全站分摊，一次轰炸会把所有用户的配额打光并招致封禁——保持克制是这套系统能长期免费的前提。
+
+## 它是怎么工作的（大白话五步）
+
+1. **听懂问题**：识别语言（中英日韩西泰…）和领域（89 个领域的模式识别——「报错」「CVE」「菜谱」各有各的信号词）
+2. **挑对来源**：按领域自动配 2–6 个对口源——问 bug 走问答社区、问论文走学术库、问影视走条目库，泛查询才走通用搜索
+3. **并行去查**：多个源同时出发，快的先回，慢的有预算约束不拖后腿
+4. **交叉验证**：多源结果按权威度、相关度、新鲜度五维重排合并；同一个 URL 被多个源命中会标记「共识」
+5. **不够就补**：首选源空手而归时自动换备用源补搜，被墙/超时/欠费都会明说，不装「没结果」
+
+## 为什么比三种替代品好
+
+### 对比「单一传统搜索」（Google / 百度网页版）
+
+1. **垂直数据根本不在网页里。** 漏洞评分、论文元数据、软件生命周期表、蛋白质结构这些是结构化数据库，网页搜索只能给你二手转述文章——而 Argo 直连官方接口拿一手数据。
+2. **一个源 = 一个视角。** 一篇测评说好、一个社区说差，单一搜索你只看到一个。Argo 多源并行，结论有分歧时两个都给你，并标记哪些源达成了共识。
+3. **SEO 噪声与内容农场。** Argo 按权威度、相关度、新鲜度五维重排，垃圾内容的排名天然靠后；恢复链里的结果还要过「与查询实质相关」的信号检查。
+4. **挂了就没辙。** 单一搜索被墙、限流、改版，你就断粮了。Argo 220 个源 + 熔断降级 + 自动换源补搜：一个源坏了，别的顶上，而且会告诉你是谁坏了、为什么。
+
+### 对比「单一 AI 搜索」（Perplexity 这类订阅产品）
+
+1. **成本结构。** AI 搜索按月订阅，源是黑盒配额；Argo **185 个源免配置**，大免费额度源（每月 1000 次的 Firecrawl、每天 300 次的 StackExchange）都做了「日常只补位、关键时顶上」的保护策略，免费额度花在刀刃上。
+2. **黑盒 vs 可审计。** AI 搜索不告诉你它用了什么源、为什么；Argo 每次输出都带 `route_reason`（为什么路由到这）和 `engines_used`（谁参与了这个答案）——答案可追溯，错了能归因。
+3. **不能点名换源。** AI 搜索的源列表你改不了；Argo 任何源都可以 `--engine` 点名调用，加一个新源 = 放一个 YAML 文件，机器可校验。
+4. **搜不了你自己的数据。** Argo 能搜本机文件、代码、笔记（本地数据融合），并且与联网搜索同一套出口——订阅产品做不到，也不该做到。
+
+### 对比「Agent 自带的搜索」（Claude / Codex 内置 web search）
+
+1. **源太薄。** 内置搜索通常一两个通用源，问漏洞、论文引用、生命周期、蛋白结构这类垂直问题，它只能拿网页转述凑合。Argo 的 89 个领域各有对口官方源。
+2. **上下文刺客。** Agent 的上下文窗口很贵：内置搜索一次抓回来的网页动辄上万 token。Argo 有 Agent 消费档（单次约 3.7KB，砍掉一切遥测只留答案），还有 `.md`/llms.txt 直出探测——同一篇文档，拿到的体积是网页版的几分之一。
+3. **没有证据链。** 内置搜索给你的结论很难复核出处；Argo 每条结果带编号信源、可回指原文，配合证据核验命令能把「这答案哪来的」一路追到底。
+4. **不抗故障。** Agent 内置搜索的上游一限流，Agent 就开始编造。Argo 有失败分型（超时/被墙/欠费各自明确上报）、熔断降级、恢复链换源——坏消息诚实说，通路自动换。
+5. **触发纪律可验证。** Argo 对「什么问题该进哪个域」有金标回归和负向控制测试（做菜的问题不许路由进行情源），这是工程化验证，不是「感觉挺准」。
+
+### 也说边界（不吹的部分）
+
+- 强人机验证页（Cloudflare 盾）没有银弹，Argo 会诚实升级到浏览器层，打不过就说打不过
+- reddit 这类对非浏览器强封的平台，需要浏览器态通道
+- 免费额度源有速率上限（所以做了补位策略），重依赖某一源的高频场景建议注册免费 key 提额
+- 上游故障（如 FRED 偶发超时）如实上报，恢复链换源兜底，但不假装那是首选源的结果
+
+## 专为 Agent 优化的搜索 Skill
+
+Argo 不只是个 CLI 工具，它本身就是一份**写给 Agent 用的搜索技能包**（SKILL.md）——Agent 读一份 7KB 的说明就能掌握全部场景，不用试错。
+
+**三种接入形态，按场景选：**
+
+- **技能包**：SKILL.md 放进 Agent 的技能目录，靠触发词驱动——用户说「查一下」「核实」「深度研究」时自动接管搜索行为
+- **CLI 单发**：`npx -y github:taxueseek/argo` 即用即走，适合脚本与一次性任务
+- **MCP 常驻**：给 Claude / Codex / Kimi 等 MCP 客户端挂上，11 个工具常驻可用
+
+**输出契约是为 Agent 的上下文窗口设计的：**
+
+- `--json --no-envelope --fields agent` 单次约 3.7KB（同场景网页抓取是它的几倍），遥测字段全部剥离，只留答案
+- 输出 schema 被**门禁锁死**（字段集合与字节预算都有测试钉住），不会因为升级突然多出几千 token
+- `fetch_required` 纪律字段明确告诉 Agent：哪些结果值得抓正文、哪些摘要已够用
+- 每条结果带编号信源（ref），Agent 可以直接向用户回指出处
+
+**11 个子命令覆盖 Agent 的完整检索场景：** search（搜索）、research（深度研究，多源采集综合）、fetch（正文抓取，四级降级）、crawl（站点爬取）、extract（结构化提取）、article（公众号文章）、job（招聘聚合）、evidence（证据核验）、clarify（意图消歧）、preflight（批量预检）、mcp（服务模式）。
+
+**Agent 最怕的问题，这里都有机制兜着：** 静默失败显式化（每个引擎的失败带归因，不再「没结果」装糊涂）、恢复链自动换源、缓存防重复消耗、熔断降级、以及排序金标 + 融合增益消融门禁保证版本升级不回退。
+
+## 快速上手
+
+```bash
+# 装（三选一）
+curl -fsSL https://raw.githubusercontent.com/taxueseek/argo/main/scripts/install.sh | bash
+npx -y github:taxueseek/argo          # 即用即走
+# 或给 Claude/Codex/Kimi 挂 MCP（见 docs/ARGO_INTRO.md）
+
+# 用
+argo search "python asyncio tutorial"      # 英文技术 → 低延迟源组合
+argo search "log4j 漏洞 CVSS"              # 安全 → NVD 官方条目
+argo search "宮崎駿 アニメ"                # 日文 → 影视域纯日文结果
+argo search "김치찌개 레시피"              # 韩语 → 原生韩文菜谱
+argo search "attention is all you need"    # 学术 → arXiv/CrossRef 元数据
+argo search "..." --engine tinyfish_news   # 点名用某个源
+argo fetch "https://某文档站/guide"        # 拿正文：.md/llms.txt/jina 自动降级
+```
+
+全部源清单与每个源的费用/配额/状态：`argo search --list-engines`，或看 [docs/ENGINE_CATALOG.md](ENGINE_CATALOG.md)。

package/engines/README.md

@@ -0,0 +1,10 @@
+# engines/ — 外置引擎声明与插件
+
+| 路径 | 用途 |
+|------|------|
+| `_template_http.yaml` | L1/L2 HTTP 引擎模板（复制到 `specs/`） |
+| `specs/*.yaml` | 声明式引擎（启动时自动 merge） |
+| `plugins/*.py` | L3 自定义 builder（`ENGINE_TYPE` + `build_engine`） |
+| `plugins/_template_plugin.py` | 插件模板（`_` 前缀不会加载） |
+
+完整流程见 `docs/ADDING_NEW_ENGINE.md`。