@josephyan/qingflow-app-builder-mcp 1.1.24 → 1.1.26

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

@@ -1,11 +1,94 @@
 from __future__ import annotations
 
 import argparse
-from copy import deepcopy
+from typing import Any
 
 from ..context import CliContext
 from ..json_io import load_json_value
-from .common import load_list_arg, load_object_arg, parse_bool_text, raise_config_error, require_list_arg
+from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
+
+
+def _parse_app_keys_arg(raw: Any) -> list[str] | None:
+    """Parse comma-separated --app-keys argument into a list, or return None if empty."""
+    if not raw:
+        return None
+    keys = [k.strip() for k in str(raw).split(",") if k.strip()]
+    return keys if keys else None
+
+
+def _load_schema_apps_payload(path: str | None, *, cli_package_id: int | None) -> tuple[list[Any], int | None]:
+    """Load schema --apps-file.
+
+    Public docs recommend {"package_id": 123, "apps": [...]}; older payloads used
+    a raw apps array, and some agents accidentally wrapped the object in a
+    singleton array. Keep all three shapes on the same multi-app path.
+    """
+    if not path:
+        return [], cli_package_id
+    payload = load_json_value(path, option_name="--apps-file")
+    package_id = cli_package_id
+    if isinstance(payload, dict):
+        if package_id is None:
+            raw_package_id = payload.get("package_id")
+            if isinstance(raw_package_id, int):
+                package_id = raw_package_id
+            elif raw_package_id is not None and str(raw_package_id).strip().isdigit():
+                package_id = int(str(raw_package_id).strip())
+        apps = payload.get("apps")
+    elif isinstance(payload, list):
+        if len(payload) == 1 and isinstance(payload[0], dict) and "apps" in payload[0]:
+            wrapper = payload[0]
+            if package_id is None:
+                raw_package_id = wrapper.get("package_id")
+                if isinstance(raw_package_id, int):
+                    package_id = raw_package_id
+                elif raw_package_id is not None and str(raw_package_id).strip().isdigit():
+                    package_id = int(str(raw_package_id).strip())
+            apps = wrapper.get("apps")
+        elif any(isinstance(item, dict) and "apps" in item for item in payload):
+            raise_config_error(
+                "APPS_FILE_SHAPE_INVALID: --apps-file may be {package_id, apps}, a raw apps array, or a singleton wrapper array only.",
+                fix_hint='Use {"package_id": 123, "apps": [{"client_key": "main", "app_name": "主表", "icon": "database", "color": "blue", "add_fields": []}]}',
+            )
+        else:
+            apps = payload
+    else:
+        raise_config_error(
+            "APPS_FILE_SHAPE_INVALID: --apps-file must be {package_id, apps} or a JSON array of app items.",
+            fix_hint='Use {"package_id": 123, "apps": [{"client_key": "main", "app_name": "主表", "icon": "database", "color": "blue", "add_fields": []}]}',
+        )
+    if not isinstance(apps, list):
+        raise_config_error(
+            "APPS_FILE_SHAPE_INVALID: --apps-file apps must be a JSON array.",
+            fix_hint='Use {"package_id": 123, "apps": [{"client_key": "main", "app_name": "主表", "icon": "database", "color": "blue", "add_fields": []}]}',
+        )
+    return apps, package_id
+
+
+def _load_views_payload(path: str | None) -> list[Any]:
+    """Load views --views-file.
+
+    Public docs recommend {"views": [...]}; accept a raw array as a small
+    compatibility convenience because most other builder file flags are arrays.
+    """
+    if not path:
+        return []
+    payload = load_json_value(path, option_name="--views-file")
+    if isinstance(payload, dict):
+        views = payload.get("views")
+    elif isinstance(payload, list):
+        views = payload
+    else:
+        raise_config_error(
+            "VIEWS_FILE_SHAPE_INVALID: --views-file must be {views: [...]} or a JSON array.",
+            fix_hint='Use {"views": [{"operation": "upsert", "app_key": "APP_KEY", "name": "业务视图", "type": "table", "columns": ["字段A"]}]}',
+        )
+    if not isinstance(views, list):
+        raise_config_error(
+            "VIEWS_FILE_SHAPE_INVALID: --views-file views must be a JSON array.",
+            fix_hint='Use {"views": [{"operation": "upsert", "app_key": "APP_KEY", "name": "业务视图", "type": "table", "columns": ["字段A"]}]}',
+        )
+    return views
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -22,7 +105,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     file_upload_local.add_argument("--bucket-type")
     file_upload_local.add_argument("--path-id", type=int)
     file_upload_local.add_argument("--file-related-url")
