技术博客深度写作

Battle-tested on heyuan110.com — a bilingual (EN/ZH) AI engineering blog. Every rule in this skill was earned from real GSC/GA data, not theory.

核心理念

这不是一个内容生成工具，而是一个观点表达工具。

每篇文章必须能回答：我到底推荐什么？反对什么？读者看完能带走什么判断？

如果写完一篇文章，删掉所有观点句子后文章还能成立——说明这篇文章没有观点，是废品。

优先级铁律（2026-07 用户定调）：SEO/GEO 友好是及格线——不收录、不被 AI 引用就白写；读者读着愉悦是得分项。两者不冲突：机器要的结构化（FAQ/keywords/可引用块/结构化数据）圈在指定区域（front matter、文末、独立 blockquote），正文留给人——而"首句即结论"的人类友好写法恰恰也是 featured snippet 和 AI 摘要最爱抓的格式。

双轨制：文章分两档。旗舰文（每周 1-2 篇）：慢写、带自己跑出来的真实验数据、有人味、目标是被 HN/Reddit 转和被人记住——博主的声誉由旗舰文定义。工作文（其余）：SEO/GEO 补缺，走标准流程,但同样必须过下面的可读性宪法。没特别说明时默认工作文标准。

博客信息

Hugo 版本: v0.153.2+（Extended）
主题: hermit-V2
内容目录: content/posts/
博客地址和具体配置从项目的 hugo.toml 中动态获取

强制执行流程

步骤1 确认需求 → 步骤2 深度研究 → 步骤3 形成判断（⛔） → 步骤4 撰写 →
步骤5 封面图+配图 → 步骤6 质量门禁（⛔） → 步骤7 发布+分发

⚠️ 每一步必须完成后才能进入下一步，不可跳过。特别是"形成判断"⛔ 步骤。

步骤 1：确认需求

向用户确认：

主题：写什么？
素材：参考链接？
目标关键词：（可选）
语言：默认中英文都写，角度可以不同

如果用户已提供，直接进入步骤 2。

步骤 2：深度研究

2.1 读取素材

用户提供的链接必须认真阅读全文，不可凭标题猜测。按素材类型分流：

网页文章：优先 WebFetch，反爬时用 Playwright MCP
YouTube / Bilibili 视频：⛔ 禁止用 WebFetch（只能拿到 footer），必须调 youtube-fetch skill

``bash bash .claude/skills/youtube-fetch/fetch.sh <url> # 等几分钟（无字幕视频会自动 whisper 转写） # 然后 Read cache/youtube/<videoId>/transcript.txt 拿全文 # Read cache/youtube/<videoId>/metadata.json 拿元数据 ``

PDF / 文档：直接用 Read 工具
GitHub 仓库：用 gh CLI 或 WebFetch GitHub URL

2.2 ⚠️ "参考文章写深度文"特殊模式

这是最常见也是最容易写废的场景。当用户说「参考这个链接/文章，写一篇 X 相关的文章」：

⛔ 绝对禁止：

把参考文章翻译/改写/总结当成自己的文章
沿用参考文章的章节结构和论证路径
只引用参考文章一个来源，没有外部交叉验证
用"原文提到"、"作者认为"这种转述为主的写法

✅ 必须做：

把参考文章当成"起点"而非"答案"：读完后，问自己——原作者有没有说错？漏掉了什么？哪些判断我不同意？
至少 3 个额外信息源：官方文档、GitHub issues、社区讨论、benchmark、对比项目——交叉验证
差异化定位：想清楚"我的文章 vs 参考文章"的不同——是更深（补充技术原理）、更实（增加实操经验）、更新（加入最新进展）、还是更批判（指出原文忽略的局限）？写在 steps 3 的核心立场里
原创占比 ≥ 70%：参考文章的信息只能作为起点或引用，不能构成文章主体
明确引用标注：引用原文观点时用"Hermes 官网文档指出..."或"根据 [原文](url)"，清楚区分一手来源 vs 自己的判断

自检问题：如果读者同时读了参考文章和你的文章，他会觉得"白读了"还是"这两篇互补、各有价值"？如果是前者，回去重写。

2.3 主动研究（不能只靠用户给的素材）

搜索该主题的最新进展和权威资料（官方最新文档、changelog、release notes）
搜索反对意见和争议点——这是形成判断的关键输入（HN、Reddit、Twitter 讨论）
搜索常见误解和踩坑经验——这是写出深度的弹药
查找 benchmark、定价、真实用户反馈等可量化数据

