@fses/workbench-app 0.1.0

package/dist/internal/personal-workbench/lib/workbenchLayout.d.ts

@@ -0,0 +1,174 @@
+/**
+ * @fileoverview 工作台布局归一化工具 - 统一处理逻辑栅格、叠卡修复和图片编排快照恢复。
+ * @author seadon
+ * @created 2026-05-17
+ */
+import type { BlockLayout, LayoutConfig, MaterializedBlock } from '@fses/workbench-app/types';
+export declare const LOGICAL_LAYOUT_COLUMNS = 100;
+export declare const LOGICAL_LAYOUT_MAX_ROWS = 999;
+export declare const WORKBENCH_ORGANIZATION_LOGICAL_SIZE: {
+    readonly banner: {
+        readonly w: 100;
+        readonly h: 16;
+    };
+    readonly group: {
+        readonly w: 100;
+        readonly h: 6;
+    };
+};
+export type ImageComposeSourceBox = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export declare const DEFAULT_LAYOUT_CONFIG: LayoutConfig;
+export declare const LAYOUT_SIZE_LIMITS: {
+    minCols: number;
+    minRows: number;
+    maxCols: number;
+    maxRows: number;
+};
+type LayoutLike = Pick<BlockLayout, 'x' | 'y' | 'w' | 'h'>;
+type ImageComposedBlockLike = {
+    id?: unknown;
+    title?: unknown;
+    layout: BlockLayout;
+    meta?: unknown;
+    source?: unknown;
+    data?: unknown;
+    renderer?: unknown;
+};
+export declare const IMAGE_SOURCE_METRIC_MIN_LOGICAL_ROWS = 13;
+export declare const IMAGE_STANDALONE_TEXT_NOTE_MIN_LOGICAL_ROWS = 10;
+export type RowInsertionLayoutResult = {
+    layouts: BlockLayout[];
+    preview: BlockLayout;
+    floatingLayout: BlockLayout;
+};
+export declare function defaultLayoutConfig(): LayoutConfig;
+export declare function clampNumber(value: number, min: number, max: number): number;
+export declare function normalizeLayoutConfig(value: unknown): LayoutConfig;
+export declare function normalizeGridHeight(value: unknown): 1 | 2 | 3;
+export declare function normalizeLegacyWidth(value: unknown): number;
+export declare function buildGridLayout(input: {
+    id: string;
+    x?: unknown;
+    y?: unknown;
+    w?: unknown;
+    h?: unknown;
+    minW?: unknown;
+    minH?: unknown;
+    maxW?: unknown;
+    maxH?: unknown;
+    static?: unknown;
+}, layoutConfig?: LayoutConfig): BlockLayout;
+export declare function sanitizeBlockLayout(value: unknown, id: string, layoutConfig?: LayoutConfig): BlockLayout;
+export declare function sortBlocksByLayout<T extends {
+    layout?: unknown;
+}>(blocks: T[]): T[];
+/**
+ * Recovers persisted image-composed risk summary rows before display-only canvas normalization.
+ * @param blocks - Persisted workbench blocks from saved workspace state.
+ * @returns Blocks with legacy split risk rows merged into one business-summary band when the signature is complete.
+ */
+export declare function recoverPersistedRiskSummaryRowsForDisplay<T extends Record<string, unknown>>(blocks: T[]): T[];
+/**
+ * Densifies persisted image-composed visual rows so screenshot cards use the full workbench canvas.
+ * @param blocks - Display blocks after risk-row recovery and logical normalization.
+ * @returns Blocks with loose same-row image panels spread to full width.
+ */
+export declare function normalizeImageComposedRowsForDisplay<T extends ImageComposedBlockLike>(blocks: T[]): T[];
+/**
+ * Applies image risk-summary business-band sizing after a block has been normalized to logical canvas coordinates.
+ * @param block - Logical-layout workbench block.
+ * @returns The same block, or a full-width risk-summary band when the block matches the persisted image pattern.
+ */
+export declare function normalizeRiskSummaryBandDisplayBlock<T extends Record<string, unknown> & {
+    layout: BlockLayout;
+}>(block: T): T;
+export declare function layoutOverlaps(left: LayoutLike, right: LayoutLike): boolean;
+export declare function layoutFitsGrid(layout: LayoutLike, cols: number, maxRows: number): boolean;
+export declare function isLayoutSlotFree(layout: LayoutLike, placed: LayoutLike[], cols: number, maxRows: number): boolean;
+export declare function resolveNonOverlappingLayout(layout: BlockLayout, placed: BlockLayout[], layoutConfig: LayoutConfig): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    i: string;
+    minW?: number;
+    minH?: number;
+    maxW?: number;
+    maxH?: number;
+    static?: boolean;
+};
+export declare function resolveNonOverlappingLayoutDuringDrag(layout: BlockLayout, placed: BlockLayout[], layoutConfig: LayoutConfig, previousLayout: BlockLayout): BlockLayout;
+/**
+ * Reorders a visual row when a moving card is dragged into an occupied row.
+ * @param layout - Moving card layout after pointer snapping.
+ * @param placed - Existing non-moving layouts.
+ * @param layoutConfig - Current display layout config.
+ * @returns Repacked layouts and moving-card preview, or null when no row insertion applies.
+ */
+export declare function resolveRowInsertionLayoutDuringDrag(layout: BlockLayout, placed: BlockLayout[], layoutConfig: LayoutConfig): RowInsertionLayoutResult | null;
+export declare function findFreeGridLayout(layout: BlockLayout, placed: BlockLayout[], layoutConfig: LayoutConfig): {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    i: string;
+    minW?: number;
+    minH?: number;
+    maxW?: number;
+    maxH?: number;
+    static?: boolean;
+};
+/**
+ * Checks whether an image customCanvas is a standalone text note with no child-card body.
+ * @param block - Candidate image-composed block.
+ * @returns True when a too-short source bbox would clip the note body.
+ */
+export declare function isStandaloneImageTextNoteLayoutBlock(block: unknown): boolean;
+/**
+ * Releases image previews that were wrongly persisted inside a parent whose source bbox does not contain them.
+ * @param blocks - Persisted image-composed blocks before display normalization.
+ * @returns Blocks with outside-source nested previews restored as top-level image cards.
+ */
+export declare function recoverImageNestedBlocksOutsideSourceParent<T extends ImageComposedBlockLike>(blocks: T[]): T[];
+/**
+ * Reads the original image-recognition bbox for top-level canvas placement.
+ * @param block - Candidate image-composed block.
+ * @returns Source-image bbox when recognition metadata is complete.
+ */
+export declare function imageComposeSourceBox(block: unknown): ImageComposeSourceBox | undefined;
+export declare function expandRowsForBlocks(layoutConfig: LayoutConfig, blocks: Array<{
+    layout?: unknown;
+    meta?: unknown;
+}>): {
+    rows: number;
+    cols: number;
+    maxCols: number;
+    maxRows: number;
+    isSquareCell: boolean;
+    layoutVersion: number;
+};
+export declare function migrateLegacyLayouts<T extends Record<string, unknown>>(blocks: T[], layoutConfig: LayoutConfig, createId: () => string): (T & {
+    layout: BlockLayout;
+})[];
+export declare function normalizeBlockLayoutToLogical<T extends {
+    id?: unknown;
+    layout?: unknown;
+    meta?: unknown;
+    source?: unknown;
+    data?: unknown;
+    renderer?: unknown;
+}>(block: T, layoutConfig?: LayoutConfig, fallbackId?: string): T & {
+    id: string;
+    layout: BlockLayout;
+};
+export declare function normalizeNonOverlappingLayouts<T extends Record<string, unknown>>(blocks: T[], layoutConfig: LayoutConfig, createId: () => string): Record<string, unknown>[];
+export declare function normalizeBlocksForDisplay(blocks: MaterializedBlock[], layoutConfig: LayoutConfig): {
+    displayBlocks: MaterializedBlock[];
+    displayRows: number;
+};
+export {};

