Merge pull request '新增 doc-issues-analyze skill：讀 issue、拆解實作階段並交付留言' (#25) from develop into master
Reviewed-on: #25 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
This commit was merged in pull request #25.
This commit is contained in:
@@ -1,7 +1,7 @@
|
|||||||
{
|
{
|
||||||
"name": "jsc",
|
"name": "jsc",
|
||||||
"version": "0.0.9",
|
"version": "0.0.10",
|
||||||
"description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode）：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。",
|
"description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode）：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。",
|
||||||
"skills": "./skills",
|
"skills": "./skills",
|
||||||
"author": {
|
"author": {
|
||||||
"name": "JSC"
|
"name": "JSC"
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "jsc",
|
"name": "jsc",
|
||||||
"version": "0.0.9",
|
"version": "0.0.10",
|
||||||
"description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例。所有 skills 以 SKILL.md 為共通標準。",
|
"description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言。所有 skills 以 SKILL.md 為共通標準。",
|
||||||
"skills": "./skills"
|
"skills": "./skills"
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -1,7 +1,7 @@
|
|||||||
# jsc — 跨 AI 助理文件化 Skill 集合
|
# jsc — 跨 AI 助理文件化 Skill 集合
|
||||||
|
|
||||||
一個可同時被 **Claude Code、Codex、Antigravity、OpenCode** 安裝的文件化 skill 集合。
|
一個可同時被 **Claude Code、Codex、Antigravity、OpenCode** 安裝的文件化 skill 集合。
|
||||||
目前內含兩個實作型 skills：`doc-docker` 用於整理 `docker-compose.yaml` 的行內註解與標題日期；`doc-funcs` 用於掃描專案 functions、建立 `.docs/` 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例。
|
目前內含三個實作型 skills：`doc-docker` 用於整理 `docker-compose.yaml` 的行內註解與標題日期；`doc-funcs` 用於掃描專案 functions、建立 `.docs/` 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；`doc-issues-analyze` 用於讀取 Gitea issue、彙整需求並拆成多階段 issue、產生實作草稿與交付留言。
|
||||||
核心是以 [Agent Skills（`SKILL.md`）](https://agentskills.io) 標準撰寫的共用 skills（唯一真實來源放在 `skills/`），
|
核心是以 [Agent Skills（`SKILL.md`）](https://agentskills.io) 標準撰寫的共用 skills（唯一真實來源放在 `skills/`），
|
||||||
搭配各助理各自的 plugin manifest，讓**同一個 repo** 可用各家**原生 plugin CLI** 安裝。
|
搭配各助理各自的 plugin manifest，讓**同一個 repo** 可用各家**原生 plugin CLI** 安裝。
|
||||||
在 Claude Code 與 Antigravity 中，skill 以 **`/jsc:` 前綴**呼叫（例如 `/jsc:doc-docker`）。
|
在 Claude Code 與 Antigravity 中，skill 以 **`/jsc:` 前綴**呼叫（例如 `/jsc:doc-docker`）。
|
||||||
@@ -39,7 +39,8 @@ doc/
|
|||||||
│ ├── doc-docker/ # 對齊 docker-compose 註解（含 scripts/）
|
│ ├── doc-docker/ # 對齊 docker-compose 註解（含 scripts/）
|
||||||
│ │ ├── SKILL.md
|
│ │ ├── SKILL.md
|
||||||
│ │ └── scripts/
|
│ │ └── scripts/
|
||||||
│ └── doc-funcs/SKILL.md # 為 function 補齊 XML 文件
|
│ ├── doc-funcs/SKILL.md # 為 function 補齊 XML 文件
|
||||||
|
│ └── doc-issues-analyze/SKILL.md # 讀 issue → 需求文件 → 拆階段 issue → 實作草稿 → 交付留言
|
||||||
├── AGENTS.md # 跨助理共用指引
|
├── AGENTS.md # 跨助理共用指引
|
||||||
└── README.md
|
└── README.md
|
||||||
```
|
```
|
||||||
@@ -131,7 +132,7 @@ git -C ~/jsc-plugin pull
|
|||||||
cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/
|
cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/
|
||||||
|
|
||||||
# 移除
|
# 移除
|
||||||
rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs
|
rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs ~/.config/opencode/skills/doc-issues-analyze
|
||||||
```
|
```
|
||||||
|
|
||||||
> **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。
|
> **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。
|
||||||
@@ -181,6 +182,14 @@ rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs
|
|||||||
- **Codex**：`$doc-funcs`，或用 `/skills` 選單
|
- **Codex**：`$doc-funcs`，或用 `/skills` 選單
|
||||||
- **OpenCode**：描述需求自動觸發
|
- **OpenCode**：描述需求自動觸發
|
||||||
|
|
||||||
|
### `doc-issues-analyze`
|
||||||
|
|
||||||
|
讀取一或多筆 Gitea issue URL（優先用 `tea`，否則用 Gitea REST API + `curl` + `GITEA_TOKEN`，不依賴 `jq`），把 issue 正文與留言彙整成一份完整需求文件，依功能拆成多個實作階段並各建立一個 issue（沿用來源 issue 的里程碑與專案、依需求性質從既有標籤挑選填入），再配合使用者指定的 repositories 或 issue 所在 repo，對每個階段派 subagent 產生實作草稿，最後產出交付文件並依 issues 分組留言到對應 issue。建立 issue 與留言前會先產生全部草稿並以 AskUserQuestion 讓使用者確認執行方式（全部執行／只建立 issue／只產文件不動 Gitea／逐階段確認）。當使用者要分析 issue、把需求拆成多階段 issue、依 issue 產生實作規劃或交付留言，或提到 doc-issues-analyze、issue 需求分析、issue 拆階段、tea issues、Gitea issue 留言時使用此 skill。
|
||||||
|
|
||||||
|
- **Claude Code / Antigravity**：`/jsc:doc-issues-analyze`
|
||||||
|
- **Codex**：`$doc-issues-analyze`，或用 `/skills` 選單
|
||||||
|
- **OpenCode**：描述需求自動觸發
|
||||||
|
|
||||||
<!-- JSC-SKILLS:END -->
|
<!-- JSC-SKILLS:END -->
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|||||||
+2
-2
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "jsc",
|
"name": "jsc",
|
||||||
"version": "0.0.9",
|
"version": "0.0.10",
|
||||||
"description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。",
|
"description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。",
|
||||||
"skills": "./skills/"
|
"skills": "./skills/"
|
||||||
}
|
}
|
||||||
|
|||||||
@@ -0,0 +1,127 @@
|
|||||||
|
---
|
||||||
|
name: doc-issues-analyze
|
||||||
|
description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gitea API），彙整成一份完整需求文件，依功能拆成多個實作階段並各建立一個 issue（沿用來源 issue 的里程碑／專案，依需求性質填入標籤），再配合使用者指定的 repositories 或 issue 所在 repo 產生實作草稿，最後產出交付文件並依 issues 分組留言到對應 issue。當使用者要分析 issue、把需求拆成多階段 issue、依 issue 產生實作規劃或交付留言，或提到 doc-issues-analyze、issue 需求分析、issue 拆階段、tea issues、Gitea issue 留言時使用此 skill。
|
||||||
|
---
|
||||||
|
|
||||||
|
# 分析 Issue 並拆解為實作階段與交付留言
|
||||||
|
|
||||||
|
你要讀取使用者提供的一或多筆 Gitea issue，彙整成完整需求文件，依功能拆成多個實作階段（每階段建立一個 issue），配合指定的 repositories 產生實作草稿，最後產出交付文件並依 issues 分組留言。**建立 issue 與留言屬於對外且不易復原的動作，必須先讓使用者確認過草稿再執行**。所有需求彙整、階段拆分與實作草稿一律先產生草稿檔，再詢問使用者是否實際建立 issue / 留言。請依下列階段依序完成。
|
||||||
|
|
||||||
|
## 前置：輸入與工具
|
||||||
|
|
||||||
|
- **輸入**：至少一筆 issue URL（可多筆）。可另外指定「repositories 位置」（本機含多個專案的資料夾）；若未指定，實作草稿以各 issue 所在的 repository 為準。
|
||||||
|
- **工具優先序**：
|
||||||
|
1. 若該 issue host 在 `tea login list` 中有對應 login，優先用 `tea`（`tea issues`、`tea comment` 等），並以 `--login <name> --repo <owner>/<repo>` 指定目標。
|
||||||
|
2. 否則改用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`（環境變數 `GITEA_TOKEN` 已設定）。
|
||||||
|
- **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
|
||||||
|
- **工作目錄**：所有草稿與文件放在 `.docs/doc-issues-analyze/`。
|
||||||
|
|
||||||
|
## 第 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/`（若不存在）。
|
||||||
|
4. 若使用者指定了 repositories 位置，先確認該路徑存在並列出其中的專案；若未指定，記錄「以 issue 所在 repo 為準」，並確認本機是否已 clone 對應 repo（沒有就在草稿中標註需人工提供或 clone）。
|
||||||
|
|
||||||
|
## 第 1 步：讀取 issues 內容
|
||||||
|
|
||||||
|
對每一筆 issue，讀取完整內容：`title`、`body`、`state`、`labels`、`milestone`、`assignees`、以及**所有 comments**；若 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}`
|
||||||
|
- 留言：`GET {base}/issues/{index}/comments`
|
||||||
|
- 同時盤點該 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/requirements.md`，內容至少包含：
|
||||||
|
|
||||||
|
- 來源 issue 清單：每筆的 URL、標題、狀態、現有 labels／milestone／project。
|
||||||
|
- 完整需求描述：整合各 issue 的正文與留言，去除重複、補齊上下文，形成單一連貫的需求敘述。
|
||||||
|
- 驗收條件／預期結果：能從 issue 推得的，逐條列出；不能確定的標註「需人工確認」。
|
||||||
|
- 分類資源盤點：此 repo 現有可用的 labels、milestones、projects（供第 3 步沿用）。
|
||||||
|
|
||||||
|
需求彙整只做整理與歸納，不得編造 issue 未提及的需求；無法確定處保守描述並標註。
|
||||||
|
|
||||||
|
## 第 3 步：依功能拆分實作階段（規劃要建立的 issues）
|
||||||
|
|
||||||
|
依功能把需求拆成多個實作階段（phase），**每個階段對應一個未來要建立的 issue**，產生草稿 `.docs/doc-issues-analyze/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。對**每一個實作階段各派一個 subagent**，研究相關專案程式碼後產生實作草稿 `.docs/doc-issues-analyze/drafts/phase-{N}.md`。subagent 只讀程式碼與必要上下文、**不修改任何原始碼、不建立 issue、不留言**，只在 `.docs/` 底下寫草稿。每份草稿包含：
|
||||||
|
|
||||||
|
- 對應階段與對應（將建立的）issue 標題。
|
||||||
|
- 涉及的專案／檔案清單與定位（以 `path:line` 形式標出關鍵位置）。
|
||||||
|
- 建議的實作方式：要新增或修改什麼、涉及的介面／資料流、相依與風險。
|
||||||
|
- 測試與驗證方式建議。
|
||||||
|
- 無法從程式碼可靠推得的部分，保守標註「需人工確認」，不要臆測。
|
||||||
|
|
||||||
|
## 第 5 步：草稿品質檢查
|
||||||
|
|
||||||
|
在對外建立 issue／留言之前，主 agent 必須檢查所有草稿：
|
||||||
|
|
||||||
|
- 內容以繁體中文為主、英文為輔，無亂碼、編碼錯誤或破損文字。
|
||||||
|
- `requirements.md` 涵蓋全部來源 issue；`phases.md` 每個階段都有標題、描述、里程碑／專案／標籤的沿用決定；每個階段都有對應的 `drafts/phase-{N}.md`。
|
||||||
|
- 里程碑／專案／標籤的沿用決定，與第 1 步盤點到的既有資源一致（id／名稱對得上）。
|
||||||
|
- 若發現問題，先修正草稿並重新檢查，通過後才進入下一步。
|
||||||
|
|
||||||
|
## 第 6 步：詢問使用者要如何執行（AskUserQuestion）
|
||||||
|
|
||||||
|
草稿完成並通過檢查後，主 agent 必須用 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/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/`）預設保留供使用者檢視；若使用者要求清理，才刪除本次產生的檔案，且不得刪除 `.docs/` 內其他既有檔案。
|
||||||
|
|
||||||
|
## 重要限制
|
||||||
|
|
||||||
|
- 建立 issue 與留言是對外且不易復原的動作，**必須先經第 6 步使用者確認**；未確認前只產生本機草稿。
|
||||||
|
- 新 issue 一律沿用來源 issue 的里程碑與專案；標籤只從既有標籤中依需求性質挑選，不自行新建（除非使用者要求）。
|
||||||
|
- subagent 與各步驟只讀程式碼與 issue、只寫 `.docs/` 草稿，**不得修改任何原始碼**；本 skill 的產出是需求文件、階段 issue、實作草稿與交付留言，不含改動程式邏輯。
|
||||||
|
- 不要依賴 `jq`（未安裝）；JSON 解析改用 tea 結構化輸出或由 subagent 解析。
|
||||||
|
- 需求、階段與實作草稿若無法可靠推論，一律保守描述並標註「需人工確認」，不得編造 issue 未提及的內容。
|
||||||
|
- 留言與交付文件不得洩漏個資（PII）；若 issue 內容含個資，於文件與留言中僅保留必要資訊或去識別化。
|
||||||
|
- 文件、留言與草稿以繁體中文為主、英文為輔；API 名稱、型別名稱與程式碼片段可保留英文。
|
||||||
Reference in New Issue
Block a user