@xtalpi/agentic-lab-skills 0.0.1

package/skills/lab-orbit-component-builder/examples/xnb-component-template/dev/src/mockXNBBitable.ts

@@ -0,0 +1,119 @@
+import type { DemoBitableSheet, XNBBitableChoreo } from '../../src/types/xnb-context'
+
+/** 与 `useSuperTableBitableLifecycle` 中 listSub.index 对齐，便于 dev 命中子表 */
+const DEV_DEFAULT_INDEX = 'sheet-demo'
+const DEV_DEFAULT_NAME = '演示'
+
+type BitableItem = { id: string; fields: Record<string, string>; visible?: boolean }
+
+type MainBitable = {
+  index: string
+  name: string
+  row: number
+  items: BitableItem[]
+  data_columns: Array<Record<string, unknown>>
+  config: Record<string, unknown>
+  xnb_show_sheetbar?: boolean
+  xnb_hide_statisticbar?: boolean
+  xnb_hide_toolbar?: boolean
+  xnb_hide_formulaBar?: boolean
+  xnb_excel_with_bg?: boolean
+  xnb_height?: string
+}
+
+/**
+ * Dev 专用：模拟宿主注入的 XNBBitable，便于 `bitable` 视图演练
+ * `new XNBBitable({ bookPath, cellUid })` 与 `getSubCell` / `getAllSubBitable` / `addColumns` 等调用链。
+ * 真机行为以 Orbit / 业务实现为准。
+ */
+export class DevXNBBitable implements XNBBitableChoreo {
+  bookPath: string
+  cellUid: string
+
+  private readonly main: MainBitable
+
+  constructor (opts: { bookPath: string; cellUid: string }) {
+    this.bookPath = opts.bookPath
+    this.cellUid = opts.cellUid
+    this.main = {
+      index: DEV_DEFAULT_INDEX,
+      name: DEV_DEFAULT_NAME,
+      row: 200,
+      items: [],
+      data_columns: [],
+      config: {}
+    }
+  }
+
+  async getSubCell (): Promise<string | null> {
+    return `mock-subcell::${this.cellUid}`
+  }
+
+  async getAllSubBitable (refresh?: boolean): Promise<DemoBitableSheet[]> {
+    if (refresh === true) {
+      /* dev mock 不区分 refresh；与真机签名对齐 */
+    }
+    return [this.main]
+  }
+
+  async getSubBitable (refresh?: boolean): Promise<DemoBitableSheet> {
+    if (refresh === true) {
+      /* dev mock 不区分 refresh；与真机签名对齐 */
+    }
+    return this.main
+  }
+
+  async addColumns (bitable: Record<string, unknown>, cols: unknown[], extra: unknown[]): Promise<void> {
+    if (Array.isArray(extra) && extra.length > 0) {
+      /* 第三参占位；真机可能传列元数据 */
+    }
+    const list = Array.isArray(cols) ? cols : []
+    const prev = Array.isArray(bitable.data_columns)
+      ? (bitable.data_columns as Array<Record<string, unknown>>)
+      : []
+    const offset = prev.length
+    bitable.data_columns = [
+      ...prev,
+      ...list.map((col: unknown, i: number) => ({
+        ...(typeof col === 'object' && col !== null ? (col as Record<string, unknown>) : {}),
+        c: offset + i
+      }))
+    ]
+  }
+
+  async createSubBitable (bitables: unknown[], sheetName: string): Promise<string> {
+    console.log('[DevXNBBitable] createSubBitable', sheetName, bitables)
+    const first = bitables[0] as Partial<MainBitable> | undefined
+    if (first != null) {
+      if (typeof first.index === 'string') this.main.index = first.index
+      if (typeof first.name === 'string') this.main.name = first.name
+      if (typeof first.row === 'number') this.main.row = first.row
+      if (Array.isArray(first.items)) this.main.items = [...first.items] as BitableItem[]
+      if (Array.isArray(first.data_columns)) {
+        this.main.data_columns = [...first.data_columns] as MainBitable['data_columns']
+      }
+      if (first.config != null && typeof first.config === 'object' && !Array.isArray(first.config)) {
+        this.main.config = { ...(first.config as Record<string, unknown>) }
+      }
+    }
+    return `mock-created-${sheetName}`
+  }
+
+  async updateSubBitable (bitables: unknown[], _opts?: Record<string, unknown>): Promise<void> {
+    const first = bitables[0] as Partial<MainBitable> | undefined
+    if (first == null) return
+    if (first !== this.main) {
+      if (Array.isArray(first.items)) this.main.items = [...first.items] as BitableItem[]
+      if (Array.isArray(first.data_columns)) {
+        this.main.data_columns = [...first.data_columns]
+      }
+    }
+    console.log('[DevXNBBitable] updateSubBitable', bitables, _opts)
+  }
+
+  async delay (ms: number): Promise<void> {
+    await new Promise<void>((resolve: () => void) => {
+      setTimeout(resolve, ms)
+    })
+  }
+}

