bestblogs-weekly-blogger

BestBlogs 周刊博客生成器 (Weekly Blogger)

从 BestBlogs.dev 已发布的周刊中，生成一篇图文并茂、风格连贯、具有个人洞察的博客文章。

博客不是周刊的简单搬运，而是一篇有主题线索、有层次感、有个人思考的深度导读。好的周刊博客让读者在 5 分钟内抓住本周 AI 领域最值得关注的趋势，同时在重点内容上获得超越摘要的理解。

完整 API 参数详情见 references/api_reference.md，博客写作风格指南见 references/blog_style_guide.md。

认证

所有请求需要 X-API-KEY 请求头。从环境变量 BESTBLOGS_API_KEY 读取密钥：

-H "X-API-KEY: $BESTBLOGS_API_KEY"

若 BESTBLOGS_API_KEY 未设置，提示用户配置。

接口地址：https://api.bestblogs.dev

进度清单

- [ ] 阶段一: 获取周刊数据
- [ ] 阶段二: 深度分析重点文章
- [ ] 阶段三: 收集个人洞察 ⚠️ 需用户输入
- [ ] 阶段四: 构思主题与结构
- [ ] 阶段五: 生成博客文章
- [ ] 阶段六: 生成配图与封面 ⚠️ 需确认风格
- [ ] 阶段七: 上传图片到 R2 并替换链接

阶段一：获取周刊数据

1.1 确定期数

用户通常会指定期数（如「写第 85 期博客」）。如果未指定，获取最新一期：

curl -s -X POST https://api.bestblogs.dev/openapi/v1/newsletter/list \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: $BESTBLOGS_API_KEY" \
  -d '{"currentPage":1,"pageSize":1,"userLanguage":"zh_CN"}'

1.2 获取周刊详情

curl -s "https://api.bestblogs.dev/openapi/v1/newsletter/get?id={ISSUE_ID}&language=zh_CN" \
  -H "X-API-KEY: $BESTBLOGS_API_KEY"

从响应中提取：

1.3 读取参考博客

博客默认输出到 /Users/gino/Documents/Github/ginonotes-blog/posts/reading/notes/，用户也可以指定其他路径。

在该目录下查找最近的博客文件作为风格参考（最多 3 篇）:

ls /Users/gino/Documents/Github/ginonotes-blog/posts/reading/notes/ | grep bestblogs_weekly | tail -3

使用 Read 工具读取最近一篇（如有多篇，优先读最新的），理解：

1.4 初步分析

从周刊推荐语和文章列表中识别：

阶段二：深度分析重点文章

不是所有文章都需要深度分析。选择 5-8 篇重点文章获取原始内容，其余依赖周刊提供的 summary 即可。

2.1 选择重点文章的标准

按以下优先级选取：

2.2 获取文章 Markdown 内容

对选中的重点文章，并行获取原始内容（每批 5 个）:

curl -s "https://api.bestblogs.dev/openapi/v1/resource/markdown?id={ARTICLE_ID}" \
  -H "X-API-KEY: $BESTBLOGS_API_KEY"

返回的 data 字段为 Markdown 字符串。内容可能很长，重点关注：

如果 markdown 返回 null，回退到周刊提供的 summary 和 mainPoints。

2.3 深度分析要点

对每篇重点文章提炼：

阶段三：收集个人洞察

⚠️ 这是需要用户参与的环节。

向用户询问以下信息（简洁地一次性问完，不要逐条追问）:

周刊推荐语中通常包含个人近期动态和思考（一般在第二段），可以作为参考素材。如果用户表示没有特别想法或让 AI 自由发挥，可以基于推荐语中的内容生成，但仍建议向用户确认是否需要补充。

阶段四：构思主题与结构

这一步在写作前完成，决定博客的骨架。

4.1 确定主题线索

从周刊标题和推荐语中提取关键词作为全文主线。好的主题线索能把 20 篇文章串联成一个连贯的故事，而不是按 MODELS/DEV/PRODUCT/NEWS 机械分类。

参考模式（来自往期）:

4.2 设计章节结构

通常 5-7 个章节，每个章节围绕一个子主题，包含 2-5 篇文章。章节之间有逻辑递进关系。

结构原则:

篇幅分配不应均匀。重点文章（如本周的头条发布、最有深度的方法论文章、个人最喜欢的内容）应该用 200-400 字展开讨论，包含文章的核心论点、关键细节和个人解读。普通文章 50-100 字带过即可。这种层次感是博客区别于简单列表的关键。

