jiantw83
fbf3e5a605
What： - 新增 assistant 技能，提供啟動、查現況、停止三個操作。 - 刪掉原本獨立的 status 技能，行為清單與 README 的技能目錄一起改。 - 三份 manifest 的版本一起提升，對 jsc-hooks 的下限提到含心跳腳本的那一版。 Why： - 助理的生命週期是一件事，拆在兩支技能裡，靠描述自動觸發的 CLI 等於擲骰子挑一支。準則也明寫技能目標不得重複。 - 刪除的代價這時候最低：這個 domain 才剛落地，status 是它唯一一支技能，除了自己的文件沒有別的東西指向它。晚一步等各處都引用了再收攏，成本差很多。 How： - 心跳的判定一律交給 jsc-hooks 的心跳腳本，三個操作都讀它的回報，不自己解析心跳檔。判定有兩份就會漂移，狀態與訊息就會對不上。 - 那支腳本的每一個結束碼都在技能裡有明確處置，包含「腳本自己沒跑起來」那一種——那時候既不能說助理在跑，也不能說助理停了。 - 時間戳壞掉一律當成不新鮮，絕不退回判成新鮮。 - 異常結束不需要額外的清理機制：心跳是時間戳，過了門檻自動失效。反過來說，stop 以外的任何路徑都不該寫心跳，否則就是留一個假心跳。 - stop 清心跳是它的職責，不算助理界線裡「不刪狀態檔」那一條。技能內文把這個例外寫明白，免得日後照界線把 stop 砍掉。 - stop 的收尾同時講兩件事：心跳清掉之後閘門會擋下技能呼叫，以及閘門目前還沒接線所以這一刻擋不到誰。前者是設計後果，停助理的人一定要知道；後者不講就是說一件還沒成真的事。 - 排程這一輪不做，start 只寫第一次心跳，並講明心跳不會自動更新。 Who： 助理落地的第二塊：心跳有了，接著要有人寫它、讀它、清它。
2.6 KiB
2.6 KiB
jsc-assist 技能行為清單
本頁記錄 jsc-assist 每支技能的行為基準，供技能驗證比對。技能異動時，在同一個 PR 內一起更新這一頁。
assistant
| 項目 | 內容 |
|---|---|
| 觸發時機 | 要啟動助理、要停止助理，或要問助理現在還在不在跑、待辦簿剩下哪幾筆時用。三個操作 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 頁 |