@qingflow-tech/qingflow-cli 1.1.2 → 1.1.34

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

@@ -117,10 +117,12 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     app_get.add_argument(
         "builder_app_get_section",
         nargs="?",
-        choices=["summary", "fields", "layout", "views", "flow", "charts"],
+        choices=["summary", "fields", "layout", "views", "flow", "charts", "buttons", "associated-resources"],
         default="summary",
     )
-    app_get.add_argument("--app-key", required=True)
+    app_get.add_argument("--app-key", default="")
+    app_get.add_argument("--app-keys", default="", help="逗号分隔的多应用 app_key；用于批量读取同一 section")
+    app_get.add_argument("--app-keys-file", help="JSON 字符串数组；用于批量读取同一 section")
     app_get.set_defaults(handler=_handle_app_get, format_hint="builder_summary")
 
     app_repair_code_blocks = app_subparsers.add_parser("repair-code-blocks", help="扫描或修复现有代码块配置")
@@ -135,8 +137,15 @@ 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_get = button_subparsers.add_parser("get", help="读取应用自定义按钮配置")
+    button_get.add_argument("--app-key", default="")
+    button_get.add_argument("--app-keys", default="", help="逗号分隔的多应用 app_key；用于批量读取按钮配置")
+    button_get.add_argument("--app-keys-file", help="JSON 字符串数组；用于批量读取按钮配置")
+    button_get.set_defaults(handler=_handle_button_get, format_hint="builder_summary")
+
     button_apply = button_subparsers.add_parser("apply", help="声明式创建、更新或删除自定义按钮")
-    button_apply.add_argument("--app-key", required=True)
+    button_apply.add_argument("--app-key", default="")
+    button_apply.add_argument("--apps-file", help="多应用按钮配置 JSON 数组；每项包含 app_key 和按钮 payload")
     button_apply.add_argument("--upsert-buttons-file")
     button_apply.add_argument("--patch-buttons-file")
     button_apply.add_argument("--remove-buttons-file")
@@ -145,8 +154,15 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     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_get = associated_resource_subparsers.add_parser("get", help="读取应用关联资源配置")
+    associated_resource_get.add_argument("--app-key", default="")
+    associated_resource_get.add_argument("--app-keys", default="", help="逗号分隔的多应用 app_key；用于批量读取关联资源配置")
+    associated_resource_get.add_argument("--app-keys-file", help="JSON 字符串数组；用于批量读取关联资源配置")
+    associated_resource_get.set_defaults(handler=_handle_associated_resource_get, format_hint="builder_summary")
+
     associated_resource_apply = associated_resource_subparsers.add_parser("apply", help="声明式管理应用关联资源池和视图展示配置")
-    associated_resource_apply.add_argument("--app-key", required=True)
+    associated_resource_apply.add_argument("--app-key", default="")
+    associated_resource_apply.add_argument("--apps-file", help="多应用关联资源配置 JSON 数组；每项包含 app_key 和资源 payload")
     associated_resource_apply.add_argument("--upsert-resources-file")
     associated_resource_apply.add_argument("--patch-resources-file")
     associated_resource_apply.add_argument("--remove-associated-item-ids-file")
@@ -179,6 +195,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.add_argument("--patch-sections-file", help="门户组件局部更新 JSON 数组，每项含 chart_ref/view_ref/order + set/unset")
     portal_apply.set_defaults(handler=_handle_portal_apply, format_hint="builder_summary", force_json_output=True)
 
     portal_delete = portal_subparsers.add_parser("delete", help="删除门户")
@@ -195,9 +212,9 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     schema_apply_apply.add_argument("--icon")
     schema_apply_apply.add_argument("--color")
     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=None)
-    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("--apps-file", help="多应用 schema JSON 对象；每项可带 client_key/app_name/form，支持 relation target_app_ref")
+    schema_apply_apply.add_argument("--form-file", help="单应用表单结构 JSON 数组；form[].rows[][] 同时声明字段和表单分组布局")
     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")