-    file_upload_local.set_defaults(handler=_handle_file_upload_local, format_hint="file_upload_local")
+    file_upload_local.set_defaults(handler=_handle_file_upload_local, format_hint="generic")
 
     feedback = builder_subparsers.add_parser("feedback", help="builder 侧反馈提交")
     feedback_subparsers = feedback.add_subparsers(dest="builder_feedback_command", required=True)
@@ -38,7 +121,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     feedback_submit.add_argument("--record-id")
     feedback_submit.add_argument("--workflow-node-id")
     feedback_submit.add_argument("--note")
-    feedback_submit.set_defaults(handler=_handle_feedback_submit, format_hint="feedback_submit")
+    feedback_submit.set_defaults(handler=_handle_feedback_submit, format_hint="generic")
 
     contract = builder_subparsers.add_parser("contract", help="读取 builder tool 合约")
     contract.add_argument("--tool-name", required=True)
@@ -52,7 +135,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     member = builder_subparsers.add_parser("member", help="成员目录")
     member_subparsers = member.add_subparsers(dest="builder_member_command", required=True)
     member_search = member_subparsers.add_parser("search", help="搜索成员")
-    member_search.add_argument("--query", required=True)
+    member_search.add_argument("--query", default="")
     member_search.add_argument("--page-num", type=int, default=1)
     member_search.add_argument("--page-size", type=int, default=20)
     member_search.add_argument("--contain-disable", action=argparse.BooleanOptionalAction, default=False)
@@ -61,7 +144,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     role = builder_subparsers.add_parser("role", help="角色目录")
     role_subparsers = role.add_subparsers(dest="builder_role_command", required=True)
     role_search = role_subparsers.add_parser("search", help="搜索角色")
-    role_search.add_argument("--keyword", required=True)
+    role_search.add_argument("--keyword", default="")
     role_search.add_argument("--page-num", type=int, default=1)
     role_search.add_argument("--page-size", type=int, default=20)
     role_search.set_defaults(handler=_handle_role_search, format_hint="builder_summary")
@@ -121,8 +204,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
         default="summary",
     )
     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.add_argument("--app-keys", help="逗号分隔的多应用批量读取，例如: KEY1,KEY2,KEY3")
     app_get.set_defaults(handler=_handle_app_get, format_hint="builder_summary")
 
     app_repair_code_blocks = app_subparsers.add_parser("repair-code-blocks", help="扫描或修复现有代码块配置")
@@ -139,35 +221,34 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     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.add_argument("--app-keys", help="逗号分隔的多应用批量读取，例如: KEY1,KEY2,KEY3")
     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", 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")
     button_apply.add_argument("--view-configs-file")
+    button_apply.add_argument("--apps-file", help="多应用批量按钮 JSON 数组，每项含 app_key + upsert_buttons/patch_buttons/remove_buttons/view_configs")
     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)
+
     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.add_argument("--app-keys", help="逗号分隔的多应用批量读取，例如: KEY1,KEY2,KEY3")
     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", 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")
     associated_resource_apply.add_argument("--reorder-associated-item-ids-file")
     associated_resource_apply.add_argument("--view-configs-file")
+    associated_resource_apply.add_argument("--apps-file", help="多应用批量关联资源 JSON 数组，每项含 app_key + upsert_resources/patch_resources/remove_associated_item_ids/reorder_associated_item_ids/view_configs")
     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="门户")
