doc-funcs 新增指令檔「用途／更新時間」標頭範本並同步文件與版本 #30
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.1.4",
|
||||
"version": "0.1.5",
|
||||
"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.4",
|
||||
"version": "0.1.5",
|
||||
"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"
|
||||
}
|
||||
|
||||
@@ -39,7 +39,9 @@ doc/
|
||||
│ ├── doc-docker/ # 對齊 docker-compose 註解（含 scripts/）
|
||||
│ │ ├── SKILL.md
|
||||
│ │ └── scripts/
|
||||
│ ├── doc-funcs/SKILL.md # 為 function 補齊 XML 文件
|
||||
│ ├── doc-funcs/ # 為 function 補齊 XML 文件、指令檔逐行註解（含 templates/）
|
||||
│ │ ├── SKILL.md
|
||||
│ │ └── templates/ # 指令檔開頭「用途／更新時間」標頭範本（command-header.md）
|
||||
│ ├── doc-issues-analyze-to-file/SKILL.md # 讀 issue → 需求文件 → 拆階段 issue → 實作草稿 → 交付留言
|
||||
│ ├── doc-issues-analyze/SKILL.md # 讀來源 → 保存議題 → 小功能議題 → 排程實作 → PR
|
||||
│ └── doc-issues-sync/SKILL.md # 讀專案／議題 → 依工作目錄勾稽 TODO → 補 TODO／更新標籤 → 進度留言
|
||||
@@ -178,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；同時整理 `.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` 變體）；同時整理 `.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` 選單
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.1.4",
|
||||
"version": "0.1.5",
|
||||
"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/"
|
||||
}
|
||||
|
||||
@@ -53,7 +53,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'` 取得）。
|
||||
- 檔案開頭必須有一段註解區塊，且「該份指令檔的用途」與「更新日期」必須包在同一個區塊內，不得拆成兩個分開的註解區塊。更新日期使用台灣時區（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。
|
||||
- 原指令檔的每一行有效指令之間必須換行，且每行都要有對應的註解說明，解釋這行在做什麼、為何需要、重要參數或副作用。
|
||||
- 註解符號必須符合該檔案類型：`*.sh`/`*.bash`/`*.ps1`/Makefile/yaml/Dockerfile 用 `#`；`*.bat`/`*.cmd` 用 `REM` 或 `::`。若該行語法不允許行尾註解（例如某些 yaml 值），改用該行上方獨立一行註解。
|
||||
- 必須保留原始指令的實際行為與順序，只新增註解與開頭用途/日期區塊，不得變更指令邏輯；若發現原指令可能有問題，於草稿中以註解標註「需人工確認」，不要逕自修改。
|
||||
@@ -73,7 +73,7 @@ description: 先判斷專案語言，再為每個 function 與每個指令檔（
|
||||
在實作到原始碼之前，主 agent 必須檢查所有草稿：
|
||||
|
||||
- 內容以繁體中文為主、英文為輔，且沒有任何亂碼、編碼錯誤、不可讀字元或明顯破損文字。
|
||||
- 指令檔草稿的指令本體與原檔一致、註解符號正確、開頭含用途與更新日期、每行皆有註解。
|
||||
- 指令檔草稿的指令本體與原檔一致、註解符號正確、每行皆有註解，且開頭標頭符合 `templates/command-header.md` 範本（用途與更新時間同一區塊、外框成對、位置正確）。
|
||||
- workflow README 草稿需完整涵蓋 `.gitea/workflows/` 底下所有 workflow 檔案，且每個 workflow 都要有用途、觸發條件與相關參數說明。
|
||||
- 若發現問題，先修正草稿並重新檢查，通過後才能進入下一步。
|
||||
|
||||
@@ -161,7 +161,7 @@ README 錨點檢查通過後，刪除本次產生的所有草稿與索引：`.do
|
||||
- 不要新增與文件無關的 helper、測試或重構。
|
||||
- 草稿是實作依據，不能跳過；所有草稿一律由 subagent 產生。
|
||||
- function 註解步驟不得為了文件改變 runtime 行為；效能優化僅限第 7 步、僅限本次被文件化原始碼，且必須保持對外行為等價並驗證。
|
||||
- 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯；唯一例外是第 6 步的輸出訊息格式正規化（可移除區塊橫幅、把區塊名稱併入每行前綴、統一訊息格式），但不得改變訊息反映的實際行為，且開頭用途/更新日期標頭必須保留。指令檔開頭的用途與更新日期必須包在同一個註解區塊內。
|
||||
- 指令檔草稿只新增註解與開頭用途/日期區塊，不得變更指令邏輯；唯一例外是第 6 步的輸出訊息格式正規化（可移除區塊橫幅、把區塊名稱併入每行前綴、統一訊息格式），但不得改變訊息反映的實際行為，且開頭用途/更新日期標頭必須保留。指令檔開頭的用途與更新日期必須包在同一個註解區塊內，且格式依本 skill 的 `templates/command-header.md` 範本。
|
||||
- function 或指令檔若有輸出訊息，訊息格式必須統一為 `[{階段}?][{等級:INF/WRN/ERR/TRC/DBG}][{時間}]: {訊息}`（`階段` 選填、沿用所屬區塊原始名稱並保留原文不翻譯、`等級` 限 `INF`/`WRN`/`ERR`/`TRC`/`DBG`、`時間` 用 Asia/Taipei 時區），且不得藉此改變訊息反映的實際行為。若該 log 被包在有名稱的區塊內（含指令檔以分隔線＋標題＋分隔線宣告的橫幅段落），須將區塊名稱當作 `階段` 名稱後移除該包裹／橫幅，且僅移除包裹、保留區塊內原有指令與行為；但開頭用途/更新日期標頭不算階段區塊，必須保留。每則訊息必須一行一則、各自為獨立的單行輸出指令，不得用區塊或字串拼接把多則訊息包成一坨輸出。
|
||||
- 若 function 或指令行為無法可靠推論，文件中要保守描述並標註不確定點，不要編造。
|
||||
- 原始碼註解與 README 盡量使用繁體中文；專有名詞、API 名稱、型別名稱與程式碼範例可保留英文。
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# 指令檔開頭「用途／更新時間」標頭範本
|
||||
|
||||
本範本定義 doc-funcs 第 3-2 步指令檔草稿開頭必備的註解區塊格式。「用途」與「更新時間」必須包在同一個註解區塊內，不得拆成兩個分開的區塊；此標頭屬於檔案說明標頭（含外框分隔線），實作與後續輸出訊息格式正規化時必須原樣保留，不得移除或轉成 `階段` 前綴。
|
||||
|
||||
## 佔位符
|
||||
|
||||
- `{用途說明}`：一到三行，說明這份指令檔做什麼、在什麼情境被呼叫、重要副作用；多行時每行開頭都要有註解符號。
|
||||
- `{更新時間}`：台灣時區（Asia/Taipei），固定格式 `yyyy/MM/dd HH:mm:ss`，可用下列指令取得：
|
||||
|
||||
```bash
|
||||
TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S'
|
||||
```
|
||||
|
||||
## 變體 A：`#` 註解（`*.sh`、`*.bash`、`*.ps1`、`Makefile`、yaml、`Dockerfile`、docker-compose）
|
||||
|
||||
```
|
||||
# ============================================================================
|
||||
# 用途：{用途說明}
|
||||
# 更新時間：{更新時間}
|
||||
# ============================================================================
|
||||
```
|
||||
|
||||
填入後範例：
|
||||
|
||||
```bash
|
||||
#!/usr/bin/env bash
|
||||
# ============================================================================
|
||||
# 用途：打包 Web 專案並上傳部署壓縮檔至部署主機，供 CI 部署階段呼叫。
|
||||
# 更新時間：2026/07/15 14:30:00
|
||||
# ============================================================================
|
||||
```
|
||||
|
||||
## 變體 B：`::` 註解（`*.bat`、`*.cmd`）
|
||||
|
||||
```
|
||||
:: ===========================================================================
|
||||
:: 用途：{用途說明}
|
||||
:: 更新時間：{更新時間}
|
||||
:: ===========================================================================
|
||||
```
|
||||
|
||||
填入後範例：
|
||||
|
||||
```bat
|
||||
@echo off
|
||||
:: ===========================================================================
|
||||
:: 用途：清理建置輸出目錄並重新建置方案，供本機開發快速重建使用。
|
||||
:: 更新時間：2026/07/15 14:30:00
|
||||
:: ===========================================================================
|
||||
```
|
||||
|
||||
（改用 `REM` 亦可，但同一份檔案內擇一使用並保持一致。）
|
||||
|
||||
## 放置規則
|
||||
|
||||
- 標頭放在檔案最前面；若第一行是必須位於首行的宣告（例如 shebang `#!...`、`@echo off`），標頭緊接在其後。
|
||||
- yaml 檔若有 document marker（`---`），`#` 標頭放在 `---` 之前即可。
|
||||
- 外框分隔線長度不強制，但上下外框必須成對出現，且整個標頭（含外框）視為同一個註解區塊。
|
||||
- 「用途」與「更新時間」兩行的中文標籤與順序依本範本，不得只留其中一項。
|
||||
Reference in New Issue
Block a user