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

package/src/qingflow_mcp/server_app_builder.py

@@ -37,14 +37,14 @@ def build_builder_server() -> FastMCP:
             "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, "
+            "app_form_schema plus app_form_get for versioned form work, using 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, validate the JSON declaration with the qingflow-app-form Skill command, preserve the complete body and existing IDs from a draft get, and use dataTitle/dataCover on canonical fields; exactly one top-level dataTitle is required for a non-empty body, while dataCover is optional and must be a top-level attachment field. A root appKey means update and may include packageId; no appKey means create and requires packageId plus spec.appName, spec.icon, and spec.color selected from workspace_icon_catalog_get, with template forbidden. "
             "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,41 @@ 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,
+    ) -> dict:
+        return ai_builder.app_form_schema(schema_version=schema_version, field_type=field_type)
+
+    @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 +449,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/server_cloud.py

@@ -24,6 +24,7 @@ from .server_app_user import build_user_server
 
 
 BUILDER_TOOL_PREFIX = "builder_"
+MAX_OAUTH_PROXY_BODY_BYTES = 64 * 1024
 
 
 ASGIApp = Callable[
@@ -88,6 +89,15 @@ class CloudMcpAuthApp:
                     backend_metadata_path,
                 )
                 return
+            backend_oauth_path = self._oauth_proxy.config.backend_oauth_endpoint_path(path)
+            if backend_oauth_path is not None:
+                await self._proxy_oauth_endpoint(
+                    scope,
+                    receive,
+                    send,
+                    backend_oauth_path,
+                )
+                return
 
         auth_value, explicit_credential, call_platform = self._extract_auth_value(scope)
         if auth_value is None:
@@ -196,7 +206,8 @@ class CloudMcpAuthApp:
     ) -> None:
         assert self._oauth_proxy is not None
         challenge = (
-            f'Bearer error="{_escape_auth_param(error)}", '
+            'Bearer realm="OAuth", '
+            f'error="{_escape_auth_param(error)}", '
             f'error_description="{_escape_auth_param(description)}", '
             f'resource_metadata="{self._oauth_proxy.config.resource_metadata_url}"'
         )
@@ -234,6 +245,44 @@ class CloudMcpAuthApp:
             return
         await self._raw_response(send, response)
 
+    async def _proxy_oauth_endpoint(
+        self,
+        scope: dict[str, Any],
+        receive: Callable[[], Awaitable[dict[str, Any]]],
+        send: Callable[[dict[str, Any]], Awaitable[None]],
+        backend_path: str,
+    ) -> None:
+        assert self._oauth_proxy is not None
+        try:
+            body = await _read_request_body(receive, MAX_OAUTH_PROXY_BODY_BYTES)
+        except ValueError:
+            await self._json_response(
+                send,
+                413,
+                {
+                    "error": "invalid_request",
+                    "error_description": "OAuth request body is too large",
+                },
+            )
+            return
+        try:
+            response = await anyio.to_thread.run_sync(
+                self._oauth_proxy.request_oauth_endpoint,
+                str(scope.get("method") or "GET"),
+                backend_path,
+                bytes(scope.get("query_string") or b""),
+                body,
+                tuple(scope.get("headers") or ()),
+            )
+        except QingflowApiError as error:
+            await self._json_response(
+                send,
+                502,
+                {"error": "oauth_service_unavailable", "message": error.message},
+            )
+            return
+        await self._raw_response(send, response)
+
     async def _json_response(
         self,
         send: Callable[[dict[str, Any]], Awaitable[None]],
@@ -385,6 +434,22 @@ def _extract_host(scope: dict[str, Any]) -> str:
     return ""
 
 
+async def _read_request_body(
+    receive: Callable[[], Awaitable[dict[str, Any]]],
+    limit: int,
+) -> bytes:
+    body = bytearray()
+    while True:
+        message = await receive()
+        if message.get("type") != "http.request":
+            return bytes(body)
+        body.extend(bytes(message.get("body") or b""))
+        if len(body) > limit:
+            raise ValueError("request body is too large")
+        if not message.get("more_body", False):
+            return bytes(body)
+
+
 def _is_allowed_host(host: str, allowed_hosts: list[str]) -> bool:
     normalized_host = host.strip().lower().rstrip(".")
     host_without_port = _strip_port(normalized_host)

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",