package/dist/internal/personal-workbench/lib/workbenchManualReplacement.d.ts

@@ -0,0 +1,87 @@
+/**
+ * @fileoverview Workbench manual replacement diagnostics - builds view data for image-compose placeholder cards.
+ * @author seadon
+ * @created 2026-05-10
+ */
+import type { MaterializedBlock } from '@fses/workbench-app/types';
+import type { UpdateCardParams } from '@fses/workbench-app/canvas/api/types';
+export interface ManualReplacementView {
+    reason: string;
+    suggestedKind: string;
+    suggestedKindLabel: string;
+    suggestedCapabilityId?: string;
+    suggestedRendererKey?: string;
+    suggestedDataShape?: string;
+    suggestedRegistryTitle?: string;
+    suggestedCapabilityLabel?: string;
+    confidenceLabel: string;
+    regionLabel: string;
+}
+export interface CreateManualReplacementUpdateOptions {
+    requestId?: string;
+    title?: string;
+    overrideCapabilityId?: string;
+    baseSnapshotVersion?: number;
+    persist?: boolean;
+}
+export interface CreateManualReplacementBatchUpdateOptions {
+    baseSnapshotVersion?: number;
+    persist?: boolean;
+}
+export interface ManualReplacementBatchFailure {
+    block: MaterializedBlock;
+    reason: string;
+}
+/**
+ * Builds renderer-facing view data for a manual replacement placeholder block.
+ * @param block - Materialized Workbench block.
+ * @returns Manual replacement view model, or null for ordinary cards.
+ */
+export declare function manualReplacementViewForBlock(block: MaterializedBlock): ManualReplacementView | null;
+/**
+ * Builds canvas lifecycle params that replace an image-compose placeholder with a registered card.
+ * @param block - Placeholder block carrying manual replacement diagnostics.
+ * @param options - Optional request title, selected capability, optimistic version, and persistence mode.
+ * @returns Update-card params, or null when the block is not replaceable.
+ */
+export declare function createManualReplacementUpdateParams(block: MaterializedBlock, options?: CreateManualReplacementUpdateOptions): UpdateCardParams | null;
+/**
+ * Builds UI action params for replacing a manual image placeholder with the suggested or selected card.
+ * @param block - Placeholder block carrying manual replacement diagnostics.
+ * @param options - Optional optimistic version and user-selected capability.
+ * @returns Update-card params suitable for the runtime action, or null when unsupported.
+ */
+export declare function createManualReplacementActionParams(block: MaterializedBlock, options?: Pick<CreateManualReplacementUpdateOptions, 'baseSnapshotVersion' | 'overrideCapabilityId'>): UpdateCardParams | null;
+/**
+ * Filters canvas blocks down to image-compose placeholders that can be replaced.
+ * @param blocks - Canvas blocks from the current visible workbench.
+ * @returns Replaceable manual placeholder blocks in their existing canvas order.
+ */
+export declare function manualReplacementBlocks(blocks: MaterializedBlock[]): MaterializedBlock[];
+/**
+ * Builds replacement params for every replaceable image-compose placeholder.
+ * @param blocks - Candidate blocks from the current canvas.
+ * @param options - Optional starting optimistic version and persistence mode.
+ * @returns Ordered replaceCard params; only the first item carries the starting version guard.
+ */
+export declare function createManualReplacementBatchUpdateParams(blocks: MaterializedBlock[], options?: CreateManualReplacementBatchUpdateOptions): UpdateCardParams[];
+/**
+ * Builds UI action params for replacing all visible manual placeholders.
+ * @param blocks - Candidate blocks from the current canvas.
+ * @param options - Optional starting optimistic version.
+ * @returns Ordered replaceCard params using user-facing replacement titles.
+ */
+export declare function createManualReplacementBatchActionParams(blocks: MaterializedBlock[], options?: Pick<CreateManualReplacementBatchUpdateOptions, 'baseSnapshotVersion'>): UpdateCardParams[];
+/**
+ * Summarizes one placeholder replacement failure with title, position, and reason.
+ * @param block - Placeholder that failed replacement.
+ * @param reason - Failure reason returned by the runtime or persistence layer.
+ * @returns Human-readable failure summary that can be shown directly in a warning notice.
+ */
+export declare function summarizeManualReplacementFailure(block: MaterializedBlock, reason: string): string;
+/**
+ * Summarizes batch replacement failures with card titles for actionable feedback.
+ * @param failures - Failed placeholder replacements with reasons.
+ * @returns Human-readable per-card failure summary.
+ */
+export declare function summarizeManualReplacementBatchFailures(failures: ManualReplacementBatchFailure[]): string;

