@qingflow-tech/qingflow-app-builder-mcp 1.0.7 → 1.0.9

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

@@ -126,6 +126,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     button_apply = button_subparsers.add_parser("apply", help="声明式创建、更新或删除自定义按钮")
     button_apply.add_argument("--app-key", required=True)
     button_apply.add_argument("--upsert-buttons-file")
+    button_apply.add_argument("--patch-buttons-file")
     button_apply.add_argument("--remove-buttons-file")
     button_apply.add_argument("--view-configs-file")
     button_apply.set_defaults(handler=_handle_button_apply, format_hint="builder_summary")
@@ -135,6 +136,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     associated_resource_apply = associated_resource_subparsers.add_parser("apply", help="声明式管理应用关联资源池和视图展示配置")
     associated_resource_apply.add_argument("--app-key", required=True)
     associated_resource_apply.add_argument("--upsert-resources-file")
+    associated_resource_apply.add_argument("--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")
@@ -197,6 +199,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     views_apply_apply.add_argument("--app-key", required=True)
     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")
 
@@ -215,6 +218,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     charts_apply_apply = charts_apply_subparsers.add_parser("apply", help="执行报表变更")
     charts_apply_apply.add_argument("--app-key", required=True)
     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.set_defaults(handler=_handle_charts_apply, format_hint="builder_summary")
@@ -366,6 +370,7 @@ def _handle_button_apply(args: argparse.Namespace, context: CliContext) -> dict:
         profile=args.profile,
         app_key=args.app_key,
         upsert_buttons=load_list_arg(args.upsert_buttons_file, option_name="--upsert-buttons-file"),
+        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"),
     )
@@ -376,6 +381,7 @@ def _handle_associated_resource_apply(args: argparse.Namespace, context: CliCont
         profile=args.profile,
         app_key=args.app_key,
         upsert_resources=load_list_arg(args.upsert_resources_file, option_name="--upsert-resources-file"),
+        patch_resources=load_list_arg(args.patch_resources_file, option_name="--patch-resources-file"),
         remove_associated_item_ids=load_list_arg(args.remove_associated_item_ids_file, option_name="--remove-associated-item-ids-file"),
         reorder_associated_item_ids=load_list_arg(args.reorder_associated_item_ids_file, option_name="--reorder-associated-item-ids-file"),
         view_configs=load_list_arg(args.view_configs_file, option_name="--view-configs-file"),
@@ -494,6 +500,7 @@ def _handle_views_apply(args: argparse.Namespace, context: CliContext) -> dict:
         app_key=args.app_key,
         publish=bool(args.publish),
         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"),
     )
 
@@ -514,6 +521,7 @@ def _handle_charts_apply(args: argparse.Namespace, context: CliContext) -> dict:
         profile=args.profile,
         app_key=args.app_key,
         upsert_charts=load_list_arg(args.upsert_file, option_name="--upsert-file"),
+        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"),
     )

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

@@ -13,7 +13,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     record_subparsers = parser.add_subparsers(
         dest="record_command",
         required=True,
-        metavar="{schema,list,access,get,insert,update,delete,code-block-run}",
+        metavar="{schema,list,access,get,insert,update,delete,member-candidates,department-candidates,code-block-run}",
     )
 
     schema = record_subparsers.add_parser("schema", help="读取记录相关表结构")
@@ -47,6 +47,28 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     schema_code_block.add_argument("--app-key", required=True)
     schema_code_block.set_defaults(handler=_handle_schema_code_block, format_hint="")
 
+    member_candidates = record_subparsers.add_parser("member-candidates", help="读取成员字段候选项")
+    member_candidates.add_argument("--app-key", required=True)
+    member_candidates.add_argument("--field-id", type=int, required=True)
+    member_candidates.add_argument("--keyword", default="")
+    member_candidates.add_argument("--page-num", type=int, default=1)
+    member_candidates.add_argument("--page-size", type=int, default=20)
+    member_candidates.add_argument("--record-id")
+    member_candidates.add_argument("--workflow-node-id", type=int)
+    member_candidates.add_argument("--fields-file")
+    member_candidates.set_defaults(handler=_handle_member_candidates, format_hint="")
+
+    department_candidates = record_subparsers.add_parser("department-candidates", help="读取部门字段候选项")
+    department_candidates.add_argument("--app-key", required=True)
+    department_candidates.add_argument("--field-id", type=int, required=True)
+    department_candidates.add_argument("--keyword", default="")
+    department_candidates.add_argument("--page-num", type=int, default=1)
+    department_candidates.add_argument("--page-size", type=int, default=20)
+    department_candidates.add_argument("--record-id")
+    department_candidates.add_argument("--workflow-node-id", type=int)
+    department_candidates.add_argument("--fields-file")
+    department_candidates.set_defaults(handler=_handle_department_candidates, format_hint="")
+
     list_parser = record_subparsers.add_parser("list", help="列出记录")
     list_parser.add_argument("--app-key", required=True)
     list_parser.add_argument("--column", dest="columns", action="append", type=int, default=[])
