AGENT SKILL

my-news

拉取用户订阅的一手 RSS 源里的内容,按需整理成中文简报、列出全量条目、或返回某条原文。触发:用户提到"简报"、"news digest"、"看看 RSS"、"my-news"、"今日新闻"、"有什么新的"、"刷一下源"、"列出文章"、"给我 X 的原文"、"总结 X 这一条"等,或斜杠/at 形式如 `/my-news`、`@my-news`。Agent 无关,Claude Code / Hermes / 其他 agent 都可用。

License 许可
MIT
所属仓库
KaleLjl/My-news
最近更新
2026-05-28
Stars
★ 1
Forks
0

01 前言 Front Matter

name
my-news
description
拉取用户订阅的一手 RSS 源里的内容,按需整理成中文简报、列出全量条目、或返回某条原文。触发:用户提到"简报"、"news digest"、"看看 RSS"、"my-news"、"今日新闻"、"有什么新的"、"刷一下源"、"列出文章"、"给我 X 的原文"、"总结 X 这一条"等,或斜杠/at 形式如 `/my-news`、`@my-news`。Agent 无关,Claude Code / Hermes / 其他 agent 都可用。

02 资源文件 1

03 SKILL.md 正文

my-news — 一手 RSS 简报

本 skill 是个壳,真正干活的是 PATH 上的 my-news CLI(基于 newsboat + trafilatura,状态走 XDG 用户目录)。Agent 无关:只要 CLI 在 PATH 上,Claude Code / Hermes / 其它能跑 shell 的 agent 都能用。根据用户意图分支为三种动作:简报(新内容深度整理)、列表(罗列已抓取的所有条目,不消耗 unread 状态)、取单条(按 id/URL 拿完整原文);外加一个 诊断(doctor,查源是否还活着)。

0. 前置检查(每次会话首次触发时跑一次即可)

command -v my-news
  • 有输出 → 直接进入后面的命令分支。

  • 没输出 → CLI 没装。先停下来征求用户同意,然后用一行装上:

    uv tool install git+https://github.com/KaleLjl/my-news.git
    

    前置依赖(缺哪个补哪个):

    • uv:brew install uv(macOS)或 curl -LsSf https://astral.sh/uv/install.sh | sh(其它)
    • newsboat:brew install newsboat(macOS / Linuxbrew)/ sudo apt install newsboat(Debian / Ubuntu ≤22.04)/ sudo pacman -S newsboat(Arch)
    • Ubuntu 24.04+ 注意:apt 源里没有 newsboat。详细方案(Linuxbrew 推荐 / snap + 环境变量 workaround / 源码编译)见 references/install.md §I.5。

    装完再走下一步,不需要重开 shell(~/.local/bin 已在 PATH 时 my-news 立即可用)。

老仓库数据迁移:如果用户曾用过老版本(仓库里的 data/cache.db、feeds/urls 等),且 my-news paths 显示的 data_dir 还是空的,问一下要不要把老数据搬过去:

my-news migrate --from <老仓库路径>

migrate 是幂等的,已存在的目标会跳过。

关键原则:检查失败时不要硬跑命令然后让用户看一屏 traceback。先报清楚问题,再问要不要让你帮装。

1. 三个 CLI 子命令

所有命令直接调 my-news ...(已在 PATH 上)。不需要 cd 到任何目录,状态走 XDG 用户目录。

fetch — 新内容简报用

my-news fetch [--no-reload] [--no-mark] [--since 24h]
  • 默认:newsboat reload → 输出所有 unread 条目 JSON → 标记已读
  • 用于"看看今天有什么新的" / 定时简报
  • content_text 完整不截断(RSS 给多少就是多少)

list — 罗列已抓取的条目(不消耗 unread)

my-news list [--no-reload] [--feed QUERY] [--limit N] [--since 24h] [--unread-only]
  • 不过滤 unread,能看到所有还在缓存里的条目(包括已读历史)
  • --feed simon 按源标题或 URL 子串过滤(不区分大小写)
  • --limit 50 默认上限
  • 不会标记任何条目已读
  • 用于"列出 simonw 最近 30 条" / "看看缓存里都有什么"

show — 取单条完整原文

my-news show <id|url> [--full] [--refresh]
  • 参数可以是数字 id(来自 fetch/list 的 id 字段),也可以是文章 URL
  • 默认返回 RSS 自带内容:单条 JSON,content_text 完整 + 多带 content_html 原始 HTML(fetch/list 不带 html)
  • --full:另外去抓文章 URL 用 trafilatura 抽正文(Markdown 格式),结果缓存在 extracted_content 表里,第二次秒回。返回结构里多一个 extracted 字段:
    "extracted": {
      "status": "ok|fetch_failed|extract_failed|empty",
      "source": "cache|fresh",
      "fetched_at": "ISO",
      "length": <数字>,
      "text": "<Markdown 正文>"
    }
    
  • --refresh:强制重抓覆盖缓存
  • 找不到 id/url 时退出码 1 + {"error": "not_found", ...}
  • 用于"把第 X 条的原文给我" / "把 https://... 这篇展开"

feeds — 已配置的源

my-news feeds

