文档写作规范

这份规范回答一个问题：怎样让第一次来的读者读完一页就能做成一件事，同时不挡住想深入的人。

改写或新增 docs/ 下的页面前请先读完本页。它约束的是用户文档（开始、使用、插件开发、AI、运维）；ADR、目标架构等维护者文档不受版式约束，但仍遵守语言规则。

三条总原则

先结果，后原理。 读者来是为了做成一件事。先给能复制运行的步骤和可见的结果，原理放在"它是怎么工作的"一节，或者链接到深入原理。
一次只引入一个新概念。 每出现一个读者没见过的名词，就要当场用一句话解释，或者链接到核心概念速览。同一段里不要堆叠两个以上新名词。
默认路径写在正文，例外写在折叠块。 90% 的读者会走的路径放正文；边界情况、兼容说明、内部实现细节放进 ::: details 或页尾的"深入"一节。

页面类型

每一页只属于一种类型。类型决定了版式。

类型	读者的问题	放在哪里	例子
教程	"带我做一遍"	开始	快速开始、第一个插件
指南	"我要做成 X，怎么做？"	使用与配置、插件开发、AI、运维	命令、接入平台、部署
概念	"它为什么这样设计？"	深入原理	插件模型、消息流
参考	"这个字段 / 参数是什么？"	参考	配置字段、CLI、API

不要在一页里混写类型。指南写到一半开始讲内部数据结构，说明这部分应该拆到概念页。

版式模板

指南页

# 动词开头的标题（例：给命令声明参数）

一句话：这页帮你做成什么。一句话：做完后你会看到什么。

::: tip 开始前
需要先完成 / 先安装的东西（没有就删掉这个块）
:::

## 最常用的写法
一个完整、可复制的最小示例 + 运行后的效果。

## 常见需求
### 需求 A
### 需求 B
每个小节：一句话场景 → 代码 → 一句话结果。

## 它是怎么工作的（可选）
三到五句话的原理，链接到概念页。

## 常见问题 / 故障排查（可选）

## 下一步
2～4 个链接，每个说明"读它能做到什么"。

概念页

# 名词（例：插件模型）

一段话：这个概念解决什么问题，用一个具体场景引出。

## 一张图
mermaid 或 text 图，只画读者需要记住的部分。

## 核心规则
3～5 条，每条一句话加一个例子。

## 细节
按需展开；字段表、边界条件、错误类型放这里。

## 相关

参考页

参考页可以长，但每一节都要能被单独搜索到：标题即字段名或命令名，第一句话说明用途，然后是表格或代码。

渐进披露节奏

一页内容按"层"往下走，读者可以在任意一层停下：

层	内容	读者在这里停下也能…
1. 开头两句	这页做什么、做完看到什么	判断这页是不是自己要的
2. 最小示例	一段能直接复制运行的代码	完成最常见的需求
3. 常见需求	按场景组织的小节	完成 80% 的需求
4. 原理与细节	工作机制、边界条件、完整字段	处理少见情况
5. 链接	概念页、参考页、源码	继续深入

具体做法：

示例从小到大。 第一个示例只演示一件事，后面的示例每次多加一个能力。
字段表放在示例之后。 先看见用法，再看完整字段；不要用一张十几行的表格开头。
内部名词往下放。 generation、projection、Capability Slot、Scope、Token 等实现词汇，只在第 4 层出现；第 1～3 层用"热重载""自动注册""插件资源"等用户能感知的说法。
用折叠块收起例外。 兼容说明、迁移注意事项、仅维护者关心的约束用 ::: details 标题。
每页最多一个 ::: warning。 警告多了等于没有警告；只留会导致数据丢失、安全问题或无法启动的事项。

版式规则

标题：一级标题一页一个。指南页的二级标题用动词短语（"声明参数""发送图片"），概念页用名词。不超过三级标题。
段落：一段只讲一件事，不超过 4 行。长段落拆成列表或表格。
列表与表格：并列的 3 个以上选项用列表；需要对比两个以上维度时才用表格。表格单元格里不写长句。
代码块：
- 第一行用注释写文件路径（// commands/hello/index.ts），读者才知道放哪里。
- 只放与当前话题相关的代码，省略部分用 // ...。
- 命令行示例用 bash，目录结构用 text，并在关键行后用 # 注释说明。
提示块：tip 写捷径和建议，warning 写会出事的事项，details 写可跳过的细节。不要用提示块承载正文。
链接：链接文字说明读者会得到什么（"给命令加权限"），不要写"点这里""见此"。

语言规则

用读者的词，不用实现的词

不要写	改成
能力进入当前 generation 的 projection	文件保存后自动注册，热重载后生效
拓扑唯一事实源	`package.json` 的 `zhin` 字段决定装了哪些插件
Feature provider 发现约定目录	放进 `commands/` 的文件会被自动识别为命令
经 Host Token 注入	从 `context.resources` 取用
黄金路径	默认路径 / 最简单的路径
闭环	完整流程 / 走通
SSOT	唯一来源（只在维护者文档中使用）

实现词汇不是禁用词：在概念页和参考页，它们是精确的名字。规则是第一次出现时解释，且不出现在页面开头。

句子

主动语态，第二人称。 "你在 commands/ 里创建文件"，而不是"文件应被创建于 commands/"。
一句话一个意思。 超过两个逗号就考虑拆句。
先说做什么，再说为什么。 "把密钥放在 .env，这样它不会被提交到 Git"，而不是反过来。
具体胜过抽象。 用 /remind 10 喝水 代替"带参数的命令"，用"两个 QQ 号"代替"多个 Endpoint 实例"。
不说"简单""只需""显然"。 读者卡住时，这些词会让他们觉得是自己的问题。
不写营销语。 "强大""优雅""极致"不提供信息；直接写能做到什么。

中英文混排

中文与英文、数字之间加空格：安装 zhin.js 后、默认端口 8068。
代码、包名、文件名、命令用反引号：`zhin.config.yml`。
产品名保持原样：Zhin.js、Console、Sandbox、Agent；通用概念用中文：插件、命令、中间件、适配器。
中文页用全角标点，代码与英文短语内部保留半角。

中英文页面同步

中文是源语言，docs/en/ 是对应译文。新增或改写中文页时，同一个 PR 内同步英文页的结构（标题层级、示例、链接）；措辞可以按英文习惯调整，不必逐字翻译。

提交前自查

[ ] 只读前两句，能判断这页是否是自己要的吗？
[ ] 第一个代码块能直接复制运行吗？标了文件路径吗？
[ ] 页面前半部分出现的每个新名词都解释了或链接了吗？
[ ] 内部实现词汇是否都在后半部分？
[ ] 有没有超过 4 行的段落、超过一个的 warning？
[ ] 结尾有"下一步"吗？
[ ] 英文页结构同步了吗？
[ ] frontmatter 的 title / description 用双引号包裹了吗？（值里出现英文冒号加空格会导致 YAML 解析失败、整站构建失败）
[ ] pnpm check:doc-links、pnpm check:doc-orphans 和 pnpm docs:build 通过了吗？

文档写作规范 ​

三条总原则 ​

页面类型 ​

版式模板 ​

指南页 ​

概念页 ​

参考页 ​

渐进披露节奏 ​

版式规则 ​

语言规则 ​

用读者的词，不用实现的词 ​

句子 ​

中英文混排 ​

中英文页面同步 ​

提交前自查 ​