package/dist/internal/personal-workbench/lib/workbenchMetricChartDetail.d.ts

@@ -0,0 +1,75 @@
+/**
+ * @fileoverview 指标图表详情触发判断 - 限定 runtime_metric 图表卡片可查看点击项明细。
+ * @author seadon
+ * @created 2026-07-12
+ */
+import type { MaterializedBlock } from '@fses/workbench-app/types';
+export interface MetricChartDetailClickPayload {
+    block: MaterializedBlock;
+    bindingId: string;
+    componentType?: unknown;
+    data?: unknown;
+    dataIndex?: unknown;
+    name?: unknown;
+    value?: unknown;
+}
+export interface MetricBlockDetailPayload {
+    block: MaterializedBlock;
+    bindingId: string;
+}
+export interface MetricChartDetailAction {
+    bindingId: string;
+    categoryValue: unknown;
+    filters?: MetricChartDetailFilter[];
+    label: string;
+    metricName: string;
+}
+export interface MetricChartDetailStorageValue {
+    type: string;
+    value: unknown;
+}
+export interface MetricChartDetailFilterValue {
+    type?: string;
+    value: unknown;
+}
+export interface MetricChartDetailFilter {
+    fieldCode: string;
+    queryType: 'eq' | 'range' | number | string;
+    values: MetricChartDetailFilterValue[];
+}
+/**
+ * 判断卡片是否支持指标图表项详情。
+ * @param block - 当前点击的卡片块
+ * @returns runtime_metric 明确允许查看明细且 renderer 为图表时返回 true
+ */
+export declare function supportsMetricChartItemDetail(block: MaterializedBlock | null | undefined): boolean;
+/**
+ * 判断卡片是否支持打开指标明细。
+ * @param block - 当前卡片块
+ * @returns runtime_metric 绑定且明细开关均为 true 时返回 true
+ */
+export declare function supportsMetricDetailBlock(block: MaterializedBlock | null | undefined): boolean;
+/**
+ * 从图表点击参数中解析指标详情动作。
+ * @param payload - 图表点击 payload
+ * @returns 可执行详情动作；不满足条件时返回 null
+ */
+export declare function resolveMetricChartDetailAction(payload: MetricChartDetailClickPayload): MetricChartDetailAction | null;
+/**
+ * 从卡片级操作解析指标明细动作。
+ * @param payload - 卡片级指标明细 payload
+ * @returns 可执行详情动作；不满足 runtime_metric 条件时返回 null
+ */
+export declare function resolveMetricBlockDetailAction(payload: MetricBlockDetailPayload): MetricChartDetailAction | null;
+/**
+ * 从 ECharts value 中读取点击分类。
+ * @param value - ECharts 点击值
+ * @returns 分类原始值
+ */
+export declare function chartClickedCategoryFromMetricValue(value: unknown): unknown;
+/**
+ * 判断 renderer 是否能发出图表项点击。
+ * @param block - 卡片块
+ * @returns 图表 renderer 返回 true
+ */
+export declare function supportsChartItemClick(block: MaterializedBlock): boolean;

