From b7f329798a3a725222e3a1ff9a3b211dcedcb97f Mon Sep 17 00:00:00 2001 From: Jeffery Date: Sat, 11 Jul 2026 09:42:16 +0000 Subject: [PATCH] =?UTF-8?q?docs(doc-funcs):=20=E6=93=B4=E5=85=85=20workflo?= =?UTF-8?q?w=20=E8=88=87=E6=B5=81=E7=A8=8B=E8=AA=AA=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 2 +- skills/doc-funcs/SKILL.md | 22 +++++++++++++++++----- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 054a2b9..48e9325 100644 --- a/README.md +++ b/README.md @@ -177,7 +177,7 @@ rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs ### `doc-funcs` -掃描目前專案所有可文件化的 function/method，建立 `.docs/doc-funcs-index.md` 與逐 function 草稿，再依草稿補齊 XML documentation comments，最後重建 README 專案列表、功能列表與使用範例；README 更新時間固定使用台灣時區（Asia/Taipei）與 `yyyy/MM/dd HH:mm:ss` 格式，專案列表會拆成「專案名稱／專案描述」、「專案名稱／參考專案列表」、「專案名稱／NuGet 套件列表」三張表，且專案名稱會連到 Gitea/GitHub 遠端上的專案資料夾；遇到跨專案或跨命名空間的同名型別時會在功能名稱補上模組/專案前綴，並會跳脫 Markdown 表格、link text、heading 中的 C# 泛型角括號，檢查功能列表連結與使用範例 anchor 一致後執行合適驗證。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、建立 .docs 草稿，或提到 doc-funcs、function 文件化、XML documentation comments 時使用此 skill。 +掃描目前專案所有可文件化的 function/method，建立 `.docs/doc-funcs-index.md` 與逐 function 草稿，再依草稿補齊 XML documentation comments；同時整理 `.gitea/workflows/readme.md` 的 workflow 說明、觸發條件與相關參數草稿，最後重建 README 專案列表、功能列表與使用範例。README 更新時間固定使用台灣時區（Asia/Taipei）與 `yyyy/MM/dd HH:mm:ss` 格式，專案列表會拆成「專案名稱／專案描述」、「專案名稱／參考專案列表」、「專案名稱／NuGet 套件列表」三張表，且專案名稱會連到 Gitea/GitHub 遠端上的專案資料夾；遇到跨專案或跨命名空間的同名型別時會在功能名稱補上模組/專案前綴，並會跳脫 Markdown 表格、link text、heading 中的 C# 泛型角括號，檢查功能列表連結與使用範例 anchor 一致後執行合適驗證。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、整理 workflow README、建立 .docs 草稿，或提到 doc-funcs、function 文件化、workflow 文件化、XML documentation comments 時使用此 skill。 - **Claude Code / Antigravity**：`/jsc:doc-funcs` - **Codex**：`$doc-funcs`，或用 `/skills` 選單 diff --git a/skills/doc-funcs/SKILL.md b/skills/doc-funcs/SKILL.md index 4156794..239d4c6 100644 --- a/skills/doc-funcs/SKILL.md +++ b/skills/doc-funcs/SKILL.md @@ -1,11 +1,11 @@ --- name: doc-funcs -description: 先判斷專案語言，再為每個 function 與每個指令檔（腳本／CI／部署設定檔）建立 .docs/ 草稿並補齊註解，由使用者選擇實作方式後寫回原始碼／覆蓋指令檔，接著保守優化被文件化原始碼的效能與排版，最後重建 README 專案列表、功能列表與使用範例。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、為腳本或 CI/部署設定檔逐行加註解、建立 .docs 草稿，或提到 doc-funcs、function 文件化、指令檔註解、XML documentation comments 時使用此 skill。 +description: 先判斷專案語言，再為每個 function 與每個指令檔（腳本／CI／部署設定檔）建立 .docs/ 草稿並補齊註解，並整理 `.gitea/workflows/readme.md` 的 workflow 說明、觸發條件與相關參數草稿；由使用者選擇實作方式後寫回原始碼／覆蓋指令檔／更新 workflow readme，接著保守優化被文件化原始碼的效能與排版，最後重建 README 專案列表、功能列表與使用範例。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、為腳本或 CI/部署設定檔逐行加註解、整理 workflow README、建立 .docs 草稿，或提到 doc-funcs、function 文件化、指令檔註解、workflow 文件化、XML documentation comments 時使用此 skill。 --- # 補齊 function 與指令檔文件 -你要替目前工作區內的專案補齊 function 文件與指令檔註解。所有草稿一律由 subagent 產生，草稿全部完成後再詢問使用者如何實作，實作完成後優化被文件化原始碼的效能與排版，最後重建 README。請依下列階段依序完成。 +你要替目前工作區內的專案補齊 function 文件、指令檔註解與 workflow README。所有草稿一律由 subagent 產生，草稿全部完成後再詢問使用者如何實作，實作完成後優化被文件化原始碼的效能與排版，最後重建 README。請依下列階段依序完成。 ## 第 0 步：先判斷語言與生態 @@ -27,12 +27,13 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（ ## 第 2 步：建立 .docs/ 與索引 -建立 .docs/ 目錄（若不存在）。產生總索引 `.docs/doc-funcs-index.md`，分兩段列出： +建立 .docs/ 目錄（若不存在）。產生總索引 `.docs/doc-funcs-index.md`，分三段列出： - function 段：專案名稱、檔案、型別、可見性、簽名、是否已有文件、草稿檔路徑。 - 指令檔段：檔案路徑、檔案類型（腳本／CI／部署設定檔）、註解符號、草稿檔路徑。 +- workflow 段：`.gitea/workflows/` 底下所有 workflow 檔案與 `.gitea/workflows/readme.md`，列出 workflow 名稱、觸發條件、相關參數、草稿檔路徑。 -## 第 3 步：派 Sub Agent 產生草稿（兩類，全部由 subagent 產生） +## 第 3 步：派 Sub Agent 產生草稿（三類，全部由 subagent 產生） 針對每一個 function 與每一個指令檔各派一個 subagent。subagent 只分析指定目標與必要上下文，**不直接改原始碼或原始指令檔**，只在 .docs/ 底下建立草稿。 @@ -58,12 +59,22 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（ - 必須保留原始指令的實際行為與順序，只新增註解與開頭用途/日期區塊，不得變更指令邏輯；若發現原指令可能有問題，於草稿中以註解標註「需人工確認」，不要逕自修改。 - 唯一例外是第 6 步定義的「輸出訊息格式／區塊階段命名／一行一則」正規化：可移除印出區塊橫幅的輸出指令、把區塊名稱併入該段每行訊息前綴、並統一訊息格式。此類調整只動「訊息呈現方式」，不得改變訊息反映的實際行為或判斷邏輯，且開頭用途/更新日期標頭必須保留。草稿即應呈現正規化後的最終樣貌。 +### 3-3 workflow README 草稿 + +對 `.gitea/workflows/` 底下所有 workflow 檔案與 `.gitea/workflows/readme.md`，subagent 要先彙整每個 workflow 的用途、觸發條件與相關參數，再產生可直接覆蓋的草稿。草稿檔放在 `.docs/doc-funcs/workflows/readme.md`，內容規則： + +- 以繁體中文為主、英文為輔，先列出 workflow 總覽，再依 workflow 檔案逐一整理。 +- 每個 workflow 至少包含：workflow 名稱、檔案位置、用途說明、觸發條件、主要輸入/環境參數、重要注意事項。 +- 若 workflow 內容有不確定或推論成分，需明確標註「需人工確認」。 +- 草稿內容不得變更任何 workflow 實際設定，只作為整理後的 README 草稿。 + ## 第 4 步：草稿品質檢查 在實作到原始碼之前，主 agent 必須檢查所有草稿： - 內容以繁體中文為主、英文為輔，且沒有任何亂碼、編碼錯誤、不可讀字元或明顯破損文字。 - 指令檔草稿的指令本體與原檔一致、註解符號正確、開頭含用途與更新日期、每行皆有註解。 +- workflow README 草稿需完整涵蓋 `.gitea/workflows/` 底下所有 workflow 檔案，且每個 workflow 都要有用途、觸發條件與相關參數說明。 - 若發現問題，先修正草稿並重新檢查，通過後才能進入下一步。 ## 第 5 步：詢問使用者要如何實作 @@ -82,6 +93,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（ - function 草稿：依第 0 步判斷的語言把建議文件寫入原始碼（C# 用 XML documentation comments）。註解盡量使用繁體中文；保留既有正確文件，僅補齊缺漏或明顯不足處；此步驟不得為了文件改變 runtime 行為。 - 指令檔草稿：用草稿內容**覆蓋原始指令檔**（草稿已是含用途/日期/逐行註解的完整版本）。 +- workflow README 草稿：用草稿內容**覆蓋 `.gitea/workflows/readme.md`**，保留 workflow 實際設定不變，僅整理成說明文件。 - 若選「逐個草稿實作」，每完成一個就回報並等待使用者確認。 - 若遇到大量目標，仍要分批持續處理，不要只做示範。若 token 或時間不足，先完成已列入 index 的批次，並在 `.docs/doc-funcs-index.md` 標記 pending。 - 輸出訊息格式：若該 function 或指令檔有輸出訊息（例如 log、console 輸出、echo、回傳給使用者的提示訊息），訊息格式必須統一為 `[{階段}?][{等級:INF/WRN/ERR/TRC/DBG}][{時間}]: {訊息}`。其中 `階段` 為選填（沿用該訊息所屬區塊的原始名稱、保留原文不翻譯，例如中文區塊名就用中文；無對應階段時省略整個 `[{階段}]` 區塊）；`等級` 必須是 `INF`/`WRN`/`ERR`/`TRC`/`DBG` 其中之一；`時間` 使用台灣時區（Asia/Taipei）。調整輸出訊息格式僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。 @@ -137,7 +149,7 @@ README 重建完成後，必須自動檢查 README 內部錨點一致性；檢 ## 第 10 步：清理草稿 -README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.docs/doc-funcs/`（含 `commands/` 指令檔草稿）與 `.docs/doc-funcs-index.md`。若 `.docs/` 內已無其他內容，可一併移除空的 `.docs/` 目錄；不得刪除使用者既有的 `.docs/` 其他檔案。 +README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.docs/doc-funcs/`（含 `commands/` 指令檔草稿與 `workflows/` workflow 草稿）與 `.docs/doc-funcs-index.md`。若 `.docs/` 內已無其他內容，可一併移除空的 `.docs/` 目錄；不得刪除使用者既有的 `.docs/` 其他檔案。 ## 第 11 步：格式化/建置驗證