Feedio RSS 协议（JSON）

面向视频 Feed 的 JSON 订阅协议。

1. 概述

Feedio RSS 是一种面向「视频 Feed 流」的 JSON 订阅协议。它与传统 RSS/Atom（XML）不同，原生包含：视频条目（items）、发布者（creator）、以及面向应用的元数据（封面、时长、平台标识、深链等）。

2. 传输与版本

建议通过 HTTPS 提供。建议 Content-Type：application/feedio+json；charset=utf-8。

版本字段：feedio_version（例如 "1.0"）。向后兼容：新增字段不得破坏已有字段语义；客户端应忽略未知字段。

3. 顶层结构

字段	类型	必填	说明
feedio_version	string	是	协议版本
type	string	是	固定为 "feed"
generated_at	string (ISO8601)	是	生成时间
source	object	是	来源信息
items	array<Item>	是	条目列表（可分页）
paging	object	否	分页信息
extensions	object	否	扩展字段

4. Source 对象

字段	类型	必填	说明
id	string	是	来源唯一 ID（稳定）
title	string	是	来源名称
feed_url	string (url)	是	该 Feedio RSS 地址
site_url	string (url)	否	网站/频道主页
icon_url	string (url)	否	来源图标（推荐 64×64 或 128×128）
avatar_url	string (url)	否	来源头像
description	string	否	来源介绍/描述
language	string	否	BCP-47，例如 zh-CN/en
categories	array<string>	否	主题标签
update_hint	object	否	更新提示（频率/缓存）

5. Item 对象（视频条目）

字段	类型	必填	说明
id	string	是	条目唯一 ID（稳定）。建议使用 guid 或 link hash。
title	string	是	标题
url	string (url)	是	播放/落地页链接
published_at	string (ISO8601)	是	发布时间
source_id	string	是	所属来源 id
summary	string	否	摘要/描述（短）
cover	object	否	封面信息
media	object	否	媒体信息（时长/类型/清晰度等）
creator	object<CreatorRef>	否	发布者（PO 主）。缺失则无法关注。
deeplink	object	否	深链信息（可选）
actions_hint	object	否	交互提示（是否可点赞/收藏/稍后看）

5.1 cover 对象

字段	类型	必填	说明
url	string (url)	是	封面 URL
width	number	否	像素宽
height	number	否	像素高
blurhash	string	否	占位模糊哈希（可选）

5.2 media 对象

字段	类型	必填	说明
url	string (url)	否	视频直链 URL（如 .mp4）
type	string	否	例如 "video"
duration_ms	number	否	时长（毫秒）
mime	string	否	媒体 MIME（如 video/mp4）
has_audio	boolean	否	是否含音频
formats	array<object>	否	清晰度/码率列表（可选）

6. Creator / PO 主对象

字段	类型	必填	说明
id	string	是	发布者唯一 ID（稳定）
name	string	是	显示名称
profile_url	string (url)	否	主页链接
avatar_url	string (url)	否	头像
platform	string	否	平台标识（如 youtube/bilibili/site）

Item 中的 creator 可仅包含 id+name（最小），其余字段可省略。

7. Actions Hint（能力提示）

Actions Hint 用于说明该条目在客户端是否允许 Like/Save/Later/Follow。Follow 是否可用通常取决于 creator 是否存在。客户端也可忽略该字段，默认允许 Like/Save/Later。

示例对象：

{
  "can_like": true,
  "can_save": true,
  "can_later": true,
  "can_follow_creator": true
}

字段定义：

can_like (boolean, optional): 是否允许点赞
can_save (boolean, optional): 是否允许收藏
can_later (boolean, optional): 是否允许稍后看
can_follow_creator (boolean, optional): 是否允许关注（通常= creator 存在）

8. Paging（分页）

字段	类型	必填	说明
cursor	string	否	当前游标
next_cursor	string	否	下一页游标
has_more	boolean	否	是否还有更多

9. 去重与稳定性规则

Item.id 必须稳定且唯一。建议优先使用原始 guid；若无 guid，可用 url 的规范化哈希。
published_at 建议使用 ISO8601（UTC 或带时区）。
客户端应忽略未知字段；服务端新增字段需向后兼容。

10. 订阅导入与分享格式

本节不是 Feed 文档本体的一部分，但用于统一扫码与 Scheme 导入。

用途	格式	示例
单 Feed URL	纯 URL	https://example.com/feedio.json
Scheme 导入（单源）	feedio://import?url=<encoded>	feedio://import?url=https%3A%2F%2Fexample.com%2Ffeedio.json
Scheme 导入（多源）	feedio://import?urls=<comma>	feedio://import?urls=https%3A%2F%2Fa.com%2Ff.json,https%3A%2F%2Fb.com%2Ff.json

11. 示例

{
  "feedio_version": "1.0",
  "type": "feed",
  "generated_at": "2026-02-21T12:00:00Z",
  "source": {
    "id": "source_tech_daily",
    "title": "Tech Daily",
    "feed_url": "https://example.com/feedio/tech-daily.json",
    "icon_url": "https://example.com/icons/tech-daily.png",
    "description": "每日科技资讯与深度解读。"
  },
  "items": [
    {
      "id": "item_20260221_001",
      "title": "AI Chips Explained in 8 Minutes",
      "url": "https://example.com/watch/ai-chips",
      "published_at": "2026-02-21T08:30:00Z",
      "source_id": "source_tech_daily",
      "cover": {
        "url": "https://example.com/covers/ai-chips.jpg"
      },
      "media": {
        "url": "https://example.com/videos/ai-chips.mp4",
        "type": "video",
        "duration_ms": 480000
      },
      "creator": {
        "id": "creator_jane_doe",
        "name": "Jane Doe"
      },
      "actions_hint": {
        "can_like": true,
        "can_save": true,
        "can_later": true,
        "can_follow_creator": true
      }
    }
  ],
  "paging": {
    "next_cursor": "c1",
    "has_more": true
  }
}

12. 客户端行为要求（摘要）

若 Item.creator 缺失，则 UI 不提供 Follow Creator（隐藏或置灰）。
Like/Save/Later 为客户端本地动作（或与账号同步），不要求在 Feed 文档中回传。
收藏（Save）与稍后看（Later）必须独立，允许同一条目同时存在。