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

package/dist/capabilities/model-override.js

@@ -0,0 +1,38 @@
+/**
+ * LLM_MODEL 会话面覆盖(issue #77)。
+ *
+ * dsh settings 分层:schema 默认 < composition 配置(cordis patch)< 用户层
+ *(~/.dsh/settings.yaml)。bin/gotry-inner.js 已把 LLM_MODEL 注入 composition
+ * 层(agent-default-model 默认模型 + llm-deepseek 目录),但用户在 dsh web UI
+ * 选过模型时,用户层压过 composition 层——单靠 patch,.env 承诺仍落空。
+ *
+ * 这里在 agent/request 瀑布(dsh-agent-loop 每次发起 LLM 请求前解析
+ * provider/model 的闸口,dsh-agent installModelSelection 也在此处施加选择)挂
+ * 监听,post-next 覆盖 provider/model:本插件随 cordis patch 在根组装载,先于
+ * 任何 agent 创建;瀑布按注册序嵌套(先注册 = 最外层,post-next 最后生效),
+ * 因此显式 .env 意图压过一切持久层选择。内存态零持久化,进程退即散,不改写
+ * 用户 ~/.dsh 设置。
+ *
+ * GOTRY_LLM_MODEL 未设置时不挂监听:默认路径(组合配置或用户 web 设置)面不变。
+ *
+ * @module gotry/capabilities/model-override
+ */
+export const MODEL_OVERRIDE_ENV = 'GOTRY_LLM_MODEL';
+/**
+ * 挂载模型覆盖;返回是否实际挂载(未设环境变量或 ctx 无事件总线时为 false)。
+ * provider 固定 deepseek-official:llm-deepseek 是 gotry 组合里唯一持有
+ * DEEPSEEK_API_KEY/DEEPSEEK_BASE_URL 映射凭证的 provider 路由。
+ */
+export function installModelOverride(ctx, env = process.env) {
+    const model = env[MODEL_OVERRIDE_ENV];
+    if (!model || typeof ctx.on !== 'function')
+        return false;
+    ctx.on('agent/request', async (_payload, next) => {
+        const resolved = await next();
+        // 与 installModelSelection 同语义:选中项无 effort 时清掉继承值,回落
+        // provider 默认推理档——不把上一个模型的 effort 错配到被覆盖的模型上
+        const { reasoningEffort: _inherited, ...rest } = resolved;
+        return { ...rest, provider: 'deepseek-official', model };
+    });
+    return true;
+}

package/dist/capabilities/opensky.js

