minimal-agent 0.8.2 → 0.10.0

package/src/web/browserBridge.js

@@ -0,0 +1,447 @@
+import { randomUUID } from 'node:crypto';
+import { rm } from 'node:fs/promises';
+import { configService } from '../config/configService.js';
+import { resolveAgentBrowserPath } from '../tools/webbrowser/agentBrowserPath.js';
+import { browserProfilePath, sessionArgs, spawnRunner } from '../tools/webbrowser/browser.js';
+import { ensureDaemon, stopDaemon } from '../tools/webbrowser/browserDaemon.js';
+import { browserService } from '../tools/webbrowser/browserService.js';
+import { getBrowserStream, } from '../tools/webbrowser/browserStream.js';
+function normalizeUrl(value) {
+    const input = value.trim();
+    if (/^[a-z][a-z0-9+.-]*:/i.test(input))
+        return input;
+    return `https://${input}`;
+}
+function requireAllowedDeveloperOrigin(url, allowedOrigins) {
+    let origin;
+    try {
+        origin = new URL(url).origin;
+    }
+    catch {
+        throw new Error('当前页面没有可授权的 HTTP(S) 站点');
+    }
+    if (!/^https?:\/\//i.test(origin) || !allowedOrigins.includes(origin)) {
+        throw new Error(`Developer Mode 尚未授权当前站点：${origin}。请在“设置 → 浏览器”添加该站点。`);
+    }
+    return origin;
+}
+function parseJsonOutput(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return undefined;
+    try {
+        const value = JSON.parse(trimmed);
+        if (typeof value === 'string') {
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return value;
+            }
+        }
+        return value;
+    }
+    catch {
+        return trimmed;
+    }
+}
+function pickScript(x, y) {
+    return `(() => {
+    const el = document.elementFromPoint(${Math.round(x)}, ${Math.round(y)});
+    if (!el) return null;
+    const r = el.getBoundingClientRect();
+    const attrs = {};
+    for (const a of Array.from(el.attributes || []).slice(0, 16)) attrs[a.name] = String(a.value).slice(0, 300);
+    const escape = (v) => CSS.escape(String(v));
+    let selector = el.id ? '#' + escape(el.id) : el.tagName.toLowerCase();
+    if (!el.id && el.classList && el.classList.length) selector += '.' + Array.from(el.classList).slice(0, 2).map(escape).join('.');
+    if (!el.id) {
+      const same = Array.from(document.querySelectorAll(selector));
+      if (same.length > 1) selector += ':nth-of-type(' + (Array.from(el.parentElement?.children || []).filter((n) => n.tagName === el.tagName).indexOf(el) + 1) + ')';
+    }
+    const role = el.getAttribute('role') || ({A:'link',BUTTON:'button',INPUT:'textbox',SELECT:'combobox',TEXTAREA:'textbox',IMG:'img'}[el.tagName] || undefined);
+    const accessibleName = el.getAttribute('aria-label') || el.getAttribute('alt') || el.getAttribute('title') || String(el.innerText || el.textContent || '').trim().slice(0, 160);
+    return { ref: selector, tag: el.tagName.toLowerCase(), role, accessibleName, text: String(el.innerText || el.textContent || '').trim().slice(0, 1000), boundingBox: { x: r.x, y: r.y, width: r.width, height: r.height }, attributes: attrs };
+  })()`;
+}
+function mapStreamEvent(event) {
+    switch (event.type) {
+        case 'frame':
+            return { t: 'browser/frame', data: String(event.data ?? ''), metadata: event.metadata,
+                frameWidth: Number(event.frameWidth ?? event.width ?? event.metadata?.width ?? 0) || undefined,
+                frameHeight: Number(event.frameHeight ?? event.height ?? event.metadata?.height ?? 0) || undefined,
+                viewportWidth: Number(event.viewportWidth ?? 0) || undefined,
+                viewportHeight: Number(event.viewportHeight ?? 0) || undefined,
+                deviceScaleFactor: Number(event.deviceScaleFactor ?? 1) || 1 };
+        case 'status':
+            return {
+                t: 'browser/status',
+                connected: Boolean(event.connected),
+                screencasting: Boolean(event.screencasting ?? event.screencast),
+                viewportWidth: Number(event.viewportWidth ?? event.width ?? 1280),
+                viewportHeight: Number(event.viewportHeight ?? event.height ?? 720),
+                engine: 'agent-browser',
+            };
+        case 'tabs': {
+            const tabs = Array.isArray(event.tabs) ? event.tabs : [];
+            return { t: 'browser/tabs', tabs: tabs.map((tab) => {
+                    const item = tab;
+                    return { id: String(item.tabId ?? item.id ?? ''), url: String(item.url ?? ''), title: typeof item.title === 'string' ? item.title : undefined, active: Boolean(item.active), favicon: typeof item.favicon === 'string' ? item.favicon : undefined };
+                }) };
+        }
+        case 'url': return { t: 'browser/url', url: String(event.url ?? ''), tabId: typeof event.tabId === 'string' ? event.tabId : undefined };
+        case 'title': return { t: 'browser/title', title: String(event.title ?? ''), tabId: typeof event.tabId === 'string' ? event.tabId : undefined };
+        case 'navigation': return { t: 'browser/navigation', url: String(event.url ?? ''), state: (event.state === 'start' || event.state === 'commit' || event.state === 'domcontentloaded') ? event.state : 'load' };
+        case 'console': return { t: 'browser/console', level: typeof event.level === 'string' ? event.level : undefined, text: String(event.text ?? '') };
+        case 'page_error': return { t: 'browser/page_error', text: String(event.text ?? event.message ?? '') };
+        case 'dialog': return { t: 'browser/dialog', type: (event.dialogType ?? event.kind ?? 'alert'), message: String(event.message ?? ''), defaultValue: typeof event.defaultValue === 'string' ? event.defaultValue : undefined };
+        case 'error': return { t: 'browser/error', message: String(event.message ?? '浏览器流错误') };
+        case 'mode': return { t: 'browser/mode', mode: event.mode };
+        case 'marked_elements': return { t: 'browser/marked/elements', elements: (event.elements ?? []) };
+        case 'agent_acting': return { t: 'browser/agent/acting', acting: Boolean(event.acting), action: typeof event.action === 'string' ? event.action : undefined, target: typeof event.target === 'string' ? event.target : undefined };
+        case 'control_state': return { t: 'browser/control/changed', state: event.state };
+        default: return null;
+    }
+}
+export function createBrowserBridge(send, sessionName = 'minimal-agent') {
+    let disposed = false;
+    let activeTabId = '';
+    let pageRevision = randomUUID();
+    const stream = getBrowserStream(sessionName);
+    const unsubscribe = stream.subscribe((event) => {
+        if (disposed)
+            return;
+        if (event.type === 'url' || event.type === 'navigation')
+            pageRevision = randomUUID();
+        if (event.type === 'tabs' && Array.isArray(event.tabs)) {
+            const active = event.tabs.find((tab) => Boolean(tab.active));
+            activeTabId = String(active?.tabId ?? active?.id ?? activeTabId);
+        }
+        const mapped = mapStreamEvent(event);
+        if (mapped?.t === 'browser/frame')
+            send({ ...mapped, tabId: activeTabId || mapped.tabId, pageRevision });
+        else if (mapped)
+            send(mapped);
+        if (event.type === 'control_state') {
+            const state = event.state;
+            if (state?.status === 'waiting_human' && state.reason !== 'manual') {
+                const summary = state.reason === 'captcha' ? '页面需要人工完成安全验证'
+                    : state.reason === 'otp' ? '页面需要人工输入一次性验证码'
+                        : state.reason === 'login' ? '页面需要人工登录'
+                            : state.reason === 'permission' ? '页面需要人工确认权限'
+                                : '网站已暂停或拦截当前访问';
+                send({
+                    t: 'browser/challenge/detected',
+                    reason: state.reason,
+                    summary,
+                    resumeToken: state.resumeToken,
+                    runId: state.runId,
+                    ...(state.conversationKey ? { conversationKey: state.conversationKey } : {}),
+                });
+            }
+        }
+    });
+    const run = async (args) => {
+        const bin = await resolveAgentBrowserPath();
+        if (!bin)
+            throw new Error('未找到内置 agent-browser');
+        await ensureDaemon(sessionName);
+        const result = await browserService.run({ sessionName, bin, args: [...sessionArgs(sessionName), ...args], runner: spawnRunner });
+        if (result.code !== 0)
+            throw new Error((result.stderr || result.stdout || `exit ${result.code}`).trim());
+        return result.stdout.trim();
+    };
+    const ensureStarted = async () => {
+        const config = await configService.browser();
+        if (!config.enabled)
+            throw new Error('内置浏览器已在设置中关闭');
+        const info = await ensureDaemon(sessionName);
+        await stream.connect();
+        return info;
+    };
+    const applyViewport = async (widthValue, heightValue) => {
+        const width = Math.max(320, Math.round(Number(widthValue)));
+        const height = Math.max(240, Math.round(Number(heightValue)));
+        if (!Number.isFinite(width) || !Number.isFinite(height))
+            throw new Error('无效的浏览器视口尺寸');
+        await run(['set', 'viewport', String(width), String(height)]);
+        // agent-browser starts its CDP screencast with the dimensions that were
+        // active when the viewer connected. Reconnect only the viewer so the next
+        // frame is encoded at the new viewport without touching tabs or profile.
+        if (stream.isConnected()) {
+            stream.disconnect();
+            await stream.connect();
+        }
+    };
+    const pick = async (x, y) => {
+        const value = parseJsonOutput(await run(['eval', pickScript(x, y)]));
+        if (!value || typeof value !== 'object')
+            return null;
+        return value;
+    };
+    stream.setPicker(pick);
+    const result = (frame, ok, data, error) => send({
+        t: 'browser/result', requestId: frame.requestId, action: frame.t, ok,
+        ...(typeof data === 'string' ? { content: data } : data === undefined ? {} : { data }),
+        ...(error ? { error } : {}),
+    });
+    return {
+        async handle(frame) {
+            if (disposed)
+                return;
+            try {
+                switch (frame.t) {
+                    case 'browser/start': {
+                        const info = await ensureStarted();
+                        const viewport = frame.viewport;
+                        if (viewport?.width && viewport?.height)
+                            await applyViewport(viewport.width, viewport.height);
+                        send({ t: 'browser/started', requestId: frame.requestId, streamPort: info.streamPort, pid: info.pid, sessionId: sessionName });
+                        result(frame, true, info);
+                        return;
+                    }
+                    case 'browser/stop':
+                        stream.disconnect();
+                        await stopDaemon(sessionName);
+                        send({ t: 'browser/stopped', requestId: frame.requestId });
+                        return;
+                    case 'browser/profile/clear':
+                        stream.disconnect();
+                        await stopDaemon(sessionName);
+                        await rm(browserProfilePath('default'), { recursive: true, force: true });
+                        send({ t: 'browser/stopped', requestId: frame.requestId });
+                        result(frame, true);
+                        return;
+                    case 'browser/mode':
+                        stream.setMode(frame.mode);
+                        result(frame, true);
+                        return;
+                    case 'browser/control/get':
+                        send({ t: 'browser/control/changed', state: stream.getControlState() });
+                        return;
+                    case 'browser/control/takeover':
+                        stream.requestHuman('manual');
+                        result(frame, true, stream.getControlState());
+                        return;
+                    case 'browser/control/resume': {
+                        const ok = stream.resumeControl(typeof frame.resumeToken === 'string' ? frame.resumeToken : undefined);
+                        result(frame, ok, stream.getControlState(), ok ? undefined : '浏览器接管请求已失效');
+                        return;
+                    }
+                    case 'browser/control/stop':
+                        stream.stopControl(typeof frame.resumeToken === 'string' ? frame.resumeToken : undefined);
+                        result(frame, true, stream.getControlState());
+                        return;
+                    case 'browser/user/input': {
+                        const type = String(frame.eventType ?? '');
+                        if (type.startsWith('mouse'))
+                            stream.send({ type: 'input_mouse', ...frame, t: undefined });
+                        else
+                            stream.send({ type: 'input_keyboard', ...frame, t: undefined });
+                        return;
+                    }
+                    case 'browser/navigate': {
+                        await ensureStarted();
+                        const url = normalizeUrl(String(frame.url ?? ''));
+                        await run(frame.newTab ? ['tab', 'new', url] : ['open', url]);
+                        stream.setCurrentUrl(url);
+                        result(frame, true);
+                        return;
+                    }
+                    case 'browser/back':
+                        await run(['back']);
+                        result(frame, true);
+                        return;
+                    case 'browser/forward':
+                        await run(['forward']);
+                        result(frame, true);
+                        return;
+                    case 'browser/reload':
+                        await run(['reload']);
+                        result(frame, true);
+                        return;
+                    case 'browser/tab/new':
+                        await run(frame.url ? ['tab', 'new', normalizeUrl(String(frame.url))] : ['tab', 'new']);
+                        result(frame, true);
+                        return;
+                    case 'browser/tab/close':
+                        await run(frame.tabId ? ['tab', 'close', String(frame.tabId)] : ['tab', 'close']);
+                        result(frame, true);
+                        return;
+                    case 'browser/tab/switch':
+                        await run(['tab', 'switch', String(frame.tabId)]);
+                        result(frame, true);
+                        return;
+                    case 'browser/tabs':
+                        result(frame, true, parseJsonOutput(await run(['tab', 'list'])));
+                        return;
+                    case 'browser/pick': {
+                        const element = await pick(Number(frame.x), Number(frame.y));
+                        if (!element) {
+                            send({ t: 'browser/picked', requestId: frame.requestId, error: '该位置没有可选元素' });
+                            return;
+                        }
+                        stream.markElement(element);
+                        const item = element;
+                        send({ t: 'browser/picked', requestId: frame.requestId, reference: {
+                                id: randomUUID(), url: stream.getCurrentUrl(), tabId: activeTabId, selector: item.ref,
+                                tag: item.tag, role: item.role, accessibleName: item.accessibleName, text: item.text,
+                                attributes: item.attributes ?? {}, boundingBox: item.boundingBox, pageRevision, capturedAt: Date.now(),
+                            }, ...element });
+                        return;
+                    }
+                    case 'browser/mark/element': {
+                        const raw = parseJsonOutput(await run(['eval', `(() => { const el=document.querySelector(${JSON.stringify(String(frame.selector))}); if(!el)return null; const r=el.getBoundingClientRect(); return {ref:${JSON.stringify(String(frame.selector))},tag:el.tagName.toLowerCase(),text:String(el.innerText||el.textContent||'').trim().slice(0,1000),boundingBox:{x:r.x,y:r.y,width:r.width,height:r.height}} })()`]));
+                        if (!raw || typeof raw !== 'object')
+                            throw new Error('未找到该元素');
+                        stream.markElement({ ...raw, label: typeof frame.label === 'string' ? frame.label : undefined, color: typeof frame.color === 'string' ? frame.color : undefined });
+                        result(frame, true);
+                        return;
+                    }
+                    case 'browser/mark/clear':
+                        stream.clearMarkedElements();
+                        result(frame, true);
+                        return;
+                    case 'browser/viewport':
+                        await ensureStarted();
+                        await applyViewport(frame.width, frame.height);
+                        result(frame, true);
+                        return;
+                    case 'browser/dialog/accept':
+                        await run(frame.text ? ['dialog', 'accept', '--text', String(frame.text)] : ['dialog', 'accept']);
+                        result(frame, true);
+                        return;
+                    case 'browser/dialog/dismiss':
+                        await run(['dialog', 'dismiss']);
+                        result(frame, true);
+                        return;
+                    case 'browser/snapshot': {
+                        const tree = await run(['snapshot']);
+                        send({ t: 'browser/snapshot', requestId: frame.requestId, tree });
+                        return;
+                    }
+                    case 'browser/getContent': {
+                        const text = await run(['get', 'text', String(frame.selector ?? 'body')]);
+                        send({ t: 'browser/content', requestId: frame.requestId, text });
+                        return;
+                    }
+                    case 'browser/click':
+                        await run(['click', String(frame.selector)]);
+                        result(frame, true);
+                        return;
+                    case 'browser/fill':
+                        await run(['fill', String(frame.selector), String(frame.value ?? '')]);
+                        result(frame, true);
+                        return;
+                    case 'browser/type':
+                        await run(['type', String(frame.selector), String(frame.value ?? '')]);
+                        result(frame, true);
+                        return;
+                    case 'browser/hover':
+                        await run(['hover', String(frame.selector)]);
+                        result(frame, true);
+                        return;
+                    case 'browser/scroll': {
+                        const args = frame.selector ? ['scrollintoview', String(frame.selector)] : ['scroll', String(frame.direction ?? 'down'), String(Math.abs(Number(frame.y ?? 600)))];
+                        await run(args);
+                        result(frame, true);
+                        return;
+                    }
+                    case 'browser/select':
+                        await run(['select', String(frame.selector), ...(Array.isArray(frame.value) ? frame.value.map(String) : [String(frame.value ?? '')])]);
+                        result(frame, true);
+                        return;
+                    case 'browser/press':
+                        await run(['press', String(frame.key)]);
+                        result(frame, true);
+                        return;
+                    case 'browser/wait':
+                        await run(frame.selector ? ['wait', String(frame.selector)] : frame.text ? ['wait', '--text', String(frame.text)] : ['wait', String(frame.ms ?? 500)]);
+                        result(frame, true);
+                        return;
+                    case 'browser/eval':
+                        result(frame, true, parseJsonOutput(await run(['eval', String(frame.js ?? '')])));
+                        return;
+                    case 'browser/upload':
+                        await run(['upload', String(frame.selector), ...(Array.isArray(frame.files) ? frame.files.map(String) : [])]);
+                        result(frame, true);
+                        return;
+                    case 'browser/drag':
+                        await run(['drag', String(frame.fromSelector), String(frame.toSelector)]);
+                        result(frame, true);
+                        return;
+                    case 'browser/screenshot': {
+                        const args = ['screenshot', ...(frame.path ? [String(frame.path)] : []), ...(frame.annotate ? ['--annotate'] : []), ...(frame.fullPage ? ['--full'] : [])];
+                        const output = await run(args);
+                        send({ t: 'browser/screenshot', requestId: frame.requestId, path: typeof frame.path === 'string' ? frame.path : undefined, data: output });
+                        return;
+                    }
+                    case 'browser/pdf': {
+                        const output = await run(['pdf', String(frame.path ?? '')]);
+                        result(frame, true, output);
+                        return;
+                    }
+                    case 'browser/cookies/get':
+                        send({ t: 'browser/cookies', requestId: frame.requestId, cookies: parseJsonOutput(await run(['cookies', 'get'])) ?? [] });
+                        return;
+                    case 'browser/cookies/clear':
+                        await run(['cookies', 'clear']);
+                        result(frame, true);
+                        return;
+                    case 'browser/device':
+                        await run(frame.preset ? ['set', 'device', String(frame.preset)] : ['set', 'viewport', String(frame.width), String(frame.height)]);
+                        result(frame, true);
+                        return;
+                    case 'browser/media':
+                        await run(['set', 'media', String(frame.scheme ?? 'no-preference')]);
+                        result(frame, true);
+                        return;
+                    case 'browser/record/start':
+                        await run(['record', 'start', String(frame.path ?? '')]);
+                        result(frame, true);
+                        return;
+                    case 'browser/record/stop':
+                        result(frame, true, await run(['record', 'stop']));
+                        return;
+                    case 'browser/debug/console':
+                    case 'browser/debug/errors':
+                    case 'browser/debug/network':
+                    case 'browser/debug/styles':
+                    case 'browser/debug/vitals':
+                    case 'browser/debug/trace/start':
+                    case 'browser/debug/trace/stop': {
+                        const browserConfig = await configService.browser();
+                        if (!browserConfig.developerMode)
+                            throw new Error('请先在“设置 → 浏览器”开启完整 CDP Developer Mode');
+                        requireAllowedDeveloperOrigin(stream.getCurrentUrl(), browserConfig.allowedCdpOrigins);
+                        if (frame.t === 'browser/debug/console')
+                            result(frame, true, await run(['console']));
+                        else if (frame.t === 'browser/debug/errors')
+                            result(frame, true, await run(['errors']));
+                        else if (frame.t === 'browser/debug/network')
+                            result(frame, true, parseJsonOutput(await run(['network', 'requests', '--json'])));
+                        else if (frame.t === 'browser/debug/styles')
+                            result(frame, true, parseJsonOutput(await run(['get', 'styles', String(frame.selector ?? 'body'), '--json'])));
+                        else if (frame.t === 'browser/debug/vitals')
+                            result(frame, true, parseJsonOutput(await run(['vitals', ...(frame.url ? [String(frame.url)] : []), '--json'])));
+                        else if (frame.t === 'browser/debug/trace/start') {
+                            await run(['trace', 'start']);
+                            result(frame, true);
+                        }
+                        else
+                            result(frame, true, await run(['trace', 'stop', ...(frame.path ? [String(frame.path)] : [])]));
+                        return;
+                    }
+                    default:
+                        result(frame, false, undefined, `暂不支持浏览器操作：${frame.t}`);
+                }
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                result(frame, false, undefined, message);
+                send({ t: 'browser/error', message });
+            }
+        },
+        dispose() { disposed = true; unsubscribe(); },
+    };
+}

package/src/web/protocol.js

@@ -0,0 +1,19 @@
+/**
+ * ============================================================
+ *  src/web/protocol.ts —— Web/Gateway WebSocket 线路协议（ClientFrame/ServerFrame）
+ * ------------------------------------------------------------
+ *  ⚠️ 不变量：本文件必须保持**纯 type-only**（只有 `import type` / `export type` /
+ *  `export interface`，零运行时 import/export）。webchat（浏览器）靠
+ *  `export type … from '../../src/web/protocol.js'` **单一真源**引用这里，
+ *  而它能安全 import 后端目录的唯一原因是：整条链全是 type，打包器（Vite/esbuild）
+ *  在编译期把它擦除干净，绝不把 `node:*` 依赖拉进浏览器 bundle。
+ *
+ *  一旦这里出现**任何运行时** import/export（哪怕一个 helper 函数），
+ *  webchat bundle 就会顺着链把 `src/types.ts`→`plugins/**` 的 node 代码拖进浏览器 →
+ *  **静默**打断前端构建。`test/webProtocolTypeOnly.test.ts` 守这条线（改动会报红）。
+ *
+ *  同理它 `import type` 了具体插件 `cron-runner` 的类型：仅因 type-only 才不构成
+ *  内核对插件的运行时耦合；下游若要新增插件资源帧，务必同样只引 type。
+ * ============================================================
+ */
+export {};

