.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-gitea",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Gitea API 工具、Wiki 讀寫、議題轉換、HTML 匯出與存取庫批次同步",
   "skills": "./skills",
   "author": {

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-gitea",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Gitea API 工具、Wiki 讀寫、議題轉換、HTML 匯出與存取庫批次同步",
   "skills": "./skills",
   "jsc": {

README.md

@@ -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`
 

plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "jsc-gitea",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Gitea API 工具、Wiki 讀寫、議題轉換、HTML 匯出與存取庫批次同步",
   "skills": "./skills/",
   "jsc": {

references/behaviors.md

@@ -36,11 +36,11 @@
 
 | 項目 | 內容 |
 | --- | --- |
-| 觸發時機 | 技能組裡任何一次 wiki 頁的讀、寫、刪或搬移，都經過這一支。呼叫端有 jsc-ask、jsc-sdlc、jsc-log、jsc-hooks 的 ERROR 頁、jsc-cli 的 CHECK 頁、jsc-meta 的 SKILLSET 與 TOOLING 頁、jsc-assist 的 MONITOR 頁。存放庫裡的程式碼檔案不歸這一支管。 |
-| 關鍵步驟 | 確認 GITEA_HOST 有值、用 tools/gitea.sh wiki-repo {TYPE} 解出 {owner}/{repo}、用 tools/hash-id 算頁名要用的 HASH、用 tools/page-name.sh check 驗過頁名、再依動作跑 wiki-list、wiki-get、wiki-put、wiki-delete 或 wiki-url，每一次呼叫都照結束碼表分流。所有 *_CONTENTS 頁一律走型別 CONTENTS，內容頁走自己的型別；存放庫的解法是先讀 JSC_WIKI_REPO_{TYPE}、再讀 JSC_WIKI_REPO、兩個都沒有才問使用者，而且不借用別的頁型的存放庫。頁面裡的連結一律寫成 [文字](絕對網址)，網址取自 wiki-url，不自行組路徑；wiki-put 之前先把這一頁要放的每一條連結交給 tools/link-check.sh，結束碼 0 才寫，1 就不寫並回報 DEAD 那幾筆，7 停下來回報金鑰問題。目錄頁的整列 upsert 交給 tools/wiki-contents.sh，寫入前一定先 wiki-get 讀回舊內容，只有結束碼 4 才准用範本建新頁；舊頁搬到新規則走 tools/migrate-wiki.sh，不帶 --apply 只印對照表，寫每一個目的地之前也一樣先 wiki-get 讀一次。收尾一律呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-gitea:wiki 寫下這一輪的結果，走每一條出口，連停在主機閘門那一條也要寫；這支被幾乎每支技能呼叫，只回報這一次 wiki 動作的成敗，不回報呼叫端自己的結果。status 五選一，讀到頁面或寫入落地是 ok，主機沒值、或 wiki-repo 回 3 而使用者沒給 {owner}/{repo}、整輪沒讀也沒寫是 blocked，金鑰失效那個結束碼 7 算 failed 不算頁面不存在、結束碼 8 與 link-check 回 1 擋下寫入也是 failed，內容頁寫成功但目錄頁沒更新（wiki-contents.sh 回 3 或 1）是 degraded、搬移只搬掉一部分也是 degraded，人工確認被否決或頁型不在允許清單而停在 wiki-repo 回 2 是 aborted。detail 只放頁名，不放頁面內容。腳本不在這台機器就安靜跳過，回報失敗不得改變回給呼叫端的結果。 |
-| 外部呼叫 | tools/gitea.sh 的 wiki-repo、wiki-list、wiki-get、wiki-put、wiki-delete、wiki-url、tools/hash-id、tools/page-name.sh、tools/link-check.sh、tools/wiki-contents.sh、tools/migrate-wiki.sh、tools/write-confirm.sh、jsc-ask:ask、jsc-hooks/tools/report-status.sh skill-end、Gitea 的 wiki API 與議題 API。 |
-| 完成條件 | 讀取動作拿到頁面內容，或拿到一個講得清楚的結束碼。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響回給呼叫端的結束碼。寫入動作先讓 tools/link-check.sh 回結束碼 0，再通過人工確認、wiki-put 回結束碼 0，而且送出去的是舊內容加上這次的異動，不是整頁覆蓋。連結檢查回 1 就不寫入，回 7 連同整個動作一起中止。wiki-put 的結束碼 7 與 8 一律中止整個動作，不建頁、不寫入、不用原參數重試。搬移動作要嘛全部搬完回 0，要嘛把失敗頁、孤兒頁、目的地已有內容的頁、指向被搬頁卻沒被搬的引用方逐條列出來，這四種一律交給人判斷。 |
-| 可驗證跡象 | 目標 wiki 存放庫多一頁或改一頁。內容頁的頁名是 {型別}_{40 碼大寫十六進位}，目錄頁是 {型別}_CONTENTS 且落在 JSC_WIKI_REPO_CONTENTS 指的那個存放庫。頁面內容是 UTF-8 繁體中文，以 mermaid 圖與 markdown 表格為主，散文每節最多三句；頁面裡每一條連結都是 [文字](絕對網址)，沒有 wiki 內部連結語法，而且每一條在寫入前都被 tools/link-check.sh 判成 OK。寫入與刪除前 tools/write-confirm.sh 會各留下一次人工確認。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-gitea:wiki，status 與 exit 就是這一次 wiki 動作的結果。只做讀取的呼叫沒有 wiki 寫入跡象，只有回報內容與那一筆事件。 |
+| 觸發時機 | 技能組裡任何一次 wiki 頁的讀、寫、刪或搬移，都經過這一支。呼叫端有 jsc-ask、jsc-sdlc、jsc-log、jsc-hooks 的 ERROR 頁、jsc-cli 的 CHECK 頁、jsc-meta 的 SKILLSET 與 TOOLING 頁、jsc-assist 的 MONITOR 頁。要在目錄頁登記一筆紀錄，也走這一支。存放庫裡的程式碼檔案不歸這一支管。 |
+| 關鍵步驟 | 確認 GITEA_HOST 有值、用 tools/gitea.sh wiki-repo {TYPE} 解出 {owner}/{repo}、用 tools/hash-id 算頁名要用的 HASH、用 tools/page-name.sh check 驗過頁名、再依動作跑 wiki-list、wiki-get、wiki-put、wiki-delete 或 wiki-url，每一次呼叫都照結束碼表分流。所有 *_CONTENTS 頁一律走型別 CONTENTS，內容頁走自己的型別；存放庫的解法是先讀 JSC_WIKI_REPO_{TYPE}、再讀 JSC_WIKI_REPO、兩個都沒有才問使用者，而且不借用別的頁型的存放庫。頁面裡的連結一律寫成 [文字](絕對網址)，網址取自 wiki-url，不自行組路徑；wiki-put 之前先把這一頁要放的每一條連結交給 tools/link-check.sh，結束碼 0 才寫，1 就不寫並回報 DEAD 那幾筆，7 停下來回報金鑰問題。內容頁的內容以圖表優先，目錄頁不放表格：一筆紀錄一個 H2 區塊，標題就是那一筆對應的內容頁頁名，欄位是標題底下一層條列「- {欄位名}：{值}」。目錄頁的區塊 upsert 交給 tools/wiki-contents.sh，參數是 upsert {TYPE} {key-col} {key} {區塊檔} [範本檔]：它先 wiki-get 讀回舊內容，舊頁還是 markdown 表格就整頁轉成區塊，再找「## {key}」，命中換掉整塊、沒命中附加到頁尾，最後整頁寫回；key-col 只給轉檔認舊表格的身分欄用，頁面已是條列就忽略；轉檔的 H2 標題只看身分欄那一格，有連結就取網址最後一段路徑、百分號編碼先解碼，沒連結才取格子純文字，取到什麼就用什麼，不拿頁名樣式去驗；轉檔那一次呼叫端有給範本，就把第一個「## 」之前的 H1 與「>」引言換成範本那一段，範本的示範區塊不得混進來，因為轉檔只搬表格不動散文，舊引言會一直講「每個存取庫一列」這種只對表格成立的話，頁面已是條列或沒給範本則引言原樣不動。只有結束碼 4 才准用範本建新頁，7 與 8 一律中止；建新頁時範本的示範區塊要剝掉。舊頁搬到新規則走 tools/migrate-wiki.sh，不帶 --apply 只印對照表，寫每一個目的地之前也一樣先 wiki-get 讀一次。收尾一律呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-gitea:wiki 寫下這一輪的結果，走每一條出口，連停在主機閘門那一條也要寫；這支被幾乎每支技能呼叫，只回報這一次 wiki 動作的成敗，不回報呼叫端自己的結果。status 五選一，讀到頁面或寫入落地是 ok，主機沒值、或 wiki-repo 回 3 而使用者沒給 {owner}/{repo}、整輪沒讀也沒寫是 blocked，金鑰失效那個結束碼 7 算 failed 不算頁面不存在、結束碼 8 與 link-check 回 1 擋下寫入也是 failed，內容頁寫成功但目錄頁沒更新（wiki-contents.sh 回 3，或回 1 組不出頁面內容、寫入沒落地）是 degraded、搬移只搬掉一部分也是 degraded，人工確認被否決或頁型不在允許清單而停在 wiki-repo 回 2 是 aborted。detail 只放頁名，不放頁面內容。腳本不在這台機器就安靜跳過，回報失敗不得改變回給呼叫端的結果。 |
+| 外部呼叫 | tools/gitea.sh 的 wiki-repo、wiki-list、wiki-get、wiki-put、wiki-delete、wiki-url、tools/hash-id、tools/page-name.sh、tools/link-check.sh、tools/wiki-contents.sh 的 upsert 與 format、tools/migrate-wiki.sh、tools/write-confirm.sh、jsc-ask:ask、jsc-hooks/tools/report-status.sh skill-end、Gitea 的 wiki API 與議題 API。 |
+| 完成條件 | 讀取動作拿到頁面內容，或拿到一個講得清楚的結束碼。這一輪還要留下一筆 skill-end 事件，或是腳本不在而略過，兩者都算收好；略過不影響回給呼叫端的結束碼。寫入動作先讓 tools/link-check.sh 回結束碼 0，再通過人工確認、wiki-put 回結束碼 0，而且送出去的是舊內容加上這次的異動，不是整頁覆蓋。目錄頁的異動只動自己那一個 H2 區塊：別人那幾筆一字不變，頁面上不留 markdown 表格，也不出現兩個同名的 H2 標題；只有從表格轉成區塊那一次，且呼叫端有給範本，引言才會換成範本那一份，其餘情況引言與別人那幾筆一起一字不動。連結檢查回 1 就不寫入，回 7 連同整個動作一起中止。wiki-put 的結束碼 7 與 8 一律中止整個動作，不建頁、不寫入、不用原參數重試。搬移動作要嘛全部搬完回 0，要嘛把失敗頁、孤兒頁、目的地已有內容的頁、指向被搬頁卻沒被搬的引用方逐條列出來，這四種一律交給人判斷。 |
+| 可驗證跡象 | 目標 wiki 存放庫多一頁或改一頁。內容頁的頁名是 {型別}_{40 碼大寫十六進位}，目錄頁是 {型別}_CONTENTS 且落在 JSC_WIKI_REPO_CONTENTS 指的那個存放庫。頁面內容是 UTF-8 繁體中文；內容頁以 mermaid 圖與 markdown 表格為主，散文每節最多三句。目錄頁只有三段：H1 頁名、「>」引言、一筆一個 H2 區塊，區塊之間空一行，H2 與第一條條列之間也空一行，H2 標題就是內容頁頁名而且不帶連結。頁面裡每一條連結都是 [文字](絕對網址)，沒有 wiki 內部連結語法，而且每一條在寫入前都被 tools/link-check.sh 判成 OK。wiki-contents.sh 印出一行 updated 或 added 加上 {owner}/{repo}/{頁名}。寫入與刪除前 tools/write-confirm.sh 會各留下一次人工確認。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件，name 是 jsc-gitea:wiki，status 與 exit 就是這一次 wiki 動作的結果。只做讀取的呼叫沒有 wiki 寫入跡象，只有回報內容與那一筆事件。 |
 
 ## wiki-to-issue
 

references/wiki-links.md

@@ -8,7 +8,7 @@
 
 | 情境 | 寫法 |
 | --- | --- |
-| 目錄頁指向內容頁（例：`PLAN_CONTENTS` → `PLAN_{HASH}`） | `[PLAN_{HASH}](https://…/wiki/PLAN_…)` |
+| 目錄頁指向內容頁（例：`PLAN_CONTENTS` → `PLAN_{HASH}`）：連結寫在該筆 H2 區塊的條列裡，H2 標題本身只放頁名，不放連結 | `- 計畫頁：[PLAN_{HASH}](https://…/wiki/PLAN_…)` |
 | 內容頁指向目錄頁，或指向別的型別 | `[顯示文字](絕對網址)` |
 | 目錄頁之間、同型別的內容頁之間 | `[顯示文字](絕對網址)` |
 | 議題、PR、存放庫檔案 | `[顯示文字](絕對網址)` |

skills/wiki/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: wiki
-description: Read or write a Gitea wiki page through tools/gitea.sh, tools/hash-id and tools/page-name.sh. Resolve the wiki repo per page type with JSC_WIKI_REPO_{TYPE} first, then JSC_WIKI_REPO, and ask only when neither is set - every *_CONTENTS page resolves through type CONTENTS and is updated with tools/wiki-contents.sh, and {HASH} is the full 40-char uppercase SHA-1 from tools/hash-id. Page content is chart-first - prefer mermaid diagrams and markdown tables over plain prose, and every link is written as [text](absolute URL) that tools/link-check.sh passed before the write. Callers are jsc-ask, jsc-sdlc, jsc-log, jsc-hooks (ERROR), jsc-cli (CHECK), jsc-meta (SKILLSET, TOOLING) and jsc-assist (MONITOR). Use for any wiki page in the skill set; not for repo code files.
+description: Read or write a Gitea wiki page through tools/gitea.sh, tools/hash-id and tools/page-name.sh. Resolve the wiki repo per page type with JSC_WIKI_REPO_{TYPE} first, then JSC_WIKI_REPO, and ask only when neither is set - every *_CONTENTS page resolves through type CONTENTS and is upserted by tools/wiki-contents.sh as one H2 block per record, and {HASH} is the full 40-char uppercase SHA-1 from tools/hash-id. A contents page carries no markdown table - one H2 block per record, headed by that record's content-page name with one bullet per field - while a content page is chart-first, preferring mermaid diagrams and markdown tables over plain prose, and every link is written as [text](absolute URL) that tools/link-check.sh passed before the write. Callers are jsc-ask, jsc-sdlc, jsc-log, jsc-hooks (ERROR), jsc-cli (CHECK), jsc-meta (SKILLSET, TOOLING) and jsc-assist (MONITOR). Use for any wiki page in the skill set; not for repo code files.
 ---
 
 # wiki — read and write Gitea wiki pages
@@ -24,7 +24,7 @@ Different page types can live in different `{owner}/{repo}` repos, classified by
 | write page | write the content to a temp file first, then `tools/gitea.sh wiki-put {owner}/{repo} {page} {file}` (asks for confirmation first, then creates or updates) |
 | delete page | `tools/gitea.sh wiki-delete {owner}/{repo} {page}` — asks for the same confirmation as a write. Only a migration or an explicit user request may call it |
 | page URL | `tools/gitea.sh wiki-url {owner}/{repo} {page}` — the page's absolute URL, taken from the API's `html_url` |
-| update a contents page | `tools/wiki-contents.sh upsert {TYPE} {key-col} {key} {row-file} [template-file]` — resolves the CONTENTS repo, replaces the row whose key column matches, appends when none does, writes the whole page back. `{key-col}` is the column's 1-based position number, not the column name |
+| update a contents page | `tools/wiki-contents.sh upsert {TYPE} {key-col} {key} {entry-file} [template-file]` — resolves the CONTENTS repo, replaces the `## {key}` block, appends when the page holds no such heading, writes the whole page back. `{entry-file}` is that record's whole H2 block. `{key-col}` only matters while the old page is still a markdown table: it is the 1-based position of the column that carries the record's identity, and the script converts such a page to H2 blocks before the upsert, taking each heading from that cell's link URL — its last path segment, percent-decoded — or from the cell's plain text when the cell holds no link. On that conversion, a supplied `{template-file}` also replaces the page's H1 and `>` intro with the template's own, because a conversion moves the table alone and the old intro keeps describing rows; an already-converted page keeps its intro untouched, and so does a conversion run without a template |
 | check a page name | `tools/page-name.sh check {page}` — the single source of the page-name pattern; `tools/page-name.sh regex` prints it |
 | move pages to the current rules | `tools/migrate-wiki.sh [--apply] [--key {key}]...` — prints the mapping table and the orphan list; writes only with `--apply` |
 | check links before a write | `tools/link-check.sh {url}...` — prints `{OK\|DEAD\|SKIP}<TAB>{url}<TAB>{reason}` per URL; exit 0 means every link is reachable |
@@ -57,8 +57,8 @@ Every code below gets its own branch. Nothing here is retried unchanged.
 | `tools/page-name.sh` | 0 | the page name follows the pattern | continue with that page name |
 | | 1 | the page name breaks the pattern | stop and report the name; build the correct one instead of writing to a wrong page |
 | | 2 | usage error | fix the arguments, then call again |
-| `tools/wiki-contents.sh` | 0 | the row was updated or added | report which of the two, and the page |
-| | 1 | the write failed, or the page held no markdown table | stop and report; fix the page or the row before calling again |
+| `tools/wiki-contents.sh` | 0 | the block was updated or added | report which of the two, and the page |
+| | 1 | the page content could not be built, or the write failed | stop and report; fix the page or the entry before calling again. A missing `## {key}` is not this code — that path appends |
 | | 2 | usage error, or an unknown page type | fix the arguments, then call again |
 | | 3 | the CONTENTS repo is not configured | go to step 3 and ask for `JSC_WIKI_REPO_CONTENTS` |
 | | 4 | the page is not there and no template was given | supply the template for that page type, then call again |
@@ -89,7 +89,7 @@ This skill is called by almost every other one, so its status is what the caller
 | `ok` | The read returned the page, or the write landed: `link-check.sh` exited 0, the confirmation was given, and `wiki-put` exited 0 |
 | `blocked` | The location could not be resolved, so nothing was read and nothing was written: `GITEA_HOST` holds no value and the user gave none, or `wiki-repo` exited 3 and the user supplied no `{owner}/{repo}` for that page type |
 | `failed` | The operation ran and broke. **Exit 7 belongs here**: the key is invalid or lacks permission, so the whole operation stopped, and that is a failure, never an absent page. Exit 8, a `wiki-put` that did not land, a `link-check.sh` exit 1 that refused the write, and a `hash-id` or `page-name.sh` rejection all sit here too |
-| `degraded` | The content page landed and the contents page did not — `wiki-put` on `{TYPE}_{HASH}` exited 0, then `wiki-contents.sh upsert` exited 3 with no CONTENTS repo configured, or exited 1 on a page holding no markdown table. The record exists but nothing indexes it, so the next reader will not find it. A migration that moved some pages and left orphans or occupied destinations behind sits here as well |
+| `degraded` | The content page landed and the contents page did not — `wiki-put` on `{TYPE}_{HASH}` exited 0, then `wiki-contents.sh upsert` exited 3 with no CONTENTS repo configured, or exited 1 because the page content could not be built or the write did not land. The record exists but nothing indexes it, so the next reader will not find it. A migration that moved some pages and left orphans or occupied destinations behind sits here as well |
 | `aborted` | The premise did not hold or the user stopped it: `write-confirm.sh` was refused before a write or a delete, or the caller asked for a page type outside the allowed list and the run stopped at `wiki-repo` exit 2 |
 
 Completion condition: exactly one `skill-end` line was recorded for this run, or the script was absent and the run finished without it.
@@ -98,14 +98,14 @@ Completion condition: exactly one `skill-end` line was recorded for this run, or
 
 1. Page names must follow the wiki naming table in the skill guidelines (see `jsc-meta/references/guidelines.md`). Check any page name you build with `tools/page-name.sh check {page}` before it reaches an API call.
 2. Use `tools/hash-id` for `{HASH}` values. It returns the full 40 uppercase SHA-1 hex chars — no truncation, no prefix. Never compute a hash by hand: a hand-made page name lands the content on a page nobody else reads.
-3. To update a contents page (`*_CONTENTS`), run `tools/wiki-contents.sh upsert {TYPE} {key-col} {key} {row-file} [template-file]`, where `{key-col}` is the column's 1-based position number, not the column name. It reads the page, replaces the row whose key column equals the key, appends the row when no line matches, and writes the whole page back through the same confirmation. Never overwrite entries owned by others. Whether the page may be created from the template instead is decided by rule 4, and by nothing else.
+3. **A contents page (`*_CONTENTS`) is one H2 block per record, never a table.** The H2 heading is that record's key, written as the content page's own name (`{TYPE}_{HASH}`) — no link, no URL, no prefix, no date. Every field is one bullet under it, `- {field}：{value}`, full-width colon, one bullet per field including the key's own. Update it with `tools/wiki-contents.sh upsert {TYPE} {key-col} {key} {entry-file} [template-file]`, where `{entry-file}` holds that whole H2 block. The script reads the page, converts a page still holding a markdown table into H2 blocks first, replaces the block whose heading equals `{key}`, appends the block when no heading matches, and writes the whole page back through the same confirmation. `{key-col}` is used only by that conversion: it is the 1-based position of the old table's identity column, and it is ignored once the page is already in block form. That conversion takes the heading from the identity cell's markdown link — the URL's last path segment, percent-decoded, because the link text is often a work-package or plan name rather than the page name — and from the cell's plain text, backticks stripped, only when the cell holds no link; it never checks the result against the page-name pattern, since old timestamped names, new 40-char names, and plain `{owner}/{repo}` identities all appear online. **That conversion is also the one moment the intro may be rewritten:** when `{template-file}` is given, everything before the first `## ` — the H1, the `>` intro, the blank lines between them — is replaced by the template's own preamble, taken the same way and carrying none of the template's demo blocks. Why: the conversion moves the table and leaves the prose, so an intro still saying "one row per repository" outlives the rows it describes, and the template holds the canonical wording. A page already in block form keeps its intro exactly as its owner wrote it — that call only updates its own record — and a conversion run without a template keeps the old intro, there being no canonical copy to install. Never overwrite entries owned by others. Whether the page may be created from the template instead is decided by rule 4, and by nothing else.
 4. **Only exit 4 means the page is not there yet — this rule binds every "create it if it does not exist" path, without exception.** It is not limited to contents pages: a content page (`*_{HASH}`), a work log, an error page, a report, any page at all, follows the same branch.
    - **Correct branch.** Read the page with `wiki-get`. Exit 0 means the page exists, so append or modify the content that came back and `wiki-put` the whole page. Exit 4 (HTTP 404) is the one and only code that permits creating a new page from the template.
    - **Exit 7 and exit 8 abort.** Exit 7 (HTTP 401 or 403) and exit 8 (any other API failure) both mean the old content is unknown, never that the page is missing. Stop the operation and report the exit code with its cause. Create no page, write nothing, and do not retry the same call unchanged.
    - **Why.** Wiki writes in this skill set are append-not-overwrite, and that semantics rests entirely on reading the old page back first. Reading a 401 as a 404 makes the caller believe it holds a brand-new page and `wiki-put` a fresh template over a live one, and the whole earlier record is gone — the write carries no merge and no backup.
    - `tools/wiki-contents.sh` implements exactly this branch for contents pages and reports the same codes.
 5. Write all wiki content in UTF-8 Traditional Chinese, per the STE100 output rule.
-6. Prefer visual forms for page content: use mermaid diagrams (flowchart, sequence, gantt, pie) and markdown tables wherever the information allows. Prose is capped at 3 sentences per section, and a sentence stays only when neither a mermaid diagram nor a markdown table can carry the same information.
+6. **Chart-first applies to content pages (`*_{HASH}`) only.** On a content page, prefer visual forms: use mermaid diagrams (flowchart, sequence, gantt, pie) and markdown tables wherever the information allows. Prose is capped at 3 sentences per section, and a sentence stays only when neither a mermaid diagram nor a markdown table can carry the same information. **A contents page (`*_CONTENTS`) always takes the H2-heading-plus-bullets form of rule 3 instead** — no table, and no diagram, whatever the field count. Why: the heading is the key the upsert matches on, so the layout is fixed by the tool, not by which form reads better.
 7. `tools/gitea.sh` retries once with the tea CLI login token when `GITEA_TOKEN` is missing or the response is 401/403. Report a failure only after that retry also fails.
 8. **Rule A — every link is written as `[text](absolute URL)`.** That is the only form. `[[page]]` and `[[display|page]]` are gone, and there is no longer a same-repo case that keeps them. The URL always comes from `tools/gitea.sh wiki-url {owner}/{repo} {page}`, never from a path built by hand. Why: `[[...]]` resolves only inside the current wiki, so a cross-repo link silently lands on a same-named page in this one — and it fails as plain text or a dead link, with nothing to catch it. Contents pages and content pages already live in different repos, so keeping two forms would mean judging, link by link, which repo each end resolves to.
 9. **Rule B — check every link before the write.** Run `tools/link-check.sh {url}...` over every link that is going into the page. Exit 0 is the only code that opens `wiki-put`. Exit 1 means at least one link is dead: write nothing, and hand the caller the `DEAD` rows. Exit 7 means the key failed, not that the pages are gone — stop and report the key problem. Checking after the write is not the same thing: the dead link is already published, and the next reader follows it.

tools/check-contents-format.sh

@@ -0,0 +1,518 @@
+#!/usr/bin/env sh
+# check-contents-format.sh — 驗證目錄頁的區塊轉檔與 upsert 規則。
+# 全部走 wiki-contents.sh 的 format 子命令，只讀寫暫存檔，不打任何 API。
+# 涵蓋五種舊頁狀態：純表格、已是條列且鍵命中、已是條列且鍵未命中、表格與區塊混合、
+# 用範本建新頁。另外驗三件事：表格取不出鍵那一列要擋下來不猜標題、轉檔後重跑同一筆
+# 結果一字不變、區塊檔沒帶標題也照樣補上。
+# 轉檔取 H2 標題另外驗四種身分欄：連結文字不是頁名、連結文字剛好等於頁名、純文字沒有
+# 連結、網址帶百分號編碼。四種都要取到真正的頁名，呼叫端那一筆才會是 updated。
+# 引言另外驗五種情形：轉檔且有範本要換成範本那一份、轉檔但沒範本保留舊的、已是條列
+# 加了範本也不准動引言、--fresh 建新頁照舊、拿轉檔結果重跑引言不再變動。
+# 全部通過印 OK 並 exit 0；任一項不符印出 want 與 got 並 exit 1。
+# 結束碼: 0=全部通過，stdout 印 OK
+#         1=有一項不符，stderr 印出 {項目}: want=… got=… 之後立刻停住，不續跑其餘項目。
+#           只有 0 與 1 兩種；這支不吃參數，也沒有用法錯誤那條路。
+set -eu
+
+dir=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
+contents="$dir/wiki-contents.sh"
+
+work=$(mktemp -d)
+trap 'rm -rf "$work"' EXIT
+
+fail() {
+  printf '%s\n' "$1" >&2
+  exit 1
+}
+
+expect_eq() { # got want label
+  [ "$1" = "$2" ] || fail "$(printf '%s: want=\n%s\ngot=\n%s' "$3" "$2" "$1")"
+}
+
+# run <label> <keycol> <key> <fresh|keep> [範本檔] — 讀 $work/old 與 $work/entry，
+# 結果留在 $work/new，動作留在 $work/action。
+run() {
+  rc=0
+  if [ "$4" = fresh ]; then
+    sh "$contents" format "$2" "$3" "$work/entry" "$work/old" "$work/new" --fresh > "$work/action" || rc=$?
+  elif [ -n "${5-}" ]; then
+    sh "$contents" format "$2" "$3" "$work/entry" "$work/old" "$work/new" "$5" > "$work/action" || rc=$?
+  else
+    sh "$contents" format "$2" "$3" "$work/entry" "$work/old" "$work/new" > "$work/action" || rc=$?
+  fi
+  [ "$rc" -eq 0 ] || fail "$1: want exit=0 got exit=$rc"
+}
+
+# ---- 1. 純表格舊頁：整頁轉成區塊，再換掉鍵相同那一筆 ----
+cat > "$work/old" <<'EOF'
+# 日誌目錄
+
+> 由 `jsc-log:worklog` 維護。一個區塊代表一個日誌頁。
+
+| 日誌頁 | 存取庫 | 條目數 |
+| --- | --- | --- |
+| [LOG_AAA](https://example.test/wiki/LOG_AAA) | plugins/meta | 3 |
+| [LOG_BBB](https://example.test/wiki/LOG_BBB) | plugins/ask | 5 |
+EOF
+cat > "$work/entry" <<'EOF'
+## LOG_BBB
+
+- 日誌頁：[LOG_BBB](https://example.test/wiki/LOG_BBB)
+- 存取庫：plugins/ask
+- 條目數：9
+EOF
+run 'table page' 1 LOG_BBB keep
+expect_eq "$(cat "$work/action")" updated 'table page action'
+expect_eq "$(cat "$work/new")" '# 日誌目錄
+
+> 由 `jsc-log:worklog` 維護。一個區塊代表一個日誌頁。
+
+## LOG_AAA
+
+- 日誌頁：[LOG_AAA](https://example.test/wiki/LOG_AAA)
+- 存取庫：plugins/meta
+- 條目數：3
+
+## LOG_BBB
+
+- 日誌頁：[LOG_BBB](https://example.test/wiki/LOG_BBB)
+- 存取庫：plugins/ask
+- 條目數：9' 'table page'
+
+# ---- 2. 已是條列，鍵命中：只換那一塊，別人那一筆一字不動 ----
+cat > "$work/old" <<'EOF'
+# 日誌目錄
+
+> 引言。
+
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：3
+
+## LOG_BBB
+
+- 存取庫：plugins/ask
+- 條目數：5
+EOF
+cat > "$work/entry" <<'EOF'
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：7
+EOF
+run 'list hit' 1 LOG_AAA keep
+expect_eq "$(cat "$work/action")" updated 'list hit action'
+expect_eq "$(cat "$work/new")" '# 日誌目錄
+
+> 引言。
+
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：7
+
+## LOG_BBB
+
+- 存取庫：plugins/ask
+- 條目數：5' 'list hit'
+
+# ---- 3. 已是條列，鍵未命中：附加到頁尾，前面的區塊照舊 ----
+cat > "$work/entry" <<'EOF'
+## LOG_CCC
+
+- 存取庫：plugins/git
+- 條目數：1
+EOF
+run 'list miss' 1 LOG_CCC keep
+expect_eq "$(cat "$work/action")" added 'list miss action'
+expect_eq "$(cat "$work/new")" '# 日誌目錄
+
+> 引言。
+
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：3
+
+## LOG_BBB
+
+- 存取庫：plugins/ask
+- 條目數：5
+
+## LOG_CCC
+
+- 存取庫：plugins/git
+- 條目數：1' 'list miss'
+
+# ---- 4. 表格與區塊混合：表格轉出來的區塊接在既有區塊後面 ----
+cat > "$work/old" <<'EOF'
+# 日誌目錄
+
+> 引言。
+
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：3
+
+| 日誌頁 | 存取庫 |
+| --- | --- |
+| [LOG_BBB](https://example.test/wiki/LOG_BBB) | plugins/ask |
+EOF
+cat > "$work/entry" <<'EOF'
+## LOG_CCC
+
+- 日誌頁：[LOG_CCC](https://example.test/wiki/LOG_CCC)
+- 存取庫：plugins/git
+EOF
+run 'mixed page' 1 LOG_CCC keep
+expect_eq "$(cat "$work/action")" added 'mixed page action'
+expect_eq "$(cat "$work/new")" '# 日誌目錄
+
+> 引言。
+
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：3
+
+## LOG_BBB
+
+- 日誌頁：[LOG_BBB](https://example.test/wiki/LOG_BBB)
+- 存取庫：plugins/ask
+
+## LOG_CCC
+
+- 日誌頁：[LOG_CCC](https://example.test/wiki/LOG_CCC)
+- 存取庫：plugins/git' 'mixed page'
+
+# ---- 5. 用範本建新頁：示範區塊與示範表格都要剝掉，只留 H1 與引言 ----
+cat > "$work/old" <<'EOF'
+# 日誌目錄
+
+> 由 `jsc-log:worklog` 維護。一個區塊代表一個日誌頁。
+
+## {日誌頁頁名}
+
+- 存取庫：{owner}/{repo}
+- 條目數：{數字}
+EOF
+cat > "$work/entry" <<'EOF'
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：3
+EOF
+run 'fresh page' 1 LOG_AAA fresh
+expect_eq "$(cat "$work/action")" added 'fresh page action'
+expect_eq "$(cat "$work/new")" '# 日誌目錄
+
+> 由 `jsc-log:worklog` 維護。一個區塊代表一個日誌頁。
+
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：3' 'fresh page'
+
+# ---- 6. 表格那一列取不出鍵：擋下來回 1，不猜標題 ----
+cat > "$work/old" <<'EOF'
+# 日誌目錄
+
+> 引言。
+
+| 日誌頁 | 存取庫 |
+| --- | --- |
+|  | plugins/ask |
+EOF
+cat > "$work/entry" <<'EOF'
+## LOG_AAA
+
+- 存取庫：plugins/meta
+EOF
+if sh "$contents" format 1 LOG_AAA "$work/entry" "$work/old" "$work/new" >/dev/null 2>&1; then
+  code=0
+else
+  code=$?
+fi
+[ "$code" -eq 1 ] || fail "keyless table row: want exit=1 got exit=$code"
+
+# ---- 7. 轉檔後重跑同一筆：結果一字不變，程式碼圍欄不被當成表格拆掉 ----
+cat > "$work/old" <<'EOF'
+# 監控目錄
+
+> 引言。
+
+```mermaid
+flowchart LR
+  A --> B
+```
+
+| 監控頁 | 主機 |
+| --- | --- |
+| `MONITOR_AAA` | myhost |
+EOF
+cat > "$work/entry" <<'EOF'
+## MONITOR_AAA
+
+- 監控頁：[MONITOR_AAA](https://example.test/wiki/MONITOR_AAA)
+- 主機：myhost
+EOF
+run 'converted once' 1 MONITOR_AAA keep
+expect_eq "$(cat "$work/action")" updated 'converted once action'
+expect_eq "$(cat "$work/new")" '# 監控目錄
+
+> 引言。
+
+```mermaid
+flowchart LR
+  A --> B
+```
+
+## MONITOR_AAA
+
+- 監控頁：[MONITOR_AAA](https://example.test/wiki/MONITOR_AAA)
+- 主機：myhost' 'converted once'
+
+cp "$work/new" "$work/old"
+run 'converted twice' 1 MONITOR_AAA keep
+expect_eq "$(cat "$work/action")" updated 'converted twice action'
+expect_eq "$(cat "$work/new")" "$(cat "$work/old")" 'converted twice'
+
+# ---- 8. 區塊檔沒帶「## 」標題：照樣補上，鍵就是標題 ----
+cat > "$work/old" <<'EOF'
+# 監控目錄
+
+> 引言。
+EOF
+cat > "$work/entry" <<'EOF'
+- 主機：myhost
+EOF
+run 'headless entry' 1 MONITOR_BBB keep
+expect_eq "$(cat "$work/action")" added 'headless entry action'
+expect_eq "$(cat "$work/new")" '# 監控目錄
+
+> 引言。
+
+## MONITOR_BBB
+
+- 主機：myhost' 'headless entry'
+
+# ---- 9. 連結文字不是頁名：標題取網址最後一段，這一筆算 updated 不是 added ----
+# 頁名一律走變數帶進來。這支腳本的每一行「## 開頭」都會被註解掃描器當成註解讀，
+# 頁名直接寫在那種行上就會被判成註解夾帶頁面編號。
+page='ANALYZE_20260821_100552_104F0709'
+cat > "$work/old" <<EOF
+# 分析目錄
+
+> 引言。
+
+| 計畫名稱 | 分析頁 | HASH |
+| --- | --- | --- |
+| 某計畫 | [假 CLI 核心程式庫](https://example.test/knowledges/ANALYZE/wiki/$page) | 104F0709 |
+EOF
+printf '## %s\n\n- 計畫名稱：某計畫\n' "$page" > "$work/entry"
+run 'link text differs' 2 "$page" keep
+expect_eq "$(cat "$work/action")" updated 'link text differs action'
+expect_eq "$(cat "$work/new")" "$(printf '# 分析目錄\n\n> 引言。\n\n## %s\n\n- 計畫名稱：某計畫' "$page")" 'link text differs'
+
+# ---- 10. 轉檔後重跑同一筆：仍是 updated，不多出區塊 ----
+cp "$work/new" "$work/old"
+run 'link text differs twice' 2 "$page" keep
+expect_eq "$(cat "$work/action")" updated 'link text differs twice action'
+expect_eq "$(cat "$work/new")" "$(cat "$work/old")" 'link text differs twice'
+
+# ---- 11. 連結文字剛好等於頁名：結果與連結文字不是頁名時一致 ----
+page='PLAN_104F0709'
+cat > "$work/old" <<EOF
+# 計畫目錄
+
+> 引言。
+
+| 計畫頁 | 狀態 |
+| --- | --- |
+| [$page](https://example.test/knowledges/PLAN/wiki/$page) | 進行中 |
+EOF
+printf '## %s\n\n- 狀態：已完成\n' "$page" > "$work/entry"
+run 'link text equals page' 1 "$page" keep
+expect_eq "$(cat "$work/action")" updated 'link text equals page action'
+expect_eq "$(cat "$work/new")" "$(printf '# 計畫目錄\n\n> 引言。\n\n## %s\n\n- 狀態：已完成' "$page")" 'link text equals page'
+
+# ---- 12. 身分欄是純文字沒有連結：標題就是那段文字 ----
+page='plugins/meta'
+cat > "$work/old" <<EOF
+# 維護目錄
+
+> 引言。
+
+| 存取庫 | 維護期限 |
+| --- | --- |
+| \`$page\` | 2026-12-31 |
+EOF
+printf '## %s\n\n- 維護期限：2027-06-30\n' "$page" > "$work/entry"
+run 'plain identity cell' 1 "$page" keep
+expect_eq "$(cat "$work/action")" updated 'plain identity cell action'
+expect_eq "$(cat "$work/new")" "$(printf '# 維護目錄\n\n> 引言。\n\n## %s\n\n- 維護期限：2027-06-30' "$page")" 'plain identity cell'
+
+# ---- 13. 網址帶百分號編碼：解碼後取最後一段 ----
+page='ANALYZE_中文'
+cat > "$work/old" <<'EOF'
+# 分析目錄
+
+> 引言。
+
+| 分析頁 | HASH |
+| --- | --- |
+| [某工作包](https://example.test/knowledges/ANALYZE/wiki/ANALYZE_%E4%B8%AD%E6%96%87) | 104F0709 |
+EOF
+printf '## %s\n\n- HASH：104F0709\n' "$page" > "$work/entry"
+run 'percent encoded url' 1 "$page" keep
+expect_eq "$(cat "$work/action")" updated 'percent encoded url action'
+expect_eq "$(cat "$work/new")" "$(printf '# 分析目錄\n\n> 引言。\n\n## %s\n\n- HASH：104F0709' "$page")" 'percent encoded url'
+
+# ---- 14. 轉檔且有範本：引言換成範本那一份，紀錄區塊一筆不少、順序照舊 ----
+# 範本的示範區塊不得混進來，所以範本檔也放一個示範區塊。
+cat > "$work/tpl" <<'EOF'
+# 日誌目錄
+
+> 由 `jsc-log:worklog` 維護。每個存取庫一個區塊；頁面上不留 markdown 表格。
+>
+> 版面：H1 頁名、這段引言，然後一筆紀錄一個 H2 區塊。
+
+## {日誌頁頁名}
+
+- 存取庫：{owner}/{repo}
+- 條目數：{數字}
+EOF
+cat > "$work/old" <<'EOF'
+# 日誌目錄
+
+> 由 `jsc-log:worklog` 維護。每個存取庫一列；`{HASH}` 為 SHA-1 前 8 碼。
+
+| 日誌頁 | 存取庫 | 條目數 |
+| --- | --- | --- |
+| [LOG_AAA](https://example.test/wiki/LOG_AAA) | plugins/meta | 3 |
+| [LOG_BBB](https://example.test/wiki/LOG_BBB) | plugins/ask | 5 |
+EOF
+cat > "$work/entry" <<'EOF'
+## LOG_BBB
+
+- 日誌頁：[LOG_BBB](https://example.test/wiki/LOG_BBB)
+- 存取庫：plugins/ask
+- 條目數：9
+EOF
+run 'converting with template' 1 LOG_BBB keep "$work/tpl"
+expect_eq "$(cat "$work/action")" updated 'converting with template action'
+expect_eq "$(cat "$work/new")" '# 日誌目錄
+
+> 由 `jsc-log:worklog` 維護。每個存取庫一個區塊；頁面上不留 markdown 表格。
+>
+> 版面：H1 頁名、這段引言，然後一筆紀錄一個 H2 區塊。
+
+## LOG_AAA
+
+- 日誌頁：[LOG_AAA](https://example.test/wiki/LOG_AAA)
+- 存取庫：plugins/meta
+- 條目數：3
+
+## LOG_BBB
+
+- 日誌頁：[LOG_BBB](https://example.test/wiki/LOG_BBB)
+- 存取庫：plugins/ask
+- 條目數：9' 'converting with template'
+expect_eq "$(grep -c '^## ' "$work/new")" 2 'converting with template block count'
+
+# ---- 15. 轉檔但沒給範本：沒有正本可換，引言保留舊的 ----
+run 'converting without template' 1 LOG_BBB keep
+expect_eq "$(cat "$work/action")" updated 'converting without template action'
+expect_eq "$(cat "$work/new")" '# 日誌目錄
+
+> 由 `jsc-log:worklog` 維護。每個存取庫一列；`{HASH}` 為 SHA-1 前 8 碼。
+
+## LOG_AAA
+
+- 日誌頁：[LOG_AAA](https://example.test/wiki/LOG_AAA)
+- 存取庫：plugins/meta
+- 條目數：3
+
+## LOG_BBB
+
+- 日誌頁：[LOG_BBB](https://example.test/wiki/LOG_BBB)
+- 存取庫：plugins/ask
+- 條目數：9' 'converting without template'
+
+# ---- 16. 已是條列還給了範本：不必轉檔，引言一字不動 ----
+# 這一筆只是更新自己那一塊，沒有理由改掉別人寫的散文。
+cat > "$work/old" <<'EOF'
+# 日誌目錄
+
+> 這段引言是頁面主人自己寫的，不准被範本蓋掉。
+
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：3
+EOF
+cat > "$work/entry" <<'EOF'
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：7
+EOF
+run 'list page with template' 1 LOG_AAA keep "$work/tpl"
+expect_eq "$(cat "$work/action")" updated 'list page with template action'
+expect_eq "$(cat "$work/new")" '# 日誌目錄
+
+> 這段引言是頁面主人自己寫的，不准被範本蓋掉。
+
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：7' 'list page with template'
+
+# ---- 17. --fresh 建新頁：整份用範本，示範區塊剝掉，行為與加了範本參數之前一樣 ----
+cp "$work/tpl" "$work/old"
+cat > "$work/entry" <<'EOF'
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：3
+EOF
+run 'fresh page with template intro' 1 LOG_AAA fresh
+expect_eq "$(cat "$work/action")" added 'fresh page with template intro action'
+expect_eq "$(cat "$work/new")" '# 日誌目錄
+
+> 由 `jsc-log:worklog` 維護。每個存取庫一個區塊；頁面上不留 markdown 表格。
+>
+> 版面：H1 頁名、這段引言，然後一筆紀錄一個 H2 區塊。
+
+## LOG_AAA
+
+- 存取庫：plugins/meta
+- 條目數：3' 'fresh page with template intro'
+
+# ---- 18. 拿轉檔結果再跑同一筆：已經沒有表格，引言不再變動 ----
+cat > "$work/old" <<'EOF'
+# 日誌目錄
+
+> 由 `jsc-log:worklog` 維護。每個存取庫一列；`{HASH}` 為 SHA-1 前 8 碼。
+
+| 日誌頁 | 存取庫 | 條目數 |
+| --- | --- | --- |
+| [LOG_AAA](https://example.test/wiki/LOG_AAA) | plugins/meta | 3 |
+| [LOG_BBB](https://example.test/wiki/LOG_BBB) | plugins/ask | 5 |
+EOF
+cat > "$work/entry" <<'EOF'
+## LOG_BBB
+
+- 日誌頁：[LOG_BBB](https://example.test/wiki/LOG_BBB)
+- 存取庫：plugins/ask
+- 條目數：9
+EOF
+run 'template intro once' 1 LOG_BBB keep "$work/tpl"
+cp "$work/new" "$work/old"
+run 'template intro twice' 1 LOG_BBB keep "$work/tpl"
+expect_eq "$(cat "$work/action")" updated 'template intro twice action'
+expect_eq "$(cat "$work/new")" "$(cat "$work/old")" 'template intro twice'
+
+printf '%s\n' 'OK'

tools/migrate-wiki.sh

@@ -14,7 +14,9 @@
 #     --key 可重複，補充自動蒐集不到的候選鍵。
 #
 # 候選鍵來源:
-#   目錄頁表格的存取庫、主機、帳號、工具、期間欄，以及這幾欄依序串成的組合鍵。
+#   目錄頁每一筆的存取庫、主機、帳號、工具、期間，以及這幾項依序串成的組合鍵。
+#   目錄頁是 H2 區塊加條列的形狀，所以讀「- {欄位名}：{值}」那幾條；還沒轉檔的舊頁
+#   仍是 markdown 表格，所以表格的欄位也照樣讀，兩種形狀都收。
 #   內容頁的 H1 標題（CHECK 頁的 H1 直接就是 {主機}/{帳號}）。
 #   --key 補充的候選。
 #
@@ -136,7 +138,7 @@ for ty in $TYPES; do
 done
 
 # ---- 第二輪：蒐集候選鍵 ----
-# 目錄頁表格的欄位值，以及依序串成的組合鍵
+# 目錄頁每一筆的欄位值，以及依序串成的組合鍵
 while IFS="$TAB" read -r orepo opage nrepo npage <&3; do
   [ -n "$opage" ] || continue
   case "$opage" in *_CONTENTS) ;; *) continue ;; esac
@@ -174,9 +176,49 @@ def plain(v):
 idx = {}
 seen_sep = False
 out = []
+block = None
+
+
+def take(found):
+    """一筆紀錄收到的欄位值，各自算一個候選鍵，依 WANT 順序再串一個組合鍵。"""
+    if not found:
+        return
+    parts = []
+    for w in WANT:
+        v = found.get(w)
+        if not v:
+            continue
+        out.append(v)
+        parts.append(v)
+    if len(parts) > 1:
+        out.append('/'.join(parts))
+
+
 for line in lines:
+    # 目錄頁一筆一個 H2 區塊，欄位在標題底下一條一條列。
+    if line.startswith('## '):
+        take(block)
+        block = {}
+        idx, seen_sep = {}, False
+        continue
     cs = cells(line)
     if cs is None:
+        if block is not None:
+            s = line.strip()
+            if s.startswith('- '):
+                body = s[2:]
+                # 正本寫全形冒號；半形也收，舊頁手寫的那幾條才不會整條漏掉。
+                for mark in ('：', ':'):
+                    if mark in body:
+                        label, value = body.split(mark, 1)
+                        label = plain(label)
+                        for w in WANT:
+                            if w in label:
+                                v = plain(value)
+                                if v:
+                                    block[w] = v
+                                break
+                        break
         idx, seen_sep = {}, False
         continue
     if is_sep(cs):
@@ -193,7 +235,7 @@ for line in lines:
         continue
     if not idx:
         continue
-    parts = []
+    found = {}
     for w in WANT:
         i = idx.get(w)
         if i is None or i >= len(cs):
@@ -201,10 +243,10 @@ for line in lines:
         v = plain(cs[i])
         if not v:
             continue
-        out.append(v)
-        parts.append(v)
-    if len(parts) > 1:
-        out.append('/'.join(parts))
+        found[w] = v
+    take(found)
+
+take(block)
 
 for v in out:
     print(v)

tools/wiki-contents.sh

@@ -1,25 +1,48 @@
 #!/usr/bin/env sh
-# wiki-contents.sh — 目錄頁（*_CONTENTS）的表格列 upsert。
+# wiki-contents.sh — 目錄頁（*_CONTENTS）的區塊 upsert。
 #
-# 為什麼要有這支腳本：目錄頁的「找同一列就取代、找不到就附加」原本靠模型照
+# 為什麼要有這支腳本：目錄頁的「找同一筆就取代、找不到就附加」原本靠模型照
 # SKILL.md 手工做，十四個目錄頁只有一處寫成程式。同一段判斷做十四次，錯一次
 # 就少一筆紀錄。抽成一支，讀舊頁、比對鍵、整頁寫回只有一種做法。
 #
+# 版面：一筆紀錄一個 H2 區塊。H2 標題就是這一筆的鍵，寫成對應內容頁的頁名；欄位是
+# 標題底下一層條列，一行一條「- {欄位名}：{值}」。目錄頁上不留 markdown 表格。
+#
 # 用法:
-#   wiki-contents.sh upsert <TYPE> <key-col> <key> <row-file> [template-file]
+#   wiki-contents.sh upsert <TYPE> <key-col> <key> <entry-file> [template-file]
 #     TYPE          頁型，決定頁名 {TYPE}_CONTENTS
-#     key-col       鍵在表格第幾欄，1 起算
-#     key           鍵值，用來找既有列
-#     row-file      整列 markdown 表格列的檔案
-#     template-file 選用。頁不存在時用它建新頁
+#     key-col       只有舊頁還是表格時才用得到：舊表格裡持有這一筆身分的欄位序號，
+#                   1 起算。轉檔時該欄格子有連結就取網址最後一段路徑當 H2 標題，
+#                   沒有連結才取格子純文字。頁面已經是條列格式時完全忽略這個參數
+#     key           這一筆的 H2 標題文字，也就是內容頁頁名。用來找既有區塊
+#     entry-file    整個 H2 區塊的 markdown：「## {key}」那一行、空行、各條條列
+#     template-file 選用。頁不存在時用它建新頁；舊頁還是表格而要自動轉檔時，
+#                   也用它的 H1 與「>」引言取代舊頁那一份
+#
+#   wiki-contents.sh format <key-col> <key> <entry-file> <old-file> <new-file> [template-file|--fresh]
+#     只做文字處理，不碰 API，把結果寫進 new-file 並印出 updated 或 added。
+#     轉檔與 upsert 的判斷只有這一份，離線驗證餵檔案給它就好，不必打 API。
+#     第六個參數給 --fresh 代表 old-file 是範本，要剝掉示範資料；給檔案路徑
+#     則等同 upsert 的 template-file，只在轉檔那一次用來換掉引言。
 #
 # 規則:
 #   目錄頁一律住在 CONTENTS 專用存取庫，所以存取庫走 wiki-repo CONTENTS，
 #   不走各自的頁型。
+#   舊頁還是 markdown 表格時，先整頁轉成 H2 區塊再做 upsert；一頁同時有表格與區塊，
+#   表格轉出來的區塊接在既有區塊後面。三種舊頁狀態都不得毀掉別人那一筆。
+#   轉檔取 H2 標題只看身分欄那一格：有連結就取網址最後一段路徑，網址經過百分號編碼
+#   就先解碼；沒有連結就取純文字，去掉反引號與頭尾空白。取到什麼就用什麼，不驗頁名樣式。
+#   找「## {key}」：標題文字去頭尾空白後完全相等才算命中。命中就換掉整塊，從那一行
+#   到下一個「## 」之前或檔尾；沒命中就附加到最後一個區塊之後。
 #   只有 wiki-get 回 4 才准建新頁。回 7 或 8 一律中止：把金鑰失效讀成
 #   「頁面不存在」，就會拿新範本蓋掉活著的頁，舊紀錄整份沒了。
 #   這條規則的正本在 skills/wiki/SKILL.md 的 Rules 第 4 條。
-# 結束碼: 0=已更新或已新增 1=寫入失敗 2=用法錯誤 3=CONTENTS 存取庫未設定
+#   建新頁時剝掉範本的示範資料，只留 H1 與「>」引言。
+#   轉檔那一次若呼叫端給了範本，連引言一起換成範本那一份：轉檔只搬表格不動散文，
+#   舊引言會一直講「每個存取庫一列」這種只對表格成立的話，誤導之後讀的人。
+#   頁面已經是條列格式、不需要轉檔時引言原樣不動，那時呼叫端只是更新自己那一筆，
+#   沒有理由改別人寫的散文；沒給範本也保留舊引言，因為沒有正本可換。
+# 結束碼: 0=已更新或已新增 1=組不出頁面內容或寫入失敗 2=用法錯誤 3=CONTENTS 存取庫未設定
 #         4=頁不存在且沒給範本 7=金鑰失效或權限不足 8=其他 API 失敗
 set -eu
 
@@ -28,18 +51,253 @@ gitea="$dir/gitea.sh"
 page_name="$dir/page-name.sh"
 
 usage() {
-  echo 'usage: wiki-contents.sh upsert <TYPE> <key-col> <key> <row-file> [template-file]' >&2
+  echo 'usage: wiki-contents.sh upsert <TYPE> <key-col> <key> <entry-file> [template-file]' >&2
+  echo '       wiki-contents.sh format <key-col> <key> <entry-file> <old-file> <new-file> [template-file|--fresh]' >&2
   exit 2
 }
 
-[ "${1-}" = upsert ] || usage
+check_keycol() {
+  case "$1" in
+    ''|*[!0-9]*) echo "key-col must be a positive integer: $1" >&2; exit 2 ;;
+  esac
+  [ "$1" -ge 1 ] || { echo "key-col must be a positive integer: $1" >&2; exit 2; }
+}
+
+# 轉檔與 upsert 只有這一份實作。upsert 與 format 共用它，離線驗證跑的就是正式路徑那一段。
+# 參數：舊頁檔 區塊檔 鍵欄序號 鍵 輸出檔 是否為新建（1 或 0） 範本檔（沒有就給空字串）
+render() {
+  python3 - "$1" "$2" "$3" "$4" "$5" "$6" "$7" <<'PY'
+import re
+import sys
+from urllib.parse import unquote
+
+old_path, entry_path, keycol, key, new_path, fresh, template_path = sys.argv[1:8]
+keycol = int(keycol)
+fresh = fresh == '1'
+key = key.strip()
+
+lines = open(old_path, encoding='utf-8').read().split('\n')
+entry = open(entry_path, encoding='utf-8').read().strip('\n')
+
+
+def cells(line):
+    s = line.strip()
+    if not s.startswith('|'):
+        return None
+    s = s[1:]
+    if s.endswith('|'):
+        s = s[:-1]
+    return [c.strip() for c in s.split('|')]
+
+
+def is_sep(cs):
+    return bool(cs) and all(c and set(c) <= set('-: ') for c in cs)
+
+
+def plain(v):
+    # 欄名只留文字。留著連結語法或反引號，條列的欄位名就跟頁面上寫的不一樣。
+    v = re.sub(r'\[\[([^\]|]*)\|([^\]]*)\]\]', r'\1', v)
+    v = re.sub(r'\[\[([^\]]*)\]\]', r'\1', v)
+    v = re.sub(r'\[([^\]]*)\]\([^)]*\)', r'\1', v)
+    return v.replace('`', '').strip()
+
+
+def last_segment(url):
+    """取網址最後一段路徑，也就是 .../wiki/{頁名} 的頁名。"""
+    u = url.strip().split('#', 1)[0].split('?', 1)[0]
+    parts = [p for p in u.split('/') if p]
+    seg = parts[-1] if parts else ''
+    # 頁名有空白或中文時網址會被百分號編碼，解碼後才是頁面上看到的頁名。
+    return unquote(seg).replace('`', '').strip()
+
+
+def title_from_cell(v):
+    # 身分欄的連結文字常常不是頁名，是工作包名稱或計畫名稱；真正的頁名在網址最後一段。
+    # 拿連結文字當 H2 標題，就跟呼叫端傳進來的鍵對不上，同一筆會長出第二個區塊。
+    m = re.search(r'\[[^\]]*\]\(([^)]*)\)', v)
+    if m:
+        return last_segment(m.group(1))
+    # wiki 連結 [[頁名|文字]] 的目標寫在前半段，那一段就是頁名。
+    m = re.search(r'\[\[([^\]|]*)(?:\|[^\]]*)?\]\]', v)
+    if m:
+        return m.group(1).replace('`', '').strip()
+    # 沒有連結就是純文字身分欄，例如 {owner}/{repo}。取到什麼就用什麼，不判形狀。
+    return v.replace('`', '').strip()
+
+
+def split_tables(src):
+    """把每一段 markdown 表格從行清單裡拿掉。回傳剩下的行與各表格的列。"""
+    rest = []
+    tables = []
+    i = 0
+    fence = False
+    while i < len(src):
+        line = src[i]
+        # 程式碼圍欄裡的「|」是內容不是表格。mermaid 圖與範例被當表格拆掉，引言就毀了。
+        if line.lstrip().startswith('```'):
+            fence = not fence
+            rest.append(line)
+            i += 1
+            continue
+        if not fence and cells(line) is not None:
+            j = i
+            while j < len(src) and cells(src[j]) is not None:
+                j += 1
+            rows = [cells(x) for x in src[i:j]]
+            if len(rows) >= 2 and is_sep(rows[1]):
+                tables.append(rows)
+            else:
+                # 沒有分隔列就不是表格，原樣留著。
+                rest.extend(src[i:j])
+            i = j
+            continue
+        rest.append(line)
+        i += 1
+    return rest, tables
+
+
+def table_blocks(rows):
+    """一列一個 H2 區塊，欄位順序照表頭從左到右。"""
+    head = rows[0]
+    out = []
+    for cs in rows[2:]:
+        if is_sep(cs):
+            continue
+        if not any(c for c in cs):
+            continue
+        title = title_from_cell(cs[keycol - 1]) if len(cs) >= keycol else ''
+        if not title:
+            # 取不出身分就不猜標題。猜錯的標題比不到任何鍵，之後每次 upsert 都在它旁邊
+            # 再長一筆；停下來讓人看那一列，比留一筆對不上的紀錄安全。
+            sys.stderr.write(
+                '[jsc][gitea][ERR]：表格有一列取不出第 %d 欄的鍵，轉不成區塊。\n' % keycol)
+            raise SystemExit(1)
+        body = []
+        for n, name in enumerate(head):
+            label = plain(name) or ('欄位%d' % (n + 1))
+            value = cs[n].strip() if n < len(cs) else ''
+            body.append('- %s：%s' % (label, value))
+        out.append('## %s\n\n%s' % (title, '\n'.join(body)))
+    return out
+
+
+def split_blocks(src):
+    """切成引言與各 H2 區塊。第一個「## 」之前的都是引言。"""
+    pre = []
+    blocks = []
+    cur = None
+    fence = False
+    for line in src:
+        if line.lstrip().startswith('```'):
+            fence = not fence
+        if not fence and line.startswith('## '):
+            cur = [line]
+            blocks.append(cur)
+            continue
+        (cur if cur is not None else pre).append(line)
+    return pre, ['\n'.join(b).strip('\n') for b in blocks]
+
+
+def preamble(path):
+    """取一份檔案第一個「## 」之前的內容，也就是 H1 加「>」引言那一段。"""
+    src = open(path, encoding='utf-8').read().split('\n')
+    # 先拆掉表格：範本若在引言之前放了示範表格，照搬進去就等於在目錄頁上留下表格。
+    head, _ = split_blocks(split_tables(src)[0])
+    return head
+
+
+rest, tables = split_tables(lines)
+pre, blocks = split_blocks(rest)
+
+# 範本的示範區塊會被當成真的一筆。照抄進新頁，那一筆就永遠留著，之後每次 upsert 都
+# 比不到它的鍵而跳過，正式頁上多出一筆指向不存在的頁的死紀錄。所以建新頁只留引言。
+if fresh:
+    blocks = []
+else:
+    # 有表格就代表這一頁還是舊版面，這一次要轉檔。
+    converting = bool(tables)
+    for rows in tables:
+        blocks.extend(table_blocks(rows))
+    # 轉檔只搬表格、不動散文，舊引言就會一直講只對表格成立的話。範本的引言是正本，
+    # 轉檔正好是換掉它的時機。不轉檔就不動引言：那時呼叫端只是更新自己那一筆。
+    if converting and template_path:
+        tpl_pre = preamble(template_path)
+        # 範本沒有引言時保留舊的，換成空白等於把 H1 也弄掉。
+        if '\n'.join(tpl_pre).strip():
+            pre = tpl_pre
+
+# 鍵就是標題，所以標題一律重寫成 key。兩者不一致的話，這一筆下一次就找不回來。
+body = entry.split('\n')
+if body and body[0].startswith('## '):
+    body = body[1:]
+while body and not body[0].strip():
+    body = body[1:]
+block = '## %s' % key
+if body:
+    block += '\n\n' + '\n'.join(body).strip('\n')
+
+hit = -1
+for i, b in enumerate(blocks):
+    if b.split('\n', 1)[0][3:].strip() == key:
+        hit = i
+        break
+
+if hit >= 0:
+    blocks[hit] = block
+    action = 'updated'
+else:
+    blocks.append(block)
+    action = 'added'
+
+head = '\n'.join(pre).strip('\n')
+parts = ([head] if head else []) + blocks
+text = '\n\n'.join(parts)
+if not text.strip():
+    sys.stderr.write('[jsc][gitea][ERR]：組不出頁面內容，不寫入。\n')
+    raise SystemExit(1)
+
+open(new_path, 'w', encoding='utf-8').write(text + '\n')
+print(action)
+PY
+}
+
+cmd="${1-}"
+[ "$cmd" = upsert ] || [ "$cmd" = format ] || usage
 shift
+
+if [ "$cmd" = format ]; then
+  [ "$#" -ge 5 ] && [ "$#" -le 6 ] || usage
+  keycol="$1"
+  key="$2"
+  entryfile="$3"
+  oldfile="$4"
+  newfile="$5"
+  fresh=0
+  template=''
+  if [ "$#" -eq 6 ]; then
+    if [ "$6" = --fresh ]; then
+      fresh=1
+    else
+      template="$6"
+    fi
+  fi
+  check_keycol "$keycol"
+  [ -n "$key" ] || { echo 'key required' >&2; exit 2; }
+  [ -f "$entryfile" ] || { echo "找不到區塊檔案: $entryfile" >&2; exit 2; }
+  [ -f "$oldfile" ] || { echo "找不到舊頁檔案: $oldfile" >&2; exit 2; }
+  [ -z "$template" ] || [ -f "$template" ] || { echo "找不到範本檔: $template" >&2; exit 2; }
+  rc=0
+  render "$oldfile" "$entryfile" "$keycol" "$key" "$newfile" "$fresh" "$template" || rc=$?
+  [ "$rc" -eq 0 ] || exit 1
+  exit 0
+fi
+
 [ "$#" -ge 4 ] && [ "$#" -le 5 ] || usage
 
 type=$(printf '%s' "${1-}" | tr a-z A-Z)
 keycol="${2-}"
 key="${3-}"
-rowfile="${4-}"
+entryfile="${4-}"
 template="${5-}"
 
 [ -n "$type" ] || usage
@@ -48,12 +306,9 @@ page="${type}_CONTENTS"
 # 它連 CONTENTS 一起擋掉——CONTENTS 只用來解存取庫，沒有 CONTENTS_CONTENTS 這一頁。
 sh "$page_name" check "$page" >/dev/null 2>&1 || { echo "不能用來組目錄頁頁名的頁型: $type" >&2; usage; }
 
-case "$keycol" in
-  ''|*[!0-9]*) echo "key-col must be a positive integer: $keycol" >&2; exit 2 ;;
-esac
-[ "$keycol" -ge 1 ] || { echo "key-col must be a positive integer: $keycol" >&2; exit 2; }
+check_keycol "$keycol"
 [ -n "$key" ] || { echo 'key required' >&2; exit 2; }
-[ -f "$rowfile" ] || { echo "找不到列檔案: $rowfile" >&2; exit 2; }
+[ -f "$entryfile" ] || { echo "找不到區塊檔案: $entryfile" >&2; exit 2; }
 [ -z "$template" ] || [ -f "$template" ] || { echo "找不到範本檔: $template" >&2; exit 2; }
 
 # 存取庫解析失敗照原碼傳出去：3 是「沒設定」，2 是型別不認得，兩者處置不同。
@@ -88,83 +343,7 @@ case "$rc" in
 esac
 
 rc=0
-action=$(python3 - "$old" "$rowfile" "$keycol" "$key" "$new" "$fresh" <<'PY'
-import sys
-
-old_path, row_path, keycol, key, new_path, fresh = sys.argv[1:7]
-keycol = int(keycol)
-fresh = fresh == '1'
-
-lines = open(old_path, encoding='utf-8').read().split('\n')
-row = open(row_path, encoding='utf-8').read().strip('\n')
-
-
-def cells(line):
-    s = line.strip()
-    if not s.startswith('|'):
-        return None
-    s = s[1:]
-    if s.endswith('|'):
-        s = s[:-1]
-    return [c.strip() for c in s.split('|')]
-
-
-def is_sep(cs):
-    return bool(cs) and all(c and set(c) <= set('-: ') for c in cs)
-
-
-# 範本表格的示範列落在分隔列之後，會被當成真的資料列。照抄進新頁，那一列就永遠留著，
-# 之後每次 upsert 都比不到它的鍵而跳過，正式頁上多出一條指向不存在的頁的死連結。
-# 所以建新頁時剝掉分隔列之後的所有資料列，只留標題、說明、表頭與分隔列。
-if fresh:
-    kept = []
-    passed_sep = False
-    for line in lines:
-        cs = cells(line)
-        if cs is None:
-            kept.append(line)
-            continue
-        if is_sep(cs):
-            passed_sep = True
-            kept.append(line)
-            continue
-        if passed_sep:
-            continue
-        kept.append(line)
-    lines = kept
-
-# 分隔列之前的都是表頭。從分隔列之後才開始比對鍵，表頭第一欄剛好等於鍵時才不會被改掉。
-seen_sep = False
-hit = -1
-last_row = -1
-for i, line in enumerate(lines):
-    cs = cells(line)
-    if cs is None:
-        continue
-    if is_sep(cs):
-        seen_sep = True
-        last_row = i
-        continue
-    if not seen_sep:
-        continue
-    last_row = i
-    if hit < 0 and len(cs) >= keycol and cs[keycol - 1] == key:
-        hit = i
-
-if hit >= 0:
-    lines[hit] = row
-    action = 'updated'
-elif last_row >= 0:
-    lines.insert(last_row + 1, row)
-    action = 'added'
-else:
-    sys.stderr.write('[jsc][gitea][ERR]：頁面裡找不到 markdown 表格，無處可放這一列。\n')
-    raise SystemExit(1)
-
-open(new_path, 'w', encoding='utf-8').write('\n'.join(lines))
-print(action)
-PY
-) || rc=$?
+action=$(render "$old" "$entryfile" "$keycol" "$key" "$new" "$fresh" "$template") || rc=$?
 # 整不出正確的頁就不要送出去。組不出內容跟送出失敗一樣寫不進去，共用結束碼 1。
 [ "$rc" -eq 0 ] || exit 1