plugins/hooks
2
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
219 Commits 12 Branches 0 Tags
28fd6664b698272f6edc249a504e9d5e057bac19
Commit Graph
14 Commits
Author SHA1 Message Date
jiantw83andClaude Opus 5 cd4cd8b936 feat(hooks): 工作階段開始時把助理的未讀提醒帶到前景 
助理算得出哪幾筆到期、哪幾筆逾期，但那些結果只寫在監控頁上——人要自己
去翻，或自己跑一次狀態查詢。這一支把它帶到前景。

session-reminder.sh 只讀助理那一輪寫好的提醒佇列，一個判定都不做。
自己拿 due 欄與 next_run 去跟現在比就是第二套到期判定，跟助理那一套遲早
對不上，而對不上的那一天兩邊都說自己是對的。它也要快：這一支跑在每一個
工作階段的開頭。

只印佇列換來一個新的失效模式，正面處理：助理停了，佇列就不再更新，而一份
舊佇列讀起來跟新的一模一樣。所以佇列檔頭帶那一輪的時間戳與 epoch，這裡
算出它多舊；超過心跳門檻或心跳不新鮮，就明說這批提醒是多久以前算的、
助理現在的心跳是什麼狀態。門檻與狀態都取 heartbeat.sh 印的那一行。

佇列空又過期的那一種分兩路：待辦簿有東西才說話，零筆就安靜——人自己按停
也算零筆那一種，對著一個刻意的決定每個工作階段催一次是噪音不是提醒。
助理狀態目錄根本不存在時整支安靜退出，那台機器從沒啟動過助理。

一個工作階段只提一次，記號是 sessions/{代號}.reminded。接不到 session id
的 CLI 全部共用 default，所以 session-timer.sh 的 restart 分支順手清掉那個
記號——不清的話那支 CLI 從第二個工作階段起再也收不到提醒。清除掛在那裡
不掛在這裡：「這是不是新的工作階段」的判準只有那一支知道。

接線與檢核一起改，不留一支沒人驗的 hook：hooks.json 與推導出來的
codex-hooks.json 各加一條、kiro 的 agentSpawn 加一條、claude 的 status
逐支列舉加一項、冒煙測試加一條並把預期條數從 17 改成 18、執行期錯誤掃描
的 jsc 判定加一支腳本名，還有散在文件與回報字串裡的「九支 hook」十處
全部改成十支。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-07 11:14:41 +08:00
jiantw83andClaude Opus 5 5493539046 Merge develop 
三份 manifest 取 develop 的版號再往上升一版。

行為清單那一節第二次解：另一張同樣動這一節的先合併了，所以基底換過，重新
比對一次。這一次 develop 那一邊多了收尾事件的說明，分支這一邊還是「目錄頁
從表格列改成大標題區塊」。逐列用差異區間比對過，兩邊在共同基底上動到的位置
仍然完全不重疊，所以照基底的座標把兩組改動一起套回去。

合完之後三方的內容都在：這張的區塊語意、另一張的收尾事件、develop 的根目錄
解析。技能本文這一次自動合併就過了，沒有衝突。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-07 09:16:22 +08:00
jiantw83andClaude Opus 5 7f6e0d9299 Merge develop 
三份 manifest 取 develop 的版號再往上升一版：分支停在一個比 develop 舊的版號。

行為清單那一節四列兩邊都改過，但改的是不同層面：分支改「目錄頁怎麼寫」——索引
從表格列變成一個報告一個大標題區塊、寫入語意委派給共用工具；develop 改「根目錄
怎麼解」——前置步驟解出兩條字面絕對路徑再拿去叫工具。逐列用差異區間比對過，
兩邊在共同基底上動到的位置完全不重疊，所以照基底的座標把兩組改動一起套回去，
不是取其中一邊。

