shared/skills/spec-wiki-contents/SKILL.md

---

name: spec-wiki-contents description: JSC plugins 共用「wiki 目錄頁格式與列合併規範」：目錄頁維持單一共用頁面（title 固定為 CONTENTS），依系統分段，每個系統一個 ## {英文系統名稱} {中文系統名稱} 段落，段落內先系統描述、再接 | 計畫 | 是否已產生代辦 | 內容 | 代辦 | 是否已完成 | 內容 | 六欄表格，一列代表一組「計畫＋其對應代辦」的配對關係、缺其中一邊時對應欄位留空、新增計畫或代辦時先找可合併的既有列才新增列、目錄頁不存在才新建、存在時禁止整頁覆蓋只能 upsert 既有段落或列、不屬於計畫或代辦的附屬參考內容改建 OTHER_{yyyyMMdd}_{HASH} 頁，從對應列原連結後加 Markdown footnote 標記（[^label] ＋段落末 [^label]: 連結）連過去，不覆蓋原本的計畫／代辦連結。當其他 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），依系統分段管理，不得各自複製一份格式或判定邏輯。

目錄頁的定位：單一共用頁面，依系統分段

目錄頁是單一共用頁面（title 固定為 CONTENTS，只有使用者明確提供 --index／--wiki-index 時才覆蓋），不是每個系統各自一頁。頁面內依系統分段：每個系統一個 ## {英文系統名稱} {中文系統名稱} 段落（系統名稱決定方式見 /jsc-shared:plan-wiki〔系統名稱決定〕與 /jsc-shared:todo-wiki〔系統名稱決定〕，本規範不重複定義），該系統的所有計畫、代辦都 upsert 進自己的段落；不同系統不共用同一個段落，也不混進同一張表格。

目錄頁格式（固定：H1 CONTENTS＋逐系統 H2 段落）

# CONTENTS

## <英文系統名稱> <中文系統名稱>

<系統描述：一段文字，說明這個系統做什麼、範圍與目的>

| 計畫 | 是否已產生代辦 | 內容 | 代辦 | 是否已完成 | 內容 |
| --- | :-: | --- | --- | :-: | --- |
| [<計畫頁連結文字>](<查表取得的 path>) | ○ | <計畫摘要> | [<代辦頁連結文字>](<查表取得的 path>) | ○ | <代辦摘要> |

## <另一個英文系統名稱> <另一個中文系統名稱>

...（格式同上，各系統各自一段）

• 頁面 H1 固定為 CONTENTS；每個系統各自一個 H2 段落，標題固定為 <英文系統名稱> <中文系統名稱>，與該系統其他頁面（計畫頁、代辦頁）H1 用的是同一組系統名稱。
• 段落 H2 之後先放一段「系統描述」，說明系統目的與範圍；來源為需求彙整或計畫目標摘要，不得留空。
• 表格欄位固定六個：計畫／是否已產生代辦／內容／代辦／是否已完成／內容，對齊列固定 | --- | :-: | --- | --- | :-: | --- |，不得增減欄位或改變順序。
• check 欄一律用 ●（已完成／已產生）／○（未完成／未產生），不適用的欄位維持留空；不得改用 [ ]／[x]——GFM 任務清單語法只在 Markdown 清單項目（- [ ] ...）裡才會被渲染成核取方塊，放進表格儲存格會被字面呈現成 [ ]／[x] 這四個字元，不會渲染成方塊。此規則只管表格儲存格，計畫頁／代辦頁內容裡的 checklist（- [ ] **編號 短標題**：...）是合法且正常渲染的 GFM 任務清單，不受本規則影響、不得比照修改。
• 一列代表一組「計畫＋其對應代辦」的配對關係，不是「一列一種頁面型別」。同一系統可以有多列，例如：同系統先後有多個計畫、同一計畫衍生多個代辦、或代辦先於計畫存在。
• 只有計畫、還沒代辦：代辦欄與是否已完成欄留空（不得填 ○，因為根本不適用），是否已產生代辦欄填 ○。
• 只有代辦、沒有對應計畫（例如需求直接進 todo-wiki 沒有經過 plan-wiki）：計畫欄與是否已產生代辦欄留空，代辦欄填連結，是否已完成欄填 ○／●。
• 兩邊都有：是否已產生代辦填 ●，是否已完成依代辦頁完成狀態填 ○／●。
• 目錄頁不存在時才依上述格式新建（先建一個系統的段落）；已存在時禁止整頁覆蓋，只能 upsert 既有段落內的列、在既有段落表格附加新列，或（該系統尚無段落時）在頁尾附加一個新的 ## 段落，保留其餘系統的段落與內容。

新增列前先找可合併的既有列

新建立計畫或代辦時，先定位到該系統的 ## 段落（找不到就視為該系統尚無段落，需新增段落），在段落內的表格找有沒有可以合併進去的列，找不到才新增列：

