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

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,99 @@ 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 '-'}")
+    file_assets = result.get("file_assets")
+    if isinstance(file_assets, dict):
+        lines.append(f"Attachments: {file_assets.get('status') or '-'}")
+        for asset in file_assets.get("items", []):
+            if isinstance(asset, dict):
+                lines.append(f"- {asset.get('file_name')}: {asset.get('access_status')} / {asset.get('local_path') or '-'}")
+        _append_warnings(lines, file_assets.get("warnings"))
+    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 +1765,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/response_trim.py

@@ -51,8 +51,9 @@ COMMON_ERROR_DROP_TOP = {
 
 SUCCESS_POLICY_BY_TOOL: dict[str, TransformFn] = {}
 
-#: 这两个校验命令的产出契约明确包含 ok 字段（供阶段 2 SKILL.md 引用），
+#: 这些校验命令的产出契约明确包含 ok 字段（供阶段 2 SKILL.md 引用），
 #: 需在 success 裁剪时保留 ok（默认 COMMON_SUCCESS_DROP_TOP 会丢弃 ok）。
+#: `builder:app_views_validate`（views 声明式校验）同属校验类工具，ok 同样进产出契约。
 _KEEP_OK_TOOLS = {
     "builder:app_form_validate_formula",
     "builder:app_form_validate_code_block",

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
@@ -148,7 +149,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - `record_delete` deletes by `record_id` or `record_ids`, and requires an accessible system `view_id`; use custom views only to locate records, not as the delete route.
 - `record_get` is the single-record frontend detail context tool. It returns detail-page visible fields, one-level relation targets, first-page data/workflow logs, associated views/reports, local readable image assets, local downloadable file assets, unavailable context, and `semantic_context`.
 - Use `record_logs_get` only when the user needs the full visible data/workflow log history for a specific record. It writes JSONL files locally and returns file paths plus completeness metadata; do not expect full log arrays in the response.
-- Read record images from `record_get.media_assets.items[].local_path` when `readable_by_agent=true`; read attachments/documents/tables from `record_get.file_assets.items[].local_path` and `extraction.text_path` when present. `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, and remote file URLs should not be treated as directly readable.
+- Download record attachments with `data_get(download_attachments=true, include_schema=true)` for the same app and record; use `file_assets.items[].local_path` only when `access_status=downloaded`. This includes original images and videos. Inspect `file_assets.warnings` for partial failures; do not request remote private URLs or fall back to record/detail tools after a data-plane denial. For specialized detail-page context, read `record_get` rich-text images from `media_assets` and its files from `file_assets` local paths or `extraction.text_path` when present.
 - `record_get.columns` are focus hints only; they do not project the detail fields. Read facts from top-level `fields[]`.
 - When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
 
@@ -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
@@ -143,7 +144,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - `record_delete` deletes by `record_id` or `record_ids`, and requires an accessible system `view_id`; use custom views only to locate records, not as the delete route.
 - `record_get` is the single-record frontend detail context tool. It returns detail-page visible fields, one-level relation targets, first-page data/workflow logs, associated views/reports, local readable image assets, local downloadable file assets, unavailable context, and `semantic_context`.
 - Use `record_logs_get` only when the user needs the full visible data/workflow log history for a specific record. It writes JSONL files locally and returns file paths plus completeness metadata; do not expect full log arrays in the response.
-- Read record images from `record_get.media_assets.items[].local_path` when `readable_by_agent=true`; read attachments/documents/tables from `record_get.file_assets.items[].local_path` and `extraction.text_path` when present. `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, and remote file URLs should not be treated as directly readable.
+- Download record attachments with `data_get(download_attachments=true, include_schema=true)` for the same app and record; use `file_assets.items[].local_path` only when `access_status=downloaded`. This includes original images and videos. Inspect `file_assets.warnings` for partial failures; do not request remote private URLs or fall back to record/detail tools after a data-plane denial. For specialized detail-page context, read `record_get` rich-text images from `media_assets` and its files from `file_assets` local paths or `extraction.text_path` when present.
 - `record_get.columns` are focus hints only; they do not project the detail fields. Read facts from top-level `fields[]`.
 - When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
 
@@ -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_files.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import mimetypes
+import os
+import re
+import time
+from pathlib import Path
+from typing import Any, Callable
+from urllib.parse import unquote, urlsplit
+from uuid import uuid4
+
+from ..backend_client import BackendRequestContext
+from ..config import get_mcp_home
+from ..errors import QingflowApiError
+from ..json_types import JSONObject
+from .storage_download import download_storage_content, requires_storage_cookie, storage_auth_type
+
+
+DATA_FILE_MAX_FILES = 50
+DATA_FILE_MAX_BYTES = 50 * 1024 * 1024
+DATA_FILE_MAX_TOTAL_BYTES = 200 * 1024 * 1024
+DATA_FILE_TIME_BUDGET_SECONDS = 55.0
+
+
+def attachment_candidates(record: JSONObject, schema: JSONObject) -> list[JSONObject]:
+    candidates: list[JSONObject] = []
+
+    def walk(values: Any, fields: Any, prefix: str) -> None:
+        if not isinstance(values, dict) or not isinstance(fields, list):
+            return
+        for field in fields:
+            if not isinstance(field, dict) or field.get("field_id") is None:
+                continue
+            key = str(field["field_id"])
+            value = values.get(key)
+            path = f"{prefix}.{key}"
+            if field.get("data_type") == "table" and isinstance(value, list):
+                for index, row in enumerate(value):
+                    walk(row, field.get("children"), f"{path}[{index}]")
+            elif field.get("data_type") == "attachment":
+                for index, item in enumerate(value if isinstance(value, list) else [value]):
+                    url = item.get("value") or item.get("url") if isinstance(item, dict) else item
+                    if not isinstance(url, str) or not url.strip():
+                        continue
+                    name = (item.get("other_info") or item.get("otherInfo") or item.get("name")) if isinstance(item, dict) else None
+                    if not isinstance(name, str) or not name.strip():
+                        try:
+                            name = Path(unquote(urlsplit(url).path)).name
+                        except ValueError:
+                            name = None
+                        name = name or f"attachment_{len(candidates) + 1}"
+                    candidates.append({
+                        "field_id": field["field_id"], "file_name": name,
+                        "source_path": f"{path}[{index}]", "source_url": url.strip(),
+                    })
+
+    walk(record.get("fields"), schema.get("fields"), "fields")
+    return candidates
+
+
+def _download_url(candidate: JSONObject) -> str:
+    url = str(candidate["source_url"])
+    parsed = urlsplit(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.netloc or parsed.username or parsed.password:
+        raise QingflowApiError.config_error("附件没有可直接下载的 HTTP 地址")
+    return url
+
+
+def _matching_attachment(
+    candidate: JSONObject, refreshed: list[JSONObject],
+) -> JSONObject | None:
+    # shortcut: 沿用旧链路，同一字段内同名附件取首个；需要区分时再引入稳定文件 ID。
+    return next((item for item in refreshed if (
+        str(item["field_id"]) == str(candidate["field_id"])
+        and str(item["file_name"]).strip() == str(candidate["file_name"]).strip()
+    )), None)
+
+
+def download_data_attachments(
+    *, backend: Any, context: BackendRequestContext, record: JSONObject, schema: JSONObject,
+    refresh_record: Callable[[], JSONObject],
+) -> JSONObject:
+    candidates = attachment_candidates(record, schema)
+    if not candidates:
+        return {"status": "none", "local_dir": None, "items": [], "warnings": []}
+    custom_home = os.environ.get("QINGFLOW_MCP_DATA_FILES_HOME")
+    local_dir = (Path(custom_home).expanduser() if custom_home else get_mcp_home() / "data-files") / uuid4().hex
+    items: list[JSONObject] = []
+    warnings: list[JSONObject] = []
+    prefix_cache: dict[str, str] = {}
+    fresh_candidates: list[JSONObject] | None = None
+    deadline = time.monotonic() + DATA_FILE_TIME_BUDGET_SECONDS
+    total_bytes = 0
+
+    for index, original in enumerate(candidates):
+        item: JSONObject = {**original, "local_path": None}
+        items.append(item)
+        if index >= DATA_FILE_MAX_FILES or time.monotonic() >= deadline:
+            item["access_status"] = "skipped_limit"
+            warnings.append({"code": "FILE_ASSET_LIMIT_EXCEEDED", "message": "附件数量或下载时间超过本次预算"})
+            continue
+        try:
+            if fresh_candidates is not None:
+                replacement = _matching_attachment(item, fresh_candidates)
+                if replacement is None:
+                    raise QingflowApiError(category="http", message="刷新后附件不在当前可见范围内", http_status=403)
+                item["source_url"] = replacement["source_url"]
+            url = _download_url(item)
+
+            def download(source_url: str) -> tuple[bytes, JSONObject]:
+                return download_storage_content(
+                    backend=backend, context=context, source_url=source_url, warnings=warnings,
+                    environment_prefix_cache=prefix_cache, operation="data_get",
+                    max_bytes=min(DATA_FILE_MAX_BYTES, DATA_FILE_MAX_TOTAL_BYTES - total_bytes),
+                    requested_strategy="qingflow_storage_cookie_redirect" if requires_storage_cookie(
+                        source_url, storage_auth_type(source_url)
+                    ) else "referer_acl",
+                )
+
+            try:
+                content, metadata = download(url)
+            except QingflowApiError as exc:
+                if exc.http_status not in {401, 403}:
+                    raise
+                if fresh_candidates is None:
+                    fresh_candidates = []
+                    fresh = refresh_record()
+                    if fresh.get("ok") is False:
+                        raise QingflowApiError(
+                            category="backend", message=str(fresh.get("message") or "刷新附件访问范围失败"),
+                            backend_code=fresh.get("backend_code"),
+                        ) from exc
+                    if not isinstance(fresh.get("record"), dict) or not isinstance(fresh.get("schema"), dict):
+                        raise QingflowApiError(category="backend", message="刷新附件需要数据面返回 record 和 schema") from exc
+                    fresh_candidates = attachment_candidates(fresh["record"], fresh["schema"])
+                replacement = _matching_attachment(item, fresh_candidates)
+                if replacement is None or replacement["source_url"] == url:
+                    raise
+                url = _download_url(replacement)
+                content, metadata = download(url)
+                item["source_url"] = url
+                warnings.append({
+                    "code": "FILE_ASSET_STORAGE_URL_REFRESHED", "source_path": item["source_path"],
+                    "message": "已通过数据面重新读取同一记录并刷新附件链接",
+                })
+            item.update(metadata)
+            item["size_bytes"] = len(content)
+            if len(content) > DATA_FILE_MAX_BYTES or total_bytes + len(content) > DATA_FILE_MAX_TOTAL_BYTES:
+                item["access_status"] = "too_large"
+                warnings.append({"code": "FILE_ASSET_SIZE_LIMIT_EXCEEDED", "message": "附件超过单文件或总大小预算"})
+                continue
+            suffix = Path(str(item["file_name"])).suffix
+            suffix = suffix if re.fullmatch(r"\.[A-Za-z0-9]{1,10}", suffix) else ""
+            local_dir.mkdir(parents=True, exist_ok=True)
+            local_path = local_dir / f"file_{index + 1:04d}{suffix}"
+            local_path.write_bytes(content)
+            total_bytes += len(content)
+            item.update({
+                "local_path": str(local_path), "access_status": "downloaded",
+                "mime_type": mimetypes.guess_type(str(item["file_name"]))[0],
+            })
+        except (QingflowApiError, OSError, ValueError) as exc:
+            blocked = isinstance(exc, QingflowApiError) and exc.http_status in {401, 403}
+            too_large = isinstance(exc, QingflowApiError) and exc.category == "file_size_limit"
+            item["access_status"] = "too_large" if too_large else "blocked_private_url" if blocked else "download_failed"
+            warnings.append({
+                "code": "FILE_ASSET_SIZE_LIMIT_EXCEEDED" if too_large else "FILE_ASSET_DOWNLOAD_FAILED", "source_path": item["source_path"],
+                "message": exc.message if isinstance(exc, QingflowApiError) else str(exc),
+                "http_status": exc.http_status if isinstance(exc, QingflowApiError) else None,
+            })
+    return {
+        "status": "ok" if all(item["access_status"] == "downloaded" for item in items) else "partial",
+        "local_dir": str(local_dir) if local_dir.exists() else None, "items": items, "warnings": warnings,
+    }