技能本文那一段同理：分支把整段改寫成區塊語意，develop 只在指令路徑前面補了
根目錄前綴。取分支那一版再補上前綴。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-07 09:10:57 +08:00
jiantw83andClaude Opus 5 f1255038f6 Merge develop 
三份 manifest 取 develop 的版號再往上升一版：分支停在一個比 develop 舊的版號，
取它等於把版號往回退。

行為清單兩支技能的節整節取 develop 那一版，再把分支新增的收尾說明逐段原文
接回去。develop 那一邊在這條分支開出去之後改寫了根目錄解析與外部呼叫兩欄，
分支那一邊只在關鍵步驟與可驗證跡象兩欄的尾端附加收尾事件的說明——兩件事互不
相干，取任一邊都會弄丟另一邊。

解這一段時弄壞過一次：第一版拿字元級差異把新增片段逐塊疊回去，中文被切碎重組，
「決定結局的那支工具的結束碼」變成「決定結局的那工具的結束碼」，關鍵步驟那一
整列還整列消失。行為清單檢核抓到表格只剩四列才發現。改成整節從 develop 重取、
只接分支相對它自己基底的那一段尾端附加，切點在共同前綴的盡頭，不切中文。

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
 2026-09-07 09:08:36 +08:00
jiantw83 95c7bb1eee fix(lib): 跨外掛路徑解析改實體解析，修好版本閘門 
版本閘門對 11 個 domain 全部回「查詢失敗」，等於完全失效——它擋不下任何版本落後的技能呼叫，而且是無聲的：report 照印表格，只是每一列都寫查詢失敗。

根因是 jsc_gitea_sh 回傳的路徑帶著 ..，而那些 .. 要穿過 current/jsc-hooks 這條符號連結。兩種解析方式對它的答案不同：核心與 [ -f ] 用實體解析、跟著連結走，判定檔案存在；shell 的 cd 用邏輯解析、純文字消去 ..，落到一個不存在的目錄。所以 [ -f ] 檢查通過、路徑交了出去，gitea.sh 的 cd 卻失敗，回結束碼 2 與空輸出，呼叫端就判成查不到。

新增 jsc_abs_path，用 cd -P 加 pwd -P 把路徑正規化成不含 .. 的實體路徑。挑這個做法是因為兩者都是 shell 內建，不必在 PATH 上找執行檔——這些函式會在 cron 那種只剩幾段 PATH 的環境下跑，少一個外部相依就少一個解不出來的理由。jsc_gitea_sh 的四條候選改成尾端統一正規化，正規化失敗就退回原樣路徑，「找得到」的判準不變。

wire-cli.sh 的 HERE 與 ROOT 一併改成實體解析。那是同一個根因的另一種發作方式：ROOT 會被 ln -sfn 當成目標，而這支腳本常常就是經由那條連結被叫起來的，邏輯解析會讓 ROOT 等於連結自己，連結被改成指向自己，全機器 hook 一起失效。這件事實際發生過。原本靠兩道防線擋著：事後的 [ -f ] 檢查，以及文件要求呼叫端先解出實體根目錄。前者要等連結已經被寫壞才攔得到，後者靠人記得。改成實體解析之後這個失敗模式不可能成立。

行為契約第 10 列跟著改：從實體根目錄跑 wire-cli.sh 的規定保留，但性質從必要條件降成多一層保險，並寫明保險為什麼還值得買——舊版腳本還在別的機器上跑。

驗證用同形佈局做：暫存區搭一套一樣形狀的連結農場，先塞原版重現失敗、再塞改版確認修好。真實環境的連結與快取全程沒有動過。
 2026-09-03 12:19:27 +08:00
jiantw83 221dca70e6 fix(behaviors): repair 的可驗證跡象補上收尾事件 
行為清單檢查拿 HEAD 的內容跑就過不了，它點名 repair 那一列的可驗證跡象沒寫到收尾的 skill-end 事件。這是既有欠帳，跟這一批的路徑處理沒有關係，所以單獨一筆，之後要回退哪一邊都不會牽連另一邊。

