@fses/workbench-app 0.2.0 → 0.2.2

package/node_modules/@fses/workbench-card/src/types/block.ts

@@ -0,0 +1,2496 @@
+/**
+ * @fileoverview 个人工作台区块、对话和快照协议类型定义。
+ * @author seadon
+ * @created 2026-05-06
+ */
+
+import type { ProtocolConfigPayload, ProtocolDataPayload, RendererType } from './echartsProtocol';
+
+export type RoleId =
+  | 'ceo'
+  | 'cfo'
+  | 'sales_leader'
+  | 'cto'
+  | 'it_admin'
+  | 'coo'
+  | 'chro'
+  | 'risk_leader'
+  | 'regional_gm';
+
+export type IntentActionType = 'append' | 'prepend' | 'replace_target' | 'replace_all' | 'unknown';
+export type IntentPlacement = 'top' | 'bottom' | 'before_target' | 'after_target';
+export type IntentScope = 'single' | 'group' | 'all';
+export type WorkbenchIntentChannel = 'card_generation' | 'card_patch' | 'answer' | 'submit';
+export type SemanticOperation =
+  | 'generate_cards'
+  | 'patch_blocks'
+  | 'delete_card'
+  | 'clear_canvas'
+  | 'regenerate_target'
+  | 'regenerate_all'
+  | 'answer'
+  | 'submit'
+  | 'unknown';
+export type CardPatchOperation =
+  | 'patch_attributes'
+  | 'patch_style'
+  | 'patch_echarts'
+  | 'patch_mixed'
+  | 'patch_common_style'
+  | 'delete_card'
+  | 'clear_canvas'
+  | 'regenerate_target'
+  | 'regenerate_all';
+export type CardPatchEditMode = 'style' | 'content' | 'renderer' | 'layout' | 'data' | 'structure' | 'text';
+export type CardMutationOperation =
+  | 'create_card'
+  | 'update_card'
+  | 'replace_card'
+  | 'delete_card'
+  | 'resize_card'
+  | 'reorder_card'
+  | 'clear_canvas'
+  | 'rollback_transaction';
+export type MutationTransactionSource = 'ai_card' | 'manual_config' | 'system_layout';
+export type MutationStepKind =
+  | 'create_block'
+  | 'update_style'
+  | 'update_content'
+  | 'update_renderer'
+  | 'update_layout'
+  | 'delete_block'
+  | 'expand_canvas'
+  | 'rollback_step';
+export type AssistantPersonaKey = 'warm' | 'professional' | 'reserved';
+
+export interface AssistantPersonaPayload {
+  key: AssistantPersonaKey;
+  label: string;
+  shortDescription: string;
+  prompt: string;
+}
+
+export type BlockType = 'display' | 'form' | 'survey' | 'action' | 'workflow' | 'report';
+
+export type DisplaySubType =
+  | 'metric'
+  | 'chart'
+  | 'weather'
+  | 'calendar'
+  | 'table'
+  | 'ranking'
+  | 'insight'
+  | 'taskSummary'
+  | 'reportSummary'
+  | 'embed'
+  | 'fdeCustom'
+  | 'customCanvas';
+
+export type FormSubType = 'inlineForm' | 'draftForm' | 'approvalForm' | 'exceptionForm';
+export type SurveySubType = 'quickSurvey' | 'stepSurvey' | 'investigationSurvey';
+export type ActionSubType = 'quickAction' | 'bulkAction' | 'automationTrigger';
+export type WorkflowSubType = 'approvalFlow' | 'taskFlow' | 'timeline' | 'statusBoard';
+export type ReportSubType = 'periodicReport' | 'boardPack' | 'managementBrief';
+
+export type BlockSubType =
+  | DisplaySubType
+  | FormSubType
+  | SurveySubType
+  | ActionSubType
+  | WorkflowSubType
+  | ReportSubType;
+
+export type BlockActionType =
+  | 'refresh'
+  | 'submit'
+  | 'execute'
+  | 'open'
+  | 'generate'
+  | 'assign'
+  | 'approve'
+  | 'reject'
+  | 'export';
+
+export interface BlockLayout {
+  i: string;
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+  minW?: number;
+  minH?: number;
+  maxW?: number;
+  maxH?: number;
+  static?: boolean;
+}
+
+export interface WorkbenchGridLayoutNode extends BlockLayout {
+  parentId?: string;
+  children?: WorkbenchGridLayoutNode[];
+}
+
+export interface WorkbenchLayoutV4 {
+  version: 4;
+  cols: number;
+  rowHeight?: number | 'auto';
+  gap: number;
+  meta?: Record<string, unknown>;
+  nodes: WorkbenchGridLayoutNode[];
+}
+
+export interface BlockIntent {
+  scene: string;
+  bizIntent: string;
+  roleTemplate: string;
+}
+
+export interface BlockSource {
+  sourceType: string;
+  service: string;
+  resourceKey: string;
+  params?: Record<string, unknown>;
+}
+
+export interface BlockRenderer {
+  engine: string;
+  rendererKey: string;
+  preset?: string;
+  displayMode?: string;
+}
+
+export interface BlockState {
+  mode: 'preview' | 'final';
+  status:
+    | 'loading'
+    | 'ready'
+    | 'error'
+    | 'draft'
+    | 'submitted'
+    | 'running'
+    | 'needs_confirmation'
+    | 'confirmed'
+    | 'executing'
+    | 'failed'
+    | 'cancelled';
+  refreshable: boolean;
+  cacheable: boolean;
+  drilldown?: boolean;
+  editable?: boolean;
+  submitable?: boolean;
+}
+
+export interface WorkbenchAction {
+  id: string;
+  actionType: BlockActionType | string;
+  label: string;
+  service?: string;
+  resourceKey?: string;
+  payloadTemplate?: Record<string, unknown>;
+}
+
+export interface IntentTargetSelector {
+  byId?: string[];
+  byTitle?: string[];
+  byTitleKeyword?: string[];
+  byBlockType?: BlockType[];
+  bySubType?: Array<BlockSubType | string>;
+  byBizIntent?: string[];
+  byTitleKeywords?: string[];
+  scope?: IntentScope;
+}
+
+export interface IntentConstraint {
+  placement?: IntentPlacement;
+  count?: number;
+  preferredLayout?: 'cards' | 'dashboard';
+}
+
+export interface IntentConfidence {
+  score: number;
+  matched: string[];
+  missing: string[];
+}
+
+export interface UserIntent {
+  rawUtterance: string;
+  literalObject?: string;
+  actualIntent?: string;
+  intentType?: string;
+  routeChannel?: WorkbenchIntentChannel;
+  selectedSkillId?: string;
+  operation?: SemanticOperation;
+  targetScope?: 'all' | 'selected' | 'named' | 'left_canvas' | 'current_workspace' | 'unknown';
+  safety?: {
+    riskLevel: 'low' | 'medium' | 'high';
+    requiresPreview: boolean;
+    requiresConfirmation: boolean;
+    reasons: string[];
+  };
+  analogyMode?: boolean;
+  domain?: 'enterprise_workbench' | 'outside_enterprise_workbench' | 'unknown';
+  requestedCapability?: string[];
+  contentIntent: string[];
+  actionType: IntentActionType;
+  targetSelector?: IntentTargetSelector;
+  runtimeCapabilityMutation?: RuntimeCapabilityMutation;
+  constraints?: IntentConstraint;
+  confidence: IntentConfidence;
+}
+
+export interface CanvasApplyAction {
+  type: Exclude<IntentActionType, 'unknown'> | 'noop';
+  scope: IntentScope;
+  placement?: IntentPlacement;
+  targetSelectors?: IntentTargetSelector[];
+}
+
+export interface CanvasApplyPolicy {
+  keepOrder: boolean;
+  reindexOrder: boolean;
+  keepPinnedBlocks?: boolean;
+}
+
+export interface WorkbenchDebugTrace {
+  rawUtterance: string;
+  userSemantics: string[];
+  requestedAction: string;
+  matchedCapabilities: string[];
+  missingCapabilities: string[];
+  nextSupportSuggestion: string[];
+}
+
+export type TurnTraceCategory = 'semantic' | 'proposal' | 'runtime';
+export type ConversationTurnStatus =
+  | 'streaming'
+  | 'ready'
+  | 'preview_failed'
+  | 'insert_failed'
+  | 'submit_failed'
+  | 'submitted'
+  | 'error'
+  | 'cancelled'
+  | 'applied'
+  | 'reverted';
+export type WorkbenchTurnMode = WorkbenchIntentChannel;
+export type TraceBlockType = 'thought' | 'json' | 'code' | 'file_change' | 'summary';
+export type TraceAttachmentType = 'json' | 'code' | 'file_change' | 'text';
+export type WorklogStageText =
+  | '正在思考'
+  | '正在计划'
+  | '正在执行'
+  | '正在收尾'
+  // Legacy values may exist in persisted turns; new runtime code should not emit them.
+  | '正在读取'
+  | '正在回复'
+  | '正在展示'
+  | '正在生成预览'
+  | '等待确认'
+  ;
+export type ConfirmationScope = 'layout' | 'preview' | 'insert' | 'patch' | 'submit' | 'execute' | 'high_risk_action';
+export type ConfirmationStatus =
+  | 'draft'
+  | 'needs_confirmation'
+  | 'confirmed'
+  | 'executing'
+  | 'submitted'
+  | 'applied'
+  | 'failed'
+  | 'cancelled';
+
+export interface ConversationTraceAttachment {
+  type: TraceAttachmentType;
+  title: string;
+  content: string;
+  collapsed?: boolean;
+}
+
+export interface ConversationConfirmation {
+  scope: ConfirmationScope;
+  status: ConfirmationStatus;
+  reason?: string;
+  summary?: string;
+  questions?: string[];
+  missingFields?: string[];
+}
+
+export type ConversationTaskKind =
+  | 'data_action'
+  | 'data_query'
+  | 'metric_query'
+  | 'attachment_analysis'
+  | 'approval_analysis'
+  | 'workbench_card'
+  | 'general_answer';
+
+export type ConversationTaskStatus =
+  | 'intent_detected'
+  | 'collecting_fields'
+  | 'waiting_confirmation'
+  | 'confirmed'
+  | 'executing'
+  | 'success'
+  | 'failed'
+  | 'cancelled'
+  | 'topic_shifted';
+
+export interface ConversationTaskField {
+  code: string;
+  name: string;
+  value?: unknown;
+  type?: string;
+  required?: boolean;
+  source?: string;
+  displayValue?: string;
+}
+
+export interface ConversationTaskError {
+  code?: string;
+  message: string;
+  retryable?: boolean;
+}
+
+export interface ConversationTaskClarificationOption {
+  index: number;
+  label: string;
+  description?: string;
+  appId?: string;
+  modelCode?: string;
+  metricCode?: string;
+  fieldCode?: string;
+  matchEvidence?: string;
+  score?: number;
+  source?: string;
+}
+
+export interface ConversationTaskState {
+  taskId: string;
+  turnId?: string;
+  conversationId?: string;
+  taskKind: ConversationTaskKind;
+  status: ConversationTaskStatus;
+  title: string;
+  fields?: ConversationTaskField[];
+  missingFields?: ConversationTaskField[];
+  confirmationRequired?: boolean;
+  allowedConfirmPhrases?: string[];
+  clarificationOptions?: ConversationTaskClarificationOption[];
+  confirmedSelection?: ConversationTaskClarificationOption;
+  executionScope?: {
+    tenantId?: string;
+    appId?: string;
+  };
+  lastError?: ConversationTaskError;
+  resultSummary?: string;
+  createdAt?: string;
+  updatedAt?: string;
+  payload?: Record<string, unknown>;
+}
+
+export interface PreviewLayoutItem extends BlockLayout {}
+
+export interface LayoutDraftPlaceholderBlock {
+  id: string;
+  title: string;
+  role: 'primary' | 'secondary' | 'supporting';
+  suggestedType: string;
+  density: 'thumbnail' | 'compact' | 'standard' | 'expanded' | 'dashboard';
+  layout: PreviewLayoutItem;
+  placeholderText?: string;
+}
+
+export interface LayoutDraft {
+  draftId: string;
+  baseSnapshotVersion: number;
+  layoutConfig: LayoutConfig;
+  sourceTurnId: string;
+  status: 'draft' | 'needs_confirmation' | 'confirmed' | 'rejected' | 'superseded';
+  intentSummary: string;
+  layoutReasoning: string[];
+  constraints: {
+    hard: string[];
+    soft: string[];
+  };
+  placeholderBlocks: LayoutDraftPlaceholderBlock[];
+  conflicts?: Array<{
+    type: string;
+    message: string;
+    recoverable: boolean;
+  }>;
+  createdAt: string;
+}
+
+export interface PreviewSnapshotDraft {
+  draftId: string;
+  layoutDraftId?: string;
+  version?: number;
+  parentDraftId?: string;
+  supersedesDraftId?: string;
+  targetArtifactId?: string;
+  changeRequest?: string;
+  status?: 'draft' | 'preview_ready' | 'applied' | 'superseded' | 'failed';
+  baseSnapshotVersion: number;
+  layoutConfig: LayoutConfig;
+  nextBlocks: MaterializedBlock[];
+  changedBlockIds: string[];
+  insertedBlockIds: string[];
+  removedBlockIds: string[];
+  createdAt: string;
+}
+
+export interface ConversationGroupSummary {
+  id: string;
+  title: string;
+  updatedAt: string;
+}
+
+export interface ConversationTurnTraceItem {
+  id: string;
+  category: TurnTraceCategory;
+  title: string;
+  detail: string;
+  humanReadable: string;
+  status: 'done' | 'running' | 'info';
+  createdAt: string;
+  blockType?: TraceBlockType;
+  collapsed?: boolean;
+  attachments?: ConversationTraceAttachment[];
+  rawPayload?: string;
+}
+
+export type ConversationReturnKind =
+  | 'start'
+  | 'status'
+  | 'process'
+  | 'action'
+  | 'conclusion'
+  | 'data'
+  | 'preview'
+  | 'confirmation'
+  | 'error'
+  | 'debug'
+  | 'usage';
+
+export type QueryTraceStage =
+  | 'question_understanding'
+  | 'memory_candidates'
+  | 'semantic_matching'
+  | 'clarification'
+  | 'query_planning'
+  | 'query_execution'
+  | 'conclusion_evidence';
+
+export type QueryTraceVisibility =
+  | 'current_only'
+  | 'history_summary'
+  | 'technical_detail';
+
+export interface QueryTraceMetric {
+  name: string;
+  definition?: string;
+  matchSource?: string;
+  source?: string;
+  score?: number;
+}
+
+export interface QueryTraceMatch extends QueryTraceMetric {}
+
+export interface QueryTraceMemoryCandidate {
+  id?: string;
+  title: string;
+  content: string;
+  type?: string;
+  scope: string;
+  confidence: number;
+  layerPath: string[];
+  evidenceRefs: string[];
+  candidateOnly: boolean;
+  source?: string;
+  reason?: string;
+}
+
+export interface QueryTraceMemorySkipped {
+  id: string;
+  title: string;
+  reason: string;
+}
+
+export interface QueryTraceExecutionSummary {
+  rowCount: number;
+  fieldCount: number;
+  fields: string[];
+  keyStats: Array<{ label: string; value: string; evidenceRef?: string }>;
+  sampleRows: Array<Record<string, unknown>>;
+  limitations: string[];
+}
+
+export interface QueryTraceRelationScope {
+  primaryModels: string[];
+  lockedModels: string[];
+  relatedModels: string[];
+  joins: string[];
+  relationEdges: string[];
+}
+
+export type QueryTraceRelationDiagnosticActionKind =
+  | 'complete_field_mapping'
+  | 'complete_trusted_join'
+  | 'complete_field_inventory'
+  | 'confirm_model_scope'
+  | 'complete_metric_dimension';
+
+export interface QueryTraceRelationDiagnosticAction {
+  kind: QueryTraceRelationDiagnosticActionKind;
+  label: string;
+  payload?: Record<string, unknown>;
+}
+
+export interface QueryTraceRelationDiagnostic {
+  code: string;
+  severity: 'info' | 'warn' | 'block';
+  message: string;
+  evidence?: string[];
+  suggestedAction?: string;
+  action?: QueryTraceRelationDiagnosticAction;
+}
+
+export interface QueryTraceMemoryCapturePrompt {
+  title: string;
+  content: string;
+  confirmLabel: string;
+  dismissLabel: string;
+  status: 'draft' | 'candidate_created' | 'dismissed';
+}
+
+export interface QueryTraceSemanticQueryIr {
+  ok?: boolean;
+  compiledSqlAvailable?: boolean;
+  compiledSqlHidden?: boolean;
+  rootModel?: string;
+  selectedModels?: string[];
+  selectedFields?: string[];
+  trustedJoins?: string[];
+  blockers?: string[];
+  limitations?: string[];
+}
+
+export interface QueryTraceDetails {
+  intent?: string;
+  memoryCandidates?: QueryTraceMemoryCandidate[];
+  memorySkipped?: QueryTraceMemorySkipped[];
+  memoryConflicts?: QueryTraceMemorySkipped[];
+  memoryCapturePrompt?: QueryTraceMemoryCapturePrompt;
+  metrics?: QueryTraceMetric[];
+  dimensions?: Array<string | QueryTraceMatch>;
+  filters?: Array<string | QueryTraceMatch>;
+  ontologyAssets?: string[];
+  ambiguities?: Array<{ field: string; options: string[]; reason: string }>;
+  queryLogic?: string[];
+  executionSummary?: QueryTraceExecutionSummary;
+  relationScope?: QueryTraceRelationScope;
+  relationDiagnostics?: QueryTraceRelationDiagnostic[];
+  semanticQueryIr?: QueryTraceSemanticQueryIr;
+  evidenceCards?: Array<{ id: string; title: string; summary: string; kind: 'data' | 'semantic' | 'limitation' }>;
+  technicalDetails?: Record<string, unknown>;
+}
+
+export interface QueryTracePayload {
+  stage: QueryTraceStage;
+  summary: string;
+  details: QueryTraceDetails;
+  evidenceRefs?: string[];
+}
+
+export type ConversationProcessStatus = 'running' | 'done' | 'error';
+export type ConversationProcessCollapseSource = 'auto' | 'user';
+export type ConversationProcessInvocationKind = 'tool' | 'skill';
+
+export interface ConversationProcessInvocation {
+  id: string;
+  kind: ConversationProcessInvocationKind;
+  name: string;
+  title: string;
+  status: ConversationProcessStatus;
+  collapsed: boolean;
+  inputSummary?: string;
+  resultSummary?: string;
+  summary?: string;
+  durationMs?: number;
+  startedAt?: string;
+  completedAt?: string;
+  eventId?: string;
+  eventCode?: string;
+  technicalDetail?: Record<string, unknown>;
+}
+
+export interface ConversationProcessGroup {
+  id: string;
+  title: string;
+  summary?: string;
+  status: ConversationProcessStatus;
+  collapsed: boolean;
+  collapseSource?: ConversationProcessCollapseSource;
+  startedAt?: string;
+  completedAt?: string;
+  eventId?: string;
+  eventCode?: string;
+  invocations: ConversationProcessInvocation[];
+}
+
+export interface ConversationReturnItem {
+  id: string;
+  kind: ConversationReturnKind;
+  title: string;
+  summary: string;
+  createdAt: string;
+  status?: 'running' | 'done' | 'info' | 'error';
+  collapsed?: boolean;
+  payloadLabel?: string;
+  payload?: unknown;
+  eventId?: string;
+  eventCode?: string;
+  seq?: number;
+  phase?: ProductStreamPhase;
+  intent?: WorkbenchIntentChannel;
+  parentEventId?: string;
+  streamType?: 'process' | 'action' | 'artifact' | 'final' | 'usage';
+  streamDone?: boolean;
+  traceStage?: QueryTraceStage;
+  traceVisibility?: QueryTraceVisibility;
+  queryTrace?: QueryTracePayload;
+  technicalDetail?: Record<string, unknown>;
+}
+
+export interface StreamActionItem {
+  id: string;
+  eventId?: string;
+  eventCode?: string;
+  seq: number;
+  phase?: ProductStreamPhase;
+  title: string;
+  detail?: string;
+  tool?: string;
+  status: 'running' | 'done' | 'error' | 'info';
+  durationMs?: number;
+  technicalDetail?: Record<string, unknown>;
+  createdAt: string;
+}
+
+export interface ConversationTurn {
+  id: string;
+  conversationId?: string;
+  title?: string;
+  mode: WorkbenchTurnMode;
+  intentChannel: WorkbenchIntentChannel;
+  userPrompt: string;
+  assistantStreamingText: string;
+  assistantFinalText: string;
+  assistantConclusion: string;
+  planResult?: PlanResponse;
+  layoutDraft?: LayoutDraft;
+  previewDraft?: PreviewSnapshotDraft;
+  rollbackSnapshot?: WorkbenchSnapshot;
+  mutationTransaction?: MutationTransaction;
+  traceItems: ConversationTurnTraceItem[];
+  returnItems: ConversationReturnItem[];
+  streamActions?: StreamActionItem[];
+  confirmation?: ConversationConfirmation;
+  taskStates?: ConversationTaskState[];
+  worklogStartedAt?: string;
+  worklogEndedAt?: string;
+  worklogStageText?: WorklogStageText;
+  worklogStageDetail?: string;
+  worklogStageVisible?: boolean;
+  worklogCollapsed?: boolean;
+  finalContentVisible?: boolean;
+  pendingPatch?: PendingWorkbenchPatch | null;
+  processCollapsed?: boolean;
+  processCollapseSource?: ConversationProcessCollapseSource;
+  processGroups?: ConversationProcessGroup[];
+  status: ConversationTurnStatus;
+  createdAt: string;
+  updatedAt: string;
+  error?: string;
+  suppressErrorDisplay?: boolean;
+  collapsed?: boolean;
+  deepAgentSubmission?: {
+    idempotencyKey: string;
+    runId?: string;
+    threadId?: string;
+    queuePosition?: number;
+    status: 'submitting' | 'pending' | 'active' | 'retry_waiting' | 'accepted';
+    retryCount?: number;
+    retryKind?: 'queue_full' | 'migration' | 'legacy_active' | 'network' | 'unknown';
+  };
+}
+
+export type CardDataTaskStatus =
+  | 'pending'
+  | 'querying'
+  | 'confirming'
+  | 'empty'
+  | 'bound'
+  | 'failed'
+  | 'config_required';
+
+export type CardDataTaskConfirmationType =
+  | 'semantic_model'
+  | 'join_path'
+  | 'metric_subject'
+  | 'filter';
+
+export interface WorkbenchCardDataTaskState {
+  taskId: string;
+  conversationId?: string;
+  workspaceId?: string;
+  capabilityId: string;
+  rendererKey?: string;
+  dataShape?: string;
+  title?: string;
+  businessQuestion: string;
+  status: CardDataTaskStatus;
+  targetBlockId?: string;
+  confirmationPayload?: Record<string, unknown>;
+  error?: { code: string; message: string };
+  updatedAt: string;
+}
+
+export type CardDataTaskEvent =
+  | {
+      type: 'card_data_task_started';
+      turnId: string;
+      taskId: string;
+      capabilityId: string;
+      title?: string;
+      targetBlockId?: string;
+      status: 'pending';
+    }
+  | {
+      type: 'card_data_task_progress';
+      turnId: string;
+      taskId: string;
+      stage: 'semantic' | 'sql_plan' | 'execute' | 'project';
+      status: 'querying';
+      summary?: string;
+    }
+  | {
+      type: 'card_data_task_confirmation';
+      turnId: string;
+      taskId: string;
+      confirmationType: CardDataTaskConfirmationType;
+      options: Array<Record<string, unknown>>;
+      status: 'confirming';
+      message?: string;
+    }
+  | {
+      type: 'card_data_task_empty';
+      turnId: string;
+      taskId: string;
+      reason: string;
+      evidence?: Record<string, unknown>;
+      status: 'empty';
+    }
+  | {
+      type: 'card_data_task_bound';
+      turnId: string;
+      taskId: string;
+      blockId: string;
+      changedBlockIds: string[];
+      status: 'bound';
+    }
+  | {
+      type: 'card_data_task_config_required';
+      turnId: string;
+      taskId: string;
+      reason: string;
+      status: 'config_required';
+    }
+  | {
+      type: 'card_data_task_failed';
+      turnId: string;
+      taskId: string;
+      reason: string;
+      retryable: boolean;
+      status: 'failed';
+    };
+
+export type PlanningDisplayStepKind =
+  | 'understanding'
+  | 'asset_selection'
+  | 'execution_plan'
+  | 'policy_guard'
+  | 'execution_status';
+
+export interface PlanningDisplayStep {
+  kind: PlanningDisplayStepKind;
+  title: string;
+  summary: string;
+  items?: string[];
+  status?: 'running' | 'done' | 'warning' | 'blocked' | 'info';
+}
+
+export interface PlanningDisplayIssue {
+  severity: 'info' | 'warning' | 'blocked';
+  message: string;
+}
+
+export interface PlanningDisplayPayload {
+  summary: string;
+  routeLabel: string;
+  steps: PlanningDisplayStep[];
+  issues?: PlanningDisplayIssue[];
+}
+
+export interface PlanningAgentPlanStreamEvent {
+  type: 'planning.agent_plan';
+  turnId: string;
+  planId: string;
+  goalType: string;
+  userGoal: string;
+  confidence: number;
+  display?: PlanningDisplayPayload;
+  createdAt: string;
+}
+
+export interface PlanningPolicyGuardStreamEvent {
+  type: 'planning.policy_guard';
+  turnId: string;
+  planId: string;
+  allowed: boolean;
+  reason: string;
+  requiresUserConfirmation: boolean;
+  display?: PlanningDisplayPayload;
+  createdAt: string;
+}
+
+export type WorkbenchPlanStreamEvent =
+  | PlanningAgentPlanStreamEvent
+  | PlanningPolicyGuardStreamEvent
+  | CardDataTaskEvent
+  | {
+      type: 'turn_started';
+      turnId: string;
+      conversationId?: string;
+      title?: string;
+      userPrompt: string;
+      createdAt: string;
+    }
+  | {
+      type: 'process.line';
+      turnId: string;
+      seq: number;
+      text: string;
+      phase?: ProductStreamPhase;
+      eventCode?: string;
+      eventId?: string;
+      createdAt: string;
+    }
+  | {
+      type: 'status.pulse';
+      turnId: string;
+      seq?: number;
+      stageText: WorklogStageText;
+      text?: string;
+      phase?: ProductStreamPhase;
+      eventCode?: string;
+      eventId?: string;
+      createdAt?: string;
+    }
+  | {
+      type: 'action.started' | 'action.done' | 'action.failed';
+      turnId: string;
+      seq: number;
+      title: string;
+      detail?: string;
+      tool?: string;
+      durationMs?: number;
+      phase?: ProductStreamPhase;
+      eventCode?: string;
+      eventId?: string;
+      technicalDetail?: Record<string, unknown>;
+      createdAt: string;
+    }
+  | {
+      type: 'final.delta';
+      turnId: string;
+      seq: number;
+      markdownDelta: string;
+      deltaIndex?: number;
+      isFinalDelta?: boolean;
+      phase?: ProductStreamPhase;
+      eventCode?: string;
+      eventId?: string;
+      createdAt: string;
+    }
+  | {
+      type: 'usage';
+      turnId: string;
+      seq: number;
+      durationMs: number;
+      inputTokens?: number;
+      outputTokens?: number;
+      summary: string;
+      phase?: ProductStreamPhase;
+      eventCode?: string;
+      eventId?: string;
+      createdAt: string;
+    }
+  | {
+      type: 'assistant_delta';
+      turnId: string;
+      target?: 'conclusion';
+      delta: string;
+    }
+  | {
+      type: 'stream_message';
+      turnId: string;
+      item: ConversationReturnItem;
+    }
+  | {
+      type: 'plan_ready';
+      turnId: string;
+      planResult: PlanResponse;
+    }
+  | {
+      type: 'patch_plan_ready';
+      turnId: string;
+      patchPlan: PatchPlan;
+      highlightBlockIds?: string[];
+      candidateBlockIds?: string[];
+      error?: CardPatchErrorPayload;
+      suggestions?: CardPatchSuggestion[];
+    }
+  | {
+      type: 'card_recommendations_ready';
+      turnId: string;
+      message: string;
+      recommendations: Array<Record<string, unknown>>;
+    }
+  | {
+      type: 'registered_card_insert_ready';
+      turnId: string;
+      sourceTurnId?: string;
+      question?: string;
+      userInstruction?: string;
+      capabilityId: string;
+      title: string;
+      reason?: string;
+      confidence?: number;
+      dataShape?: string;
+      blockPlan: Record<string, unknown>;
+      dataBinding?: Record<string, unknown>;
+      queryResult?: Record<string, unknown>;
+    }
+  | {
+      type: 'query_result_export_ready';
+      turnId: string;
+      title: string;
+      formats: string[];
+      files: Array<{
+        format: string;
+        filename: string;
+        mimeType: string;
+        content: string;
+        encoding: 'utf8' | 'base64';
+        size?: number;
+      }>;
+      sourceQuestion?: string;
+      rowCount?: number;
+    }
+  | {
+      type: 'layout_draft_ready';
+      turnId: string;
+      layoutDraft: LayoutDraft;
+    }
+  | {
+      type: 'preview_ready';
+      turnId: string;
+      previewDraft: PreviewSnapshotDraft;
+    }
+  | {
+      type: 'snapshot_updated';
+      turnId: string;
+      snapshot: WorkbenchSnapshot;
+      reason?: string;
+      changedBlockIds?: string[];
+      mutationTransaction?: MutationTransaction;
+      highlightBlockIds?: string[];
+    }
+  | {
+      type: 'trace';
+      turnId: string;
+      traceItem: ConversationTurnTraceItem;
+    }
+  | {
+      type: 'needs_confirmation';
+      turnId: string;
+      confirmation: ConversationConfirmation;
+      candidateBlockIds?: string[];
+    }
+  | {
+      type: 'confirmation_result';
+      turnId: string;
+      result: ConversationConfirmation;
+    }
+  | ({
+      type: 'task_state';
+      turnId: string;
+    } & ConversationTaskState)
+  | {
+      type: 'preview_failed';
+      turnId: string;
+      message: string;
+      retryable?: boolean;
+    }
+  | {
+      type: 'insert_failed';
+      turnId: string;
+      message: string;
+      retryable?: boolean;
+    }
+  | {
+      type: 'submit_failed';
+      turnId: string;
+      message: string;
+      retryable?: boolean;
+      draftPreserved?: boolean;
+    }
+  | {
+      type: 'done';
+      turnId: string;
+    }
+  | {
+      type: 'error';
+      turnId: string;
+      message?: string;
+      error?: {
+        code?: string;
+        message?: string;
+        [key: string]: unknown;
+      };
+      stage?: string;
+      retryable?: boolean;
+    };
+
+export interface UnsupportedIntentCase {
+  rawUtterance: string;
+  unresolvedAction?: string;
+  unresolvedTarget?: string;
+  unresolvedConstraint?: string;
+  suggestion: string;
+}
+
+export interface WorkbenchMutationPlan {
+  userIntent: UserIntent;
+  blockPlans: BlockPlan[];
+  canvasAction: CanvasApplyAction;
+  applyPolicy: CanvasApplyPolicy;
+  debug: WorkbenchDebugTrace;
+}
+
+export interface CanvasMutationResult {
+  nextBlocks: MaterializedBlock[];
+  replacedBlockIds: string[];
+  insertedBlockIds: string[];
+  removedBlockIds: string[];
+}
+
+export interface MetricSummaryData {
+  shape: 'metricSummary';
+  primaryLabel: string;
+  primaryFormat: 'currency' | 'number' | 'percent';
+  primaryValue: number;
+  deltaPct: number | null;
+  compareLabel: string;
+  periodLabel: string;
+  sourceLabel: string;
+  secondary: Array<{
+    label: string;
+    format: 'currency' | 'number' | 'percent';
+    value: number;
+  }>;
+}
+
+export interface MultiSeriesData {
+  shape: 'singleSeries' | 'multiSeries';
+  categories: string[];
+  metricFormat: 'currency' | 'number' | 'percent';
+  unit?: string;
+  series: Array<{
+    name: string;
+    type: 'bar' | 'line';
+    colorBy?: 'series' | 'data';
+    itemStyle?: {
+      color?: string;
+    };
+    data: number[];
+  }>;
+  narrative?: string;
+}
+
+export interface PieSlicesData {
+  shape: 'pieSlices';
+  unit?: string;
+  innerRadius?: number;
+  slices: Array<{
+    label: string;
+    value: number;
+    share: number;
+  }>;
+  narrative?: string;
+}
+
+export interface RadarMetricsData {
+  shape: 'radarMetrics';
+  max: number;
+  axes: Array<{
+    label: string;
+    value: number;
+  }>;
+  narrative?: string;
+}
+
+export interface ScatterPointsData {
+  shape: 'scatterPoints';
+  xLabel: string;
+  yLabel: string;
+  sizeLabel?: string;
+  points: Array<{
+    label: string;
+    x: number;
+    y: number;
+    size?: number;
+    category?: string;
+  }>;
+  narrative?: string;
+}
+
+export interface FunnelStagesData {
+  shape: 'funnelStages';
+  unit?: string;
+  stages: Array<{
+    label: string;
+    value: number;
+    rate: number;
+  }>;
+  narrative?: string;
+}
+
+export interface GaugeMetricData {
+  shape: 'gaugeMetric';
+  label: string;
+  value: number;
+  max: number;
+  unit?: string;
+  thresholds: Array<{
+    label: string;
+    value: number;
+    color: string;
+  }>;
+  narrative?: string;
+}
+
+export interface MapRegionsData {
+  shape: 'mapRegions';
+  unit?: string;
+  regions: Array<{
+    name: string;
+    value: number;
+    status: 'high' | 'medium' | 'low';
+  }>;
+  narrative?: string;
+}
+
+export interface SankeyFlowData {
+  shape: 'sankeyFlow';
+  nodes: Array<{
+    id: string;
+    label: string;
+  }>;
+  links: Array<{
+    source: string;
+    target: string;
+    value: number;
+  }>;
+  narrative?: string;
+}
+
+export interface TreeNodeData {
+  id: string;
+  label: string;
+  value?: number;
+  children?: TreeNodeData[];
+}
+
+export interface TreeHierarchyData {
+  shape: 'treeHierarchy';
+  root: TreeNodeData;
+  narrative?: string;
+}
+
+export interface GanttTasksData {
+  shape: 'ganttTasks';
+  timeline: string[];
+  tasks: Array<{
+    label: string;
+    owner: string;
+    start: number;
+    end: number;
+    status: 'done' | 'running' | 'pending' | 'risk';
+  }>;
+  narrative?: string;
+}
+
+export interface CandlestickSeriesData {
+  shape: 'candlestickSeries';
+  categories: string[];
+  unit?: string;
+  values: Array<{
+    open: number;
+    close: number;
+    low: number;
+    high: number;
+  }>;
+  narrative?: string;
+}
+
+export interface BoxplotSeriesData {
+  shape: 'boxplotSeries';
+  categories: string[];
+  values: Array<[number, number, number, number, number]>;
+  narrative?: string;
+}
+
+export interface ParetoSeriesData {
+  shape: 'paretoSeries';
+  categories: string[];
+  bars: number[];
+  cumulative: number[];
+  narrative?: string;
+}
+
+export interface NetworkGraphData {
+  shape: 'networkGraph';
+  nodes: Array<{
+    id: string;
+    label: string;
+    category?: string;
+    value?: number;
+  }>;
+  links: Array<{
+    source: string;
+    target: string;
+    value?: number;
+  }>;
+  narrative?: string;
+}
+
+export interface GeoGlobeData {
+  shape: 'geoGlobe';
+  title: string;
+  centerLabel: string;
+  arcs: Array<{
+    from: string;
+    to: string;
+    value: number;
+  }>;
+  metrics: Array<{
+    label: string;
+    value: string;
+  }>;
+  narrative?: string;
+}
+
+export interface WaterfallStepsData {
+  shape: 'waterfallSteps';
+  unit: string;
+  steps: Array<{
+    label: string;
+    value?: number;
+    delta?: number;
+  }>;
+  narrative?: string;
+}
+
+export interface HeatmapMatrixData {
+  shape: 'heatmapMatrix';
+  rows: string[];
+  columns: string[];
+  values: number[][];
+  narrative?: string;
+}
+
+export interface EchartsOptionData {
+  shape: 'echartsOption';
+  engine?: 'echarts' | 'echarts-gl';
+  requires?: string[];
+  theme?: string;
+  option: Record<string, unknown>;
+  narrative?: string;
+}
+
+export interface EchartsScriptData {
+  shape: 'echartsScript';
+  engine?: 'echarts' | 'echarts-gl';
+  requires?: string[];
+  theme?: string;
+  rootPath?: string;
+  script: string;
+  narrative?: string;
+}
+
+export interface EchartsDynamicData {
+  shape: 'echartsDynamic';
+  optionTemplate: Record<string, unknown>;
+  dataBinding: {
+    bindingId: string;
+    refreshApi: string;
+    xField?: string;
+    yFields?: string[];
+    paramsSchema?: Record<string, unknown>;
+    fieldMapping?: {
+      xField?: string;
+      yFields?: string[];
+    };
+  };
+  narrative?: string;
+}
+
+export interface DashboardGridData {
+  shape: 'dashboardGrid';
+  sourceLabel: string;
+  narrative: string;
+  panels: Array<{
+    id: string;
+    title: string;
+    subtitle?: string;
+    rendererKey: string;
+    data: DisplayBlockData;
+  }>;
+}
+
+export interface CategoryRankingData {
+  shape: 'categoryRanking';
+  dimensionLabel: string;
+  valueFormat: 'currency' | 'number';
+  items: Array<{
+    label: string;
+    value: number;
+    share: number;
+    badge?: string;
+  }>;
+}
+
+export interface TableRowsData {
+  shape: 'rows';
+  visualKind?: string;
+  sourceLabel?: string;
+  columns: string[];
+  rows: Array<{
+    id: string;
+    cells: string[];
+  }>;
+}
+
+export interface InsightNarrativeData {
+  shape: 'insightNarrative';
+  bullets: string[];
+  confidence?: number;
+  owner?: string;
+}
+
+export interface TaskSummaryData {
+  shape: 'taskSummary';
+  total: number;
+  overdue: number;
+  dueToday: number;
+  completed: number;
+  sourceLabel: string;
+  items: Array<{
+    id: string;
+    title: string;
+    type: 'form' | 'survey' | 'notice' | 'document' | 'workflow' | 'custom';
+    status: 'pending' | 'reading' | 'submitted' | 'overdue' | 'done';
+    dueAt?: string;
+    owner?: string;
+    source?: string;
+    entryLabel?: string;
+  }>;
+}
+
+export interface WeatherCurrentData {
+  shape: 'weatherCurrent';
+  location: string;
+  observedAt: string;
+  condition: 'sunny' | 'cloudy' | 'overcast' | 'rain' | 'snow' | 'storm' | 'unknown';
+  conditionLabel: string;
+  temperatureC: number | null;
+  feelsLikeC?: number | null;
+  humidityPct?: number | null;
+  precipitationPct?: number | null;
+  wind?: {
+    direction: string;
+    level: string;
+    speedKph?: number | null;
+  };
+  aqi?: {
+    value: number | null;
+    level: string;
+  };
+  forecast: Array<{
+    label: string;
+    conditionLabel: string;
+    highC: number | null;
+    lowC: number | null;
+    precipitationPct?: number | null;
+  }>;
+  sourceLabel: string;
+  dataStatus: 'live' | 'sample' | 'unavailable';
+  notice?: string;
+}
+
+export interface CalendarCardData {
+  shape: 'calendarCard';
+  timezone: string;
+  today: string;
+  dateLabel: string;
+  weekLabel: string;
+  lunarLabel?: string;
+  items: Array<{
+    id: string;
+    title: string;
+    time: string;
+    type: 'meeting' | 'deadline' | 'todo' | 'holiday' | 'reminder';
+    status: 'scheduled' | 'due' | 'done' | 'sample';
+  }>;
+  sourceLabel: string;
+  dataStatus: 'live' | 'sample' | 'unavailable';
+  notice?: string;
+}
+
+export interface ReportSummaryDisplayData {
+  shape: 'reportSummary';
+  summary: string;
+  highlights: string[];
+  sourceLabel: string;
+  dataStatus: 'generated' | 'sample' | 'unavailable';
+}
+
+export interface EmbeddedFrameData {
+  shape: 'embeddedFrame';
+  title: string;
+  srcUrl: string;
+  sandbox: string;
+  status: 'ready' | 'missing_url' | 'blocked';
+  sourceLabel: string;
+  fallbackText?: string;
+}
+
+export interface FdeCustomComponentData {
+  shape: 'fdeCustomComponent';
+  componentRef: string;
+  componentName: string;
+  props: Record<string, unknown>;
+  status: 'ready' | 'unregistered';
+  sourceLabel: string;
+  fallbackText?: string;
+}
+
+export interface CustomCanvasElement {
+  id: string;
+  kind: 'text' | 'metric' | 'badge' | 'divider';
+  label?: string;
+  value?: string;
+  x?: number;
+  y?: number;
+  w?: number;
+  h?: number;
+  style?: Record<string, unknown>;
+}
+
+export interface CustomCanvasNestedBlock {
+  id: string;
+  title: string;
+  kind: string;
+  capabilityId?: string;
+  dataShape?: string;
+  registryTitle?: string;
+  visualKind?: string;
+  meta?: Record<string, unknown>;
+  slot: string;
+  composeSource?: string;
+  dataBindingId?: string;
+  dataBinding?: {
+    id?: string;
+    bindingId?: string;
+    status?: string;
+    queryIntent?: string;
+    refreshApi?: string;
+    [key: string]: unknown;
+  };
+  dataBindingStatus: string;
+  dataBindingError?: string;
+  humanIntervention?: Record<string, unknown>;
+  queryIntent?: string;
+  subType?: BlockSubType | string;
+  renderer?: BlockRenderer;
+  state?: BlockState;
+  layout?: BlockLayout;
+  visual?: BlockVisualOptions;
+  data?: Record<string, unknown>;
+}
+
+export interface CustomCanvasData {
+  shape: 'customCanvas';
+  sourceLabel: string;
+  containerRole?: string;
+  background?: string;
+  narrative?: string;
+  elements: CustomCanvasElement[];
+  nestedBlocks?: CustomCanvasNestedBlock[];
+  nestedLayoutMode?: 'absolute' | 'grid' | string;
+  nestedLayoutBasis?: {
+    baseCols?: number;
+    x?: number;
+    y?: number;
+    w?: number;
+    h?: number;
+  };
+  nestedLayoutStacks?: Array<{
+    id: string;
+    childIds: string[];
+  }>;
+  nestedLayoutItems?: Record<string, {
+    rowSpan?: number;
+    columnSpan?: number;
+  }>;
+}
+
+/** 协议渲染数据 -- 通用卡片协议驱动 */
+export interface ProtocolRenderData {
+  shape: 'protocolRender';
+  rendererType: RendererType;
+  protocolConfig: ProtocolConfigPayload;
+  protocolData?: ProtocolDataPayload;
+  dataBindingId?: string;
+  dataBinding?: {
+    bindingId?: string;
+    refreshApi?: string;
+    xField?: string;
+    yFields?: string[];
+    status?: string;
+    params?: Record<string, unknown>;
+    sourceType?: string;
+    paramsSchema?: Record<string, unknown>;
+    fieldMapping?: {
+      xField?: string;
+      yFields?: string[];
+    };
+  };
+}
+
+export type DisplayBlockData =
+  | MetricSummaryData
+  | MultiSeriesData
+  | PieSlicesData
+  | RadarMetricsData
+  | ScatterPointsData
+  | FunnelStagesData
+  | GaugeMetricData
+  | MapRegionsData
+  | SankeyFlowData
+  | TreeHierarchyData
+  | GanttTasksData
+  | CandlestickSeriesData
+  | BoxplotSeriesData
+  | ParetoSeriesData
+  | NetworkGraphData
+  | GeoGlobeData
+  | WaterfallStepsData
+  | HeatmapMatrixData
+  | EchartsOptionData
+  | EchartsScriptData
+  | EchartsDynamicData
+  | DashboardGridData
+  | CategoryRankingData
+  | TableRowsData
+  | InsightNarrativeData
+  | TaskSummaryData
+  | WeatherCurrentData
+  | CalendarCardData
+  | ReportSummaryDisplayData
+  | EmbeddedFrameData
+  | FdeCustomComponentData
+  | CustomCanvasData
+  | ProtocolRenderData;
+
+export interface FormField {
+  id: string;
+  type: 'select' | 'currency' | 'textarea' | 'number' | 'text' | 'date' | 'user' | 'file';
+  label: string;
+  required?: boolean;
+  options?: string[];
+  placeholder?: string;
+}
+
+export interface FormBlockData {
+  schemaRef: string;
+  draftRef: string;
+  fields: FormField[];
+  values: Record<string, unknown>;
+  status: 'draft' | 'submitted';
+  lastSavedAt?: string;
+  submittedAt?: string;
+}
+
+export interface SurveyQuestion {
+  id: string;
+  type?: 'single' | 'multiple' | 'score' | 'matrix' | 'text';
+  label: string;
+  options: string[];
+  rows?: string[];
+  scale?: number;
+}
+
+export interface SurveyBlockData {
+  questionnaireRef: string;
+  progress: {
+    current: number;
+    total: number;
+  };
+  questions: SurveyQuestion[];
+  answers: Record<string, unknown>;
+  status: 'draft' | 'submitted';
+  submittedAt?: string;
+}
+
+export interface ActionGroupData {
+  buttons: Array<{
+    id: string;
+    label: string;
+    actionType: string;
+    description: string;
+    confirmLevel?: 'L1' | 'L2' | 'L3' | 'L4';
+    affectedCount?: number;
+    resultPreview?: string;
+  }>;
+}
+
+export interface WorkflowBlockData {
+  instanceRef: string;
+  status: string;
+  lanes?: Array<{
+    label: string;
+    owner: string;
+    status: string;
+  }>;
+  statusBoard?: Array<{
+    label: string;
+    count: number;
+    status: string;
+  }>;
+  steps: Array<{
+    time: string;
+    label: string;
+    status: string;
+    owner?: string;
+    description?: string;
+  }>;
+}
+
+export interface ReportSection {
+  title: string;
+  body: string;
+}
+
+export interface ReportBlockData {
+  reportRef: string;
+  status: string;
+  summary: string;
+  sections: ReportSection[];
+  exportFormats?: Array<'PDF' | 'PPT' | 'Word'>;
+  version: number;
+  updatedAt: string;
+}
+
+export interface LayoutConfig {
+  cols: number;
+  rows: number;
+  maxCols: number;
+  maxRows: number;
+  isSquareCell: boolean;
+  layoutVersion: number;
+}
+
+export interface WorkbenchVisualConfig {
+  themeId?: string;
+  accentColor?: string;
+  backgroundColor?: string;
+  textColor?: string;
+  borderColor?: string;
+  cardRadius?: number;
+  cardShadow?: 'none' | 'soft' | 'standard' | 'strong';
+  density?: 'thumbnail' | 'compact' | 'standard' | 'expanded';
+}
+
+export interface WorkbenchCardStyleConfig extends WorkbenchVisualConfig {
+  css?: Record<string, string | number | boolean | null>;
+  shell?: Record<string, unknown>;
+}
+
+export interface WorkbenchSnapshotVisualConfig {
+  cardStyle?: WorkbenchCardStyleConfig;
+  echartsDefaults?: Record<string, unknown>;
+  layoutTree?: WorkbenchLayoutV4;
+}
+
+export interface ChartVisualOptions {
+  palette?: string[];
+  showLegend?: boolean;
+  showTooltip?: boolean;
+  smooth?: boolean;
+  stacked?: boolean;
+  labelMode?: 'none' | 'inside' | 'outside';
+}
+
+export interface BlockVisualOptions {
+  themeId?: string;
+  density?: 'thumbnail' | 'compact' | 'standard' | 'expanded';
+  accentColor?: string;
+  backgroundColor?: string;
+  textColor?: string;
+  borderColor?: string;
+  cardRadius?: number;
+  cardShadow?: 'none' | 'soft' | 'standard' | 'strong';
+  cardTone?: 'neutral' | 'brand' | 'success' | 'warning' | 'danger';
+  businessSummaryBand?: 'risk';
+  metricVariant?: 'standard' | 'centerNumber';
+  hideSecondary?: boolean;
+  hideMetricLabel?: boolean;
+  hideMetricFooter?: boolean;
+  showSubtitleInThumbnail?: boolean;
+  chart?: ChartVisualOptions;
+  allowedVisualPatchPaths?: string[];
+  advancedVisualPatch?: {
+    enabled: boolean;
+    disclaimerAcceptedAt?: string;
+    rollbackVersion?: number;
+  };
+}
+
+export type CardCapacityLevel = 'micro' | 'compact' | 'standard' | 'expanded' | 'canvas';
+export type CardContentDensity = 'minimal' | 'compact' | 'standard' | 'rich' | 'dashboard';
+
+export interface CardCapacityFacts {
+  grid: {
+    cols: number;
+    rows: number;
+    blockW: number;
+    blockH: number;
+    blockArea: number;
+  };
+  viewport: {
+    width: number;
+    height: number;
+    columnsVisible: number;
+  };
+  pixelBox: {
+    width: number;
+    height: number;
+    contentWidth: number;
+    contentHeight: number;
+    area: number;
+  };
+  rendererCapabilities: Array<{
+    rendererKey: string;
+    minWidth: number;
+    minHeight: number;
+    recommendedCapacity: CardCapacityLevel;
+    supportsResponsiveTiers: boolean;
+  }>;
+  userSizeIntent: 'small' | 'medium' | 'large' | 'will_resize_later' | 'unspecified';
+}
+
+export interface CardFitAnalysis {
+  requestedTopic: string;
+  capacityLevel: CardCapacityLevel;
+  userSizeIntent: CardCapacityFacts['userSizeIntent'];
+  informationGoal: 'single_metric' | 'trend' | 'composition' | 'comparison' | 'dashboard' | 'workflow' | 'unknown';
+  contentDensity: CardContentDensity;
+  recommendedRendererKey: string;
+  selectedContent: string[];
+  omittedContent: string[];
+  overflowRisk: 'low' | 'medium' | 'high';
+  shouldSuggestResize: boolean;
+  suggestedResize?: { w: number; h: number; reason: string };
+  reasoningSummary: string[];
+}
+
+export interface ResponsiveContentTier {
+  title?: string;
+  subtitle?: string;
+  renderer?: BlockRenderer;
+  subType?: BlockSubType | string;
+  data?: DisplayBlockData | Record<string, unknown>;
+  visual?: BlockVisualOptions;
+  summary: string;
+}
+
+export interface ResponsiveContentTiers {
+  compact?: ResponsiveContentTier;
+  standard?: ResponsiveContentTier;
+  expanded?: ResponsiveContentTier;
+  canvas?: ResponsiveContentTier;
+}
+
+export type RuntimeCapabilityLevel = 'config' | 'composition';
+export type RuntimeCapabilitySlot =
+  | 'card.header.left'
+  | 'card.header.right'
+  | 'card.body.toolbar'
+  | 'card.body.inline'
+  | 'card.body.emptyState'
+  | 'card.footer.actions'
+  | 'card.detail.panel'
+  | 'workspace.banner.topRight';
+export type RuntimeCapabilityUiKind = 'iconButton+popover' | 'inlinePanel' | 'filterBar' | 'drawerPanel';
+export type RuntimeCapabilityDataSource = 'cardSearchIndex' | 'routeTargetRegistry' | 'businessObjectQuery';
+export type RuntimeCapabilityActionType =
+  | 'focusCard'
+  | 'openRoute'
+  | 'refreshData'
+  | 'toggleFavorite'
+  | 'exportData'
+  | 'tableSelection'
+  | 'openDrawer'
+  | 'callApiAction';
+export type RuntimeCapabilityMutationAction =
+  | 'mount'
+  | 'unmount'
+  | 'update'
+  | 'move'
+  | 'enable'
+  | 'disable'
+  | 'replace';
+
+export interface RuntimeCapabilityMount {
+  id: string;
+  name: string;
+  level: RuntimeCapabilityLevel;
+  version: number;
+  description?: string;
+  slot: RuntimeCapabilitySlot;
+  placement?: 'prepend' | 'append';
+  ui: {
+    kind: RuntimeCapabilityUiKind;
+    icon?: string;
+    tooltip?: string;
+    placeholder?: string;
+    submitLabel?: string;
+    emptyText?: string;
+  };
+  state?: {
+    query?: {
+      type: 'string';
+      defaultValue?: string;
+    };
+    filter?: Record<string, unknown>;
+    sort?: { field?: string; direction?: 'asc' | 'desc' };
+    pagination?: { pageSize?: number };
+  };
+  data: {
+    source: RuntimeCapabilityDataSource;
+    queryStateKey?: 'query';
+    matchFields?: string[];
+    limit?: number;
+    target?: string;
+    objectType?: string;
+    fields?: string[];
+    filters?: Record<string, unknown>;
+    timeRange?: string;
+  };
+  actions: Array<{
+    trigger: 'onSelectResult' | 'onSubmit' | 'onClick' | 'onChange';
+    type: RuntimeCapabilityActionType;
+    target?: string;
+    params?: Record<string, unknown>;
+  }>;
+  permissions: {
+    read: string[];
+    write: string[];
+    routeTargets?: string[];
+    sideEffects?: string[];
+  };
+  disabled?: boolean;
+  traceSummary?: string;
+}
+
+export interface RuntimeCapabilityMutation {
+  action: RuntimeCapabilityMutationAction;
+  targetCardSelector?: IntentTargetSelector;
+  match?: {
+    capabilityId?: string;
+    slot?: RuntimeCapabilitySlot;
+    uiIcon?: string;
+    dataSource?: RuntimeCapabilityDataSource;
+    actionType?: RuntimeCapabilityActionType;
+    nameKeywords?: string[];
+  };
+  capabilitySpec?: RuntimeCapabilityMount;
+  missingPrimitives?: string[];
+  patch?: {
+    slot?: RuntimeCapabilitySlot;
+    placement?: 'prepend' | 'append';
+    ui?: Partial<RuntimeCapabilityMount['ui']>;
+    data?: Partial<RuntimeCapabilityMount['data']>;
+    actions?: RuntimeCapabilityMount['actions'];
+    disabled?: boolean;
+  };
+  reasonSummary?: string[];
+}
+
+export interface BlockMeta {
+  visual?: BlockVisualOptions;
+  cardCapacityFacts?: CardCapacityFacts;
+  cardFitAnalysis?: CardFitAnalysis;
+  responsiveContentTiers?: ResponsiveContentTiers;
+  capabilityMounts?: RuntimeCapabilityMount[];
+  [key: string]: unknown;
+}
+
+export interface BlockPlan {
+  id: string;
+  version: number;
+  blockType: BlockType;
+  subType: BlockSubType | string;
+  title: string;
+  subtitle?: string;
+  layout: BlockLayout;
+  intent: BlockIntent;
+  source?: BlockSource;
+  renderer?: BlockRenderer;
+  state: BlockState;
+  actions?: Array<WorkbenchAction | Record<string, unknown>>;
+  meta?: BlockMeta;
+}
+
+export interface MaterializedBlock extends BlockPlan {
+  data?: DisplayBlockData | Record<string, unknown>;
+  form?: FormBlockData | Record<string, unknown>;
+  survey?: SurveyBlockData | Record<string, unknown>;
+  actionGroup?: ActionGroupData | Record<string, unknown>;
+  workflow?: WorkflowBlockData | Record<string, unknown>;
+  report?: ReportBlockData | Record<string, unknown>;
+}
+
+export type WorkbenchBlock = MaterializedBlock;
+
+export interface WorkbenchSnapshot {
+  workspaceId: string;
+  roleId: RoleId | '';
+  userId: string;
+  version: number;
+  layoutVersion?: number;
+  layoutConfig?: LayoutConfig;
+  visualConfig?: WorkbenchSnapshotVisualConfig;
+  updatedAt: string;
+  blocks: MaterializedBlock[];
+}
+
+export interface MutationStep {
+  id: string;
+  label: string;
+  kind: MutationStepKind;
+  targetBlockIds: string[];
+  before: unknown;
+  after: unknown;
+  reversible: boolean;
+  dependsOnStepIds?: string[];
+}
+
+export interface MutationTransaction {
+  id: string;
+  source: MutationTransactionSource;
+  userInstruction: string;
+  aiReasoningSummary: string[];
+  operation: CardMutationOperation;
+  targetBlockIds: string[];
+  beforeSnapshot: WorkbenchSnapshot;
+  afterSnapshot: WorkbenchSnapshot;
+  steps: MutationStep[];
+  createdAt: string;
+}
+
+export type ArtifactType =
+  | 'card_plan_block'
+  | 'layout_draft'
+  | 'preview_draft'
+  | 'preview_block'
+  | 'canvas_block'
+  | 'patch_plan'
+  | 'submit_draft'
+  | 'answer'
+  | 'confirmation';
+
+export type ArtifactStatus =
+  | 'draft'
+  | 'needs_confirmation'
+  | 'confirmed'
+  | 'preview_ready'
+  | 'applied'
+  | 'submitted'
+  | 'superseded'
+  | 'failed';
+
+export interface ArtifactIndexItem {
+  artifactId: string;
+  type: ArtifactType;
+  workItemId: string;
+  turnId: string;
+  status: ArtifactStatus;
+  title: string;
+  aliases: string[];
+  ordinal?: number;
+  createdAt: string;
+  updatedAt: string;
+  payloadRef: {
+    source: 'turn' | 'snapshot' | 'store';
+    path: string;
+  };
+  lightweightPayload: Record<string, unknown>;
+}
+
+export interface CanvasBlockContext extends MaterializedBlock {
+  rendererKey?: string;
+  nestedTitles?: string[];
+}
+
+export interface CanonicalLayoutContext {
+  baseVersion: number;
+  layoutVersion: number;
+  layoutSource: 'gridstack_layout_tree' | 'block_layout';
+  layoutFingerprint: string;
+  layoutTree?: Record<string, unknown>;
+  blockLayouts?: Array<{ blockId: string; layout: Pick<BlockLayout, 'x' | 'y' | 'w' | 'h'> }>;
+  updatedAt?: string;
+}
+
+export interface CanvasContext {
+  snapshotVersion: number;
+  layoutConfig: LayoutConfig;
+  blockCount: number;
+  blocks: CanvasBlockContext[];
+  selectedBlock?: {
+    id: string;
+    title: string;
+    blockType: string;
+    subType: string;
+    rendererKey?: string;
+  } | null;
+  canonicalLayoutContext?: CanonicalLayoutContext;
+}
+
+export interface TurnContextSummary {
+  turnId: string;
+  workItemId: string;
+  order: number;
+  userPrompt: string;
+  assistantSummary: string;
+  intentChannel: WorkbenchIntentChannel;
+  status:
+    | 'streaming'
+    | 'ready'
+    | 'needs_confirmation'
+    | 'applied'
+    | 'submitted'
+    | 'failed'
+    | 'cancelled';
+  createdAt: string;
+  updatedAt: string;
+  artifactIds: string[];
+}
+
+export interface RecentFocus {
+  latestTurnId?: string;
+  latestNonAnswerTurnId?: string;
+  latestCardWorkItemId?: string;
+  latestPatchWorkItemId?: string;
+  latestSubmitWorkItemId?: string;
+  latestPreviewDraftId?: string;
+  latestSubmitDraftId?: string;
+  selectedBlockId?: string | null;
+  selectedNestedBlock?: {
+    parentId: string;
+    childId: string;
+  } | null;
+  lastInsertedBlockIds?: string[];
+  lastHighlightedBlockIds?: string[];
+  pendingPatch?: {
+    id: string;
+    sourceTurnId: string;
+    status: PendingWorkbenchPatch['status'];
+    candidateBlockIds: string[];
+    targetSummary?: string;
+    userInstruction: string;
+  } | null;
+}
+
+export interface ConversationScreenContext {
+  conversationId: string;
+  activeTurnId?: string;
+  activeWorkItemId?: string;
+  roleId: RoleId | '';
+  workspaceId: string;
+  userId: string;
+  currentInput: string;
+  selectedBlock?: CanvasContext['selectedBlock'];
+  canvas: CanvasContext;
+  visibleTurns: TurnContextSummary[];
+  artifactIndex: ArtifactIndexItem[];
+  recentFocus: RecentFocus;
+}
+
+export interface WorkbenchTemplate {
+  id: string;
+  resource_id: string;
+  path: string;
+  name: string;
+  tag: string;
+  description: string;
+  source: 'fde_preset' | 'user_saved';
+  renameable: boolean;
+  ownerUserId?: string;
+  roleId?: RoleId;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface UserWorkbenchPreference {
+  activeWorkbenchId: string;
+  defaultWorkbenchId: string;
+  assistantPersona?: AssistantPersonaKey;
+}
+
+export interface WorkbenchConversationWorkItem {
+  id: string;
+  title: string;
+  intentChannel: WorkbenchIntentChannel;
+  status: 'active' | 'paused' | 'completed' | 'failed';
+  relatedTurnIds: string[];
+  contextSummary?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface SkillMetadata {
+  id: string;
+  name: string;
+  intentTypes: WorkbenchIntentChannel[];
+  inputSchema: unknown;
+  outputSchema: unknown;
+  requiredContext: string[];
+  requiredTools: string[];
+  permissionScope: string[];
+  confirmationPolicy: 'none' | 'low_risk' | 'required';
+  canWrite: boolean;
+  fallbackPolicy: 'none' | 'general_skill' | 'error';
+}
+
+export interface PlannerStep {
+  label: string;
+  status: 'done' | 'ready' | 'pending';
+  detail: string;
+}
+
+export interface CardPlan {
+  target: 'canvas_preview';
+  blocks: BlockPlan[];
+  mutationPlan: WorkbenchMutationPlan;
+}
+
+export interface CardTargetResolveResult {
+  status: 'resolved' | 'candidates' | 'not_found' | 'needs_clarification';
+  mode: 'selected' | 'recent_inserted' | 'ordinal' | 'row_column' | 'region' | 'title' | 'scope' | 'chart_type' | 'ai_semantic';
+  targetBlockIds: string[];
+  candidateBlockIds: string[];
+  confidence: number;
+  reason: string;
+  warnings: string[];
+  requiresConfirmation?: boolean;
+  targetSummary?: string;
+}
+
+export type WorkbenchPatchIntentOperation =
+  | 'renameTitle'
+  | 'editText'
+  | 'modifyStyle'
+  | 'changeChart'
+  | 'changeDataSource'
+  | 'replaceCard'
+  | 'adjustLayout'
+  | 'deleteCard'
+  | 'batchModify';
+
+export interface WorkbenchPatchIntent {
+  id: string;
+  sourceTurnId: string;
+  userInstruction: string;
+  operation: WorkbenchPatchIntentOperation;
+  editModes: CardPatchEditMode[];
+  targetQuery: string;
+  payload: Record<string, unknown>;
+  riskLevel: 'low' | 'medium' | 'high';
+  requiresConfirmation: boolean;
+}
+
+export interface PendingWorkbenchPatchCandidateSummary {
+  id: string;
+  title: string;
+  positionLabel: string;
+  rendererKey?: string;
+}
+
+export interface PendingWorkbenchPatch {
+  id: string;
+  sourceTurnId: string;
+  patchIntent: WorkbenchPatchIntent;
+  targetResolve: CardTargetResolveResult;
+  candidateBlockIds: string[];
+  candidateSummaries: PendingWorkbenchPatchCandidateSummary[];
+  baseSnapshotVersion: number;
+  status: 'awaiting_target' | 'awaiting_confirmation';
+  createdAt: string;
+  expiresAt: string;
+}
+
+export type CardPatchErrorCode =
+  | 'CARD_TARGET_NOT_FOUND'
+  | 'CARD_TARGET_AMBIGUOUS'
+  | 'CARD_PATCH_UNSUPPORTED'
+  | 'CHART_TYPE_INCOMPATIBLE'
+  | 'WORKBENCH_VERSION_CONFLICT';
+
+export type CardPatchSuggestionType =
+  | 'select_card'
+  | 'choose_candidate'
+  | 'retry_prompt'
+  | 'regenerate_chart'
+  | 'change_chart_type'
+  | 'refresh_workspace';
+
+export interface CardPatchTargetSummary {
+  blockId: string;
+  title: string;
+  blockType?: string;
+  subType?: string;
+  rendererKey?: string;
+  layout?: Pick<BlockLayout, 'x' | 'y' | 'w' | 'h'>;
+  confidence?: number;
+  reason?: string;
+}
+
+export interface CardPatchSuggestion {
+  type: CardPatchSuggestionType;
+  label: string;
+  prompt?: string;
+  targetBlockId?: string;
+}
+
+export interface CardPatchErrorPayload {
+  code: CardPatchErrorCode;
+  message: string;
+  summary: string;
+  detail?: string;
+  targetText?: string;
+  target?: CardPatchTargetSummary;
+  candidates?: CardPatchTargetSummary[];
+  suggestions?: CardPatchSuggestion[];
+}
+
+export interface PatchPlan {
+  operation?: CardPatchOperation;
+  editModes?: CardPatchEditMode[];
+  scope?: 'single' | 'group' | 'all' | 'global_common';
+  targetBlockIds: string[];
+  targetSummary?: string;
+  target?: CardPatchTargetSummary | null;
+  reason?: string;
+  targetResolve?: CardTargetResolveResult;
+  filteredOptionKeys?: string[];
+  patches: Array<{
+    blockId?: string;
+    path: string;
+    value: unknown;
+    mergeMode?: 'replace' | 'deepMerge' | 'arrayMergeById' | 'arrayMergeByType';
+    reason?: string;
+  }>;
+  allowedPatchPaths?: string[];
+  regenerationPrompt?: string;
+  canvasAction?: CanvasApplyAction;
+  requiresConfirmation?: boolean;
+  riskLevel?: 'low' | 'medium' | 'high';
+  summary?: string;
+  warnings?: string[];
+  error?: CardPatchErrorPayload;
+  suggestions?: CardPatchSuggestion[];
+  note?: string;
+  confirmation?: Record<string, unknown>;
+}
+
+export interface AnswerPlan {
+  answerType:
+    | 'weather'
+    | 'calendar'
+    | 'knowledge_base'
+    | 'policy'
+    | 'workspace_context'
+    | 'business_data_analysis'
+    | 'chart_compare_analysis'
+    | 'external_news'
+    | 'general';
+  dataSources: string[];
+  canWrite: false;
+}
+
+export interface SubmitPlan {
+  draftId: string;
+  submitType: SubmitType;
+  targetBlockId?: string;
+  targetBlockTitle?: string;
+  executor?: SubmitDraftExecutor;
+  payload?: Record<string, unknown>;
+  missingFields: string[];
+  confirmation: ConversationConfirmation;
+  status?: SubmitDraftStatus;
+}
+
+export type SubmitType = 'form' | 'survey' | 'action' | 'workflow' | 'data_write' | 'report';
+
+export type SubmitDraftExecutor =
+  | 'form_submit'
+  | 'survey_submit'
+  | 'action_execute'
+  | 'report_generate'
+  | 'workflow_transition'
+  | 'data_write';
+
+export type SubmitDraftStatus =
+  | 'draft'
+  | 'needs_confirmation'
+  | 'confirmed'
+  | 'executing'
+  | 'submitted'
+  | 'failed'
+  | 'cancelled';
+
+export interface SubmitDraft extends SubmitPlan {
+  executor: SubmitDraftExecutor;
+  payload: Record<string, unknown>;
+  status: SubmitDraftStatus;
+  workspaceId: string;
+  roleId: RoleId;
+  userId: string;
+  conversationId?: string;
+  sourceTurnId?: string;
+  createdAt: string;
+  updatedAt: string;
+  lastError?: string;
+}
+
+export type ProductStreamPhase =
+  | 'received'
+  | 'routing'
+  | 'context'
+  | 'planning'
+  | 'tool_running'
+  | 'drafting'
+  | 'previewing'
+  | 'confirming'
+  | 'finalizing'
+  | 'done';
+
+export interface ReferenceResolutionTrace {
+  isContinuation: boolean;
+  confidence: number;
+  targetWorkItemId?: string;
+  targetTurnId?: string;
+  targetArtifactIds: string[];
+  targetKind?: ArtifactType;
+  reason: string;
+  rewrittenInput: string;
+  warnings: string[];
+}
+
+export interface TracePlan {
+  items: ConversationTurnTraceItem[];
+  requestContext?: {
+    title?: string;
+    lines?: string[];
+  };
+  referenceResolution?: ReferenceResolutionTrace;
+  continuation?: {
+    workItemId?: string;
+    targetArtifactId?: string;
+    mode?: 'new_generation' | 'revise_previous_draft' | 'confirm_previous_preview';
+  };
+}
+
+export interface PlanResponse {
+  status: 'plan_ready';
+  intentChannel: WorkbenchIntentChannel;
+  reply: string;
+  summary: string;
+  assumptions: string[];
+  plannerSteps: PlannerStep[];
+  cardPlan?: CardPlan;
+  patchPlan?: PatchPlan | null;
+  answerPlan?: AnswerPlan | null;
+  submitPlan?: SubmitPlan | null;
+  tracePlan?: TracePlan | null;
+  /**
+   * Compatibility accessor for existing materialization code.
+   * New code should read `cardPlan.blocks`.
+   */
+  blockPlans: BlockPlan[];
+  /**
+   * Compatibility accessor for existing canvas mutation code.
+   * New code should read `cardPlan.mutationPlan`.
+   */
+  mutationPlan: WorkbenchMutationPlan;
+}
+
+export interface MaterializeResponse {
+  summary: string;
+  materializedBlocks: MaterializedBlock[];
+}
+
+export interface ActionLogItem {
+  id: string;
+  blockId: string;
+  actionId: string;
+  actionLabel: string;
+  roleId: RoleId;
+  userId: string;
+  workspaceId: string;
+  executedAt: string;
+  result: string;
+}
+
+export interface WorkbenchRoleMeta {
+  id: RoleId;
+  label: string;
+  shortLabel: string;
+  description: string;
+  orgName: string;
+  scene: string;
+  template: string;
+  theme: string;
+  heroTitle: string;
+  heroDescription: string;
+  accents: {
+    chip: string;
+    glow: string;
+    border: string;
+  };
+  quickPrompts: string[];
+  keyFocus: string[];
+}