add — 加一个源

my-news add <url> [--tag TAG]... [--force] [--timeout 10]
  • 默认会先 HTTP 探测 URL,确认是有效 RSS/Atom feed 才写入
  • --tag 可重复,等价于 newsboat urls 文件里的 "tag1" "tag2"
  • --force:跳过探测直接写入(返回里 "validated": false,标明是裸加)
  • 失败返回 JSON + exit 1,状态有 duplicate / no_feed_found
  • 保留 feeds/urls 里原有的注释和其他订阅,原子写

remove — 删一个源

my-news remove <url>
  • URL 匹配忽略大小写和尾部 /
  • 找不到返回 {"status": "not_found"} + exit 1
  • 保留其他订阅和注释

paths — 查路径(供 skill 自己用)

my-news paths

返回 JSON:config_dir / data_dir / feeds_file / newsboat_conf / cache_db / digests_dir。Skill 在写简报时先调一次它拿 digests_dir,避免硬编码路径。

2. 输出 JSON 形状

fetch 和 list:

{
  "fetched_at": "ISO 时间戳",
  "count": <数字>,
  "feed_count": <数字>,
  "by_feed": {
    "<源标题>": [
      {"id": <数字>, "title": "...", "url": "...", "author": "...",
       "pub_date": "ISO", "unread": true|false,
       "content_text": "去 HTML 的正文(完整,不截断)",
       "feed_url": "...", "tags": ["..."]}
    ]
  }
}

show 单条额外带 "content_html": "<原始 HTML>"。content_text 在所有命令里都是完整不截断的。

3. 分支决策:用户想要什么?

用户意图 用哪个命令
"看看今天的新闻" / "刷一下" / "/my-news" fetch
"看看最近 24 小时" fetch --since 24h
"预览一下,先别标已读" fetch --no-mark
"列一下 cloudflare 的所有文章" / "罗列 simonw 最近 20 条" list --feed <name> --limit 20
"看看缓存里都有什么" / "全部列出来" list --limit 100
"把第 N 条 / 标题为 X 的原文给我" 从上次 fetch/list 找到对应 id → show <id>;若 content_text 太短(RSS 只给了 metadata)→ 自动追加 show <id> --full 抓网页正文
"https://xxx 这篇是什么" show <url> --full
"总结一下 [某条]" show <id> --full 拿完整 extracted.text → 用 LLM 总结
"重新抓一下 X" show <id> --full --refresh(绕过缓存)
"我都订了什么源" feeds
"加一个源 / 订阅 X / 加上 https://..." add <url> [--tag X]...;探测失败时报清楚原因,可加 --force 裸加
"取消订阅 X / 删掉这个源" remove <url>

关键点:fetch 会"消耗" unread 状态。如果用户只是想浏览/查询/取原文,优先用 list 和 show,不要用 fetch。

首次大 backlog 处理(防爆上下文)

首次部署 / 长时间没刷 / 加了很多源时,fetch 可能一下子返回几百条,塞爆 LLM 窗口。应当先侦察再决定:

  1. 低成本侦察(不消耗 unread、内容截断):

    my-news fetch --no-mark --summary-only --limit 5
    

    只看返回 JSON 的 count 字段。

  2. 按 count 分级降级:

    count 怎么走
    <= 50 正常 my-news fetch,全量整理
    50 < count <= 200 my-news fetch --since 24h,告诉用户"另有 N 条更老的,要不要追?"
    > 200 my-news fetch --since 24h --limit 50 --summary-only,明确告诉用户在分批;剩余下次会话再处理
  3. --limit N 的语义:只输出最近 N 条 unread,只对这 N 条 mark_read,剩余 unread 保留供下次。所以分批安全,不会丢条目。

  4. --summary-only 的语义:每条 content_text 截断到 2000 字符(可用 MY_NEWS_SUMMARY_MAX_CHARS 调),并在 item 上加 "content_text_truncated": true 标记。需要全文:show <id> --full(trafilatura 抓网页正文)。

4. 简报输出格式(仅 fetch 路径)

空检查

count == 0 时输出:

📭 没有新内容(最近一次刷新:<fetched_at>)

直接结束,不调 LLM 生成内容。这让外部调度器(cron / systemd / Hermes 等)能靠是否包含"没有新内容"判断要不要推送。

有内容时的简报结构

# 📰 my-news 简报 · <YYYY-MM-DD HH:MM>

共 **<count>** 条新条目,覆盖 **<feed_count>** 个源。

## 🎯 今日要点

跨源提炼 3-5 条最重要的更新,每条 1 句话讲清楚是什么 + 为什么值得注意。

- **<要点标题>**:<一句话本质>。([来源](URL))

## 📚 分主题

如果多条围绕同一话题,合并讲、对比异同。没有跨源主题就跳过。

## 📰 按源全量

每个源下按 pub_date 倒序列出所有新条目,给 1-2 句中文摘要 + 原文链接。

### <源标题> (<n> 条)

- **<标题>** · <pub_date 简化>  
  <中文摘要 1-2 句>  
  [原文](URL) · `id: <id>`

