中文 ·
English ·
日本語 ·
한국어 ·
Español
Intro ·
Prueba ·
Mecanismo ·
Inicio rápido ·
Capacidades ·
Config ·
Actualizaciones
---
## Qué es
**Argo es infraestructura de búsqueda multilingüe para agentes de IA.**
La recuperación real nunca es «un idioma + un cuadro de búsqueda»: alguien pregunta por cotizaciones de acciones A, alguien más por el Mundial, alguien busca anime en japonés, alguien quiere el director de una película en IMDb. La premisa de Argo es simple: **enrutar por dominio, idioma e intención** hacia las fuentes adecuadas, en lugar de siempre raspado genérico de títulos web. La búsqueda en la red y la de archivos locales funcionan juntas.
> El resultado no es una «lista de enlaces», sino **candidatos de evidencia + desglose de credibilidad**. Un buen enrutamiento es lo que hace que la evidencia se sostenga.
### frente a «envolver otra API de búsqueda»
| Enfoque habitual | Argo |
|-----------------|------|
| Atado a un motor y una clave | Multi-motor con enrutamiento automático; gratis primero, con presupuesto |
| Toda consulta es búsqueda web genérica | **Fuentes verticales primero**: mercados, cine, deportes, macro, química… resultados en forma de respuesta |
| Optimizado solo para chino/inglés | **Detección de idioma + parámetros de locale + fallback interlingüístico** |
| Resumir snippets y listo | Selección × densidad de evidencia × frescura × consenso multi-fuente |
| Un motor caído tumba la cadena | Cortacircuitos, caché negativa, recuperación por etapas (sin contaminación vertical) |
| Red en cada consulta | Caché de dos capas (memoria + SQLite); consultas calientes ~10 ms |
| Misma ruta lenta para diario e investigación | **Menos motores en el día a día; más abiertos en investigación profunda** |
| JSON largo agota el contexto del agente | Respuestas MCP compactas; snippets controlables |
---
## Enrutamiento según la consulta
| Preguntas así | Lo que suele ocurrir |
|---------|----------------------|
| 贵州茅台股价 | Dominio de cotizaciones A-share; fuentes snapshot primero; early-stop si basta |
| AAPL / US pre-market | Dominio de acciones EE. UU., separado de A-shares |
| 肖申克的救赎 主演 / Inception director | Dominio cine → IMDb etc. |
| 梅西 俱乐部 / 库里 球队 | Dominio deportes → TheSportsDB etc. |
| 埃菲尔铁塔在哪 / where is Eiffel Tower | Entidad geo → OpenStreetMap etc. |
| NASA founding year / 国务院职能 | Entidad org → Wikidata etc. |
| 周杰伦 专辑 / Taylor Swift album | Dominio media → iTunes etc. |
| アニメ おすすめ / 한국 영화 추천 | Detecta JA/KO → fuentes amigables al idioma; evita sitios solo en chino |
| US CPI, China GDP | Dominio macro; separa por país |
| 阿司匹林 分子式 | Química → respuestas tipo PubChem |
| TSMC valuation debate (deep research) | Subpreguntas + fuentes en paralelo; verticales reforzados |
---
## Cómo funciona
```
query
├─ intent clarify (optional)
├─ query rewrite (optional; routing still sees original intent)
├─ language detect + language preference
├─ route (domain rules + TF-IDF + budget + lang supplements + hot-path cache)
├─ multi-engine recall (circuit breaker / negative cache / parallel)
├─ staged empty-result recovery (widen → same family/general → cross-lang; anti-pollution)
├─ RRF fusion + optional re-rank
├─ evidence skim (authority · density · freshness · consensus)
└─ unified JSON (incl. engine_outcomes / recovery)
```
### Puntuación de evidencia (resumen)
```
selection ≈ domain authority; SERP / redirect shells ranked very low
absorption ≈ density of numbers / definitions / comparisons / disclosures
freshness ≈ publish time (ignores historical comparison years like “since 2015”)
composite ≈ 0.40·selection + 0.35·absorption + 0.15·freshness + 0.10·engine score
```
Los resultados incluyen `selection`, `absorption`, `credibility_fast`, `evidence_flags`, etc. para que el agente ordene directamente.
### Disciplina del agente (recomendada)
1. **Preguntas de alto riesgo** (posiciones, seguridad, «¿es cierto?»): buscar → leer puntuaciones rápidas → `fetch` de los top → luego concluir
2. **Números**: declarar el口径 (definición/alcance); si las fuentes chocan, listarlas—no forzar fusión
3. **Páginas SERP / redirección**: nunca como fuente primaria
4. **Posts sociales**: sentimiento y narrativa, no verdad de fondo
5. **Fact-check**: preferir pocas consultas estratificadas (fuente / comparación / sujeto)
---
## Inicio rápido
Elige cualquier camino. **No necesitas el paquete del registro npm** para la build más reciente (desde v2.5.1 **GitHub** es la fuente de verdad de instalación; recomendación actual **v2.6.0**).
**Funciona sin configuración**: sin claves API corren motores gratis + `local_*` locales; los que requieren clave se omiten si faltan (y suelen mejorar cuando están).
### Opción 1: Script de instalación (mejor para uso local a largo plazo)
```bash
curl -fsSL https://raw.githubusercontent.com/taxueseek/argo/main/scripts/install.sh | bash
```
Home personalizado + enlace de Skill:
```bash
curl -fsSL https://raw.githubusercontent.com/taxueseek/argo/main/scripts/install.sh \
| bash -s -- --home "$HOME/.local/share/argo" --link "$HOME/.claude/skills/argo"
```
Verificar:
```bash
python3 ~/.local/share/argo/scripts/search.py "贵州茅台股价" --json
python3 ~/.local/share/argo/scripts/search.py --list-engines
```
### Opción 2: MCP desde GitHub (enganche rápido del agente)
Necesita **Node.js 18+** y **Python 3.10+**. Una vez:
```bash
pip3 install pyyaml
```
```bash
npx -y github:taxueseek/argo
```
Config del cliente (Claude Code / Cursor / Kimi, etc.):
```json
{
"mcpServers": {
"argo": {
"command": "npx",
"args": ["-y", "github:taxueseek/argo"]
}
}
}
```
Más estable, sin Node: instala con la opción 1 y apunta a Python local:
```json
{
"mcpServers": {
"argo": {
"command": "python3",
"args": ["/path/to/argo/scripts/mcp_server.py"]
}
}
}
```
Ruta de Python inusual: `export ARGO_PYTHON=/path/to/python3` (solo lo lee la entrada npx).
### Opción 3: Tarball de release
Abre [Releases](https://github.com/taxueseek/argo/releases), descarga **`argo-2.6.0.tar.gz`**:
```bash
tar -xzf argo-2.6.0.tar.gz
cd argo-2.6.0
pip3 install pyyaml
python3 scripts/search.py "Python asyncio" --json
python3 scripts/mcp_server.py
```
### Opción 4: git clone (dev / parchear fuente)
```bash
git clone https://github.com/taxueseek/argo.git
cd argo
pip3 install pyyaml
bash scripts/install.sh --link ~/.claude/skills/argo # optional
python3 scripts/search.py --list-engines
```
### Opción 5: Directorio Skill (symlink, una sola fuente de verdad)
```bash
python3 scripts/link_source.py --to ~/.claude/skills/argo
python3 scripts/link_source.py --to ~/.agents/skills/argo
cp installs.local.yaml.example installs.local.yaml
python3 scripts/link_source.py
python3 scripts/link_source.py --check
```
### Opción 6: Biblioteca Python
```python
import sys
sys.path.insert(0, "/path/to/argo/scripts")
from search import super_search
result = super_search("Python asyncio", n=5, mode="fast")
for item in result["results"]:
print(item["title"], item.get("credibility_fast"), item["url"])
```
```bash
# if bin/argo is on PATH
argo search "Python asyncio"
argo research "2026 mutual fund holdings structure"
argo evidence "a claim to verify"
```
---
## Plataformas
| Plataforma | Integración | Notas |
|----------|-------------|-------|
| **Claude Code** | MCP / enlace Skill | `npx` o `mcp_server.py`; `link_source.py` ok |
| **Kimi / Grok Build** | MCP Server | igual |
| **Cursor / Cline / Continue** | MCP | cualquier plugin IDE con MCP |
| **CLI** | `search.py` / `bin/argo` | scripts, cron, debug manual |
| **Proyectos Python** | `from search import super_search` | llamada de librería |
### Comprobación post-instalación
```bash
python3 --version # 3.10+
python3 -c "import yaml; print('PyYAML OK')"
python3 -m pytest tests/test_unit.py -q # optional
python3 scripts/search.py --list-engines
```
---
## Capacidades
| Capacidad | Qué hace | Entrada |
|------------|--------------|-------|
| Búsqueda unificada | route → recall → fuse → skim score | `search.py` / `argo_search` |
| Búsqueda de archivos locales | código/notas/memoria en disco (offline) | `argo_local_search` |
| Investigación profunda | subpreguntas, multi-fuente, pistas de huecos | `research.py` / `argo_research` |
| Credibilidad | autoridad / densidad / frescura / cruce | `evidence.py` / `argo_evidence` |
| Aclarar intención | polisemia, colisiones de marca, pistas de estrategia | `clarify.py` / `argo_clarify` |
| Fetch de página | HTTP primero, navegador si hace falta | `argo_fetch` (`mode=extract` para estructura) |
| Captura / PDF | capturas de página, extracto PDF estructurado | `argo_screenshot` / `argo_pdf` |
| Crawl de sitio | crawl por lotes de páginas de listado | `argo_crawl` |
| Social / sentimiento | Weibo / Xiaohongshu / Bilibili / Reddit / X … | `argo_social_search` |
### Modos de presupuesto
| Modo | Mejor para | Comportamiento |
|------|----------|----------|
| `fast` | Q simple, necesita velocidad | motores gratis primero; omite re-rank de pago |
| `auto` | default diario | equilibrio calidad/gasto con conciencia de coste |
| `deep` | investigación, sondeos | calidad primero; más motores |
| `budget` | cuota justa | control de cuota; degrada al agotarse |
### Conjunto aproximado de capacidades (v2.6.0)
- **~120+ fuentes, 60+ dominios**: web general + finanzas / macro / cine / deportes / geo / orgs / media / química / academia / código (fuente de verdad: `config.yaml`)
- **10 herramientas MCP**: search, research, evidence, clarify, fetch, screenshot, PDF, social, archivos locales, crawl
- **Búsqueda multilingüe**: chino, inglés, japonés, coreano, cirílico, tailandés, árabe, hebreo, griego, devanagari, …; el enrutamiento y los params de motor siguen el idioma; consultas no chinas evitan fuentes solo en chino (Zhihu / Sogou WeChat / snapshots A-share, etc.)
- **Compuertas de recuperación vertical**: la recuperación de vacío no «filtra» pypi / npm / flash news a cine o deportes
- **Más rápido en el día a día, más completo en investigación**: tiers `engine_policy`—combo diario apretado, long-tail abierto para deep / research
---
## Motores y enrutamiento
La config tiene ahora unos **120+** fuentes y **60+** dominios (ver `config.yaml` y `--list-engines`).
### Directos y verticales (extracto)
| Motor | Escenario | Sesgo de coste |
|--------|----------|-----------|
| anysearch / duckduckgo | general / tech | free |
| sina_quote / tencent_quote / eastmoney | cotizaciones A-share / flujos | free |
| finviz / seeking_alpha | finanzas EE. UU. y exterior | depends |
| imdb / itunes / thesportsdb | cine / música / deportes | mostly free |
| local_openstreetmap / wikidata / wikipedia | geo / org / enciclopedia | free |
| arxiv / semantic_scholar / openalex | académico | mostly free |
| pubchem / gbif / rfc_editor | química / especies / estándares | free |
| github / stackoverflow / pypi / npm | código y paquetes | depends |
| byted / bocha / metaso / octen | web china / búsqueda IA | API / low cost |
| zhihu / wechat_sogou | opinión china / WeChat | API / free |
| tavily / felo / exa | internacional / semántica | paid or quota |
| twitter / reddit / xiaohongshu / bilibili / weibo | social UGC | free (some need login) |
### Capa local de coste cero (`local_*`)
No hace falta un servicio SearXNG aparte. La ruta principal usa parseo in-process de HTML / RSS / JSON (`local_bing`, `local_sogou`, `local_google`, `local_arxiv`, …). En **consultas multilingües**, el enrutamiento reescribe params de idioma del motor (p. ej. Bing `setlang`) y fusiona con RRF.
---
## Ejemplos
### Finanzas
```bash
python3 scripts/search.py "贵州茅台股价" --explain
# typical: stock_query → quote snapshot sources
```
### Académico
```bash
python3 scripts/search.py "transformer attention mechanism paper" --json
# domain often academic; combo includes arxiv etc.
```
### Investigar y verificar
```bash
python3 scripts/research.py "2026 mutual fund Q2 holdings structure" --depth deep --json
python3 scripts/search.py "same query" --json | \
python3 scripts/evidence.py "same query" --stdin --json
```
### Herramientas MCP (10)
| Herramienta | Propósito |
|------|---------|
| `argo_search` | búsqueda unificada |
| `argo_local_search` | archivos locales (offline) |
| `argo_research` | investigación profunda (incl. modo sentimiento social) |
| `argo_evidence` | puntuación de credibilidad |
| `argo_clarify` | desambiguación de intención |
| `argo_fetch` | fetch inteligente (`mode=extract` extracto estructurado) |
| `argo_crawl` | crawl de sitio |
| `argo_screenshot` | captura de página |
| `argo_pdf` | extracto PDF |
| `argo_social_search` | social multi-plataforma (`mode=sentiment`) |
---
## Instalación y configuración
### Requisitos
| Ítem | Requisito |
|------|-------------|
| Python | 3.10+ (CLI + núcleo MCP) |
| Deps | `pip install pyyaml` (única dependencia dura) |
| Node.js | **solo** para entrada `npx`, 18+ |
| SearXNG | no requerido (motores locales integrados) |
### Claves API (todas opcionales)
Sin clave se omite ese motor; los gratis sostienen. **Usa variables de entorno**—nunca commits de claves reales ni pegarlas en issues.
```bash
# recommended (better quality)
export TAVILY_API_KEY="your_key"
export BOCHA_API_KEY="your_key"
export METASO_API_KEY="your_key"
export ZHIHU_ACCESS_SECRET="your_key"
# optional
export BRAVE_API_KEY="your_key"
export FELO_API_KEY="your_key"
export GITHUB_TOKEN="your_key"
export WEB_SEARCH_API_KEY="your_key"
export ANYSEARCH_API_KEY="your_key"
export OCTEN_API_KEY="your_key"
```
`config.yaml` solo guarda placeholders `{ENV_NAME}`—sin secretos en claro en git.
### Caché
La ruta SQLite por defecto es `cache.db_path` en `config.yaml` (suele ser `~/.cache/unified-search/cache.db`).
| Tipo | TTL aprox. |
|------|-------------|
| Finance | ~5 min |
| News / realtime | ~10–15 min |
| General | ~1 hour |
| Research / evergreen | ~2–24 hours |
| Empty results | very short (avoid freezing “no hits”) |
### FAQ
**¿Funciona sin claves API?**
Sí. Muchos motores locales gratis y APIs gratis; la ruta sin clave es automática.
**¿Script de instalación vs npx?**
Script: instalación local fija, config, enlace Skill. npx: enganchar MCP rápido. Mismo núcleo Python.
**¿Cómo ver los motores?**
`python3 scripts/search.py --list-engines`, o añade `--explain`.
**¿Varias copias de código en el repo?**
No. Prefiere una fuente + symlinks con `link_source.py`, no clones rsync.
---
## Flags CLI
```
python3 scripts/search.py [options] query
--engine, -e engine, default auto
--max-results, -n count, default 5
--depth, -d fast | balanced | deep
--mode fast | auto | deep | budget
--no-cache skip cache
--explain print routing explanation
--json JSON output
--timeout, -t timeout seconds
--list-engines list engines
```
---
## Compromisos de diseño
1. **Absorción del agente primero, cantidad de enlaces segundo.**
2. **Gratis y local primero; de pago es elevación opcional.**
3. **Los fallos son observables**: empty / timeout / breaker van etiquetados—sin tragar en silencio.
4. **Motores guiados por config**; `config.yaml` es la única fuente de verdad.
5. **Instalación de fuente única**: enlaza entradas, no rsync de copias.
6. **Lo social no es una biblioteca de verdad**; sirve para expansión y sentimiento, no como única base factual.
---
## Buenos encajes
- Backend de búsqueda para agentes Claude Code / Grok Build / Codex / Kimi
- Q&A **multilingüe y multi-dominio**: CJK + EN + finanzas / cine / deportes / academia / código
- Scripts y pipelines que necesitan recuperación **reproducible y cacheable**
- Fact-check y comparación multi-fuente de datos públicos de finanzas / entidades
No es gran solución única para: ranking nativo de engagement de plataforma, o agregadores max-recall de larga vida (los motores locales embebidos reemplazan SearXNG externo como vía principal).
---
## Árbol (resumen)
```
argo/
├── README.md # Chinese (default)
├── README.en.md # English
├── README.ja.md # Japanese
├── README.ko.md # Korean
├── README.es.md # Spanish
├── SKILL.md
├── package.json # npx entry
├── bin/argo.js # Node MCP launcher
├── bin/argo # Python CLI
├── config.yaml # engines & domains (source of truth)
├── assets/readme/ # README visuals
├── backends/
├── scripts/ # search / research / mcp / install …
├── sub-skills/local-search/
├── tests/
└── docs/
```
---
## Historial de cambios
| Versión | Notas |
|---------|-------|
| **v2.6.0** | **Búsqueda multilingüe** (detect / engine params / cross-lang fallback); verticales film·sports·geo·org·media; recovery anti-contaminación; familias de capacidad + regresión matrix; ~120+ fuentes. Ver [notas de release](docs/RELEASE_NOTES_v2.6.0.md) |
| **v2.5.1** | Fuentes de respuesta finanzas/macro/química más densas; tiers de motor + presupuesto combo; [notas v2.5.1](docs/RELEASE_NOTES_v2.5.1.md) |
| **v2.5.0** | Script de instalación + npx; rewrite desacoplado del routing; caché hot-path; MCP compacto |
| **v2.4.0** | Fallback de ruta de baja puntuación + filtros de mal-enrutado social; caché depth / soft hits; breakers y caché negativa; `engine_outcomes` |
| **v2.2–v2.3** | Evidencia en dos etapas, tabla de fuentes chinas, content_signals, stack fetch, más motores |
| **v2.1** | Capa de motores sociales (UGC multi-plataforma) |
| **v1.x** | Nombre unificado Argo; enrutamiento multi-motor + caché de dos capas |
---
## Contribuir
Issues y PRs bienvenidos. Si cambias lógica de routing o evidencia, añade tests:
```bash
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 # optional, online
```
Antes del commit: sin claves API reales, rutas absolutas de máquina ni cookies de cuenta. Las rutas locales de Skill van en `installs.local.yaml` (gitignored).
## License
MIT License © 2026 [taxueseek](https://github.com/taxueseek)
---
> Una buena búsqueda no es ver más: es concluir con confianza, y saber cuándo aún no debes.