lazyBoy/docs/agent-experience.md

AI 使用體驗

← 回到 README

這份文件記錄 LazyBoy 怎麼讓「AI 用電腦」這件事變得跟人一樣順，以及背後的取捨。 三個主題其實是同一件事：系統如果把 AI 使用電腦當成一系列無狀態的請求，AI 就必須每輪重新 交代自己在哪裡、在做什麼，界面也只能用輪詢去猜現在發生了什麼。

主題	一句話	細節
任務長度	沒有輪數額度，只有偵測鬼打牆的保險絲	輪次政策
容器內終端機	一台活的 tmux，人和 AI 看同一個 shell	終端機
聊天即時性	事件推送，輪詢只是兜底	本文件下面

輪數不是額度，是偵錯工具

以前一個 run 固定 40 輪，等於假設所有任務一樣長：洗資料這種事情做不完，但也不會因此變成 錯誤，只是被腰斬。現在的正常結局是把事情做完（模型提出驗證，或明白說它卡在哪裡），會 被停下來的只有鬼打牆：同一個會改變狀態的動作連做六次、同一個錯誤連錯八次、連續十四個動作 全部失敗。觀察、等待、輪詢不算重複動作，所以等一個長 build、等下載、輪詢佇列都不會被打斷。

設計上要記住兩件事：

• 提示（「你已經做同一件事三次了」）永远不會停掉任務，只有重複到像故障才會暫停，暫停也是停在 現況、按「繼續」接下去，不重來。
• 保險絲（budget_exhausted）代表迴圈失控，是故障不是成績；它照樣可以續跑，但值得去看執行記錄。

純聊天仍然是 4 輪上限：那是避免模型在閒聊裡燒額度，跟任務長度無關。

終端機是一台活的 tmux

shell 透過 Cua 在共用 VNC 桌面上開啟有名稱的終端機。相同 session 保留工作目錄、 環境變數與背景工作；keys: "C-c" 會在該終端機送出中斷，reset 會換成乾淨的登入 shell。

輸出以桌面截圖回傳。模型必須確認提示字元已回來才能輸入下一條命令；省略 command 即可再次查看，長輸出可以透過 Cua 捲動終端機。wait_ms 預設 1000、上限 10000， 等待結束不會終止命令。終端機若被關閉，下次呼叫會重新開啟，已關閉 shell 的環境不會還原。

檔案列出、分頁讀取與寫入也使用這個可見終端機。所有這些工具都需要視覺模型與桌面控制鎖。

聊天是推送，不是輪詢

事件早就寫進 events 表，也有 SSE 端點，但兩端都在猜：伺服器每 750 ms 掃一次資料庫，瀏覽器 每 2 秒重刷一次全部狀態（訊息、電腦狀態、螢幕、技能、心跳一起打）。所以一個回覆最快也要兩輪 輪詢才被看見。

現在的管線：

1. 寫事件的事實不變——events 表仍然是順序與重放的依據（游標是 threads.next_event_seq， 斷線重連用 Last-Event-ID 從資料庫重放，不會漏也不會重複）。
2. 提交之後往進程內的 wake channel 敲一下（WakeBus）。SSE 端點不再固定間隔輪詢，而是等敲； 敲不到時（多副本、讀者落後）以 5 秒兜底輪詢補上。
3. 瀏覽器用 EventSource 訂閱 /api/sessions/{id}/events，事件在 120 ms 的窗口裡合流， 一回合變動只刷新一次。

實測（本機 loopback、丟棄式資料庫、同一台機器）：

事件	以前	現在
自己發的訊息出現在畫面	最多 2 秒	送出去後約 25 ms
「思考中」指示出現	最多 2 秒	約 32 ms（worker 也被敲醒，不再等 200 ms 定時器）
模型回覆出現	寫入後最多 2.75 秒	寫入後約 25 ms（模型本身要幾秒是另一回事）

順帶把浪費掉的工作拿掉：分頁藏在後面時不再刷新（回到前景立刻補一次），心跳從 2 秒改成 60 秒——一次心跳買的是 15 分鐘控制租約、避免 10 分鐘閒置暫停，60 秒是很寬的餘裕。

壞了會怎樣。 SSE 被 proxy 擋住或斷線，瀏覽器察覺後自動回到 2 秒輪詢，等於退回以前的行為， 不會變成不更新；伺服器端事件順序仍然只以資料庫為準，wake 不見得可靠，只是慢。

自己量一次：

curl -N -b cookies.txt http://127.0.0.1:3101/api/sessions/<id>/events
# 另開一個終端機送訊息，看事件幾毫秒後出現在這條串流裡

已知取捨

• 模型回覆還是「整個完成」才出現，沒有串流 token。思考中的狀態有顯示，但要像 ChatGPT 那樣逐字 冒出，需要把 completion 換成串流並處理中斷/接續，這是下一件事。
• 電腦狀態（執行中／暫停、誰在控制）沒有自己的事件，只能靠兜底輪詢更新，LIVE_POLL_MS 目前是 4 秒； 桌面畫面本身是即時串流，只有狀態列會慢幾秒。要真正事件化得把 computers 的狀態變更也寫進 events（狀態是 bot 層、事件是執行緒層，要先決定寫到哪條執行緒）。
• 滑鼠停在頭像上看到的執行記錄泡泡，開啟時仍是輪詢（它只在滑鼠停留時開啟，量很小）。
• wake channel 是單進程的。多副本部署時，其他副本靠 5 秒安全輪詢追上；真要横向擴充應改用 Postgres LISTEN/NOTIFY。
• 持久終端機需要桌面映像檔裡的 tmux；舊映像檔會退回一次性 shell，docker compose build computer 之後就有了。
• 容器執行檔仍以 uid 1000、限制環境變數的方式進入容器，持久化的是 shell 狀態，不是憑證。