rss-agent-discovery

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

RSS Agent Discovery

RSS Agent 订阅源发现工具

AI agent-focused RSS feed discovery tool with machine-parseable JSON output.

一款面向AI Agent的RSS订阅源发现工具，支持机器可解析的JSON格式输出。

Quick start

快速开始

bash

npx -y rss-agent-discovery https://vercel.com

Output:

json

{
  "success": true,
  "results": [{
    "url": "https://vercel.com/",
    "feeds": [{
      "url": "https://vercel.com/atom",
      "title": "atom",
      "type": "atom"
    }],
    "error": null,
    "diagnostics": []
  }]
}

bash

npx -y rss-agent-discovery https://vercel.com

输出结果：

json

{
  "success": true,
  "results": [{
    "url": "https://vercel.com/",
    "feeds": [{
      "url": "https://vercel.com/atom",
      "title": "atom",
      "type": "atom"
    }],
    "error": null,
    "diagnostics": []
  }]
}

Core workflow

核心工作流

bash

npx -y rss-agent-discovery <url> [url2] [url3]...

Parse JSON output:

bash

npx -y rss-agent-discovery https://example.com | jq '.results[0].feeds'

bash

npx -y rss-agent-discovery <url> [url2] [url3]...

解析JSON输出：

bash

npx -y rss-agent-discovery https://example.com | jq '.results[0].feeds'

Output schema

输出 Schema

typescript

{
  success: boolean,           // true if no URLs had errors
  partialResults?: boolean,   // true if success=false but some feeds found
  results: [{
    url: string,              // scanned URL
    feeds: [{
      url: string,            // feed URL
      title: string,          // feed title from HTML
      type: 'rss' | 'atom' | 'unknown'
    }],
    error: string | null,     // error message if scan failed (timeout errors normalized to "Timeout")
    diagnostics?: string[]    // optional array of warning messages for non-fatal issues
  }]
}

typescript

{
  success: boolean,           // true if no URLs had errors
  partialResults?: boolean,   // true if success=false but some feeds found
  results: [{
    url: string,              // scanned URL
    feeds: [{
      url: string,            // feed URL
      title: string,          // feed title from HTML
      type: 'rss' | 'atom' | 'unknown'
    }],
    error: string | null,     // error message if scan failed (timeout errors normalized to "Timeout")
    diagnostics?: string[]    // optional array of warning messages for non-fatal issues
  }]
}

Output contract

输出约定

Default behavior (without
--verbose
):

JSON-only output to stdout (machine-parseable)
No stderr output (clean for programmatic consumption)
All errors and warnings included in JSON structure

Verbose mode (
--verbose
):

JSON output to stdout (unchanged)
Debug logging to stderr (useful for troubleshooting)
Additional context about skipped URLs, validation failures, etc.

Recommended integration pattern:

Parse stdout as JSON (always valid JSON, even on errors)
Check
```
success
```
field for overall status
Check
```
partialResults
```
if
```
success === false
```
to see if any feeds were found
Check
```
error
```
field in each result for URL-specific failures
Check
```
diagnostics
```
array for warnings and non-fatal issues
Use
```
--verbose
```
flag only when troubleshooting or debugging

默认行为（不使用
--verbose
参数）：

仅向标准输出（stdout）输出JSON格式内容（机器可解析）
无标准错误输出（stderr），适合程序化调用
所有错误与警告信息均包含在JSON结构中

详细模式（
--verbose
）：

向标准输出（stdout）输出JSON内容（格式不变）
向标准错误输出（stderr）输出调试日志（便于问题排查）
提供关于跳过的URL、验证失败等额外上下文信息

推荐集成方式：

将标准输出内容解析为JSON（即使发生错误，输出也始终是合法的JSON）
检查
```
success
```
字段以获取整体执行状态
若
```
success
```
为
```
false
```
，检查
```
partialResults
```
字段以确认是否找到部分订阅源
检查每个结果中的
```
error
```
字段，查看特定URL的执行失败信息
检查
```
diagnostics
```
数组，获取警告与非致命性问题信息
仅在问题排查或调试时使用
```
--verbose
```
参数

Exit codes

退出码

```
0
```
- One or more feeds found (or
```
--help
```
/
```
--version
```
used)
```
1
```
- No feeds found
```
2
```
- Error occurred

Use exit code for automation:

