工作日誌三個目錄頁改成大標題加條列，三支技能的呼叫與敘述同步 #36

2026-09-02T09:26:24Z

jiantw83 commented

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

摘要

需求描述：所有 wiki 目錄頁（*_CONTENTS）的呈現格式從 markdown 表格改成「大標題加條列」，一筆紀錄一個 H2 區塊，H2 標題就是這一筆的鍵，欄位是標題底下一層的條列 - {欄位名}：{值}，目錄頁上不留任何 markdown 表格。本支負責 jsc-log 這一段：LOG_CONTENTS、LEARN_CONTENTS、REPORT_CONTENTS 三個目錄頁範本轉條列，worklog、learn、report 三支技能的 upsert 呼叫與敘述同步。內容頁維持原本的圖表優先，不在這一輪範圍。
計畫名稱：無
計畫頁：無
分析頁：無

變更內容

檔案	為什麼改
`templates/log-contents.md`	版面從表格改成一個日誌頁一個 H2 區塊，標題寫成該日誌頁的實際頁名；引言補上參數語意，說明 `<key-col>`、`<key>` 與第四個參數各自代表什麼
`skills/worklog/SKILL.md`	upsert 呼叫從 `upsert LOG 2 "{HASH}"` 改成 `upsert LOG 1 "LOG_{HASH}"`：鍵改成 H2 標題也就是內容頁頁名。連帶把「列」的措辭、退出碼說明與 `degraded` 判準改成區塊語意
`templates/learn-contents.md`	同上轉條列。`<key-col>` 一併從 `1` 改成 `2`：線上這一頁的身分欄是教訓紀錄那一欄，不是存取庫名稱那一欄
`skills/learn/SKILL.md`	upsert 呼叫從 `upsert LEARN 1 "{owner}/{repo}"` 改成 `upsert LEARN 2 "LEARN_{HASH}"`，敘述同步
`templates/report-contents.md`	同上轉條列。原本說明「換報表存取庫會多出四列」的段落改口成區塊，那件事本身仍然成立
`skills/report/SKILL.md`	upsert 呼叫從 `upsert REPORT 2 "{HASH}"` 改成 `upsert REPORT 1 "REPORT_{HASH}"`，敘述與退出碼說明同步
`README.md`、`references/behaviors.md`	文件與範本各說一套時，照文件手工補紀錄的人會補出一列表格，那一列在條列頁上讀不成一筆紀錄，下一輪工具重寫也不會把它當成既有那一筆換掉
`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json`	三個目錄頁的版面與寫入參數都變了，版號不動版本守衛就看不出機器上裝的是舊版。三份 manifest 同步升版至 `0.1.9`

設計重點

四個決策：

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

三個頁型的鍵一律改成內容頁頁名。LOG_{HASH} 與 LEARN_{HASH} 只由 {owner}/{repo} 決定，REPORT_{HASH} 只由 {owner}/{repo}/{期間} 決定：換主機位址、把內容頁移到別的存取庫、Gitea 對頁名的編碼有差，都動不到它。含網址的那一條連結照樣留著給人點，但不當鍵——拿它當鍵，上面任一件事一變，這一輪的文字就跟上一輪不一樣，比不到既有那一筆就走附加，同一個內容頁多出第二個區塊，舊區塊從此再也更新不到。
**key-col 三支各不相同，因為線上三頁的身分欄各不相同。**日誌頁與報表頁的第 1 欄是內容頁連結，所以傳 1；教訓頁第 1 欄是存取庫名稱、第 2 欄才是教訓紀錄連結，所以傳 2。這個參數只在舊頁還是表格時用得到，轉檔時取那一格的文字當 H2 標題，格子寫成連結就只取其中的頁名；頁面已經是條列格式就完全忽略它。填錯的話轉出來的標題跟鍵對不上，既有那一筆會被當成新的附加上去，同一筆變兩個區塊。
**為什麼欄位改條列就不怕欄位增減。**表格的欄位組合是整頁共用的，一頁上卻有很多存取庫各自的紀錄，每一輪只重寫自己那一列。欄位一增減，舊列的格數與表頭就對不上；而目錄頁不能整頁覆蓋，覆蓋等於刪掉別人的紀錄。條列一筆一個區塊，欄位各自獨立，加一條只動到自己那一個區塊。
「換報表存取庫」與「鍵失準」是兩回事：雜湊本身就取自報表 wiki 存取庫，換庫等於換頁，四種期間會各多一個區塊。那是換庫的本意，舊區塊請人工清掉。
寫入前驗證的位置不動：每個要寫進目錄頁的連結先過 link-check.sh，結束碼 0 才寫，出現 DEAD 就不寫那一個區塊並回報。

測試結果

sh /root/plugins/meta/tools/check-behaviors.sh . → 通過，行為清單對上 4 支技能，五個欄位齊全，結束碼 0。
sh /root/plugins/meta/tools/lint-frontmatter.sh . → 通過 4 支（分隔線、必要鍵、冒號、起頭字元、引號），結束碼 0。
sh /root/plugins/hooks/hooks/comment-scope.sh sweep . → 無命中，結束碼 0。
本支沒有腳本變更，tools/ 一支未動，所以沒有可跑的腳本檢查。實際寫入行為全在前置 PR 那一支，實機驗證留到部署階段。

前置 Push Request

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

## 摘要 - 需求描述：所有 wiki 目錄頁（`*_CONTENTS`）的呈現格式從 markdown 表格改成「大標題加條列」，一筆紀錄一個 H2 區塊，H2 標題就是這一筆的鍵，欄位是標題底下一層的條列 `- {欄位名}：{值}`，目錄頁上不留任何 markdown 表格。本支負責 `jsc-log` 這一段：`LOG_CONTENTS`、`LEARN_CONTENTS`、`REPORT_CONTENTS` 三個目錄頁範本轉條列，`worklog`、`learn`、`report` 三支技能的 upsert 呼叫與敘述同步。內容頁維持原本的圖表優先，不在這一輪範圍。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `templates/log-contents.md` | 版面從表格改成一個日誌頁一個 H2 區塊，標題寫成該日誌頁的實際頁名；引言補上參數語意，說明 `<key-col>`、`<key>` 與第四個參數各自代表什麼 | | `skills/worklog/SKILL.md` | upsert 呼叫從 `upsert LOG 2 "{HASH}"` 改成 `upsert LOG 1 "LOG_{HASH}"`：鍵改成 H2 標題也就是內容頁頁名。連帶把「列」的措辭、退出碼說明與 `degraded` 判準改成區塊語意 | | `templates/learn-contents.md` | 同上轉條列。`<key-col>` 一併從 `1` 改成 `2`：線上這一頁的身分欄是教訓紀錄那一欄，不是存取庫名稱那一欄 | | `skills/learn/SKILL.md` | upsert 呼叫從 `upsert LEARN 1 "{owner}/{repo}"` 改成 `upsert LEARN 2 "LEARN_{HASH}"`，敘述同步 | | `templates/report-contents.md` | 同上轉條列。原本說明「換報表存取庫會多出四列」的段落改口成區塊，那件事本身仍然成立 | | `skills/report/SKILL.md` | upsert 呼叫從 `upsert REPORT 2 "{HASH}"` 改成 `upsert REPORT 1 "REPORT_{HASH}"`，敘述與退出碼說明同步 | | `README.md`、`references/behaviors.md` | 文件與範本各說一套時，照文件手工補紀錄的人會補出一列表格，那一列在條列頁上讀不成一筆紀錄，下一輪工具重寫也不會把它當成既有那一筆換掉 | | `.claude-plugin/plugin.json`、`.codex-plugin/plugin.json`、`plugin.json` | 三個目錄頁的版面與寫入參數都變了，版號不動版本守衛就看不出機器上裝的是舊版。三份 manifest 同步升版至 `0.1.9` | ## 設計重點四個決策： | 決策點 | 答案 | | --- | --- | | 版面形狀 | 每一筆一個 H2 大標題，欄位改成標題底下的一層條列 | | 鍵的落點 | H2 標題本身就是鍵，寫成該筆對應內容頁的實際頁名 | | 既有表格頁 | `wiki-contents.sh` 讀到表格就自動轉成條列後寫回，不另跑批次搬移 | | 邏輯落點 | 改 `gitea/tools/wiki-contents.sh`，不新增第二支工具 | - **三個頁型的鍵一律改成內容頁頁名。**`LOG_{HASH}` 與 `LEARN_{HASH}` 只由 `{owner}/{repo}` 決定，`REPORT_{HASH}` 只由 `{owner}/{repo}/{期間}` 決定：換主機位址、把內容頁移到別的存取庫、Gitea 對頁名的編碼有差，都動不到它。含網址的那一條連結照樣留著給人點，但不當鍵——拿它當鍵，上面任一件事一變，這一輪的文字就跟上一輪不一樣，比不到既有那一筆就走附加，同一個內容頁多出第二個區塊，舊區塊從此再也更新不到。 - **`key-col` 三支各不相同，因為線上三頁的身分欄各不相同。**日誌頁與報表頁的第 1 欄是內容頁連結，所以傳 `1`；教訓頁第 1 欄是存取庫名稱、第 2 欄才是教訓紀錄連結，所以傳 `2`。這個參數只在舊頁還是表格時用得到，轉檔時取那一格的文字當 H2 標題，格子寫成連結就只取其中的頁名；頁面已經是條列格式就完全忽略它。填錯的話轉出來的標題跟鍵對不上，既有那一筆會被當成新的附加上去，同一筆變兩個區塊。 - **為什麼欄位改條列就不怕欄位增減。**表格的欄位組合是整頁共用的，一頁上卻有很多存取庫各自的紀錄，每一輪只重寫自己那一列。欄位一增減，舊列的格數與表頭就對不上；而目錄頁不能整頁覆蓋，覆蓋等於刪掉別人的紀錄。條列一筆一個區塊，欄位各自獨立，加一條只動到自己那一個區塊。 - 「換報表存取庫」與「鍵失準」是兩回事：雜湊本身就取自報表 wiki 存取庫，換庫等於換頁，四種期間會各多一個區塊。那是換庫的本意，舊區塊請人工清掉。 - 寫入前驗證的位置不動：每個要寫進目錄頁的連結先過 `link-check.sh`，結束碼 0 才寫，出現 DEAD 就不寫那一個區塊並回報。 ## 測試結果 - `sh /root/plugins/meta/tools/check-behaviors.sh .` → 通過，行為清單對上 4 支技能，五個欄位齊全，結束碼 0。 - `sh /root/plugins/meta/tools/lint-frontmatter.sh .` → 通過 4 支（分隔線、必要鍵、冒號、起頭字元、引號），結束碼 0。 - `sh /root/plugins/hooks/hooks/comment-scope.sh sweep .` → 無命中，結束碼 0。 - 本支沒有腳本變更，`tools/` 一支未動，所以沒有可跑的腳本檢查。實際寫入行為全在前置 PR 那一支，實機驗證留到部署階段。 ## 前置 Push Request - https://gitea.jsc.idv.tw/plugins/gitea/pulls/52 — `plugins/gitea` 的 `wiki-contents.sh` 主體改寫，必須先合。本支只改敘述與範本，實際的轉檔與 upsert 邏輯全在那一支。它沒合之前就部署本支，範本組出來的 H2 區塊會被舊版工具當成表格列附加到表格後面，線上目錄頁會變成半表格半條列。

jiantw83 added 5 commits 2026-09-02 09:26:25 +00:00

feat(worklog): 日誌目錄頁改成一個日誌頁一個大標題區塊 fbfe424c39

日誌目錄頁的版面從 markdown 表格換成「大標題加條列」：一個日誌頁一個大標題
區塊，標題就是那個日誌頁的實際頁名，週五日期、條目數這些欄位改成標題底下的
一層條列。範本與 worklog 技能的寫入敘述、完成條件、退出碼說明一起跟上。

表格的欄位組合是整頁共用的，一頁上卻有很多存取庫各自的紀錄，每一輪只重寫
自己那一列。欄位一增減，舊列的格數與表頭就對不上，而目錄頁不能整頁覆蓋——
覆蓋等於刪掉別人的紀錄。條列一筆一個區塊，欄位各自獨立，加一條只動到自己
那一個區塊。

比對鍵從裸雜湊那一格改成大標題本身，標題寫成日誌頁的實際頁名。頁名只由
存取庫的擁有者與名稱決定，換主機位址、把日誌頁移到別的存取庫，或頁名編碼
有差，都動不到它；含網址的那一條連結照樣留著給人點，但不當鍵——拿它當鍵，
上面任一件事一變，這一輪的文字就跟上一輪不一樣，比不到既有那一筆就走附加，
同一個日誌頁多出第二個區塊，舊區塊從此再也更新不到。欄號那個參數只在舊
表格頁轉檔時用得到，頁面已經是條列就完全忽略它。

範圍是工作日誌的目錄頁與 worklog 技能。

feat(learn): 教訓目錄頁改成一個存取庫一個大標題區塊 cce75e2f45

教訓目錄頁的版面從 markdown 表格換成「大標題加條列」：一個存取庫一個大標題
區塊，標題就是那個存取庫教訓頁的實際頁名，存取庫名稱、教訓紀錄連結、最後
更新時間改成標題底下的一層條列。範本與 learn 技能的寫入敘述一起跟上。

表格的欄位組合是整頁共用的，一頁上卻有很多存取庫各自的紀錄，每一輪只重寫
自己那一列。欄位一增減，舊列的格數與表頭就對不上，而目錄頁不能整頁覆蓋——
覆蓋等於刪掉別人的紀錄。條列一筆一個區塊，欄位各自獨立，加一條只動到自己
那一個區塊。

比對鍵從存取庫名稱那一格改成大標題本身，標題寫成教訓頁的實際頁名。頁名只由
存取庫的擁有者與名稱決定，換主機位址、改存取庫或頁名編碼有差都動不到它。
欄號那個參數配合線上實際欄位改成教訓紀錄那一欄：轉檔時取那一格的文字當
標題，格子寫成連結就只取顯示文字。欄號填錯的話，轉出來的標題跟鍵對不上，
既有那一筆會被當成新的附加上去，同一個存取庫變兩個區塊。

範圍是教訓紀錄的目錄頁與 learn 技能。

feat(report): 報表目錄頁改成一個報表頁一個大標題區塊 369b327a4f

報表目錄頁的版面從 markdown 表格換成「大標題加條列」：一個報表頁一個大標題
區塊，也就是一個存取庫的一種期間一個區塊，標題就是那個報表頁的實際頁名，
期間、最新一期、期數這些欄位改成標題底下的一層條列。範本與 report 技能的
寫入敘述與退出碼說明一起跟上。

表格的欄位組合是整頁共用的，一頁上卻有很多報表頁各自的紀錄，每一輪只重寫
自己那一列。欄位一增減，舊列的格數與表頭就對不上，而目錄頁不能整頁覆蓋——
覆蓋等於刪掉別人的紀錄。條列一筆一個區塊，欄位各自獨立，加一條只動到自己
那一個區塊。

比對鍵從裸雜湊那一格改成大標題本身，標題寫成報表頁的實際頁名。頁名只由
存取庫的擁有者、名稱與期間決定，換主機位址或頁名編碼有差都動不到它；含
網址的那一條連結照樣留著給人點，但不當鍵。把報表存取庫改指別的庫是另一回
事：雜湊本身就取自那個庫，換庫等於換頁，四種期間會各多一個區塊，那是換庫
的本意，不是鍵失準，舊區塊請人工清掉。

範圍是工作報表的目錄頁與 report 技能。

docs(behaviors): 說明文件與行為清單跟上目錄頁的條列版面 18d12bbbe2

存取庫說明與技能行為清單裡講到目錄頁的段落一律改口：一筆一個大標題區塊、
標題就是內容頁頁名也就是鍵、欄位是標題底下的一層條列，頁上不留表格。

三個目錄頁的範本與三支技能的敘述都換了版面，說明文件卻還寫著「一列」與
「表格」。文件與範本各說一套，照文件手工補紀錄的人會補出一列表格，那一列
在條列頁上讀不成一筆紀錄，而且下一輪工具重寫時也不會被當成既有那一筆換掉。

只改敘述，行為與呼叫參數都不動；欄位語意與寫入語意的正本仍在各自的範本
引言裡，這裡只指向它，不重述細節。

範圍是說明文件與技能行為清單裡的目錄頁敘述。

chore(manifest): 三份 manifest 升版至 0.1.9 fda0fca304

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

三個目錄頁的版面與寫入參數都變了，呼叫端要靠版號才判得出手上這一份是新的
還是舊的。版號不動，版本閘門就不會提示更新，機器上會留著舊版敘述去寫新版
目錄頁。

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

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

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

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

admin merged commit 4c7b63d43a into develop

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

admin deleted branch feat/contents-list/main

2026-09-02 10:00:44 +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/log#36