feedscope 0.1.0__tar.gz → 0.2.0__tar.gz

{feedscope-0.1.0 → feedscope-0.2.0}/.github/workflows/ci.yml

@@ -9,8 +9,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
       - run: uv sync
       - run: uv run ruff check src/ tests/ scripts/
       - run: uv run mypy
@@ -26,8 +26,8 @@ jobs:
         python-version: ["3.11", "3.12", "3.13"]
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
         with:
           python-version: ${{ matrix.python-version }}
       - run: uv sync --python ${{ matrix.python-version }}
@@ -40,10 +40,10 @@ jobs:
     # 打包配置随时可构建：pyproject 的 packaging 回归在这里红，而不是发版当天才炸
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
       - run: uv build
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist-preview
           path: dist/

{feedscope-0.1.0 → feedscope-0.2.0}/.github/workflows/release.yml

@@ -16,10 +16,10 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v7
       - run: uv build    # sdist + wheel; version is read from src/feedscope/__init__.py
-      - uses: actions/upload-artifact@v4
+      - uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -32,7 +32,7 @@ jobs:
     permissions:
       id-token: write    # OIDC trusted publishing — no PyPI token stored anywhere
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -44,7 +44,7 @@ jobs:
     permissions:
       contents: write
     steps:
-      - uses: actions/download-artifact@v4
+      - uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

{feedscope-0.1.0 → feedscope-0.2.0}/.gitignore

@@ -8,6 +8,8 @@ dist/
 .DS_Store
 .zcode/
 .screenshot-sources.toml
+.screenshot-state.json
+.screenshot-feeds/
 .coverage
 coverage*.xml
 cmp/

{feedscope-0.1.0 → feedscope-0.2.0}/CHANGELOG.md

@@ -5,6 +5,21 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.2.0] - 2026-11-08
+
+### Added
+
+- Read/unread state: the row-leading `●` marks an item unread and clears when you open it (Enter into detail, `Ctrl+O` to the browser, `←`/`→` article stepping in a detail); `Ctrl+R` toggles the current item; unread persists across refreshes and restarts in a plain-text `state.json` (item ids and timestamps only, no credentials, 10k-entry FIFO cap), while the "N new" count of first-seen items shows in the status line
+- Favorites / read-later: `Ctrl+F` stars the current item from the list or while reading, `F3` opens the cross-source favorites list (newest first, Enter fetches latest comments from the original source); a full snapshot is stored in `favorites.json` so items stay readable after they leave the feeds, favorited entries are exempt from the read-state cap, and `feedscope favorites [export [file.md]]` lists / exports them as Markdown
+- Source-tag column for mixed lists: the RSS / Telegram "All" aggregate streams label each row's origin (feed / channel name) in a dedicated left-aligned column instead of prefixing it into the right-aligned meta column, which made column edges ragged; the favorites list shows the item's source the same way (a favorited aggregate item shows its feed/channel name)
+- Offline list cache: each feed is cached to its own JSON file (200 items per feed, 60 most recent feeds kept); startup and refresh paint the cache first (instant restarts), and a failed refresh keeps the old list on screen instead of clearing it — RSS / Telegram detail bodies travel with the cached list and read offline
+
+### Fixed
+
+- The unread dot was invisible on the selected row: the highlight background and the dot both use the editor blue (blue-on-blue). On a highlighted row the dot now follows the selection text color; in the sidebar-focused state (highlight suppressed, no blue band) it keeps the editor blue
+
 ## [0.1.0] - 2026-11-07
 
 Initial release.
@@ -22,4 +37,5 @@ Initial release.
 - Editor-inspired VS Code Dark+ theme; every keybinding is a non-printing key (works while an IME is active); top tab bar and sidebar are clickable
 - Layout-change self-check: 0 items parsed → immediate "site may have changed" error; `feedscope probe` inspects all sources with raw samples saved to disk; `feedscope doctor` environment self-check; `feedscope rss` CLI for subscription management
 
+[0.2.0]: https://github.com/howardli/FeedScope/releases/tag/v0.2.0
 [0.1.0]: https://github.com/howardli/FeedScope/releases/tag/v0.1.0