bash

npx -y rss-agent-discovery https://example.com
if [ $? -eq 0 ]; then
  echo "Feeds found!"
fi

```
0
```
- 找到一个或多个订阅源（或使用了
```
--help
```
/
```
--version
```
参数）
```
1
```
- 未找到任何订阅源
```
2
```
- 发生错误

使用退出码实现自动化：

bash

npx -y rss-agent-discovery https://example.com
if [ $? -eq 0 ]; then
  echo "Feeds found!"
fi

Options

选项

bash

--timeout <ms>          # Timeout per URL (default: 10000)
--skip-blogs           # Skip blog subdirectory scanning
--max-blogs <n>        # Limit blog scans (default: 3)
--blog-paths <paths>   # Custom blog paths (comma or pipe separated)
--verbose              # Enable debug logging to stderr (default: JSON-only output)
--help                 # Show help
--version              # Show version

Examples:

bash

npx -y rss-agent-discovery --timeout 15000 https://example.com
npx -y rss-agent-discovery --skip-blogs https://example.com
npx -y rss-agent-discovery --blog-paths '/blog,/news,/articles' https://example.com
npx -y rss-agent-discovery --blog-paths '/blog|/updates' https://example.com
npx -y rss-agent-discovery --max-blogs 5 https://example.com

bash

--timeout <ms>          # Timeout per URL (default: 10000)
--skip-blogs           # Skip blog subdirectory scanning
--max-blogs <n>        # Limit blog scans (default: 3)
--blog-paths <paths>   # Custom blog paths (comma or pipe separated)
--verbose              # Enable debug logging to stderr (default: JSON-only output)
--help                 # Show help
--version              # Show version

示例：

bash

npx -y rss-agent-discovery --timeout 15000 https://example.com
npx -y rss-agent-discovery --skip-blogs https://example.com
npx -y rss-agent-discovery --blog-paths '/blog,/news,/articles' https://example.com
npx -y rss-agent-discovery --blog-paths '/blog|/updates' https://example.com
npx -y rss-agent-discovery --max-blogs 5 https://example.com

Features

功能特性

Discovers feeds from HTML
```
<link>
```
tags
Tests common paths (
```
/rss.xml
```
,
```
/atom
```
,
```
/feed
```
, etc.)
Scans blog subdirectories (
```
/blog
```
,
```
/news
```
,
```
/articles
```
)
Parallel processing for multiple URLs
Deduplicates feeds across all sources
Validates feeds actually return XML
JSON-only output to stdout (clean by default, no stderr)
Errors and warnings included in JSON structure
Timeout errors normalized to consistent "Timeout" message

从HTML的
```
<link>
```
标签中发现订阅源
检测常见路径（如
```
/rss.xml
```
、
```
/atom
```
、
```
/feed
```
等）
扫描博客子目录（如
```
/blog
```
、
```
/news
```
、
```
/articles
```
等）
多URL并行处理
对所有来源的订阅源进行去重
验证订阅源是否真的返回XML内容
仅向标准输出输出JSON内容（默认无冗余输出，无标准错误输出）
所有错误与警告信息均包含在JSON结构中
超时错误统一标准化为"Timeout"消息
发现AI Agent可能遗漏的订阅源

Common patterns

常见使用场景

Single URL discovery

单URL订阅源发现

bash

npx -y rss-agent-discovery https://example.com | jq '.results[0].feeds[].url'

bash

npx -y rss-agent-discovery https://example.com | jq '.results[0].feeds[].url'

Multiple URLs (parallel)

多URL并行处理

bash

npx -y rss-agent-discovery https://site1.com https://site2.com https://site3.com

bash

npx -y rss-agent-discovery https://site1.com https://site2.com https://site3.com

Extract all feed URLs

提取所有订阅源URL

bash

npx -y rss-agent-discovery https://example.com | jq -r '.results[0].feeds[].url'

bash

npx -y rss-agent-discovery https://example.com | jq -r '.results[0].feeds[].url'

Check if feeds exist without parsing

不解析内容，仅检查订阅源是否存在

bash

npx -y rss-agent-discovery https://example.com
exit_code=$?
[ $exit_code -eq 0 ] && echo "Feeds found"

bash

npx -y rss-agent-discovery https://example.com
exit_code=$?
[ $exit_code -eq 0 ] && echo "Feeds found"

