@xtalpi/agentic-lab-skills 0.0.1

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/use/useSuperTableBitableLifecycle.ts

@@ -0,0 +1,547 @@
+/* eslint-disable @typescript-eslint/typedef, prefer-destructuring, no-continue, quote-props, operator-linebreak */
+import { computed, ref, watch } from 'vue'
+import type { Ref } from 'vue'
+import { fetchAgenticlabTicketList, postAgenticlabExecutionComplete } from '@/api/agenticlabTickets'
+import type { XNBBitableChoreo, XnbSuperCellContext } from '@/types/xnb-context'
+import { extractTicketIdsFromPayload, extractValveIdFromPayload } from '@/utils/openerTicketIds'
+
+/** 与 Book 子表、updateSubBitable 最后一参 `name` 对齐（示例名） */
+export const DEMO_SUB_TABLE_NAME = '演示'
+
+/** index 须与子表编辑器一致；单主表且编辑器为空时可试 `''`（多子表勿用空串） */
+export const DEMO_LIST_SUB = { index: 'sheet-demo', name: DEMO_SUB_TABLE_NAME, row: 200 } as const
+
+const HEADER_GRAY = '#9e9e9e'
+
+/** 列定义：field 为表格中文列头，key 为接口/内存行字段 */
+export const DEMO_LIST_COLS = [
+  { field: '编码', key: 'code' },
+  { field: '名称', key: 'name' },
+  { field: '数量', key: 'qty' }
+] as const
+
+export interface DemoListRow {
+  id: string
+  code: string
+  name: string
+  qty: number
+}
+
+const bitableConfig = {
+  columnlen: { '0': 120, '1': 160, '2': 100 },
+  rowlen: { 0: 34 }
+}
+
+function buildDataColumns (): Array<Record<string, unknown>> {
+  const cols: Array<Record<string, unknown>> = [
+    {
+      w: 120,
+      dv: { type: 'text_length' },
+      field: '编码',
+      readonly: true,
+      visible: true,
+      dbRelated: false,
+      filters: null,
+      configurable: false,
+      headerColor: HEADER_GRAY
+    },
+    {
+      w: 160,
+      dv: { type: 'text_length' },
+      field: '名称',
+      readonly: true,
+      visible: true,
+      dbRelated: false,
+      filters: null,
+      configurable: false,
+      headerColor: HEADER_GRAY
+    },
+    {
+      w: 100,
+      dv: { type: 'number' },
+      ct: { fa: '0', t: 'n' },
+      field: '数量',
+      readonly: true,
+      visible: true,
+      dbRelated: false,
+      filters: null,
+      configurable: false,
+      headerColor: HEADER_GRAY
+    }
+  ]
+  cols.forEach((dc, i) => {
+    dc.c = i
+  })
+  return cols
+}
+
+const dataColumns = buildDataColumns()
+
+/** opener `payload` 中带 `demoRows` 时用于首屏/刷新数据源（类型宽松便于对接） */
+export function parseDemoRowsFromOpenerPayload (payload: unknown): DemoListRow[] | null {
+  if (payload == null || typeof payload !== 'object') return null
+  const rows = (payload as { demoRows?: unknown }).demoRows
+  if (!Array.isArray(rows) || rows.length === 0) return null
+  const out: DemoListRow[] = []
+  for (const r of rows) {
+    if (r == null || typeof r !== 'object') continue
+    const o = r as Record<string, unknown>
+    const id = o.id != null ? String(o.id) : ''
+    if (!id) continue
+    const code = o.code != null ? String(o.code) : ''
+    const name = o.name != null ? String(o.name) : ''
+    const qty = typeof o.qty === 'number' ? o.qty : Number(o.qty)
+    if (!Number.isFinite(qty)) continue
+    out.push({ id, code, name, qty })
+  }
+  return out.length ? out : null
+}
+
+/** opener 已预拉工单列表时（如父级合并的 `ticketList`），直接映射为表格行 */
+function parseTicketListFromOpenerPayload (payload: unknown): DemoListRow[] | null {
+  if (payload == null || typeof payload !== 'object') return null
+  const list = (payload as { ticketList?: unknown }).ticketList
+  if (!Array.isArray(list) || list.length === 0) return null
+  const rows = list.map((t) => mapAgenticlabTicketToDemoRow(t)).filter((r): r is DemoListRow => r != null)
+  return rows.length ? rows : null
+}
+
+function numOr0 (v: unknown): number {
+  const n = typeof v === 'number' ? v : Number(v)
+  return Number.isFinite(n) ? n : 0
+}
+
+/** 将 `/api/ticket/list` 单项映射为示例表列（编码/名称/数量） */
+function mapAgenticlabTicketToDemoRow (raw: unknown): DemoListRow | null {
+  if (raw == null || typeof raw !== 'object') return null
+  const t = raw as Record<string, unknown>
+  const id = t.id != null ? String(t.id) : ''
+  if (!id) return null
+  const detail = t.detail != null && typeof t.detail === 'object' ? (t.detail as Record<string, unknown>) : {}
+  const ticketId = detail.ticket_id != null ? String(detail.ticket_id) : id
+  const name =
+    detail.compound_id != null
+      ? String(detail.compound_id)
+      : detail.smiles != null
+        ? String(detail.smiles)
+        : String(t.uuid ?? ticketId)
+  const pp = detail.process_params != null && typeof detail.process_params === 'object'
+    ? (detail.process_params as Record<string, unknown>)
+    : {}
+  const qty =
+    numOr0(pp['@requested_amount_mg']) ||
+    numOr0(detail.target_amount_1_mg) ||
+    numOr0(detail.target_amount_2_mg) ||
+    0
+  return { id, code: ticketId, name, qty }
+}
+
+export interface ListSubShape {
+  index: string
+  name: string
+  row: number
+}
+
+function handleBitable (bitable: Record<string, unknown>, sub: ListSubShape | undefined): void {
+  bitable.name = sub?.name
+  if (sub && Object.prototype.hasOwnProperty.call(sub, 'index')) bitable.index = sub.index
+  bitable.row = sub?.row ?? 200
+  bitable.xnb_show_sheetbar = true
+  bitable.xnb_hide_statisticbar = true
+  bitable.xnb_hide_toolbar = false
+  bitable.xnb_hide_formulaBar = false
+  bitable.xnb_excel_with_bg = true
+  bitable.xnb_height = `${Math.floor((window.innerHeight - 100) * 0.72)}px`
+  bitable.config = bitable.config ?? bitableConfig
+}
+
+function dataColumnsMismatch (bitable: Record<string, unknown>, cols: Array<Record<string, unknown>>): boolean {
+  const dc = (bitable.data_columns as Array<{ field?: string }> | undefined) ?? []
+  if (dc.length !== cols.length) return true
+  return cols.some((c, i) => c.field !== dc[i]?.field)
+}
+
+export interface UseSuperTableBitableLifecycleResult {
+  choreo: Ref<XNBBitableChoreo | null>
+  lastRowCount: Ref<number>
+  /** 首屏：ensure 列结构 + 拉数 + 写 items */
+  bootstrap: () => Promise<void>
+  /** 与 bitable-list-lifecycle.js 中 refreshTable 一致：列不齐则补建，再拉数，整表替换 items 后 update */
+  refreshTable: (opts?: { silentNotify?: boolean; skipLoading?: boolean }) => Promise<number>
+  /** 校验当前子表行：数量列为正数；`skipLoading` 为 true 时不套 loading（供提交前复用）；`silentSuccess` 为 true 时通过不弹成功提示 */
+  checkRows: (opts?: { skipLoading?: boolean; silentSuccess?: boolean }) => Promise<boolean>
+  /** 先 `checkRows`，再 POST `/api/execution/complete`（不触发整书保存） */
+  submitRows: () => Promise<void>
+}
+
+/**
+ * Vue 版「超级表格列表」生命周期。
+ * 刷新使用全量 `items = mapped`（`applyRowsToBitable(..., { replaceAll: true })`）；全量 list 接口须同此写法（见 orbit skill §8.5.2）。
+ */
+export function useSuperTableBitableLifecycle (
+  getContext: () => XnbSuperCellContext,
+  getOpenerPayload: () => unknown
+): UseSuperTableBitableLifecycleResult {
+  const choreo = ref<XNBBitableChoreo | null>(null)
+  const lastRowCount = ref(0)
+  /** 最近一次从 AgenticLab `GET /api/ticket/list` 拉到的完整工单，用于提交时与表格合并为 `tickets` */
+  const lastAgenticRawTickets = ref<Record<string, unknown>[]>([])
+  const cellUid = computed(() => getContext().cellUid || '')
+
+  watch(
+    () => [getContext().bookPath, getContext().cellUid, getContext().XNBBitable] as const,
+    () => {
+      const ctx = getContext()
+      const Ctor = ctx.XNBBitable
+      choreo.value =
+        Ctor != null
+          ? new Ctor({
+            bookPath: ctx.bookPath,
+            cellUid: ctx.cellUid
+          })
+          : null
+    },
+    { immediate: true }
+  )
+
+  function xnb (): XNBBitableChoreo {
+    const c = choreo.value
+    if (c == null) throw new Error('XNBBitable 未注入')
+    return c
+  }
+
+  const listSub: ListSubShape = {
+    index: DEMO_LIST_SUB.index,
+    name: DEMO_LIST_SUB.name,
+    row: DEMO_LIST_SUB.row
+  }
+
+  async function resolveBitableBySub (sub: ListSubShape): Promise<Record<string, unknown> | null> {
+    const x = xnb()
+    if (!(await x.getSubCell())) return null
+    const all = await x.getAllSubBitable(true)
+    if (sub.index) {
+      const hit = all.find((b) => b.index === sub.index)
+      if (hit) return hit
+    }
+    if (all.length === 1) return all[0] ?? null
+    const main = (await x.getSubBitable(true)) as Record<string, unknown> | null
+    if (main == null) return null
+    if (!sub.index || main.index === sub.index) return main
+    return null
+  }
+
+  async function rebuildSubBitableColumns (
+    bitable: Record<string, unknown>,
+    sub: ListSubShape,
+    cols: Array<Record<string, unknown>>
+  ): Promise<void> {
+    const x = xnb()
+    bitable.items = []
+    bitable.data_columns = []
+    await x.addColumns(bitable, cols, [])
+    handleBitable(bitable, sub)
+    await x.updateSubBitable([bitable], { isMerge: false, name: DEMO_SUB_TABLE_NAME })
+    if (typeof x.delay === 'function') await x.delay(20)
+  }
+
+  async function createEmptyBitable (isMerge = false): Promise<void> {
+    const x = xnb()
+    if (await x.getSubCell()) {
+      const bitable = (await x.getSubBitable(true)) as Record<string, unknown>
+      bitable.items = []
+      bitable.data_columns = []
+      await x.addColumns(bitable, dataColumns, [])
+      handleBitable(bitable, listSub)
+      await x.updateSubBitable([bitable], { isMerge, name: DEMO_SUB_TABLE_NAME })
+      if (typeof x.delay === 'function') await x.delay(10)
+      return
+    }
+    const bitable: Record<string, unknown> = { items: [], data_columns: [] }
+    handleBitable(bitable, listSub)
+    await x.addColumns(bitable, dataColumns, [])
+    await x.createSubBitable([bitable], DEMO_SUB_TABLE_NAME)
+  }
+
+  async function fetchDemoList (): Promise<DemoListRow[]> {
+    const payload = getOpenerPayload()
+    const baseUrl = import.meta.env.VITE_AGENTICLAB_API_URL || ''
+    const token = import.meta.env.VITE_DEV_TOKEN || ''
+    const ids = extractTicketIdsFromPayload(payload)
+    if (baseUrl !== '' && ids.length > 0) {
+      const list = await fetchAgenticlabTicketList({
+        baseUrl,
+        token,
+        ticketIds: ids
+      })
+      const fromApi = list.map((t) => mapAgenticlabTicketToDemoRow(t)).filter((r): r is DemoListRow => r != null)
+      if (fromApi.length > 0) {
+        lastAgenticRawTickets.value = list.map((t) => {
+          return t != null && typeof t === 'object' ? (t as Record<string, unknown>) : {}
+        })
+        return fromApi
+      }
+    }
+    lastAgenticRawTickets.value = []
+    const fromTicketList = parseTicketListFromOpenerPayload(payload)
+    if (fromTicketList != null) return fromTicketList
+    const fromOpener = parseDemoRowsFromOpenerPayload(payload)
+    if (fromOpener != null) return fromOpener
+    /* 无 Agentic 列表、无 opener ticketList/demoRows 时不注入占位行 */
+    return []
+  }
+
+  function mapRowToItem (row: DemoListRow, i: number): { id: string; fields: Record<string, string> } {
+    const fields: Record<string, string> = {}
+    for (const { field, key } of DEMO_LIST_COLS) {
+      const raw = row[key as keyof DemoListRow]
+      fields[field] = raw == null ? '' : typeof raw === 'object' ? JSON.stringify(raw) : String(raw)
+    }
+    return {
+      id: String(row.id ?? `${cellUid.value}-${i}`),
+      fields
+    }
+  }
+
+  /**
+   * `replaceAll: true`（刷新列表）：整表 `items = mapped`，与全量 list 接口写法一致，宿主表格易重绘。
+   * 默认 `replaceAll: false`：无可见行时整表替换，有行时按 id 合并 fields（询价式增量示例）。
+   */
+  async function applyRowsToBitable (
+    bitable: Record<string, unknown>,
+    rows: DemoListRow[],
+    opts?: { replaceAll?: boolean }
+  ): Promise<void> {
+    const x = xnb()
+    const mapped = rows.map((row, i) => mapRowToItem(row, i))
+    const items = (bitable.items as Array<{ id: string; fields: Record<string, string>; visible?: boolean }> | undefined) ?? []
+    const visible = items.filter((it) => it?.visible !== false)
+    if (opts?.replaceAll === true || !visible.length) {
+      bitable.items = mapped
+    } else {
+      const byId = new Map(mapped.map((m) => [m.id, m]))
+      for (const item of items) {
+        const hit = byId.get(item.id)
+        if (hit != null) item.fields = { ...item.fields, ...hit.fields }
+      }
+      const have = new Set(items.map((it) => it.id))
+      for (const m of mapped) {
+        if (!have.has(m.id)) items.push(m)
+      }
+      bitable.items = items
+    }
+
+    await x.updateSubBitable([bitable], { isMerge: true, name: DEMO_SUB_TABLE_NAME })
+    if (typeof x.delay === 'function') await x.delay(80)
+  }
+
+  async function ensureBitableStructure (): Promise<void> {
+    const x = xnb()
+    if (!(await x.getSubCell())) {
+      await createEmptyBitable()
+      return
+    }
+    const bitable = await resolveBitableBySub(listSub)
+    if (bitable == null) throw new Error('无法解析子表：请核对 listSub.index / name 与 Book')
+    if (dataColumnsMismatch(bitable, dataColumns) || !((bitable.data_columns as unknown[])?.length)) {
+      await rebuildSubBitableColumns(bitable, listSub, dataColumns)
+    }
+  }
+
+  async function refreshTable (opts: { silentNotify?: boolean; skipLoading?: boolean } = {}): Promise<number> {
+    const { silentNotify, skipLoading } = opts
+    const ctx = getContext()
+    const loadingShow = ctx.loadingShow
+    const loadingHide = ctx.loadingHide
+    const notifySuccess = ctx.notifySuccess
+    const notifyError = ctx.notifyError
+    const outer = !skipLoading
+    if (outer) loadingShow?.()
+    try {
+      const x = xnb()
+      let bitable = await resolveBitableBySub(listSub)
+      if (bitable == null && (await x.getSubCell())) {
+        bitable = (await x.getSubBitable(true)) as Record<string, unknown>
+      }
+      if (bitable == null) throw new Error('未解析到 bitable')
+
+      if (dataColumnsMismatch(bitable, dataColumns) || !((bitable.data_columns as unknown[])?.length)) {
+        await rebuildSubBitableColumns(bitable, listSub, dataColumns)
+      }
+
+      const rows = await fetchDemoList()
+      await applyRowsToBitable(bitable, rows, { replaceAll: true })
+      lastRowCount.value = rows.length
+      if (!silentNotify) notifySuccess?.(`已刷新，共 ${rows.length} 条`)
+      return rows.length
+    } catch (e) {
+      notifyError?.(e, '', '刷新失败')
+      throw e
+    } finally {
+      if (outer) loadingHide?.()
+    }
+  }
+
+  async function bootstrap (): Promise<void> {
+    const ctx = getContext()
+    const loadingShow = ctx.loadingShow
+    const loadingHide = ctx.loadingHide
+    const notifySuccess = ctx.notifySuccess
+    const notifyError = ctx.notifyError
+    loadingShow?.()
+    try {
+      await ensureBitableStructure()
+      await refreshTable({ silentNotify: true, skipLoading: true })
+      notifySuccess?.('演示表已加载')
+    } catch (e) {
+      notifyError?.(e, '', '首屏加载失败')
+      throw e
+    } finally {
+      loadingHide?.()
+    }
+  }
+
+  async function checkRows (opts: { skipLoading?: boolean; silentSuccess?: boolean } = {}): Promise<boolean> {
+    const { skipLoading = false, silentSuccess = false } = opts
+    const ctx = getContext()
+    const notifySuccess = ctx.notifySuccess
+    const notifyError = ctx.notifyError
+    const loadingShow = ctx.loadingShow
+    const loadingHide = ctx.loadingHide
+    const outer = !skipLoading
+    if (outer) loadingShow?.()
+    try {
+      const x = xnb()
+      const bitable = (await resolveBitableBySub(listSub)) ?? ((await x.getSubBitable(true)) as Record<string, unknown>)
+      const items = (bitable.items as Array<{ fields?: Record<string, string> }> | undefined) ?? []
+      const visible = items.filter((it) => (it as { visible?: boolean }).visible !== false)
+      const qtyField = DEMO_LIST_COLS.find((c) => c.key === 'qty')?.field ?? '数量'
+      const bad: string[] = []
+      for (const it of visible) {
+        const raw = it.fields?.[qtyField]
+        const n = Number(raw)
+        if (!Number.isFinite(n) || n <= 0) bad.push(String(it.fields?.['编码'] ?? it.fields?.['名称'] ?? '?'))
+      }
+      if (bad.length) {
+        notifyError?.(new Error(`数量须为正数，行：${bad.join(', ')}`), '', '数据检查未通过')
+        return false
+      }
+      if (!silentSuccess) {
+        notifySuccess?.(`数据检查通过，共 ${visible.length} 行`)
+      }
+      return true
+    } catch (e) {
+      notifyError?.(e, '', '数据检查失败')
+      throw e
+    } finally {
+      if (outer) loadingHide?.()
+    }
+  }
+
+  function resolveValveIdForSubmit (): number {
+    const fromPayload = extractValveIdFromPayload(getOpenerPayload())
+    if (fromPayload != null) return fromPayload
+    const env = import.meta.env.VITE_AGENTICLAB_VALVE_ID
+    if (env != null && env !== '') {
+      const n = Number(env)
+      if (Number.isFinite(n)) return n
+    }
+    return 0
+  }
+
+  /** 将表格行中的「数量」写回工单 `detail`（与 `mapAgenticlabTicketToDemoRow` 读取路径对齐） */
+  function mergeEditedRowIntoAgenticTicket (ticket: Record<string, unknown>, row: DemoListRow): Record<string, unknown> {
+    const out = JSON.parse(JSON.stringify(ticket)) as Record<string, unknown>
+    const detail = (out.detail != null && typeof out.detail === 'object' ? out.detail : {}) as Record<string, unknown>
+    const pp =
+      detail.process_params != null && typeof detail.process_params === 'object'
+        ? ({ ...(detail.process_params as Record<string, unknown>) } as Record<string, unknown>)
+        : ({} as Record<string, unknown>)
+    pp['@requested_amount_mg'] = row.qty
+    detail.process_params = pp
+    detail.target_amount_1_mg = row.qty
+    out.detail = detail
+    return out
+  }
+
+  function buildTicketsForComplete (bitable: Record<string, unknown>): Record<string, unknown>[] {
+    const rows = itemsToRows(bitable)
+    const byId = new Map(lastAgenticRawTickets.value.map((t) => [String(t.id), t]))
+    const tickets: Record<string, unknown>[] = []
+    for (const row of rows) {
+      const raw = byId.get(String(row.id))
+      if (raw == null) continue
+      tickets.push(mergeEditedRowIntoAgenticTicket(raw, row))
+    }
+    return tickets
+  }
+
+  function itemsToRows (bitable: Record<string, unknown>): DemoListRow[] {
+    const items = (bitable.items as Array<{ id: string; fields?: Record<string, string> }> | undefined) ?? []
+    const qtyField = DEMO_LIST_COLS.find((c) => c.key === 'qty')?.field ?? '数量'
+    return items
+      .filter((it) => (it as { visible?: boolean }).visible !== false)
+      .map((it) => {
+        const f = it.fields ?? {}
+        return {
+          id: String(it.id),
+          code: f['编码'] ?? '',
+          name: f['名称'] ?? '',
+          qty: Number(f[qtyField])
+        }
+      })
+  }
+
+  async function submitRows (): Promise<void> {
+    const ctx = getContext()
+    const notifySuccess = ctx.notifySuccess
+    const notifyError = ctx.notifyError
+    const loadingShow = ctx.loadingShow
+    const loadingHide = ctx.loadingHide
+    loadingShow?.()
+    try {
+      if (!(await checkRows({ skipLoading: true, silentSuccess: true }))) {
+        return
+      }
+      const baseUrl = import.meta.env.VITE_AGENTICLAB_API_URL || ''
+      const token = import.meta.env.VITE_DEV_TOKEN || ''
+      if (baseUrl === '') {
+        notifyError?.(new Error('未配置 VITE_AGENTICLAB_API_URL（接口地址）'), '', '无法提交')
+        return
+      }
+      const x = xnb()
+      const bitable = (await resolveBitableBySub(listSub)) ?? ((await x.getSubBitable(true)) as Record<string, unknown>)
+      const tickets = buildTicketsForComplete(bitable)
+      if (tickets.length === 0) {
+        notifyError?.(
+          new Error('当前表格行无法对应到已拉取的工单；请通过 ticket_ids 拉取列表后再提交'),
+          '',
+          '提交失败'
+        )
+        return
+      }
+      const valveId = resolveValveIdForSubmit()
+      await postAgenticlabExecutionComplete({
+        baseUrl,
+        token,
+        valveId,
+        tickets
+      })
+      notifySuccess?.(`已提交 ${tickets.length} 条工单（execution/complete）`)
+    } catch (e) {
+      notifyError?.(e, '', '提交失败')
+      throw e
+    } finally {
+      loadingHide?.()
+    }
+  }
+
+  return {
+    choreo,
+    lastRowCount,
+    bootstrap,
+    refreshTable,
+    checkRows,
+    submitRows
+  }
+}

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/utils/openerInitParams.ts

