@danceiny/gotry 0.0.1-rc.11 → 0.0.1-rc.13

package/ts/capabilities/session-consent.ts

@@ -0,0 +1,127 @@
+/**
+ * SessionConsent——账号会话授权闸(RFC 合规支柱④「用户明示授权 + 站点白名单 + 随时可关」进代码)。
+ *
+ * founder 口径(2026-08-29):「OTA 这些都是工具,不要区分什么主路径/降级路径;
+ * 这要用到用户的账号,所以必须跟用户确认(请求授权)。」
+ * 运行时原生审批卡语义是 allowed-once(逐调用批准)——首日落地后 founder 实测纠偏:
+ * 「每次都要弹,经常无法点击」→ 逐次弹卡把授权变成了骚扰。授权模型 v2:
+ *
+ *   - 每会话每站点**首次调用**弹审批卡;allowed-once 记入该 agent 的 granted 集,
+ *     会话内同站点后续调用直接放行(不再弹);
+ *   - rejected/cancelled 视为**会话内吊销**(denied 集):本会话不再弹卡、不再执行,
+ *     返回值明确告诉模型「改走其他工具,不要反复尝试」——防止反复开页骚扰用户;
+ *   - 审批通道缺席(unavailable,如 headless 一问一答)→ deny 且**不**记 denied
+ *     (通道回来后还能问一次);
+ *   - sessionAccess = 'ask'(默认)| 'allow'(用户已明示预授权,放行)| 'off'(随时可关);
+ *   - 授权状态存 Weak<agent>——会话结束即遗忘,绝不跨会话持久化(明示授权不默认延续)。
+ * 审计:批准/拒绝事件由 dsh ApprovalService 落 session log(approval/asked + decided),
+ * 本模块不重复建账。站点白名单 = ACCOUNT_TOOLS 注册表(新会话适配器接入时登记)。
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+
+export type SessionAccess = 'ask' | 'allow' | 'off'
+export type ApprovalOutcome = 'allowed-once' | 'rejected' | 'cancelled' | 'unavailable'
+
+/** dsh-tools PreToolDecision 同构(自持类型,纯函数可离线测试) */
+export type ConsentDecision =
+  | { kind: 'allow' }
+  | { kind: 'deny'; reason: string }
+  | { kind: 'ask'; reason?: string }
+
+export interface ApprovalSeam {
+  request(r: { agent?: unknown; toolName: string; callId?: string; reason?: string; signal?: AbortSignal }): Promise<ApprovalOutcome>
+}
+
+/** 账号面工具 → 站点(白名单登记处;新会话适配器接入时在此登记) */
+export const ACCOUNT_TOOLS: Record<string, string> = {
+  gotry_session_search: 'ctrip-flight',
+}
+
+const SITE_LABEL: Record<string, string> = {
+  'ctrip-flight': '携程机票',
+}
+
+interface AuthState {
+  granted: Set<string>
+  denied: Set<string>
+}
+
+export interface ConsentGateOptions {
+  /** 主闸语义:ask=每会话每站点首调弹卡(默认);allow=配置级预授权放行;off=总闸关 */
+  access: () => string
+  /** 审批缝懒解析(审批服务晚于插件注册,与 dsh-tools serviceAsk 同协议,缺席=运行时原生 ask→fail-closed) */
+  approval?: () => ApprovalSeam | undefined
+  /** 授权状态仓(Weak:随 agent/会话回收;测试注入) */
+  store?: WeakMap<object, AuthState>
+}
+
+export type ConsentExec = { name?: string; agent?: object; callId?: string }
+export type ConsentGate = (exec: ConsentExec, next: () => Promise<ConsentDecision>) => Promise<ConsentDecision>
+
+function reasonFor(toolName: string, site: string): string {
+  return `${toolName} 将使用你本人已登录的浏览器会话做「${SITE_LABEL[site] ?? site}」只读检索`
+    + '(ReadGuard 物理只读:写请求网络层中止,agent 永不碰凭证与验证码);本次批准在你本会话内有效'
+}
+
+/**
+ * 账号会话授权闸:挂 dsh `tools/pre-execute` waterfall。
+ * 契约:
+ *   - 非账号面工具 → next() 放行(零开销);
+ *   - off → 拒绝(随时可关);
+ *   - 会话内已拒绝 → 拒绝且不弹卡(拒绝=本会话吊销);
+ *   - 会话内已批准 / allow 预授权 → 放行;
+ *   - 其余 → ApprovalService.request();allowed-once 记入会话 granted;
+ *     rejected/cancelled 记入会话 denied(本会话不在请求);
+ *     无审批通道 → deny(fail-closed,headless 无用户 = 无授权)。
+ */
+export function createConsentGate(opts: ConsentGateOptions): ConsentGate {
+  const store = opts.store ?? new WeakMap<object, AuthState>()
+  const approvalOf = opts.approval ?? (() => undefined)
+  return async (exec, next) => {
+    const site = exec.name && ACCOUNT_TOOLS[exec.name]
+    if (!site) return next()
+    if ((opts.access() ?? 'ask') === 'off') {
+      return { kind: 'deny', reason: `${exec.name} 已被配置关闭(sessionAccess=off);需要账号会话检索时由用户开启` }
+    }
+    const state = (exec.agent && store.get(exec.agent)) || undefined
+    if (state?.denied.has(site)) {
+      return { kind: 'deny', reason: `你在本会话已拒绝过「${SITE_LABEL[site] ?? site}」的账号会话检索——本会话不再请求授权,请改走其他工具推进` }
+    }
+    if (state?.granted.has(site) || (opts.access() === 'allow' && exec.agent)) return next()
+    const approval = opts.approval?.()
+    if (!approval || !exec.agent) return { kind: 'ask', reason: reasonFor(exec.name ?? '', site) }
+    let outcome: string
+    try {
+      outcome = await approval.request({ agent: exec.agent, toolName: exec.name ?? '', callId: exec.callId, reason: reasonFor(exec.name ?? '', site) })
+    } catch {
+      outcome = 'unavailable'
+    }
+    if (outcome === 'allowed-once') {
+      remember(store, exec.agent, site, 'grant')
+      return next()
+    }
+    if (outcome === 'rejected' || outcome === 'cancelled') {
+      remember(store, exec.agent, site, 'deny')
+      return { kind: 'deny', reason: `你拒绝了 ${exec.name} 的账号会话授权(本会话内生效);不再重复请求,请改走其他工具推进` }
+    }
+    return { kind: 'deny', reason: `${exec.name} 需要你授权,但当前没有可用的审批通道(headless 一问一答无审批界面;请在 web 会话中使用账号会话检索)` }
+  }
+}
+
+function remember(store: WeakMap<object, AuthState>, agent: object, site: string, mode: 'grant' | 'deny'): void {
+  const prev = store.get(agent) ?? { granted: new Set<string>(), denied: new Set<string>() }
+  if (mode === 'grant') prev.granted.add(site)
+  else prev.denied.add(site)
+  store.set(agent, prev)
+}
+
+/** 从运行时上下文懒解析审批缝(与 dsh-tools serviceAsk 的 ctx.get('approval') 同一协议) */
+export function approvalFromContext(ctx: Context): () => ApprovalSeam | undefined {
+  return () => {
+    const get = (ctx as unknown as { get?: (n: string) => unknown }).get
+    if (typeof get !== 'function') return undefined
+    const approval = get.call(ctx, 'approval') as ApprovalSeam | undefined
+    return approval && typeof approval.request === 'function' ? approval : undefined
+  }
+}

