# 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`，不落在任何存取庫 |