From 19d918f499f252268301739fdacce9953cdb1279 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Wed, 2 Sep 2026 17:21:10 +0800 Subject: [PATCH] =?UTF-8?q?docs(templates):=20=E4=BA=94=E5=80=8B=E7=9B=AE?= =?UTF-8?q?=E9=8C=84=E9=A0=81=E7=AF=84=E6=9C=AC=E6=94=B9=E6=88=90=E5=A4=A7?= =?UTF-8?q?=E6=A8=99=E9=A1=8C=E5=8A=A0=E6=A2=9D=E5=88=97?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 的實作不在本存取庫，本存取庫只提供範本與敘述。 --- templates/analyze-contents.md | 16 +++++++++++----- templates/deliver-contents.md | 18 +++++++++++++----- templates/maintain-contents.md | 15 ++++++++++----- templates/plan-contents.md | 16 +++++++++++----- templates/repo-contents.md | 15 ++++++++++----- 5 files changed, 55 insertions(+), 25 deletions(-) diff --git a/templates/analyze-contents.md b/templates/analyze-contents.md index 54f231f..7d0baf2 100644 --- a/templates/analyze-contents.md +++ b/templates/analyze-contents.md @@ -1,11 +1,17 @@ # 分析目錄 > 存放位置：本頁是目錄頁，落在 `JSC_WIKI_REPO_CONTENTS` 解出的專用存取庫（沒設定就退回 `JSC_WIKI_REPO`，都沒設定就停）。分析頁 `ANALYZE_{HASH}` 住在 `JSC_WIKI_REPO_ANALYZE` 那一邊，兩者不同存取庫。 -> 寫入語意：一列代表一份分析頁。一律用 `jsc-gitea/tools/wiki-contents.sh upsert ANALYZE 3 {HASH} {列檔} {本範本}` 單列寫回：該分析頁已經有列就更新那一列，沒有才附加一列，整頁一起送出。禁止整頁覆蓋，也不得改動別人的列。 +> 版面：一個 H1 頁名、一段 `>` 引言，接著每一筆一個 H2 區塊。H2 標題就是該筆分析頁的實際頁名（示範區塊寫成 `ANALYZE_{HASH}` 只是佔位符，真正要填的是 `jsc-sdlc:analyze` 剛寫出去那一頁的頁名，線上實際長成 `ANALYZE_20260821_100552_104F0709` 這樣），標題不放連結、不加前後綴。欄位是標題底下的一層條列，一欄一條，格式 `- {欄位名}：{值}`。本頁不留 markdown 表格。 +> 寫入語意：一個區塊代表一份分析頁。一律用 `jsc-gitea/tools/wiki-contents.sh upsert ANALYZE 2 {分析頁頁名} {區塊檔} {本範本}` 單筆寫回：該分析頁已經有區塊就更新那個區塊，沒有才附加一個區塊，整頁一起送出。禁止整頁覆蓋，也不得改動別人的區塊。參數語意：`2` 是舊表格裡持有內容頁連結那一欄的序號，也就是「分析頁」欄，只供自動轉檔用——本頁還是舊表格時，腳本從那一欄的連結網址取最後一段路徑當 H2 標題；本頁已經是條列版面就完全忽略它。這個序號填錯，轉出來的標題就跟鍵對不上，既有那一筆會被當成新的附加上去，同一份分析變成兩個區塊，舊區塊從此再也更新不到，所以不是死參數、也不能隨便填。`{分析頁頁名}` 是 H2 標題，填這一筆對應內容頁的實際頁名，也就是技能自己剛寫的那一頁的頁名，不套 `ANALYZE_{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`=金鑰失效，停下回報金鑰問題，不得當成連不到。 +> 寫入前驗證：要放進本頁的每一個連結先交給 `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 碼大寫十六進位，不截短、不加前綴。 -| 計畫名稱 | 分析頁 | HASH | 工作包 | 未完成項目 | 狀態 | -| --- | --- | --- | --- | --- | --- | -| {計畫名稱} | [{計畫名稱}](https://{gitea 主機}/{owner}/{repo}/wiki/ANALYZE_{HASH}) | {HASH} | WP-01、WP-02 | {n} | 未完成 | +## ANALYZE_{HASH} + +- 計畫名稱：{計畫名稱} +- 分析頁：[{計畫名稱}](https://{gitea 主機}/{owner}/{repo}/wiki/ANALYZE_{HASH}) +- HASH：{HASH} +- 工作包：WP-01、WP-02 +- 未完成項目：{n} +- 狀態：未完成 diff --git a/templates/deliver-contents.md b/templates/deliver-contents.md index b2a31b8..ced4da0 100644 --- a/templates/deliver-contents.md +++ b/templates/deliver-contents.md @@ -1,13 +1,21 @@ # 交付目錄 > 存放位置：本頁是目錄頁，落在 `JSC_WIKI_REPO_CONTENTS` 解出的專用存取庫（沒設定就退回 `JSC_WIKI_REPO`，都沒設定就停）。交付頁 `DELIVER_{HASH}` 住在 `JSC_WIKI_REPO_DELIVER` 那一邊，兩者不同存取庫。 -> 寫入語意：一列代表一個工作包的交付。一律用 `jsc-gitea/tools/wiki-contents.sh upsert DELIVER 6 {HASH} {列檔} {本範本}` 單列寫回：該工作包已經有列就更新那一列，沒有才附加一列，整頁一起送出。禁止整頁覆蓋，也不得改動別人的列。 +> 版面：一個 H1 頁名、一段 `>` 引言，接著每一筆一個 H2 區塊。H2 標題就是該筆交付頁的實際頁名（示範區塊寫成 `DELIVER_{HASH}` 只是佔位符，真正要填的是 `jsc-sdlc:implement` 剛寫出去那一頁的頁名），標題不放連結、不加前後綴。欄位是標題底下的一層條列，一欄一條，格式 `- {欄位名}：{值}`。本頁不留 markdown 表格。 +> 寫入語意：一個區塊代表一個工作包的交付。一律用 `jsc-gitea/tools/wiki-contents.sh upsert DELIVER 5 {交付頁頁名} {區塊檔} {本範本}` 單筆寫回：該工作包已經有區塊就更新那個區塊，沒有才附加一個區塊，整頁一起送出。禁止整頁覆蓋，也不得改動別人的區塊。參數語意：`5` 是舊表格裡持有內容頁連結那一欄的序號，也就是「交付頁」欄，只供自動轉檔用——本頁還是舊表格時，腳本從那一欄的連結網址取最後一段路徑當 H2 標題；本頁已經是條列版面就完全忽略它。這個序號填錯，轉出來的標題就跟鍵對不上，既有那一筆會被當成新的附加上去，同一個工作包的交付變成兩個區塊，舊區塊從此再也更新不到，所以不是死參數、也不能隨便填。`{交付頁頁名}` 是 H2 標題，填這一筆對應內容頁的實際頁名，也就是技能自己剛寫的那一頁的頁名，不套 `DELIVER_{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`=金鑰失效，停下回報金鑰問題，不得當成連不到。 +> 寫入前驗證：要放進本頁的每一個連結先交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫入。有一筆 DEAD 就整個區塊不寫，把連不到的清單回報給呼叫端。驗證走 API，不看網頁狀態碼：私有存取庫的網頁網址對沒帶金鑰的請求一律回 404，照狀態碼判會把還活著的頁判成死連結。結束碼 `1`=至少一筆連不到、`2`=一個網址都沒給、`3`=`GITEA_HOST` 未設定、`7`=金鑰失效，停下回報金鑰問題，不得當成連不到。 > HASH：由 `jsc-gitea/tools/hash-id` 對 `{owner}/{repo}` 加工作包編號（例 `plugins/sdlc#WP-01`）算出的完整 40 碼大寫十六進位，不截短、不加前綴。一個工作包一頁，彼此不覆蓋。 -| 計畫名稱 | 工作包 | 交付 | 交付型別 | 交付頁 | HASH | 存取庫 | 交付時間 | -| --- | --- | --- | --- | --- | --- | --- | --- | -| {計畫名稱} | WP-01 {工作包名稱} | 是 | API 文件 | [{WP-01 工作包名稱}](https://{gitea 主機}/{owner}/{repo}/wiki/DELIVER_{HASH}) | {HASH} | {owner}/{repo} | {yyyy-MM-dd HH:mm:ss} | +## DELIVER_{HASH} + +- 計畫名稱：{計畫名稱} +- 工作包：WP-01 {工作包名稱} +- 交付：是 +- 交付型別：API 文件 +- 交付頁：[{WP-01 工作包名稱}](https://{gitea 主機}/{owner}/{repo}/wiki/DELIVER_{HASH}) +- HASH：{HASH} +- 存取庫：{owner}/{repo} +- 交付時間：{yyyy-MM-dd HH:mm:ss} diff --git a/templates/maintain-contents.md b/templates/maintain-contents.md index aa7a7ff..9a705c0 100644 --- a/templates/maintain-contents.md +++ b/templates/maintain-contents.md @@ -1,12 +1,17 @@ # 維護目錄 > 存放位置：本頁是目錄頁，落在 `JSC_WIKI_REPO_CONTENTS` 解出的專用存取庫（沒設定就退回 `JSC_WIKI_REPO`，都沒設定就停）。`MAINTAIN` 只有目錄頁、沒有內容頁，所以整個型別的紀錄就在這一頁。 -> 寫入語意：一列代表一個受維護的存取庫。一律用 `jsc-gitea/tools/wiki-contents.sh upsert MAINTAIN 1 {owner}/{repo} {列檔} {本範本}` 單列寫回：該存取庫已經有列就更新那一列，沒有才附加一列，整頁一起送出。禁止整頁覆蓋，也不得改動別人的列。 +> 版面：一個 H1 頁名、一段 `>` 引言，接著每一筆一個 H2 區塊。`MAINTAIN` 沒有內容頁，所以 H2 標題就是該存取庫的 `{owner}/{repo}`，標題不放連結、不加前後綴。存取庫名不會漂移，當鍵一樣穩；反過來造一個 `MAINTAIN_{HASH}` 式的標題，等於指向一個不存在的頁。欄位是標題底下的一層條列，一欄一條，格式 `- {欄位名}：{值}`。本頁不留 markdown 表格。 +> 寫入語意：一個區塊代表一個受維護的存取庫。一律用 `jsc-gitea/tools/wiki-contents.sh upsert MAINTAIN 1 {owner}/{repo} {區塊檔} {本範本}` 單筆寫回：該存取庫已經有區塊就更新那個區塊，沒有才附加一個區塊，整頁一起送出。禁止整頁覆蓋，也不得改動別人的區塊。參數語意：`1` 是舊表格裡持有這一筆身分的那一欄的序號，也就是「存取庫」欄，只供自動轉檔用——本頁還是舊表格時，腳本靠這一欄取出 H2 標題（該欄沒有連結，就取格子純文字）；本頁已經是條列版面就完全忽略它。這個序號填錯，轉出來的標題就跟鍵對不上，既有那一筆會被當成新的附加上去，同一個存取庫變成兩個區塊，舊區塊從此再也更新不到，所以不是死參數、也不能隨便填。`{owner}/{repo}` 是 H2 標題，用來找既有區塊，寫這個存取庫實際的 `{owner}/{repo}`；`{區塊檔}` 是整個 H2 區塊的 markdown（`## {owner}/{repo}` 那一行加各條欄位），不是列檔。 > 連結寫法：一律寫成 `[{文字}]({連結})`。要指向別的頁型（例如交付頁）時，連結放 `jsc-gitea/tools/gitea.sh wiki-url` 給的絕對網址，不自行組路徑，也不用 `[[頁名]]` 或 `[[顯示文字|頁名]]`：後者只在同一個 wiki 內解析，寫錯不會報錯，畫面上看起來像純文字或死連結，巡不到也修不了。 -> 寫入前驗證：要放進本頁的每一個連結先交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫入。有一筆 DEAD 就整列不寫，把連不到的清單回報給呼叫端。驗證走 API，不看網頁狀態碼：私有存取庫的網頁網址對沒帶金鑰的請求一律回 404，照狀態碼判會把還活著的頁判成死連結。結束碼 `1`=至少一筆連不到、`2`=一個網址都沒給、`3`=`GITEA_HOST` 未設定、`7`=金鑰失效，停下回報金鑰問題，不得當成連不到。 +> 寫入前驗證：要放進本頁的每一個連結先交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫入。有一筆 DEAD 就整個區塊不寫，把連不到的清單回報給呼叫端。驗證走 API，不看網頁狀態碼：私有存取庫的網頁網址對沒帶金鑰的請求一律回 404，照狀態碼判會把還活著的頁判成死連結。結束碼 `1`=至少一筆連不到、`2`=一個網址都沒給、`3`=`GITEA_HOST` 未設定、`7`=金鑰失效，停下回報金鑰問題，不得當成連不到。 -| 存取庫 | 維護方式 | 維護起始日 | 維護截止日 | 前次維護時間 | -| --- | --- | --- | --- | --- | -| {owner}/{repo} | {例：套件更新與安全掃描} | {yyyy-MM-dd} | NULL | {yyyy-MM-dd} | +## {owner}/{repo} + +- 存取庫：{owner}/{repo} +- 維護方式：{例：套件更新與安全掃描} +- 維護起始日：{yyyy-MM-dd} +- 維護截止日：NULL +- 前次維護時間：{yyyy-MM-dd} diff --git a/templates/plan-contents.md b/templates/plan-contents.md index 925d878..6cfd0f7 100644 --- a/templates/plan-contents.md +++ b/templates/plan-contents.md @@ -1,11 +1,17 @@ # 計畫目錄 > 存放位置：本頁是目錄頁，落在 `JSC_WIKI_REPO_CONTENTS` 解出的專用存取庫（沒設定就退回 `JSC_WIKI_REPO`，都沒設定就停）。計畫頁 `PLAN_{HASH}` 住在 `JSC_WIKI_REPO_PLAN` 那一邊，兩者不同存取庫。 -> 寫入語意：一列代表一份計畫。一律用 `jsc-gitea/tools/wiki-contents.sh upsert PLAN 4 {HASH} {列檔} {本範本}` 單列寫回：該計畫已經有列就更新那一列，沒有才附加一列，整頁一起送出。禁止整頁覆蓋，也不得改動別人的列。 +> 版面：一個 H1 頁名、一段 `>` 引言，接著每一筆一個 H2 區塊。H2 標題就是該筆計畫頁的實際頁名（示範區塊寫成 `PLAN_{HASH}` 只是佔位符，真正要填的是 `jsc-sdlc:plan` 剛寫出去那一頁的頁名），標題不放連結、不加前後綴。欄位是標題底下的一層條列，一欄一條，格式 `- {欄位名}：{值}`。本頁不留 markdown 表格。 +> 寫入語意：一個區塊代表一份計畫。一律用 `jsc-gitea/tools/wiki-contents.sh upsert PLAN 2 {計畫頁頁名} {區塊檔} {本範本}` 單筆寫回：該計畫已經有區塊就更新那個區塊，沒有才附加一個區塊，整頁一起送出。禁止整頁覆蓋，也不得改動別人的區塊。參數語意：`2` 是舊表格裡持有內容頁連結那一欄的序號，也就是「計畫頁」欄，只供自動轉檔用——本頁還是舊表格時，腳本從那一欄的連結網址取最後一段路徑當 H2 標題；本頁已經是條列版面就完全忽略它。這個序號填錯，轉出來的標題就跟鍵對不上，既有那一筆會被當成新的附加上去，同一份計畫變成兩個區塊，舊區塊從此再也更新不到，所以不是死參數、也不能隨便填。`{計畫頁頁名}` 是 H2 標題，填這一筆對應內容頁的實際頁名，也就是技能自己剛寫的那一頁的頁名，不套 `PLAN_{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`=金鑰失效，停下回報金鑰問題，不得當成連不到。 +> 寫入前驗證：要放進本頁的每一個連結先交給 `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 碼大寫十六進位，不截短、不加前綴。 -| 計畫名稱 | 計畫頁 | 存取庫 | HASH | 狀態 | 建立時間 | -| --- | --- | --- | --- | --- | --- | -| {計畫名稱} | [{計畫名稱}](https://{gitea 主機}/{owner}/{repo}/wiki/PLAN_{HASH}) | {owner}/{repo} | {HASH} | 未分析 | {yyyy-MM-dd} | +## PLAN_{HASH} + +- 計畫名稱：{計畫名稱} +- 計畫頁：[{計畫名稱}](https://{gitea 主機}/{owner}/{repo}/wiki/PLAN_{HASH}) +- 存取庫：{owner}/{repo} +- HASH：{HASH} +- 狀態：未分析 +- 建立時間：{yyyy-MM-dd} diff --git a/templates/repo-contents.md b/templates/repo-contents.md index 9186e34..3a3233e 100644 --- a/templates/repo-contents.md +++ b/templates/repo-contents.md @@ -1,11 +1,16 @@ # 盤點目錄 > 存放位置：本頁是目錄頁，落在 `JSC_WIKI_REPO_CONTENTS` 解出的專用存取庫（沒設定就退回 `JSC_WIKI_REPO`，都沒設定就停）。盤點頁 `REPO_{HASH}` 住在 `JSC_WIKI_REPO_REPO` 那一邊，兩者不同存取庫。 -> 寫入語意：一列代表一個存取庫的盤點。一律用 `jsc-gitea/tools/wiki-contents.sh upsert REPO 1 {owner}/{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`=金鑰失效，停下回報金鑰問題，不得當成連不到。 +> 寫入前驗證：要放進本頁的每一個連結先交給 `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 碼大寫十六進位，不截短、不加前綴。 -| 存取庫 | 盤點頁 | HASH | commit sha | 盤點時間 | -| --- | --- | --- | --- | --- | -| {owner}/{repo} | [{owner}/{repo}](https://{gitea 主機}/{owner}/{repo}/wiki/REPO_{HASH}) | {HASH} | `{sha}` | {yyyy-MM-dd} | +## REPO_{HASH} + +- 存取庫：{owner}/{repo} +- 盤點頁：[{owner}/{repo}](https://{gitea 主機}/{owner}/{repo}/wiki/REPO_{HASH}) +- HASH：{HASH} +- commit sha：`{sha}` +- 盤點時間：{yyyy-MM-dd}