@danceiny/gotry 0.2.0-rc.30 → 0.2.0-rc.32

package/dist/scripts/session-tests.js

@@ -20,7 +20,9 @@ import { buildEntryUrl, parseBatchSearch, parseBatchSearchResult } from '../capa
 import { buildHotelEntryUrl, parseCtripHotelList, looksLikeHotelListBody } from '../capabilities/session/adapters/ctrip-hotel.js';
 import { buildTrainEntryUrl, hasRecognizedAvailableSeat, parseLeftTicketQuery, parseLeftTicketQueryResult, resolveTrainQueryTelecodes, STATION_TELECODES, validateTrainQueryResponseUrl } from '../capabilities/session/adapters/rail-12306.js';
 import { buildDidaEntryUrl, parseDidaRates, parseDidaSearchCache, looksLikeDidaRatesBody } from '../capabilities/session/adapters/dida-portal.js';
-import { sessionFlightSearch, sessionHotelSearch, sessionTrainSearch, sessionDidaSearch, trainStationUnresolvedHint, hotelCityUnresolvedHint, didaLoginHint, __resetRateLimiterForTest, __setTrainSessionTransportForTest, classifyTransportFailure } from '../capabilities/session-search.js';
+import { sessionFlightSearch, sessionFlightGuiSearch, sessionHotelSearch, sessionTrainSearch, sessionDidaSearch, trainStationUnresolvedHint, hotelCityUnresolvedHint, flightCityUnresolvedHint, didaLoginHint, __resetRateLimiterForTest, __setTrainSessionTransportForTest, classifyTransportFailure } from '../capabilities/session-search.js';
+import { planFlightGuiActions, assertGuiPlanSafe, runFlightGuiSearch, parseLowestPriceCalendar, __setGuiDriverForTest } from '../capabilities/session/gui-flight.js';
+import { planHotelGuiActions, assertHotelPlanSafe, runHotelGuiSearch, __setHotelDriverForTest } from '../capabilities/session/gui-hotel.js';
 import { flyaiSearch } from '../capabilities/flyai.js';
 import { createConsentGate } from '../capabilities/session-consent.js';
 import { sessionLogin, pollTicketNames, LOGIN_TARGETS } from '../capabilities/session-login.js';
