@josephyan/qingflow-app-user-mcp 1.1.26 → 1.1.28

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

@@ -295,6 +295,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     schema_apply_apply.add_argument("--add-fields-file", help="字段 JSON 数组；字段可用 as_data_title/as_data_cover 标记数据标题/封面")
     schema_apply_apply.add_argument("--update-fields-file", help="字段更新 JSON 数组；set 内可用 as_data_title/as_data_cover 标记数据标题/封面")
     schema_apply_apply.add_argument("--remove-fields-file")
+    schema_apply_apply.add_argument("--form-file", help='表单布局 JSON 对象，例如 {"sections": [{"title": "基础信息", "rows": [["字段A"]]}]}')
     schema_apply_apply.set_defaults(handler=_handle_schema_apply, format_hint="builder_summary", force_json_output=True)
 
     layout_apply = builder_subparsers.add_parser("layout", help="布局")
@@ -686,7 +687,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
                 "schema apply multi-app mode requires a non-empty --apps-file.",
                 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.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 or args.form_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.",
@@ -737,6 +738,7 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
         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"),
+        form=load_object_arg(args.form_file, option_name="--form-file"),
     )
 
 

package/src/qingflow_mcp/cli/main.py

@@ -12,7 +12,6 @@ from ..tools.ai_builder_tools import _attach_builder_apply_envelope
 from ..version import get_cli_version, get_cli_version_info
 from .context import CliContext, build_cli_context
 from .formatters import emit_json_result, emit_text_result
-from .commands import register_all_commands
 
 
 Handler = Callable[[argparse.Namespace, CliContext], dict[str, Any]]
@@ -32,6 +31,8 @@ class _QingflowArgumentParser(argparse.ArgumentParser):
 
 
 def build_parser() -> argparse.ArgumentParser:
+    from .commands import register_all_commands
+
     parser = _QingflowArgumentParser(prog="qingflow", description="Qingflow CLI")
     parser.add_argument("--profile", default="default", help="会话 profile，默认 default")
     parser.add_argument("--json", action="store_true", help="输出 JSON")
@@ -56,10 +57,10 @@ def run(
 ) -> int:
     out = stdout or sys.stdout
     err = stderr or sys.stderr
-    parser = build_parser()
     normalized_argv = _normalize_global_args(list(argv) if argv is not None else sys.argv[1:])
-    if "--version" in normalized_argv:
+    if _is_version_argv(normalized_argv):
         return _emit_version(json_mode=_should_force_json_output_argv_for_version(normalized_argv), stdout=out)
+    parser = build_parser()
     try:
         args = parser.parse_args(normalized_argv)
     except _CliArgumentError as exc:
@@ -179,6 +180,10 @@ def _should_force_json_output_argv_for_version(argv: list[str]) -> bool:
     return "--json" in argv
 
 
+def _is_version_argv(argv: list[str]) -> bool:
+    return "--version" in argv or [token for token in argv if token != "--json"] == ["version"]
+
+
 def _should_force_json_output(args: argparse.Namespace) -> bool:
     if bool(getattr(args, "force_json_output", False)):
         return True

package/src/qingflow_mcp/server_app_builder.py

@@ -39,14 +39,13 @@ def build_builder_server() -> FastMCP:
             "Use workspace_icon_catalog_get before creating app packages, apps, or portals when supported icon/color candidates are needed; new workspace resources require explicit non-template icon + color, and the CLI validates choices without inferring business defaults. "
             "app_get as the default app map read, then app_get_fields/app_repair_code_blocks/app_get_layout/app_get_views/app_get_flow/app_flow_get/app_flow_get_schema/app_get_charts/portal_list/portal_get/view_get/chart_get for focused configuration reads, "
             "member_search/role_search/role_create when workflow assignees must come from the directory or role catalog, preferring roles over explicit members unless the user explicitly names members, "
-            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_custom_buttons_apply/app_associated_resources_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, app_custom_buttons_apply and app_associated_resources_apply publish after at least one write succeeds and expose no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal sections should use chart for QingBI blocks so portal_apply can inline create/update app-source charts before saving the portal, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, portal pc layout is a 24-column grid and mobile is a 6-column grid so omit position or use layout_preset when unsure, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use publish=false whenever you only want draft/precheck behavior. "
+            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_associated_resources_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. For normal app/system delivery, put new app fields, same-batch relations, and form layout in app_schema_apply apps[].form.sections; use app_layout_apply only for later layout-only maintenance. Schema/layout/views noop requests skip publish, app_associated_resources_apply publishes after at least one write succeeds and exposes no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal sections should use chart for QingBI blocks so portal_apply can inline create/update app-source charts before saving the portal, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, portal pc layout is a 24-column grid and mobile is a 6-column grid so omit position or use layout_preset when unsure, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use publish=false whenever you only want draft/precheck behavior. "
             "Builder apply/write outputs include schema_version, operation, summary, and resources[]; use resources[].id/key/name/ids/parent as the stable UI and agent display entry, and keep legacy fields such as field_diff/views_diff/chart_results only for compatibility or troubleshooting. "
