开发文档写作规范

文档的读者是正在接入的开发者：他们想尽快把功能跑起来，遇到问题时再回来查细节。每一页都按这个顺序写，先给能用的，再给完整的。

页面结构

顺序	内容	要求
1	一句话说明	这页能做什么，常见用途。不写背景和原理
2	快速开始	一个复制就能运行的最小示例，用真实的值；后面一两句说明结果是什么
3	你负责 / SDK（服务端）负责	客户端页面用一张表说明哪些事不需要开发者写代码；服务端页面可以换成“按需求选择字段”的表
4	常见任务或常见场景	每个任务一个小节：标题是开发者要做的事，一两句话加一段代码。任务较多时先给一张“要做什么 → 用什么 → 见哪一节”的索引表
5	接口参考	请求体、参数、返回值、错误码，用表格
6	规则与细节	限流、边界情况、不检查的内容、内部行为，放在最后

已有的页面按这个顺序调整，不删减信息：规则和细节往后移，不是去掉。

短句，一句一个事实。 一段里列了三个以上的条件、情况或限制，改成列表或表格。
写开发者要做什么。 “你调用 X，SDK 负责 Y”，不要描述 SDK 内部怎么实现，除非它影响开发者的写法。
不用内部术语。 第一次出现时用大白话解释，或者直接换成大白话。标题尤其如此，例如“本地优先”写成“先显示本地数据”。
错误码用表格。 同一个 code 下有多个 details.reason 时，按 reason 拆成一张表，并写清原因；能给出处理方式的写上处理方式。
示例要能运行。 用 alice、bob、demo 应用这些贯穿全站的值；TypeScript 示例要通过类型检查，需要的外部变量用  声明。
“什么时候用”写在字段旁边。 有默认值的开关，说明在什么场景下要改它，以及为什么。

保留锚点。 其他页面会链接到本页的标题。改了标题文字时，用 {#原来的锚点} 保留原锚点，例如 ### 先显示本地数据 {#本地优先}。改完后确认原有锚点都还在。
代码块尽量不改。 代码块在译文中必须逐字相同，改动代码块就要同步改英文和繁体。
同步译文。 中文改完后更新英文和繁体译文及 translations.json 的源哈希，见下文。

英文由人工按上面的规范写，不做逐句直译；繁体由 OpenCC 从简体转换。用 tools/i18n/sync_translations.py 生成两种译文并更新源哈希：

为每个改过的页面写一份英文草稿，代码块的位置写一行 @@FENCE@@（脚本按顺序填入原文的代码块），标题数量与原文相同（锚点由脚本补齐）。
运行脚本（需要 pip install opencc）：
bash
```
python3 tools/i18n/sync_translations.py --drafts <草稿目录> docs/server/message/send.md docs/client/web/messages.md
```
草稿文件名是页面路径把 / 换成 __，如 docs__server__message__send.md。不给草稿的页面只更新繁体和英文的源哈希。
构建并检查：在 web/docsweb 中运行 pnpm exec vitepress build --outDir /tmp/im-docs-preview，再在仓库根目录运行 python3 tools/i18n/check.py --build-dir /tmp/im-docs-preview。