refactor(apps): 重构数据层目录结构并新增启动预热编排器

apps/lib/core/ui_schema/models/actions.dart

@@ -0,0 +1,205 @@
+part of 'ui_schema.dart';
+
+abstract class ActionSpec {
+  String get type;
+  Map<String, dynamic> toJson();
+}
+
+class NavigateAction implements ActionSpec {
+  final String path;
+  final Map<String, dynamic>? params;
+
+  const NavigateAction({required this.path, this.params});
+
+  @override
+  String get type => 'navigation';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {'type': type, 'path': path, if (params != null) 'params': params};
+  }
+}
+
+class LinkAction implements ActionSpec {
+  final String url;
+  final String? target;
+
+  const LinkAction({required this.url, this.target});
+
+  @override
+  String get type => 'url';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {'type': type, 'url': url, if (target != null) 'target': target};
+  }
+}
+
+class EventAction implements ActionSpec {
+  final String event;
+  final Map<String, dynamic>? payload;
+
+  const EventAction({required this.event, this.payload});
+
+  @override
+  String get type => 'event';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'type': type,
+      'event': event,
+      if (payload != null) 'payload': payload,
+    };
+  }
+}
+
+class ToolAction implements ActionSpec {
+  final String toolId;
+  final Map<String, dynamic>? params;
+
+  const ToolAction({required this.toolId, this.params});
+
+  @override
+  String get type => 'tool';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'type': type,
+      'toolId': toolId,
+      if (params != null) 'params': params,
+    };
+  }
+}
+
+class CopyAction implements ActionSpec {
+  final String content;
+  final String? successMessage;
+
+  const CopyAction({required this.content, this.successMessage});
+
+  @override
+  String get type => 'copy';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'type': type,
+      'content': content,
+      if (successMessage != null) 'successMessage': successMessage,
+    };
+  }
+}
+
+class PayloadAction implements ActionSpec {
+  final Map<String, dynamic> payload;
+  final String? submitTo;
+
+  const PayloadAction({required this.payload, this.submitTo});
+
+  @override
+  String get type => 'payload';
+
+  @override
+  Map<String, dynamic> toJson() {
+    return {
+      'type': type,
+      'payload': payload,
+      if (submitTo != null) 'submitTo': submitTo,
+    };
+  }
+}
+
+ActionSpec actionSpecFromJson(Map<String, dynamic> json) {
+  final type = json['type'] as String? ?? '';
+  switch (type) {
+    case 'navigation':
+      return NavigateAction(
+        path: json['path'] as String? ?? '',
+        params: json['params'] as Map<String, dynamic>?,
+      );
+    case 'url':
+      return LinkAction(
+        url: json['url'] as String? ?? '',
+        target: json['target'] as String?,
+      );
+    case 'event':
+      return EventAction(
+        event: json['event'] as String? ?? '',
+        payload: json['payload'] as Map<String, dynamic>?,
+      );
+    case 'tool':
+      return ToolAction(
+        toolId: json['toolId'] as String? ?? '',
+        params: json['params'] as Map<String, dynamic>?,
+      );
+    case 'copy':
+      return CopyAction(
+        content: json['content'] as String? ?? '',
+        successMessage: json['successMessage'] as String?,
+      );
+    case 'payload':
+      return PayloadAction(
+        payload: json['payload'] as Map<String, dynamic>? ?? {},
+        submitTo: json['submitTo'] as String?,
+      );
+    default:
+      return EventAction(event: 'unknown');
+  }
+}
+
+class UiAction {
+  final String id;
+  final String label;
+  final UiIcon? icon;
+  final ActionStyle? style;
+  final bool disabled;
+  final ActionSpec action;
+  final ActionConfirm? confirm;
+
+  const UiAction({
+    required this.id,
+    required this.label,
+    this.icon,
+    this.style,
+    this.disabled = false,
+    required this.action,
+    this.confirm,
+  });
+
+  factory UiAction.fromJson(Map<String, dynamic> json) {
+    return UiAction(
+      id: json['id'] as String? ?? '',
+      label: json['label'] as String? ?? '',
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      style: json['style'] != null
+          ? ActionStyle.values.firstWhere(
+              (e) => e.value == json['style'],
+              orElse: () => ActionStyle.primary,
+            )
+          : null,
+      disabled: json['disabled'] as bool? ?? false,
+      action: actionSpecFromJson(
+        json['action'] as Map<String, dynamic>? ?? {'type': 'event'},
+      ),
+      confirm: json['confirm'] != null
+          ? ActionConfirm.fromJson(json['confirm'] as Map<String, dynamic>)
+          : null,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'label': label,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (style != null) 'style': style!.value,
+      'disabled': disabled,
+      'action': action.toJson(),
+      if (confirm != null) 'confirm': confirm!.toJson(),
+    };
+  }
+}