Custom timeout for slow sites

为慢响应站点设置自定义超时时间

bash

npx -y rss-agent-discovery --timeout 20000 https://slow-site.com

bash

npx -y rss-agent-discovery --timeout 20000 https://slow-site.com

Skip blog scanning for faster results

跳过博客扫描以提升速度

bash

npx -y rss-agent-discovery --skip-blogs https://example.com

bash

npx -y rss-agent-discovery --skip-blogs https://example.com

Integration examples

集成示例

Shell script

Shell脚本

bash

#!/bin/bash

bash

#!/bin/bash

No need to redirect stderr - it's clean by default

result=$(npx -y rss-agent-discovery "$1") if [ $? -eq 0 ]; then echo "Found feeds:" echo "$result" | jq '.results[0].feeds' fi

undefined

result=$(npx -y rss-agent-discovery "$1") if [ $? -eq 0 ]; then echo "Found feeds:" echo "$result" | jq '.results[0].feeds' fi

undefined

Python

python

import subprocess
import json

result = subprocess.run(
  ['npx', '-y', 'rss-agent-discovery', url],
  capture_output=True,
  text=True
)

if result.returncode == 0:
  data = json.loads(result.stdout)
  feeds = data['results'][0]['feeds']

python

import subprocess
import json

result = subprocess.run(
  ['npx', '-y', 'rss-agent-discovery', url],
  capture_output=True,
  text=True
)

if result.returncode == 0:
  data = json.loads(result.stdout)
  feeds = data['results'][0]['feeds']

JavaScript/Node.js

javascript

const { execSync } = require('child_process');
const result = JSON.parse(
  execSync('npx -y rss-agent-discovery https://example.com').toString()
);
const feeds = result.results[0].feeds;

javascript

const { execSync } = require('child_process');
const result = JSON.parse(
  execSync('npx -y rss-agent-discovery https://example.com').toString()
);
const feeds = result.results[0].feeds;

Why use this tool

为何选择本工具

Existing RSS discovery tools (

rss-url-finder

rss-finder

) are designed for humans:

Output human-readable text
Don't validate feeds exist
Lack structured machine output

This tool is designed for AI agents:

JSON-only output to stdout (machine-parseable)
Clean output by default (no stderr unless
```
--verbose
```
is enabled)
All errors and warnings included in JSON structure
Semantic exit codes
Validates feeds return XML
Timeout errors normalized to consistent format
Discovers feeds AI agents miss

现有的RSS订阅源发现工具（如

rss-url-finder

、

rss-finder

）是为人类用户设计的：

输出人类可读的文本内容
不验证订阅源是否真实存在
缺乏结构化的机器可读输出

而本工具是专为AI Agent设计的：

仅向标准输出输出JSON内容（机器可解析）
默认输出简洁（仅在启用
```
--verbose
```
时才会输出标准错误内容）
所有错误与警告信息均包含在JSON结构中
语义化的退出码
验证订阅源是否返回XML内容
超时错误统一为一致的格式
发现AI Agent可能遗漏的订阅源

Testing

测试

Test the tool works:

bash

npx -y rss-agent-discovery https://vercel.com
npx -y rss-agent-discovery https://news.ycombinator.com

测试工具可用性：

bash

npx -y rss-agent-discovery https://vercel.com
npx -y rss-agent-discovery https://news.ycombinator.com

rss-agent-discovery

Original

Translation

RSS Agent Discovery

RSS Agent 订阅源发现工具

Quick start

快速开始

Core workflow

核心工作流

Output schema

输出 Schema

Output contract

输出约定

Exit codes

退出码

Options

选项

Features

功能特性

Common patterns

常见使用场景

Single URL discovery

单URL订阅源发现

Multiple URLs (parallel)

多URL并行处理

Extract all feed URLs

提取所有订阅源URL

Check if feeds exist without parsing

不解析内容，仅检查订阅源是否存在

Custom timeout for slow sites

为慢响应站点设置自定义超时时间

Skip blog scanning for faster results

跳过博客扫描以提升速度

Integration examples

集成示例

Shell script

Shell脚本

No need to redirect stderr - it's clean by default

No need to redirect stderr - it's clean by default

Python

Python

JavaScript/Node.js

JavaScript/Node.js

Why use this tool

为何选择本工具

Testing

测试

More information

更多信息