plugins/gitea
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

wiki 目錄頁改成大標題加條列，舊表格讀到就自動轉檔 #52

Merged
admin merged 5 commits from feat/contents-list/main into develop 2026-09-02 10:00:22 +00:00
Conversation 0 Commits 5 Files Changed 10
+871 -122
jiantw83 commented 2026-09-02 09:23:42 +00:00
Member
Copy Link
Copy Source

摘要

  • 需求描述：所有 wiki 目錄頁（*_CONTENTS）的呈現格式從 markdown 表格改成「大標題加條列」，一筆紀錄一個 H2 區塊，H2 標題就是這一筆的鍵，欄位是標題底下一層的條列 - {欄位名}：{值}，目錄頁上不留任何 markdown 表格；內容頁維持原本的圖表優先，不在這一輪範圍。
  • 計畫名稱：無
  • 計畫頁：無
  • 分析頁：無

**這一支是整批變更的相依前提，必須先合。**其餘七個 domain 只改敘述與範本，實際的轉檔與 upsert 邏輯全部在 gitea/tools/wiki-contents.sh。這一支沒合之前就部署別的 domain，範本組出來的 H2 區塊會被舊版工具當成表格列，直接附加到表格後面，線上目錄頁會變成半表格半條列。

變更內容

檔案 為什麼改
tools/wiki-contents.sh 主體從整列 upsert 改寫成 H2 區塊 upsert：讀到的舊頁還是表格就先整頁轉成區塊再做 upsert，H2 標題改取網址最後一段路徑，轉檔那一次有給範本就連 H1 與引言一起換掉；另外拆出 format 子命令，把組頁邏輯與 API 呼叫分開，離線驗證才叫得到
tools/check-contents-format.sh 新增。只讀寫暫存檔、不打 API 的離線驗證，涵蓋五種舊頁狀態、四種身分欄取標題情形、五種引言情形
tools/migrate-wiki.sh 候選鍵解析擴充成條列與表格兩種目錄頁形狀都吃。目錄頁已改條列、線上舊頁仍是表格，同一輪搬頁會同時遇到兩種；只讀表格會讓條列頁一個候選鍵都收不到，那些頁會被當成沒有對應而漏掉
README.md、references/behaviors.md、references/wiki-links.md、skills/wiki/SKILL.md 文件與工具講的不是同一件事，呼叫端就會照舊敘述傳整列的表格文字進去。同步參數名、key-col 的新語意、取標題與換引言的判準、結束碼，並登錄新增的驗證腳本
.claude-plugin/plugin.json、.codex-plugin/plugin.json、plugin.json 對外行為變了，版本號不動版本守衛就看不出機器上裝的是舊版工具。三份 manifest 同步升版至 0.2.5

設計重點

四個決策：

決策點 答案
版面形狀 每一筆一個 H2 大標題，欄位改成標題底下的一層條列
鍵的落點 H2 標題本身就是鍵，寫成該筆對應內容頁的實際頁名
既有表格頁 wiki-contents.sh 讀到表格就自動轉成條列後寫回，不另跑批次搬移
邏輯落點 改 gitea/tools/wiki-contents.sh，不新增第二支工具

另外兩項後續決定：轉檔時用範本引言取代舊引言；線上 SKILLSET_CONTENTS 與 MONITOR_CONTENTS 的髒資料這一輪清乾淨（已完成）。

稽核抓到並已修掉的三類缺陷：

  • 六個頁型的 key-col 填錯：QUESTION、PLAN、ANALYZE、DELIVER、REPO、SKILLSET。填錯會讓轉檔產出的標題跟鍵對不上，既有那一筆被當成新的附加上去，同一筆變成兩個區塊，舊區塊從此再也更新不到。已逐頁對回線上實際欄位修正。
  • H2 標題取錯來源：轉檔原本只取連結的顯示文字，但線上有顯示文字不是頁名的資料（例如顯示成工作包或計畫名稱）。改成取網址最後一段路徑，並解掉百分號編碼。
  • 範本夾帶說明用的 ## 區段：三個範本除了示範區塊之外還有說明段落，會在正式頁上被讀成假紀錄。說明內容搬進 > 引言。

