@qingflow-tech/qingflow-cli 1.1.59 → 1.1.61-beta.1

package/src/qingflow_mcp/tools/data_tools.py

@@ -0,0 +1,313 @@
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Literal
+
+from mcp.server.fastmcp import FastMCP
+from typing_extensions import TypedDict
+
+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
+from .data_files import download_data_attachments
+
+
+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。
+
+            查询不下载附件；需要下载时对目标 app_key、record_id 调用
+            data_get(download_attachments=true)，使用 file_assets.items[].local_path。
+            """
+            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,
+            download_attachments: bool = False,
+        ) -> JSONObject:
+            """读取单条应用数据；需要下载附件或图片时设置 download_attachments=true，
+            保留 include_schema=true，并使用 file_assets.items[].local_path。
+            下载复用当前登录身份，通过数据面刷新链接；不需要 view_id，也不调用 record_get。
+            默认只读取字段；file_assets.status=partial 表示部分附件下载失败，请读取 warnings。
+            """
+            return self.data_get(
+                profile=profile, app_key=app_key, record_id=record_id, include_schema=include_schema,
+                download_attachments=download_attachments,
+            )
+
+        @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,
+        download_attachments: bool = False,
+    ) -> JSONObject:
+        self._require_app_key(app_key)
+        self._require_record_id(record_id)
+        if download_attachments and not include_schema:
+            raise_tool_error(QingflowApiError.config_error("下载附件需要 schema，请保留 include_schema=true（不要使用 --no-schema）"))
+
+        def runner(session_profile, context):
+            def read_record():
+                return self._request_data_plane(
+                    context, "GET", f"{self._base_path(app_key)}/{record_id}",
+                    params={"include_schema": include_schema},
+                )
+
+            result = read_record()
+            if download_attachments and result.get("ok") is not False:
+                if not isinstance(result.get("record"), dict) or not isinstance(result.get("schema"), dict):
+                    raise QingflowApiError(category="backend", message="下载附件需要数据面返回 record 和 schema")
+                result["file_assets"] = download_data_attachments(
+                    backend=self.backend, context=context, record=result.get("record", {}),
+                    schema=result.get("schema", {}), refresh_record=read_record,
+                )
+            return self._attach_context(result, profile, session_profile.selected_ws_id)
+
+        return self._run(profile, runner, 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"))

package/src/qingflow_mcp/tools/record_tools.py

@@ -1,6 +1,5 @@
 from __future__ import annotations
 
-import csv
 import html
 import mimetypes
 import json
@@ -34,6 +33,11 @@ from ..list_type_labels import (
 )
 from .base import ToolBase
 from .directory_tools import _directory_has_more, _directory_items
+from .csv_export import CsvShardWriter
+from .storage_download import (
+    download_storage_content, environment_cookie_prefix, is_storage_url,
+    requires_storage_cookie, storage_auth_type,
+)
 
 
 DEFAULT_QUERY_PAGE_SIZE = 50
@@ -2284,57 +2288,22 @@ class RecordTools(ToolBase):
                 }
 
             run_dir = _record_access_run_dir()
-            run_dir.mkdir(parents=True, exist_ok=True)
             header = ["record_id"] + [str(field["column_name"]) for field in fields_payload]
-            files: list[JSONObject] = []
-            shard_part = 0
-            shard_rows = 0
-            row_count = 0
-            file_handle: Any | None = None
-            writer: Any | None = None
-
-            def close_shard() -> None:
-                nonlocal file_handle, writer, shard_rows
-                if file_handle is None:
-                    return
-                path = Path(file_handle.name)
-                file_handle.close()
-                files.append(
-                    {
-                        "local_path": str(path),
-                        "row_count": shard_rows,
-                        "part": len(files) + 1,
-                    }
-                )
-                file_handle = None
-                writer = None
-                shard_rows = 0
-
-            def ensure_writer() -> Any:
-                nonlocal file_handle, writer, shard_part
-                if writer is not None:
-                    return writer
-                shard_part += 1
-                path = run_dir / f"records-{shard_part:04d}.csv"
-                file_handle = path.open("w", newline="", encoding="utf-8-sig")
-                writer = csv.writer(file_handle)
-                writer.writerow(header)
-                return writer
+            shard_writer = CsvShardWriter(
+                output_dir=run_dir,
+                file_prefix="records",
+                header=header,
+                shard_rows=DEFAULT_RECORD_ACCESS_SHARD_ROWS,
+            )
 
             def write_record(apply_id: int | None, answer_list: list[JSONValue]) -> None:
-                nonlocal row_count, shard_rows
                 if apply_id is None:
                     return
-                if shard_rows >= DEFAULT_RECORD_ACCESS_SHARD_ROWS:
-                    close_shard()
-                csv_writer = ensure_writer()
                 values: list[str] = [_public_record_id_text(apply_id) or ""]
                 for field in selected_fields:
                     answer = _find_answer_for_field(answer_list, field)
                     values.append(_record_access_csv_cell(_normalize_answer_field_value_for_output(answer, field)))
-                csv_writer.writerow(values)
-                row_count += 1
-                shard_rows += 1
+                shard_writer.write(values)
 
             current_page = 1
             has_more = False
@@ -2374,7 +2343,7 @@ class RecordTools(ToolBase):
                         break
                     page = fetch_page(current_page, BACKEND_RECORD_ACCESS_PAGE_SIZE)
             finally:
-                close_shard()
+                shard_writer.close_shard()
 
             if stopped_reason == "TIME_BUDGET_EXCEEDED":
                 warnings.append(_record_access_time_budget_warning(reported_total=reported_total, fetched_pages=fetched_pages))
@@ -2399,11 +2368,11 @@ class RecordTools(ToolBase):
                 "view_id": view_route.view_id,
                 "format": "csv",
                 "local_dir": str(run_dir),
-                "row_count": row_count,
+                "row_count": shard_writer.row_count,
                 "complete": complete,
                 "truncated": not complete,
                 "safe_for_final_conclusion": safe_for_final_conclusion,
-                "files": files,
+                "files": shard_writer.files,
                 "fields": fields_payload,
                 "warnings": warnings,
                 "verification": verification_payload,
@@ -17272,40 +17241,10 @@ def _record_detail_download_resolved_media_content(
     environment_prefix_cache: dict[str, str],
     requested_strategy: str,
 ) -> tuple[bytes, JSONObject]:
-    storage_auth_type = _record_detail_storage_auth_type(source_url)
-    if _record_detail_should_use_storage_cookie(source_url, storage_auth_type):
-        storage_cookie_prefix = _record_detail_environment_prefix(
-            backend,
-            context,
-            warnings=warnings,
-            environment_prefix_cache=environment_prefix_cache,
-        )
-        cookie_name = f"{storage_cookie_prefix}token"
-        headers = _record_detail_media_download_headers(context)
-        if hasattr(backend, "download_binary_with_cookie"):
-            response = backend.download_binary_with_cookie(context, source_url, cookie_name=cookie_name, headers=headers)
-            return response.content, {
-                "download_strategy": requested_strategy,
-                "storage_auth_type": storage_auth_type,
-                "storage_cookie_prefix": storage_cookie_prefix,
-                "redirected": bool(getattr(response, "redirected", False)),
-            }
-        cookie_headers = dict(headers)
-        cookie_headers["Cookie"] = f"{cookie_name}={context.token}"
-        content = backend.download_binary(source_url, headers=cookie_headers)
-        return content, {
-            "download_strategy": requested_strategy,
-            "storage_auth_type": storage_auth_type,
-            "storage_cookie_prefix": storage_cookie_prefix,
-            "redirected": False,
-        }
-    content = backend.download_binary(source_url, headers=_record_detail_media_download_headers(context))
-    return content, {
-        "download_strategy": requested_strategy,
-        "storage_auth_type": storage_auth_type,
-        "storage_cookie_prefix": None,
-        "redirected": False,
-    }
+    return download_storage_content(
+        backend=backend, context=context, source_url=source_url, warnings=warnings,
+        environment_prefix_cache=environment_prefix_cache, requested_strategy=requested_strategy,
+    )
 
 
 def _record_detail_media_download_strategy(source_url: str) -> str:
@@ -17317,28 +17256,15 @@ def _record_detail_media_download_strategy(source_url: str) -> str:
 
 
 def _record_detail_should_use_storage_cookie(source_url: str, storage_auth_type: str | None) -> bool:
-    if not _record_detail_is_qingflow_storage_url(source_url):
-        return False
-    if not storage_auth_type:
-        return True
-    return storage_auth_type.upper() != "ANONYMOUS"
+    return requires_storage_cookie(source_url, storage_auth_type)
 
 
 def _record_detail_is_qingflow_storage_url(source_url: str) -> bool:
-    parsed = urlsplit(source_url)
-    path = parsed.path.lower()
-    if "/storage/file/" in path:
-        return True
-    query = parse_qs(parsed.query)
-    return any(key.lower() == "qingflow-auth_type" for key in query)
+    return is_storage_url(source_url)
 
 
 def _record_detail_storage_auth_type(source_url: str) -> str | None:
-    query = parse_qs(urlsplit(source_url).query)
-    for key, values in query.items():
-        if key.lower() == "qingflow-auth_type" and values:
-            return _normalize_optional_text(values[0])
-    return None
+    return storage_auth_type(source_url)
 
 
 def _record_detail_is_download_file_url(source_url: str) -> bool:
@@ -17388,28 +17314,9 @@ def _record_detail_environment_prefix(
     warnings: list[JSONObject],
     environment_prefix_cache: dict[str, str],
 ) -> str:
-    if "value" in environment_prefix_cache:
-        return environment_prefix_cache["value"]
-    try:
-        payload = backend.request("GET", context, "/environment/properties")
-        environment = payload.get("environmentProperty") if isinstance(payload, dict) else None
-        if not isinstance(environment, dict):
-            environment = payload.get("environment_property") if isinstance(payload, dict) else None
-        prefix = _normalize_optional_text(environment.get("environmentPrefix")) if isinstance(environment, dict) else None
-        if not prefix and isinstance(environment, dict):
-            prefix = _normalize_optional_text(environment.get("environment_prefix"))
-    except QingflowApiError as exc:
-        prefix = None
-        warnings.append(
-            {
-                "code": "MEDIA_ASSET_ENVIRONMENT_PREFIX_UNAVAILABLE",
-                "message": f"record_get could not read /environment/properties; falling back to qf_ token cookie prefix: {exc.message}",
-                "http_status": exc.http_status,
-            }
-        )
-    prefix = prefix if prefix is not None else "qf_"
-    environment_prefix_cache["value"] = prefix
-    return prefix
+    return environment_cookie_prefix(
+        backend, context, warnings=warnings, environment_prefix_cache=environment_prefix_cache,
+    )
 
 
 def _record_detail_context_origin(context: BackendRequestContext) -> str:

package/src/qingflow_mcp/tools/storage_download.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import parse_qs, urlsplit
+
+from ..backend_client import BackendRequestContext
+from ..config import DEFAULT_USER_AGENT
+from ..errors import QingflowApiError
+from ..json_types import JSONObject
+
+
+def storage_auth_type(source_url: str) -> str | None:
+    for key, values in parse_qs(urlsplit(source_url).query).items():
+        if key.lower() == "qingflow-auth_type" and values:
+            return values[0].strip() or None
+    return None
+
+
+def is_storage_url(source_url: str) -> bool:
+    parsed = urlsplit(source_url)
+    return "/storage/file/" in parsed.path.lower() or any(
+        key.lower() == "qingflow-auth_type" for key in parse_qs(parsed.query)
+    )
+
+
+def requires_storage_cookie(source_url: str, auth_type: str | None) -> bool:
+    return is_storage_url(source_url) and (not auth_type or auth_type.upper() != "ANONYMOUS")
+
+
+def environment_cookie_prefix(
+    backend: Any, context: BackendRequestContext, *, warnings: list[JSONObject],
+    environment_prefix_cache: dict[str, str], operation: str = "record_get",
+) -> str:
+    if "value" in environment_prefix_cache:
+        return environment_prefix_cache["value"]
+    try:
+        payload = backend.request("GET", context, "/environment/properties")
+        environment = payload.get("environmentProperty") if isinstance(payload, dict) else None
+        if not isinstance(environment, dict):
+            environment = payload.get("environment_property") if isinstance(payload, dict) else None
+        prefix = environment.get("environmentPrefix") if isinstance(environment, dict) else None
+        if not prefix and isinstance(environment, dict):
+            prefix = environment.get("environment_prefix")
+        if prefix is not None:
+            prefix = str(prefix).strip() or None
+    except QingflowApiError as exc:
+        prefix = None
+        warnings.append({
+            "code": "MEDIA_ASSET_ENVIRONMENT_PREFIX_UNAVAILABLE",
+            "message": f"{operation} could not read /environment/properties; falling back to qf_ token cookie prefix: {exc.message}",
+            "http_status": exc.http_status,
+        })
+    prefix = prefix if prefix is not None else "qf_"
+    environment_prefix_cache["value"] = prefix
+    return prefix
+
+
+def download_storage_content(
+    *, backend: Any, context: BackendRequestContext, source_url: str,
+    warnings: list[JSONObject], environment_prefix_cache: dict[str, str],
+    requested_strategy: str, operation: str = "record_get",
+    max_bytes: int | None = None,
+) -> tuple[bytes, JSONObject]:
+    parsed = urlsplit(getattr(context, "base_url", None) or "https://qingflow.com")
+    origin = f"{parsed.scheme}://{parsed.netloc}" if parsed.scheme and parsed.netloc else "https://qingflow.com"
+    headers = {"User-Agent": DEFAULT_USER_AGENT, "Referer": f"{origin}/", "Origin": origin}
+    auth_type = storage_auth_type(source_url)
+    prefix = None
+    redirected = False
+    limits = {"max_bytes": max_bytes} if max_bytes is not None else {}
+    if requires_storage_cookie(source_url, auth_type):
+        prefix = environment_cookie_prefix(
+            backend, context, warnings=warnings, environment_prefix_cache=environment_prefix_cache,
+            operation=operation,
+        )
+        cookie_name = f"{prefix}token"
+        if hasattr(backend, "download_binary_with_cookie"):
+            response = backend.download_binary_with_cookie(context, source_url, cookie_name=cookie_name, headers=headers, **limits)
+            content = response.content
+            redirected = bool(getattr(response, "redirected", False))
+        else:
+            headers["Cookie"] = f"{cookie_name}={context.token}"
+            content = backend.download_binary(source_url, headers=headers, **limits)
+    else:
+        content = backend.download_binary(source_url, headers=headers, **limits)
+    return content, {
+        "download_strategy": requested_strategy, "storage_auth_type": auth_type,
+        "storage_cookie_prefix": prefix, "redirected": redirected,
+    }