@qingflow-tech/qingflow-app-user-mcp 1.0.3 → 1.0.5

package/src/qingflow_mcp/builder_facade/button_style_catalog.py

@@ -0,0 +1,282 @@
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any
+
+BUTTON_BACKGROUND_COLORS: tuple[str, ...] = (
+    "transparent",
+    "#FB9337",
+    "#FA6F32",
+    "#FAB300",
+    "#67C200",
+    "#00BD77",
+    "#00C5FB",
+    "#268BFB",
+    "#001A72",
+    "#9E64FB",
+    "#D164FB",
+    "#FB4B51",
+    "#FFFFFF",
+)
+
+BUTTON_TEXT_COLORS: tuple[str, ...] = (
+    "#FB9337",
+    "#FA6F32",
+    "#FAB300",
+    "#67C200",
+    "#00BD77",
+    "#00C5FB",
+    "#268BFB",
+    "#001A72",
+    "#9E64FB",
+    "#D164FB",
+    "#FB4B51",
+    "#494F57",
+    "#FFFFFF",
+)
+
+BUTTON_ICONS: tuple[str, ...] = (
+    "ex-print",
+    "ex-attachment",
+    "ex-handoff",
+    "ex-delete",
+    "ex-copy",
+    "ex-share",
+    "ex-edit2",
+    "ex-admin-outlined",
+    "ex-stamp",
+    "ex-kanban",
+    "ex-update",
+    "ex-tickincircle-outlined",
+    "ex-crossincircle-outlined",
+    "ex-plus-circle",
+    "ex-logout",
+    "ex-check",
+    "ex-rename",
+    "ex-locked",
+    "ex-shift",
+    "ex-new-tabpage",
+    "ex-cross",
+    "ex-switch",
+    "ex-layer",
+    "ex-import",
+    "ex-pin-outlined",
+    "ex-disabled",
+    "ex-duplicate",
+    "ex-heart-outlined",
+    "ex-plus",
+    "ex-save",
+    "ex-upload",
+    "ex-upgrade1",
+    "ex-downgrade",
+    "ex-unfold",
+    "ex-fold",
+    "ex-sort",
+    "ex-menu-control",
+    "ex-download",
+    "ex-insert-below",
+    "ex-left-outlined-double",
+    "ex-right-outlined-double",
+    "ex-recovery",
+    "ex-layout",
+    "ex-search",
+    "ex-preview",
+    "ex-invisible",
+    "ex-carboncopy",
+    "ex-basicInfo",
+    "ex-fillIn",
+    "ex-refresh",
+    "ex-display",
+    "ex-message",
+    "ex-edit",
+    "ex-heart-filled",
+    "ex-pin-filled",
+    "ex-transfer",
+    "ex-cross-circle",
+    "ex-clock",
+    "ex-admin-filled",
+    "ex-tickincircle-circle",
+    "ex-all-application",
+    "ex-help-filled",
+    "ex-streamline",
+    "ex-table",
+    "ex-rowheight-short",
+    "ex-rowheight-medium",
+    "ex-rowheight-tall",
+    "ex-rowheight-tallest",
+)
+
+BUTTON_STYLE_PRESETS: tuple[dict[str, Any], ...] = (
+    {
+        "key": "primary_blue",
+        "label": "Primary Blue",
+        "button_type": "default",
+        "background_color": "#268BFB",
+        "text_color": "#FFFFFF",
+        "recommended_icons": ["ex-plus-circle", "ex-plus"],
+    },
+    {
+        "key": "text_blue",
+        "label": "Text Blue",
+        "button_type": "text",
+        "background_color": "transparent",
+        "text_color": "#268BFB",
+        "recommended_icons": ["ex-share", "ex-new-tabpage"],
+    },
+    {
+        "key": "warning_orange",
+        "label": "Warning Orange",
+        "button_type": "default",
+        "background_color": "#FB9337",
+        "text_color": "#FFFFFF",
+        "recommended_icons": ["ex-message", "ex-clock"],
+    },
+    {
+        "key": "danger_red",
+        "label": "Danger Red",
+        "button_type": "default",
+        "background_color": "#FB4B51",
+        "text_color": "#FFFFFF",
+        "recommended_icons": ["ex-delete", "ex-cross-circle"],
+    },
+    {
+        "key": "neutral_outline",
+        "label": "Neutral Outline",
+        "button_type": "default",
+        "background_color": "#FFFFFF",
+        "text_color": "#494F57",
+        "recommended_icons": ["ex-edit", "ex-search"],
+    },
+    {
+        "key": "secondary_gray",
+        "label": "Secondary Gray",
+        "button_type": "text",
+        "background_color": "transparent",
+        "text_color": "#494F57",
+        "recommended_icons": ["ex-edit", "ex-search"],
+    },
+)
+
+_PRESET_BY_KEY: dict[str, dict[str, Any]] = {
+    str(item["key"]).strip(): dict(item) for item in BUTTON_STYLE_PRESETS
+}
+
+_COLOR_FAMILY_BY_VALUE: dict[str, str] = {
+    "transparent": "neutral",
+    "#FB9337": "orange",
+    "#FA6F32": "orange",
+    "#FAB300": "yellow",
+    "#67C200": "green",
+    "#00BD77": "green",
+    "#00C5FB": "cyan",
+    "#268BFB": "blue",
+    "#001A72": "blue",
+    "#9E64FB": "purple",
+    "#D164FB": "purple",
+    "#FB4B51": "red",
+    "#FFFFFF": "white",
+    "#494F57": "gray",
+}
+
+
+def _normalize_color_value(value: str | None) -> str | None:
+    normalized = str(value or "").strip()
+    if not normalized:
+        return None
+    lowered = normalized.lower().replace(" ", "")
+    if lowered == "transparent":
+        return "transparent"
+    if lowered in {
+        "#fff",
+        "#ffffff",
+        "white",
+        "rgb(255,255,255)",
+        "rgba(255,255,255,1)",
+    }:
+        return "#FFFFFF"
+    if normalized.startswith("#"):
+        return normalized.upper()
+    return normalized
+
+
+def button_style_catalog_payload() -> dict[str, Any]:
+    return {
+        "icons": [{"value": icon, "label": icon} for icon in BUTTON_ICONS],
+        "background_colors": [
+            {
+                "value": color,
+                "label": color,
+                "family": _COLOR_FAMILY_BY_VALUE.get(color, "custom"),
+            }
+            for color in BUTTON_BACKGROUND_COLORS
+        ],
+        "text_colors": [
+            {
+                "value": color,
+                "label": color,
+                "family": _COLOR_FAMILY_BY_VALUE.get(color, "custom"),
+            }
+            for color in BUTTON_TEXT_COLORS
+        ],
+        "presets": [deepcopy(item) for item in BUTTON_STYLE_PRESETS],
+    }
+
+
+def resolve_button_style(
+    *,
+    style_preset: str | None,
+    button_icon: str | None,
+    background_color: str | None,
+    text_color: str | None,
+    require_complete_style: bool,
+) -> dict[str, str | None]:
+    preset_key = str(style_preset or "").strip() or None
+    resolved_icon = str(button_icon or "").strip() or None
+    resolved_background = _normalize_color_value(background_color)
+    resolved_text = _normalize_color_value(text_color)
+
+    if preset_key is not None:
+        preset = _PRESET_BY_KEY.get(preset_key)
+        if preset is None:
+            raise ValueError(
+                "unsupported style_preset; use button_style_catalog_get to inspect available presets"
+            )
+        if resolved_background is None:
+            resolved_background = str(preset["background_color"])
+        if resolved_text is None:
+            resolved_text = str(preset["text_color"])
+        if resolved_icon is None:
+            recommended = preset.get("recommended_icons") or []
+            if recommended:
+                resolved_icon = str(recommended[0]).strip() or None
+
+    if require_complete_style:
+        missing: list[str] = []
+        if resolved_icon is None:
+            missing.append("button_icon")
+        if resolved_background is None:
+            missing.append("background_color")
+        if resolved_text is None:
+            missing.append("text_color")
+        if missing:
+            raise ValueError(f"button style requires {', '.join(missing)}")
+
+    if resolved_icon is not None and resolved_icon not in BUTTON_ICONS:
+        raise ValueError(
+            "unsupported button_icon; use button_style_catalog_get to inspect available icons"
+        )
+    if resolved_background is not None and resolved_background not in BUTTON_BACKGROUND_COLORS:
+        raise ValueError(
+            "unsupported background_color; current frontend only supports template colors from button_style_catalog_get"
+        )
+    if resolved_text is not None and resolved_text not in BUTTON_TEXT_COLORS:
+        raise ValueError(
+            "unsupported text_color; current frontend only supports template colors from button_style_catalog_get"
+        )
+
+    return {
+        "style_preset": preset_key,
+        "button_icon": resolved_icon,
+        "background_color": resolved_background,
+        "text_color": resolved_text,
+    }

