jiantw83andClaude Sonnet 5
2329e4d709
新增 spec-version-guard 規範（定義遠端發佈版本 vs 當前實際載入版本的比對規則、 fail-closed、錯誤訊息格式）與 scripts/version-guard.mjs（hook／CLI 雙模式， hook 模式輸出 Claude Code/Copilot 相容的 PreToolUse deny JSON）；spec-preflight 的載入順序補上版本檢查第 0 步；新增 hooks/hooks.json 掛 PreToolUse； do-wiki/models/plan-wiki/plugins-uninstall/todo-wiki 五個 skill 檔頭引用新規範 （plugins-install 刻意排除，避免版本落後時擋住自己的修復手段）。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
92 lines
9.1 KiB
Markdown
92 lines
9.1 KiB
Markdown
---
|
||
name: do-wiki
|
||
description: 讀取 `todo-wiki` 產生、帶鎖定模型 frontmatter 的 Gitea wiki TODO 頁並逐項執行：開工前先讀目錄頁挑一份「已完成」為未勾選的代辦（沒有就直接結束）；檢查頁面 `## 0.` 的六條強制規則並比對當前模型，不符就停止；讀取需求彙整與既有 checklist（已勾選視為完成不重做）；逐項執行——完成一項就地把 `- [ ]` 改 `- [x]` 並補上完成時間，立即回寫該 wiki 頁並讀回確認成功才能繼續下一項，任一步失敗立刻停止；全部項目完成後回目錄頁把該代辦列「已完成」改為 `[x]`。當使用者說要執行 wiki TODO、跑 do-wiki、依 wiki 清單實作、接手某份 Gitea wiki 代辦、或提到 do-wiki skill 時觸發。不適用於：把需求分析並產生 TODO 清單同步到 wiki（用 `/jsc-shared:todo-wiki`）、逐步建立計畫並同步 wiki（用 `/jsc-shared:plan-wiki`）。
|
||
argument-hint: "[--wiki-repo <owner/repo>] [--wiki-index CONTENTS] [--wiki-page <既有 TODO 頁 title>] [--yes]"
|
||
---
|
||
|
||
# do-wiki — 讀取並執行指定模型 Gitea wiki TODO 頁
|
||
|
||
把「挑代辦 → 讀取 TODO 頁 → 檢查強制規則 → 了解需求彙整 → 逐項執行並即時回寫」固定成五個階段。`do-wiki` 是 `todo-wiki` 的執行端對應物：`todo-wiki` 產生鎖定模型的 wiki TODO 清單，`do-wiki` 讀取並執行該清單。
|
||
|
||
| 階段 | 做什麼 | 產出 |
|
||
| --- | --- | --- |
|
||
| 0. 挑代辦 | 讀目錄頁列出所有未完成的 TODO 列，單選一份 | 本次執行目標的 TODO 頁 `path` |
|
||
| 1. 讀取目標 TODO 頁 | 查表取得 `path` 並讀取內容 | TODO 頁完整 Markdown |
|
||
| 2. 檢查強制規則 | 解析 `## 0.` 區塊六條規則，比對當前模型 | 相符才繼續，不符則停止 |
|
||
| 3. 了解需求彙整 | 讀 frontmatter `scope` 與需求段落，盤點既有 checklist | 待執行項目清單 |
|
||
| 4. 逐項執行並即時回寫 | 單項循環：執行 → 勾選 → 回寫 → 讀回確認 | 全部項目完成的 TODO 頁 |
|
||
| 收尾 | 回目錄頁把該代辦列「已完成」改 `[x]` | 讀回確認成功的目錄頁 |
|
||
|
||
## 共用規範（必要前置）
|
||
|
||
先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝，
|
||
依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。
|
||
本 skill 需要的規範：`spec-version-guard`、`spec-model`、`spec-output`、`spec-execution`、`spec-todo-list`、`spec-ask-user`、`spec-time-log`、`spec-gitea`、`spec-wiki-contents`、`spec-no-scratch-files`、`spec-skill-invocation`
|
||
|
||
## 參數
|
||
|
||
`[--wiki-repo <owner/repo>] [--wiki-index CONTENTS] [--wiki-page <既有 TODO 頁 title>] [--yes]`
|
||
|
||
| 參數 | 說明 |
|
||
| --- | --- |
|
||
| `--wiki-repo` | 指定要讀取的 Gitea wiki repo，例如 `knowledges/Plan`。未帶時依 `spec-ask-user` 詢問，不臆測。 |
|
||
| `--wiki-index` | 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 |
|
||
| `--wiki-page` | 直接指定既有 TODO 頁 title；有帶時跳過階段 0 的挑選詢問，直接查表取得對應 `path` 進入階段 1。 |
|
||
| `--yes` | 略過一般性確認；不得略過模型不符、目標 wiki 不明、或 wiki 回寫／讀回失敗後的停止。 |
|
||
|
||
## 階段 0：從目錄頁挑一份未完成代辦
|
||
|
||
1. 依 `spec-gitea` 決定 host 與 token；確認 `--wiki-repo`，缺少就詢問使用者，不臆測。
|
||
2. `--wiki-page` 已帶（或使用者已於對話明確指定頁面）時，依 `spec-ask-user`「已知答案時跳過詢問」直接查表取得該 title 對應的 `path`，跳過本階段其餘步驟進入階段 1；只有查表找不到該 title 時，才回頭走本階段清單並提示原指定值無效，不得臆測頁面。
|
||
3. 依 `spec-gitea` 分頁查表讀取目錄頁（title 預設 `CONTENTS`，或 `--wiki-index` 指定值），依 `spec-wiki-contents`〔目錄頁格式〕掃描**所有系統的 `## ` 段落**，取出每個段落中所有「`代辦`欄非空、`是否已完成`為 `[ ]`」的列，記下其所屬系統（該段落標題）供候選標示用。
|
||
4. **沒有未完成代辦就直接結束**：目錄頁不存在、目錄頁沒有任何系統段落、或所有段落的候選列皆為空，一律輸出 `[yyyy/MM/dd HH:mm:ss][代辦盤點][INF]: 目錄頁沒有未完成的代辦，本次不進行任何修改。` 後結束，不讀取任何 TODO 頁、不修改任何檔案或 wiki。
|
||
5. 有未完成代辦時，依 `spec-ask-user` 以**單選**呈現，候選標示為「{系統名稱}：{代辦內容摘要}」（候選 ≤4 用 `AskUserQuestion` 並含「其他」，>4 改文字編號列出）；選定列`代辦`欄連結的 `path` 直接作為階段 1 的讀取目標，不得再自行推導轉義。
|
||
|
||
## 階段 1：讀取目標 TODO 頁
|
||
|
||
1. 若階段 0 尚未取得 `path`，依 `spec-gitea`〔Wiki 頁名轉義規則〕規則 2，以 `tea wiki list --repo <owner>/<repo> --fields title,path`（或對應 REST API）**分頁完整查表**，用 title 比對取得 `path`；明文禁止自行推導 title 到 `path` 的轉義規則。
|
||
2. 以 `tea wiki view`（或 `GET /repos/<owner>/<repo>/wiki/page/<path>`）讀取該頁完整內容。
|
||
3. `--wiki-page` 未帶、階段 0 也未能決定目標頁時，依 `spec-ask-user` 詢問使用者，不臆測。
|
||
|
||
## 階段 2：檢查強制規則
|
||
|
||
1. 解析頁面 `## 0. 給執行本清單 Agent 的強制規則` 區塊列出的六條規則：**模型鎖定**、**不符就停**、**不得自行升降級**、**附加不覆蓋**、**完成即勾選**、**更新後才能繼續**；六條規則對本次執行全程有效，不只在本階段生效。
|
||
2. 依 `spec-model` 第六節，讀出 frontmatter 的 `model`（與可能並列的 `model_alias`），並依同節方式確認當前模型（agent 自我回報，不確定就請使用者 `/status` 確認）。
|
||
3. 兩者不符 → 依 `[yyyy/MM/dd HH:mm:ss][模型檢查][ERR]:` 格式停止，本次不做任何檔案修改或 wiki 修改，要求使用者切換模型後重新載入本 wiki 頁。
|
||
4. 相符才繼續往下執行；不得自行降級或升級到別的模型頂替，也不得「先做一部分」再提醒。
|
||
|
||
## 階段 3：了解需求彙整
|
||
|
||
1. 讀取 frontmatter `scope` 與頁面「需求彙整」段落（含所有〔追加〕段落的「需求彙整（追加）」），作為理解本次待執行工作的背景。
|
||
2. 依 `spec-todo-list`「盤點既有 TODO」處理頁面內的 checklist：**已勾選（`- [x]`）視為已完成不重做**，只執行未勾選（`- [ ]`）項目；依影響範圍由小到大、以及頁面既有順序處理。
|
||
|
||
## 不落地邊界
|
||
|
||
- **do-wiki 執行期的中間成果不得落地**：進度摘要、待辦排序、分析過程只留在對話內容，不得寫成本機草稿檔、暫存 JSON、或任何用來傳遞中間成果的檔案；不得 clone wiki repo；request body 一律由工具呼叫或記憶內容直接送出，不得用 `@file` 形式。
|
||
- **清單項目本身要求新增或修改的專案原始碼屬正常產出**：若某個 checklist 項目的實作方式就是「新增／修改某個檔案」，直接依該項目要求編輯專案內的原始碼、文件或設定檔，這不算落地限制的例外，是該項目的正常交付物。
|
||
|
||
## 階段 4：逐項執行並即時回寫
|
||
|
||
依序處理階段 3 篩選出的每一個未勾選項目，單項循環固定四步，**任一步失敗立刻停止，不得執行下一項；不得多項一起補勾**：
|
||
|
||
1. **執行**：依該項目的實作方式與驗收條件完成工作（可能是編輯專案檔案、可能是純分析）。
|
||
2. **就地勾選**：把該行 `- [ ]` 改成 `- [x]`，並在行末附上「（完成：`yyyy/MM/dd HH:mm:ss`）」（Asia/Taipei）。
|
||
3. **回寫 wiki**：以 `tea wiki edit`（或 `PATCH /repos/<owner>/<repo>/wiki/page/<path>`）寫回整份頁面內容。**`tea wiki edit` 陷阱**：其用法為 `tea wiki edit [options] <page>`，`<page>` 需帶 `path`；若省略 `--title`，tea 會把 `<page>` 當成新 title 送出並導致頁面被改名。**每次呼叫都必須同時帶 `--title`（原 title）與 `--content`（完整內容）**，否則勾選一次就改名一次。
|
||
4. **讀回確認**：重新讀取該頁，確認內容已更新且與預期一致（`content_base64` 需先 base64 解碼再比對）；若回寫或讀回確認失敗，立刻停止，不得繼續下一項。
|
||
|
||
## 收尾：全部完成後回寫目錄頁「已完成」
|
||
|
||
1. 只有本次 TODO 頁**所有**項目皆為 `- [x]` 時才可進行；只要還有未勾項目就不得勾選目錄頁。
|
||
2. 依 `spec-wiki-contents`〔回寫規則〕，回目錄頁把該 TODO 列的「已完成」由 `[ ]` 改為 `[x]`。
|
||
3. 讀回目錄頁確認寫入成功；失敗則停止並回報，不得視為已完成。
|
||
|
||
## 呼叫方式
|
||
|
||
依 `/jsc-shared:spec-skill-invocation` 的統一呼叫方式，本 skill 的實際參數格式與範例：
|
||
|
||
| 助理 | 呼叫 |
|
||
| --- | --- |
|
||
| Claude Code / Antigravity | `/jsc-shared:do-wiki --wiki-repo knowledges/Plan --wiki-page TODO_20260817_EDF7AA` |
|
||
| Codex | `$do-wiki --wiki-repo knowledges/Plan --wiki-page TODO_20260817_EDF7AA` |
|
||
| OpenCode | 描述需求（如「幫我執行 knowledges/Plan 這份 wiki 的代辦」）自動觸發 |
|