package/skills/lab-orbit-component-builder/examples/xnb-component-template/dev/src/shims-vue.d.ts

@@ -0,0 +1,6 @@
+/* eslint-disable */
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<{}, {}, any>
+  export default component
+}

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

@@ -0,0 +1,75 @@
+/**
+ * Dev 联调：当前页作为 opener 宿主，子页带 `?trace=` 调用 `fetchOpenerInitPayload`。
+ * 回包格式与流程页一致：`get-data-response` + 平铺 `ticket_ids` / `valve_id`。
+ */
+
+import { OPENER_MSG_GET_DATA_RESPONSE } from '@/utils/openerInitParams'
+
+export const DEV_OPENER_CHILD_QUERY = 'devOpenerChild'
+
+export function isDevOpenerChildPage (): boolean {
+  const params = new URLSearchParams(window.location.search)
+  return (
+    params.get(DEV_OPENER_CHILD_QUERY) === '1'
+    && window.opener != null
+    && !window.opener.closed
+  )
+}
+
+export function createDevOpenerTrace (): string {
+  return `dev-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`
+}
+
+export interface DevOpenerHostHandle {
+  dispose: () => void
+}
+
+function flatFieldsFromPayload (payload: unknown): Record<string, unknown> {
+  if (payload == null || typeof payload !== 'object') return {}
+  const p = payload as Record<string, unknown>
+  const out: Record<string, unknown> = {}
+  if ('ticket_ids' in p) out.ticket_ids = p.ticket_ids
+  if ('valve_id' in p) out.valve_id = p.valve_id
+  return out
+}
+
+/**
+ * 监听子页 `{ msg: 'get-data', trace }`，回 `{ msg: 'get-data-response', trace, ticket_ids, valve_id }`。
+ */
+export function installDevOpenerHost (getPayload: () => unknown): DevOpenerHostHandle {
+  const onMessage = (e: MessageEvent): void => {
+    if (e.source == null || e.source === window) return
+    const d = e.data as Record<string, unknown> | null
+    if (d == null || typeof d !== 'object') return
+    if (d.msg !== 'get-data') return
+    const { trace } = d
+    if (typeof trace !== 'string' || trace === '') return
+
+    const flat = flatFieldsFromPayload(getPayload())
+    const child = e.source as Window
+    window.setTimeout(() => {
+      child.postMessage(
+        { msg: OPENER_MSG_GET_DATA_RESPONSE, trace, ...flat },
+        '*'
+      )
+      console.log('[devOpenerHost] 已回包 get-data-response', { trace, ...flat })
+    }, 0)
+  }
+
+  window.addEventListener('message', onMessage)
+  return {
+    dispose: (): void => {
+      window.removeEventListener('message', onMessage)
+    }
+  }
+}
+
+/**
+ * 打开子页（同源），URL 携带 `trace` 与 `devOpenerChild=1`。
+ */
+export function openDevOpenerChild (trace: string): Window | null {
+  const url = new URL(window.location.href)
+  url.searchParams.set('trace', trace)
+  url.searchParams.set(DEV_OPENER_CHILD_QUERY, '1')
+  return window.open(url.toString(), `dev-opener-${trace}`)
+}

package/skills/lab-orbit-component-builder/examples/xnb-component-template/index.html

@@ -0,0 +1,13 @@
+<!DOCTYPE html>
+<html lang="">
+  <head>
+    <meta charset="utf-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width,initial-scale=1.0,user-scalable=no">
+    <title>Xnb Component Dev</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/dev/src/main.ts"></script>
+  </body>
+</html>

