@qingflow-tech/qingflow-app-user-mcp 1.0.9 → 1.0.10

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

@@ -84,7 +84,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     package_apply = package_subparsers.add_parser("apply", help="创建或更新应用包配置")
     package_apply.add_argument("--config-file", required=True)
-    package_apply.set_defaults(handler=_handle_package_apply, format_hint="builder_summary")
+    package_apply.set_defaults(handler=_handle_package_apply, format_hint="builder_summary", force_json_output=True)
 
     app = builder_subparsers.add_parser("app", help="应用")
     app_subparsers = app.add_subparsers(dest="builder_app_command", required=True)
@@ -99,7 +99,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     app_release_lock.add_argument("--app-key", required=True)
     app_release_lock.add_argument("--lock-owner-email", required=True)
     app_release_lock.add_argument("--lock-owner-name", required=True)
-    app_release_lock.set_defaults(handler=_handle_app_release_edit_lock_if_mine, format_hint="builder_summary")
+    app_release_lock.set_defaults(handler=_handle_app_release_edit_lock_if_mine, format_hint="builder_summary", force_json_output=True)
 
     app_get = app_subparsers.add_parser("get", help="读取应用配置（字段请使用: builder app get --app-key APP fields）")
     app_get.add_argument(
@@ -129,7 +129,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     button_apply.add_argument("--patch-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")
+    button_apply.set_defaults(handler=_handle_button_apply, format_hint="builder_summary", force_json_output=True)
 
     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)
@@ -140,7 +140,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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")
+    associated_resource_apply.set_defaults(handler=_handle_associated_resource_apply, format_hint="builder_summary", force_json_output=True)
 
     portal = builder_subparsers.add_parser("portal", help="门户")
     portal_subparsers = portal.add_subparsers(dest="builder_portal_command", required=True)
@@ -165,7 +165,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     portal_apply.add_argument("--hide-copyright", action=argparse.BooleanOptionalAction, default=None)
     portal_apply.add_argument("--dash-global-config-file")
     portal_apply.add_argument("--config-file")
-    portal_apply.set_defaults(handler=_handle_portal_apply, format_hint="builder_summary")
+    portal_apply.set_defaults(handler=_handle_portal_apply, format_hint="builder_summary", force_json_output=True)
 
     schema_apply = builder_subparsers.add_parser("schema", help="字段搭建")
     schema_apply_subparsers = schema_apply.add_subparsers(dest="builder_schema_command", required=True)
@@ -179,10 +179,11 @@ 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("--apps-file", help="多应用 schema JSON 数组；每项可带 client_key/app_name/add_fields，支持 relation target_app_ref")
     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")
+    schema_apply_apply.set_defaults(handler=_handle_schema_apply, format_hint="builder_summary", force_json_output=True)
 
     layout_apply = builder_subparsers.add_parser("layout", help="布局")
     layout_apply_subparsers = layout_apply.add_subparsers(dest="builder_layout_command", required=True)
@@ -191,7 +192,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     layout_apply_apply.add_argument("--mode", choices=["merge", "replace"], default="merge")
     layout_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
     layout_apply_apply.add_argument("--sections-file", required=True)
-    layout_apply_apply.set_defaults(handler=_handle_layout_apply, format_hint="builder_summary")
+    layout_apply_apply.set_defaults(handler=_handle_layout_apply, format_hint="builder_summary", force_json_output=True)
 
     views_apply = builder_subparsers.add_parser("views", help="视图")
     views_apply_subparsers = views_apply.add_subparsers(dest="builder_views_command", required=True)
@@ -201,7 +202,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     views_apply_apply.add_argument("--upsert-views-file")
     views_apply_apply.add_argument("--patch-views-file")
     views_apply_apply.add_argument("--remove-views-file")
