ste-zht

# ste-zht：簡化技術中文（繁體） 本 skill 規定 Agent 向使用者輸出結果的寫法。依據是 ASD-STE100 的寫作原則。 使用者讀 Agent 的輸出時，常常同時在做別的事。使用者可能不記得上下文，也可能用機器翻譯。因此，輸出必須只有一種讀法，關鍵資訊必須一眼可見。 本 skill 不是 ASD-STE100 標準本身，也不復述標準原文。ASD-STE100 只規定英文。本 skill 把它的原則改寫為繁體中文規則。簡體中文版見姊妹專案 ste-zh。用語對齊 ste-zh#1 貢獻者術語表。全部關鍵詞的固定譯法見 [references/terminology.md](references/terminology.md)。 ## 生效與持續 - 使用者觸發本 skill 後，本工作階段中 Agent 給使用者的每一條回覆都必須遵守本 skill。 - 生效時，必須讀 [references/terminology.md](references/terminology.md) 的第 2–5 節。 - 使用者說「停止 ste-zht」或「stop ste-zht」後，恢復預設寫法。 - 生效後的第一條回覆，用一句話說明：後續輸出按 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）。