package/ts/capabilities/session-login.ts

@@ -0,0 +1,146 @@
+/**
+ * 账号会话登录引导(产品化工具面:gotry_session_login 的能力层,founder 2026-08-29「请产品化」)。
+ *
+ * **语义边界(防误解,founder 红线「我们是不会要求用户上传密钥给 gotry 的」)**:
+ *   - 登录发生在外部网站(携程官网),用用户自己的浏览器会话完成;
+ *   - gotry 不提供、不代填、不接触任何密码/短信验证码/cookie 值;
+ *   - 本模块唯一事实:**只读 cookie 的名字**,判断「是否已登录」这个布尔——
+ *     名称级存在性检查 = 数据最小化的极端形态(0 个值过手);
+ *   - 登录入口页不挂 ReadGuard(见 transport.ts guard:false 注释):那是用户自己的
+ *     凭证流,我们的拦截绝不能站在用户与网站中间(检索面守卫不变量不受影响)。
+ *
+ * flow:attach 用户日常 Chrome → 打开登录入口标签 → 用户在携程官网自行登录 →
+ * 本模块只读轮询票据 cookie **名字**(cticket/uid/uname/passport)→ 到齐即报「已登录」。
+ */
+
+import { openSession } from './session/transport.ts'
+
+export interface LoginTarget {
+  domain: string
+  /** 登录票据 cookie 名(经 founder 登录实测后校准;D-13 同源) */
+  names: string[]
+  label: string
+  entryUrl: string
+}
+
+/** 站点白名单 = 适配器注册表;新站点适配器落地时在此登记 */
+export const LOGIN_TARGETS: Record<string, LoginTarget> = {
+  'ctrip-flight': { domain: 'ctrip.com', names: ['cticket', 'uid', 'uname', 'passport'], label: '携程机票', entryUrl: 'https://flights.ctrip.com/' },
+  'meituan-hotel': { domain: 'meituan.com', names: ['lt', 'u', 'token', 'n'], label: '美团酒店', entryUrl: 'https://hotel.meituan.com/' },
+}
+
+interface CookieLike {
+  domain?: string
+  name?: string
+}
+
+export interface SessionLoginQuery {
+  /** 站点(默认 ctrip-flight) */
+  site?: string
+  /** 等待用户完成登录的上限(ms,默认 90_000;到点返 pending,不阻塞会话) */
+  waitMs?: number
+  /** 轮询间隔(ms,默认 3000;票据 cookie 名只读) */
+  pollMs?: number
+}
+
+export interface SessionLoginResult {
+  ok: boolean
+  via: 'session-login' | 'session-login-error'
+  evidence: string
+  latencyMs: number
+  verdict: 'logged-in' | 'pending' | 'needs-attach' | 'error'
+  site: string
+  /** 已检出的登录票据 cookie 名(名字,非值——本模块永不读取/存储/回传任何 cookie 值) */
+  tickets?: string[]
+  error?: string
+}
+
+function err(site: string, verdict: SessionLoginResult['verdict'], error: string, started: number, ts: string): SessionLoginResult {
+  return {
+    ok: false, via: 'session-login-error', evidence: `[会话:login-error@${ts}] ${error.slice(0, 200)}`,
+    latencyMs: Date.now() - started, verdict, site, error: error.slice(0, 200),
+  }
+}
+
+/** 只读轮询:目标域上已存在的登录票据 cookie 名单(只要名字,永不读值) */
+export async function pollTicketNames(browser: { cookies(): Promise<CookieLike[]> }, target: LoginTarget): Promise<string[]> {
+  const cookies = await browser.cookies().catch(() => [] as CookieLike[])
+  if (!Array.isArray(cookies)) return []
+  return cookies
+    .filter((c) => (c.domain ?? '').includes(target.domain) && c.name != null && target.names.includes(c.name))
+    .map((c) => c.name as string)
+}
+
+/**
+ * 产品化登录引导(永不抛错;登录由用户在携程官网完成,gotry 只做名称级存在性检查)。
+ * verdict:logged-in=已检出票据;pending=登录入口已打开、用户尚未完成(不阻塞,可稍后再查);
+ * needs-attach=用户 Chrome 未开调试端口(一次性开关指引);error=其余降级。
+ */
+export async function sessionLogin(q: SessionLoginQuery = {}): Promise<SessionLoginResult> {
+  const started = Date.now()
+  const ts = new Date().toISOString()
+  const site = q.site ?? 'ctrip-flight'
+  const target = LOGIN_TARGETS[site]
+  if (!target) {
+    return err(site, 'error', `未知站点 ${site}(可选 ${Object.keys(LOGIN_TARGETS).join('/')})`, started, ts)
+  }
+  // 人机共治纪律:开自己的新标签页并置前台——用户必须看见登录页(2026-08-29 founder:
+  // 「我根本就看不到登录页面」,此前误劫持用户既有标签页);closeOwnPage=false 把登录页留给用户
+  const t = await openSession({ mode: 'cdp', guard: false })
+  if (!t.ok) {
+    const needsAttach = /chrome:\/\/inspect|DevToolsActivePort|cdp attach 失败/.test(t.summary)
+    return err(
+      site,
+      needsAttach ? 'needs-attach' : 'error',
+      needsAttach
+        ? `${t.summary};开启方法:你的 Chrome 打开 chrome://inspect/#remote-debugging → 打开开关(Chrome 144+,一次性),开启后直接再说一声即可`
+        : t.summary,
+      started, ts,
+    )
+  }
+  const evidenceTag = `[会话:${site}-login@${ts}]`
+  try {
+    // 自动检测优先(2026-08-29 founder「UI 里有自动检测吗」):先只读票据名——
+    // 已登录则**零弹窗**直接确认,不打开任何页面;登录状态由用户在携程官网自然留存
+    const pre = await pollTicketNames(t.browser as unknown as { cookies(): Promise<CookieLike[]> }, target)
+    if (pre.length > 0) {
+      await t.close()
+      return {
+        ok: true, via: 'session-login', latencyMs: Date.now() - started, verdict: 'logged-in', site, tickets: pre,
+        evidence: `${evidenceTag} 自动检测:票据 cookie 已在(先前登录已生效)——[${pre.join(', ')}](只读名字,0 网页交互)`,
+      }
+    }
+    // 未检出 → 开自己的新标签页并置前台(绝不劫持用户既有页面),等待用户在官网完成登录
+    const page = await t.browser.newPage()
+    await (page as unknown as { bringToFront(): Promise<void> }).bringToFront().catch(() => { /* 某些环境不可置前 */ })
+    try {
+      await page.goto(target.entryUrl, { waitUntil: 'domcontentloaded', timeout: 30_000 })
+    } catch {
+      // 站点慢不致命:入口标签已打开,用户手动登录即可
+    }
+    console.log(`[session-login] ${target.label} 登录入口已在新标签页置前打开`)
+    const waitMs = Math.min(Math.max(q.waitMs ?? 90_000, 0), 300_000)
+    const pollMs = Math.min(Math.max(q.pollMs ?? 3_000, 500), 10_000)
+    const deadline = Date.now() + waitMs
+    let tickets: string[] = []
+    while (Date.now() < deadline) {
+      await new Promise<void>((resolve) => setTimeout(resolve, pollMs))
+      tickets = await pollTicketNames(t.browser as unknown as { cookies(): Promise<CookieLike[]> }, target)
+      if (tickets.length > 0) break
+    }
+    await t.close()
+    if (tickets.length > 0) {
+      return {
+        ok: true, via: 'session-login', latencyMs: Date.now() - started, verdict: 'logged-in', site, tickets,
+        evidence: `${evidenceTag} 票据 cookie 已检出 [${tickets.join(', ')}](只读名字;登录在你自己的浏览器里完成,gotry 全程未接触任何密码/验证码/cookie 值)`,
+      }
+    }
+    return {
+      ok: true, via: 'session-login', latencyMs: Date.now() - started, verdict: 'pending', site, tickets: [],
+      evidence: `${evidenceTag} 登录入口已在你的 Chrome 打开(${target.label});在标签页里正常登录完成后再说一声「继续查」即可——gotry 只检查"是否已登录",永不收集你的账号信息`,
+    }
+  } catch (e) {
+    await t.close().catch(() => { /* ignore */ })
+    return err(site, 'error', e instanceof Error ? e.message : String(e), started, ts)
+  }
+}

