@qingflow-tech/qingflow-app-builder-mcp 1.0.10 → 1.0.12

package/src/qingflow_mcp/tools/export_tools.py

@@ -13,7 +13,7 @@ from mcp.server.fastmcp import FastMCP
 
 from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE, DEFAULT_RECORD_LIST_TYPE
-from ..errors import QingflowApiError
+from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, message_looks_like_invalid_token
 from ..export_store import ExportJobStore
 from ..json_types import JSONObject
 from .base import ToolBase, tool_cn_name
@@ -23,6 +23,8 @@ from .record_tools import (
     FormField,
     LAYOUT_ONLY_QUE_TYPES,
     RecordTools,
+    _build_top_level_field_index,
+    _normalize_data_list_base_info_schema,
     _normalize_public_column_selectors,
 )
 
@@ -59,7 +61,7 @@ class ExportTools(ToolBase):
         def record_export_start(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            view_id: str = "system:all",
+            view_id: str = "",
             columns: list[JSONObject | int] | None = None,
             where: list[JSONObject] | None = None,
             order_by: list[JSONObject] | None = None,
@@ -103,7 +105,7 @@ class ExportTools(ToolBase):
         def record_export_direct(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            view_id: str = "system:all",
+            view_id: str = "",
             columns: list[JSONObject | int] | None = None,
             where: list[JSONObject] | None = None,
             order_by: list[JSONObject] | None = None,
@@ -131,7 +133,7 @@ class ExportTools(ToolBase):
         *,
         profile: str = DEFAULT_PROFILE,
         app_key: str,
-        view_id: str = "system:all",
+        view_id: str = "",
         columns: list[JSONObject | int] | None = None,
         where: list[JSONObject] | None = None,
         order_by: list[JSONObject] | None = None,
@@ -139,7 +141,7 @@ class ExportTools(ToolBase):
         include_workflow_log: bool = False,
     ) -> dict[str, Any]:
         normalized_app_key = str(app_key or "").strip()
-        normalized_view_id = str(view_id or "").strip() or "system:all"
+        normalized_view_id = str(view_id or "").strip()
         normalized_columns = _normalize_export_columns(columns or [])
         normalized_where = self._record_tools._normalize_record_list_where(where or [])
         normalized_order_by = self._record_tools._normalize_record_list_order_by(order_by or [])
@@ -150,6 +152,12 @@ class ExportTools(ToolBase):
                 message="app_key is required",
                 extra={"view_id": normalized_view_id, "status": "failed"},
             )
+        if not normalized_view_id:
+            return self._failed_export_result(
+                error_code="EXPORT_VIEW_REQUIRED",
+                message="view_id is required; call app_get first and pass accessible_views[].view_id or use the view_id from the frontend URL",
+                extra={"app_key": normalized_app_key, "view_id": normalized_view_id, "status": "failed"},
+            )
 
         def runner(session_profile, context):
             resolved_view, compatibility_warnings = self._record_tools._resolve_accessible_view_route(
@@ -160,7 +168,7 @@ class ExportTools(ToolBase):
                 list_type=None,
                 view_key=None,
                 view_name=None,
-                allow_default=True,
+                allow_default=False,
             )
             export_config, export_config_warnings = self._build_export_config(
                 profile=profile,
@@ -238,6 +246,8 @@ class ExportTools(ToolBase):
             return {
                 "ok": True,
                 "status": "accepted",
+                "export_executed": True,
+                "safe_to_retry_export": False,
                 "app_key": normalized_app_key,
                 "view_id": resolved_view.view_id,
                 "export_handle": export_handle,
@@ -404,13 +414,17 @@ class ExportTools(ToolBase):
                         "verification": snapshot.get("verification") or {},
                     },
                 )
