feat(wiki): 目錄頁專用存取庫、HASH 去除截短與 H 前綴
What：CONTENTS 成為第 15 種頁面類型，解析鏈為 JSC_WIKI_REPO_CONTENTS 到 JSC_WIKI_REPO，刻意不退回型別變數。hash-id 拿掉 8 碼截短與 H 前綴改寫，只留大寫 轉換，輸出完整 40 碼；空輸入改成用法錯誤。新增 page-name.sh、wiki-contents.sh、 migrate-wiki.sh 與 wiki-delete 子命令。 Why：H 前綴會命中 16 個首碼裡的 13 個，還丟掉第 8 碼，把有效熵壓到 28 位元，而且 全庫查不到任何理由紀錄。目錄頁的整列 upsert 原本 14 處只有一處寫成程式，同一段判斷 做 14 次，錯一次就少一筆紀錄。 How：頁名樣式仍收 H 加 7 碼的舊頁，遷移期間讀得到舊頁。wiki-contents.sh 建新頁時 剝掉範本的示範列，否則每個目錄頁第一次建立都會留一列佔位死連結。migrate-wiki.sh 預設只印對照表，--apply 先寫新頁、確認寫成、才刪舊頁；孤兒頁只列不猜，因為 SHA-1 不可逆，新頁名只能靠候選鍵正推。 Who：jsc-gitea
This commit is contained in:
@@ -27,11 +27,13 @@ gitea.sh owners # 列出可讀取的 owner
|
||||
gitea.sh repos <owner> # 列出 owner 的 repo 全名
|
||||
gitea.sh default-branch <owner>/<repo>
|
||||
gitea.sh clone-url <owner>/<repo>
|
||||
gitea.sh hash-id <text> # 產生 8 碼大寫 SHA-1；首碼 0-9/A/B/C 時改成 Hxxxxxxx
|
||||
gitea.sh wiki-repo <TYPE> # 解析頁面類型的 wiki 位置（TYPE = QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT / SKILLSET / TOOLING / MONITOR）
|
||||
gitea.sh hash-id <text> # 產生完整 40 碼大寫 SHA-1
|
||||
gitea.sh wiki-repo <TYPE> # 解析頁面類型的 wiki 位置（TYPE = QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT / SKILLSET / TOOLING / MONITOR / CONTENTS）
|
||||
# 所有 *_CONTENTS 頁一律走 CONTENTS，內容頁走自己的型別
|
||||
gitea.sh wiki-list <owner>/<repo>
|
||||
gitea.sh wiki-get <owner>/<repo> <page> # 不存在 exit 4
|
||||
gitea.sh wiki-put <owner>/<repo> <page> <file> # 自動判斷新建或更新；會先要求確認
|
||||
gitea.sh wiki-delete <owner>/<repo> <page> # 刪除 wiki 頁；與 wiki-put 走同一道確認，頁不存在 exit 4
|
||||
gitea.sh wiki-url <owner>/<repo> <page> # 印出 wiki 頁絕對網址（取自 API 的 html_url）；跨存取庫連結用
|
||||
gitea.sh pr-create <owner>/<repo> <head> <base> <title> <body-file> # 會先要求確認
|
||||
gitea.sh pr-status <owner>/<repo> <pr-index> # 印出 {state} {merged} {mergeable}
|
||||
@@ -57,9 +59,27 @@ gitea.sh api <METHOD> <path> [json-file]
|
||||
# 7 與 8 一定要跟 4 分開：認證失敗若被讀成「頁面不存在」，
|
||||
# 附加寫入就會變成整頁覆蓋，舊紀錄直接消失
|
||||
hash-id <text> # 與 gitea.sh hash-id 相同
|
||||
# 結束碼 0=成功、1=沒有 sha1sum 也沒有 shasum、2=沒給文字或給了空字串
|
||||
page-name.sh regex | check <page> # 頁名樣式的唯一正本
|
||||
# 合法頁名 {型別}_(CONTENTS|8 碼|H 加 7 碼|40 碼大寫十六進位)
|
||||
# 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 存取庫未設定
|
||||
# 4=頁不存在且沒給範本、7=金鑰失效或權限不足、8=其他 API 失敗
|
||||
# 只有 4 才准建新頁；7 與 8 一律中止，不得當成「頁面不存在」
|
||||
migrate-wiki.sh [--apply] [--key <候選鍵>]... # 把舊頁搬到新規則：目錄頁換存取庫、內容頁換頁名
|
||||
# 只做正推配對，配不上的一律列成孤兒，不猜；不帶 --apply 只印對照表
|
||||
# 寫目的地之前先讀：只有 4 才准寫，0 列成需人工確認且不覆蓋，7 與 8 中止
|
||||
# 連結改寫只動被搬的頁；沒被搬的引用方另列一節，交給人改
|
||||
# 結束碼 0=全部搬完、1=有頁搬移失敗、2=用法錯誤、3=有需人工處理的項目
|
||||
repo-sync.sh <owner>/<repo> [target-dir] # 同步單一存取庫；印出 cloned、updated、dirty {分支} 或 failed {原因}
|
||||
# 基準分支的優先序只在這支腳本裡；dirty 會把解析好的分支帶出來當 PR 的 base
|
||||
check-wiki-rules.sh # 驗證 wiki repo 解析與 hash fallback 規則
|
||||
check-wiki-rules.sh # 驗證 wiki repo 解析、hash-id 與頁名樣式規則
|
||||
pr-watch.sh <owner>/<repo> <pr-index> [state-file]
|
||||
# 盯著一支 PR，直到它合併或關閉，不自動逾時退場
|
||||
# 退出碼 0 = 已合併或關閉、10 = 有新留言要接手、2 = 參數錯誤、3 = 查不到該 PR
|
||||
@@ -87,7 +107,7 @@ html-render.sh --markdown <檔案> --title <標題> --out <輸出檔> [--layout]
|
||||
|
||||
## 參考資料
|
||||
|
||||
- `references/wiki-links.md`：寫 wiki 頁才需要的連結規則。同類型用 `[[顯示文字|頁名]]`（顯示文字在左），跨類型用 `wiki-url` 給的絕對網址。
|
||||
- `references/wiki-links.md`：寫 wiki 頁才需要的連結規則。目錄頁之間、同型別的內容頁之間用 `[[顯示文字|頁名]]`（顯示文字在左）；目錄頁與內容頁之間以及跨型別，一律用 `wiki-url` 給的絕對網址。
|
||||
|
||||
## HTML 範本
|
||||
|
||||
@@ -122,7 +142,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）解析 wiki 所在的 `{owner}/{repo}`，先讀對應的 `JSC_WIKI_REPO_{TYPE}`，再退回 `JSC_WIKI_REPO`，不同類型不可互相代用。頁面內容以圖表優先（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`。頁面內容以圖表優先（mermaid 圖、markdown 表格），純文字每節最多三句。
|
||||
|
||||
### `repo-sync`
|
||||
|
||||
@@ -148,17 +168,18 @@ Gitea wiki 頁讀寫的統一入口：依頁面類型（QUESTION / PLAN / ANALYZ
|
||||
| --- | --- | --- |
|
||||
| `GITEA_HOST` | Gitea 站台（可省略 scheme，預設 https） | 詢問使用者 |
|
||||
| `GITEA_TOKEN` | Gitea API token；缺少或遇 401/403 時自動退回 tea CLI 登入 token | 詢問使用者 |
|
||||
| `JSC_WIKI_REPO_{TYPE}` | 各類型 wiki 頁的 `{owner}/{repo}`；TYPE = QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
|
||||
| `JSC_WIKI_REPO_SKILLSET` | `SKILLSET_CONTENTS`、`SKILLSET_{HASH}`（技能組異動報告）的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
|
||||
| `JSC_WIKI_REPO_TOOLING` | `TOOLING_CONTENTS`、`TOOLING_{HASH}`（技能盤點）的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
|
||||
| `JSC_WIKI_REPO_MONITOR` | `MONITOR_CONTENTS`、`MONITOR_{HASH}`（助理巡檢監控）的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
|
||||
| `JSC_WIKI_REPO_{TYPE}` | 各類型內容頁的 `{owner}/{repo}`；TYPE = QUESTION / PLAN / ANALYZE / DELIVER / MAINTAIN / REPO / LOG / LEARN / ERROR / CHECK / REPORT | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
|
||||
| `JSC_WIKI_REPO_SKILLSET` | `SKILLSET_{HASH}`（技能組異動報告）的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
|
||||
| `JSC_WIKI_REPO_TOOLING` | `TOOLING_{HASH}`（技能盤點）的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
|
||||
| `JSC_WIKI_REPO_MONITOR` | `MONITOR_{HASH}`（助理巡檢監控）的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不做跨類型代用 |
|
||||
| `JSC_WIKI_REPO_CONTENTS` | 全部目錄頁（各型別的 `*_CONTENTS`）共用的 `{owner}/{repo}` | 退回 `JSC_WIKI_REPO`，不退回各型別的變數 |
|
||||
| `JSC_WIKI_REPO` | 共用預設的 wiki `{owner}/{repo}` | 詢問使用者 |
|
||||
| `JSC_HOME` | `pr-watch.sh` 狀態檔的根目錄 | 預設 `~/.jsc` |
|
||||
| `JSC_PR_WATCH_INTERVAL` | `pr-watch.sh` 的輪詢間隔秒數（正整數） | 預設 60 |
|
||||
|
||||
## Hash 規則
|
||||
|
||||
`{HASH}` 一律由 `tools/hash-id` 產生。長度、大小寫、`H` 前綴與各頁型的雜湊來源，唯一來源是 `jsc-meta` 的 [`references/guidelines.md`](https://gitea.jsc.idv.tw/plugins/meta/src/branch/master/references/guidelines.md)「Wiki 頁命名總表」，這裡不再複述一份。
|
||||
`{HASH}` 一律由 `tools/hash-id` 產生：完整 40 碼大寫十六進位，不截短、不加前綴。頁名合不合規則交給 `tools/page-name.sh check` 判，不要另外寫一份樣式。各頁型的雜湊來源，唯一來源是 `jsc-meta` 的 [`references/guidelines.md`](https://gitea.jsc.idv.tw/plugins/meta/src/branch/master/references/guidelines.md)「Wiki 頁命名總表」，這裡不再複述一份。
|
||||
|
||||
## 相關 domain
|
||||
|
||||
|
||||
Reference in New Issue
Block a user