 jiantw83
|
2ec4379924
|
feat(tasks): 助理待辦簿的存放格式與讀寫工具
助理要記住兩種項目——內建的定期檢查項與使用者當面交辦的事——但目前沒有地方放。待辦簿是助理待辦與建議下一個指令兩批功能的共同地基，先把存放格式與讀寫工具做出來，判定邏輯之後才接。
存成一筆一檔，純文字 key=value。一筆一檔的理由同重啟閘門那組檔案：並行寫入不互相覆寫。五支 CLI 加上排程那一輪有可能同時動待辦簿，整本存成一個檔案的話兩邊各讀一次整檔、各改自己那一筆、各寫回整檔，後寫的那一次就把前一次整本蓋掉，而且沒有任何訊號。同一個 id 被同時寫也不會寫出半份：先寫暫存檔再搬過去，搬在同一個檔案系統上是原子操作。暫存檔名以點號開頭，列表跳過點號開頭的檔案，寫到一半的那一份不會被列出來。
規格的欄位表少一個欄位。id 是建立時間加標題的雜湊，但表上沒有存建立時間的欄位，不存它就再也算不回同一個 id、驗不出檔名對不對、前綴碰撞時也接不下去。補上建立時間，所以一筆是十四個鍵。
id 取完整雜湊的前八碼，不跟 wiki 頁名的四十碼一致。兩者用途不同：四十碼那條規則管的是 wiki 頁名，頁名一撞就是兩台機器的紀錄互相覆寫且看不出來，所以不准截短；這裡的 id 是本機檔名，人要念它、打進指令、看它印在狀態表與提醒文字裡，四十碼沒有人讀得完也打不對，人就會改用「第三筆」這種說法指定要關哪一筆，那才是真正會關錯的地方。前八碼是同一個雜湊的前綴不是另一套算法，拿建立時間與標題重算就驗得回來。前綴撞上而內容不同就每次多取兩碼再試，不在後面補序號——補了就算不回來。建立時間與標題都相同的不是碰撞而是同一筆被登錄兩次，一律不寫並回專屬結束碼，因為定期檢查項會因為清單重建而重跑登錄，靜靜多寫一筆會讓同一個檢查每輪做兩次。
操作補到六個，兩個都是補規格的洞。失敗那一個是因為規格說失敗要累加連續失敗次數，但原本四個操作沒有一個寫得到它，少了它那個計數永遠是零，監控頁與提醒上那句「已連續失敗幾次」永遠是零次，於是一個壞掉的項目每輪重試而沒人知道，那正是這個欄位要防的事。恢復那一個是因為停用只由人設，也就只有人解得開，沒有別的元件寫得出這個轉移；只給停用不給恢復就是一道單向門，人只能去手改檔案，而手改繞過了轉移表。
上次執行與下次執行不另開操作：完成與失敗都吃選項把值餵進來，值由算到期那一邊算好。這一支不算下一次是什麼時候，兩邊各算一次就會漂移。也刻意沒有編輯操作：id 由建立時間與標題算出來，改掉標題之後 id 就對不回去了。
狀態轉移寫成明確的表並在腳本裡擋住不合法的轉移。停用之後不收完成，因為停掉的那一筆助理本來就沒在跑，標成做完等於偷偷解開又收掉；停用之後不收失敗，因為助理沒在跑它就不可能是它失敗；收掉的那一筆不再有下一次，四種操作全擋。恢復刻意不把連續失敗次數歸零，那幾次失敗真的發生過，歸零會把提醒抹掉而那筆一恢復就會照樣再失敗，要歸零就等它跑成功一次。
值裡有等號或換行用兩條約定處理，不發明跳脫規則。讀的時候只在第一個等號斷開，十四個鍵都是固定的詞、一個都不含等號。寫的時候把值折成一行並在標準錯誤記一行說折過了。選折行不選跳脫，是因為讀的人不只這一支腳本，技能本文與巡檢那一輪都直接把檔案當 key=value 讀，跳脫規則要每個讀的人各自實作一次，漏掉一個就會把跳脫序列原樣印進報告或監控頁，而那看起來很像正常內容。
根目錄解析退回使用者家目錄底下那一層，跟排程、巡檢與心跳三支退回同一個值——兩邊退回的位置不同，待辦簿就會躲在一個沒有人去讀的目錄裡，而每一支都自認為讀對了。連家目錄也沒有才拒絕，不猜路徑：猜錯就是把待辦寫到一個沒有人會去讀的地方，而且看起來像成功。
實測抓到一個真的臭蟲並修掉。查找記錄原本寫成印出路徑、由呼叫端用命令替換接，於是裡面的錯誤退出只結束子行程、外層照樣往下走，訊息說欄位不合法卻回了找不到那一筆的碼，呼叫端拿到的碼與真正的原因不一樣。改寫成直接設變數再回碼。
這一輪只做存放與讀寫。登錄時的補問流程、事件詞彙表接上產生者、到期判定、逾期與失敗處理、提醒送到前景、wiki 雙向同步，六項都不在這一輪，但欄位都已經留在檔案裡，接的時候不必改存放格式。目前還沒有任何操作呼叫得到這六個子命令，行為契約只記下這一支工具存在，不讓清單先跑到技能前面去。
|
2026-09-03 15:46:09 +08:00 |
|
 admin
