釋出技能委派判定的地基與接線至 master，版本 0.2.8 升到 0.3.3 #70
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-meta",
|
||||
"version": "0.3.0",
|
||||
"version": "0.3.1",
|
||||
"description": "技能組自我管理：新建、更新、刪除技能與技能準則",
|
||||
"skills": "./skills",
|
||||
"author": {
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-meta",
|
||||
"version": "0.3.0",
|
||||
"version": "0.3.1",
|
||||
"description": "技能組自我管理：新建、更新、刪除技能與技能準則",
|
||||
"skills": "./skills",
|
||||
"jsc": {
|
||||
|
||||
@@ -63,9 +63,9 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
| `references/pr-report.md` | PR 收尾回報格式唯一來源，所有會開 PR 的技能都指向這裡 |
|
||||
| `references/deploy-verify.md` | 四支異動技能共用的部署與驗證流程：判路線、部署或工作樹、**在新的 CLI 行程裡驗證**、失敗分流 |
|
||||
| `references/behaviors.md` | 本 domain 的技能行為清單：一支技能一節，五列記下觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象，供稽核與驗證比對。格式合約見 `references/guidelines.md` 的「技能行為清單」 |
|
||||
| `templates/skillset-contents.md` | `SKILLSET_CONTENTS` 目錄頁樣板。一列代表一個 domain 存取庫；本頁落在 `JSC_WIKI_REPO_CONTENTS`，連結一律寫成 `[{文字}]({連結})` 的絕對網址並先過 `link-check.sh` 驗證，寫入一律用 `jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "{owner}/{repo}"` 只寫自己那一列 |
|
||||
| `templates/skillset-contents.md` | `SKILLSET_CONTENTS` 目錄頁樣板。大標題加條列：一個 H2 區塊代表一個 domain 存取庫，標題是內容頁頁名 `SKILLSET_{HASH}`，欄位一行一條；本頁落在 `JSC_WIKI_REPO_CONTENTS`，連結一律寫成 `[{文字}]({連結})` 的絕對網址並先過 `link-check.sh` 驗證，寫入一律用 `jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}"` 只寫自己那一個區塊。`<key-col>` 那個 `2` 是**舊表格裡持有內容頁連結那一欄的序號**，只供自動轉檔用，序號照**線上那一頁實際的欄位排法**數、不是照範本：線上舊表頭是 `| 存放庫 | 異動報告 | 目前版本 | 最後更新 |`，連結在第 2 欄 |
|
||||
| `templates/skillset-page.md` | `SKILLSET_{HASH}` 內容頁樣板。歷次異動**累積**分節，每節記日期、異動類型、異動需求、動到的技能、改動檔案、PR 網址、部署路線判定與驗證結果；`skill-check` 那一節另含優化建議表，決議與決議日期兩欄供下一輪讀回 |
|
||||
| `templates/tooling-contents.md` | `TOOLING_CONTENTS` 目錄頁樣板。一列代表一組「機器、CLI、帳號」；只更新自己那一列，別人的列原樣保留，**禁止整頁覆蓋** |
|
||||
| `templates/tooling-contents.md` | `TOOLING_CONTENTS` 目錄頁樣板。大標題加條列：一個 H2 區塊代表一組「機器、CLI、帳號」，標題是內容頁頁名 `TOOLING_{HASH}`，欄位一行一條；寫入一律用 `jsc-gitea/tools/wiki-contents.sh upsert TOOLING 1 "TOOLING_{HASH}"`，只更新自己那一個區塊，別人的區塊原樣保留，**禁止整頁覆蓋** |
|
||||
| `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 |
|
||||
@@ -83,7 +83,7 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安
|
||||
| `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 頁命名總表」。
|
||||
兩份 `TOOLING` 樣板的寫入語意與版面都剛好相反，套用前先分清楚。目錄頁是共用的，整頁覆蓋會刪掉別台機器的紀錄，所以只准動自己那一個 H2 區塊，版面一律大標題加條列，頁上不留 markdown 表格。內容頁只屬於一組「機器、CLI、帳號」，記的是當下現況，舊的安裝內容早就不成立，所以整頁覆寫，版面維持圖表優先。頁名、雜湊與這條版面區分見 `references/guidelines.md` 的「Wiki 頁命名總表」。
|
||||
|
||||
## 相關 domain
|
||||
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
{
|
||||
"name": "jsc-meta",
|
||||
"version": "0.3.0",
|
||||
"version": "0.3.1",
|
||||
"description": "技能組自我管理：新建、更新、刪除技能與技能準則",
|
||||
"skills": "./skills/",
|
||||
"jsc": {
|
||||
|
||||
+19
-19
@@ -7,50 +7,50 @@
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 手上沒有異動需求，要對整組技能做例行或臨時稽核時用。帶著異動需求要改多支技能走 skillset-update、只改一支走 skill-update |
|
||||
| 關鍵步驟 | 先跑 sync-domains.sh 同步全部 domain 存取庫、再平行跑三組審查（第一組平行跑腳本檢查、frontmatter 檢查、行為清單檢查、語言檢查、連結寫法檢查、wiki 規則檢查、頁名樣式檢查與 hook smoke，第二組以 sub agent 逐 domain 對 guidelines 檢查清單稽核，第三組先用 wiki-repo SKILLSET 與 hash-id 讀回各 domain SKILLSET_{HASH} 上已決議的優化建議再以 sub agent 分六個面向審查流程與成本；讀取回 7、8 或存取庫解不出來時只停掉該 domain 的第三組，第一組、第二組與後續步驟照跑）、合併三組結果並用決策樹逐項確認（第二組留白的九項由第一組的結論補上，其中頁名樣式與 wiki 規則兩項是整輪一份，同一個結論填進每個 domain；優化建議記下決議與決議日期）、以平行 sub agent 套用確認過的修正並跑 sync-skill-manifest.sh、跑 sync-marketplace.sh 同步兩份正本 marketplace、重跑三組驗證直到接受的修正全通過、每個受影響存取庫各開一條 PR、最後以平行 sub agent 逐 domain 把本輪稽核結果附加到 SKILLSET_{HASH}，再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-check 寫一筆收尾事件（五種 status 依本輪實際結果選，中途停下的輪次也要寫；腳本不在就安靜跳過，不影響本輪結局） |
|
||||
| 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/lint-scripts.sh、tools/lint-frontmatter.sh、tools/check-behaviors.sh、tools/ste100-lint.sh、tools/check-link-format.sh、tools/check-page-name.sh、tools/sync-skill-manifest.sh、tools/sync-marketplace.sh、jsc-gitea/tools/check-wiki-rules.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那一列）、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh smoke、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
|
||||
| 關鍵步驟 | 先跑 sync-domains.sh 同步全部 domain 存取庫、再平行跑三組審查（第一組平行跑腳本檢查、frontmatter 檢查、行為清單檢查、語言檢查、連結寫法檢查、wiki 規則檢查、頁名樣式檢查與 hook smoke，第二組以 sub agent 逐 domain 對 guidelines 檢查清單稽核，第三組先用 wiki-repo SKILLSET 與 hash-id 讀回各 domain SKILLSET_{HASH} 上已決議的優化建議再以 sub agent 分六個面向審查流程與成本；讀取回 7、8 或存取庫解不出來時只停掉該 domain 的第三組，第一組、第二組與後續步驟照跑）、合併三組結果並用決策樹逐項確認（第二組留白的九項由第一組的結論補上，其中頁名樣式與 wiki 規則兩項是整輪一份，同一個結論填進每個 domain；優化建議記下決議與決議日期）、以平行 sub agent 套用確認過的修正並跑 sync-skill-manifest.sh、跑 sync-marketplace.sh 同步兩份正本 marketplace、重跑三組驗證直到接受的修正全通過、每個受影響存取庫各開一條 PR、最後以平行 sub agent 逐 domain 把本輪稽核結果附加到 SKILLSET_{HASH}，再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" 把自己那一個 H2 區塊寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS（目錄頁一律大標題加條列，鍵是 H2 標題也就是內容頁頁名，第四個參數是區塊檔），最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-check 寫一筆收尾事件（五種 status 依本輪實際結果選，中途停下的輪次也要寫；腳本不在就安靜跳過，不影響本輪結局） |
|
||||
| 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/lint-scripts.sh、tools/lint-frontmatter.sh、tools/check-behaviors.sh、tools/ste100-lint.sh、tools/check-link-format.sh、tools/check-page-name.sh、tools/sync-skill-manifest.sh、tools/sync-marketplace.sh、jsc-gitea/tools/check-wiki-rules.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁自己那個區塊）、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh smoke、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
|
||||
| 完成條件 | 每個 domain 都有腳本檢查、frontmatter 檢查、行為清單檢查、語言檢查與連結寫法檢查的結論（連結寫法檢查退出 3 是「什麼都沒掃」，不算通過），wiki 規則檢查與頁名樣式檢查各有一次結論（frontmatter 檢查退出 3 是「什麼都沒掃」、頁名樣式檢查退出 3 是「什麼都沒查」，都不算通過）、每個 domain 的檢查清單在合併後補齊且那兩項整輪一份的結論在每個 domain 都填上同一個值、讀不到已決議清單的 domain 記成「本輪未取得已決議清單，優化建議暫不提出」、每項不合規與每項優化建議都有決策紀錄且優化建議帶決議日期、接受的修正重驗通過、每個受影響存取庫都拿到 PR 網址、寫進 wiki 的每個連結都先經 link-check.sh 退出 0、每個受影響 domain 的 wiki 頁都寫成功，或列為未寫入並附完整內容、本輪的 skill-end 事件已寫入，或據實記成腳本不在這台機器上 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-check 的 skill-end 事件（本輪唯一必留的跡象，腳本不在時才沒有）、受影響存取庫留下檔案改動、改到行為的技能連帶改寫該存取庫的 references/behaviors.md、每個 domain 的 lint-frontmatter.sh、ste100-lint.sh 與 check-link-format.sh 退出 0、check-page-name.sh 退出 0、README 的「Skills 目錄」重寫、三份 manifest 版本號提升、兩份 marketplace 檔逐位元一致、每個受影響存取庫一條 PR、每個受影響 domain 的 SKILLSET_{HASH} 各附加一節，並由 wiki-contents.sh upsert 退出 0 在 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁；本輪無 domain 被改動時，改成 plugins/meta 那一頁記「本輪無發現」 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-check 的 skill-end 事件（本輪唯一必留的跡象，腳本不在時才沒有）、受影響存取庫留下檔案改動、改到行為的技能連帶改寫該存取庫的 references/behaviors.md、每個 domain 的 lint-frontmatter.sh、ste100-lint.sh 與 check-link-format.sh 退出 0、check-page-name.sh 退出 0、README 的「Skills 目錄」重寫、三份 manifest 版本號提升、兩份 marketplace 檔逐位元一致、每個受影響存取庫一條 PR、每個受影響 domain 的 SKILLSET_{HASH} 各附加一節，並由 wiki-contents.sh upsert 退出 0 在 SKILLSET_CONTENTS 留下自己那一個 `## SKILLSET_{HASH}` 區塊、區塊裡以 `- 異動頁：[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁；本輪無 domain 被改動時，改成 plugins/meta 那一頁記「本輪無發現」 |
|
||||
|
||||
## skill-delete
|
||||
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 要把一支技能從技能組移除時用。改名不走這支，走 skill-update |
|
||||
| 關鍵步驟 | 跑 sync-domains.sh 同步、跑 list-skills.sh 列出全部技能、讓使用者挑一支確認刪除、跑 find-skill-refs.sh 盤點所有引用檔案、以平行 sub agent 逐檔修正到檢查清單全過、刪掉 skills/{name}/ 目錄、移除 references/behaviors.md 對應那一節、跑 sync-skill-manifest.sh、開 PR、依 deploy-verify.md 部署、用新的 CLI 行程驗證、跑 verify-skill-removed.sh 查磁碟殘留、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-delete 寫一筆收尾事件（五種 status 依本次實際結果選，中途停下也要寫；腳本不在就安靜跳過，不影響本次結局） |
|
||||
| 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/list-skills.sh、tools/find-skill-refs.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、tools/verify-skill-removed.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那一列）、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
|
||||
| 關鍵步驟 | 跑 sync-domains.sh 同步、跑 list-skills.sh 列出全部技能、讓使用者挑一支確認刪除、跑 find-skill-refs.sh 盤點所有引用檔案、以平行 sub agent 逐檔修正到檢查清單全過、刪掉 skills/{name}/ 目錄、移除 references/behaviors.md 對應那一節、跑 sync-skill-manifest.sh、開 PR、依 deploy-verify.md 部署、用新的 CLI 行程驗證、跑 verify-skill-removed.sh 查磁碟殘留、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" 把自己那一個 H2 區塊寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS（目錄頁一律大標題加條列，鍵是 H2 標題也就是內容頁頁名，第四個參數是區塊檔） 並依 0、1、2、3、4、7、8 各自分流，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-delete 寫一筆收尾事件（五種 status 依本次實際結果選，中途停下也要寫；腳本不在就安靜跳過，不影響本次結局） |
|
||||
| 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/list-skills.sh、tools/find-skill-refs.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、tools/verify-skill-removed.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁自己那個區塊）、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
|
||||
| 完成條件 | 盤點清單每一檔都有「已修正」或「無需修正」的結論、技能目錄與行為清單那一節都不存在、list-skills.sh 查不到那一列、殘留檢查退出 0 或據實記成「無處可查」並帶進報告、PR 網址到手、寫進頁與列的每個連結都經 link-check.sh 退出 0、SKILLSET_{HASH} 附加一節且舊節原樣留著、wiki-contents.sh upsert 退出 0、本次的 skill-end 事件已寫入，或據實記成腳本不在這台機器上 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-delete 的 skill-end 事件（本次唯一必留的跡象，腳本不在時才沒有）、skills/{name}/ 目錄消失、references/behaviors.md 少一節、README 與三份 manifest 更新、一條 PR、wiki SKILLSET_{HASH} 附加一節，並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-delete 的 skill-end 事件（本次唯一必留的跡象，腳本不在時才沒有）、skills/{name}/ 目錄消失、references/behaviors.md 少一節、README 與三份 manifest 更新、一條 PR、wiki SKILLSET_{HASH} 附加一節，並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一個 `## SKILLSET_{HASH}` 區塊、區塊裡以 `- 異動頁：[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
|
||||
|
||||
## skill-new
|
||||
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 要在技能組新增一支技能時用。改既有技能走 skill-update |
|
||||
| 關鍵步驟 | 平行跑 list-skills.sh 與 sync-domains.sh 預取技能清單與 domain 清單、用決策樹問出目標、觸發時機、輸入輸出與所屬 domain、domain 未註冊就先確認存取庫在不在、依 template 結構補齊內容再跑 sync-marketplace.sh 註冊、以 sub agent 產生 skills/{name}/SKILL.md、在 references/behaviors.md 依字典序插入該技能一節、跑 sync-skill-manifest.sh、自查 guidelines 檢查清單並跑 check-behaviors.sh、開 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-new 寫一筆收尾事件（五種 status 依本次實際結果選，中途停下也要寫；腳本不在就安靜跳過，不影響本次結局） |
|
||||
| 外部呼叫 | tools/list-skills.sh、tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/sync-marketplace.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 clone-url、api、wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那一列）、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
|
||||
| 關鍵步驟 | 平行跑 list-skills.sh 與 sync-domains.sh 預取技能清單與 domain 清單、用決策樹問出目標、觸發時機、輸入輸出與所屬 domain、domain 未註冊就先確認存取庫在不在、依 template 結構補齊內容再跑 sync-marketplace.sh 註冊、以 sub agent 產生 skills/{name}/SKILL.md、在 references/behaviors.md 依字典序插入該技能一節、跑 sync-skill-manifest.sh、自查 guidelines 檢查清單並跑 check-behaviors.sh、開 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" 把自己那一個 H2 區塊寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS（目錄頁一律大標題加條列，鍵是 H2 標題也就是內容頁頁名，第四個參數是區塊檔） 並依 0、1、2、3、4、7、8 各自分流，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-new 寫一筆收尾事件（五種 status 依本次實際結果選，中途停下也要寫；腳本不在就安靜跳過，不影響本次結局） |
|
||||
| 外部呼叫 | tools/list-skills.sh、tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/sync-marketplace.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 clone-url、api、wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁自己那個區塊）、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
|
||||
| 完成條件 | 四項提問都有紀錄、SKILL.md 與行為清單那一節都在、README 與三份 manifest 同步、檢查清單全過且 check-behaviors.sh 退出 0、PR 網址到手、deploy-verify.md 第 1 到第 5 節的完成條件全數成立、寫進頁與列的每個連結都經 link-check.sh 退出 0、SKILLSET_{HASH} 附加一節且舊節原樣留著、wiki-contents.sh upsert 退出 0、本次的 skill-end 事件已寫入，或據實記成腳本不在這台機器上 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-new 的 skill-end 事件（本次唯一必留的跡象，腳本不在時才沒有）、新增 skills/{name}/SKILL.md、references/behaviors.md 多一節、README 與三份 manifest 更新、新 domain 時兩份 marketplace 檔多一筆 plugin 條目並同步到每個 domain 存取庫、一條 PR、wiki SKILLSET_{HASH} 附加一節，並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-new 的 skill-end 事件（本次唯一必留的跡象，腳本不在時才沒有）、新增 skills/{name}/SKILL.md、references/behaviors.md 多一節、README 與三份 manifest 更新、新 domain 時兩份 marketplace 檔多一筆 plugin 條目並同步到每個 domain 存取庫、一條 PR、wiki SKILLSET_{HASH} 附加一節，並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一個 `## SKILLSET_{HASH}` 區塊、區塊裡以 `- 異動頁：[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
|
||||
|
||||
## skill-update
|
||||
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 要改一支既有技能時用。新增走 skill-new、刪除走 skill-delete、一次改多支或跨 domain 走 skillset-update |
|
||||
| 關鍵步驟 | 跑 sync-domains.sh 同步、跑 list-skills.sh 列出全部技能、讓使用者挑一支、用決策樹問出改動細節、以 sub agent 改 SKILL.md 與相關檔案、同步更新 references/behaviors.md 該技能那一節、跑 sync-skill-manifest.sh、對 guidelines 檢查清單逐項自查並跑 check-behaviors.sh、開 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-update 寫一筆收尾事件（五種 status 依本次實際結果選，中途停下也要寫；腳本不在就安靜跳過，不影響本次結局） |
|
||||
| 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/list-skills.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那一列）、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
|
||||
| 關鍵步驟 | 跑 sync-domains.sh 同步、跑 list-skills.sh 列出全部技能、讓使用者挑一支、用決策樹問出改動細節、以 sub agent 改 SKILL.md 與相關檔案、同步更新 references/behaviors.md 該技能那一節、跑 sync-skill-manifest.sh、對 guidelines 檢查清單逐項自查並跑 check-behaviors.sh、開 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" 把自己那一個 H2 區塊寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS（目錄頁一律大標題加條列，鍵是 H2 標題也就是內容頁頁名，第四個參數是區塊檔） 並依 0、1、2、3、4、7、8 各自分流，最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-update 寫一筆收尾事件（五種 status 依本次實際結果選，中途停下也要寫；腳本不在就安靜跳過，不影響本次結局） |
|
||||
| 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/list-skills.sh、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁自己那個區塊）、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
|
||||
| 完成條件 | 每個提問都有紀錄、技能檔案帶著改動、行為清單那一節與新行為一致且 check-behaviors.sh 退出 0、三份 manifest 同版、檢查清單全過、PR 網址到手、deploy-verify.md 第 1 到第 5 節的完成條件全數成立、寫進頁與列的每個連結都經 link-check.sh 退出 0、SKILLSET_{HASH} 附加一節且舊節原樣留著、wiki-contents.sh upsert 退出 0、本次的 skill-end 事件已寫入，或據實記成腳本不在這台機器上 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-update 的 skill-end 事件（本次唯一必留的跡象，腳本不在時才沒有）、該技能的 SKILL.md 與相關檔案改動、references/behaviors.md 對應節改寫、README 與三份 manifest 更新、一條 PR、wiki SKILLSET_{HASH} 附加一節，並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skill-update 的 skill-end 事件（本次唯一必留的跡象，腳本不在時才沒有）、該技能的 SKILL.md 與相關檔案改動、references/behaviors.md 對應節改寫、README 與三份 manifest 更新、一條 PR、wiki SKILLSET_{HASH} 附加一節，並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 留下自己那一個 `## SKILLSET_{HASH}` 區塊、區塊裡以 `- 異動頁：[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
|
||||
|
||||
## skillset-update
|
||||
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 一個異動需求橫跨多支技能或多個 domain，要一次做完時用。只改一支走 skill-update、手上沒有異動需求的例行稽核走 skill-check |
|
||||
| 關鍵步驟 | 平行啟動 sync-domains.sh 與異動細節決策樹、問清楚改哪一條規則、影響哪些技能與 domain，並補問工具化、sub agent、環境變數三項塑形檢查、以每個 domain 一個 sub agent 平行套用改動、同步更新每個受影響 domain 的 references/behaviors.md、逐存取庫跑 sync-skill-manifest.sh、以平行 sub agent 重跑 guidelines 檢查清單與 check-behaviors.sh 直到全過、每個受影響存取庫各開一條 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、以平行 sub agent 逐存取庫用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 把自己那一列寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS 並依 0、1、2、3、4、7、8 各自分流，最後由主 agent 呼叫一次 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skillset-update 寫一筆收尾事件（整批一筆，不逐 domain 寫；五種 status 依本次實際結果選，中途停下也要寫；腳本不在就安靜跳過，不影響本次結局） |
|
||||
| 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、tools/list-skills.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁那一列）、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
|
||||
| 關鍵步驟 | 平行啟動 sync-domains.sh 與異動細節決策樹、問清楚改哪一條規則、影響哪些技能與 domain，並補問工具化、sub agent、環境變數三項塑形檢查、以每個 domain 一個 sub agent 平行套用改動、同步更新每個受影響 domain 的 references/behaviors.md、逐存取庫跑 sync-skill-manifest.sh、以平行 sub agent 重跑 guidelines 檢查清單與 check-behaviors.sh 直到全過、每個受影響存取庫各開一條 PR、依 deploy-verify.md 部署並用新的 CLI 行程驗證、以平行 sub agent 逐存取庫用 wiki-repo SKILLSET 解出存取庫並依 templates/skillset-page.md 把異動報告附加到 SKILLSET_{HASH}、再取 wiki-url 的絕對網址、把頁上與列上的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" 把自己那一個 H2 區塊寫進 CONTENTS 存取庫的 SKILLSET_CONTENTS（目錄頁一律大標題加條列，鍵是 H2 標題也就是內容頁頁名，第四個參數是區塊檔） 並依 0、1、2、3、4、7、8 各自分流，最後由主 agent 呼叫一次 jsc-hooks/tools/report-status.sh skill-end jsc-meta:skillset-update 寫一筆收尾事件（整批一筆，不逐 domain 寫；五種 status 依本次實際結果選，中途停下也要寫；腳本不在就安靜跳過，不影響本次結局） |
|
||||
| 外部呼叫 | tools/sync-domains.sh、jsc-hooks/tools/report-status.sh skill-end、tools/check-behaviors.sh、tools/sync-skill-manifest.sh、tools/deploy-route.sh、tools/list-skills.sh、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁自己那個區塊）、jsc-ask:ask、jsc-git:pr、jsc-gitea:wiki、templates/skillset-page.md、templates/skillset-contents.md |
|
||||
| 完成條件 | 受影響技能清單與三項塑形檢查都跟使用者談定、每個受影響存取庫都帶著改動、README 同步與 manifest 提升、每支動過的技能檢查清單全過且該 domain 的 check-behaviors.sh 退出 0、每個受影響存取庫都有 PR 網址、deploy-verify.md 第 1 到第 5 節對每個存取庫都成立、每個存取庫寫進頁與列的每個連結都經 link-check.sh 退出 0、每個存取庫的 SKILLSET_{HASH} 都附加一節且舊節原樣留著、每個存取庫的 wiki-contents.sh upsert 都退出 0、本次整批一筆的 skill-end 事件已寫入，或據實記成腳本不在這台機器上 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skillset-update 的 skill-end 事件（整批只有一行，本次唯一必留的跡象，腳本不在時才沒有）、每個受影響存取庫的技能檔案改動、各自的 references/behaviors.md 更新、README 與三份 manifest 更新、每個存取庫一條 PR、每個存取庫的 wiki SKILLSET_{HASH} 各附加一節，並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 各留下自己那一列、列裡以 `[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:skillset-update 的 skill-end 事件（整批只有一行，本次唯一必留的跡象，腳本不在時才沒有）、每個受影響存取庫的技能檔案改動、各自的 references/behaviors.md 更新、README 與三份 manifest 更新、每個存取庫一條 PR、每個存取庫的 wiki SKILLSET_{HASH} 各附加一節，並在 CONTENTS 存取庫的 SKILLSET_CONTENTS 各留下自己那一個 `## SKILLSET_{HASH}` 區塊、區塊裡以 `- 異動頁：[SKILLSET_{HASH}]({連結})` 的絕對網址指向該內容頁 |
|
||||
|
||||
## ste100-sync
|
||||
|
||||
@@ -67,7 +67,7 @@
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 使用者要技能組導覽、工具地圖、支援的 plugin 清單、支援的技能清單、hook 管理概觀或新人上手參考時用。安裝、更新、刪除、稽核、修復都不走這支 |
|
||||
| 關鍵步驟 | 跑 plugins-root.sh 確認工作根目錄、跑 sync-domains.sh 取得 domain 與本機路徑、跑 inventory-tooling.sh 產生基準盤點並同時蒐集管理流程事實、需要說明或分組時以 sub agent 綜整導覽草稿、主 agent 逐項核對每個說法的來源、依記錄下來的目標交付、目標是 wiki 頁時才以 sub agent 逐 CLI 算出頁名、先寫內容頁再登記目錄頁、最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:tooling-guide 寫一筆收尾事件（五種 status 依本次實際結果選，交付目標是聊天回應的那一輪也要寫；腳本不在就安靜跳過，不影響本次結局） |
|
||||
| 外部呼叫 | tools/plugins-root.sh、tools/sync-domains.sh、tools/inventory-tooling.sh、jsc-hooks/tools/report-status.sh skill-end、jsc-gitea/tools/hash-id、jsc-gitea:wiki、jsc-ask:ask |
|
||||
| 完成條件 | 每項事實都指得到來源檔案或工具輸出、必填章節都不是空的、收尾回報寫明交付目標、來源新鮮度、過期輸入與未知的 hook 判定；目標是 wiki 時每一頁都確認寫成功，或列為未寫入並附完整內容；每一種交付目標都要寫下本次的 skill-end 事件，或據實記成腳本不在這台機器上 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:tooling-guide 的 skill-end 事件，那是這支唯讀技能唯一的寫入跡象；目標是聊天回應時除了那一行沒有其他寫入跡象，只有回報內容；目標是檔案時另外只產生使用者指定的那一個檔；目標是 wiki 時每支偵測到的 CLI 各一頁 TOOLING_{HASH}，並在 TOOLING_CONTENTS 更新自己那一列 |
|
||||
| 關鍵步驟 | 跑 plugins-root.sh 確認工作根目錄、跑 sync-domains.sh 取得 domain 與本機路徑、跑 inventory-tooling.sh 產生基準盤點並同時蒐集管理流程事實、需要說明或分組時以 sub agent 綜整導覽草稿、主 agent 逐項核對每個說法的來源、依記錄下來的目標交付、目標是 wiki 頁時才以 sub agent 逐 CLI 用 hash-id 算出 TOOLING_{HASH}、先用 jsc-gitea:wiki 覆寫內容頁、再取 gitea.sh wiki-url 的絕對網址、把區塊裡的每個連結交給 link-check.sh 驗證、退出 0 才用 wiki-contents.sh upsert TOOLING 1 "TOOLING_{HASH}" 把自己那一個 H2 區塊寫進 CONTENTS 存取庫的 TOOLING_CONTENTS 並依 0、1、2、3、4、7、8 各自分流（目錄頁一律大標題加條列，版面正本在 wiki-contents.sh，本技能不自己組頁）、最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-meta:tooling-guide 寫一筆收尾事件（五種 status 依本次實際結果選，交付目標是聊天回應的那一輪也要寫；腳本不在就安靜跳過，不影響本次結局） |
|
||||
| 外部呼叫 | tools/plugins-root.sh、tools/sync-domains.sh、tools/inventory-tooling.sh、jsc-hooks/tools/report-status.sh skill-end、jsc-gitea/tools/hash-id、jsc-gitea/tools/gitea.sh wiki-url、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/wiki-contents.sh upsert（目錄頁自己那個區塊）、jsc-gitea:wiki、jsc-ask:ask、templates/tooling-page.md、templates/tooling-contents.md |
|
||||
| 完成條件 | 每項事實都指得到來源檔案或工具輸出、必填章節都不是空的、收尾回報寫明交付目標、來源新鮮度、過期輸入與未知的 hook 判定；目標是 wiki 時每一頁都確認寫成功，或列為未寫入並附完整內容、寫進區塊的每個連結都經 link-check.sh 退出 0、每支偵測到的 CLI 的 wiki-contents.sh upsert 都退出 0；每一種交付目標都要寫下本次的 skill-end 事件，或據實記成腳本不在這台機器上 |
|
||||
| 可驗證跡象 | $JSC_HOME/usage/events.jsonl 多一行 kind=skill、phase=end、name=jsc-meta:tooling-guide 的 skill-end 事件，那是這支唯讀技能唯一的寫入跡象；目標是聊天回應時除了那一行沒有其他寫入跡象，只有回報內容；目標是檔案時另外只產生使用者指定的那一個檔；目標是 wiki 時每支偵測到的 CLI 各一頁 TOOLING_{HASH}，並由 wiki-contents.sh upsert 退出 0 在 TOOLING_CONTENTS 留下自己那一個 `## TOOLING_{HASH}` 區塊、區塊裡以 `- 盤點頁：[TOOLING_{HASH}]({連結})` 的絕對網址指向該內容頁，別台機器與別支 CLI 的區塊原樣保留 |
|
||||
|
||||
@@ -397,7 +397,7 @@ kiro 是唯一真的擋不了的，verdict 據實寫 `degraded`，不寫 `wired`
|
||||
| `TOOLING` | `TOOLING_CONTENTS` | `TOOLING_{HASH}` | 技能盤點目錄、單機單 CLI 的技能盤點頁：一台機器上某一支 CLI 的已安裝 plugin 與版本、可用技能、hook 接線狀態 | jsc-meta |
|
||||
| `MONITOR` | `MONITOR_CONTENTS` | `MONITOR_{HASH}` | 助理巡檢的監控頁。技能與 hook 每跑一次就留下事件，助理把事件收攏、判斷健康狀態、寫進這裡 | jsc-assist |
|
||||
|
||||
`MAINTAIN` 沒有內容頁。維護登記全部寫在 `MAINTAIN_CONTENTS` 的表格裡：`jsc-sdlc:implement` 只往那一頁附加登記，`jsc-sdlc:maintain` 只讀那一頁再回寫「前次維護時間」，兩支都沒有產生 `MAINTAIN_{HASH}` 的步驟，`jsc-sdlc/templates/` 也沒有對應範本。總表以前列著這個內容頁，照著找只會找到一個不存在的頁。要補內容頁就先補技能步驟與範本，不能只在總表上寫著。
|
||||
`MAINTAIN` 沒有內容頁。維護登記全部寫在 `MAINTAIN_CONTENTS` 的條列區塊上，一個專案一個 H2 區塊：`jsc-sdlc:implement` 只往那一頁附加登記，`jsc-sdlc:maintain` 只讀那一頁再回寫「前次維護時間」，兩支都沒有產生 `MAINTAIN_{HASH}` 的步驟，`jsc-sdlc/templates/` 也沒有對應範本。總表以前列著這個內容頁，照著找只會找到一個不存在的頁。要補內容頁就先補技能步驟與範本，不能只在總表上寫著。
|
||||
|
||||
### 目錄頁專用存取庫
|
||||
|
||||
@@ -408,12 +408,13 @@ kiro 是唯一真的擋不了的，verdict 據實寫 `degraded`，不寫 `wired`
|
||||
| 頁名 | `{TYPE}_CONTENTS` | `{TYPE}_{HASH}` |
|
||||
| 存取庫解析 | 一律解 `CONTENTS`：`JSC_WIKI_REPO_CONTENTS` → `JSC_WIKI_REPO` → exit 3 | 解自己的型別：`JSC_WIKI_REPO_{TYPE}` → `JSC_WIKI_REPO` → exit 3 |
|
||||
| 帶雜湊 | 否 | 是 |
|
||||
| 版面 | 大標題加條列：一筆一個 H2 區塊，欄位一行一條，不留 markdown 表格 | 圖表優先：mermaid 與表格優於散文 |
|
||||
|
||||
`CONTENTS` 因此是第十五種頁面類型，而且是唯一一種自己沒有頁的：沒有 `CONTENTS_CONTENTS`，也沒有 `CONTENTS_{HASH}`。
|
||||
它只用來解存取庫，`gitea.sh wiki-repo CONTENTS` 是全部目錄頁的解析入口。
|
||||
總表列的十四種是頁的分類，`CONTENTS` 是存取庫的分類，兩張清單長度不同是正常的。
|
||||
|
||||
四條規則，寫入前逐條核對：
|
||||
五條規則，寫入前逐條核對：
|
||||
|
||||
1. 任何 `*_CONTENTS` 頁都走 `gitea.sh wiki-repo CONTENTS`，十四種型別的目錄頁全部落在同一個存取庫。
|
||||
2. 目錄頁的解析鏈**不退回型別變數**。設了 `JSC_WIKI_REPO_LOG` 不會讓 `LOG_CONTENTS` 跟著搬過去。
|
||||
@@ -425,9 +426,19 @@ kiro 是唯一真的擋不了的，verdict 據實寫 `degraded`，不寫 `wired`
|
||||
|
||||
**為什麼驗證走 API，不看網頁狀態碼。** 私有存取庫的網頁網址對未登入請求一律回 404。拿網頁狀態碼判斷，會把還在的頁判成死連結，接著整批被刪掉或改寫。金鑰失效那一種也要與死連結分開回報，理由一樣：一次金鑰過期就會把整批好頁判成壞的。
|
||||
|
||||
5. **目錄頁一律「大標題加條列」，內容頁才維持圖表優先。** 這條區分是全技能組的判準，每支技能寫 wiki 前先看自己寫的是哪一種頁。
|
||||
|
||||
目錄頁的版面固定三段：H1 頁名、`>` 引言、然後每一筆紀錄一個 H2 區塊。H2 標題就是那一筆的鍵，寫成對應的**內容頁頁名** `{TYPE}_{HASH}`，標題不放連結、不放網址、不加前後綴、不加日期。欄位在標題底下一行一條，格式 `- {欄位名}：{值}`，全形冒號，順序照原欄位從左到右，一欄一條，鍵那一欄照樣留一條，資料才不會少。區塊之間空一行，H2 與第一條之間空一行。**目錄頁不留任何 markdown 表格**，也不放 mermaid。舊頁還是表格時由 `jsc-gitea/tools/wiki-contents.sh` 讀到就自動轉成條列後寫回，不另跑批次搬移，也不得手工搬。
|
||||
|
||||
**`<key-col>` 怎麼決定：照線上那一頁實際的欄位排法，不是照範本。** `wiki-contents.sh upsert <TYPE> <key-col> <key> <entry-file> [template-file]` 的 `<key-col>` 填的是**舊表格裡持有「內容頁連結」那一欄的序號**，只在舊頁還是表格、需要自動轉檔時才用得到：轉檔時工具從那一欄的連結網址取最後一段路徑當 H2 標題。序號一律先把線上那一頁讀回來（`gitea.sh wiki-get {CONTENTS 存取庫} {TYPE}_CONTENTS`）、看連結實際落在第幾欄再填。**不得照 `templates/` 裡的欄位排法推**：範本的欄位順序與線上那一頁常常不一樣，自動轉檔跑的是線上那一頁。填錯欄的後果是靜默的——標題會轉成那一欄的純文字（例如 `plugins/ask`），跟鍵 `{TYPE}_{HASH}` 對不上，既有那一筆被當成新的附加到頁尾，同一筆變兩個區塊，舊區塊從此再也更新不到，而且不會有任何錯誤訊息。線上是空頁、沒有舊表格要轉時，這個參數影響不到結果，照範本填即可。
|
||||
|
||||
內容頁反過來：**圖表優先，mermaid 與表格優於散文**，這一條只針對內容頁，繼續有效。
|
||||
|
||||
**為什麼分兩種。** 目錄頁是索引，每一筆的欄位一樣多、只給人挑一筆點進去；表格一寬就得橫向捲，欄位一多就對不上表頭，而且併行寫入時只要有人少打一根豎線，整張表就散掉，別人那一筆跟著看不見。條列式一筆一個區塊，寫入端只換自己那一塊，壞掉也只壞自己那一塊。內容頁要的是另一件事：一頁講一件事的全貌，流程與比較拿圖表最省讀者的力氣，所以圖表優先留在內容頁。
|
||||
|
||||
**為什麼要分開。** 目錄頁是全部使用者共用的索引，內容頁按專案或機器分散在各自的存取庫。混在一起的話，換一個專案就換一份索引，「這台機器有哪些頁」永遠問不到完整答案。索引集中一處、內容各自落地，才查得到全貌。
|
||||
|
||||
代價寫明：跨存取庫沒有原子性。內容頁寫成功、目錄頁寫失敗時，據實回報未寫入的目錄列與完整內容，不得反過來先寫目錄頁。
|
||||
代價寫明：跨存取庫沒有原子性。內容頁寫成功、目錄頁寫失敗時，據實回報那個沒寫進去的目錄頁區塊與完整內容，不得反過來先寫目錄頁。
|
||||
|
||||
`{HASH}` 一律為 `{owner}/{repo}`（必要時加上主題字串）的**完整 SHA-1**，40 碼十六進位，`a-f` 一律轉大寫。
|
||||
不截短、不加前綴：截短過的舊頁名以 `jsc-gitea/tools/migrate-wiki.sh` 遷移。
|
||||
@@ -485,6 +496,8 @@ kiro 是唯一真的擋不了的，verdict 據實寫 `degraded`，不寫 `wired`
|
||||
- [ ] gitea 操作透過 gitea.sh 或 tea
|
||||
- [ ] wiki repo 與 Gitea 認證先讀目前 shell 繼承的環境變數；只有缺值或無法解析時才詢問；頁面類型不得跨用其他 `JSC_WIKI_REPO_{TYPE}`
|
||||
- [ ] 目錄頁一律解 `CONTENTS` 存取庫（`gitea.sh wiki-repo CONTENTS`），內容頁解自己的型別；所有連結一律寫成 `[{文字}]({連結})`，網址取自 `gitea.sh wiki-url`，不用 `[[頁名]]`
|
||||
- [ ] 目錄頁寫成「大標題加條列」：一筆一個 H2 區塊、標題是內容頁頁名 `{TYPE}_{HASH}`、欄位一行一條 `- {欄位名}：{值}`、頁上沒有 markdown 表格；內容頁維持圖表優先（mermaid 與表格優於散文）。技能內文與 `templates/` 的目錄頁樣板都照這一條，寫入一律走 `jsc-gitea/tools/wiki-contents.sh upsert`，不手工改頁。規則見「目錄頁專用存取庫」第 5 條
|
||||
- [ ] `wiki-contents.sh upsert` 的 `<key-col>` 是「舊表格裡持有內容頁連結那一欄的序號」，只供自動轉檔用；序號照**線上那一頁實際的欄位排法**填，先把線上頁讀回來確認，不照 `templates/` 的欄位排法推。規則見「目錄頁專用存取庫」第 5 條的 `<key-col>` 段
|
||||
- [ ] 文件裡的連結都經過 `jsc-gitea/tools/link-check.sh` 驗證（結束碼 0 才寫入）且格式為 `[{文字}]({連結})`；`tools/check-link-format.sh {domain-path}` 對該 domain 退出 0，退出 3 是「什麼都沒掃」，不算通過
|
||||
- [ ] 頁名樣式三處一致：`jsc-gitea/tools/page-name.sh`（正本）、`jsc-hooks/hooks/comment-scope.sh`、`jsc-log/tools/worklog-pending.sh`，`tools/check-page-name.sh {root}` 退出 0；退出 3 是「什麼都沒查」，不算通過。三處刻意不共用函式，因為 hook 必須自足，不得在執行期相依別的 plugin 路徑
|
||||
- [ ] 問詢透過 jsc-ask 決策樹規則
|
||||
|
||||
+12
-12
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: skill-check
|
||||
description: Routine compliance, script, hook, flow-efficiency, and cost-efficiency audit of the whole jsc skill set with no change request in hand. Sync every domain repo from the Gitea canonical marketplace, then run three parallel groups - lint-scripts.sh plus lint-frontmatter.sh plus check-behaviors.sh plus ste100-lint.sh plus check-link-format.sh plus check-wiki-rules.sh plus check-page-name.sh plus hook smoke, the guidelines.md checklist audit, and an optimization review that first reads each domain's SKILLSET_{HASH} so suggestions already applied or deferred are never re-scanned or re-asked, then covers parallelism, tool extraction, repeated interaction, redundant checks, misplaced gates, and avoidable token, sub-agent, API, scan, or interaction cost. Confirm compliance fixes and optimization suggestions before applying them, recording each decision with its date, re-check until accepted fixes pass, then open a PR per affected repo via jsc-git pr. Close by appending the round's result to every changed domain's SKILLSET_{HASH} and its SKILLSET_CONTENTS row, or to the plugins/meta page when no domain was changed. Use for periodic or on-demand skill-set checks; not for applying a change request (use skillset-update) or editing one skill (use skill-update).
|
||||
description: Routine compliance, script, hook, flow-efficiency, and cost-efficiency audit of the whole jsc skill set with no change request in hand. Sync every domain repo from the Gitea canonical marketplace, then run three parallel groups - lint-scripts.sh plus lint-frontmatter.sh plus check-behaviors.sh plus ste100-lint.sh plus check-link-format.sh plus check-wiki-rules.sh plus check-page-name.sh plus hook smoke, the guidelines.md checklist audit, and an optimization review that first reads each domain's SKILLSET_{HASH} so suggestions already applied or deferred are never re-scanned or re-asked, then covers parallelism, tool extraction, repeated interaction, redundant checks, misplaced gates, and avoidable token, sub-agent, API, scan, or interaction cost. Confirm compliance fixes and optimization suggestions before applying them, recording each decision with its date, re-check until accepted fixes pass, then open a PR per affected repo via jsc-git pr. Close by appending the round's result to every changed domain's SKILLSET_{HASH} and its SKILLSET_CONTENTS block, or to the plugins/meta page when no domain was changed. Use for periodic or on-demand skill-set checks; not for applying a change request (use skillset-update) or editing one skill (use skill-update).
|
||||
---
|
||||
|
||||
# skill-check — audit compliance, flow efficiency, and cost efficiency
|
||||
@@ -94,14 +94,14 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
- **Which page.** For every domain repo actually changed in this round, resolve `gitea.sh wiki-repo SKILLSET` and append one section to `SKILLSET_` plus `gitea.sh hash-id "{owner}/{repo}"` of that domain repo. Append; never overwrite — the page accumulates every change that domain has ever seen.
|
||||
- **When nothing changed.** No domain repo changed in this round means one page, hashed from `plugins/meta`, gets one section recording 「本輪無發現」 with the group verdicts that produced that conclusion. A round that found nothing still has to leave the evidence that it ran.
|
||||
- **What each section holds.** The layout is [`../../templates/skillset-page.md`](../../templates/skillset-page.md): date, change type `skill-check`, the change request in one sentence, the skills touched, the files changed, the PR URL from step 7, the deploy-route verdict and the verification result. The `skill-check` section additionally carries the 優化建議 table, every row filled including 決議 and 決議日期 — that table is exactly what the next round reads in step 2's group 3.
|
||||
- **Directory page.** Refresh that page's row in `SKILLSET_CONTENTS` with `jsc-gitea/tools/wiki-contents.sh` — never by hand, and never through `jsc-gitea:wiki`. Build one file holding the single row from [`../../templates/skillset-contents.md`](../../templates/skillset-contents.md), then run:
|
||||
- **Directory page.** Refresh that page's own block in `SKILLSET_CONTENTS` with `jsc-gitea/tools/wiki-contents.sh` — never by hand, and never through `jsc-gitea:wiki`. That page is a heading-plus-bullets list and holds no markdown table: one `## SKILLSET_{HASH}` block per domain repo, every field one `- {欄位名}：{值}` line under it. Build one file holding this domain's single block, following [`../../templates/skillset-contents.md`](../../templates/skillset-contents.md), then run:
|
||||
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "{owner}/{repo}" {row file} templates/skillset-contents.md`
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" {entry file} templates/skillset-contents.md`
|
||||
|
||||
The key column is `2`, the 存取庫 column, and the key is that domain repo's `{owner}/{repo}` written exactly as the row file writes it; the string is the same every round, so one domain keeps exactly one row. The script resolves the CONTENTS repo itself — the directory page lives there, never in the SKILLSET repo — reads the whole page, replaces the row whose key column matches, appends when none matches, and writes the page back, so every row owned by another domain stays as it was.
|
||||
The key is the H2 heading `SKILLSET_{HASH}`, and that page name depends only on the domain repo's `{owner}/{repo}`, so it reads the same every round and one domain keeps exactly one block. The `2` is the key column: the index of the column that held the content-page link in the **old markdown table**, and it matters only when such an old table still has to be converted automatically — the conversion takes the last path segment of that column's link URL as the H2 heading. Count that index from the **live page's own column layout**, never from the template's: the live `SKILLSET_CONTENTS` reads `| 存放庫 | 異動報告 | 目前版本 | 最後更新 |`, so the link sits in column 2 while column 1 is plain text like `plugins/ask`. Passing `1` would make the heading `plugins/ask`, which never matches the key `SKILLSET_{HASH}`, so the existing entry is appended as a brand-new one — one domain ends up with two blocks and the older one is never updated again. The fourth argument is the whole block, not a table row. The script resolves the CONTENTS repo itself — the directory page lives there, never in the SKILLSET repo — reads the whole page, converts any leftover table to blocks, replaces the block whose heading matches, appends when none matches, and writes the page back, so every block owned by another domain stays as it was.
|
||||
|
||||
The 異動頁 cell is written as `[SKILLSET_{HASH}]({url})`, the URL being the **absolute** one from `gitea.sh wiki-url {SKILLSET repo} SKILLSET_{HASH}`. Every link on both pages takes that `[{text}]({url})` form — the double-bracket wiki-link form is never used, because it resolves only inside one wiki. Fetch that URL only after the content page is written: **write the content page first** — a directory row naming a page whose write failed is worse than a missing row.
|
||||
- **Check the links before writing.** Hand every URL going onto the content page and into the directory row to `jsc-gitea/tools/link-check.sh` and write only when it exits 0. It verifies through the Gitea API, never a web status code: a private repo answers 404 to an unauthenticated web request, so a status-code check would call a live page dead and rewrite pages that are fine.
|
||||
The 異動頁 bullet is written as `[SKILLSET_{HASH}]({url})`, the URL being the **absolute** one from `gitea.sh wiki-url {SKILLSET repo} SKILLSET_{HASH}`; the H2 heading itself carries no link, no URL, no affix and no date. Every link on both pages takes that `[{text}]({url})` form — the double-bracket wiki-link form is never used, because it resolves only inside one wiki. Fetch that URL only after the content page is written: **write the content page first** — a directory block naming a page whose write failed is worse than a missing block.
|
||||
- **Check the links before writing.** Hand every URL going onto the content page and into the directory block to `jsc-gitea/tools/link-check.sh` and write only when it exits 0. It verifies through the Gitea API, never a web status code: a private repo answers 404 to an unauthenticated web request, so a status-code check would call a live page dead and rewrite pages that are fine.
|
||||
- **Exit codes.** Route every one of them. None of these calls may be read as success by default.
|
||||
|
||||
| Call | Exit | Do |
|
||||
@@ -113,23 +113,23 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
| Content page read | 0 | Append into the sections already there |
|
||||
| | 4 | The page does not exist yet, so build it from the template |
|
||||
| | 7 or 8 | Stop and write nothing, because a page rebuilt on top of an unread read loses every section already on it |
|
||||
| `gitea.sh wiki-url` | 4 | The content page is not there, so the write above did **not** succeed. Go back and write it; put no directory row in until the page exists, because a row may not name a page that failed |
|
||||
| `gitea.sh wiki-url` | 4 | The content page is not there, so the write above did **not** succeed. Go back and write it; put no directory block in until the page exists, because a block may not name a page that failed |
|
||||
| | 5 | The API answered with no `html_url`. Stop and report it; never assemble the URL by hand from the host and the page name |
|
||||
| `link-check.sh` | 0 | Every link is reachable. Write the page |
|
||||
| | 1 | At least one link is dead. Write nothing, and report the `DEAD` lines it printed |
|
||||
| | 2 | No URL was passed, which is a defect here. Pass the links and rerun |
|
||||
| | 3 | `GITEA_HOST` is unset. Set it and rerun; never skip the check instead |
|
||||
| | 7 | Gitea authentication failed. Stop and report the key problem, and never read it as a dead link |
|
||||
| `wiki-contents.sh upsert` | 0 | The row is in place. Report the `updated` or `added` it printed, with the page it named |
|
||||
| | 1 | The write failed, or the directory page holds no markdown table. Report `SKILLSET_CONTENTS` as not written, together with the row content |
|
||||
| `wiki-contents.sh upsert` | 0 | The block is in place. Report the `updated` or `added` it printed, with the page it named |
|
||||
| | 1 | The page content could not be assembled, or the write failed. A page with no matching block is not an error — that case appends. Report `SKILLSET_CONTENTS` as not written, together with the block content |
|
||||
| | 2 | An argument was rejected. Fix it and rerun; nothing was written |
|
||||
| | 3 | No CONTENTS wiki repo is configured. Report `JSC_WIKI_REPO_CONTENTS` and `JSC_WIKI_REPO` as the two variables to set. The round's section is on `SKILLSET_{HASH}` and stays there |
|
||||
| | 4 | The directory page is absent and no template was passed. Rerun with `templates/skillset-contents.md` as the fifth argument |
|
||||
| | 7 | The token is invalid or lacks permission, so the other domains' rows are unknown. Stop, report the token problem, and create no page — writing nothing is what keeps those rows alive |
|
||||
| | 7 | The token is invalid or lacks permission, so the other domains' blocks are unknown. Stop, report the token problem, and create no page — writing nothing is what keeps those blocks alive |
|
||||
| | 8 | Some other API failure. Stop, report that status, and create no page |
|
||||
- **On a failed write.** Retry once. Still failing, hand the user the page name and the full section that was not written, so the round's result is not lost. **Never close the run reporting a page as written when it was not**, and never close it silently with the content only in the transcript.
|
||||
|
||||
Completion condition: every changed domain repo has one new section on its `SKILLSET_{HASH}` and one row in `SKILLSET_CONTENTS` written by a `wiki-contents.sh upsert` that exited 0, or — where nothing changed — the `plugins/meta` page carries the 「本輪無發現」 section and its row on the same terms; every content-page write is confirmed by a successful read-back or reported as not written with its full content handed back.
|
||||
Completion condition: every changed domain repo has one new section on its `SKILLSET_{HASH}` and one `## SKILLSET_{HASH}` block in `SKILLSET_CONTENTS` written by a `wiki-contents.sh upsert` that exited 0, or — where nothing changed — the `plugins/meta` page carries the 「本輪無發現」 section and its block on the same terms; every content-page write is confirmed by a successful read-back or reported as not written with its full content handed back.
|
||||
9. Report this round's outcome to the local event stream — the last step of every run, the ones that stop early included. Run:
|
||||
|
||||
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-check {status} {exit code} [detail]`
|
||||
@@ -143,7 +143,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
| `ok` | every domain ended with a complete checklist, every accepted fix passed its re-check, every affected repo has a PR URL, and every wiki write exited 0 |
|
||||
| `blocked` | a gate or a missing prerequisite stopped the round before anything was audited — `sync-domains.sh` never reached exit 0, or the call itself was refused |
|
||||
| `failed` | the round broke mid-way — a re-check in step 6 kept failing, or a wiki write failed again after its one retry |
|
||||
| `degraded` | the round finished with a part missing — a domain carries 「本輪未取得已決議清單，優化建議暫不提出」, or a content page was written while its `SKILLSET_CONTENTS` row was not |
|
||||
| `degraded` | the round finished with a part missing — a domain carries 「本輪未取得已決議清單，優化建議暫不提出」, or a content page was written while its `SKILLSET_CONTENTS` block was not |
|
||||
| `aborted` | the user stopped the round, or a prerequisite turned out not to hold and this skill stopped on its own |
|
||||
|
||||
`{exit code}` is this round's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
|
||||
|
||||
@@ -36,12 +36,12 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
On any mismatch — the deleted skill still listed, a leftover from exit 1, a fixed caller that now fails, a prompt failure, or unexpected stderr — fix the cause and rerun this step from 8.1. Completion condition: the skill is absent from the list, the verification script exits 0 or its exit 3 is reported as「無處可查」and carried into step 8.3, every fixed caller ran, every checkable CLI completed the prompt with the expected result, and every untestable CLI has a stated reason.
|
||||
3. Write the change report to the wiki — this part MUST run as a sub agent. It is two pages in two repos, and they must not be mixed up.
|
||||
- **Content page `SKILLSET_{HASH}`.** Resolve its repo with `jsc-gitea/tools/gitea.sh wiki-repo SKILLSET`, which reads `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. `{HASH}` is `gitea.sh hash-id "{owner}/{repo}"` of the domain repo that lost the skill, used at the full 40 characters it prints. Write it through `jsc-gitea:wiki` following [`../../templates/skillset-page.md`](../../templates/skillset-page.md): **append** a section for this change — date, 「刪除」, skill name, changed files (the step 5 inventory verdicts included), PR URL, the step 8.1 route verdict and the step 8.2 verification result per item, the deep-delete verdict「無處可查」included when it applies — and keep every earlier section.
|
||||
- **Directory page `SKILLSET_CONTENTS`.** It lives in the CONTENTS repo, never in the SKILLSET one. `wiki-contents.sh` resolves it itself with `gitea.sh wiki-repo CONTENTS`, whose chain is `JSC_WIKI_REPO_CONTENTS` then `JSC_WIKI_REPO` and never falls back to `JSC_WIKI_REPO_SKILLSET`. Build one file holding the single row from [`../../templates/skillset-contents.md`](../../templates/skillset-contents.md), its 異動頁 cell written as `[SKILLSET_{HASH}]({url})` with the **absolute** URL from `gitea.sh wiki-url {SKILLSET repo} SKILLSET_{HASH}`. Every link on both pages takes that `[{text}]({url})` form; the double-bracket wiki-link form resolves only inside one wiki, so it is never used. Then run:
|
||||
- **Directory page `SKILLSET_CONTENTS`.** It lives in the CONTENTS repo, never in the SKILLSET one. `wiki-contents.sh` resolves it itself with `gitea.sh wiki-repo CONTENTS`, whose chain is `JSC_WIKI_REPO_CONTENTS` then `JSC_WIKI_REPO` and never falls back to `JSC_WIKI_REPO_SKILLSET`. That page is a heading-plus-bullets list and holds no markdown table: one `## SKILLSET_{HASH}` block per domain repo, every field one `- {欄位名}：{值}` line under it. Build one file holding this domain's single block, following [`../../templates/skillset-contents.md`](../../templates/skillset-contents.md), with its 異動頁 bullet written as `[SKILLSET_{HASH}]({url})` from the **absolute** URL that `gitea.sh wiki-url {SKILLSET repo} SKILLSET_{HASH}` prints. The H2 heading itself carries no link, no URL, no affix and no date — only the content page name. Every link on both pages takes that `[{text}]({url})` form; the double-bracket wiki-link form resolves only inside one wiki, so it is never used. Then run:
|
||||
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "{owner}/{repo}" {row file} templates/skillset-contents.md`
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" {entry file} templates/skillset-contents.md`
|
||||
|
||||
The key column is `2`, the 存取庫 column, holding that repo's `{owner}/{repo}` exactly as the row file writes it, so one domain keeps exactly one row and no other domain's row moves. Never hand-edit the directory page. Write the content page first and fetch the URL only after it exists.
|
||||
- **Check the links before writing.** Hand every URL going onto the content page and into the directory row to `jsc-gitea/tools/link-check.sh`, and write only when it exits 0. It verifies through the Gitea API, never a web status code: a private repo answers 404 to an unauthenticated web request, so a status-code check would call a live page dead.
|
||||
The key is the H2 heading `SKILLSET_{HASH}`, so one domain keeps exactly one block and no other domain's block moves. That page name depends only on `{owner}/{repo}`, which is why it is the key: a host rename or a changed `JSC_WIKI_REPO_SKILLSET` leaves it untouched, so the match still finds the existing block. The `2` is the key column: the index of the column that held the content-page link in the **old markdown table**, and it matters only when such an old table still has to be converted automatically — the conversion takes the last path segment of that column's link URL as the H2 heading. Count that index from the **live page's own column layout**, never from the template's: the live `SKILLSET_CONTENTS` reads `| 存放庫 | 異動報告 | 目前版本 | 最後更新 |`, so the link sits in column 2 while column 1 is plain text like `plugins/ask`. Passing `1` would make the heading `plugins/ask`, which never matches the key `SKILLSET_{HASH}`, so the existing entry is appended as a brand-new one — one domain ends up with two blocks and the older one is never updated again. The fourth argument is the whole block, not a table row. Never hand-edit the directory page. Write the content page first and fetch the URL only after it exists.
|
||||
- **Check the links before writing.** Hand every URL going onto the content page and into the directory block to `jsc-gitea/tools/link-check.sh`, and write only when it exits 0. It verifies through the Gitea API, never a web status code: a private repo answers 404 to an unauthenticated web request, so a status-code check would call a live page dead.
|
||||
- **Exit codes.** Route every one of them:
|
||||
|
||||
| Call | Exit | Do |
|
||||
@@ -53,22 +53,22 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
| Content page read | 0 | Append into the sections already there |
|
||||
| | 4 | The page does not exist yet, so build it from `templates/skillset-page.md` |
|
||||
| | 7 or 8 | Stop and write nothing: a page rebuilt on top of an unread read loses every section already on it |
|
||||
| `gitea.sh wiki-url` | 4 | The content page is not there, so the write above did **not** succeed. Go back and write it, and add no directory row until the page exists |
|
||||
| `gitea.sh wiki-url` | 4 | The content page is not there, so the write above did **not** succeed. Go back and write it, and add no directory block until the page exists |
|
||||
| | 5 | The API answered with no `html_url`. Stop and report it; never assemble the URL by hand from the host and the page name |
|
||||
| `link-check.sh` | 0 | Every link is reachable. Write the page |
|
||||
| | 1 | At least one link is dead. Write nothing, and report the `DEAD` lines it printed |
|
||||
| | 2 | No URL was passed, which is a defect here. Pass the links and rerun |
|
||||
| | 3 | `GITEA_HOST` is unset. Set it and rerun; never skip the check instead |
|
||||
| | 7 | Gitea authentication failed. Stop and report the key problem, and never read it as a dead link |
|
||||
| `wiki-contents.sh upsert` | 0 | The row is in place. Report the `updated` or `added` it printed |
|
||||
| | 1 | The write failed. Report `SKILLSET_CONTENTS` as not written, together with the row content |
|
||||
| `wiki-contents.sh upsert` | 0 | The block is in place. Report the `updated` or `added` it printed |
|
||||
| | 1 | The page content could not be assembled, or the write failed. Report `SKILLSET_CONTENTS` as not written, together with the block content |
|
||||
| | 2 | An argument was rejected. Fix it and rerun; nothing was written |
|
||||
| | 3 | No CONTENTS wiki repo is configured. Report `JSC_WIKI_REPO_CONTENTS` and `JSC_WIKI_REPO` as the two variables to set; the new section is on `SKILLSET_{HASH}` and stays there |
|
||||
| | 4 | The directory page is absent and no template was passed. Rerun with `templates/skillset-contents.md` as the fifth argument |
|
||||
| | 7 | The token is invalid or lacks permission, so the other domains' rows are unknown. Stop, report the token problem, and create no page |
|
||||
| | 7 | The token is invalid or lacks permission, so the other domains' blocks are unknown. Stop, report the token problem, and create no page |
|
||||
| | 8 | Some other API failure. Stop, report that status, and create no page |
|
||||
|
||||
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's row on `SKILLSET_CONTENTS` linking that page by absolute URL.
|
||||
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's `## SKILLSET_{HASH}` block on `SKILLSET_CONTENTS` linking that page by absolute URL.
|
||||
9. Report this run's outcome to the local event stream — the last step of every run, the ones that stop early included. Run:
|
||||
|
||||
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-delete {status} {exit code} [detail]`
|
||||
@@ -82,7 +82,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
| `ok` | the skill directory and its behavior-list section are gone, the PR is open, `deploy-verify.md` sections 1 to 5 hold, `verify-skill-removed.sh` exited 0, and both wiki writes exited 0 |
|
||||
| `blocked` | a gate or a missing prerequisite stopped the run before any file changed — `sync-domains.sh` never reached exit 0, or no skill could be listed to pick from |
|
||||
| `failed` | the run broke mid-way — a leftover from `verify-skill-removed.sh` exit 1 could not be removed, or a wiki write failed again after its one retry |
|
||||
| `degraded` | the deletion landed with a part missing — the deep-delete check came back 「無處可查」, or the content page was written while its `SKILLSET_CONTENTS` row was not |
|
||||
| `degraded` | the deletion landed with a part missing — the deep-delete check came back 「無處可查」, or the content page was written while its `SKILLSET_CONTENTS` block was not |
|
||||
| `aborted` | the user stopped the run, or a prerequisite turned out not to hold and this skill stopped on its own |
|
||||
|
||||
`{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
|
||||
|
||||
+10
-10
@@ -45,12 +45,12 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
1. Follow [`../../references/deploy-verify.md`](../../references/deploy-verify.md) from section 1 to section 5: `tools/deploy-route.sh {domain-path}` picks the route, the deploy route or the worktree route runs, and the verification then runs in a **fresh CLI process**, never in the session that ran the deploy. That session raised the restart gate itself and still holds the old skill body, so verifying inside it either gets blocked or passes on stale behavior. Verify the added skill's row in `tools/list-skills.sh`, every tool the skill added, and one minimal prompt per checkable CLI — the per-CLI prompts run in parallel. Completion condition: every completion condition in `deploy-verify.md` sections 1 to 5 holds for this domain repo.
|
||||
2. Write the change report to the wiki — this part MUST run as a sub agent. It is two pages in two repos, and they must not be mixed up.
|
||||
- **Content page `SKILLSET_{HASH}`.** Resolve its repo with `jsc-gitea/tools/gitea.sh wiki-repo SKILLSET`, which reads `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. `{HASH}` is `gitea.sh hash-id "{owner}/{repo}"` of the domain repo that gained the skill, used at the full 40 characters it prints. Write it through `jsc-gitea:wiki` following [`../../templates/skillset-page.md`](../../templates/skillset-page.md): **append** a section for this change — date, 「新增」, skill name, changed files, PR URL, the step 6.1 route verdict and verification result per item — and keep every earlier section.
|
||||
- **Directory page `SKILLSET_CONTENTS`.** It lives in the CONTENTS repo, never in the SKILLSET one. `wiki-contents.sh` resolves it itself with `gitea.sh wiki-repo CONTENTS`, whose chain is `JSC_WIKI_REPO_CONTENTS` then `JSC_WIKI_REPO` and never falls back to `JSC_WIKI_REPO_SKILLSET`. Build one file holding the single row from [`../../templates/skillset-contents.md`](../../templates/skillset-contents.md), its 異動頁 cell written as `[SKILLSET_{HASH}]({url})` with the **absolute** URL from `gitea.sh wiki-url {SKILLSET repo} SKILLSET_{HASH}`. Every link on both pages takes that `[{text}]({url})` form; the double-bracket wiki-link form resolves only inside one wiki, so it is never used. Then run:
|
||||
- **Directory page `SKILLSET_CONTENTS`.** It lives in the CONTENTS repo, never in the SKILLSET one. `wiki-contents.sh` resolves it itself with `gitea.sh wiki-repo CONTENTS`, whose chain is `JSC_WIKI_REPO_CONTENTS` then `JSC_WIKI_REPO` and never falls back to `JSC_WIKI_REPO_SKILLSET`. That page is a heading-plus-bullets list and holds no markdown table: one `## SKILLSET_{HASH}` block per domain repo, every field one `- {欄位名}：{值}` line under it. Build one file holding this domain's single block, following [`../../templates/skillset-contents.md`](../../templates/skillset-contents.md), with its 異動頁 bullet written as `[SKILLSET_{HASH}]({url})` from the **absolute** URL that `gitea.sh wiki-url {SKILLSET repo} SKILLSET_{HASH}` prints. The H2 heading itself carries no link, no URL, no affix and no date — only the content page name. Every link on both pages takes that `[{text}]({url})` form; the double-bracket wiki-link form resolves only inside one wiki, so it is never used. Then run:
|
||||
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "{owner}/{repo}" {row file} templates/skillset-contents.md`
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" {entry file} templates/skillset-contents.md`
|
||||
|
||||
The key column is `2`, the 存取庫 column, holding that repo's `{owner}/{repo}` exactly as the row file writes it, so one domain keeps exactly one row and no other domain's row moves. Never hand-edit the directory page. Write the content page first and fetch the URL only after it exists.
|
||||
- **Check the links before writing.** Hand every URL going onto the content page and into the directory row to `jsc-gitea/tools/link-check.sh`, and write only when it exits 0. It verifies through the Gitea API, never a web status code: a private repo answers 404 to an unauthenticated web request, so a status-code check would call a live page dead.
|
||||
The key is the H2 heading `SKILLSET_{HASH}`, so one domain keeps exactly one block and no other domain's block moves. That page name depends only on `{owner}/{repo}`, which is why it is the key: a host rename or a changed `JSC_WIKI_REPO_SKILLSET` leaves it untouched, so the match still finds the existing block. The `2` is the key column: the index of the column that held the content-page link in the **old markdown table**, and it matters only when such an old table still has to be converted automatically — the conversion takes the last path segment of that column's link URL as the H2 heading. Count that index from the **live page's own column layout**, never from the template's: the live `SKILLSET_CONTENTS` reads `| 存放庫 | 異動報告 | 目前版本 | 最後更新 |`, so the link sits in column 2 while column 1 is plain text like `plugins/ask`. Passing `1` would make the heading `plugins/ask`, which never matches the key `SKILLSET_{HASH}`, so the existing entry is appended as a brand-new one — one domain ends up with two blocks and the older one is never updated again. The fourth argument is the whole block, not a table row. Never hand-edit the directory page. Write the content page first and fetch the URL only after it exists.
|
||||
- **Check the links before writing.** Hand every URL going onto the content page and into the directory block to `jsc-gitea/tools/link-check.sh`, and write only when it exits 0. It verifies through the Gitea API, never a web status code: a private repo answers 404 to an unauthenticated web request, so a status-code check would call a live page dead.
|
||||
- **Exit codes.** Route every one of them:
|
||||
|
||||
| Call | Exit | Do |
|
||||
@@ -62,22 +62,22 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
| Content page read | 0 | Append into the sections already there |
|
||||
| | 4 | The page does not exist yet, so build it from `templates/skillset-page.md` |
|
||||
| | 7 or 8 | Stop and write nothing: a page rebuilt on top of an unread read loses every section already on it |
|
||||
| `gitea.sh wiki-url` | 4 | The content page is not there, so the write above did **not** succeed. Go back and write it, and add no directory row until the page exists |
|
||||
| `gitea.sh wiki-url` | 4 | The content page is not there, so the write above did **not** succeed. Go back and write it, and add no directory block until the page exists |
|
||||
| | 5 | The API answered with no `html_url`. Stop and report it; never assemble the URL by hand from the host and the page name |
|
||||
| `link-check.sh` | 0 | Every link is reachable. Write the page |
|
||||
| | 1 | At least one link is dead. Write nothing, and report the `DEAD` lines it printed |
|
||||
| | 2 | No URL was passed, which is a defect here. Pass the links and rerun |
|
||||
| | 3 | `GITEA_HOST` is unset. Set it and rerun; never skip the check instead |
|
||||
| | 7 | Gitea authentication failed. Stop and report the key problem, and never read it as a dead link |
|
||||
| `wiki-contents.sh upsert` | 0 | The row is in place. Report the `updated` or `added` it printed |
|
||||
| | 1 | The write failed. Report `SKILLSET_CONTENTS` as not written, together with the row content |
|
||||
| `wiki-contents.sh upsert` | 0 | The block is in place. Report the `updated` or `added` it printed |
|
||||
| | 1 | The page content could not be assembled, or the write failed. Report `SKILLSET_CONTENTS` as not written, together with the block content |
|
||||
| | 2 | An argument was rejected. Fix it and rerun; nothing was written |
|
||||
| | 3 | No CONTENTS wiki repo is configured. Report `JSC_WIKI_REPO_CONTENTS` and `JSC_WIKI_REPO` as the two variables to set; the new section is on `SKILLSET_{HASH}` and stays there |
|
||||
| | 4 | The directory page is absent and no template was passed. Rerun with `templates/skillset-contents.md` as the fifth argument |
|
||||
| | 7 | The token is invalid or lacks permission, so the other domains' rows are unknown. Stop, report the token problem, and create no page |
|
||||
| | 7 | The token is invalid or lacks permission, so the other domains' blocks are unknown. Stop, report the token problem, and create no page |
|
||||
| | 8 | Some other API failure. Stop, report that status, and create no page |
|
||||
|
||||
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's row on `SKILLSET_CONTENTS` linking that page by absolute URL.
|
||||
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's `## SKILLSET_{HASH}` block on `SKILLSET_CONTENTS` linking that page by absolute URL.
|
||||
7. Report this run's outcome to the local event stream — the last step of every run, the ones that stop early included. Run:
|
||||
|
||||
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-new {status} {exit code} [detail]`
|
||||
@@ -91,7 +91,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
| `ok` | the new `SKILL.md` and its behavior-list section are in place, the checklist passes, the PR is open, `deploy-verify.md` sections 1 to 5 hold, and both wiki writes exited 0 |
|
||||
| `blocked` | a gate or a missing prerequisite stopped the run before any file was created — `sync-domains.sh` never reached exit 0, or Gitea refused the repository creation and nobody created it by hand |
|
||||
| `failed` | the run broke mid-way — `sync-marketplace.sh` or `sync-skill-manifest.sh` kept failing, or a wiki write failed again after its one retry |
|
||||
| `degraded` | the skill landed with a part missing — the content page was written while its `SKILLSET_CONTENTS` row was not, or a CLI could not be verified and the reason was recorded |
|
||||
| `degraded` | the skill landed with a part missing — the content page was written while its `SKILLSET_CONTENTS` block was not, or a CLI could not be verified and the reason was recorded |
|
||||
| `aborted` | the user stopped the run, or a prerequisite turned out not to hold and this skill stopped on its own |
|
||||
|
||||
`{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
|
||||
|
||||
@@ -20,12 +20,12 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
1. Follow [`../../references/deploy-verify.md`](../../references/deploy-verify.md) from section 1 to section 5: `tools/deploy-route.sh {domain-path}` picks the route, the deploy route or the worktree route runs, and the verification then runs in a **fresh CLI process**, never in the session that ran the deploy. That session raised the restart gate itself and still holds the old skill body, so verifying inside it either gets blocked or passes on stale behavior. Verify the updated `description` in the skill's `tools/list-skills.sh` row, every tool this change touched, and one minimal prompt per checkable CLI — the per-CLI prompts run in parallel. Completion condition: every completion condition in `deploy-verify.md` sections 1 to 5 holds for this domain repo.
|
||||
2. Write the change report to the wiki — this part MUST run as a sub agent. It is two pages in two repos, and they must not be mixed up.
|
||||
- **Content page `SKILLSET_{HASH}`.** Resolve its repo with `jsc-gitea/tools/gitea.sh wiki-repo SKILLSET`, which reads `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. `{HASH}` is `gitea.sh hash-id "{owner}/{repo}"` of the changed domain repo, used at the full 40 characters it prints. Write it through `jsc-gitea:wiki` following [`../../templates/skillset-page.md`](../../templates/skillset-page.md): **append** a section for this change — date, 「更新」, skill name, changed files, PR URL, the step 8.1 route verdict and verification result per item — and keep every earlier section.
|
||||
- **Directory page `SKILLSET_CONTENTS`.** It lives in the CONTENTS repo, never in the SKILLSET one. `wiki-contents.sh` resolves it itself with `gitea.sh wiki-repo CONTENTS`, whose chain is `JSC_WIKI_REPO_CONTENTS` then `JSC_WIKI_REPO` and never falls back to `JSC_WIKI_REPO_SKILLSET`. Build one file holding the single row from [`../../templates/skillset-contents.md`](../../templates/skillset-contents.md), its 異動頁 cell written as `[SKILLSET_{HASH}]({url})` with the **absolute** URL from `gitea.sh wiki-url {SKILLSET repo} SKILLSET_{HASH}`. Every link on both pages takes that `[{text}]({url})` form; the double-bracket wiki-link form resolves only inside one wiki, so it is never used. Then run:
|
||||
- **Directory page `SKILLSET_CONTENTS`.** It lives in the CONTENTS repo, never in the SKILLSET one. `wiki-contents.sh` resolves it itself with `gitea.sh wiki-repo CONTENTS`, whose chain is `JSC_WIKI_REPO_CONTENTS` then `JSC_WIKI_REPO` and never falls back to `JSC_WIKI_REPO_SKILLSET`. That page is a heading-plus-bullets list and holds no markdown table: one `## SKILLSET_{HASH}` block per domain repo, every field one `- {欄位名}：{值}` line under it. Build one file holding this domain's single block, following [`../../templates/skillset-contents.md`](../../templates/skillset-contents.md), with its 異動頁 bullet written as `[SKILLSET_{HASH}]({url})` from the **absolute** URL that `gitea.sh wiki-url {SKILLSET repo} SKILLSET_{HASH}` prints. The H2 heading itself carries no link, no URL, no affix and no date — only the content page name. Every link on both pages takes that `[{text}]({url})` form; the double-bracket wiki-link form resolves only inside one wiki, so it is never used. Then run:
|
||||
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "{owner}/{repo}" {row file} templates/skillset-contents.md`
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" {entry file} templates/skillset-contents.md`
|
||||
|
||||
The key column is `2`, the 存取庫 column, holding that repo's `{owner}/{repo}` exactly as the row file writes it, so one domain keeps exactly one row and no other domain's row moves. Never hand-edit the directory page. Write the content page first and fetch the URL only after it exists.
|
||||
- **Check the links before writing.** Hand every URL going onto the content page and into the directory row to `jsc-gitea/tools/link-check.sh`, and write only when it exits 0. It verifies through the Gitea API, never a web status code: a private repo answers 404 to an unauthenticated web request, so a status-code check would call a live page dead.
|
||||
The key is the H2 heading `SKILLSET_{HASH}`, so one domain keeps exactly one block and no other domain's block moves. That page name depends only on `{owner}/{repo}`, which is why it is the key: a host rename or a changed `JSC_WIKI_REPO_SKILLSET` leaves it untouched, so the match still finds the existing block. The `2` is the key column: the index of the column that held the content-page link in the **old markdown table**, and it matters only when such an old table still has to be converted automatically — the conversion takes the last path segment of that column's link URL as the H2 heading. Count that index from the **live page's own column layout**, never from the template's: the live `SKILLSET_CONTENTS` reads `| 存放庫 | 異動報告 | 目前版本 | 最後更新 |`, so the link sits in column 2 while column 1 is plain text like `plugins/ask`. Passing `1` would make the heading `plugins/ask`, which never matches the key `SKILLSET_{HASH}`, so the existing entry is appended as a brand-new one — one domain ends up with two blocks and the older one is never updated again. The fourth argument is the whole block, not a table row. Never hand-edit the directory page. Write the content page first and fetch the URL only after it exists.
|
||||
- **Check the links before writing.** Hand every URL going onto the content page and into the directory block to `jsc-gitea/tools/link-check.sh`, and write only when it exits 0. It verifies through the Gitea API, never a web status code: a private repo answers 404 to an unauthenticated web request, so a status-code check would call a live page dead.
|
||||
- **Exit codes.** Route every one of them:
|
||||
|
||||
| Call | Exit | Do |
|
||||
@@ -37,22 +37,22 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
| Content page read | 0 | Append into the sections already there |
|
||||
| | 4 | The page does not exist yet, so build it from `templates/skillset-page.md` |
|
||||
| | 7 or 8 | Stop and write nothing: a page rebuilt on top of an unread read loses every section already on it |
|
||||
| `gitea.sh wiki-url` | 4 | The content page is not there, so the write above did **not** succeed. Go back and write it, and add no directory row until the page exists |
|
||||
| `gitea.sh wiki-url` | 4 | The content page is not there, so the write above did **not** succeed. Go back and write it, and add no directory block until the page exists |
|
||||
| | 5 | The API answered with no `html_url`. Stop and report it; never assemble the URL by hand from the host and the page name |
|
||||
| `link-check.sh` | 0 | Every link is reachable. Write the page |
|
||||
| | 1 | At least one link is dead. Write nothing, and report the `DEAD` lines it printed |
|
||||
| | 2 | No URL was passed, which is a defect here. Pass the links and rerun |
|
||||
| | 3 | `GITEA_HOST` is unset. Set it and rerun; never skip the check instead |
|
||||
| | 7 | Gitea authentication failed. Stop and report the key problem, and never read it as a dead link |
|
||||
| `wiki-contents.sh upsert` | 0 | The row is in place. Report the `updated` or `added` it printed |
|
||||
| | 1 | The write failed. Report `SKILLSET_CONTENTS` as not written, together with the row content |
|
||||
| `wiki-contents.sh upsert` | 0 | The block is in place. Report the `updated` or `added` it printed |
|
||||
| | 1 | The page content could not be assembled, or the write failed. Report `SKILLSET_CONTENTS` as not written, together with the block content |
|
||||
| | 2 | An argument was rejected. Fix it and rerun; nothing was written |
|
||||
| | 3 | No CONTENTS wiki repo is configured. Report `JSC_WIKI_REPO_CONTENTS` and `JSC_WIKI_REPO` as the two variables to set; the new section is on `SKILLSET_{HASH}` and stays there |
|
||||
| | 4 | The directory page is absent and no template was passed. Rerun with `templates/skillset-contents.md` as the fifth argument |
|
||||
| | 7 | The token is invalid or lacks permission, so the other domains' rows are unknown. Stop, report the token problem, and create no page |
|
||||
| | 7 | The token is invalid or lacks permission, so the other domains' blocks are unknown. Stop, report the token problem, and create no page |
|
||||
| | 8 | Some other API failure. Stop, report that status, and create no page |
|
||||
|
||||
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's row on `SKILLSET_CONTENTS` linking that page by absolute URL.
|
||||
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: `SKILLSET_{HASH}` holds the new section plus all earlier sections, and `wiki-contents.sh upsert` exited 0 with this domain's `## SKILLSET_{HASH}` block on `SKILLSET_CONTENTS` linking that page by absolute URL.
|
||||
9. Report this run's outcome to the local event stream — the last step of every run, the ones that stop early included. Run:
|
||||
|
||||
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:skill-update {status} {exit code} [detail]`
|
||||
@@ -66,7 +66,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
| `ok` | the skill files and the behavior-list section carry the change, the checklist passes, the PR is open, `deploy-verify.md` sections 1 to 5 hold, and both wiki writes exited 0 |
|
||||
| `blocked` | a gate or a missing prerequisite stopped the run before any file changed — `sync-domains.sh` never reached exit 0, or no skill could be listed to pick from |
|
||||
| `failed` | the run broke mid-way — the step 6 checklist loop kept failing, or a wiki write failed again after its one retry |
|
||||
| `degraded` | the update landed with a part missing — the content page was written while its `SKILLSET_CONTENTS` row was not, or a CLI could not be verified and the reason was recorded |
|
||||
| `degraded` | the update landed with a part missing — the content page was written while its `SKILLSET_CONTENTS` block was not, or a CLI could not be verified and the reason was recorded |
|
||||
| `aborted` | the user stopped the run, or a prerequisite turned out not to hold and this skill stopped on its own |
|
||||
|
||||
`{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
|
||||
|
||||
@@ -21,12 +21,12 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
1. Follow [`../../references/deploy-verify.md`](../../references/deploy-verify.md) from section 1 to section 5, once per affected domain repo — the route judgements run in parallel. The batch takes the deploy route only when **every** affected repo's `tools/deploy-route.sh` exits 0; a single exit 3 puts the whole batch on the worktree route, because the change reaches the CLIs only when the last repo merges, so name every outstanding release PR. The verification then runs in a **fresh CLI process**, never in the session that ran the deploy: that session raised the restart gate itself and still holds the old skill bodies. Verify every touched skill's row in `tools/list-skills.sh`, every tool this change touched, and one minimal prompt per affected domain per checkable CLI — the per-CLI and per-domain prompts run in parallel. Completion condition: every completion condition in `deploy-verify.md` sections 1 to 5 holds for every affected domain repo.
|
||||
2. Write the change report to the wiki — this part MUST run as a sub agent, one sub agent per affected domain repo, run in parallel. Each sub agent writes two pages in two repos, and they must not be mixed up.
|
||||
- **Content page `SKILLSET_{HASH}`.** Resolve its repo with `jsc-gitea/tools/gitea.sh wiki-repo SKILLSET`, which reads `JSC_WIKI_REPO_SKILLSET` first, then `JSC_WIKI_REPO`. `{HASH}` is `gitea.sh hash-id "{owner}/{repo}"` of that repo, used at the full 40 characters it prints. Write it through `jsc-gitea:wiki` following [`../../templates/skillset-page.md`](../../templates/skillset-page.md): **append** a section for this change — date, 「批次更新」, the change request in one line, touched skills, changed files, PR URL, the step 5.1 route verdict and verification result per item — and keep every earlier section.
|
||||
- **Directory page `SKILLSET_CONTENTS`.** One shared page holds every domain's row, so each sub agent writes only its own. It lives in the CONTENTS repo, never in the SKILLSET one: `wiki-contents.sh` resolves it itself with `gitea.sh wiki-repo CONTENTS`, whose chain is `JSC_WIKI_REPO_CONTENTS` then `JSC_WIKI_REPO` and never falls back to `JSC_WIKI_REPO_SKILLSET`. Build one file holding the single row from [`../../templates/skillset-contents.md`](../../templates/skillset-contents.md), its 異動頁 cell written as `[SKILLSET_{HASH}]({url})` with the **absolute** URL from `gitea.sh wiki-url {SKILLSET repo} SKILLSET_{HASH}`. Every link on both pages takes that `[{text}]({url})` form; the double-bracket wiki-link form resolves only inside one wiki, so it is never used. Then run:
|
||||
- **Directory page `SKILLSET_CONTENTS`.** One shared page holds every domain's block, so each sub agent writes only its own. It lives in the CONTENTS repo, never in the SKILLSET one: `wiki-contents.sh` resolves it itself with `gitea.sh wiki-repo CONTENTS`, whose chain is `JSC_WIKI_REPO_CONTENTS` then `JSC_WIKI_REPO` and never falls back to `JSC_WIKI_REPO_SKILLSET`. That page is a heading-plus-bullets list and holds no markdown table: one `## SKILLSET_{HASH}` block per domain repo, every field one `- {欄位名}：{值}` line under it. Build one file holding this domain's single block, following [`../../templates/skillset-contents.md`](../../templates/skillset-contents.md), with its 異動頁 bullet written as `[SKILLSET_{HASH}]({url})` from the **absolute** URL that `gitea.sh wiki-url {SKILLSET repo} SKILLSET_{HASH}` prints. The H2 heading itself carries no link, no URL, no affix and no date — only the content page name. Every link on both pages takes that `[{text}]({url})` form; the double-bracket wiki-link form resolves only inside one wiki, so it is never used. Then run:
|
||||
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "{owner}/{repo}" {row file} templates/skillset-contents.md`
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" {entry file} templates/skillset-contents.md`
|
||||
|
||||
The key column is `2`, the 存取庫 column, holding that repo's `{owner}/{repo}` exactly as the row file writes it, so one domain keeps exactly one row and no sibling sub agent's row moves. Never hand-edit the directory page, and never overwrite it as a whole. Write the content page first and fetch the URL only after it exists.
|
||||
- **Check the links before writing.** Hand every URL going onto the content page and into the directory row to `jsc-gitea/tools/link-check.sh`, and write only when it exits 0. It verifies through the Gitea API, never a web status code: a private repo answers 404 to an unauthenticated web request, so a status-code check would call a live page dead.
|
||||
The key is the H2 heading `SKILLSET_{HASH}`, so one domain keeps exactly one block and no sibling sub agent's block moves. That page name depends only on `{owner}/{repo}`, which is why it is the key: a host rename or a changed `JSC_WIKI_REPO_SKILLSET` leaves it untouched, so the match still finds the existing block. The `2` is the key column: the index of the column that held the content-page link in the **old markdown table**, and it matters only when such an old table still has to be converted automatically — the conversion takes the last path segment of that column's link URL as the H2 heading. Count that index from the **live page's own column layout**, never from the template's: the live `SKILLSET_CONTENTS` reads `| 存放庫 | 異動報告 | 目前版本 | 最後更新 |`, so the link sits in column 2 while column 1 is plain text like `plugins/ask`. Passing `1` would make the heading `plugins/ask`, which never matches the key `SKILLSET_{HASH}`, so the existing entry is appended as a brand-new one — one domain ends up with two blocks and the older one is never updated again. The fourth argument is the whole block, not a table row. Never hand-edit the directory page, and never overwrite it as a whole. Write the content page first and fetch the URL only after it exists.
|
||||
- **Check the links before writing.** Hand every URL going onto the content page and into the directory block to `jsc-gitea/tools/link-check.sh`, and write only when it exits 0. It verifies through the Gitea API, never a web status code: a private repo answers 404 to an unauthenticated web request, so a status-code check would call a live page dead.
|
||||
- **Exit codes.** Route every one of them:
|
||||
|
||||
| Call | Exit | Do |
|
||||
@@ -38,22 +38,22 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
| Content page read | 0 | Append into the sections already there |
|
||||
| | 4 | The page does not exist yet, so build it from `templates/skillset-page.md` |
|
||||
| | 7 or 8 | Stop and write nothing: a page rebuilt on top of an unread read loses every section already on it |
|
||||
| `gitea.sh wiki-url` | 4 | The content page is not there, so the write above did **not** succeed. Go back and write it, and add no directory row until the page exists |
|
||||
| `gitea.sh wiki-url` | 4 | The content page is not there, so the write above did **not** succeed. Go back and write it, and add no directory block until the page exists |
|
||||
| | 5 | The API answered with no `html_url`. Stop and report it; never assemble the URL by hand from the host and the page name |
|
||||
| `link-check.sh` | 0 | Every link is reachable. Write the page |
|
||||
| | 1 | At least one link is dead. Write nothing, and report the `DEAD` lines it printed |
|
||||
| | 2 | No URL was passed, which is a defect here. Pass the links and rerun |
|
||||
| | 3 | `GITEA_HOST` is unset. Set it and rerun; never skip the check instead |
|
||||
| | 7 | Gitea authentication failed. Stop and report the key problem, and never read it as a dead link |
|
||||
| `wiki-contents.sh upsert` | 0 | The row is in place. Report the `updated` or `added` it printed |
|
||||
| | 1 | The write failed. Report `SKILLSET_CONTENTS` as not written, together with the row content |
|
||||
| `wiki-contents.sh upsert` | 0 | The block is in place. Report the `updated` or `added` it printed |
|
||||
| | 1 | The page content could not be assembled, or the write failed. Report `SKILLSET_CONTENTS` as not written, together with the block content |
|
||||
| | 2 | An argument was rejected. Fix it and rerun; nothing was written |
|
||||
| | 3 | No CONTENTS wiki repo is configured. Report `JSC_WIKI_REPO_CONTENTS` and `JSC_WIKI_REPO` as the two variables to set; the new section is on `SKILLSET_{HASH}` and stays there |
|
||||
| | 4 | The directory page is absent and no template was passed. Rerun with `templates/skillset-contents.md` as the fifth argument |
|
||||
| | 7 | The token is invalid or lacks permission, so the other domains' rows are unknown. Stop, report the token problem, and create no page |
|
||||
| | 7 | The token is invalid or lacks permission, so the other domains' blocks are unknown. Stop, report the token problem, and create no page |
|
||||
| | 8 | Some other API failure. Stop, report that status, and create no page |
|
||||
|
||||
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: every affected repo's `SKILLSET_{HASH}` holds the new section plus all earlier sections, and every one of those repos has a row on `SKILLSET_CONTENTS` written by a `wiki-contents.sh upsert` that exited 0, linking its page by absolute URL.
|
||||
On any failure, hand the page name and the unwritten entry back to the user and leave this step open; never close the flow on an unwritten report. Completion condition: every affected repo's `SKILLSET_{HASH}` holds the new section plus all earlier sections, and every one of those repos has a `## SKILLSET_{HASH}` block on `SKILLSET_CONTENTS` written by a `wiki-contents.sh upsert` that exited 0, linking its page by absolute URL.
|
||||
6. Report this run's outcome to the local event stream — the last step of every run, the ones that stop early included. One event for the whole batch, not one per domain. Run:
|
||||
|
||||
`jsc-hooks/tools/report-status.sh skill-end jsc-meta:skillset-update {status} {exit code} [detail]`
|
||||
@@ -67,7 +67,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
| `ok` | every affected repo carries the change and its behavior-list update, every checklist passes, every repo has a PR URL, `deploy-verify.md` sections 1 to 5 hold for all of them, and every wiki write exited 0 |
|
||||
| `blocked` | a gate or a missing prerequisite stopped the run before any file changed — `sync-domains.sh` never reached exit 0, or the affected-skill list was never agreed |
|
||||
| `failed` | the run broke mid-way — the step 3 checklist loop kept failing for some repo, or a wiki write failed again after its one retry |
|
||||
| `degraded` | part of the batch landed and part did not — some repos got their PR and others did not, or a content page was written while its `SKILLSET_CONTENTS` row was not. Name the repos in `detail` |
|
||||
| `degraded` | part of the batch landed and part did not — some repos got their PR and others did not, or a content page was written while its `SKILLSET_CONTENTS` block was not. Name the repos in `detail` |
|
||||
| `aborted` | the user stopped the run, or a prerequisite turned out not to hold and this skill stopped on its own |
|
||||
|
||||
`{exit code}` is this run's own result as a number: `0` for `ok`, non-zero otherwise. `detail` is optional, one line, at most 200 characters.
|
||||
|
||||
@@ -18,7 +18,7 @@ Single source of guidelines: [`../../references/guidelines.md`](../../references
|
||||
- Do not modify README files, manifests, marketplace files, hooks, tools, or other skills.
|
||||
- Put generated guide text in the response or in the user-requested target only.
|
||||
- Run detail synthesis as a sub agent when the guide needs explanations, grouping, or onboarding prose.
|
||||
- Route every wiki read and write through `jsc-gitea:wiki`, and every `{HASH}` through `jsc-gitea/tools/hash-id`.
|
||||
- Route every wiki read and write through `jsc-gitea:wiki`, and every `{HASH}` through `jsc-gitea/tools/hash-id`. The directory page `TOOLING_CONTENTS` is the one exception: it goes through `jsc-gitea/tools/wiki-contents.sh`, which owns the directory-page layout for every page type, so this skill never assembles that page itself.
|
||||
- Close every run with the step 8 `skill-end` event. That one line in `$JSC_HOME/usage/events.jsonl` is the only thing this skill writes outside the recorded output target, and the rule above about not modifying files does not cover it.
|
||||
|
||||
Done when each rule above has a recorded pass, or a recorded exception naming the claim and the reason, checked before the final report.
|
||||
@@ -86,18 +86,25 @@ Done when the scope and the output target are each written down as one of the va
|
||||
|
||||
7.1 **Build one page name per detected CLI.** Take the CLI code names from the step 3 `Supported CLIs` section — that section already carries the first column of `jsc-cli/tools/detect-clis.sh`, one of `claude`, `codex`, `copilot`, `antigravity`, `kiro`. Pair each code name with this machine's host name and the current login account, then hand `{hostname}/{tool}/{account}` to `jsc-gitea/tools/hash-id`. The hash rules live in `../../references/guidelines.md` and are not restated here; compute nothing by hand. One page per host, CLI, and account: every CLI carries its own installed plugin set and its own hook wiring, and the tool segment is what keeps five CLIs off one page. A missing host name, tool name, or account stops the step — name the missing segment and substitute no default value. `hash-id` exit 1 means this machine has neither `sha1sum` nor `shasum`: stop and report that one of them has to be installed. Completion condition: every detected CLI has one `TOOLING_{HASH}` name built from three non-empty segments, all of them produced by `hash-id`.
|
||||
|
||||
7.2 **Resolve the wiki repo** for type `TOOLING` through `jsc-gitea:wiki`, which reads `JSC_WIKI_REPO_TOOLING` first and `JSC_WIKI_REPO` second. Exit 3 — neither variable is set: ask for that type's `{owner}/{repo}` per the `jsc-ask:ask` rules. Exit 2 — the installed `jsc-gitea` does not accept the `TOOLING` type yet: stop and report that the type has to be registered there first. Completion condition: exactly one `{owner}/{repo}` is recorded, and every write in this step targets it.
|
||||
7.2 **Resolve the wiki repo** for type `TOOLING` through `jsc-gitea:wiki`, which reads `JSC_WIKI_REPO_TOOLING` first and `JSC_WIKI_REPO` second. Exit 3 — neither variable is set: ask for that type's `{owner}/{repo}` per the `jsc-ask:ask` rules. Exit 2 — the installed `jsc-gitea` does not accept the `TOOLING` type yet: stop and report that the type has to be registered there first. Completion condition: exactly one `{owner}/{repo}` is recorded, and every **content page** write in this step targets it; the directory page lives in the CONTENTS repo instead, and `wiki-contents.sh` resolves that one itself in step 7.4.
|
||||
|
||||
7.3 **Write the content pages first.** Render `templates/tooling-page.md` for each `TOOLING_{HASH}` from the step 3 inventory, keeping only that page's own CLI row in the `Supported CLIs` and `Hook wiring status` tables. Each run overwrites the whole page: it records what this machine looks like right now, so keeping earlier runs buys nothing. Content pages go before the contents page for the same reason as every other jsc skill — a contents row must never point at a page whose write failed. Completion condition: every `TOOLING_{HASH}` write returned exit 0, or its failure went to step 7.5.
|
||||
7.3 **Write the content pages first.** Render `templates/tooling-page.md` for each `TOOLING_{HASH}` from the step 3 inventory, keeping only that page's own CLI row in the `Supported CLIs` and `Hook wiring status` tables. Each run overwrites the whole page: it records what this machine looks like right now, so keeping earlier runs buys nothing. Content pages go before the directory page for the same reason as every other jsc skill — a directory block must never point at a page whose write failed. Completion condition: every `TOOLING_{HASH}` write returned exit 0, or its failure went to step 7.5.
|
||||
|
||||
7.4 **Register the pages in `TOOLING_CONTENTS` second.** Read that page first, then route the read exit code:
|
||||
- 0 — the page is there. Find the row whose host, tool, and account all match this run, refresh that one row per `templates/tooling-contents.md`, leave every other row exactly as it was, and write the whole page back.
|
||||
- 4 — the page does not exist yet. **This is the only code that allows creating it.** Build it from the template with this run's rows.
|
||||
- 7 or 8 — the key was rejected, or the API failed, so the old content is unknown. Stop. Create nothing and overwrite nothing: a page built on top of unknown content deletes rows that nobody can get back. Report the exit code and the page name.
|
||||
7.4 **Register the pages in `TOOLING_CONTENTS` second, with `jsc-gitea/tools/wiki-contents.sh`.** That page is a heading-plus-bullets list and holds no markdown table: one `## TOOLING_{HASH}` block per machine, CLI and account, every field one `- {欄位名}：{值}` line under it, following [`../../templates/tooling-contents.md`](../../templates/tooling-contents.md). Build one file holding this run's single block, its 盤點頁 bullet written as `[TOOLING_{HASH}]({url})` from the **absolute** URL that `jsc-gitea/tools/gitea.sh wiki-url {TOOLING repo} TOOLING_{HASH}` prints; the H2 heading itself carries no link, no URL, no affix and no date — only the content page name. Hand every URL to `jsc-gitea/tools/link-check.sh` first and write only when it exits 0; it verifies through the Gitea API, because a private repo answers 404 to an unauthenticated web request. Then run this once per page written in step 7.3:
|
||||
|
||||
Completion condition: `TOOLING_CONTENTS` holds one row per page written in step 7.3, every row belonging to another machine or CLI is unchanged, or the step stopped with the read exit code and the page name reported.
|
||||
`jsc-gitea/tools/wiki-contents.sh upsert TOOLING 1 "TOOLING_{HASH}" {entry file} templates/tooling-contents.md`
|
||||
|
||||
7.5 **Route a failed write.** Retry the failed `jsc-gitea:wiki` write once. When it fails again, stop the publish and report the page name together with the content that never reached the wiki, so the user can place it by hand. Report a page as written only after its write returned exit 0. Completion condition: every page named in this step is either confirmed written with its page name, or listed as unwritten with its exit code and its full content.
|
||||
That tool owns the whole read-modify-write of the directory page: it resolves the CONTENTS repo itself, reads the page, converts any leftover markdown table to blocks, replaces the block whose heading matches, appends when none matches, and writes the page back, so every block belonging to another machine or CLI stays as it was. The key is the H2 heading `TOOLING_{HASH}`, and that name is hashed from `{hostname}/{tool}/{account}`, so a heading match already proves all three segments match — no per-field comparison is needed. The `1` is the key column, and it only matters while the page is still an old markdown table: it names the 盤點頁 column, whose cell text is that same page name, so the automatic conversion produces headings that match. The fourth argument is the whole block, not a table row. Route each exit code:
|
||||
- 0 — the block is in place. Report the `updated` or `added` it printed.
|
||||
- 1 — the page content could not be assembled, or the write failed. A page holding no matching block is **not** this case; that one appends. Report `TOOLING_CONTENTS` as not written together with the block content, and take it to step 7.5.
|
||||
- 2 — an argument was rejected. Fix it and rerun; nothing was written.
|
||||
- 3 — no CONTENTS wiki repo is configured. Name `JSC_WIKI_REPO_CONTENTS` and `JSC_WIKI_REPO`, ask per the `jsc-ask:ask` rules, then rerun. The content pages of step 7.3 stay written.
|
||||
- 4 — the directory page is absent and no template was passed. Rerun with `templates/tooling-contents.md` as the fifth argument. **This is the only path that creates that page.**
|
||||
- 7 or 8 — the token was rejected, or the API failed, so the other machines' blocks are unknown. Stop. Create nothing and overwrite nothing: a page built on top of unknown content deletes blocks that nobody can get back. Report the exit code and the page name.
|
||||
|
||||
Completion condition: `TOOLING_CONTENTS` holds one `## TOOLING_{HASH}` block per page written in step 7.3, each written by an `upsert` that exited 0, every block belonging to another machine or CLI is unchanged, or the step stopped with the exit code and the page name reported.
|
||||
|
||||
7.5 **Route a failed write.** Retry the failed write once — a `jsc-gitea:wiki` content-page write, or a `wiki-contents.sh upsert` that exited 1. When it fails again, stop the publish and report the page name together with the content that never reached the wiki, so the user can place it by hand. Report a page as written only after its write returned exit 0. Completion condition: every page named in this step is either confirmed written with its page name, or listed as unwritten with its exit code and its full content.
|
||||
|
||||
8. Report this run's outcome to the local event stream — the last step of every run, the ones that stop early included, and the ones whose target was the chat response. Run:
|
||||
|
||||
@@ -140,4 +147,4 @@ The guide must include these fields in this order:
|
||||
|
||||
Done when the output has all fields in order and each non-empty table has at least one source reference.
|
||||
|
||||
For the wiki-page target, the same fields go to `TOOLING_{HASH}` in the section order of `templates/tooling-page.md`, and the row registered in `TOOLING_CONTENTS` follows `templates/tooling-contents.md`. Both templates own their own field lists; do not restate them here.
|
||||
For the wiki-page target, the same fields go to `TOOLING_{HASH}` in the section order of `templates/tooling-page.md`, and the `## TOOLING_{HASH}` block registered in `TOOLING_CONTENTS` follows `templates/tooling-contents.md`. Both templates own their own field lists; do not restate them here.
|
||||
|
||||
@@ -1,41 +1,42 @@
|
||||
# 技能組異動目錄
|
||||
|
||||
> 由 `jsc-meta` 的 `skill-new`、`skill-update`、`skill-delete`、`skillset-update`、`skill-check` 共同維護。這是目錄頁 `SKILLSET_CONTENTS`。
|
||||
> 一列代表一個 domain 存取庫。技能組有幾個 domain 被改過，就有幾列。
|
||||
> 一個區塊代表一個 domain 存取庫。技能組有幾個 domain 被改過，就有幾個區塊。
|
||||
> 本頁落在 `JSC_WIKI_REPO_CONTENTS` 解出來的存取庫，不是內容頁那一個。解析鏈是 `JSC_WIKI_REPO_CONTENTS` → `JSC_WIKI_REPO` → exit 3，中間不退回 `JSC_WIKI_REPO_SKILLSET`。
|
||||
> 寫入一律用 `jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "{owner}/{repo}" {列檔} templates/skillset-contents.md`：`<TYPE>` 填 `SKILLSET`，鍵欄填數字 `2`，也就是「存取庫」那一欄。
|
||||
> 它讀回整頁、換掉鍵欄相符的那一列、找不到才附加，最後整頁寫回。不得手工改目錄頁。
|
||||
> 寫入一律用 `jsc-gitea/tools/wiki-contents.sh upsert SKILLSET 2 "SKILLSET_{HASH}" {區塊檔} templates/skillset-contents.md`：`<TYPE>` 填 `SKILLSET`，`<key>` 填這一筆的 H2 標題，也就是內容頁頁名 `SKILLSET_{HASH}`，第四個參數是整個 H2 區塊的檔案，不是一列表格。
|
||||
> `<key-col>` 填 `2`。這個參數填的是**舊表格裡持有「內容頁連結」那一欄的序號**，只在舊頁還是 markdown 表格、需要自動轉檔時才用得到：轉檔時工具從那一欄的連結網址取最後一段路徑當 H2 標題。序號要照**線上那一頁實際的欄位排法**數，不是照這份範本的欄位排法——線上 `SKILLSET_CONTENTS` 的舊表頭是 `| 存放庫 | 異動報告 | 目前版本 | 最後更新 |`，連結在第 2 欄，第 1 欄是 `plugins/ask` 這種純文字。填成 `1` 會把標題轉成 `plugins/ask`，跟鍵 `SKILLSET_{HASH}` 對不上，既有那一筆會被當成新的附加上去，同一筆變兩個區塊，舊區塊從此再也更新不到。頁面已經是條列格式時這個參數完全不影響結果。
|
||||
> 它讀回整頁、換掉 H2 標題相符的那個區塊、找不到才附加到頁尾，最後整頁寫回。不得手工改目錄頁。
|
||||
> `SKILLSET_{HASH}` 的 `{HASH}` 交給 `jsc-gitea/tools/hash-id` 產生，雜湊來源見 `jsc-meta/references/guidelines.md` 的「Wiki 頁命名總表」。
|
||||
> 連結寫法：所有連結一律 `[{文字}]({連結})`，網址放 `jsc-gitea/tools/gitea.sh wiki-url` 印出的絕對網址，不用 `[[...]]`。寫入前先把每個連結交給 `jsc-gitea/tools/link-check.sh` 驗證，結束碼 0 才寫入；驗證走 API，不看網頁狀態碼。
|
||||
>
|
||||
> 欄位說明：一個區塊固定五條，順序照下面從上到下。
|
||||
>
|
||||
> - 異動頁：`[SKILLSET_{HASH}]({連結})`，連結是 `gitea.sh wiki-url` 印出的絕對網址。與 H2 標題指的是同一頁，標題不放連結，這一條才放。
|
||||
> - 存取庫：被改動的 domain 存取庫 `{owner}/{repo}`，也就是那一頁的雜湊來源。
|
||||
> - 最近異動：最後一次異動的一句話摘要，與內容頁最新一節的「異動需求」同一句。
|
||||
> - 異動次數：該內容頁累積的節數。內容頁只附加不覆蓋，所以這個數字只會往上加。
|
||||
> - 最後更新：最後一次寫入內容頁的時間，與那一節的日期一致。
|
||||
>
|
||||
> 為什麼 H2 標題寫頁名：頁名只由 `{owner}/{repo}` 決定，換主機名、`JSC_WIKI_REPO_SKILLSET` 改指別的存取庫、Gitea 的頁名編碼有差，都動不到它。鍵夠穩，`upsert` 才比得到既有那一筆；鍵一漂，同一個 domain 就多出第二個區塊，兩邊都寫得成功，也都看不出被分裂。
|
||||
>
|
||||
> 為什麼連結要用絕對網址，還要先驗證：目錄頁與內容頁分屬不同存取庫。同 wiki 連結解到的是目錄頁自己那個存取庫，那裡沒有這一頁，點下去是 404。更麻煩的是它看起來像「頁沒寫成功」，實際上頁好好的，只是連結指錯地方，查的人會回去重寫一次已經寫好的頁。驗證則走 API，不看網頁狀態碼。私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判斷會把還在的頁判成死連結，接著被刪掉或改寫。
|
||||
>
|
||||
> 寫入規則：
|
||||
>
|
||||
> - 一律走 `jsc-gitea/tools/wiki-contents.sh upsert`，鍵是 H2 標題 `SKILLSET_{HASH}`。
|
||||
> - 那支腳本先整頁讀回來，再逐個比對 H2 標題。
|
||||
> - 標題相同就整塊換掉，區塊裡的每一條都覆寫成本次結果。
|
||||
> - 找不到相同的標題，才附加一個新區塊。
|
||||
> - 只動自己那一個區塊，別人的區塊原樣保留。
|
||||
> - 禁止整頁覆蓋。這一頁是全部 domain 共用的索引，覆蓋等於刪掉別的 domain 的紀錄。
|
||||
> - 讀不到舊內容就中止，不附加區塊，也不寫入。
|
||||
> - 這一頁不留任何 markdown 表格。舊頁還是表格時由 `wiki-contents.sh` 自動轉成條列後寫回，不要手工搬。
|
||||
> - 先寫內容頁，成功了才回來更新這個區塊。目錄頁指向一個寫失敗的頁，比缺一筆更難查。
|
||||
|
||||
| 異動頁 | 存取庫 | 最近異動 | 異動次數 | 最後更新 |
|
||||
| --- | --- | --- | ---: | --- |
|
||||
| [SKILLSET_{HASH}]({wiki-url 印出的絕對網址}) | {owner}/{repo} | {一句話寫這一次改了什麼} | {n} | {yyyy-MM-dd HH:mm} |
|
||||
## SKILLSET_{HASH}
|
||||
|
||||
## 欄位說明
|
||||
|
||||
| 欄位 | 內容 |
|
||||
| --- | --- |
|
||||
| 異動頁 | `[SKILLSET_{HASH}]({連結})`，連結是 `gitea.sh wiki-url` 印出的絕對網址。`{owner}/{repo}` 是內容頁那一個存取庫 |
|
||||
| 存取庫 | 被改動的 domain 存取庫 `{owner}/{repo}`，也就是這一頁的雜湊來源 |
|
||||
| 最近異動 | 最後一次異動的一句話摘要，與內容頁最新一節的「異動需求」同一句 |
|
||||
| 異動次數 | 該內容頁累積的節數。內容頁只附加不覆蓋，所以這個數字只會往上加 |
|
||||
| 最後更新 | 最後一次寫入內容頁的時間，與那一節的日期一致 |
|
||||
|
||||
## 為什麼連結要用絕對網址，還要先驗證
|
||||
|
||||
目錄頁與內容頁分屬不同存取庫。同 wiki 連結解到的是目錄頁自己那個存取庫，那裡沒有這一頁，點下去是 404。
|
||||
更麻煩的是它看起來像「頁沒寫成功」，實際上頁好好的，只是連結指錯地方，查的人會回去重寫一次已經寫好的頁。
|
||||
|
||||
驗證則走 API，不看網頁狀態碼。私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判斷會把還在的頁判成死連結，接著被刪掉或改寫。
|
||||
|
||||
## 寫入規則
|
||||
|
||||
- 一律走 `jsc-gitea/tools/wiki-contents.sh upsert`，鍵欄是第 2 欄「存取庫」，鍵值是 `{owner}/{repo}`。
|
||||
- 那支腳本先整頁讀回來，再比對「存取庫」欄。
|
||||
- 該欄相同就更新那一列，其餘欄位覆寫成本次結果。
|
||||
- 找不到相同的一列，才新增一列。
|
||||
- 只動自己那一列，別人的列原樣保留。
|
||||
- 禁止整頁覆蓋。這一頁是全部 domain 共用的索引，覆蓋等於刪掉別的 domain 的紀錄。
|
||||
- 讀不到舊內容就中止，不新增列，也不寫入。
|
||||
- 先寫內容頁，成功了才回來更新這一列。目錄列指向一個寫失敗的頁，比缺一列更難查。
|
||||
- 異動頁：[SKILLSET_{HASH}]({wiki-url 印出的絕對網址})
|
||||
- 存取庫：{owner}/{repo}
|
||||
- 最近異動：{一句話寫這一次改了什麼}
|
||||
- 異動次數：{n}
|
||||
- 最後更新：{yyyy-MM-dd HH:mm}
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> 由 `jsc-meta` 的 `skill-new`、`skill-update`、`skill-delete`、`skillset-update`、`skill-check` 共同維護。這是內容頁 `SKILLSET_{HASH}`。
|
||||
> 一個 domain 存取庫一頁。雜湊來源是這個存取庫的 `{owner}/{repo}`。
|
||||
> 本頁落在 `JSC_WIKI_REPO_SKILLSET` 解出來的存取庫；目錄頁 `SKILLSET_CONTENTS` 在別的存取庫，兩者不要混。
|
||||
> 本頁落在 `JSC_WIKI_REPO_SKILLSET` 解出來的存取庫；目錄頁 `SKILLSET_CONTENTS` 在別的存取庫，版面也不同：那頁是大標題加條列，一筆一個 H2 區塊，本頁是內容頁，版面維持圖表優先。兩者不要混。
|
||||
> **每次異動附加一節，不覆蓋舊紀錄。** 要看一支技能改過幾次，就在這一頁上翻。
|
||||
> 節的排列由新到舊，最新那一次放最上面。
|
||||
|
||||
@@ -12,7 +12,7 @@
|
||||
| --- | --- |
|
||||
| 日期 | {yyyy-MM-dd HH:mm} |
|
||||
| 異動類型 | {skill-new、skill-update、skill-delete、skillset-update、skill-check 五選一} |
|
||||
| 異動需求 | {一句話。與目錄頁「最近異動」欄同一句} |
|
||||
| 異動需求 | {一句話。與目錄頁「最近異動」那一條同一句} |
|
||||
| 動到的技能 | {技能名，多支用頓號隔開；一支都沒動就寫「無」} |
|
||||
| 改動檔案 | {存取庫內相對路徑，一行一個；一個檔都沒動就寫「無」} |
|
||||
| PR 網址 | {絕對網址；沒開 PR 就寫「無」並說明原因} |
|
||||
|
||||
@@ -1,32 +1,45 @@
|
||||
# 技能盤點目錄
|
||||
|
||||
> 由 `jsc-meta:tooling-guide` 維護。這是目錄頁 `TOOLING_CONTENTS`。
|
||||
> 一列代表一組「機器、CLI、帳號」。同一台機器裝了幾支 CLI，就有幾列。
|
||||
> 一個區塊代表一組「機器、CLI、帳號」。同一台機器裝了幾支 CLI，就有幾個區塊。
|
||||
> 寫入一律用 `jsc-gitea/tools/wiki-contents.sh upsert TOOLING 1 "TOOLING_{HASH}" {區塊檔} templates/tooling-contents.md`：`<TYPE>` 填 `TOOLING`，`<key>` 填這一筆的 H2 標題，也就是內容頁頁名 `TOOLING_{HASH}`，第四個參數是整個 H2 區塊的檔案，不是一列表格。
|
||||
> `<key-col>` 填 `1`。這個參數填的是**舊表格裡持有「內容頁連結」那一欄的序號**，只在舊頁還是 markdown 表格、需要自動轉檔時才用得到：轉檔時工具從那一欄的連結網址取最後一段路徑當 H2 標題。序號要照**線上那一頁實際的欄位排法**數，不是照這份範本的欄位排法。這裡之所以是 `1`：線上 `TOOLING_CONTENTS` 目前是空頁，沒有舊表格要轉，而這份範本的「盤點頁」連結就在第 1 欄。線上哪一天真有舊表格，就先讀回線上那一頁、看連結落在第幾欄，再照那個序號填。頁面已經是條列格式時這個參數完全不影響結果。
|
||||
> 它讀回整頁、換掉 H2 標題相符的那個區塊、找不到才附加到頁尾，最後整頁寫回。不得手工改目錄頁。
|
||||
> `TOOLING_{HASH}` 的 `{HASH}` 交給 `jsc-gitea/tools/hash-id` 產生，雜湊來源見 `jsc-meta/references/guidelines.md` 的「Wiki 頁命名總表」。
|
||||
> 連結寫法：所有連結一律 `[{文字}]({連結})`，網址放 `jsc-gitea/tools/gitea.sh wiki-url` 印出的絕對網址，不用 `[[...]]`。寫入前先把每個連結交給 `jsc-gitea/tools/link-check.sh` 驗證，結束碼 0 才寫入；驗證走 API，不看網頁狀態碼，私有存取庫的網頁網址對未登入請求會回 404。
|
||||
>
|
||||
> 欄位說明：一個區塊固定八條，順序照下面從上到下。
|
||||
>
|
||||
> - 盤點頁：`[TOOLING_{HASH}]({連結})`，連結是 `gitea.sh wiki-url` 印出的絕對網址。與 H2 標題指的是同一頁，標題不放連結，這一條才放。
|
||||
> - 主機：這次盤點的機器名，與雜湊第一段相同。
|
||||
> - 工具：CLI 代號，與雜湊第二段相同。
|
||||
> - 帳號：執行盤點的登入帳號，與雜湊第三段相同。
|
||||
> - plugin 數：該頁「已安裝 plugin」一節的筆數。
|
||||
> - 技能數：該頁「可用技能」一節的筆數。
|
||||
> - hook 接線：該頁「hook 接線狀態」對這支 CLI 的判定。
|
||||
> - 最後盤點：該頁盤點時間，與內容頁標頭一致。
|
||||
>
|
||||
> 為什麼 H2 標題寫頁名：`TOOLING_{HASH}` 的雜湊來源就是「主機、工具、帳號」三段，所以標題相符等於三段都相符，一個鍵就夠。以前靠三個欄位逐欄比對，任一欄的寫法差一點（FQDN 對短主機名、大小寫不同）就比不到既有那一筆，同一台機器同一支 CLI 於是多出第二筆，兩筆都寫得成功，也都看不出被分裂。
|
||||
>
|
||||
> 寫入規則：
|
||||
>
|
||||
> - 一律走 `jsc-gitea/tools/wiki-contents.sh upsert`，鍵是 H2 標題 `TOOLING_{HASH}`。
|
||||
> - 那支腳本先整頁讀回來，再逐個比對 H2 標題。
|
||||
> - 標題相同就整塊換掉，區塊裡的每一條都覆寫成本次結果。
|
||||
> - 找不到相同的標題，才附加一個新區塊。
|
||||
> - 只動自己那一個區塊，別人的區塊原樣保留。
|
||||
> - 禁止整頁覆蓋。這一頁是共用目錄，覆蓋等於刪掉別台機器的紀錄。
|
||||
> - 讀不到舊內容就中止，不附加區塊，也不寫入。
|
||||
> - 這一頁不留任何 markdown 表格。舊頁還是表格時由 `wiki-contents.sh` 自動轉成條列後寫回，不要手工搬。
|
||||
> - 先寫內容頁，成功了才回來更新這個區塊。目錄頁指向一個寫失敗的頁，比缺一筆更難查。
|
||||
|
||||
| 盤點頁 | 主機 | 工具 | 帳號 | plugin 數 | 技能數 | hook 接線 | 最後盤點 |
|
||||
| --- | --- | --- | --- | ---: | ---: | --- | --- |
|
||||
| [TOOLING_{HASH}]({wiki-url 印出的絕對網址}) | {主機名} | {claude、codex、copilot、antigravity、kiro 五選一} | {登入帳號} | {n} | {n} | {wired、degraded、unwired、unknown 四選一} | {yyyy-MM-dd HH:mm} |
|
||||
## TOOLING_{HASH}
|
||||
|
||||
## 欄位說明
|
||||
|
||||
| 欄位 | 內容 |
|
||||
| --- | --- |
|
||||
| 盤點頁 | `[TOOLING_{HASH}]({連結})`，連結是 `gitea.sh wiki-url` 印出的絕對網址 |
|
||||
| 主機 | 這次盤點的機器名，與雜湊第一段相同 |
|
||||
| 工具 | CLI 代號，與雜湊第二段相同 |
|
||||
| 帳號 | 執行盤點的登入帳號，與雜湊第三段相同 |
|
||||
| plugin 數 | 該頁「已安裝 plugin」表的列數 |
|
||||
| 技能數 | 該頁「可用技能」表的列數 |
|
||||
| hook 接線 | 該頁「hook 接線狀態」對這支 CLI 的判定 |
|
||||
| 最後盤點 | 該頁盤點時間，與內容頁標頭一致 |
|
||||
|
||||
## 寫入規則
|
||||
|
||||
- 先整頁讀回來，再比對主機、工具、帳號三欄。
|
||||
- 三欄都相同就更新那一列，其餘欄位覆寫成本次結果。
|
||||
- 三欄找不到相同的一列，才新增一列。
|
||||
- 只動自己那一列，別人的列原樣保留。
|
||||
- 禁止整頁覆蓋。這一頁是共用目錄，覆蓋等於刪掉別台機器的紀錄。
|
||||
- 讀不到舊內容就中止，不新增列，也不寫入。
|
||||
- 盤點頁：[TOOLING_{HASH}]({wiki-url 印出的絕對網址})
|
||||
- 主機：{主機名}
|
||||
- 工具：{claude、codex、copilot、antigravity、kiro 五選一}
|
||||
- 帳號：{登入帳號}
|
||||
- plugin 數：{n}
|
||||
- 技能數：{n}
|
||||
- hook 接線：{wired、degraded、unwired、unknown 四選一}
|
||||
- 最後盤點：{yyyy-MM-dd HH:mm}
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
> 由 `jsc-meta:tooling-guide` 維護。這是盤點頁 `TOOLING_{HASH}`。
|
||||
> 這頁記的是「現在這台機器上這支 CLI 長什麼樣」。每次盤點覆寫整頁，不保留歷史。
|
||||
> 覆寫是刻意的：舊的安裝內容與接線狀態早就不成立，留著只會讓人照著過期的事實下判斷。
|
||||
> 目錄頁 `TOOLING_CONTENTS` 的規則相反，那頁只更新自己那一列，兩者不要混用。
|
||||
> 目錄頁 `TOOLING_CONTENTS` 的規則相反：那頁是大標題加條列，一筆一個 H2 區塊，每次只更新自己那一個區塊，兩者不要混用。本頁是內容頁，版面維持圖表優先。
|
||||
> 要看技能組歷次異動請翻 `SKILLSET_{HASH}`，累積紀錄在那一頁。
|
||||
|
||||
## 本次盤點
|
||||
|
||||
Reference in New Issue
Block a user