apps/lib/core/ui_schema/models/builders.dart

@@ -0,0 +1,47 @@
+part of 'ui_schema.dart';
+
+UiSchemaDocument buildSuccessDocument(
+  List<UiNode> nodes, {
+  String version = '1.0',
+  SchemaType schemaType = SchemaType.toolResult,
+  String? docId,
+  String? timestamp,
+  String locale = 'zh-CN',
+  RendererConfig? renderer,
+  DocumentMeta? meta,
+}) {
+  return UiSchemaDocument(
+    version: version,
+    schemaType: schemaType,
+    docId: docId,
+    timestamp: timestamp,
+    locale: locale,
+    status: UiStatus.success,
+    renderer: renderer,
+    meta: meta,
+    nodes: nodes,
+  );
+}
+
+UiSchemaDocument buildErrorDocument(
+  List<UiNode> nodes, {
+  String version = '1.0',
+  SchemaType schemaType = SchemaType.toolResult,
+  String? docId,
+  String? timestamp,
+  String locale = 'zh-CN',
+  RendererConfig? renderer,
+  DocumentMeta? meta,
+}) {
+  return UiSchemaDocument(
+    version: version,
+    schemaType: schemaType,
+    docId: docId,
+    timestamp: timestamp,
+    locale: locale,
+    status: UiStatus.error,
+    renderer: renderer,
+    meta: meta,
+    nodes: nodes,
+  );
+}

apps/lib/core/ui_schema/models/common_types.dart

