AnyBot/docs/plan-2026-11-improvements.md

改進總計畫：產品面＋操控鏈路（2026-11）

依據：對本 repo 的程式碼審查（src/providers.rs、src/computer.rs、src/cloudbox.rs、 src/agent.rs、src/marks.rs、src/remote.rs、src/model.rs、deploy/server/、 deploy/test/、.gitea/workflows/release.yml），2026-11 競品調查（OpenClaw 394k★、 browser-use 120k★、UI-TARS-Desktop 39.6k★、Khoj 38k★、Letta 25k★、Leon 17.6k★）， 以及 bench/computer-use/README.md 的量測資料（模型思考佔一題總時間約 90%：746/824 秒）。

狀態：全部未動工。每一項都附「做什麼、動哪裡、怎麼算做完」。 順序是建議值，可按能力調整；標 ⛓ 的項有相依。

---

總覽：三條工作軌

軌	目標	項目
P（產品/分發）	讓别人能用、敢用、想貢獻	P1–P8
S（安全）	把「Bot 動我電腦」變成可信系統	S1–S5（S1 是 P5 的前件）
C（操控鏈路）	更精確、更少來回、更便宜	C1–C9、H1–H4

全案最高 CP 值的前五件：C1（prompt cache）、S1（docker.sock）、P1（授權）、C2（AX 直寫）、P2（英文 README＋demo）。

---

軌 P：產品與分發

P1. 授權條款 ⛓（社群/貢獻的前件） ✅ 2026-11：Apache-2.0（LICENSE＋Cargo.toml＋README 授權節）

• 加 LICENSE（建議 Apache-2.0，與依賴的 agent-desktop-core 一致）＋ Cargo.toml 加 license = "Apache-2.0"。
• relay/Cargo.toml 同步。
• ✅ 完成標準：cargo publish --dry-run 通過；README 有「授權」章節。

P2. 英文入口＋視覺化 demo ⛓（依賴 P1）

• README.md 保留繁中，新增 README.en.md（或英文在前）＋ docs/en/（至少 architecture、install、multi-device 翻譯）。
• README 開頭加：一句話定位、GIF/短片（computer-use 全自動完成「填表＋送單」一鏡）、vs OpenClaw / OpenHands / Khoj / UI-TARS 的對比表（多機大腦/手腳、Box 沙盒＋VNC 接手、AX 編號＋批次＋快速模型、一鍵自架伺服器＋HTTPS——這四項競品都沒整套）。
• docs/protocol.md 出英文版（開放第三方用戶端）。
• ✅ 完成標準：README 首屏 10 秒內看懂「它跟別的有什麼不同」，有一段 60 秒內的真機影片。

P3. 逆向工程註解整併（法務風險） ✅ 2026-11：反編譯註解全數改為行為規格；逆向文件移出 repo；驗收 grep＝0

• 全 repo 的註解大量引用 main-core.cjs @727949、main-app.cjs、CUGrokBotService 等行號級逆向參考，公開 repo 對 xAI 資產留下行號地圖，法務與公關都難看。
• 做法：把這類註解改寫為行為規格（「原版在 macOS 10.14+ 用 UNUserNotificationCenter，授權狀態 0..4 對應 …」），刪去檔案名＋偏移量；GROK_BOT_FEATURES.md、GROK_BOT_TOKENS.md、ORIGINAL_FEATURES.md 移出主 repo（內部文件/附件），程式內引用改指向 docs/specs/ 下的行為規格。
• 重點檔：src/notify.rs、src/axread.rs、src/policy.rs、src/computer.rs、src/app.rs 開頭註解區塊。
• ✅ 完成標準：grep -rn "main-core\|main-app\|@0x\|CUGrokBot" src/ deploy/ 為空。

P4. 資料層：state.json → SQLite ⛓（P6、D1 的前件）