-    views_apply_apply.set_defaults(handler=_handle_views_apply, format_hint="builder_summary")
+    views_apply_apply.set_defaults(handler=_handle_views_apply, format_hint="builder_summary", force_json_output=True)
 
     flow_apply = builder_subparsers.add_parser("flow", help="流程")
     flow_apply_subparsers = flow_apply.add_subparsers(dest="builder_flow_command", required=True)
@@ -211,7 +212,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     flow_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
     flow_apply_apply.add_argument("--nodes-file", required=True)
     flow_apply_apply.add_argument("--transitions-file", required=True)
-    flow_apply_apply.set_defaults(handler=_handle_flow_apply, format_hint="builder_summary")
+    flow_apply_apply.set_defaults(handler=_handle_flow_apply, format_hint="builder_summary", force_json_output=True)
 
     charts_apply = builder_subparsers.add_parser("charts", help="报表")
     charts_apply_subparsers = charts_apply.add_subparsers(dest="builder_charts_command", required=True)
@@ -221,14 +222,14 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     charts_apply_apply.add_argument("--patch-file")
     charts_apply_apply.add_argument("--remove-chart-ids-file")
     charts_apply_apply.add_argument("--reorder-chart-ids-file")
-    charts_apply_apply.set_defaults(handler=_handle_charts_apply, format_hint="builder_summary")
+    charts_apply_apply.set_defaults(handler=_handle_charts_apply, format_hint="builder_summary", force_json_output=True)
 
     publish_verify = builder_subparsers.add_parser("publish", help="发布校验")
     publish_verify_subparsers = publish_verify.add_subparsers(dest="builder_publish_command", required=True)
     publish_verify_verify = publish_verify_subparsers.add_parser("verify", help="校验应用发布")
     publish_verify_verify.add_argument("--app-key", required=True)
     publish_verify_verify.add_argument("--expected-package-id", type=int)
-    publish_verify_verify.set_defaults(handler=_handle_publish_verify, format_hint="builder_summary")
+    publish_verify_verify.set_defaults(handler=_handle_publish_verify, format_hint="builder_summary", force_json_output=True)
 
     view = builder_subparsers.add_parser("view", help="视图详情")
     view_subparsers = view.add_subparsers(dest="builder_view_command", required=True)
@@ -451,6 +452,34 @@ def _handle_chart_get(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    apps = load_list_arg(args.apps_file, option_name="--apps-file")
+    if args.apps_file:
+        if not apps:
+            raise_config_error(
+                "schema apply multi-app mode requires a non-empty --apps-file.",
+                fix_hint="Pass a JSON array with at least one app item.",
+            )
+        if args.app_key or args.app_name or args.app_title or args.add_fields_file or args.update_fields_file or args.remove_fields_file:
+            raise_config_error(
+                "schema apply multi-app mode accepts --package-id/--create-if-missing plus --apps-file only.",
+                fix_hint="Use `--apps-file` for batch mode, or remove `--apps-file` and use the single-app arguments.",
+            )
+        if args.package_id is None:
+            raise_config_error(
+                "schema apply multi-app mode requires --package-id.",
+                fix_hint="Pass `--package-id` and app names inside --apps-file.",
+            )
+        return context.builder.app_schema_apply(
+            profile=args.profile,
+            package_id=args.package_id,
+            visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
+            create_if_missing=bool(args.create_if_missing),
+            publish=bool(args.publish),
+            apps=apps,
+            add_fields=[],
+            update_fields=[],
+            remove_fields=[],
+        )
     has_app_key = bool((args.app_key or "").strip())
     has_app_name = bool((args.app_name or "").strip())
     has_app_title = bool((args.app_title or "").strip())

package/src/qingflow_mcp/cli/main.py

@@ -8,6 +8,7 @@ from typing import Any, Callable, TextIO
 from ..errors import QingflowApiError
 from ..public_surface import cli_public_tool_spec_from_namespace
 from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
+from ..tools.ai_builder_tools import _attach_builder_apply_envelope
 from .context import CliContext, build_cli_context
 from .formatters import emit_json_result, emit_text_result
 from .commands import register_all_commands
@@ -16,8 +17,21 @@ from .commands import register_all_commands
 Handler = Callable[[argparse.Namespace, CliContext], dict[str, Any]]
 
 
+class _CliArgumentError(Exception):
+    def __init__(self, *, prog: str, message: str, usage: str) -> None:
+        super().__init__(message)
+        self.prog = prog
+        self.message = message
+        self.usage = usage
+
+
+class _QingflowArgumentParser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        raise _CliArgumentError(prog=self.prog, message=message, usage=self.format_usage())
+
+
 def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="qingflow", description="Qingflow CLI")