2.4 获取已有文章列表

ls content/posts/ai/

目的：避免与已有文章重复；找到可以内链的相关旧文。

步骤 3：形成判断 ⛔ 必须通过

这是整个 skill 最重要的步骤。不完成这一步，禁止开始写作。

在写任何正文之前，必须先产出一份判断框架，回答以下 6 个问题：

3.1 我的核心立场是什么？

用一句话表达：关于 [主题]，我认为 [判断]，因为 [理由]。

示例：

✅ "关于 Harness Engineering，我认为它是 2026 年 AI 工程最重要的范式转变，因为 LangChain 不换模型只改 harness 就从第 30 名升到第 5 名。"
❌ "Harness Engineering 是一个新兴的概念。"（← 没有判断，只有陈述）

3.2 行业常见的误解是什么？（至少 2 个）

列出读者可能相信但实际上错误或误导的观点。

示例：

误解 1："模型越好 Agent 越强" → 实际上 harness 决定 80% 的效果
误解 2："CLAUDE.md 写得越详细越好" → ETH Zurich 研究证明超过 60 行反而降低表现

3.3 真实案例/数据是什么？（至少 3 个）

不是引用官方宣传，而是真实的使用经验、benchmark 数据、社区反馈。

示例：

OpenAI Codex 团队用 harness engineering 写了 100 万行代码
我的博客 CTR 从 0.33% 通过 FAQ 优化提升到 X%
Cursor Composer 2 在 TerminalBench 上只比 Claude 高 3.7 分

3.4 什么时候该用？什么时候不该用？

明确的边界条件和 trade-off，不要说"视情况而定"。

示例：

该用：代码库 > 10 万行、需要多文件重构 → 用 Claude Code
不该用：快速补全、行内建议 → 用 Copilot
代价：Claude Code Max 每月 $200，对个人开发者贵

3.5 读者看完能带走什么？

一个具体的行动建议或判断框架。

示例：

"如果你的项目满足 X 条件，从今天开始用 Y"
"先试 A，如果遇到 B 问题再换 C"

3.6 文章的叙事弧线

不是章节目录，而是论证逻辑：先建立什么认知 → 打破什么误解 → 给出什么判断 → 用什么证据支撑。

示例：

1. 开头：抛出反常识的结论（"模型是 AI Agent 中最不重要的部分"）
2. 建立背景：为什么这个结论违反直觉
3. 核心论证：用 3 个真实案例证明
4. 误区拆解：指出常见的错误做法
5. 实操指南：读者现在就能用的方法
6. 边界说明：什么时候这个建议不适用

3.7 读者价值自检（"读完值不值"测试）

在判断框架完成后，用以下标准检查文章是否值得读者花 5 分钟：

认知升级（读者学到了自己没想到的判断）：

读完这篇文章后，读者会改变什么观点或决策？如果答案是"不会改变任何事"，这篇文章不值得写。

可带走的东西（马上能用）：

文章必须包含至少一个读者可以今天就用的具体产物：
- 决策框架/流程图（"遇到 X 就选 Y"）
- 可复制的配置/命令/代码片段
- 速查表/对比表
- 具体的预算/方案建议

避坑价值（本来会踩的坑）：

文章必须包含至少 2 个"如果不读这篇文章，读者可能犯的具体错误"。不是抽象的误区，是会导致浪费时间或金钱的具体坑。

⛔ 如果上面 6+1 个问题任何一个回答是空的或模糊的，禁止进入下一步。回去补充研究。

步骤 4：撰写文章

基于步骤 3 的判断框架写作，不是从零开始"生成内容"。

4.0 先选文章形态（反模板化第一关）

动笔前先从四种形态里选一种——结构必须服务素材,禁止套万能骨架：

形态	适用	结构特征	禁忌
新闻快评	热点事件 24-72h	事实钉死 → 一个鲜明判断 → 对读者的三个影响,短平快	别写成百科;可以没有决策树
实测战报	自己真跑过的工具/模型	按"我想干嘛→哪里卡→怎么解→账单/数字"的故事线走	没跑过就不许用这个形态
深度论证	观点文/趋势判断	一个反常识论点吃全文,证据层层推进,篇幅偏科	别均匀覆盖 5-8 个方面
参考手册	教程/配置/速查	表格和代码块为主,文字极短,扫读优先	别硬加"叙事"

