@danceiny/gotry 0.0.1-rc.9 → 0.2.0-rc.27

package/dist/scripts/observability-tests.js

@@ -0,0 +1,381 @@
+/**
+ * 服务运行时观测补齐测试(§73;#272/#511,2026-10-02 UAT 只读实查证实的两个
+ * 证据留存缺口)。
+ *
+ * 全离线确定性(零网络、零真实供应商、零真实模型调用;所有进程与目录隔离在
+ * /tmp 临时根,不写共享产品状态):
+ *   ① #272 verdict 结构化日志:session-search 模块注入 fake search + verdictLog
+ *      收集器,经真 createBackendServer HTTP 面结算——形状断言(键封闭
+ *      ts/surface/supplier/verdict/latencyMs[+error])/error 摘要 ≤200 字符/
+ *      cookie·ticket·凭据哨兵脱敏为 [REDACTED]/rates·evidence 回包面永不入日志/
+ *      换行压平防日志注入/cooldown·异常路径也各落一行/status 结算面独立 verdict。
+ *   ② #511 planner 子进程 boot 观测:临时 fixture worker 子进程走真
+ *      ManagedDshRunPort JSON-lines 协议——boot 成功一行 HARNESS_BOOT_STAGE
+ *      (initializeMs,mode=reused 不重复打)/worker 握手超时一行
+ *      HARNESS_BOOT_TIMEOUT(闭集分类+elapsedMs+initializeMs 若可得)/
+ *      注入 runPort 的 planner turn 结算 PLANNER_BOOT_TIMEOUT 分类行。
+ *   ③ #511 gotry-backend 启动阶段行:startGotryBackendFromEnvironment(离线假
+ *      env,booking-copilot 只做惰性配置解析不 spawn planner)——每个模块挂载一行
+ *      CORE_BOOT_STAGE(module_mounted)+ listening 一行(port 与句柄一致);
+ *      启动失败行 CORE_BOOT_FAILURE 形状与 200 字符有界。
+ */
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { startSessionSearchModule } from '../src/backend/modules/session-search.js';
+import { closeBackend, createBackendServer } from '../src/backend/kernel.js';
+import { formatBackendBootFailure, startGotryBackendFromEnvironment } from '../src/gotry-backend.js';
+import { ManagedDshRunPort } from '../src/booking-surface/managed-dsh-run-port.js';
+import { createDshEmbeddedBookingPlanner } from '../src/booking-surface/dsh-planner.js';
+let passed = 0;
+async function check(label, assertion) {
+    await assertion();
+    passed += 1;
+    console.log(`  ok - ${label}`);
+}
+const VERDICT_PREFIX = '[session-search] verdict ';
+async function jfetch(url, init = {}) {
+    const r = await fetch(url, init);
+    const text = await r.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = { raw: text };
+    }
+    return { status: r.status, body };
+}
+/** 解析一条 verdict 行:前缀剥离 + JSON 校验 */
+function parseVerdictLine(line) {
+    assert.ok(line.startsWith(VERDICT_PREFIX), `verdict 行必须以 ${VERDICT_PREFIX} 开头:${line}`);
+    return JSON.parse(line.slice(VERDICT_PREFIX.length));
+}
+async function main() {
+    /* ================= ① #272 verdict 结构化日志 ================= */
+    console.log('① session-search verdict 结构化日志(#272)');
+    const verdictLines = [];
+    let fakeResult = {
+        ok: true, via: 'session-dida-portal', evidence: '[会话:dida-portal@fixture]', latencyMs: 42, verdict: 'hit', rates: [],
+    };
+    let fakeError;
+    const sessionModule = startSessionSearchModule({
+        apiKey: () => 'observability-key',
+        search: async () => {
+            if (fakeError)
+                throw fakeError;
+            return fakeResult;
+        },
+        verdictLog: (line) => verdictLines.push(line),
+    });
+    const sessionBackend = await createBackendServer({ modules: [sessionModule], port: 0 });
+    const base = `http://127.0.0.1:${sessionBackend.port}`;
+    const searchInit = {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: 'Bearer observability-key' },
+        body: JSON.stringify({ supplier: 'dida-portal' }),
+    };
+    try {
+        await check('hit 结算:一行结构化 verdict,键封闭且值正确,回包内容不入日志', async () => {
+            // rates 形状对断言无关紧要(仅作为「回包内容」哨兵载体)
+            fakeResult = {
+                ok: true, via: 'session-dida-portal', evidence: '[会话:dida-portal@SECRET-EVIDENCE]', latencyMs: 42, verdict: 'hit',
+                rates: [{ hotelName: 'SECRET-HOTEL-RESPONSE-BODY', price: '100' }],
+            };
+            const before = verdictLines.length;
+            const r = await jfetch(`${base}/v1/session/search`, searchInit);
+            assert.equal(r.status, 200);
+            assert.equal(verdictLines.length - before, 1, 'hit 结算恰好一行');
+            const line = verdictLines.at(-1);
+            assert.ok(!line.includes('\n'), 'verdict 行内部不得有换行(日志注入面)');
+            assert.ok(!line.includes('SECRET-HOTEL-RESPONSE-BODY'), 'rates 回包内容不入日志');
+            assert.ok(!line.includes('SECRET-EVIDENCE'), 'evidence 字段不入日志');
+            const record = parseVerdictLine(line);
+            assert.deepEqual(Object.keys(record).sort(), ['latencyMs', 'supplier', 'surface', 'ts', 'verdict'], '键封闭:ts/surface/supplier/verdict/latencyMs');
+            assert.equal(record.verdict, 'hit');
+            assert.equal(record.supplier, 'dida-portal');
+            assert.equal(record.surface, 'search');
+            assert.equal(record.latencyMs, 42);
+            assert.ok(!Number.isNaN(Date.parse(String(record.ts))), 'ts 是可解析时刻');
+            assert.ok(/^\d{4}-\d{2}-\d{2}T/.test(String(record.ts)), 'ts 是 ISO 形状');
+        });
+        await check('error 结算:cookie/ticket/凭据哨兵脱敏为 [REDACTED],摘要 ≤200 字符,单行化', async () => {
+            fakeResult = {
+                ok: false, via: 'session-dida-portal-error', evidence: '[会话:dida-portal@fixture]', latencyMs: 7, verdict: 'error',
+                error: 'extension job failed; cookie SESSION_TICKET=SECRET-TICKET-9F3A; ticket=SECRET-TICKET-2;\nAuthorization: Bearer sk-SECRET-KEY-1; body fragment ignored',
+            };
+            const before = verdictLines.length;
+            const r = await jfetch(`${base}/v1/session/search`, searchInit);
+            assert.equal(r.status, 200);
+            assert.equal(verdictLines.length - before, 1);
+            const line = verdictLines.at(-1);
+            assert.ok(!line.includes('SECRET-TICKET-9F3A'), 'cookie 值不得入日志');
+            assert.ok(!line.includes('SECRET-TICKET-2'), 'ticket 值不得入日志');
+            assert.ok(!line.includes('sk-SECRET-KEY-1'), 'bearer 凭据值不得入日志');
+            assert.ok(line.includes('[REDACTED]'), '被脱敏的值以 [REDACTED] 占位');
+            assert.ok(!line.includes('\n'), '原始换行被压平(日志注入面)');
+            const record = parseVerdictLine(line);
+            assert.equal(record.verdict, 'error');
+            assert.ok(typeof record.error === 'string' && record.error.length <= 200, `error 摘要 ≤200 字符,实际 ${String(record.error).length}`);
+        });
+        await check('超长 error 摘要被截断到 ≤200 字符', async () => {
+            fakeResult = {
+                ok: false, via: 'session-dida-portal-error', evidence: '', latencyMs: 3, verdict: 'error',
+                error: `host copy prefix;${'x'.repeat(400)}`,
+            };
+            await jfetch(`${base}/v1/session/search`, searchInit);
+            const record = parseVerdictLine(verdictLines.at(-1));
+            assert.ok(typeof record.error === 'string' && record.error.length <= 200 && record.error.length >= 199, '截断后仍 ≤200 且保留信息量');
+            assert.ok(record.error.endsWith('…'), '截断以省略号标记');
+        });
+        await check('cooldown 结算:429 + verdict 行 verdict=cooldown', async () => {
+            fakeResult = {
+                ok: false, via: 'session-dida-portal-error', evidence: '', latencyMs: 5, verdict: 'cooldown', error: '节律冷却中,30s 后重试',
+            };
+            const r = await jfetch(`${base}/v1/session/search`, searchInit);
+            assert.equal(r.status, 429);
+            const record = parseVerdictLine(verdictLines.at(-1));
+            assert.equal(record.verdict, 'cooldown');
+        });
+        await check('异常结算:500 + verdict 行 verdict=error 且异常消息里的凭据脱敏', async () => {
+            fakeError = new Error('search crashed cookie=LEAK-COOKIE-77');
+            try {
+                const r = await jfetch(`${base}/v1/session/search`, searchInit);
+                assert.equal(r.status, 500);
+            }
+            finally {
+                fakeError = undefined;
+            }
+            const line = verdictLines.at(-1);
+            assert.ok(!line.includes('LEAK-COOKIE-77'), '异常消息里的 cookie 值不得入日志');
+            const record = parseVerdictLine(line);
+            assert.equal(record.verdict, 'error');
+            assert.ok(typeof record.latencyMs === 'number' && record.latencyMs >= 0, 'latencyMs 非负');
+        });
+        await check('status 结算:surface=status,扩展未连接时 verdict=needs-extension', async () => {
+            const before = verdictLines.length;
+            const r = await jfetch(`${base}/v1/session/status`, { headers: { authorization: 'Bearer observability-key' } });
+            assert.equal(r.status, 200);
+            assert.equal(verdictLines.length - before, 1);
+            const record = parseVerdictLine(verdictLines.at(-1));
+            assert.equal(record.surface, 'status');
+            assert.equal(record.verdict, 'needs-extension');
+            assert.equal(record.supplier, 'dida-portal');
+            assert.ok(typeof record.latencyMs === 'number' && record.latencyMs >= 0);
+        });
+        await check('非 verdict 结算(鉴权失败 403)不落 verdict 行', async () => {
+            const before = verdictLines.length;
+            const r = await jfetch(`${base}/v1/session/search`, {
+                method: 'POST', headers: { 'content-type': 'application/json', authorization: 'Bearer wrong' }, body: JSON.stringify({ supplier: 'dida-portal' }),
+            });
+            assert.equal(r.status, 403);
+            assert.equal(verdictLines.length - before, 0, '鉴权拒绝不是检索结算');
+        });
+    }
+    finally {
+        await closeBackend(sessionBackend, [sessionModule]);
+    }
+    /* ================= ② #511 planner 子进程 boot 观测 ================= */
+    console.log('② planner 子进程 boot 观测(#511)');
+    const bootScratch = mkdtempSync(join(tmpdir(), 'gotry-obs-boot-'));
+    try {
+        // fixture worker:真 ManagedDshRunPort JSON-lines 协议;首请求报 started 握手,
+        // 后续报 reused(拒绝 HARNESS_BOOT_TIMEOUT 的独立 fixture 在下方)。
+        const bootWorkerPath = join(bootScratch, 'boot-fixture-worker.mjs');
+        writeFileSync(bootWorkerPath, [
+            "import { createInterface } from 'node:readline'",
+            "process.stdout.write(JSON.stringify({ lifecycle: 'worker_started', workerPid: process.pid, parentPid: process.ppid }) + '\\n')",
+            "const input = createInterface({ input: process.stdin, crlfDelay: Infinity })",
+            "input.on('line', (line) => {",
+            '  const request = JSON.parse(line)',
+            '  const first = !globalThis.__booted',
+            '  globalThis.__booted = true',
+            "  process.stdout.write(JSON.stringify({ id: request.id, boot: first ? { initializeMs: 531, mode: 'started' } : { initializeMs: 0, mode: 'reused' } }) + '\\n')",
+            "  process.stdout.write(JSON.stringify({ id: request.id, ok: true, result: { finalResponse: '', events: [], notifications: [] } }) + '\\n')",
+            '})',
+            '',
+        ].join('\n'), { encoding: 'utf8' });
+        await check('boot 成功:每个子进程一行 HARNESS_BOOT_STAGE(role+initializeMs);reused 不重复打', async () => {
+            const bootLines = [];
+            const port = new ManagedDshRunPort({ workerPath: bootWorkerPath, cleanupRole: 'task', graceMs: 50, bootLog: (line) => bootLines.push(line) });
+            try {
+                await port.run('fixture', { sessionId: 'observability-boot' });
+                assert.deepEqual(bootLines, ['HARNESS_BOOT_STAGE {"role":"task","initializeMs":531,"mode":"started"}'], '首启动恰好一行,含 initializeMs');
+                assert.deepEqual(port.bootObservation(), { initializeMs: 531, mode: 'started' });
+                await port.run('fixture-two', { sessionId: 'observability-boot' });
+                assert.deepEqual(port.bootObservation(), { initializeMs: 0, mode: 'reused' });
+                assert.equal(bootLines.length, 1, 'reused 没有再 boot,不再打行');
+            }
+            finally {
+                await port.close();
+            }
+        });
+        const timeoutWorkerPath = join(bootScratch, 'boot-timeout-fixture-worker.mjs');
+        writeFileSync(timeoutWorkerPath, [
+            "import { createInterface } from 'node:readline'",
+            "process.stdout.write(JSON.stringify({ lifecycle: 'worker_started', workerPid: process.pid, parentPid: process.ppid }) + '\\n')",
+            "const input = createInterface({ input: process.stdin, crlfDelay: Infinity })",
+            "input.on('line', (line) => {",
+            '  const request = JSON.parse(line)',
+            `  process.stdout.write(JSON.stringify({ id: request.id, ok: false, error: 'HARNESS_BOOT_TIMEOUT' }) + '\\n')`,
+            '})',
+            '',
+        ].join('\n'), { encoding: 'utf8' });
+        await check('worker 握手超时:HARNESS_BOOT_TIMEOUT 行(闭集分类+elapsedMs+initializeMs=null)', async () => {
+            const bootLines = [];
+            const port = new ManagedDshRunPort({ workerPath: timeoutWorkerPath, cleanupRole: 'task', graceMs: 50, bootLog: (line) => bootLines.push(line) });
+            try {
+                await assert.rejects(() => port.run('fixture', { sessionId: 'observability-boot-timeout' }), /HARNESS_BOOT_TIMEOUT/);
+                assert.equal(bootLines.length, 1);
+                const line = bootLines[0];
+                assert.ok(line.startsWith('HARNESS_BOOT_TIMEOUT '), `行前缀必须是 HARNESS_BOOT_TIMEOUT:${line}`);
+                const record = JSON.parse(line.slice('HARNESS_BOOT_TIMEOUT '.length));
+                assert.equal(record.role, 'task');
+                assert.equal(record.initializeMs, null, '握手从未完成,initializeMs 不可得即为 null');
+                assert.ok(typeof record.elapsedMs === 'number' && record.elapsedMs >= 0, 'elapsedMs 时刻差非负');
+            }
+            finally {
+                await port.close();
+            }
+        });
+        await check('planner 结算:boot 超时分类 PLANNER_BOOT_TIMEOUT 行(initializeMs/mode 不可得即 null)', async () => {
+            const availability = {
+                initialized: true, recoveryStarted: false, availabilityPhase: 'need_offers', activeHotelOrdinal: 0,
+                hotelRefs: [], hotels: {}, attempts: [], queryReservations: [],
+            };
+            const task = {
+                schemaVersion: 'booking.surface',
+                taskId: 'task-observability-boot-1',
+                contextRef: 'ctx-observability-boot-1',
+                surface: 'tenant',
+                revision: 0,
+                allowedActions: ['search.patch', 'search.run'],
+                userTurnCount: 1,
+                lastTurnId: 'turn-observability-boot-1',
+                operationCount: 0,
+                phase: 'planning',
+                lastSequence: 0,
+                availability,
+            };
+            const workspace = {
+                schemaVersion: 'booking.surface',
+                contextRef: task.contextRef,
+                surface: 'tenant',
+                revision: 0,
+                locale: 'zh-CN',
+                currency: 'CNY',
+                searchDraft: {},
+                results: { status: 'idle' },
+                visibleHotels: [],
+                loadedOffers: [],
+                shortlistedOfferRefs: [],
+                capabilities: { surface: 'tenant', allowedActions: ['search.patch', 'search.run'] },
+            };
+            task.workspaceSnapshot = workspace;
+            const turn = {
+                schemaVersion: 'booking.surface',
+                kind: 'user.turn',
+                taskId: task.taskId,
+                turnId: task.lastTurnId,
+                workspace,
+                request: { text: 'Find hotels' },
+            };
+            const captured = [];
+            const originalStderrWrite = process.stderr.write.bind(process.stderr);
+            process.stderr.write = ((chunk) => {
+                captured.push(typeof chunk === 'string' ? chunk : Buffer.from(chunk).toString('utf8'));
+                return true;
+            });
+            let planner;
+            try {
+                const factoryPort = {
+                    run: () => Promise.reject(new Error('HARNESS_BOOT_TIMEOUT')),
+                    async close() { },
+                    bootObservation: () => undefined,
+                };
+                planner = await createDshEmbeddedBookingPlanner({ runPortFactory: () => factoryPort, turnTimeoutMs: 1_000 });
+                const decisions = await planner.plannerFactory(task).next({ task, turn });
+                assert.equal(decisions[0]?.kind, 'error');
+                assert.equal(decisions[0].error?.code, 'PLANNER_BOOT_TIMEOUT');
+                await planner.close();
+                planner = undefined;
+                const line = captured.find((value) => value.startsWith('PLANNER_BOOT_TIMEOUT '));
+                assert.ok(line, '服务进程 stderr 必须出现 PLANNER_BOOT_TIMEOUT 行');
+                const record = JSON.parse(line.slice('PLANNER_BOOT_TIMEOUT '.length).trim());
+                assert.deepEqual(record, { initializeMs: null, mode: null });
+            }
+            finally {
+                process.stderr.write = originalStderrWrite;
+                await planner?.close().catch(() => undefined);
+            }
+        });
+    }
+    finally {
+        rmSync(bootScratch, { recursive: true, force: true });
+    }
+    /* ================= ③ #511 gotry-backend 启动阶段行 ================= */
+    console.log('③ gotry-backend 启动阶段行(#511)');
+    const backendScratch = mkdtempSync(join(tmpdir(), 'gotry-obs-backend-'));
+    let backendHandle;
+    try {
+        await check('启动:每模块一行 module_mounted + 一行 listening(port 与句柄一致)', async () => {
+            const stageLines = [];
+            backendHandle = await startGotryBackendFromEnvironment({
+                GOTRY_BACKEND_PORT: '0',
+                GOTRY_BACKEND_SESSION_API_KEY: 'observability-session-key',
+                GOTRY_BACKEND_STATE_ROOT: backendScratch,
+                GOTRY_BOOKING_COPILOT_API_KEY: 'observability-copilot-key',
+                GOTRY_BOOKING_COPILOT_STATE_ROOT: backendScratch,
+                DEEPSEEK_API_KEY: 'offline-fake-key-planner-not-spawned-at-boot',
+            }, (line) => stageLines.push(line));
+            const records = stageLines.map((line) => {
+                assert.ok(line.startsWith('CORE_BOOT_STAGE '), `启动阶段行前缀必须是 CORE_BOOT_STAGE:${line}`);
+                return JSON.parse(line.slice('CORE_BOOT_STAGE '.length));
+            });
+            const mounted = records.filter((record) => record.phase === 'module_mounted');
+            assert.deepEqual(mounted.map((record) => record.module), ['booking-copilot', 'session-search', 'booking-executor'], '每个模块挂载一行,按挂载顺序');
+            for (const record of mounted) {
+                assert.ok(typeof record.elapsedMs === 'number' && record.elapsedMs >= 0, 'module_mounted 携带非负 elapsedMs');
+            }
+            const listening = records.at(-1);
+            assert.equal(listening.phase, 'listening');
+            assert.equal(listening.port, backendHandle.port, 'listening 行端口与句柄一致');
+            assert.equal(listening.modules, 'booking-copilot,session-search,booking-executor');
+        });
+        await check('启动失败行:CORE_BOOT_FAILURE 数组形状,error 摘要 ≤200 字符', () => {
+            const line = formatBackendBootFailure(new Error('x'.repeat(500)));
+            assert.ok(line.startsWith('CORE_BOOT_FAILURE '), '启动失败行前缀必须是 CORE_BOOT_FAILURE');
+            const [record] = JSON.parse(line.slice('CORE_BOOT_FAILURE '.length));
+            assert.equal(record.phase, 'startup');
+            assert.ok(record.error.length <= 200 && record.error.length === 200, '500 字符消息被截到 200');
+            assert.ok(!line.includes('\n'), '失败行单行');
+        });
+        await check('启动失败(缺 booking-copilot key):同一函数落 CORE_BOOT_FAILURE 后原样抛出', async () => {
+            const failureLines = [];
+            await assert.rejects(() => startGotryBackendFromEnvironment({
+                GOTRY_BACKEND_PORT: '0',
+                GOTRY_BACKEND_SESSION_API_KEY: 'observability-session-key',
+                // GOTRY_BOOKING_COPILOT_API_KEY 缺失 → booking_copilot_api_key_required
+            }, (line) => failureLines.push(line)), /booking_copilot_api_key_required/);
+            const line = failureLines.find((value) => value.startsWith('CORE_BOOT_FAILURE '));
+            assert.ok(line, '模块挂载失败必须经启动函数落 CORE_BOOT_FAILURE(bin 包装层直接调本函数)');
+            const [record] = JSON.parse(line.slice('CORE_BOOT_FAILURE '.length));
+            assert.equal(record.phase, 'startup');
+            assert.ok(!line.includes('offline-fake-key'), '失败行不含密钥材料');
+        });
+        await check('健康面可达后干净关闭', async () => {
+            const r = await jfetch(`http://127.0.0.1:${backendHandle.port}/healthz`, { headers: { authorization: 'Bearer observability-copilot-key' } });
+            assert.ok(r.status === 200 || r.status === 503, `healthz 探活可达(实际 ${r.status})`);
+        });
+    }
+    finally {
+        await backendHandle?.close().catch(() => undefined);
+        rmSync(backendScratch, { recursive: true, force: true });
+    }
+    console.log(`\n§73 observability: ${passed} 段全绿`);
+}
+main().catch((error) => {
+    console.error('FAIL:', error);
+    process.exit(1);
+});

