newsbox
- Repo stars 0
- Author updated Live
- Author repo skills-registry
- Domain
- DevOps
- Compatible agents
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- Trust score
- 88 / 100 · community maintained
- Author / version / license
- @tomevault-io · no license declared
- Token usage
- Moderate
- Setup complexity
- Manual integration
- External API key
- Not required
- Operating systems
- Docker
- Runtime requirements
- Python · Docker
- Permissions
-
- Read-only
- Write / modify
- Shell exec
- Env read
- Network behavior
- External requests
- Install commands
- 26 variants
Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.
Heads up: 未限定 allowed-tools,默认拥有全部工具权限。
---
name: newsbox
description: newsbox 是「采集层」CLI + SDK:从 RSS / 网页采集 AI 信源 → 落进 ~/.newsbox/raw.db(业务投影是 articlesraw 表;另有 sources…
category: devops
runtime: Python / Docker
---
# newsbox output preview
## PART A: Task fit
- Use case: newsbox 是「采集层」CLI + SDK:从 RSS / 网页采集 AI 信源 → 落进 ~/.newsbox/raw.db(业务投影是 articlesraw 表;另有 sourcestate 表记每个信源的最近抓取/失败状态,你通过 state 命令读,不需要自己直查)。它只采集,不做内容筛选 / 打分 / 摘要 / 日报(这些是消费方/agent 自己干)。 makes outbound network calls; runs on Python. Works with Claude Code, Cursor, Cline and 23 more..
- Inputs: target material, constraints, expected output, and acceptance criteria.
- Evidence boundary: follow “数据怎么进、怎么出 / 场景 1:信源管理 / 加信源” and do not present inference as author intent.
## PART B: Execution result
- **01** The card summarizes the use case; runtime output centers on “newsbox 是「采集层」CLI + SDK:从 RSS / 网页采集 AI 信源 → 落进 ~/.newsbox/raw.db(业务投影是 articlesraw 表;另有 sourcestate 表记每个信源的最近抓取/失败状态,你通过 state 命令读,不需要自己直查)。它只采集,不做内容筛选 / 打分 / 摘要 / 日报(这些是消费方/agent 自己干)。 makes outbound network calls; runs on Python. Works with Claude Code, Cursor, Cline and 23 more.”.
- **02** When the source has headings, the agent prioritizes “数据怎么进、怎么出 / 场景 1:信源管理 / 加信源” so the result follows the author’s structure.
- **03** Typical output includes task judgment, concrete steps, required commands or file edits, validation, and follow-up options.
- **04** Risk context follows the fingerprint: read files, write/modify files, run shell commands, read environment variables; may access external network resources; usually needs no extra API key.
## Running Rules
- read files, write/modify files, run shell commands, read environment variables; may access external network resources; usually needs no extra API key.
- Validate with a small sample before expanding scope.
- Return the result, validation criteria, and next iteration options. The source does not require a stable slash command. After installation, invoke the skill by name and describe the task.
Name target files or source material, expected output, forbidden changes, and whether network or shell access is allowed. Permission fingerprint: read files, write/modify files, run shell commands, read environment variables.
Start with a small task and check whether the result follows “数据怎么进、怎么出 / 场景 1:信源管理 / 加信源”. Inspect diffs, logs, previews, or tests before expanding scope.
Confirm the final output includes a concrete result, evidence, and next action. If it stays generic, tighten inputs, boundaries, and acceptance criteria.
---
name: newsbox
description: newsbox 是「采集层」CLI + SDK:从 RSS / 网页采集 AI 信源 → 落进 ~/.newsbox/raw.db(业务投影是 articlesraw 表;另有 sources…
category: devops
source: tomevault-io/skills-registry
---
# newsbox
## When to use
- newsbox 是「采集层」CLI + SDK:从 RSS / 网页采集 AI 信源 → 落进 ~/.newsbox/raw.db(业务投影是 articlesraw 表;另有 sourcestate 表记每个信源的最近抓取/失败状态…
- Use it when the task has clear inputs, repeatable steps, and validation criteria.
## What to provide
- Target material, scope, expected result, and forbidden changes.
- Whether network, commands, file writes, or external services are allowed.
## Execution rules
- Organize steps around “数据怎么进、怎么出 / 场景 1:信源管理 / 加信源” and keep inference separate from source facts.
- read files, write/modify files, run shell commands, read environment variables; may access external network resources; usually needs no extra API key.
- Validate with a small sample before expanding the task.
## Output requirements
- Return the deliverable, key evidence, validation method, and next action.
- Mark missing information as unknown; do not invent commands, platforms, or dependencies. The author source anchors workflow facts; repository files anchor sources and commands; Fluxly only adds fit, limitations, and quality judgment.
skill "newsbox" {
input -> user goal + target files + boundaries + acceptance criteria
context -> 数据怎么进、怎么出 / 场景 1:信源管理 / 加信源
rules -> SKILL.md triggers / order / output contract
runtime -> Python / Docker | read files, write/modify files, run shell commands, read environment variables | may access external network resources
guardrails -> usually needs no extra API key + small-sample validation + diff/log review
output -> copyable result + checklist + next iteration
} 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.
Decide Fit First
Design Intent
How To Use It
Boundaries And Review