argo-search 1.0.1 → 2.9.8

package/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: argo
+description: Argo 阿尔戈 — 统一搜索、网页抓取与证据核验。当需要搜索/查一下/核实/抓取网页/爬取/深度研究/论文检索/新闻/舆情/公众号文章/招聘聚合时使用；支持影视/体育/金融/宏观/学术等垂直域与多语言查询。
+version: 2.9.8
+triggers:
+  - 搜索
+  - 查一下
+  - 搜一下
+  - 核实
+  - 查证
+  - 可信度
+  - 抓取
+  - 爬取
+  - 深度研究
+  - 论文
+  - 舆情
+  - 公众号
+  - 招聘
+  - search for
+  - look up
+  - fact check
+  - fetch
+  - crawl
+  - research
+---
+
+# Argo — 统一搜索与证据核验
+
+> 不止搜到，还要核到：高后果问题标 `fetch_required`、结果标 `fetch_suggested`，`--verify` 核验正文并回填证据分。收录 272 个源、235 个免密钥可用；digup 默认关；deepseek_search 默认开、需 DEEPSEEK_API_KEY（按次计费，无 key 自动跳过）。
+
+## 快速上手
+
+```bash
+argo search "查询词"                     # 自动路由搜索（daemon 需显式启动）
+argo search "查询词" --json --fields agent  # Agent 消费档
+argo search "查询词" --verify 3           # 核验 top-3 并回填证据分
+python3 scripts/research.py "复杂问题" --json  # 取证包（扩词或多工作包 → dossier）
+```
+
+默认不附 candidates/sources；`--fields agent` 只留答案（~4.3 KB），要追溯或归档才加 `--envelope`（`--archive` 自动带）。
+
+深度研究只此一条，产出**取证包（dossier）**（来源/覆盖/缺口/达标，不是判断稿）：先读 `references/research-protocol.md` 写工作包再取证，判断按事实/推断/建议写。不要另装「专业深度研究」skill。
+
+## 核心命令
+
+### search — 统一搜索
+
+| 参数 | 说明 |
+|------|------|
+| `--engine <name>` | 强制引擎（anysearch/byted/bocha/exa/deepseek_search/tavily/eastmoney/zhihu/arxiv/pypi/mdn/hackernews/v2ex/redskill…，全量见 `--list-engines`） |
+| `--local-first` | 本地零成本聚合优先（local_search 29 引擎） |
+| `--include-local` / `--no-local` | 本机文件命中（source=local_files，score 0.9/0.7）：fast/budget 默认开，auto/deep 显式 |
+| `--mode fast|auto|deep|budget` | fast 免费优先 / auto 成本感知（默认）/ deep 质量优先 / budget 配额控制 |
+| `--explain` | 解释路由决策（含 TF-IDF 分数） |
+| `--no-cache` / `--depth fast|balanced|deep` | 跳过缓存 / 搜索深度 |
+| `--academic-deep` | 学术多源模式：自动设置 depth=deep + domain=academic，禁用 early-stop 让所有学术源参与（arxiv/openalex/local_pubmed/core 等） |
+| `--since 7d|2026-08-01` `--until` `--sort relevance|newest|oldest` | 时间窗过滤 + 时间排序 |
+| `--verify [N]` | 对 top-N 未核验结果 fetch 正文，回填证据分（URL→证据分缓存，同 URL 二次搜索自动复用） |
+| `--domain` `--sub_domain` | 垂直域 / 子域限定 |
+
+**按场景选引擎**：时事/时间窗 → deepseek_search，学术 → `--academic-deep`/exa，社交 → anysearch。口径与取舍见 `references/usage.md`。
+
+### 图片检索
+
+网络图走 `search`（`image_search` 域自动命中）；本地素材走 `argo local-image`
+（Vision 索引 + `--similar-to` 找相似图 + `--sheet` 出联络表；默认关，需 `ARGO_LOCAL_IMAGE=1`，见 `references/usage.md`）。
+
+### 增强三工具
+
+```bash
+# research — 取证（扩词或 --work-packages → 取证包 + 引用 + 达标检查）
+#   工作包可带 file_inputs / recompute（默认拒绝，需显式授权）
+#   社交舆情：--mode social-sentiment --platforms xiaohongshu,reddit,twitter
+python3 scripts/research.py "查询" [--work-packages PATH|JSON] [--depth deep] [--json] [--verify N]
+
+# evidence — 可信度评估（选拔×吸收两维）
+echo '{"results": [...]}' | python3 scripts/evidence.py "查询词" --stdin --json [--high-stakes]
+
+# clarify — 意图消歧
+python3 scripts/clarify.py "有歧义的查询" --json
+```
+
+
+### 抓取族（`bin/argo` 入口）
+
+```bash
+argo fetch "https://example.com" [--focus "关键词"] [--use-browser]
+# 降级链见 references/usage.md
+argo screenshot "https://example.com" [--full-page]
+argo pdf "https://example.com/paper.pdf" [--pages "1-5"] [--password "secret"]
+argo paper "1706.03762"  # 论文深读
+argo tweet "<x-url|id>"  # X 帖子打包（正文+串/引用/转发+媒体）
+argo answer "query" [--scope <语料>]   # 直答（语料见 usage.md）
+argo watch add|check|list|remove   # 观察模式（--json 供 cron）
+```
+
+## Agent 执行纪律
+
+1. **高后果问题**（金融/医疗/法律/事实核查）：search → evidence（或看 `credibility_fast`）→ fetch 高分 URL → 再下结论；`fetch_required=true` 时禁止跳过核验
+2. **数字**：必须标注算法（全市场/主动/持仓市值 vs 占比）；冲突时并列，禁止算法未对齐就合并
+3. **SERP 链**（baidu/s、sogou/link）：禁止当正文来源
+4. **社交帖**：叙事/舆情，不进事实真值
+5. **深度研究**：先读 `references/research-protocol.md`；有决策含义就交工作包，不要靠扩词充问题树；`quality_gate_results.passed=false` 必须降级表述
+6. **引用**：讲给用户的事实带 URL 出处，日常档也要带（URL 在 `results[].url`，零成本）
+7. **上下文纪律**：Agent 用 `--json --fields agent`、按需 `-n`；追溯/归档才加 `--envelope`；引擎状态用 `--list-engines --detail --engine <名>`（~0.9 KB）。踩坑见 Gotchas
+
+## Gotchas
+
+踩坑加一行，口径见 `references/usage.md`。
+
+- **`--envelope` 与 `--fields agent` 别同给**：后者把 envelope 增量剥成 0 字节；要 provenance 就去掉 `--fields agent`。
+- **结果异常少**：看 `funnel` 六格阶段计数，哪格归零即塌陷点。
+- **慢查询**：看 `timing.dispatch` 的 `tail_wait_ms`（就绪后还在等）/`abandoned_engine_ms`。
+- **`--list-engines` 别直接 `--all`**：全量 ~54 KB 灌爆版面，默认摘要够用。
+- **`-n` 超 10 无收益**。
+
+## 按需读取（低频操作细节）
+
+以下按需打开；日常搜索/抓取/研究走上面核心命令即可。
+
+| 场景 | 读什么 |
+|------|--------|
+| MCP 工具全清单 / 多客户端注入 / DSH 插件接入 / 配额·TinyFish / 子技能 / 本地打通 / 工程纪律 | `references/operations.md` |
+| **使用指南**：全命令、参数、86 开关总表、输出体积陷阱、日志反馈 | `references/usage.md` |
+| 深度研究协议：约定、工作包、取证包 vs 判断稿、达标检查 | `references/research-protocol.md` |
+| 约定 / 工作包 / 判断稿模板 | `references/research-templates.md` |
+| X 关键词搜索与查询模板（`argo x-search` / `argo template`，含机制与扩展） | `references/query-templates.md` |
+| 引擎全景：垂直域/社交/学术/本地引擎表 + 路由规则 | `references/engines.md` |
+| 学术检索：查询构造（arXiv/S2/GS 语法）、相关性五因子排序、引用网络挖掘、学术反模式与证据分级 | `references/academic-query.md` |
+| 架构：文件结构、证据流水线、量化公式、输出 JSON Schema、内容质量信号 | `references/architecture.md` |
+| MCP 多客户端注入详解 | `docs/MCP_SETUP.md` |
+| **搜索源使用文档**：全量清单（费用 / 密钥 / 状态 / 域组合）+ 特别能力 + 打开方式 | `docs/ENGINE_CATALOG.md`（生成，勿手改） |
+
+
+> 工程纪律（每个事实只定义一处：代码看本仓库、引擎声明看 config.yaml、宿主入口用 link_source.py 建软链、新增源流程）见 `references/operations.md` 末尾。

