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 的實作不在本存取庫，本存取庫只提供範本與說明。
46 lines
4.0 KiB
Markdown
46 lines
4.0 KiB
Markdown
# 技能盤點目錄
|
||
|
||
> 由 `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}
|