@@ -195,13 +276,9 @@ 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.add_argument("--patch-sections-file", help="门户组件局部更新 JSON 数组，每项含 chart 或 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="删除门户")
-    portal_delete.add_argument("--dash-key", required=True)
-    portal_delete.set_defaults(handler=_handle_portal_delete, 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)
     schema_apply_apply = schema_apply_subparsers.add_parser("apply", help="执行字段变更")
@@ -212,9 +289,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("--publish", action=argparse.BooleanOptionalAction, default=None)
-    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("--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；推荐对象 {package_id, apps}，兼容 raw apps 数组；支持 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")
@@ -224,63 +301,61 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     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", 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")
+    layout_apply_apply.add_argument("--apps-file", help="多应用批量布局 JSON 数组，每项含 app_key + sections")
     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", default="")
-    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.add_argument("--views-file", help="推荐：扁平批量视图 JSON；对象 {views:[{operation, app_key, ...}]}，同 app/跨 app 均可")
+    views_apply_apply.add_argument("--apps-file", help="多应用批量视图 JSON 数组，每项含 app_key + upsert_views/patch_views/remove_views")
     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)
-    flow_schema = flow_apply_subparsers.add_parser("schema", help="读取 WorkflowSpec JSON Schema")
+    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_schema.add_argument("--schema-version", default="")
     flow_schema.set_defaults(handler=_handle_flow_schema, format_hint="builder_summary")
 
-    flow_get = flow_apply_subparsers.add_parser("get", help="读取 WorkflowSpec")
+    flow_get = flow_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_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")
-    flow_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
-    flow_apply_apply.add_argument("--nodes-file")
-    flow_apply_apply.add_argument("--transitions-file")
-    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)
+    flow_apply = flow_subparsers.add_parser("apply", help="应用 WorkflowSpec")
+    flow_apply.add_argument("--app-key", required=True)
+    flow_apply.add_argument("--spec-file")
+    flow_apply.add_argument("--patch-nodes-file", help="节点局部更新 JSON 数组，每项含 id + set/unset")
+    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)
 
     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", 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")
     charts_apply_apply.add_argument("--reorder-chart-ids-file")
+    charts_apply_apply.add_argument("--apps-file", help="多应用批量报表 JSON 数组，每项含 app_key + upsert_charts/patch_charts/remove_chart_ids/reorder_chart_ids")
     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", 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("--app-keys", help="逗号分隔的多应用批量校验，例如: KEY1,KEY2,KEY3")
     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)
 
