讓排程輪次自己帶齊環境與權限,監控頁改成固定三塊,文件與三份外掛清單一併升到 0.1.1 #7

Merged
admin merged 5 commits from fix/unattended-patrol-round-env-and-permissions into develop 2026-09-02 01:20:42 +00:00
Member

摘要

  • 需求描述:在 WSL、root 身分的機器上啟動背景助理,排程輪次連續失敗。排程裝著卻永遠空轉,外面只看得到心跳過期。這一輪把那一輪跑不完的四道關卡一次修掉,並順手把監控頁改成讀得完的格式,文件與外掛清單一併跟上。
  • 計畫名稱:無
  • 計畫頁:無
  • 分析頁:無

變更內容

檔案 為什麼改
tools/schedule.sh 排程條目原本靠殼的環境跑,那一輪四道關卡全卡住。改成條目自己帶齊執行環境,並在裝完印出那一輪要開的權限規則。另外開跑就比對自己是不是從不帶版本號的連結底下被叫起來的,走錯路徑就印警告
tools/patrol.sh 一輪附加一節,頁面沒有人讀得完。收攏改成產出固定三塊,輸出鍵位跟著換。另外補上「警示來源」:每一處把判定改成警示的地方一律改走同一支函式順手收下理由,收攏時多印一行來源,並比照排程那一支做開跑時的執行路徑自檢
templates/monitor-page.md 範本還寫著「只附加、不覆寫」,跟新的三塊寫法對不起來。摘要表也從四欄改成五欄,最新一輪那一塊跟著補上警示來源那一列
skills/assistant/SKILL.md 工具路徑改走不帶版本號的連結,監控頁那幾步改成讀回舊頁再三塊重組;另補上工具路徑一節、權限說明,以及執行路徑自檢與警示來源這兩件事
references/behaviors.md 行為清單要跟著記下新的環境快照、權限規則、暫存檔名與可驗證跡象,以及腳本自檢的警告與摘要表多出來的那一欄
README.md 兩支腳本與監控頁範本的說明要跟上新做法
AGENTS.md 界線第四條從「只附加」改成三塊寫入語意
plugin.json、.claude-plugin/plugin.json、.codex-plugin/plugin.json 版本 0.1.0 升到 0.1.1。版本不動,版本閘門就看不出哪台機器裝的是舊的那一版,舊條目會繼續空轉

設計重點

排程那一輪跑不完的四道關卡,逐道修法如下。

關卡 原本的樣子 這次的修法
找不到執行檔 條目寫裸的指令名,cron 的 PATH 不含使用者 bin 目錄 用 command -v 解成絕對路徑再寫進條目,解不到就停下,不猜路徑
連不上 wiki cron 不讀殼的設定檔,主機位址與存放庫變數全是空的 install 當下就地快照主機位址、金鑰、狀態根目錄、心跳門檻與所有已設定的存放庫變數,以名稱等於值的前綴寫進條目
寫入被擋 寫入確認只認 tty,排程條目沒有 tty 條目自帶寫入確認旗標,無人值守那一輪本來就沒有人可以按同意
權限沒開 巡檢腳本連跑都跑不起來,而那一輪沒有人可以核准 install 完印出四支腳本各三種呼叫形式的放行規則,一行一條

四關任何一關沒過,那一輪就不寫心跳。這是空轉的根:頁寫不成就不寫心跳,外面只看得到心跳過期,看不出是卡在哪一關。

另外兩項是設計調整,不是修錯。

調整 為什麼 改成什麼
監控頁固定三塊 一輪附加一節,十五分鐘一輪,一天疊出九十六節,沒有人讀得完,也就沒有人會發現壞在哪一輪 本頁基本資料建頁時寫一次就不動、最新一輪每輪整塊換掉、近 24 輪摘要一輪一列且最新的在最上面
工具路徑改走不帶版本號的連結 腳本自己去挑另一個版本,同一輪就跑到混版的工具,那種不一致查起來沒有線索 技能、權限規則與腳本內部找工具,一律以 $JSC_HOME/current/{外掛名} 為準,外掛升版不必改設定

摘要表刻意只有五欄:巡檢時間、本輪判定、四項成敗、待人處理筆數、警示來源。一列要能一眼看完,才看得出是從哪一輪開始壞的。

