jiantw83
2b7176a644
What： - 新增 tools/patrol.sh，三個子命令：collect 收集、finish 收尾、abort 中止。這一輪的巡檢項目是四項純讀取：使用統計、版本落差與重啟閘門、階段鎖與工作包鎖、心跳自述。 - 心跳的寫入從排程移到巡檢收尾。排程只呼叫巡檢，不再直接寫心跳。 - 排程週期由心跳門檻推導，不再寫死。install heartbeat 這個工作代號改為拒絕。 Why： - 排程直接寫心跳的話，心跳新鮮只證明排程活著。巡檢整個壞掉、每輪都失敗，心跳照樣新鮮，閘門照樣放行，而且沒有任何錯誤訊息——這是無聲失效，是最難發現的一種。 - 改成巡檢寫，心跳新鮮才等於上一輪真的跑完了。閘門判的才是工作訊號，不是行程存活訊號。 - 門檻是讀取端的設定，心跳檔裡不存它。所以週期與門檻各寫死一個數字一定會撞：門檻五分鐘、巡檢十五分鐘，心跳永遠是過期的。 How： - 週期取「滿足漏掉一輪還算新鮮、漏掉兩輪才過期」的最大值，並且要能整除一小時。要拉長巡檢週期就調大門檻，週期自動跟著長，兩個數字不會各走各的。 - 心跳只看「這一輪有沒有把結果記下來」，不看四項的成敗。四項有失敗但監控頁寫成了就寫心跳，頁上判定標警示；頁寫不成就中止，一定不寫，讓心跳自己過期。頁每輪都寫失敗卻照樣寫心跳，等於把這次要修掉的缺陷原封不動搬過去。 - 整輪拿一把目錄鎖，搶不到就讓開，不排隊也不並行。並行兩輪會在同一頁附兩節，還會互相蓋掉用量快照。鎖逾時可被下一輪搶走，被搶走的那一輪收尾時對不上就不寫心跳——它沒跑到底，不該蓋章。 - 任一項失敗不影響其餘項目。失敗要在監控頁上看得出來是失敗，不是沒資料；來源是空的則明寫「那是零次，不是故障」。 - 版本盤點照抄腳本原字。抄到查詢失敗就寫查詢失敗，不改寫成相符、也不自己補查遠端版本——查不到是沒有證據，不是版本沒問題。 Who： 助理落地的第四塊。排程那一輪留下的問題在這裡解掉了。
jsc-assist — 技能助理
jsc 技能組的 assist domain：技能與 hook 每跑一次就留下事件，助理負責把事件收攏、判斷健康狀態、寫進 wiki 的監控頁（MONITOR_{HASH}）。
助理只做三件事：觸發既有技能、巡檢既有的唯讀腳本與狀態檔、把結果提醒給前景會話。它不做決策、不改程式碼、不覆寫 wiki。完整界線見 AGENTS.md 的「助理的界線」。
安裝、更新、移除
Marketplace 統一為 jsc（https://gitea.jsc.idv.tw/plugins/meta.git），安裝 token 為 jsc-assist@jsc。每個指令一行：
| CLI | 安裝 | 更新 | 移除 |
|---|---|---|---|
| claude | claude plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && claude plugin install jsc-assist@jsc |
claude plugin marketplace update jsc && claude plugin update jsc-assist@jsc |
claude plugin uninstall jsc-assist@jsc |
| codex | codex plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && codex plugin add jsc-assist@jsc |
codex plugin marketplace upgrade jsc |
codex plugin remove jsc-assist@jsc |
| copilot | copilot plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && copilot plugin install jsc-assist@jsc |
copilot plugin marketplace update jsc && copilot plugin update jsc-assist@jsc |
copilot plugin uninstall jsc-assist@jsc |
| antigravity | git clone https://gitea.jsc.idv.tw/plugins/assist.git ~/plugins/assist && agy plugin install ~/plugins/assist |
git -C ~/plugins/assist pull && agy plugin uninstall jsc-assist && agy plugin install ~/plugins/assist |
agy plugin uninstall jsc-assist |
| kiro | kiro-cli plugin marketplace add https://gitea.jsc.idv.tw/plugins/meta.git && kiro-cli plugin install jsc-assist@jsc |
kiro-cli plugin marketplace update jsc && kiro-cli plugin update jsc-assist@jsc |
kiro-cli plugin uninstall jsc-assist@jsc |
antigravity 不支援 gitea URL 安裝，改用本地 clone 路徑。批次操作五個 CLI：使用
/jsc-cli:deploy。
Skills 目錄
呼叫方式：Claude / Antigravity /jsc-assist:{name}；Codex ${name}；Copilot / Kiro 描述需求自動觸發。
assistant
助理主體，四個操作：start 啟動、status 查現況、patrol 跑一輪巡檢、stop 停止。心跳的寫入、判定與清除一律交給 jsc-hooks 的 hooks/heartbeat.sh，判定只有那一份；系統排程一律交給 tools/schedule.sh；一輪巡檢的流程交給 tools/patrol.sh。心跳由巡檢寫，而且只由巡檢寫：一輪跑完、結果寫上監控頁了，才寫那一次心跳，所以心跳新鮮等於「上一輪巡檢真的做完了」。start 先跑一輪巡檢，再裝上巡檢那一筆排程；巡檢週期由心跳的過期門檻算出來，兩個數字綁在一起。patrol 讀四項來源（使用統計、版本與重啟閘門、SDLC 階段鎖與工作包鎖、心跳自述），四項各自獨立，一項掛掉其餘三項照跑、照記，結果一律附加到 MONITOR_{HASH}、不覆寫。status 全程唯讀，讀心跳、排程與待辦簿，印成三塊；助理沒在跑就印「助理未運行」，不當成錯誤。stop 先移除排程再清掉心跳，順序不能反。這支不參與閘門判定、不做決策、巡檢那一路全程不問人。
相依
| Plugin | 最低版本 | 用途 |
|---|---|---|
jsc-cli |
>=0.2.7 |
CLI 偵測與委派 |
jsc-gitea |
>=0.2.0 |
監控頁的所有 wiki 讀寫，一律經 tools/gitea.sh |
jsc-hooks |
>=0.3.7 |
心跳、閘門與事件來源（$JSC_HOME 底下的狀態檔）。心跳的寫入、判定與清除一律走 hooks/heartbeat.sh，那支腳本是 0.3.7 才有的 |
jsc-log |
>=0.1.4 |
使用統計與工作日誌的資料來源 |
參考與工具
| 檔案 | 用途 |
|---|---|
tools/schedule.sh |
助理系統排程的安裝、移除與查現況。三個子命令 install、remove、status，只裝 patrol 這一筆——心跳由巡檢自己寫，install heartbeat 一律回 6，舊版遺留的心跳條目由 install patrol 順手清掉。巡檢週期由心跳的過期門檻算出來（2 × 週期 × 60 < 門檻，再取能整除一小時的分鐘數）：門檻 300 秒是每 2 分鐘一輪，門檻 1800 秒是每 12 分鐘一輪。Linux、WSL 與 macOS 走 crontab，Windows 走 schtasks。條目行尾帶固定標記 # jsc-assist:assistant {工作}，只動自己那一筆，別人的排程一行都不碰。裝完會檢查排程服務在不在跑，沒跑就回 1——WSL 預設不啟動 cron。--dry-run 只印組出來的條目與寫回後的內容，什麼都不動 |
tools/patrol.sh |
一輪巡檢的收攏與收口。三個子命令：collect 取鎖、讀四項來源、組出監控頁要附加的那一節與目錄頁那一列；finish 在監控頁寫成之後才寫心跳、換上用量快照、放掉鎖；abort 只放掉鎖，不寫心跳。四項來源各自獨立，一項失敗其餘三項照跑，失敗那一項在頁上寫明是「這一項失敗」而不是沒資料。整輪拿一把目錄鎖，上一輪還在跑就回 4 讓開；鎖逾時（門檻取心跳門檻）會被下一輪搶回來，並在頁上記一筆。version-guard.sh report 回「查詢失敗」時照原字抄，不補查、不美化 |
references/behaviors.md |
本 domain 的技能行為清單：一支技能一節，五列記下觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象，供稽核與驗證比對。格式合約見 plugins/meta 的 references/guidelines.md「技能行為清單」 |
templates/monitor-contents.md |
目錄頁 MONITOR_CONTENTS 的範本。一列代表一台機器，雜湊來源是 {主機名}/{登入帳號}。寫入語意是只更新自己那一列：比對主機與帳號兩欄，別台機器的列原樣保留，禁止整頁覆蓋 |
templates/monitor-page.md |
內容頁 MONITOR_{HASH} 的範本。記的是這台機器的巡檢軌跡。寫入語意與目錄頁相反，是一律附加一節、不覆寫：一次巡檢一節，節標題帶時間戳，既有的節一個字都不動 |
助理的狀態檔
全部放在 $JSC_HOME/assistant/ 底下，一律純文字 key=value：
| 路徑 | 內容 |
|---|---|
heartbeat |
心跳檔，欄位 ts、pid、cli、session。只由 tools/patrol.sh finish 寫，也就是一輪巡檢跑完、結果記下來之後才寫。判準只看 ts，不看 pid 存活——五支 CLI 與容器裡的行程互相看不到彼此的 pid |
tasks/{id} |
待辦簿，一筆一檔。一筆一檔是為了讓並行寫入不互相覆寫 |
schedule.log |
排程條目的輸出。刻意放在存取庫外面：寫進專案會多出未追蹤檔，污染別人的變更盤點 |
patrol.lock/ |
一輪巡檢的鎖，是目錄——mkdir 是原子操作，搶不到就是別人在跑。裡面的 info 記 round、pid、started |
patrol/ |
本輪巡檢的暫存檔：section.md 是要附加的那一節，newpage.md 是頁不存在時要建的整頁，contents.tsv 是目錄頁那一列 |
usage-prev.tsv |
上一輪記下來的累計用量。有了它，下一輪的「本輪次數」才算得出來；沒有它的第一輪一律寫「-」，不拿累計冒充本輪 |