package/dist/internal/personal-workbench/lib/workbenchMetricDetailApi.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview 指标图表详情调用适配层 - 通过 run-agent 代理查询运行态事实明细。
+ * @author seadon
+ * @created 2026-07-12
+ */
+export interface WorkbenchMetricDetailColumn {
+    label?: string;
+    name: string;
+    type: string;
+}
+export interface WorkbenchMetricStorageValue {
+    type: string;
+    value: unknown;
+}
+export interface WorkbenchMetricFilterValue {
+    type?: string;
+    value: unknown;
+}
+export interface WorkbenchMetricDimensionFilter {
+    dimensionCode: string;
+    operator: 'EQ' | 'IN';
+    values: WorkbenchMetricStorageValue[];
+}
+export interface WorkbenchMetricFilter {
+    fieldCode: string;
+    queryType: 'eq' | 'range' | number | string;
+    values: WorkbenchMetricFilterValue[];
+}
+export interface WorkbenchMetricDrillPathSelection {
+    dimensionCode: string;
+    storageValue: WorkbenchMetricStorageValue;
+}
+export interface WorkbenchMetricDetailPageRequest {
+    workspaceId: string;
+    cardId: string;
+    bindingId: string;
+    metricName?: string;
+    categoryField?: string;
+    categoryValue: unknown;
+    filters?: WorkbenchMetricFilter[];
+    dimensionFilters?: WorkbenchMetricDimensionFilter[];
+    drillPath?: WorkbenchMetricDrillPathSelection[];
+    pageIndex: number;
+    pageSize: number;
+}
+export interface WorkbenchMetricDetailPageResult {
+    success: boolean;
+    title: string;
+    columns: WorkbenchMetricDetailColumn[];
+    rows: Array<Record<string, unknown>>;
+    pageIndex: number;
+    pageSize: number;
+    total: number;
+    hasMore?: boolean;
+    errorMessage?: string;
+}
+/**
+ * 查询指标图表点击项详情。
+ * @param request - 指标详情分页请求
+ * @returns 分页表格数据
+ */
+export declare function queryWorkbenchMetricDetailPage(request: WorkbenchMetricDetailPageRequest): Promise<WorkbenchMetricDetailPageResult>;

