前言¶

在 DSH 裏做產品演示或讓智能體操作網頁時，常見做法是臨時起一個無頭瀏覽器，或手工錄屏。前者很難固定分辨率、幀率和可審計的證據文件；後者窗口搶焦點，演示腳本也難以版本化管理。Malo Browser 把 Electron + Chromium 拆成觀衆側的 Stage、固定規格的 Recorder，以及場景腳本、Director 控制台和僅綁定 loopback 的控制 API；同一套代碼還是 malo-browser 智能體運行時，用後臺 daemon 分配端口租約，讓多個 agent 並行驅動隔離會話。下面介紹 Lumos-789 維護的 DSH 插件 Lumos-789/malo-browser 是什麼、能做什麼，以及如何在本機啓用與試跑。

這是什麼¶

Malo Browser（中文技能裏也稱馬嘍瀏覽器）是一個面向腳本化演示的瀏覽器原型（當前 0.1.x），維護者爲 Lumos-789。它不 fork 瀏覽器引擎，而是用場景 YAML 描述演示流程，支持隱藏錄製、物理 CDP 輸入、overlay、1080p30 輸出、證據 JSON 以及 macOS 上的最小 .app 包。倉庫同時充當 DSH 插件載體：package.json 聲明 dsh.bundle（patch 指向 cordis.patch.yml），index.js 通過 bundledSkillDir 掛載 skills/malo-browser/，安裝與排障說明在 bundled skill SKILL.md 中，不重複實現產品邏輯。

社區目錄頁：https://www.skillhub.cn/plugins/Lumos-789/malo-browser（SkillHub 爲獨立社區站點，與 DeepSeek / 幻方無官方從屬關係）。源碼與文檔：https://github.com/Lumos-789/malo-browser。插件當前版本與倉庫一致爲 0.1.3，許可證 MIT。

核心功能¶

演示與錄製¶

• Stage / Recorder 分離：演示給觀衆看的內容與固定規格採集分開配置；默認 hidden 錄製不顯示窗口、不搶焦點，macOS 上使用 accessory 激活策略且不佔用 Dock 圖標。
• 場景腳本：場景爲 fixtures/scenes/<name>/scene.yaml，通過 demo://scene/... 協議加載；內置場景包括 report-review（7 步 wait/highlight/click/fill/assert 等）、多場景切換 multi-a → multi-b、賬號登錄路徑 login-demo。字段契約見 schemas/scene.schema.json。
• Director 與控制 API：npm run start 啓動 Director 控制台與 Stage；npm run start:control 額外在 http://127.0.0.1:7317 提供 loopback 控制 API，啓動時生成隨機 token 並寫入 <out>/control.json（權限 0600），路由說明見倉庫 docs/control-api.md。
• 錄製與證據：--mode=record 產出 mp4、*.evidence.json、overlay 校驗幀等；自檢要求包括 1920×1080、30fps、時長誤差 ±0.5s、黑幀比例低於 50% 等（--plain 跳過 overlay 相關檢查）。

窗口與焦點模式¶

README Phase 0 實測表格概括了 hidden（默認）、inactive、offscreen、ghost、focused 等行爲。無頭或 hidden 交互依賴 focus emulation（默認開啓）；若 --focus-emulation=false，CDP 物理點擊會被丟棄。

malo-browser 智能體運行時¶

npm run daemon 啓動 broker：默認 127.0.0.1:7410，租約端口池 7411–7499，數據目錄 ~/.malo-browser，成功啓動後寫入 broker.json（0600，含 endpoint、token、pid）。每個 agent 獲得穩定端口，單端口可承載多個隔離 session；默認無可見窗口、不搶焦點。Session 需 lease token 與 session token 同時使用；可選 profile 持久化 cookie 與 storage。Agent 側可通過 HTTP 工具接口做 snapshot、extract、click/fill、assert、run_steps 等（詳見 bundled skill 與 docs/malo-browser.md）。

安裝與啓用¶

DSH 側要求（來自 package.json）：

• engines.dsh：>=0.2.1-rc.2 <0.3.0
• 可選 peer：@deepseek-ai/dsh-skill-filesystem（optional，不影響 Electron 應用自身的 npm install）

在 Harness 中安裝插件時，使用社區目錄標識 Lumos-789/malo-browser。SkillHub 目錄頁「發送給 DeepSeek Harness 安裝」的說明爲：請安裝 DSH 插件 Lumos-789/malo-browser，並按頁面引導讓 Harness 讀取 bundled skill 完成後續步驟。DSH 理念是「一切皆插件」；具體安裝交互以你使用的 Harness 版本爲準，不要憑插件名自行拼接未在資料中出現的 CLI。

