feat(schedule): 助理的系統排程接線
What: - 新增 tools/schedule.sh,三個子命令:install 安裝、remove 移除、status 查現況。兩筆工作分別是每分鐘的心跳與每十五分鐘的巡檢。 - 助理主體的 start 接上安裝、stop 接上移除,行為清單與 README 跟著更新。 Why: - 心跳要有人定時寫,不然啟動之後過幾分鐘就自己過期,助理看起來像沒在跑。 - 排程這件事有標準的輸入與輸出,準則要求下放腳本,技能只描述何時呼叫。 How: - 條目行尾帶固定標記,安裝先濾掉自己的舊條目再追加。絕不覆寫整份排程,別人的條目一行都不碰;寫完回讀驗證,出現兩筆或別人的行數對不上就報錯。 - 裝完檢查排程服務在不在跑。這台機器是 WSL,預設不啟動 cron,裝了條目卻一次都不會執行——不檢查就會宣稱一件沒發生的事。 - 條目一律帶 </dev/null。排程是非互動環境,任何等輸入的東西都會把整筆卡死。 - 輸出寫到 JSC_HOME 底下,不寫進任何專案目錄,免得多出未追蹤檔污染別人的變更盤點。 - 巡檢那一筆預設不裝,要明著指定才會裝。巡檢本體還沒實作,裝了只會每十五分鐘失敗一次;巡檢指令也不猜 CLI,判不出來就停下,猜錯的代價是每十五分鐘跑一支不存在的執行檔。 - stop 先移除排程再清心跳,順序不能反。反過來的話清完下一分鐘排程就補寫一次,stop 等於騙人。 Who: 助理落地的第三塊。這裡留下一個要在巡檢那一輪解掉的問題:心跳目前由排程直接寫,所以心跳新鮮只證明排程活著,不證明助理做了事。往後應該改由巡檢跑完那一輪去寫,心跳才等於工作訊號。限制已寫進技能內文與說明文件。
This commit is contained in:
@@ -7,7 +7,7 @@
|
||||
| 項目 | 內容 |
|
||||
| --- | --- |
|
||||
| 觸發時機 | 要啟動助理、要停止助理,或要問助理現在還在不在跑、待辦簿剩下哪幾筆時用。三個操作 `start`、`status`、`stop` 都走這一支。執行環境健檢不走這支,走 `jsc-cli:doctor`。技能使用次數不走這支,走 `jsc-log:stats` |
|
||||
| 關鍵步驟 | 先認出使用者要的是哪一個操作。`start`:跑 `heartbeat.sh write` 寫第一次心跳、跑 `heartbeat.sh report` 確認寫進去了、印出心跳路徑與時間並註明排程還沒接線、心跳過了門檻要再跑一次 start。`status`:跑 `heartbeat.sh report` 取心跳現況、把 `state` 對映成新鮮、過期、心跳檔損壞、不存在、不自己解析心跳檔也不自己判定、從 `file=` 解出助理目錄後列出 `tasks/` 底下每一個檔案並解析 `state`、`title`、`next_run`、`fail_count`、印成一張表、`fail_count` 大於 0 的列標上「已連續失敗 N 次」。`stop`:先跑 `heartbeat.sh report` 留下原本的狀態、再跑 `heartbeat.sh clear` 清掉心跳、印出停止訊息並說明心跳清掉之後閘門會擋人、同時說明閘門還沒接線所以現在擋不到人 |
|
||||
| 外部呼叫 | `jsc-hooks/hooks/heartbeat.sh` 的 `write`、`report`、`clear` 三個子命令,六個結束碼各有處置:0 往下走、1 與 3 印「助理未運行」、2 回報判不出狀態並停下、4 當成不新鮮並回報心跳檔損壞、5 是嚴重狀況要吵出來且不得回報成功、6 是呼叫寫錯要更正後重跑。另外唯讀 `$JSC_HOME/assistant/tasks/` 底下的檔案。呼叫端沒講清楚要哪一個操作時,走 `jsc-ask:ask` 的決策樹問。不碰 wiki、不參與閘門判定 |
|
||||
| 完成條件 | `start` 要 `write` 回 0 且 `report` 回 `state=fresh`,才算啟動成功;`write` 回 5 一律回報失敗並停下,不得宣稱啟動。`status` 要印出現況表,或印出「助理未運行」並說明原因;心跳不存在、待辦簿目錄不存在、待辦簿零筆,三種都算正常結束。`stop` 要 `clear` 回 0,並印出帶兩段話的停止訊息;`clear` 回 5 就回報心跳檔還在、助理沒有確實停掉,不印停止訊息 |
|
||||
| 可驗證跡象 | `start` 之後 `$JSC_HOME/assistant/heartbeat` 存在,`ts` 是剛才的時間。`stop` 之後同一個路徑不存在。`status` 無寫入跡象,只有回報內容。三個操作都不動 `tasks/` 底下的檔案,也不動 worktree 與 wiki 頁 |
|
||||
| 關鍵步驟 | 先認出使用者要的是哪一個操作。`start`:跑 `heartbeat.sh write` 寫第一次心跳、跑 `heartbeat.sh report` 確認寫進去了、跑 `tools/schedule.sh install heartbeat` 裝每分鐘那一筆排程、依結束碼選一段收尾訊息印出——排程接上、排程寫進去了但 cron 沒在跑、排程沒接上三種各一段。巡檢那一筆預設不裝,要呼叫端指名 `patrol` 或 `all` 才裝,而且要先講明巡檢本體還沒實作、裝了每一輪都會失敗。`status`:跑 `heartbeat.sh report` 取心跳現況、把 `state` 對映成新鮮、過期、心跳檔損壞、不存在、不自己解析心跳檔也不自己判定、從 `file=` 解出助理目錄後列出 `tasks/` 底下每一個檔案並解析 `state`、`title`、`next_run`、`fail_count`、跑 `tools/schedule.sh status` 取排程現況、印成心跳、排程、待辦三塊、`fail_count` 大於 0 的列標上「已連續失敗 N 次」、心跳與排程兜起來會誤讀的三種組合各補一句話。`stop`:先跑 `heartbeat.sh report` 留下原本的狀態、再跑 `tools/schedule.sh remove all` 移除排程、最後才跑 `heartbeat.sh clear` 清掉心跳、印出停止訊息並說明心跳清掉之後閘門會擋人、同時說明閘門還沒接線所以現在擋不到人 |
|
||||
| 外部呼叫 | `jsc-hooks/hooks/heartbeat.sh` 的 `write`、`report`、`clear` 三個子命令,六個結束碼各有處置:0 往下走、1 與 3 印「助理未運行」、2 回報判不出狀態並停下、4 當成不新鮮並回報心跳檔損壞、5 是嚴重狀況要吵出來且不得回報成功、6 是呼叫寫錯要更正後重跑。本 domain 的 `tools/schedule.sh` 的 `install`、`remove`、`status` 三個子命令,七個結束碼各有處置:0 往下走、1 是條目裝了但 cron 沒在跑要照實講不會執行、2 是缺 jsc-hooks、3 是這台機器沒有排程機制、4 是排程操作失敗要原樣引用 stderr、5 是回讀驗證失敗要叫人自己去看 `crontab -l`、6 是呼叫寫錯。crontab 與 schtasks 一律經那支腳本,技能自己不碰。另外唯讀 `$JSC_HOME/assistant/tasks/` 底下的檔案。呼叫端沒講清楚要哪一個操作時,走 `jsc-ask:ask` 的決策樹問。不碰 wiki、不參與閘門判定 |
|
||||
| 完成條件 | `start` 要 `write` 回 0 且 `report` 回 `state=fresh`,才算啟動成功;`write` 回 5 一律回報失敗並停下,不得宣稱啟動;`schedule.sh install` 回 1 要講明條目不會被執行與 `sudo service cron start`,不得宣稱排程會定時執行。`status` 要印出現況表,或印出「助理未運行」並說明原因;心跳不存在、待辦簿目錄不存在、待辦簿零筆、排程沒裝,四種都算正常結束。`stop` 要 `schedule.sh remove all` 先回 0、`clear` 再回 0,並印出帶三段話的停止訊息;`remove` 非 0 就回報排程還在、助理停不掉,不清心跳也不印停止訊息;`clear` 回 5 就回報心跳檔還在、助理沒有確實停掉,不印停止訊息 |
|
||||
| 可驗證跡象 | `start` 之後 `$JSC_HOME/assistant/heartbeat` 存在,`ts` 是剛才的時間,`crontab -l` 找得到一筆帶 `# jsc-assist:assistant heartbeat` 的條目,而且只有一筆。`stop` 之後心跳路徑不存在,`crontab -l` 找不到任何 `# jsc-assist:assistant` 條目。兩者都不動別人的排程條目,條目數量前後相同。`status` 無寫入跡象,只有回報內容。三個操作都不動 `tasks/` 底下的檔案,也不動 worktree 與 wiki 頁。排程的 log 一律在 `$JSC_HOME/assistant/schedule.log`,不落在任何存取庫 |
|
||||
|
||||
Reference in New Issue
Block a user