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

package/ts/capabilities/session/transport.ts

@@ -0,0 +1,146 @@
+/**
+ * SessionTransport(会话检索传输层,RFC §3.2;2026-08-28 定案 puppeteer-core):
+ * - mode=cdp(默认):attach 用户日常 Chrome——Chrome 144+ 调试服务(chrome://inspect 开关)
+ *   与 playwright 不兼容(握手后 CDP 初始化悬挂,实测三轮),与 puppeteer 完全兼容(实测 2256 cookies)。
+ *   发现走 user-data-dir 的 DevToolsActivePort 文件(HTTP 发现面已硬化 404;Origin 头=403,安全设计)。
+ *   close() 只 disconnect,绝不关用户浏览器。
+ * - mode=persistent(测试/后备):puppeteer.launch 专用 profile(测试用 mktemp 隔离匿名态)。
+ * fail-closed(RFC §3.3-④):guard 装不上 = 整个会话打不开——不存在「无守卫的会话」这一形态。
+ * 永不抛错:任何启动失败降级为 TransportFailure,由 session-search 编排层消费。
+ */
+
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { attachReadGuardPuppeteer, type ReadGuardHandle } from './read-guard.ts'
+import type { Browser, Page } from 'puppeteer-core'
+
+/**
+ * puppeteer-core 为可选依赖(D-14:产品运行时零硬依赖,缺则优雅降级)。
+ * 顶层动态 import——npm 形态若未装 puppeteer-core,openSession 返回 TransportFailure
+ * 而非在模块加载期炸掉整个插件(2026-08-28 发布面实测:静态 import 会拖垮 index.ts 加载链)。
+ */
+async function loadPuppeteer(): Promise<typeof import('puppeteer-core') | { missing: true }> {
+  try {
+    return await import('puppeteer-core')
+  } catch {
+    return { missing: true }
+  }
+}
+
+export interface TransportFailure {
+  ok: false
+  summary: string
+}
+
+export interface SessionTransport {
+  ok: true
+  browser: Browser
+  page: Page
+  guard: ReadGuardHandle
+  close(): Promise<void>
+}
+
+export interface TransportOptions {
+  /** 传输模式:cdp=attach 用户日常 Chrome(默认,登录态=用户本人,founder 2026-08-28 定案);persistent=专用 profile(测试/后备) */
+  mode?: 'cdp' | 'persistent'
+  /** persistent 模式专用 profile 目录(测试用 mktemp 隔离匿名态;缺省 tmpdir) */
+  profileDir?: string
+  /** persistent 模式 headless(默认 true);cdp 模式恒为用户可见窗口 */
+  headless?: boolean
+  /** ReadGuard 审计落盘路径(缺省仅内存计数) */
+  auditPath?: string
+  /**
+   * 是否挂 ReadGuard(默认 true;检索面强制:检索会话不存在无守卫形态)。
+   * 唯一豁免 = 登录 bootstrap(guard:false):那是用户本人的凭证入口页,agent 只开页+只读轮询
+   * cookie 名,从不检索/点提交——守卫若在场,反而会物理 abort 用户自己的登录 POST
+   * (护照登录端点多为 POST /login/submit,命中写词模式),既挡登录又让我们站在用户
+   * 凭证流的中间(隐私+可靠性双输)。该形态下不发起任何检索导航、不落审计。
+   */
+  guard?: boolean
+  /**
+   * 开**自己的新标签页**(默认 false=沿用既有首页——那是用户的页面!)。
+   * 人机共治纪律(2026-08-29 founder:「我根本就看不到登录页面」):登录与检索一律
+   * newPage 开自己的页,绝不劫持用户已有标签页;closeOwnPage 控制收尾是否关掉自己开的页。
+   */
+  newPage?: boolean
+  /** newPage:true 时,close() 是否连自己开的标签页一起关(默认 true;登录引导保持 false——把登录页留给用户) */
+  closeOwnPage?: boolean
+}
+
+function devtoolsWsEndpoint(): { ws: string } | { err: string } {
+  try {
+    const udd = process.env.CHROME_USER_DATA_DIR ?? `${homedir()}/Library/Application Support/Google/Chrome`
+    const [port, wsPath] = readFileSync(`${udd}/DevToolsActivePort`, 'utf8').trim().split('\n')
+    if (!port || !wsPath?.startsWith('/devtools/browser/')) {
+      return { err: `DevToolsActivePort 内容异常: ${String(port)}/${String(wsPath)}` }
+    }
+    return { ws: `ws://127.0.0.1:${port.trim()}${wsPath.trim()}` }
+  } catch {
+    return { err: '日常 Chrome 未开调试端口。开启方法:Chrome 打开 chrome://inspect/#remote-debugging → 打开开关(Chrome 144+)' }
+  }
+}
+
+export async function openSession(opts: TransportOptions = {}): Promise<SessionTransport | TransportFailure> {
+  const pp = await loadPuppeteer()
+  if ('missing' in pp) {
+    return { ok: false, summary: 'puppeteer-core 未安装(可选依赖):会话检索不可用,官方通道 gotry_flyai_search 仍可用。安装:npm i -D puppeteer-core' }
+  }
+  const puppeteer = pp.default
+  const useCdp = opts.mode === 'cdp' || (opts.mode !== 'persistent' && !opts.profileDir)
+  let browser: Browser
+  let isCdp = false
+  if (useCdp) {
+    const d = devtoolsWsEndpoint()
+    if ('err' in d) return { ok: false, summary: d.err }
+    try {
+      browser = await puppeteer.connect({ browserWSEndpoint: d.ws, defaultViewport: null })
+      isCdp = true
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : (e as { message?: string })?.message ?? JSON.stringify(e).slice(0, 200)
+      return { ok: false, summary: `cdp attach 失败:${String(msg).split('\n')[0]}` }
+    }
+  } else {
+    const { tmpdir } = await import('node:os')
+    const profileDir = opts.profileDir ?? `${tmpdir()}/gotry-session-profile`
+    try {
+      browser = await puppeteer.launch({ channel: 'chrome', headless: opts.headless ?? true, userDataDir: profileDir })
+    } catch (e) {
+      return { ok: false, summary: `chrome launch failed: ${e instanceof Error ? e.message.split('\n')[0] : String(e)}` }
+    }
+  }
+  // fail-closed:guard 装不上即断开返回失败——不给无守卫的检索会话形态
+  // (唯一豁免:登录 bootstrap 显式 guard:false,见 TransportOptions 注释)
+  let guard: ReadGuardHandle | undefined
+  if (opts.guard !== false) {
+    try {
+      guard = await attachReadGuardPuppeteer(browser as unknown as Parameters<typeof attachReadGuardPuppeteer>[0], opts.auditPath)
+    } catch (e) {
+      await (isCdp ? browser.disconnect() : browser.close()).catch(() => { /* ignore */ })
+      return { ok: false, summary: `read-guard attach failed: ${e instanceof Error ? e.message.split('\n')[0] : String(e)}` }
+    }
+  }
+  // 标签页纪律:ownPage=自己开的新页(newPage:true)——用它,收尾按 closeOwnPage 关;
+  // 否则沿用既有首页(仅 persistent 兼容形态;cdp 检索/登录一律 newPage)
+  let ownPage: boolean = false
+  let page
+  if (opts.newPage) {
+    page = await browser.newPage()
+    ownPage = true
+  } else {
+    page = (await browser.pages())[0] ?? await browser.newPage()
+  }
+  return {
+    ok: true,
+    browser,
+    page,
+    guard: guard ?? { blockedCount: () => 0, requestCount: () => 0 },
+    close: async () => {
+      // 自己开的标签页按 closeOwnPage 收尾(登录引导保持 false——登录页留给用户);
+      // cdp:只断开连接,绝不关用户浏览器;persistent:关自己拉起的实例
+      if (ownPage && (opts.closeOwnPage ?? true)) {
+        await (page as { close(): Promise<void> }).close().catch(() => { /* ignore */ })
+      }
+      await (isCdp ? browser.disconnect() : browser.close()).catch(() => { /* ignore */ })
+    },
+  }
+}

