feat(assistant): 助理主體收攏 start、status、stop 三個操作

What:
- 新增 assistant 技能,提供啟動、查現況、停止三個操作。
- 刪掉原本獨立的 status 技能,行為清單與 README 的技能目錄一起改。
- 三份 manifest 的版本一起提升,對 jsc-hooks 的下限提到含心跳腳本的那一版。

Why:
- 助理的生命週期是一件事,拆在兩支技能裡,靠描述自動觸發的 CLI 等於擲骰子挑一支。準則也明寫技能目標不得重複。
- 刪除的代價這時候最低:這個 domain 才剛落地,status 是它唯一一支技能,除了自己的文件沒有別的東西指向它。晚一步等各處都引用了再收攏,成本差很多。

How:
- 心跳的判定一律交給 jsc-hooks 的心跳腳本,三個操作都讀它的回報,不自己解析心跳檔。判定有兩份就會漂移,狀態與訊息就會對不上。
- 那支腳本的每一個結束碼都在技能裡有明確處置,包含「腳本自己沒跑起來」那一種——那時候既不能說助理在跑,也不能說助理停了。
- 時間戳壞掉一律當成不新鮮,絕不退回判成新鮮。
- 異常結束不需要額外的清理機制:心跳是時間戳,過了門檻自動失效。反過來說,stop 以外的任何路徑都不該寫心跳,否則就是留一個假心跳。
- stop 清心跳是它的職責,不算助理界線裡「不刪狀態檔」那一條。技能內文把這個例外寫明白,免得日後照界線把 stop 砍掉。
- stop 的收尾同時講兩件事:心跳清掉之後閘門會擋下技能呼叫,以及閘門目前還沒接線所以這一刻擋不到誰。前者是設計後果,停助理的人一定要知道;後者不講就是說一件還沒成真的事。
- 排程這一輪不做,start 只寫第一次心跳,並講明心跳不會自動更新。

Who:
助理落地的第二塊:心跳有了,接著要有人寫它、讀它、清它。
This commit is contained in:
2026-09-01 14:19:24 +08:00
parent 4b0e4d796c
commit fbf3e5a605
7 changed files with 116 additions and 70 deletions
+6 -6
View File
@@ -2,12 +2,12 @@
本頁記錄 jsc-assist 每支技能的行為基準,供技能驗證比對。技能異動時,在同一個 PR 內一起更新這一頁。
## status
## assistant
| 項目 | 內容 |
| --- | --- |
| 觸發時機 | 有人問助理現在還在不在跑,或問待辦簿裡剩下哪幾筆時用。啟動與停止助理不走這支。執行環境健檢不走這支,走 `jsc-cli:doctor`。技能使用次數不走這支,走 `jsc-log:stats` |
| 關鍵步驟 | 解出 `$JSC_HOME`(未設定就退回 `~/.jsc`)並組出 `assistant/` 目錄、讀 `heartbeat` 的 `ts`、`pid`、`cli`、`session`、以 `ts` 距現在是否不到 300 秒判成新鮮或過期、不看 pid 存活、列出 `tasks/` 底下每一個檔案並解析 `state`、`title`、`next_run`、`fail_count`、把心跳區塊與逐筆待辦印成一張表、`fail_count` 大於 0 的列標上「已連續失敗 N 次」 |
| 外部呼叫 | 無。只讀 `$JSC_HOME/assistant/heartbeat` 與 `$JSC_HOME/assistant/tasks/` 底下的檔案。不呼叫腳本、不呼叫其他技能、不碰 wiki、不啟動也不停止助理 |
| 完成條件 | 印出現況表,或印出「助理未運行」並說明是哪個路徑讀不到。心跳檔不存在、待辦簿目錄不存在、待辦簿零筆,三種都算正常結束,不得以非 0 結束 |
| 可驗證跡象 | 無寫入跡象,只有回報內容 |
| 觸發時機 | 要啟動助理、要停止助理,或要問助理現在還在不在跑、待辦簿剩下哪幾筆時用。三個操作 `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 頁 |