---
name: Blog Writer
slug: blog-writer
category: Writing
description: Blog Writer provides a style guide for writing Peri project blog posts. Use it when drafting project intros, technical retrospectives, architecture discussions, or performance writeups in the Peri voice.
github: "https://github.com/KonghaYao/peri/tree/main/.claude/skills/blog-writer"
language: Rust
stars: 163
forks: 30
install: "npx degit https://github.com/KonghaYao/peri/tree/main/.claude/skills/blog-writer ~/.claude/skills/blog-writer"
installs_to: ~/.claude/skills/blog-writer
source_path: .claude/skills/blog-writer/SKILL.md
collection_size: 20
category_size: 1361
collection_url: "https://dirskills.com/collections/KonghaYao/peri"
added: 2026-09-08T05:35:42.780Z
last_synced: 2026-09-08T05:35:42.780Z
canonical_url: "https://dirskills.com/skills/blog-writer"
---

# Blog Writer

Blog Writer provides a style guide for writing Peri project blog posts. Use it when drafting project intros, technical retrospectives, architecture discussions, or performance writeups in the Peri voice.

**Install:**

```bash
npx degit https://github.com/KonghaYao/peri/tree/main/.claude/skills/blog-writer ~/.claude/skills/blog-writer
```

## README

# Peri 博客写作风格指南

基于 `docs/blogs/` 下已有文章提炼，覆盖项目介绍、技术复盘、架构讨论、性能优化、架构设计等类型。

---

## 核心原则

**用工程师的精确度写，直接说事，不绕弯子，但要让没接触过这个领域的读者也能读下去。**

每篇文章都要有一个可以一句话说清的核心论点。写之前先问自己——这篇文章想让读者记住什么？如果说不清楚，先别动笔。

工程准确和通俗易懂不矛盾。准确指的是机制不能写错、判断要有依据，不是把术语和代码堆满。读者的下限按「听过这个方向、但没碰过具体实现」来设定——术语第一次出现要带一句白话讲明白是什么，代码块能少则少。宁可多用一句白话解释，也不要让读者卡在某个词上往回翻。

**与 Anthropic/Codex 博客的关系：** Peri 博客借鉴了 Codex 官方博客的教学式渐进结构（先讲概念定义，再讲为什么重要，最后讲怎么做）、关键术语 **bold** 强调、以及丰富的交叉引用习惯。但有三个刻意的差异——(1) Peri 的段落更短（2-4 句 vs 3-5 句），保持工程师的切分感；(2) Peri 的语气更直接，可以下判断、可以表现偏好，不完全追求 Codex 的临床式冷静距离感；(3) Peri 不回避第一人称（我们、我），用个人经历和具体场景驱动叙述。

---

## 写作流程

按以下六步推进，前五步每步获得用户确认后再进入下一步，第 5 步写完后接第 6 步独立审查。

**第 1 步：用户提出方向，AI 用 grill 质询对齐核心命题。** 用户描述想写什么——一个功能的设计理念、一个踩坑复盘、一次性能调优经历。AI 在这个阶段只问澄清性问题，不提方案。

grill 必须显式覆盖「重心维度」。同一题材往往有多个可行的重心，比如讲工具设计可以从「工具机制」切入，可以从「能力关系」切入，可以从「用户姿势」切入。让用户在 grill 阶段选重心方向，比让重心被默认成某一个、用户在初稿里发现偏移要省事得多。

grill 结束的标志是用户确认了「核心命题一句话」——这篇文章想让读者记住的那一句话。这一句话确认后再进入第 2 步出标题。标题是包装，命题是内容，确认包装之前先确认内容。

**第 2 步：AI 出 N 个大标题。** AI 根据方向提 5 个大标题供选择。大标题说清楚文章对象和核心价值，不写驳论句式（「不是 X，是 Y」），不漂移到其他功能。格式参照「大标题规则」。

**第 3 步：用户选大标题。** 用户从 5 个中选一个，或者提出修改方向让 AI 再出 5 个。可以反复直到满意。

**第 4 步：AI 出大纲，用户审阅。** AI 给出章节标题列表（小标题），每个标题只说这节讲什么行为/机制。用户审核——砍掉偏离论点的章节、调整顺序、合并冗余。大纲确认后才进入写作。

**第 5 步：AI 写出全文。** 严格按确认的大纲写。

**动笔前必须先过写前 7 条红灯（30 秒自检，写完再查就晚了）：**

1. **中文冒号「：」**——这篇正文一句都不能有。项目地址行的冒号是唯一例外。
2. **任何引号（「」和 ""）**——一个都不能有。术语和观点不加引号直接写。
3. **每个 h2 的第一段**——必须至少两句话。一句话的段落立即跟下一段合并。
4. **每个小标题**——扫一遍有没有逗号串联两件事、有没有"适合/刚好/才是对的"等判词、有没有"怎么/如何/为什么"设问、有没有 CamelCase 代码标识符（SearchExtraTools→搜索工具、ToolResult→工具执行结果）。
5. **全文搜 `为什么` `怎么` `如何` `本文` `这篇文章`**——小标题里出现的一律改成陈述句，正文里「本文展开」「这篇文章记录」一律删除。
6. **结尾最后一段**——必须回应开头场景，禁止复读正文已讲过的机制结构。
7. **全文搜 `""`**——和「」一样禁止，一个不留。

