From e7e9b8ce184e388547803dee278944d65d169b0b Mon Sep 17 00:00:00 2001 From: Jeffery Date: Tue, 1 Sep 2026 12:11:26 +0800 Subject: [PATCH] =?UTF-8?q?feat(templates):=20=E6=96=B0=E5=A2=9E=E7=9B=A3?= =?UTF-8?q?=E6=8E=A7=E9=A0=81=E7=9A=84=E7=9B=AE=E9=8C=84=E9=A0=81=E8=88=87?= =?UTF-8?q?=E5=85=A7=E5=AE=B9=E9=A0=81=E7=AF=84=E6=9C=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit What： - 新增 templates/monitor-contents.md 與 templates/monitor-page.md。 - README 的「參考與工具」表補上這兩份範本，說明欄寫出兩者相反的寫入語意。 - 三份 manifest 的版本一起提升。 Why： - 監控頁是助理巡檢結果的落點。沒有範本，每次巡檢寫出來的格式都不一樣，累積久了看不出趨勢，也對不起來。 - 兩份範本的寫入語意剛好相反，必須各自寫明白。目錄頁是共用的，一列代表一台機器，整頁覆蓋會刪掉別台機器的紀錄；內容頁只屬於一台機器，記的是歷次巡檢的軌跡，所以附加不覆寫。 How： - 目錄頁範本帶欄位說明與寫入規則：比對主機與帳號兩欄，只更新自己那一列，讀不到舊內容就中止，不硬寫。 - 內容頁範本一次巡檢附加一節，節標題帶時間戳，涵蓋心跳與閘門、使用統計、hook 錯誤、版本落差、階段鎖與工作包鎖、待辦簿到期與逾期六類結果。 - 連續失敗的項目一定要標「已連續失敗 N 次」。待辦簿的項目失敗不會自動暫停，會每輪重試，不標出來就是一個壞掉的項目一直重試而沒人知道。 - 內容以圖表優先，流程用 mermaid、結果用表格，純文字每節最多三句。 Who： 技能助理落地帶出來的頁型別需求，四個存放庫同一批改。 --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- README.md | 2 + plugin.json | 2 +- templates/monitor-contents.md | 44 +++++++++++++ templates/monitor-page.md | 114 ++++++++++++++++++++++++++++++++++ 6 files changed, 163 insertions(+), 3 deletions(-) create mode 100644 templates/monitor-contents.md create mode 100644 templates/monitor-page.md diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index 1f37653..c8d5d82 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-assist", - "version": "0.0.1", + "version": "0.0.2", "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_{HASH} wiki 頁）", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 6f6a6bf..c12c2d9 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-assist", - "version": "0.0.1", + "version": "0.0.2", "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_{HASH} wiki 頁）", "skills": "./skills", "jsc": { diff --git a/README.md b/README.md index 514442c..6f03302 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,8 @@ Marketplace 統一為 `jsc`（https://gitea.jsc.idv.tw/plugins/meta.git），安 | 檔案 | 用途 | | --- | --- | | `references/behaviors.md` | 本 domain 的技能行為清單：一支技能一節，五列記下觸發時機、關鍵步驟、外部呼叫、完成條件、可驗證跡象，供稽核與驗證比對。格式合約見 `plugins/meta` 的 `references/guidelines.md`「技能行為清單」 | +| `templates/monitor-contents.md` | 目錄頁 `MONITOR_CONTENTS` 的範本。一列代表一台機器，雜湊來源是 `{主機名}/{登入帳號}`。寫入語意是**只更新自己那一列**：比對主機與帳號兩欄，別台機器的列原樣保留，禁止整頁覆蓋 | +| `templates/monitor-page.md` | 內容頁 `MONITOR_{HASH}` 的範本。記的是這台機器的巡檢軌跡。寫入語意與目錄頁相反，是**一律附加一節、不覆寫**：一次巡檢一節，節標題帶時間戳，既有的節一個字都不動 | ## 助理的狀態檔 diff --git a/plugin.json b/plugin.json index f6f7877..b25d28f 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-assist", - "version": "0.0.1", + "version": "0.0.2", "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_{HASH} wiki 頁）", "skills": "./skills/", "jsc": { diff --git a/templates/monitor-contents.md b/templates/monitor-contents.md new file mode 100644 index 0000000..b4dcf07 --- /dev/null +++ b/templates/monitor-contents.md @@ -0,0 +1,44 @@ +# 助理巡檢目錄 + +> 由 `jsc-assist` 維護。這是目錄頁 `MONITOR_CONTENTS`。 +> 一列代表一台機器。雜湊來源是 `{主機名}/{登入帳號}`，所以一台機器一列、一頁，換一支 CLI 不另開列。 +> `MONITOR_{HASH}` 的 `{HASH}` 交給 `jsc-gitea/tools/hash-id` 產生，雜湊來源見 `jsc-meta` 的 `references/guidelines.md`「Wiki 頁命名總表」。 + +| 監控頁 | 主機 | 帳號 | 心跳 | 最後巡檢 | 待辦筆數 | 連續失敗項 | +| --- | --- | --- | --- | --- | ---: | ---: | +| [[MONITOR_{HASH}]] | {主機名} | {登入帳號} | {新鮮、過期、不存在 三選一} | {yyyy-MM-dd HH:mm} | {n} | {n} | + +## 欄位說明 + +| 欄位 | 內容 | 為什麼留這一欄 | +| --- | --- | --- | +| 監控頁 | 指向 `MONITOR_{HASH}` 的同 wiki 連結 | 少了連結就要人自己算雜湊才翻得到內容頁 | +| 主機 | 這台機器的主機名，與雜湊第一段相同 | 比對用的兩欄之一，決定要更新哪一列 | +| 帳號 | 助理執行時的登入帳號，與雜湊第二段相同 | 比對用的兩欄之一。同一台機器換帳號就是另一個巡檢對象 | +| 心跳 | 巡檢當下的心跳判定，判準只看 `ts` 距現在是否不到 300 秒 | 一眼看出這台機器的助理還在不在跑，不必逐頁翻 | +| 最後巡檢 | 該頁最新一節的時間戳 | 心跳新鮮而這一欄很舊，代表助理活著卻沒在巡 | +| 待辦筆數 | 待辦簿現有筆數 | 心跳新鮮而筆數為 0，代表助理空轉，沒有東西可跑 | +| 連續失敗項 | 該頁最新一節裡 `fail_count` 大於 0 的筆數 | 待辦簿的項目失敗不會自動暫停，每輪都重試。這一欄讓壞掉的項目在目錄頁就現形 | + +## 寫入規則 + +這一頁是共用目錄，別台機器的列一律原樣保留。 + +```mermaid +flowchart TD + A[整頁讀回來] --> B{讀得到舊內容} + B -- 否 --> C[中止：不新增列，也不寫入] + B -- 是 --> D{主機與帳號兩欄都對得上} + D -- 是 --> E[只覆寫那一列的其餘欄位] + D -- 否 --> F[新增一列] + E --> G[其他機器的列原樣送回] + F --> G +``` + +- 先整頁讀回來，再比對主機與帳號兩欄。 +- 兩欄都相同就更新那一列，其餘欄位覆寫成本次巡檢結果。 +- 找不到兩欄都相同的列，才新增一列。 +- 只動自己那一列，別台機器的列一個字都不改。 +- 禁止整頁覆蓋。整頁覆蓋等於刪掉別台機器的紀錄。 +- 讀不到舊內容就中止，不新增列，也不寫入。 +- 內容頁 `MONITOR_{HASH}` 的寫入語意相反，那頁只附加一節、不覆寫，兩者不要混用。 diff --git a/templates/monitor-page.md b/templates/monitor-page.md new file mode 100644 index 0000000..84fdf6b --- /dev/null +++ b/templates/monitor-page.md @@ -0,0 +1,114 @@ +# 助理巡檢 — {主機名}/{登入帳號} + +> 由 `jsc-assist` 維護。這是監控頁 `MONITOR_{HASH}`。 +> 這頁是這台機器的巡檢軌跡：一次巡檢附加一節，節標題帶時間戳，舊的節一個字都不動。 +> 附加是刻意的。助理的寫入是背景行為，覆寫錯了沒人在現場，軌跡被抹掉也看不出斷在哪一輪。 +> 目錄頁 `MONITOR_CONTENTS` 只更新自己那一列，寫入語意與這頁不同，不要混用。 + +```mermaid +flowchart LR + A[巡檢一輪] --> B[收攏六類結果] + B --> C[附加一節，節標題帶時間戳] + C --> D[既有的節原樣保留] + D --> E[回頭更新 MONITOR_CONTENTS 自己那一列] +``` + +## 本頁基本資料 + +建頁時寫一次，之後不再更動。 + +| 項目 | 內容 | +| --- | --- | +| 主機 | {主機名} | +| 帳號 | {登入帳號} | +| 雜湊來源 | `{主機名}/{登入帳號}` | +| 狀態檔根目錄 | `$JSC_HOME/assistant/`（`$JSC_HOME` 未設定就退回 `~/.jsc`） | + +## 巡檢 {yyyy-MM-dd HH:mm} + +一輪巡檢就是這樣一節，最新的一節放在最下面。六個子節固定都寫；某個來源讀不到，就在那個子節寫明是哪個路徑讀不到，不要整節略過。 + +| 項目 | 內容 | +| --- | --- | +| 巡檢時間 | {yyyy-MM-dd HH:mm} | +| 觸發方式 | {排程、事件、手動 三選一} | +| 本輪判定 | {正常、警示、異常 三選一} | +| 讀不到的來源 | {路徑清單，全部讀得到就寫「無」} | + +### 心跳與閘門狀態 + +| 項目 | 內容 | +| --- | --- | +| 心跳 | {新鮮、過期、不存在 三選一} | +| 上次心跳 | {yyyy-MM-dd HH:mm}，距這次巡檢 {n} 秒 | +| cli | {claude、codex、copilot、antigravity、kiro 五選一} | +| session | {工作階段代號} | +| pid | {數字}。只給要找行程的人參考，不參與判定 | + +心跳的判準只看 `ts` 距現在是否不到 300 秒。不看 pid 存活：五支 CLI 與容器裡的行程互相看不到彼此的 pid。閘門的判定留在 hook，助理只維持心跳。 + +### 技能與呼叫鏈使用統計 + +資料出自 `$JSC_HOME/usage/skills.jsonl` 與 `$JSC_HOME/usage/chains.jsonl`，由 `jsc-log:stats` 聚合。 + +| 對象 | 類別 | 本輪次數 | 累計次數 | +| --- | --- | ---: | ---: | +| {技能名或呼叫鏈} | {技能、呼叫鏈 二選一} | {n} | {n} | + +### hook 執行期錯誤 + +資料出自 `jsc-hooks` 的 `tools/scan-hook-errors.sh` 與 `tools/scan-logs.sh`。助理只記錄與發動 `jsc-hooks:repair`，不自己改 hook。 + +| 發生時間 | hook | CLI | 結束碼 | 錯誤摘要 | 已寫 ERROR 頁 | +| --- | --- | --- | ---: | --- | --- | +| {yyyy-MM-dd HH:mm} | {腳本檔名} | {CLI 代號} | {n} | {一句摘要} | {ERROR_{HASH} 連結或「否」} | + +### 版本落差與重啟閘門 + +資料出自 `version-guard.sh report` 與 `restart-gate.sh report`。 + +| domain | 本機版本 | 應有版本 | 判定 | +| --- | --- | --- | --- | +| {domain} | {版本字串} | {版本字串} | {相符、落後、查不到 三選一} | + +| CLI | 重啟閘門 | 升起時間 | +| --- | --- | --- | +| {CLI 代號} | {已升起、未升起 二選一} | {yyyy-MM-dd HH:mm 或「-」} | + +### SDLC 階段鎖與工作包鎖現況 + +資料出自 `$JSC_HOME/sessions/{sid}.stage` 與 `$JSC_HOME/wp/*.pr`。只讀狀態，不做判定。 + +| 工作階段 | 階段 | 存取庫 | 登記時間 | +| --- | --- | --- | --- | +| {工作階段代號} | {plan、analyze、implement、maintain 四選一} | {owner}/{repo} | {yyyy-MM-dd HH:mm} | + +| 存取庫 | 工作包 | PR | 歸屬工作階段 | +| --- | --- | --- | --- | +| {owner}/{repo} | {WP-nn} | {PR 連結} | {工作階段代號} | + +### 待辦簿到期與逾期 + +資料出自 `$JSC_HOME/assistant/tasks/` 底下的每一個檔案，一筆一列。 + +| id | 標題 | 狀態 | 下次執行 | 到期 | 連續失敗 | 標記 | +| --- | --- | --- | --- | --- | ---: | --- | +| {id} | {title} | {pending、done、paused 三選一} | {next_run} | {due 或「-」} | {fail_count} | {已連續失敗 N 次，或「-」} | + +`fail_count` 大於 0 的列，標記欄一律寫「已連續失敗 N 次」，`N` 照檔案原值抄。待辦簿的項目失敗不會自動暫停，會每輪重試；沒標出來，一個壞掉的項目會一直重試而沒人知道。 + +### 待人處理 + +助理只提醒，不代為執行。這一節列的是本輪要人接手的項目。 + +| 項目 | 來源子節 | 建議入口 | +| --- | --- | --- | +| {一句話講完要處理什麼} | {上面六個子節之一} | {技能名或指令} | + +## 寫入規則 + +- 一次巡檢附加一節，節標題帶時間戳，節名不重複。 +- 既有的節原樣保留，一個字都不改。 +- 禁止整頁覆寫。覆寫等於把這台機器的巡檢軌跡刪掉。 +- 讀不到舊內容就中止，不附加，也不寫入。 +- 附加成功之後，才回頭更新 `MONITOR_CONTENTS` 自己那一列。