Skip to content

AI_API_GUIDE.md

Latest commit

 

History

History
234 lines (162 loc) · 4.74 KB

AI_API_GUIDE.md

File metadata and controls

234 lines (162 loc) · 4.74 KB
Raw

RSS API 使用指南（AI 版本）

这是一份给大模型阅读的 API 文档，教你如何调用本地 RSS 接口获取文章数据。

基础信息

API 地址： http://localhost:8000

所有请求方法： GET（除了刷新是 POST）

返回格式： JSON

核心端点

1. 获取文章列表

GET /articles

参数：

参数 类型 必填 说明
category string 否 按分类筛选，需要 URL 编码
limit integer 否 返回数量，默认 50
mode string 否 summary=仅摘要，full=含全文（默认 full）

示例：

# 获取最新 10 篇文章（含全文）
curl "http://localhost:8000/articles?limit=10&mode=full"

# 仅获取摘要，不包含正文（更快、数据量更小）
curl "http://localhost:8000/articles?limit=50&mode=summary"

# 按分类获取
curl "http://localhost:8000/articles?category=L1%20-%20AI%20Core&limit=20"

返回结构：

[
  {
    "id": 1,
    "title": "文章标题",
    "url": "https://原文链接.com",
    "published": "2026-02-09T10:00:00Z",
    "summary": "文章摘要...",
    "content": "完整正文内容（仅 mode=full 时包含）",
    "author": "作者名",
    "source": "RSS源名称",
    "category": "分类名称"
  }
]

2. 获取单篇文章

GET /articles/{article_id}

用途： 获取指定文章的完整内容（包含正文）

示例：

curl "http://localhost:8000/articles/36"

返回结构： 同上，始终包含 content 字段

3. 获取所有分类

GET /categories

用途： 了解有哪些分类、每个分类有多少文章

示例：

curl "http://localhost:8000/categories"

返回结构：

[
  {"name": "L1 - AI Core", "count": 45},
  {"name": "架构与工程素养", "count": 38},
  {"name": "思维", "count": 52}
]

4. 获取所有订阅源

GET /feeds

用途： 了解订阅了哪些 RSS 源

示例：

curl "http://localhost:8000/feeds"

5. 刷新所有文章

POST /refresh

用途： 重新抓取所有 RSS 源的最新文章

示例：

curl -X POST "http://localhost:8000/refresh"

分类列表

当前支持的所有分类：

分类名 说明
L1 - AI Core AI 核心技术
AI应用 AI 应用案例
架构与工程素养 软件架构、工程实践
思维 思考方法、认知模型
底层原理与黑客精神 底层技术、安全
Hardcore Engineering 硬核工程
Vision & Trends 前沿趋势
Blogs 个人博客

AI 使用策略

策略 1：快速浏览

# 先获取摘要模式，快速了解有哪些文章
curl "http://localhost:8000/articles?mode=summary&limit=50"

根据标题和摘要筛选出感兴趣的文章后，再获取全文：

curl "http://localhost:8000/articles/{article_id}"

策略 2：按主题获取

# 只获取 AI 相关内容
curl "http://localhost:8000/articles?category=L1%20-%20AI%20Core&limit=20"

策略 3：生成简报

  1. 获取分类列表：curl "http://localhost:8000/categories"
  2. 每个分类获取 5-10 篇摘要
  3. 根据摘要筛选重要文章
  4. 获取筛选后文章的全文
  5. 总结生成简报

数据字段说明

字段 说明 注意事项
id 文章唯一ID 用于单独获取文章
title 标题 可能为空
url 原文链接 始终存在
published 发布时间 格式不统一，可能为空
summary RSS摘要 来自RSS源，长度限制500字符
content 正文内容 需要解析HTML，可能为空或解析失败
author 作者 大多数情况为空
source RSS源名称 始终存在
category 分类 始终存在

注意事项

  1. 数据时效性：文章在服务启动时抓取，需要调用 /refresh 刷新
  2. content 可能为空：部分网站可能解析失败或反爬虫
  3. URL 编码：分类名称含空格等字符时需要编码（用 %20 替代空格）
  4. 启动时间：服务首次启动需要 1-2 分钟抓取内容
  5. 文章数量：每个 RSS 源最多保存 5 篇文章

快速命令参考

# 获取所有分类
curl "http://localhost:8000/categories"

# 获取 20 篇最新文章摘要
curl "http://localhost:8000/articles?mode=summary&limit=20"

# 获取 AI Core 分类文章
curl "http://localhost:8000/articles?category=L1%20-%20AI%20Core&limit=10"

# 获取指定文章全文
curl "http://localhost:8000/articles/36"

# 刷新所有内容
curl -X POST "http://localhost:8000/refresh"