From 4a741071e52a10b8554bdd32ad87ae4c794a03c5 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Mon, 31 Aug 2026 19:12:48 +0800 Subject: [PATCH] =?UTF-8?q?docs(frontmatter-lint):=20=E5=90=8C=E6=AD=A5=20?= =?UTF-8?q?README=20=E8=88=87=E8=A1=8C=E7=82=BA=E6=B8=85=E5=96=AE=E7=9A=84?= =?UTF-8?q?=20frontmatter=20=E6=AA=A2=E6=9F=A5?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What： - README 的 skill-check 段落，第一組稽核補上 lint-frontmatter.sh。 - README 的工具表新增 tools/lint-frontmatter.sh 一列，寫明五項檢查、不相依 YAML 套件、四種結束碼、退出 3 不等於通過。 - references/behaviors.md 的 skill-check 表改寫四列：關鍵步驟、外部呼叫、完成條件、可驗證跡象。 Why： - 準則要求該 domain 的 behaviors.md 與 skills/ 相符，check-behaviors.sh 才會退出 0；README 的「Skills 目錄」也要跟著改動同步。 - 文件沒跟上，稽核就查不到這支新腳本，也不知道退出 3 是什麼都沒掃。這支腳本擋的正是靜默失效，文件本身先靜默漏掉它，等於白做。 How： - 照 skills/skill-check/SKILL.md 的新流程改寫，關鍵步驟寫明第一組平行跑腳本檢查、frontmatter 檢查、行為清單檢查與 hook smoke。 - 外部呼叫清單依實際呼叫順序插入 tools/lint-frontmatter.sh。 - 完成條件補上「frontmatter 檢查退出 3 是什麼都沒掃，不算通過」，可驗證跡象補上「每個 domain 的 lint-frontmatter.sh 退出 0」。 - 第二組留白項目由四項改五項，同步寫進關鍵步驟的合併說明。 Who： 屬 CLI hook 接線修正（jsc-hooks 0.3.4）在 meta 這一側的文件同步。 --- README.md | 3 ++- references/behaviors.md | 8 ++++---- 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index bccac38..4f77678 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 ### `skill-check` -例行稽核——沒有變更需求時，同步存取庫之後併行跑三組：`lint-scripts.sh` 加 `check-behaviors.sh` 加 hook smoke、準則審核檢查清單、流程與成本優化審查。優化面向包含可平行化、可下放工具、重複來回、冗餘步驟、過早或過晚的閘門與可省的成本；不符項目與優化建議分開回報，逐項決策樹確認後才套用，最後逐 repo 開 PR。有變更需求改用 skillset-update。 +例行稽核——沒有變更需求時，同步存取庫之後併行跑三組：`lint-scripts.sh` 加 `lint-frontmatter.sh` 加 `check-behaviors.sh` 加 hook smoke、準則審核檢查清單、流程與成本優化審查。優化面向包含可平行化、可下放工具、重複來回、冗餘步驟、過早或過晚的閘門與可省的成本；不符項目與優化建議分開回報，逐項決策樹確認後才套用，最後逐 repo 開 PR。有變更需求改用 skillset-update。 ### `ste100-sync` @@ -68,6 +68,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | `tools/plugins-root.sh` | 推導技能組工作目錄的根，六支腳本共用。以 plugin 形式安裝時「腳本上兩層」會落在快取目錄，所以推導規則抽出來；推不出來 exit 1 並指名要設 `JSC_PLUGINS_ROOT` | | `tools/ste100-lint.sh` | 語言規則的機檢工具：中國用語、中文句內半形標點、AI 套話、簡體字、中文並列斜線；命中 exit 1，沒給檢查對象 exit 2 | | `tools/lint-scripts.sh` | 一個 domain 的腳本檢查三合一：`sh -n` 語法、執行權限、檔頭結束碼宣告；有不合格 exit 1，沒有腳本可掃 exit 3（**不等於通過**） | +| `tools/lint-frontmatter.sh` | 一個 domain 每支 `skills/*/SKILL.md` 的 frontmatter 解析檢查：分隔線成對、必要鍵齊全、未加引號的純量不含「冒號加空白」也不以 YAML 特殊字元起頭、引號收得起來。不相依任何 YAML 套件。不合格 exit 1（清單在 stderr），用法錯誤 exit 2，沒有 SKILL.md 可掃 exit 3（**不等於通過**）。frontmatter 壞掉時 Antigravity 會**靜默丟棄整支技能**，沒有任何錯誤訊息 | | `tools/check-behaviors.sh` | 比對一個 domain 的 `references/behaviors.md` 與 `skills/`：節對技能、字典序、每節一張表、五個欄位齊全且內容欄非空；不符 exit 1，用法錯誤 exit 2，找不到清單或找不到技能 exit 3（**不等於通過**） | | `tools/deploy-route.sh` | 判定改動有沒有進存取庫的預設分支，決定走部署路線（exit 0）或工作樹路線（exit 3）；判不出來 exit 1，**不等於工作樹路線** | | `tools/sync-domains.sh` | 依 Gitea 正本 marketplace 把所有 domain 存取庫 clone 或 pull 到本機，印出 `domainpath`；**只有 exit 0 代表全部到位且最新**，exit 3 代表有存取庫跳過或 pull 失敗（stderr 列路徑），exit 2 代表有 domain clone 失敗 | diff --git a/references/behaviors.md b/references/behaviors.md index de4bb7f..f51a5f4 100644 --- a/references/behaviors.md +++ b/references/behaviors.md @@ -7,10 +7,10 @@ | 項目 | 內容 | | --- | --- | | 觸發時機 | 手上沒有異動需求，要對整組技能做例行或臨時稽核時用。帶著異動需求要改多支技能走 skillset-update、只改一支走 skill-update | -| 關鍵步驟 | 先跑 sync-domains.sh 同步全部 domain 存取庫、再平行跑三組審查（第一組跑腳本檢查、行為清單檢查與 hook smoke、第二組以 sub agent 逐 domain 對 guidelines 檢查清單稽核、第三組以 sub agent 分六個面向審查流程與成本）、合併三組結果並用決策樹逐項確認、以平行 sub agent 套用確認過的修正並跑 sync-skill-manifest.sh、跑 sync-marketplace.sh 同步兩份正本 marketplace、重跑三組驗證直到接受的修正全通過、每個受影響存取庫各開一條 PR | -| 外部呼叫 | tools/sync-domains.sh、tools/lint-scripts.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/sync-marketplace.sh、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh smoke、jsc-ask:ask、jsc-git:pr | -| 完成條件 | 每個 domain 都有腳本檢查與行為清單檢查的結論、每個 domain 的檢查清單在合併後補齊、每項不合規與每項優化建議都有決策紀錄、接受的修正重驗通過、每個受影響存取庫都拿到 PR 網址 | -| 可驗證跡象 | 受影響存取庫留下檔案改動、改到行為的技能連帶改寫該存取庫的 references/behaviors.md、README 的「Skills 目錄」重寫、三份 manifest 版本號提升、兩份 marketplace 檔逐位元一致、每個受影響存取庫一條 PR | +| 關鍵步驟 | 先跑 sync-domains.sh 同步全部 domain 存取庫、再平行跑三組審查（第一組平行跑腳本檢查、frontmatter 檢查、行為清單檢查與 hook smoke，第二組以 sub agent 逐 domain 對 guidelines 檢查清單稽核，第三組以 sub agent 分六個面向審查流程與成本）、合併三組結果並用決策樹逐項確認（第二組留白的五項由第一組的結論補上）、以平行 sub agent 套用確認過的修正並跑 sync-skill-manifest.sh、跑 sync-marketplace.sh 同步兩份正本 marketplace、重跑三組驗證直到接受的修正全通過、每個受影響存取庫各開一條 PR | +| 外部呼叫 | tools/sync-domains.sh、tools/lint-scripts.sh、tools/lint-frontmatter.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/sync-marketplace.sh、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh smoke、jsc-ask:ask、jsc-git:pr | +| 完成條件 | 每個 domain 都有腳本檢查、frontmatter 檢查與行為清單檢查的結論（frontmatter 檢查退出 3 是「什麼都沒掃」，不算通過）、每個 domain 的檢查清單在合併後補齊、每項不合規與每項優化建議都有決策紀錄、接受的修正重驗通過、每個受影響存取庫都拿到 PR 網址 | +| 可驗證跡象 | 受影響存取庫留下檔案改動、改到行為的技能連帶改寫該存取庫的 references/behaviors.md、每個 domain 的 lint-frontmatter.sh 退出 0、README 的「Skills 目錄」重寫、三份 manifest 版本號提升、兩份 marketplace 檔逐位元一致、每個受影響存取庫一條 PR | ## skill-delete