@qingflow-tech/qingflow-cli 1.1.48-beta.5 → 1.1.49

package/src/qingflow_mcp/resource_uri.py

@@ -1,241 +0,0 @@
-from __future__ import annotations
-
-import re
-from collections.abc import Iterator
-from contextlib import contextmanager
-from contextvars import ContextVar
-from dataclasses import dataclass
-from typing import Any
-from urllib.parse import quote, unquote, urlsplit, urlunsplit
-
-from .config import DEFAULT_WEB_BASE_URL, get_web_base_url
-from .errors import QingflowApiError
-from .json_types import JSONObject
-
-
-SYSTEM_VIEW_NAMES = frozenset({"all", "initiated", "todo", "done", "cc"})
-_ENCODED_OCTET = re.compile(r"%[0-9A-Fa-f]{2}")
-_CLI_RESOURCE_BASE_URL: ContextVar[str | None] = ContextVar(
-    "qingflow_cli_resource_base_url",
-    default=None,
-)
-
-
-@dataclass(frozen=True, slots=True)
-class ResourcePath:
-    resource_type: str
-    ws_id: int
-    package_id: int | None = None
-    app_key: str | None = None
-    view_kind: str | None = None
-    view_key: str | None = None
-
-
-@contextmanager
-def cli_resource_base_url(value: str) -> Iterator[None]:
-    """让一次 CLI 调用的资源 URI 使用 QINGFLOW_BASE_URL 对应的网页环境。"""
-    token = _CLI_RESOURCE_BASE_URL.set(value)
-    try:
-        yield
-    finally:
-        _CLI_RESOURCE_BASE_URL.reset(token)
-
-
-def validate_resource_identity(value: object, field: str = "resource_id") -> str:
-    """按资源 URI 单路径段合同校验并返回规范身份，不读取网页域名配置。"""
-    return _validate_identity(value, field)
-
-
-def validate_positive_resource_id(value: object, field: str = "resource_id") -> int:
-    """按资源 URI 数字路径段合同校验正整数，不接受布尔值或浮点截断。"""
-    return int(_positive_int_segment(value, field))
-
-
-def build_resource_uri(
-    *,
-    ws_id: object,
-    resource_type: str,
-    package_id: object = None,
-    app_key: object = None,
-    view_kind: str | None = None,
-    view_key: object = None,
-    web_origin: str | None = None,
-) -> str:
-    """按固定公共合同构造资源 URI，不接受通用目标路由。"""
-    workspace = _positive_int_segment(ws_id, "ws_id")
-    if resource_type == "package":
-        path = f"/resources/ws/{workspace}/package/{_positive_int_segment(package_id, 'package_id')}"
-    elif resource_type == "app":
-        path = f"/resources/ws/{workspace}/app/{_identity_segment(app_key, 'app_key')}"
-    elif resource_type == "view":
-        app_segment = _identity_segment(app_key, "app_key")
-        if view_kind == "custom":
-            view_segment = _identity_segment(view_key, "view_key")
-        elif view_kind == "system":
-            name = str(view_key or "").strip()
-            if name not in SYSTEM_VIEW_NAMES:
-                raise ValueError("system view name is not supported")
-            view_segment = name
-        else:
-            raise ValueError("view_kind must be custom or system")
-        path = f"/resources/ws/{workspace}/app/{app_segment}/view/{view_kind}/{view_segment}"
-    else:
-        raise ValueError("resource_type is not supported")
-    return f"{resolve_resource_web_origin(web_origin)}{path}"
-
-
-def parse_resource_path(value: str) -> ResourcePath:
-    """严格解析资源 pathname，供免登录签发前校验工作区。"""
-    try:
-        parsed = urlsplit(value)
-        if parsed.scheme or parsed.netloc or parsed.query or parsed.fragment or parsed.path != value:
-            raise ValueError
-        parts = parsed.path.split("/")
-        if len(parts) < 6 or parts[:3] != ["", "resources", "ws"]:
-            raise ValueError
-        ws_id = int(_decode_segment(parts[3], "ws_id"))
-        if ws_id <= 0:
-            raise ValueError
-        if len(parts) == 6 and parts[4] == "package":
-            package_id = int(_decode_segment(parts[5], "package_id"))
-            if package_id <= 0:
-                raise ValueError
-            return ResourcePath("package", ws_id, package_id=package_id)
-        if len(parts) == 6 and parts[4] == "app":
-            return ResourcePath("app", ws_id, app_key=_decode_segment(parts[5], "app_key"))
-        if len(parts) == 9 and parts[4] == "app" and parts[6] == "view":
-            app_key = _decode_segment(parts[5], "app_key")
-            view_kind = parts[7]
-            view_key = _decode_segment(parts[8], "view_key")
-            if view_kind == "system" and view_key not in SYSTEM_VIEW_NAMES:
-                raise ValueError
-            if view_kind not in {"custom", "system"}:
-                raise ValueError
-            return ResourcePath("view", ws_id, app_key=app_key, view_kind=view_kind, view_key=view_key)
-    except (TypeError, ValueError, UnicodeError):
-        pass
-    raise ValueError("resource path is invalid")
-
-
-def try_build_resource_uri(**kwargs: Any) -> tuple[str | None, JSONObject | None]:
-    try:
-        return build_resource_uri(**kwargs), None
-    except (QingflowApiError, ValueError, UnicodeError) as error:
-        return None, {
-            "code": "RESOURCE_URI_UNAVAILABLE",
-            "message": f"resource URI was omitted because its identity or web origin is invalid: {error}",
-        }
-
-
-def _positive_int_segment(value: object, field: str) -> str:
-    if isinstance(value, bool):
-        raise ValueError(f"{field} must be a positive integer")
-    try:
-        parsed = int(value)
-    except (TypeError, ValueError):
-        raise ValueError(f"{field} must be a positive integer") from None
-    if parsed <= 0 or str(value).strip() != str(parsed):
-        raise ValueError(f"{field} must be a positive integer")
-    return str(parsed)
-
-
-def _normalize_web_origin(value: str) -> str:
-    try:
-        parsed = urlsplit(value.strip())
-        if (
-            parsed.scheme not in {"http", "https"}
-            or not parsed.hostname
-            or parsed.username is not None
-            or parsed.password is not None
-            or parsed.path not in {"", "/"}
-            or parsed.query
-            or parsed.fragment
-            or any(character.isspace() or ord(character) < 32 for character in value)
-        ):
-            raise ValueError
-        _ = parsed.port
-    except (AttributeError, ValueError):
-        raise ValueError("web_origin must be an absolute HTTP(S) origin") from None
-    return urlunsplit((parsed.scheme, parsed.netloc, "", "", ""))
-
-
-def resolve_resource_web_origin(web_origin: str | None = None) -> str:
-    """解析当前调用面的网页根地址；CLI 与 MCP 分别沿用各自的环境配置。"""
-    if web_origin is not None:
-        return _normalize_web_origin(web_origin)
-    cli_base_url = _CLI_RESOURCE_BASE_URL.get()
-    if cli_base_url is None:
-        return get_web_base_url()
-    return _web_origin_from_api_base_url(cli_base_url)
-
-
-def _web_origin_from_api_base_url(value: str) -> str:
-    normalized = value.strip()
-    if not normalized:
-        return DEFAULT_WEB_BASE_URL
-    try:
-        parsed = urlsplit(normalized)
-        host = parsed.hostname or ""
-        valid_host = bool(host) and (":" in host or all(
-            re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?", label)
-            for label in host.rstrip(".").split(".")
-        ))
-        if (
-            parsed.scheme not in {"http", "https"}
-            or not valid_host
-            or host.lower() in {"null", "undefined"}
-            or parsed.username is not None
-            or parsed.password is not None
-            or parsed.query
-            or parsed.fragment
-            or any(character.isspace() or ord(character) < 32 for character in normalized)
-        ):
-            raise ValueError
-        _ = parsed.port
-        return _normalize_web_origin(urlunsplit((parsed.scheme, parsed.netloc, "", "", "")))
-    except ValueError:
-        raise QingflowApiError.config_error(
-            "QINGFLOW_BASE_URL 必须是有效的 HTTP(S) API 地址，不包含查询参数、片段或用户凭证"
-        ) from None
-
-
-def _identity_segment(value: object, field: str) -> str:
-    raw = _validate_identity(value, field)
-    return quote(raw, safe="")
-
-
-def _decode_segment(value: str, field: str) -> str:
-    decoded = _validate_identity(unquote(value, errors="strict"), field)
-    if quote(decoded, safe="") != value:
-        raise ValueError(f"{field} must use canonical path encoding")
-    return decoded
-
-
-def _validate_identity(value: object, field: str) -> str:
-    source = str(value or "")
-    if any(ord(character) < 32 or ord(character) == 127 for character in source):
-        raise ValueError(f"{field} must be one safe path segment")
-    raw = source.strip()
-    if not raw:
-        raise ValueError(f"{field} is required")
-    current = raw
-    for _ in range(8):
-        if (
-            current in {".", ".."}
-            or any(character in current for character in "/\\?#")
-            or any(ord(character) < 32 or ord(character) == 127 for character in current)
-        ):
-            raise ValueError(f"{field} must be one safe path segment")
-        decoded = unquote(current, errors="strict")
-        if decoded == current:
-            return raw
-        current = decoded
-    if (
-        current in {".", ".."}
-        or any(character in current for character in "/\\?#")
-        or any(ord(character) < 32 or ord(character) == 127 for character in current)
-    ):
-        raise ValueError(f"{field} must be one safe path segment")
-    if _ENCODED_OCTET.search(current):
-        raise ValueError(f"{field} has excessive encoding")
-    return raw

package/src/qingflow_mcp/tools/csv_export.py

@@ -1,168 +0,0 @@
-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

@@ -1,271 +0,0 @@
-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", []),
-                "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")
-
-        def fetch_page(page: int, page_size: int) -> JSONObject:
-            request_body = dict(body)
-            request_body.update({"page": page, "page_size": page_size, "include_schema": page == 1})
-            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)
-            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, "hints": probe.get("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"))