@josephyan/qingflow-cli 0.2.0-beta.1010 → 0.2.0-beta.1011

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@0.2.0-beta.1010
+npm install @josephyan/qingflow-cli@0.2.0-beta.1011
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@0.2.0-beta.1010 qingflow
+npx -y -p @josephyan/qingflow-cli@0.2.0-beta.1011 qingflow
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "0.2.0-beta.1010",
+  "version": "0.2.0-beta.1011",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b1010"
+version = "0.2.0b1011"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

@@ -5,7 +5,7 @@ from pathlib import Path
 
 __all__ = ["__version__"]
 
-_FALLBACK_VERSION = "0.2.0b1010"
+_FALLBACK_VERSION = "0.2.0b1011"
 
 
 def _resolve_local_pyproject_version() -> str | None:

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

@@ -3,6 +3,7 @@ from __future__ import annotations
 import argparse
 
 from ..context import CliContext
+from .common import load_list_arg
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -12,6 +13,11 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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("--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="查询导出状态")
@@ -26,16 +32,38 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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("--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 _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),
+        record_ids=_record_ids(args),
+        include_workflow_log=args.include_workflow_log,
     )
 
 
@@ -59,6 +87,9 @@ def _handle_direct(args: argparse.Namespace, context: CliContext) -> dict:
         profile=args.profile,
         app_key=args.app_key,
         view_id=args.view_id,
+        columns=_columns(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,
     )

package/src/qingflow_mcp/cli/formatters.py

@@ -426,6 +426,21 @@ def _format_export_common(result: dict[str, Any], *, title: str | None = None) -
             f"Rows: {result.get('num') if result.get('num') is not None else '-'}",
         ]
     )
+    row_scope = result.get("row_scope")
+    if row_scope not in (None, ""):
+        lines.append(f"Row Scope: {row_scope}")
+    selected_record_count = result.get("selected_record_count")
+    if selected_record_count not in (None, ""):
+        lines.append(f"Selected Rows: {selected_record_count}")
+    field_scope = result.get("field_scope")
+    if field_scope not in (None, ""):
+        lines.append(f"Field Scope: {field_scope}")
+    selected_field_count = result.get("selected_field_count")
+    if selected_field_count not in (None, ""):
+        lines.append(f"Selected Fields: {selected_field_count}")
+    include_workflow_log = result.get("include_workflow_log")
+    if include_workflow_log not in (None, ""):
+        lines.append(f"Include Workflow Log: {include_workflow_log}")
     file_names = result.get("file_names") if isinstance(result.get("file_names"), list) else []
     file_urls = result.get("file_urls") if isinstance(result.get("file_urls"), list) else []
     if file_names or file_urls:

package/src/qingflow_mcp/server.py

@@ -155,6 +155,13 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 
 - `record_export_direct` is the one-shot export path that starts the export, waits for completion, downloads locally, and still returns remote download links.
 - Export v1 supports record views only and follows the same public `view_id` semantics as `record_list` (`system:*` and `custom:*`).
+- `record_export_start` / `record_export_direct` support frontend-like row selection:
+  - omit `record_ids` to export all rows in the selected view
+  - pass `record_ids` to export selected rows only
+- `record_export_start` / `record_export_direct` also support frontend-like column selection:
+  - omit `columns` to export all current-view fields
+  - pass `columns` to export only selected fields, preserving the provided order
+- `include_workflow_log=true` maps to the native workflow-log export switch.
 
 ## Task Workflow Path
 

package/src/qingflow_mcp/server_app_user.py

@@ -150,6 +150,13 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 
 - `record_export_direct` is the one-shot path that starts export, waits, downloads locally, and still returns remote download links.
 - Export v1 supports record views only and follows the same public `view_id` semantics as `record_list`.
+- `record_export_start` / `record_export_direct` support frontend-like row selection:
+  - omit `record_ids` to export all rows in the selected view
+  - pass `record_ids` to export selected rows only
+- `record_export_start` / `record_export_direct` also support frontend-like column selection:
+  - omit `columns` to export all current-view fields
+  - pass `columns` to export only selected fields, preserving the provided order
+- `include_workflow_log=true` maps to the native workflow-log export switch.
 
 ## Task Workflow Path
 
