feedscope 0.1.0__tar.gz

feedscope-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,82 @@
+name: Bug report / 问题报告
+description: Something is broken, renders wrong, or fails to fetch / 抓取失败、显示异常
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to report! 谢谢反馈！
+
+        Pasting `feedscope doctor` output up front (item 4) usually saves a
+        round trip — it carries the version, OS, Python and Chrome state in
+        four lines.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened / 发生了什么
+      description: And what did you expect instead? 期望的行为是什么？
+    validations:
+      required: true
+  - type: dropdown
+    id: source
+    attributes:
+      label: Affected source / 受影响的源
+      multiple: true
+      options:
+        - Zhihu
+        - X (Twitter)
+        - Reddit
+        - Hacker News
+        - V2EX
+        - RSS
+        - Telegram
+        - TUI / app-wide (not source-specific)
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce / 复现步骤
+      placeholder: |
+        1. `feedscope`
+        2. Tab to Reddit, wait for Popular
+        3. ...
+    validations:
+      required: true
+  - type: textarea
+    id: doctor
+    attributes:
+      label: "`feedscope doctor` output / doctor 输出"
+      description: Run it in a terminal and paste the whole output — it includes version and environment in one shot.
+      placeholder: |
+        FeedScope doctor v0.1.0
+        OK  Python 3.12
+        ...
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: probe
+    attributes:
+      label: Probe sample (if a site redesign is suspected) / probe 样本（怀疑改版时）
+      description: |
+        `feedscope probe <source>` saves raw samples to disk — paste the
+        relevant excerpt if the error says a source may have changed. Mind
+        that samples can contain your feed content.
+      render: text
+  - type: dropdown
+    id: os
+    attributes:
+      label: OS / 操作系统
+      options:
+        - macOS
+        - Linux (Debian / Ubuntu)
+        - Linux (Arch)
+        - Linux (other)
+        - Windows (not supported yet — say more below)
+        - Other
+    validations:
+      required: true
+  - type: textarea
+    id: context
+    attributes:
+      label: Additional context / 其他补充
+      description: Logs, screenshots, config excerpts (minus anything sensitive) — anything that helps.

feedscope-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Questions & discussions / 交流讨论
+    url: https://github.com/howardli/FeedScope/discussions
+    about: Usage questions, setups and ideas that aren't bugs or concrete features
+  - name: Security issues / 安全问题
+    url: https://github.com/howardli/FeedScope/security/policy
+    about: Please don't report vulnerabilities in public issues — see the security policy

feedscope-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,32 @@
+name: Feature request / 功能建议
+description: Suggest a new source, feed, or behavior / 新源、新流或行为建议
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve? / 它解决什么问题
+      description: Not the feature itself — the pain behind it. 不是功能本身，是它背后的痛点。
+      placeholder: I can't ... / 我没法……
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: What would it look like? / 你期望的形态
+      description: Command, key, feed, source — sketch it however is natural.
+    validations:
+      required: true
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area / 领域
+      options:
+        - New source (a new site / 新站点)
+        - New feed in an existing source
+        - Reading / detail view
+        - Login & accounts
+        - RSS / subscriptions
+        - Config & source manager
+        - i18n
+        - Other

feedscope-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,21 @@
+## Summary / 摘要
+
+<!-- What changed and why. One or two sentences, then the detail that matters. -->
+
+## Type of change / 变更类型
+
+- [ ] Bug fix
+- [ ] New feature
+- [ ] New source (registered alphabetically in `sources/__init__.py`; caps tests updated)
+- [ ] Refactor / internals
+- [ ] Docs / assets
+
+## Checklist / 自查
+
+- [ ] Tests added or updated for the behavior change (fixture-driven, offline)
+- [ ] `uv run ruff check src/ tests/ scripts/` clean
+- [ ] `uv run mypy` clean
+- [ ] `uv run pytest` green
+- [ ] User-facing change has a `CHANGELOG.md` entry under `[Unreleased]`
+- [ ] UI-visible change → screenshots / demo GIF regenerated (`scripts/screenshot.py`, `scripts/demo_gif.py`)
+- [ ] New user-visible strings go through i18n catalogs (no hardcoded copy)

feedscope-0.1.0/.github/dependabot.yml

@@ -0,0 +1,22 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "chore(deps)"
+    groups:
+      python-deps:
+        patterns:
+          - "*"
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    commit-message:
+      prefix: "chore(ci)"
+    groups:
+      actions-deps:
+        patterns:
+          - "*"

