Blog Writer

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。产品介绍或可脱离站点单独分发的专题稿若确实需要项目身份说明，只在开头语境中自然交代一次，不使用全站统一宣传模板。

开头

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

开头不超过 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 符号定位被排除：多步串行增加错误点」——直接给出结论，不用提问引出。

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

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

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

技术细节的写法

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

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

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

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

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

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

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

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

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

实现术语的通俗化

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

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

代码块也要通俗化

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

叙述中的术语替换

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