feat(git-safety,model): 分支一律先確認、模型 id 改以 transcript 實際值為準 #13
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-shared",
|
||||
"version": "0.1.4",
|
||||
"version": "0.1.5",
|
||||
"description": "JSC 跨 AI 助理共用規範 skills plugin（Claude Code / Codex / Antigravity / OpenCode / GitHub Copilot CLI），`skills/` 為唯一真實來源，並提供整組 plugin 的安裝／更新／移除管理（plugins-install 一次安裝或更新 jsc-code／jsc-doc／jsc-persona／jsc-shared，plugins-uninstall 一次移除四個 JSC plugin）。安裝與更新一律以 Gitea 遠端 repo 的 README 與檔案為準，不依賴既有本機存取庫；所有 skills 以 SKILL.md 為共通標準；於 Claude Code 以 /jsc-shared: 前綴呼叫。",
|
||||
"skills": "./skills",
|
||||
"author": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-shared",
|
||||
"version": "0.1.4",
|
||||
"version": "0.1.5",
|
||||
"description": "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 為共通標準。",
|
||||
"skills": "./skills"
|
||||
}
|
||||
|
||||
@@ -140,8 +140,9 @@ shared/
|
||||
| Skill | 用途 | 使用方法 |
|
||||
| --- | --- | --- |
|
||||
| `models` | 查詢目前可用哪些模型並依 `spec-model` 的標籤體系標註，維護 `~/.claude/jsc/models.json` 快取，依任務類型推薦模型或檢查當前模型是否符合指定模型。是 `spec-model` 的唯一可執行入口——其他 skill 需要模型清單或推薦時一律呼叫本 skill，不自行重寫探測或推薦邏輯 | `/jsc-shared:models`；可帶 `--refresh`（重跑探測與 smoke test）、`--task <analysis\|implement\|review\|summary\|persona>`（依對映表推薦模型）、`--check <model>`（比對指定模型與當前模型）、`--json` |
|
||||
| `plan-wiki` | 逐步詢問使用者計畫內容，並把每一輪已確認的計畫草稿直接同步到指定 Gitea wiki 的目錄頁與計畫頁；全程不建立本機計畫檔、草稿檔、暫存 JSON body 或 wiki clone | `/jsc-shared:plan-wiki`；可帶 `--wiki-repo <owner/repo>`、`--index <目錄頁title>`、`--project <計畫名稱>`、`--page <計畫頁title>`、`--host <gitea主機>`、`--yes` |
|
||||
| `todo-wiki` | 把「需求 → 分析 → 產生鎖定模型的 TODO 清單 → 同步到 Gitea wiki 目錄與頁面」固定成不落地檔案的流程；不產生本機 `todo.md`，只寫入指定 wiki 目錄頁與 todo 頁 | `/jsc-shared:todo-wiki`；可帶 `--source <需求描述\|檔案路徑\|議題編號>`、`--impl-model <id\|alias>`、`--wiki-repo <owner/repo>`、`--wiki-index <目錄頁title>`、`--wiki-project <計畫名稱>`、`--wiki-page <todo頁title>`、`--append\|--overwrite`、`--yes` |
|
||||
| `plan-wiki` | 逐步詢問使用者計畫內容，並把每一輪已確認的計畫草稿直接同步到指定 Gitea wiki 的目錄頁與計畫頁；目錄頁為四欄表格，計畫列的「已產生」欄初始為 `[ ]`，待 `todo-wiki` 依該計畫產生 TODO 頁後才改為 `[x]`；全程不建立本機計畫檔、草稿檔、暫存 JSON body 或 wiki clone | `/jsc-shared:plan-wiki`；可帶 `--wiki-repo <owner/repo>`、`--index <目錄頁title>`、`--project <計畫名稱>`、`--page <計畫頁title>`、`--host <gitea主機>`、`--yes` |
|
||||
| `todo-wiki` | 把「需求 → 分析 → 產生鎖定模型的 TODO 清單 → 同步到 Gitea wiki 目錄與頁面」固定成不落地檔案的流程；開工前先從目錄頁挑一個尚未產生代辦的計畫（可不選），目錄頁的 TODO 列「已完成」欄初始為 `[ ]`，待 `do-wiki` 執行完該 TODO 頁全部項目後才改為 `[x]`；不產生本機 `todo.md`，只寫入指定 wiki 目錄頁與 todo 頁 | `/jsc-shared:todo-wiki`；可帶 `--source <需求描述\|檔案路徑\|議題編號>`、`--impl-model <id\|alias>`、`--wiki-repo <owner/repo>`、`--wiki-index <目錄頁title>`、`--wiki-project <計畫名稱>`、`--wiki-page <todo頁title>`、`--append\|--overwrite`、`--yes` |
|
||||
| `do-wiki` | 讀取 `todo-wiki` 產生、帶鎖定模型 frontmatter 的 Gitea wiki TODO 頁並逐項執行；開工前先從目錄頁挑一份未完成的代辦，沒有就直接結束；比對當前模型與頁面 `model` 不符就停止；每完成一項就地勾選並立即回寫該 wiki 頁、讀回確認成功才繼續下一項；全部完成後回目錄頁把該代辦列「已完成」改為 `[x]` | `/jsc-shared:do-wiki`；可帶 `--wiki-repo <owner/repo>`、`--wiki-page <todo頁title>`、`--yes` |
|
||||
|
||||
### 整組 plugin 安裝管理
|
||||
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-shared",
|
||||
"version": "0.1.4",
|
||||
"version": "0.1.5",
|
||||
"description": "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 為共通標準；於 Antigravity 以 /jsc-shared: 前綴呼叫。",
|
||||
"skills": "./skills"
|
||||
}
|
||||
|
||||
+1
-1
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "jsc-shared",
|
||||
"shortName": "shared",
|
||||
"version": "0.1.4",
|
||||
"version": "0.1.7",
|
||||
"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:",
|
||||
|
||||
@@ -0,0 +1,90 @@
|
||||
---
|
||||
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-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-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-page <既有 TODO 頁 title>] [--yes]`
|
||||
|
||||
| 參數 | 說明 |
|
||||
| --- | --- |
|
||||
| `--wiki-repo` | 指定要讀取的 Gitea wiki repo，例如 `knowledges/Plan`。未帶時依 `spec-ask-user` 詢問，不臆測。 |
|
||||
| `--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`），依 `spec-wiki-contents`〔列型別判定〕取出所有「已完成」為 `[ ]` 的 TODO 列。
|
||||
4. **沒有未完成代辦就直接結束**：目錄頁不存在、目錄頁沒有任何 TODO 列、或所有 TODO 列「已完成」皆為 `[x]` 這三種情境，一律輸出 `[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 的代辦」）自動觸發 |
|
||||
+13
-22
@@ -1,7 +1,7 @@
|
||||
---
|
||||
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]"
|
||||
argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN_<yyyyMMdd>_<HASH>] [--host <gitea主機>] [--yes]"
|
||||
---
|
||||
|
||||
# plan-wiki — 逐步建立計畫並同步到 Gitea wiki
|
||||
@@ -20,39 +20,40 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫
|
||||
|
||||
先載入 `/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 需要的規範：`spec-output`、`spec-execution`、`spec-gitea`、`spec-wiki-contents`、`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` 由已確認的計畫內容、計畫名稱或需求摘要產生穩定短雜湊並轉成全大寫。
|
||||
- 計畫頁 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。同步失敗時停止下一輪詢問，先回報錯誤與待使用者處理的點。
|
||||
- 每一輪使用者回答後都要同步 wiki；一輪一同步、一輪一確認，不可累積多輪回答後一次送出。同步失敗、讀回失敗或比對不一致時，停止下一輪詢問，先回報錯誤與待使用者處理的點。
|
||||
- 只有階段 D 的 wiki 同步完成且讀回確認成功後，才能進入下一輪提問。
|
||||
- 不要求使用者把 token 貼進對話；token 依 `spec-gitea` 從環境變數或既有設定取得。
|
||||
|
||||
## 參數
|
||||
|
||||
`[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN-<yyyyMMdd>-<HASH>] [--host <gitea主機>] [--yes]`
|
||||
`[--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}`，不詢問。 |
|
||||
| `--page` | 計畫頁 title；未帶時固定使用 `PLAN_{yyyyMMdd}_{HASH}`，不詢問。 |
|
||||
| `--host` | Gitea 主機，依 `spec-gitea` host 決定順序處理。 |
|
||||
| `--yes` | 略過一般性確認；不得略過目標 wiki 不明、寫入衝突或使用者尚未確認的計畫完成判斷。 |
|
||||
| `--yes` | 略過一般性確認；不得略過目標 wiki 不明、寫入衝突、同步失敗後的停止，或使用者尚未確認的計畫完成判斷。 |
|
||||
|
||||
## 階段 A：前置設定
|
||||
|
||||
1. 依 `spec-gitea` 決定 host 與 token，只輸出 token「已設定／未設定」。
|
||||
2. 確認 `--wiki-repo` 是否為 `owner/repo` 格式；不符合時詢問使用者修正。
|
||||
3. 確認目錄頁 title：未帶 `--index` 時固定使用 `CONTENTS`。
|
||||
4. 確認計畫頁 title：未帶 `--page` 時固定使用 `PLAN-{yyyyMMdd}-{HASH}`。雜湊輸入優先使用已確認的計畫內容；內容不足時使用計畫名稱、來源摘要與當輪時間組合，輸出全大寫短雜湊。
|
||||
4. 確認計畫頁 title：未帶 `--page` 時固定使用 `PLAN_{yyyyMMdd}_{HASH}`。雜湊輸入優先使用已確認的計畫內容；內容不足時使用計畫名稱、來源摘要與當輪時間組合，輸出全大寫短雜湊。
|
||||
5. 確認系統名稱：先從 `--project`、計畫內容、需求來源或使用者回答尋找明確系統名稱；找不到時產生精簡系統名稱，不為此單獨詢問。
|
||||
6. 用 `GET /repos/<owner>/<repo>` 驗證 token 對 repo 有權限；失敗時遮蔽機密後回報並停止。
|
||||
|
||||
@@ -65,21 +66,9 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫
|
||||
|
||||
## 目錄頁格式
|
||||
|
||||
目錄頁不存在時建立下列結構；更新既有目錄頁時禁止整頁覆蓋，必須保留既有標題、說明、表格與其他內容，只新增或更新本計畫相關列：
|
||||
目錄頁的四欄表格格式、「已產生」欄初始值、列型別判定、以及連結來源（查表取得的 `sub_url`／`path`，不使用 percent-encode 的 title）一律依 `/jsc-shared:spec-wiki-contents`，本 skill 不重複定義。
|
||||
|
||||
```markdown
|
||||
# CONTENTS
|
||||
|
||||
計畫目錄。
|
||||
|
||||
| 頁面 | 內容 |
|
||||
|------|------|
|
||||
| [<系統名稱>-計畫](<page title percent-encoded, 空白用 %20>) | plan wiki：<系統名稱> 計畫 |
|
||||
|
||||
產出日期：yyyy-MM-dd
|
||||
```
|
||||
|
||||
若目錄頁已存在且不是單一計畫專用目錄，仍以同一張 `| 頁面 | 內容 |` 表格為準：保留原標題與說明，只在表格中 upsert 本計畫頁面列。若既有目錄頁沒有 `| 頁面 | 內容 |` 表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。連結文字固定為 `<系統名稱>-計畫`；連結 target 用 `encodeURIComponent(title).replace(/%20/g, "%20")` 的結果，不使用 API `sub_url` 反推人工連結。
|
||||
目錄頁不存在時，依 `spec-wiki-contents`〔目錄頁格式〕建立新頁，並在計畫列「已產生」欄填 `[ ]`（表示尚未產生對應 TODO）、「已完成」欄留空；目錄頁已存在時禁止整頁覆蓋，只能 upsert 既有的 `<系統名稱>-計畫` 列或在既有表格附加新列，保留其餘標題、說明與內容。
|
||||
|
||||
## 計畫頁格式
|
||||
|
||||
@@ -120,6 +109,7 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫
|
||||
- 把仍不明確的點列入 `## 待確認`。
|
||||
- 產出或更新 `## TODO` checklist，格式依 `spec-todo-list`。
|
||||
- 詢問使用者下一輪問題前，先完成階段 D 的 wiki 同步。
|
||||
- 如果某輪資料不足，先把不確定內容放進 `## 待確認`，不得自行補完再繼續問下一輪。
|
||||
|
||||
使用者明確表示「完成」「先到這裡」「計畫完成」時，進入階段 E；不要再追問非必要細節。
|
||||
|
||||
@@ -130,6 +120,7 @@ argument-hint: "[--wiki-repo <owner/repo>] [--index CONTENTS] [--project <計畫
|
||||
1. 更新計畫頁。
|
||||
2. 更新目錄頁：不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<系統名稱>-計畫` 列，或在既有表格／頁末附加新列，確保有本計畫頁連結與摘要。
|
||||
3. 再次讀回兩個頁面確認內容已更新。讀回時若回應含 `content_base64`，必須 base64 解碼後比對正文 Markdown 是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。
|
||||
4. 每輪只允許一輪同步結果對應下一輪提問；若 wiki 寫入失敗、讀回失敗或內容比對不一致，必須停止下一輪詢問，先回報錯誤與待處理點。
|
||||
|
||||
API 寫入方式：
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: spec-todo-list
|
||||
description: JSC plugins 共用「TODO list 規範」：一律用 Markdown checklist（`- [ ]`）格式、每項要具體到可執行可驗收、不得憑空編造需求外的項目、依影響範圍由小到大排序、每項要能舉證對應到 `path:line` 或議題描述的哪一句、完成一項就勾選並附上 Asia/Taipei 時間戳並留言回報進度。當其他 skill 內文引用 spec-todo-list 或 /jsc-shared:spec-todo-list、或需要產生／追蹤議題（或文件）TODO list 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
description: JSC plugins 共用「TODO list 規範」：一律用 Markdown checklist（`- [ ]`）格式、每項要具體到可執行可驗收、必要時補上實作方式與建議修改內容、不得憑空編造需求外的項目、依影響範圍由小到大排序、每項要能舉證對應到 `path:line` 或議題描述的哪一句、完成一項就勾選並附上 Asia/Taipei 時間戳並留言回報進度。當其他 skill 內文引用 spec-todo-list 或 /jsc-shared:spec-todo-list、或需要產生／追蹤議題（或文件）TODO list 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-todo-list — 共用 TODO list 規範
|
||||
@@ -19,6 +19,8 @@ description: JSC plugins 共用「TODO list 規範」：一律用 Markdown check
|
||||
- 每一項 TODO 都必須具體到**看到這一句就知道要做什麼、做完後能明確判斷是否達成**；不得使用「優化一下」「檢查看看」「處理相關問題」這類模糊、無驗收標準的措辭。
|
||||
- 動詞＋對象＋（必要時）驗收條件三者盡量齊備，例如「把 `UserService.Login` 的密碼驗證改為使用雪湯 hash 比對，單元測試涵蓋密碼錯誤與帳號鎖定兩種情境」，而非「改善登入安全性」。
|
||||
- 一項 TODO 只對應一件可獨立完成、可獨立驗收的工作；範圍過大時拆成多項，不得把整個議題塞成一項。
|
||||
- 若 TODO 用於實作或修正文件／程式，建議直接補上「實作方式」與「建議修改內容」，讓執行者不必回頭猜測改法。
|
||||
- 供實作型 TODO 使用時，建議格式可寫成 `- [ ] **編號 短標題**：具體內容；實作方式：...；驗收條件：...；來源依據：...；建議修改內容：...`；若確實沒有明確修改方向，`建議修改內容` 可省略，但 `實作方式` 不可省略。
|
||||
|
||||
## 禁止憑空編造
|
||||
|
||||
|
||||
@@ -0,0 +1,52 @@
|
||||
---
|
||||
name: spec-wiki-contents
|
||||
description: JSC plugins 共用「wiki 目錄頁四欄格式與列型別判定規範」：目錄頁固定 `| 頁面 | 已產生 | 已完成 | 內容 |` 四欄表格與 `| --- | :-: | :-: | --- |` 對齊列、依「已產生」「已完成」欄位判定計畫列／TODO 列／略過並輸出 WRN、目錄列連結一律用查表取得的 sub_url／path 而非 percent-encode 的 title、目錄頁不存在才新建、存在時禁止整頁覆蓋只能 upsert 既有列。當其他 skill 內文引用 spec-wiki-contents 或 /jsc-shared:spec-wiki-contents、或需要讀取／更新 plan-wiki／todo-wiki／do-wiki 共用的四欄目錄頁時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||||
---
|
||||
|
||||
# spec-wiki-contents — 共用 wiki 目錄頁四欄格式與列型別判定規範
|
||||
|
||||
`plan-wiki`、`todo-wiki`、`do-wiki` 三個 skill 共用同一份 Gitea wiki 目錄頁（預設 title `CONTENTS`），一律遵守以下規範，不得各自複製一份格式或判定邏輯。
|
||||
|
||||
## 目錄頁格式（固定四欄）
|
||||
|
||||
```markdown
|
||||
# CONTENTS
|
||||
|
||||
| 頁面 | 已產生 | 已完成 | 內容 |
|
||||
| --- | :-: | :-: | --- |
|
||||
| [<系統名稱>-計畫](<查表取得的 path>) | [ ] | | plan wiki：<系統名稱> 計畫 |
|
||||
| [<系統名稱>-代辦](<查表取得的 path>) | | [ ] | todo wiki：<系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |
|
||||
```
|
||||
|
||||
- 欄位固定四個：`頁面`／`已產生`／`已完成`／`內容`，對齊列固定 `| --- | :-: | :-: | --- |`，不得增減欄位或改變順序。
|
||||
- **計畫列**：由 `plan-wiki` 建立，「已產生」欄填 `[ ]`（表示尚未產生對應 TODO），「已完成」欄留空。
|
||||
- **TODO 列**：由 `todo-wiki` 建立，「已完成」欄填 `[ ]`，「已產生」欄留空。
|
||||
- 目錄頁不存在時才依上述格式新建；已存在時**禁止整頁覆蓋**，只能 upsert 既有列或在既有表格附加新列，保留其餘標題、說明與內容。
|
||||
|
||||
## 列型別判定
|
||||
|
||||
讀取既有目錄頁表格時，依每列「已產生」「已完成」兩欄判定列型別：
|
||||
|
||||
| 判定 | 條件 |
|
||||
| --- | --- |
|
||||
| 計畫列 | 「已產生」欄含 `[ ]` 或 `[x]`（不論勾選與否），「已完成」欄留空 |
|
||||
| TODO 列 | 「已完成」欄含 `[ ]` 或 `[x]`，「已產生」欄留空 |
|
||||
| 略過 | 兩欄皆空、或兩欄格式皆無法解析 |
|
||||
|
||||
略過的列一律輸出 `[yyyy/MM/dd HH:mm:ss][目錄盤點][WRN]: <該列「頁面」欄內容> 兩個 check 欄皆無法判定列型別，已略過`，並繼續處理其餘列，不得中止整個流程、也不得自行臆測型別。
|
||||
|
||||
## 連結來源：查表取得的 path，不用 percent-encode title
|
||||
|
||||
目錄列的連結一律使用依 `/jsc-shared:spec-gitea`〔Wiki 頁名轉義規則〕規則 2 分頁查表取得的 `sub_url`／`path`；**不得**自行對 title 做 `encodeURIComponent` 之類的轉換後當成連結——含中日文標題的頁面，Gitea 的轉義規則不可靠，只有查表結果可信。新建列且對應頁面尚未建立時，先建立該頁取得其 `sub_url` 後再回填目錄列連結；查表暫時失敗時，先以人類可讀 title 當佔位連結並標註「待查表更新」，不得因此跳過目錄列的建立。
|
||||
|
||||
## 使用者互動：開工前挑選
|
||||
|
||||
- `todo-wiki` 開工前：讀目錄頁，列出所有「已產生」為 `[ ]` 的計畫列，依 `/jsc-shared:spec-ask-user` 詢問使用者是否要關聯其中一個（選項固定含「不關聯任何計畫」與「其他」，可以不選）；只要存在至少一個這種計畫列就必須詢問，`--yes` 不得略過；一個都沒有時不詢問直接繼續。
|
||||
- `do-wiki` 開工前：讀目錄頁，列出所有「已完成」為 `[ ]` 的 TODO 列，依 `/jsc-shared:spec-ask-user` 以**單選**呈現；沒有任何未完成 TODO 列時直接結束，不讀取任何 TODO 頁、不修改任何檔案或 wiki。
|
||||
- 兩者的候選數量、呈現方式（候選 ≤4 用 `AskUserQuestion`、>4 改文字編號列出）與「其他」選項，一律依 `/jsc-shared:spec-ask-user` 辦理。
|
||||
|
||||
## 回寫規則
|
||||
|
||||
- `todo-wiki` 寫入 TODO 頁成功後，若本次關聯到某個計畫列，回目錄頁把該計畫列「已產生」由 `[ ]` 改為 `[x]` 並讀回確認；找不到對應計畫列時**不得新建該列**，改以警告回報。
|
||||
- `do-wiki` 於 TODO 頁全部項目皆為 `- [x]` 後，回目錄頁把該 TODO 列「已完成」由 `[ ]` 改為 `[x]` 並讀回確認；只要還有未勾項目就不得勾選。
|
||||
- 兩者都必須讀回確認寫入成功，失敗立刻停止，不得繼續下一步。
|
||||
+53
-29
@@ -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 CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO-<yyyyMMdd>-<HASH>] [--append|--overwrite] [--yes]"
|
||||
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 <既有頁 title|TODO_<yyyyMMdd>_<HASH>>] [--append|--overwrite] [--yes]"
|
||||
---
|
||||
|
||||
# todo-wiki — 需求分析並同步指定模型 TODO 到 Gitea wiki
|
||||
@@ -22,24 +22,29 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode
|
||||
|
||||
先載入 `/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 需要的規範：`spec-model`、`spec-output`、`spec-execution`、`spec-issue-read`、`spec-todo-list`、`spec-ask-user`、`spec-time-log`、`spec-gitea`、`spec-wiki-contents`、`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 只負責產生與同步清單，不執行清單內容。
|
||||
- 本 skill 產生的 checklist 每項都要明寫實作方式；文件或程式修改若已有具體方向，必要時再補 `建議修改內容`，避免讓執行者回頭猜測。
|
||||
- 階段 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 頁 title 預設固定為 `TODO_{yyyyMMdd}_{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由需求彙整、關聯計畫或系統名稱產生穩定短雜湊並轉成全大寫。
|
||||
- **開工前先挑計畫**：依 `/jsc-shared:spec-wiki-contents`〔使用者互動〕，在階段 2-0 讀到目錄頁後、進入需求分析前，先列出所有「已產生」為 `[ ]` 的計畫列詢問使用者是否關聯（可以不選）；細節見階段 2「選擇尚未產生代辦的計畫」。
|
||||
- 目錄頁列型別判定（哪些列是計畫列、哪些是 TODO 列，以及無法判定時的 `[目錄盤點][WRN]` 提示）一律依 `/jsc-shared:spec-wiki-contents`〔列型別判定〕，本 skill 不重複定義。
|
||||
- 必須詢問使用者三個獨立決策：是否關聯到計畫／系統名稱、是否把新的代辦加入既有的 todo 內，以及是否更新 wiki 目錄頁；使用者回答不加入計畫時，仍預設更新 wiki 目錄頁，除非使用者另行明確說不要更新目錄頁。
|
||||
- 需要加入目錄頁時，目錄標題使用 `{關聯計畫的系統名稱}-代辦`，並連結到 TODO 頁。**系統名稱優先取自使用者於階段 2 選定的計畫列**；若沒有選定計畫，從需求內容尋找或產生系統名稱。
|
||||
- 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本 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>] [--wiki-repo <owner/repo>] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO_<yyyyMMdd>_<HASH>] [--append|--overwrite] [--yes]`
|
||||
|
||||
| 參數 | 說明 |
|
||||
| --- | --- |
|
||||
@@ -47,28 +52,44 @@ 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-page` | todo 頁 title；未帶時固定使用 `TODO-{yyyyMMdd}-{HASH}`，不詢問。 |
|
||||
| `--wiki-project` | 關聯計畫或系統名稱；預設仍會更新目錄頁，只有使用者明確表示不要更新目錄頁時才可略過。 |
|
||||
| `--wiki-page` | todo 頁 title；可指向既有 todo 頁 title，未帶時先詢問是否加入既有 todo，只有使用者選擇新建時才固定使用 `TODO_{yyyyMMdd}_{HASH}`。 |
|
||||
| `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。 |
|
||||
| `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否關聯到計畫／系統名稱、是否更新 wiki 目錄頁，或對外寫入目標不明等必要決策。 |
|
||||
|
||||
## 階段 1：選分析模型
|
||||
|
||||
1. 依 `/jsc-shared:spec-model` 第三節取得可用模型清單與標籤。
|
||||
1. 在讀取任何來源、做任何分析、或接觸 wiki 前，先依 `/jsc-shared:spec-model` 第三節取得可用模型清單與標籤，並確認目前執行本 skill 的模型 id。
|
||||
2. 依「需求分析／拆 TODO／架構決策」任務列比對必要標籤 `#深度推理` `#分析` `#本機可用`，選出推薦模型。
|
||||
3. 確認當前執行本 skill 的模型 id；無法確定時請使用者以 `/status` 確認，不要用猜的。
|
||||
4. 當前模型不符時，依 `spec-model` 第五節格式停止並要求使用者切換；不得先做階段 2 分析。
|
||||
3. 若當前執行本 skill 的模型 id 無法確定，先請使用者執行 `/status`，不得用猜的。
|
||||
4. 當前模型不符時，依 `spec-model` 第五節格式停止並要求使用者切換；開始任何實作前就要檢查，不得先做階段 2 分析、不得讀取來源、不得接觸 wiki。
|
||||
5. 相符時記錄此模型 id 供階段 4 的 `analyzed_by` 使用。
|
||||
|
||||
## 階段 2：分析需求
|
||||
|
||||
1. 判斷來源型態：
|
||||
### 階段 2-0：確認 wiki repo 並讀取目錄頁
|
||||
|
||||
1. **先確認 --wiki-repo**（即 `--wiki-repo` 參數）；缺少時依 `/jsc-shared:spec-ask-user` 詢問，不臆測。
|
||||
2. 依 `/jsc-shared:spec-gitea`〔Wiki 頁名轉義規則〕規則 2 分頁**查表取 path**，取得目錄頁（預設 title `CONTENTS`）的 `path` 並讀取內容。
|
||||
3. 本步驟讀到的目錄頁內容**供階段 5 重用**，不得為同一份目錄頁重複讀取。
|
||||
|
||||
### 選擇尚未產生代辦的計畫
|
||||
|
||||
- **--wiki-project 已帶則跳過**詢問（即 `--wiki-project` 參數已帶時），直接以該值為系統名稱。
|
||||
- 依 `/jsc-shared:spec-wiki-contents`〔列型別判定〕，從階段 2-0 讀到的目錄頁取出所有「已產生」為 `[ ]` 的計畫列；**無計畫不問**——一個都沒有時不詢問，直接進入「了解需求」。
|
||||
- **有計畫必問**——只要存在至少一個這種計畫列，就必須依 `/jsc-shared:spec-ask-user` 詢問使用者是否關聯其中一個；**可不選**——選項固定含「不關聯任何計畫」與「其他」，候選 ≤4 用 `AskUserQuestion`、>4 改文字編號列出。**--yes 不得略過**（即 `--yes` 旗標不得用來省略）本次詢問。
|
||||
- 使用者選定某個計畫列時，記下該列連結的 `path`，供下一步讀取計畫頁全文；使用者選「不關聯任何計畫」時，維持只用 `--source` 分析需求。
|
||||
|
||||
### 了解需求
|
||||
|
||||
1. 判斷 `--source` 型態：
|
||||
- 對應到本機可讀取的檔案路徑 → 視為檔案，唯讀讀取全文，不寫任何衍生檔。
|
||||
- 純數字、`#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」處理：已勾選視為完成不重做，缺漏才補新項目並標「新增」。
|
||||
2. 使用者選定計畫時，以該計畫頁的 `path` 讀取計畫頁全文，**計畫頁全文併入需求來源**，並在需求彙整中**標明來源**（哪些需求來自計畫頁、哪些來自 `--source`）；讀取失敗（404 或權限不足）時**讀取失敗即停**——立刻停止並回報，不得改用臆測內容或略過。未選計畫時維持只用 `--source`。
|
||||
3. 釐清需求：目標、驗收條件、限制條件、影響範圍任一模糊或缺漏，一律依 `/jsc-shared:spec-ask-user` 詢問使用者。
|
||||
4. 產出需求彙整：目標、驗收條件、限制條件，以及本次 wiki todo 頁的 `scope`。
|
||||
5. 若來源本身有既有 Markdown checklist，依 `/jsc-shared:spec-todo-list`「盤點既有 TODO」處理：已勾選視為完成不重做，缺漏才補新項目並標「新增」。
|
||||
|
||||
## 階段 3：選實作模型
|
||||
|
||||
@@ -103,11 +124,11 @@ scope: <階段 2 產出的 scope>
|
||||
| 規則 | 內容 |
|
||||
| --- | --- |
|
||||
| **模型鎖定** | 本頁 frontmatter 的 `model` 是**強制**的，不是建議。開工前先自我確認當前模型 id。 |
|
||||
| **不符就停** | 當前模型 ≠ `<model>` 時，**立刻停止、不做任何檔案修改或 wiki 修改**，輸出下方錯誤訊息並要求使用者切換。 |
|
||||
| **不符就停** | 當前模型 ≠ `<model>` 時，**立刻停止、不做任何檔案修改或 wiki 修改**，輸出下方錯誤訊息並要求使用者切換。開始任何實作前就要檢查，不可先讀來源或接觸 wiki。 |
|
||||
| **不得自行升降級** | 不可以「先用手上的模型做一點」、不可以自行判定「我這顆更強所以沒關係」。降級與升級同樣禁止。 |
|
||||
| **附加不覆蓋** | 若之後要往本頁追加新需求：`model` 相同 → 附加到頁面末尾；`model` 不同 → 先問使用者是否覆蓋，未得同意不得寫入。 |
|
||||
| **完成即勾選** | 每完成一項就地把該行的 `- [ ]` 改成 `- [x]`，並在行末附上「（完成：yyyy/MM/dd HH:mm:ss）」（Asia/Taipei）。不得留待多項一起補勾。 |
|
||||
| **更新後才能繼續** | 每完成一項後，必須立即把勾選狀態寫回本 wiki 頁並讀回確認成功；若 wiki 更新或讀回確認失敗，**立刻停止，不得繼續執行下一項**。 |
|
||||
| **更新後才能繼續** | 每完成一項後，必須立即把勾選狀態寫回本 wiki 頁並讀回解碼比對成功；若 wiki 更新失敗、讀回失敗或內容不一致，**立刻停止，不得繼續執行下一項**。 |
|
||||
|
||||
[<yyyy/MM/dd HH:mm:ss>][模型檢查][ERR]: 本清單指定 <model>（<alias>），當前模型為 <current-model-id>。
|
||||
請執行 /model <alias> 切換後重新載入本 wiki 頁，本次不進行任何修改。
|
||||
@@ -116,16 +137,16 @@ scope: <階段 2 產出的 scope>
|
||||
### checklist
|
||||
|
||||
- 逐項使用 `- [ ] **編號 短標題**：具體內容`。
|
||||
- 內容需動詞＋對象＋驗收條件齊備，並能舉證對應 `path:line` 或需求彙整中的哪一句。
|
||||
- 內容需動詞＋對象＋實作方式＋驗收條件＋來源依據齊備，並能舉證對應 `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 轉義規則。
|
||||
2. `--wiki-repo` 與目錄頁內容**沿用階段 2-0 的結果**，不重複讀取；`--wiki-index` 未帶時固定使用 `CONTENTS`，`--wiki-page` 未帶時先詢問使用者是否要把新的代辦加入既有的 todo 內；只有使用者選擇新建時才固定使用 `TODO_{yyyyMMdd}_{HASH}`。
|
||||
3. 詢問使用者三個獨立決策：是否關聯到計畫／系統名稱（已於階段 2「選擇尚未產生代辦的計畫」問過則不重問）、是否把新的代辦加入既有的 todo 內，以及是否更新 wiki 目錄頁。使用者回答不加入計畫時，仍預設會更新目錄頁；只有使用者明確回答不要更新目錄頁，才可記錄為「不更新目錄頁」。使用者若明確選既有 todo 頁，該頁就是本次寫入目標，不得自行改成新頁。
|
||||
4. 分頁讀取 `GET /repos/<owner>/<repo>/wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若使用者選擇既有 todo 頁，直接以該頁 title 對應 `sub_url`。目錄頁的 `sub_url`／內容沿用階段 2-0 已讀取的結果；目錄頁不存在時才建立；目錄頁存在時必須保留原內容，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。
|
||||
5. 讀取既有 todo 頁；若不存在，策略為「建立」。
|
||||
6. 既有 todo 頁存在時解析 frontmatter：
|
||||
|
||||
@@ -136,23 +157,25 @@ scope: <階段 2 產出的 scope>
|
||||
| 頁面存在且 frontmatter `model` 不同 | 停下來詢問使用者是否覆蓋、沿用舊模型附加、或取消；未得同意不得寫入。 |
|
||||
| 頁面存在但沒有 frontmatter | 視為不同模型處理。 |
|
||||
|
||||
`--append`／`--overwrite` 已明確回答不同模型分支時，依該旗標執行；`--yes` 不算回答。
|
||||
`--append`／`--overwrite` 已明確回答不同模型分支時，依該旗標執行；`--yes` 不算回答。若使用者選擇既有 todo 頁，仍要沿用這個 frontmatter 模型判斷與寫回驗證流程，不得因為是既有頁就跳過。
|
||||
|
||||
## 階段 6：同步 Gitea wiki
|
||||
|
||||
同步順序固定：
|
||||
|
||||
1. 寫入 todo 頁。
|
||||
2. 若使用者明確表示不要更新目錄頁，跳過目錄頁更新；否則 upsert 目錄頁表格列。目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。
|
||||
3. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認。讀回時若回應含 `content_base64`，必須 base64 解碼後再比對 Markdown 內容是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。
|
||||
2. 若使用者明確表示不要更新目錄頁，跳過目錄頁更新；否則 upsert 目錄頁表格列（TODO 列）。目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。
|
||||
3. 若本次於階段 2「選擇尚未產生代辦的計畫」關聯到某個計畫列，回目錄頁把該計畫列「已產生」由 `[ ]` 改為 `[x]` 並讀回確認；找不到對應計畫列時**不得新建該列**，改以警告回報。未關聯計畫時跳過本步驟。
|
||||
4. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認（含步驟 2、3 的異動）。讀回時若回應含 `content_base64`，必須 base64 解碼後再比對 Markdown 內容是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。
|
||||
5. 一項一回寫、一項一確認；若任一步失敗，立刻停止，不得把多個 checklist 累積後一起處理。
|
||||
|
||||
目錄頁表格列格式：
|
||||
目錄頁的四欄表格格式、TODO 列初始值、以及連結來源（查表取得的 `sub_url`／`path`，不使用 percent-encode 的 title）一律依 `/jsc-shared:spec-wiki-contents`，本 skill 不重複定義；TODO 列範例：
|
||||
|
||||
```markdown
|
||||
| [<關聯計畫的系統名稱>-代辦](<todo page title percent-encoded>) | todo wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |
|
||||
| [<關聯計畫的系統名稱>-代辦](<查表取得的 path>) | | [ ] | todo wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 |
|
||||
```
|
||||
|
||||
若既有目錄頁沒有 `| 頁面 | 內容 |` 表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。
|
||||
若既有目錄頁沒有四欄目錄表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。
|
||||
|
||||
API 寫入方式：
|
||||
|
||||
@@ -171,11 +194,12 @@ API 寫入方式：
|
||||
| --- | --- |
|
||||
| 分析模型 | `analyzed_by` |
|
||||
| 實作模型 | `model` / `model_alias`，並註明推薦或使用者指定 |
|
||||
| 項目數 | 本次新增的 checklist 項目數 |
|
||||
| 已完成項目數 | 本次實際完成且已回寫確認的 checklist 項目數 |
|
||||
| Wiki repo | `<owner/repo>` |
|
||||
| 目錄頁 | URL；若使用者明確不要更新目錄頁，填「未更新（使用者選擇不更新目錄頁）」 |
|
||||
| Todo 頁 | URL |
|
||||
| 本次動作 | 建立／附加／覆蓋 |
|
||||
| 已回寫確認 | `是`／`否`，僅在所有本次 checklist 都完成且讀回比對成功時填 `是` |
|
||||
|
||||
最後提醒：
|
||||
|
||||
|
||||
Reference in New Issue
Block a user