package/skills/lab-orbit-component-builder/examples/xnb-component-template/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "xnbOrbitComponent",
+  "version": "0.2.0",
+  "author": "yansen.lei",
+  "main": "./dist/DemoOrbitBitable.umd.js",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "dev": "vite --config vite.dev.config.ts",
+    "dev:bitable": "VITE_COMPONENT_ID=bitable vite --config vite.dev.config.ts",
+    "dev:custom-page": "VITE_COMPONENT_ID=custom-page vite --config vite.dev.config.ts",
+    "build": "vite build --mode func",
+    "build:bitable": "VITE_COMPONENT_ID=bitable vite build --mode func",
+    "build:custom-page": "VITE_COMPONENT_ID=custom-page vite build --mode func",
+    "build:all": "npm run build:bitable && npm run build:custom-page",
+    "build:es": "vite build",
+    "lint": "eslint --ext .js,.ts,.tsx,.vue src"
+  },
+  "dependencies": {
+    "@vueuse/core": "^10.2.1"
+  },
+  "devDependencies": {
+    "dayjs": "^1.11.7",
+    "@quasar/extras": "^1.14.1",
+    "@quasar/vite-plugin": "1.6.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "@vitejs/plugin-vue": "^5.0.0",
+    "@vue/compiler-sfc": "3.2.29",
+    "@xtalpi/webb-api": "0.1.0",
+    "axios": "^1.7.0",
+    "eslint": "^8.57.0",
+    "eslint-plugin-vue": "^9.28.0",
+    "lodash": "^4.17.21",
+    "quasar": "2.12.7",
+    "rollup-plugin-external-globals": "^0.13.0",
+    "sass": "~1.77.6",
+    "typescript": "~5.5.0",
+    "vite": "^5.4.0",
+    "vite-plugin-compression": "^0.5.1",
+    "vite-plugin-css-injected-by-js": "^3.5.2",
+    "vue": "3.2.29"
+  },
+  "webb": {
+    "name": "DemoOrbitVueLib",
+    "type": "element",
+    "exports": [
+      {
+        "name": "View",
+        "category": "view"
+      }
+    ],
+    "dependencies": {}
+  }
+}

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/api/agenticlabTickets.ts

@@ -0,0 +1,110 @@
+/**
+ * AgenticLab App：Ticket 列表 HTTP。
+ * 请求走 **`orbitRequestJson`**（`src/utils/orbitHttpClient.ts`），优先 **`window.xnb.http.client.request`**，见 **OrbitAPI.md** §6.3。
+ */
+
+import { orbitRequestJson } from '@/utils/orbitHttpClient'
+
+export interface FetchAgenticlabTicketListParams {
+  /** 无尾部斜杠亦可，如 `https://agenticlab.example.com`；嵌入 Orbit 且仅用 http.client 时仍建议填写以便回退 fetch */
+  baseUrl: string
+  /**
+   * 可选静态 Bearer；为空时依次尝试：
+   * `await window.xnb.choreo.getUserToken()`（无参）、`VITE_DEV_TOKEN`。
+   */
+  token?: string
+  /** 业务工单号列表，对应 query `ticket_id__in`（多值逗号拼接） */
+  ticketIds: string[]
+  limit?: number
+  offset?: number
+}
+
+function joinBaseAndPath (baseUrl: string, path: string): string {
+  const trimmed = baseUrl.replace(/\/+$/, '')
+  const p = path.startsWith('/') ? path : `/${path}`
+  return `${trimmed}${p}`
+}
+
+async function resolveBearerToken (opts: { token?: string }): Promise<string | undefined> {
+  if (opts.token != null && opts.token !== '') return opts.token
+  const w = window as Window & { xnb?: { choreo?: { getUserToken?: () => Promise<string> } } }
+  const getToken = w.xnb?.choreo?.getUserToken
+  if (getToken != null) {
+    try {
+      return await getToken()
+    } catch {
+      return undefined
+    }
+  }
+  const env = import.meta.env.VITE_DEV_TOKEN
+  return env != null && env !== '' ? env : undefined
+}
+
+/**
+ * `GET /api/ticket/list`，`ticket_id__in` 为逗号拼接的 ticket 业务号（与 `detail.ticket_id` 对应）。
+ */
+export async function fetchAgenticlabTicketList (params: FetchAgenticlabTicketListParams): Promise<unknown[]> {
+  const { baseUrl, token, ticketIds, limit = 999999, offset = 0 } = params
+  if (!baseUrl || ticketIds.length === 0) return []
+
+  const url = joinBaseAndPath(baseUrl, '/api/ticket/list')
+  const bearer = await resolveBearerToken({ token })
+  const headers: Record<string, string> = { Accept: 'application/json' }
+  if (bearer != null && bearer !== '') {
+    headers.Authorization = `Bearer ${bearer}`
+  }
+
+  const raw = await orbitRequestJson({
+    method: 'get',
+    url,
+    headers,
+    query: {
+      limit,
+      offset,
+      ticket_id__in: ticketIds.join(',')
+    }
+  })
+  const body = raw as { code?: number; msg?: string; data?: { list?: unknown[] } }
+  if (body.code !== 200) {
+    throw new Error(body.msg != null && body.msg !== '' ? String(body.msg) : `业务 code ${String(body.code)}`)
+  }
+  return body.data?.list ?? []
+}
+
+export interface PostAgenticlabExecutionCompleteParams {
+  baseUrl: string
+  token?: string
+  /** 门控 / 执行实例标识，与后端约定一致；缺省可由 opener 或环境变量提供 */
+  valveId: number
+  /** 与列表项结构一致的工单对象数组，字段须与 `GET /api/ticket/list` 的 `list[]` 项对齐（含编辑后的 `detail` 等） */
+  tickets: Record<string, unknown>[]
+}
+
+/**
+ * `POST /api/execution/complete`：提交编辑后的Ticket列表，由后端完成执行闭环。
+ */
+export async function postAgenticlabExecutionComplete (params: PostAgenticlabExecutionCompleteParams): Promise<void> {
+  const { baseUrl, token, valveId, tickets } = params
+  if (!baseUrl) throw new Error('缺少 AgenticLab baseUrl')
+
+  const url = joinBaseAndPath(baseUrl, '/api/execution/complete')
+  const bearer = await resolveBearerToken({ token })
+  const headers: Record<string, string> = {
+    Accept: 'application/json',
+    'Content-Type': 'application/json; charset=utf-8'
+  }
+  if (bearer != null && bearer !== '') {
+    headers.Authorization = `Bearer ${bearer}`
+  }
+
+  const raw = await orbitRequestJson({
+    method: 'post',
+    url,
+    headers,
+    jsonBody: { valve_id: valveId, tickets }
+  })
+  const body = raw as { code?: number; msg?: string }
+  if (body.code !== 200) {
+    throw new Error(body.msg != null && body.msg !== '' ? String(body.msg) : `业务 code ${String(body.code)}`)
+  }
+}

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/entries/bitable.ts

