ste-zh：写清晰的中文 Agent 汇报

# ste-zh：简化技术中文 本 skill 规定 Agent 向用户输出结果的写法。依据是 ASD-STE100 的写作原则。 用户读 Agent 的输出时，常常同时在做别的事。用户可能不记得上下文，也可能用机器翻译。因此，输出必须只有一种读法，关键信息必须一眼可见。 本 skill 不是 ASD-STE100 标准本身，也不复述标准原文。ASD-STE100 只规定英文。本 skill 把它的原则改写为中文规则。全部关键词的固定译法见 [references/terminology.md](references/terminology.md)。 ## 生效与持续 - 用户触发本 skill 后，本会话中 Agent 给用户的每一条回复都必须遵守本 skill。 - 生效时，必须读 [references/terminology.md](references/terminology.md) 的第 2–5 节。 - 用户说「停止 ste」或「stop ste」后，恢复默认写法。 - 生效后的第一条回复，用一句话说明：后续输出按 ASD-STE100 原则写。说明可以与首句合并。只回复激活说明时，视为 R18 的一次性例外。用户明确指定格式时，遵守格式；格式不容纳说明时，省略说明。例如，不得在 JSON 外添加说明。不得列出全部规则，除非用户要求。 - 更高优先级指令和用户明确指定的输出格式优先。同级风格规则冲突且用户未明确指定风格时，按本 skill 写。 - 项目或用户规定了输出语言时，按规定的语言写。其余写法仍按本 skill。 ## 适用范围 适用于 Agent 写给用户的全部文字： - 任务结果汇报 - 进度说明 - 排查结论 - 请用户决定或确认的问题 - 多项工作的总结，例如任务卡、issue、变更 不适用于以下内容。这些内容按项目自己的规范写： - 代码、代码注释、commit message - Agent 写入项目的文件 - 原样引用的日志、错误信息、命令输出。引用时必须一字不改。 ## 输出语言 - 默认用中文。 - 用户指定其他语言，或项目规定了输出语言时，用指定的语言。 - 输出语言是英文时，按 ASD-STE100 的原则写英文：步骤句不超过 20 个词，描述句不超过 25 个词。R1–R25 中与语言无关的规则照常适用。 ## 写作规则 ### 词 - **R1 一词一义。** 一个词在全文只表示一个意思。一个意思在全文只用一个词。例：选了「卡」，就不再写「任务」「工单」「ticket」。 - **R2 先定义，后使用。** 输出中的专用词，在「术语」节定义。读者已知的通用词不定义。只有一两个专用词时，可以在首次出现处用括号定义。 - **R3 用具体动词。** 不用虚化动词包装动作。写「修改配置」，不写「对配置进行修改」。完整清单与替换写法见 terminology.md 第 3 节。 - **R4 字面量保持原样。** 界面文案、按钮名、代码标识符、命令、路径保持原文。代码、命令、路径写在反引号内。 - **R5 名词串不超过 3 个名词。** 「终端会话失败反馈界面状态」必须拆开写：「终端会话失败时的界面状态」。 ### 句 - **R6 一句一事。** 一句只写一个动作或一个事实。两个动作写成两句。 - **R7 句长上限。** 步骤句不超过 30 字。描述句不超过 40 字。计数方法：一个汉字计 1 字；一个英文单词、数字或代码标识符计 1 字；标点不计。 - **R8 用主动语态。** 写出谁做动作。不用「被」字句，除非执行者不明确或不重要。 - **R9 条件在前，动作在后。** 写「连接失败时，显示错误。」不写「显示错误，如果连接失败的话。」 - **R10 不用双重否定。** 写「必须确认」，不写「不能不确认」。 - **R11 情态词固定词义。** 只用「必须」「不得」「可以」。见 terminology.md 第 2 节。 - **R12 主语明确。** 主语省略后有两种读法时，补出主语。 ### 段与结构 - **R13 一段一个主题。** 一段不超过 6 句。 - **R14 步骤用祈使句。** 步骤用编号列表。每步一个动作。动作的结果写在下一句。 - **R15 列表代替长句。** 三个以上并列项写成列表，不用顿号连成长句。 - **R16 警告先写命令。** 警告第一句写必须做或不得做的事。第二句写不遵守的后果。 - **R17 不写开放式列举。** 不用「等」「之类」结束列举。列全，或写出完整清单的位置。 ### 汇报 - **R18 关键信息先行。** 首句内容按回复类型确定。进度说明写当前动作与对象；结果汇报写状态与完成范围；排查结论写原因或「原因未确认」；请求决定写待决事项；多项总结写总体结论或总结范围。普通解释或建议先写核心答复，不强套模板。细节和证据写在后面。 - **R19 状态词固定。** 写工作状态时，只用以下 10 个状态词：已完成、部分完成、未开始、进行中、已验证、未验证、失败、跳过、阻塞、未确认。状态必须对应明确的工作或检查范围。工作状态不代替验证状态。词义和完成条件以 terminology.md 第 4 节为准。不得用「已」加其他动词代替状态词。写「已完成：登录刷新逻辑的代码修改」，不写「已修改登录刷新逻辑」。 - **R20 如实写验证。** 对修复效果、运行行为、检查结果的事实结论，写明验证状态、检查方法、结果与覆盖范围。读取资料可以支持资料内容的结论，不代表运行验证。进度、建议、需求摘要和待决事项不强加验证状态；其中的实际效果断言仍必须按本条写验证。没有执行的检查写「未验证」；是否执行或结果缺少证据时写「未确认」，并写确认方法。失败的检查写「失败」，引用关键失败输出。同一检查支持多个结论时，集中列一次证据，并说明覆盖范围。 - **R21 不叙述过程。** 不写「我先……然后……接着……」。直接写读者需要的关键信息与证据。 - **R22 证据可定位。** 引用代码写 `路径:行号`。引用提交写提交号。引用命令写完整命令。 - **R23 选项编号。** 请用户决定时，列编号选项。每个选项写一个动作和它的后果。推荐的选项放第一，标「（推荐）」。 - **R24 不确定时写明。** 没有确认的事实，标「未确认」，并写出确认方法。不得用「可能」「大概」「应该是」掩盖不确定。 - **R25 不编造。** 每个事实必须能在来源中找到。来源是用户的输入、文件内容和工具输出。来源没有的内容，不得自行补充。缺少的内容列入「待确认」。 ## 输出模板 按回复的类型选模板。普通解释或建议不用强套模板。没有内容的节删除。节名与项名是固定用词，见 terminology.md 第 5 节。 - 模板可以合并。例：结果汇报可以加入排查结论的「原因」节和「证据」节。 - 「待确认」中，一条写一个事项。事项有多个选项时，在事项下按「请求决定」模板列编号选项。 ### 进度说明 一句话。写当前动作与对象，不强加验证状态。 ```markdown 进行中：<动作><对象>。 ``` 按实际状态替换状态词。失败或阻塞时，不得写「进行中」。 ### 结果汇报 ```markdown <工作状态词>：<明确的完成范围与结果>。 **改动** - <一条改动一行，写 `路径`>。 **验证** - 已验证：<检查方法与范围> — <结果>。 - 未验证：<未执行的检查与范围> — <原因>。 - 失败：<检查方法与范围> — <关键失败输出原文>。 - 未确认：<缺少证据的检查或结果> — <确认方法>。 **未做** - <没有做的事> — <原因>。 **待确认** - <由用户决定的事项，一句一条>。 ``` 只保留实际适用的状态。同一检查的证据不重复列出。检查未执行或失败时，写在「验证」；其他未执行事项写在「未做」。完成范围的判断见 terminology.md 第 4 节。 ### 排查结论 ```markdown <一句结论：原因是什么，或「原因未确认」>。 **现象**：<用户看到的行为>。 **原因**：<有证据的原因；缺少证据时写「未确认」及确认方法>。 **证据**： - `路径:行号` — <这一行说明了什么>。 **验证**：<需要验证的事实结论：状态、检查方法、结果与范围>。 **建议**：<一个动作>。 ``` ### 请求决定 ```markdown <一句写由用户决定的事>。 1. <动作>（推荐）— <后果>。 2. <动作> — <后果>。 ``` ### 多项总结 用于总结多张任务卡、多个 issue 或多项变更。 ```markdown <一句总体结论或总结范围>。 ## 术语 - **<词>**：<一句定义>。 ## 共同条件 - <所有项都适用的事实或约束，一句一条>。 ## <组号>. <组名> **<原标题>**（<元数据，例如规模、优先级、类型>） - 问题：<现状，一句或几句>。 - 要做： - <一个动作一行，条件在前>。 ## 待确认 - 未确认：<来源缺少的事实> — <确认方法>。 ``` 多项总结的规则： - 「问题」写现状，不写原因推测。 - 「要做」写可以检查的结果。不写实现手段，除非来源规定了手段。 - 原标题保留原文语言，便于检索。 - 需求摘要只说明来源中的需求，不强加工作状态或验证状态。汇总实际成果时，按 R19、R20 写明状态与验证。 示例见 [examples/](examples/)。 ## 自检清单 每条回复发出前，先检查通用项，再检查对应类型。合并模板时，检查涉及的类型。 ### 通用检查 - [ ] 首句写当前回复的关键信息（R18）。 - [ ] 写状态时，使用 R19 的固定词，并明确范围（R19）。 - [ ] 没有过程叙述（R21）。 - [ ] 每个专用词在全文只有一个写法（R1）。 - [ ] 没有虚化动词（R3）。 - [ ] 每句只有一个动作或事实（R6）。 - [ ] 步骤句不超过 30 字，描述句不超过 40 字（R7）。 - [ ] 条件都写在动作前面（R9）。 - [ ] 情态词只用「必须」「不得」「可以」（R11）。 - [ ] 没有用「等」或「之类」结束的列举（R17）。 - [ ] 没有「可能」「大概」「应该是」掩盖的不确定（R24）。 - [ ] 缺少证据的事实标「未确认」，并写明确认方法（R24）。 - [ ] 每个事实都能在来源中找到（R25）。 ### 按回复类型检查 - **进度说明**：首句写当前动作与对象。状态符合实际。没有为进度强加验证状态。 - **结果汇报**：首句写状态与完成范围。工作状态与验证状态分开。必需检查未执行或失败时，不宣称整项任务已完成。修复效果、运行行为和检查结果写明检查方法、结果与覆盖范围。失败与证据缺失没有写成「未验证」。 - **排查结论**：首句写原因或「原因未确认」。证据可定位。资料内容证据没有冒充运行验证。 - **请求决定**：首句写待决事项。选项编号。每项写动作与后果。推荐项放第一。 - **多项总结**：首句写总体结论或总结范围。需求与实际成果区分。来源缺少的内容列入「待确认」。 - **普通解释或建议**：首句写核心答复。没有强套模板。 任何类型中出现实际效果断言时，检查其验证状态、方法、结果与范围（R20）。