• 現況：全部狀態在一个 state.json（src/model.rs:457）；多裝置同步＋例行任務＋長聊天長期必遇併發遺失、檔案肥大、無 schema 遷移。
• 做法：rusqlite（已 bundle）新增 src/db.rs；聊天/訊息/oplog/例行任務/快照索引進 SQLite（WAL），state.json 只留設定與 Bot 定義；寫入採「遷移＋雙寫→讀切換→去 JSON」三步，附 state.json 一鍵匯入與回退。
• schema 帶 user_version，之後所有加欄位都走遷移。
• ✅ 完成標準：10 萬則訊息的 Bot 開啟 <1s；兩端同時寫聊天不互刪（整合測試）；make doctor 會驗 DB 完整性。

P5. 安全敘事公開化 ⛓（依賴 S1–S3）

• README/docs 加 SECURITY.md＋威脅模型章節：哪些金鑰存哪裡（vault 的 AES-GCM＋keychain）、relay 只存雜湊、box 的隔離層（gVisor）、docker.sock 收斂後的能力面、prompt injection 的防線（見 S3）、「Bot 動過我電腦什麼」的稽核面（A1）。
• ✅ 完成標準： SECURITY.md + security@ 通報管道 + GitHub/Gitea security advisory 開啟。

P6. 記憶升級：第二個大腦（依賴 P4）

• 現況：src/memory.rs 每 Bot 200 條×500 字，無 embedding、無檢索——對照 Letta/Khoj 是最明顯短板。
• 做法：
  1. 離線 embedding：優先本機（Ollama 路徑已有；小模型如 bge-m3/qwen3-embedding），雲端 provider 当備援。
  2. 向量進 SQLite（vec/FTS5 混合檢索即可，40k 行規模不需要專庫）。
  3. 记忆分层：bot 事實（現行）／使用者偏好（跨 Bot 共用）／事件日誌（從 oplog 自動摘取）；每回合以語意檢索注入 top-k，取代全量注入。
  4. 文件索引（Khoj 式）：選定資料夾＋box 的 ~/Documents 增量索引，供「我上個月那份報表」類問題。
• ✅ 完成標準：跨月對話「我上次說的那個…」檢索命中；記憶上限取消；離線可用。

P7. 技能生態（MCP 已有，加 registry）

• teach（示範→技能）與 replay_skill 是好底子；缺分發面。
• 做法：技能檔式（Markdown＋front matter，相容 skills 慣例）、一鍵從 repo/網址安裝、內建範例包（每日彙報、瀏覽器表單、照片整理…）；docs/ 加「寫技能」指南。
• ✅ 完成標準：第三方可發「AnyBot 技能」repo 並被人一行安裝。

P8. 平台與工程衛生 ✅ 2026-11：.gitea/workflows/ci.yml（build/test/relay；bench 維持人工閘門）

• Windows：Cargo 已編 agent-desktop-windows，先出「手腳/螢幕」角色的 Windows 版（install 腳本＋facts＋x11 對應層），桌面全功能二期。
• CI：加 cargo clippy -- -D warnings、cargo fmt --check、deploy/test/remote_e2e.py 進 CI、relay 協議整合測試；bench/computer-use 8 題在 Linux runner（Docker-in-Docker/gVisor 已具備）每晚跑，結果寫入 repo（bench/results/）做回歸閘門。
• 遥測：opt-in 崩潰/成功率回報（自架 relay endpoint，遵守 SECURITY.md 敘事）。
• ✅ 完成標準：CI 紅灯可擋合併；每晚 bench 有連圖。

---

軌 S：安全

S1. 移除大腦容器的 docker.sock 全權 ⛓（P5 前件，最高優先） ✅ 2026-11：docker-socket-proxy 過濾層（兩份 compose）；DOCKER_SOCKET 支援 rootless

• 現況：deploy/server/docker-compose.yml 讓大腦掛 /var/run/docker.sock＝大腦被攻破即宿主淪陷。
• 做法：docker-socket-proxy（只放行 containers create/start/stop/exec_resize、volumes inspect）；或長期：rootless Docker＋systemd socket activation。Box 執行加 gVisor（bench 已用）。
• ✅ 完成標準：大腦容器內 docker ps 只剩 box 一個容器可見；make doctor 驗 proxy 端點清單。

