@qingflow-tech/qingflow-cli 1.1.49 → 1.1.50-beta.1

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -20,6 +20,7 @@ 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
 from ..json_types import JSONObject
+from ..resource_uri import try_build_resource_uri
 from ..builder_facade.models import (
     AssociatedResourcesApplyRequest,
     ChartApplyRequest,
@@ -187,6 +188,26 @@ class AiBuilderTools(ToolBase):
             registry=app_form_schema_registry(),
         )
 
+    def _selected_ws_id(self, profile: str) -> int:
+        session_profile, _backend_session, _context = self._require_context(profile, require_workspace=True)
+        assert session_profile.selected_ws_id is not None
+        return session_profile.selected_ws_id
+
+    def _attach_apply_envelope(self, profile: str, tool_name: str, payload: JSONObject) -> JSONObject:
+        result = _attach_builder_apply_envelope(tool_name, payload)
+        eligible = [
+            item
+            for item in result.get("resources") or []
+            if isinstance(item, dict)
+            and item.get("resource_type") in {"package", "app", "view"}
+            and str(item.get("status") or "").lower()
+            not in {"failed", "pending", "planned", "readback_pending", "pending_readback", "unknown", "removed"}
+            and str(item.get("operation") or "").lower() not in {"failed", "removed", "planned"}
+        ]
+        if eligible:
+            _attach_builder_resource_uris(result, eligible, ws_id=self._selected_ws_id(profile))
+        return result
+
     def _apply_app_batch(self, *, tool_name: str, profile: str, apps: list[JSONObject], apply_one) -> JSONObject:
         started_at = time.perf_counter()
         batch_item_apply_ms = 0
@@ -199,7 +220,7 @@ class AiBuilderTools(ToolBase):
                 child_total_ms=child_total_ms,
                 total_ms=_elapsed_ms(started_at),
             )
-            return _attach_builder_apply_envelope(tool_name, payload)
+            return self._attach_apply_envelope(profile, tool_name, payload)
 
         if not isinstance(apps, list) or not apps:
             return finish(
@@ -677,6 +698,41 @@ class AiBuilderTools(ToolBase):
         def app_flow_get_schema(profile: str = DEFAULT_PROFILE, schema_version: str = "") -> JSONObject:
             return self.app_flow_get_schema(profile=profile, schema_version=schema_version or None)
 
+        @mcp.tool()
+        def app_flow_validate(
+            profile: str = DEFAULT_PROFILE,
+            spec: JSONObject | None = None,
+            schema_version: str = "",
+        ) -> JSONObject:
+            return self.app_flow_validate(
+                profile=profile,
+                spec=spec or {},
+                schema_version=schema_version or None,
+            )
+
+        @mcp.tool()
+        def app_flow_list_versions(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+        ) -> JSONObject:
+            return self.app_flow_list_versions(profile=profile, app_key=app_key)
+
+        @mcp.tool()
+        def app_flow_restore_version(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            version_id: str = "",
+            idempotency_key: str = "",
+            schema_version: str = "",
+        ) -> JSONObject:
+            return self.app_flow_restore_version(
+                profile=profile,
+                app_key=app_key,
+                version_id=version_id,
+                idempotency_key=idempotency_key or None,
+                schema_version=schema_version or None,
+            )
+
         @mcp.tool()
         def app_flow_apply(
             profile: str = DEFAULT_PROFILE,
@@ -686,7 +742,10 @@ class AiBuilderTools(ToolBase):
             idempotency_key: str = "",
             schema_version: str = "",
             patch_nodes: list[JSONObject] | None = None,
+            confirm_ticket: str = "",
+            base_version: int | None = None,
         ) -> JSONObject:
+            """执行应用相关逻辑。"""
             return self.app_flow_apply(
                 profile=profile,
                 app_key=app_key,
@@ -695,6 +754,8 @@ class AiBuilderTools(ToolBase):
                 idempotency_key=idempotency_key or None,
                 schema_version=schema_version or None,
                 patch_nodes=patch_nodes,
+                confirm_ticket=confirm_ticket or None,
+                base_version=base_version,
             )
 
         @mcp.tool()
@@ -841,16 +902,30 @@ class AiBuilderTools(ToolBase):
         being_draft: bool = False,
     ) -> JSONObject:
         """Read a canonical draft or published AppForm resource."""
