@qingflow-tech/qingflow-cli 1.1.43 → 1.1.44

package/src/qingflow_mcp/server_app_builder.py

@@ -36,15 +36,15 @@ def build_builder_server() -> FastMCP:
             "Use builder_tool_contract when you need a machine-readable contract, aliases, allowed enums, or a minimal valid example for a public builder tool. "
             "Use solution_install when the user explicitly wants to install a packaged solution/template by solution_key, optionally copying bundled demo data. "
             "Use package_list to find visible app packages by keyword and package_get to read package detail before editing; if creating or updating an app package may be appropriate, use package_apply with explicit user intent; otherwise use app_resolve to locate app resources, "
-            "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_get_charts/portal_list/portal_get/view_get/chart_get for focused configuration reads, "
+            "Use workspace_icon_catalog_get before creating app packages or portals when supported icon/color candidates are needed; those resources require explicit non-template icon + color. AppForm-created apps derive a stable default icon and color from spec.appName. "
+            "app_form_schema plus app_form_get for versioned form work; query app_form_schema with schema_kind=formula before writing defaultType=3 formulas, and use being_draft=true only for editing and the published default for relation or record consumers; use app_get as the default non-form 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 compatibility or non-form 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_associated_resources_apply/app_charts_apply/portal_apply/portal_delete to execute normalized patches; app_custom_buttons_apply is maintenance-only for explicit standalone button work outside normal view design. These apply/delete tools perform basic validation, normalization, writes, and readback verification 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, portal delete separates DELETE execution from readback verification, 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_form_apply for complete app form targets, explicit app_delete for application deletion, and app_flow_apply/app_views_apply/app_associated_resources_apply/app_charts_apply/portal_apply/portal_delete for non-form patches. app_custom_buttons_apply is maintenance-only for explicit standalone button work outside normal view design. These apply/delete tools perform validation, normalization, writes, and readback verification where applicable. AppForm publishes only after a draft change or when the published form lags behind; 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, portal delete separates DELETE execution from readback verification, 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 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 builder write/apply results, separate write execution from final readback verification: status=partial_success with write_executed=true and safe_to_retry=false means the write was sent or succeeded, while final readback, publish verification, or metadata confirmation is pending or permission-restricted. Report it as written but unverified; do not repeat the same write blindly. "
-            "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_form_apply, pin the version from app_form_schema, preserve the complete body and existing IDs from a draft get, and configure data display through app-level spec.dataTitleField/spec.dataCoverField selectors rather than booleans on fields; App Builder MCP validates the declaration inside app_form_apply, while the CLI route has a separate static validate command. dataTitleField must resolve to exactly one top-level field for a non-empty body, while dataCoverField is optional and must resolve to a top-level attachment field. A root appKey means update and may include packageId; no appKey means create and requires packageId plus spec.appName. AppForm does not accept spec.icon or spec.color; creation derives a stable default icon and color from spec.appName. "
             "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. View writes use ViewManagementAuth (beingViewManageStatus), falling back to DataManageAuth when advanced app permissions are not enabled. "
             "For ordinary business buttons, declare them on the target view with app_views_apply.views[].action_buttons; app_views_apply writes the view first, then creates/binds the button. Use app_custom_buttons_apply only when the user explicitly asks to maintain existing standalone buttons outside view design, such as custom style/icon changes, cross-view reuse, deleting button bodies, bulk binding reorder, or exact qRobot/wings config. Button body writes require EditAppAuth; view_configs placement writes require ViewManagementAuth, matching the backend viewConfig route. For addData buttons, prefer action_buttons.target_app_key + field_mappings/default_values on the view path; 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; standalone view_configs are only for explicit maintenance. 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; 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. "
@@ -180,6 +180,46 @@ def build_builder_server() -> FastMCP:
     def builder_tool_contract(tool_name: str = "") -> dict:
         return ai_builder.builder_tool_contract(tool_name=tool_name)
 
