# M（vpn-cef-browser） **產品名稱是「M」（智新工作瀏覽器；圖示也是 M）**，程式、套件、資料夾仍叫 `vpn-cef-browser`。改名只改**顯示名稱**（App 名稱、選單、視窗、關於、DMG 名稱、桌面捷徑、文件的產生者欄位）； **bundle ID `com.steps.vpn-cef-browser`、簽章身分、資料資料夾 `~/.local/share/vpn-cef-browser`、執行檔名、`vpndoc://` 都不能改**——bundle ID 或簽章一變，macOS 就會當成另一個 App，鑰匙圈會再問一次、設定資料也對不上。 舊版的「VPN Browser.app」跟新的「M.app」是同一個 bundle ID：換新版時要把舊的刪掉。 用 CEF（Chromium Embedded Framework）打造「真的帶著自己核心」的瀏覽器 POC， 跟 vpn-browser（Tauri 版，借系統 WebView）是兩個獨立方向的實驗專案。 ## 為什麼要有這個專案 跟 Tauri 版最大的差異：不依賴作業系統裝好的 WebView 引擎（Linux 上是 webkit2gtk、Windows 是 WebView2、macOS 是 WKWebView），而是自己帶一份 Chromium（透過 CEF）。代價是安裝檔變大很多（stripped 後約 465MB），換來 三平台渲染引擎一致、不依賴系統是否裝了瀏覽器元件。 ## 架構 瀏覽器外框（分頁列 + 工具列 + 書籤列、左側圖示列）是**內建網頁** （`resources/chrome/`），各裝在一個 BrowserView 裡，跟分頁內容的 BrowserView 用 CEF 的 Views 版面排在同一個原生視窗——不像 Tauri 版要搞多視窗疊貼同步。 早期外框是用 Views 元件（LabelButton / Panel）刻的，但 Views 只能畫純色 方塊，做不出圓角、漸層、陰影，看起來不像 Mac App，所以改成 HTML/CSS。 - `src/shared/window_state.rs`：**每個視窗一份**的狀態——分頁列表、作用中 分頁、外框 BrowserView 的參照，加上一個全域登記表讓 Client 端共用 的 Handler 能用 `Browser::identifier()` 反查「這個 Browser 是哪個視窗的 哪個分頁」。分頁 = 一個 BrowserView，所有分頁都裝在同一個內容欄 Panel 裡、flex=1，只有作用中的 `set_visible(true)`（BoxLayout 會略過不可見的 子 view），切分頁就是切可見性，頁面狀態都保留。狀態一變就 `push()` 整份 JSON 給外框網頁重畫 - `src/shared/chrome.rs` + `resources/chrome/`：外框。`chrome.html`（分頁列、 工具列、書籤列）、`sidebar.html`（左側圖示列）；網頁上的操作用 `fetch('vpndoc://app/api/chrome/<指令>')` 回到 Rust。分頁列空白處用 CSS `-webkit-app-region: drag` 標成可拖動視窗（DragHandler 轉交給視窗）。 下拉選單（⋮、下載、所有書籤）是原生選單（`app_menu.rs` 等） - `src/shared/settings.rs` + `settings.html`：設定（預設首頁〔沒設就是空白頁 `about:blank`，沒有內建的預設網站〕、預設聊天、**說明**），存在 `settings.json`；「⋮ → 設定…」或 ⌘,。**辦公文件位置**（`locations.rs`）：文書、試算表、簡報、上傳的檔案、資料夾、簡報圖片可以放到別的資料夾 （設定頁輸入路徑或按「選擇…」〔macOS 原生選資料夾視窗，要在 UI 執行緒跑，所以開工作、頁面輪詢〕；底下會有 `documents/ sheets/ slides/ files/ slide-assets/ folders.json`； 設定、書籤、歷史紀錄、Tor 等其他資料不動）。換位置之前先問：新位置**已經有辦公資料**→ 改用它（舊的不動、可以切回去）；沒有→「搬移現有文件」（同一個磁碟用 rename 瞬間完成；跨磁碟先複製、核對檔案數和大小才刪舊的，出錯會還原）或「不搬、從空的開始」。路徑要是完整路徑、不能有 `..`、不能是磁碟根目錄、要寫得進去 （換位置前就檢查，不是等選完才報錯）；新位置不能在舊位置裡面。搬移在背景執行緒做。`docs.rs` 的 `docs_dir` / `folders_path` / `slide_asset_dir` 都經過 `locations::office_root()`。**影音資料夾**：影片頁掃描的資料夾可以自訂（多個、檢查過存在、去重；空的 = 預設的下載 / 影片 / 音樂），影片頁的 播放 / 縮圖 API 只認這些資料夾底下的檔案。「說明」卡片：App 版本（Cargo.toml 的 `version`）、Chromium / CEF 版本（CEF 標頭的版本字串）、 平台、資料位置，加上本軟體的簡介和功能清單（`about` 欄位由 `settings.rs` 的 `about_json()` 提供） - `src/shared/security.rs`：連線安全性/憑證檢視。資料來自 CEF 的 `NavigationEntry::SSLStatus`（Chromium 自己的判定）：TLS 版本、憑證 簽發給/簽發者/有效期/序號/憑證鏈、`cert_status` 旗標解成中文、混合 內容。鎖頭圖示（🔒 安全 / ⚠ 有問題或 HTTP / 🏠 內建頁）跟著作用中分頁 的載入狀態更新；按下去把報告存起來、開一個 `vpndoc://app/cert.html` 分頁顯示（讀 SSLStatus 要在 UI 執行緒，自訂協定回應在 IO 執行緒，所以 先存再開） - `src/shared/simple_app.rs`：視窗/BrowserView 的建立邏輯（改自官方 `cefsimple` 範例），`on_window_created` 組版面：外層垂直 [上方外框（全寬）][下面一列]，下面一列水平 [左側圖示列][各分頁 BrowserView]； `target="_blank"`/`window.open` 的彈出視窗掛成來源視窗的新分頁 - `src/shared/simple_handler/`：Client 端各種 Handler（標題列、生命週期、 載入錯誤……，同樣改自 `cefsimple`）。載入錯誤頁是自己畫的中文版， 憑證錯誤（`ERR_CERT_*`）會標成安全警告——CEF 預設會拒絕憑證有問題 的連線，使用者看到這頁就是「被擋下來了」 - **「文件」首頁（`resources/docs/drive.*`）**：雲端硬碟式的檔案管理。左側 ＋新增（資料夾 / 文件 / 試算表 / 簡報）、我的檔案、與我共用、近期存取、 已加星號、垃圾桶；右側顯示目前資料夾內容，可切清單或圖示檢視；點檔案 才開啟，文書 / 試算表 / 簡報頁面頂端有 ← 回到首頁。文書、試算表、簡報 三種檔案共用同一套儲存（`docs.rs` 的 `Kind`，各自目錄與修改紀錄）， 資料夾存 `folders.json`，星號 / 垃圾桶 / 最近開啟是 Doc 上的欄位。 「與我共用」目前只是說明用的空狀態：沒有雲端帳號，不可能有別人共用給 你的檔案。瀏覽器左側圖示列的「文件」開這個首頁。 - `src/shared/docs.rs` / `docs_provider.rs` + `resources/docs/`：本機文件 編輯器，介面照 Google 文件：頁首標題 + 「檔案 編輯 查看 插入 格式 工具 說明」選單列（含子選單）、右上「修改紀錄」「共用」、灰底白紙的頁面。 每份文件一個 JSON 檔存在 `~/.local/share/vpn-cef-browser/documents/`， 前端用 `fetch()` 打 `vpndoc://app/api/*`（list/doc/new/save/delete/ export/info/history/version/snapshot），資料不離開這台電腦。 - 列表：摘要、相對時間、搜尋標題/內容；沒打標題時自動用內容第一行 - 編輯：復原/重做、粗斜底刪、上下標、H1–H3/內文/引用/程式碼、對齊、 清單/編號/核取方塊、縮排、連結、圖片（「插入 → 圖片」或工具列 🖼：**從電腦選擇**、輸入網址；也可以貼上或把圖片檔拖進文件， 內嵌 data URL。點陣圖超過 2000 px 或 2.5 MB 會自動縮小〔最長邊 2000 px，JPEG 重新壓縮、PNG / WebP 維持 PNG 保留透明，GIF / SVG 原樣〕， 縮完還超過 8 MB 就說明、不插入，不是圖片的檔案也會說明；`office.js` 的 `pickImage` / `pickImageBlob`）、表格、分隔線、日期、尋找與取代（Ctrl+H）、 字數統計、1.2 秒自動存檔 + Ctrl+S - 修改紀錄：Rust 端每次存檔做版本快照，5 分鐘內的自動快照合併成一個 （不然每 1.2 秒一個），最多 100 個；「保留目前版本」會釘選（檔名 `{ts}-pinned.json`），自動存檔不覆寫也不修剪。側板點版本 → 唯讀預覽 → 還原 - 共用：文件只在本機、沒有雲端連結，提供複製純文字/帶格式到剪貼簿 （scheme 加了 SECURE 才有 `navigator.clipboard`）、匯出 HTML/ Markdown/純文字到 `~/Downloads`（或 `~/下載`）、開聊天 - 所有對話框都自己畫（Alloy 沒有 alert/confirm/prompt）；列印 / PDF 見下面 「文書的版面與排版」 - 側欄「文書」「聊天」是「已開著就切過去、沒有才開新分頁」 ## 開發 ```bash # 第一次要先抓 CEF prebuilt binary（約 1.5GB） cargo run -p export-cef-dir --manifest-path /Cargo.toml \ -- --force $HOME/.local/share/cef export CEF_PATH="$HOME/.local/share/cef" cargo build # 啟動（debug 版；LD_LIBRARY_PATH 要指到 target/debug，libcef.so 在那裡） LD_LIBRARY_PATH=$PWD/target/debug ./target/debug/vpn-cef-browser ``` 文件編輯器的 HTML / CSS / JS 是編譯時用 `include_str!` 打包進執行檔的，改了前端 也要重新 `cargo build`。加上 `--remote-debugging-port=9222` 啟動，就能用 DevTools 協定（或 `http://127.0.0.1:9222`）檢查頁面、驅動測試。 ## 打包安裝檔 ```bash packaging/build-packages.sh # 輸出到 dist/，約 1 分鐘 ``` 需要 `dpkg-deb`、`fakeroot`、ImageMagick `convert`。一次產生： - `dist/vpn-cef-browser_<版本>_amd64.deb`（約 100 MB）：Debian / Ubuntu 用 `sudo apt install ./vpn-cef-browser_*.deb`（自動裝依賴的系統函式庫）， 裝到 `/opt/vpn-cef-browser`，終端機指令 `m`（在背景開、馬上回到命令列，可以帶網址或檔案； `vpn-cef-browser` 是前景執行、看得到記錄），並有應用程式選單捷徑 - `dist/vpn-cef-browser-<版本>-linux-x86_64.tar.gz`（約 135 MB）：其他主機用。 解開後 `./vpn-cef-browser.sh` 免安裝直接跑，或 `./install.sh` 裝到自己 帳號（`~/.local`，免 root）、`sudo ./install.sh --system` 裝給所有使用者、 `./install.sh --uninstall` 解除安裝 - `dist/SHA256SUMS`：校驗碼 `libcef.so` 會 strip（1.4 GB → 約 270 MB），語系只帶 zh-TW / zh-CN / en-US / en-GB。目標主機需要 x86_64 Linux 與 Chromium 依賴的系統函式庫（deb 會自動裝， tar.gz 的 `README.txt` 有 apt 指令）。使用者資料在 `~/.local/share/vpn-cef-browser/`，解除安裝不會動它。 ### Linux 版跟 macOS 版的對應（`src/linux/`） macOS 用系統元件做的東西，Linux 各有對應的做法，改 macOS 那邊的時候這邊也要跟著看： - **名稱 / 圖示**：捷徑名稱是「M」（`Name[zh_TW]` 也要寫，不然中文桌面會沿用舊翻譯），圖示從 `packaging/icon/AppIcon-1024.png` 轉各種尺寸。視窗的 WM_CLASS / Wayland app id 設成 `vpn-cef-browser`（`WindowDelegate::linux_window_properties`），要跟 .desktop 的 `StartupWMClass` 一樣，工作列才對得到捷徑；視窗圖示另外換掉（CEF 預設是 Chromium 的藍色圓圈， `resources/linux/app-icon-*.png`）。標題列是「頁面標題 - M」 - **已經開著又開一次**：Linux 再按一次捷徑、用 M 開檔案、`xdg-open` 網址，都會再跑一個行程，它把命令列 交給已經在跑的那一個後自己結束。CEF 預設的處理是開一個 Chrome 風格的視窗——就是「突然變回原版 Chromium」（Google 首頁、「Chromium 不是你的預設瀏覽器」）。`on_already_running_app_relaunch` 改成： 有帶網址 / 檔案就開成新分頁，沒帶就開新視窗。macOS 再按 Dock 圖示不會開第二個行程 - **檔案對話框**（網頁上傳檔案、開啟檔案、另存新檔 / 另存 PDF、設定頁選資料夾）：Alloy 風格沒有內建 對話框，macOS 用 NSOpenPanel（`mac/file_panel.rs`），Linux 叫 zenity（KDE 用 kdialog， `linux/file_dialog.rs`），在背景執行緒等，選完回 UI 執行緒。zenity 4 另存新檔時檔案不存在就帶不出 檔名，所以先放一個空檔、對話框讀到檔名就刪掉 - **快捷鍵**：macOS 走選單列，Linux 用 `Window::set_accelerator`：Ctrl+T / W / Shift+W / L / D / N / Shift+N / O / H / ,、Ctrl+R / F5、Ctrl+Shift+R / Shift+F5、Alt+← / → / Home、F11。同一個指令要兩組按鍵 得用兩個 id（`set_accelerator` 會先拿掉同一個 id 原本的按鍵）；Ctrl+F5 留給簡報的「從頭播放」 - **影音**：沒有 AVPlayer，影片頁、「開啟檔案…」點影音檔交給系統的播放器（`xdg-open`）； 縮圖用 ffmpeg（有裝才有） ### Google 雲端硬碟同步的用戶端 ID（只有發行者做一次） 辦公的「上傳到 Google 雲端硬碟」（`src/shared/gdrive_sync.rs`）用官方 Drive API，需要一組 **OAuth 用戶端 ID**。這組是**公司的**（發行者建一次、編進程式），**使用者不用建任何東西**：在設定頁按「連線」、用自己的 Google 帳號按「允許」，檔案存進他們自己的雲端硬碟。 1. Google Cloud Console → 建立（或選一個）專案 → 「API 和服務」→ 啟用 **Google Drive API** 2. 「OAuth 同意畫面」：Workspace 公司選「**內部**」（只有公司帳號能用、不用送審）；範圍加 `https://www.googleapis.com/auth/drive.file`（非敏感範圍：只能碰這個 App 自己建立的檔案） 3. 「憑證」→ 建立憑證 → **OAuth 用戶端 ID** → 應用程式類型選「**電腦版應用程式**」→ 記下用戶端 ID 跟密鑰（桌面應用程式的密鑰不是機密，Google 的規範就是編進程式；安全靠 PKCE 和使用者自己的同意） 4. 放進 `packaging/google-oauth.local`（第 1 行用戶端 ID、第 2 行密鑰；已在 `.gitignore`），再跑 `packaging/build-macos.sh`（或 `build-packages.sh`）。**要重新編譯**（`SKIP_BUILD=1` 不會編進去）。沒有這個檔案的版本，設定頁會說「還沒有設定」，使用者可以在「進階」自己填一組 ### macOS ```bash brew install rustup cmake ninja && rustup default stable # 第一次 packaging/build-macos.sh # 輸出到 dist/，第一次會自動下載 CEF（約 470 MB） ``` 需要 Xcode（`ibtool` / `codesign` / `hdiutil`）。產生 `dist/M-<版本>-macos-.dmg`（約 130 MB，架構跟編譯 的機器相同），打開後把「M」拖進「應用程式」即可；`.app` 本身也留在 `dist/stage-mac/` 可直接執行測試。 - macOS 的子行程跑的是另一個執行檔 `vpn-cef-browser-helper`（包成 5 個 `vpn-cef-browser Helper (…).app`），它也要註冊 vpndoc://，選項跟主程式共用 `src/shared/scheme.rs` - 預設只做 ad-hoc 簽章：別台 Mac 第一次開會被 Gatekeeper 擋，要右鍵 →「打開」， 或 `xattr -cr "/Applications/M.app"`。有 Apple Developer ID 的話用 `SIGN_ID="Developer ID Application: …" packaging/build-macos.sh`（要正式發佈 還得再做 notarize） - 使用者資料目前在 macOS 上也放 `~/.local/share/vpn-cef-browser/` - 影音播放：CEF 標準版沒有 H.264 / AAC 解碼器（mp4、mov、m4a 播不了，mp3 / webm 可以）。macOS 上點到影音連結（或伺服器回應是影音）會開「播放器分頁」 （`vpndoc://app/player.html`），把 AVKit 的 AVPlayerView 嵌在分頁內容區 （`src/mac/player.rs`），串流播放並帶上網站 cookie；分頁上方資訊列的「下載」 才存檔。左側「影片」（`media.html`）列出下載 / 影片 / 音樂資料夾（可以在設定頁改成自己的資料夾，見 `locations.rs`）裡的影音檔， 左邊有資料夾樹可以切換（來源資料夾 + 底下有影音檔的子資料夾，數字是含底下的檔案數，選的資料夾會記住；「資料夾設定…」開設定頁） （同一個檔案掃到兩次會去掉重複；影片有縮圖，由 `qlmanage -t` 在背景產生、快取在 `media-thumbs/`；「開啟檔案…」可以播任何位置的檔案），點了在播放器分頁播放。 判斷規則與 API 在 `src/shared/media.rs` - 播放器分頁上方資訊列：「← 影片清單」（切回清單分頁）、「⛶ 全螢幕」、下載 / 在 Finder 中顯示。**影片全螢幕**：視窗進 macOS 全螢幕、播放器蓋滿整個視窗內容，右上角一顆 ✕ （SF Symbol `xmark.circle.fill` 的調色盤版：白 X + 半透明黑圓，亮暗畫面都看得到），按 ✕ 或 Esc 離開（Esc 在 `SimpleApplication::send_event` 攔，影片全螢幕中才攔，不管鍵盤焦點在哪）； 切到別的分頁、關掉播放器分頁、使用者自己把視窗退出全螢幕，都會一起結束影片全螢幕 （`media::set_video_fullscreen`、`WindowState::sync_players` / `set_fullscreen`） - **播放器位置的坑**：播放器是視窗內容 view 的子 view，位置要用「分頁內容區在視窗裡的範圍」算。 原本用 `View::convert_point_to_window`，但 cef-rs 的包裝把傳進去的點複製一份再轉換、結果沒寫回 （跟 `task_info()`、`set_preference` 的 error 參數同一類問題），永遠拿到 (0, 0)，播放器因此擺到 視窗左上角、蓋住網址列跟左側欄。現在改用螢幕座標相減（`view.bounds_in_screen()` − `window.client_area_bounds_in_screen()`，見 `window_state.rs` 的 `view_rect_in_window`）。 - 測試用：帶 `--remote-debugging-port` 的測試實例吃環境變數 `VPN_MEDIA_TRACE=1`，把播放器 view 的位置印出來（`media-trace:`），並開 `vpndoc://app/api/media/self-test`（`click-x` 按下 ✕、 `escape` 送出 Esc 事件、`hit` 問某個位置最上層是哪個 view）。自動測試沒有輔助使用權限、送不出真的 滑鼠 / 鍵盤事件，所以改在程式裡面做；平常使用的 App 不開。 - 聊天（`chat.rs` + `resources/chrome/chat.html`）：左側「聊天」可以選內建聊天 （vpnadmin）、Google Chat、LINE。LINE 個人帳號沒有網頁版，用 **LINE 官方的 Chrome 擴充功能**在分頁裡開——只用這個方式，Linux（沒有 LINE 電腦版）也一樣 能用；預設開哪個在 選擇頁或「設定」裡改，在「聊天」上按右鍵可以隨時切換。為了讓 Google 登入不被 擋，全域 User-Agent 用 CEF 預設（標準 Chromium），自家品牌「VPNBrowser/1.0」 只加在送到 steps.tw 的請求標頭（`BrandResourceRequestHandler`） - Chrome 擴充功能（`extensions.rs`、`crx.rs` + `extensions.html`，「⋮ → 擴充功能…」）： CEF 底層是完整的 Chrome，`--load-extension` 載入的擴充功能（背景程式、內容 腳本、擴充功能頁面）在 Alloy 分頁裡都能用。安裝 = 從 Google 官方下載 .crx → 驗證 CRX3 的 RSA 簽章（擴充功能 ID 必須等於開發者公鑰的雜湊）→ 解壓到 `<資料夾>/extensions//`、manifest 補 `key`（ID 才會跟官方一樣）。啟動時 在 `on_before_command_line_processing` 接成 `--load-extension`；CEF 沒有執行中 載入的 API，所以安裝 / 停用 / 移除要重新啟動（App 內建「重新啟動」）。啟動後 背景檢查更新，新版下次啟動換上。沒有 chrome://extensions、工具列的擴充功能 按鈕還沒做。下載用系統的 `curl`（Linux 安裝包已列為相依套件） - 介面語系固定繁體中文（CefSettings.locale = zh-TW），擴充功能（例如 LINE）也會 跟著顯示中文 - 結束 App（⌘Q、重新啟動）改成「關掉所有視窗」：cefsimple 原本的 close_all_browsers 握著 SimpleHandler 的鎖呼叫 close_browser，CEF 同步回呼 do_close 又要拿同一把鎖，整個 App 會卡死 - 辦公的 Word / OpenDocument（`src/shared/office/` 轉檔、`office_api.rs` API、 `resources/docs/office.js`）：全部是自己的程式，不靠 LibreOffice 或系統工具， Mac / Linux 一樣。首頁網址是 `vpndoc://app/office`（頁面是 drive.html，舊網址 也還能開）。 - 文書「檔案 → 另存新檔」：.docx、.odt（ODF 1.2，用 OASIS 官方 RelaxNG schema 驗證過）、.rtf、.doc。Word 97 的二進位格式沒有開放的寫入實作（PHPWord 之類的 函式庫也一樣），所以 .doc 的內容是 RTF，Word / WPS / LibreOffice 開的時候會看 內容、正常開（Mac 的「快速查看」預覽不出來）。Mac 上跳系統的存檔視窗 - 開啟：.docx、.odt、.rtf、.doc——.doc 看內容判斷：Word 97-2003 二進位（自己讀 OLE 複合文件：文字、字元 / 段落格式、樣式、表格、清單、內嵌與浮動圖片、超連結）、 其實是 RTF / HTML / MHT 的 .doc（網站系統常見）、其實是 .docx；Word 6/95 只讀 文字。EMF / WMF 圖片瀏覽器顯示不了，留一段說明文字 - 上傳到「辦公」的 Word / ODT / RTF 點了直接用文書開（第一次轉檔，之後開同一份）， 改完「檔案 → 儲存回原檔」照原本的格式蓋回去；Excel / ODS / CSV 用試算表開， 試算表可以存 .xlsx / .xls / .ods（SheetJS）；PowerPoint（.pptx）用簡報開（見下面「匯入 .pptx」） - 安全：XML 不處理 DTD（防外部實體攻擊）、解析前先量巢狀深度（擋幾千層的惡意檔）、 ZIP 每個檔案有大小上限；匯入的內容一律轉成中間格式再重新組 HTML（全部跳脫， script / 事件屬性 / javascript: 連結都不會帶進編輯器） - 測過的檔案：Apache POI 跟 LibreOffice 的公開測試檔（各版本 Word 產生的 .doc / .docx、.odt、中文 Big5 的 RTF）、macOS 存的 .doc、Laravel 式的 HTML .doc、MHT - PDF（`resources/docs/pdf-import.mjs`，用 pdf.js 在頁面裡轉，一樣不靠外部程式）： 在「辦公」點 PDF 會問要「直接開啟」（PDF 檢視器）還是「轉成可編輯的文件」，可以 記住選擇；⋮ 選單兩種都有。轉換：同一條基線的字併成行，再依行距（每頁各自統計， 公文常見的固定 27、28 點行距也接得起來）、縮排、上一行有沒有寫滿接成段落；字大的 短行當標題（「受文者：○○」這種欄位不算）；每頁頂端 / 底端重複出現的頁首、頁尾、 頁碼拿掉；跨頁的段落接回去。有框線的表格從繪圖指令找出格線，合併儲存格算得出來； 向量畫的圖表（長條圖、折線圖、流程圖）整塊畫成圖片；點陣圖片照放；掃描檔（只有 圖片沒有文字）先警告。字型認得標楷體、細明體、正黑體等；康熙部首字元（⼀⽇）換回 一般漢字。轉好的內容另存一份 .odt 在 PDF 旁邊，文書打開的就是它，改完「儲存回」 存回 .odt；PDF 本身不動。文書的「檔案 → 開啟…」也能選 PDF。沒有文字層的掃描檔需要 OCR，目前沒做；文字顏色、超連結、沒有框線的表格還不會還原 - **理科試卷 / 數學式**（用 110 年指考物理卷測的）：Symbol 字型的私用區字元（U+F0xx， α β λ μ Δ Φ ≤ ×…）換回真正的希臘字母 / 符號；上下標依字級與基線轉成 `` / `` （T甲、R₁、10⁻⁸）；堆疊的分數（分子 / 橫線 / 分母各是獨立的字）攤平成 `(分子)/(分母)`， 單一數字 / 字母不加括號；根號（Word 公式畫成路徑：左邊一撇 + 上面一條橫線）補回 `√`； 絕對值的短直線補回 `|`。向量畫的圖（含圖上的標示文字，這些字不會再重複出現在內文） 把周圍的字與圖形一起分群，整塊畫成一張圖；表格框裡其實是圖（只有一兩個字）的改成圖； 同一列的選項圖（A）～（E）併成一段。頁首（左右兩邊用很寬的空白字隔開的）跟偶數頁 頁首不會漏進內文。表格的橫線常被切成一格一格，分數偵測前先接成一條，不然發票這種 表頭會被誤判成分數。(A)(B) 開頭的行接在解說文字後面（`(B)：…`）不拆段 - 圖要「完整」：點陣圖加上蓋在上面的小圖 / 標示字（θ、座標、編號、「圖 13」說明文字都是另外畫的） 一起算成一張圖；選項小圖（A）～（E）連左上角的字母一起裁；裁圖時別張圖的邊緣（框線、 旁邊的標籤）蓋白；貼著圖上緣的內文（「…關係圖？」）留在內文。文字繞圖（圖在右邊、字在 左邊窄窄一欄）：這幾行的右邊界是圖的左邊，整題的敘述接成一段，圖放在敘述後面、選項前面。 PDF 把「10 V/m」整串當一個字、上標 6 另外畫在中間時，從上標的位置切開（10⁶ V/m）； 空白字不自己成行（不然會搶走旁邊的上標 10⁻⁸）；有分數的行行距比較大，仍接成同一段 - 修改這支檔案後的驗證方法：在執行中的測試實例用 Blob 載入新的 `pdf-import.mjs` （`import(URL.createObjectURL(new Blob([src])))`），不用重新打包；跟舊版轉同一批 PDF， 比較圖片 / 表格 / 字數與純文字差異 - 合併原卷（`resources/docs/exam-merge.js`，文書「檔案 → 合併原卷 PDF（題目、圖 + 這份詳解）…」）：AI 小幫手寫的 詳解 .md 只有答案和解析、放不進圖；原卷的題目與圖要從 PDF 轉。在詳解文件裡選一份原卷 PDF（辦公裡的 PDF 清單， 或從電腦選），PDF 現場轉成題目 + 圖，跟詳解依題號合併成一份**新文件**（原本的詳解文件不動）：每題「題目 → 圖 → 選項 →【詳解】→ 詳解內容」。切題：段落開頭是題號（`6.`、`6、`、`第 6 題`、`Q6`），題號要接得上（下一題，或最多 跳過兩題；從 1 重新開始 = 新的一大題，所以第二部分「一、二、」各自從 1 編號也對得上，題目的身分是「第幾次 重新編號 + 題號」）；`第 3-4 題為題組` 的短文 / 圖放在第 3 題前面；大題標題（一、二、、第○部分、說明框）不屬於上 一題。詳解開頭的說明、標題、結尾的聊天（「已為您…製作完畢」）不放進來；沒對到題目的詳解接在最後面、原卷沒有 詳解的題照樣留著；詳解第一段只是把題目又寫一遍（第二部分的子題）就拿掉。合併好跳摘要（N 題對到、哪幾題沒對到）。 Gemini Canvas 抓下來的 md 換行有意義：整行粗體（`**1. 答案：(E)**`）、整行數學式各自一段，黏在一起的 `$A$$B$` 拆成兩行，清單後面沒縮排的中文行是新的一段，畫面上的「直接編輯或用 Gemini 編輯」提示拿掉 - 用 AI 產生解析（`resources/docs/exam-ai.js`；辦公首頁 PDF 的「開啟 PDF」對話框 / ⋮ 選單「用 AI 產生解析」、文書「檔案 → 用 AI 產生解析」）：選考卷 PDF → 對話框說明會把 PDF 送到 AI小幫手（Gemini）、可貼官方答案（選填，AI 只負責解釋）→ 一鍵完成： PDF 在頁面裡轉成題目 + 圖，同時後端 `ai_panel.rs` 的 `solve`（透過 `office_api.rs` 的 `ai-solve` 工作，頁面輪詢 `status`） 打開 AI 對話窗、開新對話、在 Gemini 網頁裡跑 `SOLVE_SCRIPT`：模擬貼上 PDF（不行再試拖放、檔案輸入框；看附件有沒有出現）→ 等上傳完 → 放進提問（要求「N. 答案：(X)」格式、LaTeX 算式、不要 Canvas / 檔案 / 開場白）→ 按送出 → 等寫完（「停止」鈕消失後字數 連續 5 秒不變；從頭到尾沒看到停止鈕就等 25 秒）→ 讀最後一則回答的 HTML，`sanitizeAiHtml`（`ai-html.js`，Gemini 的 KaTeX 節點只 取 LaTeX）清理後依題號跟原卷合併（`exam-merge.js`）。題目多、回答被截斷時，自動在同一個對話請它「接著寫」缺的題，最多 3 輪。 失敗（找不到輸入框 / 附不上 PDF / 送不出去 / 逾時 / 回答裡沒有題號）會說明原因，詳細步驟與 Gemini 頁面按鈕 / 元件的名稱記在 `gdrive.log`（「AI 自動解析（Gemini 頁面）」，沒有內容，Gemini 改版時用它調整選擇器）。測試：環境變數 `VPN_TEST_GEMINI_URL` （只有帶 `--remote-debugging-port` 的測試實例吃）可以把 Gemini 換成本機的假頁面 - 文書的版面與排版（`resources/docs/editor-layout.js`），比照 Google 文件 / Word： - 字級：− / ＋（Ctrl+Shift+, / .）一次加減 1 點，也能直接打 1–400；沒選字時設的 字級套到接著打的字。試算表（預設 10pt，工具列新加的字級）、簡報也是一次 1 - 格式刷（工具列 🖌、「格式」選單）：按一下套用一次，按兩下可以連續套用，Esc 結束。 文書複製粗斜底刪、上下標、文字顏色、螢光筆、字型、字級、段落樣式（標題 / 內文）、 對齊；試算表照來源範圍的排列重複套上去（只點一格就套成跟來源一樣大），點欄 / 列 標題整欄整列套用；簡報複製文字方塊的字級、顏色、字型、粗斜、對齊、填滿（圖形只有 填滿；沒自己設顏色、字型的跟著主題，套到另一種文字上時改成看到的樣子） - 文件大綱（查看 → 顯示文件大綱，Ctrl+Alt+A）：列出 H1–H3 和所在頁碼，點了跳過去； 整節上移 / 下移、升降階層、改名都能復原 - 目錄（插入 → 目錄）：附頁碼（點點引線）或附連結兩種，標題改了自動更新；點目錄出現 的小工具列可以更新、改樣式、移除 - 頁面設定（檔案 → 頁面設定）：A4 / A3 / A5 / B4 / B5 / Letter / Legal、直式 / 橫式、 邊界（一般、窄、適中、寬、公文） - 分頁顯示（預設，查看 → 分頁顯示）：跟 Word 的整頁模式一樣，一頁一張紙，每一頁都有自己 的頁首、頁尾、頁碼。做法是把編輯區排成一欄、固定高度、會換列的多欄版面（CSS `column-height` + `column-wrap`，Chromium 154 有），每一列就是一頁的內容區——瀏覽器 切欄跟列印用同一套分頁規則（孤行寡行、表格列不拆、標題不放頁底、分頁符號），所以畫面上 每一頁的內容跟印出來的 PDF 一樣（測試逐頁比對過）。白紙畫在編輯區後面，內容多一頁時 同一個畫格就補上。關掉分頁顯示是一整張連續的紙，用排版模擬畫分頁線 - 頁首、頁尾、頁碼（插入 → 頁碼 / 頁首和頁尾）：靠左 / 置中 / 靠右，頁碼格式有 「第 N 頁」「第 N 頁，共 M 頁」「N / M」「- N -」「Page N of M」，可以首頁不顯示； 分頁符號（Ctrl+Enter） - 列印（Ctrl+P）與「另存新檔 → PDF」：用 CEF 的 `print_to_pdf`（`office_api.rs` 的 print-pdf），頁首頁尾頁碼是 CSS `@page` 的邊框區，目錄的頁碼跟印出來的一樣。 列印是把 PDF 開在新分頁預覽，從那裡印或下載；存 PDF 在 Mac 上跳系統存檔視窗 - 存成 .docx / .odt / .rtf 都帶著這些（紙張、邊界、頁首頁尾的 PAGE / NUMPAGES 欄位、首頁不同、目錄——Word 的 TOC 欄位 / ODF 的 table-of-content、分頁符號、 標題書籤），開回來也讀得到；LibreOffice 開過確認一致。PDF 轉文件時也會抓紙張、 邊界和頁首、頁碼格式。RTF 順便修了：英數跟 `\u` 中文字的順序、目錄欄位內容漏出來 - 簡報（`resources/docs/slides.*`）的主題與效果，比照 Google 簡報 / PowerPoint： - 主題（整份簡報的背景、配色、字型、裝飾圖形）12 種：簡約、簡約深色、商務藍、繽紛 漸層、海洋、森林、暖陽、科技、典雅（宋體）、粉彩（圓體）、公務（標楷體）、空白； 「標題 / 章節 / 大數字 / 引言」這類大字頁有另一套封面樣式。另有三份附範例內容的 範本（工作報告、專案提案、產品介紹）。新簡報打開時右側先出現主題面板 - 版面配置 8 種（標題、章節標題、標題與內容、兩欄、只有標題、大數字、引言、空白）。 換主題時，預留位置的文字跟著換顏色、字型；還在預設位置的跟著搬，自己拖過的不動 - 轉場（淡入淡出、推入、滑入、擦去、圓形展開、縮放、翻轉、立方體，可調速度、套用到 全部）與物件進場動畫（淡入、浮現、四個方向飛入、縮放、彈跳、旋轉、擦去；「按一下時 / 與上一個同時 / 在上一個之後」、延遲、順序），用 Web Animations API 播放，編輯時 可以預覽，簡報模式按一下播下一個動畫 - 匯出 .pptx：主題背景（漸層、裝飾）畫成背景圖（JPEG，同一種背景只存一份），轉場、 動畫寫成 PowerPoint 的 ``、``（翻轉、立方體是 PowerPoint 2010 的效果，舊版退回淡入淡出），用 LibreOffice 匯入確認讀得到 - 主題以前做的簡報維持原本的樣子（「空白」主題），套主題時會猜哪個是標題 / 副標 - **匯入 .pptx**（`src/shared/office/pptx.rs`，只讀；檔案管理點 .pptx，或簡報頁「檔案 → 匯入 PowerPoint」）： 自己讀 zip + XML，不靠 LibreOffice。讀：投影片順序與大小（寬度對到 960，4:3 保持比例、左右置中， 字級同比例縮放）、背景（純色 / 漸層 / 圖片）、母片與版面配置上的裝飾圖形、文字方塊與佔位符 （位置、字型、字級、顏色、對齊、行距、項目符號 / 編號，照 PowerPoint 的繼承順序疊起來：投影片 → 版面配置 → 母片 → 簡報預設，顏色走主題色 + `clrMap`）、圖形（方塊、圓角、橢圓、填色、外框、旋轉、翻轉； 常見的預設圖形——箭頭、V 形、三角形、菱形、平行四邊形、梯形、五 / 六 / 八角形、星形、加號、甜甜圈、括號—— 跟自由繪製的外形（`custGeom`：直線、貝茲曲線、弧線）都變成 SVG 路徑，公式照 presetShapeDefinitions， 讀得到調整值）、圖片（含裁切、橢圓裁切）、表格、群組（含縮放）、直線、備忘稿、轉場。編輯器的文字方塊一個只有一種 字型 / 字級 / 顏色，所以字級差很多的段落會拆成由上往下疊的幾個方塊。沒辦法匯入的（圖表、SmartArt、 嵌入物件、EMF / WMF 圖片、物件動畫、陰影特效）用灰色方塊標出位置或略過，開啟時跳說明對話框 （`?note=`）。原檔不會被更動，也沒有「儲存回原檔」：編輯器能表達的東西比 PowerPoint 少，寫回去會把 原本的內容弄丟；要帶走用「匯出 .pptx」 - 匯入的簡報用到這些選用欄位（`slides.js` 最上面有完整說明）：文字的 `valign`（`align-content`）、`lh` （行高倍數）；任何元素的 `rot`（CSS `rotate`，不用 `transform`，才不會被動畫蓋掉）、`ln` / `lnw` （外框）、`r`（圓角）、`path`（其他外形：SVG 路徑字串 `M L C Q Z`，座標是方塊寬高的 0~1 倍，用 inline SVG 畫、外框用 `non-scaling-stroke`；匯出 .pptx 時寫成 PowerPoint 的自訂外形）；圖片的 `crop`、`clip`；`fill` 可以是 `transparent` 或 CSS 漸層；投影片的 `bg` 可以是 CSS 漸層或 `url(…)`。匯出 .pptx 時都轉得回去（漸層 / 圖片背景畫成背景圖、裁切在 canvas 上裁好、 圖片內嵌） - 簡報的「插入 → 圖片」跟文書一樣可以**從電腦選擇**（或輸入網址）：選到的圖片（先縮小）用 `POST vpndoc://app/api/slides-asset` 傳給 Rust （`docs.rs` 的 `store_uploaded_slide_image`：看檔案開頭判斷是 PNG / JPEG / GIF / WebP / BMP，不信 Content-Type；**SVG 不收**，上傳的檔案不可信；上限 12 MB），存成下面說的簡報圖片，簡報裡只放網址；照長寬比放在投影片中間（最大 640×380） - 圖片不放進簡報 JSON（編輯器每次修改都存一份復原紀錄，圖片放進去會變成幾十份）：存成 `slide-assets/.<副檔名>`（內容相同的只有一份），簡報裡只放 `vpndoc://app/api/slides-asset?h=`（內容跟網址一對一，所以回應可以一直快取）。刪除簡報後沒人用 的圖片會被清掉（簡報跟它的修改紀錄都掃過；一小時內存的不動，匯入是先存圖片再建簡報，清理剛好跑在中間 不能刪）。匯出 .pptx / .html 時再把圖片內嵌回去 - 檔案是不可信的：zip 有大小 / 數量上限（單一項目 120 MB、總量 600 MB、2 萬個項目、600 張投影片、每張 800 個物件）、XML 不准有 DTD（沒有實體展開）、群組巢狀有層數上限，壞掉的部分只會讓那個物件被略過、 不會整份失敗。`pptx.rs` 裡有 19 個單元測試（DTD / 實體、125 MB 的壓縮炸彈、路徑跳脫、座標對應、群組、 轉場、表格、備忘稿、圖形路徑……；`cargo test` 整個專案要下載 CEF，所以是把檔案放進只有 `zip` / `roxmltree` / `serde_json` / `sha2` 的小專案跑） - 左側圖示列可以自訂（左下角「自訂」，或 ⋮ → 自訂左側圖示列；頁面是 `resources/chrome/customize.*`）：拖曳排順序、開關顯示 / 隱藏、自己加按鈕（名稱、網址、 emoji 或一兩個字當圖示；點了就開那個網址，同一個網站已經開著就切過去）、恢復預設。在左側 按鈕上也能直接拖曳排序、按右鍵隱藏。內建按鈕除了辦公、聊天、影片、遠端，還有「效能」 （工作管理員）和預設隱藏的設定、擴充功能。設定存在 `settings.json` 的 `sidebar`（Rust 端 檢查過才存，見 `settings.rs`），清單跟著外框狀態一起推給每個視窗（`window_state.rs` 的 push），改了每個視窗馬上換；按鈕多到放不下時可以捲動 - 工作管理員（左側「效能」、⋮ 選單、macOS 選單列「視窗」；`src/shared/taskmgr.rs` + `resources/chrome/taskmgr.*`）：記憶體、CPU、網路三張卡片，各有最近兩分鐘的走勢圖，每 2 秒 更新；最上面一句話說負擔輕 / 中等 / 偏重和原因（例如最耗記憶體的分頁、最耗 CPU 的程序）。 - 記憶體：瀏覽器全部程序加起來直接問作業系統（macOS 的 phys_footprint，跟「活動監視器」 一樣；Linux 用 PSS），跟整台電腦的已使用 / 可用、記憶體壓力、交換空間比 - CPU：瀏覽器佔全部核心的比例、整台電腦的 CPU 使用率（兩條線畫在一起）、平均負載、 最耗 CPU 的程序 - 網路：瀏覽器的下載（流入）/ 上傳（流出）速度、開這頁以來的累計；整台電腦的速度讀網路 介面的累計位元組（macOS 用 sysctl NET_RT_IFLIST2 的 64 位元計數器，Linux 讀 /proc/net/dev），實體網路跟 VPN 通道（utun、ppp、tun、wg……）分開算，免得 VPN 的 流量算兩次。macOS 沒有公開 API 能查單一程序的網路量，所以頁面開著的時候在背景跑系統 內建的 `nettop`（每秒一筆、只給差值），加總這個瀏覽器所有程序。注意幾點：nettop 的 輸出接到管線會整塊緩衝，所以給它一個虛擬終端機（openpty）；exec 前把從瀏覽器繼承來的 檔案全部關掉（不然它會拿著瀏覽器的連線、占住埠），並把終端機設成它的控制終端，瀏覽器 不管怎麼結束它都會收到 SIGHUP 跟著結束；頁面 20 秒沒在看就停掉。Linux 只顯示整台電腦的 - 各分頁與程序：每個分頁、GPU、網路服務等程序的記憶體、CPU（CEF 的 TaskManager，跟 Chrome 的工作管理員同一套；同一個程序的分頁併成一列），可以點「切換」跳到那個分頁。 注意：cef-rs 包好的 `task_info()` 不會把結果寫回來，要直接呼叫 C 函式；TaskManager 物件 要一直拿著才會持續取樣（頁面沒在看 20 秒就放掉） - **內建聊天（本地聊天）**（`resources/chrome/messenger.{html,css,js}`、`messenger-data.js`，入口：左側「聊天」→ 聊天服務 選擇頁的「內建聊天」、右鍵選單、設定的「預設聊天」；`chat.rs` 的 `MESSENGER_URL`）：像 LINE 的聊天畫面，是 瀏覽器自己的頁面。**以前的 vpnadmin 網頁版聊天已經拿掉**（選擇頁、右鍵選單、設定、文件的「開聊天」都改開這個；舊設定值 `builtin` 自動當成 `messenger`）。**API 已經接上**：登入（`/ping`、`POST /auth/login`、Google）、`/auth/me`、`/auth/logout`， 以及對話、訊息、傳送、已讀、收回、靜音、隱藏 / 離開、聯絡人、建立聊天室、邀請 / 移出成員、相簿、個人資料、端對端加密與裝置核准、 即時更新（見下面「訊息 API」）。身分驗證公司用的是 **Google**（API 文件 2.2 節）：App 不整合 Google SDK、也不用自己申請 OAuth client ID（只允許 @steps.com.tw 的帳號、第一次登入自動建立帳號、管理員可以關閉 Google 登入），流程是四步：①開一個分頁到 `https://<伺服器>/auth/google?client=app` ②使用者在那個分頁登入 Google（這個瀏覽器的 Google 通常已經登入）③伺服器把分頁導向 `messageapp://oauth-callback?code=<交換碼>`（手機 App 註冊的 deep link；失敗時帶錯誤）④App 拿交換碼打 `POST /api/auth/exchange-code {code}` 換 token（90 秒有效、只能用一次）。我們是 CEF 瀏覽器、不是手機 App，所以第 ③ 步由 `src/shared/messenger_auth.rs` 在瀏覽器裡攔下來：`on_before_browse`、`on_resource_redirect`（伺服器 302）、未知協定的請求 （頁面用 JS 導向）三條路都接，第一個到的算；**只認自己開的那個登入分頁**、同一時間只有一個登入在等，別的分頁導向 `messageapp://…` 一律丟掉（不然惡意網站可以塞它自己的交換碼，讓使用者登入成別人的帳號）。結果存在 Rust 裡，聊天頁輪詢 `api/messenger-auth`（`start` / `poll` / `cancel`），登入分頁自動關掉、回到聊天頁。`client=app` 這個參數是探出來的（伺服器把 `client` 的值原樣當成 Google 的 `state`，其他參數名稱 `state` 都是隨機 40 字元），文件摘要沒寫第一步的網址，要核對。 **測試站目前不能用 Google 登入**（測試站的 Google 回呼網址設成了正式站、兩站帳號和 token 各自獨立）：選測試站按 Google 登入只會說明 原因、不會開分頁；要測 Google 登入請全程用正式站，測試站用 Email 登入。失敗情況（網域不符、Google 登入被關閉、使用者取消、交換碼 過期）各有中文說明 - **訊息 API**（`messenger-live.js`，依 API 文件第 3、4、6 節和網頁版 `messaging.js` / `messaging-crypto.js`）： - 對話 `GET /messaging`（隱藏的不列出；加密對話的預覽文件沒給明文，顯示「🔒 加密訊息」）、`GET /messaging/{id}`（成員、已讀位置， 打開聊天室時才載入）、訊息 `GET …/messages?before_id=`（一次 50 則，往前翻頁）、傳送 `POST …/messages`（文字用 JSON；圖片 `image` ≤ 5 MB、其他 `file` ≤ 20 MB 用 multipart，圖片超過 5 MB 改當檔案傳；上傳進度用 XHR）、`…/messages/read`、`…/recall`、`/mute`、`/hide`、 `/participants`（邀請 / 離開 / 移出）、`/messaging/users/all`、相簿 `…/messages/media`、`POST /auth/me`（姓名、大頭貼）。 語音訊息可以播放、位置訊息顯示成地圖連結、通話記錄顯示成一行；列表和訊息的格式用「寬鬆解析」（陣列或包在 `data` 裡都收）。 **置頂只存在這台電腦**（伺服器沒有這個功能，`localStorage` 的 `messenger.pins.<伺服器>.<帳號>`） - **端對端加密**（`messenger-crypto.js`，演算法跟網頁版相同才能互通）：每台裝置一組 ECDH P-256 金鑰（私鑰 non-extractable，存在這個頁面 專屬的 IndexedDB，按「伺服器 + 帳號」分開，登出不刪）、每個對話一把 AES-256-GCM 金鑰（`key_version`）、wrap = ECDH 推導的 AES-GCM、 `wrapped_key = base64(iv).base64(密文)`。帳號的第一台裝置直接 active，**之後的（包括這台電腦）是 pending，要由已核准的裝置按核准**： pending 時讀得到明文訊息、讀不到加密訊息（顯示「🔒 這台裝置還沒核准」），而且**不能在加密的聊天室傳訊息**（不會偷偷改傳明文，網頁版小視窗會）。 「設定 → 裝置與加密」可以看帳號底下所有裝置、核准（重新包裝每個對話的每個版本的金鑰給新裝置）、拒絕、撤銷、重新申請。 對話還沒有金鑰（加密上線前的舊對話）時，第一次傳訊息現場產生並 `POST /keys` 補發；對方沒有任何加密裝置就維持明文。 邀請成員時依文件產生新版本金鑰（+1）、包給所有現有成員和新成員的每台裝置 - **即時更新**（`messenger-rt.js`，Reverb / Pusher 協定，不用 pusher-js）：`GET /broadcast-config` → 連 `wss://host:port/app/key` → 訂閱 `private-App.Models.User.{id}`（所有新訊息）和目前聊天室的 `presence-conversation.{id}`（已讀、編輯、收回）；事件 `message.sent` / `message.updated` / `conversation.read` / `call.ringing`（來電只跳提示，內建聊天不能通話）。斷線 1 → 30 秒重連、 重連後補抓漏掉的；即時連線一直連不上時 15 秒更新一次（平常兩分鐘一次當保險）。**沒有「輸入中」提示**（文件沒有這個事件） - **頻道授權要請瀏覽器本體代打**：`POST /broadcasting/auth` 在網站根目錄、不在 `/api` 底下，伺服器沒有替它送 CORS 標頭（預檢回 200 但沒有 `access-control-*`，實測過），頁面直接打會被擋。所以先試直接 `fetch`（哪天伺服器開了 CORS 就會通），失敗就改 `messenger_auth.rs` 的 `channel-auth`：用 **curl**（`.deb` 已經依賴 curl）在背景執行緒打，頁面輪詢結果；網址只准自家伺服器的 `/broadcasting/auth`， token 等欄位只准簡單字元、從 stdin 給 curl 的設定檔（不會出現在程序列表）。這個請求不走瀏覽器的代理 / 連線出口設定 - **貼圖**（API 文件第 7 節；`messenger-live.js` 的 `api.stickers` / `sendSticker`、`messenger.js` 的貼圖面板與商店）：輸入框旁的貼圖鈕開面板（`GET /messaging/sticker-packs` 已下載的貼圖包，上面一排貼圖包、左邊 ＋ 是商店），**點一張就直接送出**（`POST …/messages {sticker_id}`，JSON；帶著回覆的話一起送 `reply_to_message_id`）； 貼圖畫成沒有泡泡的大圖（128 px）、可以回覆、轉傳（用 `sticker_id` 重送）、傳送失敗可以重送。貼圖商店（`GET …/sticker-packs/store?category=&sort=popular|new`）： 熱門 / 最新、分類（商店的資料有 `category` 才顯示）、「下載」（`POST …/{id}/download`，冪等）；沒下載的貼圖包的貼圖傳送會被伺服器 403，畫面說「還沒有下載」。 商店的回應格式文件沒寫細（`cover_url`、`downloaded`、`category`、`sticker_count` 這些欄位名稱是照常見寫法猜的，用寬鬆解析）。示範資料有 4 個貼圖包可以玩 - 圖片、檔案的網址：公開的直接 `` 載入；要帶 token 才讀得到的（`/api/…`）載入失敗後改用 `Authorization` 抓成 blob（只對伺服器自己的網址帶 token）。 下載：先用 token 抓 blob 存檔，抓不到（伺服器沒開 CORS）就請瀏覽器本體下載（`messenger_auth.rs` 的 `download`，只准 https） - **沒做**：輸入中、通話、編輯訊息、表情回應、跨單位聊天（文件沒有說明格式，這個頁籤顯示「還沒接上」）、推播。 正式站目前沒有照片 / 檔案列表和修改個人資料的 API（`POST /auth/me` 回 405），畫面標示「這個伺服器還沒有」；伺服器只能改姓名和大頭貼， 暱稱 / 狀態 / 電話 / Email 畫面上是灰的 - **驗證範圍**：全部都只對「照 API 文件寫的假伺服器」測過（含用 Node WebCrypto 扮演對方和另一台裝置，驗證加解密、金鑰包裝互通）， **沒有對真的伺服器、真的帳號測過**（登入真伺服器要使用者自己操作）；回應格式文件沒寫死的地方用寬鬆解析，實際有出入時看頁面的 console - 登入前先選伺服器：正式站（`portal.steps.tw/api`）/ 測試站（`vpnadmin.steps.tw/api`），旁邊的燈是真的打 `/api/ping` 量出來的 （`/ping` 一分鐘只能 10 次：30 秒內量過的不重量、429 當成「通的」）；Google 登入或 Email + 密碼；只存 token （`localStorage` 的 `messenger.token.<伺服器>`，內建頁面專用的網域，一般網站讀不到）、不存密碼；頁面重新打開時用存的 token 問 `/auth/me`，有效就直接進去，401 就回登入畫面；「網頁版已登入就直接帶入」那一列已經有畫面，偵測本身（`detectWebLogin`）還沒接。 請求直接從頁面用 `fetch` 打（`/api` 底下的 CORS 開放 `authorization` 標頭，實測 preflight 通過） 登入頁最下面「先看看畫面（示範資料）」會多出第三個「示範資料」伺服器，不連線、任何帳密都能進 - 登入後三欄：功能列（個人資料、聊天〔未讀總數〕、聯絡人、跨單位、設定、登出）、清單（搜尋、全部 / 未讀 / 群組、置頂、靜音、 未讀數、輸入中、右鍵選單）、對話（日期分隔、未讀分隔線、群組顯示名字、已讀 / 已讀 N、輸入中的三個點、回覆引用、@提及、 連結、照片九宮格與大圖檢視、影片、檔案卡片與上傳進度、收回、轉傳、傳送中 / 失敗重送、訊息搜尋 ⌘F、表情面板、貼上 / 拖曳 / 選檔案 附件、輸入法組字中不會誤送出）；右邊可展開聊天室資訊（成員、照片、檔案、連結、靜音、置頂、離開）；新增聊天 / 建立群組； 聯絡人（依部門）；跨單位聯絡人；設定（個人資料、通知、聊天、外觀〔淺 / 深 / 跟隨系統、文字大小〕、伺服器與帳號、關於）； 窄視窗清單與對話二選一。只在測試站才有的 API（跨單位聯絡人、照片與檔案列表、修改個人資料）在正式站畫面上標示「這個伺服器還沒有」 - 資料層是 `Api`（`messenger-data.js` 最上面有資料格式的說明）：`DemoApi` 能玩所有畫面（收訊息、已讀、輸入中、傳檔、輸入 `/fail` 看傳送失敗）；`LiveApi`（`messenger-data.js` 管連線和登入、`messenger-live.js` 管訊息）接上的見上面，沒做的丟 `NotConnected`。測試用：`localStorage['messenger.apiOverride']`（JSON，例如 `{"test":"http://127.0.0.1:9777/api"}`）可以把伺服器位址換成假伺服器——只能用 localStorage， **不能**改成讀網址參數（任何網頁都能把分頁導到 `vpndoc://app/messenger.html?…`，那樣就能把登入導去別的伺服器騙密碼）預覽用網址：`messenger.html?demo=1&view=settings&tab=server` - 測試：用 CDP 逐一操作畫面（登入、清單、開對話、資訊欄、搜尋、傳送 / 失敗 / 重送 / 回覆 / 附件 / 表情、大圖、收回、輸入中、新增群組、 聯絡人、跨單位、設定各頁、深色、窄視窗、登出）77 項；另外用假伺服器（照文件的通用規則：Bearer、422 的 `errors`、401）測真的 API 流程 （Email 登入、錯誤訊息、token 存取、重新開頁面自動登入、過期、登出，以及 Google 登入：302 / JS 導向 deep link、四種失敗、交換碼只能用一次、 取消、使用者關掉登入分頁、別的分頁送來的 deep link 被丟掉、沒有在等時的 deep link）46 項；訊息 API 另外用假伺服器（含 WebSocket 的 Pusher 協定、 Node WebCrypto 的「對方」和「我的另一台裝置」）測 121 項（含貼圖：面板、商店、下載、傳送、403、失敗重送、收到對方貼圖、轉傳）：列表 / 預覽 / 未讀、裝置註冊與 pending 的限制、核准後解密、加密送出（對方裝置解得開）、 回覆、即時新訊息 / 已讀 / 收回 / 編輯、附件（含超過上限）、需要登入的圖片、相簿、建立聊天室（有無加密裝置）、邀請 / 移出成員、靜音 / 置頂 / 離開、 個人資料、裝置頁核准（另一台裝置解得開舊訊息）、撤銷、斷線重連補抓、伺服器刪掉裝置後重新註冊、即時連線連不上時的定時更新；視窗沒有焦點時新訊息照樣畫出來、但留著未讀 - 右下角的 Gemini 對話窗（介面上的名稱是「**AI小幫手**」：左側按鈕、⋮ 選單、對話窗標題列、右鍵選單的「用 AI小幫手解釋 / 翻譯 / 摘要」、提示訊息都這樣叫；程式碼、註解、這份說明裡講的是它背後的服務 Gemini）（`src/shared/ai_panel.rs` + `resources/chrome/aipanel.*`）：每個視窗 右下角常駐一顆圓形按鈕，點了在它上面跳出對話窗（浮在網頁上、不擠壓網頁），再點一次收起來； 左上角可以拖曳調大小（預設 360×460，最大不會超出網頁區）。裡面直接是 Gemini 網頁版，用使用者 在瀏覽器登入的 Google 帳號——公司 Google Workspace 的 Gemini 直接能用，不需要 API 金鑰。 - 標題列：問這一頁（把目前分頁的文字連同標題、網址放進輸入框，使用者看過再自己送出）、 套用到文件（把 Gemini 最新一則回答放進目前「辦公」文件的游標位置，有選取就取代；回答先 清理成段落、標題、粗斜體、清單、表格、程式碼、http(s) 連結、**內嵌的圖片**，script、事件屬性、按鈕、遠端網址的圖片、SVG 全部拿掉；Ctrl+Z 可以復原。**回答裡的圖片會一起帶進文件**：Gemini 頁面裡的腳本（`LAST_ANSWER_SCRIPT`，非同步，`Runtime.evaluate` 要 `awaitPromise`） 把每張圖讀成 data URL——圖片網址常常是 `blob:` 或要在 Gemini 頁面才讀得到，貼進文件就不能用了；順序：已經是 data: → `fetch`（先不帶、再帶 cookie）→ 已載入的圖畫到 canvas；最長邊超過 1600 px 或 1.5 MB 的縮小；小於 48 px 的（網站小圖示、頭像）和「來源」清單裡的不算內容；最多 30 張、總共 24 MB； 讀不到的（跨網域又沒有 CORS）丟掉，提示會說「有 N 張圖片讀不到」。文件編輯器只收 `data:image/png|jpeg|gif|webp|bmp;base64`； 「存進辦公」沒有檔案連結時存成新文件的路徑（辦公的 HTML 匯入）一樣會帶圖片。只有圖片、沒有文字的回答也能貼）。**你上傳給 AI小幫手的圖片也會一併放進文件** （在你那一則提問裡、不在回答裡，所以要另外讀：同一支腳本往前看最近 3 則提問〔`user-query`〕，找到有圖片的那一則為止，圖片依 `user-query` 和 `model-response` 在頁面上的順序判斷；Google 圖片網址尾巴的 `=s200` 之類縮圖大小會先改成 `=s1600` 要大一點的；同一個網址只放一次；一張一個段落、**接在回答後面**， 檔名當替代文字；設定頁「AI小幫手」可以關，`ai_skip_uploads`）。提問裡有圖片但一張都沒帶進來時，把那些 `` 的形狀（網址類型、寬度、class、父元素，不含網址） 記到 `gdrive.log`，才知道 Gemini 的上傳預覽長什麼樣。圖片大小未知（還沒載入 / 載入失敗）時看畫面上佔的位置，兩邊都小於 48 px 才算小圖示—— 不然讀不到的圖片會被當成小圖示靜靜丟掉）、新對話、在分頁中開啟、關閉 - **Markdown（.md）與數學式**（`resources/docs/markdown.js`，純 JS、瀏覽器和 Node 都能跑，單元測試用 Node 直接跑）： - AI 產生的 .md 在辦公首頁顯示成「Markdown」，點開（或「存進辦公」下載到 .md）就用文書開、**排好版**：標題、粗斜體、刪除線、清單（巢狀、待辦）、表格（對齊）、引用、程式碼、連結；原始 HTML（`