jiantw83andClaude Sonnet 5
2fa73f443d
收斂 plan-wiki／todo-wiki／do-wiki 三個 skill 共用的目錄頁四欄表格格式、 計畫列／TODO 列型別判定、連結來源（查表 path）與回寫規則，避免各自重複。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
53 lines
4.5 KiB
Markdown
53 lines
4.5 KiB
Markdown
---
|
||
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]` 並讀回確認；只要還有未勾項目就不得勾選。
|
||
- 兩者都必須讀回確認寫入成功，失敗立刻停止，不得繼續下一步。
|