docs: 精简贡献指南,去掉技术细节
- 删掉添加新渠道的代码示例和 3 步教程 - 删掉希望支持的渠道列表 - 简化为:想要新渠道提 Issue/PR,想本地加让 Agent clone 改就行 - 中英文同步
This commit is contained in:
@@ -159,11 +159,10 @@ Agent Reach 做的事情很简单:**帮你把这些选型和配置的活儿做
|
|||||||
|
|
||||||
### 🔌 每个渠道都是可插拔的
|
### 🔌 每个渠道都是可插拔的
|
||||||
|
|
||||||
每个平台对应一个独立的 Python 文件(~50–100 行),实现统一接口。**后端工具随时可以换**——哪天出了更好的工具,改一个文件就行,其他不用动。
|
每个平台对应一个独立的 Python 文件,实现统一接口。**后端工具随时可以换**——哪天出了更好的工具,改一个文件就行,其他不用动。
|
||||||
|
|
||||||
```
|
```
|
||||||
channels/
|
channels/
|
||||||
├── base.py → 统一接口(Channel 基类)
|
|
||||||
├── web.py → Jina Reader ← 可以换成 Firecrawl、Crawl4AI……
|
├── web.py → Jina Reader ← 可以换成 Firecrawl、Crawl4AI……
|
||||||
├── twitter.py → birdx ← 可以换成 Nitter、官方 API……
|
├── twitter.py → birdx ← 可以换成 Nitter、官方 API……
|
||||||
├── youtube.py → yt-dlp ← 可以换成 YouTube API、Whisper……
|
├── youtube.py → yt-dlp ← 可以换成 YouTube API、Whisper……
|
||||||
@@ -173,54 +172,9 @@ channels/
|
|||||||
├── xiaohongshu.py → mcporter MCP ← 可以换成其他 XHS 工具……
|
├── xiaohongshu.py → mcporter MCP ← 可以换成其他 XHS 工具……
|
||||||
├── rss.py → feedparser ← 可以换成 atoma……
|
├── rss.py → feedparser ← 可以换成 atoma……
|
||||||
├── exa_search.py → mcporter MCP ← 可以换成 Tavily、SerpAPI……
|
├── exa_search.py → mcporter MCP ← 可以换成 Tavily、SerpAPI……
|
||||||
└── __init__.py → 渠道注册(加一行就注册一个新渠道)
|
└── __init__.py → 渠道注册
|
||||||
```
|
```
|
||||||
|
|
||||||
想换后端?打开对应文件,改掉 `read()` / `search()` 的实现就行。接口不变,其他代码不用动。
|
|
||||||
|
|
||||||
### 🧩 添加新渠道(3 步)
|
|
||||||
|
|
||||||
添加新渠道非常简单,3 步就能搞定:
|
|
||||||
|
|
||||||
**第 1 步:** 新建 `channels/你的渠道.py`
|
|
||||||
|
|
||||||
```python
|
|
||||||
from .base import Channel, ReadResult, SearchResult
|
|
||||||
|
|
||||||
class 你的渠道Channel(Channel):
|
|
||||||
name = "你的渠道"
|
|
||||||
description = "一句话描述"
|
|
||||||
backends = ["用了什么工具"]
|
|
||||||
|
|
||||||
def can_handle(self, url: str) -> bool:
|
|
||||||
return "你的域名" in url
|
|
||||||
|
|
||||||
async def read(self, url: str, config=None) -> ReadResult:
|
|
||||||
# 读取内容,返回 ReadResult
|
|
||||||
return ReadResult(title="...", content="...", url=url, platform=self.name)
|
|
||||||
|
|
||||||
def check(self, config=None):
|
|
||||||
return "ok", "一切正常"
|
|
||||||
|
|
||||||
# 可选:实现 search() 支持搜索
|
|
||||||
```
|
|
||||||
|
|
||||||
**第 2 步:** 在 `channels/__init__.py` 注册
|
|
||||||
|
|
||||||
```python
|
|
||||||
from .你的渠道 import 你的渠道Channel
|
|
||||||
|
|
||||||
ALL_CHANNELS: List[Channel] = [
|
|
||||||
...
|
|
||||||
你的渠道Channel(), # 加这一行
|
|
||||||
WebChannel(),
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
**第 3 步:** 没了。`agent-reach doctor` 自动识别,`agent-reach read` 自动路由。
|
|
||||||
|
|
||||||
> 💡 **参考现有渠道:** `rss.py`(30 行,最简单)→ `web.py`(50 行)→ `youtube.py`(100 行,含搜索)
|
|
||||||
|
|
||||||
### 当前选型
|
### 当前选型
|
||||||
|
|
||||||
| 场景 | 选型 | 为什么选它 |
|
| 场景 | 选型 | 为什么选它 |
|
||||||
@@ -241,25 +195,9 @@ ALL_CHANNELS: List[Channel] = [
|
|||||||
|
|
||||||
欢迎提 [Issue](https://github.com/Panniantong/agent-reach/issues) 和 [PR](https://github.com/Panniantong/agent-reach/pulls)。
|
欢迎提 [Issue](https://github.com/Panniantong/agent-reach/issues) 和 [PR](https://github.com/Panniantong/agent-reach/pulls)。
|
||||||
|
|
||||||
### 🆕 想添加新渠道?
|
**想要新渠道?** 直接提 Issue 告诉我们,或者自己提 PR。
|
||||||
|
|
||||||
1. 复制 `agent_reach/channels/rss.py`(最简单的参考)
|
**想在本地加?** 让你的 Agent clone 下来改就行,每个渠道就是一个独立文件,加起来很简单。
|
||||||
2. 实现 `can_handle()` + `read()`,可选 `search()` 和 `check()`
|
|
||||||
3. 在 `__init__.py` 注册
|
|
||||||
|
|
||||||
就这么简单。不需要改框架代码,不需要了解其他渠道。
|
|
||||||
|
|
||||||
**希望支持的渠道(欢迎 PR):**
|
|
||||||
|
|
||||||
- 📰 Hacker News — 科技新闻
|
|
||||||
- 🐘 Mastodon / Fediverse — 去中心化社交
|
|
||||||
- 📱 Telegram — 频道和群组
|
|
||||||
- 🎵 Spotify / Apple Podcasts — 播客字幕
|
|
||||||
- 📝 Medium / Substack — 付费墙文章
|
|
||||||
- 🔬 arXiv / Semantic Scholar — 学术论文
|
|
||||||
- 💬 Discord — 服务器消息
|
|
||||||
- 📌 Pinterest — 图片搜索
|
|
||||||
- …… 任何你觉得有用的平台!
|
|
||||||
|
|
||||||
## 致谢
|
## 致谢
|
||||||
|
|
||||||
|
|||||||
+4
-64
@@ -159,11 +159,10 @@ Agent Reach does one simple thing: **it makes those tool selection and configura
|
|||||||
|
|
||||||
### 🔌 Every Channel is Pluggable
|
### 🔌 Every Channel is Pluggable
|
||||||
|
|
||||||
Each platform is a single Python file (~50–100 lines) implementing a unified interface. **Backends can be swapped anytime** — when a better tool comes along, change one file and nothing else breaks.
|
Each platform is a single Python file implementing a unified interface. **Backends can be swapped anytime** — when a better tool comes along, change one file and nothing else breaks.
|
||||||
|
|
||||||
```
|
```
|
||||||
channels/
|
channels/
|
||||||
├── base.py → Unified interface (Channel base class)
|
|
||||||
├── web.py → Jina Reader ← swap to Firecrawl, Crawl4AI…
|
├── web.py → Jina Reader ← swap to Firecrawl, Crawl4AI…
|
||||||
├── twitter.py → birdx ← swap to Nitter, official API…
|
├── twitter.py → birdx ← swap to Nitter, official API…
|
||||||
├── youtube.py → yt-dlp ← swap to YouTube API, Whisper…
|
├── youtube.py → yt-dlp ← swap to YouTube API, Whisper…
|
||||||
@@ -173,52 +172,9 @@ channels/
|
|||||||
├── xiaohongshu.py → mcporter MCP ← swap to other XHS tools…
|
├── xiaohongshu.py → mcporter MCP ← swap to other XHS tools…
|
||||||
├── rss.py → feedparser ← swap to atoma…
|
├── rss.py → feedparser ← swap to atoma…
|
||||||
├── exa_search.py → mcporter MCP ← swap to Tavily, SerpAPI…
|
├── exa_search.py → mcporter MCP ← swap to Tavily, SerpAPI…
|
||||||
└── __init__.py → Channel registry (one line to register a new channel)
|
└── __init__.py → Channel registry
|
||||||
```
|
```
|
||||||
|
|
||||||
Want to swap a backend? Open the file, change the `read()` / `search()` implementation. Interface stays the same, nothing else needs to change.
|
|
||||||
|
|
||||||
### 🧩 Adding a New Channel (3 Steps)
|
|
||||||
|
|
||||||
**Step 1:** Create `channels/your_channel.py`
|
|
||||||
|
|
||||||
```python
|
|
||||||
from .base import Channel, ReadResult, SearchResult
|
|
||||||
|
|
||||||
class YourChannel(Channel):
|
|
||||||
name = "your_channel"
|
|
||||||
description = "One-line description"
|
|
||||||
backends = ["tool-name"]
|
|
||||||
|
|
||||||
def can_handle(self, url: str) -> bool:
|
|
||||||
return "yourdomain.com" in url
|
|
||||||
|
|
||||||
async def read(self, url: str, config=None) -> ReadResult:
|
|
||||||
# Fetch content, return ReadResult
|
|
||||||
return ReadResult(title="...", content="...", url=url, platform=self.name)
|
|
||||||
|
|
||||||
def check(self, config=None):
|
|
||||||
return "ok", "All good"
|
|
||||||
|
|
||||||
# Optional: implement search() for search support
|
|
||||||
```
|
|
||||||
|
|
||||||
**Step 2:** Register in `channels/__init__.py`
|
|
||||||
|
|
||||||
```python
|
|
||||||
from .your_channel import YourChannel
|
|
||||||
|
|
||||||
ALL_CHANNELS: List[Channel] = [
|
|
||||||
...
|
|
||||||
YourChannel(), # add this line
|
|
||||||
WebChannel(),
|
|
||||||
]
|
|
||||||
```
|
|
||||||
|
|
||||||
**Step 3:** Done. `agent-reach doctor` auto-detects it, `agent-reach read` auto-routes to it.
|
|
||||||
|
|
||||||
> 💡 **Reference examples:** `rss.py` (30 lines, simplest) → `web.py` (50 lines) → `youtube.py` (100 lines, with search)
|
|
||||||
|
|
||||||
### Current Tool Choices
|
### Current Tool Choices
|
||||||
|
|
||||||
| Scenario | Tool | Why |
|
| Scenario | Tool | Why |
|
||||||
@@ -239,25 +195,9 @@ ALL_CHANNELS: List[Channel] = [
|
|||||||
|
|
||||||
[Issues](https://github.com/Panniantong/agent-reach/issues) and [PRs](https://github.com/Panniantong/agent-reach/pulls) welcome.
|
[Issues](https://github.com/Panniantong/agent-reach/issues) and [PRs](https://github.com/Panniantong/agent-reach/pulls) welcome.
|
||||||
|
|
||||||
### 🆕 Want to Add a New Channel?
|
**Want a new channel?** Open an Issue to request it, or submit a PR yourself.
|
||||||
|
|
||||||
1. Copy `agent_reach/channels/rss.py` (simplest reference)
|
**Want to add one locally?** Just have your Agent clone the repo and modify it — each channel is a single standalone file, easy to add.
|
||||||
2. Implement `can_handle()` + `read()`, optionally `search()` and `check()`
|
|
||||||
3. Register in `__init__.py`
|
|
||||||
|
|
||||||
That's it. No framework code to modify, no need to understand other channels.
|
|
||||||
|
|
||||||
**Channels we'd love to see (PRs welcome):**
|
|
||||||
|
|
||||||
- 📰 Hacker News — tech news
|
|
||||||
- 🐘 Mastodon / Fediverse — decentralized social
|
|
||||||
- 📱 Telegram — channels and groups
|
|
||||||
- 🎵 Spotify / Apple Podcasts — podcast transcripts
|
|
||||||
- 📝 Medium / Substack — paywalled articles
|
|
||||||
- 🔬 arXiv / Semantic Scholar — academic papers
|
|
||||||
- 💬 Discord — server messages
|
|
||||||
- 📌 Pinterest — image search
|
|
||||||
- … anything you find useful!
|
|
||||||
|
|
||||||
## Credits
|
## Credits
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user