package/workflows/adaptive-research.yaml

@@ -12,21 +12,27 @@ inputs:
   - name: topic
     type: string
     required: true
-    description: "调研主题"
+    greedy: true
+    description: "调研主题（可直接一句话自然语言；命令行整句进 topic，不被空格拆碎）"
 
 steps:
   # 1. agent 节点：开放式调研，自主决定怎么做，产出笔记并自我验证
   - id: research
+    title: "1/3·自主调研写笔记"
     agent: |
       调研主题「${inputs.topic}」：用你手上的工具搜集 3-5 个关键要点，
       整理成简洁的中文 markdown，写到 ./out/notes.md（目录不存在就先创建）。
       写完后用 Read 自检文件确实写好了再收尾。
     allowed_tools: [Read, Write, Edit, Bash, Grep, Glob]
+    # 确定性完成条件：模型「宣告要写却没写」时引擎自动提醒续跑（announce-not-do 兜底）
+    done_when: "fileExists('./out/notes.md')"
     capture:
-      content: notes
+      # agent 步 raw 只有 text/result（无 content）——曾绑 content 导致 notes 恒 undefined
+      text: notes
 
   # 2. 确定性工具，但带 onError: recover —— 出意外就地自愈，而非崩停
   - id: count_lines
+    title: "2/3·统计笔记行数"
     tool: Bash
     args:
       command: "wc -l ./out/notes.md"
