@qingflow-tech/qingflow-app-user-mcp 1.0.2 → 1.0.4

package/src/qingflow_mcp/tools/record_tools.py

@@ -13,6 +13,7 @@ from mcp.server.fastmcp import FastMCP
 
 from ..config import DEFAULT_PROFILE, DEFAULT_RECORD_LIST_TYPE
 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
 from ..list_type_labels import (
     SYSTEM_VIEW_DEFINITIONS,
@@ -180,6 +181,16 @@ class AccessibleViewRoute:
     view_type: str | None = None
 
 
+@dataclass(slots=True)
+class RecordContextRouteProbe:
+    route: AccessibleViewRoute
+    answer_list: list[JSONObject] | None
+    used_list_type: int | None
+    readable: bool
+    transport_error: bool
+    error_payload: JSONObject | None
+
+
 @dataclass(slots=True)
 class WorkflowNodeRef:
     workflow_node_id: int
@@ -274,7 +285,7 @@ class RecordTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             field_id: int = 0,
-            record_id: int | None = None,
+            record_id: str | None = None,
             workflow_node_id: int | None = None,
             fields: JSONObject | None = None,
             keyword: str = "",
@@ -305,7 +316,7 @@ class RecordTools(ToolBase):
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
             field_id: int = 0,
-            record_id: int | None = None,
+            record_id: str | None = None,
             workflow_node_id: int | None = None,
             fields: JSONObject | None = None,
             keyword: str = "",
@@ -397,7 +408,7 @@ class RecordTools(ToolBase):
         def record_get(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            record_id: int = 0,
+            record_id: str = "",
             columns: list[JSONObject | int] | None = None,
             view_id: str | None = None,
             workflow_node_id: int | None = None,
@@ -429,7 +440,7 @@ class RecordTools(ToolBase):
         @mcp.tool()
         def record_update_schema_get(
             app_key: str = "",
-            record_id: int = 0,
+            record_id: str = "",
             output_profile: str = "normal",
         ) -> JSONObject:
             return self.record_update_schema_get_public(
@@ -469,7 +480,7 @@ class RecordTools(ToolBase):
         )
         def record_update(
             app_key: str = "",
-            record_id: int | None = None,
+            record_id: str | None = None,
             fields: JSONObject | None = None,
             items: list[JSONObject] | None = None,
             dry_run: bool = False,
@@ -495,8 +506,8 @@ class RecordTools(ToolBase):
         )
         def record_delete(
             app_key: str = "",
-            record_id: int | None = None,
-            record_ids: list[int] | None = None,
+            record_id: str | None = None,
+            record_ids: list[str] | None = None,
             output_profile: str = "normal",
         ) -> JSONObject:
             return self.record_delete_public(
@@ -774,14 +785,13 @@ class RecordTools(ToolBase):
         *,
         profile: str = DEFAULT_PROFILE,
         app_key: str,
-        record_id: int,
+        record_id: Any,
         output_profile: str = "normal",
     ) -> JSONObject:
         """执行记录相关逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
-        if record_id <= 0:
-            raise_tool_error(QingflowApiError.config_error("record_id is required"))
+        record_id_int = normalize_positive_id_int(record_id, field_name="record_id")
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
 
         def runner(session_profile, context):
@@ -801,55 +811,29 @@ class RecordTools(ToolBase):
                 index=app_index,
                 question_relations=question_relations,
             )
-            try:
-                current_answers = self._load_record_answers_for_preflight(context, app_key=app_key, apply_id=record_id)
-            except QingflowApiError:
-                return self._record_update_schema_blocked_response(
-                    profile=profile,
-                    ws_id=session_profile.selected_ws_id,
-                    request_route=request_route,
-                    app_key=app_key,
-                    record_id=record_id,
-                    blockers=["CURRENT_RECORD_CONTEXT_UNAVAILABLE"],
-                    warnings=[
-                        "update schema could not load the current record; context-sensitive lookup requirements cannot be derived safely."
-                    ],
-                    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.",
-                    ],
-                    output_profile=normalized_output_profile,
-                    view_probe_summary=[],
-                    ambiguous_fields=[],
-                )
-
             candidate_routes = self._candidate_update_views(profile, context, app_key)
+            probes = self._probe_candidate_record_contexts(
+                context,
+                app_key=app_key,
+                apply_id=record_id_int,
+                candidate_routes=candidate_routes,
+            )
             probe_summary: list[JSONObject] = []
-            matched_any = False
+            matched_probes: list[RecordContextRouteProbe] = []
             ordered_field_ids: list[int] = []
             field_payloads_by_id: dict[int, JSONObject] = {}
             title_to_field_ids: dict[str, list[int]] = {}
             ws_id = session_profile.selected_ws_id
 
-            for candidate in candidate_routes:
-                matched_record = self._record_matches_accessible_view(
-                    context,
-                    current_answers,
-                    resolved_view=candidate,
-                )
-                candidate_summary: JSONObject = {
-                    "view_id": candidate.view_id,
-                    "name": candidate.name,
-                    "kind": candidate.kind,
-                    "matched_record": matched_record,
-                    "context_complete": True,
-                    "writable_field_titles": [],
-                }
-                if not matched_record:
+            for probe in probes:
+                candidate = probe.route
+                candidate_summary = self._record_context_probe_summary_payload(probe)
+                candidate_summary["writable_field_titles"] = []
+                if not probe.readable:
                     probe_summary.append(candidate_summary)
                     continue
 
-                matched_any = True
+                matched_probes.append(probe)
                 browse_scope = self._build_browse_write_scope(
                     profile,
                     context,
@@ -893,19 +877,39 @@ class RecordTools(ToolBase):
                 candidate_summary["writable_field_titles"] = candidate_titles
                 probe_summary.append(candidate_summary)
 
-            if not matched_any:
+            if not matched_probes:
+                blockers = (
+                    ["CURRENT_RECORD_CONTEXT_UNAVAILABLE"]
+                    if probes and all(probe.transport_error for probe in probes)
+                    else ["NO_MATCHING_ACCESSIBLE_VIEW_FOR_RECORD"]
+                )
+                warnings = (
+                    [
+                        "update schema could not load the current record from any candidate route; context-sensitive lookup requirements cannot be derived safely."
+                    ]
+                    if blockers == ["CURRENT_RECORD_CONTEXT_UNAVAILABLE"]
+                    else []
+                )
+                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 blockers == ["CURRENT_RECORD_CONTEXT_UNAVAILABLE"]
+                    else [
+                        "Check whether this record is still visible in any accessible view for the current profile.",
+                        "Use record_get or record_list to confirm the record still exists in the current workspace.",
+                    ]
+                )
                 return self._record_update_schema_blocked_response(
                     profile=profile,
                     ws_id=ws_id,
                     request_route=request_route,
                     app_key=app_key,
-                    record_id=record_id,
-                    blockers=["NO_MATCHING_ACCESSIBLE_VIEW_FOR_RECORD"],
-                    warnings=[],
-                    recommended_next_actions=[
-                        "Check whether this record is still visible in any accessible view for the current profile.",
-                        "Use record_get or record_list to confirm the record still exists in the current workspace.",
-                    ],
+                    record_id=record_id_int,
+                    blockers=blockers,
+                    warnings=warnings,
+                    recommended_next_actions=recommended_next_actions,
                     output_profile=normalized_output_profile,
                     view_probe_summary=probe_summary,
                     ambiguous_fields=[],
@@ -913,7 +917,10 @@ class RecordTools(ToolBase):
 
             ambiguous_field_ids: set[int] = set()
             ambiguous_fields: list[JSONObject] = []
-            warnings: list[JSONObject] = []
+            warnings: list[JSONObject] = [
+                {"code": "RECORD_CONTEXT_ROUTE_FALLBACK", "message": message}
+                for message in self._record_context_probe_fallback_warnings(probes)
+            ]
             for title, field_ids in title_to_field_ids.items():
                 unique_ids = list(dict.fromkeys(field_ids))
                 if len(unique_ids) <= 1:
@@ -942,7 +949,7 @@ class RecordTools(ToolBase):
                     ws_id=ws_id,
                     request_route=request_route,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     blockers=["NO_WRITABLE_FIELDS_FOR_RECORD"],
                     warnings=[item["message"] for item in warnings if isinstance(item.get("message"), str)],
                     recommended_next_actions=[
@@ -962,7 +969,7 @@ class RecordTools(ToolBase):
                 "request_route": request_route,
                 "warnings": warnings,
                 "app_key": app_key,
-                "record_id": record_id,
+                "record_id": stringify_backend_id(record_id_int),
                 "schema_scope": "update_ready",
                 "writable_fields": writable_fields,
                 "payload_template": {
@@ -972,6 +979,7 @@ class RecordTools(ToolBase):
             }
             if normalized_output_profile == "verbose":
                 response["view_probe_summary"] = probe_summary
+                response["record_context_probe"] = probe_summary
                 response["ambiguous_fields"] = ambiguous_fields
             return response
 
@@ -1001,7 +1009,7 @@ class RecordTools(ToolBase):
             "request_route": request_route,
             "warnings": [{"code": "PREFLIGHT_WARNING", "message": item} for item in warnings],
             "app_key": app_key,
-            "record_id": record_id,
+            "record_id": stringify_backend_id(record_id),
             "schema_scope": "update_ready",
             "blockers": blockers,
             "writable_fields": [],
@@ -1022,6 +1030,7 @@ class RecordTools(ToolBase):
         ws_id: int | None,
         required_override: bool | None,
         linkage_payloads_by_field_id: dict[str, JSONObject] | None = None,
+        include_field_id: bool = True,
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
         kind = self._ready_schema_kind(field)
@@ -1042,6 +1051,8 @@ class RecordTools(ToolBase):
             "kind": kind,
             "required": required,
         }
+        if include_field_id:
+            payload["field_id"] = field.que_id
         if kind in {"single_select", "multi_select"} and field.options:
             payload["options"] = list(field.options)
         if kind in {"member", "department", "relation"}:
@@ -1097,6 +1108,7 @@ class RecordTools(ToolBase):
             ws_id=ws_id,
             required_override=True,
             linkage_payloads_by_field_id=linkage_payloads_by_field_id,
+            include_field_id=False,
         )
         payload["reason"] = reason
         self._attach_ready_schema_linkage(
@@ -1177,6 +1189,7 @@ class RecordTools(ToolBase):
                     ws_id=ws_id,
                     required_override=bool(subfield.required),
                     linkage_payloads_by_field_id=linkage_payloads_by_field_id,
+                    include_field_id=False,
                 )
             )
         return payloads
@@ -1268,7 +1281,7 @@ class RecordTools(ToolBase):
         profile: str,
         app_key: str,
         field_id: int,
-        record_id: int | None = None,
+        record_id: Any | None = None,
         workflow_node_id: int | None = None,
         fields: JSONObject | None = None,
         keyword: str,
@@ -1284,6 +1297,12 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("page_num must be positive"))
         if page_size <= 0:
             raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
+        record_id_int = (
+            normalize_positive_id_int(record_id, field_name="record_id")
+            if record_id is not None
+            else None
+        )
+        record_id_text = stringify_backend_id(record_id_int) if record_id_int is not None else None
 
         def runner(session_profile, context):
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
@@ -1303,7 +1322,7 @@ class RecordTools(ToolBase):
                 )
             normalized_fields = fields if isinstance(fields, dict) else {}
             runtime_lookup = self._candidate_lookup_uses_runtime_scope(
-                record_id=record_id,
+                record_id=record_id_int,
                 workflow_node_id=workflow_node_id,
                 fields=normalized_fields,
             )
@@ -1314,7 +1333,7 @@ class RecordTools(ToolBase):
                     profile,
                     context,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     workflow_node_id=workflow_node_id,
                     fields=normalized_fields,
                 )
@@ -1353,7 +1372,7 @@ class RecordTools(ToolBase):
                         "app_key": app_key,
                         "field_id": field.que_id,
                         "field_title": field.que_title,
-                        "record_id": record_id,
+                        "record_id": record_id_text,
                         "workflow_node_id": workflow_node_id,
                         "fields_present": bool(normalized_fields),
                         "keyword": keyword,
@@ -1372,7 +1391,7 @@ class RecordTools(ToolBase):
         profile: str,
         app_key: str,
         field_id: int,
-        record_id: int | None = None,
+        record_id: Any | None = None,
         workflow_node_id: int | None = None,
         fields: JSONObject | None = None,
         keyword: str,
@@ -1388,6 +1407,12 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("page_num must be positive"))
         if page_size <= 0:
             raise_tool_error(QingflowApiError.config_error("page_size must be positive"))
+        record_id_int = (
+            normalize_positive_id_int(record_id, field_name="record_id")
+            if record_id is not None
+            else None
+        )
+        record_id_text = stringify_backend_id(record_id_int) if record_id_int is not None else None
 
         def runner(session_profile, context):
             index = self._get_field_index(profile, context, app_key, force_refresh=False)
@@ -1407,7 +1432,7 @@ class RecordTools(ToolBase):
                 )
             normalized_fields = fields if isinstance(fields, dict) else {}
             runtime_lookup = self._candidate_lookup_uses_runtime_scope(
-                record_id=record_id,
+                record_id=record_id_int,
                 workflow_node_id=workflow_node_id,
                 fields=normalized_fields,
             )
@@ -1418,7 +1443,7 @@ class RecordTools(ToolBase):
                     profile,
                     context,
                     app_key=app_key,
-                    record_id=record_id,
+                    record_id=record_id_int,
                     workflow_node_id=workflow_node_id,
                     fields=normalized_fields,
                 )
@@ -1474,7 +1499,7 @@ class RecordTools(ToolBase):
                         "app_key": app_key,
                         "field_id": field.que_id,
                         "field_title": field.que_title,
-                        "record_id": record_id,
+                        "record_id": record_id_text,
                         "workflow_node_id": workflow_node_id,
                         "fields_present": bool(normalized_fields),
                         "keyword": keyword,
@@ -1740,7 +1765,7 @@ class RecordTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        record_id: int,
+        record_id: Any,
         columns: list[JSONObject | int],
         view_id: str | None = None,
         workflow_node_id: int | None = None,
@@ -1748,8 +1773,7 @@ class RecordTools(ToolBase):
     ) -> JSONObject:
         """执行记录相关逻辑。"""
         normalized_output_profile = self._normalize_public_output_profile(output_profile, allow_normalized=True)
-        if record_id <= 0:
-            raise_tool_error(QingflowApiError.config_error("record_id must be positive"))
+        record_id_int = normalize_positive_id_int(record_id, field_name="record_id")
         normalized_columns = _normalize_public_column_selectors(columns)
 
         def runner(session_profile, context):
@@ -1778,7 +1802,7 @@ class RecordTools(ToolBase):
                 result = self.backend.request(
                     "GET",
                     context,
-                    f"/view/{resolved_view.view_selection.view_key}/apply/{record_id}",
+                    f"/view/{resolved_view.view_selection.view_key}/apply/{record_id_int}",
                 )
                 used_list_type = None
             else:
@@ -1795,7 +1819,7 @@ class RecordTools(ToolBase):
                         result = self.backend.request(
                             "GET",
                             context,
-                            f"/app/{app_key}/apply/{record_id}",
+                            f"/app/{app_key}/apply/{record_id_int}",
                             params={"role": 1, "listType": lt},
                         )
                         used_list_type = lt
@@ -1810,7 +1834,7 @@ class RecordTools(ToolBase):
                         raise last_error
                     raise_tool_error(QingflowApiError.config_error("record_get failed: no accessible listType"))
             answer_list = result.get("answers") if isinstance(result, dict) and isinstance(result.get("answers"), list) else []
-            row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id)
+            row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id_int)
             normalized_record, normalized_ambiguous_fields = _build_normalized_row_from_answers(
                 cast(list[JSONValue], answer_list),
                 selected_fields,
@@ -1838,7 +1862,7 @@ class RecordTools(ToolBase):
                     if normalized_columns
                     else list(index.by_id.values())
                 )
-                row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id)
+                row = _build_flat_row(cast(list[JSONValue], answer_list), selected_fields, apply_id=record_id_int)
                 normalized_record, normalized_ambiguous_fields = _build_normalized_row_from_answers(
                     cast(list[JSONValue], answer_list),
                     selected_fields,
@@ -1861,7 +1885,7 @@ class RecordTools(ToolBase):
                 "output_profile": normalized_output_profile,
                 "data": {
                     "app_key": app_key,
-                    "record_id": _public_record_id_text(record_id),
+                    "record_id": _public_record_id_text(record_id_int),
                     "record": row,
                     "selection": {
                         "columns": [_column_selector_payload(field_id) for field_id in normalized_columns] if normalized_columns else [],
@@ -1962,7 +1986,7 @@ class RecordTools(ToolBase):
         *,
         profile: str = DEFAULT_PROFILE,
         app_key: str,
-        record_id: int | None,
+        record_id: Any | None,
         fields: JSONObject | None = None,
         items: list[JSONObject] | None = None,
         dry_run: bool = False,
@@ -1991,14 +2015,15 @@ class RecordTools(ToolBase):
             )
         if dry_run:
             raise_tool_error(QingflowApiError.config_error("dry_run currently requires items"))
-        if record_id is None or record_id <= 0:
+        if record_id is None:
             raise_tool_error(QingflowApiError.config_error("record_id is required"))
+        record_id_int = normalize_positive_id_int(record_id, field_name="record_id")
         if fields is not None and not isinstance(fields, dict):
             raise_tool_error(QingflowApiError.config_error("fields must be an object map keyed by field title"))
         return self._record_update_public_single(
             profile=profile,
             app_key=app_key,
-            record_id=record_id,
+            record_id=record_id_int,
             fields=cast(JSONObject, fields or {}),
             verify_write=verify_write,
             output_profile=normalized_output_profile,
@@ -2188,7 +2213,7 @@ class RecordTools(ToolBase):
     def _normalize_public_record_update_batch_items(
         self,
         *,
-        record_id: int | None,
+        record_id: Any | None,
         fields: JSONObject | None,
         items: list[JSONObject] | None,
     ) -> list[JSONObject]:
@@ -2204,9 +2229,10 @@ class RecordTools(ToolBase):
         for index, item in enumerate(items):
             if not isinstance(item, dict):
                 raise_tool_error(QingflowApiError.config_error(f"items[{index}] must be an object"))
-            normalized_record_id = _coerce_count(item.get("record_id"))
-            if normalized_record_id is None or normalized_record_id <= 0:
-                raise_tool_error(QingflowApiError.config_error(f"items[{index}].record_id must be a positive integer"))
+            normalized_record_id = normalize_positive_id_int(
+                item.get("record_id"),
+                field_name=f"items[{index}].record_id",
+            )
             if normalized_record_id in seen_record_ids:
                 raise_tool_error(
                     QingflowApiError.config_error(f"duplicate record_id in items: {normalized_record_id}")
@@ -2336,9 +2362,15 @@ class RecordTools(ToolBase):
         def runner(session_profile, context):
             request_route = self._request_route_payload(context)
             def build_once(*, effective_force_refresh: bool) -> JSONObject:
-                try:
-                    current_answers = self._load_record_answers_for_preflight(context, app_key=app_key, apply_id=record_id)
-                except QingflowApiError:
+                candidate_routes = self._candidate_update_views(profile, context, app_key)
+                probes = self._probe_candidate_record_contexts(
+                    context,
+                    app_key=app_key,
+                    apply_id=record_id,
+                    candidate_routes=candidate_routes,
+                )
+                matched_probes = [probe for probe in probes if probe.readable]
+                if not matched_probes and probes and all(probe.transport_error for probe in probes):
                     return {
                         "profile": profile,
                         "ws_id": session_profile.selected_ws_id,
@@ -2349,46 +2381,40 @@ class RecordTools(ToolBase):
                             record_id=record_id,
                             blockers=["CURRENT_RECORD_CONTEXT_UNAVAILABLE"],
                             warnings=[
-                                "update preflight could not load the current record; automatic view selection was blocked to avoid resolving lookup fields against a partial patch."
+                                "update preflight could not load the current record from any candidate route; automatic view selection was blocked to avoid resolving lookup fields against a partial patch."
                             ],
                             recommended_next_actions=[
                                 "Retry after the record becomes readable in the current workspace/profile context.",
                                 "Call record_update_schema_get to inspect the overall writable field set for this record after context access is restored.",
                             ],
-                            view_probe_summary=[],
+                            view_probe_summary=[
+                                self._record_context_probe_summary_payload(probe)
+                                for probe in probes
+                            ],
                         ),
                     }
 
-                candidate_routes = self._candidate_update_views(profile, context, app_key)
                 probe_summary: list[JSONObject] = []
-                matched_any = False
                 matched_routes: list[AccessibleViewRoute] = []
+                matched_answers_for_union: list[JSONObject] | None = None
                 first_blocked_plan: JSONObject | None = None
                 first_confirmation_plan: JSONObject | None = None
-
-                for candidate in candidate_routes:
-                    matched_record = self._record_matches_accessible_view(
-                        context,
-                        current_answers,
-                        resolved_view=candidate,
-                    )
-                    if not matched_record:
-                        probe_summary.append(
-                            {
-                                "view_id": candidate.view_id,
-                                "name": candidate.name,
-                                "kind": candidate.kind,
-                                "matched_record": False,
-                                "writable_field_titles": [],
-                                "missing_field_titles": [],
-                                "context_complete": True,
-                                "selected": False,
-                            }
-                        )
+                fallback_warning_messages = self._record_context_probe_fallback_warnings(probes)
+
+                for probe in probes:
+                    candidate = probe.route
+                    candidate_summary = self._record_context_probe_summary_payload(probe)
+                    candidate_summary["writable_field_titles"] = []
+                    candidate_summary["missing_field_titles"] = []
+                    candidate_summary["selected"] = False
+                    if not probe.readable:
+                        probe_summary.append(candidate_summary)
                         continue
 
-                    matched_any = True
+                    current_answers = probe.answer_list or []
                     matched_routes.append(candidate)
+                    if matched_answers_for_union is None:
+                        matched_answers_for_union = current_answers
                     browse_scope = self._build_browse_write_scope(
                         profile,
                         context,
@@ -2444,16 +2470,8 @@ class RecordTools(ToolBase):
                             title = _normalize_optional_text(field_payload.get("que_title"))
                             if title and title not in missing_field_titles:
                                 missing_field_titles.append(title)
-                    candidate_summary: JSONObject = {
-                        "view_id": candidate.view_id,
-                        "name": candidate.name,
-                        "kind": candidate.kind,
-                        "matched_record": True,
-                        "writable_field_titles": candidate_titles,
-                        "missing_field_titles": missing_field_titles,
-                        "context_complete": True,
-                        "selected": False,
-                    }
+                    candidate_summary["writable_field_titles"] = candidate_titles
+                    candidate_summary["missing_field_titles"] = missing_field_titles
                     if plan_data.get("blockers"):
                         confirmation_requests = plan_data.get("confirmation_requests")
                         if (
@@ -2472,8 +2490,26 @@ class RecordTools(ToolBase):
                             view_payload["auto_selected"] = True
                             view_payload["selection_source"] = "first_satisfying_accessible_view"
                             candidate_summary["selected"] = True
+                            validation = plan_data.get("validation")
+                            if isinstance(validation, dict):
+                                warnings = validation.get("warnings")
+                                if not isinstance(warnings, list):
+                                    warnings = []
+                                    validation["warnings"] = warnings
+                                for message in fallback_warning_messages:
+                                    if message not in warnings:
+                                        warnings.append(message)
                             first_confirmation_plan = plan_data
                         elif first_blocked_plan is None:
+                            validation = plan_data.get("validation")
+                            if isinstance(validation, dict):
+                                warnings = validation.get("warnings")
+                                if not isinstance(warnings, list):
+                                    warnings = []
+                                    validation["warnings"] = warnings
+                                for message in fallback_warning_messages:
+                                    if message not in warnings:
+                                        warnings.append(message)
                             first_blocked_plan = plan_data
                         probe_summary.append(candidate_summary)
                         continue
@@ -2489,8 +2525,18 @@ class RecordTools(ToolBase):
                     view_payload["auto_selected"] = True
                     view_payload["selection_source"] = "first_satisfying_accessible_view"
                     candidate_summary["selected"] = True
+                    validation = plan_data.get("validation")
+                    if isinstance(validation, dict):
+                        warnings = validation.get("warnings")
+                        if not isinstance(warnings, list):
+                            warnings = []
+                            validation["warnings"] = warnings
+                        for message in fallback_warning_messages:
+                            if message not in warnings:
+                                warnings.append(message)
                     probe_summary.append(candidate_summary)
                     plan_data["view_probe_summary"] = probe_summary
+                    plan_data["record_context_probe"] = probe_summary
                     return {
                         "profile": profile,
                         "ws_id": session_profile.selected_ws_id,
@@ -2499,7 +2545,7 @@ class RecordTools(ToolBase):
                         "data": plan_data,
                     }
 
-                if not matched_any:
+                if not matched_probes:
                     blocked_data = self._build_auto_view_blocked_preflight_data(
                         app_key=app_key,
                         record_id=record_id,
@@ -2521,6 +2567,7 @@ class RecordTools(ToolBase):
 
                 if first_confirmation_plan is not None:
                     first_confirmation_plan["view_probe_summary"] = probe_summary
+                    first_confirmation_plan["record_context_probe"] = probe_summary
                     return {
                         "profile": profile,
                         "ws_id": session_profile.selected_ws_id,
@@ -2535,12 +2582,22 @@ class RecordTools(ToolBase):
                     app_key=app_key,
                     record_id=record_id,
                     fields=fields,
-                    current_answers=current_answers,
+                    current_answers=matched_answers_for_union or [],
                     matched_routes=matched_routes,
                     force_refresh_form=effective_force_refresh,
                 )
                 if union_plan is not None:
+                    validation = union_plan.get("validation")
+                    if isinstance(validation, dict):
+                        warnings = validation.get("warnings")
+                        if not isinstance(warnings, list):
+                            warnings = []
+                            validation["warnings"] = warnings
+                        for message in fallback_warning_messages:
+                            if message not in warnings:
+                                warnings.append(message)
                     union_plan["view_probe_summary"] = probe_summary
+                    union_plan["record_context_probe"] = probe_summary
                     return {
                         "profile": profile,
                         "ws_id": session_profile.selected_ws_id,
@@ -2803,8 +2860,6 @@ class RecordTools(ToolBase):
         """执行内部辅助逻辑。"""
         candidates: list[AccessibleViewRoute] = []
         for view_id, list_type, name in SYSTEM_VIEW_DEFINITIONS:
-            if not self._probe_list_type_access(context, app_key=app_key, list_type=list_type):
-                continue
             candidates.append(
                 AccessibleViewRoute(
                     view_id=view_id,
@@ -2821,11 +2876,22 @@ class RecordTools(ToolBase):
             view_key = _normalize_optional_text(item.get("viewKey"))
             if not view_key:
                 continue
-            view_selection = self._resolve_view_selection(profile, context, app_key, view_key=view_key, view_name=None)
-            if view_selection is None:
-                continue
-            view_name = _normalize_optional_text(item.get("viewName")) or view_selection.view_name or view_key
-            view_type = _normalize_optional_text(item.get("viewType") or item.get("viewgraphType")) or view_selection.view_type
+            view_name = _normalize_optional_text(item.get("viewName")) or view_key
+            view_type = _normalize_optional_text(item.get("viewType") or item.get("viewgraphType"))
+            filter_config: JSONObject | None = None
+            if isinstance(item.get("viewgraphLimit"), list):
+                filter_config = item
+            else:
+                raw_view_config = item.get("viewConfig")
+                if isinstance(raw_view_config, dict):
+                    filter_config = raw_view_config
+            view_selection = ViewSelection(
+                view_key=view_key,
+                view_name=view_name,
+                conditions=_compile_view_conditions(filter_config or {}),
+                view_type=view_type,
+                filter_config_loaded=isinstance(filter_config, dict),
+            )
             candidates.append(
                 AccessibleViewRoute(
                     view_id=f"custom:{view_key}",
@@ -2838,6 +2904,264 @@ class RecordTools(ToolBase):
             )
         return candidates
 
+    def _route_view_key(self, resolved_view: AccessibleViewRoute) -> str | None:
+        if resolved_view.view_selection is not None:
+            view_key = _normalize_optional_text(resolved_view.view_selection.view_key)
+            if view_key:
+                return view_key
+        if resolved_view.kind == "custom" and resolved_view.view_id.startswith("custom:"):
+            view_key = resolved_view.view_id.split(":", 1)[1].strip()
+            return view_key or None
+        return None
+
+    def _record_context_route_error_payload(self, error: QingflowApiError) -> JSONObject:
+        payload: JSONObject = {"message": error.message}
+        if error.category:
+            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, 40023, 40027, 40038, 404}:
+            return True
+        if error.http_status == 404:
+            return True
+        return False
+
+    def _load_record_answers_for_accessible_route(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+        resolved_view: AccessibleViewRoute,
+    ) -> tuple[list[JSONObject], int | None]:
+        if resolved_view.kind == "custom":
+            view_key = self._route_view_key(resolved_view)
+            if not view_key:
+                raise_tool_error(
+                    QingflowApiError.config_error(
+                        f"cannot resolve custom view route for '{resolved_view.view_id}'"
+                    )
+                )
+            record = self.backend.request(
+                "GET",
+                context,
+                f"/view/{view_key}/apply/{apply_id}",
+            )
+            used_list_type = None
+        else:
+            used_list_type = resolved_view.list_type if resolved_view.list_type is not None else DEFAULT_RECORD_LIST_TYPE
+            record = self.backend.request(
+                "GET",
+                context,
+                f"/app/{app_key}/apply/{apply_id}",
+                params={"role": 1, "listType": used_list_type},
+            )
+        answers = record.get("answers") if isinstance(record, dict) else None
+        normalized_answers = [item for item in answers if isinstance(item, dict)] if isinstance(answers, list) else []
+        return normalized_answers, used_list_type
+
+    def _probe_record_context_route(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+        resolved_view: AccessibleViewRoute,
+    ) -> RecordContextRouteProbe:
+        try:
+            answer_list, used_list_type = self._load_record_answers_for_accessible_route(
+                context,
+                app_key=app_key,
+                apply_id=apply_id,
+                resolved_view=resolved_view,
+            )
+            return RecordContextRouteProbe(
+                route=resolved_view,
+                answer_list=answer_list,
+                used_list_type=used_list_type,
+                readable=True,
+                transport_error=False,
+                error_payload=None,
+            )
+        except QingflowApiError as exc:
+            return RecordContextRouteProbe(
+                route=resolved_view,
+                answer_list=None,
+                used_list_type=resolved_view.list_type if resolved_view.kind == "system" else None,
+                readable=False,
+                transport_error=not self._is_record_context_route_miss(exc),
+                error_payload=self._record_context_route_error_payload(exc),
+            )
+
+    def _probe_candidate_record_contexts(
+        self,
+        context,  # type: ignore[no-untyped-def]
+        *,
+        app_key: str,
+        apply_id: int,
+        candidate_routes: list[AccessibleViewRoute],
+    ) -> list[RecordContextRouteProbe]:
+        return [
+            self._probe_record_context_route(
+                context,
+                app_key=app_key,
+                apply_id=apply_id,
+                resolved_view=candidate,
+            )
+            for candidate in candidate_routes
+        ]
+
+    def _record_context_probe_summary_payload(self, probe: RecordContextRouteProbe) -> JSONObject:
+        payload: JSONObject = {
+            "view_id": probe.route.view_id,
+            "name": probe.route.name,
+            "kind": probe.route.kind,
+            "matched_record": probe.readable,
+            "readable": probe.readable,
+            "context_complete": probe.readable,
+            "used_list_type": probe.used_list_type,
+        }
+        if probe.error_payload is not None:
+            payload["error"] = probe.error_payload
+            payload["transport_error"] = probe.transport_error
+        return payload
+
+    def _record_context_probe_fallback_warnings(
+        self,
+        probes: list[RecordContextRouteProbe],
+    ) -> list[str]:
+        matched_probes = [probe for probe in probes if probe.readable]
+        if not matched_probes:
+            return []
+        if any(
+            probe.route.kind == "system" and probe.used_list_type == DEFAULT_RECORD_LIST_TYPE
+            for probe in matched_probes
+        ):
+            return []
+        first_probe = matched_probes[0]
+        if first_probe.route.kind == "custom":
+            return [
+                "current record context was not accessible via listType="
+                f"{DEFAULT_RECORD_LIST_TYPE}; preflight resolved it via custom view "
+                f"'{first_probe.route.name}'."
+            ]
+        used_list_type = first_probe.used_list_type
+        if used_list_type is None:
+            return []
+        return [
+            "current record context was not accessible via listType="
+            f"{DEFAULT_RECORD_LIST_TYPE}; preflight resolved it via listType={used_list_type} "
+            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]
@@ -2861,22 +3185,26 @@ class RecordTools(ToolBase):
         *,
         profile: str = DEFAULT_PROFILE,
         app_key: str,
-        record_id: int | None = None,
-        record_ids: list[int] | None = None,
+        record_id: Any | None = None,
+        record_ids: list[Any] | None = None,
         output_profile: str = "normal",
     ) -> JSONObject:
         """执行记录相关逻辑。"""
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
-        normalized_record_ids = [item for item in (record_ids or []) if isinstance(item, int) and item > 0]
-        delete_ids = normalized_record_ids or ([record_id] if record_id is not None and record_id > 0 else [])
+        normalized_record_ids: list[int] = []
+        for index, item in enumerate(record_ids or []):
+            normalized_record_ids.append(normalize_positive_id_int(item, field_name=f"record_ids[{index}]"))
+        delete_ids = normalized_record_ids
+        if not delete_ids and record_id is not None:
+            delete_ids = [normalize_positive_id_int(record_id, field_name="record_id")]
         if not delete_ids:
             raise_tool_error(QingflowApiError.config_error("record_id or record_ids is required"))
         normalized_payload = {
             "operation": "delete",
-            "record_id": record_id,
-            "record_ids": delete_ids,
+            "record_id": stringify_backend_id(record_id) if record_id is not None else None,
+            "record_ids": [stringify_backend_id(item) for item in delete_ids],
             "answers": [],
             "submit_type": 1,
         }
@@ -5406,7 +5734,19 @@ class RecordTools(ToolBase):
                 existing_answers_loaded = True
             else:
                 try:
-                    existing_answers_for_update = self._load_record_answers_for_preflight(context, app_key=app_key, apply_id=apply_id)
+                    if resolved_view is not None:
+                        existing_answers_for_update, _used_list_type = self._load_record_answers_for_accessible_route(
+                            context,
+                            app_key=app_key,
+                            apply_id=apply_id,
+                            resolved_view=resolved_view,
+                        )
+                    else:
+                        existing_answers_for_update = self._load_record_answers_for_preflight(
+                            context,
+                            app_key=app_key,
+                            apply_id=apply_id,
+                        )
                     existing_answers_loaded = True
                 except QingflowApiError:
                     validation_warnings.append(
@@ -6118,12 +6458,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,
@@ -6653,6 +7003,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:
@@ -7144,13 +7496,6 @@ class RecordTools(ToolBase):
             raise_tool_error(QingflowApiError.config_error("view_id is required; call app_get first to inspect accessible_views"))
 
         system_all_list_type = SYSTEM_VIEW_ID_TO_LIST_TYPE["system:all"]
-        if not self._probe_list_type_access(context, app_key=app_key, list_type=system_all_list_type):
-            raise_tool_error(
-                QingflowApiError.config_error(
-                    "view_id is required because system:all is not accessible; call app_get first to inspect accessible_views"
-                )
-            )
-
         return (
             AccessibleViewRoute(
                 view_id="system:all",
@@ -8314,8 +8659,8 @@ class RecordTools(ToolBase):
         """执行内部辅助逻辑。"""
         payload: JSONObject = {
             "operation": operation,
-            "record_id": record_id,
-            "record_ids": record_ids,
+            "record_id": stringify_backend_id(record_id) if record_id is not None else None,
+            "record_ids": [stringify_backend_id(item) for item in record_ids],
             "answers": normalized_answers,
             "submit_type": submit_type,
         }
@@ -8514,7 +8859,7 @@ class RecordTools(ToolBase):
             "output_profile": output_profile,
             "data": {
                 "action": {"operation": operation, "executed": True},
-                "resource": raw_apply.get("resource"),
+                "resource": _public_record_resource(raw_apply.get("resource")),
                 "verification": raw_apply.get("verification"),
                 "normalized_payload": normalized_payload,
                 "blockers": [],
@@ -8564,7 +8909,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")
@@ -8572,6 +8923,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,
@@ -9859,10 +10212,20 @@ class RecordTools(ToolBase):
         """执行内部辅助逻辑。"""
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))
-        normalized_apply_id = _coerce_count(apply_id)
-        if normalized_apply_id is None or normalized_apply_id <= 0:
-            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:
         """执行内部辅助逻辑。"""
@@ -10871,10 +11234,14 @@ def _build_flat_row(answer_list: list[JSONValue], fields: list[FormField], *, ap
     return row
 
 
-def _public_record_id_text(record_id: int | None) -> str | None:
-    if record_id is None or record_id <= 0:
+def _public_record_id_text(record_id: Any) -> str | None:
+    if record_id is None or isinstance(record_id, bool):
+        return None
+    if isinstance(record_id, int) and record_id <= 0:
         return None
-    return str(record_id)
+    if isinstance(record_id, str) and (not record_id.strip() or not record_id.strip().isdecimal()):
+        return None
+    return stringify_backend_id(record_id)
 
 
 def _normalize_public_record_rows(rows: list[JSONValue]) -> list[JSONObject]:
@@ -11427,10 +11794,29 @@ def _field_mapping_entry(role: str, field: FormField | None, *, requested: str)
     }
 
 
-def _record_resource_payload(record_id: int | None) -> JSONObject | None:
-    if record_id is None or record_id <= 0:
+def _record_resource_payload(record_id: Any) -> JSONObject | None:
+    public_record_id = _public_record_id_text(record_id)
+    if public_record_id is None:
         return None
-    return {"type": "record", "record_id": record_id, "apply_id": record_id}
+    return {"type": "record", "record_id": public_record_id, "apply_id": public_record_id}
+
+
+def _public_record_resource(resource: Any) -> Any:
+    if not isinstance(resource, dict) or resource.get("type") != "record":
+        return resource
+    payload = dict(resource)
+    if "record_id" in payload:
+        payload["record_id"] = _public_record_id_text(payload.get("record_id"))
+    if "apply_id" in payload:
+        payload["apply_id"] = _public_record_id_text(payload.get("apply_id"))
+    record_ids = payload.get("record_ids")
+    if isinstance(record_ids, list):
+        payload["record_ids"] = [
+            stringify_backend_id(item)
+            for item in record_ids
+            if stringify_backend_id(item) is not None
+        ]
+    return payload
 
 
 def _query_id() -> str: