@josephyan/qingflow-cli 0.2.0-beta.999 → 1.0.6

package/src/qingflow_mcp/tools/record_tools.py

@@ -1,17 +1,21 @@
 from __future__ import annotations
 
+import csv
 import json
+import os
 import re
 import time
 from copy import deepcopy
 from dataclasses import dataclass
 from datetime import UTC, datetime
 from decimal import Decimal, InvalidOperation
+from pathlib import Path
 from typing import Any, cast
+from uuid import uuid4
 
 from mcp.server.fastmcp import FastMCP
 
-from ..config import DEFAULT_PROFILE, DEFAULT_RECORD_LIST_TYPE
+from ..config import DEFAULT_PROFILE, DEFAULT_RECORD_LIST_TYPE, get_mcp_home
 from ..errors import QingflowApiError, raise_tool_error
 from ..id_utils import normalize_positive_id_int, stringify_backend_id
 from ..json_types import JSONObject, JSONScalar, JSONValue
@@ -28,6 +32,8 @@ from .directory_tools import _directory_has_more, _directory_items
 
 DEFAULT_QUERY_PAGE_SIZE = 50
 DEFAULT_LIST_PAGE_SIZE = 200
+BACKEND_RECORD_ACCESS_PAGE_SIZE = 1000
+DEFAULT_RECORD_ACCESS_SHARD_ROWS = 5000
 DEFAULT_ANALYSIS_PAGE_SIZE = 1000
 DEFAULT_SCAN_MAX_PAGES = 10
 DEFAULT_ANALYSIS_SCAN_MAX_PAGES = 100
@@ -49,6 +55,7 @@ LOOKUP_RELATION_FILTER_PAGE_SIZE = 20
 MEMBER_QUE_TYPES = {5}
 DEPARTMENT_QUE_TYPES = {22}
 DATE_QUE_TYPES = {4}
+NUMBER_QUE_TYPES = {8}
 ADDRESS_QUE_TYPES = {21}
 SINGLE_SELECT_QUE_TYPES = {10, 11}
 MULTI_SELECT_QUE_TYPES = {12, 15}
