@josephyan/qingflow-cli 0.2.0-beta.988 → 0.2.0-beta.990

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,
@@ -284,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 = "",
@@ -315,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 = "",
@@ -407,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,
@@ -439,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(
@@ -479,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,
@@ -505,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(
@@ -784,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):
@@ -815,7 +815,7 @@ class RecordTools(ToolBase):
             probes = self._probe_candidate_record_contexts(
                 context,
                 app_key=app_key,
-                apply_id=record_id,
+                apply_id=record_id_int,
                 candidate_routes=candidate_routes,
             )
             probe_summary: list[JSONObject] = []
@@ -906,7 +906,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=blockers,
                     warnings=warnings,
                     recommended_next_actions=recommended_next_actions,
@@ -949,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=[
@@ -969,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": {
@@ -1009,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": [],
@@ -1281,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,
@@ -1297,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)
@@ -1316,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,
             )
@@ -1327,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,
                 )
@@ -1366,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,
@@ -1385,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,
@@ -1401,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)
@@ -1420,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,
             )
@@ -1431,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,
                 )
@@ -1487,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,
@@ -1753,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,
@@ -1761,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):
@@ -1791,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:
@@ -1808,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
@@ -1823,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,
@@ -1851,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,
@@ -1874,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 [],
@@ -1975,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,
@@ -2004,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,
@@ -2201,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]:
@@ -2217,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}")
@@ -3069,22 +3082,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,
         }
@@ -8527,8 +8544,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,
         }
@@ -8727,7 +8744,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": [],
@@ -10072,8 +10089,9 @@ 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:
+        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
 
@@ -11084,10 +11102,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
-    return str(record_id)
+    if isinstance(record_id, int) and record_id <= 0:
+        return None
+    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]:
@@ -11640,10 +11662,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: