170 lines
10 KiB
Markdown
170 lines
10 KiB
Markdown
---
|
||
name: plan-wiki
|
||
description: 逐步詢問使用者計畫內容，並把每一輪已確認的計畫草稿直接同步到指定 Gitea wiki 的目錄頁與計畫頁，全程不建立本機計畫檔、草稿檔、暫存 JSON body 或 wiki clone。使用者要建立計畫、把計畫加入 wiki 目錄、指定 Gitea wiki repo／目錄頁／計畫頁、要求邊問邊同步 wiki、要求計畫檔案不落地、或提到 plan-wiki、計畫 wiki、wiki 目錄頁時觸發。適用於：需求尚未完整、需要逐題釐清並保存到 wiki 的計畫文件。不適用於：產生本機 plan.md／todo.md、拆 Gitea issue（用 /jsc-doc:issues-analyze）、或非 Gitea wiki。
|
||
argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN-<yyyyMMdd>-<HASH>] [--host <gitea主機>] [--yes]"
|
||
---
|
||
|
||
# plan-wiki — 逐步建立計畫並同步到 Gitea wiki
|
||
|
||
把「逐步詢問 → 彙整計畫 → 同步 wiki 目錄與頁面 → 繼續詢問」固定成可重複流程。每次使用者回答一輪問題後，都必須把目前已確認內容同步到 Gitea wiki，直到使用者明確表示計畫完成；全程不建立本機計畫檔或草稿檔。
|
||
|
||
| 階段 | 動作 |
|
||
| --- | --- |
|
||
| A. 前置設定 | 確認 Gitea host、token、wiki repo、目錄頁、計畫名稱與計畫頁 |
|
||
| B. 讀取 wiki 現況 | 讀取目錄頁與計畫頁，保留既有內容 |
|
||
| C. 逐步詢問 | 每輪只問 1～3 個必要問題，使用者回答後整理計畫草稿 |
|
||
| D. 同步 wiki | 每輪都更新目錄頁與計畫頁 |
|
||
| E. 完成收斂 | 使用者確認計畫完成後輸出 wiki 連結與摘要 |
|
||
|
||
## 共用規範（必要前置）
|
||
|
||
先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝，
|
||
依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。
|
||
本 skill 需要的規範：`spec-output`、`spec-execution`、`spec-gitea`、`spec-ask-user`、`spec-time-log`、`spec-no-scratch-files`、`spec-skill-invocation`
|
||
|
||
本 skill 特有補充：
|
||
|
||
- 本 skill 會寫入外部 Gitea wiki；目標 wiki repo 不明時必須詢問，不得臆測。
|
||
- 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--index` 時才覆蓋預設值。
|
||
- 計畫頁 title 預設固定為 `PLAN-{yyyyMMdd}-{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由已確認的計畫內容、計畫名稱或需求摘要產生穩定短雜湊並轉成全大寫。
|
||
- 加入目錄頁時，先從計畫內容尋找系統名稱；若無明確系統名稱，依計畫目標產生一個精簡系統名稱。目錄標題使用 `{系統名稱}-計畫`，並連結到計畫頁。
|
||
- 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本計畫既有列或在既有表格附加新列。
|
||
- **不落地絕對規則**：不得建立本機 `plan.md`、`todo.md`、`.md` 草稿、暫存 JSON body、wiki clone、或任何用來傳遞中間成果的檔案；中間成果只存在於對話內容與 Gitea wiki API request body。不得使用 `curl --data @file`。
|
||
- 使用者已用參數指定 `--wiki-repo`、`--index`、`--project`、`--page` 時跳過對應詢問。
|
||
- 每一輪使用者回答後都要同步 wiki；一輪一同步、一輪一確認，不可累積多輪回答後一次送出。同步失敗、讀回失敗或比對不一致時，停止下一輪詢問，先回報錯誤與待使用者處理的點。
|
||
- 只有階段 D 的 wiki 同步完成且讀回確認成功後，才能進入下一輪提問。
|
||
- 不要求使用者把 token 貼進對話；token 依 `spec-gitea` 從環境變數或既有設定取得。
|
||
|
||
## 參數
|
||
|
||
`[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN-<yyyyMMdd>-<HASH>] [--host <gitea主機>] [--yes]`
|
||
|
||
| 參數 | 說明 |
|
||
| --- | --- |
|
||
| `--wiki-repo` | Gitea wiki 所屬 repo，例如 `knowledges/Plan`。未帶且無法從目前 repo 推得時詢問使用者。 |
|
||
| `--index` | 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 |
|
||
| `--project` | 計畫名稱；未帶時從計畫內容尋找或產生系統名稱，用於目錄列標題與摘要。 |
|
||
| `--page` | 計畫頁 title；未帶時固定使用 `PLAN-{yyyyMMdd}-{HASH}`，不詢問。 |
|
||
| `--host` | Gitea 主機，依 `spec-gitea` host 決定順序處理。 |
|
||
| `--yes` | 略過一般性確認；不得略過目標 wiki 不明、寫入衝突、同步失敗後的停止，或使用者尚未確認的計畫完成判斷。 |
|
||
|
||
## 階段 A：前置設定
|
||
|
||
1. 依 `spec-gitea` 決定 host 與 token，只輸出 token「已設定／未設定」。
|
||
2. 確認 `--wiki-repo` 是否為 `owner/repo` 格式；不符合時詢問使用者修正。
|
||
3. 確認目錄頁 title：未帶 `--index` 時固定使用 `CONTENTS`。
|
||
4. 確認計畫頁 title：未帶 `--page` 時固定使用 `PLAN-{yyyyMMdd}-{HASH}`。雜湊輸入優先使用已確認的計畫內容；內容不足時使用計畫名稱、來源摘要與當輪時間組合，輸出全大寫短雜湊。
|
||
5. 確認系統名稱：先從 `--project`、計畫內容、需求來源或使用者回答尋找明確系統名稱；找不到時產生精簡系統名稱，不為此單獨詢問。
|
||
6. 用 `GET /repos/<owner>/<repo>` 驗證 token 對 repo 有權限；失敗時遮蔽機密後回報並停止。
|
||
|
||
## 階段 B：讀取 wiki 現況
|
||
|
||
1. 依 `spec-gitea` 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`。
|
||
2. 以 title 查表取得目錄頁與計畫頁的 `sub_url`，不得自行猜測轉義規則。
|
||
3. 讀取頁面：`GET /repos/<owner>/<repo>/wiki/page/<sub_url>`，將 `content_base64` 解成 UTF-8 Markdown。
|
||
4. 目錄頁不存在時在記憶中組出符合「目錄頁格式」的新頁內容；目錄頁存在時不得用預設格式覆蓋整頁，只能保留原內容後修改或附加本計畫目錄列。計畫頁不存在時在記憶中組出目前計畫草稿。不得先寫成本機檔案。
|
||
|
||
## 目錄頁格式
|
||
|
||
目錄頁不存在時建立下列結構；更新既有目錄頁時禁止整頁覆蓋，必須保留既有標題、說明、表格與其他內容，只新增或更新本計畫相關列：
|
||
|
||
```markdown
|
||
# CONTENTS
|
||
|
||
計畫目錄。
|
||
|
||
| 頁面 | 內容 |
|
||
|------|------|
|
||
| [<系統名稱>-計畫](<page title percent-encoded, 空白用 %20>) | plan wiki：<系統名稱> 計畫 |
|
||
|
||
產出日期：yyyy-MM-dd
|
||
```
|
||
|
||
若目錄頁已存在且不是單一計畫專用目錄，仍以同一張 `| 頁面 | 內容 |` 表格為準：保留原標題與說明，只在表格中 upsert 本計畫頁面列。若既有目錄頁沒有 `| 頁面 | 內容 |` 表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。連結文字固定為 `<系統名稱>-計畫`；連結 target 用 `encodeURIComponent(title).replace(/%20/g, "%20")` 的結果，不使用 API `sub_url` 反推人工連結。
|
||
|
||
## 計畫頁格式
|
||
|
||
計畫頁使用 Markdown，至少包含：
|
||
|
||
```markdown
|
||
# <page title>
|
||
|
||
## 目標
|
||
|
||
## 背景與限制
|
||
|
||
## 範圍
|
||
|
||
## 方案
|
||
|
||
## 待確認
|
||
|
||
## TODO
|
||
- [ ] ...
|
||
```
|
||
|
||
已有計畫頁時保留使用者明確保留的內容；每輪只更新本 skill 管理的章節。需求不明的部分放在 `## 待確認`，不得自行補完。
|
||
|
||
## 階段 C：逐步詢問
|
||
|
||
每輪最多問 1～3 個問題，問題必須能推進計畫內容。建議順序：
|
||
|
||
1. 計畫目標與成功標準。
|
||
2. 使用者、情境、限制條件。
|
||
3. 功能範圍與明確不做的範圍。
|
||
4. 方案拆解、資料流、外部依賴。
|
||
5. 里程碑、驗收項目、風險與待確認。
|
||
|
||
每輪回答後：
|
||
|
||
- 將回答整合進計畫頁。
|
||
- 把仍不明確的點列入 `## 待確認`。
|
||
- 產出或更新 `## TODO` checklist，格式依 `spec-todo-list`。
|
||
- 詢問使用者下一輪問題前，先完成階段 D 的 wiki 同步。
|
||
- 如果某輪資料不足，先把不確定內容放進 `## 待確認`，不得自行補完再繼續問下一輪。
|
||
|
||
使用者明確表示「完成」「先到這裡」「計畫完成」時，進入階段 E；不要再追問非必要細節。
|
||
|
||
## 階段 D：同步 wiki
|
||
|
||
每輪同步順序固定：
|
||
|
||
1. 更新計畫頁。
|
||
2. 更新目錄頁：不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<系統名稱>-計畫` 列，或在既有表格／頁末附加新列，確保有本計畫頁連結與摘要。
|
||
3. 再次讀回兩個頁面確認內容已更新。讀回時若回應含 `content_base64`，必須 base64 解碼後比對正文 Markdown 是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。
|
||
4. 每輪只允許一輪同步結果對應下一輪提問；若 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 必須由工具呼叫或記憶中內容直接送出，不得先寫成本機 JSON 或 Markdown 檔。
|
||
- message 用繁體中文，例如 `更新 <page title>`。
|
||
|
||
若站台不支援 REST wiki 寫入端點，回報「此站台不支援不落地 wiki 寫入」並停止，不得改用 wiki git clone。
|
||
|
||
## 階段 E：完成收斂
|
||
|
||
輸出摘要表格：
|
||
|
||
| 項目 | 內容 |
|
||
| --- | --- |
|
||
| Wiki repo | `<owner/repo>` |
|
||
| 目錄頁 | `<index title>` |
|
||
| 計畫頁 | `<page title>` |
|
||
| 同步次數 | 本輪實際寫入次數 |
|
||
| 待確認 | `## 待確認` 剩餘項目數 |
|
||
|
||
最後附上目錄頁與計畫頁 URL。
|
||
|
||
## 呼叫方式
|
||
|
||
依 `/jsc-shared:spec-skill-invocation` 的統一呼叫方式，本 skill 的實際參數格式與範例：
|
||
|
||
| 助理 | 呼叫 |
|
||
| --- | --- |
|
||
| Claude Code / Antigravity | `/jsc-shared:plan-wiki --wiki-repo knowledges/Plan --project Kokorone` |
|
||
| Codex | `$plan-wiki --wiki-repo knowledges/Plan --project Kokorone` |
|
||
| OpenCode | 描述需求（如「逐步問我計畫內容，並同步到 Gitea wiki 目錄與頁面」）自動觸發 |
|