「警示來源」那一欄不能省。沙箱跑出來的列是「警示、四項全過、待人處理 0」,讀的人看不出警示哪來。查過不是缺陷:四項來源都讀得到,是讀到的內容有警示。所以每一處把判定改成警示的地方,一律改走同一支函式順手收下一句短理由,多個用頓號串,沒有就寫「無」,像「心跳過期」「版本查詢失敗」「重啟閘門未清」「上一輪逾時被接手」。最新一輪那一塊也補同一列,兩處同源。

還有一道防線是執行路徑自檢。用全新的 CLI 行程實測,代理人會把工具路徑解回外掛快取那一份,不是指定的工作樹那一份,讀到的還是舊語意——只在說明書裡寫明禁止是擋不住的。所以巡檢與排程兩支腳本開跑時先比對自己是不是從那一組不帶版本號的連結底下被叫起來的,不是就往標準錯誤印一行警告,點名實際路徑、應該用的路徑與理由。

刻意只警告、不中止:從工作樹直接跑腳本是開發時的正當用法,中止會把那條路擋掉。真正的阻擋本來就發生在權限閘門那裡。

測試結果

四道關卡各自在實機上驗證過,逐項如下。

驗證項目 做法 結果
條目組法 以 --dry-run 印出組好的條目與寫回後的內容,確認絕對路徑、環境快照與寫入確認旗標都在 通過
金鑰遮蔽 檢查 install、remove、status 三處印出的條目 金鑰一律遮成星號
別人的條目 比對安裝前後的排程條目數量 數量相同,別人的一行都沒動
排程輪次 實際裝上條目後等一輪跑完 通過。連續兩輪由排程寫出心跳,監控頁也寫成
監控頁三塊 跑 collect,檢查產出的暫存檔 三塊與摘要列都產得出來
權限規則 對照放行前後各跑一輪 通過。未放行那一輪停在權限詢問,放行後整輪跑完
路徑解錯 用全新的 CLI 行程指定工作樹跑一輪 重現了。代理人把工具路徑解回外掛快取那一份,不是指定的工作樹那一份,讀到的還是舊語意
執行路徑自檢 兩支腳本各從工作樹與從那一組連結底下跑一次 通過。從工作樹跑會印出警告並點名兩邊路徑,從連結底下跑不印,兩次都照跑不中止
五欄摘要列 跑 collect,看產出的摘要列 通過。四項全過而判定是警示的那一列,第五欄寫出了理由,不再是讀不懂的「警示、4/4、0」

自動化測試:無。這幾項都是排程與外部服務的整合行為,靠實機跑一輪驗證。

驗證範圍要說清楚,避免看的人誤判:

事項 實際狀況
實機跑通的那幾輪 跑的是機器上已安裝的舊版巡檢腳本,不是這一版
條目的三項修正 已在實機整輪驗證,那正是讓輪次跑得完的原因
監控頁三塊 只驗到 collect 產出的暫存檔,還沒有真的寫上遠端的頁
install 印出的放行規則 權限確實是那一輪的阻礙已驗證,但驗的是舊的路徑寫法,不是這一版改用的不帶版本號路徑。新增的路徑自檢會在走錯時出聲,但那只是警告,擋不住走錯的那一輪
待補的驗證 這一版部署、且連結由 deploy 建好之後,要再跑一輪確認三塊與新路徑都成立

已知風險

風險 說明 目前的處置
條目帶著金鑰快照 輸出印條目時金鑰已遮成星號,但檔案裡是真值 crontab 檔案必須維持只有本人可讀
快照會過時 快照寫死安裝當下的值 這幾個變數改過就要重跑一次 install,條目才會跟著換
權限閘門只認一組路徑 巡檢輪次若用技能提示給的快取基底目錄組路徑,會被靜靜擋掉,那一輪失敗且不寫心跳。實測證實光靠說明書寫明禁止是擋不住的:代理人照樣把路徑解回快取那一份 兩道防線。第一道是技能主文寫明禁止,第二道是兩支腳本開跑時的執行路徑自檢。自檢只印警告、不中止,所以真正的阻擋仍然發生在權限閘門,走錯路徑那一輪還是會失敗。風險沒有消失,只是走錯時會留下一行看得見的線索
連結還沒有人建 current 那一組連結由另一支 CLI 的 deploy 維護,那一支還沒改,是後續的另一支 PR 連結不存在時 install 只警告,不代建
舊格式的頁會掉資料 舊格式的監控頁第一次重組會丟掉堆疊起來的舊節 只留基本資料,摘要表從當輪那一列開始
Windows 那一邊沒有快照 schtasks 沒有環境快照機制 維持吃使用者環境,不在這一輪處理