@@ -233,8 +240,18 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
         view_id: str = "system:all",
+        columns: list[dict | int] | None = None,
+        record_ids: list[str | int] | None = None,
+        include_workflow_log: bool = False,
     ) -> dict:
-        return exports.record_export_start(profile=profile, app_key=app_key, view_id=view_id)
+        return exports.record_export_start(
+            profile=profile,
+            app_key=app_key,
+            view_id=view_id,
+            columns=columns or [],
+            record_ids=record_ids or [],
+            include_workflow_log=include_workflow_log,
+        )
 
     @server.tool()
     def record_export_status_get(
@@ -260,6 +277,9 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
         view_id: str = "system:all",
+        columns: list[dict | int] | None = None,
+        record_ids: list[str | int] | None = None,
+        include_workflow_log: bool = False,
         download_to_path: str | None = None,
         wait_timeout_seconds: float | None = None,
     ) -> dict:
@@ -267,6 +287,9 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
             profile=profile,
             app_key=app_key,
             view_id=view_id,
+            columns=columns or [],
+            record_ids=record_ids or [],
+            include_workflow_log=include_workflow_log,
             download_to_path=download_to_path,
             wait_timeout_seconds=wait_timeout_seconds,
         )

package/src/qingflow_mcp/tools/export_tools.py

@@ -11,12 +11,17 @@ from uuid import uuid4
 
 from mcp.server.fastmcp import FastMCP
 
-from ..config import DEFAULT_PROFILE
+from ..config import DEFAULT_PROFILE, DEFAULT_RECORD_LIST_TYPE
 from ..errors import QingflowApiError
 from ..export_store import ExportJobStore
 from ..json_types import JSONObject
 from .base import ToolBase, tool_cn_name
-from .record_tools import AccessibleViewRoute, LAYOUT_ONLY_QUE_TYPES, RecordTools
+from .record_tools import (
+    AccessibleViewRoute,
+    LAYOUT_ONLY_QUE_TYPES,
+    RecordTools,
+    _normalize_public_column_selectors,
+)
 
 
 EXPORT_STATUS_BY_PROCESS_STATUS = {
@@ -28,6 +33,8 @@ EXPORT_STATUS_BY_PROCESS_STATUS = {
 }
 DEFAULT_EXPORT_TIMEOUT_SECONDS = 60.0
 EXPORT_POLL_INTERVAL_SECONDS = 1.5
+EXPORT_ROWS_LIMIT = 20_000
+EXPORT_CELL_LIMIT = 4_000_000
 _SAFE_FILE_CHARS = re.compile(r"[^0-9A-Za-z._-]+")
 LOCAL_TIMEZONE = datetime.now().astimezone().tzinfo or timezone.utc
 
@@ -50,11 +57,17 @@ class ExportTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             view_id: str = "system:all",
+            columns: list[JSONObject | int] | None = None,
+            record_ids: list[str | int] | None = None,
+            include_workflow_log: bool = False,
         ) -> dict[str, Any]:
             return self.record_export_start(
                 profile=profile,
                 app_key=app_key,
                 view_id=view_id,
+                columns=columns or [],
+                record_ids=record_ids or [],
+                include_workflow_log=include_workflow_log,
             )
 
         @mcp.tool(description="Get asynchronous record export status by opaque export_handle.")
@@ -84,6 +97,9 @@ class ExportTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             view_id: str = "system:all",
+            columns: list[JSONObject | int] | None = None,
+            record_ids: list[str | int] | None = None,
+            include_workflow_log: bool = False,
             download_to_path: str | None = None,
             wait_timeout_seconds: float | None = None,
         ) -> dict[str, Any]:
@@ -91,6 +107,9 @@ class ExportTools(ToolBase):
                 profile=profile,
                 app_key=app_key,
                 view_id=view_id,
+                columns=columns or [],
+                record_ids=record_ids or [],
+                include_workflow_log=include_workflow_log,
                 download_to_path=download_to_path,
                 wait_timeout_seconds=wait_timeout_seconds,
             )
@@ -102,9 +121,14 @@ class ExportTools(ToolBase):
         profile: str = DEFAULT_PROFILE,
         app_key: str,
         view_id: str = "system:all",
+        columns: list[JSONObject | int] | None = None,
+        record_ids: list[str | int] | None = None,
+        include_workflow_log: bool = False,
     ) -> dict[str, Any]:
         normalized_app_key = str(app_key or "").strip()
         normalized_view_id = str(view_id or "").strip() or "system:all"
+        normalized_columns = _normalize_export_columns(columns or [])
+        normalized_record_ids = _normalize_export_record_ids(record_ids or [])
         if not normalized_app_key:
             return self._failed_export_result(
                 error_code="EXPORT_START_FAILED",
@@ -128,8 +152,24 @@ class ExportTools(ToolBase):
                 context=context,
                 app_key=normalized_app_key,
                 resolved_view=resolved_view,
+                column_selectors=normalized_columns,
+            )
+            result_amount = self._estimate_export_result_amount(
+                context,
+                app_key=normalized_app_key,
+                resolved_view=resolved_view,
+                selected_record_ids=normalized_record_ids,
+            )
+            self._validate_export_limits(
+                result_amount=result_amount,
+                selected_field_count=len(cast(list[JSONObject], export_config.get("questionExportConfigList") or [])),
+                include_workflow_log=include_workflow_log,
+            )
+            filter_bean = self._build_export_filter_bean(
+                resolved_view,
+                selected_record_ids=normalized_record_ids,
+                include_workflow_log=include_workflow_log,
             )
-            filter_bean = self._build_export_filter_bean(resolved_view)
             started_at = _utc_now().replace(microsecond=0).isoformat()
             socket_result = self.backend.start_socket_record_export(
                 context,
@@ -138,7 +178,10 @@ class ExportTools(ToolBase):
                 view_key=resolved_view.view_selection.view_key if resolved_view.view_selection is not None else None,
                 filter_bean=filter_bean,
                 export_config=export_config,
+                result_amount=result_amount,
             )
+            row_scope = "selected" if normalized_record_ids else "all"
+            column_scope = "selected" if normalized_columns else "all"
             export_handle = uuid4().hex
             self._job_store.put(
                 export_handle,
@@ -150,6 +193,11 @@ class ExportTools(ToolBase):
                     "backend_export_id": str(socket_result.get("backend_export_id") or ""),
                     "started_at": started_at,
                     "uid": session_profile.uid,
+                    "row_scope": row_scope,
+                    "selected_record_count": len(normalized_record_ids),
+                    "field_scope": column_scope,
+                    "selected_field_count": len(cast(list[JSONObject], export_config.get("questionExportConfigList") or [])),
+                    "include_workflow_log": bool(include_workflow_log),
                 },
             )
             warnings = [
@@ -163,6 +211,11 @@ class ExportTools(ToolBase):
                 "app_key": normalized_app_key,
                 "view_id": resolved_view.view_id,
                 "export_handle": export_handle,
+                "row_scope": row_scope,
+                "selected_record_count": len(normalized_record_ids),
+                "field_scope": column_scope,
+                "selected_field_count": len(cast(list[JSONObject], export_config.get("questionExportConfigList") or [])),
+                "include_workflow_log": bool(include_workflow_log),
                 "file_urls": [],
                 "file_names": [],
                 "downloaded_files": [],
@@ -170,6 +223,8 @@ class ExportTools(ToolBase):
                 "verification": {
                     "export_acknowledged": bool(socket_result.get("backend_export_id")),
                     "view_route_supported": True,
+                    "row_selection_applied": bool(normalized_record_ids),
+                    "field_selection_applied": bool(normalized_columns),
                 },
                 "request_route": self.backend.describe_route(context),
             }
@@ -253,6 +308,11 @@ class ExportTools(ToolBase):
                         "export_handle": normalized_handle,
                         "app_key": str(local_job.get("app_key") or ""),
                         "view_id": str(local_job.get("view_id") or ""),
+                        "row_scope": str(local_job.get("row_scope") or "all"),
+                        "selected_record_count": _coerce_int(local_job.get("selected_record_count")) or 0,
+                        "field_scope": str(local_job.get("field_scope") or "all"),
+                        "selected_field_count": _coerce_int(local_job.get("selected_field_count")),
+                        "include_workflow_log": bool(local_job.get("include_workflow_log")),
                         "file_urls": snapshot.get("file_urls") or [],
                         "file_names": snapshot.get("file_names") or [],
                         "downloaded_files": [],
@@ -270,6 +330,11 @@ class ExportTools(ToolBase):
                             "export_handle": normalized_handle,
                             "app_key": str(local_job.get("app_key") or ""),
                             "view_id": str(local_job.get("view_id") or ""),
+                            "row_scope": str(local_job.get("row_scope") or "all"),
+                            "selected_record_count": _coerce_int(local_job.get("selected_record_count")) or 0,
+                            "field_scope": str(local_job.get("field_scope") or "all"),
+                            "selected_field_count": _coerce_int(local_job.get("selected_field_count")),
+                            "include_workflow_log": bool(local_job.get("include_workflow_log")),
                             "file_urls": snapshot.get("file_urls") or [],
                             "file_names": snapshot.get("file_names") or [],
                             "downloaded_files": [],
@@ -308,6 +373,11 @@ class ExportTools(ToolBase):
                 "export_handle": normalized_handle,
                 "app_key": str(local_job.get("app_key") or ""),
                 "view_id": str(local_job.get("view_id") or ""),
+                "row_scope": str(local_job.get("row_scope") or "all"),
+                "selected_record_count": _coerce_int(local_job.get("selected_record_count")) or 0,
+                "field_scope": str(local_job.get("field_scope") or "all"),
+                "selected_field_count": _coerce_int(local_job.get("selected_field_count")),
+                "include_workflow_log": bool(local_job.get("include_workflow_log")),
                 "num": snapshot.get("num"),
                 "process_status": snapshot.get("process_status"),
                 "error_code": snapshot.get("error_code"),
@@ -336,6 +406,9 @@ class ExportTools(ToolBase):
         profile: str = DEFAULT_PROFILE,
         app_key: str,
         view_id: str = "system:all",
+        columns: list[JSONObject | int] | None = None,
+        record_ids: list[str | int] | None = None,
+        include_workflow_log: bool = False,
         download_to_path: str | None = None,
         wait_timeout_seconds: float | None = None,
     ) -> dict[str, Any]:
@@ -354,6 +427,9 @@ class ExportTools(ToolBase):
                 profile=profile,
                 app_key=normalized_app_key,
                 view_id=normalized_view_id,
+                columns=columns or [],
+                record_ids=record_ids or [],
+                include_workflow_log=include_workflow_log,
             )
             if not bool(start_result.get("ok")):
                 return start_result
@@ -395,6 +471,11 @@ class ExportTools(ToolBase):
                         "export_handle": export_handle,
                         "app_key": str(local_job.get("app_key") or ""),
                         "view_id": str(local_job.get("view_id") or ""),
+                        "row_scope": str(local_job.get("row_scope") or "all"),
+                        "selected_record_count": _coerce_int(local_job.get("selected_record_count")) or 0,
+                        "field_scope": str(local_job.get("field_scope") or "all"),
+                        "selected_field_count": _coerce_int(local_job.get("selected_field_count")),
+                        "include_workflow_log": bool(local_job.get("include_workflow_log")),
                         "num": snapshot.get("num"),
                         "process_status": snapshot.get("process_status"),
                         "audit_record_status": snapshot.get("audit_record_status"),
@@ -417,6 +498,11 @@ class ExportTools(ToolBase):
                             "export_handle": export_handle,
                             "app_key": str(local_job.get("app_key") or ""),
                             "view_id": str(local_job.get("view_id") or ""),
+                            "row_scope": str(local_job.get("row_scope") or "all"),
+                            "selected_record_count": _coerce_int(local_job.get("selected_record_count")) or 0,
+                            "field_scope": str(local_job.get("field_scope") or "all"),
+                            "selected_field_count": _coerce_int(local_job.get("selected_field_count")),
+                            "include_workflow_log": bool(local_job.get("include_workflow_log")),
                             "file_urls": snapshot.get("file_urls") or [],
                             "file_names": snapshot.get("file_names") or [],
                             "downloaded_files": [],
