# 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 頁 |