@@ -0,0 +1,158 @@
+/**
+ * 弹层 / 子页由 opener 打开时，用 URL `?trace=...` 与 opener `postMessage` 拉取完整初始化参数。
+ *
+ * **子页发送**：`{ msg: 'get-data', trace }`
+ *
+ * **宿主回包（流程页标准）**：
+ * `{ msg: 'get-data-response', trace: '<同一 trace>', ticket_ids, valve_id, ... }`
+ *
+ * **兼容旧约定**：`{ msg: 'data', trace, payload: <对象> }` 或 `msg: 'data'` 且字段平铺在根上。
+ *
+ * 监听器内校验 `e.source === window.opener`（跨源 postMessage 仍适用）。
+ *
+ * Dev 无 opener 或缺 trace 时返回 `skipped`；development 可读 `VITE_DEV_OPENER_INIT_JSON` 作回退。
+ */
+
+export type OpenerInitSkipped = 'no-opener-or-closed' | 'no-trace'
+
+/** 流程页 / AgenticLab 宿主标准回包 msg */
+export const OPENER_MSG_GET_DATA_RESPONSE = 'get-data-response'
+
+/** 模板 / dev 兼容回包 msg */
+export const OPENER_MSG_DATA = 'data'
+
+export interface OpenerInitDeps {
+  loadingShow: () => void
+  loadingHide: () => void
+  notifyError: (msg: unknown, ...rest: unknown[]) => void
+  /** 等待 opener 回包超时，默认 10000ms */
+  timeoutMs?: number
+}
+
+export interface OpenerInitResult {
+  ok: boolean
+  trace: string | null
+  /** 规范化后的业务参数（含 ticket_ids、valve_id 等） */
+  payload: unknown
+  skipped?: OpenerInitSkipped
+  /** 为 true 时表示 payload 来自 `VITE_DEV_OPENER_INIT_JSON`（仅 development） */
+  devFromEnv?: boolean
+}
+
+/**
+ * 解析 `.env.local` 中的 `VITE_DEV_OPENER_INIT_JSON`；非 development 或未配置时返回 `null`。
+ */
+export function parseDevOpenerInitFromEnv (): unknown | null {
+  if (!import.meta.env.DEV) return null
+  const raw = import.meta.env.VITE_DEV_OPENER_INIT_JSON
+  if (raw == null || typeof raw !== 'string' || raw.trim() === '') return null
+  try {
+    return JSON.parse(raw) as unknown
+  } catch {
+    console.warn('[openerInitParams] VITE_DEV_OPENER_INIT_JSON 不是合法 JSON，已忽略')
+    return null
+  }
+}
+
+function devPayloadWhenSkipped (): OpenerInitResult | null {
+  const dev = parseDevOpenerInitFromEnv()
+  if (dev == null) return null
+  return { ok: true, trace: null, payload: dev, devFromEnv: true }
+}
+
+/** 部分浏览器下 `e.source` 与缓存的 `opener` 引用不完全相等，需兼容 WindowProxy */
+function isMessageFromOpener (e: MessageEvent, opener: Window): boolean {
+  if (e.source == null) return false
+  return e.source === opener || e.source === window.opener
+}
+
+function omitMsgTrace (d: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const [k, v] of Object.entries(d)) {
+    if (k !== 'msg' && k !== 'trace') {
+      out[k] = v
+    }
+  }
+  return out
+}
+
+/**
+ * 将宿主 postMessage 回包规范为业务 payload（供 `openerTicketIds` 等使用）。
+ * @returns 匹配 trace 且 msg 合法时返回对象，否则 `null`
+ */
+export function parseOpenerReplyMessage (
+  d: Record<string, unknown>,
+  trace: string
+): unknown | null {
+  if (String(d.trace) !== String(trace)) return null
+
+  if (d.msg === OPENER_MSG_GET_DATA_RESPONSE) {
+    return omitMsgTrace(d)
+  }
+
+  if (d.msg === OPENER_MSG_DATA) {
+    if ('payload' in d && d.payload != null && typeof d.payload === 'object') {
+      return d.payload
+    }
+    const flat = omitMsgTrace(d)
+    return Object.keys(flat).length > 0 ? flat : null
+  }
+
+  return null
+}
+
+/**
+ * 拉取 opener 初始化参数
+ */
+export async function fetchOpenerInitPayload (deps: OpenerInitDeps): Promise<OpenerInitResult> {
+  const { loadingShow, loadingHide, notifyError, timeoutMs = 120000 } = deps
+  loadingShow()
+  try {
+    const opener = window.opener as Window | null
+    if (opener == null || opener.closed) {
+      const fromEnv = devPayloadWhenSkipped()
+      if (fromEnv != null) return fromEnv
+      return { ok: false, trace: null, payload: null, skipped: 'no-opener-or-closed' }
+    }
+
+    const searchParams = new URLSearchParams(window.location.search)
+    const trace = searchParams.get('trace')
+    if (trace == null || trace === '') {
+      const fromEnv = devPayloadWhenSkipped()
+      if (fromEnv != null) return fromEnv
+      return { ok: false, trace: null, payload: null, skipped: 'no-trace' }
+    }
+
+    const payload = await new Promise<unknown>((resolve: (v: unknown) => void, reject: (e?: unknown) => void) => {
+      const timer = window.setTimeout(() => {
+        window.removeEventListener('message', onMessage)
+        const err = new Error('Timeout')
+        notifyError(err, '', '初始化超时')
+        reject(err)
+      }, timeoutMs)
+
+      const onMessage = (e: MessageEvent): void => {
+        if (!isMessageFromOpener(e, opener)) return
+        const d = e.data as Record<string, unknown> | null
+        if (d == null || typeof d !== 'object') return
+
+        const parsed = parseOpenerReplyMessage(d, trace)
+        if (parsed == null) return
+
+        window.clearTimeout(timer)
+        window.removeEventListener('message', onMessage)
+        resolve(parsed)
+      }
+
+      window.addEventListener('message', onMessage)
+      opener.postMessage({ msg: 'get-data', trace }, '*')
+    })
+
+    return { ok: true, trace, payload }
+  } catch (err) {
+    notifyError(err, '', '初始化失败')
+    throw err
+  } finally {
+    loadingHide()
+  }
+}