docs(guidelines): 改寫相依版本準則並補上技能行為清單合約
What:「Manifest 相依版本」第 5 條改成部署端照樣更新,只在回報裡寫明缺哪一版。「版本前置檢查」補上相依版本檢查三列。新增「技能行為清單」一節,訂出位置、標題、節、表格、欄位與更新時機。審核檢查清單加上行為清單這一項。README 補上 behaviors.md 與 check-behaviors.sh 兩列,並把 skill-check 段落改成三組腳本。 Why:跳過更新會讓落後的 domain 永遠更新不到。它落後所以被跳過,被跳過所以永遠落後。相依版本不符要擋的是拿舊版去跑,不是把舊版換成新版。阻擋改到技能被呼叫的當下,才擋得住真正會出事的動作。行為清單要有一份格式合約,check-behaviors.sh 才有判定依據。 How:阻擋交給 jsc-hooks/hooks/version-guard.sh。版本比對由它自己實作,不呼叫 jsc-cli/tools/check-requires.sh。hook 專屬存放於 jsc-hooks,而且 jsc-cli 已宣告相依 jsc-hooks,反向呼叫會做出循環相依。兩道檢查共用同一份豁免清單。行為清單一個 domain 一份,放進該 domain 的 references/behaviors.md,技能改動與清單改動才進得了同一個 PR。 Who:涵蓋這次兩件需求的準則與說明文件,一件是相依版本不符改為阻擋執行,一件是技能行為清單。
This commit is contained in:
@@ -42,7 +42,7 @@ Marketplace 統一為 `jsc`(https://gitea.jsc.idv.tw/plugins/meta.git),安
|
||||
|
||||
### `skill-check`
|
||||
|
||||
例行稽核——沒有變更需求時,同步存取庫之後併行跑三組:`lint-scripts.sh` 加 hook smoke、準則審核檢查清單、流程與成本優化審查。優化面向包含可平行化、可下放工具、重複來回、冗餘步驟、過早或過晚的閘門與可省的成本;不符項目與優化建議分開回報,逐項決策樹確認後才套用,最後逐 repo 開 PR。有變更需求改用 skillset-update。
|
||||
例行稽核——沒有變更需求時,同步存取庫之後併行跑三組:`lint-scripts.sh` 加 `check-behaviors.sh` 加 hook smoke、準則審核檢查清單、流程與成本優化審查。優化面向包含可平行化、可下放工具、重複來回、冗餘步驟、過早或過晚的閘門與可省的成本;不符項目與優化建議分開回報,逐項決策樹確認後才套用,最後逐 repo 開 PR。有變更需求改用 skillset-update。
|
||||
|
||||
### `ste100-sync`
|
||||
|
||||
@@ -62,11 +62,13 @@ Marketplace 統一為 `jsc`(https://gitea.jsc.idv.tw/plugins/meta.git),安
|
||||
| `references/ste100.md` | STE100 擬人台灣感語言規則唯一來源(改寫自 speak-human-tw,MIT) |
|
||||
| `references/pr-report.md` | PR 收尾回報格式唯一來源,所有會開 PR 的技能都指向這裡 |
|
||||
| `references/deploy-verify.md` | 四支異動技能共用的部署與驗證流程:判路線、部署或工作樹、**在新的 CLI 行程裡驗證**、失敗分流 |
|
||||
| `references/behaviors.md` | 本 domain 的技能行為清單:一支技能一節,五列記下觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象,供稽核與驗證比對。格式合約見 `references/guidelines.md` 的「技能行為清單」 |
|
||||
| `templates/tooling-contents.md` | `TOOLING_CONTENTS` 目錄頁樣板。一列代表一組「機器、CLI、帳號」;只更新自己那一列,別人的列原樣保留,**禁止整頁覆蓋** |
|
||||
| `templates/tooling-page.md` | `TOOLING_{HASH}` 內容頁樣板。分節對應 `inventory-tooling.sh` 的輸出;**每次盤點覆寫整頁**,只留現況,不留歷史 |
|
||||
| `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/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 到本機,印出 `domain<TAB>path`;**只有 exit 0 代表全部到位且最新**,exit 3 代表有存取庫跳過或 pull 失敗(stderr 列路徑),exit 2 代表有 domain clone 失敗 |
|
||||
| `tools/list-skills.sh` | 列出正本 marketplace 上各 domain 存取庫的技能,印出 `domain<TAB>name<TAB>description`;不在正本清單上的存取庫不列 |
|
||||
|
||||
Reference in New Issue
Block a user