S2. Relay 加 2FA＋登入韌性

• docs/protocol.md：加 TOTP（/relay/2fa/enroll|verify）與復原碼；密碼雜湊改 memory-hard（argon2id；httpd::check_password 現況要確認）；鎖定策略（8 次/5 分）加 IP＋帳號雙維度。
• 手機端 PWA 存 session 的提醒文案與「裝置清單＋一頁登出」。
• ✅ 完成標準：可關密碼-only；竊得 session 可被單一裝置清單踢除。

S3. Prompt injection 防線 ✅ 2026-11：敏感詞控件點擊每問（直接模式亦同、無放行符）；截圖塗黑卡號/OTP；讀进来的內容 <untrusted> 包夾＋系統提示；keep_to_chosen 補測試；紅隊集 R1–R7 進 bench（--tasks R1..R7，手動閘門——CI 沒有模型金鑰與 box）

1. 瀏覽器/畫面的敏感動作白名單：送出付款、發訊息、刪除、對外發文 → 一律詢問（policy 規則層，非模型自決）；網站來源（browser_open 的域）進政策判定。
2. 截圖遮罩：vault 已存卡號/密碼，截圖進模型前對照螢幕上可偵測的卡號/OTP 樣式做遮罩（正則＋框選重繪）。
3. keep_to_chosen（B26 那類參數改寫）補整合測試，禁模型改寫 computer/vault 目標。
4. 注入標記：來自網頁/文件/螢幕文字的內文，進歷史時加包夾標記（防「請忽略之前指令」）。

• ✅ 完成標準：注入紅隊集（10+ 題）在 bench 跑，成功外洩/成功送出為 0；紅隊集進 CI。

S4. Egress 代理收斂 ✅ 2026-11：egress 只綁 loopback＋偵測到的 docker bridge（docker0/br-/gwbridge）

• 現況：Linux 綁 0.0.0.0＋allowed_peer（src/egress.rs:26）。
• 改：綁 docker bridge 網段（172.17.0.1/16 之類，啟動時探測）＋開機自癒；加子網變動測試；連線計數進 oplog 可在 UI 看。
• ✅ 完成標準：ss -ltnp 顯示只綁 bridge；子網變動整合測試通過。

S5. 稽核時間軸（信任面版，產品級賣點）

• oplog.rs 已有底：做成一級 UI——時間軸＋每步截圖/參數/結果＋來源（哪個 Bot、哪個模型路由）＋敏感動作的核准記錄；可匯出。競品全無此完整度，這是「敢讓 Bot 動手」的差異點。
• ✅ 完成標準：任何一次 box 操作可在 UI 還原全过程；手機端可看。

---

軌 C：操控鏈路（更精確、更少來回）

量測前提（bench 已證）：模型回合佔 90% 時間，環境端 0.7–3.5s/步。 所以「少花 token/回合」＞「壓環境延遲」。C1 先做。

C1. Prompt caching（全案最高 CP 值） ✅ 2026-11：Anthropic 三斷點＋CACHE_STATS；前綴穩定約束寫進 agent.rs 迴圈前註解

• 現況：src/providers.rs 全無 cache_control；每步重送 system＋facts＋~40 工具 schema＋截圖。
• 做法：
  1. Anthropic 系：system、tools、facts 段落、歷史末兩條加 cache_control: ephemeral；OpenAI 相容：確保前綴穩定（tools 排序固定、facts 位置固定、描述不動）。
  2. facts::for_turn 改在開回合算好後凍結進 request（現況每步可能因快取過期而變文→破 cache）。
  3. 工具清單在回合內不変（quick_tools 目前每步重組→改成快回合級常數）。
• ✅ 完成標準：Anthropic 路徑 cache_read_input_tokens >70%；bench 總時間/成本下降 ≥15%（列進 results.json 欄位）。
• ✅ 已驗證（2026-11）：facts 於回合開始加入（loop 外）、tools 每回合建一次、quick_tools 為確定性映射→回合內前綴穩定；以 agent.rs 迴圈前註解固定此約束。

