From 2fa73f443d21d6bf27e61b684ac0303fc72da53f Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 17 Aug 2026 11:20:34 +0800 Subject: [PATCH] =?UTF-8?q?feat(spec-wiki-contents):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=20wiki=20=E7=9B=AE=E9=8C=84=E9=A0=81=E5=9B=9B=E6=AC=84?= =?UTF-8?q?=E6=A0=BC=E5=BC=8F=E8=88=87=E5=88=97=E5=9E=8B=E5=88=A5=E5=88=A4?= =?UTF-8?q?=E5=AE=9A=E5=85=B1=E7=94=A8=E8=A6=8F=E7=AF=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 收斂 plan-wiki／todo-wiki／do-wiki 三個 skill 共用的目錄頁四欄表格格式、 計畫列／TODO 列型別判定、連結來源（查表 path）與回寫規則，避免各自重複。 Co-Authored-By: Claude Sonnet 5 --- skills/spec-wiki-contents/SKILL.md | 52 ++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 skills/spec-wiki-contents/SKILL.md diff --git a/skills/spec-wiki-contents/SKILL.md b/skills/spec-wiki-contents/SKILL.md new file mode 100644 index 0000000..3f44f13 --- /dev/null +++ b/skills/spec-wiki-contents/SKILL.md @@ -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]` 並讀回確認；只要還有未勾項目就不得勾選。 +- 兩者都必須讀回確認寫入成功，失敗立刻停止，不得繼續下一步。