skills/doc-funcs/SKILL.md

@@ -53,7 +53,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'` 取得）。標頭格式必須依本 skill 的範本 `templates/command-header.md` 產生：依檔案類型選用 `#` 或 `::`/`REM` 變體，並遵守範本的佔位符與放置規則（shebang/`@echo off` 之後、外框成對）。派 subagent 產生指令檔草稿時，必須把該範本內容一併提供給 subagent。
 - 原指令檔的每一行有效指令之間必須換行，且每行都要有對應的註解說明，解釋這行在做什麼、為何需要、重要參數或副作用。
 - 註解符號必須符合該檔案類型：`*.sh`/`*.bash`/`*.ps1`/Makefile/yaml/Dockerfile 用 `#`；`*.bat`/`*.cmd` 用 `REM` 或 `::`。若該行語法不允許行尾註解（例如某些 yaml 值），改用該行上方獨立一行註解。
 - 必須保留原始指令的實際行為與順序，只新增註解與開頭用途/日期區塊，不得變更指令邏輯；若發現原指令可能有問題，於草稿中以註解標註「需人工確認」，不要逕自修改。
@@ -73,7 +73,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
 在實作到原始碼之前，主 agent 必須檢查所有草稿：
 
 - 內容以繁體中文為主、英文為輔，且沒有任何亂碼、編碼錯誤、不可讀字元或明顯破損文字。
-- 指令檔草稿的指令本體與原檔一致、註解符號正確、開頭含用途與更新日期、每行皆有註解。
+- 指令檔草稿的指令本體與原檔一致、註解符號正確、每行皆有註解，且開頭標頭符合 `templates/command-header.md` 範本（用途與更新時間同一區塊、外框成對、位置正確）。
 - workflow README 草稿需完整涵蓋 `.gitea/workflows/` 底下所有 workflow 檔案，且每個 workflow 都要有用途、觸發條件與相關參數說明。
 - 若發現問題，先修正草稿並重新檢查，通過後才能進入下一步。
 
@@ -161,7 +161,7 @@ README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.do
 - 不要新增與文件無關的 helper、測試或重構。
 - 草稿是實作依據，不能跳過；所有草稿一律由 subagent 產生。
 - function 註解步驟不得為了文件改變 runtime 行為；效能優化僅限第 7 步、僅限本次被文件化原始碼，且必須保持對外行為等價並驗證。
-- 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯；唯一例外是第 6 步的輸出訊息格式正規化（可移除區塊橫幅、把區塊名稱併入每行前綴、統一訊息格式），但不得改變訊息反映的實際行為，且開頭用途/更新日期標頭必須保留。指令檔開頭的用途與更新日期必須包在同一個註解區塊內。
+- 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯；唯一例外是第 6 步的輸出訊息格式正規化（可移除區塊橫幅、把區塊名稱併入每行前綴、統一訊息格式），但不得改變訊息反映的實際行為，且開頭用途/更新日期標頭必須保留。指令檔開頭的用途與更新日期必須包在同一個註解區塊內，且格式依本 skill 的 `templates/command-header.md` 範本。
 - function 或指令檔若有輸出訊息，訊息格式必須統一為 `[{階段}?][{等級:INF/WRN/ERR/TRC/DBG}][{時間}]: {訊息}`（`階段` 選填、沿用所屬區塊原始名稱並保留原文不翻譯、`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`、`時間` 用 Asia/Taipei 時區），且不得藉此改變訊息反映的實際行為。若該 log 被包在有名稱的區塊內（含指令檔以分隔線＋標題＋分隔線宣告的橫幅段落），須將區塊名稱當作 `階段` 名稱後移除該包裹／橫幅，且僅移除包裹、保留區塊內原有指令與行為；但開頭用途/更新日期標頭不算階段區塊，必須保留。每則訊息必須一行一則、各自為獨立的單行輸出指令，不得用區塊或字串拼接把多則訊息包成一坨輸出。
 - 若 function 或指令行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。
 - 原始碼註解與 README 盡量使用繁體中文；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文。

skills/doc-funcs/templates/command-header.md

@@ -0,0 +1,59 @@
+# 指令檔開頭「用途／更新時間」標頭範本
+
+本範本定義 doc-funcs 第 3-2 步指令檔草稿開頭必備的註解區塊格式。「用途」與「更新時間」必須包在同一個註解區塊內，不得拆成兩個分開的區塊；此標頭屬於檔案說明標頭（含外框分隔線），實作與後續輸出訊息格式正規化時必須原樣保留，不得移除或轉成 `階段` 前綴。
+
+## 佔位符
+
+- `{用途說明}`：一到三行，說明這份指令檔做什麼、在什麼情境被呼叫、重要副作用；多行時每行開頭都要有註解符號。
+- `{更新時間}`：台灣時區（Asia/Taipei），固定格式 `yyyy/MM/dd HH:mm:ss`，可用下列指令取得：
+
+  ```bash
+  TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'
+  ```
+
+## 變體 A：`#` 註解（`*.sh`、`*.bash`、`*.ps1`、`Makefile`、yaml、`Dockerfile`、docker-compose）
+
+```
+# ============================================================================
+# 用途：{用途說明}
+# 更新時間：{更新時間}
+# ============================================================================
+```
+
+填入後範例：
+
+```bash
+#!/usr/bin/env bash
+# ============================================================================
+# 用途：打包 Web 專案並上傳部署壓縮檔至部署主機，供 CI 部署階段呼叫。
+# 更新時間：2026/07/15 14:30:00
+# ============================================================================
+```
+
+## 變體 B：`::` 註解（`*.bat`、`*.cmd`）
+
+```
+:: ===========================================================================
+:: 用途：{用途說明}
+:: 更新時間：{更新時間}
+:: ===========================================================================
+```
+
+填入後範例：
+
+```bat
+@echo off
+:: ===========================================================================
+:: 用途：清理建置輸出目錄並重新建置方案，供本機開發快速重建使用。
+:: 更新時間：2026/07/15 14:30:00
+:: ===========================================================================
+```
+
+（改用 `REM` 亦可，但同一份檔案內擇一使用並保持一致。）
+
+## 放置規則
+
+- 標頭放在檔案最前面；若第一行是必須位於首行的宣告（例如 shebang `#!...`、`@echo off`），標頭緊接在其後。
+- yaml 檔若有 document marker（`---`），`#` 標頭放在 `---` 之前即可。
+- 外框分隔線長度不強制，但上下外框必須成對出現，且整個標頭（含外框）視為同一個註解區塊。
+- 「用途」與「更新時間」兩行的中文標籤與順序依本範本，不得只留其中一項。