plugins/doc
2
0
Fork 0
Code Pull Requests Activity

refactor(shared): switch doc skills to jsc-shared

Browse Source
This commit is contained in:
jiantw83
2026-07-31 17:36:08 +00:00
parent 7ee80a87ee
commit 7b2ab8bf38
5 changed files with 44 additions and 44 deletions
Download Patch File Download Diff File Expand all files Collapse all files
skills/issues-sync/SKILL.md
+13 -13
View File
@@ -7,14 +7,14 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
你要讀取使用者提供的一個 Gitea **專案（project）**或**單一議題**，取得要同步的議題清單，然後一個議題派一個 subagent，**以目前工作目錄下的所有檔案為依據**，勾稽並更新每個議題的 TODO（markdown 任務清單）與標籤，最後把 TODO 的異動整理成留言。例外：輸入為專案且使用者指定「關閉專案／專案完成」時，進入**專案完成模式**（見第 1 步之後的專節），跳過標籤分組與逐議題勾稽，改為批次搬移至「已完成」並關閉議題。**修改議題正文、變更議題標籤、留言都是對外且不易復原的動作，subagent 只回傳同步計畫（不落地任何檔案），實際寫入 Gitea 前必須先讓使用者確認**。請依下列階段依序完成。
## 共用規範（generic plugin，必要前置）
## 共用規範（shared plugin，必要前置）
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（generic plugin 未安裝）時，先詢問使用者是否安裝 generic plugin（`https://gitea.jsc.idv.tw/plugins/generic.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
- `/jsc-generic:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。
- `/jsc-generic:spec-execution`：不臆測／需人工確認。
- `/jsc-generic:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（分頁完整讀取、GET 探測版本相依端點）。
- `/jsc-generic:spec-project-board`：看板欄位語意對應與建議欄位規則、404／501 視為不支援、不得新建欄位。
- `/jsc-shared:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、Mermaid 呈現、個資（PII）去識別化。
- `/jsc-shared:spec-execution`：不臆測／需人工確認。
- `/jsc-shared:spec-gitea`：`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 呼叫慣例（分頁完整讀取、GET 探測版本相依端點）。
- `/jsc-shared:spec-project-board`：看板欄位語意對應與建議欄位規則、404／501 視為不支援、不得新建欄位。
## 絕對準則（不可違反）
@@ -27,10 +27,10 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
- **工具優先序**：
1. 若該 host 在 `tea login list` 中有對應 login，優先用 `tea`（`tea issues`、`tea comment`、`tea labels` 等），並以 `--login <name> --repo <owner>/<repo>` 指定目標。
2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定；未設定則停下請使用者提供）。
- **不要依賴 `jq`**：依 `/jsc-generic:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。
- **不要依賴 `jq`**：依 `/jsc-shared:spec-gitea`（JSON 用 tea 結構化輸出或交給 subagent 解析，不 pipe 到 `jq`）。
- **TODO 的定義**：議題正文（body）中的 markdown 任務清單項目，`- [ ]`（未完成）與 `- [x]`（已完成）。本 skill 所有「TODO 追蹤／勾稽／新增」都在這種任務清單上操作。
- **專案進度欄位（project column）**：依 `/jsc-generic:spec-project-board`（欄位語意以看板實際名稱為準、不得假設五欄都存在、對不上或介面不支援時不移動只回報建議）；本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整，對應規則見第 3.5 步。
- **議題描述流程圖**：依 `/jsc-generic:spec-output` — 補進議題正文或進度留言的內容有助理解時（需求流程、TODO 先後／相依），加入 Mermaid 流程圖，忠實反映議題需求與 TODO 現況、不得杜撰。
- **專案進度欄位（project column）**：依 `/jsc-shared:spec-project-board`（欄位語意以看板實際名稱為準、不得假設五欄都存在、對不上或介面不支援時不移動只回報建議）；本 skill 會依議題描述、需求與 TODO 勾稽結果建議議題應在的欄位，並在使用者確認後調整，對應規則見第 3.5 步。
- **議題描述流程圖**：依 `/jsc-shared:spec-output` — 補進議題正文或進度留言的內容有助理解時（需求流程、TODO 先後／相依），加入 Mermaid 流程圖，忠實反映議題需求與 TODO 現況、不得杜撰。
## 第 0 步：解析輸入、判斷專案或議題、準備工具
@@ -90,7 +90,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
3. **3.2 依需求更新可用標籤**：依議題需求性質，從該 repo **既有標籤**中挑選應掛上（或應移除）的標籤，回傳內容中列出「建議的標籤異動」（新增哪些、移除哪些、維持哪些）。**不自行新建標籤**，除非使用者要求；找不到合適標籤就維持原樣並標註。
4. **3.3 逐條勾稽未完成 TODO 是否已完成**：對所有**未完成**的 TODO（含 3.1 新增的），逐條依工作目錄下的檔案內容判斷是否已完成。已完成者標記為 `- [x]` 並在回傳內容記下判斷依據（以 `path:line` 指出對應實作位置）；無法從檔案可靠判斷者維持未完成並標註「需人工確認」。
5. **3.4 整理 TODO 異動留言**：若本議題有任何 TODO 異動（**新增**的 TODO，或**狀態變更**——由未完成改為完成），整理成一則留言內容，包含：本次新增了哪些 TODO、哪些 TODO 判定為完成（附對應實作位置）、哪些仍未完成（含原因／需人工確認）。若沒有任何 TODO 異動，回傳標明「無異動、不需留言」。
6. **3.5 建議專案進度欄位**：若本議題屬於某個專案看板且能取得看板的欄位清單與議題目前所在欄位，依議題描述、需求與 3.1／3.3 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則依 `/jsc-generic:spec-project-board` 的建議欄位表（分析中／待處理／進行中／待測試／已完成，欄位名稱以看板實際名稱為準、語意相近即可對應）。
6. **3.5 建議專案進度欄位**：若本議題屬於某個專案看板且能取得看板的欄位清單與議題目前所在欄位，依議題描述、需求與 3.1／3.3 的結果，從**看板實際存在的欄位**中建議議題應在的欄位；語意對應規則依 `/jsc-shared:spec-project-board` 的建議欄位表（分析中／待處理／進行中／待測試／已完成，欄位名稱以看板實際名稱為準、語意相近即可對應）。
回傳內容需含：目前欄位、建議欄位、判斷依據。建議欄位與目前欄位相同時標明「欄位無異動」；看板欄位語意對不上（或取不到欄位資訊）時標明「無法對應、維持原欄位」並列出實際欄位名稱，不得硬套。議題不屬於任何專案看板時跳過本項。
每個 subagent **回傳**一份結構化同步計畫（**不落地成檔案**），至少包含：議題參照與標題、追加後的完整正文（標明新增與勾稽的變更）、建議的標籤異動、TODO 異動留言內容（或「無異動」）、專案進度欄位建議（目前欄位／建議欄位／判斷依據，或「不屬於專案看板」「無法對應」）、以及所有「需人工確認」項目。
@@ -127,7 +127,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
- 更新前先重新讀一次議題正文，若與 subagent 讀到的版本已不同（他人期間有改動），停下該議題並回報，避免覆蓋他人變更。
- **標籤異動**：套用建議的新增／移除。
- tea：`tea labels`／issue 編輯對應指令；API：`POST`/`DELETE {base}/repos/{owner}/{repo}/issues/{index}/labels`（用既有 label id）。
- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，依 `/jsc-generic:spec-project-board` 把議題移到建議欄位（先 GET 探測端點、404／501 視為不支援且不得對未確認端點寫入；介面可用時一次一個議題並確認回應成功；不可用時不視為錯誤，改在第 7 步回報列「議題 → 建議欄位」清單請使用者手動拖曳；只在欄位確實存在且語意對應明確時移動，有疑慮就不動並回報）。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。
- **調整專案進度欄位**：對「建議欄位與目前欄位不同」的議題，依 `/jsc-shared:spec-project-board` 把議題移到建議欄位（先 GET 探測端點、404／501 視為不支援且不得對未確認端點寫入；介面可用時一次一個議題並確認回應成功；不可用時不視為錯誤，改在第 7 步回報列「議題 → 建議欄位」清單請使用者手動拖曳；只在欄位確實存在且語意對應明確時移動，有疑慮就不動並回報）。「欄位無異動」「無法對應」「不屬於專案看板」的議題跳過。
- **留言**：對有 TODO 異動的議題張貼留言。
- tea：`tea comment --repo <owner>/<repo> --login <name> <index> "<留言內容>"`；API：`POST {base}/repos/{owner}/{repo}/issues/{index}/comments`，body `{"body":"<留言內容>"}`。
- 無異動的議題不留言。
@@ -146,6 +146,6 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
- 「TODO 是否完成」「該補哪些 TODO」「該掛哪些標籤」一律以**工作目錄下的檔案**為依據；無法可靠判斷就標「需人工確認」，不得臆測或編造需求未涵蓋的內容。
- subagent 與各步驟只讀檔案與議題、只回傳結構化內容，**不得在磁碟寫任何檔案、不得修改任何工作目錄原始碼**。
- 標籤只從既有標籤挑選，不自行新建（除非使用者要求）。
- 進度欄位調整依 `/jsc-generic:spec-project-board`，且必須經第 5 步使用者確認後執行。
- 進度欄位調整依 `/jsc-shared:spec-project-board`，且必須經第 5 步使用者確認後執行。
- 專案完成模式只在輸入為專案且使用者**明確**指定關閉／完成時進入；語意不明就用 AskUserQuestion 確認，不得自行認定。批次關閉議題前必須經使用者確認；含未完成 TODO 的議題要在確認時明確標出。不得透過此模式關閉不屬於該專案的議題。
- JSON 解析（不依賴 `jq`）依 `/jsc-generic:spec-gitea`；個資保護（PII）與語言規範依 `/jsc-generic:spec-output`。
- JSON 解析（不依賴 `jq`）依 `/jsc-shared:spec-gitea`；個資保護（PII）與語言規範依 `/jsc-shared:spec-output`。