From 28f453176e6397eb7e165165b19b10beae878dd0 Mon Sep 17 00:00:00 2001 From: Jeffery Date: Fri, 4 Sep 2026 10:15:34 +0800 Subject: [PATCH] =?UTF-8?q?feat(seed):=20=E7=A8=AE=E5=85=A5=E5=85=A7?= =?UTF-8?q?=E5=BB=BA=E9=A0=85=E6=99=82=E6=94=B9=E8=AE=80=E5=A7=94=E6=B4=BE?= =?UTF-8?q?=E6=B8=85=E5=96=AE=E7=9A=84=E5=94=AF=E8=AE=80=E7=9B=A4=E9=BB=9E?= =?UTF-8?q?=E6=8C=87=E4=BB=A4=E6=AC=84?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 委派清單補上第十二欄 probe 之後，這一支不再把所有非 invoke 的列一律推成 只提醒：填了指令的四列改成把那一行指令代好代入點寫進動作欄，寫著 pending 的七列照舊只提醒但另外印出來，讓「入口還沒接上」跟「本來就只提醒」 在回報上分得開。 三個判斷刻意寫死： 一、way 含 invoke 的列連看都不看 probe。填了指令會讓整支技能的交出變成 只跑一支腳本，那支技能該寫的頁一頁都不會寫，而且看起來完全正常。 二、probe 代不進去一律退回只提醒並照樣種入。不種入在 apply 那一路等於 移除，於是上游一格填錯就會刪掉一筆帶著 last_run 與 fail_count 的內建項。 金錢符號與波浪號擋在種入這一刻，那兩種寫法在無人值守那一輪解不出來、 也進不了允許清單，會被靜靜擋掉。 三、{cli} 與 {repo} 留在值裡不展開。種入的當下還不知道要代什麼，展開成 多筆會讓同一個 spec_key 有好幾個檔案，一致化整個垮掉。展開由執行那一步 負責，而動作欄裡出現大括號就是還沒代好，一律不得原樣拿去執行。 清單只有十一欄時整份先數一次欄位數，全部照舊推成只提醒、只印一行說明， 行為與加這一欄之前一模一樣。第十三欄以後另接一個收尾變數，免得上游哪天 加一欄就把多出來的值黏進 probe，代入點檢查全過得了關、最後執行的卻是 一行誰都沒寫過的指令。 相依下限刻意不動。清單那一欄晚一步到也照常跑得完，把下限拉到有那一欄的 版本等於逼兩個存放庫排合併順序，而排順序正是這一段程式碼要免掉的事。 三份 manifest 的版號從 0.1.9 升到 0.2.0。 Co-Authored-By: Claude Opus 5 --- .claude-plugin/plugin.json | 2 +- .codex-plugin/plugin.json | 2 +- plugin.json | 2 +- references/behaviors.md | 8 +- skills/assistant/SKILL.md | 29 ++++- tools/seed-tasks.sh | 258 +++++++++++++++++++++++++++++++++---- 6 files changed, 265 insertions(+), 36 deletions(-) diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json index c9a1baf..22ccdfd 100644 --- a/.claude-plugin/plugin.json +++ b/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-assist", - "version": "0.1.9", + "version": "0.2.0", "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_{HASH} wiki 頁）", "skills": "./skills", "author": { diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json index 96df2b5..05a0410 100644 --- a/.codex-plugin/plugin.json +++ b/.codex-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-assist", - "version": "0.1.9", + "version": "0.2.0", "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_{HASH} wiki 頁）", "skills": "./skills", "jsc": { diff --git a/plugin.json b/plugin.json index d9ae51a..1e4cb51 100644 --- a/plugin.json +++ b/plugin.json @@ -1,6 +1,6 @@ { "name": "jsc-assist", - "version": "0.1.9", + "version": "0.2.0", "description": "助理：事件收攏、健康巡檢與待辦簿（MONITOR_{HASH} wiki 頁）", "skills": "./skills/", "jsc": { diff --git a/references/behaviors.md b/references/behaviors.md index b1232d5..c672292 100644 --- a/references/behaviors.md +++ b/references/behaviors.md @@ -7,7 +7,7 @@ | 項目 | 內容 | | --- | --- | | 觸發時機 | 要啟動助理、要停止助理、要跑一輪巡檢，或要問助理現在還在不在跑、待辦簿剩下哪幾筆時用。四個操作 `start`、`status`、`patrol`、`stop` 都走這一支。排程每一輪叫起來的也是這一支的 `patrol`。委派清單改過之後要讓助理的內建定期檢查項跟著重建，也走這一支的 `start`；只想知道差在哪、不要動待辦簿就走 `status`。執行環境健檢不走這支，走 `jsc-cli:doctor`。技能使用次數不走這支，走 `jsc-log:stats` | -| 關鍵步驟 | 四個操作都先跑同一個前置步驟，取得工具根目錄（本頁記成 `{CURRENT}`），根目錄一律由外面餵進來：排程那一輪從叫用文字裡的「工具根目錄=」那一段取字面絕對路徑，一個指令都不跑；人在現場叫用時，叫用文字帶那一段就取那一段，沒帶才跑一次 `readlink -f "${JSC_HOME:-$HOME/.jsc}/current"` 自己解，那一次會跳一次權限詢問，人按一下就過。無人值守那一輪取不到根目錄就停下回報：說明條目是舊版 `schedule.sh` 裝的、沒有把根目錄寫進提示文字，叫人重跑一次 `start` 或 `schedule.sh install patrol` 把條目重寫，收尾狀態取 `aborted`；一律不跑 `readlink`、不跑 `ls`、不退回帶變數的路徑、不拿技能提示或上一次轉錄裡的路徑、也不猜。整次叫用只取這一次，之後每一次腳本呼叫都填那一個字面絕對路徑，不是每一次呼叫各取一次，也不另外加印路徑的工具，更不另外跑指令去驗那一個路徑。取到的是空的、不是絕對路徑、或那條路徑不是存在的目錄，就回報根目錄不見了、叫人跑 `jsc-cli:deploy`，收尾狀態取 `aborted`；第四項要單獨查，`JSC_HOME` 沒設時 `readlink -f "$JSC_HOME/current"` 印的是 `/current`、結束碼 0，非空又是絕對路徑，前三項全過得了關，之後每一條字面路徑都指向不存在的地方，所以人在現場那一次要在同一步再跑 `[ -d "{剛印出來的路徑}" ]`，目錄存在才算取到根目錄；排程那一輪不查，它的根目錄是裝排程的人寫進條目的，根目錄不對就會在第一支腳本呼叫上失敗。除了人在現場那一次 `readlink`，任何指令列都不得出現 `$JSC_HOME`、`${JSC_HOME}` 或 `~`：權限層比對的是還沒展開的指令字面。實測歸納出兩條判準：一、無人值守時只有允許清單上的完整字面指令跑得動，沒有「預設安全的唯讀指令」這回事，連 `readlink -f "$JSC_HOME/current"`、`ls -d "$JSC_HOME/current"` 與沒有規則的 `ls -d /root/.jsc/current` 都被擋；二、路徑中段的萬用字元不匹配，版本號寫成 `*` 的快取路徑規則一樣擋，規則與指令都必須是完整字面。排程那一輪沒有人可以按同意，被擋就是停在第一支腳本，什麼都不記，心跳也寫不出來。接著認出使用者要的是哪一個操作，`patrol` 那一路全程不問人。`start`：先跑 `tools/seed-tasks.sh apply --root {CURRENT}` 把內建定期檢查項對齊委派清單（清單在 `{CURRENT}/jsc-meta/tools/delegate-spec.tsv`，根目錄一律用 `--root` 餵進去、那一支自己不解），清單上可交而待辦簿沒有的就加一筆、待辦簿有而清單上已經沒有或改成不交的就移除、`origin` 是 `user` 的一律不動、判定是 `cond` 的預設保留不種入並印出條件原文、`trigger` 或 `recur` 變了只印 `drift=` 不改那一筆；種入與重建是同一個呼叫、冪等，所以每一次 `start` 都跑，第二次跑不會重複建；結束碼 1、2、3 都是「一筆都沒動」，不中止啟動，照實記進收尾回報再往下走，4 是部分失敗、成功的那幾筆算數，一律不帶 `--force` 也不自己帶 `--allow-cond`；接著照 `patrol` 的每一步跑完一輪巡檢，第一次心跳由那一輪寫、不另外寫、跑不完就不算啟動、跑 `heartbeat.sh report` 確認 `state=fresh`、跑 `tools/schedule.sh install patrol` 裝巡檢那一筆排程、把它印的 `allow_rule=` 每一行、`patrol_root=`（條目寫進去的字面根目錄，之後每一輪都從那裡讀）、環境快照提醒與 `current` 連結缺漏的警告原樣轉給人、依結束碼選一段收尾訊息印出——排程接上、排程寫進去了但 cron 沒在跑、排程沒接上三種各一段。心跳那一筆不裝了，`install heartbeat` 一律回 6。`patrol`：跑 `tools/patrol.sh collect` 取鎖並讀五項來源（那一輪另外會自己叫一次 `tools/due.sh scan`，把待辦簿的事件偵測與到期判定寫成「待辦簿到期與逾期」那一節，技能本文一律不自己再叫一次——`scan` 會推進事件快照，同一輪叫第二次就比不出任何事件，而那一次會回報零事件、看起來完全正常；要看下一輪會判出什麼就叫 `due.sh events`，那個子命令一律唯讀）（第五項是執行狀態事件：`collect` 自己叫 `jsc-hooks/tools/report-status.sh drain` 排空，緊接著跑 `rotate`，再把非 ok 的事件與「有 start 沒有配對 end」的技能彙整成監控頁那一節；技能本文一律不自己再跑一次 `drain`）、結束碼 4 就讓開不寫任何東西、結束碼 1 與 3 照樣把這一輪寫上監控頁、`hash` 是空的就 `abort`、經 `jsc-gitea:wiki` 讀回 `MONITOR_{HASH}` 舊頁、基本資料原樣留著、最新一輪那一塊整塊換成 `latest_file`、`summary_file` 的本輪那一列擺最上面（五欄：巡檢時間、本輪判定、各項成敗、待人處理、警示來源）、舊的資料列接在下面並截到 24 列、三塊重組成整頁、寫回之前先把這一頁要放進去的每一個連結交給 `jsc-gitea/tools/link-check.sh`（結束碼 0 才整頁寫回，結束碼 1 就把 DEAD 那幾筆原樣回報並 `abort`，2、3、7 同樣 `abort`，一個連結都沒有就跳過這一次驗證並照實說明）、頁不存在（唯有結束碼 4）才用 `newpage_file` 建頁、讀不回舊頁就不寫、監控頁寫成之後跑 `gitea.sh wiki-url` 取那一頁的絕對網址並依結束碼分流（4 回步驟三重寫、5 沒有 `html_url`、7 與 8 走 `abort`，其餘非 0 也走 `abort`，網址取不到就不寫那一個區塊）、換掉 `contents_file` 那個 H2 區塊裡 `{監控頁絕對網址}` 那個佔位、換完再用 `link-check.sh` 驗那一個網址（結束碼 0 才寫那一個區塊；非 0 一律不寫，比照目錄頁結束碼 3 當成那一個區塊沒更新、這一輪照樣往下寫心跳，並把連不到的那一筆列進待人處理）、用 `jsc-gitea/tools/wiki-contents.sh upsert MONITOR 1 "MONITOR_{HASH}" {區塊檔}` 以 H2 標題（也就是內容頁頁名，取 `collect` 印的 `page=`）當鍵更新 `MONITOR_CONTENTS` 自己那一個區塊並一律帶上 `templates/monitor-contents.md` 當範本（第三個參數 `1` 是 `key-col`，只在舊頁還是 markdown 表格時用得到：舊表格第 1 欄「監控頁」持有身分，那一格是 `[MONITOR_{HASH}](網址)`，轉檔時只取文字當標題；頁面已經是條列格式時這個參數被忽略，照樣固定給 `1`）、目錄頁回 3（`CONTENTS` 存取庫沒設定）不中止這一輪，照樣往下寫心跳，並把「設 `JSC_WIKI_REPO_CONTENTS` 或 `JSC_WIKI_REPO`」列進待人處理、監控頁任一失敗或目錄頁其餘非 0 才 `abort` 且不寫心跳、跑 `tools/patrol.sh finish` 寫心跳、最後印出各項結果、本輪事件數與非 ok 事件數、非 ok 事件的明細（kind、name、status、exit、detail）、以及有 start 沒有配對 end 的那幾支技能（單獨列，那代表那一輪中止了）、兩次寫入各自的連結驗證結果（通過、無連結而跳過、或被擋下並附結束碼與 DEAD 明細）、判成警示時的警示來源與待人處理列。`status`：跑 `heartbeat.sh report` 取心跳現況、把 `state` 對映成新鮮、過期、心跳檔損壞、不存在、不自己解析心跳檔也不自己判定、從 `file=` 解出助理目錄後列出 `tasks/` 底下每一個檔案並解析 `state`、`title`、`next_run`、`fail_count`、跑 `tools/schedule.sh status` 取排程現況與週期、印成心跳、排程、待辦三塊、`fail_count` 大於 0 的列標上「已連續失敗 N 次」、心跳與排程兜起來會誤讀的四種組合各補一句話、最後跑 `tools/seed-tasks.sh plan --root {CURRENT}` 唯讀比對內建項與委派清單並印出差在哪（該加幾筆、還剩幾筆孤兒、保留的 `cond` 各是哪一支、`drift=` 各要換什麼值），一律不跑 `apply`，並說明要套用差異就跑 `start`；那一支回 1、2、3 就照實說比不出來、不說成已對齊。`stop`：先跑 `heartbeat.sh report` 留下原本的狀態、再跑 `tools/schedule.sh remove all` 移除排程與舊版遺留的心跳條目、最後才跑 `heartbeat.sh clear` 清掉心跳、印出停止訊息並說明心跳清掉之後閘門會擋人、同時說明閘門還沒接線所以現在擋不到人。四個操作最後都一樣：回報印完之後跑一次 `jsc-hooks/tools/report-status.sh skill-end jsc-assist:assistant {status} {結束碼}`，`start` 由 hook 記、`end` 由這裡寫，不寫就等於這一次自己看起來中止了 | -| 外部呼叫 | 工具一律走前置步驟取得的根目錄底下那一組不帶版本的路徑（本頁記成 `{CURRENT}`，實際填的是像 `/root/.jsc/current` 這種字面絕對路徑）：`{CURRENT}/jsc-assist/tools/patrol.sh`、`{CURRENT}/jsc-assist/tools/schedule.sh`、`{CURRENT}/jsc-assist/tools/due.sh`、`{CURRENT}/jsc-hooks/hooks/heartbeat.sh`，wiki 那一支是 `{CURRENT}/jsc-gitea/tools/gitea.sh`，目錄頁那一支是 `{CURRENT}/jsc-gitea/tools/wiki-contents.sh`，連結驗證那一支是 `{CURRENT}/jsc-gitea/tools/link-check.sh`，執行狀態事件那一支是 `{CURRENT}/jsc-hooks/tools/report-status.sh`，範本是 `{CURRENT}/jsc-assist/templates/monitor-contents.md`；`JSC_HOME` 沒設時，人在現場那一次 `readlink` 自己退回 `~/.jsc` 再解，排程那一輪則直接用條目餵進來的值，指令列上不留變數也不留波浪號；不拿技能提示給的快取基底目錄組工具路徑——權限只放行 current 那一組，快取路徑帶版本號，規則寫成萬用字元也對不上，用錯路徑會被靜靜擋掉。`jsc-hooks/hooks/heartbeat.sh` 的 `write`、`report`、`clear` 三個子命令，六個結束碼各有處置：0 往下走、1 與 3 印「助理未運行」、2 回報判不出狀態並停下、4 當成不新鮮並回報心跳檔損壞、5 是嚴重狀況要吵出來且不得回報成功、6 是呼叫寫錯要更正後重跑。`write` 只由 `tools/patrol.sh finish` 呼叫，技能自己不呼叫。本 domain 的 `tools/schedule.sh` 的 `install`、`remove`、`status` 三個子命令：`install` 會查 `{CURRENT}/jsc-assist` 與 `{CURRENT}/jsc-gitea` 兩個連結在不在、不在就警告且不代建，會把巡檢的 CLI 用 `command -v` 解成絕對路徑、把 `GITEA_HOST`、`GITEA_TOKEN`、`JSC_HOME`、`JSC_ASSISTANT_HEARTBEAT_TTL` 與所有已設定的 `JSC_WIKI_REPO` 系列快照進條目（含內容頁的 `JSC_WIKI_REPO_MONITOR` 與目錄頁的 `JSC_WIKI_REPO_CONTENTS`，名單當下從環境撈、不寫死，新頁型自動涵蓋）、條目自帶 `JSC_GITEA_CONFIRM=yes`、把自己解好的字面根目錄寫進條目的提示文字（固定格式 `工具根目錄={字面絕對路徑}`，那一輪就是從這裡讀根目錄）並印成 `patrol_root=`、`--patrol-cmd` 或 `JSC_ASSIST_PATROL_CMD` 給的自訂指令沒帶那一段時只警告不中止、並印出這一輪要開的 `allow_rule=` 規則（七支腳本各三種呼叫形式，含 `gitea.sh`、`wiki-contents.sh`、`link-check.sh` 與 `jsc-hooks/tools/report-status.sh`——`Skill(jsc-gitea:wiki)` 只放行叫用技能，技能內部的 Bash 呼叫仍各自受檢；路徑是 `current` 那一組確切路徑，不用萬用字元）；七個結束碼各有處置：0 往下走、1 是條目裝了但 cron 沒在跑要照實講不會執行、2 是缺 jsc-hooks 導致門檻讀不到、3 是這台機器沒有排程機制、4 是排程操作失敗要原樣引用 stderr、5 是回讀驗證失敗要叫人自己去看 `crontab -l`、6 是呼叫寫錯，含 `install heartbeat`、週期塞不進門檻、判不出 CLI、那一支 CLI 的執行檔不在 `PATH` 上，以及 `JSC_HOME` 解不出絕對路徑（條目寫不出字面根目錄）。本 domain 的 `tools/patrol.sh` 的 `collect`、`finish`、`abort` 三個子命令，七個結束碼各有處置：0 往下走、1 部分失敗照樣寫頁、2 是 finish 找不到 heartbeat.sh 要回報「記下來了但沒有心跳」、3 是各項全失敗照樣寫頁且判定異常、4 是讓開或鎖被搶走一律不寫心跳、5 是檔案系統失敗要吵出來、6 是呼叫寫錯。巡檢那五項讀 `jsc-log/tools/usage-stats.sh`、`jsc-hooks/hooks/version-guard.sh report`、`jsc-hooks/hooks/restart-gate.sh report`、`$JSC_HOME/sessions/*.stage`、`$JSC_HOME/wp/*.pr`、`heartbeat.sh report`、`jsc-hooks/tools/report-status.sh drain` 與 `rotate`，除了排空會把事件流的位移往前推之外全部只讀，任一項失敗不影響其餘各項。`report-status.sh` 三個結束碼各有處置：0 是排空到新事件、3 是沒有新事件（正常狀態，不是失敗）、2 是呼叫寫錯；找不到這一支、`drain` 回 0 與 3 以外的碼、或 `rotate` 回非 0，都只讓這一項標成失敗或記一筆警示，一律不中止那一輪——回報鏈自己壞掉不可以把被回報的那一輪拖下去。`rotate` 只在 `drain` 成功時緊接著跑：中間隔越久，那段時間新寫進來的事件被搬進備份檔而從此排不到的機會越大；排空失敗時位移狀態未知，這時候輪替會直接吃掉還沒排空的那一批。配對以 `session` 加 `name` 為鍵，不只看 `name`：五支 CLI 併發時同一支技能會有好幾個工作階段同時在跑。沒配對到的 `start` 留在 `$JSC_HOME/assistant/events-open.tsv` 跨輪繼續配對，開超過心跳門檻才算疑似中止，未達門檻的算還在跑，超過一天沒配對到就丟掉。wiki 讀寫一律經 `jsc-gitea:wiki`，技能自己不拼 API 呼叫；只有目錄頁那一個 H2 區塊例外，走 `jsc-gitea/tools/wiki-contents.sh upsert`，它自己解 `CONTENTS` 存取庫、自己讀回整頁比對標題，舊頁還是 markdown 表格時自己先整頁轉成 H2 區塊再寫，七個結束碼各有處置：0 已更新或已新增、1 組不出頁面內容或寫入失敗要 `abort`（找不到同名標題不算錯，那是附加）、2 參數錯就改正重跑（範本路徑不存在也回這一碼，代表 plugin 沒裝齊）、3 是 `CONTENTS` 存取庫未設定且**不中止這一輪**、4 是頁不存在又沒給範本，本技能一律帶第五個參數所以不會出現、7 金鑰失效要 `abort`、8 其他 API 失敗要 `abort`。比對鍵取 H2 標題，也就是內容頁頁名 `MONITOR_{HASH}`，不取「監控頁」那一條的連結：連結含 `GITEA_HOST` 與頁名的網址編碼，那三樣一變鍵就對不上，同一台機器每輪多附一個區塊；頁名只由 `{主機名}/{登入帳號}` 決定，那三樣都動不到它。連結一律寫成 `[{文字}]({絕對網址})`，網址只取 `gitea.sh wiki-url` 印的那一個、不自己組路徑，那一支的結束碼 4、5、7、8 與其餘非 0 各有處置；每一個要放進頁面的連結在寫入前先過 `jsc-gitea/tools/link-check.sh`，它每個網址印一行 `{OK|DEAD|SKIP}` 加網址加說明，五個結束碼各有處置：0 才准寫入、1 有連不到的就不寫並回報 DEAD 那幾筆、2 是一個網址都沒給要補參數重跑、3 是 `GITEA_HOST` 未設定要先設定且不得跳過驗證、7 是金鑰失效要停下來回報金鑰問題而不是當成死連結；驗證走 API 不看網頁狀態碼，私有存取庫的網頁網址對未登入請求一律回 404。頁名雜湊一律取 `gitea.sh hash-id`／`tools/hash-id` 印的完整 40 碼大寫十六進位，不截短、不加前綴、不手算，空輸入回 2。crontab 與 schtasks 一律經 `tools/schedule.sh`。另外唯讀 `$JSC_HOME/assistant/tasks/` 底下的檔案。待辦簿的存放格式與讀寫入口是本 domain 的 `tools/tasks.sh`：一筆一檔、純文字 key=value、十五個鍵順序固定、值是空的照樣寫出那一行，讀的時候只在第一個等號斷開，寫的時候把值折成一行，一筆一檔的理由同 `restart-required.d`（並行寫入不互相覆寫），`id` 取共用 hash 規則那四十碼的前 8 碼、碰撞時每次加長兩碼，七個子命令 `list`、`add`、`done`、`fail`、`pause`、`resume`、`remove` 與八個結束碼的完整說明寫在那一支的檔頭；第十五個鍵是 `spec_key`，值是 `jsc-{domain}:{技能名}`，那是從一支技能反查到它對應那一筆內建項的唯一把手（`id` 是建立時間加標題的雜湊、反查不了；標題與 `action` 拿來當鍵會撞上使用者交辦的那幾筆），只有 `origin=assistant` 帶得上它，`--spec-key` 配 `--origin user` 回 2，`remove` 對 `origin=user` 的那一筆一律回 7、除非人親自帶 `--force`。內建定期檢查項照委派清單種入與重建的入口是本 domain 的 `tools/seed-tasks.sh`，兩個子命令 `plan`（唯讀預覽）與 `apply`（真的做），清單路徑取 `--root` 餵進來的那一個字面絕對路徑底下的 `jsc-meta/tools/delegate-spec.tsv`；欄位對映是 `trigger` 與 `recur` 原樣抄、`spec_key` 由清單前兩欄合成、`action` 由 `way` 推（含 `invoke` 就取技能名，其餘取 `remind`，因為巡檢與提醒那兩種交出方式沒有獨立入口，填技能名會讓助理把整支技能一路跑完，那正是切片交要防的事）、`title` 固定寫成「委派清單內建項：{spec_key}」以免清單一改就換 `id`、`kind` 一律 `check`、`origin` 一律 `assistant`、`repo` 與 `due` 一律留空，清單的 `verdict`、`slice`、`human`、`next`、`version` 與它自己的 `origin` 欄一律不抄（清單的 `origin` 是 `seed` 或 `judged`，與待辦簿的 `origin` 同名不同義）；七個結束碼各有處置：0 對齊完成（零筆改動也算）、1 清單讀不到、2 清單讀到了卻解不出任何可交項目、3 找不到 `tasks.sh`，這三碼一律「一筆都沒動」且不得回報成清單上沒有可交項目，4 是部分失敗、逐筆帶 `tasks.sh` 的結束碼、成功的那幾筆算數，5 檔案系統失敗，6 呼叫寫錯（含 `--root` 不是絕對路徑、`--allow-cond` 形狀不對）。這一支只呼叫 `tasks.sh` 的 `list`、`add`、`remove` 三個子命令，一次都不自己動 `tasks/` 底下的檔案，也一次都不帶 `--force`。事件偵測與到期判定是本 domain 的 `tools/due.sh`，三個子命令 `scan`、`events`、`next`：`scan` 一輪一次，比對狀態快照算出本輪新事件、推進快照與事件計數，再逐筆判到期；`events` 是唯讀預覽，一律不推進快照；`next` 是純算，給一組欄位算出 `next_run`。七個結束碼各有處置：0 判完了、1 有狀態來源存在卻讀不到（結果照樣印得出來，那個來源本輪不發事件）、2 有待辦的欄位值判不了（其餘各筆照判）、3 快照換不上去（同一批事件下一輪會被判第二次，要吵出來）、4 待辦簿目錄不存在或零筆（不是失敗，但「沒判過」不等於「都沒到期」）、5 檔案系統失敗、6 呼叫寫錯。事件靠比對狀態快照，一個產生者的腳本都不改：工作包鎖檔轉態、`sessions/{sid}.stage` 換值、`errors/hooks.jsonl` 新增列、`sessions/{sid}.start` 與 `.end`、`worklog-pending` 暫存區清空，各對一個事件名；`analyze-completed:{HASH}` 的來源在 wiki 的分析頁上，要連網才判得出來，這一輪標成未接線並吵出來，不靜靜當成還沒發生，`cron:{式子}` 同樣未接線。快照比對有一個明確的代價：**兩輪之間發生又消失的事件會漏掉**，假設「事件不會漏」就會出錯，而那種錯是無聲的。`tasks/` 底下的檔案只有 `start` 那一步的 `seed-tasks.sh apply` 會經 `tasks.sh` 動到，`patrol`、`status`、`stop` 三個操作一律只讀：`patrol` 一次都不跑 `seed-tasks.sh`（無人值守那一輪移除一筆會把那一筆的 `last_run` 與 `fail_count` 一起弄丟，而清單同步到一半就會刪錯，破壞性清理留給人），`status` 只跑 `plan`、那個子命令一律不寫。代價要講明：沒有人 `start` 也沒有人看的機器上，清單改動要等下一次 `start` 才進得了待辦簿。`tasks.sh` 的 `done`、`fail`、`pause`、`resume` 四個子命令還沒有任何一個操作呼叫得到：登錄時的補問流程、逾期與失敗的處理行為、`remind` 怎麼送到前景、待辦簿的 wiki 雙向同步，四項都還沒接上去，所以到期的那幾筆這一輪只印出來、不執行，也不回寫 `last_run`。呼叫端沒講清楚要哪一個操作時走 `jsc-ask:ask` 的決策樹問，但 `patrol` 那一路一律不問。不參與閘門判定 | -| 完成條件 | 四個操作都要先取得工具根目錄，之後每一支腳本都拿那一個字面絕對路徑呼叫；排程那一輪只從叫用文字取，取不到就回報條目沒帶根目錄並中止，收尾狀態取 `aborted`，不得改跑 `readlink` 或任何解析指令，也不得改用帶變數的路徑硬跑；人在現場叫用時取不到才自己解一次，解出來的要是一條存在的絕對路徑（同一步用 `[ -d ]` 查過），解不出來或目錄不存在就回報缺 `current` 並中止，同樣取 `aborted`。`start` 要先跑過一次 `seed-tasks.sh apply` 並把它的結束碼、`added=`、`removed=`、`kept=`、`drift=`、`held=`、`bad=` 各數字與逐列 `held=`、`bad=`、`drift=`、`dup=`、`skip_user=` 記進收尾回報（回 1、2、3 時要寫成「內建項原樣沒動」並附原因，不得寫成「沒有可交項目」），然後要那一輪巡檢的 `finish` 回 0 且 `report` 回 `state=fresh`，才算啟動成功；巡檢沒寫成心跳一律回報失敗並停下，不得宣稱啟動；`schedule.sh install patrol` 回 1 要講明條目不會被執行與 `sudo service cron start`，不得宣稱排程會定時執行；回 0 或 1 都要把 `allow_rule=` 各行、「條目含金鑰快照、變數改了要重裝」這句提醒，以及 `current` 連結缺漏的警告轉出去。`patrol` 要五項各自有 `status`、「待辦簿到期與逾期」那一節要有逐筆判定表（`due.sh` 回 0、1、2、3、4 都算判過，其中 1、2、3 各記一筆警示與一列待人處理；回別的碼就照實寫「這一輪判不出到期」並說明那不代表沒有任何一筆到期，不留空白也不寫成「都沒到期」）、執行狀態事件那一項要印出本輪事件數、非 ok 事件數與未配對的 `start`（`drain` 回 3 是沒有新事件，照樣算這一項讀到底）、監控頁那一頁要放的連結全部通過 `link-check.sh`（或整頁本來就沒有連結）、監控頁三塊重組寫成、目錄頁那一個 H2 區塊的網址通過 `link-check.sh` 後更新成功，或以目錄頁結束碼 3、或以連結驗證非 0 回報成沒更新、`finish` 回 0，才算一輪跑完；`collect` 回 4 是讓開，不算失敗也不寫任何東西；舊頁讀不回來就不寫，回報「這一輪沒有結果」；連結驗證沒過就不寫那一頁，監控頁沒寫成就 `abort`，心跳一定不寫；目錄頁除了結束碼 3 之外的非 0 也一樣 `abort`，結束碼 3 只少一筆索引，那一輪的結果已經在監控頁上，照樣寫心跳並把缺的變數列進待人處理；目錄頁那一個區塊的連結驗不過同樣只少一筆索引，照樣寫心跳並把那一筆列進待人處理。`status` 要印出現況表，或印出「助理未運行」並說明原因，並且要多印一段內建項與委派清單的差異（該加幾筆、還剩幾筆孤兒、保留的 `cond` 各是哪一支、`drift=` 各要換什麼值，以及「要套用就跑 `start`」這句話），那一段比不出來就照實說比不出來；心跳不存在、待辦簿目錄不存在、待辦簿零筆、排程沒裝、清單讀不到，五種都算正常結束。`stop` 要 `schedule.sh remove all` 先回 0、`clear` 再回 0，並印出帶三段話的停止訊息；`remove` 非 0 就回報排程還在、助理停不掉，不清心跳也不印停止訊息；`clear` 回 5 就回報心跳檔還在、助理沒有確實停掉，不印停止訊息。四個操作都要在回報之後寫一筆 `skill-end`，`status` 取 ok、blocked、failed、degraded、aborted 五選一，要與回報出去的結果一致；那一支回非 0 只回報成回報鏈的缺陷，不改寫這一次操作的成敗 | -| 可驗證跡象 | 四個操作的轉錄裡，每一條指令列都是字面絕對路徑，開頭是 `/`，沒有 `$JSC_HOME`、`${JSC_HOME}` 或 `~`，也沒有任何一次因為路徑帶變數而跳出來的權限詢問；排程那一輪從頭到尾一次 `readlink`、一次 `ls` 都沒有，根目錄直接取自叫用文字；人在現場那一路才可能有 `readlink`，而且同一次叫用只出現一次。`start` 之後 `$JSC_HOME/assistant/heartbeat` 存在，`ts` 是剛才那一輪的時間，`crontab -l` 找得到一筆帶 `# jsc-assist:assistant patrol` 的條目，而且只有一筆，帶 `# jsc-assist:assistant heartbeat` 的舊條目一筆都不剩；那一筆條目裡的 CLI 是絕對路徑，前面帶著 `JSC_GITEA_CONFIRM=yes` 與環境變數快照，提示文字裡有「工具根目錄=」接一個字面絕對路徑，那個值與 install 印的 `patrol_root=` 和 `allow_rule=` 用的根目錄完全相同，不是變數也不是快取實體路徑；install 印出的 `allow_rule=` 都是 current 那一組展開後的字面絕對路徑，沒有變數、沒有波浪號、沒有萬用字元，也沒有 `Write(...)`，而且 `jsc-gitea/tools/link-check.sh` 與 `jsc-hooks/tools/report-status.sh` 那三種呼叫形式都在裡面。`patrol` 跑完之後 wiki 的 `MONITOR_{HASH}` 只有三塊：基本資料一字未改、最新一輪換成本輪、摘要表最上面一列是本輪且總列數不超過 24，頁名的 `{HASH}` 是 40 碼大寫十六進位，雜湊來源那一列寫的是不含網域的短主機名；`CONTENTS` 存取庫裡的 `MONITOR_CONTENTS` 只有自己那一個 H2 區塊變動，同一台機器從頭到尾只有一個區塊，標題是 `MONITOR_` 接 40 碼大寫十六進位、標題上不帶連結也不帶網址，區塊裡「監控頁」那一條是 `[{頁名}]({絕對網址})` 這種連結、點下去開得起那一頁，「HASH」那一條是裸 HASH、40 碼大寫十六進位、不帶連結，八條欄位一條都不缺、格式是 `- {欄位名}：{值}`，頁上一個 markdown 表格都不剩，兩頁上點得到的連結沒有一個是死的——把頁上的網址抓出來重跑一次 `link-check.sh`，應該全部是 `OK`、結束碼 0，別台機器的區塊一字不動，`$JSC_HOME/assistant/patrol/` 底下有本輪的 `latest.md`、`summary.md`、`summary-row.md`、`newpage.md`、`contents-entry.md`，摘要列是五欄、警示來源那一欄有值或寫「無」；兩支腳本不是從 current 那一組路徑跑起來時，stderr 會有一行 `[WARN]` 點出實際路徑與應該用的路徑，`$JSC_HOME/assistant/usage-prev.tsv` 換成本輪的累計數，`$JSC_HOME/assistant/events-prev.tsv` 換成本輪的狀態快照（三欄定位字元分隔，每一個來源另有一列 `meta`）、`$JSC_HOME/assistant/events-seen.tsv` 是每一個事件名的累計次數與最後發生時間，`$JSC_HOME/assistant/patrol/due/` 底下有本輪的 `due.md` 與 `rows.txt`（`rows.txt` 是十一欄定位字元分隔，欄位順序印在 `rows_columns=`；要逐筆取值就讀它，不要切 `task=` 那幾行，那幾行的四個欄位都可能帶空白），第一次跑那一輪的 `due.sh` 印 `first_run=1`、事件數為 0，且 `tasks/` 底下一個檔案都沒被改動，`$JSC_HOME/assistant/patrol.lock` 已經放掉；監控頁的最新一輪有「執行狀態事件」那一節，節裡有本輪事件數、非 ok 事件數，以及非 ok 明細與未配對 `start` 兩張表（一筆都沒有時寫明「沒有」，不留空表格）；`$JSC_HOME/usage/scan-state/events.offset` 的數字往前推到本輪排空的位置，`$JSC_HOME/assistant/events-open.tsv` 只剩下還沒配對到 `end` 的那幾筆。讓開的那一輪沒有任何寫入跡象。`stop` 之後心跳路徑不存在，`crontab -l` 找不到任何 `# jsc-assist:assistant` 條目。以上都不動別人的排程條目，條目數量前後相同。`status` 無寫入跡象，只有回報內容。四個操作跑完，`$JSC_HOME/usage/events.jsonl` 最後都多一筆 `name` 是 `jsc-assist:assistant`、`phase` 是 `end` 的事件，`status` 與回報出去的結果一致，而且同一個 `session` 下它與 hook 記的那一筆 `phase=start` 配得起來。`patrol`、`status`、`stop` 三個操作都不動 `tasks/` 底下的檔案；`start` 只在第一步經 `tasks.sh` 動內建項，動完之後 `tasks/` 底下每一個 `origin=user` 的檔案內容與修改時間都一字未改，`origin=assistant` 且帶 `spec_key` 的那幾筆與委派清單上非 `none`、非 `cond` 的那幾列一對一對得上（同一個 `spec_key` 只有一個檔案），`spec_key` 是空的那幾筆一筆都沒被加也沒被刪，判定是 `cond` 的那幾支在 `tasks/` 底下找不到對應檔案而回報裡逐支有一行 `held=`。四個操作都不動 worktree 與程式碼存取庫。排程的 log 一律在 `$JSC_HOME/assistant/schedule.log`，不落在任何存取庫 | +| 關鍵步驟 | 四個操作都先跑同一個前置步驟，取得工具根目錄（本頁記成 `{CURRENT}`），根目錄一律由外面餵進來：排程那一輪從叫用文字裡的「工具根目錄=」那一段取字面絕對路徑，一個指令都不跑；人在現場叫用時，叫用文字帶那一段就取那一段，沒帶才跑一次 `readlink -f "${JSC_HOME:-$HOME/.jsc}/current"` 自己解，那一次會跳一次權限詢問，人按一下就過。無人值守那一輪取不到根目錄就停下回報：說明條目是舊版 `schedule.sh` 裝的、沒有把根目錄寫進提示文字，叫人重跑一次 `start` 或 `schedule.sh install patrol` 把條目重寫，收尾狀態取 `aborted`；一律不跑 `readlink`、不跑 `ls`、不退回帶變數的路徑、不拿技能提示或上一次轉錄裡的路徑、也不猜。整次叫用只取這一次，之後每一次腳本呼叫都填那一個字面絕對路徑，不是每一次呼叫各取一次，也不另外加印路徑的工具，更不另外跑指令去驗那一個路徑。取到的是空的、不是絕對路徑、或那條路徑不是存在的目錄，就回報根目錄不見了、叫人跑 `jsc-cli:deploy`，收尾狀態取 `aborted`；第四項要單獨查，`JSC_HOME` 沒設時 `readlink -f "$JSC_HOME/current"` 印的是 `/current`、結束碼 0，非空又是絕對路徑，前三項全過得了關，之後每一條字面路徑都指向不存在的地方，所以人在現場那一次要在同一步再跑 `[ -d "{剛印出來的路徑}" ]`，目錄存在才算取到根目錄；排程那一輪不查，它的根目錄是裝排程的人寫進條目的，根目錄不對就會在第一支腳本呼叫上失敗。除了人在現場那一次 `readlink`，任何指令列都不得出現 `$JSC_HOME`、`${JSC_HOME}` 或 `~`：權限層比對的是還沒展開的指令字面。實測歸納出兩條判準：一、無人值守時只有允許清單上的完整字面指令跑得動，沒有「預設安全的唯讀指令」這回事，連 `readlink -f "$JSC_HOME/current"`、`ls -d "$JSC_HOME/current"` 與沒有規則的 `ls -d /root/.jsc/current` 都被擋；二、路徑中段的萬用字元不匹配，版本號寫成 `*` 的快取路徑規則一樣擋，規則與指令都必須是完整字面。排程那一輪沒有人可以按同意，被擋就是停在第一支腳本，什麼都不記，心跳也寫不出來。接著認出使用者要的是哪一個操作，`patrol` 那一路全程不問人。`start`：先跑 `tools/seed-tasks.sh apply --root {CURRENT}` 把內建定期檢查項對齊委派清單（清單在 `{CURRENT}/jsc-meta/tools/delegate-spec.tsv`，根目錄一律用 `--root` 餵進去、那一支自己不解），清單上可交而待辦簿沒有的就加一筆、待辦簿有而清單上已經沒有或改成不交的就移除、`origin` 是 `user` 的一律不動、判定是 `cond` 的預設保留不種入並印出條件原文、`trigger`、`recur` 或 `action` 變了只印 `drift=` 不改那一筆（上游把 `probe` 那一欄合併進來的那一輪，四筆指令型就是走這一條，要換值得人親自帶 `--refresh`）；種入與重建是同一個呼叫、冪等，所以每一次 `start` 都跑，第二次跑不會重複建；結束碼 1、2、3 都是「一筆都沒動」，不中止啟動，照實記進收尾回報再往下走，4 是部分失敗、成功的那幾筆算數，一律不帶 `--force` 也不自己帶 `--allow-cond`；接著照 `patrol` 的每一步跑完一輪巡檢，第一次心跳由那一輪寫、不另外寫、跑不完就不算啟動、跑 `heartbeat.sh report` 確認 `state=fresh`、跑 `tools/schedule.sh install patrol` 裝巡檢那一筆排程、把它印的 `allow_rule=` 每一行、`patrol_root=`（條目寫進去的字面根目錄，之後每一輪都從那裡讀）、環境快照提醒與 `current` 連結缺漏的警告原樣轉給人、依結束碼選一段收尾訊息印出——排程接上、排程寫進去了但 cron 沒在跑、排程沒接上三種各一段。心跳那一筆不裝了，`install heartbeat` 一律回 6。`patrol`：跑 `tools/patrol.sh collect` 取鎖並讀五項來源（那一輪另外會自己叫一次 `tools/due.sh scan`，把待辦簿的事件偵測與到期判定寫成「待辦簿到期與逾期」那一節，技能本文一律不自己再叫一次——`scan` 會推進事件快照，同一輪叫第二次就比不出任何事件，而那一次會回報零事件、看起來完全正常；要看下一輪會判出什麼就叫 `due.sh events`，那個子命令一律唯讀）（第五項是執行狀態事件：`collect` 自己叫 `jsc-hooks/tools/report-status.sh drain` 排空，緊接著跑 `rotate`，再把非 ok 的事件與「有 start 沒有配對 end」的技能彙整成監控頁那一節；技能本文一律不自己再跑一次 `drain`）、結束碼 4 就讓開不寫任何東西、結束碼 1 與 3 照樣把這一輪寫上監控頁、`hash` 是空的就 `abort`、經 `jsc-gitea:wiki` 讀回 `MONITOR_{HASH}` 舊頁、基本資料原樣留著、最新一輪那一塊整塊換成 `latest_file`、`summary_file` 的本輪那一列擺最上面（五欄：巡檢時間、本輪判定、各項成敗、待人處理、警示來源）、舊的資料列接在下面並截到 24 列、三塊重組成整頁、寫回之前先把這一頁要放進去的每一個連結交給 `jsc-gitea/tools/link-check.sh`（結束碼 0 才整頁寫回，結束碼 1 就把 DEAD 那幾筆原樣回報並 `abort`，2、3、7 同樣 `abort`，一個連結都沒有就跳過這一次驗證並照實說明）、頁不存在（唯有結束碼 4）才用 `newpage_file` 建頁、讀不回舊頁就不寫、監控頁寫成之後跑 `gitea.sh wiki-url` 取那一頁的絕對網址並依結束碼分流（4 回步驟三重寫、5 沒有 `html_url`、7 與 8 走 `abort`，其餘非 0 也走 `abort`，網址取不到就不寫那一個區塊）、換掉 `contents_file` 那個 H2 區塊裡 `{監控頁絕對網址}` 那個佔位、換完再用 `link-check.sh` 驗那一個網址（結束碼 0 才寫那一個區塊；非 0 一律不寫，比照目錄頁結束碼 3 當成那一個區塊沒更新、這一輪照樣往下寫心跳，並把連不到的那一筆列進待人處理）、用 `jsc-gitea/tools/wiki-contents.sh upsert MONITOR 1 "MONITOR_{HASH}" {區塊檔}` 以 H2 標題（也就是內容頁頁名，取 `collect` 印的 `page=`）當鍵更新 `MONITOR_CONTENTS` 自己那一個區塊並一律帶上 `templates/monitor-contents.md` 當範本（第三個參數 `1` 是 `key-col`，只在舊頁還是 markdown 表格時用得到：舊表格第 1 欄「監控頁」持有身分，那一格是 `[MONITOR_{HASH}](網址)`，轉檔時只取文字當標題；頁面已經是條列格式時這個參數被忽略，照樣固定給 `1`）、目錄頁回 3（`CONTENTS` 存取庫沒設定）不中止這一輪，照樣往下寫心跳，並把「設 `JSC_WIKI_REPO_CONTENTS` 或 `JSC_WIKI_REPO`」列進待人處理、監控頁任一失敗或目錄頁其餘非 0 才 `abort` 且不寫心跳、跑 `tools/patrol.sh finish` 寫心跳、最後印出各項結果、本輪事件數與非 ok 事件數、非 ok 事件的明細（kind、name、status、exit、detail）、以及有 start 沒有配對 end 的那幾支技能（單獨列，那代表那一輪中止了）、兩次寫入各自的連結驗證結果（通過、無連結而跳過、或被擋下並附結束碼與 DEAD 明細）、判成警示時的警示來源與待人處理列。`status`：跑 `heartbeat.sh report` 取心跳現況、把 `state` 對映成新鮮、過期、心跳檔損壞、不存在、不自己解析心跳檔也不自己判定、從 `file=` 解出助理目錄後列出 `tasks/` 底下每一個檔案並解析 `state`、`title`、`next_run`、`fail_count`、跑 `tools/schedule.sh status` 取排程現況與週期、印成心跳、排程、待辦三塊、`fail_count` 大於 0 的列標上「已連續失敗 N 次」、心跳與排程兜起來會誤讀的四種組合各補一句話、最後跑 `tools/seed-tasks.sh plan --root {CURRENT}` 唯讀比對內建項與委派清單並印出差在哪（該加幾筆、還剩幾筆孤兒、保留的 `cond` 各是哪一支、`drift=` 各要換什麼值），一律不跑 `apply`，並說明要套用差異就跑 `start`；那一支回 1、2、3 就照實說比不出來、不說成已對齊。`stop`：先跑 `heartbeat.sh report` 留下原本的狀態、再跑 `tools/schedule.sh remove all` 移除排程與舊版遺留的心跳條目、最後才跑 `heartbeat.sh clear` 清掉心跳、印出停止訊息並說明心跳清掉之後閘門會擋人、同時說明閘門還沒接線所以現在擋不到人。四個操作最後都一樣：回報印完之後跑一次 `jsc-hooks/tools/report-status.sh skill-end jsc-assist:assistant {status} {結束碼}`，`start` 由 hook 記、`end` 由這裡寫，不寫就等於這一次自己看起來中止了 | +| 外部呼叫 | 工具一律走前置步驟取得的根目錄底下那一組不帶版本的路徑（本頁記成 `{CURRENT}`，實際填的是像 `/root/.jsc/current` 這種字面絕對路徑）：`{CURRENT}/jsc-assist/tools/patrol.sh`、`{CURRENT}/jsc-assist/tools/schedule.sh`、`{CURRENT}/jsc-assist/tools/due.sh`、`{CURRENT}/jsc-hooks/hooks/heartbeat.sh`，wiki 那一支是 `{CURRENT}/jsc-gitea/tools/gitea.sh`，目錄頁那一支是 `{CURRENT}/jsc-gitea/tools/wiki-contents.sh`，連結驗證那一支是 `{CURRENT}/jsc-gitea/tools/link-check.sh`，執行狀態事件那一支是 `{CURRENT}/jsc-hooks/tools/report-status.sh`，範本是 `{CURRENT}/jsc-assist/templates/monitor-contents.md`；`JSC_HOME` 沒設時，人在現場那一次 `readlink` 自己退回 `~/.jsc` 再解，排程那一輪則直接用條目餵進來的值，指令列上不留變數也不留波浪號；不拿技能提示給的快取基底目錄組工具路徑——權限只放行 current 那一組，快取路徑帶版本號，規則寫成萬用字元也對不上，用錯路徑會被靜靜擋掉。`jsc-hooks/hooks/heartbeat.sh` 的 `write`、`report`、`clear` 三個子命令，六個結束碼各有處置：0 往下走、1 與 3 印「助理未運行」、2 回報判不出狀態並停下、4 當成不新鮮並回報心跳檔損壞、5 是嚴重狀況要吵出來且不得回報成功、6 是呼叫寫錯要更正後重跑。`write` 只由 `tools/patrol.sh finish` 呼叫，技能自己不呼叫。本 domain 的 `tools/schedule.sh` 的 `install`、`remove`、`status` 三個子命令：`install` 會查 `{CURRENT}/jsc-assist` 與 `{CURRENT}/jsc-gitea` 兩個連結在不在、不在就警告且不代建，會把巡檢的 CLI 用 `command -v` 解成絕對路徑、把 `GITEA_HOST`、`GITEA_TOKEN`、`JSC_HOME`、`JSC_ASSISTANT_HEARTBEAT_TTL` 與所有已設定的 `JSC_WIKI_REPO` 系列快照進條目（含內容頁的 `JSC_WIKI_REPO_MONITOR` 與目錄頁的 `JSC_WIKI_REPO_CONTENTS`，名單當下從環境撈、不寫死，新頁型自動涵蓋）、條目自帶 `JSC_GITEA_CONFIRM=yes`、把自己解好的字面根目錄寫進條目的提示文字（固定格式 `工具根目錄={字面絕對路徑}`，那一輪就是從這裡讀根目錄）並印成 `patrol_root=`、`--patrol-cmd` 或 `JSC_ASSIST_PATROL_CMD` 給的自訂指令沒帶那一段時只警告不中止、並印出這一輪要開的 `allow_rule=` 規則（七支腳本各三種呼叫形式，含 `gitea.sh`、`wiki-contents.sh`、`link-check.sh` 與 `jsc-hooks/tools/report-status.sh`——`Skill(jsc-gitea:wiki)` 只放行叫用技能，技能內部的 Bash 呼叫仍各自受檢；路徑是 `current` 那一組確切路徑，不用萬用字元）；七個結束碼各有處置：0 往下走、1 是條目裝了但 cron 沒在跑要照實講不會執行、2 是缺 jsc-hooks 導致門檻讀不到、3 是這台機器沒有排程機制、4 是排程操作失敗要原樣引用 stderr、5 是回讀驗證失敗要叫人自己去看 `crontab -l`、6 是呼叫寫錯，含 `install heartbeat`、週期塞不進門檻、判不出 CLI、那一支 CLI 的執行檔不在 `PATH` 上，以及 `JSC_HOME` 解不出絕對路徑（條目寫不出字面根目錄）。本 domain 的 `tools/patrol.sh` 的 `collect`、`finish`、`abort` 三個子命令，七個結束碼各有處置：0 往下走、1 部分失敗照樣寫頁、2 是 finish 找不到 heartbeat.sh 要回報「記下來了但沒有心跳」、3 是各項全失敗照樣寫頁且判定異常、4 是讓開或鎖被搶走一律不寫心跳、5 是檔案系統失敗要吵出來、6 是呼叫寫錯。巡檢那五項讀 `jsc-log/tools/usage-stats.sh`、`jsc-hooks/hooks/version-guard.sh report`、`jsc-hooks/hooks/restart-gate.sh report`、`$JSC_HOME/sessions/*.stage`、`$JSC_HOME/wp/*.pr`、`heartbeat.sh report`、`jsc-hooks/tools/report-status.sh drain` 與 `rotate`，除了排空會把事件流的位移往前推之外全部只讀，任一項失敗不影響其餘各項。`report-status.sh` 三個結束碼各有處置：0 是排空到新事件、3 是沒有新事件（正常狀態，不是失敗）、2 是呼叫寫錯；找不到這一支、`drain` 回 0 與 3 以外的碼、或 `rotate` 回非 0，都只讓這一項標成失敗或記一筆警示，一律不中止那一輪——回報鏈自己壞掉不可以把被回報的那一輪拖下去。`rotate` 只在 `drain` 成功時緊接著跑：中間隔越久，那段時間新寫進來的事件被搬進備份檔而從此排不到的機會越大；排空失敗時位移狀態未知，這時候輪替會直接吃掉還沒排空的那一批。配對以 `session` 加 `name` 為鍵，不只看 `name`：五支 CLI 併發時同一支技能會有好幾個工作階段同時在跑。沒配對到的 `start` 留在 `$JSC_HOME/assistant/events-open.tsv` 跨輪繼續配對，開超過心跳門檻才算疑似中止，未達門檻的算還在跑，超過一天沒配對到就丟掉。wiki 讀寫一律經 `jsc-gitea:wiki`，技能自己不拼 API 呼叫；只有目錄頁那一個 H2 區塊例外，走 `jsc-gitea/tools/wiki-contents.sh upsert`，它自己解 `CONTENTS` 存取庫、自己讀回整頁比對標題，舊頁還是 markdown 表格時自己先整頁轉成 H2 區塊再寫，七個結束碼各有處置：0 已更新或已新增、1 組不出頁面內容或寫入失敗要 `abort`（找不到同名標題不算錯，那是附加）、2 參數錯就改正重跑（範本路徑不存在也回這一碼，代表 plugin 沒裝齊）、3 是 `CONTENTS` 存取庫未設定且**不中止這一輪**、4 是頁不存在又沒給範本，本技能一律帶第五個參數所以不會出現、7 金鑰失效要 `abort`、8 其他 API 失敗要 `abort`。比對鍵取 H2 標題，也就是內容頁頁名 `MONITOR_{HASH}`，不取「監控頁」那一條的連結：連結含 `GITEA_HOST` 與頁名的網址編碼，那三樣一變鍵就對不上，同一台機器每輪多附一個區塊；頁名只由 `{主機名}/{登入帳號}` 決定，那三樣都動不到它。連結一律寫成 `[{文字}]({絕對網址})`，網址只取 `gitea.sh wiki-url` 印的那一個、不自己組路徑，那一支的結束碼 4、5、7、8 與其餘非 0 各有處置；每一個要放進頁面的連結在寫入前先過 `jsc-gitea/tools/link-check.sh`，它每個網址印一行 `{OK|DEAD|SKIP}` 加網址加說明，五個結束碼各有處置：0 才准寫入、1 有連不到的就不寫並回報 DEAD 那幾筆、2 是一個網址都沒給要補參數重跑、3 是 `GITEA_HOST` 未設定要先設定且不得跳過驗證、7 是金鑰失效要停下來回報金鑰問題而不是當成死連結；驗證走 API 不看網頁狀態碼，私有存取庫的網頁網址對未登入請求一律回 404。頁名雜湊一律取 `gitea.sh hash-id`／`tools/hash-id` 印的完整 40 碼大寫十六進位，不截短、不加前綴、不手算，空輸入回 2。crontab 與 schtasks 一律經 `tools/schedule.sh`。另外唯讀 `$JSC_HOME/assistant/tasks/` 底下的檔案。待辦簿的存放格式與讀寫入口是本 domain 的 `tools/tasks.sh`：一筆一檔、純文字 key=value、十五個鍵順序固定、值是空的照樣寫出那一行，讀的時候只在第一個等號斷開，寫的時候把值折成一行，一筆一檔的理由同 `restart-required.d`（並行寫入不互相覆寫），`id` 取共用 hash 規則那四十碼的前 8 碼、碰撞時每次加長兩碼，七個子命令 `list`、`add`、`done`、`fail`、`pause`、`resume`、`remove` 與八個結束碼的完整說明寫在那一支的檔頭；第十五個鍵是 `spec_key`，值是 `jsc-{domain}:{技能名}`，那是從一支技能反查到它對應那一筆內建項的唯一把手（`id` 是建立時間加標題的雜湊、反查不了；標題與 `action` 拿來當鍵會撞上使用者交辦的那幾筆），只有 `origin=assistant` 帶得上它，`--spec-key` 配 `--origin user` 回 2，`remove` 對 `origin=user` 的那一筆一律回 7、除非人親自帶 `--force`。內建定期檢查項照委派清單種入與重建的入口是本 domain 的 `tools/seed-tasks.sh`，兩個子命令 `plan`（唯讀預覽）與 `apply`（真的做），清單路徑取 `--root` 餵進來的那一個字面絕對路徑底下的 `jsc-meta/tools/delegate-spec.tsv`；欄位對映是 `trigger` 與 `recur` 原樣抄、`spec_key` 由清單前兩欄合成、`action` 由 `way` 與第十二欄 `probe` 一起推、`title` 固定寫成「委派清單內建項：{spec_key}」以免清單一改就換 `id`、`kind` 一律 `check`、`origin` 一律 `assistant`、`repo` 與 `due` 一律留空，清單的 `verdict`、`slice`、`human`、`next`、`version` 與它自己的 `origin` 欄一律不抄（清單的 `origin` 是 `seed` 或 `judged`，與待辦簿的 `origin` 同名不同義）；`action` 那一欄的推法分兩路：`way` 含 `invoke` 就取技能名、`probe` 連看都不看（填了指令會讓整支交出變成只跑一支腳本，那支技能該寫的頁一頁都不會寫，所以那是清單填錯，照 `way` 取技能名並印一行 `probe_bad=`），其餘那幾種交出方式照 `probe` 走——一行指令就取那一行指令、`pending:{理由}` 取 `remind` 並印一行 `pending=`、減號或空的取 `remind`；`probe` 代不進去一律退回 `remind` 並印一行 `probe_bad=`，照樣種入那一筆，涵蓋路徑不是 `{root}/jsc-{domain}/` 開頭、指令裡有金錢符號或波浪號、出現三個代入點以外的大括號、代不出根目錄、代出來的腳本不在這台機器上五種（不種入等於讓上游一格填錯把一筆帶著 `last_run` 與 `fail_count` 的內建項刪掉）；`{root}` 由這一支代成 `--root` 給的字面絕對根目錄（沒給就從清單位置往上推三層），那一層的目錄名以 `jsc-{domain}` 為準、找不到才退回不帶前綴的 `{domain}`，而 `{cli}` 與 `{repo}` 刻意留在值裡不展開——那兩件事種入的當下還不知道，種入時展開成多筆會讓同一個 `spec_key` 有好幾個檔案、一致化每一輪只印 `dup=`，而且 CLI 或存取庫一變就要移除再重新登錄、歷史跟著歸零；**`action` 裡出現大括號就是還沒代好的代入點，任何讀取端一律不得原樣拿去執行**，展開由往後接上來的執行那一步負責，`{cli}` 換成每一支偵測到的 CLI 代號、`{repo}` 換成每一個掃到的存取庫工作目錄，一個目標跑一次，所有目標的結果合起來算這一筆的一次成敗；`pending` 的那幾筆只印在回報裡、待辦檔上一個字都不加（寫進標題會換 `id` 又比不出漂移，另立欄位要動待辦簿那十五個固定的鍵，而理由是清單上會變的散文，抄進去就是抄一份改不掉的舊值）；清單只有十一欄、也就是還沒有 `probe` 那一欄時，全部照 `way` 推 `action`、行為與加上那一欄之前一模一樣，只印一行 note 講明整份清單沒有那一欄，不逐列印警告；七個結束碼各有處置：0 對齊完成（零筆改動也算）、1 清單讀不到、2 清單讀到了卻解不出任何可交項目、3 找不到 `tasks.sh`，這三碼一律「一筆都沒動」且不得回報成清單上沒有可交項目，4 是部分失敗、逐筆帶 `tasks.sh` 的結束碼、成功的那幾筆算數，5 檔案系統失敗，6 呼叫寫錯（含 `--root` 不是絕對路徑、`--allow-cond` 形狀不對）。這一支只呼叫 `tasks.sh` 的 `list`、`add`、`remove` 三個子命令，一次都不自己動 `tasks/` 底下的檔案，也一次都不帶 `--force`。事件偵測與到期判定是本 domain 的 `tools/due.sh`，三個子命令 `scan`、`events`、`next`：`scan` 一輪一次，比對狀態快照算出本輪新事件、推進快照與事件計數，再逐筆判到期；`events` 是唯讀預覽，一律不推進快照；`next` 是純算，給一組欄位算出 `next_run`。七個結束碼各有處置：0 判完了、1 有狀態來源存在卻讀不到（結果照樣印得出來，那個來源本輪不發事件）、2 有待辦的欄位值判不了（其餘各筆照判）、3 快照換不上去（同一批事件下一輪會被判第二次，要吵出來）、4 待辦簿目錄不存在或零筆（不是失敗，但「沒判過」不等於「都沒到期」）、5 檔案系統失敗、6 呼叫寫錯。事件靠比對狀態快照，一個產生者的腳本都不改：工作包鎖檔轉態、`sessions/{sid}.stage` 換值、`errors/hooks.jsonl` 新增列、`sessions/{sid}.start` 與 `.end`、`worklog-pending` 暫存區清空，各對一個事件名；`analyze-completed:{HASH}` 的來源在 wiki 的分析頁上，要連網才判得出來，這一輪標成未接線並吵出來，不靜靜當成還沒發生，`cron:{式子}` 同樣未接線。快照比對有一個明確的代價：**兩輪之間發生又消失的事件會漏掉**，假設「事件不會漏」就會出錯，而那種錯是無聲的。`tasks/` 底下的檔案只有 `start` 那一步的 `seed-tasks.sh apply` 會經 `tasks.sh` 動到，`patrol`、`status`、`stop` 三個操作一律只讀：`patrol` 一次都不跑 `seed-tasks.sh`（無人值守那一輪移除一筆會把那一筆的 `last_run` 與 `fail_count` 一起弄丟，而清單同步到一半就會刪錯，破壞性清理留給人），`status` 只跑 `plan`、那個子命令一律不寫。代價要講明：沒有人 `start` 也沒有人看的機器上，清單改動要等下一次 `start` 才進得了待辦簿。`tasks.sh` 的 `done`、`fail`、`pause`、`resume` 四個子命令還沒有任何一個操作呼叫得到：登錄時的補問流程、逾期與失敗的處理行為、`remind` 怎麼送到前景、待辦簿的 wiki 雙向同步，四項都還沒接上去，所以到期的那幾筆這一輪只印出來、不執行，也不回寫 `last_run`；執行那一步接上來的時候，代入點的展開歸它負責——`action` 帶大括號的那幾筆要先把 `{cli}` 換成每一支偵測到的 CLI 代號、`{repo}` 換成每一個掃到的存取庫工作目錄，一個目標跑一次，代不出目標就當這一筆這一輪沒得跑並回報，一律不得把帶大括號的字面值原樣送進殼。呼叫端沒講清楚要哪一個操作時走 `jsc-ask:ask` 的決策樹問，但 `patrol` 那一路一律不問。不參與閘門判定 | +| 完成條件 | 四個操作都要先取得工具根目錄，之後每一支腳本都拿那一個字面絕對路徑呼叫；排程那一輪只從叫用文字取，取不到就回報條目沒帶根目錄並中止，收尾狀態取 `aborted`，不得改跑 `readlink` 或任何解析指令，也不得改用帶變數的路徑硬跑；人在現場叫用時取不到才自己解一次，解出來的要是一條存在的絕對路徑（同一步用 `[ -d ]` 查過），解不出來或目錄不存在就回報缺 `current` 並中止，同樣取 `aborted`。`start` 要先跑過一次 `seed-tasks.sh apply` 並把它的結束碼、`added=`、`removed=`、`kept=`、`drift=`、`held=`、`bad=`、`probe=`、`pending=`、`probe_bad=` 各數字與逐列 `held=`、`bad=`、`drift=`、`dup=`、`skip_user=`、`probe=`、`pending=`、`probe_bad=` 記進收尾回報（`pending=` 那幾筆要寫成「有唯讀盤點入口、還沒接上」並附清單上的理由原文，不得跟本來就只提醒的那幾筆混成一句；`probe=` 那幾筆的 `holes=` 不是減號時要寫明還留著哪幾個代入點）（回 1、2、3 時要寫成「內建項原樣沒動」並附原因，不得寫成「沒有可交項目」），然後要那一輪巡檢的 `finish` 回 0 且 `report` 回 `state=fresh`，才算啟動成功；巡檢沒寫成心跳一律回報失敗並停下，不得宣稱啟動；`schedule.sh install patrol` 回 1 要講明條目不會被執行與 `sudo service cron start`，不得宣稱排程會定時執行；回 0 或 1 都要把 `allow_rule=` 各行、「條目含金鑰快照、變數改了要重裝」這句提醒，以及 `current` 連結缺漏的警告轉出去。`patrol` 要五項各自有 `status`、「待辦簿到期與逾期」那一節要有逐筆判定表（`due.sh` 回 0、1、2、3、4 都算判過，其中 1、2、3 各記一筆警示與一列待人處理；回別的碼就照實寫「這一輪判不出到期」並說明那不代表沒有任何一筆到期，不留空白也不寫成「都沒到期」）、執行狀態事件那一項要印出本輪事件數、非 ok 事件數與未配對的 `start`（`drain` 回 3 是沒有新事件，照樣算這一項讀到底）、監控頁那一頁要放的連結全部通過 `link-check.sh`（或整頁本來就沒有連結）、監控頁三塊重組寫成、目錄頁那一個 H2 區塊的網址通過 `link-check.sh` 後更新成功，或以目錄頁結束碼 3、或以連結驗證非 0 回報成沒更新、`finish` 回 0，才算一輪跑完；`collect` 回 4 是讓開，不算失敗也不寫任何東西；舊頁讀不回來就不寫，回報「這一輪沒有結果」；連結驗證沒過就不寫那一頁，監控頁沒寫成就 `abort`，心跳一定不寫；目錄頁除了結束碼 3 之外的非 0 也一樣 `abort`，結束碼 3 只少一筆索引，那一輪的結果已經在監控頁上，照樣寫心跳並把缺的變數列進待人處理；目錄頁那一個區塊的連結驗不過同樣只少一筆索引，照樣寫心跳並把那一筆列進待人處理。`status` 要印出現況表，或印出「助理未運行」並說明原因，並且要多印一段內建項與委派清單的差異（該加幾筆、還剩幾筆孤兒、保留的 `cond` 各是哪一支、`drift=` 各要換什麼值，以及「要套用就跑 `start`」這句話），那一段比不出來就照實說比不出來；心跳不存在、待辦簿目錄不存在、待辦簿零筆、排程沒裝、清單讀不到，五種都算正常結束。`stop` 要 `schedule.sh remove all` 先回 0、`clear` 再回 0，並印出帶三段話的停止訊息；`remove` 非 0 就回報排程還在、助理停不掉，不清心跳也不印停止訊息；`clear` 回 5 就回報心跳檔還在、助理沒有確實停掉，不印停止訊息。四個操作都要在回報之後寫一筆 `skill-end`，`status` 取 ok、blocked、failed、degraded、aborted 五選一，要與回報出去的結果一致；那一支回非 0 只回報成回報鏈的缺陷，不改寫這一次操作的成敗 | +| 可驗證跡象 | 四個操作的轉錄裡，每一條指令列都是字面絕對路徑，開頭是 `/`，沒有 `$JSC_HOME`、`${JSC_HOME}` 或 `~`，也沒有任何一次因為路徑帶變數而跳出來的權限詢問；排程那一輪從頭到尾一次 `readlink`、一次 `ls` 都沒有，根目錄直接取自叫用文字；人在現場那一路才可能有 `readlink`，而且同一次叫用只出現一次。`start` 之後 `$JSC_HOME/assistant/heartbeat` 存在，`ts` 是剛才那一輪的時間，`crontab -l` 找得到一筆帶 `# jsc-assist:assistant patrol` 的條目，而且只有一筆，帶 `# jsc-assist:assistant heartbeat` 的舊條目一筆都不剩；那一筆條目裡的 CLI 是絕對路徑，前面帶著 `JSC_GITEA_CONFIRM=yes` 與環境變數快照，提示文字裡有「工具根目錄=」接一個字面絕對路徑，那個值與 install 印的 `patrol_root=` 和 `allow_rule=` 用的根目錄完全相同，不是變數也不是快取實體路徑；install 印出的 `allow_rule=` 都是 current 那一組展開後的字面絕對路徑，沒有變數、沒有波浪號、沒有萬用字元，也沒有 `Write(...)`，而且 `jsc-gitea/tools/link-check.sh` 與 `jsc-hooks/tools/report-status.sh` 那三種呼叫形式都在裡面。`patrol` 跑完之後 wiki 的 `MONITOR_{HASH}` 只有三塊：基本資料一字未改、最新一輪換成本輪、摘要表最上面一列是本輪且總列數不超過 24，頁名的 `{HASH}` 是 40 碼大寫十六進位，雜湊來源那一列寫的是不含網域的短主機名；`CONTENTS` 存取庫裡的 `MONITOR_CONTENTS` 只有自己那一個 H2 區塊變動，同一台機器從頭到尾只有一個區塊，標題是 `MONITOR_` 接 40 碼大寫十六進位、標題上不帶連結也不帶網址，區塊裡「監控頁」那一條是 `[{頁名}]({絕對網址})` 這種連結、點下去開得起那一頁，「HASH」那一條是裸 HASH、40 碼大寫十六進位、不帶連結，八條欄位一條都不缺、格式是 `- {欄位名}：{值}`，頁上一個 markdown 表格都不剩，兩頁上點得到的連結沒有一個是死的——把頁上的網址抓出來重跑一次 `link-check.sh`，應該全部是 `OK`、結束碼 0，別台機器的區塊一字不動，`$JSC_HOME/assistant/patrol/` 底下有本輪的 `latest.md`、`summary.md`、`summary-row.md`、`newpage.md`、`contents-entry.md`，摘要列是五欄、警示來源那一欄有值或寫「無」；兩支腳本不是從 current 那一組路徑跑起來時，stderr 會有一行 `[WARN]` 點出實際路徑與應該用的路徑，`$JSC_HOME/assistant/usage-prev.tsv` 換成本輪的累計數，`$JSC_HOME/assistant/events-prev.tsv` 換成本輪的狀態快照（三欄定位字元分隔，每一個來源另有一列 `meta`）、`$JSC_HOME/assistant/events-seen.tsv` 是每一個事件名的累計次數與最後發生時間，`$JSC_HOME/assistant/patrol/due/` 底下有本輪的 `due.md` 與 `rows.txt`（`rows.txt` 是十一欄定位字元分隔，欄位順序印在 `rows_columns=`；要逐筆取值就讀它，不要切 `task=` 那幾行，那幾行的四個欄位都可能帶空白），第一次跑那一輪的 `due.sh` 印 `first_run=1`、事件數為 0，且 `tasks/` 底下一個檔案都沒被改動，`$JSC_HOME/assistant/patrol.lock` 已經放掉；監控頁的最新一輪有「執行狀態事件」那一節，節裡有本輪事件數、非 ok 事件數，以及非 ok 明細與未配對 `start` 兩張表（一筆都沒有時寫明「沒有」，不留空表格）；`$JSC_HOME/usage/scan-state/events.offset` 的數字往前推到本輪排空的位置，`$JSC_HOME/assistant/events-open.tsv` 只剩下還沒配對到 `end` 的那幾筆。讓開的那一輪沒有任何寫入跡象。`stop` 之後心跳路徑不存在，`crontab -l` 找不到任何 `# jsc-assist:assistant` 條目。以上都不動別人的排程條目，條目數量前後相同。`status` 無寫入跡象，只有回報內容。四個操作跑完，`$JSC_HOME/usage/events.jsonl` 最後都多一筆 `name` 是 `jsc-assist:assistant`、`phase` 是 `end` 的事件，`status` 與回報出去的結果一致，而且同一個 `session` 下它與 hook 記的那一筆 `phase=start` 配得起來。`patrol`、`status`、`stop` 三個操作都不動 `tasks/` 底下的檔案；`start` 只在第一步經 `tasks.sh` 動內建項，動完之後 `tasks/` 底下每一個 `origin=user` 的檔案內容與修改時間都一字未改，`origin=assistant` 且帶 `spec_key` 的那幾筆與委派清單上非 `none`、非 `cond` 的那幾列一對一對得上（同一個 `spec_key` 只有一個檔案），`spec_key` 是空的那幾筆一筆都沒被加也沒被刪，判定是 `cond` 的那幾支在 `tasks/` 底下找不到對應檔案而回報裡逐支有一行 `held=`；`way` 只有 `patrol` 或 `remind`、而 `probe` 是一行指令的那幾筆，`action=` 那一行是完整字面絕對指令，開頭是 `/` 或一個大寫環境變數指派，路徑中段沒有版本號、沒有金錢符號、沒有波浪號，代入點只可能剩 `{cli}` 或 `{repo}`，而且那幾行在回報裡各有一行 `probe=` 對得上；`probe` 是 `pending:` 的那幾筆 `action=remind`、待辦檔上看不出跟本來就只提醒的那幾筆有什麼不同，差別只在回報裡的 `pending=` 那幾行；清單只有十一欄時 `probe=`、`pending=`、`probe_bad=` 三個數字全是 0，而且 stderr 有一行 note 講明那一份清單沒有第十二欄。四個操作都不動 worktree 與程式碼存取庫。排程的 log 一律在 `$JSC_HOME/assistant/schedule.log`，不落在任何存取庫 | diff --git a/skills/assistant/SKILL.md b/skills/assistant/SKILL.md index 5aeb4c6..7ca5234 100644 --- a/skills/assistant/SKILL.md +++ b/skills/assistant/SKILL.md @@ -132,7 +132,7 @@ The call never changes the outcome: it returns 0 even when it cannot write, and | `$JSC_HOME/assistant/heartbeat` | `heartbeat.sh` only, never this skill | `key=value` lines: `ts`, `pid`, `cli`, `session` | | `$JSC_HOME/assistant/schedule.log` | nobody here — the scheduled entry appends to it | free text; point the operator at it when a scheduled round misbehaves | | `$JSC_HOME/assistant/tasks/{id}` | this skill reads it directly; every write goes through `tasks.sh` | `key=value` lines, one task per file: `id`, `created`, `kind` (`check` / `todo`), `title`, `action`, `trigger`, `recur`, `repo`, `due`, `state` (`pending` / `done` / `paused`), `last_run`, `next_run`, `fail_count`, `origin` (`user` / `assistant`), `spec_key` (`jsc-{domain}:{skill}` for a built-in item, empty for anything a person asked for) | -| `{CURRENT}/jsc-meta/tools/delegate-spec.tsv` | `seed-tasks.sh` only, read-only | the delegation list, tab-separated, one skill per row. `verdict`, `way`, `trigger` and `recur` are what decide whether a skill gets a built-in check item and on what schedule | +| `{CURRENT}/jsc-meta/tools/delegate-spec.tsv` | `seed-tasks.sh` only, read-only | the delegation list, tab-separated, one skill per row. `verdict`, `way`, `trigger` and `recur` decide whether a skill gets a built-in check item and on what schedule; column 12, `probe`, decides what that item's `action` actually is — a one-line read-only command, `pending:{reason}` for a slice whose entry point is not wired yet, or `-` for a row that has none. A list with only 11 columns predates that column and is handled as if every row said `-` | | `$JSC_HOME/assistant/patrol.lock/` | `patrol.sh` only | the round lock, a directory. `info` holds `round`, `pid`, `started` | | `$JSC_HOME/assistant/patrol/` | `patrol.sh` only | one round's scratch files, including `latest.md`, `summary.md`, `summary-row.md`, `newpage.md` and `contents-entry.md` | | `$JSC_HOME/assistant/usage-prev.tsv` | `patrol.sh` only | last recorded round's cumulative usage counts, so the next round can print a real per-round delta | @@ -243,6 +243,25 @@ The delegation list holds one row per jsc skill and records whether that skill c | The row is still delegable but its `trigger`, `recur` or `way` changed | report it as `drift=` and change nothing, unless `--refresh` was passed | | The row's `verdict` is `cond` | hold it: seed nothing, print a `held=` line carrying the condition text, unless `--allow-cond {key}` named that row | +## What a built-in item actually does, and the `probe` column + +`way` decides the shape of the entry's `action`, and column 12 `probe` decides the rest of it: + +| `way` | `probe` | `action` | Also printed | +| --- | --- | --- | --- | +| contains `invoke` | ignored entirely | the skill name | a `probe_bad=` line if `probe` held a command — the list's own header says an `invoke` row carries `-`, and honouring a command there would turn a whole delegated skill into one script call that writes none of the pages that skill exists to write, while looking perfectly healthy | +| `patrol`, `remind`, `patrol,remind` | a one-line command | that command, substituted | a `probe=` line with the command and its remaining holes | +| `patrol`, `remind`, `patrol,remind` | `pending:{reason}` | `remind` | a `pending=` line carrying the reason verbatim | +| `patrol`, `remind`, `patrol,remind` | `-`, empty, or the whole list is 11 columns | `remind` | nothing — this is the behaviour that predates the column | + +**A `probe` that cannot be substituted falls back to `remind` and is reported, never dropped.** The path is not `{root}/jsc-{domain}/...`, the command carries a `$` or a `~`, a brace other than the three known holes survived, the root could not be resolved, or the script is not on this machine: each prints `probe_bad=` and the entry is still seeded, as a reminder. Not seeding it would mean removing it on `apply`, so one mistyped cell upstream would delete an entry carrying its own `last_run` and `fail_count` history. + +**`{root}` is substituted here; `{cli}` and `{repo}` are deliberately left in the value.** The CLI list has to be detected and the repositories have to be scanned, and neither is known at seeding time. Expanding into several entries instead would give one `spec_key` several files — the reconcile treats that as `dup=` and refuses to touch any of them — and would go stale the moment a CLI is installed or a repository cloned, with re-expansion costing the history it just protected. So the hole stays, and one rule pays for it: **an `action` containing a brace is not yet a runnable command and must never be executed as written.** Nothing executes an `action` today — `tasks.sh` stores it, `due.sh` prints it, `status` and the monitor page print it — so the rule is aimed at whoever wires execution up later: substitute `{cli}` with each detected CLI token and `{repo}` with each scanned repository working directory, run once per target, and let the targets' results together count as this entry's one success or failure. + +**A `pending` row stays a reminder but is never reported as an ordinary one.** The reason lives in the report, as a `pending=` line, and nothing is written into the task file. Putting the marker in the title would change the `id` and cut that entry's history, and the drift check compares `kind`, `action`, `trigger` and `recur` but not the title, so a stale marker would never be caught; adding a sixteenth key would change the task book's fixed storage format for a piece of upstream prose the task book has no way to edit later. `status` runs `plan`, so `pending=`, `held=` and `drift=` all reach a human in the same place. + +**Neither repository's merge order can break the other.** `seed-tasks.sh` measures the list's column count once: 12 or more and `probe` applies, 11 or fewer and every non-`invoke` row seeds as `remind` exactly as before, with a single note saying why rather than one warning per row. On the round after `jsc-meta` gains the column, the four command rows show up as `drift=` and change nothing until a human passes `--refresh` — report that as the expected transition, not as a fault. + **Seeding and rebuilding are the same call.** There is no first-run flag and no second code path: what happens is decided by comparing the list against the task book, so the first call seeds every item and every later call is a no-op until the list actually changes. That is why `start` runs it every time rather than only once. **A `cond` row is held back on purpose, and the report has to say so.** The condition lives in prose in the list, so no script can evaluate it, and one of them says in as many words that its own scripts still resolve through version-carrying paths — seeding it would have the assistant invoke, every single round, something that stops on its first script call with no error, no output and a heartbeat that still looks healthy. So the default is to hold, and every held row is printed with its condition and the half that stays with a human. Never quietly drop them: a missing item nobody can account for is the failure this reporting prevents. @@ -251,7 +270,7 @@ The delegation list holds one row per jsc skill and records whether that skill c | Code | Meaning | What to do | | --- | --- | --- | -| 0 | The two sides are reconciled — `plan` printed its verdict, or `apply` made the changes. Zero changes is this code too | Carry on, and carry the `added=`, `removed=`, `kept=`, `drift=`, `held=` and `bad=` counts into the report | +| 0 | The two sides are reconciled — `plan` printed its verdict, or `apply` made the changes. Zero changes is this code too | Carry on, and carry the `added=`, `removed=`, `kept=`, `drift=`, `held=`, `bad=`, `probe=`, `pending=` and `probe_bad=` counts into the report | | 1 | The delegation list could not be read, so **nothing was touched** | Report `jsc-meta` as missing or unreadable and say the built-in items were left exactly as they were. Never report this as "the list has no delegable skills" | | 2 | The list was read but not one delegable row came out of it, so **nothing was touched** | Report the list itself as suspect — a half-synced or damaged list would otherwise delete every built-in item. Point at the file and stop | | 3 | `tasks.sh` was not found, so **nothing was touched** | Report the installation as incomplete: the task book has exactly one writer and it is missing | @@ -282,7 +301,7 @@ That property holds only while nothing fakes a heartbeat. **`write` is called by `start` proves the loop works before it schedules it: the built-in items first, then one patrol round, then the scheduled entry. It installs no daemon and writes no bare heartbeat. -1. **Reconcile the built-in check items against the delegation list.** Run `{CURRENT}/jsc-assist/tools/seed-tasks.sh apply --root {CURRENT}`. This comes before the round, so the round's own task-book section already shows the items this machine is supposed to be checking. Judge the result by the seed-tasks.sh exit-code table, and keep every `add=`, `remove=`, `drift=`, `held=`, `bad=`, `dup=` and `skip_user=` line plus the summary counts for the report. **Exit 1, 2 and 3 do not stop the start.** Nothing was touched in any of those cases, so the assistant still has whatever items it had before and the round is still worth running: record what the code means, put it into the closing report, and carry on to step 2. Exit 4 is the same — the entries that did get added or removed stand, and the failed ones are named. Never pass `--force` and never pass `--allow-cond` on your own initiative: the first would let this step delete something a person asked for, and the second asserts a condition only a person can check. Completion condition: the exit code and the summary counts are recorded, with every `held=` row's skill name kept for the report, or the code was recorded as "nothing was touched" and step 2 was reached anyway. +1. **Reconcile the built-in check items against the delegation list.** Run `{CURRENT}/jsc-assist/tools/seed-tasks.sh apply --root {CURRENT}`. This comes before the round, so the round's own task-book section already shows the items this machine is supposed to be checking. Judge the result by the seed-tasks.sh exit-code table, and keep every `add=`, `remove=`, `drift=`, `held=`, `bad=`, `dup=`, `skip_user=`, `probe=`, `pending=` and `probe_bad=` line plus the summary counts for the report. **Exit 1, 2 and 3 do not stop the start.** Nothing was touched in any of those cases, so the assistant still has whatever items it had before and the round is still worth running: record what the code means, put it into the closing report, and carry on to step 2. Exit 4 is the same — the entries that did get added or removed stand, and the failed ones are named. Never pass `--force` and never pass `--allow-cond` on your own initiative: the first would let this step delete something a person asked for, and the second asserts a condition only a person can check. Completion condition: the exit code and the summary counts are recorded, with every `held=` row's skill name kept for the report, or the code was recorded as "nothing was touched" and step 2 was reached anyway. 2. **Run one patrol round.** Follow every step of the `patrol` operation below, start to finish. This is what writes the first heartbeat — there is no shortcut past it, because a heartbeat that no round produced is exactly the lie this design removes. When that round ends without a heartbeat for any reason (`collect` exit 4, 5 or 6, an empty `hash=`, a failed write of the monitor page, a directory-entry failure other than exit 3, or `finish` exit 2, 4 or 5), the start has failed: report the round's outcome and the code, do not run step 4, and do not claim a started assistant. A round that completed with failed items (`collect` exit 1 or 3) is still a completed round — carry on to step 3 and name the failures in the closing report. Completion condition: `patrol.sh finish` exited 0, or the failure report naming the step and the code has been printed and no start was claimed. @@ -292,7 +311,7 @@ That property holds only while nothing fakes a heartbeat. **`write` is called by 5. **Report the start.** Print the round's verdict and its four item results, the monitor page that was written, the heartbeat path, the local time of `ts`, the TTL in seconds, `pid`, `cli` and `session` as hints, then the scheduler mechanism, the derived period, the installed entry line as the script printed it with the token already masked, the `patrol_root=` the entry carries — that is what every later round reads its tool root from — how many legacy heartbeat entries were removed, and how many other entries were left untouched. Then hand over the two operator items the install printed: the `allow_rule=` lines verbatim, so the unattended round never meets a permission prompt, and the reminder that the entry holds a snapshot of the listed variables including the token — keep the crontab file readable by its owner alone, and run `install` again after any of those variables changes. - **Then report step 1's reconcile in its own block**, because it is the only place the built-in items are accounted for: how many were added, how many removed, how many left alone, then every held `cond` row by name with the reason it was held, every `bad=` row as a defect in the list rather than in this machine, every `drift=` row with the change the list now asks for and the note that `--refresh` is what applies it, and every `dup=` or `skip_user=` row as an entry a person has to settle. An exit of 1, 2 or 3 is reported here as "the built-in items were left as they were" with the reason, never as "there is nothing to check". Close with the notice that matches step 4's outcome, printed literally with `{ttl}` replaced by the TTL just read and `{period}` by the derived period: + **Then report step 1's reconcile in its own block**, because it is the only place the built-in items are accounted for: how many were added, how many removed, how many left alone, then every held `cond` row by name with the reason it was held, every `bad=` row as a defect in the list rather than in this machine, every `drift=` row with the change the list now asks for and the note that `--refresh` is what applies it, and every `dup=` or `skip_user=` row as an entry a person has to settle. **Then account for the `probe` column separately**: every `probe=` row as an item that now runs a read-only command rather than only reminding, naming any `{cli}` or `{repo}` hole still in it; every `pending=` row as a slice whose entry point is not wired yet, with the list's own reason — that is the only place those are distinguishable from the rows that were always reminders; and every `probe_bad=` row as an item that fell back to reminding, with what stopped the substitution. When the summary carries `spec_cols=11`, say that this machine's `jsc-meta` predates the column and that no item runs a command this round. An exit of 1, 2 or 3 is reported here as "the built-in items were left as they were" with the reason, never as "there is nothing to check". Close with the notice that matches step 4's outcome, printed literally with `{ttl}` replaced by the TTL just read and `{period}` by the derived period: | Step 4 | Notice | | --- | --- | @@ -394,7 +413,7 @@ Read-only throughout. This operation creates, modifies and deletes nothing under 6. **Flag the repeatedly failing tasks.** Append 已連續失敗 N 次 to every row whose `fail_count` is above 0, with `N` taken verbatim from the file. A broken entry that retries every round with nobody noticing is the reason this field exists, so let no such row leave the table unmarked. Completion condition: every row with `fail_count` above 0 carries the marker and its number matches the file. -7. **Check the built-in items against the delegation list, read-only.** Run `{CURRENT}/jsc-assist/tools/seed-tasks.sh plan --root {CURRENT}`. `plan` writes nothing at all — it prints what a reconcile would do and stops — which is what makes it safe here, and `apply` must never be run from `status`. Judge the code by the seed-tasks.sh table and report the difference: the count of items the list expects but the task book lacks, the count of orphans the task book still holds, every `held=` row by name, and every `drift=` row with the change the list asks for. Say plainly that `start` is what applies any of it. On exit 1, 2 or 3 report that the comparison could not be made and why, and never present that as an aligned task book. Completion condition: the difference is reported with its counts and the held rows named, or the reason it could not be computed is reported, and nothing under `$JSC_HOME` was written. +7. **Check the built-in items against the delegation list, read-only.** Run `{CURRENT}/jsc-assist/tools/seed-tasks.sh plan --root {CURRENT}`. `plan` writes nothing at all — it prints what a reconcile would do and stops — which is what makes it safe here, and `apply` must never be run from `status`. Judge the code by the seed-tasks.sh table and report the difference: the count of items the list expects but the task book lacks, the count of orphans the task book still holds, every `held=` row by name, every `drift=` row with the change the list asks for, every `pending=` row as a slice with an entry point still unwired — this is where a human finds out which reminders are waiting on plumbing rather than on them — and every `probe_bad=` row as an item that fell back to reminding. Say plainly that `start` is what applies any of it. On exit 1, 2 or 3 report that the comparison could not be made and why, and never present that as an aligned task book. Completion condition: the difference is reported with its counts and the held rows named, or the reason it could not be computed is reported, and nothing under `$JSC_HOME` was written. 8. **Finish successfully.** `助理未運行`, an absent `tasks/` directory, an empty `tasks/` directory and an uninstalled schedule are normal results — never exit non-zero for any of them. Reserve a failure report for a condition none of the tables above covers, and state which path and which error produced it. Completion condition: the report is printed and nothing under `$JSC_HOME` has been created, modified or deleted. diff --git a/tools/seed-tasks.sh b/tools/seed-tasks.sh index c5740f9..fb2bef5 100755 --- a/tools/seed-tasks.sh +++ b/tools/seed-tasks.sh @@ -41,13 +41,13 @@ # # --- 哪些欄位從清單來、哪些自己補 --- # -# 清單有十一欄，待辦簿有十五個鍵，對得上的只有兩欄。逐個交代： +# 清單有十二欄，待辦簿有十五個鍵，直接抄過來的只有兩欄。逐個交代： # 從清單直接抄過來 # trigger 原樣抄。第一次什麼時候到期是判定結果，不是這一支的決定 # recur 原樣抄。同上 # 從清單推出來 # spec_key domain 與 name 兩欄合起來寫成 jsc-{domain}:{技能名}，那就是一支技能的身分 -# action 由 way 推，對映見下一段。way 與 action 不是同一件事 +# action 由 way 與 probe 兩欄一起推，對映見下一段。way 與 action 不是同一件事 # title 固定寫成「委派清單內建項：{spec_key}」。標題刻意不含 way、trigger、recur： # 那幾欄會隨清單改動而變，寫進標題就等於每一次改動都換一個 id，而 id 一換， # last_run 與 fail_count 的歷史就跟著斷掉 @@ -68,19 +68,92 @@ # 兩個同名不同義，一律不互抄 # state、last_run、next_run、fail_count 由 tasks.sh 與判到期那一邊維護，這一支不碰。 # -# --- way 與 action 的對映 --- +# --- way 與 probe 怎麼推出 action --- # # 清單的 way 是交出方式，三種：invoke 觸發、patrol 巡檢、remind 提醒。待辦簿的 action 是 -# 助理實際要跑的事，三種：技能名、腳本、remind。兩套詞彙不對應，所以要明寫對映： -# way 含 invoke → action 取技能名。觸發的定義就是呼叫既有技能、內容照那支技能自己的 -# 流程走，所以填技能名就是照判定結果做 -# 其餘（patrol、remind、patrol,remind）→ action 取 remind -# 第二條的理由要講清楚，因為它看起來像偷懶。巡檢那個交出方式的意思是「助理在自己那一輪裡 -# 順手做那一段唯讀盤點」，而那一段沒有獨立的入口：巡檢那一輪讀的是固定那幾項來源，沒有 -# 一支腳本或一個技能名代表得了「某一支技能的唯讀切片」。這時候把技能名填進 action，助理下一輪 -# 就會去呼叫整支技能，那正是切片交要防的事——留在人手上的那一半會被一路跑完。 -# 所以填 remind：助理照時程提醒該做那一段、指出入口，不動手。等哪一天那些切片各自有了自己的 -# 入口，改的是這個對映，不是待辦簿的格式。 +# 助理實際要跑的事，三種：技能名、指令、remind。兩套詞彙不對應，所以要明寫對映： +# way 含 invoke → action 取技能名，probe 一律不看。觸發的定義就是呼叫既有技能、內容 +# 照那支技能自己的流程走，所以填技能名就是照判定結果做 +# 其餘那幾種（patrol、remind、patrol,remind）看 probe 那一欄： +# probe 是一行指令 → action 取那一行指令，代入點先代好 +# probe 是 pending:{理由} → action 取 remind，另外印一行 pending= +# probe 是減號或空的 → action 取 remind +# 中間那一條原本沒有：這一支以前把非 invoke 的列一律推成 remind，因為那些唯讀切片沒有獨立 +# 的入口——巡檢那一輪讀的是固定那幾項來源，沒有一支腳本代表得了「某一支技能的唯讀切片」。 +# 清單補上 probe 之後，有入口的那幾列指得出來了，所以改成照 probe 走。沒有入口的那幾列行為 +# 一個字都沒變，還是 remind：填技能名會讓助理下一輪去呼叫整支技能，那正是切片交要防的事， +# 留在人手上的那一半會被一路跑完。 +# invoke 那一路為什麼連看都不看 probe：填了指令會讓整支交出變成只跑一支腳本，那支技能該寫 +# 的頁一頁都不會寫，而且看起來完全正常。清單自己的檔頭也明寫 invoke 的列一律填減號，所以 +# 那是清單填錯，不是這裡要順從的設定。這一支照 way 取技能名、另外印一行 probe_bad= 報出來， +# 不因為那個錯就不種入——不種入等於讓上游一個打錯的欄位把一筆好好的內建項刪掉。 +# +# --- probe 代不進去的時候一律退回 remind --- +# +# probe 有問題的處置只有一種：**退回 remind，另外印一行 probe_bad=，照樣種入那一筆。** +# 涵蓋這幾種：路徑不是 {root}/jsc-{domain}/ 開頭、指令裡有金錢符號或波浪號（那兩種在無人 +# 值守那一輪解不出來，也進不了允許清單）、出現 {root}、{cli}、{repo} 以外的代入點、代不出 +# 根目錄，還有那支腳本不在這台機器上。 +# 為什麼不改成「不種入」：不種入在 apply 那一路等於移除，於是上游改壞一格就會把一筆帶著 +# last_run 與 fail_count 的內建項刪掉。退回 remind 的代價只是那一筆這一輪不動手，人照樣被 +# 提醒該做那一段，而 probe_bad= 那幾行指得出是哪一支、壞在哪。 +# 為什麼不把代不出來的指令原樣種進去：那個值最後會被拿去執行。帶著 {root} 或 {cli} 的字面值 +# 執行起來就是指到一個不存在的路徑，每一輪失敗一次；帶著金錢符號的那一種更糟，展開之後跑到 +# 哪裡去沒有人說得準。 +# +# --- {cli} 與 {repo} 留在值裡，執行那一步才代 --- +# +# probe 認得三個代入點。{root} 這一支自己代得掉，另外兩個代不掉：{cli} 要代入助理偵測到的 +# CLI 代號，{repo} 要代入助理掃到的存取庫工作目錄，兩件事種入的當下都還不知道。 +# 兩條路，這裡選第二條： +# 一、種入時就展開成多筆。代價是一致化整個垮掉。反查鍵 spec_key 是一支技能一個值，展開成 +# 多筆就是同一個鍵有好幾個檔案，而這一支碰到同一個鍵有兩筆以上一律不動它、只印 dup=， +# 於是每一輪都印一堆 dup=、一筆都對不齊。而且 CLI 裝了新的一支、存取庫多 clone 一個， +# 那組展開就過期了，要重新展開就得先移除再重新登錄，last_run 與 fail_count 跟著歸零， +# 那正是下面 drift 那一段刻意不做的事。 +# 二、留著代入點，執行那一步再展開。代價是待辦簿裡留著一個還沒代進去的字面值。 +# 選二，並且把代價擋掉：**action 裡出現大括號就是還沒代好的代入點，一律不得原樣拿去執行。** +# 執行那一步（現在還沒接上來，見技能本文）要先把 {cli} 換成每一支偵測到的 CLI 代號、把 +# {repo} 換成每一個掃到的存取庫工作目錄，一個目標跑一次，那一輪所有目標的結果合起來算這一筆 +# 的一次成敗。展開由執行那一步負責，不由這一支、也不由 tasks.sh 負責。 +# 其他讀取端會不會誤解，逐個交代：tasks.sh 只存放，action 對它是不透明的一個字串；due.sh +# 只判到期，它讀 action 是為了印出來，一次都不執行；技能的 status 與監控頁也只是把 action +# 原樣印出來。三個讀取端沒有一個會拿 action 去跑，所以現在留著代入點不會有人跑錯；真正要防 +# 的是往後接執行那一步的人，那一條規則寫在上面那一句，也寫進技能本文與行為清單。 +# 種入時每一筆指令型都印一行 probe=，holes= 那一欄列出這一筆還留著哪幾個代入點，所以留了 +# 什麼看得見，不必去讀待辦檔才知道。 +# +# --- pending 的那幾筆只印不寫 --- +# +# probe 是 pending:{理由} 的那幾列，action 照舊取 remind，但要跟「本來就只提醒」分得開。 +# 分法是**只印在回報裡**：一行 pending={spec_key} reason={清單上的理由原文}，摘要另外印 +# pending= 的筆數。待辦檔本身一個字都不加。 +# 為什麼不寫進標題：標題是 id 的雜湊來源，改標題就換 id，last_run 與 fail_count 跟著斷掉； +# 而且這一支的漂移比對只比 kind、action、trigger、recur 四欄，不比標題，所以一個寫進標題的 +# 記號在 pending 換成指令、或換成減號的時候不會被比出來，會一直留在那裡指著一件已經不成立 +# 的事。 +# 為什麼不另立一個欄位：那是待辦簿的存放格式，十五個鍵是固定的，加一個鍵要動 tasks.sh 的 +# 寫入、驗證、list 欄位順序，還有每一個讀 list 的人。而 pending 的理由是清單上的散文，會隨 +# 上游改，待辦簿又沒有 edit 操作，抄進去就是抄了一份改不掉的舊值。清單的 verdict、slice、 +# human 幾欄不抄進待辦簿也是同一個理由。 +# 只印在回報裡夠不夠用：夠。人要看的入口就是 status，那一個操作跑的是這一支的 plan， +# pending= 與 held=、drift= 印在同一個地方，一次看完。 +# +# --- 清單只有十一欄的時候 --- +# +# probe 是清單的第十二欄，比這一支晚不了也早不了：兩個存取庫各自合併，總有一邊先到。所以 +# 十一欄的舊清單餵進來要照常跑完，行為與加上這一欄之前一模一樣。 +# 判法是先數一次資料列的欄位數，取最大值當這一份清單的形狀： +# 最大欄位數 12 以上 → 這一份有 probe，照上面那幾段走；某一列少一格導致 probe 是空的， +# 那是那一列漏填，退回 remind 並印 probe_bad= +# 最大欄位數 11 以下 → 這一份沒有 probe，全部照 way 推 action，一行 note 講明這一輪為什麼 +# 沒有任何一筆指令型，不逐列印 probe_bad=——三十五行同一個原因的警告 +# 會把真的缺失蓋掉 +# 取最大值而不是逐列各判：清單是一份檔案，欄位數是整份的性質。逐列各判的話，十二欄清單裡 +# 一列漏填會被當成「這一列是舊格式」而靜靜放過，那正是要抓出來的東西。 +# 第十三欄以後留給往後：讀的時候另外接一個變數收尾，多出來的欄位不會被黏進 probe。少了這個 +# 收尾，上游哪天加第十三欄，probe 讀到的就是「指令加一個定位字元加第十三欄」，代入點檢查 +# 全部過得了關，最後拿去執行的是一行誰都沒寫過的指令。 # # --- 條件式交的那幾支一律不種入 --- # @@ -238,15 +311,90 @@ find_tasks_sh() { return 1 } -# --- way 對 action --- +# --- way 與 probe 對 action --- -# 對映與理由見檔頭「way 與 action 的對映」。way 是半形逗號隔開的清單，比對時前後各補一個 -# 逗號，才不會讓 invoke 去命中一個叫別的名字但含有 invoke 這幾個字的交出方式。 -action_of() { # $1=way $2=spec_key +# way 是半形逗號隔開的清單，比對時前後各補一個逗號，才不會讓 invoke 去命中一個叫別的名字 +# 但含有 invoke 這幾個字的交出方式。 +is_invoke() { # $1=way case ",$1," in - *,invoke,*) printf '%s' "$2" ;; - *) printf 'remind' ;; + *,invoke,*) return 0 ;; esac + return 1 +} + +# 代入 {root} 用的字面絕對根目錄，整份清單只解一次，值放在 PROBE_ROOT。--root 給了就用那 +# 一個，理由同 find_spec()：根目錄由呼叫端餵進來，這一支不自己解也不猜。沒給才從清單自己的 +# 位置往上推三層——清單一定在 {根目錄}/jsc-meta/tools/delegate-spec.tsv，推得回去；--spec +# 指到別處時推出來的值不一定對，所以每一列代完還要看那一層底下有沒有對應的 domain 目錄。 +resolve_root() { + if [ -n "$OPT_ROOT" ]; then + PROBE_ROOT="$OPT_ROOT" + return 0 + fi + PROBE_ROOT=$(CDPATH= cd -- "$(dirname -- "$SPEC")/../.." 2>/dev/null && pwd -L) || PROBE_ROOT='' + return 0 +} + +# 把 probe 那一行指令代好代入點。設好 PROBE_CMD 與 PROBE_HOLES 回 0，代不出來就設好 +# PROBE_WHY 回 1。處置一律是退回 remind，理由見檔頭「probe 代不進去的時候一律退回 remind」。 +# 這一支刻意用設全域變數的寫法、不用命令替換接回傳值：命令替換是子行程，裡面設的 +# PROBE_HOLES 與 PROBE_WHY 傳不回來，於是每一筆的 holes= 與失敗理由都會是空的。 +probe_action() { # $1=probe 原文 + PROBE_CMD='' + PROBE_HOLES='' + PROBE_WHY='' + # 金錢符號與波浪號先擋。那兩種寫法在無人值守那一輪解不出來，也進不了允許清單，會被靜靜 + # 擋掉；擋在種入這一刻，錯的是清單這件事才看得見。 + case "$1" in + *'$'*) PROBE_WHY='指令裡有金錢符號。那種寫法在無人值守那一輪解不出來，也進不了允許清單，會被靜靜擋掉'; return 1 ;; + *'~'*) PROBE_WHY='指令裡有波浪號。那種寫法在無人值守那一輪解不出來，也進不了允許清單，會被靜靜擋掉'; return 1 ;; + esac + # 腳本路徑一律寫成 {root}/jsc-{domain}/ 開頭。認不出這個形狀就代不出絕對路徑，而權限閘門 + # 只放行完整字面絕對路徑。 + _dom=$(printf '%s' "$1" | LC_ALL=C sed -n 's|.*{root}/jsc-\([a-z0-9-]*\)/.*|\1|p') + if [ -z "$_dom" ]; then + PROBE_WHY='路徑不是 {root}/jsc-{domain}/ 開頭，代不出字面絕對路徑' + return 1 + fi + if [ -z "$PROBE_ROOT" ]; then + PROBE_WHY="代不出根目錄（清單在 $SPEC，也沒有帶 --root）" + return 1 + fi + # 那一層的目錄名以 jsc-{domain} 為準，找不到就退回不帶前綴的 {domain}，比照 find_spec() + # 找清單本身的作法：開發用的並排存取庫版面那一層就是不帶前綴的。 + if [ -d "$PROBE_ROOT/jsc-$_dom" ]; then + _dir="jsc-$_dom" + elif [ -d "$PROBE_ROOT/$_dom" ]; then + _dir="$_dom" + else + PROBE_WHY="這台機器的 $PROBE_ROOT 底下找不到 jsc-$_dom，也找不到 $_dom，那一段唯讀盤點的腳本不在這裡" + return 1 + fi + _pre="${1%%\{root\}/jsc-$_dom/*}" + _post="${1#*\{root\}/jsc-$_dom/}" + _cmd="$_pre$PROBE_ROOT/$_dir/$_post" + # 指到不存在的腳本算缺失。種進去的話那一筆每一輪失敗一次，而失敗的原因在清單那一邊。 + _script="$PROBE_ROOT/$_dir/${_post%% *}" + if [ ! -f "$_script" ]; then + PROBE_WHY="代出來的腳本不存在：$_script" + return 1 + fi + # {root} 代完之後還准留的大括號只有 {cli} 與 {repo} 兩種。其餘一律算填錯：代不進去的字面值 + # 會原樣送進指令。 + _left=$(printf '%s' "$_cmd" | sed 's/{cli}//g; s/{repo}//g') + case "$_left" in + *'{'*|*'}'*) + PROBE_WHY="代完 {root} 之後還留著認不得的代入點：$_cmd" + return 1 ;; + esac + case "$_cmd" in + *'{cli}'*) PROBE_HOLES='{cli}' ;; + esac + case "$_cmd" in + *'{repo}'*) PROBE_HOLES="${PROBE_HOLES:+$PROBE_HOLES,}{repo}" ;; + esac + PROBE_CMD="$_cmd" + return 0 } # --- 參數 --- @@ -309,8 +457,30 @@ HAVE="$TMPD/have.tsv" N_HELD=0 N_BAD=0 +N_PROBE=0 +N_PENDING=0 +N_PROBE_BAD=0 +PROBE_ROOT='' +PROBE_CMD='' +PROBE_HOLES='' +PROBE_WHY='' +resolve_root + +# 這一份清單有沒有 probe 那一欄，先數欄位數判一次，理由與判法見檔頭「清單只有十一欄的 +# 時候」。註解列不算：檔頭那幾行的欄位數是說明文字切出來的，跟資料列無關。 +SPEC_COLS=$(awk -F"$TAB" '/^#/{next} NF>1 {if (NF>m) m=NF} END{print m+0}' "$SPEC" 2>/dev/null) +case "$SPEC_COLS" in + ''|*[!0-9]*) SPEC_COLS=0 ;; +esac +if [ "$SPEC_COLS" -lt 12 ]; then + note "委派清單 $SPEC 只有 $SPEC_COLS 欄，沒有第十二欄 probe。這一輪所有非 invoke 的列照舊一律種成只提醒，行為與清單補上那一欄之前相同。要讓有唯讀盤點入口的那幾列真的動手，請先把 jsc-meta 更新到有 probe 那一欄的版本，再跑一次 apply——那一次那幾筆會印成 drift=，要換值得帶 --refresh。" +fi + # 註解列與空白列跳掉。清單是定位字元分隔，欄位順序見清單自己的檔頭。 -while IFS="$TAB" read -r c_domain c_name c_verdict c_way c_slice c_human c_trigger c_recur c_rest; do +# c_rest 收第十三欄以後：少了它，上游哪天加一欄，多出來的值會連著定位字元黏進 c_probe， +# 而黏出來的那一行看起來還很像一個完整的指令。 +while IFS="$TAB" read -r c_domain c_name c_verdict c_way c_slice c_human c_trigger c_recur \ + c_next c_version c_origin c_probe c_rest; do case "$c_domain" in ''|'#'*) continue ;; esac @@ -347,8 +517,45 @@ while IFS="$TAB" read -r c_domain c_name c_verdict c_way c_slice c_human c_trigg "$_key" "$c_verdict" "${c_trigger:--}" "${c_recur:--}" continue fi + # way 決定 action 的大方向，probe 只在「不是 invoke」那一路上改動它。對映見檔頭 + # 「way 與 probe 怎麼推出 action」。 + _probe="$c_probe" + # 十一欄的舊清單一律當成沒有 probe，不逐列印警告：上面已經整份講過一次。 + [ "$SPEC_COLS" -ge 12 ] || _probe='' + if is_invoke "$c_way"; then + _action="$_key" + case "$_probe" in + ''|'-') ;; + *) + N_PROBE_BAD=$((N_PROBE_BAD + 1)) + printf 'probe_bad=%s reason=way 含 invoke，這一次照 way 取技能名，probe 沒有採用 probe=%s\n' \ + "$_key" "$_probe" ;; + esac + else + _action=remind + case "$_probe" in + ''|'-') ;; + 'pending:') + # 冒號後面留白的話，下一輪分不出是刻意不接還是漏填，所以當成填錯報出來，動作照樣 + # 退回只提醒。 + N_PROBE_BAD=$((N_PROBE_BAD + 1)) + printf 'probe_bad=%s reason=probe 寫了 pending 卻沒有寫理由，分不出是刻意不接還是漏填\n' "$_key" ;; + pending:*) + N_PENDING=$((N_PENDING + 1)) + printf 'pending=%s reason=%s\n' "$_key" "${_probe#pending:}" ;; + *) + if probe_action "$_probe"; then + _action="$PROBE_CMD" + N_PROBE=$((N_PROBE + 1)) + printf 'probe=%s holes=%s action=%s\n' "$_key" "${PROBE_HOLES:--}" "$PROBE_CMD" + else + N_PROBE_BAD=$((N_PROBE_BAD + 1)) + printf 'probe_bad=%s reason=%s probe=%s\n' "$_key" "$PROBE_WHY" "$_probe" + fi ;; + esac + fi printf '%s\t%s\t%s\t%s\t%s\t%s\n' \ - "$_key" 'check' "委派清單內建項：$_key" "$(action_of "$c_way" "$_key")" \ + "$_key" 'check' "委派清單內建項：$_key" "$_action" \ "$c_trigger" "$c_recur" >>"$WANT" 2>/dev/null \ || die 5 "暫存檔寫不進去：$WANT。" done <"$SPEC" @@ -491,12 +698,15 @@ done <"$HAVE" # --- 摘要 --- N_HAVE=$(awk 'END{print NR+0}' "$HAVE") -printf 'mode=%s spec=%s tasks_sh=%s want=%s have=%s added=%s removed=%s kept=%s drift=%s held=%s bad=%s dup=%s skip_user=%s\n' \ - "$MODE" "$SPEC" "$TASKS_SH" "$N_WANT" "$N_HAVE" "$N_ADD" "$N_REMOVE" "$N_KEEP" \ - "$N_DRIFT" "$N_HELD" "$N_BAD" "$N_DUP" "$N_SKIP_USER" +printf 'mode=%s spec=%s spec_cols=%s root=%s tasks_sh=%s want=%s have=%s added=%s removed=%s kept=%s drift=%s held=%s bad=%s dup=%s skip_user=%s probe=%s pending=%s probe_bad=%s\n' \ + "$MODE" "$SPEC" "$SPEC_COLS" "${PROBE_ROOT:--}" "$TASKS_SH" "$N_WANT" "$N_HAVE" "$N_ADD" "$N_REMOVE" "$N_KEEP" \ + "$N_DRIFT" "$N_HELD" "$N_BAD" "$N_DUP" "$N_SKIP_USER" "$N_PROBE" "$N_PENDING" "$N_PROBE_BAD" [ "$N_HELD" -gt 0 ] && note "有 $N_HELD 支是條件式交，這一次沒有種入，逐支印在上面的 held= 那幾行。條件是散文，程式判不了；人確認過某一支的條件成立就帶 --allow-cond 那一支的鍵。" [ "$N_BAD" -gt 0 ] && warn "清單上有 $N_BAD 列對不上，那幾支這一次沒有種入，逐列印在上面的 bad= 那幾行。請回去補清單，不要在這裡補預設值。" +[ "$N_PENDING" -gt 0 ] && note "有 $N_PENDING 支切得出唯讀盤點、入口還沒接上，逐支印在上面的 pending= 那幾行，理由是清單上的原文。那幾筆的動作是只提醒，跟本來就只提醒的那幾筆分別在這裡，待辦檔上看不出來。" +[ "$N_PROBE_BAD" -gt 0 ] && warn "有 $N_PROBE_BAD 支的 probe 代不進去，逐支印在上面的 probe_bad= 那幾行。那幾筆照樣種入，動作退回只提醒——不種入等於讓清單上一格填錯把一筆帶著歷史的內建項刪掉。請回去補清單，或把缺的 plugin 裝起來。" +[ "$N_PROBE" -gt 0 ] && note "有 $N_PROBE 支的動作是一行唯讀盤點指令，逐支印在上面的 probe= 那幾行。holes= 不是減號的那幾筆還留著代入點，執行那一步要先把 {cli} 換成偵測到的 CLI 代號、把 {repo} 換成掃到的存取庫工作目錄，一個目標跑一次；帶著大括號的指令一律不得原樣執行。" [ "$N_DRIFT" -gt 0 ] && [ "$OPT_REFRESH" -eq 0 ] && note "有 $N_DRIFT 筆的判定結果與清單不一樣，這一次照原樣留著。要換值請帶 --refresh，並且知道那一筆的 last_run 與 fail_count 會歸零。" [ "$RC_PARTIAL" -eq 0 ] || die 4 "有 add 或 remove 失敗，其餘各筆照做完了。失敗的逐筆印在上面的 add_failed= 與 remove_failed= 那幾行，各自帶了 tasks.sh 的結束碼，照那一支的結束碼表處理。"