e10-ebuilder-prototype 0.5.4 → 0.5.7

package/dist/index.js

@@ -1,24 +1,22 @@
 #!/usr/bin/env node
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { hostCapabilities, workBuddyHostBlocker, isHostDiagnosticCommand, } from './runtime-support.mjs';
 import { parseArgs } from 'node:util';
 import { CaptureError, errorInfo, VERSION, digest } from './common.js';
-import { Store } from './store.js';
-import { fetchPages, fetchCatalog } from './platform.js';
-import { capture, launchChrome } from './capture.js';
-import { pack } from './archive.js';
-import { inspectHtml } from './html-inspect.js';
-import { readyHtml, acceptReadyHtml } from './html-handoff.js';
-import { nextHtml, acceptHtml, failHtml, retryHtml } from './html.js';
-import { discoverMenus } from './menus.js';
-import { collectForms } from './forms.js';
-import { applicationInput } from './application.js';
-import { readEnvironmentAuthContext, readEnvironmentAuthStatus, readActiveEnvironmentAuthProfile, setEnvironmentAuth, verifyEnvironmentAuth, listEnvironmentAuthProfiles, useEnvironmentAuthProfile, } from './vendor/environment-auth.js';
+import { parseHostEvents, parseHostActiveTokens, updateHostLedger } from './host-ledger.js';
 const spec = {
     json: { type: 'boolean' },
     brief: { type: 'boolean' },
     refill: { type: 'boolean' },
     'accept-ready': { type: 'boolean' },
+    'host-active-tokens': { type: 'string' },
+    'host-events': { type: 'string' },
+    'after-state': { type: 'string' },
+    'watch-ms': { type: 'string' },
     summary: { type: 'string' },
+    'repair-reason': { type: 'string' },
+    steps: { type: 'string' },
     help: { type: 'boolean' },
     version: { type: 'boolean' },
     'app-id': { type: 'string' },
@@ -41,6 +39,7 @@ const spec = {
     reason: { type: 'string' },
 };
 let secret = '';
+let pendingOutput;
 const safeAuth = (s) => ({
     authenticated: s.authenticated,
     status: s.status,
@@ -55,14 +54,18 @@ run --app-url URL --dir DIR [--json]
 init --app-id ID --dir DIR [--allow-temporary-records]
 next|status|discover|collect|capture|pack|retry --dir DIR
 html next --dir DIR (allocate/resume up to concurrency host-AI jobs)
-html inspect --dir DIR --kind page|form --page-id ID --token TOKEN [--width 390]
+html inspect --dir DIR --kind page|form --page-id ID --token TOKEN [--width 390] [--repair-reason TEXT]
+html interact --dir DIR --kind page|form --page-id ID --token TOKEN --steps FILE [--width 390]
 html ready --dir DIR --kind page|form --page-id ID --token TOKEN --summary TEXT
-html next --dir DIR --accept-ready --brief
+html next --dir DIR --accept-ready --brief [--host-events '[]'] (durable worker identities)
+html watch --dir DIR --host-active-tokens '["TOKEN"]' [--after-state DIGEST --watch-ms 60000]
 html accept --dir DIR --kind page|form --page-id ID --token TOKEN [--refill --brief]
 html fail --dir DIR --kind page|form --page-id ID --token TOKEN --reason TEXT
 html retry --dir DIR [--kind page|form --page-id ID] (retry failures, or regenerate one target)
 run pauses at HTML for host AI; after accept, run/pack builds the ZIP.
-retry: retry failed pages and rebuild archive; run resumes interrupted work.
+retry: explicitly retry failed sources and HTML; verified successes are reused.
+run/capture resume pending work but never retry failed screenshots.
+Task settings are fixed at init. Resume reports effectiveSettings; conflicting flags fail.
 auth set --base-url URL --eteamsid-stdin (also supports --eteamsid VALUE)
 auth status [--local]
 auth profile list|current|use NAME
@@ -76,16 +79,27 @@ async function main() {
         strict: true,
     });
     const command = pos[0];
+    const hostEvents = v['host-events'] === undefined ? undefined : parseHostEvents(v['host-events']);
+    if ((hostEvents !== undefined && !(command === 'html' && pos[1] === 'next')) ||
+        (hostEvents !== undefined && v['host-active-tokens'] !== undefined))
+        throw new CaptureError('ARGUMENT_INVALID', '--host-events 只用于 html next，不能与 --host-active-tokens 混用');
+    const activeTokens = v['host-active-tokens'] === undefined
+        ? undefined
+        : parseHostActiveTokens(v['host-active-tokens']);
+    if (activeTokens !== undefined &&
+        !(command === 'html' &&
+            (['next', 'watch'].includes(pos[1]) || (v.refill && ['accept', 'fail'].includes(pos[1])))))
+        throw new CaptureError('ARGUMENT_INVALID', '--host-active-tokens 仅用于 html next/watch 或 accept/fail --refill');
+    if ((v['after-state'] !== undefined || v['watch-ms'] !== undefined) &&
+        !(command === 'html' && pos[1] === 'watch'))
+        throw new CaptureError('ARGUMENT_INVALID', '--after-state/--watch-ms 仅用于 html watch');
+    if (v['repair-reason'] !== undefined && !(command === 'html' && pos[1] === 'inspect'))
+        throw new CaptureError('ARGUMENT_INVALID', '--repair-reason 仅用于 html inspect');
+    if (v.steps !== undefined && !(command === 'html' && pos[1] === 'interact'))
+        throw new CaptureError('ARGUMENT_INVALID', '--steps 仅用于 html interact');
     const output = (value) => {
-        if (v.json)
-            console.log(JSON.stringify(value));
-        else {
-            const { next, fix, ...rest } = value;
-            console.log(JSON.stringify(rest, null, 2));
-            if (fix)
-                console.log(`FIX: ${fix}`);
-            console.log(`NEXT: ${next || 'none'}`);
-        }
+        // Final output is committed only after the transaction releases its lock.
+        pendingOutput = { value, json: !!v.json };
     };
     if (v.help || (!command && !v.version)) {
         if (v.json)
@@ -98,7 +112,14 @@ async function main() {
         output({ version: VERSION, next: 'none' });
         return;
     }
+    const hostBlocker = workBuddyHostBlocker();
+    if (hostBlocker && !isHostDiagnosticCommand(pos)) {
+        output(hostBlocker);
+        process.exitCode = 1;
+        return;
+    }
     if (command === 'doctor') {
+        const { launchChrome } = await import('./capture.js');
         const chrome = await launchChrome();
         const version = chrome.version;
         await chrome.close();
@@ -109,11 +130,13 @@ async function main() {
             platform: process.platform,
             chrome: version,
             defaultConcurrency: 6,
+            host: hostCapabilities(),
             next: 'auth status',
         });
         return;
     }
     if (command === 'auth') {
+        const { AUTH_REQUIRED_FIX, readEnvironmentAuthStatus, readActiveEnvironmentAuthProfile, setEnvironmentAuth, verifyEnvironmentAuth, listEnvironmentAuthProfiles, useEnvironmentAuthProfile, } = await import('./vendor/environment-auth.js');
         if (pos[1] === 'set') {
             if (!v['base-url'])
                 throw new CaptureError('ARGUMENT_REQUIRED', '需要 --base-url');
@@ -142,6 +165,7 @@ async function main() {
             const status = v.local ? readEnvironmentAuthStatus() : await verifyEnvironmentAuth();
             output({
                 ...safeAuth(status),
+                ...(!status.authenticated ? { fix: AUTH_REQUIRED_FIX } : {}),
                 next: status.authenticated ? 'run --app-id ID --dir DIR' : 'auth set',
             });
             return;
@@ -176,6 +200,7 @@ async function main() {
         throw new CaptureError('COMMAND_INVALID', `未知命令: ${command}`);
     if (!v.dir)
         throw new CaptureError('ARGUMENT_REQUIRED', '需要 --dir');
+    const { Store } = await import('./store.js');
     const store = new Store(v.dir);
     const settings = {};
     for (const [arg, key, min, max] of [
@@ -195,13 +220,15 @@ async function main() {
     }
     const report = async (s) => {
         const { results, htmlResults, formResults, formHtmlResults, ...status } = await store.status(s);
-        const local = ['DISCOVER', 'COLLECT', 'CAPTURE'].includes(status.state)
-            ? readEnvironmentAuthStatus()
-            : { authenticated: true };
+        const failedSources = status.failed + status.collection.failed;
+        const auth = ['DISCOVER', 'COLLECT', 'CAPTURE'].includes(status.state)
+            ? await import('./vendor/environment-auth.js')
+            : undefined;
+        const local = auth ? auth.readEnvironmentAuthStatus() : { authenticated: true };
         const state = !local.authenticated && ['DISCOVER', 'COLLECT', 'CAPTURE'].includes(status.state)
             ? 'WAITING_AUTH'
             : status.state;
-        const next = state === 'WAITING_AUTH'
+        let next = state === 'WAITING_AUTH'
             ? 'auth set'
             : state === 'DISCOVER'
                 ? 'discover'
@@ -216,17 +243,43 @@ async function main() {
                                 : state === 'PARTIAL'
                                     ? 'retry'
                                     : 'none';
+        // A capture failure must come with its exact recovery command, even when
+        // successful form inputs have already moved the overall state to HTML.
+        if (failedSources && command !== 'retry' && state !== 'WAITING_AUTH' && state !== 'DISCOVER')
+            next = 'retry';
         output({
             ...status,
             state,
+            ...(state === 'WAITING_AUTH' ? { fix: auth.AUTH_REQUIRED_FIX } : {}),
             appId: s.appId,
             directory: store.root,
+            effectiveSettings: s.settings,
+            ...(failedSources
+                ? {
+                    sourceRecovery: {
+                        command: process.execPath,
+                        args: [fileURLToPath(import.meta.url), 'retry', '--dir', store.root, '--json'],
+                        reuseVerifiedSuccesses: true,
+                        attemptedThisCommand: command === 'retry',
+                        guidance: command === 'retry'
+                            ? '本次已重试。仍失败时保留原因并继续可生成项，交付标明 PARTIAL；没有新证据不要循环重试。'
+                            : '需要重试失败源时直接执行此命令一次。run/capture 不重试失败项；不要查 help、重建目录或尝试加超时参数。',
+                    },
+                }
+                : {}),
             warnedPages: results
                 .filter((r) => r?.status === 'succeeded' && r.warnings?.length)
                 .map((r) => ({ id: r.id, name: r.name, warnings: r.warnings })),
             failedPages: results
                 .filter((r) => r?.status === 'failed')
-                .map((r) => ({ id: r.id, name: r.name, error: r.history.at(-1)?.error })),
+                .map((r) => ({
+                id: r.id,
+                name: r.name,
+                stage: r.history.at(-1)?.stage,
+                attempts: r.history.length,
+                elapsedMs: r.history.at(-1)?.elapsedMs,
+                error: r.history.at(-1)?.error,
+            })),
             generationJobs: [...htmlResults, ...formHtmlResults]
                 .filter((r) => r?.status === 'running')
                 .map((r) => ({
@@ -253,10 +306,28 @@ async function main() {
             process.exitCode = 2;
     };
     if (command === 'status' || command === 'next') {
-        await report(await store.load());
+        const s = await store.load();
+        store.assertSettings(s, settings);
+        await report(s);
+        return;
+    }
+    if (command === 'html' && pos[1] === 'watch') {
+        const { watchHost } = await import('./host-watch.js');
+        if (activeTokens === undefined)
+            throw new CaptureError('ARGUMENT_REQUIRED', 'html watch 需要 --host-active-tokens');
+        if (Object.keys(settings).length || v.refill || v['accept-ready'])
+            throw new CaptureError('ARGUMENT_INVALID', 'html watch 只读，不接受队列修改或任务设置');
+        output(await watchHost(store, {
+            activeTokens,
+            afterState: v['after-state'],
+            watchMs: v['watch-ms'] === undefined ? undefined : Number(v['watch-ms']),
+        }));
         return;
     }
-    if (command === 'html' && ['inspect', 'ready'].includes(pos[1])) {
+    if (command === 'html' && ['inspect', 'interact', 'ready'].includes(pos[1])) {
+        const ignored = Object.keys(settings).filter((key) => !(['inspect', 'interact'].includes(pos[1]) && key === 'width'));
+        if (ignored.length)
+            throw new CaptureError('ARGUMENT_INVALID', `html ${pos[1]} 不支持这些参数：${ignored.join(', ')}；校对仅支持 --width`);
         const kind = v.kind || 'page';
         if (kind !== 'page' && kind !== 'form')
             throw new CaptureError('ARGUMENT_INVALID', 'kind 必须为 page 或 form');
@@ -267,10 +338,22 @@ async function main() {
         const reviewLock = new Store(path.join(store.meta, 'inspection-locks', digest(`${kind}:${v['page-id']}:${v.token}`)));
         await reviewLock.lock(async () => {
             if (pos[1] === 'ready') {
+                const { readyHtml } = await import('./html-handoff.js');
                 output(await readyHtml(store, await store.load(), v['page-id'], v.token, kind, v.summary || ''));
                 return;
             }
-            const inspection = await inspectHtml(store, await store.load(), v['page-id'], v.token, kind, settings.width);
+            if (pos[1] === 'interact') {
+                if (!v.steps)
+                    throw new CaptureError('ARGUMENT_REQUIRED', 'html interact 需要 --steps JSON文件');
+                const { interactHtml } = await import('./html-interact.js');
+                const result = await interactHtml(store, await store.load(), v['page-id'], v.token, kind, path.resolve(v.steps), settings.width);
+                output({ ...result, next: result.ok ? 'host-review' : 'repair-draft' });
+                if (!result.ok)
+                    process.exitCode = 1;
+                return;
+            }
+            const { inspectHtmlViewports } = await import('./html-inspect.js');
+            const inspection = await inspectHtmlViewports(store, await store.load(), v['page-id'], v.token, kind, settings.width, v['repair-reason']);
             output({ ...inspection, next: inspection.ok ? 'host-review' : 'repair-draft' });
             if (!inspection.ok)
                 process.exitCode = 1;
@@ -281,6 +364,7 @@ async function main() {
         let s;
         if (command === 'init' || command === 'run') {
             if (v['app-id'] || v['app-url']) {
+                const { applicationInput } = await import('./application.js');
                 const input = applicationInput(v['app-url'] || v['app-id']);
                 if (v['app-id'] && applicationInput(v['app-id']).appId !== input.appId)
                     throw new CaptureError('APP_INPUT_CONFLICT', '应用 ID 与地址不一致');
@@ -300,6 +384,7 @@ async function main() {
         }
         else
             s = await store.load();
+        store.assertSettings(s, settings);
         if (v['allow-temporary-records']) {
             if (!['run', 'init'].includes(command))
                 throw new CaptureError('ARGUMENT_INVALID', '临时记录开关只能在 init/run 时启用');
@@ -313,17 +398,23 @@ async function main() {
             return;
         }
         if (command === 'pack') {
+            const { pack } = await import('./archive.js');
             await pack(store, s);
             await report(s);
             return;
         }
         if (command === 'html') {
+            const { nextHtml, acceptHtml, failHtml, retryHtml } = await import('./html.js');
             const kind = v.kind || 'page';
             if (kind !== 'page' && kind !== 'form')
                 throw new CaptureError('ARGUMENT_INVALID', 'kind 必须为 page 或 form');
             if (pos[1] === 'next') {
-                const handoff = v['accept-ready'] ? await acceptReadyHtml(store, s) : undefined;
-                output({ ...(await nextHtml(store, s, { brief: v.brief })), ...handoff });
+                if (hostEvents !== undefined)
+                    await updateHostLedger(store, s, hostEvents);
+                const handoff = v['accept-ready']
+                    ? await (await import('./html-handoff.js')).acceptReadyHtml(store, s)
+                    : undefined;
+                output({ ...(await nextHtml(store, s, { brief: v.brief, activeTokens })), ...handoff });
                 return;
             }
             if (pos[1] === 'retry') {
@@ -343,13 +434,13 @@ async function main() {
                 await failHtml(store, s, v['page-id'], v.token, v.reason, kind);
             }
             if (v.refill)
-                output(await nextHtml(store, s, { brief: v.brief }));
+                output(await nextHtml(store, s, { brief: v.brief, activeTokens }));
             else
                 await report(s);
             return;
         }
         if (command === 'retry')
-            await retryHtml(store, s);
+            await (await import('./html.js')).retryHtml(store, s);
         const before = await store.status(s);
         const needsCapture = ['capture', 'run', 'retry'].includes(command) &&
             (before.pending > 0 || (command === 'retry' && before.failed > 0));
@@ -365,14 +456,16 @@ async function main() {
         if (command === 'collect' && (!s.formPages || !s.menus))
             throw new CaptureError('CATALOG_REQUIRED', '先执行 discover 获取发布菜单');
         if (needsDiscover || needsCapture || needsCollect) {
+            const { readEnvironmentAuthContext } = await import('./vendor/environment-auth.js');
             const auth = readEnvironmentAuthContext();
             secret = auth.eteamsId;
             store.bind(s, auth);
             await store.save(s);
             if (needsDiscover) {
                 if (s.menuRequired)
-                    Object.assign(s, await discoverMenus(auth, s.appId));
+                    Object.assign(s, await (await import('./menus.js')).discoverMenus(auth, s.appId));
                 else {
+                    const { fetchPages, fetchCatalog } = await import('./platform.js');
                     if (!s.pages)
                         s.pages = await fetchPages(auth, s.appId);
                     if (s.siteRequired && (!s.forms || !s.appName))
@@ -382,26 +475,55 @@ async function main() {
                 await store.save(s);
             }
             if (s.menuRequired && ['collect', 'run', 'retry'].includes(command))
-                await collectForms(store, s, auth, command === 'retry');
+                await (await import('./forms.js')).collectForms(store, s, auth, command === 'retry');
             if (['capture', 'run', 'retry'].includes(command))
-                await capture(store, s, auth, {
+                await (await import('./capture.js')).capture(store, s, auth, {
                     retryFailed: command === 'retry',
                     progress: (event) => console.error(JSON.stringify(event)),
                 });
         }
         if ((command === 'run' || command === 'retry') && (await store.status(s)).state === 'PACKAGE')
-            await pack(store, s);
+            await (await import('./archive.js')).pack(store, s);
         await report(s);
     });
 }
-main().catch((e) => {
-    const error = errorInfo(e, secret);
+main()
+    .then(() => {
+    if (!pendingOutput)
+        return;
+    const { value, json } = pendingOutput;
+    if (json)
+        console.log(JSON.stringify(value));
+    else {
+        const { next, fix, ...rest } = value;
+        console.log(JSON.stringify(rest, null, 2));
+        if (fix)
+            console.log(`FIX: ${fix}`);
+        console.log(`NEXT: ${next || 'none'}`);
+    }
+})
+    .catch(async (e) => {
+    let error = errorInfo(e, secret);
+    const guard = error.code.startsWith('SAFE_DELETE_BULK_')
+        ? error.message.match(/\[safe-delete\]\[SAFE_DELETE_BULK_[A-Z_]+\][^\r\n]*/)?.[0]
+        : undefined;
+    if (guard) {
+        // WorkBuddy parses the first marker in stdout + stderr as raw JSON.
+        // A marker escaped inside our JSON hides the actual authorization signal.
+        // Preserve the native signal on stderr; structured stdout retains its code.
+        console.error(guard);
+        error = JSON.parse(JSON.stringify(error).replaceAll('[safe-delete][SAFE_DELETE_BULK_', 'WorkBuddy[SAFE_DELETE_BULK_'));
+    }
     const value = {
         ok: false,
         error,
-        fix: error.code === 'E10_LOGIN_REQUIRED'
-            ? '执行 auth set 后用原目录重新 run'
-            : '根据 error 修正后用原目录恢复',
+        fix: error.code.startsWith('SAFE_DELETE_BULK_')
+            ? 'WorkBuddy 宿主删除保护阻塞了命令。停止自动重试并保留草稿/回执/锁；不要手删锁目录、切换删除方式或改安全设置。由宿主正常授权流程处理后，先核对现有回执和原生任务状态，再用原目录恢复；不要把本次当作完成或重新生成页面。'
+            : error.code === 'E10_LOGIN_REQUIRED'
+                ? (await import('./vendor/environment-auth.js')).AUTH_REQUIRED_FIX
+                : error.code === 'SETTINGS_MISMATCH'
+                    ? '按 error.details.effectiveSettings 恢复：移除不同参数；截图失败执行 retry，run/capture 不会重试失败项。'
+                    : '根据 error 修正后用原目录恢复',
         next: 'none',
     };
     if (process.argv.includes('--json'))

package/dist/model.d.ts

@@ -117,9 +117,10 @@ export interface HtmlResult {
     kind?: 'page' | 'form';
     status: 'pending' | 'running' | 'succeeded' | 'failed';
     token: string;
+    dispatchName?: string;
     attempt: number;
     sourceSha256: string;
-    promptVersion: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+    promptVersion: 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17;
     startedAt: string;
     finishedAt?: string;
     file?: string;

package/dist/offline-render.d.ts

@@ -0,0 +1,11 @@
+import type { Page } from 'playwright-core';
+/** Inspect and pack must execute the same bytes under the same file-origin rules. */
+export declare function loadOfflinePage(page: Page, filename: string, form: boolean): Promise<{
+    ok: boolean;
+    stage: string;
+    ready: boolean;
+    errors: string[];
+    runtimeErrors: string[];
+    details: any;
+    url: string;
+}>;

package/dist/offline-render.js

@@ -0,0 +1,71 @@
+import { pathToFileURL } from 'node:url';
+import { bounded } from './common.js';
+/** Inspect and pack must execute the same bytes under the same file-origin rules. */
+export async function loadOfflinePage(page, filename, form) {
+    const url = pathToFileURL(filename).href;
+    const errors = [], runtimeErrors = [];
+    let stage = 'navigation';
+    page.on('pageerror', (error) => {
+        if (runtimeErrors.length < 10)
+            runtimeErrors.push(`${error.name}: ${error.message}`.slice(0, 500));
+    });
+    page.on('websocket', () => errors.push('页面尝试建立网络连接'));
+    await page.route('**/*', async (route) => {
+        if (route.request().url() === url || /^(data:|about:)/.test(route.request().url()))
+            await route.continue();
+        else {
+            if (errors.length < 10)
+                errors.push('页面尝试访问外部或旁路资源');
+            await route.abort();
+        }
+    });
+    await page.addInitScript(() => {
+        ;
+        window.__E10_INSPECTION_ERRORS__ = [];
+        const record = (message, url = '', line = 0, column = 0) => {
+            const entries = window.__E10_INSPECTION_ERRORS__;
+            if (entries.length < 10)
+                entries.push({ message: String(message).slice(0, 500), url, line, column });
+        };
+        addEventListener('error', (e) => {
+            if (e.message)
+                record(e.message, e.filename, e.lineno, e.colno);
+        });
+        addEventListener('unhandledrejection', (e) => record(e.reason?.message || String(e.reason)));
+    });
+    try {
+        await page.goto(url, { waitUntil: 'load', timeout: 10000 });
+        stage = 'initialization';
+        if (form)
+            await page.waitForFunction(() => window.__E10_FORM_READY__ === true ||
+                window.__E10_INSPECTION_ERRORS__?.length > 0, undefined, { timeout: 10000 });
+        stage = 'fonts';
+        await bounded(page.evaluate(() => document.fonts.ready), 10000, 'FORM_FONTS_TIMEOUT');
+        stage = 'ready';
+    }
+    catch (error) {
+        errors.push(`${stage}: ${error instanceof Error ? error.message : String(error)}`.slice(0, 700));
+    }
+    const evidence = await page
+        .evaluate(() => ({
+        ready: window.__E10_FORM_READY__ === true,
+        details: window.__E10_INSPECTION_ERRORS__ || [],
+    }))
+        .catch(() => ({ ready: false, details: [] }));
+    for (const e of evidence.details)
+        if (!runtimeErrors.some((v) => v.includes(e.message)) && runtimeErrors.length < 10)
+            runtimeErrors.push(e.message);
+    if (runtimeErrors.length)
+        errors.push('页面存在 JavaScript 运行错误');
+    if (form && !evidence.ready)
+        errors.push('表单未完成初始化，检查具体脚本错误及 __E10_FORM_READY__ 设置');
+    return {
+        ok: !errors.length,
+        stage,
+        ready: evidence.ready,
+        errors,
+        runtimeErrors,
+        details: evidence.details,
+        url,
+    };
+}

package/dist/offline-store.mjs

@@ -44,6 +44,16 @@ export function createOfflineStorage(appId) {
     return {
         valid,
         operate(scope, operation, value) {
+            if (operation === 'compareSave') {
+                check(scope, value?.expected);
+                check(scope, value?.next);
+                const next = read();
+                if (JSON.stringify(next.objects[scope]) !== JSON.stringify(value.expected))
+                    throw new Error('FORM_CONFLICT: 本地记录已变化，请重新打开后修改');
+                next.objects[scope] = clone(value.next);
+                persist(next);
+                return clone(next.objects[scope]);
+            }
             check(scope, value);
             if (!['load', 'save', 'reset'].includes(operation))
                 throw new Error('未知本地操作');

package/dist/runtime-support.d.mts

@@ -1,3 +1,37 @@
+export function hostCapabilities(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): {
+    code?: string | undefined;
+    fix?: string | undefined;
+    background: string;
+    agentTeams: string;
+    backgroundTasks: string;
+    evidenceSource: string;
+    evidenceScope: string;
+    verification: string;
+};
+export function workBuddyHostBlocker(env?: NodeJS.ProcessEnv, required?: boolean): {
+    ok: boolean;
+    blocked: boolean;
+    state: string;
+    error: {
+        code: string;
+        message: string;
+    };
+    userMessage: string;
+    fix: string;
+    next: string;
+    host: {
+        code?: string | undefined;
+        fix?: string | undefined;
+        background: string;
+        agentTeams: string;
+        backgroundTasks: string;
+        evidenceSource: string;
+        evidenceScope: string;
+        verification: string;
+    };
+} | null;
+/** @param {string[]} commands */
+export function isHostDiagnosticCommand(commands: string[]): boolean;
 export function environmentValue(env: any, name: any, platform?: NodeJS.Platform): any;
 export function productStateRoot(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform, homeDirectory?: string): string;
 export function npmEnvironment(env?: NodeJS.ProcessEnv): {

package/dist/runtime-support.mjs

@@ -9,6 +9,73 @@ import { fileURLToPath } from 'node:url';
 const here = fileURLToPath(import.meta.url);
 const fail = (code, message = code) => Object.assign(new Error(message), { code });
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// Inspect only the two capability flags inherited from the host. A reserved CLI
+// token or a saved preference is not proof that a background Agent is running.
+export function hostCapabilities(env = process.env, platform = process.platform) {
+    const flag = (name) => {
+        const value = environmentValue(env, name, platform)?.trim() || '';
+        return /^(1|true)$/i.test(value) ? true : /^(0|false)$/i.test(value) ? false : undefined;
+    };
+    const teams = flag('CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS');
+    const disabled = flag('CODEBUDDY_CODE_DISABLE_BACKGROUND_TASKS');
+    const agentTeams = teams === true ? 'enabled' : teams === false ? 'disabled' : 'unknown';
+    const backgroundTasks = disabled === true ? 'disabled' : disabled === false ? 'allowed' : 'unknown';
+    const background = disabled === true || teams === false ? 'disabled' : teams === true ? 'enabled' : 'unknown';
+    return {
+        background,
+        agentTeams,
+        backgroundTasks,
+        evidenceSource: 'inherited-host-environment',
+        evidenceScope: 'current-session',
+        verification: 'native-task-id-and-independent-completion-required',
+        ...(background === 'disabled'
+            ? {
+                code: 'HOST_BACKGROUND_DISABLED',
+                fix: workBuddyHostFix,
+            }
+            : {}),
+    };
+}
+const workBuddyHostFix = '请在 WorkBuddy 左下角头像 → 设置 → 智能体 → 智能体团队管理中检查智能体团队：若显示“取消禁用”，请点击；若显示“禁用”，表示界面设置已开启，请勿再次点击。然后完全退出并重新打开 WorkBuddy，回到本任务回复“继续”。若界面已开启且重启后仍受阻，可能是界面设置与当前会话能力状态不同步，请向 WorkBuddy 反馈该状态异常，不要反复切换开关。复查通过后会从原任务目录继续。';
+const workBuddyHostReason = '应用原型生成是高并发任务，需要多个智能体同时生成和校对不同页面。未开启智能体团队时，只能逐页串行处理，整体耗时会非常长。为避免长时间等待，必须先开启智能体团队，才能继续生成。';
+// The wrapper requires positive evidence even before runtime installation. Direct
+// CLI use on other hosts remains supported; inherited WorkBuddy flags opt it in.
+export function workBuddyHostBlocker(env = process.env, required = false) {
+    const host = hostCapabilities(env);
+    const detected = [
+        'CODEBUDDY_CODE_EXPERIMENTAL_AGENT_TEAMS',
+        'CODEBUDDY_CODE_DISABLE_BACKGROUND_TASKS',
+    ].some((name) => environmentValue(env, name) !== undefined);
+    if (host.background === 'enabled' || (!required && !detected))
+        return null;
+    const message = host.backgroundTasks === 'disabled'
+        ? '当前 WorkBuddy 会话报告后台任务不可用，应用原型任务已暂停。'
+        : host.agentTeams === 'disabled'
+            ? '当前 WorkBuddy 会话报告智能体团队未生效，应用原型任务已暂停。'
+            : '当前无法确认 WorkBuddy 会话的智能体团队可用，应用原型任务已暂停。';
+    return {
+        ok: false,
+        blocked: true,
+        state: 'WAITING_HOST',
+        error: {
+            code: host.background === 'disabled' ? 'HOST_BACKGROUND_DISABLED' : 'HOST_BACKGROUND_UNVERIFIED',
+            message,
+        },
+        userMessage: `${message}\n\n${workBuddyHostReason}\n\n${workBuddyHostFix}`,
+        fix: workBuddyHostFix,
+        next: 'enable-agent-teams',
+        host,
+    };
+}
+/** @param {string[]} commands */
+export function isHostDiagnosticCommand(commands) {
+    const [command, subcommand, action] = commands;
+    return (['doctor', 'status', 'next', 'version', '--help', '--version'].includes(command) ||
+        (command === 'html' && subcommand === 'watch') ||
+        (command === 'auth' &&
+            (subcommand === 'status' ||
+                (subcommand === 'profile' && ['list', 'current'].includes(action)))));
+}
 export function environmentValue(env, name, platform = process.platform) {
     return platform === 'win32'
         ? Object.entries(env).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1]