决策树/速查表/象限图只在内容真的是"选型决策"时用——连续几篇都出现同款图表 = 模板化警报。

4.1 Front Matter

完整模板详见 [references/frontmatter-template.md](references/frontmatter-template.md)。

关键规则：

中英文版默认都创建
每篇 3-5 个 FAQ（[[params.faqItems]]）
封面图正文第一行引用
中英文 keywords 独立

4.2 写作原则（优先级从高到低）

第一优先：观点驱动

每个章节必须服务于步骤 3 确定的核心立场
如果一个段落不支持也不反驳核心论点，删掉它

第二优先：证据支撑

每个判断必须有数据、案例或代码示例
没有证据的观点不如不写

第三优先：反常识价值

步骤 3 识别的误区必须在文章中明确拆解
拆解方式：先说常见理解 → 再说为什么错 → 再给正确理解

第四优先：可带走价值

每篇文章必须包含至少一个读者今天就能用的具体产物
决策框架、速查表、配置模板、命令片段——读者截图保存的那种东西
如果全文删掉只留这一个产物，读者仍然觉得"没白来"

第五优先：边界诚实

步骤 3 的 trade-off 必须在文章中体现
"什么时候不该用"比"什么时候该用"更有价值

第六优先：不均衡原则（反百科全书）

最有趣/最有信息增量的 20% 内容,配得上 60% 的篇幅
一节你自己写着都无聊 → 读者更无聊 → 删掉或一句话带过,把字数省给主菜
好文章是偏科的:H2 数量和长度不需要整齐——3 个不等长的章节胜过 7 个 500 字的标准块

4.3 逐段打磨机制（自我迭代）

不要一次性生成全文。按章节写，每写完一个章节立即自检并打磨。

写作节奏：

写一个章节（300-800 字）
立即自检，用以下 5 个问题审视刚写的内容：

- 有没有"一句话观点"？→ 必须展开成完整论证（现象 → 原因 → 证据 → 结论） - 有没有空洞的判断？→ 必须补数据或案例（"效果很好" → "CTR 从 0.33% 升到 1.5%"） - 有没有只陈述不分析？→ 必须加"为什么"和"意味着什么" - 段落是否太短（< 3 句）？→ 短段落通常意味着论证不充分，展开它 - 删掉这段后文章是否仍然成立？→ 如果成立，这段没有存在价值

打磨不合格的段落，直到通过自检
进入下一章节，重复 1-3

可读性宪法（2026-07 重写——治"字多晦涩",但厚度不许降）：

先分清两个概念：空洞 = 没有新信息/证据的句子多；晦涩 = 有信息但排版成墙。旧规用"段落必须 5-10 句"防空洞,结果制造了晦涩。新规把两者解耦：

厚度红线不变：判断框架 6+1 问、≥3 真实案例/数据、≥2 误区拆解、字数体量（EN 2000+ 词 / ZH 4000+ 字）——这些硬指标一条不松。空洞的解法是补证据,永远不是把段落写长。
一段一个观点,观点在第一句（金字塔原理）。读者扫首句就能拼出全文逻辑链——这同时是 featured snippet 和 AI 引用最爱的格式（SEO/GEO 加分,不是妥协）。
中文段落 ≤4 行（手机屏一眼装下）。一个论证需要 8 句就切成 2-3 段,每段有自己的小结论。
节奏变化：长段后跟一个短句段。独立成段的一句狠话,比埋在段落里响十倍。
每屏一个锚点：小标题/表格/加粗结论/图,任何一屏(约 300 字)不能全是素文字。
列表用于并列速查没问题；但论证仍然必须是文字推进——列表堆不出观点。

仍然禁止：

❌ 无证据的观点句（"效果很好" → "CTR 从 0.33% 升到 1.5%"）——这才是空洞的定义
❌ 只陈述不分析——每个事实后面要有"所以呢"

4.4 写作风格

必须做：

真收据的第一人称：带可核实的自己跑出来的数字/截图/翻车记录（"3 个任务烧掉 5 小时额度的 73%"）。没跑过就明说"我没跑过,以下基于 X 的实测"——诚实比表演可信
给出明确推荐（"如果你 X，我建议 Y"）
用具体数字说话（"CTR 从 0.33% 提升到 1.5%"，不是"显著提升"）
人味：允许吐槽、惊叹、自嘲、一句跑题再拉回来。写完朗读一段——不像对朋友说话就重写
开头钩子轮换：场景/故事/刺痛的数字/挑衅的问题/一句反常识,至少五种轮着用。连续两篇同款开头 = 失败

