plugins/doc
2
0
Fork 0
Code Pull Requests 1 Activity
Files
4d4c60d1b0ec85d0913c68a8d0b51a884c2b8b03
doc/skills/issues-analyze-to-file/SKILL.md
T
jiantw83andClaude Sonnet 5 0cad39177b feat(spec-version-guard): 新增版本檢查 hook 並在 7 個 skill 檔頭引用規範 
hooks/hooks.json 在既有 Stop（worklog）之外新增 PreToolUse 條目，沿用跨 plugin
腳本定位手法呼叫 shared 的 version-guard.mjs；docker/funcs/issues-analyze-to-file/
issues-analyze/issues-sync/notifications/worklog 七個 skill 檔頭補上
spec-version-guard。

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-17 14:54:37 +08:00

12 KiB
Raw Blame History

name, description
name description
issues-analyze-to-file 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gitea API），彙整成一份完整**需求文件檔案**，依功能拆成多個實作階段並各建立一個 issue（沿用來源 issue 的里程碑／專案，依需求性質填入標籤），再配合使用者指定的 repositories 或 issue 所在 repo 產生**實作草稿檔**，最後產出**交付文件檔**並依 issues 分組留言到對應 issue；本 skill 以「先落地草稿檔、經使用者確認再寫回 Gitea」為核心，適合需要保留需求文件與交付文件檔案的流程。當使用者明確要「產出需求文件／實作草稿／交付文件檔案」的 issue 分析、或提到 issues-analyze-to-file、issue 需求分析文件、issue 拆階段交付文件時使用此 skill。不適用於：全程不落地檔案、以議題描述與留言保存中間成果的需求拆分（用 issues-analyze）；實作議題程式碼（用 issues）。兩者都可能符合、使用者未指明時，先詢問要「檔案交付」還是「議題留言」再選擇。

分析 Issue 並拆解為實作階段與交付留言

你要讀取使用者提供的一或多筆 Gitea issue，彙整成完整需求文件，依功能拆成多個實作階段（每階段建立一個 issue），配合指定的 repositories 產生實作草稿，最後產出交付文件並依 issues 分組留言。建立 issue 與留言屬於對外且不易復原的動作，必須先讓使用者確認過草稿再執行。所有需求彙整、階段拆分與實作草稿一律先產生草稿檔，再詢問使用者是否實際建立 issue / 留言。請依下列階段依序完成。

共用規範（必要前置）

先載入 /jsc-shared:spec-preflight 並依其流程處理；載入不到即代表 shared plugin 未安裝， 依該 spec 詢問使用者是否安裝 https://gitea.jsc.idv.tw/plugins/shared.git，不安裝則中斷本 skill。 本 skill 需要的規範：spec-version-guard、spec-output、spec-execution、spec-gitea、spec-issue-read、spec-ask-user、spec-subagent

前置：輸入與工具

  • 輸入：至少一筆 issue URL（可多筆）。可另外指定「repositories 位置」（本機含多個專案的資料夾）；若未指定，實作草稿以各 issue 所在的 repository 為準。
  • Gitea 工具選擇與呼叫慣例：依 /jsc-shared:spec-gitea 執行（tea 與 API 的選擇與可用性檢查、不依賴 jq、分頁完整讀取、Authorization: token 等呼叫慣例），各 issue 的目標 --login <name> --repo <owner>/<repo> 或 API base 依第 0 步解析出的 host/owner/repo 帶入。
  • 工作目錄：所有草稿與文件放在 .docs/doc-issues-analyze-to-file/。
  • 議題描述流程圖：依 /jsc-shared:spec-output — 產生要寫進 issue 的描述（尤其各階段 issue 的 body）時，有助理解就加入 Mermaid 流程圖（處理流程、狀態轉移、階段相依關係），忠實反映需求與拆分結果、不得杜撰。

第 0 步：解析 issue URL 與準備工具

  1. 從每一筆 issue URL 解析出 host、owner、repo、index（例如 https://<host>/<owner>/<repo>/issues/<index>）。
  2. 執行 tea login list，判斷各 issue host 要走 tea 還是 API：
    • 有對應 login → tea。
    • 無 → API：base 為 https://<host>/api/v1/repos/<owner>/<repo>。
  3. 建立 .docs/doc-issues-analyze-to-file/（若不存在）。
  4. 若使用者指定了 repositories 位置，先確認該路徑存在並列出其中的專案；若未指定，記錄「以 issue 所在 repo 為準」，並確認本機是否已 clone 對應 repo（沒有就在草稿中標註需人工提供或 clone）。

