From e96ebdec88d5d1034797882aa4b65039ba30ecc6 Mon Sep 17 00:00:00 2001 From: Panniantong Date: Tue, 24 Feb 2026 07:22:35 +0100 Subject: [PATCH] docs: Chinese README as default, English in docs/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Chinese README polished 3 rounds: - Round 1: direct translation - Round 2: too dry, too many tables, too technical - Round 3: conversational tone, scenario-driven, collapsible details Key improvements: - Opens with WHY not WHAT ('你的Agent很聪明，但是看不见') - Install section explains WHERE to paste for newbies - Features shown as bullet list not tables (better visual scan) - Architecture hidden in collapsible section (most users don't care) - 'Why Agent Eyes' section explains positioning clearly - English version at docs/README_en.md --- README.md | 338 +++++++++++++++++++--------------------------- docs/README_en.md | 130 ++++++++++++++++++ 2 files changed, 272 insertions(+), 196 deletions(-) create mode 100644 docs/README_en.md diff --git a/README.md b/README.md index 3e8f92e..6a659a6 100644 --- a/README.md +++ b/README.md @@ -1,106 +1,139 @@ # 👁️ Agent Eyes -**Give your AI Agent eyes to see the entire internet.** +**让你的 AI Agent 看见整个互联网。** -Agent Eyes is an open-source Agent capability aggregator. It combines the best free tools into one install, so any AI Agent can search and read the entire internet. +你的 AI Agent 很聪明，但是它看不见。它不能帮你刷 Reddit、搜 Twitter、读 B站视频。Agent Eyes 解决这个问题——装好之后，Agent 就能搜索和阅读互联网上几乎所有内容。 -> Not a framework. Not a library. Just glue — beautifully simple glue that gives your Agent superpowers. +> 装一次，能力拉满。大部分功能零配置、零花费。 + +[English](docs/README_en.md) --- -## Install (One Line) +## 30 秒上手 -**Copy this to your AI Agent** (Claude Code, OpenClaw, Cursor, ChatGPT, etc.): +把这句话复制给你的 AI Agent： ``` -Install and configure Agent Eyes by following the instructions here: -https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md +帮我安装 Agent Eyes：https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md ``` -Your Agent reads the guide, installs everything, and configures itself. You just watch. +> 💡 不知道怎么发？打开你的 Agent 对话框（Claude Code 终端、OpenClaw 聊天、Cursor Chat），直接粘贴上面这段话就行。 -**Or install manually:** +Agent 会自动装好并告诉你哪些功能已经可以用了。你最多需要回答 1-2 个问题。 + +
+想手动装？点这里 ```bash pip install https://github.com/Panniantong/agent-eyes/archive/main.zip -agent-eyes doctor # See what's available -agent-eyes setup # Unlock more (optional) -``` - -# Read any URL (works immediately, no config needed) -agent-eyes read "https://github.com/openai/gpt-4" -agent-eyes read "https://www.bilibili.com/video/BV1xx411c7mD" - -# Search GitHub (works immediately, no config needed) -agent-eyes search-github "LLM framework" - -# Unlock search (one free API key) -agent-eyes setup -agent-eyes search "AI agent infrastructure 2025" -agent-eyes search-reddit "best self-hosted LLM" --sub LocalLLaMA -agent-eyes search-twitter "OpenClaw agent" +agent-eyes install --env=auto +agent-eyes doctor ``` +
--- -## Platform Support +## 装好就能用的 -### ✅ Zero Config (works out of the box) +不需要任何配置，装好直接用： -| Platform | Read | Search | Notes | -|----------|:----:|:------:|-------| -| Web Pages | ✅ | — | Any URL via Jina Reader | -| GitHub | ✅ | ✅ | Repos, issues, PRs, code | -| Bilibili | ✅ | — | Videos with subtitles | -| YouTube | ✅ | — | Videos with subtitles (needs yt-dlp) | -| RSS | ✅ | — | Any RSS/Atom feed | -| Single Tweet | ✅ | — | Via Jina Reader | - -### 🔑 One Free API Key (30 seconds to set up) - -| Platform | Read | Search | Notes | -|----------|:----:|:------:|-------| -| Web (semantic) | — | ✅ | Exa API (1000 free/month) | -| Reddit | — | ✅ | Via Exa (site:reddit.com) | -| Twitter/X | — | ✅ | Via Exa (site:x.com) | - -### ⚙️ Optional Setup - -| Platform | Read | Search | What's Needed | -|----------|:----:|:------:|---------------| -| Reddit (full) | ✅ | — | ISP proxy (~$3-10/mo) | -| Twitter (advanced) | ✅ | ✅ | birdx + browser cookies (free) | -| WeChat Articles | ✅ | — | Playwright (free, auto-installed) | -| XiaoHongShu | ✅ | — | Playwright + one-time login (free) | -| Video Transcription | ✅ | — | Groq API key (free) | - ---- - -## Three Ways to Use - -### 1. Command Line (CLI) +- 🌐 **网页** — 给个 URL，帮你读出来 +- 📦 **GitHub** — 仓库、Issue、PR、代码搜索 +- 📺 **YouTube** — 自动提取视频字幕 +- 📺 **B站** — 视频信息 + 字幕提取 +- 📡 **RSS** — 任意订阅源 +- 🐦 **Twitter** — 读单条推文 ```bash -agent-eyes read # Read any URL -agent-eyes search "query" # Search the web -agent-eyes search-reddit "query" # Search Reddit -agent-eyes search-github "query" # Search GitHub -agent-eyes search-twitter "query" # Search Twitter -agent-eyes setup # Interactive setup wizard -agent-eyes doctor # Check platform status +agent-eyes read "https://github.com/openai/gpt-4" +agent-eyes read "https://www.bilibili.com/video/BV1xx411c7mD" +agent-eyes search-github "LLM 框架" ``` -### 2. MCP Server (for Claude Code, Cursor, etc.) +--- + +## 一个 Key 解锁搜索 + +注册 [Exa](https://exa.ai)（免费，1000 次/月），一个 Key 同时解锁 **全网搜索 + Reddit 搜索 + Twitter 搜索**： + +```bash +agent-eyes configure exa-key 你的KEY + +agent-eyes search "2025 最好的开源 LLM" +agent-eyes search-reddit "best self-hosted LLM" --sub LocalLLaMA +agent-eyes search-twitter "AI agent" +``` + +> 没有 Exa Key 也能用——只是不能搜索，读取功能不受影响。 + +--- + +## 解锁更多平台 + +### 🍪 Cookie 解锁（免费，2 分钟） + +本地电脑一键导入所有 cookies： + +```bash +agent-eyes configure --from-browser chrome +``` + +> 关掉 Chrome 再运行。支持 chrome / firefox / edge / brave / opera。 + +服务器用户？装个 [Cookie-Editor](https://chromewebstore.google.com/detail/cookie-editor/hlkenndednhfkekhgcdicdfddnkalmdm) 浏览器扩展，在网站上点一下 Export → Header String，粘贴给 Agent 就行。 + +Cookie 能解锁： + +| 平台 | 额外能力 | +|------|---------| +| 🐦 Twitter | 时间线搜索、完整线程、高级搜索 | +| 📕 小红书 | 笔记内容 + 评论 | + +### 🌐 代理解锁（$1/月，仅服务器需要） + +Reddit 和 B站封服务器 IP。本地电脑不受影响。 + +```bash +agent-eyes configure proxy http://用户名:密码@IP:端口 +``` + +> 推荐 [Webshare](https://webshare.io)，$1/月。一个代理同时解锁 Reddit + B站。 +> +> 不买也行——Reddit **搜索** 通过 Exa 免费可用，只是不能读完整帖子。 + +--- + +## 三种使用方式 + +### 命令行 + +```bash +agent-eyes read "https://任意URL" +agent-eyes search "任意搜索词" +agent-eyes search-github "关键词" +agent-eyes search-reddit "关键词" +agent-eyes search-twitter "关键词" +agent-eyes doctor +``` + +### Python + +```python +from agent_eyes import AgentEyes +import asyncio + +eyes = AgentEyes() +result = asyncio.run(eyes.read("https://example.com")) +results = asyncio.run(eyes.search("AI agent")) +``` + +### MCP Server（Claude Code / Cursor） ```bash pip install agent-eyes[mcp] -python -m agent_eyes.integrations.mcp_server ``` -Exposes 8 tools: `read_url`, `read_batch`, `detect_platform`, `search`, `search_reddit`, `search_github`, `search_twitter`, `get_status` - -Add to your MCP config: - ```json { "mcpServers": { @@ -112,148 +145,61 @@ Add to your MCP config: } ``` -### 3. Python Library +--- -```python -from agent_eyes import AgentEyes -import asyncio +## 配置速查 -eyes = AgentEyes() - -# Read -result = asyncio.run(eyes.read("https://github.com/openai/gpt-4")) -print(result["title"]) -print(result["content"]) - -# Search -results = asyncio.run(eyes.search("AI agent framework")) -for r in results: - print(f"{r['title']} — {r['url']}") - -# Search Reddit -results = asyncio.run(eyes.search_reddit("best LLM", subreddit="LocalLLaMA")) - -# Health check -print(eyes.doctor_report()) -``` +| 命令 | 作用 | +|------|------| +| `agent-eyes doctor` | 查看所有频道状态 | +| `agent-eyes configure --from-browser chrome` | 一键导入 cookies（本地）| +| `agent-eyes configure exa-key KEY` | 解锁全网搜索 | +| `agent-eyes configure twitter-cookies "..."` | 解锁 Twitter 高级 | +| `agent-eyes configure xhs-cookie "..."` | 解锁小红书 | +| `agent-eyes configure proxy URL` | 解锁 Reddit + B站（服务器）| --- -## Configuration +## 为什么用 Agent Eyes？ -### Interactive Setup +**不是框架，不是 SDK，就是胶水。** -```bash -agent-eyes setup -``` +- 把最好的免费工具粘在一起：Jina Reader、birdx、yt-dlp、Exa、feedparser +- 每个平台就是一个 ~50 行的薄封装，换后端只改一个文件 +- CLI、MCP Server、Python API 三种接入方式 +- 99% 功能免费，剩下 1% 也就 $1/月 -Walks you through configuring each platform step by step. Only asks for what you want to set up. - -### Agent-Readable Guides - -Each platform has a detailed setup guide in `agent_eyes/guides/`. These are designed for AI Agents to read and follow — the Agent handles the technical steps, and only asks the user for things that require human action (logging in, copying API keys, buying proxies). - -| Guide | What It Configures | -|-------|-------------------| -| `setup-exa.md` | Exa search API key (free) | -| `setup-reddit.md` | Reddit ISP proxy | -| `setup-twitter.md` | Twitter birdx cookies | -| `setup-xiaohongshu.md` | XiaoHongShu login | -| `setup-wechat.md` | WeChat Playwright | -| `setup-groq.md` | Groq Whisper API key (free) | - -### Manual Config - -Config file: `~/.agent-eyes/config.yaml` - -```yaml -exa_api_key: "exa-..." -github_token: "ghp_..." -reddit_proxy: "http://user:pass@ip:port" -groq_api_key: "gsk_..." -``` - -Environment variables also work (uppercase): `EXA_API_KEY`, `GITHUB_TOKEN`, etc. - ---- - -## Health Check - -```bash -$ agent-eyes doctor - -👁️ Agent Eyes Status -======================================== - -✅ Ready (no setup needed): - ✅ Web Pages - ✅ GitHub - ✅ Bilibili - ✅ RSS - ✅ Tweet (single) - ✅ GitHub Search - -🔍 Search (need free Exa API key): - ⬜ Web Search - ⬜ Reddit Search - ⬜ Twitter Search - -🔧 Optional (advanced setup): - ⬜ Twitter Advanced — Install birdx for timeline/deep search - ⬜ Reddit Reader — Need proxy for full post reading - ⬜ WeChat — pip install agent-eyes[browser] - ⬜ XiaoHongShu — pip install agent-eyes[browser] - -Status: 7/13 platforms active -Run `agent-eyes setup` to unlock more! -``` - ---- - -## Architecture - -Agent Eyes is pure glue. Every channel is a thin wrapper (~50 lines) around an external tool. **Swap any backend by changing one file.** +
+架构图 ``` ┌─────────────────────────────────────────┐ -│ Agent Eyes (pure glue) │ +│ Agent Eyes（纯胶水） │ │ │ -│ ┌─────────────────────────────────────┐│ -│ │ Pluggable Channels ││ -│ │ ││ -│ │ web.py → Jina Reader API ││ -│ │ github.py → GitHub API ││ -│ │ twitter.py → birdx + Jina ││ -│ │ youtube.py → yt-dlp ││ -│ │ reddit.py → Reddit JSON API ││ -│ │ bilibili.py → Bilibili API ││ -│ │ rss.py → feedparser ││ -│ │ exa.py → Exa Search API ││ -│ │ ││ -│ │ ↑ Swap any backend, nothing else ││ -│ │ changes. Just edit one file. ││ -│ └─────────────────────────────────────┘│ -│ ┌──────────┐ ┌──────────────────────┐ │ -│ │ Config │ │ Integrations │ │ -│ │ Doctor │ │ CLI · MCP · Skill │ │ -│ │ Guides │ │ Python API │ │ -│ └──────────┘ └──────────────────────┘ │ +│ web.py → Jina Reader API │ +│ github.py → GitHub API │ +│ twitter.py → birdx + Jina │ +│ youtube.py → yt-dlp │ +│ reddit.py → Reddit JSON API │ +│ bilibili.py → Bilibili API │ +│ rss.py → feedparser │ +│ exa.py → Exa Search API │ +│ xhs.py → XHS Web API │ +│ │ +│ CLI · MCP Server · Python API │ └─────────────────────────────────────────┘ ``` - -**Design principle**: Agent Eyes doesn't reinvent wheels. It aggregates the best free tools and makes them accessible to any AI Agent with one install. +
--- -## Credits +## 致谢 -Agent Eyes stands on the shoulders of these amazing open-source projects: - -- **[Jina Reader](https://r.jina.ai)** — web page reading -- **[birdx](https://github.com/runesleo/birdx)** by [@runes_leo](https://x.com/runes_leo) — Twitter access -- **[Exa](https://exa.ai)** — semantic search -- **[yt-dlp](https://github.com/yt-dlp/yt-dlp)** — YouTube transcripts -- **[feedparser](https://github.com/kurtmckee/feedparser)** — RSS/Atom feeds +- [Jina Reader](https://r.jina.ai) — 网页阅读 +- [birdx](https://github.com/runesleo/birdx) by [@runes_leo](https://x.com/runes_leo) — Twitter +- [Exa](https://exa.ai) — 语义搜索 +- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — YouTube +- [feedparser](https://github.com/kurtmckee/feedparser) — RSS ## License diff --git a/docs/README_en.md b/docs/README_en.md new file mode 100644 index 0000000..185b116 --- /dev/null +++ b/docs/README_en.md @@ -0,0 +1,130 @@ +# 👁️ Agent Eyes + +**Give your AI Agent eyes to see the entire internet.** + +Your AI Agent is smart but blind. It can't browse Reddit, search Twitter, or read Bilibili videos. Agent Eyes fixes this — once installed, your Agent can search and read content across 10+ platforms. + +> Install once. Superpowers unlocked. Most features work with zero config, zero cost. + +[中文文档](../README.md) + +--- + +## Get Started in 30 Seconds + +Copy this to your AI Agent (Claude Code, OpenClaw, Cursor, etc.): + +``` +Install Agent Eyes: https://raw.githubusercontent.com/Panniantong/agent-eyes/main/docs/install.md +``` + +Your Agent handles everything. You answer 1-2 questions at most. + +
+Manual install + +```bash +pip install https://github.com/Panniantong/agent-eyes/archive/main.zip +agent-eyes install --env=auto +agent-eyes doctor +``` +
+ +--- + +## Works Out of the Box + +No configuration needed: + +- 🌐 **Web pages** — read any URL +- 📦 **GitHub** — repos, issues, PRs, code search +- 📺 **YouTube** — video transcripts +- 📺 **Bilibili** — video info + subtitles +- 📡 **RSS** — any feed +- 🐦 **Twitter** — read individual tweets + +```bash +agent-eyes read "https://github.com/openai/gpt-4" +agent-eyes search-github "LLM framework" +``` + +--- + +## One Key Unlocks Search + +Sign up at [Exa](https://exa.ai) (free, 1000 searches/month). One key unlocks **web + Reddit + Twitter search**: + +```bash +agent-eyes configure exa-key YOUR_KEY +agent-eyes search "best open source LLM 2025" +agent-eyes search-reddit "self-hosted LLM" --sub LocalLLaMA +agent-eyes search-twitter "AI agent" +``` + +--- + +## Unlock More + +### 🍪 Cookie-based (free, 2 minutes) + +```bash +# Local: auto-import all cookies +agent-eyes configure --from-browser chrome + +# Server: use Cookie-Editor extension, export Header String +agent-eyes configure twitter-cookies "cookie_string" +agent-eyes configure xhs-cookie "cookie_string" +``` + +Unlocks: Twitter deep search, XiaoHongShu notes + +### 🌐 Proxy ($1/month, servers only) + +Reddit and Bilibili block server IPs. Local computers are fine. + +```bash +agent-eyes configure proxy http://user:pass@ip:port +``` + +Recommend [Webshare](https://webshare.io). One proxy covers both Reddit and Bilibili. + +--- + +## Three Ways to Use + +**CLI** · **Python API** · **MCP Server** + +```bash +agent-eyes read "URL" +agent-eyes search "query" +agent-eyes doctor +``` + +```python +from agent_eyes import AgentEyes +eyes = AgentEyes() +result = asyncio.run(eyes.read("https://example.com")) +``` + +```json +{"mcpServers": {"agent-eyes": {"command": "python", "args": ["-m", "agent_eyes.integrations.mcp_server"]}}} +``` + +--- + +## Why Agent Eyes? + +Not a framework. Not an SDK. Just glue — beautifully simple glue. + +- Aggregates the best free tools: Jina Reader, birdx, yt-dlp, Exa, feedparser +- Each channel is ~50 lines. Swap any backend by editing one file. +- CLI, MCP Server, Python API +- 99% free. The remaining 1% costs $1/month. + +## Credits + +[Jina Reader](https://r.jina.ai) · [birdx](https://github.com/runesleo/birdx) · [Exa](https://exa.ai) · [yt-dlp](https://github.com/yt-dlp/yt-dlp) · [feedparser](https://github.com/kurtmckee/feedparser) + +## License + +MIT