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

package/dist/capabilities/effect.js

@@ -1,7 +1,31 @@
-import { CircuitBreaker, withRetry } from './resilience.js';
+/**
+ * 效应解译器 effect_interpreter.v1(issue #16 采纳,ADR-18)。
+ *
+ * 「效应描述 + 解译器」:业务/编排层对基础设施的依赖收敛为一个**纯数据的效应值**
+ * (effect 名 + params),不存在对渠道模块的直接 import——agent 不调用 Ctrip.Query(),
+ * 它描述 `SEARCH_FLIGHT`;把意图换算成真实副作用的是可替换的解译器:
+ *
+ *   - 生产解译器 makeProductionInterpreter:查注册表 → 韧性横切(指数退避重试/
+ *     断路器,per-效应策略表)→ 渠道 handler(现能力层函数,零改写);
+ *   - mock  解译器 makeMockInterpreter:夹具回放(CI/本地无网确定性);
+ *   - 浏览器解译 = SESSION_* 效应(用户本人登录态的扩展桥车道,2026-08-29 起默认传输:
+ *     MV3 GoTry Session Bridge + 本地桥长轮询,零系统弹窗;ReadGuard+授权闸不变,
+ *     非 CUA 视觉点击——本仓已按零 Python 依赖与 a11y/DOM 优先判死后者,
+ *     docs/design/effect-interpreter.md §4)。
+ *
+ * 解译产物:`{ result, trace }`——result 是渠道自有 observation **原样透传**
+ * (ADR-13 平铺 envelope 在工具层不受扰);trace 是解译层横切证据
+ * {attempts, backoffMs, breaker, declined, evidence},拼进工具层 summary/evidence。
+ * unknown-effect / 断路拒绝时 result=null + declinedObservation() 给出平铺失败面。
+ *
+ * 多渠道比价口径:解译器**不做**渠道间自动路由/降级排序——OTA 工具面平铺是
+ * founder 判定(persona 19),比价发生在 agent 层(多工具并调+证据链逐源标注);
+ * 本层只让「每条通道」更可替换、可熔断、可 mock。
+ */
+import { CircuitBreaker, withRetry, } from './resilience.js';
 import { flyaiSearch } from './flyai.js';
 import { checkAvail, hotelRates, searchHotels } from './hbcli.js';
-import { sessionFlightSearch, sessionHotelSearch, sessionTrainSearch } from './session-search.js';
+import { sessionFlightSearch, sessionHotelSearch, sessionTrainSearch, sessionDidaSearch } from './session-search.js';
 import { geocodePlace, getClimate, getForecast } from './weather.js';
 import { verifyFlight } from './opensky.js';
 import { anythingSearch } from './anything.js';
