diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index f20939d..fc835a9 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc", - "version": "0.1.5", + "version": "0.1.6", "description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode）：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；doc-issues-analyze 會把專案／議題／文件來源拆成小功能議題並依到期日實作；doc-issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度與標籤並產生進度留言。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 4f7df27..89ab585 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc", - "version": "0.1.5", + "version": "0.1.6", "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；doc-issues-analyze 會把專案／議題／文件來源拆成小功能議題並依到期日實作；doc-issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度與標籤並產生進度留言。所有 skills 以 SKILL.md 為共通標準。", "skills": "./skills" } diff --git a/README.md b/README.md index b667fcb..e42df29 100644 --- a/README.md +++ b/README.md @@ -180,7 +180,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；指令檔（腳本／CI／部署設定檔）草稿開頭的「用途／更新時間」標頭固定依 `skills/doc-funcs/templates/command-header.md` 範本產生（依檔案類型選 `#` 或 `::`/`REM` 變體）；同時整理 `.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。 +掃描目前專案所有可文件化的 function/method，建立 `.docs/doc-funcs-index.md` 與逐 function 草稿，再依草稿補齊 XML documentation comments；指令檔（腳本／CI／部署設定檔）草稿開頭的「用途／更新時間」標頭固定依 `skills/doc-funcs/templates/command-header.md` 範本產生（依檔案類型選 `#` 或 `::`/`REM` 變體）；`Dockerfile` 與 README 的檔名會依專案內多數檔案的大小寫命名慣例正規化（無明顯多數則保留原檔名），改名時同步更新引用；同時整理 `.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/plugin.json b/plugin.json index 2af9525..5b075aa 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc", - "version": "0.1.5", + "version": "0.1.6", "description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；doc-issues-analyze 會把專案／議題／文件來源拆成小功能議題並依到期日實作；doc-issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度與標籤並產生進度留言。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。", "skills": "./skills/" } diff --git a/skills/doc-funcs/SKILL.md b/skills/doc-funcs/SKILL.md index 23cc02f..71bf470 100644 --- a/skills/doc-funcs/SKILL.md +++ b/skills/doc-funcs/SKILL.md @@ -1,6 +1,6 @@ --- name: doc-funcs -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。 +description: 先判斷專案語言，再為每個 function 與每個指令檔（腳本／CI／部署設定檔）建立 .docs/ 草稿並補齊註解，並整理 `.gitea/workflows/readme.md` 的 workflow 說明、觸發條件與相關參數草稿；由使用者選擇實作方式後寫回原始碼／覆蓋指令檔／更新 workflow readme，並依專案內多數檔案的大小寫命名慣例正規化 Dockerfile 與 README 檔名（含同步更新引用），接著保守優化被文件化原始碼的效能與排版，最後重建 README 專案列表、功能列表與使用範例。當使用者要補齊 function 文件、產生 XML doc、為每個 method 加 summary/param/remarks、為腳本或 CI/部署設定檔逐行加註解、整理 workflow README、建立 .docs 草稿，或提到 doc-funcs、function 文件化、指令檔註解、workflow 文件化、XML documentation comments 時使用此 skill。 --- # 補齊 function 與指令檔文件 @@ -13,7 +13,11 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（ - 檢查專案檔與設定檔（例如 `*.csproj`/`*.sln`、`package.json`、`pyproject.toml`/`requirements.txt`、`go.mod`、`pom.xml`/`build.gradle`、`Cargo.toml` 等）、主要副檔名分布與 README，推斷主要語言。 - 依語言決定 function 註解格式：C# 用 XML documentation comments（``/``/``）；其他語言改用該語言慣用的文件註解格式（例如 JS/TS 用 JSDoc、Python 用 docstring、Go 用 doc comment、Java 用 Javadoc）。 -- 在 `.docs/doc-funcs-index.md` 開頭記錄判斷出的主要語言與將採用的註解格式，作為後續所有 subagent 的依據。 +- 統計專案檔名的大小寫慣例，作為後續 `Dockerfile` 與 README 檔名正規化（第 6 步、第 8 步）的依據： + - 樣本範圍排除 generated/bin/obj/.git/.docs 與第三方依賴；把檔名歸類為「全大寫」（如 `README.md`、`CHANGELOG.md`）、「首字大寫」（如 `Dockerfile`、`Makefile`）、「全小寫」（如 `readme.md`、`dockerfile`）等風格。 + - 優先以同類型檔案為樣本（README 看其他 `*.md` 文件檔、Dockerfile 看其他容器/建置相關檔）；同類型樣本不足 3 個時，改看全專案檔名分布。 + - 只有某一風格明顯過半才視為「專案多數慣例」；無明顯多數時不做檔名正規化，保留原檔名。 +- 在 `.docs/doc-funcs-index.md` 開頭記錄判斷出的主要語言、將採用的註解格式，以及檔名命名慣例的判斷結果（多數風格或「無明顯多數」）。 ## 第 1 步：掃描 function 與指令檔 @@ -93,6 +97,7 @@ 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 步判斷為「無明顯多數」時保留原檔名，不做改名。 - workflow README 草稿：用草稿內容**覆蓋 `.gitea/workflows/readme.md`**，保留 workflow 實際設定不變，僅整理成說明文件。 - 若選「逐個草稿實作」，每完成一個就回報並等待使用者確認。 - 若遇到大量目標，仍要分批持續處理，不要只做示範。若 token 或時間不足，先完成已列入 index 的批次，並在 `.docs/doc-funcs-index.md` 標記 pending。 @@ -113,7 +118,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（ ## 第 8 步：重建 README -補齊後，重建專案根目錄的 README.md。若根目錄已有 README.md，先刪除既有檔案，再產生新的 README.md；不要保留或合併舊內容。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 必須包含更新時間，更新時間必須使用台灣時區（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 前，必須先為每個公開方法決定「最終功能名稱」： - 預設功能名稱為 `Type.Method`。 - 若公開方法所在的型別簡名在不同專案或不同命名空間中重複，最終功能名稱不得只使用 `Type.Method`，必須在型別前加入可辨識的專案或模組前綴，格式為 `Module.Type.Method`。例如 `Hangfire.ServiceCollectionExtension.AddHangfireOptions`、`Hangfire.SqlServer.ServiceCollectionExtension.AddSqlServerHangfire`、`Swagger.ServiceCollectionExtension.AddSwagger`、`Swagger.ApplicationBuilderExtension.UseSwaggerUI`。 @@ -157,7 +162,8 @@ README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.do ## 重要限制 -- 不要修改 generated/bin/obj/.git/.docs 以外的非原始碼/非指令檔，除非是建立草稿、索引，依流程實作註解、依草稿覆蓋指令檔、優化本次被文件化原始碼，或刪除並重建根目錄 README.md。 +- 不要修改 generated/bin/obj/.git/.docs 以外的非原始碼/非指令檔，除非是建立草稿、索引，依流程實作註解、依草稿覆蓋指令檔、優化本次被文件化原始碼、刪除並重建根目錄 README，或依第 0 步判斷的專案多數命名慣例正規化 `Dockerfile` 與 README 檔名（含同步更新引用舊檔名的位置）。 +- `Dockerfile` 與 README 的檔名正規化只在專案多數慣例明確（某一風格明顯過半）時執行；無明顯多數就保留原檔名。改名時必須同步更新所有引用，不得造成建置或連結失效。 - 不要新增與文件無關的 helper、測試或重構。 - 草稿是實作依據，不能跳過；所有草稿一律由 subagent 產生。 - function 註解步驟不得為了文件改變 runtime 行為；效能優化僅限第 7 步、僅限本次被文件化原始碼，且必須保持對外行為等價並驗證。