jiantw83
7343def16e
What： - 新增 tools/schedule.sh，三個子命令：install 安裝、remove 移除、status 查現況。兩筆工作分別是每分鐘的心跳與每十五分鐘的巡檢。 - 助理主體的 start 接上安裝、stop 接上移除，行為清單與 README 跟著更新。 Why： - 心跳要有人定時寫，不然啟動之後過幾分鐘就自己過期，助理看起來像沒在跑。 - 排程這件事有標準的輸入與輸出，準則要求下放腳本，技能只描述何時呼叫。 How： - 條目行尾帶固定標記，安裝先濾掉自己的舊條目再追加。絕不覆寫整份排程，別人的條目一行都不碰；寫完回讀驗證，出現兩筆或別人的行數對不上就報錯。 - 裝完檢查排程服務在不在跑。這台機器是 WSL，預設不啟動 cron，裝了條目卻一次都不會執行——不檢查就會宣稱一件沒發生的事。 - 條目一律帶 </dev/null。排程是非互動環境，任何等輸入的東西都會把整筆卡死。 - 輸出寫到 JSC_HOME 底下，不寫進任何專案目錄，免得多出未追蹤檔污染別人的變更盤點。 - 巡檢那一筆預設不裝，要明著指定才會裝。巡檢本體還沒實作，裝了只會每十五分鐘失敗一次；巡檢指令也不猜 CLI，判不出來就停下，猜錯的代價是每十五分鐘跑一支不存在的執行檔。 - stop 先移除排程再清心跳，順序不能反。反過來的話清完下一分鐘排程就補寫一次，stop 等於騙人。 Who： 助理落地的第三塊。這裡留下一個要在巡檢那一輪解掉的問題：心跳目前由排程直接寫，所以心跳新鮮只證明排程活著，不證明助理做了事。往後應該改由巡檢跑完那一輪去寫，心跳才等於工作訊號。限制已寫進技能內文與說明文件。
4.1 KiB
4.1 KiB
jsc-assist 技能行為清單
本頁記錄 jsc-assist 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
assistant
| 項目 | 內容 |
|---|---|
| 觸發時機 | 要啟動助理、要停止助理，或要問助理現在還在不在跑、待辦簿剩下哪幾筆時用。三個操作 start、status、stop 都走這一支。執行環境健檢不走這支，走 jsc-cli:doctor。技能使用次數不走這支，走 jsc-log:stats |
| 關鍵步驟 | 先認出使用者要的是哪一個操作。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，不落在任何存取庫 |