C2. AX 直寫操作（精確度根治）⛓（H1、C3 前件） ✅ 2026-11：axwrite（AXPress/AXValue）＋act() 像素路徑退回；darwin type-check 過；待 Mac CI＋bench 驗收

• 現況：agent-desktop 唯讀；所有動作=滑鼠座標＋鍵（computer.rs、cloudbox.rs xdotool）。
• 做法：新模組 src/axwrite.rs：
  • macOS：AXUIElementPerformAction(kAXPress)、AXUIElementSetAttributeValue(kAXValue/SelectedText)；選單項 AXPress 不須滑鼠。
  • Linux/AT-SPI：Action.DoAction、EditableText.SetContents/SetTextContents（box 內 a11y 助手擴充）。
  • 手腳端：remote::run_on_device 加 ax_act 指令。
  • 保留現行座標路徑当後備（AX 不可用時自動降級，並在結果註明走了哪條）。
• 效益：打字進欄=1 呼叫（消掉 click+全選替換邊角case）；被遮擋/其他桌面視窗可操作；快速模型不再對編號點錯（消掉 bench 記錄的這整類失敗）。
• ✅ 完成標準：T3/T8 與 lxappearance 題步數 −30% 以上；「編號點錯」在 v12 bench 歸零。

C3. 高層語意工具 ✅ 2026-11：menu_click/fill_form/wait_for 進 computer 工具（AX）；batch 每步 expect 斷言（失敗即停＋附截圖）。紅隊/多選單 App 的 bench 加題待 Mac 驗證

• menu_click("檔案","新視窗")：走 AX 選單樹（app_menu_controls 已會讀），3 回合→1。
• fill_form(fields:[{name,value}])：AX SetValue 逐欄填，1 回合＋1 截圖。
• wait_for(what, timeout)：文字/元素出現或消失＋逾時（box 的 SETTLE_SH 探測通用化）；消掉截圖輪詢。
• batch 每步加 expect 斷言：失敗點自動帶截圖＋原因回傳。
• ✅ 完成標準：T8 填表 ≤2 回合；新增 2 題 bench（多選單 App、長表單）步數達標。

C4. 控制樹 diff 回傳 ✅ 2026-11：每次截圖附「＋/－ 控件變化」（multiset diff，macOS＋box 都有）；快速模型每步少讀整張清單。token −40% 的對照組數據待量

• 每步回傳：控制清單變化（新增/消失/值變）＋（僅主模型/審查步）截圖；marks::fingerprint 材料現成。
• 效益：每步少送一張 ~1.5k tokens 的圖→上下文膨脹慢 3 倍、摘要頻率降、TTFT 降。
• ✅ 完成標準：「分開跑」模式每回合 token −40%，成功率不降（bench 對照組）。

C5. 環境端小錢

• Mac：screencapture 與 AX 讀取並行（省 ~0.3s/步）。
• 遠端路：截圖改 WebP（同品質 −25% 位元組，image crate 已支援編碼）；手腳端先縮到 1024 再過網；AX 讀取與截圖並行後併入同回覆。
• ✅ 完成標準：T7/T8 遠端題总時間 −10%。

C6. 意圖優先於 GUI（facts → 意圖登記表）

• 常見操作（音量、亮度、Wi-Fi、鎖屏、時區、截圖、App 內建指令）登記 CLI/AppleScript/Shortcuts/dbus 捷徑，系統指示明令「有捷徑先捷徑，GUI 是後備」；bench T1 已證指令路 9 步 vs GUI 2 分鐘。
• ✅ 完成標準：8 題中指令路佔 5 題以上、總步數 −25%。

C7. 迴路保護從字串比對改狀態碼 ✅ 2026-11：noop 偵測改機器標籤 [[noop]]（computer::NOOP_TAG），控制流不再匹配中文句子；合同測試釘住「句子可改、標籤不能跑掉」