@@ -35,8 +41,10 @@ steps:
     capture:
       content: line_report
 
-  # 3. 守门 assert
+  # 3. 守门 verify（升级自 assert，享受 verify 的 file_exists 检查器）
   - id: verify
-    type: assert
-    condition: 'fileExists("./out/notes.md")'
+    title: "3/3·守门校验"
+    type: verify
+    checks:
+      - 'file_exists:./out/notes.md'
     onFail: "调研笔记 ./out/notes.md 未生成，检查 research 步"

package/workflows/book-review-short.yaml

@@ -1,27 +1,31 @@
 name: book-review-short
 description: |
   从书名生成 YouTube Shorts 书评短视频（60 秒）：
-  调研 → 60 秒口播脚本 → 缩略图 prompt → meta.json。
-  P0 跑通 steps 1/2/3/5/6/7（step 4 loop/钩子标题 P1 启用）。
+  调研 → 60 秒口播脚本 → 缩略图 prompt + 真生图（可降级）→ meta.json。
+  step 4（loop 生成钩子标题）P1 启用。
 version: "0.1"
 
 inputs:
   - name: book
     type: string
     required: true
-    description: "书名（中英都行）"
+    greedy: true
+    description: "书名（中英都行，可一句话自然语言；命令行整句进 book，不被空格拆碎）"
   - name: angle
     type: enum
     values: [insight, contrarian, beginner]
     default: insight