@@ -1,33 +1,46 @@
+/**
+ * OpenSky 实时观测桥(免费匿名,~400 credits/天,~4 req/s burst):
+ * 查某 callsign 的飞机是否在 ADS-B 网络的当前观测里——航线层的实时印证。
+ *
+ * 契约(与 weather.ts / hbcli.ts 同构):
+ *   - 永不抛错:网络失败/超时/解析失败一律降级返回;
+ *   - 三值语义:命中=强肯定;查空≠证伪(ADS-B 覆盖有限,降权不排除);服务不可用=无结论;
+ *   - 证据链:成功 [实时API:opensky@ts];失败 [实时API:opensky@error@ts]。
+ *
+ * 接口面(2026-08 实际可达,匿名路径):
+ *   GET /api/states/all  — 当前全球 ADS-B 状态,~10000 架
+ *   GET /api/states/all?icao24=<hex>  — 单飞机
+ *   /api/flights/airport 历史查 = 需鉴权(匿名 403)
+ *
+ * 数据意义:与 OpenFlights 骨架(通航性)+ 静态班次包(班期时刻) 三值互补——
+ *   OpenFlights = 历史上是否通航过(offline)
+ *   flights_2026.json = 调研估算的班次时刻
+ *   OpenSky = 该 callsign 的飞机「现在」是否在观测网络里(实时刻正飞)
+ *
+ * v0.0.1-rc.3 +: 之前是 scripts/opensky-check.ts 一次性 CLI(M2 时设计为 7 天窗
+ * 历史校验,但匿名路径实际不可达),现升级为能力层封装 + dsh 插件工具。
+ */
 const BASE = 'https://opensky-network.org/api';
 async function fetchOpenSky(url, timeoutMs) {
     const ctrl = new AbortController();
-    const timer = setTimeout(()=>ctrl.abort(), timeoutMs);
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
     try {
         const res = await fetch(url, {
             signal: ctrl.signal,
-            headers: {
-                Accept: 'application/json',
-                'User-Agent': 'gotry/0.0.1-rc.3 (+https://github.com/Danceiny/gotry)'
-            }
+            headers: { Accept: 'application/json', 'User-Agent': 'gotry/0.0.1-rc.3 (+https://github.com/Danceiny/gotry)' },
         });
-        if (!res.ok) return {
-            ok: false,
-            error: `opensky HTTP ${res.status}${res.status === 429 ? ' (rate limited, 400 credits/day anonymous)' : ''}`
-        };
-        return {
-            ok: true,
-            data: await res.json()
-        };
-    } catch (e) {
-        return {
-            ok: false,
-            error: e.message.slice(0, 200)
-        };
-    } finally{
+        if (!res.ok)
+            return { ok: false, error: `opensky HTTP ${res.status}${res.status === 429 ? ' (rate limited, 400 credits/day anonymous)' : ''}` };
+        return { ok: true, data: await res.json() };
+    }
+    catch (e) {
+        return { ok: false, error: e.message.slice(0, 200) };
+    }
+    finally {
         clearTimeout(timer);
     }
 }