@@ -444,6 +530,11 @@ class ExportTools(ToolBase):
                 "export_handle": str(start_result.get("export_handle") or ""),
                 "app_key": normalized_app_key,
                 "view_id": str(start_result.get("view_id") or normalized_view_id),
+                "row_scope": start_result.get("row_scope") or ("selected" if record_ids else "all"),
+                "selected_record_count": start_result.get("selected_record_count") or 0,
+                "field_scope": start_result.get("field_scope") or ("selected" if columns else "all"),
+                "selected_field_count": start_result.get("selected_field_count"),
+                "include_workflow_log": start_result.get("include_workflow_log"),
                 "file_urls": (last_snapshot or {}).get("file_urls") or [],
                 "file_names": (last_snapshot or {}).get("file_names") or [],
                 "downloaded_files": [],
@@ -461,15 +552,23 @@ class ExportTools(ToolBase):
                 extra={"app_key": normalized_app_key, "view_id": normalized_view_id},
             )
 
-    def _build_export_filter_bean(self, resolved_view: AccessibleViewRoute) -> JSONObject:
+    def _build_export_filter_bean(
+        self,
+        resolved_view: AccessibleViewRoute,
+        *,
+        selected_record_ids: list[int],
+        include_workflow_log: bool,
+    ) -> JSONObject:
         filter_payload: JSONObject = {}
         if resolved_view.kind == "system" and resolved_view.list_type is not None:
             filter_payload["type"] = resolved_view.list_type
+        if selected_record_ids:
+            filter_payload["applyIds"] = selected_record_ids
         return {
             "filter": filter_payload,
             # Backend export code later auto-unboxes this field to primitive boolean.
-            # Sending explicit false avoids a null -> NPE -> 41100 failure path.
-            "auditRecordStatus": False,
+            # Always send an explicit boolean to avoid a null -> NPE -> 41100 failure path.
+            "auditRecordStatus": bool(include_workflow_log),
         }
 
     def _build_export_config(
@@ -479,6 +578,7 @@ class ExportTools(ToolBase):
         context,
         app_key: str,
         resolved_view: AccessibleViewRoute,
+        column_selectors: list[int],
     ) -> tuple[JSONObject, list[JSONObject]]:  # type: ignore[no-untyped-def]
         browse_scope = self._record_tools._build_browse_write_scope(
             profile,
@@ -507,9 +607,32 @@ class ExportTools(ToolBase):
                 for field in cast(Any, index).by_id.values()
                 if field.que_type not in LAYOUT_ONLY_QUE_TYPES
             ]
+        exportable_by_id = {field.que_id: field for field in ordered_visible_fields}
+        selected_fields: list[Any]
+        if column_selectors:
+            selected_fields = []
+            seen: set[int] = set()
+            for selector in column_selectors:
+                field = self._record_tools._resolve_field_selector(selector, index, location="export_columns")
+                if field.que_id in seen:
+                    continue
+                exportable_field = exportable_by_id.get(field.que_id)
+                if exportable_field is None:
+                    raise QingflowApiError.config_error(
+                        f"field '{field.que_title}' is not exportable in the selected view",
+                        details={
+                            "error_code": "EXPORT_FIELD_NOT_VISIBLE",
+                            "field_id": field.que_id,
+                            "view_id": resolved_view.view_id,
+                        },
+                    )
+                selected_fields.append(exportable_field)
+                seen.add(field.que_id)
+        else:
+            selected_fields = ordered_visible_fields
         question_export_config_list: list[JSONObject] = []
         warnings: list[JSONObject] = []
