助理巡檢目錄頁改成大標題加條列，巡檢輸出檔改名 contents-entry.md #13

2026-09-02T09:26:18Z

jiantw83 commented

2026-09-02 09:26:18 +00:00

摘要

需求描述：所有 wiki 目錄頁（*_CONTENTS）的呈現格式從 markdown 表格改成「大標題加條列」，一筆紀錄一個 H2 區塊，H2 標題就是這一筆的鍵，欄位是標題底下一層的條列 - {欄位名}：{值}，目錄頁上不留任何 markdown 表格。本支負責 jsc-assist 這一段：巡檢目錄頁 MONITOR_CONTENTS 的範本與敘述轉條列，一台機器一個區塊；tools/patrol.sh 改組區塊檔。內容頁 MONITOR_{HASH} 維持原本的固定三塊與圖表優先，不在這一輪範圍。
計畫名稱：無
計畫頁：無
分析頁：無

呼叫端契約變更：contents.tsv 改名 contents-entry.md。tools/patrol.sh collect 印出的 contents_file= 從 {暫存目錄}/contents.tsv 改成 {暫存目錄}/contents-entry.md，內容也從 page=、row= 這類逐行欄位變成一整段 markdown 區塊。寫死舊檔名或還在解析 row= 的呼叫端會讀不到檔，或讀到讀得開卻意義全錯的內容。舊檔名說的是逐欄對照的資料檔，內容其實是 markdown，所以連檔名一起換掉——同名換格式的話，還沒跟上的呼叫端不會出錯，只會靜靜寫錯一頁。

變更內容

檔案	為什麼改
`templates/monitor-contents.md`	版面從表格改成一台機器一個 H2 區塊，標題寫成該台機器監控頁的實際頁名。原本用 `## 欄位說明`、`## 寫入規則` 寫的說明區段全部搬進 `>` 引言：留在二階標題上，轉檔後會被讀成一筆假紀錄
`templates/monitor-page.md`	內容頁範本裡提到目錄頁的段落跟著改口，一併把「只更新自己那一列」改成「只更新自己那一個區塊」
`tools/patrol.sh`	`collect` 組給目錄頁的輸出從一列表格改成一整個區塊；輸出檔改名 `contents-entry.md`，`contents_file=` 指向新檔名。新增 `oneline` 處理條列值
`tools/schedule.sh`	權限規則說明裡「目錄頁那一列改由 `wiki-contents.sh` 寫」的措辭跟上區塊語意，放行規則本身不動
`skills/assistant/SKILL.md`	upsert 呼叫改成 `upsert MONITOR 1 "MONITOR_{HASH}"`：鍵改成 H2 標題也就是內容頁頁名。並補上 `key-col` 只在舊表格頁轉檔時有意義的說明，以及完成條件改成「頁上恰好一個 `## MONITOR_{HASH}` 區塊」
`README.md`、`AGENTS.md`、`references/behaviors.md`	文件與範本各說一套時，照文件手工補紀錄的人會補出一列表格，那一列在條列頁上讀不成一筆紀錄，下一輪工具重寫也不會把它當成既有那一筆換掉
`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json`	目錄頁版面與巡檢輸出檔名都變了，版號不動版本守衛就看不出機器上裝的是舊版。三份 manifest 同步升版至 `0.1.5`

設計重點

四個決策：

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

**比對鍵從裸 HASH 那一格改成 H2 標題。**標題寫成 MONITOR_{HASH}，只由 {主機名}/{登入帳號} 決定：GITEA_HOST 一換、JSC_WIKI_REPO_MONITOR 改指別的存取庫、Gitea 對頁名的編碼有差，都動不到它。含網址的那一條連結照樣留著給人點，但不當鍵——拿它當鍵，上面任一件事一變，這一輪的文字就跟上一輪不一樣，比不到既有那一筆就走附加。這一頁每 15 分鐘寫一次，重複區塊累積得很快。
**key-col 傳 1，而且只在舊表格頁轉檔時用得到。**線上舊頁第 1 欄是監控頁連結，格子是 [MONITOR_{HASH}]({網址})，轉檔取其中的頁名當標題。頁面已經是條列格式就完全忽略這個參數，所以一律傳 1，不要照當下頁面重新推算欄號。
**為什麼欄位改條列就不怕欄位增減。**表格的欄位組合是整頁共用的，表頭跟著建頁那一台機器走，之後每一台只改自己那一列。欄位一增減，只有跑到新版的機器寫得出新的格數，同一張表混著兩種格數，多出來的那一格對不到任何欄名；而目錄頁沒有整頁改寫的路可以走，整頁覆蓋等於刪掉別台機器的紀錄。條列一筆一個區塊，欄位各自獨立。
**oneline 的兩個判準。**值裡的換行一律壓成空白：一條條列裡的換行會被讀成另一條，或讓整個區塊提早結束。| 反而不跳脫：條列裡沒有切欄的意思，跳脫過的符號會原樣顯示在頁面上。
裸 HASH 照樣留一條。標題是 MONITOR_ 接上它，留這一條讓人不必從標題切字串就抄得到。
監控頁那一條的網址仍然留 {監控頁絕對網址} 佔位，由呼叫端換成真網址、過完 link-check.sh 才寫。tools/patrol.sh 一頁都不寫，兩次 wiki 寫入都在呼叫端，驗證的時機也在呼叫端。

