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

package/src/qingflow_mcp/builder_facade/service.py

@@ -16,9 +16,11 @@ from urllib.parse import quote_plus, unquote_plus
 from uuid import uuid4
 
 from ..backend_client import BackendRequestContext
+from ..config import get_flow_edit_maintenance_threshold
 from ..errors import QingflowApiError, backend_code_int, backend_code_value_int, is_auth_like_error
 from ..json_types import JSONObject
 from ..list_type_labels import RECORD_LIST_TYPE_LABELS, SYSTEM_VIEW_ID_TO_LIST_TYPE
+from ..resource_uri import validate_positive_resource_id, validate_resource_identity
 from ..solution.build_assembly_store import BuildAssemblyStore, default_artifacts, default_manifest
 from ..solution.compiler.chart_compiler import qingbi_workspace_visible_auth
 from ..solution.compiler.form_compiler import build_question, default_form_payload, default_member_auth
@@ -36,6 +38,7 @@ from ..tools.role_tools import RoleTools
 from ..tools.solution_tools import SolutionTools
 from ..tools.view_tools import ViewTools
 from ..tools.workflow_tools import WorkflowTools
+from . import flow_validation
 from . import workflow_spec as workflow_spec_api
 from .button_style_catalog import button_style_catalog_payload
 from .models import (
@@ -393,10 +396,370 @@ class AiBuilderFacade:
             "verified": True,
             "app_key": app_key,
         }
