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.7 KiB
技能組異動目錄
由
jsc-meta的skill-new、skill-update、skill-delete、skillset-update、skill-check共同維護。這是目錄頁SKILLSET_CONTENTS。 一個區塊代表一個 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 "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}
- 異動頁：[SKILLSET_{HASH}]({wiki-url 印出的絕對網址})
- 存取庫：{owner}/{repo}
- 最近異動：{一句話寫這一次改了什麼}
- 異動次數：{n}
- 最後更新：{yyyy-MM-dd HH:mm}