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

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

@@ -123,30 +123,22 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     button_catalog = button_subparsers.add_parser("catalog", help="读取按钮样式目录")
     button_catalog.set_defaults(handler=_handle_button_catalog, format_hint="builder_summary")
 
-    button_list = button_subparsers.add_parser("list", help="列出自定义按钮")
-    button_list.add_argument("--app-key", required=True)
-    button_list.set_defaults(handler=_handle_button_list, format_hint="builder_summary")
-
-    button_get = button_subparsers.add_parser("get", help="读取自定义按钮")
-    button_get.add_argument("--app-key", required=True)
-    button_get.add_argument("--button-id", type=int, required=True)
-    button_get.set_defaults(handler=_handle_button_get, format_hint="builder_summary")
-
-    button_create = button_subparsers.add_parser("create", help="创建自定义按钮")
-    button_create.add_argument("--app-key", required=True)
-    button_create.add_argument("--payload-file", required=True)
-    button_create.set_defaults(handler=_handle_button_create, format_hint="builder_summary")
-
-    button_update = button_subparsers.add_parser("update", help="更新自定义按钮")
-    button_update.add_argument("--app-key", required=True)
-    button_update.add_argument("--button-id", type=int, required=True)
-    button_update.add_argument("--payload-file", required=True)
-    button_update.set_defaults(handler=_handle_button_update, format_hint="builder_summary")
-
-    button_delete = button_subparsers.add_parser("delete", help="删除自定义按钮")
-    button_delete.add_argument("--app-key", required=True)
-    button_delete.add_argument("--button-id", type=int, required=True)
-    button_delete.set_defaults(handler=_handle_button_delete, format_hint="builder_summary")
+    button_apply = button_subparsers.add_parser("apply", help="声明式创建、更新或删除自定义按钮")
+    button_apply.add_argument("--app-key", required=True)
+    button_apply.add_argument("--upsert-buttons-file")
+    button_apply.add_argument("--remove-buttons-file")
+    button_apply.add_argument("--view-configs-file")
+    button_apply.set_defaults(handler=_handle_button_apply, format_hint="builder_summary")
+
+    associated_resource = builder_subparsers.add_parser("associated-resource", aliases=["associated-resources"], help="关联视图/报表")
+    associated_resource_subparsers = associated_resource.add_subparsers(dest="builder_associated_resource_command", required=True)
+    associated_resource_apply = associated_resource_subparsers.add_parser("apply", help="声明式管理应用关联资源池和视图展示配置")
+    associated_resource_apply.add_argument("--app-key", required=True)
+    associated_resource_apply.add_argument("--upsert-resources-file")
+    associated_resource_apply.add_argument("--remove-associated-item-ids-file")
+    associated_resource_apply.add_argument("--reorder-associated-item-ids-file")
+    associated_resource_apply.add_argument("--view-configs-file")
+    associated_resource_apply.set_defaults(handler=_handle_associated_resource_apply, format_hint="builder_summary")
 
     portal = builder_subparsers.add_parser("portal", help="门户")
     portal_subparsers = portal.add_subparsers(dest="builder_portal_command", required=True)
@@ -185,8 +177,8 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     schema_apply_apply.add_argument("--visibility-file")
     schema_apply_apply.add_argument("--create-if-missing", action="store_true")
     schema_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
-    schema_apply_apply.add_argument("--add-fields-file")
-    schema_apply_apply.add_argument("--update-fields-file")
+    schema_apply_apply.add_argument("--add-fields-file", help="字段 JSON 数组；字段可用 as_data_title/as_data_cover 标记数据标题/封面")
+    schema_apply_apply.add_argument("--update-fields-file", help="字段更新 JSON 数组；set 内可用 as_data_title/as_data_cover 标记数据标题/封面")
     schema_apply_apply.add_argument("--remove-fields-file")
     schema_apply_apply.set_defaults(handler=_handle_schema_apply, format_hint="builder_summary")
 
@@ -369,6 +361,27 @@ def _handle_button_catalog(args: argparse.Namespace, context: CliContext) -> dic
     return context.builder.button_style_catalog_get(profile=args.profile)
 
 