其他防護：身分欄取不出鍵就整支擋下來，不猜標題；頁面已是條列時只更新自己那一筆，不動引言；用範本建新頁時剝掉示範區塊，正式頁上不留佔位的死紀錄。

測試結果

  • sh tools/check-contents-format.sh → 印 OK，結束碼 0。五種舊頁狀態、四種取標題情形、五種引言情形全數通過，另含「表格取不出鍵要擋下」「轉檔後重跑同一筆結果一字不變」「區塊檔沒帶標題也照樣補上」三項。
  • sh /root/plugins/hooks/hooks/comment-scope.sh sweep → 無命中，結束碼 0。

前置 Push Request

  • 無
## 摘要 - 需求描述：所有 wiki 目錄頁（`*_CONTENTS`）的呈現格式從 markdown 表格改成「大標題加條列」，一筆紀錄一個 H2 區塊，H2 標題就是這一筆的鍵，欄位是標題底下一層的條列 `- {欄位名}：{值}`，目錄頁上不留任何 markdown 表格；內容頁維持原本的圖表優先，不在這一輪範圍。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 > **這一支是整批變更的相依前提，必須先合。**其餘七個 domain 只改敘述與範本，實際的轉檔與 upsert 邏輯全部在 `gitea/tools/wiki-contents.sh`。這一支沒合之前就部署別的 domain，範本組出來的 H2 區塊會被舊版工具當成表格列，直接附加到表格後面，線上目錄頁會變成半表格半條列。 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `tools/wiki-contents.sh` | 主體從整列 upsert 改寫成 H2 區塊 upsert：讀到的舊頁還是表格就先整頁轉成區塊再做 upsert，H2 標題改取網址最後一段路徑，轉檔那一次有給範本就連 H1 與引言一起換掉；另外拆出 `format` 子命令，把組頁邏輯與 API 呼叫分開，離線驗證才叫得到 | | `tools/check-contents-format.sh` | 新增。只讀寫暫存檔、不打 API 的離線驗證，涵蓋五種舊頁狀態、四種身分欄取標題情形、五種引言情形 | | `tools/migrate-wiki.sh` | 候選鍵解析擴充成條列與表格兩種目錄頁形狀都吃。目錄頁已改條列、線上舊頁仍是表格，同一輪搬頁會同時遇到兩種；只讀表格會讓條列頁一個候選鍵都收不到，那些頁會被當成沒有對應而漏掉 | | `README.md`、`references/behaviors.md`、`references/wiki-links.md`、`skills/wiki/SKILL.md` | 文件與工具講的不是同一件事，呼叫端就會照舊敘述傳整列的表格文字進去。同步參數名、`key-col` 的新語意、取標題與換引言的判準、結束碼，並登錄新增的驗證腳本 | | `.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json` | 對外行為變了，版本號不動版本守衛就看不出機器上裝的是舊版工具。三份 manifest 同步升版至 `0.2.5` | ## 設計重點 四個決策： | 決策點 | 答案 | | --- | --- | | 版面形狀 | 每一筆一個 H2 大標題，欄位改成標題底下的一層條列 | | 鍵的落點 | H2 標題本身就是鍵，寫成該筆對應內容頁的實際頁名 | | 既有表格頁 | `wiki-contents.sh` 讀到表格就自動轉成條列後寫回，不另跑批次搬移 | | 邏輯落點 | 改 `gitea/tools/wiki-contents.sh`，不新增第二支工具 | 另外兩項後續決定：轉檔時用範本引言取代舊引言；線上 `SKILLSET_CONTENTS` 與 `MONITOR_CONTENTS` 的髒資料這一輪清乾淨（已完成）。 稽核抓到並已修掉的三類缺陷： - **六個頁型的 `key-col` 填錯**：QUESTION、PLAN、ANALYZE、DELIVER、REPO、SKILLSET。填錯會讓轉檔產出的標題跟鍵對不上，既有那一筆被當成新的附加上去，同一筆變成兩個區塊，舊區塊從此再也更新不到。已逐頁對回線上實際欄位修正。 - **H2 標題取錯來源**：轉檔原本只取連結的顯示文字，但線上有顯示文字不是頁名的資料（例如顯示成工作包或計畫名稱）。改成取網址最後一段路徑，並解掉百分號編碼。 - **範本夾帶說明用的 `## ` 區段**：三個範本除了示範區塊之外還有說明段落，會在正式頁上被讀成假紀錄。說明內容搬進 `>` 引言。 其他防護：身分欄取不出鍵就整支擋下來，不猜標題；頁面已是條列時只更新自己那一筆，不動引言；用範本建新頁時剝掉示範區塊，正式頁上不留佔位的死紀錄。 ## 測試結果 - `sh tools/check-contents-format.sh` → 印 `OK`，結束碼 0。五種舊頁狀態、四種取標題情形、五種引言情形全數通過，另含「表格取不出鍵要擋下」「轉檔後重跑同一筆結果一字不變」「區塊檔沒帶標題也照樣補上」三項。 - `sh /root/plugins/hooks/hooks/comment-scope.sh sweep` → 無命中，結束碼 0。 ## 前置 Push Request - 無
jiantw83 added 5 commits 2026-09-02 09:23:42 +00:00
refactor(wiki-contents): 目錄頁改成 H2 區塊 upsert，舊表格自動轉檔 2e8712126f 
目錄頁的一筆紀錄從 markdown 表格的一列，改成一個 H2 區塊：標題就是這一筆
對應內容頁的頁名，欄位變成標題底下一層的條列「- {欄位名}：{值}」。upsert
換掉標題相同那一塊，找不到就附加到頁尾。

