jiantw83andClaude Sonnet 5
e83b4ff4f3
GFM 任務清單語法只在 Markdown 清單項目生效，放進表格儲存格只會被渲染成字面 文字，改用 ●（已完成／已產生）／○（未完成／未產生）避免這個問題； plan-wiki／todo-wiki／do-wiki 三個消費端同步更新描述，計畫頁／代辦頁自己的 checklist（- [ ]／- [x]）不受影響、原樣保留。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
80 lines
10 KiB
Markdown
80 lines
10 KiB
Markdown
---
|
||
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 段落）
|
||
|
||
```markdown
|
||
# 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]` 後，回目錄頁把該列（在其所屬系統段落內）`是否已完成`由 `○` 改為 `●` 並讀回確認；只要還有未勾項目就不得勾選。
|
||
- 兩者都必須讀回確認寫入成功，失敗立刻停止，不得繼續下一步。
|