-        for field in ordered_visible_fields:
+        for field in selected_fields:
             if field.que_type is None:
                 warnings.append(
                     {
@@ -533,6 +656,61 @@ class ExportTools(ToolBase):
             )
         return {"questionExportConfigList": question_export_config_list}, warnings
 
+    def _estimate_export_result_amount(
+        self,
+        context,
+        *,
+        app_key: str,
+        resolved_view: AccessibleViewRoute,
+        selected_record_ids: list[int],
+    ) -> int:
+        if selected_record_ids:
+            return len(selected_record_ids)
+        page = self._record_tools._search_page(
+            context,
+            app_key=app_key,
+            view_selection=resolved_view.view_selection,
+            page_num=1,
+            page_size=1,
+            query_key=None,
+            match_rules=[],
+            sorts=[],
+            search_que_ids=None,
+            list_type=resolved_view.list_type if resolved_view.list_type is not None else DEFAULT_RECORD_LIST_TYPE,
+        )
+        result_amount = _effective_total(page, page_size=1)
+        if result_amount < 0:
+            result_amount = 0
+        return result_amount
+
+    def _validate_export_limits(
+        self,
+        *,
+        result_amount: int,
+        selected_field_count: int,
+        include_workflow_log: bool,
+    ) -> None:
+        if result_amount > EXPORT_ROWS_LIMIT:
+            raise QingflowApiError.config_error(
+                f"record export exceeds the native row limit of {EXPORT_ROWS_LIMIT}",
+                details={
+                    "error_code": "EXPORT_ROWS_LIMIT_EXCEEDED",
+                    "result_amount": result_amount,
+                    "row_limit": EXPORT_ROWS_LIMIT,
+                },
+            )
+        estimated_cells = max(result_amount, 0) * max(selected_field_count, 0)
+        if estimated_cells > EXPORT_CELL_LIMIT:
+            raise QingflowApiError.config_error(
+                f"record export exceeds the native cell limit of {EXPORT_CELL_LIMIT}",
+                details={
+                    "error_code": "EXPORT_CELLS_LIMIT_EXCEEDED",
+                    "estimated_cells": estimated_cells,
+                    "cell_limit": EXPORT_CELL_LIMIT,
+                    "include_workflow_log": include_workflow_log,
+                },
+            )
+
     def _resolve_export_snapshot(
         self,
         context,
@@ -651,6 +829,11 @@ class ExportTools(ToolBase):
             "export_handle": export_handle,
             "app_key": str(local_job.get("app_key") or ""),
             "view_id": str(local_job.get("view_id") or ""),
+            "row_scope": str(local_job.get("row_scope") or "all"),
+            "selected_record_count": _coerce_int(local_job.get("selected_record_count")) or 0,
+            "field_scope": str(local_job.get("field_scope") or "all"),
+            "selected_field_count": _coerce_int(local_job.get("selected_field_count")),
+            "include_workflow_log": bool(local_job.get("include_workflow_log")),
             "num": snapshot.get("num"),
             "process_status": snapshot.get("process_status"),
             "error_code": snapshot.get("error_code"),
@@ -884,6 +1067,40 @@ def _coerce_int(value: Any) -> int | None:
         return None
 
 
+def _normalize_export_columns(columns: list[JSONObject | int]) -> list[int]:
+    normalized: list[int] = []
+    for field_id in _normalize_public_column_selectors(columns):
+        if field_id not in normalized:
+            normalized.append(field_id)
+    return normalized
+
+
+def _normalize_export_record_ids(record_ids: list[str | int]) -> list[int]:
+    normalized: list[int] = []
+    seen: set[int] = set()
+    for item in record_ids:
+        record_id = _coerce_int(item)
+        if record_id is None or record_id <= 0 or record_id in seen:
+            continue
+        normalized.append(record_id)
+        seen.add(record_id)
+    return normalized
+
+
+def _effective_total(page: JSONObject, *, page_size: int) -> int:
+    rows = page.get("list")
+    returned_rows = len(rows) if isinstance(rows, list) else 0
+    reported = _coerce_int(page.get("total"))
+    if reported is None:
+        reported = _coerce_int(page.get("count"))
+    if reported is not None:
+        return max(reported, returned_rows)
+    page_amount = _coerce_int(page.get("pageAmount"))
+    if page_amount is not None:
+        return page_amount * page_size
+    return returned_rows
+
+
 def _resolve_download_targets(
     destination_hint: str,
     *,