jiantw83
a3ef205489
現行紀錄只記「被叫用」，欄位是 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，就是那一輪中止了。
131 lines
5.6 KiB
Bash
Executable File
131 lines
5.6 KiB
Bash
Executable File
#!/usr/bin/env sh
|
||
# report-status.sh — 技能與 hook 的執行狀態事件流。
|
||
#
|
||
# 為什麼要有這支：現行 usage/skills.jsonl 只記「被叫用」，欄位是 {ts,cli,session,skill}，
|
||
# 沒有成敗、沒有結束碼。跑完整輪的技能與開場就中止的技能，在紀錄裡長得一模一樣。
|
||
# hook 成功時更是完全不留紀錄，只有錯誤路徑會寫 wiki，而那條路徑刻意不自動觸發。
|
||
#
|
||
# 為什麼不直接寫 wiki：hook 每次提示都跑，網路寫入會拖垮宿主 CLI；失敗的 hook 自我回報
|
||
# 還會疊出迴圈。所以一律先寫本機事件流，助理巡檢時排空、彙整、寫 MONITOR 頁。
|
||
#
|
||
# 用法:
|
||
# report-status.sh skill-start <名稱>
|
||
# report-status.sh skill-end <名稱> <status> [結束碼] [detail]
|
||
# report-status.sh hook-end <名稱> <status> <結束碼> [detail]
|
||
# report-status.sh drain # 印出上次排空之後的新事件
|
||
# report-status.sh rotate # 超過上限就輪替，只留一份舊的
|
||
#
|
||
# <名稱>: 技能寫 {domain}:{skill}，hook 寫 {腳本檔名} 加子命令，例如 sdlc-gate check。
|
||
# <status>: ok、blocked、failed、degraded、aborted 五選一。
|
||
# ok 完成條件全部達成
|
||
# blocked 被閘門或前置條件擋下，沒有做事
|
||
# failed 做到一半失敗
|
||
# degraded 做完了但有部分沒達成
|
||
# aborted 使用者中止，或前提不成立而主動停止
|
||
#
|
||
# 規則:
|
||
# - 三個記錄子命令一律回 0，寫檔失敗也是 0。回報機制自己壞掉，不可以讓被回報的東西
|
||
# 跟著壞——hook 的結束碼是閘門的判準，被記錄動到就等於閘門行為被記錄改寫。
|
||
# 參數檢查是例外：那是呼叫端的程式錯誤，寫進去只會汙染事件流，所以先擋下來。
|
||
# - 本檔不讀 stdin。技能由 Bash 呼叫它，stdin 可能是還沒關閉的管線，讀下去會卡住宿主。
|
||
# 所有資訊一律走參數。
|
||
# - 輪替不放在每次寫入。每次提示都寫事件，順手 stat 一次檔案就是每次提示多一次系統呼叫；
|
||
# 改由巡檢排空之後呼叫 rotate，成本落在本來就週期性執行的地方。
|
||
#
|
||
# 結束碼: 0=成功（記錄子命令一律 0） 2=用法錯誤 3=drain 沒有新事件
|
||
set -eu
|
||
|
||
HERE=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
|
||
# lib.sh 在同一個存取庫，不是跨 plugin 依賴。hook 必須自足，事件寫入的函式因此留在 lib.sh，
|
||
# 這支只是把它包成命令列介面給技能用。
|
||
STDIN_JSON=""
|
||
. "$HERE/../hooks/lib.sh"
|
||
|
||
EVENTS="$JSC_HOME/usage/events.jsonl"
|
||
OFFSET="$JSC_HOME/usage/scan-state/events.offset"
|
||
MAX_BYTES=5242880
|
||
|
||
usage() {
|
||
cat >&2 <<'EOF'
|
||
用法:
|
||
report-status.sh skill-start <名稱>
|
||
report-status.sh skill-end <名稱> <status> [結束碼] [detail]
|
||
report-status.sh hook-end <名稱> <status> <結束碼> [detail]
|
||
report-status.sh drain
|
||
report-status.sh rotate
|
||
|
||
status: ok、blocked、failed、degraded、aborted
|
||
結束碼: 0=成功 2=用法錯誤 3=drain 沒有新事件
|
||
EOF
|
||
exit 2
|
||
}
|
||
|
||
valid_status() {
|
||
case "$1" in
|
||
ok|blocked|failed|degraded|aborted) ;;
|
||
*) echo "[jsc][狀態回報][ERR]：status 須為 ok、blocked、failed、degraded、aborted 五選一，收到「$1」。" >&2; exit 2 ;;
|
||
esac
|
||
}
|
||
|
||
valid_exit() {
|
||
case "$1" in
|
||
''|*[!0-9]*) echo "[jsc][狀態回報][ERR]：結束碼須為非負整數，收到「$1」。" >&2; exit 2 ;;
|
||
esac
|
||
}
|
||
|
||
cmd="${1:-}"; [ -n "$cmd" ] || usage
|
||
shift || true
|
||
|
||
case "$cmd" in
|
||
skill-start)
|
||
name="${1:-}"; [ -n "$name" ] || usage
|
||
# start 沒有成敗可言，狀態欄固定 ok、結束碼固定 0。判讀靠的是「有沒有配對的 end」：
|
||
# 有 start 沒 end 就是中止，那正是現行紀錄分不出來的那一種。
|
||
emit_event skill "$name" start ok 0
|
||
;;
|
||
skill-end)
|
||
name="${1:-}"; status="${2:-}"
|
||
[ -n "$name" ] && [ -n "$status" ] || usage
|
||
valid_status "$status"
|
||
code="${3:-0}"; valid_exit "$code"
|
||
emit_event skill "$name" end "$status" "$code" "" "${4:-}"
|
||
;;
|
||
hook-end)
|
||
name="${1:-}"; status="${2:-}"; code="${3:-}"
|
||
[ -n "$name" ] && [ -n "$status" ] && [ -n "$code" ] || usage
|
||
valid_status "$status"; valid_exit "$code"
|
||
emit_event hook "$name" end "$status" "$code" "" "${4:-}"
|
||
;;
|
||
drain)
|
||
[ -f "$EVENTS" ] || exit 3
|
||
size=$(wc -c < "$EVENTS" 2>/dev/null || echo 0)
|
||
old=0
|
||
[ -f "$OFFSET" ] && old=$(cat "$OFFSET" 2>/dev/null || echo 0)
|
||
case "$old" in ''|*[!0-9]*) old=0 ;; esac
|
||
# 檔案比已存位移還小就是輪替過，從頭讀。不比對 inode：五支 CLI 與容器裡的行程
|
||
# 看到的 inode 不保證一致，用大小判斷才在每個環境都成立。
|
||
[ "$size" -lt "$old" ] && old=0
|
||
[ "$size" -eq "$old" ] && exit 3
|
||
mkdir -p "$(dirname "$OFFSET")" 2>/dev/null || true
|
||
# tail -c +N 從第 N 個位元組起（1 起算），所以位移要加一。
|
||
# 不用 dd bs=1 skip=：那是一個位元組一次系統呼叫，位移到了幾 MB 就是幾百萬次，
|
||
# 每輪巡檢都排空一次的話會慢到不能用。
|
||
tail -c "+$((old + 1))" "$EVENTS" 2>/dev/null || true
|
||
printf '%s' "$size" > "$OFFSET" 2>/dev/null || true
|
||
;;
|
||
rotate)
|
||
[ -f "$EVENTS" ] || exit 0
|
||
size=$(wc -c < "$EVENTS" 2>/dev/null || echo 0)
|
||
if [ "$size" -gt "$MAX_BYTES" ]; then
|
||
mv "$EVENTS" "$EVENTS.1" 2>/dev/null || true
|
||
: > "$EVENTS" 2>/dev/null || true
|
||
# 位移歸零：新檔從頭算起，不歸零的話下一次 drain 會跳過開頭那一段。
|
||
printf '0' > "$OFFSET" 2>/dev/null || true
|
||
printf '已輪替：%s -> %s.1（原大小 %s 位元組）\n' "$EVENTS" "$EVENTS" "$size"
|
||
fi
|
||
;;
|
||
*) usage ;;
|
||
esac
|
||
|
||
exit 0
|