閘門提早 return,frame 依賴就消失:clawd-actor 修 command-period 閃動時多補的一刀
2026 年 10 月 13 日,clawd-actor 的 issue 區多了一則 #3:每次跑 /reload-plugins,Clawd 那條舞台就閃一下。回報者寫的版本是 clawd-actor 0.5.3、Claude Code 2.1.296,內文還附了一段「Guess at the cause (from reading 0.5.3 source)」。他自己標明是猜的,沒有確診。
clawd-actor 是個 Claude Code mod,Clawd 會走到 prompt 上方的小舞台,演出 spinner 那個 -ing 字。README 說有 32 個場景(以 README 為準,我沒逐一數),0.8.0 之後還加了筆記、todo、提醒和徽章。純裝飾,場景是依 spinner 字的字根或工具名挑的,不反映真實進度。我沒有安裝過它,也沒跑過它的測試,下面全部來自 repo 的原始碼、PR 與 issue。
一個閘門,兩個毛病
隔天 10 月 14 日,PR #5 開出來,兩小時多就合併了,標題是 “Fix the command-period isWorking blink: turn-gated band, frame read before the gate”。內文處理兩件事,第二件是第一件逼出來的。
第一件,閘門太鬆。PR 內文說,/reload-plugins 這類指令會讓 isWorking 變成 true,卻沒有任何 turn 在跑,「the isWorking-only gate let Clawd on stage for exactly one still frame before the command ended」。只看 isWorking 當閘門,Clawd 就在指令期間上台一格靜止畫面,這就是那一閃。修法是閘門再加一個 isTurnRunning。程式裡的註解把這個差別寫得很清楚:isWorking 是引擎自己說有沒有 turn 在跑,但它不等於 turn 本身。這條死路我會直接跳過:拿引擎給的「忙碌」旗標當「我的動畫該演」的判斷。
第二件,閘門一加,新的毛病就在等著,PR 內文說這讓它「from a freeze fix into a necessity」。作者在 AbovePrompt 的 ui.render 上方留了一段註解,逐字如下:
read before any early return: the engine tracks the atoms a render reads and redelivers on their writes — a gated return that reads nothing unregisters the frame dependency, and the band would never redraw on its own again (the whole-turn blackout)
PR 內文講得更白:「A gated early return next(e) reads no atoms, so the engine unregisters the frame dependency: after one gated pass, frame writes stop triggering redelivery entirely.」
mod 有個計時器,每 140 毫秒(FRAME_MS = 140)寫一次叫 frame 的 atom,舞台靠它重畫。作者的說法是,引擎記的是「這次 render 讀了哪些 atom」,寫入時只通知讀過的那些。照這個說法,閘門擋掉的那一輪如果在讀 frame 之前就 return next(e),這一輪等於什麼都沒讀,frame 的依賴就被登出,之後計時器寫得再勤也不會再叫它重畫。程式第一行因此是 const t = await read($, frame),之後才走到那串 if (... ) return next(e) 的閘門。
這段我只能引述,不能替它背書。那是作者的註解與 PR 描述對引擎行為的說法,我沒有對照 Claude Code 官方文件,也沒讀引擎原始碼。
重畫停了,狀態放哪
讀順序弄對之後,第二個問題接著冒出來:/reload-plugins 本身就是熱重載。作者在檔頭寫了一句,「a hot reload (/reload-plugins) loses module variables, not state」。所以放哪裡,是照這句話分的。
| 東西 | 放哪 | 依據 |
|---|---|---|
frame |
atom,計時器每 140 毫秒寫入 | 註解寫引擎依 render 讀過的 atom 重新送達 |
turn 的 show(isTurnRunning、turnBase、seed、played) |
$.state 的 show atom |
檔頭註解:熱重載丟模組變數、不丟 state |
spinner 的 word、mode |
模組變數 | 註解寫 “State cannot be written during a render” |
最後一列的原因寫在註解裡。Spinner 那邊是另一個 ui.render hook,只觀察、原樣 return next(e),記下 e.props.message ?? e.props.word。render 期間不能寫 state,所以只好落在模組變數。熱重載之後這兩個值會怎樣,作者沒寫,我不替它推。
還沒收乾淨的部分
PR 內文寫它「Fixes the last open finding from #3」,但 #3 到 2026-11-16 我查的時候仍是 open。它只處理其中 command-period 那一項的閃動,#3 現在還會不會閃,我沒查到。另一則 #6 回報 Claude Desktop(Windows)上舞台列對不齊,推測原因是比例字型與行高;0.7.2(2026-10-29,標題 “aligned on Desktop and VS Code”)把終端機以外的舞台改用 SVG 矩形畫,不過 #6 一樣還開著,是否已解,我也沒查到。
clawd-actor 的這幾週
2026-10-13
#3 開出,回報 /reload-plugins 時舞台閃動;同一天開的 #2(Workflow tool 執行時動畫凍住)隔天關閉,根因我只讀了標題與部分內文。
2026-10-14
PR #5 合併,閘門加上 isTurnRunning,frame 改成先讀再判斷。
2026-10-29
v0.7.2 發布,終端機以外的繪製面改成 SVG 矩形。
2026-11-14
v0.8.0 與 v0.8.1 同日發布,加入筆記與徽章,/clawd list 顯示 todo。
我會怎麼用這件事
我的立場:寫任何會被計時器驅動重畫的 ui.render hook,第一個動作先讀你依賴的 atom,閘門判斷全部排在它後面。照作者的說法,少讀這一次的代價是整個 turn 的畫面不再自己重畫。
會讓我收回這句話的條件:官方 mods 文件或引擎行為顯示,依賴是依照「mod 註冊時宣告」而不是「某次 render 實際讀到什麼」來決定的,或是作者之後把這段註解改掉。到那時,這個順序只是這個 mod 的實作細節,不是通則。
AbovePrompt 一律呼叫 next({ ...e, props: { ...e.props, maxRows: e.props.maxRows - H - said.length } }),把下層內容疊在舞台下方;README 寫的是,不呼叫 next 的 band mod 會蓋掉其下所有內容。想看守門型 hook 在 tool.call 出錯時會怎麼辦,可以讀我 10 月 5 日那篇 照抄官方範例,validate 還是多吐一行:Claude Code mods 的守門 hook 出錯會放行,切角不同,那篇談的是守門,不是渲染。
裝不裝是另一回事:它只有裝飾、/clawd 聊天會呼叫 Haiku 並花使用額度(README 的說法)、專案 2026-10-05 才建立,貢獻者 3 人、其中一人是主力(BrianHuang813 44 個 commit,數字取自 2026-11-16)。README 也聲明這是粉絲作品、與 Anthropic 無關。
原文來源:clawd-actor(README、hooks/register.tsx,main 分支,2026-11-16 clone)、PR #5、issue #3、issue #6、releases(以 2026 年 11 月 16 日讀取的內容為準)


















