diff --git a/skills/spec-action-params/SKILL.md b/skills/spec-action-params/SKILL.md new file mode 100644 index 0000000..73df92e --- /dev/null +++ b/skills/spec-action-params/SKILL.md @@ -0,0 +1,31 @@ +--- +name: spec-action-params +description: JSC plugins 共用「Gitea／GitHub action 參數來源優先序」：開發 action 需要新參數時，先取 gitea/github context（composite）或 runner 注入的 GITHUB_*/GITEA_* 執行期環境變數（docker），取不到才經使用者同意新增 inputs；secrets/vars 在 action 內一律視為不可用，需要時宣告為 input 由呼叫端 workflow 傳入。當其他 skill 內文引用 spec-action-params 或 /jsc:spec-action-params、或開發 composite/docker action 需要決定參數來源時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +--- + +# spec-action-params — 共用 action 參數來源優先序 + +開發 Gitea／GitHub action（composite 或 Docker 容器 action）過程中需要新的參數值時，依下列順序處理，**前一項可取得就不往下**。 + +## 1. 平台注入的 context／環境變數 + +- **composite action**：`runs.steps` 內可直接使用 `${{ gitea.* }}`／`${{ github.* }}` context（Gitea 中兩者互為別名）。常用如 `github.repository`、`github.ref_name`、`github.server_url`、`github.token`、`github.event.*`。為同時相容 GitHub Actions，建議寫 `github.*`；`run` 腳本內可改讀同源的執行期環境變數（`$GITHUB_REPOSITORY` 等）。 +- **Docker 容器 action**：`action.yml` 內 expression 幾乎只有 `inputs`／`env` context 可用，但 runner 會把 `gitea.*`／`github.*` 同源資訊以**執行期環境變數注入容器** — Node 主程式讀 `process.env.GITHUB_*`（如 `GITHUB_REPOSITORY`、`GITHUB_SERVER_URL`、`GITHUB_REF_NAME`、`GITHUB_EVENT_PATH`；Gitea 亦提供 `GITEA_*` 同義變數），`entrypoint.sh` 內以 `$GITHUB_*` 讀取。為相容 GitHub，程式內建議讀 `GITHUB_*`。 + +## 2. 取不到 → 詢問使用者新增 `inputs` + +- 以 `AskUserQuestion` 詢問使用者是否新增對應 `input`（名稱／description／`required`／`default`），**經同意後**才於 `inputs` 宣告。 +- 取用方式：composite 於 step 內以 `${{ inputs. }}`；docker 容器內以 `INPUT_<大寫名稱>` 環境變數（Node 讀 `process.env.INPUT_`）。 +- **未經同意不得擅自更動 `inputs`／`outputs` 契約。** + +## secrets／vars 一律視為不可用（不列入優先序） + +- `${{ secrets.* }}`／`${{ vars.* }}` context 在 composite action 的 `action.yml` 內於 GitHub 為**官方明文不可用**（`inputs` 的 `default` 也不能引用）；在 Docker 容器 action 的 `runs.args`／`runs.env` 內亦不可用（官方文件僅記載 `inputs` context 可用，runner 也不會把呼叫端 secrets 自動注入容器）。Gitea act_runner 未嚴格檢查 context 可用性、行為無保證。 +- 為求兩邊相容，一律視為不可用 — 參數值本質上屬 secrets／vars 者，直接依第 2 項宣告為 `input`，回報時附上呼叫端 workflow 的傳入寫法： + + ```yaml + - uses: /@ + with: + token: ${{ secrets.MY_TOKEN }} # secrets 由呼叫端 workflow 傳入 + registry: ${{ vars.MY_REGISTRY }} # vars 亦同 + ``` diff --git a/skills/spec-doc-funcs-handoff/SKILL.md b/skills/spec-doc-funcs-handoff/SKILL.md new file mode 100644 index 0000000..352f277 --- /dev/null +++ b/skills/spec-doc-funcs-handoff/SKILL.md @@ -0,0 +1,19 @@ +--- +name: spec-doc-funcs-handoff +description: JSC plugins 共用「串接 doc-funcs 文件化流程」規範：code 類 skill（action 標準化、Dockerfile 整理）完成主要工作後，對整個目標專案完整執行 /jsc:doc-funcs（前置可用性檢查、完整流程步驟、由使用者裁示實作方式、完成後統一時間戳）。當其他 skill 內文引用 spec-doc-funcs-handoff 或 /jsc:spec-doc-funcs-handoff、或某 skill 的最後階段要完整執行 doc-funcs 補文件並重建 README 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +--- + +# spec-doc-funcs-handoff — 共用「串接 doc-funcs」流程 + +code 類 skill 完成主要工作（action 標準化、容器化、Dockerfile 整理等）後，對**整個目標專案**完整執行 `/jsc:doc-funcs` 流程，替程式碼與指令檔補文件並重建 README。 + +## 流程 + +- **前置檢查**：先確認 doc-funcs skill 可用（`/jsc:doc-funcs`）；不可用則回報並**略過本階段**，於總結標註「未文件化」。 +- 以呼叫端 skill 的目標專案根目錄為目標，執行 `doc-funcs` skill 的完整流程：判斷語言 → 掃描 function 與指令檔 → 建立 `.docs/` 草稿 → 草稿品質檢查 → 詢問使用者如何實作 → 依選擇寫回 → 保守優化 → 重建 README → 錨點檢查 → 清理草稿 → 建置／語法驗證。 +- doc-funcs 會把 `action.yml`／`Dockerfile`／`entrypoint.sh`／`docker-compose*` 等視為指令檔／CI／部署設定檔處理：補齊「用途＋更新日期同一註解區塊」與逐行註解；`steps` 引用的腳本（`*.sh`／`*.ps1` 等）逐行註解；專案內各 function 補文件註解。 +- doc-funcs 的「如何實作」詢問（全部一起／逐個／其他）由使用者於該流程內裁示，呼叫端 skill **不代為決定**。 +- 完成後依 doc-funcs 規範重建根目錄 `README.md`（含台灣時區更新時間、專案列表、功能列表、使用範例）。 +- **統一時間戳**：doc-funcs 全部完成後，以完成當下的 Asia/Taipei 時間（`yyyy/MM/dd HH:mm:ss`）回頭同步呼叫端 skill 產生的各處時間戳（橫幅 step／`entrypoint.sh`／標頭註解區塊／README），**確保各處一致**（格式見 `/jsc:spec-time-log`）。 + +> 銜接方式：在呼叫端 skill 環境中以 `/jsc:doc-funcs`（或 Skill 工具）啟動 doc-funcs 流程；若該流程需參數，沿用呼叫端 skill 的目標專案根目錄。 diff --git a/skills/spec-dockerfile/SKILL.md b/skills/spec-dockerfile/SKILL.md new file mode 100644 index 0000000..5eeaf13 --- /dev/null +++ b/skills/spec-dockerfile/SKILL.md @@ -0,0 +1,35 @@ +--- +name: spec-dockerfile +description: JSC plugins 共用「Dockerfile 六步流程」：參數處理 → 安裝套件 → 複製檔案 → 執行程序 → 縮小映像檔 → 設定入口，以多階段建置縮小最終映像、ARG 集中檔首、相依描述先 COPY 以利 layer 快取、COPY --from 逐項明列、.dockerignore、對外契約不變與自我檢查。當其他 skill 內文引用 spec-dockerfile 或 /jsc:spec-dockerfile、或需要產生／重整 Dockerfile 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +--- + +# spec-dockerfile — 共用 Dockerfile 六步流程 + +Dockerfile 一律組織為以下**固定六步流程**，並採**多階段建置**縮小最終映像。六步是骨架，每一步的實際內容必須依專案／主程式實作決定 — 不要套用與其無關的固定樣板，也不要硬塞用不到的安裝或建置指令。 + +## 六步流程 + +1. **參數處理**：可調參數集中到檔案開頭以 `ARG` 注入（base image 版本、build flag、路徑等）；`# syntax` 指示與全域 `ARG` 置於最前。 +2. **安裝套件**：先 `COPY` 相依描述檔（`package*.json`／`requirements.txt`／`go.mod go.sum`／`*.csproj` 等）再安裝，以利 layer 快取；OS 套件與語言相依在此安裝，安裝後於**同一 `RUN`** 清理快取（`apt-get clean`／`rm -rf /var/lib/apt/lists/*`、`--no-cache`）。安裝指令**二擇一寫死**（如有 lockfile 用 `npm ci`、否則 `npm install`），不得以 `A || B` fallback 串接（避免靜默吞錯、破壞可重現性）。OS 套件只在真的會用到時才安裝。 +3. **複製檔案**：`COPY` 實際需要的檔案，**明列路徑、不整包 `COPY .`**（除非重整既有 Dockerfile 需保留原行為），並配合 `.dockerignore` 排除無關檔案（至少 `.git`、`.docs`、`node_modules` 等非執行必需檔）。 +4. **執行程序**：build／compile／transpile（`npm run build`／`go build`／`dotnet publish` 等）與必要的權限設定（`chmod`）於此執行；不需 build 時此步只做權限設定。 +5. **縮小映像檔**：多階段建置，runtime 階段改用較小基底（`*-slim`／`*-alpine`／`distroless`／`scratch`，依語言對應），只 `COPY --from=` 帶入**執行所必需**的產物；**必須逐項明列路徑，不得整包搬**（整包搬等於沒有縮小）。不把 build 期 dev 相依與快取帶進最終映像；runtime 需要的 OS 執行檔於 runtime 階段安裝；同步搬移 runtime 需要的 `ENV`／`WORKDIR`／`EXPOSE`／`USER`。 +6. **設定入口**：`ENTRYPOINT`／`CMD` 置於最後，語意與需求（或原檔）一致。 + +## base image 版本 + +- **預設使用固定 major tag**（如 `node:22` 與 `node:22-slim`），不用 `latest` — 避免 base 無預警跳版導致行為漂移、跨環境不一致、無法重現除錯。 +- runtime 基底版號需與 build 基底一致，以**獨立的 runtime ARG** 帶入（如 `NODE_RUNTIME=22-slim`），不要用 `${VERSION}-slim` 組裝。tag 已是 `-alpine`／`-slim` 變體時，build 與 runtime **直接沿用同一 tag**、不再另組（沒有 `node:22-alpine-slim` 這種 tag）。使用者明確要求 `latest` 時，runtime 用 `node:slim`（**沒有 `node:latest-slim`**）。 + +## 對外契約不動（重整既有 Dockerfile 時） + +- `ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`／`VOLUME`／`HEALTHCHECK`／`USER` 的語意保持與原檔一致；只可調整位置與分層，不可改變值或刪除。 +- 凡無法可靠保證建置行為等價的重整（`ARG` 作用範圍跨 `FROM`、`COPY` 順序影響覆蓋、`RUN` 間狀態相依、單階段改多階段時 runtime 缺檔），先確認或標 `# 需人工確認` 退回最小重排。 + +## 自我檢查 + +1. `ARG` 在使用它的 `FROM` 之後有重新宣告（跨階段 `ARG` 規則）。 +2. runtime 階段 `COPY --from` 帶齊執行所需全部產物（執行檔、相依、靜態資源），容器能啟動。 +3. 對外契約（`ENTRYPOINT`／`CMD`／`EXPOSE`／`ENV`）語意一致。 +4. 路徑一致：`WORKDIR`／`COPY` 落點與入口（`entrypoint.sh`／主程式路徑）對得上。 +5. 若環境可執行，`docker build`（或至少 `--check`／語法檢查）驗證可建置；無法執行時說明原因並標註風險。 diff --git a/skills/spec-execution/SKILL.md b/skills/spec-execution/SKILL.md new file mode 100644 index 0000000..d4c43db --- /dev/null +++ b/skills/spec-execution/SKILL.md @@ -0,0 +1,26 @@ +--- +name: spec-execution +description: JSC plugins 共用「執行原則」：自動執行原則（簡短計畫後直接執行到完成、只在必要決策中斷）、不臆測／需人工確認、不擴及無關檔案（排除 node_modules/.git/.docs/bin/obj/第三方依賴）。當其他 skill 內文引用 spec-execution 或 /jsc:spec-execution、或執行任何 JSC skill 需要共用執行原則時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +--- + +# spec-execution — 共用執行原則 + +所有 JSC skills（code／doc／generic）的執行行為，一律遵守以下原則。 + +## 自動執行原則 + +- 除非使用者明確要求先確認，或遇到**不可忽略的必要決策**，否則各階段只需輸出簡短計畫／進度後**直接執行到完成**，不要為一般寫入、修復、留言、提交等反覆詢問。 +- **已知資訊一律跳過詢問**：使用者已透過參數（如 `--tool`、`--repo`）或對話提供的資訊，不得重複確認。 +- 帶 `--yes` 時更不應中斷；但各 skill 自行定義的「一定會中斷詢問的點」（破壞性高風險決策、對外不易復原的動作）**不得被 `--yes` 略過**。 +- 常見必要決策：目標不明（分支／專案／檔案缺失且無法推斷）、破壞性改寫需先確認、憑證皆失敗、無法安全解衝突、需求與現況衝突需人工裁示。 + +## 不臆測／需人工確認 + +- 任何無法可靠推論或等價推論的內容，**不編造、不硬改**：以註解或回報標註「需人工確認：...」，保留原行為，繼續處理其他項目。 +- 找不到目標（manifest、檔案、分支、專案）時**不臆測**、不逕自動工；詢問使用者或依 skill 定義的流程處理。 +- 需求彙整只做整理與歸納，不得編造來源未提及的需求。 + +## 不擴及無關檔案 + +- 只動 skill 明文宣告的目標檔案範圍；一律排除 `node_modules`／`.git`／`.docs`／`bin`／`obj`／generated 與第三方依賴。 +- 不要新增與任務無關的 helper、測試或重構。 diff --git a/skills/spec-git-safety/SKILL.md b/skills/spec-git-safety/SKILL.md new file mode 100644 index 0000000..5a8792f --- /dev/null +++ b/skills/spec-git-safety/SKILL.md @@ -0,0 +1,52 @@ +--- +name: spec-git-safety +description: JSC plugins 共用「Git 安全操作規範」：不破壞既有工作（未提交變更先提醒、絕不 reset --hard/checkout -f/clean）、git mv 保留歷史、develop → master 後備分支選擇、pull --ff-only、保守解衝突。當其他 skill 內文引用 spec-git-safety 或 /jsc:spec-git-safety、或執行任何會操作 git 工作區／分支的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +--- + +# spec-git-safety — 共用 Git 安全操作規範 + +所有 JSC skills 操作 git 工作區、分支與遠端時，一律遵守以下規範。 + +## 不破壞既有工作 + +- 改寫／覆寫／搬移檔案前，若工作區有未提交變更，先提醒使用者建議先 commit／備份。 +- **絕不** `reset --hard`／`checkout -f`／`clean`，也不刪除使用者既有原始碼、不強制丟棄未提交變更。 +- 未提交變更導致切換分支／pull／建立分支失敗時，**停止並回報**，請使用者先處理；不可強制丟棄。 +- 目錄已存在且非預期內容（如非 git repo）→ 回報並略過，**不刪除、不覆蓋**。 + +## 移動檔案優先 `git mv` + +- 搬移／改名檔案優先用 `git mv` 保留歷史。 +- 大小寫不敏感的檔案系統上需兩段式改名（先 `git mv A A.tmp` 再 `git mv A.tmp a`）。 +- 改名後必須同步更新專案內所有引用（設定檔、CI、文件連結），確保行為不變。 + +## develop → master 後備分支 + +需要基準／後備分支時（當前分支不在遠端、clone 後選工作分支、PR 目標後備），依序： + +1. `origin/develop` 存在 → 用 `develop`。 +2. 否則 `origin/master` 存在 → 用 `master`。 +3. 兩者皆無 → 回報「找不到 develop／master」並停止或略過該項，**不臆測其他分支**。 + +切換寫法： + +```bash +git switch develop 2>/dev/null || git switch -c develop --track origin/develop +``` + +- 切換後備分支屬不可忽略的狀態變更，需明確告知使用者已從原分支切換到哪個分支。 +- 批次更新既有 repo 時用 `git pull --ff-only`；無法快進（本地與遠端分歧）→ 回報需人工處理，**不**自動 merge／rebase／reset。 + +## 保守解衝突 + +pull／merge／cherry-pick 發生衝突時： + +1. 用 `git status --porcelain` 與衝突標記定位衝突檔。 +2. 讀取衝突檔脈絡，依專案現有行為與遠端變更做**最小合理整合**。 +3. 可安全解決的衝突：編輯移除衝突標記，`git add -- <檔案...>` 標記已解決，完成 merge／rebase／cherry-pick 的必要步驟。 +4. 無法安全判斷的衝突：**停止處理**，列出檔案、原因與需要使用者決策的點；不要硬選任一邊。 + +## 建立分支不覆蓋 + +- 新分支名稱需可讀且避免覆蓋既有分支；本地或遠端已存在同名分支時，換一個時間戳或短 hash，不可覆蓋。 +- 建立新分支屬不可忽略的狀態變更，需明確告知使用者原因與新分支名稱。 diff --git a/skills/spec-gitea/SKILL.md b/skills/spec-gitea/SKILL.md new file mode 100644 index 0000000..b7dea14 --- /dev/null +++ b/skills/spec-gitea/SKILL.md @@ -0,0 +1,65 @@ +--- +name: spec-gitea +description: JSC plugins 共用「Gitea 工具規範」：tea 或 Gitea REST API + GITEA_TOKEN 的工具選擇與可用性檢查、token 機密保護（不 echo、遮蔽、不落地）、不依賴 jq、API 呼叫慣例（分頁完整讀取、UTF-8 JSON body、實際換行）、gitea 主機決定順序。當其他 skill 內文引用 spec-gitea 或 /jsc:spec-gitea、或執行任何需存取 Gitea 的 JSC skill 時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +--- + +# spec-gitea — 共用 Gitea 工具規範 + +所有 JSC skills 存取 Gitea（議題、留言、PR、repo 清單）時，一律遵守以下規範。 + +## 工具選擇（`tea` 或 `api`） + +使用者已明確選定工具（`--tool` 或對話中已選）時**跳過詢問**，只做該工具的可用性驗證。否則： + +1. 檢查 `tea` 是否存在：`command -v tea`；存在則執行 `tea login list` 記錄可用 login 與 host（失敗記錄原因，不中止）。 +2. 檢查 `GITEA_TOKEN` 是否已設定，**只輸出「已設定／未設定」**，不得輸出 token 內容： + + ```bash + [ -n "${GITEA_TOKEN}" ] && echo "GITEA_TOKEN 已設定" || echo "GITEA_TOKEN 未設定" + ``` + +3. 以表格呈現檢查結果後詢問使用者要用哪一種： + + | 選項 | 可選條件 | 後續使用方式 | + | --- | --- | --- | + | `tea` | `tea` 可執行且目標 host 有對應 login | 命令一律帶 `--login --repo /` | + | `api` | `GITEA_TOKEN` 已設定 | Gitea REST API + `curl`，標頭 `Authorization: token $GITEA_TOKEN` | + +4. 兩種方式都不可用 → 回報缺少 `tea login` 或 `GITEA_TOKEN` 並停止；**不要請使用者把 token 貼進對話**。 +5. 多筆來源分屬不同 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： + + ```bash + git -C "${dest}" remote set-url origin "https:////.git" + ``` + +- 流程若可能使對話內文殘留 token（push／API 呼叫），完成後提醒使用者清除對話（Claude Code：`/clear`），並先確認輸出與 log 無明文 token。 + +## 不依賴 `jq`（環境未必安裝） + +- 解析 JSON 用 `tea` 的結構化輸出（`--output csv`／`--fields`），或把原始 JSON 直接交給助理／subagent 解析，**不要 pipe 到 `jq`**。 + +## API 呼叫慣例 + +- API base：`https:///api/v1`（repo 層：`https:///api/v1/repos//`）。 +- 標頭：`Authorization: token $GITEA_TOKEN`。 +- **分頁必須完整讀取**：持續累加 `page` 直到回傳筆數 `< limit`（或回空陣列）為止，不可只取第一頁。 +- 寫入（議題描述／留言／PR body）以 **UTF-8 JSON 檔**帶入（如 `--data @body.json`）；換行必須是**實際換行**，不可讓內容顯示字面 `\n`（編碼細節見 `/jsc:spec-output`）。 +- API 失敗（401／403／網路錯誤）→ 回報錯誤（**遮蔽 token**）並停止；401／403 多半是 token 失效或權限不足。 +- 版本相依端點（project／column／dependency 等）先以 GET 探測（404／501 視為不支援），**不得對未確認存在的端點做寫入**。 + +## gitea 主機決定順序 + +依序決定（取第一個成功者）： + +1. 參數 `--host <主機>`。 +2. 環境變數 `$GITEA_HOST`（若有）。 +3. 目前工作目錄是 git repo 且 `git remote get-url origin` 指向某 gitea 主機 → 取該 host。 +4. 以上皆無 → **詢問使用者**，不臆測。 + +主機僅取 host 部分（如 `gitea.jsc.idv.tw`）。 diff --git a/skills/spec-output/SKILL.md b/skills/spec-output/SKILL.md new file mode 100644 index 0000000..866d5d1 --- /dev/null +++ b/skills/spec-output/SKILL.md @@ -0,0 +1,37 @@ +--- +name: spec-output +description: JSC plugins 共用「輸出規範」：繁體中文（台灣用語）、UTF-8（不含 BOM）無亂碼、優先以 Markdown 表格與 Mermaid 圖呈現。當其他 skill 內文引用 spec-output 或 /jsc:spec-output、或執行任何 JSC skill 需要語言／編碼／呈現規範時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +--- + +# spec-output — 共用輸出規範 + +所有 JSC skills（code／doc／generic）面向使用者的輸出與寫入檔案，一律遵守以下規範。 + +## 語言 + +- 所有面向使用者的輸出（計畫、進度、總結、反問）與寫入外部系統的內容（議題描述／留言、commit 訊息、PR 標題與描述、README、註解）一律使用**繁體中文（台灣用語）**。 +- 僅程式碼識別字、檔名、指令（git／docker／curl 等）、API 路徑、YAML／JSON 鍵名、conventional commit 的 `type`、既有技術術語保留原文。 +- **不可**使用簡體字；敘述句不可改用英文。 + +## 編碼無亂碼 + +- 凡輸出或寫入含繁體中文、全形標點、emoji，一律 **UTF-8（不含 BOM）**，不得出現問號方框（）或錯碼。涵蓋：產生／覆寫的任何檔案、commit 訊息、PR 標題／描述、議題內容、終端訊息。 +- 實作要點： + - **寫檔**：優先用助理的檔案寫入工具（預設 UTF-8 無 BOM）。改用 shell 寫檔時，**避免 PowerShell 的 `>`／`Out-File`**（可能寫成 UTF-16 或加 BOM）；需要時用 `Set-Content -Encoding utf8NoBOM`，或在 bash 用 `printf`／heredoc。 + - **commit 訊息**：用 `git commit -m` 直接帶字串，或寫進 UTF-8 無 BOM 的檔案再 `git commit -F `；確保 `git config i18n.commitEncoding utf-8`。 + - **API body**：以 UTF-8 JSON 檔帶入（如 `--data @body.json`）；換行必須是**實際換行**，不可讓對方顯示字面 `\n`。 + - **送出前自我檢查**：產生含繁中的檔案／訊息後，回頭確認沒有亂碼或 BOM 再提交／送出。 +- 若 skill 使用特定 emoji（如等級 🔴🟠🟡🔵、裁決 🚫🔁❌✅），須確保正常顯示。 + +## 表格與圖形優先 + +- 面向使用者的輸出與寫入議題的內容（需求彙整、清單、進度回報），優先以 **Markdown 表格**與 **Mermaid 圖**（` ```mermaid ` flowchart／stateDiagram，Gitea 可直接渲染）呈現，讓使用者一眼看懂意圖。 +- 圖表必須忠實反映實際內容，**不得杜撰**未提及的流程或資料。 + +## 個資保護（PII） + +- 寫入外部系統的內容（議題、留言、PR、文件）**不得洩漏個資（PII）**；若來源內容含個資，僅保留必要資訊或去識別化。 + +## 派發 subagent 時 + +- 須把本規範一併寫入每個 subagent 的提示，確保各 subagent 回傳的內容同樣是繁體中文、無亂碼。 diff --git a/skills/spec-project-board/SKILL.md b/skills/spec-project-board/SKILL.md new file mode 100644 index 0000000..0d7d171 --- /dev/null +++ b/skills/spec-project-board/SKILL.md @@ -0,0 +1,31 @@ +--- +name: spec-project-board +description: JSC plugins 共用「Gitea 專案看板進度欄位規範」：欄位語意對應（分析中／待處理／進行中／待測試／已完成，以看板實際欄位名稱為準）、依需求與 TODO 勾稽結果建議欄位、先 GET 探測 project/column API（404/501 視為不支援、不對未確認端點寫入）、不往回移、不支援時改列建議清單請人工拖曳、不得新建欄位。當其他 skill 內文引用 spec-project-board 或 /jsc:spec-project-board、或需要調整 Gitea 議題所在看板欄位時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +--- + +# spec-project-board — 共用 Gitea 看板進度欄位規範 + +JSC skills 調整議題所在的專案看板（project board）欄位時，一律遵守以下規範。 + +## 欄位語意對應 + +- 看板欄位名稱可對應進度語意時才操作，例如「分析中」「待處理」「進行中」「待測試」「已完成」；一律以看板**實際欄位名稱**為準，語意相近即可對應，**不得假設看板一定有這五欄**。 +- 依議題狀態建議欄位的預設規則： + + | 議題狀態 | 建議欄位 | + | --- | --- | + | 需求仍不明確、TODO 明顯不足以追蹤需求而需大量補列 | 分析中 | + | 需求與 TODO 齊全，但尚無任何對應實作 | 待處理 | + | 部分 TODO 已完成（已有部分實作） | 進行中 | + | 所有 TODO 已完成，但仍有「需人工確認」項目或尚待驗證 | 待測試 | + | 所有 TODO 已完成且無需人工確認（僅在使用者確認時） | 已完成 | + +- **不往回移**：議題已在建議欄位或更後面的欄位時維持原欄位，不往回移動。 + +## 介面探測與寫入限制 + +- `tea` 目前**沒有** project 看板指令；Gitea REST 的 project／column 端點依版本而異。 +- 移動前先以 GET 探測端點是否存在（回 404／501 視為該實例不支援），**不得對未確認存在的端點做寫入**。 +- 介面可用 → 一次一個議題移動並確認回應成功。 +- 介面不支援、看板沒有可對應語意的欄位、或欄位語意對不上 → **不移動、不視為錯誤**：改在回報（或議題留言）中列出「議題 → 建議欄位」建議清單，請使用者到看板手動拖曳。 +- **不得新建欄位**；只在建議欄位確實存在於看板且語意對應明確時移動，有疑慮就不動並回報。 diff --git a/skills/spec-time-log/SKILL.md b/skills/spec-time-log/SKILL.md new file mode 100644 index 0000000..3d216db --- /dev/null +++ b/skills/spec-time-log/SKILL.md @@ -0,0 +1,36 @@ +--- +name: spec-time-log +description: JSC plugins 共用「時間戳與輸出訊息格式規範」：更新時間一律台灣時區（Asia/Taipei）固定 yyyy/MM/dd HH:mm:ss、寫成檔內固定字串、流程完成後統一同步各處時間戳；輸出訊息統一為 [yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息（等級 INF/WRN/ERR/TRC/DBG）、一行一則。當其他 skill 內文引用 spec-time-log 或 /jsc:spec-time-log、或需要產生更新時間／統一 log 格式時載入此 skill。單獨被使用者呼叫時，直接說明本規範內容。 +--- + +# spec-time-log — 共用時間戳與訊息格式規範 + +## 更新時間 + +- 一律使用**台灣時區（Asia/Taipei）**並固定為 `yyyy/MM/dd HH:mm:ss`，例如 `2026/06/30 18:30:05`。取得方式： + + ```bash + TZ='Asia/Taipei' date +'%Y/%m/%d %H:%M:%S' + ``` + +- 寫入檔案（橫幅、標頭註解、README）的更新時間語意為「本檔最後由 skill 產生／更新的時間」，**寫成檔內固定字串**（非執行期動態時間）。 +- 多階段流程中先寫入暫定時間戳即可；**全部完成後以完成當下的時間回頭統一同步各處時間戳**（橫幅、標頭註解區塊、README），確保各處一致。 + +## 輸出訊息格式 + +function 或指令檔若有輸出訊息（log、console 輸出、echo、提示訊息），格式必須統一為： + +``` +[yyyy/MM/dd HH:mm:ss][階段][等級]: 訊息 +``` + +- `階段`：選填，沿用該訊息所屬區塊的原始名稱並**保留原文不翻譯**；無對應階段則移除整個 `[階段]` 區塊。 +- `等級`：限 `INF`／`WRN`／`ERR`／`TRC`／`DBG` 其中之一。 +- `時間`：Asia/Taipei，固定 `yyyy/MM/dd HH:mm:ss`。 +- 調整訊息格式僅限「訊息呈現方式」，**不得改變訊息反映的實際行為或判斷邏輯**。 + +## 區塊階段命名與一行一則 + +- 被格式化的 log 若包在有名稱的區塊內（原始碼的 `#region 名稱`、指令檔以「分隔線＋標題＋分隔線」宣告的橫幅段落），須將區塊名稱作為該段每則 log 的 `階段` 前綴，並**移除該包裹／橫幅本身**（僅移除標記，保留區塊內原有指令與行為）。 +- **例外**：檔案開頭「用途／更新日期」的說明標頭（含外框分隔線）屬檔案標頭、不是階段區塊，必須原樣保留。 +- **一行一則**：每則訊息必須是獨立的單行輸出指令；不得用多行字串、字串拼接或迴圈外包裹把多則訊息包成一個輸出。原本包成一坨的必須拆成逐行逐則，且每則仍套用統一格式。