補上的內容照準則寫：收尾在本機事件流留下這一輪的 skill-end，status 從 ok、blocked、failed、degraded、aborted 五個裡取一個，中途停下的那幾輪也照寫——只有 start 沒有配對的 end，會被讀成中斷。

受影響的是驗收 repair 有沒有跑完的人，還有把行為清單檢查掛在流程裡的每一個存放庫。
 2026-09-03 10:32:22 +08:00
jiantw83 358c30c7b8 fix(hooks-install): 腳本呼叫一律寫成執行期解出的字面絕對路徑 
無人看管的輪次會在第一支腳本就被擋下，整輪還沒開始就結束。2026-09-02 到 09-03 以非互動模式比照排程環境實測七種寫法，結論很乾淨：權限層比對的是還沒展開的字面字串，帶變數或帶波浪號的路徑一律解不出來，一律要人核准；路徑中段的萬用字元也不匹配，所以帶版本號的快取路徑放不進允許清單。連 readlink、ls 這種只讀指令都要有自己的規則。放寬允許清單救不了這件事，只有把路徑寫成字面絕對值才跑得動。

技能因此多兩節。路徑守則寫明每一次腳本呼叫都要是字面絕對路徑，並說清楚為什麼不能為了可攜性換回變數寫法——變數寫法買不到可攜性，只買到一輪還沒跑到第一階段就死掉。前置步驟把可攜性挪到執行期：兩個根目錄各以 readlink 解一次，只在這裡解，之後不重解，也不為此新增腳本。主代理人解完把兩條字面路徑交給每一個 sub agent，sub agent 自己不解。技能內九處腳本呼叫都改成由這兩個根目錄開頭。

兩條 readlink 各自在同一步用 [ -d ] 查過印出來的目錄真的存在。JSC_HOME 沒設時第一條會印出 /current、結束碼 0，非空又是絕對路徑，只查前三項擋不下來。

解兩個根目錄不是重複。連結農場根目錄給跨 domain 呼叫用；jsc-hooks 的實體根目錄只給接線腳本用，而這一條的理由與權限無關：那支腳本從自身位置推出自己的根目錄，又會改寫自己正踩著的那條連結。走連結跑下去，連結會被指向自己，全機器的 hook 一起失效——這件事實際發生過。

存放庫自帶的 hook 設定檔刻意保留變數寫法，技能文件也把這個例外寫明。那是檔案內容，由 hook 自己的 shell 在執行當下展開，不經過權限層，也不是誰在提示裡打出來的路徑；改成實體路徑等於把某一台機器的路徑寫死進要發佈的檔案。

行為清單的 hooks-install 四列跟著校準。

受影響的是每一個跑 hooks-install 的人，最直接的是排程觸發、沒有人在旁邊核准的那些輪次。
 2026-09-03 10:32:22 +08:00
jiantw83 02caedf91e feat(異常目錄頁): 索引改成 H2 區塊條列並委派共用工具 
What：
異常目錄頁的版面從 markdown 表格改成一筆異常一個 H2 區塊，標題就是那一筆的異常頁頁名，時間、頁名、存取庫名稱、觸發 hook、退出碼、摘要六個欄位改成標題底下的一層條列，頁上不再留任何表格。失敗回報腳本不再自己讀回舊頁、附加新列、整頁寫回，改成只組出自己那一個區塊，交給 jsc-gitea 的目錄頁工具做讀回、比對與整頁寫回。範本、技能敘述、行為清單與說明文件一併對齊。

Why：
目錄頁有十幾份，各自在自己的腳本裡寫一套「讀得回舊內容才寫」的判斷，錯一次就少一筆紀錄，而且每一頁長出來的樣子都不一樣。版面與寫入語意收回一份正本之後，改一次全部跟著改。表格欄位遇到換行或半形豎線還會被切斷，條列沒有這個問題。