feedscope-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv sync
+      - run: uv run ruff check src/ tests/ scripts/
+      - run: uv run mypy
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        # classifiers 声明支持的平台都在矩阵里被真跑过（macOS 的 Chrome 路径 /
+        # platformdirs 目录差异以前只有本机验证）；playwright 只装包不装浏览器，
+        # 测试基线全离线，hosted runner 直接可跑
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --python ${{ matrix.python-version }}
+      - run: uv run pytest tests/ --cov --cov-fail-under=80
+        # 测试基线全离线（解析 fixture / TUI 冒烟 / 登录流程），hosted runner 直接可跑；
+        # feedscope probe 巡检需要真实登录态与 Chrome，只能挂 self-hosted runner 定时跑（见 README）
+        # coverage 门槛在 pyproject（fail_under=80，当前实测 ~89%）：防倒退，新增模块应抬高它
+
+  build:
+    # 打包配置随时可构建：pyproject 的 packaging 回归在这里红，而不是发版当天才炸
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist-preview
+          path: dist/
+          if-no-files-found: error

feedscope-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,54 @@
+# Release pipeline: push a tag `v*` → build → publish to PyPI (OIDC trusted
+# publishing, no tokens) → GitHub Release with the artifacts.
+#
+# One-time setup lives in docs/release.md (PyPI pending publisher + the
+# `pypi` GitHub environment). After that, a release is: changelog entry,
+# version bump, `git tag vX.Y.Z && git push --tags`.
+
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build    # sdist + wheel; version is read from src/feedscope/__init__.py
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi    # create this environment once; see docs/release.md
+    permissions:
+      id-token: write    # OIDC trusted publishing — no PyPI token stored anywhere
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

feedscope-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.pyc
+.ruff_cache/
+.pytest_cache/
+.claude/
+dist/
+.DS_Store
+.zcode/
+.screenshot-sources.toml
+.coverage
+coverage*.xml
+cmp/

feedscope-0.1.0/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+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).
+
+## [0.1.0] - 2026-11-07
+
+Initial release.
+
+### Added
+
+- Multi-source aggregation in one terminal UI (`Tab` to switch): Zhihu Hot / Recommend / Following, X For You / Following, Reddit Home / Popular / custom subreddits, Hacker News Front / New / Ask / Show, V2EX Hot / Latest, Telegram channel subscriptions
+- RSS subscriptions: any RSS / Atom feed; site-homepage feed auto-discovery; OPML import (idempotent merge) / export; "All" stream merged by publish time with cross-feed dedup; conditional requests (ETag / Last-Modified) keep refreshes polite to sources
+- Three-layer in-terminal reading (feed → detail → discussion) loaded per layer on demand; HN-style deep threads flattened to two levels with `@parent` prefixes preserving who-replies-to-whom
+- Login loop: in-app Chrome QR / password login with auto-refresh on completion, `Ctrl+U` to switch accounts; session-revocation detection that never leaves you guessing (X 401 semantics, Reddit `token_v2` JWT local decode — zero network, zero forgery)
+- Resident browser-tab data channels for Zhihu / X / Reddit: TLS, header order and cookies fully consistent with the login session; X GraphQL queryIds self-heal by harvesting the current deployment's JS chunks; Reddit rides the website's own HTML channel with self-healing client version
+- Auto Grok translation for foreign-language X posts; media rendered as clickable `[图片]` / `[视频]` markers linking to originals
+- Bilingual UI (中文 / English), per-language TOML catalogs; a new language is one new TOML file, auto-discovered, enforced by key-parity and no-hardcoded-copy tests
+- Source manager (`F2`): enable sources on demand, per-source feed `hide` config, subscription managers for RSS / Reddit / Telegram
+- 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.1.0]: https://github.com/howardli/FeedScope/releases/tag/v0.1.0

