@josephyan/qingflow-app-user-mcp 0.2.0-beta.20 → 0.2.0-beta.21

package/src/qingflow_mcp/tools/record_tools.py

@@ -192,155 +192,88 @@ class RecordTools(ToolBase):
 
         @mcp.tool(
             description=(
-                "Static preflight for record create/update payloads. Supports ergonomic fields{} mapping, resolves field titles, "
-                "and reports blockers before submit."
+                "Browse Qingflow records with a schema-first list DSL. "
+                "Use record_schema_get first, then pass field_id-only columns, where, and order_by clauses. "
+                "This route is for browse/export/sample inspection only, not analysis."
             )
         )
-        def record_write_plan(
+        def record_list(
             profile: str = DEFAULT_PROFILE,
-            operation: str = "auto",
             app_key: str = "",
-            apply_id: int | None = None,
-            answers: list[JSONObject] | None = None,
-            fields: JSONObject | None = None,
-            force_refresh_form: bool = False,
+            columns: list[int] | None = None,
+            where: list[JSONObject] | None = None,
+            order_by: list[JSONObject] | None = None,
+            limit: int = 50,
+            page: int = 1,
+            view_key: str | None = None,
+            view_name: str | None = None,
+            output_profile: str = "normal",
         ) -> JSONObject:
-            return self.record_write_plan(
+            return self.record_list(
                 profile=profile,
-                operation=operation,
                 app_key=app_key,
-                apply_id=apply_id,
-                answers=answers or [],
-                fields=fields or {},
-                force_refresh_form=force_refresh_form,
+                columns=columns or [],
+                where=where or [],
+                order_by=order_by or [],
+                limit=limit,
+                page=page,
+                view_key=view_key,
+                view_name=view_name,
+                output_profile=output_profile,
             )
 
-        @mcp.tool(
-            description=(
-                "Unified read entry for record list / record detail. "
-                "Use query_mode=auto to route: apply_id -> record, otherwise -> list. "
-                "query_mode only supports auto, list, or record. "
-                "For statistical analysis use record_schema_get and record_analyze."
-            )
-        )
-        def record_query(
+        @mcp.tool(description="Read one Qingflow record by record_id. Use record_schema_get first if columns are ambiguous.")
+        def record_get(
             profile: str = DEFAULT_PROFILE,
-            query_mode: str = "auto",
             app_key: str = "",
-            apply_id: int | None = None,
-            page_num: int = 1,
-            query_key: str | None = None,
-            filters: list[JSONObject] | None = None,
-            sorts: list[JSONObject] | None = None,
-            max_rows: int = DEFAULT_ROW_LIMIT,
-            max_columns: int | None = None,
-            select_columns: list[str | int] | None = None,
-            output_profile: str = DEFAULT_OUTPUT_PROFILE,
-            list_type: int = DEFAULT_RECORD_LIST_TYPE,
-            view_key: str | None = None,
-            view_name: str | None = None,
+            record_id: int = 0,
+            columns: list[int] | None = None,
+            workflow_node_id: int | None = None,
+            output_profile: str = "normal",
         ) -> JSONObject:
-            paging = _fixed_list_scan_policy()
-            return self.record_query(
+            return self.record_get_public(
                 profile=profile,
-                query_mode=query_mode,
                 app_key=app_key,
-                apply_id=apply_id,
-                page_num=page_num,
-                page_size=int(paging["page_size"]),
-                requested_pages=int(paging["requested_pages"]),
-                scan_max_pages=int(paging["scan_max_pages"]),
-                auto_expand_pages=bool(paging["auto_expand_pages"]),
-                query_key=query_key,
-                filters=filters or [],
-                sorts=sorts or [],
-                max_rows=max_rows,
-                max_columns=max_columns,
-                select_columns=select_columns or [],
-                amount_column=None,
-                time_range={},
-                stat_policy={},
-                strict_full=False,
+                record_id=record_id,
+                columns=columns or [],
+                workflow_node_id=workflow_node_id,
                 output_profile=output_profile,
-                list_type=list_type,
-                view_key=view_key,
-                view_name=view_name,
             )
 
         @mcp.tool(
             description=(
-                "Create one record. Supports explicit answers[] and ergonomic fields{} mapping by exact field title or queId. "
-                "Use record_write_plan first for complex payloads."
+                "Write Qingflow records with a SQL-like JSON DSL. "
+                "Use record_schema_get first, then choose operation=insert|update|delete and mode=plan|apply. "
+                "This route does not accept raw SQL strings or free-form WHERE clauses."
             )
         )
-        def record_create(
+        def record_write(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            answers: list[JSONObject] | None = None,
-            fields: JSONObject | None = None,
-            submit_type: int = 1,
-            verify_write: bool = False,
-            force_refresh_form: bool = False,
+            operation: str = "insert",
+            mode: str = "plan",
+            record_id: int | None = None,
+            record_ids: list[int] | None = None,
+            values: list[JSONObject] | None = None,
+            set: list[JSONObject] | None = None,
+            submit_type: str | int = "submit",
+            verify_write: bool = True,
+            output_profile: str = "normal",
         ) -> JSONObject:
-            return self.record_create(
+            return self.record_write(
                 profile=profile,
                 app_key=app_key,
-                answers=answers or [],
-                fields=fields or {},
+                operation=operation,
+                mode=mode,
+                record_id=record_id,
+                record_ids=record_ids or [],
+                values=values or [],
+                set=set or [],
                 submit_type=submit_type,
                 verify_write=verify_write,
-                force_refresh_form=force_refresh_form,
-            )
-
-        @mcp.tool()
-        def record_get(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            apply_id: int = 0,
-            role: int = 1,
-            list_type: int | None = None,
-            audit_node_id: int | None = None,
-        ) -> JSONObject:
-            return self.record_get(
-                profile=profile,
-                app_key=app_key,
-                apply_id=apply_id,
-                role=role,
-                list_type=list_type,
-                audit_node_id=audit_node_id,
-            )
-
-        @mcp.tool(description=self._high_risk_tool_description(operation="update", target="record data"))
-        def record_update(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            apply_id: int = 0,
-            answers: list[JSONObject] | None = None,
-            fields: JSONObject | None = None,
-            role: int = 1,
-            verify_write: bool = False,
-            force_refresh_form: bool = False,
-        ) -> JSONObject:
-            return self.record_update(
-                profile=profile,
-                app_key=app_key,
-                apply_id=apply_id,
-                answers=answers or [],
-                fields=fields or {},
-                role=role,
-                verify_write=verify_write,
-                force_refresh_form=force_refresh_form,
+                output_profile=output_profile,
             )
 
-        @mcp.tool(description=self._high_risk_tool_description(operation="delete", target="record data"))
-        def record_delete(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            apply_id: int = 0,
-            list_type: int = DEFAULT_RECORD_LIST_TYPE,
-        ) -> JSONObject:
-            return self.record_delete(profile=profile, app_key=app_key, apply_id=apply_id, list_type=list_type)
-
     def record_schema_get(
         self,
         *,
@@ -445,7 +378,349 @@ class RecordTools(ToolBase):
 
         return self._run_record_tool(profile, runner)
 
+    def record_list(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        columns: list[int],
+        where: list[JSONObject],
+        order_by: list[JSONObject],
+        limit: int,
+        page: int,
+        view_key: str | None,
+        view_name: str | None,
+        output_profile: str,
+    ) -> 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"))
+        if not columns:
+            raise_tool_error(QingflowApiError.config_error("columns is required"))
+        if any(not isinstance(item, int) or item < 0 for item in columns):
+            raise_tool_error(QingflowApiError.config_error("columns must be a list of field_id integers"))
+        if limit <= 0:
+            raise_tool_error(QingflowApiError.config_error("limit must be positive"))
+        if page <= 0:
+            raise_tool_error(QingflowApiError.config_error("page must be positive"))
+
+        raw = self.record_query(
+            profile=profile,
+            query_mode="list",
+            app_key=app_key,
+            apply_id=None,
+            page_num=page,
+            page_size=DEFAULT_LIST_PAGE_SIZE,
+            requested_pages=1,
+            scan_max_pages=1,
+            auto_expand_pages=False,
+            query_key=None,
+            filters=self._normalize_record_list_where(where),
+            sorts=self._normalize_record_list_order_by(order_by),
+            max_rows=limit,
+            max_columns=len(columns),
+            select_columns=columns,
+            amount_column=None,
+            time_range={},
+            stat_policy={},
+            strict_full=False,
+            output_profile="verbose" if normalized_output_profile == "verbose" else DEFAULT_OUTPUT_PROFILE,
+            list_type=DEFAULT_RECORD_LIST_TYPE,
+            view_key=view_key,
+            view_name=view_name,
+        )
+        list_data = cast(JSONObject, cast(JSONObject, raw["data"])["list"])
+        pagination = cast(JSONObject, list_data["pagination"])
+        warnings: list[JSONObject] = []
+        warning = _normalize_optional_text(list_data.get("analysis_warning"))
+        if warning:
+            warnings.append({"code": "BROWSE_ONLY", "message": warning})
+        response: JSONObject = {
+            "profile": profile,
+            "ws_id": raw.get("ws_id"),
+            "ok": bool(raw.get("ok", True)),
+            "request_route": raw.get("request_route"),
+            "warnings": warnings,
+            "output_profile": normalized_output_profile,
+            "data": {
+                "app_key": app_key,
+                "items": list_data.get("rows", []),
+                "pagination": {
+                    "page": page,
+                    "limit": limit,
+                    "returned_items": pagination.get("returned_items"),
+                    "result_amount": pagination.get("result_amount"),
+                },
+                "selection": {
+                    "columns": columns,
+                    "view": cast(JSONObject, raw["data"]).get("view"),
+                },
+            },
+        }
+        if normalized_output_profile == "verbose":
+            response["data"]["debug"] = {
+                "completeness": raw.get("completeness"),
+                "evidence": raw.get("evidence"),
+                "resolved_mappings": raw.get("resolved_mappings"),
+                "row_cap_hit": list_data.get("row_cap_hit"),
+                "sample_only": list_data.get("sample_only"),
+            }
+        return response
+
+    def record_get_public(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        record_id: int,
+        columns: list[int],
+        workflow_node_id: int | None,
+        output_profile: str,
+    ) -> JSONObject:
+        normalized_output_profile = self._normalize_public_output_profile(output_profile)
+        if record_id <= 0:
+            raise_tool_error(QingflowApiError.config_error("record_id must be positive"))
+        if columns and any(not isinstance(item, int) or item < 0 for item in columns):
+            raise_tool_error(QingflowApiError.config_error("columns must be a list of field_id integers"))
+
+        if columns:
+            raw = self.record_query(
+                profile=profile,
+                query_mode="record",
+                app_key=app_key,
+                apply_id=record_id,
+                page_num=1,
+                page_size=20,
+                requested_pages=1,
+                scan_max_pages=1,
+                auto_expand_pages=False,
+                query_key=None,
+                filters=[],
+                sorts=[],
+                max_rows=1,
+                max_columns=len(columns),
+                select_columns=columns,
+                amount_column=None,
+                time_range={},
+                stat_policy={},
+                strict_full=False,
+                output_profile="verbose" if normalized_output_profile == "verbose" else DEFAULT_OUTPUT_PROFILE,
+                list_type=DEFAULT_RECORD_LIST_TYPE,
+            )
+            record_data = cast(JSONObject, cast(JSONObject, raw["data"])["record"])
+            response: JSONObject = {
+                "profile": profile,
+                "ws_id": raw.get("ws_id"),
+                "ok": bool(raw.get("ok", True)),
+                "request_route": raw.get("request_route"),
+                "warnings": [],
+                "output_profile": normalized_output_profile,
+                "data": {
+                    "app_key": app_key,
+                    "record_id": record_id,
+                    "record": record_data.get("row"),
+                    "selection": {
+                        "columns": columns,
+                        "workflow_node_id": workflow_node_id,
+                    },
+                },
+            }
+            if normalized_output_profile == "verbose":
+                response["data"]["debug"] = {
+                    "evidence": raw.get("evidence"),
+                    "resolved_mappings": raw.get("resolved_mappings"),
+                }
+            return response
+
+        raw = self.record_get(
+            profile=profile,
+            app_key=app_key,
+            apply_id=record_id,
+            role=1,
+            list_type=None,
+            audit_node_id=workflow_node_id,
+        )
+        return {
+            "profile": profile,
+            "ws_id": raw.get("ws_id"),
+            "ok": bool(raw.get("ok", True)),
+            "request_route": raw.get("request_route"),
+            "warnings": [],
+            "output_profile": normalized_output_profile,
+            "data": {
+                "app_key": app_key,
+                "record_id": record_id,
+                "record": raw.get("result"),
+                "selection": {
+                    "columns": columns,
+                    "workflow_node_id": workflow_node_id,
+                },
+            },
+        }
+
+    def record_write(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        operation: str,
+        mode: str,
+        record_id: int | None,
+        record_ids: list[int],
+        values: list[JSONObject],
+        set: list[JSONObject],
+        submit_type: str | int,
+        verify_write: bool,
+        output_profile: str,
+    ) -> JSONObject:
+        normalized_output_profile = self._normalize_public_output_profile(output_profile)
+        normalized_operation = operation.strip().lower()
+        normalized_mode = mode.strip().lower()
+        if normalized_operation not in {"insert", "update", "delete"}:
+            raise_tool_error(QingflowApiError.config_error("operation must be insert, update, or delete"))
+        if normalized_mode not in {"plan", "apply"}:
+            raise_tool_error(QingflowApiError.config_error("mode must be plan or apply"))
+        if not app_key:
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+        normalized_record_ids = [item for item in record_ids if isinstance(item, int) and item > 0]
+        submit_type_value = self._normalize_record_write_submit_type(submit_type)
+
+        if normalized_operation == "insert":
+            if record_id is not None or normalized_record_ids:
+                raise_tool_error(QingflowApiError.config_error("insert must not include record_id or record_ids"))
+            if set:
+                raise_tool_error(QingflowApiError.config_error("insert must use values, not set"))
+            normalized_answers = self._normalize_record_write_clauses(values, location="values")
+            normalized_payload: JSONObject = {
+                "operation": "insert",
+                "record_id": None,
+                "record_ids": [],
+                "answers": normalized_answers,
+                "submit_type": submit_type_value,
+            }
+            if normalized_mode == "plan":
+                raw_plan = self.record_write_plan(
+                    profile=profile,
+                    operation="create",
+                    app_key=app_key,
+                    apply_id=None,
+                    answers=normalized_answers,
+                    fields={},
+                    force_refresh_form=False,
+                )
+                return self._record_write_plan_response(
+                    raw_plan,
+                    operation="insert",
+                    normalized_payload=normalized_payload,
+                    output_profile=normalized_output_profile,
+                    human_review=False,
+                )
+            raw_apply = self.record_create(
+                profile=profile,
+                app_key=app_key,
+                answers=normalized_answers,
+                fields={},
+                submit_type=submit_type_value,
+                verify_write=verify_write,
+                force_refresh_form=False,
+            )
+            return self._record_write_apply_response(
+                raw_apply,
+                operation="insert",
+                normalized_payload=normalized_payload,
+                output_profile=normalized_output_profile,
+                human_review=False,
+            )
+
+        if normalized_operation == "update":
+            if record_id is None or record_id <= 0:
+                raise_tool_error(QingflowApiError.config_error("update requires record_id"))
+            if normalized_record_ids:
+                raise_tool_error(QingflowApiError.config_error("update does not support record_ids"))
+            if values:
+                raise_tool_error(QingflowApiError.config_error("update must use set, not values"))
+            normalized_answers = self._normalize_record_write_clauses(set, location="set")
+            normalized_payload = {
+                "operation": "update",
+                "record_id": record_id,
+                "record_ids": [],
+                "answers": normalized_answers,
+                "submit_type": submit_type_value,
+            }
+            if normalized_mode == "plan":
+                raw_plan = self.record_write_plan(
+                    profile=profile,
+                    operation="update",
+                    app_key=app_key,
+                    apply_id=record_id,
+                    answers=normalized_answers,
+                    fields={},
+                    force_refresh_form=False,
+                )
+                return self._record_write_plan_response(
+                    raw_plan,
+                    operation="update",
+                    normalized_payload=normalized_payload,
+                    output_profile=normalized_output_profile,
+                    human_review=True,
+                )
+            raw_apply = self.record_update(
+                profile=profile,
+                app_key=app_key,
+                apply_id=record_id,
+                answers=normalized_answers,
+                fields={},
+                role=1,
+                verify_write=verify_write,
+                force_refresh_form=False,
+            )
+            return self._record_write_apply_response(
+                raw_apply,
+                operation="update",
+                normalized_payload=normalized_payload,
+                output_profile=normalized_output_profile,
+                human_review=True,
+            )
+
+        if values or set:
+            raise_tool_error(QingflowApiError.config_error("delete must not include values or set"))
+        delete_ids = normalized_record_ids or ([record_id] if record_id is not None and record_id > 0 else [])
+        if not delete_ids:
+            raise_tool_error(QingflowApiError.config_error("delete requires record_id or record_ids"))
+        normalized_payload = {
+            "operation": "delete",
+            "record_id": record_id,
+            "record_ids": delete_ids,
+            "answers": [],
+            "submit_type": submit_type_value,
+        }
+        if normalized_mode == "plan":
+            return {
+                "profile": profile,
+                "ok": True,
+                "request_route": None,
+                "warnings": [],
+                "output_profile": normalized_output_profile,
+                "data": {
+                    "action": {"operation": "delete", "mode": "plan"},
+                    "resource": {"type": "record", "app_key": app_key, "record_id": record_id, "record_ids": delete_ids},
+                    "verification": None,
+                    "normalized_payload": normalized_payload,
+                    "blockers": [],
+                    "human_review": self._record_write_human_review_payload("delete", enabled=True),
+                },
+            }
+        raw_apply = self._record_delete_many(profile=profile, app_key=app_key, record_ids=delete_ids)
+        return self._record_write_apply_response(
+            raw_apply,
+            operation="delete",
+            normalized_payload=normalized_payload,
+            output_profile=normalized_output_profile,
+            human_review=True,
+        )
+
     def _schema_field_payload(self, field: FormField) -> JSONObject:
+        write_hints = self._schema_write_hints(field)
         return {
             "field_id": field.que_id,
             "title": field.que_title,
@@ -455,6 +730,15 @@ class RecordTools(ToolBase):
             "options": field.options,
             "aliases": field.aliases,
             "role_hints": self._schema_role_hints(field),
+            "readable": True,
+            "writable": write_hints["writable"],
+            "write_kind": write_hints["write_kind"],
+            "supported_read_ops": write_hints["supported_read_ops"],
+            "supported_write_ops": write_hints["supported_write_ops"],
+            "requires_lookup": write_hints["requires_lookup"],
+            "requires_upload": write_hints["requires_upload"],
+            "requires_existing_row_id": write_hints["requires_existing_row_id"],
+            "unsupported_reason": write_hints["unsupported_reason"],
         }
 
     def _schema_role_hints(self, field: FormField) -> JSONObject:
@@ -475,6 +759,49 @@ class RecordTools(ToolBase):
             "semantic_hints": self._schema_semantic_hint(field, field_family=field_family),
         }
 
+    def _schema_write_hints(self, field: FormField) -> JSONObject:
+        write_format = _write_format_for_field(field)
+        kind = _normalize_optional_text(write_format.get("kind")) or "scalar_text"
+        support_level = _normalize_optional_text(write_format.get("support_level")) or "full"
+        write_kind = self._schema_write_kind(kind)
+        writable = bool(not field.system and not field.readonly and support_level != "unsupported")
+        supported_write_ops = ["insert", "update"] if writable else []
+        requires_lookup = write_kind in {"member", "department", "relation"}
+        requires_upload = write_kind == "attachment"
+        requires_existing_row_id = write_kind == "subtable"
+        unsupported_reason = _normalize_optional_text(write_format.get("reason"))
+        supported_read_ops = ["select"]
+        if field.que_type not in ATTACHMENT_QUE_TYPES | SUBTABLE_QUE_TYPES:
+            supported_read_ops.append("filter")
+        if field.que_type not in ATTACHMENT_QUE_TYPES | RELATION_QUE_TYPES | SUBTABLE_QUE_TYPES:
+            supported_read_ops.append("sort")
+        return {
+            "writable": writable,
+            "write_kind": write_kind,
+            "supported_read_ops": supported_read_ops,
+            "supported_write_ops": supported_write_ops,
+            "requires_lookup": requires_lookup,
+            "requires_upload": requires_upload,
+            "requires_existing_row_id": requires_existing_row_id,
+            "unsupported_reason": unsupported_reason,
+        }
+
+    def _schema_write_kind(self, kind: str) -> str:
+        mapping = {
+            "single_select": "select",
+            "multi_select": "select",
+            "member_list": "member",
+            "department_list": "department",
+            "relation_record": "relation",
+            "attachment_list": "attachment",
+            "subtable_rows": "subtable",
+            "unsupported_direct_write": "unsupported",
+            "boolean_label": "scalar",
+            "date_string": "scalar",
+            "scalar_text": "scalar",
+        }
+        return mapping.get(kind, "scalar")
+
     def _schema_field_family(self, field: FormField) -> str:
         if self._schema_is_identifier_like(field):
             return "text"
@@ -2553,6 +2880,178 @@ class RecordTools(ToolBase):
             "qf_version_source": getattr(context, "qf_version_source", None) or ("context" if getattr(context, "qf_version", None) else "unknown"),
         }
 
+    def _normalize_public_output_profile(self, output_profile: str) -> str:
+        normalized = (output_profile or "normal").strip().lower()
+        if normalized not in {"normal", "verbose"}:
+            raise_tool_error(QingflowApiError.config_error("output_profile must be normal or verbose"))
+        return normalized
+
+    def _normalize_record_list_where(self, where: list[JSONObject]) -> list[JSONObject]:
+        normalized: list[JSONObject] = []
+        for idx, item in enumerate(where):
+            if not isinstance(item, dict):
+                raise_tool_error(QingflowApiError.config_error(f"where[{idx}] must be an object"))
+            field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+            if field_id is None:
+                raise_tool_error(QingflowApiError.config_error(f"where[{idx}] requires field_id"))
+            payload: JSONObject = {"field_id": field_id}
+            if "op" in item:
+                payload["op"] = item["op"]
+            if "operator" in item:
+                payload["operator"] = item["operator"]
+            if "value" in item:
+                payload["value"] = item["value"]
+            elif "values" in item:
+                payload["values"] = item["values"]
+            normalized.append(payload)
+        return normalized
+
+    def _normalize_record_list_order_by(self, order_by: list[JSONObject]) -> list[JSONObject]:
+        normalized: list[JSONObject] = []
+        for idx, item in enumerate(order_by):
+            if not isinstance(item, dict):
+                raise_tool_error(QingflowApiError.config_error(f"order_by[{idx}] must be an object"))
+            field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+            if field_id is None:
+                raise_tool_error(QingflowApiError.config_error(f"order_by[{idx}] requires field_id"))
+            direction = _normalize_optional_text(item.get("direction", item.get("order"))) or "asc"
+            if direction not in {"asc", "desc"}:
+                raise_tool_error(QingflowApiError.config_error(f"order_by[{idx}].direction must be asc or desc"))
+            normalized.append({"field_id": field_id, "direction": direction})
+        return normalized
+
+    def _normalize_record_write_submit_type(self, submit_type: str | int) -> int:
+        if isinstance(submit_type, int):
+            if submit_type in {0, 1}:
+                return submit_type
+            raise_tool_error(QingflowApiError.config_error("submit_type must be 0, 1, save, or submit"))
+        normalized = (submit_type or "submit").strip().lower()
+        if normalized == "submit":
+            return 1
+        if normalized in {"save", "draft"}:
+            return 0
+        raise_tool_error(QingflowApiError.config_error("submit_type must be save or submit"))
+
+    def _normalize_record_write_clauses(self, clauses: list[JSONObject], *, location: str) -> list[JSONObject]:
+        normalized: list[JSONObject] = []
+        for idx, item in enumerate(clauses):
+            if not isinstance(item, dict):
+                raise_tool_error(QingflowApiError.config_error(f"{location}[{idx}] must be an object"))
+            field_id = _coerce_count(item.get("field_id", item.get("fieldId")))
+            if field_id is None:
+                raise_tool_error(QingflowApiError.config_error(f"{location}[{idx}] requires field_id"))
+            payload: JSONObject = {"field_id": field_id}
+            if "value" in item:
+                payload["value"] = item["value"]
+            elif "values" in item:
+                payload["values"] = item["values"]
+            else:
+                raise_tool_error(QingflowApiError.config_error(f"{location}[{idx}] requires value"))
+            normalized.append(payload)
+        return normalized
+
+    def _record_write_human_review_payload(self, operation: str, *, enabled: bool) -> JSONObject | None:
+        if not enabled:
+            return None
+        return {
+            "required": True,
+            "operation": operation,
+            "message": "Read the current record first and confirm the exact target before applying this high-risk write.",
+        }
+
+    def _record_write_plan_response(
+        self,
+        raw_plan: JSONObject,
+        *,
+        operation: str,
+        normalized_payload: JSONObject,
+        output_profile: str,
+        human_review: bool,
+    ) -> JSONObject:
+        plan_data = cast(JSONObject, raw_plan.get("data", {}))
+        validation = cast(JSONObject, plan_data.get("validation", {}))
+        warnings_payload = validation.get("warnings", [])
+        warnings = [{"code": "PLAN_WARNING", "message": str(item)} for item in warnings_payload] if isinstance(warnings_payload, list) else []
+        response: JSONObject = {
+            "profile": raw_plan.get("profile"),
+            "ws_id": raw_plan.get("ws_id"),
+            "ok": bool(raw_plan.get("ok", True)),
+            "request_route": raw_plan.get("request_route"),
+            "warnings": warnings,
+            "output_profile": output_profile,
+            "data": {
+                "action": {"operation": operation, "mode": "plan"},
+                "resource": {"type": "record", "app_key": plan_data.get("app_key"), "record_id": plan_data.get("apply_id")},
+                "verification": None,
+                "normalized_payload": normalized_payload,
+                "blockers": plan_data.get("blockers", []),
+                "human_review": self._record_write_human_review_payload(operation, enabled=human_review),
+            },
+        }
+        if output_profile == "verbose":
+            response["data"]["debug"] = {
+                "legacy_plan": plan_data,
+            }
+        return response
+
+    def _record_write_apply_response(
+        self,
+        raw_apply: JSONObject,
+        *,
+        operation: str,
+        normalized_payload: JSONObject,
+        output_profile: str,
+        human_review: bool,
+    ) -> JSONObject:
+        response: JSONObject = {
+            "profile": raw_apply.get("profile"),
+            "ws_id": raw_apply.get("ws_id"),
+            "ok": bool(raw_apply.get("ok", True)),
+            "request_route": raw_apply.get("request_route"),
+            "warnings": [],
+            "output_profile": output_profile,
+            "data": {
+                "action": {"operation": operation, "mode": "apply"},
+                "resource": raw_apply.get("resource"),
+                "verification": raw_apply.get("verification"),
+                "normalized_payload": normalized_payload,
+                "blockers": [],
+                "human_review": self._record_write_human_review_payload(operation, enabled=human_review),
+            },
+        }
+        if output_profile == "verbose":
+            response["data"]["debug"] = {
+                "legacy_result": raw_apply.get("result"),
+                "status": raw_apply.get("status"),
+                "write_verified": raw_apply.get("write_verified"),
+            }
+        return response
+
+    def _record_delete_many(self, *, profile: str, app_key: str, record_ids: list[int]) -> JSONObject:
+        if not app_key:
+            raise_tool_error(QingflowApiError.config_error("app_key is required"))
+        normalized_ids = [item for item in record_ids if isinstance(item, int) and item > 0]
+        if not normalized_ids:
+            raise_tool_error(QingflowApiError.config_error("record_ids must contain at least one positive id"))
+
+        def runner(session_profile, context):
+            result = self.backend.request(
+                "DELETE",
+                context,
+                f"/app/{app_key}/apply",
+                json_body={"type": DEFAULT_RECORD_LIST_TYPE, "applyIds": normalized_ids},
+            )
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "request_route": self._request_route_payload(context),
+                "result": result,
+                "resource": {"type": "record", "apply_ids": normalized_ids},
+                "ok": True,
+            }
+
+        return self._run_record_tool(profile, runner)
+
     def _resolve_field_selector(self, selector: str | int | None, index: FieldIndex, *, location: str) -> FormField:
         if selector is None:
             raise RecordInputError(
@@ -3349,7 +3848,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_query(list) 适合浏览或导出明细；最终统计结论请改用 record_schema_get -> record_analyze。"
+    return "record_list 适合浏览或导出明细；最终统计结论请改用 record_schema_get -> record_analyze。"
 
 
 def _resolve_query_mode(