Annolux Search

---

💡 为什么选择 Annolux？

目前面向 AI Agent 的网页搜索 API 存在三个致命缺陷：

1. 垃圾进，垃圾出：商业搜索引擎收录了数百万个 SEO 内容农场、抓取式垃圾信息和自动生成的噪声，污染大模型的上下文窗口。
2. 缺少时间来源信息：搜索 API 没有提供确切的快照时间戳（fetched_at），导致大模型会对当前状态产生幻觉。
3. 掠夺式计费：请求失败、输出为空或因速率限制而重试，仍需支付全额费用。

Annolux 通过以 Agent 为先的精选方案解决这些问题：

• 🛡️ 精选双语技术索引：高信噪比的中英文语料（Rust、Go、Python、AI/ML、官方文档、RFC、GitHub、arXiv）。
• 🕒 明确的 fetched_at 时间戳：每条排名结果都会显示其入库的确切时间（精确到秒），支持可靠引用和时间推理。
• 🎯 可预测的账本计费：每次成功的 2xx 响应恰好扣除 1 个额度。错误、超时（504）、速率限制（429）和错误请求均不扣额度。
• 🧩 原生支持 Model Context Protocol（MCP）：无需配置即可用于 Claude Code、Cursor、Windsurf、Cline、Zed 和 Claude Desktop。
• 🚀 每月赠送 1,000 个免费额度：在 annolux.com 使用 GitHub 或 Google 登录，30 秒即可开始查询。

---

🥊 对比：Annolux 与通用搜索 API

功能 / 指标	Annolux	Exa（Metaphor）	Tavily	Serper / Google
索引质量	精选技术与知识内容（EN/ZH）	覆盖全网的神经搜索	覆盖全网的聚合器	整个 Web（SEO 噪声较多）
中文（ZH）技术语料	原生双语全文搜索（FTS），一流支持	中等	较弱 / 翻译内容	混杂内容农场
明确的快照时间戳	✅ 每条结果均包含 fetched_at	❌ 不一致	❌ 未提供	❌ 仅有近似的摘要时间
计费保障	✅ 仅在 2xx 成功时扣 1 个额度	按请求计费	按请求计费	按请求计费
失败 / 超时查询	🆓 不扣额度	❌ 计费	❌ 计费	❌ 计费
MCP 工具接口	单个精简的 search_web（尽量减少令牌浪费）	多个臃肿工具	多步工具	需要自定义桥接
域名限制	✅ 精确的主机名过滤（domains）	✅ 支持	✅ 支持	仅支持有限的 site: 查询
免费入门套餐	每月 1,000 个额度	有限试用	每月 1,000 个	一次性 2,500 个

---

📦 快速安装

唯一的前置条件是 Node.js 18+。可从零配置沙盒开始使用，无需账户或 API 密钥：

npx -y annolux-mcp

如需使用完整的月度额度，请在 annolux.com 创建免费密钥，并通过进程环境传入：

ANNOLUX_API_KEY=ann_live_YOUR_API_KEY npx -y annolux-mcp

---

🔌 MCP 集成

Annolux 按照官方 Model Context Protocol（MCP） 规范实现了单个高效工具：search_web。

⚡ 一键安装（Cursor 和 Smithery）

• Cursor：点击 ，通过深层链接原生安装。
• Smithery CLI：

  npx -y @smithery/cli install annolux-mcp --client claude
  npx -y @smithery/cli install annolux-mcp --client cursor
  

• Glama 在线 Playground：在 Glama.ai 上立即测试查询，无需本地设置。

1. Claude Code

claude mcp add annolux -- npx -y annolux-mcp

此命令会以沙盒模式启动。若要使用账户密钥，请在 -- 前添加 -e ANNOLUX_API_KEY=ann_live_YOUR_API_KEY。

2. Cursor / Windsurf

添加到项目的 .cursor/mcp.json 或全局配置中：

{
  "mcpServers": {
    "annolux": {
      "command": "npx",
      "args": ["-y", "annolux-mcp"],
      "env": {
        "ANNOLUX_API_KEY": "ann_live_YOUR_API_KEY"
      }
    }
  }
}

3. Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "annolux": {
      "command": "npx",
      "args": ["-y", "annolux-mcp"],
      "env": {
        "ANNOLUX_API_URL": "https://api.annolux.com",
        "ANNOLUX_API_KEY": "ann_live_YOUR_API_KEY"
      }
    }
  }
}

---

🚀 HTTP API 快速入门

标准搜索端点

POST https://api.annolux.com/api/v1/search
Authorization: Bearer ann_live_YOUR_API_KEY
Content-Type: application/json

{
  "query": "tokio async runtime memory model",
  "domains": ["tokio.rs", "docs.rs", "github.com"],
  "deduplicate": true,
  "limit": 5,
  "timeout": 10,
  "ranking": "default"
}