禁止做：

表演性第一人称（没跑过却写"我实测发现"）——这是信誉自杀
中性总结（"总的来说，X 有优点也有缺点"）
空话（"随着 AI 的发展..."、"未来可期"）
功能罗列不做判断
结构太对称整齐（每个工具都说 3 个优点 3 个缺点 — AI 味太重）
报告腔/论文腔——读者是来看博主的,不是来看咨询交付物的

4.5 英文优先 + 中文本土化改写 ⛔（2026-07 用户定调，硬要求）

英文版是主版本——收入主要来自英文市场，所有文章一律先写英文版，定稿后再产出中文版。

英文版硬要求：地道美国英语，禁止任何中文直译痕迹。写完自查三条：

口语节奏：用缩写（it's / you'll / doesn't）和美式短句；"Cards on the table" 而不是 "My position, on the table"
习语走美式惯用：napkin math、pencils out、making the rounds、fifty cents to two bucks——不许逐字对应中文说法（"摆桌面上""这本账"之类硬译）
逐段朗读测试：任何一句读起来像"先想了中文再翻过来"（镜像中文语序、量词直译、成语硬译）就地重写。参照系是 Simon Willison 式的直接英文博主语感

中文版定位：英文版的本土化改写——不是机械翻译，也不是重新写一篇：

内容对齐：事实、数字、论点、案例、结构与英文版一一对应，信息量不许缺斤短两
表达重塑：用词、语序、节奏按中文读者（刷手机的国内工程师）习惯重写；习语换成中文里自然的说法（napkin math → 粗算一笔账），案例补充国内读者需要的背景
禁止翻译腔：不出现"让我们""正如我们所见""值得注意的是"这类逐句直译产物；写完朗读，像本土中文博主说话
两版 keywords 仍完全独立（中英文搜索词不同）

4.6 链接策略

内链 4-6 个（必须含 Related Reading）
外链 3-5 个（官方文档、GitHub、权威来源）
内链要自然嵌入正文（"我在[之前的文章](/posts/ai/xxx/)中提到过..."），不要集中堆在文末
外链优先链接到一手来源（官方文档、论文、GitHub），不链二手转载

4.7 SEO 优化

关键词密度：

核心关键词在正文中自然出现 3-5 次（不要刻意堆砌）
第一段必须包含核心关键词
GEO 可引用块(2026-07 起):关键结论必须自带日期+数字("As of July 2026, Sonnet 5 costs $3/$15"),AI 引擎(ChatGPT 搜索/Perplexity/AI Overviews)引用时会保留归属——被 AI 引用是新流量入口,GA4 AI Assistant 渠道互动率全站最高
至少 2 个 H2 标题包含核心关键词或近义词
图片 ALT 文本包含关键词

文章结构：

H2 用于主要章节（5-8 个），H3 用于子章节
每个 H2 章节 300-800 字，不要出现超过 1500 字无小标题的长段
目录（toc = true）对长文必须开启
开头 150 字内必须点明文章核心价值（Google 用这段做搜索摘要）

Meta 优化：

title：50-60 字符，核心关键词在前 30 字符内，含数字或年份效果更好
description：120-160 字符，直接回答用户搜索问题（不是概述文章），包含核心关键词
keywords：5-8 个，包含长尾搜索词（"Claude Code 怎么用" 而不只是 "Claude Code"）
FAQ：问题用用户真实会搜的句式（"X 是什么？"、"X 和 Y 哪个好？"、"怎么用 X？"）

避免的 SEO 错误：

关键词堆砌（同一个词出现 10+ 次）——Google 会降权
标题和内容不匹配（标题说"对比"但正文没有对比）——高跳出率
全文无小标题的长段落——影响可读性和 Google 结构化理解

4.8 嵌套代码块

外层反引号数量必须大于内层。

4.9 草稿审阅 checkpoint ⛔

默认工作流：先写英文版完整草稿 → 暂停向用户汇报 → 确认后再产出中文版。

为什么不能一次两版全写完：

英文版是主版本（见 4.5）：中文版是它的本土化改写，必须等英文版定稿才能开工
一次写完两版，如果英文版观点/结构需调整，中文版也要跟着重做，浪费一倍工作量
用户对英文版的反馈会直接决定中文版改写的基线

