@qingflow-tech/qingflow-app-user-mcp 1.0.43 → 1.1.0

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -27,10 +27,6 @@ from ..builder_facade.models import (
     FieldPatch,
     FieldRemovePatch,
     FieldUpdatePatch,
-    FlowPreset,
-    FlowNodePatch,
-    FlowPlanRequest,
-    FlowTransitionPatch,
     LayoutApplyMode,
     LayoutPlanRequest,
     LayoutPreset,
@@ -70,7 +66,6 @@ from .qingbi_report_tools import QingbiReportTools
 from .role_tools import RoleTools
 from .solution_tools import SolutionTools
 from .view_tools import ViewTools
-from .workflow_tools import WorkflowTools
 
 
 def _normalize_builder_view_key(value: str) -> str:
@@ -80,7 +75,6 @@ def _normalize_builder_view_key(value: str) -> str:
     return raw
 
 
-PUBLIC_STABLE_FLOW_NODE_TYPES = ["start", "approve", "fill", "copy", "webhook", "end"]
 BUILDER_APPLY_SCHEMA_VERSION = "builder.apply.v1"
 BUILDER_APPLY_TOOL_NAMES = {
     "package_apply",
@@ -115,7 +109,6 @@ class AiBuilderTools(ToolBase):
             buttons=CustomButtonTools(sessions, backend),
             packages=PackageTools(sessions, backend),
             views=ViewTools(sessions, backend),
-            workflows=WorkflowTools(sessions, backend),
             portals=PortalTools(sessions, backend),
             charts=QingbiReportTools(sessions, backend),
             roles=RoleTools(sessions, backend),
@@ -455,22 +448,34 @@ class AiBuilderTools(ToolBase):
         ) -> JSONObject:
             return self.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [])
 
+        @mcp.tool()
+        def app_flow_get(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            version_id: str = "",
+        ) -> JSONObject:
+            return self.app_get_flow(profile=profile, app_key=app_key, version_id=version_id or None)
+
+        @mcp.tool()
+        def app_flow_get_schema(profile: str = DEFAULT_PROFILE, schema_version: str = "") -> JSONObject:
+            return self.app_flow_get_schema(profile=profile, schema_version=schema_version or None)
+
         @mcp.tool()
         def app_flow_apply(
             profile: str = DEFAULT_PROFILE,
             app_key: str = "",
-            mode: str = "replace",
             publish: bool = True,
-            nodes: list[JSONObject] | None = None,
-            transitions: list[JSONObject] | None = None,
+            spec: JSONObject | None = None,
+            idempotency_key: str = "",
+            schema_version: str = "",
         ) -> JSONObject:
             return self.app_flow_apply(
                 profile=profile,
                 app_key=app_key,
-                mode=mode,
                 publish=publish,
-                nodes=nodes or [],
-                transitions=transitions or [],
+                spec=spec or {},
+                idempotency_key=idempotency_key or None,
+                schema_version=schema_version or None,
             )
 
         @mcp.tool()
@@ -631,15 +636,16 @@ class AiBuilderTools(ToolBase):
                 "allowed_values": {"tool_name": public_tool_names},
                 "details": {"reason_path": "tool_name"},
                 "suggested_next_call": None,
-            "request_id": None,
-            "backend_code": None,
-            "http_status": None,
-            "noop": False,
-            "warnings": [],
-            "verification": {},
-            "verified": False,
-        }
+                "request_id": None,
+                "backend_code": None,
+                "http_status": None,
+                "noop": False,
+                "warnings": [],
+                "verification": {},
+                "verified": False,
+            }
         contract = _builder_contract_with_apply_output(lookup_name, contract)
+        contract_summary = _builder_tool_contract_summary(lookup_name, contract)
         return {
             "status": "success",
             "error_code": None,
@@ -658,6 +664,8 @@ class AiBuilderTools(ToolBase):
             "verification": {},
             "verified": True,
             "tool_name": requested,
+            "summary": contract_summary,
+            "json_paths": contract_summary["json_paths"],
             "contract": contract,
         }
 
