跳至主要內容
返回

HandsOff 教我怎麼帶 coding agent

我做 HandsOff 只有一個理由。coding agent 現在可以跑很久的任務,而我想在它跑的時候讀螢幕。螢幕鎖定會把畫面藏起來,剛好破壞了「盯著看」這件事。所以我把機器開著,結果工作被鍵盤上那雙好奇的小手毀掉。那時我最小的孩子還在念幼兒園。

HandsOff 在系統層擋住鍵盤、觸控板和滑鼠。螢幕維持可見。你用盲打密語解鎖,沒有回顯、沒有游標。它防的是隨手亂碰:跑到鍵盤前的小孩、同事、螢幕分享的觀眾。有心攻擊的人會直接重開機或把筆電帶走,所以它比較像行李箱的簡單號碼鎖,而不是保險箱。

這個定位決定了設計。對一個擋輸入的工具來說,把鍵盤鎖住卻放不開,就是立刻出局。所以我留了自動解鎖這個保險機制,而不是保證鎖得超級牢。好用比多餘的功能重要。

它做什麼

HandsOff 是 macOS 13 以上的原生選單列應用程式,用 Rust 寫的。系統鉤子攔下每一次按鍵。第一次執行有設定精靈,有全域快速鍵可以鎖定,預設閒置 180 秒自動鎖定,自動解鎖則從 60 分鐘開始,每加倍一次,最多到 24 小時。只有真的用密語解鎖才會重設它。

應用程式儲存的是你按下的實體鍵碼的單向雜湊。任何鍵盤配置都能用,磁碟上也沒有可讀的東西。

雖然我以前寫過 Rust 的 CLI 和函式庫,但沒做過系統層的程式設計,更沒做過 macOS 上的 GUI 工具。這是我第一個完全 vibe coding 的專案。我寫規格,agent 寫程式,機器決定誰對。

Agent 看不到的東西

Handsoff 已經好用到我自己在用,但很長一段時間,還不夠穩到能分享給別人。agent 可以讀程式碼,但看不到我從滑鼠游標的頓感、幾毫秒的打字延遲裡感受到的系統不穩定。

所以真正重要的 bug 要重複出現夠多次,我才看出模式、開始懷疑;而隨著這幾個月模型變聰明,agent 終於能用我的問題描述去拆解問題,跟我一起收集更多執行期資料,然後把埋在先前模型留下的層層 slop 底下的根本原因解掉。

那個從不睡的 sleep

一開始是跑 Handsoff 幾週後系統變慢。於是我請 agent 加一個 Suspend Mode,減少輪詢、降低 CPU 用量。sleep-then-check 迴圈就是這時候插進來的,但後面一連串最佳化把它退化成 CPU 耗損的來源。Slop bug。

靜態審查看出一個死掉的背景執行緒,估它每秒醒來 2 次。刪掉它是對的決定,估的數字錯了大概 10,000 倍。

活動監視器顯示 handsoff-tray 一直吃滿一個核心,不管我有沒有碰機器。對執行中的 release binary 取樣,幾乎全部時間都在那個執行緒裡。主執行緒則在睡覺。

那個迴圈,原文照登:

loop {
    let result = unsafe {
        CFRunLoop::run_in_mode(kCFRunLoopDefaultMode,
                               Duration::from_millis(500), // "sleep" half a second
                               false)
    };
    if shutdown_rx.try_recv().is_ok() { break; }
    ...
}

很諷刺,原本的設計在執行時得到相反的結果。應用程式請系統等半秒再檢查一次。但沒有東西可等,run loop 就立刻回傳。於是那個執行緒再問一次、又問一次,快到 CPU 允許的極限。註解寫著「run the loop for 0.5 seconds」。那句話沒人測過。

修法是把執行緒刪掉。刪掉它之後,「最小 CPU 模式」那組選單也失去理由,所以一起拿掉。agent 抓對了方向,抓錯了大小。是量測把數字糾正回來的。光讀程式碼找不到這個 bug。

那個永遠說不要的按鈕

更新換掉應用程式檔案後,macOS 的權限畫面還亮著舊的項目,但兩個真正的檢查都失敗。精靈就永遠在那裡等「授權」。於是我加了「重設權限並重新啟動」按鈕。

按鈕從來沒作用過。程式拿對話框的回答去比錯的常數。它檢查是不是 1,但第一個按鈕回傳的是 1000。那個分支從未觸發,所以每次點擊都是取消。

它編譯過了。讀起來正確。也 ship 出去了。只有真的點下去才會露出來,而那一下點擊得由我來按。再怎麼 review 都抓不到,因為 diff 裡沒有任何地方看起來有錯。

把我鎖在外面的鎖

這個嚴重,但壞的是安裝精靈,不是主要用途。精靈以前在權限一通過的瞬間就開始聽你的密語。那個監聽器會吞掉機器上每一次按鍵,這本來就是它的工作。只是螢幕上完全沒說這件事正在發生,而且會持續最多 300 秒。結束再重開,精靈又來一次。

我追這件事的那個下午,數到 16 個疊在一起的精靈啟動。每一個都綁架著鍵盤。我完全沒想到要為安裝程式的 bug 留逃生口。

修法動到設計,不是只改表面。只有你按下「擷取密語」按鈕,擷取才開始。最多跑 120 秒,畫面上有倒數;關掉視窗時,0.1 秒內就會停。鎖檔案會擋掉第二份同時跑。政策也改了:如果應用程式執行中權限壞掉,它就解鎖、跳一則通知,然後結束。權限壞掉時要放開鍵盤,絕不把它當人質。

把不能接受的失敗,一想到就寫下來,變成硬性限制。它會塑造設計,不只是測試清單。這次教訓之後,我在 AGENTS.md 加了「永遠不要讓輸入被鎖住」。

我現在怎麼帶 agent

幾個心得。

先定義失敗。把不能接受的結果寫進 AGENTS.md 和規格裡。讓它變成 agent 無法忽略的硬性限制。

把執行期的說法變成驗收條件。寫出指令和數字:sample handsoff-tray 5、閒置 CPU 的目標、鎖定後打字再解鎖。

餵給 agent 觀察,不是意見。取樣輸出、log 行、確切的回傳碼。「感覺很慢」不是 bug report。「對話框大概回傳別的東西」在我們知道真正的數字之前,也不算修好。

把人工步驟寫清楚。任何你留著沒說的實機驗證步驟,都會變成卡住的 agent 回來找你。

質疑模型假設,不要只 review PR。有一次 review 指出輸入鉤子拆除時有很高的當機風險。把真正的呼叫圖走一遍,這個說法就死了。那條可怕的鏈根本不會發生。把心智模型弄對,比那次 review 裡的任何 patch 都值錢。

我最小的孩子已經過了幼兒園。鍵盤安全多了。每次有小孩晃過來「幫忙」,HandsOff 就又證明一次自己有用。幾乎所有字都是 agent 打的,而且打得很快。判斷「壞掉」是什麼意思、把它寫下來、然後真的跑起來看誰對——這部分還留在我身上。它也留在任何一個手放在鍵盤上的人身上。

原始碼在 mhuang74/handsoff-rs。安裝說明在產品文章。


分享這篇文章:

上一篇
Infinite Worship:分析 API 消失後,音樂還是能一直播下去
下一篇
HandsOff:防小手也防貓爪