From 59f080705441c1fae451f032af3b9e7a370193bb Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 17 Aug 2026 11:20:45 +0800 Subject: [PATCH] =?UTF-8?q?refactor(todo-wiki):=20=E9=96=8B=E5=B7=A5?= =?UTF-8?q?=E5=89=8D=E6=8C=91=E8=A8=88=E7=95=AB=E3=80=81=E6=94=B9=E7=94=A8?= =?UTF-8?q?=20spec-wiki-contents=E3=80=81=E5=91=BD=E5=90=8D=E6=94=B9=20=5F?= =?UTF-8?q?=20=E5=88=86=E9=9A=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit TODO 頁 title 命名改用 TODO_{yyyyMMdd}_{HASH}；目錄頁四欄格式與列型別判定 改為引用 spec-wiki-contents；新增階段 2-0 提前確認 wiki repo 並讀目錄頁、 開工前挑選尚未產生代辦的計畫並把計畫頁全文併入需求來源、寫入成功後回寫 該計畫列「已產生」。 Co-Authored-By: Claude Sonnet 5 --- skills/todo-wiki/SKILL.md | 57 ++++++++++++++++++++++++++------------- 1 file changed, 38 insertions(+), 19 deletions(-) diff --git a/skills/todo-wiki/SKILL.md b/skills/todo-wiki/SKILL.md index 2a3ba98..7597fe6 100644 --- a/skills/todo-wiki/SKILL.md +++ b/skills/todo-wiki/SKILL.md @@ -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 ] [--wiki-repo ] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page <既有頁 title|TODO-->] [--append|--overwrite] [--yes]" +argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-model ] [--wiki-repo ] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page <既有頁 title|TODO__>] [--append|--overwrite] [--yes]" --- # todo-wiki — 需求分析並同步指定模型 TODO 到 Gitea wiki @@ -22,7 +22,7 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode 先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝， 依該 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 特有補充： @@ -35,14 +35,16 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode - **一項一回寫、一項一確認**：每完成一項 checklist，就立刻把該項 `- [ ]` 改成 `- [x]`，立即回寫 wiki，讀回解碼比對成功後才能繼續下一項；不可累積多項後一次回寫。 - 目標 wiki repo 不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。 - 目錄頁 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 頁。系統名稱優先從關聯計畫取得；若沒有關聯計畫，從需求內容尋找或產生系統名稱。 +- 需要加入目錄頁時，目錄標題使用 `{關聯計畫的系統名稱}-代辦`，並連結到 TODO 頁。**系統名稱優先取自使用者於階段 2 選定的計畫列**；若沒有選定計畫，從需求內容尋找或產生系統名稱。 - 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本 TODO 既有列或在既有表格附加新列。 ## 參數 -`[--source <需求描述|檔案路徑|議題編號>] [--impl-model ] [--wiki-repo ] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO--] [--append|--overwrite] [--yes]` +`[--source <需求描述|檔案路徑|議題編號>] [--impl-model ] [--wiki-repo ] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO__] [--append|--overwrite] [--yes]` | 參數 | 說明 | | --- | --- | @@ -51,7 +53,7 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode | `--wiki-repo` | 指定要同步的 Gitea wiki repo，例如 `knowledges/Plan`。 | | `--wiki-index` | wiki 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 | | `--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` 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。 | | `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否關聯到計畫／系統名稱、是否更新 wiki 目錄頁，或對外寫入目標不明等必要決策。 | @@ -65,13 +67,29 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode ## 階段 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` 讀取描述、所有留言、所有附件。 - 都不是 → 視為需求描述本文。 -2. 釐清需求：目標、驗收條件、限制條件、影響範圍任一模糊或缺漏，一律依 `/jsc-shared:spec-ask-user` 詢問使用者。 -3. 產出需求彙整：目標、驗收條件、限制條件，以及本次 wiki todo 頁的 `scope`。 -4. 若來源本身有既有 Markdown checklist，依 `/jsc-shared:spec-todo-list`「盤點既有 TODO」處理：已勾選視為完成不重做，缺漏才補新項目並標「新增」。 +2. 使用者選定計畫時，以該計畫頁的 `path` 讀取計畫頁全文，**計畫頁全文併入需求來源**，並在需求彙整中**標明來源**（哪些需求來自計畫頁、哪些來自 `--source`）；讀取失敗（404 或權限不足）時**讀取失敗即停**——立刻停止並回報，不得改用臆測內容或略過。未選計畫時維持只用 `--source`。 +3. 釐清需求：目標、驗收條件、限制條件、影響範圍任一模糊或缺漏，一律依 `/jsc-shared:spec-ask-user` 詢問使用者。 +4. 產出需求彙整：目標、驗收條件、限制條件，以及本次 wiki todo 頁的 `scope`。 +5. 若來源本身有既有 Markdown checklist，依 `/jsc-shared:spec-todo-list`「盤點既有 TODO」處理：已勾選視為完成不重做，缺漏才補新項目並標「新增」。 ## 階段 3：選實作模型 @@ -126,9 +144,9 @@ scope: <階段 2 產出的 scope> ## 階段 5：讀取既有 wiki 頁並決定寫入策略 1. 依 `spec-gitea` 決定 host 與 token，不輸出 token。 -2. 確認 `--wiki-repo`；缺少就詢問。`--wiki-index` 未帶時固定使用 `CONTENTS`，`--wiki-page` 未帶時先詢問使用者是否要把新的代辦加入既有的 todo 內；只有使用者選擇新建時才固定使用 `TODO-{yyyyMMdd}-{HASH}`。 -3. 詢問使用者三個獨立決策：是否關聯到計畫／系統名稱、是否把新的代辦加入既有的 todo 內，以及是否更新 wiki 目錄頁。使用者回答不加入計畫時，仍預設會更新目錄頁；只有使用者明確回答不要更新目錄頁，才可記錄為「不更新目錄頁」。使用者若明確選既有 todo 頁，該頁就是本次寫入目標，不得自行改成新頁。 -4. 分頁讀取 `GET /repos///wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若使用者選擇既有 todo 頁，直接以該頁 title 對應 `sub_url`；若目錄頁更新決策為開啟，也取得目錄頁 `sub_url`。目錄頁不存在時才建立；目錄頁存在時必須讀取原內容並保留，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。 +2. `--wiki-repo` 與目錄頁內容**沿用階段 2-0 的結果**，不重複讀取；`--wiki-index` 未帶時固定使用 `CONTENTS`，`--wiki-page` 未帶時先詢問使用者是否要把新的代辦加入既有的 todo 內；只有使用者選擇新建時才固定使用 `TODO_{yyyyMMdd}_{HASH}`。 +3. 詢問使用者三個獨立決策：是否關聯到計畫／系統名稱（已於階段 2「選擇尚未產生代辦的計畫」問過則不重問）、是否把新的代辦加入既有的 todo 內，以及是否更新 wiki 目錄頁。使用者回答不加入計畫時，仍預設會更新目錄頁；只有使用者明確回答不要更新目錄頁，才可記錄為「不更新目錄頁」。使用者若明確選既有 todo 頁，該頁就是本次寫入目標，不得自行改成新頁。 +4. 分頁讀取 `GET /repos///wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若使用者選擇既有 todo 頁，直接以該頁 title 對應 `sub_url`。目錄頁的 `sub_url`／內容沿用階段 2-0 已讀取的結果；目錄頁不存在時才建立；目錄頁存在時必須保留原內容，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。 5. 讀取既有 todo 頁；若不存在，策略為「建立」。 6. 既有 todo 頁存在時解析 frontmatter： @@ -146,17 +164,18 @@ scope: <階段 2 產出的 scope> 同步順序固定： 1. 寫入 todo 頁。 -2. 若使用者明確表示不要更新目錄頁，跳過目錄頁更新；否則 upsert 目錄頁表格列。目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。 -3. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認。讀回時若回應含 `content_base64`，必須 base64 解碼後再比對 Markdown 內容是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。 -4. 一項一回寫、一項一確認；若任一步失敗，立刻停止，不得把多個 checklist 累積後一起處理。 +2. 若使用者明確表示不要更新目錄頁，跳過目錄頁更新；否則 upsert 目錄頁表格列（TODO 列）。目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。 +3. 若本次於階段 2「選擇尚未產生代辦的計畫」關聯到某個計畫列，回目錄頁把該計畫列「已產生」由 `[ ]` 改為 `[x]` 並讀回確認；找不到對應計畫列時**不得新建該列**，改以警告回報。未關聯計畫時跳過本步驟。 +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 -| [<關聯計畫的系統名稱>-代辦]() | todo wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 | +| [<關聯計畫的系統名稱>-代辦](<查表取得的 path>) | | [ ] | todo wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 | ``` -若既有目錄頁沒有 `| 頁面 | 內容 |` 表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。 +若既有目錄頁沒有四欄目錄表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。 API 寫入方式：