package/assets/readme/hero.svg

@@ -0,0 +1,121 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="380" viewBox="0 0 1200 380" role="img" aria-labelledby="title desc">
+  <title id="title">Argo 阿尔戈</title>
+  <desc id="desc">给 Agent 用的统一搜索与证据核验：按域按语言选路，返回能核验、能吸收的材料</desc>
+
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1200" y2="380" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#070B14"/>
+      <stop offset="55%" stop-color="#0B1220"/>
+      <stop offset="100%" stop-color="#0E1730"/>
+    </linearGradient>
+    <linearGradient id="route" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#38BDF8" stop-opacity="0.15"/>
+      <stop offset="50%" stop-color="#38BDF8" stop-opacity="0.85"/>
+      <stop offset="100%" stop-color="#A78BFA" stop-opacity="0.7"/>
+    </linearGradient>
+    <linearGradient id="barA" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#38BDF8"/>
+      <stop offset="100%" stop-color="#34D399"/>
+    </linearGradient>
+    <linearGradient id="barB" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#A78BFA"/>
+      <stop offset="100%" stop-color="#38BDF8"/>
+    </linearGradient>
+    <pattern id="dots" width="24" height="24" patternUnits="userSpaceOnUse">
+      <circle cx="1" cy="1" r="0.8" fill="#38BDF8" opacity="0.12"/>
+    </pattern>
+  </defs>
+
+  <rect width="1200" height="380" rx="28" fill="url(#bg)"/>
+  <rect width="1200" height="380" rx="28" fill="url(#dots)"/>
+
+  <!-- left accent rail -->
+  <rect x="0" y="48" width="4" height="284" fill="#38BDF8" opacity="0.9"/>
+
+  <!-- Title block -->
+  <g id="title-block" transform="translate(56 52)">
+    <text x="0" y="18" font-family="ui-monospace, SFMono-Regular, Menlo, monospace" font-size="13" fill="#38BDF8" letter-spacing="2.5">AGENT SEARCH · EVIDENCE ROUTER</text>
+    <text x="0" y="78" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="56" font-weight="700" fill="#E8EEF7">Argo</text>
+    <text x="168" y="78" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="34" font-weight="500" fill="#94A3B8">阿尔戈</text>
+    <text x="0" y="122" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="18" fill="#CBD5E1">给 Agent 用的统一搜索与证据核验</text>
+    <text x="0" y="152" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="16" fill="#64748B">不只返回链接 · 按域按语言选路 · 输出可吸收证据</text>
+
+    <!-- meta chips -->
+    <g transform="translate(0 188)">
+      <rect width="118" height="32" rx="8" fill="#121A2B" stroke="#1E2A3F"/>
+      <text x="59" y="21" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#94A3B8">v2.9.8</text>
+
+      <rect x="130" width="132" height="32" rx="8" fill="#121A2B" stroke="#1E2A3F"/>
+      <text x="196" y="21" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#38BDF8">272 engines</text>
+
+      <rect x="274" width="118" height="32" rx="8" fill="#121A2B" stroke="#1E2A3F"/>
+      <text x="333" y="21" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#A78BFA">19 MCP</text>
+
+      <rect x="404" width="100" height="32" rx="8" fill="#121A2B" stroke="#1E2A3F"/>
+      <text x="454" y="21" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#34D399">Python</text>
+    </g>
+
+    <!-- pipeline cue -->
+    <g transform="translate(0 248)" font-family="ui-monospace, Menlo, monospace" font-size="12">
+      <text x="0" y="0" fill="#475569">query</text>
+      <text x="58" y="0" fill="#334155">→</text>
+      <text x="78" y="0" fill="#38BDF8">lang</text>
+      <text x="118" y="0" fill="#334155">→</text>
+      <text x="138" y="0" fill="#38BDF8">route</text>
+      <text x="186" y="0" fill="#334155">→</text>
+      <text x="206" y="0" fill="#A78BFA">RRF</text>
+      <text x="244" y="0" fill="#334155">→</text>
+      <text x="264" y="0" fill="#34D399">evidence</text>
+    </g>
+  </g>
+
+  <!-- Right: live route proof card -->
+  <g id="project-proof" transform="translate(620 42)">
+    <rect width="528" height="296" rx="18" fill="#0D1526" stroke="#1E2A3F" stroke-width="1.5"/>
+    <!-- title bar -->
+    <rect width="528" height="40" rx="18" fill="#121A2B"/>
+    <rect y="22" width="528" height="18" fill="#121A2B"/>
+    <circle cx="22" cy="20" r="5" fill="#F87171" opacity="0.8"/>
+    <circle cx="40" cy="20" r="5" fill="#FBBF24" opacity="0.8"/>
+    <circle cx="58" cy="20" r="5" fill="#34D399" opacity="0.8"/>
+    <text x="86" y="24" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#64748B">argo search --json</text>
+
+    <!-- query line -->
+    <text x="24" y="68" font-family="ui-monospace, Menlo, monospace" font-size="13" fill="#475569">$</text>
+    <text x="42" y="68" font-family="ui-monospace, Menlo, monospace" font-size="13" fill="#E2E8F0">贵州茅台股价</text>
+    <rect x="360" y="52" width="144" height="24" rx="6" fill="#0B3B2E" stroke="#166534"/>
+    <text x="432" y="68" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#34D399">domain: stock</text>
+
+    <!-- route nodes -->
+    <g transform="translate(24 92)">
+      <text x="0" y="0" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">ROUTE</text>
+      <rect x="0" y="12" width="110" height="28" rx="7" fill="#122033" stroke="#1E3A5F"/>
+      <text x="55" y="30" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#38BDF8">sina_quote</text>
+      <rect x="122" y="12" width="128" height="28" rx="7" fill="#122033" stroke="#1E3A5F"/>
+      <text x="186" y="30" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#38BDF8">tencent_quote</text>
+      <rect x="262" y="12" width="100" height="28" rx="7" fill="#1A1430" stroke="#3B2F6B"/>
+      <text x="312" y="30" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#A78BFA">early-stop</text>
+      <path d="M 110 26 L 122 26" stroke="url(#route)" stroke-width="2"/>
+      <path d="M 250 26 L 262 26" stroke="url(#route)" stroke-width="2"/>
+    </g>
+
+    <!-- result card -->
+    <g transform="translate(24 156)">
+      <rect width="480" height="118" rx="12" fill="#101826" stroke="#243044"/>
+      <text x="16" y="28" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="15" font-weight="600" fill="#E8EEF7">贵州茅台 1337.74  ↓ -1.56%</text>
+      <text x="16" y="52" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">source · sina_quote · 553ms · fact-ready</text>
+
+      <!-- score bars -->
+      <text x="16" y="82" font-family="ui-monospace, Menlo, monospace" font-size="10" fill="#64748B">selection</text>
+      <rect x="92" y="72" width="160" height="8" rx="4" fill="#1E2A3F"/>
+      <rect x="92" y="72" width="144" height="8" rx="4" fill="url(#barA)"/>
+
+      <text x="16" y="104" font-family="ui-monospace, Menlo, monospace" font-size="10" fill="#64748B">absorption</text>
+      <rect x="92" y="94" width="160" height="8" rx="4" fill="#1E2A3F"/>
+      <rect x="92" y="94" width="132" height="8" rx="4" fill="url(#barB)"/>
+
+      <text x="280" y="88" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#34D399">not a SERP shell</text>
+      <text x="280" y="106" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#94A3B8">digits + quote snapshot</text>
+    </g>
+  </g>
+</svg>