+    description: "【高级·用 --input angle=...】切入角度"
   - name: lang
     type: enum
     values: [zh, en]
     default: zh
+    description: "【高级·用 --input lang=...】输出语言"
 
 steps:
   # 1. 调研（确定性工具）
   - id: research
+    title: "1/7·调研书评素材"
     tool: WebSearch
     args:
       query: "${inputs.book} 核心观点 书评 ${inputs.lang}"
@@ -30,6 +34,7 @@ steps:
 
   # 2. 60 秒短视频脚本（llm 单轮，不开工具）
   - id: script
+    title: "2/7·写 60 秒口播脚本"
     llm: |
       你是一名 YouTube Shorts 创作者。基于以下调研，为书 "${inputs.book}" 写一段
       60 秒口播脚本，视角是 ${inputs.angle}（insight=洞察、contrarian=逆向、beginner=入门）。
@@ -48,27 +53,36 @@ steps:
 
   # 3. 写脚本到文件（确定性工具）
   - id: write_script
+    title: "3/7·脚本落盘"
     tool: Write
     args:
       file_path: "videos/${inputs.book}/script.txt"
       content: "${script_text}"
 
   # 4. 生成 3 个钩子标题（loop + llm）—— P1 启用
+  # ⚠️ 启用前注意：step id 必须是静态字符串（id: hook_${idx} 这种动态 id 会破坏
+  #    checkpoint/resume 的步骤寻址）。正确写法：静态 id + 累积变量拼接，如下。
   # - id: gen_hooks
   #   type: loop
   #   over: "[1, 2, 3]"
   #   as: idx
   #   do:
