jiantw83
5db1d8a608
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 的實作不在本存取庫，本存取庫只提供範本與說明。
4.0 KiB
技能盤點目錄
由
jsc-meta:tooling-guide維護。這是目錄頁TOOLING_CONTENTS。 一個區塊代表一組「機器、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自動轉成條列後寫回，不要手工搬。- 先寫內容頁，成功了才回來更新這個區塊。目錄頁指向一個寫失敗的頁，比缺一筆更難查。
TOOLING_{HASH}
- 盤點頁：[TOOLING_{HASH}]({wiki-url 印出的絕對網址})
- 主機：{主機名}
- 工具：{claude、codex、copilot、antigravity、kiro 五選一}
- 帳號：{登入帳號}
- plugin 數：{n}
- 技能數：{n}
- hook 接線：{wired、degraded、unwired、unknown 四選一}
- 最後盤點：{yyyy-MM-dd HH:mm}