-            downloaded_files = self._download_export_files(
+            downloaded_files, download_warnings = self._download_export_files(
                 file_infos=file_infos,
                 download_to_path=download_to_path,
                 default_directory=None,
                 app_key=str(local_job.get("app_key") or ""),
                 view_id=str(local_job.get("view_id") or ""),
             )
+            warnings = [
+                *cast(list[JSONObject], snapshot.get("warnings") or []),
+                *download_warnings,
+            ]
             return {
                 "ok": True,
                 "status": "succeeded",
@@ -429,7 +443,7 @@ class ExportTools(ToolBase):
                 "file_urls": snapshot.get("file_urls") or [],
                 "file_names": snapshot.get("file_names") or [],
                 "downloaded_files": downloaded_files,
-                "warnings": snapshot.get("warnings") or [],
+                "warnings": warnings,
                 "verification": snapshot.get("verification") or {},
                 "request_route": self.backend.describe_route(lookup_context),
             }
@@ -449,7 +463,7 @@ class ExportTools(ToolBase):
         *,
         profile: str = DEFAULT_PROFILE,
         app_key: str,
-        view_id: str = "system:all",
+        view_id: str = "",
         columns: list[JSONObject | int] | None = None,
         where: list[JSONObject] | None = None,
         order_by: list[JSONObject] | None = None,
@@ -459,13 +473,19 @@ class ExportTools(ToolBase):
         wait_timeout_seconds: float | None = None,
     ) -> dict[str, Any]:
         normalized_app_key = str(app_key or "").strip()
-        normalized_view_id = str(view_id or "").strip() or "system:all"
+        normalized_view_id = str(view_id or "").strip()
         if not normalized_app_key:
             return self._failed_export_result(
                 error_code="EXPORT_START_FAILED",
                 message="app_key is required",
                 extra={"status": "failed", "view_id": normalized_view_id},
             )
+        if not normalized_view_id:
+            return self._failed_export_result(
+                error_code="EXPORT_VIEW_REQUIRED",
+                message="view_id is required; call app_get first and pass accessible_views[].view_id or use the view_id from the frontend URL",
+                extra={"status": "failed", "app_key": normalized_app_key, "view_id": normalized_view_id},
+            )
         timeout_seconds = self._normalize_timeout_seconds(wait_timeout_seconds)
 
         def runner(session_profile, context):
@@ -509,9 +529,15 @@ class ExportTools(ToolBase):
                         download_to_path=effective_download_path,
                     )
                     if bool(get_result.get("ok")):
+                        get_result = dict(get_result)
+                        get_result.setdefault("export_executed", True)
+                        get_result.setdefault("safe_to_retry_export", False)
+                        get_result.setdefault("export_handle", export_handle)
                         return get_result
                     return {
                         **get_result,
+                        "export_executed": True,
+                        "safe_to_retry_export": False,
                         "export_handle": export_handle,
                         "file_urls": snapshot.get("file_urls") or [],
                         "file_names": snapshot.get("file_names") or [],
@@ -547,8 +573,11 @@ class ExportTools(ToolBase):
                     }
                     if "EXPORT_HISTORY_AMBIGUOUS" in warning_codes:
                         return {
-                            "ok": True,
+                            "ok": False,
                             "status": "unknown",
+                            "error_code": "EXPORT_STATUS_UNKNOWN",
+                            "export_executed": True,
+                            "safe_to_retry_export": False,
                             "export_handle": export_handle,
                             "app_key": str(local_job.get("app_key") or ""),
                             "view_id": str(local_job.get("view_id") or ""),
@@ -579,8 +608,11 @@ class ExportTools(ToolBase):
                 }
             )
             return {
-                "ok": True,
+                "ok": False,
                 "status": timeout_status,
+                "error_code": "EXPORT_WAIT_TIMEOUT",
+                "export_executed": True,
+                "safe_to_retry_export": False,
                 "export_handle": str(start_result.get("export_handle") or ""),
                 "app_key": normalized_app_key,
                 "view_id": str(start_result.get("view_id") or normalized_view_id),
@@ -704,7 +736,7 @@ class ExportTools(ToolBase):
         order_by: list[JSONObject],
         select_columns: list[JSONObject],
     ) -> list[int]:
