refactor(doc): 接上 shared 共用規範，去除重抄段落並修正時區/機密遮蔽引用
依 todo.md 執行的規範治理專案：worklog／funcs／issues-analyze／ issues-analyze-to-file／issues-sync／notifications／docker 七個 skill 改為 引用 shared 新增的 14 個共用 spec（token 優先序、issue 讀取、TODO list、 ask-user、subagent、no-scratch-files、skill-invocation、script-path 等）， 不再重抄內容；wiki_api.py 改用 zoneinfo 而非硬編 +8 offset，並補上與 shared/scripts/lib/redact-patterns.json 的對應註記；worklog 的 --tune 改為 呼叫 /jsc-shared:models --task summary。 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Claude Sonnet 5
@@ -7,18 +7,16 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
|
||||
|
||||
你要先做工具可用性檢查並選擇工具；第二步詢問使用者要讀取哪些來源：專案編號、議題編號、檔案文件，至少選一種，接著讀取選定來源，並在產生保存議題前完整釐清需求——只要有任何不清楚的部分都必須詢問使用者，絕對不可以幻想——確認清楚後才彙整成保存議題內容。第三步必須把上個步驟產生的議題內容拆分成多個小功能議題，並為每個小功能議題產生標題、描述、阻擋關閉規則與依複雜度評估的到期日；若形成子母議題（保存議題為母、小功能議題為子），母議題必須所有子議題都關閉後才可關閉（優先以 issue dependency 阻擋）；分析完成後，若議題屬於專案看板且欄位可對應進度語意（例如分析中／待處理／進行中／待測試／已完成），把議題移到「待處理」欄位。第四步必須將小功能議題依到期日與相依關係排序，並把排序結果留言到保存議題；**本 skill 不實作程式碼**——不修改原始碼、不 commit、不 push、不開 PR，後續實作交由 `/jsc-code:issues` 或使用者另行處理。所有中間成果都不准落地成草稿檔，必須一律使用 `tea` 或 Gitea API 保存到議題描述或留言。
|
||||
|
||||
## 共用規範（shared plugin，必要前置）
|
||||
## 共用規範（必要前置）
|
||||
|
||||
執行本 skill 前，先以 Skill 工具載入下列共用規範並全程遵守；**任一載入不到（shared plugin 未安裝）時，先詢問使用者是否安裝 shared plugin（`https://gitea.jsc.idv.tw/plugins/shared.git`），使用者不安裝則直接中斷本 skill**，不得只憑下方一行摘要繼續執行：
|
||||
|
||||
- `/jsc-shared:spec-output`：繁體中文為主英文為輔、UTF-8（不含 BOM）無亂碼、表格／Mermaid 呈現、個資（PII）去識別化。
|
||||
- `/jsc-shared:spec-execution`：不臆測／需人工確認、已知資訊跳過詢問。
|
||||
- `/jsc-shared:spec-gitea`：tea／API 工具選擇與檢查、`GITEA_TOKEN` 機密保護、不依賴 `jq`、API 分頁完整讀取。
|
||||
- `/jsc-shared:spec-project-board`：看板欄位語意對應、GET 探測（404／501 不支援）、不往回移、不得新建欄位。
|
||||
先載入 `/jsc-shared:spec-preflight` 並依其流程處理；載入不到即代表 shared plugin 未安裝，
|
||||
依該 spec 詢問使用者是否安裝 `https://gitea.jsc.idv.tw/plugins/shared.git`，不安裝則中斷本 skill。
|
||||
本 skill 需要的規範：`spec-output`、`spec-execution`、`spec-gitea`、`spec-issue-read`、`spec-no-scratch-files`、`spec-subagent`、`spec-todo-list`、`spec-project-board`
|
||||
|
||||
## 絕對準則（不可違反）
|
||||
|
||||
- **全程不得在磁碟落地任何檔案**：不建立 `.docs/`、不寫草稿檔、不寫暫存檔、不用檔案傳遞中間結果。所有中間成果（需求彙整、保存議題內容、小功能拆分、到期日排序、交付摘要）一律留在**對話內容**與 **subagent 的回傳值**，並透過 `tea` 或 Gitea API **保存到議題描述或留言**。例外只有一個：為了讀取議題附件（圖片等二進位檔）而**唯讀暫存下載到系統暫存目錄**，讀取完畢後立即刪除，不得下載到工作目錄或任何 repo 內、不得用暫存檔傳遞其他中間成果。除此之外不產生任何本機檔案。
|
||||
- **不落地**：依 `/jsc-shared:spec-no-scratch-files` 執行——全程不建立任何草稿檔／暫存檔，所有中間成果（需求彙整、保存議題內容、小功能拆分、到期日排序、交付摘要）一律留在對話內容、議題描述或留言；唯一例外是讀取議題附件時的唯讀暫存，讀取完畢立即刪除。
|
||||
- **派 subagent（例如研究 target repositories 程式碼以補充議題描述）**：依 `/jsc-shared:spec-subagent` 執行——一個明確目標派一個 subagent、只讀不寫、回傳結構化結果供本 skill 判讀後再寫回議題，不得直接寫外部系統。
|
||||
|
||||
## 前置：輸入與工具
|
||||
|
||||
@@ -28,19 +26,14 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
|
||||
- **檔案文件**：本機文件路徑，可多筆；支援 Markdown、純文字與其他可直接讀取的需求文件。
|
||||
- **保存目標**：合併整理後必須在指定專案建立一張議題保存；若輸入來源未包含可作為保存目標的專案編號，必須詢問使用者提供專案編號，不得自行臆測。
|
||||
- **repositories 位置**：可另外指定本機含多個專案的資料夾；若未指定，程式碼分析參考（僅供研究、補充議題描述，不修改）以來源議題所在 repo、保存目標 repo 或使用者指定 repo 為準。
|
||||
- **工具選擇**：依 `/jsc-shared:spec-gitea` 的工具選擇流程（檢查 `tea`／`tea login list`／`GITEA_TOKEN` 後詢問使用者用 `tea` 或 `api`；已明確指定工具時才可跳過詢問；不依賴 `jq`，JSON 改用 tea 結構化輸出或交給 subagent 解析）。
|
||||
- **議題必須連同留言與附件一起讀取**：處理任何議題（含專案底下展開的議題）時，除了 `title`／`body` 等欄位，必須一併讀取**所有留言（comments）**與**所有附件（attachments/assets，含議題本身與各留言的附件）**，其內容都是需求分析的依據：
|
||||
- 附件清單：`tea` 目前沒有附件指令，一律走 API — 議題附件 `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 並標註「附件無法讀取，需人工確認」，不得忽略附件的存在，也不得臆測其內容。
|
||||
- **禁止草稿落地**：所有流程都不准建立 `.docs/` 或其他本機草稿檔；需求整理、小功能拆分、排序、進度與交付資訊一律使用 `tea` 或 Gitea API 保存到對應議題描述或留言。
|
||||
- **TODO list**：所有建立或更新的議題描述最後都必須加上依該描述內容推導出的 `## TODO` 區塊，使用 Markdown checklist（`- [ ] ...`）；TODO 必須可執行、可驗收，且不得加入描述未提及或無法合理推得的工作。
|
||||
- **工具選擇**：依 `/jsc-shared:spec-gitea` 執行（見第 1 步）。
|
||||
- **議題讀取**：依 `/jsc-shared:spec-issue-read` 執行——連同所有留言與附件一起讀取，附件依類型分流讀取，無法讀取的格式標註「附件無法讀取，需人工確認」。
|
||||
- **TODO list**：依 `/jsc-shared:spec-todo-list` 執行——所有建立或更新的議題描述最後都必須有 `## TODO` 區塊。
|
||||
- **議題描述流程圖**：依 `/jsc-shared:spec-output` — 產生保存議題或小功能議題的描述時，有助理解就加入 Mermaid 流程圖（需求流程、狀態轉移、相依／阻擋關係），忠實反映需求與拆分結果、不得杜撰。
|
||||
|
||||
## 第 1 步：工具可用性檢查與使用方式選擇
|
||||
|
||||
依 `/jsc-shared:spec-gitea` 的工具選擇流程執行：檢查 `tea`（`command -v tea`、`tea login list`，失敗記錄原因不中止）與 `GITEA_TOKEN`（只輸出「已設定／未設定」）→ 詢問使用者要用 `tea` 或 `api`（除非使用者已明確指定，不得自行決定；選 `tea` 後續仍需確認來源 host 有對應 login）→ 兩種方式都不可用則停止並回報缺少 `tea login` 或 `GITEA_TOKEN`（不要要求使用者把 token 貼進對話）。
|
||||
依 `/jsc-shared:spec-gitea` 執行工具可用性檢查與使用方式選擇。
|
||||
|
||||
## 第 2 步：選擇讀取來源、讀取內容並保存議題內容
|
||||
|
||||
@@ -83,8 +76,8 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
|
||||
- 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`。
|
||||
- 專案：讀取 project 描述、欄位／卡片、project metadata，並只讀取該專案下**開啟中的議題**（若 API 有分頁必須完整分頁讀取；每筆議題都依 `/jsc-shared:spec-issue-read` 完整讀取）。若 Gitea 版本不支援 project API 或無法由 project 取得開啟中的 issue 清單，標註「此 Gitea 版本不支援 project API，需人工處理」，並請使用者改提供議題編號或可匯出的 project 文件。
|
||||
- 議題：對每一筆 issue，依 `/jsc-shared:spec-issue-read` 讀取完整內容（`title`、`body`、`state`、`labels`、`milestone`、`assignees`、所有 comments、議題與各留言的所有附件）；若 Gitea 版本支援，另讀該 issue 所屬 `project`。
|
||||
- 檔案文件：讀取文件全文；若格式無法直接讀取，標註需人工轉換或提供純文字／Markdown。
|
||||
6. 同時盤點該 repo 既有的分類資源，供後續階段沿用：
|
||||
- 標籤：`GET {base}/labels`（tea：`tea labels list`）
|
||||
@@ -100,7 +93,7 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
|
||||
- 完整需求描述：整合專案、議題（含留言與附件內容）、檔案文件的內容，去除重複、補齊上下文，形成單一連貫的需求敘述。
|
||||
- 驗收條件／預期結果：能從來源內容推得的，逐條列出；不能確定的標註「需人工確認」。
|
||||
- 保存議題分類：labels／milestone／project 掛載方式。
|
||||
- `## TODO`：根據保存議題描述內容產生 Markdown checklist，放在描述最後。
|
||||
- `## TODO`：依 `/jsc-shared:spec-todo-list` 產生 Markdown checklist，放在描述最後。
|
||||
|
||||
需求彙整只做整理與歸納，不得編造來源內容未提及的需求；無法確定處必須依上方「需求釐清」關卡先詢問使用者，只有使用者明確指示保留的項目才可標註「需人工確認」後寫入。
|
||||
|
||||
@@ -109,7 +102,7 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
|
||||
將第 2 步保存到議題的內容拆分成多個小功能議題，使用 `tea` 或 Gitea API 建立／更新小功能議題或將小功能清單留言到保存議題；不得寫入本機草稿檔。每個小功能議題至少包含：
|
||||
|
||||
- 標題：能清楚表示單一小功能交付範圍。
|
||||
- 描述：描述內容必須先詢問使用者想要包含哪些段落或資訊，至少提供可選項，例如需求背景、功能範圍、驗收條件、技術提示、測試方式、相依關係、風險與備註；依使用者選擇組成描述，不得自行固定格式。每個小功能議題建立或更新前，都必須逐一詢問使用者該議題描述是否有補充內容；使用者提供補充時，必須整合到該小功能議題描述中，若使用者明確表示沒有補充才可繼續建立或更新。描述最後必須加入 `## TODO` 區塊，根據該小功能描述內容產生 Markdown checklist。
|
||||
- 描述：描述內容必須先詢問使用者想要包含哪些段落或資訊，至少提供可選項，例如需求背景、功能範圍、驗收條件、技術提示、測試方式、相依關係、風險與備註；依使用者選擇組成描述，不得自行固定格式。每個小功能議題建立或更新前，都必須逐一詢問使用者該議題描述是否有補充內容；使用者提供補充時，必須整合到該小功能議題描述中，若使用者明確表示沒有補充才可繼續建立或更新。描述最後必須依 `/jsc-shared:spec-todo-list` 加入 `## TODO` 區塊。
|
||||
- 阻擋關閉：小功能議題建立後必須以可追溯方式阻擋其被直接關閉，直到驗收條件完成。可用方式包含加上既有 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 並回報需人工設定。
|
||||
@@ -117,8 +110,8 @@ description: 讀取使用者選擇的一或多種來源（專案編號、議題
|
||||
|
||||
**子母議題關閉規則**：若本次拆分實際建立了子母關係（保存議題為**母議題**、拆出的小功能議題為**子議題**），母議題必須在**所有子議題都關閉後才可關閉**，建立子議題時就要把這個限制落實：
|
||||
|
||||
- 優先用 Gitea issue dependency 實作：把母議題設為 blocked by **每一個**子議題（API `POST {base}/issues/{母議題 index}/dependencies`，body 帶子議題資訊；先以 GET 探測該實例是否啟用 dependency 功能，404／501 視為不支援），讓 Gitea 在子議題尚未全部關閉前直接阻止關閉母議題。
|
||||
- dependency 不支援或未啟用時：在母議題描述加入「子議題清單」markdown 任務清單（每項連結一個子議題，例如 `- [ ] #<index> <子議題標題>`）與「關閉前檢查：所有子議題皆已關閉」字樣，並在回報中標註此限制需人工遵守；不得對未確認存在的端點做寫入。
|
||||
- 優先用 Gitea issue dependency 實作：依 `/jsc-shared:spec-project-board` 的介面探測慣例（先 GET 探測、404／501 視為不支援、不寫入未確認端點）確認該實例是否啟用 dependency 功能後，把母議題設為 blocked by **每一個**子議題（API `POST {base}/issues/{母議題 index}/dependencies`，body 帶子議題資訊），讓 Gitea 在子議題尚未全部關閉前直接阻止關閉母議題。
|
||||
- dependency 不支援或未啟用時：在母議題描述加入「子議題清單」markdown 任務清單（每項連結一個子議題，例如 `- [ ] #<index> <子議題標題>`）與「關閉前檢查：所有子議題皆已關閉」字樣，並在回報中標註此限制需人工遵守。
|
||||
- 後續新增或補拆子議題時，必須同步補上對應的 dependency 或母議題子議題清單項目，不得遺漏。
|
||||
|
||||
決定要對照的 target repositories：使用者指定位置底下的所有專案、來源議題所在 repo，或使用者指定 repo。可研究相關專案程式碼以補充小功能議題描述，但所有分析結果必須直接保存到小功能議題描述或留言，不得建立本機草稿檔。
|
||||
|
||||
Reference in New Issue
Block a user