4.3 简要大纲

在开始写作前，先列出：

阶段五：生成博客文章

5.1 文件信息

默认路径: /Users/gino/Documents/Github/ginonotes-blog/posts/reading/notes/{DATE}_bestblogs_weekly_issue_{N}.mdx

其中 {DATE} 为 YYYYMMDD 格式，{N} 为期数。用户可以指定其他输出路径。

Frontmatter:

---
title: BestBlogs 周刊第 {N} 期：{关键词}
date: {YYYY-MM-DD}
description: {一句话描述本期主题和亮点，50-80 字}
category: reading
tags: BestBlogs, {3-4 个相关标签}
cover: cover_bestblogs_{N}.png
slug: bestblogs-weekly-issue-{N}
---

5.2 图片占位符

写作阶段先使用占位路径，阶段六会生成实际图片并替换：

![章节描述](bestblogs-issue-{N}-{seq}.png)

其中 {seq} 从 1 开始递增。通常 6-8 张图。首图和尾图固定：

5.3 写作风格

详见 references/blog_style_guide.md，核心要点：

5.4 结构模板

开头段（2-3 段）
  - 本期关键词和主题概述
  - 个人近期动态（1-2 句）
  - 首图

章节 1: {重磅内容}
  - 章节配图
  - 重点展开 1-2 篇核心文章
  - 其他相关文章简要提及

章节 2-5: {各子主题}
  - 按主题组织，不按分类
  - 重点文章深入讨论，普通文章简要串联
  - 章节间有过渡句

思考/感悟章节
  - 深度内容或哲学性讨论
  - 与本期主题呼应

结尾段
  - 回扣主题关键词
  - 个人感想（3-5 句，点到为止）
  - 链接到 BestBlogs.dev 完整周刊
  - 「保持好奇，我们下周见。」
  - 尾图

5.5 输出

使用 Write 工具直接创建 MDX 文件。写完后告知用户：

继续进入阶段六生成配图。

阶段六：生成配图与封面

使用 image-gen 技能的 CLI 脚本为博客生成配图和封面。如需更精细的维度定制，可参考 cover-image 和 article-illustrator 的提示词模板。

6.1 环境检查

确认 GOOGLE_API_KEY 环境变量已设置（默认使用 Google Gemini 生成图片）。

6.2 生成文章配图

创建工作目录存放图片：

mkdir -p /tmp/bestblogs-issue-{N}/

为博客中的每张配图生成提示词并调用 image-gen 生成。每张图的提示词应基于：

使用 image-gen 的 CLI 生成图片：

SKILL_DIR=~/.claude/skills/image-gen
bun run ${SKILL_DIR}/scripts/main.ts \
  --prompt "{图片提示词}" \
  --image /tmp/bestblogs-issue-{N}/bestblogs-issue-{N}-{seq}.png \
  --provider google \
  --model gemini-3-pro-image-preview \
  --ar 16:9 \
  --quality 2k

每张图片依次生成，生成后确认图片文件存在。如果生成失败，重试一次。

6.3 生成封面图

封面图使用不同的宽高比和风格：

bun run ${SKILL_DIR}/scripts/main.ts \
  --prompt "{封面提示词，包含标题关键词和期数}" \
  --image /tmp/bestblogs-issue-{N}/cover_bestblogs_{N}.png \
  --provider google \
  --model gemini-3-pro-image-preview \
  --ar 16:9 \
  --quality 2k

6.4 确认图片

生成完成后列出所有图片，告知用户：

阶段七：上传图片到 R2 并替换链接

7.1 环境检查

确认以下环境变量已设置：

7.2 上传配图

使用 image-gen 中的 R2 上传脚本批量上传：

SKILL_DIR=~/.claude/skills/image-gen
bun run ${SKILL_DIR}/scripts/upload-r2.ts \
  --batch /tmp/bestblogs-issue-{N}/ \
  Banana/

脚本会输出每个文件的公开 URL（格式：{R2_PUBLIC_URL}/Banana/{filename}）。

7.3 上传封面图

封面图上传到单独路径：

bun run ${SKILL_DIR}/scripts/upload-r2.ts \
  /tmp/bestblogs-issue-{N}/cover_bestblogs_{N}.png \
  covers/cover_bestblogs_{N}.png

7.4 替换博客中的链接

用上传后的实际 URL 替换博客文件中的占位路径：

使用 Edit 工具逐个替换。

7.5 完成

告知用户：

错误处理

重要: 始终先检查 response.success 再处理 response.data。