@fses/workbench-card

工作台卡片组件库，提供卡片注册表、渲染器、图表协议和图生组合卡片模式。组件库只承载 UI、类型和契约；PersonalWorkbench 的 API、store、问数和保存逻辑仍由宿主通过 bridge 注入。

宿主接入样式

使用运行时渲染器或图生组合卡片的宿主应用必须加载包样式：

import "@fses/workbench-card/styles.css";

如果宿主使用 Tailwind 构建源码别名，还需要把 packages/workbench-card/src/**/*.{vue,js,ts} 加进 Tailwind content。改动 content 后必须重启 dev server；否则 grid-cols-[...]、grid-rows-[...]、h-[...] 这类任意值布局类不会重新生成，真实浏览器里组合卡会在刷新后压缩或遮挡。包样式里已提供 workbench-reference-* 关键布局兜底，但宿主扫描源码仍能保证所有 Tailwind 视觉类完整生效。

图生组合卡片

图生卡片里常见的多区域看板已经沉淀为 WORKBENCH_COMPOSITE_CARD_PATTERNS，并登记到 CARD_REGISTRY 的 card.composite_cards 分类：

• card.composite.asset：资产与成本组合卡片
• card.composite.project：项目与效能组合卡片
• card.composite.ops：运维稳定组合卡片
• card.composite.security：安全合规组合卡片
• card.composite.businessMetricMatrix：业务指标矩阵组合卡片

这些组合卡片都使用 rendererKey: "customCanvas" 和 dataShape: "customCanvas"。推荐数据形态是：

{
  shape: "customCanvas",
  sourceLabel: "image",
  elements: [],
  nestedLayoutMode: "stack",
  nestedBlocks: [
    {
      id: "project-progress",
      title: "重点 IT 项目看板",
      kind: "list",
      visualKind: "progressList",
      dataBindingId: "binding-project-progress",
      dataBindingStatus: "business_input",
      dataBinding: {
        id: "binding-project-progress",
        status: "business_input",
        queryIntent: "查询重点 IT 项目进度",
        refreshApi: "/workbench/v2/documents/{workspaceId}/data-bindings/binding-project-progress/query"
      }
    }
  ]
}

布局原则：

• 源图比例优先：先按截图区域比例决定外层卡片大小，页面可以向下增长。
• 卡片内不放真实滚动条：内容不够放时调高父卡或内部行高，不靠内部滚动凑。
• 元素不能互相遮挡：子区优先使用 stack/grid，密集组合卡不要退成一堆绝对定位小条。
• 填满卡片内部高度：底部大空白通常先修内部 grid-rows、grid-auto-rows、h-full、min-h-0。

问数怎么触发

组合卡片本身不会直接请求数据。问数由宿主读取卡片或 nestedBlocks[] 上的 dataBinding.refreshApi 后触发：

1. 图生识别完成后，后端或宿主为可问数子卡生成 dataBindingId、queryIntent、refreshApi 和状态。
2. live compose 阶段由后端逐卡问数；页面刷新后的恢复场景由宿主 refresh watcher 对 ready/refreshed 绑定补一次真实刷新。
3. 失败或低召回时，状态保持 business_input / error / humanIntervention，页面在“待补业务口径”清单中显示入口。
4. 宿主页面需要提供固定可见的“补口径”编辑区：展示当前目标卡、补充示例、输入框和“补口径并问数”按钮，清单项只负责切换目标 binding。
5. 用户输入必须包含指标、表、字段、系统名或问法同义词等可查询线索，宿主把补充口径附加到 query 请求，再走同一个 dataBinding refresh。
6. 宿主应在所有图生绑定卡面显示状态：已问数、问数中、问数失败、待补口径 或 子卡需补充业务口径。
7. 只有真实 query 成功后才允许 setData/ready；OCR、截图预览和低召回候选只能保持视觉预览，不能伪装成已问数。

最常用入口：

import {
  CARD_REGISTRY,
  WORKBENCH_COMPOSITE_CARD_PATTERNS,
  compositeCardPatternById,
} from "@fses/workbench-card/registry";

CARD_REGISTRY 用于卡片库插入；WORKBENCH_COMPOSITE_CARD_PATTERNS 用于图生还原和文档说明；compositeCardPatternById() 用于按模式查布局、数据和问数契约。