-  #     - id: hook_${idx}
+  #     - id: gen_one_hook
+  #       title: "生成第 ${idx} 个钩子标题"
   #       llm: |
   #         为 "${inputs.book}" 书评 Shorts 生成第 ${idx} 个标题（≤20 字 / ≤8 words）。
   #         风格序号 1=金句、2=反问、3=数字承诺。
   #         只输出标题本体。
   #       capture:
-  #         text: hook_${idx}
+  #         text: hook_text
+  #     - id: accumulate_hook
+  #       type: set
+  #       set:
+  #         hooks_text: "${hooks_text}${idx}. ${hook_text}\n"
 
   # 5. 缩略图 prompt（llm 单轮）
   - id: thumbnail
+    title: "4/7·生成缩略图提示词"
     llm: |
       为书 "${inputs.book}" 的 YouTube Shorts 缩略图生成英文文生图 prompt：
       - 主体：书 + 一个隐喻物
@@ -79,21 +93,33 @@ steps:
     capture:
       text: thumb_prompt
 
+  # 5b. 真生成缩略图（可选：缺 OPENROUTER_API_KEY 时降级只留 prompt，不挡流水线）
+  - id: gen_thumbnail
+    title: "5/7·生成缩略图（可降级）"
+    skill: image-gen-openrouter
+    input: 'prompt=${thumb_prompt} output=videos/${inputs.book}/thumbnail.png aspect=9:16'
+    onError: continue
+
   # 6. 元数据汇总（确定性工具）