情境	判斷	動作
目錄頁裡沒有該系統的 ## 段落	—	在頁尾附加新段落（系統描述＋空表格），再依下列規則新增列
新建代辦，且使用者於開工前選定要關聯的計畫列	該計畫列的代辦欄目前是空的	直接把代辦欄、是否已完成欄、內容欄填進同一列，是否已產生代辦改為 ●；不新增列
新建代辦，且使用者於開工前選定的計畫列代辦欄已有內容	該列已被佔用	不得覆蓋既有代辦，改在同一段落表格附加新列，計畫欄留空或重複連結同一計畫（依 todo-wiki 詢問使用者結果決定），並依 spec-ask-user 詢問使用者是否要重複關聯同一計畫
新建代辦，未關聯任何計畫	—	在該系統段落表格附加新列，計畫欄與是否已產生代辦欄留空
新建計畫	該系統段落表格已有某列計畫欄為空、且內容明顯屬於同一需求脈絡（需使用者確認，不得臆測）	依使用者確認結果，填入該列計畫欄；未獲確認一律新增列
新建計畫，無可合併列	—	在該系統段落表格附加新列，代辦欄與是否已完成欄留空

附屬參考頁（OTHER_ 頁）與註腳連結

計畫或代辦有需要附掛的補充內容（例如視覺資產、命名規範、外部素材說明），但該內容本身不是計畫也不是代辦、塞不進六欄表格時：

• 另建一頁，title 固定為 OTHER_{yyyyMMdd}_{HASH}（yyyyMMdd／HASH 規則與 PLAN_／TODO_ 相同）；OTHER_ 頁內容不受計畫頁／代辦頁格式（frontmatter、固定 H1）約束，維持原有內容型態即可。
• 目錄頁對應列的計畫或代辦欄保留原本指向計畫頁／代辦頁的連結不變，只在連結後面加一個 Markdown footnote 標記：[原連結文字](原 path)[^<label>]。不得改用參考式連結（[text][1]）取代原連結，那會讓連結目的地被覆蓋成附屬頁而不是計畫／代辦頁本身。
• <label> 需在整份目錄頁內全域唯一，建議用系統英文名稱＋序號避免撞號（例如 [^kokorone-1]）；顯示出來的「小數字」由 Gitea 依頁面內 footnote 出現順序自動編號，不必也不能手動指定數字。
• 在該系統段落表格下方列出對應的 footnote 定義：[^<label>]: [<OTHER 頁連結文字>](<查表取得的 path>)；一列有多個附屬頁時，用不同 <label> 各自定義。
• 找不到可掛的既有列、或使用者未指明要掛在哪一列時，依 spec-ask-user 詢問使用者，不得自行臆測掛在哪一列。

連結來源：查表取得的 path，不用 percent-encode title

目錄列的連結一律使用依 /jsc-shared:spec-gitea〔Wiki 頁名轉義規則〕規則 2 分頁查表取得的 sub_url／path；不得自行對 title 做 encodeURIComponent 之類的轉換後當成連結——含中日文標題的頁面，Gitea 的轉義規則不可靠，只有查表結果可信。新建列且對應頁面尚未建立時，先建立該頁取得其 sub_url 後再回填目錄列連結；查表暫時失敗時，先以人類可讀 title 當佔位連結並標註「待查表更新」，不得因此跳過目錄列的建立。

使用者互動：開工前挑選

• todo-wiki 開工前：先確定本次系統名稱（見 todo-wiki〔系統名稱決定〕），讀取目錄頁後定位到該系統的 ## 段落；若段落存在且段落內有「計畫欄有連結、代辦欄空白」的列，依 /jsc-shared:spec-ask-user 詢問使用者是否要把本次代辦合併進其中一列（選項固定含「不合併，直接新增列」與「其他」，可以不選）；只要存在至少一個這種列就必須詢問，--yes 不得略過；一個都沒有時不詢問直接繼續。
• do-wiki 開工前：讀目錄頁，掃描所有系統段落，列出所有是否已完成為 ○ 的列（即代辦欄非空但未完成者），候選標示為「{該列所屬系統的段落標題}：{代辦內容摘要}」，依 /jsc-shared:spec-ask-user 以單選呈現；沒有任何未完成代辦列時直接結束，不讀取任何代辦頁、不修改任何檔案或 wiki。
• 候選數量、呈現方式（候選 ≤4 用 AskUserQuestion、>4 改文字編號列出）與「其他」選項，一律依 /jsc-shared:spec-ask-user 辦理。

回寫規則

• todo-wiki 寫入代辦頁成功後：若本次合併進某個既有列，回目錄頁把該列代辦／是否已完成／內容欄填好、是否已產生代辦改為 ●並讀回確認；若本次是新增列，依「新增列前先找可合併的既有列」規則在對應系統段落附加後讀回確認。
• do-wiki 於代辦頁全部項目皆為 - [x] 後，回目錄頁把該列（在其所屬系統段落內）是否已完成由 ○ 改為 ● 並讀回確認；只要還有未勾項目就不得勾選。
• 兩者都必須讀回確認寫入成功，失敗立刻停止，不得繼續下一步。