feat(git-safety,model): 分支一律先確認、模型 id 改以 transcript 實際值為準 #13
+1
-1
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "jsc-shared",
|
||||
"shortName": "shared",
|
||||
"version": "0.1.2",
|
||||
"version": "0.1.4",
|
||||
"descriptionCore": "JSC 跨 AI 助理共用規範 skills plugin，`skills/` 為唯一真實來源，並提供整組 plugin 的安裝／更新／移除管理（plugins-install 一次安裝或更新 jsc-code／jsc-doc／jsc-persona／jsc-shared，plugins-uninstall 一次移除四個 JSC plugin）。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準，不依賴既有本機存取庫；所有 skills 以 SKILL.md 為共通標準。",
|
||||
"assistants": ["Claude Code", "Codex", "Antigravity", "OpenCode", "GitHub Copilot CLI"],
|
||||
"cliPrefix": "/jsc-shared:",
|
||||
|
||||
+26
-25
@@ -1,19 +1,19 @@
|
||||
---
|
||||
name: plan-wiki
|
||||
description: 逐步詢問使用者計畫內容，持續釐清到系統規劃所需描述完整後，才把詳細分析同步到指定 Gitea wiki 的目錄頁與計畫頁，全程禁止本機檔案落地，不建立本機計畫檔、草稿檔、暫存 JSON body、附件暫存檔或 wiki clone。使用者要建立計畫、把計畫加入 wiki 目錄、指定 Gitea wiki repo／目錄頁／計畫頁、要求計畫檔案不落地、或提到 plan-wiki、計畫 wiki、wiki 目錄頁時觸發。適用於：需求尚未完整、需要逐題釐清並保存到 wiki 的計畫文件。不適用於：產生本機 plan.md／todo.md、產生代辦事項、拆 Gitea issue（用 /jsc-doc:issues-analyze）、或非 Gitea 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 目錄與頁面」固定成流程。必須一直重複詢問使用者，直到蒐集完系統規劃所需的所有描述；凡有疑問或缺口都要詢問，不得自行幻想。只有描述完整後，才可以把詳細分析寫入計畫頁；全程禁止本機檔案落地。
|
||||
把「逐步詢問 → 彙整計畫 → 同步 wiki 目錄與頁面 → 繼續詢問」固定成可重複流程。每次使用者回答一輪問題後，都必須把目前已確認內容同步到 Gitea wiki，直到使用者明確表示計畫完成；全程不建立本機計畫檔或草稿檔。
|
||||
|
||||
| 階段 | 動作 |
|
||||
| --- | --- |
|
||||
| A. 前置設定 | 確認 Gitea host、token、wiki repo、目錄頁、計畫名稱與計畫頁 |
|
||||
| B. 讀取 wiki 現況 | 讀取目錄頁與計畫頁，保留既有內容 |
|
||||
| C. 逐步詢問 | 每輪只問 1～3 個必要問題，使用者回答後判斷是否仍有疑問 |
|
||||
| D. 同步 wiki | 描述完整且已完成詳細分析後，更新目錄頁與計畫頁 |
|
||||
| C. 逐步詢問 | 每輪只問 1～3 個必要問題，使用者回答後整理計畫草稿 |
|
||||
| D. 同步 wiki | 每輪都更新目錄頁與計畫頁 |
|
||||
| E. 完成收斂 | 使用者確認計畫完成後輸出 wiki 連結與摘要 |
|
||||
|
||||
## 共用規範（必要前置）
|
||||
@@ -27,12 +27,11 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫
|
||||
- 本 skill 會寫入外部 Gitea wiki；目標 wiki repo 不明時必須詢問，不得臆測。
|
||||
- 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--index` 時才覆蓋預設值。
|
||||
- 計畫頁 title 預設固定為 `PLAN-{yyyyMMdd}-{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由已確認的計畫內容、計畫名稱或需求摘要產生穩定短雜湊並轉成全大寫。
|
||||
- 加入目錄頁時，先從計畫內容尋找系統名稱；若無明確系統名稱，依計畫目標產生一個精簡系統名稱。系統名稱必須是程式碼專案可使用的英文名稱，格式固定為大駝峰（PascalCase），只允許英文字母與數字，且必須以英文字母開頭，例如 `InventoryTracker`。無法可靠產生時必須詢問使用者，不得自行幻想。目錄標題使用 `{系統名稱}-計畫`，並連結到計畫頁。
|
||||
- 加入目錄頁時，先從計畫內容尋找系統名稱；若無明確系統名稱，依計畫目標產生一個精簡系統名稱。目錄標題使用 `{系統名稱}-計畫`，並連結到計畫頁。
|
||||
- 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本計畫既有列或在既有表格附加新列。
|
||||
- **不落地絕對規則**：全程禁止本機檔案落地。不得建立、更新、下載或暫存任何本機輸出／中介檔案，包含 `plan.md`、`todo.md`、`.md` 草稿、暫存 JSON body、附件暫存檔、wiki clone、或任何用來傳遞中間成果的檔案；中間成果只存在於對話內容、工具參數與 Gitea wiki API request body。不得使用 `curl --data @file`、`--data-binary @file` 或任何 `@file` 形式送出本機檔案。
|
||||
- **不落地絕對規則**：不得建立本機 `plan.md`、`todo.md`、`.md` 草稿、暫存 JSON body、wiki clone、或任何用來傳遞中間成果的檔案；中間成果只存在於對話內容與 Gitea wiki API request body。不得使用 `curl --data @file`。
|
||||
- 使用者已用參數指定 `--wiki-repo`、`--index`、`--project`、`--page` 時跳過對應詢問。
|
||||
- 使用者已用 `--project` 指定計畫名稱時，仍需檢查是否符合 PascalCase 英文專案名稱；不符合時必須請使用者修正或授權轉換後的新名稱。
|
||||
- 不產生 `TODO`、待辦事項、checklist、工作清單或實作任務；計畫頁只描述系統規劃、決策、範圍、方案、風險與待確認事項。
|
||||
- 每一輪使用者回答後都要同步 wiki。同步失敗時停止下一輪詢問，先回報錯誤與待使用者處理的點。
|
||||
- 不要求使用者把 token 貼進對話；token 依 `spec-gitea` 從環境變數或既有設定取得。
|
||||
|
||||
## 參數
|
||||
@@ -43,7 +42,7 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫
|
||||
| --- | --- |
|
||||
| `--wiki-repo` | Gitea wiki 所屬 repo，例如 `knowledges/Plan`。未帶且無法從目前 repo 推得時詢問使用者。 |
|
||||
| `--index` | 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 |
|
||||
| `--project` | 計畫名稱／系統名稱；必須是程式碼專案可使用的 PascalCase 英文名稱。未帶時從計畫內容尋找或產生系統名稱，用於目錄列標題與摘要。 |
|
||||
| `--project` | 計畫名稱；未帶時從計畫內容尋找或產生系統名稱，用於目錄列標題與摘要。 |
|
||||
| `--page` | 計畫頁 title；未帶時固定使用 `PLAN-{yyyyMMdd}-{HASH}`，不詢問。 |
|
||||
| `--host` | Gitea 主機，依 `spec-gitea` host 決定順序處理。 |
|
||||
| `--yes` | 略過一般性確認；不得略過目標 wiki 不明、寫入衝突或使用者尚未確認的計畫完成判斷。 |
|
||||
@@ -54,7 +53,7 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫
|
||||
2. 確認 `--wiki-repo` 是否為 `owner/repo` 格式；不符合時詢問使用者修正。
|
||||
3. 確認目錄頁 title：未帶 `--index` 時固定使用 `CONTENTS`。
|
||||
4. 確認計畫頁 title：未帶 `--page` 時固定使用 `PLAN-{yyyyMMdd}-{HASH}`。雜湊輸入優先使用已確認的計畫內容；內容不足時使用計畫名稱、來源摘要與當輪時間組合，輸出全大寫短雜湊。
|
||||
5. 確認系統名稱：先從 `--project`、計畫內容、需求來源或使用者回答尋找明確系統名稱；系統名稱必須符合 PascalCase 英文專案名稱格式。找不到或無法可靠轉換時，必須詢問使用者，不得自行幻想。
|
||||
5. 確認系統名稱：先從 `--project`、計畫內容、需求來源或使用者回答尋找明確系統名稱；找不到時產生精簡系統名稱，不為此單獨詢問。
|
||||
6. 用 `GET /repos/<owner>/<repo>` 驗證 token 對 repo 有權限；失敗時遮蔽機密後回報並停止。
|
||||
|
||||
## 階段 B：讀取 wiki 現況
|
||||
@@ -66,10 +65,10 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫
|
||||
|
||||
## 目錄頁格式
|
||||
|
||||
目錄頁不存在時建立下列結構；更新既有目錄頁時禁止整頁覆蓋，必須保留既有標題、說明、表格與其他內容，只新增或更新本計畫相關列。新建目錄頁的大標題（H1）使用系統名稱；若此 wiki 不是單一系統專用且無法確認系統名稱，使用 `# 代辦事項`：
|
||||
目錄頁不存在時建立下列結構；更新既有目錄頁時禁止整頁覆蓋，必須保留既有標題、說明、表格與其他內容，只新增或更新本計畫相關列：
|
||||
|
||||
```markdown
|
||||
# <系統名稱或代辦事項>
|
||||
# CONTENTS
|
||||
|
||||
計畫目錄。
|
||||
|
||||
@@ -97,12 +96,13 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫
|
||||
|
||||
## 方案
|
||||
|
||||
## 風險
|
||||
|
||||
## 待確認
|
||||
|
||||
## TODO
|
||||
- [ ] ...
|
||||
```
|
||||
|
||||
已有計畫頁時保留使用者明確保留的內容；只更新本 skill 管理的章節。需求不明的部分放在 `## 待確認`，不得自行補完。不得加入 `## TODO`、Markdown checklist 或任何代辦事項章節。
|
||||
已有計畫頁時保留使用者明確保留的內容；每輪只更新本 skill 管理的章節。需求不明的部分放在 `## 待確認`，不得自行補完。
|
||||
|
||||
## 階段 C：逐步詢問
|
||||
|
||||
@@ -116,26 +116,27 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫
|
||||
|
||||
每輪回答後：
|
||||
|
||||
- 檢查目標、成功標準、使用者與情境、限制條件、功能範圍、不做範圍、資料流、外部依賴、里程碑、驗收項目、風險與待確認事項是否足以形成系統規劃。
|
||||
- 對所有仍不明確、互相矛盾或無法可靠推論的點，繼續詢問使用者；不得用「合理推測」補完。
|
||||
- 在描述完整前，不得把詳細分析寫入計畫頁。
|
||||
- 描述完整後，才整理計畫頁的目標、背景與限制、範圍、方案、風險與待確認；不得產生 TODO 或 checklist。
|
||||
- 將回答整合進計畫頁。
|
||||
- 把仍不明確的點列入 `## 待確認`。
|
||||
- 產出或更新 `## TODO` checklist，格式依 `spec-todo-list`。
|
||||
- 詢問使用者下一輪問題前，先完成階段 D 的 wiki 同步。
|
||||
|
||||
使用者明確表示「完成」「先到這裡」「計畫完成」時，先檢查系統規劃必要描述是否完整；若仍有必要缺口，必須列出缺口並繼續詢問。只有必要描述完整時，才能進入階段 D 與階段 E；不要再追問非必要細節。
|
||||
使用者明確表示「完成」「先到這裡」「計畫完成」時，進入階段 E；不要再追問非必要細節。
|
||||
|
||||
## 階段 D：同步 wiki
|
||||
|
||||
描述完整並完成詳細分析後，同步順序固定：
|
||||
每輪同步順序固定：
|
||||
|
||||
1. 更新計畫頁。
|
||||
2. 更新目錄頁：不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<系統名稱>-計畫` 列，或在既有表格／頁末附加新列，確保有本計畫頁連結與摘要。
|
||||
3. 再次讀回兩個頁面確認內容已更新。
|
||||
3. 再次讀回兩個頁面確認內容已更新。讀回時若回應含 `content_base64`，必須 base64 解碼後比對正文 Markdown 是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。
|
||||
|
||||
API 寫入方式：
|
||||
|
||||
- 建立新頁：`POST /repos/<owner>/<repo>/wiki/new`，body 帶 `title`、`content`、`message`。
|
||||
- 更新既有頁：先查表取得 `sub_url`，再用 `PATCH /repos/<owner>/<repo>/wiki/page/<sub_url>`，body 帶 `title`、`content`、`message`。
|
||||
- request body 必須由工具呼叫、stdin、shell 變數或記憶中內容直接送出，不得先寫成本機 JSON、Markdown 或任何暫存檔；禁止所有 `@file` 形式。
|
||||
- 建立新頁：`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。
|
||||
|
||||
@@ -86,7 +86,7 @@ description: JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API
|
||||
- API base：`https://<host>/api/v1`（repo 層：`https://<host>/api/v1/repos/<owner>/<repo>`）。
|
||||
- 標頭：`Authorization: token $GITEA_TOKEN`。
|
||||
- **分頁必須完整讀取**：持續累加 `page` 直到回傳筆數 `< limit`（或回空陣列）為止，不可只取第一頁。
|
||||
- 寫入（議題描述／留言／PR body）以 **UTF-8 JSON 檔**帶入（如 `--data @body.json`）；換行必須是**實際換行**，不可讓內容顯示字面 `\n`（編碼細節見 `/jsc-shared:spec-output`）。
|
||||
- 寫入（議題描述／留言／PR body）以 **UTF-8 JSON body** 帶入；wiki 寫入則使用 `content_base64`，值必須是 wiki Markdown 內容先以 UTF-8 編碼再 base64 編碼的結果，不能用 `content`、不能用 `@file` 形式。換行必須是**實際換行**，不可讓內容顯示字面 `\n`（編碼細節見 `/jsc-shared:spec-output`）。
|
||||
- API 失敗（401／403／網路錯誤）→ 回報錯誤（**遮蔽 token**）並停止；401／403 多半是 token 失效或權限不足。
|
||||
- 版本相依端點（project／column／dependency 等）先以 GET 探測（404／501 視為不支援），**不得對未確認存在的端點做寫入**。
|
||||
|
||||
@@ -107,11 +107,12 @@ Gitea wiki 的「title」與實際存放用的「sub_url／檔名」不是同一
|
||||
sub_url 使用（新頁尚未建立時的合理退路）。
|
||||
3. **建立新頁不必自行轉義**：`POST /wiki/new` 直接帶完整、人類可讀的 title 字串即可
|
||||
（含空白與符號皆可），轉義是 Gitea 伺服器端完成的，呼叫端不用預先處理。
|
||||
4. 若寫入策略是透過 **git clone/push** 直接操作 wiki repo 產生 `.md` 檔（而非呼叫
|
||||
4. **wiki 讀回驗證以正文為準**：寫入後一律再呼叫 `GET /repos/<owner>/<repo>/wiki/page/<sub_url>` 讀回內容驗證，不可只確認建立成功；若回應含 `content_base64`，以 base64 解碼後的 Markdown 做比對；若回應格式不同，依官方 API 文件與實際回應欄位抽取正文後再比對。
|
||||
5. 若寫入策略是透過 **git clone/push** 直接操作 wiki repo 產生 `.md` 檔（而非呼叫
|
||||
REST API），則不必還原 Gitea 的內部轉義：改由呼叫端自建一份「工作路徑 → 儲存
|
||||
檔名」manifest（例如 `_paths.json`），寫入時查 manifest 決定檔名、讀回時查 manifest
|
||||
還原原始路徑，全程不依賴、也不猜測 Gitea 從檔名反推 title 的規則。
|
||||
5. 兩種寫入策略（REST API 查表 vs git clone/push + 自建 manifest）各有各的理由，
|
||||
6. 兩種寫入策略（REST API 查表 vs git clone/push + 自建 manifest）各有各的理由，
|
||||
不合併；但上述查表優先、不猜測轉義的原則對兩者都適用。
|
||||
|
||||
參考實作：`doc/scripts/worklog/wiki_api.py` 的 `resolve_sub_url()` 走 REST API 查表
|
||||
|
||||
+16
-25
@@ -1,12 +1,12 @@
|
||||
---
|
||||
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`）。
|
||||
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 頁 → 交給指定模型實作」固定成七個階段。全程禁止本機檔案落地；唯一輸出位置是指定 Gitea wiki。
|
||||
把「需求 → 分析 → 產生 TODO wiki 頁 → 交給指定模型實作」固定成七個階段。全程不建立本機 `todo.md`、草稿檔、暫存 JSON body 或 wiki clone；唯一輸出位置是指定 Gitea wiki。
|
||||
|
||||
| 階段 | 做什麼 | 產出 |
|
||||
| --- | --- | --- |
|
||||
@@ -26,16 +26,15 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
|
||||
|
||||
本 skill 特有補充：
|
||||
|
||||
- **不落地絕對規則**：全程禁止本機檔案落地。不得建立、更新、下載或暫存任何本機輸出／中介檔案，包含 `todo.md`、`plan.md`、`.md` 草稿、暫存 JSON body、附件暫存檔、wiki clone、或任何用來傳遞中間成果的檔案；中間成果只存在於對話內容、工具參數與 Gitea wiki API request body。不得使用 `curl --data @file`、`--data-binary @file` 或任何 `@file` 形式送出本機檔案。
|
||||
- `--source` 指向本機既有檔案時可以唯讀讀取來源檔；這不是輸出落地，不得修改該來源檔或寫出衍生檔。`--source` 指向 Gitea 議題附件時，只能以 API／工具直接讀入記憶；若附件必須下載成暫存檔才能讀取，立刻停止並回報「附件需要檔案落地，違反本 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 repo 不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。
|
||||
- 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--wiki-index` 時才覆蓋預設值。
|
||||
- TODO 頁 title 預設固定為 `TODO-{yyyyMMdd}-{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由需求彙整、關聯計畫或系統名稱產生穩定短雜湊並轉成全大寫。
|
||||
- 必須詢問使用者是否需要把本 TODO 連結到計畫；使用者回答不需要時，不更新目錄頁，也不要把 TODO 加到目錄。
|
||||
- 必須詢問使用者兩個獨立決策：是否關聯到計畫／系統名稱，以及是否更新 wiki 目錄頁；使用者回答不加入計畫時，仍預設更新 wiki 目錄頁，除非使用者另行明確說不要更新目錄頁。
|
||||
- 需要加入目錄頁時，目錄標題使用 `{關聯計畫的系統名稱}-代辦`，並連結到 TODO 頁。系統名稱優先從關聯計畫取得；若沒有關聯計畫，從需求內容尋找或產生系統名稱。
|
||||
- 目錄頁不存在而需要新建時，頁面 Markdown 的大標題（H1）必須是 `# <系統名稱>`；若無法確認系統名稱且使用者也未提供，使用 `# 代辦事項`。不得用 `# CONTENTS` 作為新建目錄頁的大標題。
|
||||
- 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本 TODO 既有列或在既有表格附加新列。
|
||||
|
||||
## 參數
|
||||
@@ -48,10 +47,10 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
|
||||
| `--impl-model` | 直接指定實作模型（id 或 alias），跳過階段 3 的推薦流程；仍會在 `model_reason` 註明「使用者指定」。 |
|
||||
| `--wiki-repo` | 指定要同步的 Gitea wiki repo，例如 `knowledges/Plan`。 |
|
||||
| `--wiki-index` | wiki 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 |
|
||||
| `--wiki-project` | 關聯計畫或系統名稱；需要加入目錄頁時，用於產生 `{關聯計畫的系統名稱}-代辦`。 |
|
||||
| `--wiki-project` | 關聯計畫或系統名稱；需要更新目錄頁時，用於產生 `{關聯計畫的系統名稱}-代辦`。 |
|
||||
| `--wiki-page` | todo 頁 title；未帶時固定使用 `TODO-{yyyyMMdd}-{HASH}`，不詢問。 |
|
||||
| `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。 |
|
||||
| `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否連結到計畫、或對外寫入目標不明等必要決策。 |
|
||||
| `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否關聯到計畫／系統名稱、是否更新 wiki 目錄頁，或對外寫入目標不明等必要決策。 |
|
||||
|
||||
## 階段 1：選分析模型
|
||||
|
||||
@@ -125,8 +124,8 @@ scope: <階段 2 產出的 scope>
|
||||
|
||||
1. 依 `spec-gitea` 決定 host 與 token，不輸出 token。
|
||||
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 轉義規則。
|
||||
3. 詢問使用者兩個獨立決策：是否關聯到計畫／系統名稱，以及是否更新 wiki 目錄頁。使用者回答不加入計畫時，仍預設會更新目錄頁；只有使用者明確回答不要更新目錄頁，才可記錄為「不更新目錄頁」。
|
||||
4. 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若目錄頁更新決策為開啟，也取得目錄頁 `sub_url`。目錄頁不存在時才建立；目錄頁存在時必須讀取原內容並保留，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。
|
||||
5. 讀取既有 todo 頁；若不存在，策略為「建立」。
|
||||
6. 既有 todo 頁存在時解析 frontmatter：
|
||||
|
||||
@@ -144,8 +143,8 @@ scope: <階段 2 產出的 scope>
|
||||
同步順序固定：
|
||||
|
||||
1. 寫入 todo 頁。
|
||||
2. 若使用者確認需要連結到計畫，upsert 目錄頁表格列：目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。若使用者回答不需要，跳過目錄頁更新。
|
||||
3. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認。
|
||||
2. 若使用者明確表示不要更新目錄頁，跳過目錄頁更新；否則 upsert 目錄頁表格列。目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。
|
||||
3. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認。讀回時若回應含 `content_base64`，必須 base64 解碼後再比對 Markdown 內容是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。
|
||||
|
||||
目錄頁表格列格式：
|
||||
|
||||
@@ -154,21 +153,13 @@ scope: <階段 2 產出的 scope>
|
||||
```
|
||||
|
||||
若既有目錄頁沒有 `| 頁面 | 內容 |` 表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。
|
||||
目錄頁不存在而新建時，內容格式如下；`<目錄大標題>` 必須依本 skill 特有補充使用系統名稱或 `代辦事項`，不是 wiki page title：
|
||||
|
||||
```markdown
|
||||
# <目錄大標題>
|
||||
|
||||
| 頁面 | 內容 |
|
||||
| --- | --- |
|
||||
| [<關聯計畫的系統名稱>-代辦](<todo page title percent-encoded>) | todo wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |
|
||||
```
|
||||
|
||||
API 寫入方式：
|
||||
|
||||
- 建立新頁：`POST /repos/<owner>/<repo>/wiki/new`，body 帶 `title`、`content`、`message`。
|
||||
- 更新既有頁：先查表取得 `sub_url`，再用 `PATCH /repos/<owner>/<repo>/wiki/page/<sub_url>`，body 帶 `title`、`content`、`message`。
|
||||
- request body 必須由工具呼叫、stdin、shell 變數或記憶中內容直接送出，不得先寫成本機 JSON、Markdown 或任何暫存檔；禁止所有 `@file` 形式。
|
||||
- 建立新頁：`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。
|
||||
|
||||
@@ -182,7 +173,7 @@ API 寫入方式：
|
||||
| 實作模型 | `model` / `model_alias`，並註明推薦或使用者指定 |
|
||||
| 項目數 | 本次新增的 checklist 項目數 |
|
||||
| Wiki repo | `<owner/repo>` |
|
||||
| 目錄頁 | URL；若本次未連結到計畫，填「未更新（使用者選擇不加入目錄）」 |
|
||||
| 目錄頁 | URL；若使用者明確不要更新目錄頁，填「未更新（使用者選擇不更新目錄頁）」 |
|
||||
| Todo 頁 | URL |
|
||||
| 本次動作 | 建立／附加／覆蓋 |
|
||||
|
||||
|
||||
Reference in New Issue
Block a user