• 現況：agent.rs:1144 用 output.contains("畫面和上一步完全一樣") 判 noop——脆。
• 改：工具結果尾部機器欄位 [status: ok|noop|blocked|needs_human]，迴路偵測（agent.rs:1095-1144、卡住偵測）讀欄位不讀散文；聊天 UI 仍顯示人話。
• ✅ 完成標準：無字串比對迴路邏輯（單元測試反推）。

C8. 技能重播擴張（接 P7）

• teach 示範錄影→replay_skill 已有（時區題 9 步 49s→4 步 15s）。加：重播失敗自動截圖交還模型、示範可直接錄人的真實操作（box 端事件記錄）、技能進 registry 可分享。
• ✅ 完成標準：使用者示範一次→第二次同任務 ≤5 步零模型。

C9. Windows 操控面（接 P8）

• UIA（agent-desktop-windows）讀取＋SendInput；x11.rs/wl.rs 對應 win.rs；facts/意圖表 Windows 版。
• ✅ 完成標準：Windows 手腳可被大腦派畫面步（bench T2/T5 移植版）。

---

軌 H：Harness 收斂（借 pi-bolt 的「少而熟」，不抄它的「純通用」）

判定：在 GUI 域，AnyBot 的 harness（圖剪枝、noop 偵測、重複攔截、StepPlan、核准閘、 bench 驅動）比 pi-bolt 對等物更完整；落後點只在工具數量與每步 token 成本。

H1. 12 個 computer_use_* → 1 個 computer 工具（action enum）⛓（依賴 C2） ✅ 2026-11：單一 computer 工具（action enum），模型輸出邊界展開回內部名；遠端 limb 免更新

• 採 Anthropic computer tool／OpenAI CUA 的公版形狀：{action: screenshot|zoom|click|type|key|scroll|move|drag|batch|open_app|menu|fill_form|wait_for, ...}。模型對這形狀有訓練先驗；schema token 減半；消掉「選錯工具/換路由」失敗類。
• 過渡：保留舊名 1 個大版本（內部轉發到新工具），系統指示同步改。
• ✅ 完成標準：工具 schema token −50%；快速模型工具選擇錯誤在 bench 歸零。

H2. 瀏覽器 18 個 browser_* → ≤6 個（read/open/act/extract/upload/download 級別）。

• ✅ 完成標準：全工具清單/請求 ≤15 個。

H3. 描述瘦身：教學移入 system

• 工具 description 只留參數語義；使用時機（「Use it when…/Do not…」）集中進 system 的「工具使用規則」章（被 C1 cache 覆蓋）。
• ✅ 完成標準：tools 序列化 token −60%，效果由 C1 指標連測。

H4. 雙軌結果（人話＋機器欄位）＝ C7，保留人話是產品決策（pi 無此需求，不要抄掉）。

---

執行順序建議（里程碑）

里程碑	內容	驗證
M1（第 1–2 週）	P1 授權、P3 註解整併、S1 docker.sock、C1 prompt cache	紅隊 grep 乾淨；cache_read>70%；bench 成本 −15%
M2（第 3–5 週）	C2 AX 直寫、H1/H3 工具收斂＋瘦身、S4 egress、P8 CI	v12 bench：步數 −30%、編號點錯歸零
M3（第 6–8 週）	C3 高層工具、C4 diff、C7 狀態碼、S3 injection 防線＋紅隊進 CI	T8 ≤2 回合；紅隊洩漏 0
M4（第 9–12 週）	P2 英文＋demo、S2 2FA、S5 稽核時間軸、P4 SQLite	公開發布（英文首屏）；bench 夜間回歸上線
M5（第 13 週起）	P6 記憶/RAG、P7 技能 registry、C6 意圖表、C5 小錢、C8 重播、C9 Windows	Khoj/Letta 對照測試；技能安裝量開始計量

每階段結束以 bench/computer-use 固定題組＋新增題（多選單 App、長表單、注入紅隊）做前後對照，結果續寫進 bench/computer-use/README.md 的版本記錄。