@@ -337,7 +344,8 @@ class RecordTools(ToolBase):
 
         @mcp.tool(
             description=(
-                "Run schema-first analytics on a Qingflow app using a restricted DSL. "
+                "Run lightweight schema-first analytics on a Qingflow app using a restricted DSL. "
+                "This is not the default analysis path; prefer record_access plus Python for final conclusions. "
                 "Use record_browse_schema_get first, then let the model build a DSL with field_id references only. "
                 "dimensions=[] means whole-table summary; dimensions!=[] means grouped analysis. "
                 "This route hides paging and scan-budget controls from callers."
@@ -404,6 +412,29 @@ class RecordTools(ToolBase):
                 output_profile=output_profile,
             )
 
+        @mcp.tool(
+            description=(
+                "Access Qingflow records for analysis by writing local CSV shard files. "
+                "Use app_get -> record_browse_schema_get first, then pass field_id-only columns, where, and order_by. "
+                "This tool hides pagination and row limits from the caller and returns file metadata instead of record items."
+            )
+        )
+        def record_access(
+            app_key: str = "",
+            view_id: str = "",
+            columns: list[JSONObject | int] | None = None,
+            where: list[JSONObject] | None = None,
+            order_by: list[JSONObject] | None = None,
+        ) -> JSONObject:
+            return self.record_access(
+                profile=DEFAULT_PROFILE,
+                app_key=app_key,
+                view_id=view_id,
+                columns=columns or [],
+                where=where or [],
+                order_by=order_by or [],
+            )
+
         @mcp.tool(description="Read one Qingflow record by record_id. Use record_browse_schema_get first if columns are ambiguous.")
         def record_get(
             profile: str = DEFAULT_PROFILE,
@@ -1759,6 +1790,290 @@ class RecordTools(ToolBase):
             }
         return response
 
+    @tool_cn_name("记录访问")
+    def record_access(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        view_id: str,
+        columns: list[JSONObject | int],
+        where: list[JSONObject],
+        order_by: list[JSONObject],
+    ) -> JSONObject:
+        """Fetch records across pages and write stable CSV shards for local analysis."""
+        if not app_key:
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+        if not (view_id or "").strip():
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "record_access requires view_id. Call app_get first and pass accessible_views[].view_id."
+                )
+            )
+        legacy_warnings = _detect_record_list_legacy_warnings(columns=columns, where=where, order_by=order_by)
+        normalized_columns = _normalize_public_column_selectors(columns)
+        if not normalized_columns:
+            raise_tool_error(
+                QingflowApiError.config_error(
+                    "columns is required. Call record_browse_schema_get first and pass field_id-only columns."
+                )
+            )
+        view_route, compatibility_warnings = self._resolve_accessible_view_route_for_public(
+            profile=profile,
+            app_key=app_key,
+            view_id=view_id,
+            list_type=None,
+            view_key=None,
+            view_name=None,
+            allow_default=False,
+        )
+        if not _view_type_supports_analysis(view_route.view_type):
+            raise_tool_error(
+                QingflowApiError(
+                    category="not_supported",
+                    message=(
+                        f"record_access does not support view '{view_route.name}' "
+                        f"because its type is {view_route.view_type}."
+                    ),
+                    details={
+                        "error_code": "VIEW_ACCESS_UNSUPPORTED",
+                        "view_id": view_route.view_id,
+                        "view_name": view_route.name,
+                        "view_type": view_route.view_type,
+                        "fix_hint": "Choose a system view or a custom table-style view from app_get.accessible_views.",
+                    },
+                )
+            )
+        filters = self._normalize_record_list_where(where)
+        sorts = self._normalize_record_list_order_by(order_by)
+
+        def runner(session_profile, context):
+            index = self._get_field_index(profile, context, app_key, force_refresh=False)
+            selected_fields = self._resolve_select_columns(
+                normalized_columns,
+                index,
+                max_columns=len(normalized_columns),
+                default_limit=MAX_LIST_COLUMN_LIMIT,
+            )
+            selected_field_batches = _chunk_fields(selected_fields, BACKEND_LIST_SEARCH_FIELD_LIMIT)
+            primary_search_que_ids: list[int] | None = [field.que_id for field in selected_field_batches[0]]
+            view_selection = view_route.view_selection
+            if view_selection is not None and not _view_selection_supported_by_search_ids(
+                view_selection,
+                primary_search_que_ids,
+            ):
+                primary_search_que_ids = None
+                remaining_field_batches: list[list[FormField]] = []
+            else:
+                remaining_field_batches = selected_field_batches[1:]
+                primary_search_que_ids = primary_search_que_ids or None
+            match_rules = self._resolve_match_rules(context, filters, index)
+            sort_rules = self._resolve_sorts(sorts, index)
+            used_list_type: int | None = None
+            fallback_list_types = (
+                [view_route.list_type if view_route.list_type is not None else DEFAULT_RECORD_LIST_TYPE]
+                if view_selection is not None or view_route.list_type is not None
+                else [DEFAULT_RECORD_LIST_TYPE, 14, 1, 2, 12]
+            )
+
+            run_dir = _record_access_run_dir()
+            run_dir.mkdir(parents=True, exist_ok=True)
+            header = ["record_id"] + [f"field_{field.que_id}" for field in selected_fields]
+            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
+
+            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
+
+            current_page = 1
+            has_more = False
+            reported_total: int | None = None
+            try:
+                while True:
+                    if used_list_type is None:
+                        last_error: QingflowApiError | None = None
+                        page: JSONObject | None = None
+                        for candidate_list_type in fallback_list_types:
+                            try:
+                                page = self._search_page(
+                                    context,
+                                    app_key=app_key,
+                                    view_selection=view_selection,
+                                    page_num=current_page,
+                                    page_size=BACKEND_RECORD_ACCESS_PAGE_SIZE,
+                                    query_key=None,
+                                    match_rules=match_rules,
+                                    sorts=sort_rules,
+                                    search_que_ids=primary_search_que_ids,
+                                    list_type=candidate_list_type,
+                                )
+                                used_list_type = None if view_selection is not None else candidate_list_type
+                                break
+                            except QingflowApiError as exc:
+                                last_error = exc
+                                if (
+                                    self._should_retry_list_type_fallback(exc)
+                                    and candidate_list_type != fallback_list_types[-1]
+                                ):
+                                    continue
+                                raise
+                        if page is None:
+                            if last_error is not None:
+                                raise last_error
+                            raise_tool_error(QingflowApiError.config_error("record_access failed: no accessible listType"))
+                    else:
+                        page = self._search_page(
+                            context,
+                            app_key=app_key,
+                            view_selection=view_selection,
+                            page_num=current_page,
+                            page_size=BACKEND_RECORD_ACCESS_PAGE_SIZE,
+                            query_key=None,
+                            match_rules=match_rules,
+                            sorts=sort_rules,
+                            search_que_ids=primary_search_que_ids,
+                            list_type=used_list_type,
+                        )
+                    page_rows = page.get("list")
+                    items = page_rows if isinstance(page_rows, list) else []
+                    if reported_total is None:
+                        reported_total = _effective_total(page, BACKEND_RECORD_ACCESS_PAGE_SIZE)
+                    has_more = _page_has_more(page, current_page, BACKEND_RECORD_ACCESS_PAGE_SIZE, len(items))
+                    page_apply_order: list[int] = []
+                    page_answer_map: dict[int, list[JSONValue]] = {}
+                    for item in items:
+                        if not isinstance(item, dict):
+                            continue
+                        answers = item.get("answers")
+                        answer_list = answers if isinstance(answers, list) else []
+                        apply_id = _coerce_count(item.get("applyId")) or _coerce_count(item.get("id"))
+                        if apply_id is None:
+                            continue
+                        page_apply_order.append(apply_id)
+                        page_answer_map[apply_id] = cast(list[JSONValue], answer_list)
+                    if page_apply_order and remaining_field_batches:
+                        for batch in remaining_field_batches:
+                            extra_page = self._search_page(
+                                context,
+                                app_key=app_key,
+                                view_selection=view_selection,
+                                page_num=current_page,
+                                page_size=BACKEND_RECORD_ACCESS_PAGE_SIZE,
+                                query_key=None,
+                                match_rules=match_rules,
+                                sorts=sort_rules,
+                                search_que_ids=[field.que_id for field in batch],
+                                list_type=used_list_type or DEFAULT_RECORD_LIST_TYPE,
+                            )
+                            extra_rows = extra_page.get("list")
+                            extra_items = extra_rows if isinstance(extra_rows, list) else []
+                            for extra_item in extra_items:
+                                if not isinstance(extra_item, dict):
+                                    continue
+                                apply_id = _coerce_count(extra_item.get("applyId")) or _coerce_count(extra_item.get("id"))
+                                if apply_id is None or apply_id not in page_answer_map:
+                                    continue
+                                extra_answers = extra_item.get("answers")
+                                extra_answer_list = extra_answers if isinstance(extra_answers, list) else []
+                                page_answer_map[apply_id] = _merge_answer_lists_by_field_id(
+                                    page_answer_map.get(apply_id, []),
+                                    cast(list[JSONValue], extra_answer_list),
+                                )
+                    for apply_id in page_apply_order:
+                        write_record(apply_id, page_answer_map.get(apply_id, []))
+                    if not has_more:
+                        break
+                    current_page += 1
+            finally:
+                close_shard()
+
+            warnings: list[JSONObject] = []
+            warnings.extend(legacy_warnings)
+            warnings.extend(compatibility_warnings)
+            warnings.extend(_view_filter_trust_warnings(view_route))
+            if used_list_type is not None and used_list_type != DEFAULT_RECORD_LIST_TYPE:
+                warnings.append(
+                    {
+                        "code": "LIST_TYPE_FALLBACK",
+                        "message": (
+                            f"record_access not accessible via listType={DEFAULT_RECORD_LIST_TYPE}; "
+                            f"fell back to listType={used_list_type} ({get_record_list_type_label(used_list_type)})."
+                        ),
+                    }
+                )
+            complete = not has_more
+            safe_for_final_conclusion = complete and not any(
+                warning.get("code") == "CUSTOM_VIEW_FILTER_UNVERIFIED" for warning in warnings
+            )
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "ok": True,
+                "status": "success" if complete else "partial",
+                "app_key": app_key,
+                "view_id": view_route.view_id,
+                "format": "csv",
+                "row_count": row_count,
+                "complete": complete,
+                "truncated": not complete,
+                "safe_for_final_conclusion": safe_for_final_conclusion,
+                "files": files,
+                "fields": [_record_access_field_payload(field) for field in selected_fields],
+                "warnings": warnings,
+                "verification": {
+                    **_view_filter_verification_payload(view_route),
+                    "reported_total": reported_total,
+                    "list_type_used": used_list_type,
+                },
+                "request_route": self._request_route_payload(context),
+            }
+
+        return self._run_record_tool(profile, runner)
+
     @tool_cn_name("记录详情")
     def record_get_public(
         self,
@@ -2920,12 +3235,14 @@ class RecordTools(ToolBase):
             payload["category"] = error.category
         if error.backend_code is not None:
             payload["backend_code"] = error.backend_code
+        if error.request_id is not None:
+            payload["request_id"] = error.request_id
         if error.http_status is not None:
             payload["http_status"] = error.http_status
         return payload
 
     def _is_record_context_route_miss(self, error: QingflowApiError) -> bool:
-        if error.backend_code in {40002, 40027, 40038, 404}:
+        if error.backend_code in {40002, 40023, 40027, 40038, 404}:
             return True
         if error.http_status == 404:
             return True
@@ -3059,6 +3376,107 @@ class RecordTools(ToolBase):
             f"({get_record_list_type_label(used_list_type)})."
         ]
 
+    def _looks_like_generic_record_update_backend_failure(self, exc: QingflowApiError) -> bool:
+        if exc.backend_code == 500:
+            return True
+        if exc.http_status is not None and exc.http_status >= 500:
+            return True
+        normalized_message = exc.message.strip().lower()
+        return normalized_message in {"unknown error", "internal server error"}
+
+    def _remap_record_update_target_context_error(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+        exc: QingflowApiError,
+    ) -> None:
+        if not self._looks_like_generic_record_update_backend_failure(exc):
+            return
+        try:
+            candidate_routes = self._candidate_update_views(profile, context, app_key)
+            probes = self._probe_candidate_record_contexts(
+                context,
+                app_key=app_key,
+                apply_id=apply_id,
+                candidate_routes=candidate_routes,
+            )
+        except (QingflowApiError, RuntimeError):
+            return
+        if not probes or any(probe.readable for probe in probes):
+            return
+
+        blocker = (
+            "CURRENT_RECORD_CONTEXT_UNAVAILABLE"
+            if all(probe.transport_error for probe in probes)
+            else "NO_MATCHING_ACCESSIBLE_VIEW_FOR_RECORD"
+        )
+        recommended_next_actions = (
+            [
+                "Retry after the record becomes readable in the current workspace/profile context.",
+                "If the issue persists, verify that the current profile still has read access to this record.",
+            ]
+            if blocker == "CURRENT_RECORD_CONTEXT_UNAVAILABLE"
+            else [
+                "Use record_get or record_list to confirm the record still exists in the current workspace.",
+                "Call record_update_schema_get to inspect whether any accessible view still matches this record.",
+            ]
+        )
+        first_error_payload = next(
+            (
+                cast(JSONObject, probe.error_payload)
+                for probe in probes
+                if isinstance(probe.error_payload, dict)
+            ),
+            None,
+        )
+        backend_code = (
+            cast(int, first_error_payload.get("backend_code"))
+            if isinstance(first_error_payload, dict) and isinstance(first_error_payload.get("backend_code"), int)
+            else exc.backend_code
+        )
+        request_id = (
+            _normalize_optional_text(first_error_payload.get("request_id"))
+            if isinstance(first_error_payload, dict)
+            else None
+        ) or exc.request_id
+        http_status = (
+            cast(int, first_error_payload.get("http_status"))
+            if isinstance(first_error_payload, dict) and isinstance(first_error_payload.get("http_status"), int)
+            else exc.http_status
+        )
+        raise_tool_error(
+            QingflowApiError(
+                category="backend",
+                message=(
+                    "Direct record edit was blocked because the current record context could not be loaded from any candidate route."
+                    if blocker == "CURRENT_RECORD_CONTEXT_UNAVAILABLE"
+                    else "Direct record edit was blocked because the target record is no longer accessible in any readable view for the current profile."
+                ),
+                backend_code=backend_code,
+                request_id=request_id,
+                http_status=http_status,
+                details={
+                    "error_code": blocker,
+                    "operation": "update",
+                    "app_key": app_key,
+                    "record_id": apply_id,
+                    "blockers": [blocker],
+                    "request_route": self._request_route_payload(context),
+                    "view_probe_summary": [
+                        self._record_context_probe_summary_payload(probe)
+                        for probe in probes
+                    ],
+                    "recommended_next_actions": recommended_next_actions,
+                    "fix_hint": (
+                        "Confirm the target record still exists and remains visible in at least one accessible view before retrying the update."
+                    ),
+                },
+            )
+        )
+
     def _record_matches_accessible_view(
         self,
         context,  # type: ignore[no-untyped-def]
@@ -5138,9 +5556,8 @@ class RecordTools(ToolBase):
         source_pages: list[int] = []
         result_amount: int | None = None
         has_more = False
-        dept_member_cache: dict[int, set[int]] = {}
         view_selection = resolved_view.view_selection
-        local_filtering = bool(filters) or bool(view_selection is not None and view_selection.conditions)
+        local_filtering = bool(filters)
         group_stats: dict[tuple[tuple[str, object], ...], JSONObject] = {}
         overall_metrics = self._initialize_metric_states(metrics)
         matched_rows = 0
@@ -5184,13 +5601,6 @@ class RecordTools(ToolBase):
                     continue
                 answers = item.get("answers")
                 answer_list = answers if isinstance(answers, list) else []
-                if not self._matches_view_selection(
-                    context,
-                    answer_list,
-                    view_selection=view_selection,
-                    dept_member_cache=dept_member_cache,
-                ):
-                    continue
                 if not self._matches_analyze_filters(answer_list, filters):
                     continue
                 matched_rows += 1
@@ -6276,7 +6686,6 @@ class RecordTools(ToolBase):
                 if view_selection is not None
                 else self._get_field_index(profile, context, app_key, force_refresh=False)
             )