@@ -0,0 +1,4 @@
+import View from '../views/bitable.vue'
+import packageData from '../../package.json'
+
+export { View, packageData }

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/entries/custom-page.ts

@@ -0,0 +1,4 @@
+import View from '../views/custom-page.vue'
+import packageData from '../../package.json'
+
+export { View, packageData }

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

@@ -0,0 +1 @@
+export { View, packageData } from './entries/bitable'

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/styles/orbit-quasar-host.scss

@@ -0,0 +1,19 @@
+/**
+ * Orbit Cell 内 Quasar 子树：根节点加 `class="orbit-quasar-host"` 后，本节点以下生效。
+ * - 主色：`color="primary"` / `.bg-primary` → `var(--q-primary)`
+ * - `q-btn`：紧凑内边距；关闭默认全大写
+ *
+ * 复用：在 SFC 的 `<style scoped lang="scss">` 内首行 `@import '@/styles/orbit-quasar-host.scss';`
+ * （须 scoped + `:deep(.q-btn)`，否则子组件 DOM 无法命中）
+ * 主题调整：新增/修改主色或全局 `q-btn` 表现请只改本文件；页面结构见 `src/views/bitable.vue`。
+ * 按钮分工：`primary` 仅提交等持久化写回；`outline` 仅刷新/检查等页面数据交互（见 studio-orbit-vue-component SKILL 规则 2）。
+ */
+.orbit-quasar-host {
+  --orbit-primary: #123aff;
+  --q-primary: var(--orbit-primary);
+
+  :deep(.q-btn) {
+    padding: 0 10px;
+    text-transform: none;
+  }
+}

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/types/context.ts

@@ -0,0 +1,15 @@
+export interface XnbContext {
+  bookPath: string
+  cellUid: string
+  notifySuccess: (msg: string) => void
+  notifyError: (msg: any) => void
+  loadingShow: (opts?: any) => void
+  loadingHide: () => void
+  userData: Record<string, any>
+  getUserData: () => Record<string, any>
+  updateUserData: (data: any) => void
+  mergeUserData: (data: any) => void
+  getInstanceById: (id: string) => any
+  getInstanceValueById: (id: string) => any
+  setInstanceValueById: (id: string, value: any) => void
+}

package/skills/lab-orbit-component-builder/examples/xnb-component-template/src/types/xnb-context.ts

