e10-ebuilder-prototype 0.5.4 → 0.5.7

package/dist/html-inspect.js

@@ -1,11 +1,39 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { loadOfflinePage } from './offline-render.js';
 import { bounded, CaptureError, digest, fileDigest, atomicJson } from './common.js';
 import { launchChrome } from './capture.js';
 import { prepareHtml } from './html.js';
+import { reviewRevision, validateRepairReason } from './html-review-budget.js';
+/** One host call and at most one owned Chrome for the required form viewports. */
+export async function inspectHtmlViewports(store, state, pageId, token, kind = 'page', width, repairReason) {
+    validateRepairReason(repairReason);
+    if (kind === 'page' || width !== undefined)
+        return inspectHtml(store, state, pageId, token, kind, width, undefined, repairReason);
+    let chrome;
+    const started = Date.now();
+    try {
+        const getChrome = async () => (chrome ??= await launchChrome());
+        const inspections = [];
+        for (const w of [1440, 390])
+            inspections.push(await inspectHtml(store, state, pageId, token, kind, w, getChrome, repairReason));
+        if (new Set(inspections.map((r) => r.sourceSha256)).size !== 1)
+            throw new CaptureError('HTML_REVIEW_STALE', '两种视口校对期间草稿发生变化，请重新校对');
+        return {
+            ok: inspections.every((r) => r.ok),
+            reused: inspections.every((r) => r.reused),
+            inspections,
+            screenshots: inspections.flatMap((r) => r.screenshots),
+            elapsedMs: Date.now() - started,
+        };
+    }
+    finally {
+        await chrome?.close();
+    }
+}
 /** Deterministic local rendering, never a visual similarity assertion or model call. */
