@qingflow-tech/qingflow-cli 1.1.41 → 1.1.43-beta.1

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -14,6 +14,8 @@ from ..builder_facade.button_style_catalog import (
     BUTTON_STYLE_PRESETS,
     BUTTON_TEXT_COLORS,
 )
+from ..builder_facade.app_form import AppFormReconciler
+from ..builder_facade.app_form_schema import app_form_schema_registry
 from ..public_surface import public_builder_contract_tool_names
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, backend_code_int, backend_code_value_int
@@ -130,10 +132,14 @@ def _inline_form_layout_was_handled(payload: JSONObject) -> bool:
 
 PUBLIC_STABLE_FLOW_NODE_TYPES = ["start", "approve", "fill", "copy", "webhook", "end"]
 BUILDER_APPLY_SCHEMA_VERSION = "builder.apply.v1"
-BUILDER_APPLY_TOOL_NAMES = {
-    "package_apply",
+# TODO(deprecation): Remove these names and their imperative adapters after internal AppForm migration completes.
+LEGACY_IMPERATIVE_APP_FORM_TOOL_NAMES = {
     "app_schema_apply",
     "app_layout_apply",
+}
+BUILDER_APPLY_TOOL_NAMES = {
+    "package_apply",
+    *LEGACY_IMPERATIVE_APP_FORM_TOOL_NAMES,
     "app_flow_apply",
     "app_views_apply",
     "app_custom_buttons_apply",
@@ -161,10 +167,12 @@ class AiBuilderTools(ToolBase):
     def __init__(self, sessions, backend) -> None:
         """执行内部辅助逻辑。"""
         super().__init__(sessions, backend)
+        apps = AppTools(sessions, backend)
+        packages = PackageTools(sessions, backend)
         self._facade = AiBuilderFacade(
-            apps=AppTools(sessions, backend),
+            apps=apps,
             buttons=CustomButtonTools(sessions, backend),
-            packages=PackageTools(sessions, backend),
+            packages=packages,
             views=ViewTools(sessions, backend),
             workflows=WorkflowTools(sessions, backend),
             portals=PortalTools(sessions, backend),
@@ -173,6 +181,11 @@ class AiBuilderTools(ToolBase):
             directory=DirectoryTools(sessions, backend),
             solutions=SolutionTools(sessions, backend),
         )
+        self._app_form = AppFormReconciler(
+            apps=apps,
+            packages=packages,
+            registry=app_form_schema_registry(),
+        )
 
     def _apply_app_batch(self, *, tool_name: str, profile: str, apps: list[JSONObject], apply_one) -> JSONObject:
         started_at = time.perf_counter()
@@ -367,6 +380,41 @@ class AiBuilderTools(ToolBase):
         def builder_tool_contract(tool_name: str = "") -> JSONObject:
             return self.builder_tool_contract(tool_name=tool_name)
 
+        @mcp.tool()
+        def app_form_schema(
+            schema_version: str | None = None,
+            field_type: str | None = None,
+        ) -> JSONObject:
+            return self.app_form_schema(schema_version=schema_version, field_type=field_type)
+
+        @mcp.tool()
+        def app_form_get(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            schema_version: str | None = None,
+            being_draft: bool = False,
+        ) -> JSONObject:
+            return self.app_form_get(
+                profile=profile,
+                app_key=app_key,
+                schema_version=schema_version,
+                being_draft=being_draft,
+            )
+
+        @mcp.tool()
+        def app_form_apply(
+            profile: str = DEFAULT_PROFILE,
+            spec: JSONObject | None = None,
+        ) -> JSONObject:
+            return self.app_form_apply(profile=profile, spec=spec or {})
+
+        @mcp.tool(description=self._high_risk_tool_description(operation="delete", target="app configuration"))
+        def app_delete(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+        ) -> JSONObject:
+            return self.app_delete(profile=profile, app_key=app_key)
+
         @mcp.tool()
         def workspace_icon_catalog_get(profile: str = DEFAULT_PROFILE) -> JSONObject:
             return self.workspace_icon_catalog_get(profile=profile)
@@ -612,98 +660,6 @@ class AiBuilderTools(ToolBase):
         ) -> JSONObject:
             return self.chart_get(profile=profile, chart_id=chart_id)
 
-        @mcp.tool()
-        def app_schema_apply(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            package_id: int | None = None,
-            app_name: str = "",
-            app_title: str = "",
-            icon: str | JSONObject = "",
-            color: str = "",
-            icon_name: str | None = None,
-            icon_color: str | None = None,
-            icon_config: JSONObject | None = None,
-            visibility: JSONObject | None = None,
-            publish: bool = True,
-            form: list[JSONObject] | None = None,
-            add_fields: list[JSONObject] | None = None,
-            update_fields: list[JSONObject] | None = None,
-            remove_fields: list[JSONObject] | None = None,
-            apps: list[JSONObject] | None = None,
-        ) -> JSONObject:
-            if apps is not None:
-                if app_key or app_name or app_title or form or add_fields or update_fields or remove_fields:
-                    return _config_failure(
-                        tool_name="app_schema_apply",
-                        message="app_schema_apply multi-app mode accepts package_id plus apps only.",
-                        fix_hint="Put per-app form in apps[].form when using batch mode.",
-                    )
-                if package_id is None:
-                    return _config_failure(
-                        tool_name="app_schema_apply",
-                        message="app_schema_apply multi-app mode requires package_id.",
-                        fix_hint="Pass package_id and apps[].app_name for new apps, or apps[].app_key for existing apps.",
-                    )
-                return self.app_schema_apply(
-                    profile=profile,
-                    package_id=package_id,
-                    visibility=visibility,
-                    publish=publish,
-                    apps=apps,
-                    form=None,
-                    add_fields=[],
-                    update_fields=[],
-                    remove_fields=[],
-                )
-            has_app_key = bool((app_key or "").strip())
-            has_app_name = bool((app_name or "").strip())
-            has_app_title = bool((app_title or "").strip())
-            has_package_id = package_id is not None
-            if has_app_key:
-                if has_package_id:
-                    return _config_failure(
-                        tool_name="app_schema_apply",
-                        message="app_schema_apply edit mode accepts app_key and optional app_name rename only.",
-                        fix_hint="For existing apps, use `app_key` and optionally `app_name`. For create mode, use `package_id + app_name`.",
-                    )
-            elif not (has_package_id and (has_app_name or has_app_title)):
-                return _config_failure(
-                    tool_name="app_schema_apply",
-                    message="app_schema_apply create mode requires package_id and app_name.",
-                        fix_hint="Use `app_key` for existing apps, or pass `package_id + app_name` to create a new app.",
-                    )
-            return self.app_schema_apply(
-                profile=profile,
-                app_key=app_key,
-                package_id=package_id,
-                app_name=app_name,
-                app_title=app_title,
-                icon=icon,
-                color=color,
-                icon_name=icon_name,
-                icon_color=icon_color,
-                icon_config=icon_config,
-                visibility=visibility,
-                publish=publish,
-                form=form or [],
-                add_fields=add_fields or [],
-                update_fields=update_fields or [],
-                remove_fields=remove_fields or [],
-                apps=None,
-            )
-
-        @mcp.tool()
-        def app_layout_apply(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            mode: str = "merge",
-            publish: bool = True,
-            sections: list[JSONObject] | None = None,
-            apps: list[JSONObject] | None = None,
-        ) -> JSONObject:
-            return self.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [], apps=apps)
-
         @mcp.tool()
         def app_flow_get(
             profile: str = DEFAULT_PROFILE,
@@ -857,6 +813,39 @@ class AiBuilderTools(ToolBase):
                 expected_package_id=expected_package_id,
             )
 