測試結果

sh /root/plugins/meta/tools/lint-scripts.sh . → 通過 2 支（語法、可執行、結束碼宣告），結束碼 0。
sh /root/plugins/meta/tools/check-behaviors.sh . → 通過，行為清單對上 1 支技能，五個欄位齊全，結束碼 0。
sh /root/plugins/meta/tools/lint-frontmatter.sh . → 通過 1 支，結束碼 0。
sh /root/plugins/hooks/hooks/comment-scope.sh sweep . → 無命中，結束碼 0。首輪掃到 tools/patrol.sh 一行註解夾帶目錄頁頁名，已就地改成「目錄頁」後重掃通過。
未跑實機巡檢：patrol collect 之後的兩次寫入都會動到線上 wiki，前置 PR 未合之前寫進去會被舊版工具當成表格列附加。實機驗證留到部署階段。

前置 Push Request

plugins/gitea#52 — plugins/gitea 的 wiki-contents.sh 主體改寫，必須先合。本支只改敘述與範本，實際的轉檔與 upsert 邏輯全在那一支。它沒合之前就部署本支，範本組出來的 H2 區塊會被舊版工具當成表格列附加到表格後面，線上目錄頁會變成半表格半條列。

## 摘要 - 需求描述：所有 wiki 目錄頁（`*_CONTENTS`）的呈現格式從 markdown 表格改成「大標題加條列」，一筆紀錄一個 H2 區塊，H2 標題就是這一筆的鍵，欄位是標題底下一層的條列 `- {欄位名}：{值}`，目錄頁上不留任何 markdown 表格。本支負責 `jsc-assist` 這一段：巡檢目錄頁 `MONITOR_CONTENTS` 的範本與敘述轉條列，一台機器一個區塊；`tools/patrol.sh` 改組區塊檔。內容頁 `MONITOR_{HASH}` 維持原本的固定三塊與圖表優先，不在這一輪範圍。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 > **呼叫端契約變更：`contents.tsv` 改名 `contents-entry.md`。**`tools/patrol.sh collect` 印出的 `contents_file=` 從 `{暫存目錄}/contents.tsv` 改成 `{暫存目錄}/contents-entry.md`，內容也從 `page=`、`row=` 這類逐行欄位變成一整段 markdown 區塊。寫死舊檔名或還在解析 `row=` 的呼叫端會讀不到檔，或讀到讀得開卻意義全錯的內容。舊檔名說的是逐欄對照的資料檔，內容其實是 markdown，所以連檔名一起換掉——同名換格式的話，還沒跟上的呼叫端不會出錯，只會靜靜寫錯一頁。 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `templates/monitor-contents.md` | 版面從表格改成一台機器一個 H2 區塊，標題寫成該台機器監控頁的實際頁名。原本用 `## 欄位說明`、`## 寫入規則` 寫的說明區段全部搬進 `>` 引言：留在二階標題上，轉檔後會被讀成一筆假紀錄 | | `templates/monitor-page.md` | 內容頁範本裡提到目錄頁的段落跟著改口，一併把「只更新自己那一列」改成「只更新自己那一個區塊」 | | `tools/patrol.sh` | `collect` 組給目錄頁的輸出從一列表格改成一整個區塊；輸出檔改名 `contents-entry.md`，`contents_file=` 指向新檔名。新增 `oneline` 處理條列值 | | `tools/schedule.sh` | 權限規則說明裡「目錄頁那一列改由 `wiki-contents.sh` 寫」的措辭跟上區塊語意，放行規則本身不動 | | `skills/assistant/SKILL.md` | upsert 呼叫改成 `upsert MONITOR 1 "MONITOR_{HASH}"`：鍵改成 H2 標題也就是內容頁頁名。並補上 `key-col` 只在舊表格頁轉檔時有意義的說明，以及完成條件改成「頁上恰好一個 `## MONITOR_{HASH}` 區塊」 | | `README.md`、`AGENTS.md`、`references/behaviors.md` | 文件與範本各說一套時，照文件手工補紀錄的人會補出一列表格，那一列在條列頁上讀不成一筆紀錄，下一輪工具重寫也不會把它當成既有那一筆換掉 | | `.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json` | 目錄頁版面與巡檢輸出檔名都變了，版號不動版本守衛就看不出機器上裝的是舊版。三份 manifest 同步升版至 `0.1.5` | ## 設計重點四個決策： | 決策點 | 答案 | | --- | --- | | 版面形狀 | 每一筆一個 H2 大標題，欄位改成標題底下的一層條列 | | 鍵的落點 | H2 標題本身就是鍵，寫成該筆對應內容頁的實際頁名 | | 既有表格頁 | `wiki-contents.sh` 讀到表格就自動轉成條列後寫回，不另跑批次搬移 | | 邏輯落點 | 改 `gitea/tools/wiki-contents.sh`，不新增第二支工具 | - **比對鍵從裸 HASH 那一格改成 H2 標題。**標題寫成 `MONITOR_{HASH}`，只由 `{主機名}/{登入帳號}` 決定：`GITEA_HOST` 一換、`JSC_WIKI_REPO_MONITOR` 改指別的存取庫、Gitea 對頁名的編碼有差，都動不到它。含網址的那一條連結照樣留著給人點，但不當鍵——拿它當鍵，上面任一件事一變，這一輪的文字就跟上一輪不一樣，比不到既有那一筆就走附加。這一頁每 15 分鐘寫一次，重複區塊累積得很快。 - **`key-col` 傳 `1`，而且只在舊表格頁轉檔時用得到。**線上舊頁第 1 欄是監控頁連結，格子是 `[MONITOR_{HASH}]({網址})`，轉檔取其中的頁名當標題。頁面已經是條列格式就完全忽略這個參數，所以一律傳 `1`，不要照當下頁面重新推算欄號。 - **為什麼欄位改條列就不怕欄位增減。**表格的欄位組合是整頁共用的，表頭跟著建頁那一台機器走，之後每一台只改自己那一列。欄位一增減，只有跑到新版的機器寫得出新的格數，同一張表混著兩種格數，多出來的那一格對不到任何欄名；而目錄頁沒有整頁改寫的路可以走，整頁覆蓋等於刪掉別台機器的紀錄。條列一筆一個區塊，欄位各自獨立。 - **`oneline` 的兩個判準。**值裡的換行一律壓成空白：一條條列裡的換行會被讀成另一條，或讓整個區塊提早結束。`|` 反而不跳脫：條列裡沒有切欄的意思，跳脫過的符號會原樣顯示在頁面上。 - 裸 HASH 照樣留一條。標題是 `MONITOR_` 接上它，留這一條讓人不必從標題切字串就抄得到。 - 監控頁那一條的網址仍然留 `{監控頁絕對網址}` 佔位，由呼叫端換成真網址、過完 `link-check.sh` 才寫。`tools/patrol.sh` 一頁都不寫，兩次 wiki 寫入都在呼叫端，驗證的時機也在呼叫端。 ## 測試結果 - `sh /root/plugins/meta/tools/lint-scripts.sh .` → 通過 2 支（語法、可執行、結束碼宣告），結束碼 0。 - `sh /root/plugins/meta/tools/check-behaviors.sh .` → 通過，行為清單對上 1 支技能，五個欄位齊全，結束碼 0。 - `sh /root/plugins/meta/tools/lint-frontmatter.sh .` → 通過 1 支，結束碼 0。 - `sh /root/plugins/hooks/hooks/comment-scope.sh sweep .` → 無命中，結束碼 0。首輪掃到 `tools/patrol.sh` 一行註解夾帶目錄頁頁名，已就地改成「目錄頁」後重掃通過。 - 未跑實機巡檢：`patrol collect` 之後的兩次寫入都會動到線上 wiki，前置 PR 未合之前寫進去會被舊版工具當成表格列附加。實機驗證留到部署階段。 ## 前置 Push Request - https://gitea.jsc.idv.tw/plugins/gitea/pulls/52 — `plugins/gitea` 的 `wiki-contents.sh` 主體改寫，必須先合。本支只改敘述與範本，實際的轉檔與 upsert 邏輯全在那一支。它沒合之前就部署本支，範本組出來的 H2 區塊會被舊版工具當成表格列附加到表格後面，線上目錄頁會變成半表格半條列。

