2026-08-17 03:43:51 +00:00
1 changed files with 52 additions and 0 deletions
@@ -0,0 +1,52 @@
+---
+name: spec-wiki-contents
+description: JSC plugins 共用「wiki 目錄頁四欄格式與列型別判定規範」：目錄頁固定 `| 頁面 | 已產生 | 已完成 | 內容 |` 四欄表格與 `| --- | :-: | :-: | --- |` 對齊列、依「已產生」「已完成」欄位判定計畫列／TODO 列／略過並輸出 WRN、目錄列連結一律用查表取得的 sub_url／path 而非 percent-encode 的 title、目錄頁不存在才新建、存在時禁止整頁覆蓋只能 upsert 既有列。當其他 skill 內文引用 spec-wiki-contents 或 /jsc-shared:spec-wiki-contents、或需要讀取／更新 plan-wiki／todo-wiki／do-wiki 共用的四欄目錄頁時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
+---
+
+# spec-wiki-contents — 共用 wiki 目錄頁四欄格式與列型別判定規範
+
+`plan-wiki`、`todo-wiki`、`do-wiki` 三個 skill 共用同一份 Gitea wiki 目錄頁（預設 title `CONTENTS`），一律遵守以下規範，不得各自複製一份格式或判定邏輯。
+
+## 目錄頁格式（固定四欄）
+
+```markdown
+# CONTENTS
+
+| 頁面 | 已產生 | 已完成 | 內容 |
+| --- | :-: | :-: | --- |
+| [<系統名稱>-計畫](<查表取得的 path>) | [ ] |  | plan wiki：<系統名稱> 計畫 |
+| [<系統名稱>-代辦](<查表取得的 path>) |  | [ ] | todo wiki：<系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |
+```
+
+- 欄位固定四個：`頁面`／`已產生`／`已完成`／`內容`，對齊列固定 `| --- | :-: | :-: | --- |`，不得增減欄位或改變順序。
+- **計畫列**：由 `plan-wiki` 建立，「已產生」欄填 `[ ]`（表示尚未產生對應 TODO），「已完成」欄留空。
+- **TODO 列**：由 `todo-wiki` 建立，「已完成」欄填 `[ ]`，「已產生」欄留空。
+- 目錄頁不存在時才依上述格式新建；已存在時**禁止整頁覆蓋**，只能 upsert 既有列或在既有表格附加新列，保留其餘標題、說明與內容。
+
+## 列型別判定
+
+讀取既有目錄頁表格時，依每列「已產生」「已完成」兩欄判定列型別：
+
+| 判定 | 條件 |
+| --- | --- |
+| 計畫列 | 「已產生」欄含 `[ ]` 或 `[x]`（不論勾選與否），「已完成」欄留空 |
+| TODO 列 | 「已完成」欄含 `[ ]` 或 `[x]`，「已產生」欄留空 |
+| 略過 | 兩欄皆空、或兩欄格式皆無法解析 |
+
+略過的列一律輸出 `[yyyy/MM/dd HH:mm:ss][目錄盤點][WRN]: <該列「頁面」欄內容> 兩個 check 欄皆無法判定列型別，已略過`，並繼續處理其餘列，不得中止整個流程、也不得自行臆測型別。
+
+## 連結來源：查表取得的 path，不用 percent-encode title
+
+目錄列的連結一律使用依 `/jsc-shared:spec-gitea`〔Wiki 頁名轉義規則〕規則 2 分頁查表取得的 `sub_url`／`path`；**不得**自行對 title 做 `encodeURIComponent` 之類的轉換後當成連結——含中日文標題的頁面，Gitea 的轉義規則不可靠，只有查表結果可信。新建列且對應頁面尚未建立時，先建立該頁取得其 `sub_url` 後再回填目錄列連結；查表暫時失敗時，先以人類可讀 title 當佔位連結並標註「待查表更新」，不得因此跳過目錄列的建立。
+
+## 使用者互動：開工前挑選
+
+- `todo-wiki` 開工前：讀目錄頁，列出所有「已產生」為 `[ ]` 的計畫列，依 `/jsc-shared:spec-ask-user` 詢問使用者是否要關聯其中一個（選項固定含「不關聯任何計畫」與「其他」，可以不選）；只要存在至少一個這種計畫列就必須詢問，`--yes` 不得略過；一個都沒有時不詢問直接繼續。
+- `do-wiki` 開工前：讀目錄頁，列出所有「已完成」為 `[ ]` 的 TODO 列，依 `/jsc-shared:spec-ask-user` 以**單選**呈現；沒有任何未完成 TODO 列時直接結束，不讀取任何 TODO 頁、不修改任何檔案或 wiki。
+- 兩者的候選數量、呈現方式（候選 ≤4 用 `AskUserQuestion`、>4 改文字編號列出）與「其他」選項，一律依 `/jsc-shared:spec-ask-user` 辦理。
+
+## 回寫規則
+
+- `todo-wiki` 寫入 TODO 頁成功後，若本次關聯到某個計畫列，回目錄頁把該計畫列「已產生」由 `[ ]` 改為 `[x]` 並讀回確認；找不到對應計畫列時**不得新建該列**，改以警告回報。
+- `do-wiki` 於 TODO 頁全部項目皆為 `- [x]` 後，回目錄頁把該 TODO 列「已完成」由 `[ ]` 改為 `[x]` 並讀回確認；只要還有未勾項目就不得勾選。
+- 兩者都必須讀回確認寫入成功，失敗立刻停止，不得繼續下一步。