@@ -206,46 +223,53 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     layout_apply = builder_subparsers.add_parser("layout", help="布局")
     layout_apply_subparsers = layout_apply.add_subparsers(dest="builder_layout_command", required=True)
     layout_apply_apply = layout_apply_subparsers.add_parser("apply", help="执行布局变更")
-    layout_apply_apply.add_argument("--app-key", required=True)
+    layout_apply_apply.add_argument("--app-key", default="")
+    layout_apply_apply.add_argument("--apps-file", help="多应用布局 JSON 数组；每项包含 app_key/mode?/publish?/sections")
     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.add_argument("--sections-file")
     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)
     views_apply_apply = views_apply_subparsers.add_parser("apply", help="执行视图变更")
-    views_apply_apply.add_argument("--app-key", required=True)
+    views_apply_apply.add_argument("--app-key", default="")
+    views_apply_apply.add_argument("--views-file", help='推荐批量视图 JSON 对象：{"views":[...]}；每项包含 app_key、operation、视图配置')
+    views_apply_apply.add_argument("--apps-file", help="多应用视图 JSON 数组；每项包含 app_key 和 upsert/patch/remove payload")
     views_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
     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", force_json_output=True)
 
-    flow_parser = builder_subparsers.add_parser("flow", help="流程（WorkflowSpec）")
-    flow_subparsers = flow_parser.add_subparsers(dest="builder_flow_command", required=True)
-
-    flow_schema = flow_subparsers.add_parser("schema", help="读取 WorkflowSpec JSON Schema")
+    flow_apply = builder_subparsers.add_parser("flow", help="流程")
+    flow_apply_subparsers = flow_apply.add_subparsers(dest="builder_flow_command", required=True)
+    flow_schema = flow_apply_subparsers.add_parser("schema", help="读取 WorkflowSpec JSON Schema")
     flow_schema.add_argument("--schema-version", default="")
     flow_schema.set_defaults(handler=_handle_flow_schema, format_hint="builder_summary")
 
-    flow_get = flow_subparsers.add_parser("get", help="读取 WorkflowSpec")
+    flow_get = flow_apply_subparsers.add_parser("get", help="读取 WorkflowSpec")
     flow_get.add_argument("--app-key", required=True)
     flow_get.add_argument("--version-id", default="")
     flow_get.set_defaults(handler=_handle_flow_get, format_hint="builder_summary")
 
-    flow_apply = flow_subparsers.add_parser("apply", help="应用 WorkflowSpec")
-    flow_apply.add_argument("--app-key", required=True)
-    flow_apply.add_argument("--spec-file", required=True)
-    flow_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
-    flow_apply.add_argument("--idempotency-key", default="")
-    flow_apply.add_argument("--schema-version", default="")
-    flow_apply.set_defaults(handler=_handle_flow_apply, format_hint="builder_summary", force_json_output=True)
+    flow_apply_apply = flow_apply_subparsers.add_parser("apply", help="执行流程变更")
+    flow_apply_apply.add_argument("--app-key", required=True)
+    flow_apply_apply.add_argument("--mode", choices=["replace"], default="replace", help=argparse.SUPPRESS)
+    flow_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
+    flow_apply_apply.add_argument("--nodes-file", help=argparse.SUPPRESS)
+    flow_apply_apply.add_argument("--transitions-file", help=argparse.SUPPRESS)
+    flow_apply_apply.add_argument("--spec-file")
+    flow_apply_apply.add_argument("--patch-nodes-file", help="节点局部更新 JSON 数组，每项含 id + set/unset")
+    flow_apply_apply.add_argument("--idempotency-key", default="")
+    flow_apply_apply.add_argument("--schema-version", default="")
+    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)
     charts_apply_apply = charts_apply_subparsers.add_parser("apply", help="执行报表变更")
