jiantw83
02bfc70f4e
兩支腳本開跑就檢查自己的執行路徑，監控頁的摘要表與最新一輪那一塊補上 「警示來源」。 兩件都是實測之後補的。用全新的 CLI 行程跑，代理人會把工具路徑解回外掛 快取那一份，不是指定的工作樹那一份。原本的對策只在技能說明書裡寫明禁 止，那是文件約束，擋不住真的走錯的那一輪。權限閘門只放行 current 那一 組確切路徑，走錯就被靜靜擋掉，那一輪不寫心跳，外面只看得到心跳過期。 另一頭，沙箱跑出來的摘要列是「警示、四項全過、待人處理 0」，讀的人看 不出警示哪來。查過不是缺陷：四項來源都讀得到，是讀到的內容有警示。摘 要表的用途本來就是一眼看出從哪一輪開始壞，少了原因那一欄就做不到。 巡檢與排程兩支腳本開跑時先比對自己是不是從 current 底下被叫起來的，不 是就往 stderr 印一行警告，點名實際路徑、應該用的路徑與理由。刻意只警告 不中止：從工作樹直接跑腳本是開發時的正當用法，中止會把那條路擋掉，真 正的失敗本來就發生在權限閘門那裡。摘要表從四欄加到五欄，最新一輪那一 塊也補一列，值取每一處設警示時收下來的短理由，多個用頓號串，沒有就寫 「無」。腳本裡每一處把判定改成警示的地方，一律改走同一支函式順手收下 理由，collect 的輸出多印一行 warn_sources。技能主文、行為清單與監控頁 範本跟著寫明這兩件事。 功能範圍是助理的一輪巡檢與系統排程安裝。
140 lines
6.8 KiB
Markdown
140 lines
6.8 KiB
Markdown
# 助理巡檢 — {主機名}/{登入帳號}
|
||
|
||
> 由 `jsc-assist` 維護。這是監控頁 `MONITOR_{HASH}`。
|
||
> 這頁固定三塊：本頁基本資料、最新一輪、近 24 輪摘要。
|
||
> 最新一輪每輪整塊換掉；摘要表一輪一列往上疊，只留 24 列；基本資料建頁時寫一次就不動。
|
||
> 完整內容只留最新一輪，頁面才讀得完；軌跡留在摘要表，看得出是從哪一輪開始壞的。
|
||
> 目錄頁 `MONITOR_CONTENTS` 只更新自己那一列，別台機器的列一個字都不動。
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[巡檢一輪] --> B[收攏四項結果]
|
||
B --> C[讀回舊頁]
|
||
C --> D[換掉最新一輪那一塊]
|
||
D --> E[本輪摘要列插到表格最上面，截到 24 列]
|
||
E --> F[整頁寫回]
|
||
F --> G[更新 MONITOR_CONTENTS 自己那一列]
|
||
G --> H[最後才寫心跳]
|
||
```
|
||
|
||
心跳排在最後一步，不能提前。心跳新鮮的意思就是「上一輪跑到這一步了」：這一輪沒寫上來，心跳就不寫，讓它自己過期。那是巡檢在空轉的唯一訊號。
|
||
|
||
## 本頁基本資料
|
||
|
||
建頁時寫一次，之後不再更動。
|
||
|
||
| 項目 | 內容 |
|
||
| --- | --- |
|
||
| 主機 | {主機名} |
|
||
| 帳號 | {登入帳號} |
|
||
| 雜湊來源 | `{主機名}/{登入帳號}` |
|
||
| 狀態檔根目錄 | `$JSC_HOME/assistant/`（`$JSC_HOME` 未設定就退回 `~/.jsc`） |
|
||
|
||
## 最新一輪
|
||
|
||
這一塊每輪整塊換掉，只留最新那一輪的完整內容。再往前的軌跡看下面的摘要表。
|
||
|
||
六個子節固定都寫；某個來源讀不到，就在那個子節寫明是哪個路徑讀不到，不要整節略過。還沒實作的子節也照寫，寫明「這一輪不做這一項」——空表格會被讀成「查過了，沒問題」。
|
||
|
||
| 項目 | 內容 |
|
||
| --- | --- |
|
||
| 巡檢時間 | {yyyy-MM-dd HH:mm} |
|
||
| 觸發方式 | {排程、事件、手動 三選一} |
|
||
| 本輪判定 | {正常、警示、異常 三選一} |
|
||
| 本輪項目 | {這一輪跑了哪幾項，成功幾項、失敗幾項} |
|
||
| 讀不到的來源 | {路徑清單，全部讀得到就寫「無」} |
|
||
| 警示來源 | {警示原因，多個用頓號串；沒有就寫「無」} |
|
||
|
||
### 心跳與閘門狀態
|
||
|
||
| 項目 | 內容 |
|
||
| --- | --- |
|
||
| 心跳 | {新鮮、過期、不存在 三選一} |
|
||
| 上次心跳 | {yyyy-MM-dd HH:mm}，距這次巡檢 {n} 秒 |
|
||
| cli | {claude、codex、copilot、antigravity、kiro 五選一} |
|
||
| session | {工作階段代號} |
|
||
| pid | {數字}。只給要找行程的人參考，不參與判定 |
|
||
|
||
這一欄讀到的是**上一輪**巡檢寫的心跳：心跳由巡檢寫，本輪那一次要等這一頁寫成之後才寫。
|
||
|
||
心跳的判準只看 `ts` 距現在有沒有超過門檻，預設 300 秒。不看 pid 存活：五支 CLI 與容器裡的行程互相看不到彼此的 pid。閘門的判定留在 hook，助理只維持心跳。心跳新鮮代表上一輪巡檢跑完了，不代表那一輪四項都成功——那要看這一塊上面的「本輪判定」。
|
||
|
||
### 技能與呼叫鏈使用統計
|
||
|
||
資料出自 `$JSC_HOME/usage/skills.jsonl` 與 `$JSC_HOME/usage/chains.jsonl`，由 `jsc-log:stats` 聚合。
|
||
|
||
| 對象 | 類別 | 本輪次數 | 累計次數 |
|
||
| --- | --- | ---: | ---: |
|
||
| {技能名或呼叫鏈} | {技能、呼叫鏈 二選一} | {n} | {n} |
|
||
|
||
### hook 執行期錯誤
|
||
|
||
資料出自 `jsc-hooks` 的 `tools/scan-hook-errors.sh` 與 `tools/scan-logs.sh`。助理只記錄與發動 `jsc-hooks:repair`，不自己改 hook。
|
||
|
||
| 發生時間 | hook | CLI | 結束碼 | 錯誤摘要 | 已寫 ERROR 頁 |
|
||
| --- | --- | --- | ---: | --- | --- |
|
||
| {yyyy-MM-dd HH:mm} | {腳本檔名} | {CLI 代號} | {n} | {一句摘要} | {ERROR_{HASH} 連結或「否」} |
|
||
|
||
### 版本落差與重啟閘門
|
||
|
||
資料出自 `version-guard.sh report` 與 `restart-gate.sh report`。
|
||
|
||
| domain | 本機版本 | 應有版本 | 判定 |
|
||
| --- | --- | --- | --- |
|
||
| {domain} | {版本字串} | {版本字串} | {相符、落後、查不到 三選一} |
|
||
|
||
| CLI | 重啟閘門 | 升起時間 |
|
||
| --- | --- | --- |
|
||
| {CLI 代號} | {已升起、未升起 二選一} | {yyyy-MM-dd HH:mm 或「-」} |
|
||
|
||
### SDLC 階段鎖與工作包鎖現況
|
||
|
||
資料出自 `$JSC_HOME/sessions/{sid}.stage` 與 `$JSC_HOME/wp/*.pr`。只讀狀態，不做判定。
|
||
|
||
| 工作階段 | 階段 | 存取庫 | 登記時間 |
|
||
| --- | --- | --- | --- |
|
||
| {工作階段代號} | {plan、analyze、implement、maintain 四選一} | {owner}/{repo} | {yyyy-MM-dd HH:mm} |
|
||
|
||
| 存取庫 | 工作包 | PR | 歸屬工作階段 |
|
||
| --- | --- | --- | --- |
|
||
| {owner}/{repo} | {WP-nn} | {PR 連結} | {工作階段代號} |
|
||
|
||
### 待辦簿到期與逾期
|
||
|
||
資料出自 `$JSC_HOME/assistant/tasks/` 底下的每一個檔案，一筆一列。
|
||
|
||
| id | 標題 | 狀態 | 下次執行 | 到期 | 連續失敗 | 標記 |
|
||
| --- | --- | --- | --- | --- | ---: | --- |
|
||
| {id} | {title} | {pending、done、paused 三選一} | {next_run} | {due 或「-」} | {fail_count} | {已連續失敗 N 次，或「-」} |
|
||
|
||
`fail_count` 大於 0 的列，標記欄一律寫「已連續失敗 N 次」，`N` 照檔案原值抄。待辦簿的項目失敗不會自動暫停，會每輪重試；沒標出來，一個壞掉的項目會一直重試而沒人知道。
|
||
|
||
### 待人處理
|
||
|
||
助理只提醒，不代為執行。這一節列的是本輪要人接手的項目。
|
||
|
||
| 項目 | 來源子節 | 建議入口 |
|
||
| --- | --- | --- |
|
||
| {一句話講完要處理什麼} | {上面六個子節之一} | {技能名或指令} |
|
||
|
||
## 近 24 輪摘要
|
||
|
||
一輪一列，最新的在最上面，超過 24 列就丟掉最舊的那一列。
|
||
|
||
| 巡檢時間 | 本輪判定 | 四項成敗 | 待人處理 | 警示來源 |
|
||
| --- | --- | --- | ---: | --- |
|
||
| {yyyy-MM-dd HH:mm} | {正常、警示、異常 三選一} | {成功項數}/{總項數} | {待人處理筆數} | {警示原因，多個用頓號串；沒有就寫「無」} |
|
||
|
||
「警示來源」那一欄不能省。四項讀取全部成功、但讀到的內容有警示時，判定是警示而成敗欄是 4/4，沒有這一欄的話，看的人不知道警示哪來。理由要短，一眼讀完，像「心跳過期」「版本查詢失敗」「重啟閘門未清」「上一輪逾時被接手」。
|
||
|
||
## 寫入規則
|
||
|
||
- 讀不到舊頁就中止，不重組，也不寫入。舊頁讀不回來就沒有摘要表可以接下去。
|
||
- 本頁基本資料原樣保留，一個字都不改。
|
||
- 最新一輪整塊換掉，只留這一輪的完整內容。
|
||
- 本輪的摘要列插到摘要表最上面，舊的列往下移，超過 24 列就丟掉最舊的那一列。
|
||
- 三塊重組成一整頁再整頁寫回。除了這三塊，頁上沒有別的東西。
|
||
- 舊格式的頁（一輪一節疊起來的那種）第一次重組時，基本資料留著，那些節收掉，摘要表從本輪這一列開始，並在回報裡說明。
|
||
- 整頁寫成之後，才回頭更新 `MONITOR_CONTENTS` 自己那一列，別台機器的列一個字都不動。
|
||
- 兩頁都寫成之後，才寫這一輪的心跳。任一頁沒寫成就不寫心跳，讓它過期。
|