-        return self._app_form.get(
+        result = self._app_form.get(
             profile=profile,
             app_key=app_key,
             schema_version=schema_version,
             being_draft=being_draft,
         )
+        if result.get("status") == "success":
+            _attach_uri(result, result, ws_id=self._selected_ws_id(profile), resource_type="app", app_key=app_key)
+        return result
 
     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)
+        result = self._app_form.apply(profile=profile, spec=spec)
+        if result.get("appKey") and (
+            str(result.get("status") or "") == "success" or result.get("createdAppPreserved") is True
+        ):
+            _attach_uri(
+                result,
+                result,
+                ws_id=self._selected_ws_id(profile),
+                resource_type="app",
+                app_key=result.get("appKey"),
+            )
+        return result
 
     def app_form_evaluate_formula(
         self,
@@ -917,12 +992,24 @@ class AiBuilderTools(ToolBase):
     def package_list(self, *, profile: str, trial_status: str = "all", query: str = "") -> JSONObject:
         """执行分组与包相关逻辑。"""
         normalized_args = {"trial_status": trial_status, "query": query}
-        return _safe_tool_call(
+        result = _safe_tool_call(
             lambda: self._facade.package_list(profile=profile, trial_status=trial_status, query=query),
             error_code="PACKAGE_LIST_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "package_list", "arguments": {"profile": profile, "trial_status": trial_status, "query": query}},
         )
+        if result.get("status") == "success":
+            ws_id = self._selected_ws_id(profile)
+            for item in result.get("items") or []:
+                if isinstance(item, dict):
+                    _attach_uri(
+                        item,
+                        result,
+                        ws_id=ws_id,
+                        resource_type="package",
+                        package_id=item.get("package_id"),
+                    )
+        return result
 
     def package_resolve(self, *, profile: str, package_name: str) -> JSONObject:
         """执行分组与包相关逻辑。"""
@@ -1062,12 +1149,23 @@ class AiBuilderTools(ToolBase):
     def package_get(self, *, profile: str, package_id: int | None = None) -> JSONObject:
         """执行分组与包相关逻辑。"""
         normalized_args = {"package_id": package_id}
-        return _publicize_package_fields(_safe_tool_call(
+        result = _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.package_get(profile=profile, package_id=package_id),
             error_code="PACKAGE_GET_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "package_get", "arguments": {"profile": profile, "package_id": package_id}},
         ))
+        if result.get("status") == "success":
+            ws_id = self._selected_ws_id(profile)
+            _attach_uri(
+                result,
+                result,
+                ws_id=ws_id,
+                resource_type="package",
+                package_id=result.get("package_id"),
+            )
+            _attach_package_item_uris(result.get("items"), result, ws_id=ws_id)
+        return result
 
     def package_apply(
         self,
@@ -1097,7 +1195,7 @@ class AiBuilderTools(ToolBase):
             try:
                 visibility_patch = VisibilityPatch.model_validate(visibility)
             except ValidationError as exc:
-                return _attach_builder_apply_envelope(
+                return self._attach_apply_envelope(profile,
                     "package_apply",
                     _visibility_validation_failure(str(exc), tool_name="package_apply", exc=exc),
                 )
@@ -1108,7 +1206,7 @@ class AiBuilderTools(ToolBase):
             creating=package_id is None and bool(str(package_name or "").strip()),
         )
         if icon_failure is not None:
-            return _attach_builder_apply_envelope("package_apply", icon_failure)
+            return self._attach_apply_envelope(profile, "package_apply", icon_failure)
         normalized_args = {
             "package_id": package_id,
             **({"package_name": package_name} if str(package_name or "").strip() else {}),
@@ -1133,7 +1231,7 @@ class AiBuilderTools(ToolBase):
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "package_apply", "arguments": {"profile": profile, **normalized_args}},
         ))
-        return _attach_builder_apply_envelope("package_apply", result)
+        return self._attach_apply_envelope(profile, "package_apply", result)
 
     def package_update(
         self,
@@ -1187,7 +1285,7 @@ class AiBuilderTools(ToolBase):
             "being_copy_data": being_copy_data,
             "solution_source": solution_source,
         }
-        return _safe_tool_call(
+        result = _safe_tool_call(
             lambda: self._facade.solution_install(
                 profile=profile,
                 solution_key=solution_key,
@@ -1198,6 +1296,7 @@ class AiBuilderTools(ToolBase):
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "solution_install", "arguments": {"profile": profile, **normalized_args}},
         )
+        return self._attach_apply_envelope(profile, "solution_install", result)
 
     def member_search(
         self,
@@ -1394,7 +1493,7 @@ class AiBuilderTools(ToolBase):
         try:
             request = CustomButtonsApplyRequest.model_validate(raw_request)
         except ValidationError as exc:
-            return _attach_builder_apply_envelope("app_custom_buttons_apply", _validation_failure(
+            return self._attach_apply_envelope(profile, "app_custom_buttons_apply", _validation_failure(
                 str(exc),
                 tool_name="app_custom_buttons_apply",
                 exc=exc,
@@ -1418,7 +1517,7 @@ class AiBuilderTools(ToolBase):
                 },
             ))
         normalized_args = request.model_dump(mode="json")
-        return _attach_builder_apply_envelope("app_custom_buttons_apply", _safe_tool_call(
+        return self._attach_apply_envelope(profile, "app_custom_buttons_apply", _safe_tool_call(
             lambda: self._facade.app_custom_buttons_apply(profile=profile, request=request),
             error_code="CUSTOM_BUTTONS_APPLY_FAILED",
             normalized_args=normalized_args,
@@ -1475,7 +1574,7 @@ class AiBuilderTools(ToolBase):
         try:
             request = AssociatedResourcesApplyRequest.model_validate(raw_request)
         except ValidationError as exc:
-            return _attach_builder_apply_envelope("app_associated_resources_apply", _validation_failure(
+            return self._attach_apply_envelope(profile, "app_associated_resources_apply", _validation_failure(
                 str(exc),
                 tool_name="app_associated_resources_apply",
                 exc=exc,
@@ -1504,7 +1603,7 @@ class AiBuilderTools(ToolBase):
                 },
             ))
         normalized_args = request.model_dump(mode="json", exclude_none=True)
-        return _attach_builder_apply_envelope("app_associated_resources_apply", _safe_tool_call(
+        return self._attach_apply_envelope(profile, "app_associated_resources_apply", _safe_tool_call(
             lambda: self._facade.app_associated_resources_apply(profile=profile, request=request),
             error_code="ASSOCIATED_RESOURCES_APPLY_FAILED",
             normalized_args=normalized_args,
@@ -1629,12 +1728,27 @@ class AiBuilderTools(ToolBase):
                 read_one=lambda item_app_key: self.app_get(profile=profile, app_key=item_app_key, app_keys=None),
             )
         normalized_args = {"app_key": app_key}
-        return _publicize_package_fields(_safe_tool_call(
+        result = _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.app_get(profile=profile, app_key=app_key),
             error_code="APP_GET_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
         ))
+        if result.get("status") == "success":
+            ws_id = self._selected_ws_id(profile)
+            _attach_uri(result, result, ws_id=ws_id, resource_type="app", app_key=app_key)
+            for view in result.get("views") or []:
+                if isinstance(view, dict) and (view.get("view_key") or view.get("viewKey")):
+                    _attach_uri(
+                        view,
+                        result,
+                        ws_id=ws_id,
+                        resource_type="view",
+                        app_key=app_key,
+                        view_kind="custom",
+                        view_key=view.get("view_key") or view.get("viewKey"),
+                    )
+        return result
 
     def app_read_fields(self, *, profile: str, app_key: str) -> JSONObject:
         """执行应用相关逻辑。"""
@@ -1727,12 +1841,27 @@ class AiBuilderTools(ToolBase):
                 read_one=lambda item_app_key: self.app_get_views(profile=profile, app_key=item_app_key, app_keys=None),
             )
         normalized_args = {"app_key": app_key}
-        return _safe_tool_call(
+        result = _safe_tool_call(
             lambda: self._facade.app_get_views(profile=profile, app_key=app_key),
             error_code="APP_GET_VIEWS_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_get_views", "arguments": {"profile": profile, "app_key": app_key}},
         )
+        if result.get("status") == "success":
+            ws_id = self._selected_ws_id(profile)
+            _attach_uri(result, result, ws_id=ws_id, resource_type="app", app_key=app_key)
+            for view in result.get("views") or []:
+                if isinstance(view, dict) and (view.get("view_key") or view.get("viewKey")):
+                    _attach_uri(
+                        view,
+                        result,
+                        ws_id=ws_id,
+                        resource_type="view",
+                        app_key=app_key,
+                        view_kind="custom",
+                        view_key=view.get("view_key") or view.get("viewKey"),
+                    )
+        return result
 
     def app_read_flow_summary(self, *, profile: str, app_key: str) -> JSONObject:
         """执行应用相关逻辑。"""
@@ -1779,6 +1908,50 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    def app_flow_validate(self, *, profile: str, spec: JSONObject, schema_version: str | None = None) -> JSONObject:
+        """离线校验 WorkflowSpec（apply 前预检，不写后端）。"""
+        normalized_args = {"spec": spec, "schema_version": schema_version}
+        return _safe_tool_call(
+            lambda: self._facade.flow_validate(profile=profile, spec=spec, schema_version=schema_version),
+            error_code="APP_FLOW_VALIDATE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile}},
+        )
+
+    def app_flow_list_versions(self, *, profile: str, app_key: str) -> JSONObject:
+        """列出某应用的 WorkflowSpec 版本快照（version_id/snapshot_type/时间）。"""
+        normalized_args = {"app_key": app_key}
+        return _safe_tool_call(
+            lambda: self._facade.flow_versions(profile=profile, app_key=app_key),
+            error_code="APP_FLOW_LIST_VERSIONS_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_flow_list_versions", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
+    def app_flow_restore_version(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        version_id: str,
+        idempotency_key: str | None = None,
+        schema_version: str | None = None,
+    ) -> JSONObject:
+        """回滚到指定版本快照，并回读当前 spec 与目标版本比对确认。"""
+        normalized_args = {"app_key": app_key, "version_id": version_id}
+        return _safe_tool_call(
+            lambda: self._facade.flow_restore_version(
+                profile=profile,
+                app_key=app_key,
+                version_id=version_id,
+                idempotency_key=idempotency_key,
+                schema_version=schema_version,
+            ),
+            error_code="APP_FLOW_RESTORE_VERSION_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_flow_list_versions", "arguments": {"profile": profile, "app_key": app_key}},
+        )
+
     def app_read_charts_summary(self, *, profile: str, app_key: str) -> JSONObject:
         """执行应用相关逻辑。"""
         normalized_args = {"app_key": app_key}
@@ -1871,12 +2044,27 @@ class AiBuilderTools(ToolBase):
         """执行视图相关逻辑。"""
         resolved_view_key = _normalize_builder_view_key(str(view_key or viewgraph_key or "").strip())
         normalized_args = {"view_key": resolved_view_key}
-        return _safe_tool_call(
+        result = _safe_tool_call(
             lambda: self._facade.view_get(profile=profile, view_key=resolved_view_key),
             error_code="VIEW_GET_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "view_get", "arguments": {"profile": profile, **normalized_args}},
         )
+        if result.get("status") == "success":
+            config = result.get("config") if isinstance(result.get("config"), dict) else {}
+            base_info = result.get("base_info") if isinstance(result.get("base_info"), dict) else {}
+            app_key = str(config.get("appKey") or config.get("formKey") or base_info.get("appKey") or base_info.get("formKey") or "").strip()
+            if app_key:
+                _attach_uri(
+                    result,
+                    result,
+                    ws_id=self._selected_ws_id(profile),
+                    resource_type="view",
+                    app_key=app_key,
+                    view_kind="custom",
+                    view_key=resolved_view_key,
+                )
+        return result
 
     def chart_get(
         self,
@@ -2165,7 +2353,7 @@ class AiBuilderTools(ToolBase):
             )
             failure = normalized_apps_payload.get("failure")
             if isinstance(failure, dict):
-                return _attach_builder_apply_envelope("app_schema_apply", failure)
+                return self._attach_apply_envelope(profile, "app_schema_apply", failure)
             package_id = normalized_apps_payload.get("package_id")  # type: ignore[assignment]
             apps = normalized_apps_payload.get("apps")  # type: ignore[assignment]
             input_warnings = list(normalized_apps_payload.get("warnings") or [])
@@ -2181,7 +2369,7 @@ class AiBuilderTools(ToolBase):
                 )
                 failure = form_result.get("failure")
                 if isinstance(failure, dict):
-                    return _attach_builder_apply_envelope("app_schema_apply", failure)
+                    return self._attach_apply_envelope(profile, "app_schema_apply", failure)
                 normalized_apps.append(form_result.get("payload") or app_item)
             apps = normalized_apps
             result = self._app_schema_apply_multi(
@@ -2195,7 +2383,7 @@ class AiBuilderTools(ToolBase):
                 result_warnings = list(result.get("warnings") or [])
                 result_warnings.extend(deepcopy(input_warnings))
                 result["warnings"] = result_warnings
-            return _attach_builder_apply_envelope("app_schema_apply", result)
+            return self._attach_apply_envelope(profile, "app_schema_apply", result)
         inline_form_layout_sections: list[JSONObject] = []
         if form:
             form_payload: JSONObject = {"form": form}
@@ -2208,7 +2396,7 @@ class AiBuilderTools(ToolBase):
             )
             failure = form_result.get("failure")
             if isinstance(failure, dict):
-                return _attach_builder_apply_envelope("app_schema_apply", failure)
+                return self._attach_apply_envelope(profile, "app_schema_apply", failure)
             normalized_payload = form_result.get("payload") if isinstance(form_result.get("payload"), dict) else {}
             add_fields = list(normalized_payload.get("add_fields") or [])
             inline_form_layout_sections = list(form_result.get("layout_sections") or [])
@@ -2246,7 +2434,7 @@ class AiBuilderTools(ToolBase):
                 inline_form_layout_sections=inline_form_layout_sections,
             ),
         )
-        return _attach_builder_apply_envelope("app_schema_apply", result)
+        return self._attach_apply_envelope(profile, "app_schema_apply", result)
 
     def _app_schema_apply_multi(
         self,
@@ -3525,7 +3713,7 @@ class AiBuilderTools(ToolBase):
                 sections=sections,
             ),
         )
-        return _attach_builder_apply_envelope("app_layout_apply", result)
+        return self._attach_apply_envelope(profile, "app_layout_apply", result)
 
     def _app_layout_apply_once(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
         """执行内部辅助逻辑。"""
@@ -3580,6 +3768,8 @@ class AiBuilderTools(ToolBase):
         idempotency_key: str | None = None,
         schema_version: str | None = None,
         patch_nodes: list[JSONObject] | None = None,
+        confirm_ticket: str | None = None,
+        base_version: int | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
         if patch_nodes is not None:
@@ -3589,8 +3779,9 @@ class AiBuilderTools(ToolBase):
                 "patch_nodes": patch_nodes,
                 "idempotency_key": idempotency_key,
                 "schema_version": schema_version,
+                "base_version": base_version,
             }
-            return _attach_builder_apply_envelope("app_flow_apply", _safe_tool_call(
+            return self._attach_apply_envelope(profile, "app_flow_apply", _safe_tool_call(
                 lambda: self._facade.flow_patch_nodes(
                     profile=profile,
                     app_key=app_key,
@@ -3610,8 +3801,10 @@ class AiBuilderTools(ToolBase):
                 "spec": spec,
                 "idempotency_key": idempotency_key,
                 "schema_version": schema_version,
+                "confirm_ticket": confirm_ticket,
+                "base_version": base_version,
             }
-            return _attach_builder_apply_envelope("app_flow_apply", _safe_tool_call(
+            return self._attach_apply_envelope(profile, "app_flow_apply", _safe_tool_call(
                 lambda: self._facade.flow_apply(
                     profile=profile,
                     app_key=app_key,
@@ -3619,6 +3812,8 @@ class AiBuilderTools(ToolBase):
                     publish=publish,
                     idempotency_key=idempotency_key,
                     schema_version=schema_version,
+                    confirm_ticket=confirm_ticket,
+                    base_version=base_version,
                 ),
                 error_code="FLOW_SPEC_APPLY_FAILED",
                 normalized_args=normalized_args,
@@ -3647,9 +3842,9 @@ class AiBuilderTools(ToolBase):
                     transitions=effective_transitions,
                 ),
             )
-            return _attach_builder_apply_envelope("app_flow_apply", result)
+            return self._attach_apply_envelope(profile, "app_flow_apply", result)
         normalized_args = {"app_key": app_key, "publish": publish}
-        return _attach_builder_apply_envelope(
+        return self._attach_apply_envelope(profile,
             "app_flow_apply",
             {
                 "status": "failed",
@@ -3784,7 +3979,7 @@ class AiBuilderTools(ToolBase):
                 patch_views=patch_views or [],
             ),
         )
-        return _attach_builder_apply_envelope("app_views_apply", result)
+        return self._attach_apply_envelope(profile, "app_views_apply", result)
 
     def _app_views_apply_view_batch(
         self,
@@ -3795,7 +3990,7 @@ class AiBuilderTools(ToolBase):
     ) -> JSONObject:
         started_at = time.perf_counter()
         if not isinstance(views, list) or not views:
-            return _attach_builder_apply_envelope(
+            return self._attach_apply_envelope(profile,
                 "app_views_apply",
                 _config_failure(
                     tool_name="app_views_apply",
@@ -4026,7 +4221,7 @@ class AiBuilderTools(ToolBase):
             view_write_parallel_wall_ms=view_write_parallel_wall_ms,
             total_ms=_elapsed_ms(started_at),
         )
-        return _attach_builder_apply_envelope("app_views_apply", payload)
+        return self._attach_apply_envelope(profile, "app_views_apply", payload)
 
     def _app_views_apply_once(
         self,
@@ -4149,7 +4344,7 @@ class AiBuilderTools(ToolBase):
                 }
             )
         except ValidationError as exc:
-            return _attach_builder_apply_envelope("app_charts_apply", _visibility_validation_failure(
+            return self._attach_apply_envelope(profile, "app_charts_apply", _visibility_validation_failure(
                 str(exc),
                 tool_name="app_charts_apply",
                 exc=exc,
@@ -4165,7 +4360,7 @@ class AiBuilderTools(ToolBase):
                 },
             ))
         normalized_args = request.model_dump(mode="json")
-        return _attach_builder_apply_envelope("app_charts_apply", _safe_tool_call(
+        return self._attach_apply_envelope(profile, "app_charts_apply", _safe_tool_call(
             lambda: self._facade.chart_apply(profile=profile, request=request),
             error_code="CHART_APPLY_FAILED",
             normalized_args=normalized_args,
@@ -4201,7 +4396,7 @@ class AiBuilderTools(ToolBase):
                 "publish": publish,
                 "patch_sections": patch_sections,
             }
-            return _attach_builder_apply_envelope("portal_apply", _publicize_package_fields(_safe_tool_call(
+            return self._attach_apply_envelope(profile, "portal_apply", _publicize_package_fields(_safe_tool_call(
                 lambda: self._facade.portal_patch_sections(
                     profile=profile,
                     dash_key=dash_key,
@@ -4248,7 +4443,7 @@ class AiBuilderTools(ToolBase):
         try:
             request = PortalApplyRequest.model_validate(request_payload)
         except ValidationError as exc:
-            return _attach_builder_apply_envelope("portal_apply", _visibility_validation_failure(
+            return self._attach_apply_envelope(profile, "portal_apply", _visibility_validation_failure(
                 str(exc),
                 tool_name="portal_apply",
                 exc=exc,
@@ -4279,14 +4474,14 @@ class AiBuilderTools(ToolBase):
             creating=not bool(str(request.dash_key or "").strip()),
         )
         if icon_failure is not None:
-            return _attach_builder_apply_envelope("portal_apply", icon_failure)
+            return self._attach_apply_envelope(profile, "portal_apply", icon_failure)
         result = _publicize_package_fields(_safe_tool_call(
             lambda: self._facade.portal_apply(profile=profile, request=request),
             error_code="PORTAL_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "portal_apply", "arguments": {"profile": profile, **normalized_args}},
         ))
-        return _attach_builder_apply_envelope("portal_apply", result)
+        return self._attach_apply_envelope(profile, "portal_apply", result)
 
     def portal_delete(self, *, profile: str, dash_key: str) -> JSONObject:
         """执行门户删除逻辑。"""
@@ -4297,7 +4492,7 @@ class AiBuilderTools(ToolBase):
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "portal_delete", "arguments": {"profile": profile, **normalized_args}},
         ))
-        return _attach_builder_apply_envelope("portal_delete", result)
+        return self._attach_apply_envelope(profile, "portal_delete", result)
 
     def app_publish_verify(
         self,
@@ -4336,7 +4531,7 @@ class AiBuilderTools(ToolBase):
                 expected_package_tag_id=expected_package_id,
             ),
         ))
-        return _attach_builder_apply_envelope("app_publish_verify", result)
+        return self._attach_apply_envelope(profile, "app_publish_verify", result)
 
     def _retry_after_self_lock_release(self, *, profile: str, result: JSONObject, retry_call) -> JSONObject:
         """执行内部辅助逻辑。"""
@@ -5613,7 +5808,7 @@ def _safe_tool_call(
         result = call()
     except (QingflowApiError, RuntimeError) as error:
         api_error = _coerce_api_error(error)
-        public_http_status = None if api_error.http_status == 404 else api_error.http_status
+        # #162 D5：404 不再抹除 http_status，错误信封保留真实传输层事实
         result = {
             "status": "failed",
             "error_code": error_code,
@@ -5632,7 +5827,7 @@ def _safe_tool_call(
             "suggested_next_call": suggested_next_call,
             "request_id": api_error.request_id,
             "backend_code": api_error.backend_code,
-            "http_status": public_http_status,
+            "http_status": api_error.http_status,
             "noop": False,
             "verification": {},
         }
@@ -5702,6 +5897,68 @@ def _publicize_package_fields(value):
     return public
 
 
+def _append_uri_warning(payload: JSONObject, warning: JSONObject | None) -> None:
+    if not warning:
+        return
+    warnings = payload.setdefault("warnings", [])
+    if isinstance(warnings, list) and not any(
+        isinstance(item, dict) and item.get("code") == warning.get("code") for item in warnings
+    ):
+        warnings.append(warning)
+
+
+def _attach_uri(target: JSONObject, payload: JSONObject, *, ws_id: int, **identity: Any) -> None:
+    uri, warning = try_build_resource_uri(ws_id=ws_id, **identity)
+    if uri:
+        target["uri"] = uri
+    _append_uri_warning(payload, warning)
+
+
+def _attach_builder_resource_uris(payload: JSONObject, resources: list[JSONObject], *, ws_id: int) -> None:
+    for resource in resources:
+        resource_type = str(resource.get("resource_type") or "")
+        ids = resource.get("ids") if isinstance(resource.get("ids"), dict) else {}
+        if resource_type == "package":
+            _attach_uri(
+                resource,
+                payload,
+                ws_id=ws_id,
+                resource_type="package",
+                package_id=resource.get("id") or ids.get("package_id"),
+            )
+        elif resource_type == "app":
+            _attach_uri(
+                resource,
+                payload,
+                ws_id=ws_id,
+                resource_type="app",
+                app_key=resource.get("key") or ids.get("app_key"),
+            )
+        elif resource_type == "view":
+            parent = resource.get("parent") if isinstance(resource.get("parent"), dict) else {}
+            _attach_uri(
+                resource,
+                payload,
+                ws_id=ws_id,
+                resource_type="view",
+                app_key=ids.get("app_key") or (parent.get("key") if parent.get("resource_type") == "app" else None),
+                view_kind="custom",
+                view_key=resource.get("key") or ids.get("view_key"),
+            )
+
+
+def _attach_package_item_uris(items: Any, payload: JSONObject, *, ws_id: int) -> None:
+    if not isinstance(items, list):
+        return
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        if item.get("type") == "app" and item.get("app_key"):
+            _attach_uri(item, payload, ws_id=ws_id, resource_type="app", app_key=item.get("app_key"))
+        if item.get("type") == "group":
+            _attach_package_item_uris(item.get("items"), payload, ws_id=ws_id)
+
+
 def _builder_contract_with_apply_output(tool_name: str, contract: JSONObject) -> JSONObject:
     public = deepcopy(contract)
     if tool_name not in BUILDER_APPLY_TOOL_NAMES:
@@ -5714,7 +5971,7 @@ def _builder_contract_with_apply_output(tool_name: str, contract: JSONObject) ->
     public["output_contract"] = {
         "schema_version": BUILDER_APPLY_SCHEMA_VERSION,
         "preferred_ui_fields": ["operation", "summary", "resources"],
-        "resource_fields": ["resource_type", "operation", "status", "id", "key", "name", "ids", "parent", "icon_config", "error_code", "message"],
+        "resource_fields": ["resource_type", "operation", "status", "id", "key", "name", "ids", "parent", "uri", "icon_config", "error_code", "message"],
         "json_paths": _builder_apply_json_paths(),
         "legacy_fields_preserved": True,
     }
@@ -5766,6 +6023,7 @@ def _builder_apply_json_paths() -> JSONObject:
         "resource_keys": "$.resources[].key",
         "resource_ids": "$.resources[].id",
         "resource_statuses": "$.resources[].status",
+        "resource_uris": "$.resources[].uri",
     }
 
 
@@ -5855,7 +6113,9 @@ def _builder_verification_truthy(value: object) -> bool:
 
 def _builder_apply_resources(tool_name: str, payload: JSONObject) -> list[JSONObject]:
     resources: list[JSONObject]
-    if tool_name == "package_apply":
+    if tool_name == "solution_install":
+        resources = [deepcopy(item) for item in payload.get("resources") or [] if isinstance(item, dict)]
+    elif tool_name == "package_apply":
         resources = _builder_package_resources(payload)
     elif tool_name == "app_schema_apply":
         resources = _builder_schema_resources(payload)
@@ -6620,6 +6880,10 @@ def _public_error_message(error_code: str, error: QingflowApiError) -> str:
         return "app is currently locked by another active editor session"
     if error.http_status != 404:
         return error.message
+    # 404 优先保留后端原始 message（agent 排障依据）；仅当原始 message 为空时
+    # 才落多路由环境泛化兑底（#162 D5：不再默认泛化丢失真实原因）。
+    if error.message:
+        return f"{error.message} (HTTP 404)"
     mapping = {
         "PACKAGE_LIST_FAILED": "package list is unavailable in the current route",
         "PACKAGE_RESOLVE_FAILED": "package resolution is unavailable in the current route",
@@ -7811,6 +8075,75 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "patch_nodes": [{"id": "approve_1", "set": {"name": "主管审批"}}],
         },
     },
+    "app_flow_validate": {
+        "allowed_keys": [
+            "spec",
+            "schema_version",
+        ],
+        "aliases": {
+            "schemaVersion": "schema_version",
+        },
+        "allowed_values": {},
+        "dependency_hints": [
+            "run app_flow_validate on the drafted WorkflowSpec before app_flow_apply to catch schema/structure issues without writing",
+        ],
+        "execution_notes": [
+            "offline precheck: fetches the WorkflowSpec JSON Schema and runs schema + structural + semantic lint checks",
+            "never writes: the only network call is the schema GET; publish=false is a draft write, not a precheck",
+            "issues[] blocks apply; warnings[] (e.g. rejection-edge cycles) are advisory only",
+            "server-side field-reference semantics are validated at apply time; a clean validate does not guarantee apply success",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "spec": {"schemaVersion": "1", "nodes": [], "edges": []},
+        },
+    },
+    "app_flow_list_versions": {
+        "allowed_keys": [
+            "app_key",
+        ],
+        "aliases": {},
+        "allowed_values": {},
+        "dependency_hints": [
+            "use app_flow_list_versions to discover version_id values before app_flow_restore_version or app_flow_get(version_id=...)",
+        ],
+        "execution_notes": [
+            "returns items[] with version_id, snapshot_type, created_at_ms/created_at_iso, operator_name, spec_hash per version snapshot",
+            "raw backend entries ride along in details.versions of the full envelope for troubleshooting",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+        },
+    },
+    "app_flow_restore_version": {
+        "allowed_keys": [
+            "app_key",
+            "version_id",
+            "idempotency_key",
+            "schema_version",
+        ],
+        "aliases": {
+            "versionId": "version_id",
+            "idempotencyKey": "idempotency_key",
+            "schemaVersion": "schema_version",
+        },
+        "allowed_values": {},
+        "dependency_hints": [
+            "resolve version_id via app_flow_list_versions, optionally inspect it with app_flow_get(version_id=...), then restore",
+        ],
+        "execution_notes": [
+            "draft-domain write: restores the draft workflow spec to the target version snapshot and does not auto-publish",
+            "maintenance gate applies: restore to a version with more nodes than the threshold is blocked (FLOW_EDIT_UNDER_MAINTENANCE)",
+            "readback verification compares the restored current spec with the target version; mismatch yields partial_success with FLOW_RESTORE_VERIFY_FAILED",
+            "verify the outcome with app_flow_get afterwards when verification reports partial_success",
+        ],
+        "minimal_example": {
+            "profile": "default",
+            "app_key": "APP_KEY",
+            "version_id": "v_1765000000_ab12cd34",
+        },
+    },
     "app_views_plan": {
         "allowed_keys": [
             "app_key",