refactor(spec-wiki-contents): 目錄頁改依系統分段六欄表格,新增系統名稱決定與 OTHER 附屬頁規則

plan-wiki/todo-wiki 新增系統名稱決定流程(需求指定或推論候選/挑工作目錄與程式碼中文名),
spec-wiki-contents 目錄頁維持單一 CONTENTS 頁但依系統分成 `## 英文 中文` 段落,段落內用
計畫/代辦六欄表格取代原本四欄單一表格,並支援不屬於計畫代辦的附屬內容另建 OTHER_ 頁、
用 footnote 從對應列連過去;do-wiki 開工前挑代辦改為掃描全部系統段落。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
2026-08-17 12:54:37 +08:00
co-authored by Claude Sonnet 5
parent 3790ff733f
commit aaa14064f7
4 changed files with 122 additions and 79 deletions
+37 -30
View File
@@ -1,7 +1,7 @@
---
name: todo-wiki
description: 把「需求 → 分析 → 產生鎖定模型的 TODO 清單 → 同步到 Gitea wiki 目錄與頁面」固定成不落地檔案的流程:先依 `/jsc-shared:spec-model` 的「需求分析」任務挑出分析模型,當前模型不符就停止;接著讀取來源(需求描述、本機檔案,或走 `/jsc-shared:spec-issue-read` 讀取的 Gitea 議題)並釐清需求,任何不清楚之處依 `/jsc-shared:spec-ask-user` 詢問;再依「依清單實作」任務挑出實作模型或採用使用者指定;最後把帶 `model`/`model_alias`/`model_reason`/`analyzed_by`/`analyzed_at`/`scope` frontmatter、強制規則區塊,以及具備實作方式/驗收條件/來源依據/必要時建議修改內容的 TODO 內容直接同步到指定 Gitea wiki 目錄頁與 todo 頁。當使用者說要把需求整理成 wiki TODO、同步 todo 到 Gitea wiki、需求轉 todo-wiki、指定模型 todo wiki、或提到 todo-wiki skill 時觸發。不適用於:產生本機 todo.md、把需求拆分成多個 Gitea 議題(用 `/jsc-doc:issues-analyze`)、實作既有 Gitea 議題的 TODO(用 `/jsc-code:issues`)。
argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-model <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page <既有頁 title|TODO_<yyyyMMdd>_<HASH>>] [--append|--overwrite] [--yes]"
argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-model <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index <英文系統名稱>_<中文系統名稱>] [--wiki-project <英文系統名稱>_<中文系統名稱>] [--wiki-page <既有頁 title|TODO_<yyyyMMdd>_<HASH>>] [--append|--overwrite] [--yes]"
---
# todo-wiki — 需求分析並同步指定模型 TODO 到 Gitea wiki
@@ -34,17 +34,24 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
- **模型鎖定要在開工前完成**:在讀取任何來源、做任何分析、或接觸 wiki 前,先確認目前執行本 skill 的模型 id;無法確定時先請使用者執行 `/status`,不得用猜的。
- **一項一回寫、一項一確認**:每完成一項 checklist,就立刻把該項 `- [ ]` 改成 `- [x]`,立即回寫 wiki,讀回解碼比對成功後才能繼續下一項;不可累積多項後一次回寫。
- 目標 wiki repo 不明時必須詢問;不得因為目前工作目錄是某 repo 就臆測 wiki 目標。
- 目錄頁 title 預設固定為 `CONTENTS`,不詢問使用者;只有使用者明確提供 `--wiki-index` 時才覆蓋預設值。
- TODO 頁 title 預設固定為 `TODO_{yyyyMMdd}_{HASH}`,不詢問使用者;`yyyyMMdd` 使用 Asia/Taipei 當日日期,`HASH` 由需求彙整、關聯計畫或系統名稱產生穩定短雜湊並轉成全大寫。
- **開工前先挑計畫**:依 `/jsc-shared:spec-wiki-contents`〔使用者互動〕,在階段 2-0 讀到目錄頁後、進入需求分析前,先列出所有「已產生」為 `[ ]` 的計畫列詢問使用者是否關聯(可以不選);細節見階段 2「選擇尚未產生代辦的計畫」。
- 目錄頁列型別判定(哪些列是計畫列、哪些是 TODO 列,以及無法判定時的 `[目錄盤點][WRN]` 提示)一律依 `/jsc-shared:spec-wiki-contents`〔列型別判定〕,本 skill 不重複定義。
- 必須詢問使用者三個獨立決策:是否關聯到計畫/系統名稱、是否把新的代辦加入既有的 todo 內,以及是否更新 wiki 目錄頁;使用者回答不加入計畫時,仍預設更新 wiki 目錄頁,除非使用者另行明確說不要更新目錄頁。
- 需要加入目錄頁時,目錄標題使用 `{關聯計畫的系統名稱}-代辦`,並連結到 TODO 頁。**系統名稱優先取自使用者於階段 2 選定的計畫列**;若沒有選定計畫,從需求內容尋找或產生系統名稱。
- 目錄頁禁止整頁覆蓋:不存在時才新建;存在時必須保留既有內容,只修改本 TODO 既有列或在既有表格附加新列。
- 目錄頁是單一共用頁面,title 預設固定為 `CONTENTS`,不詢問使用者;只有使用者明確提供 `--wiki-index` 時才覆蓋預設值。
- TODO 頁 title 預設固定為 `TODO_{yyyyMMdd}_{HASH}`,不詢問使用者;`yyyyMMdd` 使用 Asia/Taipei 當日日期,`HASH` 由需求彙整或系統名稱產生穩定短雜湊並轉成全大寫。
- **開工前先確定系統名稱、再挑要不要合併**:依下方〔系統名稱決定〕得到系統名稱後,在階段 2-0 讀到該系統的目錄頁時,依 `/jsc-shared:spec-wiki-contents`〔使用者互動〕,列出所有「`計畫`欄有連結、`代辦`欄空白」的列詢問使用者是否要合併(可以不選);細節見階段 2「選擇要不要合併進既有列」。
- 目錄頁列合併判斷(哪些列可以合併、找不到可合併列時如何新增列)一律依 `/jsc-shared:spec-wiki-contents`〔新增列前先找可合併的既有列〕,本 skill 不重複定義。
- 必須詢問使用者兩個獨立決策:是否合併進既有列,以及是否把新的代辦加入既有的 todo 頁內;系統名稱已由〔系統名稱決定〕流程固定,不再詢問是否關聯計畫/系統名稱。目錄頁預設一律更新,除非使用者明確說不要更新目錄頁。
- 需要加入目錄頁時,`代辦`欄連結到 TODO 頁;系統名稱固定為下方〔系統名稱決定〕的結果,不因是否合併既有列而改變。
- 目錄頁禁止整頁覆蓋:不存在時才新建;存在時必須保留既有內容,只 upsert 本 TODO 對應的既有列或在既有表格附加新列。
### 系統名稱決定
- **英文系統名稱**:使用目前工作目錄的名稱(`basename` 當前工作目錄)。
- **中文系統名稱**:從既有程式碼與文件中尋找(例如 `README`、`package.json`/`pyproject.toml` 的 name/description、`CLAUDE.md`、專案內顯著的中文專案名稱);找到多個不一致的候選時,依 `/jsc-shared:spec-ask-user` 請使用者確認採用哪一個。完全找不到中文名稱時,不得自行編造,依 `spec-ask-user` 詢問使用者提供。
- `--wiki-project` 已帶時直接採用(視為使用者已指定英文+中文系統名稱),跳過上述推論與詢問。
- 決定出的系統名稱在本次 todo-wiki 執行全程固定不變,供目錄頁對應段落標題、TODO 頁 H1 等引用系統名稱處使用;不再走「使用者從既有計畫列中選擇要關聯的系統」這條路徑。
## 參數
`[--source <需求描述|檔案路徑|議題編號>] [--impl-model <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO_<yyyyMMdd>_<HASH>] [--append|--overwrite] [--yes]`
`[--source <需求描述|檔案路徑|議題編號>] [--impl-model <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index <英文系統名稱>_<中文系統名稱>] [--wiki-project <英文系統名稱>_<中文系統名稱>] [--wiki-page TODO_<yyyyMMdd>_<HASH>] [--append|--overwrite] [--yes]`
| 參數 | 說明 |
| --- | --- |
@@ -52,10 +59,10 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
| `--impl-model` | 直接指定實作模型(id 或 alias),跳過階段 3 的推薦流程;仍會在 `model_reason` 註明「使用者指定」。 |
| `--wiki-repo` | 指定要同步的 Gitea wiki repo,例如 `knowledges/Plan`。 |
| `--wiki-index` | wiki 目錄頁 title;未帶時固定使用 `CONTENTS`,不詢問。 |
| `--wiki-project` | 關聯計畫或系統名稱;預設仍會更新目錄頁,只有使用者明確表示不要更新目錄頁時才可略過。 |
| `--wiki-project` | 系統名稱(英文+中文);未帶時依〔系統名稱決定〕流程從工作目錄與程式碼推論。預設仍會更新目錄頁,只有使用者明確表示不要更新目錄頁時才可略過。 |
| `--wiki-page` | todo 頁 title;可指向既有 todo 頁 title,未帶時先詢問是否加入既有 todo,只有使用者選擇新建時才固定使用 `TODO_{yyyyMMdd}_{HASH}`。 |
| `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一,同時提供視為衝突,仍需詢問使用者。 |
| `--yes` | 略過一般性確認;不得略過模型不同是否覆蓋、目標 wiki 不明、是否關聯到計畫/系統名稱、是否更新 wiki 目錄頁,或對外寫入目標不明等必要決策。 |
| `--yes` | 略過一般性確認;不得略過模型不同是否覆蓋、目標 wiki 不明、是否合併進既有列、是否更新 wiki 目錄頁,或對外寫入目標不明等必要決策。 |
## 階段 1:選分析模型
@@ -67,18 +74,18 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
## 階段 2:分析需求
### 階段 2-0:確認 wiki repo 並讀取目錄頁
### 階段 2-0:確定系統名稱、確認 wiki repo 並讀取目錄頁
1. **先確認 --wiki-repo**(即 `--wiki-repo` 參數);缺少時依 `/jsc-shared:spec-ask-user` 詢問,不臆測。
2. 依 `/jsc-shared:spec-gitea`〔Wiki 頁名轉義規則〕規則 2 分頁**查表取 path**,取得目錄頁(預設 title `CONTENTS`)的 `path` 並讀取內容。
3. 本步驟讀到的目錄頁內容**供階段 5 重用**,不得為同一份目錄頁重複讀取。
2. 依上方〔系統名稱決定〕得到英文+中文系統名稱;`--wiki-project` 已帶則直接採用並跳過推論。
3. 依 `/jsc-shared:spec-gitea`〔Wiki 頁名轉義規則〕規則 2 分頁**查表取 path**,取得目錄頁(title 預設 `CONTENTS`,或 `--wiki-index` 指定值)的 `path` 並讀取內容,定位到本系統對應的 `## {英文系統名稱} {中文系統名稱}` 段落;目錄頁不存在、或存在但沒有本系統段落,都視為該系統尚無任何計畫或代辦。
4. 本步驟讀到的目錄頁內容**供階段 5 重用**,不得為同一份目錄頁重複讀取。
### 選擇尚未產生代辦的計畫
### 選擇要不要合併進既有列
- **--wiki-project 已帶則跳過**詢問(即 `--wiki-project` 參數已帶時),直接以該值為系統名稱。
- 依 `/jsc-shared:spec-wiki-contents`〔列型別判定〕,從階段 2-0 讀到的目錄頁取出所有「已產生」為 `[ ]` 的計畫列;**無計畫不問**——一個都沒有時不詢問,直接進入「了解需求」。
- **有計畫必問**——只要存在至少一個這種計畫列,就必須依 `/jsc-shared:spec-ask-user` 詢問使用者是否關聯其中一個;**可不選**——選項固定含「不關聯任何計畫」與「其他」,候選 ≤4 用 `AskUserQuestion`、>4 改文字編號列出。**--yes 不得略過**(即 `--yes` 旗標不得用來省略)本次詢問。
- 使用者選定某個計畫列時,記下該列連結的 `path`,供下一步讀取計畫頁全文;使用者選「不關聯任何計畫」時,維持只用 `--source` 分析需求。
- 依 `/jsc-shared:spec-wiki-contents`〔新增列前先找可合併的既有列〕,從階段 2-0 讀到的目錄頁取出所有「`計畫`欄有連結、`代辦`欄空白」的列;**無可合併列不問**——一個都沒有時不詢問,直接進入「了解需求」。
- **有可合併列必問**——只要存在至少一個這種列,就必須依 `/jsc-shared:spec-ask-user` 詢問使用者是否要合併其中一列;**可不選**——選項固定含「不合併,直接新增列」與「其他」,候選 ≤4 用 `AskUserQuestion`、>4 改文字編號列出。**--yes 不得略過**(即 `--yes` 旗標不得用來省略)本次詢問。
- 使用者選定某一列時,記下該列`計畫`欄連結的 `path`,供下一步讀取計畫頁全文;使用者選「不合併」時,維持只用 `--source` 分析需求。
### 了解需求
@@ -86,7 +93,7 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
- 對應到本機可讀取的檔案路徑 → 視為檔案,唯讀讀取全文,不寫任何衍生檔。
- 純數字、`#123`、或 Gitea 議題 URL → 視為議題編號,走 `/jsc-shared:spec-issue-read` 讀取描述、所有留言、所有附件。
- 都不是 → 視為需求描述本文。
2. 使用者選定計畫時,以該計畫頁的 `path` 讀取計畫頁全文,**計畫頁全文併入需求來源**,並在需求彙整中**標明來源**(哪些需求來自計畫頁、哪些來自 `--source`);讀取失敗(404 或權限不足)時**讀取失敗即停**——立刻停止並回報,不得改用臆測內容或略過。未選計畫時維持只用 `--source`。
2. 使用者選定要合併的計畫列時,以該列連結的 `path` 讀取計畫頁全文,**計畫頁全文併入需求來源**,並在需求彙整中**標明來源**(哪些需求來自計畫頁、哪些來自 `--source`);讀取失敗(404 或權限不足)時**讀取失敗即停**——立刻停止並回報,不得改用臆測內容或略過。未選合併時維持只用 `--source`。
3. 釐清需求:目標、驗收條件、限制條件、影響範圍任一模糊或缺漏,一律依 `/jsc-shared:spec-ask-user` 詢問使用者。
4. 產出需求彙整:目標、驗收條件、限制條件,以及本次 wiki todo 頁的 `scope`。
5. 若來源本身有既有 Markdown checklist,依 `/jsc-shared:spec-todo-list`「盤點既有 TODO」處理:已勾選視為完成不重做,缺漏才補新項目並標「新增」。
@@ -99,7 +106,7 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
## 階段 4:產生 TODO wiki 內容
產生 Markdown 內容但不得寫入本機檔案。
產生 Markdown 內容但不得寫入本機檔案。內容 H1 固定為 `{英文系統名稱} {中文系統名稱} 代辦事項`(使用〔系統名稱決定〕得到的系統名稱,與 wiki 頁 title `TODO_{yyyyMMdd}_{HASH}` 是兩件事,不得把雜湊 title 直接當 H1),frontmatter 之後、強制規則區塊之前先放這行 H1。
### frontmatter
@@ -144,8 +151,8 @@ scope: <階段 2 產出的 scope>
## 階段 5:讀取既有 wiki 頁並決定寫入策略
1. 依 `spec-gitea` 決定 host 與 token,不輸出 token。
2. `--wiki-repo` 與目錄頁內容**沿用階段 2-0 的結果**,不重複讀取;`--wiki-index` 未帶時固定使用 `CONTENTS`,`--wiki-page` 未帶時先詢問使用者是否要把新的代辦加入既有的 todo 內;只有使用者選擇新建時才固定使用 `TODO_{yyyyMMdd}_{HASH}`。
3. 詢問使用者三個獨立決策:是否關聯到計畫/系統名稱(已於階段 2「選擇尚未產生代辦的計畫」問過則不重問)、是否把新的代辦加入既有的 todo 內,以及是否更新 wiki 目錄頁。使用者回答不加入計畫時,仍預設會更新目錄頁;只有使用者明確回答不要更新目錄頁,才可記錄為「不更新目錄頁」。使用者若明確選既有 todo 頁,該頁就是本次寫入目標,不得自行改成新頁。
2. `--wiki-repo`、系統名稱與目錄頁內容**沿用階段 2-0 的結果**,不重複讀取;`--wiki-index` 未帶時固定使用 `CONTENTS`,`--wiki-page` 未帶時先詢問使用者是否要把新的代辦加入既有的 todo 內;只有使用者選擇新建時才固定使用 `TODO_{yyyyMMdd}_{HASH}`。
3. 詢問使用者兩個獨立決策:是否把新的代辦加入既有的 todo 內,以及是否更新 wiki 目錄頁(是否合併進既有列已於階段 2「選擇要不要合併進既有列」問過,不重問)。目錄頁預設一律更新;只有使用者明確回答不要更新目錄頁,才可記錄為「不更新目錄頁」。使用者若明確選既有 todo 頁,該頁就是本次寫入目標,不得自行改成新頁。
4. 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`,以 title 查表取得 todo 頁 `sub_url`;若使用者選擇既有 todo 頁,直接以該頁 title 對應 `sub_url`。目錄頁的 `sub_url`/內容沿用階段 2-0 已讀取的結果;目錄頁不存在時才建立;目錄頁存在時必須保留原內容,不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。
5. 讀取既有 todo 頁;若不存在,策略為「建立」。
6. 既有 todo 頁存在時解析 frontmatter:
@@ -164,18 +171,18 @@ scope: <階段 2 產出的 scope>
同步順序固定:
1. 寫入 todo 頁。
2. 若使用者明確表示不要更新目錄頁,跳過目錄頁更新;否則 upsert 目錄頁表格列(TODO 列)。目錄頁不存在才建立;存在時禁止整頁覆蓋,只修改既有 `<關聯計畫的系統名稱>-代辦` 列,或在既有表格/頁末附加新列。
3. 若本次於階段 2「選擇尚未產生代辦的計畫」關聯到某個計畫列,回目錄頁把該計畫列「已產生」由 `[ ]` 改為 `[x]` 並讀回確認;找不到對應計畫列時**不得新建該列**,改以警告回報。未關聯計畫時跳過本步驟。
2. 若使用者明確表示不要更新目錄頁,跳過目錄頁更新;否則依 `spec-wiki-contents`〔新增列前先找可合併的既有列〕upsert 本系統對應段落內的表格列。目錄頁不存在才整頁新建(title `CONTENTS`);目錄頁存在但沒有本系統段落時,在頁尾新增一個 `## {英文系統名稱} {中文系統名稱}` 段落;兩種情況都禁止整頁覆蓋,只修改對應列的`代辦`/`是否已完成`/內容欄,或在該段落表格附加新列。
3. 若本次於階段 2「選擇要不要合併進既有列」合併到某個計畫列,回目錄頁把該列`是否已產生代辦`由 `[ ]` 改為 `[x]`、`代辦`欄填入本次 TODO 頁連結並讀回確認;找不到對應列時**不得新建混用列**,改以警告回報。未合併時跳過本步驟,直接以新列的`代辦`欄寫入、`計畫`欄留空。
4. 讀回 todo 頁確認內容已更新;有更新目錄頁時也讀回目錄頁確認(含步驟 2、3 的異動)。讀回時若回應含 `content_base64`,必須 base64 解碼後再比對 Markdown 內容是否與預期一致;若回應格式不同,依 Gitea 官方 API 文件取出正文再比對,不可只確認狀態碼或頁面存在。
5. 一項一回寫、一項一確認;若任一步失敗,立刻停止,不得把多個 checklist 累積後一起處理。
目錄頁的四欄表格格式、TODO 列初始值、以及連結來源(查表取得的 `sub_url`/`path`,不使用 percent-encode 的 title)一律依 `/jsc-shared:spec-wiki-contents`,本 skill 不重複定義;TODO 列範例:
目錄頁是單一共用頁面依系統分段、段落標題與六欄表格格式、列合併規則、以及連結來源(查表取得的 `sub_url`/`path`,不使用 percent-encode 的 title)一律依 `/jsc-shared:spec-wiki-contents`,本 skill 不重複定義;新增列範例(未合併既有計畫列時):
```markdown
| [<關聯計畫的系統名稱>-代辦](<查表取得的 path>) | | [ ] | todo wiki:<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |
| | | | [<TODO 頁連結文字>](<查表取得的 path>) | [ ] | todo wiki:<系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |
```
若既有目錄頁沒有四欄目錄表格,附加一段新的目錄表格到頁面末尾,不得刪除或重排既有內容。
若既有目錄頁沒有本系統的 `## ` 段落與六欄目錄表格,附加一段新的段落到頁面末尾,不得刪除或重排其他系統的段落與既有內容。
API 寫入方式:
@@ -211,6 +218,6 @@ API 寫入方式:
| 助理 | 呼叫 |
| --- | --- |
| Claude Code / Antigravity | `/jsc-shared:todo-wiki --source "把 X 模組改成非同步" --wiki-repo knowledges/Plan --wiki-project Kokorone` |
| Codex | `$todo-wiki --source ./RFC.md --wiki-repo knowledges/Plan --wiki-project Kokorone` |
| Claude Code / Antigravity | `/jsc-shared:todo-wiki --source "把 X 模組改成非同步" --wiki-repo knowledges/Plan --wiki-project Kokorone_心音` |
| Codex | `$todo-wiki --source ./RFC.md --wiki-repo knowledges/Plan --wiki-project Kokorone_心音` |
| OpenCode | 描述需求(如「幫我把這段需求分析清楚,直接同步成 Gitea wiki TODO,不要落地檔案」)自動觸發 |