bpinhosilva/ste-simplify

STE 简化

概述

使用 ASD-STE100 简化技术英语（STE） 的实用子集，生成清晰、无歧义的解释和指令。

核心原则： 一词一义，一句一意；主动语态，简单时态。

此为 STE 的子集，非完整规范。不得在输出中声称符合 ASD-STE100。

请勿用于创意、营销或对话式散文等注重风格的场景。

保持不变

以下内容需原样保留，仅对其周围的散文应用规则：

• 代码、命令、文件路径及引号内的值（例如 'localhost'）
• 错误消息和日志字符串
• API、函数、参数和变量名
• 产品名称、专有名词和版本号
• 引用的文本和法律文本
• Markdown 结构：重写文档时，保留标题、链接、表格和代码块。重写标题、列表项和表格单元格内的散文，但保持相同的结构。

保留原意

• 保留每个句子的动作和对象。不要添加源文本未给出的建议、原因或步骤。
• 唯一可添加的内容是对技术术语的单句定义（参见“词汇”部分）。
• 表示可能性时，使用如果、有时、可能或可以。切勿将可能性变成事实。
• 如果简单词会损失精确性，则保留原词并加以定义。
• 如果源文本包含奇怪或错误的术语，保留源文本措辞。在文本后添加一行以**注意：**开头，说明问题。不要静默修正。
• 如果源文本包含孤立的等等（前无列表），则删除它。

规则

1. 词汇

• 一词一义。 整个文本中对同一事物使用同一词汇。不要重命名事物。

• 选择简单词：

  使用	替代
  使用	利用、采用、运用
  开始	启动、发起
  停止	停止、终止、中断
  显示	演示、表明、说明
  更改	修改、改变
  确保	保证、查明
  帮助	促进、协助
  需要、必须	要求、必要
  如果	前提是、在...情况下
  因为	由于、鉴于、作为（当它们提供原因时；自从用于时间）

• 无色语、俚语、隐喻或类比。 用事物本身来解释。

• 无缩写形式。 写不而非不（示例：does not，不写 doesn't）。

• 写例如、即和等等 替代 e.g.、i.e. 和 etc.

• 首次使用时用一句话定义技术术语，如果对该主题不熟悉的读者可能不认识该术语（例如守护进程、预写日志）。不要定义必须保留的名称。

2. 名词

• 名词串最多 3 个。 使用介词拆解更长的串。
  • 错误： “运行生产数据库连接池健康检查。”
  • 正确： “检查生产数据库连接池的健康状况。”
• 保留冠词（这个、一个）。

3. 动词

• 主动语态。 指出执行动作的人或物。
  • 错误： “配置文件被服务器读取。”
  • 正确： “服务器读取配置文件。”
• 指令用祈使语气。
  • 错误： “您应该重启服务。”
  • 正确： “重启服务。”
• 简单时态。 使用一般现在时、一般过去时和一般将来时（将读取）。不要使用进行时（正在读取）或完成时（已读取）形式。Has 和 have 作为主要动词时是正确的（该账户有一个余额）。
• 情态动词： 不要使用将、可能或也许。仅用可以表示可能性。仅用能够表示能力。将应该改为祈使句，或改为必须（若行动是强制性的）。
  • 错误： “您应该在升级前备份数据库。”
  • 正确： “升级前备份数据库。”
• 不使用动名词作名词。 作为形容词的分词是正确的（正在运行的进程）。
  • 错误： “记录错误有助于调试。”
  • 正确： “在日志中记录错误以帮助您发现错误。”

4. 句子和段落

• 描述： 每句最多 25 词。每句一个想法。
• 指令： 每句最多 20 词。每句一个指令，除非两个动作同时发生。此限制也适用于编号步骤列表中的每个项目。
• 混合文本： 对每个告知读者采取行动的指令应用 20 词限制。对其余内容（包括系统工作方式的描述步骤）应用 25 词限制。
• 条件前置。
  • 错误： “如果进程停止，删除锁文件。”
  • 正确： “如果进程停止，则删除锁文件。”
• 每段最多 6 句。 每段一个主题。
• 对 3 个或更多项目或顺序步骤使用垂直列表。

5. 警告

• 如果某一步骤可能导致伤害、数据丢失或损坏，在该步骤之前放置一行简短的警告：。说明风险。
• 如果一个风险适用于多个步骤，在这些步骤的第一个之前写一个**警告：**行。

输出结构

解释概念（按此顺序使用标题；根据需要省略可选部分）：

1. 定义： 1–2 句。说明它是什么以及它做什么。
2. 工作原理： 仅当概念具有有序过程时才包括。使用编号的短句列表。
3. 关键术语： 列出文本中新手读者可能不知道的每个技术术语（定义中已定义的主要术语除外）。每个用一句话定义。如果列表为空，则省略此部分。
4. 示例： 一个具体、最小的示例。最多 5 句或步骤。

重写现有文本： 仅输出重写后的文本，如果“保留原意”规则要求，则加上一条**注意：**行。不使用标题。对步骤使用垂直列表。除非用户要求，否则不要添加前言或更改列表。

读者水平： 如果用户说读者是新手或初学者，则定义每个技术术语，并使用“关键术语”部分。如果用户未指定水平，则假定读者了解该领域的基础知识。解释具体想法，而非整个领域。

示例

重写现有文本

源文本：

部署管道的工件提升门控机制正被利用以确保未经 QA 验证的构建不会被传播到生产环境。

重写：

管道会阻止 QA 未验证的构建。只有经过验证的构建才能进入生产环境。

解释概念

请求：“解释什么是数据库索引。”

定义： 数据库索引是一种帮助数据库快速查找行的数据结构。数据库除了表之外还保留索引。

工作原理：

1. 数据库将一列或多列的值复制到索引中。
2. 数据库对这些值进行排序并存储指向每一行的指针。
3. 查询搜索排序后的值，而不是表中的每一行。

关键术语：

• 列： 表中每行的一个命名字段。
• 指针： 给出行位置的值。

示例： 一张users表有一百万行。你在email列上添加一个索引。针对一个电子邮件地址的查询现在只读取几个索引条目。没有索引，该查询会读取所有一百万行。

回复前自检

通读你的草稿一次，修复每个违规项：

• 描述超过 25 词，或指令或列表步骤超过 20 词？拆分它。
• 被动语态、进行时或完成时、将/可能/也许，或应该？重写它。
• 动名词用作名词？使用简单动词。
• 名词串超过 3 个名词？使用的、对于、在...中或到来拆解。
• 缩写形式、习语、类比或 e.g.、i.e.、etc.？替换它。
• 使用了表格“替代”列中的词汇？使用“使用”列中的词汇。
• 包含源文本中没有的事实、步骤或原因？删除它。
• 受保护的文本（代码、名称、错误、引用的值、Markdown 结构）被更改？原样恢复。
• 同一事物有两个名称？选择一个。