Files

T

JefferyandClaude Opus 5 db492e6ba7 refactor(plugin 命名空間): plugin 更名 jsc-generic、hooks 只註冊自己擁有的 role

- 五份 manifest 的 name 由 jsc 改為 jsc-generic
- hooks/hooks.json 由合併超集改為只註冊 SessionStart（role_load）與 Stop（role_capture）：worklog 的 hook 交還 jsc-doc
- hook 腳本搜尋路徑改指 jsc-generic
- role skill 更新 hooks 說明：改名後各 plugin 名稱獨立、互不覆蓋，不再需要三份同步；並註明不可再把別的 plugin 的 hook 寫進自己的 hooks.json
- skill 名稱不變（role、spec-*），指令引用改為 /jsc-generic: 前綴
- 版號 0.0.8 → 0.0.9

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-07-28 17:07:14 +08:00

4.1 KiB

Raw Blame History

name, description

name	description
spec-gitea	JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API + GITEA_TOKEN 的工具選擇與可用性檢查、token 機密保護（不 echo、遮蔽、不落地）、不依賴 jq、API 呼叫慣例（分頁完整讀取、UTF-8 JSON body、實際換行）、gitea 主機決定順序。當其他 skill 內文引用 spec-gitea 或 /jsc-generic:spec-gitea、或執行任何需存取 Gitea 的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

name

description

spec-gitea

JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API + GITEA_TOKEN 的工具選擇與可用性檢查、token 機密保護（不 echo、遮蔽、不落地）、不依賴 jq、API 呼叫慣例（分頁完整讀取、UTF-8 JSON body、實際換行）、gitea 主機決定順序。當其他 skill 內文引用 spec-gitea 或 /jsc-generic:spec-gitea、或執行任何需存取 Gitea 的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。

spec-gitea — 共用 Gitea 工具規範

所有 JSC skills 存取 Gitea（議題、留言、PR、repo 清單）時，一律遵守以下規範。

工具選擇（`tea` 或 `api`）

使用者已明確選定工具（--tool 或對話中已選）時跳過詢問，只做該工具的可用性驗證。否則：

檢查 tea 是否存在：command -v tea；存在則執行 tea login list 記錄可用 login 與 host（失敗記錄原因，不中止）。
檢查 GITEA_TOKEN 是否已設定，只輸出「已設定／未設定」，不得輸出 token 內容：
```
[ -n "${GITEA_TOKEN}" ] && echo "GITEA_TOKEN 已設定" || echo "GITEA_TOKEN 未設定"
```

以表格呈現檢查結果後詢問使用者要用哪一種：

選項	可選條件	後續使用方式
`tea`	`tea` 可執行且目標 host 有對應 login	命令一律帶 `--login <name> --repo <owner>/<repo>`
`api`	`GITEA_TOKEN` 已設定	Gitea REST API + `curl`，標頭 `Authorization: token $GITEA_TOKEN`

兩種方式都不可用 → 回報缺少 tea login 或 GITEA_TOKEN 並停止；不要請使用者把 token 貼進對話。
多筆來源分屬不同 host：選 tea 須確認每個 host 都有對應 login；選 api 須同一個 token 可存取全部，否則回報權限不足並停止。

Token 機密保護（極重要）

token 一律從環境變數讀取（$GITEA_TOKEN），絕不寫死在 skill、commit、PR、議題、log 或任何輸出。
不可 echo 含 token 的指令或 URL；顯示給使用者的指令／錯誤訊息一律遮蔽 token（以 *** 取代）；檢查時只輸出「已設定／未設定」。
帶 token 的 URL（clone／push）用變數帶入、不可印出；token 用完即棄，不寫進 git remote 設定、不落地。clone 完成後把 origin 還原成不含 token 的乾淨 URL：
```
git -C "${dest}" remote set-url origin "https://<host>/<owner>/<repo>.git"
```
流程若可能使對話內文殘留 token（push／API 呼叫），完成後提醒使用者清除對話（Claude Code：/clear），並先確認輸出與 log 無明文 token。

不依賴 `jq`（環境未必安裝）

解析 JSON 用 tea 的結構化輸出（--output csv／--fields），或把原始 JSON 直接交給助理／subagent 解析，不要 pipe 到 jq。

API 呼叫慣例

API base：https://<host>/api/v1（repo 層：https://<host>/api/v1/repos/<owner>/<repo>）。
標頭：Authorization: token $GITEA_TOKEN。
分頁必須完整讀取：持續累加 page 直到回傳筆數 < limit（或回空陣列）為止，不可只取第一頁。
寫入（議題描述／留言／PR body）以 UTF-8 JSON 檔帶入（如 --data @body.json）；換行必須是實際換行，不可讓內容顯示字面 \n（編碼細節見 /jsc-generic:spec-output）。
API 失敗（401／403／網路錯誤）→ 回報錯誤（遮蔽 token）並停止；401／403 多半是 token 失效或權限不足。
版本相依端點（project／column／dependency 等）先以 GET 探測（404／501 視為不支援），不得對未確認存在的端點做寫入。

gitea 主機決定順序

依序決定（取第一個成功者）：

參數 --host <主機>。
環境變數 $GITEA_HOST（若有）。
目前工作目錄是 git repo 且 git remote get-url origin 指向某 gitea 主機 → 取該 host。
以上皆無 → 詢問使用者，不臆測。

主機僅取 host 部分（如 gitea.jsc.idv.tw）。

4.1 KiB Raw Blame History Unescape Escape