@@ -207,6 +229,38 @@ def _handle_schema_code_block(args: argparse.Namespace, context: CliContext) ->
     return context.code_block.record_code_block_schema_get_public(profile=args.profile, app_key=args.app_key)
 
 
+def _candidate_context_fields(args: argparse.Namespace) -> dict[str, Any]:
+    return load_object_arg(args.fields_file, option_name="--fields-file") or {}
+
+
+def _handle_member_candidates(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_member_candidates(
+        profile=args.profile,
+        app_key=args.app_key,
+        field_id=args.field_id,
+        record_id=args.record_id,
+        workflow_node_id=args.workflow_node_id,
+        fields=_candidate_context_fields(args),
+        keyword=args.keyword,
+        page_num=args.page_num,
+        page_size=args.page_size,
+    )
+
+
+def _handle_department_candidates(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_department_candidates(
+        profile=args.profile,
+        app_key=args.app_key,
+        field_id=args.field_id,
+        record_id=args.record_id,
+        workflow_node_id=args.workflow_node_id,
+        fields=_candidate_context_fields(args),
+        keyword=args.keyword,
+        page_num=args.page_num,
+        page_size=args.page_size,
+    )
+
+
 def _validate_public_view_selector(
     *,
     view_id: str | None,

package/src/qingflow_mcp/public_surface.py

@@ -78,8 +78,8 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
         ("record_code_block_schema_get_public",),
         ("record", "schema", "code-block"),
     ),
-    PublicToolSpec(USER_DOMAIN, "record_member_candidates", ("record_member_candidates",), cli_public=False),
-    PublicToolSpec(USER_DOMAIN, "record_department_candidates", ("record_department_candidates",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "record_member_candidates", ("record_member_candidates",), ("record", "member-candidates")),
+    PublicToolSpec(USER_DOMAIN, "record_department_candidates", ("record_department_candidates",), ("record", "department-candidates")),
     PublicToolSpec(USER_DOMAIN, "record_analyze", ("record_analyze",), ("record", "analyze"), mcp_public=False),
     PublicToolSpec(USER_DOMAIN, "record_list", ("record_list",), ("record", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_access", ("record_access",), ("record", "access"), cli_show_effective_context=True),

package/src/qingflow_mcp/response_trim.py

@@ -91,7 +91,12 @@ def trim_error_response(payload: dict[str, Any]) -> dict[str, Any]:
     _drop_deep_keys(trimmed.get("details"), {"request_route", "base_url", "normalized_args", "suggested_next_call", "transport", "response", "body", "raw"})
     details = trimmed.get("details")
     if isinstance(details, dict):
+        preserved = {}
+        for key in ("blocking_issues", "compiled_match_rules"):
+            if key in details:
+                preserved[key] = details.get(key)
         compact_details = _compact_scalar_dict(details)
+        compact_details.update(preserved)
         if compact_details:
             trimmed["details"] = compact_details
         else:
@@ -156,7 +161,12 @@ def _trim_returned_failure(payload: dict[str, Any]) -> dict[str, Any]:
     _drop_deep_keys(trimmed.get("details"), {"request_route", "base_url", "normalized_args", "suggested_next_call", "transport", "response", "body", "raw"})
     details = trimmed.get("details")
     if isinstance(details, dict):
+        preserved = {}
+        for key in ("blocking_issues", "compiled_match_rules"):
+            if key in details:
+                preserved[key] = details.get(key)
         compact_details = _compact_scalar_dict(details)
+        compact_details.update(preserved)
         if compact_details:
             trimmed["details"] = compact_details
         else:
@@ -944,7 +954,11 @@ def _trim_builder_envelope(payload: JSONObject) -> None:
         details = payload.get("details")
         if isinstance(details, dict):
             _drop_deep_keys(details, {"request_route", "base_url", "normalized_args", "suggested_next_call", "transport", "response", "body", "raw"})
+            preserved = {}
+            if isinstance(details.get("compiled_match_rules"), dict):
+                preserved["compiled_match_rules"] = details.get("compiled_match_rules")
             compact = _compact_scalar_dict(details)
+            compact.update(preserved)
             if compact:
                 payload["details"] = compact
             else:

package/src/qingflow_mcp/server.py

@@ -131,6 +131,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 - Read relation targets from `record_insert_schema_get` / `record_update_schema_get` relation metadata before preparing relation writes.
 - Member, department, and relation fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to candidate tools when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- CLI-only agents can use `qingflow record member-candidates --app-key APP_KEY --field-id FIELD_ID --keyword NAME --json` or `qingflow record department-candidates --app-key APP_KEY --field-id FIELD_ID --keyword DEPT --json` for that fallback; pass `--record-id`, `--workflow-node-id`, and `--fields-file` only when the candidate scope must match an existing runtime context.
 - For batch insert `partial_success`, read `created_record_ids`, failed `items[].row_number`, and `failed_fields`; repair only failed rows and never retry the whole batch after any row has `write_executed=true`.
 - If explicit candidate browsing is needed for default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 

package/src/qingflow_mcp/server_app_builder.py

@@ -39,10 +39,13 @@ def build_builder_server() -> FastMCP:
             "app_get as the default app map read, then app_get_fields/app_repair_code_blocks/app_get_layout/app_get_views/app_get_flow/app_get_charts/portal_list/portal_get/view_get/chart_get for focused configuration reads, "
             "member_search/role_search/role_create when workflow assignees must come from the directory or role catalog, preferring roles over explicit members unless the user explicitly names members, "
             "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_custom_buttons_apply/app_associated_resources_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, app_custom_buttons_apply and app_associated_resources_apply publish after at least one write succeeds and expose no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use publish=false whenever you only want draft/precheck behavior. "
+            "For existing object parameter replacement, prefer patch_views, patch_buttons, patch_resources, and patch_charts with set/unset; the tool reads current config and full-saves internally, while upsert_* is for creation or full target configuration and should not be used as an incomplete partial update. "
             "For app_schema_apply, configure data title and data cover directly in field JSON with as_data_title=true and as_data_cover=true; data title is required and exactly one field may be marked, while data cover is optional and must be a top-level attachment field. "
             "For app_views_apply, keep fixed saved filters in filters and configure the frontend query panel separately with query_conditions; query_conditions.rows is a matrix of field names compiled to backend queryCondition queIds. "
-            "For custom button body create/update/delete and view placement, use app_custom_buttons_apply. For addData buttons, prefer trigger_add_data_config.target_app_key + field_mappings/default_values; do not ask agents to write raw que_relation unless maintaining a legacy config. View button bindings merge by default and merge-mode view_configs must include buttons; use view_configs[].mode=replace or explicit buttons=[] only when clearing/replacing existing bindings is intended. "
-            "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, not chart_id/chart_key. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "
+            "For custom button body create/update/delete and view placement, use app_custom_buttons_apply. For addData buttons, prefer trigger_add_data_config.target_app_key + field_mappings/default_values; do not ask agents to write raw que_relation unless maintaining a legacy config. field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id means current record id (-17), 编号/record_number means visible record number (0). To fill a target relation with the current record, map {'source_field': '数据ID', 'target_field': '目标引用字段'}; default_values is only for static constants. View button bindings merge by default and merge-mode view_configs must include buttons; use view_configs[].mode=replace or explicit buttons=[] only when clearing/replacing existing bindings is intended. Builder view_key arguments are raw keys from app_get.views[].view_key and must not be prefixed with custom:. "
+            "For BI reports, keep report-body development separate from Qingflow in-app display: use app_charts_apply to create, update, remove, or reorder app-source QingBI chart bodies/configs with dataSourceType=qingflow; dataset BI reports are not created or edited by app_charts_apply yet and should be created in QingBI first, then attached with app_associated_resources_apply using report_source=dataset. "
+            "For associated views/reports, use app_associated_resources_apply. Use match_mappings for filtering associated resources: dynamic current-record conditions use source_field, static conditions use value. match_mappings also supports 数据ID(-17) and 编号(0). Do not ask agents to write raw match_rules unless preserving a legacy backend config. "
+            "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. "
             "Use package_apply to manage package metadata, visibility, grouping, and ordering, and app_publish_verify for explicit final publish verification. "
             "For workflow edits, keep the public builder surface on stable linear flows only: start/approve/fill/copy/webhook/end. Branch and condition nodes are intentionally disabled because the backend workflow route is not front-end stable for those node types. Declare node assignees and editable fields explicitly. "
@@ -303,6 +306,7 @@ def build_builder_server() -> FastMCP:
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
         upsert_buttons: list[dict] | None = None,
+        patch_buttons: list[dict] | None = None,
         remove_buttons: list[dict] | None = None,
         view_configs: list[dict] | None = None,
     ) -> dict:
@@ -310,6 +314,7 @@ def build_builder_server() -> FastMCP:
             profile=profile,
             app_key=app_key,
             upsert_buttons=upsert_buttons or [],
+            patch_buttons=patch_buttons or [],
             remove_buttons=remove_buttons or [],
             view_configs=view_configs or [],
         )
@@ -319,6 +324,7 @@ def build_builder_server() -> FastMCP:
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
         upsert_resources: list[dict] | None = None,
+        patch_resources: list[dict] | None = None,
         remove_associated_item_ids: list[int] | None = None,
         reorder_associated_item_ids: list[int] | None = None,
         view_configs: list[dict] | None = None,
@@ -327,6 +333,7 @@ def build_builder_server() -> FastMCP:
             profile=profile,
             app_key=app_key,
             upsert_resources=upsert_resources or [],
+            patch_resources=patch_resources or [],
             remove_associated_item_ids=remove_associated_item_ids or [],
             reorder_associated_item_ids=reorder_associated_item_ids or [],
             view_configs=view_configs or [],
@@ -466,6 +473,7 @@ def build_builder_server() -> FastMCP:
         app_key: str = "",
         publish: bool = True,
         upsert_views: list[dict] | None = None,
+        patch_views: list[dict] | None = None,
         remove_views: list[str] | None = None,
     ) -> dict:
         return ai_builder.app_views_apply(
@@ -473,6 +481,7 @@ def build_builder_server() -> FastMCP:
             app_key=app_key,
             publish=publish,
             upsert_views=upsert_views or [],
+            patch_views=patch_views or [],
             remove_views=remove_views or [],
         )
 
@@ -481,6 +490,7 @@ def build_builder_server() -> FastMCP:
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
         upsert_charts: list[dict] | None = None,
+        patch_charts: list[dict] | None = None,
         remove_chart_ids: list[str] | None = None,
         reorder_chart_ids: list[str] | None = None,
     ) -> dict:
@@ -488,6 +498,7 @@ def build_builder_server() -> FastMCP:
             profile=profile,
             app_key=app_key,
             upsert_charts=upsert_charts or [],
+            patch_charts=patch_charts or [],
             remove_chart_ids=remove_chart_ids or [],
             reorder_chart_ids=reorder_chart_ids or [],
         )

package/src/qingflow_mcp/server_app_user.py

@@ -132,6 +132,7 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 - Read relation targets from `record_insert_schema_get` / `record_update_schema_get` relation metadata before preparing relation writes.
 - Member, department, and relation fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to candidate tools when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- CLI-only agents can use `qingflow record member-candidates --app-key APP_KEY --field-id FIELD_ID --keyword NAME --json` or `qingflow record department-candidates --app-key APP_KEY --field-id FIELD_ID --keyword DEPT --json` for that fallback.
 - For batch insert `partial_success`, read `created_record_ids`, failed `items[].row_number`, and `failed_fields`; repair only failed rows and never retry the whole batch after any row has `write_executed=true`.
 - When candidate browsing must match a real update/write scope, pass `record_id`, `workflow_node_id`, and any pending `fields` context to the candidate tool; otherwise the candidate result is only a static applicant-node preview.
 - If explicit candidate browsing is needed for default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.