前置 Push Request

  • 無
## 摘要 - 需求描述:在 WSL、root 身分的機器上啟動背景助理,排程輪次連續失敗。排程裝著卻永遠空轉,外面只看得到心跳過期。這一輪把那一輪跑不完的四道關卡一次修掉,並順手把監控頁改成讀得完的格式,文件與外掛清單一併跟上。 - 計畫名稱:無 - 計畫頁:無 - 分析頁:無 ## 變更內容 | 檔案 | 為什麼改 | | --- | --- | | `tools/schedule.sh` | 排程條目原本靠殼的環境跑,那一輪四道關卡全卡住。改成條目自己帶齊執行環境,並在裝完印出那一輪要開的權限規則。另外開跑就比對自己是不是從不帶版本號的連結底下被叫起來的,走錯路徑就印警告 | | `tools/patrol.sh` | 一輪附加一節,頁面沒有人讀得完。收攏改成產出固定三塊,輸出鍵位跟著換。另外補上「警示來源」:每一處把判定改成警示的地方一律改走同一支函式順手收下理由,收攏時多印一行來源,並比照排程那一支做開跑時的執行路徑自檢 | | `templates/monitor-page.md` | 範本還寫著「只附加、不覆寫」,跟新的三塊寫法對不起來。摘要表也從四欄改成五欄,最新一輪那一塊跟著補上警示來源那一列 | | `skills/assistant/SKILL.md` | 工具路徑改走不帶版本號的連結,監控頁那幾步改成讀回舊頁再三塊重組;另補上工具路徑一節、權限說明,以及執行路徑自檢與警示來源這兩件事 | | `references/behaviors.md` | 行為清單要跟著記下新的環境快照、權限規則、暫存檔名與可驗證跡象,以及腳本自檢的警告與摘要表多出來的那一欄 | | `README.md` | 兩支腳本與監控頁範本的說明要跟上新做法 | | `AGENTS.md` | 界線第四條從「只附加」改成三塊寫入語意 | | `plugin.json`、`.claude-plugin/plugin.json`、`.codex-plugin/plugin.json` | 版本 0.1.0 升到 0.1.1。版本不動,版本閘門就看不出哪台機器裝的是舊的那一版,舊條目會繼續空轉 | ## 設計重點 排程那一輪跑不完的四道關卡,逐道修法如下。 | 關卡 | 原本的樣子 | 這次的修法 | | --- | --- | --- | | 找不到執行檔 | 條目寫裸的指令名,cron 的 PATH 不含使用者 bin 目錄 | 用 `command -v` 解成絕對路徑再寫進條目,解不到就停下,不猜路徑 | | 連不上 wiki | cron 不讀殼的設定檔,主機位址與存放庫變數全是空的 | install 當下就地快照主機位址、金鑰、狀態根目錄、心跳門檻與所有已設定的存放庫變數,以名稱等於值的前綴寫進條目 | | 寫入被擋 | 寫入確認只認 tty,排程條目沒有 tty | 條目自帶寫入確認旗標,無人值守那一輪本來就沒有人可以按同意 | | 權限沒開 | 巡檢腳本連跑都跑不起來,而那一輪沒有人可以核准 | install 完印出四支腳本各三種呼叫形式的放行規則,一行一條 | 四關任何一關沒過,那一輪就不寫心跳。這是空轉的根:頁寫不成就不寫心跳,外面只看得到心跳過期,看不出是卡在哪一關。 另外兩項是設計調整,不是修錯。 | 調整 | 為什麼 | 改成什麼 | | --- | --- | --- | | 監控頁固定三塊 | 一輪附加一節,十五分鐘一輪,一天疊出九十六節,沒有人讀得完,也就沒有人會發現壞在哪一輪 | 本頁基本資料建頁時寫一次就不動、最新一輪每輪整塊換掉、近 24 輪摘要一輪一列且最新的在最上面 | | 工具路徑改走不帶版本號的連結 | 腳本自己去挑另一個版本,同一輪就跑到混版的工具,那種不一致查起來沒有線索 | 技能、權限規則與腳本內部找工具,一律以 `$JSC_HOME/current/{外掛名}` 為準,外掛升版不必改設定 | 摘要表刻意只有五欄:巡檢時間、本輪判定、四項成敗、待人處理筆數、警示來源。一列要能一眼看完,才看得出是從哪一輪開始壞的。 「警示來源」那一欄不能省。沙箱跑出來的列是「警示、四項全過、待人處理 0」,讀的人看不出警示哪來。查過不是缺陷:四項來源都讀得到,是讀到的內容有警示。所以每一處把判定改成警示的地方,一律改走同一支函式順手收下一句短理由,多個用頓號串,沒有就寫「無」,像「心跳過期」「版本查詢失敗」「重啟閘門未清」「上一輪逾時被接手」。最新一輪那一塊也補同一列,兩處同源。 還有一道防線是執行路徑自檢。用全新的 CLI 行程實測,代理人會把工具路徑解回外掛快取那一份,不是指定的工作樹那一份,讀到的還是舊語意——只在說明書裡寫明禁止是擋不住的。所以巡檢與排程兩支腳本開跑時先比對自己是不是從那一組不帶版本號的連結底下被叫起來的,不是就往標準錯誤印一行警告,點名實際路徑、應該用的路徑與理由。 刻意只警告、不中止:從工作樹直接跑腳本是開發時的正當用法,中止會把那條路擋掉。真正的阻擋本來就發生在權限閘門那裡。 ## 測試結果 四道關卡各自在實機上驗證過,逐項如下。 | 驗證項目 | 做法 | 結果 | | --- | --- | --- | | 條目組法 | 以 `--dry-run` 印出組好的條目與寫回後的內容,確認絕對路徑、環境快照與寫入確認旗標都在 | 通過 | | 金鑰遮蔽 | 檢查 install、remove、status 三處印出的條目 | 金鑰一律遮成星號 | | 別人的條目 | 比對安裝前後的排程條目數量 | 數量相同,別人的一行都沒動 | | 排程輪次 | 實際裝上條目後等一輪跑完 | 通過。連續兩輪由排程寫出心跳,監控頁也寫成 | | 監控頁三塊 | 跑 collect,檢查產出的暫存檔 | 三塊與摘要列都產得出來 | | 權限規則 | 對照放行前後各跑一輪 | 通過。未放行那一輪停在權限詢問,放行後整輪跑完 | | 路徑解錯 | 用全新的 CLI 行程指定工作樹跑一輪 | 重現了。代理人把工具路徑解回外掛快取那一份,不是指定的工作樹那一份,讀到的還是舊語意 | | 執行路徑自檢 | 兩支腳本各從工作樹與從那一組連結底下跑一次 | 通過。從工作樹跑會印出警告並點名兩邊路徑,從連結底下跑不印,兩次都照跑不中止 | | 五欄摘要列 | 跑 collect,看產出的摘要列 | 通過。四項全過而判定是警示的那一列,第五欄寫出了理由,不再是讀不懂的「警示、4/4、0」 | 自動化測試:無。這幾項都是排程與外部服務的整合行為,靠實機跑一輪驗證。 驗證範圍要說清楚,避免看的人誤判: | 事項 | 實際狀況 | | --- | --- | | 實機跑通的那幾輪 | 跑的是機器上已安裝的舊版巡檢腳本,不是這一版 | | 條目的三項修正 | 已在實機整輪驗證,那正是讓輪次跑得完的原因 | | 監控頁三塊 | 只驗到 collect 產出的暫存檔,還沒有真的寫上遠端的頁 | | install 印出的放行規則 | 權限確實是那一輪的阻礙已驗證,但驗的是舊的路徑寫法,不是這一版改用的不帶版本號路徑。新增的路徑自檢會在走錯時出聲,但那只是警告,擋不住走錯的那一輪 | | 待補的驗證 | 這一版部署、且連結由 deploy 建好之後,要再跑一輪確認三塊與新路徑都成立 | ## 已知風險 | 風險 | 說明 | 目前的處置 | | --- | --- | --- | | 條目帶著金鑰快照 | 輸出印條目時金鑰已遮成星號,但檔案裡是真值 | crontab 檔案必須維持只有本人可讀 | | 快照會過時 | 快照寫死安裝當下的值 | 這幾個變數改過就要重跑一次 install,條目才會跟著換 | | 權限閘門只認一組路徑 | 巡檢輪次若用技能提示給的快取基底目錄組路徑,會被靜靜擋掉,那一輪失敗且不寫心跳。實測證實光靠說明書寫明禁止是擋不住的:代理人照樣把路徑解回快取那一份 | 兩道防線。第一道是技能主文寫明禁止,第二道是兩支腳本開跑時的執行路徑自檢。自檢只印警告、不中止,所以真正的阻擋仍然發生在權限閘門,走錯路徑那一輪還是會失敗。風險沒有消失,只是走錯時會留下一行看得見的線索 | | 連結還沒有人建 | `current` 那一組連結由另一支 CLI 的 deploy 維護,那一支還沒改,是後續的另一支 PR | 連結不存在時 install 只警告,不代建 | | 舊格式的頁會掉資料 | 舊格式的監控頁第一次重組會丟掉堆疊起來的舊節 | 只留基本資料,摘要表從當輪那一列開始 | | Windows 那一邊沒有快照 | schtasks 沒有環境快照機制 | 維持吃使用者環境,不在這一輪處理 | ## 前置 Push Request - 無
jiantw83 added 4 commits 2026-09-01 10:36:30 +00:00
排程條目改成自己帶齊執行環境,install 完也印出那一輪要開的權限規則。

