skills/doc-funcs/SKILL.md

@@ -52,7 +52,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
 
 對每個指令檔，subagent 要**複製原始指令檔的完整內容**到草稿，並補上註解，作為實作時直接覆蓋原檔的版本。草稿檔放在 `.docs/doc-funcs/commands/{relative-path}` （保留原副檔名，便於語法檢查）。草稿內容規則：
 
-- 檔案開頭必須有一段註解區塊，包含「該份指令檔的用途」與「更新日期」。更新日期使用台灣時區（Asia/Taipei）並固定輸出為 `yyyy/MM/dd HH:mm:ss`（可用 `TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'` 取得）。
+- 檔案開頭必須有一段註解區塊，且「該份指令檔的用途」與「更新日期」必須包在同一個區塊內，不得拆成兩個分開的註解區塊。更新日期使用台灣時區（Asia/Taipei）並固定輸出為 `yyyy/MM/dd HH:mm:ss`（可用 `TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'` 取得）。
 - 原指令檔的每一行有效指令之間必須換行，且每行都要有對應的註解說明，解釋這行在做什麼、為何需要、重要參數或副作用。
 - 註解符號必須符合該檔案類型：`*.sh`/`*.bash`/`*.ps1`/Makefile/yaml/Dockerfile 用 `#`；`*.bat`/`*.cmd` 用 `REM` 或 `::`。若該行語法不允許行尾註解（例如某些 yaml 值），改用該行上方獨立一行註解。
 - 必須保留原始指令的實際行為與順序，只新增註解與開頭用途/日期區塊，不得變更指令邏輯；若發現原指令可能有問題，於草稿中以註解標註「需人工確認」，不要逕自修改。
@@ -83,6 +83,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
 - 指令檔草稿：用草稿內容**覆蓋原始指令檔**（草稿已是含用途/日期/逐行註解的完整版本）。
 - 若選「逐個草稿實作」，每完成一個就回報並等待使用者確認。
 - 若遇到大量目標，仍要分批持續處理，不要只做示範。若 token 或時間不足，先完成已列入 index 的批次，並在 `.docs/doc-funcs-index.md` 標記 pending。
+- 輸出訊息格式：若該 function 有輸出訊息（例如 log、console 輸出、回傳給使用者的提示訊息），訊息格式必須統一為 `[{階段(英文名稱)?}][{等級:INF/WRN/ERR/TRC/DBG}][{時間}]: {訊息}`。其中 `階段` 為選填（英文名稱，無對應階段時可省略整個 `[{階段}]` 區塊）；`等級` 必須是 `INF`/`WRN`/`ERR`/`TRC`/`DBG` 其中之一；`時間` 使用台灣時區（Asia/Taipei）。調整輸出訊息格式時僅限本次被文件化的原始碼，且不得改變訊息所反映的實際行為或判斷邏輯。
 
 ## 第 7 步：實作註解後，優化被文件化原始碼的效能與排版
 
@@ -142,6 +143,7 @@ README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.do
 - 不要新增與文件無關的 helper、測試或重構。
 - 草稿是實作依據，不能跳過；所有草稿一律由 subagent 產生。
 - function 註解步驟不得為了文件改變 runtime 行為；效能優化僅限第 7 步、僅限本次被文件化原始碼，且必須保持對外行為等價並驗證。
-- 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯。
+- 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯；指令檔開頭的用途與更新日期必須包在同一個註解區塊內。
+- function 若有輸出訊息，訊息格式必須統一為 `[{階段(英文名稱)?}][{等級:INF/WRN/ERR/TRC/DBG}][{時間}]: {訊息}`（`階段` 選填、`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`、`時間` 用 Asia/Taipei 時區），且不得藉此改變訊息反映的實際行為。
 - 若 function 或指令行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。
 - 原始碼註解與 README 盡量使用繁體中文；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文。