-        if isinstance(payload, dict):
-            response.update(payload)
+        # 受控提取（#162 D7/D8）：不再裸 response.update(payload)，避免后端驼峰键
+        # 与后端大写 status="SUCCESS" 污染桥接层信封（顶层只保留 spec 本体 + 白名单
+        # 蛇形元数据键）；spec 缺失/为空时显式失败（对齐评测口径 EMPTY_SPEC）。
+        spec = payload.get("spec") if isinstance(payload, dict) else None
+        if isinstance(spec, dict) and spec:
+            response["spec"] = spec
+            for snake_key, camel_key in (
+                ("source", "source"),
+                ("schema_version", "schemaVersion"),
+                ("version_id", "versionId"),
+                ("snapshot_type", "snapshotType"),
+                ("mapping_summary", "mappingSummary"),
+                ("draft_version", "draftVersion"),
+            ):
+                if camel_key in payload:
+                    response[snake_key] = payload[camel_key]
+        elif isinstance(payload, dict) and payload and "nodes" in payload:
+            # 兑底：spec 直接在 data 根级（评测脚本同口径）
+            response["spec"] = payload
+        else:
+            return _failed(
+                "FLOW_SPEC_GET_FAILED",
+                "no data.spec in response",
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
+                backend_code="EMPTY_SPEC",
+            )
+        return _apply_permission_outcomes(response, permission_outcome)
+
+    def flow_validate(
+        self,
+        *,
+        profile: str,
+        spec: dict[str, Any],
+        schema_version: str | None = None,
+    ) -> JSONObject:
+        """离线校验 WorkflowSpec（apply 前预检 / dry-run）。
+
+        唯一网络调用是 schema 拉取（GET /api/workflow/spec/schema），
+        绝不 POST / 写；服务端写面全量语义校验（字段引用存在性等）超出
+        离线能力，作为已知限制记录，后端真 dryRun 需要时另立后端 issue。
+        """
+        effective_schema_version = schema_version or workflow_spec_api.DEFAULT_SCHEMA_VERSION
+        normalized_args = {"spec": spec, "schema_version": effective_schema_version}
+        try:
+            schema_payload = self._with_backend_context(
+                profile,
+                lambda context: workflow_spec_api.fetch_schema(
+                    self.apps.backend,
+                    context,
+                    schema_version=schema_version,
+                ),
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            failure = _failed_from_api_error(
+                "FLOW_SPEC_SCHEMA_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={},
+                suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile, **normalized_args}},
+            )
+            failure.update({
+                "category": "validation",
+                "ok": False,
+                "issues": [str(failure.get("message") or "workflow spec schema fetch failed")],
+                "schema_version": effective_schema_version,
+            })
+            return failure
+        if not isinstance(schema_payload, dict):
+            schema_payload = {}
+        result = flow_validation.validate_spec(spec if isinstance(spec, dict) else {}, schema_payload)
+        ok = result.ok
+        return {
+            "category": "validation",
+            "status": "success" if ok else "failed",
+            "error_code": None if ok else "FLOW_SPEC_INVALID",
+            "recoverable": True,
+            "ok": ok,
+            "message": (
+                "workflow spec passed offline validation"
+                if ok
+                else f"workflow spec failed offline validation with {len(result.issues)} issue(s)"
+            ),
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {
+                "issue_count": len(result.issues),
+                "warning_count": len(result.warnings),
+                "node_count": result.node_count,
+                "edge_count": result.edge_count,
+                "write_executed": False,
+            },
+            "request_id": None,
+            "suggested_next_call": (
+                None
+                if ok
+                else {"tool_name": "app_flow_get_schema", "arguments": {"profile": profile}}
+            ),
+            "noop": True,
+            "warnings": result.warnings,
+            "issues": result.issues,
+            "node_count": result.node_count,
+            "edge_count": result.edge_count,
+            "schema_version": effective_schema_version,
+            "write_executed": False,
+            "safe_to_retry": True,
+        }
+
+    def flow_versions(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+    ) -> JSONObject:
+        """列出某应用的 WorkflowSpec 版本快照（GET /api/workflow/spec/versions）。"""
+        normalized_args = {"app_key": app_key}
+        permission_outcome = self._guard_app_permission(
+            profile=profile,
+            app_key=app_key,
+            required_permission="data_manage",
+            normalized_args=normalized_args,
+        )
+        if permission_outcome.block is not None:
+            return permission_outcome.block
+        try:
+            payload = self._with_backend_context(
+                profile,
+                lambda context: workflow_spec_api.fetch_versions(
+                    self.apps.backend,
+                    context,
+                    app_key=app_key,
+                ),
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "FLOW_VERSIONS_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_flow_list_versions", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        entries = workflow_spec_api.normalize_version_entries(payload)
+        items = [_public_flow_version_entry(entry) for entry in entries]
+        response = {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "listed workflow spec versions",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {"versions": entries},
+            "request_id": None,
+            "suggested_next_call": None,
+            "noop": False,
+            "warnings": list(permission_outcome.warnings),
+            "verification": {"versions_loaded": True, "count": len(items)},
+            "verified": True,
+            "app_key": app_key,
+            "items": items,
+            "count": len(items),
+        }
+        return _apply_permission_outcomes(response, permission_outcome)
+
+    def flow_restore_version(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        version_id: str,
+        idempotency_key: str | None = None,
+        schema_version: str | None = None,
+    ) -> JSONObject:
+        """回滚到指定版本快照（POST /api/workflow/spec:restore）。
+
+        链路：权限(data_manage) → 目标版本预读(fetch_spec version_id)→
+        维护闸门（契约 1 对齐：目标版本节点数 > 阈值拦截）→ POST restore →
+        回读当前 spec 与目标版本比对。restore 是草稿域写操作，不自动发布。
+        """
+        normalized_args = {
+            "app_key": app_key,
+            "version_id": version_id,
+            "idempotency_key": idempotency_key,
+            "schema_version": schema_version or workflow_spec_api.DEFAULT_SCHEMA_VERSION,
+        }
+        permission_outcome = self._guard_app_permission(
+            profile=profile,
+            app_key=app_key,
+            required_permission="data_manage",
+            normalized_args=normalized_args,
+        )
+        if permission_outcome.block is not None:
+            return permission_outcome.block
+        requested_version_id = str(version_id or "").strip()
+        if not requested_version_id:
+            return _apply_permission_outcomes(
+                _failed(
+                    "FLOW_VERSION_ID_REQUIRED",
+                    "version_id is required for flow restore",
+                    normalized_args=normalized_args,
+                    missing_fields=["version_id"],
+                    suggested_next_call={"tool_name": "app_flow_list_versions", "arguments": {"profile": profile, "app_key": app_key}},
+                ),
+                permission_outcome,
+            )
+        # 目标版本预读：闸门判定 + 回滚后回读比对基线（复用既有单点读）
+        try:
+            target_flow = self._with_backend_context(
+                profile,
+                lambda context: workflow_spec_api.fetch_spec(
+                    self.apps.backend,
+                    context,
+                    app_key=app_key,
+                    version_id=requested_version_id,
+                ),
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            not_found = api_error.http_status == 404 or "not found" in str(api_error.message or "").lower()
+            return _apply_permission_outcomes(
+                _failed_from_api_error(
+                    "FLOW_VERSION_NOT_FOUND" if not_found else "FLOW_RESTORE_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details={"app_key": app_key, "version_id": requested_version_id},
+                    suggested_next_call={"tool_name": "app_flow_list_versions", "arguments": {"profile": profile, "app_key": app_key}},
+                ),
+                permission_outcome,
+            )
+        target_spec = target_flow.get("spec") if isinstance(target_flow, dict) else None
+        # 维护闸门（契约 1）：restore 后流程即目标版本形态，按目标版本节点数判定
+        gate_block = _flow_edit_maintenance_gate(
+            {"spec": target_spec} if isinstance(target_spec, dict) else {},
+            app_key=app_key,
+            normalized_args=normalized_args,
+        )
+        if gate_block is not None:
+            return _apply_permission_outcomes(gate_block, permission_outcome)
+        restore_body = {
+            "appKey": app_key,
+            "versionId": requested_version_id,
+            "idempotencyKey": idempotency_key or str(uuid4()),
+            "schemaVersion": schema_version or workflow_spec_api.DEFAULT_SCHEMA_VERSION,
+        }
+        try:
+            restore_result = self._with_backend_context(
+                profile,
+                lambda context: workflow_spec_api.post_restore(
+                    self.apps.backend,
+                    context,
+                    restore_body=restore_body,
+                ),
+            )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _apply_permission_outcomes(
+                _failed_from_api_error(
+                    "FLOW_RESTORE_FAILED",
+                    api_error,
+                    normalized_args=normalized_args,
+                    details={"app_key": app_key, "version_id": requested_version_id},
+                    suggested_next_call={"tool_name": "app_flow_list_versions", "arguments": {"profile": profile, "app_key": app_key}},
+                ),
+                permission_outcome,
+            )
+        if not isinstance(restore_result, dict):
+            restore_result = {"result": restore_result}
+        backend_status = str(restore_result.get("status") or "SUCCESS").upper()
+        if backend_status not in {"SUCCESS", "OK"}:
+            return _apply_permission_outcomes(
+                _failed(
+                    "FLOW_RESTORE_FAILED",
+                    str(restore_result.get("message") or "workflow spec restore failed"),
+                    normalized_args=normalized_args,
+                    details={"app_key": app_key, "version_id": requested_version_id, "restore_result": restore_result},
+                    suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
+                ),
+                permission_outcome,
+            )
+        # 回读确认：当前 spec 应与目标版本一致（验收 2）
+        warnings: list[dict[str, Any]] = []
+        verification: JSONObject = {"restore_post_succeeded": True}
+        verified: bool | None = None
+        try:
+            readback = self._with_backend_context(
+                profile,
+                lambda context: workflow_spec_api.fetch_spec(
+                    self.apps.backend,
+                    context,
+                    app_key=app_key,
+                ),
+            )
+            readback_spec = readback.get("spec") if isinstance(readback, dict) else None
+            verified = isinstance(readback_spec, dict) and readback_spec == target_spec
+            verification["readback_matches_target"] = verified
+            if verified:
+                verification["restored_spec_matches_target"] = True
+            else:
+                verification["restored_spec_matches_target"] = False
+                warnings.append(
+                    {
+                        "code": "FLOW_RESTORE_VERIFY_FAILED",
+                        "message": "readback spec does not match the target version snapshot",
+                    }
+                )
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            verification["readback_matches_target"] = None
+            verification["readback_error"] = str(api_error.message or "readback failed")
+            warnings.append(
+                {
+                    "code": "FLOW_RESTORE_READBACK_UNAVAILABLE",
+                    "message": "restore succeeded but readback verification is unavailable",
+                }
+            )
+        if verified is True:
+            status = "success"
+            error_code = None
+            message = "restored workflow spec to target version"
+            recoverable = False
+            suggested_next_call = None
+        elif verified is False:
+            status = "partial_success"
+            error_code = "FLOW_RESTORE_VERIFY_FAILED"
+            message = "restored workflow spec; readback does not match the target version"
+            recoverable = True
+            suggested_next_call = {"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}}
         else:
-            response["result"] = payload
+            status = "partial_success"
+            error_code = "FLOW_RESTORE_READBACK_UNAVAILABLE"
+            message = "restored workflow spec; readback verification unavailable"
+            recoverable = True
+            suggested_next_call = {"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}}
+        response = {
+            "status": status,
+            "error_code": error_code,
+            "recoverable": recoverable,
+            "message": message,
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {
+                "app_key": app_key,
+                "version_id": requested_version_id,
+                "restore_result": restore_result,
+            },
+            "request_id": None,
+            "suggested_next_call": suggested_next_call,
+            "noop": False,
+            "warnings": warnings,
+            "verification": verification,
+            "verified": verified is True,
+            "app_key": app_key,
+            "restored_from_version_id": requested_version_id,
+            "current_version_id": restore_result.get("currentVersionId"),
+            "draft_version": restore_result.get("draftVersion"),
+            "write_executed": True,
+            "write_succeeded": True,
+            "safe_to_retry": False,
+        }
         return _apply_permission_outcomes(response, permission_outcome)
 
     def flow_apply(
@@ -408,6 +771,58 @@ class AiBuilderFacade:
         publish: bool = True,
         idempotency_key: str | None = None,
         schema_version: str | None = None,
+        confirm_ticket: str | None = None,
+        base_version: int | None = None,
+        _prefetched_current_flow: JSONObject | None = None,
+    ) -> JSONObject:
+        """Apply a complete WorkflowSpec, retrying once on transient business codes.
+
+        评测沉淀的瞬态业务码重试回流（eval_replay_flow._TRANSIENT_CODES 同款，
+        视图基准 PERMISSION 318 教训）：apply 主调用失败且 error_code 属于白名单时
+        sleep 后重试 1 次；闸门失败 / 权限失败 / 输入校验失败不在白名单，不重试。
+        """
+        response = self._flow_apply_core(
+            profile=profile,
+            app_key=app_key,
+            spec=spec,
+            publish=publish,
+            idempotency_key=idempotency_key,
+            schema_version=schema_version,
+            confirm_ticket=confirm_ticket,
+            base_version=base_version,
+            prefetched_current_flow=_prefetched_current_flow,
+        )
+        if not _is_transient_flow_failure(response):
+            return response
+        time.sleep(_FLOW_TRANSIENT_RETRY_DELAY_SECONDS)
+        response = self._flow_apply_core(
+            profile=profile,
+            app_key=app_key,
+            spec=spec,
+            publish=publish,
+            idempotency_key=idempotency_key,
+            schema_version=schema_version,
+            confirm_ticket=confirm_ticket,
+            base_version=base_version,
+            prefetched_current_flow=_prefetched_current_flow,
+        )
+        if not isinstance(response.get("details"), dict):
+            response["details"] = {}
+        response["details"]["transient_retried"] = True
+        return response
+
+    def _flow_apply_core(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        spec: dict[str, Any],
+        publish: bool,
+        idempotency_key: str | None,
+        schema_version: str | None,
+        confirm_ticket: str | None,
+        base_version: int | None,
+        prefetched_current_flow: JSONObject | None,
     ) -> JSONObject:
         normalized_args = {
             "app_key": app_key,
@@ -415,9 +830,12 @@ class AiBuilderFacade:
             "publish": publish,
             "idempotency_key": idempotency_key,
             "schema_version": schema_version or workflow_spec_api.DEFAULT_SCHEMA_VERSION,
+            "confirm_ticket": confirm_ticket,
+            "base_version": base_version,
         }
         apply_started_at = time.perf_counter()
         permission_ms = 0
+        flow_maintenance_gate_ms = 0
         flow_spec_apply_ms = 0
         flow_spec_verify_ms = 0
         publish_ms = 0
@@ -429,6 +847,7 @@ class AiBuilderFacade:
             _merge_duration_breakdown(
                 response,
                 permission_ms=permission_ms,
+                flow_maintenance_gate_ms=flow_maintenance_gate_ms,
                 flow_spec_apply_ms=flow_spec_apply_ms,
                 flow_spec_verify_ms=flow_spec_verify_ms,
                 publish_ms=publish_ms,
@@ -467,12 +886,37 @@ class AiBuilderFacade:
                     suggested_next_call={"tool_name": "app_flow_get_schema", "arguments": {"profile": profile}},
                 )
             )
+        # BEGIN temporary flow edit maintenance guard: remove this block when flow editing is restored.
+        # 闸门下沉到 facade：CLI / MCP / 进程内评测的唯一共同必经点。
+        # flow_patch_nodes 等已有前置读的调用方可用 prefetched_current_flow 复用读结果，零新增请求。
+        gate_started_at = time.perf_counter()
+        current_flow = prefetched_current_flow
+        if current_flow is None:
+            current_flow = self.flow_get(profile=profile, app_key=app_key)
+        flow_maintenance_gate_ms += _duration_ms(gate_started_at)
+        if str(current_flow.get("status") or "").strip().lower() != "success":
+            return finish(current_flow)
+        gate_block = _flow_edit_maintenance_gate(
+            current_flow,
+            app_key=app_key,
+            normalized_args=normalized_args,
+        )
+        if gate_block is not None:
+            return finish(gate_block)
+        # END temporary flow edit maintenance guard.
         apply_body = {
             "appKey": app_key,
             "idempotencyKey": idempotency_key or str(uuid4()),
             "schemaVersion": schema_version or workflow_spec_api.DEFAULT_SCHEMA_VERSION,
             "spec": spec,
         }
+        if confirm_ticket:
+            # one-time confirmation ticket from a previous CONFIRMATION_REQUIRED preview
+            apply_body["confirmTicket"] = confirm_ticket
+        if base_version is not None:
+            # optimistic lock: echo the draftVersion read from app_flow_get so a concurrent
+            # editor save between get and apply surfaces as BASE_VERSION_CONFLICT (409)
+            apply_body["baseVersionNo"] = base_version
         try:
             flow_spec_apply_started_at = time.perf_counter()
             apply_result = self._with_backend_context(
@@ -494,6 +938,45 @@ class AiBuilderFacade:
         flow_spec_apply_ms += _duration_ms(flow_spec_apply_started_at)
         if not isinstance(apply_result, dict):
             apply_result = {"result": apply_result}
+        # Two-phase destructive-apply protocol (#149): intercept BEFORE the SUCCESS/OK whitelist
+        # (which would swallow it as FLOW_SPEC_APPLY_FAILED) and BEFORE publish — a confirmation
+        # gate result must not trigger publishing, must not be an error envelope, and must surface
+        # the ticket + preview to the agent untouched.
+        if workflow_spec_api.is_confirmation_required(apply_result):
+            summary = workflow_spec_api.confirmation_required_summary(apply_result)
+            retry_arguments: JSONObject = {"profile": profile, "app_key": app_key, "spec": spec}
+            if summary.get("confirm_ticket"):
+                retry_arguments["confirm_ticket"] = summary.get("confirm_ticket")
+            response = {
+                "status": "confirmation_required",
+                "error_code": None,
+                "recoverable": True,
+                "message": str(
+                    summary.get("message")
+                    or "destructive flow apply requires confirmation; nothing was changed"
+                ),
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {},
+                "details": {
+                    "apply_result": apply_result,
+                    "confirmation": summary,
+                },
+                "request_id": None,
+                "suggested_next_call": {
+                    "tool_name": "app_flow_apply",
+                    "arguments": retry_arguments,
+                },
+                "noop": False,
+                "warnings": [],
+                "verification": {"applied_spec_available": False, "confirmation_required": True},
+                "verified": False,
+                "app_key": app_key,
+                "write_executed": False,
+                "write_succeeded": False,
+                "safe_to_retry": True,
+            }
+            return finish(response)
         flow_spec_verify_started_at = time.perf_counter()
         verification, verify_warnings, verified = workflow_spec_api.verify_apply_response(
             input_spec=spec,
@@ -1491,6 +1974,74 @@ class AiBuilderFacade:
                 details={"solution_key": requested_solution_key},
                 suggested_next_call={"tool_name": "solution_install", "arguments": {"profile": profile, **normalized_args}},
             )
+        raw_result = created.get("result") if isinstance(created.get("result"), dict) else {}
+        raw_tag_ids = raw_result.get("tagIds")
+        raw_app_keys = raw_result.get("appKeys")
+        tag_ids, tag_ids_complete = _unique_resource_tag_ids(raw_tag_ids)
+        app_keys, app_keys_complete = _unique_resource_app_keys(raw_app_keys)
+        resource_list_complete = tag_ids_complete and app_keys_complete
+        resources: list[JSONObject] = []
+        warnings: list[JSONObject] = []
+
+        for tag_id in tag_ids:
+            name = None
+            try:
+                detail = self.packages.package_get(profile=profile, tag_id=tag_id, include_raw=False)
+                package = detail.get("result") if isinstance(detail.get("result"), dict) else {}
+                name = str(package.get("tagName") or package.get("tag_name") or "").strip() or None
+            except (QingflowApiError, RuntimeError):
+                pass
+            if not name:
+                warnings.append(_warning("RESOURCE_NAME_UNAVAILABLE", "installed package name could not be read", package_id=tag_id))
+            resources.append(
+                _compact_dict(
+                    {
+                        "resource_type": "package",
+                        "operation": "installed",
+                        "status": "success",
+                        "id": tag_id,
+                        "key": str(tag_id),
+                        "name": name,
+                        "ids": {"package_id": tag_id},
+                    }
+                )
+            )
+
+        for app_key in app_keys:
+            name = None
+            parent = None
+            try:
+                detail = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=False)
+                app = detail.get("result") if isinstance(detail.get("result"), dict) else {}
+                name = str(app.get("formTitle") or app.get("appName") or "").strip() or None
+                matching_tag_ids = [tag_id for tag_id in _unique_positive_ints(app.get("tagIds")) if tag_id in tag_ids]
+                if len(matching_tag_ids) == 1:
+                    parent = {"resource_type": "package", "id": matching_tag_ids[0], "key": str(matching_tag_ids[0])}
+            except (QingflowApiError, RuntimeError):
+                pass
+            if not name:
+                warnings.append(_warning("RESOURCE_NAME_UNAVAILABLE", "installed application name could not be read", app_key=app_key))
+            resources.append(
+                _compact_dict(
+                    {
+                        "resource_type": "app",
+                        "operation": "installed",
+                        "status": "success",
+                        "key": app_key,
+                        "name": name,
+                        "ids": {"app_key": app_key},
+                        "parent": parent,
+                    }
+                )
+            )
+
+        if not resource_list_complete:
+            warnings.append(
+                _warning(
+                    "RESOURCE_LIST_INCOMPLETE",
+                    "solution installation succeeded, but its returned package/application identity list was incomplete",
+                )
+            )
         return {
             "status": "success",
             "error_code": None,
@@ -1503,9 +2054,15 @@ class AiBuilderFacade:
             "request_id": created.get("request_id"),
             "suggested_next_call": None,
             "noop": False,
-            "verification": {},
+            "warnings": warnings,
+            "verified": False,
+            "verification": {
+                "resource_list_complete": resource_list_complete,
+                "business_verified": False,
+            },
             "write_executed": True,
             "safe_to_retry": False,
+            "resources": resources,
         }
 
     def package_list(self, *, profile: str, trial_status: str = "all", query: str = "") -> JSONObject:
@@ -1933,6 +2490,12 @@ class AiBuilderFacade:
             "error_code": None,
             "recoverable": False,
             "message": "resolved members",
+            "pagination": {
+                **(listed.get("data", {}).get("pagination", {})),
+                "page": page_num,
+                "page_size": page_size,
+                "returned_items": len(items),
+            },
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {},
@@ -1998,6 +2561,13 @@ class AiBuilderFacade:
             "error_code": None,
             "recoverable": False,
             "message": "resolved roles",
+            "pagination": {
+                "page": page_num,
+                "page_size": page_size,
+                "returned_items": len(items),
+                "reported_total": page.get("total"),
+                "page_amount": page.get("pageAmount"),
+            },
             "normalized_args": normalized_args,
             "missing_fields": [],
             "allowed_values": {},
@@ -6750,6 +7320,17 @@ class AiBuilderFacade:
                 normalized_args={"app_key": app_key},
                 suggested_next_call={"tool_name": "app_flow_get", "arguments": {"profile": profile, "app_key": app_key}},
             ))
+        # BEGIN temporary flow edit maintenance guard: remove this block when flow editing is restored.
+        # 既有 current 读之后的闸门判定（零新增请求）；通过后把 current 传给
+        # flow_apply 复用，避免二次读。
+        gate_block = _flow_edit_maintenance_gate(
+            current,
+            app_key=app_key,
+            normalized_args={"app_key": app_key},
+        )
+        if gate_block is not None:
+            return attach_patch_duration(gate_block)
+        # END temporary flow edit maintenance guard.
         flow_patch_compile_started_at = time.perf_counter()
         spec = deepcopy(current.get("spec") or {})
         if not isinstance(spec, dict) or not spec:
@@ -6814,6 +7395,7 @@ class AiBuilderFacade:
             ))
         flow_patch_compile_ms += _duration_ms(flow_patch_compile_started_at)
         flow_patch_apply_started_at = time.perf_counter()