+    def app_form_schema(
+        self,
+        *,
+        schema_version: str | None = None,
+        field_type: str | None = None,
+    ) -> JSONObject:
+        """Return the versioned AppForm summary or one field-type schema."""
+        return self._app_form.schema(schema_version=schema_version, field_type=field_type)
+
+    def app_form_get(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        schema_version: str | None = None,
+        being_draft: bool = False,
+    ) -> JSONObject:
+        """Read a canonical draft or published AppForm resource."""
+        return self._app_form.get(
+            profile=profile,
+            app_key=app_key,
+            schema_version=schema_version,
+            being_draft=being_draft,
+        )
+
+    def app_form_apply(self, *, profile: str, spec: JSONObject) -> JSONObject:
+        """Reconcile one complete declarative AppForm target."""
+        return self._app_form.apply(profile=profile, spec=spec)
+
+    def app_delete(self, *, profile: str, app_key: str) -> JSONObject:
+        """Delete an application explicitly."""
+        return self._app_form.delete(profile=profile, app_key=app_key)
+
     def package_list(self, *, profile: str, trial_status: str = "all", query: str = "") -> JSONObject:
         """执行分组与包相关逻辑。"""
         normalized_args = {"trial_status": trial_status, "query": query}
@@ -2092,7 +2081,7 @@ class AiBuilderTools(ToolBase):
         remove_fields: list[JSONObject],
         apps: list[JSONObject] | None = None,
     ) -> JSONObject:
-        """执行应用相关逻辑。"""
+        """Legacy imperative schema adapter retained only for internal callers pending deletion."""
         icon, color = _normalize_builder_icon_args(
             icon=icon,
             color=color,
@@ -3435,7 +3424,7 @@ class AiBuilderTools(ToolBase):
         sections: list[JSONObject],
         apps: list[JSONObject] | None = None,
     ) -> JSONObject:
-        """执行应用相关逻辑。"""
+        """Legacy imperative layout adapter retained only for internal callers pending deletion."""
         if apps is not None:
             return self._apply_app_batch(
                 tool_name="app_layout_apply",
@@ -7282,6 +7271,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "remove_fields": [],
         },
     },
+    # TODO(deprecation): Retained only for internal imperative adapter validation. This contract
+    # is deliberately excluded from builder_tool_contract and must be deleted with the adapter.
     "app_schema_apply": {
         "allowed_keys": [
             "app_key",
@@ -7638,6 +7629,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "preset_example": {"profile": "default", "app_key": "APP_KEY", "mode": "merge", "preset": "balanced", "sections": []},
     },
+    # TODO(deprecation): Retained only for internal imperative adapter validation. This contract
+    # is deliberately excluded from builder_tool_contract and must be deleted with the adapter.
     "app_layout_apply": {
         "allowed_keys": ["app_key", "mode", "publish", "sections"],
         "aliases": {"overwrite": "replace", "sectionId": "section_id"},
@@ -8172,7 +8165,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_values": {},
         "execution_notes": [
             "returns compact current field configuration for one app",
-            "use this before app_schema_apply when you need exact field definitions",
+            "use app_form_get through the qingflow-app-form Skill for editable form definitions",
             "also returns chart_fields from QingBI datasource fields; app_charts_apply field selectors should use chart_fields because record/schema-visible fields and QingBI fields are not the same schema",
             "chart_fields[].field_id supports field_<queId> selectors, while chart_fields[].bi_field_id is the raw QingBI fieldId accepted by report configs",
             "chart_fields[].chart_apply_examples contains copyable semantic app_charts_apply snippets such as count_by_field, filtered_count, and numeric sum_metric",
@@ -8189,7 +8182,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "allowed_values": {},
         "execution_notes": [
             "returns compact current layout configuration for one app",
-            "use this before app_layout_apply when you need paragraph and row structure",
+            "use app_form_get through the qingflow-app-form Skill for editable form layout",
         ],
         "minimal_example": {
             "profile": "default",

package/src/qingflow_mcp/tools/app_tools.py

@@ -20,8 +20,11 @@ class AppTools(ToolBase):
     类型：应用元数据与配置工具。
     主要职责：
     1. 查询应用列表、读取应用详情；
-    2. 读取与更新应用基础配置、表单结构与发布状态；
-    3. 提供应用创建、删除、发布等管理能力。
+    2. 为声明式 AppForm 和 Solution 编排保留底层应用适配器；
+    3. 仅将应用列表与详情注册为本类的 MCP 入口。
+
+    TODO(deprecation): Remove the imperative app-form adapters after AppForm and Solution
+    no longer call them. They are implementation details and must not be registered as MCP tools.
     """
 
     def register(self, mcp: FastMCP) -> None:
@@ -34,58 +37,6 @@ class AppTools(ToolBase):
         def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
             return self.app_get(profile=profile, app_key=app_key)
 
-        @mcp.tool()
-        def app_get_base(profile: str = DEFAULT_PROFILE, app_key: str = "", include_raw: bool = False) -> JSONObject:
-            return self.app_get_base(profile=profile, app_key=app_key, include_raw=include_raw)
-
-        @mcp.tool(description=self._high_risk_tool_description(operation="update", target="app base settings"))
-        def app_update_base(profile: str = DEFAULT_PROFILE, app_key: str = "", payload: JSONObject | None = None) -> JSONObject:
-            return self.app_update_base(profile=profile, app_key=app_key, payload=payload or {})
-
-        @mcp.tool()
-        def app_get_form_schema(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            form_type: int | str = 1,
-            being_draft: bool | None = None,
-            being_apply: bool | None = None,
-            audit_node_id: int | None = None,
-            include_raw: bool = False,
-        ) -> JSONObject:
-            return self.app_get_form_schema(
-                profile=profile,
-                app_key=app_key,
-                form_type=form_type,
-                being_draft=being_draft,
-                being_apply=being_apply,
-                audit_node_id=audit_node_id,
-                include_raw=include_raw,
-            )
-
-        @mcp.tool()
-        def app_get_edit_version_no(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
-            return self.app_get_edit_version_no(profile=profile, app_key=app_key)
-
-        @mcp.tool()
-        def app_edit_finished(profile: str = DEFAULT_PROFILE, app_key: str = "", payload: JSONObject | None = None) -> JSONObject:
-            return self.app_edit_finished(profile=profile, app_key=app_key, payload=payload or {})
-
-        @mcp.tool()
-        def app_create(profile: str = DEFAULT_PROFILE, payload: JSONObject | None = None) -> JSONObject:
-            return self.app_create(profile=profile, payload=payload or {})
-
-        @mcp.tool(description=self._high_risk_tool_description(operation="delete", target="app configuration"))
-        def app_delete(profile: str = DEFAULT_PROFILE, app_key: str = "") -> JSONObject:
-            return self.app_delete(profile=profile, app_key=app_key)
-
-        @mcp.tool()
-        def app_publish(
-            profile: str = DEFAULT_PROFILE,
-            app_key: str = "",
-            payload: JSONObject | None = None,
-        ) -> JSONObject:
-            return self.app_publish(profile=profile, app_key=app_key, payload=payload or {})
-
     def app_list(self, *, profile: str, query: str = "", keyword: str = "", ship_auth: bool = False) -> JSONObject:
         """List current-user visible apps in the selected workspace."""
         def runner(session_profile, context):
@@ -294,7 +245,7 @@ class AppTools(ToolBase):
         return self._run(profile, runner, tool_name='应用详情')
 
     def app_get_base(self, *, profile: str, app_key: str, include_raw: bool = False) -> JSONObject:
-        """执行应用相关逻辑。"""
+        """Legacy low-level app-form adapter retained for internal callers pending deletion."""
         self._require_app_key(app_key)
 
         def runner(session_profile, context):
@@ -343,7 +294,7 @@ class AppTools(ToolBase):
         return self._run(profile, runner, tool_name='应用基础信息')
 
     def app_update_base(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
-        """执行应用相关逻辑。"""
+        """Legacy low-level app-form adapter retained for internal callers pending deletion."""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
 
@@ -368,7 +319,7 @@ class AppTools(ToolBase):
         audit_node_id: int | None,
         include_raw: bool = False,
     ) -> JSONObject:
-        """执行应用相关逻辑。"""
+        """Legacy low-level app-form adapter retained for internal callers pending deletion."""
         self._require_app_key(app_key)
         resolved_form_type = _normalize_form_type(form_type)
 
@@ -398,7 +349,7 @@ class AppTools(ToolBase):
         return self._run(profile, runner, tool_name='应用表单结构')
 
     def app_get_edit_version_no(self, *, profile: str, app_key: str) -> JSONObject:
-        """执行应用相关逻辑。"""
+        """Legacy low-level app-form adapter retained for internal callers pending deletion."""
         self._require_app_key(app_key)
 
         def runner(session_profile, context):
@@ -446,7 +397,7 @@ class AppTools(ToolBase):
         return self._run(profile, runner, tool_name='更新应用流程配置')
 
     def app_update_form_schema(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
-        """执行应用相关逻辑。"""
+        """Legacy low-level app-form adapter retained for internal callers pending deletion."""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
 
@@ -461,7 +412,7 @@ class AppTools(ToolBase):
         return self._run(profile, runner, tool_name='更新应用表单结构')
 
     def app_edit_finished(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
-        """执行应用相关逻辑。"""
+        """Legacy low-level app-form adapter retained for internal callers pending deletion."""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
 
@@ -471,13 +422,19 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner, tool_name='应用编辑完成')
 
-    def app_create(self, *, profile: str, payload: JSONObject) -> JSONObject:
-        """执行应用相关逻辑。"""
+    def app_create(
+        self,
+        *,
+        profile: str,
+        payload: JSONObject,
+        retry_without_qf_version: bool = True,
+    ) -> JSONObject:
+        """Legacy low-level app-form adapter retained for internal callers pending deletion."""
         body = self._require_dict(payload)
 
         def runner(session_profile, context):
             attempted_contexts = [context]
-            if context.qf_version is not None:
+            if retry_without_qf_version and context.qf_version is not None:
                 attempted_contexts.append(
                     BackendRequestContext(
                         base_url=context.base_url,
@@ -519,7 +476,7 @@ class AppTools(ToolBase):
         return self._run(profile, runner, tool_name='创建应用')
 
     def app_delete(self, *, profile: str, app_key: str) -> JSONObject:
-        """执行应用相关逻辑。"""
+        """Legacy low-level app-form adapter retained for the declarative delete path pending deletion."""
         self._require_app_key(app_key)
 
         def runner(session_profile, context):
@@ -533,7 +490,7 @@ class AppTools(ToolBase):
         return self._run(profile, runner, tool_name='删除应用')
 
     def app_publish(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
-        """执行应用相关逻辑。"""
+        """Legacy low-level app-form adapter retained for internal callers pending deletion."""
         self._require_app_key(app_key)
         body = self._require_dict(payload)
 
@@ -543,6 +500,30 @@ class AppTools(ToolBase):
 
         return self._run(profile, runner, tool_name='发布应用')
 
+    def app_publish_raw(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
+        """Legacy low-level publish adapter retained for internal callers pending deletion."""
+        self._require_app_key(app_key)
+        body = self._require_dict(payload)
+
+        def runner(session_profile, context):
+            response = self.backend.request_with_meta(
+                "POST",
+                context,
+                f"/app/{app_key}/publish",
+                json_body=body,
+                unwrap=False,
+            )
+            return {
+                "profile": profile,
+                "ws_id": session_profile.selected_ws_id,
+                "app_key": app_key,
+                "http_status": response.http_status,
+                "request_id": response.request_id,
+                "response": response.data,
+            }
+
+        return self._run(profile, runner, tool_name='发布应用')
+
     def _require_app_key(self, app_key: str) -> None:
         """执行内部辅助逻辑。"""
         if not app_key:

package/src/qingflow_mcp/tools/base.py

@@ -5,7 +5,7 @@ from contextvars import ContextVar
 from typing import Any, Callable, TypeVar
 
 from ..backend_client import BackendRequestContext, BackendClient
-from ..cloud_context import current_cloud_context
+from ..cloud_context import current_call_platform, current_cloud_context
 from ..config import (
     get_credit_meter_enabled,
     get_credit_usage_base_url,
@@ -323,6 +323,7 @@ class ToolBase:
                 "scene": "MCP",
                 "aiBiz": "MCP",
                 "extraInfo": tool_name,
+                "callPlatform": current_call_platform.get(),
             },
         )
 

package/src/qingflow_mcp/tools/task_context_tools.py

@@ -535,6 +535,10 @@ class TaskContextTools(ToolBase):
                     task_context=task_context,
                     fields=field_updates,
                 )
+            elif normalized_action == "transfer" and body.get("answers") is None:
+                record = task_context.get("record") if isinstance(task_context.get("record"), dict) else {}
+                current_answers = record.get("answers") if isinstance(record.get("answers"), list) else []
+                prepared_fields = {"merged_answers": current_answers}
             before_apply_status = ((task_context.get("record") or {}).get("apply_status"))
             runtime_baseline = None
             if normalized_action != "save_only":
@@ -704,6 +708,8 @@ class TaskContextTools(ToolBase):
                 action_payload["auditFeedback"] = audit_feedback
             if merged_answers is not None:
                 action_payload["answers"] = merged_answers
+            elif payload.get("answers") is not None:
+                action_payload["answers"] = payload["answers"]
             return self._approval_tools.record_transfer(
                 profile=profile,
                 app_key=app_key,