@@ -1,11 +1,15 @@
---
name : doc-issues-sync
description : 讀取一個 Gitea 專案（project）或單一議題（優先用 tea，否則用 Gitea REST API + curl + GITEA_TOKEN，不依賴 jq）；若給的是專案就讀取與此專案關聯的所有 議題， 所有對 Gitea 的寫入（改 正文／改 標籤／留言）先產生草稿並 經使用者確認再執行 。當使用者要同步議題進度、依專案批次更新議題 TODO、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 doc-issues-sync、issue sync、議題同步、TODO 勾稽、tea issues、Gitea 專案議題時使用此 skill。
description : 讀取一個 Gitea 專案（project）或單一議題（優先用 tea，否則用 Gitea REST API + curl + GITEA_TOKEN，不依賴 jq）；若給的是專案，因 tea／Gitea API 目前無法直接查詢專案，就先取得該 repo 底下所有開啟中的議題、再過濾掉與此專案無關的 議題； 全程不落地任何檔案：所有中間成果一律留在對話／subagent 回傳內容，最終只透過 tea 或 Gitea API 寫回議題 正文／標籤／留言，且寫入前先 經使用者確認。當使用者要同步議題進度、依專案批次更新議題 TODO、依程式碼勾稽議題完成度、更新議題標籤與進度留言，或提到 doc-issues-sync、issue sync、議題同步、TODO 勾稽、tea issues、Gitea 專案議題時使用此 skill。
---
# 依工作目錄同步 Gitea 專案／議題的 TODO 進度與標籤
你要讀取使用者提供的一個 Gitea **專案（project） ** ，取得要同步的議題清單，然後一個議題派一個 subagent，**以目前工作目錄下的所有檔案為依據**，勾稽並更新每個議題的 TODO（markdown 任務清單）與標籤，最後把 TODO 的異動整理成留言。**修改議題正文、變更議題標籤、留言都是對外且不易復原的動作，subagent 只產生草稿 ，實際寫入 Gitea 前必須先讓使用者確認**。請依下列階段依序完成。
你要讀取使用者提供的一個 Gitea **專案（project） ** ，取得要同步的議題清單，然後一個議題派一個 subagent，**以目前工作目錄下的所有檔案為依據**，勾稽並更新每個議題的 TODO（markdown 任務清單）與標籤，最後把 TODO 的異動整理成留言。**修改議題正文、變更議題標籤、留言都是對外且不易復原的動作，subagent 只回傳同步計畫（不落地任何檔案） ，實際寫入 Gitea 前必須先讓使用者確認**。請依下列階段依序完成。
## 絕對準則（不可違反）
- **全程不得在磁碟落地任何檔案**：不建立 `.docs/` 、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（議題清單、需求分析、追加後的正文、標籤異動、勾稽結果、留言內容）一律留在**對話內容**與 **subagent 的回傳值**裡。最終產物只透過 `tea` 或 Gitea API **寫回議題正文／標籤／留言 ** ，除此之外不產生任何本機檔案。
## 前置：輸入與工具
@@ -16,7 +20,7 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
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/`
- **議題描述流程圖**：若要補進議題正文或進度留言的內容有助於理解（例如需求流程、TODO 之間的先後／相依），盡量加入 **Mermaid 流程圖 ** （ ` ` ` `mermaid ` flowchart／ ， 。
## 第 0 步：解析輸入、判斷專案或議題、準備工具
@@ -24,16 +28,17 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
- 議題 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（ `https://<host>/api/v1` ）。
3. 建立 `.docs/doc-issues-sync/` （若不存在） 。
4. **找不到就詢問使用者（AskUserQuestion） ** ：若無法從輸入判斷是專案還是議題、或依輸入查不到對應的專案／議題（例如 API 回 404、專案 id 不存在、repo 拼錯），必須用 AskUserQuestion 請使用者補齊或更正（host／
3. **找不到就詢問使用者（AskUserQuestion） ** ：若無法從輸入判斷是專案還是議題、或依輸入查不到對應的專案／議題（例如 API 回 404、專案 id 不存在、repo 拼錯），必須用 AskUserQuestion 請使用者補齊或更正（host／ 。
## 第 1 步：取得要同步的議題清單
- **若輸入是議題**：清單就是這一筆議題，**跳過本步的專案展開**，直接進入第 2 步。
- **若輸入是專案**： 讀取與此專案關聯的所有議題。
- tea：優先用 tea 對應指令列出專案關聯議題；若該版本 tea 無法列專案議題，改用 API。
- API：以 Gitea 的 project／ ` owner/ repo` 、 `index` 、 `title` 、 ` labels`
- 若該 Gitea 版本不支援 project API 或查不到關聯議題，用 AskUserQuestion 告知並請使用者改提供議題清單（或改給單一議題 URL），不要自行臆測要同步哪些議題
- **若輸入是專案**： ** `tea` 與 Gitea API 目前都無法直接查詢專案掛載的議題**，因此改用「先撈全部、再過濾」：
1. 先取得該 `owner/repo` 底下**所有開啟中（open）的議題**：
- tea： `tea issues list --repo < owner>/< repo> --login <name> --state open` （必要時加 `--fields index,title, labels` 等 ）。
- API： `GET {base}/repos/{owner}/{repo}/issues?state=open&type=issues` （注意分頁，逐頁取完） 。
2. **過濾掉與此專案無關的議題 ** ，只保留屬於目標專案的議題：依每個議題可取得的專案關聯資訊（issue 物件上的 project 欄位、或該議題所屬 project id／名稱）比對目標專案；比對得上才留下。彙整成議題清單（每筆記下 `owner/repo` 、`index` 、`title` 、`labels` ）。
3. 若逐議題都**無法可靠判斷是否屬於此專案**（tea／API 完全取不到議題的專案關聯），用 AskUserQuestion 告知此限制，請使用者選擇要如何處理（例如：把該 repo 全部 open 議題都視為要同步、由使用者提供屬於此專案的議題清單／編號、或改給單一議題 URL），不要自行臆測。
## 第 2 步：依標籤分組並詢問要同步哪些（AskUserQuestion）
@@ -44,38 +49,38 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
- 標籤數量超過 AskUserQuestion 選項上限（4）時，改在訊息中列出全部標籤與各自議題數，請使用者回覆要同步哪些（可用「其他」自訂輸入）。
4. 依選取的標籤過濾清單：保留**帶有任一選取標籤**的議題，作為後續要同步的最終清單。未被選取標籤涵蓋的議題不同步。
## 第 3 步：逐議題派 subagent 產生同步草稿 （每個議題一個 subagent）
## 第 3 步：逐議題派 subagent 產生同步計畫 （每個議題一個 subagent）
對最終清單中的**每一個議題各派一個 subagent**。subagent **以目前工作目錄下的所有檔案為依據 ** ，只讀檔案與議題、**只在 `.docs/doc-issues-sync/` 底下寫草稿 **，
對最終清單中的**每一個議題各派一個 subagent**。subagent **以目前工作目錄下的所有檔案為依據 ** ，只讀檔案與議題、**把結果以結構化內容回傳給主 agent，不得在磁碟寫任何檔案 **、 **不得修改任何工作目錄的原始碼、不得直接改議題正文／標籤、不得直接留言**。每個 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 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 異動，草稿 標明「無異動、不需留言」。
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，或**狀態變更**——由未完成改為完成），整理成一則留言內容， 回傳 標明「無異動、不需留言」。
每個 subagent 產出一份 `.docs/doc-issues-sync/issue-{owner}-{repo}-{index}.md` 草稿 （或「無異動」）、以及所有「需人工確認」項目。
每個 subagent **回傳**一份結構化同步計畫（**不落地成檔案 ** ） 內容 （或「無異動」）、以及所有「需人工確認」項目。
## 第 4 步：草稿 品質檢查
## 第 4 步：同步計畫 品質檢查
實際寫入 Gitea 前，主 agent 必須檢查所有議題草稿 ：
實際寫入 Gitea 前，主 agent 必須檢查所有 subagent 回傳的同步計畫（僅在對話中檢查，不寫檔） ：
- 內容以繁體中文為主、英文為輔，無亂碼或破損文字。
- 每個要同步的議題都有對應草稿 ；正文的 TODO 變更（新增／勾稽）與留言草稿 的敘述一致。
- 每個要同步的議題都有對應的同步計畫 ；正文的 TODO 變更（新增／勾稽）與留言內容 的敘述一致。
- 標籤異動只用到該 repo 既有標籤（名稱／id 對得上第 3.1 盤點結果），未擅自新建標籤。
- 「已完成」的勾稽都有工作目錄檔案的依據；無依據者標為未完成或「需人工確認」，未被誤判為完成。
- 有問題先修正草稿 並重新檢查，通過後才進入下一步。
- 有問題先在對話中修正同步計畫 並重新檢查，通過後才進入下一步。
## 第 5 步：詢問使用者要如何執行（AskUserQuestion）
草稿 通過檢查後，主 agent 用 AskUserQuestion 讓使用者確認要如何對 Gitea 執行寫入，至少提供：
同步計畫 通過檢查後，主 agent 用 AskUserQuestion 讓使用者確認要如何對 Gitea 執行寫入，至少提供：
1. 全部執行：追加／勾稽 TODO 到議題正文、套用標籤異動、對有異動的議題留言。
2. 只更新議題（正文＋標籤），先不留言。
3. 只產生草稿 、先不動 Gitea：僅輸出本機草稿供檢視 。
3. 只呈現同步計畫 、先不動 Gitea：僅在對話中列出計畫供檢視（不落地檔案、不寫入議題） 。
4. 逐議題確認：每處理完一個議題就回報，待使用者確認後再做下一個。
5. 其他（由使用者輸入自訂方式）。
@@ -85,27 +90,29 @@ description: 讀取一個 Gitea 專案（project）或單一議題（優先用 t
依使用者選擇，對最終清單的每個議題執行（主 agent 執行，非 subagent）：
- **更新正文（TODO 追加＋勾稽）**：以草稿 中「追加後的完整正文」更新議題 body。
- **更新正文（TODO 追加＋勾稽）**：以同步計畫 中「追加後的完整正文」更新議題 body。
- tea：對應的 issue 編輯指令；API：`PATCH {base}/repos/{owner}/{repo}/issues/{index}` ， `{"body":"<新正文>"}` 。
- 更新前先重新讀一次議題正文，若與 subagent 讀到的版本已不同（他人期間有改動），停下該議題並回報，避免覆蓋他人變更。
- **標籤異動**：套用建議的新增／移除。
- tea： `tea labels` ／ ： `POST` /`DELETE {base}/repos/{owner}/{repo}/issues/{index}/labels` （用既有 label id）。
- **留言**：對有 TODO 異動的議題張貼留言草稿 。
- **留言**：對有 TODO 異動的議題張貼留言。
- tea： `tea comment --repo <owner>/<repo> --login <name> <index> "<留言內容>"` ； ： `POST {base}/repos/{owner}/{repo}/issues/{index}/comments` ， `{"body":"<留言內容>"}` 。
- 無異動的議題不留言。
- 若需要把 API body 帶入 `curl` ，用管線／heredoc／變數帶入，**不要為此在磁碟落地暫存檔**。
- 若選「逐議題確認」，每處理完一個就回報並等待確認再繼續。
## 第 7 步：回報與清理
## 第 7 步：回報
- 回報：輸入是專案或議題、（若為專案）關聯 議題數與依標籤篩選後的最終清單、每個議題新增了哪些 TODO、勾稽為完成的 TODO（附實作位置）、標籤異動、是否留言，以及所有「需人工確認」或「Gitea 版本不支援 」項目。
- 草稿（ `.docs/doc-issues-sync/` ）預設保留供檢視；使用者要求清理時才刪除本次產生的檔案，不得刪除 `.docs/` 內其他既有檔案 。
- 回報：輸入是專案或議題、（若為專案）該 repo open 議題數／過濾後屬於此專案的 議題數與依標籤篩選後的最終清單、每個議題新增了哪些 TODO、勾稽為完成的 TODO（附實作位置）、標籤異動、是否留言，以及所有「需人工確認」或「無法判斷是否屬於此專案 」項目。
- 因全程不落地檔案，**沒有本機草稿需要清理**；成果都在對話與已寫回的議題正文／標籤／留言中 。
## 重要限制
- 修改 議題正文、變更 標籤、 留言都是對外且不易復原的動作，**必須先經第 5 步使用者確認**；未確認前只產生本機草稿 。
- **全程不得在磁碟落地任何檔案**（見上方「絕對準則」）：中間成果只留在對話與 subagent 回傳值，最終只寫回 議題正文／ ／
- 修改議題正文、變更標籤、留言都是對外且不易復原的動作，**必須先經第 5 步使用者確認**；未確認前不寫入 Gitea，成果只留在對話中。
- 「TODO 是否完成」「該補哪些 TODO」「該掛哪些標籤」一律以**工作目錄下的檔案**為依據；無法可靠判斷就標「需人工確認」，不得臆測或編造需求未涵蓋的內容。
- subagent 與各步驟只讀檔案與議題、只寫 `.docs/` 草稿，** 不得修改任何工作目錄原始碼**。
- subagent 與各步驟只讀檔案與議題、只回傳結構化內容，**不得在磁碟寫任何檔案、 不得修改任何工作目錄原始碼**。
- 標籤只從既有標籤挑選，不自行新建（除非使用者要求）。
- 不要依賴 `jq` （未安裝）；JSON 解析改用 tea 結構化輸出或由 subagent 解析。
- 留言與草稿 不得洩漏個資（PII）；若議題內容含個資，於草稿 與留言中僅保留必要資訊或去識別化。
- 文件、留言與草稿 以繁體中文為主、英文為輔；API 名稱、型別名稱與程式碼片段可保留英文。
- 留言與回傳內容 不得洩漏個資（PII）；若議題內容含個資，於回傳內容 與留言中僅保留必要資訊或去識別化。
- 回傳內容與留言 以繁體中文為主、英文為輔；API 名稱、型別名稱與程式碼片段可保留英文。