Python

import os
import requests

response = requests.post(
    "https://api.annolux.com/api/v1/search",
    headers={"Authorization": f"Bearer {os.environ.get('ANNOLUX_API_KEY')}"},
    json={
        "query": "DeepSeek R1 architecture reinforcement learning",
        "limit": 5,
        "deduplicate": True
    },
    timeout=15
)

data = response.json()
for result in data.get("results", []):
    print(f"[{result['fetched_at']}] {result['title']} -> {result['url']}")

TypeScript / Node.js

const res = await fetch("https://api.annolux.com/api/v1/search", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.ANNOLUX_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    query: "vLLM PagedAttention implementation details",
    limit: 5,
    deduplicate: true
  })
});

const data = await res.json();
console.log(`Credits Remaining: ${res.headers.get("X-Annolux-Credits-Remaining")}`);
console.log(data.results);

cURL

curl -s -X POST https://api.annolux.com/api/v1/search \
  -H "Authorization: Bearer ann_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Go sync.Pool benchmark best practices",
    "limit": 3
  }' | jq .

---

🏛️ 架构与机制

┌─────────────────────────────────────────────────────────────┐
│                 AI Agent / RAG Application                  │
│       (Claude Code / Cursor / LangChain / Custom LLM)       │
└──────────────────────────────┬──────────────────────────────┘
                               │
               Stdio MCP / HTTPS REST Request
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│                  Annolux Gateway API Engine                 │
│  ┌─────────────────────────┐     ┌───────────────────────┐  │
│  │ 1. Account & Rate Limit │ ──► │ Reserve 1 Credit      │  │
│  │    (5 RPS, Burst 10)    │     │ in /data/accounts.db  │  │
│  └─────────────────────────┘     └───────────────────────┘  │
│                                              │              │
│                                              ▼              │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ 2. Bilingual FTS Ranker (/data/index.db)              │  │
│  │    • Curated English & Chinese Corpus                 │  │
│  │    • SimHash Content-Deduplication Engine             │  │
│  │    • Domain Filter & Exact Substring Match            │  │
│  └───────────────────────────────────────────────────────┘  │
│                                              │              │
│                                              ▼              │
│  ┌───────────────────────────────────────────────────────┐  │
│  │ 3. Atomic Response & Ledger Settlement                │  │
│  │    • 2xx Success ──► Commit 1 Credit & Attach Timing  │  │
│  │    • 4xx/5xx Err ──► Release Reservation (0 Cost)     │  │
│  └───────────────────────────────────────────────────────┘  │
└──────────────────────────────┬──────────────────────────────┘
                               │
          JSON with exact `fetched_at` & verified URL
                               │
                               ▼
                     [ Grounded LLM Response ]

---

📊 搜索质量与固定基准测试

Annolux 使用一组不可变的固定盲测集评估搜索检索性能，该测试集包含 40 个复杂的双语查询。排名权重绝不会根据测试集进行调整。

指标	首轮门槛基线	上线前验证门槛
Hit@1	72.5%	72.5%
Hit@3	82.5%	82.5%
Hit@10	85.0%	85.0%
MRR@10	0.78125	0.78125
P95 延迟	532 ms	356 ms
5xx 错误率	0.00%	0.00%

所有基准测试均在客户端以完全并发负载进行评估。

---

💳 透明定价

套餐	价格	额度	速率限制	计费规则
免费版	$0	每月 1,000 个	5 RPS / 突发 10	永久免费，无需信用卡
Pro	$29 / 月	每月 20,000 个	5 RPS / 突发 10	1 次成功 = 1 个额度，不结转
Scale	$99 / 月	每月 100,000 个	5 RPS / 突发 10	1 次成功 = 1 个额度，不结转

• 不收取超额费用。
• 错误、速率限制和超时均完全免费（不扣额度）。
• 每个账户最多可创建 3 个有效 API 密钥。

---

📁 示例与配方

查看 examples/ 目录，获取可用于生产环境的入门示例：

• 01-claude-code-literature-research：自动化技术综述 Agent，提供带时间戳的引用。
• 02-cursor-authority-domain-refactor：将搜索限制在官方文档域名（react.dev、go.dev），实现零幻觉重构。
• 03-production-rag-temporal-pipeline：生产级 RAG 混合搜索管道，支持回退检索。
• 04-n8n-ai-research-agent：可直接导入的 n8n AI Agent 工作流，使用社区节点（n8n-nodes-annolux）并提供时间引用。

---

🤝 社区与支持

• 在 GitHub Issues 提交错误报告或功能请求。
• 查看 SECURITY.md，了解如何私下报告漏洞。
• 公开的 OpenAPI 规范：annolux.com/openapi.json。

---

📄 许可证

Annolux 是根据 Apache License, Version 2.0 授权的开源软件。