@qingflow-tech/qingflow-app-builder-mcp 1.0.11 → 1.0.12

package/src/qingflow_mcp/solution/executor.py

@@ -5,7 +5,7 @@ from copy import deepcopy
 from typing import Any
 from uuid import uuid4
 
-from ..errors import QingflowApiError
+from ..errors import QingflowApiError, backend_code_int, is_auth_like_error
 from ..tools.app_tools import AppTools
 from ..tools.navigation_tools import NavigationTools
 from ..tools.package_tools import PackageTools
@@ -76,7 +76,8 @@ class SolutionExecutor:
             except Exception as exc:  # noqa: BLE001
                 store.record_step_failed(step.step_name, str(exc), debug_context=debug_context)
                 return store.summary()
-        store.mark_finished(status="success")
+        final_status = "partial_success" if _artifacts_have_post_write_readback_pending(store.data.get("artifacts", {})) else "success"
+        store.mark_finished(status=final_status)
         return store.summary()
 
     def _repair_start_index(self, compiled: CompiledSolution, store: RunArtifactStore) -> int:
@@ -203,6 +204,11 @@ class SolutionExecutor:
             dash_key = store.get_artifact("portal", "dash_key")
             if dash_key:
                 self.portal_tools.portal_publish(profile=profile, dash_key=dash_key)
+                store.set_artifact(
+                    "portal",
+                    "publish",
+                    {"published": True, "write_executed": True, "safe_to_retry": False},
+                )
                 self._refresh_portal_artifact(profile=profile, store=store, being_draft=False, artifact_key="published_result")
             return
         if step_name == "publish.navigation" and publish and compiled.normalized_spec.publish_policy.navigation:
@@ -347,7 +353,32 @@ class SolutionExecutor:
         updated_items.insert(insert_at, item)
         self.package_tools.package_sort_items(profile=profile, tag_id=tag_id, tag_items=updated_items)
 
-        verified_detail = _verify_package_attachment(self.package_tools, profile=profile, tag_id=tag_id, app_key=app_key)
+        try:
+            verified_detail = _verify_package_attachment(self.package_tools, profile=profile, tag_id=tag_id, app_key=app_key)
+        except Exception as exc:  # noqa: BLE001
+            api_error = _coerce_qingflow_error(exc)
+            if api_error is None or not _is_permission_restricted_error(api_error):
+                raise
+            store.set_artifact(
+                "package",
+                "attachment_readback",
+                _post_write_readback_artifact(
+                    resource="package_attach",
+                    target={"tag_id": tag_id, "app_key": app_key},
+                    error=api_error,
+                ),
+            )
+            self._record_package_attachment(
+                store,
+                entity.entity_id,
+                app_artifact,
+                tag_id=tag_id,
+                attached=True,
+                reused=False,
+                readback_status="unavailable",
+                readback_verified=False,
+            )
+            return
         verified_result = verified_detail.get("result") if isinstance(verified_detail.get("result"), dict) else {}
         verified_items = [deepcopy(existing) for existing in verified_result.get("tagItems", []) if isinstance(existing, dict)]
         if not any(_package_item_app_key(existing) == app_key for existing in verified_items):
@@ -369,12 +400,18 @@ class SolutionExecutor:
         tag_id: int,
         attached: bool,
         reused: bool,
+        readback_status: str = "verified",
+        readback_verified: bool = True,
     ) -> None:
         next_artifact = deepcopy(app_artifact)
         next_artifact["package_attachment"] = {
             "tag_id": tag_id,
             "attached": attached,
             "reused": reused,
+            "readback_status": readback_status,
+            "readback_verified": readback_verified,
+            "write_executed": not reused,
+            "safe_to_retry": reused or not attached,
         }
         store.set_artifact("apps", entity_id, next_artifact)
 
@@ -698,12 +735,23 @@ class SolutionExecutor:
                 api_error = _coerce_qingflow_error(exc)
                 if api_error is None or not _is_permission_restricted_error(api_error):
                     raise
-                raise _required_state_read_blocked_error(
-                    resource="portal",
-                    message=f"portal update requires readable draft state for dash '{dash_key}'",
-                    error=api_error,
-                    details={"dash_key": dash_key},
-                ) from exc
+                if not result:
+                    raise _required_state_read_blocked_error(
+                        resource="portal",
+                        message=f"portal update requires readable draft state for dash '{dash_key}'",
+                        error=api_error,
+                        details={"dash_key": dash_key},
+                    ) from exc
+                base_payload = {}
+                store.set_artifact(
+                    "portal",
+                    "draft_readback_before_update",
+                    _post_write_readback_artifact(
+                        resource="portal",
+                        target={"dash_key": dash_key, "phase": "created_portal_draft_readback"},
+                        error=api_error,
+                    ),
+                )
             update_payload = self._resolve_portal_payload(compiled.portal_plan["update_payload"], store, base_payload=base_payload)
             self.portal_tools.portal_update(profile=profile, dash_key=dash_key, payload=update_payload)
             self._refresh_portal_artifact(profile=profile, store=store, being_draft=True, artifact_key="draft_result")
