jiantw83
19d918f499
What
- `templates/plan-contents.md`、`templates/analyze-contents.md`、`templates/repo-contents.md`、`templates/deliver-contents.md`、`templates/maintain-contents.md` 的版面從 markdown 表格改成一筆一個 H2 區塊，欄位改成標題底下的一層條列。
- 四個有內容頁的型別，H2 標題寫成該筆對應內容頁的實際頁名；`MAINTAIN` 沒有內容頁，標題改用該存取庫的 `{owner}/{repo}`。
- 各範本的引言補上版面段，並把寫入語意從「單列 upsert」改寫成單一區塊 upsert，末端的示範資料改成一個完整的 H2 區塊。
- 引言裡寫明鍵欄的語意與各頁的正確序號，並點出填錯的靜默後果。
Why
- 目錄頁是全部使用者共用的索引。表格一寬就得橫向捲、欄位一多就對不上表頭，而且併行寫入時只要有人少打一根豎線，整張表就散掉，別人那一筆跟著看不見。
- 條列式一筆一個區塊，寫入端只換自己那一塊，壞掉也只壞自己那一塊。
- `MAINTAIN` 整個型別只有目錄頁，硬套內容頁頁名當標題會指向一個不存在的頁；存取庫名不會漂移，當鍵一樣穩。
- 鍵欄填錯時工具不會報錯，既有那一筆會被當成新的附加到頁尾，同一筆變兩個區塊，舊區塊從此再也更新不到，所以範本要把序號寫死。
How
- 一頁固定三段：H1 頁名、`>` 引言、然後每一筆一個 H2 區塊；欄位格式 `- {欄位名}：{值}`，全形冒號，順序照原本的欄位從左到右，鍵那一欄照樣留一條。
- 寫入示例統一成 `wiki-contents.sh upsert {TYPE} {鍵欄} "{鍵}" {區塊檔} [{本範本}]`，並註明第四個引數是整個 H2 區塊的 markdown，不是列檔。
- 頁上不留任何 markdown 表格；內容頁範本不在本輪範圍，維持圖表優先。
Who
- 影響照這五個範本寫目錄頁的四支階段技能。
- 舊表格頁的自動轉檔與單一區塊 upsert 的實作不在本存取庫，本存取庫只提供範本與敘述。
3.0 KiB
盤點目錄
存放位置：本頁是目錄頁，落在
JSC_WIKI_REPO_CONTENTS解出的專用存取庫（沒設定就退回JSC_WIKI_REPO，都沒設定就停）。盤點頁REPO_{HASH}住在JSC_WIKI_REPO_REPO那一邊，兩者不同存取庫。 版面：一個 H1 頁名、一段>引言，接著每一筆一個 H2 區塊。H2 標題就是該筆盤點頁的實際頁名（示範區塊寫成REPO_{HASH}只是佔位符，真正要填的是盤點那一步剛寫出去那一頁的頁名），標題不放連結、不加前後綴。欄位是標題底下的一層條列，一欄一條，格式- {欄位名}：{值}。本頁不留 markdown 表格。 寫入語意：一個區塊代表一個存取庫的盤點。一律用jsc-gitea/tools/wiki-contents.sh upsert REPO 2 {盤點頁頁名} {區塊檔} {本範本}單筆寫回：該存取庫已經有區塊就更新那個區塊，沒有才附加一個區塊，整頁一起送出。禁止整頁覆蓋，也不得改動別人的區塊。參數語意：2是舊表格裡持有內容頁連結那一欄的序號，也就是「盤點頁」欄，只供自動轉檔用——本頁還是舊表格時，腳本從那一欄的連結網址取最後一段路徑當 H2 標題；本頁已經是條列版面就完全忽略它。這個序號填錯，轉出來的標題就跟鍵對不上，既有那一筆會被當成新的附加上去，同一個存取庫的盤點變成兩個區塊，舊區塊從此再也更新不到，所以不是死參數、也不能隨便填。{盤點頁頁名}是 H2 標題，填這一筆對應內容頁的實際頁名，也就是技能自己剛寫的那一頁的頁名，不套REPO_{HASH}的公式；{區塊檔}是整個 H2 區塊的 markdown（## {盤點頁頁名}那一行加各條欄位），不是列檔。 連結寫法：一律寫成[{文字}]({連結})。盤點頁欄位的連結放jsc-gitea/tools/gitea.sh wiki-url給的絕對網址，不自行組路徑，也不用[[頁名]]或[[顯示文字|頁名]]：後者只在同一個 wiki 內解析，寫錯不會報錯，畫面上看起來像純文字或死連結，巡不到也修不了。 寫入前驗證：要放進本頁的每一個連結先交給jsc-gitea/tools/link-check.sh，結束碼 0 才寫入。有一筆 DEAD 就整個區塊不寫，把連不到的清單回報給呼叫端。驗證走 API，不看網頁狀態碼：私有存取庫的網頁網址對沒帶金鑰的請求一律回 404，照狀態碼判會把還活著的頁判成死連結。結束碼1=至少一筆連不到、2=一個網址都沒給、3=GITEA_HOST未設定、7=金鑰失效，停下回報金鑰問題，不得當成連不到。 HASH：由jsc-gitea/tools/hash-id對該存取庫自己的{owner}/{repo}算出的完整 40 碼大寫十六進位，不截短、不加前綴。
REPO_{HASH}
- 存取庫：{owner}/{repo}
- 盤點頁：[{owner}/{repo}](https://{gitea 主機}/{owner}/{repo}/wiki/REPO_{HASH})
- HASH：{HASH}
- commit sha：
{sha} - 盤點時間：{yyyy-MM-dd}