背景助理在無人值守的輪次連續失敗,查出四道關卡。cron 給的 PATH 很短,
不含使用者的 bin 目錄,裸的指令名每一輪都是找不到執行檔。cron 也不讀
殼的設定檔,那一輪沒有 Gitea 主機位址與 wiki 存放庫變數,連不上 wiki。
寫入確認只認 tty,排程沒有 tty,寫監控頁一定被擋。工具權限沒開,巡檢
腳本連跑都跑不起來,而那一輪沒有人可以按同意。四關任何一關沒過,那一
輪就不寫心跳,排程裝著卻永遠空轉,外面只看得到心跳過期。

CLI 改用 command -v 解成絕對路徑再寫進條目,解不到就停下,不猜路徑。
install 當下把主機位址、金鑰、狀態根目錄、心跳門檻與所有已設定的 wiki
存放庫變數就地快照,以名稱等於值的前綴寫進條目,值裡的單引號照 POSIX
寫法跳脫。條目自帶寫入確認旗標,無人值守的那一輪本來就沒有人可以按同
意。install 完印出四支腳本各三種呼叫形式的 allow 規則,路徑一律取
current 那一組不帶版本的連結,並順手檢查連結在不在,不在只警告、不代
建。腳本內部找心跳腳本也改成 current 優先,避免同一輪跑到混版的工具。

