docs(wiki skills): 更新計畫與代辦頁預設規則
This commit is contained in:
Codex
+22
-17
@@ -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 <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index <目錄頁title>] [--wiki-project <計畫名稱>] [--wiki-page <todo頁title>] [--append|--overwrite] [--yes]"
|
||||
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
|
||||
@@ -30,22 +30,26 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
|
||||
- `--source` 指向本機檔案時可以唯讀讀取來源檔；這不是輸出落地。`--source` 指向 Gitea 議題附件時，僅可依 `spec-issue-read` 的附件唯讀暫存例外讀取，讀完立即刪除。
|
||||
- 本 skill 產生的 wiki todo 頁就是 `spec-model` 第六節所述「帶 `model:` frontmatter 的清單檔」的源頭；本 skill 只負責產生與同步清單，不執行清單內容。
|
||||
- 階段 1 的模型檢查針對「執行本 skill 分析工作的 agent 自己」；階段 3 選出的實作模型是寫進 wiki 頁給未來另一個 session 用。
|
||||
- 目標 wiki repo、目錄頁、計畫名稱不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。
|
||||
- 目標 wiki repo 不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。
|
||||
- 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--wiki-index` 時才覆蓋預設值。
|
||||
- TODO 頁 title 預設固定為 `TODO-{yyyyMMdd}-{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由需求彙整、關聯計畫或系統名稱產生穩定短雜湊並轉成全大寫。
|
||||
- 必須詢問使用者是否需要把本 TODO 連結到計畫；使用者回答不需要時，不更新目錄頁，也不要把 TODO 加到目錄。
|
||||
- 需要加入目錄頁時，目錄標題使用 `{關聯計畫的系統名稱}-代辦`，並連結到 TODO 頁。系統名稱優先從關聯計畫取得；若沒有關聯計畫，從需求內容尋找或產生系統名稱。
|
||||
|
||||
## 參數
|
||||
|
||||
`[--source <需求描述|檔案路徑|議題編號>] [--impl-model <id|alias>] [--wiki-repo <owner/repo>] [--wiki-index <目錄頁title>] [--wiki-project <計畫名稱>] [--wiki-page <todo頁title>] [--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]`
|
||||
|
||||
| 參數 | 說明 |
|
||||
| --- | --- |
|
||||
| `--source` | 需求來源。未帶時視為必要決策，詢問使用者要用描述／檔案路徑／議題編號哪一種，不得臆測。 |
|
||||
| `--impl-model` | 直接指定實作模型（id 或 alias），跳過階段 3 的推薦流程；仍會在 `model_reason` 註明「使用者指定」。 |
|
||||
| `--wiki-repo` | 指定要同步的 Gitea wiki repo，例如 `knowledges/Plan`。 |
|
||||
| `--wiki-index` | wiki 目錄頁 title，例如 `目錄`。 |
|
||||
| `--wiki-project` | 目錄頁中的計畫名稱，用於目錄頁標題、說明或 upsert 摘要。 |
|
||||
| `--wiki-page` | todo 頁 title；未帶時用 `<wiki-project> 實作清單`，並在同步摘要中明確列出。 |
|
||||
| `--wiki-index` | wiki 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 |
|
||||
| `--wiki-project` | 關聯計畫或系統名稱；需要加入目錄頁時，用於產生 `{關聯計畫的系統名稱}-代辦`。 |
|
||||
| `--wiki-page` | todo 頁 title；未帶時固定使用 `TODO-{yyyyMMdd}-{HASH}`，不詢問。 |
|
||||
| `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。 |
|
||||
| `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、或對外寫入目標不明等必要決策。 |
|
||||
| `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否連結到計畫、或對外寫入目標不明等必要決策。 |
|
||||
|
||||
## 階段 1：選分析模型
|
||||
|
||||
@@ -117,10 +121,11 @@ scope: <階段 2 產出的 scope>
|
||||
## 階段 5：讀取既有 wiki 頁並決定寫入策略
|
||||
|
||||
1. 依 `spec-gitea` 決定 host 與 token，不輸出 token。
|
||||
2. 確認 `--wiki-repo`、`--wiki-index`、`--wiki-project`；缺少就詢問。
|
||||
3. 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`，以 title 查表取得目錄頁與 todo 頁 `sub_url`。
|
||||
4. 讀取既有 todo 頁；若不存在，策略為「建立」。
|
||||
5. 既有 todo 頁存在時解析 frontmatter：
|
||||
2. 確認 `--wiki-repo`；缺少就詢問。`--wiki-index` 未帶時固定使用 `CONTENTS`，`--wiki-page` 未帶時固定使用 `TODO-{yyyyMMdd}-{HASH}`。
|
||||
3. 詢問使用者是否需要把本 TODO 連結到計畫。若不需要，記錄為「不更新目錄頁」；若需要，確認或產生關聯計畫的系統名稱，用於目錄列標題。
|
||||
4. 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若需要連結到計畫，也取得目錄頁 `sub_url`。不得為了找頁面自行猜測 title 轉義規則。
|
||||
5. 讀取既有 todo 頁；若不存在，策略為「建立」。
|
||||
6. 既有 todo 頁存在時解析 frontmatter：
|
||||
|
||||
| 狀況 | 動作 |
|
||||
| --- | --- |
|
||||
@@ -136,13 +141,13 @@ scope: <階段 2 產出的 scope>
|
||||
同步順序固定：
|
||||
|
||||
1. 寫入 todo 頁。
|
||||
2. upsert 目錄頁表格列。
|
||||
3. 讀回兩個頁面確認內容已更新。
|
||||
2. 若使用者確認需要連結到計畫，upsert 目錄頁表格列；若使用者回答不需要，跳過目錄頁更新。
|
||||
3. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認。
|
||||
|
||||
目錄頁表格列格式：
|
||||
|
||||
```markdown
|
||||
| [<todo page title>](<todo page title percent-encoded>) | todo wiki：<wiki-project> 實作清單——執行規則、需求彙整、分群任務與驗收條件 |
|
||||
| [<關聯計畫的系統名稱>-代辦](<todo page title percent-encoded>) | todo wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |
|
||||
```
|
||||
|
||||
API 寫入方式：
|
||||
@@ -163,7 +168,7 @@ API 寫入方式：
|
||||
| 實作模型 | `model` / `model_alias`，並註明推薦或使用者指定 |
|
||||
| 項目數 | 本次新增的 checklist 項目數 |
|
||||
| Wiki repo | `<owner/repo>` |
|
||||
| 目錄頁 | URL |
|
||||
| 目錄頁 | URL；若本次未連結到計畫，填「未更新（使用者選擇不加入目錄）」 |
|
||||
| Todo 頁 | URL |
|
||||
| 本次動作 | 建立／附加／覆蓋 |
|
||||
|
||||
@@ -177,6 +182,6 @@ API 寫入方式：
|
||||
|
||||
| 助理 | 呼叫 |
|
||||
| --- | --- |
|
||||
| Claude Code / Antigravity | `/jsc-shared:todo-wiki --source "把 X 模組改成非同步" --wiki-repo knowledges/Plan --wiki-index 目錄 --wiki-project Kokorone` |
|
||||
| Codex | `$todo-wiki --source ./RFC.md --wiki-repo knowledges/Plan --wiki-index 目錄 --wiki-project Kokorone` |
|
||||
| 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，不要落地檔案」）自動觸發 |
|
||||
|
||||
Reference in New Issue
Block a user