+  # json() 生成含外层引号的合法 JSON 字符串——裸 "${thumb_prompt}" 在值含引号/换行时产坏 JSON
   - id: meta
+    title: "6/7·汇总 meta.json"
     tool: Write
     args:
       file_path: "videos/${inputs.book}/meta.json"
       content: |
         {
-          "book": "${inputs.book}",
+          "book": ${json(inputs.book)},
           "angle": "${inputs.angle}",
           "lang": "${inputs.lang}",
-          "thumbnail_prompt": "${thumb_prompt}"
+          "thumbnail_prompt": ${json(thumb_prompt)}
         }
 
-  # 7. 守门 assert
+  # 7. 守门 verify（升级自 assert；多条 file_exists 拆成 checks 数组）
   - id: verify
-    type: assert
-    condition: 'fileExists("videos/${inputs.book}/script.txt") && fileExists("videos/${inputs.book}/meta.json")'
+    title: "7/7·守门校验"
+    type: verify
+    checks:
+      - 'file_exists:videos/${inputs.book}/script.txt'
+      - 'file_exists:videos/${inputs.book}/meta.json'
     onFail: "脚本或 meta 未写盘，请检查 Write 工具"

package/workflows/e2e-write-greet.yaml

@@ -9,6 +9,7 @@ inputs:
 
 steps:
   - id: write_note
+    title: "1/3·写入便签"
     tool: Write
     args:
       file_path: "out/${inputs.topic}/note.txt"
@@ -17,11 +18,14 @@ steps:
       args.content: note_body
 
   - id: verify_file
-    type: assert
-    condition: 'fileExists("out/${inputs.topic}/note.txt")'
+    title: "2/3·校验落盘"
+    type: verify
+    checks:
+      - 'file_exists:out/${inputs.topic}/note.txt'
     onFail: "note.txt 未落盘"
 
   - id: verify_capture
+    title: "3/3·校验 capture"
     type: assert
     condition: 'length(note_body) > 0'
     onFail: "capture 没绑到 note_body"