package/src/qingflow_mcp/builder_facade/models.py

@@ -5,6 +5,7 @@ from typing import Any
 
 from pydantic import AliasChoices, Field, model_validator
 
+from .button_style_catalog import resolve_button_style
 from ..solution.spec_models import StrictModel
 
 
@@ -1180,10 +1181,10 @@ def _is_white_button_color(value: str | None) -> bool:
 
 class CustomButtonPatch(StrictModel):
     button_text: str = Field(validation_alias=AliasChoices("button_text", "buttonText"))
-    background_color: str = Field(validation_alias=AliasChoices("background_color", "backgroundColor"))
-    text_color: str = Field(validation_alias=AliasChoices("text_color", "textColor"))
-    button_icon: str = Field(validation_alias=AliasChoices("button_icon", "buttonIcon"))
-    icon_color: str | None = Field(default=None, validation_alias=AliasChoices("icon_color", "iconColor"))
+    background_color: str | None = Field(default=None, validation_alias=AliasChoices("background_color", "backgroundColor"))
+    text_color: str | None = Field(default=None, validation_alias=AliasChoices("text_color", "textColor"))
+    button_icon: str | None = Field(default=None, validation_alias=AliasChoices("button_icon", "buttonIcon"))
+    style_preset: str | None = Field(default=None, validation_alias=AliasChoices("style_preset", "stylePreset"))
     trigger_action: PublicButtonTriggerAction = Field(validation_alias=AliasChoices("trigger_action", "triggerAction"))
     trigger_link_url: str | None = Field(default=None, validation_alias=AliasChoices("trigger_link_url", "triggerLinkUrl"))
     trigger_add_data_config: CustomButtonAddDataConfigPatch | None = Field(
@@ -1204,8 +1205,29 @@ class CustomButtonPatch(StrictModel):
         validation_alias=AliasChoices("trigger_wings_config", "triggerWingsConfig"),
     )
 
