@qingflow-tech/qingflow-cli 1.1.58 → 1.1.60

package/src/qingflow_mcp/cli/context.py

@@ -11,6 +11,7 @@ from ..tools.ai_builder_tools import AiBuilderTools
 from ..tools.app_tools import AppTools
 from ..tools.auth_tools import AuthTools
 from ..tools.code_block_tools import CodeBlockTools
+from ..tools.data_tools import DataTools
 from ..tools.export_tools import ExportTools
 from ..tools.feedback_tools import FeedbackTools
 from ..tools.file_tools import FileTools
@@ -33,6 +34,7 @@ class CliContext:
     app: AppTools
     resource: ResourceReadTools
     record: RecordTools
+    data: DataTools
     code_block: CodeBlockTools
     imports: ImportTools
     exports: ExportTools
@@ -64,6 +66,7 @@ def build_cli_context() -> CliContext:
         app=AppTools(sessions, backend),
         resource=ResourceReadTools(sessions, backend),
         record=RecordTools(sessions, backend),
+        data=DataTools(sessions, backend),
         code_block=CodeBlockTools(sessions, backend),
         imports=ImportTools(sessions, backend),
         exports=ExportTools(sessions, backend),

package/src/qingflow_mcp/cli/formatters.py

@@ -8,7 +8,10 @@ from typing import Any, TextIO
 def emit_text_result(result: dict[str, Any], *, hint: str, stream: TextIO) -> None:
     text = _format_cancelled_result(result)
     if text is None:
-        if _is_failed_result(result) and hint != "task_action_execute":
+        if hint in _DATA_FORMAT_HINTS:
+            # 数据面失败也必须保留 field_errors 与列表型 hints，不能先走通用失败裁剪。
+            text = _format_data_result(result)
+        elif _is_failed_result(result) and hint != "task_action_execute":
             text = _format_failed_result(result)
         else:
             formatter = _FORMATTERS.get(hint, _format_generic)
@@ -90,6 +93,92 @@ def _format_generic(result: dict[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _format_data_result(result: dict[str, Any]) -> str:
+    lines = [f"Status: {result.get('status') or ('success' if result.get('ok') is not False else 'failed')}"]
+    if result.get("format") == "csv":
+        files = result.get("files") if isinstance(result.get("files"), list) else []
+        lines.extend(
+            [
+                f"Local dir: {result.get('local_dir') or '-'}",
+                f"Files: {len(files)}",
+            ]
+        )
+        for item in files:
+            if isinstance(item, dict):
+                lines.append(
+                    f"- part {item.get('part')}: {item.get('local_path')} ({item.get('row_count')} rows)"
+                )
+        lines.extend(
+            [
+                f"Rows: {result.get('row_count')}",
+                f"Complete: {result.get('complete')}",
+                f"Truncated: {result.get('truncated')}",
+                f"Safe for final conclusion: {result.get('safe_for_final_conclusion')}",
+                f"Stopped reason: {result.get('stopped_reason') or '-'}",
+            ]
+        )
+    access = result.get("access") if isinstance(result.get("access"), dict) else {}
+    if access:
+        sources = access.get("scope_sources") if isinstance(access.get("scope_sources"), list) else []
+        lines.append(
+            f"Access: level={access.get('level') or '-'} / can_write={access.get('can_write')}"
+            f" / scope_sources={','.join(str(item) for item in sources) or '-'}"
+        )
+
+    records = result.get("records") if isinstance(result.get("records"), dict) else {}
+    if records:
+        items = records.get("items") if isinstance(records.get("items"), list) else []
+        lines.append(
+            "Pagination: "
+            f"page={records.get('page')} / requested_page_size={records.get('requested_page_size')} / "
+            f"page_size={records.get('page_size')} / total={records.get('total')} / "
+            f"has_more={records.get('has_more')} / returned={len(items)}"
+        )
+    record = result.get("record") if isinstance(result.get("record"), dict) else {}
+    if record:
+        lines.append(f"Record ID: {record.get('record_id') or '-'}")
+    items = result.get("items") if isinstance(result.get("items"), list) else []
+    if items:
+        lines.append(f"Items: {len(items)}")
+
+    for key, label in (
+        ("error_code", "Error Code"),
+        ("message", "Message"),
+        ("write_executed", "Write Executed"),
+        ("retry_safe", "Retry Safe"),
+    ):
+        if key in result:
+            lines.append(f"{label}: {result.get(key)}")
+
+    field_errors = result.get("field_errors") if isinstance(result.get("field_errors"), list) else []
+    if field_errors:
+        lines.append("Field Errors:")
+        _append_data_field_errors(lines, field_errors)
+    for index, item in enumerate(items):
+        if not isinstance(item, dict) or not isinstance(item.get("field_errors"), list):
+            continue
+        lines.append(f"Item {index} Field Errors:")
+        _append_data_field_errors(lines, item["field_errors"])
+
+    hints = result.get("hints") if isinstance(result.get("hints"), list) else []
+    lines.append(f"Hints: {len(hints)}")
+    for hint in hints:
+        if isinstance(hint, dict):
+            lines.append(f"- {hint.get('code') or '-'}: {hint.get('message') or '-'}")
+        else:
+            lines.append(f"- {hint}")
+    return "\n".join(lines) + "\n"
+
+
+def _append_data_field_errors(lines: list[str], field_errors: list[Any]) -> None:
+    for error in field_errors:
+        if isinstance(error, dict):
+            lines.append(
+                f"- {error.get('path') or '-'}: {error.get('message') or '-'}"
+                f" / fix_hint={error.get('fix_hint') or '-'}"
+            )
+
+
 def _format_whoami(result: dict[str, Any]) -> str:
     lines = [
         f"User: {result.get('nick_name') or '-'} ({result.get('email') or '-'})",
@@ -1669,4 +1758,11 @@ _FORMATTERS = {
     "builder_summary": _format_builder_summary,
     "file_upload_local": _format_file_upload_local,
     "feedback_submit": _format_feedback_submit,
+    "data_query": _format_data_result,
+    "data_get": _format_data_result,
+    "data_insert": _format_data_result,
+    "data_update": _format_data_result,
+    "data_delete": _format_data_result,
 }
+
+_DATA_FORMAT_HINTS = {"data_query", "data_get", "data_insert", "data_update", "data_delete"}

package/src/qingflow_mcp/public_surface.py

@@ -40,6 +40,11 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "workspace_select", ("workspace_select",), ("workspace", "select")),
     PublicToolSpec(USER_DOMAIN, "app_list", ("app_list",), ("app", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "app_get", ("app_get",), ("app", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "data_query", ("data_query",), ("data", "query"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "data_get", ("data_get",), ("data", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "data_insert", ("data_insert",), ("data", "insert"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "data_update", ("data_update",), ("data", "update"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "data_delete", ("data_delete",), ("data", "delete"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(USER_DOMAIN, "portal_list", ("portal_list",), ("portal", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "portal_get", ("portal_get",), ("portal", "get"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "view_get", ("view_get",), ("view", "get"), cli_show_effective_context=True),

package/src/qingflow_mcp/server.py

@@ -7,6 +7,7 @@ from mcp.server.fastmcp import FastMCP
 from .backend_client import BackendClient
 from .session_store import SessionStore
 from .tools.app_tools import AppTools
+from .tools.data_tools import DataTools
 from .tools.auth_tools import AuthTools
 from .tools.code_block_tools import CodeBlockTools
 from .tools.feedback_tools import FeedbackTools
@@ -249,6 +250,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     TaskContextTools(sessions, backend).register(server)
     RoleTools(sessions, backend).register(server)
     AppTools(sessions, backend).register(server)
+    DataTools(sessions, backend).register(server)
     QingbiReportTools(sessions, backend).register(server)
     PackageTools(sessions, backend).register(server)
     NavigationTools(sessions, backend).register(server)

package/src/qingflow_mcp/server_app_user.py

@@ -10,6 +10,7 @@ from .config import DEFAULT_PROFILE
 from .response_trim import USER_SERVER_METHOD_MAP, trim_error_response, trim_public_response, wrap_trimmed_methods
 from .session_store import SessionStore
 from .tools.app_tools import AppTools
+from .tools.data_tools import DataTools
 from .tools.auth_tools import AuthTools
 from .tools.code_block_tools import CodeBlockTools
 from .tools.directory_tools import DirectoryTools
@@ -242,6 +243,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     backend = BackendClient()
     auth = wrap_trimmed_methods(AuthTools(sessions, backend), USER_SERVER_METHOD_MAP)
     apps = wrap_trimmed_methods(AppTools(sessions, backend), USER_SERVER_METHOD_MAP)
+    data_tools = wrap_trimmed_methods(DataTools(sessions, backend), USER_SERVER_METHOD_MAP)
     workspace = wrap_trimmed_methods(WorkspaceTools(sessions, backend), USER_SERVER_METHOD_MAP)
     file_tools = wrap_trimmed_methods(FileTools(sessions, backend), USER_SERVER_METHOD_MAP)
     imports = wrap_trimmed_methods(ImportTools(sessions, backend), USER_SERVER_METHOD_MAP)
@@ -395,6 +397,8 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
         return apps.app_get(profile=profile, app_key=app_key)
 
+    data_tools.register(server)
+
     @server.tool()
     def portal_list(profile: str = DEFAULT_PROFILE) -> dict:
         return resources.portal_list(profile=profile)

package/src/qingflow_mcp/tools/csv_export.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import csv
+import json
+import time
+from pathlib import Path
+from typing import Any, Callable
+
+from ..json_types import JSONObject
+
+
+PageFetcher = Callable[[int, int], JSONObject]
+RowProjector = Callable[[JSONObject], list[str]]
+
+
+class CsvPageFailure(RuntimeError):
+    """后续分页返回结构化业务错误；已写文件保留为不完整结果。"""
+
+    def __init__(self, payload: JSONObject) -> None:
+        super().__init__(str(payload.get("message") or "分页请求失败"))
+        self.payload = payload
+
+
+class CsvShardWriter:
+    """视图无关的 UTF-8 BOM CSV 分片写入器。"""
+
+    def __init__(self, *, output_dir: Path, file_prefix: str, header: list[str], shard_rows: int) -> None:
+        self.output_dir = output_dir
+        self.file_prefix = file_prefix
+        self.header = header
+        self.shard_rows = shard_rows
+        self.files: list[JSONObject] = []
+        self.row_count = 0
+        self._part = 0
+        self._current_rows = 0
+        self._file: Any | None = None
+        self._writer: Any | None = None
+        output_dir.mkdir(parents=True, exist_ok=True)
+
+    def write(self, values: list[str]) -> None:
+        if self._current_rows >= self.shard_rows:
+            self.close_shard()
+        self._ensure_writer().writerow(values)
+        self._current_rows += 1
+        self.row_count += 1
+
+    def close_shard(self) -> None:
+        if self._file is None:
+            return
+        path = Path(self._file.name)
+        self._file.close()
+        self.files.append({"local_path": str(path), "row_count": self._current_rows, "part": len(self.files) + 1})
+        self._file = None
+        self._writer = None
+        self._current_rows = 0
+
+    def _ensure_writer(self) -> Any:
+        if self._writer is not None:
+            return self._writer
+        self._part += 1
+        path = self.output_dir / f"{self.file_prefix}-{self._part:04d}.csv"
+        self._file = path.open("w", newline="", encoding="utf-8-sig")
+        self._writer = csv.writer(self._file)
+        self._writer.writerow(self.header)
+        return self._writer
+
+
+def export_csv_pages(
+    *,
+    fetch_page: PageFetcher,
+    header: list[str],
+    project_row: RowProjector,
+    output_dir: Path,
+    file_prefix: str,
+    page_size: int,
+    shard_rows: int,
+    time_budget_seconds: float,
+) -> JSONObject:
+    """执行与业务权限无关的分页、CSV 分片和时间预算控制。"""
+    output_dir.mkdir(parents=True, exist_ok=True)
+    deadline = time.monotonic() + time_budget_seconds
+    files: list[JSONObject] = []
+    row_count = 0
+    fetched_pages = 0
+    current_page = 1
+    file_handle: Any | None = None
+    writer: Any | None = None
+    current_rows = 0
+    part = 0
+    has_more = False
+    stopped_reason: str | None = None
+    page_error: JSONObject | None = None
+
+    def close_file() -> None:
+        nonlocal file_handle, writer, current_rows
+        if file_handle is None:
+            return
+        path = Path(file_handle.name)
+        file_handle.close()
+        files.append({"local_path": str(path), "row_count": current_rows, "part": len(files) + 1})
+        file_handle = None
+        writer = None
+        current_rows = 0
+
+    def get_writer() -> Any:
+        nonlocal file_handle, writer, part
+        if writer is not None:
+            return writer
+        part += 1
+        path = output_dir / f"{file_prefix}-{part:04d}.csv"
+        file_handle = path.open("w", newline="", encoding="utf-8-sig")
+        writer = csv.writer(file_handle)
+        writer.writerow(header)
+        return writer
+
+    try:
+        while True:
+            page = fetch_page(current_page, page_size)
+            records = page.get("records") if isinstance(page, dict) else None
+            container = records if isinstance(records, dict) else page
+            raw_items = container.get("items", container.get("list", [])) if isinstance(container, dict) else []
+            items = raw_items if isinstance(raw_items, list) else []
+            has_more = bool(container.get("has_more")) if isinstance(container, dict) else False
+            for item in items:
+                if not isinstance(item, dict):
+                    continue
+                if current_rows >= shard_rows:
+                    close_file()
+                get_writer().writerow(project_row(item))
+                current_rows += 1
+                row_count += 1
+            fetched_pages += 1
+            if not has_more:
+                break
+            if time.monotonic() >= deadline:
+                stopped_reason = "TIME_BUDGET_EXCEEDED"
+                break
+            current_page += 1
+    except CsvPageFailure as exception:
+        stopped_reason = "PAGE_FETCH_FAILED"
+        page_error = exception.payload
+    except Exception:
+        # 已落盘分片仍是有效的部分结果；调用方据此禁止形成完整性结论。
+        stopped_reason = "PAGE_FETCH_FAILED"
+    finally:
+        close_file()
+
+    complete = stopped_reason is None and not has_more
+    result: JSONObject = {
+        "files": files,
+        "row_count": row_count,
+        "complete": complete,
+        "truncated": not complete,
+        "safe_for_final_conclusion": complete,
+        "fetched_pages": fetched_pages,
+        "stopped_reason": stopped_reason,
+    }
+    if page_error is not None:
+        result["page_error"] = page_error
+    return result
+
+
+def csv_cell(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, (dict, list)):
+        return json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+    return str(value)

package/src/qingflow_mcp/tools/data_tools.py

@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Literal, TypedDict
+
+from mcp.server.fastmcp import FastMCP
+
+from ..backend_client import BackendRequestContext
+from ..config import DEFAULT_PROFILE
+from ..errors import QingflowApiError, raise_tool_error
+from ..json_types import JSONObject, JSONValue
+from .base import ToolBase
+from .csv_export import CsvPageFailure, csv_cell, export_csv_pages
+
+
+DATA_PAGE_SIZE = 1000
+DATA_CSV_SHARD_ROWS = 20_000
+DATA_UNBOUNDED_ROW_THRESHOLD = 50_000
+DATA_CSV_TIME_BUDGET_SECONDS = 55.0
+
+DataFilterOperator = Literal[
+    "eq", "ne", "contains", "not_contains", "gt", "gte", "lt", "lte", "in", "not_in"
+]
+DataSortDirection = Literal["asc", "desc"]
+
+
+class DataWhereItem(TypedDict):
+    """数据面筛选项；in/not_in 使用数组，其余操作符使用单值。"""
+
+    field_id: int
+    op: DataFilterOperator
+    value: JSONValue
+
+
+class DataSortItem(TypedDict):
+    """数据面排序项。"""
+
+    field_id: int
+    direction: DataSortDirection
+
+
+class DataInsertItem(TypedDict):
+    """数据面新增项，fields 的键为字符串形式 field_id。"""
+
+    fields: dict[str, JSONValue]
+
+
+class DataTools(ToolBase):
+    """视图无关的应用数据面工具。"""
+
+    def register(self, mcp: FastMCP) -> None:
+        @mcp.tool()
+        def data_query(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            columns: list[int] | None = None,
+            where: list[DataWhereItem] | None = None,
+            sort: list[DataSortItem] | None = None,
+            search: str = "",
+            page: int = 1,
+            page_size: int = 100,
+            include_schema: bool = True,
+            all_pages: bool = False,
+            output: str = "json",
+        ) -> JSONObject:
+            """按字段 ID 查询应用数据；先读取 field_capabilities 再构造 where 和 sort。"""
+            return self.data_query(
+                profile=profile, app_key=app_key, columns=columns or [], where=where or [], sort=sort or [],
+                search=search, page=page, page_size=page_size, include_schema=include_schema,
+                all_pages=all_pages, output=output,
+            )
+
+        @mcp.tool()
+        def data_get(
+            profile: str = DEFAULT_PROFILE, app_key: str = "", record_id: str = "", include_schema: bool = True
+        ) -> JSONObject:
+            return self.data_get(profile=profile, app_key=app_key, record_id=record_id, include_schema=include_schema)
+
+        @mcp.tool()
+        def data_insert(
+            profile: str = DEFAULT_PROFILE, app_key: str = "", items: list[DataInsertItem] | None = None,
+            include_schema: bool = True,
+        ) -> JSONObject:
+            """新增应用数据；每项形如 {"fields": {"字段ID": 值}}。"""
+            return self.data_insert(profile=profile, app_key=app_key, items=items or [], include_schema=include_schema)
+
+        @mcp.tool()
+        def data_update(
+            profile: str = DEFAULT_PROFILE, app_key: str = "", record_id: str = "",
+            fields: dict | None = None, include_schema: bool = True,
+        ) -> JSONObject:
+            return self.data_update(
+                profile=profile, app_key=app_key, record_id=record_id, fields=fields or {},
+                include_schema=include_schema,
+            )
+
+        @mcp.tool()
+        def data_delete(
+            profile: str = DEFAULT_PROFILE, app_key: str = "", record_ids: list[str | int] | None = None,
+        ) -> JSONObject:
+            return self.data_delete(profile=profile, app_key=app_key, record_ids=record_ids or [])
+
+    def data_query(
+        self, *, profile: str, app_key: str, columns: list[int], where: list[DataWhereItem],
+        sort: list[DataSortItem],
+        search: str = "", page: int = 1, page_size: int = 100, include_schema: bool = True,
+        all_pages: bool = False, output: str = "json",
+    ) -> JSONObject:
+        self._require_app_key(app_key)
+        if all_pages and output != "csv":
+            raise_tool_error(QingflowApiError.config_error("all_pages 仅支持 output=csv"))
+
+        def runner(session_profile, context):
+            body: JSONObject = {
+                "page": page, "page_size": page_size, "columns": columns, "where": where, "sort": sort,
+                "search": search, "include_schema": include_schema,
+            }
+            if not all_pages:
+                return self._attach_context(
+                    self._request_data_plane(context, "POST", self._base_path(app_key) + "/query", json_body=body),
+                    profile, session_profile.selected_ws_id,
+                )
+            return self._export_all(
+                context=context, profile=profile, ws_id=session_profile.selected_ws_id, app_key=app_key,
+                body=body, has_scope=bool(where or search),
+            )
+
+        return self._run(profile, runner, tool_name="数据面查询")
+
+    def data_get(self, *, profile: str, app_key: str, record_id: str | int, include_schema: bool = True) -> JSONObject:
+        self._require_app_key(app_key)
+        self._require_record_id(record_id)
+        return self._run(
+            profile,
+            lambda session_profile, context: self._attach_context(
+                self._request_data_plane(
+                    context, "GET", f"{self._base_path(app_key)}/{record_id}",
+                    params={"include_schema": include_schema},
+                ), profile, session_profile.selected_ws_id,
+            ),
+            tool_name="数据面单条读取",
+        )
+
+    def data_insert(
+        self, *, profile: str, app_key: str, items: list[DataInsertItem], include_schema: bool = True
+    ) -> JSONObject:
+        self._require_app_key(app_key)
+        return self._write(profile, app_key, "POST", self._base_path(app_key), {"items": items, "include_schema": include_schema}, "数据面新增")
+
+    def data_update(
+        self, *, profile: str, app_key: str, record_id: str | int, fields: dict, include_schema: bool = True
+    ) -> JSONObject:
+        self._require_app_key(app_key)
+        self._require_record_id(record_id)
+        return self._write(
+            profile, app_key, "POST", f"{self._base_path(app_key)}/{record_id}/update",
+            {"fields": fields, "include_schema": include_schema}, "数据面更新",
+        )
+
+    def data_delete(self, *, profile: str, app_key: str, record_ids: list[str | int]) -> JSONObject:
+        self._require_app_key(app_key)
+        return self._write(profile, app_key, "POST", self._base_path(app_key) + "/delete", {"record_ids": record_ids}, "数据面删除")
+
+    def _write(self, profile: str, app_key: str, method: str, path: str, body: JSONObject, tool_name: str) -> JSONObject:
+        return self._run(
+            profile,
+            lambda session_profile, context: self._attach_context(
+                self._request_data_plane(context, method, path, json_body=body), profile, session_profile.selected_ws_id,
+            ),
+            tool_name=tool_name,
+        )
+
+    def _request_data_plane(
+        self, context: BackendRequestContext, method: str, path: str, *, params: JSONObject | None = None,
+        json_body: JSONValue = None,
+    ) -> JSONObject:
+        raw = self.backend.request(method, context, path, params=params, json_body=json_body, unwrap=False)
+        if not isinstance(raw, dict):
+            raise QingflowApiError(category="backend", message="数据面返回了非对象响应")
+        code = raw.get("code")
+        payload = raw.get("data")
+        result: JSONObject = dict(payload) if isinstance(payload, dict) else {}
+        success = code in (None, 0, 200, 20000) or str(code).lower() in {"success", "ok"}
+        result.setdefault("ok", success)
+        result.setdefault("status", "success" if success else "failed")
+        result.setdefault("hints", [])
+        if not success:
+            result.setdefault("message", str(raw.get("message") or raw.get("msg") or "数据面请求失败"))
+            result.setdefault("backend_code", code)
+        return result
+
+    def _export_all(
+        self, *, context: BackendRequestContext, profile: str, ws_id: int | None, app_key: str,
+        body: JSONObject, has_scope: bool,
+    ) -> JSONObject:
+        probe_body = dict(body)
+        probe_body.update({"page": 1, "page_size": 1, "include_schema": True})
+        probe = self._request_data_plane(context, "POST", self._base_path(app_key) + "/query", json_body=probe_body)
+        if probe.get("ok") is False:
+            # 探测请求没有产生文件，保留后端结构化错误，不把失败误报为空数据成功。
+            return self._attach_context(probe, profile, ws_id)
+        records = probe.get("records") if isinstance(probe.get("records"), dict) else {}
+        total = records.get("total") if isinstance(records, dict) else None
+        if isinstance(total, int) and total > DATA_UNBOUNDED_ROW_THRESHOLD and not has_scope:
+            return self._attach_context({
+                "ok": True, "status": "needs_scope", "app_key": app_key, "format": "csv", "row_count": 0,
+                "complete": False, "truncated": True, "safe_for_final_conclusion": False, "files": [],
+                "hints": probe.get("hints", []),
+                "schema": probe.get("schema", {}),
+                "field_capabilities": probe.get("field_capabilities", []),
+                "scope": {"reported_total": total, "row_threshold": DATA_UNBOUNDED_ROW_THRESHOLD},
+            }, profile, ws_id)
+        schema = probe.get("schema") if isinstance(probe.get("schema"), dict) else {}
+        fields = schema.get("fields") if isinstance(schema, dict) else None
+        field_list = fields if isinstance(fields, list) else []
+        business_fields = [field for field in field_list if isinstance(field, dict) and field.get("field_id") is not None]
+        columns = [(str(field.get("field_id")), str(field.get("title") or field.get("field_id"))) for field in business_fields]
+        header = ["record_id"] + [f"{title}__field_{field_id}" for field_id, title in columns]
+        run_dir = Path.home() / ".qingflow" / "data-exports" / datetime.now().strftime("%Y%m%d-%H%M%S-%f")
+        latest_hints = probe.get("hints", [])
+        latest_schema = schema
+        latest_capabilities = probe.get("field_capabilities", [])
+
+        def fetch_page(page: int, page_size: int) -> JSONObject:
+            nonlocal latest_hints, latest_schema, latest_capabilities
+            request_body = dict(body)
+            # 每页都请求 schema，使最后一页的后端原始 hints 同时准确表达完整性和字段能力。
+            request_body.update({"page": page, "page_size": page_size, "include_schema": True})
+            response = self._request_data_plane(
+                context, "POST", self._base_path(app_key) + "/query", json_body=request_body
+            )
+            if response.get("ok") is False:
+                raise CsvPageFailure(response)
+            latest_hints = response.get("hints", [])
+            if isinstance(response.get("schema"), dict):
+                latest_schema = response["schema"]
+            if isinstance(response.get("field_capabilities"), list):
+                latest_capabilities = response["field_capabilities"]
+            return response
+
+        def project_row(record: JSONObject) -> list[str]:
+            values = record.get("fields") if isinstance(record.get("fields"), dict) else record
+            return [str(record.get("record_id") or "")] + [csv_cell(values.get(field_id)) for field_id, _ in columns]
+
+        exported = export_csv_pages(
+            fetch_page=fetch_page, header=header, project_row=project_row, output_dir=run_dir,
+            file_prefix="records", page_size=DATA_PAGE_SIZE, shard_rows=DATA_CSV_SHARD_ROWS,
+            time_budget_seconds=DATA_CSV_TIME_BUDGET_SECONDS,
+        )
+        page_error = exported.pop("page_error", None)
+        result: JSONObject = {
+            "ok": True, "status": "success" if exported["complete"] else "partial", "app_key": app_key,
+            "format": "csv", "local_dir": str(run_dir), "fields": business_fields,
+            "schema": latest_schema, "field_capabilities": latest_capabilities, "hints": latest_hints,
+            **exported,
+        }
+        if isinstance(page_error, dict):
+            # 后续页失败时保留已落盘分片，同时把后端稳定错误字段原样带回。
+            result["ok"] = False
+            for key in ("error_code", "message", "backend_code", "write_executed", "retry_safe", "field_errors"):
+                if key in page_error:
+                    result[key] = page_error[key]
+            if "hints" in page_error:
+                result["hints"] = page_error["hints"]
+        return self._attach_context(result, profile, ws_id)
+
+    @staticmethod
+    def _base_path(app_key: str) -> str:
+        return f"/app/{app_key}/data/v1/records"
+
+    @staticmethod
+    def _attach_context(result: JSONObject, profile: str, ws_id: int | None) -> JSONObject:
+        return {"profile": profile, "ws_id": ws_id, **result}
+
+    @staticmethod
+    def _require_app_key(app_key: str) -> None:
+        if not str(app_key or "").strip():
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+
+    @staticmethod
+    def _require_record_id(record_id: str | int) -> None:
+        if not str(record_id or "").strip():
+            raise_tool_error(QingflowApiError.config_error("record_id is required"))