这 7 条检查的是生成时最高频的机械性违规——标点习惯、段落结构、标题措辞和结尾套路——写完再让 subagent 抓出来修，不如写之前扫一眼直接避坑。

写完后不直接交付用户，进入第 6 步。

**第 6 步：subagent 文风审查（不可跳过）。** 写完全文后，派一个独立 subagent（`general-purpose`，全新上下文）做一轮文风审查。把本 skill 完整路径和文章路径交给 subagent，要求它按 skill 全文逐项核对，重点查这些高频违规项：

- 故事性叙事——拟人化模型行为（模型「撒谎」「老老实实」）、戏剧口语替代后果（「翻车」「废了」）、叙事过渡引子（「先说结论」「下面分别讲」「回头看」）
- 单句成段（一句话前后空行）
- 设问自答（「为什么不 X？因为 Y」）
- 代码块数量（整篇 1-2 个，只许报错信息和极简示意）
- 实现术语通俗化（内部函数名、类型标识符、框架 API 是否已替换为通用 CS 概念）
- 术语首次出现是否带白话解释
- 禁用词与禁用标点（中文冒号、双引号、「说白了」「本质上」等）
- 小标题是否机制描述、有无态度性措辞或破折号

subagent 输出逐条问题清单（位置 + 原文摘录 + 违反规则 + 修改建议）后，主 agent 据此修复全部违规，再交付用户。skill 的规则在生成时容易执行不到位，独立审查是补执行漏洞的硬关卡，一次都不要省。

**审查 subagent 必须持零容忍心态。** subagent 默认倾向于「合格」，需要显式指令纠正——prompt 中必须包含「宁可误判也不漏判，对违规持零容忍态度」的原则声明。高频违规项（故事性叙事、单句成段、设问自答）应从「注意」升级为「逐行扫描」，确保不被 subagent 的默认松弛心态漏掉。

subagent 审查的是 SKILL.md 的全部规则，不是字面硬规则。SKILL.md 包含许多例外条款，比如「规则类内容（项目链接、配置清单条目）不受单句成段禁令约束」、`项目地址：[github.com/konghayao/peri]` 作为固定结尾格式包含中文冒号、大标题允许用破折号副标题（小标题才禁）等。subagent 必须读到这些例外才不会误判。如果 subagent 环境不支持读本地文件，把 SKILL.md 全文嵌入 prompt 传递，不要只传硬规则摘要。

---

## 标题

标题优先说清文章对象和核心价值，不机械重复项目名。站点、栏目和正文语境已经明确文章属于 Peri 时，标题直接写具体命题；只有产品介绍、版本动态、跨项目比较或脱离站点传播时，为避免对象不明才加入 Peri。

好的标题模式：

- `长任务的自动上下文压缩机制`
- `工具交换的原子提交`
- `Peri v2 架构说明`（版本动态需要点明对象）

差的标题模式：

- 对象不明：`它的 99%，是国产模型写的`
- 太口语：`Peri Agent 的文件编辑工具：造了三个版本，最后一版全删了`（信息量低）
- 太宽泛：`关于上下文压缩的一些思考`

副标题（破折号后）用来补充核心机制或反转点，不是重复主标题。

**标题格式**：优先使用 `[功能或概念] 的 [机制或边界]`。需要点明项目时使用 `Peri [版本或产品主题]`，不使用 `Peri Code:` 作为统一前缀。

- 不出现「不是 X，是 Y」的驳论句式——标题不立靶子
- 不漂移到 Peri 其他功能——标题聚焦本文对象
- 不写纯态度标题（如「Peri 不需要 Undo」）——标题说能力，不说态度

---

## 文章头部

普通文章不添加项目宣传 blockquote。产品介绍或可脱离站点单独分发的专题稿若确实需要项目身份说明，只在开头语境中自然交代一次，不使用全站统一宣传模板。

---

## 开头

**永远从一个具体事实或场景切入，不宏大叙事。**

| 好的开头 | 差的开头 |
|---------|---------|
| 「我们有一次让 Peri 分析 300 条 trace 日志，跑了 40 分钟，到 80% 时 400 报错。」 | 「随着 AI 技术的发展，上下文管理变得越来越重要。」 |
| 「翻开 git 历史，满眼都是 deepseek-v4-pro 和 glm-5.1。」 | 「今天我们来聊聊国产模型。」 |
| 「Codex 在经历几十轮对话后内存会膨胀到 2GB，随后 OOM。」 | 「内存优化是一个复杂的话题。」 |

开头不超过 3 段。第一段锚定场景，第二段点出问题，第三段引出文章方向。