|
56fe144c38
|
Merge pull request '助理巡檢改用字面絕對路徑，排程根目錄由 cron 條目帶入，避免無人值守輪次被權限層擋下' (#14) from fix/literal-absolute-paths-for-unattended-patrol into develop
Reviewed-on: #14
|
2026-09-03 02:52:00 +00:00 |
|
|
jiantw83
|
711eecac2f
|
fix(assistant): 根目錄守門補上目錄存在檢查
人在現場那一條路解出根目錄之後，守門只看「非空、結束碼 0、是絕對路徑」三項，攔不住 JSC_HOME 沒設的情況。
實測：JSC_HOME 沒設時，readlink -f "$JSC_HOME/current" 印出 /current、結束碼 0。三項全部符合，直接通關，而 /current 並不存在。之後每一條由它組出來的字面路徑都指向不存在的地方，錯誤要到第一支腳本才浮出來，而且訊息看不出根因。
守門加上第四項：印出來的路徑必須是存在的目錄，用 [ -d ] 在同一個已核准的步驟裡查。檢查只掛在人在現場那一條，排程那一輪照舊一個指令都不跑——它的根目錄是安裝排程的人寫進條目的，錯了就由第一支腳本呼叫失敗來反映。
行為契約的關鍵步驟與完成條件兩列跟著改。
|
2026-09-03 10:31:05 +08:00 |
|
|
jiantw83
|
e4a3d3ae12
|
chore(manifest): 三份 manifest 升版至 0.1.6
三份 manifest 的版本從 0.1.5 升到 0.1.6，由 sync-skill-manifest.sh 同步。
助理技能的路徑守則與排程條目的內容都改過，安裝端要靠版號才認得出該更新，不升版的話舊條目會一直留在機器上。
版號與主變更分開成一筆，是因為這三個檔案只帶版號、不帶行為，混進主變更會讓那一筆的 diff 夾雜非行為變更；分開之後回溯哪一版對應哪一次變更也看得清楚。
|
2026-09-03 10:10:02 +08:00 |
|
|
jiantw83
|
fb8b9baedd
|
fix(assistant): 巡檢改用字面絕對路徑，根目錄由排程條目帶進來
無人看管的排程輪次在第一支腳本就被權限層擋下。心跳因此寫不出來，助理斷了兩個多小時，沒有人發現。
2026-09-02 到 09-03 用非互動模式比照排程環境實測七種寫法，歸納出兩條判準。一、無人值守時只有允許清單上的完整字面指令跑得動，沒有「預設安全的唯讀指令」這回事，連 readlink 與 ls 都要有自己的規則。二、路徑中段的萬用字元不匹配，規則與指令都必須是完整字面，所以帶版本號的快取路徑放不進允許清單。「先解路徑再用」因此不成立：解路徑的指令自己就過不了，而路徑能寫成字面就不必解。
助理技能新增路徑守則與 Step 0。守則寫明權限層比對的是指令還沒展開的字面字串，帶未展開變數或波浪號的路徑一律要核准，並附上七列實測佐證表。Step 0 從「自己跑 readlink 解路徑」改成「從叫用文字的『工具根目錄=』取字面絕對路徑」，排程那一輪一個解析指令都不跑；人在現場叫用才用 readlink 解一次，那一次有人可以按同意。取不到根目錄就停下回報，收尾狀態取 aborted，不猜也不退回帶變數的路徑。全篇 46 處腳本呼叫改成字面絕對路徑。
排程工具在安裝時把解好的字面根目錄寫進條目的提示文字，並印成 patrol_root=。條目與允許規則共用同一個值，兩邊各算各的就會差開，而差開的那一輪是被靜靜擋掉。允許規則的提示改成完整字面路徑，不寫變數、波浪號與萬用字元。JSC_HOME 解不出絕對路徑時回結束碼 6，不讓相對路徑寫進條目。自訂巡檢指令沒帶那一段只警告、不中止。
行為契約四列與說明文件兩處敘述一併跟上。
|
2026-09-03 10:10:01 +08:00 |
|
|
admin
|
225478f756
|
Merge pull request '助理巡檢目錄頁改成大標題加條列，巡檢輸出檔改名 contents-entry.md' (#13) from feat/contents-list/main into develop
Reviewed-on: #13
|
2026-09-02 10:00:32 +00:00 |
|
|
jiantw83
|
8053c15425
|
chore(manifest): 三份 manifest 升版至 0.1.5
三份外掛清單的版號一起往上推一版。
目錄頁的版面與巡檢輸出檔名都變了，呼叫端要靠版號才判得出手上這一份是新的
還是舊的。版號不動，版本閘門就不會提示更新，機器上會留著舊版工具去讀新版
範本。
三份清單各自被不同的 CLI 讀，值必須一致，所以一起改、一起提交。
範圍是外掛清單的版號宣告。
|
2026-09-02 17:21:23 +08:00 |
|
|
jiantw83
|
d8aa0b1f5d
|
feat(patrol): 巡檢改組目錄頁區塊檔，輸出檔改名 contents-entry.md
一輪巡檢組給目錄頁的輸出，從一列 markdown 表格改成一整個大標題區塊：
`## {監控頁頁名}` 那一行、空行，然後每個欄位一條 `- {欄位名}：{值}`。輸出
檔跟著從 `contents.tsv` 改名 `contents-entry.md`，`contents_file=` 指向
新檔名。
目錄頁已經不放表格，再組出那一列就沒有地方放。舊檔名說的是逐欄對照的資料
檔，內容其實是一段 markdown，名不對實會讓呼叫端以為還能逐欄解析。改名讓
呼叫端契約的變動在檔名上就看得見，而不是同名檔悄悄換了格式——同名換格式
的話，還沒跟上的呼叫端會拿到讀得開卻意義全錯的內容。
新增 `oneline` 處理條列一條的值：換行一律壓成空白，因為一條條列裡的換行會
被讀成另一條，或者讓整個區塊提早結束；`|` 反而不跳脫，條列裡沒有切欄的
意思，跳脫過的符號會原樣顯示在頁面上。監控頁那一條的網址仍然留佔位，由
呼叫端換成真網址、驗過連得到才寫，這支腳本一頁都不寫。裸雜湊照樣留一條，
讓人不必從標題切字串就抄得到。
範圍是一輪巡檢給目錄頁的輸出檔。
|
2026-09-02 17:21:23 +08:00 |
|
|
jiantw83
|
311cdc611a
|
feat(wiki): 巡檢目錄頁改成一台機器一個大標題區塊
巡檢目錄頁的版面從 markdown 表格換成「大標題加條列」：一台機器一個大標題
區塊，標題就是那一台機器監控頁的實際頁名，欄位改成標題底下的一層條列。
範本、技能敘述、行為清單與說明文件一併跟上，目錄頁上不再留任何表格。
表格的欄位組合是整頁共用的，表頭跟著建頁那一台機器走，之後每一台只改自己
那一列。欄位一增減，只有跑到新版的機器寫得出新的格數，同一張表就混著兩種
格數，多出來的那一格對不到任何欄名，而目錄頁又沒有整頁改寫的路可以走——
整頁覆蓋等於刪掉別台機器的紀錄。條列一筆一個區塊，欄位各自獨立，加一條只
動到自己那一個區塊。
比對鍵從裸雜湊那一格改成大標題本身，標題寫成監控頁的實際頁名。頁名只由
主機名與登入帳號決定，換主機位址、換專用存取庫或換一種頁名編碼都動不到
它；含網址的那一條連結照樣留著給人點，但不當鍵。呼叫改成拿頁名當鍵，欄號
那個參數只在舊表格頁轉檔時用得到。範本原本用二階標題寫的說明區段全部搬進
引言，否則轉檔後會被當成一筆真紀錄讀進去。
範圍是助理的巡檢目錄頁與 assistant 技能的敘述。
|
2026-09-02 17:21:12 +08:00 |
|
|
admin
|
6fd987fc0e
|
Merge pull request '收尾寫一筆 skill-end 事件，執行狀態才回報得到助理' (#12) from feat/status-report into develop
Reviewed-on: #12
|
2026-09-02 08:04:03 +00:00 |
|
|
jiantw83
|
ed624e0743
|
chore(plugin 版本): 三份 manifest 升版至 0.1.4
|
2026-09-02 16:01:13 +08:00 |
|
|
jiantw83
|
3dac1475df
|
feat(狀態回報): 收尾寫一筆 skill-end 事件
現行紀錄只記「被叫用」，沒有成敗也沒有結束碼。跑完整輪的技能與開場就
中止的技能，在紀錄裡長得一模一樣。
start 由技能用量 hook 順手發，不必改技能文件。end 只能由技能自己在收尾
步驟寫——hook 接在技能工具呼叫上，而實際工作發生在之後的模型輪次，它在
原理上看不到成敗。有 start 沒有配對的 end，就是那一輪中止了。
status 五選一，每支技能各自寫明什麼情況選哪一個。找不到回報腳本就安靜
跳過，回報失敗一律不改變技能自己的結論。
|
2026-09-02 16:01:13 +08:00 |
|
|
admin
|
94566026c7
|
Merge pull request '連結一律寫成 [文字](絕對網址)，並在寫入前驗證連得到' (#11) from feat/link-verification/main into develop
Reviewed-on: #11
|
2026-09-02 06:46:35 +00:00 |
|
|
jiantw83
|
f2d30925f6
|
chore(plugin 版本): 三份 manifest 升版至 0.1.3
|
2026-09-02 14:27:18 +08:00 |
|
|
jiantw83
|
9ea83da38b
|
feat(link): 連結一律寫成 [文字](絕對網址)，寫入前先驗證連得到
取消 [[頁名]] 與 [[顯示文字|頁名]] 兩種同 wiki 寫法，不再分「同存取庫」與
「跨存取庫」兩條規則。那種寫法只在自己那個 wiki 內解析，寫錯不報錯，畫面上
看起來像普通文字或死連結，巡不到也修不了。
連結寫進頁面前先過 jsc-gitea 的 link-check.sh，結束碼 0 才寫。驗證一律走 API，
不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把
好連結判成壞的。認證失敗回 7，與死連結的 1 分開，免得金鑰一過期就把還在的頁
整批判死。
|
2026-09-02 14:27:18 +08:00 |
|
|
admin
|
4e87b1e662
|
Merge pull request 'feat(wiki): 監控目錄頁改走專用存取庫，比對鍵改用裸 HASH' (#9) from feat/wiki-contents-repo/main into develop
Reviewed-on: #9
|
2026-09-02 03:27:49 +00:00 |
|
|
jiantw83
|
4bf99dde76
|
feat(wiki): 監控目錄頁改走專用存取庫，比對鍵改用裸 HASH
What：MONITOR_CONTENTS 改由 wiki-repo CONTENTS 解析並透過 wiki-contents.sh
upsert 寫入，MONITOR_{HASH} 仍走 wiki-repo MONITOR。目錄頁新增一欄裸 HASH 當
比對鍵，第一欄的絕對網址連結留給人看。主機名一律取短名。
Why：目錄頁集中之後兩頁不再同庫，[[...]] 只在同一個 wiki 內解析，連結必須改絕對
網址。比對鍵原本是含網址的儲存格，換主機、換存取庫或 URL 編碼有差就比對不到，
巡檢每 15 分鐘寫一次，重複列會累積得很快。
How：目錄頁解不出存取庫時不再中止巡檢——那一頁只是索引，內容頁寫成就照樣寫心跳。
內容頁寫不成仍然中止且不寫心跳，自咬環的前提沒有鬆動。
Who：jsc-assist
|
2026-09-02 11:01:51 +08:00 |
|
|
admin
|
d349a76b9c
|
Merge pull request '讓排程輪次自己帶齊環境與權限，監控頁改成固定三塊，文件與三份外掛清單一併升到 0.1.1' (#7) from fix/unattended-patrol-round-env-and-permissions into develop
Reviewed-on: #7
|
2026-09-02 01:20:42 +00:00 |
|
|
jiantw83
|
02bfc70f4e
|
fix(assistant): 讓執行路徑走錯與警示原因都看得見
兩支腳本開跑就檢查自己的執行路徑，監控頁的摘要表與最新一輪那一塊補上
「警示來源」。
兩件都是實測之後補的。用全新的 CLI 行程跑，代理人會把工具路徑解回外掛
快取那一份，不是指定的工作樹那一份。原本的對策只在技能說明書裡寫明禁
止，那是文件約束，擋不住真的走錯的那一輪。權限閘門只放行 current 那一
組確切路徑，走錯就被靜靜擋掉，那一輪不寫心跳，外面只看得到心跳過期。
另一頭，沙箱跑出來的摘要列是「警示、四項全過、待人處理 0」，讀的人看
不出警示哪來。查過不是缺陷：四項來源都讀得到，是讀到的內容有警示。摘
要表的用途本來就是一眼看出從哪一輪開始壞，少了原因那一欄就做不到。
巡檢與排程兩支腳本開跑時先比對自己是不是從 current 底下被叫起來的，不
是就往 stderr 印一行警告，點名實際路徑、應該用的路徑與理由。刻意只警告
不中止：從工作樹直接跑腳本是開發時的正當用法，中止會把那條路擋掉，真
正的失敗本來就發生在權限閘門那裡。摘要表從四欄加到五欄，最新一輪那一
塊也補一列，值取每一處設警示時收下來的短理由，多個用頓號串，沒有就寫
「無」。腳本裡每一處把判定改成警示的地方，一律改走同一支函式順手收下
理由，collect 的輸出多印一行 warn_sources。技能主文、行為清單與監控頁
範本跟著寫明這兩件事。
功能範圍是助理的一輪巡檢與系統排程安裝。
|
2026-09-01 18:54:05 +08:00 |
|
|
jiantw83
|
2af9dda7a6
|
chore(manifest): 三份外掛清單升到 0.1.1
三份外掛清單的版本從 0.1.0 改成 0.1.1。
這一輪改了排程條目的組法、監控頁的格式與技能的工具路徑，三件都會影響
已經裝在機器上的那一份。版本不動，版本閘門就看不出哪台機器裝的是舊的
那一版，也提不出重啟要求，舊條目會繼續空轉到有人自己發現。
三份檔案只動 version 一欄，其餘不碰，三份保持同一個號碼，這樣不管從哪
一支 CLI 讀到的都是同一個答案。功能範圍是外掛的版本宣告。
|
2026-09-01 18:28:04 +08:00 |
|
|
jiantw83
|
a8e387ad50
|
docs(assistant): 文件跟上新的工具路徑與監控頁寫法
技能主文、行為清單、專案說明與界線文件一起改，對齊這一輪的排程修正與
監控頁改版。
工具路徑與監控頁寫法都換了，文件沒跟上就是照舊做法跑：用快取基底目錄
組出來的路徑會被權限靜靜擋掉，那一輪停在沒有人能回答的權限詢問；照舊
的附加語意寫頁，又會把剛換好的三塊寫回一輪一節。
技能主文的工具路徑一律改走 current 那一組不帶版本的路徑，新增 Tool
paths 一節列出四支工具，並寫明權限閘門只放行那一組，放行技能不等於放
行技能裡的每一個呼叫。監控頁那幾步改寫成讀回舊頁、基本資料原樣留著、
最新一輪整塊換掉、本輪摘要列擺最上面並截到 24 列，舊格式的頁第一次重
組要在回報裡說明。frontmatter 的 description 重寫並補上單引號，句中有
冒號不加引號會讓解析走偏。界線四從「只附加」改成三塊寫入語意。專案說
明與行為清單同步條目的環境快照、allow 規則、暫存檔名與可驗證跡象。
功能範圍是助理技能的文件與行為合約，不動任何腳本行為。
|
2026-09-01 18:28:04 +08:00 |
|
|
jiantw83
|
717a562cb7
|
refactor(patrol): 監控頁改成固定三塊
巡檢產出與監控頁範本改成固定三塊：本頁基本資料、最新一輪、近 24 輪摘要。
舊寫法是一輪附加一節。十五分鐘跑一輪，一天就疊出九十六節，那樣的頁沒
有人讀得完，也就沒有人會發現助理壞在哪一輪。軌跡留著卻沒人看，等於沒
有留。
基本資料建頁時寫一次就不動。最新一輪每輪整塊換掉，只留最新那一輪的完
整內容。摘要表一輪一列，最新的在最上面，超過 24 列就丟掉最舊的那一列，
一列只有四欄：巡檢時間、本輪判定、四項成敗、待人處理筆數，一眼看得出
是從哪一輪開始壞的。collect 的輸出鍵位跟著換，section_file 不再產出，
改印 latest_file、summary_file 與 summary_row_file，另外多印本輪待人處
理的筆數。範本連帶把流程圖與寫入規則改成先讀回舊頁、再三塊重組整頁寫
回，並寫明舊格式的頁第一次重組要怎麼收。
順手把腳本內部找別的 domain 工具的順序改成 current 連結優先，理由跟排
程那支一樣：技能與權限規則都以 current 為準，腳本自己去挑另一個版本就
會跑到混版的工具，而那種不一致查起來沒有線索。功能範圍是一輪巡檢的收
攏與監控頁產出。
|
2026-09-01 18:28:04 +08:00 |
|
|
jiantw83
|
3b86674d1b
|
fix(schedule): 讓排程那一輪自己帶齊環境與權限
排程條目改成自己帶齊執行環境，install 完也印出那一輪要開的權限規則。
背景助理在無人值守的輪次連續失敗，查出四道關卡。cron 給的 PATH 很短，
不含使用者的 bin 目錄，裸的指令名每一輪都是找不到執行檔。cron 也不讀
殼的設定檔，那一輪沒有 Gitea 主機位址與 wiki 存放庫變數，連不上 wiki。
寫入確認只認 tty，排程沒有 tty，寫監控頁一定被擋。工具權限沒開，巡檢
腳本連跑都跑不起來，而那一輪沒有人可以按同意。四關任何一關沒過，那一
輪就不寫心跳，排程裝著卻永遠空轉，外面只看得到心跳過期。
CLI 改用 command -v 解成絕對路徑再寫進條目，解不到就停下，不猜路徑。
install 當下把主機位址、金鑰、狀態根目錄、心跳門檻與所有已設定的 wiki
存放庫變數就地快照，以名稱等於值的前綴寫進條目，值裡的單引號照 POSIX
寫法跳脫。條目自帶寫入確認旗標，無人值守的那一輪本來就沒有人可以按同
意。install 完印出四支腳本各三種呼叫形式的 allow 規則，路徑一律取
current 那一組不帶版本的連結，並順手檢查連結在不在，不在只警告、不代
建。腳本內部找心跳腳本也改成 current 優先，避免同一輪跑到混版的工具。
條目裡帶著金鑰快照，所以印條目時一律把金鑰遮成星號，遮到下一個空白為
止；crontab 檔案要保持只有本人讀得到，這幾個變數改過就要重跑一次
install。功能範圍是助理的系統排程安裝、移除與查現況。
|
2026-09-01 18:28:04 +08:00 |
|
|
admin
|
0e5d93ccd9
|
Merge pull request '釋出助理主體、排程與一輪巡檢' (#5) from feat/assistant-body/main into develop
Reviewed-on: #5
|
2026-09-01 07:41:23 +00:00 |
|
|
admin
|
5a8766b2d6
|
Merge pull request 'feat/assistant-body/start-stop-status' (#4) from feat/assistant-body/start-stop-status into feat/assistant-body/main
Reviewed-on: #4
|
2026-09-01 07:24:29 +00:00 |
|
|
jiantw83
|
2b7176a644
|
feat(patrol): 一輪巡檢落地，心跳改由巡檢跑完才寫
What：
- 新增 tools/patrol.sh，三個子命令：collect 收集、finish 收尾、abort 中止。這一輪的巡檢項目是四項純讀取：使用統計、版本落差與重啟閘門、階段鎖與工作包鎖、心跳自述。
- 心跳的寫入從排程移到巡檢收尾。排程只呼叫巡檢，不再直接寫心跳。
- 排程週期由心跳門檻推導，不再寫死。install heartbeat 這個工作代號改為拒絕。
Why：
- 排程直接寫心跳的話，心跳新鮮只證明排程活著。巡檢整個壞掉、每輪都失敗，心跳照樣新鮮，閘門照樣放行，而且沒有任何錯誤訊息——這是無聲失效，是最難發現的一種。
- 改成巡檢寫，心跳新鮮才等於上一輪真的跑完了。閘門判的才是工作訊號，不是行程存活訊號。
- 門檻是讀取端的設定，心跳檔裡不存它。所以週期與門檻各寫死一個數字一定會撞：門檻五分鐘、巡檢十五分鐘，心跳永遠是過期的。
How：
- 週期取「滿足漏掉一輪還算新鮮、漏掉兩輪才過期」的最大值，並且要能整除一小時。要拉長巡檢週期就調大門檻，週期自動跟著長，兩個數字不會各走各的。
- 心跳只看「這一輪有沒有把結果記下來」，不看四項的成敗。四項有失敗但監控頁寫成了就寫心跳，頁上判定標警示；頁寫不成就中止，一定不寫，讓心跳自己過期。頁每輪都寫失敗卻照樣寫心跳，等於把這次要修掉的缺陷原封不動搬過去。
- 整輪拿一把目錄鎖，搶不到就讓開，不排隊也不並行。並行兩輪會在同一頁附兩節，還會互相蓋掉用量快照。鎖逾時可被下一輪搶走，被搶走的那一輪收尾時對不上就不寫心跳——它沒跑到底，不該蓋章。
- 任一項失敗不影響其餘項目。失敗要在監控頁上看得出來是失敗，不是沒資料；來源是空的則明寫「那是零次，不是故障」。
- 版本盤點照抄腳本原字。抄到查詢失敗就寫查詢失敗，不改寫成相符、也不自己補查遠端版本——查不到是沒有證據，不是版本沒問題。
Who：
助理落地的第四塊。排程那一輪留下的問題在這裡解掉了。
|
2026-09-01 15:06:10 +08:00 |
|
|
jiantw83
|
7343def16e
|
feat(schedule): 助理的系統排程接線
What：
- 新增 tools/schedule.sh，三個子命令：install 安裝、remove 移除、status 查現況。兩筆工作分別是每分鐘的心跳與每十五分鐘的巡檢。
- 助理主體的 start 接上安裝、stop 接上移除，行為清單與 README 跟著更新。
Why：
- 心跳要有人定時寫，不然啟動之後過幾分鐘就自己過期，助理看起來像沒在跑。
- 排程這件事有標準的輸入與輸出，準則要求下放腳本，技能只描述何時呼叫。
How：
- 條目行尾帶固定標記，安裝先濾掉自己的舊條目再追加。絕不覆寫整份排程，別人的條目一行都不碰；寫完回讀驗證，出現兩筆或別人的行數對不上就報錯。
- 裝完檢查排程服務在不在跑。這台機器是 WSL，預設不啟動 cron，裝了條目卻一次都不會執行——不檢查就會宣稱一件沒發生的事。
- 條目一律帶 </dev/null。排程是非互動環境，任何等輸入的東西都會把整筆卡死。
- 輸出寫到 JSC_HOME 底下，不寫進任何專案目錄，免得多出未追蹤檔污染別人的變更盤點。
- 巡檢那一筆預設不裝，要明著指定才會裝。巡檢本體還沒實作，裝了只會每十五分鐘失敗一次；巡檢指令也不猜 CLI，判不出來就停下，猜錯的代價是每十五分鐘跑一支不存在的執行檔。
- stop 先移除排程再清心跳，順序不能反。反過來的話清完下一分鐘排程就補寫一次，stop 等於騙人。
Who：
助理落地的第三塊。這裡留下一個要在巡檢那一輪解掉的問題：心跳目前由排程直接寫，所以心跳新鮮只證明排程活著，不證明助理做了事。往後應該改由巡檢跑完那一輪去寫，心跳才等於工作訊號。限制已寫進技能內文與說明文件。
|
2026-09-01 14:34:12 +08:00 |
|
|
jiantw83
|
fbf3e5a605
|
feat(assistant): 助理主體收攏 start、status、stop 三個操作
What：
- 新增 assistant 技能，提供啟動、查現況、停止三個操作。
- 刪掉原本獨立的 status 技能，行為清單與 README 的技能目錄一起改。
- 三份 manifest 的版本一起提升，對 jsc-hooks 的下限提到含心跳腳本的那一版。
Why：
- 助理的生命週期是一件事，拆在兩支技能裡，靠描述自動觸發的 CLI 等於擲骰子挑一支。準則也明寫技能目標不得重複。
- 刪除的代價這時候最低：這個 domain 才剛落地，status 是它唯一一支技能，除了自己的文件沒有別的東西指向它。晚一步等各處都引用了再收攏，成本差很多。
How：
- 心跳的判定一律交給 jsc-hooks 的心跳腳本，三個操作都讀它的回報，不自己解析心跳檔。判定有兩份就會漂移，狀態與訊息就會對不上。
- 那支腳本的每一個結束碼都在技能裡有明確處置，包含「腳本自己沒跑起來」那一種——那時候既不能說助理在跑，也不能說助理停了。
- 時間戳壞掉一律當成不新鮮，絕不退回判成新鮮。
- 異常結束不需要額外的清理機制：心跳是時間戳，過了門檻自動失效。反過來說，stop 以外的任何路徑都不該寫心跳，否則就是留一個假心跳。
- stop 清心跳是它的職責，不算助理界線裡「不刪狀態檔」那一條。技能內文把這個例外寫明白，免得日後照界線把 stop 砍掉。
- stop 的收尾同時講兩件事：心跳清掉之後閘門會擋下技能呼叫，以及閘門目前還沒接線所以這一刻擋不到誰。前者是設計後果，停助理的人一定要知道；後者不講就是說一件還沒成真的事。
- 排程這一輪不做，start 只寫第一次心跳，並講明心跳不會自動更新。
Who：
助理落地的第二塊：心跳有了，接著要有人寫它、讀它、清它。
|
2026-09-01 14:19:24 +08:00 |
|
|
admin
|
4b0e4d796c
|
Merge pull request '釋出 jsc-assist 0.0.2：助理 domain 落地與 status 技能' (#2) from feat/assistant-domain-bootstrap/main into develop
Reviewed-on: #2
|
2026-09-01 04:42:50 +00:00 |
|
|
admin
|
f09830a636
|
Merge pull request 'feat/assistant-domain-bootstrap/init-and-status-skill' (#1) from feat/assistant-domain-bootstrap/init-and-status-skill into feat/assistant-domain-bootstrap/main
Reviewed-on: #1
|
2026-09-01 04:27:21 +00:00 |
|
|
jiantw83
|
e7e9b8ce18
|
feat(templates): 新增監控頁的目錄頁與內容頁範本
What：
- 新增 templates/monitor-contents.md 與 templates/monitor-page.md。
- README 的「參考與工具」表補上這兩份範本，說明欄寫出兩者相反的寫入語意。
- 三份 manifest 的版本一起提升。
Why：
- 監控頁是助理巡檢結果的落點。沒有範本，每次巡檢寫出來的格式都不一樣，累積久了看不出趨勢，也對不起來。
- 兩份範本的寫入語意剛好相反，必須各自寫明白。目錄頁是共用的，一列代表一台機器，整頁覆蓋會刪掉別台機器的紀錄；內容頁只屬於一台機器，記的是歷次巡檢的軌跡，所以附加不覆寫。
How：
- 目錄頁範本帶欄位說明與寫入規則：比對主機與帳號兩欄，只更新自己那一列，讀不到舊內容就中止，不硬寫。
- 內容頁範本一次巡檢附加一節，節標題帶時間戳，涵蓋心跳與閘門、使用統計、hook 錯誤、版本落差、階段鎖與工作包鎖、待辦簿到期與逾期六類結果。
- 連續失敗的項目一定要標「已連續失敗 N 次」。待辦簿的項目失敗不會自動暫停，會每輪重試，不標出來就是一個壞掉的項目一直重試而沒人知道。
- 內容以圖表優先，流程用 mermaid、結果用表格，純文字每節最多三句。
Who：
技能助理落地帶出來的頁型別需求，四個存放庫同一批改。
|
2026-09-01 12:11:26 +08:00 |
|
|
jiantw83
|
814f28a6b8
|
chore(marketplace): 把 jsc-assist 登錄進統一 marketplace
What：
- 兩份 marketplace 檔各加一個 jsc-assist 條目，來源網址指向 assist 存取庫。
Why：
- 準則要求每個 domain 存取庫都帶同一份 marketplace 檔，任何一個存取庫都能當註冊入口。少了這個條目，各 CLI 的安裝指令找不到 jsc-assist，sync-domains 也不會把它同步下來。
How：
- 條目由 meta 的 sync-marketplace.sh 產生，同時寫進正本與每個 domain 存取庫的副本，寫完逐檔比對位元組。這一支存取庫的兩份副本就是那一輪的產物。
- 條目依名稱排序，縮排與非 ASCII 描述的處理都交給同一支腳本，不手改 JSON。
Who：
助理 domain 落地的註冊步驟，其餘 domain 存取庫的同一份副本另外送出。
|
2026-09-01 11:21:03 +08:00 |
|
|
jiantw83
|
6e18a373f3
|
feat(assist): 樣板改成 jsc-assist domain，加上 status 技能
What：
- 三份 manifest 的 name 由 jsc-template 改成 jsc-assist，version 設為 0.0.1，description 改寫成助理的定位，並加上 jsc.requires 宣告對 jsc-cli、jsc-gitea、jsc-hooks、jsc-log 的最低版本。
- README.md 與 AGENTS.md 依 meta domain 的格式重寫，AGENTS.md 多一節「助理的界線」。
- 刪掉樣板的 hello 技能，新增 status 技能與 references/behaviors.md 行為清單。
Why：
- 這個存取庫原本整份是 template 的樣板，四份 manifest 都還叫 jsc-template。名字沒改，marketplace 認不出它是獨立的 domain，各 CLI 也裝不上。
- 助理的閘門、心跳與巡檢要有落點，前提是存取庫先認得出自己。
- 樣板的 hello 技能只是安裝驗證用，留著會讓助理的技能清單從第一天就帶著一支沒有用途的技能。換成唯讀的 status，行為檢查與 frontmatter 檢查也才有掃描對象。
How：
- status 全程唯讀：讀心跳檔判斷助理在不在跑，判準只看時間戳距現在是否不到 300 秒，不看 pid 存活——五支 CLI 與容器裡的行程互相看不到彼此的 pid。
- 心跳檔不存在時印「助理未運行」，這是正常結果，不以非 0 結束。
- 這支不新增 tools/ 腳本。讀兩個路徑印一張表還不到抽腳本的門檻，助理主體落地時再一併評估。
- 三份 manifest 的 version 由 sync-skill-manifest.sh 同步，README 的技能目錄區塊一起更新。
Who：
助理 domain 落地的第一步，後續的閘門、心跳與排程都接在這個基礎上。
|
2026-09-01 11:20:52 +08:00 |
|
|
jiantw83
|
7790283920
|
Initial commit
|
2026-08-31 09:49:28 +00:00 |
|