@danceiny/gotry 0.0.1-rc.21 → 0.0.1-rc.24

package/dist/scripts/channel-probe-tests.js

@@ -1,148 +1,76 @@
+/**
+ * 通道探针 tick 测试(外部事件接缝第 1 段,issue #82 兼容方向;全离线):
+ *  1. evaluateProbeResults 纯函数:fail→down / ok+此前down→'ok'恢复 / ok+健康→零写 / skip→不产事件
+ *  2. readLatestChannelEvents latest-wins:'ok' 事件超越同通道更早的 down(恢复语义落地)
+ *  3. doctor 消费口径:恢复后 `state === 'down'` 判定不再命中(飞行可达性注释消失)
+ *  4. metrics aggregateChannels:'ok' 超越后 newest 不含该通道,down 事件计数保留(历史频率面)
+ *  5. CLI:--list 列探测面(session 系与 flyai 显式 skip);--only 未匹配 exit 2
+ *
+ * 运行: cd ts && npx tsx scripts/channel-probe-tests.ts
+ */
 import assert from 'node:assert/strict';
 import { mkdtemp, writeFile, mkdir, readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { evaluateProbeResults, defaultProbes, parseArgs, main } from './channel-probe.js';
-import { readLatestChannelEvents, recordChannelEvent } from '../capabilities/channel-health.js';
+import { readLatestChannelEvents } from '../capabilities/channel-health.js';
 import { aggregateChannels } from './build-metrics-report.js';
 const tmp = await mkdtemp(join(tmpdir(), 'gotry-probe-test-'));
+// ── 1. evaluateProbeResults 纯函数 ───────────────────────────────────────────
 const probes = defaultProbes();
-const hb = probes.find((p)=>p.channel === 'hbcli-hotel');
-const om = probes.find((p)=>p.channel === 'open-meteo');
-const fly = probes.find((p)=>p.channel === 'flyai');
+const hb = probes.find((p) => p.channel === 'hbcli-hotel');
+const om = probes.find((p) => p.channel === 'open-meteo');
+const fly = probes.find((p) => p.channel === 'flyai');
 const now = new Date('2026-09-07T12:00:00Z');
 const evs = evaluateProbeResults([
-    {
-        probe: hb,
-        result: {
-            ok: false,
-            reason: 'auth-denied',
-            ms: 5
-        }
-    },
-    {
-        probe: om,
-        result: {
-            ok: true,
-            ms: 100
-        }
-    },
-    {
-        probe: fly,
-        result: {
-            ok: true,
-            ms: 0
-        }
-    }
-], new Set([
-    'open-meteo'
-]), now);
+    { probe: hb, result: { ok: false, reason: 'auth-denied', ms: 5 } },
+    { probe: om, result: { ok: true, ms: 100 } },
+    { probe: fly, result: { ok: true, ms: 0 } },
+], new Set(['open-meteo']), now);
 assert.equal(evs.length, 2, `fail→down + ok恢复→'ok' 共 2 条,实际 ${evs.length}`);
-assert.deepEqual({
-    channel: evs[0].channel,
-    state: evs[0].state,
-    reason: evs[0].reason
-}, {
-    channel: 'hbcli-hotel',
-    state: 'down',
-    reason: 'auth-denied'
-}, 'fail 应产 down 事件带 reason');
-assert.deepEqual({
-    channel: evs[1].channel,
-    state: evs[1].state
-}, {
-    channel: 'open-meteo',
-    state: 'ok'
-}, 'ok 且此前 down 应产 ok 恢复事件');
-const noWrites = evaluateProbeResults([
-    {
-        probe: om,
-        result: {
-            ok: true,
-            ms: 90
-        }
-    }
-], new Set(), now);
+assert.deepEqual({ channel: evs[0].channel, state: evs[0].state, reason: evs[0].reason }, { channel: 'hbcli-hotel', state: 'down', reason: 'auth-denied' }, 'fail 应产 down 事件带 reason');
+assert.deepEqual({ channel: evs[1].channel, state: evs[1].state }, { channel: 'open-meteo', state: 'ok' }, 'ok 且此前 down 应产 ok 恢复事件');
+const noWrites = evaluateProbeResults([{ probe: om, result: { ok: true, ms: 90 } }], new Set(), now);
 assert.equal(noWrites.length, 0, 'ok 且此前健康 → 零写放大');