**首段禁止孤立单句。** 不要把开头第一句话单独拿出来、前后空行当 hook 段落（如开篇一句「issue 跟踪散成这样，已经成了负债。」然后空一行才开始正文）。开头的每一段都应是完整场景锚定——一句话悬空既不是场景也不是结论，读者不知道它跟上下文的关系。把这句话并入下一段或展开成完整段落。

**开头的数字必须和正文一致。** 不要为了吸睛编造一个漂亮数字。如果正文才有精确数据，开头用定性描述（如「几百行代码」），不要给出一个和正文矛盾的具体数字。

反例：开头写「12 行核心代码里完成所有设计」，正文写「总计不到 400 行」——自相矛盾。

---

## 结构模式

```
开头（具体场景/数据切入）
  ↓
核心结论先说（不要憋到最后）
  ↓
机制/过程展开（按读者最需要的顺序，不按时间顺序）
  ↓
关键细节（用代码块或具体例子支撑）
  ↓
结尾（一句话收束 + 项目链接）
```

**结论要放在前面**，不是结尾。读者想先知道「这东西能做什么」，再看「怎么做到的」。

反例：compact 文章最初把「让 Agent 跑几小时不中断」放在 Micro/Full compact 机制之后——改过来之后，读者先看到价值，再看机制，逻辑更顺。

**每个章节覆盖一个独立话题。** 如果连续两章描述同一件事（如「调研 → 为什么不行 → 所以用了 X」和「X 的具体细节」），应该合成一条线。写完后通读，如果连续两章出现了相同的术语解释，就该合并。

**场景驱动结构，不用分类驱动。** 不要按「三种模式 → 五个 agent → 继承规则」这种分类目录来组织文章，这是文档不是博客。按具体使用场景来组织——「场景 1 怎么协作、场景 2 怎么协作」，每个场景自然带出相关的模式和配置。分类信息（配置表、规则列表）放附录。

**每个章节必须服务于核心论点。** 写完后逐章检查：这段内容是在推进核心论点，还是在讲别的东西？如果删掉某个章节后核心论点的论证完全不受影响，这个章节就不该出现在正文。配置清单、参考手册类的内容跟核心论点无关，应该降级为附录或删除。

**方法论类文章的特有陷阱**（「我们是怎么用 X 做 Y 的」类型）：
- 小标题主语容易从系统偏移到「我们」——正文可以写「我们从最早的文件开始」，标题应写系统行为如「Agent 并行验证 issue 状态并批量更新」
- 结尾容易掉进数字归纳（「你只需要三个东西」「这套方法不绑特定工具，你只需要……」）——删掉，用具体行为收束
- 流程顺序容易退化为「第一步→第二步→第三步」流水账——按「每个步骤解决了什么问题」组织章节，而不是按「这个步骤做了什么」

**自检信号**：如果正文超过 30% 的篇幅不服务于核心论点，说明结构需要重排。

---

## 格式规范

**关键术语在正文首次出现时用 `**bold**` 强调。** 每个小节引入的核心概念——如 Micro-compact、ContextBudget、prompt cache——首次出现时加粗，方便读者扫读定位。同一个术语只在首次出现时加粗，后续不再重复加粗。

**交叉引用要主动、完整。** 每个引用的外部概念——其他博客文章、官方文档、源码文件——在首次提及时附上可访问的链接。内部引用（同一项目下的其他博客）用该文件的中文简称 + GitHub 链接，格式参见事实核查一节。外部引用（如 Anthropic prompt caching 文档）直接附 URL。能给的链接主动给，不要等读者追要。

---

## 小标题

直接描述这一节在说什么——机制、行为、结论，不用态度性表达。

好的小标题：

- `所有 ToolResult 收集完再统一写入`
- `连续失败 5 次，框架注入纠正消息`
- `多个 ToolResult 必须合并进同一条 user 消息`
- `三个版本，三次加码，每次都加错了地方`

差的小标题：

- `字符串匹配，反而是对的`（态度性，不够直接）
- `为 AI 设计工具，直觉是反的`（花哨，信息量低）
- `关于工具设计的思考`（空洞）
- `我们搞错了什么`（太口语，信息量低）

小标题说清楚这一节讲什么，读者扫标题就能知道文章结构，不需要进去读才明白。

**描述行为，不写态度。** 每个小标题回答「这一节讲什么事」，而不是「作者觉得这件事怎么样」。禁止在小标题中出现判断词——「适合」「刚好」「恰好」「才是对的」——这些词在评价而非描述。标题只需给出行为和结论，不写适用性判断。

| 差 | 好 | 问题 |
|----|-----|------|
| `回退的是一个子树，不是一条线` | `选中一条消息，之后全部截断` | 「不是一条线」是态度，「之后全部截断」是行为 |
| `文件恢复是尽力局，不是事务` | `文件恢复倒序执行，单条失败跳过` | 「不是事务」在反驳没人提的事，「倒序、跳过」是行为 |
| `工具配对验证是血的教训` | `截断后扫描未配对的工具调用和结果` | 「血的教训」是态度，「扫描配对」是机制 |
| `回退后自动回填，不是贴心的设计，是必须的闭环` | `回退完成后把被撤回的文本放回输入框` | 前半句在自我评价，后半句在说事 |

