plugins/shared
2
0
Fork 0
Code Pull Requests Activity

refactor(todo-wiki): 開工前挑計畫、改用 spec-wiki-contents、命名改 _ 分隔

Browse Source 
TODO 頁 title 命名改用 TODO_{yyyyMMdd}_{HASH}；目錄頁四欄格式與列型別判定
改為引用 spec-wiki-contents；新增階段 2-0 提前確認 wiki repo 並讀目錄頁、
開工前挑選尚未產生代辦的計畫並把計畫頁全文併入需求來源、寫入成功後回寫
該計畫列「已產生」。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
jiantw83
2026-08-17 11:20:45 +08:00
co-authored by Claude Sonnet 5
parent 2fa73f443d
commit 59f0807054
1 changed files with 38 additions and 19 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/todo-wiki/SKILL.md
+38 -19
View File
@@ -1,7 +1,7 @@
--- ---
name: todo-wiki 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`）。 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 CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page <既有頁 title|TODO_<yyyyMMdd>_<HASH>>] [--append|--overwrite] [--yes]"
--- ---
# todo-wiki — 需求分析並同步指定模型 TODO 到 Gitea wiki # todo-wiki — 需求分析並同步指定模型 TODO 到 Gitea wiki
@@ -22,7 +22,7 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝， 先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝，
依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。 依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。
本 skill 需要的規範：`spec-model`、`spec-output`、`spec-execution`、`spec-issue-read`、`spec-todo-list`、`spec-ask-user`、`spec-time-log`、`spec-gitea`、`spec-no-scratch-files`、`spec-skill-invocation` 本 skill 需要的規範：`spec-model`、`spec-output`、`spec-execution`、`spec-issue-read`、`spec-todo-list`、`spec-ask-user`、`spec-time-log`、`spec-gitea`、`spec-wiki-contents`、`spec-no-scratch-files`、`spec-skill-invocation`
本 skill 特有補充： 本 skill 特有補充：
@@ -35,14 +35,16 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
- **一項一回寫、一項一確認**：每完成一項 checklist，就立刻把該項 `- [ ]` 改成 `- [x]`，立即回寫 wiki，讀回解碼比對成功後才能繼續下一項；不可累積多項後一次回寫。 - **一項一回寫、一項一確認**：每完成一項 checklist，就立刻把該項 `- [ ]` 改成 `- [x]`，立即回寫 wiki，讀回解碼比對成功後才能繼續下一項；不可累積多項後一次回寫。
- 目標 wiki repo 不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。 - 目標 wiki repo 不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。
- 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--wiki-index` 時才覆蓋預設值。 - 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--wiki-index` 時才覆蓋預設值。
- TODO 頁 title 預設固定為 `TODO-{yyyyMMdd}-{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由需求彙整、關聯計畫或系統名稱產生穩定短雜湊並轉成全大寫。 - 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 內，以及是否更新 wiki 目錄頁；使用者回答不加入計畫時，仍預設更新 wiki 目錄頁，除非使用者另行明確說不要更新目錄頁。
- 需要加入目錄頁時，目錄標題使用 `{關聯計畫的系統名稱}-代辦`，並連結到 TODO 頁。系統名稱優先從關聯計畫取得；若沒有關聯計畫，從需求內容尋找或產生系統名稱。 - 需要加入目錄頁時，目錄標題使用 `{關聯計畫的系統名稱}-代辦`，並連結到 TODO 頁。**系統名稱優先取自使用者於階段 2 選定的計畫列**；若沒有選定計畫，從需求內容尋找或產生系統名稱。
- 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本 TODO 既有列或在既有表格附加新列。 - 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本 TODO 既有列或在既有表格附加新列。
## 參數 ## 參數
`[--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 CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO_<yyyyMMdd>_<HASH>] [--append|--overwrite] [--yes]`
| 參數 | 說明 | | 參數 | 說明 |
| --- | --- | | --- | --- |
@@ -51,7 +53,7 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
| `--wiki-repo` | 指定要同步的 Gitea wiki repo，例如 `knowledges/Plan`。 | | `--wiki-repo` | 指定要同步的 Gitea wiki repo，例如 `knowledges/Plan`。 |
| `--wiki-index` | wiki 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 | | `--wiki-index` | wiki 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 |
| `--wiki-project` | 關聯計畫或系統名稱；預設仍會更新目錄頁，只有使用者明確表示不要更新目錄頁時才可略過。 | | `--wiki-project` | 關聯計畫或系統名稱；預設仍會更新目錄頁，只有使用者明確表示不要更新目錄頁時才可略過。 |
| `--wiki-page` | todo 頁 title；可指向既有 todo 頁 title，未帶時先詢問是否加入既有 todo，只有使用者選擇新建時才固定使用 `TODO-{yyyyMMdd}-{HASH}`。 | | `--wiki-page` | todo 頁 title；可指向既有 todo 頁 title，未帶時先詢問是否加入既有 todo，只有使用者選擇新建時才固定使用 `TODO_{yyyyMMdd}_{HASH}`。 |
| `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。 | | `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。 |
| `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否關聯到計畫／系統名稱、是否更新 wiki 目錄頁，或對外寫入目標不明等必要決策。 | | `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否關聯到計畫／系統名稱、是否更新 wiki 目錄頁，或對外寫入目標不明等必要決策。 |
@@ -65,13 +67,29 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
## 階段 2：分析需求 ## 階段 2：分析需求
1. 判斷來源型態： ### 階段 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 重用**，不得為同一份目錄頁重複讀取。
### 選擇尚未產生代辦的計畫
- **--wiki-project 已帶則跳過**詢問（即 `--wiki-project` 參數已帶時），直接以該值為系統名稱。
- 依 `/jsc-shared:spec-wiki-contents`〔列型別判定〕，從階段 2-0 讀到的目錄頁取出所有「已產生」為 `[ ]` 的計畫列；**無計畫不問**——一個都沒有時不詢問，直接進入「了解需求」。
- **有計畫必問**——只要存在至少一個這種計畫列，就必須依 `/jsc-shared:spec-ask-user` 詢問使用者是否關聯其中一個；**可不選**——選項固定含「不關聯任何計畫」與「其他」，候選 ≤4 用 `AskUserQuestion`、>4 改文字編號列出。**--yes 不得略過**（即 `--yes` 旗標不得用來省略）本次詢問。
- 使用者選定某個計畫列時，記下該列連結的 `path`，供下一步讀取計畫頁全文；使用者選「不關聯任何計畫」時，維持只用 `--source` 分析需求。
### 了解需求
1. 判斷 `--source` 型態：
- 對應到本機可讀取的檔案路徑 → 視為檔案，唯讀讀取全文，不寫任何衍生檔。 - 對應到本機可讀取的檔案路徑 → 視為檔案，唯讀讀取全文，不寫任何衍生檔。
- 純數字、`#123`、或 Gitea 議題 URL → 視為議題編號，走 `/jsc-shared:spec-issue-read` 讀取描述、所有留言、所有附件。 - 純數字、`#123`、或 Gitea 議題 URL → 視為議題編號，走 `/jsc-shared:spec-issue-read` 讀取描述、所有留言、所有附件。
- 都不是 → 視為需求描述本文。 - 都不是 → 視為需求描述本文。
2. 釐清需求：目標、驗收條件、限制條件、影響範圍任一模糊或缺漏，一律依 `/jsc-shared:spec-ask-user` 詢問使用者。 2. 使用者選定計畫時，以該計畫頁的 `path` 讀取計畫頁全文，**計畫頁全文併入需求來源**，並在需求彙整中**標明來源**（哪些需求來自計畫頁、哪些來自 `--source`）；讀取失敗（404 或權限不足）時**讀取失敗即停**——立刻停止並回報，不得改用臆測內容或略過。未選計畫時維持只用 `--source`。
3. 產出需求彙整：目標、驗收條件、限制條件，以及本次 wiki todo 頁的 `scope`。 3. 釐清需求：目標、驗收條件、限制條件、影響範圍任一模糊或缺漏，一律依 `/jsc-shared:spec-ask-user` 詢問使用者。
4. 若來源本身有既有 Markdown checklist，依 `/jsc-shared:spec-todo-list`「盤點既有 TODO」處理：已勾選視為完成不重做，缺漏才補新項目並標「新增」。 4. 產出需求彙整：目標、驗收條件、限制條件，以及本次 wiki todo 頁的 `scope`。
5. 若來源本身有既有 Markdown checklist，依 `/jsc-shared:spec-todo-list`「盤點既有 TODO」處理：已勾選視為完成不重做，缺漏才補新項目並標「新增」。
## 階段 3：選實作模型 ## 階段 3：選實作模型
@@ -126,9 +144,9 @@ scope: <階段 2 產出的 scope>
## 階段 5：讀取既有 wiki 頁並決定寫入策略 ## 階段 5：讀取既有 wiki 頁並決定寫入策略
1. 依 `spec-gitea` 決定 host 與 token，不輸出 token。 1. 依 `spec-gitea` 決定 host 與 token，不輸出 token。
2. 確認 `--wiki-repo`；缺少就詢問。`--wiki-index` 未帶時固定使用 `CONTENTS`，`--wiki-page` 未帶時先詢問使用者是否要把新的代辦加入既有的 todo 內；只有使用者選擇新建時才固定使用 `TODO-{yyyyMMdd}-{HASH}`。 2. `--wiki-repo` 與目錄頁內容**沿用階段 2-0 的結果**，不重複讀取；`--wiki-index` 未帶時固定使用 `CONTENTS`，`--wiki-page` 未帶時先詢問使用者是否要把新的代辦加入既有的 todo 內；只有使用者選擇新建時才固定使用 `TODO_{yyyyMMdd}_{HASH}`。
3. 詢問使用者三個獨立決策：是否關聯到計畫／系統名稱、是否把新的代辦加入既有的 todo 內，以及是否更新 wiki 目錄頁。使用者回答不加入計畫時，仍預設會更新目錄頁；只有使用者明確回答不要更新目錄頁，才可記錄為「不更新目錄頁」。使用者若明確選既有 todo 頁，該頁就是本次寫入目標，不得自行改成新頁。 3. 詢問使用者三個獨立決策：是否關聯到計畫／系統名稱（已於階段 2「選擇尚未產生代辦的計畫」問過則不重問）、是否把新的代辦加入既有的 todo 內，以及是否更新 wiki 目錄頁。使用者回答不加入計畫時，仍預設會更新目錄頁；只有使用者明確回答不要更新目錄頁，才可記錄為「不更新目錄頁」。使用者若明確選既有 todo 頁，該頁就是本次寫入目標，不得自行改成新頁。
4. 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若使用者選擇既有 todo 頁，直接以該頁 title 對應 `sub_url`；若目錄頁更新決策為開啟，也取得目錄頁 `sub_url`。目錄頁不存在時才建立；目錄頁存在時必須讀取原內容並保留，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。 4. 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若使用者選擇既有 todo 頁，直接以該頁 title 對應 `sub_url`。目錄頁的 `sub_url`／內容沿用階段 2-0 已讀取的結果；目錄頁不存在時才建立；目錄頁存在時必須保留原內容，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。
5. 讀取既有 todo 頁；若不存在，策略為「建立」。 5. 讀取既有 todo 頁；若不存在，策略為「建立」。
6. 既有 todo 頁存在時解析 frontmatter： 6. 既有 todo 頁存在時解析 frontmatter：
@@ -146,17 +164,18 @@ scope: <階段 2 產出的 scope>
同步順序固定： 同步順序固定：
1. 寫入 todo 頁。 1. 寫入 todo 頁。
2. 若使用者明確表示不要更新目錄頁，跳過目錄頁更新；否則 upsert 目錄頁表格列。目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。 2. 若使用者明確表示不要更新目錄頁，跳過目錄頁更新；否則 upsert 目錄頁表格列（TODO 列）。目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。
3. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認。讀回時若回應含 `content_base64`，必須 base64 解碼後再比對 Markdown 內容是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。 3. 若本次於階段 2「選擇尚未產生代辦的計畫」關聯到某個計畫列，回目錄頁把該計畫列「已產生」由 `[ ]` 改為 `[x]` 並讀回確認；找不到對應計畫列時**不得新建該列**，改以警告回報。未關聯計畫時跳過本步驟。
4. 一項一回寫、一項一確認；若任一步失敗，立刻停止，不得把多個 checklist 累積後一起處理。 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 列範例：
```markdown ```markdown
| [<關聯計畫的系統名稱>-代辦](<todo page title percent-encoded>) | todo wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 | | [<關聯計畫的系統名稱>-代辦](<查表取得的 path>) | | [ ] | todo wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |
``` ```
若既有目錄頁沒有 `| 頁面 | 內容 |` 表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。 若既有目錄頁沒有四欄目錄表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。
API 寫入方式： API 寫入方式：