-const upper = (s)=>s.trim().toUpperCase();
+const upper = (s) => s.trim().toUpperCase();
 export async function verifyFlight(query) {
     const started = Date.now();
     const ts = new Date().toISOString();
@@ -38,37 +51,35 @@ export async function verifyFlight(query) {
     if (!r.ok) {
         return {
             verdict: 'unavailable',
-            callsign: cs,
-            airport,
-            sampleSize: 0,
-            hits: [],
+            callsign: cs, airport,
+            sampleSize: 0, hits: [],
             evidence: `[实时API:opensky@error@${ts}] ${r.error}`,
             via: 'opensky-error',
-            latencyMs,
-            error: r.error
+            latencyMs, error: r.error,
         };
     }
+    // /api/states/all → { time, states: Array<17 元素数组> }
+    // [0 icao24, 1 callsign, 2 origin_country, 3 time_position, 4 last_contact,
+    //  5 lon, 6 lat, 7 baro_altitude, 8 on_ground, ...]
     const rawStates = (r.data ?? {}).states ?? [];
-    const observed = rawStates.filter((row)=>(row[1] ?? '').trim().toUpperCase().includes(cs)).map((row)=>({
-            icao24: String(row[0] ?? ''),
-            callsign: (row[1] ?? '').trim() || null,
-            lastSeen: Number(row[4] ?? 0),
-            firstSeen: Number(row[4] ?? 0),
-            estArrivalAirport: airport
-        }));
+    const observed = rawStates
+        .filter(row => (row[1] ?? '').trim().toUpperCase().includes(cs))
+        .map(row => ({
+        icao24: String(row[0] ?? ''),
+        callsign: (row[1] ?? '').trim() || null,
+        lastSeen: Number(row[4] ?? 0),
+        firstSeen: Number(row[4] ?? 0),
+        estArrivalAirport: airport,
+    }));
     const verdict = observed.length > 0 ? 'observed' : 'not_observed';
-    const evidence = observed.length > 0 ? `[实时API:opensky@${ts}] ✅ 全球 ADS-B 当前观测命中 ${cs} (${observed.length} 架)` : `[实时API:opensky@${ts}] ○ 当前 ADS-B 全球观测列表未见 ${cs}(ADS-B 覆盖有限,不作否定结论)`;
+    const evidence = observed.length > 0
+        ? `[实时API:opensky@${ts}] ✅ 全球 ADS-B 当前观测命中 ${cs} (${observed.length} 架)`
+        : `[实时API:opensky@${ts}] ○ 当前 ADS-B 全球观测列表未见 ${cs}(ADS-B 覆盖有限,不作否定结论)`;
     return {
-        verdict,
-        callsign: cs,
-        airport,
+        verdict, callsign: cs, airport,
         sampleSize: rawStates.length,
-        hits: observed,
-        evidence,
+        hits: observed, evidence,
         via: 'opensky',
-        latencyMs
+        latencyMs,
     };
 }
-
-
-//# sourceURL=/Users/bytedance/work/gotry/ts/capabilities/opensky.ts

package/dist/capabilities/resilience.js

@@ -0,0 +1,191 @@
+/**
+ * 外部依赖韧性原语(issue #16 采纳,ADR-18):effect_interpreter.v1 解译器层的横切面。
+ *
+ * 对外通道的三类故障形态在此归一一处,能力层 handler(永不抛错契约)零改写:
+ *   - 指数退避重试 withRetry:只对「瞬时类失败」按策略重试,不改变单次失败语义;
+ *   - 断路器 CircuitBreaker:closed→open→half-open,连续失败达阈值即熔断,
+ *     冷却后放行单探测——保护配额与上游,拒绝也是显式结构化观察(不抛错);
+ *
+ * 策略边界(issue #16 三个解译器主张在本仓的保守落法,详见 docs/design/effect-interpreter.md):
+ *   - 重试只属于被判定「值得重试」的瞬时失败;风控/挑战/限流类上游明确说「不」的
+ *     失败(如 FlyAI Sentinel)永不重试——重试是放大器,不是修复器;
+ *   - 断路器状态是进程内瞬态(同 session-search 节律闸的先例),重启即重置;
+ *     不把瞬态熔断写盘成持久资产。
+ */
+/** 第 failedAttempt 次失败后的等待时长(纯函数,单测锁定 500→1000→2000 封顶链) */
+export function backoffDelayMs(policy, failedAttempt) {
+    const raw = policy.baseDelayMs * 2 ** (Math.max(1, failedAttempt) - 1);
+    return Math.min(raw, policy.maxDelayMs);
+}
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * 带指数退避的受控重试:handler 本身永不抛错(能力层契约),这里兼容抛错的
+ * 「裸调用方」——异常按 isRetryable(result=null, error) 判定后并入同一计数。
+ * 重试只针对瞬时失败;上限到点即返回最后结果,永不向上抛。
+ */
+export async function withRetry(fn, policy, onBackoff) {
+    const sleep = policy.sleep ?? defaultSleep;
+    const maxAttempts = Math.max(1, policy.maxAttempts);
+    let attempts = 0;
+    let backoffMs = 0;
+    const abortableSleep = (ms) => {
+        const signal = policy.signal;
+        if (signal?.aborted)
+            return Promise.resolve('aborted');
+        // The injected sleep is part of the retry contract. Keep its rejection
+        // visible to callers, while making an abort win the race and consuming a
+        // later rejection so cancellation cannot create an unhandled rejection.
+        if (!signal)
+            return sleep(ms).then(() => 'slept');
+        return new Promise((resolve, reject) => {
+            let settled = false;
+            let timer;
+            const cleanup = () => signal.removeEventListener('abort', onAbort);
+            const finish = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                if (timer !== undefined)
+                    clearTimeout(timer);
+                cleanup();
+                resolve(outcome);
+            };
+            const onAbort = () => finish('aborted');
+            const onSleepResolved = () => finish('slept');
+            const onSleepRejected = (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                reject(error);
+            };
+            signal.addEventListener('abort', onAbort, { once: true });
+            if (policy.sleep) {
+                void Promise.resolve().then(() => policy.sleep(ms)).then(onSleepResolved, onSleepRejected);
+            }
+            else {
+                timer = setTimeout(onSleepResolved, ms);
+            }
+        });
+    };
+    for (;;) {
+        if (policy.signal?.aborted) {
+            return { result: null, error: null, attempts, backoffMs, aborted: true };
+        }
+        attempts += 1;
+        let result = null;
+        let error = null;
+        try {
+            result = await fn();
+        }
+        catch (e) {
+            error = e;
+        }
+        if (policy.signal?.aborted) {
+            return { result: null, error, attempts, backoffMs, aborted: true };
+        }
+        const retryable = policy.isRetryable?.(result, error)
+            ?? (error != null || result?.ok === false);
+        if (attempts < maxAttempts && retryable) {
+            const delay = backoffDelayMs(policy, attempts);
+            onBackoff?.(attempts, delay);
+            backoffMs += delay;
+            if (await abortableSleep(delay) === 'aborted') {
+                return { result: null, error, attempts, backoffMs, aborted: true };
+            }
+            continue;
+        }
+        return { result, error, attempts, backoffMs, aborted: false };
+    }
+}
+/**
+ * 断路器(每效应一个实例):
+ *   closed    常态放行;连续失败达 failureThreshold → open;
+ *   open      拒绝(new attempts=0,.fail-fast 保护上游/配额);冷却满 openMs → half-open;
+ *   half-open 仅放行单个探测:onSuccess → closed 清零;onFailure → 重新 open(冷却重启)。
+ * 「失败」按效应的 isFailure 语义计数(一次调用一次计数,重试耗尽才计,非每 attempt)。
+ */
+export class CircuitBreaker {
+    o;
+    consecutiveFailures = 0;
+    openedAt = 0;
+    generation = 0;
+    nextTokenId = 0;
+    probeToken = null;
+    constructor(o) {
+        this.o = o;
+    }
+    threshold() {
+        return Math.max(1, this.o.failureThreshold);
+    }
+    now() {
+        return (this.o.now ?? Date.now)();
+    }
+    state() {
+        if (this.openedAt > 0 && this.now() - this.openedAt >= this.o.openMs)
+            return 'half-open';
+        if (this.openedAt > 0)
+            return 'open';
+        return 'closed';
+    }
+    /** 发起一次调用前问闸:open 回 {allowed:false}(调用方须返回显式降级观察,不重试) */
+    canAttempt() {
+        const s = this.state();
+        if (s === 'closed')
+            return { allowed: true, state: s, token: this.makeToken(false) };
+        if (s === 'open')
+            return { allowed: false, state: s };
+        // half-open:单探测语义——已有探测在途拒其余并发
+        if (this.probeToken)
+            return { allowed: false, state: s };
+        this.generation += 1;
+        const token = this.makeToken(true);
+        this.probeToken = token;
+        return { allowed: true, state: s, token };
+    }
+    /**
+     * half-open 探测被取消:仅令牌持有者释放所有权,不把 probe 永久卡死,
+     * 也不让旧 closed 调用或旧 generation 释放新探测。
+     */
+    releaseProbe(token) {
+        if (token?.probe !== true || this.probeToken !== token || this.state() !== 'half-open')
+            return;
+        this.probeToken = null;
+        this.generation += 1;
+    }
+    /** 一次解译调用成功(非 isFailure)——清零;half-open 探测成功即回 closed */
+    onSuccess(token) {
+        if (!this.owns(token))
+            return;
+        this.consecutiveFailures = 0;
+        this.openedAt = 0;
+        if (token?.probe === true || (!token && this.probeToken !== null)) {
+            this.probeToken = null;
+            this.generation += 1;
+        }
+    }
+    /** 一次解译调用失败(含重试耗尽)——半开探测失败 = 重新开闸 */
+    onFailure(token) {
+        if (!this.owns(token))
+            return;
+        if (token?.probe === true || (!token && this.probeToken !== null))
+            this.probeToken = null;
+        this.consecutiveFailures += 1;
+        if (this.openedAt > 0 || this.consecutiveFailures >= this.threshold()) {
+            this.openedAt = this.now();
+            this.generation += 1;
+        }
+    }
+    makeToken(probe) {
+        return Object.freeze({ generation: this.generation, probe, id: ++this.nextTokenId });
+    }
+    owns(token) {
+        // Keep the direct CircuitBreaker API backwards-compatible for callers
+        // that settle the currently active call without retaining its token.
+        if (!token)
+            return true;
+        if (token.probe)
+            return this.probeToken === token && this.state() === 'half-open';
+        return token.generation === this.generation && this.probeToken === null;
+    }
+}