**禁止在小标题中写代码。** 不出现函数调用（`textarea.insert_str()`）、十六进制（`0x1B`）、数组切片（`history[..target_idx]`）、字面量值（`false`、`null`、`is_error`）等代码语法和值。也包括 CamelCase 类型标识符——`ToolResult`、`ToolCall`、`ContextBudget` 这类代码命名在小标题中读起来像标识符不像是概念，应替换为中文通用描述（「工具调用」「工具执行结果」「上下文预算管理器」）。小标题是给人扫读的，不是给编译器看的。

**禁止在小标题中使用项目内部标记符号。** `[TRAP]`、`[FIXED]`、`[P0]` 这类约定标签只应在正文解释，不应出现在标题中。标题给读者扫读，标记打断节奏且需要背景知识才能理解。

**禁止在小标题中用逗号串联多个信息点。** 每条标题聚焦单一行为或机制的表述。用逗号把两件事拼在一起（`Edit 工具 284 次失败，错误也用成功状态返回`、`错误改走失败返回，参数描述强调必填`），读者扫不出重点。要么拆成两节，要么用「和」连接成一句。

**禁止在小标题中打包多个行为（即使不用逗号）。** 多个动词堆叠在一个标题里（「判定、验证、删除、改状态」「提炼并写入」），读者扫不出核心动作。超过两个动词就该拆成多节，或选定一个主行为做标题、其余在正文交代。

**禁止在小标题中用 `——`。** 破折号用于正文句间停顿，标题直接接续。

**禁止在小标题中用模糊回指修辞。** `同样的返回方式`、`一致的错误处理` 这类回指前文的说法不说清具体是什么，读者扫标题不知道这节讲什么。标题要自包含，直接点明具体行为，不依赖读者读过上一条才懂。

**禁止在小标题中用设问句式。** `trace 数据怎么变成错误清单`、`为什么不用 LSP 辅助定位` 是假装提问。小标题直接陈述机制即可，不用「怎么」「如何」「为什么」开头。如果文章需要讨论一个被排除的方案，小标题写方案+被排除的原因——如「LSP 符号定位被排除：多步串行增加错误点」——直接给出结论，不用提问引出。

**用工程语言描述机制，不写悬疑故事。** 小标题是技术分析目录，不是章回体回目。把机制包装成悬念（「根因同源」「决定生死」「撒谎」「真相」「假象」）会降低专业感，读起来像在卖关子而不是在讲清楚。直接点明是哪个层面、什么失效、怎么判定。

| 差（故事性/悬念） | 好（机制描述） | 问题 |
|----|-----|------|
| `三个 bug，看似无关，根因同源` | `流式数据的三层完整性边界` | 「根因同源」是叙事结论，标题应直接给出分类 |
| `max_tokens 截断 JSON，字段顺序决定生死` | `max_tokens 截断破坏 JSON 字段完整性` | 「决定生死」戏剧化，「破坏完整性」是机制 |
| `stop_reason 撒谎，内容才是真相` | `stop_reason 与响应内容不一致的路由判定` | 「撒谎」「真相」拟人化，「不一致的路由判定」是工程判断 |

自检信号：如果一个小标题里出现「同源」「撒谎」「真相」「生死」「假象」「玄机」这类词，说明在讲故事而非分析——把它换成对机制或行为的直接描述。

**小标题描述系统行为，不描述作者动作。** 生成时容易把「描述机制」误解为「描述我在做什么」。小标题的主语是系统/规则/现象，不是「我们」。

| 差（作者动作） | 好（系统行为） | 问题 |
|----|-----|------|
| `靠三段话控制风格，第二篇就失灵` | `三段风格偏好描述在第二个题材失效` | 「靠……控制」是作者动作，「失效」是系统行为 |
| `扫出一篇文章里十几处孤立单句，把它写成禁令` | `孤立单句被扫出后按类型分类禁止` | 「扫出」「把它写成」是作者在干什么，「被扫出后分类禁止」是规则怎么生效 |
| `同一个模型检查自己的输出，漏掉一半违规` | `生成和审查用不同上下文后违例检出翻倍` | 「同一个模型检查……」描述了谁做了什么，「用不同上下文后检出翻倍」描述了机制的因果 |

---

## 技术细节的写法

**模式：具体数字 → 技术概念 → 业务含义**

```
每轮会产生 70 万次 malloc 调用，其中 97.3% 在 prompt 结束前就已释放。
严格意义上并不存在泄漏，问题出在别处。
```

