docs(meta): 同步文件與參考資料
What：更新 README、AGENTS.md、templates 與 references，讓文件敘述與實際行為一致。 Why：稽核發現多處文件與程式行為分歧，違反「每個意義只有單一真實來源」。 How：以實際程式行為為準改寫敘述，重複的規則收成單一來源並以一行指引指過去。 Who：jsc-meta:skill-check 例行稽核（2026-08-25）。 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 5
@@ -2,7 +2,7 @@
|
||||
|
||||
jsc 技能組的 meta domain：新建、更新、刪除技能的流程，以及**全技能組的準則單一來源** `references/guidelines.md`（命名、description 規則、hook / 工具 / sub agent 下放、語言、環境變數、wiki 頁命名總表、審核檢查清單）。
|
||||
|
||||
## 安裝 / 更新 / 移除
|
||||
## 安裝、更新、移除
|
||||
|
||||
Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 `jsc-meta@jsc`。每個指令一行：
|
||||
|
||||
@@ -34,7 +34,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
|
||||
### `skill-delete`
|
||||
|
||||
刪除技能：先查 Gitea 正本 marketplace 取得 domain 清單並補 clone 缺少的存取庫，列出全部技能 → 使用者選擇 → sub agent 盤點關聯檔案 → 逐檔判斷是否需修正以維持功能（需要就決策樹問修正細節並依準則檢查）→ 刪除 → sub agent 實地檢查各 CLI 的技能與 hook 保存位置，確認沒有殘留 → PR。
|
||||
刪除技能：`sync-domains.sh` 依 Gitea 正本 marketplace 同步所有存取庫，`list-skills.sh` 列出全部技能 → 使用者選擇 → `find-skill-refs.sh` 盤點關聯檔案 → sub agent 逐檔判斷是否需修正以維持功能（需要就決策樹問修正細節並依準則檢查）→ 刪除 → `verify-skill-removed.sh` 實地檢查各 CLI 的技能快取與 hook 設定，確認沒有殘留 → PR。
|
||||
|
||||
### `skillset-update`
|
||||
|
||||
@@ -46,7 +46,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
|
||||
### `ste100-sync`
|
||||
|
||||
同步上游 speak-human-tw 的語言規則：比對 `references/ste100.md` 釘住的上游版本，有新版就萃取適用的變更、更新 lint 樣式、全庫重掃，最後開 PR。適合列為本 repo 的維護方式。
|
||||
同步上游 speak-human-tw 的語言規則：比對 `references/ste100.md` 釘住的上游版本，有新版就萃取適用的變更、逐項決策樹確認、更新 lint 樣式、全庫重掃、bump manifest，最後開 PR。適合列為本 repo 的維護方式。
|
||||
|
||||
<!-- JSC-SKILLS:END -->
|
||||
|
||||
@@ -56,7 +56,13 @@ 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 |
|
||||
| `tools/ste100-lint.sh` | 語言規則的機檢工具：中國用語、中文句內半形標點、AI 套話、簡體字、中文並列斜線；命中 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/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 |
|
||||
| `tools/find-skill-refs.sh` | 盤點一個技能在正本 marketplace 各 domain 存取庫裡的引用檔案（不掃非技能組存取庫與點開頭目錄）；技能名稱為純子字串比對，命中要逐檔確認；零命中 exit 1，掃描失敗 exit 3 |
|
||||
| `tools/verify-skill-removed.sh` | 刪除技能後實地檢查各 CLI 的技能快取與 hook 設定有無殘留；有殘留 exit 1，沒偵測到 CLI 或沒有可查位置 exit 3（**不等於乾淨**） |
|
||||
|
||||
## 相關 domain
|
||||
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
|
||||
## Description 規則
|
||||
|
||||
1. frontmatter 的 `description` 為一行英文，不超過 5 句或 5 個步驟。
|
||||
1. frontmatter 的 `description` 為一行英文，不超過 5 句或 5 個步驟——**兩個上限滿足任一個就算通過**，句數與步驟數都超過才要精簡。
|
||||
2. 使用專有名詞、概念或指引詞（例：WBS、TDD、decision tree、STE100）取代解釋。
|
||||
3. 必須寫清楚觸發時機（何時用、何時不用），這是各 CLI 自動載入的唯一依據。
|
||||
4. 複雜流程透過**組合其他技能**實現，不在單一 description 裡塞流程。
|
||||
@@ -77,13 +77,17 @@
|
||||
|
||||
技能組的每一支技能在被呼叫前都要確認本機版本沒有落後遠端發佈版本。判定在程式層，由 `jsc-hooks` 的 `version-guard.sh`（PreToolUse，matcher `Skill`）執行，**不靠技能內文自我約束**——寫在內文的規則，模型可以無視。
|
||||
|
||||
這道檢查只擋「確定落後」一種情況。查不到任何一項基礎資訊就安靜放行（exit 0），不要求先修好環境：五支 CLI 只有 claude 讀得到本機載入版本，fail-closed 會把另外四支整批鎖死。
|
||||
|
||||
| 項目 | 規則 |
|
||||
| --- | --- |
|
||||
| 比對對象 | 遠端發佈版本（`master` 的 `plugin.json`）對本機**實際載入**版本 |
|
||||
| 實際載入版本 | 讀 `installed_plugins.json` 的 `installPath` 底下那份 `plugin.json`，**不可只看註冊欄位**——兩者可能不同，只看註冊值會放過真正被載入的舊版 |
|
||||
| 落後 | 擋下該次技能呼叫（exit 2），並印出更新指令 |
|
||||
| 相等或超前 | 放行。開發技能組時本機本來就會超前 `master`，擋下去維護者自己動不了 |
|
||||
| 查不到遠端版本 | **擋**（fail-closed）。查詢失敗會重試一次，仍失敗才擋 |
|
||||
| 比對對象 | 遠端發佈版本（存取庫**預設分支**的 `plugin.json`，經 `jsc-gitea/tools/gitea.sh` 讀取，不寫死分支名）對本機**實際載入**版本 |
|
||||
| 實際載入版本 | 只認 `installed_plugins.json` 的 `installPath` 底下那份 `plugin.json`。註冊在 `installed_plugins.json` 的 `version` 欄位**不當備援**——註冊值可能比實際載入的版本新，拿它來比對會放過真正被載入的舊版 |
|
||||
| 落後 | 擋下該次技能呼叫（exit 2），並印出更新指令。**只有這一種情況會擋** |
|
||||
| 相等或超前 | 放行。開發技能組時本機本來就會超前預設分支，擋下去維護者自己動不了 |
|
||||
| 查不到本機載入版本 | **放行**（exit 0，安靜降級）。讀不到 `installed_plugins.json`、裡面沒有該 plugin 的條目、取不到 `installPath`、`installPath` 底下那份 `plugin.json` 讀不到，四種都算這一列，不退回註冊欄位 |
|
||||
| 解不出 Gitea 站台 | **放行**（exit 0，安靜降級） |
|
||||
| 查不到遠端版本 | **放行**（exit 0，安靜降級）。缺基礎設施不等於落後，擋下去會把四支非 Claude CLI 整批鎖死 |
|
||||
| 逃生門 | `JSC_VERSION_GUARD=off`（離線工作用），快取秒數 `JSC_VERSION_TTL`（預設 600） |
|
||||
|
||||
**豁免清單**（永遠放行，改動前想清楚後果）：
|
||||
@@ -122,7 +126,7 @@
|
||||
新增或更新技能後逐項檢查，任一不符就修正：
|
||||
|
||||
- [ ] 名稱符合命名規則，且與既有技能目標不重複
|
||||
- [ ] description 為英文、≤ 5 句或 5 步驟、含觸發時機
|
||||
- [ ] description 為英文、≤ 5 句或 ≤ 5 步驟（滿足任一即通過）、含觸發時機（何時用、何時不用）
|
||||
- [ ] 可 hook 的規則已下放 jsc-hooks；可工具化的流程已下放 tools/；SKILL.md 沒有保留可由標準輸入輸出執行的細節流程
|
||||
- [ ] 細節流程已標示 MUST run as a sub agent
|
||||
- [ ] gitea 操作透過 gitea.sh 或 tea
|
||||
|
||||
Reference in New Issue
Block a user