qm-reader-data

QMReader data reading

Read via the project's built-in command-line script https://rss.qiaomu.ai data. The script is located in this skill directory under scripts/qm_reader.py, depends only on the Python standard library, and requires nothing to be installed.

Usage

All commands support --json output of raw JSON (use when complete structured data is needed).

SCRIPT="<skill目录>/scripts/qm_reader.py"

python3 "$SCRIPT" entries --limit 20 # latest article list (default 60 articles) python3 "$SCRIPT" sources # source list (including id, category, article count; disabled sources are marked with ✗) python3 "$SCRIPT" source <source_id> # articles under a certain source python3 "$SCRIPT" entry <entry_id> # article body (original text; automatically falls back to the rewrite when the original text is empty) python3 "$SCRIPT" entry <entry_id> --translation # Chinese translation python3 "$SCRIPT" entry <entry_id> --rewrite # Qiaomu rewrite python3 "$SCRIPT" raw "/api/entry/" # raw JSON for any /api path


`<skill目录>` 即本 SKILL.md 所在目录。

## 典型工作流

1. **用户问"最近有什么新文章"** → 跑 `entries`，把标题和时间整理成简洁清单回复。
2. **用户要读/总结某篇文章** → 先用 `entries` 或 `sources` 拿到 entry id，再跑 `entry <id>`；
   如果正文质量差或用户偏好中文表达，改用 `--translation` 或 `--rewrite` 版本作为总结素材。
3. **用户想看某个订阅源的内容** → 先 `sources` 按名字找到 source id，再 `source <id>`。
4. **翻页**：`source` 命令返回 `nextCursor` 时，用
   `raw "/api/sources/<id>/entries?limit=40&ready=rewrite&cursor=<cursor>"` 取下一页。

## 禁用源说明

订阅源可能被服务端**禁用**（`sources --json` 中 `enabled: false`）。禁用源的
`/api/sources/{id}/entries` 接口会返回 **HTTP 404**，其文章也不会出现在跨源
`entries` 列表里——这不是网络故障，不要反复重试。脚本已对此做了友好提示，
遇到时应如实告知用户该源不可用，并建议换一个已启用的类似源。

## 回复用户的注意事项

- 列表输出里每篇文章的方括号内是 **entry id**，读取正文时要原样传给 `entry` 命令。
- 时间戳为服务器返回的毫秒 epoch，脚本已转成本地时间。
- API 只返回已就绪（ready=rewrite）的内容；服务端正在生成的文章不会出现在结果里。
- `sources` 文本输出中带 ✗ 前缀的源是禁用状态，不要对它们跑 `source <id>`。
- 网络失败会以非零退出码结束并打印错误原因（HTTP 状态码或 DNS/连接错误），
  此时如实告知用户即可，不要编造文章内容。

## 数据来源说明

此 API 与 QMReader iOS 客户端使用同一后端，接口契约参见项目中
`QMReader/APIClient.swift` 与 `QMReader/Models.swift`。主要端点：

| 端点 | 说明 |
|---|---|
| `/api/entries?limit=N&ready=rewrite` | 跨源最新文章 |
| `/api/sources?ready=rewrite` | 订阅源列表 |
| `/api/sources/{id}/entries?limit=&cursor=` | 单源文章，cursor 分页 |
| `/api/entry/{id}` | 文章详情（含 content、summary、rewrite.body 等） |
| `/api/entry/{id}/translation` | 中文翻译（段落对数组 content[].target/targetHtml） |
| `/api/entry/{id}/rewrite` | 乔木改写版（markdown body） |

About this skill

Usage