- 先给数字锚定现实
- 技术术语第一次出现要带一句白话解释，不能默认读者都懂。比如「chunk（网络传输的一个数据块）」「max_tokens（模型一次最多能输出的字数上限）」。解释必须在首次出现时给出，禁止滞后到后文章节再补——术语首次出现时读者已经卡住，后文解释等于没解释。**注意：同一个术语可能在不同小节重复出现，解释只在全文第一次出现时给出，后续不再重复。如果写作中把某个小节的顺序提前了，要检查该小节中的术语是否是全文首次出现——是的话补解释，不是的话删掉已出现在前文的解释。** 自检：每个术语搜全文首次出现位置，解释必须在该句或紧邻下一句里
- 紧跟着说这个数据的实际意义

**技术细节必须挂在它所属的功能下面。** 描述 A 功能时，不要把 B 功能的实现细节混进来。如果两个功能的策略不同（如搜索截断 500 字符 vs 网页截断 2000 行），分别说，不要在同一段里交叉描述。

**只写代码库里真实存在的东西。** 如果提到一个计划中但未实现的设计，必须明确标注（如「正确的做法应该是」「我们计划加上」），不能用现在时写成既定事实。读者会把文章当成当前状态的说明，而不是路线图。

**博客聚焦设计决策和用户可感知的行为。** 内部类型定义、字段映射、协议细节只有在用来支撑一个关键论点时才提，不值得单独成章。如果删掉一段后读者对「为什么这样设计」的理解不受影响，那段就不该写。

**代码块能少则少，整篇控制在 1-2 个。** 优先用白话把「做了什么」「为什么」讲清楚，读者不需要看实现代码。只有这两种代码块值得放，且都必须是读者一眼能看懂的直观形式：

- 真实报错信息（让读者看到失败的确切样子）
- 极简的前后对比或数据示意

禁止放大段实现代码、函数定义、类型签名——那是文档不是博客。代码块要带注释说明场景，不要裸代码。一句话能说清的行为，绝不用代码块展示。

---

## 实现术语的通俗化

博客的目标读者是「听过这个方向、但没碰过具体实现」的工程师，不是项目贡献者。实现语言（Rust/Go/Python）的特有语法、内部函数名、类型标识符对读者来说是不必要的认知负担——读者只关心机制怎么运作，不关心代码里函数叫 `on_bg_complete` 还是 `handle_completion`。

**原则：所有解释性文本用通用 CS 概念代替实现层术语。**

### 代码块也要通俗化

代码块不是文档摘抄，是为读者展示逻辑流的示意图。用通用动词描述步骤，不用裸函数名：

| 原文（差） | 改为（好） |
|-----------|-----------|
| `on_bg_complete(&result) → router.route_bg_result(result) → inbox.push_defer(MessageSource::SubAgentComplete, msg)` | `完成回调被触发 → 路由到对应的结果处理器 → 将结果消息写入待处理队列` |
| `queue empty → idle_should_wait (active_count > 0) → await_wake → ???` | `消息队列为空 → 检查活跃任务计数（> 0） → 进入阻塞等待 → 永远等不到` |

### 叙述中的术语替换

下面是实际执行过的替换，作为参考基准：

| 类型 | 原文 | 改为 |
|------|------|------|
| 内部函数调用 | `push_defer → wake.notify_one()` | `写入队列 → 触发唤醒信号` |
| 内部枚举/类型 | `LoopResult::Completed` | `已完成状态` |
| 内部方法 | `idle_should_wait 返回 true` | `空闲等待判断为真` |
| 内部变量 | `cancel_fut` | `用户取消信号` |
| 内部 API | `WorkflowTaskRegistry::kill()` | `Workflow 任务管理器的终止方法` |
| 配置项 | `max_iterations(500)` | `最大 500 轮迭代限制` |
| 内部组件名 | `ReAct 循环 / MessageQueue / BackgroundTaskRegistry` | `推理-执行循环 / 消息队列 / 后台任务注册表` |
| 语言特有 API | `tokio::spawn` | `通过异步方式启动` |
| 语言特有概念 | `tokio task` | `异步任务` |
| 框架宏 | `tokio::select!` | `并发选择机制` |
| 框架 API | `tokio::time::timeout` | `异步超时机制` |
| 框架类型 | `JoinHandle` | `子进程任务句柄` |
| 框架原语 | `cancel token` | `取消标记` |
| 框架原语 | `watch channel` | `观察通道` |
| 类型标识符（CamelCase） | `ToolResult`、`ToolCall`、`ContextBudget`、`ActOutput` | `工具执行结果`、`工具调用`、`上下文预算管理器`、`执行输出` |

### 什么可以保留

以下类型不需要转换：

- **众所周知的协议/标准**：JSON-RPC、HTTP、WebSocket
- **通用 CS 概念**：wake、callback、loading spinner、session
- **UI 显示文本**（用户看到的就是这个）：`[后台任务 bg-xxx 已完成]`
- **API 参数名**（读者需要知道调什么）：`run_in_background: true`
- **真实报错信息**：原样展示
- **类型标识符首次出现时可以保留英文**（如 Micro-compact、prompt cache、old_string），但必须紧跟中文解释，且后续全部用中文。**自检方法**：搜英文标识符的全文出现次数——如果 >1 且不是首次出现的那句，说明没有替换干净。例如 `old_string` 首次出现后，后续全部改用「原始文本片段」

