docs(templates): 兩個目錄頁範本改成大標題加條列

What
- `templates/skillset-contents.md`:`SKILLSET_CONTENTS` 的版面從 markdown 表格改成一筆一個 H2 區塊,標題寫成該筆對應內容頁的實際頁名,欄位改成標題底下的一層條列。
- `templates/tooling-contents.md`:同樣轉條列,原本說明用的 `## ` 區段併進 `>` 引言,正式頁上才不會被讀成一筆假紀錄。
- `templates/skillset-page.md`、`templates/tooling-page.md`:引言補上目錄頁與內容頁的版面差別,內容頁本身維持圖表優先、不改版面。
- `README.md`:兩份目錄頁範本的說明同步改寫,兩份 `TOOLING` 範本語意相反那一段補上「版面也相反」。

Why
- 目錄頁是全部使用者共用的索引。表格一寬就得橫向捲、欄位一多就對不上表頭,而且併行寫入時只要有人少打一根豎線,整張表就散掉,別人那一筆跟著看不見。
- 條列式一筆一個區塊,寫入端只換自己那一塊,壞掉也只壞自己那一塊。
- 三個範本原本除了示範區塊之外還留著說明用的 `## ` 區段,轉條列後那種區段會在正式頁上被當成一筆紀錄讀進去。

How
- 一頁固定三段:H1 頁名、`>` 引言、然後每一筆一個 H2 區塊;區塊之間空一行,H2 與第一條之間空一行。
- 欄位在標題底下一行一條,格式 `- {欄位名}:{值}`,全形冒號,順序照原本的欄位從左到右,鍵那一欄照樣留一條。
- 寫入示例改成 `wiki-contents.sh upsert {TYPE} {鍵欄} "{內容頁頁名}" {區塊檔}`,並註明鍵欄是舊表格裡持有內容頁連結那一欄的序號、只供自動轉檔用、要照線上那一頁實際的欄位排法填。
- 頁上不留任何 markdown 表格,也不放 mermaid。

Who
- 影響照這兩個範本寫目錄頁的技能:`skill-new`、`skill-update`、`skill-delete`、`skillset-update`、`skill-check` 與 `tooling-guide`。
- 舊頁的轉檔與單一區塊 upsert 的實作不在本存取庫,本存取庫只提供範本與說明。
This commit is contained in:
2026-09-02 17:21:02 +08:00
parent 6de2aa9321
commit 5db1d8a608
5 changed files with 78 additions and 64 deletions
+3 -3
View File
@@ -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