Merge pull request '同步 doc-funcs 與 doc-issues skills 更新' (#34) from develop into master
Reviewed-on: #34 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
This commit was merged in pull request #34.
This commit is contained in:
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.1.9",
|
||||
"version": "0.2.0",
|
||||
"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": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.1.9",
|
||||
"version": "0.2.0",
|
||||
"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"
|
||||
}
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.1.9",
|
||||
"version": "0.2.0",
|
||||
"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/"
|
||||
}
|
||||
|
||||
@@ -101,11 +101,11 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
|
||||
- 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）。調整輸出訊息格式僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。
|
||||
- 輸出訊息格式：若該 function 或指令檔有輸出訊息（例如 log、console 輸出、echo、回傳給使用者的提示訊息），訊息格式必須統一為 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息`。其中 `階段` 為選填，沿用該訊息所屬區塊的原始名稱並保留原文不翻譯；若無對應階段則移除整個 `[階段]` 區塊。`等級` 必須是 `INF`/`WRN`/`ERR`/`TRC`/`DBG` 其中之一；`時間` 使用台灣時區（Asia/Taipei）並固定為 `yyyy/MM/dd HH:mm:ss`。調整輸出訊息格式僅限本次被文件化的原始碼或被覆蓋的指令檔，且不得改變訊息所反映的實際行為或判斷邏輯。
|
||||
- 區塊內 log 的階段命名：若被調整格式的 log 被包在某個有名稱的區塊內，必須將該區塊名稱作為該 log 的 `階段` 名稱（沿用原始名稱、保留原文不翻譯），套用完成後移除標示該區塊的包裹／標題本身（僅移除標記與包裹，保留區塊內原有的指令與行為）。有名稱的區塊包含但不限於：
|
||||
- 原始碼：`#region 名稱`/`#endregion`、或其他帶名稱的包裹結構。
|
||||
- 指令檔：以「印出分隔線＋區塊標題＋分隔線」這種橫幅（banner）方式宣告的段落（例如先 echo `====`、再 echo 區塊名稱、再 echo `----`）。此時橫幅顯示的標題即為該段所有 log 的 `階段` 名稱，且必須移除這幾行印出橫幅的輸出指令，改成把 `階段` 名稱併進該段每一行訊息的前綴。
|
||||
- 例外：指令檔開頭「用途／更新日期」的檔案說明標頭（含其外框分隔線）屬於檔案標頭、不是階段區塊，必須原樣保留，不可被移除或轉成 `階段` 前綴。
|
||||
- 例外：指令檔開頭「用途／更新日期」的檔案說明標頭（含其外框分隔線）屬於檔案標頭、不是階段區塊，必須原樣保留，不可被移除或轉成 `階段` 前綴。
|
||||
- 一行一則訊息：每一則輸出訊息（原始碼或指令檔皆適用）都必須是獨立的單行輸出指令，一則訊息對應一行；不得用任何區塊（例如多行字串、字串拼接累積成一坨、迴圈外層包住整段訊息的結構）把多則訊息包成一個輸出。原本被包成一坨輸出的多則訊息，必須拆成逐行、逐則的輸出，且每則仍套用上述統一訊息格式。
|
||||
|
||||
## 第 7 步：實作註解後，保守優化效能並僅修正有誤的排版
|
||||
@@ -169,6 +169,6 @@ README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.do
|
||||
- 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 或指令檔若有輸出訊息，訊息格式必須統一為 `[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息`（`階段` 選填、沿用所屬區塊原始名稱並保留原文不翻譯；無對應階段時移除該區塊；`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`；`時間` 用 Asia/Taipei 時區），且不得藉此改變訊息反映的實際行為。若該 log 被包在有名稱的區塊內（含指令檔以分隔線＋標題＋分隔線宣告的橫幅段落），須將區塊名稱當作 `階段` 名稱後移除該包裹／橫幅，且僅移除包裹、保留區塊內原有指令與行為；但開頭用途/更新日期標頭不算階段區塊，必須保留。每則訊息必須一行一則、各自為獨立的單行輸出指令，不得用區塊或字串拼接把多則訊息包成一坨輸出。
|
||||
- 若 function 或指令行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。
|
||||
- 原始碼註解與 README 盡量使用繁體中文；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文。
|
||||
|
||||
Reference in New Issue
Block a user