@_daniel_jiang/ai-host 0.1.0

package/src/store.ts

@@ -0,0 +1,327 @@
+import type {
+  HostAnchorRef,
+  HostHintPlacement,
+  HostPageAction,
+  HostPageContext,
+  HostRefreshPayload,
+  RegisterPageOptions,
+} from './types'
+import type { SerializedPageAction, WidgetPayload } from './messages'
+import { cloneForPostMessage } from './messages'
+
+function resolveMaybe<T>(v: T | (() => T)): T {
+  return typeof v === 'function' ? (v as () => T)() : v
+}
+
+export type PrimaryPageHint = {
+  pageId: string
+  actionId: string
+  hint: string
+  placement: HostHintPlacement
+}
+
+type PageRefreshBinding = {
+  refreshKey: string
+  onRefresh: (payload?: HostRefreshPayload) => void
+}
+
+const pageActions: Record<string, HostPageAction[]> = {}
+const pageRefresh: Record<string, PageRefreshBinding> = {}
+/** 宿主会话级上下文（系统 / 名称 / 描述 / 菜单；由 init.getHostContext 按需提供） */
+let hostContext: HostPageContext = {}
+let currentPageId: string | null = null
+let hintDismissed = false
+/** 当前页、hintPlacement=anchor 且焦点在该 action 锚点内 */
+let anchorFocusedActionId: string | null = null
+let hintUiListener: (() => void) | null = null
+let docFocusBound = false
+
+export function setHintUiListener(fn: (() => void) | null) {
+  hintUiListener = fn
+}
+
+function notifyHintUi() {
+  try {
+    hintUiListener?.()
+  } catch {
+    /* ignore */
+  }
+}
+
+export function resolveAnchorElement(anchor: HostPageAction['anchor']): HTMLElement | null {
+  if (!anchor) return null
+  const raw = typeof anchor === 'function' ? anchor() : anchor
+  if (!raw) return null
+  let el: Element | null = null
+  if (raw instanceof Element) {
+    el = raw
+  } else if (typeof raw === 'object' && raw.$el instanceof Element) {
+    el = raw.$el
+  }
+  if (!el) return null
+  const inner = el.querySelector?.('textarea, input, [contenteditable="true"]')
+  return (inner instanceof HTMLElement ? inner : el) as HTMLElement
+}
+
+function isHintNode(node: Node | null): boolean {
+  if (!node || typeof (node as Element).closest !== 'function') return false
+  return Boolean((node as Element).closest('#agent-host-launcher-hint'))
+}
+
+function actionWantsAnchorHint(action: HostPageAction): boolean {
+  return Boolean(action.anchor) && action.hintPlacement === 'anchor'
+}
+
+function syncAnchorFocusFromTarget(target: EventTarget | null, related?: EventTarget | null) {
+  if (!currentPageId) {
+    if (anchorFocusedActionId) {
+      anchorFocusedActionId = null
+      notifyHintUi()
+    }
+    return
+  }
+  if (isHintNode(target as Node) || isHintNode(related as Node)) return
+  const actions = pageActions[currentPageId] || []
+  let next: string | null = null
+  if (target instanceof Node) {
+    for (const a of actions) {
+      if (!actionWantsAnchorHint(a)) continue
+      const el = resolveAnchorElement(a.anchor)
+      if (el && el.contains(target)) {
+        next = a.id
+        break
+      }
+    }
+  }
+  if (next === anchorFocusedActionId) return
+  anchorFocusedActionId = next
+  notifyHintUi()
+}
+
+function onDocFocusIn(ev: FocusEvent) {
+  syncAnchorFocusFromTarget(ev.target)
+}
+
+function onDocFocusOut(ev: FocusEvent) {
+  if (isHintNode(ev.relatedTarget as Node)) return
+  const t = ev.target
+  if (!(t instanceof Node) || !currentPageId) return
+  const actions = pageActions[currentPageId] || []
+  const focused = actions.find((a) => a.id === anchorFocusedActionId)
+  if (!focused) return
+  const el = resolveAnchorElement(focused.anchor)
+  if (el && el.contains(t) && !el.contains(ev.relatedTarget as Node)) {
+    anchorFocusedActionId = null
+    notifyHintUi()
+  }
+}
+
+function ensureDocFocusListeners() {
+  if (docFocusBound || typeof document === 'undefined') return
+  document.addEventListener('focusin', onDocFocusIn, true)
+  document.addEventListener('focusout', onDocFocusOut, true)
+  docFocusBound = true
+}
+
+function inferRefreshKey(actions: HostPageAction[], explicit?: string): string | undefined {
+  const key = (explicit || '').trim()
+  if (key) return key
+  for (const a of actions) {
+    if (!a.hostContext) continue
+    const hc = resolveMaybe(a.hostContext)
+    const refresh = hc && typeof hc === 'object' ? String((hc as { refresh?: unknown }).refresh || '').trim() : ''
+    if (refresh) return refresh
+  }
+  return undefined
+}
+
+export function isDirectHostAction(action: Pick<HostPageAction, 'kind'> | Pick<SerializedPageAction, 'kind'> | null | undefined): boolean {
+  return (action?.kind || 'widget') === 'direct'
+}
+
+export function registerHostPage(
+  pageId: string,
+  actions: HostPageAction[],
+  options: RegisterPageOptions = {},
+) {
+  ensureDocFocusListeners()
+  const pageChanged = pageId !== currentPageId
+  if (pageChanged) {
+    hintDismissed = false
+    anchorFocusedActionId = null
+  }
+  pageActions[pageId] = actions
+  currentPageId = pageId
+  if (!pageChanged && actions.some((a) => !a.enabled || a.enabled())) {
+    hintDismissed = false
+  }
+
+  const refreshKey = inferRefreshKey(actions, options.refreshKey)
+  if (refreshKey && typeof options.onRefresh === 'function') {
+    pageRefresh[pageId] = { refreshKey, onRefresh: options.onRefresh }
+  } else {
+    delete pageRefresh[pageId]
+  }
+  notifyHintUi()
+}
+
+export function unregisterHostPage(pageId: string) {
+  delete pageActions[pageId]
+  delete pageRefresh[pageId]
+  if (currentPageId === pageId) {
+    currentPageId = null
+    anchorFocusedActionId = null
+  }
+  notifyHintUi()
+}
+
+function sanitizeHostContext(raw: HostPageContext): HostPageContext {
+  const next = cloneForPostMessage(raw || {})
+  for (const key of Object.keys(next)) {
+    const val = next[key]
+    if (val == null || (typeof val === 'string' && !val.trim())) {
+      delete next[key]
+    }
+  }
+  return next
+}
+
+/** 整份写入宿主会话上下文（按需拉取后回写；离开专病时不应残留旧 name） */
+export function replaceHostContext(partial: HostPageContext): HostPageContext {
+  hostContext = sanitizeHostContext(partial || {})
+  return { ...hostContext }
+}
+
+export function getHostContext(): HostPageContext {
+  return { ...hostContext }
+}
+
+export function clearHostContext() {
+  hostContext = {}
+}
+
+/** 任务完成：仅对仍注册且 refreshKey 匹配的页面触发刷新 */
+export function dispatchRegisteredPageRefresh(refreshKey: unknown, payload?: HostRefreshPayload) {
+  const key = String(refreshKey || '').trim()
+  if (!key) return
+  for (const binding of Object.values(pageRefresh)) {
+    if (binding.refreshKey !== key) continue
+    try {
+      binding.onRefresh(payload)
+    } catch {
+      /* 业务刷新失败不阻断完成回调 */
+    }
+  }
+}
+
+export function clearHostPageStore() {
+  for (const id of Object.keys(pageActions)) delete pageActions[id]
+  for (const id of Object.keys(pageRefresh)) delete pageRefresh[id]
+  hostContext = {}
+  currentPageId = null
+  hintDismissed = false
+  anchorFocusedActionId = null
+  notifyHintUi()
+}
+
+export function setCurrentHostPage(pageId: string | null) {
+  if (pageId !== currentPageId) {
+    hintDismissed = false
+    anchorFocusedActionId = null
+  }
+  currentPageId = pageId
+  notifyHintUi()
+}
+
+export function dismissCurrentPageHint() {
+  hintDismissed = true
+}
+
+export function serializePageActions(actions: HostPageAction[]): SerializedPageAction[] {
+  return actions.map((a) => ({
+    id: a.id,
+    workflow: a.workflow || a.skill || '',
+    label: a.label,
+    host: a.host,
+    hint: a.hint ? resolveMaybe(a.hint) : undefined,
+    hostContext: a.hostContext ? cloneForPostMessage(resolveMaybe(a.hostContext)) : undefined,
+    prefilled: a.prefilled ? cloneForPostMessage(resolveMaybe(a.prefilled)) : undefined,
+    enabled: a.enabled ? a.enabled() : true,
+    kind: a.kind,
+    skill: a.skill,
+    noTools: a.noTools === true ? true : undefined,
+  }))
+}
+
+export function buildActionLaunchPayload(pageId: string, actionId: string): {
+  action: HostPageAction
+  prefilled?: Record<string, unknown>
+  hostContext?: Record<string, unknown>
+} | null {
+  const action = (pageActions[pageId] || []).find((a) => a.id === actionId)
+  if (!action) return null
+  if (action.enabled && !action.enabled()) return null
+  const prefilled = action.prefilled ? cloneForPostMessage(resolveMaybe(action.prefilled)) : undefined
+  return {
+    action,
+    prefilled,
+    hostContext: action.hostContext ? cloneForPostMessage(resolveMaybe(action.hostContext)) : undefined,
+  }
+}
+
+export function buildActionWidgetRequest(pageId: string, actionId: string): WidgetPayload | null {
+  const packed = buildActionLaunchPayload(pageId, actionId)
+  if (!packed) return null
+  if (isDirectHostAction(packed.action)) return null
+  return {
+    workflow: packed.action.workflow || packed.action.skill || '',
+    title: packed.action.label,
+    host: packed.action.host,
+    prefilled: packed.prefilled,
+    hostContext: packed.hostContext,
+  }
+}
+
+export function getCurrentPageId() {
+  return currentPageId
+}
+
+export function getRegisteredPages(): { pageId: string; actions: HostPageAction[] }[] {
+  return Object.entries(pageActions).map(([pageId, actions]) => ({ pageId, actions }))
+}
+
+export function getActionAnchorElement(pageId: string, actionId: string): HTMLElement | null {
+  const action = (pageActions[pageId] || []).find((a) => a.id === actionId)
+  if (!action) return null
+  return resolveAnchorElement(action.anchor)
+}
+
+export function getActionAnchorRect(pageId: string, actionId: string): DOMRect | null {
+  const el = getActionAnchorElement(pageId, actionId)
+  if (!el) return null
+  const r = el.getBoundingClientRect()
+  if (!r.width && !r.height) return null
+  return r
+}
+
+export function getCurrentPagePrimaryAction(): PrimaryPageHint | null {
+  if (hintDismissed || !currentPageId) return null
+  const actions = pageActions[currentPageId] || []
+  for (const a of actions) {
+    if (a.enabled && !a.enabled()) continue
+    if (actionWantsAnchorHint(a) && anchorFocusedActionId !== a.id) continue
+    const hint = a.hint ? resolveMaybe(a.hint) : `可使用「${a.label}」`
+    const placement: HostHintPlacement = actionWantsAnchorHint(a) ? 'anchor' : 'launcher'
+    return { pageId: currentPageId, actionId: a.id, hint, placement }
+  }
+  return null
+}
+
+/** @deprecated 使用 getCurrentPagePrimaryAction */
+export function getCurrentPageHintText(): string | null {
+  return getCurrentPagePrimaryAction()?.hint ?? null
+}
+
+export function resolveHostAnchorElement(ref: HostAnchorRef | (() => HostAnchorRef)): HTMLElement | null {
+  return resolveAnchorElement(ref)
+}

