信標多報三件雲端會壞掉的事:版本落差/舊複本遮蔽正門/退役機制的殘骸(inkstone/ISEP#90 ②③)

信標原本只證明「有一份 plugin 載入了」,不證明「載入的是哪一份」——
2026-08-27 雲端載的是 0.3.9、main 是 0.9.0,中間差 7 個 release,而它照樣是綠的。
那個看不見的落差的實際後果:0.3.9 裡還活著兩支 v0.9.0 已整支刪掉的 hook,
於是 .claude/pending-verification/ 被清掉之後又長回來。

三格(都只報告、不擋、拿不到答案就閉嘴):
· 版本落差:匿名讀 ISEP main 的 plugin.json(D20 判準下屬於「讀」),快取 6 小時、
  逾時 6 秒。落後就講清楚差幾版與怎麼修,並指向 inkstone/ISEP#67。
· 舊複本遮蔽正門:plugin 的 scripts/* 在專案樹(含雲端的 $TOP/InkStoneCo/)裡
  有同名但**內容不同**的複本就點名。實例=InkStoneCo/scripts/ticket 的取 token
  邏輯還停在「只認名叫 gitea 的 remote」,而雲端的 Gitea 叫 origin
  ⇒ 一律死在「拿不到 gitea token」⇒ 人被逼去繞過正門直接打 API,
  而那正是 ticket-api-bypass-guard.sh 在防的事。
· 退役機制的殘骸:.claude/ 底下的目錄,若 plugin 的 hooks/scripts 一個字都沒提到
  ⇒ 產生它的東西已經不在這一份裡了。判準是「plugin 現在還認不認得它」,
  **不是關鍵字黑名單**(leo 2026-08-17 已證明那條路 8 次誤攔、0 次正確攔截)。

訊息改由 hooks/lib/beacon_report.py 序列化:三段報告含引號與換行,
用 shell 內插拼 JSON 一個引號就會讓整行信標消失——而那正是「零閘狀態」的長相。
fail-open:python 掛掉、檔案不見、網路不通,一律退回原本那一行乾淨的信標。

測試 hooks/tests/isep-presence-beacon.test.sh:14/14(全離線)。
第 ⑪ 條守的是寫這支時真的犯過的 bug(內層迴圈變數跟外層的 d 撞名,
第二個殘骸之後全部被靜靜跳過)——把那個 bug 放回去,該條立刻轉紅。
This commit is contained in:
claude-code
2026-08-28 00:05:15 +00:00
parent 352d7a0b81
commit adb7009b67
3 changed files with 302 additions and 2 deletions
+18 -2
View File
@@ -42,12 +42,28 @@ case "$ROOT" in
*) SRC="來源不明" ;;
esac
# ── 交給 lib/beacon_report.py 組訊息 ─────────────────────────────────
#
# 🔴 為什麼改成走 python 而不是繼續用 printf 拼 JSONinkstone/ISEP#90):
# 下面要多報三件事(版本落差/舊複本遮蔽正門/退役機制的殘骸),
# 而那三段的內容含引號與換行。**用 shell 內插拼 JSON,一個引號就會把整包 JSON 弄壞,
# 而壞掉的 JSON 讓信標整行消失** —— 那正是本檔要偵測的「零閘狀態」的長相。
# ⇒ 訊息本身可以變複雜,但**序列化這件事不准手拼**。
#
# 🔴 fail-openpython 掛掉、網路不通、什麼都不准讓這行消失。
# 信標消失=leo 會判定這個 session 沒有閘(本檔第 8 行寫的判準),
# 所以組不出加料版就退回原本那一行乾淨的訊息。
MSG="🟢 ISEP v${VER} 已載入(${GATES} 支閘|來源:${SRC}${ROOT}"
printf '%s\n' "{
FALLBACK="{
\"systemMessage\": \"${MSG}\",
\"hookSpecificOutput\": {
\"hookEventName\": \"SessionStart\",
\"additionalContext\": \"${MSG}。這行是 ISEP plugin 自己發的——看得到它就表示閘真的生效了。若某個 session 從頭到尾沒有這行,那個 session 是零閘狀態,先修 plugin 再做事,不要用『跑得動』當證據。\"
}
}"
OUT="$(python3 "$ROOT/hooks/lib/beacon_report.py" "$VER" "$GATES" "$SRC" 2>/dev/null || true)"
case "$OUT" in
\{*) printf '%s\n' "$OUT" ;;
*) printf '%s\n' "$FALLBACK" ;;
esac
+167
View File
@@ -0,0 +1,167 @@
# ── 以下三格是 inkstone/ISEP#90 加的「這一份是不是還有效」自檢 ──────────
# 都**只是報告,不擋任何事**(SessionStart 本來就不該擋),而且每一格拿不到答案就閉嘴。
import json, os, re, subprocess, sys, time, urllib.request
ROOT = os.environ.get("CLAUDE_PLUGIN_ROOT", "")
PROJ = os.environ.get("CLAUDE_PROJECT_DIR") or os.getcwd()
VER = sys.argv[1] if len(sys.argv) > 1 else "未知"
GATES = sys.argv[2] if len(sys.argv) > 2 else "?"
SRC = sys.argv[3] if len(sys.argv) > 3 else "來源不明"
MSG = "🟢 ISEP v%s 已載入(%s 支閘|來源:%s%s" % (VER, GATES, SRC, ROOT)
notes = []
# ══ ① 這一份跟 ISEP main 是不是同一版 ═══════════════════════════════════
#
# 🔴 為什麼要自己查(inkstone/ISEP#902026-08-27 實查):
# ISEP main 的 plugin.json → 0.9.0
# 雲端實際載入 → 0.3.9 ← 中間差 7 個 release
# 而信標**照樣是綠的**——它只證明「有一份 plugin 載入了」,不證明「載入的是哪一份」。
# 後果不是抽象的:0.3.9 裡還活著兩支已經在 v0.9.0 整支刪掉的 hook
# 於是 `.claude/pending-verification/` 在雲端**被清掉之後又長回來**。
# ⇒ 一個看不見的落差,會讓「已經刪掉的機制」在別人的工作區裡復活。
#
# 匿名讀(不帶任何憑證)⇒ D20 判準下屬於「讀」,不需要開閘、不計次。
# 快取 6 小時、逾時 6 秒、任何失敗一律閉嘴——信標不能因為網路而變吵或變慢。
def main_version():
cache = os.path.join(os.environ.get("ISEP_BEACON_CACHE_DIR", "/tmp"), ".isep-main-version")
try:
if time.time() - os.path.getmtime(cache) < 6 * 3600:
v = open(cache, encoding="utf-8").read().strip()
return v or None
except Exception:
pass
url = os.environ.get("ISEP_MAIN_MANIFEST_URL",
"https://git.uncle6.me/inkstone/ISEP/raw/branch/main/.claude-plugin/plugin.json")
try:
with urllib.request.urlopen(url, timeout=6) as r:
v = (json.loads(r.read().decode("utf-8")) or {}).get("version") or ""
except Exception:
v = ""
try:
open(cache, "w", encoding="utf-8").write(v)
except Exception:
pass
return v or None
def vtuple(v):
return tuple(int(x) for x in re.findall(r"\d+", v)[:3]) or (0,)
MAIN = main_version() if os.environ.get("ISEP_BEACON_SKIP_NET") != "1" else os.environ.get("ISEP_FAKE_MAIN_VERSION")
if MAIN and VER != "未知" and MAIN != VER:
if vtuple(MAIN) > vtuple(VER):
notes.append(
"🔴 **這一份落後 ISEP main**(載入 %s main %s)——你現在跑的不是最新那組閘,"
"而且**已經刪掉的機制可能還活著**(0.3.9 就是這樣讓 .claude/pending-verification/ 復活的)。"
"修:本機 `claude plugin update isep@inkstone`;雲端要去動一下 Environment 的 setup script "
"內容逼它重拍快照(快取約 7 天)。追蹤票 inkstone/ISEP#67。" % (VER, MAIN))
else:
notes.append("️ 這一份比 ISEP main 新(載入 %s main %s)——沒發版的改動只在這台機器上。" % (VER, MAIN))
# ══ ② 專案裡有沒有 ISEP 腳本的舊複本在遮蔽正門 ══════════════════════════
#
# 🔴 實例(inkstone/ISEP#90 ②):`InkStoneCo/scripts/ticket` 是 ISEP `scripts/ticket`
# 的**舊複本**,它的取 token 邏輯還停在「只認名叫 gitea 的 remote」,
# 而 bootstrap.sh 在雲端把 Gitea 設成 `origin`
# ⇒ 在雲端跑 `scripts/ticket` 一律死在「拿不到 gitea token」
# ⇒ 人只好繞過正門直接打 API——而那正是 ticket-api-bypass-guard.sh 在防的事。
# **一道閘把人逼去走它自己禁止的那條路,那道閘就是在製造違規。**
#
# 判準不是「檔名一樣」,是「檔名一樣**而內容不同**」——同步過的複本不吵。
def shadow_copies():
out = []
src = os.path.join(ROOT, "scripts")
if not os.path.isdir(src):
return out
roots = [PROJ, os.path.join(PROJ, "InkStoneCo")]
for name in sorted(os.listdir(src)):
a = os.path.join(src, name)
if not os.path.isfile(a):
continue
try:
ab = open(a, "rb").read()
except Exception:
continue
for base in roots:
b = os.path.join(base, "scripts", name)
if os.path.realpath(b) == os.path.realpath(a):
continue
if not os.path.isfile(b):
continue
try:
if open(b, "rb").read() != ab:
out.append(os.path.relpath(b, PROJ))
except Exception:
pass
return out
sh = shadow_copies()
if sh:
notes.append(
"🟡 **專案裡有 ISEP 腳本的舊複本**,而它們排在 plugin 前面被叫到:%s"
"兩份必然漂移,漂移的那份會安靜地騙人——`InkStoneCo/scripts/ticket` 就是這樣"
"在雲端一律死在「拿不到 gitea token」。要嘛刪掉複本改叫 "
"`\"$CLAUDE_PLUGIN_ROOT\"/scripts/<名字>`,要嘛把複本同步回 ISEP。" % "".join(sh))
# ══ ③ 工作區有沒有「已退役機制」留下的產物 ══════════════════════════════
#
# 判準是機械的、而且會自己長大:**plugin 自己的原始碼裡有沒有任何一個字提到這個目錄**。
# 提到了 ⇒ 它是現行機制的產物,正常。
# 一個字都沒提到 ⇒ 產生它的東西已經不在這一份 ISEP 裡了 ⇒ 它是殘骸。
# 刻意**不用關鍵字黑名單**leo 2026-08-17 已證明那條路 8 次誤攔、0 次正確攔截):
# 這裡問的是「plugin 現在還認不認得它」,不是「這個名字看起來像不像壞東西」。
NATIVE = {"hooks", "commands", "skills", "agents", "plugins", "wiki", "cloud-shell",
"projects", "statsig", "shell-snapshots", "todos", "ide", "local", "isep"}
def orphan_artifacts():
out = []
for base in [PROJ, os.path.join(PROJ, "InkStoneCo")]:
d = os.path.join(base, ".claude")
if not os.path.isdir(d):
continue
for name in sorted(os.listdir(d)):
p = os.path.join(d, name)
if not os.path.isdir(p) or name in NATIVE or name.startswith("."):
continue
# 🔴 只搜「會產生東西的那些檔」(hooks/scripts),不搜 docs
# docs 提到一個名字**不會讓那個目錄長出來**,但會讓這一格閉嘴。
# 🔴 也要把本檔排除掉:本檔的註解裡就寫著 `pending-verification` 當例子,
# 第一次跑就因此漏報了真正存在的那一個——**自己提到自己=這格靜音**。
try:
hit = False
for sub in ("hooks", "scripts"):
# 🔴 變數名不要跟外層的 `d`(.claude 那個目錄)撞——撞了會把
# 外層迴圈的基準目錄換掉,第二個名字之後全部被靜靜跳過。
# 第一版就是這樣寫的,實測結果:真的存在的 `verified-claims`
# 一聲不吭地消失了。**假綠不是漏寫檢查,是檢查跑在錯的對象上。**
sd = os.path.join(ROOT, sub)
if not os.path.isdir(sd):
continue
if subprocess.run(["grep", "-rqlF", "--exclude", os.path.basename(__file__),
"--", name, sd],
capture_output=True, timeout=20).returncode == 0:
hit = True
break
except Exception:
hit = True # 問不出來就當它有效,不亂報
if not hit:
out.append(os.path.relpath(p, PROJ))
return out
orph = orphan_artifacts()
if orph:
notes.append(
"🟡 **工作區有已退役機制的產物**%s。這一份 ISEP 裡沒有任何東西提到它們"
"(v0.9.0 已整支刪除產生它的 hook),所以它們是殘骸——"
"**它們還在長,就表示這台機器跑的是舊版**(見上面那格)。確認之後刪掉。" % "".join(orph))
CONTEXT = ("%s。這行是 ISEP plugin 自己發的——看得到它就表示閘真的生效了。"
"若某個 session 從頭到尾沒有這行,那個 session 是零閘狀態,"
"先修 plugin 再做事,不要用『跑得動』當證據。" % MSG)
if notes:
MSG = MSG + "\n" + "\n".join(notes)
CONTEXT = CONTEXT + "\n\n" + "\n".join(notes)
print(json.dumps({"systemMessage": MSG,
"hookSpecificOutput": {"hookEventName": "SessionStart",
"additionalContext": CONTEXT}},
ensure_ascii=False))
+117
View File
@@ -0,0 +1,117 @@
#!/usr/bin/env bash
# isep-presence-beacon.sh 的迴歸測試(inkstone/ISEP#90 ②③)
#
# 信標的價值全在鑑別力,所以這支要同時證明兩件相反的事:
# ① 該報的三件真的報得出來(版本落差/舊複本遮蔽正門/退役機制的殘骸)
# ② **不管加多少報告,那行綠色信標永遠在**——它消失=leo 會判定這個 session 零閘。
# 所以連 python 掛掉、網路不通、訊息裡有引號,都要還有一行合法 JSON。
#
# 🔴 全程離線(ISEP_BEACON_SKIP_NET=1,版本用 ISEP_FAKE_MAIN_VERSION 造),
# 造假的 plugin root 與 project dir 都在 TMP 底下,不碰真 repo。
set -u
HOOK="${1:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)/isep-presence-beacon.sh}"
REAL_HOOKS="$(cd "$(dirname "$HOOK")" && pwd)"
TMP=$(mktemp -d); trap 'rm -rf "$TMP"' EXIT
export ISEP_BEACON_SKIP_NET=1 ISEP_BEACON_CACHE_DIR="$TMP"
PASS=0; FAIL=0; N=0
# mkplugin <版本> → 造一份假的 plugin root(只放信標真的會讀的東西)
mkplugin() {
d="$TMP/plugin-$1"; mkdir -p "$d/.claude-plugin" "$d/hooks/lib" "$d/scripts"
printf '{"name":"isep","version":"%s"}\n' "$1" > "$d/.claude-plugin/plugin.json"
printf '{"hooks":{"Stop":[{"hooks":[{"command":"hooks/a.sh"},{"command":"hooks/b.sh"}]}]}}\n' \
> "$d/hooks/hooks.json"
cp "$HOOK" "$d/hooks/$(basename "$HOOK")"
cp "$REAL_HOOKS/lib/beacon_report.py" "$d/hooks/lib/beacon_report.py"
printf '#!/bin/sh\necho real\n' > "$d/scripts/ticket"
printf '%s\n' "$d"
}
# run <plugin root> <project dir> → 印出 systemMessageJSON 壞掉就印 __BADJSON__
run() {
CLAUDE_PLUGIN_ROOT="$1" CLAUDE_PROJECT_DIR="$2" bash "$1/hooks/$(basename "$HOOK")" 2>/dev/null \
| python3 -c 'import json,sys
try: print(json.load(sys.stdin)["systemMessage"])
except Exception: print("__BADJSON__")'
}
check() { # check <說明> <輸出> <該出現|!不該出現>...
desc="$1"; out="$2"; shift 2; N=$((N+1)); ok=1; why=""
for w in "$@"; do
case "$w" in
"!"*) if printf '%s' "$out" | grep -qF -- "${w#!}"; then ok=0; why="不該出現卻出現了:${w#!}"; fi ;;
*) if ! printf '%s' "$out" | grep -qF -- "$w"; then ok=0; why="少了:$w"; fi ;;
esac
done
if [ "$ok" = 1 ]; then printf ' ✅ %s\n' "$desc"; PASS=$((PASS+1))
else printf ' ❌ %s —— %s\n' "$desc" "$why"; printf '%s\n' "$out" | sed 's/^/ /'; FAIL=$((FAIL+1)); fi
}
echo "── 基本盤:那行綠色信標永遠在 ────────────────────────────────"
P=$(mkplugin 0.9.0); J="$TMP/proj-clean"; mkdir -p "$J"
out=$(run "$P" "$J")
check "① 乾淨環境:只有一行信標,版本與閘數都在" "$out" \
"🟢 ISEP v0.9.0 已載入" "2 支閘" "!🔴" "!🟡" "!__BADJSON__"
echo "── ①版本落差 ────────────────────────────────────────────────"
out=$(ISEP_FAKE_MAIN_VERSION=0.9.0 run "$P" "$J")
check "② 載入版=main 版 → 不吵" "$out" "🟢 ISEP v0.9.0" "!落後"
P39=$(mkplugin 0.3.9)
out=$(ISEP_FAKE_MAIN_VERSION=0.9.0 run "$P39" "$J")
check "③ 載入 0.3.9、main 0.9.0 → 要說它落後(雲端那個現場)" "$out" \
"🟢 ISEP v0.3.9 已載入" "落後 ISEP main" "0.9.0" "inkstone/ISEP#67"
out=$(ISEP_FAKE_MAIN_VERSION=0.1.0 run "$P" "$J")
check "④ 載入版比 main 新 → 說「沒發版」,不說「落後」" "$out" "比 ISEP main 新" "!落後 ISEP main"
echo "── ②舊複本遮蔽正門 ──────────────────────────────────────────"
J2="$TMP/proj-shadow"; mkdir -p "$J2/scripts"
printf '#!/bin/sh\necho OLD\n' > "$J2/scripts/ticket"
out=$(run "$P" "$J2")
check "⑤ 專案裡有內容不同的同名腳本 → 要點名(ticket 那件)" "$out" \
"舊複本" "scripts/ticket"
J3="$TMP/proj-same"; mkdir -p "$J3/scripts"; cp "$P/scripts/ticket" "$J3/scripts/ticket"
out=$(run "$P" "$J3")
check "⑥ 複本內容一模一樣(同步過的)→ 不吵" "$out" "!舊複本"
J4="$TMP/proj-body"; mkdir -p "$J4/InkStoneCo/scripts"
printf '#!/bin/sh\necho OLD\n' > "$J4/InkStoneCo/scripts/ticket"
out=$(run "$P" "$J4")
check "⑦ 雲端排法:複本在 \$TOP/InkStoneCo/ 底下也要抓到" "$out" \
"舊複本" "InkStoneCo/scripts/ticket"
echo "── ③退役機制的殘骸 ──────────────────────────────────────────"
J5="$TMP/proj-orphan"; mkdir -p "$J5/.claude/pending-verification" "$J5/.claude/hooks"
out=$(run "$P" "$J5")
check "⑧ plugin 的 hooks/scripts 完全沒提到的目錄 → 報殘骸" "$out" \
"已退役機制的產物" ".claude/pending-verification"
check "⑨ Claude Code 自己的目錄(hooks)不算殘骸" "$out" "!.claude/hooks"
# 現行機制的產物不該被報:讓 plugin 的某支 hook 提到它
mkdir -p "$J5/.claude/pending-main-push"
printf '#!/bin/sh\n# 寫到 pending-main-push/\n' > "$P/hooks/x.sh"
out=$(run "$P" "$J5")
check "⑩ hooks 裡有東西提到它 → 那是現行機制的產物,不報" "$out" "!pending-main-push"
# 🔴 這條守的是第一版真的犯過的 bug:內層迴圈的變數名跟外層的 `d` 撞,
# 第二個名字之後全部被靜靜跳過 ⇒ 真的存在的殘骸一聲不吭地消失。
mkdir -p "$J5/.claude/verified-claims"
out=$(run "$P" "$J5")
check "⑪ 同一個 .claude 底下有多個殘骸 → 每一個都要報(變數撞名的迴歸)" "$out" \
".claude/pending-verification" ".claude/verified-claims"
echo "── 最重要:加了報告也不准讓信標消失 ──────────────────────────"
# python 掛掉(把 report 換成一定會爆的內容)→ 仍要有一行合法 JSON 的信標
PB=$(mkplugin 0.9.0); printf 'raise SystemExit(3)\n' > "$PB/hooks/lib/beacon_report.py"
out=$(run "$PB" "$J")
check "⑫ 組訊息的 python 整支掛掉 → 退回乾淨的那一行,不是沉默" "$out" \
"🟢 ISEP v0.9.0 已載入" "!__BADJSON__"
rm -f "$PB/hooks/lib/beacon_report.py"
out=$(run "$PB" "$J")
check "⑬ 連 report 檔都不見 → 一樣要有信標" "$out" "🟢 ISEP v0.9.0 已載入" "!__BADJSON__"
# 訊息裡有引號/換行時 JSON 仍要合法(舊版是 printf 手拼的,這正是它會壞的地方)
J6="$TMP/proj-quote"; mkdir -p "$J6/scripts"
printf '#!/bin/sh\necho "OLD"\n' > "$J6/scripts/ticket"
out=$(run "$P" "$J6")
check "⑭ 報告內容含引號 → JSON 仍然合法" "$out" "🟢 ISEP" "!__BADJSON__"
echo
printf '通過 %s 條,失敗 %s 條(共 %s 條)\n' "$PASS" "$FAIL" "$N"
[ "$FAIL" = 0 ] || exit 1