@@ -0,0 +1,70 @@
+/**
+ * 与「超级表格 / 子 Cell」协作相关的 xnbContext 形状（精简版，便于本模板内类型对齐）。
+ * 完整类型定义以你们宿主或正式项目中的 `Types/context` 等为准；本处仅保留模板示例所需字段。
+ */
+
+/**
+ * 单张子表在 XNBBitable 侧的常见形状（`getSubBitable` / `getAllSubBitable` 返回值对齐用）。
+ * 宿主实现字段可能更多；此处保留示例所需最小集。
+ */
+export interface DemoBitableSheet {
+  index?: string
+  name?: string
+  row?: number
+  items: unknown[]
+  data_columns: unknown[]
+  config?: unknown
+  [key: string]: unknown
+}
+
+/** 子表创建时单张 bitable 的配置骨架（创建前常补全 items / data_columns / config） */
+export interface DemoSubBitableOption {
+  index?: string
+  name?: string
+  rowFocus?: number
+  columnFocus?: number
+  items?: unknown[]
+  data_columns?: unknown[]
+  config?: unknown[]
+  [key: string]: unknown
+}
+
+/** 宿主注入的 XNBBitable 构造函数（典型用法：`new XNBBitable({ bookPath, cellUid })`） */
+export interface XNBBitableChoreo {
+  getSubCell (): Promise<string | null>
+  createSubBitable (bitables: unknown[], sheetName: string): Promise<string>
+  /** 多子表时用于按 `index` 命中目标子表；单表场景常返回长度为 1 的数组 */
+  getAllSubBitable (refresh?: boolean): Promise<DemoBitableSheet[]>
+  getSubBitable (refresh?: boolean): Promise<DemoBitableSheet>
+  /**
+   * 为子表追加列定义（常见签名第三参为 `[]`）。
+   * 与 `bitable-list-lifecycle.js` 一致：重建列前常先清空 `bitable.data_columns` 再调用。
+   */
+  addColumns (bitable: Record<string, unknown>, dataColumns: unknown[], extra: unknown[]): Promise<void>
+  updateSubBitable (bitables: unknown[], opts?: Record<string, unknown>): Promise<void>
+  delay (ms: number): Promise<void>
+}
+
+export type XNBBitableConstructor = new (opts: { bookPath: string; cellUid: string }) => XNBBitableChoreo
+
+/** window.xnb.event 最小形状（仅示例里 on/off/emit） */
+export interface XnbEventBus {
+  on: (channel: string, handler: (...args: unknown[]) => void) => void
+  off: (channel: string, handler: (...args: unknown[]) => void) => void
+  emit: (channel: string, ...args: unknown[]) => void
+}
+
+/** 超级表格 Cell 场景下 xnbContext 常用字段（宿主注入上下文 + XNBBitable 类） */
+export interface XnbSuperCellContext {
+  bookPath: string
+  cellUid: string
+  /** 类本身，由宿主注入；dev 环境见 dev/src/mockXNBBitable.ts */
+  XNBBitable?: XNBBitableConstructor
+  loadingShow?: (opts?: unknown) => void
+  loadingHide?: () => void
+  notifySuccess?: (msg: string) => void
+  notifyError?: (msg: unknown, ...rest: unknown[]) => void
+  getUserData?: () => Record<string, unknown>
+  updateUserData?: (data: Record<string, unknown>) => Promise<void> | void
+  [key: string]: unknown
+}

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