### 自检

写完初稿后，用以下方法逐段扫描：
1. 每个反引号包裹的术语——它是实现层标识符还是通用概念？实现层的就改
2. 每个代码块——它是在展示逻辑流还是在展示函数调用链？函数调用链就改
3. 每个箭头链路（`A → B → C`）——箭头两端是函数名还是行为描述？函数名就改

---

## 用具体场景代替抽象描述

每个论点都要有一个具体的支撑例子，而不是泛泛描述。

| 抽象描述（差） | 具体场景（好） |
|--------------|--------------|
| 「行号定位不稳定」 | 「模型要改 invoke.rs 第 58 行，实际代码在第 63 行，偏了 5 行，返回成功但什么都没改」 |
| 「general-purpose 占比过高效率低」 | 「回头看，那次任务里 general-purpose 占了 73%，专用 coder 只有 12%」 |
| 「compact 后 Agent 能继续跑」 | 「消息管线重构跑了 3 小时，触发了 2 次 Full compact、4 次 Micro-compact，任务完成，中间没中断」 |

**解释「为什么不用别的方案」比「我们用了什么方案」更有说服力。** 每个设计决策都要说明排除了哪些替代方案、为什么排除。比如介绍 Fork 模式时，要解释「为什么不用 Sync（重复传方案浪费 token）」和「为什么不用 Background（需要汇总结果）」。没有反面论证的文章读起来像产品说明书。

**决策树比散文描述更清晰。** 当文章需要解释「怎么选择 X/Y/Z」时，用一个两到三层的决策树图，而不是三段平行描述。读者扫一眼决策树就能理解选择逻辑，比读完三段文字再自己归纳高效得多。

---

## 句子结构

**短句为主，破折号制造停顿，允许逗号串联长句推进叙事。**

破折号（——）是核心标点，用于：

- 解释：「超长上下文下注意力机制有结构性限制——窗口再大，有效注意力是有上限的」
- 强调：「compact 让 Agent 工作在有效注意力区间里——塞得下只是副产品」
- 转折：「任务完成了——但你不知道它跑对了没有」

句子节奏：短-中-短。一句话一个判断，不在一句话里塞两个论点。

**正文段落不少于两句，规则类条目不受此限。** 禁止正文中单独一句话成段——一句话的观点融入前后段落，不要悬空。单句站立不住，读者扫过去不知道它跟上下文的关系。

**版本迭代类叙事的段落陷阱：** 「第一版……第二版……第三版……」的结构容易让每个版本的描述都变成独立短段落，甚至出现单句成段。处理方法——每个版本独占一节（h2），每节内部把「描述+问题+后果」合成一段，不拆成多段。**特别关注每节第一段**——如果该节第一段只有一句话（如介绍该版本的做法），它需要跟下一段（说明问题）合并；一句话做不了完整的论证单元。

**零容忍：一句话前后都是空行，就是 bug。** 写完通读时，把每个「前后空行夹着的单句」揪出来。这类句子通常是三种东西：预告句（「这篇文章记录……」）、过渡性总结（「同一个根因，两种失败模式」）、收束提炼（「一句话，每一层都用 X 覆盖 Y」）。处理方式按优先级：能删就删（多数是废话和预告），删了伤筋动骨就跟上文或下文合并成同一段落，绝对不要让它单独占一段。规则类内容（项目链接、配置清单条目）不受此限。

---

## 语气

- 第一人称为主（「我们」），偶尔用「我」
- **直接下判断不等于戏剧口语。** 可以说「这个方案不行」——这是判断。不能说「这个方案撑爆了」「输出质量断崖式下跌」——这是用剧情替代后果。情绪表达限于「踩够了」「炸了」这类主观感受，不能蔓延到对系统行为的描述——系统行为用中性动词（「失败」「中断」「下降」），不用戏剧化动词（「撑爆」「挣扎」「断崖」）
- 敢于下结论，不用「可能」「也许」「某种程度上」来逃避判断
- 允许推销，可以直接说「强烈推荐 DeepSeek 官方 API」「建议配合 Herdr 使用」

---

## 禁用词和模式

| 禁用 | 替换 |
|------|------|
| 「说白了」 | 「其实就是」「坦率说」 |
| 「本质上」 | 「说到底」「其实」 |
| 「换句话说」 | 直接说 |
| 「综上所述」 | 具体的回扣句 |
| 「值得注意的是」 | 直接说 |
| 「不难发现」 | 直接说 |
| 「让我们来看看」 | 直接开始 |

**禁用标点：**

- 中文冒号「：」→ 用逗号或破折号
- 双引号「""/""」和直角引号「」→ 不加引号。直接用文字本身表达即可，不需要用引号包裹术语和观点。注意：本 SKILL.md 自身用「」标记反例短语是技能文档的内部约定，博客正文不能沿用

