docs(wiki): 同步目錄頁條列格式的敘述與工具用法
README 的工具用法、技能行為清單、連結規則與 wiki 技能本文，全部改寫成 目錄頁的區塊格式：參數名從整列改成整個區塊、key-col 的用途縮回只給轉檔 用、補上取標題與換引言的判準，並登錄新增的驗證腳本。 文件與工具講的不是同一件事，呼叫端就會照舊敘述傳整列的表格文字進去，寫出 半表格半條列的頁面。key-col 的語意變動最容易誤解——它從「要換掉哪一欄」 變成「轉檔時哪一欄持有身分」，敘述不改就會被填成別的欄位。 目錄頁條列、內容頁維持圖表優先，這個區分在每一份文件裡都寫明，避免把改版 範圍誤讀成整個 wiki。結束碼說明一併對回工具現況。 功能範圍：目錄頁版面改版的文件同步。
This commit is contained in:
@@ -66,13 +66,22 @@ page-name.sh regex | check <page> # 頁名樣式的唯一正本
|
||||
# 8 碼與 H 加 7 碼留給尚未遷移的舊頁；舊演算法多數情況會加 H，兩種都要收
|
||||
# 前綴只收十四種內容型別。CONTENTS 只解存取庫，沒有 CONTENTS_CONTENTS 這一頁
|
||||
# 結束碼 0=合法、1=不合法、2=用法錯誤
|
||||
wiki-contents.sh upsert <TYPE> <key-col> <key> <row-file> [template-file]
|
||||
# 目錄頁的整列 upsert：解 CONTENTS 存取庫、讀舊頁、換掉鍵相同那一列或附加到表尾、整頁寫回
|
||||
# key-col 是 1 起算的欄位序號，不是欄位名稱
|
||||
# 用範本建新頁時剝掉分隔列之後的示範列，正式頁上不留佔位的死連結
|
||||
# 結束碼 0=已更新或已新增、1=寫入失敗、2=用法錯誤、3=CONTENTS 存取庫未設定
|
||||
wiki-contents.sh upsert <TYPE> <key-col> <key> <entry-file> [template-file]
|
||||
# 目錄頁的區塊 upsert：解 CONTENTS 存取庫、讀舊頁、換掉「## {key}」那一塊或附加到頁尾、整頁寫回
|
||||
# 目錄頁一筆一個 H2 區塊：標題就是內容頁頁名，欄位是底下一層條列「- {欄位名}：{值}」
|
||||
# entry-file 放整個 H2 區塊；舊頁還是表格時先整頁轉成區塊，再做 upsert
|
||||
# key-col 只給轉檔用：舊表格裡持有身分那一欄的序號，1 起算，頁面已是條列就忽略
|
||||
# 轉檔的 H2 標題只看那一格：有連結取網址最後一段路徑（百分號編碼先解碼），沒連結取純文字
|
||||
# 連結文字常常是工作包或計畫名稱不是頁名；拿它當標題會跟呼叫端的鍵對不上，同一筆長出第二個區塊
|
||||
# 轉檔那一次有給範本，就連 H1 與「>」引言一起換成範本那一份：只搬表格不動散文，舊引言會一直講「一列一筆」
|
||||
# 頁面已是條列就不動引言，那時只是更新自己那一筆；沒給範本也保留舊引言，沒有正本可換
|
||||
# 用範本建新頁時剝掉示範區塊，只留 H1 與引言，正式頁上不留佔位的死紀錄
|
||||
# 結束碼 0=已更新或已新增、1=組不出頁面內容或寫入失敗、2=用法錯誤、3=CONTENTS 存取庫未設定
|
||||
# 4=頁不存在且沒給範本、7=金鑰失效或權限不足、8=其他 API 失敗
|
||||
# 只有 4 才准建新頁；7 與 8 一律中止，不得當成「頁面不存在」
|
||||
wiki-contents.sh format <key-col> <key> <entry-file> <old-file> <new-file> [template-file|--fresh]
|
||||
# 同一份轉檔與 upsert 判斷，只讀寫檔案、不碰 API，供離線驗證用
|
||||
# 第六個參數給 --fresh 是「old-file 就是範本」，給路徑則等同 upsert 的範本檔
|
||||
migrate-wiki.sh [--apply] [--key <候選鍵>]... # 把舊頁搬到新規則：目錄頁換存取庫、內容頁換頁名
|
||||
# 只做正推配對，配不上的一律列成孤兒，不猜；不帶 --apply 只印對照表
|
||||
# 寫目的地之前先讀：只有 4 才准寫，0 列成需人工確認且不覆蓋，7 與 8 中止
|
||||
@@ -81,6 +90,7 @@ migrate-wiki.sh [--apply] [--key <候選鍵>]... # 把舊頁搬到新規則
|
||||
repo-sync.sh <owner>/<repo> [target-dir] # 同步單一存取庫；印出 cloned、updated、dirty {分支} 或 failed {原因}
|
||||
# 基準分支的優先序只在這支腳本裡；dirty 會把解析好的分支帶出來當 PR 的 base
|
||||
check-wiki-rules.sh # 驗證 wiki repo 解析、hash-id 與頁名樣式規則
|
||||
check-contents-format.sh # 驗證目錄頁的區塊轉檔與 upsert 規則；全走 format 子命令，不打 API
|
||||
link-check.sh <網址>... # 連結寫進文件之前先驗證連得到；也吃標準輸入，一行一個
|
||||
# 每個網址一行「{OK|DEAD|SKIP}<TAB>{網址}<TAB>{說明}」
|
||||
# wiki 頁與議題轉成 API 查，其他 Gitea 網址帶金鑰 HEAD，外部網址不帶金鑰 HEAD
|
||||
@@ -150,7 +160,7 @@ html-render.sh --markdown <檔案> --title <標題> --out <輸出檔> [--layout]
|
||||
|
||||
### `wiki`
|
||||
|
||||
Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT / SKILLSET / TOOLING / MONITOR / CONTENTS）解析 wiki 所在的 `{owner}/{repo}`，先讀對應的 `JSC_WIKI_REPO_{TYPE}`，再退回 `JSC_WIKI_REPO`，不同類型不可互相代用。所有 `*_CONTENTS` 頁一律走 `CONTENTS` 這個型別，內容頁走自己的型別；目錄頁的整列 upsert 交給 `tools/wiki-contents.sh`。頁面內容以圖表優先（mermaid 圖、markdown 表格），純文字每節最多三句。
|
||||
Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT / SKILLSET / TOOLING / MONITOR / CONTENTS）解析 wiki 所在的 `{owner}/{repo}`，先讀對應的 `JSC_WIKI_REPO_{TYPE}`，再退回 `JSC_WIKI_REPO`，不同類型不可互相代用。所有 `*_CONTENTS` 頁一律走 `CONTENTS` 這個型別，內容頁走自己的型別；目錄頁的區塊 upsert 交給 `tools/wiki-contents.sh`，一筆紀錄一個 H2 區塊，標題就是內容頁頁名，欄位是底下一層條列。內容頁的內容以圖表優先（mermaid 圖、markdown 表格），純文字每節最多三句；目錄頁不放表格。
|
||||
|
||||
### `repo-sync`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user