-    charts_apply_apply.add_argument("--app-key", required=True)
+    charts_apply_apply.add_argument("--app-key", default="")
+    charts_apply_apply.add_argument("--apps-file", help="多应用报表 JSON 数组；每项包含 app_key 和 upsert/patch/remove/reorder payload")
     charts_apply_apply.add_argument("--upsert-file")
     charts_apply_apply.add_argument("--patch-file")
     charts_apply_apply.add_argument("--remove-chart-ids-file")
@@ -255,7 +279,9 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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("--app-key", default="")
+    publish_verify_verify.add_argument("--app-keys", default="", help="逗号分隔的多应用 app_key；用于批量发布校验")
+    publish_verify_verify.add_argument("--app-keys-file", help="JSON 字符串数组；用于批量发布校验")
     publish_verify_verify.add_argument("--expected-package-id", type=int)
     publish_verify_verify.set_defaults(handler=_handle_publish_verify, format_hint="builder_summary", force_json_output=True)
 
@@ -360,6 +386,7 @@ def _handle_package_apply(args: argparse.Namespace, context: CliContext) -> dict
     config = load_object_arg(args.config_file, option_name="--config-file")
     if not isinstance(config, dict):
         raise_config_error("package apply --config-file must contain a JSON object.")
+    config.pop("create_if_missing", None)
     return context.builder.package_apply(profile=args.profile, **config)
 
 
@@ -403,6 +430,9 @@ def _handle_button_catalog(args: argparse.Namespace, context: CliContext) -> dic
 
 
 def _handle_button_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    apps = load_list_arg(args.apps_file, option_name="--apps-file") if getattr(args, "apps_file", None) else None
+    if apps is None and not (args.app_key or "").strip():
+        raise_config_error("builder button apply requires --app-key unless --apps-file is provided")
     return context.builder.app_custom_buttons_apply(
         profile=args.profile,
         app_key=args.app_key,
@@ -410,10 +440,14 @@ def _handle_button_apply(args: argparse.Namespace, context: CliContext) -> dict:
         patch_buttons=load_list_arg(args.patch_buttons_file, option_name="--patch-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"),
+        apps=apps,
     )
 
 
 def _handle_associated_resource_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    apps = load_list_arg(args.apps_file, option_name="--apps-file") if getattr(args, "apps_file", None) else None
+    if apps is None and not (args.app_key or "").strip():
+        raise_config_error("builder associated-resource apply requires --app-key unless --apps-file is provided")
     return context.builder.app_associated_resources_apply(
         profile=args.profile,
         app_key=args.app_key,
@@ -422,11 +456,26 @@ def _handle_associated_resource_apply(args: argparse.Namespace, context: CliCont
         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"),
+        apps=apps,
     )
 
 
 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)
+    app_keys = _app_keys_from_args(args)
+    if app_keys is not None:
+        return context.builder.app_get_buttons(profile=args.profile, app_key="", app_keys=app_keys)
+    if not (args.app_key or "").strip():
+        raise_config_error("builder button get requires --app-key unless --app-keys or --app-keys-file is provided")
+    return context.builder.app_get_buttons(profile=args.profile, app_key=args.app_key)
+
+
+def _handle_associated_resource_get(args: argparse.Namespace, context: CliContext) -> dict:
+    app_keys = _app_keys_from_args(args)
+    if app_keys is not None:
+        return context.builder.app_get_associated_resources(profile=args.profile, app_key="", app_keys=app_keys)
+    if not (args.app_key or "").strip():
+        raise_config_error("builder associated-resource get requires --app-key unless --app-keys or --app-keys-file is provided")
+    return context.builder.app_get_associated_resources(profile=args.profile, app_key=args.app_key)
 
 
 def _handle_button_create(args: argparse.Namespace, context: CliContext) -> dict:
@@ -450,6 +499,17 @@ def _handle_button_delete(args: argparse.Namespace, context: CliContext) -> dict
     return context.builder.app_custom_button_delete(profile=args.profile, app_key=args.app_key, button_id=args.button_id)
 
 