**禁用模式：**

- 教科书开头：「在当今 AI 快速发展的时代……」
- 空泛工具名：「某个模型」「AI 工具」→ 说具体名字
- 流水账结构：「然后我们做了 X，然后做了 Y，然后做了 Z」→ 用论点驱动，不用时间顺序
- 无数据支撑的判断：「效果很好」「明显提升」→ 给数字
- 铺垫句：「我们先来想清楚为什么」「让我们看看具体实现」→ 直接讲，不需要预告
- 预告句：「这个约束是双向的」「具体来说」「主要包括以下几个方面」「本文展开」「这篇文章记录/复盘」→ 直接展开，读者自己能看出来。特别是结尾处的「本文……」类预告——它既是冗余过渡，又等于在跟读者说「我接下来要总结了」，消解结尾的力度
- 总结性填充：「回头看，这些代价是必要的」「综上所述」→ 用具体论据收束，不要用空话收束
- 孤立总结句：段落末尾单独一行提炼结论（如「没有中间状态，没有写了一半的窗口」）→ 结论融入段落里说，不要单独提出来当句号
- **单句独立成段**：一句话前后都是空行，单独占一段（如「这篇文章记录这三个坑，以及每层我们最后选择怎么兜底。」「同一个根因，两种失败模式，区别只在 X。」「一句话，每一层都用 X 覆盖 Y。」）→ 多数是预告、过渡总结或收束提炼，能删则删，删不掉就并进相邻段落。绝对禁止一句话悬空成段
- 反问句开头：「Agent 调工具出错了，谁来负责？」→ 直接给出判断，不用反问引出
- **设问自答**：「为什么不只信 stop_reason？因为……」「为什么不直接用 String？因为……」「那怎么办？用 X。」→ 设问是假装提问再自己接话，把结论裹了一层多余的壳。删掉「为什么不 X？」前半句，直接给判断和理由
- **故事性叙事替代工程描述**：把技术分析写成情节，三类都要改。一，拟人化模型行为（模型「老老实实写完」「没遵守 schema」「撒谎」）→ 用中性动词描述实际输出（「字段排在前面」「stop_reason 与内容不一致」），模型是程序的输出方不是角色。二，戏剧化口语替代具体后果（「翻车」「撑爆」「撑满」「断崖式下跌」「堵死」「能忍」「挣扎」）→ 写出实际影响（「中断长任务」「超出 token 上限」「消除该类错误」「质量急剧下降」）。三，叙事过渡引子（「先说结论」「这就是为什么 X」「修复的关键认识是」「下面按顺序讲」「回头看」「收拾完之后再看」）→ 删掉，直接进入机制。语气可以直、可以批判，但不把模型当角色演。四，拟人化系统设计——用人类认知动词描述 agent 系统的设计行为（agent「记住」「记忆」「学会」「忘记」），把系统架构比喻为人类认知。删掉比喻，直接描述机制。agent 没有「记忆」，有检索链和持久化查询。用功能名词替代认知动词
- 比喻：「就像一个团队」「好比一条流水线」→ 直接描述机制，比喻增加阅读负担不增加信息量
- **拖拉式论证**：「不是因为做不到——是因为……」「不是因为 X——恰恰相反，是因为 Y」→ 直接说结论，砍掉辩解性铺垫
- **排比重复**：「同一个 X，同一个 Y，同一个 Z」「没 X，没 Y，没 Z」「没有 X，没有 Y，没有 Z」等三连同构句式，以及段尾对仗式概括（「前者改一行，后者改一条链」）→ 前文已经说清楚的事不要用对称句式复述。列举用顿号串联，不用排比铺陈。**反面典型**：「没有行号、没有 diff 格式、没有中间状态」→ 改为「行号、diff 格式和中间状态全部消除」
- **哲学总结段**：文章末尾用「两个原则」「三个核心」等数字归纳已说过的内容 → 删除。正文已经把事说清楚了，不需要用编号再提炼一遍
- **诗化收尾**：「十字路口」「枝杈」「重新长」等→ 技术文章不需要意象，用具体行为收束
- **偏离论点的独立章节**：某个端到端实现故事（如 ESC 双击 bug 调试、输入框回填的异步细节）不服务于核心论点 → 砍掉。好故事≠好论据，必须为论点服务

---

## 特性列表格式

仅在介绍产品特性时使用，其他内容用散文。

```
* 🔤 **标题** — 描述，1-3 句话，结尾句号。
```

- 列表符号用 `*`，不用 `-`
- 每个特性一个 emoji，全文不重复
- 描述可以带推荐或使用建议
- 正文中不用 emoji

---

## 结尾

干脆收束。**结尾必须回应开头**——开头抛出的场景、问题或判断，结尾要完成闭环。如果开头讲了 bug 故事，结尾要回扣具体的工程判断。没有呼应的结尾像没收完的尾音。