插件安裝後，載體與 GitHub 倉庫爲同一份源碼（README 明確無第二份拷貝）。要在本機跑 Electron 應用，還需滿足運行依賴並按 skill 構建：

運行依賴

• Node.js：^22.12.0 || ^24.0.0 || >=26.0.0（不含 23、25 線；與 engines.node 不一致時 install 階段會報 EBADENGINE）
• ffmpeg、ffprobe 在 PATH 上（缺失時進程以 exit code 3 退出）
• macOS：窗口模式與錄製在 macOS 上驗證；hidden 模式依賴 accessory 策略
• Python 3：僅用於 fixture 靜態頁 python3 -m http.server
• git（倉庫開發與 skill 文檔中列爲前置）

在插件/項目根目錄構建

在 Harness 展開或同步的插件目錄內執行（與 README「Plugin packaging」及 bundled skill 一致）：

npm install
npm run build

建議門禁：npm run typecheck && npm test 均通過後再做錄製或 daemon 試驗。

若你使用 ZCode 生態而非 DSH，README 給出的 marketplace 安裝方式爲（需已註冊 dev-oss-projects）：

zcode plugins install malo-browser@dev-oss-projects -s user

典型用法¶

先做構建，再按場景選擇命令。下列示例均來自 README / bundled skill，路徑相對於倉庫根目錄。

1. 啓動 fixture 靜態服務

另開終端，提供默認 demo 頁面：

python3 -m http.server 4788 --bind 127.0.0.1 --directory out/fixture

2. 隱藏錄製 10 秒

無窗口、不搶焦點，輸出到 evidence/：

npx electron . --mode=record --seconds=10 --out=evidence --label=hidden

3. Director + 控制 API

npm run start:control

token 從輸出目錄下的 control.json 讀取，請求需帶 Authorization: Bearer <token> 或 x-demo-token。

4. 跑完整內置場景

npx electron . --mode=app --autorun=report-review --scenes=fixtures/scenes

5. 啓動 malo-browser daemon 並自檢

npm run daemon

另一終端：

curl -s http://127.0.0.1:7410/health
cat ~/.malo-browser/broker.json

多 agent 路徑可用 README 中的 npm run smoke:malo -- <broker.json> <fixture-url> 做聯調。

常用 flag 包括 --url、--width、--height、--window-mode、--control-api=true、--headless=true 等；拼寫錯誤會快速失敗，npx electron . --help 可查看完整列表。

適用場景與注意¶

適合誰

• 需要把 Web 演示腳本化、固定 1080p30 證據鏈路的開發者或技術傳播者。
• 在 DSH 或其它 agent 框架裏，需要後臺、低打擾、可隔離 session 的 Chromium 執行層，並通過 loopback API 驅動頁面工具的團隊。

權限與安全

• 插件與 Malo Browser 進程以當前 DSH / 終端用戶權限運行；安裝前請閱讀 GitHub 源碼 與 MIT 許可證，確認 side effect 可接受。README 與 skill 列出的 side effect 包括：在 --out 下寫入 mp4、證據 JSON、失敗截圖；綁定 loopback 端口（控制 API 默認 7317、broker 7410、租約池 7411–7499）；daemon 持久化 ~/.malo-browser；賬號文件須位於 git 工作樹外且 mode 0600。
• 控制 API 與 broker 僅監聽 loopback，不提供遠程多用戶服務；不適合當作對外暴露的瀏覽器 SaaS。

平臺與成熟度

• README 寫明 僅在 macOS 上驗證；其它平臺未測試。
• 0.1.x 爲 working prototype；API 行爲可能變化（例如 skill 提到 assert 失敗返回 HTTP 200 且 result.ok: false，而非 5xx）。

常見故障

• exit 3：安裝 ffmpeg（如 macOS 上 brew install ffmpeg）。
• 錄製 exit 0 但無文件：檢查環境變量 ELECTRON_RUN_AS_NODE，必要時 env -u ELECTRON_RUN_AS_NODE npx electron ...。
• Control API 401：使用 control.json 中的 token。
• Node 版本不在 engines 範圍內：換用 22.12+、24.x 或 26+。

結尾¶

Malo Browser DSH 插件把「腳本化 Stage 演示 + 固定規格錄製」和「多 agent 隔離 Web 會話」收進同一 Electron 載體；通過 bundled skill 銜接 Harness 與本機構建、運行、排障。若要在社區中查看簡介並交給 Harness 安裝，可打開 SkillHub 目錄頁；細節與變更以 GitHub 倉庫 README 爲準。