+    parser = _QingflowArgumentParser(prog="qingflow", description="Qingflow CLI")
     parser.add_argument("--profile", default="default", help="会话 profile，默认 default")
     parser.add_argument("--json", action="store_true", help="输出 JSON")
     subparsers = parser.add_subparsers(dest="command", required=True)
@@ -42,6 +56,21 @@ def run(
     normalized_argv = _normalize_global_args(list(argv) if argv is not None else sys.argv[1:])
     try:
         args = parser.parse_args(normalized_argv)
+    except _CliArgumentError as exc:
+        if _should_force_json_output_argv(normalized_argv):
+            payload = {
+                "category": "config",
+                "status": "failed",
+                "error_code": "ARGUMENT_ERROR",
+                "message": exc.message,
+                "details": {"usage": exc.usage.strip(), "prog": exc.prog},
+            }
+            payload = _maybe_attach_builder_apply_error_envelope_from_argv(normalized_argv, payload)
+            emit_json_result(payload, stream=out)
+            return 2
+        err.write(exc.usage)
+        err.write(f"{exc.prog}: error: {exc.message}\n")
+        return 2
     except SystemExit as exc:
         return int(exc.code or 0)
     setattr(args, "_stdin", sys.stdin)
@@ -51,8 +80,10 @@ def run(
     if handler is None:
         parser.print_help(out)
         return 2
-    context = context_factory()
     try:
+        if _should_force_json_output(args):
+            setattr(args, "json", True)
+        context = context_factory()
         if not bool(args.json):
             _emit_cli_effective_context_notice(args, context, stream=err)
         result = handler(args, context)
@@ -60,12 +91,15 @@ def run(
         return int(exc.code or 0)
     except RuntimeError as exc:
         payload = trim_error_response(_parse_error_payload(exc))
+        payload = _maybe_attach_builder_apply_error_envelope_from_args(args, payload)
         return _emit_error(payload, json_mode=bool(args.json), stdout=out, stderr=err)
     except QingflowApiError as exc:
         payload = trim_error_response(exc.to_dict())
+        payload = _maybe_attach_builder_apply_error_envelope_from_args(args, payload)
         return _emit_error(payload, json_mode=bool(args.json), stdout=out, stderr=err)
     finally:
-        context.close()
+        if "context" in locals():
+            context.close()
 
     exit_code = _result_exit_code(result)
     trimmed_result = trim_public_response(resolve_cli_tool_name(args), result) if isinstance(result, dict) else result
@@ -104,6 +138,173 @@ def _normalize_global_args(argv: list[str]) -> list[str]:
     return global_args + remaining
 
 
+def _should_force_json_output(args: argparse.Namespace) -> bool:
+    if bool(getattr(args, "force_json_output", False)):
+        return True
+    if (
+        getattr(args, "command", "") == "builder"
+        and getattr(args, "builder_app_command", "") == "repair-code-blocks"
+        and bool(getattr(args, "apply", False))
+    ):
+        return True
+    return False
+
+
+def _should_force_json_output_argv(argv: list[str]) -> bool:
+    tokens = _strip_global_args(argv)
+    if not tokens or tokens[0] not in {"builder", "build"}:
+        return False
+    if len(tokens) < 3:
+        return False
+    section = tokens[1]
+    action = tokens[2]
+    if section in {"package", "button", "associated-resource", "associated-resources", "portal", "schema", "layout", "views", "flow", "charts"}:
+        return action == "apply"
+    if section == "publish":
+        return action == "verify"
+    if section == "app":
+        if action == "release-edit-lock-if-mine":
+            return True
+        if action == "repair-code-blocks":
+            return "--apply" in tokens
+    return False
+
+
+def _maybe_attach_builder_apply_error_envelope_from_args(args: argparse.Namespace, payload: dict[str, Any]) -> dict[str, Any]:
+    operation = _builder_apply_operation_from_args(args)
+    if not operation:
+        return payload
+    enriched = dict(payload)
+    enriched.setdefault("status", "failed")
+    enriched.setdefault("ok", False)
+    enriched.setdefault("write_executed", False)
+    enriched.setdefault("safe_to_retry", False)
+    _copy_arg_identity(enriched, args)
+    return _attach_builder_apply_envelope(operation, enriched)
+
+
+def _maybe_attach_builder_apply_error_envelope_from_argv(argv: list[str], payload: dict[str, Any]) -> dict[str, Any]:
+    operation = _builder_apply_operation_from_argv(argv)
+    if not operation:
+        return payload
+    enriched = dict(payload)
+    enriched.setdefault("status", "failed")
+    enriched.setdefault("ok", False)
+    enriched.setdefault("write_executed", False)
+    enriched.setdefault("safe_to_retry", False)
+    _copy_argv_identity(enriched, argv)
+    return _attach_builder_apply_envelope(operation, enriched)
+
+
+def _builder_apply_operation_from_args(args: argparse.Namespace) -> str | None:
+    if getattr(args, "command", "") not in {"builder", "build"}:
+        return None
+    section = str(getattr(args, "builder_command", "") or "")
+    if section == "package" and getattr(args, "builder_package_command", "") == "apply":
+        return "package_apply"
+    if section == "button" and getattr(args, "builder_button_command", "") == "apply":
+        return "app_custom_buttons_apply"
+    if section in {"associated-resource", "associated-resources"} and getattr(args, "builder_associated_resource_command", "") == "apply":
+        return "app_associated_resources_apply"
+    if section == "portal" and getattr(args, "builder_portal_command", "") == "apply":
+        return "portal_apply"
+    if section == "schema" and getattr(args, "builder_schema_command", "") == "apply":
+        return "app_schema_apply"
+    if section == "layout" and getattr(args, "builder_layout_command", "") == "apply":
+        return "app_layout_apply"
+    if section == "views" and getattr(args, "builder_views_command", "") == "apply":
+        return "app_views_apply"
+    if section == "flow" and getattr(args, "builder_flow_command", "") == "apply":
+        return "app_flow_apply"
+    if section == "charts" and getattr(args, "builder_charts_command", "") == "apply":
+        return "app_charts_apply"
+    if section == "publish" and getattr(args, "builder_publish_command", "") == "verify":
+        return "app_publish_verify"
+    return None
+
+
+def _builder_apply_operation_from_argv(argv: list[str]) -> str | None:
+    tokens = _strip_global_args(argv)
+    if not tokens or tokens[0] not in {"builder", "build"} or len(tokens) < 3:
+        return None
+    section = tokens[1]
+    action = tokens[2]
+    if action != "apply" and not (section == "publish" and action == "verify"):
+        return None
+    mapping = {
+        "package": "package_apply",
+        "button": "app_custom_buttons_apply",
+        "associated-resource": "app_associated_resources_apply",
+        "associated-resources": "app_associated_resources_apply",
+        "portal": "portal_apply",
+        "schema": "app_schema_apply",
+        "layout": "app_layout_apply",
+        "views": "app_views_apply",
+        "flow": "app_flow_apply",
+        "charts": "app_charts_apply",
+        "publish": "app_publish_verify",
+    }
+    return mapping.get(section)
+
+
+def _copy_arg_identity(payload: dict[str, Any], args: argparse.Namespace) -> None:
+    for attr, key in (
+        ("app_key", "app_key"),
+        ("app_name", "app_name"),
+        ("app_title", "app_title"),
+        ("package_id", "package_id"),
+        ("dash_key", "dash_key"),
+        ("dash_name", "dash_name"),
+    ):
+        value = getattr(args, attr, None)
+        if value not in (None, ""):
+            payload.setdefault(key, value)
+
+
+def _copy_argv_identity(payload: dict[str, Any], argv: list[str]) -> None:
+    tokens = _strip_global_args(argv)
+    option_to_key = {
+        "--app-key": "app_key",
+        "--app-name": "app_name",
+        "--app-title": "app_title",
+        "--package-id": "package_id",
+        "--dash-key": "dash_key",
+        "--dash-name": "dash_name",
+    }
+    index = 0
+    while index < len(tokens):
+        token = tokens[index]
+        if token in option_to_key and index + 1 < len(tokens):
+            payload.setdefault(option_to_key[token], tokens[index + 1])
+            index += 2
+            continue
+        for option, key in option_to_key.items():
+            prefix = f"{option}="
+            if token.startswith(prefix):
+                payload.setdefault(key, token[len(prefix) :])
+                break
+        index += 1
+
+
+def _strip_global_args(argv: list[str]) -> list[str]:
+    stripped: list[str] = []
+    index = 0
+    while index < len(argv):
+        token = argv[index]
+        if token == "--json":
+            index += 1
+            continue
+        if token == "--profile":
+            index += 2
+            continue
+        if token.startswith("--profile="):
+            index += 1
+            continue
+        stripped.append(token)
+        index += 1
+    return stripped
+
+
 def _parse_error_payload(exc: RuntimeError) -> dict[str, Any]:
     raw = str(exc)
     try:

package/src/qingflow_mcp/response_trim.py

@@ -58,7 +58,7 @@ def trim_public_response(tool_name: str | None, payload: dict[str, Any]) -> 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 {
+        if tool_name in {"user:record_insert", "user:record_update", "user:record_delete"} and status in {
             "blocked",
             "needs_confirmation",
             "partial_success",
@@ -75,6 +75,8 @@ def trim_success_response(tool_name: str | None, payload: dict[str, Any]) -> dic
     drop_keys = COMMON_SUCCESS_DROP_TOP
     if tool_name == "user:record_get":
         drop_keys = COMMON_SUCCESS_DROP_TOP - {"output_profile"}
+    if tool_name in {"user:record_insert", "user:record_update", "user:record_delete"} and payload.get("ok") is False:
+        drop_keys = drop_keys - {"ok"}
     _drop_top_keys(trimmed, drop_keys)
     transformer = SUCCESS_POLICY_BY_TOOL.get(tool_name or "")
     if transformer is not None:
@@ -420,7 +422,7 @@ def _trim_record_write(payload: JSONObject) -> 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"):
+    for key in ("summary", "app_key", "mode"):
         if data.get(key) in (None, [], {}, ""):
             data.pop(key, None)
     items = payload.get("items")
@@ -449,10 +451,8 @@ def _trim_record_write_batch(payload: JSONObject, data: JSONObject) -> None:
             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)
+    if payload.get("items") in (None, [], {}, ""):
+        payload.pop("items", None)
 
 
 def _trim_record_get(payload: JSONObject) -> None:
@@ -714,13 +714,18 @@ def _trim_record_delete(payload: JSONObject) -> None:
     if not isinstance(data, dict):
         return
     resource = data.get("resource")
-    deleted_ids: list[str] = []
-    if isinstance(resource, dict):
+    deleted_ids = payload.get("deleted_ids") if isinstance(payload.get("deleted_ids"), list) else data.get("deleted_ids")
+    failed_ids = payload.get("failed_ids") if isinstance(payload.get("failed_ids"), list) else data.get("failed_ids")
+    if not isinstance(deleted_ids, list):
+        deleted_ids = []
+    if not isinstance(failed_ids, list):
+        failed_ids = []
+    if not deleted_ids and isinstance(resource, dict):
         raw_ids = resource.get("record_ids") or resource.get("apply_ids") or resource.get("applyIds")
         if isinstance(raw_ids, list):
             deleted_ids = [str(item) for item in raw_ids if item not in (None, "")]
-    data["deleted_ids"] = deleted_ids
-    data.setdefault("failed_ids", [])
+    data["deleted_ids"] = [str(item) for item in deleted_ids if item not in (None, "")]
+    data["failed_ids"] = [str(item) for item in failed_ids if item not in (None, "")]
     for key in (
         "resource",
         "action",

package/src/qingflow_mcp/server_app_builder.py

@@ -39,9 +39,10 @@ def build_builder_server() -> FastMCP:
             "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_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. "
+            "Builder apply/write outputs include schema_version, operation, summary, and resources[]; use resources[].id/key/name/ids/parent as the stable UI and agent display entry, and keep legacy fields such as field_diff/views_diff/chart_results only for compatibility or troubleshooting. "
             "For existing object parameter replacement, prefer patch_views, patch_buttons, patch_resources, and patch_charts with set/unset; the tool reads current config and full-saves internally, while upsert_* is for creation or full target configuration and should not be used as an incomplete partial update. "
-            "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 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 multi-app creation, pass apps[]/--apps-file on app_schema_apply; each item may have client_key, and relation fields may use target_app_ref to point at another same-call client_key. "
+            "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. New views default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless associated_resources is explicitly patched. "
             "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. field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id means current record id (-17), 编号/record_number means visible record number (0). To fill a target relation with the current record, map {'source_field': '数据ID', 'target_field': '目标引用字段'}; default_values is only for static constants. 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. Builder view_key arguments are raw keys from app_get.views[].view_key and must not be prefixed with custom:. "
             "For BI reports, keep report-body development separate from Qingflow in-app display: use app_charts_apply to create, update, remove, or reorder app-source QingBI chart bodies/configs with dataSourceType=qingflow; dataset BI reports are not created or edited by app_charts_apply yet and should be created in QingBI first, then attached with app_associated_resources_apply using report_source=dataset. "
             "For associated views/reports, use app_associated_resources_apply. Use match_mappings for filtering associated resources: dynamic current-record conditions use source_field, static conditions use value. match_mappings also supports 数据ID(-17) and 编号(0). Do not ask agents to write raw match_rules unless preserving a legacy backend config. "
@@ -407,7 +408,30 @@ def build_builder_server() -> FastMCP:
         add_fields: list[dict] | None = None,
         update_fields: list[dict] | None = None,
         remove_fields: list[dict] | None = None,
+        apps: list[dict] | None = None,
     ) -> dict:
+        if apps:
+            if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
+                return _config_failure(
+                    "app_schema_apply multi-app mode accepts package_id/create_if_missing plus apps only.",
+                    fix_hint="Use `apps` for batch mode, or use the single-app arguments without `apps`.",
+                )
+            if package_id is None:
+                return _config_failure(
+                    "app_schema_apply multi-app mode requires package_id.",
+                    fix_hint="Pass `package_id` and `apps[].app_name` for new apps, or `apps[].app_key` for existing apps.",
+                )
+            return ai_builder.app_schema_apply(
+                profile=profile,
+                package_id=package_id,
+                visibility=visibility,
+                create_if_missing=create_if_missing,
+                publish=publish,
+                add_fields=[],
+                update_fields=[],
+                remove_fields=[],
+                apps=apps,
+            )
         has_app_key = bool((app_key or "").strip())
         has_app_name = bool((app_name or "").strip())
         has_app_title = bool((app_title or "").strip())
@@ -437,6 +461,7 @@ def build_builder_server() -> FastMCP:
             add_fields=add_fields or [],
             update_fields=update_fields or [],
             remove_fields=remove_fields or [],
+            apps=[],
         )
 
     @server.tool()