docs(guidelines): 修正版本閘門、重啟閘門與維護頁的準則記載
版本前置檢查的豁免表只列了四項,重啟閘門的豁免表少了 hook 修復技能。 照著這兩張表設定,hook 壞掉時唯一的修復路徑會被自己擋住,修不好也繞不過。 兩張表逐項對齊三方實作與腳本現況,補成七項與十項, 並寫明各自的唯一真實來源是哪一支 hook 腳本,兩邊以後要一起改。 Wiki 頁命名總表原本替維護類型列了內容頁。 技能與樣板都沒有產生那一頁的步驟,照著總表找,只會找到一個不存在的頁。 改成只列目錄頁,並寫清楚維護登記全寫在目錄頁的表格裡; 要補內容頁就先補技能步驟與樣板,不能只在總表上寫著。 另外登記技能盤點頁的類型、環境變數與雜湊來源,說明為什麼雜湊要帶工具名稱, 補上唯讀稽核要帶唯讀旗標、行數一律讀腳本自己印的那一行兩項檢查, 並把新增的共用說明、兩份樣板與三支工具寫進 README 的檔案一覽。
This commit is contained in:
@@ -26,31 +26,31 @@ Marketplace 統一為 `jsc`(https://gitea.jsc.idv.tw/plugins/meta.git),安
|
||||
|
||||
### `skill-new`
|
||||
|
||||
新建技能:決策樹問細節(目標、觸發、輸入輸出、domain)→ 缺 domain 時依 template 結構建立新存取庫 → sub agent 依準則產生技能 → 審核清單自檢 → PR,並依 `references/pr-report.md` 回報。
|
||||
新建技能:先併行預跑 `list-skills.sh` 與 `sync-domains.sh`,再用決策樹問細節(目標、觸發、輸入輸出、domain)→ 缺 domain 時依 template 結構建立新存取庫 → sub agent 依準則產生技能 → 審核清單自檢 → PR,並依 `references/pr-report.md` 回報 → 依 `references/deploy-verify.md` 部署與驗證。
|
||||
|
||||
### `skill-update`
|
||||
|
||||
更新技能:先查 Gitea 正本 marketplace 取得 domain 清單並補 clone 缺少的存取庫,列出全部技能 → 使用者選擇 → 決策樹問更新細節 → 更新後依審核檢查清單逐項檢查,不符就回到詢問 → PR,並依 `references/pr-report.md` 回報。
|
||||
更新技能:先查 Gitea 正本 marketplace 取得 domain 清單並補 clone 缺少的存取庫,列出全部技能 → 使用者選擇 → 決策樹問更新細節 → 更新後依審核檢查清單逐項檢查,不符就回到詢問 → PR,並依 `references/pr-report.md` 回報 → 依 `references/deploy-verify.md` 部署與驗證。
|
||||
|
||||
### `skill-delete`
|
||||
|
||||
刪除技能:`sync-domains.sh` 依 Gitea 正本 marketplace 同步所有存取庫,`list-skills.sh` 列出全部技能 → 使用者選擇 → `find-skill-refs.sh` 盤點關聯檔案 → sub agent 逐檔判斷是否需修正以維持功能(需要就決策樹問修正細節並依準則檢查)→ 刪除 → `verify-skill-removed.sh` 實地檢查各 CLI 的技能快取與 hook 設定,確認沒有殘留 → PR。
|
||||
刪除技能:`sync-domains.sh` 依 Gitea 正本 marketplace 同步所有存取庫,`list-skills.sh` 列出全部技能 → 使用者選擇 → `find-skill-refs.sh` 盤點關聯檔案 → 併行的 sub agent 逐檔判斷是否需修正以維持功能(需要就決策樹問修正細節並依準則檢查)→ 刪除 → PR → 依 `references/deploy-verify.md` 部署,再用 `verify-skill-removed.sh` 實地檢查各 CLI 的技能快取與 hook 設定。深層刪除只在部署後查一次:部署前的刪除還沒生效,查了一定乾淨,證明不了任何事。
|
||||
|
||||
### `skillset-update`
|
||||
|
||||
批次更新——把一份變更需求套用到整個技能組的多個技能/domain,先檢查工具化、sub agent 與環境變數優先規則,再逐 repo 開 PR;PR 回報格式見 `references/pr-report.md`;單一技能改用 skill-update。
|
||||
批次更新——把一份變更需求套用到整個技能組的多個技能、domain。同步存取庫與決策樹併行起跑,先檢查工具化、sub agent 與環境變數優先規則,再由併行的 sub agent 逐 repo 改檔與開 PR;PR 回報格式見 `references/pr-report.md`,部署與驗證見 `references/deploy-verify.md`;單一技能改用 skill-update。
|
||||
|
||||
### `skill-check`
|
||||
|
||||
例行稽核——沒有變更需求時,先跑腳本語法檢查與 hook smoke,再把整個技能組逐一對照準則的審核檢查清單,並分開跑流程優化審查。優化面向包含可平行化、可下放工具、重複來回、冗餘步驟、過早或過晚的閘門;不符項目與優化建議分開回報,逐項決策樹確認後才套用,最後逐 repo 開 PR。有變更需求改用 skillset-update。
|
||||
例行稽核——沒有變更需求時,同步存取庫之後併行跑三組:`lint-scripts.sh` 加 hook smoke、準則審核檢查清單、流程與成本優化審查。優化面向包含可平行化、可下放工具、重複來回、冗餘步驟、過早或過晚的閘門與可省的成本;不符項目與優化建議分開回報,逐項決策樹確認後才套用,最後逐 repo 開 PR。有變更需求改用 skillset-update。
|
||||
|
||||
### `ste100-sync`
|
||||
|
||||
同步上游 speak-human-tw 的語言規則:比對 `references/ste100.md` 釘住的上游版本,有新版就萃取適用的變更、逐項決策樹確認、更新 lint 樣式、全庫重掃、bump manifest,最後開 PR。適合列為本 repo 的維護方式。
|
||||
同步上游 speak-human-tw 的語言規則:先只讀上游 `SKILL.md` frontmatter 的版本來比對,判定要更新才 clone;有新版就萃取適用的變更、逐項決策樹確認、更新 lint 樣式與 `jsc-hooks` 的簡體字表、全庫併行重掃、bump manifest,最後開 PR。適合列為本 repo 的維護方式。
|
||||
|
||||
### `tooling-guide`
|
||||
|
||||
盤點目前支援的 plugins、skills、hooks 管理與使用路徑,產出技能組基礎指引。適合建立技能組地圖、支援清單、hook 管理總覽與新人交接資料;安裝、更新、刪除、稽核與修復改用對應技能。
|
||||
盤點目前支援的 plugins、skills、hooks 管理與使用路徑,產出技能組基礎指引。基礎盤點一律沿用 `inventory-tooling.sh` 的輸出,不再重跑它內部已經跑過的三支腳本。適合建立技能組地圖、支援清單、hook 管理總覽與新人交接資料;安裝、更新、刪除、稽核與修復改用對應技能。
|
||||
|
||||
<!-- JSC-SKILLS:END -->
|
||||
|
||||
@@ -60,15 +60,24 @@ Marketplace 統一為 `jsc`(https://gitea.jsc.idv.tw/plugins/meta.git),安
|
||||
| --- | --- |
|
||||
| `references/guidelines.md` | 技能準則唯一來源,所有 domain 的 AGENTS.md 都指向這裡 |
|
||||
| `references/ste100.md` | STE100 擬人台灣感語言規則唯一來源(改寫自 speak-human-tw,MIT) |
|
||||
| `tools/ste100-lint.sh` | 語言規則的機檢工具:中國用語、中文句內半形標點、AI 套話、簡體字、中文並列斜線;命中 exit 1 |
|
||||
| `references/pr-report.md` | PR 收尾回報格式唯一來源,所有會開 PR 的技能都指向這裡 |
|
||||
| `references/deploy-verify.md` | 四支異動技能共用的部署與驗證流程:判路線、部署或工作樹、**在新的 CLI 行程裡驗證**、失敗分流 |
|
||||
| `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/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`;不在正本清單上的存取庫不列 |
|
||||
| `tools/inventory-tooling.sh` | 盤點目前支援的 plugins、skills、tools、hooks,輸出技能組基礎指引 Markdown |
|
||||
| `tools/sync-marketplace.sh` | 寫入或更新兩份正本 marketplace 的 plugin 條目,再複製到每個 domain 存取庫(保證位元組一致)。**需要 python3**(json 模組改 JSON),缺 python3 不寫檔並 exit 1;存取庫不在本機 exit 3 |
|
||||
| `tools/sync-skill-manifest.sh` | 同步 domain README 的「Skills 目錄」,並 bump 三份 manifest 的 version;`minor` 與 `patch` 不得超過 `9`,`major` 可以超過 `9` |
|
||||
| `tools/sync-skill-manifest.sh` | 同步 domain README 的「Skills 目錄」,並 bump 三份 manifest 的 version;`minor` 與 `patch` 不得超過 `9`,`major` 可以超過 `9`。缺目錄、缺標記或缺 version 欄位 exit 1,用法錯誤 exit 2 |
|
||||
| `tools/find-skill-refs.sh` | 盤點一個技能在正本 marketplace 各 domain 存取庫裡的引用檔案(不掃非技能組存取庫與點開頭目錄);技能名稱為純子字串比對,命中要逐檔確認;零命中 exit 1,掃描失敗 exit 3 |
|
||||
| `tools/verify-skill-removed.sh` | 刪除技能後實地檢查各 CLI 的技能快取與 hook 設定有無殘留;有殘留 exit 1,沒偵測到 CLI 或沒有可查位置 exit 3(**不等於乾淨**) |
|
||||
|
||||
兩份 `TOOLING` 樣板的寫入語意剛好相反,套用前先分清楚。目錄頁是共用的,整頁覆蓋會刪掉別台機器的紀錄,所以只准動自己那一列。內容頁只屬於一組「機器、CLI、帳號」,記的是當下現況,舊的安裝內容早就不成立,所以整頁覆寫。頁名與雜湊規則見 `references/guidelines.md` 的「Wiki 頁命名總表」。
|
||||
|
||||
## 相關 domain
|
||||
|
||||
- [`jsc-ask`](https://gitea.jsc.idv.tw/plugins/ask):決策樹問詢
|
||||
|
||||
Reference in New Issue
Block a user