package/assets/readme/made-with-beautify.svg

@@ -0,0 +1,10 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="420" height="64" viewBox="0 0 420 64" role="img" aria-labelledby="title desc">
+  <title id="title">README made with beautify-github-readme</title>
+  <desc id="desc">Compact project-native credit for the README redesign skill</desc>
+  <rect width="420" height="64" rx="12" fill="#0B1220" stroke="#1E2A3F"/>
+  <rect x="0" y="16" width="3" height="32" fill="#38BDF8"/>
+  <text x="20" y="28" font-family="ui-monospace, Menlo, monospace" font-size="10" fill="#64748B" letter-spacing="1.5">README MADE WITH</text>
+  <text x="20" y="48" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, sans-serif" font-size="14" font-weight="600" fill="#E8EEF7">beautify-github-readme</text>
+  <circle cx="380" cy="32" r="10" fill="none" stroke="#38BDF8" stroke-width="1.5"/>
+  <path d="M376 32 L384 32 M380 28 L384 32 L380 36" stroke="#38BDF8" stroke-width="1.5" fill="none" stroke-linecap="round"/>
+</svg>

package/assets/readme/proof-routes.svg

@@ -0,0 +1,73 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="420" viewBox="0 0 1200 420" role="img" aria-labelledby="title desc">
+  <title id="title">Argo 问啥像啥</title>
+  <desc id="desc">四类真实路由：A股行情、影视、多语言、地理实体各自命中垂直源</desc>
+
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0%" stop-color="#070B14"/>
+      <stop offset="100%" stop-color="#0B1220"/>
+    </linearGradient>
+  </defs>
+
+  <rect width="1200" height="420" rx="28" fill="url(#bg)"/>
+
+  <text x="56" y="48" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#38BDF8" letter-spacing="2">PROOF · REAL ROUTES</text>
+  <text x="56" y="82" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="26" font-weight="650" fill="#E8EEF7">问啥像啥 · 垂直源优先</text>
+  <text x="56" y="110" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="14" fill="#64748B">同样是「搜索」，路由不同 · 答案形态不同 · 可信度字段跟输出一起回来</text>
+
+  <!-- card 1 finance -->
+  <g transform="translate(56 140)">
+    <rect width="260" height="230" rx="16" fill="#0D1526" stroke="#1E2A3F"/>
+    <rect x="16" y="16" width="64" height="22" rx="6" fill="#0B3B2E"/>
+    <text x="48" y="31" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="10" fill="#34D399">FINANCE</text>
+    <text x="16" y="64" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="15" font-weight="600" fill="#E8EEF7">贵州茅台股价</text>
+    <text x="16" y="92" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">domain</text>
+    <text x="16" y="112" font-family="ui-monospace, Menlo, monospace" font-size="13" fill="#38BDF8">stock_query</text>
+    <text x="16" y="142" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">engines</text>
+    <text x="16" y="162" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#CBD5E1">sina · tencent</text>
+    <text x="16" y="192" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">result shape</text>
+    <text x="16" y="212" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="13" fill="#94A3B8">报价快照 · early-stop</text>
+  </g>
+
+  <!-- card 2 film -->
+  <g transform="translate(332 140)">
+    <rect width="260" height="230" rx="16" fill="#0D1526" stroke="#1E2A3F"/>
+    <rect x="16" y="16" width="52" height="22" rx="6" fill="#1A1430"/>
+    <text x="42" y="31" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="10" fill="#A78BFA">FILM</text>
+    <text x="16" y="64" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="15" font-weight="600" fill="#E8EEF7">Inception director</text>
+    <text x="16" y="92" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">domain</text>
+    <text x="16" y="112" font-family="ui-monospace, Menlo, monospace" font-size="13" fill="#A78BFA">film_search</text>
+    <text x="16" y="142" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">engines</text>
+    <text x="16" y="162" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#CBD5E1">imdb · itunes</text>
+    <text x="16" y="192" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">result shape</text>
+    <text x="16" y="212" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="13" fill="#94A3B8">作品页 · 实体字段</text>
+  </g>
+
+  <!-- card 3 multilingual -->
+  <g transform="translate(608 140)">
+    <rect width="260" height="230" rx="16" fill="#0D1526" stroke="#1E2A3F"/>
+    <rect x="16" y="16" width="48" height="22" rx="6" fill="#0C2A3A"/>
+    <text x="40" y="31" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="10" fill="#38BDF8">LANG</text>
+    <text x="16" y="64" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="15" font-weight="600" fill="#E8EEF7">アニメ おすすめ</text>
+    <text x="16" y="92" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">query_lang</text>
+    <text x="16" y="112" font-family="ui-monospace, Menlo, monospace" font-size="13" fill="#38BDF8">ja · no zh-only</text>
+    <text x="16" y="142" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">engines</text>
+    <text x="16" y="162" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#CBD5E1">local_bing · ddg</text>
+    <text x="16" y="192" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">gate</text>
+    <text x="16" y="212" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="13" fill="#94A3B8">避开中文专用源</text>
+  </g>
+
+  <!-- card 4 geo -->
+  <g transform="translate(884 140)">
+    <rect width="260" height="230" rx="16" fill="#0D1526" stroke="#1E2A3F"/>
+    <rect x="16" y="16" width="44" height="22" rx="6" fill="#2A2310"/>
+    <text x="38" y="31" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="10" fill="#FBBF24">GEO</text>
+    <text x="16" y="64" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="15" font-weight="600" fill="#E8EEF7">where is Eiffel Tower</text>
+    <text x="16" y="92" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">domain</text>
+    <text x="16" y="112" font-family="ui-monospace, Menlo, monospace" font-size="13" fill="#FBBF24">geo_places</text>
+    <text x="16" y="142" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">engines</text>
+    <text x="16" y="162" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#CBD5E1">openstreetmap · wiki</text>
+    <text x="16" y="192" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#64748B">result shape</text>
+    <text x="16" y="212" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="13" fill="#94A3B8">坐标 · 实体定位</text>
+  </g>
+</svg>

