中文 ·
English ·
日本語 ·
한국어 ·
Español
소개 ·
증명 ·
메커니즘 ·
빠른 시작 ·
기능 ·
설정 ·
업데이트
---
## 무엇인가
**Argo는 AI 에이전트를 위한 다국어 검색 인프라입니다.**
실제 검색은 결코 「한 언어 + 검색창 하나」가 아닙니다. A주 시세를 묻는 사람, World Cup을 묻는 사람, 일본어로 애니를 찾는 사람, IMDb에서 감독 정보를 원하는 사람이 있습니다. Argo의 출발점은 단순합니다—**도메인·언어·의도에 따라 길을 고르고**, 문제를 알맞은 소스로 보내지 웹 제목만 훑지 않습니다. 온라인 검색과 로컬 파일 검색을 함께 쓸 수 있습니다.
> 산출물은 「링크 목록」이 아니라 **증거 후보 + 신뢰도 분해**입니다. 길이 맞아야 증거가 설 수 있습니다.
### 「검색 API를 한 겹 더 감싼 것」과의 차이
| 흔한 방식 | Argo |
|---------|------|
| 엔진 하나·키 하나에 고정 | 다중 엔진 자동 라우팅, 무료 우선·예산 설정 가능 |
| 모든 질문을 일반 웹 검색 | **수직 소스 우선**: 시세·영화·스포츠·매크로·화학 등 답형 결과 |
| 중·영에만 최적화 | **언어 감지 + 엔진 언어 파라미터 + 교차 언어 폴백** |
| 검색 후 스니펫 요약만 | 선택 문턱 × 증거 밀도 × 시의성 × 다중 소스 합의 |
| 엔진 하나가 죽으면 전체 중단 | 서킷 브레이커, 네거티브 캐시, 단계적 복구(수직 소스 오염 방지) |
| 매번 네트워크 재호출 | 이중 캐시(메모리 + SQLite), 핫 쿼리 약 10ms급 |
| 일상·연구에 같은 느린 경로 | **일상은 엔진 적게, 심층 연구는 넓게** |
| 긴 JSON이 에이전트 컨텍스트 소모 | MCP 응답 압축, 스니펫 제어 가능 |
---
## 질문 형태에 맞는 라우팅
| 이렇게 물으면 | 대개 일어나는 일 |
|---------|----------------------|
| 贵州茅台股价 | A주 시세 도메인, 스냅샷 소스 우선, 충분하면 early-stop |
| AAPL / US pre-market | 미국 주식 도메인, A주와 분리 |
| 肖申克的救赎 主演 / Inception director | 영화 도메인 → IMDb 등 |
| 梅西 俱乐部 / 库里 球队 | 스포츠 도메인 → TheSportsDB 등 |
| 埃菲尔铁塔在哪 / where is Eiffel Tower | 지리 엔티티 → OpenStreetMap 등 |
| NASA founding year / 国务院职能 | 조직 엔티티 → Wikidata 등 |
| 周杰伦 专辑 / Taylor Swift album | 미디어 도메인 → iTunes 등 |
| アニメ おすすめ / 한국 영화 추천 | JA/KO 감지 → 언어 친화 소스, 중국어 전용 사이트 회피 |
| US CPI, China GDP | 매크로 도메인, 국가 분리 |
| 阿司匹林 分子式 | 화학 → PubChem 계열 답 |
| TSMC valuation debate (deep research) | 하위 질문 + 병렬 소스, 수직 소스 가중 |
---
## 동작 방식
```
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)
```
### 증거 점수 (요약)
```
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
```
결과에 `selection`, `absorption`, `credibility_fast`, `evidence_flags` 등이 포함되어 에이전트가 바로 정렬할 수 있습니다.
### 에이전트 규율 (권장)
1. **고위험 질문**(포지션, 안전, 「이게 사실인가?」): 검색 → 빠른 점수 확인 → 상위 결과 `fetch` → 그다음 결론
2. **숫자**: 口径(정의·범위)을 밝히고, 소스가 충돌하면 나열—억지로 합치지 않기
3. **SERP / 리다이렉트 페이지**: 1차 출처로 취급하지 않기
4. **소셜 포스트**: 감성과 서사, 최종 사실 근거가 아님
5. **팩트체크**: 층위별 소수 쿼리 선호(출처 / 비교 / 대상)
---
## 빠른 시작
경로를 고르면 됩니다. 최신 빌드는 **npm 레지스트리 패키지가 필요 없습니다**(v2.5.1부터 **GitHub**가 설치 진원; 현재 권장 **v2.6.0**).
**제로 설정으로 동작**: API 키 없이도 무료 엔진 + 로컬 `local_*` 엔진이 돌고, 키 없는 엔진은 스킵됩니다(키가 있으면 보통 더 좋습니다).
### 옵션 1: 설치 스크립트 (장기 로컬 사용에 적합)
```bash
curl -fsSL https://raw.githubusercontent.com/taxueseek/argo/main/scripts/install.sh | bash
```
홈 경로 + 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"
```
확인:
```bash
python3 ~/.local/share/argo/scripts/search.py "贵州茅台股价" --json
python3 ~/.local/share/argo/scripts/search.py --list-engines
```
### 옵션 2: GitHub MCP (에이전트에 빠르게 붙이기)
**Node.js 18+** 와 **Python 3.10+** 필요. 한 번:
```bash
pip3 install pyyaml
```
```bash
npx -y github:taxueseek/argo
```
클라이언트 설정 (Claude Code / Cursor / Kimi 등):
```json
{
"mcpServers": {
"argo": {
"command": "npx",
"args": ["-y", "github:taxueseek/argo"]
}
}
}
```
더 안정적·Node 불필요: 옵션 1로 설치 후 로컬 Python 지정:
```json
{
"mcpServers": {
"argo": {
"command": "python3",
"args": ["/path/to/argo/scripts/mcp_server.py"]
}
}
}
```
비표준 Python 경로: `export ARGO_PYTHON=/path/to/python3` (npx 진입점만 읽음).
### 옵션 3: 릴리스 tarball
[Releases](https://github.com/taxueseek/argo/releases)에서 **`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
```
### 옵션 4: git clone (개발 / 소스 패치)
```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
```
### 옵션 5: Skill 디렉터리 (심볼릭 링크, 단일 진원)
```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
```
### 옵션 6: 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"
```
---
## 플랫폼
| 플랫폼 | 연동 | 비고 |
|----------|-------------|-------|
| **Claude Code** | MCP / Skill 링크 | `npx` 또는 `mcp_server.py`; `link_source.py` 가능 |
| **Kimi / Grok Build** | MCP Server | 동일 |
| **Cursor / Cline / Continue** | MCP | MCP 지원 IDE 플러그인 |
| **CLI** | `search.py` / `bin/argo` | 스크립트, cron, 수동 디버그 |
| **Python 프로젝트** | `from search import super_search` | 라이브러리 호출 |
### 설치 후 점검
```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
```
---
## 기능
| 기능 | 하는 일 | 진입점 |
|------------|--------------|-------|
| 통합 검색 | route → recall → fuse → skim score | `search.py` / `argo_search` |
| 로컬 파일 검색 | 디스크 코드/노트/메모리 (오프라인) | `argo_local_search` |
| 심층 연구 | 하위 질문, 다중 소스, 갭 힌트 | `research.py` / `argo_research` |
| 신뢰도 | 권위 / 밀도 / 시의성 / 교차 검증 | `evidence.py` / `argo_evidence` |
| 의도 명확화 | 다의어, 브랜드 충돌, 전략 힌트 | `clarify.py` / `argo_clarify` |
| 페이지 가져오기 | HTTP 우선, 필요 시 브라우저 폴백 | `argo_fetch` (`mode=extract` 구조 추출) |
| 스크린샷 / PDF | 페이지 캡처, 구조화 PDF 추출 | `argo_screenshot` / `argo_pdf` |
| 사이트 크롤 | 목록 페이지 배치 크롤 | `argo_crawl` |
| 소셜 / 감성 | Weibo / Xiaohongshu / Bilibili / Reddit / X … | `argo_social_search` |
### 예산 모드
| 모드 | 적합한 경우 | 동작 |
|------|----------|----------|
| `fast` | 단순 Q, 속도 필요 | 무료 엔진 우선, 유료 re-rank 스킵 |
| `auto` | 일상 기본 | 비용 인식 품질/지출 트레이드오프 |
| `deep` | 연구, 조사 | 품질 우선, 엔진 더 허용 |
| `budget` | 할당량 타이트 | 쿼터 제어, 소진 시 저하 |
### 대략적인 능력 세트 (v2.6.0)
- **약 120+ 소스, 60+ 도메인**: 일반 웹 + 금융 / 매크로 / 영화 / 스포츠 / 지리 / 조직 / 미디어 / 화학 / 학술 / 코드 (진원: `config.yaml`)
- **MCP 도구 10개**: search, research, evidence, clarify, fetch, screenshot, PDF, social, local files, crawl
- **다국어 검색**: 중국어, 영어, 일본어, 한국어, 키릴, 태국어, 아랍어, 히브리어, 그리스어, 데바나가리, …; 라우팅과 엔진 파라미터가 언어를 따름; 비중국어 쿼리는 중국어 전용 소스 회피 (Zhihu / Sogou WeChat / A주 스냅샷 등)
- **수직 복구 게이트**: 빈 결과 복구 시 영화·스포츠에 pypi / npm / 속보 등이 「새지」 않음
- **일상은 빠르게, 연구는 넓게**: `engine_policy` 티어—일상 콤보는 타이트, deep / research는 롱테일 개방
---
## 엔진과 라우팅
설정에는 현재 약 **120+** 소스와 **60+** 도메인이 있습니다 (`config.yaml`, `--list-engines` 참고).
### 직접·수직 (발췌)
| 엔진 | 시나리오 | 비용 성향 |
|--------|----------|-----------|
| anysearch / duckduckgo | 일반 / 기술 | free |
| sina_quote / tencent_quote / eastmoney | A주 시세 / 자금 흐름 | free |
| finviz / seeking_alpha | 미국·해외 금융 | depends |
| imdb / itunes / thesportsdb | 영화 / 음악 / 스포츠 | mostly free |
| local_openstreetmap / wikidata / wikipedia | 지리 / 조직 / 백과 | free |
| arxiv / semantic_scholar / openalex | 학술 | mostly free |
| pubchem / gbif / rfc_editor | 화학 / 종 / 표준 | free |
| github / stackoverflow / pypi / npm | 코드·패키지 | depends |
| byted / bocha / metaso / octen | 중국 웹 / AI 검색 | API / low cost |
| zhihu / wechat_sogou | 중국 여론 / WeChat | API / free |
| tavily / felo / exa | 국제 / 시맨틱 | paid or quota |
| twitter / reddit / xiaohongshu / bilibili / weibo | 소셜 UGC | free (some need login) |
### 로컬 제로 비용 레이어 (`local_*`)
별도 SearXNG 서비스 불필요. 메인 경로는 프로세스 내 HTML / RSS / JSON 파싱 (`local_bing`, `local_sogou`, `local_google`, `local_arxiv`, …). **다국어 쿼리**에서는 라우팅이 엔진 언어 파라미터를 재작성(예: Bing `setlang`)하고 RRF로 융합합니다.
---
## 예시
### 금융
```bash
python3 scripts/search.py "贵州茅台股价" --explain
# typical: stock_query → quote snapshot sources
```
### 학술
```bash
python3 scripts/search.py "transformer attention mechanism paper" --json
# domain often academic; combo includes arxiv etc.
```
### 연구와 검증
```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
```
### MCP 도구 (10)
| 도구 | 용도 |
|------|---------|
| `argo_search` | 통합 검색 |
| `argo_local_search` | 로컬 파일 (오프라인) |
| `argo_research` | 심층 연구 (소셜 감성 모드 포함) |
| `argo_evidence` | 신뢰도 점수 |
| `argo_clarify` | 의도 명확화 |
| `argo_fetch` | 스마트 fetch (`mode=extract` 구조 추출) |
| `argo_crawl` | 사이트 크롤 |
| `argo_screenshot` | 페이지 스크린샷 |
| `argo_pdf` | PDF 추출 |
| `argo_social_search` | 멀티 플랫폼 소셜 (`mode=sentiment`) |
---
## 설치와 설정
### 요구 사항
| 항목 | 요구 |
|------|-------------|
| Python | 3.10+ (CLI + MCP 코어) |
| 의존성 | `pip install pyyaml` (필수 의존성 하나) |
| Node.js | **`npx` 진입에만** 필요, 18+ |
| SearXNG | 불필요 (내장 로컬 엔진) |
### API 키 (모두 선택)
키가 없으면 해당 엔진 스킵, 무료 엔진이 버팀. **환경 변수 사용**—실제 키를 커밋하거나 이슈에 붙이지 마세요.
```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`에는 `{ENV_NAME}` 플레이스홀더만—git에 평문 시크릿 없음.
### 캐시
기본 SQLite 경로는 `config.yaml`의 `cache.db_path` (보통 `~/.cache/unified-search/cache.db`).
| 유형 | 대략 TTL |
|------|-------------|
| 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
**API 키 없이도 되나요?**
네. 많은 로컬 무료 엔진과 무료 API; 키 없는 경로가 자동입니다.
**설치 스크립트 vs npx?**
스크립트: 고정 로컬 설치, 설정, Skill 링크. npx: MCP를 빠르게 붙임. 같은 Python 코어.
**엔진 확인은?**
`python3 scripts/search.py --list-engines`, 또는 `--explain` 추가.
**저장소에 코드 사본이 여러 개?**
아니요. `link_source.py`로 단일 소스 + 심볼릭 링크를 권장, rsync 복제 지양.
---
## 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
```
---
## 설계 트레이드오프
1. **에이전트 흡수 우선, 링크 개수 차선.**
2. **무료·로컬 우선, 유료는 선택적 향상.**
3. **실패는 관측 가능**: empty / timeout / breaker에 라벨—조용히 삼키지 않음.
4. **설정 주도 엔진**; `config.yaml`이 단일 진원.
5. **단일 소스 설치**: 링크 엔트리, rsync 복제 금지.
6. **소셜은 진리 라이브러리가 아님**; 확장·감성에는 좋으나 유일한 사실 근거는 아님.
---
## 잘 맞는 경우
- Claude Code / Grok Build / Codex / Kimi 에이전트의 검색 백엔드
- **다국어·다도메인** Q&A: CJK + EN + 금융 / 영화 / 스포츠 / 학술 / 코드
- **재현 가능·캐시 가능** 검색이 필요한 스크립트와 파이프라인
- 공개 금융 / 엔티티 데이터의 팩트체크와 다중 소스 비교
단독 솔루션으로 덜 적합한 경우: 플랫폼 네이티브 인게이지먼트 랭킹, 또는 장기 max-recall 애그리게이터(내장 로컬 엔진이 외부 SearXNG 메인 경로를 대체).
---
## 트리 (요약)
```
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/
```
---
## 변경 이력
| 버전 | 비고 |
|---------|-------|
| **v2.6.0** | **다국어 검색** (detect / engine params / cross-lang fallback); film·sports·geo·org·media 수직; recovery 오염 방지; 능력 패밀리 + 매트릭스 회귀; ~120+ 소스. [릴리스 노트](docs/RELEASE_NOTES_v2.6.0.md) |
| **v2.5.1** | 금융/매크로/화학 답형 소스 강화; 엔진 티어 + combo 예산; [v2.5.1 notes](docs/RELEASE_NOTES_v2.5.1.md) |
| **v2.5.0** | 설치 스크립트 + npx; rewrite와 라우팅 분리; hot-path 캐시; compact MCP |
| **v2.4.0** | 저점수 라우트 폴백 + 소셜 오라우트 필터; 캐시 depth / soft hits; breakers & negative cache; `engine_outcomes` |
| **v2.2–v2.3** | 2단계 증거, 중국 소스 표, content_signals, fetch 스택, 엔진 확장 |
| **v2.1** | 소셜 엔진 레이어 (멀티 플랫폼 UGC) |
| **v1.x** | 통합 이름 Argo; 다중 엔진 라우팅 + 이중 캐시 |
---
## 기여
Issue와 PR 환영합니다. 라우팅이나 증거 로직을 바꿀 때 테스트를 추가해 주세요:
```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
```
커밋 전: 실제 API 키, 본기 절대 경로, 계정 쿠키 없음. 로컬 Skill 경로는 `installs.local.yaml`(gitignored)에.
## License
MIT License © 2026 [taxueseek](https://github.com/taxueseek)
---
> 좋은 검색은 더 많이 보는 것이 아니라, 자신 있게 결론 내리고, 아직 결론 내리면 안 될 때를 아는 것입니다.