Argus

Argus

面向 AI Agent 的检索平台。Argus 可在 14 个提供商之间路由搜索、恢复失效 URL、抓取重要网站内容、构建本地文档与研究资料包，并将所有内容持久化为可追溯的本地文件。

功能一览：

• 感知网络拓扑的采集 — Argus 能判断自己使用的是住宅 IP 还是数据中心 IP，并自动路由搜索和内容提取，以避免拦截并尽量减少网络跳转。
• 14 个提供商，一个 API — 优先使用免费服务进行路由，并自动跳过预算耗尽的提供商
• 零密钥快速开始 — pip install argus-search 即可立即使用 DuckDuckGo + Yahoo，无需注册账号
• 自托管 SearXNG = 70 多个搜索引擎 — 通过一个 Docker 容器使用 Google、Bing、Yahoo、Startpage、Ecosia、Qwant 等
• 12 步内容提取 — 通过质量门控返回完整页面文本，而不只是链接
• 约定明确的检索工作流 — 恢复失效文章、抓取网站中的重要页面，并构建本地文档与研究资料包
• 由 Argus 管理的语料库存储 — 运行时数据会写入可写的用户数据目录，而非仓库检出目录
• 多轮会话 — 传入 session_id，即可在多次搜索之间保留对话上下文
• 分数归因 — 可选择显示哪些提供商参与了每个融合 RRF 分数的计算
• 用量仪表板 — 在 /dashboard 查看提供商预算、近期查询量和机器级用量
• 4 种搜索模式 — 发现、研究、恢复、溯源
• 失效 URL 恢复 — 使用 Wayback Machine 和存档回退功能，通过 /recover-url 恢复内容
• 4 种集成方式 — HTTP API、CLI、MCP 服务、Python SDK

专为 AI Agent 构建者、RAG 流水线和运维团队打造，帮助他们无需拼接多个 API，即可获取可靠的搜索、内容抓取和本地证据。

状态：测试版。检索工作流和语料库模型面向生产环境设计，但仍在持续完善。

状态：请参阅公开的状态页面。获得授权的维护者 可通过私有的 argus-ops README 查看最新的带日期报告。

当前生产环境检查点 — 2026 年 9 月 7 日： 已启用身份验证的 HTTP API 和 MCP 适配器现已运行，抽样测试的免费搜索可通过 SearXNG、Yahoo 和 GitHub 正常工作。DuckDuckGo 服务不稳定，并会在采集策略拦截后以关闭方式失败。生产就绪状态为 ready=true, degraded；在记录非机密的凭证版本和账户范围绑定信息之前， 暂不接入付费提供商。浏览器能力和恢复元数据证据仍待完善。依赖任何提供商之前，请参阅 当前状态矩阵。

目录

• 快速开始
• 开发
• Argus 写入数据的位置
• 约定明确的工作流
• 提供商
• HTTP API
• 仪表板
• 集成
  • CLI
  • MCP
  • Python
• 内容提取
• 架构
• 配置
• 何时不应使用 Argus
• 常见问题

快速开始

模式 1：本地 CLI（零配置）

pip install argus-search && argus search -q "python web frameworks"

就这么简单。DuckDuckGo 负责搜索——无需账号、密钥或容器。现在就能在你的笔记本电脑上免费使用无限搜索。想要更多搜索提供商时，随时添加 API 密钥；不添加也可以。

argus extract -u "https://example.com/article"       # extract clean text from any URL
argus recover-article -u "https://example.com/dead-post"
argus capture-site -u "https://docs.example.com"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

任何安装了 Python 3.11+ 的机器都能运行——笔记本电脑、Mac Mini、Raspberry Pi、云 VM。无需托管任何服务。

用于 MCP（Claude Code、Codex、OpenCode、Cursor、VS Code）：

pipx install argus-search[mcp]
export ARGUS_MCP_STANDALONE=true  # explicit development-only local broker
argus mcp init --global --client all

这会为 Claude Code、Codex CLI、OpenCode 和 Cursor 写入原生配置。配置完成后，重启客户端。手动配置 stdio：

{"mcpServers": {"argus": {"command": "argus", "args": ["mcp", "serve"], "env": {"ARGUS_MCP_STANDALONE": "true"}}}}

或者从 MCP Registry 安装：