如果某条 `content_text_truncated: true`(用了 `--summary-only`),摘要只写一句话 + 链接,注明"全文需 `show <id> --full`",不要假装看完了全文。

## 🔖 推荐精读

挑 2-3 条最值得点开看完的,说明"为什么推荐"。

带上 id:让用户后续可以说"给我 id 1042 的原文",skill 直接调 show 1042。

写到文件

简报输出到聊天的同时,也写一份到 my-news paths 返回的 digests_dir 下:

<digests_dir>/<YYYY-MM-DD-HHMM>.md

(默认是 ~/.local/share/my-news/digests/<YYYY-MM-DD-HHMM>.md)

digests_dir 不存在就 mkdir -p 一下。路径稳定可预测,方便调度器 cat 后推送。

5. 列表输出格式(list 路径)

# 📋 my-news 列表 · 共 <count> 条
<过滤条件回显:feed=xxx limit=N since=24h>

## <源标题> (<n> 条)

- `[id: 1042]` **<标题>** · <pub_date> · <unread ? "🆕" : "✓">  
  <如果 content_text 够长,给一句话摘要;不够长就略>  
  [原文](URL)

列表模式不写 digests 文件、不生成深度简报、不做跨源主题分析 — 这是"目录索引",不是简报。

6. 单条原文输出格式(show 路径)

# 📄 <标题>

- **源**:<feed_title>
- **作者**:<author>
- **发布**:<pub_date>
- **URL**:<url>
- **状态**:<unread ? "未读" : "已读">
- **标签**:<tags>

---

<content_text 全文,原样保留分段>

如果 content_text 极短(< 200 字符,像 HN 那种只有 metadata 的源):立即追加 show <id> --full 调 trafilatura 抓网页正文,然后用 extracted.text 而不是 content_text 渲染。如果 extracted.status != "ok"(fetch_failed / extract_failed / empty),再告诉用户原文抓不到、给原 URL 让他自己点。

7. 简报风格要求(仅 fetch 路径)

  • 中文输出,标题可保留原文(特别是技术名词、产品名)
  • 信息密度高:每句话都要有信息量,避免"近期 X 公司发布了关于 Y 的内容"这种空话
  • 可扫读:bullet、加粗、清晰小节,30 秒能抓住重点
  • 不编造:只依据 content_text。content_text 太短就照实说"原文需点开看"
  • 链接保留:每条都带 url 链接
  • 去噪:HN 这种源经常有杂项,可在"按源全量"列,但别进"今日要点"

8. 错误处理

  • CLI 自身失败(非 0 退出):先告诉用户错误,不要编造内容
  • command not found: my-news → 回到 §0 重新走前置检查
  • command not found: newsboat(CLI 跑得动但 fetch 时报错)→ 提示用户装 newsboat
  • show 返回 not_found:告诉用户没找到,建议先 list 看 id
  • stderr 有内容但 stdout 有有效 JSON:继续做简报/列表,末尾加"⚠️ 部分源刷新有问题,详见 my-news paths 返回的 error_log"
  • JSON parse 失败:输出 stdout 头 20 行帮助排查;如果 payload 巨大(单条 content 上万字)可重试 --summary-only

9. 环境变量覆盖(可选)

my-news 默认 config 在 ~/.config/my-news/,data 在 ~/.local/share/my-news/。如果用户想改:

  • MY_NEWS_CONFIG=/some/path 改 config 根(feeds/urls + newsboat.conf 都在里头)
  • MY_NEWS_DATA=/some/path 改 data 根(cache.db + digests/ 都在里头)
  • MY_NEWS_SUMMARY_MAX_CHARS=N 改 --summary-only 的截断阈值(默认 2000)

三个变量都是可选的;不设就用默认。设置时请用户自己写进 shell rc,skill 不应该替用户改 rc。

10. 源健康检查(用户问"哪个源没数据"时)

用户类似抱怨——"为什么 X 一直没东西"、"机器之心好像挂了"、"加了新源但 fetch 不到"——走 doctor:

my-news doctor              # 人类可读表格
my-news doctor --json       # 机器可读 JSON
my-news doctor --timeout 20 # 慢源放宽超时

输出每条源的:HTTP 状态、Content-Type、能不能 parse 成 RSS/Atom、item 数。状态分四种:

状态 含义 给用户什么建议
ok 拉得到 + parse 成功 + 有 item 没事
feed_unreachable HTTP 4xx/5xx 或网络错误 检查 URL 是不是改了;连续失败考虑删行
not_a_feed HTTP 200 但响应不是 RSS/Atom(多半是 HTML 落地页) URL 错了,去站点重找 RSS 入口
duplicate 与前面某行 URL 完全一致(仅规范化大小写 / 末尾斜杠) 删一行

Skill 拿到 --json 输出后,把 reports 里 status != "ok" 的整理给用户,建议改 feeds_file 路径(来自 my-news paths)。

注意:doctor 检测不到"同站不同 URL 但内容雷同"的伪重复(典型陷阱:hnrss.org/frontpage 和 news.ycombinator.com/rss 都会过 doctor,但后者只 metadata)。这种已知组合在 references/install.md §III "已知陷阱" 里列了。

04 同仓库更多 Skills