package/src/types.ts

@@ -0,0 +1,159 @@
+export type HostActionKind = 'widget' | 'direct'
+
+export type HostHintPlacement = 'launcher' | 'anchor'
+
+/**
+ * 横幅锚点。优先传真实 DOM（`HTMLElement`）。
+ * Vue 2 单根组件可传实例（用 `$el`）。Vue 3 多根 / React 组件实例没有稳定 `$el`，请 `querySelector` 或 ref 取到节点再传入。
+ */
+export type HostAnchorRef =
+  | Element
+  | { $el?: Element | null }
+  | null
+  | undefined
+
+export type HostPageAction = {
+  id: string
+  /** Widget 工作流名；kind=direct 时可省略，此时用 skill */
+  workflow?: string
+  label: string
+  host?: string
+  /**
+   * widget（默认）：打开 FormWidget。
+   * direct：不弹窗。有 skill 时 Hub 发 Chat；仅有 workflow 时静默 POST /host/scenarios（不弹 Widget）。
+   */
+  kind?: HostActionKind
+  /** 内置 skill slug；kind=direct 时写入启动上下文 */
+  skill?: string
+  /**
+   * 可选覆盖。场景默认的 no_tools / skip_post_summary 在 Agent host_ui_registry。
+   * 不要写进 Skill，以免 Chat `@` 被连带改成无工具。
+   */
+  noTools?: boolean
+  hostContext?: Record<string, unknown> | (() => Record<string, unknown>)
+  prefilled?: Record<string, unknown> | (() => Record<string, unknown>)
+  enabled?: () => boolean
+  hint?: string | (() => string)
+  /**
+   * launcher（默认）：横幅贴在右下角 FAB 上方。
+   * anchor：横幅贴在 `anchor` 控件旁；仅当该控件处于焦点时显示。
+   */
+  hintPlacement?: HostHintPlacement
+  /** 控件锚点；函数在 registerPage 时于宿主求值 */
+  anchor?: HostAnchorRef | (() => HostAnchorRef)
+}
+
+/** EDC Host prefilled 公共字段（snake_case 为主，兼容宿主 camelCase） */
+export type HostPrefilledContext = {
+  sub_project_id?: string
+  subProjectId?: string
+  project_id?: string
+  projectId?: string
+  sort_start?: number
+}
+
+/** EDC AI 填表 prefilled */
+export type HostPrefilledPatients = HostPrefilledContext & {
+  forms?: unknown[]
+  visits?: unknown[]
+  target?: {
+    form_name?: string
+    form_guid?: string
+    visit_name?: string
+    visit_guid?: string
+    period_name?: string
+    form_fields: { fields: unknown[]; formName?: string; formGuid?: string }
+  }
+}
+
+export type OpenWorkflowOptions = {
+  host?: string
+  hostContext?: Record<string, unknown>
+  prefilled?: Record<string, unknown>
+  title?: string
+  label?: string
+  sessionId?: string
+  preferSandboxFiles?: boolean
+}
+
+export type HostRefreshPayload = {
+  taskId?: string
+  result?: string
+  hostContext?: Record<string, unknown>
+  apply?: Record<string, unknown>
+}
+
+/** 宿主会话级上下文（抽屉提问注入；专病 / 我的项目 / 数据探索 / 数据分析共用 name + description） */
+export type HostPageContext = {
+  /**
+   * 宿主系统标识，例如：
+   * - 专病数据库系统
+   * - 我的项目（EDC；属科研平台子系统）
+   * - 数据探索（属科研平台子系统）
+   * - 数据分析（在线分析；属科研平台子系统，路由 /analyzer）
+   * 科研平台本身包含「我的项目」「数据探索」「数据分析」等子系统，不要笼统写「科研平台」。
+   */
+  system?: string
+  /** 专病名或 EDC 项目名 */
+  name?: string
+  /** 专病描述或项目说明 */
+  description?: string
+  /** 当前菜单或页面名（按需读取时从路由取） */
+  menu?: string
+  [key: string]: unknown
+}
+
+/**
+ * registerPage 可选：任务完成刷新。
+ * 页面 unregister 后自动失效，无需宿主自己管 window 事件。
+ */
+export type RegisterPageOptions = {
+  /** 与 hostContext.refresh 对齐，如 form_list / export_list */
+  refreshKey?: string
+  /** 当前页仍注册时，任务成功完成且 hostContext.refresh 匹配则调用 */
+  onRefresh?: (payload?: HostRefreshPayload) => void
+}
+
+/** 宿主 BFF bootstrap 响应（boot-admin GET /agent/bootstrap） */
+export type BootstrapResult = {
+  agent_token?: string
+  refresh_token?: string
+  /** Agent 前端 origin，由 BFF 下发，SDK 用于 iframe 地址 */
+  agent_web_origin?: string
+  integrations?: Record<string, unknown>
+  cached?: boolean
+  error?: string
+}
+
+export type HostInitOptions = {
+  /**
+   * Agent 前端 origin（可选）。
+   * 优先使用 bootstrap 返回的 `agent_web_origin`；未配置且 bootstrap 未返回时报错。
+   */
+  agentOrigin?: string
+  host?: string
+  /** 宿主 BFF bootstrap；返回 token + agent_web_origin */
+  bootstrap?: () => Promise<BootstrapResult>
+  /**
+   * 打开 Widget 前钩子（如强制重新 bootstrap / establish）。
+   * Hub 可复用缓存 JWT；推沙盒等业务 API 需要 establish，应在此刷新。
+   */
+  prepareOpenWidget?: () => Promise<void>
+  /** 获取 Agent JWT；未提供时由 bootstrap 缓存 token */
+  getToken?: () => Promise<string>
+  /**
+   * 按需读取宿主上下文（系统 / 名称 / 描述 / 菜单）。
+   * Hub 场景弹窗打开时会 `request-host-context`；优先走此回调，无需路由全局监测。
+   */
+  getHostContext?: () => HostPageContext | Promise<HostPageContext>
+  showHub?: boolean
+  onBootstrap?: (result: BootstrapResult) => void
+  onTaskComplete?: (payload: {
+    taskId: string
+    status: string
+    hostContext?: Record<string, unknown>
+    result?: string
+    apply?: Record<string, unknown>
+  }) => void
+  onAuthRequired?: () => void
+}