jiantw83 added 3 commits 2026-09-02 09:26:18 +00:00

feat(wiki): 巡檢目錄頁改成一台機器一個大標題區塊 311cdc611a

巡檢目錄頁的版面從 markdown 表格換成「大標題加條列」：一台機器一個大標題
區塊，標題就是那一台機器監控頁的實際頁名，欄位改成標題底下的一層條列。
範本、技能敘述、行為清單與說明文件一併跟上，目錄頁上不再留任何表格。

表格的欄位組合是整頁共用的，表頭跟著建頁那一台機器走，之後每一台只改自己
那一列。欄位一增減，只有跑到新版的機器寫得出新的格數，同一張表就混著兩種
格數，多出來的那一格對不到任何欄名，而目錄頁又沒有整頁改寫的路可以走——
整頁覆蓋等於刪掉別台機器的紀錄。條列一筆一個區塊，欄位各自獨立，加一條只
動到自己那一個區塊。

比對鍵從裸雜湊那一格改成大標題本身，標題寫成監控頁的實際頁名。頁名只由
主機名與登入帳號決定，換主機位址、換專用存取庫或換一種頁名編碼都動不到
它；含網址的那一條連結照樣留著給人點，但不當鍵。呼叫改成拿頁名當鍵，欄號
那個參數只在舊表格頁轉檔時用得到。範本原本用二階標題寫的說明區段全部搬進
引言，否則轉檔後會被當成一筆真紀錄讀進去。

