From cb3aecef8999a41bcde5af42c0d161947643d1dd Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 14 Aug 2026 18:33:53 +0800 Subject: [PATCH 01/10] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20?= =?UTF-8?q?=E4=B8=89=E5=AE=B6=20manifest=20=E5=8D=87=E7=89=88=200.1.5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- plugin.meta.json | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index f6b9c30..5b506ee 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -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": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index d32b03e..644f737 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -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" } diff --git a/plugin.json b/plugin.json index 01b5e51..aa1156f 100644 --- a/plugin.json +++ b/plugin.json @@ -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" } diff --git a/plugin.meta.json b/plugin.meta.json index 9f3ca8a..563c5cd 100644 --- a/plugin.meta.json +++ b/plugin.meta.json @@ -1,7 +1,7 @@ { "name": "jsc-shared", "shortName": "shared", - "version": "0.1.4", + "version": "0.1.5", "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:", From 60df01a21ae8936b8076f9e02d5d613dafb5b87c Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 14 Aug 2026 18:53:16 +0800 Subject: [PATCH 02/10] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20?= =?UTF-8?q?=E4=B8=89=E5=AE=B6=20manifest=20=E5=8D=87=E7=89=88=200.1.6?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- plugin.meta.json | 2 +- skills/plan-wiki/SKILL.md | 7 +++++-- skills/todo-wiki/SKILL.md | 18 +++++++++++------- 6 files changed, 20 insertions(+), 13 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 5b506ee..fdad75e 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.5", + "version": "0.1.6", "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": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 644f737..50d1e24 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.5", + "version": "0.1.6", "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" } diff --git a/plugin.json b/plugin.json index aa1156f..a9b1066 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.5", + "version": "0.1.6", "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" } diff --git a/plugin.meta.json b/plugin.meta.json index 563c5cd..e478071 100644 --- a/plugin.meta.json +++ b/plugin.meta.json @@ -1,7 +1,7 @@ { "name": "jsc-shared", "shortName": "shared", - "version": "0.1.5", + "version": "0.1.6", "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:", diff --git a/skills/plan-wiki/SKILL.md b/skills/plan-wiki/SKILL.md index 93fa7af..15cdc24 100644 --- a/skills/plan-wiki/SKILL.md +++ b/skills/plan-wiki/SKILL.md @@ -31,7 +31,8 @@ argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫 - 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本計畫既有列或在既有表格附加新列。 - **不落地絕對規則**：不得建立本機 `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` 從環境變數或既有設定取得。 ## 參數 @@ -45,7 +46,7 @@ argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫 | `--project` | 計畫名稱；未帶時從計畫內容尋找或產生系統名稱，用於目錄列標題與摘要。 | | `--page` | 計畫頁 title；未帶時固定使用 `PLAN-{yyyyMMdd}-{HASH}`，不詢問。 | | `--host` | Gitea 主機，依 `spec-gitea` host 決定順序處理。 | -| `--yes` | 略過一般性確認；不得略過目標 wiki 不明、寫入衝突或使用者尚未確認的計畫完成判斷。 | +| `--yes` | 略過一般性確認；不得略過目標 wiki 不明、寫入衝突、同步失敗後的停止，或使用者尚未確認的計畫完成判斷。 | ## 階段 A：前置設定 @@ -120,6 +121,7 @@ argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫 - 把仍不明確的點列入 `## 待確認`。 - 產出或更新 `## TODO` checklist，格式依 `spec-todo-list`。 - 詢問使用者下一輪問題前，先完成階段 D 的 wiki 同步。 +- 如果某輪資料不足，先把不確定內容放進 `## 待確認`，不得自行補完再繼續問下一輪。 使用者明確表示「完成」「先到這裡」「計畫完成」時，進入階段 E；不要再追問非必要細節。 @@ -130,6 +132,7 @@ argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫 1. 更新計畫頁。 2. 更新目錄頁：不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<系統名稱>-計畫` 列，或在既有表格／頁末附加新列，確保有本計畫頁連結與摘要。 3. 再次讀回兩個頁面確認內容已更新。讀回時若回應含 `content_base64`，必須 base64 解碼後比對正文 Markdown 是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。 +4. 每輪只允許一輪同步結果對應下一輪提問；若 wiki 寫入失敗、讀回失敗或內容比對不一致，必須停止下一輪詢問，先回報錯誤與待處理點。 API 寫入方式： diff --git a/skills/todo-wiki/SKILL.md b/skills/todo-wiki/SKILL.md index b1d726a..682ac69 100644 --- a/skills/todo-wiki/SKILL.md +++ b/skills/todo-wiki/SKILL.md @@ -30,6 +30,8 @@ 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 前，先確認目前執行本 skill 的模型 id；無法確定時先請使用者執行 `/status`，不得用猜的。 +- **一項一回寫、一項一確認**：每完成一項 checklist，就立刻把該項 `- [ ]` 改成 `- [x]`，立即回寫 wiki，讀回解碼比對成功後才能繼續下一項；不可累積多項後一次回寫。 - 目標 wiki repo 不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。 - 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--wiki-index` 時才覆蓋預設值。 - TODO 頁 title 預設固定為 `TODO-{yyyyMMdd}-{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由需求彙整、關聯計畫或系統名稱產生穩定短雜湊並轉成全大寫。 @@ -47,17 +49,17 @@ 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 不明、是否關聯到計畫／系統名稱、是否更新 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：分析需求 @@ -103,11 +105,11 @@ scope: <階段 2 產出的 scope> | 規則 | 內容 | | --- | --- | | **模型鎖定** | 本頁 frontmatter 的 `model` 是**強制**的，不是建議。開工前先自我確認當前模型 id。 | -| **不符就停** | 當前模型 ≠ `` 時，**立刻停止、不做任何檔案修改或 wiki 修改**，輸出下方錯誤訊息並要求使用者切換。 | +| **不符就停** | 當前模型 ≠ `` 時，**立刻停止、不做任何檔案修改或 wiki 修改**，輸出下方錯誤訊息並要求使用者切換。開始任何實作前就要檢查，不可先讀來源或接觸 wiki。 | | **不得自行升降級** | 不可以「先用手上的模型做一點」、不可以自行判定「我這顆更強所以沒關係」。降級與升級同樣禁止。 | | **附加不覆蓋** | 若之後要往本頁追加新需求：`model` 相同 → 附加到頁面末尾；`model` 不同 → 先問使用者是否覆蓋，未得同意不得寫入。 | | **完成即勾選** | 每完成一項就地把該行的 `- [ ]` 改成 `- [x]`，並在行末附上「（完成：yyyy/MM/dd HH:mm:ss）」（Asia/Taipei）。不得留待多項一起補勾。 | -| **更新後才能繼續** | 每完成一項後，必須立即把勾選狀態寫回本 wiki 頁並讀回確認成功；若 wiki 更新或讀回確認失敗，**立刻停止，不得繼續執行下一項**。 | +| **更新後才能繼續** | 每完成一項後，必須立即把勾選狀態寫回本 wiki 頁並讀回解碼比對成功；若 wiki 更新失敗、讀回失敗或內容不一致，**立刻停止，不得繼續執行下一項**。 | [][模型檢查][ERR]: 本清單指定 （），當前模型為 。 請執行 /model 切換後重新載入本 wiki 頁，本次不進行任何修改。 @@ -145,6 +147,7 @@ scope: <階段 2 產出的 scope> 1. 寫入 todo 頁。 2. 若使用者明確表示不要更新目錄頁，跳過目錄頁更新；否則 upsert 目錄頁表格列。目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。 3. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認。讀回時若回應含 `content_base64`，必須 base64 解碼後再比對 Markdown 內容是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。 +4. 一項一回寫、一項一確認；若任一步失敗，立刻停止，不得把多個 checklist 累積後一起處理。 目錄頁表格列格式： @@ -171,11 +174,12 @@ API 寫入方式： | --- | --- | | 分析模型 | `analyzed_by` | | 實作模型 | `model` / `model_alias`，並註明推薦或使用者指定 | -| 項目數 | 本次新增的 checklist 項目數 | +| 已完成項目數 | 本次實際完成且已回寫確認的 checklist 項目數 | | Wiki repo | `` | | 目錄頁 | URL；若使用者明確不要更新目錄頁，填「未更新（使用者選擇不更新目錄頁）」 | | Todo 頁 | URL | | 本次動作 | 建立／附加／覆蓋 | +| 已回寫確認 | `是`／`否`，僅在所有本次 checklist 都完成且讀回比對成功時填 `是` | 最後提醒： From 66af00cfdd4ad62007fc02e0c92828fcdafefee2 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 17 Aug 2026 09:18:28 +0800 Subject: [PATCH 03/10] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20?= =?UTF-8?q?=E4=B8=89=E5=AE=B6=20manifest=20=E5=8D=87=E7=89=88=200.1.7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- plugin.meta.json | 2 +- skills/spec-todo-list/SKILL.md | 4 +++- skills/todo-wiki/SKILL.md | 19 ++++++++++--------- 6 files changed, 17 insertions(+), 14 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index fdad75e..2353fbf 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.6", + "version": "0.1.7", "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": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 50d1e24..1ba7951 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.6", + "version": "0.1.7", "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" } diff --git a/plugin.json b/plugin.json index a9b1066..cc0e863 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.6", + "version": "0.1.7", "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" } diff --git a/plugin.meta.json b/plugin.meta.json index e478071..b7d733e 100644 --- a/plugin.meta.json +++ b/plugin.meta.json @@ -1,7 +1,7 @@ { "name": "jsc-shared", "shortName": "shared", - "version": "0.1.6", + "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:", diff --git a/skills/spec-todo-list/SKILL.md b/skills/spec-todo-list/SKILL.md index c5801a7..66b28b5 100644 --- a/skills/spec-todo-list/SKILL.md +++ b/skills/spec-todo-list/SKILL.md @@ -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 使用時，建議格式可寫成 `- [ ] **編號 短標題**：具體內容；實作方式：...；驗收條件：...；來源依據：...；建議修改內容：...`；若確實沒有明確修改方向，`建議修改內容` 可省略，但 `實作方式` 不可省略。 ## 禁止憑空編造 diff --git a/skills/todo-wiki/SKILL.md b/skills/todo-wiki/SKILL.md index 682ac69..2a3ba98 100644 --- a/skills/todo-wiki/SKILL.md +++ b/skills/todo-wiki/SKILL.md @@ -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 ] [--wiki-repo ] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO--] [--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 ] [--wiki-repo ] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page <既有頁 title|TODO-->] [--append|--overwrite] [--yes]" --- # todo-wiki — 需求分析並同步指定模型 TODO 到 Gitea wiki @@ -29,13 +29,14 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode - **不落地絕對規則**：不得建立或更新本機 `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 內，以及是否更新 wiki 目錄頁；使用者回答不加入計畫時，仍預設更新 wiki 目錄頁，除非使用者另行明確說不要更新目錄頁。 - 需要加入目錄頁時，目錄標題使用 `{關聯計畫的系統名稱}-代辦`，並連結到 TODO 頁。系統名稱優先從關聯計畫取得；若沒有關聯計畫，從需求內容尋找或產生系統名稱。 - 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本 TODO 既有列或在既有表格附加新列。 @@ -50,7 +51,7 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode | `--wiki-repo` | 指定要同步的 Gitea wiki repo，例如 `knowledges/Plan`。 | | `--wiki-index` | wiki 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 | | `--wiki-project` | 關聯計畫或系統名稱；預設仍會更新目錄頁，只有使用者明確表示不要更新目錄頁時才可略過。 | -| `--wiki-page` | todo 頁 title；未帶時固定使用 `TODO-{yyyyMMdd}-{HASH}`，不詢問。 | +| `--wiki-page` | todo 頁 title；可指向既有 todo 頁 title，未帶時先詢問是否加入既有 todo，只有使用者選擇新建時才固定使用 `TODO-{yyyyMMdd}-{HASH}`。 | | `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。 | | `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否關聯到計畫／系統名稱、是否更新 wiki 目錄頁，或對外寫入目標不明等必要決策。 | @@ -118,16 +119,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///wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若目錄頁更新決策為開啟，也取得目錄頁 `sub_url`。目錄頁不存在時才建立；目錄頁存在時必須讀取原內容並保留，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。 +2. 確認 `--wiki-repo`；缺少就詢問。`--wiki-index` 未帶時固定使用 `CONTENTS`，`--wiki-page` 未帶時先詢問使用者是否要把新的代辦加入既有的 todo 內；只有使用者選擇新建時才固定使用 `TODO-{yyyyMMdd}-{HASH}`。 +3. 詢問使用者三個獨立決策：是否關聯到計畫／系統名稱、是否把新的代辦加入既有的 todo 內，以及是否更新 wiki 目錄頁。使用者回答不加入計畫時，仍預設會更新目錄頁；只有使用者明確回答不要更新目錄頁，才可記錄為「不更新目錄頁」。使用者若明確選既有 todo 頁，該頁就是本次寫入目標，不得自行改成新頁。 +4. 分頁讀取 `GET /repos///wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若使用者選擇既有 todo 頁，直接以該頁 title 對應 `sub_url`；若目錄頁更新決策為開啟，也取得目錄頁 `sub_url`。目錄頁不存在時才建立；目錄頁存在時必須讀取原內容並保留，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。 5. 讀取既有 todo 頁；若不存在，策略為「建立」。 6. 既有 todo 頁存在時解析 frontmatter： @@ -138,7 +139,7 @@ scope: <階段 2 產出的 scope> | 頁面存在且 frontmatter `model` 不同 | 停下來詢問使用者是否覆蓋、沿用舊模型附加、或取消；未得同意不得寫入。 | | 頁面存在但沒有 frontmatter | 視為不同模型處理。 | -`--append`／`--overwrite` 已明確回答不同模型分支時，依該旗標執行；`--yes` 不算回答。 +`--append`／`--overwrite` 已明確回答不同模型分支時，依該旗標執行；`--yes` 不算回答。若使用者選擇既有 todo 頁，仍要沿用這個 frontmatter 模型判斷與寫回驗證流程，不得因為是既有頁就跳過。 ## 階段 6：同步 Gitea wiki From 029ef5a775d53654b1d257e282411c7bf056e3ce Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 17 Aug 2026 11:20:27 +0800 Subject: [PATCH 04/10] =?UTF-8?q?feat(do-wiki):=20=E6=96=B0=E5=A2=9E?= =?UTF-8?q?=E4=BE=9D=20wiki=20TODO=20=E6=B8=85=E5=96=AE=E9=80=90=E9=A0=85?= =?UTF-8?q?=E5=9F=B7=E8=A1=8C=E7=9A=84=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 作為 todo-wiki 的執行端對應物：讀取鎖定模型的 wiki TODO 頁、檢查強制規則、 逐項執行並即時回寫勾選，全部完成後回目錄頁把該代辦列標記已完成。 Co-Authored-By: Claude Sonnet 5 --- skills/do-wiki/SKILL.md | 90 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 skills/do-wiki/SKILL.md diff --git a/skills/do-wiki/SKILL.md b/skills/do-wiki/SKILL.md new file mode 100644 index 0000000..de7b5df --- /dev/null +++ b/skills/do-wiki/SKILL.md @@ -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 ] [--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 ] [--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 / --fields title,path`（或對應 REST API）**分頁完整查表**，用 title 比對取得 `path`；明文禁止自行推導 title 到 `path` 的轉義規則。 +2. 以 `tea wiki view`（或 `GET /repos///wiki/page/`）讀取該頁完整內容。 +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///wiki/page/`）寫回整份頁面內容。**`tea wiki edit` 陷阱**：其用法為 `tea wiki edit [options] `，`` 需帶 `path`；若省略 `--title`，tea 會把 `` 當成新 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 的代辦」）自動觸發 | From 2fa73f443d21d6bf27e61b684ac0303fc72da53f Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 17 Aug 2026 11:20:34 +0800 Subject: [PATCH 05/10] =?UTF-8?q?feat(spec-wiki-contents):=20=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=20wiki=20=E7=9B=AE=E9=8C=84=E9=A0=81=E5=9B=9B?= =?UTF-8?q?=E6=AC=84=E6=A0=BC=E5=BC=8F=E8=88=87=E5=88=97=E5=9E=8B=E5=88=A5?= =?UTF-8?q?=E5=88=A4=E5=AE=9A=E5=85=B1=E7=94=A8=E8=A6=8F=E7=AF=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 收斂 plan-wiki／todo-wiki／do-wiki 三個 skill 共用的目錄頁四欄表格格式、 計畫列／TODO 列型別判定、連結來源（查表 path）與回寫規則，避免各自重複。 Co-Authored-By: Claude Sonnet 5 --- skills/spec-wiki-contents/SKILL.md | 52 ++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 skills/spec-wiki-contents/SKILL.md diff --git a/skills/spec-wiki-contents/SKILL.md b/skills/spec-wiki-contents/SKILL.md new file mode 100644 index 0000000..3f44f13 --- /dev/null +++ b/skills/spec-wiki-contents/SKILL.md @@ -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]` 並讀回確認；只要還有未勾項目就不得勾選。 +- 兩者都必須讀回確認寫入成功，失敗立刻停止，不得繼續下一步。 From 59f080705441c1fae451f032af3b9e7a370193bb Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 17 Aug 2026 11:20:45 +0800 Subject: [PATCH 06/10] =?UTF-8?q?refactor(todo-wiki):=20=E9=96=8B=E5=B7=A5?= =?UTF-8?q?=E5=89=8D=E6=8C=91=E8=A8=88=E7=95=AB=E3=80=81=E6=94=B9=E7=94=A8?= =?UTF-8?q?=20spec-wiki-contents=E3=80=81=E5=91=BD=E5=90=8D=E6=94=B9=20=5F?= =?UTF-8?q?=20=E5=88=86=E9=9A=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit TODO 頁 title 命名改用 TODO_{yyyyMMdd}_{HASH}；目錄頁四欄格式與列型別判定 改為引用 spec-wiki-contents；新增階段 2-0 提前確認 wiki repo 並讀目錄頁、 開工前挑選尚未產生代辦的計畫並把計畫頁全文併入需求來源、寫入成功後回寫 該計畫列「已產生」。 Co-Authored-By: Claude Sonnet 5 --- skills/todo-wiki/SKILL.md | 57 ++++++++++++++++++++++++++------------- 1 file changed, 38 insertions(+), 19 deletions(-) diff --git a/skills/todo-wiki/SKILL.md b/skills/todo-wiki/SKILL.md index 2a3ba98..7597fe6 100644 --- a/skills/todo-wiki/SKILL.md +++ b/skills/todo-wiki/SKILL.md @@ -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 ] [--wiki-repo ] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page <既有頁 title|TODO-->] [--append|--overwrite] [--yes]" +argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-model ] [--wiki-repo ] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page <既有頁 title|TODO__>] [--append|--overwrite] [--yes]" --- # todo-wiki — 需求分析並同步指定模型 TODO 到 Gitea wiki @@ -22,7 +22,7 @@ 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 特有補充： @@ -35,14 +35,16 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode - **一項一回寫、一項一確認**：每完成一項 checklist，就立刻把該項 `- [ ]` 改成 `- [x]`，立即回寫 wiki，讀回解碼比對成功後才能繼續下一項；不可累積多項後一次回寫。 - 目標 wiki repo 不明時必須詢問；不得因為目前工作目錄是某 repo 就臆測 wiki 目標。 - 目錄頁 title 預設固定為 `CONTENTS`，不詢問使用者；只有使用者明確提供 `--wiki-index` 時才覆蓋預設值。 -- TODO 頁 title 預設固定為 `TODO-{yyyyMMdd}-{HASH}`，不詢問使用者；`yyyyMMdd` 使用 Asia/Taipei 當日日期，`HASH` 由需求彙整、關聯計畫或系統名稱產生穩定短雜湊並轉成全大寫。 +- 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 頁。系統名稱優先從關聯計畫取得；若沒有關聯計畫，從需求內容尋找或產生系統名稱。 +- 需要加入目錄頁時，目錄標題使用 `{關聯計畫的系統名稱}-代辦`，並連結到 TODO 頁。**系統名稱優先取自使用者於階段 2 選定的計畫列**；若沒有選定計畫，從需求內容尋找或產生系統名稱。 - 目錄頁禁止整頁覆蓋：不存在時才新建；存在時必須保留既有內容，只修改本 TODO 既有列或在既有表格附加新列。 ## 參數 -`[--source <需求描述|檔案路徑|議題編號>] [--impl-model ] [--wiki-repo ] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO--] [--append|--overwrite] [--yes]` +`[--source <需求描述|檔案路徑|議題編號>] [--impl-model ] [--wiki-repo ] [--wiki-index CONTENTS] [--wiki-project <關聯計畫或系統名稱>] [--wiki-page TODO__] [--append|--overwrite] [--yes]` | 參數 | 說明 | | --- | --- | @@ -51,7 +53,7 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode | `--wiki-repo` | 指定要同步的 Gitea wiki repo，例如 `knowledges/Plan`。 | | `--wiki-index` | wiki 目錄頁 title；未帶時固定使用 `CONTENTS`，不詢問。 | | `--wiki-project` | 關聯計畫或系統名稱；預設仍會更新目錄頁，只有使用者明確表示不要更新目錄頁時才可略過。 | -| `--wiki-page` | todo 頁 title；可指向既有 todo 頁 title，未帶時先詢問是否加入既有 todo，只有使用者選擇新建時才固定使用 `TODO-{yyyyMMdd}-{HASH}`。 | +| `--wiki-page` | todo 頁 title；可指向既有 todo 頁 title，未帶時先詢問是否加入既有 todo，只有使用者選擇新建時才固定使用 `TODO_{yyyyMMdd}_{HASH}`。 | | `--append` / `--overwrite` | 針對既有 wiki todo 頁 frontmatter `model` 不同的情境提前作答。二擇一，同時提供視為衝突，仍需詢問使用者。 | | `--yes` | 略過一般性確認；不得略過模型不同是否覆蓋、目標 wiki 不明、是否關聯到計畫／系統名稱、是否更新 wiki 目錄頁，或對外寫入目標不明等必要決策。 | @@ -65,13 +67,29 @@ argument-hint: "[--source <需求描述|檔案路徑|議題編號>] [--impl-mode ## 階段 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：選實作模型 @@ -126,9 +144,9 @@ scope: <階段 2 產出的 scope> ## 階段 5：讀取既有 wiki 頁並決定寫入策略 1. 依 `spec-gitea` 決定 host 與 token，不輸出 token。 -2. 確認 `--wiki-repo`；缺少就詢問。`--wiki-index` 未帶時固定使用 `CONTENTS`，`--wiki-page` 未帶時先詢問使用者是否要把新的代辦加入既有的 todo 內；只有使用者選擇新建時才固定使用 `TODO-{yyyyMMdd}-{HASH}`。 -3. 詢問使用者三個獨立決策：是否關聯到計畫／系統名稱、是否把新的代辦加入既有的 todo 內，以及是否更新 wiki 目錄頁。使用者回答不加入計畫時，仍預設會更新目錄頁；只有使用者明確回答不要更新目錄頁，才可記錄為「不更新目錄頁」。使用者若明確選既有 todo 頁，該頁就是本次寫入目標，不得自行改成新頁。 -4. 分頁讀取 `GET /repos///wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若使用者選擇既有 todo 頁，直接以該頁 title 對應 `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///wiki/pages`，以 title 查表取得 todo 頁 `sub_url`；若使用者選擇既有 todo 頁，直接以該頁 title 對應 `sub_url`。目錄頁的 `sub_url`／內容沿用階段 2-0 已讀取的結果；目錄頁不存在時才建立；目錄頁存在時必須保留原內容，不得用新目錄內容整頁覆蓋。不得為了找頁面自行猜測 title 轉義規則。 5. 讀取既有 todo 頁；若不存在，策略為「建立」。 6. 既有 todo 頁存在時解析 frontmatter： @@ -146,17 +164,18 @@ scope: <階段 2 產出的 scope> 同步順序固定： 1. 寫入 todo 頁。 -2. 若使用者明確表示不要更新目錄頁，跳過目錄頁更新；否則 upsert 目錄頁表格列。目錄頁不存在才建立；存在時禁止整頁覆蓋，只修改既有 `<關聯計畫的系統名稱>-代辦` 列，或在既有表格／頁末附加新列。 -3. 讀回 todo 頁確認內容已更新；有更新目錄頁時也讀回目錄頁確認。讀回時若回應含 `content_base64`，必須 base64 解碼後再比對 Markdown 內容是否與預期一致；若回應格式不同，依 Gitea 官方 API 文件取出正文再比對，不可只確認狀態碼或頁面存在。 -4. 一項一回寫、一項一確認；若任一步失敗，立刻停止，不得把多個 checklist 累積後一起處理。 +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 wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 | +| [<關聯計畫的系統名稱>-代辦](<查表取得的 path>) | | [ ] | todo wiki：<關聯計畫的系統名稱> 代辦——執行規則、需求彙整、分群任務與驗收條件 | ``` -若既有目錄頁沒有 `| 頁面 | 內容 |` 表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。 +若既有目錄頁沒有四欄目錄表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。 API 寫入方式： From 508527df7cce18975e823f22912bb0204eb57b9a Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 17 Aug 2026 11:20:52 +0800 Subject: [PATCH 07/10] =?UTF-8?q?refactor(plan-wiki):=20=E6=94=B9=E7=94=A8?= =?UTF-8?q?=20spec-wiki-contents=E3=80=81=E5=91=BD=E5=90=8D=E6=94=B9=20=5F?= =?UTF-8?q?=20=E5=88=86=E9=9A=94?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 計畫頁 title 命名改用 PLAN_{yyyyMMdd}_{HASH}；目錄頁四欄格式、 「已產生」欄初始值與連結來源（查表 path）改為引用 spec-wiki-contents， 不再自行定義與 percent-encode title。 Co-Authored-By: Claude Sonnet 5 --- skills/plan-wiki/SKILL.md | 28 ++++++++-------------------- 1 file changed, 8 insertions(+), 20 deletions(-) diff --git a/skills/plan-wiki/SKILL.md b/skills/plan-wiki/SKILL.md index 15cdc24..3b2f2bc 100644 --- a/skills/plan-wiki/SKILL.md +++ b/skills/plan-wiki/SKILL.md @@ -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 ] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN--] [--host ] [--yes]" +argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN__] [--host ] [--yes]" --- # plan-wiki — 逐步建立計畫並同步到 Gitea wiki @@ -20,13 +20,13 @@ argument-hint: "[--wiki-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`。 @@ -37,14 +37,14 @@ argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫 ## 參數 -`[--wiki-repo ] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN--] [--host ] [--yes]` +`[--wiki-repo ] [--index CONTENTS] [--project <計畫名稱>] [--page PLAN__] [--host ] [--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 不明、寫入衝突、同步失敗後的停止，或使用者尚未確認的計畫完成判斷。 | @@ -53,7 +53,7 @@ argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫 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//` 驗證 token 對 repo 有權限；失敗時遮蔽機密後回報並停止。 @@ -66,21 +66,9 @@ argument-hint: "[--wiki-repo ] [--index CONTENTS] [--project <計畫 ## 目錄頁格式 -目錄頁不存在時建立下列結構；更新既有目錄頁時禁止整頁覆蓋，必須保留既有標題、說明、表格與其他內容，只新增或更新本計畫相關列： +目錄頁的四欄表格格式、「已產生」欄初始值、列型別判定、以及連結來源（查表取得的 `sub_url`／`path`，不使用 percent-encode 的 title）一律依 `/jsc-shared:spec-wiki-contents`，本 skill 不重複定義。 -```markdown -# CONTENTS - -計畫目錄。 - -| 頁面 | 內容 | -|------|------| -| [<系統名稱>-計畫]() | plan wiki：<系統名稱> 計畫 | - -產出日期：yyyy-MM-dd -``` - -若目錄頁已存在且不是單一計畫專用目錄，仍以同一張 `| 頁面 | 內容 |` 表格為準：保留原標題與說明，只在表格中 upsert 本計畫頁面列。若既有目錄頁沒有 `| 頁面 | 內容 |` 表格，附加一段新的目錄表格到頁面末尾，不得刪除或重排既有內容。連結文字固定為 `<系統名稱>-計畫`；連結 target 用 `encodeURIComponent(title).replace(/%20/g, "%20")` 的結果，不使用 API `sub_url` 反推人工連結。 +目錄頁不存在時，依 `spec-wiki-contents`〔目錄頁格式〕建立新頁，並在計畫列「已產生」欄填 `[ ]`（表示尚未產生對應 TODO）、「已完成」欄留空；目錄頁已存在時禁止整頁覆蓋，只能 upsert 既有的 `<系統名稱>-計畫` 列或在既有表格附加新列，保留其餘標題、說明與內容。 ## 計畫頁格式 From 17a4cd58d019b4728379302cbef762c29cce1e47 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 17 Aug 2026 11:20:58 +0800 Subject: [PATCH 08/10] =?UTF-8?q?docs(README):=20=E8=A3=9C=E4=B8=8A=20do-w?= =?UTF-8?q?iki=20=E8=AA=AA=E6=98=8E=E5=88=97=E8=88=87=E9=96=8B=E5=B7=A5?= =?UTF-8?q?=E5=89=8D=E9=81=B8=E5=96=AE=EF=BC=8F=E7=9B=AE=E9=8C=84=E9=A0=81?= =?UTF-8?q?=20check=20=E6=AC=84=E4=BD=8D=E8=AA=AA=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 do-wiki 一列；plan-wiki／todo-wiki 列補上目錄頁四欄「已產生／已完成」 check 欄位行為；todo-wiki／do-wiki 列補上開工前挑選提示。 Co-Authored-By: Claude Sonnet 5 --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 98c5b99..7c6ed0c 100644 --- a/README.md +++ b/README.md @@ -140,8 +140,9 @@ shared/ | Skill | 用途 | 使用方法 | | --- | --- | --- | | `models` | 查詢目前可用哪些模型並依 `spec-model` 的標籤體系標註，維護 `~/.claude/jsc/models.json` 快取，依任務類型推薦模型或檢查當前模型是否符合指定模型。是 `spec-model` 的唯一可執行入口——其他 skill 需要模型清單或推薦時一律呼叫本 skill，不自行重寫探測或推薦邏輯 | `/jsc-shared:models`；可帶 `--refresh`（重跑探測與 smoke test）、`--task `（依對映表推薦模型）、`--check `（比對指定模型與當前模型）、`--json` | -| `plan-wiki` | 逐步詢問使用者計畫內容，並把每一輪已確認的計畫草稿直接同步到指定 Gitea wiki 的目錄頁與計畫頁；全程不建立本機計畫檔、草稿檔、暫存 JSON body 或 wiki clone | `/jsc-shared:plan-wiki`；可帶 `--wiki-repo `、`--index <目錄頁title>`、`--project <計畫名稱>`、`--page <計畫頁title>`、`--host `、`--yes` | -| `todo-wiki` | 把「需求 → 分析 → 產生鎖定模型的 TODO 清單 → 同步到 Gitea wiki 目錄與頁面」固定成不落地檔案的流程；不產生本機 `todo.md`，只寫入指定 wiki 目錄頁與 todo 頁 | `/jsc-shared:todo-wiki`；可帶 `--source <需求描述\|檔案路徑\|議題編號>`、`--impl-model `、`--wiki-repo `、`--wiki-index <目錄頁title>`、`--wiki-project <計畫名稱>`、`--wiki-page `、`--append\|--overwrite`、`--yes` | +| `plan-wiki` | 逐步詢問使用者計畫內容，並把每一輪已確認的計畫草稿直接同步到指定 Gitea wiki 的目錄頁與計畫頁；目錄頁為四欄表格，計畫列的「已產生」欄初始為 `[ ]`，待 `todo-wiki` 依該計畫產生 TODO 頁後才改為 `[x]`；全程不建立本機計畫檔、草稿檔、暫存 JSON body 或 wiki clone | `/jsc-shared:plan-wiki`；可帶 `--wiki-repo `、`--index <目錄頁title>`、`--project <計畫名稱>`、`--page <計畫頁title>`、`--host `、`--yes` | +| `todo-wiki` | 把「需求 → 分析 → 產生鎖定模型的 TODO 清單 → 同步到 Gitea wiki 目錄與頁面」固定成不落地檔案的流程；開工前先從目錄頁挑一個尚未產生代辦的計畫（可不選），目錄頁的 TODO 列「已完成」欄初始為 `[ ]`，待 `do-wiki` 執行完該 TODO 頁全部項目後才改為 `[x]`；不產生本機 `todo.md`，只寫入指定 wiki 目錄頁與 todo 頁 | `/jsc-shared:todo-wiki`；可帶 `--source <需求描述\|檔案路徑\|議題編號>`、`--impl-model `、`--wiki-repo `、`--wiki-index <目錄頁title>`、`--wiki-project <計畫名稱>`、`--wiki-page `、`--append\|--overwrite`、`--yes` | +| `do-wiki` | 讀取 `todo-wiki` 產生、帶鎖定模型 frontmatter 的 Gitea wiki TODO 頁並逐項執行；開工前先從目錄頁挑一份未完成的代辦，沒有就直接結束；比對當前模型與頁面 `model` 不符就停止；每完成一項就地勾選並立即回寫該 wiki 頁、讀回確認成功才繼續下一項；全部完成後回目錄頁把該代辦列「已完成」改為 `[x]` | `/jsc-shared:do-wiki`；可帶 `--wiki-repo `、`--wiki-page `、`--yes` | ### 整組 plugin 安裝管理 From b34f4f4af842a0831c3e22cd91886d6aea2314ed Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 17 Aug 2026 11:21:07 +0800 Subject: [PATCH 09/10] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20?= =?UTF-8?q?=E4=B8=89=E5=AE=B6=20manifest=20=E5=8D=87=E7=89=88=200.1.8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 新增 do-wiki、spec-wiki-contents 兩個 skill，並調整 plan-wiki／todo-wiki 內容，對照 master 現行版本 0.1.4 與本機既有 0.1.7 升版至 0.1.8。 Co-Authored-By: Claude Sonnet 5 --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 2353fbf..317f0ca 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.7", + "version": "0.1.8", "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": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 1ba7951..eff1b31 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.7", + "version": "0.1.8", "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" } diff --git a/plugin.json b/plugin.json index cc0e863..e452aae 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.7", + "version": "0.1.8", "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" } From 3790ff733fe3c13fd206dca8b072ef6fd91fa3ff Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 17 Aug 2026 11:37:27 +0800 Subject: [PATCH 10/10] =?UTF-8?q?chore(plugin=20=E7=89=88=E6=9C=AC):=20?= =?UTF-8?q?=E6=9B=B4=E6=AD=A3=E4=B8=89=E5=AE=B6=20manifest=20=E7=89=88?= =?UTF-8?q?=E8=99=9F=E7=82=BA=200.1.5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 同一 PR（develop -> master，#7）先前已累積多次未合併的版號變更；依 spec-plugin-version「同一 PR 只以 master 版本計算一次最終升版」， 以 master 現行版本 0.1.4 為基準改為 0.1.5，取代先前誤算的 0.1.8。 Co-Authored-By: Claude Sonnet 5 --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 317f0ca..5b506ee 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.8", + "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": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index eff1b31..644f737 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.8", + "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" } diff --git a/plugin.json b/plugin.json index e452aae..aa1156f 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-shared", - "version": "0.1.8", + "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" }