jiantw83
7343def16e
What： - 新增 tools/schedule.sh，三個子命令：install 安裝、remove 移除、status 查現況。兩筆工作分別是每分鐘的心跳與每十五分鐘的巡檢。 - 助理主體的 start 接上安裝、stop 接上移除，行為清單與 README 跟著更新。 Why： - 心跳要有人定時寫，不然啟動之後過幾分鐘就自己過期，助理看起來像沒在跑。 - 排程這件事有標準的輸入與輸出，準則要求下放腳本，技能只描述何時呼叫。 How： - 條目行尾帶固定標記，安裝先濾掉自己的舊條目再追加。絕不覆寫整份排程，別人的條目一行都不碰；寫完回讀驗證，出現兩筆或別人的行數對不上就報錯。 - 裝完檢查排程服務在不在跑。這台機器是 WSL，預設不啟動 cron，裝了條目卻一次都不會執行——不檢查就會宣稱一件沒發生的事。 - 條目一律帶 </dev/null。排程是非互動環境，任何等輸入的東西都會把整筆卡死。 - 輸出寫到 JSC_HOME 底下，不寫進任何專案目錄，免得多出未追蹤檔污染別人的變更盤點。 - 巡檢那一筆預設不裝，要明著指定才會裝。巡檢本體還沒實作，裝了只會每十五分鐘失敗一次；巡檢指令也不猜 CLI，判不出來就停下，猜錯的代價是每十五分鐘跑一支不存在的執行檔。 - stop 先移除排程再清心跳，順序不能反。反過來的話清完下一分鐘排程就補寫一次，stop 等於騙人。 Who： 助理落地的第三塊。這裡留下一個要在巡檢那一輪解掉的問題：心跳目前由排程直接寫，所以心跳新鮮只證明排程活著，不證明助理做了事。往後應該改由巡檢跑完那一輪去寫，心跳才等於工作訊號。限制已寫進技能內文與說明文件。
67 lines
5.8 KiB
Markdown
67 lines
5.8 KiB
Markdown
# 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 描述需求自動觸發。
|
||
|
||
<!-- JSC-SKILLS:START -->
|
||
|
||
### `assistant`
|
||
|
||
助理主體，三個操作：`start` 啟動、`status` 查現況、`stop` 停止。心跳的寫入、判定與清除一律交給 `jsc-hooks` 的 `hooks/heartbeat.sh`，判定只有那一份；系統排程一律交給 `tools/schedule.sh`，技能自己不碰 crontab 與 schtasks。`start` 寫下第一次心跳，再裝上每分鐘寫一次心跳的排程；cron 服務沒在跑就照實講條目不會被執行。`status` 全程唯讀，讀心跳、排程與待辦簿，印成三塊；助理沒在跑就印「助理未運行」，不當成錯誤。`stop` 先移除排程再清掉心跳，順序不能反——反了下一分鐘 cron 會再寫一次心跳。這支不碰 wiki、不參與閘門判定。心跳新鮮只證明排程活著，不證明助理做了事。
|
||
|
||
<!-- JSC-SKILLS:END -->
|
||
|
||
## 相依
|
||
|
||
| 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`，兩筆工作 `heartbeat`（每 60 秒）與 `patrol`（每 15 分鐘）。Linux、WSL 與 macOS 走 crontab，Windows 走 schtasks。條目行尾帶固定標記 `# jsc-assist:assistant {工作}`，只動自己那一筆，別人的排程一行都不碰。裝完會檢查排程服務在不在跑，沒跑就回 1——WSL 預設不啟動 cron。巡檢那一筆預設不裝，巡檢本體還沒實作。`--dry-run` 只印組出來的條目與寫回後的內容，什麼都不動 |
|
||
| `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`。判準只看 `ts`，不看 pid 存活——五支 CLI 與容器裡的行程互相看不到彼此的 pid |
|
||
| `tasks/{id}` | 待辦簿，一筆一檔。一筆一檔是為了讓並行寫入不互相覆寫 |
|
||
| `schedule.log` | 排程條目的輸出。刻意放在存取庫外面：寫進專案會多出未追蹤檔，污染別人的變更盤點 |
|
||
|
||
## 相關 domain
|
||
|
||
- [`jsc-hooks`](https://gitea.jsc.idv.tw/plugins/hooks)：閘門與心跳，跟 hook 一起裝
|
||
- [`jsc-gitea`](https://gitea.jsc.idv.tw/plugins/gitea)：wiki 讀寫的唯一入口
|
||
- [`jsc-log`](https://gitea.jsc.idv.tw/plugins/log)：使用統計與工作日誌
|
||
- [`jsc-cli`](https://gitea.jsc.idv.tw/plugins/cli)：環境健檢與跨 CLI 委派
|