@qingflow-tech/qingflow-app-builder-mcp 1.0.5 → 1.0.7

package/src/qingflow_mcp/tools/record_tools.py

@@ -470,21 +470,22 @@ class RecordTools(ToolBase):
 
         @mcp.tool(
             description=(
-                "Insert one Qingflow record using an applicant-node field map. "
+                "Insert Qingflow records using applicant-node field maps. "
                 "Use record_insert_schema_get first. "
-                "This tool performs internal preflight validation before any write is applied."
+                "Prefer items=[{'fields': {...}}]; a single insert is one item. "
+                "Each item performs internal preflight validation before that item is written."
             )
         )
         def record_insert(
             app_key: str = "",
-            fields: JSONObject | None = None,
+            items: list[JSONObject] | None = None,
             verify_write: bool = True,
             output_profile: str = "normal",
         ) -> JSONObject:
             return self.record_insert_public(
                 profile=DEFAULT_PROFILE,
                 app_key=app_key,
-                fields=fields or {},
+                items=items,
                 verify_write=verify_write,
                 output_profile=output_profile,
             )
@@ -1064,11 +1065,16 @@ class RecordTools(ToolBase):
             required = bool(required_override) if required_override is not None else bool(field.required or any(item.get("required") for item in row_fields))
         else:
             required = bool(required_override) if required_override is not None else bool(field.required)
+        write_format = _write_format_for_field(field)
         payload: JSONObject = {
             "title": field.que_title,
             "kind": kind,
             "required": required,
+            "format_hint": _ready_schema_format_hint(kind, write_format),
         }
+        example_value = _ready_schema_example_value(kind, field, write_format, row_fields=row_fields)
+        if example_value is not None:
+            payload["example_value"] = example_value
         if include_field_id:
             payload["field_id"] = field.que_id
         if kind in {"single_select", "multi_select"} and field.options:
@@ -2995,6 +3001,7 @@ class RecordTools(ToolBase):
         profile: str = DEFAULT_PROFILE,
         app_key: str,
         fields: JSONObject | None = None,
+        items: list[JSONObject] | None = None,
         verify_write: bool = True,
         output_profile: str = "normal",
     ) -> JSONObject:
@@ -3002,68 +3009,477 @@ class RecordTools(ToolBase):
         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 items is not None:
+            normalized_items = self._normalize_public_record_insert_batch_items(fields=fields, items=items)
+            return self._record_insert_public_batch(
+                profile=profile,
+                app_key=app_key,
+                items=normalized_items,
+                verify_write=verify_write,
+                output_profile=normalized_output_profile,
+            )
         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"))