package/dist/internal/personal-workbench/lib/workbenchMetricFilterBinding.d.ts

@@ -0,0 +1,85 @@
+/**
+ * @fileoverview 工作台指标筛选绑定 - 读取推荐候选、匹配 FDE 组件并识别确认状态
+ * @author seadon
+ * @created 2026-07-13
+ */
+import type { CardRecommendationItem } from '@fses/workbench-app/types';
+import type { FdeFilterCatalogItem } from '@workbench-internal/fde-skill-cards/runtime/fdeSkillFilterBarBridge';
+export interface RuntimeMetricFilterCandidate {
+    fieldCode: string;
+    fieldName?: string;
+    dataCode?: string;
+    fieldType?: string;
+    operators: Array<number | string>;
+    source?: 'fact' | 'dimension';
+    semanticAliases?: string[];
+    valueDataType?: string;
+    valueType?: 'scalar' | 'array' | 'time_range' | 'typed_storage';
+}
+export interface MetricFilterBinding {
+    filterId: string;
+    fieldCode: string;
+    queryType: number | string;
+    dataCode?: string;
+    source?: 'fact' | 'dimension';
+    valueDataType?: string;
+    valueType?: 'scalar' | 'array' | 'time_range' | 'typed_storage';
+}
+export declare const METRIC_FILTER_CONFIG_REVIEWED_FLAG = "metricFilterConfigReviewed";
+/**
+ * 从指标执行返回对象中直接归一化筛选候选字段。
+ * @param value - 指标 execute 返回、工具结果或 dataBinding 包裹对象。
+ * @returns data.query_filters 转换后的候选字段。
+ */
+export declare function metricFilterCandidatesFromPayload(value: unknown): RuntimeMetricFilterCandidate[];
+/**
+ * 从推荐项读取指标可筛选字段候选。
+ * @param item - 卡片推荐项
+ * @returns 安全候选摘要
+ */
+export declare function metricFilterCandidatesFromItem(item: CardRecommendationItem | null): RuntimeMetricFilterCandidate[];
+/**
+ * 从推荐项读取已保存的筛选绑定。
+ * @param item - 卡片推荐项
+ * @returns 已归一化绑定
+ */
+export declare function metricFilterBindingsFromItem(item: CardRecommendationItem | null): MetricFilterBinding[];
+/**
+ * 判断推荐项是否属于指标服务或指标卡片。
+ * @param item - 卡片推荐项
+ * @returns 指标相关推荐返回 true
+ */
+export declare function isMetricRecommendationItem(item: CardRecommendationItem | null): boolean;
+/**
+ * 判断指标筛选配置是否已由插入前弹窗确认。
+ * @param item - 卡片推荐项
+ * @returns 已确认返回 true
+ */
+export declare function hasReviewedMetricFilterConfig(item: CardRecommendationItem | null): boolean;
+/**
+ * 判断推荐项是否尚未完成插卡前筛选绑定确认。
+ * @param item - 卡片推荐项
+ * @returns 有候选且所有配置层都缺少绑定数组时返回 true
+ */
+export declare function hasUnreviewedMetricFilterBindings(item: CardRecommendationItem | null): boolean;
+/**
+ * 返回可供 FDE 筛选组件绑定的指标字段。
+ * @param filter - FDE 筛选组件
+ * @param candidates - 指标候选字段
+ * @returns 时间筛选只返回时间字段；其它筛选返回接口提供的候选字段
+ */
+export declare function compatibleMetricFilterCandidates(filter: FdeFilterCatalogItem, candidates: RuntimeMetricFilterCandidate[]): RuntimeMetricFilterCandidate[];
+/**
+ * 按当前 FDE 控件语义和指标字段合同选择本次刷新使用的操作符。
+ * @param filter - FDE 筛选组件
+ * @param candidate - 指标字段候选
+ * @returns 平台 query_type 或别名
+ */
+export declare function metricFilterBindingQueryTypeForCandidate(filter: FdeFilterCatalogItem, candidate: RuntimeMetricFilterCandidate): number | string;
+/**
+ * 按字段编码、语义别名和唯一兼容候选的顺序自动生成绑定。
+ * @param filter - FDE 筛选组件
+ * @param candidates - 指标候选字段
+ * @returns 唯一可确定的绑定；存在歧义时返回 null
+ */
+export declare function autoMetricFilterBinding(filter: FdeFilterCatalogItem, candidates: RuntimeMetricFilterCandidate[]): MetricFilterBinding | null;