-            "For existing object parameter replacement, prefer patch_views, patch_buttons, patch_resources, and patch_charts with set/unset; the tool reads current config and full-saves internally, while upsert_* is for creation or full target configuration and should not be used as an incomplete partial update. "
+            "For existing object parameter replacement, prefer patch_views, patch_resources, and patch_charts with set/unset; the tool reads current config and full-saves internally, while upsert_* is for creation or full target configuration and should not be used as an incomplete partial update. "
             "For builder delete/remove apply results, separate delete execution from readback verification: after DELETE is sent, resources expose delete_executed, readback_status, and safe_to_retry_delete=false. If readback_status is unavailable or still_exists, do not blindly repeat the delete; confirm later with app_get/view_get/chart_get or the relevant apply readback. Views/buttons use single-item readback; associated resources use one app-level resource-pool readback because there is no confirmed single-item GET. "
-            "For app_schema_apply, configure data title and data cover directly in field JSON with as_data_title=true and as_data_cover=true; data title is required and exactly one field may be marked, while data cover is optional and must be a top-level attachment field. For multi-app creation, pass apps[]/--apps-file on app_schema_apply; each item may have client_key, and relation fields may use target_app_ref to point at another same-call client_key. "
-            "For app_views_apply, keep fixed saved filters in filters and configure the frontend query panel separately with query_conditions; query_conditions.rows is a matrix of field names compiled to backend queryCondition queIds. New views default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless associated_resources is explicitly patched. "
-            "For custom button body create/update/delete and view placement, use app_custom_buttons_apply. For addData buttons, prefer trigger_add_data_config.target_app_key + field_mappings/default_values; do not ask agents to write raw que_relation unless maintaining a legacy config. field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id means current record id (-17), 编号/record_number means visible record number (0). To fill a target relation with the current record, map {'source_field': '数据ID', 'target_field': '目标引用字段'}; default_values is only for static constants. View button bindings merge by default and merge-mode view_configs must include buttons; use view_configs[].mode=replace or explicit buttons=[] only when clearing/replacing existing bindings is intended. Builder view_key arguments are raw keys from app_get.views[].view_key and must not be prefixed with custom:. "
-            "For portal BI blocks, prefer portal_apply sections[].chart so the portal write can inline create/update app-source QingBI charts and attach the resulting chart_id. Use app_charts_apply for advanced standalone report maintenance such as batch edits, deletes, or reordering; chart dimension/metric/filter/query fields must come from app_get_fields.chart_fields, not record schema or form-only fields; dataset BI reports are not created or edited by app_charts_apply yet and should be created in QingBI first, then attached with app_associated_resources_apply using report_source=dataset. "
+            "For app_schema_apply, configure data title and data cover directly in field JSON with as_data_title=true and as_data_cover=true; data title is required and exactly one field may be marked, while data cover is optional and must be a top-level attachment field. For multi-app creation, pass apps[]/--apps-file on app_schema_apply; each item may have client_key and form.sections, and relation fields may use target_app_ref to point at another same-call client_key. "
+            "For app_views_apply, keep fixed saved filters in filters and configure the frontend query panel separately with query_conditions; query_conditions.rows is a matrix of field names compiled to backend queryCondition queIds. If a view needs business actions, declare them directly in action_buttons on that view; field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id means current record id (-17), 编号/record_number means visible record number (0). New views default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless associated_resources is explicitly patched. Builder view_key arguments are raw keys from app_get.views[].view_key and must not be prefixed with custom:. "
+            "For portal BI blocks, prefer portal_apply sections[].chart so the portal write can inline create/update app-source QingBI charts and attach the resulting chart_id; chart dimension/metric/filter/query fields must come from app_get_fields.chart_fields, not record schema or form-only fields. Use app_charts_apply only when the user explicitly asks for standalone chart maintenance such as batch edits, deletes, or reordering; dataset BI reports are not created or edited by app_charts_apply yet and should be created in QingBI first, then attached with app_associated_resources_apply using report_source=dataset. "
             "For associated views/reports, use app_associated_resources_apply. Use match_mappings for filtering associated resources: dynamic current-record conditions use source_field, static conditions use value. match_mappings also supports 数据ID(-17) and 编号(0). Do not ask agents to write raw match_rules unless preserving a legacy backend config. "
             "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, and view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key because the tool resolves those to the internal id. Before creating an associated resource, read app_get.associated_resources and reuse an existing matching target_app_key + view_key/chart_key through patch_resources; client_key only works inside one apply call and is not persisted. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "
             "For code_block fields with output bindings, always use qf_output assignment rather than const/let qf_output, and use app_repair_code_blocks when an existing form hangs because output-bound fields stay loading. "
@@ -418,13 +417,14 @@ def build_builder_server() -> FastMCP:
         add_fields: list[dict] | None = None,
         update_fields: list[dict] | None = None,
         remove_fields: list[dict] | None = None,
+        form: dict | None = None,
         apps: list[dict] | None = None,
     ) -> dict:
         if apps:
-            if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
+            if app_key or app_name or app_title or add_fields or update_fields or remove_fields or form:
                 return _config_failure(
                     "app_schema_apply multi-app mode accepts package_id/create_if_missing plus apps only.",
-                    fix_hint="Use `apps` for batch mode, or use the single-app arguments without `apps`.",
+                    fix_hint="Use `apps[].form` for batch mode, or use the single-app arguments including `form` without `apps`.",
                 )
             if package_id is None:
                 return _config_failure(
@@ -471,6 +471,7 @@ def build_builder_server() -> FastMCP:
             add_fields=add_fields or [],
             update_fields=update_fields or [],
             remove_fields=remove_fields or [],
+            form=form,
             apps=[],
         )