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

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.5
+npm install @qingflow-tech/qingflow-app-builder-mcp@1.0.6
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.5 qingflow-app-builder-mcp
+npx -y -p @qingflow-tech/qingflow-app-builder-mcp@1.0.6 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-builder-mcp",
-  "version": "1.0.5",
+  "version": "1.0.6",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "1.0.5"
+version = "1.0.6"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/cli/commands/record.py

@@ -82,7 +82,8 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     insert = record_subparsers.add_parser("insert", help="新增记录")
     insert.add_argument("--app-key", required=True)
-    insert.add_argument("--fields-file", required=True)
+    insert.add_argument("--fields-file")
+    insert.add_argument("--items-file")
     insert.add_argument("--verify-write", action=argparse.BooleanOptionalAction, default=True)
     insert.set_defaults(handler=_handle_insert, format_hint="")
 
@@ -274,6 +275,23 @@ def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_insert(args: argparse.Namespace, context: CliContext) -> dict:
+    if args.items_file:
+        if args.fields_file:
+            raise_config_error(
+                "record insert batch mode does not accept --fields-file.",
+                fix_hint="Use `record insert --app-key APP_KEY --items-file ITEMS.json` for batch inserts.",
+            )
+        return context.record.record_insert_public(
+            profile=args.profile,
+            app_key=args.app_key,
+            items=require_list_arg(args.items_file, option_name="--items-file"),
+            verify_write=bool(args.verify_write),
+        )
+    if not args.fields_file:
+        raise_config_error(
+            "record insert requires --items-file or --fields-file.",
+            fix_hint="Prefer `record insert --app-key APP_KEY --items-file ITEMS.json`; use --fields-file only for legacy single inserts.",
+        )
     return context.record.record_insert_public(
         profile=args.profile,
         app_key=args.app_key,

package/src/qingflow_mcp/response_trim.py

@@ -57,6 +57,13 @@ def trim_public_response(tool_name: str | None, payload: dict[str, Any]) -> dict
     if not isinstance(payload, dict):
         return payload
     if _looks_like_failure_payload(payload):
+        status = str(payload.get("status") or "").lower()
+        if tool_name in {"user:record_insert", "user:record_update"} and status in {
+            "blocked",
+            "needs_confirmation",
+            "partial_success",
+        }:
+            return trim_success_response(tool_name, payload)
         return _trim_returned_failure(payload)
     return trim_success_response(tool_name, payload)
 
@@ -140,7 +147,7 @@ def _looks_like_failure_payload(payload: dict[str, Any]) -> bool:
     if payload.get("ok") is False:
         return True
     status = str(payload.get("status") or "").lower()
-    return status in {"failed", "blocked", "verification_failed"}
+    return status in {"failed", "blocked"}
 
 
 def _trim_returned_failure(payload: dict[str, Any]) -> dict[str, Any]:
@@ -368,6 +375,9 @@ def _trim_record_write(payload: JSONObject) -> None:
     data = payload.get("data")
     if not isinstance(data, dict):
         return
+    if payload.get("mode") == "batch" or data.get("mode") == "batch":
+        _trim_record_write_batch(payload, data)
+        return
     data.pop("debug", None)
     data.pop("normalized_payload", None)
     data.pop("human_review", None)
@@ -397,6 +407,44 @@ def _trim_record_write(payload: JSONObject) -> None:
             data.pop(key, None)
 
 
+def _trim_record_write_batch(payload: JSONObject, data: JSONObject) -> None:
+    data.pop("items", None)
+    data.pop("debug", None)
+    for key in ("summary", "created_record_ids", "app_key", "mode"):
+        if data.get(key) in (None, [], {}, ""):
+            data.pop(key, None)
+    items = payload.get("items")
+    if isinstance(items, list):
+        payload["items"] = [
+            _pick(
+                item,
+                (
+                    "index",
+                    "row_number",
+                    "status",
+                    "record_id",
+                    "apply_id",
+                    "write_executed",
+                    "verification_status",
+                    "safe_to_retry",
+                    "failed_fields",
+                    "confirmation_requests",
+                    "blockers",
+                    "error",
+                    "warnings",
+                    "resource",
+                    "verification",
+                ),
+            )
+            for item in items
+            if isinstance(item, dict)
+        ]
+    for key in ("items", "created_record_ids"):
+        value = payload.get(key)
+        if value in (None, [], {}, ""):
+            payload.pop(key, None)
+
+
 def _trim_record_get(payload: JSONObject) -> None:
     if payload.get("fields") is not None or payload.get("semantic_context") is not None:
         _trim_detail_context_record_get(payload)
@@ -730,6 +778,19 @@ def _compact_schema_field(item: Any, *, template_map: dict[str, Any] | None) ->
         compact["required"] = bool(item.get("required"))
     if template_map is not None and isinstance(title, str) and title in template_map:
         compact["template"] = template_map.get(title)
+    for key in (
+        "format_hint",
+        "example_value",
+        "linkage",
+        "may_become_required",
+        "activation_sources",
+        "requirement_reason",
+        "accepts_natural_input",
+        "requires_upload",
+    ):
+        value = item.get(key)
+        if value not in (None, [], {}, ""):
+            compact[key] = value
     candidate_hint = item.get("candidate_hint")
     if isinstance(candidate_hint, dict):
         compact["candidate_hint"] = candidate_hint

package/src/qingflow_mcp/server.py

@@ -104,7 +104,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 ## Record CRUD Path
 
 `app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get`
-`record_insert_schema_get -> record_insert`
+`record_insert_schema_get -> record_insert(items)`
 `record_update_schema_get -> record_update`
 `record_list / record_get -> record_delete`
 `record_code_block_schema_get -> record_code_block_run`
@@ -115,7 +115,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - Use `order_by` items as `{{field_id, direction}}`
 - Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
 
-- `record_insert` uses an applicant-node `fields` map keyed by field title.
+- `record_insert` defaults to an applicant-node `items` array; each item contains a field-title keyed `fields` map. A single insert is one item.
 - `record_update` uses a field-title keyed `fields` map and internally selects the first accessible view that can execute the current payload.
 - For insert, `runtime_linked_required_fields` means required-but-not-directly-writable fields that are usually supplied by runtime linkage or upstream context.
 - For insert, fields marked `may_become_required=true` stay in `optional_fields`; they are still directly writable, but linked visibility or option-driven rules can make them required at runtime.
@@ -130,7 +130,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
 
 - Read relation targets from `record_insert_schema_get` / `record_update_schema_get` relation metadata before preparing relation writes.
-- Member and department fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to `record_member_candidates` or `record_department_candidates` when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- Member, department, and relation fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to candidate tools when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- For batch insert `partial_success`, read `created_record_ids`, failed `items[].row_number`, and `failed_fields`; repair only failed rows and never retry the whole batch after any row has `write_executed=true`.
 - If explicit candidate browsing is needed for default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
 ## Code Block Path

package/src/qingflow_mcp/server_app_user.py

@@ -103,7 +103,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 ## Record CRUD Path
 
 `app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get`
-`record_insert_schema_get -> record_insert`
+`record_insert_schema_get -> record_insert(items)`
 `record_update_schema_get -> record_update`
 `record_list / record_get -> record_delete`
 `record_code_block_schema_get -> record_code_block_run`
@@ -116,7 +116,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - Use `order_by` items as `{{field_id, direction}}`
 - Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
 
-- `record_insert` uses an applicant-node `fields` map keyed by field title.
+- `record_insert` defaults to an applicant-node `items` array; each item contains a field-title keyed `fields` map. A single insert is one item.
 - `record_update` uses a field-title keyed `fields` map and internally selects the first accessible view that can execute the current payload.
 - For insert, `runtime_linked_required_fields` means required-but-not-directly-writable fields that are usually supplied by runtime linkage or upstream context.
 - For insert, fields marked `may_become_required=true` stay in `optional_fields`; they are still directly writable, but linked visibility or option-driven rules can make them required at runtime.
@@ -131,7 +131,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
 
 - Read relation targets from `record_insert_schema_get` / `record_update_schema_get` relation metadata before preparing relation writes.
-- Member and department fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to `record_member_candidates` or `record_department_candidates` when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- Member, department, and relation fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to candidate tools when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- For batch insert `partial_success`, read `created_record_ids`, failed `items[].row_number`, and `failed_fields`; repair only failed rows and never retry the whole batch after any row has `write_executed=true`.
 - When candidate browsing must match a real update/write scope, pass `record_id`, `workflow_node_id`, and any pending `fields` context to the candidate tool; otherwise the candidate result is only a static applicant-node preview.
 - If explicit candidate browsing is needed for default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 

package/src/qingflow_mcp/tools/record_tools.py

@@ -470,21 +470,24 @@ 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 {},
+                fields=fields,
+                items=items,
                 verify_write=verify_write,
                 output_profile=output_profile,
             )
@@ -1064,11 +1067,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 +3003,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,69 +3011,478 @@ 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(
         self,
@@ -7357,7 +7775,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 +7979,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 +10518,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 +10564,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 +10609,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 +10657,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 +10679,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 +10723,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,
@@ -18316,6 +18776,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": [],