條目裡帶著金鑰快照,所以印條目時一律把金鑰遮成星號,遮到下一個空白為
止;crontab 檔案要保持只有本人讀得到,這幾個變數改過就要重跑一次
install。功能範圍是助理的系統排程安裝、移除與查現況。
巡檢產出與監控頁範本改成固定三塊:本頁基本資料、最新一輪、近 24 輪摘要。

舊寫法是一輪附加一節。十五分鐘跑一輪,一天就疊出九十六節,那樣的頁沒
有人讀得完,也就沒有人會發現助理壞在哪一輪。軌跡留著卻沒人看,等於沒
有留。

基本資料建頁時寫一次就不動。最新一輪每輪整塊換掉,只留最新那一輪的完
整內容。摘要表一輪一列,最新的在最上面,超過 24 列就丟掉最舊的那一列,
一列只有四欄:巡檢時間、本輪判定、四項成敗、待人處理筆數,一眼看得出
是從哪一輪開始壞的。collect 的輸出鍵位跟著換,section_file 不再產出,
改印 latest_file、summary_file 與 summary_row_file,另外多印本輪待人處
理的筆數。範本連帶把流程圖與寫入規則改成先讀回舊頁、再三塊重組整頁寫
回,並寫明舊格式的頁第一次重組要怎麼收。