@@ -744,7 +792,19 @@ class SolutionExecutor:
             return
         try:
             result = self.portal_tools.portal_get(profile=profile, dash_key=dash_key, being_draft=being_draft)
-        except Exception:  # noqa: BLE001
+        except Exception as exc:  # noqa: BLE001
+            api_error = _coerce_qingflow_error(exc)
+            if api_error is None:
+                raise
+            store.set_artifact(
+                "portal",
+                f"{artifact_key}_readback",
+                _post_write_readback_artifact(
+                    resource="portal",
+                    target={"dash_key": dash_key, "being_draft": being_draft, "artifact_key": artifact_key},
+                    error=api_error,
+                ),
+            )
             return
         store.set_artifact("portal", artifact_key, result)
         store.set_artifact("portal", "result", result)
@@ -2112,10 +2172,9 @@ def _has_explicit_workflow_global_settings(global_settings: dict[str, Any] | Non
 
 
 def _is_navigation_plugin_unavailable(error: QingflowApiError) -> bool:
-    try:
-        backend_code = int(error.backend_code)
-    except (TypeError, ValueError):
-        backend_code = None
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
     if backend_code != 50004:
         return False
     message = error.message or ""
@@ -2152,7 +2211,9 @@ def _coerce_qingflow_error(error: Exception) -> QingflowApiError | None:
 
 
 def _is_permission_restricted_error(error: QingflowApiError) -> bool:
-    return error.backend_code in {40002, 40027}
+    if is_auth_like_error(error):
+        return False
+    return backend_code_int(error) in {40002, 40027}
 
 
 def _required_state_read_blocked_error(
@@ -2182,6 +2243,42 @@ def _required_state_read_blocked_error(
     )
 
 
+def _post_write_readback_artifact(
+    *,
+    resource: str,
+    target: dict[str, Any],
+    error: QingflowApiError,
+) -> dict[str, Any]:
+    return {
+        "resource": resource,
+        "target": deepcopy(target),
+        "readback_status": "unavailable",
+        "readback_verified": False,
+        "write_executed": True,
+        "safe_to_retry": False,
+        "transport_error": {
+            "http_status": error.http_status,
+            "backend_code": error.backend_code,
+            "category": error.category,
+            "request_id": error.request_id,
+        },
+    }
+
+
+def _artifacts_have_post_write_readback_pending(value: Any) -> bool:
+    if isinstance(value, dict):
+        if (
+            value.get("write_executed") is True
+            and value.get("safe_to_retry") is False
+            and value.get("readback_status") == "unavailable"
+        ):
+            return True
+        return any(_artifacts_have_post_write_readback_pending(item) for item in value.values())
+    if isinstance(value, list):
+        return any(_artifacts_have_post_write_readback_pending(item) for item in value)
+    return False
+
+
 def _portal_component_position(
     source_type: Any,
     *,

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -15,7 +15,7 @@ from ..builder_facade.button_style_catalog import (
 )
 from ..public_surface import public_builder_contract_tool_names
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError
+from ..errors import QingflowApiError, backend_code_int
 from ..json_types import JSONObject
 from ..builder_facade.models import (
     AssociatedResourcesApplyRequest,
@@ -854,16 +854,23 @@ class AiBuilderTools(ToolBase):
         contain_disable: bool = False,
     ) -> JSONObject:
         """执行工具方法逻辑。"""
+        normalized_query = str(query or "").strip()
         normalized_args = {
-            "query": query,
+            "query": normalized_query,
             "page_num": page_num,
             "page_size": page_size,
             "contain_disable": contain_disable,
         }
+        if not normalized_query:
+            return _config_failure(
+                tool_name="member_search",
+                message="query is required for member_search; builder member lookup is a contact-directory path, not a record candidate fallback.",
+                fix_hint="For record member/department field ambiguity, use record member-candidates / department-candidates instead.",
+            )
         return _safe_tool_call(
             lambda: self._facade.member_search(
                 profile=profile,
-                query=query,
+                query=normalized_query,
                 page_num=page_num,
                 page_size=page_size,
                 contain_disable=contain_disable,
@@ -876,9 +883,16 @@ class AiBuilderTools(ToolBase):
     @tool_cn_name("角色检索")
     def role_search(self, *, profile: str, keyword: str, page_num: int = 1, page_size: int = 20) -> JSONObject:
         """执行角色相关逻辑。"""
-        normalized_args = {"keyword": keyword, "page_num": page_num, "page_size": page_size}
+        normalized_keyword = str(keyword or "").strip()
+        normalized_args = {"keyword": normalized_keyword, "page_num": page_num, "page_size": page_size}
+        if not normalized_keyword:
+            return _config_failure(
+                tool_name="role_search",
+                message="keyword is required for role_search; builder role lookup is a contact-management path, not a record candidate fallback.",
+                fix_hint="For record member/department field ambiguity, use record member-candidates / department-candidates instead.",
+            )
         return _safe_tool_call(
-            lambda: self._facade.role_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size),
+            lambda: self._facade.role_search(profile=profile, keyword=normalized_keyword, page_num=page_num, page_size=page_size),
             error_code="ROLE_SEARCH_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, **normalized_args}},
@@ -1820,6 +1834,9 @@ class AiBuilderTools(ToolBase):
             )
             public_shell = _publicize_package_fields(shell)
             resolved_key = str(public_shell.get("app_key") or "").strip()
+            shell_write_executed = _schema_apply_result_has_write(public_shell)
+            if shell_write_executed:
+                any_write_executed = True
             if public_shell.get("status") not in {"success", "partial_success"} or not resolved_key:
                 results.append({
                     "index": index,
@@ -1831,13 +1848,12 @@ class AiBuilderTools(ToolBase):
                     "stage": "resolve_or_create_shell",
                     "error_code": public_shell.get("error_code") or "APP_SHELL_APPLY_FAILED",
                     "message": public_shell.get("message") or "app shell resolve/create failed",
-                    "safe_to_retry": not any_write_executed,
+                    "write_executed": shell_write_executed,
+                    "safe_to_retry": not shell_write_executed and not any_write_executed,
                 })
                 continue
             if bool(public_shell.get("created")):
                 created_app_keys.append(resolved_key)
-            if _schema_apply_result_has_write(public_shell):
-                any_write_executed = True
             if client_key:
                 client_key_to_app_key[client_key] = resolved_key
             results.append({
@@ -2842,6 +2858,8 @@ def _merge_schema_field_diffs(*diffs: object) -> JSONObject:
 
 
 def _schema_apply_result_has_write(result: JSONObject) -> bool:
+    if "write_executed" in result:
+        return bool(result.get("write_executed"))
     if bool(result.get("created")) or bool(result.get("published")) or bool(result.get("app_base_updated")):
         return True
     field_diff = result.get("field_diff")
@@ -3831,7 +3849,7 @@ def _coerce_api_error(error: Exception) -> QingflowApiError:
 
 
 def _public_error_message(error_code: str, error: QingflowApiError) -> str:
-    if error.backend_code == 40074 or error_code == "APP_EDIT_LOCKED":
+    if backend_code_int(error) == 40074 or error_code == "APP_EDIT_LOCKED":
         return "app is currently locked by another active editor session"
     if error.http_status != 404:
         return error.message
@@ -4030,6 +4048,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "package_id maps internally to backend tagId; do not use tag_id in public calls",
             "items is a full package layout tree; omitting existing app/portal items is blocked unless allow_detach=true",
             "item shapes: {type:'app', app_key}, {type:'portal', dash_key}, or {type:'group', group_id?, name, items:[...]}",
+            "layout apply calls backend package ordering (MoveGroupAuth), so it requires package edit_app permission even when items=[] only clears/deletes existing groups",
             *_VISIBILITY_EXECUTION_NOTES,
         ],
         "minimal_example": {
@@ -4256,6 +4275,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id maps to current record id (-17), 编号/record_number maps to visible record number (0)",
             "to fill a target relation field with the current source record, map source_field='数据ID' to the target relation field; default_values is for static constants, not dynamic current-record values",
             "do not write raw que_relation unless maintaining a legacy config; field_mappings/default_values and que_relation are mutually exclusive",
+            "permission split follows backend routes: upsert_buttons/patch_buttons/remove_buttons require EditAppAuth; view_configs also requires ViewManagementAuth (beingViewManageStatus), which falls back to DataManageAuth when advanced app permissions are not enabled",
             "view_configs binds custom buttons into views in the same apply call; button_ref may be a same-call client_key, a button_id, or an exact unique existing button_text",
             "view_configs[].view_key is the raw builder view key from app_get.views[].view_key; do not pass record-data view_id values like custom:VIEW_KEY",
             "view_configs[].buttons is required in merge mode; omitting buttons is blocked to avoid no-op writes and accidental publish",
@@ -4399,6 +4419,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "this tool manages Qingflow in-app associated report/view display; it does not create or edit QingBI report bodies/configs",
             "create or edit app-source BI report bodies first with app_charts_apply, then attach the resulting chart_id here with graph_type=chart; dataset BI reports can only be attached when they already exist",
             "this is the default associated report/view path; it manages both the app-level associated resource pool and per-view display config",
+            "permission split follows backend routes: upsert_resources/patch_resources/remove/reorder require EditAppAuth; view_configs require ViewManagementAuth (beingViewManageStatus), which falls back to DataManageAuth when advanced app permissions are not enabled",
             "use patch_resources for partial parameter replacement on existing associated resources; the tool reads the current resource including backend-required raw fields, merges patch_resources[].set/unset, then submits the backend full-save payload internally",
             "associated_item_id is form_asos_chart.id from app_get.associated_resources[].associated_item_id; view_configs/remove/reorder may also pass an existing associated resource's chart_id/chart_key/view_key and the tool resolves it to the internal id",
             "before creating an associated resource, read app_get.associated_resources and reuse an existing item with patch_resources when target_app_key + view_key/chart_key already matches; repeated upsert_resources without associated_item_id can create duplicate associated items",
@@ -4587,6 +4608,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "use exactly one resource mode",
             "edit mode: app_key, optional app_name to rename the existing app",
             "create mode: package_id + app_name + create_if_missing=true",
+            "create mode follows backend CreateAppBean: package add_app permission is checked on the target package; package edit_app is not required for the create precheck",
             "multi-app mode: pass package_id + create_if_missing + apps[]; do not mix apps with top-level app_key/app_name/add_fields/update_fields/remove_fields",
             "multi-app relation fields may use target_app_ref to point at another apps[].client_key; the tool creates/resolves app shells first and compiles it to target_app_key",
             "multi-app mode is not transactional; read created_app_keys and apps[].status before retrying, and retry only failed app items",
@@ -4987,6 +5009,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             **deepcopy(_VISIBILITY_ALLOWED_VALUES),
         },
         "execution_notes": [
+            "creating a new view follows backend createViewgraphConfig and requires both ViewManagementAuth and DataManageAuth; updating/deleting existing views only requires ViewManagementAuth",
             "upsert_views[].visibility may set per-view visibility; omit it to preserve an existing view's auth or default a new view to workspace/not",
             "filters are saved fixed filters that apply when the view opens; query_conditions configure the frontend query panel and only apply after a user enters query values",
             "upsert_views[].query_conditions.rows is a layout matrix of field names; it is compiled to backend queryCondition queIds",
@@ -5111,6 +5134,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
         "execution_notes": [
             "apply may return partial_success when some views land and others fail",
+            "creating a new view follows backend createViewgraphConfig and requires both ViewManagementAuth and DataManageAuth; updating/deleting existing views only requires ViewManagementAuth",
             "when duplicate view names exist, supply view_key to target the exact view",
             "read back app_get after any failed or partial view apply",
             "view existence verification and saved-filter verification are separate; treat filters as unverified until verification.view_filters_verified is true",
@@ -5196,8 +5220,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "returns builder-side app map: base summary, editability, field/view/chart/button counts, compact views, compact charts, custom_buttons, and app-level associated_resources",
             "use this as the default builder discovery read before view_get/chart_get/apply detail work",
             "editability is route-aware builder capability summary, not end-user data visibility",
-            "can_edit_app_base covers app base-info writes such as app_name, icon, and visibility",
-            "can_edit_form covers form/schema routes only and does not imply app base-info writes",
+            "can_edit_app_base covers app base-info writes such as app_name, icon, and visibility; it follows backend EditAppAuth and does not require package edit_tag",
+            "can_edit_form covers form/schema routes and also follows backend EditAppAuth",
             "returns normalized app visibility when backend auth is readable",
             "custom_buttons[].button_id is the id required by app_custom_buttons_apply view_configs[].buttons[].button_ref",
             "associated_resources[].associated_item_id is the internal id; app_associated_resources_apply.view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key",
@@ -5413,6 +5437,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "use exactly one resource mode",
             "update mode: dash_key",
             "create mode: package_id + dash_name",
+            "create mode follows backend DashCtrl.createDash: package add_app permission is checked on the target package; package edit_app is not required for the create precheck",
             "create mode requires explicit icon + color; icon=template is blocked because it is too generic",
             "edit mode preserves existing icon/color when omitted; explicit icon/color values are still validated",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",