/personal-chinese-writing-style

Chinese Article Structure Preferences

Core Principle

文章应该像自然对话一样流畅，而不是像教科书大纲那样机械。

Guidelines

1. 结构隐于文中

让内容本身传达层次，不要靠编号、标签、"总结"这类显式脚手架。读者应该感受到结构，而不是看到结构。

• frontmatter 已声明 title，正文不要再写 # H1 重复标题。 Markdown 渲染管线（Substack、知识星球、博客主题）大多会用 frontmatter title 渲染大标题，正文 H1 会变成视觉冗余。frontmatter 之后空一行直接进开篇正文，section 用 ## 1. xxx / ## xxx 起步
• 不要在标题里加编号 - 不用"一、""二、""三、"，也不用"1.""2.""3."。标题就是描述性的短语，编号是多余的
  • 好：## 坑：sha256 校验挂了
  • 避免：## 二、坑：sha256 校验挂了
• 标题保持简洁，不带"主标：副标"结构。 只保留核心概念，补充细节（具体技术名词、解释性内容、本节要拆解什么）放到该章节的正文开头自然引出，而不是塞到标题里。frontmatter 的 title 字段同样不带解释性副标 - 让正文负责展开
  • 好：## 核心机制（正文开头再介绍 ui:// 协议和 iframe 沙箱）
  • 好：### 5.1 Offscreen 侧（正文负责讲拆什么）
  • 避免：## 核心机制：ui:// 协议和 iframe 沙箱
  • 避免：### 5.1 Offscreen 侧：拆 WebRTC + 释放音频
• 文章的结尾应该自然收束，不需要仪式感的"总结"章节
• 如果一个子标题只是在给下方内容贴标签（比如"与其他方案的对比"），那它可以被一句自然的引导语替代

2. 用散文连接，不要硬切

话题之间用自然的过渡句桥接，而不是靠标题层级的机械跳转。整篇文章读起来是一个连贯的叙事，不是一份提纲。

• 大的话题转换处，加一句桥接语把上下文串起来
• 写博客不是写论文，语气可以随性、温暖

3. 开篇与收尾

开篇段落承担「写作意图 + 主角点名」两件事，引子可以用客气话收个尾再进正文。

• 开篇用第一人称声明这篇要做什么。 「我会梳理 X」「我会利用这份代码讲清楚 Y」 比「这篇拿 X 当骨架」「本文 Y」更亲近，是中文技术博客的成熟写法
• 开篇至少出现一次主角的英文 ID（产品名、模型名、工具名、库名），用反引号 ` 包起来。即使 frontmatter title 已经写过，正文第一段也要重提一次 - 让扫读读者和搜索引擎都抓得住主题
• 引子末尾可以用「期望对大家有所帮助」类客气话收尾再进正文章节。这是中文技术博客的标准惯例，避免技术作者常见的高高在上的语气
• 文章结尾自然收束，回到「跑起来」「资源链接」之类的开放尾部，不要写「总结」「最后」「结语」之类显式的终结章节

Examples

✅ 好：
OpenAI 5 月 7 号在 Realtime API 里放了 `gpt-realtime-translate` - 一个端到端 speech-to-speech 的实时翻译模型。我做了一个 Chrome 扩展叫 `open-realtime-translate` 调通它。

这篇不是产品介绍。我会利用这份代码，把 `gpt-realtime-translate` 模型的使用梳理清楚 - 怎么 X、怎么 Y、怎么 Z。期望对大家有所帮助。

❌ 避免：
# OpenAI gpt-realtime-translate 实战：以 open-realtime-translate 代码为骨架，讲清整条连接生命周期

OpenAI 5 月 7 号 ......

这篇不是产品介绍。这篇拿这份代码当骨架，讲清楚怎么 X、怎么 Y、怎么 Z。每一步都贴真实代码，不是伪代码。

错的版本里有三处问题：H1 重复 frontmatter title、标题带"以 X 为骨架"副标、开篇用「这篇」非第一人称、末尾「每一步都贴真实代码」是 selling line（见下条规则）。

4. 不写 trust-me / 自夸句

事实让读者自己判断。不要在文章里提前夸自己 / 夸内容质量 / 引导读者预先信任。这条覆盖博客和推文都适用。

判断方法：句子如果能被压缩成「这（产品 / 做法 / 文章）+ 最高级形容词」（最稳、最详细、最完整、最干净），它就是 selling line，删掉。show, don't tell。

5. 尾部克制

强烈偏好轻量级结尾。 文章最后不要做仪式感的总结、不做正反对比定位、不做资源清单堆砌。让最后一节自然结束就好。

不要写

• ❌ ## 总结 / ## 最后 / ## 结语 / ## 写在最后 等显式终结章节
• ❌ 收尾段做横向对比定位：「它是 X，不是 Y 的替代品。Y 在 A 上强，X 在 B 上顺手」- 即使每句都是事实，组合起来就是 positioning，读起来像产品页 elevator pitch
• ❌ ## 链接合集 / ## 资源 header 配 2-3 条链接，里面还有正文 inline 已经出现过的重复链接

怎么收

• ✅ 最后一节自然讲完就停。不解释、不总结、不"小结一下"
• ✅ 一两个核心外链（仓库、主资源）→ 文末加一个 --- 分隔线 + 裸 bullet，不加 section header
• ✅ 三条以上链接、或链接需要分组才用 ## 链接合集 这类 header
• ✅ 正文 inline 已经出现的链接，结尾不要再列一遍

Examples

✅ 轻量结尾（推荐）：
...... 最后一节正文结束 ......

---

- 仓库：[github.com/sugarforever/01coder-agent-skills](https://github.com/sugarforever/01coder-agent-skills)

❌ 总结 + 对比定位 + 重复链接（避免）：
...... 最后一节正文结束 ......

定位是清楚的：它是一个 X，不是 Y 的替代品。Y 在 A 上更强，X 在 B 上更顺手。两边并不互斥。

## 链接合集

- 仓库：[github.com/.../...](...)
- 配套博客：[正文已经 inline 过的那篇](...)
- 文中提到的 API 文档：[正文已经 inline 过的那个](...)

判断方法：把文章最后一节之后的内容删掉，剩下的文章是否完整、流畅、不悬空 - 如果是，那段尾部就是冗余的。