-        submit_type_value = self._normalize_record_write_submit_type("submit")
-        raw_preflight = self._preflight_record_write(
+        return self._record_insert_public_single(
             profile=profile,
-            operation="create",
             app_key=app_key,
-            apply_id=None,
-            answers=[],
             fields=cast(JSONObject, fields or {}),
-            force_refresh_form=False,
-            view_id=None,
-            list_type=None,
-            view_key=None,
-            view_name=None,
-        )
-        preflight_used_force_refresh = self._record_preflight_used_force_refresh(raw_preflight)
-        preflight_data = cast(JSONObject, raw_preflight.get("data", {}))
-        normalized_payload: JSONObject = self._record_write_normalized_payload(
-            operation="insert",
-            record_id=None,
-            record_ids=[],
-            normalized_answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
-            submit_type=submit_type_value,
-            selection=cast(JSONObject | None, preflight_data.get("selection") if isinstance(preflight_data.get("selection"), dict) else None),
+            verify_write=verify_write,
+            output_profile=normalized_output_profile,
+            capture_exceptions=False,
         )
-        if preflight_data.get("blockers"):
-            return self._record_write_blocked_response(
-                raw_preflight,
-                operation="insert",
-                normalized_payload=normalized_payload,
-                output_profile=normalized_output_profile,
-                human_review=False,
-                target_resource={"type": "record", "app_key": app_key, "record_id": None, "record_ids": []},
-            )
+
+    def _record_insert_public_single(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        fields: JSONObject,
+        verify_write: bool,
+        output_profile: str,
+        capture_exceptions: bool,
+    ) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        submit_type_value = self._normalize_record_write_submit_type("submit")
+        write_attempted = False
         try:
-            raw_apply = self.record_create(
+            raw_preflight = self._preflight_record_write(
                 profile=profile,
+                operation="create",
                 app_key=app_key,
-                answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
-                fields={},
+                apply_id=None,
+                answers=[],
+                fields=fields,
+                force_refresh_form=False,
+                view_id=None,
+                list_type=None,
+                view_key=None,
+                view_name=None,
+            )
+            preflight_used_force_refresh = self._record_preflight_used_force_refresh(raw_preflight)
+            preflight_data = cast(JSONObject, raw_preflight.get("data", {}))
+            normalized_payload: JSONObject = self._record_write_normalized_payload(
+                operation="insert",
+                record_id=None,
+                record_ids=[],
+                normalized_answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
                 submit_type=submit_type_value,
-                verify_write=verify_write,
-                force_refresh_form=preflight_used_force_refresh,
+                selection=cast(JSONObject | None, preflight_data.get("selection") if isinstance(preflight_data.get("selection"), dict) else None),
             )
-        except QingflowApiError as exc:
-            self._raise_record_write_permission_error(
+            if preflight_data.get("blockers"):
+                return self._record_write_blocked_response(
+                    raw_preflight,
+                    operation="insert",
+                    normalized_payload=normalized_payload,
+                    output_profile=output_profile,
+                    human_review=False,
+                    target_resource={"type": "record", "app_key": app_key, "record_id": None, "record_ids": []},
+                )
+            try:
+                write_attempted = True
+                raw_apply = self.record_create(
+                    profile=profile,
+                    app_key=app_key,
+                    answers=cast(list[JSONObject], preflight_data.get("normalized_answers", [])),
+                    fields={},
+                    submit_type=submit_type_value,
+                    verify_write=verify_write,
+                    force_refresh_form=preflight_used_force_refresh,
+                )
+            except QingflowApiError as exc:
+                self._raise_record_write_permission_error(
+                    exc,
+                    operation="insert",
+                    app_key=app_key,
+                    record_id=None,
+                    selection=cast(JSONObject | None, preflight_data.get("selection") if isinstance(preflight_data.get("selection"), dict) else None),
+                )
+                raise
+            return self._record_write_apply_response(
+                raw_apply,
+                operation="insert",
+                normalized_payload=normalized_payload,
+                output_profile=output_profile,
+                human_review=False,
+                preflight=raw_preflight,
+            )
+        except (QingflowApiError, RuntimeError) as exc:
+            if not capture_exceptions:
+                raise
+            return self._record_write_exception_response(
                 exc,
                 operation="insert",
+                profile=profile,
                 app_key=app_key,
                 record_id=None,
-                selection=cast(JSONObject | None, preflight_data.get("selection") if isinstance(preflight_data.get("selection"), dict) else None),
+                output_profile=output_profile,
+                human_review=False,
+                write_executed=write_attempted,
             )
-            raise
-        return self._record_write_apply_response(
-            raw_apply,
-            operation="insert",
-            normalized_payload=normalized_payload,
-            output_profile=normalized_output_profile,
-            human_review=False,
-            preflight=raw_preflight,
+
+    def _normalize_public_record_insert_batch_items(
+        self,
+        *,
+        fields: JSONObject | None,
+        items: list[JSONObject] | None,
+    ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
+        if fields is not None:
+            raise_tool_error(QingflowApiError.config_error("record_insert batch mode does not accept fields"))
+        if not isinstance(items, list) or not items:
+            raise_tool_error(QingflowApiError.config_error("items must be a non-empty list"))
+        normalized_items: list[JSONObject] = []
+        for index, item in enumerate(items):
+            if not isinstance(item, dict):
+                raise_tool_error(QingflowApiError.config_error(f"items[{index}] must be an object"))
+            item_fields = item.get("fields")
+            if not isinstance(item_fields, dict):
+                raise_tool_error(QingflowApiError.config_error(f"items[{index}].fields must be an object map keyed by field title"))
+            normalized_items.append({"fields": cast(JSONObject, item_fields)})
+        return normalized_items
+
+    def _record_insert_public_batch(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        items: list[JSONObject],
+        verify_write: bool,
+        output_profile: str,
+    ) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        responses: list[JSONObject] = []
+        for item in items:
+            responses.append(
+                self._record_insert_public_single(
+                    profile=profile,
+                    app_key=app_key,
+                    fields=cast(JSONObject, item["fields"]),
+                    verify_write=verify_write,
+                    output_profile=output_profile,
+                    capture_exceptions=True,
+                )
+            )
+        return self._record_insert_batch_response(
+            profile=profile,
+            app_key=app_key,
+            responses=responses,
+            output_profile=output_profile,
+        )
+
+    def _record_insert_batch_response(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        responses: list[JSONObject],
+        output_profile: str,
+    ) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        items = [
+            self._record_insert_batch_item_from_response(index=index, response=response, output_profile=output_profile)
+            for index, response in enumerate(responses)
+        ]
+        summary = self._record_insert_batch_summary(items)
+        status, ok, message = self._record_insert_batch_envelope_status(summary=summary)
+        first_response = responses[0] if responses else {}
+        created_record_ids = [
+            cast(str, item["record_id"])
+            for item in items
+            if isinstance(item.get("record_id"), str) and item.get("record_id")
+        ]
+        write_executed = any(bool(item.get("write_executed")) for item in items)
+        verification_status = self._record_insert_batch_verification_status(items)
+        return {
+            "profile": first_response.get("profile", profile),
+            "ws_id": first_response.get("ws_id"),
+            "ok": ok,
+            "status": status,
+            "mode": "batch",
+            "total": summary["total"],
+            "succeeded": summary["succeeded"],
+            "failed": summary["failed"],
+            "created_record_ids": created_record_ids,
+            "write_executed": write_executed,
+            "verification_status": verification_status,
+            "safe_to_retry": not write_executed,
+            "request_route": first_response.get("request_route"),
+            "warnings": [],
+            "output_profile": output_profile,
+            "items": items,
+            "data": {
+                "app_key": app_key,
+                "mode": "batch",
+                "summary": summary,
+                "created_record_ids": created_record_ids,
+                "items": items,
+            },
+            "message": message,
+        }
+
+    def _record_insert_batch_summary(self, items: list[JSONObject]) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        created = [item for item in items if isinstance(item.get("record_id"), str) and item.get("record_id")]
+        failed = [item for item in items if item.get("status") not in {"success", "verification_failed"}]
+        return {
+            "total": len(items),
+            "succeeded": len(created),
+            "failed": len(failed),
+            "created_count": len(created),
+            "blocked_count": sum(1 for item in items if item.get("status") == "blocked"),
+            "confirmation_count": sum(1 for item in items if item.get("status") == "needs_confirmation"),
+            "verification_failed_count": sum(1 for item in items if item.get("status") == "verification_failed"),
+        }
+
+    def _record_insert_batch_envelope_status(self, *, summary: JSONObject) -> tuple[str, bool, str]:
+        """执行内部辅助逻辑。"""
+        succeeded = int(summary["succeeded"])
+        failed = int(summary["failed"])
+        if succeeded and failed:
+            return "partial_success", False, "batch insert completed with partial failures"
+        if succeeded and int(summary["verification_failed_count"]):
+            return "verification_failed", True, "batch insert completed but verification failed for some created records"
+        if succeeded:
+            return "success", True, "batch insert completed"
+        if int(summary["confirmation_count"]):
+            return "needs_confirmation", False, "batch insert requires confirmation before retrying failed rows"
+        if int(summary["blocked_count"]):
+            return "blocked", False, "batch insert preflight blocked all rows"
+        return "failed", False, "batch insert failed"
+
+    def _record_insert_batch_verification_status(self, items: list[JSONObject]) -> str:
+        """执行内部辅助逻辑。"""
+        statuses = {str(item.get("verification_status") or "not_requested") for item in items}
+        if "failed" in statuses:
+            return "failed"
+        if "verified" in statuses:
+            return "verified"
+        return "not_requested"
+
+    def _record_insert_batch_item_from_response(
+        self,
+        *,
+        index: int,
+        response: JSONObject,
+        output_profile: str,
+    ) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        data = cast(JSONObject, response.get("data", {})) if isinstance(response.get("data"), dict) else {}
+        resource = _public_record_resource(data.get("resource"))
+        record_id = _public_record_id_text(response.get("record_id"))
+        apply_id = _public_record_id_text(response.get("apply_id"))
+        if record_id is None and isinstance(resource, dict):
+            record_id = _public_record_id_text(resource.get("record_id"))
+        if apply_id is None and isinstance(resource, dict):
+            apply_id = _public_record_id_text(resource.get("apply_id"))
+        item: JSONObject = {
+            "index": index,
+            "row_number": index + 1,
+            "status": response.get("status"),
+            "write_executed": bool(response.get("write_executed")),
+            "verification_status": response.get("verification_status", "not_requested"),
+            "safe_to_retry": bool(response.get("safe_to_retry", True)),
+        }
+        if record_id is not None:
+            item["record_id"] = record_id
+        if apply_id is not None:
+            item["apply_id"] = apply_id
+        if resource:
+            item["resource"] = resource
+        verification = data.get("verification")
+        if isinstance(verification, dict):
+            compact_verification = {
+                key: verification[key]
+                for key in ("verified", "verification_mode", "field_level_verified")
+                if key in verification
+            }
+            if compact_verification:
+                item["verification"] = compact_verification
+        field_errors = cast(list[JSONObject], data.get("field_errors", [])) if isinstance(data.get("field_errors"), list) else []
+        confirmation_requests = cast(list[JSONObject], data.get("confirmation_requests", [])) if isinstance(data.get("confirmation_requests"), list) else []
+        failed_fields = self._record_write_failed_fields(field_errors=field_errors, confirmation_requests=confirmation_requests)
+        if failed_fields:
+            item["failed_fields"] = failed_fields
+        if confirmation_requests:
+            item["confirmation_requests"] = [
+                self._record_write_semantic_confirmation_request(request)
+                for request in confirmation_requests
+                if isinstance(request, dict)
+            ]
+        blockers = data.get("blockers")
+        if isinstance(blockers, list) and blockers:
+            item["blockers"] = blockers
+        warnings = response.get("warnings")
+        if isinstance(warnings, list) and warnings:
+            item["warnings"] = warnings
+        error = data.get("error")
+        if isinstance(error, dict):
+            item["error"] = error
+        if output_profile == "verbose" and isinstance(data.get("debug"), dict):
+            item["debug"] = data.get("debug")
+        return item
+
+    def _record_write_failed_fields(
+        self,
+        *,
+        field_errors: list[JSONObject],
+        confirmation_requests: list[JSONObject],
+    ) -> list[JSONObject]:
+        """执行内部辅助逻辑。"""
+        failed_fields = [
+            self._record_write_semantic_field_error(error)
+            for error in field_errors
+            if isinstance(error, dict)
+        ]
+        failed_fields.extend(
+            self._record_write_failed_field_from_confirmation(request)
+            for request in confirmation_requests
+            if isinstance(request, dict)
         )
+        return failed_fields
+
+    def _record_write_semantic_field_error(self, error: JSONObject) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        field = error.get("field")
+        field_payload = cast(JSONObject, field) if isinstance(field, dict) else {}
+        error_code = _normalize_optional_text(error.get("error_code")) or "INVALID_FIELD_VALUE"
+        title = (
+            _normalize_optional_text(field_payload.get("que_title"))
+            or _normalize_optional_text(field_payload.get("title"))
+            or _normalize_optional_text(error.get("location"))
+            or "unknown field"
+        )
+        field_id = (
+            field_payload.get("que_id")
+            if field_payload.get("que_id") is not None
+            else field_payload.get("field_id")
+        )
+        expected_format = error.get("expected_format") if isinstance(error.get("expected_format"), dict) else None
+        if expected_format is None:
+            expected_format = self._record_write_expected_format_from_field_payload(field_payload)
+        payload: JSONObject = {
+            "title": title,
+            "field_id": field_id,
+            "error_code": error_code,
+            "message": self._record_write_semantic_error_message(error_code, error.get("message")),
+            "next_action": self._record_write_next_action_for_error(error_code),
+        }
+        if expected_format is not None:
+            payload["expected_format"] = expected_format
+            payload["example_value"] = self._record_write_example_value_for_format(expected_format, field_payload)
+        if error.get("received_value") is not None:
+            payload["received_value"] = error.get("received_value")
+        if error.get("fix_hint") is not None:
+            payload["fix_hint"] = error.get("fix_hint")
+        if error.get("details") is not None:
+            payload["details"] = error.get("details")
+        return payload
+
+    def _record_write_semantic_confirmation_request(self, request: JSONObject) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        field_ref = request.get("field_ref")
+        field_payload = cast(JSONObject, field_ref) if isinstance(field_ref, dict) else {}
+        payload: JSONObject = {
+            "field": request.get("field"),
+            "title": _normalize_optional_text(request.get("field")) or _normalize_optional_text(field_payload.get("que_title")),
+            "field_id": field_payload.get("que_id"),
+            "kind": request.get("kind"),
+            "input": request.get("input"),
+            "candidates": request.get("candidates", []),
+            "next_action": "让用户确认候选，或用显式 id/object 只重试本行。",
+        }
+        if request.get("parent_field") is not None:
+            payload["parent_field"] = request.get("parent_field")
+        if request.get("row_ordinal") is not None:
+            payload["row_ordinal"] = request.get("row_ordinal")
+        return payload
+
+    def _record_write_failed_field_from_confirmation(self, request: JSONObject) -> JSONObject:
+        """执行内部辅助逻辑。"""
+        semantic = self._record_write_semantic_confirmation_request(request)
+        return {
+            "title": semantic.get("title") or semantic.get("field"),
+            "field_id": semantic.get("field_id"),
+            "error_code": "LOOKUP_NEEDS_CONFIRMATION",
+            "message": "候选不唯一，需要用户确认。",
+            "kind": semantic.get("kind"),
+            "input": semantic.get("input"),
+            "candidates": semantic.get("candidates", []),
+            "next_action": semantic.get("next_action"),
+        }
+
+    def _record_write_expected_format_from_field_payload(self, field_payload: JSONObject) -> JSONObject | None:
+        """执行内部辅助逻辑。"""
+        que_type = _coerce_count(field_payload.get("que_type"))
+        if que_type is None:
+            return None
+        synthetic_field = FormField(
+            que_id=_coerce_count(field_payload.get("que_id")) or 0,
+            que_title=_normalize_optional_text(field_payload.get("que_title")) or _normalize_optional_text(field_payload.get("title")) or "",
+            que_type=que_type,
+            required=False,
+            readonly=False,
+            system=False,
+            options=[],
+            aliases=[],
+            target_app_key=None,
+            target_app_name_hint=None,
+            member_select_scope_type=None,
+            member_select_scope=None,
+            dept_select_scope_type=None,
+            dept_select_scope=None,
+            raw={},
+        )
+        return _write_format_for_field(synthetic_field)
+
+    def _record_write_example_value_for_format(self, expected_format: JSONObject, field_payload: JSONObject) -> JSONValue:
+        """执行内部辅助逻辑。"""
+        examples = expected_format.get("examples")
+        if isinstance(examples, list) and examples:
+            return cast(JSONValue, examples[0])
+        kind = _normalize_optional_text(expected_format.get("kind"))
+        if kind == "member_list":
+            return "张三"
+        if kind == "department_list":
+            return "直销部"
+        if kind == "relation_record":
+            return {"apply_id": "5001"}
+        if kind == "attachment_list":
+            return {"value": "<file_upload_local 返回的 value/url>", "name": "example.pdf"}
+        if kind == "subtable_rows":
+            return {"rows": [{"子字段": "值"}]}
+        if kind == "date_string":
+            return "2026-03-13 10:00:00"
+        if kind == "boolean_label":
+            return "是"
+        if kind in {"single_select", "multi_select"}:
+            options = expected_format.get("options")
+            if isinstance(options, list) and options:
+                return cast(JSONValue, options[0])
+        que_type = _coerce_count(field_payload.get("que_type"))
+        if que_type in NUMBER_QUE_TYPES:
+            return 100
+        return "文本"
+
+    def _record_write_semantic_error_message(self, error_code: str, fallback: JSONValue) -> str:
+        """执行内部辅助逻辑。"""
+        if error_code == "MISSING_REQUIRED_FIELD":
+            return "缺少必填字段。"
+        if error_code == "FIELD_NOT_FOUND":
+            return "字段不存在或字段标题不匹配。"
+        if error_code == "AMBIGUOUS_FIELD":
+            return "字段标题存在歧义。"
+        if error_code in {"INVALID_FIELD_VALUE", "INVALID_MEMBER_VALUE", "INVALID_DEPARTMENT_VALUE", "INVALID_RELATION_VALUE"}:
+            return _normalize_optional_text(fallback) or "字段值格式不正确。"
+        return _normalize_optional_text(fallback) or "字段写入失败。"
+
+    def _record_write_next_action_for_error(self, error_code: str) -> str:
+        """执行内部辅助逻辑。"""
+        if error_code == "MISSING_REQUIRED_FIELD":
+            return "补充该字段后只重试本行。"
+        if error_code in {"FIELD_NOT_FOUND", "AMBIGUOUS_FIELD"}:
+            return "重新调用 schema 工具确认字段标题或 field_id 后，只重试本行。"
+        return "修正该字段值后只重试本行。"
 
     @tool_cn_name("更新记录")
     def record_update_public(
@@ -7357,7 +7773,7 @@ class RecordTools(ToolBase):
                 "result": result,
                 "normalized_answers": normalized_answers,
                 "status": "completed" if verified else "verification_failed",
-                "ok": verified,
+                "ok": True,
                 "apply_id": apply_id,
                 "record_id": apply_id,
                 "verify_write": verify_write,
@@ -7561,7 +7977,7 @@ class RecordTools(ToolBase):
                     "result": result,
                     "normalized_answers": normalized_answers,
                     "status": "completed" if verified else "verification_failed",
-                    "ok": verified,
+                    "ok": True,
                     "verify_write": verify_write,
                     "write_verified": verified if verify_write else None,
                     "verification": verification,
@@ -10100,6 +10516,9 @@ class RecordTools(ToolBase):
             "ws_id": raw_preflight.get("ws_id"),
             "ok": False,
             "status": status,
+            "write_executed": False,
+            "verification_status": "not_requested",
+            "safe_to_retry": True,
             "request_route": raw_preflight.get("request_route"),
             "warnings": warnings,
             "output_profile": output_profile,
@@ -10143,6 +10562,9 @@ class RecordTools(ToolBase):
             "ws_id": raw_preflight.get("ws_id"),
             "ok": True,
             "status": "ready",
+            "write_executed": False,
+            "verification_status": "not_requested",
+            "safe_to_retry": True,
             "request_route": raw_preflight.get("request_route"),
             "warnings": warnings,
             "output_profile": output_profile,
@@ -10185,17 +10607,45 @@ class RecordTools(ToolBase):
         resolved_fields = cast(list[JSONObject], preflight_data.get("lookup_resolved_fields", []))
         if isinstance(verification_warnings, list):
             warnings.extend(cast(list[JSONObject], [item for item in verification_warnings if isinstance(item, dict)]))
+        resource = _public_record_resource(raw_apply.get("resource"))
+        record_id = _public_record_id_text(resource.get("record_id")) if isinstance(resource, dict) else None
+        apply_id = _public_record_id_text(resource.get("apply_id")) if isinstance(resource, dict) else None
+        if record_id is None:
+            record_id = _public_record_id_text(raw_apply.get("record_id"))
+        if apply_id is None:
+            apply_id = _public_record_id_text(raw_apply.get("apply_id"))
+        if apply_id is None:
+            apply_id = record_id
+        if record_id is None:
+            record_id = apply_id
+        write_executed = True
+        verification_requested = (
+            raw_apply.get("verify_write") is True
+            or raw_apply.get("write_verified") is not None
+            or isinstance(raw_apply.get("verification"), dict)
+        )
+        if verification_requested:
+            verification_status = "verified" if bool(verification.get("verified")) else "failed"
+        else:
+            verification_status = "not_requested"
+        raw_status = _normalize_optional_text(raw_apply.get("status"))
+        response_status = "verification_failed" if verification_status == "failed" else "success"
+        if not bool(raw_apply.get("ok", True)) and verification_status != "failed":
+            response_status = raw_status or "failed"
         response: JSONObject = {
             "profile": raw_apply.get("profile"),
             "ws_id": raw_apply.get("ws_id"),
-            "ok": bool(raw_apply.get("ok", True)),
-            "status": "success" if bool(raw_apply.get("ok", True)) else _normalize_optional_text(raw_apply.get("status")) or "failed",
+            "ok": True if verification_status == "failed" and write_executed else bool(raw_apply.get("ok", True)),
+            "status": response_status,
+            "write_executed": write_executed,
+            "verification_status": verification_status,
+            "safe_to_retry": False,
             "request_route": raw_apply.get("request_route"),
             "warnings": warnings,
             "output_profile": output_profile,
             "data": {
                 "action": {"operation": operation, "executed": True},
-                "resource": _public_record_resource(raw_apply.get("resource")),
+                "resource": resource,
                 "verification": raw_apply.get("verification"),
                 "normalized_payload": normalized_payload,
                 "blockers": [],
@@ -10205,6 +10655,10 @@ class RecordTools(ToolBase):
                 "human_review": self._record_write_human_review_payload(operation, enabled=human_review),
             },
         }
+        if record_id is not None:
+            response["record_id"] = record_id
+        if apply_id is not None:
+            response["apply_id"] = apply_id
         if output_profile == "verbose":
             debug: JSONObject = {
                 "legacy_result": raw_apply.get("result"),
@@ -10223,9 +10677,10 @@ class RecordTools(ToolBase):
         operation: str,
         profile: str,
         app_key: str,
-        record_id: int,
+        record_id: Any | None,
         output_profile: str,
         human_review: bool,
+        write_executed: bool = True,
     ) -> JSONObject:
         """执行内部辅助逻辑。"""
         error_payload: JSONObject = {
@@ -10266,11 +10721,14 @@ class RecordTools(ToolBase):
             "ws_id": None,
             "ok": False,
             "status": "failed",
+            "write_executed": write_executed,
+            "verification_status": "failed" if write_executed else "not_requested",
+            "safe_to_retry": not write_executed,
             "request_route": request_route,
             "warnings": [],
             "output_profile": output_profile,
             "data": {
-                "action": {"operation": operation, "executed": True},
+                "action": {"operation": operation, "executed": write_executed},
                 "resource": {"type": "record", "app_key": app_key, "record_id": record_id, "record_ids": []},
                 "verification": None,
                 "normalized_payload": None,
@@ -13658,11 +14116,15 @@ def _record_detail_associated_resource(raw: JSONObject) -> JSONObject:
     view_key = _normalize_optional_text(raw.get("viewKey", raw.get("viewgraphKey")))
     chart_key = _normalize_optional_text(raw.get("chartKey", raw.get("chartId")))
     is_view = bool(view_key) or graph_type.endswith("view") or graph_type == "view"
+    if is_view and not view_key and chart_key:
+        view_key = chart_key
+        chart_key = None
     resource_type = "view" if is_view else "report"
     view_type = _normalize_optional_text(raw.get("viewType", raw.get("viewgraphType", raw.get("graphType"))))
     data_access = _record_detail_resource_data_access(resource_type=resource_type, view_type=view_type)
     return {
         "type": resource_type,
+        "resource_type": resource_type,
         "name": _normalize_optional_text(raw.get("viewName", raw.get("chartName", raw.get("name", raw.get("title"))))),
         "app_key": _normalize_optional_text(raw.get("appKey", raw.get("targetAppKey"))),
         "app_name": _normalize_optional_text(raw.get("formTitle", raw.get("appName", raw.get("targetAppName")))),
@@ -13670,10 +14132,15 @@ def _record_detail_associated_resource(raw: JSONObject) -> JSONObject:
         "chart_key": chart_key,
         "view_type": view_type,
         "graph_type": raw.get("graphType"),
+        "report_source": _record_detail_report_source(raw.get("sourceType")) if resource_type == "report" else None,
         "data_access": data_access,
     }
 
 
+def _record_detail_report_source(source_type: Any) -> str:
+    return "dataset" if str(source_type or "").strip().upper() == "BI_DATASET" else "app"
+
+
 def _record_detail_resource_data_access(*, resource_type: str, view_type: str | None) -> JSONObject:
     if resource_type == "report":
         return {
@@ -18316,6 +18783,105 @@ def _write_format_for_field(field: FormField) -> JSONObject:
     return _write_support_payload(support_level="full", kind="scalar_text")
 
 
+def _ready_schema_format_hint(kind: str, write_format: JSONObject) -> str:
+    if kind == "member":
+        return "可直接填成员姓名；唯一匹配会自动解析，重名时会返回候选确认。也可传成员 id/value 对象。"
+    if kind == "department":
+        return "可直接填部门名称；唯一匹配会自动解析，重名时会返回候选确认。也可传部门 id/value 对象。"
+    if kind == "relation":
+        return "可传目标记录 apply_id/record_id 对象，也可填目标记录的可搜索文本；多候选时会返回确认。"
+    if kind == "attachment":
+        return "先调用 file_upload_local 上传文件，再写入上传返回的附件对象或 value/name。"
+    if kind == "subtable":
+        return "传 {'rows': [{...}]} 或直接传行对象数组；每行 key 使用子字段标题。"
+    if kind == "address":
+        return "传省/市/区/详细地址对象、地址明细字符串，或后端地址 parts 数组。"
+    if kind == "single_select":
+        return "传 options 中的一个选项文本。"
+    if kind == "multi_select":
+        return "传 options 中的多个选项文本数组。"
+    if kind == "boolean":
+        return "传 '是' 或 '否'。"
+    if kind == "date":
+        return "推荐传 'YYYY-MM-DD HH:MM:SS'；只有日期时可传 'YYYY-MM-DD'。"
+    if kind == "number":
+        return "传数字或数字字符串。"
+    if kind == "unsupported":
+        reason = _normalize_optional_text(write_format.get("reason"))
+        return reason or "该字段不支持直接写入。"
+    return "传文本值。"
+
+
+def _ready_schema_example_value(
+    kind: str,
+    field: FormField,
+    write_format: JSONObject,
+    *,
+    row_fields: list[JSONObject],
+) -> JSONValue:
+    if kind == "member":
+        return "张三"
+    if kind == "department":
+        return "直销部"
+    if kind == "relation":
+        return {"apply_id": "5001"}
+    if kind == "attachment":
+        return {"value": "<file_upload_local 返回的 value/url>", "name": "example.pdf"}
+    if kind == "subtable":
+        row: JSONObject = {}
+        for item in row_fields:
+            if not isinstance(item, dict):
+                continue
+            title = _normalize_optional_text(item.get("title"))
+            if not title:
+                continue
+            row[title] = item.get("example_value", _ready_schema_template_scalar(item.get("kind")))
+        if not row:
+            row = {"子字段": "值"}
+        return {"rows": [row]}
+    if kind == "address":
+        examples = write_format.get("examples")
+        if isinstance(examples, list) and examples:
+            return deepcopy(cast(JSONValue, examples[0]))
+        return {"province": "上海市", "city": "上海市", "district": "闵行区", "detail": "浦江路99号"}
+    if kind == "single_select":
+        return field.options[0] if field.options else "选项A"
+    if kind == "multi_select":
+        return [field.options[0]] if field.options else ["选项A"]
+    if kind == "boolean":
+        return "是"
+    if kind == "date":
+        return "2026-03-13 10:00:00"
+    if kind == "number":
+        return 100
+    if kind == "unsupported":
+        return None
+    return "示例文本"
+
+
+def _ready_schema_template_scalar(kind: Any) -> JSONValue:
+    normalized = _normalize_optional_text(kind)
+    if normalized == "number":
+        return 100
+    if normalized == "date":
+        return "2026-03-13 10:00:00"
+    if normalized == "boolean":
+        return "是"
+    if normalized == "member":
+        return "张三"
+    if normalized == "department":
+        return "直销部"
+    if normalized == "relation":
+        return {"apply_id": "5001"}
+    if normalized == "multi_select":
+        return ["选项A"]
+    if normalized == "attachment":
+        return {"value": "<file_upload_local 返回的 value/url>", "name": "example.pdf"}
+    if normalized == "address":
+        return {"province": "上海市", "city": "上海市", "district": "闵行区", "detail": "浦江路99号"}
+    return "值"
+
+
 def _summarize_write_support(resolved_fields: list[JSONObject]) -> JSONObject:
     summary: JSONObject = {
         "full": [],