docs(guidelines): 準則新增 SKILLSET 頁型、部署後重啟閘門與流程檢查四項

What:`references/guidelines.md` 四處增修。環境變數表新增 `JSC_WIKI_REPO_SKILLSET` 與 `JSC_RESTART_GATE` 兩列;wiki 頁命名總表新增 `SKILLSET` 一列,並補上雜湊來源為被改動的 domain 存取庫 `{owner}/{repo}`、頁內累積歷次異動兩段說明;新增「部署後重啟閘門」一節,用表寫下狀態檔、清除時機、判定位置與逃生門,另附九支豁免技能的表與「清單認的是技能名,不是呼叫鏈」一段;審核檢查清單末尾新增流程檢查四項。

Why:這批規則要落到四個 domain 的腳本與技能裡,準則是它們的唯一真實來源。規則只留在各自的實作裡,改一邊忘一邊,稽核就沒有對照標準。三件事各有各的理由:`SKILLSET` 頁型讓技能組每次異動留下查得到的驗證紀錄;重啟閘門補上「部署換掉的是磁碟上的技能檔,工作階段載入的還是舊版」這段落差;流程檢查四項把過去踩過的坑寫成逐項確認得出來的項目。

How:閘門那一節刻意把每一支的「為什麼不能擋」逐支寫出來,不只列技能名——豁免清單日後要增刪,理由沒寫下來就得重新想一次。九支的理由收斂成同一件事:部署後還要寫得完技能組異動報告與工作日誌,整批擋下去「先重啟」與「先寫完報告」會互相打死,通則另外寫進流程檢查第 4 項「閘門不自鎖」。「清單認技能名不認呼叫鏈」單獨寫一段,因為後三支(`jsc-ask:ask`、`jsc-git:pr`、`jsc-git:commit`)自己不是收尾規則的主體,是為了讓前六支走得完才補進來的,日後增豁免時要一併想它會呼叫誰。流程檢查其中兩項附上踩過的實例,抽象敘述判不出來的,看實例就判得出來。