+def _app_keys_from_args(args: argparse.Namespace) -> list[str] | None:
+    keys: list[str] = []
+    raw = str(getattr(args, "app_keys", "") or "").strip()
+    if raw:
+        keys.extend(part.strip() for part in raw.split(",") if part.strip())
+    keys_file = getattr(args, "app_keys_file", None)
+    if keys_file:
+        keys.extend(str(item).strip() for item in require_list_arg(keys_file, option_name="--app-keys-file") if str(item).strip())
+    return keys or None
+
+
 def _handle_app_get(args: argparse.Namespace, context: CliContext) -> dict:
     handlers = {
         "summary": context.builder.app_get,
@@ -458,7 +518,14 @@ def _handle_app_get(args: argparse.Namespace, context: CliContext) -> dict:
         "views": context.builder.app_get_views,
         "flow": context.builder.app_get_flow,
         "charts": context.builder.app_get_charts,
+        "buttons": context.builder.app_get_buttons,
+        "associated-resources": context.builder.app_get_associated_resources,
     }
+    app_keys = _app_keys_from_args(args)
+    if app_keys is not None:
+        return handlers[args.builder_app_get_section](profile=args.profile, app_key="", app_keys=app_keys)
+    if not (args.app_key or "").strip():
+        raise_config_error("builder app get requires --app-key unless --app-keys or --app-keys-file is provided")
     return handlers[args.builder_app_get_section](profile=args.profile, app_key=args.app_key)
 
 
@@ -495,17 +562,11 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
     if package_id is None and apps_payload.get("package_id") is not None:
         package_id = _coerce_apps_file_package_id(apps_payload["package_id"])
     if args.apps_file:
-        file_create_if_missing = _coerce_apps_file_bool(
-            apps_payload.get("create_if_missing"),
-            field_name="create_if_missing",
-            default=False,
-        )
         file_publish = _coerce_apps_file_bool(
             apps_payload.get("publish"),
             field_name="publish",
             default=True,
         )
-        effective_create_if_missing = bool(args.create_if_missing or file_create_if_missing)
         effective_publish = bool(args.publish if args.publish is not None else file_publish)
         if not apps:
             raise_config_error(
@@ -513,10 +574,10 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
                 fix_hint="Pass a JSON array, or a JSON object like {\"package_id\":1001,\"apps\":[...]} with at least one app item.",
                 error_code="APPS_FILE_EMPTY",
             )
-        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:
+        if args.app_key or args.app_name or args.app_title or args.form_file 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.",
+                "schema apply multi-app mode accepts --package-id plus --apps-file only.",
+                fix_hint="Use apps[].form inside --apps-file for batch mode, or remove --apps-file and use --form-file for a single app.",
             )
         if package_id is None:
             raise_config_error(
@@ -527,9 +588,9 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
             profile=args.profile,
             package_id=package_id,
             visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
-            create_if_missing=effective_create_if_missing,
             publish=effective_publish,
             apps=apps,
+            form=None,
             add_fields=[],
             update_fields=[],
             remove_fields=[],
@@ -544,16 +605,16 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
     has_app_title = bool((args.app_title or "").strip())
     has_package_id = args.package_id is not None
     if has_app_key:
-        if args.create_if_missing or has_package_id:
+        if has_package_id:
             raise_config_error(
                 "schema apply edit mode accepts --app-key and optional --app-name only.",
-                fix_hint="For existing apps, use `--app-key` and optionally `--app-name`. For create mode, use `--package-id --app-name --create-if-missing`.",
+                fix_hint="For existing apps, use `--app-key` and optionally `--app-name`. For create mode, use `--package-id --app-name`.",
             )
     else:
-        if not args.create_if_missing or not has_package_id or not (has_app_name or has_app_title):
+        if not has_package_id or not (has_app_name or has_app_title):
             raise_config_error(
-                "schema apply create mode requires --package-id, --app-name, and --create-if-missing.",
-                fix_hint="Use `--app-key` for existing apps, or pass `--package-id --app-name --create-if-missing` to create a new app.",
+                "schema apply create mode requires --package-id and --app-name.",
+                fix_hint="Use `--app-key` for existing apps, or pass `--package-id --app-name` to create a new app.",
             )
     return context.builder.app_schema_apply(
         profile=args.profile,
@@ -564,8 +625,8 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
         icon=args.icon,
         color=args.color,
         visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
-        create_if_missing=bool(args.create_if_missing),
         publish=True if args.publish is None else bool(args.publish),
+        form=load_list_arg(args.form_file, option_name="--form-file") if args.form_file else [],
         add_fields=load_list_arg(args.add_fields_file, option_name="--add-fields-file"),
         update_fields=load_list_arg(args.update_fields_file, option_name="--update-fields-file"),
         remove_fields=load_list_arg(args.remove_fields_file, option_name="--remove-fields-file"),
@@ -583,7 +644,12 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
                 "app_name": "员工花名册",
                 "icon": "business-personalcard",
                 "color": "emerald",
-                "add_fields": [],
+                "form": [
+                    {
+                        "section": "基础信息",
+                        "rows": [[{"name": "员工名称", "type": "text", "data_title": True}]],
+                    }
+                ],
             }
         ],
     }
