blog-publisher

name	blog-publisher
description	从 URL 整理并发布中文博客文章。当用户提供文章链接，希望改写成中文技术博客并保存到博客仓库时使用。

Blog Publisher

从 URL 抓取文章内容，整理萃取为具备个人洞见的中文技术博客，并发布到博客仓库。

发布前请先阅读 references/blog-conventions.md，其中包含 frontmatter schema、有效 tags、目录命名规则、写作风格要求与 commit 格式。

---

工作流程

Step 0 — 确认项目根目录

git rev-parse --show-toplevel

如果命令失败（不在 git 仓库中），停止执行并提示用户先切换到博客项目目录。

---

Step 1 — 抓取文章内容

抓取用户提供的 URL，提取核心论点、技术原理、实践经验与代码示例。

抓取工具优先级与降级策略：

优先级	说明	工具
1（默认）	所有 URL 一律先走主通道	markdown.new — POST https://markdown.new/ 或 https://markdown.new/<url>
2（回退）	markdown.new 返回空或报错	chrome-devtools
3（兜底）	chrome-devtools 仍然失败	agent-browser

Medium 会员文章（Member-only story）特殊处理：

• 将 Medium URL 拼接到 https://freedium-mirror.cfd/ 后面，再交给 markdown.new。 示例：https://freedium-mirror.cfd/https://alirezarezvani.medium.com/...
• 引用说明中的链接继续保留原始 Medium 链接。

Reddit / 论坛讨论帖特殊处理：

• 抓取评论区时，优先覆盖：赞同并补充经验的、指出风险的、明确反对的代表性声音。

检测到未安装agent-browser时，自行安装并重试抓取

npm install -g agent-browser
agent-browser install  # Download Chromium

---

Step 2 — 消化与重构（撰写博客）

以资深技术博主的视角，对内容进行深度总结与重构。不要做机械的流水账翻译，而是要判断先行、融入思考、结构灵活。

2.1 写作风格与结构

• 判断先行：开篇直接抛出核心论点或你阅读后的最大启发，摒弃“本文总结了…”等机器味开场白。
• 灵活叙事：不要硬套传统的五段式模板。根据内容顺其自然地展开，如“核心争议 -> 各方观点 -> 我的取舍”，或“痛点 -> 巧妙解法 -> 局限性”。
• 去翻译化与高信息密度：用博主和你对话的语气表达。去除啰嗦的转场（“换言之”、“值得注意的是”），合并冗余段落，直击要害。
• 保留关键骨架：代码片段、核心数据、图表逻辑、关键命令必须准确精炼地保留。
• 复用 humanizer-zh：完成初稿后，必须加载 humanizer-zh，清理通用中文 AI 写作痕迹，尤其是段末收尾总结句、三段式结构、升华句、对比框架、提示语引导、报告腔、形式感连接词。
• 保留博客专属约束：humanizer-zh 只负责通用文本去 AI 味；本文发布前还要额外检查博客语境下的内容契约。
• 图后 prose 与 alt 对齐：图片 alt text 列了几项，正文 prose 就要展开同样几项，不能错位。改正文之前先看图 alt，改完检查图 alt，必要时图也得重画。

2.2 frontmatter 与文件操作

1. 读取 src/constants.ts，以 FRONTMATTER_TAGS 作为 tags 的唯一来源。
2. 从主题推导简洁的 kebab-case slug（英文优先）。
3. 使用今天的日期作为 date 和 lastUpdated。
4. 检查 content/blog/YYYY-MM-DD--{slug} 是否已存在：
   • 不存在 → 新建
   • 存在且为空 → 复用
   • 存在且非空 → 追加后缀（如 -2）避免冲突
5. 创建文件：content/blog/YYYY-MM-DD--{slug}/index.mdx
6. 正文使用简体中文。
7. 正文开头（紧接 frontmatter 之后）插入引用说明块：

:::note[引用说明]
本文基于 <作者名> 的文章学习与整理：[<标题>](<URL>)。
:::

2.3 必须遵守的硬性约束

1. 术语准确：遇到专有名词、库名、API、核心概念，如果不确定准确的中文习惯叫法，宁可保留英文原词。
2. 站内链接规范：引用本站其他博客文章时，直接使用 slug（如 (/harness-engineering-agent-first)），绝不要添加 /blog/ 前缀。
3. 标题精简：小节标题使用直接的结论或名词短语，不要用冗长的提问或过度铺垫。

---

Step 3 — 校验

执行 blog-conventions.md 中的校验清单，并且本地验证通过：

cd $BLOG_ROOT
pnpm build:astro

发布前人工复核清单：

• 所有必填 frontmatter 字段均已填写，且 tags 符合 src/constants.ts。
• 目录名格式为 YYYY-MM-DD--{slug}，文件名为 index.mdx。
• 开篇是否做到了判断先行，直接给出了核心价值。
• 表达是否自然流畅，消除了大模型的“整理稿”或“AI翻译工厂”气味。
• 核心技术事实、代码、数据是否准确无误地保留。
• ## / ### 小节标题是否精炼直接。
• 站内博客引用链接是否使用了正确的 slug 格式（不含 /blog/ 前缀）。

---

Step 4 — 提交并推送

cd $BLOG_ROOT
git status --short
git add content/blog/YYYY-MM-DD--{slug}/
git commit -m 'docs: add post "<文章标题>"'
git push origin main

commit 格式遵循 blog-conventions.md 的规定。

提交边界： 除非用户明确要求，只暂存新建的文章目录，不包含其他文件。

---

技术博主写作原则

原则	说明
判断先行	读者时间宝贵，把结论和最深刻的洞见放在最前面
拒绝翻译腔	像人一样说话，不搞堆砌辞藻，用最简洁直接的中文表达
灵活重构	结构为内容服务，抛弃套路化的章节骨架，顺着思考逻辑写作
尊重原作者	始终保留引用说明，做好来源追踪和致敬