博客文章写作指南

📋 标准模板位置

_templates/article-template.md —— 新式模板（2026-05+ 推荐使用，无目录、叙事驱动）

_templates/post-template.md —— 旧式模板（含 本文结构 TOC、编号章节）

🎯 参考风格

参考 HTML Effectiveness 的设计风格：

🎨 视觉风格

色彩系统

字体

间距

📝 模板结构（推荐新式）

1. Frontmatter

新式（2026-05+ 推荐）：

---
layout: post
title: "文章标题"
date: 2026-06-27T10:00:00+08:00
tags: [AI-Native软件工程, 标签2, 标签3]
author: "@postcodeeng"
series: AI-Native Engineering
---

旧式（带系列编号、redirect_from）：

---
layout: post
title: "文章标题"
date: 2026-05-26T14:00:00+08:00
tags: [AI-Native软件工程, Prompt工程, 组织能力]
author: "@postcodeeng"
series: AI-Native软件工程系列 #43

redirect_from:
  - /post-slug.html
---

2. TL;DR（第一块引用）

> **TL;DR**
>
> 本文核心观点：
> 1. **核心概念** — 简短描述
> 2. **关键机制** — 简短描述
> 3. **实际效果** — 简短描述
> 4. **延伸洞察** — 简短描述

3. Hero 图（可选但推荐）

如果文章围绕一个核心模型/框架展开，TL;DR 之后立即插入一张总览 SVG。这是新式文章的主流模式（见 Goodhart、Anthropic Containment、VibeSec 等）。

4. 正文组织（新式：叙事驱动；旧式：编号章节）

新式（2026-05+ 推荐，无目录）：

旧式（带目录和编号）：

## 📋 本文结构

1. [第一章标题](#第一章标题)
2. [第二章标题](#第二章标题)

## 一、第一章标题
## 二、第二章标题

5. Key Insight 标注

段落之间插入，强化核心观点：

> 💡 **Key Insight**
>
> 一句话总结本章核心观点（不要超过两行）

6. 段落格式

🎨 SVG 嵌入规范（重要）

嵌入方式（强制模板）

SVG 必须用 <object> 标签，不能用 ![](path) 或 <img>（失去响应式 + a11y）。

<object data="/assets/images/2026-06-27-loop-engineering-02-flow.svg"
        type="image/svg+xml"
        width="100%"></object>

不要在 <object type="image/svg+xml"> 上加 aria-label —— html-validate 的 aria-label-misuse 规则会阻断（SVG 内部 <title>/<desc> 已提供 a11y）。

非 SVG 图片（jpg/png）才需要 aria-label：

<object data="/assets/images/example.jpg"
        type="image/jpeg"
        width="100%"
        aria-label="图片描述"
        role="img"></object>

理由：

复制模板（推荐）

不要从空白写 SVG。从预优化模板复制：

cp _templates/svg-hero-template.svg \
   assets/images/YYYY-MM-DD-post-slug-NN-desc.svg

模板已 svgo-clean（check-svgo 通过），编辑后通常不需要再 optimize。详见 _templates/svg-hero-template.README.md。

SVG 文件命名规范

YYYY-MM-DD-post-slug-NN-description.svg

示例：

2026-06-27-loop-engineering-01-stack.svg
2026-06-27-loop-engineering-02-flow.svg
2026-06-27-loop-engineering-03-react.svg
2026-06-27-loop-engineering-04-components.svg
2026-06-27-agent-skills-01-disclosure.svg
2026-06-27-agent-skills-02-patterns.svg

SVG 编号策略

按叙事流编号（最常见）：01-overview.svg、02-detail-a.svg、03-detail-b.svg

按概念编号：每个 SVG 表达独立概念时，按出现顺序编号即可

SVG 放置策略

位置 适用场景 示例
TL;DR 之后（Hero 图） 文章围绕一个核心模型/框架展开 Goodhart、Anthropic Containment、VibeSec
引入概念的小节内 概念解释后立即配图，强化理解 Loop Engineering 五阶段、ReAct 循环
章节之间 作为章节分隔的视觉锚点 DORA 对比图、四层权力结构

重要：SVG 引用按文章实际引用的顺序编号。img2-batch 系列 commit 的批改证明：经常存在”补图”操作，需要重命名以匹配叙事顺序。

SVG 视觉系统（保持与博客一致）

<svg viewBox="0 0 680 360" xmlns="http://www.w3.org/2000/svg"
     font-family="ui-serif, Georgia, serif">
  <!-- 颜色系统 -->
  <!-- #FAF9F5 (背景) | #FFFFFF (卡片) -->
  <!-- #141413 (主文字) | #87867F (次文字) -->
  <!-- #D97757 (强调/clay) | #788C5D (olive) -->
  <!-- #D1CFC5 (边框) -->

  <rect width="680" height="360" fill="#FAF9F5"/>

  <!-- 标题 -->
  <text x="340" y="26" text-anchor="middle" font-size="14"
        font-weight="500" fill="#141413">标题文本</text>

  <!-- 副标题/数据来源 -->
  <text x="340" y="42" text-anchor="middle" font-size="10"
        fill="#87867F" font-family="ui-monospace, monospace">
    来源 · 日期
  </text>

  <!-- 卡片 -->
  <rect x="40" y="68" width="130" height="88" rx="8"
        fill="#FFFFFF" stroke="#D97757" stroke-width="1.8"/>
</svg>

关键约束：

SVG 更新原则

推荐阅读顺序

创建文章配图时：

  1. 先写正文 — 确定核心概念和叙事顺序
  2. 画 01 主图 — 通常是 Hero/总览图，放 TL;DR 后
  3. 画 02+ 概念图 — 每章一图，配合 Key Insight 使用
  4. 同步编号 — 按文章实际引用顺序编号（避免 02 在前 03 在后的情况）

✅ 写作检查清单

发布前检查：

内容

SVG 配图

元信息

📌 写作风格对比

新式（2026-05+ 推荐，叙事驱动）

适用：技术深度文、行业分析、热点解读

特点：

旧式（2025 标准模板）

适用：教程、体系化课程、系列文章

特点：

📌 示例文章

新式参考：

旧式参考：

🔗 相关资源

🚨 强制规则（发布前必查）

1. 引用可信度

禁止以下写作模式：

允许的替代措辞：

每个 post 的 footer（如果有）应满足：

工具（已落仓）：

所有脚本支持 --dry-run，可先看 diff 再应用。

3. 标准结尾（必须）

每篇文章必须有 ## 结尾、## 写在最后、## 结论、## 结语、## 总结 其中之一。 如果不写，技术读者会感觉文章缺收束；RSS 订阅体验也会断裂。

写作时使用 ## 结尾（最常用），写作风格：

4. 链接完整性

⚙️ 发布前清单（升级版）

发布前除了内容/SVG/元信息三项外，增加引用 + footer 维度：

内容

引用（新增）

Footer & 元信息（新增）