@@ -680,6 +688,12 @@ class AiBuilderTools(ToolBase):
             "color_count": len(catalog["icon_colors"]),
             "warnings": [],
             "verification": {"source": "backend AiBuildConstant ICON_NAMES/ICON_COLORS"},
+            "json_paths": {
+                "icon_names": "$.icon_names",
+                "icon_colors": "$.icon_colors",
+                "generic_icon_names": "$.generic_icon_names",
+                "common_examples": "$.common_examples",
+            },
         }
 
     @tool_cn_name("分组创建")
@@ -1361,26 +1375,25 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_get_views", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
-    @tool_cn_name("应用流程摘要读取")
-    def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
-        """执行应用相关逻辑。"""
-        normalized_args = {"app_key": app_key}
+    @tool_cn_name("Workflow Spec Schema")
+    def app_flow_get_schema(self, *, profile: str, schema_version: str | None = None) -> JSONObject:
+        normalized_args = {"schema_version": schema_version}
         return _safe_tool_call(
-            lambda: self._facade.app_read_flow_summary(profile=profile, app_key=app_key),
-            error_code="FLOW_READ_FAILED",
+            lambda: self._facade.flow_get_schema(profile=profile, schema_version=schema_version),
+            error_code="FLOW_SPEC_SCHEMA_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
+            suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile, **normalized_args}},
         )
 
-    @tool_cn_name("应用流程详情查询")
-    def app_get_flow(self, *, profile: str, app_key: str) -> JSONObject:
+    @tool_cn_name("Workflow Spec 读取")
+    def app_get_flow(self, *, profile: str, app_key: str, version_id: str | None = None) -> JSONObject:
         """执行应用相关逻辑。"""
-        normalized_args = {"app_key": app_key}
+        normalized_args = {"app_key": app_key, "version_id": version_id}
         return _safe_tool_call(
-            lambda: self._facade.app_get_flow(profile=profile, app_key=app_key),
+            lambda: self._facade.flow_get(profile=profile, app_key=app_key, version_id=version_id),
             error_code="APP_GET_FLOW_FAILED",
             normalized_args=normalized_args,
-            suggested_next_call={"tool_name": "app_get_flow", "arguments": {"profile": profile, "app_key": app_key}},
+            suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
         )
 
     @tool_cn_name("应用图表摘要读取")
@@ -1591,52 +1604,6 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_layout_plan", "arguments": {"profile": profile, **normalized_request}},
         )
 