package/assets/readme/why-better.svg

@@ -0,0 +1,104 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="400" viewBox="0 0 1200 400" role="img" aria-labelledby="title desc">
+  <title id="title">Argo 与其他搜索方式的差别</title>
+  <desc id="desc">左侧：模型自带搜索、AI 搜索、聚合搜索引擎给人看的总结页或链接清单；右侧：Argo 给 Agent 的证据 JSON 与可信度评分</desc>
+
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1200" y2="400" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#070B14"/>
+      <stop offset="55%" stop-color="#0B1220"/>
+      <stop offset="100%" stop-color="#0E1730"/>
+    </linearGradient>
+    <linearGradient id="route" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#38BDF8" stop-opacity="0.15"/>
+      <stop offset="50%" stop-color="#38BDF8" stop-opacity="0.85"/>
+      <stop offset="100%" stop-color="#A78BFA" stop-opacity="0.7"/>
+    </linearGradient>
+    <linearGradient id="barA" x1="0" y1="0" x2="1" y2="0">
+      <stop offset="0%" stop-color="#38BDF8"/>
+      <stop offset="100%" stop-color="#34D399"/>
+    </linearGradient>
+    <pattern id="dots" width="24" height="24" patternUnits="userSpaceOnUse">
+      <circle cx="1" cy="1" r="0.8" fill="#38BDF8" opacity="0.12"/>
+    </pattern>
+  </defs>
+
+  <rect width="1200" height="400" rx="28" fill="url(#bg)"/>
+  <rect width="1200" height="400" rx="28" fill="url(#dots)"/>
+
+  <!-- column headers -->
+  <text x="48" y="44" font-family="ui-monospace, Menlo, monospace" font-size="13" fill="#64748B" letter-spacing="2.5">HUMAN-FACING · 给人看</text>
+  <text x="720" y="44" font-family="ui-monospace, Menlo, monospace" font-size="13" fill="#38BDF8" letter-spacing="2.5">AGENT-FACING · 给 Agent 吸收</text>
+
+  <!-- left: three default alternatives -->
+  <g id="default-1" transform="translate(48 68)">
+    <rect width="480" height="76" rx="10" fill="#0D1526" stroke="#1E2A3F"/>
+    <rect width="3" height="76" fill="#334155"/>
+    <text x="20" y="28" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#94A3B8">模型自带搜索</text>
+    <text x="20" y="54" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="13" fill="#64748B">泛搜网页 → 拼一段长文本，塞回 Agent 上下文</text>
+  </g>
+  <g id="default-2" transform="translate(48 156)">
+    <rect width="480" height="76" rx="10" fill="#0D1526" stroke="#1E2A3F"/>
+    <rect width="3" height="76" fill="#334155"/>
+    <text x="20" y="28" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#94A3B8">AI 搜索（总结型）</text>
+    <text x="20" y="54" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="13" fill="#64748B">总结页给人看；Agent 拿不到结构化证据</text>
+  </g>
+  <g id="default-3" transform="translate(48 244)">
+    <rect width="480" height="76" rx="10" fill="#0D1526" stroke="#1E2A3F"/>
+    <rect width="3" height="76" fill="#334155"/>
+    <text x="20" y="28" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#94A3B8">聚合搜索 / 搜索引擎</text>
+    <text x="20" y="54" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="13" fill="#64748B">SERP 链接清单；无评分、无垂直门禁</text>
+  </g>
+
+  <text x="48" y="356" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#475569">default search answers people · argo answers agents</text>
+
+  <!-- vs badge -->
+  <circle cx="624" cy="196" r="26" fill="#0D1526" stroke="#38BDF8" stroke-width="2"/>
+  <text x="624" y="202" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="15" fill="#38BDF8">vs</text>
+
+  <!-- right: argo proof card -->
+  <g id="argo-card" transform="translate(720 68)">
+    <rect width="432" height="288" rx="16" fill="#0D1526" stroke="#1E3A5F" stroke-width="1.5"/>
+    <!-- title bar -->
+    <rect width="432" height="36" rx="16" fill="#121A2B"/>
+    <rect y="20" width="432" height="16" fill="#121A2B"/>
+    <circle cx="20" cy="18" r="4.5" fill="#F87171" opacity="0.8"/>
+    <circle cx="36" cy="18" r="4.5" fill="#FBBF24" opacity="0.8"/>
+    <circle cx="52" cy="18" r="4.5" fill="#34D399" opacity="0.8"/>
+    <text x="70" y="23" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#64748B">argo search --json</text>
+
+    <!-- query line -->
+    <text x="20" y="66" font-family="ui-monospace, Menlo, monospace" font-size="13" fill="#475569">$</text>
+    <text x="36" y="66" font-family="ui-monospace, Menlo, monospace" font-size="13" fill="#E2E8F0">贵州茅台股价</text>
+    <rect x="296" y="52" width="116" height="22" rx="6" fill="#0B3B2E" stroke="#166534"/>
+    <text x="354" y="67" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="11" fill="#34D399">domain: stock</text>
+
+    <!-- route nodes -->
+    <g transform="translate(20 84)">
+      <text x="0" y="0" font-family="ui-monospace, Menlo, monospace" font-size="10" fill="#64748B">ROUTE</text>
+      <rect x="0" y="10" width="92" height="26" rx="6" fill="#122033" stroke="#1E3A5F"/>
+      <text x="46" y="28" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="10.5" fill="#38BDF8">sina_quote</text>
+      <rect x="104" y="10" width="104" height="26" rx="6" fill="#122033" stroke="#1E3A5F"/>
+      <text x="156" y="28" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="10.5" fill="#38BDF8">tencent_quote</text>
+      <rect x="220" y="10" width="84" height="26" rx="6" fill="#1A1430" stroke="#3B2F6B"/>
+      <text x="262" y="28" text-anchor="middle" font-family="ui-monospace, Menlo, monospace" font-size="10.5" fill="#A78BFA">early-stop</text>
+      <path d="M 92 23 L 104 23" stroke="url(#route)" stroke-width="2"/>
+      <path d="M 208 23 L 220 23" stroke="url(#route)" stroke-width="2"/>
+    </g>
+
+    <!-- result card -->
+    <g transform="translate(20 136)">
+      <rect width="392" height="112" rx="10" fill="#101826" stroke="#243044"/>
+      <text x="14" y="22" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="14" font-weight="600" fill="#E8EEF7">贵州茅台 1337.74  ↓ -1.56%</text>
+      <text x="14" y="42" font-family="ui-monospace, Menlo, monospace" font-size="10" fill="#64748B">source · sina_quote · 553ms · fact-ready</text>
+      <text x="14" y="62" font-family="ui-monospace, Menlo, monospace" font-size="9.5" fill="#94A3B8">{ "price": "1337.74", "credibility_fast": 0.86 }</text>
+      <text x="14" y="78" font-family="ui-monospace, Menlo, monospace" font-size="9.5" fill="#94A3B8">  "engine_outcomes": { "sina_quote": "ok" } }</text>
+      <text x="14" y="98" font-family="ui-monospace, Menlo, monospace" font-size="9.5" fill="#64748B">selection</text>
+      <rect x="86" y="90" width="120" height="6" rx="3" fill="#1E2A3F"/>
+      <rect x="86" y="90" width="108" height="6" rx="3" fill="url(#barA)"/>
+      <text x="230" y="98" font-family="ui-monospace, Menlo, monospace" font-size="10" fill="#34D399">not a SERP shell</text>
+    </g>
+
+    <!-- bottom cue -->
+    <text x="20" y="272" font-family="ui-monospace, Menlo, monospace" font-size="10.5" fill="#64748B">free-first · ~10ms cache · fast/auto/deep/budget</text>
+  </g>
+</svg>

