把注意力，还给
自己选择的内容。

当前版本专注于“本机上的可控阅读”，不会把尚未实现的云端能力包装成已有功能。

需要 Node.js 22.13.0 或更高版本。克隆仓库后安装依赖并启动开发服务器。

git clone https://github.com/BillShiyaoZhang/our-choice.git
cd our-choice
npm install
npm run dev

浏览器打开 http://localhost:3000。文档位于 /docs/。

Mac 版用原生 Swift/WKWebView 包装同一套网站，并内置 Node 22、Vinext 生产产物和浏览器助手；运行应用不要求预装 Node.js 或 Docker。

npm run mac:build
open "build/macos/Our Choice.app"

DEVELOPER_DIR=/Applications/Xcode-beta.app/Contents/Developer npm run mac:package-local
open build/macos/Our-Choice-local-unsigned.pkg

npm run mac:package

浏览器助手通过安装版 Mac 应用每次启动重新生成的短期会话保护本地持久队列，自动发现端口后把内容交给 Mac 应用；Docker / 网页模式仍可使用手工配对。这样避免 Chrome、Safari 与 WKWebView 各自隔离的 localStorage 造成错投。完整产品数据仍使用设置中的 JSON 导入导出显式迁移。架构、签名和双架构验收见 docs/spec/macos-local-app.md。

Chrome、Edge 与 Safari 共用同一套 Manifest V3 源码，可以在用户浏览时收藏当前内容、订阅当前来源，并把 B站关注页中的 UP 主批量送回自选确认。平台登录始终留在原网站，扩展不会读取或保存密码、Cookie 或访问令牌。

B站关注导入

1. 打开个人空间中的“全部关注”页，在扩展中选择“自动扫描全部关注”。
2. 扩展逐页读取已经渲染的公开 MID、昵称和头像；页面内会显示进度，也可以随时取消并保留已扫描结果。
3. 到达最后一页后自动发送，再从 UP 主主页可发现的 9 类固定来源中多选本次范围，随后预览、去重并确认；同一组选择会应用到本次导入的所有 UP 主。仍可使用“开始新一轮 / 扫描本页”手动扫描。

可选范围包括：UP 主图文、投币视频、动态、粉丝、关注用户、点赞视频、用户追番列表、默认收藏夹和投稿；默认只选择投稿。普通添加订阅、浏览器助手单个来源、批量导入及来源设置都使用同一套多选项。确认批量导入后，任务会在独立的右上角进度窗口中继续，可收起、暂停、继续或取消；最多六个账号并行处理，并省去每个 B站账号重复发现内容范围的请求。粉丝与关注用户依赖登录 UID 及自建 RSSHub 的 B站 Cookie 配置；投币、点赞、追番与收藏夹也受目标用户公开设置影响。

扩展处理的数据、保存期限和权限用途见独立的自选助手隐私政策。

订阅、查看时间、新增基线、合集和发现偏好保存在当前浏览器的 localStorage，键名为 our-choice:state:v1；旧版数据会自动迁移到当前数据模型。

• 备份：设置 → 数据与隐私 → 导出，下载 JSON 文件。
• 恢复：在同一区域导入此前导出的 JSON；导入前请确认文件来源。
• 跨标签页：同一站点下的其他标签页会收到存储变化。
• 平台会话：内嵌页面只有在浏览器与平台允许第三方 Cookie 或 Storage Access 时才能沿用登录状态；自选只记录平台地址和最近打开时间，不接触密码或 Cookie 内容。
• 助手连接：安装版使用应用进程短期会话并在重启后自动续连；our-choice:assistant:v1 只为 Docker / 网页模式保存本地配对码，不进入应用状态或 JSON 备份；扩展待处理队列保存在扩展自己的本地存储中。
• 清理提醒：清除浏览器站点数据会删除本地内容，操作前请先导出。

our-choice/
├── app/
│   ├── api/source-preview/route.ts  # 来源获取、发现与解析
│   ├── lib/model.ts                 # 产品类型和种子数据
│   ├── our-choice-app.tsx           # 客户端状态与界面
│   └── globals.css                  # 产品视觉系统
├── docs/
│   ├── assets/                      # 文档样式与渐进增强脚本
│   ├── spec/                        # 文档驱动的功能规格
│   └── index.html                   # 文档站入口
├── browser-extension/               # Chrome / Safari 共用 WebExtension 源码
├── macos/                            # Swift 外壳与本地 Node 代理
├── scripts/                          # 文档、扩展、Mac App 与 PKG 构建
├── tests/                            # 行为和渲染测试
└── .github/workflows/               # GitHub Pages 发布

public/docs/ 是构建前生成的副本，不应直接编辑或提交。

客户端拥有产品状态与来源基线；服务端路由只在预览和刷新时请求来源，不持久化用户订阅。可选浏览器助手在安装版中使用短期原生会话、在 Docker / 网页模式中使用手工配对，把本地扩展队列送入客户端确认；网页收藏直接写入本地合集，来源候选仍必须经过预览接口。配置 RSSHub 后，服务端通过 /api/radar/rules/{domain} 读取同源 Radar 规则并请求匹配的 Feed；实例地址和访问密钥不进入浏览器数据。外部频道和内容通过受限 iframe 在主区域加载，来源平台的会话仍由浏览器管理。响应设置 Cache-Control: no-store。

{
  "url": "https://example.com/feed.xml",
  "limit": 12
}

成功响应

mode: "live" 返回规范化的来源、条目与抓取时间。由 RSSHub 转换的来源还会返回 provider: "rsshub"、原始 refreshUrl 与不含实例地址或密钥的 rsshubRoute。未配置、无规则或转换失败的中文内容平台返回 mode: "link-only"、平台标识、原始链接、空条目列表和明确警告；Bilibili 保留兼容的 BILIBILI_LINK_ONLY 警告。

失败响应

RSSHub 配置

Docker Compose 默认连接同编排中的独立 RSSHub 服务。直接运行应用时设置 RSSHUB_BASE_URL；实例启用访问控制时再设置仅服务端可见的 RSSHUB_ACCESS_KEY。自选不会默认使用公共实例，也不会执行远程 Radar JavaScript。

仓库遵循文档驱动开发和 Red–Green–Refactor：先在 docs/spec/ 记录可观察行为与边界，再添加会因缺失功能而失败的测试，最后实现并重构。

node --test tests/docs-site.test.mjs
npm run lint
npm test

新增测试必须确定、隔离且不依赖真实上游网络。API 测试应使用注入或模拟响应覆盖成功、超时、格式错误与 SSRF 防护。

文档由 GitHub Pages 托管。推送到 main 且改动涉及 docs/** 或工作流时，GitHub Actions 会直接发布 docs/。

1. 在仓库 Settings → Pages 中将 Source 设为 GitHub Actions。
2. 更新 docs/；如行为发生变化，同步更新对应规格和测试。
3. 提交并推送，等待 Deploy documentation to GitHub Pages 完成。
4. 访问 billshiyaozhang.github.io/our-choice/ 验证。

文档站没有外部运行时依赖；.nojekyll 确保文件按原样发布。本地应用则由同步脚本在 /docs/ 提供同一份内容。