tomevault-io newsbox — 工具说明书
newsbox 是「采集层」CLI + SDK：从 RSS / 网页采集 AI 信源 → 落进 ~/.newsbox/raw.db（业务投影是 articles_raw 表；另有 source_state 表记每个信源的最近抓取/失败状态，你通过 state 命令读，不需要自己直查）。它只采集，不做内容筛选 / 打分 / 摘要 / 日报（这些是消费方/agent 自己干）。
你（agent）通常做两类事：
- 运维这个工具：加信源、跑抓取、排故障
- 消费它的产出：通过 CLI/SDK 拿到文章 → 用 LLM 二次加工
下面 5 类场景按需查。命令都支持 --help 看完整参数。
数据怎么进、怎么出
上游（RSS / 网页 / RSSHub 转译的 X / Reddit）
│ newsbox fetch
▼
~/.newsbox/raw.db （articles_raw 表）
│ CLI: newsbox read --json ← 你查数据走这里
│ SDK: newsbox.sdk.read_raw() ← 在 Python 里走这里
▼
你的二次加工（LLM 摘要 / 筛选 / 写日报）
重要：不要直接 sqlite3 ~/.newsbox/raw.db "SELECT ..." 写 SQL —— 表结构会演进（已删过死字段、未来还会改），直接查 raw.db 的代码会随之坏。统一走 read --json（shell 环境）或 sdk.read_raw()（Python 环境），这两条是稳定契约。
场景 1：信源管理
加 / 看 / 改 / 删信源。信源清单存在 ~/.newsbox/sources.yaml，CLI 自动管理，不要手编 yaml。
加信源
# 智能录入：探测 url → 提示建议 → 交互确认（有 TTY 时）
newsbox sources add https://example.com/blog
# 非交互式（你最常用这个）
newsbox sources add https://example.com/blog \
--tier=kol \
--domain=ai \
--id=example_blog
# probe 判不准 / url 不可达但你知道类型时，显式指定
newsbox sources add https://example.com/blog --type=rss --tier=kol --domain=ai --id=example_blog
# 批量
newsbox sources add --from-file=urls.txt
参数说明：
--tier:official_first_party/kol/secondary（信源权重，影响消费方打分）--domain:ai是默认；未来可能finance等（多领域设计）--id: 信源唯一 id，建议小写下划线（如simon_willison_blog）--type:rss/web/twikit（一般不传，靠 probe 自动判定；探测不准时手动覆盖）
X (Twitter) 账号特殊：录 X 账号 URL（https://x.com/<handle> / https://twitter.com/<handle>）会被 probe 自动识别为 twikit 类型，url 字段自动归一化为裸 handle（dotey 而非完整 URL）。例：
newsbox sources add https://x.com/dotey --tier=kol --id=x_dotey
# yaml 落地：twikit 段下 url: "dotey"
首次配置 X 信源前需生成 ~/.newsbox/twikit_cookies.json（含 auth_token + ct0），步骤见 docs/twikit-setup.md §1。
录入前先侦察
# 单 url 探测：可达性 / type / 建议 id / 样本标题
newsbox sources probe https://example.com/blog
# 批量探测（不写 yaml，只回报）
newsbox sources probe --from-file=urls.txt
侦察用来判断「这个 url 能不能采、采到啥」，再决定要不要 add。
看信源
newsbox sources list # 全部
newsbox sources list --enabled-only # 只看启用的
newsbox sources list --type=web --tier=kol # 多维过滤
newsbox sources show <id> # 单条完整配置
newsbox sources export --out=backup.yaml # 备份（字节级保真）
改 / 删
newsbox sources edit <id> --tier=official_first_party
newsbox sources rename <old_id> <new_id>
newsbox sources disable <id> # 临停（保留配置）
newsbox sources enable <id> # 恢复
newsbox sources remove <id> --yes # 彻底删（--yes 非交互必须加）
newsbox sources test <id> # 试拉一次（不入库），看能不能抓到
兜底：清单丢失时重铺种子
newsbox sources seed # 拷贝项目种子清单到 ~/.newsbox/sources.yaml
newsbox sources seed --force # 覆盖已存在的清单（慎用）
sources.yaml 不在或被你清空时用；正常路径不需要。
场景 2：日常运行
抓数据
# 默认拉所有启用信源 24h 内更新
newsbox fetch
# 拉指定时间窗口
newsbox fetch --since=7d
newsbox fetch --since=24h
# 单类型 / 单信源（统一走 --source，CLI 自动判断传的是 type 还是 id）
newsbox fetch --source=rss
newsbox fetch --source=anthropic_news
# 调并发（rss 桶默认 8 并发，web 桶串行）
newsbox fetch --concurrency=4
注意：信源更新频率天然不固定（Anthropic 一周 1-2 次很正常），--since=24h 看不到新内容 ≠ 出问题，把窗口拉到 7d 或 30d 再判断。
看数据
# 默认 rich Table 输出，看 24h 内
newsbox read
# JSON 模式（你最常用，便于 jq / Python 解析）
newsbox read --since=24h --json
# 多维过滤
newsbox read --since=7d --source-types=rss --domain=ai --tier=official_first_party --json
newsbox read --since=7d --source-id=anthropic_news --json
newsbox read --since=24h --limit=20 --json
newsbox read --since=24h --limit=0 --json # 0 = 无限制
# 大窗口需绕过阈值软阻断时显式 --yes（或 --json 自动跳过）
newsbox read --since=90d --limit=0 --yes
read 字段：id / source_type / source_id / source_tier / external_id / url / title / body / published_at / fetched_at / domain_tags / content_hash。
调用量阈值机制（重要）：read 命令在执行前 COUNT(*) 预估返回行数，超过 10000 条时 stderr 打 warn 并 typer.confirm 软阻断，引导切到 SDK。四态行为：
- 交互 tty + 无
--yes+ 无--json→ stderr warn + confirm 拒绝则 abort --json模式 → 隐含--yes，warn 仍走 stderr，stdout 仍是干净 NDJSON（agent 管道安全）--yesflag → stderr warn，跳过 confirm 直接执行（agent 显式覆盖）- 非 tty + 无
--yes+ 无--json→ abort + 引导文案（必须显式传其一）
阈值可在 ~/.newsbox/config.yaml 加 thresholds.cli_read_warn: <N> 覆盖默认 10000。超阈值场景优先考虑切 SDK（流式游标，无 JSON 序列化往返）—— 详见 docs/sdk-usage.md。
看统计
newsbox stats # 4 块 panel：总数 / Top-N 信源 / 近 7 天 ASCII 柱图 / type×domain
newsbox stats --top=20
newsbox stats --json
清旧数据
newsbox clean --before=30d # dry-run：只报会删多少（默认）
newsbox clean --before=30d --yes # 真删
newsbox clean --before=30d --yes --no-vacuum # 真删但跳过 VACUUM（删完磁盘不回收）
默认 dry-run 是为了防误删；想真动手必须显式 --yes。删完默认自动 VACUUM 回收磁盘。
场景 3：拿到数据后二次加工
核心场景：你抓到一批文章后要让 LLM 摘要 / 筛选 / 写日报，怎么用最稳？
路径 A：shell + jq（agent 在 bash 里跑）
# 拿 7d 内所有 ai-domain 的官方一手内容，提取 title + url
newsbox read --since=7d --domain=ai --tier=official_first_party --json \
| jq -r '.title + "\t" + .url'
# 拿某信源的 title 列表给 LLM 输入
newsbox read --since=7d --source-id=anthropic_news --json \
| jq -r '.title'
# 拿完整记录写进文件给后续脚本读
newsbox read --since=24h --json > today.ndjson
输出是 NDJSON（每行一个 JSON 对象），不是 JSON 数组，所以用 jq 不需要 .[]。
路径 B：Python SDK（你在 Python 环境里）
from datetime import datetime, timedelta, timezone
from newsbox import sdk
# 流式游标，不一次性加载内存
since = datetime.now(timezone.utc) - timedelta(days=7)
for art in sdk.read_raw(domain="ai", since=since, source_types=["rss"]):
print(art.source_id, art.title, art.url)
# art.title / art.body / art.published_at / art.fetched_at / art.content_hash ...
read_raw() 签名：
read_raw(
domain: str = "ai",
since: datetime | None = None,
source_types: list[str] | None = None,
limit: int | None = None,
db_path: Path | None = None,
) -> Iterator[ArticleRaw]
按 (fetched_at ASC, id ASC) 排序输出。db_path 默认 ~/.newsbox/raw.db。
何时用哪种？
- 写日报 / 一次性筛选 → shell + jq 简单粗暴（一次性
read --json子进程开销可忽略） - 批量处理几千篇文章给 LLM 的长流水线 → Python SDK 流式游标（避免在循环里反复起 CLI 子进程，每次都重新启 Python 解释器 + 重新打开 sqlite）
content_hash 字段的用法
不同 url 但同内容（搬运 / 转载）有同样的 content_hash（基于 title + 正文前 500 字 sha256）。你可以：
- 按
content_hash分组识别热门转载内容（"被 N 家媒体转发"作为热度信号） - 按
content_hash去重（消费方自己决定，collector 不替你去重）
场景 4：故障处理
系统不对劲先跑 doctor
newsbox doctor
全面诊断：Docker 起没？X token 填了？数据库通吗？随机抽样信源能否抓到？
看运行状态
newsbox status # 容器健康 / 上次抓取时间 / 库里多少条 / 最近失败信源
newsbox state # 列每个信源最近抓取情况、连续失败次数
newsbox logs --tail=50 # 最近日志
重启 RSSHub
newsbox restart # X token 换了、容器抽风时用
常见报错
docker-compose.yml 不存在 —— v0.5.1 起 compose 文件存在 home 目录，老版本升级会撞这条。修：
newsbox setup # 自动补齐 compose 文件 + 启容器（幂等）
某信源 fetched=0 —— 不一定是 bug。按顺序判断，不要先下 adapter bug 结论：
newsbox sources test <id> --limit=5试拉一次（不入库），看能不能抓到内容newsbox state看连续失败次数；也可只看一类：newsbox state --source-type=rss- 信源更新频率天然不固定，把窗口拉大单独跑：
newsbox fetch --source=<id> --since=30d - 抓到内容但入库 0 条 → 多半是去重命中（同一信源相同 external_id 不重复入）
- 扩大窗口仍异常 → 看
newsbox logs --tail=100与 adapter 真实样本，再下 bug 结论（不要凭"页面看着有内容"就判 adapter 错）
X / Twitter 信源失败 —— v1.0.2 起 X 走 twikit（cookie-based），不再依赖 .env 的 TWITTER_AUTH_TOKEN。newsbox doctor 看 [Twikit] panel：
twikit cookies 文件不存在→ 按 docs/twikit-setup.md §1 生成~/.newsbox/twikit_cookies.json缺少 auth_token / ct0 字段→ 重新从浏览器 devtools 复制填入- fetch 时报
TwikitAuthError（401） → auth_token 失效，重新复制（一般数月才失效一次） - 报
TwikitRateLimitError（429） → X 限流，几小时后再试 - 报
TwikitUserUnavailableError→ 账号不存在/被封，检查 url 字段拼写 完整失败矩阵见 docs/twikit-setup.md §3。
场景 5：装机与关停
首次装机
pipx install newsbox # 或 uv tool install newsbox
newsbox setup # 一步完成：建目录 + 启 RSSHub/Redis + 初始化库 + 铺信源 + 引导 X token
关停
newsbox teardown # 停容器，数据永远保留（不提供 --purge）
数据保留是设计取舍：误删的恢复成本远高于"占点磁盘"。重装时 setup 自动接续。
配置
newsbox config init # 在 ~/.newsbox/config.yaml 写默认配置
newsbox config show # 看当前生效配置
~/.newsbox/ 是运行时数据目录（不在项目里）：
sources.yaml— 信源清单（顶层rss/web/twikit三类）config.yaml— CLI / 抓取参数配置（含thresholds.cli_read_warn覆盖 read 阈值默认 10000）.env—TWITTER_AUTH_TOKEN（容器内 RSSHub 兜底；X 主路径已走 twikit）twikit_cookies.json— X 浏览器 cookies（v1.0.2+，auth_token + ct0；setup 生成同名.example.json模板）raw.db— SQLite 采集库docker-compose.yml— RSSHub + Redis 容器配置（v0.5.1 起）logs/newsbox.log— 日志
给 agent 的几条经验法则
- 看到
--help优先用 —— 命令参数会演进，--help是单一真相源 - 机器读输出永远加
--json—— rich Table 是给人看的，正则切割会脆。信息查询类（list / show / state / status / doctor / stats）输出整块 JSON；流式列表（read/sources list）输出 NDJSON（每行一条，不是 JSON 数组） - 错误路径走
{ok: false, message, details}schema —— 操作类命令（setup / fetch / clean / sources add / remove 等）--json模式下成功{ok: true, ...}、失败{ok: false, message, ...}，便于jq -e .ok判断 --since默认 24h，但信源更新频率不一定每天有更新 —— 找不到内容前先把窗口拉大再判断read大窗口注意阈值软阻断 —— 默认 >10000 条时会 stderr warn + confirm 阻断；agent 调用要么加--yes显式覆盖、要么加--json隐含跳过；非 tty 环境必须显式传其中之一否则 abort- 批量加信源用
--from-file=—— 别在循环里调add，CLI 启动开销叠加 - 要做内容判断 / 写日报 / 摘要 —— 那是你的活，collector 只给你原料
Source: a809384377/newsbox — distributed by TomeVault.