rss-agent-discovery

RSS Agent 发现工具

专为 AI Agent 设计的 RSS 订阅源发现工具，提供机器可解析的 JSON 输出。

快速开始

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

输出：

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

核心工作流

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

解析 JSON 输出：

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

输出架构

{
  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
  }]
}

输出约定

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

• 仅向 stdout 输出 JSON（可供机器解析）
• 不向 stderr 输出内容（便于程序处理）
• 所有错误和警告均包含在 JSON 结构中

详细模式（--verbose）：

• 向 stdout 输出 JSON（保持不变）
• 向 stderr 输出调试日志（便于排查问题）
• 提供有关跳过的 URL、验证失败等的额外上下文

推荐的集成模式：

1. 将 stdout 解析为 JSON（即使发生错误，也始终是有效的 JSON）
2. 检查 success 字段，了解整体状态
3. 如果 success === false，检查 partialResults，查看是否找到了订阅源
4. 检查每条结果中的 error 字段，了解特定 URL 的失败情况
5. 检查 diagnostics 数组中的警告和非致命问题
6. 仅在排查问题或调试时使用 --verbose 标志

退出代码

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

在自动化任务中使用退出代码：

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

选项

--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

示例：

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

功能

• 从 HTML <link> 标签中发现订阅源
• 测试常见路径（/rss.xml、/atom、/feed 等）
• 扫描博客子目录（/blog、/news、/articles）
• 并行处理多个 URL
• 对所有来源中的订阅源去重
• 验证订阅源是否确实返回 XML
• 仅向 stdout 输出 JSON（默认输出简洁，不使用 stderr）
• 错误和警告均包含在 JSON 结构中
• 将超时错误统一为一致的“Timeout”消息

常见模式

发现单个 URL

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

多个 URL（并行）

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

提取所有订阅源 URL

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

检查订阅源是否存在，但不解析

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

为响应较慢的网站设置自定义超时时间

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

跳过博客扫描以加快结果返回

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

集成示例

Shell 脚本

#!/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

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

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;

为什么使用此工具

现有的 RSS 发现工具（rss-url-finder、rss-finder）面向人类用户：

• 输出人类可读的文本
• 不会验证订阅源是否存在
• 缺少结构化的机器可读输出

此工具专为 AI Agent 设计：

• 仅向 stdout 输出 JSON（可供机器解析）
• 默认输出简洁（除非启用 --verbose，否则不使用 stderr）
• 所有错误和警告均包含在 JSON 结构中
• 提供语义化退出代码
• 验证订阅源是否返回 XML
• 将超时错误统一为一致的格式
• 发现 AI Agent 容易遗漏的订阅源

测试

测试工具是否正常工作：

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

更多信息

• NPM：https://www.npmjs.com/package/rss-agent-discovery
• GitHub：https://github.com/brooksy4503/rss-agent-discovery