refactor(doc): 接上 shared 共用規範，去除重抄段落並修正時區/機密遮蔽引用
依 todo.md 執行的規範治理專案：worklog／funcs／issues-analyze／ issues-analyze-to-file／issues-sync／notifications／docker 七個 skill 改為 引用 shared 新增的 14 個共用 spec（token 優先序、issue 讀取、TODO list、 ask-user、subagent、no-scratch-files、skill-invocation、script-path 等）， 不再重抄內容；wiki_api.py 改用 zoneinfo 而非硬編 +8 offset，並補上與 shared/scripts/lib/redact-patterns.json 的對應註記；worklog 的 --tune 改為 呼叫 /jsc-shared:models --task summary。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 5
+12
-14
@@ -7,13 +7,11 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
|
||||
|
||||
你要替目前工作區內的專案補齊 function 文件、指令檔註解與 workflow README。所有草稿一律由 subagent 產生，草稿全部完成後再詢問使用者如何實作，實作完成後保守優化被文件化原始碼的效能（排版依原本方式維持原樣，僅修正有誤處），最後重建 README。請依下列階段依序完成。
|
||||
|
||||
## 共用規範（shared plugin，必要前置）
|
||||
## 共用規範（必要前置）
|
||||
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc-shared:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、subagent 提示需帶入本規範。
|
||||
- `/jsc-shared:spec-execution`：不臆測／需人工確認、不擴及無關檔案（generated/bin/obj/.git/.docs 與第三方依賴）。
|
||||
- `/jsc-shared:spec-time-log`：更新時間 Asia/Taipei `yyyy/MM/dd HH:mm:ss`、輸出訊息格式 `[時間][階段][等級]: 訊息`、一行一則。
|
||||
先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝，
|
||||
依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。
|
||||
本 skill 需要的規範：`spec-output`、`spec-execution`、`spec-subagent`、`spec-time-log`、`spec-ask-user`、`spec-git-safety`
|
||||
|
||||
## 第 0 步：先判斷語言與生態
|
||||
|
||||
@@ -47,7 +45,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
|
||||
|
||||
## 第 3 步：派 Sub Agent 產生草稿（三類，全部由 subagent 產生）
|
||||
|
||||
針對每一個 function 與每一個指令檔各派一個 subagent。subagent 只分析指定目標與必要上下文，**不直接改原始碼或原始指令檔**，只在 .docs/ 底下建立草稿。
|
||||
依 `/jsc-shared:spec-subagent` 派工：針對每一個 function 與每一個指令檔各派一個 subagent，一個明確目標對應一個 subagent。本 skill 明確授權的例外寫入範圍僅限在 `.docs/` 底下建立草稿；subagent 只分析指定目標與必要上下文，不直接改原始碼或原始指令檔，其餘讀寫與回傳規則依該 spec。
|
||||
|
||||
### 3-1 function 註解草稿
|
||||
|
||||
@@ -65,7 +63,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'` 取得）。標頭格式必須依本 skill 的範本 `templates/command-header.md` 產生：依檔案類型選用 `#` 或 `::`/`REM` 變體，並遵守範本的佔位符與放置規則（shebang/`@echo off` 之後、外框成對）。派 subagent 產生指令檔草稿時，必須把該範本內容一併提供給 subagent。
|
||||
- 檔案開頭必須有一段註解區塊，且「該份指令檔的用途」與「更新日期」必須包在同一個區塊內，不得拆成兩個分開的註解區塊。更新日期格式依 `/jsc-shared:spec-time-log`。標頭格式必須依本 skill 的範本 `templates/command-header.md` 產生：依檔案類型選用 `#` 或 `::`/`REM` 變體，並遵守範本的佔位符與放置規則（shebang/`@echo off` 之後、外框成對）。派 subagent 產生指令檔草稿時，必須把該範本內容一併提供給 subagent。
|
||||
- 原指令檔的每一行有效指令之間必須換行，且每行都要有對應的註解說明，解釋這行在做什麼、為何需要、重要參數或副作用。
|
||||
- 註解符號必須符合該檔案類型：`*.sh`/`*.bash`/`*.ps1`/Makefile/yaml/Dockerfile 用 `#`；`*.bat`/`*.cmd` 用 `REM` 或 `::`。若該行語法不允許行尾註解（例如某些 yaml 值），改用該行上方獨立一行註解。
|
||||
- 必須保留原始指令的實際行為與順序，只新增註解與開頭用途/日期區塊，不得變更指令邏輯；若發現原指令可能有問題，於草稿中以註解標註「需人工確認」，不要逕自修改。
|
||||
@@ -91,7 +89,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
|
||||
|
||||
## 第 5 步：詢問使用者要如何實作
|
||||
|
||||
所有草稿完成且通過檢查後，主 agent 必須詢問使用者要如何實作（使用 AskUserQuestion），提供以下選項：
|
||||
所有草稿完成且通過檢查後，主 agent 必須依 `/jsc-shared:spec-ask-user` 詢問使用者要如何實作（單選，已含「其他」選項），提供以下選項：
|
||||
|
||||
1. 全部一起實作。
|
||||
2. 逐個草稿實作（每實作完一個草稿就回報，並讓使用者確認後再做下一個）。
|
||||
@@ -105,11 +103,11 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
|
||||
|
||||
- function 草稿：依第 0 步判斷的語言把建議文件寫入原始碼（C# 用 XML documentation comments）。註解盡量使用繁體中文；保留既有正確文件，僅補齊缺漏或明顯不足處；此步驟不得為了文件改變 runtime 行為。
|
||||
- 指令檔草稿：用草稿內容**覆蓋原始指令檔**（草稿已是含用途/日期/逐行註解的完整版本）。
|
||||
- Dockerfile 檔名正規化：覆蓋 Dockerfile 類指令檔時，若實際檔名大小寫與第 0 步判斷的專案多數命名慣例不符（例如專案多數為全小寫但檔名為 `Dockerfile`，或反之），用 `git mv` 把檔名調整為慣例風格；在大小寫不敏感的檔案系統上需兩段式改名（先 `git mv Dockerfile Dockerfile.tmp` 再 `git mv Dockerfile.tmp dockerfile`）。改名後必須同步更新專案內引用該檔名的位置（例如 docker-compose 的 `dockerfile:`、CI workflow 的 build 參數、文件內連結），確保建置行為不變；此檔名與引用調整不視為變更指令邏輯。第 0 步判斷為「無明顯多數」時保留原檔名，不做改名。
|
||||
- Dockerfile 檔名正規化：覆蓋 Dockerfile 類指令檔時，若實際檔名大小寫與第 0 步判斷的專案多數命名慣例不符（例如專案多數為全小寫但檔名為 `Dockerfile`，或反之），改名方式依 `/jsc-shared:spec-git-safety`（`git mv` 保留歷史、大小寫不敏感檔案系統的兩段式改名）。改名後必須同步更新專案內引用該檔名的位置（例如 docker-compose 的 `dockerfile:`、CI workflow 的 build 參數、文件內連結），確保建置行為不變；此檔名與引用調整不視為變更指令邏輯。第 0 步判斷為「無明顯多數」時保留原檔名，不做改名。
|
||||
- workflow README 草稿：用草稿內容**覆蓋 `.gitea/workflows/readme.md`**，保留 workflow 實際設定不變，僅整理成說明文件。
|
||||
- 若選「逐個草稿實作」，每完成一個就回報並等待使用者確認。
|
||||
- 若遇到大量目標，仍要分批持續處理，不要只做示範。若 token 或時間不足，先完成已列入 index 的批次，並在 `.docs/doc-funcs-index.md` 標記 pending。
|
||||
- 輸出訊息格式：依 `/jsc-shared:spec-time-log` — 若該 function 或指令檔有輸出訊息，統一為 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息`（`階段` 選填、沿用所屬區塊原始名稱不翻譯；`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`；時間 Asia/Taipei）；區塊階段命名（`#region`／橫幅段落名稱作為 `階段` 前綴並移除包裹／橫幅本身、僅移除標記保留指令與行為）、檔案標頭保留例外、一行一則規則皆依該 spec。調整僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。
|
||||
- 輸出訊息格式：若該 function 或指令檔有輸出訊息，訊息格式、區塊階段命名、檔案標頭保留例外與一行一則規則一律依 `/jsc-shared:spec-time-log`。調整範圍僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。
|
||||
|
||||
## 第 7 步：實作註解後，保守優化效能並僅修正有誤的排版
|
||||
|
||||
@@ -121,7 +119,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
|
||||
|
||||
## 第 8 步：重建 README
|
||||
|
||||
補齊後，重建專案根目錄的 README。README 檔名依第 0 步判斷的專案多數命名慣例決定（例如多數全大寫用 `README.md`、多數全小寫用 `readme.md`）；第 0 步判斷為「無明顯多數」或無法判斷時，沿用既有 README 檔名，完全沒有既有 README 時預設 `README.md`。若根目錄已有 README（不論大小寫），先刪除既有檔案，再以慣例檔名產生新的 README；不要保留或合併舊內容，也不得同時留下兩種大小寫的 README。若檔名大小寫因此改變，需同步更新專案內引用舊 README 檔名的位置（例如文件連結、CI、套件描述檔）。README 必須包含更新時間，更新時間必須使用台灣時區（Asia/Taipei）並固定輸出為 `yyyy/MM/dd HH:mm:ss` 格式，例如 `2026/06/22 18:30:05`；README 必須在功能列表前加入專案列表，並只列出所有專案內的公開方法（public method、public constructor、public extension method、public operator），但不得列出單元測試方法；若方法位於測試專案、測試檔案、測試型別，或帶有測試框架屬性/命名（例如 `Test`、`Fact`、`Theory`、`TestMethod`、`TestCase`、`SetUp`、`TearDown`、`Initialize`、`Cleanup`），即使是 public 也要排除。產生 README 前，必須先為每個公開方法決定「最終功能名稱」：
|
||||
補齊後，重建專案根目錄的 README。README 檔名依第 0 步判斷的專案多數命名慣例決定（例如多數全大寫用 `README.md`、多數全小寫用 `readme.md`）；第 0 步判斷為「無明顯多數」或無法判斷時，沿用既有 README 檔名，完全沒有既有 README 時預設 `README.md`。若根目錄已有 README（不論大小寫），先刪除既有檔案，再以慣例檔名產生新的 README；不要保留或合併舊內容，也不得同時留下兩種大小寫的 README。若檔名大小寫因此改變，需同步更新專案內引用舊 README 檔名的位置（例如文件連結、CI、套件描述檔）。README 必須包含更新時間，格式依 `/jsc-shared:spec-time-log`；README 必須在功能列表前加入專案列表，並只列出所有專案內的公開方法（public method、public constructor、public extension method、public operator），但不得列出單元測試方法；若方法位於測試專案、測試檔案、測試型別，或帶有測試框架屬性/命名（例如 `Test`、`Fact`、`Theory`、`TestMethod`、`TestCase`、`SetUp`、`TearDown`、`Initialize`、`Cleanup`），即使是 public 也要排除。產生 README 前，必須先為每個公開方法決定「最終功能名稱」：
|
||||
|
||||
- 預設功能名稱為 `Type.Method`。
|
||||
- 若公開方法所在的型別簡名在不同專案或不同命名空間中重複，最終功能名稱不得只使用 `Type.Method`，必須在型別前加入可辨識的專案或模組前綴，格式為 `Module.Type.Method`。例如 `Hangfire.ServiceCollectionExtension.AddHangfireOptions`、`Hangfire.SqlServer.ServiceCollectionExtension.AddSqlServerHangfire`、`Swagger.ServiceCollectionExtension.AddSwagger`、`Swagger.ApplicationBuilderExtension.UseSwaggerUI`。
|
||||
@@ -171,7 +169,7 @@ README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.do
|
||||
- 草稿是實作依據，不能跳過；所有草稿一律由 subagent 產生。
|
||||
- function 註解步驟不得為了文件改變 runtime 行為；效能優化僅限第 7 步、僅限本次被文件化原始碼，且必須保持對外行為等價並驗證。
|
||||
- 排版一律依照檔案原本的排版方式；只有排版確實有誤（縮排錯亂、tab／空白混用致錯、對齊錯誤造成誤讀、編碼／行尾異常）才修正該處，不得全檔重排、不得套用 formatter 改變原有風格。
|
||||
- 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯；唯一例外是第 6 步的輸出訊息格式正規化（可移除區塊橫幅、把區塊名稱併入每行前綴、統一訊息格式），但不得改變訊息反映的實際行為，且開頭用途/更新日期標頭必須保留。指令檔開頭的用途與更新日期必須包在同一個註解區塊內，且格式依本 skill 的 `templates/command-header.md` 範本。
|
||||
- function 或指令檔若有輸出訊息，訊息格式、區塊階段命名、檔案標頭保留與一行一則規則一律依 `/jsc-shared:spec-time-log`，且不得藉此改變訊息反映的實際行為。
|
||||
- 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯；唯一例外是輸出訊息格式正規化（同上，見前置區塊 spec-time-log），且開頭用途/更新日期標頭必須保留，格式依本 skill 的 `templates/command-header.md` 範本。指令檔開頭的用途與更新日期必須包在同一個註解區塊內。
|
||||
- function 或指令檔若有輸出訊息，其格式規則同上（見前置區塊 spec-time-log），且不得藉此改變訊息反映的實際行為。
|
||||
- 若 function 或指令行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。
|
||||
- 原始碼註解與 README 的語言依 `/jsc-shared:spec-output`（繁體中文為主；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文）。
|
||||
|
||||
Reference in New Issue
Block a user