釋出 wiki 目錄頁的 H2 區塊改寫與連結驗證至 master，版本 0.2.2 升到 0.2.5 #53

2026-09-03T03:01:49Z

jiantw83 commented

2026-09-03 03:01:49 +00:00

摘要

需求描述：把 develop 累積的變更釋出到 master。部署工具的 git clone 沒有指定分支，抓的是預設分支 master，所以變更沒進 master 就等於沒有到任何一台機器。版本 0.2.2 升到 0.2.5。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

wiki-contents.sh 的目錄頁改成 H2 區塊 upsert 並自動轉換舊表格、新增目錄頁區塊格式的離線驗證、migrate-wiki 候選鍵兼收條列與表格兩種形狀、收尾寫 skill-end 事件、連結一律寫成絕對網址並先驗證連得到。

設計重點

這是釋出用的 PR，內容全部來自已經審過並合併進 develop 的變更，這裡不新增任何程式碼。
釋出的動機是路徑修正那一批要生效。無人看管的排程輪次在第一支腳本就被權限層擋下，技能端的修正已經進 develop，但部署抓 master，不釋出就到不了機器。

測試結果

各存放庫的檢查在合併進 develop 前都跑過並回結束碼 0：check-behaviors.sh、ste100-lint.sh、lint-frontmatter.sh、lint-scripts.sh。
端到端的無人看管巡檢回歸尚未實測。要等這批釋出並部署到機器之後才驗得出來，因為目前機器上還缺 link-check.sh 與 report-status.sh 兩支腳本。

前置 Push Request

無

## 摘要 - 需求描述：把 `develop` 累積的變更釋出到 `master`。部署工具的 `git clone` 沒有指定分支，抓的是預設分支 `master`，所以變更沒進 `master` 就等於沒有到任何一台機器。版本 0.2.2 升到 0.2.5。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 `wiki-contents.sh` 的目錄頁改成 H2 區塊 upsert 並自動轉換舊表格、新增目錄頁區塊格式的離線驗證、`migrate-wiki` 候選鍵兼收條列與表格兩種形狀、收尾寫 `skill-end` 事件、連結一律寫成絕對網址並先驗證連得到。 ## 設計重點 - 這是釋出用的 PR，內容全部來自已經審過並合併進 `develop` 的變更，這裡不新增任何程式碼。 - 釋出的動機是路徑修正那一批要生效。無人看管的排程輪次在第一支腳本就被權限層擋下，技能端的修正已經進 `develop`，但部署抓 `master`，不釋出就到不了機器。 ## 測試結果 - 各存放庫的檢查在合併進 `develop` 前都跑過並回結束碼 0：`check-behaviors.sh`、`ste100-lint.sh`、`lint-frontmatter.sh`、`lint-scripts.sh`。 - 端到端的無人看管巡檢回歸尚未實測。要等這批釋出並部署到機器之後才驗得出來，因為目前機器上還缺 `link-check.sh` 與 `report-status.sh` 兩支腳本。 ## 前置 Push Request - 無

jiantw83 added 12 commits 2026-09-03 03:01:49 +00:00

feat(link): 連結一律寫成 [文字](絕對網址)，寫入前先驗證連得到 9ec18b8a94

取消 [[頁名]] 與 [[顯示文字|頁名]] 兩種同 wiki 寫法，不再分「同存取庫」與
「跨存取庫」兩條規則。那種寫法只在自己那個 wiki 內解析，寫錯不報錯，畫面上
看起來像普通文字或死連結，巡不到也修不了。

連結寫進頁面前先過 jsc-gitea 的 link-check.sh，結束碼 0 才寫。驗證一律走 API，
不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把
好連結判成壞的。認證失敗回 7，與死連結的 1 分開，免得金鑰一過期就把還在的頁
整批判死。

chore(plugin 版本): 三份 manifest 升版至 0.2.3 b59782d093

Merge pull request '連結一律寫成 [文字](絕對網址)，並在寫入前驗證連得到' (#50 ) from feat/link-verification/main into develop e045cc804f

Reviewed-on: #50

feat(狀態回報): 收尾寫一筆 skill-end 事件 f69b4b6f85

現行紀錄只記「被叫用」，沒有成敗也沒有結束碼。跑完整輪的技能與開場就
中止的技能，在紀錄裡長得一模一樣。

start 由技能用量 hook 順手發，不必改技能文件。end 只能由技能自己在收尾
步驟寫——hook 接在技能工具呼叫上，而實際工作發生在之後的模型輪次，它在
原理上看不到成敗。有 start 沒有配對的 end，就是那一輪中止了。

status 五選一，每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜
跳過，回報失敗一律不改變技能自己的結論。

chore(plugin 版本): 三份 manifest 升版至 0.2.4 a1a00eae74

Merge pull request '收尾寫一筆 skill-end 事件，執行狀態才回報得到助理' (#51 ) from feat/status-report into develop bac7810f51

Reviewed-on: #51

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 的範本要對上這一版才組得
出正確的區塊。版本號沒動，版本守衛就看不出機器上裝的是舊版工具。

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

功能範圍：目錄頁版面改版的版本標記。

Merge pull request 'wiki 目錄頁改成大標題加條列，舊表格讀到就自動轉檔' (#52 ) from feat/contents-list/main into develop cfb6a89e82

Reviewed-on: #52

admin approved these changes 2026-09-03 03:17:25 +00:00

admin merged commit 93c18023f6 into master

2026-09-03 03:17:28 +00:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: plugins/gitea#53