-        browse_scope = self._record_tools._build_browse_write_scope(
+        browse_scope = self._build_export_read_scope(
             profile,
             context,
             app_key,
@@ -841,7 +873,7 @@ class ExportTools(ToolBase):
         resolved_view: AccessibleViewRoute,
         column_selectors: list[int],
     ) -> tuple[JSONObject, list[JSONObject]]:  # type: ignore[no-untyped-def]
-        browse_scope = self._record_tools._build_browse_write_scope(
+        browse_scope = self._build_export_read_scope(
             profile,
             context,
             app_key,
@@ -912,6 +944,71 @@ class ExportTools(ToolBase):
             )
         return {"questionExportConfigList": question_export_config_list}, warnings
 
+    def _build_export_read_scope(
+        self,
+        profile: str,
+        context,
+        app_key: str,
+        resolved_view: AccessibleViewRoute,
+        *,
+        force_refresh: bool,
+    ) -> JSONObject:
+        try:
+            scope = self._record_tools._build_browse_read_scope(
+                profile,
+                context,
+                app_key,
+                resolved_view,
+                force_refresh=force_refresh,
+            )
+        except QingflowApiError as exc:
+            if not _is_optional_export_lookup_error(exc):
+                raise
+            scope = {}
+        index = scope.get("index") if isinstance(scope, dict) else None
+        if getattr(index, "by_id", None):
+            return scope
+        if resolved_view.kind == "system" and resolved_view.list_type is not None:
+            try:
+                list_base_scope = self._build_system_export_list_base_info_scope(context, app_key)
+            except QingflowApiError as exc:
+                if not _is_optional_export_lookup_error(exc):
+                    raise
+            else:
+                list_base_index = list_base_scope.get("index")
+                if getattr(list_base_index, "by_id", None):
+                    return list_base_scope
+        try:
+            applicant_index = self._record_tools._get_applicant_top_level_field_index(
+                profile,
+                context,
+                app_key,
+                force_refresh=force_refresh,
+            )
+        except QingflowApiError as exc:
+            if not _is_optional_export_lookup_error(exc):
+                raise
+            applicant_index = None
+        if applicant_index is not None and applicant_index.by_id:
+            visible_question_ids = {field.que_id for field in applicant_index.by_id.values()}
+            return {
+                "index": applicant_index,
+                "writable_field_ids": set(),
+                "visible_question_ids": visible_question_ids,
+            }
+        return scope or {"index": _build_top_level_field_index({}), "writable_field_ids": set(), "visible_question_ids": set()}
+
+    def _build_system_export_list_base_info_scope(self, context, app_key: str) -> JSONObject:
+        payload = self.backend.request("GET", context, f"/app/{app_key}/data/listBaseInfo")
+        schema = _normalize_data_list_base_info_schema(payload)
+        index = _build_top_level_field_index(schema)
+        visible_question_ids = {field.que_id for field in index.by_id.values()}
+        return {
+            "index": index,
+            "writable_field_ids": set(),
+            "visible_question_ids": visible_question_ids,
+        }
+
     def _resolve_exportable_fields(
         self,
         *,
@@ -1047,16 +1144,35 @@ class ExportTools(ToolBase):
     ) -> dict[str, Any]:  # type: ignore[no-untyped-def]
         app_key = str(local_job.get("app_key") or "").strip()
         process_payload = self._lookup_process_details(context, app_key=app_key)
-        history_page = self.backend.request(
-            "GET",
-            context,
-            "/app/apply/dataExport/record",
-            params={"appKey": app_key, "pageNum": 1, "pageSize": 100},
-        )
+        history_unavailable_warning: JSONObject | None = None
+        try:
+            history_page = self.backend.request(
+                "GET",
+                context,
+                "/app/apply/dataExport/record",
+                params={"appKey": app_key, "pageNum": 1, "pageSize": 100},
+            )
+        except QingflowApiError as exc:
+            if not _is_optional_export_lookup_error(exc):
+                raise
+            history_page = {"list": []}
+            history_unavailable_warning = {
+                "code": "EXPORT_HISTORY_UNAVAILABLE",
+                "message": "export history is not readable for the current user; using current process details when available.",
+            }
+            if exc.category:
+                history_unavailable_warning["category"] = exc.category
+            if exc.backend_code is not None:
+                history_unavailable_warning["backend_code"] = exc.backend_code
+            if exc.http_status is not None:
+                history_unavailable_warning["http_status"] = exc.http_status
+            if exc.request_id:
+                history_unavailable_warning["request_id"] = exc.request_id
         history_records = _extract_export_records(history_page)
         matched_record, matched_by = _match_export_history_record(history_records, local_job=local_job)
         if process_payload is not None:
             normalized_status = _normalize_export_status(process_payload.get("processStatus") or process_payload.get("status"))
+            process_file_infos = _normalize_export_file_infos(process_payload.get("fileUrls"))
             if normalized_status in {"queued", "running"}:
                 return {
                     "status": normalized_status,
@@ -1064,22 +1180,47 @@ class ExportTools(ToolBase):
                     "num": _coerce_int(process_payload.get("num")),
                     "error_code": process_payload.get("errorCode"),
                     "audit_record_status": process_payload.get("auditRecordStatus"),
-                    "file_infos": _normalize_export_file_infos(process_payload.get("fileUrls")),
-                    "file_urls": _extract_export_file_urls(process_payload.get("fileUrls")),
-                    "file_names": _extract_export_file_names(process_payload.get("fileUrls")),
-                    "warnings": [],
+                    "file_infos": process_file_infos,
+                    "file_urls": [item.get("url") for item in process_file_infos if isinstance(item.get("url"), str)],
+                    "file_names": [item.get("name") for item in process_file_infos if isinstance(item.get("name"), str)],
+                    "warnings": [history_unavailable_warning] if history_unavailable_warning is not None else [],
                     "verification": {
                         "current_process_visible": True,
                         "history_match_resolved": matched_record is not None,
+                        "history_readable": history_unavailable_warning is None,
                     },
                     "message": None,
                 }
+            if normalized_status in {"succeeded", "failed"} and (process_file_infos or normalized_status == "failed"):
+                message = "export failed" if normalized_status == "failed" else None
+                return {
+                    "status": normalized_status,
+                    "process_status": _coerce_int(process_payload.get("processStatus") or process_payload.get("status")),
+                    "num": _coerce_int(process_payload.get("num")),
+                    "error_code": process_payload.get("errorCode"),
+                    "audit_record_status": process_payload.get("auditRecordStatus"),
+                    "file_infos": process_file_infos,
+                    "file_urls": [item.get("url") for item in process_file_infos if isinstance(item.get("url"), str)],
+                    "file_names": [item.get("name") for item in process_file_infos if isinstance(item.get("name"), str)],
+                    "warnings": [history_unavailable_warning] if history_unavailable_warning is not None else [],
+                    "verification": {
+                        "current_process_visible": True,
+                        "history_match_resolved": matched_record is not None,
+                        "history_readable": history_unavailable_warning is None,
+                        "matched_by": "current_process",
+                    },
+                    "message": message,
+                }
         if matched_record is None:
             warning_code = "EXPORT_HISTORY_PENDING"
             warning_message = "export has not appeared in export history yet"
             if matched_by == "ambiguous":
                 warning_code = "EXPORT_HISTORY_AMBIGUOUS"
                 warning_message = "export result could not be matched uniquely in export history"
+            warnings = [{"code": warning_code, "message": warning_message}]
+            if history_unavailable_warning is not None:
+                warnings = [history_unavailable_warning]
+                warning_message = str(history_unavailable_warning["message"])
             return {
                 "status": "unknown",
                 "process_status": None,
@@ -1089,10 +1230,11 @@ class ExportTools(ToolBase):
                 "file_infos": [],
                 "file_urls": [],
                 "file_names": [],
-                "warnings": [{"code": warning_code, "message": warning_message}],
+                "warnings": warnings,
                 "verification": {
                     "current_process_visible": process_payload is not None,
                     "history_match_resolved": False,
+                    "history_readable": history_unavailable_warning is None,
                 },
                 "message": warning_message,
             }
@@ -1129,7 +1271,7 @@ class ExportTools(ToolBase):
                 params={"taskType": 2},
             )
         except QingflowApiError as exc:
-            if exc.backend_code in {40002, 40027}:
+            if _is_optional_export_lookup_error(exc):
                 return None
             raise
         if isinstance(payload, dict):
@@ -1183,9 +1325,9 @@ class ExportTools(ToolBase):
         default_directory: str | None,
         app_key: str,
         view_id: str,
-    ) -> list[JSONObject]:
+    ) -> tuple[list[JSONObject], list[JSONObject]]:
         if download_to_path is None and default_directory is None:
-            return []
+            return [], []
         effective_hint = download_to_path or default_directory
         assert effective_hint is not None
         targets = _resolve_download_targets(
@@ -1195,13 +1337,45 @@ class ExportTools(ToolBase):
             view_id=view_id,
         )
         downloaded_files: list[JSONObject] = []
+        warnings: list[JSONObject] = []
         for file_info, target in zip(file_infos, targets, strict=False):
             url = str(file_info.get("url") or "").strip()
             if not url:
                 continue
-            content = self.backend.download_binary(url)
-            target.parent.mkdir(parents=True, exist_ok=True)
-            target.write_bytes(content)
+            try:
+                content = self.backend.download_binary(url)
+                target.parent.mkdir(parents=True, exist_ok=True)
+                target.write_bytes(content)
+            except QingflowApiError as exc:
+                warning: JSONObject = {
+                    "code": "EXPORT_FILE_DOWNLOAD_UNAVAILABLE",
+                    "message": "export file link is available, but local download failed; use file_urls or retry download later.",
+                    "file_name": str(file_info.get("name") or target.name),
+                    "url": url,
+                    "category": exc.category,
+                    "backend_code": exc.backend_code,
+                    "request_id": exc.request_id,
+                    "http_status": exc.http_status,
+                }
+                if is_auth_like_error(exc):
+                    warning["auth_like"] = True
+                    warning["error_code"] = "AUTH_REQUIRED"
+                if exc.details:
+                    warning["details"] = exc.details
+                warnings.append(warning)
+                continue
+            except OSError as exc:
+                warnings.append(
+                    {
+                        "code": "EXPORT_FILE_WRITE_UNAVAILABLE",
+                        "message": "export file link is available, but writing the local file failed; use file_urls or retry with another download_to_path.",
+                        "file_name": str(file_info.get("name") or target.name),
+                        "url": url,
+                        "path": str(target),
+                        "error": str(exc),
+                    }
+                )
+                continue
             downloaded_files.append(
                 {
                     "file_name": str(file_info.get("name") or target.name),
@@ -1209,7 +1383,7 @@ class ExportTools(ToolBase):
                     "url": url,
                 }
             )