+    @model_validator(mode="before")
+    @classmethod
+    def normalize_aliases(cls, value: Any) -> Any:
+        if not isinstance(value, dict):
+            return value
+        payload = dict(value)
+        if "icon_color" in payload or "iconColor" in payload:
+            raise ValueError("icon_color is not supported; icon color follows text_color")
+        return payload
+
     @model_validator(mode="after")
     def validate_shape(self) -> "CustomButtonPatch":
+        resolved = resolve_button_style(
+            style_preset=self.style_preset,
+            button_icon=self.button_icon,
+            background_color=self.background_color,
+            text_color=self.text_color,
+            require_complete_style=True,
+        )
+        self.style_preset = resolved["style_preset"]
+        self.button_icon = resolved["button_icon"]
+        self.background_color = resolved["background_color"]
+        self.text_color = resolved["text_color"]
         if self.trigger_action == PublicButtonTriggerAction.link and not str(self.trigger_link_url or "").strip():
             raise ValueError("link buttons require trigger_link_url")
         if self.trigger_action == PublicButtonTriggerAction.add_data and self.trigger_add_data_config is None:
@@ -1225,7 +1247,7 @@ class ViewButtonBindingPatch(StrictModel):
     button_id: int = Field(validation_alias=AliasChoices("button_id", "buttonId", "id"))
     button_text: str | None = Field(default=None, validation_alias=AliasChoices("button_text", "buttonText"))
     button_icon: str | None = Field(default=None, validation_alias=AliasChoices("button_icon", "buttonIcon"))
-    icon_color: str | None = Field(default=None, validation_alias=AliasChoices("icon_color", "iconColor"))
+    style_preset: str | None = Field(default=None, validation_alias=AliasChoices("style_preset", "stylePreset"))
     background_color: str | None = Field(default=None, validation_alias=AliasChoices("background_color", "backgroundColor"))
     text_color: str | None = Field(default=None, validation_alias=AliasChoices("text_color", "textColor"))
     trigger_action: str | None = Field(default=None, validation_alias=AliasChoices("trigger_action", "triggerAction"))
@@ -1244,6 +1266,8 @@ class ViewButtonBindingPatch(StrictModel):
         if not isinstance(value, dict):
             return value
         payload = dict(value)
+        if "icon_color" in payload or "iconColor" in payload:
+            raise ValueError("icon_color is not supported; icon color follows text_color")
         raw_button_type = payload.get("button_type", payload.get("buttonType"))
         if isinstance(raw_button_type, str):
             normalized_type = raw_button_type.strip().lower()
@@ -1265,6 +1289,21 @@ class ViewButtonBindingPatch(StrictModel):
 
     @model_validator(mode="after")
     def validate_shape(self) -> "ViewButtonBindingPatch":
+        require_complete_style = self.button_type == PublicViewButtonType.system or any(
+            str(value or "").strip()
+            for value in (self.style_preset, self.button_icon, self.background_color, self.text_color)
+        )
+        resolved = resolve_button_style(
+            style_preset=self.style_preset,
+            button_icon=self.button_icon,
+            background_color=self.background_color,
+            text_color=self.text_color,
+            require_complete_style=require_complete_style,
+        )
+        self.style_preset = resolved["style_preset"]
+        self.button_icon = resolved["button_icon"]
+        self.background_color = resolved["background_color"]
+        self.text_color = resolved["text_color"]
         if self.button_type == PublicViewButtonType.system:
             missing = [
                 field_name

package/src/qingflow_mcp/builder_facade/service.py

@@ -34,6 +34,7 @@ from ..tools.role_tools import RoleTools
 from ..tools.solution_tools import SolutionTools
 from ..tools.view_tools import ViewTools
 from ..tools.workflow_tools import WorkflowTools
+from .button_style_catalog import button_style_catalog_payload
 from .models import (
     AppChartsReadResponse,
     AppFieldsReadResponse,
@@ -2353,6 +2354,26 @@ class AiBuilderFacade:
             **match,
         }
 
+    def button_style_catalog_get(self, *, profile: str) -> JSONObject:
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "read button style catalog",
+            "normalized_args": {},
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "warnings": [],
+            "verification": {"button_style_catalog_verified": True},
+            "verified": True,
+            "profile": profile,
+            **button_style_catalog_payload(),
+        }
+
     def app_custom_button_list(self, *, profile: str, app_key: str) -> JSONObject:
         normalized_args = {"app_key": app_key}
         permission_outcomes: list[PermissionCheckOutcome] = []
@@ -8035,8 +8056,6 @@ def _serialize_custom_button_payload(payload: CustomButtonPatch) -> dict[str, An
         "buttonIcon": data["button_icon"],
         "triggerAction": data["trigger_action"],
     }
-    if str(data.get("icon_color") or "").strip():
-        serialized["iconColor"] = data["icon_color"]
     if str(data.get("trigger_link_url") or "").strip():
         serialized["triggerLinkUrl"] = data["trigger_link_url"]
     trigger_add_data_config = data.get("trigger_add_data_config")
