preflite 1.0.1

package/dist/mcp/exploration/tools-atomic.js

@@ -0,0 +1,34 @@
+import { resolveSession } from "./tools-session.js";
+/**
+ * Parse a data URI and return the base64 payload and MIME type.
+ * Falls back to `mimeType: "unknown"` when the data URI cannot be parsed.
+ */
+function parseDataUri(uri) {
+    const match = /^data:([^;]+);base64,(.+)$/.exec(uri);
+    if (!match) {
+        return { screenshot: uri, mimeType: "unknown" };
+    }
+    return { screenshot: match[2], mimeType: match[1] };
+}
+export function getScreenshotHandler(ctx) {
+    return async (input) => {
+        const session = await resolveSession(input.sessionId, ctx);
+        const rawDataUri = await session.device.screenshotBase64();
+        return parseDataUri(rawDataUri);
+    };
+}
+export function getTypeHandler(ctx) {
+    return async (input) => {
+        const session = await resolveSession(input.sessionId, ctx);
+        await session.agent.aiAct(`输入 ${input.text}`);
+        return { ok: true };
+    };
+}
+export function getWaitHandler(ctx) {
+    return async (input) => {
+        const session = await resolveSession(input.sessionId, ctx);
+        const clamped = Math.max(0, Math.min(input.ms, 10000));
+        await new Promise((r) => setTimeout(r, clamped));
+        return { ok: true };
+    };
+}

package/dist/mcp/exploration/tools-intelligent.js

@@ -0,0 +1,33 @@
+import { resolveSession } from "./tools-session.js";
+export function getPageSummaryHandler(ctx) {
+    return async (input) => {
+        const session = await resolveSession(input.sessionId, ctx);
+        const summary = await session.agent.aiAsk("详细描述当前页面。请按从上到下的顺序列出所有可见区域、交互元素和文案。\n" +
+            "特别注意：\n" +
+            "1) 页面底部是否有更多内容（是否可滚动）？如果底部紧贴导航栏/状态栏则说明是固定单屏布局\n" +
+            "2) 是否有弹窗、广告或遮挡物？\n" +
+            "3) 整体布局类型：固定单屏 / 可滚动长页面 / 多Tab / 列表\n" +
+            "先判断布局类型，再逐一描述每个区域的内容。");
+        return { summary };
+    };
+}
+export function askAboutScreenHandler(ctx) {
+    return async (input) => {
+        const session = await resolveSession(input.sessionId, ctx);
+        const answer = await session.agent.aiAsk(input.question);
+        return { answer };
+    };
+}
+export function aiActHandler(ctx) {
+    return async (input) => {
+        const session = await resolveSession(input.sessionId, ctx);
+        await session.agent.aiAct(input.intent);
+        const afterSummary = await session.agent.aiAsk("刚刚的操作已完成。请判断：\n" +
+            "1) 操作是否改变了页面内容？（新页面、弹窗、滚动到底部、输入框获得焦点等）\n" +
+            "2) 如果操作是滑动页面，是否滑到了底部或页面内容没有变化？\n" +
+            "3) 当前页面布局类型是固定单屏还是可滚动长页面？\n" +
+            "4) 当前页面出现的最关键变化是什么？\n" +
+            "如果你发现操作没有产生任何实际变化（比如反复滑动但没有新内容），请明确指出\"页面没有变化\"。");
+        return { ok: true, summary: afterSummary };
+    };
+}

package/dist/mcp/exploration/tools-session.js

@@ -0,0 +1,276 @@
+import { readFile } from "node:fs/promises";
+import http from "node:http";
+import { homedir } from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+import { createSession, getSession, destroySession, destroySessionById } from "./sessionManager.js";
+import { createMidsceneSession } from "../../utils/midscene-device-session.js";
+// ---------------------------------------------------------------------------
+// Auto-discover WDA port from watchdog state file
+// ---------------------------------------------------------------------------
+async function discoverWdaPort(deviceId) {
+    const statePath = process.env.IOS_WDA_PORT_MAP_FILE_PATH
+        || path.join(homedir(), ".preflight", "runtime", ".wda-agent-state", "wda-port-map.json");
+    try {
+        const raw = await readFile(statePath, "utf8");
+        const parsed = JSON.parse(raw);
+        const port = parsed?.portsByUdid?.[deviceId];
+        if (port && Number.isFinite(port) && port > 0)
+            return Math.floor(port);
+    }
+    catch {
+        // state file not found or malformed — will use default port
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// WDA health check and auto-start for iOS exploration
+// ---------------------------------------------------------------------------
+async function checkWdaHealth(host, port, timeoutMs) {
+    return new Promise((resolve) => {
+        const req = http.get(`http://${host}:${port}/status`, { timeout: timeoutMs }, (res) => {
+            let body = "";
+            res.on("data", (chunk) => { body += chunk; });
+            res.on("end", () => resolve(body.trim().length > 0));
+        });
+        req.on("error", () => resolve(false));
+        req.on("timeout", () => { req.destroy(); resolve(false); });
+    });
+}
+/**
+ * Ensure WebDriverAgent is running for the given iOS device.
+ * If already healthy, returns immediately. Otherwise invokes start-ios-wda.sh
+ * and waits up to 120s for it to become ready.
+ */
+export async function ensureIosWdaStarted(resourceId, runtimeEnv, projectRoot) {
+    const host = runtimeEnv.MIDSCENE_IOS_WDA_HOST || "127.0.0.1";
+    const defaultPort = Number(runtimeEnv.MIDSCENE_IOS_WDA_PORT) || 8200;
+    const udid = extractDeviceValue(resourceId);
+    // Discover port from watchdog port map, else use default
+    const discoveredPort = udid ? await discoverWdaPort(udid) : null;
+    const port = discoveredPort ?? defaultPort;
+    // Already healthy?
+    if (await checkWdaHealth(host, port, 2000)) {
+        return { ok: true, message: `WebDriverAgent is already healthy on ${host}:${port}.`, host, port };
+    }
+    // Resolve start-ios-wda.sh script path
+    const resolvedProjectRoot = projectRoot || process.cwd();
+    const scriptPath = path.join(resolvedProjectRoot, "scripts", "start-ios-wda.sh");
+    if (!udid) {
+        return { ok: false, message: "Cannot start WDA: no iOS device UDID found in resourceId.", host, port };
+    }
+    // Start WDA via script
+    return new Promise((resolve) => {
+        const child = spawn("/bin/bash", [scriptPath, udid, String(port)], {
+            stdio: ["ignore", "pipe", "pipe"],
+            timeout: 120_000,
+        });
+        let stdout = "";
+        let stderr = "";
+        child.stdout?.on("data", (chunk) => { stdout += String(chunk); });
+        child.stderr?.on("data", (chunk) => { stderr += String(chunk); });
+        child.on("close", async (code) => {
+            if (code === 0) {
+                // Script succeeded — now wait for WDA to be actually healthy
+                for (let attempt = 0; attempt < 30; attempt++) {
+                    if (await checkWdaHealth(host, port, 1000)) {
+                        resolve({ ok: true, message: `WebDriverAgent started successfully on ${host}:${port}.`, host, port });
+                        return;
+                    }
+                    await new Promise((r) => setTimeout(r, 1000));
+                }
+                resolve({
+                    ok: false,
+                    message: `start-ios-wda.sh exited 0 but WDA not healthy on ${host}:${port} after 30s. stdout: ${stdout.slice(0, 500)}`,
+                    host, port,
+                });
+            }
+            else {
+                resolve({
+                    ok: false,
+                    message: `start-ios-wda.sh exited code ${code}. stderr: ${stderr.slice(0, 300)}`,
+                    host, port,
+                });
+            }
+        });
+        child.on("error", (err) => {
+            resolve({
+                ok: false,
+                message: `Failed to start WDA script: ${err.message}`,
+                host, port,
+            });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Exported helpers (used by other exploration tools for session recovery)
+// ---------------------------------------------------------------------------
+export function generateSessionId() {
+    return `explore-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+export function parsePlatform(resourceId) {
+    const colonIdx = resourceId.indexOf(":");
+    if (colonIdx < 0) {
+        throw new Error(`Invalid resourceId format: "${resourceId}". Expected "platform:id"`);
+    }
+    const prefix = resourceId.slice(0, colonIdx);
+    switch (prefix) {
+        case "android":
+            return "ANDROID";
+        case "ios":
+            return "IOS";
+        case "harmony":
+            return "HARMONY";
+        default:
+            throw new Error(`Unknown platform prefix in resourceId: "${resourceId}"`);
+    }
+}
+function extractDeviceValue(resourceId) {
+    const colonIdx = resourceId.indexOf(":");
+    return colonIdx >= 0 ? resourceId.slice(colonIdx + 1) : "";
+}
+export async function createMidsceneSessionFromResourceId(resourceId, runtimeEnv) {
+    const platform = parsePlatform(resourceId);
+    const value = extractDeviceValue(resourceId);
+    switch (platform) {
+        case "ANDROID": {
+            const adbPortRaw = runtimeEnv.MIDSCENE_ANDROID_ADB_PORT;
+            const adbPort = adbPortRaw ? Number(adbPortRaw) : 5037;
+            return createMidsceneSession({
+                platform: "android",
+                serial: value || undefined,
+                adbHost: runtimeEnv.MIDSCENE_ANDROID_ADB_HOST ?? "127.0.0.1",
+                adbPort,
+            });
+        }
+        case "IOS": {
+            const udid = value || undefined;
+            const discoveredPort = await discoverWdaPort(udid || "");
+            const wdaPort = runtimeEnv.MIDSCENE_IOS_WDA_PORT
+                ? Number(runtimeEnv.MIDSCENE_IOS_WDA_PORT)
+                : discoveredPort ?? 8200;
+            const logPort = wdaPort === discoveredPort ? `${wdaPort} (discovered)` : `${wdaPort} (default)`;
+            console.log(`[ios-target] ${udid || "auto"} WDA port: ${logPort}`);
+            return createMidsceneSession({
+                platform: "ios",
+                deviceId: udid,
+                wdaHost: runtimeEnv.MIDSCENE_IOS_WDA_HOST ?? "127.0.0.1",
+                wdaPort,
+            });
+        }
+        case "HARMONY":
+            return createMidsceneSession({
+                platform: "harmony",
+                deviceId: value || undefined,
+                hdcPath: runtimeEnv.MIDSCENE_HARMONY_HDC_PATH || undefined,
+            });
+        default:
+            const _exhaustive = platform;
+            throw new Error(`Unsupported platform: ${_exhaustive}`);
+    }
+}
+function isInstallableRef(appRef) {
+    const lower = appRef.toLowerCase();
+    return (lower.startsWith("http") ||
+        lower.startsWith("file") ||
+        lower.endsWith(".apk") ||
+        lower.endsWith(".ipa"));
+}
+// ---------------------------------------------------------------------------
+// Session manager helpers (shared across all exploration tools)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve a session by ID, with automatic recovery across MCP server restarts.
+ * 1. Try in-memory lookup (fast path)
+ * 2. If not found, try to load session metadata from disk
+ * 3. If metadata found, re-create the device connection using the context factory
+ * 4. Store the recovered session in memory for subsequent calls
+ */
+export async function resolveSession(id, ctx) {
+    try {
+        const state = getSession(id);
+        return state.session;
+    }
+    catch {
+        // Session not in memory — try to recover from disk
+    }
+    const { loadMeta, storeSession } = await import("./sessionManager.js");
+    const meta = await loadMeta(id);
+    if (!meta) {
+        throw new Error(`Exploration session not found: ${id}. Call exploration_start first.`);
+    }
+    // Inject env vars for the Midscene SDK
+    for (const [key, value] of Object.entries(meta.env)) {
+        if (value !== undefined && !(key in process.env)) {
+            process.env[key] = value;
+        }
+    }
+    const session = await createMidsceneSessionFromResourceId(meta.resourceId, meta.env);
+    storeSession(id, session, meta);
+    return session;
+}
+// ---------------------------------------------------------------------------
+// Tool handlers
+// ---------------------------------------------------------------------------
+export function getExplorationStartHandler(ctx) {
+    return async (input) => {
+        await ctx.ensureAgentStarted();
+        const configEnv = await ctx.loadConfigEnv();
+        const runtimeEnv = { ...configEnv };
+        for (const [key, value] of Object.entries(runtimeEnv)) {
+            if (value !== undefined && !(key in process.env)) {
+                process.env[key] = value;
+            }
+        }
+        let resourceId = input.resourceId;
+        if (!resourceId) {
+            const devices = await ctx.client.listDevices();
+            if (devices.length === 0) {
+                throw new Error("No devices available. Provide a resourceId or connect a device first.");
+            }
+            resourceId = devices[0].id;
+        }
+        const platform = parsePlatform(resourceId);
+        // Auto-start WDA for iOS if not running
+        if (platform === "IOS") {
+            const wdaResult = await ensureIosWdaStarted(resourceId, runtimeEnv, ctx.projectRoot);
+            if (!wdaResult.ok) {
+                throw new Error(`iOS WebDriverAgent is not running and could not be auto-started: ${wdaResult.message}. ` +
+                    `Call "start_ios_wda" tool explicitly if needed.`);
+            }
+        }
+        const session = await createMidsceneSessionFromResourceId(resourceId, runtimeEnv);
+        const sessionId = generateSessionId();
+        createSession(sessionId, resourceId, platform, session, runtimeEnv);
+        try {
+            if (input.appRef) {
+                if (isInstallableRef(input.appRef)) {
+                    await ctx.client.installApp(resourceId, input.appRef);
+                    return {
+                        sessionId,
+                        device: { platform, resourceId },
+                        note: `App installed from ${input.appRef}. Use exploration_ai_act to launch it.`,
+                    };
+                }
+                await session.agent.launch(input.appRef);
+            }
+        }
+        catch (err) {
+            await destroySessionById(sessionId).catch(() => { });
+            throw err;
+        }
+        return { sessionId, device: { platform, resourceId } };
+    };
+}
+export function getExplorationEndHandler() {
+    return async (input) => {
+        try {
+            const state = getSession(input.sessionId);
+            await destroySession(state);
+        }
+        catch {
+            // Session may already be expired or destroyed — always return ok
+        }
+        return { ok: true };
+    };
+}

package/dist/mcp/exploration/types.js

@@ -0,0 +1 @@
+export {};

package/dist/mcp/flowStepEvents.js

@@ -0,0 +1,114 @@
+const PREFIX = "__FLOW_STEP_EVENT__";
+export function extractFlowStepEventsFromRun(run) {
+    const out = [];
+    for (const event of run.events) {
+        for (const text of candidateTexts(event)) {
+            out.push(...extractFlowStepEventsFromText(text));
+        }
+    }
+    return out.sort((a, b) => a.ts - b.ts || a.stepIndex - b.stepIndex);
+}
+export function extractFlowStepEventsFromText(text) {
+    const out = [];
+    for (const line of text.split(/\r?\n/)) {
+        const idx = line.indexOf(PREFIX);
+        if (idx < 0)
+            continue;
+        const json = line.slice(idx + PREFIX.length).trim();
+        try {
+            const parsed = JSON.parse(json);
+            const type = parsed.type;
+            const stepIndex = Number(parsed.stepIndex);
+            const ts = Number(parsed.ts);
+            if ((type !== "start" && type !== "end" && type !== "error") || !Number.isFinite(stepIndex) || !Number.isFinite(ts)) {
+                continue;
+            }
+            out.push({
+                type,
+                stepIndex,
+                ts,
+                ...(Number.isFinite(Number(parsed.durationMs)) ? { durationMs: Number(parsed.durationMs) } : {}),
+                ...(typeof parsed.message === "string" ? { message: parsed.message } : {}),
+                ...(Number.isFinite(Number(parsed.iteration)) ? { iteration: Number(parsed.iteration) } : {}),
+            });
+        }
+        catch {
+            // Ignore non-JSON log lines.
+        }
+    }
+    return out;
+}
+export function buildFlowStepView(visualFlow, events) {
+    const steps = flattenVisualFlowSteps(visualFlow);
+    const latestByStep = new Map();
+    for (const event of events)
+        latestByStep.set(event.stepIndex, event);
+    const current = [...events].reverse().find((event) => event.type === "start" || event.type === "error");
+    return {
+        currentStepIndex: current?.stepIndex,
+        events,
+        steps: steps.map((step) => {
+            const latest = latestByStep.get(step.index);
+            return {
+                ...step,
+                status: latest?.type === "end" ? "passed" : latest?.type === "error" ? "failed" : latest?.type === "start" ? "running" : "pending",
+                ...(latest?.durationMs != null ? { durationMs: latest.durationMs } : {}),
+                ...(latest?.message ? { message: latest.message } : {}),
+            };
+        }),
+    };
+}
+function candidateTexts(event) {
+    const payload = event.payload ?? {};
+    const keys = ["chunk", "message", "log", "text", "stdout", "stderr"];
+    const out = [];
+    for (const key of keys) {
+        const value = payload[key];
+        if (typeof value === "string" && value.includes(PREFIX))
+            out.push(value);
+    }
+    return out;
+}
+function flattenVisualFlowSteps(visualFlow) {
+    const root = visualFlow && typeof visualFlow === "object" ? visualFlow : {};
+    const steps = Array.isArray(root.steps) ? root.steps : [];
+    const out = [];
+    let index = 0;
+    const walk = (items, depth) => {
+        for (const item of items) {
+            if (!item || typeof item !== "object" || Array.isArray(item))
+                continue;
+            const step = item;
+            const type = typeof step.type === "string" ? step.type : "unknown";
+            index += 1;
+            out.push({ index, type, title: describeStep(type, step), depth });
+            if (type === "if" || type === "ifDeviceType") {
+                if (Array.isArray(step.thenSteps))
+                    walk(step.thenSteps, depth + 1);
+                if (Array.isArray(step.elseSteps))
+                    walk(step.elseSteps, depth + 1);
+            }
+            else if (type === "whileLoop" || type === "forLoop") {
+                if (Array.isArray(step.bodySteps))
+                    walk(step.bodySteps, depth + 1);
+            }
+        }
+    };
+    walk(steps, 0);
+    return out;
+}
+function describeStep(type, step) {
+    const primary = stringField(step, "prompt") ??
+        stringField(step, "locatePrompt") ??
+        stringField(step, "conditionPrompt") ??
+        stringField(step, "packageName") ??
+        stringField(step, "bundleId") ??
+        stringField(step, "appRef") ??
+        stringField(step, "expression") ??
+        stringField(step, "title");
+    return primary ? `${type}: ${primary}` : type;
+}
+function stringField(step, key) {
+    const value = step[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}

package/dist/mcp/liveViewer.js

@@ -0,0 +1,156 @@
+import { createServer } from "node:http";
+export async function startLiveViewer(port, runManager) {
+    let lastError;
+    for (let candidate = port; candidate < port + 20; candidate += 1) {
+        try {
+            const server = createLiveViewerServer(runManager);
+            await listen(server, candidate);
+            return { server, port: candidate, baseUrl: `http://127.0.0.1:${candidate}` };
+        }
+        catch (error) {
+            lastError = error;
+            if (!isAddressInUse(error))
+                throw error;
+        }
+    }
+    throw lastError instanceof Error ? lastError : new Error(String(lastError));
+}
+function createLiveViewerServer(runManager) {
+    const server = createServer((req, res) => {
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        const runMatch = url.pathname.match(/^\/runs\/([^/]+)\/live$/);
+        if (runMatch) {
+            const run = runManager.getRun(decodeURIComponent(runMatch[1]));
+            if (!run) {
+                res.statusCode = 404;
+                res.end("run not found");
+                return;
+            }
+            res.setHeader("Content-Type", "text/html; charset=utf-8");
+            res.end(renderLivePage(run.runId));
+            return;
+        }
+        const apiMatch = url.pathname.match(/^\/api\/runs\/([^/]+)$/);
+        if (apiMatch) {
+            const run = runManager.getRun(decodeURIComponent(apiMatch[1]));
+            if (!run) {
+                res.statusCode = 404;
+                res.end(JSON.stringify({ message: "run not found" }));
+                return;
+            }
+            res.setHeader("Content-Type", "application/json; charset=utf-8");
+            res.end(JSON.stringify(run));
+            return;
+        }
+        res.statusCode = 404;
+        res.end("not found");
+    });
+    return server;
+}
+function listen(server, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (error) => {
+            server.off("listening", onListening);
+            reject(error);
+        };
+        const onListening = () => {
+            server.off("error", onError);
+            resolve();
+        };
+        server.once("error", onError);
+        server.once("listening", onListening);
+        server.listen(port, "127.0.0.1");
+    });
+}
+function isAddressInUse(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "EADDRINUSE";
+}
+function renderLivePage(runId) {
+    return `<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width,initial-scale=1" />
+  <title>Qingju Self Test ${escapeHtml(runId)}</title>
+  <style>
+    body { margin: 0; font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #f7f8fa; color: #15171a; }
+    header { padding: 16px 20px; background: #101214; color: white; }
+    main { display: grid; grid-template-columns: minmax(280px, 420px) 1fr; gap: 16px; padding: 16px; }
+    section { background: white; border: 1px solid #dfe3e8; border-radius: 8px; padding: 14px; min-width: 0; }
+    h1 { font-size: 16px; margin: 0 0 4px; }
+    h2 { font-size: 14px; margin: 0 0 10px; }
+    pre { white-space: pre-wrap; overflow-wrap: anywhere; background: #f1f3f5; padding: 10px; border-radius: 6px; max-height: 68vh; overflow: auto; }
+    .status { font-weight: 700; }
+    .artifact { display: block; margin: 6px 0; overflow-wrap: anywhere; }
+    .steps { display: grid; gap: 6px; }
+    .step { border: 1px solid #e5e7eb; border-radius: 6px; padding: 8px 10px; background: #fafafa; }
+    .step.running { border-color: #2f80ed; background: #eef6ff; }
+    .step.passed { border-color: #2f9e44; background: #effaf2; }
+    .step.failed { border-color: #d64545; background: #fff1f1; }
+    .step-title { font-size: 13px; font-weight: 650; overflow-wrap: anywhere; }
+    .step-meta { margin-top: 4px; color: #626b76; font-size: 12px; overflow-wrap: anywhere; }
+    @media (max-width: 820px) { main { grid-template-columns: 1fr; } }
+  </style>
+</head>
+<body>
+  <header>
+    <h1>Qingju Live Viewer</h1>
+    <div>Run ID: ${escapeHtml(runId)}</div>
+  </header>
+  <main>
+    <section>
+      <h2>状态</h2>
+      <div id="status" class="status">loading</div>
+      <p id="meta"></p>
+      <h2>产物</h2>
+      <div id="artifacts"></div>
+    </section>
+    <section>
+      <h2>Visual Flow 步骤</h2>
+      <div id="steps" class="steps"></div>
+      <h2>事件与任务快照</h2>
+      <pre id="raw"></pre>
+    </section>
+  </main>
+  <script>
+    const runId = ${JSON.stringify(runId)};
+    async function refresh() {
+      const resp = await fetch('/api/runs/' + encodeURIComponent(runId));
+      const run = await resp.json();
+      document.getElementById('status').textContent = run.task?.status || 'CREATED';
+      document.getElementById('meta').textContent = [run.platform, run.resourceId, run.taskId].filter(Boolean).join(' | ');
+      document.getElementById('artifacts').innerHTML = (run.artifacts || []).map(a => {
+        const text = a.type + ': ' + a.uri;
+        return '<a class="artifact" href="' + escapeAttr(a.uri) + '" target="_blank" rel="noreferrer">' + escapeText(text) + '</a>';
+      }).join('') || '暂无产物';
+      renderSteps(run.flowStepView);
+      document.getElementById('raw').textContent = JSON.stringify(run, null, 2);
+    }
+    function renderSteps(view) {
+      const steps = Array.isArray(view?.steps) ? view.steps : [];
+      document.getElementById('steps').innerHTML = steps.map(s => {
+        const depth = Number.isFinite(Number(s.depth)) ? Number(s.depth) : 0;
+        const meta = [
+          '#' + s.index,
+          s.type,
+          s.status,
+          s.durationMs != null ? s.durationMs + 'ms' : '',
+          s.message || ''
+        ].filter(Boolean).join(' | ');
+        return '<div class="step ' + escapeAttr(s.status || 'pending') + '" style="margin-left:' + Math.min(depth * 14, 56) + 'px">' +
+          '<div class="step-title">' + escapeText(s.title || s.type || 'step') + '</div>' +
+          '<div class="step-meta">' + escapeText(meta) + '</div>' +
+        '</div>';
+      }).join('') || '<div class="step"><div class="step-title">暂无 visualFlow 步骤</div></div>';
+    }
+    function escapeText(s) { return String(s).replace(/[&<>]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c])); }
+    function escapeAttr(s) { return escapeText(s).replace(/"/g, '&quot;'); }
+    refresh();
+    setInterval(refresh, 1500);
+  </script>
+</body>
+</html>`;
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"]/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", "\"": "&quot;" }[char] ?? char));
+}