{
  "mcpServers": {
    "argus": {
      "registryType": "pypi",
      "identifier": "argus-search",
      "runtimeHint": "uvx",
      "env": {"ARGUS_MCP_STANDALONE": "true"}
    }
  }
}

独立开发无需服务器或密钥，但必须显式启用。 生产环境中的 MCP 始终委托给经过身份验证的 HTTP 权威服务。

请参阅 MCP 客户端设置，了解准确的配置文件、验证命令、远程 HTTP 设置和故障排除方法。

模式 2：全栈服务

你有一台运行 Pi-hole 的 Raspberry Pi？桌上有一台 Mac Mini？或者一台旧笔记本电脑？这些设备足以运行全栈——SearXNG（你自己的私有搜索引擎，默认禁用）以及本地 JS 渲染内容提取。

# Optional: tell Argus it has residential egress to optimize routing
export ARGUS_EGRESS_TYPE=residential
ARGUS_SEARXNG_ENABLED=true docker compose up -d    # SearXNG + Argus

SearXNG 占用 512MB 内存，为你提供私有的 Google 风格搜索引擎（默认禁用——设置 ARGUS_SEARXNG_ENABLED=true），没有人能对其进行速率限制、封锁或收费。它可以与 Pi-hole 一起运行在数百万人已经拥有的硬件上。

Argus 将数据写入何处

Argus 代码和 Argus 运行时数据是两回事。

• 代码存放在你安装或克隆 Argus 的位置。
• 运行时语料库数据存放在由 platformdirs 确定的可写用户数据目录中；也可以通过 ARGUS_DATA_ROOT 指定其他位置。

查看你机器上的确切路径：

argus paths

默认情况下，Argus 会写入：

• 官方文档缓存写入已解析的 docs/cache/ 目录
• 研究包写入 docs/research/ 目录
• 工作流运行状态写入 workflows/runs/ 目录
• 有版本管理的工作流快照写入 snapshots/ 目录

这意味着 Argus 不要求同级目录中存在 ../docs-cache 检出副本。如果你有较旧的 docs-cache 目录树，可以用以下命令导入一次：

argus corpus import-docs-cache -s /path/to/docs-cache

注重实效的工作流

这些工作流会构建本地文件，而不只是生成临时 JSON 响应。

找回失效文章

argus recover-article -u "https://example.com/old-post" -t "Example Post"

Argus 会搜索可供恢复的候选内容，提取最佳结果，在本地保存恢复的来源，并写入带引用的报告和清单。

捕获网站的重要内容

argus capture-site -u "https://docs.example.com"

Argus 会限制在当前域名内，使用站点地图辅助发现内容，并结合启发式链接评分，保存找到的重要页面，然后写入带有参考资料的详细摘要。

构建文档 + 研究包

argus build-research-pack -t "example sdk"
argus build-research-pack -t "example sdk" --official-url "https://docs.example.com"

Argus 会将官方文档抓取到本地文档缓存，从搜索结果中添加非官方的辅助来源，并写入包含可追溯文件的综合研究包。

开发

仓库开发固定使用 Python 3.12。软件包运行时最低要求为 Python 3.11，生产镜像运行 Python 3.12.3，Python 3.13 则用于兼容性 CI。必需的 CI 检查会覆盖这三个版本；贡献者应使用下方的 uv 工作流，以确保本地验证与规范 CI 环境一致，避免意外使用较旧的系统解释器。

uv sync --python 3.12 --extra dev --extra mcp
uv run pytest tests/ -v --tb=short

仓库包含 .python-version，其中指定了 3.12，这样 uv、pyenv 等工具默认就会选择正确的解释器。更多贡献指南请参阅 CONTRIBUTING.md。

提供商

¹ SearXNG 可聚合 Google、Bing、Yahoo、Startpage、Ecosia、Qwant、Wikipedia 等 60 多个来源，统一通过一个自托管端点提供服务。在任何拥有 512MB 可用内存的机器上运行 docker compose up -d 即可。

² WolframAlpha 返回的是计算结果（数学、单位换算、事实查询），而不是网页搜索结果。它仅在 grounding 和 research 模式下启用。对于无法计算的查询（常规网页搜索），它会返回空结果——不会报错，也不会影响健康状态。

