From 58b9c04e527ec0ff1e2bb411cc76ce7d506db327 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 16 Jul 2026 10:45:48 +0800 Subject: [PATCH 1/2] =?UTF-8?q?feat(doc-funcs=20skill):=20=E6=8E=92?= =?UTF-8?q?=E7=89=88=E4=BE=9D=E6=AA=94=E6=A1=88=E5=8E=9F=E6=9C=AC=E6=96=B9?= =?UTF-8?q?=E5=BC=8F=E7=B6=AD=E6=8C=81=E5=8E=9F=E6=A8=A3=EF=BC=8C=E5=83=85?= =?UTF-8?q?=E4=BF=AE=E6=AD=A3=E6=9C=89=E8=AA=A4=E8=99=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- skills/doc-funcs/SKILL.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/skills/doc-funcs/SKILL.md b/skills/doc-funcs/SKILL.md index 71bf470..6d797c9 100644 --- a/skills/doc-funcs/SKILL.md +++ b/skills/doc-funcs/SKILL.md @@ -1,11 +1,11 @@ --- name: doc-funcs -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。 +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 與指令檔文件 -你要替目前工作區內的專案補齊 function 文件、指令檔註解與 workflow README。所有草稿一律由 subagent 產生，草稿全部完成後再詢問使用者如何實作，實作完成後優化被文件化原始碼的效能與排版，最後重建 README。請依下列階段依序完成。 +你要替目前工作區內的專案補齊 function 文件、指令檔註解與 workflow README。所有草稿一律由 subagent 產生，草稿全部完成後再詢問使用者如何實作，實作完成後保守優化被文件化原始碼的效能（排版依原本方式維持原樣，僅修正有誤處），最後重建 README。請依下列階段依序完成。 ## 第 0 步：先判斷語言與生態 @@ -108,13 +108,13 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（ - 例外：指令檔開頭「用途／更新日期」的檔案說明標頭（含其外框分隔線）屬於檔案標頭、不是階段區塊，必須原樣保留，不可被移除或轉成 `階段` 前綴。 - 一行一則訊息：每一則輸出訊息（原始碼或指令檔皆適用）都必須是獨立的單行輸出指令，一則訊息對應一行；不得用任何區塊（例如多行字串、字串拼接累積成一坨、迴圈外層包住整段訊息的結構）把多則訊息包成一個輸出。原本被包成一坨輸出的多則訊息，必須拆成逐行、逐則的輸出，且每則仍套用上述統一訊息格式。 -## 第 7 步：實作註解後，優化被文件化原始碼的效能與排版 +## 第 7 步：實作註解後，保守優化效能並僅修正有誤的排版 -完成註解實作後，對「本次被文件化的原始碼」做保守的效能與排版優化： +完成註解實作後，對「本次被文件化的原始碼」做保守的效能優化；排版**依照原本的排版方式維持原樣**，僅修正確實有誤之處： - 效能：在不改變對外行為與輸出的前提下，優化明顯可改善處（例如不必要的重複計算、可提前 return、低效集合操作）。任何不確定是否等價的改動一律不做，並以註解或回報標註建議人工評估。 -- 排版：套用該語言/專案既有的格式化慣例（縮排、空白、括號風格、import/using 排序），不引入與專案風格衝突的格式。 -- 每次優化後必須執行可用的格式化/建置/測試驗證行為未被破壞；若無法執行，明確說明原因並標註風險。優化僅限本次被文件化的檔案，不擴及無關檔案。 +- 排版：**預設維持檔案原本的排版方式，不重排**。只有排版確實有誤時才修正，例如：縮排錯亂或與同檔明顯不一致、tab／空白混用造成語法或建置錯誤、括號／區塊對齊錯誤造成誤讀、編碼或行尾字元異常。修正僅限有誤之處並比照該檔既有慣例；不得順手重排其他正確區塊、不得對全檔套用 formatter、不得引入新的排版風格（含 import/using 重新排序）。 +- 每次優化後必須執行可用的建置/測試（或至少語法檢查）驗證行為未被破壞；不得以套用全檔 formatter 作為驗證方式。若無法執行，明確說明原因並標註風險。優化僅限本次被文件化的檔案，不擴及無關檔案。 ## 第 8 步：重建 README @@ -167,6 +167,7 @@ README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.do - 不要新增與文件無關的 helper、測試或重構。 - 草稿是實作依據，不能跳過；所有草稿一律由 subagent 產生。 - function 註解步驟不得為了文件改變 runtime 行為；效能優化僅限第 7 步、僅限本次被文件化原始碼，且必須保持對外行為等價並驗證。 +- 排版一律依照檔案原本的排版方式；只有排版確實有誤（縮排錯亂、tab／空白混用致錯、對齊錯誤造成誤讀、編碼／行尾異常）才修正該處，不得全檔重排、不得套用 formatter 改變原有風格。 - 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯；唯一例外是第 6 步的輸出訊息格式正規化（可移除區塊橫幅、把區塊名稱併入每行前綴、統一訊息格式），但不得改變訊息反映的實際行為，且開頭用途/更新日期標頭必須保留。指令檔開頭的用途與更新日期必須包在同一個註解區塊內，且格式依本 skill 的 `templates/command-header.md` 範本。 - function 或指令檔若有輸出訊息，訊息格式必須統一為 `[{階段}?][{等級:INF/WRN/ERR/TRC/DBG}][{時間}]: {訊息}`（`階段` 選填、沿用所屬區塊原始名稱並保留原文不翻譯、`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`、`時間` 用 Asia/Taipei 時區），且不得藉此改變訊息反映的實際行為。若該 log 被包在有名稱的區塊內（含指令檔以分隔線＋標題＋分隔線宣告的橫幅段落），須將區塊名稱當作 `階段` 名稱後移除該包裹／橫幅，且僅移除包裹、保留區塊內原有指令與行為；但開頭用途/更新日期標頭不算階段區塊，必須保留。每則訊息必須一行一則、各自為獨立的單行輸出指令，不得用區塊或字串拼接把多則訊息包成一坨輸出。 - 若 function 或指令行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。 -- 2.53.0 From eb0e84981a6da2f95a30affe1554f6b6726f6d87 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Thu, 16 Jul 2026 10:45:48 +0800 Subject: [PATCH 2/2] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20bump?= =?UTF-8?q?=20=E8=87=B3=200.1.9?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 5b66832..eb72d72 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc", - "version": "0.1.8", + "version": "0.1.9", "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 a75890f..6eae2df 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc", - "version": "0.1.8", + "version": "0.1.9", "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/plugin.json b/plugin.json index 8fdf597..a41c95f 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc", - "version": "0.1.8", + "version": "0.1.9", "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/" } -- 2.53.0