@@ -0,0 +1,180 @@
+import { computed, onMounted, ref, watch } from 'vue'
+import type { ComputedRef, Ref } from 'vue'
+import { useQuasar } from 'quasar'
+import type { XnbSuperCellContext } from '@/types/xnb-context'
+import type { OpenerInitResult } from '@/utils/openerInitParams'
+import { fetchOpenerInitPayload } from '@/utils/openerInitParams'
+import { useSuperTableBitableLifecycle } from '@/use/useSuperTableBitableLifecycle'
+
+export interface UseBitablePageResult {
+  openerInitReady: Ref<boolean>
+  openerInitError: Ref<unknown>
+  openerErrorText: ComputedRef<string>
+  busyRefresh: Ref<boolean>
+  busyCheck: Ref<boolean>
+  busySubmit: Ref<boolean>
+  lastRowCount: Ref<number>
+  onRefresh: () => Promise<void>
+  onCheck: () => Promise<void>
+  onSubmit: () => Promise<void>
+}
+
+/**
+ * 超级表格 Cell 页：opener 初始化 + `useSuperTableBitableLifecycle`（刷新 / 检查 / 提交）。
+ */
+export function useBitablePage (getContext: () => XnbSuperCellContext): UseBitablePageResult {
+  const $q = useQuasar()
+
+  function confirmDataMutation (title: string, message: string): Promise<boolean> {
+    return new Promise<boolean>((resolve: (v: boolean) => void) => {
+      let settled = false
+      const finish = (v: boolean): void => {
+        if (settled) return
+        settled = true
+        resolve(v)
+      }
+      $q.dialog({
+        title,
+        message,
+        persistent: true,
+        ok: { label: '确定', color: 'primary', flat: false },
+        cancel: { label: '取消', flat: true, color: 'grey-8' }
+      })
+        .onOk(() => {
+          finish(true)
+        })
+        .onCancel(() => {
+          finish(false)
+        })
+        .onDismiss(() => {
+          finish(false)
+        })
+    })
+  }
+
+  const openerInit = ref<OpenerInitResult | null>(null)
+  const openerInitError = ref<unknown>(null)
+  const openerInitReady = ref(false)
+
+  const openerPayload = computed(() => {
+    if (openerInit.value?.ok === true) return openerInit.value.payload
+    return null
+  })
+
+  const openerErrorText = computed(() => '没有获得有效参数，请关闭页面重试。')
+
+  const { choreo, lastRowCount, bootstrap, refreshTable, checkRows, submitRows } = useSuperTableBitableLifecycle(
+    getContext,
+    () => openerPayload.value
+  )
+
+  const busyRefresh = ref(false)
+  const busyCheck = ref(false)
+  const busySubmit = ref(false)
+
+  async function runOpenerInit (): Promise<void> {
+    const ctx = getContext()
+    try {
+      openerInit.value = await fetchOpenerInitPayload({
+        loadingShow: () => {
+          ctx.loadingShow?.()
+        },
+        loadingHide: () => {
+          ctx.loadingHide?.()
+        },
+        notifyError: (msg: unknown, ...rest: unknown[]) => {
+          console.warn('[opener] init error:', msg, ...rest)
+        }
+      })
+      if (openerInit.value && !openerInit.value.ok) {
+        console.warn('[opener] init not ok:', openerInit.value.skipped)
+        openerInitError.value = new Error(openerInit.value.skipped || 'init-failed')
+      }
+    } catch (err) {
+      console.warn('[opener] init exception:', err)
+      openerInitError.value = err
+    } finally {
+      openerInitReady.value = true
+    }
+  }
+
+  async function runBootstrapSafe (): Promise<void> {
+    if (!choreo.value) return
+    try {
+      await bootstrap()
+    } catch {
+      /* composable 内已 notify */
+    }
+  }
+
+  async function onRefresh (): Promise<void> {
+    const ok = await confirmDataMutation(
+      '确认刷新',
+      '将重新拉取数据并覆盖当前表格内容，是否继续？'
+    )
+    if (!ok) return
+    busyRefresh.value = true
+    try {
+      await refreshTable({})
+    } finally {
+      busyRefresh.value = false
+    }
+  }
+
+  async function onCheck (): Promise<void> {
+    busyCheck.value = true
+    try {
+      await checkRows()
+    } finally {
+      busyCheck.value = false
+    }
+  }
+
+  async function onSubmit (): Promise<void> {
+    const ok = await confirmDataMutation(
+      '确认提交',
+      '将把当前表格中的工单提交至服务器（execution/complete），是否继续？'
+    )
+    if (!ok) return
+    busySubmit.value = true
+    try {
+      await submitRows()
+    } finally {
+      busySubmit.value = false
+    }
+  }
+
+  onMounted(() => {
+    runOpenerInit().catch(() => {})
+  })
+
+  watch(
+    [openerInitReady, openerPayload, choreo],
+    () => {
+      if (!openerInitReady.value || !choreo.value) return
+      runBootstrapSafe().catch(() => {})
+    },
+    { immediate: true }
+  )
+
+  watch(
+    () => [getContext().bookPath, getContext().cellUid, getContext().XNBBitable] as const,
+    () => {
+      if (!openerInitReady.value || !choreo.value) return
+      runBootstrapSafe().catch(() => {})
+    }
+  )
+
+  return {
+    openerInitReady,
+    openerInitError,
+    openerErrorText,
+    busyRefresh,
+    busyCheck,
+    busySubmit,
+    lastRowCount,
+    onRefresh,
+    onCheck,
+    onSubmit
+  }
+}