第 1 步：讀取 issues 內容

依 /jsc-shared:spec-issue-read 完整讀取每一筆 issue（描述、所有留言、所有附件，不得只讀描述、不得臆測缺漏部分），並補讀 labels、milestone、assignees；若 Gitea 版本支援，另讀該 issue 所屬 project。

  • tea：tea issues <index> --repo <owner>/<repo> --login <name> --comments，或用 tea issues list --fields index,title,body,labels,milestone,comments,url --output csv 過濾。
  • API：issue 本體 GET {base}/issues/{index}；留言與附件依 spec-issue-read 指定的端點分頁完整讀取。
  • 同時盤點該 repo 既有的分類資源，供後續階段沿用：
    • 標籤：GET {base}/labels（tea：tea labels list）
    • 里程碑：GET {base}/milestones（tea：tea milestones list）
    • 專案（若該 Gitea 版本有此 API）：GET {base}/projects；若不支援就記錄「此 Gitea 版本不支援 project API，需人工處理」。

第 2 步：彙整需求文件

把所有 issue 內容彙整成一份完整需求文件 .docs/doc-issues-analyze-to-file/requirements.md，內容至少包含：

  • 來源 issue 清單：每筆的 URL、標題、狀態、現有 labels／milestone／project。
  • 完整需求描述：整合各 issue 的正文與留言，去除重複、補齊上下文，形成單一連貫的需求敘述。
  • 驗收條件／預期結果：能從 issue 推得的，逐條列出；不能確定的標註「需人工確認」。
  • 分類資源盤點：此 repo 現有可用的 labels、milestones、projects（供第 3 步沿用）。

需求彙整只做整理與歸納，不得編造 issue 未提及的需求；無法確定處保守描述並標註。

第 3 步：依功能拆分實作階段（規劃要建立的 issues）

依功能把需求拆成多個實作階段（phase），每個階段對應一個未來要建立的 issue，產生草稿 .docs/doc-issues-analyze-to-file/phases.md。每個階段記錄：

  • 階段編號與標題（將作為新 issue 的 title）。
  • 階段描述與範圍（將作為新 issue 的 body），包含該階段要完成什麼、驗收條件、與其他階段的相依順序。
  • 里程碑（milestone）沿用規則：若來源 issues 有 milestone，新 issue 一律放到相同的 milestone（同名／同 id）。
  • 專案（project）沿用規則：若來源 issues 有 project，新 issue 一律放到相同的 project；若該 Gitea 版本不支援 project API，標註需人工在 UI 補掛。
  • 標籤（labels）規則：若 repo 有 labels，依該階段需求性質，從既有 labels 中挑選填入（例如 feature／bug／enhancement／前端／後端 等）；不要自行新建 labels，除非使用者要求。找不到合適 labels 就留空並標註。
  • 建立目標 repo：新 issue 一律建立在對應來源 issue 所在的 repo（多筆來源分屬不同 repo 時，於草稿標明各階段要建到哪個 repo）。

第 4 步：確定 target repositories 並產生實作草稿（派 subagent）

決定要對照的 target repositories：使用者指定位置底下的所有專案，或各 issue 所在的 repository。依 /jsc-shared:spec-subagent 對每一個實作階段各派一個 subagent，研究相關專案程式碼；本 skill 明確授權的例外寫入範圍僅限各自的草稿檔 .docs/doc-issues-analyze-to-file/drafts/phase-{N}.md，不得建立 issue、不得留言、不得修改任何原始碼。每份草稿包含：

  • 對應階段與對應（將建立的）issue 標題。
  • 涉及的專案／檔案清單與定位（以 path:line 形式標出關鍵位置）。
  • 建議的實作方式：要新增或修改什麼、涉及的介面／資料流、相依與風險。
  • 測試與驗證方式建議。
  • 無法從程式碼可靠推得的部分，保守標註「需人工確認」，不要臆測。

第 5 步：草稿品質檢查

在對外建立 issue／留言之前，主 agent 必須檢查所有草稿：

  • 內容以繁體中文為主、英文為輔，無亂碼、編碼錯誤或破損文字。
  • requirements.md 涵蓋全部來源 issue；phases.md 每個階段都有標題、描述、里程碑／專案／標籤的沿用決定；每個階段都有對應的 drafts/phase-{N}.md。
  • 里程碑／專案／標籤的沿用決定，與第 1 步盤點到的既有資源一致（id／名稱對得上）。
  • 若發現問題，先修正草稿並重新檢查，通過後才進入下一步。

