新增 frontmatter 解析檢查，改寫五支 CLI 的 hook 接線準則 #50
No Assignees
Notifications
Due Date
No due date set.
Dependencies
No dependencies set.
Reference: plugins/meta#50
Reference in New Issue
Block a user
摘要
tools/lint-frontmatter.sh補上第五種無聲失效的機檢。四支 CLI 原本都接錯位置，版本前置檢查與部署後重啟閘門因此長期完全失效，而且失效不報錯。版本號同步為 0.2.5。變更內容
tools/lint-frontmatter.shdescription是未加引號的 YAML 純量、內容含「冒號加空白」，那在 YAML 是語法錯誤，Antigravity 會靜默丟棄整支技能，磁碟 34 支只認 28 支，沒有任何錯誤訊息。這是第五個同一類的無聲失效，唯一發現途徑是逐檔比對磁碟數量與載入數量，人工每次稽核都要重做一遍還會漏，所以交給程式。檢查五項：分隔線成對、必要鍵齊全、未加引號的純量不含「冒號加空白」也不以 YAML 特殊字元起頭、引號收得起來。不相依任何 YAML 套件，因為護欄不該綁在不保證存在的相依上。references/guidelines.mdskill-name.sh與deny.sh兩支，避免規則寫兩份、改一份、另一份安靜漂移；改寫「版本前置檢查」，補進五支 CLI 的接線位置表與逐支陷阱表，並要求未實測的部分據實標明；改寫「部署後重啟閘門」，兩道閘門共用同一套接線就共用同一份事實表；審核檢查清單新增一項lint-frontmatter.sh退出 0。skills/skill-check/SKILL.mdlint-frontmatter.sh併進第一組稽核，與lint-scripts.sh平行跑，四個結束碼逐一路由，明寫退出 3 是「什麼都沒掃」、不算通過。第一組步驟重新編號；第二組 sub agent 要略過的既決項目由四項改五項；第一組完成條件、第 3 步合併說明、第 6 步重驗完成條件全部同步。description也補上新腳本。references/behaviors.mdcheck-behaviors.sh的比對來源，流程改了就要跟著改。skill-check 的關鍵步驟、外部呼叫、完成條件、可驗證跡象四列補上 frontmatter 檢查，完成條件寫明退出 3 不算通過。README.mdlint-frontmatter.sh；「Tools 目錄」表新增一列，寫清楚五項檢查、三個結束碼與「退出 3 不等於通過」，並註明 frontmatter 壞掉時 Antigravity 靜默丟棄整支技能。plugin.json.claude-plugin/plugin.json.codex-plugin/plugin.json設計重點
Skill，但 Codex 沒有Skill工具，技能是模型用 Bash 讀SKILL.md；codex 的hooks鍵寫成內嵌物件，實際規格是路徑字串；antigravity 的PreToolUse寫成 Flat，實際要matcher加hooks包一層的 Grouped；三支新接的命令沒帶JSC_CLI={代號}，閘門認不出自己跑在哪支 CLI 上，一次都擋不下來。copilot 原本指向$COPILOT_HOME/hooks/，那是腳本目錄不是設定目錄，設定從來不會被讀。degraded，不寫wired也不寫failed。理由是 CLI 限制，不是接線問題：技能走ResolveSkill這個 agent 內部請求、由前端發起，preToolUse攔不到技能叫用；userPromptSubmit的非零結束碼也擋不下那一輪。只能把警告印到 stdout 供注入並退出 0。installed_plugins.json那份本機載入版本，fail-closed 會把另外四支整批鎖死。這是版本讀得到讀不到的限制，跟能不能阻擋是兩件事。lint-frontmatter.sh不相依 YAML 套件。本機沒有 pyyaml，五項檢查只需要 YAML 1.2 的 plain scalar 規則，自己判定就夠，也才跑得到每一台機器上。單引號跳脫是重複一次、雙引號跳脫是反斜線，兩套規則不同，所以逐字掃而不用正規表示式一次比對兩種。測試結果
sh tools/lint-scripts.sh /root/plugins/meta退出 0，13 支腳本過語法、可執行、結束碼宣告三項，新腳本的執行權限已帶上；sh tools/check-behaviors.sh /root/plugins/meta退出 0，行為清單對上 7 支技能、五個欄位齊全；sh tools/ste100-lint.sh /root/plugins/meta退出 0。lint-frontmatter.sh對十個 jsc domain 實跑，全部退出 0，共 34 支 SKILL.md：ask 1 支、cli 5 支、git 2 支、gitea 5 支、hooks 2 支、log 4 支、meta 7 支、pkg 1 支、review 3 支、sdlc 4 支。原本那 6 支「冒號加空白」的缺陷已在各自存取庫修掉，這支腳本確認修乾淨了。lint-frontmatter.sh的錯誤路徑也實跑：不帶參數退出 2（用法錯誤）；對沒有skills/的目錄退出 3 並印出原因，符合「什麼都沒掃、不等於通過」的設計。agy -p "/hooks"確認四條全載入）agent validate加三種反證）agentSpawn、userPromptSubmit實跑觸發degraded，理由是 CLI 限制不是接線問題：技能走ResolveSkill這個 agent 內部請求，preToolUse攔不到技能叫用，userPromptSubmit的非零結束碼也擋不下那一輪。write-guard.sh三種模式與 SDLC 模型鎖在 codex、copilot、antigravity、kiro 四支非 claude CLI 上還沒接線；kiro 的resources兩層 glob 能不能修好技能可見性未驗證。前置 Push Request
What： - 新增 tools/lint-frontmatter.sh，掃一個 domain 每支 skills/*/SKILL.md 的 frontmatter，檢查分隔線成對、必要鍵齊全、未加引號的純量不含「冒號加空白」、起頭字元不是 YAML 特殊字元、加了引號的值收得起來，共五項。 - 改寫 skills/skill-check/SKILL.md 的第一組稽核，把這支腳本併進去成為第 2 步，原本的行為清單檢查、結束碼路由檢查、hook smoke 依序後移。 - 第二組留白的檢查清單項目由四項改成五項，第 3 步的合併說明、三組的完成條件、第 6 步的重驗完成條件同步改寫。 Why： - 抓到 6 支技能的 description 是未加引號的 YAML 純量、內容含「冒號加空白」。那在 YAML 是鍵的分隔符號，整份 frontmatter 當場語法錯誤。 - Antigravity 讀到語法錯誤就靜默丟棄整支技能。磁碟上 34 支，它只認 28 支。載入器不報、CLI 不報，技能清單只是少了幾列。 - 這種缺陷唯一的發現途徑是逐檔比對磁碟數量與載入數量。人工比對 10 個 domain 每次稽核都要重做一遍，還會漏。輸入輸出固定的判定就交給程式。 How： - 腳本用 awk 自己判定 YAML 1.2 的 plain scalar 規則，不相依 pyyaml。護欄不綁在一個不保證存在的相依上，才跑得到每一台機器。 - 單引號的跳脫是重複一次、雙引號的跳脫是反斜線，兩套規則不同，所以引號改用逐字掃描，不用正規表示式一次比對兩種。 - 結束碼分四種：0 是掃到 SKILL.md 且五項全過、1 是有不合格項目（清單走 stderr，格式 {檔案}:{鍵}:{說明}）、2 是用法錯誤、3 是什麼都沒掃。 - SKILL.md 明寫退出 3 不算通過，並把「每個 domain 的 lint-frontmatter.sh 退出 0」列進第 6 步的完成條件。 Who： 屬 CLI hook 接線修正（jsc-hooks 0.3.4）在 meta 這一側的稽核工具。What： - 改寫「Hook 規則」第 3 條，寫明五支 CLI 的 hook 負載形態各不相同，沒有哪一支是基準格式。 - 新增「技能名解析與阻擋輸出的共用腳本」節，列出 skill-name.sh 與 deny.sh 的用法、各 CLI 的技能名取值來源、抽成共用腳本的理由。 - 改寫「版本前置檢查」，補上五支 CLI 的接線位置表、逐支陷阱表、未實測部分的標明規則。 - 改寫「部署後重啟閘門」，指名 restart-gate.sh，並寫明接線位置與版本前置檢查完全相同。 - 審核檢查清單新增一項：該 domain 的 lint-frontmatter.sh 要退出 0，退出 3 不算通過。 Why： - 這一節以前寫著「只有 claude 接得上，其餘四支沒有 pre-tool hook」。那是錯的。四支全都有能阻擋的 pre-tool 事件，是我們接錯位置。 - 四個無聲失效逐一坐實了這件事：codex 的 matcher 用 Skill，但 Codex 沒有 Skill 工具，技能是模型用 Bash 讀 SKILL.md；codex 的 hooks 鍵寫成內嵌物件，實際規格是路徑字串；antigravity 的 PreToolUse 寫成 Flat，實際要 matcher 加 hooks 包一層的 Grouped；三支新接的命令沒帶 JSC_CLI={代號}，閘門認不出自己跑在哪支 CLI 上，一次都擋不下來。 - 錯誤的結論被寫進準則之後就沒有人再去查。版本前置檢查與部署後重啟閘門因此在四支 CLI 上長期失效，而且失效是安靜的：hook 沒被觸發不會報錯，看起來就跟「沒有東西該擋」一樣。 How： - 接線位置表每一列都經過執行檔抽出或本機實測，事件名、matcher、寫入檔案、阻擋方式逐欄寫死。 - verdict 據實分級：claude、codex、copilot、antigravity 寫 wired；kiro 的技能叫用走 ResolveSkill 內部請求、不走工具管線，攔不到，寫 degraded，不寫 failed。 - antigravity 與 kiro 的觸發沒有實跑驗證，另段標明，回報時不得混進已驗證的結論。 - 兩道閘門共用同一套接線，就共用同一份事實表。重啟閘門那節只指回接線位置表，不另寫一份能力描述，避免改一份、漏一份。 Who： 屬 CLI hook 接線修正（jsc-hooks 0.3.4）在 meta 這一側的規範文件。