-            dept_member_cache: dict[int, set[int]] = {}
             result = self._search_page(
                 context,
                 app_key=app_key,
@@ -6291,17 +6700,7 @@ class RecordTools(ToolBase):
             )
             rows = result.get("list")
             raw_rows = rows if isinstance(rows, list) else []
-            filtered_rows = [
-                item
-                for item in raw_rows
-                if isinstance(item, dict)
-                and self._matches_view_selection(
-                    context,
-                    item.get("answers") if isinstance(item.get("answers"), list) else [],
-                    view_selection=view_selection,
-                    dept_member_cache=dept_member_cache,
-                )
-            ]
+            filtered_rows = [item for item in raw_rows if isinstance(item, dict)]
             if isinstance(rows, list):
                 result = dict(result)
                 result["list"] = filtered_rows
@@ -6355,12 +6754,22 @@ class RecordTools(ToolBase):
                 force_refresh_form=force_refresh_form,
             )
             self._validate_record_write(app_key, normalized_answers, apply_id=normalized_apply_id)
-            result = self.backend.request(
-                "POST",
-                context,
-                f"/app/{app_key}/apply/{normalized_apply_id}",
-                json_body={"role": role, "answers": normalized_answers},
-            )
+            try:
+                result = self.backend.request(
+                    "POST",
+                    context,
+                    f"/app/{app_key}/apply/{normalized_apply_id}",
+                    json_body={"role": role, "answers": normalized_answers},
+                )
+            except QingflowApiError as exc:
+                self._remap_record_update_target_context_error(
+                    profile,
+                    context,
+                    app_key=app_key,
+                    apply_id=normalized_apply_id,
+                    exc=exc,
+                )
+                raise
             verification = self._verify_record_write_result(
                 context,
                 app_key=app_key,
@@ -6541,7 +6950,6 @@ class RecordTools(ToolBase):
         def runner(session_profile, context):
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
             view_selection = self._resolve_view_selection(profile, context, app_key, view_key=view_key, view_name=view_name)
-            dept_member_cache: dict[int, set[int]] = {}
             resolved_column_cap = _bounded_column_limit(
                 max_columns,
                 default_limit=MAX_LIST_COLUMN_LIMIT,
@@ -6647,13 +7055,6 @@ class RecordTools(ToolBase):
                         continue
                     answers = item.get("answers")
                     answer_list = answers if isinstance(answers, list) else []
-                    if not self._matches_view_selection(
-                        context,
-                        answer_list,
-                        view_selection=view_selection,
-                        dept_member_cache=dept_member_cache,
-                    ):
-                        continue
                     matched_records += 1
                     apply_id = _coerce_count(item.get("applyId")) or _coerce_count(item.get("id"))
                     row = _build_flat_row(answer_list, selected_fields_from_primary, apply_id=apply_id)
@@ -6890,6 +7291,8 @@ class RecordTools(ToolBase):
             isinstance(payload.get("viewgraphLimit"), list)
             or isinstance(payload.get("viewConfig"), dict)
             or isinstance(payload.get("viewgraphConfig"), dict)
+            or isinstance(payload.get("viewgraphQuestions"), list)
+            or isinstance(payload.get("viewgraphQueIds"), list)
         ):
             config = payload
         else:
@@ -8794,7 +9197,13 @@ class RecordTools(ToolBase):
             except json.JSONDecodeError:
                 parsed = None
             if isinstance(parsed, dict):
-                error_payload["error_code"] = parsed.get("error_code") or cast(JSONObject, parsed.get("details", {})).get("error_code") or error_payload["error_code"]
+                parsed_details = parsed.get("details")
+                details_payload = cast(JSONObject, parsed_details) if isinstance(parsed_details, dict) else None
+                error_payload["error_code"] = (
+                    parsed.get("error_code")
+                    or (details_payload.get("error_code") if details_payload is not None else None)
+                    or error_payload["error_code"]
+                )
                 error_payload["message"] = parsed.get("message") or error_payload["message"]
                 if parsed.get("backend_code") is not None:
                     error_payload["backend_code"] = parsed.get("backend_code")
@@ -8802,6 +9211,8 @@ class RecordTools(ToolBase):
                     error_payload["request_id"] = parsed.get("request_id")
                 if isinstance(parsed.get("request_route"), dict):
                     request_route = cast(JSONObject, parsed.get("request_route"))
+                elif details_payload is not None and isinstance(details_payload.get("request_route"), dict):
+                    request_route = cast(JSONObject, details_payload.get("request_route"))
         response: JSONObject = {
             "profile": profile,
             "ws_id": None,
@@ -10089,11 +10500,20 @@ class RecordTools(ToolBase):
         """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
-        try:
-            normalized_apply_id = normalize_positive_id_int(apply_id, field_name="apply_id")
-        except QingflowApiError:
-            raise_tool_error(QingflowApiError.config_error("apply_id must be positive"))
-        return normalized_apply_id
+        return self._normalize_internal_backend_id(apply_id, field_name="apply_id")
+
+    def _normalize_internal_backend_id(self, value: Any, *, field_name: str) -> int:
+        """Normalize backend/apply ids after the public boundary has already preserved long string ids."""
+        if value in (None, "") or isinstance(value, bool):
+            raise_tool_error(QingflowApiError.config_error(f"{field_name} must be positive"))
+        if isinstance(value, int):
+            if value <= 0:
+                raise_tool_error(QingflowApiError.config_error(f"{field_name} must be positive"))
+            return value
+        text = stringify_backend_id(value)
+        if text is None or not text.isdecimal() or int(text) <= 0:
+            raise_tool_error(QingflowApiError.config_error(f"{field_name} must be positive"))
+        return int(text)
 
     def _validate_record_write(self, app_key: str, answers: list[JSONObject], apply_id: int | None = None) -> None:
         """执行内部辅助逻辑。"""
@@ -11035,7 +11455,7 @@ def _list_sample_only(*, returned_items: int, row_cap: int, result_amount: int |
 def _list_sample_warning(*, returned_items: int, row_cap: int, result_amount: int | None) -> str:
     if _list_sample_only(returned_items=returned_items, row_cap=row_cap, result_amount=result_amount):
         return "当前仅返回样本，不适合最终统计结论。"
-    return "record_list 适合浏览或导出明细；最终统计结论请改用 record_browse_schema_get -> record_analyze。"
+    return "record_list 适合浏览或样本检查；最终统计结论请改用 record_browse_schema_get -> record_access -> Python。"
 
 
 def _resolve_query_mode(
@@ -11067,6 +11487,56 @@ def _chunk_fields(fields: list[FormField], chunk_size: int) -> list[list[FormFie
     return [fields[index : index + chunk_size] for index in range(0, len(fields), chunk_size)]
 
 
+def _record_access_run_dir() -> Path:
+    custom_home = os.getenv("QINGFLOW_MCP_RECORD_ACCESS_HOME")
+    base_dir = Path(custom_home).expanduser() if custom_home else get_mcp_home() / "record-access"
+    run_id = f"{datetime.now(UTC).strftime('%Y%m%dT%H%M%SZ')}-{uuid4().hex[:8]}"
+    return base_dir / run_id
+
+
+def _record_access_field_payload(field: FormField) -> JSONObject:
+    return {
+        "field_id": field.que_id,
+        "title": field.que_title,
+        "column_name": f"field_{field.que_id}",
+        "type": _record_access_field_type(field),
+    }
+
+
+def _record_access_field_type(field: FormField) -> str:
+    if field.que_type in DATE_QUE_TYPES:
+        return "datetime"
+    if field.que_type in NUMBER_QUE_TYPES:
+        return "number"
+    if field.que_type in MEMBER_QUE_TYPES:
+        return "member"
+    if field.que_type in DEPARTMENT_QUE_TYPES:
+        return "department"
+    if field.que_type in ADDRESS_QUE_TYPES:
+        return "address"
+    if field.que_type in RELATION_QUE_TYPES:
+        return "relation"
+    if field.que_type in ATTACHMENT_QUE_TYPES:
+        return "attachment"
+    if field.que_type in SINGLE_SELECT_QUE_TYPES:
+        return "single_select"
+    if field.que_type in MULTI_SELECT_QUE_TYPES:
+        return "multi_select"
+    if field.que_type in SUBTABLE_QUE_TYPES:
+        return "subtable"
+    return "value"
+
+
+def _record_access_csv_cell(value: JSONValue) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int | float | str):
+        return str(value)
+    return json.dumps(value, ensure_ascii=False)
+
+
 def _is_board_view_type(view_type: str | None) -> bool:
     normalized = _normalize_optional_text(view_type)
     return normalized is not None and normalized.lower() == "boardview"