package/assets/readme/workflow.svg

@@ -0,0 +1,83 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="360" viewBox="0 0 1200 360" role="img" aria-labelledby="title desc">
+  <title id="title">Argo 工作流</title>
+  <desc id="desc">从查询到统一 JSON：语言检测、路由、多引擎召回、RRF 融合、证据快评</desc>
+
+  <defs>
+    <linearGradient id="bg" x1="0" y1="0" x2="1200" y2="360" gradientUnits="userSpaceOnUse">
+      <stop offset="0%" stop-color="#070B14"/>
+      <stop offset="100%" stop-color="#0B1220"/>
+    </linearGradient>
+    <marker id="arr" markerWidth="8" markerHeight="8" refX="6" refY="3" orient="auto">
+      <path d="M0,0 L6,3 L0,6 Z" fill="#475569"/>
+    </marker>
+  </defs>
+
+  <rect width="1200" height="360" rx="28" fill="url(#bg)"/>
+
+  <text x="56" y="44" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#38BDF8" letter-spacing="2">HOW IT WORKS</text>
+  <text x="56" y="76" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="24" font-weight="650" fill="#E8EEF7">一条查询的完整路径</text>
+
+  <!-- stage boxes row -->
+  <g font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif">
+    <!-- 1 -->
+    <rect x="56" y="120" width="150" height="96" rx="14" fill="#0D1526" stroke="#1E2A3F"/>
+    <text x="131" y="152" text-anchor="middle" font-size="11" fill="#64748B" font-family="ui-monospace, Menlo, monospace">01</text>
+    <text x="131" y="178" text-anchor="middle" font-size="15" font-weight="600" fill="#E8EEF7">查询</text>
+    <text x="131" y="200" text-anchor="middle" font-size="11" fill="#64748B">改写可选</text>
+
+    <!-- 2 -->
+    <rect x="246" y="120" width="150" height="96" rx="14" fill="#0D1526" stroke="#1E3A5F"/>
+    <text x="321" y="152" text-anchor="middle" font-size="11" fill="#38BDF8" font-family="ui-monospace, Menlo, monospace">02</text>
+    <text x="321" y="178" text-anchor="middle" font-size="15" font-weight="600" fill="#E8EEF7">语言 + 域</text>
+    <text x="321" y="200" text-anchor="middle" font-size="11" fill="#64748B">检测 · 规则 · TF-IDF</text>
+
+    <!-- 3 -->
+    <rect x="436" y="120" width="150" height="96" rx="14" fill="#0D1526" stroke="#1E3A5F"/>
+    <text x="511" y="152" text-anchor="middle" font-size="11" fill="#38BDF8" font-family="ui-monospace, Menlo, monospace">03</text>
+    <text x="511" y="178" text-anchor="middle" font-size="15" font-weight="600" fill="#E8EEF7">多引擎召回</text>
+    <text x="511" y="200" text-anchor="middle" font-size="11" fill="#64748B">熔断 · 负缓存</text>
+
+    <!-- 4 -->
+    <rect x="626" y="120" width="150" height="96" rx="14" fill="#0D1526" stroke="#3B2F6B"/>
+    <text x="701" y="152" text-anchor="middle" font-size="11" fill="#A78BFA" font-family="ui-monospace, Menlo, monospace">04</text>
+    <text x="701" y="178" text-anchor="middle" font-size="15" font-weight="600" fill="#E8EEF7">RRF 融合</text>
+    <text x="701" y="200" text-anchor="middle" font-size="11" fill="#64748B">分阶恢复</text>
+
+    <!-- 5 -->
+    <rect x="816" y="120" width="150" height="96" rx="14" fill="#0D1526" stroke="#166534"/>
+    <text x="891" y="152" text-anchor="middle" font-size="11" fill="#34D399" font-family="ui-monospace, Menlo, monospace">05</text>
+    <text x="891" y="178" text-anchor="middle" font-size="15" font-weight="600" fill="#E8EEF7">证据快评</text>
+    <text x="891" y="200" text-anchor="middle" font-size="11" fill="#64748B">权威 · 密度 · 时效</text>
+
+    <!-- 6 -->
+    <rect x="1006" y="120" width="138" height="96" rx="14" fill="#122033" stroke="#38BDF8" stroke-opacity="0.5"/>
+    <text x="1075" y="152" text-anchor="middle" font-size="11" fill="#38BDF8" font-family="ui-monospace, Menlo, monospace">06</text>
+    <text x="1075" y="178" text-anchor="middle" font-size="15" font-weight="600" fill="#E8EEF7">统一 JSON</text>
+    <text x="1075" y="200" text-anchor="middle" font-size="11" fill="#64748B">Agent 可吸收</text>
+  </g>
+
+  <!-- arrows -->
+  <g stroke="#475569" stroke-width="1.5" fill="none" marker-end="url(#arr)">
+    <path d="M210 168 H240"/>
+    <path d="M400 168 H430"/>
+    <path d="M590 168 H620"/>
+    <path d="M780 168 H810"/>
+    <path d="M970 168 H1000"/>
+  </g>
+
+  <!-- bottom notes -->
+  <g transform="translate(56 260)">
+    <rect width="1088" height="64" rx="12" fill="#0D1526" stroke="#1E2A3F"/>
+    <text x="24" y="28" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#64748B">budget</text>
+    <text x="24" y="48" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="13" fill="#CBD5E1">fast · auto · deep · budget</text>
+
+    <text x="280" y="28" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#64748B">cache</text>
+    <text x="280" y="48" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="13" fill="#CBD5E1">内存 + SQLite · 热查询约 10ms</text>
+
+    <text x="580" y="28" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#64748B">recovery gate</text>
+    <text x="580" y="48" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="13" fill="#CBD5E1">空结果可恢复 · 禁无关垂直源串味</text>
+
+    <text x="900" y="28" font-family="ui-monospace, Menlo, monospace" font-size="12" fill="#64748B">local + web</text>
+    <text x="900" y="48" font-family="-apple-system, BlinkMacSystemFont, Segoe UI, PingFang SC, sans-serif" font-size="13" fill="#CBD5E1">联网 + 本机文件一体</text>
+  </g>
+</svg>