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/pr-report.md` | PR 收尾回報格式唯一來源,所有會開 PR 的技能都指向這裡 |
| `references/deploy-verify.md` | 四支異動技能共用的部署與驗證流程:判路線、部署或工作樹、**在新的 CLI 行程裡驗證**、失敗分流 | | `references/deploy-verify.md` | 四支異動技能共用的部署與驗證流程:判路線、部署或工作樹、**在新的 CLI 行程裡驗證**、失敗分流 |
| `references/behaviors.md` | 本 domain 的技能行為清單:一支技能一節,五列記下觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象,供稽核與驗證比對。格式合約見 `references/guidelines.md` 的「技能行為清單」 | | `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/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` 的輸出;**每次盤點覆寫整頁**,只留現況,不留歷史 | | `templates/tooling-page.md` | `TOOLING_{HASH}` 內容頁樣板。分節對應 `inventory-tooling.sh` 的輸出;**每次盤點覆寫整頁**,只留現況,不留歷史 |
| `tools/plugins-root.sh` | 推導技能組工作目錄的根,六支腳本共用。以 plugin 形式安裝時「腳本上兩層」會落在快取目錄,所以推導規則抽出來;推不出來 exit 1 並指名要設 `JSC_PLUGINS_ROOT` | | `tools/plugins-root.sh` | 推導技能組工作目錄的根,六支腳本共用。以 plugin 形式安裝時「腳本上兩層」會落在快取目錄,所以推導規則抽出來;推不出來 exit 1 並指名要設 `JSC_PLUGINS_ROOT` |
| `tools/ste100-lint.sh` | 語言規則的機檢工具:中國用語、中文句內半形標點、AI 套話、簡體字、中文並列斜線;命中 exit 1,沒給檢查對象 exit 2 | | `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/find-skill-refs.sh` | 盤點一個技能在正本 marketplace 各 domain 存取庫裡的引用檔案(不掃非技能組存取庫與點開頭目錄);技能名稱為純子字串比對,命中要逐檔確認;零命中 exit 1,掃描失敗 exit 3 |
| `tools/verify-skill-removed.sh` | 刪除技能後實地檢查各 CLI 的技能快取與 hook 設定有無殘留;有殘留 exit 1,沒偵測到 CLI 或沒有可查位置 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 ## 相關 domain
+34 -33
View File
@@ -1,41 +1,42 @@
# 技能組異動目錄 # 技能組異動目錄
> 由 `jsc-meta` 的 `skill-new`、`skill-update`、`skill-delete`、`skillset-update`、`skill-check` 共同維護。這是目錄頁 `SKILLSET_CONTENTS`。 > 由 `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_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 頁命名總表」。 > `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,不看網頁狀態碼。 > 連結寫法:所有連結一律 `[{文字}]({連結})`,網址放 `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}
| --- | --- | --- | ---: | --- |
| [SKILLSET_{HASH}]({wiki-url 印出的絕對網址}) | {owner}/{repo} | {一句話寫這一次改了什麼} | {n} | {yyyy-MM-dd HH:mm} |
## 欄位說明 - 異動頁:[SKILLSET_{HASH}]({wiki-url 印出的絕對網址})
- 存取庫:{owner}/{repo}
| 欄位 | 內容 | - 最近異動:{一句話寫這一次改了什麼}
| --- | --- | - 異動次數:{n}
| 異動頁 | `[SKILLSET_{HASH}]({連結})`,連結是 `gitea.sh wiki-url` 印出的絕對網址。`{owner}/{repo}` 是內容頁那一個存取庫 | - 最後更新:{yyyy-MM-dd HH:mm}
| 存取庫 | 被改動的 domain 存取庫 `{owner}/{repo}`,也就是這一頁的雜湊來源 |
| 最近異動 | 最後一次異動的一句話摘要,與內容頁最新一節的「異動需求」同一句 |
| 異動次數 | 該內容頁累積的節數。內容頁只附加不覆蓋,所以這個數字只會往上加 |
| 最後更新 | 最後一次寫入內容頁的時間,與那一節的日期一致 |
## 為什麼連結要用絕對網址,還要先驗證
目錄頁與內容頁分屬不同存取庫。同 wiki 連結解到的是目錄頁自己那個存取庫,那裡沒有這一頁,點下去是 404。
更麻煩的是它看起來像「頁沒寫成功」,實際上頁好好的,只是連結指錯地方,查的人會回去重寫一次已經寫好的頁。
驗證則走 API,不看網頁狀態碼。私有存取庫的網頁網址對未登入請求一律回 404,拿狀態碼判斷會把還在的頁判成死連結,接著被刪掉或改寫。
## 寫入規則
- 一律走 `jsc-gitea/tools/wiki-contents.sh upsert`,鍵欄是第 2 欄「存取庫」,鍵值是 `{owner}/{repo}`。
- 那支腳本先整頁讀回來,再比對「存取庫」欄。
- 該欄相同就更新那一列,其餘欄位覆寫成本次結果。
- 找不到相同的一列,才新增一列。
- 只動自己那一列,別人的列原樣保留。
- 禁止整頁覆蓋。這一頁是全部 domain 共用的索引,覆蓋等於刪掉別的 domain 的紀錄。
- 讀不到舊內容就中止,不新增列,也不寫入。
- 先寫內容頁,成功了才回來更新這一列。目錄列指向一個寫失敗的頁,比缺一列更難查。
+2 -2
View File
@@ -2,7 +2,7 @@
> 由 `jsc-meta` 的 `skill-new`、`skill-update`、`skill-delete`、`skillset-update`、`skill-check` 共同維護。這是內容頁 `SKILLSET_{HASH}`。 > 由 `jsc-meta` 的 `skill-new`、`skill-update`、`skill-delete`、`skillset-update`、`skill-check` 共同維護。這是內容頁 `SKILLSET_{HASH}`。
> 一個 domain 存取庫一頁。雜湊來源是這個存取庫的 `{owner}/{repo}`。 > 一個 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} | | 日期 | {yyyy-MM-dd HH:mm} |
| 異動類型 | {skill-new、skill-update、skill-delete、skillset-update、skill-check 五選一} | | 異動類型 | {skill-new、skill-update、skill-delete、skillset-update、skill-check 五選一} |
| 異動需求 | {一句話。與目錄頁「最近異動」欄同一句} | | 異動需求 | {一句話。與目錄頁「最近異動」那一條同一句} |
| 動到的技能 | {技能名,多支用頓號隔開;一支都沒動就寫「無」} | | 動到的技能 | {技能名,多支用頓號隔開;一支都沒動就寫「無」} |
| 改動檔案 | {存取庫內相對路徑,一行一個;一個檔都沒動就寫「無」} | | 改動檔案 | {存取庫內相對路徑,一行一個;一個檔都沒動就寫「無」} |
| PR 網址 | {絕對網址;沒開 PR 就寫「無」並說明原因} | | PR 網址 | {絕對網址;沒開 PR 就寫「無」並說明原因} |
+38 -25
View File
@@ -1,32 +1,45 @@
# 技能盤點目錄 # 技能盤點目錄
> 由 `jsc-meta:tooling-guide` 維護。這是目錄頁 `TOOLING_CONTENTS`。 > 由 `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 頁命名總表」。 > `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。 > 連結寫法:所有連結一律 `[{文字}]({連結})`,網址放 `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}
| --- | --- | --- | --- | ---: | ---: | --- | --- |
| [TOOLING_{HASH}]({wiki-url 印出的絕對網址}) | {主機名} | {claude、codex、copilot、antigravity、kiro 五選一} | {登入帳號} | {n} | {n} | {wired、degraded、unwired、unknown 四選一} | {yyyy-MM-dd HH:mm} |
## 欄位說明 - 盤點頁:[TOOLING_{HASH}]({wiki-url 印出的絕對網址})
- 主機:{主機名}
| 欄位 | 內容 | - 工具:{claude、codex、copilot、antigravity、kiro 五選一}
| --- | --- | - 帳號:{登入帳號}
| 盤點頁 | `[TOOLING_{HASH}]({連結})`,連結是 `gitea.sh wiki-url` 印出的絕對網址 | - plugin 數:{n}
| 主機 | 這次盤點的機器名,與雜湊第一段相同 | - 技能數:{n}
| 工具 | CLI 代號,與雜湊第二段相同 | - hook 接線:{wired、degraded、unwired、unknown 四選一}
| 帳號 | 執行盤點的登入帳號,與雜湊第三段相同 | - 最後盤點:{yyyy-MM-dd HH:mm}
| plugin 數 | 該頁「已安裝 plugin」表的列數 |
| 技能數 | 該頁「可用技能」表的列數 |
| hook 接線 | 該頁「hook 接線狀態」對這支 CLI 的判定 |
| 最後盤點 | 該頁盤點時間,與內容頁標頭一致 |
## 寫入規則
- 先整頁讀回來,再比對主機、工具、帳號三欄。
- 三欄都相同就更新那一列,其餘欄位覆寫成本次結果。
- 三欄找不到相同的一列,才新增一列。
- 只動自己那一列,別人的列原樣保留。
- 禁止整頁覆蓋。這一頁是共用目錄,覆蓋等於刪掉別台機器的紀錄。
- 讀不到舊內容就中止,不新增列,也不寫入。
+1 -1
View File
@@ -3,7 +3,7 @@
> 由 `jsc-meta:tooling-guide` 維護。這是盤點頁 `TOOLING_{HASH}`。 > 由 `jsc-meta:tooling-guide` 維護。這是盤點頁 `TOOLING_{HASH}`。
> 這頁記的是「現在這台機器上這支 CLI 長什麼樣」。每次盤點覆寫整頁,不保留歷史。 > 這頁記的是「現在這台機器上這支 CLI 長什麼樣」。每次盤點覆寫整頁,不保留歷史。
> 覆寫是刻意的:舊的安裝內容與接線狀態早就不成立,留著只會讓人照著過期的事實下判斷。 > 覆寫是刻意的:舊的安裝內容與接線狀態早就不成立,留著只會讓人照著過期的事實下判斷。
> 目錄頁 `TOOLING_CONTENTS` 的規則相反,那頁只更新自己那一列,兩者不要混用。 > 目錄頁 `TOOLING_CONTENTS` 的規則相反:那頁是大標題加條列,一筆一個 H2 區塊,每次只更新自己那一個區塊,兩者不要混用。本頁是內容頁,版面維持圖表優先。
> 要看技能組歷次異動請翻 `SKILLSET_{HASH}`,累積紀錄在那一頁。 > 要看技能組歷次異動請翻 `SKILLSET_{HASH}`,累積紀錄在那一頁。
## 本次盤點 ## 本次盤點