plugins/code
1
0
Fork 0
Code Pull Requests Activity
Files
6d9bac458531d30a542e46fe25d42c245f47696a
code/skills/code-issues/SKILL.md
T

18 KiB
Raw Blame History

name, description, argument-hint
name description argument-hint
code-issues 處理一或多個 Gitea 議題的實作流程：先選擇使用 `tea` 或 Gitea REST API + `GITEA_TOKEN`（已選定則跳過），再確認議題所在專案（已知則跳過）與要處理的議題編號（一或多個）；接著讀取議題描述與留言、彙整需求，整理 TODO 列表並依影響範圍由小到大排序，既有 TODO 不足以達成議題需求時補上新 TODO 並附加到議題描述；最後逐項實作 TODO，每完成一項就到議題勾選該 TODO 的 checkbox 並把進度留言到議題；議題若有母議題，實作完成後母議題 checklist 中引用本議題的 TODO 項目也要一併勾選並留言告知。議題若屬於專案看板且有「分析中／待處理／進行中／待測試／已完成」欄位可調整，依處理進度同步把議題移到對應欄位（彙整需求時「分析中」、TODO 確定「待處理」、開始實作「進行中」、實作完成且驗證通過「待測試」，「已完成」僅在使用者確認時）。全程不建立任何草稿檔，中間成果一律用議題描述或留言保存，並盡量以表格與 Mermaid 圖呈現。當使用者說處理議題、實作議題、依議題 TODO 開工、把議題需求整理成 TODO 並逐項完成、議題進度留言、調整議題看板欄位進度，或提到 code-issues、issue 實作、Gitea 議題處理時觸發。不適用於：把需求拆分成多個新議題（用 doc-issues-analyze）、只同步議題狀態不實作（用 doc-issues-sync）、或與 Gitea 無關的本機 TODO 管理。 [--tool <tea|api>] [--repo <owner/repo>] [--issues <編號,以逗號分隔>] [--host <gitea 主機>] [--yes]

code-issues — 彙整議題 TODO 並逐項實作、留言進度

五階段 skill：先做工具選擇（tea 或 Gitea REST API + GITEA_TOKEN），再確認議題所在專案與要處理的議題編號，接著讀取議題並彙整 TODO 列表（依影響範圍小→大排序，缺漏的 TODO 附加到議題描述），最後逐項實作 TODO，每完成一項就把進度留言到議題。

階段 動作 可跳過條件
A. 工具選擇 檢查 tea / GITEA_TOKEN → 詢問使用者要用 tea 或 api 使用者已明確選定（--tool 或對話中已選）
B. 確認專案 詢問議題所在專案（owner/repo），可用目前 repo 的 origin 當預設選項 已知專案（--repo、對話已提供、或使用者確認採用 origin）
C. 選擇議題 詢問要處理的議題編號，一個或多個 已提供（--issues 或對話中已列出）
D. 彙整 TODO 讀議題描述＋留言 → 彙整需求 → TODO 依影響範圍小→大排序 → 不足以達成需求的缺漏 TODO 附加到議題描述 —
E. 逐項實作 依排序實作每項 TODO → 每完成一項：勾選議題描述 checkbox ＋ 留言進度到議題 → 全部完成後同步母議題 TODO 狀態（若有母議題） —

議題若屬於專案看板且看板有「分析中／待處理／進行中／待測試／已完成」欄位可調整，階段 D／E 需依處理進度同步調整議題所在欄位（見「議題進度欄位調整」）。

