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. 授權條款 ⛓（社群/貢獻的前件）
- 加 `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. 逆向工程註解整併（法務風險）
- 全 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. 平台與工程衛生
- **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 前件，最高優先）
- 現況：`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 防線（操控域的核心風險）
1. 瀏覽器/畫面的敏感動作白名單：送出付款、發訊息、刪除、對外發文 → 一律詢問（policy 規則層，非模型自決）；網站來源（`browser_open` 的域）進政策判定。
2. 截圖遮罩：vault 已存卡號/密碼，截圖進模型前對照螢幕上可偵測的卡號/OTP 樣式做遮罩（正則＋框選重繪）。
3. `keep_to_chosen`（B26 那類參數改寫）補整合測試，禁模型改寫 `computer`/vault 目標。
4. 注入標記：來自網頁/文件/螢幕文字的內文，進歷史時加包夾標記（防「請忽略之前指令」）。
- ✅ 完成標準：注入紅隊集（10+ 題）在 bench 跑，成功外洩/成功送出為 0；紅隊集進 CI。

## S4. Egress 代理收斂
- 現況：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 值）
- 現況：`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 前件）
- 現況：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. 高層語意工具（依赖 C2）
- `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 回傳（快速模型只吃文字）
- 每步回傳：控制清單變化（新增/消失/值變）＋（僅主模型/審查步）截圖；`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. 迴路保護從字串比對改狀態碼（配合 H3）
- 現況：`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）
- 採 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` 的版本記錄。