+// ── 2. latest-wins:'ok' 超越更早的 down ──────────────────────────────────────
 const stateRoot = join(tmp, 'state');
-await mkdir(join(stateRoot, 'gotry-state'), {
-    recursive: true
-});
+await mkdir(join(stateRoot, 'gotry-state'), { recursive: true });
 const jsonl = join(stateRoot, 'gotry-state', 'channel-health.jsonl');
 await writeFile(jsonl, [
-    JSON.stringify({
-        channel: 'opensky',
-        state: 'down',
-        reason: 'http-503',
-        at: '2026-09-07T10:00:00.000Z'
-    }),
-    JSON.stringify({
-        channel: 'opensky',
-        state: 'ok',
-        at: '2026-09-07T11:00:00.000Z'
-    }),
-    JSON.stringify({
-        channel: 'hbcli-hotel',
-        state: 'down',
-        reason: 'auth-denied',
-        at: '2026-09-07T10:30:00.000Z'
-    }),
+    JSON.stringify({ channel: 'opensky', state: 'down', reason: 'http-503', at: '2026-09-07T10:00:00.000Z' }),
+    JSON.stringify({ channel: 'opensky', state: 'ok', at: '2026-09-07T11:00:00.000Z' }),
+    JSON.stringify({ channel: 'hbcli-hotel', state: 'down', reason: 'auth-denied', at: '2026-09-07T10:30:00.000Z' }),
     'not-json-garbage',
-    ''
+    '',
 ].join('\n'), 'utf-8');
-const latest = await readLatestChannelEvents(stateRoot, {
-    now: Date.parse('2026-09-07T12:00:00Z')
-});
+const latest = await readLatestChannelEvents(stateRoot, { now: Date.parse('2026-09-07T12:00:00Z') });
 assert.equal(latest.get('opensky')?.state, 'ok', "'ok' 应超越同通道更早的 down");
 assert.equal(latest.get('hbcli-hotel')?.state, 'down', '未恢复通道保持 down');
 assert.equal(latest.size, 2, '坏行跳过,latest 只含两通道');
+// ── 3. doctor 消费口径:恢复后 '=== down' 不命中 ─────────────────────────────
 const openskyEv = latest.get('opensky');
 assert.ok(openskyEv && openskyEv.state !== 'down', 'doctor 的 down 判定应不再命中已恢复通道');