順手把腳本內部找別的 domain 工具的順序改成 current 連結優先,理由跟排
程那支一樣:技能與權限規則都以 current 為準,腳本自己去挑另一個版本就
會跑到混版的工具,而那種不一致查起來沒有線索。功能範圍是一輪巡檢的收
攏與監控頁產出。
技能主文、行為清單、專案說明與界線文件一起改,對齊這一輪的排程修正與
監控頁改版。

工具路徑與監控頁寫法都換了,文件沒跟上就是照舊做法跑:用快取基底目錄
組出來的路徑會被權限靜靜擋掉,那一輪停在沒有人能回答的權限詢問;照舊
的附加語意寫頁,又會把剛換好的三塊寫回一輪一節。

技能主文的工具路徑一律改走 current 那一組不帶版本的路徑,新增 Tool
paths 一節列出四支工具,並寫明權限閘門只放行那一組,放行技能不等於放
行技能裡的每一個呼叫。監控頁那幾步改寫成讀回舊頁、基本資料原樣留著、
最新一輪整塊換掉、本輪摘要列擺最上面並截到 24 列,舊格式的頁第一次重
組要在回報裡說明。frontmatter 的 description 重寫並補上單引號,句中有
冒號不加引號會讓解析走偏。界線四從「只附加」改成三塊寫入語意。專案說
明與行為清單同步條目的環境快照、allow 規則、暫存檔名與可驗證跡象。

功能範圍是助理技能的文件與行為合約,不動任何腳本行為。
三份外掛清單的版本從 0.1.0 改成 0.1.1。

這一輪改了排程條目的組法、監控頁的格式與技能的工具路徑,三件都會影響
已經裝在機器上的那一份。版本不動,版本閘門就看不出哪台機器裝的是舊的
那一版,也提不出重啟要求,舊條目會繼續空轉到有人自己發現。

三份檔案只動 version 一欄,其餘不碰,三份保持同一個號碼,這樣不管從哪
一支 CLI 讀到的都是同一個答案。功能範圍是外掛的版本宣告。
jiantw83 added 1 commit 2026-09-01 10:54:07 +00:00
兩支腳本開跑就檢查自己的執行路徑,監控頁的摘要表與最新一輪那一塊補上
「警示來源」。

兩件都是實測之後補的。用全新的 CLI 行程跑,代理人會把工具路徑解回外掛
快取那一份,不是指定的工作樹那一份。原本的對策只在技能說明書裡寫明禁
止,那是文件約束,擋不住真的走錯的那一輪。權限閘門只放行 current 那一
組確切路徑,走錯就被靜靜擋掉,那一輪不寫心跳,外面只看得到心跳過期。
另一頭,沙箱跑出來的摘要列是「警示、四項全過、待人處理 0」,讀的人看
不出警示哪來。查過不是缺陷:四項來源都讀得到,是讀到的內容有警示。摘
要表的用途本來就是一眼看出從哪一輪開始壞,少了原因那一欄就做不到。

巡檢與排程兩支腳本開跑時先比對自己是不是從 current 底下被叫起來的,不
是就往 stderr 印一行警告,點名實際路徑、應該用的路徑與理由。刻意只警告
不中止:從工作樹直接跑腳本是開發時的正當用法,中止會把那條路擋掉,真
正的失敗本來就發生在權限閘門那裡。摘要表從四欄加到五欄,最新一輪那一
塊也補一列,值取每一處設警示時收下來的短理由,多個用頓號串,沒有就寫
「無」。腳本裡每一處把判定改成警示的地方,一律改走同一支函式順手收下
理由,collect 的輸出多印一行 warn_sources。技能主文、行為清單與監控頁
範本跟著寫明這兩件事。

功能範圍是助理的一輪巡檢與系統排程安裝。
admin merged commit d349a76b9c into develop 2026-09-02 01:20:42 +00:00
admin deleted branch fix/unattended-patrol-round-env-and-permissions 2026-09-02 01:20:42 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: plugins/assist#7