+def _handle_button_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_custom_buttons_apply(
+        profile=args.profile,
+        app_key=args.app_key,
+        upsert_buttons=load_list_arg(args.upsert_buttons_file, option_name="--upsert-buttons-file"),
+        remove_buttons=load_list_arg(args.remove_buttons_file, option_name="--remove-buttons-file"),
+        view_configs=load_list_arg(args.view_configs_file, option_name="--view-configs-file"),
+    )
+
+
+def _handle_associated_resource_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_associated_resources_apply(
+        profile=args.profile,
+        app_key=args.app_key,
+        upsert_resources=load_list_arg(args.upsert_resources_file, option_name="--upsert-resources-file"),
+        remove_associated_item_ids=load_list_arg(args.remove_associated_item_ids_file, option_name="--remove-associated-item-ids-file"),
+        reorder_associated_item_ids=load_list_arg(args.reorder_associated_item_ids_file, option_name="--reorder-associated-item-ids-file"),
+        view_configs=load_list_arg(args.view_configs_file, option_name="--view-configs-file"),
+    )
+
+
 def _handle_button_get(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_custom_button_get(profile=args.profile, app_key=args.app_key, button_id=args.button_id)
 

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", help=argparse.SUPPRESS)
+    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.",
+            fix_hint="Use `record insert --app-key APP_KEY --items-file ITEMS.json`; a single insert is one item in the JSON array.",
+        )
     return context.record.record_insert_public(
         profile=args.profile,
         app_key=args.app_key,

package/src/qingflow_mcp/public_surface.py

@@ -136,11 +136,8 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(BUILDER_DOMAIN, "app_release_edit_lock_if_mine", ("app_release_edit_lock_if_mine",), ("builder", "app", "release-edit-lock-if-mine"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_resolve", ("app_resolve",), ("builder", "app", "resolve"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "button_style_catalog_get", ("button_style_catalog_get",), ("builder", "button", "catalog"), has_contract=True, cli_show_effective_context=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_list", ("app_custom_button_list",), ("builder", "button", "list"), has_contract=True, cli_show_effective_context=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_get", ("app_custom_button_get",), ("builder", "button", "get"), has_contract=True, cli_show_effective_context=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_create", ("app_custom_button_create",), ("builder", "button", "create"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_update", ("app_custom_button_update",), ("builder", "button", "update"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_custom_button_delete", ("app_custom_button_delete",), ("builder", "button", "delete"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_custom_buttons_apply", ("app_custom_buttons_apply",), ("builder", "button", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_associated_resources_apply", ("app_associated_resources_apply",), ("builder", "associated-resource", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_get", ("app_get",), ("builder", "app", "get", "summary"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_get_fields", ("app_get_fields",), ("builder", "app", "get", "fields"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_repair_code_blocks", ("app_repair_code_blocks",), ("builder", "app", "repair-code-blocks"), has_contract=True, cli_show_effective_context=True),

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)
@@ -538,7 +586,7 @@ def _trim_detail_context_record_get(payload: JSONObject) -> None:
     associated_resources = payload.get("associated_resources")
     if isinstance(associated_resources, list):
         payload["associated_resources"] = [
-            _pick(item, ("type", "name", "app_key", "app_name", "view_key", "chart_key", "view_type", "data_access"))
+            _pick(item, ("type", "resource_type", "name", "app_key", "app_name", "view_key", "chart_key", "view_type", "report_source", "data_access"))
             for item in associated_resources
             if isinstance(item, dict)
         ]
@@ -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
@@ -996,11 +1057,8 @@ _register_policy(
         "app_release_edit_lock_if_mine",
         "app_resolve",
         "button_style_catalog_get",
-        "app_custom_button_list",
-        "app_custom_button_get",
-        "app_custom_button_create",
-        "app_custom_button_update",
-        "app_custom_button_delete",
+        "app_custom_buttons_apply",
+        "app_associated_resources_apply",
         "app_get_fields",
         "app_repair_code_blocks",
         "app_get_layout",

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_builder.py

@@ -36,9 +36,13 @@ def build_builder_server() -> FastMCP:
             "Use builder_tool_contract when you need a machine-readable contract, aliases, allowed enums, or a minimal valid example for a public builder tool. "
             "Use solution_install when the user explicitly wants to install a packaged solution/template by solution_key, optionally copying bundled demo data. "
             "If creating or updating an app package may be appropriate, use package_apply with explicit user intent; otherwise use package_get and app_resolve to locate resources, "
-            "app_get/app_get_fields/app_repair_code_blocks/app_get_layout/app_get_views/app_get_flow/app_get_charts/portal_list/portal_get/view_get/chart_get for configuration reads, "
+            "app_get as the default app map read, then app_get_fields/app_repair_code_blocks/app_get_layout/app_get_views/app_get_flow/app_get_charts/portal_list/portal_get/view_get/chart_get for focused configuration reads, "
             "member_search/role_search/role_create when workflow assignees must come from the directory or role catalog, preferring roles over explicit members unless the user explicitly names members, "
-            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, publish=false only guarantees draft/base-info updates, and flow should use publish=false whenever you only want draft/precheck behavior. "
+            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_custom_buttons_apply/app_associated_resources_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, app_custom_buttons_apply and app_associated_resources_apply publish after at least one write succeeds and expose no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use publish=false whenever you only want draft/precheck behavior. "
+            "For app_schema_apply, configure data title and data cover directly in field JSON with as_data_title=true and as_data_cover=true; data title is required and exactly one field may be marked, while data cover is optional and must be a top-level attachment field. "
+            "For app_views_apply, keep fixed saved filters in filters and configure the frontend query panel separately with query_conditions; query_conditions.rows is a matrix of field names compiled to backend queryCondition queIds. "
+            "For custom button body create/update/delete and view placement, use app_custom_buttons_apply. For addData buttons, prefer trigger_add_data_config.target_app_key + field_mappings/default_values; do not ask agents to write raw que_relation unless maintaining a legacy config. View button bindings merge by default and merge-mode view_configs must include buttons; use view_configs[].mode=replace or explicit buttons=[] only when clearing/replacing existing bindings is intended. "
+            "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, not chart_id/chart_key. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "
             "For code_block fields with output bindings, always use qf_output assignment rather than const/let qf_output, and use app_repair_code_blocks when an existing form hangs because output-bound fields stay loading. "
             "Use package_apply to manage package metadata, visibility, grouping, and ordering, and app_publish_verify for explicit final publish verification. "
             "For workflow edits, keep the public builder surface on stable linear flows only: start/approve/fill/copy/webhook/end. Branch and condition nodes are intentionally disabled because the backend workflow route is not front-end stable for those node types. Declare node assignees and editable fields explicitly. "
@@ -295,29 +299,38 @@ def build_builder_server() -> FastMCP:
         return ai_builder.button_style_catalog_get(profile=profile)
 
     @server.tool()
-    def app_custom_button_list(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
-        return ai_builder.app_custom_button_list(profile=profile, app_key=app_key)
-
-    @server.tool()
-    def app_custom_button_get(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> dict:
-        return ai_builder.app_custom_button_get(profile=profile, app_key=app_key, button_id=button_id)
-
-    @server.tool()
-    def app_custom_button_create(profile: str = DEFAULT_PROFILE, app_key: str = "", payload: dict | None = None) -> dict:
-        return ai_builder.app_custom_button_create(profile=profile, app_key=app_key, payload=payload or {})
-
-    @server.tool()
-    def app_custom_button_update(
+    def app_custom_buttons_apply(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
-        button_id: int = 0,
-        payload: dict | None = None,
+        upsert_buttons: list[dict] | None = None,
+        remove_buttons: list[dict] | None = None,
+        view_configs: list[dict] | None = None,
     ) -> dict:
-        return ai_builder.app_custom_button_update(profile=profile, app_key=app_key, button_id=button_id, payload=payload or {})
+        return ai_builder.app_custom_buttons_apply(
+            profile=profile,
+            app_key=app_key,
+            upsert_buttons=upsert_buttons or [],
+            remove_buttons=remove_buttons or [],
+            view_configs=view_configs or [],
+        )
 
     @server.tool()
-    def app_custom_button_delete(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> dict:
-        return ai_builder.app_custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+    def app_associated_resources_apply(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        upsert_resources: list[dict] | None = None,
+        remove_associated_item_ids: list[int] | None = None,
+        reorder_associated_item_ids: list[int] | None = None,
+        view_configs: list[dict] | None = None,
+    ) -> dict:
+        return ai_builder.app_associated_resources_apply(
+            profile=profile,
+            app_key=app_key,
+            upsert_resources=upsert_resources or [],
+            remove_associated_item_ids=remove_associated_item_ids or [],
+            reorder_associated_item_ids=reorder_associated_item_ids or [],
+            view_configs=view_configs or [],
+        )
 
     @server.tool()
     def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:

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_*`.