具有 API 密钥的定期免费额度提供商每月可提供 7,000 多次免费查询（WolframAlpha 2k + Brave 2k + Tavily 1k + Exa 1k + Linkup 1k）；符合条件且账户已绑定银行卡时，若 Parallel 的月度额度可用，则最多可达 12,000 多次。DuckDuckGo、Yahoo 和 GitHub 没有月度上限。SearXNG 默认禁用（可在 .env 中启用）。路由优先级：Tier 0（免费：SearXNG*、DuckDuckGo、Yahoo、GitHub、WolframAlpha）→ Tier 1（每月定期额度：Brave、Tavily、Exa、Linkup、Parallel）→ Tier 3（一次性额度：Serper、You.com、Valyu、SearchAPI）。额度耗尽的提供商会自动跳过。

这些是软件包级别的提供商层级和公布的配额，并不代表其当前在生产环境中可用。对于已配置凭据的提供商，生产环境权威机制会在其注册指纹、账户范围、预算和经批准的测试证据齐备之前拒绝启用。仅有受保护的密钥值并不能证明当前密钥有效；实时分类请参阅 docs/STATUS.md。

HTTP API

所有端点均以 /api 为前缀。OpenAPI 文档位于 http://localhost:8000/docs。

本地环回调用无需身份验证即可使用 API。远程 HTTP 调用方必须通过 Authorization: Bearer ... 或 X-API-Key: ... 发送 ARGUS_API_KEY。/api/admin/* 下的特权路由需要 ARGUS_ADMIN_API_KEY（如果未配置单独的管理员密钥，则回退使用 ARGUS_API_KEY）。

# Search
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "mode": "discovery", "max_results": 5}'

# Search with score attribution
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "python web frameworks", "include_attribution": true}'

# Multi-turn search (conversational refinement)
curl -X POST http://localhost:8000/api/search \
  -H "Content-Type: application/json" \
  -d '{"query": "what about async?", "session_id": "my-session"}'

# Extract content from a working URL
curl -X POST http://localhost:8000/api/extract \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

# Recover a dead or moved URL
curl -X POST http://localhost:8000/api/recover-url \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/old-page", "title": "Example Article"}'

# Network-free process liveness (container health target)
curl http://localhost:8000/api/live

# Public minimal startup and cached readiness
curl http://localhost:8000/api/startup
curl http://localhost:8000/api/ready

# Authenticated operator status, health compatibility, and budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/budgets
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/status
curl -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/dead-letters
# After correcting the cause of a permanent rejection:
curl -X POST -H "Authorization: Bearer $ARGUS_ADMIN_API_KEY" \
  http://localhost:8000/api/admin/maya-outbox/DELIVERY_ID/recover

/api/health 仍是返回 200 的存活状态兼容端点。它有意不检查 PostgreSQL、提供商、Maya 或浏览器，以免依赖项中断导致容器反复重启。规范的拓扑结构和运维流程请参阅生产运维；端点语义、就绪状态分类、观测数据过期机制和安全遥测请参阅运维状态。

搜索模式

始终优先应用基于层级的路由。在每个层级内，模式决定提供方的顺序。

响应格式

{
  "query": "python web frameworks",
  "mode": "discovery",
  "results": [
    {
      "url": "https://fastapi.tiangolo.com",
      "title": "FastAPI",
      "snippet": "Modern Python web framework",
      "provider": "duckduckgo",
      "score": 0.0164,
      "score_attribution": {"duckduckgo": 0.0164},
      "egress": "unknown",
      "machine": null
    }
  ],
  "total_results": 1,
  "cached": false,
  "traces": [
    {"provider": "duckduckgo", "status": "success", "results_count": 5, "latency_ms": 312}
  ]
}

每个结果都包含 url、title、snippet、domain、provider 和 score。traces 数组会显示调用了哪些提供方及其结果。

当 include_attribution 为 true 时，每个结果还会包含 score_attribution：一个提供方到分数的映射，用于分解结果的 Reciprocal Rank Fusion 分数。RRF 采用加法，因此每个提供方的归因值 恰好是其自身的排名贡献，所有值之和等于 score。归因默认关闭， 并与不含归因的搜索分别缓存。

配额

{
  "budgets": {
    "brave": {"remaining": 1847, "monthly_usage": 153, "usage_count": 153, "exhausted": false},
    "duckduckgo": {"remaining": 0, "monthly_usage": 0, "usage_count": 42, "exhausted": false}
  },
  "token_balances": {"jina": 9833638}
}

每个提供方都会跟踪用量。层级 1（每月）使用 30 天滚动窗口；层级 3（一次性）使用永不重置的终身计数器。当某个提供方达到配额时，Argus 会跳过它并转到下一个提供方。免费提供方（DuckDuckGo、GitHub）没有限制。SearXNG 免费，但默认禁用。设置 ARGUS_*_MONTHLY_BUDGET_USD 可为每个提供方设置自定义限额。

仪表板

运行 HTTP 服务并打开 /dashboard：

argus serve
# http://127.0.0.1:8000/dashboard

仪表板会显示提供方预算消耗、超速和已耗尽的提供方、过去 30 天的查询量、按机器统计的用量，以及近期的提供方活动。预算卡片会自动刷新。

设置 ARGUS_ADMIN_API_KEY 可要求登录仪表板。如果未设置管理员密钥，任何能够访问该服务的人都可以打开仪表板，因此这种配置仅适用于可信的本地使用环境。

若要在反向代理后通过子路径部署，请将 ARGUS_ROOT_PATH 设置为 外部路径前缀：

ARGUS_ROOT_PATH=/argus argus serve

这样，当代理将 Argus 托管在类似 https://khamel.com/argus/ 的路径下时，仪表板重定向、链接和 HTMX 片段 URL 都能正常工作。

如需直接通过 HTTPS 公开访问，仓库提供了一个 Caddy 配置：

ARGUS_DOMAIN=argus.example.com [email protected] \
  docker compose --profile proxy up -d

对于已有的 Authentik/nginx 部署，请在代理层保留身份验证，并将 ARGUS_ROOT_PATH 设置为公开路径前缀。

集成

CLI

argus search -q "python web framework"              # zero-config, uses DuckDuckGo
argus search -q "python web framework" --mode research -n 20
argus search -q "python web framework" --free        # free providers only (no paid API calls)
argus search -q "python web framework" --attribution # show per-provider score attribution
argus search -q "fastapi" --session my-session       # multi-turn context
argus extract -u "https://example.com/article"       # extract clean text
argus extract -u "https://example.com/article" -d nytimes.com  # auth extraction
argus recover-url -u "https://dead.link" -t "Title"
argus doctor                                         # full setup diagnostics
argus health                                         # provider status
argus budgets                                        # budget + token balances
argus mcp check                                      # validate MCP setup
argus set-balance -s jina -b 9833638                 # track token balance
argus test-provider -p brave                         # smoke-test a provider
argus serve                                          # start API server
argus mcp serve                                      # start MCP server
argus mcp init                                       # add MCP config to project

所有命令都支持 --json，以生成结构化输出。

argus ledger reconcile-sessions \
  --source sqlite:///argus_budgets.db \
  --target "$ARGUS_DB_URL"
# Review source/imported/skipped/conflicting, then repeat with --apply.

MCP 是经过身份验证的 HTTP API 上的无状态执行适配器。它不会构建提供方或代理，也不持有浏览器、数据库、预算、会话、健康状态或发件箱状态。请为适配器进程配置：

export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN=replace-with-a-scoped-caller-token

已部署的生产端点同时支持经过验证的 MCP 2025-11-25 兼容性契约和 MCP 2026-07-28 无状态传输修订版。 较新的路径是单次调用，不需要初始化握手或 Mcp-Session-Id；持久化策略、预算、会话和证据仍由 HTTP 权限端负责。有关有源代码依据的边界和必要的零支出探测，请参阅 docs/research/2026-08-11-mcp-stateless-production-authority.md。

选项 A — 本地适配器（stdio）

在与 MCP 客户端相同的机器上安装适配器：

{
  "mcpServers": {
    "argus": {
      "command": "argus",
      "args": ["mcp", "serve"]
    }
  }
}

如果 argus 不在 PATH 中，请使用完整路径："/home/you/.local/bin/argus"。 适配器会从客户端进程继承 ARGUS_AUTHORITY_URL 和 ARGUS_AUTHORITY_TOKEN。若要改为运行本地代理，开发环境 必须显式设置 ARGUS_MCP_STANDALONE=true；生产环境会拒绝此设置。

可与 Claude Code、Codex CLI、OpenCode、Cursor 以及任何基于 stdio 的 MCP 客户端配合使用。使用 argus mcp init --global --client all 为当前机器写入原生客户端配置。

详细的客户端设置和验证命令见 docs/mcp-clients.md。

选项 B — 远程 MCP 适配器（通过 Tailscale 连接客户端）

在一台机器上运行 Argus，通过网络连接所有客户端。客户端无需本地安装。

在适配器主机上：

export ARGUS_API_KEY=replace-with-a-long-random-secret
export ARGUS_AUTHORITY_URL=http://argus-api:8000
export ARGUS_AUTHORITY_TOKEN="$ARGUS_API_KEY"
argus mcp serve --transport streamable-http --host YOUR_TAILSCALE_IP --port 8001

远程 MCP 凭据也必须是 HTTP 权限端上的有效作用域凭据，因为适配器会原样转发每个经过身份验证的 bearer token。 对于 stdio，ARGUS_AUTHORITY_TOKEN 是调用方凭据。

若要在 systemd 主机上让 HTTP API 和远程 MCP 服务在重启后继续运行：

cat >mcp.env <<'EOF'
ARGUS_AUTHORITY_URL=http://argus-api:8000
ARGUS_AUTHORITY_TOKEN=replace-with-scoped-caller-token
ARGUS_API_KEY=replace-with-the-same-scoped-caller-token
EOF
chmod 600 mcp.env
ARGUS_MCP_ENV_FILE="$PWD/mcp.env" scripts/install-systemd.sh
systemctl status argus argus-mcp --no-pager

安装程序会验证最小适配器环境，将其安装为仅 root 可访问的 /etc/argus/mcp.env，然后安装并启动两个单元。MCP 单元绝不会加载权限端的 .env、提供方保险库、数据库设置、 浏览器路径或可写数据卷。

在每个客户端上：

使用 Tailscale 时，<server> 是你机器的 Tailscale IP（例如 100.x.x.x）。一台服务，每台接入网状网络的机器都能获得搜索能力。

一条命令完成配置：

# Load secrets, then push config to any machine:
eval $(secrets decrypt argus | grep -E 'ARGUS_REMOTE_URL|ARGUS_API_KEY' | sed 's/^/export /')

curl -s https://raw.githubusercontent.com/Khamel83/argus/main/scripts/provision-mcp-client.sh | bash -s local              # this machine; uses local stdio if argus is installed
curl -s https://raw.githubusercontent.com/Khamel83/argus/main/scripts/provision-mcp-client.sh | bash -s [email protected]    # remote machine

该脚本会在目标机器上写入 Claude/Cursor、Codex 和 OpenCode 配置。 本地 stdio 无需 MCP 监听器密钥，但适配器仍需要其作用域凭据 ARGUS_AUTHORITY_TOKEN。远程 MCP 模式需要 ARGUS_REMOTE_URL 和 ARGUS_API_KEY。需要 Python 3。

argus mcp init 也会自动生成配置：

argus mcp init --global              # local stdio adapter for Claude Code + OpenCode + Cursor
argus mcp init --client codex        # local stdio for Codex (writes ~/.codex/config.toml)
argus mcp init --client opencode     # local stdio for OpenCode
ARGUS_REMOTE_URL=http://argus.local:8271 ARGUS_API_KEY=... argus mcp init --global --client all
argus mcp init --client gemini       # prints gemini mcp add command
argus mcp init --global --client all # everything above

发布状态

推送到 main 不会发布到 PyPI。创建发布版本或手动触发 GitHub 发布工作流时，才会发布软件包和 MCP Registry。有关版本同步、发布前检查和发布验证，请参阅 docs/releasing.md。

传输方式：stdio（默认本地适配器）、sse（旧版远程方式）和 streamable-http（现代远程方式，配置中为 "type":"http"）。远程 MCP 传输方式需要 ARGUS_API_KEY；所有传输方式都会将执行委托给 ARGUS_AUTHORITY_URL。

可用工具：

• 基于 HTTP 的 stdio 和远程 MCP：search_web、extract_content、 recover_url、expand_links、search_health、search_budgets、 recover_dead_article、capture_site 和 build_research_pack
• 显式的独立开发模式还会提供仅限本地的 test_provider、cookie_health、valyu_answer、路径／文件工具和 资源。这些工具有意不包含在生产适配器中。

search_web 支持 free_only=true，仅筛选免费（tier-0）提供方的结果；还支持 include_attribution=true，在 Markdown 响应中包含各提供方的分数归因信息。

通过 MCP 与 HTTP 使用 Argus

两种传输方式，一条规则：Agent 使用 MCP，其他一切使用 HTTP。

• MCP（argus mcp serve）——面向原生支持 MCP 的 AI 框架的无状态认证适配器。核心工具会将请求委托给 HTTP 权威服务： search_web、extract_content、recover_url、expand_links 和工作流 启动操作。重启 MCP 不会分叉计费、会话、健康状态或发件箱状态。
• HTTP（POST /api/search、POST /api/extract、 POST /api/workflows/...）——适用于脚本、cron 作业和服务 集成（包括 Maya）。在 Authorization 中发送限定范围的调用方凭证；请求正文中的 "caller" 值仅为诊断标签，无法覆盖经过认证的身份。

更广泛的服务群组（Maya / Hermes / Argus）之间的传输和角色契约，以 Maya 的架构文档为准。

Python

直接导入 broker 和提取模块，是独立开发时的便利方式。 生产环境中的 Python 调用方应使用经过认证的 HTTP API，以确保所有执行和 持久化计费都由同一个权威服务处理。

from argus.broker.router import create_broker
from argus.models import SearchQuery, SearchMode
from argus.extraction import extract_url

broker = create_broker()

response = await broker.search(
    SearchQuery(query="python web frameworks", mode=SearchMode.DISCOVERY, max_results=10),
    compute_attribution=True,
)
for r in response.results:
    print(f"{r.title}: {r.url} (score: {r.score:.3f})")
    print(r.score_attribution)

content = await extract_url(response.results[0].url)
print(content.title)
print(content.text)

内容提取

Argus 会尝试多达 12 种方法，从任意 URL 提取内容：先尝试用于付费墙的身份验证提取，然后依次尝试本地提取器（trafilatura、Crawl4AI、Obscura、Playwright、住宅 IP），最后尝试外部 API（Jina、Valyu Contents、Firecrawl、You.com、Wayback、archive.is）。每次尝试都会检查内容质量，确认内容是否完整且没有垃圾输出。完整的提取器对比请参阅 docs/providers.md。

完整性评估会在每次成功提取后自动运行。Argus 会对五种信号进行评分——尾部省略号、信息流截断标记（“Read more”、WordPress RSS 页脚）、句中结束、最后一段突然中断，以及可疑的整数词数——并在文本旁返回 is_complete、completeness_confidence 和 truncation_type。当置信度 ≥ 85% 时，Argus 会继续尝试下一个提取器，而不是返回部分结果；也就是说，如果 trafilatura 抓取的内容以“...”结尾，Argus 会自动继续尝试 Playwright、Jina、Wayback 等提取器。已有文本的调用方（例如 RSS 信息流项目）可以使用 POST /api/assess-content 检查内容完整性，而无需触发提取。

Obscura（可选）是一款轻量级 Rust 无头浏览器（约 70MB 二进制文件、30MB 内存），内置隐身模式——它会将 navigator.webdriver 设为 undefined，为每个会话随机生成 canvas/GPU/音频指纹，并拦截 3,520 个跟踪器域名。它可以直接应对 JS 密集型和反爬网站对机器人的检测，这些网站会屏蔽标准 Playwright/Chrome。无需 API 密钥，也没有速率限制——完全在本地运行。

有两种使用方式：

安装二进制文件：github.com/h4ckf0r0day/obscura/releases

提取可获取有效 URL 的完整文本，并告知你文本是否完整。恢复 URL 则会在 URL 失效、存在付费墙或内容发生彻底变化时查找替代项。

架构

Caller (CLI/HTTP/MCP/Python) → SearchBroker → tier-sorted providers → RRF ranking → response
                                     ↕ SessionStore (optional)
                            Extractor (on demand) → 12-step fallback chain with quality gates

只需一个适配器文件，即可添加新的提供方或提取器。有关接口，请参阅 CONTRIBUTING.md。

查询的工作方式

query arrives → cache? → build provider queue → execute sequentially → RRF fuse → dedup → respond

1. 检查缓存。 SearchCache 会对规范化后的查询、模式以及是否请求了归属信息进行哈希（SHA256）。命中时立即返回，TTL 为 168 小时（7 天）。

2. 提供方队列。 resolve_routing() 会获取特定模式的偏好列表，并按层级稳定排序：层级 0（免费）优先，其次是层级 1（月付），最后是层级 3（一次性）。发现模式示例：

   searxng → duckduckgo → yahoo → github → brave → exa → tavily → linkup → parallel → serper → you → valyu
   

3. 带门控的顺序执行。 系统会按顺序检查每个提供方。发起 API 调用前必须通过以下四道门控：

   • 配置 — 提供方是否已启用并完成配置（是否存在 API 密钥）？
   • 健康状态 — 是否已连续失败 5 次或以上（会触发 60 分钟冷却期）？
   • 预算 — 对于层级 1 及以上：预算是否已耗尽？对于层级 1（月付），节奏检查会判断 7 天使用速率是否会在一周内耗尽剩余预算——未使用的日额度会累积为余量。对于层级 3（一次性），通过终身计数器控制访问——唯一的检查是额度是否已耗尽。
   • 执行 — 实际的 HTTP 调用。成功会重置失败计数；失败则会增加计数。

4. RRF 融合。 系统使用倒数排名融合（Reciprocal Rank Fusion，k=60）合并所有已查询提供方的结果。每项结果的得分为所有返回该结果的提供方的 1/(k + rank) 之和。在多个提供方中出现的结果排名更高。

5. 去重和截断。 系统会规范化 URL（去除 www.、utm_* 等跟踪参数以及末尾斜杠），并删除重复项。合并后的列表会截断至 max_results（默认值为 10）。

6. 缓存并持久化。 权威服务会将最终响应写入内存缓存和已配置的 SQL 仓库（生产环境使用 PostgreSQL，独立开发时使用 SQLite）。搜索结果和提取内容会包含溯源元数据（egress、machine、source_type），供下游审计使用。现有数据库会在启动时通过增量方式升级。

配置

所有配置均通过环境变量设置。完整列表请参见 .env.example。有限 API 密钥的提供方需选择启用：同时设置 API 密钥和 ARGUS_<PROVIDER>_ENABLED=true。缺少密钥时会优雅降级——跳过相应提供方，而不会报错。

从代码仓库运行时，Argus 现在会自动加载 .env 和 .env.local（不会覆盖已导出的环境变量）。设置 ARGUS_AUTOLOAD_DOTENV=false 可禁用此行为。

何时不应使用 Argus

当你需要将搜索、采集、来源追溯和本地制品整合在一起时，Argus 最适合。

以下情况请勿使用：

• 你只需要一个搜索 API，不需要回退或预算控制
• 你只需要一次性抓取页面，不需要持久化语料库或报告输出
• 你需要面向最终用户的搜索界面，而不是后端检索基础设施
• 你需要完全确定性的摘要，不涉及启发式或 LLM 辅助步骤

常见问题

这与直接调用 Tavily/Serper 有何不同？ Argus 会替你调用它们，以及其他 13 个提供商。你只需获取一组经过排序和去重的结果，无需管理多个 API 密钥并拼接结果。系统会优先尝试免费提供商，因此只有在需要时才会消耗额度。

我可以只运行一个提供商吗？ 可以。只设置你想使用的提供商的 API 密钥即可。其他提供商会自动跳过，不作提示。要实现零配置，只需安装并开始使用——DuckDuckGo + Yahoo 无需密钥即可处理搜索。

我需要 Docker 吗？ 不需要。在任何安装了 Python 3.11+ 的机器上，执行 pip install argus-search 即可立即使用。只有使用 SearXNG（在 .env 中设置 ARGUS_SEARXNG_ENABLED=true）或 Crawl4AI（本地 JS 渲染）时才需要 Docker。

贡献者应使用哪个 Python 版本？ 请使用 Python 3.12 进行仓库开发和验证：执行 uv sync --python 3.12 --extra dev --extra mcp，然后执行 uv run pytest tests/ -v --tb=short。已发布的软件包仍支持 Python 3.11+。

在网络上部署 Argus 的最安全方式是什么？ 使用 Tailscale 或其他私有网络，明确绑定到受信任的接口，设置 ARGUS_API_KEY，并将 /api/admin/* 限定为 ARGUS_ADMIN_API_KEY 使用。只有在反向代理后面，才应将直接暴露到互联网视为高级用法。

许可证

MIT——版本历史请参阅 CHANGELOG.md。