claude-code
55 lines
4.2 KiB
Markdown
55 lines
4.2 KiB
Markdown
# 已知誤解 / 踩過的坑
|
||
|
||
> 這是 ISEP 自己的坑，不是 InkStoneCo 的（不轉抄，複製即 fork，fork 即漂移）。
|
||
> 撞到新坑就 append 一條；session 開場只推最近幾條標題（見 `hooks/session-start-recall.sh` push 5/5），全文在這裡。
|
||
|
||
⚠️ MISTAKE: 「環境設定」曾經拆成兩份，各自會漂
|
||
症狀: 本機在跑 `InkStoneCo/.claude/`（真身），雲端跑的是 `generate-shell-payload.py`
|
||
另外產生塞進 GitHub 私 repo 的一份（薄殼）。`inkstone/InkStoneCo#57` 實測：薄殼比真身
|
||
少 7 支閘，其中兩支是前一天才立的；`#14` 更早查到雲端 33 支 guard 一支都沒生效。
|
||
正確做法: 只留一份——ISEP 這個 repo 本身就是唯一真相源，本機與雲端裝同一個 plugin。
|
||
改動一律只改這裡，然後兩邊各自 `/plugin update`。不要再改
|
||
`InkStoneCo/.claude/hooks/`（退場中，早晚會刪）。
|
||
原因: 「一份東西兩個副本」在沒有機制強制同步的情況下必然漂移——差異不是誰疏忽，
|
||
是結構本身允許漂移發生。
|
||
日期: 2026-08-20（ISEP `c263866` 建立時就是為了解這個病）
|
||
|
||
⚠️ MISTAKE: hook 路徑寫死會在雲端斷
|
||
症狀: 舊版 hook 若用 `$CLAUDE_PROJECT_DIR/.claude/hooks/...` 或寫死的絕對路徑指向 hook
|
||
腳本自己，雲端執行時的 cwd 不是本機那個真身目錄，路徑就對不到、hook 直接失效
|
||
（正是上一條「雲端 33 支 guard 一支都沒生效」的根因）。
|
||
正確做法: hook 指自己（找到自己在哪、要 source 的其他 hook 檔）一律用官方
|
||
`${CLAUDE_PLUGIN_ROOT}`。腳本內部要指**專案裡的檔案**（如 `system-dev/wiki/`、
|
||
`system-dev/docs/`）才用 `$CLAUDE_PROJECT_DIR`——那些檔案本來就该住在被操作的
|
||
那個 repo 裡，跟 hook 自己的路徑是两回事，别混。
|
||
原因: 兩種路徑指的是完全不同的東西（「plugin 安裝到哪」vs「正在操作哪個專案」），
|
||
混用就是這條坑的直接原因。
|
||
日期: 2026-08-20（README「路徑規約」段記錄，ISEP 0.1.0 把 51 條 hook 路徑全部改過一輪）
|
||
|
||
## ⚠️ MISTAKE: 「裝好了」不等於「它在跑」
|
||
|
||
2026-08-20 實查：ISEP repo 建好、README 寫著 0.1.0、41 支閘都在裡面——
|
||
但 `claude plugin list` 裡**根本沒有 ISEP**。本機仍然在跑 `InkStoneCo/.claude/`，
|
||
Gitea 上**一個 release tag 都沒有**。
|
||
|
||
⇒ 「東西做出來了」與「有人在用它」是兩件事，而只有後者算交付。
|
||
⇒ 判準：**去執行環境查它有沒有被載入**（`claude plugin list` / `claude plugin details`），
|
||
不要從 repo 裡有什麼檔案去推論。
|
||
|
||
## ⚠️ MISTAKE: 閘的「釋放章」用 `stat -f %m` 先，雲端 Linux 永遠放行不了
|
||
|
||
2026-08-23 雲端 cloud-worker 實撞：三支閘（`prod-write-guard`／`main-and-prod-push-guard`／
|
||
`stage-before-prod-guard`）取戳記 mtime 都寫成 `stat -f %m … || stat -c %Y …`。
|
||
GNU（Linux）的 `stat -f` 是 `--file-system`，`%m` 被當成**檔名** ⇒ 把整張檔案系統表印到
|
||
stdout（被 `$()` 收進去）且 exit 1 ⇒ 時間變數變非數字 ⇒ `case *[!0-9]*` 命中 ⇒ 釋放章判無效。
|
||
後果：總管 `touch /tmp/.prod-write-ok` 在雲端**從沒生效過**，連 routine 要求的心跳都打不出去。
|
||
|
||
⇒ 正確做法：**GNU 先、BSD 後** → `stat -c %Y … || stat -f %m …`（Linux 走前者、macOS 走後者）。
|
||
⇒ 為什麼本機測不出來：dev 在 macOS，BSD `stat -f %m` 本來就正常 ⇒ 這種「只咬某一個 OS」的坑，
|
||
**驗證要在真正會跑的環境（雲端 Linux）跑，不能只在 dev 機跑**。
|
||
⇒ 同款第二例（同日抓到，未修）：`history-first-guard` 的逃生口說明寫 `touch /tmp/.kbdb-down`，
|
||
但它讀該檔是 `cat` 出來當時間戳算術——**空 `touch` 會炸**，正解是 `date +%s > /tmp/.kbdb-down`。
|
||
教訓：**逃生口本身也要被測**，不然閘壞了連逃生口都用不了。
|
||
（修復：分支 `fix/stamp-release-stat-ordering-linux`；回報 ISEP#30 / InkStoneCo#14）
|
||
日期: 2026-08-23
|