feedscope-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,79 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement — the maintainer
+([@howardli](https://github.com/howardli)) via a private message on GitHub.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Impact assessments and some wording are drawn from the [Baseline Code of
+Conduct](https://baseathon.github.io/baseline-code-of-conduct/).
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html

feedscope-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,142 @@
+# Contributing to FeedScope
+
+Thanks for your interest in making FeedScope better. Bug reports, new sources,
+new languages and doc improvements are all welcome — the two most natural
+contributions for this codebase are **adding a source** and **adding a
+language**, both designed to need almost no code outside their own files.
+
+A note on language: the README is bilingual (English / 中文); code comments in
+this repo are written in Chinese. Either language is fine in issues and PRs.
+
+## Getting started
+
+Prerequisites: Python 3.11+, [uv](https://docs.astral.sh/uv/), and a local
+Google Chrome (the app drives it; no `playwright install` needed).
+
+```bash
+git clone https://github.com/howardli/FeedScope.git
+cd FeedScope
+uv sync                 # create the venv and install all dependencies
+uv run feedscope        # run the app from source
+uv run pytest           # run the full test suite — all offline, ~1 min
+```
+
+The full quality gate (same as CI):
+
+```bash
+uv run ruff check src/ tests/ scripts/
+uv run mypy             # src/ is typed and held at zero errors
+uv run pytest tests/ --cov   # coverage floor: 80%
+```
+
+## Project layout
+
+```
+src/feedscope/
+  core/        models, config, registry, i18n, text/wrap/timefmt, tree,
+               browser channel — the foundation everything else builds on
+  sources/     one package per site: zhihu / x / reddit / hn / v2ex / rss / telegram
+  ui/          Textual screens and widgets
+  cli.py       argparse entry point (tui / login / probe / doctor / rss)
+tests/         offline suite: fixture-driven parsers, TUI smoke via Textual Pilot,
+               plus architecture / i18n / registry guard tests
+scripts/       screenshot.py (README images), demo_gif.py, x_probe.py
+```
+
+Layering is enforced by `tests/test_architecture.py`, not just convention:
+
+```
+ui → top-level business (cli / login / subscriptions / probe / doctor / report)
+   → sources → core
+```
+
+Dependencies only point downward; `parse.py` modules are pure leaves (no IO);
+UI never reads source-private keys. If the guard blocks you, read its
+docstring — the exceptions are documented there.
+
+## Adding a new source
+
+The highest-value contribution. The architecture is plugin-shaped: a source is
+one package under `src/feedscope/sources/`, registered by a single import —
+UI and core need zero changes.
+
+```
+sources/<id>/
+  fetch.py      data layer: get raw data (httpx / resident browser tab /
+                DOM extraction); incremental loaders that hold resources live
+                here. No UI.
+  parse.py      parsing layer: raw dict/HTML → FeedItem / Answer / DetailDoc /
+                markdown. Pure functions, directly testable against fixtures.
+                No network, no IO — it is the bottommost leaf.
+  __init__.py   orchestration: the @register'd Source subclass — capability
+                declaration and open_* dispatch. First-screen guard via
+                require_feed_items; login gate via core.source.login_gate
+                if the site needs one.
+```
+
+Step by step:
+
+1. **Read an existing source closest to your target shape.** RSS / Telegram
+   are subscription-style; HN / Reddit are three-layer with discussion trees;
+   V2EX is two-layer. `sources/__init__.py`'s docstring is the authoritative
+   template.
+2. **Write `parse.py` first** and drive it with saved fixtures
+   (`tests/test_<id>_parse.py`). This is where most of the logic should live,
+   because it is trivially testable offline.
+3. **Write `fetch.py`**: use `core/http.py` for plain HTTP, or the resident
+   browser-tab channel (`core/browser.py`) when the site blocks non-browser
+   fingerprints — see the Reddit / X sources for the pattern.
+4. **Write the `Source` subclass** in `__init__.py` with its capability flags
+   (`supports_detail`, `supports_comments`, `subscribable`, `feeds`,
+   `feed_labels`, `detail_kinds`). Inherit the shared skeletons instead of
+   rewriting mechanics:
+   - subscription-style → `core.source.SubscribedSource` (the "All" stream's
+     error handling comes free; inject `_fetch_merged` / `_open_one`)
+   - detail fetched as one full tree → `SliceDetailLoader` (floor / reply
+     paging = in-memory slicing, zero code)
+   - body carried by the list → `StaticDetailLoader` (opening a detail costs
+     zero requests)
+   - deep discussion flattening → `core.tree` (`@parent` prefix rule has a
+     single implementation)
+5. **Register it** by adding one import line to `sources/__init__.py`, in
+   **alphabetical order by `source_id`** — import order = source-picker row
+   order = default Tab order. `tests/test_source_caps.py` and
+   `tests/test_registry_order_is_tab_order` go red if you get this wrong.
+6. **All UI copy through i18n** (`core/i18n.t()`) — never hardcode user-visible
+   strings; `tests/test_i18n_no_hardcoded.py` blocks it in CI. Source
+   vocabulary words (unit labels like "回复" / "comment") go through the same
+   catalogs.
+7. **Run the full gate** (see above) and add a caps test entry if the source
+   introduces a new capability combination.
+
+## Adding a language
+
+Copy `src/feedscope/core/i18n/en.toml` to `<code>.toml` (e.g. `ja.toml`), set
+the native name in `[meta]`, translate the messages. The language picker
+discovers it automatically — zero code changes. `tests/test_i18n.py` enforces
+an identical key tree across catalogs, so a missing translation fails CI.
+
+## UI changes → refresh the images
+
+README screenshots and the demo GIF are generated from the real app driven by
+offline stub sources, so they can never drift from the code:
+
+```bash
+uv run python scripts/screenshot.py                  # README stills → docs/*.png
+uv run --with pillow python scripts/demo_gif.py      # demo GIF → docs/demo.gif
+```
+
+If your change affects what's on screen, re-run the relevant script and commit
+the images together with the code.
+
+## Pull requests
+
+- Keep PRs focused; one logical change each
+- New behavior needs tests (offline; fixture-driven — look at existing
+  `tests/test_*_parse.py` for the pattern)
+- User-facing changes get a `CHANGELOG.md` entry under `[Unreleased]`
+- CI (ruff + mypy + pytest on Python 3.11–3.13, macOS & Linux) must be green
+- Match the existing style: Chinese comments that explain *why*, ruff's
+  line-length 100 in `src/`
+
+Thank you! 🎉

feedscope-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 howardli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.