絕對準則（不可違反）

  • 不建立任何草稿檔：不寫 .docs/、不寫暫存檔、不用本機檔案傳遞中間結果。需求彙整、TODO 排序、實作進度、驗證結果等所有中間成果，一律留在對話內容，並透過 tea 或 Gitea API 保存到議題描述或議題留言。唯一例外是階段 E 在議題範圍內對目標 repo 原始碼的正常程式修改。
  • 盡量使用表格或圖形：面向使用者的輸出與寫入議題的內容（需求彙整、TODO 列表、進度回報），優先以 Markdown 表格與 Mermaid 圖（```mermaid flowchart／stateDiagram，Gitea 可直接渲染）呈現，讓使用者一眼看懂意圖；圖表必須忠實反映議題內容，不得杜撰。

輸出規範（務必遵守）

  • 語言：所有面向使用者的輸出與寫入議題的描述／留言，一律使用繁體中文（台灣用語）；僅程式碼識別字、檔名、指令、API 路徑等技術標識保留原文，不可使用簡體字。
  • 編碼無亂碼：凡輸出或寫入含繁體中文、全形標點、emoji，一律 UTF-8（不含 BOM），不得出現問號方框或錯碼。用 API 送出議題描述／留言時，以 UTF-8 JSON 檔帶入（如 --data @body.json），換行必須是實際換行，不可讓議題顯示字面 \n。
  • Token 機密保護（極重要）：gitea token 一律從環境變數讀取（$GITEA_TOKEN），絕不寫死、不 echo、不寫進議題或 log；顯示給使用者的指令／錯誤訊息一律遮蔽 token（以 *** 取代）。檢查時只輸出「已設定／未設定」。
  • 不依賴 jq（環境未必安裝）：解析 JSON 用 tea 的結構化輸出（--output csv / --fields），或把原始 JSON 直接交給助理解析，不要 pipe 到 jq。
  • 自動執行原則：除非遇到不可忽略的必要決策（工具皆不可用、專案不明、議題編號缺失、TODO 與需求衝突需人工裁示、實作失敗需使用者決策），否則各階段輸出簡短計畫／進度後直接執行到完成；帶 --yes 時更不應為一般寫入／留言反覆詢問。階段 A／B／C 的詢問在「可跳過條件」成立時必須跳過，不要重複確認已知資訊。

參數

格式：[--tool <tea|api>] [--repo <owner/repo>] [--issues <編號,以逗號分隔>] [--host <gitea 主機>] [--yes]

  • --tool <tea|api>：指定工具，帶此參數時跳過階段 A 的詢問（仍需驗證該工具可用）。
  • --repo <owner/repo>：議題所在專案，帶此參數時跳過階段 B 的詢問。
  • --issues <編號,以逗號分隔>：要處理的議題編號，可一個或多個（例 --issues 12 或 --issues 12,15,18），帶此參數時跳過階段 C 的詢問。
  • --host <gitea 主機>：gitea 主機（如 gitea.jsc.idv.tw）；省略時依 --repo 的 URL、目前 repo 的 origin 或 tea login 對應 host 決定，無法決定時詢問。
  • --yes：全自動；即使未帶此參數，也依「自動執行原則」盡量不中斷。

階段 A：工具選擇（已選定則跳過）

若使用者已透過 --tool 或對話明確選定工具，跳過詢問，只做該工具的可用性驗證。

  1. 檢查 tea 是否存在：command -v tea；存在則執行 tea login list 記錄可用 login 與 host（失敗記錄原因，不中止）。

  2. 檢查 GITEA_TOKEN 是否已設定，只輸出「已設定／未設定」，不得輸出 token 內容：

    [ -n "${GITEA_TOKEN}" ] && echo "GITEA_TOKEN 已設定" || echo "GITEA_TOKEN 未設定"

  3. 以表格呈現檢查結果後詢問使用者要用哪一種：

    選項 可選條件 後續使用方式
    tea tea 可執行且目標 host 有對應 login 命令一律帶 --login <name> --repo <owner>/<repo>
    api GITEA_TOKEN 已設定 Gitea REST API + curl，標頭 Authorization: token $GITEA_TOKEN

  4. 兩種方式都不可用 → 回報缺少 tea login 或 GITEA_TOKEN 並停止；不要請使用者把 token 貼進對話。

階段 B：確認議題所在專案（已知則跳過）

若已透過 --repo、對話內容或先前階段確知專案，跳過詢問。

  1. 若目前工作目錄是 git repo，解析 git remote get-url origin 取得 host／owner／repo 作為預設選項提供給使用者。
  2. 詢問使用者議題所在專案（owner/repo 或 repo URL）；使用者只給名稱時，確認 host／owner 補齊完整座標。
  3. 驗證專案可讀：
    • tea：tea repos <owner>/<repo> 或 tea issues list --repo <owner>/<repo> --limit 1
    • api：GET https://<host>/api/v1/repos/<owner>/<repo>
  4. 確認本機是否已 clone 該 repo（實作階段需要）；找不到本機 repo 時詢問路徑或是否需要 clone，不臆測位置。

階段 C：選擇要處理的議題編號（一個或多個）

若已透過 --issues 或對話提供編號，跳過詢問。

  1. 先列出該專案開啟中的議題供使用者參考（編號、標題、標籤、里程碑），以表格呈現：
    • tea：tea issues list --repo <owner>/<repo> --state open --output csv --fields index,title,labels,milestone
    • api：GET {base}/issues?state=open&type=issues（有分頁必須完整分頁讀取）
  2. 詢問使用者要處理哪些議題編號，接受一個或多個。
  3. 逐一驗證每個編號存在且為 issue（非 pull request）；不存在或已關閉的編號回報並請使用者確認是否仍要處理。

階段 D：彙整需求與 TODO 列表（依影響範圍小→大排序）

對每一個選定議題執行：

D1. 讀取議題完整內容

  • 讀取 title、body、state、labels、milestone、assignees 與所有留言：
    • tea：tea issues <index> --repo <owner>/<repo> --comments
    • api：GET {base}/issues/{index} 與 GET {base}/issues/{index}/comments
  • 留言中若有需求補充、變更或取消，必須納入需求彙整，並以最新留言為準。
  • 一併確認**議題是否屬於專案看板（project）**與看板有哪些欄位（column）：tea 不支援 project 操作，一律改走 API（需 GITEA_TOKEN）；project／column API 隨 Gitea 版本差異大，先探測可用性（如 GET {base}/projects、議題回應中的 project 資訊），不可用時記錄並略過欄位調整，不影響其餘流程。
  • 一併確認議題是否有母議題：檢查議題描述／留言中的「屬於 #n」「parent: #n」等引用、timeline 的 cross-reference（GET {base}/issues/{index}/timeline）、或依賴關係 API；找到候選母議題時讀取其描述，確認其 checklist 是否有引用本議題（如 - [ ] #<本議題編號>）或語意對應本議題的 TODO 項目，記錄母議題編號與對應項目。無法確定時可詢問使用者；找不到就記錄「無母議題」，不臆測。

議題進度欄位調整（議題屬於專案看板時）

議題屬於專案看板、且看板有「分析中／待處理／進行中／待測試／已完成」欄位可調整時，依處理進度把議題移到對應欄位；每次移動在輸出中回報「議題 #n：<原欄位> → <新欄位>」。

時機 目標欄位
階段 D 開始彙整需求時 分析中
階段 D 完成（TODO 列表確定）、尚未開始實作 待處理
階段 E 開始實作第一項 TODO 進行中
階段 E 全部 TODO 實作完成且驗證通過 待測試
議題需求全數達成且使用者確認無需再測試（或明確指示） 已完成
  • 就近對應：欄位名稱不完全相同時做語意對應（如「To Do」→ 待處理、「In Progress」→ 進行中、「Done」→ 已完成）；無法明確對應的欄位不硬移，回報並略過。
  • 保守推進：預設最多推進到「待測試」（本 skill 不負責測試與關閉議題）；只有使用者明確指示或議題描述明定無需測試時才移到「已完成」。
  • 只依實際狀態移動：欄位只反映真實進度，不得先移欄位再補工作；若實作中途停止（待人工處理），欄位停留在「進行中」並於留言註明原因。
  • 議題不屬於任何專案、看板缺少可對應欄位、或 API 不支援移動時 → 回報並略過欄位調整，其餘流程照常。

D2. 彙整需求並盤點既有 TODO

  • 把議題描述與留言整理成需求彙整：目標、驗收條件、限制條件；只做歸納，不編造議題未提及的需求，不確定處標註「需人工確認」。
  • 盤點議題描述中既有的 Markdown checklist（- [ ] / - [x]）作為既有 TODO；已勾選項目視為已完成，不重做。

D3. 產生排序後的 TODO 列表

  • 每項 TODO 必須可執行、可驗收，並評估其影響範圍（預計修改的檔案／模組數與波及面）：

    影響範圍 定義（參考）
    XS 單一檔案內的局部修改（文案、設定值、小修正）
    S 單一檔案或單一函式的邏輯調整
    M 同一模組內跨多檔案的修改
    L 跨模組修改或介面／契約變更
    XL 跨專案、資料結構或流程性的大改動

  • 依影響範圍由小到大排序（XS → XL）；範圍相同時，前置依賴在前。

  • 勾稽需求覆蓋度：逐條比對需求彙整與 TODO 列表；若既有 TODO 不足以達成議題描述與需求，補上缺漏的 TODO（標註「新增」）。

  • 有助理解時，在留言或描述中加入 Mermaid 流程圖呈現 TODO 之間的依賴與執行順序。

D4. 缺漏 TODO 附加到議題描述

  • 若 D3 有新增 TODO，用 tea 或 API 更新議題描述：保留原描述內容，於既有 ## TODO 區塊補上新項目；沒有該區塊時在描述最後加上 ## TODO：
    • tea：tea issues edit <index> --repo <owner>/<repo> --description <更新後全文>（tea 版本不支援時改用 API）
    • api：PATCH {base}/issues/{index}，body 以 UTF-8 JSON 檔帶入 {"body": "..."}
  • 更新前先向使用者以表格摘要「新增了哪些 TODO、為什麼需要」；帶 --yes 時直接執行並回報。
  • 沒有新增 TODO 時不改動議題描述。

階段 E：逐項實作 TODO，每完成一項留言到議題

依 D3 排序（多議題時先完成一個議題的所有 TODO，再進入下一個議題；有跨議題依賴時先處理被依賴者）逐項執行：

  1. 實作：在本機 repo 依 TODO 內容實作，只修改該 TODO 必要範圍；發現需要擴大範圍或牽動其他 TODO 時，先停止並詢問使用者。開始實作該議題第一項 TODO 前，若議題屬於專案看板，依「議題進度欄位調整」把議題移到「進行中」。
  2. 驗證：執行適合專案的建置／測試／驗證；失敗時修正到通過，無法通過則記錄原因並在留言中標註「待人工處理」。
  3. 更新議題 TODO 狀態：實作完成（驗證通過）後，把議題描述中該 TODO 的 checkbox 由 - [ ] 勾成 - [x]（同 D4 的更新方式）；未通過驗證的 TODO 不得勾選。若母議題的 checklist 有對應到本項 TODO 的項目，一併勾選。
  4. 留言進度到議題（每完成一項就留言，不可累積到最後一次補）：
    • tea：tea comment <index> --repo <owner>/<repo> <內容>
    • api：POST {base}/issues/{index}/comments，body 以 UTF-8 JSON 檔帶入
    • 留言內容以表格呈現：本項 TODO、影響範圍、主要變更（檔案／模組）、驗證方式與結果、整體進度（已完成 n/總數 m）；有助理解時附 Mermaid 圖。
  5. 全部 TODO 完成後，對每個議題留下總結留言：TODO 完成統計表、變更檔案清單、驗證總結、待人工處理項目（若有）；若議題屬於專案看板且全部 TODO 實作完成並驗證通過，把議題移到「待測試」（有待人工處理項目時停留在「進行中」）。
  6. 同步母議題 TODO 狀態（D1 有記錄母議題時）：本議題全部 TODO 實作完成且驗證通過後，更新母議題描述，把其 checklist 中引用本議題的項目（如 - [ ] #<本議題編號>）勾成 - [x]（同 D4 的更新方式，保留母議題其餘內容不動），並在母議題留言告知「子議題 #<編號> 已實作完成」與總結留言連結。母議題 checklist 以其他文字描述本議題時做就近語意對應；無法明確對應的項目不硬勾，回報並略過。本議題尚有待人工處理項目時不得勾選母議題對應項目。

本 skill 範圍到「實作＋留言」為止；是否 commit、push、開 PR 或關閉議題不在本 skill 自動範圍，由使用者另行指示（可搭配 code-review-resolve 的分類提交與 PR 流程）。

總結

各階段執行後輸出：

  • 階段 A：選定工具（tea 或 api）、可用性檢查結果（token 只顯示已設定／未設定）、是否因已選定而跳過詢問。
  • 階段 B：議題所在專案（host／owner／repo）、本機 repo 位置、是否因已知而跳過詢問。
  • 階段 C：處理的議題編號清單（含標題），是否因已提供而跳過詢問。
  • 階段 D：每個議題的需求彙整重點、TODO 列表（含影響範圍排序）、新增了幾項 TODO 並是否已附加到議題描述。
  • 階段 E：每項 TODO 的完成狀態與留言連結（或編號）、驗證結果、待人工處理項目；提醒後續可自行決定 commit／PR／關閉議題。
  • 欄位調整：議題是否屬於專案看板、各議題的欄位移動紀錄（#n：<原欄位> → <新欄位>），或略過欄位調整的原因（不屬於專案／無可對應欄位／API 不支援）。
  • 母議題同步：各議題是否有母議題、母議題 checklist 勾選了哪些項目與留言連結，或略過同步的原因（無母議題／無法明確對應／尚有待人工處理項目）。

呼叫方式

格式：[--tool <tea|api>] [--repo <owner/repo>] [--issues <編號,以逗號分隔>] [--host <gitea 主機>] [--yes] — 全部可省略；省略時依階段 A／B／C 詢問（已知資訊一律跳過詢問）。token 一律由環境變數 GITEA_TOKEN 提供。

助理 呼叫
Claude Code / Antigravity /jsc:code-issues，或 /jsc:code-issues --tool api --repo plugins/code --issues 12,15 --yes
Codex $code-issues，或 $code-issues --tool tea --repo plugins/code --issues 12，或用 /skills 選單
OpenCode 描述需求（如「用 GITEA_TOKEN 讀 plugins/code 的 12、15 號議題，整理需求成 TODO 依影響範圍小到大排序、缺的補進議題描述，然後逐項實作、每完成一項留言進度」）自動觸發
View Git Blame Copy Permalink