package/ts/capabilities/session/wizard.ts

@@ -0,0 +1,140 @@
+/**
+ * 会话扩展 onboarding wizard(RFC docs/rfc/user-session-data-rfc.md §3.3,ADR-21 上架后重设)。
+ *
+ * 单一职责(2026-09-02 重设):**只做 Node 端两件事**——
+ *   ① 扩展文件从源落位到 `~/.gotry/extension`(幂等)
+ *   ② source/dest 静态预检 + manifest.key 校验(给 health-watch 前的快照)
+ *
+ * 浏览器商店安装是浏览器的事,dsh 渲染 verdict.installUrl 是 dsh UI 的事;
+ * gotry **不再**弹 GUI 面板(pbcopy/osascript/zenity/msg)、不再 open 浏览器、
+ * 不再写一墙文字 CLI 指引。任何"装到能用"的 UX 都由浏览器商店 + dsh UI 分担。
+ *
+ * 历史形态回顾:
+ * - 2026-08-30 初版:5 步编排 + 剪贴板 + GUI 面板 + 健康探活(全栈闭环初衷好,但越界管了浏览器)
+ * - 2026-09-02 上架后:缩为 2 步(ensure + watch precheck),纯 Node 职责
+ *
+ * 接口契约:
+ * - `runOnboardingWizard({ dryRun, extensionDir?, sourceDir? })` 返回 2 步 OnboardingResult
+ * - `defaultExtensionDir()` / `describeExtensionDir()` 留作公开工具
+ */
+
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+export interface OnboardingStep {
+  step: 'ensure-extension-files' | 'watch-extension-ready'
+  status: 'ok' | 'skip' | 'fail'
+  summary: string
+}
+
+export interface OnboardingOptions {
+  /** 零网络零浏览器;只校验命令编排与输出形态;run-all §40 必走 */
+  dryRun?: boolean
+  /** 扩展落位目录(默认 ~/.gotry/extension) */
+  extensionDir?: string
+  /** 源扩展目录(默认仓库 ./extension/,随 npm 装入 dist/extension) */
+  sourceDir?: string
+}
+
+export interface OnboardingResult {
+  ok: boolean
+  steps: OnboardingStep[]
+  extensionDir: string
+}
+
+const DEFAULT_SOURCE_DIR_CANDIDATES = [
+  join(process.cwd(), 'extension'),
+  join(process.cwd(), 'dist', 'extension'),
+  join(process.cwd(), 'ts', '..', 'extension'),
+]
+
+function resolveExtensionSourceDir(): string {
+  for (const candidate of DEFAULT_SOURCE_DIR_CANDIDATES) {
+    if (existsSync(join(candidate, 'manifest.json'))) return candidate
+  }
+  return DEFAULT_SOURCE_DIR_CANDIDATES[0]!
+}
+
+export function defaultExtensionDir(): string {
+  return join(homedir(), '.gotry', 'extension')
+}
+
+/** 落位扩展文件(幂等);缺源/源不全会 fail-soft,提示用户重跑 `gotry setup` */
+function ensureExtensionFiles(source: string, target: string, dryRun: boolean): OnboardingStep {
+  if (dryRun) return { step: 'ensure-extension-files', status: 'skip', summary: '[dry-run] skip 扩展落位' }
+  try {
+    if (!existsSync(source) || !existsSync(join(source, 'manifest.json'))) {
+      return { step: 'ensure-extension-files', status: 'fail', summary: `源扩展目录缺失 manifest.json: ${source}(先跑 npx @danceiny/gotry setup 落位)` }
+    }
+    mkdirSync(target, { recursive: true })
+    const required = ['manifest.json', 'background.js', 'content-main.js', 'content-bridge.js']
+    for (const f of required) {
+      const src = join(source, f)
+      if (!existsSync(src)) return { step: 'ensure-extension-files', status: 'fail', summary: `源扩展缺 ${f}(重新 npm install 或 gotry setup)` }
+      copyFileSync(src, join(target, f))
+    }
+    return { step: 'ensure-extension-files', status: 'ok', summary: `扩展已落位 ${target}(manifest+3 文件)` }
+  } catch (e) {
+    return { step: 'ensure-extension-files', status: 'fail', summary: `扩展落位失败: ${e instanceof Error ? e.message.slice(0, 120) : String(e)}` }
+  }
+}
+
+/** 静态预检:落位目录可见 + manifest.key 存在(扩展 ID 稳定)+ 源未新于 dest */
+async function watchExtensionReady(dryRun: boolean, sourceDir: string, extensionDir: string): Promise<OnboardingStep> {
+  if (dryRun) return { step: 'watch-extension-ready', status: 'skip', summary: '[dry-run] skip health-watch precheck' }
+  if (!existsSync(extensionDir) || !existsSync(join(extensionDir, 'manifest.json'))) {
+    return { step: 'watch-extension-ready', status: 'fail', summary: `落位缺失 manifest.json:${extensionDir}` }
+  }
+  try {
+    const srcStat = statSync(sourceDir)
+    const dstStat = statSync(extensionDir)
+    if (srcStat.mtimeMs > dstStat.mtimeMs) {
+      return { step: 'watch-extension-ready', status: 'fail', summary: `扩展文件可能过期(源比落位新);重跑 npx @danceiny/gotry setup` }
+    }
+    const manifest = JSON.parse(await (await import('node:fs/promises')).readFile(join(extensionDir, 'manifest.json'), 'utf8'))
+    if (typeof manifest.key !== 'string' || manifest.key.length < 100) {
+      return { step: 'watch-extension-ready', status: 'fail', summary: 'manifest.key 缺失或过短,扩展 ID 不能稳定' }
+    }
+  } catch (e) {
+    return { step: 'watch-extension-ready', status: 'fail', summary: `静态预检失败: ${e instanceof Error ? e.message.slice(0, 120) : String(e)}` }
+  }
+  return { step: 'watch-extension-ready', status: 'ok', summary: '扩展文件就绪(manifest.key 校验通过,后台轮询就绪态由 health-watch 接管)' }
+}
+
+/**
+ * 主入口(2 步):①扩展落位 ②watch precheck 静态预检。
+ * 真 health-watch 由 health-watch.ts 单独负责,不并入 wizard。
+ */
+export async function runOnboardingWizard(opts: OnboardingOptions = {}): Promise<OnboardingResult> {
+  const dryRun = opts.dryRun ?? false
+  const extensionDir = opts.extensionDir ?? defaultExtensionDir()
+  const sourceDir = opts.sourceDir ?? resolveExtensionSourceDir()
+
+  const steps: OnboardingStep[] = []
+  steps.push(ensureExtensionFiles(sourceDir, extensionDir, dryRun))
+  steps.push(await watchExtensionReady(dryRun, sourceDir, extensionDir))
+
+  const ok = steps.every((s) => s.status !== 'fail')
+  return { ok, steps, extensionDir }
+}
+
+/** stdout 人话化打印(给 bootstrap 子进程单行 JSON 输出之外的兜底形态) */
+export function printWizardResult(result: OnboardingResult, destination: NodeJS.WritableStream = process.stdout): void {
+  const tag = (s: OnboardingStep): string => {
+    if (s.status === 'ok') return '✅'
+    if (s.status === 'skip') return '⏭ '
+    return '❌'
+  }
+  for (const s of result.steps) {
+    destination.write(`${tag(s)} ${s.step}: ${s.summary}\n`)
+  }
+  destination.write(`extensionDir=${result.extensionDir}; overall=${result.ok ? 'ok' : 'has-failures'}\n`)
+}
+
+/** 公开诊断探针(bootstrap 报告用) */
+export function describeExtensionDir(extensionDir: string): { exists: boolean; fileCount: number; hasManifest: boolean } {
+  if (!existsSync(extensionDir)) return { exists: false, fileCount: 0, hasManifest: false }
+  const files = readdirSync(extensionDir)
+  return { exists: true, fileCount: files.length, hasManifest: files.includes('manifest.json') }
+}