汇报模板（写完英文版后）：

英文版草稿完成：<文章目录>/index.md
- 字数：约 N 字
- 核心立场：<一句话总结文章观点>
- 章节结构：<H2 列表>
- 主要案例/数据：<3 条>
- 预计配图：<mermaid X 个 / architecture Y 个 / AI 生图 Z 张>

是否按此方向写中文版？有什么要调整的？

用户可能反馈：

立场不够鲜明 → 回步骤 3 重新做判断框架
案例不够硬 → 回步骤 2 补充研究
结构OK但某章要改 → 局部改英文版后再写中文
直接通过 → 产出中文版（按 4.5 定位：内容对齐英文版，表达按中文读者习惯本土化——不是机械翻译，也不是另写一篇）

例外：用户明确说"一次写完两版"或"只写中文"时跳过这个 checkpoint。

步骤 5：封面图 + 内容配图

文章写完后，根据内容生成图片。

5.1 封面图（必须）

调用 blog-cover-image skill：

/blog-cover-image <文章目录> --quick

文件名：cover.webp，1200×630px，WebP 质量 85
统一英文生成，中英文共用
封面图在正文第一行引用：![ALT](cover.webp)

5.2 内容配图（必须，至少 2 张；3-4 张更好）

用户明确偏好（2026-07）：图表对比是表达论证的好办法，适当多用。 具体：

凡是"A vs B"、多方案选型、价格/能力权衡的论证，必须配对比表（markdown table）或对比图（mermaid quadrantChart/决策树），不能只用文字说
流程、时间线、分层关系优先用 mermaid 画出来，而不是一段文字描述
速查表/决策框架这类"可带走产物"尽量做成表格——读者会截图保存
上限意识：图是服务论证的，不是堆数量；单篇 mermaid 建议 2-4 张，画完跑 node scripts/check-mermaid.mjs 验证

第一步：按图表类型选对应的 skill

