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

package/dist/capabilities/channel-health.js

@@ -0,0 +1,131 @@
+/**
+ * 通道健康面(channel health)——issue #106/#107/#108 编排设计
+ * (docs/design/tool-orchestration-design.md §2.2)的会话瞬态态 + 持久事件面。
+ *
+ * 两个粒度,均从既有 verdict 流派生,不新增运行时:
+ *  - 会话瞬态面:进程内 Map。检索通道 verdict≠hit 时记状态
+ *    (down=本会话别再试 / cooldown=节律闸冷却中),后续同意图工具结果的
+ *    routing 建议(channel-registry.routingAdvice)据此排除不可用通道;
+ *    成功调用(hit)自动清除——补装 key/装完扩展后不被陈旧状态锁死。
+ *    与断路器同先例(ADR-18):进程内瞬态,不是持久资产。
+ *  - 持久事件面:down/cooldown 事件 append-only 落
+ *    <stateRoot>/gotry-state/channel-health.jsonl,供 doctor(CLI 独立进程,
+ *    看不到进程内 Map)显示「最近一次达限/不可用时间」。只记状态变化,
+ *    不记成功(零写放大);落盘失败不阻塞检索主路径(事实侧车同纪律)。
+ *
+ * verdict → 状态映射的唯一入口是 noteChannelVerdict:
+ *   needs-setup → down(quota-or-setup)   challenged → down(challenged)
+ *   needs-login / needs-extension → down(同因,会话内改道;hit 即清除)
+ *   cooldown → cooldown(默认 30s,会话节律闸同款)
+ *   hit → 清除该通道全部状态
+ *   其余 verdict(miss/error 等)不改变通道状态——那是业务结果,不是通道健康。
+ *
+ * @module capabilities/channel-health
+ */
+/** 会话瞬态面(进程内;与断路器状态同生命周期先例) */
+const session = new Map();
+/** 默认 cooldown = 会话节律闸同款 30s */
+export const DEFAULT_COOLDOWN_MS = 30_000;
+export function markChannelDown(channel, reason, now = Date.now()) {
+    session.set(channel, { state: 'down', reason, since: now });
+    return { channel, state: 'down', reason, at: new Date(now).toISOString() };
+}
+export function markChannelCooldown(channel, cooldownMs = DEFAULT_COOLDOWN_MS, now = Date.now()) {
+    session.set(channel, { state: 'cooldown', until: now + cooldownMs, since: now });
+    return { channel, state: 'cooldown', at: new Date(now).toISOString() };
+}
+/** 成功即清除(恢复信号:下一次成功调用自动解锁,不要求显式复位) */
+export function clearChannel(channel) {
+    session.delete(channel);
+}
+/** 读通道状态;cooldown 过期惰性清除。无状态返回 undefined。 */
+export function channelState(channel, now = Date.now()) {
+    const e = session.get(channel);
+    if (!e)
+        return undefined;
+    if (e.state === 'cooldown' && (e.until ?? 0) <= now) {
+        session.delete(channel);
+        return undefined;
+    }
+    return { state: e.state, reason: e.reason };
+}
+/** 测试隔离:清空全部会话态(生产路径不调) */
+export function resetChannelHealth() {
+    session.clear();
+}
+/**
+ * verdict → 通道状态变化的唯一映射(工具层在拿到渠道结果后调用)。
+ * 返回落盘事件(down/cooldown 才有;hit 清除与其余 verdict 返回 undefined)。
+ */
+export function noteChannelVerdict(channel, verdict, opts = {}) {
+    const now = opts.now ?? Date.now();
+    switch (verdict) {
+        case 'hit':
+        case 'found':
+            clearChannel(channel);
+            return undefined;
+        case 'needs-setup':
+        case 'needs-login':
+        case 'needs-extension':
+        case 'needs-attach':
+        case 'challenged':
+            return markChannelDown(channel, verdict, now);
+        case 'cooldown':
+            return markChannelCooldown(channel, opts.cooldownMs ?? DEFAULT_COOLDOWN_MS, now);
+        default:
+            return undefined;
+    }
+}
+/** 持久事件面:append-only JSONL(<stateRoot>/gotry-state/channel-health.jsonl)。永不抛错。 */
+export async function recordChannelEvent(stateRoot, event) {
+    try {
+        const { mkdir, appendFile } = await import('node:fs/promises');
+        const dir = `${stateRoot.replace(/\/+$/, '')}/gotry-state`;
+        await mkdir(dir, { recursive: true });
+        await appendFile(`${dir}/channel-health.jsonl`, `${JSON.stringify(event)}\n`, 'utf-8');
+    }
+    catch { /* 证据侧车永不阻塞主路径 */ }
+}
+/**
+ * 读最近事件(每通道取最新一条)——doctor(CLI 独立进程)的持久面输入。
+ * 容忍坏行/空文件/缺文件;limitDays 过滤过旧事件(默认 30 天)。
+ * latest-wins:'ok' 恢复事件可超越同通道更早的 down/cooldown(外部事件接缝
+ * 第 1 段);消费方以 `state !== 'down'` 判当前健康,旧判定(`=== 'down'`)
+ * 不受影响。
+ * requireValidTimestamp(opt-in,#436 路由消费方):缺失/不可解析/未来时间戳的行
+ * **在 latest-wins 覆盖之前**丢弃——否则一条坏时间戳的新行会顶掉同通道更早的
+ * 有效 down,把通道错误地判回可用。默认 false,doctor/metrics/探针既有口径不变
+ * (它们只消费状态与历史频率,不要求时间戳可信);保留期仍是同一个 limitDays。
+ */
+export async function readLatestChannelEvents(stateRoot, opts = {}) {
+    const latest = new Map();
+    try {
+        const { readFile } = await import('node:fs/promises');
+        const raw = await readFile(`${stateRoot.replace(/\/+$/, '')}/gotry-state/channel-health.jsonl`, 'utf-8');
+        const nowMs = opts.now ?? Date.now();
+        const cutoff = nowMs - (opts.limitDays ?? 30) * 86_400_000;
+        for (const line of raw.split('\n')) {
+            const t = line.trim();
+            if (!t)
+                continue;
+            try {
+                const ev = JSON.parse(t);
+                if (!ev || typeof ev.channel !== 'string' || typeof ev.state !== 'string')
+                    continue;
+                if (!['down', 'cooldown', 'ok'].includes(ev.state))
+                    continue;
+                const atMs = Date.parse(ev.at ?? '');
+                if (opts.requireValidTimestamp) {
+                    if (!Number.isFinite(atMs) || atMs > nowMs || atMs < cutoff)
+                        continue;
+                }
+                else if (Number.isFinite(atMs) && atMs < cutoff)
+                    continue;
+                latest.set(ev.channel, ev);
+            }
+            catch { /* 坏行跳过 */ }
+        }
+    }
+    catch { /* 无文件=无事件 */ }
+    return latest;
+}

package/dist/capabilities/channel-registry.js

@@ -0,0 +1,256 @@
+/**
+ * 通道注册表(channel registry)——检索通道的**单一数据来源**
+ * (docs/design/tool-orchestration-design.md §2.1,issue #106/#107/#108 编排设计)。
+ *
+ * 每行描述一条通道:覆盖意图 / 配额类 / 证据级 / 工具名 / setup 成本。
+ * persona 路由卡(renderRoutingCard → {{channel_routing_card}})、工具结果内的
+ * routing 建议字段(routingAdvice)、doctor 通道行,全部由本表**生成**——
+ * 加一个通道 = 这里加一行 + handler 一个 + 测试断言,prose 站点零手改。
+ *
+ * 编排语义(§3.3,founder D-8 拍板采纳):工具面保持平铺(ADR-18/persona (19)
+ * 判定不动),本模块只产出「健康态驱动的动态建议」——价值序 =
+ * lexicographic(可用性, 可靠性=证据级, 效率=成本/时延)。通道间在给定健康态
+ * 下相互独立,最优子结构成立,DP 退化为有序建议表;**建议不是派发**,
+ * 解译器不做隐藏改道(调用可审计性)。
+ *
+ * 配额分类(§3.2,D-7 拍板采纳):user-session=用户本人账号;user-key=用户自备
+ * 凭证;anonymous-trial=产品垫付导流层(达限即改道+升级指引);free-public=社区
+ * 公平使用;static=无配额估算(内部自动降级面,不进模型可选路由)。
+ *
+ * @module capabilities/channel-registry
+ */
+import { channelState } from './channel-health.js';
+export const CHANNELS = [
+    {
+        id: 'flyai',
+        label: '飞猪官方 API',
+        tool: 'gotry_flyai_search',
+        intents: ['search-flight', 'search-train', 'search-hotel'],
+        quotaClass: 'anonymous-trial',
+        evidenceTag: '[实时API:flyai@ts]',
+        tier: 'realtime-api',
+        efficiencyRank: 0,
+        setup: '可匿名试用（共享额度）；本机运行 gotry setup flyai 配置并验证 key；模型仅可用 gotry_flyai_setup 查看或检查状态；未配置 key 时该通道易达 Trial limit reached(达限本会话内不可用,改走 gotry_session_search 账号会话)',
+    },
+    {
+        id: 'hbcli-hotel',
+        label: 'hbcli 酒店实时源',
+        tool: 'gotry_hotel_search',
+        intents: ['search-hotel'],
+        quotaClass: 'user-key',
+        evidenceTag: '[实时API:hbcli@ts]',
+        tier: 'realtime-api',
+        efficiencyRank: 1,
+        setup: 'hbcli 凭证(demo 沙箱一键);未装自动降静态包',
+    },
+    {
+        id: 'session:ctrip-flight',
+        label: '携程·用户登录态',
+        tool: 'gotry_session_search',
+        intents: ['search-flight'],
+        quotaClass: 'user-session',
+        evidenceTag: '[会话:ctrip-flight@ts]',
+        tier: 'session',
+        efficiencyRank: 2,
+        setup: '一次性装 Session Bridge 扩展 + 授权卡 + (如需)官网登录',
+        hint: 'kind=flight',
+    },
+    {
+        id: 'session:ctrip-hotel',
+        label: '携程·用户登录态',
+        tool: 'gotry_session_search',
+        intents: ['search-hotel'],
+        quotaClass: 'user-session',
+        evidenceTag: '[会话:ctrip-hotel@ts]',
+        tier: 'session',
+        efficiencyRank: 2,
+        setup: '一次性装 Session Bridge 扩展 + 授权卡 + (如需)官网登录',
+        hint: 'kind=hotel',
+    },
+    {
+        id: 'session:dida-portal',
+        label: 'Dida 供应商门户·用户登录态',
+        tool: 'gotry_session_search',
+        intents: ['search-hotel'],
+        quotaClass: 'user-session',
+        evidenceTag: '[会话:dida-portal@ts]',
+        tier: 'session',
+        efficiencyRank: 2,
+        setup: '一次性装 Session Bridge 扩展 + 授权卡 + hotel-be portal 自动登录跳板(dida 官网由人完成登录)',
+        hint: 'kind=dida',
+    },
+    {
+        id: 'session:12306-train',
+        label: '12306 公开查询面',
+        tool: 'gotry_session_search',
+        intents: ['search-train'],
+        quotaClass: 'user-session',
+        evidenceTag: '[会话:train-12306@ts]',
+        tier: 'session',
+        efficiencyRank: 2,
+        setup: '一次性装 Session Bridge 扩展(公开查询面,无需登录)',
+        hint: 'kind=train',
+    },
+    {
+        id: 'anything-geo',
+        label: '目的地/酒店候选(hotel-be)',
+        tool: 'gotry_anything_search',
+        intents: ['search-geo'],
+        quotaClass: 'user-key',
+        evidenceTag: '[实时API:hbcli-anything@ts]',
+        tier: 'realtime-api',
+        efficiencyRank: 1,
+        setup: 'hbcli 可达即可(随 hbcli 安装)',
+    },
+    {
+        id: 'open-meteo',
+        label: '天气(open-meteo)',
+        tool: 'gotry_weather_check',
+        intents: ['weather'],
+        quotaClass: 'free-public',
+        evidenceTag: '[实时API:open-meteo@ts]',
+        tier: 'realtime-api',
+        efficiencyRank: 0,
+    },
+    {
+        id: 'opensky',
+        label: '航班实时印证(OpenSky)',
+        tool: 'gotry_flight_verify',
+        intents: ['verify-flight'],
+        quotaClass: 'free-public',
+        evidenceTag: '[实时API:opensky@ts]',
+        tier: 'realtime-api',
+        efficiencyRank: 0,
+    },
+    {
+        id: 'web-read',
+        label: '网页读取兜底(agent-reach)',
+        tool: 'gotry_web_search',
+        intents: ['read-web', 'search-flight', 'search-train', 'search-hotel'],
+        quotaClass: 'user-key',
+        evidenceTag: '[agent-reach:web.read@ts]',
+        tier: 'best-effort',
+        efficiencyRank: 3,
+        setup: 'gotry .venv 装 agent-reach(npx @danceiny/gotry doctor --fix)',
+    },
+    {
+        id: 'static-hotel',
+        label: '内置静态数据包',
+        tool: 'gotry_hotel_search',
+        intents: ['search-hotel'],
+        quotaClass: 'static',
+        evidenceTag: '[静态包:估算]',
+        tier: 'static',
+        efficiencyRank: 9,
+        routable: false,
+    },
+];
+const TIER_RANK = {
+    'realtime-api': 0,
+    session: 1,
+    'best-effort': 2,
+    static: 3,
+};
+const TIER_WHY = {
+    'realtime-api': '官方结构化数据,证据链最强',
+    'session': '用户本人登录态的真实价/库存',
+    'best-effort': '非结构化兜底(读页汇总),证据弱于 API',
+    'static': '内置估算,仅覆盖内置场景',
+};
+export const INTENT_LABELS = {
+    'search-flight': '机票',
+    'search-train': '火车',
+    'search-hotel': '酒店',
+    'search-geo': '目的地候选',
+    'read-web': '网页/社媒',
+    'weather': '天气',
+    'verify-flight': '航班印证',
+};
+/** 意图 → 候选通道(证据级降序,同 tier 按效率升序)。纯函数。 */
+export function channelsForIntent(intent) {
+    return CHANNELS
+        .filter(c => c.routable !== false && c.intents.includes(intent))
+        .slice()
+        .sort((a, b) => TIER_RANK[a.tier] - TIER_RANK[b.tier] || a.efficiencyRank - b.efficiencyRank);
+}
+/**
+ * 持久健康面投影(#436):readLatestChannelEvents 的最新事件表 → 应排除的通道集合。
+ * 纯函数,IO 归调用方(工具结果边界)。与会话态同口径:只有 down 排除——
+ * cooldown 是节律闸不是不可用,'ok' 是恢复事件(latest-wins)自然放行。
+ * 无时间戳/时间戳不可解析/时间戳在未来的事件一律不排除:坏输入不能凭空压制通道;
+ * 过期事件由读方的既有保留期(limitDays 默认 30 天)负责,此处不另立窗口。
+ */
+export function persistedDownChannels(latest, now = Date.now()) {
+    const down = new Set();
+    for (const [channel, ev] of latest) {
+        if (ev?.state !== 'down')
+            continue;
+        const at = Date.parse(ev.at ?? '');
+        if (!Number.isFinite(at) || at > now)
+            continue;
+        down.add(channel);
+    }
+    return down;
+}
+/**
+ * 意图 × 健康态 → 有序改道建议(模型可见的 routing 字段形状)。
+ * 排除规则:发起通道本身;会话健康面标记为 down 的通道;调用方投影进来的
+ * 持久健康面 down 集合(跨进程生产者,#436)。
+ * cooldown 是瞬时节律,不算不可用(保留在表里,why 不变——模型自然
+ * 「稍候重试或其他」),down(配额尽/挑战/需登录/需扩展)才排除。
+ * 两个健康面只做并集:持久面缺席/恢复都不能解除会话态的 down。
+ */
+export function routingAdvice(intent, opts = {}) {
+    const alternatives = channelsForIntent(intent)
+        .filter(c => c.id !== opts.excludeChannel)
+        .filter(c => channelState(c.id, opts.now)?.state !== 'down')
+        .filter(c => !opts.persistedDownChannels?.has(c.id))
+        .slice(0, opts.limit ?? 3)
+        .map(c => ({
+        tool: c.tool,
+        channel: c.id,
+        label: c.label,
+        why: TIER_WHY[c.tier],
+        ...(c.setup ? { setup: c.setup } : {}),
+        ...(c.hint ? { hint: c.hint } : {}),
+    }));
+    return { intent, alternatives };
+}
+/**
+ * 工具描述首行生成(§3.3④,issue #113):某检索工具在注册表内服务的意图 →
+ * 「服务意图 × 当前通道顺位」卡,前置进工具描述——模型在选工具时(读描述)
+ * 与失败后(读 routing 字段)两个决策点拿到同一张表。顺位=证据级降序(与
+ * renderRoutingCard 同口径:通道状态变化不改变顺位表本身,只影响 routing
+ * 建议的可用性过滤)。注册表加行,描述首行自动一致,零手改。
+ * 非检索工具(不在表内)返回 '',描述保持原样。纯函数。
+ */
+export function toolRoutingHeadline(tool) {
+    const intents = new Set();
+    for (const c of CHANNELS) {
+        if (c.routable === false || c.tool !== tool)
+            continue;
+        for (const i of c.intents)
+            intents.add(i);
+    }
+    if (intents.size === 0)
+        return '';
+    const lines = [...intents].map(intent => `- ${INTENT_LABELS[intent]}: ${channelsForIntent(intent).map(c => `${c.label}(${c.tool}${c.hint ? ` ${c.hint}` : ''})`).join(' → ')}`);
+    return ['本工具服务的检索意图与通道顺位(证据级降序):', ...lines, 'verdict≠hit 时按结果内 routing 字段改道下一通道,勿盲试同通道。'].join('\n');
+}
+/**
+ * persona 路由卡({{channel_routing_card}}):每意图一行顺位 + 额度口径脚注。
+ * 确定性渲染(零 IO,时钟只进脚注);只列有 ≥2 条可选通道的意图——
+ * 单通道意图没有路由选择,列了只是 token 噪声。
+ */
+export function renderRoutingCard(now = new Date()) {
+    const multiChannel = Object.keys(INTENT_LABELS)
+        .map(intent => ({ intent, channels: channelsForIntent(intent) }))
+        .filter(x => x.channels.length >= 2);
+    const lines = multiChannel.map(({ intent, channels }) => `- ${INTENT_LABELS[intent]}: ${channels.map(c => `${c.label}(${c.tool}${c.hint ? ` ${c.hint}` : ''})`).join(' → ')}`);
+    return [
+        '检索通道顺位(官方API > 用户会话 > 网页兜底;某次检索 verdict≠hit 时,按该结果内 routing 字段改道下一通道,同通道本会话不盲试第二次):',
+        ...lines,
+        '额度口径:匿名试用=首次体验导流(达限即改道并提示配 key);正式 key(FLYAI_API_KEY/hbcli 凭证)与账号会话=正式用量;静态包=估算必标注。',
+        `卡生成于 ${now.toISOString()}(通道状态变化不改变顺位表本身,只影响 routing 建议的可用性过滤)。`,
+    ].join('\n');
+}