排程器代理管理指南
在單一畫面中管理依專案（CSN）註冊的自動化執行器（gissue 排程器等背景代理）：線上/離線狀態、執行狀態與歷史記錄，以及即時日誌。
📋 概覽
排程器代理管理 顯示目前所選專案（CSN）下註冊的所有自動化代理 —— 例如 gissue 的每小時排程器、互動式 Claude Code 工作階段等。與將 giip 問題 視覺化為貓咪的 /admin/catquest 不同，本畫面是用來管理 執行自動化工作的代理本身 的維運儀表板：檢視每個代理是否存活、目前執行是否正常、以及在哪裡可以查看其日誌。
🎨 狀態顏色
每個代理會顯示兩個彼此獨立的狀態訊號——請勿混淆。
身分狀態（代理名稱旁的小圓點）
表示代理程序本身是否可連線（tSchedulerAgent.status），與單次執行無關。
| 顏色 | 狀態 | 意義 |
|---|---|---|
| 🟢 綠色 | online | 代理可連線且正常回報中 |
| 🔴 紅色 | error | 代理回報了錯誤狀態 |
| ⚪ 灰色（slate-400） | offline | 目前無法連線至代理 |
| ⚪ 淺灰色（slate-300） | unknown | 尚未回報任何狀態 |
執行狀態（Status 欄位徽章）
反映最近一次排程器 執行（run） 的狀態（currentStatus），以及 stale（停滯）偵測結果。
| 顏色 | 顯示標籤 | 條件 | 意義 |
|---|---|---|---|
| 🟢 綠色 | RUNNING | currentStatus = RUNNING 且未 stale | 正常執行中 |
| 🔴 紅色 | STALE | currentStatus = RUNNING 且 isStale = true | 標記為執行中，但心跳長時間無回應 —— 看起來像卡住/殭屍執行 |
| 🟠 橙色 | STALE | currentStatus = STALE（明確值） | 後端將此次執行本身標記為 stale |
| ⚪ 灰色 | ENDED | currentStatus = ENDED | 已結束（正常完成或受控停止） |
| ⚪ 灰色 | （原始值） | 其他情況 / 尚無執行紀錄 | 未知 / 無資料 |
在下方的執行歷史彈窗中，已完成的執行也可能以紅色的 FAILED 顯示——這是以錯誤結束的執行，與 ENDED（正常結束）或 stale/逾時不同。
🔍 畫面結構
1. 頂部標題列
- 返回
/admin/catquest的箭頭（←）。 - Refresh：重新載入目前 CSN 的代理清單。
2. Open Interactive Sessions
僅當至少存在一個活躍的 claude_interactive_session 代理時（即目前在某主機上註冊為執行中的互動式 Claude Code 工作階段），才會單獨顯示此卡片。每一列顯示工作階段名稱、主機、最後通訊時間，以及當該代理的 capabilities 中已註冊工作階段 URL 時顯示的 「Open session」 連結。
3. 代理清單（表格）
每個排程器代理占一列，包含：
- Name —— 身分狀態圓點、代理名稱、作業系統/代理類型/版本徽章、
lssn（關聯伺服器）、截斷顯示的 capabilities 摘要，以及最近記錄的錯誤（若有）。 - Host ——
hostIdentifier。 - Windows Task —— 若適用，執行該代理的 Windows 工作排程器工作名稱。
- Project —— 專案名稱。
- Active —— ON/OFF 徽章（
isActive）。 - Last Comm —— 最後一次心跳/通訊時間戳記。
- Status —— 上述執行狀態徽章，以及（若有回報）目前階段（phase）文字。
底部統計列彙總清單中所有代理的 已處理（Processed）/ 已略過（Skipped）/ 失敗（Failed） 計數。
4. 執行歷史（Run History）
表格下方的「View History」卡片會再次列出所有代理；點擊某列的 History 按鈕會開啟彈窗，顯示該代理最近的執行記錄——執行模式、狀態（含 FAILED）、開始/結束時間、耗時、已處理/已略過/失敗計數、階段、以及摘要。
5. 即時日誌檢視器（Live Log Viewer）
雙欄即時追蹤畫面：
- 左側（代理 → 日誌串流樹）：代理依群組顯示，展開後可看到已知的日誌串流清單（日誌串流以
streamKey識別，具有streamType與輪替世代編號）。代理會依最近通訊時間顯示 online/offline。 - 右側（日誌串流卡片）：選取某個日誌串流後，會顯示其最近的日誌行，並持續更新以實現即時追蹤。
💡 注意事項
- 本畫面為 僅限管理員 使用，需具備
AdminGuard（uLevel ≥ 70）權限。 - 代理清單、執行歷史與日誌目錄皆依工作階段目前的 CSN 範圍取得——如需查看其他專案的代理，請在頂部導覽切換專案。
- 載入資料需要已驗證的工作階段（AK 權杖）；若請求開始因驗證錯誤而失敗，請重新登入後按下 Refresh。
- 本頁面與
/admin/catquest是彼此獨立的工具——透過 CatQuest 畫面的導覽進入本頁，並不代表共用 CatQuest 的貓咪視覺化資料或受眾。
疑難排解
| 症狀 | 原因 | 解決方法 |
|---|---|---|
| 出現「Authentication required」錯誤 | 找不到 AK/工作階段權杖 | 重新登入後重新整理頁面。 |
| 代理清單為空 | 此 CSN 下沒有已註冊的排程器代理，或所選專案不正確 | 確認頂部導覽中已選擇正確的專案（CSN）。 |
| 明明工作已閒置，某列卻顯示紅色 STALE | 代理在執行過程中停止傳送心跳（isStale = true）且未轉為 ENDED —— 可能是程序當機或被強制終止 | 直接檢查代理所在主機；一旦其重新啟動並再次回報，徽章會自動更新。 |
| Live Log Viewer 顯示「No streams yet.」 | 該代理尚未註冊任何日誌串流，或自上次目錄更新以來沒有新輸出 | 等待代理下一次執行，或確認代理程序確實正在寫入日誌。 |
| Open Interactive Sessions 中缺少「Open session」連結 | 該代理已註冊的 capabilities 中未包含 sessionUrl | 沒有可開啟的項目——該互動式工作階段未註冊可連線的 URL。 |
版本：1.0
最後更新：2026-08-29
來源檔案：giipv3/public/help/catquest-schedulers.zh-TW.md