图表类型	首选 skill	输出形式	渲染方式
流程图 / 决策树 / 时序图 / 状态机 / 思维导图 / ER 图 / 甘特图 / 类图	`mermaid`	``mermaid` 代码块	Hugo 主题原生渲染（本地 JS）
分层系统架构（User→App→Data→Infra）	`architecture`	内嵌 HTML + CSS	Hugo `unsafe=true` 直接渲染
富视觉信息卡 / Bento 概览 / 数据看板 / 对比矩阵	`blog-diagram`	AI 生成 WebP	`![](diagram-xxx.webp)`
概念插图 / 场景化插画	`blog-illustrator`	AI 生成 WebP	`![](illustration-xxx.webp)`
封面图	`blog-cover-image`	AI 生成 WebP	`![](cover.webp)`

第二步：按优先级规则决策（文本结构化 > AI 位图）

能用 mermaid 表达的优先 mermaid —— 可编辑、可搜索、中英文各自独立渲染、SEO 友好、响应式
分层架构优先 architecture —— 响应式、Hugo 原生、无外部依赖
剩下才考虑 AI 生图 —— 富视觉信息卡走 blog-diagram，场景化插画走 blog-illustrator

第三步：调用

# mermaid / architecture —— 让 AI 直接写代码嵌入文章 markdown
# （不是一个独立的 CLI 命令，是写作过程中直接产出）

# AI 生图 —— 独立 skill 调用
/blog-diagram <文章目录> --layout bento-grid --style corporate
/blog-illustrator <文章目录> --quick

专业图表（按需启用，不在默认流程里）：

graphviz 复杂依赖 / 调用图
uml 类图 / 时序图 / 活动图 / 组件图
network 企业网络拓扑（Cisco / Citrix 图标）
bpmn 业务流程 / 集成模式
cloud AWS / Azure / GCP / 阿里云架构图（官方图标）
archimate 企业架构（TOGAF）
infographic KPI 卡片 / 时间线 / SWOT
infocard 编辑风格信息卡
canvas 自由定位思维导图 / 知识图谱
vega 数据驱动图表（柱状 / 折线 / 热力 / 散点）

需要哪种按文件名查阅 .claude/skills/<name>/SKILL.md。

⚠️ 本项目 Hugo 集成规范（已配置到位，直接用，不要改）：

配置点	位置	作用
mermaid JS 本地托管	`static/js/mermaid.min.js`	不依赖 jsdelivr CDN，国内读者加载稳定
mermaid 深色主题	`layouts/_partials/mermaid.html`	自定义 themeVariables 让菱形 / 连线 / 分支标签在深色背景高对比
HTML unsafe 开启	`hugo.toml` → `markup.goldmark.renderer.unsafe = true`	architecture skill 的 HTML 可直接嵌入

避坑经验（2026-04 沉淀）：不要用默认的 cdn.jsdelivr.net 加载 mermaid.esm，国内读者会看不到渲染结果；架构图也不要走 AI 生图，mermaid/architecture 的可编辑性和响应式远胜 WebP。

配图规范（不变）：

WebP 格式（AI 生图）：质量 85，最大宽度 1200px，英文生成，中英文共用
命名：diagram-xxx.webp / illustration-xxx.webp / cover.webp
中英文版本都需要在对应位置插入引用（mermaid/architecture 代码是独立的两份，中英文可以用不同语言各写一份）

一篇文章至少要有封面图 + 2 张内容配图。 纯文字长文没有配图会严重降低读者体验和停留时间。

步骤 6：质量门禁 ⛔

以下检查项必须全部通过，任何一项不通过必须回去修改。

门禁优先级：SEO 检查 + GEO 可引用块 = 及格线(不收录、不被 AI 引用就白写,一票否决);深度检查 + 可读性检查 = 得分项(决定读者会不会回来和转发)。两者都必须过,冲突时先满足及格线、再用排版手段满足得分项——它们几乎从不真冲突。

深度检查（最重要）

核心立场清晰：能用一句话概括文章的判断
至少 2 个误区拆解：指出了行业常见但错误的理解
至少 3 个真实案例/数据：不是引用官方宣传
明确的 trade-off：说了什么时候不该用
有行动建议：读者看完知道下一步做什么
没有空话：搜索全文，不存在"未来可期"、"值得关注"等废话
真收据：第一人称处有可核实的数字/截图/翻车记录；没跑过的地方诚实标注了来源
无空洞观点句：每个判断句后面跟着证据（数字/案例/引用），空洞的解法是补证据不是加长段落

可读性检查（2026-07 新增——读着愉悦是得分项）

一段一观点、首句即观点：抽查 5 个段落,首句拼起来能还原该节逻辑链
中文段落 ≤4 行：不存在手机屏装不下的文字墙
每屏有锚点：任意连续 300 字内有小标题/表格/加粗结论/图之一
朗读测试：随机读一段,像对朋友说话,不像论文/咨询报告
英文版母语化检查（2026-07 硬要求）：抽读英文版 3 段,无中文直译痕迹（镜像语序/硬译习语/中式定语堆叠）,符合美式技术博客语感;不过就整段重写,不许只做词面替换
中文版对齐+本土化检查（2026-07 硬要求）：与英文版逐节核对,事实/数字/案例/内外链无缺失;同时抽读 3 段无翻译腔,用词节奏像本土中文博主——中文版是英文版的本土化改写,不是机械翻译,也不是另写一篇
模板痕迹检查：和本站最近 5 篇对比——开头句式、H2 节奏、图表套路(决策树/速查表)撞车 ≥2 项就改;形态(4.0)选对了吗

格式和图片检查

标题 ≤ 60 字符，关键词前置
Description 120-160 字符
TOML Front Matter（+++）
封面图 cover.webp（正文第一行引用）
内容配图 ≥ 2 张（架构图、对比图、流程图等）
FAQ ≥ 3 个
内链 ≥ 4 个（自然嵌入正文，不是堆在文末）
外链 ≥ 3 个（链接一手来源）
中英文版都已创建

SEO 检查

关键词密度：核心关键词在正文自然出现 3-5 次
第一段含关键词：开头 150 字内包含核心关键词
H2 含关键词：至少 2 个 H2 标题包含核心关键词或近义词
title 关键词前置：核心关键词在标题前 30 字符内
description 回答问题：不是概述文章，是直接回答搜索问题
keywords 含长尾词：5-8 个，包含用户真实搜索句式
无超长无标题段落：不存在超过 1500 字无 H2/H3 的长段
中英文版都插入了配图引用

画图渲染验证（2026-04 起必查）

Markdown 加粗渲染正常：跑 python3 scripts/check-markdown.py（HTML 级扫描字面 ）——CJK 标点紧贴 会解析断裂,句号引号要放加粗外面,顽固病灶用 <strong>
mermaid 代码块语法正确：跑 node scripts/check-mermaid.mjs（用站点同款 mermaid 引擎离线校验全站所有块，5 秒出结果）——2026-07 实锤教训：agent 写的 sequenceDiagram 参与者起名 Loop 撞保留字、quadrantChart 中文标签没加引号，上线才被读者发现。此脚本必须在每次发布前跑，不能靠肉眼
architecture HTML 无错位：浏览器打开看分层色块对齐、响应式在移动宽度不断裂
WebP 图片路径正确：![](diagram-xxx.webp) 引用的文件确实存在于文章目录
中英文配图一致：两版引用相同的 .webp；mermaid/architecture 代码块可以各写一份但信息量要对等
优先顺序检查：能用 mermaid/architecture 的流程图 / 分层架构没用 AI 生图（结构化内容必须文本可编辑）

Hugo 构建

hugo --minify

步骤 7：发布 + 分发

7.1 发布前核对

文章目录命名：content/posts/<category>/<YYYY-MM-DD>-<english-slug>/

- 示例：content/posts/ai/2026-04-14-claude-skills-guide/ - ⛔ slug 一旦发布就不得更改（URL 稳定性是 SEO 硬规则）

中英文两个文件都存在：index.md + index.zh.md
封面图 cover.webp 和内容配图 ≥ 2 张已就位
默认不添加 categories（违反 URL 规则会影响已索引页面）

7.2 本地构建验证

hugo --minify                        # 生产构建，检查报错
hugo server -D                       # 本地预览，确认渲染正常（含封面图/配图/FAQ）

构建失败的常见原因和 fallback：

TOML 语法错误 → 检查 front matter 引号和数组格式
图片引用失效 → 确认文件名大小写和 .webp 扩展名
链接 404 → 内链路径以 /posts/ 开头（不带 content/）

7.3 提交 + 触发部署

git add content/posts/<category>/<article-dir>/
git commit -m "post: <中文标题或主题>"
git push origin code                 # 推送到 code 分支自动触发 GitHub Actions 部署

等待 2-5 分钟后访问线上 URL 验证：

https://www.heyuan110.com/posts/<category>/<slug>/（英文）
https://www.heyuan110.com/zh/posts/<category>/<slug>/（中文）

7.4 分发到外部平台

调用 blog-distributor skill 同步到 dev.to / 掘金 / V2EX / HN：

/blog-distributor <文章目录>

⚠️ 只分发已经线上可访问的文章（dev.to 需要 canonical URL 反向引用本站）。

参考文件

[references/frontmatter-template.md](references/frontmatter-template.md) — Front Matter 模板
[references/thinking-framework.md](references/thinking-framework.md) — 判断框架详细示例

与其他 skill 的关系

blog-growth → 选题 → blog-writer（本 skill）
                        │
                        ├── 封面图
                        │   └── blog-cover-image（AI 生成 cover.webp）
                        │
                        ├── 文本结构化图（首选，可编辑 / 响应式 / 双语独立）
                        │   ├── mermaid（流程图 / 决策树 / 时序图 / 状态机 / ER / 甘特 / 类图 / 思维导图）
                        │   └── architecture（分层系统架构 HTML）
                        │
                        ├── AI 位图（富视觉场景）
                        │   ├── blog-diagram（信息卡 / Bento / 对比矩阵）
                        │   └── blog-illustrator（概念插图 / 场景插画）
                        │
                        └── 专业图表（按需）
                            ├── graphviz / uml / network / bpmn / archimate
                            └── cloud / infographic / infocard / canvas / vega
                     →  blog-distributor（分发）

决策口诀：能 mermaid 不 architecture，能 architecture 不 AI 生图；一定要 AI 生图时，信息卡走 blog-diagram，插画走 blog-illustrator。

mermaid 画丑了怎么办：用户反馈"图丑 / 看不清 / 布局乱"时，先优化原图不要换技术栈——查 .claude/skills/mermaid/references/aesthetics.md，按顺序检查：① 节点密度（mindmap ≤ 25、subgraph ≤ 5）→ ② 方向 LR/TB（4+ subgraph 必须 TB）→ ③ 主题变量（fontSize/lineColor/theme）→ ④ classDef 三件套（fill+stroke+color）→ ⑤ subgraph 节点数平衡。把原图美化到位远比换成 HTML grid 好——换技术栈 = 推翻重建 = 没听懂"美化"需求。