197 lines
16 KiB
Markdown
197 lines
16 KiB
Markdown
---
|
||
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 TODO-<yyyyMMdd>-<HASH>] [--append|--overwrite] [--yes]"
|
||
---
|
||
|
||
# todo-wiki — 需求分析並同步指定模型 TODO 到 Gitea wiki
|
||
|
||
把「需求 → 分析 → 產生 TODO wiki 頁 → 交給指定模型實作」固定成七個階段。全程不建立本機 `todo.md`、草稿檔、暫存 JSON body 或 wiki clone；唯一輸出位置是指定 Gitea wiki。
|
||
|
||
| 階段 | 做什麼 | 產出 |
|
||
| --- | --- | --- |
|
||
| 1. 選分析模型 | 依 `spec-model`「需求分析」任務取得推薦模型，比對當前模型 | 相符才繼續，不符則停止 |
|
||
| 2. 分析需求 | 讀取來源、釐清不清楚之處 | 需求彙整（目標／驗收條件／限制／`scope`） |
|
||
| 3. 選實作模型 | 依 `spec-model`「依清單實作」任務取得推薦模型，或採用使用者指定 | 實作模型 id／alias／理由 |
|
||
| 4. 產生 TODO wiki 內容 | 依固定格式產生 frontmatter＋強制規則區塊＋checklist | 僅存在於對話記憶中的 Markdown 內容 |
|
||
| 5. 讀取既有 wiki 頁 | 依既有 wiki 頁 frontmatter 決定建立／附加／詢問覆蓋 | 寫入策略 |
|
||
| 6. 同步 Gitea wiki | 寫入 todo 頁並 upsert 目錄頁列 | wiki 目錄頁與 todo 頁 |
|
||
| 7. 交付 | 輸出摘要表格，提醒以哪個模型開新 session 執行 | 面向使用者的總結 |
|
||
|
||
## 共用規範（必要前置）
|
||
|
||
先載入 `/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 特有補充：
|
||
|
||
- **不落地絕對規則**：不得建立或更新本機 `todo.md`、`.md` 草稿、暫存 JSON body、wiki clone、或任何用來傳遞中間成果的檔案；中間成果只存在於對話內容與 Gitea wiki API request body。不得使用 `curl --data @file`。
|
||
- `--source` 指向本機檔案時可以唯讀讀取來源檔；這不是輸出落地。`--source` 指向 Gitea 議題附件時，僅可依 `spec-issue-read` 的附件唯讀暫存例外讀取，讀完立即刪除。
|
||
- 本 skill 產生的 wiki todo 頁就是 `spec-model` 第六節所述「帶 `model:` frontmatter 的清單檔」的源頭；本 skill 只負責產生與同步清單，不執行清單內容。
|
||
- 階段 1 的模型檢查針對「執行本 skill 分析工作的 agent 自己」；階段 3 選出的實作模型是寫進 wiki 頁給未來另一個 session 用。
|
||
- **模型鎖定要在開工前完成**：在讀取任何來源、做任何分析、或接觸 wiki 前，先確認目前執行本 skill 的模型 id；無法確定時先請使用者執行 `/status`，不得用猜的。
|
||
- **一項一回寫、一項一確認**：每完成一項 checklist，就立刻把該項 `- [ ]` 改成 `- [x]`，立即回寫 wiki，讀回解碼比對成功後才能繼續下一項；不可累積多項後一次回寫。
|
||
- 目標 wiki repo 不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。
|
||
- 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--wiki-index` 時才覆蓋預設值。
|
||
- TODO 頁 title 預設固定為 `TODO-{yyyyMMdd}-{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由需求彙整、關聯計畫或系統名稱產生穩定短雜湊並轉成全大寫。
|
||
- 必須詢問使用者兩個獨立決策：是否關聯到計畫／系統名稱，以及是否更新 wiki 目錄頁；使用者回答不加入計畫時，仍預設更新 wiki 目錄頁，除非使用者另行明確說不要更新目錄頁。
|
||
- 需要加入目錄頁時，目錄標題使用 `{關聯計畫的系統名稱}-代辦`，並連結到 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），跳過階段 3 的推薦流程；仍會在 `model_reason` 註明「使用者指定」。 |
|
||
| `--wiki-repo` | 指定要同步的 Gitea wiki repo，例如 `knowledges/Plan`。 |
|
||
| `--wiki-index` | wiki 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 |
|
||
| `--wiki-project` | 關聯計畫或系統名稱；預設仍會更新目錄頁，只有使用者明確表示不要更新目錄頁時才可略過。 |
|
||
| `--wiki-page` | todo 頁 title；未帶時固定使用 `TODO-{yyyyMMdd}-{HASH}`，不詢問。 |
|
||
| `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。 |
|
||
| `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否關聯到計畫／系統名稱、是否更新 wiki 目錄頁，或對外寫入目標不明等必要決策。 |
|
||
|
||
## 階段 1：選分析模型
|
||
|
||
1. 在讀取任何來源、做任何分析、或接觸 wiki 前，先依 `/jsc-shared:spec-model` 第三節取得可用模型清單與標籤，並確認目前執行本 skill 的模型 id。
|
||
2. 依「需求分析／拆 TODO／架構決策」任務列比對必要標籤 `#深度推理` `#分析` `#本機可用`，選出推薦模型。
|
||
3. 若當前執行本 skill 的模型 id 無法確定，先請使用者執行 `/status`，不得用猜的。
|
||
4. 當前模型不符時，依 `spec-model` 第五節格式停止並要求使用者切換；開始任何實作前就要檢查，不得先做階段 2 分析、不得讀取來源、不得接觸 wiki。
|
||
5. 相符時記錄此模型 id 供階段 4 的 `analyzed_by` 使用。
|
||
|
||
## 階段 2：分析需求
|
||
|
||
1. 判斷來源型態：
|
||
- 對應到本機可讀取的檔案路徑 → 視為檔案，唯讀讀取全文，不寫任何衍生檔。
|
||
- 純數字、`#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」處理：已勾選視為完成不重做，缺漏才補新項目並標「新增」。
|
||
|
||
## 階段 3：選實作模型
|
||
|
||
1. `--impl-model` 有帶時，以使用者指定為準；盡可能驗證其存在性與可用性，無法驗證也不得拒絕，改在 `model_reason` 註明未能於本機驗證。
|
||
2. 未指定時，依 `/jsc-shared:spec-model`「依清單實作／規格落地」任務列比對必要標籤 `#均衡實作` `#實作` `#本機可用`，選出推薦模型。
|
||
3. 記下最終 `model`、`model_alias`、`model_reason`。
|
||
|
||
## 階段 4：產生 TODO wiki 內容
|
||
|
||
產生 Markdown 內容但不得寫入本機檔案。
|
||
|
||
### frontmatter
|
||
|
||
```yaml
|
||
---
|
||
model: <實作模型 id>
|
||
model_alias: <實作模型 alias，若無 alias 則省略此欄>
|
||
model_reason: <階段 3 產出的理由>
|
||
analyzed_by: <階段 1 確認的分析模型 id>
|
||
analyzed_at: <yyyy/MM/dd HH:mm:ss，Asia/Taipei>
|
||
scope: <階段 2 產出的 scope>
|
||
---
|
||
```
|
||
|
||
### 強制規則區塊
|
||
|
||
固定加入：
|
||
|
||
```markdown
|
||
## 0. 給執行本清單 Agent 的強制規則（先讀完再動手）
|
||
|
||
| 規則 | 內容 |
|
||
| --- | --- |
|
||
| **模型鎖定** | 本頁 frontmatter 的 `model` 是**強制**的，不是建議。開工前先自我確認當前模型 id。 |
|
||
| **不符就停** | 當前模型 ≠ `<model>` 時，**立刻停止、不做任何檔案修改或 wiki 修改**，輸出下方錯誤訊息並要求使用者切換。開始任何實作前就要檢查，不可先讀來源或接觸 wiki。 |
|
||
| **不得自行升降級** | 不可以「先用手上的模型做一點」、不可以自行判定「我這顆更強所以沒關係」。降級與升級同樣禁止。 |
|
||
| **附加不覆蓋** | 若之後要往本頁追加新需求：`model` 相同 → 附加到頁面末尾；`model` 不同 → 先問使用者是否覆蓋，未得同意不得寫入。 |
|
||
| **完成即勾選** | 每完成一項就地把該行的 `- [ ]` 改成 `- [x]`，並在行末附上「（完成：yyyy/MM/dd HH:mm:ss）」（Asia/Taipei）。不得留待多項一起補勾。 |
|
||
| **更新後才能繼續** | 每完成一項後，必須立即把勾選狀態寫回本 wiki 頁並讀回解碼比對成功；若 wiki 更新失敗、讀回失敗或內容不一致，**立刻停止，不得繼續執行下一項**。 |
|
||
|
||
[<yyyy/MM/dd HH:mm:ss>][模型檢查][ERR]: 本清單指定 <model>（<alias>），當前模型為 <current-model-id>。
|
||
請執行 /model <alias> 切換後重新載入本 wiki 頁，本次不進行任何修改。
|
||
```
|
||
|
||
### checklist
|
||
|
||
- 逐項使用 `- [ ] **編號 短標題**：具體內容`。
|
||
- 內容需動詞＋對象＋驗收條件齊備，並能舉證對應 `path:line` 或需求彙整中的哪一句。
|
||
- 依影響範圍由小到大排序；範圍相同時前置依賴排前面。
|
||
- 不得加入需求來源未提及、也無法合理推得的項目；有疑慮者標「需人工確認」。
|
||
|
||
## 階段 5：讀取既有 wiki 頁並決定寫入策略
|
||
|
||
1. 依 `spec-gitea` 決定 host 與 token，不輸出 token。
|
||
2. 確認 `--wiki-repo`；缺少就詢問。`--wiki-index` 未帶時固定使用 `CONTENTS`，`--wiki-page` 未帶時固定使用 `TODO-{yyyyMMdd}-{HASH}`。
|
||
3. 詢問使用者兩個獨立決策：是否關聯到計畫／系統名稱，以及是否更新 wiki 目錄頁。使用者回答不加入計畫時，仍預設會更新目錄頁；只有使用者明確回答不要更新目錄頁，才可記錄為「不更新目錄頁」。
|
||
4. 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若目錄頁更新決策為開啟，也取得目錄頁 `sub_url`。目錄頁不存在時才建立；目錄頁存在時必須讀取原內容並保留，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。
|
||
5. 讀取既有 todo 頁；若不存在，策略為「建立」。
|
||
6. 既有 todo 頁存在時解析 frontmatter：
|
||
|
||
| 狀況 | 動作 |
|
||
| --- | --- |
|
||
| 頁面不存在 | 建立新 todo 頁。 |
|
||
| 頁面存在且 frontmatter `model` 相同 | 附加到頁面最後：加 `---` 分隔與 `## 追加（<yyyy/MM/dd HH:mm:ss>）` 標題，接新的 checklist 項目；frontmatter 只更新 `analyzed_at`。 |
|
||
| 頁面存在且 frontmatter `model` 不同 | 停下來詢問使用者是否覆蓋、沿用舊模型附加、或取消；未得同意不得寫入。 |
|
||
| 頁面存在但沒有 frontmatter | 視為不同模型處理。 |
|
||
|
||
`--append`／`--overwrite` 已明確回答不同模型分支時，依該旗標執行；`--yes` 不算回答。
|
||
|
||
## 階段 6：同步 Gitea wiki
|
||
|
||
同步順序固定：
|
||
|
||
1. 寫入 todo 頁。
|
||
2. 若使用者明確表示不要更新目錄頁，跳過目錄頁更新；否則 upsert 目錄頁表格列。目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。
|
||
3. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認。讀回時若回應含 `content_base64`，必須 base64 解碼後再比對 Markdown 內容是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。
|
||
4. 一項一回寫、一項一確認；若任一步失敗，立刻停止，不得把多個 checklist 累積後一起處理。
|
||
|
||
目錄頁表格列格式：
|
||
|
||
```markdown
|
||
| [<關聯計畫的系統名稱>-代辦](<todo page title percent-encoded>) | todo wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |
|
||
```
|
||
|
||
若既有目錄頁沒有 `| 頁面 | 內容 |` 表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。
|
||
|
||
API 寫入方式：
|
||
|
||
- 建立新頁：`POST /repos/<owner>/<repo>/wiki/new`，body 帶 `title`、`content_base64`、`message`。
|
||
- 更新既有頁：先查表取得 `sub_url`，再用 `PATCH /repos/<owner>/<repo>/wiki/page/<sub_url>`，body 帶 `title`、`content_base64`、`message`。
|
||
- `content_base64` 的值必須是 wiki Markdown 內容以 UTF-8 編碼後再 base64 編碼的結果；`title`、`message` 與其他原有欄位行為不變。
|
||
- request body 必須由工具呼叫、stdin、shell 變數或記憶中內容直接送出，不得先寫成本機 JSON 或 Markdown 檔。
|
||
|
||
不得自行猜測 Gitea wiki title 到 `sub_url` 的轉義規則；找既有頁一律查表。若 REST wiki 寫入端點不可用，回報「此站台不支援不落地 wiki 寫入」並停止，不得改用 wiki git clone。
|
||
|
||
## 階段 7：交付
|
||
|
||
輸出摘要表格：
|
||
|
||
| 項目 | 內容 |
|
||
| --- | --- |
|
||
| 分析模型 | `analyzed_by` |
|
||
| 實作模型 | `model` / `model_alias`，並註明推薦或使用者指定 |
|
||
| 已完成項目數 | 本次實際完成且已回寫確認的 checklist 項目數 |
|
||
| Wiki repo | `<owner/repo>` |
|
||
| 目錄頁 | URL；若使用者明確不要更新目錄頁，填「未更新（使用者選擇不更新目錄頁）」 |
|
||
| Todo 頁 | URL |
|
||
| 本次動作 | 建立／附加／覆蓋 |
|
||
| 已回寫確認 | `是`／`否`，僅在所有本次 checklist 都完成且讀回比對成功時填 `是` |
|
||
|
||
最後提醒：
|
||
|
||
> 請以 `<alias>`（找不到 alias 時用完整 id）模型開新 session 執行本 wiki 頁：`<todo page URL>`。
|
||
|
||
## 呼叫方式
|
||
|
||
依 `/jsc-shared:spec-skill-invocation` 的統一呼叫方式，本 skill 的實際參數格式與範例：
|
||
|
||
| 助理 | 呼叫 |
|
||
| --- | --- |
|
||
| 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，不要落地檔案」）自動觸發 |
|