How：
失敗回報腳本移除目錄專用存取庫的解析與整頁組裝，改為組出區塊檔之後呼叫共用工具的 upsert，並依它的結束碼分流：3 是目錄頁的存取庫沒設定，找不到那支腳本也走同一條，兩者都只寫異常頁、跳過目錄頁、仍回 0；其餘非零一律以 4 回報。摘要不再替換半形豎線，改成把換行併成一行。傳進去的欄位序號 2 指舊表格版持有內容頁連結的那一欄，只供舊頁自動轉條列時取標題用。

Who：
使用 jsc-hooks 失敗回報流程的操作者，以及所有讀異常目錄頁追問題的人。
 2026-09-02 18:01:33 +08:00
jiantw83 4afb282c78 feat(狀態回報): 兩支技能的收尾寫一筆 skill-end 
hook 在原理上看不到技能的成敗：它接在技能工具呼叫上，而實際工作發生在
之後的模型輪次。start 由技能用量 hook 順手發，end 只能由技能自己寫。
有 start 沒有配對的 end，就是那一輪中止了。
 2026-09-02 16:05:54 +08:00
jiantw83 a3ef205489 feat(狀態回報): 技能與 hook 的執行結果寫進本機事件流 
現行紀錄只記「被叫用」，欄位是 ts、cli、session、skill，沒有成敗也沒有
結束碼。跑完整輪的技能與開場就中止的技能，在紀錄裡長得一模一樣。hook
成功時更是完全不留紀錄，只有錯誤路徑會寫 wiki，而那條路徑刻意不自動觸發。

事件流走本機檔案，不直接寫 wiki。hook 每次提示都跑，網路寫入會拖垮宿主
CLI；失敗的 hook 自我回報還會疊出迴圈，既有的錯誤回報因此不接在失敗的
hook 上，這裡沿用同一條線。助理巡檢時排空、彙整、寫頁。

hook 端用 EXIT trap 接，一支只加一行。這幾支的 exit 點很多，階段閘門一支
就有五十幾個；逐點改要動到每一條判定路徑，而那些路徑正是閘門的判準，為了
加一行紀錄去動閘門，風險遠大於收益。trap 涵蓋每一條離開路徑，含中途失敗。

狀態預設由結束碼推，推不出來的由 hook 自己覆寫。相依版本檢查與兩道閘門有
這種情形：antigravity 走 deny JSON、kiro 只印警告，兩者擋下時結束碼都是 0，
單看結束碼會把擋下記成放行。

技能的 start 由既有的技能用量 hook 順手發，不必改任何技能文件。end 只能由
技能自己在收尾步驟寫——hook 觸發時技能的實際工作還在後面的模型輪次，看不到
成敗。有 start 沒有配對的 end，就是那一輪中止了。
 2026-09-02 15:40:17 +08:00
jiantw83 096a85e638 feat(link): 連結一律寫成 [文字](絕對網址)，寫入前先驗證連得到 
取消 [[頁名]] 與 [[顯示文字|頁名]] 兩種同 wiki 寫法，不再分「同存取庫」與
「跨存取庫」兩條規則。那種寫法只在自己那個 wiki 內解析，寫錯不報錯，畫面上
看起來像普通文字或死連結，巡不到也修不了。

連結寫進頁面前先過 jsc-gitea 的 link-check.sh，結束碼 0 才寫。驗證一律走 API，
不看網頁狀態碼：私有存取庫的網頁網址對未登入請求一律回 404，拿狀態碼判會把
好連結判成壞的。認證失敗回 7，與死連結的 1 分開，免得金鑰一過期就把還在的頁
整批判死。
 2026-09-02 14:27:18 +08:00
jiantw83 f4871afd19 feat(wiki): 異常目錄頁改走專用存取庫，並修正目錄列連結恆空 
What：ERROR_CONTENTS 改由 wiki-repo CONTENTS 解析，ERROR_{HASH} 仍走
wiki-repo ERROR，兩者是兩個不同的存取庫。目錄列的連結改用 wiki-url 的絕對網址。
註解掃描的頁面編號樣式補上 40 碼與 H 加 7 碼兩種形狀。

