前言¶
在 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 为准。
