@tianshu-ai/tianshu 0.3.0

package/packages/server/builtinConfig/plugins/microsandbox/skills/microsandbox-config.md

@@ -0,0 +1,38 @@
+---
+name: microsandbox-config
+description: How to change the sandbox VM image / cpus / memory using `update_sandbox_config`, and when a `reset_sandbox` is needed for the change to take effect.
+when:
+  toolPresent: update_sandbox_config
+---
+
+`update_sandbox_config` writes the tenant config file. The currently-running
+VM is **not** restarted automatically; call `reset_sandbox` after this if you
+want the new settings live now.
+
+## Configurable fields
+
+| Field | Default | Reset needed? |
+|-------|---------|---------------|
+| `image` | `python:3.12-slim` | yes (rebuilds VM) |
+| `cpus` | 2 | yes |
+| `memory_mib` | 2048 | yes |
+| `sandbox_name` | `tianshu-<tenantId>` | yes (rarely useful) |
+| `idle_shutdown_ms` | 14400000 (4h) | no (read live) |
+| `exec_timeout_ms` | 300000 (5min) | no (read live per call) |
+
+The result returns `reset_required: true/false` so you know whether to call
+`reset_sandbox` next.
+
+## Common changes
+
+- Need a different OS / pre-installed packages: change `image`, then
+  `reset_sandbox`. Image pulls happen on next `exec` (cold start cost).
+- Memory pressure: bump `memory_mib`, `reset_sandbox`.
+- Idle reaping too aggressive: raise `idle_shutdown_ms`. No reset needed.
+
+## What NOT to do
+
+- Don't set `image` to something you haven't verified locally first — a
+  bad image leaves the sandbox in `state: "error"` and the agent loses
+  `exec` until you fix the config.
+- Don't set `cpus` higher than the host has free.

package/packages/server/builtinConfig/plugins/microsandbox/skills/microsandbox-exec-howto.md

@@ -0,0 +1,144 @@
+---
+name: microsandbox-exec-howto
+description: How to use `exec` effectively — default workdir, timeouts, output truncation, when to call `reset_sandbox` vs retrying.
+when:
+  toolPresent: exec
+---
+
+`exec` runs a command inside a per-tenant microVM started lazily on first use.
+
+## Default working dir
+
+`exec` defaults `cwd` to your user home inside the sandbox
+(`/workspace/users/<your-userId>/`), the SAME dir `read_file`/`write_file`
+operate on. So a relative path means the same file on both sides:
+
+```
+write_file("/hello.py", "print('hi')")
+exec("python3 hello.py")     # → "hi"
+```
+
+Pass an absolute path in `workdir` to step outside (e.g. `/etc`, `/usr`,
+`/tmp`).
+
+## Timeouts
+
+- Default: 5 minutes.
+- Cap: 30 minutes (`timeout_ms` is clamped).
+- Use `timeout_ms` for slow tasks: `pip install`, `npm install`, builds,
+  data processing.
+- A timed-out call returns `timed_out: true` and `exit_code: -1`. Retry with
+  a larger timeout if the command is legitimately slow.
+
+## Starting servers / long-running processes
+
+**Don't run a foreground server with `exec`.** A command like
+`python -m http.server 8000` or `npm start` never returns; the
+`exec` call hangs until the host timeout, then your turn dies
+with no useful output AND the server keeps running, tying up
+the port for the next attempt.
+
+Three safe shapes, in order of preference:
+
+### 1. Skip the server (best)
+
+If you only need to verify the file works in a browser, write
+it and tell the user the path. Don't "verify by starting a
+server" — the user will open it themselves. This is the
+default for static sites, single-file games, demos.
+
+### 2. Background + readiness check
+
+When the verification truly needs the server up:
+
+```bash
+# detach completely so exec returns immediately
+nohup setsid python -m http.server 8000 \
+  > /tmp/srv.log 2>&1 < /dev/null &
+
+# wait briefly, then probe
+sleep 2
+curl -sS --max-time 5 http://127.0.0.1:8000/ | head -20
+```
+
+Key moves: `nohup setsid ... &` detaches from this shell;
+`> /tmp/srv.log 2>&1 < /dev/null` closes stdin and redirects
+output so the parent shell can exit cleanly. Without these the
+fd connection keeps `exec` waiting.
+
+### 3. Bounded foreground (rarely useful)
+
+If you need to capture output and the command will exit on its
+own after some short time (a one-shot test runner, a CLI tool):
+
+```bash
+timeout 30 ./run-tests.sh 2>&1 | tail -50
+```
+
+`timeout` guarantees the call returns; the trailing `tail`
+keeps stdout under the truncation cap.
+
+### Stopping a server you started
+
+```bash
+pkill -f 'python -m http.server' || true
+```
+
+Or just `reset_sandbox` if it's gotten messy — your files in
+`/workspace` survive.
+
+## Output truncation
+
+stdout/stderr each truncated at 200 lines / 8 KB. If output is bigger:
+
+```
+exec("long-running-thing > /workspace/out.log 2>&1")
+read_file("/out.log")
+```
+
+…or pipe through `tail`/`sed` inline.
+
+## Pre-installed tools (don't `apt install` / `pip install` what's already there)
+
+The sandbox image ships with these out of the box. Use them
+directly instead of installing alternatives:
+
+- **`soffice`** (LibreOffice 25.2) — headless docx / xlsx / pptx /
+  pdf conversion. See `microsandbox-libreoffice` for the full
+  conversion table, sandbox-specific gotchas (single-instance
+  lock, AF_UNIX status, font cache), and "when soffice is the
+  WRONG tool".
+- **`chromium` / Playwright MCP** — see `microsandbox-browser-howto`.
+  Don't `playwright install chromium`; the sandbox already has it
+  on CDP 9222 + MCP 3200.
+- **`node`, `npm`, `npx`** — Node 22 LTS, configured to npmmirror
+  in CN. `npm install <pkg>` works; just don't try to upgrade
+  Node itself.
+- **`fc-cache`** — already run at build time, so CJK fonts render
+  in `soffice` and `chromium` without a 30s cold start.
+- **`pdftoppm`** (Poppler) — PDF → PNG / JPEG, the right tool
+  for multi-page rasterisation (used by the LibreOffice and
+  PPTX flows).
+
+If you need something not on this list and it's a one-shot:
+`apt-get install -y <pkg>` works in the running VM but won't
+survive a `reset_sandbox`. For persistence, edit Sandboxfile
+and rebuild (see `microsandbox-build-use`).
+
+## When to reset
+
+Call `reset_sandbox` only when:
+
+- `exec` keeps timing out (process stuck, kernel deadlocked).
+- A long-running daemon (e.g. `python -m http.server`) is in your way.
+- `get_sandbox_status` shows `state: "error"`.
+- You broke something in `/etc` / `/usr` and want a clean slate.
+
+`reset_sandbox` destroys the VM and re-creates it. **Files under
+`/workspace` survive**; everything else (installed packages, `/tmp`, running
+processes) does not.
+
+## Cold start
+
+The sandbox boots on first `exec` (≈10s the first time per session).
+Subsequent calls in the same conversation are sub-second.

package/packages/server/builtinConfig/plugins/microsandbox/skills/microsandbox-libreoffice.md

@@ -0,0 +1,159 @@
+---
+name: microsandbox-libreoffice
+description: How to convert / read / extract Office documents inside the sandbox using the pre-installed LibreOffice (soffice). Covers docx / xlsx / pptx / odt round-trips, PDF rendering, slide-deck text extraction with markitdown, and the sandbox-specific gotchas (AF_UNIX shim, font cache, single-process mode, output paths).
+when:
+  toolPresent: exec
+---
+
+# LibreOffice in the sandbox
+
+The sandbox image ships LibreOffice 25.2 (`writer / calc /
+impress`) plus its CLI alias `soffice`. Use it directly — don't
+`pip install python-docx` / `openpyxl` / `python-pptx` for tasks
+that are basically format conversion. They're worth their weight
+when you need cell-level edits or programmatic slide construction;
+for "give me the text", "convert to PDF", "extract slide images",
+`soffice` is one shell call away.
+
+## Conversion table
+
+```bash
+# Office → text
+soffice --headless --convert-to txt   input.docx --outdir /tmp/
+soffice --headless --convert-to txt   input.xlsx --outdir /tmp/   # cells joined by tabs
+soffice --headless --convert-to txt   input.pptx --outdir /tmp/   # slides as paragraphs
+
+# Office → PDF (the workhorse: any → pdf, lossless layout)
+soffice --headless --convert-to pdf   input.docx  --outdir /tmp/
+soffice --headless --convert-to pdf   input.xlsx  --outdir /tmp/
+soffice --headless --convert-to pdf   input.pptx  --outdir /tmp/
+
+# Office round-trips
+soffice --headless --convert-to docx  input.odt   --outdir /tmp/
+soffice --headless --convert-to xlsx  input.csv   --outdir /tmp/
+soffice --headless --convert-to csv   input.xlsx  --outdir /tmp/
+
+# PDF → image (multi-page; use pdftoppm, NOT soffice)
+soffice --headless --convert-to pdf   input.pptx  --outdir /tmp/
+pdftoppm -jpeg -r 150 /tmp/input.pdf /tmp/slide
+# → /tmp/slide-01.jpg, /tmp/slide-02.jpg, ...
+```
+
+**`--outdir` is required.** Without it `soffice` writes the
+output next to the input, which means a relative input path that
+resolves anywhere unexpected (your `cwd` in the sandbox is
+`/workspace`, not `/tmp`). Always pass `--outdir`.
+
+## Reading content (text extraction)
+
+For "what does this document say?" — skip the conversion step
+and use `markitdown`, which understands docx / xlsx / pptx /
+pdf natively and outputs structured Markdown:
+
+```bash
+pip install --quiet "markitdown[all]"   # already in image cache; first call ~1s
+python -m markitdown report.docx
+python -m markitdown deck.pptx          # slide titles + body text + speaker notes
+python -m markitdown sheet.xlsx         # tabular Markdown
+```
+
+Markitdown is the right pick when you need to **summarise** the
+document or pass content to another LLM call. `soffice
+--convert-to txt` is the right pick when you need a raw textual
+artefact for an export pipeline.
+
+## Multi-page slide / PDF preview
+
+For visual QA of generated decks (the agent decides "did the
+bullets I generated actually fit?"), render every page to JPEG
+and inspect with the vision model:
+
+```bash
+soffice --headless --convert-to pdf deck.pptx --outdir /tmp/
+pdftoppm -jpeg -r 150 /tmp/deck.pdf /tmp/slide
+ls /tmp/slide-*.jpg
+```
+
+`-r 150` is a good visual-QA DPI; bump to 300 for print review,
+drop to 96 if you only want a thumbnail grid.
+
+To re-render a single slide after a fix:
+
+```bash
+pdftoppm -jpeg -r 150 -f 7 -l 7 /tmp/deck.pdf /tmp/slide-7-fixed
+```
+
+## Sandbox-specific gotchas
+
+### Single-instance lock
+
+`soffice` uses an X server profile + an internal lock file under
+`~/.config/libreoffice/`. If two `soffice --headless` calls run
+concurrently in the same VM, the second one waits for the first.
+Two safe options:
+
+- **Sequential calls** (default; just don't background them).
+- **Per-call user profile** when you legitimately need parallel:
+  ```bash
+  soffice --headless \
+          -env:UserInstallation=file:///tmp/lo-$$ \
+          --convert-to pdf input.docx --outdir /tmp/
+  ```
+  `$$` is the shell's PID; one fresh profile per invocation. Costs
+  ~200 ms of cold start per call.
+
+### AF_UNIX socket shim (probably NOT needed here)
+
+Some sandbox runtimes block `socket(AF_UNIX, ...)`, which makes
+`soffice --headless` hang waiting on its internal IPC. Microsandbox
+on macOS / Linux **does NOT block AF_UNIX** (verified), so you
+don't need a shim. If a future runtime change breaks this, the
+diagnostic is:
+
+```bash
+python3 -c 'import socket; socket.socket(socket.AF_UNIX); print("OK")'
+# OK   → no shim needed
+# OSError → AF_UNIX blocked, build an LD_PRELOAD shim that falls
+#          back to socketpair (see Anthropic pptx skill for the C source)
+```
+
+### Java warning is benign
+
+You'll see `Warning: failed to launch javaldx - java may not
+function correctly`. Java is only needed for the optional
+spreadsheet macro / form-controls path, which we don't use.
+Ignore.
+
+### CJK font rendering
+
+The image build runs `fc-cache -fv` so first-call rendering is
+fast and Chinese / Japanese / Korean glyphs render properly.
+If a build skips that step, the first `soffice` call eats 30+s
+synchronising fonts.
+
+### `--outdir` and absolute paths
+
+`soffice` resolves `--outdir` against the sandbox's `cwd`
+(`/workspace` by default). When the agent's `exec` runs from a
+project subdirectory, prefer absolute paths in BOTH `--outdir`
+and the input filename so the output lands where you expect.
+
+## When LibreOffice is the WRONG tool
+
+- **Cell-level editing / formulas in xlsx**: use `openpyxl` or
+  Pandas. `soffice` rewrites the whole file; structural metadata
+  (named ranges, conditional formatting) can shift.
+- **Programmatic slide creation from scratch**: use `pptxgenjs`
+  (Node) or `python-pptx`. `soffice` is for converting an
+  existing deck, not authoring one.
+- **Markdown / text reports**: don't bounce through Office. Just
+  write `.md`.
+
+## Cleanup
+
+`soffice` leaves `~/.config/libreoffice/`, `~/.cache/libreoffice/`,
+and any per-call `/tmp/lo-*` profile dirs around. Sandbox `/tmp`
+is wiped on `reset_sandbox`; `~` (root) survives. If you're
+running thousands of conversions in one session, `rm -rf
+~/.cache/libreoffice/` periodically to keep disk usage from
+creeping.

package/packages/server/builtinConfig/plugins/microsandbox/skills/microsandbox-main-orchestration.md

@@ -0,0 +1,75 @@
+---
+name: microsandbox-main-orchestration
+description: How the main (orchestrator) agent should describe sandbox-bound tasks to its workers. Read before writing a `task_create` description that will run shell commands, browser scripts, or file conversions in the sandbox — it covers what the worker already has so you don't ask it to install duplicates.
+scope: main
+---
+
+# Sandbox capabilities the worker already has
+
+When you write a `task_create` description that the worker will
+execute via `exec`, `browser_*`, or any sandbox-bound tool, **do
+not tell the worker to install software the sandbox image already
+ships**. Workers see this list themselves (via
+`microsandbox-exec-howto`), but a task description that says "if
+this fails, install X" overrides their own skill and burns time
+on installs that don't survive a reset.
+
+The default sandbox image carries:
+
+| Tool | Already there | Don't ask worker to install |
+|---|---|---|
+| Chromium + Playwright MCP | CDP `127.0.0.1:9222`, MCP `:3200`, noVNC `:6080` | `playwright install chromium`, `npx playwright install` |
+| LibreOffice 25.2 | `soffice --headless --convert-to ...` | `apt install libreoffice*` (already there) |
+| Node 22 LTS + npm + npx | npmmirror configured | `nvm install`, manual node tarballs |
+| Python 3.12 + pip | tuna PyPI mirror configured | reinstalling python |
+| `pdftoppm`, `fc-cache`, `jq`, `git` | one-shot build done | duplicates of these |
+
+For one-off Python packages the worker can `pip install` them at
+runtime — that's fine. The trap is **reinstalling the runtime
+itself or a multi-hundred-MB binary** (chromium, JDK, LibreOffice
+fonts) only to throw it away on the next `reset_sandbox`.
+
+## How to phrase the task
+
+Bad (worker burns 3 minutes on a redundant install):
+
+> Convert `/workspace/users/dev/projects/foo/report.docx` to PDF.
+> If `soffice` isn't available, install LibreOffice with apt.
+
+Good (worker just runs the conversion):
+
+> Convert `/workspace/users/dev/projects/foo/report.docx` to PDF
+> using `soffice --headless --convert-to pdf <input> --outdir
+> /workspace/users/dev/projects/foo/`. The sandbox already has
+> LibreOffice; don't reinstall.
+
+Bad (worker tries Path A, then dutifully follows your fallback):
+
+> Render the deck. Path A: use `browser_navigate` to open the
+> page. Path B: if A doesn't work, `pip install playwright &&
+> playwright install chromium` and use page.pdf().
+
+Good (no second path, points at the existing browser):
+
+> Render the deck. Use `browser_navigate(<file URL>)` then
+> `browser_screenshot()`. The sandbox's own chromium handles
+> this — don't install another browser. If the in-sandbox
+> chromium is unhealthy (verify with `browser_health_check`),
+> escalate via `task_intervention_required` instead of
+> reinstalling.
+
+## When the worker should install something
+
+Most agent tasks don't need new packages. A few legit cases:
+
+- A small Python package with no native deps (markitdown,
+  beautifulsoup4, requests). `pip install` adds ~1s and lands
+  in `/usr/local/lib/python3.12/site-packages/` which is part
+  of the rootfs delta — survives until reset.
+- A short-lived utility for a one-shot task (`pip install
+  pdfplumber` to extract a specific PDF's tables).
+
+For anything bigger (chromium, ffmpeg, JDK, LibreOffice, CUDA
+toolkit), don't `apt install` ad-hoc. Edit the Sandboxfile, run
+a build, switch the tenant onto it. That's the path
+`microsandbox-build-use` documents.

package/packages/server/builtinConfig/plugins/microsandbox/templates/README.md

@@ -0,0 +1,26 @@
+# Sandboxfile templates
+
+Each `*.yaml` here is a starting-point Sandboxfile a user can load
+into the admin Sandbox page (or the agent can author via
+`write_file`). Templates surface through the host:
+
+- `GET /api/p/microsandbox/sandboxfile/templates` returns
+  `{ templates: [{ id, displayName, description, content }, ...] }`.
+- The admin page's "Load template" dropdown reads that list and
+  pastes the picked template into the editor (replacing the
+  current draft only after the user clicks Save).
+
+Templates are not enforced — they're just curated examples that
+follow the patterns from `skills/microsandbox-build-use.md` (use
+`bash -c` for verification, regional mirrors for slow apt, etc.).
+
+## When to add a new template
+
+A new template earns its slot when:
+1. Multiple users have hit the same "what packages do I need" wall
+   for a real workload (Office automation, browser, data science),
+   AND
+2. The recipe survives a real `build & use` test on Apple Silicon
+   arm64.
+
+Otherwise leave it as a skill paragraph; less surface to maintain.

package/packages/server/builtinConfig/plugins/microsandbox/templates/browser.yaml

@@ -0,0 +1,105 @@
+# Browser-enabled Sandboxfile (CloakBrowser + Playwright MCP + noVNC).
+#
+# Verified end-to-end on Apple Silicon arm64: build → publish →
+# reset → all 6 supervisord processes RUNNING → CDP / MCP / noVNC
+# all reachable. Build cost: ~3-5 min on cache hit, ~10 min cold
+# (apt + Node + LibreOffice + 200 MB CloakBrowser tarball).
+#
+# After build & use, supervisord must be started inside the live
+# VM. N+5.3 will do that automatically; today the user runs:
+#   supervisord -c /etc/supervisor/conf.d/browser.conf
+#
+# Notes on the painful bits this template encodes:
+#  - dbus is intentionally NOT a supervisor program: dbus-x11 in
+#    debian:slim is missing /usr/share/dbus-1/system.conf and
+#    chromium headless doesn't need a system bus anyway.
+#  - chromium pinned to /tmp/chrome-profile so a stale profile
+#    lock from the build VM can't block startup. Snapshots will
+#    not preserve /tmp.
+#  - chromium binds CDP to 0.0.0.0 so port-forward picks it up.
+#  - Playwright MCP listens on 0.0.0.0; default ::1 was IPv6-only
+#    and unreachable from the IPv4-only host port-forward.
+#  - All multi-line config files (supervisord conf) go through
+#    base64 because the v0 Sandboxfile parser is single-line only
+#    and bash single-quoted heredocs don't carry \n correctly.
+
+image: python:3.12-slim
+cpus: 2
+memory_mib: 8192
+
+exec:
+  # APT 国内源（在其他地区可改成上游 deb.debian.org）
+  - sed -i 's/deb.debian.org/mirrors.aliyun.com/g' /etc/apt/sources.list.d/debian.sources
+  - apt-get update -qq
+
+  # 一行装完（无 dbus）
+  # x11-xserver-utils → xrandr (resize Xvfb framebuffer at runtime)
+  # wmctrl            → fit chromium window to the new framebuffer
+  - DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends curl ca-certificates xz-utils sudo fontconfig fonts-noto-cjk fonts-noto-color-emoji libreoffice-writer libreoffice-calc libreoffice-impress xvfb x11vnc fluxbox supervisor x11-xserver-utils wmctrl libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgbm1 libxss1 libasound2 libxshmfence1 libxkbcommon0 libpango-1.0-0 libxcomposite1 libxdamage1 libxrandr2
+
+  # Node 22 LTS — 多源 fallback。nodejs.org 主源，失败后依次走
+  # npmmirror 镜像、cnpmjs 镜像。每个源走到身为止 (--retry 3)，
+  # 并且 --connect-timeout 30 避免 TCP 建连后被 RST 时挂死。
+  - |
+    bash -c '
+      set -eu
+      VER=v22.20.0
+      F=node-${VER}-linux-arm64.tar.xz
+      for u in \
+        https://nodejs.org/dist/${VER}/${F} \
+        https://npmmirror.com/mirrors/node/${VER}/${F} \
+        https://registry.npmmirror.com/-/binary/node/${VER}/${F}; do
+        echo "[node] trying $u"
+        if curl -fsSL --retry 3 --retry-delay 5 --retry-all-errors \
+             --connect-timeout 30 --max-time 600 "$u" \
+           | tar -xJ -C /usr/local --strip-components=1; then
+          echo "[node] installed from $u"
+          exit 0
+        fi
+        echo "[node] failed: $u"
+      done
+      echo "[node] all sources exhausted" >&2
+      exit 1
+    '
+  - npm config set registry https://registry.npmmirror.com
+
+  # CloakBrowser 200MB - ghproxy + retry + 落盘解压
+  # Tarball is FLAT (no top-level dir); entry binary is `chrome`.
+  - bash -c "mkdir -p /opt/cloakbrowser && curl -fsSL --retry 8 --retry-delay 8 --retry-all-errors --connect-timeout 30 -o /tmp/cb.tar.gz https://gh-proxy.com/https://github.com/CloakHQ/CloakBrowser/releases/download/chromium-v145.0.7632.159.7/cloakbrowser-linux-arm64.tar.gz"
+  - bash -c "test $(stat -c %s /tmp/cb.tar.gz) -gt 100000000"
+  - tar -xzf /tmp/cb.tar.gz -C /opt/cloakbrowser
+  - rm -f /tmp/cb.tar.gz
+
+  # noVNC + websockify
+  - bash -c "mkdir -p /opt/novnc && curl -fsSL --retry 5 --retry-delay 3 --retry-all-errors https://gh-proxy.com/https://github.com/novnc/noVNC/archive/refs/tags/v1.5.0.tar.gz | tar -xz -C /opt/novnc --strip-components=1"
+  - bash -c "mkdir -p /opt/websockify && curl -fsSL --retry 5 --retry-delay 3 --retry-all-errors https://gh-proxy.com/https://github.com/novnc/websockify/archive/refs/tags/v0.13.0.tar.gz | tar -xz -C /opt/websockify --strip-components=1"
+  - ln -sf /opt/novnc/vnc_lite.html /opt/novnc/index.html
+
+  # Playwright MCP - 提前把 npm 包拉到 npx 缓存，runtime 启动不再下载
+  - npx -y @playwright/mcp@latest --help > /dev/null 2>&1
+
+  # 字体缓存（首次 LibreOffice / chromium CJK 渲染）
+  - fc-cache -fv
+
+  # supervisord 配置（base64 - 多行 conf 通过 v0 sandboxfile parser 的唯一办法）
+  - mkdir -p /etc/supervisor/conf.d
+  - bash -c "echo W3VuaXhfaHR0cF9zZXJ2ZXJdCmZpbGU9L3Zhci9ydW4vc3VwZXJ2aXNvci5zb2NrCmNobW9kPTA3MDAKCltzdXBlcnZpc29yZF0KbG9nZmlsZT0vdmFyL2xvZy9zdXBlcnZpc29yZC5sb2cKcGlkZmlsZT0vdmFyL3J1bi9zdXBlcnZpc29yZC5waWQKCltycGNpbnRlcmZhY2U6c3VwZXJ2aXNvcl0Kc3VwZXJ2aXNvci5ycGNpbnRlcmZhY2VfZmFjdG9yeT1zdXBlcnZpc29yLnJwY2ludGVyZmFjZTptYWtlX21haW5fcnBjaW50ZXJmYWNlCgpbc3VwZXJ2aXNvcmN0bF0Kc2VydmVydXJsPXVuaXg6Ly8vdmFyL3J1bi9zdXBlcnZpc29yLnNvY2sKCltwcm9ncmFtOnh2ZmJdCmNvbW1hbmQ9L3Vzci9iaW4vWHZmYiA6OTkgLXNjcmVlbiAwIDI0MDB4MTgwMHgyNCAtYWMgLW5vbGlzdGVuIHRjcAphdXRvcmVzdGFydD10cnVlCnByaW9yaXR5PTEwCgpbcHJvZ3JhbTpmbHV4Ym94XQpjb21tYW5kPS91c3IvYmluL2ZsdXhib3gKZW52aXJvbm1lbnQ9RElTUExBWT0iOjk5IgphdXRvcmVzdGFydD10cnVlCnByaW9yaXR5PTIwCgpbcHJvZ3JhbTpjaHJvbWl1bV0KY29tbWFuZD0vb3B0L2Nsb2FrYnJvd3Nlci9jaHJvbWUgLS1yZW1vdGUtZGVidWdnaW5nLXBvcnQ9OTIyMiAtLXJlbW90ZS1kZWJ1Z2dpbmctYWRkcmVzcz0wLjAuMC4wIC0tbm8tc2FuZGJveCAtLWRpc2FibGUtZGV2LXNobS11c2FnZSAtLXVzZXItZGF0YS1kaXI9L3RtcC9jaHJvbWUtcHJvZmlsZSAtLXdpbmRvdy1zaXplPTEyODAsODAwCmVudmlyb25tZW50PURJU1BMQVk9Ijo5OSIKYXV0b3Jlc3RhcnQ9dHJ1ZQpwcmlvcml0eT0zMApzdGFydHNlY3M9OAoKW3Byb2dyYW06cGxheXdyaWdodC1tY3BdCmNvbW1hbmQ9L3Vzci9sb2NhbC9iaW4vbnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QgLS1ob3N0IDAuMC4wLjAgLS1wb3J0IDMyMDAgLS1hbGxvd2VkLWhvc3RzPSogLS1hbGxvdy11bnJlc3RyaWN0ZWQtZmlsZS1hY2Nlc3MgLS1jYXBzPXBkZix2aXNpb24gLS1icm93c2VyIGNocm9taXVtIC0tY2RwLWVuZHBvaW50IGh0dHA6Ly8xMjcuMC4wLjE6OTIyMgphdXRvcmVzdGFydD10cnVlCnByaW9yaXR5PTQwCnN0YXJ0c2Vjcz04CgpbcHJvZ3JhbTp4MTF2bmNdCmNvbW1hbmQ9L3Vzci9iaW4veDExdm5jIC1kaXNwbGF5IDo5OSAtZm9yZXZlciAtc2hhcmVkIC1ub3B3IC1yZmJwb3J0IDU5MDAKYXV0b3Jlc3RhcnQ9dHJ1ZQpwcmlvcml0eT01MAoKW3Byb2dyYW06bm92bmNdCmNvbW1hbmQ9L29wdC93ZWJzb2NraWZ5L3J1biAtLXdlYj0vb3B0L25vdm5jIDYwODAgbG9jYWxob3N0OjU5MDAKYXV0b3Jlc3RhcnQ9dHJ1ZQpwcmlvcml0eT02MAo= | base64 -d > /etc/supervisor/conf.d/browser.conf"
+
+  # Build 阶段启动 supervisord 一次，让 verify 步骤能 curl 到端口
+  - supervisord -c /etc/supervisor/conf.d/browser.conf
+  - sleep 18
+
+  # === Verify ============================================================
+  # 任一 fail 整个 build fail，避免 "build 成功但实际跑不起来"
+  - bash -c "node --version && npm --version && /opt/cloakbrowser/chrome --version | head -1"
+  # supervisor 没有 FATAL/EXITED/STOPPED
+  - bash -c "supervisorctl -c /etc/supervisor/conf.d/browser.conf status; supervisorctl -c /etc/supervisor/conf.d/browser.conf status | grep -E 'FATAL|EXITED|STOPPED' && exit 1 || true"
+  # 6 个 program 都 RUNNING
+  - bash -c "test $(supervisorctl -c /etc/supervisor/conf.d/browser.conf status | grep -c RUNNING) -eq 6"
+  # CDP 9222
+  - bash -c "curl -sS --max-time 8 http://127.0.0.1:9222/json/version | grep -q Browser"
+  # noVNC 6080
+  - bash -c "curl -sS --max-time 8 http://127.0.0.1:6080/vnc_lite.html | grep -qi DOCTYPE"
+  # Playwright MCP 3200（HTTP 403/404/200 都说明服务在 listen）
+  - bash -c "code=$(curl -sS --max-time 8 -o /dev/null -w '%{http_code}' http://127.0.0.1:3200/); echo MCP HTTP code=$code; test \"$code\" != \"000\""
+  - echo OK

package/packages/server/builtinConfig/plugins/microsandbox/templates/task-runner-with-browser.yaml

@@ -0,0 +1,80 @@
+# Task runner + Browser (incremental layer).
+#
+# Designed to be built ON TOP OF the `task-runner` snapshot via the
+# admin UI's "based on" dropdown:
+#
+#   1. Build the task-runner template first → snapshot
+#      `tianshu-<tenant>-build-<id>`
+#   2. Switch the editor to this template
+#   3. Click Build, pick "based on: task-runner build-<id>" in the
+#      dropdown
+#   4. The Sandboxfile's `image:` line below is IGNORED in that
+#      mode — the snapshot already pins it. Only the apt / curl /
+#      supervisord steps below run, layering chromium + Playwright
+#      MCP + noVNC on top of the existing task-runner image.
+#
+# Result: a snapshot that has everything task-runner ships
+# (Node + Python + office libs + libreoffice + CN mirrors)
+# AND the browser stack from `browser.yaml`. Bigger than
+# task-runner (~2.5 GB extra for the chromium/CloakBrowser
+# binaries) but you skip re-running the slow apt + pip + libreoffice
+# layers from scratch.
+#
+# If you boot this WITHOUT picking a "based on" snapshot the build
+# will fail at the very first `apt install` step (the base image
+# below is bare python:3.12-slim — it doesn't have any of
+# task-runner's tools yet). That failure is the intended signal
+# that you skipped step 3.
+
+# Image is a deliberate placeholder. It only matters when this
+# template is built without a "based on" snapshot, and that's
+# explicitly not how this template is meant to be used.
+image: python:3.12-slim
+cpus: 2
+memory_mib: 8192
+
+exec:
+  # APT mirrors (no-op outside CN; harmless inside).
+  - sed -i 's|deb.debian.org|mirrors.aliyun.com|g; s|security.debian.org|mirrors.aliyun.com|g' /etc/apt/sources.list.d/debian.sources
+  - apt-get update -qq
+
+  # The browser stack on top of task-runner. We DON'T re-install
+  # python3 / sudo / git / fonts / libreoffice — those came from
+  # the task-runner snapshot we layered on. xz-utils gets pulled
+  # in for the CloakBrowser tarball; everything else is new.
+  - DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends xz-utils xvfb x11vnc fluxbox supervisor x11-xserver-utils wmctrl libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libgbm1 libxss1 libasound2 libxshmfence1 libxkbcommon0 libpango-1.0-0 libxcomposite1 libxdamage1 libxrandr2
+  - rm -rf /var/lib/apt/lists/*
+
+  # CloakBrowser binary + noVNC + websockify.
+  - bash -c "mkdir -p /opt/cloakbrowser && curl -fsSL --retry 8 --retry-delay 8 --retry-all-errors --connect-timeout 30 -o /tmp/cb.tar.gz https://gh-proxy.com/https://github.com/CloakHQ/CloakBrowser/releases/download/chromium-v145.0.7632.159.7/cloakbrowser-linux-arm64.tar.gz"
+  - bash -c "test $(stat -c %s /tmp/cb.tar.gz) -gt 100000000"
+  - tar -xzf /tmp/cb.tar.gz -C /opt/cloakbrowser
+  - rm -f /tmp/cb.tar.gz
+  - bash -c "mkdir -p /opt/novnc && curl -fsSL --retry 5 --retry-delay 3 --retry-all-errors https://gh-proxy.com/https://github.com/novnc/noVNC/archive/refs/tags/v1.5.0.tar.gz | tar -xz -C /opt/novnc --strip-components=1"
+  - bash -c "mkdir -p /opt/websockify && curl -fsSL --retry 5 --retry-delay 3 --retry-all-errors https://gh-proxy.com/https://github.com/novnc/websockify/archive/refs/tags/v0.13.0.tar.gz | tar -xz -C /opt/websockify --strip-components=1"
+  - ln -sf /opt/novnc/vnc_lite.html /opt/novnc/index.html
+
+  # Pre-warm the Playwright MCP npx cache.
+  - npx -y @playwright/mcp@latest --help > /dev/null 2>&1
+
+  # supervisord conf (base64'd same as browser.yaml; the parser is
+  # single-line only, so multi-line conf round-trips through
+  # base64).
+  - mkdir -p /etc/supervisor/conf.d
+  - bash -c "echo W3VuaXhfaHR0cF9zZXJ2ZXJdCmZpbGU9L3Zhci9ydW4vc3VwZXJ2aXNvci5zb2NrCmNobW9kPTA3MDAKCltzdXBlcnZpc29yZF0KbG9nZmlsZT0vdmFyL2xvZy9zdXBlcnZpc29yZC5sb2cKcGlkZmlsZT0vdmFyL3J1bi9zdXBlcnZpc29yZC5waWQKCltycGNpbnRlcmZhY2U6c3VwZXJ2aXNvcl0Kc3VwZXJ2aXNvci5ycGNpbnRlcmZhY2VfZmFjdG9yeT1zdXBlcnZpc29yLnJwY2ludGVyZmFjZTptYWtlX21haW5fcnBjaW50ZXJmYWNlCgpbc3VwZXJ2aXNvcmN0bF0Kc2VydmVydXJsPXVuaXg6Ly8vdmFyL3J1bi9zdXBlcnZpc29yLnNvY2sKCltwcm9ncmFtOnh2ZmJdCmNvbW1hbmQ9L3Vzci9iaW4vWHZmYiA6OTkgLXNjcmVlbiAwIDI0MDB4MTgwMHgyNCAtYWMgLW5vbGlzdGVuIHRjcAphdXRvcmVzdGFydD10cnVlCnByaW9yaXR5PTEwCgpbcHJvZ3JhbTpmbHV4Ym94XQpjb21tYW5kPS91c3IvYmluL2ZsdXhib3gKZW52aXJvbm1lbnQ9RElTUExBWT0iOjk5IgphdXRvcmVzdGFydD10cnVlCnByaW9yaXR5PTIwCgpbcHJvZ3JhbTpjaHJvbWl1bV0KY29tbWFuZD0vb3B0L2Nsb2FrYnJvd3Nlci9jaHJvbWUgLS1yZW1vdGUtZGVidWdnaW5nLXBvcnQ9OTIyMiAtLXJlbW90ZS1kZWJ1Z2dpbmctYWRkcmVzcz0wLjAuMC4wIC0tbm8tc2FuZGJveCAtLWRpc2FibGUtZGV2LXNobS11c2FnZSAtLXVzZXItZGF0YS1kaXI9L3RtcC9jaHJvbWUtcHJvZmlsZSAtLXdpbmRvdy1zaXplPTEyODAsODAwCmVudmlyb25tZW50PURJU1BMQVk9Ijo5OSIKYXV0b3Jlc3RhcnQ9dHJ1ZQpwcmlvcml0eT0zMApzdGFydHNlY3M9OAoKW3Byb2dyYW06cGxheXdyaWdodC1tY3BdCmNvbW1hbmQ9L3Vzci9sb2NhbC9iaW4vbnB4IEBwbGF5d3JpZ2h0L21jcEBsYXRlc3QgLS1ob3N0IDAuMC4wLjAgLS1wb3J0IDMyMDAgLS1hbGxvd2VkLWhvc3RzPSogLS1hbGxvdy11bnJlc3RyaWN0ZWQtZmlsZS1hY2Nlc3MgLS1jYXBzPXBkZix2aXNpb24gLS1icm93c2VyIGNocm9taXVtIC0tY2RwLWVuZHBvaW50IGh0dHA6Ly8xMjcuMC4wLjE6OTIyMgphdXRvcmVzdGFydD10cnVlCnByaW9yaXR5PTQwCnN0YXJ0c2Vjcz04CgpbcHJvZ3JhbTp4MTF2bmNdCmNvbW1hbmQ9L3Vzci9iaW4veDExdm5jIC1kaXNwbGF5IDo5OSAtZm9yZXZlciAtc2hhcmVkIC1ub3B3IC1yZmJwb3J0IDU5MDAKYXV0b3Jlc3RhcnQ9dHJ1ZQpwcmlvcml0eT01MAoKW3Byb2dyYW06bm92bmNdCmNvbW1hbmQ9L29wdC93ZWJzb2NraWZ5L3J1biAtLXdlYj0vb3B0L25vdm5jIDYwODAgbG9jYWxob3N0OjU5MDAKYXV0b3Jlc3RhcnQ9dHJ1ZQpwcmlvcml0eT02MAo= | base64 -d > /etc/supervisor/conf.d/browser.conf"
+
+  # Boot supervisord once during build so verify can hit the ports.
+  - supervisord -c /etc/supervisor/conf.d/browser.conf
+  - sleep 18
+
+  # === Verify ============================================================
+  # Carry-over from task-runner: those tools must still work.
+  - bash -c "node --version && python3 --version && pip3 --version && python3 -c 'import pandas, docx, pptx; print(\"py-libs ok\")'"
+  # New layer: browser stack alive.
+  - bash -c "/opt/cloakbrowser/chrome --version | head -1"
+  - bash -c "supervisorctl -c /etc/supervisor/conf.d/browser.conf status; supervisorctl -c /etc/supervisor/conf.d/browser.conf status | grep -E 'FATAL|EXITED|STOPPED' && exit 1 || true"
+  - bash -c "test $(supervisorctl -c /etc/supervisor/conf.d/browser.conf status | grep -c RUNNING) -eq 6"
+  - bash -c "curl -sS --max-time 8 http://127.0.0.1:9222/json/version | grep -q Browser"
+  - bash -c "curl -sS --max-time 8 http://127.0.0.1:6080/vnc_lite.html | grep -qi DOCTYPE"
+  - bash -c "code=$(curl -sS --max-time 8 -o /dev/null -w '%{http_code}' http://127.0.0.1:3200/); echo MCP HTTP code=$code; test \"$code\" != \"000\""
+  - echo OK