Why：目錄列的網址原本在異常頁寫入之前就取，而頁名的雜湊帶時間戳、每次都是全新頁，
那時查一定是 404，又被吞掉，所以那一格一直都是空的。註解掃描原本只收 8 碼純十六進位，
舊演算法有十三個首碼會改寫成 H 開頭，等於對絕大多數舊頁編號漏偵測。

How：降級語意分兩層——異常頁的存取庫解不出來就整支安靜降級，只有目錄頁解不出來就
只寫異常頁、跳過索引，兩種都維持 exit 0。「只有 exit 4 才准建新頁、7 與 8 一律中止」
那段原樣保留，那是防止把金鑰失效讀成頁面不存在、拿範本蓋掉整頁既有列。

Who：jsc-hooks
 2026-09-02 11:30:49 +08:00
jiantw83 f586a6b69f docs(hooks): 同步四支 CLI 的接線位置與驗證等級 
What：README.md、references/behaviors.md 與 skills/hooks-install/SKILL.md 同步這一批的接線事實。

Why：
- 文件寫著「這些 CLI 沒有 pre-tool hook」。那句話是錯的，也正是三支 CLI 長期沒有守門的原因。照著它報告，會讓使用者以為只有 claude 有保護、其餘四支本來就接不上。
- kiro 的 degraded 原本被寫成接線缺東西，實際上是那支 CLI 擋不下技能叫用。兩件事的處理方式完全不同。

How：
- 一支 CLI 一列，列出接線位置、事件與 matcher、阻擋形態與判定，並寫明 claude、codex、copilot、antigravity 回 wired，kiro 回 degraded。
- 新增驗證等級表，把「形狀」與「觸發」分開記：形狀是那支 CLI 真的讀得懂設定，觸發是 hook 真的被叫用過。copilot 的形狀未證、antigravity 與 codex 的觸發未驗證，一律照實列出，不含糊帶過。
- README 補上 hooks/skill-name.sh 與 hooks/deny.sh 兩列，並補 COPILOT_HOME、KIRO_HOME、JSC_ANTIGRAVITY_HOOKS、JSC_COPILOT_INSTRUCTIONS、JSC_ANTIGRAVITY_RULES 幾個環境變數。
- kiro 的接線位置從 .kiro/hooks/jsc-hooks.json 全面改寫成 ~/.kiro/agents/jsc.json。
- 講明 write-guard.sh 三個模式與 SDLC 模型鎖在另外三支上是「還沒接」，不是「沒有 hook 可接」。
- behaviors.md 的完成條件與可驗證跡象跟著改，repair 那一列加上「技能名解析改 skill-name.sh、阻擋形態改 deny.sh，兩支是唯一真實來源」。

Who：codex、copilot、antigravity、kiro 四支 CLI 的 pre-tool hook 接線修正。
 2026-08-31 19:05:48 +08:00
jiantw83andClaude Opus 5 63c8073be1 docs(references): 新增技能行為清單，作為技能驗證的比對基準 
新增 references/behaviors.md，逐支列出本存取庫 hooks-install 與 repair
兩支技能的行為：觸發時機、關鍵步驟、外部呼叫、完成條件與可驗證跡象。

技能驗證原本沒有一份基準可比。驗的人只能回頭讀技能內文，讀到的是當下的
寫法，不是講好的行為；技能改壞了、少走一道關卡，比對不出來。

一支技能一張表，一項一列，內容寫成看得出對錯的敘述，可驗證跡象逐條指到
磁碟上真的留得下的東西。技能異動時，在同一個 PR 內一起更新這一頁。

所屬功能：技能驗證基準。

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
 2026-08-31 13:41:25 +08:00