表格一列擠著所有欄位，欄位一多就超出可讀寬度，得橫向捲才看得完；換行之後
也分不出哪幾格屬於同一筆。條列沒有寬度上限，一筆看得完整。

讀到的舊頁還是表格，就先整頁轉成區塊再在轉好的頁面上做 upsert，一頁同時
有表格與區塊也照樣接得起來。轉檔取標題只看持有身分那一欄：有連結取網址
最後一段路徑並解掉百分號編碼，沒連結取純文字——連結的顯示文字常常是計畫
或工作包名稱而不是頁名，拿它當標題會跟呼叫端傳進來的鍵對不上，同一筆長出
第二個區塊，舊的那塊從此再也更新不到。那一欄取不出鍵就整支擋下來，不猜
標題。轉檔那一次有給範本，就連 H1 與引言一起換成範本那一份，舊引言否則
會一直講「一列一筆」；頁面已是條列時只更新自己那一筆，不動引言。組頁邏輯
另外拆出 format 子命令，離線驗證才叫得到，不必打 API。

功能範圍：目錄頁版面改版，涵蓋所有以 _CONTENTS 結尾的頁面與每一支寫目錄
頁的技能。
test(check-contents-format): 新增目錄頁區塊格式的離線驗證 c7c14445e6 
新增一支只讀寫暫存檔的驗證腳本，全程走 format 子命令，涵蓋五種舊頁狀態：
純表格、已是條列且鍵命中、已是條列且鍵未命中、表格與區塊混合、用範本建
新頁。另外驗身分欄取標題的四種情形與引言的五種情形。

轉檔與 upsert 的錯法都是靜默的：標題取錯只會多長一個區塊，引言沒換掉只是
說明過期，兩種都不會報錯，要等到線上頁面壞掉才看得出來。手動打 API 驗又
會在正式頁上留下試出來的垃圾紀錄。

