Merge pull request '新增 doc-issues-sync skill 並重整 doc-issues 系列 skill' (#28) from develop into master
Reviewed-on: #28 Reviewed-by: 系統管理員 <1+admin@noreply.localhost>
This commit was merged in pull request #28.
This commit is contained in:
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.1.1",
|
||||
"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: 前綴呼叫。",
|
||||
"version": "0.1.2",
|
||||
"description": "JSC 文件化 skills（Claude Code / Codex / Antigravity / OpenCode）：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；doc-issues-analyze 會把專案／議題／文件來源拆成小功能議題並依到期日實作；doc-issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度與標籤並產生進度留言。所有 skills 以 SKILL.md 為共通標準，於 Claude Code 以 /jsc: 前綴呼叫。",
|
||||
"skills": "./skills",
|
||||
"author": {
|
||||
"name": "JSC"
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.1.1",
|
||||
"description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言。所有 skills 以 SKILL.md 為共通標準。",
|
||||
"version": "0.1.2",
|
||||
"description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；doc-issues-analyze 會把專案／議題／文件來源拆成小功能議題並依到期日實作；doc-issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度與標籤並產生進度留言。所有 skills 以 SKILL.md 為共通標準。",
|
||||
"skills": "./skills"
|
||||
}
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# jsc — 跨 AI 助理文件化 Skill 集合
|
||||
|
||||
一個可同時被 **Claude Code、Codex、Antigravity、OpenCode** 安裝的文件化 skill 集合。
|
||||
目前內含四個實作型 skills：`doc-docker` 用於整理 `docker-compose.yaml` 的行內註解與標題日期；`doc-funcs` 用於掃描專案 functions、建立 `.docs/` 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；`doc-issues-analyze` 用於讀取 Gitea issue、彙整需求並拆成多階段 issue、產生實作草稿與交付留言；`doc-issues-breakdown` 用於把專案／議題／文件來源拆成小功能議題並依到期日實作。
|
||||
目前內含五個實作型 skills：`doc-docker` 用於整理 `docker-compose.yaml` 的行內註解與標題日期；`doc-funcs` 用於掃描專案 functions、建立 `.docs/` 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；`doc-issues-analyze-to-file` 用於讀取 Gitea issue、彙整需求並拆成多階段 issue、產生實作草稿與交付留言；`doc-issues-analyze` 用於把專案／議題／文件來源拆成小功能議題並依到期日實作；`doc-issues-sync` 用於讀取 Gitea 專案或議題，依工作目錄檔案勾稽並同步議題的 TODO 進度與標籤、產生進度留言。
|
||||
核心是以 [Agent Skills（`SKILL.md`）](https://agentskills.io) 標準撰寫的共用 skills（唯一真實來源放在 `skills/`），
|
||||
搭配各助理各自的 plugin manifest，讓**同一個 repo** 可用各家**原生 plugin CLI** 安裝。
|
||||
在 Claude Code 與 Antigravity 中，skill 以 **`/jsc:` 前綴**呼叫（例如 `/jsc:doc-docker`）。
|
||||
@@ -40,8 +40,9 @@ doc/
|
||||
│ │ ├── SKILL.md
|
||||
│ │ └── scripts/
|
||||
│ ├── doc-funcs/SKILL.md # 為 function 補齊 XML 文件
|
||||
│ ├── doc-issues-analyze/SKILL.md # 讀 issue → 需求文件 → 拆階段 issue → 實作草稿 → 交付留言
|
||||
│ └── doc-issues-breakdown/SKILL.md # 讀來源 → 保存議題 → 小功能議題 → 排程實作 → PR
|
||||
│ ├── doc-issues-analyze-to-file/SKILL.md # 讀 issue → 需求文件 → 拆階段 issue → 實作草稿 → 交付留言
|
||||
│ ├── doc-issues-analyze/SKILL.md # 讀來源 → 保存議題 → 小功能議題 → 排程實作 → PR
|
||||
│ └── doc-issues-sync/SKILL.md # 讀專案／議題 → 依工作目錄勾稽 TODO → 補 TODO／更新標籤 → 進度留言
|
||||
├── AGENTS.md # 跨助理共用指引
|
||||
└── README.md
|
||||
```
|
||||
@@ -133,7 +134,7 @@ git -C ~/jsc-plugin pull
|
||||
cp -r ~/jsc-plugin/skills/* ~/.config/opencode/skills/
|
||||
|
||||
# 移除
|
||||
rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs ~/.config/opencode/skills/doc-issues-analyze ~/.config/opencode/skills/doc-issues-breakdown
|
||||
rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs ~/.config/opencode/skills/doc-issues-analyze-to-file ~/.config/opencode/skills/doc-issues-analyze ~/.config/opencode/skills/doc-issues-sync
|
||||
```
|
||||
|
||||
> **Windows PowerShell**：`cp -r A B` → `Copy-Item A B -Recurse -Force`、`rm -rf X` → `Remove-Item X -Recurse -Force`、`~` → `$HOME`。
|
||||
@@ -183,20 +184,28 @@ rm -rf ~/.config/opencode/skills/doc-docker ~/.config/opencode/skills/doc-funcs
|
||||
- **Codex**：`$doc-funcs`，或用 `/skills` 選單
|
||||
- **OpenCode**：描述需求自動觸發
|
||||
|
||||
### `doc-issues-analyze-to-file`
|
||||
|
||||
讀取一或多筆 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-to-file、issue 需求分析、issue 拆階段、tea issues、Gitea issue 留言時使用此 skill。
|
||||
|
||||
- **Claude Code / Antigravity**：`/jsc:doc-issues-analyze-to-file`
|
||||
- **Codex**：`$doc-issues-analyze-to-file`，或用 `/skills` 選單
|
||||
- **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。
|
||||
讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題），先檢查 `tea` 與 `GITEA_TOKEN` 並詢問使用者要用 `tea` 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日），每個小功能議題都會詢問使用者描述是否有補充內容，所有議題描述最後都會依描述內容產生 TODO list，依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。所有中間成果都不落地成草稿檔，一律使用 `tea` 或 Gitea API 保存到議題描述或留言。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。
|
||||
|
||||
- **Claude Code / Antigravity**：`/jsc:doc-issues-analyze`
|
||||
- **Codex**：`$doc-issues-analyze`，或用 `/skills` 選單
|
||||
- **OpenCode**：描述需求自動觸發
|
||||
|
||||
### `doc-issues-breakdown`
|
||||
### `doc-issues-sync`
|
||||
|
||||
讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題），先檢查 `tea` 與 `GITEA_TOKEN` 並詢問使用者要用 `tea` 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日），每個小功能議題都會詢問使用者描述是否有補充內容，所有議題描述最後都會依描述內容產生 TODO list，依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。所有中間成果都不落地成草稿檔，一律使用 `tea` 或 Gitea API 保存到議題描述或留言。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-breakdown、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。
|
||||
讀取一個 Gitea 專案（project）或單一議題（優先用 `tea`，否則用 Gitea REST API + `curl` + `GITEA_TOKEN`，不依賴 `jq`）；輸入是專案就讀取與此專案關聯的所有議題，輸入是議題就只同步該議題，找不到目標時以 AskUserQuestion 請使用者補齊。議題若有標籤就依標籤分組、以 AskUserQuestion（多選）讓使用者挑選要同步哪些標籤的議題（只有一個議題或全部無標籤則跳過）。接著一個議題派一個 subagent，**以工作目錄下的所有檔案為依據**：判斷議題內的 TODO（markdown 任務清單）是否足以追蹤議題描述的需求、不足就補 TODO 追加到正文、依需求從既有標籤更新議題標籤、逐條勾稽未完成 TODO（含新增）是否已完成、有異動就整理成一則留言。所有對 Gitea 的寫入（改正文／改標籤／留言）先產生草稿並以 AskUserQuestion 讓使用者確認執行方式再套用。當使用者要同步議題進度、依專案批次更新議題 TODO、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 doc-issues-sync、issue sync、議題同步、TODO 勾稽、Gitea 專案議題時使用此 skill。
|
||||
|
||||
- **Claude Code / Antigravity**：`/jsc:doc-issues-breakdown`
|
||||
- **Codex**：`$doc-issues-breakdown`，或用 `/skills` 選單
|
||||
- **Claude Code / Antigravity**：`/jsc:doc-issues-sync`
|
||||
- **Codex**：`$doc-issues-sync`，或用 `/skills` 選單
|
||||
- **OpenCode**：描述需求自動觸發
|
||||
|
||||
<!-- JSC-SKILLS:END -->
|
||||
|
||||
+2
-2
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc",
|
||||
"version": "0.1.1",
|
||||
"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: 前綴呼叫。",
|
||||
"version": "0.1.2",
|
||||
"description": "JSC 文件化 skills：doc-docker 會整理 docker-compose.yaml 的行內註解與標題日期；doc-funcs 會為專案 functions 建立 .docs 草稿、補齊 XML 文件註解並重建 README 功能列表與使用範例；doc-issues-analyze-to-file 會讀取 Gitea issue、彙整需求、拆成多階段 issue 並產生實作草稿與交付留言；doc-issues-analyze 會把專案／議題／文件來源拆成小功能議題並依到期日實作；doc-issues-sync 會讀取 Gitea 專案或議題、依工作目錄檔案勾稽並同步議題的 TODO 進度與標籤並產生進度留言。所有 skills 以 SKILL.md 為共通標準；於 Antigravity 以 /jsc: 前綴呼叫。",
|
||||
"skills": "./skills/"
|
||||
}
|
||||
|
||||
@@ -0,0 +1,127 @@
|
||||
---
|
||||
name: doc-issues-analyze-to-file
|
||||
description: 讀取一或多筆 Gitea issue URL（優先用 tea，否則用 Gitea API），彙整成一份完整需求文件，依功能拆成多個實作階段並各建立一個 issue（沿用來源 issue 的里程碑／專案，依需求性質填入標籤），再配合使用者指定的 repositories 或 issue 所在 repo 產生實作草稿，最後產出交付文件並依 issues 分組留言到對應 issue。當使用者要分析 issue、把需求拆成多階段 issue、依 issue 產生實作規劃或交付留言，或提到 doc-issues-analyze-to-file、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-to-file/`。
|
||||
|
||||
## 第 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 內容
|
||||
|
||||
對每一筆 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-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。對**每一個實作階段各派一個 subagent**，研究相關專案程式碼後產生實作草稿 `.docs/doc-issues-analyze-to-file/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-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 與各步驟只讀程式碼與 issue、只寫 `.docs/` 草稿，**不得修改任何原始碼**；本 skill 的產出是需求文件、階段 issue、實作草稿與交付留言，不含改動程式邏輯。
|
||||
- 不要依賴 `jq`（未安裝）；JSON 解析改用 tea 結構化輸出或由 subagent 解析。
|
||||
- 需求、階段與實作草稿若無法可靠推論，一律保守描述並標註「需人工確認」，不得編造 issue 未提及的內容。
|
||||
- 留言與交付文件不得洩漏個資（PII）；若 issue 內容含個資，於文件與留言中僅保留必要資訊或去識別化。
|
||||
- 文件、留言與草稿以繁體中文為主、英文為輔；API 名稱、型別名稱與程式碼片段可保留英文。
|
||||
@@ -1,127 +1,120 @@
|
||||
---
|
||||
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。
|
||||
description: 讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日），每個小功能議題都必須詢問使用者描述是否有補充內容，所有議題都要根據描述內容在描述最後產生 TODO list，依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-analyze、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。
|
||||
---
|
||||
|
||||
# 分析 Issue 並拆解為實作階段與交付留言
|
||||
# 分析多來源需求並保存為議題
|
||||
|
||||
你要讀取使用者提供的一或多筆 Gitea issue，彙整成完整需求文件，依功能拆成多個實作階段（每階段建立一個 issue），配合指定的 repositories 產生實作草稿，最後產出交付文件並依 issues 分組留言。**建立 issue 與留言屬於對外且不易復原的動作，必須先讓使用者確認過草稿再執行**。所有需求彙整、階段拆分與實作草稿一律先產生草稿檔，再詢問使用者是否實際建立 issue / 留言。請依下列階段依序完成。
|
||||
你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源並彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日。第四步必須將小功能議題依到期日排序，逐個議題實作並將進度留言到議題，完成後 PR 到 `develop` 或 `master`；**實作任何議題前必須先詢問使用者並取得確認，不得擅自開始修改程式碼；但使用者確認開始實作該議題後，可在該議題範圍內自行 commit、push 與開 PR**。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。
|
||||
|
||||
## 前置：輸入與工具
|
||||
|
||||
- **輸入**：至少一筆 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` 已設定）。
|
||||
- **輸入來源**：使用者必須選擇要讀取的來源種類，可多選且數量必須 `>= 1`：
|
||||
- **專案編號**：Gitea project 編號或可定位 project 的 URL／識別資訊；若選取專案編號，必須只讀取該專案下開啟中的議題（含可取得的卡片／欄位／描述）；也可作為保存整理結果的目標專案。
|
||||
- **議題編號**：Gitea issue 編號或 issue URL，可多筆。
|
||||
- **檔案文件**：本機文件路徑，可多筆；支援 Markdown、純文字與其他可直接讀取的需求文件。
|
||||
- **保存目標**：合併整理後必須在指定專案建立一張議題保存；若輸入來源未包含可作為保存目標的專案編號，必須詢問使用者提供專案編號，不得自行臆測。
|
||||
- **repositories 位置**：可另外指定本機含多個專案的資料夾；若未指定，實作參考以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。
|
||||
- **工具選擇**：在解析與讀取 Gitea 來源前，先檢查本機是否可用 `tea`、`tea login list` 是否有對應 login、以及環境變數 `GITEA_TOKEN` 是否已設定；接著詢問使用者要使用 `tea` 或 Gitea REST API + `curl` + token。使用者已明確指定工具時才可跳過詢問。
|
||||
- **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
|
||||
- **工作目錄**：所有草稿與文件放在 `.docs/doc-issues-analyze/`。
|
||||
- **禁止草稿落地**：所有流程都不准建立 `.docs/` 或其他本機草稿檔；需求整理、小功能拆分、排序、進度與交付資訊一律使用 `tea` 或 Gitea API 保存到對應議題描述或留言。
|
||||
- **TODO list**：所有建立或更新的議題描述最後都必須加上依該描述內容推導出的 `## TODO` 區塊，使用 Markdown checklist（`- [ ] ...`）；TODO 必須可執行、可驗收，且不得加入描述未提及或無法合理推得的工作。
|
||||
|
||||
## 第 0 步：解析 issue URL 與準備工具
|
||||
## 第 1 步：工具可用性檢查與使用方式選擇
|
||||
|
||||
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）。
|
||||
先檢查可用工具並選擇後續使用方式。除非使用者已明確指定 `tea` 或 `api`，否則不得自行決定。
|
||||
|
||||
## 第 1 步：讀取 issues 內容
|
||||
1. 檢查 `tea` 是否存在：`command -v tea`。
|
||||
2. 若 `tea` 存在，執行 `tea login list`，記錄可用 login 與其 host；若失敗，記錄失敗原因但不要中止。
|
||||
3. 檢查 `GITEA_TOKEN` 是否已設定，只輸出「已設定／未設定」，不得輸出 token 內容。
|
||||
4. 依檢查結果詢問使用者要使用哪一種方式：
|
||||
- `tea`：只有在 `tea` 可執行時才可選；後續解析來源後仍需確認來源 host 有對應 login。
|
||||
- `api`：只有在 `GITEA_TOKEN` 已設定時才可選；後續使用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`。
|
||||
5. 若兩種方式都不可用，停止並回報缺少 `tea login` 或 `GITEA_TOKEN`；不要要求使用者把 token 貼進對話。
|
||||
|
||||
對每一筆 issue，讀取完整內容：`title`、`body`、`state`、`labels`、`milestone`、`assignees`、以及**所有 comments**；若 Gitea 版本支援，另讀該 issue 所屬 `project`。
|
||||
## 第 2 步：選擇讀取來源、讀取內容並保存議題內容
|
||||
|
||||
- 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 既有的分類資源，供後續階段沿用：
|
||||
這是必要決策。若使用者尚未明確提供來源種類，必須先詢問要讀取哪些來源種類，並要求至少選一種：
|
||||
|
||||
1. 專案編號。
|
||||
2. 議題編號。
|
||||
3. 檔案文件。
|
||||
|
||||
選定後收集對應輸入：
|
||||
|
||||
- 選「專案編號」：收集 project 編號或 project URL，並確認其 host／owner／repo／project id（若資訊不足，先詢問補齊）；後續必須只讀取該專案下開啟中的議題。
|
||||
- 選「議題編號」：收集 issue 編號或 issue URL；若只提供編號，必須確認其 host／owner／repo。
|
||||
- 選「檔案文件」：收集本機檔案路徑並確認存在；不存在的檔案先回報並請使用者修正。
|
||||
|
||||
合併整理後一定要建立一張保存議題：
|
||||
|
||||
- 若已提供專案編號，詢問是否使用該專案作為保存目標；使用者可改指定其他專案。
|
||||
- 若未提供專案編號，必須詢問保存用專案編號或 project URL。
|
||||
- 不得在缺少保存目標專案時繼續到對外建立議題的步驟。
|
||||
|
||||
接著執行：
|
||||
|
||||
1. 解析每一筆來源：
|
||||
- 專案：解析出 `host`、`owner`、`repo`、`project id` 或可定位 project 的資訊。
|
||||
- 議題：解析出 `host`、`owner`、`repo`、`index`（例如 `https://<host>/<owner>/<repo>/issues/<index>`）。
|
||||
- 檔案：解析出本機絕對路徑、檔名與格式。
|
||||
2. 依第 1 步選定的工具建立每筆 Gitea 來源的存取設定：
|
||||
- `tea`：找出對應 host 的 login，後續命令一律帶 `--login <name> --repo <owner>/<repo>`。
|
||||
- `api`：base 為 `https://<host>/api/v1/repos/<owner>/<repo>`。
|
||||
- 若多筆專案／議題分屬不同 host，選擇 `tea` 時必須確認每個 host 都有對應 login；選擇 `api` 時同一個 `GITEA_TOKEN` 必須可存取全部專案／議題，否則在讀取階段回報權限不足並停止。
|
||||
3. 顯示本次處理的基本資料，至少包含：
|
||||
- 選定工具：`tea` 或 `api`。
|
||||
- 若選 `tea`：每個 host 對應的 login 名稱；若選 `api`：顯示 `GITEA_TOKEN` 已設定，不顯示 token 內容。
|
||||
- 讀取來源種類：專案編號／議題編號／檔案文件，至少一種。
|
||||
- 來源專案：每筆 project 的 host、owner、repo、project id（若有）。
|
||||
- 來源議題：每筆 issue 的 URL、host、owner、repo、index（若有）。
|
||||
- 來源檔案：每筆檔案的路徑與格式（若有）。
|
||||
- 保存目標專案：host、owner、repo、project id。
|
||||
- target repositories 來源：使用者指定的 repositories 位置，或「以來源議題所在 repo／保存目標 repo 為準」。
|
||||
4. 若使用者指定了 repositories 位置，先確認該路徑存在並列出其中的專案；若未指定，記錄「以來源議題所在 repo／保存目標 repo 為準」，並確認本機是否已 clone 對應 repo（沒有就在保存議題留言中標註需人工提供或 clone）。
|
||||
5. 依選定來源讀取內容：
|
||||
- 專案：讀取 project 描述、欄位／卡片、project metadata，並只讀取該專案下**開啟中的議題**（若 API 有分頁必須完整分頁讀取）。若 Gitea 版本不支援 project API 或無法由 project 取得開啟中的 issue 清單，標註「此 Gitea 版本不支援 project API，需人工處理」，並請使用者改提供議題編號或可匯出的 project 文件。
|
||||
- 議題：對每一筆 issue，讀取完整內容：`title`、`body`、`state`、`labels`、`milestone`、`assignees`、以及**所有 comments**；若 Gitea 版本支援，另讀該 issue 所屬 `project`。
|
||||
- 檔案文件：讀取文件全文；若格式無法直接讀取，標註需人工轉換或提供純文字／Markdown。
|
||||
6. 同時盤點該 repo 既有的分類資源，供後續階段沿用：
|
||||
- 標籤：`GET {base}/labels`（tea：`tea labels list`）
|
||||
- 里程碑：`GET {base}/milestones`（tea：`tea milestones list`）
|
||||
- 專案（若該 Gitea 版本有此 API）：`GET {base}/projects`；若不支援就記錄「此 Gitea 版本不支援 project API，需人工處理」。
|
||||
7. 把所有來源內容彙整成保存議題內容，使用 `tea` 或 Gitea API 建立或更新保存議題；不得寫入本機草稿檔。保存議題描述至少包含：
|
||||
- 來源清單：每筆專案／議題／檔案的來源資訊、標題或名稱、狀態、現有 labels／milestone／project（若適用）。
|
||||
- 完整需求描述：整合專案、議題、檔案文件的內容，去除重複、補齊上下文，形成單一連貫的需求敘述。
|
||||
- 驗收條件／預期結果：能從來源內容推得的，逐條列出；不能確定的標註「需人工確認」。
|
||||
- 保存議題分類：labels／milestone／project 掛載方式。
|
||||
- `## TODO`：根據保存議題描述內容產生 Markdown checklist，放在描述最後。
|
||||
|
||||
## 第 2 步：彙整需求文件
|
||||
需求彙整只做整理與歸納，不得編造來源內容未提及的需求；無法確定處保守描述並標註。
|
||||
|
||||
把所有 issue 內容彙整成一份完整需求文件 `.docs/doc-issues-analyze/requirements.md`，內容至少包含：
|
||||
## 第 3 步：拆分小功能議題
|
||||
|
||||
- 來源 issue 清單：每筆的 URL、標題、狀態、現有 labels／milestone／project。
|
||||
- 完整需求描述：整合各 issue 的正文與留言，去除重複、補齊上下文，形成單一連貫的需求敘述。
|
||||
- 驗收條件／預期結果：能從 issue 推得的，逐條列出；不能確定的標註「需人工確認」。
|
||||
- 分類資源盤點：此 repo 現有可用的 labels、milestones、projects（供第 3 步沿用）。
|
||||
將第 2 步保存到議題的內容拆分成多個小功能議題，使用 `tea` 或 Gitea API 建立／更新小功能議題或將小功能清單留言到保存議題；不得寫入本機草稿檔。每個小功能議題至少包含：
|
||||
|
||||
需求彙整只做整理與歸納，不得編造 issue 未提及的需求；無法確定處保守描述並標註。
|
||||
- 標題：能清楚表示單一小功能交付範圍。
|
||||
- 描述：描述內容必須先詢問使用者想要包含哪些段落或資訊，至少提供可選項，例如需求背景、功能範圍、驗收條件、技術提示、測試方式、相依關係、風險與備註；依使用者選擇組成描述，不得自行固定格式。每個小功能議題建立或更新前，都必須逐一詢問使用者該議題描述是否有補充內容；使用者提供補充時，必須整合到該小功能議題描述中，若使用者明確表示沒有補充才可繼續建立或更新。描述最後必須加入 `## TODO` 區塊，根據該小功能描述內容產生 Markdown checklist。
|
||||
- 阻擋關閉：小功能議題建立後必須以可追溯方式阻擋其被直接關閉，直到驗收條件完成。可用方式包含加上既有 blocking／blocked 類標籤、在 body 中加入「關閉前檢查清單」、建立與保存議題的追溯連結，或依 Gitea 支援能力設定 issue dependency；不得使用不存在的標籤或 API，找不到支援方式時標註需人工處理。若小功能有前後相依，較先完成的前置議題必須阻擋較後完成的後置議題（前置 issue blocks 後置 issue；後置 issue is blocked by 前置 issue），不得反向設定。
|
||||
- 複雜度：依工作量、跨模組程度、風險、未知數與測試成本評估為 `S`／`M`／`L`／`XL`。
|
||||
- 到期日：根據複雜度評估 due date，預設從建立日往後推算：`S` 3 個工作天、`M` 5 個工作天、`L` 10 個工作天、`XL` 15 個工作天；若遇週末順延到下一個工作天。若小功能有相依關係，必須先排定相依順序，後置功能的到期日不得早於其前置功能的到期日，且應從最後一個前置功能的到期日之後再依自身複雜度推算。若 Gitea API 不支援 due date，寫入 issue body 並回報需人工設定。
|
||||
- 相依關係：列出與保存議題、來源議題與其他小功能議題的關聯；若有前後依賴，必須標明前置功能、後置功能、阻擋方向與到期日排程依據。
|
||||
|
||||
## 第 3 步：依功能拆分實作階段（規劃要建立的 issues）
|
||||
決定要對照的 target repositories：使用者指定位置底下的所有專案、來源議題所在 repo，或使用者指定 repo。可研究相關專案程式碼以補充小功能議題描述，但所有分析結果必須直接保存到小功能議題描述或留言，不得建立本機草稿檔。
|
||||
|
||||
依功能把需求拆成多個實作階段（phase），**每個階段對應一個未來要建立的 issue**，產生草稿 `.docs/doc-issues-analyze/phases.md`。每個階段記錄：
|
||||
## 第 4 步：依到期日排序並逐議題實作
|
||||
|
||||
- 階段編號與標題（將作為新 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）。
|
||||
將第 3 步產生的小功能議題依到期日由早到晚排序；若到期日相同，依相依關係排序，前置議題必須排在後置議題前。排序結果必須使用 `tea` 或 Gitea API 留言到保存議題或相關小功能議題，不得寫入本機檔案。
|
||||
|
||||
## 第 4 步：確定 target repositories 並產生實作草稿（派 subagent）
|
||||
開始實作前必須逐個議題詢問使用者，至少提供該議題的標題、URL（若已建立）、到期日、相依關係、預計修改範圍與驗證方式。未取得使用者確認前，不得修改任何原始碼、不得 commit、不得 push、不得開 PR。使用者確認開始實作某一議題後，即授權在該議題範圍內自行 commit、push 工作分支並開 PR，不需要對每個 git 動作再次詢問。
|
||||
|
||||
決定要對照的 target repositories：使用者指定位置底下的所有專案，或各 issue 所在的 repository。對**每一個實作階段各派一個 subagent**，研究相關專案程式碼後產生實作草稿 `.docs/doc-issues-analyze/drafts/phase-{N}.md`。subagent 只讀程式碼與必要上下文、**不修改任何原始碼、不建立 issue、不留言**，只在 `.docs/` 底下寫草稿。每份草稿包含：
|
||||
使用者確認某一議題後，才可對該議題執行：
|
||||
|
||||
- 對應階段與對應（將建立的）issue 標題。
|
||||
- 涉及的專案／檔案清單與定位（以 `path:line` 形式標出關鍵位置）。
|
||||
- 建議的實作方式：要新增或修改什麼、涉及的介面／資料流、相依與風險。
|
||||
- 測試與驗證方式建議。
|
||||
- 無法從程式碼可靠推得的部分，保守標註「需人工確認」，不要臆測。
|
||||
- 建立或切換工作分支，分支名稱應包含議題編號或小功能識別。
|
||||
- 依議題描述實作，過程中定期將進度留言到該議題；至少包含開始實作、主要變更完成、驗證結果、PR 連結。
|
||||
- 只修改該議題必要範圍；若發現需要擴大範圍或改動其他議題，先停止並詢問使用者。
|
||||
- 執行適合專案的測試／建置／驗證；失敗時留言說明失敗原因與下一步。
|
||||
- 完成後提交變更並推送工作分支，向 `develop` 開 PR；若遠端沒有 `develop`，改向 `master` 開 PR。不得直接 push 到 `develop` 或 `master`。
|
||||
- PR 內容必須連結對應小功能議題，並摘要變更、測試結果、風險與需人工確認項目。
|
||||
|
||||
## 第 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 名稱、型別名稱與程式碼片段可保留英文。
|
||||
若小功能議題尚未實際建立到 Gitea，本步只能產生排序與實作計畫，不得開始實作；必須先回到建立小功能議題的確認流程。
|
||||
|
||||
@@ -1,120 +0,0 @@
|
||||
---
|
||||
name: doc-issues-breakdown
|
||||
description: 讀取使用者選擇的一或多種來源（專案編號、議題編號、檔案文件；至少一種；若選專案編號則只讀取該專案下開啟中的議題），先檢查 tea 與 GITEA_TOKEN 並詢問使用者要用 tea 或 Gitea API + token，將來源內容合併整理成保存議題內容，再拆分成多個小功能議題（標題、描述、阻擋關閉、依複雜度評估到期日），每個小功能議題都必須詢問使用者描述是否有補充內容，所有議題都要根據描述內容在描述最後產生 TODO list，依到期日排序並在使用者逐議題確認後實作、留言進度、完成後 PR 到 develop 或 master。當使用者要把需求拆成小功能議題、依專案／議題／文件產生保存議題與功能議題、依到期日排程實作、或提到 doc-issues-breakdown、issue breakdown、議題拆分、小功能議題、Gitea issue 拆解時使用此 skill。
|
||||
---
|
||||
|
||||
# 分析多來源需求並保存為議題
|
||||
|
||||
你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源並彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日。第四步必須將小功能議題依到期日排序，逐個議題實作並將進度留言到議題，完成後 PR 到 `develop` 或 `master`；**實作任何議題前必須先詢問使用者並取得確認，不得擅自開始修改程式碼；但使用者確認開始實作該議題後，可在該議題範圍內自行 commit、push 與開 PR**。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。
|
||||
|
||||
## 前置：輸入與工具
|
||||
|
||||
- **輸入來源**：使用者必須選擇要讀取的來源種類，可多選且數量必須 `>= 1`：
|
||||
- **專案編號**：Gitea project 編號或可定位 project 的 URL／識別資訊；若選取專案編號，必須只讀取該專案下開啟中的議題（含可取得的卡片／欄位／描述）；也可作為保存整理結果的目標專案。
|
||||
- **議題編號**：Gitea issue 編號或 issue URL，可多筆。
|
||||
- **檔案文件**：本機文件路徑，可多筆；支援 Markdown、純文字與其他可直接讀取的需求文件。
|
||||
- **保存目標**：合併整理後必須在指定專案建立一張議題保存；若輸入來源未包含可作為保存目標的專案編號，必須詢問使用者提供專案編號，不得自行臆測。
|
||||
- **repositories 位置**：可另外指定本機含多個專案的資料夾；若未指定，實作參考以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。
|
||||
- **工具選擇**：在解析與讀取 Gitea 來源前，先檢查本機是否可用 `tea`、`tea login list` 是否有對應 login、以及環境變數 `GITEA_TOKEN` 是否已設定；接著詢問使用者要使用 `tea` 或 Gitea REST API + `curl` + token。使用者已明確指定工具時才可跳過詢問。
|
||||
- **不要依賴 `jq`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
|
||||
- **禁止草稿落地**：所有流程都不准建立 `.docs/` 或其他本機草稿檔；需求整理、小功能拆分、排序、進度與交付資訊一律使用 `tea` 或 Gitea API 保存到對應議題描述或留言。
|
||||
- **TODO list**：所有建立或更新的議題描述最後都必須加上依該描述內容推導出的 `## TODO` 區塊，使用 Markdown checklist（`- [ ] ...`）；TODO 必須可執行、可驗收，且不得加入描述未提及或無法合理推得的工作。
|
||||
|
||||
## 第 1 步：工具可用性檢查與使用方式選擇
|
||||
|
||||
先檢查可用工具並選擇後續使用方式。除非使用者已明確指定 `tea` 或 `api`，否則不得自行決定。
|
||||
|
||||
1. 檢查 `tea` 是否存在：`command -v tea`。
|
||||
2. 若 `tea` 存在，執行 `tea login list`，記錄可用 login 與其 host；若失敗，記錄失敗原因但不要中止。
|
||||
3. 檢查 `GITEA_TOKEN` 是否已設定，只輸出「已設定／未設定」，不得輸出 token 內容。
|
||||
4. 依檢查結果詢問使用者要使用哪一種方式：
|
||||
- `tea`：只有在 `tea` 可執行時才可選；後續解析來源後仍需確認來源 host 有對應 login。
|
||||
- `api`：只有在 `GITEA_TOKEN` 已設定時才可選；後續使用 Gitea REST API + `curl`，帶標頭 `Authorization: token $GITEA_TOKEN`。
|
||||
5. 若兩種方式都不可用，停止並回報缺少 `tea login` 或 `GITEA_TOKEN`；不要要求使用者把 token 貼進對話。
|
||||
|
||||
## 第 2 步：選擇讀取來源、讀取內容並保存議題內容
|
||||
|
||||
這是必要決策。若使用者尚未明確提供來源種類，必須先詢問要讀取哪些來源種類，並要求至少選一種：
|
||||
|
||||
1. 專案編號。
|
||||
2. 議題編號。
|
||||
3. 檔案文件。
|
||||
|
||||
選定後收集對應輸入：
|
||||
|
||||
- 選「專案編號」：收集 project 編號或 project URL，並確認其 host／owner／repo／project id（若資訊不足，先詢問補齊）；後續必須只讀取該專案下開啟中的議題。
|
||||
- 選「議題編號」：收集 issue 編號或 issue URL；若只提供編號，必須確認其 host／owner／repo。
|
||||
- 選「檔案文件」：收集本機檔案路徑並確認存在；不存在的檔案先回報並請使用者修正。
|
||||
|
||||
合併整理後一定要建立一張保存議題：
|
||||
|
||||
- 若已提供專案編號，詢問是否使用該專案作為保存目標；使用者可改指定其他專案。
|
||||
- 若未提供專案編號，必須詢問保存用專案編號或 project URL。
|
||||
- 不得在缺少保存目標專案時繼續到對外建立議題的步驟。
|
||||
|
||||
接著執行：
|
||||
|
||||
1. 解析每一筆來源：
|
||||
- 專案：解析出 `host`、`owner`、`repo`、`project id` 或可定位 project 的資訊。
|
||||
- 議題：解析出 `host`、`owner`、`repo`、`index`（例如 `https://<host>/<owner>/<repo>/issues/<index>`）。
|
||||
- 檔案：解析出本機絕對路徑、檔名與格式。
|
||||
2. 依第 1 步選定的工具建立每筆 Gitea 來源的存取設定：
|
||||
- `tea`：找出對應 host 的 login，後續命令一律帶 `--login <name> --repo <owner>/<repo>`。
|
||||
- `api`：base 為 `https://<host>/api/v1/repos/<owner>/<repo>`。
|
||||
- 若多筆專案／議題分屬不同 host，選擇 `tea` 時必須確認每個 host 都有對應 login；選擇 `api` 時同一個 `GITEA_TOKEN` 必須可存取全部專案／議題，否則在讀取階段回報權限不足並停止。
|
||||
3. 顯示本次處理的基本資料，至少包含：
|
||||
- 選定工具：`tea` 或 `api`。
|
||||
- 若選 `tea`：每個 host 對應的 login 名稱；若選 `api`：顯示 `GITEA_TOKEN` 已設定，不顯示 token 內容。
|
||||
- 讀取來源種類：專案編號／議題編號／檔案文件，至少一種。
|
||||
- 來源專案：每筆 project 的 host、owner、repo、project id（若有）。
|
||||
- 來源議題：每筆 issue 的 URL、host、owner、repo、index（若有）。
|
||||
- 來源檔案：每筆檔案的路徑與格式（若有）。
|
||||
- 保存目標專案：host、owner、repo、project id。
|
||||
- target repositories 來源：使用者指定的 repositories 位置，或「以來源議題所在 repo／保存目標 repo 為準」。
|
||||
4. 若使用者指定了 repositories 位置，先確認該路徑存在並列出其中的專案；若未指定，記錄「以來源議題所在 repo／保存目標 repo 為準」，並確認本機是否已 clone 對應 repo（沒有就在保存議題留言中標註需人工提供或 clone）。
|
||||
5. 依選定來源讀取內容：
|
||||
- 專案：讀取 project 描述、欄位／卡片、project metadata，並只讀取該專案下**開啟中的議題**（若 API 有分頁必須完整分頁讀取）。若 Gitea 版本不支援 project API 或無法由 project 取得開啟中的 issue 清單，標註「此 Gitea 版本不支援 project API，需人工處理」，並請使用者改提供議題編號或可匯出的 project 文件。
|
||||
- 議題：對每一筆 issue，讀取完整內容：`title`、`body`、`state`、`labels`、`milestone`、`assignees`、以及**所有 comments**；若 Gitea 版本支援，另讀該 issue 所屬 `project`。
|
||||
- 檔案文件：讀取文件全文；若格式無法直接讀取，標註需人工轉換或提供純文字／Markdown。
|
||||
6. 同時盤點該 repo 既有的分類資源，供後續階段沿用：
|
||||
- 標籤：`GET {base}/labels`（tea：`tea labels list`）
|
||||
- 里程碑：`GET {base}/milestones`（tea：`tea milestones list`）
|
||||
- 專案（若該 Gitea 版本有此 API）：`GET {base}/projects`；若不支援就記錄「此 Gitea 版本不支援 project API，需人工處理」。
|
||||
7. 把所有來源內容彙整成保存議題內容，使用 `tea` 或 Gitea API 建立或更新保存議題；不得寫入本機草稿檔。保存議題描述至少包含：
|
||||
- 來源清單：每筆專案／議題／檔案的來源資訊、標題或名稱、狀態、現有 labels／milestone／project（若適用）。
|
||||
- 完整需求描述：整合專案、議題、檔案文件的內容，去除重複、補齊上下文，形成單一連貫的需求敘述。
|
||||
- 驗收條件／預期結果：能從來源內容推得的，逐條列出；不能確定的標註「需人工確認」。
|
||||
- 保存議題分類：labels／milestone／project 掛載方式。
|
||||
- `## TODO`：根據保存議題描述內容產生 Markdown checklist，放在描述最後。
|
||||
|
||||
需求彙整只做整理與歸納，不得編造來源內容未提及的需求；無法確定處保守描述並標註。
|
||||
|
||||
## 第 3 步：拆分小功能議題
|
||||
|
||||
將第 2 步保存到議題的內容拆分成多個小功能議題，使用 `tea` 或 Gitea API 建立／更新小功能議題或將小功能清單留言到保存議題；不得寫入本機草稿檔。每個小功能議題至少包含：
|
||||
|
||||
- 標題：能清楚表示單一小功能交付範圍。
|
||||
- 描述：描述內容必須先詢問使用者想要包含哪些段落或資訊，至少提供可選項，例如需求背景、功能範圍、驗收條件、技術提示、測試方式、相依關係、風險與備註；依使用者選擇組成描述，不得自行固定格式。每個小功能議題建立或更新前，都必須逐一詢問使用者該議題描述是否有補充內容；使用者提供補充時，必須整合到該小功能議題描述中，若使用者明確表示沒有補充才可繼續建立或更新。描述最後必須加入 `## TODO` 區塊，根據該小功能描述內容產生 Markdown checklist。
|
||||
- 阻擋關閉：小功能議題建立後必須以可追溯方式阻擋其被直接關閉，直到驗收條件完成。可用方式包含加上既有 blocking／blocked 類標籤、在 body 中加入「關閉前檢查清單」、建立與保存議題的追溯連結，或依 Gitea 支援能力設定 issue dependency；不得使用不存在的標籤或 API，找不到支援方式時標註需人工處理。若小功能有前後相依，較先完成的前置議題必須阻擋較後完成的後置議題（前置 issue blocks 後置 issue；後置 issue is blocked by 前置 issue），不得反向設定。
|
||||
- 複雜度：依工作量、跨模組程度、風險、未知數與測試成本評估為 `S`／`M`／`L`／`XL`。
|
||||
- 到期日：根據複雜度評估 due date，預設從建立日往後推算：`S` 3 個工作天、`M` 5 個工作天、`L` 10 個工作天、`XL` 15 個工作天；若遇週末順延到下一個工作天。若小功能有相依關係，必須先排定相依順序，後置功能的到期日不得早於其前置功能的到期日，且應從最後一個前置功能的到期日之後再依自身複雜度推算。若 Gitea API 不支援 due date，寫入 issue body 並回報需人工設定。
|
||||
- 相依關係：列出與保存議題、來源議題與其他小功能議題的關聯；若有前後依賴，必須標明前置功能、後置功能、阻擋方向與到期日排程依據。
|
||||
|
||||
決定要對照的 target repositories：使用者指定位置底下的所有專案、來源議題所在 repo，或使用者指定 repo。可研究相關專案程式碼以補充小功能議題描述，但所有分析結果必須直接保存到小功能議題描述或留言，不得建立本機草稿檔。
|
||||
|
||||
## 第 4 步：依到期日排序並逐議題實作
|
||||
|
||||
將第 3 步產生的小功能議題依到期日由早到晚排序；若到期日相同，依相依關係排序，前置議題必須排在後置議題前。排序結果必須使用 `tea` 或 Gitea API 留言到保存議題或相關小功能議題，不得寫入本機檔案。
|
||||
|
||||
開始實作前必須逐個議題詢問使用者，至少提供該議題的標題、URL（若已建立）、到期日、相依關係、預計修改範圍與驗證方式。未取得使用者確認前，不得修改任何原始碼、不得 commit、不得 push、不得開 PR。使用者確認開始實作某一議題後，即授權在該議題範圍內自行 commit、push 工作分支並開 PR，不需要對每個 git 動作再次詢問。
|
||||
|
||||
使用者確認某一議題後，才可對該議題執行：
|
||||
|
||||
- 建立或切換工作分支，分支名稱應包含議題編號或小功能識別。
|
||||
- 依議題描述實作，過程中定期將進度留言到該議題；至少包含開始實作、主要變更完成、驗證結果、PR 連結。
|
||||
- 只修改該議題必要範圍；若發現需要擴大範圍或改動其他議題，先停止並詢問使用者。
|
||||
- 執行適合專案的測試／建置／驗證；失敗時留言說明失敗原因與下一步。
|
||||
- 完成後提交變更並推送工作分支，向 `develop` 開 PR；若遠端沒有 `develop`，改向 `master` 開 PR。不得直接 push 到 `develop` 或 `master`。
|
||||
- PR 內容必須連結對應小功能議題，並摘要變更、測試結果、風險與需人工確認項目。
|
||||
|
||||
若小功能議題尚未實際建立到 Gitea，本步只能產生排序與實作計畫，不得開始實作；必須先回到建立小功能議題的確認流程。
|
||||
@@ -0,0 +1,111 @@
|
||||
---
|
||||
name: doc-issues-sync
|
||||
description: 讀取一個 Gitea 專案（project）或單一議題（優先用 tea，否則用 Gitea REST API + curl + GITEA_TOKEN，不依賴 jq）；若給的是專案就讀取與此專案關聯的所有議題，若給的是議題就只同步該議題。議題若有標籤就依標籤分組並以 AskUserQuestion 讓使用者挑選要同步哪些標籤的議題（只有一個議題或全部無標籤則跳過）。接著一個議題派一個 subagent，基於工作目錄下的所有檔案：分析議題描述的需求並判斷議題內的 TODO（markdown 任務清單）是否足以追蹤議題描述的需求、不足就補上 TODO 追加到議題正文、依需求從既有標籤更新議題標籤、逐條判斷未完成 TODO（含新增）是否已完成、有異動就整理成一則留言。所有對 Gitea 的寫入（改正文／改標籤／留言）先產生草稿並經使用者確認再執行。當使用者要同步議題進度、依專案批次更新議題 TODO、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 doc-issues-sync、issue sync、議題同步、TODO 勾稽、tea issues、Gitea 專案議題時使用此 skill。
|
||||
---
|
||||
|
||||
# 依工作目錄同步 Gitea 專案／議題的 TODO 進度與標籤
|
||||
|
||||
你要讀取使用者提供的一個 Gitea **專案（project）**或**單一議題**，取得要同步的議題清單，然後一個議題派一個 subagent，**以目前工作目錄下的所有檔案為依據**，勾稽並更新每個議題的 TODO（markdown 任務清單）與標籤，最後把 TODO 的異動整理成留言。**修改議題正文、變更議題標籤、留言都是對外且不易復原的動作，subagent 只產生草稿，實際寫入 Gitea 前必須先讓使用者確認**。請依下列階段依序完成。
|
||||
|
||||
## 前置：輸入與工具
|
||||
|
||||
- **輸入**：一個 Gitea 專案（project）或一筆議題的參照（URL 最佳，或 `owner/repo` + project id／issue index）。
|
||||
- **依據來源**：所有「TODO 是否完成」「該補哪些 TODO」「該掛哪些標籤」的判斷，一律以**目前工作目錄下的檔案內容**為準（程式碼、設定、文件等），不得臆測。
|
||||
- **工具優先序**：
|
||||
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`（環境未安裝）**：需要解析 JSON 時，用 `tea` 的結構化輸出（例如 `--fields ... --output csv`），或把原始 JSON 交給 subagent 解析，不要在指令中 pipe 到 `jq`。
|
||||
- **TODO 的定義**：議題正文（body）中的 markdown 任務清單項目，`- [ ]`（未完成）與 `- [x]`（已完成）。本 skill 所有「TODO 追蹤／勾稽／新增」都在這種任務清單上操作。
|
||||
- **工作目錄**：所有草稿放在 `.docs/doc-issues-sync/`。
|
||||
|
||||
## 第 0 步：解析輸入、判斷專案或議題、準備工具
|
||||
|
||||
1. 從輸入解析出 `host`、`owner`、`repo`，並判斷這是**專案**還是**議題**：
|
||||
- 議題 URL 形如 `https://<host>/<owner>/<repo>/issues/<index>` → 議題。
|
||||
- 專案 URL 形如 `https://<host>/<owner>/<repo>/projects/<id>` 或組織層級 `https://<host>/<owner>/-/projects/<id>` → 專案。
|
||||
2. 執行 `tea login list`，判斷該 host 走 tea 還是 API（API base 為 `https://<host>/api/v1`）。
|
||||
3. 建立 `.docs/doc-issues-sync/`（若不存在）。
|
||||
4. **找不到就詢問使用者（AskUserQuestion）**：若無法從輸入判斷是專案還是議題、或依輸入查不到對應的專案／議題（例如 API 回 404、專案 id 不存在、repo 拼錯），必須用 AskUserQuestion 請使用者補齊或更正（host／owner／repo、專案 id 或議題 URL）。取得可解析的目標前，不進入下一步。
|
||||
|
||||
## 第 1 步：取得要同步的議題清單
|
||||
|
||||
- **若輸入是議題**：清單就是這一筆議題，**跳過本步的專案展開**，直接進入第 2 步。
|
||||
- **若輸入是專案**：讀取與此專案關聯的所有議題。
|
||||
- tea：優先用 tea 對應指令列出專案關聯議題；若該版本 tea 無法列專案議題，改用 API。
|
||||
- API：以 Gitea 的 project／board API 取得該專案掛載的所有議題（column／card → issue），彙整成議題清單（每筆記下 `owner/repo`、`index`、`title`、`labels`）。
|
||||
- 若該 Gitea 版本不支援 project API 或查不到關聯議題，用 AskUserQuestion 告知並請使用者改提供議題清單（或改給單一議題 URL），不要自行臆測要同步哪些議題。
|
||||
|
||||
## 第 2 步：依標籤分組並詢問要同步哪些（AskUserQuestion）
|
||||
|
||||
1. 讀取清單中每個議題的 `labels`。
|
||||
2. **跳過條件**：若清單只有**一個議題**，或**所有議題都沒有標籤**，跳過本步、同步全部清單。
|
||||
3. 否則依標籤把議題分組（一個議題有多個標籤時，各組都出現），用 **AskUserQuestion（multiSelect）** 讓使用者挑選要同步「哪些標籤」的議題：
|
||||
- 每個選項是一個標籤（附該標籤下的議題數量），讓使用者多選。
|
||||
- 標籤數量超過 AskUserQuestion 選項上限（4）時，改在訊息中列出全部標籤與各自議題數，請使用者回覆要同步哪些（可用「其他」自訂輸入）。
|
||||
4. 依選取的標籤過濾清單：保留**帶有任一選取標籤**的議題，作為後續要同步的最終清單。未被選取標籤涵蓋的議題不同步。
|
||||
|
||||
## 第 3 步：逐議題派 subagent 產生同步草稿（每個議題一個 subagent）
|
||||
|
||||
對最終清單中的**每一個議題各派一個 subagent**。subagent **以目前工作目錄下的所有檔案為依據**，只讀檔案與議題、**只在 `.docs/doc-issues-sync/` 底下寫草稿**，**不得修改任何工作目錄的原始碼、不得直接改議題正文／標籤、不得直接留言**。每個 subagent 依序做：
|
||||
|
||||
1. **讀取議題**：`title`、`body`（含其中的 TODO 任務清單）、`labels`、以及既有 comments。
|
||||
- tea：`tea issues <index> --repo <owner>/<repo> --login <name> --comments`。
|
||||
- API：`GET {base}/repos/{owner}/{repo}/issues/{index}` 與 `.../comments`。
|
||||
- 一併盤點該 repo 既有標籤（供第 3.2 用）：`GET {base}/repos/{owner}/{repo}/labels`（tea：`tea labels list`）。
|
||||
2. **3.1 判斷 TODO 是否足以追蹤議題描述的需求，不足就補**：分析議題描述的需求，逐項對照現有 TODO，判斷目前的 TODO 清單是否足以追蹤議題描述的需求。若不足，補上缺少的 TODO（以未完成 `- [ ]` 形式），規劃**追加到議題正文**（草稿中給出「追加後的正文」與「新增了哪些 TODO」）。補的 TODO 必須能對應到議題描述的需求，不得編造需求未涵蓋的項目。
|
||||
3. **3.2 依需求更新可用標籤**：依議題需求性質，從該 repo **既有標籤**中挑選應掛上（或應移除）的標籤，草稿中列出「建議的標籤異動」（新增哪些、移除哪些、維持哪些）。**不自行新建標籤**，除非使用者要求；找不到合適標籤就維持原樣並標註。
|
||||
4. **3.3 逐條勾稽未完成 TODO 是否已完成**：對所有**未完成**的 TODO（含 3.1 新增的），逐條依工作目錄下的檔案內容判斷是否已完成。已完成者標記為 `- [x]` 並在草稿記下判斷依據（以 `path:line` 指出對應實作位置）；無法從檔案可靠判斷者維持未完成並標註「需人工確認」。
|
||||
5. **3.4 整理 TODO 異動留言**：若本議題有任何 TODO 異動（**新增**的 TODO，或**狀態變更**——由未完成改為完成），整理成一則留言草稿，內容包含：本次新增了哪些 TODO、哪些 TODO 判定為完成（附對應實作位置）、哪些仍未完成（含原因／需人工確認）。若沒有任何 TODO 異動，草稿標明「無異動、不需留言」。
|
||||
|
||||
每個 subagent 產出一份 `.docs/doc-issues-sync/issue-{owner}-{repo}-{index}.md`，至少包含：議題參照與標題、追加後的完整正文（標明新增與勾稽的變更）、建議的標籤異動、TODO 異動留言草稿（或「無異動」）、以及所有「需人工確認」項目。
|
||||
|
||||
## 第 4 步：草稿品質檢查
|
||||
|
||||
實際寫入 Gitea 前，主 agent 必須檢查所有議題草稿：
|
||||
|
||||
- 內容以繁體中文為主、英文為輔，無亂碼或破損文字。
|
||||
- 每個要同步的議題都有對應草稿；正文的 TODO 變更（新增／勾稽）與留言草稿的敘述一致。
|
||||
- 標籤異動只用到該 repo 既有標籤（名稱／id 對得上第 3.1 盤點結果），未擅自新建標籤。
|
||||
- 「已完成」的勾稽都有工作目錄檔案的依據；無依據者標為未完成或「需人工確認」，未被誤判為完成。
|
||||
- 有問題先修正草稿並重新檢查，通過後才進入下一步。
|
||||
|
||||
## 第 5 步：詢問使用者要如何執行（AskUserQuestion）
|
||||
|
||||
草稿通過檢查後，主 agent 用 AskUserQuestion 讓使用者確認要如何對 Gitea 執行寫入，至少提供：
|
||||
|
||||
1. 全部執行：追加／勾稽 TODO 到議題正文、套用標籤異動、對有異動的議題留言。
|
||||
2. 只更新議題（正文＋標籤），先不留言。
|
||||
3. 只產生草稿、先不動 Gitea：僅輸出本機草稿供檢視。
|
||||
4. 逐議題確認：每處理完一個議題就回報，待使用者確認後再做下一個。
|
||||
5. 其他（由使用者輸入自訂方式）。
|
||||
|
||||
未獲確認前不得對 Gitea 做任何寫入。
|
||||
|
||||
## 第 6 步：套用到 Gitea
|
||||
|
||||
依使用者選擇，對最終清單的每個議題執行（主 agent 執行，非 subagent）：
|
||||
|
||||
- **更新正文（TODO 追加＋勾稽）**：以草稿中「追加後的完整正文」更新議題 body。
|
||||
- tea：對應的 issue 編輯指令；API：`PATCH {base}/repos/{owner}/{repo}/issues/{index}`，body `{"body":"<新正文>"}`。
|
||||
- 更新前先重新讀一次議題正文，若與 subagent 讀到的版本已不同（他人期間有改動），停下該議題並回報，避免覆蓋他人變更。
|
||||
- **標籤異動**：套用建議的新增／移除。
|
||||
- tea：`tea labels`／issue 編輯對應指令；API：`POST`/`DELETE {base}/repos/{owner}/{repo}/issues/{index}/labels`（用既有 label id）。
|
||||
- **留言**：對有 TODO 異動的議題張貼留言草稿。
|
||||
- tea：`tea comment --repo <owner>/<repo> --login <name> <index> "<留言內容>"`；API：`POST {base}/repos/{owner}/{repo}/issues/{index}/comments`，body `{"body":"<留言內容>"}`。
|
||||
- 無異動的議題不留言。
|
||||
- 若選「逐議題確認」，每處理完一個就回報並等待確認再繼續。
|
||||
|
||||
## 第 7 步：回報與清理
|
||||
|
||||
- 回報：輸入是專案或議題、（若為專案）關聯議題數與依標籤篩選後的最終清單、每個議題新增了哪些 TODO、勾稽為完成的 TODO（附實作位置）、標籤異動、是否留言，以及所有「需人工確認」或「Gitea 版本不支援」項目。
|
||||
- 草稿（`.docs/doc-issues-sync/`）預設保留供檢視；使用者要求清理時才刪除本次產生的檔案，不得刪除 `.docs/` 內其他既有檔案。
|
||||
|
||||
## 重要限制
|
||||
|
||||
- 修改議題正文、變更標籤、留言都是對外且不易復原的動作，**必須先經第 5 步使用者確認**；未確認前只產生本機草稿。
|
||||
- 「TODO 是否完成」「該補哪些 TODO」「該掛哪些標籤」一律以**工作目錄下的檔案**為依據；無法可靠判斷就標「需人工確認」，不得臆測或編造需求未涵蓋的內容。
|
||||
- subagent 與各步驟只讀檔案與議題、只寫 `.docs/` 草稿，**不得修改任何工作目錄原始碼**。
|
||||
- 標籤只從既有標籤挑選，不自行新建（除非使用者要求）。
|
||||
- 不要依賴 `jq`（未安裝）；JSON 解析改用 tea 結構化輸出或由 subagent 解析。
|
||||
- 留言與草稿不得洩漏個資（PII）；若議題內容含個資，於草稿與留言中僅保留必要資訊或去識別化。
|
||||
- 文件、留言與草稿以繁體中文為主、英文為輔；API 名稱、型別名稱與程式碼片段可保留英文。
|
||||
Reference in New Issue
Block a user