@@ -385,7 +460,6 @@ 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)
 
 
@@ -429,9 +503,26 @@ 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")
+    apps = load_list_arg(getattr(args, "apps_file", None), option_name="--apps-file")
+    if apps:
+        single_app_args = [a for a in ["--app-key" if args.app_key else None, "--upsert-buttons-file" if getattr(args, "upsert_buttons_file", None) else None, "--patch-buttons-file" if getattr(args, "patch_buttons_file", None) else None, "--remove-buttons-file" if getattr(args, "remove_buttons_file", None) else None, "--view-configs-file" if getattr(args, "view_configs_file", None) else None] if a]
+        if single_app_args:
+            raise_config_error(
+                f"button apply --apps-file cannot be combined with {', '.join(single_app_args)}.",
+                fix_hint="Use --apps-file for batch mode (each item contains app_key + per-app params), or remove --apps-file for single-app mode.",
+            )
+    if apps:
+        return context.builder.app_custom_buttons_apply(
+            profile=args.profile,
+            app_key="",
+            upsert_buttons=[],
+            patch_buttons=[],
+            remove_buttons=[],
+            view_configs=[],
+            apps=apps,
+        )
+    if not args.app_key:
+        raise_config_error("button apply requires --app-key or --apps-file", fix_hint="Pass --app-key APP_KEY for single-app mode, or --apps-file for batch mode.")
     return context.builder.app_custom_buttons_apply(
         profile=args.profile,
         app_key=args.app_key,
@@ -439,14 +530,40 @@ 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")
+    apps = load_list_arg(getattr(args, "apps_file", None), option_name="--apps-file")
+    if apps:
+        single_app_args = [
+            a for a in [
+                "--app-key" if args.app_key else None,
+                "--upsert-resources-file" if getattr(args, "upsert_resources_file", None) else None,
+                "--patch-resources-file" if getattr(args, "patch_resources_file", None) else None,
+                "--remove-associated-item-ids-file" if getattr(args, "remove_associated_item_ids_file", None) else None,
+                "--reorder-associated-item-ids-file" if getattr(args, "reorder_associated_item_ids_file", None) else None,
+                "--view-configs-file" if getattr(args, "view_configs_file", None) else None,
+            ] if a
+        ]
+        if single_app_args:
+            raise_config_error(
+                f"associated-resource apply --apps-file cannot be combined with {', '.join(single_app_args)}.",
+                fix_hint="Use --apps-file for batch mode (each item contains app_key + per-app params), or remove --apps-file for single-app mode.",
+            )
+    if apps:
+        return context.builder.app_associated_resources_apply(
+            profile=args.profile,
+            app_key="",
+            upsert_resources=[],
+            patch_resources=[],
+            remove_associated_item_ids=[],
+            reorder_associated_item_ids=[],
+            view_configs=[],
+            apps=apps,
+        )
+    if not args.app_key:
+        raise_config_error("associated-resource apply requires --app-key or --apps-file", fix_hint="Pass --app-key APP_KEY for single-app mode, or --apps-file for batch mode.")
     return context.builder.app_associated_resources_apply(
         profile=args.profile,
         app_key=args.app_key,
@@ -455,26 +572,27 @@ 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:
-    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)
+    app_keys = _parse_app_keys_arg(getattr(args, "app_keys", None))
+    if app_keys:
+        return context.builder.app_get_buttons(profile=args.profile, app_keys=app_keys)
+    app_key = str(getattr(args, "app_key", "") or "").strip()
+    if not app_key:
+        raise_config_error("button get requires --app-key or --app-keys", fix_hint="Pass --app-key APP_KEY or --app-keys KEY1,KEY2")
+    return context.builder.app_get_buttons(profile=args.profile, app_key=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)
+    app_keys = _parse_app_keys_arg(getattr(args, "app_keys", None))
+    if app_keys:
+        return context.builder.app_get_associated_resources(profile=args.profile, app_keys=app_keys)
+    app_key = str(getattr(args, "app_key", "") or "").strip()
+    if not app_key:
+        raise_config_error("associated-resource get requires --app-key or --app-keys", fix_hint="Pass --app-key APP_KEY or --app-keys KEY1,KEY2")
+    return context.builder.app_get_associated_resources(profile=args.profile, app_key=app_key)
 
 
 def _handle_button_create(args: argparse.Namespace, context: CliContext) -> dict:
@@ -498,18 +616,32 @@ 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:
+    section = args.builder_app_get_section
+    app_keys = _parse_app_keys_arg(getattr(args, "app_keys", None))
+    app_key = str(getattr(args, "app_key", "") or "").strip()
+    if not app_keys and not app_key:
+        raise_config_error("app get requires --app-key or --app-keys", fix_hint="Pass --app-key APP_KEY or --app-keys KEY1,KEY2")
+    if section == "buttons":
+        if app_keys:
+            return context.builder.app_get_buttons(profile=args.profile, app_keys=app_keys)
+        return context.builder.app_get_buttons(profile=args.profile, app_key=app_key)
+    if section == "associated-resources":
+        if app_keys:
+            return context.builder.app_get_associated_resources(profile=args.profile, app_keys=app_keys)
+        return context.builder.app_get_associated_resources(profile=args.profile, app_key=app_key)
+    if app_keys:
+        batch_handlers = {
+            "summary": context.builder.app_get,
+            "fields": context.builder.app_get_fields,
+            "layout": context.builder.app_get_layout,
+            "views": context.builder.app_get_views,
+            "flow": context.builder.app_get_flow,
+            "charts": context.builder.app_get_charts,
+        }
+        if section not in batch_handlers:
+            raise_config_error(f"app get --app-keys does not support section '{section}'", fix_hint="Batch reads support: summary, fields, layout, views, flow, charts, buttons, associated-resources")
+        return batch_handlers[section](profile=args.profile, app_keys=app_keys)
     handlers = {
         "summary": context.builder.app_get,
         "fields": context.builder.app_get_fields,
@@ -517,15 +649,8 @@ 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)
+    return handlers[section](profile=args.profile, app_key=app_key)
 
 
 def _handle_app_repair_code_blocks(args: argparse.Namespace, context: CliContext) -> dict:
@@ -554,66 +679,49 @@ def _handle_chart_get(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
-    apps_payload = _load_apps_file_arg(args.apps_file)
-    apps = apps_payload["apps"]
-    apps_warnings = apps_payload.get("warnings") or []
-    package_id = args.package_id
-    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"])
+    apps, apps_package_id = _load_schema_apps_payload(args.apps_file, cli_package_id=args.package_id)
     if args.apps_file:
-        file_publish = _coerce_apps_file_bool(
-            apps_payload.get("publish"),
-            field_name="publish",
-            default=True,
-        )
-        effective_publish = bool(args.publish if args.publish is not None else file_publish)
         if not apps:
             raise_config_error(
                 "schema apply multi-app mode requires a non-empty --apps-file.",
-                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",
+                fix_hint='Pass {"package_id": 123, "apps": [{"client_key": "main", "app_name": "主表", "icon": "database", "color": "blue", "add_fields": []}]}',
             )
-        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:
+        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 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.",
+                "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 package_id is None:
+        if apps_package_id is None:
             raise_config_error(
                 "schema apply multi-app mode requires --package-id.",
-                fix_hint="Pass `--package-id`, or put `package_id` at the top level of --apps-file. `package_name` alone does not create the package here; run `builder package apply` first.",
+                fix_hint="Pass root `--package-id`, or include package_id in the --apps-file object.",
             )
-        result = context.builder.app_schema_apply(
+        return context.builder.app_schema_apply(
             profile=args.profile,
-            package_id=package_id,
+            package_id=apps_package_id,
             visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
-            publish=effective_publish,
+            create_if_missing=bool(args.create_if_missing),
+            publish=bool(args.publish),
             apps=apps,
-            form=None,
             add_fields=[],
             update_fields=[],
             remove_fields=[],
         )
-        if apps_warnings and isinstance(result, dict):
-            result_warnings = list(result.get("warnings") or [])
-            result_warnings.extend(deepcopy(apps_warnings))
-            result["warnings"] = result_warnings
-        return result
     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())
     has_package_id = args.package_id is not None
     if has_app_key:
-        if has_package_id:
+        if args.create_if_missing or 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`.",
+                fix_hint="For existing apps, use `--app-key` and optionally `--app-name`. For create mode, use `--package-id --app-name --create-if-missing`.",
             )
     else:
-        if not has_package_id or not (has_app_name or has_app_title):
+        if not args.create_if_missing or not has_package_id or not (has_app_name or has_app_title):
             raise_config_error(
-                "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.",
+                "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.",
             )
     return context.builder.app_schema_apply(
         profile=args.profile,
@@ -624,175 +732,92 @@ 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"),
-        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 [],
+        create_if_missing=bool(args.create_if_missing),
+        publish=bool(args.publish),
         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"),
     )
 
 
-def _load_apps_file_arg(path: str | None) -> dict[str, object]:
-    if not path:
-        return {"apps": []}
-    expected_shape = {
-        "package_id": 1001,
-        "apps": [
-            {
-                "client_key": "employee",
-                "app_name": "员工花名册",
-                "icon": "business-personalcard",
-                "color": "emerald",
-                "add_fields": [],
-            }
-        ],
-    }
-    expected_shape_details = {
-        "expected_shape": expected_shape,
-        "expected_shape_json": (
-            '{"package_id":1001,"apps":[{"client_key":"employee","app_name":"员工花名册",'
-            '"icon":"business-personalcard","color":"emerald","add_fields":[]}]}'
-        ),
-    }
-    payload = load_json_value(path, option_name="--apps-file")
-    if isinstance(payload, list):
-        if len(payload) == 1 and isinstance(payload[0], dict) and "apps" in payload[0]:
-            wrapper = payload[0]
-            apps = wrapper.get("apps")
-            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\":[...]}].",
-                    error_code="APPS_FILE_SHAPE_INVALID",
-                    details=expected_shape_details,
-                )
-            result: dict[str, object] = {
-                "apps": apps,
-                "warnings": [
-                    {
-                        "code": "APPS_FILE_WRAPPER_ARRAY_UNWRAPPED",
-                        "message": "--apps-file was a singleton wrapper array; normalized it to {package_id, apps}.",
-                    }
-                ],
-            }
-            if wrapper.get("package_id") is not None:
-                result["package_id"] = wrapper.get("package_id")
-            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.",
-                error_code="APPS_FILE_SHAPE_INVALID",
-                details=expected_shape_details,
-            )
-        return {"apps": payload}
-    if isinstance(payload, dict):
-        apps = payload.get("apps")
-        if not isinstance(apps, list):
+def _handle_layout_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    apps = load_list_arg(getattr(args, "apps_file", None), option_name="--apps-file")
+    if apps:
+        single_app_args = [a for a in ["--app-key" if args.app_key else None, "--sections-file" if getattr(args, "sections_file", None) else None] if a]
+        if single_app_args:
             raise_config_error(
-                "--apps-file JSON object requires an apps array.",
-                fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw JSON array.",
-                error_code="APPS_FILE_SHAPE_INVALID",
-                details=expected_shape_details,
+                f"layout apply --apps-file cannot be combined with {', '.join(single_app_args)}.",
+                fix_hint="Use --apps-file for batch mode (each item contains app_key + sections), or remove --apps-file for single-app mode.",
             )
-        result: dict[str, object] = {"apps": apps}
-        if payload.get("package_id") is not None:
-            result["package_id"] = payload.get("package_id")
-        if payload.get("publish") is not None:
-            result["publish"] = payload.get("publish")
-        return result
-    raise_config_error(
-        "--apps-file must be a JSON array or an object containing apps.",
-        fix_hint="Use [{...}] or {\"package_id\":1001,\"apps\":[...]}",
-        error_code="APPS_FILE_SHAPE_INVALID",
-        details=expected_shape_details,
-    )
-
-
-def _coerce_apps_file_package_id(value: object) -> int:
-    package_id: int
-    if isinstance(value, bool):
-        _raise_apps_file_package_id_invalid(value)
-    if isinstance(value, int):
-        package_id = value
-    elif isinstance(value, str):
-        stripped = value.strip()
-        try:
-            package_id = int(stripped)
-        except ValueError:
-            _raise_apps_file_package_id_invalid(value)
-    else:
-        _raise_apps_file_package_id_invalid(value)
-    if package_id <= 0:
-        _raise_apps_file_package_id_invalid(value)
-    return package_id
-
-
-def _raise_apps_file_package_id_invalid(value: object) -> None:
-    raise_config_error(
-        "--apps-file package_id must be a positive integer.",
-        fix_hint='Use a numeric package_id, for example {"package_id":1001,"apps":[...]}.',
-        error_code="APPS_FILE_PACKAGE_ID_INVALID",
-        details={
-            "field": "package_id",
-            "value": value,
-            "expected": "positive integer or numeric string",
-        },
-    )
-
-
-def _coerce_apps_file_bool(value: object, *, field_name: str, default: bool) -> bool:
-    if value is None:
-        return default
-    if isinstance(value, bool):
-        return value
-    if isinstance(value, str):
-        try:
-            return parse_bool_text(value)
-        except argparse.ArgumentTypeError:
-            pass
-    raise_config_error(
-        f"--apps-file {field_name} must be a boolean.",
-        fix_hint=f'Use "{field_name}": true or "{field_name}": false in --apps-file.',
-        error_code="APPS_FILE_BOOLEAN_INVALID",
-        details={
-            "field": field_name,
-            "value": value,
-            "expected": "boolean true/false or string true/false/1/0/yes/no",
-        },
-    )
-
-
-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",
-            },
+    if apps:
+        return context.builder.app_layout_apply(
+            profile=args.profile,
+            app_key="",
+            mode=args.mode,
+            publish=bool(args.publish),
+            sections=[],
+            apps=apps,
         )
+    if not args.app_key:
+        raise_config_error("layout apply requires --app-key or --apps-file", fix_hint="Pass --app-key + --sections-file for single-app mode, or --apps-file for batch mode.")
     return context.builder.app_layout_apply(
         profile=args.profile,
         app_key=args.app_key,
         mode=args.mode,
         publish=bool(args.publish),
-        sections=[] if apps is not None else require_list_arg(args.sections_file, option_name="--sections-file"),
-        apps=apps,
+        sections=require_list_arg(args.sections_file, option_name="--sections-file"),
     )
 
 
 def _handle_views_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 views apply requires --app-key unless --apps-file is provided")
+    views_file = getattr(args, "views_file", None)
+    views = _load_views_payload(views_file)
+    if views_file is not None:
+        legacy_args = [
+            a
+            for a in [
+                "--app-key" if args.app_key else None,
+                "--apps-file" if getattr(args, "apps_file", None) else None,
+                "--upsert-views-file" if getattr(args, "upsert_views_file", None) else None,
+                "--patch-views-file" if getattr(args, "patch_views_file", None) else None,
+                "--remove-views-file" if getattr(args, "remove_views_file", None) else None,
+            ]
+            if a
+        ]
+        if legacy_args:
+            raise_config_error(
+                f"views apply --views-file cannot be combined with {', '.join(legacy_args)}.",
+                fix_hint="Use --views-file as the single batch input, or remove --views-file and use legacy single-app/apps-file mode.",
+            )
+        return context.builder.app_views_apply(
+            profile=args.profile,
+            app_key="",
+            publish=bool(args.publish),
+            upsert_views=[],
+            patch_views=[],
+            remove_views=[],
+            views=views,
+        )
+    apps = load_list_arg(getattr(args, "apps_file", None), option_name="--apps-file")
+    if apps:
+        single_app_args = [a for a in ["--app-key" if args.app_key else None, "--upsert-views-file" if getattr(args, "upsert_views_file", None) else None, "--patch-views-file" if getattr(args, "patch_views_file", None) else None, "--remove-views-file" if getattr(args, "remove_views_file", None) else None] if a]
+        if single_app_args:
+            raise_config_error(
+                f"views apply --apps-file cannot be combined with {', '.join(single_app_args)}.",
+                fix_hint="Use --apps-file for batch mode (each item contains app_key + per-app params), or remove --apps-file for single-app mode.",
+            )
+    if apps:
+        return context.builder.app_views_apply(
+            profile=args.profile,
+            app_key="",
+            publish=bool(args.publish),
+            upsert_views=[],
+            patch_views=[],
+            remove_views=[],
+            apps=apps,
+        )
+    if not args.app_key:
+        raise_config_error("views apply requires --app-key or --apps-file", fix_hint="Pass --app-key for single-app mode, or --apps-file for batch mode.")
     return context.builder.app_views_apply(
         profile=args.profile,
         app_key=args.app_key,
@@ -800,65 +825,79 @@ 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_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_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))
-    selected_modes = sum(1 for selected in (bool(patch_nodes), bool(spec), has_legacy_nodes) if selected)
-    if selected_modes != 1:
+    if patch_nodes and args.spec_file:
         raise_config_error(
-            "builder flow apply requires exactly one input mode: --spec-file, --patch-nodes-file, or --nodes-file with --transitions-file.",
-            fix_hint="Use --patch-nodes-file for local edits, --spec-file for full WorkflowSpec, or legacy --nodes-file plus --transitions-file.",
+            "flow apply --spec-file and --patch-nodes-file are mutually exclusive.",
+            fix_hint="Use --spec-file to replace the full flow spec, or --patch-nodes-file to patch specific nodes.",
         )
     if patch_nodes:
         return context.builder.app_flow_apply(
             profile=args.profile,
             app_key=args.app_key,
             publish=bool(args.publish),
+            spec=None,
             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,
-        )
-    if not getattr(args, "nodes_file", None) or not getattr(args, "transitions_file", None):
-        raise_config_error(
-            "legacy builder flow apply requires both --nodes-file and --transitions-file.",
-            fix_hint="Pass both files, or use --spec-file / --patch-nodes-file.",
+            idempotency_key=args.idempotency_key or None,
+            schema_version=args.schema_version or None,
         )
+    spec_payload = load_object_arg(args.spec_file, option_name="--spec-file") if args.spec_file else None
+    if not isinstance(spec_payload, dict):
+        raise_config_error("flow apply requires either --spec-file or --patch-nodes-file.", fix_hint="Pass --spec-file to replace the full flow spec, or --patch-nodes-file to patch specific nodes.")
+    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,
-        mode=args.mode,
         publish=bool(args.publish),
-        nodes=require_list_arg(args.nodes_file, option_name="--nodes-file"),
-        transitions=require_list_arg(args.transitions_file, option_name="--transitions-file"),
+        spec=spec,
+        idempotency_key=args.idempotency_key or None,
+        schema_version=args.schema_version 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_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")
+    apps = load_list_arg(getattr(args, "apps_file", None), option_name="--apps-file")
+    if apps:
+        single_app_args = [a for a in ["--app-key" if args.app_key else None, "--upsert-file" if getattr(args, "upsert_file", None) else None, "--patch-file" if getattr(args, "patch_file", None) else None, "--remove-chart-ids-file" if getattr(args, "remove_chart_ids_file", None) else None, "--reorder-chart-ids-file" if getattr(args, "reorder_chart_ids_file", None) else None] if a]
+        if single_app_args:
+            raise_config_error(
+                f"charts apply --apps-file cannot be combined with {', '.join(single_app_args)}.",
+                fix_hint="Use --apps-file for batch mode (each item contains app_key + per-app params), or remove --apps-file for single-app mode.",
+            )
+    if apps:
+        return context.builder.app_charts_apply(
+            profile=args.profile,
+            app_key="",
+            upsert_charts=[],
+            patch_charts=[],
+            remove_chart_ids=[],
+            reorder_chart_ids=[],
+            apps=apps,
+        )
+    if not args.app_key:
+        raise_config_error("charts apply requires --app-key or --apps-file", fix_hint="Pass --app-key for single-app mode, or --apps-file for batch mode.")
     return context.builder.app_charts_apply(
         profile=args.profile,
         app_key=args.app_key,
@@ -866,11 +905,30 @@ 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,
     )
 
 
 def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    patch_sections = load_list_arg(getattr(args, "patch_sections_file", None), option_name="--patch-sections-file")
+    if patch_sections:
+        if not (args.dash_key or "").strip():
+            raise_config_error("portal apply --patch-sections-file requires --dash-key", fix_hint="Pass --dash-key DASH_KEY to identify the portal to patch")
+        has_sections_file = bool(getattr(args, "sections_file", None))
+        has_payload_file = bool(getattr(args, "payload_file", None))
+        if has_sections_file or has_payload_file:
+            raise_config_error(
+                "portal apply --patch-sections-file cannot be combined with --sections-file or --payload-file.",
+                fix_hint="Use --patch-sections-file alone to patch specific sections, or --sections-file to replace all sections.",
+            )
+        return context.builder.portal_apply(
+            profile=args.profile,
+            dash_key=args.dash_key,
+            dash_name="",
+            package_id=None,
+            publish=bool(args.publish),
+            sections=[],
+            patch_sections=patch_sections,
+        )
     payload = load_object_arg(args.payload_file, option_name="--payload-file") if getattr(args, "payload_file", None) else None
     payload_obj = payload if isinstance(payload, dict) else {}
     effective_dash_name = (args.dash_name or str(payload_obj.get("dash_name") or payload_obj.get("dashName") or payload_obj.get("name") or "")).strip()
@@ -889,11 +947,6 @@ 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,
@@ -910,28 +963,17 @@ 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,
-    )
-
-
-def _handle_portal_delete(args: argparse.Namespace, context: CliContext) -> dict:
-    return context.builder.portal_delete(
-        profile=args.profile,
-        dash_key=args.dash_key,
     )
 
 
 def _handle_publish_verify(args: argparse.Namespace, context: CliContext) -> dict:
-    app_keys = _app_keys_from_args(args)
-    if app_keys is not None:
+    app_keys = _parse_app_keys_arg(getattr(args, "app_keys", None))
+    if app_keys:
         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,