assist/templates/monitor-contents.md

助理巡檢目錄

由 jsc-assist 維護。這是目錄頁 MONITOR_CONTENTS，落在 JSC_WIKI_REPO_CONTENTS 解出的專用存取庫，和監控頁不同庫。 一列代表一台機器。雜湊來源是 {主機名}/{登入帳號}，主機名取短的那一段，所以一台機器一列、一頁，換一支 CLI 不另開列。 MONITOR_{HASH} 的 {HASH} 執行 jsc-gitea/tools/hash-id {主機名}/{登入帳號} 取得，原樣採用它印出的完整 40 碼大寫十六進位，不截短、不加前綴（共用 wiki hash 規則，演算法見 jsc-meta 的 references/guidelines.md）。

連結寫法：監控頁那一欄放 jsc-gitea/tools/gitea.sh wiki-url 印出的絕對網址，不用 [[...]]。兩頁分屬不同存取庫，[[...]] 連不過去，畫面上還看不出壞掉。

比對鍵：第 2 欄的裸 HASH，純文字，不帶連結、不帶網址。連結那一欄是給人看的，不當鍵。

監控頁	HASH	主機	帳號	心跳	最後巡檢	待辦筆數	連續失敗項
[MONITOR_{HASH}]({wiki-url 印出的絕對網址})	{HASH}	{主機名}	{登入帳號}	{新鮮、過期、不存在 三選一}	{yyyy-MM-dd HH:mm}	{n}	{n}

欄位說明

欄位	內容	為什麼留這一欄
監控頁	指向 MONITOR_{HASH} 的絕對網址連結，給人點的，不當比對鍵	少了連結就要人自己算雜湊才翻得到內容頁；跨存取庫只有絕對網址連得過去
HASH	hash-id 印出的完整 40 碼大寫十六進位，純文字，不加連結、不加網址，也是 upsert 的比對鍵	這一格只跟 {主機名}/{登入帳號} 有關，換主機位址、換存取庫、換一種網址編碼都不會變。拿含網址的連結當鍵才會對不上，然後同一台機器每輪多附一列
主機	這台機器的短主機名，與雜湊第一段相同	一眼看出這一列是哪一台機器
帳號	助理執行時的登入帳號，與雜湊第二段相同	同一台機器換帳號就是另一個巡檢對象，雜湊也會不同
心跳	巡檢當下（本輪寫入前）的心跳判定，判準只看 ts 距現在有沒有超過門檻，預設 300 秒	一眼看出這台機器上一輪巡檢有沒有跑完，不必逐頁翻
最後巡檢	該頁最新一輪的時間戳	心跳由巡檢寫，兩欄理當一致；差很多就代表有一輪寫了心跳卻沒寫頁，那是缺陷
待辦筆數	待辦簿現有筆數	心跳新鮮而筆數為 0，代表助理空轉，沒有東西可跑
連續失敗項	待辦簿裡 fail_count 大於 0 的筆數	待辦簿的項目失敗不會自動暫停，每輪都重試。這一欄讓壞掉的項目在目錄頁就現形

寫入規則

這一頁是共用目錄，別台機器的列一律原樣保留。寫入一律用 jsc-gitea/tools/wiki-contents.sh upsert，不手工改頁。

flowchart TD
  A[監控頁已經寫成] --> B[gitea.sh wiki-url 取監控頁絕對網址]
  B --> C[組出本機那一列，網址換掉佔位]
  C --> D[wiki-contents.sh upsert MONITOR 第 2 欄的裸 HASH 當鍵]
  D --> E{舊頁讀得回來}
  E -- 是 --> F{HASH 欄對得上}
  F -- 是 --> G[取代那一列]
  F -- 否 --> H[附加一列]
  E -- 頁不存在 --> I[用範本建頁，再附加一列]
  E -- 金鑰失效或 API 失敗 --> J[中止：不建頁、不寫入]
  G --> K[整頁寫回，別台機器的列原樣送回]
  H --> K
  I --> K

• 存取庫走 gitea.sh wiki-repo CONTENTS：先 JSC_WIKI_REPO_CONTENTS，再 JSC_WIKI_REPO，都沒設就結束碼 3，不退回監控頁那一支變數。
• 比對鍵是第 2 欄的裸 HASH，原樣比對整格文字。鍵取 collect 印的 hash=，自己重打會對不上，結果是同一台機器多出第二列。
• 第一欄的連結不當鍵：那一格含 GITEA_HOST 與頁名的網址編碼，主機位址改掉、JSC_WIKI_REPO_MONITOR 換了存取庫、或 Gitea 的網址編碼有差，整格文字就變了，鍵跟著對不上。這一頁每 15 分鐘寫一次，對不上的那一刻起每輪多附一列，舊列再也不會更新。
• 找得到相同的 HASH 就更新那一列，找不到才附加一列。
• 只動自己那一列，別台機器的列一個字都不改。禁止整頁覆蓋——整頁覆蓋等於刪掉別台機器的紀錄。
• 只有「頁不存在」才准用範本建頁。金鑰失效或 API 失敗一律中止：那兩種情況舊內容是未知的，拿範本蓋上去就是把活著的紀錄整份刪掉。
• 內容頁 MONITOR_{HASH} 的寫入語意不同：那頁固定三塊，最新一輪整塊換掉，摘要表一輪一列、最新的在最上面、超過 24 列丟最舊的。兩者不要混用。