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:
@@ -27,10 +27,10 @@
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 裝完或更新完技能組、技能因設定或接線問題失敗、機器要交接前用。要動手修不用這支,那是 jsc-cli:setup |
|
||||
| 關鍵步驟 | 同時開四個 sub agent 收版本、hook 接線、設定與未登錄變數,每個 sub agent 回傳原始輸出行、把四份輸出各存成檔、依 templates/check-page.md 印出五個區塊並寫明掃描的專案目錄、用 tools/build-todo.sh 把三份輸出合成待修項目表、用程式取短主機名與登入帳號(主機名切掉第一個點之後的網域)交給 hash-id 算出 HASH、用 wiki-repo CHECK 解出的存取庫透過 jsc-gitea:wiki 整頁覆寫 CHECK_{HASH}、寫完再用 wiki-url 取該頁絕對網址、把要寫進兩頁的每個連結交給 jsc-gitea/tools/link-check.sh 驗證且只有結束碼 0 才往下寫、第 1 欄的連結寫成 `[CHECK_{HASH}]({絕對網址})`、用 wiki-contents.sh upsert CHECK 4 以第 4 欄的裸 HASH 當鍵把本機那一列寫進 CONTENTS 存取庫的 CHECK_CONTENTS、報出四項計數並視情況建議 /jsc-cli:setup,最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-cli:doctor 寫下這一輪的結果。這一筆是這支技能唯一的寫入動作,記的是查到什麼,不動設定、不動接線、不動版本,唯讀合約照樣成立;走每一條出口都要寫。status 五選一,四項檢查都有結論、五個區塊與待修項目表都在畫面上、兩頁都寫成是 ok,任何一項報成無法驗證、離線讓 Gitea 相關列變成 skipped、或 wiki-repo 回 3 而略過寫頁是 degraded——唯讀技能讀不到來源就是這一種,金鑰失效回 7 或其他 API 失敗回 8 讓紀錄寫不成是 failed,使用者在寫頁之前喊停是 aborted。blocked 這支用不到:沒 CLI、沒登錄檔、沒 wiki 存放庫的機器一樣查得出四項發現,報成 blocked 會把做完的一輪講成沒做事。detail 只放四項計數 |
|
||||
| 關鍵步驟 | 同時開四個 sub agent 收版本、hook 接線、設定與未登錄變數,每個 sub agent 回傳原始輸出行、把四份輸出各存成檔、依 templates/check-page.md 印出五個區塊並寫明掃描的專案目錄、用 tools/build-todo.sh 把三份輸出合成待修項目表、用程式取短主機名與登入帳號(主機名切掉第一個點之後的網域)交給 hash-id 算出 HASH、用 wiki-repo CHECK 解出的存取庫透過 jsc-gitea:wiki 整頁覆寫 CHECK_{HASH}、寫完再用 wiki-url 取該頁絕對網址、把要寫進兩頁的每個連結交給 jsc-gitea/tools/link-check.sh 驗證且只有結束碼 0 才往下寫、「體檢頁」那一條的連結寫成 `[CHECK_{HASH}]({絕對網址})`、用 wiki-contents.sh upsert CHECK 1 CHECK_{HASH} 以 H2 標題也就是體檢頁頁名當鍵,把本機那一個區塊寫進 CONTENTS 存取庫的 CHECK_CONTENTS,區塊檔是 `## CHECK_{HASH}` 那一行、一個空行,再照 templates/check-contents.md 的欄位順序每欄一條 `- {欄位名}:{值}`、報出四項計數並視情況建議 /jsc-cli:setup,最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-cli:doctor 寫下這一輪的結果。這一筆是這支技能唯一的寫入動作,記的是查到什麼,不動設定、不動接線、不動版本,唯讀合約照樣成立;走每一條出口都要寫。status 五選一,四項檢查都有結論、五個區塊與待修項目表都在畫面上、兩頁都寫成是 ok,任何一項報成無法驗證、離線讓 Gitea 相關列變成 skipped、或 wiki-repo 回 3 而略過寫頁是 degraded——唯讀技能讀不到來源就是這一種,金鑰失效回 7 或其他 API 失敗回 8 讓紀錄寫不成是 failed,使用者在寫頁之前喊停是 aborted。blocked 這支用不到:沒 CLI、沒登錄檔、沒 wiki 存放庫的機器一樣查得出四項發現,報成 blocked 會把做完的一輪講成沒做事。detail 只放四項計數 |
|
||||
| 外部呼叫 | jsc-hooks/hooks/version-guard.sh report、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh status(一律帶 JSC_READONLY=1)、jsc-cli/tools/scan-config.sh 的 scan all 與 orphans、jsc-cli/tools/build-todo.sh、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/wiki-contents.sh upsert、jsc-hooks/tools/report-status.sh skill-end、jsc-gitea:wiki |
|
||||
| 完成條件 | 四項檢查各有結論,或明寫無法驗證與原因;五個區塊與待修項目表都在畫面上;每個要寫進頁面的連結都經 link-check.sh 驗過,結束碼 0 才寫,1 就兩頁都不寫並列出 DEAD 那幾筆,3 把 GITEA_HOST 排進待修項目最前面,7 停下來回報金鑰問題而不判成死連結;連結一律寫成文字加絕對網址的形式;兩頁各自寫成功,或寫入略過連同結束碼一起回報,wiki-contents.sh 宣告的 0、1、2、3、4、7、8 每一碼都有分流,建不建新頁的判斷留在腳本裡,技能不自己建;必要項缺漏、設定錯誤、CLI 未接線、domain 落後四項計數都講出來。這一輪還要留下一筆 skill-end 事件,或是腳本不在而略過,兩者都算收好;略過不影響這支技能的結束碼 |
|
||||
| 可驗證跡象 | wiki 的 CHECK_{HASH} 頁(雜湊來源是 {短主機名}/{登入帳號})被整頁覆寫成這次的結果;另一個存取庫的 CHECK_CONTENTS 多出本機那一列,或該列的缺漏數與最後體檢時間被更新;第 1 欄是 `[CHECK_{HASH}]({絕對網址})` 這種文字加連結的寫法,點下去連得到體檢頁,頁面上找不到同 wiki 的雙括號連結;第 4 欄是裸 HASH,也就是比對用的鍵,同一台機器重跑幾次都只有這一列,別台機器的列一個位元組都沒變;連結驗不過的那一輪,兩頁都維持上一輪的內容。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件,name 是 jsc-cli:doctor,status 與 exit 就是這一輪的結果,那也是這支技能唯一寫得出來的檔案痕跡。機器本身的設定、接線與版本都不動:這支技能不寫任何設定 |
|
||||
| 完成條件 | 四項檢查各有結論,或明寫無法驗證與原因;五個區塊與待修項目表都在畫面上;每個要寫進頁面的連結都經 link-check.sh 驗過,結束碼 0 才寫,1 就兩頁都不寫並列出 DEAD 那幾筆,3 把 GITEA_HOST 排進待修項目最前面,7 停下來回報金鑰問題而不判成死連結;連結一律寫成文字加絕對網址的形式,H2 標題本身不放連結;兩頁各自寫成功,或寫入略過連同結束碼一起回報,wiki-contents.sh 宣告的 0、1、2、3、4、7、8 每一碼都有分流,結束碼 1 是組不出頁面內容或寫入失敗,頁上找不到本機那一個區塊不算錯、腳本改成附加,建不建新頁的判斷留在腳本裡,技能不自己建;必要項缺漏、設定錯誤、CLI 未接線、domain 落後四項計數都講出來。這一輪還要留下一筆 skill-end 事件,或是腳本不在而略過,兩者都算收好;略過不影響這支技能的結束碼 |
|
||||
| 可驗證跡象 | wiki 的 CHECK_{HASH} 頁(雜湊來源是 {短主機名}/{登入帳號})被整頁覆寫成這次的結果;另一個存取庫的 CHECK_CONTENTS 多出本機那一個 H2 區塊,或該區塊的缺漏數與最後體檢時間被更新;區塊標題是 `## CHECK_{HASH}`,也就是比對用的鍵,標題上沒有連結也沒有網址,「體檢頁」那一條是 `[CHECK_{HASH}]({絕對網址})` 這種文字加連結的寫法,點下去連得到體檢頁,頁面上找不到同 wiki 的雙括號連結;欄位一律是 `- {欄位名}:{值}` 的條列,頁上沒有 markdown 表格,同一台機器重跑幾次都只有這一個區塊,別台機器的區塊一個位元組都沒變;連結驗不過的那一輪,兩頁都維持上一輪的內容。$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件,name 是 jsc-cli:doctor,status 與 exit 就是這一輪的結果,那也是這支技能唯一寫得出來的檔案痕跡。機器本身的設定、接線與版本都不動:這支技能不寫任何設定 |
|
||||
|
||||
## models
|
||||
|
||||
@@ -47,7 +47,7 @@
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | doctor 報出待修項目、要實際動手修這台機器時用。只想做唯讀體檢不用這支,那是 jsc-cli:doctor |
|
||||
| 關鍵步驟 | 用程式取短主機名與登入帳號算出 HASH,從 wiki-repo CHECK 解出的存取庫讀 CHECK_{HASH} 的待修項目表,讀不到就以 sub agent 同時重跑設定、接線、版本三個檢查器再用 build-todo.sh 合併、依 jsc-ask 決策樹逐項循序確認、依 fix 欄分流(auto 與 ask 走 apply-config.sh 的 set 或 mkdir、manual 印出步驟交給操作者、domain 落後轉呼叫 jsc-cli:deploy 並附上手上的版本報告、hook 未接線轉呼叫 jsc-hooks:hooks-install、缺 model-tags.tsv 轉呼叫 jsc-cli:models)、同時重驗每個已套用項目、重寫 CHECK_{HASH}、再用 wiki-url 取它的絕對網址、把要寫進兩頁的每個連結交給 jsc-gitea/tools/link-check.sh 驗證且只有結束碼 0 才往下寫、第 1 欄的連結寫成 `[CHECK_{HASH}]({絕對網址})`、以 wiki-contents.sh upsert CHECK 4 用第 4 欄的裸 HASH 當鍵更新 CONTENTS 存取庫的 CHECK_CONTENTS、報出已修、略過、轉呼叫、未修好四項計數,最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-cli:setup 寫下這一輪的結果。收尾那一筆走每一條出口,連停在讀不到待修項目那一條也要寫;status 五選一,每一項都修好也重驗過、沒有略過、兩頁都寫成是 ok,環境不允許寫入、apply-config.sh 每一項都回 4 而一個 rc 檔都沒動到是 blocked,已套用的項目重驗仍失敗、apply-config.sh 回 2 是這支技能自己下錯命令、或金鑰失效回 7 與其他 API 失敗回 8 讓紀錄改寫不成是 failed,使用者否決某一項而那一項記成略過、或轉呼叫出去的修正沒收尾是 degraded,使用者在逐項確認到一半喊停、剩下的項目沒問到是 aborted。detail 只放四項計數,不放使用者輸入的值 |
|
||||
| 關鍵步驟 | 用程式取短主機名與登入帳號算出 HASH,從 wiki-repo CHECK 解出的存取庫讀 CHECK_{HASH} 的待修項目表,讀不到就以 sub agent 同時重跑設定、接線、版本三個檢查器再用 build-todo.sh 合併、依 jsc-ask 決策樹逐項循序確認、依 fix 欄分流(auto 與 ask 走 apply-config.sh 的 set 或 mkdir、manual 印出步驟交給操作者、domain 落後轉呼叫 jsc-cli:deploy 並附上手上的版本報告、hook 未接線轉呼叫 jsc-hooks:hooks-install、缺 model-tags.tsv 轉呼叫 jsc-cli:models)、同時重驗每個已套用項目、重寫 CHECK_{HASH}、再用 wiki-url 取它的絕對網址、把要寫進兩頁的每個連結交給 jsc-gitea/tools/link-check.sh 驗證且只有結束碼 0 才往下寫、「體檢頁」那一條的連結寫成 `[CHECK_{HASH}]({絕對網址})`、以 wiki-contents.sh upsert CHECK 1 CHECK_{HASH} 用 H2 標題也就是體檢頁頁名當鍵,更新 CONTENTS 存取庫的 CHECK_CONTENTS 上本機那一個區塊,區塊檔是 `## CHECK_{HASH}` 那一行、一個空行,再照 templates/check-contents.md 的欄位順序每欄一條 `- {欄位名}:{值}`、報出已修、略過、轉呼叫、未修好四項計數,最後呼叫 jsc-hooks/tools/report-status.sh skill-end jsc-cli:setup 寫下這一輪的結果。收尾那一筆走每一條出口,連停在讀不到待修項目那一條也要寫;status 五選一,每一項都修好也重驗過、沒有略過、兩頁都寫成是 ok,環境不允許寫入、apply-config.sh 每一項都回 4 而一個 rc 檔都沒動到是 blocked,已套用的項目重驗仍失敗、apply-config.sh 回 2 是這支技能自己下錯命令、或金鑰失效回 7 與其他 API 失敗回 8 讓紀錄改寫不成是 failed,使用者否決某一項而那一項記成略過、或轉呼叫出去的修正沒收尾是 degraded,使用者在逐項確認到一半喊停、剩下的項目沒問到是 aborted。detail 只放四項計數,不放使用者輸入的值 |
|
||||
| 外部呼叫 | jsc-cli/tools/scan-config.sh、jsc-cli/tools/detect-clis.sh、jsc-hooks/tools/wire-cli.sh status(一律帶 JSC_READONLY=1)、jsc-hooks/hooks/version-guard.sh report、jsc-cli/tools/build-todo.sh、jsc-cli/tools/apply-config.sh 的 set、mkdir 與 show、jsc-gitea/tools/gitea.sh 的 wiki-repo、hash-id 與 wiki-url、jsc-gitea/tools/link-check.sh、jsc-gitea/tools/wiki-contents.sh upsert、jsc-hooks/tools/report-status.sh skill-end、jsc-ask:ask、jsc-gitea:wiki、jsc-cli:deploy、jsc-hooks:hooks-install、jsc-cli:models |
|
||||
| 完成條件 | 每一項都有已修、略過、轉呼叫或未修好的結果;每個已套用項目都由自己那一列指定的檢查器重驗過;每個寫進去的環境變數都附上 export 那一行;每個要寫進頁面的連結都經 link-check.sh 驗過,結束碼 0 才寫,1 就兩頁都不寫並列出 DEAD 那幾筆,3 回報 GITEA_HOST 仍未修好,7 停下來回報金鑰問題而不判成死連結;連結一律寫成文字加絕對網址的形式;兩頁各自寫好或略過都有回報,wiki-contents.sh 宣告的 0、1、2、3、4、7、8 每一碼都有分流,建不建新頁的判斷留在腳本裡,技能不自己建;四項計數都講出來。這一輪還要留下一筆 skill-end 事件,或是腳本不在而略過,兩者都算收好;略過不影響這支技能的結束碼 |
|
||||
| 可驗證跡象 | 各 shell rc 檔的 `# jsc-config` 區塊被改寫,改寫前的備份落在 $JSC_HOME/backup/config/{時間戳}/;auto 路線建立的目錄實際出現在磁碟上;wiki CHECK_{HASH} 被改寫成修完後的狀態,另一個存取庫的 CHECK_CONTENTS 只有本機那一列跟著更新,第 1 欄是 `[CHECK_{HASH}]({絕對網址})` 這種文字加連結的寫法、點下去連得到體檢頁,頁面上找不到同 wiki 的雙括號連結,第 4 欄是當鍵用的裸 HASH;連結驗不過的那一輪,兩頁都維持上一輪的內容;轉呼叫出去的項目留下各自技能的跡象,也就是 deploy 的重啟狀態檔、hooks-install 改寫的接線設定、models 產生的 model-tags.tsv;$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件,name 是 jsc-cli:setup,status 與 exit 就是這一輪的結果 |
|
||||
| 完成條件 | 每一項都有已修、略過、轉呼叫或未修好的結果;每個已套用項目都由自己那一列指定的檢查器重驗過;每個寫進去的環境變數都附上 export 那一行;每個要寫進頁面的連結都經 link-check.sh 驗過,結束碼 0 才寫,1 就兩頁都不寫並列出 DEAD 那幾筆,3 回報 GITEA_HOST 仍未修好,7 停下來回報金鑰問題而不判成死連結;連結一律寫成文字加絕對網址的形式,H2 標題本身不放連結;兩頁各自寫好或略過都有回報,wiki-contents.sh 宣告的 0、1、2、3、4、7、8 每一碼都有分流,結束碼 1 是組不出頁面內容或寫入失敗,頁上找不到本機那一個區塊不算錯、腳本改成附加,建不建新頁的判斷留在腳本裡,技能不自己建;四項計數都講出來。這一輪還要留下一筆 skill-end 事件,或是腳本不在而略過,兩者都算收好;略過不影響這支技能的結束碼 |
|
||||
| 可驗證跡象 | 各 shell rc 檔的 `# jsc-config` 區塊被改寫,改寫前的備份落在 $JSC_HOME/backup/config/{時間戳}/;auto 路線建立的目錄實際出現在磁碟上;wiki CHECK_{HASH} 被改寫成修完後的狀態,另一個存取庫的 CHECK_CONTENTS 只有本機那一個 H2 區塊跟著更新,區塊標題是當鍵用的 `## CHECK_{HASH}`,標題上沒有連結也沒有網址,「體檢頁」那一條是 `[CHECK_{HASH}]({絕對網址})` 這種文字加連結的寫法、點下去連得到體檢頁,頁面上找不到同 wiki 的雙括號連結,欄位一律是 `- {欄位名}:{值}` 的條列、頁上沒有 markdown 表格;連結驗不過的那一輪,兩頁都維持上一輪的內容;轉呼叫出去的項目留下各自技能的跡象,也就是 deploy 的重啟狀態檔、hooks-install 改寫的接線設定、models 產生的 model-tags.tsv;$JSC_HOME/usage/events.jsonl 會多一筆 {kind:skill,phase:end} 事件,name 是 jsc-cli:setup,status 與 exit 就是這一輪的結果 |
|
||||
|
||||
Reference in New Issue
Block a user