@@ -145,6 +147,16 @@ assert(e1.ok === true && e1.url === 'https://flights.ctrip.com/online/list/onewa
 const e2 = buildEntryUrl('乌兰巴托', '丽江', '2026-10-01');
 assert(e2.ok === false && e2.unresolved?.[0] === '乌兰巴托', '词表外城市 unresolved 逐字保留(不猜)');
 assert(buildEntryUrl('上海', '丽江', '十月一号').ok === false, '非法日期拒绝');
+const internationalEntry = buildEntryUrl('迪拜', '香港', '2026-12-01', { fromCode: 'DXB', toCode: 'HKG' });
+assert(internationalEntry.ok && internationalEntry.url?.includes('oneway-dxb-hkg') === true, '显式供应商城市码不受内置表限制');
+assert(!buildEntryUrl('迪拜', '香港', '2026-12-01', { fromCode: '../dxb', toCode: 'HKG' }).ok, '显式城市码拒绝 URL 注入');
+// 实测校准抽查(2026-10-14 list 页实证:合法组合 200+title 航线名,非法组合 302)
+const e3 = buildEntryUrl('香港', '迪拜', '2026-12-06');
+assert(e3.ok === true && e3.url === 'https://flights.ctrip.com/online/list/oneway-hkg-dxb?depdate=2026-12-06', '香港/迪拜=实测校准入缓存表(hkg/dxb)', e3);
+const e4 = buildEntryUrl('乌兰巴托', '丽江', '2026-10-01', { fromCode: 'ubn' });
+assert(e4.ok === true && e4.url === 'https://flights.ctrip.com/online/list/oneway-ubn-ljg?depdate=2026-10-01', '显式三字码逃生口(形状合格即成行)', e4);
+assert(buildEntryUrl('乌兰巴托', '丽江', '2026-10-01', { fromCode: 'UBN!' }).ok === false, '显式码形状不合格不得进 URL');
+assert(flightCityUnresolvedHint(['乌兰巴托']).includes('fromCityCode'), '机票 unresolved 指引带显式码逃生口');
 // D. DOM 提交件过滤
 console.log('D. isSubmitText(DOM 提交件黑名单)');
 assert(isSubmitText('立即下单') && isSubmitText('去支付') && isSubmitText('提交订单'), '下单/支付/提交 命中');
@@ -153,9 +165,9 @@ assert(!isSubmitText('搜索') && !isSubmitText('筛选'), '搜索/筛选 不误
 console.log('E. 节律闸(≥30s 间隔)');
 __resetRateLimiterForTest();
 const r1 = await sessionFlightSearch({ from: '乌兰巴托', to: '丽江', date: '2026-10-01' });
-const r2 = await sessionFlightSearch({ from: '上海', to: '丽江', date: '2026-10-01' });
+const r2 = await sessionFlightSearch({ from: '另一个未知城市', to: '丽江', date: '2026-10-01' });
 assert(r1.verdict === 'error' && /unresolved/.test(r1.error ?? ''), '首次调用:词表外 → error(unresolved)');
-assert(r2.verdict === 'cooldown', '30s 内二次调用 → cooldown,不发起导航');
+assert(r2.verdict === 'error', '城市解析失败不占用库存检索节律额度，不误报 cooldown');
 __resetRateLimiterForTest();
 // F. transport 失败分类 + live FlyAI 官方通道
 console.log('F. transport verdict + flyaiSearch(live,飞猪官方,无 key;GOTRY_SESSION_LIVE=0 跳过)');
@@ -167,7 +179,10 @@ if (process.env.GOTRY_SESSION_LIVE === '0') {
     console.log('  SKIP - GOTRY_SESSION_LIVE=0(离线门禁不调用 FlyAI 外部实时端点)');
 }
 else {
-    fr = await flyaiSearch({ kind: 'flight', origin: '上海', destination: '丽江', depDate: '2026-10-01' });
+    // 滚动未来日期(硬编码日期跨日假红的教训:过去日期会被上游「出发日期非法」业务失败拒绝)
+    const roll = new Date(Date.now() + 30 * 24 * 3600 * 1000);
+    const rollingDepDate = `${roll.getFullYear()}-${String(roll.getMonth() + 1).padStart(2, '0')}-${String(roll.getDate()).padStart(2, '0')}`;
+    fr = await flyaiSearch({ kind: 'flight', origin: '上海', destination: '丽江', depDate: rollingDepDate });
     const sentinelBlocked = fr.verdict === 'error' && /sentinel|block|trial limit/i.test(fr.error ?? '');
     if (sentinelBlocked) {
         console.log('  WARN - 飞猪上游限流(Sentinel 2026-08-28 / trial-limit 429 2026-08-31 实测,配额未文档化)——降级合同验证通过,跳过 hit 断言');
@@ -540,8 +555,8 @@ console.log('K. 酒店适配器(buildHotelEntryUrl/走形解析/形状嗅探/城
     __resetRateLimiterForTest();
     const e1 = await sessionHotelSearch({ to: '不在码表的城市' });
     assert(e1.ok === false && e1.verdict === 'error' && /city=/.test(e1.error ?? ''), '未收录城市 → error + cityId 指引', e1);
-    const e2 = await sessionHotelSearch({ to: '上海' });
-    assert(e2.ok === false && e2.verdict === 'cooldown', '节律闸:同站点 30s 内第二调 → cooldown(不发起导航)', e2);
+    const e2 = await sessionHotelSearch({ to: '另一个未知酒店城市' });
+    assert(e2.ok === false && e2.verdict === 'error', '酒店城市解析失败不占用库存节律额度', e2);
 }
 // L. 火车会话面(2026-09-03 实装,12306 公开查询面)纯函数:entry URL/管道行解析/电报码指引/闸面
 console.log('L. 火车适配器(buildTrainEntryUrl/parseLeftTicketQuery/电报码指引/节律闸)');
@@ -854,6 +869,162 @@ console.log('M. Dida 门户(entry 守域 + 信封走形 + 闸面)');
     assert(q2.ok === false && q2.verdict === 'cooldown', '节律闸:30s 内二调 → cooldown', q2);
     assert(typeof didaLoginHint() === 'string' && /自动登录/.test(didaLoginHint()), '登录指引指向 hotel-be portal 跳板(账密永不经 gotry)');
 }
+// L. 携程机票 GUI 车道(2026-10-14):规划器/安全白名单/假 driver 全流程/readback 硬闸
+{
+    console.log('L. GUI 车道(规划器 + 安全闸 + 假 driver)');
+    const planOw = planFlightGuiActions({ from: '上海', to: '丽江', date: '2027-05-02' });
+    assert(planOw.some(a => a.t === 'clickTripTab' && a.trip === 'oneway') && !planOw.some(a => a.t === 'setDate' && a.which === 'back'), '单程规划:显式点单程 tab(页面默认往返态)/无回程日期');
+    const planRt = planFlightGuiActions({ from: '香港', to: '迪拜', date: '2026-12-06', backDate: '2026-12-13' });
+    assert(planRt.some(a => a.t === 'clickTripTab' && a.trip === 'roundtrip') && planRt.some(a => a.t === 'setDate' && a.which === 'back'), '往返规划:往返 tab + 回程日期(不知 URL 形状也能搜)');
+    const rb = planRt.find(a => a.t === 'readback');
+    assert(!!rb && rb.t === 'readback' && rb.expect.back === '2026-12-13', 'readback 期望含回程日期');
+    // 安全白名单:闭集外/提交件文本/非固定入口/坏日期/坏按键全拒
+    assert(!assertGuiPlanSafe([{ t: 'goto', url: 'https://evil.example.com/' }]).ok, '安全闸:非固定入口 URL 拒绝');
+    assert(!assertGuiPlanSafe([{ t: 'typeCity', which: 'from', text: '立即下单' }]).ok, '安全闸:城市位提交件文本拒绝(写面红线)');
+    assert(!assertGuiPlanSafe([{ t: 'setDate', which: 'dep', ymd: '十二月六号' }]).ok, '安全闸:非 YMD 日期拒绝');
+    assert(!assertGuiPlanSafe([{ t: 'press', key: 'Meta' }]).ok, '安全闸:按键白名单外拒绝');
+    assert(assertGuiPlanSafe(planRt).ok, '合法规划全过');
+    // 假 driver:表单内存模型 + 可编程回包
+    const FIXTURE = JSON.stringify({ data: { flightItineraryList: [{
+                    flightSegments: [{ airlineName: 'Spring Airlines', duration: 215, flightList: [{ flightNo: '9C6617', departureAirportName: '浦东', arrivalAirportName: '三义', departureDateTime: '2027-05-02 17:05:00', arrivalDateTime: '2027-05-02 20:40:00' }] }],
+                    priceList: [{ adultPrice: 1790 }],
+                }] } });
+    // live 实测形状(2026-10-14 GUI 捕获,382 条之一):顶层 priceList,/Date(ms+0800)/ 日期,price>0 才可售
+    const CAL_FIXTURE = JSON.stringify({ responseStatus: { Ack: 'Success' }, priceList: [
+            { departDate: '/Date(1791993600000+0800)/', price: 0 }, // 无价日(过滤)
+            { departDate: '/Date(1792080000000+0800)/', price: 880 }, // 2027-05-02? 由断言锚定实际换算
+            { departDate: '/Date(1792166400000+0800)/', price: 1020 },
+            { departDate: '/Date(1792252800000+0800)/', price: 760 },
+        ] });
+    const makeFakeDriver = (opts = {}) => {
+        const state = { clickedSearch: false, form: { from: '', to: '', dep: '', back: '' } };
+        const page = {
+            async goto() { },
+            async clickTripTab() { },
+            async typeCity(which, text) { state.form[which] = text; },
+            async pickSuggest(which, text) { state.form[which] = `${text}(SHA)`; /* 站点补全归一化形态 */ },
+            async setDate(which, ymd) { state.form[which === 'dep' ? 'dep' : 'back'] = ymd; },
+            async press() { },
+            async clickSearch() { state.clickedSearch = true; },
+            async visibleFormText() { return Object.values({ ...state.form, ...opts.formOverride }).concat(['上海', '丽江']).join(' | '); },
+            async cityFieldValues() { const f = { ...state.form, ...opts.formOverride }; return { from: f.from ?? '', to: f.to ?? '' }; },
+            async pageText() { return opts.challenge ? '请输入验证码 拖动滑块' : '机票预订'; },
+            async currentUrl() { return opts.listUrl ?? 'https://flights.ctrip.com/online/channel/domestic'; },
+            async waitForApiCapture() {
+                const itinerary = opts.apiBody === undefined
+                    ? { url: 'https://flights.ctrip.com/international/search/api/search/batchSearch', body: FIXTURE }
+                    : opts.apiBody ? { url: 'x', body: opts.apiBody } : null;
+                const calendar = opts.calendarBody ? { url: 'https://m.ctrip.com/restapi/soa2/15380/bjjson/FlightIntlAndInlandLowestPriceSearch', body: opts.calendarBody } : null;
+                return (itinerary || calendar) ? { ...(itinerary ? { itinerary } : {}), ...(calendar ? { calendar } : {}) } : null;
+            },
+        };
+        return { driver: { open: async () => page, close: async () => { } }, state };
+    };
+    __setGuiDriverForTest(() => makeFakeDriver().driver);
+    const g1 = await runFlightGuiSearch({ from: '上海', to: '丽江', date: '2027-05-02' });
+    assert(g1.ok === true && g1.verdict === 'hit' && g1.anonymous === true && (g1.options?.length ?? 0) === 1, '假 driver 全流程 → hit(anonymous 标注)', g1);
+    assert(/\[会话:ctrip-flight-gui@/.test(g1.evidence) && /transport=gui/.test(g1.evidence), 'GUI 证据链 [会话:ctrip-flight-gui@ts]');
+    assert(g1.options?.[0]?.flightNo === '9C6617' && g1.options?.[0]?.price === 1790, '既有 batchSearch 解析器复用(结构化选项)');
+    // #661/#662:匿名绑定面——无行程回包、仅有低价日历 → hit + 日历数据 + listUrl 透传
+    const calDriver = makeFakeDriver({ apiBody: null, calendarBody: CAL_FIXTURE, listUrl: 'https://flights.ctrip.com/online/list/roundtrip-sha-ljg?depdate=2027-05-02&retdate=2027-05-09' });
+    __setGuiDriverForTest(() => calDriver.driver);
+    const g5 = await runFlightGuiSearch({ from: '上海', to: '丽江', date: '2027-05-02', backDate: '2027-05-09' });
+    assert(g5.ok === true && g5.verdict === 'hit' && (g5.options?.length ?? 0) === 0, '日历绑定:无行程回包时日历即 hit(#661)', g5);
+    assert((g5.calendar?.length ?? 0) === 3 && g5.calendar?.[0]?.date === '2026-10-16' && g5.calendar?.[0]?.price === 880 && g5.calendar?.[2]?.price === 760, '日历数据 /Date(ms)/→date 与 price>0 解析(#662,无价日过滤)', g5.calendar);
+    const calDup = parseLowestPriceCalendar(JSON.stringify({ priceList: [
+            { departDate: '/Date(1792080000000+0800)/', price: 900 }, { departDate: '/Date(1792080000000+0800)/', price: 700 },
+        ] }));
+    assert(calDup.length === 1 && calDup[0]?.price === 700, '往返双程同日双价 → 按日聚合取最低', calDup);
+    assert(g5.listUrl === 'https://flights.ctrip.com/online/list/roundtrip-sha-ljg?depdate=2027-05-02&retdate=2027-05-09', 'listUrl 回传(#663 URL 教师)', g5.listUrl);
+    assert(/低价日历/.test(g5.evidence), '日历证据链标注');
+    assert(parseLowestPriceCalendar('not json').length === 0 && parseLowestPriceCalendar('{"data":{"unknownShape":1}}').length === 0, '日历 parser 形状闸:未知形状空数组(不发明价格)');
+    const mixed = makeFakeDriver({ calendarBody: CAL_FIXTURE });
+    __setGuiDriverForTest(() => mixed.driver);
+    const g6 = await runFlightGuiSearch({ from: '上海', to: '丽江', date: '2027-05-02' });
+    assert((g6.options?.length ?? 0) === 1 && (g6.calendar?.length ?? 0) === 3 && /calendar=3天/.test(g6.evidence), '行程+日历双槽并存(行程优先结算,日历随行)', g6);
+    const rbDriver = makeFakeDriver({ formOverride: { dep: '2027-05-03' } }); // 日期被「改回」→ readback 必须拦
+    __setGuiDriverForTest(() => rbDriver.driver);
+    const g2 = await runFlightGuiSearch({ from: '上海', to: '丽江', date: '2027-05-02' });
+    assert(g2.ok === false && g2.verdict === 'error' && /readback 硬闸/.test(g2.error ?? ''), 'readback 硬闸:日期不符 → 终止,不发起搜索', g2);
+    assert(rbDriver.state.clickedSearch === false, 'readback 拦截后搜索按钮零点击(绝不搜错日期)');
+    const cityDriver = makeFakeDriver({ formOverride: { from: '北京(BJS)' } }); // 城市打进别的框(live 实测形态)
+    __setGuiDriverForTest(() => cityDriver.driver);
+    const g2b = await runFlightGuiSearch({ from: '上海', to: '丽江', date: '2027-05-02' });
+    assert(g2b.ok === false && /出发城市框未确认/.test(g2b.error ?? '') && cityDriver.state.clickedSearch === false, 'readback 逐字段:城市框错位(全局框假阳)→ 终止', g2b);
+    __setGuiDriverForTest(() => makeFakeDriver({ challenge: true }).driver);
+    const g3 = await runFlightGuiSearch({ from: '上海', to: '丽江', date: '2027-05-02' });
+    assert(g3.ok === false && g3.verdict === 'challenged', '风控页 → challenged(不重试不绕过)', g3);
+    __setGuiDriverForTest(() => makeFakeDriver({ apiBody: null }).driver);
+    const g4 = await runFlightGuiSearch({ from: '上海', to: '丽江', date: '2027-05-02' });
+    assert(g4.ok === false && g4.verdict === 'error' && /嗅探超时/.test(g4.error ?? ''), '回包超时 → 结构化 error', g4);
+    // 编排面:节律闸同站同桶 + 回程日期校验
+    __resetRateLimiterForTest();
+    __setGuiDriverForTest(() => makeFakeDriver().driver);
+    const s1 = await sessionFlightGuiSearch({ from: '上海', to: '丽江', date: '2027-05-02' });
+    assert(s1.ok === true && s1.verdict === 'hit', 'sessionFlightGuiSearch 编排 → hit');
+    const s2 = await sessionFlightGuiSearch({ from: '上海', to: '丽江', date: '2027-05-02' });
+    assert(s2.ok === false && s2.verdict === 'cooldown', 'GUI 与 bridge 同站同桶:30s 内二调 → cooldown');
+    __resetRateLimiterForTest();
+    const s3 = await sessionFlightGuiSearch({ from: '上海', to: '丽江', date: '2027-05-02', backDate: '2027-05-01' });
+    assert(s3.ok === false && s3.verdict === 'error' && /回程日期/.test(s3.error ?? ''), '回程早于去程 → 参数闸拒绝');
+    // bridge 往返(#663 解锁):URL 形状由 GUI 教师实测定稿;回程≤去程仍参数闸拒绝
+    __resetRateLimiterForTest();
+    const s4 = await sessionFlightSearch({ from: '上海', to: '丽江', date: '2027-05-02', backDate: '2027-05-01' });
+    assert(s4.ok === false && s4.verdict === 'error' && /回程日期/.test(s4.error ?? ''), 'bridge 回程早于去程 → 参数闸拒绝', s4);
+    const rtUrl = buildEntryUrl('香港', '迪拜', '2026-11-13', {}, '2026-11-17');
+    assert(rtUrl.ok === true && rtUrl.url === 'https://flights.ctrip.com/online/list/round-hkg0-dxb0?depdate=2026-11-13_2026-11-17&cabin=y_s&adult=1&child=0&infant=0', '往返 URL=GUI 教师实证形状(round-{code}0)', rtUrl);
+    __setGuiDriverForTest(null);
+}
+// M. 携程酒店 GUI 车道(2026-10-14,#664 首片):规划/安全闸/readback/needs-login 边界
+{
+    console.log('M. 酒店 GUI 车道(规划器 + 安全闸 + 假 driver + 登录墙判语)');
+    const hp = planHotelGuiActions({ to: '迪拜', checkIn: '2026-12-06', checkOut: '2026-12-08' });
+    assert(hp.some(a => a.t === 'setDate' && a.which === 'in') && hp.some(a => a.t === 'setDate' && a.which === 'out'), '酒店规划:入住/退房成对');
+    assert(!assertHotelPlanSafe([{ t: 'typeCity', text: '立即下单' }]).ok, '安全闸:目的地位提交件文本拒绝');
+    assert(!assertHotelPlanSafe([{ t: 'goto', url: 'https://evil.example.com/' }]).ok, '安全闸:非固定入口拒绝');
+    const HOTEL_FIXTURE = JSON.stringify({ ResponseStatus: { Ack: 'Success' }, hotelList: [
+            { hotelName: '测试酒店', minPrice: 500, star: 4 },
+        ] });
+    const mkHotelDriver = (opts = {}) => {
+        const state = { clickedSearch: false, form: { to: '', in: '', out: '' }, url: 'https://hotels.ctrip.com/' };
+        const page = {
+            async goto() { },
+            async typeCity(text) { state.form.to = text; },
+            async pickSuggest(text) { state.form.to = `${text}(测试)`; },
+            async setDate(which, ymd) { state.form[which] = ymd; },
+            async press() { },
+            async clickSearch() { state.clickedSearch = true; if (opts.passportAfterSearch)
+                state.url = 'https://passport.ctrip.com/user/login?backurl=x'; },
+            async visibleFormText() {
+                const f = { ...state.form, ...opts.formOverride };
+                const cn = (ymd) => ymd ? `${Number(ymd.slice(5, 7))}月${Number(ymd.slice(8, 10))}日` : '';
+                return Object.values(f).concat(['上海', cn(f.in ?? ''), cn(f.out ?? '')]).join(' | ');
+            },
+            async destFieldValue() { return (opts.formOverride?.to ?? state.form.to) + '(测试)'; },
+            async pageText() { return '酒店预订'; },
+            async currentUrl() { return state.url; },
+            async waitForApiBody() {
+                if (opts.passportAfterSearch)
+                    return null;
+                return opts.body === undefined ? { url: 'https://hotels.ctrip.com/hotels/api/list', body: HOTEL_FIXTURE } : opts.body ? { url: 'x', body: opts.body } : null;
+            },
+        };
+        return { driver: { open: async () => page, close: async () => { } }, state };
+    };
+    __setHotelDriverForTest(() => mkHotelDriver().driver);
+    const h1 = await runHotelGuiSearch({ to: '上海', checkIn: '2026-11-13', checkOut: '2026-11-15' });
+    assert(h1.ok === true && h1.verdict === 'hit' && h1.anonymous === true && (h1.hotels?.length ?? 0) >= 1, '酒店假 driver 全流程 → hit(匿名标注;本地化日期格式核对)', h1);
+    const hLogin = mkHotelDriver({ passportAfterSearch: true });
+    __setHotelDriverForTest(() => hLogin.driver);
+    const h2 = await runHotelGuiSearch({ to: '上海', checkIn: '2026-11-13', checkOut: '2026-11-15' });
+    assert(h2.ok === false && h2.verdict === 'needs-login' && /gotry_session_login/.test(h2.error ?? ''), '登录墙(passport 跳转)→ needs-login 判语(live 实证边界)', h2);
+    const hBadDate = mkHotelDriver({ formOverride: { in: '2026-11-20' } });
+    __setHotelDriverForTest(() => hBadDate.driver);
+    const h3 = await runHotelGuiSearch({ to: '上海', checkIn: '2026-11-13', checkOut: '2026-11-15' });
+    assert(h3.ok === false && /readback 硬闸/.test(h3.error ?? '') && hBadDate.state.clickedSearch === false, 'readback 硬闸:入住日期错位 → 零搜索点击', h3);
+    assert((await runHotelGuiSearch({ to: '上海', checkIn: '2026-11-15', checkOut: '2026-11-13' })).verdict === 'error', '退房早于入住 → 参数闸拒绝');
+    __setHotelDriverForTest(null);
+}
 if (process.env.GOTRY_SESSION_TEST_FORCE_FAILURE === '1') {
     assert(false, 'forced session failure propagation proof');
 }

package/dist/src/artifact-delivery.js

@@ -0,0 +1,26 @@
+import { realpathSync, statSync } from 'node:fs';
+import { isAbsolute, relative, sep } from 'node:path';
+export function registerArtifactDeliveries(ctx) {
+    // Tool-registration-only hosts have no conversation event surface.
+    if (typeof ctx.on !== 'function')
+        return;
+    ctx.on('tools/result', (exec, result) => {
+        if (result.isError || exec.signal.aborted || !['gotry_itinerary_render', 'gotry_itinerary_deck_render'].includes(exec.name))
+            return;
+        const value = result.value;
+        const session = exec.agent?.session, cwd = session?.header.cwd;
+        if (!session || !cwd || !isAbsolute(cwd) || value?.ok !== true || typeof value.path !== 'string' || !isAbsolute(value.path))
+            return;
+        const boundary = ctx.get('sessionProjections')?.stateOf(session, 'turnBoundary');
+        if (!boundary || boundary.openTurnStartSeq === null)
+            return;
+        try {
+            const path = realpathSync(value.path), root = realpathSync(cwd), inside = relative(root, path);
+            if (inside === '..' || inside.startsWith('..' + sep) || isAbsolute(inside) || !statSync(path).isFile())
+                return;
+            session.append('deliverables/presented', { turn: boundary.lastTurn, callId: exec.callId,
+                files: [{ path: value.path, description: 'GoTry itinerary' }] });
+        }
+        catch { /* A deleted or escaped file cannot become a delivery. */ }
+    });
+}

package/dist/src/gotry-web-api.js

@@ -0,0 +1,219 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute } from 'node:path';
+import { verifyFlyaiCandidate } from '../../bin/gotry-flyai-verification.js';
+import { listArtifacts } from '../capabilities/artifacts.js';
+import { atomicWriteJson, clearFlyaiKey, displayEndpoint, endpointFingerprint, flyaiConfigPath, isPlaceholderFlyaiKey, maskFlyaiKey, readFlyaiConfig, readFlyaiVerification, removeFlyaiVerification, resolveFlyaiEndpoint, resolveFlyaiKey, saveFlyaiKey, sha256Hex, writeFlyaiVerification, } from '../capabilities/flyai-config.js';
+import { hbcliCredentialPath, hbcliSetupStatus, readHbcliCredentials, removeHbcliVerification, verifyHbcliCandidate, withHbcliCredentials, withoutHbcliCredentials, writeHbcliCredentials, writeHbcliVerification, } from '../capabilities/hbcli-config.js';
+const json = (value, status = 200) => Response.json(value, { status, headers: { 'cache-control': 'no-store' } });
+const rejection = (error, status = 400) => json({ ok: false, error }, status);
+const BODY_LIMIT = 8192;
+async function readInput(request) {
+    if (request.headers.get('content-type')?.split(';')[0].trim() !== 'application/json')
+        return rejection('需要 JSON 请求。', 415);
+    const reader = request.body?.getReader();
+    if (!reader)
+        return rejection('请求为空。');
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            bytes += chunk.value.byteLength;
+            if (bytes > BODY_LIMIT) {
+                await reader.cancel();
+                return rejection('请求过大。', 413);
+            }
+            chunks.push(chunk.value);
+        }
+        const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+        return value && typeof value === 'object' && !Array.isArray(value) ? value : rejection('请求无效。');
+    }
+    catch {
+        return rejection('请求无效。');
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+export function createGotryWebHandlers(options) {
+    const homeDir = options.homeDir ?? homedir(), env = options.env ?? process.env;
+    const paths = { homeDir, env }, configPath = flyaiConfigPath(homeDir);
+    const hbPaths = { homeDir, env, hbcliBin: options.hbcliBin };
+    let mutations = Promise.resolve();
+    const status = () => {
+        const current = resolveFlyaiKey(paths), endpoint = resolveFlyaiEndpoint(paths), receipt = readFlyaiVerification(homeDir);
+        const matches = current.key && receipt?.keySha256 === sha256Hex(current.key) && receipt.source === current.source
+            && receipt.endpointFingerprint === endpointFingerprint(endpoint.url) && receipt.endpointDebug === endpoint.debug;
+        return { ok: true, configured: Boolean(current.key), verified: Boolean(matches && receipt?.verdict === 'verified'),
+            writable: current.source !== 'env' && current.source !== 'env-debug' && process.platform !== 'win32', source: current.source,
+            endpoint: displayEndpoint(endpoint.url), endpointDebug: endpoint.debug,
+            ...(matches && receipt ? { checkedAt: receipt.at, verdict: receipt.verdict } : {}) };
+    };
+    const bytesAt = () => existsSync(configPath) ? readFileSync(configPath, 'utf8') : undefined;
+    async function mutate(input, signal) {
+        if (signal.aborted)
+            return rejection('操作已取消。', 409);
+        if (!status().writable)
+            return rejection('当前 Key 由环境变量提供或此平台不支持安全写入。', 409);
+        if (input.action === 'clear') {
+            const result = clearFlyaiKey(paths);
+            if (!result.ok)
+                return rejection('无法清除配置，请检查本机配置文件及权限。', 409);
+            removeFlyaiVerification(homeDir);
+            return json(status());
+        }
+        const key = typeof input.key === 'string' ? input.key.trim() : '';
+        if (!key || key.length > 2048 || /[\r\n\0]/.test(key) || isPlaceholderFlyaiKey(key))
+            return rejection('请粘贴控制台中的真实 API Key。');
+        const before = readFlyaiConfig(configPath);
+        if (!before.ok)
+            return rejection('原配置损坏，已保留原文件，请先修复。', 409);
+        const previousBytes = bytesAt(), endpoint = resolveFlyaiEndpoint(paths), fingerprint = endpointFingerprint(endpoint.url);
+        if (!fingerprint)
+            return rejection('当前服务地址无效。', 409);
+        const verify = await verifyFlyaiCandidate(key, { env: { ...env, HOME: homeDir }, signal });
+        if (signal.aborted || verify.verdict !== 'hit')
+            return json({ ok: false, verdict: signal.aborted ? 'cancelled' : verify.verdict,
+                error: signal.aborted ? '验证已取消，旧配置保留。' : verify.error ?? '验证失败，旧配置保留。' }, 422);
+        if (!status().writable || bytesAt() !== previousBytes || fingerprint !== endpointFingerprint(resolveFlyaiEndpoint(paths).url)) {
+            return rejection('配置在验证期间发生变化，请重新读取后再试。', 409);
+        }
+        const saved = saveFlyaiKey(key, paths);
+        if (!saved.ok)
+            return rejection('安全保存失败，旧配置保留，请检查本机权限。', 409);
+        const receiptSaved = writeFlyaiVerification({ schema: 'gotry.flyai-verification.v1', source: 'config',
+            keySha256: sha256Hex(key), maskedKey: maskFlyaiKey(key), verdict: 'verified', endpointFingerprint: fingerprint,
+            endpointDebug: endpoint.debug, at: new Date().toISOString() }, homeDir);
+        if (!receiptSaved) {
+            const restored = previousBytes === undefined
+                ? (() => { try {
+                    rmSync(configPath, { force: true });
+                    return true;
+                }
+                catch {
+                    return false;
+                } })()
+                : atomicWriteJson(configPath, before.data).ok;
+            return rejection(restored ? '验证回执保存失败，旧配置已恢复。' : '验证回执保存失败，恢复旧配置失败，请检查本机文件。', 409);
+        }
+        return json(status());
+    }
+    async function mutateHbcli(input, signal) {
+        if (signal.aborted)
+            return rejection('操作已取消。', 409);
+        if (!hbcliSetupStatus(hbPaths).writable)
+            return rejection('当前凭证来自环境变量，或本机配置不可安全写入。', 409);
+        const before = readHbcliCredentials(hbPaths);
+        if (!before.ok)
+            return rejection('原配置损坏，已保留原文件，请先修复。', 409);
+        if (input.action === 'clear') {
+            if (!writeHbcliCredentials(withoutHbcliCredentials(before.data), hbPaths))
+                return rejection('无法清除配置，请检查本机文件及权限。', 409);
+            removeHbcliVerification(homeDir);
+            return json(hbcliSetupStatus(hbPaths));
+        }
+        const appKey = typeof input.appKey === 'string' ? input.appKey.trim() : '';
+        const appSecret = typeof input.appSecret === 'string' ? input.appSecret.trim() : '';
+        if ([appKey, appSecret].some(value => !value || value.length > 2048 || /[\r\n\0]/.test(value)))
+            return rejection('请填写 HotelByte 提供的 App Key 和 App Secret。');
+        const verified = await verifyHbcliCandidate(appKey, appSecret, hbPaths, signal);
+        if (signal.aborted || verified.verdict === 'error' || verified.verdict === 'cancelled') {
+            return json({ ok: false, error: verified.error ?? '验证已取消，旧配置保留。' }, 422);
+        }
+        const current = readHbcliCredentials(hbPaths);
+        if (!hbcliSetupStatus(hbPaths).writable || !current.ok || current.bytes !== before.bytes)
+            return rejection('配置在验证期间发生变化，请重新读取后再试。', 409);
+        const next = withHbcliCredentials(before.data, appKey, appSecret);
+        if (!writeHbcliCredentials(next, hbPaths))
+            return rejection('安全保存失败，旧配置保留，请检查本机权限。', 409);
+        if (!writeHbcliVerification(next, verified.verdict, hbPaths)) {
+            const restored = before.bytes === undefined
+                ? (() => { try {
+                    rmSync(hbcliCredentialPath(hbPaths));
+                    return true;
+                }
+                catch {
+                    return false;
+                } })()
+                : writeHbcliCredentials(before.data, hbPaths);
+            return rejection(restored ? '验证回执保存失败，旧配置已恢复。' : '验证回执保存失败，请检查本机文件。', 409);
+        }
+        return json(hbcliSetupStatus(hbPaths));
+    }
+    return {
+        async hbcli(request) {
+            if (request.method === 'GET')
+                return json(hbcliSetupStatus(hbPaths));
+            if (request.method !== 'POST')
+                return rejection('不支持此操作。', 405);
+            const input = await readInput(request);
+            if (input instanceof Response)
+                return input;
+            if (!['save', 'clear'].includes(String(input.action))
+                || Object.keys(input).some(key => !['action', 'appKey', 'appSecret'].includes(key))
+                || (input.action === 'clear' && ('appKey' in input || 'appSecret' in input)))
+                return rejection('请求无效。');
+            const operation = mutations.then(() => mutateHbcli(input, request.signal)).catch(() => rejection('操作失败，未能确认保存，请重新读取状态。', 500));
+            mutations = operation.then(() => undefined);
+            return operation;
+        },
+        async flyai(request) {
+            if (request.method === 'GET')
+                return json(status());
+            if (request.method !== 'POST')
+                return rejection('不支持此操作。', 405);
+            const input = await readInput(request);
+            if (input instanceof Response)
+                return input;
+            if (!['save', 'clear'].includes(String(input.action)) || Object.keys(input).some(key => key !== 'action' && key !== 'key')
+                || (input.action === 'clear' && 'key' in input))
+                return rejection('请求无效。');
+            const operation = mutations.then(() => mutate(input, request.signal)).catch(() => rejection('操作失败，未能确认保存，请重新读取状态。', 500));
+            mutations = operation.then(() => undefined);
+            return operation;
+        },
+        async artifacts(request) {
+            const query = new URL(request.url).searchParams;
+            if ([...query.keys()].some(key => !['sessionId', 'search', 'offset', 'limit'].includes(key)))
+                return rejection('查询字段无效。');
+            const sessionId = query.get('sessionId') ?? '';
+            if (!/^[A-Za-z0-9_-]{1,256}$/.test(sessionId))
+                return rejection('需要有效会话。');
+            const cwd = await options.workspaceForSession(sessionId);
+            if (!cwd || !isAbsolute(cwd))
+                return rejection('会话工作目录不可用。', 404);
+            try {
+                return json({ ok: true, ...await listArtifacts({ stateRoot: options.stateRoot, cwd,
+                        handoffRoot: env.GOTRY_TURN_HANDOFF_ROOT ?? (options.stateRoot !== '.' ? options.stateRoot : cwd),
+                        search: query.get('search') ?? undefined, offset: query.has('offset') ? Number(query.get('offset')) : undefined,
+                        limit: query.has('limit') ? Number(query.get('limit')) : 20 }) });
+            }
+            catch {
+                return rejection('查询参数无效或产物暂时不可读取。');
+            }
+        },
+    };
+}
+export function registerGotryWebApi(ctx, stateRoot, hbcliBin) {
+    if (typeof ctx.inject !== 'function')
+        return;
+    ctx.inject(['connection', 'sessions'], scope => {
+        const connection = scope.get('connection');
+        const handlers = createGotryWebHandlers({ stateRoot, hbcliBin, workspaceForSession: async (sessionId) => {
+                const id = sessionId;
+                const live = scope.sessions.get(id)?.header;
+                const stored = live ? undefined : await scope.get('sessionPersistence')?.stat(sessionId);
+                return (live ?? stored?.header)?.cwd;
+            } });
+        // DSH's streaming adapter always attaches a request body; GET cannot use
+        // it. Exact routes have one body mode, so reads and bounded writes differ.
+        scope.effect(() => connection.fetch.register({ path: '/api/gotry/flyai', methods: ['GET'], requestBody: 'buffered', fetch: handlers.flyai }));
+        scope.effect(() => connection.fetch.register({ path: '/api/gotry/flyai/write', methods: ['POST'], requestBody: 'streaming', fetch: handlers.flyai }));
+        scope.effect(() => connection.fetch.register({ path: '/api/gotry/hbcli', methods: ['GET'], requestBody: 'buffered', fetch: handlers.hbcli }));
+        scope.effect(() => connection.fetch.register({ path: '/api/gotry/hbcli/write', methods: ['POST'], requestBody: 'streaming', fetch: handlers.hbcli }));
+        scope.effect(() => connection.fetch.register({ path: '/api/gotry/artifacts', methods: ['GET'], requestBody: 'buffered', fetch: handlers.artifacts }));
+    });
+}