@@ -8126,7 +8145,6 @@ def _normalize_custom_button_summary(item: dict[str, Any]) -> dict[str, Any]:
         "button_id": _coerce_positive_int(item.get("button_id") or item.get("buttonId") or item.get("id")),
         "button_text": str(item.get("button_text") or item.get("buttonText") or "").strip() or None,
         "button_icon": str(item.get("button_icon") or item.get("buttonIcon") or "").strip() or None,
-        "icon_color": str(item.get("icon_color") or item.get("iconColor") or "").strip() or None,
         "background_color": str(item.get("background_color") or item.get("backgroundColor") or "").strip() or None,
         "text_color": str(item.get("text_color") or item.get("textColor") or "").strip() or None,
         "used_in_chart_count": _coerce_nonnegative_int(item.get("used_in_chart_count") or item.get("userInChartCount")),
@@ -14887,7 +14905,6 @@ def _normalize_view_button_entry(entry: dict[str, Any]) -> dict[str, Any]:
     for public_key, source_key in (
         ("default_button_text", "defaultButtonText"),
         ("button_icon", "buttonIcon"),
-        ("icon_color", "iconColor"),
         ("background_color", "backgroundColor"),
         ("text_color", "textColor"),
         ("trigger_link_url", "triggerLinkUrl"),
@@ -14925,7 +14942,6 @@ def _normalize_view_buttons_for_compare(value: Any) -> list[dict[str, Any]]:
                 "button_id": normalized.get("button_id") if is_custom else None,
                 "button_text": normalized.get("button_text"),
                 "button_icon": normalized.get("button_icon"),
-                "icon_color": normalized.get("icon_color"),
                 "background_color": normalized.get("background_color"),
                 "text_color": normalized.get("text_color"),
                 "trigger_action": normalized.get("trigger_action"),
@@ -15000,7 +15016,6 @@ def _normalize_expected_view_buttons_for_compare(
                 for key in (
                     "button_text",
                     "button_icon",
-                    "icon_color",
                     "background_color",
                     "text_color",
                     "trigger_action",
@@ -15183,8 +15198,6 @@ def _serialize_view_button_binding(
     if binding.button_type in {PublicViewButtonType.system, PublicViewButtonType.custom}:
         dto["buttonText"] = binding.button_text
         dto["buttonIcon"] = binding.button_icon
-        if str(binding.icon_color or "").strip():
-            dto["iconColor"] = binding.icon_color
         dto["backgroundColor"] = binding.background_color
         dto["textColor"] = binding.text_color
         dto["triggerAction"] = binding.trigger_action

package/src/qingflow_mcp/cli/commands/__init__.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 import argparse
 
-from . import app, auth, builder, chart, imports, portal, record, task, view, workspace
+from . import app, auth, builder, chart, exports, imports, portal, record, task, view, workspace
 
 
 def register_all_commands(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -14,5 +14,6 @@ def register_all_commands(subparsers: argparse._SubParsersAction[argparse.Argume
     chart.register(subparsers)
     record.register(subparsers)
     imports.register(subparsers)
+    exports.register(subparsers)
     task.register(subparsers)
     builder.register(subparsers)

package/src/qingflow_mcp/cli/commands/app.py

@@ -3,6 +3,9 @@ from __future__ import annotations
 import argparse
 
 from ..context import CliContext
+from ..interaction import cancelled_result, resolve_interactive_selection
+from ..terminal_ui import SelectionOption
+from .common import raise_config_error
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -19,7 +22,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     search.set_defaults(handler=_handle_search, format_hint="app_search")
 
     get = app_subparsers.add_parser("get", help="读取应用可访问视图与导入能力")
-    get.add_argument("--app-key", required=True)
+    get.add_argument("--app-key", help="不传时在交互终端中选择应用")
     get.set_defaults(handler=_handle_get, format_hint="app_get")
 
 
@@ -37,4 +40,47 @@ def _handle_search(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
+    if not (args.app_key or "").strip():
+        selection = _choose_app_interactively(args, context)
+        if selection.status == "unavailable":
+            raise_config_error(
+                "app get requires --app-key, or an interactive terminal to choose an app",
+                fix_hint="Run `app list` to inspect visible apps, or retry with `--app-key APP_KEY`.",
+            )
+        if selection.status == "empty":
+            raise_config_error(
+                selection.message or "app get could not open a selector because no visible apps were returned.",
+                fix_hint="Run `app list` to confirm visible apps, or retry with `--app-key APP_KEY`.",
+            )
+        if selection.status == "cancelled":
+            return cancelled_result(selection.message or "已取消")
+        args.app_key = str(selection.value or "")
     return context.app.app_get(profile=args.profile, app_key=args.app_key)
+
+
+def _choose_app_interactively(args: argparse.Namespace, context: CliContext):
+    def load_options() -> list[SelectionOption[str]]:
+        result = context.app.app_list(profile=args.profile)
+        items = result.get("items") if isinstance(result, dict) and isinstance(result.get("items"), list) else []
+        options: list[SelectionOption[str]] = []
+        for item in items:
+            if not isinstance(item, dict):
+                continue
+            app_key = str(item.get("app_key") or "").strip()
+            if not app_key:
+                continue
+            app_name = str(item.get("app_name") or app_key).strip() or app_key
+            package_name = str(item.get("package_name") or "").strip()
+            hint = f"app_key={app_key}"
+            if package_name:
+                hint += f" · package={package_name}"
+            options.append(SelectionOption(value=app_key, label=app_name, hint=hint))
+        return options
+
+    return resolve_interactive_selection(
+        args,
+        title="选择应用",
+        unavailable_message="app get requires --app-key, or an interactive terminal to choose an app",
+        empty_message="app get could not open a selector because no visible apps were returned.",
+        load_options=load_options,
+    )

package/src/qingflow_mcp/cli/commands/builder.py

@@ -120,6 +120,9 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     button = builder_subparsers.add_parser("button", help="自定义按钮")
     button_subparsers = button.add_subparsers(dest="builder_button_command", required=True)
 
+    button_catalog = button_subparsers.add_parser("catalog", help="读取按钮样式目录")
+    button_catalog.set_defaults(handler=_handle_button_catalog, format_hint="builder_summary")
+
     button_list = button_subparsers.add_parser("list", help="列出自定义按钮")
     button_list.add_argument("--app-key", required=True)
     button_list.set_defaults(handler=_handle_button_list, format_hint="builder_summary")
@@ -362,6 +365,10 @@ def _handle_button_list(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_custom_button_list(profile=args.profile, app_key=args.app_key)
 
 
+def _handle_button_catalog(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.button_style_catalog_get(profile=args.profile)
+
+
 def _handle_button_get(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_custom_button_get(profile=args.profile, app_key=args.app_key, button_id=args.button_id)
 

package/src/qingflow_mcp/cli/commands/exports.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import argparse
+
+from ..context import CliContext
+from .common import load_list_arg
+
+
+def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    parser = subparsers.add_parser("export", help="导出")
+    export_subparsers = parser.add_subparsers(dest="export_command", required=True)
+
+    start = export_subparsers.add_parser("start", help="启动导出")
+    start.add_argument("--app-key", required=True)
+    start.add_argument("--view-id", default="system:all")
+    start.add_argument("--column", dest="columns", action="append", type=int, default=[], help="只导出这些 field_id；不传时导出当前视图全部字段")
+    start.add_argument("--columns-file", help="JSON/YAML list，内容与 --column 语义一致")
+    start.add_argument("--where-file", help="JSON/YAML list，内容与 record list 的 where DSL 一致；内部先查命中 record_id 再走原生导出")
+    start.add_argument("--order-by-file", help="JSON/YAML list，内容与 record list 的 order_by DSL 一致；内部查询和导出记录顺序保持一致")
+    start.add_argument("--record-id", dest="record_ids", action="append", default=[], help="只导出这些 record_id；不传时导出当前视图全部数据")
+    start.add_argument("--record-ids-file", help="JSON/YAML list，内容与 --record-id 语义一致")
+    start.add_argument("--include-workflow-log", action=argparse.BooleanOptionalAction, default=False, help="是否同时导出流程日志")
+    start.set_defaults(handler=_handle_start, format_hint="export_start")
+
+    status = export_subparsers.add_parser("status", help="查询导出状态")
+    status.add_argument("--export-handle", required=True)
+    status.set_defaults(handler=_handle_status, format_hint="export_status")
+
+    get = export_subparsers.add_parser("get", help="获取导出结果")
+    get.add_argument("--export-handle", required=True)
+    get.add_argument("--download-to-path")
+    get.set_defaults(handler=_handle_get, format_hint="export_get")
+
+    direct = export_subparsers.add_parser("direct", help="直接导出并下载")
+    direct.add_argument("--app-key", required=True)
+    direct.add_argument("--view-id", default="system:all")
+    direct.add_argument("--column", dest="columns", action="append", type=int, default=[], help="只导出这些 field_id；不传时导出当前视图全部字段")
+    direct.add_argument("--columns-file", help="JSON/YAML list，内容与 --column 语义一致")
+    direct.add_argument("--where-file", help="JSON/YAML list，内容与 record list 的 where DSL 一致；内部先查命中 record_id 再走原生导出")
+    direct.add_argument("--order-by-file", help="JSON/YAML list，内容与 record list 的 order_by DSL 一致；内部查询和导出记录顺序保持一致")
+    direct.add_argument("--record-id", dest="record_ids", action="append", default=[], help="只导出这些 record_id；不传时导出当前视图全部数据")
+    direct.add_argument("--record-ids-file", help="JSON/YAML list，内容与 --record-id 语义一致")
+    direct.add_argument("--include-workflow-log", action=argparse.BooleanOptionalAction, default=False, help="是否同时导出流程日志")
+    direct.add_argument("--download-to-path")
+    direct.add_argument("--wait-timeout-seconds", type=float)
+    direct.set_defaults(handler=_handle_direct, format_hint="export_direct")
+
+
+def _columns(args: argparse.Namespace) -> list[int | dict]:
+    columns: list[int | dict] = list(args.columns or [])
+    if args.columns_file:
+        columns.extend(load_list_arg(args.columns_file, option_name="--columns-file"))
+    return columns
+
+
+def _record_ids(args: argparse.Namespace) -> list[str | int]:
+    record_ids: list[str | int] = list(args.record_ids or [])
+    if args.record_ids_file:
+        record_ids.extend(load_list_arg(args.record_ids_file, option_name="--record-ids-file"))
+    return record_ids
+
+
+def _where(args: argparse.Namespace) -> list[dict]:
+    return load_list_arg(args.where_file, option_name="--where-file") if args.where_file else []
+
+
+def _order_by(args: argparse.Namespace) -> list[dict]:
+    return load_list_arg(args.order_by_file, option_name="--order-by-file") if args.order_by_file else []
+
+
+def _handle_start(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.exports.record_export_start(
+        profile=args.profile,
+        app_key=args.app_key,
+        view_id=args.view_id,
+        columns=_columns(args),
+        where=_where(args),
+        order_by=_order_by(args),
+        record_ids=_record_ids(args),
+        include_workflow_log=args.include_workflow_log,
+    )
+
+
+def _handle_status(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.exports.record_export_status_get(
+        profile=args.profile,
+        export_handle=args.export_handle,
+    )
+
+
+def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.exports.record_export_get(
+        profile=args.profile,
+        export_handle=args.export_handle,
+        download_to_path=args.download_to_path,
+    )
+
+
+def _handle_direct(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.exports.record_export_direct(
+        profile=args.profile,
+        app_key=args.app_key,
+        view_id=args.view_id,
+        columns=_columns(args),
+        where=_where(args),
+        order_by=_order_by(args),
+        record_ids=_record_ids(args),
+        include_workflow_log=args.include_workflow_log,
+        download_to_path=args.download_to_path,
+        wait_timeout_seconds=args.wait_timeout_seconds,
+    )