@@ -591,7 +657,8 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
         "expected_shape": expected_shape,
         "expected_shape_json": (
             '{"package_id":1001,"apps":[{"client_key":"employee","app_name":"员工花名册",'
-            '"icon":"business-personalcard","color":"emerald","add_fields":[]}]}'
+            '"icon":"business-personalcard","color":"emerald","form":[{"section":"基础信息",'
+            '"rows":[[{"name":"员工名称","type":"text","data_title":true}]]}]}]}'
         ),
     }
     payload = load_json_value(path, option_name="--apps-file")
@@ -602,7 +669,7 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
             if not isinstance(apps, list):
                 raise_config_error(
                     "--apps-file wrapper object requires an apps array.",
-                    fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw apps array like [{\"app_name\":\"...\",\"icon\":\"...\",\"color\":\"...\",\"add_fields\":[...]}].",
+                    fix_hint='Use {"package_id":1001,"apps":[...]} with apps[].form, or pass a raw apps array with form sections.',
                     error_code="APPS_FILE_SHAPE_INVALID",
                     details=expected_shape_details,
                 )
@@ -617,15 +684,13 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
             }
             if wrapper.get("package_id") is not None:
                 result["package_id"] = wrapper.get("package_id")
-            if wrapper.get("create_if_missing") is not None:
-                result["create_if_missing"] = wrapper.get("create_if_missing")
             if wrapper.get("publish") is not None:
                 result["publish"] = wrapper.get("publish")
             return result
         if any(isinstance(item, dict) and "apps" in item for item in payload):
             raise_config_error(
                 "--apps-file root array items must be app items, not package wrapper objects.",
-                fix_hint="Use one object {\"package_id\":1001,\"apps\":[...]} or a raw app array [{\"app_name\":\"...\",\"icon\":\"...\",\"color\":\"...\",\"add_fields\":[...]}]. Do not wrap multiple {package_id, apps} objects in an array.",
+                fix_hint='Use one object {"package_id":1001,"apps":[...]} with apps[].form, or a raw app array with form sections. Do not wrap multiple {package_id, apps} objects in an array.',
                 error_code="APPS_FILE_SHAPE_INVALID",
                 details=expected_shape_details,
             )
@@ -642,8 +707,6 @@ def _load_apps_file_arg(path: str | None) -> dict[str, object]:
         result: dict[str, object] = {"apps": apps}
         if payload.get("package_id") is not None:
             result["package_id"] = payload.get("package_id")
-        if payload.get("create_if_missing") is not None:
-            result["create_if_missing"] = payload.get("create_if_missing")
         if payload.get("publish") is not None:
             result["publish"] = payload.get("publish")
         return result
@@ -709,17 +772,74 @@ def _coerce_apps_file_bool(value: object, *, field_name: str, default: bool) ->
     )
 
 