@@ -0,0 +1,273 @@
+part of 'ui_schema.dart';
+
+class UiIcon {
+  final IconSource source;
+  final String value;
+  final String? color;
+  final int? size;
+
+  const UiIcon({
+    required this.source,
+    required this.value,
+    this.color,
+    this.size,
+  });
+
+  factory UiIcon.fromJson(Map<String, dynamic> json) {
+    return UiIcon(
+      source: IconSource.values.firstWhere(
+        (e) => e.value == json['source'],
+        orElse: () => IconSource.icon,
+      ),
+      value: json['value'] as String? ?? '',
+      color: json['color'] as String?,
+      size: json['size'] as int?,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'source': source.value,
+      'value': value,
+      if (color != null) 'color': color,
+      if (size != null) 'size': size,
+    };
+  }
+}
+
+class UiBadge {
+  final String label;
+  final BadgeVariant variant;
+
+  const UiBadge({required this.label, this.variant = BadgeVariant.def});
+
+  factory UiBadge.fromJson(Map<String, dynamic> json) {
+    return UiBadge(
+      label: json['label'] as String? ?? '',
+      variant: BadgeVariant.values.firstWhere(
+        (e) => e.value == json['variant'],
+        orElse: () => BadgeVariant.def,
+      ),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {'label': label, 'variant': variant.value};
+  }
+}
+
+class Pagination {
+  final int page;
+  final int pageSize;
+  final int total;
+  final bool hasMore;
+
+  const Pagination({
+    required this.page,
+    required this.pageSize,
+    required this.total,
+    required this.hasMore,
+  });
+
+  factory Pagination.fromJson(Map<String, dynamic> json) {
+    return Pagination(
+      page: json['page'] as int? ?? 1,
+      pageSize: json['pageSize'] as int? ?? 20,
+      total: json['total'] as int? ?? 0,
+      hasMore: json['hasMore'] as bool? ?? false,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'page': page,
+      'pageSize': pageSize,
+      'total': total,
+      'hasMore': hasMore,
+    };
+  }
+}
+
+class ActionConfirm {
+  final String? title;
+  final String? message;
+  final String? confirmLabel;
+  final String? cancelLabel;
+
+  const ActionConfirm({
+    this.title,
+    this.message,
+    this.confirmLabel,
+    this.cancelLabel,
+  });
+
+  factory ActionConfirm.fromJson(Map<String, dynamic> json) {
+    return ActionConfirm(
+      title: json['title'] as String?,
+      message: json['message'] as String?,
+      confirmLabel: json['confirmLabel'] as String?,
+      cancelLabel: json['cancelLabel'] as String?,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      if (title != null) 'title': title,
+      if (message != null) 'message': message,
+      if (confirmLabel != null) 'confirmLabel': confirmLabel,
+      if (cancelLabel != null) 'cancelLabel': cancelLabel,
+    };
+  }
+}
+
+class KeyValuePair {
+  final String key;
+  final String? label;
+  final dynamic value;
+  final bool? copyable;
+
+  const KeyValuePair({
+    required this.key,
+    this.label,
+    required this.value,
+    this.copyable,
+  });
+
+  factory KeyValuePair.fromJson(Map<String, dynamic> json) {
+    return KeyValuePair(
+      key: json['key'] as String? ?? '',
+      label: json['label'] as String?,
+      value: json['value'],
+      copyable: json['copyable'] as bool?,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'key': key,
+      if (label != null) 'label': label,
+      'value': value,
+      if (copyable != null) 'copyable': copyable,
+    };
+  }
+}
+
+class TableColumn {
+  final String key;
+  final String label;
+  final String? width;
+  final String? align;
+
+  const TableColumn({
+    required this.key,
+    required this.label,
+    this.width,
+    this.align,
+  });
+
+  factory TableColumn.fromJson(Map<String, dynamic> json) {
+    return TableColumn(
+      key: json['key'] as String? ?? '',
+      label: json['label'] as String? ?? '',
+      width: json['width'] as String?,
+      align: json['align'] as String?,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'key': key,
+      'label': label,
+      if (width != null) 'width': width,
+      if (align != null) 'align': align,
+    };
+  }
+}
+
+class TableRow {
+  final String id;
+  final Map<String, dynamic> cells;
+  final Map<String, dynamic>? metadata;
+  final List<UiAction>? actions;
+
+  const TableRow({
+    required this.id,
+    required this.cells,
+    this.metadata,
+    this.actions,
+  });
+
+  factory TableRow.fromJson(Map<String, dynamic> json) {
+    return TableRow(
+      id: json['id'] as String? ?? '',
+      cells: json['cells'] as Map<String, dynamic>? ?? {},
+      metadata: json['metadata'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'cells': cells,
+      if (metadata != null) 'metadata': metadata,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class ListItem {
+  final String id;
+  final String title;
+  final String? subtitle;
+  final String? description;
+  final UiIcon? icon;
+  final UiBadge? badge;
+  final Map<String, dynamic>? metadata;
+  final List<UiAction>? actions;
+
+  const ListItem({
+    required this.id,
+    required this.title,
+    this.subtitle,
+    this.description,
+    this.icon,
+    this.badge,
+    this.metadata,
+    this.actions,
+  });
+
+  factory ListItem.fromJson(Map<String, dynamic> json) {
+    return ListItem(
+      id: json['id'] as String? ?? '',
+      title: json['title'] as String? ?? '',
+      subtitle: json['subtitle'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      badge: json['badge'] != null
+          ? UiBadge.fromJson(json['badge'] as Map<String, dynamic>)
+          : null,
+      metadata: json['metadata'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'title': title,
+      if (subtitle != null) 'subtitle': subtitle,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (badge != null) 'badge': badge!.toJson(),
+      if (metadata != null) 'metadata': metadata,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}

apps/lib/core/ui_schema/models/document.dart

@@ -0,0 +1,128 @@
+part of 'ui_schema.dart';
+
+class RendererConfig {
+  final String? renderer;
+  final RendererTheme? theme;
+
+  const RendererConfig({this.renderer, this.theme});
+
+  factory RendererConfig.fromJson(Map<String, dynamic> json) {
+    return RendererConfig(
+      renderer: json['renderer'] as String?,
+      theme: json['theme'] != null
+          ? RendererTheme.values.firstWhere(
+              (e) => e.value == json['theme'],
+              orElse: () => RendererTheme.def,
+            )
+          : null,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      if (renderer != null) 'renderer': renderer,
+      if (theme != null) 'theme': theme!.value,
+    };
+  }
+}
+
+class DocumentMeta {
+  final String? requestId;
+  final String? toolId;
+  final String? traceId;
+  final String? userId;
+  final Map<String, dynamic>? extra;
+
+  const DocumentMeta({
+    this.requestId,
+    this.toolId,
+    this.traceId,
+    this.userId,
+    this.extra,
+  });
+
+  factory DocumentMeta.fromJson(Map<String, dynamic> json) {
+    return DocumentMeta(
+      requestId: json['requestId'] as String?,
+      toolId: json['toolId'] as String?,
+      traceId: json['traceId'] as String?,
+      userId: json['userId'] as String?,
+      extra: json,
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      if (requestId != null) 'requestId': requestId,
+      if (toolId != null) 'toolId': toolId,
+      if (traceId != null) 'traceId': traceId,
+      if (userId != null) 'userId': userId,
+    };
+  }
+}
+
+class UiSchemaDocument {
+  final String version;
+  final SchemaType schemaType;
+  final String? docId;
+  final String? timestamp;
+  final String? locale;
+  final UiStatus status;
+  final RendererConfig? renderer;
+  final DocumentMeta? meta;
+  final List<UiNode> nodes;
+
+  const UiSchemaDocument({
+    required this.version,
+    required this.schemaType,
+    this.docId,
+    this.timestamp,
+    this.locale,
+    required this.status,
+    this.renderer,
+    this.meta,
+    required this.nodes,
+  });
+
+  factory UiSchemaDocument.fromJson(Map<String, dynamic> json) {
+    return UiSchemaDocument(
+      version: json['version'] as String? ?? '1.0',
+      schemaType: SchemaType.values.firstWhere(
+        (e) => e.value == json['schemaType'],
+        orElse: () => SchemaType.toolResult,
+      ),
+      docId: json['docId'] as String?,
+      timestamp: json['timestamp'] as String?,
+      locale: json['locale'] as String?,
+      status: UiStatus.values.firstWhere(
+        (e) => e.value == json['status'],
+        orElse: () => UiStatus.info,
+      ),
+      renderer: json['renderer'] != null
+          ? RendererConfig.fromJson(json['renderer'] as Map<String, dynamic>)
+          : null,
+      meta: json['meta'] != null
+          ? DocumentMeta.fromJson(json['meta'] as Map<String, dynamic>)
+          : null,
+      nodes:
+          (json['nodes'] as List<dynamic>?)
+              ?.map((e) => UiNode.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'version': version,
+      'schemaType': schemaType.value,
+      if (docId != null) 'docId': docId,
+      if (timestamp != null) 'timestamp': timestamp,
+      if (locale != null) 'locale': locale,
+      'status': status.value,
+      if (renderer != null) 'renderer': renderer!.toJson(),
+      if (meta != null) 'meta': meta!.toJson(),
+      'nodes': nodes.map((e) => (e as dynamic).toJson()).toList(),
+    };
+  }
+}

apps/lib/core/ui_schema/models/enums.dart

@@ -0,0 +1,104 @@
+part of 'ui_schema.dart';
+
+enum SchemaType {
+  toolResult('tool_result'),
+  agentResponse('agent_response'),
+  notification('notification');
+
+  final String value;
+  const SchemaType(this.value);
+}
+
+enum UiStatus {
+  info('info'),
+  success('success'),
+  warning('warning'),
+  error('error'),
+  pending('pending');
+
+  final String value;
+  const UiStatus(this.value);
+}
+
+enum IconSource {
+  icon('icon'),
+  emoji('emoji'),
+  url('url');
+
+  final String value;
+  const IconSource(this.value);
+}
+
+enum OperationType {
+  create('create'),
+  update('update'),
+  delete('delete'),
+  execute('execute');
+
+  final String value;
+  const OperationType(this.value);
+}
+
+enum OperationResult {
+  success('success'),
+  failure('failure'),
+  partial('partial');
+
+  final String value;
+  const OperationResult(this.value);
+}
+
+enum ContainerDirection {
+  vertical('vertical'),
+  horizontal('horizontal');
+
+  final String value;
+  const ContainerDirection(this.value);
+}
+
+enum TextFormat {
+  plain('plain'),
+  markdown('markdown');
+
+  final String value;
+  const TextFormat(this.value);
+}
+
+enum KvLayout {
+  vertical('vertical'),
+  horizontal('horizontal'),
+  grid('grid');
+
+  final String value;
+  const KvLayout(this.value);
+}
+
+enum BadgeVariant {
+  def('default'),
+  success('success'),
+  warning('warning'),
+  error('error'),
+  info('info');
+
+  final String value;
+  const BadgeVariant(this.value);
+}
+
+enum ActionStyle {
+  primary('primary'),
+  secondary('secondary'),
+  ghost('ghost'),
+  danger('danger');
+
+  final String value;
+  const ActionStyle(this.value);
+}
+
+enum RendererTheme {
+  def('default'),
+  dark('dark'),
+  light('light');
+
+  final String value;
+  const RendererTheme(this.value);
+}

apps/lib/core/ui_schema/models/nodes.dart

@@ -0,0 +1,595 @@
+part of 'ui_schema.dart';
+
+abstract class UiNode {
+  String get type;
+  String? get id;
+
+  factory UiNode.fromJson(Map<String, dynamic> json) {
+    final type = json['type'] as String? ?? '';
+    switch (type) {
+      case 'text':
+        return UiTextNode.fromJson(json);
+      case 'card':
+        return UiCardNode.fromJson(json);
+      case 'list':
+        return UiListNode.fromJson(json);
+      case 'table':
+        return UiTableNode.fromJson(json);
+      case 'kv':
+        return UiKvNode.fromJson(json);
+      case 'operation':
+        return UiOperationNode.fromJson(json);
+      case 'error':
+        return UiErrorNode.fromJson(json);
+      case 'container':
+        return UiContainerNode.fromJson(json);
+      default:
+        return UiTextNode(content: 'Unknown node type: $type');
+    }
+  }
+}
+
+class UiTextNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'text';
+  final String content;
+  final TextFormat format;
+  final UiIcon? icon;
+  final List<UiAction>? actions;
+
+  const UiTextNode({
+    this.id,
+    required this.content,
+    this.format = TextFormat.plain,
+    this.icon,
+    this.actions,
+  });
+
+  factory UiTextNode.fromJson(Map<String, dynamic> json) {
+    return UiTextNode(
+      id: json['id'] as String?,
+      content: json['content'] as String? ?? '',
+      format: TextFormat.values.firstWhere(
+        (e) => e.value == json['format'],
+        orElse: () => TextFormat.plain,
+      ),
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      'content': content,
+      'format': format.value,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiCardNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'card';
+  final String? title;
+  final String? description;
+  final UiIcon? icon;
+  final UiStatus? status;
+  final String? timestamp;
+  final List<UiNode>? children;
+  final UiTextNode? footer;
+  final Map<String, dynamic>? extensions;
+  final List<UiAction>? actions;
+
+  const UiCardNode({
+    this.id,
+    this.title,
+    this.description,
+    this.icon,
+    this.status,
+    this.timestamp,
+    this.children,
+    this.footer,
+    this.extensions,
+    this.actions,
+  });
+
+  factory UiCardNode.fromJson(Map<String, dynamic> json) {
+    return UiCardNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      status: json['status'] != null
+          ? UiStatus.values.firstWhere(
+              (e) => e.value == json['status'],
+              orElse: () => UiStatus.info,
+            )
+          : null,
+      timestamp: json['timestamp'] as String?,
+      children: (json['children'] as List<dynamic>?)
+          ?.map((e) => UiNode.fromJson(e as Map<String, dynamic>))
+          .toList(),
+      footer: json['footer'] != null
+          ? UiTextNode.fromJson(json['footer'] as Map<String, dynamic>)
+          : null,
+      extensions: json['extensions'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (status != null) 'status': status!.value,
+      if (timestamp != null) 'timestamp': timestamp,
+      if (children != null)
+        'children': children!.map((e) => (e as dynamic).toJson()).toList(),
+      if (footer != null) 'footer': footer!.toJson(),
+      if (extensions != null) 'extensions': extensions,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiListNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'list';
+  final String? title;
+  final String? description;
+  final UiIcon? icon;
+  final UiStatus? status;
+  final List<ListItem> items;
+  final Pagination? pagination;
+  final String? emptyText;
+  final Map<String, dynamic>? extensions;
+  final List<UiAction>? actions;
+
+  const UiListNode({
+    this.id,
+    this.title,
+    this.description,
+    this.icon,
+    this.status,
+    required this.items,
+    this.pagination,
+    this.emptyText,
+    this.extensions,
+    this.actions,
+  });
+
+  factory UiListNode.fromJson(Map<String, dynamic> json) {
+    return UiListNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      status: json['status'] != null
+          ? UiStatus.values.firstWhere(
+              (e) => e.value == json['status'],
+              orElse: () => UiStatus.info,
+            )
+          : null,
+      items:
+          (json['items'] as List<dynamic>?)
+              ?.map((e) => ListItem.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+      pagination: json['pagination'] != null
+          ? Pagination.fromJson(json['pagination'] as Map<String, dynamic>)
+          : null,
+      emptyText: json['emptyText'] as String?,
+      extensions: json['extensions'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (status != null) 'status': status!.value,
+      'items': items.map((e) => e.toJson()).toList(),
+      if (pagination != null) 'pagination': pagination!.toJson(),
+      if (emptyText != null) 'emptyText': emptyText,
+      if (extensions != null) 'extensions': extensions,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiTableNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'table';
+  final String? title;
+  final String? description;
+  final UiIcon? icon;
+  final UiStatus? status;
+  final List<TableColumn> columns;
+  final List<TableRow> rows;
+  final Pagination? pagination;
+  final Map<String, dynamic>? extensions;
+  final List<UiAction>? actions;
+
+  const UiTableNode({
+    this.id,
+    this.title,
+    this.description,
+    this.icon,
+    this.status,
+    required this.columns,
+    required this.rows,
+    this.pagination,
+    this.extensions,
+    this.actions,
+  });
+
+  factory UiTableNode.fromJson(Map<String, dynamic> json) {
+    return UiTableNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      status: json['status'] != null
+          ? UiStatus.values.firstWhere(
+              (e) => e.value == json['status'],
+              orElse: () => UiStatus.info,
+            )
+          : null,
+      columns:
+          (json['columns'] as List<dynamic>?)
+              ?.map((e) => TableColumn.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+      rows:
+          (json['rows'] as List<dynamic>?)
+              ?.map((e) => TableRow.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+      pagination: json['pagination'] != null
+          ? Pagination.fromJson(json['pagination'] as Map<String, dynamic>)
+          : null,
+      extensions: json['extensions'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (status != null) 'status': status!.value,
+      'columns': columns.map((e) => e.toJson()).toList(),
+      'rows': rows.map((e) => e.toJson()).toList(),
+      if (pagination != null) 'pagination': pagination!.toJson(),
+      if (extensions != null) 'extensions': extensions,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiKvNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'kv';
+  final String? title;
+  final String? description;
+  final UiIcon? icon;
+  final UiStatus? status;
+  final List<KeyValuePair> pairs;
+  final KvLayout layout;
+  final Map<String, dynamic>? extensions;
+  final List<UiAction>? actions;
+
+  const UiKvNode({
+    this.id,
+    this.title,
+    this.description,
+    this.icon,
+    this.status,
+    required this.pairs,
+    this.layout = KvLayout.vertical,
+    this.extensions,
+    this.actions,
+  });
+
+  factory UiKvNode.fromJson(Map<String, dynamic> json) {
+    return UiKvNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      status: json['status'] != null
+          ? UiStatus.values.firstWhere(
+              (e) => e.value == json['status'],
+              orElse: () => UiStatus.info,
+            )
+          : null,
+      pairs:
+          (json['pairs'] as List<dynamic>?)
+              ?.map((e) => KeyValuePair.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+      layout: KvLayout.values.firstWhere(
+        (e) => e.value == json['layout'],
+        orElse: () => KvLayout.vertical,
+      ),
+      extensions: json['extensions'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (status != null) 'status': status!.value,
+      'pairs': pairs.map((e) => e.toJson()).toList(),
+      'layout': layout.value,
+      if (extensions != null) 'extensions': extensions,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiOperationNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'operation';
+  final String? title;
+  final String? description;
+  final UiIcon? icon;
+  final UiStatus? status;
+  final OperationType operation;
+  final OperationResult result;
+  final String? message;
+  final int? affectedCount;
+  final UiNode? details;
+  final UiAction? rollback;
+  final Map<String, dynamic>? extensions;
+  final List<UiAction>? actions;
+
+  const UiOperationNode({
+    this.id,
+    this.title,
+    this.description,
+    this.icon,
+    this.status,
+    required this.operation,
+    required this.result,
+    this.message,
+    this.affectedCount,
+    this.details,
+    this.rollback,
+    this.extensions,
+    this.actions,
+  });
+
+  factory UiOperationNode.fromJson(Map<String, dynamic> json) {
+    return UiOperationNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      description: json['description'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      status: json['status'] != null
+          ? UiStatus.values.firstWhere(
+              (e) => e.value == json['status'],
+              orElse: () => UiStatus.info,
+            )
+          : null,
+      operation: OperationType.values.firstWhere(
+        (e) => e.value == json['operation'],
+        orElse: () => OperationType.execute,
+      ),
+      result: OperationResult.values.firstWhere(
+        (e) => e.value == json['result'],
+        orElse: () => OperationResult.failure,
+      ),
+      message: json['message'] as String?,
+      affectedCount: json['affectedCount'] as int?,
+      details: json['details'] != null
+          ? UiNode.fromJson(json['details'] as Map<String, dynamic>)
+          : null,
+      rollback: json['rollback'] != null
+          ? UiAction.fromJson(json['rollback'] as Map<String, dynamic>)
+          : null,
+      extensions: json['extensions'] as Map<String, dynamic>?,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (description != null) 'description': description,
+      if (icon != null) 'icon': icon!.toJson(),
+      if (status != null) 'status': status!.value,
+      'operation': operation.value,
+      'result': result.value,
+      if (message != null) 'message': message,
+      if (affectedCount != null) 'affectedCount': affectedCount,
+      if (details != null) 'details': (details as dynamic).toJson(),
+      if (rollback != null) 'rollback': rollback!.toJson(),
+      if (extensions != null) 'extensions': extensions,
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiErrorNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'error';
+  final String? title;
+  final UiIcon? icon;
+  final String errorCode;
+  final String message;
+  final String? details;
+  final String? stack;
+  final bool retryable;
+  final List<String>? suggestions;
+  final UiAction? retry;
+  final UiAction? support;
+  final List<UiAction>? actions;
+
+  const UiErrorNode({
+    this.id,
+    this.title,
+    this.icon,
+    required this.errorCode,
+    required this.message,
+    this.details,
+    this.stack,
+    this.retryable = false,
+    this.suggestions,
+    this.retry,
+    this.support,
+    this.actions,
+  });
+
+  factory UiErrorNode.fromJson(Map<String, dynamic> json) {
+    return UiErrorNode(
+      id: json['id'] as String?,
+      title: json['title'] as String?,
+      icon: json['icon'] != null
+          ? UiIcon.fromJson(json['icon'] as Map<String, dynamic>)
+          : null,
+      errorCode: json['errorCode'] as String? ?? 'UNKNOWN',
+      message: json['message'] as String? ?? 'An error occurred',
+      details: json['details'] as String?,
+      stack: json['stack'] as String?,
+      retryable: json['retryable'] as bool? ?? false,
+      suggestions: (json['suggestions'] as List<dynamic>?)
+          ?.map((e) => e as String)
+          .toList(),
+      retry: json['retry'] != null
+          ? UiAction.fromJson(json['retry'] as Map<String, dynamic>)
+          : null,
+      support: json['support'] != null
+          ? UiAction.fromJson(json['support'] as Map<String, dynamic>)
+          : null,
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      if (title != null) 'title': title,
+      if (icon != null) 'icon': icon!.toJson(),
+      'errorCode': errorCode,
+      'message': message,
+      if (details != null) 'details': details,
+      if (stack != null) 'stack': stack,
+      'retryable': retryable,
+      if (suggestions != null) 'suggestions': suggestions,
+      if (retry != null) 'retry': retry!.toJson(),
+      if (support != null) 'support': support!.toJson(),
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}
+
+class UiContainerNode implements UiNode {
+  @override
+  final String? id;
+  @override
+  String get type => 'container';
+  final ContainerDirection direction;
+  final int? gap;
+  final List<UiNode> children;
+  final List<UiAction>? actions;
+
+  const UiContainerNode({
+    this.id,
+    this.direction = ContainerDirection.vertical,
+    this.gap,
+    required this.children,
+    this.actions,
+  });
+
+  factory UiContainerNode.fromJson(Map<String, dynamic> json) {
+    return UiContainerNode(
+      id: json['id'] as String?,
+      direction: ContainerDirection.values.firstWhere(
+        (e) => e.value == json['direction'],
+        orElse: () => ContainerDirection.vertical,
+      ),
+      gap: json['gap'] as int?,
+      children:
+          (json['children'] as List<dynamic>?)
+              ?.map((e) => UiNode.fromJson(e as Map<String, dynamic>))
+              .toList() ??
+          [],
+      actions: (json['actions'] as List<dynamic>?)
+          ?.map((e) => UiAction.fromJson(e as Map<String, dynamic>))
+          .toList(),
+    );
+  }
+
+  Map<String, dynamic> toJson() {
+    return {
+      'id': id,
+      'type': type,
+      'direction': direction.value,
+      if (gap != null) 'gap': gap,
+      'children': children.map((e) => (e as dynamic).toJson()).toList(),
+      if (actions != null) 'actions': actions!.map((e) => e.toJson()).toList(),
+    };
+  }
+}

apps/lib/core/ui_schema/models/ui_schema.dart

@@ -0,0 +1,14 @@
+// UI Schema Protocol Implementation.
+///
+/// This file is the single source of truth for UI Schema.
+/// All implementations must follow docs/protocols/ui-schema.md.
+///
+/// Version: 1.0
+library;
+
+part 'enums.dart';
+part 'common_types.dart';
+part 'actions.dart';
+part 'nodes.dart';
+part 'document.dart';
+part 'builders.dart';

apps/lib/core/ui_schema/navigation/ui_schema_navigation.dart

@@ -0,0 +1,35 @@
+bool isValidInternalNavigationPath(String path) {
+  if (path.isEmpty || !path.startsWith('/')) {
+    return false;
+  }
+  return !path.startsWith('//') &&
+      !path.contains('://') &&
+      !path.contains('?') &&
+      !path.contains('#') &&
+      !path.contains(':');
+}
+
+String buildUiSchemaNavigationTarget({
+  required String path,
+  Map<String, dynamic>? params,
+}) {
+  final baseUri = Uri.parse(path);
+  final queryParams = <String, String>{};
+
+  if (params != null) {
+    for (final entry in params.entries) {
+      final value = entry.value;
+      if (value is String && value.isNotEmpty) {
+        queryParams[entry.key] = value;
+      } else if (value is num || value is bool) {
+        queryParams[entry.key] = value.toString();
+      }
+    }
+  }
+
+  final mergedQueryParams = {...baseUri.queryParameters, ...queryParams};
+  final targetUri = baseUri.replace(
+    queryParameters: mergedQueryParams.isEmpty ? null : mergedQueryParams,
+  );
+  return targetUri.toString();
+}