38 lines
2.8 KiB
Markdown
38 lines
2.8 KiB
Markdown
---
|
||
name: spec-output
|
||
description: JSC plugins 共用「輸出規範」：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼、優先以 Markdown 表格與 Mermaid 圖呈現。當其他 skill 內文引用 spec-output 或 /jsc:spec-output、或執行任何 JSC skill 需要語言／編碼／呈現規範時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||
---
|
||
|
||
# spec-output — 共用輸出規範
|
||
|
||
所有 JSC skills（code／doc／generic）面向使用者的輸出與寫入檔案，一律遵守以下規範。
|
||
|
||
## 語言
|
||
|
||
- 所有面向使用者的輸出（計畫、進度、總結、反問）與寫入外部系統的內容（議題描述／留言、commit 訊息、PR 標題與描述、README、註解）一律使用**繁體中文（台灣用語）**。
|
||
- 僅程式碼識別字、檔名、指令（git／docker／curl 等）、API 路徑、YAML／JSON 鍵名、conventional commit 的 `type`、既有技術術語保留原文。
|
||
- **不可**使用簡體字；敘述句不可改用英文。
|
||
|
||
## 編碼無亂碼
|
||
|
||
- 凡輸出或寫入含繁體中文、全形標點、emoji，一律 **UTF-8（不含 BOM）**，不得出現問號方框（）或錯碼。涵蓋：產生／覆寫的任何檔案、commit 訊息、PR 標題／描述、議題內容、終端訊息。
|
||
- 實作要點：
|
||
- **寫檔**：優先用助理的檔案寫入工具（預設 UTF-8 無 BOM）。改用 shell 寫檔時，**避免 PowerShell 的 `>`／`Out-File`**（可能寫成 UTF-16 或加 BOM）；需要時用 `Set-Content -Encoding utf8NoBOM`，或在 bash 用 `printf`／heredoc。
|
||
- **commit 訊息**：用 `git commit -m` 直接帶字串，或寫進 UTF-8 無 BOM 的檔案再 `git commit -F <file>`；確保 `git config i18n.commitEncoding utf-8`。
|
||
- **API body**：以 UTF-8 JSON 檔帶入（如 `--data @body.json`）；換行必須是**實際換行**，不可讓對方顯示字面 `\n`。
|
||
- **送出前自我檢查**：產生含繁中的檔案／訊息後，回頭確認沒有亂碼或 BOM 再提交／送出。
|
||
- 若 skill 使用特定 emoji（如等級 🔴🟠🟡🔵、裁決 🚫🔁❌✅），須確保正常顯示。
|
||
|
||
## 表格與圖形優先
|
||
|
||
- 面向使用者的輸出與寫入議題的內容（需求彙整、清單、進度回報），優先以 **Markdown 表格**與 **Mermaid 圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染）呈現，讓使用者一眼看懂意圖。
|
||
- 圖表必須忠實反映實際內容，**不得杜撰**未提及的流程或資料。
|
||
|
||
## 個資保護（PII）
|
||
|
||
- 寫入外部系統的內容（議題、留言、PR、文件）**不得洩漏個資（PII）**；若來源內容含個資，僅保留必要資訊或去識別化。
|
||
|
||
## 派發 subagent 時
|
||
|
||
- 須把本規範一併寫入每個 subagent 的提示，確保各 subagent 回傳的內容同樣是繁體中文、無亂碼。
|