jiantw83
3dac1475df
現行紀錄只記「被叫用」，沒有成敗也沒有結束碼。跑完整輪的技能與開場就 中止的技能，在紀錄裡長得一模一樣。 start 由技能用量 hook 順手發，不必改技能文件。end 只能由技能自己在收尾 步驟寫——hook 接在技能工具呼叫上，而實際工作發生在之後的模型輪次，它在 原理上看不到成敗。有 start 沒有配對的 end，就是那一輪中止了。 status 五選一，每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜 跳過，回報失敗一律不改變技能自己的結論。
69 lines
7.0 KiB
Markdown
69 lines
7.0 KiB
Markdown
# 助理巡檢目錄
|
|
|
|
> 由 `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` 印出的那一個，不自己組路徑。wiki 自己那種雙中括號寫法只在同一個 wiki 裡解得開，寫錯不會報錯，畫面上看起來像正常文字或死連結。
|
|
>
|
|
> 寫入前驗證：這一列要放進去的連結，先交給 `jsc-gitea/tools/link-check.sh`，結束碼 0 才寫。有 DEAD 就不寫這一列，把連不到的那幾筆回報出去。驗證走 API，不看網頁狀態碼——私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把還在的頁判成死連結。
|
|
>
|
|
> 比對鍵：第 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 的筆數 | 待辦簿的項目失敗不會自動暫停，每輪都重試。這一欄讓壞掉的項目在目錄頁就現形 |
|
|
|
|
### 為什麼沒有「本輪非 ok 事件數」這一欄
|
|
|
|
執行狀態事件的筆數只放在監控頁的「執行狀態事件」那一節，這一頁不加欄。兩個理由：
|
|
|
|
- **這一頁的欄不是自己一台機器說了算。** 每一列是一台機器，欄位卻是共用的：表頭跟著建頁的那一台走，之後每一台只更新自己那一列。新加一欄，只有跑到新版的機器會寫出多一格的列，其餘機器的列還是舊的格數，表頭也還是舊的——同一張表混著兩種格數，多出來的那一格對不到任何欄名。目錄頁沒有整頁改寫的路可以走：整頁覆蓋等於刪掉別台機器的紀錄。
|
|
- **這個數字離開監控頁就會被讀錯。** 它算的是「上一次排空之後到這一輪之間」的事件，視窗長度隨巡檢週期與上一輪的成敗變動。放在監控頁上，同一節裡就有事件總數、未配對的 `start` 與明細表可以對照；抽一個數字放到目錄頁，0 會被讀成「這台機器很健康」，但它同樣可能只是那一段時間沒有任何技能跑過。
|
|
|
|
要判斷一台機器有沒有問題，這一頁上的「心跳」與「最後巡檢」就夠帶人往下翻；細節一律回監控頁看。
|
|
|
|
## 寫入規則
|
|
|
|
這一頁是共用目錄，別台機器的列一律原樣保留。寫入一律用 `jsc-gitea/tools/wiki-contents.sh upsert`，不手工改頁。
|
|
|
|
```mermaid
|
|
flowchart TD
|
|
A[監控頁已經寫成] --> B[gitea.sh wiki-url 取監控頁絕對網址]
|
|
B --> C[組出本機那一列，網址換掉佔位]
|
|
C --> V{link-check.sh 驗這一列的連結}
|
|
V -- 結束碼 0 --> D[wiki-contents.sh upsert MONITOR 第 2 欄的裸 HASH 當鍵]
|
|
V -- 有 DEAD 或其他非 0 --> W[不寫這一列，回報連不到的那幾筆]
|
|
D --> E{舊頁讀得回來}
|
|
E -- 是 --> F{HASH 欄對得上}
|
|
F -- 是 --> G[取代那一列]
|
|
F -- 否 --> H[附加一列]
|
|
E -- 頁不存在 --> I[用範本建頁，再附加一列]
|
|
E -- 金鑰失效或 API 失敗 --> J[中止：不建頁、不寫入]
|
|
G --> K[整頁寫回，別台機器的列原樣送回]
|
|
H --> K
|
|
I --> K
|
|
```
|
|
|
|
- 連結一律 `[{文字}]({絕對網址})`，網址取 `gitea.sh wiki-url`。這一列要放進去的每一個連結，寫入前先過 `link-check.sh`，結束碼 0 才寫；結束碼 1 就不寫這一列，把 DEAD 那幾筆回報出去。結束碼 3 是 `GITEA_HOST` 沒設定，補設定再驗，不准跳過驗證；結束碼 7 是金鑰失效，停下來回報金鑰問題，不要當成死連結——金鑰過期時私有存取庫的回應和「頁不存在」分不出來，混為一談會把還在的頁整批判死。
|
|
- 存取庫走 `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 列丟最舊的。兩者不要混用。
|