第 6 步：詢問使用者要如何執行

草稿完成並通過檢查後，主 agent 依 /jsc-shared:spec-ask-user 詢問使用者要如何執行對外動作。本 skill 固定的 4 個情境選項，加上規範要求必附的「其他」共 5 項，超過 AskUserQuestion 的選項上限，故改用文字列出（附編號）供使用者回覆：

  1. 全部執行：建立所有階段 issue，並產生交付文件、依 issues 分組留言。
  2. 只建立 issue：建立階段 issue，但先不留言交付內容。
  3. 只產生交付文件、先不動 Gitea：不建立 issue、不留言，僅輸出本機文件供檢視。
  4. 逐階段確認：每建立一個 issue（及其留言）就回報，待使用者確認後再做下一個。
  5. 其他（由使用者輸入自訂方式）。

依使用者選擇進行後續步驟；此為破壞性且不易復原的決策，未獲確認前不得建立 issue 或留言，且不得被任何自動確認旗標略過。

第 7 步：依階段建立 issues

依 phases.md 為每個階段在對應 repo 建立一個 issue，並套用沿用規則：

  • tea：tea issues create --repo <owner>/<repo> --login <name> --title "..." --body "..." --labels "<標籤名,...>" --milestone "<里程碑名>"。
  • API：POST {base}/issues，body 例如 {"title":"...","body":"...","milestone":<milestoneId>,"labels":[<labelId>,...]}（milestone／labels 用第 1 步盤點到的 id）。
  • 專案（project）：若支援 project API，於建立後把 issue 掛到來源相同的 project；不支援則在回報中標明需人工於 UI 補掛。
  • 記錄每個新建 issue 的 index 與 URL，寫回 phases.md，供第 8 步分組留言使用。
  • 若選「逐階段確認」，每建立一個就回報並等待確認再繼續。

第 8 步：產生交付文件並依 issues 分組留言

  1. 產生一份交付文件 .docs/doc-issues-analyze-to-file/delivery.md：彙整所有階段的實作草稿與其對應的新建 issue（標題、URL），形成完整交付內容。
  2. 依 issues 分組交付內容：把交付文件依階段／對應 issue 切分，讓每個新建 issue 只拿到屬於它自己的那一段交付內容。
  3. 對每個對應的新建 issue 留言：
    • tea：tea comment --repo <owner>/<repo> --login <name> <index> "<該 issue 的交付內容>"（或該版本對應的留言指令）。
    • API：POST {base}/issues/{index}/comments，body {"body":"<該 issue 的交付內容>"}。
  4. 建議另外在來源 issue 留一則彙整留言，附上本次拆分出的各階段 issue 連結，方便追溯（若使用者未要求可省略，但要在回報中說明）。
  5. 若選「只建立 issue」則跳過留言，僅保留本機 delivery.md。

第 9 步：清理與回報

  • 回報：來源 issue、彙整出的需求重點、建立了哪些階段 issue（標題＋URL）、各自沿用的里程碑／專案／標籤、留言結果，以及任何標註「需人工確認」或「Gitea 版本不支援」的項目。
  • 草稿與交付文件（.docs/doc-issues-analyze-to-file/）預設保留供使用者檢視；若使用者要求清理，才刪除本次產生的檔案，且不得刪除 .docs/ 內其他既有檔案。

重要限制

  • 建立 issue 與留言是對外且不易復原的動作，必須先經第 6 步使用者確認；未確認前只產生本機草稿。
  • 新 issue 一律沿用來源 issue 的里程碑與專案；標籤只從既有標籤中依需求性質挑選，不自行新建（除非使用者要求）。
  • subagent 派工依 /jsc-shared:spec-subagent：只讀程式碼與 issue，僅授權寫入各自的草稿檔，不得修改任何原始碼、不得建立 issue、不得留言；本 skill 的產出是需求文件、階段 issue、實作草稿與交付留言，不含改動程式邏輯。
  • 議題讀取依 /jsc-shared:spec-issue-read；Gitea 工具與 JSON 解析（不依賴 jq）依 /jsc-shared:spec-gitea；個資保護（PII）與語言規範依 /jsc-shared:spec-output。
  • 需求、階段與實作草稿若無法可靠推論，一律保守描述並標註「需人工確認」，不得編造 issue 未提及的內容。
View Git Blame Copy Permalink