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