diff --git a/assets/malo-browser/icon.png b/assets/malo-browser/icon.png
new file mode 100644
index 00000000..8f1e2f4c
Binary files /dev/null and b/assets/malo-browser/icon.png differ
diff --git a/external_plugins/malo-browser/.codex-plugin/plugin.json b/external_plugins/malo-browser/.codex-plugin/plugin.json
new file mode 100644
index 00000000..38e37af9
--- /dev/null
+++ b/external_plugins/malo-browser/.codex-plugin/plugin.json
@@ -0,0 +1,33 @@
+{
+  "name": "malo-browser",
+  "version": "0.1.11",
+  "description": "Scripted browser demo tool and agent browser runtime: a visible Electron stage for live web demos, hidden 1080p30 recording with evidence files, a director console, a loopback control API, and a background daemon that hands out port leases with isolated browser sessions.",
+  "author": {
+    "name": "Lumos-789",
+    "url": "https://github.com/Lumos-789"
+  },
+  "homepage": "https://github.com/Lumos-789/malo-browser",
+  "repository": "https://github.com/Lumos-789/malo-browser",
+  "license": "MIT",
+  "keywords": [
+    "browser",
+    "electron",
+    "demo",
+    "recording",
+    "agent",
+    "daemon",
+    "codex"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Malo Browser",
+    "shortDescription": "Open, drive and record pages in a scripted browser",
+    "longDescription": "Malo Browser runs a scripted Electron stage for live web demos, hidden 1920x1080@30fps recording with evidence files, a React director console and a loopback control API. Its daemon mode issues per-agent port leases so several agents can drive isolated browser sessions at the same time.",
+    "developerName": "Lumos-789",
+    "category": "Developer Tools",
+    "capabilities": [
+      "Read",
+      "Run commands"
+    ]
+  }
+}
diff --git a/external_plugins/malo-browser/.zcode-plugin/plugin.json b/external_plugins/malo-browser/.zcode-plugin/plugin.json
new file mode 100644
index 00000000..6a5d2349
--- /dev/null
+++ b/external_plugins/malo-browser/.zcode-plugin/plugin.json
@@ -0,0 +1,24 @@
+{
+  "name": "malo-browser",
+  "version": "0.1.11",
+  "description": "Scripted browser demo tool and agent browser runtime: a visible Electron stage for live web demos, hidden 1080p30 recording with evidence files, a director console and a loopback control API, plus a daemon handing out port leases with isolated, profile-backed browser sessions exposing 25 session tools (including network capture).",
+  "description_i18n": {
+    "en": "Scripted browser demo tool and agent browser runtime: a visible Electron stage for live web demos, hidden 1080p30 recording with evidence files, a director console and a loopback control API, plus a daemon handing out port leases with isolated, profile-backed browser sessions exposing 25 session tools (including network capture).",
+    "zh-CN": "脚本化浏览器演示工具兼 agent 浏览器运行时：可见的 Electron 演示舞台、无头 1080p30 录制与证据文件、导演控制台与本地控制 API；守护进程按端口发放租约，提供隔离且可复用登录态的 session，共 25 个 session 工具（含网络抓包）。"
+  },
+  "author": {
+    "name": "Lumos-789",
+    "url": "https://github.com/Lumos-789"
+  },
+  "homepage": "https://github.com/Lumos-789/malo-browser",
+  "repository": "https://github.com/Lumos-789/malo-browser",
+  "license": "MIT",
+  "keywords": [
+    "demo",
+    "recording",
+    "electron",
+    "browser",
+    "screencast"
+  ],
+  "skills": "skills"
+}
diff --git a/external_plugins/malo-browser/CHANGELOG.md b/external_plugins/malo-browser/CHANGELOG.md
new file mode 100644
index 00000000..e1277466
--- /dev/null
+++ b/external_plugins/malo-browser/CHANGELOG.md
@@ -0,0 +1,266 @@
+# Changelog
+
+## 0.1.11
+
+- **文档与实现对齐（无行为变化）。**`SKILL.md` 不再把 login 的自动隐藏写到 `watch`
+  头上——`watch` 窗口保持可见直到显式再调 `watch`（`show:false`）收起，`login`
+  成功才自动隐藏（`keep_visible: true` 例外），与两版 README 一致；`docs/malo-browser.md`
+  登录交接规则里的同款失实一并改正，并补上 0.1.8 起存在的
+  `POST /v1/profiles/:name/import`（说明 + curl 示例）；`README_CN.md` 补译英文版
+  0.1.8 起就有的「Profile 登录态导入」整章（参数、返回字段、错误码、隐私边界）；
+  `login-import.ts` 去掉两个无外部消费者的 `export` 修饰符。
+
+## 0.1.10
+
+- **`POST /v1/profiles/:name/import` 的 `domains` 改为逐项校验、fail-loud。**此前
+  `[""]` / `[123]` 这类非法条目会被静默过滤成空数组，而空数组在域过滤层等于「匹配
+  所有域」——即调用方以为只迁指定域的 cookie，实际全量导入了所有域（隐私边界被击穿）。
+  现在任一非法条目直接 400 `E_BAD_REQUEST` 并点名非法项；`domains` 传非数组或空数组
+  仍报 400。同时把 `.zcode-plugin` / `.codex-plugin` manifest 与 `package-lock.json`
+  根版本从滞留的 0.1.7 同步到当前版本，`SKILL.md` 动作工具枚举补上 0.1.7 新增的
+  `upload_file`。
+
+## 0.1.9
+
+- **Human-visible windows now get a Dock icon while they are on screen.** The daemon
+  keeps running as an accessory app exactly as before (no Dock icon, no focus stealing,
+  no programmatic activation), but the moment a session window is shown for a human
+  (`watch` / login handoff) the macOS Dock icon appears, so a window buried behind
+  other apps can be raised again by clicking it; the icon disappears once no visible
+  window is left. Offscreen and ghost windows never surface an icon and recordings
+  stay fully headless. The only focus change is the one the user makes by clicking
+  the Dock icon.
+
+## 0.1.8
+
+- **New profile login import: `POST /v1/profiles/:name/import`.** Seeds a persistent
+  profile with cookies read live from another Chromium's DevTools endpoint
+  (`cdp_url`, loopback `http://` only), so a logged-in daily Chrome hands its login
+  state to a malo profile without re-typing credentials. The daemon connects to the
+  source browser-level WebSocket, calls `Storage.getCookies`, and writes each cookie
+  through the Electron cookie store of the target partition — this crosses the
+  Chrome/Electron keychain encryption boundary that makes raw profile-file copies
+  unreadable. Optional `domains` allowlist filters which cookies move (equal,
+  subdomain, or parent matches); `session_cookie_ttl_days` (default 180) re-stamps
+  session cookies as persistent so imported logins survive daemon restarts (`0` keeps
+  them session-only). The response reports
+  `cookies_total / cookies_matched / cookies_written / cookies_failed` with up to 20
+  per-cookie errors (e.g. `__Host-` prefix rejections). Import merges, never clears;
+  only cookies move (localStorage / IndexedDB stay in the source). Source unreachable
+  → 502 `E_IMPORT_SOURCE_UNREACHABLE`; zero matched cookies → 400 `E_IMPORT_EMPTY`.
+
+## 0.1.7
+
+- **New `upload_file` tool.** Sets files on an `input[type=file]` through CDP
+  `DOM.setFileInputFiles`, so the input may stay visually hidden; a site whose upload
+  button opens a native picker still needs that button clicked first. `selector` must
+  match an input and `files` are absolute paths on the host running the browser. A
+  missing selector fails as `E_SELECTOR_NOT_FOUND` (400 on the lease endpoint) like the
+  other action tools, and the tool is allowed inside `run_steps`. The manifest now
+  declares 25 session tools.
+
+## 0.1.6
+
+Full review pass; every item below was reproduced before fixing.
+
+### Isolation and security
+
+- **Shared-profile sessions no longer cross-wire downloads or network state.** Electron
+  keeps one `webRequest` listener and one permission handler per session, and
+  `will-download` fires for every webContents in the partition. Two sessions on the same
+  `profile` used to fight over `setSavePath` (a download started in A could land in B's
+  `downloads/`) and the newer session silently disabled the older one's failure
+  tracking. Handlers are now installed once per Electron session and dispatched by
+  webContents id (`src/main/malo/partition-hooks.ts`); a download with no owner is
+  cancelled.
+- **The demo stage now blocks redirects, not just navigations.** Server-side 3xx emits
+  `will-redirect`, which was never hooked, so an allowlisted origin could 302 to an
+  arbitrary one and the remaining steps ran there. Both events share one gate now.
+- **`goto` obeys the scene allowlist.** `webContents.loadURL` does not emit
+  `will-navigate`, so tool-initiated navigation was unchecked; the runner now asks the
+  host policy first (`assertNavigationAllowed`).
+- **`${env:NAME}` is limited to `SCENE_*`.** A third-party scene could interpolate any
+  `process.env` value (cloud keys, tokens) into a URL or form field, and the allowlist
+  was declared by that same scene. All three interpolation implementations share the
+  same rule now (the third one, `interpolateScene`, had no guard at all).
+- **`demo://` validates the scene id.** The protocol handler used the URL segment as the
+  containment root, so `demo://scene/..%2Fprivate%2Fcredential.json` served files one
+  level above the scenes root. It now applies `SCENE_ID_PATTERN`, and a 404 no longer
+  echoes the resolved filesystem path to the page.
+- **`--data-dir=~/.malo-browser` actually expands `~`** instead of creating a literal `~`
+  directory (`--out` and `--scenes` too).
+- Data dir and session dirs are created 0700; run reports, failure screenshots and
+  encoded takes are 0600 (the legacy evidence writer was 0644).
+- `GET /health` on a lease endpoint no longer enumerates `lease_id` / `agent_id`
+  without a token.
+
+### Recording and evidence
+
+- **A rejected take no longer claims "no video was written"** while a playable mp4 sits
+  on disk: the failed-evidence warning names the file and says it failed self-checks.
+- Frame temp dirs (`<take>-frames`, `<take>-seq`) are cleaned even when encoding is
+  rejected, so a failed take stops leaving hundreds of JPEGs behind.
+- `ffmpeg` / `ffprobe` now run with timeouts (120s metadata probe, 250ms/frame encode,
+  20min ceiling) and are killed instead of hanging `stop()` forever. Whole-file decode
+  passes (blackdetect, ssim) scale their timeout with the video length, so a long take
+  is not failed by a flat cap; a buffer overflow reports itself instead of posing as a
+  timeout.
+- `capture.timeline_frames` reports the encoder's slot count instead of duplicating
+  `video.frames`.
+- The `steps_completed` / `steps_within_take` checks only consider steps executed inside
+  the take; borrowing the whole scene's step list could pass a take that ran nothing.
+- A failed evidence write no longer leaves the recorder stuck in "recording".
+
+### Demo pipeline
+
+- **Director shortcuts can no longer kill the app.** Every shortcut rejection used to
+  reach the process-level `unhandledRejection` handler, which calls `app.exit()`; a
+  routine "no scene loaded" or "nothing to step back to" ended the session. Shortcuts now
+  surface the error in the UI.
+- **`goto` / `login` no longer break every later visual step.** Navigation drops the
+  injected overlay, and only load/switch re-injected it, so `goto` → `click` failed with
+  `TypeError: … reading 'click'`. The overlay is now installed on demand (and re-injected
+  after navigation as a best-effort step, so a landing page that redirects again cannot
+  fail the take); `reset` / `stop` / `prev` recover too.
+- `recorder.start` refuses while a scene is still loading instead of recording a
+  half-initialised page.
+- `runner.load()` is awaited, removing the load/start race that surfaced as
+  "场景尚未就绪" on slow or redirected scenes.
+- A failed `scene.load` no longer leaks an untracked `BaseWindow`.
+- The documented-but-rejected scene fields now parse: `fill.target_text`,
+  `press.modifiers`, and x/y coordinates for `click` / `fill` / `highlight` /
+  `spotlight` / `mask` (and `target_text` survives normalization instead of being
+  dropped).
+- `scroll.behavior: smooth` is implemented; `annotate.position` now places the label
+  where it says.
+- Director step indexing uses one convention (last executed step), so a paused run no
+  longer shows the completed step as both "current" and "next"; `app.error` no longer
+  inherits a stale step index and screenshot.
+- Blackout state is cleared on scene load and on a same-URL scene switch; leaving
+  fullscreen re-applies the active scene's viewport instead of the pre-fullscreen one.
+
+### Tools
+
+- Action errors no longer carry the code twice
+  (`E_SELECTOR_NOT_FOUND: E_SELECTOR_NOT_FOUND: …`).
+- A selector with invalid syntax is `E_BAD_REQUEST` (400) on every tool instead of a
+  misleading `E_STEP_TIMEOUT` (504).
+- `extract` with an invalid selector is a 4xx instead of HTTP 200 with `count: 0` and an
+  undeclared `error` field.
+- `assert value` on a password input is rejected; comparing the redacted literal made
+  `value: "[redacted]"` pass regardless of the real value.
+- `press` validates the key name instead of reporting success for `Enterr`.
+- `run_steps` rejects `login` (it can open a handoff window and type credentials) as the
+  docs always claimed, and the docs now also list `close`.
+- `network_capture` recovers after a failed `Network.disable` instead of being stuck.
+- `ProfileStore` writes recover after one failed write instead of failing forever.
+
+### Docs and packaging
+
+- README/README_CN corrected where they contradicted the code: download policy (the agent
+  runtime accepts downloads into the session dir, it does not need a scene policy),
+  password redaction (`snapshot` returns `""` + `sensitive`, `[redacted]` is the
+  interactive text), failed-step screenshots (only `assert`), `--data-dir=~`, and the
+  scene-variable/`SCENE_` rule.
+- `docs/malo-browser.md`: mutually exclusive login success heuristic, partition dir
+  without the `persist:` prefix, updated `run_steps` blocklist, new permission/mode notes.
+- The published field contract `schemas/scene.schema.json` accepts the same step fields
+  as the runtime (`target_text`, `modifiers`, coordinate targets), and a unit test now
+  fails when the two schemas drift apart — that drift is how the fields became
+  documented-but-rejected in the first place.
+- `SKILL.md`: `EADDRINUSE` advice distinguishes control / broker / lease, invalid
+  selector is `E_BAD_REQUEST`, added `E_NAV_BLOCKED` and the `SCENE_` rule.
+- `package.json` `files` now ships `docs/` and `schemas/`, which the bundled skill links
+  to (the DSH bundle is still installed from the prebuilt Release tarball because `out/`
+  is gitignored); `scripts/pack-dsh-bundle.sh` stages the same two directories.
+- `package-lock.json` root version caught up with `package.json`.
+
+Tests: 232 → 254.
+
+## 0.1.5
+
+- `scripts/pack-dsh-bundle.sh` builds and packs the prebuilt DSH bundle attached
+  to the GitHub release. The DSH plugin is installed from that asset, because
+  `out/` is gitignored and a source install would leave `index.js` pointing at a
+  compiled entry that does not exist yet.
+
+- Added the `network_capture` and `responses` session tools: subscribe to URL prefixes,
+  navigate/interact, then poll the captured XHR/fetch response bodies. Capture reuses the
+  page driver's single CDP attach (no second debugger, no focus change); the Network
+  domain is enabled lazily with 64 MiB/8 MiB response buffers and disabled when the
+  subscription clears.
+- Records keep every response's metadata in one 500-entry window, while bodies are kept
+  only for subscribed hits up to 200 records and a 16 MiB budget. Each body is capped at
+  1 MiB (`body_truncated`); base64 payloads report `body_error: "binary"` instead of a
+  lossy UTF-8 decode, and queued bodies report `"pending"`. Query envelopes use
+  `has_more`, not `truncated`, so they cannot be confused with `body_truncated`.
+- Capture state is session-private and in memory only: bodies never reach logs, evidence,
+  traces or run reports, and `MaloNetworkInfo` is unchanged. A capture subsystem failure
+  surfaces as `E_CAPTURE_UNAVAILABLE` (`ok: false`) instead of an empty list.
+
+## 0.1.4
+
+- `--mode=record` now leaves failed evidence for every pre-encode throw, including
+  opening the stage. An unreachable page writes `<out>/<label>.evidence.json` with
+  `status: "failed"`, `video: null`, the real Chromium code (`ERR_CONNECTION_REFUSED`),
+  the failing `error.step`, the steps captured so far and any partial `artifacts`; the
+  original error and exit code 2 are unchanged. Covered by
+  `tests/unit/phase0-failed-evidence.test.ts`.
+- `resolveTool` keeps resolving `ffmpeg`/`ffprobe` from `PATH` first and only then from
+  the documented Homebrew/local directories; a real miss now throws a typed
+  `DemoError` (`E_FFMPEG_MISSING`, exit 3) and the policy is unit-tested via
+  `resolveToolOnPath`.
+
+## 0.1.3
+
+- Removed `docs/phase0-report.md`, `docs/phase1.md`, `docs/phase1b.md`: internal
+  engineering reports, never linked from the README, the skill or any test.
+- Removed `scripts/baseline_chrome.py`. It rebuilt a Chrome baseline from the
+  author's private `~/recorder-pipe` virtualenv, so it could not run on another
+  machine; `scripts/compare.cjs` still compares two recordings.
+
+## 0.1.2
+
+- `README.md` is English again and `README_CN.md` is its Chinese translation with
+  the same section structure (install / run / scene scripts / recording and
+  evidence / control API / troubleshooting / side effects / limitations). Both were
+  re-checked against the current code for commands, flags, ports, paths and artifact
+  names; the plugin packaging notes moved into the shared structure.
+- An `assert` failure now uses the same contract as a failed `run_steps` batch:
+  HTTP 200 with `result.ok: false`, per-check `expected`/`actual` on
+  `result.checks` and `result.error.details.checks`, and the failure screenshot.
+  Invalid arguments stay 4xx and real server failures stay 5xx. Callers that keyed
+  on the old HTTP 500 must read `result.ok` instead — a 0.1.x contract change.
+- App mode now leaves failed evidence when a take dies before encoding: a zero-frame
+  `recordStop` (`E_RECORDER_NO_FRAMES`) and any other recorder stop failure write the
+  take's `.evidence.json` with `status: "failed"`, `video: null`, `error.code` and
+  `error.message` instead of only logging a line, matching `--mode=record`. Exit
+  codes and control-API errors are unchanged.
+
+## 0.1.1
+
+- A failed step keeps one error-code prefix: `E_SELECTOR_NOT_FOUND: 找不到元素
+  #m` instead of `E_SELECTOR_NOT_FOUND: E_SELECTOR_NOT_FOUND: ...` in stderr,
+  the run snapshot and evidence step details.
+- An autorun take that fails on a step now stops the recorder and writes
+  failed evidence with the real cause, instead of exiting 2 with no artifact.
+- Evidence no longer says `passed` for a run with a failed step: it records
+  `status: failed`, the run error and `video.partial`, and `recorder.stop` only
+  reports `E_EVIDENCE_MISMATCH` when a recording self-check fails.
+- The human-handoff toolbar no longer shrinks the page: session `width`/`height`
+  are the page viewport again (a 1280x800 session rendered 1280x756 before), and
+  screenshots match the requested size. `npm run smoke:toolbar` checks it.
+- An invalid scene lists the actual field errors in the message instead of only
+  `N error(s)`.
+- A busy broker/lease port points at `--daemon-port` / `--port-min`--`--port-max`
+  instead of telling the user to change `--control-port`.
+- Documented the handoff toolbar, `run_steps`, the session viewport rule, the
+  `overlay-before` frame and the `smoke:toolbar` / `smoke:control` scripts;
+  `package.json` now declares the published `files` list.
+
+## 0.1.0
+
+- Scene-driven Electron stage, hidden 1920x1080@30fps recording with evidence
+  files, window modes, director console and loopback control API.
+- `malo-browser` agent runtime: broker daemon, port leases, isolated sessions,
+  page tools, `assert`, `run_steps`, login handoff, persistent profiles.
diff --git a/external_plugins/malo-browser/LICENSE b/external_plugins/malo-browser/LICENSE
new file mode 100644
index 00000000..b6c14d9c
--- /dev/null
+++ b/external_plugins/malo-browser/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lumos-789
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/external_plugins/malo-browser/README.md b/external_plugins/malo-browser/README.md
new file mode 100644
index 00000000..b2ba7933
--- /dev/null
+++ b/external_plugins/malo-browser/README.md
@@ -0,0 +1,570 @@
+<p align="center"><img src="assets/malo-browser/icon.png" width="88" height="88" alt="Malo Browser icon"></p>
+
+<h1 align="center">Malo Browser</h1>
+
+A browser for scripted demos. It is built on Electron + Chromium and splits a web demo
+into a Stage (what the audience sees) and a Recorder (fixed-spec capture) without
+forking the browser engine; demo flows are written as scene scripts, with a Director
+console and a loopback control API on top.
+
+This repository is a working prototype (0.1.x): hidden recording, physical CDP input,
+an overlay, 1080p30 output, evidence files and a minimal `.app`. It is also the
+`malo-browser` agent runtime: a background daemon hands out port leases so several
+agents can drive isolated browser sessions at the same time.
+
+## Install
+
+### Requirements
+
+- Node 22.12+ on the 22 line, 24.x, or 26+ (`engines` is
+  `^22.12.0 || ^24.0.0 || >=26.0.0`; the 23 and 25 lines are excluded). The range is
+  declared in `package.json`, so a mismatch surfaces during install (yarn fails;
+  npm/pnpm print an EBADENGINE warning and fail under `engine-strict`) instead of deep
+  inside vite/vitest.
+- ffmpeg and ffprobe on `PATH` (resolved from `PATH` first, then the Homebrew/local
+  fallback directories); missing binaries exit with code 3.
+- macOS for the verified path: window modes and recording are tested there, and hidden
+  mode uses the accessory activation policy.
+- Python 3 only for the bundled fixture static server (`python3 -m http.server`).
+- git.
+
+### From source
+
+```bash
+git clone https://github.com/Lumos-789/malo-browser.git
+cd malo-browser
+npm install
+npm run build
+```
+
+`npm run build` compiles the main process with tsc and bundles the fixture and the
+director console with vite. `npm run typecheck` type-checks the main and renderer
+projects without emitting, and `npm test` runs the vitest unit suite.
+
+### Plugin packaging
+
+The repository is both the app and the plugin carrier; there is no second copy of the
+source.
+
+- ZCode plugin: `.zcode-plugin/plugin.json` (name `malo-browser`, version kept in sync
+  with the repo), skill `skills/malo-browser/SKILL.md` (install / configure /
+  troubleshoot; it does not reimplement the product), icon
+  `assets/malo-browser/icon.png` (512x512). With the `dev-oss-projects` marketplace
+  registered: `zcode plugins install malo-browser@dev-oss-projects -s user`.
+- DSH bundle: `package.json` declares `dsh.bundle` (patch -> repo-root
+  `cordis.patch.yml`) and `index.js` mounts `skills/` through `bundledSkillDir`.
+  `engines.dsh` and the optional `@deepseek-ai/*` peerDependencies are in
+  `package.json`; because the peer is optional, it does not affect `npm install` for the
+  Electron app.
+
+## Run
+
+Serve the fixture page first (the default demo target), in another terminal:
+
+```bash
+python3 -m http.server 4788 --bind 127.0.0.1 --directory out/fixture
+```
+
+Default: hidden background recording for 10 seconds.
+
+```bash
+npx electron . --mode=record --seconds=10 --out=evidence --label=hidden
+```
+
+The default recording shows no window, takes no focus and claims no Dock icon on macOS
+(`setActivationPolicy('accessory')`), so you can keep using the machine while it records.
+
+| Command | What it does |
+|---|---|
+| `npm run build` | main process (tsc), fixture and director (vite) |
+| `npm run typecheck` | type-check main + renderer projects, no emit |
+| `npm test` | vitest unit suite |
+| `npm start` | Director console + Stage; the Stage shows as `inactive` and does not steal focus |
+| `npm run start:control` | same, plus the loopback control API on `http://127.0.0.1:7317` |
+| `npx electron . --mode=record --seconds=10` | hidden recording (default) |
+| `npx electron . --mode=record --window-mode=inactive --seconds=10` | visible but unfocused recording |
+| `npx electron . --mode=record --plain --seconds=10` | no interaction, static page only (control run) |
+| `npx electron . --mode=app --autorun=report-review --scenes=fixtures/scenes` | run a whole scene headless and produce a take |
+| `npx electron . --mode=app --director-check` | invisible check of the Director and the preload bridge |
+| `npx electron . --mode=app --headless=true --control-api=true` | windowless background instance with only the control API and recording |
+| `npx electron . --mode=stage --window-mode=inactive` | visible Stage for manual browsing |
+| `npm run daemon` | malo-browser broker daemon handing out leases to agents |
+| `npm run smoke:malo -- <broker.json> <fixture-url>` | real multi-agent / multi-session path |
+| `npm run smoke:toolbar` | hidden check of the handoff toolbar (preload, Enter navigation, address sync, back, page viewport) |
+| `npm run smoke:control -- report-review` | against a running control API: load scene -> record -> verify evidence |
+| `npm run package` | package an unpacked app under `dist/` (Apple Silicon: `dist/mac-arm64/Malo Browser.app`) |
+| `./scripts/run-phase0.sh` | Phase 0 primary evidence run (hidden + inactive) |
+
+`--mode=stage` follows `--window-mode`, and its default is `hidden`; pass
+`--window-mode=inactive` (or `focused`) to actually see the Stage.
+
+Common flags: `--url`, `--width`, `--height`, `--out`, `--label`, `--keep-frames`,
+`--window-mode=hidden|inactive|offscreen|ghost|focused`, `--focus-emulation=false`,
+`--control-api=true`, `--control-port`, `--headless=true`, `--scenes`, `--autorun`,
+`--plain`. A misspelled flag fails fast; `--help` prints the full reference and
+`--version` prints the version.
+
+The app control API binds only to loopback, generates a random token at startup and
+writes it to `<out>/control.json` (0600). Routes and curl examples are in the
+[App control API](#app-control-api) section below.
+
+### Window and focus modes
+
+Measured in Phase 0:
+
+| Mode | Behaviour | Recordable | Interactive |
+|---|---|---|---|
+| `hidden` (default) | window is never shown | yes | yes with focus emulation |
+| `hidden` + `--focus-emulation=false` | window is never shown | yes | no, clicks are dropped |
+| `inactive` | window is shown without taking focus | yes | yes |
+| `offscreen` | window is shown at (-12000, -12000) | yes | yes |
+| `ghost` | window is shown with opacity 0 | yes | yes |
+| `focused` | window is shown and takes focus | yes | yes |
+
+Headless mode requires `Emulation.setFocusEmulationEnabled` (on by default), otherwise
+CDP physical clicks do not take effect.
+
+### malo-browser agent runtime
+
+`malo-browser` is the background web-execution layer for agents: one long-lived daemon
+manages port leases, every agent gets a stable port, and one port can host several
+isolated sessions. There is no visible window by default; it does not take focus, does
+not cover the screen and does not switch Spaces. Screenshots are produced only on
+explicit request or as failure evidence.
+
+```bash
+npm run daemon
+# in another terminal
+curl -s http://127.0.0.1:7410/health
+cat ~/.malo-browser/broker.json
+```
+
+Defaults: broker `127.0.0.1:7410`, lease port pool `7411-7499`, data directory
+`~/.malo-browser`. A successful start prints one JSON line and writes
+`~/.malo-browser/broker.json` (0600) with `{endpoint, token, pid}`. Only one daemon may
+use a data directory: a healthy running instance makes the new process fail loudly, and
+a stale `broker.json` left by a stopped instance is overwritten.
+
+Daemon flags: `--daemon-port=7410`, `--port-min=7411`, `--port-max=7499`,
+`--lease-ttl-seconds=300`, `--session-idle-seconds=300`, `--max-sessions=4`,
+`--data-dir=~/.malo-browser`.
+
+A new session needs both the lease token and its own session token; a session token from
+session A cannot read session B (401). `width` / `height` are the page viewport, and the
+handoff toolbar does not consume them. Sessions without a `profile` are anonymous and
+are wiped on close; sessions created with `{"profile":"work"}` share that profile's
+cookies and storage across sessions and daemon restarts. Profile names allow lowercase
+letters, digits, dot, underscore and hyphen (max 64 chars). Data lives under
+`<data-dir>/leases/<lease-id>/sessions/<session-id>/{downloads,artifacts}`, profile data
+under `<data-dir>/chromium`.
+
+`delivery-video` is only a visual-output adapter; it does not define the malo-browser
+kernel boundary.
+
+### Verification scripts
+
+- `npm run smoke:malo -- ~/.malo-browser/broker.json http://127.0.0.1:4788` runs the
+  real daemon chain (see also [docs/malo-browser.md](docs/malo-browser.md)).
+- `npm run smoke:toolbar` builds and drives the handoff toolbar in a hidden window.
+- `npm run smoke:control -- report-review` talks to an already running control API; set
+  `DEMO_CONTROL_URL` (default `http://127.0.0.1:7317`) and `DEMO_CONTROL_TOKEN` from
+  `<out>/control.json`.
+
+## Scene scripts
+
+Scenes are YAML files at `fixtures/scenes/<id>/scene.yaml`, loaded through the
+`demo://scene/<id>/...` protocol, which only serves files inside the scene directory.
+The field contract is [schemas/scene.schema.json](schemas/scene.schema.json).
+
+### Bundled scenes
+
+- `report-review`: the currently usable demo, 7 steps
+  `wait_for -> highlight -> click -> fill -> assert -> spotlight -> annotate`. The page
+  loads as `demo://scene/report-review/index.html`.
+- `multi-a -> multi-b`: verifies multi-scene switching: 1280x720 switches to 1600x900
+  through one continuous screencast, and evidence records `run.scene_ids`.
+- `login-demo`: the full account-login path (see below).
+
+Scene actions: `goto`, `login`, `wait`, `wait_for`, `wait_for_presenter`, `click`,
+`fill`, `press`, `scroll`, `highlight`, `spotlight`, `annotate`, `mask`, `blackout`,
+`assert`, `scene`, `set`, `note`, `screenshot` (19 actions).
+
+### Target resolution
+
+Targeted actions resolve in a fixed order, first match wins:
+
+| Priority | Form | Resolved to |
+|---|---|---|
+| 1 | `data_demo_id: increment` | `[data-demo-id="increment"]` |
+| 2 | `selector: ".btn-primary"` | raw CSS selector |
+| 3 | `text: 金额异常` | text match (rules below) |
+| 4 | `x: 640` + `y: 360` | viewport point (no selector, last resort) |
+
+Text matching picks the smallest **visible** element (not hidden, has size) whose text
+**contains** the target string, and marks it with a runtime attribute for later commands
+in the same step. No match, or no target at all, reports `E_SELECTOR_NOT_FOUND` (the
+message distinguishes "no element contains this text" from "the step has no resolvable
+click or visual target").
+
+Three special cases do not use `text` as the target:
+
+- `fill`: `text` is the input content; the target is `selector` / `data_demo_id` /
+  coordinates, or `target_text` names the element to click.
+- `annotate`: `text` is the annotation copy; the target must be `selector` /
+  `data_demo_id` / coordinates.
+- `wait_for`: `text` is the wait condition (wait for text to appear), not a click target.
+
+### Account login
+
+The `login` action uses a `0600` account file outside the repository; a scene stores only
+`account_id`, the password is read from `password_env` at runtime, and the action opens
+the login page, fills, submits and waits for a success condition.
+`fixtures/scenes/login-demo` verifies the whole path. The default account file is
+`~/.config/malo-browser/accounts.json`, overridable with `MALO_BROWSER_ACCOUNTS`. The file
+must live outside a git worktree, be a regular `0600` file, keep `origin` and `login_url`
+same-origin, and define `success_selector` or `success_url`; a plaintext `password` field
+is rejected. Format, security boundary, examples and failure troubleshooting:
+[docs/accounts.md](docs/accounts.md).
+
+### Scene variables
+
+`vars` holds scene-local strings; `${name}` interpolates them into action fields, and
+`${env:SCENE_NAME}` reads an environment variable from the `SCENE_` namespace only — any
+other name is rejected, so a third-party scene cannot pull cloud keys or tokens into a
+URL or form field.
+
+### Validation
+
+Scene validation reports every error at once; unknown fields, out-of-range times and
+missing targets fail before the scene loads.
+
+## Recording and evidence
+
+### Output files
+
+A `--mode=record` run writes, per take:
+
+```text
+evidence/
+  hidden.mp4
+  hidden.evidence.json      # version, viewport, DPR, frames, duration, SHA256, steps, self-checks
+  hidden.overlay-frame.png  # overlay check frame (not written with --plain)
+  hidden.overlay-before.png # same moment before the overlay (not written with --plain)
+```
+
+An app-mode take (autorun or control API) writes
+`<out>/recordings/<timestamp>_<scene>/take-01.mp4` plus `take-01.evidence.json`; a failed
+`assert` step also writes `<out>/errors/<scene>/step-<index>.png` (other failing actions
+carry the error, not a screenshot).
+
+App-mode evidence and the encoded mp4 are written with mode 0600. The document records `status`,
+`app`, `scene`, `run` (including `run.scene_ids` for multi-scene takes), `capture`,
+`video`, `steps`, `checks`, `warnings` and `error` when the take failed.
+
+### Self-checks
+
+A `--mode=record` take exits 0 only when every self-check passes: no Node in the window,
+frames arrived, duration within ±0.5s, 30fps, 1920x1080, black-frame ratio <50%, and the
+overlay really ended up in the video (skipped for `--plain`).
+
+App-mode takes check `frames_arrived`, `steps_completed` and `steps_within_take`; a
+failed step or a failed check marks the evidence `failed` and the take carries
+`video.partial`. Failed self-checks raise `E_EVIDENCE_MISMATCH` with the failing check
+ids. In the autorun path a failed step still stops the recorder first, so the take keeps
+its video and its failed evidence.
+
+### Failed takes
+
+"Failure also has evidence" holds for every entry point:
+
+- `--mode=record` writes `<out>/<label>.evidence.json` with `status: "failed"`,
+  `video: null`, `error.code`, `error.message` and the failing `error.step` whenever the
+  run throws before the video is encoded — opening the stage (for example an unreachable
+  page, reported as `ERR_CONNECTION_REFUSED`), capture, step or encoding failure.
+  `artifacts` lists any partial files that were written before the failure.
+- app mode (`--autorun`, control API, IPC) writes the take's `take-01.evidence.json`
+  with `status: "failed"`, `video: null`, `error.code` and `error.message` when the
+  recorder fails before encoding — including the zero-frame case
+  `E_RECORDER_NO_FRAMES` — and then rethrows the original error, so the exit code /
+  control-API error is unchanged.
+- A take whose recorder succeeded but whose run had a failed step keeps the video
+  (`video.partial: true`) and records the step error.
+- `--keep-frames` additionally keeps the raw frames of a failed take.
+
+### Exit codes
+
+| Exit code | Meaning |
+|---|---|
+| 0 | success: every self-check passed (an `--mode=app --autorun` success also prints one JSON line on stdout) |
+| 2 | argument error or general failure (page load failure, `E_SELECTOR_NOT_FOUND`, assertion failure, CDP attach failure, scene validation failure, port busy, evidence self-check failure) |
+| 3 | ffmpeg/ffprobe missing or failed (`E_FFMPEG_MISSING` / `E_FFMPEG_FAILED`; install ffmpeg) |
+| 4 | recorder failure (`E_RECORDER_NO_FRAMES` and other capture/timeline errors) |
+
+## Control API
+
+### App control API
+
+Started with `--control-api=true` (or `npm run start:control`), it binds
+`127.0.0.1:7317` by default and drives the same `dispatchCommand` path as the Director:
+
+```bash
+curl http://127.0.0.1:$PORT/health
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:$PORT/state
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:$PORT/scenes
+curl -X POST -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
+  -d '{"cmd":"run.start","args":{"mode":"record"}}' http://127.0.0.1:$PORT/command
+curl -N -H "Authorization: Bearer $TOKEN" http://127.0.0.1:$PORT/events
+```
+
+`x-demo-token: $TOKEN` is accepted as the equivalent of the bearer header.
+`POST /command` returns 200 with `{"ok":true,"result":...}`; `DemoError` maps to 400,
+`E_PROFILE_LOCKED` / `E_STEP_TIMEOUT` / `E_RECORDER_NO_FRAMES` to 409, and anything else
+to 500. `/events` is SSE: a `: connected` comment, then a `: ping` comment every 15
+seconds, and `data:` lines carrying `AppEvent` JSON. The token is in
+`<out>/control.json` (0600) as `{url, token, pid}` and is compared with
+`crypto.timingSafeEqual`. The server sends no CORS headers, so a cross-origin browser
+script cannot call it; the API is for local scripts.
+
+### Agent tool API
+
+The lease endpoint exposes agent tools. `GET /v1/tools` returns the list with JSON
+Schema, and a call is `POST /v1/sessions/:id/tools/<tool>` with both the lease token and
+the session token:
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/sessions/$SESSION_ID/tools/snapshot \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "x-malo-session-token: $SESSION_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"max_chars":8000,"max_items":120}'
+```
+
+Tools: `navigate`, `history`, `events`, `observe`, `snapshot`, `extract`, `click`,
+`fill`, `upload_file`, `press`, `hover`, `select`, `focus`, `scroll`, `scroll_into_view`, `wait_for`,
+`sleep`, `assert`, `run_steps`, `network_capture`, `responses`, `watch`, `login`,
+`profiles`, `close`. `snapshot` returns body text, title, links, buttons, inputs, forms,
+tables, landmarks, iframes, dialogs and selectors for interactive elements; `extract`
+does targeted reads. `network_capture` subscribes this session to XHR/fetch response
+bodies for matching URL prefixes and `responses` returns them by seq, in daemon memory
+only. `run_steps` runs a list of those tools in order (stop at the first failure by
+default), writes a run report to the session's `artifacts/run-<timestamp>.json`, and
+returns `{ ok, step_count, failed_step, steps, report_path }`; `run_steps`, `watch`,
+`login`, `profiles` and `close` cannot be nested inside `run_steps`; `network_capture` and
+`responses` are session controls and are rejected there too, so captured bodies never
+reach a run report.
+
+Status mapping on the lease endpoint: bad arguments, unknown tools, selector-not-found
+and navigation policy violations → 400; unknown session → 404; locked profile → 409;
+session cap → 429; navigation failure → 502; step timeout → 504; real server failures →
+500. A navigation failure carries `details.navigation` (`http_status`, `net_error`,
+`net_error_description`, `settle`).
+
+### Profile login import
+
+`POST /v1/profiles/:name/import` seeds a persistent profile with cookies read live from
+another Chromium's DevTools endpoint, so a logged-in daily Chrome can hand its login
+state to a malo profile without re-typing credentials:
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/profiles/work/import \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"cdp_url":"http://127.0.0.1:9223"}'
+```
+
+Body: `cdp_url` (required, loopback `http://` only), `domains` (optional allowlist, e.g.
+`["example.com","example.org"]` — a cookie matches when its domain equals, is a subdomain of,
+or is a parent of an entry), and `session_cookie_ttl_days` (default 180; session cookies
+are re-stamped as persistent so the imported login survives daemon restarts; `0` keeps
+them session-only). The daemon connects to the source's browser-level WebSocket and calls
+`Storage.getCookies`, writes each cookie through the Electron cookie store of the target
+profile's partition, and returns
+`{ profile, created, source, cookies_total, cookies_matched, cookies_written, cookies_failed, failed }`
+(`failed` lists up to 20 per-cookie write errors, e.g. `__Host-` cookies that fail
+Chromium's prefix rules; `cookies_failed` counts that capped list, not all failures). Importing merges into whatever the profile already has; it
+never clears existing state, and cookies whose login has expired on the server side still
+need a real re-login. Source unreachable → 502 `E_IMPORT_SOURCE_UNREACHABLE`; zero
+cookies matched → 400 `E_IMPORT_EMPTY`. Only cookies move; localStorage, IndexedDB and
+HTTP cache stay in the source browser.
+
+Security boundary: loopback only, `Host` must be `127.0.0.1:<port>` or
+`localhost:<port>` (DNS-rebinding guard), JSON only with a 1MB body cap, broker / lease /
+session tokens are three separate layers, navigation is `http:`/`https:` only with
+URL-embedded credentials rejected, and `window.open` plus permission requests are denied
+by default. The old `x-pagehand-*` token headers are still accepted; new scripts use
+`x-malo-*`.
+
+### assert and run_steps verdicts
+
+A failed assertion is a business verdict, not a broken service. `assert` answers **HTTP
+200** with the verdict on the result:
+
+```json
+{
+  "tool": "assert",
+  "result": {
+    "ok": false,
+    "passed": false,
+    "checks": [{ "kind": "visible", "expected": true, "actual": false, "ok": false }],
+    "url": "https://example.com/done",
+    "waited_ms": 5001,
+    "screenshot": "<artifacts>/failure-<ms>.png",
+    "error": {
+      "code": "E_ASSERTION_FAILED",
+      "message": "E_ASSERTION_FAILED: 断言失败：visible expected true, got false",
+      "details": {
+        "checks": [{ "kind": "visible", "expected": true, "actual": false, "ok": false }],
+        "waited_ms": 5001,
+        "screenshotPath": "<artifacts>/failure-<ms>.png"
+      }
+    }
+  }
+}
+```
+
+On success `result.ok` and `result.passed` are `true`, and `result.checks` holds every
+check. So for both `assert` and `run_steps`, read `result.ok` for the verdict:
+`run_steps` also answers 200 when the batch ran, with `result.ok: false` plus
+`failed_step` and `steps[].error`. Invalid arguments stay 4xx and genuine server
+failures stay 5xx.
+
+Contract change in 0.1.2: an `assert` failure used to be HTTP 500 with
+`{"ok":false,"error":{"code":"E_ASSERTION_FAILED",...}}`. Callers that treated the 500
+status as "assertion failed" must now read HTTP 200 plus `result.ok`. This is a 0.1.x
+contract change, hence the explicit note.
+
+### Human handoff
+
+Logins, QR codes and human checks should not be brute-forced by an agent. `watch` and
+`login` make "human takes over once, agent gets control back" a contract: the window
+appears with `showInactive` by default (no keyboard focus, no Space switch), has a native
+title bar and a browser toolbar (back, forward, reload, address bar that accepts only
+http/https, Enter to navigate, address synced from the page). `focus: true` is the only
+way to bring it to the front. Credentials live only in that call's memory: never written
+to disk, events or responses; password fields read `[redacted]` and `assert value` on a
+password input is rejected instead of compared. A successful `login`
+hides the handoff window again (unless `keep_visible: true`), and the agent keeps the
+same session; `watch` stays visible until it is hidden explicitly, and a timed-out
+handoff window is not closed automatically. The login state survives only with a
+`profile`.
+
+## Project layout
+
+```text
+src/main/
+  index.ts            # startup, exit codes, top-level failure handling
+  cli.ts              # flags
+  app.ts              # app mode: scene service, Director, autorun, IPC
+  app-controller.ts   # state snapshot, scene loading, run, recording, evidence
+  ipc.ts              # Director channel and control commands
+  control-dispatch.ts # command dispatch shared by Director IPC and the control API
+  control/            # loopback HTTP control API (token + SSE)
+  stage-layout.ts     # scene size / policy / visit-order math
+  demo-protocol.ts    # demo:// scene protocol (registered per session)
+  electron-page-driver.ts  # PageDriver on Electron (CDP physical events)
+  electron-overlay.ts      # OverlayPort: cursor/highlight/spotlight/annotate/mask/blackout
+  malo/               # malo-browser daemon: port pool, leases, broker, sessions, HTTP
+  scenes/             # Zod validation, scene loading, interpolation, script hash
+  runner/             # state machine, 19 actions, target resolution
+  capture/            # screencast frames, 30fps timeline, ffmpeg, evidence
+  security/           # allowlist, path safety, permission and download policy
+  windows/            # Stage (BaseWindow + WebContentsView), Director
+  phase0.ts           # Phase 0 smoke / --mode=record path
+src/renderer/director # presenter console (React + lucide)
+src/preload/          # Director bridge (sandbox-safe)
+src/fixture/          # React fixture: counter, search, risk rows, animation
+fixtures/scenes/      # loadable scenes (report-review, login-demo, multi-a, multi-b)
+scripts/
+  run-phase0.sh      # primary evidence reproduction
+  malo-smoke.mjs     # multi-agent / multi-session daemon smoke
+  control-smoke.mjs  # control API: load -> record -> evidence
+  toolbar-smoke.mjs  # handoff toolbar (hidden StageWindow)
+  malo-web-probe.mjs # site compatibility probe (captures + screenshots)
+  compare.cjs        # SSIM comparison between two videos
+```
+
+## Troubleshooting
+
+- `EBADENGINE` warning/failure -> wrong Node line; use a range from `engines`
+  (>=22.12 on the 22 line, 24.x, or >=26; not 23/25).
+- Exit 0 with no stdout and no files in `<out>` -> `ELECTRON_RUN_AS_NODE` is set in that
+  shell (`echo $ELECTRON_RUN_AS_NODE`), so Electron ran as plain Node and never started
+  the app; re-run as `env -u ELECTRON_RUN_AS_NODE npx electron ...`.
+- Exit 3 `E_FFMPEG_MISSING` -> install ffmpeg (e.g. `brew install ffmpeg`) and re-run.
+- Exit 4 / recording failure -> open the take's `.evidence.json`: it exists even when no
+  video was written (`video: null`, `error.code`). `E_RECORDER_NO_FRAMES` means the
+  screencast delivered no frames; check that the page really rendered and that the window
+  was not destroyed mid-take.
+- `EADDRINUSE` -> the message names the right surface: `--control-port` for the control
+  API, `--daemon-port` for the broker, `--port-min`/`--port-max` for the lease pool.
+- Control API 401 -> read the token from `<out>/control.json` and send it as
+  `Authorization: Bearer <token>` or `x-demo-token: <token>`.
+- Director shows a MOCK marker -> the preload bridge is missing; launch via `npm start` /
+  `npm run start:control`, not by opening the HTML directly.
+- `E_SELECTOR_NOT_FOUND` -> no visible element matched; check target syntax. For `fill`
+  the `text` is the input content, so the target needs `selector` / `data_demo_id` /
+  coordinates (or `target_text`); for `annotate` `text` is the annotation copy.
+- `E_ACCOUNT_NOT_FOUND` -> account file or `account_id` missing; check
+  `MALO_BROWSER_ACCOUNTS` and the ids listed in the error.
+- `E_ACCOUNT_INVALID` with `0600` or `outside a git worktree` -> move the profile outside
+  the repo and run `chmod 600 <accounts.json>`.
+- `E_ACCOUNT_INVALID` with `environment variable` -> export the profile's
+  `password_env` in the shell that launches Electron; never put the password in scene
+  YAML.
+- A window steals focus during recording -> a focusing `--window-mode` was passed; the
+  defaults (`hidden`/`inactive`) never take focus.
+- `assert` returns HTTP 200 with `result.ok: false` -> that is the verdict, not a broken
+  service; read `result.error.details.checks` and the failure screenshot.
+- malo session 401 -> send both the lease token and the session token; a session token
+  from another session is rejected. 404 after a long idle period -> the session was
+  reaped, create a new one.
+- Daemon refuses to start -> another daemon owns that data directory; stop it or pass a
+  different `--data-dir`.
+
+## Side effects
+
+- Writes evidence and recordings under `--out` (default `./evidence`): mp4, evidence
+  JSON, overlay check frames, app-mode takes under `recordings/`, failed step
+  screenshots under `errors/<scene>/`, and `control.json` (0600) when the control API is
+  on.
+- Starts ffmpeg/ffprobe child processes while encoding and self-checking; capture itself
+  costs CPU while the take runs.
+- Binds loopback ports only: control API `7317`, broker `7410`, lease pool `7411-7499`
+  (all configurable). No listener on external interfaces.
+- Opens windows depending on mode: none by default in record / autorun / headless;
+  a visible, unfocused stage with `npm start`; the handoff window for `watch`/`login`.
+  Non-interactive macOS modes switch to the accessory activation policy and hide the
+  Dock icon; while any human-visible window is on screen the Dock icon is shown so a
+  buried window can be raised from the Dock, and it disappears again once none is left.
+- The malo daemon keeps running until stopped, writes `~/.malo-browser` (broker.json
+  0600, Chromium profile data, per-session downloads/artifacts), and deletes anonymous
+  session partitions when those sessions close.
+- Login state persists only for named `profile` sessions, until
+  `DELETE /v1/profiles/:name`.
+- Permissions and `window.open` are denied. Downloads are allowed, but only into the
+  session's own `downloads/` directory (sanitized filename); the demo stage additionally
+  refuses downloads unless the scene policy allows them.
+
+## Limitations
+
+- Verified on macOS only; other platforms are untested.
+- Recording caps at 1920x1080 and a 30fps timeline; evidence self-checks enforce that.
+- Not a general-purpose browser: no tabs, bookmarks or multi-tab UI; the handoff window
+  only has an address bar plus back/forward/reload.
+- Loopback only: no remote access, no multi-user service, no approval flow or remote
+  deployment.
+- Hidden mode needs focus emulation; with `--focus-emulation=false` physical clicks are
+  dropped.
+- The agent runtime runs one daemon per data directory, defaults to 4 sessions per lease
+  and reaps idle sessions after 300 seconds; it never streams video continuously.
+- Login handling is auto-detection plus selector overrides, not a per-site adapter
+  layer.
+- Sites can block automated or headless browsers at the network / challenge layer; see
+  [docs/malo-web-compat.md](docs/malo-web-compat.md). `network_capture` covers the page
+  target only: OOPIF (cross-process iframe) and Service Worker requests are not captured.
+- 0.1.x contract change: `assert` failures are HTTP 200 with `result.ok: false`, not
+  HTTP 500. Callers that keyed on 500 must be updated.
+
+## License
+
+MIT (see [LICENSE](LICENSE)).
diff --git a/external_plugins/malo-browser/README_CN.md b/external_plugins/malo-browser/README_CN.md
new file mode 100644
index 00000000..1a2ef7db
--- /dev/null
+++ b/external_plugins/malo-browser/README_CN.md
@@ -0,0 +1,518 @@
+<p align="center"><img src="assets/malo-browser/icon.png" width="88" height="88" alt="Malo Browser 图标"></p>
+
+<h1 align="center">Malo Browser</h1>
+
+演示用浏览器。基于 Electron + Chromium，把网页演示拆成
+Stage（给观众看）和 Recorder（固定规格录制），不 fork 浏览器内核；
+演示流程用场景脚本编排，配 Director 控制台与本地控制 API。
+
+当前仓库是 0.1.x 的可工作原型：无头录制、CDP 物理交互、覆盖层、1080p30 出片、
+证据文件、最小 `.app`。它同时是 `malo-browser` agent 运行时：常驻 daemon 分发端口租约，
+多个 agent 可以并行驱动相互隔离的浏览 session。
+
+## 安装
+
+### 环境要求
+
+- Node 22 行的 22.12 及以上、24.x，或 26 及以上（`engines` 为
+  `^22.12.0 || ^24.0.0 || >=26.0.0`，不含 23 与 25 行）。该范围已写进
+  `package.json`，版本不满足时包管理器在安装阶段就给出明确提示（yarn 直接失败；
+  npm / pnpm 默认打印 EBADENGINE 警告、`engine-strict` 下失败），不会拖到
+  vite / vitest 深处才炸出难懂的错误。
+- `PATH` 上有 ffmpeg 与 ffprobe（先查 `PATH`，再回退到 Homebrew / 本地安装目录）；
+  缺失时以退出码 3 结束。
+- macOS 是已验证路径：窗口模式与录制在 macOS 上实测，隐藏模式使用 accessory 激活策略。
+- Python 3 仅用于起内置 fixture 静态服务（`python3 -m http.server`）。
+- git。
+
+### 从源码
+
+```bash
+git clone https://github.com/Lumos-789/malo-browser.git
+cd malo-browser
+npm install
+npm run build
+```
+
+`npm run build` 用 tsc 编译主进程、用 vite 打包 fixture 与 director 控制台。
+`npm run typecheck` 只做类型检查、不产物；`npm test` 跑 vitest 单元测试。
+
+### 插件形态
+
+仓库既是应用也是插件载体，不复制第二份源码。
+
+- ZCode 插件：`.zcode-plugin/plugin.json`（名称 `malo-browser`，版本与主仓一致），
+  技能 `skills/malo-browser/SKILL.md`（安装 / 配置 / 排障型，不复制产品逻辑），
+  图标 `assets/malo-browser/icon.png`（512x512）。已注册 `dev-oss-projects` 市场时：
+  `zcode plugins install malo-browser@dev-oss-projects -s user`。
+- DSH bundle：`package.json` 声明 `dsh.bundle`（patch 指向仓根 `cordis.patch.yml`），
+  `index.js` 用 `bundledSkillDir` 挂载 `skills/`。`engines.dsh` 与
+  `@deepseek-ai/*` peerDependencies 也在 `package.json`；peer 声明为 optional，
+  不影响本仓作为 Electron 应用的 `npm install`。
+
+## 运行
+
+先另开一个终端起 fixture 页面（默认演示目标）：
+
+```bash
+python3 -m http.server 4788 --bind 127.0.0.1 --directory out/fixture
+```
+
+默认：无头后台录制，10 秒。
+
+```bash
+npx electron . --mode=record --seconds=10 --out=evidence --label=hidden
+```
+
+默认录制不显示窗口、不抢焦点、不占 Dock（macOS 下 `setActivationPolicy('accessory')`），
+可以一边录一边继续用电脑。
+
+| 命令 | 作用 |
+|---|---|
+| `npm run build` | 编译主进程（tsc），打包 fixture 与 director（vite） |
+| `npm run typecheck` | 主进程 + renderer 类型检查，不产物 |
+| `npm test` | vitest 单元测试 |
+| `npm start` | Director 控制台 + Stage；Stage 以 `inactive` 显示，不抢焦点 |
+| `npm run start:control` | 同上，并启动本地控制 API（`http://127.0.0.1:7317`） |
+| `npx electron . --mode=record --seconds=10` | 无头录制（默认） |
+| `npx electron . --mode=record --window-mode=inactive --seconds=10` | 可见但不抢焦点录制 |
+| `npx electron . --mode=record --plain --seconds=10` | 不做交互，只录静态页（对照用） |
+| `npx electron . --mode=app --autorun=report-review --scenes=fixtures/scenes` | 无头跑完整场景并出片 |
+| `npx electron . --mode=app --director-check` | 隐形校验 Director 与 preload 桥接 |
+| `npx electron . --mode=app --headless=true --control-api=true` | 全无窗口后台实例，只留控制 API 与录制 |
+| `npx electron . --mode=stage --window-mode=inactive` | 可见 Stage，手动体验页面 |
+| `npm run daemon` | malo-browser 后台 broker，向多个 agent 分发隔离 session |
+| `npm run smoke:malo -- <broker.json> <fixture-url>` | 跑 malo-browser 多 agent / 多 session 真实链路 |
+| `npm run smoke:toolbar` | 无头校验人工接管窗口的工具条（preload、回车跳转、地址同步、后退、页面视口） |
+| `npm run smoke:control -- report-review` | 对已启动的控制 API 跑一遍加载场景 → 录制 → 校验 evidence |
+| `npm run package` | 打一个 `.app`（`dir` 目标，不生成安装包）到 `dist/`（Apple Silicon 为 `dist/mac-arm64/Malo Browser.app`） |
+| `./scripts/run-phase0.sh` | 跑 Phase 0 主证据（hidden + inactive） |
+
+`--mode=stage` 跟随 `--window-mode`，而它的默认值是 `hidden`；要真正看到 Stage，
+请显式传 `--window-mode=inactive`（或 `focused`）。
+
+常用参数：`--url`、`--width`、`--height`、`--out`、`--label`、`--keep-frames`、
+`--window-mode=hidden|inactive|offscreen|ghost|focused`、`--focus-emulation=false`、
+`--control-api=true`、`--control-port`、`--headless=true`、`--scenes`、`--autorun`、
+`--plain`。参数拼错会直接报错退出；`--help` 打印完整说明，`--version` 打印版本号。
+
+本地控制 API 只绑回环地址，启动时生成随机 token 并写到 `<out>/control.json`（0600）。
+路由与 curl 示例见下文「应用控制 API」一节。
+
+### 窗口与焦点模式
+
+Phase 0 实测：
+
+| 模式 | 行为 | 可录制 | 可交互 |
+|---|---|---|---|
+| `hidden`（默认） | 不显示窗口 | 是 | 是（带焦点仿真） |
+| `hidden` + `--focus-emulation=false` | 不显示窗口 | 是 | 否，点击会被丢弃 |
+| `inactive` | 显示窗口但不抢焦点 | 是 | 是 |
+| `offscreen` | 显示到屏幕外 (-12000, -12000) | 是 | 是 |
+| `ghost` | 显示但透明度 0 | 是 | 是 |
+| `focused` | 显示窗口并抢焦点 | 是 | 是 |
+
+无头模式必须配合 `Emulation.setFocusEmulationEnabled`（默认开启），否则 CDP 物理点击
+不会生效。
+
+### malo-browser（agent 运行时）
+
+`malo-browser` 是给 agent 用的后台 Web 执行层：一个常驻 daemon 管理端口租约，每个
+agent 拿一个稳定端口，同一端口下可以开多个相互隔离的 session。默认没有可见窗口，
+不抢焦点、不抢屏、不切 Space；截图只在显式请求或动作失败取证时生成。
+
+```bash
+npm run daemon
+# in another terminal
+curl -s http://127.0.0.1:7410/health
+cat ~/.malo-browser/broker.json
+```
+
+默认：broker `127.0.0.1:7410`，lease 端口池 `7411-7499`，数据目录 `~/.malo-browser`。
+启动成功会打印一行 JSON，并写入 `~/.malo-browser/broker.json`（0600），内容为
+`{endpoint, token, pid}`。同一个数据目录只允许一个 daemon：已有实例仍健康时，新进程
+会明确报错；已停止实例留下的 `broker.json` 会被识别为陈旧文件并覆盖。
+
+daemon 参数：`--daemon-port=7410`、`--port-min=7411`、`--port-max=7499`、
+`--lease-ttl-seconds=300`、`--session-idle-seconds=300`、`--max-sessions=4`、
+`--data-dir=~/.malo-browser`。
+
+新 session 需要同时带 lease token 和自己的 session token；拿 session A 的 token 访问
+session B 会返回 401。`width` / `height` 是页面视口尺寸，人工接管窗口的工具条不占用
+这两个值。不带 `profile` 的 session 是匿名的，关闭即清空；创建时带
+`{"profile":"work"}` 的 session 共享该 profile 的 cookies 与 storage，跨 session、
+跨 daemon 重启保留。profile 名只接受小写字母、数字、点、下划线、短横线，最长 64 字符。
+数据落在 `<data-dir>/leases/<lease-id>/sessions/<session-id>/{downloads,artifacts}`，
+profile 数据落在 `<data-dir>/chromium`。
+
+`delivery-video` 只是视觉输出适配器，不决定 malo-browser 的内核边界。
+
+### 验证脚本
+
+- `npm run smoke:malo -- ~/.malo-browser/broker.json http://127.0.0.1:4788` 跑真实 daemon
+  链路（详见 [docs/malo-browser.md](docs/malo-browser.md)）。
+- `npm run smoke:toolbar` 先 build，再在隐藏窗口里驱动人工接管工具条。
+- `npm run smoke:control -- report-review` 连已经在跑的控制 API；需要设
+  `DEMO_CONTROL_URL`（默认 `http://127.0.0.1:7317`）与 `DEMO_CONTROL_TOKEN`
+  （从 `<out>/control.json` 读）。
+
+## 场景脚本
+
+场景是 `fixtures/scenes/<id>/scene.yaml` 下的 YAML，通过 `demo://scene/<id>/...`
+协议加载，只允许读写场景目录内的文件。字段契约见
+[schemas/scene.schema.json](schemas/scene.schema.json)。
+
+### 内置场景
+
+- `report-review`：当前可用场景，7 步
+  `wait_for -> highlight -> click -> fill -> assert -> spotlight -> annotate`；
+  页面以 `demo://scene/report-review/index.html` 加载。
+- `multi-a -> multi-b`：验证多场景切换：1280x720 切到 1600x900，同一路 screencast
+  不断流，evidence 里记 `run.scene_ids`。
+- `login-demo`：完整账号登录链路（见下）。
+
+场景动作：`goto`、`login`、`wait`、`wait_for`、`wait_for_presenter`、`click`、
+`fill`、`press`、`scroll`、`highlight`、`spotlight`、`annotate`、`mask`、`blackout`、
+`assert`、`scene`、`set`、`note`、`screenshot`（共 19 个）。
+
+### 目标解析
+
+带目标的动作按固定顺序解析，先命中先用：
+
+| 优先级 | 写法 | 解析为 |
+|---|---|---|
+| 1 | `data_demo_id: increment` | `[data-demo-id="increment"]` |
+| 2 | `selector: ".btn-primary"` | 原样 CSS 选择器 |
+| 3 | `text: 金额异常` | 文本匹配（规则见下） |
+| 4 | `x: 640` + `y: 360` | 视口坐标点（无选择器，兜底用） |
+
+文本匹配在页面内找**可见**（非隐藏且有尺寸）且文本**包含**目标串的最小元素，命中后
+打上运行期属性供该步后续命令复用。找不到匹配、或四层目标都没写，都报
+`E_SELECTOR_NOT_FOUND`（报错文案会区分「没有元素包含这段文本」与「步骤没有可解析的
+点击或视觉目标」）。
+
+三个特例里 `text` 不当目标用：
+
+- `fill`：`text` 是要输入的内容；目标另写 `selector` / `data_demo_id` / 坐标，
+  或用 `target_text` 指定要点的元素文本；
+- `annotate`：`text` 是标注文案；目标必须是 `selector` / `data_demo_id` / 坐标；
+- `wait_for`：`text` 是等待条件（等文本出现），不是点击目标。
+
+### 账号登录
+
+`login` 动作使用仓库外的 `0600` 账户文件：场景只写 `account_id`，密码在运行时从
+`password_env` 读取，动作负责打开登录页、填写、提交并等待成功条件。
+`fixtures/scenes/login-demo` 可验证完整链路。默认账户文件为
+`~/.config/malo-browser/accounts.json`，可用 `MALO_BROWSER_ACCOUNTS` 覆盖。文件必须
+位于 git worktree 之外、是普通 `0600` 文件、`origin` 与 `login_url` 同源，并至少配置
+`success_selector` 或 `success_url`；带明文 `password` 字段会被拒绝。配置格式、安全
+边界、运行示例和失败排查见 [docs/accounts.md](docs/accounts.md)。
+
+### 场景变量
+
+`vars` 存放场景内字符串，`${name}` 在动作字段里插值；`${env:SCENE_NAME}` 只读取
+`SCENE_` 前缀的环境变量，其他名字一律拒绝——第三方提供的场景因此无法把云密钥或 token
+拼进 URL 或表单。
+
+### 校验
+
+Scene 层校验一次报全所有错误；未知字段、越界时间、缺目标都会在加载前失败。
+
+## 录制与证据
+
+### 产物文件
+
+一次 `--mode=record` 录制按 label 落：
+
+```text
+evidence/
+  hidden.mp4
+  hidden.evidence.json      # 版本、视口、DPR、帧数、时长、SHA256、步骤、自检结果
+  hidden.overlay-frame.png  # 覆盖层校验帧（--plain 时不生成）
+  hidden.overlay-before.png # 覆盖层出现前的对照帧（--plain 时不生成）
+```
+
+app 模式的 take（autorun 或控制 API）落在
+`<out>/recordings/<timestamp>_<scene>/take-01.mp4` 与同名 `take-01.evidence.json`；
+`assert` 失败会额外落一张 `<out>/errors/<scene>/step-<index>.png`（其他动作失败只带错误，
+不截图）。
+
+app 模式 evidence 与成片都以 0600 权限写入。文档记录 `status`、`app`、`scene`、`run`（多场景
+take 含 `run.scene_ids`）、`capture`、`video`、`steps`、`checks`、`warnings`，失败时
+还有 `error`。
+
+### 自检
+
+`--mode=record` 的 take 只有全部自检通过才返回 0：窗口无 Node、帧到达、时长误差
+≤0.5s、30fps、1920x1080、黑帧占比 <50%、覆盖层真的进了视频（`--plain` 跳过）。
+
+app 模式的 take 检查 `frames_arrived`、`steps_completed`、`steps_within_take`；步骤
+失败或自检失败都会把 evidence 标成 `failed`，take 带 `video.partial`。自检失败抛
+`E_EVIDENCE_MISMATCH`，并带上失败项 id。autorun 路径里步骤失败也会先停录制器，所以
+take 仍保留视频与失败 evidence。
+
+### 失败的 take
+
+「失败也有证据」对所有入口成立：
+
+- `--mode=record` 在视频编码之前抛错时，写 `<out>/<label>.evidence.json`，含
+  `status: "failed"`、`video: null`、`error.code`、`error.message` 与失败步骤
+  `error.step`；覆盖打开舞台（例如页面不可达，记为 `ERR_CONNECTION_REFUSED`）、采帧、
+  步骤与编码失败。失败前已写出的部分产物列在 `artifacts` 里。
+- app 模式（`--autorun`、控制 API、IPC）在录制器编码之前失败时，写该 take 的
+  `take-01.evidence.json`，含 `status: "failed"`、`video: null`、`error.code` 与
+  `error.message`——包括 0 帧的 `E_RECORDER_NO_FRAMES`——随后继续抛原始错误，所以退出码
+  / 控制 API 错误行为不变。
+- 录制器成功、但 run 里有失败步骤的 take 保留视频（`video.partial: true`），并记录
+  步骤错误。
+- `--keep-frames` 额外保留失败 take 的原始帧。
+
+### 退出码
+
+| 退出码 | 含义 |
+|---|---|
+| 0 | 成功：自检全过（`--mode=app --autorun` 成功时 stdout 另输出一行 JSON） |
+| 2 | 参数错误或通用失败（页面加载失败、`E_SELECTOR_NOT_FOUND`、断言失败、CDP 附加失败、场景校验失败、端口被占用、evidence 自检失败） |
+| 3 | ffmpeg/ffprobe 缺失或执行失败（`E_FFMPEG_MISSING` / `E_FFMPEG_FAILED`，先安装 ffmpeg） |
+| 4 | 录制器失败（`E_RECORDER_NO_FRAMES` 等采帧/时间轴错误） |
+
+## 控制 API
+
+### 应用控制 API
+
+用 `--control-api=true`（或 `npm run start:control`）启动，默认绑 `127.0.0.1:7317`，
+命令走与 Director 相同的 `dispatchCommand` 通道：
+
+```bash
+curl http://127.0.0.1:$PORT/health
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:$PORT/state
+curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:$PORT/scenes
+curl -X POST -H "Authorization: Bearer $TOKEN" -H "content-type: application/json" \
+  -d '{"cmd":"run.start","args":{"mode":"record"}}' http://127.0.0.1:$PORT/command
+curl -N -H "Authorization: Bearer $TOKEN" http://127.0.0.1:$PORT/events
+```
+
+`x-demo-token: $TOKEN` 与 bearer 头等价。`POST /command` 成功返回 200 与
+`{"ok":true,"result":...}`；`DemoError` 映射为 400，`E_PROFILE_LOCKED` /
+`E_STEP_TIMEOUT` / `E_RECORDER_NO_FRAMES` 为 409，其余为 500。`/events` 是 SSE：先回
+`: connected` 注释行，此后每 15 秒一行 `: ping`，`data:` 行是 `AppEvent` JSON。token
+在 `<out>/control.json`（0600）里，内容为 `{url, token, pid}`，服务端用
+`crypto.timingSafeEqual` 比较。接口不返回 CORS 头，跨源浏览器脚本无法直接调用，
+只面向本机脚本。
+
+### Agent 工具 API
+
+lease endpoint 暴露 agent 工具。`GET /v1/tools` 返回带 JSON Schema 的工具清单，调用入口是
+`POST /v1/sessions/:id/tools/<tool>`，需要同时带 lease token 与 session token：
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/sessions/$SESSION_ID/tools/snapshot \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "x-malo-session-token: $SESSION_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"max_chars":8000,"max_items":120}'
+```
+
+工具：`navigate`、`history`、`events`、`observe`、`snapshot`、`extract`、`click`、
+`fill`、`upload_file`、`press`、`hover`、`select`、`focus`、`scroll`、`scroll_into_view`、`wait_for`、
+`sleep`、`assert`、`run_steps`、`network_capture`、`responses`、`watch`、`login`、
+`profiles`、`close`。`snapshot` 返回正文、标题、链接、按钮、输入框、表单、表格、
+landmark、iframe、dialog 和可交互元素的 selector；`extract` 做定向读取。
+`network_capture` 为当前 session 订阅命中 URL 前缀的 XHR/fetch 响应体，`responses`
+按 seq 取回，body 只留在 daemon 内存。`run_steps` 顺序执行一串工具（默认遇错即停），
+把 run report 写进 session 的 `artifacts/run-<timestamp>.json`，返回
+`{ ok, step_count, failed_step, steps, report_path }`；`run_steps`、`watch`、`login`、
+`profiles` 与 `close` 自身不能再嵌进 `run_steps`；`network_capture`、`responses` 属于 session
+控制，同样会被拒绝，捕获到的 body 不会进入 run report。
+
+lease endpoint 状态码：参数错误、未知工具、选择器找不到、导航策略拒绝 → 400；session
+不存在 → 404；profile 被占用 → 409；session 超上限 → 429；导航失败 → 502；步骤超时 →
+504；服务内部异常 → 500。导航失败会在 `details.navigation` 中带 `http_status`、
+`net_error`、`net_error_description` 和 `settle` 信息。
+
+安全边界：只监听回环地址；`Host` 只接受 `127.0.0.1:<port>` 与 `localhost:<port>`（防
+DNS rebinding）；只接受 JSON、请求体上限 1MB；broker / lease / session token 三层分离；
+只允许 `http:` / `https:` 导航，拒绝 URL 内嵌 credentials；`window.open` 与权限请求默认
+拒绝。旧版 `x-pagehand-*` token 头仍被接受，新脚本请用 `x-malo-*`。
+
+### Profile 登录态导入
+
+`POST /v1/profiles/:name/import` 从另一个 Chromium 的 DevTools 端点实时读取 cookie
+并写进持久 profile：已登录的日常 Chrome 无需重新输入密码，就能把登录态交给一个 malo
+profile：
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/profiles/work/import \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"cdp_url":"http://127.0.0.1:9223"}'
+```
+
+请求体：`cdp_url`（必填，只允许回环 `http://`）、`domains`（可选白名单，如
+`["example.com","example.org"]`——cookie 的域与条目相等、是其子域或父域即算匹配）、
+`session_cookie_ttl_days`（默认 180；session cookie 会被改写成持久 cookie，让导入的
+登录态活过 daemon 重启；`0` 表示保持 session-only）。daemon 连上源浏览器的
+browser-level WebSocket 调 `Storage.getCookies`，把每条 cookie 经目标 profile 分区的
+Electron cookie store 写入，返回
+`{ profile, created, source, cookies_total, cookies_matched, cookies_written, cookies_failed, failed }`
+（`failed` 最多列 20 条逐 cookie 写入错误，例如过不了 Chromium 前缀规则的 `__Host-`
+cookie；`cookies_failed` 统计的是封顶后的列表，不是全部失败数）。导入只合并不清空
+profile 已有状态；服务端已过期的登录仍然需要真实重新登录。源浏览器连不上 → 502
+`E_IMPORT_SOURCE_UNREACHABLE`；域过滤后 0 条 → 400 `E_IMPORT_EMPTY`。只迁移 cookie，
+localStorage、IndexedDB 与 HTTP cache 都留在源浏览器。
+
+### assert 与 run_steps 判决
+
+断言没通过是业务判决，不是服务坏了。`assert` 返回 **HTTP 200**，判决在 result 上：
+
+```json
+{
+  "tool": "assert",
+  "result": {
+    "ok": false,
+    "passed": false,
+    "checks": [{ "kind": "visible", "expected": true, "actual": false, "ok": false }],
+    "url": "https://example.com/done",
+    "waited_ms": 5001,
+    "screenshot": "<artifacts>/failure-<ms>.png",
+    "error": {
+      "code": "E_ASSERTION_FAILED",
+      "message": "E_ASSERTION_FAILED: 断言失败：visible expected true, got false",
+      "details": {
+        "checks": [{ "kind": "visible", "expected": true, "actual": false, "ok": false }],
+        "waited_ms": 5001,
+        "screenshotPath": "<artifacts>/failure-<ms>.png"
+      }
+    }
+  }
+}
+```
+
+通过时 `result.ok` 与 `result.passed` 为 `true`，`result.checks` 带全部检查项。所以
+`assert` 与 `run_steps` 都统一读 `result.ok` 拿判决：`run_steps` 在批次跑完时同样是
+200，`result.ok: false` 配 `failed_step` 与 `steps[].error`。非法参数仍是 4xx，真正的
+服务内部异常仍是 5xx。
+
+0.1.2 契约变更：`assert` 失败原先是 HTTP 500 加
+`{"ok":false,"error":{"code":"E_ASSERTION_FAILED",...}}`。把 500 状态当成「断言失败」的
+调用方必须改成读 HTTP 200 加 `result.ok`。这是 0.1.x 的契约变更，因此明确写出。
+
+### 人工接管
+
+登录、扫码和人机校验不该让 agent 硬碰。`watch` 与 `login` 把「人接手一次、agent 拿回
+控制权」做成契约：窗口默认以 `showInactive` 出现（不抢键盘焦点、不切 Space），带原生
+标题栏和一条浏览器工具条（后退、前进、刷新，地址栏只接受 http/https，回车跳转，地址随
+页面同步）。只有显式 `focus: true` 才把窗口带到前台。凭据只存在于本次调用内存：不落盘、
+不进事件、不回显；密码框固定读 `[redacted]`，且对密码框做 `assert value` 会被拒绝而不是
+拿脱敏串比较。`login` 成功后窗口自动隐藏（`keep_visible:
+true` 可留给人继续操作），agent 继续用同一个 session；`watch` 打开的窗口要显式关闭才
+隐藏，超时的人工接管窗口也不会自动关闭。登录态只有指定 `profile` 时才保留。
+
+## 项目结构
+
+```text
+src/main/
+  index.ts            # 启动、退出码、全局失败兜底
+  cli.ts              # 参数
+  app.ts              # app 模式装配：Scene 服务、Director、autorun、IPC
+  app-controller.ts   # 状态快照、场景加载、运行、录制、evidence
+  ipc.ts              # Director 通道与控制命令
+  control-dispatch.ts # Director IPC 与本地 API 共用的命令分发
+  control/            # 本地 HTTP 控制 API（回环 + token + SSE）
+  stage-layout.ts     # 场景尺寸/安全策略/访问顺序的纯计算
+  demo-protocol.ts    # demo:// 场景协议（按 session 注册）
+  electron-page-driver.ts  # PageDriver 的 Electron 实现（CDP 物理事件）
+  electron-overlay.ts      # OverlayPort：光标/高亮/聚光/标注/遮罩/黑屏
+  malo/               # malo-browser daemon：端口池、租约、broker、session、HTTP
+  scenes/             # Zod 校验、Scene 加载、变量插值、脚本 hash
+  runner/             # 状态机、19 个动作、目标解析
+  capture/            # screencast 抓帧、30fps 时间轴、ffmpeg、evidence
+  security/           # 白名单、路径安全、权限与下载策略
+  windows/            # Stage（BaseWindow+WebContentsView）、Director
+  phase0.ts           # Phase 0 冒烟 / --mode=record 路径
+src/renderer/director # 讲解人控制台（React + lucide）
+src/preload/          # Director 桥接（沙箱可用）
+src/fixture/          # React fixture：计数按钮、搜索、风险行、动画
+fixtures/scenes/      # 可直接加载的场景（report-review、login-demo、multi-a、multi-b）
+scripts/
+  run-phase0.sh      # 主证据复现
+  malo-smoke.mjs     # 多 agent / 多 session daemon 冒烟
+  control-smoke.mjs  # 控制 API：加载 → 录制 → evidence
+  toolbar-smoke.mjs  # 人工接管工具条（隐藏 StageWindow）
+  malo-web-probe.mjs # 站点兼容性探针（抓帧 + 截图）
+  compare.cjs        # 两段视频的 SSIM 对比
+```
+
+## 排障
+
+- `EBADENGINE` 警告/失败 → Node 行不对；用 `engines` 允许的范围（22 行 ≥22.12、24.x，
+  或 ≥26；不含 23/25）。
+- 退出码 0、没有 stdout、`<out>` 里也没有文件 → 该 shell 里设了
+  `ELECTRON_RUN_AS_NODE`（用 `echo $ELECTRON_RUN_AS_NODE` 确认），Electron 当普通 Node
+  跑、应用根本没启动；改用 `env -u ELECTRON_RUN_AS_NODE npx electron ...`。
+- 退出码 3 `E_FFMPEG_MISSING` → 安装 ffmpeg（例如 `brew install ffmpeg`）后重试。
+- 退出码 4 / 录制失败 → 打开该 take 的 `.evidence.json`：即使没出视频它也存在
+  （`video: null`、`error.code`）。`E_RECORDER_NO_FRAMES` 表示 screencast 没有送达任何
+  帧；确认页面真的渲染了，以及窗口没有在录制中途被销毁。
+- `EADDRINUSE` → 报错会指出该改哪个参数：控制 API 用 `--control-port`，broker 用
+  `--daemon-port`，lease 端口池用 `--port-min`/`--port-max`。
+- 控制 API 401 → 从 `<out>/control.json` 读 token，用 `Authorization: Bearer <token>`
+  或 `x-demo-token: <token>` 发送。
+- Director 显示 MOCK → preload 桥接缺失；用 `npm start` / `npm run start:control`
+  启动，不要直接打开 HTML。
+- `E_SELECTOR_NOT_FOUND` → 没有可见元素匹配；检查目标写法。`fill` 的 `text` 是输入
+  内容，目标要写 `selector` / `data_demo_id` / 坐标（或用 `target_text`）；`annotate`
+  的 `text` 是标注文案。
+- `E_ACCOUNT_NOT_FOUND` → 账户文件或 `account_id` 缺失；检查 `MALO_BROWSER_ACCOUNTS`
+  以及报错里列出的可用 id。
+- `E_ACCOUNT_INVALID` 带 `0600` 或 `outside a git worktree` → 把账户文件移出仓库并
+  `chmod 600 <accounts.json>`。
+- `E_ACCOUNT_INVALID` 带 `environment variable` → 在启动 Electron 的那个 shell 里
+  export 该 profile 的 `password_env`；永远不要把密码写进场景 YAML。
+- 录制时窗口抢焦点 → 传了会抢焦点的 `--window-mode`；默认的 `hidden`/`inactive`
+  都不会抢焦点。
+- `assert` 返回 HTTP 200 且 `result.ok: false` → 这是判决而不是服务坏了；读
+  `result.error.details.checks` 和失败截图。
+- malo session 401 → 必须同时带 lease token 与 session token；用别的 session 的 token
+  会被拒绝。长时间空闲后 404 → session 已被回收，新建一个。
+- daemon 起不来 → 另一个 daemon 占着这个数据目录；停掉它，或换 `--data-dir`。
+
+## 副作用
+
+- 在 `--out`（默认 `./evidence`）下写 evidence 与录制产物：mp4、evidence JSON、覆盖层
+  校验帧、app 模式的 take（`recordings/`）、失败步骤截图（`errors/<scene>/`），开控制
+  API 时还有 `control.json`（0600）。
+- 编码与自检时启动 ffmpeg/ffprobe 子进程；录制期间采帧本身也占 CPU。
+- 只绑回环端口：控制 API `7317`、broker `7410`、lease 端口池 `7411-7499`（都可改）。
+  不在外部网卡上监听。
+- 按模式决定是否开窗：record / autorun / headless 默认不开；`npm start` 开一个可见但
+  不抢焦点的 Stage；`watch`/`login` 开人工接管窗口。macOS 非交互模式切到 accessory
+  激活策略并隐藏 Dock 图标；有可见窗口期间 Dock 会亮出图标（被挡住的窗口点 Dock
+  即可调回最前），窗口全部收起后图标自动消失。
+- malo daemon 会一直运行到被停止，写 `~/.malo-browser`（broker.json 0600、Chromium
+  profile 数据、每 session 的 downloads/artifacts），匿名 session 关闭时删除自己的
+  partition。
+- 登录态只在指定 `profile` 的 session 上保留，直到 `DELETE /v1/profiles/:name`。
+- 权限与 `window.open` 默认拒绝。下载允许，但只能落进当前 session 自己的 `downloads/`
+  目录（文件名已消毒）；演示端（Stage）另按场景策略决定是否放行下载。
+
+## 限制
+
+- 只在 macOS 上验证过；其他平台未测。
+- 录制上限 1920x1080、30fps 时间轴，evidence 自检按这个规格校验。
+- 不是通用浏览器：没有标签页、书签或多标签 UI；人工接管窗口只有地址栏加
+  后退/前进/刷新。
+- 只做回环：不支持远程访问、多用户服务化，也没有审批流或远程部署。
+- 隐藏模式依赖焦点仿真；`--focus-emulation=false` 时物理点击会被丢弃。
+- agent 运行时一个数据目录只跑一个 daemon，每 lease 默认 4 个 session，空闲 300 秒
+  回收；不做连续视频推流。
+- 登录处理是自动识别加 selector 覆盖，不是按站点配置的适配层。
+- 站点可能在网络层 / 人机校验层拦自动化或无头浏览器，见
+  [docs/malo-web-compat.md](docs/malo-web-compat.md)。`network_capture` 只覆盖页面
+  target：OOPIF（跨进程 iframe）与 Service Worker 发出的请求抓不到。
+- 0.1.x 契约变更：`assert` 失败是 HTTP 200 加 `result.ok: false`，不再是 HTTP 500；
+  按 500 判断的调用方必须改。
+
+## 许可
+
+MIT（见 [LICENSE](LICENSE)）。
diff --git a/external_plugins/malo-browser/assets/malo-browser/icon.png b/external_plugins/malo-browser/assets/malo-browser/icon.png
new file mode 100644
index 00000000..8f1e2f4c
Binary files /dev/null and b/external_plugins/malo-browser/assets/malo-browser/icon.png differ
diff --git a/external_plugins/malo-browser/assets/malo-browser/icon.svg b/external_plugins/malo-browser/assets/malo-browser/icon.svg
new file mode 100644
index 00000000..1dac4477
--- /dev/null
+++ b/external_plugins/malo-browser/assets/malo-browser/icon.svg
@@ -0,0 +1,14 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="512" height="512" viewBox="0 0 512 512">
+  <rect x="36" y="36" width="440" height="440" rx="104" fill="#0B1220"/>
+  <rect x="37.5" y="37.5" width="437" height="437" rx="102.5" fill="none" stroke="#263248" stroke-width="3"/>
+  <rect x="104" y="138" width="304" height="236" rx="30" fill="#E9F0FF"/>
+  <path d="M104 184H408V168C408 151.4 394.6 138 378 138H134C117.4 138 104 151.4 104 168V184Z" fill="#C8D6F4"/>
+  <circle cx="142" cy="161" r="9" fill="#F05D67"/>
+  <circle cx="171" cy="161" r="9" fill="#F2B44B"/>
+  <circle cx="200" cy="161" r="9" fill="#39C980"/>
+  <rect x="226" y="151" width="146" height="20" rx="10" fill="#F7FAFF"/>
+  <rect x="128" y="210" width="256" height="140" rx="20" fill="#F7FAFF"/>
+  <path d="M232 244L304 280L232 316Z" fill="#5E79F7"/>
+  <circle cx="360" cy="358" r="50" fill="#F15B64"/>
+  <circle cx="360" cy="358" r="17" fill="#F7FAFF"/>
+</svg>
diff --git a/external_plugins/malo-browser/clients/python/README.md b/external_plugins/malo-browser/clients/python/README.md
new file mode 100644
index 00000000..28e722ee
--- /dev/null
+++ b/external_plugins/malo-browser/clients/python/README.md
@@ -0,0 +1,22 @@
+# Python client
+
+`malo_client.py` — zero-dependency (stdlib only) transport client for the malo
+daemon: on-demand daemon spawn, lease acquire/heartbeat/release, profile-backed
+sessions, tool calls, capability checks, and the profile login import
+(`import_profile_login`). Drop the file into any project, or add this directory
+to `sys.path` — the copy talks HTTP to a running daemon, but its auto-spawn
+derives the repo root from the file's own location (`malo_client.py` `MALO_REPO`),
+so a daemon that is not already running can only be spawned from a copy that
+still lives inside the repo (a copy placed elsewhere fails with a repo-path
+error; start the daemon from the repo first):
+
+```python
+from malo_client import acquire_lease, import_profile_login
+
+lease = acquire_lease("my-agent")
+import_profile_login(lease, "work", "http://127.0.0.1:9223", domains=["example.com"])
+with lease.new_session("work", profile="work") as s:
+    s.call("navigate", {"url": "https://example.com"})
+    print(s.call("snapshot", {"max_chars": 4000}))
+lease.release()
+```
diff --git a/external_plugins/malo-browser/clients/python/malo_client.py b/external_plugins/malo-browser/clients/python/malo_client.py
new file mode 100644
index 00000000..31d64d9d
--- /dev/null
+++ b/external_plugins/malo-browser/clients/python/malo_client.py
@@ -0,0 +1,288 @@
+#!/usr/bin/env python3
+"""malo-browser daemon 的 Python 传输层客户端（零第三方依赖）。
+
+malo daemon = 后台 Electron broker：127.0.0.1:7410 分发端口租约（7411-7499），
+session 工具走 HTTP（POST /v1/sessions/:id/tools/<tool>，双 token：lease+session）。
+本模块只管传输与生命周期：按需拉起 daemon、租约（心跳/释放）、session
+（profile 持久化登录态）、工具调用、capabilities 校验、profile 登录态导入。
+页面语义由调用方负责。
+
+用法：
+    from malo_client import acquire_lease
+    lease = acquire_lease("my-agent")
+    try:
+        with lease.new_session("work", profile="work") as s:
+            s.call("navigate", {"url": "https://example.com"})
+            print(s.call("snapshot", {"max_chars": 5000}))
+    finally:
+        lease.release()
+"""
+
+from __future__ import annotations
+
+import json
+import socket
+import subprocess
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+
+# 仓内自指：clients/python/ 的上上级即仓根（electron 与 out/main 都在这里）。
+MALO_REPO = Path(__file__).resolve().parent.parent.parent
+BROKER_JSON = Path.home() / ".malo-browser" / "broker.json"
+DEFAULT_BROKER_ENDPOINT = "http://127.0.0.1:7410"
+DEFAULT_LOG = Path.home() / ".malo-browser" / "daemon.log"
+# daemon 的 CDP 调试口：带上后 session 页即普通 CDP target，
+# Playwright connect_over_cdp 可直连（登录链等存量脚本的迁移通道）。
+DEFAULT_CDP_PORT = 9450
+
+# 每个客户端按需声明必需工具；缺失 = daemon 版本过旧，fail-loud 不降级。
+BASE_REQUIRED_TOOLS = ("navigate", "click", "fill", "snapshot", "assert", "close")
+
+
+class MaloError(RuntimeError):
+    """malo 链路失败（拉起/租约/工具），message 自带证据，不兜底。"""
+
+
+def _http(method: str, url: str, payload: dict | None = None,
+          headers: dict | None = None, timeout: float = 30) -> dict:
+    """一次 JSON HTTP 调用 → 解析后的 body；非 2xx 抛 MaloError（带响应体）。"""
+    data = json.dumps(payload).encode() if payload is not None else None
+    req = urllib.request.Request(url, data=data, method=method)
+    req.add_header("content-type", "application/json")
+    for k, v in (headers or {}).items():
+        req.add_header(k, v)
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            body = resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as e:
+        detail = e.read().decode("utf-8", errors="replace")[:500]
+        raise MaloError(f"malo HTTP {e.code} {url}: {detail}") from e
+    except (urllib.error.URLError, socket.timeout, ConnectionError) as e:
+        raise MaloError(f"malo 连不上 {url}: {type(e).__name__} {e}") from e
+    try:
+        return json.loads(body) if body else {}
+    except json.JSONDecodeError as e:
+        raise MaloError(f"malo 响应非 JSON {url}: {body[:200]}") from e
+
+
+def _port_open(endpoint: str, timeout: float = 2.0) -> bool:
+    try:
+        host = urllib.parse.urlsplit(endpoint).hostname or "127.0.0.1"
+        port = urllib.parse.urlsplit(endpoint).port or 80
+    except ValueError:
+        return False
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except OSError:
+        return False
+
+
+def _read_broker_json() -> dict:
+    try:
+        return json.loads(BROKER_JSON.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+
+
+def _spawn_daemon(started_by: str, log_path: Path, debug_port: int | None = None) -> None:
+    """后台拉起 daemon（detached，不抢焦点；日志追加到 log_path）。"""
+    electron = MALO_REPO / "node_modules" / ".bin" / "electron"
+    entry = MALO_REPO / "out" / "main" / "index.js"
+    for p, hint in ((electron, f"malo 仓未装依赖: {MALO_REPO}"),
+                    (entry, f"malo 未构建（out/main 缺失）: cd {MALO_REPO} && npm run build")):
+        if not p.exists():
+            raise MaloError(f"无法拉起 malo daemon——{hint}")
+    cmd = [str(electron), ".", "--mode=daemon"]
+    if debug_port:
+        cmd.append(f"--remote-debugging-port={debug_port}")
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    with log_path.open("a") as log:
+        log.write(f"\n===== {time.strftime('%Y-%m-%d %H:%M:%S')} spawn by {started_by} =====\n")
+        log.flush()
+        subprocess.Popen(
+            cmd, cwd=MALO_REPO,
+            stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT,
+            start_new_session=True)
+
+
+def ensure_daemon(wait_s: float = 60.0, log_path: Path | None = None,
+                  debug_port: int | None = None) -> dict:
+    """broker 就绪（健康复用/死了拉起）→ 返回 broker.json 内容（endpoint/token）。
+
+    debug_port：要求 daemon 带 CDP 调试口跑。daemon 活着但没带口时 fail-loud
+    （登录态在运行中的进程里，不静默杀进程重启——由调用方处置）。
+    """
+    info = _read_broker_json()
+    endpoint = info.get("endpoint") or DEFAULT_BROKER_ENDPOINT
+    broker_ok = _port_open(endpoint)
+    cdp_ok = debug_port is None or _port_open(f"http://127.0.0.1:{debug_port}")
+    if broker_ok and cdp_ok:
+        return info or {"endpoint": endpoint}
+    if broker_ok and not cdp_ok:
+        raise MaloError(
+            f"malo daemon 在跑（{endpoint}）但 CDP 调试口 {debug_port} 未开。"
+            f"该进程内可能挂着带登录态的 session，不自动杀；确认无需保留后执行："
+            f"pkill -f 'malo.*--mode=daemon' 再重跑（本次会带调试口拉起）。")
+    print(f"[malo] daemon 不在（{endpoint}），后台拉起（{MALO_REPO}）")
+    _spawn_daemon(started_by="python-client", log_path=log_path or DEFAULT_LOG,
+                  debug_port=debug_port)
+    deadline = time.time() + wait_s
+    while time.time() < deadline:
+        if _port_open(endpoint, timeout=1.0) and (
+            debug_port is None or _port_open(f"http://127.0.0.1:{debug_port}", timeout=1.0)
+        ):
+            # 新实例会重写 broker.json；端点通了但文件没刷新 = 异常，如实报
+            fresh = _read_broker_json()
+            if fresh.get("endpoint"):
+                return fresh
+        time.sleep(1.5)
+    tail = ""
+    try:
+        tail = (log_path or DEFAULT_LOG).read_text(encoding="utf-8")[-600:] if (log_path or DEFAULT_LOG).is_file() else "(无日志)"
+    except OSError:
+        tail = "(日志读失败)"
+    raise MaloError(f"malo daemon {wait_s:.0f}s 未就绪（{endpoint}）；启动日志尾:\n{tail}")
+
+
+def acquire_lease(agent_id: str, required_tools: tuple[str, ...] = BASE_REQUIRED_TOOLS,
+                  log_path: Path | None = None) -> "MaloLease":
+    """ensure daemon → 租约（同 agent_id 有效期内复用）→ capabilities 校验。"""
+    broker = ensure_daemon(log_path=log_path)
+    endpoint = broker.get("endpoint") or DEFAULT_BROKER_ENDPOINT
+    token = broker.get("token")
+    if not token:
+        raise MaloError(f"{BROKER_JSON} 缺 token（daemon 端点 {endpoint}），无法租约")
+    lease = _http("POST", f"{endpoint}/v1/leases",
+                  {"agent_id": agent_id}, {"x-malo-broker-token": token})
+    ml = MaloLease(endpoint=lease["endpoint"], token=lease["token"],
+                   lease_id=lease["lease_id"], agent_id=agent_id,
+                   broker_endpoint=endpoint, broker_token=token)
+    ml.check_capabilities(required_tools)
+    return ml
+
+
+def import_profile_login(lease: "MaloLease", profile: str, cdp_url: str,
+                         domains: list[str] | None = None,
+                         session_cookie_ttl_days: int = 180) -> dict:
+    """把源 Chromium（回环 CDP 端点）的 cookies 热导入 malo profile。
+
+    返回 {cookies_total/cookies_matched/cookies_written/cookies_failed/...}；
+    源连不上抛 MaloError(502 E_IMPORT_SOURCE_UNREACHABLE)，0 条命中抛 400。
+    """
+    body: dict = {"cdp_url": cdp_url, "session_cookie_ttl_days": session_cookie_ttl_days}
+    if domains:
+        body["domains"] = domains
+    return lease._post(f"/v1/profiles/{profile}/import", body)
+
+
+def open_session(agent_id: str, url: str, profile: str | None = None,
+                 debug_port: int | None = DEFAULT_CDP_PORT,
+                 required_tools: tuple[str, ...] = BASE_REQUIRED_TOOLS,
+                 log_path: Path | None = None,
+                 settle_ms: int = 3000,
+                 width: int = 1440, height: int = 900) -> tuple["MaloLease", "MaloSession"]:
+    """一步到位：拉起带 CDP 调试口的 daemon → 租约 → profile 会话 → 导航到 url。
+
+    返回 (lease, session)；调用方 finally 里 session.close() + lease.release()
+    （登录态已沉淀 profile，收尾失败不影响）。导航结果 ok:false 时抛 MaloError。
+    Playwright 直连调试口（http://127.0.0.1:<debug_port>）可继续驱动该会话页。
+    width/height 是会话视口（CSS 内容区，录制场景按 16:9 给）。
+    """
+    ensure_daemon(log_path=log_path, debug_port=debug_port)
+    lease = acquire_lease(agent_id, required_tools=required_tools, log_path=log_path)
+    try:
+        session = lease.new_session(f"{profile or 'anon'}-session", profile=profile,
+                                    width=width, height=height)
+        r = session.call("navigate", {"url": url, "timeout_ms": 45_000,
+                                      "settle_ms": settle_ms})
+        if isinstance(r, dict) and r.get("ok") is False:
+            raise MaloError(f"malo 会话导航失败（{url}）：{str(r)[:300]}")
+        return lease, session
+    except Exception:
+        lease.release()
+        raise
+
+
+class MaloLease:
+    """一个端口租约：心跳续租、session 生命周期、工具调用入口。"""
+
+    def __init__(self, endpoint: str, token: str, lease_id: str, agent_id: str,
+                 broker_endpoint: str, broker_token: str):
+        self.endpoint = endpoint          # lease 端口，如 http://127.0.0.1:7411
+        self.token = token                # lease token
+        self.lease_id = lease_id
+        self.agent_id = agent_id
+        self._headers = {"x-malo-lease-token": token}
+        self._broker = (broker_endpoint, broker_token)
+
+    def check_capabilities(self, required: tuple[str, ...] = BASE_REQUIRED_TOOLS) -> None:
+        names = {t.get("name") for t in self._get("/v1/tools").get("tools", [])}
+        missing = [t for t in required if t not in names]
+        if missing:
+            raise MaloError(f"运行中的 malo daemon 缺工具 {missing}（版本过旧），"
+                            f"需升级 {MALO_REPO} 并重启 daemon")
+
+    def heartbeat(self) -> None:
+        # 心跳/释放都是 broker 路由（lease 端口只挂 session 工具）
+        be, bt = self._broker
+        _http("POST", f"{be}/v1/leases/{self.lease_id}/heartbeat",
+              None, {"x-malo-broker-token": bt})
+
+    def release(self) -> None:
+        # 释放是 broker 路由（lease 端口没有 DELETE /v1/leases/:id）
+        be, bt = self._broker
+        try:
+            _http("DELETE", f"{be}/v1/leases/{self.lease_id}",
+                  None, {"x-malo-broker-token": bt})
+        except MaloError as e:  # 收尾清理性失败不掩盖主流程结果
+            print(f"[malo] ⚠️ 租约释放失败（不影响本次产出）：{e}")
+
+    def new_session(self, name: str, profile: str | None = None,
+                    width: int = 1440, height: int = 900) -> "MaloSession":
+        body = {"name": name, "width": width, "height": height}
+        if profile:
+            body["profile"] = profile
+        r = self._post("/v1/sessions", body)
+        return MaloSession(self, r["session_id"], r["session_token"])
+
+    def _get(self, path: str) -> dict:
+        return _http("GET", f"{self.endpoint}{path}", None, self._headers)
+
+    def _post(self, path: str, payload: dict) -> dict:
+        return _http("POST", f"{self.endpoint}{path}", payload, self._headers)
+
+
+class MaloSession:
+    """一个浏览 session（同名 profile 跨 session 复用 cookies/登录态）。"""
+
+    def __init__(self, lease: MaloLease, session_id: str, session_token: str):
+        self.lease = lease
+        self.id = session_id
+        self._headers = {**lease._headers, "x-malo-session-token": session_token}
+
+    def call(self, tool: str, payload: dict | None = None,
+             timeout: float = 120) -> dict:
+        """调 session 工具 → result 字段；HTTP 层失败抛 MaloError。
+
+        注意：业务失败（如 assert 不成立）是 HTTP 200 + result.ok=false，
+        由调用方读语义，本层不吞不判。
+        """
+        r = _http("POST", f"{self.lease.endpoint}/v1/sessions/{self.id}/tools/{tool}",
+                  payload or {}, self._headers, timeout=timeout)
+        return r.get("result", r)
+
+    def close(self) -> None:
+        try:
+            self.call("close")
+        except MaloError as e:
+            print(f"[malo] ⚠️ session 关闭失败（登录态已在 profile，不影响）：{e}")
+
+    def __enter__(self) -> "MaloSession":
+        return self
+
+    def __exit__(self, *exc) -> None:
+        self.close()
diff --git a/external_plugins/malo-browser/cordis.patch.yml b/external_plugins/malo-browser/cordis.patch.yml
new file mode 100644
index 00000000..ed269234
--- /dev/null
+++ b/external_plugins/malo-browser/cordis.patch.yml
@@ -0,0 +1,3 @@
+- insert:
+    - id: malo-browser
+      name: malo-browser
diff --git a/external_plugins/malo-browser/docs/accounts.md b/external_plugins/malo-browser/docs/accounts.md
new file mode 100644
index 00000000..f44785e8
--- /dev/null
+++ b/external_plugins/malo-browser/docs/accounts.md
@@ -0,0 +1,127 @@
+# 账号登录
+
+`login` 动作让场景在录制前打开登录页、填写账号、提交，并等待明确的成功条件。
+场景只保存账号 ID；用户名、选择器和密码环境变量保存在仓库外的本地账户文件中。
+
+## 1. 创建账户文件
+
+默认路径是 `~/.config/malo-browser/accounts.json`，可用
+`MALO_BROWSER_ACCOUNTS` 指向其他位置。文件必须：
+
+- 位于 git worktree 之外；loader 会拒绝仓库内路径
+- 权限为 `0600`；group/world readable/writable 会直接失败
+- 是普通文件，不是符号链接
+- `origin` 与 `login_url` 必须同源
+- `success_selector` 或 `success_url` 至少配置一个
+- 只允许已知字段；明文 `password` 字段会被拒绝
+
+```json
+{
+  "schema_version": 1,
+  "accounts": {
+    "work-demo": {
+      "origin": "https://app.example.com",
+      "login_url": "https://app.example.com/login",
+      "username": "demo@example.com",
+      "password_env": "WORK_DEMO_PASSWORD",
+      "username_selector": "input[name=email]",
+      "password_selector": "input[name=password]",
+      "submit_selector": "button[type=submit]",
+      "success_selector": "[data-testid=dashboard]"
+    }
+  }
+}
+```
+
+```bash
+install -d -m 700 ~/.config/malo-browser
+chmod 600 ~/.config/malo-browser/accounts.json
+```
+
+密码只通过 `password_env` 指向的环境变量传入。不要写进场景、账户 JSON、
+命令行参数或 shell 历史：
+
+```bash
+read -rs WORK_DEMO_PASSWORD
+export WORK_DEMO_PASSWORD
+export MALO_BROWSER_ACCOUNTS="$HOME/.config/malo-browser/accounts.json"
+```
+
+## 2. 在场景中登录
+
+```yaml
+steps:
+  - id: sign-in
+    action: login
+    account_id: work-demo
+    timeout_ms: 15000
+```
+
+`login` 按以下顺序执行，任一步失败都会停止：
+
+1. 加载账户配置并解析 `password_env`
+2. 确认登录地址在当前场景的 `allow` 安全边界内
+3. 打开登录页，并在输入前再次核对页面来源
+4. 等待用户名、密码和提交按钮可见
+5. 通过真实鼠标/键盘事件填写并提交
+6. 等待 `success_selector` 或 `success_url`
+
+录制证据中的步骤详情固定为 `signed in with account "<account_id>"`。密码不会进入
+场景变量、Runner 快照、SSE、错误详情或 evidence JSON；账户文件中的用户名和
+`password_env` 也不会出现在步骤详情中。
+
+## 3. 本地证明场景
+
+仓库内置 `fixtures/scenes/login-demo`，使用真实 DOM 表单和 `demo://` 页面。
+账户文件中的 `fixture` 项可以用以下值：
+
+```json
+{
+  "schema_version": 1,
+  "accounts": {
+    "fixture": {
+      "origin": "demo://scene/login-demo",
+      "login_url": "demo://scene/login-demo/index.html",
+      "username": "demo@example.test",
+      "password_env": "MALO_BROWSER_FIXTURE_PASSWORD",
+      "username_selector": "input[name=email]",
+      "password_selector": "input[name=password]",
+      "submit_selector": "button[type=submit]",
+      "success_selector": "#signed-in"
+    }
+  }
+}
+```
+
+```bash
+MALO_BROWSER_ACCOUNTS=/path/outside/git/accounts.json \
+MALO_BROWSER_FIXTURE_PASSWORD="fixture-only" \
+npx electron . --mode=app --autorun=login-demo \
+  --scenes=fixtures/scenes --out=evidence --headless=true
+```
+
+成功时 stdout 输出 `{"status":"passed",...}`，录制目录中的 evidence 包含：
+
+```json
+{
+  "action": "login",
+  "status": "passed",
+  "detail": "signed in with account \"fixture\""
+}
+```
+
+## 4. 失败排查
+
+| 错误 / 现象 | 原因 | 修复 |
+|---|---|---|
+| `E_ACCOUNT_NOT_FOUND` | 账户文件不存在，或 `account_id` 不在文件中 | 检查 `MALO_BROWSER_ACCOUNTS` 与报错列出的 `available` ID |
+| `E_ACCOUNT_INVALID` + `0600` | 文件权限过宽 | `chmod 600 <accounts.json>` |
+| `E_ACCOUNT_INVALID` + `outside a git worktree` | 账户文件放在仓库内 | 移到 `~/.config/malo-browser/` 等仓库外位置 |
+| `E_ACCOUNT_INVALID` + `same origin` | `origin` 与 `login_url` 不同源 | 使用目标站点的同一 origin；SSO 跳转当前不支持 |
+| `E_ACCOUNT_INVALID` + `environment variable` | `password_env` 没有值 | 在启动 Electron 的同一 shell 中导出该变量 |
+| `E_ACCOUNT_INVALID` + `moved from` | 登录页导航到了其他来源 | 检查重定向；动作会在输入任何凭据前停止 |
+| `E_NAV_BLOCKED` | 登录页不在场景 `allow` 中 | 把登录页 origin 加入场景 `allow` |
+| `E_STEP_TIMEOUT` / `E_SELECTOR_NOT_FOUND` | 字段或成功条件选择器不匹配 | 检查四个 selector；必要时改用 `success_url` |
+
+当前边界：不处理 MFA、CAPTCHA、跨源 SSO 跳转、登录重试或多步验证码。每个账号只做
+一次确定性尝试，不会因超时自动重复提交。
diff --git a/external_plugins/malo-browser/docs/malo-browser.md b/external_plugins/malo-browser/docs/malo-browser.md
new file mode 100644
index 00000000..f0764b08
--- /dev/null
+++ b/external_plugins/malo-browser/docs/malo-browser.md
@@ -0,0 +1,500 @@
+# malo-browser
+
+malo-browser 是给 agent 用的 Web 执行层：一个常驻后台 daemon 向多个 agent 分发端口租约，
+每个租约下可以创建多个互相隔离的浏览 session。它不是人类主浏览器，也不要求有可见窗口。
+
+当前版本是 v0.1，先验证四件事：
+
+- 多 agent 各自拿到稳定端口，不互相抢
+- 同一端口下多 session 的 cookies、页面、下载和日志互不串用
+- 默认后台运行，不抢焦点、不抢屏、不切换 Space
+- agent 能通过 HTTP 完成导航、轻量观察、按需截图和基础动作
+
+## 启动
+
+```bash
+npm run build
+npm run daemon
+```
+
+默认监听：
+
+- broker：`127.0.0.1:7410`
+- lease 端口池：`7411-7499`
+- 数据目录：`~/.malo-browser`
+
+启动成功后会打印一行 JSON，并写入 `~/.malo-browser/broker.json`（权限 `0600`）：
+
+```json
+{
+  "endpoint": "http://127.0.0.1:7410",
+  "token": "<broker-token>",
+  "pid": 1234
+}
+```
+
+常用参数：
+
+```bash
+electron . --mode=daemon \
+  --daemon-port=7410 \
+  --port-min=7411 \
+  --port-max=7499 \
+  --lease-ttl-seconds=300 \
+  --session-idle-seconds=300 \
+  --max-sessions=4 \
+  --data-dir=~/.malo-browser
+```
+
+同一个数据目录只允许一个 daemon。已有实例仍健康时，新进程会明确报错，不会抢占端口。
+已停止实例留下的 `broker.json` 会被识别为陈旧文件并覆盖。
+
+## 端口租约
+
+Broker 管理端口池和租约表。每个 agent 申请一个租约：
+
+```bash
+curl -X POST http://127.0.0.1:7410/v1/leases \
+  -H "x-malo-broker-token: $BROKER_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"agent_id":"agent-a"}'
+```
+
+```json
+{
+  "lease_id": "lease-...",
+  "agent_id": "agent-a",
+  "endpoint": "http://127.0.0.1:7411",
+  "token": "<lease-token>",
+  "expires_at": "2026-11-03T10:00:00.000Z"
+}
+```
+
+规则：
+
+- 同一 `agent_id` 在租约有效期内重复申请会复用原租约
+- 每个 lease 有独立 token，端口只绑定 `127.0.0.1`
+- 心跳续租：`POST /v1/leases/:id/heartbeat`
+- 主动释放：`DELETE /v1/leases/:id`
+- 过期租约由 daemon 自动回收，端口归还端口池
+- 释放或过期会关闭该租约下所有 session
+
+## Session
+
+Lease endpoint 使用 lease token：
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/sessions \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"name":"research","width":1280,"height":800,"profile":"work"}'
+```
+
+创建结果会返回一次 `session_token`。后续访问该 session 必须同时带 lease token 和
+session token；拿 session A 的 token 访问 session B 会返回 401。
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/sessions/$SESSION_ID/navigate \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "x-malo-session-token: $SESSION_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"url":"https://example.com","settle_ms":6000}'
+```
+
+默认每个 session 使用独立的 persistent partition、下载目录和产物目录；指定 `profile`
+的 session 共用该 profile 的 partition（见下节）：
+
+```text
+<data-dir>/leases/<lease-id>/sessions/<session-id>/
+  downloads/
+  artifacts/
+```
+
+`width` / `height` 是页面视口尺寸：人工接管窗口顶部的工具条不占用这两个值，截图也是
+`width` x `height`（乘以 DPR）。
+
+## 登录态 profile
+
+默认 session 是匿名的：关闭时清空 cookies 和 storage，下次要重新登录。
+需要跨 session、跨 daemon 重启保留登录态时，创建 session 时显式指定 `profile`：
+
+```json
+{ "name": "research", "profile": "work" }
+```
+
+- profile 存在 `<data-dir>/chromium/Partitions/malo-profile-<name>`（Electron 分区的
+  `persist:` 前缀不进入目录名），daemon 的 Chromium 用户数据整体落在 `<data-dir>/chromium`，
+  一个目录管住全部状态
+- 只接受小写字母、数字、点、下划线、短横线，最长 64 字符；最多 64 个 profile
+- 同名 profile 会被多个 session 共享，因此并行 agent 各自用自己的名字，例如 `agent-a.work`
+- 未指定 profile 的 session 行为不变：关闭即清空，不会继承任何登录态
+- `login` 结果和 session summary 都带 `profile` 字段，agent 能确认这次登录是否可复用
+
+查询与清理：
+
+```bash
+curl -H "x-malo-lease-token: $LEASE_TOKEN" http://127.0.0.1:7411/v1/profiles
+curl -X DELETE -H "x-malo-lease-token: $LEASE_TOKEN" \
+  http://127.0.0.1:7411/v1/profiles/work
+```
+
+清理正在被 session 使用的 profile 会返回 409 `E_PROFILE_LOCKED`，先关闭这些 session。
+工具调用里同样可用 `profiles`（`{"action":"list"}` / `{"action":"clear","name":"work"}`）。
+
+从已登录的 Chromium 导入登录态：`POST /v1/profiles/:name/import` 连源浏览器回环
+`cdp_url` 的 DevTools 端点实时拉 cookie，写进该 profile 的分区；可选 `domains` 白名单
+与 `session_cookie_ttl_days`（默认 180）。导入只合并不清空已有状态，也只迁 cookie
+（localStorage / IndexedDB 留在源浏览器）；源浏览器连不上 → 502
+`E_IMPORT_SOURCE_UNREACHABLE`，域过滤后 0 条 → 400 `E_IMPORT_EMPTY`：
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/profiles/work/import \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"cdp_url":"http://127.0.0.1:9223","domains":["example.com"]}'
+```
+
+## Agent 工具
+
+Agent 不需要自己猜接口。lease endpoint 提供一份工具清单：
+
+```bash
+curl -H "x-malo-lease-token: $LEASE_TOKEN" \
+  http://127.0.0.1:7411/v1/tools
+```
+
+每个工具带 JSON Schema，可直接映射到 function calling / MCP 工具定义。统一调用入口：
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/sessions/$SESSION_ID/tools/snapshot \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "x-malo-session-token: $SESSION_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"max_chars":8000,"max_items":120}'
+```
+
+可用工具：
+
+- `navigate`、`history`、`events`
+- `observe`、`snapshot`、`extract`
+- `click`、`fill`、`upload_file`、`press`、`hover`、`select`、`focus`
+- `scroll`、`scroll_into_view`、`wait_for`、`sleep`
+- `assert`（visible / hidden / text / value / url / count）
+- `run_steps`（批量串行执行上面的工具，产出 run report 文件）
+- `network_capture`（设置/查看 XHR/fetch 响应体捕获订阅）
+- `responses`（按 seq 游标查询捕获到的响应）
+- `watch`、`login`、`profiles`
+- `close`
+
+`snapshot` 是 agent 看页面的主工具，返回：
+
+- 可见正文、标题、viewport 和滚动位置
+- 标题、链接、按钮、输入框、下拉框、表单
+- 表格、landmark、iframe、dialog、alert/live region
+- 可交互元素及稳定的 CSS selector、坐标和尺寸
+- `truncated` 标记，明确哪些内容被截断
+
+`extract` 用于定向读取：
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/sessions/$SESSION_ID/tools/extract \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "x-malo-session-token: $SESSION_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"selector":".price","mode":"text","max_chars":4000}'
+```
+
+`assert` 用于验证，所有条件按 AND 组合，并在 `timeout_ms` 内反复重试。断言没通过是业务
+判决而不是服务故障：HTTP 状态仍是 **200**，判决在 `result.ok` 上——通过时 `result.ok`
+与 `result.passed` 为 `true`；失败时两者为 `false`，`result.checks` 与
+`result.error.details.checks` 带每项 expected/actual，`result.screenshot` /
+`result.error.details.screenshotPath` 指向 session `artifacts/` 下的失败截图，
+`result.error.code` 为 `E_ASSERTION_FAILED`。参数错误仍是 4xx，服务内部异常仍是 5xx
+（0.1.2 起；此前 assert 失败返回 500）：
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/sessions/$SESSION_ID/tools/assert \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "x-malo-session-token: $SESSION_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"visible":"#done","hidden":"#spinner","text":"保存成功","url":"/done","timeout_ms":5000}'
+```
+
+```json
+{
+  "tool": "assert",
+  "result": {
+    "ok": false,
+    "passed": false,
+    "checks": [{ "kind": "visible", "expected": true, "actual": false, "ok": false }],
+    "url": "https://example.com/done",
+    "waited_ms": 5001,
+    "screenshot": "<artifacts>/failure-<ms>.png",
+    "error": {
+      "code": "E_ASSERTION_FAILED",
+      "message": "E_ASSERTION_FAILED: 断言失败：visible expected true, got false",
+      "details": {
+        "checks": [{ "kind": "visible", "expected": true, "actual": false, "ok": false }],
+        "waited_ms": 5001,
+        "screenshotPath": "<artifacts>/failure-<ms>.png"
+      }
+    }
+  }
+}
+```
+
+`selector` 在 `assert` 里有两个用途：给 `text` 限定查找范围，或作为 `value` / `count`
+的目标。对密码输入框做 `value` 断言会直接返回 400（密码值永远读不到，拿脱敏串比较只会
+假通过），改用 `visible` 或页面上的登录态断言。
+
+`run_steps` 把一串工具调用交给 daemon 顺序执行，默认遇错即停（`stop_on_failure:false`
+可继续），最后把每一步的结果与错误写进 session `artifacts/` 下的 run report，
+返回 `{ ok, step_count, failed_step, steps, report_path }`。`run_steps`、`watch`、`login`、
+`profiles`、`close`、`network_capture`、`responses` 都不能再嵌进 `run_steps`（响应体永远
+不进 run report）。
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/sessions/$SESSION_ID/tools/run_steps \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "x-malo-session-token: $SESSION_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"steps":[{"type":"click","selector":"#save"},{"type":"assert","text":"保存成功"}]}'
+```
+
+工具调用返回 `{ "tool": "...", "result": ... }`；协议/参数错误返回
+`{ "ok": false, "error": { "code", "message", "details" } }`，服务内部异常为 5xx。
+业务判决失败（`assert` 未通过、`run_steps` 有失败步骤）仍是 200，读 `result.ok`。
+导航失败会在 `details.navigation` 中带 `http_status`、`net_error`、`net_error_description` 和 `settle` 信息。
+
+旧版 `x-pagehand-*` token 头仍被接受一段时间，新脚本请使用 `x-malo-*`。
+
+### 网络响应捕获（XHR / fetch）
+
+`network_capture` 声明关心的 URL 前缀，`responses` 取回命中的响应体。文档化的时序是
+先订阅、再导航、再触发交互，最后按 `seq` 轮询：
+
+```bash
+BASE=http://127.0.0.1:7411
+SESSION=/v1/sessions/$SESSION_ID/tools
+AUTH=(-H "x-malo-lease-token: $LEASE_TOKEN" -H "x-malo-session-token: $SESSION_TOKEN" -H "content-type: application/json")
+
+# 1) 订阅（替换式；空数组=清空，省略=只查看）
+curl -X POST "$BASE$SESSION/network_capture" "${AUTH[@]}" \
+  -d '{"url_prefixes":["https://web-api.example.com/api/v1/action/"]}'
+
+# 2) 导航
+curl -X POST "$BASE/v1/sessions/$SESSION_ID/navigate" \
+  -H "x-malo-lease-token: $LEASE_TOKEN" -H "x-malo-session-token: $SESSION_TOKEN" \
+  -H "content-type: application/json" -d '{"url":"https://example.com/action/2026-11-05"}'
+
+# 3) 触发请求（标签、按钮等）
+curl -X POST "$BASE$SESSION/click" "${AUTH[@]}" -d '{"selector":"#tab-theme"}'
+
+# 4) 轮询；body_error=pending 表示 body 还在串行队列里，稍后再查
+curl -X POST "$BASE$SESSION/responses" "${AUTH[@]}" \
+  -d '{"url_prefix":"https://web-api.example.com/api/v1/action/","after":0,"limit":50}'
+```
+
+订阅语义：
+
+- `network_capture` 省略 `url_prefixes` 只返回当前订阅和已保留 body 的条数
+  （`{"url_prefixes":[],"captured":0}`）；`[]` 清空订阅并关闭 CDP 网络域。
+- 首次设置非空前缀时才发 `Network.enable`，并带 `maxTotalBufferSize=64 MiB`、
+  `maxResourceBufferSize=8 MiB`——不带这两个值，大响应体会取不到，看起来像页面把缓冲
+  淘汰了。清空订阅时发 `Network.disable`，丢弃已缓存 body，元数据保留。
+- 订阅是 session 私有的，关闭 session 即失效，不写 profile，不影响其他 session。
+- 捕获复用 `ElectronPageDriver` 已有的 debugger 附着，不会二次 attach，也不引入任何
+  窗口/焦点行为。
+
+`responses` 入参 `url_prefix`（结果过滤）、`after`（取 `seq` 大于它的记录）、`limit`
+（1–200，默认 50），返回 `{"responses":[record],"has_more":bool}`。`has_more` 表示还有
+未返回的匹配记录——故意不叫 `truncated`，避免和单条 body 的 `body_truncated` 混淆。
+record 形态：
+
+```json
+{
+  "seq": 12,
+  "url": "https://web-api.example.com/api/v1/action/field?x=1",
+  "status": 200,
+  "mime_type": "application/json",
+  "resource_type": "XHR",
+  "body": "{\"errCode\":\"0\"}",
+  "body_truncated": false,
+  "body_error": null
+}
+```
+
+`body` 是原始文本，不替调用方解析 JSON；`body_truncated=true` 表示超过单条 **1 MiB**
+上限、只保留前 1 MiB。`body_error` 只在 `body=null` 时出现，如实标注原因，绝不造空成功：
+
+| 值 | 含义 |
+|---|---|
+| `not_subscribed` | 未命中订阅，只记元数据 |
+| `no_body` | 204/304 或空响应体（合法态） |
+| `evicted` | 被 200 条 captured 上限或 16 MiB 字节预算挤出 |
+| `pending` | body 仍在串行队列里；调用方稍后重试 `responses` |
+| `binary` | `Network.getResponseBody` 返回 base64（二进制），不按 UTF-8 解码 |
+| `getResponseBody_failed: <原因>` | CDP 取 body 失败（如导航离开后缓冲已清），不重试 |
+| `too_large` | 契约保留值；当前实现对超限 body 截断，不会返回此值 |
+
+内存模型：所有 resource type 都记元数据，可见列表最多 **500 条**（一页图片不会把后来的
+JSON 元数据挤掉）；body 只为订阅命中的响应保留，最多 **200 条**且总字节预算 **16 MiB**，
+超限时最老的 body 先丢、元数据保留并标 `body_error="evicted"`。`responses` 的 `limit`
+仍是 1–200。body 只存在于 daemon 内存和 `responses` 的返回值中，不写日志、
+`evidence/*.json`、trace 或 run report，也不进 `MaloNetworkInfo`。
+
+捕获子系统自身故障（`Network.enable` / `Network.disable` 被拒等）会让
+`network_capture` / `responses` 返回显式的 `E_CAPTURE_UNAVAILABLE` 错误（HTTP 5xx、
+`ok:false`），不会伪装成空列表；空列表只表示真的没有匹配记录。
+
+限制：CDP session 附着在页面 target 上，所以请求由跨进程 iframe（OOPIF）或 service
+worker 发出时不会被捕获。这是刻意划定的范围，不是 bug；需要时改用页面主 frame 发起
+等价请求。
+
+## 观察
+
+默认只取轻量状态，不生成截图：
+
+```bash
+GET /v1/sessions/:id/observe?mode=light&max_chars=2000
+```
+
+返回 URL、title、readyState、viewport、DOM 元素数量、可交互元素数量和正文摘要。
+
+需要视觉证据时显式请求截图：
+
+```bash
+GET /v1/sessions/:id/observe?mode=screenshot&max_chars=200
+```
+
+截图是 base64 PNG。动作失败时同时会在 session 的 `artifacts/` 下落一张失败截图。
+malo-browser 不默认连续推流，也不默认每步截图。
+
+导航默认会等待 DOM 和网络稳定，`settle_ms` 是等待上限。Reddit 的 JS challenge、
+Three.js 的异步列表这类页面不能只等 `load` 事件；`navigation.settle` 会明确记录等待时长、
+最终 DOM 元素数和稳定采样数。站点兼容性实测见
+[malo-web-compat.md](malo-web-compat.md)。
+
+## 动作
+
+```bash
+curl -X POST http://127.0.0.1:7411/v1/sessions/$SESSION_ID/actions \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "x-malo-session-token: $SESSION_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"action":{"type":"fill","selector":"#q","text":"hello"}}'
+```
+
+v0.1 支持：
+
+- `click`：`selector` 或 `x`/`y`
+- `fill`：`selector`、`text`、可选 `clear`
+- `press`：`key` 和可选 `modifiers`
+- `scroll`：`dx`、`dy`
+- `hover`：`selector` 或 `x`/`y`
+- `select`：`selector` + `value` 或 `label`
+- `focus`：`selector`
+- `scroll_into_view`：`selector`
+- `history`：`back` / `forward` / `reload`
+- `wait_for`：`selector` 或 `text`，可选 `state`、`timeout_ms`
+- `sleep`：`ms`
+
+Meta/Command 快捷键中的 `Cmd+A/C/V/X/Z` 会映射到 Electron 的编辑命令，避免合成系统级按键；
+其他 Meta 组合会明确返回 `E_UNSUPPORTED`。
+
+动作和页面事件可以从 `GET /v1/sessions/:id/events?after=<seq>` 读取。
+
+## 登录交接
+
+登录墙、扫码和人机校验不该让 agent 硬碰。malo 把「人接手一次、agent 拿回控制权」做成契约：
+
+```bash
+# 账号密码：agent 提供一次性凭据
+curl -X POST http://127.0.0.1:7411/v1/sessions/$SESSION_ID/tools/login \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "x-malo-session-token: $SESSION_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"mode":"password","username":"demo","password":"secret"}'
+
+# 人工接管：窗口拉给人看，扫码或点确认后自动收回
+curl -X POST http://127.0.0.1:7411/v1/sessions/$SESSION_ID/tools/watch \
+  -H "x-malo-lease-token: $LEASE_TOKEN" \
+  -H "x-malo-session-token: $SESSION_TOKEN" \
+  -H "content-type: application/json" \
+  -d '{"show":true,"focus":false}'
+
+curl -X POST http://127.0.0.1:7411/v1/sessions/$SESSION_ID/tools/login \
+  -d '{"mode":"watch","timeout_ms":180000}'
+```
+
+规则：
+
+- 默认 `focus=false`，窗口用 `showInactive` 出现：不抢键盘焦点、不切换 Space；只有显式 `focus:true` 才上前台
+- `password` 模式自动识别用户名、密码和提交按钮，可用 `username_selector`、`password_selector`、`submit_selector` 覆盖
+- 成功判定是**互斥**的：给了 `success_selector` 就只看它，给了 `success_url_contains` 就只看 URL；
+  两者都没给才退回「密码框消失 / URL 变化 / 页面出现退出登录等文本」的启发式
+- 失败判定看 `error_selector` 或页面上的常见错误文案，返回 `reason=login_error` 而不是空转重试
+- 凭据只存在于本次调用内存：不落盘、不进事件、不回显；快照里密码框的 `value` 固定为空串并标记 `sensitive: true`（`[redacted]` 只出现在 `interactive[].text`）
+- 登录态只有指定 `profile` 时才保留，未指定就随 session 一起清掉
+- `login` 成功后窗口自动隐藏，agent 继续用同一个 session；`keep_visible: true` 可留给人继续操作；`watch` 打开的窗口保持可见，显式再调 `watch`（`show:false`）才收起
+- 超时的人工接管窗口不会自动关闭，人处理完再调 `watch` 收起
+
+## 安全与资源边界
+
+- 只监听回环地址
+- `Host` 只接受 `127.0.0.1:<port>` 和 `localhost:<port>`，防 DNS rebinding
+- broker token、lease token、session token 三层分离
+- 只允许 `http:` / `https:` 导航，拒绝 URL 内嵌 credentials
+- `window.open` 默认拒绝，权限请求默认拒绝
+- 请求体上限 1MB，只接受 `application/json`
+- 每 lease 默认最多 4 个 session；超出返回 429
+- 空闲 session 默认 300 秒回收
+- 不同 session 的 cookies、storage、下载、页面和事件互不共享；共享 profile 的多个
+  session 之间，下载仍按发起它的 webContents 归属到各自 session 的 `downloads/`
+- 数据目录与 session 目录按 0700 建立，`broker.json` / `profiles.json` / 失败截图 /
+  run report 一律 0600；录制成片同样 0600
+- `profile` 是显式共享单元：同名 profile 的 session 共用 cookies，名字由调用方自己隔离
+- profile 数据只落在 `<data-dir>/chromium`，清理走 `DELETE /v1/profiles/:name`
+- 匿名 session 关闭时会清空 storage 并删除自己的 partition 目录，不留在磁盘上
+
+## 焦点与窗口
+
+daemon 在 macOS 使用 `accessory` 激活策略并隐藏 Dock，不创建可见窗口，不编程激活应用、
+不切换 Space。session 的 `WebContentsView` 放在隐藏 `BaseWindow` 中，系统窗口列表中
+`onscreen=false`。人眼可见的窗口（`watch` / `login` 接管窗口）出现期间，Dock 会临时亮出
+图标，被别的应用挡住的窗口点 Dock 图标即可调回最前——这是唯一的前台切换，且由用户点击
+触发；窗口全部收起后图标自动隐藏，纯后台期间仍然无图标。
+
+需要给人看的时候才进入 `watch` / `login`，其余时间只有隐藏窗口和按需截图。
+人工接管窗口带原生标题栏，可以拖动和缩放，顶部还有一条浏览器工具条：后退、前进、
+刷新和地址栏（只接受 `http` / `https`，回车跳转，地址随页面同步）；录制与演示舞台
+仍然是无边框窗口，也没有这条工具条。
+
+## 验证
+
+```bash
+npm run typecheck
+npm test
+
+# 先起 fixture 静态服务
+python3 -m http.server 4788 --bind 127.0.0.1 --directory out/fixture
+
+# 另一个终端起 daemon，然后跑完整链路 smoke
+#（smoke 会自己起一个临时登录测试页，不依赖仓库里的 HTML）
+npm run smoke:malo -- ~/.malo-browser/broker.json http://127.0.0.1:4788
+```
+
+smoke 覆盖两个 agent、三个 session、导航隔离、轻量观察、截图、工具清单、
+snapshot/extract、fill/click/hover/focus/history、session token 越权拒绝、
+账号密码登录与错误凭据、人工接管登录、密码不回显/不入事件、
+profile 登录态恢复与匿名 session 隔离、
+session 关闭、lease 释放和端口归还。
+
+## v0.1 不做
+
+- 把整个仓库或包名改成 malo-browser
+- delivery-video adapter 拆分
+- 新的 1080p capture 实现
+- 把登录页做成可定制的站点适配层
+- 审批流、远程访问、跨用户服务化
+- 书签、标签栏、多标签页等人类浏览器功能（人工接管窗口只有地址栏与后退/前进/刷新）
diff --git a/external_plugins/malo-browser/docs/malo-web-compat.md b/external_plugins/malo-browser/docs/malo-web-compat.md
new file mode 100644
index 00000000..20297aef
--- /dev/null
+++ b/external_plugins/malo-browser/docs/malo-web-compat.md
@@ -0,0 +1,55 @@
+# malo-browser 真实站点兼容性调研
+
+日期：2026-11-03；范围：无头 session、单页顶层加载、每站一次、不重试、不登录、不处理验证码。
+
+## 结论
+
+- 12 个代表性站点（静态页、SPA、搜索、电商、视频、WebGL、地图库）中 9 个能正常加载并观察；
+  1 个是登录墙，1 个是网络层不可达，1 个是站点侧 HTTP 403 + 人机校验。
+- 异步页面必须等 DOM/网络稳定，不能只等 `load`；JS challenge 不一定是拦截，可能只是二次导航。
+- 登录墙、滑块/验证码、IP 级反爬必须显式识别（`login-wall` / `challenge` / `network-error`），
+  不能伪装成功。
+
+## 复现
+
+```bash
+python3 -m http.server 4788 --bind 127.0.0.1 --directory out/fixture
+npm run daemon
+
+MALO_BROKER_FILE=~/.malo-browser/broker.json \
+MALO_PROBE_INTERVAL_MS=8000 \
+MALO_PROBE_TIMEOUT_MS=25000 \
+node scripts/malo-web-probe.mjs
+```
+
+## 关键发现
+
+### 1. “加载完成”不等于“页面稳定”
+
+`document.readyState === "complete"` 只说明主文档和同步资源到了，不保证 SPA 的异步数据已渲染、
+challenge 已二次跳转、地图/表格/列表已填充。malo-browser 同时看
+`Page.lifecycleEvent` 的 `networkAlmostIdle`、URL 与 DOM 元素数的稳定采样、challenge URL 的额外
+等待，以及最终 `navigation.settle` 诊断。
+
+### 2. JS challenge 不是统一按“反爬失败”处理
+
+Reddit 的 URL 带 `js_challenge=1` / `jsc_token`，等待后页面正常渲染；只看 URL 或首屏 DOM 会误判。
+当前策略：challenge URL + DOM 仍很小则继续等到 `settle_ms`；DOM 已丰富按正常页面返回；超时仍无
+内容按 partial/timeout 返回，不伪装成功。
+
+### 3. 网络失败和站点反爬要分开
+
+OpenStreetMap 的 `ERR_CONNECTION_TIMED_OUT` 是本机网络不可达，现放在
+`error.details.navigation.net_error`；NYT 的 403 + 滑块是站点侧挑战。前者查出口/DNS/代理，后者
+停止自动重试，转人工 `watch` / 登录态 session / 白名单站点。
+
+UA 不写死：它随 Electron 版本变化，以真机 `observe` 的 `runtime.user_agent` / `webdriver` 为准；
+malo-browser 不做 UA 伪装。
+
+## 不做
+
+- 不伪造 `navigator.webdriver`
+- 不伪造 UA 绕过站点策略
+- 不自动破解滑块、验证码或登录
+- 不把挑战页、空白页或 403 当成成功
+- 不对同一站点高频重试
diff --git a/external_plugins/malo-browser/index.js b/external_plugins/malo-browser/index.js
new file mode 100644
index 00000000..c3bc4322
--- /dev/null
+++ b/external_plugins/malo-browser/index.js
@@ -0,0 +1,26 @@
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+
+export const name = "malo-browser";
+export const inject = ["skills"];
+
+export function apply(ctx) {
+  // DSH host 在运行期提供 @deepseek-ai/dsh-skill-filesystem（optional peer）；
+  // Electron 应用上下文装不了它，所以只在 apply 里解析，不做顶层 import。
+  const { apply: applySkillFilesystem } = createRequire(import.meta.url)(
+    "@deepseek-ai/dsh-skill-filesystem",
+  );
+  applySkillFilesystem(ctx, {
+    providerName: name,
+    includeDefaultRoots: false,
+    bundledSkillDir: fileURLToPath(new URL("./skills/", import.meta.url)),
+    watch: false,
+  });
+  return ctx;
+}
+
+// `electron .` 同样以本文件为应用入口（package.json main）；
+// 真正的应用主进程转发到编译产物，其 CJS 语义由 out/package.json 钉住。
+if (process.type === "browser") {
+  await import(new URL("./out/main/index.js", import.meta.url).href);
+}
diff --git a/external_plugins/malo-browser/schemas/scene.schema.json b/external_plugins/malo-browser/schemas/scene.schema.json
new file mode 100644
index 00000000..c7b1fb9c
--- /dev/null
+++ b/external_plugins/malo-browser/schemas/scene.schema.json
@@ -0,0 +1,542 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://malo-browser.dev/schemas/scene.schema.json",
+  "title": "Malo Browser Scene v1",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "id", "title", "viewport", "steps"],
+  "properties": {
+    "schema_version": {
+      "const": 1
+    },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z0-9-]+$"
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1
+    },
+    "description": {
+      "type": "string"
+    },
+    "url": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^[Hh][Tt][Tt][Pp][Ss]?://"
+    },
+    "file": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?!/)(?![A-Za-z]:)(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$))(?!.*(?:/{2}|\\\\{2}))(?!.*[\\\\/]$).+$"
+    },
+    "viewport": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["width", "height"],
+      "properties": {
+        "width": {
+          "type": "integer",
+          "minimum": 800,
+          "maximum": 3840
+        },
+        "height": {
+          "type": "integer",
+          "minimum": 450,
+          "maximum": 2160
+        },
+        "device_scale_factor": {
+          "type": "number",
+          "minimum": 0.5,
+          "maximum": 4
+        },
+        "mobile": {
+          "type": "boolean"
+        }
+      }
+    },
+    "profile": {
+      "type": "string",
+      "minLength": 1
+    },
+    "allow": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "permissions": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      }
+    },
+    "reset_policy": {
+      "enum": ["reload", "clear-storage", "new-session"]
+    },
+    "vars": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "steps": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "$ref": "#/$defs/step"
+      }
+    },
+    "record": {
+      "type": "object"
+    }
+  },
+  "oneOf": [
+    {
+      "required": ["url"]
+    },
+    {
+      "required": ["file"]
+    }
+  ],
+  "$defs": {
+    "step": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["action"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "action": {
+          "enum": [
+            "goto",
+            "login",
+            "wait",
+            "wait_for",
+            "wait_for_presenter",
+            "click",
+            "fill",
+            "press",
+            "scroll",
+            "highlight",
+            "spotlight",
+            "annotate",
+            "mask",
+            "blackout",
+            "assert",
+            "scene",
+            "set",
+            "note",
+            "screenshot"
+          ]
+        },
+        "note": {
+          "type": "string"
+        },
+        "advance": {
+          "enum": ["auto", "manual"]
+        },
+        "hold_ms": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 600000
+        },
+        "wait_after_ms": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 600000
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 600000
+        },
+        "optional": {
+          "type": "boolean"
+        },
+        "on_error": {
+          "enum": ["stop", "warn"]
+        },
+        "data_demo_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "selector": {
+          "type": "string",
+          "minLength": 1
+        },
+        "text": {
+          "type": "string",
+          "minLength": 1
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "wait_until": {
+          "enum": ["load", "domcontentloaded", "networkidle"]
+        },
+        "seconds": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 3600
+        },
+        "state": {
+          "enum": ["visible", "hidden", "attached"]
+        },
+        "button": {
+          "enum": ["left", "middle", "right"]
+        },
+        "click_count": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 10
+        },
+        "clear": {
+          "type": "boolean"
+        },
+        "key_events": {
+          "type": "boolean"
+        },
+        "key": {
+          "type": "string",
+          "minLength": 1
+        },
+        "target_text": {
+          "type": "string",
+          "minLength": 1
+        },
+        "modifiers": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 15
+        },
+        "dx": {
+          "type": "number"
+        },
+        "dy": {
+          "type": "number"
+        },
+        "behavior": {
+          "enum": ["auto", "instant", "smooth"]
+        },
+        "color": {
+          "type": "string",
+          "minLength": 1
+        },
+        "padding": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 500
+        },
+        "dim": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "x": {
+          "type": "number"
+        },
+        "y": {
+          "type": "number"
+        },
+        "position": {
+          "enum": ["top", "bottom", "left", "right"]
+        },
+        "until": {
+          "enum": ["scene-end"]
+        },
+        "mode": {
+          "enum": ["blur", "solid"]
+        },
+        "on": {
+          "type": "boolean"
+        },
+        "visible": {
+          "type": "string",
+          "minLength": 1
+        },
+        "value": {
+          "type": "string"
+        },
+        "count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "scene_id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "account_id": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+$"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1
+        },
+        "path": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?!/)(?![A-Za-z]:)(?!.*(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$))(?!.*(?:/{2}|\\\\{2}))(?!.*[\\\\/]$).+$"
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "goto"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "required": ["url"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "login"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "required": ["account_id"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "wait"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "required": ["seconds"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "wait_for"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "required": ["selector"]
+              },
+              {
+                "required": ["text"]
+              },
+              {
+                "required": ["url"]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "enum": ["click", "highlight", "spotlight", "mask"]
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "required": ["data_demo_id"]
+              },
+              {
+                "required": ["selector"]
+              },
+              {
+                "required": ["text"]
+              },
+              {
+                "required": ["x", "y"]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "fill"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "required": ["text"],
+            "anyOf": [
+              {
+                "required": ["data_demo_id"]
+              },
+              {
+                "required": ["selector"]
+              },
+              {
+                "required": ["target_text"]
+              },
+              {
+                "required": ["x", "y"]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "annotate"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "required": ["text"],
+            "anyOf": [
+              {
+                "required": ["data_demo_id"]
+              },
+              {
+                "required": ["selector"]
+              },
+              {
+                "required": ["x", "y"]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "assert"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "anyOf": [
+              {
+                "required": ["visible"]
+              },
+              {
+                "required": ["text"]
+              },
+              {
+                "required": ["value"]
+              },
+              {
+                "required": ["url"]
+              },
+              {
+                "required": ["count"]
+              }
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "press"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "required": ["key"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "blackout"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "required": ["on"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "scene"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "required": ["scene_id"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "set"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "required": ["name"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "action": {
+                "const": "screenshot"
+              }
+            },
+            "required": ["action"]
+          },
+          "then": {
+            "required": ["path"]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "optional": {
+                "const": true
+              }
+            },
+            "required": ["optional"]
+          },
+          "then": {
+            "properties": {
+              "action": {
+                "enum": ["highlight", "spotlight", "annotate"]
+              }
+            }
+          }
+        }
+      ]
+    }
+  }
+}
diff --git a/external_plugins/malo-browser/skills/malo-browser/SKILL.md b/external_plugins/malo-browser/skills/malo-browser/SKILL.md
new file mode 100644
index 00000000..6b2df668
--- /dev/null
+++ b/external_plugins/malo-browser/skills/malo-browser/SKILL.md
@@ -0,0 +1,174 @@
+---
+name: malo-browser
+description: Install, configure and run Malo Browser (Chinese name 马喽浏览器), a scripted browser demo and agent web-execution tool (Electron stage, hidden 1080p30 recording with evidence files, director console, loopback control API, multi-agent daemon with isolated sessions). Use when the user says "malo-browser", "马喽浏览器", "马喽", "演示浏览器", "网页演示录制", "场景演示", or asks to set up, run or troubleshoot the Malo Browser project.
+metadata:
+  short-description: Install and run the scripted browser demo tool; troubleshoot it
+---
+
+# Malo Browser — install / configure / troubleshoot
+
+Scripted browser demo tool on Electron: scene scripts drive a Chromium stage,
+recording is fixed-spec 1920x1080@30fps with mp4 plus evidence files, and a
+React director console and loopback HTTP control API sit on top. This skill is
+an install/config/troubleshooting shell — it does NOT replicate product logic;
+it gets the real GitHub repo running on the user's machine.
+
+## Prerequisites
+
+- Node.js on the 22 line >= 22.12, 24.x, or >= 26 (`engines` is
+  `^22.12.0 || ^24.0.0 || >=26.0.0`; the 23 and 25 lines are excluded)
+- ffmpeg + ffprobe on PATH (missing → exit code 3)
+- macOS (window modes and recording are verified on macOS; hidden mode uses the accessory activation policy)
+- Python 3 (only for the bundled fixture static server)
+- git
+
+## Install (from the GitHub repo)
+
+```bash
+git clone https://github.com/Lumos-789/malo-browser.git
+cd malo-browser
+npm install
+npm run build
+```
+
+Sanity gate: `npm run typecheck && npm test` — both green before anything else.
+
+## Run
+
+1. Serve the fixture page (default demo target):
+
+   ```bash
+   python3 -m http.server 4788 --bind 127.0.0.1 --directory out/fixture
+   ```
+
+2. Hidden 10s recording (no window, no focus steal, no Dock icon):
+
+   ```bash
+   npx electron . --mode=record --seconds=10 --out=evidence --label=hidden
+   ```
+
+   Produces `evidence/hidden.mp4` + `hidden.evidence.json` (+ overlay check
+   frame). Exit 0 only when self-checks pass: duration ±0.5s, 30fps,
+   1920x1080, black-frame ratio <50%, overlay really captured.
+
+3. Visible stage for manual browsing: `npx electron . --mode=stage`
+4. Director console + control API: `npm run start:control` — the API binds
+   127.0.0.1 only; a random token is written to `<out>/control.json` (0600);
+   curl examples are in the repository README (`App control API` section).
+5. Full scripted scene run:
+   `npx electron . --mode=app --autorun=report-review --scenes=fixtures/scenes`
+
+## malo-browser agent runtime
+
+`npm run daemon` starts the background malo-browser broker: one daemon hands out
+loopback port leases to multiple agents, and each lease can host isolated
+browser sessions with separate cookies, downloads and artifacts. It creates no
+visible window and does not take focus. Broker state is written to
+`~/.malo-browser/broker.json` (0600); routes, lease rules and the smoke script are
+documented in `docs/malo-browser.md`.
+
+Agents discover page tools with `GET /v1/tools` and invoke them through
+`POST /v1/sessions/:id/tools/<tool>`. Use `snapshot` for structured page content
+(text, headings, links, buttons, inputs, forms, tables, frames, dialogs and
+interactive selectors), `extract` for targeted reads, and the action tools for
+click/fill/upload_file/press/hover/select/focus/scroll/history. `assert` checks
+visible/hidden/text/value/url/count with retry and returns per-check
+expected/actual plus a failure screenshot; a failed assertion is HTTP 200 with
+`result.ok: false` (not a 5xx), and `run_steps` reports its verdict the same way,
+so agent-driven runs end in a pass/fail verdict instead of a vague observation.
+`run_steps` runs a batch of those tools back to back and writes a per-step run
+report.
+
+Response bodies from the network layer: `network_capture` subscribes the session to
+XHR/fetch responses matching URL prefixes, `responses` returns bodies by `seq` (daemon
+memory only). Order: subscribe, navigate, interact, then poll — requests sent before the
+subscription are missed. Scope: the CDP session attaches to the page target, so OOPIF
+(cross-process iframe) and Service Worker requests are never captured.
+
+Login walls and human checks: `watch` shows the real page in an inactive window
+(no focus steal; it stays visible until it is hidden explicitly, i.e. another
+`watch` call with `show:false`) with a native title bar and a browser toolbar
+(address bar plus back/forward/reload), and `login` either fills one-shot
+credentials or waits for the human handoff — a successful `login` hides the
+handoff window again unless `keep_visible: true`. Credentials stay in memory and
+are never written to events or responses.
+
+Persistent login state: create a session with `{"profile":"work"}` to keep
+cookies and storage across sessions and daemon restarts; omit it and the session
+closes anonymous. Inspect or clear profiles with `GET /v1/profiles` and
+`DELETE /v1/profiles/:name` (409 while sessions still use it). Seed a profile from
+an already-logged-in Chromium with `POST /v1/profiles/:name/import` (lease token)
+passing `{"cdp_url":"http://127.0.0.1:<port>"}` (loopback only) plus optional
+`domains` filter — it pulls cookies live over the source's DevTools endpoint and
+writes them into the profile's partition, so logins move over without re-typing
+credentials. Chromium data for the daemon lives under `<data-dir>/chromium`.
+
+## Configure
+
+- Common flags: `--url --width --height --out --label --keep-frames
+  --window-mode=hidden|inactive|offscreen|ghost|focused --focus-emulation=false
+  --control-api=true --control-port --headless=true`
+- Scenes: YAML under `fixtures/scenes/` (bundled: `report-review`, plus
+  `multi-a` → `multi-b` for multi-scene switching, and `login-demo` for account
+  login); the field contract is
+  `schemas/scene.schema.json`; step target resolution order is
+  `data_demo_id` → `selector` → `text` → `x/y` coordinates.
+- Account login: keep profiles in a `0600` file outside git (default
+  `~/.config/malo-browser/accounts.json`, override with
+  `MALO_BROWSER_ACCOUNTS`). A scene uses only `account_id`; the password comes
+  from the profile's `password_env`. `origin` and `login_url` must be
+  same-origin, and the profile must define `success_selector` or `success_url`.
+  Full contract:
+  https://github.com/Lumos-789/malo-browser/blob/main/docs/accounts.md
+- Hidden window mode needs focus emulation (on by default) — without it CDP
+  physical clicks are dropped.
+
+## Exit codes
+
+| code | meaning |
+|---|---|
+| 0 | success, all self-checks passed |
+| 2 | argument error or general failure (selector not found, assertion failed, port busy, scene validation failed) |
+| 3 | ffmpeg/ffprobe missing or failed — install ffmpeg first |
+| 4 | recorder failure (e.g. no frames captured) |
+
+## Troubleshoot
+
+- `EBADENGINE` warning/failure → wrong Node line; use a range from `engines`
+  (>=22.12 on the 22 line, 24.x, or >=26; not 23/25).
+- Exit 0 with no stdout and no files in `<out>` → `ELECTRON_RUN_AS_NODE` is set
+  in that shell (`echo $ELECTRON_RUN_AS_NODE`), so Electron ran as plain Node and
+  never started the app; re-run with `env -u ELECTRON_RUN_AS_NODE npx electron ...`.
+- Exit 3 `E_FFMPEG_MISSING` → install ffmpeg (e.g. `brew install ffmpeg`), re-run.
+- Exit 4 / recording failed → read the take's `.evidence.json`; failure still
+  leaves evidence (`status: "failed"`, `video: null`, `error.code`). In app mode
+  this includes the zero-frame `E_RECORDER_NO_FRAMES` case, which used to only log
+  a line — look next to the take: `recordings/<timestamp>_<scene>/take-01.evidence.json`.
+- `assert` returned HTTP 200 with `result.ok: false` → the check ran and the page
+  did not match; read `result.error.details.checks` (expected/actual) and the
+  failure screenshot. Only bad arguments (4xx) or server failures (5xx) are HTTP
+  errors.
+- `EADDRINUSE` → port occupied; stderr prints a self-help pointer. For the demo
+  control API pass `--control-port`, for the daemon pass `--daemon-port`, and for
+  a lease exhaust change `--port-min` / `--port-max`.
+- Control API 401 → read the token from `<out>/control.json`; send it as
+  `Authorization: Bearer <token>` or `x-demo-token: <token>`.
+- Director shows a MOCK marker → preload bridge missing; launch via
+  `npm start` / `npm run start:control`, not by opening HTML directly.
+- `E_SELECTOR_NOT_FOUND` → no visible element matched; check target syntax
+  (`fill`'s `text` is the input content — the target needs
+  `selector`/`data_demo_id`/`target_text`, or x/y coordinates). A selector with
+  invalid syntax is a different error: `E_BAD_REQUEST` (400), not a timeout.
+- `E_NAV_BLOCKED` on a `goto` step → the scene's `allow` list does not contain
+  that origin; tool-initiated navigation is checked like page navigation.
+- `${env:NAME}` only reads `SCENE_`-prefixed variables; other names are refused
+  so a third-party scene cannot exfiltrate process secrets.
+- `E_ACCOUNT_NOT_FOUND` → account file or `account_id` missing; check
+  `MALO_BROWSER_ACCOUNTS` and the available ids in the error.
+- `E_ACCOUNT_INVALID` with `0600` or `outside a git worktree` → move the
+  profile outside the repo and run `chmod 600 <accounts.json>`.
+- `E_ACCOUNT_INVALID` with `environment variable` → export the profile's
+  `password_env` in the shell that launches Electron. Never put the password
+  in scene YAML.
+- A window steals focus during recording → a focusing `--window-mode` was
+  passed; the defaults (`hidden`/`inactive`) never take focus.
diff --git a/marketplace.json b/marketplace.json
index c7f09a06..e7c84261 100644
--- a/marketplace.json
+++ b/marketplace.json
@@ -10,7 +10,10 @@
     "url": "https://z.ai"
   },
   "unlistedPlugins": [
-    { "name": "openpencil", "source": "./external_plugins/openpencil" }
+    {
+      "name": "openpencil",
+      "source": "./external_plugins/openpencil"
+    }
   ],
   "plugins": [
     {
@@ -827,7 +830,9 @@
     },
     {
       "name": "excalidraw",
-      "componentTypes": ["ui"],
+      "componentTypes": [
+        "ui"
+      ],
       "displayName": "Excalidraw",
       "displayName_i18n": {
         "en": "Excalidraw",
@@ -850,7 +855,9 @@
       "name": "photocraft",
       "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/photocraft/icon.png",
       "source": "./external_plugins/photocraft",
-      "componentTypes": ["ui"],
+      "componentTypes": [
+        "ui"
+      ],
       "displayName": "PhotoCraft",
       "displayName_i18n": {
         "en": "PhotoCraft",
@@ -877,7 +884,9 @@
       "name": "vectorcraft",
       "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/vectorcraft/icon.png",
       "source": "./external_plugins/vectorcraft",
-      "componentTypes": ["ui"],
+      "componentTypes": [
+        "ui"
+      ],
       "displayName": "VectorCraft",
       "displayName_i18n": {
         "en": "VectorCraft",
@@ -904,7 +913,9 @@
       "name": "pdfcraft",
       "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/pdfcraft/icon.png",
       "source": "./external_plugins/pdfcraft",
-      "componentTypes": ["ui"],
+      "componentTypes": [
+        "ui"
+      ],
       "displayName": "PdfCraft",
       "displayName_i18n": {
         "en": "PdfCraft",
@@ -931,7 +942,9 @@
       "name": "designcraft",
       "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/designcraft/icon.png",
       "source": "./external_plugins/designcraft",
-      "componentTypes": ["ui"],
+      "componentTypes": [
+        "ui"
+      ],
       "displayName": "DesignCraft",
       "displayName_i18n": {
         "en": "DesignCraft",
@@ -958,7 +971,9 @@
       "name": "wordcraft",
       "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/wordcraft/icon.png",
       "source": "./external_plugins/wordcraft",
-      "componentTypes": ["ui"],
+      "componentTypes": [
+        "ui"
+      ],
       "displayName": "WordCraft",
       "displayName_i18n": {
         "en": "WordCraft",
@@ -985,7 +1000,9 @@
       "name": "gridcraft",
       "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/gridcraft/icon.png",
       "source": "./external_plugins/gridcraft",
-      "componentTypes": ["ui"],
+      "componentTypes": [
+        "ui"
+      ],
       "displayName": "GridCraft",
       "displayName_i18n": {
         "en": "GridCraft",
@@ -1012,7 +1029,9 @@
       "name": "deckcraft",
       "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/deckcraft/icon.png",
       "source": "./external_plugins/deckcraft",
-      "componentTypes": ["ui"],
+      "componentTypes": [
+        "ui"
+      ],
       "displayName": "DeckCraft",
       "displayName_i18n": {
         "en": "DeckCraft",
@@ -1039,7 +1058,9 @@
       "name": "cadcraft",
       "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/cadcraft/icon.png",
       "source": "./external_plugins/cadcraft",
-      "componentTypes": ["ui"],
+      "componentTypes": [
+        "ui"
+      ],
       "displayName": "CADCraft",
       "displayName_i18n": {
         "en": "CADCraft",
@@ -1066,7 +1087,9 @@
       "name": "soundcraft",
       "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/soundcraft/icon.png",
       "source": "./external_plugins/soundcraft",
-      "componentTypes": ["ui"],
+      "componentTypes": [
+        "ui"
+      ],
       "displayName": "SoundCraft",
       "displayName_i18n": {
         "en": "SoundCraft",
@@ -1149,7 +1172,9 @@
       },
       "category": "developer-tools",
       "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/kicad/icon.png",
-      "componentTypes": ["ui"],
+      "componentTypes": [
+        "ui"
+      ],
       "displayName": "KiCad",
       "displayName_i18n": {
         "en": "KiCad",
@@ -1443,6 +1468,43 @@
         "mcp",
         "verification"
       ]
+    },
+    {
+      "name": "malo-browser",
+      "source": "./external_plugins/malo-browser",
+      "icon": "https://cdn-zcode.z.ai/zcode/official-plugin/assets/malo-browser/icon.png",
+      "description": "Scripted browser demo tool and agent browser runtime: a visible Electron stage for live web demos, hidden 1080p30 recording with evidence files, a director console and a loopback control API, plus a daemon handing out port leases with isolated, profile-backed browser sessions exposing 25 session tools (including network capture).",
+      "description_i18n": {
+        "en": "Scripted browser demo tool and agent browser runtime: a visible Electron stage for live web demos, hidden 1080p30 recording with evidence files, a director console and a loopback control API, plus a daemon handing out port leases with isolated, profile-backed browser sessions exposing 25 session tools (including network capture).",
+        "zh-CN": "脚本化浏览器演示工具兼 agent 浏览器运行时：可见的 Electron 演示舞台、无头 1080p30 录制与证据文件、导演控制台与本地控制 API；守护进程按端口发放租约，提供隔离且可复用登录态的 session，共 25 个 session 工具（含网络抓包）。"
+      },
+      "version": "0.1.11",
+      "author": {
+        "name": "Lumos-789",
+        "url": "https://github.com/Lumos-789"
+      },
+      "category": "developer-tools",
+      "keywords": [
+        "demo",
+        "recording",
+        "electron",
+        "browser",
+        "screencast"
+      ],
+      "examplePrompts": [
+        "Install Malo Browser and record a hidden 10-second demo of the fixture page",
+        "装一下演示浏览器，无头录一段 10 秒的 fixture 演示"
+      ],
+      "examplePrompts_i18n": {
+        "zh-CN": [
+          "装一下演示浏览器，无头录一段 10 秒的 fixture 演示",
+          "演示浏览器录制失败了，帮我排查"
+        ]
+      },
+      "displayName": "Malo Browser",
+      "displayName_i18n": {
+        "zh-CN": "马喽浏览器"
+      }
     }
   ]
-}
\ No newline at end of file
+}