-export async function inspectHtml(store, state, pageId, token, kind = 'page', width) {
+export async function inspectHtml(store, state, pageId, token, kind = 'page', width, sharedChrome, repairReason) {
+    validateRepairReason(repairReason);
     const prepared = await prepareHtml(store, state, pageId, token, kind);
     const viewport = {
         width: width ?? (kind === 'page' ? prepared.png.width : 1440),
@@ -17,7 +45,7 @@ export async function inspectHtml(store, state, pageId, token, kind = 'page', wi
     await fs.mkdir(directory, { recursive: true });
     const receiptPath = path.join(directory, `inspection-${viewport.width}.json`);
     const sourceSha256 = digest(prepared.bytes);
-    const key = digest(JSON.stringify({ version: 3, sourceSha256, input: prepared.png.sha256, viewport }));
+    const key = digest(JSON.stringify({ version: 4, sourceSha256, input: prepared.png.sha256, viewport }));
     const old = await fs
         .readFile(receiptPath, 'utf8')
         .then(JSON.parse)
@@ -28,16 +56,17 @@ export async function inspectHtml(store, state, pageId, token, kind = 'page', wi
         if (valid.length && valid.every(Boolean))
             return { ...old, reused: true, receiptPath };
     }
+    const reviewBudget = await reviewRevision(directory, sourceSha256, repairReason);
     const started = Date.now();
     const errors = new Set();
     const runtimeErrors = [];
     const runtimeErrorDetails = [];
     const screenshots = [];
+    let fixedBehavior;
     const previewPath = path.join(directory, 'preview.html');
     await fs.writeFile(previewPath, prepared.bytes, { mode: 0o600 });
-    const previewUrl = pathToFileURL(previewPath).href;
     const sourceLines = prepared.bytes.toString('utf8').split(/\r?\n/);
-    const chrome = await launchChrome();
+    const chrome = await (sharedChrome ? sharedChrome() : launchChrome());
     try {
         const context = await chrome.browser.newContext({
             viewport,
@@ -45,52 +74,18 @@ export async function inspectHtml(store, state, pageId, token, kind = 'page', wi
             serviceWorkers: 'block',
         });
         try {
-            await context.route('**/*', async (route) => {
-                if (route.request().url() === previewUrl || /^(data:|about:)/.test(route.request().url()))
-                    await route.continue();
-                else {
-                    errors.add('页面尝试访问外部或旁路资源');
-                    await route.abort();
-                }
-            });
             const page = await context.newPage();
             try {
-                // Capture browser source locations, including parse errors without a JS stack.
-                await page.addInitScript(() => {
-                    ;
-                    window.__E10_INSPECTION_ERRORS__ = [];
-                    addEventListener('error', (event) => {
-                        const errors = window.__E10_INSPECTION_ERRORS__;
-                        if (errors.length < 10 && event.message)
-                            errors.push({
-                                message: event.message.slice(0, 500),
-                                url: event.filename,
-                                line: event.lineno,
-                                column: event.colno,
-                            });
-                    });
-                });
-                page.on('pageerror', (error) => {
-                    errors.add('页面存在 JavaScript 运行错误');
-                    if (runtimeErrors.length < 10)
-                        runtimeErrors.push(`${error.name}: ${error.message}`.slice(0, 500));
-                });
-                page.on('websocket', () => errors.add('页面尝试建立网络连接'));
                 await bounded((async () => {
-                    await page.goto(previewUrl, { waitUntil: 'load', timeout: 10000 });
-                    if (kind === 'form') {
-                        try {
-                            await page.waitForFunction(() => window.__E10_FORM_READY__ === true ||
-                                window.__E10_INSPECTION_ERRORS__?.length > 0, undefined, { timeout: 10000 });
-                        }
-                        catch (error) {
-                            if (!(error instanceof Error) || error.name !== 'TimeoutError')
-                                throw error;
-                        }
-                        if (!(await page.evaluate(() => window.__E10_FORM_READY__ === true)))
-                            errors.add('表单未完成初始化，检查脚本错误及 __E10_FORM_READY__ 设置');
-                    }
-                    await page.evaluate(() => document.fonts.ready);
+                    const rendered = await loadOfflinePage(page, previewPath, kind === 'form');
+                    for (const error of rendered.errors)
+                        errors.add(error);
+                    runtimeErrors.push(...rendered.runtimeErrors);
+                    if (kind === 'form')
+                        fixedBehavior = await page.evaluate(() => ({
+                            initialized: window.__E10_FORM_BEHAVIOR__?.initialized === true,
+                            limitations: (window.__E10_FORM_BEHAVIOR__?.limitations || []).slice(0, 40),
+                        }));
                     const layout = await page.evaluate(() => ({
                         height: Math.max(document.documentElement.scrollHeight, document.body.scrollHeight),
                         width: Math.max(document.documentElement.scrollWidth, document.body.scrollWidth),
@@ -124,7 +119,7 @@ export async function inspectHtml(store, state, pageId, token, kind = 'page', wi
                     }
                     const browserErrors = await page.evaluate(() => window.__E10_INSPECTION_ERRORS__ || []);
                     for (const error of browserErrors.slice(0, 10)) {
-                        if (error.url !== previewUrl || !Number.isInteger(error.line) || error.line < 1)
+                        if (error.url !== rendered.url || !Number.isInteger(error.line) || error.line < 1)
                             continue;
                         runtimeErrorDetails.push({
                             message: String(error.message).slice(0, 500),
@@ -145,7 +140,8 @@ export async function inspectHtml(store, state, pageId, token, kind = 'page', wi
         }
     }
     finally {
-        await chrome.close();
+        if (!sharedChrome)
+            await chrome.close();
     }
     const current = await prepareHtml(store, state, pageId, token, kind);
     if (digest(current.bytes) !== sourceSha256)
@@ -159,9 +155,11 @@ export async function inspectHtml(store, state, pageId, token, kind = 'page', wi
         errors: [...errors],
         runtimeErrors,
         runtimeErrorDetails,
+        fixedBehavior,
         elapsedMs: Date.now() - started,
         reviewedAt: new Date().toISOString(),
         visual: 'host-review-required',
+        reviewBudget,
     };
     await atomicJson(receiptPath, receipt);
     return { ...receipt, reused: false, receiptPath };

package/dist/html-interact.d.ts

@@ -0,0 +1,36 @@
+import type { Store } from './store.js';
+import type { TaskState } from './model.js';
+type Step = {
+    action: 'click' | 'fill' | 'select' | 'press' | 'check' | 'uncheck' | 'reload' | 'assert';
+    selector?: string;
+    value?: string;
+    dialog?: 'accept' | 'dismiss';
+    check?: 'visible' | 'hidden' | 'text' | 'value' | 'count';
+    expected?: string | number;
+};
+export declare function parseInteractionPlan(raw: string): Step[];
+/** Fixed, token-private offline interaction runner. No server, new dependencies or arbitrary scripts. */
+export declare function interactHtml(store: Store, state: TaskState, pageId: string, token: string, kind: 'page' | 'form', stepsFile: string, width?: number): Promise<{
+    receiptPath: string;
+    ok: boolean;
+    sourceSha256: string;
+    steps: Step[];
+    results: {
+        index: number;
+        action: string;
+        ok: boolean;
+        error?: string;
+    }[];
+    errors: string[];
+    screenshots: {
+        path: string;
+        sha256: string;
+    }[];
+    viewport: {
+        width: number;
+        height: number;
+    };
+    elapsedMs: number;
+    checkedAt: string;
+}>;
+export {};

package/dist/html-interact.js

@@ -0,0 +1,216 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { atomicJson, bounded, CaptureError, digest } from './common.js';
+import { launchChrome } from './capture.js';
+import { prepareHtml } from './html.js';
+import { loadOfflinePage } from './offline-render.js';
+export function parseInteractionPlan(raw) {
+    const invalid = (field, expected, index) => {
+        const step = index === undefined ? undefined : index + 1;
+        throw new CaptureError('INTERACTION_PLAN_INVALID', `${step === undefined ? '' : `第 ${step} 步：`}${field} ${expected}；只修正步骤 JSON 后重跑 html interact，无需重生成 HTML 或重跑 inspect`, { field, ...(step === undefined ? {} : { step }), expected });
+    };
+    if (raw.length > 64000)
+        invalid('plan', '不能超过 64KB');
+    let plan;
+    try {
+        plan = JSON.parse(raw);
+    }
+    catch {
+        invalid('plan', '必须是合法 JSON 对象，例如 {"steps":[{"action":"assert","selector":"h1","check":"visible"}]}');
+    }
+    if (!plan || typeof plan !== 'object' || Array.isArray(plan))
+        invalid('plan', '必须是含 steps 数组的对象 {"steps":[...]}，不能直接传数组');
+    const steps = plan?.steps;
+    if (!Array.isArray(steps) || !steps.length || steps.length > 40)
+        invalid('steps', '必须是 1..40 个操作的数组');
+    for (const [index, s] of steps.entries()) {
+        const field = `steps[${index}]`;
+        if (!s || typeof s !== 'object' || Array.isArray(s))
+            invalid(field, '必须是操作对象', index);
+        if (!['click', 'fill', 'select', 'press', 'check', 'uncheck', 'reload', 'assert'].includes(s.action))
+            invalid(`${field}.action`, '必须是 click/fill/select/press/check/uncheck/reload/assert，无脚本执行', index);
+        if (s.action !== 'reload' &&
+            (typeof s.selector !== 'string' || !s.selector.trim() || s.selector.length > 500))
+            invalid(`${field}.selector`, '必须是 1..500 字符的非空 CSS 选择器', index);
+        if (['fill', 'select', 'press'].includes(s.action) &&
+            (typeof s.value !== 'string' || s.value.length > 4000))
+            invalid(`${field}.value`, '必须是最多 4000 字符的字符串，例如 "李四" 或 "Enter"', index);
+        if (s.dialog !== undefined && !['accept', 'dismiss'].includes(s.dialog))
+            invalid(`${field}.dialog`, '只能是 "accept" 或 "dismiss"', index);
+        if (s.action === 'assert') {
+            if (!['visible', 'hidden', 'text', 'value', 'count'].includes(s.check))
+                invalid(`${field}.check`, '必须是 visible/hidden/text/value/count', index);
+            if (['text', 'value'].includes(s.check) &&
+                (typeof s.expected !== 'string' || s.expected.length > 4000))
+                invalid(`${field}.expected`, `${s.check} 断言要求最多 4000 字符的字符串，例如 "已保存"`, index);
+            if (s.check === 'count' &&
+                (!Number.isInteger(s.expected) || s.expected < 0 || s.expected > 10000))
+                invalid(`${field}.expected`, 'count 断言要求 0..10000 的整数，例如 6，不能写成字符串 "6"', index);
+        }
+    }
+    if (steps.at(-1).action !== 'assert')
+        invalid(`steps[${steps.length - 1}].action`, '最后一步必须是 assert 结果断言', steps.length - 1);
+    return steps;
+}
+async function runStep(page, step) {
+    if (step.action === 'reload') {
+        await page.reload({ waitUntil: 'load', timeout: 5000 });
+        return;
+    }
+    const target = page.locator(step.selector);
+    switch (step.action) {
+        case 'click':
+            await target.click();
+            return;
+        case 'fill':
+            await target.fill(step.value);
+            return;
+        case 'select':
+            await target.selectOption(step.value);
+            return;
+        case 'press':
+            await target.press(step.value);
+            return;
+        case 'check':
+            await target.check();
+            return;
+        case 'uncheck':
+            await target.uncheck();
+            return;
+    }
+    // Retry DOM assertions briefly for event handlers that update asynchronously.
+    const deadline = Date.now() + 2500;
+    let actual;
+    do {
+        if (step.check === 'visible') {
+            actual = await target.isVisible();
+            if (actual)
+                return;
+        }
+        if (step.check === 'hidden') {
+            actual = await target.isVisible();
+            if (!actual)
+                return;
+        }
+        if (step.check === 'text') {
+            actual = await target.innerText();
+            if (actual === step.expected)
+                return;
+        }
+        if (step.check === 'value') {
+            actual = await target.inputValue();
+            if (actual === step.expected)
+                return;
+        }
+        if (step.check === 'count') {
+            actual = await target.count();
+            if (actual === step.expected)
+                return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 50));
+    } while (Date.now() < deadline);
+    throw new CaptureError('INTERACTION_ASSERTION_FAILED', `${step.check} 断言失败：${step.selector}；实际值 ${JSON.stringify(actual)?.slice(0, 500)}`);
+}
+/** Fixed, token-private offline interaction runner. No server, new dependencies or arbitrary scripts. */
+export async function interactHtml(store, state, pageId, token, kind, stepsFile, width = 1440) {
+    if (!Number.isInteger(width) || width < 320 || width > 3840)
+        throw new CaptureError('ARGUMENT_INVALID', '交互检查宽度范围 320..3840');
+    const stat = await fs.lstat(stepsFile);
+    if (!stat.isFile() || stat.size > 64000)
+        throw new CaptureError('INTERACTION_PLAN_INVALID', 'steps 必须为不超过 64KB 的普通 JSON 文件');
+    const steps = parseInteractionPlan(await fs.readFile(stepsFile, 'utf8'));
+    const prepared = await prepareHtml(store, state, pageId, token, kind);
+    const sourceSha256 = digest(prepared.bytes);
+    const directory = path.join(path.dirname(prepared.draft), 'review');
+    await fs.mkdir(directory, { recursive: true });
+    const previewPath = path.join(directory, 'interaction-preview.html');
+    await fs.writeFile(previewPath, prepared.bytes, { mode: 0o600 });
+    const started = Date.now(), results = [];
+    const errors = [], screenshots = [];
+    const chrome = await launchChrome();
+    try {
+        const context = await chrome.browser.newContext({
+            viewport: { width, height: 900 },
+            offline: true,
+            serviceWorkers: 'block',
+        });
+        try {
+            const page = await context.newPage();
+            page.setDefaultTimeout(2500);
+            let dialogPolicy = 'dismiss';
+            page.on('dialog', async (dialog) => {
+                await (dialogPolicy === 'accept' ? dialog.accept() : dialog.dismiss()).catch(() => { });
+            });
+            context.on('page', (popup) => {
+                if (popup !== page) {
+                    errors.push('交互尝试打开新窗口');
+                    void popup.close().catch(() => { });
+                }
+            });
+            try {
+                await bounded((async () => {
+                    const loaded = await loadOfflinePage(page, previewPath, kind === 'form');
+                    if (!loaded.ok)
+                        errors.push(...loaded.errors, ...loaded.runtimeErrors);
+                    if (loaded.ok)
+                        for (const [index, step] of steps.entries()) {
+                            dialogPolicy = step.dialog || 'dismiss';
+                            try {
+                                await runStep(page, step);
+                                if (page.url().split('#')[0] !== loaded.url)
+                                    throw new Error('交互离开当前离线页面');
+                                results.push({ index, action: step.action, ok: true });
+                            }
+                            catch (error) {
+                                results.push({
+                                    index,
+                                    action: step.action,
+                                    ok: false,
+                                    error: String(error).slice(0, 1000),
+                                });
+                                break;
+                            }
+                            if (loaded.errors.length || loaded.runtimeErrors.length || errors.length)
+                                break;
+                        }
+                    errors.push(...loaded.errors, ...loaded.runtimeErrors);
+                    const browserErrors = await page.evaluate(() => window.__E10_INSPECTION_ERRORS__ || []);
+                    errors.push(...browserErrors.map((e) => String(e.message).slice(0, 500)));
+                    const screenshotPath = path.join(directory, 'interaction-final.png');
+                    const bytes = await page.screenshot({ timeout: 5000, animations: 'disabled' });
+                    await fs.writeFile(screenshotPath, bytes, { mode: 0o600 });
+                    screenshots.push({ path: screenshotPath, sha256: digest(bytes) });
+                })(), 30000, 'HTML_INTERACTION_TIMEOUT');
+            }
+            catch (error) {
+                errors.push(String(error).slice(0, 1000));
+            }
+            finally {
+                await bounded(page.close(), 8000, 'PAGE_CLOSE_TIMEOUT');
+            }
+        }
+        finally {
+            await bounded(context.close(), 8000, 'CONTEXT_CLOSE_TIMEOUT');
+        }
+    }
+    finally {
+        await chrome.close();
+    }
+    const current = await prepareHtml(store, state, pageId, token, kind);
+    if (digest(current.bytes) !== sourceSha256)
+        throw new CaptureError('HTML_REVIEW_STALE', '交互期间草稿发生变化，请重新验证');
+    const receiptPath = path.join(directory, 'interaction.json');
+    const receipt = {
+        ok: !errors.length && results.length === steps.length && results.every((r) => r.ok),
+        sourceSha256,
+        steps,
+        results,
+        errors: [...new Set(errors)],
+        screenshots,
+        viewport: { width, height: 900 },
+        elapsedMs: Date.now() - started,
+        checkedAt: new Date().toISOString(),
+    };
+    await atomicJson(receiptPath, receipt);
+    return { ...receipt, receiptPath };
+}

package/dist/html-review-budget.d.ts

@@ -0,0 +1,9 @@
+export declare function validateRepairReason(reason?: string): string | undefined;
+/** One writer per token. Both viewports and damaged-image repairs share a revision. */
+export declare function reviewRevision(directory: string, sha256: string, reason?: string): Promise<{
+    historyPath: string;
+    repairReason?: any;
+    revision: any;
+    standardRevisionLimit: number;
+    remainingStandardRevisions: number;
+}>;

package/dist/html-review-budget.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { atomicJson, CaptureError } from './common.js';
+export function validateRepairReason(reason) {
+    if (reason !== undefined && (!reason.trim() || reason.trim().length > 500))
+        throw new CaptureError('ARGUMENT_INVALID', '--repair-reason 需要 1..500 字符的具体内容/业务/运行错误说明');
+    return reason?.trim();
+}
+/** One writer per token. Both viewports and damaged-image repairs share a revision. */
+export async function reviewRevision(directory, sha256, reason) {
+    reason = validateRepairReason(reason);
+    const filename = path.join(directory, 'review-history.json');
+    let history;
+    try {
+        history = JSON.parse(await fs.readFile(filename, 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw new CaptureError('HTML_REVIEW_HISTORY', '校对轮次记录无法读取，保留记录并报告错误');
+        history = { schema: 1, revisions: [] };
+    }
+    if (history.schema !== 1 ||
+        !Array.isArray(history.revisions) ||
+        history.revisions.some((r) => !r || typeof r.sourceSha256 !== 'string'))
+        throw new CaptureError('HTML_REVIEW_HISTORY', '校对轮次记录格式无效，不能重置计数继续检查');
+    let index = history.revisions.findIndex((r) => r.sourceSha256 === sha256);
+    if (index === -1) {
+        if (history.revisions.length >= 3 && !reason)
+            throw new CaptureError('HTML_REVIEW_BUDGET', '已校对首版及两轮修正。停止装饰微调；若仍有缺模块、业务或运行错误，修复后追加 --repair-reason 说明具体问题；未完成不能 ready。');
+        index = history.revisions.length;
+        history.revisions.push({
+            sourceSha256: sha256,
+            firstAttemptAt: new Date().toISOString(),
+            ...(reason ? { repairReason: reason } : {}),
+        });
+        await atomicJson(filename, history);
+    }
+    return {
+        revision: index + 1,
+        standardRevisionLimit: 3,
+        remainingStandardRevisions: Math.max(0, 3 - history.revisions.length),
+        ...(history.revisions[index].repairReason
+            ? { repairReason: history.revisions[index].repairReason }
+            : {}),
+        historyPath: filename,
+    };
+}

package/dist/html.d.ts

@@ -1,15 +1,99 @@
 import type { HtmlResult, PageResult, TaskState, FormCollection } from './model.js';
 import { Store } from './store.js';
+export { parseHostActiveTokens } from './host-ledger.js';
 export declare function draftPath(store: Store, r: HtmlResult): string;
 export declare function nextHtml(store: Store, s: TaskState, options?: {
     brief?: boolean;
+    activeTokens?: string[];
 }): Promise<{
     state: string;
     concurrency: number;
     host: {
-        modelPolicy: string;
-        scheduling: string;
+        code?: string | undefined;
+        fix?: string | undefined;
+        background: string;
+        agentTeams: string;
+        backgroundTasks: string;
+        evidenceSource: string;
+        evidenceScope: string;
+        verification: string;
         maxVisualCorrections: number;
+        watch?: {
+            command: string;
+            args: string[];
+            mode: string;
+        } | undefined;
+        availableSlots?: number | undefined;
+        dispatchTokens?: string[] | undefined;
+        slots?: ({
+            token: string;
+            htmlStatus: string;
+            checkReason: string;
+            reviewSubmitted: boolean;
+            kind?: undefined;
+            pageId?: undefined;
+            name?: undefined;
+            lastLocalActivityAt?: undefined;
+            localIdleMs?: undefined;
+        } | {
+            token: string;
+            kind: "page" | "form";
+            pageId: string;
+            name: string;
+            htmlStatus: "running" | "succeeded" | "failed" | "pending";
+            reviewSubmitted: boolean;
+            lastLocalActivityAt: string;
+            localIdleMs: number;
+            checkReason: string | undefined;
+        })[] | undefined;
+        observationState?: string | undefined;
+        reconcile?: ({
+            token: string;
+            htmlStatus: string;
+            checkReason: string;
+            reviewSubmitted: boolean;
+            kind?: undefined;
+            pageId?: undefined;
+            name?: undefined;
+            lastLocalActivityAt?: undefined;
+            localIdleMs?: undefined;
+        } | {
+            token: string;
+            kind: "page" | "form";
+            pageId: string;
+            name: string;
+            htmlStatus: "running" | "succeeded" | "failed" | "pending";
+            reviewSubmitted: boolean;
+            lastLocalActivityAt: string;
+            localIdleMs: number;
+            checkReason: string | undefined;
+        })[] | undefined;
+        activeTokens?: string[] | undefined;
+        activeCount?: number | undefined;
+        activeCountMeaning?: string | undefined;
+        deliveredAwaitingExit?: number | undefined;
+        scheduling: string;
+        schedulingInstruction: string;
+        completionPolicy: string;
+        workers?: {
+            taskId: string;
+            token: string;
+            kind: "page" | "form";
+            pageId: string;
+            startedAt: string;
+            nativeName?: string;
+            outcome?: string;
+            endedAt?: string;
+        }[] | undefined;
+        accounting?: string | undefined;
+        terminalWithoutHandoff?: {
+            taskId: string;
+            token: string;
+            pageId: string;
+            kind: "page" | "form";
+            outcome: string | undefined;
+            next: string;
+        }[] | undefined;
     };
     jobs: any[];
     html: {