範圍是助理的巡檢目錄頁與 assistant 技能的敘述。

feat(patrol): 巡檢改組目錄頁區塊檔，輸出檔改名 contents-entry.md d8aa0b1f5d

一輪巡檢組給目錄頁的輸出，從一列 markdown 表格改成一整個大標題區塊：
`## {監控頁頁名}` 那一行、空行，然後每個欄位一條 `- {欄位名}：{值}`。輸出
檔跟著從 `contents.tsv` 改名 `contents-entry.md`，`contents_file=` 指向
新檔名。

目錄頁已經不放表格，再組出那一列就沒有地方放。舊檔名說的是逐欄對照的資料
檔，內容其實是一段 markdown，名不對實會讓呼叫端以為還能逐欄解析。改名讓
呼叫端契約的變動在檔名上就看得見，而不是同名檔悄悄換了格式——同名換格式
的話，還沒跟上的呼叫端會拿到讀得開卻意義全錯的內容。

新增 `oneline` 處理條列一條的值：換行一律壓成空白，因為一條條列裡的換行會
被讀成另一條，或者讓整個區塊提早結束；`|` 反而不跳脫，條列裡沒有切欄的
意思，跳脫過的符號會原樣顯示在頁面上。監控頁那一條的網址仍然留佔位，由
呼叫端換成真網址、驗過連得到才寫，這支腳本一頁都不寫。裸雜湊照樣留一條，
讓人不必從標題切字串就抄得到。

範圍是一輪巡檢給目錄頁的輸出檔。

chore(manifest): 三份 manifest 升版至 0.1.5 8053c15425

三份外掛清單的版號一起往上推一版。

目錄頁的版面與巡檢輸出檔名都變了，呼叫端要靠版號才判得出手上這一份是新的
還是舊的。版號不動，版本閘門就不會提示更新，機器上會留著舊版工具去讀新版
範本。

三份清單各自被不同的 CLI 讀，值必須一致，所以一起改、一起提交。

範圍是外掛清單的版號宣告。

jiantw83 added a new dependency 2026-09-02 09:26:30 +00:00

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

admin merged commit 225478f756 into develop

2026-09-02 10:00:32 +00:00

admin deleted branch feat/contents-list/main

2026-09-02 10:00:32 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Depends on

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

plugins/gitea

Reference: plugins/assist#13