Who:`jsc-meta` 的技能準則,以及依準則稽核的 `skill-check` 與四支技能組異動技能。
This commit is contained in:
2026-08-27 16:34:16 +08:00
parent 47c479d65c
commit 6447416c7b
+44
View File
@@ -86,9 +86,11 @@
| `JSC_WIKI_REPO_ERROR` | `ERROR_CONTENTS`、`ERROR_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` |
| `JSC_WIKI_REPO_CHECK` | `CHECK_CONTENTS`、`CHECK_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` |
| `JSC_WIKI_REPO_REPORT` | `REPORT_CONTENTS`、`REPORT_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` |
| `JSC_WIKI_REPO_SKILLSET` | `SKILLSET_CONTENTS`、`SKILLSET_{HASH}` 所在的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO` |
| `JSC_WIKI_REPO` | 未逐類設定時的共用 wiki `{owner}/{repo}` | 詢問使用者 |
| `JSC_HOME` | Hook 資料目錄 | 預設 `~/.jsc` |
| `JSC_PR_WATCH_INTERVAL` | `jsc-gitea/tools/pr-watch.sh` 輪詢 PR 狀態的間隔秒數 | 預設 60 |
| `JSC_RESTART_GATE` | 部署後重啟閘門的開關,`off` 關閉整道閘門 | 閘門開啟 |
頁面類型只讀自己的 `JSC_WIKI_REPO_{TYPE}`。只有該變數未設定時,才退回 `JSC_WIKI_REPO`。不得跨類型代用。
@@ -120,6 +122,37 @@
沒有 pre-tool hook 的 CLI 接不上這道檢查,`hooks-install` 要據實回報,不得暗示每個 CLI 都有保護。
## 部署後重啟閘門
部署換掉的是磁碟上的技能檔,目前工作階段載入的還是舊版。這段落差期間跑技能,改動看起來沒生效,人會以為部署失敗又重跑一次。
| 項目 | 規則 |
| --- | --- |
| 狀態檔 | `$JSC_HOME/restart-required`,由 `jsc-cli:deploy` 收尾寫入 |
| 清除時機 | 重啟 CLI 之後由 `jsc-hooks` 清除,不必手動刪 |
| 狀態檔存在時 | 擋下 jsc 技能呼叫,印出「請先重啟 CLI」與狀態檔路徑 |
| 狀態檔不存在時 | 全部放行 |
| 判定位置 | 程式層,由 `jsc-hooks` 執行,不靠技能內文自我約束 |
| 逃生門 | `JSC_RESTART_GATE=off` |
**豁免清單**(狀態檔存在也放行):
| 技能 | 為什麼不能擋 |
| --- | --- |
| `jsc-cli:deploy` | 部署本身的入口。擋了就沒有方法重跑部署,形成死鎖 |
| `jsc-hooks:hooks-install` | 部署後要重新接線,擋了會讓部署做一半卡住 |
| `jsc-gitea:wiki` | 寫 `SKILLSET_{HASH}` 異動報告與工作日誌的唯一路徑 |
| `jsc-log:worklog` | 部署後還要結清工作日誌 |
| `jsc-log:learn` | 部署後還要記這次的教訓 |
| `jsc-meta:*` | 開發技能組本身的工具,擋了就修不了技能組 |
| `jsc-ask:ask` | 上面幾支都要問使用者。擋了 `deploy` 連 install 或 update 都問不出來 |
| `jsc-git:pr` | 報告與異動的收尾要開 PR,擋了收尾做不完 |
| `jsc-git:commit` | 同上,`pr` 的第一步就是它 |
豁免這幾支的理由是同一件事:`jsc-meta` 四支異動技能的收尾要求把驗證結果寫進 `SKILLSET_{HASH}`,還要結清工作日誌,而這條路徑必經 `jsc-gitea:wiki` 與 `jsc-log`。全擋的話,部署一跑完就沒有路徑寫完報告,重啟閘門與報告要求互相打死。閘門不自鎖的通則見「審核檢查清單」的流程檢查第 4 項。
**清單認的是技能名,不是呼叫鏈。** 豁免技能轉呼叫的下一層若不在清單上,那一層照樣會被擋。後三支(`jsc-ask:ask`、`jsc-git:pr`、`jsc-git:commit`)自己不是收尾規則的主體,是為了讓前六支走得完才補進來的。`version-guard.sh` 的豁免清單當年也是為同一個原因收進 `jsc-ask:ask`。新增豁免技能時要一併想它會呼叫誰。
## Wiki 頁命名總表
所有 wiki 頁面一律採雙層命名:
@@ -137,6 +170,7 @@
| `ERROR` | `ERROR_CONTENTS` | `ERROR_{HASH}` | 異常目錄、異常頁 | jsc-hooks |
| `CHECK` | `CHECK_CONTENTS` | `CHECK_{HASH}` | 體檢目錄、執行環境體檢頁 | jsc-cli |
| `REPORT` | `REPORT_CONTENTS` | `REPORT_{HASH}` | 報表目錄、工作報表頁(年、月、週、日各一頁) | jsc-log |
| `SKILLSET` | `SKILLSET_CONTENTS` | `SKILLSET_{HASH}` | 技能組異動目錄、技能組異動報告頁(新增、更新、刪除、批次更新之後的驗證結果與改動清單) | jsc-meta |
`{HASH}` 一律為 `{owner}/{repo}`(必要時加上主題字串)的 SHA-1 前 8 碼,大寫。
若第一碼是 `0-9`、`A`、`B`、`C`,就改成 `H` 加上原 SHA-1 前 7 碼,總長仍維持 8 碼。
@@ -145,6 +179,9 @@
`REPORT` 用得到那個主題字串:雜湊來源為 `{owner}/{repo}/{期間}`,期間是 `daily`、`weekly`、`monthly`、`yearly` 其中之一。
年、月、週、日各自一頁,每頁內依期間累積分節。
`SKILLSET` 的雜湊來源就是被改動的 domain 存取庫 `{owner}/{repo}`,算法同上,由同一支 `jsc-gitea/tools/hash-id` 產生。
頁內**累積**歷次異動:每次異動附加一節,不覆蓋舊紀錄。要看一支技能改過幾次,就在同一頁上翻。
`CHECK` 是唯一例外:它記的是一台執行環境,不是一個存取庫,所以雜湊來源為 `{主機名}/{登入帳號}`。
8 碼與 `H` 前綴的算法完全相同,由同一支 `jsc-gitea/tools/hash-id` 產生。
在沒有存取庫的目錄也跑得出體檢,是這個例外存在的原因。
@@ -164,3 +201,10 @@
- [ ] 所有非程式碼輸出(程式碼註解、commit 訊息、PR 描述、wiki 頁、回報、文件)為繁體中文、UTF-8、無亂碼、無簡體字,且 `tools/ste100-lint.sh` 對該 domain 全綠
- [ ] 已同步更新該 domain 的 README「Skills 目錄」與三份 manifest 的 version
- [ ] PR 的 base 符合「PR 分支階梯」,沒有越級
流程檢查四項,對照技能自己的流程逐項確認:
- [ ] 技能內外引用的步驟編號、檔案路徑、節標題都真的存在,指標指得到。踩過的實例:規則搬到 `references/` 後指標指向空處,照著指過去只看到空白
- [ ] 每個步驟以可檢核的完成條件結尾,沒有「理解後」「適當地」這類模糊語
- [ ] 每個外部呼叫(腳本、API、其他技能)的失敗情況都有明寫怎麼辦,退出碼都有分流
- [ ] 技能自己裝的閘門不會擋掉解除那道閘門的唯一路徑(閘門不自鎖)。踩過的實例:工作包閘門若擋掉 `implement`,結清 PR 就沒有路徑