package/dist/internal/personal-workbench/lib/workbenchMetricFilterLinkage.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview 工作台指标筛选联动 - 协调 FDE 完整筛选状态与指标卡刷新
+ * @author seadon
+ * @created 2026-07-13
+ */
+import type { MaterializedBlock } from '@fses/workbench-app/types';
+import type { FdeFilterBarEvent } from '@workbench-internal/fde-skill-cards/runtime/fdeSkillFilterBarBridge';
+import { type MetricFilterBinding } from './workbenchMetricFilterBinding';
+/**
+ * 创建页面级指标筛选刷新协调器。
+ * @param input - 当前卡片读取函数和单卡刷新函数
+ * @returns FDE 事件处理、单卡刷新、空闲等待和释放方法
+ */
+export declare function createWorkbenchMetricFilterLinkage(input: {
+    blocks: () => MaterializedBlock[];
+    refresh: (cardId: string, bindingId: string, values: Record<string, unknown>, metricFilterBindings?: MetricFilterBinding[]) => Promise<unknown>;
+}): {
+    /** 接收 FDE submit/reset 的完整值快照并刷新受影响的指标卡。 */
+    handle(event: Pick<FdeFilterBarEvent, "action" | "values"> & Partial<Pick<FdeFilterBarEvent, "filters">>): void;
+    /** 使用最近一次完整筛选状态刷新指定卡片。 */
+    refreshCard(cardId: string): Promise<void>;
+    /** 返回最近一次 FDE 完整筛选状态的克隆。 */
+    currentValues: () => Record<string, unknown>;
+    metricFilterBindingsForCard(cardId: string): MetricFilterBinding[] | undefined;
+    hasCurrentValues: () => boolean;
+    /** 等待当前所有卡片刷新及其排队刷新完成。 */
+    idle: () => Promise<void>;
+    /** 释放页面级协调状态。 */
+    dispose(): void;
+};

package/dist/internal/personal-workbench/lib/workbenchPendingPatch.d.ts