+def _load_views_file_arg(path: str | None) -> list[object] | None:
+    if not path:
+        return None
+    payload = load_json_value(path, option_name="--views-file")
+    if isinstance(payload, dict):
+        views = payload.get("views")
+        if not isinstance(views, list):
+            raise_config_error(
+                "--views-file JSON object must contain a views array.",
+                fix_hint='Use {"views": [{"operation": "upsert", "app_key": "...", "name": "...", "type": "table", "columns": [...]}]}.',
+                error_code="VIEWS_FILE_SHAPE_INVALID",
+                details={"expected": '{"views": [...]}', "actual_type": type(views).__name__},
+            )
+        return views
+    if isinstance(payload, list):
+        return payload
+    raise_config_error(
+        "--views-file must be a JSON object with views[] or a JSON array.",
+        fix_hint='Prefer {"views": [...]} for new automation. A bare array is accepted only for compatibility.',
+        error_code="VIEWS_FILE_SHAPE_INVALID",
+        details={"actual_type": type(payload).__name__},
+    )
+
+
 def _handle_layout_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    apps = load_list_arg(args.apps_file, option_name="--apps-file") if getattr(args, "apps_file", None) else None
+    if apps is None and not (args.app_key or "").strip():
+        raise_config_error("builder layout apply requires --app-key unless --apps-file is provided")
+    if apps is None and not getattr(args, "sections_file", None):
+        raise_config_error(
+            "--sections-file is required",
+            fix_hint="Pass --sections-file for single-app layout apply, or use --apps-file for batch layout apply.",
+            error_code="ARGUMENT_ERROR",
+            details={
+                "prog": "qingflow builder layout apply",
+                "usage": "qingflow builder layout apply --app-key APP_KEY --sections-file SECTIONS.json",
+            },
+        )
     return context.builder.app_layout_apply(
         profile=args.profile,
         app_key=args.app_key,
         mode=args.mode,
         publish=bool(args.publish),
-        sections=require_list_arg(args.sections_file, option_name="--sections-file"),
+        sections=[] if apps is not None else require_list_arg(args.sections_file, option_name="--sections-file"),
+        apps=apps,
     )
 
 
 def _handle_views_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    views = _load_views_file_arg(args.views_file) if getattr(args, "views_file", None) else None
+    apps = load_list_arg(args.apps_file, option_name="--apps-file") if getattr(args, "apps_file", None) else None
+    if views is not None:
+        if apps is not None or (args.app_key or "").strip() or getattr(args, "upsert_views_file", None) or getattr(args, "patch_views_file", None) or getattr(args, "remove_views_file", None):
+            raise_config_error(
+                "builder views apply --views-file cannot be mixed with --app-key, --apps-file, --upsert-views-file, --patch-views-file, or --remove-views-file.",
+                fix_hint="Use one shape: preferred --views-file for flat batch jobs, or legacy --app-key/--apps-file for grouped payloads.",
+            )
+        return context.builder.app_views_apply(
+            profile=args.profile,
+            app_key="",
+            publish=bool(args.publish),
+            upsert_views=[],
+            patch_views=[],
+            remove_views=[],
+            views=views,
+        )
+    if apps is None and not (args.app_key or "").strip():
+        raise_config_error("builder views apply requires --views-file, --apps-file, or --app-key")
     return context.builder.app_views_apply(
         profile=args.profile,
         app_key=args.app_key,
@@ -727,43 +847,63 @@ def _handle_views_apply(args: argparse.Namespace, context: CliContext) -> dict:
         upsert_views=load_list_arg(args.upsert_views_file, option_name="--upsert-views-file"),
         patch_views=load_list_arg(args.patch_views_file, option_name="--patch-views-file"),
         remove_views=load_list_arg(args.remove_views_file, option_name="--remove-views-file"),
+        apps=apps,
     )
 
 
