GoQQBot 文档风格指南

以 SDK 维护者的身份为开发者写文档。功能页说明如何配置、调用和判断结果。涉及实机测试时，写清测试场景、平台返回及验证范围，避免使用「本轮交付」或「未完成验收」等项目过程用语。

所有 wiki 页面的写作和润色必须遵守本指南。润色只允许修改表达，不得删除缺陷说明、平台限制和错误码等事实性内容。

结构

1. 页面标题用动宾短语（"发送 Markdown"）。
2. 正文顺序：先一段话说清这页帮你完成什么 → 代码示例 → 简要说明 → 独立的"注意事项"小节（有坑才设）→ 另请参阅。
3. 三件事以上必须拆成无序列表，一条一事，一行一条。禁止用分号连接两个以上意思。
4. 每个二级标题下第一段是结论或做法，限制和坑一律移入"注意事项"。

语言

1. 一段只回答一个问题。先讲读者要做什么，再解释条件和结果。将紧密相关的说明写在同一段，按语义组织句子，不按固定字数切分。
2. 代词必须有明确主语。禁止"它会……""这是……"开头指代不明的句子。
3. 禁止翻译腔，对照表：
   • 必须互斥 → 二选一，不能混用
   • 内容来源 → 来源
   • 在……时中止/降级 → 失败时直接不发 / 退回预填
   • 替代文本 → 替代文本（alt text）
   • 请注意 / 需要注意的是 → 直接删，或写进注意事项列表
4. 正文里用中文说行为，代码标识符保留原文；禁止"非 nil 结果 + 非 nil 错误"这类代码混排，改写为"返回了结果但 err 也不是 nil"。
5. 数字要给出算式或出处："两列最多 10 个（5 行 × 2 列）"，不要凭空跳数。
6. 不好直译的术语首次出现括注英文原文："替代文本（alt text）"。每页最多 5 处。
7. 采用自然、准确的书面中文，用读者能观察到的行为解释接口。比如，把“不执行 I/O，返回快照”写成“只在本地解析消息，不向 QQ 发请求。返回的是一份独立副本，修改其中的字段不会影响 SDK 内部的数据”。
8. 代码示例前说清怎么用，示例后只解释读者需要理解的行为。权限、失败条件和例外统一放进独立的二级标题“注意事项”。同一条限制在一页里讲清一次即可。

链接

1. 正文提到其他页面的内容时加相对路径内链；目标页面必须存在。
2. 每页底部"另请参阅"保留原有链接并补齐缺失项，用" · "分隔。
3. wiki/_Sidebar.md 是导航，不参与润色。

语气

1. 用陈述后果代替禁令：不说"不要将 X 当 Y"，说"把 X 当 Y 会发送失败"。
2. 正文禁令式祈使句（不要/必须/不能开头）每页最多两处；注意事项小节内的条目不受限。
3. 开头禁止"本节介绍如何……"，直接说结论："Markdown 适合需要排版的回复，单聊群聊免申请模板。"

修订记录

• 2026-11-04：v1.2，按读者的问题组织段落，用可观察的行为解释接口，避免机械拆句和直译。

• 2026-11-04：v1.1，补充内链规则、术语括注规则、禁令句统计口径（仅正文）、注意事项小节设置条件。

• 2026-11-04：v1.0 初版，基于 messages/types/markdown.md 试点修订总结。