feat(wiki): 體檢目錄頁改條列式版面,鍵改用體檢頁頁名

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` 這一型目錄頁的去表格化。內容頁維持圖表優先,不在這一輪範圍。
This commit is contained in:
2026-09-02 17:25:37 +08:00
parent 8444307534
commit d5bc40be13
5 changed files with 56 additions and 40 deletions
+2 -2
View File
@@ -54,11 +54,11 @@ Marketplace 統一為 `jsc`(https://gitea.jsc.idv.tw/plugins/meta.git),安
### `doctor`
一次體檢執行環境,只讀不改。四項檢查**同時啟動,各一個 sub agent**:技能版本(`jsc-hooks/hooks/version-guard.sh report`)、Hook 接線(`jsc-hooks/tools/wire-cli.sh status`,唯讀子命令)、設定現況(`tools/scan-config.sh scan all` 比對 `tools/config-spec.tsv`,一次掃完全域與專案兩個範圍)、漏登錄變數(`scan-config.sh orphans`)。唯讀契約下放程式層:呼叫 `wire-cli.sh` 一律帶 `JSC_READONLY=1`,打錯子命令也不會改到機器。每項各出一張表,專案那張一定寫出掃的是哪個目錄;待修項目由 `tools/build-todo.sh` 合併三份輸出並排序。整份結果寫進 wiki `CHECK_{HASH}`,`HASH` 取 `{短主機名}/{登入帳號}`,兩個值都由程式取,主機名一律切掉網域,只保留最新一次。目錄頁 `CHECK_CONTENTS` 住另一個庫(`JSC_WIKI_REPO_CONTENTS`),改由 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 4` 只寫本機那一列。鍵是第 4 欄的裸 `HASH`,不是第 1 欄的連結:網址會隨站台、存取庫與頁名編碼改變,拿網址當鍵就比不中,同一台機器每體檢一次就多附一列。第 1 欄的連結給人點,填絕對網址。修復交給 `/jsc-cli:setup`,體檢本身不動任何設定。
一次體檢執行環境,只讀不改。四項檢查**同時啟動,各一個 sub agent**:技能版本(`jsc-hooks/hooks/version-guard.sh report`)、Hook 接線(`jsc-hooks/tools/wire-cli.sh status`,唯讀子命令)、設定現況(`tools/scan-config.sh scan all` 比對 `tools/config-spec.tsv`,一次掃完全域與專案兩個範圍)、漏登錄變數(`scan-config.sh orphans`)。唯讀契約下放程式層:呼叫 `wire-cli.sh` 一律帶 `JSC_READONLY=1`,打錯子命令也不會改到機器。每項各出一張表,專案那張一定寫出掃的是哪個目錄;待修項目由 `tools/build-todo.sh` 合併三份輸出並排序。整份結果寫進 wiki `CHECK_{HASH}`,`HASH` 取 `{短主機名}/{登入帳號}`,兩個值都由程式取,主機名一律切掉網域,只保留最新一次。目錄頁 `CHECK_CONTENTS` 住另一個庫(`JSC_WIKI_REPO_CONTENTS`),版面是 H1 加 `>` 引言,再一台機器一個 H2 區塊,頁上沒有 markdown 表格;改由 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 CHECK_{HASH}` 只寫本機那一個區塊,欄位是 `- {欄位名}:{值}` 的條列。鍵是 H2 標題,也就是體檢頁頁名 `CHECK_{HASH}`,不是任何含網址的值:網址會隨站台、存取庫與頁名編碼改變,頁名只由主機加帳號決定,拿網址當鍵就比不中,同一台機器每體檢一次就多附一個區塊。第二個參數 `1` 是 `<key-col>`,只在頁面還是舊表格、需要自動轉檔時用得到,指舊表格裡持有 `[CHECK_{HASH}](網址)` 的第 1 欄。「體檢頁」那一條的連結給人點,填絕對網址。修復交給 `/jsc-cli:setup`,體檢本身不動任何設定。
### `setup`
修復 `/jsc-cli:doctor` 找出的問題,一次一項,逐項確認才動手。待修清單優先讀 wiki `CHECK_{HASH}`,沒有頁面就當場重掃:**三支檢查腳本併行跑**,再用 `tools/build-todo.sh` 合併成同一張表。依修法分流:`auto` 用 `tools/apply-config.sh` 直接寫、`ask` 先用決策樹問到值再寫、`manual` 印出步驟交給操作者。複合修復交回原主:版本落後找 `/jsc-cli:deploy`(連同已確認的模式與版本報告一起傳過去,不讓它重問重查)、hook 未接線找 `/jsc-hooks:hooks-install`、缺 `model-tags.tsv` 找 `/jsc-cli:models`。逐項確認維持循序,**寫完的重驗併行**;環境變數類只驗「rc 段落裡確實有那一行」,環境層面交給下一次 `/jsc-cli:doctor`。最後覆寫體檢頁 `CHECK_{HASH}`,並用 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 4` 以裸 `HASH` 當鍵更新目錄頁 `CHECK_CONTENTS` 的本機那一列,兩頁分屬不同存取庫。
修復 `/jsc-cli:doctor` 找出的問題,一次一項,逐項確認才動手。待修清單優先讀 wiki `CHECK_{HASH}`,沒有頁面就當場重掃:**三支檢查腳本併行跑**,再用 `tools/build-todo.sh` 合併成同一張表。依修法分流:`auto` 用 `tools/apply-config.sh` 直接寫、`ask` 先用決策樹問到值再寫、`manual` 印出步驟交給操作者。複合修復交回原主:版本落後找 `/jsc-cli:deploy`(連同已確認的模式與版本報告一起傳過去,不讓它重問重查)、hook 未接線找 `/jsc-hooks:hooks-install`、缺 `model-tags.tsv` 找 `/jsc-cli:models`。逐項確認維持循序,**寫完的重驗併行**;環境變數類只驗「rc 段落裡確實有那一行」,環境層面交給下一次 `/jsc-cli:doctor`。最後覆寫體檢頁 `CHECK_{HASH}`,並用 `jsc-gitea/tools/wiki-contents.sh upsert CHECK 1 CHECK_{HASH}` 以 H2 標題(也就是體檢頁頁名)當鍵,更新目錄頁 `CHECK_CONTENTS` 的本機那一個區塊,兩頁分屬不同存取庫。
<!-- JSC-SKILLS:END -->