-        return downloaded_files
+        return downloaded_files, warnings
 
     def _normalize_timeout_seconds(self, wait_timeout_seconds: float | None) -> float:
         if wait_timeout_seconds is None:
@@ -1259,10 +1433,16 @@ class ExportTools(ToolBase):
             payload = json.loads(str(error))
         except json.JSONDecodeError:
             payload = {"message": str(error)}
+        details = payload.get("details") if isinstance(payload.get("details"), dict) else {}
         response = self._failed_export_result(
-            error_code=((payload.get("details") or {}) if isinstance(payload.get("details"), dict) else {}).get("error_code") or error_code,
+            error_code=details.get("error_code") or _runtime_error_code(payload, default=error_code),
             message=str(payload.get("message") or str(error)),
         )
+        for key in ("category", "backend_code", "request_id", "http_status"):
+            if key in payload:
+                response[key] = payload.get(key)
+        if details:
+            response["details"] = details
         if extra:
             response.update(extra)
         return response
@@ -1279,6 +1459,23 @@ def _extract_export_records(payload: Any) -> list[JSONObject]:
     return []
 
 
+def _is_optional_export_lookup_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404
+
+
+def _runtime_error_code(payload: JSONObject, *, default: str) -> str:
+    category = str(payload.get("category") or "").strip().lower()
+    http_status = _coerce_int(payload.get("http_status"))
+    if category == "auth" or http_status == 401 or message_looks_like_invalid_token(payload.get("message")):
+        return "AUTH_REQUIRED"
+    if category == "workspace":
+        return "WORKSPACE_NOT_SELECTED"
+    return default
+
+
 def _match_export_history_record(
     records: list[JSONObject],
     *,

package/src/qingflow_mcp/tools/file_tools.py

@@ -12,12 +12,12 @@ from urllib.parse import quote
 from mcp.server.fastmcp import FastMCP
 
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError, raise_tool_error
+from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
 from ..json_types import JSONObject
 from .base import ToolBase, tool_cn_name
 
 
-ATTACHMENT_UPLOAD_INFO_FALLBACK_CODES = {"40118", 40118}
+ATTACHMENT_UPLOAD_INFO_FALLBACK_CODES = {40118}
 LEGACY_OSS_FORM_REQUIRED_KEYS = ("key", "policy", "signature", "ossAccessKeyId")
 
 
@@ -190,6 +190,8 @@ class FileTools(ToolBase):
                 "result": result,
                 "upload_result": upload_result,
                 "download_url": download_url,
+                "write_executed": True,
+                "safe_to_retry": False,
                 "attachment_value": {
                     "value": download_url,
                     "otherInfo": file_name,
@@ -357,10 +359,12 @@ class FileTools(ToolBase):
         error: QingflowApiError,
     ) -> bool:
         """执行内部辅助逻辑。"""
+        if is_auth_like_error(error):
+            return False
         return (
             requested_kind == "attachment"
             and attempted_kind == "attachment"
-            and error.backend_code in ATTACHMENT_UPLOAD_INFO_FALLBACK_CODES
+            and backend_code_int(error) in ATTACHMENT_UPLOAD_INFO_FALLBACK_CODES
         )
 
     def _is_legacy_oss_form_upload(self, payload: JSONObject) -> bool: