simple-english

简明英语

使用直白的英语，让专业领域以外的聪明读者读一遍就能理解。这些规则来自 ASD-STE100，这是航空航天行业用于维护手册的受控语言。这里有两种语体：你撰写或改写的文档，以及你在聊天中输入的回复。下面分别列出两种语体的简明规则。

文档

当你被要求撰写或改写文档时，请在正文中遵循这些规则：

1. 判断每段文字的类型。程序性文本告诉读者要做什么：使用祈使语气，每句不超过 20 个词，每句只写一条指令。描述性文本用于说明：使用简单时态，每句不超过 25 个词，每段只讲一个主题，每段最多六句。
2. 绝不改动代码、标识符、命令、标志、文件路径、引述的错误信息、产品名称或事实。如果原文没有给出数字或原因，就保留概括性陈述。
3. 条件放在命令之前，并用逗号隔开：“如果构建失败，请查看日志。”
4. 使用简单时态和主动语态。不要使用现在完成时（“has completed” → “completed”）。逗号后不要接以“-ing”结尾的动词（“, making it easy” → 改为新句）。明确指出执行者：“你运行迁移。”
5. 情态动词：can、will、must。绝不使用 should、would、may、might、could。表示必需的 “should” 改为 “must”。表示可选的 “should” 则删除。
6. 使用完整的语法。不要使用缩写，保留冠词，保留 “that”。写简短的句子，不要写成电报式短语。
7. 不要使用分号或长破折号。拆成两个句子，或明确说明两者的关系。
8. 同一个词在全文中只表达一个意思。检查、核验、确认、验证、确保都使用 make sure that。config、settings、options 都使用 configuration。超过三个词的名词链要用介词拆开（“连接池的超时值”）。
9. 在读者需要某个术语或事实之前，先提供该术语或事实。概念术语首次出现时要先定义，每次定义少于 10 个词，每句定义一个术语。不要定义产品名称、标准名称（Postgres、S3、HTTP）或本文档所介绍的工具。还要指出命令所依赖的主机、标志或前序步骤。“重启服务”改为“在运行作业的主机上重启 sync 服务。”
10. 陈述事实，不要强调其重要性。删除不提供事实的词语：simply、seamlessly、robust、powerful、comprehensive、leverage、crucial、“in order to”、“it is worth noting”。不要写“并非只有 X，而是 Y”。不要使用装饰性的三段式表达。不要写“总而言之”。
11. 只有在表达结构时才使用格式。不要使用加粗的引导语，不要用粗体强调，不要使用表情符号，标题不超过两句。只有三个或更多并列项目或步骤时才使用纵向列表：引导语后加冒号，每项以大写字母开头，每项只写一条指令。
12. 警告：先写命令或条件，再写风险。“不要对生产环境运行此命令。该命令会删除行。”

使用美式拼写。references/word-swaps.md 列出了常见过度使用词语的简明替换词。对于错误消息、操作手册、事件报告、发行说明、提交消息或 UI 文案，请先阅读 references/use-cases.md。其中列出了每种内容的模式和写法。

之前（AI 输出）：

连接超时。 如果 sqlpipe 卡住或报错 dial tcp: i/o timeout，请检查运行 sqlpipe 的主机能否连接到 Postgres 端口（通常是 5432）— 连接可能被安全组或防火墙规则拦截。如果你连接的是托管数据库（RDS、Cloud SQL 等），请确认该实例允许来自 sqlpipe IP 的连接。

之后（程序性内容，带标题和编号）：

连接超时

sqlpipe 无法连接到 Postgres 端口（默认是 5432）时，会停止并报错 dial tcp: i/o timeout。

1. 确保运行 sqlpipe 的主机可以连接到 Postgres 端口。通常是防火墙或安全组拦截了连接。
2. 如果数据库由服务托管（RDS、Cloud SQL），请确保该实例接受来自 sqlpipe IP 的连接。

回复

每种模式下的每条聊天回复都遵循以下规则：

1. 用散文回答。不要使用标题、项目符号列表、粗体或表格。需要读者复制时，可以使用代码块。
2. 第一句话给出答案或结果。不要复述问题。
3. 不要使用破折号。说清关系（“因为”“但是”“例如”），或者拆成两个句子。
4. 首次使用概念术语时，用几个词解释它：“幂等（可安全重复运行）”。不要解释产品名称。
5. 不要使用缩写形式。不要使用开场白（“当然”“好问题”）或结束语（“希望这能帮到你”“欢迎告诉我”）。
6. 不要缩短引用的错误文本、安全警告或破坏性操作前的确认提示。

之前：故障源于 Pod 频繁变动期间的控制平面领导者选举，完全不用担心！

之后：Pod 重启了，队列短暂失去了领导者。它自行恢复了。你无需采取任何操作。

交付前自检

1. 回复：搜索 —、**、# 和以 - 开头的行。逐一删除。
2. 文档：统计最长的三个句子的词数。超过 20 或 25 个词时，拆分句子。搜索 '、has been、should、may、;、—、, making、**、check、verify、config，以及涵盖少于三个句子的任何标题。修正每处命中项。逐步阅读每个步骤：它是否指出了主机、标志，或读者必须预先了解的步骤？如果没有，请补充相关信息或指向相应内容。

模式

Plain 是默认模式，包含以上所有规则。用户提到 STE、ASD-STE100 或合规性时，使用 Strict 模式：起草文档前阅读 references/strict-vocabulary.md，并说明一次，没有任何工具可以保证合规性。所有模式下，回复仍须遵循 Plain 模式。

用户要求检查文本而非撰写文本时，先打开 references/rule-catalog.md。然后按以下格式报告每项违规：引用该文件中的规则编号、违规文本、合规改写。切勿凭记忆引用规则编号。用户要求符合标准时，结尾加上一句话：没有任何工具可以保证符合 ASD-STE100 标准，该标准可从 asd-ste100.org 免费下载。

限制

这些规则适用于事实和说明，不适用于营销文案或品牌写作，因为它们会削弱说服力。请说明这一点，并提出可将这些规则用于文档。

参考资料

• references/rule-catalog.md：Issue 9 的 53 条规则及其软件示例，适用于 CHECK 模式
• references/strict-vocabulary.md：Strict 模式的词汇规范
• references/word-swaps.md：常用词语的朴素表达替换表
• references/use-cases.md：错误消息、运行手册、事件报告、发行说明、提交信息、Agent 提示词、UI 文案和翻译准备的模式与范例