驗證只比對輸入與輸出檔，不碰網路，任何機器上都跑得完。除了正常流程還特別
釘住三件事：表格取不出鍵那一列要擋下來不猜標題、轉檔後拿結果重跑同一筆
必須一字不變、區塊檔沒帶標題也照樣補上。任一項不符就印出期望值與實際值
之後立刻停住，不續跑其餘項目。

功能範圍：目錄頁版面改版的迴歸防護。
fix(migrate-wiki): 候選鍵兼收條列與表格兩種目錄頁形狀 9942cf2506 
搬頁時蒐集候選鍵的那一段，原本只讀目錄頁表格的存取庫、主機、帳號、工具、
期間五欄。現在改成 H2 區塊底下的「- {欄位名}：{值}」也照樣讀，表格的欄位
維持原樣收下，兩種形狀都認得。

目錄頁已經改成條列，還沒轉檔的線上舊頁卻仍是表格，同一輪搬頁會同時遇到
兩種。只讀表格的話，條列頁一個候選鍵都收不到，那些頁的舊頁名就對不到新
頁名，搬頁會把它們當成沒有對應而漏掉。

讀取改成逐行判斷：碰到「## 」就把上一個區塊收掉並開新的一筆，區塊內的
條列按欄位名對照收值。欄位值各自算一個候選鍵，再依固定欄位順序串一個組合
鍵，跟表格那一路的產出規則完全一致。條列的冒號正本寫全形，半形也一併收，
舊頁手寫的那幾條才不會整條漏掉。

功能範圍：目錄頁版面改版的搬頁相容。
docs(wiki): 同步目錄頁條列格式的敘述與工具用法 89463cd263 
README 的工具用法、技能行為清單、連結規則與 wiki 技能本文，全部改寫成
目錄頁的區塊格式：參數名從整列改成整個區塊、key-col 的用途縮回只給轉檔
用、補上取標題與換引言的判準，並登錄新增的驗證腳本。

文件與工具講的不是同一件事，呼叫端就會照舊敘述傳整列的表格文字進去，寫出
半表格半條列的頁面。key-col 的語意變動最容易誤解——它從「要換掉哪一欄」
變成「轉檔時哪一欄持有身分」，敘述不改就會被填成別的欄位。

目錄頁條列、內容頁維持圖表優先，這個區分在每一份文件裡都寫明，避免把改版
範圍誤讀成整個 wiki。結束碼說明一併對回工具現況。

功能範圍：目錄頁版面改版的文件同步。
chore(plugin): 三份 manifest 升版至 0.2.5 a229964dfe 
三份 plugin manifest 的版本號同步升到 0.2.5。

目錄頁格式改動了工具的對外行為，其餘七個 domain 的範本要對上這一版才組得
出正確的區塊。版本號沒動，版本守衛就看不出機器上裝的是舊版工具。

三份一起改，維持既有的同版策略。

功能範圍：目錄頁版面改版的版本標記。
admin merged commit cfb6a89e82 into develop 2026-09-02 10:00:22 +00:00
admin deleted branch feat/contents-list/main 2026-09-02 10:00:22 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin (系統管理員) jiantw83 (Jeffery)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Blocks
#79 異常目錄頁改成 H2 區塊條列，寫入語意委派共用工具
plugins/hooks
#28 問詢目錄頁改成大標題加條列，鍵改用問詢紀錄頁頁名
plugins/ask
#58 體檢目錄頁改成大標題加條列，doctor 與 setup 的呼叫同步換鍵
plugins/cli
#60 五個階段目錄頁範本改成大標題加條列，四支技能的讀寫敘述同步
plugins/sdlc
#36 工作日誌三個目錄頁改成大標題加條列，三支技能的呼叫與敘述同步
plugins/log
#67 技能準則新增目錄頁條列與內容頁圖表優先的區分，兩個目錄頁範本與六支技能同步
plugins/meta
#13 助理巡檢目錄頁改成大標題加條列，巡檢輸出檔改名 contents-entry.md
plugins/assist
Reference: plugins/gitea#52