+    @server.tool()
+    def app_form_schema(
+        schema_version: str | None = None,
+        field_type: str | None = None,
+        schema_kind: str | None = None,
+    ) -> dict:
+        return ai_builder.app_form_schema(
+            schema_version=schema_version,
+            field_type=field_type,
+            schema_kind=schema_kind,
+        )
+
+    @server.tool()
+    def app_form_get(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        schema_version: str | None = None,
+        being_draft: bool = False,
+    ) -> dict:
+        return ai_builder.app_form_get(
+            profile=profile,
+            app_key=app_key,
+            schema_version=schema_version,
+            being_draft=being_draft,
+        )
+
+    @server.tool()
+    def app_form_apply(
+        profile: str = DEFAULT_PROFILE,
+        spec: dict | None = None,
+    ) -> dict:
+        return ai_builder.app_form_apply(profile=profile, spec=spec or {})
+
+    @server.tool(description=ai_builder._high_risk_tool_description(operation="delete", target="app configuration"))
+    def app_delete(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+    ) -> dict:
+        return ai_builder.app_delete(profile=profile, app_key=app_key)
+
     @server.tool()
     def workspace_icon_catalog_get(profile: str = DEFAULT_PROFILE) -> dict:
         return ai_builder.workspace_icon_catalog_get(profile=profile)
@@ -414,89 +454,6 @@ def build_builder_server() -> FastMCP:
     def chart_get(profile: str = DEFAULT_PROFILE, chart_id: str = "") -> dict:
         return ai_builder.chart_get(profile=profile, chart_id=chart_id)
 
-    @server.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 = "",
-        color: str = "",
-        visibility: dict | None = None,
-        publish: bool = True,
-        form: list[dict] | None = None,
-        add_fields: list[dict] | None = None,
-        update_fields: list[dict] | None = None,
-        remove_fields: list[dict] | None = None,
-        apps: list[dict] | None = None,
-    ) -> dict:
-        if apps:
-            if app_key or app_name or app_title or form or add_fields or update_fields or remove_fields:
-                return _config_failure(
-                    "app_schema_apply multi-app mode accepts package_id plus apps only.",
-                    fix_hint="Use apps[].form for batch mode, or use the single-app arguments without apps.",
-                )
-            if package_id is None:
-                return _config_failure(
-                    "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 ai_builder.app_schema_apply(
-                profile=profile,
-                package_id=package_id,
-                visibility=visibility,
-                publish=publish,
-                form=None,
-                add_fields=[],
-                update_fields=[],
-                remove_fields=[],
-                apps=apps,
-            )
-        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
-        create_by_shape = has_package_id and (has_app_name or has_app_title)
-        if has_app_key:
-            if has_package_id:
-                return _config_failure(
-                    "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 create_by_shape:
-            return _config_failure(
-                "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 ai_builder.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,
-            visibility=visibility,
-            publish=publish,
-            form=form or [],
-            add_fields=add_fields or [],
-            update_fields=update_fields or [],
-            remove_fields=remove_fields or [],
-            apps=None,
-        )
-
-    @server.tool()
-    def app_layout_apply(
-        profile: str = DEFAULT_PROFILE,
-        app_key: str = "",
-        mode: str = "merge",
-        publish: bool = True,
-        sections: list[dict] | None = None,
-        apps: list[dict] | None = None,
-    ) -> dict:
-        return ai_builder.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [], apps=apps)
-
     @server.tool()
     def app_flow_get(
         profile: str = DEFAULT_PROFILE,

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,46 @@ 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,
+            schema_kind: str | None = None,
+        ) -> JSONObject:
+            return self.app_form_schema(
+                schema_version=schema_version,
+                field_type=field_type,
+                schema_kind=schema_kind,
+            )
+
+        @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 +665,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 +818,44 @@ class AiBuilderTools(ToolBase):
                 expected_package_id=expected_package_id,
             )
 
+    def app_form_schema(
+        self,
+        *,
+        schema_version: str | None = None,
+        field_type: str | None = None,
+        schema_kind: str | None = None,
+    ) -> JSONObject:
+        """Return a versioned AppForm summary, field, or formula schema."""
+        return self._app_form.schema(
+            schema_version=schema_version,
+            field_type=field_type,
+            schema_kind=schema_kind,
+        )
+
+    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 +2091,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 +3434,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 +7281,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 +7639,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 +8175,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 +8192,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: