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

體檢目錄頁改成大標題加條列，doctor 與 setup 的呼叫同步換鍵 #58

Merged
admin merged 2 commits from feat/contents-list/main into develop 2026-09-02 10:00:37 +00:00
Conversation 0 Commits 2 Files Changed 8
+59 -43
jiantw83 commented 2026-09-02 09:25:52 +00:00
Member
Copy Link
Copy Source

摘要

  • 需求描述：所有 wiki 目錄頁（*_CONTENTS）的呈現格式從 markdown 表格改成「大標題加條列式」——一筆紀錄一個 H2 區塊，H2 標題就是這一筆的鍵（該筆對應內容頁的實際頁名），欄位是標題底下的一層條列 - {欄位名}：{值}，目錄頁上不留任何 markdown 表格。本存取庫負責體檢目錄頁 CHECK_CONTENTS 的範本，以及 doctor 與 setup 兩支技能對它的呼叫，實際的轉檔與 upsert 邏輯全部在 gitea/tools/wiki-contents.sh。內容頁維持原本的圖表優先，不在這一輪的範圍。
  • 計畫名稱：無
  • 計畫頁：無
  • 分析頁：無

變更內容

檔案 為什麼改
templates/check-contents.md 版面從七欄 markdown 表格改成一台執行環境一個 H2 區塊，標題是體檢頁頁名 CHECK_{HASH}，七個欄位改成 - {欄位名}：{值} 的一層條列；引言補上參數語意，並把「鍵用裸 HASH」的說法改成「鍵用頁名」
skills/doctor/SKILL.md 目錄頁寫入從「列」改成「區塊」：呼叫改成 upsert CHECK 1 CHECK_{HASH}，鍵從第 4 欄的裸 HASH 改成 H2 標題，並改成備妥區塊檔而不是列檔
skills/setup/SKILL.md 收尾覆寫體檢頁後更新目錄頁的那一段同步成同一組呼叫與同一個鍵，兩支技能對同一頁的寫法不分岔
references/behaviors.md doctor 與 setup 的關鍵步驟、外部呼叫、完成條件、可驗證跡象同步成條列式目錄頁，可驗證跡象改成驗 H2 區塊與欄位條列、整頁不留表格
README.md doctor 與 setup 兩節的敘述同步成條列式目錄頁與新的 upsert 呼叫形式
plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 目錄頁格式是破壞性的行為改變，三份 manifest 的版本號一起推進，讓版本守門看得出機器上的副本是舊的

設計重點

  • 鍵從第 4 欄的裸 HASH 改成 H2 標題文字，也就是體檢頁頁名 CHECK_{HASH}。頁名只由 {短主機名}/{登入帳號} 決定，站台、存取庫與頁名編碼怎麼變都不影響它，比對永遠找得到同一台機器既有的那個區塊。標題不放連結、不放網址、不加日期、不加別的前後綴。
  • {key-col} 填 1。這個參數指舊表格裡持有內容頁連結那一欄的欄位序號，CHECK_CONTENTS 的舊表格第 1 欄就是 [CHECK_{HASH}](網址)，自動轉檔時取那一格的連結產生 H2 標題。原本沿用第 4 欄會在轉檔時取到裸 HASH，標題跟鍵 CHECK_{HASH} 對不上，既有那一筆被當成新的附加上去，同一台機器在頁面上變成兩個區塊，舊區塊從此再也更新不到。
  • 這個參數只在頁面還是舊表格、需要自動轉檔時才用得到，頁面已經是條列格式就完全忽略它；範本引言寫明它的來歷與填錯的後果，避免下一個人當成可有可無的欄位。
  • 第四個參數從「列檔」改成「區塊檔」：內容是 ## CHECK_{HASH} 那一行、一個空行，再接體檢頁、主機、帳號、HASH、必要項缺漏、設定錯誤、最後體檢七條欄位 bullet。HASH 從表格欄位變成區塊裡的一條，值本身不變。
  • 「體檢頁」那一條的連結留給人點，仍走 gitea.sh wiki-url 印出的絕對網址並先過 link-check.sh，但它不再兼任鍵，連結壞掉不會再連帶讓比對失準。
  • 只動範本與技能敘述，不新增任何腳本。讀回整頁、比對鍵、整塊換掉或附加、整頁寫回這一串邏輯全部留在 gitea/tools/wiki-contents.sh 一處。

測試結果

  • 未跑自動化測試：本次變更全部是 markdown 敘述與範本，沒有動到 tools/ 底下任何腳本，這個存取庫的既有腳本行為一字未變。
  • git status --porcelain 在提交後無輸出，git log --oneline origin/develop..HEAD 只有本輪的 commit，工作區乾淨。
  • 註解掃描 jsc-hooks/hooks/comment-scope.sh sweep 在提交前執行，結束碼 0，無命中。變更檔案全是 markdown 與 json，本來就不在該規則的掃描範圍內。
  • 條列格式的實際產出行為由 gitea 那一支的離線驗證 check-contents-format.sh 負責，本存取庫沒有可獨立驗證的執行路徑。

前置 Push Request

## 摘要 - 需求描述：所有 wiki 目錄頁（`*_CONTENTS`）的呈現格式從 markdown 表格改成「大標題加條列式」——一筆紀錄一個 H2 區塊，H2 標題就是這一筆的鍵（該筆對應內容頁的實際頁名），欄位是標題底下的一層條列 `- {欄位名}：{值}`，目錄頁上不留任何 markdown 表格。本存取庫負責體檢目錄頁 `CHECK_CONTENTS` 的範本，以及 `doctor` 與 `setup` 兩支技能對它的呼叫，實際的轉檔與 upsert 邏輯全部在 `gitea/tools/wiki-contents.sh`。內容頁維持原本的圖表優先，不在這一輪的範圍。 - 計畫名稱：無 - 計畫頁：無 - 分析頁：無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `templates/check-contents.md` | 版面從七欄 markdown 表格改成一台執行環境一個 H2 區塊，標題是體檢頁頁名 `CHECK_{HASH}`，七個欄位改成 `- {欄位名}：{值}` 的一層條列；引言補上參數語意，並把「鍵用裸 `HASH`」的說法改成「鍵用頁名」 | | `skills/doctor/SKILL.md` | 目錄頁寫入從「列」改成「區塊」：呼叫改成 `upsert CHECK 1 CHECK_{HASH}`，鍵從第 4 欄的裸 `HASH` 改成 H2 標題，並改成備妥區塊檔而不是列檔 | | `skills/setup/SKILL.md` | 收尾覆寫體檢頁後更新目錄頁的那一段同步成同一組呼叫與同一個鍵，兩支技能對同一頁的寫法不分岔 | | `references/behaviors.md` | `doctor` 與 `setup` 的關鍵步驟、外部呼叫、完成條件、可驗證跡象同步成條列式目錄頁，可驗證跡象改成驗 H2 區塊與欄位條列、整頁不留表格 | | `README.md` | `doctor` 與 `setup` 兩節的敘述同步成條列式目錄頁與新的 upsert 呼叫形式 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 目錄頁格式是破壞性的行為改變，三份 manifest 的版本號一起推進，讓版本守門看得出機器上的副本是舊的 | ## 設計重點 - 鍵從第 4 欄的裸 `HASH` 改成 H2 標題文字，也就是體檢頁頁名 `CHECK_{HASH}`。頁名只由 `{短主機名}/{登入帳號}` 決定，站台、存取庫與頁名編碼怎麼變都不影響它，比對永遠找得到同一台機器既有的那個區塊。標題不放連結、不放網址、不加日期、不加別的前後綴。 - `{key-col}` 填 `1`。這個參數指舊表格裡持有內容頁連結那一欄的欄位序號，`CHECK_CONTENTS` 的舊表格第 1 欄就是 `[CHECK_{HASH}](網址)`，自動轉檔時取那一格的連結產生 H2 標題。原本沿用第 4 欄會在轉檔時取到裸 `HASH`，標題跟鍵 `CHECK_{HASH}` 對不上，既有那一筆被當成新的附加上去，同一台機器在頁面上變成兩個區塊，舊區塊從此再也更新不到。 - 這個參數只在頁面還是舊表格、需要自動轉檔時才用得到，頁面已經是條列格式就完全忽略它；範本引言寫明它的來歷與填錯的後果，避免下一個人當成可有可無的欄位。 - 第四個參數從「列檔」改成「區塊檔」：內容是 `## CHECK_{HASH}` 那一行、一個空行，再接體檢頁、主機、帳號、`HASH`、必要項缺漏、設定錯誤、最後體檢七條欄位 bullet。`HASH` 從表格欄位變成區塊裡的一條，值本身不變。 - 「體檢頁」那一條的連結留給人點，仍走 `gitea.sh wiki-url` 印出的絕對網址並先過 `link-check.sh`，但它不再兼任鍵，連結壞掉不會再連帶讓比對失準。 - 只動範本與技能敘述，不新增任何腳本。讀回整頁、比對鍵、整塊換掉或附加、整頁寫回這一串邏輯全部留在 `gitea/tools/wiki-contents.sh` 一處。 ## 測試結果 - 未跑自動化測試：本次變更全部是 markdown 敘述與範本，沒有動到 `tools/` 底下任何腳本，這個存取庫的既有腳本行為一字未變。 - `git status --porcelain` 在提交後無輸出，`git log --oneline origin/develop..HEAD` 只有本輪的 commit，工作區乾淨。 - 註解掃描 `jsc-hooks/hooks/comment-scope.sh sweep` 在提交前執行，結束碼 0，無命中。變更檔案全是 markdown 與 json，本來就不在該規則的掃描範圍內。 - 條列格式的實際產出行為由 `gitea` 那一支的離線驗證 `check-contents-format.sh` 負責，本存取庫沒有可獨立驗證的執行路徑。 ## 前置 Push Request - [plugins/gitea：wiki 目錄頁改成大標題加條列，舊表格讀到就自動轉檔](https://gitea.jsc.idv.tw/plugins/gitea/pulls/52)——必須先合。實際的轉檔與 upsert 邏輯全部在該存取庫的 `gitea/tools/wiki-contents.sh`，本存取庫只改敘述與範本。前置未合就先部署本存取庫，範本組出來的 H2 區塊會被舊版工具當成表格列附加到表格後面。
jiantw83 added 2 commits 2026-09-02 09:25:52 +00:00
feat(wiki): 體檢目錄頁改條列式版面，鍵改用體檢頁頁名 d5bc40be13 
What：`templates/check-contents.md` 從 markdown 表格改成一台執行環境一個 H2 區塊，H2 標題就是那一台的體檢頁頁名 `CHECK_{HASH}`，原本的七個欄位改成標題底下一層 `- {欄位名}：{值}` 的條列，頁上不留任何表格。`skills/doctor/SKILL.md` 與 `skills/setup/SKILL.md` 對目錄頁的呼叫從 `wiki-contents.sh upsert CHECK 4 "{HASH}"` 改成 `upsert CHECK 1 "CHECK_{HASH}"`，`references/behaviors.md` 的關鍵步驟、完成條件與可驗證跡象，以及 `README.md` 的兩段技能敘述都跟著對齊。

Why：一列七格的表格，欄位一多就要橫向捲動，讀的人得先數欄位再對照表頭才知道哪一格是什麼；一筆一個 H2 區塊、每一條自己帶欄位名，掃過去就讀得懂。版面換成區塊之後鍵也得跟著換：表格時代的鍵是第 4 欄的裸 `HASH`，區塊沒有欄位可指，唯一能當鍵的是 H2 標題。key-col 與 key 沿用舊值會讓腳本比對不中，同一台機器每體檢一次就在頁尾多附一個區塊，舊區塊從此再也更新不到，而頁面看起來完全正常，錯得無聲無息。頁名只由 `{短主機名}/{登入帳號}` 決定，`GITEA_HOST` 換掉、`JSC_WIKI_REPO_CHECK` 搬到別的存取庫、Gitea 對頁名的編碼有差都動不到它，拿它當鍵比拿任何含網址的值都穩。

How：範本頁首的寫入語意從「一列」改寫成「一個區塊」，並補上四個參數的說明。第三個參數 `<key>` 收 H2 標題文字，也就是 `CHECK_{HASH}`；第四個參數收的是區塊檔而不是列檔，內容為 `## CHECK_{HASH}` 那一行、一個空行，再照範本的欄位順序每欄一條條列，`HASH` 那一欄照樣要寫，標題是鍵不代表欄位可以省，否則下一個讀的人讀不到。第二個參數 `1` 定位成 `<key-col>`，只在頁面還留著舊表格、需要自動轉檔時才用得到，指舊表格裡持有 `[CHECK_{HASH}](網址)` 的第 1 欄，轉檔時取那一格的文字當 H2 標題，頁面已經是條列格式就忽略它。「體檢頁」那一條維持 `[{文字}]({絕對網址})` 的人用連結寫法，H2 標題本身不放連結也不放網址。兩支技能的結束碼分流一併校正：`wiki-contents.sh` 的結束碼 1 從「寫入失敗」改寫成「組不出頁面內容或寫入失敗」，頁上找不到本機那一個區塊不算這一碼，腳本會改成附加。實際的轉檔與 upsert 邏輯都在 `jsc-gitea/tools/wiki-contents.sh`，這個存取庫只改敘述與範本。

Who：屬於「wiki 目錄頁改條列式呈現」這個需求落在 jsc-cli 的部分，也就是 `CHECK_CONTENTS` 這一型目錄頁的去表格化。內容頁維持圖表優先，不在這一輪範圍。
chore(plugin 版本): 三份 manifest 升版至 0.3.1 4479a090a6 
What：`plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` 三份 manifest 的 `version` 從 `0.3.0` 升到 `0.3.1`，三份一起改、值保持一致，其餘欄位一個字都不動。

Why：版本號是 `jsc-hooks/hooks/version-guard.sh` 判斷機器上的 plugin 落後與否的唯一依據。目錄頁的版面與鍵已經換過，版本號不動的話 version-guard 會把機器上的舊版當成最新版，`jsc-cli:doctor` 不會把它列進待修項目，那台機器就繼續留著以裸 `HASH` 當鍵的舊敘述，寫出來的目錄頁跟新範本對不上。三份分別給不同 CLI 讀，只升其中一份會讓同一支 plugin 在不同 CLI 上報出不同版本，落後判斷跟著失準。

How：只改 `version` 這一個鍵，走修訂號一階。這一輪是既有頁面型別的呈現方式調整，沒有新增技能，也沒有改動任何腳本的呼叫介面，不到次版本號的幅度。三份的值刻意保持一致，version-guard 才比得出單一結論。

Who：屬於「wiki 目錄頁改條列式呈現」這個需求的發版收尾，與同一輪的敘述與範本改動配成一套。獨立成一個 commit 的理由是型別不同：這一組是 chore 而非 feat，改動的檔案與敘述那一組完全不重疊，版號要重切或回退時也不必動到行為契約。
admin merged commit 9d0e1ea3dd into develop 2026-09-02 10:00:37 +00:00
admin deleted branch feat/contents-list/main 2026-09-02 10:00:37 +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.
Depends on
#52 wiki 目錄頁改成大標題加條列，舊表格讀到就自動轉檔
plugins/gitea
Reference: plugins/cli#58