jiantw83andClaude Sonnet 5
1030f9d403
依 todo.md 執行的規範治理專案：新增 spec-preflight 等 14 個共用規範（含 conventional-commit/pull-request/git-push/issue-read/todo-list/ask-user/ subagent/no-scratch-files/skill-invocation/script-path/action-scaffold/ node-src-layout/plugin-cli/model），擴充 spec-git-safety 與 spec-gitea（token 優先序、機密遮蔽、Wiki 頁名轉義規則）；新增可執行 skill `models`（模型能力 查詢與標籤）與 `todo`（依指定模型產生/附加 todo.md）；新增 plugin.meta.json 單一事實來源與 gen-plugin-files.mjs 樣板產生器，統一四個 repo 的 manifest／ README／AGENTS.md 並移除寫死的本機使用者路徑；新增 shared/scripts/lib 的 log／機密遮蔽三語言參考實作。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
48 lines
3.6 KiB
Markdown
48 lines
3.6 KiB
Markdown
---
|
||
name: spec-issue-read
|
||
description: JSC plugins 共用「Gitea 議題讀取與需求彙整規範」：讀取議題必須含描述、所有留言與所有附件內容（不得只讀描述）、留言與附件分頁完整讀取（分頁規則見 spec-gitea，不重複細節）、彙整議題需求時不得臆測缺漏的部分，須詢問使用者或如實標記「未提及」。當其他 skill 內文引用 spec-issue-read 或 /jsc-shared:spec-issue-read、或讀取 Gitea 議題／彙整議題需求時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。
|
||
---
|
||
|
||
# spec-issue-read — 共用 Gitea 議題讀取與需求彙整規範
|
||
|
||
所有 JSC skills 讀取 Gitea 議題並據以彙整需求時，一律遵守以下規範。
|
||
|
||
## 議題必須完整讀取，不能只讀描述
|
||
|
||
讀取任一議題（含專案看板底下展開的議題）時，至少必須取得：
|
||
|
||
| 欄位 | 說明 |
|
||
| --- | --- |
|
||
| `title`／`body`／`state` | 議題標題、描述、狀態 |
|
||
| `labels`／`milestone`／`assignees` | 既有分類與指派資訊 |
|
||
| **所有留言（comments）** | 不得只取第一頁或前幾則，見下節分頁規則 |
|
||
| **所有附件（attachments/assets）** | 議題本身與**每一則留言**各自的附件都要讀，見下節附件讀取 |
|
||
|
||
- `tea`：`tea issues <index> --repo <owner>/<repo> --comments` 取得本文與留言；`tea` 目前沒有附件指令，附件一律改走 API。
|
||
- `api`：`GET {base}/issues/{index}` 取得本文，`GET {base}/issues/{index}/comments` 取得留言。
|
||
- 留言中若有需求補充、變更或取消，必須納入需求彙整，並以**最新留言**為準；只讀描述、略過留言即視為讀取不完整，不得據此彙整需求或判定 TODO 完成度。
|
||
|
||
## 附件讀取
|
||
|
||
- 附件清單一律走 API（`tea` 無此功能）：
|
||
- 議題附件：`GET {base}/repos/{owner}/{repo}/issues/{index}/assets`
|
||
- 留言附件：`GET {base}/repos/{owner}/{repo}/issues/comments/{id}/assets`
|
||
- 取得每個附件的檔名、類型與下載 URL。
|
||
- 依附件類型決定讀取方式：
|
||
|
||
| 附件類型 | 讀取方式 |
|
||
| --- | --- |
|
||
| 文字類（Markdown、純文字、CSV、JSON 等） | 以 `curl` 直接取得內容到對話中分析，不落地 |
|
||
| 圖片或其他二進位 | 依絕對準則的例外，唯讀暫存下載到系統暫存目錄讀取（例如圖片以視覺方式讀取內容），讀取完畢後立即刪除暫存檔 |
|
||
| 無法讀取的格式，或僅有 `tea` 而無 token 可下載附件 | 列出附件檔名與 URL 並標註「附件無法讀取，需人工確認」，不得忽略附件的存在，也不得臆測其內容 |
|
||
|
||
## 分頁必須完整讀取
|
||
|
||
留言與附件清單都是分頁 API，完整分頁規則（持續累加 `page` 直到回傳筆數小於 `limit` 或回空陣列為止，不可只取第一頁）一律依 `/jsc-shared:spec-gitea` 的「API 呼叫慣例」執行，本規範不重複細節。
|
||
|
||
## 彙整需求時不得臆測
|
||
|
||
- 把議題描述與所有留言（含附件內容）整理成需求彙整（目標、驗收條件、限制條件）時，**只做歸納，不編造來源未提及的需求**。
|
||
- 來源之間說法不一致、範圍不明、驗收條件缺漏、附件無法讀取造成的資訊缺口等，一律先詢問使用者澄清；來不及或無法立即詢問時，如實在彙整內容中標記「未提及」或「需人工確認」，不得自行補完、猜測或以常見做法代填。
|
||
- 議題描述既有的 Markdown checklist（`- [ ]`／`- [x]`）視為既有 TODO 的一部分納入盤點；已勾選項目視為已完成，不重做，也不得因臆測而改判其完成狀態。
|