package/ts/capabilities/session-consent.ts

@@ -0,0 +1,211 @@
+/**
+ * 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 注册表(新会话适配器接入时登记)。
+ *
+ * site 绑定(2026-09-10 #308):同一工具多个 kind(例如 gotry_session_search → flight/hotel/dida/train)
+ * 必须按与 execute 同源的 interpretArgs 选 site(包装 query 优先);授权与拒绝均按 site
+ * 分桶。缺省 kind 保持工具合同的 flight 默认值;unknown/malformed kind 失败关闭(deny,
+ * 不扩权),防止新站点未登记就放行。train 虽是 12306 公开查询面,仍经过本闸的 off/ask/allow。
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import { interpretArgs } from '../src/tool-packet.ts'
+
+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>
+}
+
+/**
+ * 工具级 site 表(无 kind 维度时使用):key=工具名,value=站点。
+ * 复合工具(同一名字下多 kind)在 SITE_FOR_KIND 中显式登记。
+ */
+export const ACCOUNT_TOOLS: Record<string, string> = {
+  gotry_session_search: 'ctrip-flight',
+}
+
+const SITE_LABEL: Record<string, string> = {
+  'ctrip-flight': '携程机票',
+  'ctrip-hotel': '携程酒店',
+  'dida-portal': 'Dida 供应商门户',
+  'train-12306': '12306 余票(公开查询面)',
+}
+
+/**
+ * 复合工具 × kind → site(#308:site 绑定)。
+ * 仅对显式登记的 kind 放行,未知 kind → 失败关闭(防止未登记站点扩权)。
+ * 12306 公开查询面(kind=train)仍受本工具的会话授权总闸约束,不因公开查询而绕过 off/ask/allow。
+ */
+export const SITE_FOR_KIND: Record<string, Record<string, string>> = {
+  gotry_session_search: {
+    flight: 'ctrip-flight',
+    hotel: 'ctrip-hotel',
+    dida: 'dida-portal',
+    train: 'train-12306',
+  },
+}
+
+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; arguments?: unknown }
+export type ConsentGate = (exec: ConsentExec, next: () => Promise<ConsentDecision>) => Promise<ConsentDecision>
+
+/** 会话检索工具支持的 kind;gate 与 execute 共用此选择结果。 */
+export const SESSION_SEARCH_KINDS = ['flight', 'hotel', 'train', 'dida'] as const
+export type SessionSearchKind = typeof SESSION_SEARCH_KINDS[number]
+
+export type SessionSearchKindSelection =
+  | { ok: true; kind: SessionSearchKind }
+  | { ok: false; reason: string }
+
+/**
+ * Select the kind exactly as the session tool execute path does.
+ * `interpretArgs` is intentionally the only query-wrapper normalizer: a
+ * wrapped query wins over conflicting flat fields, and omitted kind keeps the
+ * documented flight default. Explicit malformed/unknown kinds fail closed.
+ */
+export function resolveSessionSearchKind(args: unknown): SessionSearchKindSelection {
+  if (args === undefined) return { ok: true, kind: 'flight' }
+  if (!args || typeof args !== 'object' || Array.isArray(args)) {
+    return { ok: false, reason: 'gotry_session_search 参数必须是对象;无法安全选择 kind,已失败关闭' }
+  }
+  const selected = interpretArgs<{ kind?: unknown }>(args as { query?: unknown } & Record<string, unknown>)
+  if (!selected || typeof selected !== 'object' || Array.isArray(selected)) {
+    return { ok: false, reason: 'gotry_session_search 参数包装形态无效;无法安全选择 kind,已失败关闭' }
+  }
+  if (!Object.prototype.hasOwnProperty.call(selected, 'kind')) return { ok: true, kind: 'flight' }
+  const kind = (selected as { kind?: unknown }).kind
+  if (typeof kind !== 'string' || kind.length === 0) {
+    return { ok: false, reason: 'gotry_session_search 收到 malformed kind;无法安全选择站点,已失败关闭' }
+  }
+  if (!(SESSION_SEARCH_KINDS as readonly string[]).includes(kind)) {
+    return { ok: false, reason: `gotry_session_search 收到未知 kind=${kind};只支持 ${SESSION_SEARCH_KINDS.join('/')},未知 kind 失败关闭` }
+  }
+  return { ok: true, kind: kind as SessionSearchKind }
+}
+
+/**
+ * 解析 site(#308):对复合工具(缺省 kind=flight,未知/malformed kind → fail-closed);对未在
+ * SITE_FOR_KIND 登记的工具走原 ACCOUNT_TOOLS 表保持兼容。无 site → 放行(非账号面工具)。
+ */
+export function resolveSiteForExec(exec: ConsentExec): { site: string } | { failClosed: true; reason: string } | null {
+  const name = exec.name
+  if (!name) return null
+  const map = SITE_FOR_KIND[name]
+  if (map) {
+    const selected = resolveSessionSearchKind(exec.arguments)
+    if (!selected.ok) return { failClosed: true, reason: selected.reason }
+    const site = map[selected.kind]
+    if (!site) return { failClosed: true, reason: `工具 ${name} 的 kind=${selected.kind} 未登记站点;失败关闭` }
+    return { site }
+  }
+  const site = ACCOUNT_TOOLS[name]
+  if (!site) return null
+  return { site }
+}
+
+function reasonFor(toolName: string, site: string): string {
+  return `工具 ${toolName} 将使用你本人已登录的浏览器会话，在「${SITE_LABEL[site] ?? site}」进行只读检索`
+    + '（ReadGuard 物理只读：写请求在网络层即中止，agent 永不接触凭证与验证码）；'
+    + '本次批准仅在本会话内有效，会话结束即失效，不会跨会话延续。'
+}
+
+/**
+ * 账号会话授权闸:挂 dsh `tools/pre-execute` waterfall。
+ * 契约:
+ *   - 非账号面工具 → next() 放行(零开销);
+ *   - off → 拒绝(随时可关);
+ *   - 会话内已拒绝 → 拒绝且不弹卡(拒绝=本会话吊销;按 site 分桶,跨站不互授);
+ *   - 会话内已批准 / allow 预授权 → 放行;
+ *   - 复合工具未知/malformed kind → fail-closed deny(不扩权),缺省 kind=flight;
+ *   - 其余 → ApprovalService.request();allowed-once 按 site 入会话 granted;
+ *     rejected/cancelled 按 site 入会话 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 resolved = resolveSiteForExec(exec)
+    if (!resolved) return next()
+    if ('failClosed' in resolved) return { kind: 'deny', reason: resolved.reason }
+    const { site } = resolved
+    if ((opts.access() ?? 'ask') === 'off') {
+      return { kind: 'deny', reason: `工具 ${exec.name} 已被配置关闭（sessionAccess=off）。如需重新启用账号会话检索，请到配置中重新开启 sessionAccess。` }
+    }
+    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
+  }
+}