@@ -9,6 +33,7 @@ import { continentListUrl, countryPageUrl, extractVisaSection, fetchVisaPolicyPa
 import { readUrl, reach, reachStatus } from './agent-reach.js';
 import { githubSearch, videoSubtitle } from './agent-reach-deep.js';
 import { sessionLogin } from './session-login.js';
+/** C 档中国领事服务网抓取编排:country 直抓 / continent 列表遍历(≤limit,默认 10;抓取纪律=礼貌间隔,不并发) */
 async function fetchVisaPolicyEntries(p) {
     const started = Date.now();
     const fetchedAt = new Date().toISOString();
@@ -16,322 +41,267 @@ async function fetchVisaPolicyEntries(p) {
     const facts = [];
     const targets = [];
     if (p.country) {
-        targets.push({
-            continent: p.continent ?? 'yz_645708',
-            country: p.country
-        });
-    } else if (p.continent) {
+        targets.push({ continent: p.continent ?? 'yz_645708', country: p.country });
+    }
+    else if (p.continent) {
         const listUrl = continentListUrl(p.continent);
-        if (!listUrl) return {
-            ok: false,
-            via: 'visa-policy-error',
-            evidence: `[visa-policy@${fetchedAt}] 非法洲路径`,
-            latencyMs: 0,
-            facts: [],
-            countries: [],
-            error: 'invalid_continent'
-        };
+        if (!listUrl)
+            return { ok: false, via: 'visa-policy-error', evidence: `[visa-policy@${fetchedAt}] 非法洲路径`, latencyMs: 0, facts: [], countries: [], error: 'invalid_continent' };
         const page = await fetchVisaPolicyPage(listUrl, p.timeoutMs);
-        if (!page.ok || !page.html) return {
-            ok: false,
-            via: 'visa-policy-error',
-            evidence: `[visa-policy@${fetchedAt}] 洲列表抓取失败: ${page.error ?? '?'}`,
-            latencyMs: 0,
-            facts: [],
-            countries: [],
-            error: page.error
-        };
-        for (const c of listCountryPaths(page.html, p.continent).slice(0, Math.max(1, Math.min(10, p.limit ?? 10))))targets.push({
-            continent: p.continent,
-            country: c
-        });
+        if (!page.ok || !page.html)
+            return { ok: false, via: 'visa-policy-error', evidence: `[visa-policy@${fetchedAt}] 洲列表抓取失败: ${page.error ?? '?'}`, latencyMs: 0, facts: [], countries: [], error: page.error };
+        for (const c of listCountryPaths(page.html, p.continent).slice(0, Math.max(1, Math.min(10, p.limit ?? 10))))
+            targets.push({ continent: p.continent, country: c });
     }
-    for (const t of targets){
+    for (const t of targets) {
         const url = countryPageUrl(t.continent, t.country);
-        if (!url) continue;
+        if (!url)
+            continue;
         const page = await fetchVisaPolicyPage(url, p.timeoutMs);
         countries.push(t.country);
-        if (!page.ok || !page.html) continue;
+        if (!page.ok || !page.html)
+            continue;
         const section = extractVisaSection(page.html);
-        if (!section) continue;
-        facts.push(...policyFactsFromMfa({
-            countryLabel: t.country,
-            countryPath: t.country,
-            section,
-            fetchedAt
-        }));
+        if (!section)
+            continue;
+        facts.push(...policyFactsFromMfa({ countryLabel: t.country, countryPath: t.country, section, fetchedAt }));
     }
-    const evidence = facts.length > 0 ? `[visa-policy:cs-mfa@${fetchedAt}] ${facts.length} 条政策事实(抓取 ${countries.length} 国)` : `[visa-policy@${fetchedAt}] 0 条(页面缺「签证入境」章节或抓取失败;不落负事实)`;
-    return {
-        ok: true,
-        via: 'cs-mfa',
-        evidence,
-        latencyMs: Date.now() - started,
-        facts,
-        countries
-    };
+    const evidence = facts.length > 0
+        ? `[visa-policy:cs-mfa@${fetchedAt}] ${facts.length} 条政策事实(抓取 ${countries.length} 国)`
+        : `[visa-policy@${fetchedAt}] 0 条(页面缺「签证入境」章节或抓取失败;不落负事实)`;
+    return { ok: true, via: 'cs-mfa', evidence, latencyMs: Date.now() - started, facts, countries };
 }
+/** 默认渠道实现(生产解译器的 dispatch 目标;全部满足「永不抛错」能力层契约) */
 const DEFAULT_HANDLERS = {
-    FLYAI_SEARCH: (p)=>flyaiSearch(p),
-    HBCLI_HOTEL_SEARCH: (p)=>searchHotels({
-            destination: p.destination,
-            checkIn: p.checkIn,
-            checkOut: p.checkOut,
-            adults: p.adults
-        }, {
-            hbcliBin: p.hbcliBin,
-            timeoutMs: p.timeoutMs,
-            fallbackPath: p.fallbackPath
-        }),
-    HBCLI_HOTEL_RATES: (p)=>hotelRates({
-            hotelId: p.hotelId,
-            checkIn: p.checkIn,
-            checkOut: p.checkOut,
-            adults: p.adults,
-            countryCode: p.countryCode,
-            nationalityCode: p.nationalityCode,
-            residencyCode: p.residencyCode
-        }, {
-            hbcliBin: p.hbcliBin,
-            timeoutMs: p.timeoutMs
-        }),
-    HBCLI_CHECK_AVAIL: (p)=>checkAvail({
-            ratePkgId: p.ratePkgId
-        }, {
-            hbcliBin: p.hbcliBin,
-            timeoutMs: p.timeoutMs
-        }),
-    SESSION_FLIGHT_SEARCH: (p)=>sessionFlightSearch(p),
-    SESSION_HOTEL_SEARCH: (p)=>sessionHotelSearch(p),
-    SESSION_TRAIN_SEARCH: (p)=>sessionTrainSearch(p),
-    WEATHER_GEOCODE: (p)=>geocodePlace(p.name, {
-            count: p.count,
-            timeoutMs: p.timeoutMs
-        }),
-    WEATHER_FORECAST: (p)=>getForecast({
-            latitude: p.latitude,
-            longitude: p.longitude
-        }, {
-            days: p.days,
-            timeoutMs: p.timeoutMs
-        }),
-    WEATHER_CLIMATE: (p)=>getClimate({
-            latitude: p.latitude,
-            longitude: p.longitude
-        }, p.month, {
-            timeoutMs: p.timeoutMs
-        }),
-    OPENSKY_FLIGHT_VERIFY: (p)=>verifyFlight(p),
-    ANYTHING_SEARCH: (p)=>anythingSearch(p),
-    WEB_READ: (p)=>readUrl({
-            url: p.url,
-            timeoutMs: p.timeoutMs
-        }),
-    GITHUB_SEARCH: (p)=>githubSearch(p),
-    VIDEO_SUBTITLE: (p)=>videoSubtitle(p),
-    AGENT_REACH: (p)=>p.action === 'status' || !p.action && !p.channel ? reachStatus(p.timeoutMs) : reach({
-            channel: p.channel ?? '',
-            method: p.method ?? '',
-            args: p.args,
-            timeoutMs: p.timeoutMs
-        }),
-    SESSION_LOGIN: (p)=>sessionLogin({
-            waitMs: typeof p.waitSeconds === 'number' ? p.waitSeconds * 1000 : undefined
-        }),
-    VISA_POLICY_FETCH: (p)=>fetchVisaPolicyEntries(p)
-};
-const defaultIsFailure = (r)=>r?.ok === false;
-const flyaiTransient = (msg)=>msg.length > 0 && !/Sentinel/i.test(msg) && /timeout|timed out|ECONNRESET|ECONNREFUSED|ETIMEDOUT|socket|HTTP 5/i.test(msg);
-const API_RETRY = {
-    maxAttempts: 2,
-    baseDelayMs: 400,
-    maxDelayMs: 1_600
+    /** 飞猪官方只读通道(机/火/酒店;spawn CLI) */
+    FLYAI_SEARCH: (p) => flyaiSearch(p),
+    /** hotelbyte 桥(实时 hbcli → 静态包降级;spawn CLI) */
+    HBCLI_HOTEL_SEARCH: (p) => searchHotels({ destination: p.destination, checkIn: p.checkIn, checkOut: p.checkOut, adults: p.adults }, { hbcliBin: p.hbcliBin, timeoutMs: p.timeoutMs, fallbackPath: p.fallbackPath }),
+    /** hotelbyte 桥·房型报价(M0 预订链;spawn CLI;价格面无静态降级 fail-closed) */
+    HBCLI_HOTEL_RATES: (p) => hotelRates({
+        hotelId: p.hotelId, checkIn: p.checkIn, checkOut: p.checkOut, adults: p.adults,
+        countryCode: p.countryCode, nationalityCode: p.nationalityCode, residencyCode: p.residencyCode,
+    }, { hbcliBin: p.hbcliBin, timeoutMs: p.timeoutMs }),
+    /** hotelbyte 桥·下单前实时验价(M0 预订链;spawn CLI;同价格面红线,不可用即诚实失败) */
+    HBCLI_CHECK_AVAIL: (p) => checkAvail({ ratePkgId: p.ratePkgId }, { hbcliBin: p.hbcliBin, timeoutMs: p.timeoutMs }),
+    /** 用户本人登录态会话检索(浏览器解译通道:扩展桥默认 + cdp 显式后备;ReadGuard+节律闸) */
+    SESSION_FLIGHT_SEARCH: (p) => sessionFlightSearch(p),
+    /** 用户本人登录态会话酒店检索(2026-09-03 实装;同浏览器解译通道,风控红线同款) */
+    SESSION_HOTEL_SEARCH: (p) => sessionHotelSearch(p),
+    /** 12306 余票会话检索(2026-09-03 实装;公开查询面,无登录闸;同浏览器解译通道) */
+    SESSION_TRAIN_SEARCH: (p) => sessionTrainSearch(p),
+    /** Dida 供应商门户实时价会话检索(2026-09-09 实装;hotel-be portal integration 迁移线) */
+    SESSION_DIDA_SEARCH: (p) => sessionDidaSearch(p),
+    /** 地名 → 坐标(open-meteo → nominatim 双源,免费) */
+    WEATHER_GEOCODE: (p) => geocodePlace(p.name, { count: p.count, timeoutMs: p.timeoutMs }),
+    /** 预报(≤16 天,免费无 key) */
+    WEATHER_FORECAST: (p) => getForecast({ latitude: p.latitude, longitude: p.longitude }, { days: p.days, timeoutMs: p.timeoutMs }),
+    /** 历史气候(季节性基线,免费无 key) */
+    WEATHER_CLIMATE: (p) => getClimate({ latitude: p.latitude, longitude: p.longitude }, p.month, { timeoutMs: p.timeoutMs }),
+    /** OpenSky ADS-B 实时印证(免费匿名,~400 credits/天) */
+    OPENSKY_FLIGHT_VERIFY: (p) => verifyFlight(p),
+    /** hotel-be Anything 目的地/酒店候选(hbcli CLI;gotry_anything_search 同源,D-23 收编) */
+    ANYTHING_SEARCH: (p) => anythingSearch(p),
+    /** 网页读取兜底(r.jina.ai 免费公共源;gotry_web_search 同源,D-23 收编) */
+    WEB_READ: (p) => readUrl({ url: p.url, timeoutMs: p.timeoutMs }),
+    /** GitHub 仓库搜索(gh CLI;agent-reach-deep 执行面,gotry_github_search 同源,D-23 收编) */
+    GITHUB_SEARCH: (p) => githubSearch(p),
+    /** 视频字幕拉取(yt-dlp;agent-reach-deep 执行面,gotry_video_subtitle 同源,D-23 收编) */
+    VIDEO_SUBTITLE: (p) => videoSubtitle(p),
+    /** agent-reach 反射桥(status=上游 doctor;reach=渠道×方法透传,gotry_agent_reach 同源,D-23 收编) */
+    AGENT_REACH: (p) => (p.action === 'status' || (!p.action && !p.channel))
+        ? reachStatus(p.timeoutMs)
+        : reach({ channel: p.channel ?? '', method: p.method ?? '', args: p.args, timeoutMs: p.timeoutMs }),
+    /** 账号会话登录引导(浏览器通道;票据名只读 0 值过手,gotry_session_login 同源,D-23 收编) */
+    SESSION_LOGIN: (p) => sessionLogin({ waitMs: typeof p.waitSeconds === 'number' ? p.waitSeconds * 1000 : undefined }),
+    /** 政策事实生产端 v1(issue #141,D-26):C 档中国领事服务网国家指南树(礼貌抓取:永不重试+断路器护站) */
+    VISA_POLICY_FETCH: (p) => fetchVisaPolicyEntries(p),
 };
-const API_BREAKER = {
-    failureThreshold: 3,
-    openMs: 30_000
-};
-const hbcliTimeout = (r)=>{
+const defaultIsFailure = (r) => r?.ok === false;
+/** FlyAI 错误原话里瞬时类(超时/网络断)才值得重试;Sentinel 限流与 ENOENT 永不 */
+const flyaiTransient = (msg) => msg.length > 0
+    && !/Sentinel/i.test(msg)
+    && /timeout|timed out|ECONNRESET|ECONNREFUSED|ETIMEDOUT|socket|HTTP 5/i.test(msg);
+const API_RETRY = { maxAttempts: 2, baseDelayMs: 400, maxDelayMs: 1_600 };
+const API_BREAKER = { failureThreshold: 3, openMs: 30_000 };
+/**
+ * HBCLI timeout 专用瞬时判定(2026-09-02 迪拜 session 实况:hotel-list 首调
+ * 30s 超时,LLM 立即手动重试即成功——上游冷启动建后端 session 可超 30s,而
+ * 「候选路径是切换不是重试」的契约只针对 ENOENT 类 spawn 失败,不覆盖超时)。
+ * 只有 timeout 类失败值得重试一次;ENOENT/退码类上游明确说「不」的失败永不。
+ */
+const hbcliTimeout = (r) => {
     const msg = String((r ?? {}).error ?? '');
     return msg.length > 0 && /timeout/i.test(msg);
 };
-const HBCLI_RETRY = {
-    maxAttempts: 2,
-    baseDelayMs: 300,
-    maxDelayMs: 1_000
-};
+const HBCLI_RETRY = { maxAttempts: 2, baseDelayMs: 300, maxDelayMs: 1_000 };
+/**
+ * 渠道韧性策略表(权威面;docs/design/effect-interpreter.md §3 同表逐行有依据):
+ *   - FLYAI:瞬时代码级错误重试 1 次;连续 3 次 error(含 Sentinel)熔断 60s 保护配额;
+ *     试用额度达限(429)归 needs-setup,永不重试;
+ *   - HBCLI:仅 timeout 类失败重试 1 次(冷启动建后端 session 可超时,重试即恢复);
+ *     ENOENT/退码类永不重试(上游契约「候选路径是切换不是重试」),熔断同上;
+ *     RATES/CHECK_AVAIL 同族,且价格面无静态降级(fail-closed,不估算房价——
+ *     与 bookable-facts 证据分级同口径,live_inventory 才可进确认卡);
+ *   - SESSION:永不重试、不熔断——风控/挑战是「上游说不」,重试即红线;
+ *     节律闸(≥30s)在渠道内(session-search §3.4),不在本层重复。
+ *   - WEATHER/OPENSKY:免费源,瞬时网络抖动可重试,熔断防免费配额空转。
+ *   - ANYTHING:同 HBCLI 族(timeout 类瞬时重试 1 次;ENOENT/退码类永不);
+ *   - WEB_READ:r.jina.ai 免费公共源,瞬时抖动可重试,熔断防公共配额空转;
+ *   - GITHUB/VIDEO(gh/yt-dlp):verdict=timeout 瞬时重试 1 次;not-installed=配置态不重试;
+ *   - AGENT_REACH:反射桥透传(wrapper 不是 router)——永不重试不熔断,上游超时自管;
+ *   - SESSION_LOGIN:同 SESSION 浏览器族(风控红线)。
+ *   (D-23 收尾,issue #115:六渠道入表,没有策略表行就没有效应。)
+ */
 const SPECS = {
     FLYAI_SEARCH: {
         channel: 'cli',
-        retry: {
-            maxAttempts: 2,
-            baseDelayMs: 500,
-            maxDelayMs: 2_000
-        },
-        breaker: {
-            failureThreshold: 3,
-            openMs: 60_000
-        },
-        isRetryable: (_r, e)=>{
+        retry: { maxAttempts: 2, baseDelayMs: 500, maxDelayMs: 2_000 },
+        breaker: { failureThreshold: 3, openMs: 60_000 },
+        isRetryable: (_r, e) => {
             const msg = e != null ? String(e.message ?? e) : String((_r ?? {}).error ?? '');
             return flyaiTransient(msg);
         },
-        isFailure: defaultIsFailure
+        isFailure: defaultIsFailure,
     },
     HBCLI_HOTEL_SEARCH: {
         channel: 'cli',
         retry: HBCLI_RETRY,
-        isRetryable: (r)=>hbcliTimeout(r),
-        breaker: {
-            failureThreshold: 3,
-            openMs: 60_000
-        },
-        isFailure: (r)=>r.via === 'hbcli-error'
+        // spec 级 isRetryable 是解译器组装 policy 的权威源(FLYAI 同款):仅 timeout 类
+        // 瞬时(冷启动建后端 session);ENOENT/退码类永不(「切换不是重试」契约不变)
+        isRetryable: (r) => hbcliTimeout(r),
+        breaker: { failureThreshold: 3, openMs: 60_000 },
+        isFailure: r => r.via === 'hbcli-error',
     },
     HBCLI_HOTEL_RATES: {
         channel: 'cli',
         retry: HBCLI_RETRY,
-        isRetryable: (r)=>hbcliTimeout(r),
-        breaker: {
-            failureThreshold: 3,
-            openMs: 60_000
-        },
-        isFailure: (r)=>r.via === 'hbcli-error'
+        isRetryable: (r) => hbcliTimeout(r),
+        breaker: { failureThreshold: 3, openMs: 60_000 },
+        isFailure: r => r.via === 'hbcli-error',
     },
     HBCLI_CHECK_AVAIL: {
         channel: 'cli',
         retry: HBCLI_RETRY,
-        isRetryable: (r)=>hbcliTimeout(r),
-        breaker: {
-            failureThreshold: 3,
-            openMs: 60_000
-        },
-        isFailure: (r)=>r.via === 'hbcli-error'
+        isRetryable: (r) => hbcliTimeout(r),
+        breaker: { failureThreshold: 3, openMs: 60_000 },
+        isFailure: r => r.via === 'hbcli-error',
     },
     SESSION_FLIGHT_SEARCH: {
         channel: 'browser',
         retry: null,
         breaker: null,
-        isFailure: defaultIsFailure
+        isFailure: defaultIsFailure,
     },
     SESSION_HOTEL_SEARCH: {
         channel: 'browser',
         retry: null,
         breaker: null,
-        isFailure: defaultIsFailure
+        isFailure: defaultIsFailure,
     },
     SESSION_TRAIN_SEARCH: {
         channel: 'browser',
         retry: null,
         breaker: null,
-        isFailure: defaultIsFailure
-    },
-    WEATHER_GEOCODE: {
-        channel: 'api',
-        retry: API_RETRY,
-        breaker: API_BREAKER,
-        isFailure: defaultIsFailure
-    },
-    WEATHER_FORECAST: {
-        channel: 'api',
-        retry: API_RETRY,
-        breaker: API_BREAKER,
-        isFailure: defaultIsFailure
+        isFailure: defaultIsFailure,
     },
-    WEATHER_CLIMATE: {
-        channel: 'api',
-        retry: API_RETRY,
-        breaker: API_BREAKER,
-        isFailure: defaultIsFailure
+    SESSION_DIDA_SEARCH: {
+        channel: 'browser',
+        retry: null,
+        breaker: null,
+        isFailure: defaultIsFailure,
     },
+    WEATHER_GEOCODE: { channel: 'api', retry: API_RETRY, breaker: API_BREAKER, isFailure: defaultIsFailure },
+    WEATHER_FORECAST: { channel: 'api', retry: API_RETRY, breaker: API_BREAKER, isFailure: defaultIsFailure },
+    WEATHER_CLIMATE: { channel: 'api', retry: API_RETRY, breaker: API_BREAKER, isFailure: defaultIsFailure },
     OPENSKY_FLIGHT_VERIFY: {
         channel: 'api',
         retry: API_RETRY,
         breaker: API_BREAKER,
-        isRetryable: (_r, e)=>e != null || (_r ?? {}).verdict === 'unavailable',
-        isFailure: (r)=>r.via === 'opensky-error'
+        isRetryable: (_r, e) => e != null || (_r ?? {}).verdict === 'unavailable',
+        isFailure: r => r.via === 'opensky-error',
     },
+    // --- D-23 收尾(issue #115):六渠道入注册表——没有策略表行就没有效应 ---
+    // ANYTHING:同 HBCLI 族(hbcli CLI):仅 timeout 类瞬时(冷启动建后端 session)重试 1 次;
+    // ENOENT/退码类永不(「切换不是重试」契约);熔断防上游空转
     ANYTHING_SEARCH: {
         channel: 'cli',
         retry: HBCLI_RETRY,
-        isRetryable: (r)=>hbcliTimeout(r),
-        breaker: {
-            failureThreshold: 3,
-            openMs: 60_000
-        },
-        isFailure: (r)=>r.via === 'hbcli-anything-error'
+        isRetryable: (r) => hbcliTimeout(r),
+        breaker: { failureThreshold: 3, openMs: 60_000 },
+        isFailure: r => r.via === 'hbcli-anything-error',
     },
+    // WEB_READ:r.jina.ai 免费公共源(同 WEATHER/OPENSKY 族):瞬时网络抖动可重试,
+    // 熔断防公共配额空转;非法 URL 是用户输入错(isFailure 不含,不重试不熔断)
     WEB_READ: {
         channel: 'api',
         retry: API_RETRY,
         breaker: API_BREAKER,
-        isFailure: (r)=>r.via === 'r.jina.ai-error'
+        isFailure: r => r.via === 'r.jina.ai-error',
     },
+    // GITHUB/VIDEO(gh/yt-dlp CLI):verdict=timeout 瞬时重试 1 次(进程冷启动超时同 HBCLI
+    // 2026-09-02 实况);not-installed 是配置态(needs-setup 族,重试无意义),error 是上游说不;
+    // 两者都计入熔断(防坏环境空转)
     GITHUB_SEARCH: {
         channel: 'cli',
         retry: HBCLI_RETRY,
-        isRetryable: (r)=>r.verdict === 'timeout',
-        breaker: {
-            failureThreshold: 3,
-            openMs: 60_000
-        },
-        isFailure: (r)=>{
-            const v = r.verdict;
-            return v === 'error' || v === 'timeout';
-        }
+        isRetryable: (r) => r.verdict === 'timeout',
+        breaker: { failureThreshold: 3, openMs: 60_000 },
+        isFailure: r => { const v = r.verdict; return v === 'error' || v === 'timeout'; },
     },
     VIDEO_SUBTITLE: {
         channel: 'cli',
         retry: HBCLI_RETRY,
-        isRetryable: (r)=>r.verdict === 'timeout',
-        breaker: {
-            failureThreshold: 3,
-            openMs: 60_000
-        },
-        isFailure: (r)=>{
-            const v = r.verdict;
-            return v === 'error' || v === 'timeout';
-        }
+        isRetryable: (r) => r.verdict === 'timeout',
+        breaker: { failureThreshold: 3, openMs: 60_000 },
+        isFailure: r => { const v = r.verdict; return v === 'error' || v === 'timeout'; },
     },
+    // AGENT_REACH:反射桥透传(wrapper 不是 router,D-4a')——上游超时自管,重试会放大
+    // 上游配额消耗,永不重试不熔断;needs-setup/not-installed 是「上游说不」同 SESSION 族
     AGENT_REACH: {
         channel: 'cli',
         retry: null,
         breaker: null,
-        isFailure: (r)=>r.verdict === 'error'
+        isFailure: r => r.verdict === 'error',
     },
+    // SESSION_LOGIN:同 SESSION_* 浏览器族——风控/挑战红线,永不重试不熔断;
+    // pending 是「等用户」不是失败
     SESSION_LOGIN: {
         channel: 'browser',
         retry: null,
         breaker: null,
-        isFailure: defaultIsFailure
+        isFailure: defaultIsFailure,
     },
+    // VISA_POLICY(issue #141,D-26 v1):C 档中国领事服务网——政府权威源礼貌抓取:
+    // 永不重试(抓取纪律)+ 断路器防 hammering 政府站点;页面缺章节=无结论不落负事实
     VISA_POLICY_FETCH: {
         channel: 'api',
         retry: null,
-        breaker: {
-            failureThreshold: 2,
-            openMs: 300_000
-        },
-        isFailure: defaultIsFailure
-    }
+        breaker: { failureThreshold: 2, openMs: 300_000 },
+        isFailure: defaultIsFailure,
+    },
 };
+/** 断路/未注册时的平铺失败观察(ADR-13 ToolFailure 兼容形态,工具层可直接返回) */
 export function declinedObservation(effect, trace) {
     return {
         ok: false,
         verdict: 'error',
-        summary: trace.declined === 'circuit-open' ? `${effect} 通道被断路器开启保护(连续失败达到阈值,冷却中)——不要立即重试,换其他工具或稍后再试;原因见 trace 证据链` : `${effect} 未登记效应(effect_interpreter.v1 注册表外,生产解译器拒绝)`,
-        evidence: trace.evidence.join(';')
+        summary: trace.declined === 'circuit-open'
+            ? `${effect} 通道被断路器开启保护(连续失败达到阈值,冷却中)——不要立即重试,换其他工具或稍后再试;原因见 trace 证据链`
+            : `${effect} 未登记效应(effect_interpreter.v1 注册表外,生产解译器拒绝)`,
+        evidence: trace.evidence.join(';'),
     };
 }
 const defaultBreakers = new Map();
-const defaultSleep = (ms)=>new Promise((resolve)=>setTimeout(resolve, ms));
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/** 测试隔离:清空产品单例断路器(断路状态是进程内瞬态,同 rate limiter 先例) */
 export function __resetEffectBreakersForTest() {
     defaultBreakers.clear();
 }
 export function makeProductionInterpreter(opts = {}) {
     const breakers = opts.breakers ?? defaultBreakers;
     const sleep = opts.sleep ?? defaultSleep;
-    return async (fx)=>{
+    return async (fx) => {
         const ts = new Date().toISOString();
         const name = fx.effect;
         const spec = SPECS[name];
@@ -339,128 +309,72 @@ export function makeProductionInterpreter(opts = {}) {
         if (!spec || !handler) {
             return {
                 result: null,
-                trace: {
-                    effect: fx.effect,
-                    channel: 'api',
-                    attempts: 0,
-                    backoffMs: 0,
-                    breaker: 'off',
-                    declined: 'unknown-effect',
-                    evidence: [
-                        `[效应:${fx.effect}@${ts}] unknown effect`
-                    ]
-                }
+                trace: { effect: fx.effect, channel: 'api', attempts: 0, backoffMs: 0, breaker: 'off', declined: 'unknown-effect', evidence: [`[效应:${fx.effect}@${ts}] unknown effect`] },
             };
         }
-        const br = (()=>{
-            if (!spec.breaker) return null;
+        const br = (() => {
+            if (!spec.breaker)
+                return null;
             const existing = breakers.get(fx.effect);
-            if (existing) return existing;
-            const created = new CircuitBreaker({
-                ...spec.breaker,
-                ...opts.now ? {
-                    now: opts.now
-                } : {}
-            });
+            if (existing)
+                return existing;
+            const created = new CircuitBreaker({ ...spec.breaker, ...(opts.now ? { now: opts.now } : {}) });
             breakers.set(fx.effect, created);
             return created;
         })();
-        const gate = br?.canAttempt() ?? {
-            allowed: true,
-            state: 'closed'
-        };
+        const gate = br?.canAttempt() ?? { allowed: true, state: 'closed' };
         if (!gate.allowed) {
-            const trace = {
-                effect: fx.effect,
-                channel: spec.channel,
-                attempts: 0,
-                backoffMs: 0,
-                breaker: gate.state,
-                declined: 'circuit-open',
-                evidence: [
-                    `[效应:${fx.effect}@${ts}] breaker=${gate.state} 拒绝(冷却中,不重试)`
-                ]
-            };
-            return {
-                result: null,
-                trace
-            };
+            const trace = { effect: fx.effect, channel: spec.channel, attempts: 0, backoffMs: 0, breaker: gate.state, declined: 'circuit-open', evidence: [`[效应:${fx.effect}@${ts}] breaker=${gate.state} 拒绝(冷却中,不重试)`] };
+            return { result: null, trace };
         }
-        const policy = spec.retry ? {
-            maxAttempts: spec.retry.maxAttempts,
-            baseDelayMs: spec.retry.baseDelayMs,
-            maxDelayMs: spec.retry.maxDelayMs,
-            isRetryable: spec.isRetryable,
-            sleep
-        } : {
-            maxAttempts: 1,
-            baseDelayMs: 0,
-            maxDelayMs: 0,
-            sleep
-        };
+        const policy = spec.retry
+            ? { maxAttempts: spec.retry.maxAttempts, baseDelayMs: spec.retry.baseDelayMs, maxDelayMs: spec.retry.maxDelayMs, isRetryable: spec.isRetryable, sleep }
+            : { maxAttempts: 1, baseDelayMs: 0, maxDelayMs: 0, sleep };
         const dispatch = handler;
-        const outcome = await withRetry(()=>dispatch(fx.params), policy);
+        const outcome = await withRetry(() => dispatch(fx.params), policy);
         const failed = outcome.error != null || spec.isFailure(outcome.result);
-        if (br) failed ? br.onFailure() : br.onSuccess();
+        if (br)
+            failed ? br.onFailure() : br.onSuccess();
         const breakerState = br?.state() ?? 'off';
-        const evidence = [
-            `[效应:${fx.effect}@${ts}] attempts=${outcome.attempts} backoff=${outcome.backoffMs}ms breaker=${breakerState}`
-        ];
+        const evidence = [`[效应:${fx.effect}@${ts}] attempts=${outcome.attempts} backoff=${outcome.backoffMs}ms breaker=${breakerState}`];
         return {
             result: outcome.error != null ? null : outcome.result,
-            trace: {
-                effect: fx.effect,
-                channel: spec.channel,
-                attempts: outcome.attempts,
-                backoffMs: outcome.backoffMs,
-                breaker: breakerState,
-                evidence
-            }
+            trace: { effect: fx.effect, channel: spec.channel, attempts: outcome.attempts, backoffMs: outcome.backoffMs, breaker: breakerState, evidence },
         };
     };
 }
+/** 产品面解译器单例(断路器状态随进程存活;同 session-search 节律闸先例) */
 export const productionInterpreter = makeProductionInterpreter();
+/** 类型化入口:tool 层 `interpretEffect({ effect: 'FLYAI_SEARCH', params })` */
 export async function interpretEffect(fx) {
     return productionInterpreter(fx);
 }
+// ---------------------------------------------------------------------------
+// mock 解译器:CI/本地无网确定性(夹具 = 渠道 observation 的录制形态)
+// ---------------------------------------------------------------------------
+/**
+ * mock 解译器(禁止网络,0 延迟,确定性):给同一效应返回夹具原样——
+ * 渠道 observation 的录制就长什么样回放什么样,证据链由夹具自带
+ * (录制期已带 [实时API:…]),trace 落 [效应:mock@ts] 夹具回放标注。
+ * CI / 离线单测 / 巡检「不联网跑全链」即此通道(与 mock-llm 同思想的第三个成员)。
+ */
 export function makeMockInterpreter(fixtures) {
-    return async (fx)=>{
+    return async (fx) => {
         const ts = new Date().toISOString();
         const registered = Object.prototype.hasOwnProperty.call(fixtures, fx.effect);
         if (!registered) {
             return {
                 result: null,
-                trace: {
-                    effect: fx.effect,
-                    channel: 'mock',
-                    attempts: 0,
-                    backoffMs: 0,
-                    breaker: 'off',
-                    declined: 'unknown-effect',
-                    evidence: [
-                        `[效应:mock@${ts}] ${fx.effect} 未登记夹具`
-                    ]
-                }
+                trace: { effect: fx.effect, channel: 'mock', attempts: 0, backoffMs: 0, breaker: 'off', declined: 'unknown-effect', evidence: [`[效应:mock@${ts}] ${fx.effect} 未登记夹具`] },
             };
         }
         return {
             result: fixtures[fx.effect],
-            trace: {
-                effect: fx.effect,
-                channel: 'mock',
-                attempts: 1,
-                backoffMs: 0,
-                breaker: 'off',
-                evidence: [
-                    `[效应:mock@${ts}] ${fx.effect} 夹具回放(确定性,无网络)`
-                ]
-            }
+            trace: { effect: fx.effect, channel: 'mock', attempts: 1, backoffMs: 0, breaker: 'off', evidence: [`[效应:mock@${ts}] ${fx.effect} 夹具回放(确定性,无网络)`] },
         };
     };
 }
+/** 按环境选择解译器('production' 默认;'mock' 供 CI/离线) */
 export function selectInterpreter(env, opts = {}) {
     return env === 'mock' ? makeMockInterpreter(opts.fixtures ?? {}) : makeProductionInterpreter(opts);
 }
-
-
-//# sourceURL=ts/capabilities/effect.ts