package/dist/capabilities/session/action-cache.js

@@ -1,23 +1,28 @@
+/**
+ * action-cache 本地自愈层(RFC docs/rfc/user-session-data-rfc.md §3.2 / §2.3;Stagehand 云端缓存的本地化):
+ *
+ * 目的:会话检索的查询模式高度重复(同站点同类型搜索),首跑用 LLM/规则定位,后续走
+ * 缓存的确定性载荷零成本重放;站点改版 → DOM 指纹失配 → miss → 重新定位并回写。
+ *
+ * 设计原则(Stagehand「错误的缓存点击比慢更糟」的被动失效):
+ *   - key = site + action + 参数模板(%from%/%to%/%date% 变量化,同型查询共享条目);
+ *   - 每条目绑 domFingerprint(快照/接口形状的 sha256 指纹);lookup 时现场指纹与条目不符 = miss(即使 key 命中);
+ *   - miss 即回写(记录新定位),过期(默认 48h)与容量(每 site 默认 50 条,LRU)被动淘汰;
+ *   - 纯函数 + JSON 文件持久化(隔离 stateRoot;损坏文件按空缓存处理,永不抛错)。
+ *
+ * P2 切片:模块+确定性测试先行;消费方(P2 美团适配器/a11y 兜底)下一切片接线。
+ */
 import { createHash } from 'node:crypto';