-const rows = (await readFile(jsonl, 'utf-8')).split('\n').filter((l)=>l.trim()).flatMap((l)=>{
+// ── 4. metrics:ok 超越后 newest 不含该通道,计数保留 ─────────────────────────
+const rows = (await readFile(jsonl, 'utf-8')).split('\n').filter((l) => l.trim()).flatMap((l) => {
     try {
-        return [
-            JSON.parse(l)
-        ];
-    } catch  {
+        return [JSON.parse(l)];
+    }
+    catch {
         return [];
     }
 });
-const stats = aggregateChannels(rows, {
-    now: new Date('2026-09-07T12:00:00Z'),
-    windowDays: 30
-});
-const openskyStat = stats.latest.find((c)=>c.channel === 'opensky');
+const stats = aggregateChannels(rows, { now: new Date('2026-09-07T12:00:00Z'), windowDays: 30 });
+const openskyStat = stats.latest.find((c) => c.channel === 'opensky');
 assert.equal(openskyStat, undefined, 'ok 超越的通道不应出现在当前 down/cooldown newest 面');
-const hbStat = stats.latest.find((c)=>c.channel === 'hbcli-hotel');
+const hbStat = stats.latest.find((c) => c.channel === 'hbcli-hotel');
 assert.ok(hbStat && hbStat.state === 'down', '未恢复通道仍在 newest 面');
+// ── 5. CLI 面 ────────────────────────────────────────────────────────────────
 const listed = defaultProbes();
-assert.ok(listed.find((p)=>p.channel === 'flyai')?.probeable === false, 'flyai 默认不探(共享额度)');
-assert.ok(listed.filter((p)=>p.channel.startsWith('session:')).every((p)=>!p.probeable), 'session:* 全部 skip');
-assert.deepEqual(parseArgs([
-    '--state-root',
-    '/tmp/x',
-    '--only',
-    'a, b',
-    '--dry-run'
-]), {
-    stateRoot: '/tmp/x',
-    only: [
-        'a',
-        'b'
-    ],
-    dryRun: true,
-    list: false
-}, 'parseArgs 解析');
-const rcList = await main([
-    '--list'
-]);
+assert.ok(listed.find((p) => p.channel === 'flyai')?.probeable === false, 'flyai 默认不探(共享额度)');
+assert.ok(listed.filter((p) => p.channel.startsWith('session:')).every((p) => !p.probeable), 'session:* 全部 skip');
+assert.deepEqual(parseArgs(['--state-root', '/tmp/x', '--only', 'a, b', '--dry-run']), { stateRoot: '/tmp/x', only: ['a', 'b'], dryRun: true, list: false }, 'parseArgs 解析');
+const rcList = await main(['--list']);
 assert.equal(rcList, 0, '--list exit 0');
-const rcBad = await main([
-    '--only',
-    'no-such-channel'
-]);
+const rcBad = await main(['--only', 'no-such-channel']);
 assert.equal(rcBad, 2, '--only 未匹配 exit 2');
 console.log('CHANNEL PROBE TESTS: 5/5 OK(evaluate 纯函数 / latest-wins 恢复 / doctor 口径 / metrics 超越 / CLI 面)');
-
-
-//# sourceURL=ts/scripts/channel-probe-tests.ts

package/dist/scripts/channel-probe.js

@@ -1,3 +1,25 @@
+/**
+ * 通道探针 tick(外部事件接缝落地第 1 段,docs/design/external-event-seam.md §6①;
+ * issue #82 兼容方向)——外部事件作为健康面第二个生产者的本地形态。
+ *
+ * 设计边界(设计文档 §4,边界即信任):
+ *  - 只读探测:每通道一个无副作用最小调用(whoami/免费公开 GET),不检索、不下单;
+ *  - 本地生产者免鉴权(§3.2 本地可信):异常写 `down` 事件进
+ *    <stateRoot>/gotry-state/channel-health.jsonl,routingAdvice/doctor 零改动受益;
+ *  - 恢复走事件:探测通过且该通道此前处于 down → 写 'ok' 恢复事件
+ *    (readLatestChannelEvents latest-wins 超越 down);此前健康则零写放大;
+ *  - session:* 通道(需用户 Chrome 会话)无头不可探,显式 skip 不误报;
+ *  - flyai 默认不探(匿名共享额度,探针烧额度弊大于利)——`--only flyai` 显式选入;
+ *  - 不做常驻监听:tick 由 loopx/cron 驱动,一次运行一轮探测后退出。
+ *
+ * 用法(loopx/cron 驱动):
+ *   npx tsx ts/scripts/channel-probe.ts --state-root <root>            # 探测+落账
+ *   npx tsx ts/scripts/channel-probe.ts --dry-run                      # 只打印不落账
+ *   npx tsx ts/scripts/channel-probe.ts --only hbcli-hotel,open-meteo  # 选通道
+ *   npx tsx ts/scripts/channel-probe.ts --list                         # 列探测面
+ *
+ * @module scripts/channel-probe
+ */
 import { recordChannelEvent, readLatestChannelEvents } from '../capabilities/channel-health.js';
 function timeout(ms) {
     return AbortSignal.timeout(ms);
@@ -5,179 +27,81 @@ function timeout(ms) {
 async function fetchOk(url, what, ms = 8000) {
     const t0 = Date.now();
     try {
-        const res = await fetch(url, {
-            signal: timeout(ms),
-            headers: {
-                Accept: 'application/json'
-            }
-        });
-        if (res.ok) return {
-            ok: true,
-            ms: Date.now() - t0
-        };
-        return {
-            ok: false,
-            reason: `${what}-http-${res.status}`,
-            ms: Date.now() - t0
-        };
-    } catch (err) {
+        const res = await fetch(url, { signal: timeout(ms), headers: { Accept: 'application/json' } });
+        if (res.ok)
+            return { ok: true, ms: Date.now() - t0 };
+        return { ok: false, reason: `${what}-http-${res.status}`, ms: Date.now() - t0 };
+    }
+    catch (err) {
         const msg = err instanceof Error ? err.name : String(err);
-        return {
-            ok: false,
-            reason: msg === 'TimeoutError' ? 'timeout' : 'unreachable',
-            ms: Date.now() - t0
-        };
+        return { ok: false, reason: msg === 'TimeoutError' ? 'timeout' : 'unreachable', ms: Date.now() - t0 };
     }
 }
 function spawnOk(cmd, args, what, ms = 10000) {
-    return async ()=>{
+    return async () => {
         const t0 = Date.now();
         try {
             const { spawn } = await import('node:child_process');
-            const child = spawn(cmd, args, {
-                stdio: [
-                    'ignore',
-                    'ignore',
-                    'ignore'
-                ]
-            });
-            const code = await new Promise((resolve, reject)=>{
-                const timer = setTimeout(()=>{
-                    child.kill('SIGKILL');
-                    reject(new Error('timeout'));
-                }, ms);
-                child.on('exit', (c)=>{
-                    clearTimeout(timer);
-                    resolve(c ?? 1);
-                });
-                child.on('error', (e)=>{
-                    clearTimeout(timer);
-                    reject(e);
-                });
+            const child = spawn(cmd, args, { stdio: ['ignore', 'ignore', 'ignore'] });
+            const code = await new Promise((resolve, reject) => {
+                const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('timeout')); }, ms);
+                child.on('exit', (c) => { clearTimeout(timer); resolve(c ?? 1); });
+                child.on('error', (e) => { clearTimeout(timer); reject(e); });
             });
-            return code === 0 ? {
-                ok: true,
-                ms: Date.now() - t0
-            } : {
-                ok: false,
-                reason: `${what}-exit-${code}`,
-                ms: Date.now() - t0
-            };
-        } catch (err) {
+            return code === 0 ? { ok: true, ms: Date.now() - t0 } : { ok: false, reason: `${what}-exit-${code}`, ms: Date.now() - t0 };
+        }
+        catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
-            return {
-                ok: false,
-                reason: msg === 'timeout' ? 'timeout' : 'spawn-failed',
-                ms: Date.now() - t0
-            };
+            return { ok: false, reason: msg === 'timeout' ? 'timeout' : 'spawn-failed', ms: Date.now() - t0 };
         }
     };
 }
+/** 默认探测面(设计文档 §6①「关键通道」的无头子集;session 系与 flyai 显式 skip) */
 export function defaultProbes() {
     return [
         {
             channel: 'hbcli-hotel',
             probeable: true,
-            run: spawnOk('hbcli', [
-                'auth',
-                'whoami'
-            ], 'auth-denied')
+            run: spawnOk('hbcli', ['auth', 'whoami'], 'auth-denied'),
         },
         {
             channel: 'open-meteo',
             probeable: true,
-            run: ()=>fetchOk('https://api.open-meteo.com/v1/forecast?latitude=25.2048&longitude=55.2708&current=temperature_2m', 'weather')
+            run: () => fetchOk('https://api.open-meteo.com/v1/forecast?latitude=25.2048&longitude=55.2708&current=temperature_2m', 'weather'),
         },
         {
             channel: 'opensky',
             probeable: true,
-            run: ()=>fetchOk('https://opensky-network.org/api/states/all?lamin=24.0&lomin=53.0&lamax=26.5&lomax=56.5', 'flights', 12000)
-        },
-        {
-            channel: 'flyai',
-            probeable: false,
-            skipReason: 'anonymous-shared-quota——探针烧额度弊大于利;--only flyai 显式选入',
-            run: async ()=>({
-                    ok: true,
-                    ms: 0
-                })
+            run: () => fetchOk('https://opensky-network.org/api/states/all?lamin=24.0&lomin=53.0&lamax=26.5&lomax=56.5', 'flights', 12000),
         },
-        {
-            channel: 'session:ctrip-flight',
-            probeable: false,
-            skipReason: '需用户 Chrome 会话,无头不可探',
-            run: async ()=>({
-                    ok: true,
-                    ms: 0
-                })
-        },
-        {
-            channel: 'session:ctrip-hotel',
-            probeable: false,
-            skipReason: '需用户 Chrome 会话,无头不可探',
-            run: async ()=>({
-                    ok: true,
-                    ms: 0
-                })
-        },
-        {
-            channel: 'session:12306-train',
-            probeable: false,
-            skipReason: '需用户 Chrome 会话,无头不可探',
-            run: async ()=>({
-                    ok: true,
-                    ms: 0
-                })
-        },
-        {
-            channel: 'anything-geo',
-            probeable: false,
-            skipReason: '静态包通道,无远端可探',
-            run: async ()=>({
-                    ok: true,
-                    ms: 0
-                })
-        },
-        {
-            channel: 'static-hotel',
-            probeable: false,
-            skipReason: '静态包通道,无远端可探',
-            run: async ()=>({
-                    ok: true,
-                    ms: 0
-                })
-        },
-        {
-            channel: 'web-read',
-            probeable: false,
-            skipReason: '依赖 agent-reach 装配态,探测意义低;--only 显式选入可探',
-            run: async ()=>({
-                    ok: true,
-                    ms: 0
-                })
-        }
+        { channel: 'flyai', probeable: false, skipReason: 'anonymous-shared-quota——探针烧额度弊大于利;--only flyai 显式选入', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'session:ctrip-flight', probeable: false, skipReason: '需用户 Chrome 会话,无头不可探', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'session:ctrip-hotel', probeable: false, skipReason: '需用户 Chrome 会话,无头不可探', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'session:12306-train', probeable: false, skipReason: '需用户 Chrome 会话,无头不可探', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'anything-geo', probeable: false, skipReason: '静态包通道,无远端可探', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'static-hotel', probeable: false, skipReason: '静态包通道,无远端可探', run: async () => ({ ok: true, ms: 0 }) },
+        { channel: 'web-read', probeable: false, skipReason: '依赖 agent-reach 装配态,探测意义低;--only 显式选入可探', run: async () => ({ ok: true, ms: 0 }) },
     ];
 }
+/**
+ * 探测结果 → 事件序列(纯函数,测试锚点):
+ *  - fail → down 事件(永远落,哪怕已 down——重申事实,消费方幂等);
+ *  - ok 且此前处于 down → 'ok' 恢复事件(latest-wins 超越);
+ *  - ok 且此前健康 → 不落(零写放大);
+ *  - skip(probeable=false)→ 不产生事件。
+ */
 export function evaluateProbeResults(results, priorDown, now = new Date()) {
     const events = [];
-    for (const { probe, result } of results){
-        if (!probe.probeable) continue;
+    for (const { probe, result } of results) {
+        if (!probe.probeable)
+            continue;
         if (result.ok) {
             if (priorDown.has(probe.channel)) {
-                events.push({
-                    channel: probe.channel,
-                    state: 'ok',
-                    at: now.toISOString()
-                });
+                events.push({ channel: probe.channel, state: 'ok', at: now.toISOString() });
             }
             continue;
         }
-        events.push({
-            channel: probe.channel,
-            state: 'down',
-            reason: result.reason,
-            at: now.toISOString()
-        });
+        events.push({ channel: probe.channel, state: 'down', reason: result.reason, at: now.toISOString() });
     }
     return events;
 }
@@ -186,67 +110,60 @@ export function parseArgs(argv) {
     let only;
     let dryRun = false;
     let list = false;
-    for(let i = 0; i < argv.length; i += 1){
+    for (let i = 0; i < argv.length; i += 1) {
         const a = argv[i];
-        if (a === '--state-root') stateRoot = argv[++i];
-        else if (a === '--only') only = (argv[++i] ?? '').split(',').map((s)=>s.trim()).filter(Boolean);
-        else if (a === '--dry-run') dryRun = true;
-        else if (a === '--list') list = true;
+        if (a === '--state-root')
+            stateRoot = argv[++i];
+        else if (a === '--only')
+            only = (argv[++i] ?? '').split(',').map((s) => s.trim()).filter(Boolean);
+        else if (a === '--dry-run')
+            dryRun = true;
+        else if (a === '--list')
+            list = true;
     }
-    return {
-        stateRoot,
-        only,
-        dryRun,
-        list
-    };
+    return { stateRoot, only, dryRun, list };
 }
 export async function main(argv) {
     const args = parseArgs(argv);
     const all = defaultProbes();
     if (args.list) {
-        for (const p of all){
+        for (const p of all) {
             console.log(`${p.probeable ? 'probe' : 'skip '}  ${p.channel}${p.skipReason ? `  # ${p.skipReason}` : ''}`);
         }
         return 0;
     }
-    const selected = args.only?.length ? all.filter((p)=>args.only.includes(p.channel)) : all.filter((p)=>p.probeable);
+    const selected = args.only?.length ? all.filter((p) => args.only.includes(p.channel)) : all.filter((p) => p.probeable);
     if (selected.length === 0) {
         console.error('[channel-probe] --only 未匹配任何通道;--list 查看探测面');
         return 2;
     }
     const results = [];
-    for (const probe of selected){
+    for (const probe of selected) {
         const result = await probe.run();
-        results.push({
-            probe,
-            result
-        });
+        results.push({ probe, result });
         console.log(`[channel-probe] ${result.ok ? 'ok  ' : 'FAIL'} ${probe.channel} (${result.ms}ms)${result.ok ? '' : ` reason=${result.reason}`}`);
     }
-    const failures = results.filter((r)=>!r.result.ok).length;
+    const failures = results.filter((r) => !r.result.ok).length;
     if (args.dryRun || !args.stateRoot) {
-        if (!args.stateRoot) console.log('[channel-probe] 未给 --state-root:只探测不落账(等价 --dry-run)');
+        if (!args.stateRoot)
+            console.log('[channel-probe] 未给 --state-root:只探测不落账(等价 --dry-run)');
         return failures > 0 ? 1 : 0;
     }
     let priorDown = new Set();
     try {
         const latest = await readLatestChannelEvents(args.stateRoot);
-        priorDown = new Set([
-            ...latest.entries()
-        ].filter(([, ev])=>ev.state === 'down' || ev.state === 'cooldown').map(([ch])=>ch));
-    } catch  {}
-    for (const ev of evaluateProbeResults(results, priorDown)){
+        priorDown = new Set([...latest.entries()].filter(([, ev]) => ev.state === 'down' || ev.state === 'cooldown').map(([ch]) => ch));
+    }
+    catch { /* 读不到按全健康处理 */ }
+    for (const ev of evaluateProbeResults(results, priorDown)) {
         await recordChannelEvent(args.stateRoot, ev);
         console.log(`[channel-probe] 记录 ${ev.state} ${ev.channel}${ev.reason ? `(${ev.reason})` : ''}`);
     }
     return failures > 0 ? 1 : 0;
 }
 if (import.meta.url === `file://${process.argv[1]}`) {
-    main(process.argv.slice(2)).then((code)=>process.exit(code)).catch((err)=>{
+    main(process.argv.slice(2)).then((code) => process.exit(code)).catch((err) => {
         console.error('[channel-probe] fatal:', err instanceof Error ? err.message : err);
         process.exit(1);
     });
 }
-
-
-//# sourceURL=ts/scripts/channel-probe.ts