---
name: blog-writer
description: >
  Peri 项目博客写作风格指南。当用户说"写博客"、"写文章"、"出稿"、
  "按风格写"、"博客"时触发。也适用于用户丢过来素材说"帮我写篇博客"的场景。
  覆盖项目介绍、技术复盘、架构讨论、性能优化、架构设计等类型。
---

# Peri 博客写作风格指南

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

---

## 核心原则

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

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

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

---

## 写作流程

按以下六步推进，前五步每步获得用户确认后再进入下一步，第 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 写出全文。** 严格按确认的大纲写。写完后不直接交付用户，进入第 6 步。

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

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

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

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

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

---

## 标题

**必须包含 Peri**，且要说清楚核心价值或反直觉点。

好的标题模式：

- `Peri Agent 如何让长任务跑几个小时不中断——自动上下文压缩机制`
- `Peri Code 的 99%，是国产模型写的`
- `Peri Agent 编辑工具设计复盘：行号和 Diff 为什么不如字符串替换`

差的标题模式：

- 没有 Peri：`Edit 工具才是正确答案`（读者不知道在说谁）
- 太口语：`Peri Agent 的文件编辑工具：造了三个版本，最后一版全删了`（信息量低）
- 太宽泛：`关于上下文压缩的一些思考`

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

**标题格式**：`Peri Code: [功能名/概念] 如何设计[能力名]` 或 `Peri Code 的 [反直觉发现]`。

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

---

## 文章头部

标题下方紧跟一行项目宣传 blockquote，格式固定：

```
> **[Peri Code](https://github.com/konghayao/peri)** — 用 Rust 写的开源 Coding Agent，兼容 Claude Code 生态。<https://github.com/KonghaYao/peri>
```

不加 install 命令，只留项目链接。所有文章统一用此格式，不因文章类型调整。

---

## 开头

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

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

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

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

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

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

---

## 结构模式

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

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

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

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

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

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

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

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

---

## 小标题

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

好的小标题：

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

差的小标题：

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

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

**描述行为，不写态度。** 每个小标题回答「这一节讲什么事」，而不是「作者觉得这件事怎么样」。

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

**禁止在小标题中写代码。** 不出现函数调用（`textarea.insert_str()`）、十六进制（`0x1B`）、数组切片（`history[..target_idx]`）、字面量值（`false`、`null`、`is_error`）等代码语法和值。小标题是给人扫读的，不是给编译器看的。

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

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

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

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

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

**禁止在小标题中用设问句式。** `trace 数据怎么变成错误清单` 是假装提问。小标题直接陈述机制即可，不用「怎么」「如何」开头。

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

| 差（故事性/悬念） | 好（机制描述） | 问题 |
|----|-----|------|
| `三个 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 个。** 优先用白话把「做了什么」「为什么」讲清楚，读者不需要看实现代码。只有这两种代码块值得放，且都必须是读者一眼能看懂的直观形式：

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

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

---

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

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

| 抽象描述（差） | 具体场景（好） |
|--------------|--------------|
| 「行号定位不稳定」 | 「模型要改 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 工作在有效注意力区间里——塞得下只是副产品」
- 转折：「任务完成了——但你不知道它跑对了没有」

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

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

**零容忍：一句话前后都是空行，就是 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」等三连同构句式，以及段尾对仗式概括（「前者改一行，后者改一条链」）→ 前文已经说清楚的事不要用对称句式复述。列举用顿号串联，不用排比铺陈
- **哲学总结段**：文章末尾用「两个原则」「三个核心」等数字归纳已说过的内容 → 删除。正文已经把事说清楚了，不需要用编号再提炼一遍
- **诗化收尾**：「十字路口」「枝杈」「重新长」等→ 技术文章不需要意象，用具体行为收束
- **偏离论点的独立章节**：某个端到端实现故事（如 ESC 双击 bug 调试、输入框回填的异步细节）不服务于核心论点 → 砍掉。好故事≠好论据，必须为论点服务

---

## 特性列表格式

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

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

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

---

## 结尾

干脆收束，附项目链接。**结尾必须回应开头**——开头抛出的场景、问题或判断，结尾要完成闭环。如果开头讲了 bug 故事，结尾要回扣「回头看这个 bug，教训是什么」。没有呼应的结尾像没收完的尾音。

```
项目地址：[github.com/konghayao/peri](https://github.com/konghayao/peri)
```

不用「总结」「结语」这类字眼。

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

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

---

## 事实核查

写完之前检查：

- 工具名、函数名、文件路径是否和代码库一致（如白名单里是 `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`

---

## 结构自检

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

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

---

## 参考文章

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

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`，每条可勾选标记。
