技术博客深度写作
核心理念
这不是一个内容生成工具，而是一个观点表达工具。
每篇文章必须能回答：我到底推荐什么？反对什么？读者看完能带走什么判断？
如果写完一篇文章，删掉所有观点句子后文章还能成立——说明这篇文章没有观点，是废品。
博客信息
- 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.claude/skills/youtube-fetch/fetch.sh <url> # 等几分钟（无字幕视频会自动 whisper 转写） # 然后 Read cache/youtube/<videoId>/transcript.txt 拿全文 # Read cache/youtube/<videoId>/metadata.json 拿元数据 - PDF / 文档：直接用 Read 工具
- GitHub 仓库：用
ghCLI 或 WebFetch GitHub URL
2.2 ⚠️ "参考文章写深度文"特殊模式
这是最常见也是最容易写废的场景。当用户说「参考这个链接/文章，写一篇 X 相关的文章」：
⛔ 绝对禁止：
- 把参考文章翻译/改写/总结当成自己的文章
- 沿用参考文章的章节结构和论证路径
- 只引用参考文章一个来源，没有外部交叉验证
- 用"原文提到"、"作者认为"这种转述为主的写法
✅ 必须做：
- 把参考文章当成"起点"而非"答案"：读完后，问自己——原作者有没有说错？漏掉了什么？哪些判断我不同意？
- 至少 3 个额外信息源：官方文档、GitHub issues、社区讨论、benchmark、对比项目——交叉验证
- 差异化定位：想清楚"我的文章 vs 参考文章"的不同——是更深（补充技术原理）、更实（增加实操经验）、更新（加入最新进展）、还是更批判（指出原文忽略的局限）？写在 steps 3 的核心立场里
- 原创占比 ≥ 70%：参考文章的信息只能作为起点或引用，不能构成文章主体
- 明确引用标注：引用原文观点时用"Hermes 官网文档指出..."或"根据 原文"，清楚区分一手来源 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.1 Front Matter
完整模板详见 references/frontmatter-template.md。
关键规则：
- 中英文版默认都创建
- 每篇 3-5 个 FAQ（
[[params.faqItems]]） - 封面图正文第一行引用
- 中英文 keywords 独立
4.2 写作原则（优先级从高到低）
第一优先：观点驱动
- 每个章节必须服务于步骤 3 确定的核心立场
- 如果一个段落不支持也不反驳核心论点，删掉它
第二优先：证据支撑
- 每个判断必须有数据、案例或代码示例
- 没有证据的观点不如不写
第三优先：反常识价值
- 步骤 3 识别的误区必须在文章中明确拆解
- 拆解方式：先说常见理解 → 再说为什么错 → 再给正确理解
第四优先：可带走价值
- 每篇文章必须包含至少一个读者今天就能用的具体产物
- 决策框架、速查表、配置模板、命令片段——读者截图保存的那种东西
- 如果全文删掉只留这一个产物，读者仍然觉得"没白来"
第五优先：边界诚实
- 步骤 3 的 trade-off 必须在文章中体现
- "什么时候不该用"比"什么时候该用"更有价值
4.3 逐段打磨机制（自我迭代）
不要一次性生成全文。按章节写，每写完一个章节立即自检并打磨。
写作节奏：
- 写一个章节（300-800 字）
- 立即自检，用以下 5 个问题审视刚写的内容：
- 有没有"一句话观点"？→ 必须展开成完整论证（现象 → 原因 → 证据 → 结论） - 有没有空洞的判断？→ 必须补数据或案例（"效果很好" → "CTR 从 0.33% 升到 1.5%"） - 有没有只陈述不分析？→ 必须加"为什么"和"意味着什么" - 段落是否太短（< 3 句）？→ 短段落通常意味着论证不充分，展开它 - 删掉这段后文章是否仍然成立？→ 如果成立，这段没有存在价值
- 打磨不合格的段落，直到通过自检
- 进入下一章节，重复 1-3
禁止模式：
- ❌ 一句话就是一个观点（"Cursor 速度最快。"）→ 必须展开为什么快、快多少、什么场景下快
- ❌ 结论先行不给推导（"我推荐 X。"）→ 必须先铺垫问题、分析选项、再给结论
- ❌ 列表代替论述（连续 5 个 bullet point）→ 关键观点必须用段落展开，列表只用于速查/总结
合格的段落长度：
- 核心论证段落：5-10 句，包含论点 + 证据 + 分析 + 边界条件
- 过渡段落：2-3 句，可以短
- 案例段落：完整讲述一个故事（背景 → 做法 → 结果 → 启示）
4.4 写作风格
必须做：
- 用第一人称分享经验（"我实际使用下来发现..."）
- 给出明确推荐（"如果你 X，我建议 Y"）
- 用具体数字说话（"CTR 从 0.33% 提升到 1.5%"，不是"显著提升"）
- 开头用反常识或冲突感吸引注意力
禁止做：
- 中性总结（"总的来说，X 有优点也有缺点"）
- 空话（"随着 AI 的发展..."、"未来可期"）
- 功能罗列不做判断
- 结构太对称整齐（每个工具都说 3 个优点 3 个缺点 — AI 味太重）
4.5 中英文差异化
- 中文版偏实操、国内生态、接地气
- 英文版偏原理、国际视角、数据驱动
- 两版 keywords 完全独立
- 中文不是英文的翻译，是同一个判断的不同表达
4.6 链接策略
- 内链 4-6 个（必须含 Related Reading）
- 外链 3-5 个（官方文档、GitHub、权威来源）
- 内链要自然嵌入正文（"我在之前的文章中提到过..."），不要集中堆在文末
- 外链优先链接到一手来源（官方文档、论文、GitHub），不链二手转载
4.7 SEO 优化
关键词密度：
- 核心关键词在正文中自然出现 3-5 次（不要刻意堆砌）
- 第一段必须包含核心关键词
- 至少 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 ⛔
默认工作流：先写英文版完整草稿 → 暂停向用户汇报 → 确认后再写中文版。
为什么不能一次两版全写完：
- 中英文角度默认独立（核心立场一致，但论证路径/案例/风格可以不同）
- 一次写完两版，如果英文版观点/结构需调整，中文版也要重写，浪费一倍工作量
- 用户对英文版的反馈往往会改变中文版的切入角度
汇报模板（写完英文版后）：
英文版草稿完成：<文章目录>/index.md
- 字数：约 N 字
- 核心立场：<一句话总结文章观点>
- 章节结构：<H2 列表>
- 主要案例/数据：<3 条>
- 预计配图：<mermaid X 个 / architecture Y 个 / AI 生图 Z 张>
是否按此方向写中文版？有什么要调整的？用户可能反馈：
- 立场不够鲜明 → 回步骤 3 重新做判断框架
- 案例不够硬 → 回步骤 2 补充研究
- 结构OK但某章要改 → 局部改英文版后再写中文
- 直接通过 → 写中文版（中文不是翻译，是同一判断用中文读者更熟悉的语境重新表达）
例外：用户明确说"一次写完两版"或"只写中文"时跳过这个 checkpoint。
步骤 5：封面图 + 内容配图
文章写完后，根据内容生成图片。
5.1 封面图（必须）
调用 blog-cover-image skill：
/blog-cover-image <文章目录> --quick- 文件名：
cover.webp，1200×630px，WebP 质量 85 - 统一英文生成，中英文共用
- 封面图在正文第一行引用：
5.2 内容配图（必须，至少 2 张）
第一步：按图表类型选对应的 skill
| 图表类型 | 首选 skill | 输出形式 | 渲染方式 |
|---|---|---|---|
| 流程图 / 决策树 / 时序图 / 状态机 / 思维导图 / ER 图 / 甘特图 / 类图 | mermaid | ``` `mermaid ``` 代码块 | Hugo 主题原生渲染（本地 JS） |
| 分层系统架构（User→App→Data→Infra） | architecture | 内嵌 HTML + CSS | Hugo unsafe=true 直接渲染 |
| 富视觉信息卡 / Bento 概览 / 数据看板 / 对比矩阵 | blog-diagram | AI 生成 WebP |  |
| 概念插图 / 场景化插画 | blog-illustrator | AI 生成 WebP |  |
| 封面图 | blog-cover-image | AI 生成 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业务流程 / 集成模式cloudAWS / Azure / GCP / 阿里云架构图（官方图标）archimate企业架构（TOGAF）infographicKPI 卡片 / 时间线 / SWOTinfocard编辑风格信息卡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：质量门禁 ⛔
以下检查项必须全部通过，任何一项不通过必须回去修改。
深度检查（最重要）
- 核心立场清晰：能用一句话概括文章的判断
- 至少 2 个误区拆解：指出了行业常见但错误的理解
- 至少 3 个真实案例/数据：不是引用官方宣传
- 明确的 trade-off：说了什么时候不该用
- 有行动建议：读者看完知道下一步做什么
- 没有空话：搜索全文，不存在"未来可期"、"值得关注"等废话
- 有第一人称经验：至少出现 3 次"我认为"/"实际使用中"/"我的建议"
- 无单句观点：搜索全文，核心论证段落不存在"一句话就是一个观点"的情况
- 段落充分展开：核心章节的段落至少 5 句，包含论点+证据+分析
格式和图片检查
- 标题 ≤ 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 起必查）
- mermaid 代码块语法正确：本地
hugo server打开文章，所有 mermaid 图表正常渲染（不是代码块原文） - architecture HTML 无错位：浏览器打开看分层色块对齐、响应式在移动宽度不断裂
- 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 — Front Matter 模板
- 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 好——换技术栈 = 推翻重建 = 没听懂"美化"需求。