-import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync, existsSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+/** 把具体查询参数变量化为模板 key:日期→%date%,from/to 语义序在前,其余参数按字典序尾随 */
 export function templateKey(site, action, params) {
-    const val = (k)=>k === 'date' ? '%date%' : (params[k] ?? '').trim();
-    const head = [
-        'from',
-        'to',
-        'date'
-    ].filter((k)=>k in params).map(val);
-    const tail = Object.keys(params).filter((k)=>![
-            'from',
-            'to',
-            'date'
-        ].includes(k)).sort().map(val);
-    return `${site}:${action}:${[
-        ...head,
-        ...tail
-    ].join('|')}`;
+    const val = (k) => (k === 'date' ? '%date%' : (params[k] ?? '').trim());
+    const head = ['from', 'to', 'date'].filter((k) => k in params).map(val);
+    const tail = Object.keys(params).filter((k) => !['from', 'to', 'date'].includes(k)).sort().map(val);
+    return `${site}:${action}:${[...head, ...tail].join('|')}`;
 }
+/** 指纹:快照/接口形状文本 → sha256 前 16 位(微改版即失配——宁可 miss 不可错点) */
 export function fingerprint(shapeText) {
     return createHash('sha256').update(shapeText).digest('hex').slice(0, 16);
 }
@@ -28,76 +33,79 @@ export class ActionCache {
     ttlMs;
     maxPerSite;
     now;
-    constructor(filePath, opts = {}){
+    constructor(filePath, opts = {}) {
         this.filePath = filePath;
         this.ttlMs = opts.ttlMs ?? 48 * 3600_000;
         this.maxPerSite = opts.maxEntriesPerSite ?? 50;
-        this.now = opts.now ?? (()=>new Date());
+        this.now = opts.now ?? (() => new Date());
     }
     load() {
-        if (this.loaded) return;
+        if (this.loaded)
+            return;
         this.loaded = true;
         try {
             if (existsSync(this.filePath)) {
                 const raw = JSON.parse(readFileSync(this.filePath, 'utf8'));
-                for (const e of raw){
-                    if (e?.key && e.domFingerprint && e.locator) this.entries.set(e.key, e);
+                for (const e of raw) {
+                    if (e?.key && e.domFingerprint && e.locator)
+                        this.entries.set(e.key, e);
                 }
             }
-        } catch  {}
+        }
+        catch { /* 损坏文件按空缓存处理 */ }
     }
     persist() {
         try {
-            mkdirSync(dirname(this.filePath), {
-                recursive: true
-            });
+            mkdirSync(dirname(this.filePath), { recursive: true });
             const tmp = this.filePath + '.tmp';
-            writeFileSync(tmp, JSON.stringify([
-                ...this.entries.values()
-            ], null, 0), 'utf8');
+            writeFileSync(tmp, JSON.stringify([...this.entries.values()], null, 0), 'utf8');
             writeFileSync(this.filePath, readFileSync(tmp, 'utf8'), 'utf8');
             try {
                 require('node:fs').rmSync(tmp);
-            } catch  {}
-        } catch  {}
+            }
+            catch { /* best effort */ }
+        }
+        catch { /* 持久化失败不阻塞内存路径 */ }
     }
+    /** 站点前缀条目数(LRU 淘汰用) */
     siteEntries(site) {
-        return [
-            ...this.entries.values()
-        ].filter((e)=>e.key.startsWith(site + ':'));
+        return [...this.entries.values()].filter((e) => e.key.startsWith(site + ':'));
     }
+    /** 命中三条件:key 存在 + 未过期 + 指纹一致;命中计 hits 并惰性落盘 */
     lookup(key, domFingerprint, site) {
         this.load();
         const e = this.entries.get(key);
-        if (!e) return null;
+        if (!e)
+            return null;
         if (this.now().getTime() - Date.parse(e.lastHitAt || e.createdAt) > this.ttlMs) {
             this.entries.delete(key);
             this.persist();
             return null;
         }
-        if (e.domFingerprint !== domFingerprint) return null;
+        if (e.domFingerprint !== domFingerprint)
+            return null; // 改版:被动失效,等 record 回写
         e.hits += 1;
         e.lastHitAt = this.now().toISOString();
         this.persist();
         void site;
         return e;
     }
+    /** miss 后回写(重新定位的产物);同 key 覆盖;超容 LRU 淘汰最旧 */
     record(key, domFingerprint, locator, site) {
         this.load();
         const ts = this.now().toISOString();
         const prev = this.entries.get(key);
         this.entries.set(key, {
-            key,
-            domFingerprint,
-            locator,
+            key, domFingerprint, locator,
             createdAt: prev?.createdAt ?? ts,
             lastHitAt: ts,
-            hits: prev?.hits ?? 0
+            hits: prev?.hits ?? 0,
         });
         const siteList = this.siteEntries(site);
         if (siteList.length > this.maxPerSite) {
-            const victim = siteList.sort((a, b)=>Date.parse(a.lastHitAt) - Date.parse(b.lastHitAt))[0];
-            if (victim) this.entries.delete(victim.key);
+            const victim = siteList.sort((a, b) => Date.parse(a.lastHitAt) - Date.parse(b.lastHitAt))[0];
+            if (victim)
+                this.entries.delete(victim.key);
         }
         this.persist();
         return this.entries.get(key);
@@ -112,9 +120,7 @@ export class ActionCache {
         return site ? this.siteEntries(site).length : this.entries.size;
     }
 }
+/** 便捷入口:隔离 stateRoot 下的缓存文件路径 */
 export function actionCachePath(stateRoot) {
     return join(stateRoot, 'session-action-cache.json');
 }
-
-
-//# sourceURL=/Users/bytedance/work/gotry/ts/capabilities/session/action-cache.ts