package/ts/capabilities/session-search.ts

@@ -47,6 +47,13 @@ export function __resetRateLimiterForTest(): void {
 
 const CHALLENGE_RE = /验证|滑块|captcha|verify/i
 
+/** 把 transport 文案漂移收敛为稳定的产品 verdict；纯函数供回归覆盖。 */
+export function classifyTransportFailure(summary: string, cdpMode: boolean): Extract<SessionVerdict, 'needs-attach' | 'error'> {
+  return cdpMode && /日常 Chrome 未开调试端口|cdp attach 失败/.test(summary)
+    ? 'needs-attach'
+    : 'error'
+}
+
 export async function sessionFlightSearch(q: SessionFlightQuery): Promise<SessionSearchResult> {
   const started = Date.now()
   const ts = new Date().toISOString()
@@ -67,11 +74,12 @@ export async function sessionFlightSearch(q: SessionFlightQuery): Promise<Sessio
     return err('error', `unresolved entry: ${(entry.unresolved ?? []).join('/')} 不在城市码表`)
   }
 
-  const t = await openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: q.profileDir ? 'persistent' : 'cdp' })
+  // 人机共治纪律:检索一律开自己的新标签页(绝不劫持用户已有页面),用完关自己的页
+  const t = await openSession({ profileDir: q.profileDir, headless: q.headless, auditPath: q.auditPath, mode: q.profileDir ? 'persistent' : 'cdp', newPage: true })
   if (!t.ok) {
-    // cdp 未开端口 → needs-attach(一次性用户动作);persistent 启动失败仍走 error
-    if (q.profileDir === undefined && /cdp attach 失败/.test(t.summary)) return err('needs-attach', t.summary)
-    return err('error', t.summary)
+    // cdp 未开端口或握手失败 → needs-attach(一次性用户动作);persistent 启动失败仍走 error。
+    // transport 的“端口未开”在连接前返回,文案不含 `cdp attach 失败`,两种形态都要归入同一用户门禁。
+    return err(classifyTransportFailure(t.summary, q.profileDir === undefined), t.summary)
   }
 
   try {
@@ -81,7 +89,7 @@ export async function sessionFlightSearch(q: SessionFlightQuery): Promise<Sessio
       return cookies.some((c) => c.domain.includes(SITE_DOMAIN.replace(/^\./, '')) && LOGIN_COOKIE_NAMES.includes(c.name))
     }
     if (!(await loggedIn()) && !q.allowAnonymous) {
-      return err('needs-login', '匿名实例——先跑 scripts/session-login.ts 用用户自己的账号建立登录态(allowAnonymous 仅限链路自检)')
+      return err('needs-login', '未检出你本人登录态——调用 gotry_session_login 为用户打开携程登录入口(登录在携程官网完成;gotry 永不经手密码/验证码/cookie 值)')
     }
     // 先挂监听再导航(Playwright network 模式):命中 networkHint 的第一个响应即搜索回包
     let settled = false