普通文章不重复项目地址。只有产品介绍、对外发布稿或明确承担转化任务的页面，才在结尾保留一次项目链接。

不用「总结」「结语」「结尾」这类字眼做章节标题——最后一段直接接在正文末尾，前面加一个空行分隔即可。结尾内容应收束全文而非给一节的标题。

**结尾不要复读正文已详述的机制结构。** 正文已经逐节展开，结尾再列一遍架构层次是冗余复盘。保留一句闭环足够，不要做目录式重申。

**禁止开头和结尾重复同一句诗化断言。** 同一句话出现在开头和结尾，极大概率是诗化收束而非事实判断——两端都删，用具体行为替代。

---

## 事实核查

写完之前检查：

- 工具名、函数名、文件路径是否和代码库一致（如白名单里是 `Grep` 不是 `search`）
- 数字是否有来源（git 历史、代码注释、实测数据）
- 代码块里的内容是否符合实际格式
- 不编造场景——用真实经历，没有就说「我们还没测过」
- 只描述已实现的功能，未实现的必须标注为计划方向
- **引用项目内其他博客或文件时，用该文件的 h1 中文标题简称 + GitHub 链接，禁止用英文目录名。** 例如引用 `docs/blogs/streaming-protocol-traps/` 时写「[流式协议踩坑篇](https://github.com/konghayao/peri/blob/main/docs/blogs/streaming-protocol-traps/streaming-protocol-traps.md)」，不写 `streaming-protocol-traps`
- **引用外部项目（Codex、Aider 等）时，首次出现必须附 GitHub 或官网链接。** 例如「[Codex](https://github.com/anthropics/Codex) 和 [Aider](https://github.com/Aider-AI/aider) 的早期版本」

---

## 结构自检

写完第一稿后，逐项检查：

1. **论点覆盖率**——逐章标注「推进核心论点 / 偏离 / 无关」，偏离+无关超过 30% 就该重排。
2. **叙事张力曲线**——画出每章的阅读吸引力（1-10），如果中间出现连续两个低于 5 分的章节，说明该段是文档式内容，需要用场景重构或移到附录。
3. **前置依赖链**——每个新概念首次出现时，读者是否已经有足够的上下文理解它？如果读者到了某段需要往回翻，说明信息编排顺序有问题。
4. **结尾呼应**——结尾是否回应了开头抛出的场景或问题？如果没有，补上。
5. **反面论证**——每个设计决策是否解释了「为什么不用替代方案」？如果没有，读者会觉得是一面之词。反面论证缺失是生成时的最高频结构性问题之一——agent 写文章倾向于只描述「我们用了什么」，不主动想「为什么不用别的」。写完第一稿后逐决策补反面论证，不要等审查时才追补。
6. **空话扫描**——逐句检查：这句话删掉后，读者是否损失信息？如果不损失，删掉。常见空话类型见「禁用模式」。
7. **逻辑连贯性**——相邻段落之间是否有逻辑跳跃？如果一个段落突然引入前面没铺垫的新概念，或者结论和论据不匹配，需要加过渡句或调整顺序。
8. **外部资源链接**——所有引用的外部资源（其他博客文章、代码文件、skill 文件）是否在首次出现时附了可访问的 GitHub 链接？能给的链接主动给，不要等用户追要。
9. **中文标点清零**——全文搜索中文冒号「：」和直角引号「」，逐一替换。直角引号在任何情况下都不出现——要引用的短语直接说，不加任何引号。这是生成时最高频的机械性违规——写完第一稿后全局搜索这两个字符是性价比最高的自检。
10. **小标题判词扫描**——逐条小标题检查是否出现判断词（「适合」「刚好」「才是对的」「反而更好」）。判词是小标题从行为描述漂移到态度表达的第一个信号——删掉判词后如果标题信息量不变，说明判词是多余的。

---

## 参考文章

按质量排序，写作前可以读一遍找感觉。注意，部分参考文章写于风格调整之前，代码偏多，作为结构参考而非代码密度标杆：

1. `docs/blogs/multi-agent-patterns/` — 场景驱动结构和通俗表述的范本，四个使用场景带出三种模式，决策树清晰
2. `docs/blogs/streaming-protocol-traps/` — 通俗化机制类文章的范本，代码块克制，术语都带白话解释
3. `docs/blogs/web-search/` — 调研类文章模板，「为什么朴素方案不行 → 所以我们自研」的论证结构
4. `docs/blogs/compact-mechanism/` — 机制类文章的结构模板
5. `docs/blogs/perf-optimization/` — 数字密度高、论证有力，但代码块偏多，作为代码量的反面参考
6. `docs/blogs/introducing-peri/` — 产品介绍类的语气和特性列表参考
7. `docs/blogs/issue-archive/` — 方法论类文章的结构范本，三层检索结构每章回答一个问题而非描述一个步骤

---

## 写作素材库

见 `docs/WRITING_TOPICS.md`，每条可勾选标记。