-def _handle_flow_schema(args: argparse.Namespace, context: CliContext) -> dict:
-    return context.builder.app_flow_get_schema(
-        profile=args.profile,
-        schema_version=args.schema_version or None,
+def _handle_flow_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    patch_nodes = load_list_arg(getattr(args, "patch_nodes_file", None), option_name="--patch-nodes-file")
+    spec = load_object_arg(getattr(args, "spec_file", None), option_name="--spec-file")
+    has_legacy_nodes = bool(getattr(args, "nodes_file", None) or getattr(args, "transitions_file", None))
+    if has_legacy_nodes:
+        raise_config_error(
+            "builder flow apply no longer exposes legacy --nodes-file/--transitions-file input.",
+            fix_hint="Use --spec-file for a complete WorkflowSpec, or --patch-nodes-file for targeted edits after builder flow get.",
+            error_code="FLOW_LEGACY_INPUT_DISABLED",
+            details={"allowed_input_modes": ["--spec-file", "--patch-nodes-file"]},
+        )
+    selected_modes = sum(1 for selected in (bool(patch_nodes), bool(spec), has_legacy_nodes) if selected)
+    if selected_modes != 1:
+        raise_config_error(
+            "builder flow apply requires exactly one input mode: --spec-file or --patch-nodes-file.",
+            fix_hint="Use --spec-file for a complete WorkflowSpec, or --patch-nodes-file for targeted edits after builder flow get.",
+        )
+    if patch_nodes:
+        return context.builder.app_flow_apply(
+            profile=args.profile,
+            app_key=args.app_key,
+            publish=bool(args.publish),
+            patch_nodes=patch_nodes,
+            idempotency_key=args.idempotency_key,
+            schema_version=args.schema_version,
+        )
+    if spec:
+        return context.builder.app_flow_apply(
+            profile=args.profile,
+            app_key=args.app_key,
+            publish=bool(args.publish),
+            spec=spec,
+            idempotency_key=args.idempotency_key,
+            schema_version=args.schema_version,
+        )
+    raise_config_error(
+        "builder flow apply requires --spec-file or --patch-nodes-file.",
+        fix_hint="Use --spec-file for a complete WorkflowSpec, or --patch-nodes-file for targeted edits after builder flow get.",
     )
 
 
-def _handle_flow_get(args: argparse.Namespace, context: CliContext) -> dict:
-    return context.builder.app_get_flow(
-        profile=args.profile,
-        app_key=args.app_key,
-        version_id=args.version_id or None,
-    )
+def _handle_flow_schema(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_flow_get_schema(profile=args.profile, schema_version=args.schema_version)
 
 
-def _handle_flow_apply(args: argparse.Namespace, context: CliContext) -> dict:
-    spec_payload = load_object_arg(args.spec_file, option_name="--spec-file")
-    if not isinstance(spec_payload, dict):
-        raise_config_error("flow apply --spec-file must contain a JSON object.")
-    if "spec" in spec_payload and isinstance(spec_payload.get("spec"), dict):
-        spec = spec_payload["spec"]
-    else:
-        spec = spec_payload
-    return context.builder.app_flow_apply(
-        profile=args.profile,
-        app_key=args.app_key,
-        publish=bool(args.publish),
-        spec=spec,
-        idempotency_key=args.idempotency_key or None,
-        schema_version=args.schema_version or None,
-    )
+def _handle_flow_get(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.app_flow_get(profile=args.profile, app_key=args.app_key, version_id=args.version_id)
 
 
 def _handle_charts_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    apps = load_list_arg(args.apps_file, option_name="--apps-file") if getattr(args, "apps_file", None) else None
+    if apps is None and not (args.app_key or "").strip():
+        raise_config_error("builder charts apply requires --app-key unless --apps-file is provided")
     return context.builder.app_charts_apply(
         profile=args.profile,
         app_key=args.app_key,
@@ -771,6 +911,7 @@ def _handle_charts_apply(args: argparse.Namespace, context: CliContext) -> dict:
         patch_charts=load_list_arg(args.patch_file, option_name="--patch-file"),
         remove_chart_ids=load_list_arg(args.remove_chart_ids_file, option_name="--remove-chart-ids-file"),
         reorder_chart_ids=load_list_arg(args.reorder_chart_ids_file, option_name="--reorder-chart-ids-file"),
+        apps=apps,
     )
 
 
@@ -793,6 +934,11 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
             fix_hint="Use `--dash-key` for an existing portal. For create mode, pass `--package-id --dash-name`.",
         )
     sections = [] if not args.sections_file else require_list_arg(args.sections_file, option_name="--sections-file")
+    patch_sections = (
+        load_list_arg(args.patch_sections_file, option_name="--patch-sections-file")
+        if args.patch_sections_file
+        else None
+    )
     return context.builder.portal_apply(
         profile=args.profile,
         dash_key=args.dash_key,
@@ -809,6 +955,7 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
         dash_global_config=load_object_arg(args.dash_global_config_file, option_name="--dash-global-config-file"),
         config=load_object_arg(args.config_file, option_name="--config-file"),
         payload=payload,
+        patch_sections=patch_sections,
     )
 
 
@@ -820,6 +967,16 @@ def _handle_portal_delete(args: argparse.Namespace, context: CliContext) -> dict
 
 
 def _handle_publish_verify(args: argparse.Namespace, context: CliContext) -> dict:
+    app_keys = _app_keys_from_args(args)
+    if app_keys is not None:
+        return context.builder.app_publish_verify(
+            profile=args.profile,
+            app_key="",
+            app_keys=app_keys,
+            expected_package_id=args.expected_package_id,
+        )
+    if not (args.app_key or "").strip():
+        raise_config_error("builder publish verify requires --app-key unless --app-keys or --app-keys-file is provided")
     return context.builder.app_publish_verify(
         profile=args.profile,
         app_key=args.app_key,

package/src/qingflow_mcp/cli/main.py

@@ -79,6 +79,23 @@ def run(
         return 2
     except SystemExit as exc:
         return int(exc.code or 0)
+    try:
+        _validate_conditional_args(args)
+    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_args(args, payload)
+            emit_json_result(payload, stream=out)
+            return 2
+        err.write(exc.usage)
+        err.write(f"{exc.prog}: error: {exc.message}\n")
+        return 2
     setattr(args, "_stdin", sys.stdin)
     setattr(args, "_stdout_stream", out)
     setattr(args, "_stderr_stream", err)
@@ -144,6 +161,21 @@ def _emit_version(*, json_mode: bool, stdout: TextIO) -> int:
     return 0
 
 
+def _validate_conditional_args(args: argparse.Namespace) -> None:
+    if (
+        getattr(args, "command", "") in {"builder", "build"}
+        and getattr(args, "builder_command", "") == "layout"
+        and getattr(args, "builder_layout_command", "") == "apply"
+        and not getattr(args, "apps_file", None)
+        and not getattr(args, "sections_file", None)
+    ):
+        raise _CliArgumentError(
+            prog="qingflow builder layout apply",
+            message="--sections-file is required",
+            usage="usage: qingflow builder layout apply --app-key APP_KEY --sections-file SECTIONS.json\n",
+        )
+
+
 def _should_force_json_output_argv_for_version(argv: list[str]) -> bool:
     return "--json" in argv
 
@@ -384,6 +416,8 @@ def _emit_error(payload: dict[str, Any], *, json_mode: bool, stdout: TextIO, std
 
 
 def _error_exit_code(payload: dict[str, Any]) -> int:
+    if str(payload.get("error_code") or "").upper() == "ARGUMENT_ERROR":
+        return 2
     if _is_auth_or_workspace_payload(payload):
         return 3
     return 4