package/ts/capabilities/weather.ts

@@ -59,11 +59,11 @@ export function wmoLabel(code: number): string {
   return WMO_ZH[code] ?? `天气码${code}`
 }
 
-async function fetchJson(url: string, timeoutMs: number): Promise<{ ok: boolean; data?: unknown; error?: string }> {
+async function fetchJson(url: string, timeoutMs: number, headers: Record<string, string> = {}): Promise<{ ok: boolean; data?: unknown; error?: string }> {
   const ctrl = new AbortController()
   const timer = setTimeout(() => ctrl.abort(), timeoutMs)
   try {
-    const res = await fetch(url, { signal: ctrl.signal, headers: { Accept: 'application/json' } })
+    const res = await fetch(url, { signal: ctrl.signal, headers: { Accept: 'application/json', ...headers } })
     if (!res.ok) return { ok: false, error: `HTTP ${res.status}` }
     return { ok: true, data: await res.json() }
   } catch (e) {
@@ -73,29 +73,94 @@ async function fetchJson(url: string, timeoutMs: number): Promise<{ ok: boolean;
   }
 }
 
-/** 地名 → 坐标(地理编码,供 dsh 工具把「大理」转成经纬度) */
+const NOMINATIM_BASE = 'https://nominatim.openstreetmap.org/search'
+
+/** 行政级/人口重镇 feature_code(open-meteo 命名惯例):PPLC=首都 PPLA*=首府 PPLB=城镇 PPLX=区片 */
+const MAJOR_FEATURE = /^(PPLC|PPLA|PPLB|PPLX)/
+
+interface GeoHitInternal {
+  name: string
+  latitude: number
+  longitude: number
+  country?: string
+  admin1?: string
+  /** 排序用:open-meteo 有 population;同名小地(村/镇)缺失时按 -1 处理 */
+  population: number
+  featureCode: string
+}
+
+function stripHits(hits: GeoHitInternal[]): Array<{ name: string; latitude: number; longitude: number; country?: string; admin1?: string }> {
+  return hits.map(({ name, latitude, longitude, country, admin1 }) =>
+    ({ ...(country ? { country } : {}), ...(admin1 ? { admin1 } : {}), name, latitude, longitude }))
+}
+
+/** 地名 → 坐标(双源,供 dsh 工具把「大理」转成经纬度):
+ *  1. Open-Meteo(主源):命中按人口/行政级降序——「大理」会同时命中云南州府与四川同名乡,不能盲信次序;
+ *  2. Nominatim(兜底):open-meteo 的中文名覆盖有洞(实测(issue #24)「普吉岛」0 结果、
+ *     裸词「普吉」错配西藏林芝同名村),弱命中/零结果时走 Nominatim 拿正确目标,
+ *     兜底仍空则回退 open-meteo 弱结果(不比此前更差)。 */
 export async function geocodePlace(
   name: string,
   opts: { timeoutMs?: number; count?: number } = {},
-): Promise<{ ok: boolean; evidence: string; results: Array<{ name: string; latitude: number; longitude: number; country?: string; admin1?: string }>; error?: string }> {
+): Promise<{ ok: boolean; evidence: string; via?: 'open-meteo' | 'nominatim'; results: Array<{ name: string; latitude: number; longitude: number; country?: string; admin1?: string }>; error?: string }> {
   const ts = new Date().toISOString()
   const count = opts.count ?? 5
-  const url = `${GEOCODE_BASE}?name=${encodeURIComponent(name)}&count=${count}&language=zh&format=json`
-  const r = await fetchJson(url, opts.timeoutMs ?? 15_000)
-  if (!r.ok) {
-    return { ok: false, evidence: `[实时API:open-meteo-geo@error@${ts}]`, results: [], error: r.error }
+  const query = name.trim()
+  const omUrl = `${GEOCODE_BASE}?name=${encodeURIComponent(query)}&count=${count}&language=zh&format=json`
+  const r = await fetchJson(omUrl, opts.timeoutMs ?? 15_000)
+  const omResults: GeoHitInternal[] = r.ok
+    ? ((r.data as { results?: unknown[] })?.results ?? []).map((item) => {
+        const it = item as Record<string, unknown>
+        return {
+          name: String(it['name'] ?? ''),
+          latitude: Number(it['latitude']),
+          longitude: Number(it['longitude']),
+          country: it['country'] ? String(it['country']) : undefined,
+          admin1: it['admin1'] ? String(it['admin1']) : undefined,
+          population: Number(it['population'] ?? 0) || 0,
+          featureCode: String(it['feature_code'] ?? ''),
+        }
+      }).filter(h => h.name && Number.isFinite(h.latitude) && Number.isFinite(h.longitude))
+    : []
+  omResults.sort((a, b) => (b.population - a.population) || (Number(MAJOR_FEATURE.test(b.featureCode)) - Number(MAJOR_FEATURE.test(a.featureCode))))
+  const top = omResults[0]
+  // 强命中:有人口规模或主要行政级,直接采信(「深圳市」「曼谷」路径不变)
+  if (top && (top.population > 0 || MAJOR_FEATURE.test(top.featureCode))) {
+    return { ok: true, evidence: `[实时API:open-meteo-geo@${ts}]`, via: 'open-meteo', results: stripHits(omResults) }
+  }
+  // 弱命中/零结果/主源请求失败:Nominatim 兜底(免费无 key;中文 accept-language)
+  const nomTs = new Date().toISOString()
+  const nomUrl = `${NOMINATIM_BASE}?q=${encodeURIComponent(query)}&format=jsonv2&limit=${count}&accept-language=zh&addressdetails=1`
+  const nom = await fetchJson(nomUrl, opts.timeoutMs ?? 15_000, { 'User-Agent': 'gotry-travel-agent/0.1 (+https://github.com/Danceiny/gotry)' })
+  const nomResults: Array<{ name: string; latitude: number; longitude: number; country?: string; admin1?: string }> = nom.ok
+    ? ((nom.data as unknown[]) ?? []).map((item) => {
+        const it = item as Record<string, unknown>
+        const addr = (it['address'] ?? {}) as Record<string, string>
+        return {
+          name: String(it['name'] ?? ''),
+          latitude: Number(it['lat']),
+          longitude: Number(it['lon']),
+          country: addr['country'],
+          admin1: addr['province'] ?? addr['state'] ?? addr['county'],
+        }
+      }).filter(h => h.name && Number.isFinite(h.latitude) && Number.isFinite(h.longitude))
+    : []
+  if (nomResults.length) {
+    const omNote = r.ok
+      ? `open-meteo ${omResults.length} 条弱命中(无人口/行政级,不足采信)`
+      : `open-meteo 失败:${r.error ?? 'HTTP error'}`
+    return { ok: true, evidence: `[实时API:nominatim@${nomTs}](兜底层: ${omNote})`, via: 'nominatim', results: nomResults }
+  }
+  // 双源皆空/兜底失败:open-meteo 有弱结果仍返回(同构「降级不阻塞」契约),否则维持失败终态
+  if (omResults.length) {
+    return { ok: true, evidence: `[实时API:open-meteo-geo@${ts}]`, via: 'open-meteo', results: stripHits(omResults) }
+  }
+  return {
+    ok: false,
+    evidence: `[实时API:open-meteo-geo@error@${ts}];[实时API:nominatim@error@${nomTs}]`,
+    results: [],
+    error: r.ok ? `双源无结果:${nom.error ?? 'nominatim empty'}` : (r.error),
   }
-  const results = ((r.data as { results?: unknown[] })?.results ?? []).map((item) => {
-    const it = item as Record<string, unknown>
-    return {
-      name: String(it['name'] ?? ''),
-      latitude: Number(it['latitude']),
-      longitude: Number(it['longitude']),
-      country: it['country'] ? String(it['country']) : undefined,
-      admin1: it['admin1'] ? String(it['admin1']) : undefined,
-    }
-  })
-  return { ok: true, evidence: `[实时API:open-meteo-geo@${ts}]`, results }
 }
 
 /** 未来天气预报(≤16 天) */

package/ts/scripts/async-collect.ts

@@ -3,16 +3,50 @@
  * 经可日志化 solve 端口执行深度规划(done 步骤复用账本结果,不重执行),
  * 交付物落账本 + .deliverable.md 视图。可由任何后续进程执行(loopx 驱动的
  * tick、state-cli tick、人工、未来的通知系统)——「一小时后回来」跨进程成立,
- * 且崩溃恢复 exactly-once:重放不重复花钱。
+ * 且崩溃恢复 exactly-once:重放不重复花钱。最后一行固定输出
+ * gotry_async_terminal.v1 JSON；4/4 exit 0，非 4/4 exit 2。
  * 运行(在 ts/ 下):npx tsx scripts/async-collect.ts <ticketId> [stateRoot]
  * 环境变量 GOTRY_SOLVE_COUNT_FILE:每次真实求解追加一行(回归用计数探针)。
  */
 
 import { appendFileSync } from 'node:fs'
-import { collectDeepPlanning, loadAsyncTicket, makeJournaledSolvePort, settleAsyncTicket } from '../src/loop.ts'
+import {
+  ASYNC_TERMINAL_SCHEMA,
+  collectDeepPlanning,
+  loadAsyncTicket,
+  makeJournaledSolvePort,
+  settleAsyncTicket,
+  type AsyncTerminalOutcome,
+} from '../src/loop.ts'
 import { solveUnified } from '../src/unified.ts'
 import { openLedgerIfExists } from '../src/state-ledger.ts'
 
+function isTerminalOutcome(value: Record<string, unknown> | null): value is Record<string, unknown> & AsyncTerminalOutcome {
+  return value?.['schema'] === ASYNC_TERMINAL_SCHEMA
+    && (value['status'] === 'succeeded' || value['status'] === 'failed')
+    && typeof value['passed'] === 'number'
+    && value['total'] === 4
+    && Array.isArray(value['failed_checks'])
+}
+
+function legacyTerminalOutcome(ticket: string, status: 'settled' | 'failed', deliverable: string): AsyncTerminalOutcome {
+  const succeeded = status === 'settled' && deliverable.includes('不失望四条:4/4 ✅')
+  return {
+    schema: ASYNC_TERMINAL_SCHEMA,
+    ticket_id: ticket,
+    status: succeeded ? 'succeeded' : 'failed',
+    passed: succeeded ? 4 : 0,
+    total: 4,
+    checks: { legacy_human_marker_only: succeeded },
+    failed_checks: succeeded ? [] : ['legacy_unstructured_terminal'],
+  }
+}
+
+function emitTerminal(outcome: AsyncTerminalOutcome): never {
+  console.log(JSON.stringify(outcome))
+  process.exit(outcome.status === 'succeeded' ? 0 : 2)
+}
+
 const ticketId = process.argv[2]
 const stateRoot = process.argv[3] ?? '.'
 if (!ticketId) {
@@ -26,12 +60,17 @@ if (!loaded) {
   process.exit(1)
 }
 
-// 终态幂等:已 settled 的工单复诵账本交付物,零重算
+// 终态幂等:已 settled/failed 的工单复诵账本交付物与机器终态,零重算
 const ledger = openLedgerIfExists(stateRoot)
 const run = ledger?.getWorkflowRun(ticketId)
-if (run?.status === 'settled' && run.deliverable) {
+if ((run?.status === 'settled' || run?.status === 'failed') && run.deliverable) {
+  const storedOutcome = ledger?.getWorkflowTerminalOutcome(ticketId) ?? null
+  const outcome = isTerminalOutcome(storedOutcome)
+    ? storedOutcome
+    : legacyTerminalOutcome(ticketId, run.status, run.deliverable)
+  await settleAsyncTicket(ticketId, run.deliverable, stateRoot, outcome)
   console.log(`工单 ${ticketId} 已交付(账本终态,复诵不重算):\n\n${run.deliverable}`)
-  process.exit(0)
+  emitTerminal(outcome)
 }
 if (!ledger) {
   console.error(`工单 ${ticketId}:stateRoot(${stateRoot})无账本——持久化先于回收,不应发生`)
@@ -45,6 +84,8 @@ const solve = makeJournaledSolvePort(ledger, ticketId, solveUnified as never, {
   },
 })
 
-const { reply } = await collectDeepPlanning(loaded.state, loaded.ticket, solve)
-const out = await settleAsyncTicket(ticketId, reply, stateRoot)
+const { reply, outcome } = await collectDeepPlanning(loaded.state, loaded.ticket, solve)
+const out = await settleAsyncTicket(ticketId, reply, stateRoot, outcome)
 console.log(`交付物已落盘:${out}\n\n${reply}`)
+console.log(JSON.stringify(outcome))
+process.exitCode = outcome.status === 'succeeded' ? 0 : 2