-    @tool_cn_name("应用流程规划")
-    def app_flow_plan(
-        self,
-        *,
-        profile: str,
-        app_key: str,
-        mode: str = "replace",
-        nodes: list[JSONObject] | None = None,
-        transitions: list[JSONObject] | None = None,
-        preset: str | None = None,
-    ) -> JSONObject:
-        """执行应用相关逻辑。"""
-        try:
-            request = FlowPlanRequest.model_validate(
-                {
-                    "app_key": app_key,
-                    "mode": mode,
-                    "nodes": nodes or [],
-                    "transitions": transitions or [],
-                    "preset": preset,
-                }
-            )
-        except ValidationError as exc:
-            return _validation_failure(
-                str(exc),
-                tool_name="app_flow_plan",
-                exc=exc,
-                suggested_next_call={
-                    "tool_name": "app_flow_plan",
-                    "arguments": {
-                        "profile": profile,
-                        "app_key": app_key,
-                        "mode": "replace",
-                        "preset": "basic_approval",
-                        "nodes": [],
-                        "transitions": [],
-                    },
-                },
-            )
-        return _safe_tool_call(
-            lambda: self._facade.app_flow_plan(profile=profile, request=request),
-            error_code="FLOW_PLAN_FAILED",
-            normalized_args=request.model_dump(mode="json"),
-            suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, **request.model_dump(mode="json")}},
-        )
-
     @tool_cn_name("应用视图规划")
     def app_views_plan(
         self,
@@ -2367,111 +2334,51 @@ class AiBuilderTools(ToolBase):
         *,
         profile: str,
         app_key: str,
-        mode: str = "replace",
+        spec: JSONObject,
         publish: bool = True,
-        nodes: list[JSONObject],
-        transitions: list[JSONObject],
+        idempotency_key: str | None = None,
+        schema_version: str | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
-        result = self._app_flow_apply_once(
-            profile=profile,
-            app_key=app_key,
-            mode=mode,
-            publish=publish,
-            nodes=nodes,
-            transitions=transitions,
-        )
-        result = self._retry_after_self_lock_release(
-            profile=profile,
-            result=result,
-            retry_call=lambda: self._app_flow_apply_once(
-                profile=profile,
-                app_key=app_key,
-                mode=mode,
-                publish=publish,
-                nodes=nodes,
-                transitions=transitions,
-            ),
-        )
-        return _attach_builder_apply_envelope("app_flow_apply", result)
-
-    def _app_flow_apply_once(
-        self,
-        *,
-        profile: str,
-        app_key: str,
-        mode: str = "replace",
-        publish: bool = True,
-        nodes: list[JSONObject],
-        transitions: list[JSONObject],
-    ) -> JSONObject:
-        """执行内部辅助逻辑。"""
-        plan_result = self._rewrite_plan_result_for_apply(
-            result=self.app_flow_plan(
-                profile=profile,
-                app_key=app_key,
-                mode=mode,
-                nodes=nodes,
-                transitions=transitions,
-                preset=None,
-            ),
-            profile=profile,
-            publish=publish,
-            plan_tool_name="app_flow_plan",
-            apply_tool_name="app_flow_apply",
-        )
-        if not isinstance(plan_result, dict) or plan_result.get("status") != "success":
-            return plan_result
-        plan_args = plan_result.get("normalized_args")
-        if not isinstance(plan_args, dict):
-            plan_args = {}
-        try:
-            request = FlowPlanRequest.model_validate(
-                {
-                    "app_key": plan_args.get("app_key") or app_key,
-                    "mode": plan_args.get("mode") or mode,
-                    "nodes": plan_args.get("nodes") or [],
-                    "transitions": plan_args.get("transitions") or [],
-                    "preset": None,
-                }
-            )
-        except ValidationError as exc:
-            return _validation_failure(
-                str(exc),
+        if not isinstance(spec, dict) or not spec:
+            return _config_failure(
                 tool_name="app_flow_apply",
-                exc=exc,
-                suggested_next_call={
-                    "tool_name": "app_flow_apply",
-                    "arguments": {
-                        "profile": profile,
-                        "app_key": str(plan_args.get("app_key") or app_key),
-                        "mode": str(plan_args.get("mode") or "replace"),
-                        "publish": publish,
-                        "nodes": plan_args.get("nodes") or [{"id": "start", "type": "start", "name": "发起"}],
-                        "transitions": plan_args.get("transitions") or [],
-                    },
-                },
+                message="app_flow_apply requires a non-empty WorkflowSpecDTO `spec` object.",
+                fix_hint="Call app_flow_get_schema, then app_flow_get for GET-first baseline, patch spec, and apply.",
             )
         normalized_args = {
-            "app_key": request.app_key,
-            "mode": request.mode,
+            "app_key": app_key,
             "publish": publish,
-            "nodes": [node.model_dump(mode="json") for node in request.nodes],
-            "transitions": [transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
+            "spec": spec,
+            "idempotency_key": idempotency_key,
+            "schema_version": schema_version,
         }
-        return _safe_tool_call(
-            lambda: self._facade.app_flow_apply(
+        result = _safe_tool_call(
+            lambda: self._facade.flow_apply(
                 profile=profile,
-                app_key=request.app_key,
-                mode=request.mode,
+                app_key=app_key,
+                spec=spec,
                 publish=publish,
-                nodes=[node.model_dump(mode="json") for node in request.nodes],
-                transitions=[transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
+                idempotency_key=idempotency_key,
+                schema_version=schema_version,
             ),
             error_code="FLOW_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
         )
+        result = self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.flow_apply(
+                profile=profile,
+                app_key=app_key,
+                spec=spec,
+                publish=publish,
+                idempotency_key=idempotency_key,
+                schema_version=schema_version,
+            ),
+        )
+        return _attach_builder_apply_envelope("app_flow_apply", result)
 
     @tool_cn_name("应用视图应用")
     def app_views_apply(
@@ -3927,11 +3834,58 @@ def _builder_contract_with_apply_output(tool_name: str, contract: JSONObject) ->
         "schema_version": BUILDER_APPLY_SCHEMA_VERSION,
         "preferred_ui_fields": ["operation", "summary", "resources"],
         "resource_fields": ["resource_type", "operation", "status", "id", "key", "name", "ids", "parent", "icon_config", "error_code", "message"],
+        "json_paths": _builder_apply_json_paths(),
         "legacy_fields_preserved": True,
     }
     return public
 
 
+def _builder_tool_contract_summary(tool_name: str, contract: JSONObject) -> JSONObject:
+    allowed_values = contract.get("allowed_values") if isinstance(contract, dict) else {}
+    allowed_values_keys = sorted(str(key) for key in allowed_values) if isinstance(allowed_values, dict) else []
+    return {
+        "tool_name": tool_name,
+        "contract_path": "$.contract",
+        "allowed_keys_path": "$.contract.allowed_keys",
+        "allowed_values_path": "$.contract.allowed_values",
+        "allowed_values_key_style": "flat_dotted_keys",
+        "minimal_example_path": "$.contract.minimal_example",
+        "execution_notes_path": "$.contract.execution_notes",
+        "top_level_allowed_values_usage": "empty on successful contract lookup; use $.contract.allowed_values instead",
+        "allowed_values_keys_sample": allowed_values_keys[:12],
+        "json_paths": {
+            "contract": "$.contract",
+            "allowed_keys": "$.contract.allowed_keys",
+            "allowed_values": "$.contract.allowed_values",
+            "minimal_example": "$.contract.minimal_example",
+            "execution_notes": "$.contract.execution_notes",
+            "aliases": "$.contract.aliases",
+        },
+    }
+
+
+def _builder_apply_json_paths() -> JSONObject:
+    return {
+        "status": "$.status",
+        "schema_version": "$.schema_version",
+        "operation": "$.operation",
+        "summary": "$.summary",
+        "resources": "$.resources",
+        "warnings": "$.warnings",
+        "verification": "$.verification",
+        "details": "$.details",
+        "write_executed": "$.write_executed",
+        "write_may_have_succeeded": "$.write_may_have_succeeded",
+        "safe_to_retry": "$.safe_to_retry",
+        "next_action": "$.next_action",
+        "summary_write_executed": "$.summary.write_executed",
+        "summary_safe_to_retry": "$.summary.safe_to_retry",
+        "resource_keys": "$.resources[].key",
+        "resource_ids": "$.resources[].id",
+        "resource_statuses": "$.resources[].status",
+    }
+
+
 def _attach_builder_apply_envelope(tool_name: str, payload: JSONObject) -> JSONObject:
     if not isinstance(payload, dict):
         return payload
@@ -3940,6 +3894,7 @@ def _attach_builder_apply_envelope(tool_name: str, payload: JSONObject) -> JSONO
     payload["operation"] = tool_name
     payload["resources"] = resources
     payload["summary"] = _builder_apply_summary(payload, resources)
+    payload["json_paths"] = _builder_apply_json_paths()
     return payload
 
 
@@ -5748,92 +5703,56 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "sections": [{"type": "paragraph", "paragraph_id": "basic", "title": "基础信息", "rows": [["项目名称", "项目负责人", "项目阶段", "优先级"]]}],
         },
     },
-    "app_flow_plan": {
-        "allowed_keys": ["app_key", "mode", "nodes", "transitions", "preset"],
-        "aliases": {
-            "overwrite": "replace",
-            "base_preset": "preset",
-            "default_approval": "basic_approval",
-            "node.role_names": "node.assignees.role_names",
-            "node.role_ids": "node.assignees.role_ids",
-            "node.member_names": "node.assignees.member_names",
-            "node.member_emails": "node.assignees.member_emails",
-            "node.member_uids": "node.assignees.member_uids",
-            "node.editable_fields": "node.permissions.editable_fields",
-            "default_approval": "basic_approval",
-        },
-        "allowed_values": {
-            "mode": ["replace"],
-            "preset": [member.value for member in FlowPreset],
-            "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
-        },
-        "dependency_hints": [
-            "approval-style workflows require an explicit status field",
-            "approve/fill/copy nodes require at least one assignee",
+    "app_flow_get_schema": {
+        "allowed_keys": ["schema_version"],
+        "aliases": {"schemaVersion": "schema_version"},
+        "allowed_values": {},
+        "execution_notes": [
+            "returns WorkflowSpec JSON Schema from /workflow/spec/schema",
+            "call this before authoring a new spec or validating spec shape",
+            "worksheet-level approval deduplication toggles (legacy global settings) are not yet part of WorkflowSpec",
         ],
+        "minimal_example": {
+            "profile": "default",
+            "schema_version": "vnext-2026-06",
+        },
+    },
+    "app_flow_get": {
+        "allowed_keys": ["app_key", "version_id"],
+        "aliases": {"versionId": "version_id"},
+        "allowed_values": {},
         "execution_notes": [
-            "public flow building is intentionally limited to linear workflows",
-            "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
+            "returns current WorkflowSpecDTO for one app via GET /workflow/spec",
+            "use GET-first before patching and app_flow_apply",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "mode": "replace",
-            "preset": "basic_approval",
-            "nodes": [
-                {
-                    "id": "approve_1",
-                    "type": "approve",
-                    "name": "部门审批",
-                    "assignees": {"role_names": ["项目经理"]},
-                    "permissions": {"editable_fields": ["状态", "审批意见"]},
-                }
-            ],
-            "transitions": [],
         },
     },
     "app_flow_apply": {
-        "allowed_keys": ["app_key", "mode", "publish", "nodes", "transitions"],
+        "allowed_keys": ["app_key", "publish", "spec", "idempotency_key", "schema_version"],
         "aliases": {
-            "overwrite": "replace",
-            "node.role_names": "node.assignees.role_names",
-            "node.role_ids": "node.assignees.role_ids",
-            "node.member_names": "node.assignees.member_names",
-            "node.member_emails": "node.assignees.member_emails",
-            "node.member_uids": "node.assignees.member_uids",
-            "node.editable_fields": "node.permissions.editable_fields",
-        },
-        "allowed_values": {
-            "mode": ["replace"],
-            "node.type": PUBLIC_STABLE_FLOW_NODE_TYPES,
+            "schemaVersion": "schema_version",
+            "idempotencyKey": "idempotency_key",
         },
+        "allowed_values": {},
         "dependency_hints": [
-            "approval-style workflows require an explicit status field",
-            "approve/fill/copy nodes require at least one assignee",
+            "spec must be a complete WorkflowSpecDTO object (replace-only apply)",
         ],
         "execution_notes": [
-            "public flow building is intentionally limited to linear workflows",
-            "app_flow_apply is replace-only; do not treat node snippets as partial patches",
-            "branch and condition nodes are disabled because the backend workflow route is not front-end stable for these node types",
-            "workflow verification only covers linear node structure in the public tool surface",
+            "posts to /workflow/spec:apply with appKey, idempotencyKey, schemaVersion, and spec",
+            "verification uses appliedSpec, diffSummary, and semanticLint from the apply response",
+            "publish=false keeps changes in draft when supported by the backend",
         ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
-            "mode": "replace",
             "publish": True,
-            "nodes": [
-                {"id": "start", "type": "start", "name": "发起"},
-                {
-                    "id": "approve_1",
-                    "type": "approve",
-                    "name": "部门审批",
-                    "assignees": {"role_names": ["项目经理"]},
-                    "permissions": {"editable_fields": ["状态", "审批意见"]},
-                },
-                {"id": "end", "type": "end", "name": "结束"},
-            ],
-            "transitions": [{"from": "start", "to": "approve_1"}, {"from": "approve_1", "to": "end"}],
+            "spec": {
+                "nodes": [{"id": "n1", "type": "APPLICANT", "name": "发起"}],
+                "transitions": [],
+            },
         },
     },
     "app_views_plan": {
@@ -5894,7 +5813,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "creating a new view follows backend createViewgraphConfig and requires both ViewManagementAuth and DataManageAuth; updating/deleting existing views only requires ViewManagementAuth",
             "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
-            "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
+            "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
+            "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
             "use patch_views for partial parameter replacement on existing views; the tool reads current config, merges patch_views[].set/unset, then submits the backend full-save payload internally",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
@@ -5945,6 +5865,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             ],
             "remove_views": [],
         },
+        "query_conditions_field_rules": {
+            "supported_field_types": ["text", "long_text", "number", "amount", "date", "datetime", "single_select", "multi_select", "phone", "email", "boolean", "member", "department"],
+            "unsupported_field_types": ["relation", "attachment", "subtable", "address", "code_block", "q_linker"],
+            "use_instead": {
+                "fixed_filter": "filters",
+                "current_record_related_report_or_view": "app_associated_resources_apply.match_mappings",
+            },
+        },
         "gantt_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -6024,7 +5952,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "buttons omitted preserves existing button config; buttons=[] clears all buttons; buttons=[...] replaces the full button config",
             "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
-            "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
+            "upsert_views[].query_conditions.rows is a layout matrix of query-panel supported field names; it is compiled to backend queryCondition queIds",
+            "do not put relation/attachment/subtable/code_block/q_linker/address fields in query_conditions; use filters for fixed filters or app_associated_resources_apply.match_mappings for current-record relation/report matching",
             "use patch_views for partial parameter replacement on existing views; the public update mode is patch even though the backend save is still a full view payload",
             "remove_views accepts a raw view_key or an exact unique view name; after DELETE the tool verifies deletion by single view_key readback, not by a full app view list",
             "deleted views return verification.by_view[].delete_executed, readback_status, and safe_to_retry_delete=false; if readback is pending, do not blindly repeat the delete",
@@ -6078,6 +6007,14 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             ],
             "remove_views": [],
         },
+        "query_conditions_field_rules": {
+            "supported_field_types": ["text", "long_text", "number", "amount", "date", "datetime", "single_select", "multi_select", "phone", "email", "boolean", "member", "department"],
+            "unsupported_field_types": ["relation", "attachment", "subtable", "address", "code_block", "q_linker"],
+            "use_instead": {
+                "fixed_filter": "filters",
+                "current_record_related_report_or_view": "app_associated_resources_apply.match_mappings",
+            },
+        },
         "gantt_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -6165,8 +6102,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "aliases": {},
         "allowed_values": {},
         "execution_notes": [
-            "returns workflow configuration summary for one app",
-            "use this before app_flow_apply when you need the current node structure",
+            "returns WorkflowSpecDTO for one app (alias of app_flow_get)",
+            "use app_flow_get_schema then app_flow_get before app_flow_apply",
         ],
         "minimal_example": {
             "profile": "default",
@@ -6472,7 +6409,6 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
 _PRIVATE_BUILDER_TOOL_CONTRACTS = {
     "app_schema_plan",
     "app_layout_plan",
-    "app_flow_plan",
     "app_views_plan",
 }