bestblogs-read, 资源深度阅读（Local）

何时使用

• 用户想让本地 LLM / reading UI 消费某篇 BestBlogs 内容的正文。
• 用户想看某条资源的元信息 + 全文 Markdown。
• 用户想在阅读的同时把 "read" 行为回传，让 BestBlogs 的个性化飞轮跟得上。

原语

原语	CLI	说明
bestblogs.resource.meta.get	内部调用 /resources/{id}/meta	meta
bestblogs.resource.markdown.get	内部调用 /resources/{id}/markdown	正文 markdown
bestblogs.resource.read.mark	内部调用 POST /resources/{id}/read	回传已读
bestblogs.resource.deep_read.prepare	bestblogs read deep <id>	一次完成 meta + markdown + mark read

只暴露 deep_read.prepare 作为主原语, , 它是 CLI bestblogs read deep 的 wrap，并行拉 meta+markdown，串行 mark read。

动作

完整深读（默认，包含 mark read）

bestblogs read deep RAW_xxx --json

返回：

{
  "success": true,
  "data": {
    "meta": {
      "resourceId": "RAW_xxx",
      "title": "...",
      "url": "...",
      "resourceType": "ARTICLE",
      "language": "en_US",
      "score": 88,
      "sourceName": "..."
    },
    "markdown": "# Title\n\n...",
    "readMarked": true,
    "markError": null
  }
}

只要正文 Markdown（喂给本地 LLM）

bestblogs read deep RAW_xxx --markdown-only

输出纯 Markdown（stdout），适合 | anthropic / | llm 等管道。

不回传 read 行为（如只是预览）

bestblogs read deep RAW_xxx --no-mark-read --json

错误处理

• 404 / NOT_FOUND → 资源不存在或已下架；告诉用户
• 资源为私有源（sourceVisibility=PRIVATE）且当前用户未订阅 → meta 可能返回 null；提示用户订阅对应源
• mark read 失败时 CLI 返回 readMarked=false, markError="..." 而不是整体失败，skill 应保留正文给用户并告知 "已读回传失败，不影响阅读"

组合建议

• 常用链：bestblogs-discover today → 从 candidates[] 挑一条 → bestblogs-read deep <id> --json → 把 markdown 喂给本地 LLM 做总结/提问 → bestblogs-capture 做笔记保存
• 不要重复回传：默认就会 mark read，除非用户明确只是预览再决定是否读