@@ -0,0 +1,54 @@
+/**
+ * @fileoverview 工作台 pending 改卡工具 - 保存多候选改卡意图并解析用户续接选择。
+ * @author seadon
+ * @created 2026-06-08
+ */
+import type { MaterializedBlock, PatchPlan, PendingWorkbenchPatch, WorkbenchPatchIntent } from '@fses/workbench-app/types';
+import type { UpdateCardParams } from '@fses/workbench-app/canvas/api/types';
+export type PendingPatchContinuation = {
+    kind: 'single';
+    blockId: string;
+} | {
+    kind: 'all';
+    blockIds: string[];
+} | {
+    kind: 'cancel';
+} | {
+    kind: 'unknown';
+    reason: string;
+};
+export interface BuildPendingWorkbenchPatchInput {
+    sourceTurnId: string;
+    userInstruction: string;
+    patchPlan: PatchPlan;
+    blocks: MaterializedBlock[];
+    baseSnapshotVersion: number;
+    now?: string;
+}
+/**
+ * 从多候选 PatchPlan 构建 pending 改卡状态。
+ * @param input - pending 改卡构建参数
+ * @returns pending 改卡状态；非多候选计划返回 null
+ */
+export declare function buildPendingWorkbenchPatch(input: BuildPendingWorkbenchPatchInput): PendingWorkbenchPatch | null;
+/**
+ * 解析用户对 pending 改卡候选的续接选择。
+ * @param text - 用户输入文本
+ * @param pending - 当前 pending 改卡状态
+ * @returns 解析后的续接动作
+ */
+export declare function parsePendingPatchContinuation(text: string, pending: PendingWorkbenchPatch): PendingPatchContinuation;
+/**
+ * 格式化 pending 候选卡片摘要。
+ * @param pending - 当前 pending 改卡状态
+ * @returns 用于聊天提示的候选摘要文本
+ */
+export declare function pendingPatchCandidateSummary(pending: PendingWorkbenchPatch): string;
+/**
+ * 将 pending 改卡意图转换为画布生命周期更新参数。
+ * @param intent - pending 改卡中保留的原始操作意图
+ * @param blockId - 用户选中的目标卡片 ID
+ * @param baseSnapshotVersion - 可选的画布快照版本保护
+ * @returns 画布 updateCard 参数
+ */
+export declare function patchIntentToUpdateCardParams(intent: WorkbenchPatchIntent, blockId: string, baseSnapshotVersion?: number): UpdateCardParams;

package/dist/internal/personal-workbench/lib/workbenchRemoteClient.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview 工作台远端客户端 - 封装 snapshot 与 layout 持久化 HTTP 调用
+ * @author seadon
+ * @created 2026-05-10
+ */
+import type { BlockLayout, LayoutConfig, RoleId, WorkbenchSnapshot } from '@fses/workbench-app/types';
+export interface WorkbenchRemoteContext {
+    workspaceId: string;
+    userId: string;
+    roleId: RoleId | string;
+    tenantId?: string;
+    appId?: string;
+}
+export interface WorkbenchRemoteClientOptions {
+    baseUrl?: string;
+}
+export interface WorkbenchRemoteSaveLayoutPayload {
+    baseVersion: number;
+    layoutVersion?: number;
+    layout: BlockLayout[];
+    layoutConfig?: LayoutConfig;
+    visualConfig?: WorkbenchSnapshot['visualConfig'] | null;
+}
+export interface WorkbenchRemoteSaveSnapshotPayload {
+    baseVersion: number;
+    persistenceFallbackReason?: string;
+    persistenceFallbackSummary?: Record<string, unknown>;
+    snapshot: WorkbenchSnapshot;
+}
+/**
+ * 创建工作台远端持久化客户端。
+ * @param options - 远端客户端配置。
+ * @returns 工作台快照读取与保存客户端。
+ */
+export declare function createWorkbenchRemoteClient({ baseUrl }?: WorkbenchRemoteClientOptions): {
+    fetchSnapshot(context: WorkbenchRemoteContext): Promise<WorkbenchSnapshot>;
+    saveLayout(context: WorkbenchRemoteContext, payload: WorkbenchRemoteSaveLayoutPayload): Promise<WorkbenchSnapshot>;
+    saveSnapshot(context: WorkbenchRemoteContext, payload: WorkbenchRemoteSaveSnapshotPayload): Promise<WorkbenchSnapshot>;
+};