+        patch_base_version = current.get("draft_version")
         result = self.flow_apply(
             profile=profile,
             app_key=app_key,
@@ -6821,6 +7403,8 @@ class AiBuilderFacade:
             publish=publish,
             idempotency_key=idempotency_key,
             schema_version=schema_version,
+            _prefetched_current_flow=current,
+            base_version=patch_base_version if isinstance(patch_base_version, int) else None,
         )
         flow_patch_apply_ms += _duration_ms(flow_patch_apply_started_at)
         return attach_patch_duration(result)
@@ -16497,6 +17081,106 @@ def _custom_button_upsert_payload_from_detail(
     return _compact_dict(payload)
 
 
+# 评测沉淀的瞬态业务码重试（视图基准 PERMISSION 318 教训，design §3 强制约束）：
+# apply 失败且 error_code 属于白名单时重试 1 次——权限读失败/权限数据传播延迟
+# 是可自愈的瞬态故障，裸抛会让长跑场景整轮报废。
+_FLOW_TRANSIENT_RETRY_CODES = {"APP_PERMISSION_UNVERIFIED", "PERMISSION_DENIED"}
+_FLOW_TRANSIENT_RETRY_DELAY_SECONDS = 2.0
+
+
+def _is_transient_flow_failure(response: JSONObject) -> bool:
+    if str(response.get("status") or "").strip().lower() != "failed":
+        return False
+    return str(response.get("error_code") or "") in _FLOW_TRANSIENT_RETRY_CODES
+
+
+def _public_flow_version_entry(entry: JSONObject) -> JSONObject:
+    """后端版本条目(camelCase)→ 公开稳定形状(snake_case),None 字段丢弃。
+
+    兼容后端 entity(createdAt 毫秒时间戳)与 meta(timestamp 字符串)两种条目形态。
+    """
+    from datetime import datetime, timezone
+
+    created_at_ms: int | None = None
+    raw_created_at = entry.get("createdAt")
+    if isinstance(raw_created_at, bool):
+        raw_created_at = None
+    if isinstance(raw_created_at, (int, float)):
+        created_at_ms = int(raw_created_at)
+    elif isinstance(raw_created_at, str) and raw_created_at.isdigit():
+        created_at_ms = int(raw_created_at)
+    created_at_iso: str | None = None
+    if created_at_ms is not None:
+        try:
+            created_at_iso = datetime.fromtimestamp(created_at_ms / 1000, tz=timezone.utc).isoformat()
+        except (OverflowError, OSError, ValueError):
+            created_at_iso = None
+    elif isinstance(entry.get("timestamp"), str):
+        created_at_iso = str(entry["timestamp"])
+    item: JSONObject = {
+        "version_id": entry.get("versionId"),
+        "snapshot_type": entry.get("snapshotType"),
+        "created_at_ms": created_at_ms,
+        "created_at_iso": created_at_iso,
+        "operator_name": entry.get("operatorName"),
+        "spec_hash": entry.get("specHash"),
+        "is_current": entry.get("isCurrent"),
+        "idempotency_key": entry.get("idempotencyKey"),
+    }
+    return {key: value for key, value in item.items() if value is not None}
+
+
+# BEGIN temporary flow edit maintenance guard: remove this helper block when flow editing is restored.
+def _flow_spec_node_count(flow_result: JSONObject) -> int | None:
+    spec = flow_result.get("spec")
+    if not isinstance(spec, dict):
+        return None
+    nodes = spec.get("nodes")
+    return len(nodes) if isinstance(nodes, list) else None
+
+
+def _flow_edit_maintenance_gate(
+    current_flow_result: JSONObject,
+    *,
+    app_key: str,
+    normalized_args: JSONObject,
+) -> JSONObject | None:
+    """流程编辑维护闸门：返回 None 放行，返回失败信封拦截。
+
+    CLI / MCP / 进程内评测统一在 facade 层判定；阈值经
+    get_flow_edit_maintenance_threshold() 读取（off/disabled/none 关闭）。
+    """
+    threshold = get_flow_edit_maintenance_threshold()
+    if threshold is None:
+        return None
+    node_count = _flow_spec_node_count(current_flow_result)
+    if node_count is None:
+        return _failed(
+            "FLOW_STATE_UNAVAILABLE",
+            "无法读取当前流程节点，未执行流程变更。",
+            normalized_args=normalized_args,
+            details={
+                "app_key": app_key,
+                "fix_hint": "当前流程状态无法确认，未执行流程变更。请稍后重试。",
+            },
+        )
+    if node_count > threshold:
+        return _failed(
+            "FLOW_EDIT_UNDER_MAINTENANCE",
+            "功能维护中，暂时不允许处理",
+            recoverable=True,
+            normalized_args=normalized_args,
+            details={
+                "app_key": app_key,
+                "current_node_count": node_count,
+                "maintenance_node_threshold": threshold,
+                "fix_hint": f"当前流程节点超过 {threshold} 个，流程编辑功能维护中；请稍后重试。",
+            },
+        )
+    return None
+# END temporary flow edit maintenance guard.
+
+
 def _failed(
     error_code: str,
     message: str,
@@ -16546,10 +17230,12 @@ def _failed_from_api_error(
         effective_error_code = "AUTH_REQUIRED"
     elif backend_code_int(error) == 40074:
         effective_error_code = "APP_EDIT_LOCKED"
+    elif _backend_result_code(error) == "BASE_VERSION_CONFLICT":
+        effective_error_code = "FLOW_SPEC_VERSION_CONFLICT"
     else:
         effective_error_code = error_code
     public_message = _public_error_message(effective_error_code, error)
-    public_http_status = None if error.http_status == 404 else error.http_status
+    # #162 D5：404 不再抹除 http_status，错误信封保留真实传输层事实
     merged_details = dict(details or {})
     if backend_code_int(error) == 40074:
         owner = _extract_edit_lock_owner(error.message)
@@ -16578,6 +17264,14 @@ def _failed_from_api_error(
                 "category": error.category,
             },
         )
+    backend_result = _backend_result_body(error)
+    if isinstance(backend_result, dict):
+        for key, value in backend_result.items():
+            # backend structured error body (e.g. BASE_VERSION_CONFLICT negotiation payload)
+            # merges in without overriding facade-provided details
+            if value is not None:
+                merged_details.setdefault(key, value)
+        merged_details.setdefault("backend_result", backend_result)
     result = _failed(
         effective_error_code,
         public_message,
@@ -16589,7 +17283,7 @@ def _failed_from_api_error(
         suggested_next_call=suggested_next_call,
         request_id=error.request_id,
         backend_code=error.backend_code,
-        http_status=public_http_status,
+        http_status=error.http_status,
     )
     if _is_environment_quota_code(error.backend_code):
         _mark_environment_quota_block(
@@ -17058,6 +17752,21 @@ def _coerce_api_error(error: Exception) -> QingflowApiError:
     return QingflowApiError(category="runtime", message=str(error))
 
 
+def _backend_result_body(error: QingflowApiError) -> JSONObject | None:
+    """Structured backend error body extracted by BackendClient (``ResponseResult.result``)."""
+    details = error.details
+    return details if isinstance(details, dict) else None
+
+
+def _backend_result_code(error: QingflowApiError) -> str | None:
+    body = _backend_result_body(error)
+    if isinstance(body, dict):
+        code = body.get("code")
+        if code is not None:
+            return str(code)
+    return None
+
+
 def _public_error_message(error_code: str, error: QingflowApiError) -> str:
     if backend_code_int(error) == 40074 or error_code == "APP_EDIT_LOCKED":
         owner = _extract_edit_lock_owner(error.message)
@@ -17067,6 +17776,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 = {
         "APP_READ_FAILED": "app base or schema is unavailable in the current route",
         "FIELDS_READ_FAILED": "app fields are unavailable in the current route",
@@ -17148,6 +17861,49 @@ def _coerce_positive_int(value: Any) -> int | None:
     return None
 
 
+def _unique_positive_ints(value: Any) -> list[int]:
+    if not isinstance(value, list):
+        return []
+    result: list[int] = []
+    for item in value:
+        number = _coerce_positive_int(item)
+        if number is not None and number not in result:
+            result.append(number)
+    return result
+
+
+def _unique_resource_tag_ids(value: Any) -> tuple[list[int], bool]:
+    if not isinstance(value, list):
+        return [], False
+    result: list[int] = []
+    complete = True
+    for item in value:
+        try:
+            tag_id = validate_positive_resource_id(item, "package_id")
+        except (ValueError, UnicodeError):
+            complete = False
+            continue
+        if tag_id not in result:
+            result.append(tag_id)
+    return result, complete
+
+
+def _unique_resource_app_keys(value: Any) -> tuple[list[str], bool]:
+    if not isinstance(value, list):
+        return [], False
+    result: list[str] = []
+    complete = True
+    for item in value:
+        try:
+            app_key = validate_resource_identity(item, "app_key")
+        except (ValueError, UnicodeError):
+            complete = False
+            continue
+        if app_key not in result:
+            result.append(app_key)
+    return result, complete
+
+
 def _coerce_nonnegative_int(value: Any) -> int | None:
     if isinstance(value, bool) or value is None:
         return None