package/dist/scripts/onboarding-tests.js

@@ -0,0 +1,161 @@
+/**
+ * onboarding UX 测试(issue #21 onboarding UX,§3.3 ADR-21 上架后重设,run-all §40)。
+ *
+ * 4 段全离线断言(wizard 2026-09-02 缩为 2 步纯 Node 端:扩展落位 + watch precheck):
+ *   1. wizard --dry-run:零网络零浏览器零 GUI spawn,exit 0,2 步齐全
+ *   2. health-watch 三时序:0ms ready(立即 timeout)/ 5s ready(中途 ready)/ 120s+1ms 超时
+ *   3. retry-after-watch:needs-extension → watch ready → 自动重放同 query_id 同参数
+ *   4. wizard 无强制 spawn:forcePlatform 参数彻底消失(GUI 跨平台降级退役)
+ *
+ * 离线纪律:不打真 Chrome、不发真请求;wizard 不需要 spawn 注入(stub 注入路径仍在但 dry-run 路径不调)。
+ */
+import assert from 'node:assert/strict';
+import { runOnboardingWizard, defaultExtensionDir, describeExtensionDir, } from '../capabilities/session/wizard.js';
+import { startExtensionHealthWatch, withAutoRetryOnExtension, HEALTH_WATCH_INTERVAL_FLOOR_MS, HEALTH_WATCH_INTERVAL_CEIL_MS, } from '../capabilities/session/health-watch.js';
+let passed = 0;
+function check(label, fn) {
+    return Promise.resolve()
+        .then(fn)
+        .then(() => { passed += 1; console.log(`  ok - ${label}`); });
+}
+function noopSpawn() {
+    const { EventEmitter } = require('node:events');
+    const child = new EventEmitter();
+    // 流对象 stub
+    const stream = new EventEmitter();
+    child.stdin = stream;
+    child.stdout = null;
+    child.stderr = null;
+    child.unref = () => undefined;
+    return child;
+}
+function captureSpawn() {
+    const calls = [];
+    const spawn = ((bin, args = []) => {
+        calls.push({ bin, args });
+        return noopSpawn();
+    });
+    return { spawn, calls };
+}
+async function asyncSleep(ms) {
+    if (ms <= 0)
+        return;
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+console.log('ONBOARDING UX (§40)');
+await check('1. wizard --dry-run 零网络零浏览器零 GUI spawn,exit 0,2 步齐全', async () => {
+    const result = await runOnboardingWizard({ dryRun: true });
+    assert.equal(result.ok, true, `wizard ok 应 true,实际 ${JSON.stringify(result.steps)}`);
+    assert.equal(result.steps.length, 2, `应有 2 步,实际 ${result.steps.length}`);
+    const expected = ['ensure-extension-files', 'watch-extension-ready'];
+    for (let i = 0; i < expected.length; i++) {
+        assert.equal(result.steps[i].step, expected[i]);
+        assert.equal(result.steps[i].status, 'skip', `dry-run 每步应为 skip,${result.steps[i].step} 实为 ${result.steps[i].status}`);
+    }
+});
+await check('2. health-watch 三时序:0ms / 中途 / 120s+1ms', async () => {
+    // (a) timeoutMs=0 → 立即 timeout
+    const w0 = startExtensionHealthWatch({ timeoutMs: 0, intervalMs: 10 });
+    const o0 = await w0.waitReady();
+    assert.equal(o0.ready, false);
+    assert.equal(o0.reason, 'timeout');
+    // (b) 中途 ready:第一次 probe false,第二次 true(30ms 后)
+    let probeCalls = 0;
+    const wMid = startExtensionHealthWatch({
+        timeoutMs: 500,
+        intervalMs: 30,
+        probe: async () => { probeCalls += 1; return probeCalls >= 2; },
+    });
+    const oMid = await wMid.waitReady();
+    assert.equal(oMid.ready, true, `中途 ready 实为 ${JSON.stringify(oMid)}`);
+    assert.ok(oMid.attempts >= 2);
+    // (c) 永不 ready → timeout(用极小 timeoutMs+全 false probe 模拟)
+    const wTimeout = startExtensionHealthWatch({
+        timeoutMs: 60,
+        intervalMs: 20,
+        probe: async () => false,
+    });
+    const oTimeout = await wTimeout.waitReady();
+    assert.equal(oTimeout.ready, false);
+    assert.equal(oTimeout.reason, 'timeout');
+});
+await check('3. wizard 完全不调 spawn(GUI 面板/剪贴板/直开浏览器均已退役)', async () => {
+    // 2026-09-02 上架后:wizard 缩为 2 步纯 Node 端职责(扩展落位 + watch precheck),
+    // 不弹 osascript/zenity、不动 pbcopy/xclip/clip、不 open 浏览器。
+    // 这里只校验 dry-run 与无源目录 fail 路径都不产生 spawn 调用。
+    const dry = captureSpawn();
+    await runOnboardingWizard({ dryRun: true, sourceDir: '/', extensionDir: '/tmp/none' });
+    assert.equal(dry.calls.length, 0, `dry-run 不应 spawn 任何命令(实调 ${dry.calls.length})`);
+    const fail = captureSpawn();
+    // dryRun=false + 不存在的源目录 → ensure 会 fail,但应仍不产生 spawn 调用
+    await runOnboardingWizard({ dryRun: false, sourceDir: '/nonexistent-source-dir-for-onboarding-tests', extensionDir: '/tmp/none-fail' });
+    assert.equal(fail.calls.length, 0, `fail 路径也不应 spawn(实调 ${fail.calls.length})`);
+});
+await check('4. retry-after-watch:needs-extension → watch ready → 自动重放同 query_id', async () => {
+    let fetchCalls = 0;
+    const queryId = 'sf-01';
+    const fetch = async () => {
+        fetchCalls += 1;
+        return { query_id: queryId, verdict: 'needs-extension', needsExt: fetchCalls === 1 };
+    };
+    // 第一次 → needs-extension,启 watch
+    const first = await fetch();
+    assert.equal(first.verdict, 'needs-extension');
+    let probeCount = 0;
+    const watch = startExtensionHealthWatch({
+        timeoutMs: 1_000,
+        intervalMs: 20,
+        probe: async () => { probeCount += 1; return probeCount >= 2; },
+    });
+    const outcome = await watch.waitReady();
+    assert.equal(outcome.ready, true);
+    // watch ready → 自动重放同 query_id
+    const retry = await fetch();
+    assert.equal(retry.query_id, queryId, '同 query_id 必须保持');
+    assert.equal(fetchCalls, 2, `应调用 fetch 两次(首次 + 重放),实 ${fetchCalls}`);
+});
+await check('5. wizard 不依赖 platform/panel 参数(GUI 跨平台降级退役)', async () => {
+    // 2026-09-02 上架后:wizard 不再接 forcePlatform/spawn panel 参数,
+    // 任何对 wizard 的调用都是 2 步(ensure + watch precheck)。
+    const result = await runOnboardingWizard({ dryRun: true, extensionDir: '/tmp/gotry-test-ext-2' });
+    assert.equal(result.steps.length, 2, `应 2 步,实 ${result.steps.length}`);
+    assert.equal(result.steps[0].step, 'ensure-extension-files');
+    assert.equal(result.steps[1].step, 'watch-extension-ready');
+    assert.equal(result.platform, undefined, 'platform 字段应不再存在');
+});
+await check('6. withAutoRetryOnExtension 端到端:首次 needs-ext → 自动重放', async () => {
+    let callCount = 0;
+    let ready = false;
+    // watch 第一次 probe 后 30ms 标记 ready(模拟用户装完扩展)
+    setTimeout(() => { ready = true; }, 30);
+    const args = {
+        fetch: async () => {
+            callCount += 1;
+            return callCount === 1 ? { needsExt: true } : { needsExt: false, hit: true };
+        },
+        isExtensionNeeded: (r) => r.needsExt === true,
+        watch: { timeoutMs: 1_000, intervalMs: 20, probe: async () => ready },
+    };
+    const out = await withAutoRetryOnExtension(args);
+    assert.equal(out.retried, true, `应触发重放,实 retried=${out.retried}`);
+    assert.equal(out.attempts, 2);
+    assert.equal(out.result.needsExt, false);
+    assert.equal(out.result.hit, true);
+    assert.equal(callCount, 2, `withAutoRetry 应调 2 次 fetch,实 ${callCount}`);
+});
+await check('7. health-watch interval 边界常量与 watch 契约对齐', () => {
+    assert.ok(HEALTH_WATCH_INTERVAL_FLOOR_MS >= 1_000, '下界不应让 watch 风暴');
+    assert.ok(HEALTH_WATCH_INTERVAL_CEIL_MS <= 44_000, '上界应 < EXTENSION_CONNECTED_WINDOW_MS');
+});
+await check('8. defaultExtensionDir = ~/.gotry/extension(契约对齐 bootstrap 节)', () => {
+    const dir = defaultExtensionDir();
+    assert.match(dir, /\.gotry[\\/]extension$/, `扩展目录形态应是 ~/.gotry/extension,实 ${dir}`);
+});
+await check('9. describeExtensionDir:不存在的目录不抛错,返回 exists:false', () => {
+    const desc = describeExtensionDir('/nonexistent/zzz');
+    assert.equal(desc.exists, false);
+    assert.equal(desc.fileCount, 0);
+    assert.equal(desc.hasManifest, false);
+});
+await asyncSleep(0);
+console.log(`ONBOARDING UX (§40): ${passed} pass`);

package/dist/scripts/opensky-check.js

@@ -1,20 +1,25 @@
+/**
+ * OpenSky 校验桥(M2 段 3 第一件,§7-1 免费路线的校验层):验证某航班真实执飞。
+ * 零新依赖:匿名 REST(400 credits/天),失败降级为「校验不可用」而非阻塞规划。
+ * 证据链:[实时API:opensky] + 抓取时间;查不到≠不存在(ADS-B 覆盖有限),只作正向印证。
+ * 运行:cd ts && npx tsx scripts/opensky-check.ts EK329
+ */
 const BASE = 'https://opensky-network.org/api';
 async function checkArrival(callsign, airport) {
+    // 匿名窗口只支持近 7 天;演示用最近的到达查询验证桥通不通
     const now = Math.floor(Date.now() / 1000);
-    const url = airport ? `${BASE}/arrivals?airport=${airport}&begin=${now - 7 * 86400}&end=${now}` : `${BASE}/arrivals?airport=OMDB&begin=${now - 7 * 86400}&end=${now}`;
-    const res = await fetch(url, {
-        headers: {
-            Accept: 'application/json'
-        }
-    });
-    if (!res.ok) return `[校验不可用:opensky ${res.status}]`;
-    const data = await res.json();
-    const hit = data.find((a)=>(a.callsign ?? '').trim().toUpperCase().includes(callsign.toUpperCase()));
+    const url = airport
+        ? `${BASE}/arrivals?airport=${airport}&begin=${now - 7 * 86400}&end=${now}`
+        : `${BASE}/arrivals?airport=OMDB&begin=${now - 7 * 86400}&end=${now}`;
+    const res = await fetch(url, { headers: { Accept: 'application/json' } });
+    if (!res.ok)
+        return `[校验不可用:opensky ${res.status}]`;
+    const data = (await res.json());
+    const hit = data.find(a => (a.callsign ?? '').trim().toUpperCase().includes(callsign.toUpperCase()));
     const ts = new Date().toISOString();
-    return hit ? `[实时API:opensky@${ts}] ✅ ${callsign} 近 7 天执飞记录:到达 ${hit.arrivalAirport ?? '?'}(callsign ${hit.callsign?.trim()})` : `[实时API:opensky@${ts}] ○ 近 7 天 ${airport ?? 'OMDB'} 到达列表未见 ${callsign}(ADS-B 覆盖有限,不作否定结论)`;
+    return hit
+        ? `[实时API:opensky@${ts}] ✅ ${callsign} 近 7 天执飞记录:到达 ${hit.arrivalAirport ?? '?'}(callsign ${hit.callsign?.trim()})`
+        : `[实时API:opensky@${ts}] ○ 近 7 天 ${airport ?? 'OMDB'} 到达列表未见 ${callsign}(ADS-B 覆盖有限,不作否定结论)`;
 }
 const target = process.argv[2] ?? 'EK329';
 console.log(await checkArrival(target, process.argv[3] ?? null));
-
-
-//# sourceURL=/Users/bytedance/work/gotry/ts/scripts/opensky-check.ts