内容
<h1 align="center">🛰️ AgentSpan</h1>
<p align="center"><strong>AI 智能体的网络访问网关 — 多平台、多租户、专为速度设计。</strong></p>
<p align="center">
<a href="https://github.com/oxbshw/Agent-Span/actions/workflows/ci.yml"><img src="https://github.com/oxbshw/Agent-Span/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<img src="https://img.shields.io/badge/channels-52-4f8cff?style=flat-square" alt="channels">
<img src="https://img.shields.io/badge/MCP%20tools-92-9b59b6?style=flat-square" alt="mcp tools">
<img src="https://img.shields.io/badge/SDKs-9-orange?style=flat-square" alt="sdks">
<img src="https://img.shields.io/badge/license-MIT-blue?style=flat-square" alt="license">
<img src="https://img.shields.io/badge/rust-async%20(Tokio)-orange?style=flat-square&logo=rust" alt="rust">
</p>
AgentSpan 为 AI 智能体提供持久、可扩展、**缓存**的访问权限，支持 **52 个互联网平台**，通过一个 REST API、SSE 事件流、原生 **MCP 服务器（92 个工具）**、**9 种语言 SDK**、命令行界面和 React 控制台 — 所有这些都基于异步 Rust 核心。
这些通道还具有**自我修复**功能 — 后台监视器自动切换失败的后端、重新安装损坏的命令行工具，并在持续中断时发出警报 — 网关还**从其自身的流量中学习**，建议缓存 TTL 调整、更快的后端和值得添加的平台。
> **语言：** [English](README.md) · [中文](docs/README_zh.md) · [日本語](docs/README_ja.md) · [한국어](docs/README_ko.md)
## 为什么选择 AgentSpan？
[Agent Reach](https://github.com/Panniantong/Agent-Reach) 证明了“能力层”模型（安装 → 诊断 → 路由）在智能体网络访问中的可行性。AgentSpan 基于该模型，打造了一个真正的**网关** — 它直接负责读取内容，背后是一个 API。
| 能力 | Agent Reach | AgentSpan |
|---|:---:|:---:|
| 架构 | Python 安装程序（智能体调用工具） | **异步 Rust 网关** |
| 通道 | 13 | **52** |
| 缓存 | ❌ | ✅ L1/L2/L3 |
| REST API | ❌（仅命令行界面） | ✅ + SSE + OpenAPI |
| MCP 工具 | 1 | **92** |
| SDKs | 0 | **9**（Python、JavaScript/TypeScript、Rust、Go、Ruby、Java、PHP、C#、Swift） |
| 多租户 / RBAC / 审计 | ❌ | ✅ |
| Web 控制台 | ❌ | ✅ React |
| Docker | ❌ | ✅ |
| Cookie 认证 · 转录 · 安装程序 · SKILL.md | ✅ | ✅ |
### AgentSpan 不是什么
- 不是浏览器自动化智能体（无法点击、登录、填写表单）。请使用 Browser-Use 或 Playwright 实现此功能。
- 不是通用爬虫，竞争 Firecrawl 的任意站点质量。AgentSpan 针对它所知的 52 个平台进行了优化。
- 不是托管的 SaaS。它是一个自托管的二进制文件，您可以在自己的基础设施上运行。
## 网站
两个界面，一个设计系统 — 使用 React 18 + TypeScript + Vite + GSAP（ScrollTrigger）+ Lenis，纯 CSS（无 Tailwind/Bootstrap）：
- **首页**（ `/` ）— 营销页面；整个滚动条**就是**登录体验。
- **状态**（ `/status` ）— 实时、只读网关控制台。
### 首页（ `/` ）
一个基于章节的编辑 / 未来主义 HUD 克隆，逆向工程自参考设计，并填充了真实的 AgentSpan 内容：
| # | 章节 | 显示内容 |
|---|---|---|
| 0 | **预加载器** | 渐变网关球体，带有脉动环，0→100 启动计数器，终端输出 (`<92 MCP TOOLS>`，`// 2026`) |
| 1 | **英雄** | `Web Access Gateway` 显示标题，位于失真阴影的珊瑚网关图形上（其头部是一个开放环，路由请求通过天空），粉色云天空背景，散布的坐标标签，侧边标签，`EXPLORE` / `GITHUB` 药丸 |
| 2 | **通道** | 圆形门户，带有旋转的球体 + `52 CHANNELS` + 4 个编号类别卡 |
| 3 | **网络** | **网络网格** — 52 个通道作为品牌颜色的剪影头像，每个头像都佩戴着平台的真实徽标（或在没有徽标的情况下手绘字符），带有实时状态点 + 类别 |
| 4 | **架构** | 粉色轨道环图 + 9 个 Rust crates — **固定** 在滚动条上 |
| 5 | **功能** | 粉色面板上的 6 个杀手级功能 |
| 6 | **展示** | **AGENTSPAN 波形文字**，统计数据和安装代码片段 |
| 7 | **页脚** | 链接，MIT，版本 |
签名 Chrome：角落框架括号，实时鼠标坐标 HUD，声音切换，点网格章节纹理，动画切瓦隆药丸 CTA，一个 1s 每章节背景渐变，和 GSAP 滚动条揭示每个章节。
### 状态控制台（ `/status` ）
只读的网关概览，共享首页的 Chrome、字体、颜色和动画：网关**状态头部**（计数统计卡）、**52 个通道的网格**、**性能图表**（请求量 + 延迟，重绘）、**健康监视器**表格，具有故障转移状态、**快速操作**，以及可复制到剪贴板的**安装代码片段**。
**启动：** `cd web && npm install && npm run dev` → `/` 和 `/status`。（`?static` 在没有预加载器/平滑滚动的情况下渲染，便于截图。）
## 架构
```mermaid
flowchart TD
subgraph Clients
SDKs["9 种 SDK（Python/JavaScript/Rust/Go/Ruby/Java/PHP/C#/Swift）"]
CLI["AgentSpan 命令行界面"]
Dash["React 控制台"]
MCP["MCP 客户端（Claude/Cursor/...）"]
end
subgraph Gateway["AgentSpan 核心（Rust，异步）"]
API["REST API + SSE"]
MCPS["MCP 服务器（92 个工具）"]
Router["路由器：探测 · 选择 · 重试 · 电路中断"]
Cache["三层缓存（L1/L2/L3）"]
Auth["身份验证：密钥 · 租户 · RBAC · 速率限制 · 审计"]
end
Backends["后端：HTTP API · 命令行工具 · Jina Reader"]
Clients --> API & MCPS
API --> Router --> Backends
Router --> Cache
API --> Auth
```
## 快速开始（3 个命令）
```bash
cargo run --bin agentspan -- serve # 1. 在 :8080 上启动网关
curl "localhost:8080/api/v1/read?url=https://example.com" # 2. 读取任意页面
curl "localhost:8080/api/v1/channels/hackernews/search?q=rust" # 3. 搜索
```
或使用 Docker：
```bash
docker compose up --build # API + UI + Redis + PostgreSQL + Prometheus + Grafana
```
### 与 AI 智能体结合使用（Claude Code、Cursor、Windsurf）
```bash
# 一条命令 — 自动将 MCP 配置写入正确的文件：
agentspan mcp install --client claude-code # 或：cursor，windsurf，cline
# 或打印配置并自行粘贴：
agentspan mcp print-config --client cursor
# 查看所有 92 个工具：
agentspan mcp tools
```
参阅完整指南： [Claude Code](docs/guides/use-with-claude-code.md) ·
[Cursor](docs/guides/use-with-cursor.md) ·
[Windsurf](docs/guides/use-with-windsurf.md).
### 使用 SDK
```python
# 发布到 PyPI 之前：
# pip install agentspan
# 在发布之前，从源代码安装：
pip install -e sdk/python
from agentspan import AgentSpanClient
client = AgentSpanClient(base_url="http://localhost:8080")
print((await client.read("https://example.com")).body)
```
参阅 [sdk/README.md](sdk/README.md) 获取所有 9 种语言和
[docs/api-reference.md](docs/api-reference.md) 获取完整 API。
## 通道（52 个）
| 0 级（零配置） | 1 级（需要密钥/cookie） |
|---|---|
| web, github, youtube, tiktok, rss, hackernews, v2ex, exa, wikipedia, arxiv, quora, pinterest, npm, crates, pypi, gitlab, dockerhub, wayback, maps, weather, coinbase, duckduckgo, gnews, statuspage, huggingface, devto, openlibrary, gutenberg, lobsters, wikidata | twitter, reddit, bilibili, xiaohongshu, instagram, linkedin, xueqiu, xiaoyuzhou, discord, telegram, spotify, twitch, scholar, podcasts, openai, anthropic, brave, bing, google, notion, slack, flight |
每个通道都实现了 `read` 和/或 `search`，通过健康检查的后端路由器，并通过 `format_for_llm` 减少令牌。运行 `agentspan doctor` 查看当前哪个后端为每个通道提供服务。
## 命令行界面
```
agentspan serve | doctor | watch | format | benchmark | transcribe | tunnel
| plugin | install | uninstall | setup | config | skill | mcp | completions | update
```
亮点：`benchmark`（缓存命中率 vs 后端 p50/p99），`tunnel`（通过 cloudflared 的公共 URL），`plugin`（社区通道），`transcribe`（Whisper），`format`（每个通道的令牌减少规则），`completions <shell>`（bash/zsh/fish/powershell/elvish），以及 `config backup`/`config restore`。
## 可观察性和运维
- **`GET /metrics`** — Prometheus 文本公示（请求计数、错误、放弃的请求、延迟、通道仪表）。公开，因此刮刀不需要 API 密钥。
- **请求跟踪** — 每个请求/响应都带有 `x-trace-id`（一个传入的 `x-trace-id`/`x-request-id` 被尊重）；该 ID 附加到审计事件中以进行关联。
- **资源限制** — 2 MiB 请求体上限 + 全局飞行中并发限制，超过负荷时使用 `503` 而不是无限制的排队。
- **优雅关闭** — `agentspan serve` 在 Ctrl-C 和（在 Unix 上）`SIGTERM` 上排空飞行中请求。
## 智能路由和内容
- **自适应路由** — 使用 `BackendRouter::with_adaptive_routing()` 选择。自适应路由从实时流量中学习每个后端的 EWMA 延迟和成功率，并优先选择健康级别中表现更好的后端。未知后端保持乐观，以便仍然可以尝试。
- **内容智能** — 获取的页面被分类（文章/论坛/代码/文档）并附带关键事实（URL、日期、代码块）、阅读统计数据（字数/句子数、阅读时间）和**提取摘要**（最相关的句子）提取并作为元数据附加；`smart_truncate` 在句子边界而不是单词中间进行修剪。所有依赖项免费的启发式算法 — 无需模型调用。
- **条件再验证** — 直接 HTTP 路径记住 `ETag` / `Last-Modified` 并使用 `If-None-Match` / `If-Modified-Since` 再验证，因此不变的页面作为廉价的 `304` 返回，而不是完全重新下载。
- **联合搜索** — `POST /api/v1/search/federated` 同时查询多个通道， 按 URL 去重（合并哪些通道找到每个结果），并优先显示跨源命中。 一个通道失败不会影响查询。传递 `"rerank": true` 以按依赖项无关的词汇相关性分数（标题加权 TF 带有短语奖励）排序结果，并传递 `"collapse": true` 以通过标题相似性合并近似重复命中（同一故事在不同 URL 下重新发布）。
- **请求合并** — `with_request_coalescing()` 将多个并发相同读取合并为单个上游获取（单次飞行），因此五个智能体在同一秒内请求相同 URL 时，只需访问上游一次。
## 智能体内存
命名空间键/值临时存储，智能体可以在请求之间持久化小状态 — 游标、已见集合、笔记 — 而无需建立自己的存储：
```bash
curl -X PUT localhost:8080/api/v1/memory/agent1/cursor \
-H 'content-type: application/json' -d '{"value":{"page":3},"ttl_secs":3600}'
curl localhost:8080/api/v1/memory/agent1/cursor # -> {"value":{"page":3},...}
curl localhost:8080/api/v1/memory/agent1 # -> {"keys":["cursor"]}
```
内存中和进程本地（在请求之间存活，但不会重启）；条目采用可选的 TTL，并被懒惰地扫描。`GET`/`PUT`/`DELETE` 在 `/api/v1/memory/{namespace}/{key}` 上，`GET` 在 `/api/v1/memory/{namespace}` 上。
## AI 原生内容基元
`agentspan-channels` 中依赖项无关、确定性的构建块，使读取对智能体来说更便宜、更有用 — 无需模型调用，无需额外服务：
- **令牌预算编译器** (`budget::fit_to_budget`) — “给我这个页面，限制在 ≤ 2 000 个令牌内。” 将任何文本适配到硬令牌上限，优雅地从提取摘要降级到边界感知截断，并报告其使用的策略。估计值是安全的上限，因此上限成立。
- **内容指纹** (`fingerprint`) — 精确的 FNV-1a 哈希值 + 64 位 SimHash，因此智能体可以询问“自从我上次读取它以来，这个页面是否发生了**有意义**的变化，变化程度如何？”，而无需对正文进行差异比较。补充 ETag 再验证（仅表示字节不同）。
- **结构化提取** (`extract`) — 将类型化字段（标题、链接、日期、电子邮件、价格、摘要）拉取到 JSON 中，并仅投影您请求的键，因此通道可以在固定模式下回答，而无需花费 LLM 提取。
这些作为库原语提供；REST/MCP 接口是下一个波浪。
## 项目结构
```
crates/ Rust 工作空间（核心、探测、路由器、缓存、身份验证、通道、MCP、API、CLI）
sdk/ 9 种 SDK（Python、JavaScript、Rust、Go、Ruby、Java、PHP、C#、Swift）
web/ React 营销站点 + 管理控制台（Vite + GSAP + Lenis）
integrations/ MCP 客户端配置、VS Code/JetBrains/Nvim 插件、GitHub Action
plugins/ 社区通道注册表
docs/ API 参考、指南、mdbook 站点、i18n
tests/ 集成 + 负载测试套件
```
参阅 [KNOWN_ISSUES.md](KNOWN_ISSUES.md) 获取当前粗糙边缘和构建怪癖。
## 社区
- [问题](https://github.com/oxbshw/Agent-Span/issues) — 错误和功能请求
- [讨论](https://github.com/oxbshw/Agent-Span/discussions) — 问题和展示
- [CONTRIBUTING.md](CONTRIBUTING.md) — 如何添加通道或 MCP 工具
## 许可证
MIT — 参见 [LICENSE](LICENSE).
## 安全
- 默认绑定到 `127.0.0.1`；Docker 镜像设置为 `0.0.0.0`。
- 单用户模式（默认）：管理员路由返回 `403`。设置 `auth.require_api_key=true` 以启用作用域 API 密钥。
- API 密钥存储为 SHA-256 哈希值；`~/.agentspan/config.yaml` 为 `0600`，输出/日志中的机密会被遮蔽。参见 [SECURITY.md](SECURITY.md).
## 许可证
MIT — 参见 [LICENSE](LICENSE).