{feedscope-0.1.0 → feedscope-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: feedscope
-Version: 0.1.0
+Version: 0.2.0
 Summary: FeedScope (观流): a terminal feed reader — Zhihu / X / Reddit / HN / V2EX / RSS / Telegram, all in one terminal
 Project-URL: Homepage, https://github.com/howardli/FeedScope
 Project-URL: Repository, https://github.com/howardli/FeedScope
@@ -51,6 +51,8 @@ Zhihu Hot → X timeline → post detail (auto translation, quoted post) → Red
 - **Multi-source aggregation**: Zhihu Hot / Recommend / Following, X For You / Following, Reddit Home / Popular / custom subreddits, HN Front / New / Ask / Show, V2EX Hot / Latest, Telegram channel subscriptions — one UI, `Tab` to switch
 - **RSS subscriptions**: any RSS / Atom feed; the "All" stream merges by publish time (cross-feed dedup, a dead feed never drags others down); read feed-provided full text in-terminal; conditional requests keep refreshes polite to sources
 - **Full in-terminal reading**: feed → question → answers → comments, loaded per layer on demand
+- **Read state & offline**: the row-leading `●` marks an item unread and clears when you open it (`Ctrl+R` toggles back) — refreshes and restarts never touch it; the "N new" count lives in the status line; lists are cached locally, so restarts paint instantly and offline keeps them readable (RSS / Telegram details read offline too)
+- **Favorites / read-later**: `Ctrl+F` stars the current item (from the list or while reading), `F3` opens the cross-source list; a full snapshot is stored — items stay readable after they scroll off hot lists or get deleted, and `feedscope favorites export` takes them with you (no lock-in)
 - **HN discussion tree**: top-level comments as floors, reply trees one `Enter` deeper; deeply nested threads are flattened to two levels with `@parent` prefixes preserving who-replies-to-whom
 - **Auto Grok translation for foreign posts on X**; media markers `[图片]` / `[视频]` are clickable links to the original image / video
 - **Login loop**: in-app Chrome QR / password login when a source needs it; `Ctrl+U` to switch accounts
@@ -139,6 +141,9 @@ feedscope
 | `Enter` | Open detail; inside a detail, open the discussion layer of the floor you are reading; return to the list from the sidebar / source bar |
 | `Ctrl+N` | Load more (list / floors / comments, each layer independently) |
 | `Ctrl+O` | Open current item in browser |
+| `Ctrl+R` | Toggle read / unread on the current item (mark it unread to revisit) |
+| `Ctrl+F` | Favorite / unfavorite the current item (works while reading too) |
+| `F3` | Favorites list: cross-source, newest first; Enter opens detail, Ctrl+F unfavorites |
 | `F5` | Refresh |
 | `Ctrl+U` | Account: login / logout |
 | `Ctrl+L` | UI language: pick and save; restart `feedscope` to apply |
@@ -148,6 +153,22 @@ feedscope
 
 All keys are non-printing — they work while a Chinese IME is active; typing printable characters by mistake shows a hint. The top tab bar and the left sidebar are clickable and drive the same code path as the keyboard. Arrow keys follow CLI conventions: `↑`/`↓` move the selection within the current list; `↑` on the first row of any region climbs to the source bar (the top region sits above everything), and `↓` from the source bar descends to the sidebar (inverse of the sidebar's first-feed `↑`); other region moves are horizontal — in the source bar `←`/`→` switches site in place; in the sidebar `↑`/`↓` switches feed in place, `→` returns to the list and `←` goes to the source bar; in the list `←` enters the sidebar (staying on the current feed) and `→` hits the right edge; `Enter` / `Esc` return to the list at any time. Dialogs (source manager / subscriptions / input / confirm / account) support the same arrow-key focus movement: `↓` past the bottom of the list enters the button row, `↑` returns to the list, `←`/`→` move between buttons, and `Enter` presses the focused button.
 
+### Read state & offline
+
+The dot column on each row tracks reading state: `●` unread (editor blue), blank = read. Unread is persistent — refreshes, feed switches and restarts never touch it; the dot only clears when you open the item (`Enter` into detail, `Ctrl+O` to the browser, or `←`/`→` article-stepping inside a detail). `Ctrl+R` toggles the current item — mark it unread to revisit. How many items arrived with this refresh shows as a count in the status line ("N items · M new"), not as row-level marks.
+
+Favorites (`Ctrl+F`) store a **full snapshot at the moment of starring** (title/link/meta, and the body for RSS / Telegram) — items stay readable after they scroll off hot lists or get deleted. The `F3` list reads snapshots with zero requests (works offline); Enter fetches the latest comments from the original source. Favorited entries are exempt from the read-state cap; `feedscope favorites` lists them in the terminal and `feedscope favorites export [file.md]` exports Markdown to take them anywhere.
+
+Both live in plain local files (delete to reset; no credentials involved):
+
+| File | Contents |
+| --- | --- |
+| `state.json` (platform state dir, `~/.local/state/feedscope/` on Linux) | read/seen/favorite item ids with timestamps (capped at 10k entries, oldest evicted first; favorites exempt) |
+| `favorites.json` (same state dir) | full snapshots of favorited items (user-curated data, never pruned) |
+| `feeds/` (platform cache dir, `~/.cache/feedscope/feeds/` on Linux) | one JSON list cache per feed (200 items per feed, 60 most recent feeds kept) |
+
+Startup and refresh paint the cache before fetching: restarts show the list instantly; offline or a broken site keeps the old content readable, and RSS / Telegram detail bodies travel with the cached list. `feedscope doctor` reports the state-file location.
+
 ### UI Language
 
 The first launch asks for the language (pre-selected from your system locale; `Enter` to confirm, `Esc` keeps the default). Change it anytime with `Ctrl+L`; the choice is saved to the config and **takes effect when you restart `feedscope`** (counts and unit words are baked into fetched data in the process language, so a fixed-per-process language is the most robust model). **English is the default when no language is configured** — 中文用户在首启回车即选简体中文，或 `Ctrl+L` 随时切换。Subcommands (`doctor` / `probe` / `rss` / `login`) follow the same language as the TUI:
@@ -186,6 +207,7 @@ feedscope doctor          # environment self-check (Chrome / profile / config)
 feedscope rss add <url> [--key k --label name]  # add: feed URL / site homepage (auto-discovered) / OPML path
 feedscope rss list | remove <key>               # list / remove subscriptions
 feedscope rss import <x.opml> | export [x.opml] # bulk import (idempotent merge) / export
+feedscope favorites [export [x.md]]             # list favorites / export as Markdown (no lock-in)
 ```
 
 ### Source & Feed Config
@@ -276,7 +298,7 @@ No login; data comes from each channel's public web preview (`t.me/s/<channel>`,
 
 - Pure subscription source shaped exactly like RSS: `F2` → Telegram row → `→` opens the manager; type a channel name or link (`durov`, `@durov`, `t.me/durov`, even a post link); label defaults to the channel's own name
 - The "All" stream merges every channel by publish time (newest first), one dead channel only loses its own items; each channel is also its own feed (individually hideable)
-- Meta column "N views" is the channel-post heat radar; the "All" stream prefixes the channel name; inline HTML becomes markdown, images/videos become `[图片]` / `[视频]` markers (videos have no direct link — the marker points to the post page)
+- Meta column "N views" is the channel-post heat radar; the "All" stream labels each row's origin in a dedicated source-tag column (same as the favorites list); inline HTML becomes markdown, images/videos become `[图片]` / `[视频]` markers (videos have no direct link — the marker points to the post page)
 - Details read list-carried content (zero requests); `Ctrl+N` in a single-channel feed pages back through history via the `?before=` cursor; no comment layer (channel discussion groups aren't in the preview)
 
 ## Community

{feedscope-0.1.0 → feedscope-0.2.0}/README.md

@@ -20,6 +20,8 @@ Zhihu Hot → X timeline → post detail (auto translation, quoted post) → Red
 - **Multi-source aggregation**: Zhihu Hot / Recommend / Following, X For You / Following, Reddit Home / Popular / custom subreddits, HN Front / New / Ask / Show, V2EX Hot / Latest, Telegram channel subscriptions — one UI, `Tab` to switch
 - **RSS subscriptions**: any RSS / Atom feed; the "All" stream merges by publish time (cross-feed dedup, a dead feed never drags others down); read feed-provided full text in-terminal; conditional requests keep refreshes polite to sources
 - **Full in-terminal reading**: feed → question → answers → comments, loaded per layer on demand
+- **Read state & offline**: the row-leading `●` marks an item unread and clears when you open it (`Ctrl+R` toggles back) — refreshes and restarts never touch it; the "N new" count lives in the status line; lists are cached locally, so restarts paint instantly and offline keeps them readable (RSS / Telegram details read offline too)
+- **Favorites / read-later**: `Ctrl+F` stars the current item (from the list or while reading), `F3` opens the cross-source list; a full snapshot is stored — items stay readable after they scroll off hot lists or get deleted, and `feedscope favorites export` takes them with you (no lock-in)
 - **HN discussion tree**: top-level comments as floors, reply trees one `Enter` deeper; deeply nested threads are flattened to two levels with `@parent` prefixes preserving who-replies-to-whom
 - **Auto Grok translation for foreign posts on X**; media markers `[图片]` / `[视频]` are clickable links to the original image / video
 - **Login loop**: in-app Chrome QR / password login when a source needs it; `Ctrl+U` to switch accounts
@@ -108,6 +110,9 @@ feedscope
 | `Enter` | Open detail; inside a detail, open the discussion layer of the floor you are reading; return to the list from the sidebar / source bar |
 | `Ctrl+N` | Load more (list / floors / comments, each layer independently) |
 | `Ctrl+O` | Open current item in browser |
+| `Ctrl+R` | Toggle read / unread on the current item (mark it unread to revisit) |
+| `Ctrl+F` | Favorite / unfavorite the current item (works while reading too) |
+| `F3` | Favorites list: cross-source, newest first; Enter opens detail, Ctrl+F unfavorites |
 | `F5` | Refresh |
 | `Ctrl+U` | Account: login / logout |
 | `Ctrl+L` | UI language: pick and save; restart `feedscope` to apply |
@@ -117,6 +122,22 @@ feedscope
 
 All keys are non-printing — they work while a Chinese IME is active; typing printable characters by mistake shows a hint. The top tab bar and the left sidebar are clickable and drive the same code path as the keyboard. Arrow keys follow CLI conventions: `↑`/`↓` move the selection within the current list; `↑` on the first row of any region climbs to the source bar (the top region sits above everything), and `↓` from the source bar descends to the sidebar (inverse of the sidebar's first-feed `↑`); other region moves are horizontal — in the source bar `←`/`→` switches site in place; in the sidebar `↑`/`↓` switches feed in place, `→` returns to the list and `←` goes to the source bar; in the list `←` enters the sidebar (staying on the current feed) and `→` hits the right edge; `Enter` / `Esc` return to the list at any time. Dialogs (source manager / subscriptions / input / confirm / account) support the same arrow-key focus movement: `↓` past the bottom of the list enters the button row, `↑` returns to the list, `←`/`→` move between buttons, and `Enter` presses the focused button.
 
+### Read state & offline
+
+The dot column on each row tracks reading state: `●` unread (editor blue), blank = read. Unread is persistent — refreshes, feed switches and restarts never touch it; the dot only clears when you open the item (`Enter` into detail, `Ctrl+O` to the browser, or `←`/`→` article-stepping inside a detail). `Ctrl+R` toggles the current item — mark it unread to revisit. How many items arrived with this refresh shows as a count in the status line ("N items · M new"), not as row-level marks.
+
+Favorites (`Ctrl+F`) store a **full snapshot at the moment of starring** (title/link/meta, and the body for RSS / Telegram) — items stay readable after they scroll off hot lists or get deleted. The `F3` list reads snapshots with zero requests (works offline); Enter fetches the latest comments from the original source. Favorited entries are exempt from the read-state cap; `feedscope favorites` lists them in the terminal and `feedscope favorites export [file.md]` exports Markdown to take them anywhere.
+
+Both live in plain local files (delete to reset; no credentials involved):
+
+| File | Contents |
+| --- | --- |
+| `state.json` (platform state dir, `~/.local/state/feedscope/` on Linux) | read/seen/favorite item ids with timestamps (capped at 10k entries, oldest evicted first; favorites exempt) |
+| `favorites.json` (same state dir) | full snapshots of favorited items (user-curated data, never pruned) |
+| `feeds/` (platform cache dir, `~/.cache/feedscope/feeds/` on Linux) | one JSON list cache per feed (200 items per feed, 60 most recent feeds kept) |
+
+Startup and refresh paint the cache before fetching: restarts show the list instantly; offline or a broken site keeps the old content readable, and RSS / Telegram detail bodies travel with the cached list. `feedscope doctor` reports the state-file location.
+
 ### UI Language
 
 The first launch asks for the language (pre-selected from your system locale; `Enter` to confirm, `Esc` keeps the default). Change it anytime with `Ctrl+L`; the choice is saved to the config and **takes effect when you restart `feedscope`** (counts and unit words are baked into fetched data in the process language, so a fixed-per-process language is the most robust model). **English is the default when no language is configured** — 中文用户在首启回车即选简体中文，或 `Ctrl+L` 随时切换。Subcommands (`doctor` / `probe` / `rss` / `login`) follow the same language as the TUI:
@@ -155,6 +176,7 @@ feedscope doctor          # environment self-check (Chrome / profile / config)
 feedscope rss add <url> [--key k --label name]  # add: feed URL / site homepage (auto-discovered) / OPML path
 feedscope rss list | remove <key>               # list / remove subscriptions
 feedscope rss import <x.opml> | export [x.opml] # bulk import (idempotent merge) / export
+feedscope favorites [export [x.md]]             # list favorites / export as Markdown (no lock-in)
 ```
 
 ### Source & Feed Config
@@ -245,7 +267,7 @@ No login; data comes from each channel's public web preview (`t.me/s/<channel>`,
 
 - Pure subscription source shaped exactly like RSS: `F2` → Telegram row → `→` opens the manager; type a channel name or link (`durov`, `@durov`, `t.me/durov`, even a post link); label defaults to the channel's own name
 - The "All" stream merges every channel by publish time (newest first), one dead channel only loses its own items; each channel is also its own feed (individually hideable)
-- Meta column "N views" is the channel-post heat radar; the "All" stream prefixes the channel name; inline HTML becomes markdown, images/videos become `[图片]` / `[视频]` markers (videos have no direct link — the marker points to the post page)
+- Meta column "N views" is the channel-post heat radar; the "All" stream labels each row's origin in a dedicated source-tag column (same as the favorites list); inline HTML becomes markdown, images/videos become `[图片]` / `[视频]` markers (videos have no direct link — the marker points to the post page)
 - Details read list-carried content (zero requests); `Ctrl+N` in a single-channel feed pages back through history via the `?before=` cursor; no comment layer (channel discussion groups aren't in the preview)
 
 ## Community

{feedscope-0.1.0 → feedscope-0.2.0}/README.zh-CN.md

@@ -20,6 +20,8 @@
 - **多源聚合**：知乎热榜 / 推荐 / 关注，X 推荐 / 正在关注，Reddit 首页 / 热门 / 自选 subreddit，HN 首页 / 最新 / Ask / Show，V2EX 热门 / 最新，Telegram 频道订阅，一个界面切换
 - **RSS 订阅**：任意 RSS / Atom 源，「全部」流按时间合并（跨订阅去重、单源失败不拖垮），终端内读 feed 自带全文，条件请求刷新对源友好
 - **终端内完整阅读**：信息流 → 问题 → 回答 → 评论，逐层按需加载
+- **已读与未读**：行首 `●` 标未读，打开即灭（`Ctrl+R` 可改回），刷新/重启都不动它；「N 新」计数在顶部状态行；列表缓存本地，重启秒开、断网可翻（RSS / Telegram 详情离线可读）
+- **收藏/稍后读**：`Ctrl+F` 收藏（列表或阅读中都行），`F3` 看跨源收藏列表；存全量快照——条目从热榜流走、回答被删之后仍可读，`feedscope favorites export` 随时带走防锁定
 - **HN 讨论树**：顶层评论当楼层、回复树再深一层（`Enter`），深层嵌套拍平两层、`@父作者` 标出回复指向
 - **X 外文推自动附 Grok 译文**，媒体记号 `[图片]` / `[视频]` 可点击直达原图 / 视频直链
 - **登录闭环**：未登录自动弹 Chrome 扫码 / 输密码，`Ctrl+U` 一键登出换账号
@@ -108,6 +110,9 @@ feedscope
 | `Enter` | 进详情；详情屏内进「正在阅读」的那个楼层（回答 / 评论）的讨论层；边栏 / 源栏聚焦时回列表 |
 | `Ctrl+N` | 加载更多（列表 / 楼层 / 评论，逐层各自生效） |
 | `Ctrl+O` | 浏览器打开当前条目 |
+| `Ctrl+R` | 当前条目已读 / 未读切换（想重看的标回未读） |
+| `Ctrl+F` | 收藏 / 取消收藏当前条目（阅读中也生效） |
+| `F3` | 收藏列表：跨源按收藏时间倒序，Enter 进详情，Ctrl+F 取消 |
 | `F5` | 刷新 |
 | `Ctrl+U` | 账号：登录 / 登出 |
 | `Ctrl+L` | 界面语言：选择后保存，重启 `feedscope` 生效 |
@@ -117,6 +122,22 @@ feedscope
 
 键位全部为非打印键，输入法中文状态照常可用；误把中文打进来会弹提示。顶部 tab 条与左侧边栏可点击，与键盘走同一条路径。方向键按 CLI 惯例处理：`↑`/`↓` 在当前列表里移动选中；任何区域的首行再 `↑` 都上探源栏（顶部区域在所有内容之上），源栏 `↓` 下探边栏（与边栏首流 `↑` 互逆）；其余区域移动走横向——源栏里 `←`/`→` 就地切站，边栏里 `↑`/`↓` 就地切流、`→` 回列表、`←` 去源栏，列表里 `←` 进边栏（停当前流）、`→` 抵右缘；`Enter` / `Esc` 随时回列表。弹层（源管理 / 订阅管理 / 输入 / 确认 / 账号）里方向键同样移动焦点：列表到底再 `↓` 进按钮行、`↑` 返回列表、`←`/`→` 在按钮间平移、`Enter` 按下聚焦的按钮。
 
+### 已读与离线
+
+行首圆点标记阅读状态：`●` 未读（编辑器蓝）、空白 = 已读。未读是持久状态——刷新、切流、重启都不会动它，圆点只随「打开」消失（`Enter` 进详情、`Ctrl+O` 开浏览器、详情屏 `←`/`→` 换篇都算）；`Ctrl+R` 手动切换当前条目，想重看的标回未读。本次刷新首见几条会计数在顶部状态行（「N 条 · M 新」），不做行级标记。
+
+收藏（`Ctrl+F`）存的是**收藏那一刻的全量快照**（标题/链接/元信息，RSS / Telegram 连正文一起）——条目从热榜流走、回答被删之后收藏仍可读；`F3` 列表读快照零请求、离线可用，Enter 才按原源在线抓最新评论。收藏条目豁免已读状态的淘汰；`feedscope favorites` 终端看列表、`feedscope favorites export [x.md]` 导出 Markdown 随时带走。
+
+状态与缓存都是本机纯文本文件（删掉即重置，不含任何凭据）：
+
+| 文件 | 内容 |
+| --- | --- |
+| `state.json`（状态目录，Linux 为 `~/.local/state/feedscope/`） | 已读/已见/收藏条目 id 与时间戳（上限一万条按最旧淘汰；收藏条目豁免） |
+| `favorites.json`（同状态目录） | 收藏条目的全量快照（用户数据，永不淘汰） |
+| `feeds/`（缓存目录，Linux 为 `~/.cache/feedscope/feeds/`） | 每流一个 JSON 的列表缓存（每流 200 条、留最近 60 流） |
+
+启动或刷新先画缓存再抓新数据：重启秒开列表；断网或站点改版时旧内容保留可翻，RSS / Telegram 的详情正文随列表缓存离线可读。`feedscope doctor` 会列出状态文件位置。
+
 ### 界面语言
 
 首启先弹语言选择（预选跟随系统语言，`Enter` 确认、`Esc` 沿用默认），之后 `Ctrl+L` 随时修改；修改保存到配置后**重启 `feedscope` 生效**（数字/单位等文案在抓取时就随语言烙进数据，语言随进程固定是最稳的模型）。**未配置语言时默认英文**——中文用户首启直接回车选简体中文，或 `Ctrl+L` 随时切换。子命令（`doctor` / `probe` / `rss` / `login`）的输出与 TUI 同语言：
@@ -155,6 +176,7 @@ feedscope doctor          # 环境自检（Chrome / profile / 配置）
 feedscope rss add <url> [--key k --label 名]  # 加订阅：feed 直链 / 站点首页（自动发现）/ OPML 路径
 feedscope rss list | remove <key>             # 查看 / 删除订阅
 feedscope rss import <x.opml> | export [x.opml]  # OPML 批量迁入（幂等合并）/ 导出
+feedscope favorites [export [x.md]]           # 收藏列表 / 导出 Markdown（防锁定）
 ```
 
 ### 源与信息流配置
@@ -245,7 +267,7 @@ hide = ["all"]       # 可隐藏「全部」聚合流，或填订阅 key 隐藏
 
 - 与 RSS 同形的纯订阅源：`F2` → Telegram 行按 `→` 进订阅管理，输入频道名或链接（`durov`、`@durov`、`t.me/durov`、帖子直链都认），显示名缺省拉频道名
 - 「全部」流 = 全部频道按发布时间倒序合并，单频道失败只损失自己的条目；每频道也各自成流（可 `hide` 单藏）
-- 元信息列「N 观看」是频道帖的热度雷达；「全部」流里前缀频道名；正文行内 HTML 转 markdown、图片/视频换 `[图片]` / `[视频]` 记号（视频无直链，记号指向帖子页）
+- 元信息列「N 观看」是频道帖的热度雷达；「全部」流里每行带源名列标频道名（与收藏列表同款，出处成列不挤元信息）；正文行内 HTML 转 markdown、图片/视频换 `[图片]` / `[视频]` 记号（视频无直链，记号指向帖子页）
 - 详情读列表自带正文（零请求）；单频道流 `Ctrl+N` 走 `?before=` 游标往回翻历史帖；无评论层（频道讨论组在预览页拿不到）
 
 ## 社区

{feedscope-0.1.0 → feedscope-0.2.0}/SECURITY.md

@@ -13,6 +13,9 @@ where the sensitive bits live, so you can audit that claim:
 | --- | --- | --- |
 | User config | `sources.toml` in your platform config dir (`~/.config/feedscope/` on Linux, `~/Library/Application Support/feedscope/` on macOS) | No — language, enabled sources, subscriptions only |
 | Browser profile | `chromium-profile/` in your platform cache dir (`~/.cache/feedscope/` on Linux, `~/Library/Caches/feedscope/` on macOS) | **Yes** — Chrome profile with your Zhihu / X / Reddit session cookies |
+| Read state | `state.json` in your platform state dir (`~/.local/state/feedscope/` on Linux) | No — item ids and timestamps only |
+| Favorites | `favorites.json` next to `state.json` | No — snapshots (title/link/body) of public items you starred |
+| List cache | `feeds/` next to the browser profile in your platform cache dir | No — titles, links and bodies of the public feeds you subscribe to |
 
 Guarantees:
 

{feedscope-0.1.0 → feedscope-0.2.0}/scripts/demo_gif.py

@@ -93,10 +93,20 @@ def main() -> None:
     from feedscope.core.registry import install_sources, source_classes
     from feedscope.ui import app as app_mod
 
-    # 隔离本机用户配置（与 screenshot.main 同一套路：避开首启引导 / 隐藏流漂移 / 真 Chrome 预热）
+    # 隔离本机用户配置（与 screenshot.main 同一套路：避开首启引导 / 隐藏流漂移 / 真 Chrome 预热）。
+    # 状态/缓存同样钉住并先清：GIF 想要「首跑全 ● → Enter 逐条清点」的叙事，
+    # 上一次运行的残留已读会让首帧就带空点
     cfg = DOCS.parent / ".screenshot-sources.toml"
     cfg.write_text('enabled = ["zhihu", "x", "reddit", "hn", "v2ex"]\n', encoding="utf-8")
+    state = DOCS.parent / ".screenshot-state.json"
+    state.unlink(missing_ok=True)
+    cache = DOCS.parent / ".screenshot-feeds"
+    if cache.exists():
+        for p in cache.iterdir():
+            p.unlink()
     os.environ["FEEDSCOPE_CONFIG"] = str(cfg)
+    os.environ["FEEDSCOPE_STATE"] = str(state)
+    os.environ["FEEDSCOPE_FEED_CACHE"] = str(cache)
     os.environ["FEEDSCOPE_NO_PREWARM"] = "1"
 
     frames: list[Path] = []

{feedscope-0.1.0 → feedscope-0.2.0}/scripts/screenshot.py

@@ -746,6 +746,7 @@ async def _shots() -> None:
         for _ in range(6):
             await pilot.pause()
         DOCS.mkdir(exist_ok=True)
+        await _demo_read_mix(app, pilot)
         _emit(app, "screenshot-zhihu")
         await pilot.press("tab")  # Tab 切到 X
         for _ in range(6):
@@ -753,6 +754,7 @@ async def _shots() -> None:
         await pilot.press("enter")  # 切站落边栏：Enter 回列表
         for _ in range(2):
             await pilot.pause()
+        await _demo_read_mix(app, pilot)
         _emit(app, "screenshot-x")
         await pilot.press("enter")  # 进首条推文详情（外文 + 译文 + 引用块）
         for _ in range(8):
@@ -765,6 +767,7 @@ async def _shots() -> None:
         await pilot.press("enter")  # 切站落边栏：Enter 回列表
         for _ in range(2):
             await pilot.pause()
+        await _demo_read_mix(app, pilot)
         _emit(app, "screenshot-reddit")
         await pilot.press("enter")  # 进帖子详情（markdown 自述 + 置顶/赞数评论楼层）
         for _ in range(8):
@@ -777,6 +780,7 @@ async def _shots() -> None:
         await pilot.press("enter")  # 切站落边栏：Enter 回列表
         for _ in range(2):
             await pilot.pause()
+        await _demo_read_mix(app, pilot)
         _emit(app, "screenshot-hn")
         await pilot.press("enter")  # 进 story 详情（原文一行 + 评论楼层）
         for _ in range(8):
@@ -794,6 +798,7 @@ async def _shots() -> None:
         await pilot.press("enter")  # 切站落边栏：Enter 回列表
         for _ in range(2):
             await pilot.pause()
+        await _demo_read_mix(app, pilot)
         _emit(app, "screenshot-v2ex")
         await pilot.press("enter")  # 进主题详情（markdown 正文 + 回复楼层）
         for _ in range(8):
@@ -801,6 +806,22 @@ async def _shots() -> None:
         _emit(app, "screenshot-v2ex-detail")
 
 
+async def _demo_read_mix(app: app_mod.FeedScopeApp, pilot) -> None:
+    """列表截图的已读混合态：每隔三条标一条已读再重排。
+
+    截图要同时展示圆点三态（● 新 / ○ 未读 / 空 已读）——全新状态全屏 ●
+    看不出「已读会变空」，全已读又看不出特性；隔条混合最像真实使用痕迹。
+    """
+    main = app.main
+    if main is None or not main.items:
+        return
+    for it in main.items[::3]:
+        app.state.mark_read(it.source, it.id)
+    await main.rebuild_items()
+    for _ in range(2):
+        await pilot.pause()
+
+
 def _emit(app: app_mod.FeedScopeApp, name: str) -> None:
     """导出一张：SVG -> 修 CJK 格宽 -> 栅格化 PNG。"""
     svg, fixed = _fix_cjk_metrics(app.export_screenshot())
@@ -811,10 +832,20 @@ def _emit(app: app_mod.FeedScopeApp, name: str) -> None:
 
 def main() -> None:
     # 隔离本机用户配置（隐藏流会让侧栏条目数漂移）；预写 enabled 跳过首启引导
-    # （引导是交互弹层，自动化流程过不去）；FEEDSCOPE_NO_PREWARM 关掉不拉真 Chrome
+    # （引导是交互弹层，自动化流程过不去）；FEEDSCOPE_NO_PREWARM 关掉不拉真 Chrome。
+    # 已读状态/列表缓存同样钉在仓库根（gitignore），先清再跑：读/缓存都会让截图
+    # 漂移（混合已读态由 _demo_read_mix 脚本化生成，不靠上一次运行的残留）
     cfg = DOCS.parent / ".screenshot-sources.toml"
     cfg.write_text('enabled = ["zhihu", "x", "reddit", "hn", "v2ex"]\n', encoding="utf-8")
+    state = DOCS.parent / ".screenshot-state.json"
+    state.unlink(missing_ok=True)
+    cache = DOCS.parent / ".screenshot-feeds"
+    if cache.exists():
+        for p in cache.iterdir():
+            p.unlink()
     os.environ["FEEDSCOPE_CONFIG"] = str(cfg)
+    os.environ["FEEDSCOPE_STATE"] = str(state)
+    os.environ["FEEDSCOPE_FEED_CACHE"] = str(cache)
     os.environ["FEEDSCOPE_NO_PREWARM"] = "1"
     saved = source_classes()
     install_sources([DemoZhihu, DemoX, DemoReddit, DemoHn, DemoV2ex])

{feedscope-0.1.0 → feedscope-0.2.0}/src/feedscope/__init__.py

@@ -1,3 +1,3 @@
 """FeedScope（观流）：终端信息流聚合阅读器（知乎 / X / Reddit / HN / V2EX / RSS / Telegram）。"""
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{feedscope-0.1.0 → feedscope-0.2.0}/src/feedscope/cli.py

@@ -1,4 +1,4 @@
-"""命令行入口：`feedscope` 启动 TUI；子命令 login / probe / doctor / rss。"""
+"""命令行入口：`feedscope` 启动 TUI；子命令 login / probe / doctor / rss / favorites。"""
 
 from __future__ import annotations
 
@@ -38,6 +38,11 @@ def build_parser() -> argparse.ArgumentParser:
     export_p = rss_sub.add_parser("export", help=t("cli.help_rss_export"))
     export_p.add_argument("path", nargs="?", help=t("cli.help_rss_export_path"))
 
+    fav = sub.add_parser("favorites", help=t("cli.help_favorites"))
+    fav_sub = fav.add_subparsers(dest="fav_command")
+    fav_export = fav_sub.add_parser("export", help=t("cli.help_favorites_export"))
+    fav_export.add_argument("path", nargs="?", help=t("cli.help_favorites_export_path"))
+
     return parser
 
 
@@ -116,6 +121,39 @@ def _run_rss(args: argparse.Namespace) -> int:
     return 0
 
 
+def _run_favorites(args: argparse.Namespace) -> int:
+    """favorites 子命令：无子命令 = 明文列表；export = Markdown（防锁定，同 rss export）。"""
+    import time
+
+    from feedscope.core.store import ReadState
+
+    pairs = ReadState().favorites()
+    if args.fav_command != "export":
+        if not pairs:
+            print(t("cli.favorites_empty"))
+            return 0
+        for ts, it in pairs:
+            date = time.strftime("%Y-%m-%d", time.localtime(ts))
+            print(f"{it.source:<10} {date}  {it.title}  <{it.url}>")
+        print(t("fav.status_count", n=len(pairs)))
+        return 0
+
+    # Markdown 链接的方括号/圆括号会破坏语法，标题与 URL 做最小转义
+    lines = [
+        f"- [{it.title.replace('[', '(').replace(']', ')')}]"
+        f"({it.url.replace('(', '%28').replace(')', '%29')}) — {it.source}，"
+        f"{time.strftime('%Y-%m-%d', time.localtime(ts))}"
+        for ts, it in pairs
+    ]
+    md = "\n".join(lines) + "\n" if lines else ""
+    if args.path:
+        Path(args.path).write_text(md, encoding="utf-8")
+        print(t("cli.favorites_exported", n=len(pairs), path=args.path))
+    else:
+        print(md, end="")
+    return 0
+
+
 def main(argv: list[str] | None = None) -> int:
     # 进程语言按配置设定（未设置 = 缺省）：CLI 的 help/输出与 TUI 同语言；
     # 必须在 build_parser 之前——argparse 的 help 在构造时就成型
@@ -151,4 +189,7 @@ def main(argv: list[str] | None = None) -> int:
     if args.command == "rss":
         return _run_rss(args)
 
+    if args.command == "favorites":
+        return _run_favorites(args)
+
     return 0

feedscope-0.2.0/src/feedscope/core/feed_cache.py

@@ -0,0 +1,104 @@
+"""列表缓存：每流一个 JSON 文件，重启先画缓存秒开、抓取失败时兜底不清屏。
+
+- 目录：FEEDSCOPE_FEED_CACHE 环境变量（测试隔离），缺省用户缓存目录下 feeds/
+  （platformdirs，与 chromium-profile / samples 同根）
+- 每流一文件是硬约束不是风格：RSS 的 extra 带全文 content_html（单条 5-20KB），
+  聚合到单文件 JSON 后每次刷新任何一个流都要原子重写全部缓存（十几 MB 写
+  放大）；拆文件后每次只重写本流自己的文件（几十 KB～几 MB）
+- 缓存是派生数据：删除/损坏的最坏代价 = 下次刷新重抓，所以 LRU 淘汰（按
+  mtime 留最近 _MAX_FEEDS 个流）与坏文件容错都可以放心地激进
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import logging
+import os
+from pathlib import Path
+from urllib.parse import quote
+
+from platformdirs import user_cache_path
+
+from feedscope.core.models import FeedItem
+
+logger = logging.getLogger(__name__)
+
+_MAX_FEEDS = 60        # LRU：超过即删最旧（切流频繁的缓存自然留大，冷流自然让位）
+_MAX_ITEMS = 200       # 单流上限：取列表头部（各源列表都是新→旧序）
+_NAME_CAP = 120        # 文件名上限（quote 后）：防超长订阅 key 撞文件系统限制
+
+
+def cache_dir() -> Path:
+    if p := os.environ.get("FEEDSCOPE_FEED_CACHE"):
+        return Path(p)
+    return user_cache_path("feedscope") / "feeds"
+
+
+def _file(source_id: str, feed: str) -> Path:
+    """(source, feed) -> 缓存文件路径。
+
+    quote 编码非 URL 安全字符（中文订阅 key、路径分隔符都变成 %XX）：
+    唯一、路径安全；只做正向映射不回解，寻址永远走 (source, feed) 入参。
+    超长名截断后补内容散列前缀，防不同长 key 截断后撞名。
+    """
+    name = quote(f"{source_id}__{feed}", safe="")
+    if len(name) > _NAME_CAP:
+        digest = hashlib.sha1(name.encode()).hexdigest()[:8]
+        name = f"{name[:_NAME_CAP]}~{digest}"
+    return cache_dir() / f"{name}.json"
+
+
+def save(source_id: str, feed: str, items: list[FeedItem]) -> None:
+    """流刷新成功后整流覆写（头部 _MAX_ITEMS 条）；空列表不落盘（无可兜底）。"""
+    if not items:
+        return
+    path = _file(source_id, feed)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_name(path.name + ".tmp")
+        tmp.write_text(
+            json.dumps(
+                {"version": 1, "items": [it.to_dict() for it in items[:_MAX_ITEMS]]},
+                ensure_ascii=False,
+                separators=(",", ":"),
+            ),
+            encoding="utf-8",
+        )
+        os.replace(tmp, path)
+    except OSError as exc:
+        logger.warning("列表缓存写入失败（%s/%s，忽略）：%s", source_id, feed, exc)
+    _evict()
+
+
+def load(source_id: str, feed: str) -> list[FeedItem] | None:
+    """读缓存；不存在/坏/形状不符 = None（调用方当作「无缓存」走正常空态）。"""
+    try:
+        raw = json.loads(_file(source_id, feed).read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        return None
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError) as exc:
+        logger.warning("列表缓存读取失败（%s/%s，忽略）：%s", source_id, feed, exc)
+        return None
+    rows = raw.get("items") if isinstance(raw, dict) else None
+    if not isinstance(rows, list):
+        return None
+    items = [FeedItem.from_dict(r) for r in rows if isinstance(r, dict)]
+    return items or None
+
+
+def _evict() -> None:
+    """目录内 .json 超过 _MAX_FEEDS 个时删最旧（mtime = 最近一次 save）。"""
+    d = cache_dir()
+    try:
+        files = [p for p in d.iterdir() if p.suffix == ".json"]
+    except OSError:
+        return  # 目录不存在（还没写过任何缓存）
+    if len(files) <= _MAX_FEEDS:
+        return
+    files.sort(key=lambda p: p.stat().st_mtime)  # 调用点已兜 OSError，这里不再拦
+    for p in files[: len(files) - _MAX_FEEDS]:
+        try:
+            p.unlink()
+        except OSError:
+            pass  # 并发/权限抖动：残留一个旧文件无害，下次淘汰再试