@josephyan/qingflow-app-builder-mcp 0.2.0-beta.6 → 0.2.0-beta.7

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.6
+npm install @josephyan/qingflow-app-builder-mcp@0.2.0-beta.7
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.6 qingflow-app-builder-mcp
+npx -y -p @josephyan/qingflow-app-builder-mcp@0.2.0-beta.7 qingflow-app-builder-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-builder-mcp",
-  "version": "0.2.0-beta.6",
+  "version": "0.2.0-beta.7",
   "description": "Builder MCP for Qingflow app/package/system design and staged solution workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "qingflow-mcp"
-version = "0.2.0b6"
+version = "0.2.0b7"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/skills/qingflow-app-builder/SKILL.md

@@ -21,7 +21,7 @@ Pick the smallest tool layer that can finish the task.
 - File upload: `file_upload_local`
 - Resource resolve/read: `package_list`, `package_resolve`, `app_resolve`, `app_read_summary`, `app_read_fields`, `app_read_layout_summary`, `app_read_views_summary`, `app_read_flow_summary`
 - Resource plan: `app_schema_plan`, `app_layout_plan`, `app_flow_plan`, `app_views_plan`
-- Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `package_attach_app`
+- Resource patch: `app_schema_apply`, `app_layout_apply`, `app_flow_apply`, `app_views_apply`, `package_attach_app`, `app_release_edit_lock_if_mine`
 - Publish and verify: `app_publish_verify`
 
 Note:
@@ -55,6 +55,7 @@ For builder work:
 8. Use `app_flow_apply` after schema exists. It publishes by default.
 9. Use `app_views_apply` when the user wants explicit list/card/board views. It publishes by default.
 10. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need an explicit verification pass.
+11. If a write fails with `APP_EDIT_LOCKED`, stop normal writes. Only use `app_release_edit_lock_if_mine` when the failed result shows the lock owner is the current logged-in user.
 
 In `prod`, keep `plan` and `apply` as separate phases unless the user explicitly asks for a direct live execution.
 
@@ -74,6 +75,7 @@ For additive work on existing systems:
 - `package_attach_app` is the source of truth for package ownership; do not assume app creation or publish implicitly attaches the app.
 - `relation` and `subtable` must be explicit; do not infer them from vague natural language.
 - In `prod`, prefer explicit patch tools and avoid any speculative create flow.
+- Never try to bypass collaborative edit locks. `app_release_edit_lock_if_mine` is only for the case where the lock owner is the current authenticated user.
 
 ## Response Interpretation
 
@@ -101,6 +103,7 @@ For additive work on existing systems:
 - Replace workflow: `app_flow_apply`
 - Upsert/remove views: `app_views_apply`
 - Attach one app to a package: `package_attach_app`
+- Release your own stale edit lock: `app_release_edit_lock_if_mine`
 - Publish and verify: `app_publish_verify` when you need a separate verification pass beyond the default auto-publish behavior in apply tools
 
 Detailed playbooks:

package/src/qingflow_mcp/__init__.py

@@ -2,4 +2,4 @@ from __future__ import annotations
 
 __all__ = ["__version__"]
 
-__version__ = "0.2.0b6"
+__version__ = "0.2.0b7"

package/src/qingflow_mcp/builder_facade/service.py

@@ -4,6 +4,7 @@ from copy import deepcopy
 from dataclasses import dataclass
 import json
 import os
+import re
 import tempfile
 from typing import Any
 from uuid import uuid4
@@ -210,6 +211,114 @@ class AiBuilderFacade:
             "attached": attached,
         }
 
+    def app_release_edit_lock_if_mine(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        lock_owner_email: str = "",
+        lock_owner_name: str = "",
+    ) -> JSONObject:
+        normalized_args = {
+            "app_key": app_key,
+            "lock_owner_email": lock_owner_email,
+            "lock_owner_name": lock_owner_name,
+        }
+        session_profile = self.apps.sessions.get_profile(profile)
+        if session_profile is None:
+            return _failed(
+                "AUTH_REQUIRED",
+                "auth profile is required before releasing an app edit lock",
+                normalized_args=normalized_args,
+                recoverable=False,
+                suggested_next_call={"tool_name": "auth_whoami", "arguments": {"profile": profile}},
+            )
+        current_email = str(session_profile.email or "").strip().lower()
+        current_name = str(session_profile.nick_name or "").strip()
+        requested_owner_email = str(lock_owner_email or "").strip().lower()
+        requested_owner_name = str(lock_owner_name or "").strip()
+        if not requested_owner_email and not requested_owner_name:
+            return _failed(
+                "EDIT_LOCK_OWNER_UNKNOWN",
+                "lock owner could not be verified; refuse to release edit lock blindly",
+                normalized_args=normalized_args,
+                recoverable=False,
+                details={
+                    "current_user_email": session_profile.email,
+                    "current_user_name": session_profile.nick_name,
+                },
+                suggested_next_call=None,
+            )
+        owner_matches = True
+        if requested_owner_email:
+            owner_matches = bool(current_email) and current_email == requested_owner_email
+        elif requested_owner_name:
+            owner_matches = bool(current_name) and current_name == requested_owner_name
+        if not owner_matches:
+            return _failed(
+                "EDIT_LOCK_HELD_BY_OTHER_USER",
+                "edit lock is owned by another user; refusing to release it",
+                normalized_args=normalized_args,
+                recoverable=False,
+                details={
+                    "lock_owner_email": requested_owner_email or None,
+                    "lock_owner_name": requested_owner_name or None,
+                    "current_user_email": session_profile.email,
+                    "current_user_name": session_profile.nick_name,
+                },
+                suggested_next_call=None,
+            )
+        try:
+            version_result = self.apps.app_get_edit_version_no(profile=profile, app_key=app_key).get("result") or {}
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "EDIT_LOCK_RELEASE_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        edit_version_no = _coerce_positive_int(version_result.get("editVersionNo") or version_result.get("versionNo")) or 1
+        try:
+            self.apps.app_edit_finished(profile=profile, app_key=app_key, payload={"editVersionNo": edit_version_no})
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "EDIT_LOCK_RELEASE_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={
+                    "app_key": app_key,
+                    "edit_version_no": edit_version_no,
+                    "lock_owner_email": requested_owner_email or None,
+                    "lock_owner_name": requested_owner_name or None,
+                },
+                suggested_next_call={"tool_name": "app_release_edit_lock_if_mine", "arguments": {"profile": profile, **normalized_args}},
+            )
+        return {
+            "status": "success",
+            "error_code": None,
+            "recoverable": False,
+            "message": "released app edit lock owned by current user",
+            "normalized_args": normalized_args,
+            "missing_fields": [],
+            "allowed_values": {},
+            "details": {
+                "lock_owner_email": requested_owner_email or None,
+                "lock_owner_name": requested_owner_name or None,
+                "current_user_email": session_profile.email,
+                "current_user_name": session_profile.nick_name,
+                "edit_version_no": edit_version_no,
+            },
+            "request_id": None,
+            "suggested_next_call": {"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            "noop": False,
+            "verification": {"released": True},
+            "app_key": app_key,
+            "released": True,
+        }
+
     def app_resolve(
         self,
         *,
@@ -1347,7 +1456,20 @@ class AiBuilderFacade:
         if stage.get("status") != "success":
             failed = _normalize_flow_stage_failure(stage, profile=profile, app_key=app_key, entity=entity)
             failed["normalized_args"] = normalized_args
-            failed["suggested_next_call"] = failed.get("suggested_next_call") or {"tool_name": "app_flow_plan", "arguments": {"profile": profile, **normalized_args}}
+            suggested_next_call = failed.get("suggested_next_call")
+            if not isinstance(suggested_next_call, dict):
+                suggested_next_call = {"tool_name": "app_flow_plan", "arguments": {"profile": profile, **normalized_args}}
+            elif suggested_next_call.get("tool_name") == "app_flow_plan":
+                arguments = suggested_next_call.get("arguments")
+                if not isinstance(arguments, dict):
+                    arguments = {}
+                arguments.setdefault("profile", profile)
+                arguments.setdefault("app_key", app_key)
+                arguments.setdefault("mode", mode)
+                arguments.setdefault("nodes", nodes)
+                arguments.setdefault("transitions", transitions)
+                suggested_next_call["arguments"] = arguments
+            failed["suggested_next_call"] = suggested_next_call
             return failed
         verified_nodes, verified_nodes_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
         response = {
@@ -1511,6 +1633,33 @@ class AiBuilderFacade:
                     created.append(patch.name)
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
+                if api_error.backend_code == 48104:
+                    try:
+                        if existing_key or created_key:
+                            target_key = created_key or existing_key or ""
+                            fallback_payload = _build_minimal_view_payload(
+                                app_key=app_key,
+                                schema=schema,
+                                patch=patch,
+                                ordinal=ordinal,
+                            )
+                            self.views.view_update(profile=profile, viewgraph_key=target_key, payload=fallback_payload)
+                            if existing_key:
+                                updated.append(patch.name)
+                            else:
+                                created.append(patch.name)
+                            continue
+                        fallback_payload = _build_minimal_view_payload(
+                            app_key=app_key,
+                            schema=schema,
+                            patch=patch,
+                            ordinal=ordinal,
+                        )
+                        self.views.view_create(profile=profile, payload=fallback_payload)
+                        created.append(patch.name)
+                        continue
+                    except (QingflowApiError, RuntimeError) as fallback_error:
+                        api_error = _coerce_api_error(fallback_error)
                 if created_key:
                     try:
                         self.views.view_delete(profile=profile, viewgraph_key=created_key)
@@ -1526,6 +1675,7 @@ class AiBuilderFacade:
                         "view_type": patch.type.value,
                         "columns": patch.columns,
                         "group_by": patch.group_by,
+                        "operation": "update" if existing_key or created_key else "create",
                     },
                     suggested_next_call={
                         "tool_name": "app_views_plan",
@@ -2032,9 +2182,28 @@ def _failed_from_api_error(
     suggested_next_call: JSONObject | None = None,
     recoverable: bool = True,
 ) -> JSONObject:
-    public_message = _public_error_message(error_code, error)
+    effective_error_code = "APP_EDIT_LOCKED" if error.backend_code == 40074 else error_code
+    public_message = _public_error_message(effective_error_code, error)
     public_http_status = None if error.http_status == 404 else error.http_status
     merged_details = dict(details or {})
+    if error.backend_code == 40074:
+        owner = _extract_edit_lock_owner(error.message)
+        merged_details.setdefault("lock_owner_name", owner.get("lock_owner_name"))
+        merged_details.setdefault("lock_owner_email", owner.get("lock_owner_email"))
+        app_key = None
+        if isinstance(normalized_args, dict):
+            app_key = normalized_args.get("app_key")
+        if not app_key and isinstance(details, dict):
+            app_key = details.get("app_key")
+        if isinstance(app_key, str) and app_key.strip():
+            suggested_next_call = {
+                "tool_name": "app_release_edit_lock_if_mine",
+                "arguments": {
+                    "app_key": app_key,
+                    "lock_owner_name": owner.get("lock_owner_name") or "",
+                    "lock_owner_email": owner.get("lock_owner_email") or "",
+                },
+            }
     if error.http_status is not None or error.backend_code is not None:
         merged_details.setdefault(
             "transport_error",
@@ -2045,7 +2214,7 @@ def _failed_from_api_error(
             },
         )
     return _failed(
-        error_code,
+        effective_error_code,
         public_message,
         recoverable=recoverable,
         normalized_args=normalized_args,
@@ -2095,6 +2264,12 @@ 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":
+        owner = _extract_edit_lock_owner(error.message)
+        owner_label = owner.get("lock_owner_email") or owner.get("lock_owner_name")
+        if owner_label:
+            return f"app is currently locked by active editor {owner_label}"
+        return "app is currently locked by another active editor session"
     if error.http_status != 404:
         return error.message
     mapping = {
@@ -2111,10 +2286,29 @@ def _public_error_message(error_code: str, error: QingflowApiError) -> str:
         "VIEW_APPLY_FAILED": "view resource rejected the operation or is unavailable in the current route",
         "LAYOUT_APPLY_FAILED": "layout resource rejected the operation or is unavailable in the current route",
         "SCHEMA_APPLY_FAILED": "schema resource rejected the operation or is unavailable in the current route",
+        "EDIT_LOCK_RELEASE_FAILED": "edit lock release route is unavailable in the current route",
     }
     return mapping.get(error_code, "requested builder resource is unavailable in the current route")
 
 
+def _extract_edit_lock_owner(message: str) -> JSONObject:
+    text = str(message or "").strip()
+    if not text:
+        return {"lock_owner_name": None, "lock_owner_email": None}
+    patterns = [
+        r"应用已被\s*(?P<name>[^（(]+?)\s*[（(](?P<email>[^）)]+)[）)]\s*编辑",
+        r"edited by\s*(?P<name>[^<(]+?)\s*<(?P<email>[^>]+)>",
+    ]
+    for pattern in patterns:
+        match = re.search(pattern, text)
+        if match:
+            return {
+                "lock_owner_name": match.groupdict().get("name", "").strip() or None,
+                "lock_owner_email": match.groupdict().get("email", "").strip() or None,
+            }
+    return {"lock_owner_name": None, "lock_owner_email": None}
+
+
 def _coerce_positive_int(value: Any) -> int | None:
     if isinstance(value, bool) or value is None:
         return None
@@ -2851,19 +3045,17 @@ def _build_view_create_payload(
     payload["auth"] = default_member_auth()
     payload.setdefault("sortType", "defaultSort")
     payload.setdefault("viewgraphSorts", [{"queId": 0, "beingSortAscend": True, "queType": 8}])
-    payload.setdefault("beingPinNavigate", True)
-    payload.setdefault("beingShowCover", False)
-    payload.setdefault("defaultRowHigh", "compact")
-    payload.setdefault("asosChartVisible", False)
-    payload.setdefault("viewgraphLimitType", 1)
-    payload.setdefault("viewgraphLimit", [])
-    payload.setdefault("buttonConfigDTOList", [])
     if patch.type.value in {"card", "board"}:
         payload["beingShowTitleQue"] = True
         payload["titleQue"] = visible_que_ids[0] if visible_que_ids else None
     if patch.type.value == "board":
         payload["groupQueId"] = field_map.get(patch.group_by or "")
-    return payload
+    return _hydrate_view_backend_payload(
+        payload=payload,
+        view_type=patch.type.value,
+        visible_que_id_values=visible_que_ids,
+        group_que_id=field_map.get(patch.group_by or "") if patch.group_by else None,
+    )
 
 
 def _build_form_payload_from_existing_schema(
@@ -3055,7 +3247,109 @@ def _build_view_update_payload(
         payload["beingShowTitleQue"] = True
         payload["titleQue"] = visible_que_id_values[0] if visible_que_id_values else None
         payload["groupQueId"] = field_map.get(patch.group_by or "")
-    return payload
+    return _hydrate_view_backend_payload(
+        payload=payload,
+        view_type=normalized_type,
+        visible_que_id_values=visible_que_id_values,
+        group_que_id=field_map.get(patch.group_by or "") if patch.group_by else None,
+    )
+
+
+def _build_minimal_view_payload(
+    *,
+    app_key: str,
+    schema: dict[str, Any],
+    patch: ViewUpsertPatch,
+    ordinal: int,
+) -> JSONObject:
+    field_map = extract_field_map(schema)
+    visible_que_id_values = [field_map[name] for name in patch.columns if name in field_map]
+    payload: JSONObject = {
+        "appKey": app_key,
+        "viewgraphName": patch.name,
+        "viewgraphType": {
+            "table": "tableView",
+            "card": "cardView",
+            "board": "boardView",
+        }[patch.type.value],
+        "ordinal": ordinal,
+        "viewgraphQueIds": visible_que_id_values,
+        "viewgraphQuestions": _build_viewgraph_questions(schema, visible_que_id_values),
+        "auth": default_member_auth(),
+    }
+    if patch.type.value in {"card", "board"}:
+        payload["beingShowTitleQue"] = True
+        payload["titleQue"] = visible_que_id_values[0] if visible_que_id_values else None
+    if patch.type.value == "board":
+        payload["groupQueId"] = field_map.get(patch.group_by or "")
+    return _hydrate_view_backend_payload(
+        payload=payload,
+        view_type=patch.type.value,
+        visible_que_id_values=visible_que_id_values,
+        group_que_id=field_map.get(patch.group_by or "") if patch.group_by else None,
+    )
+
+
+def _hydrate_view_backend_payload(
+    *,
+    payload: JSONObject,
+    view_type: str,
+    visible_que_id_values: list[int],
+    group_que_id: int | None,
+) -> JSONObject:
+    data = deepcopy(payload)
+    data.setdefault("beingPinNavigate", True)
+    data.setdefault("beingNeedPass", False)
+    data.setdefault("beingShowTitleQue", view_type in {"card", "board"})
+    data.setdefault("beingShowCover", False)
+    data.setdefault("defaultRowHigh", "compact")
+    data.setdefault("asosChartVisible", False)
+    data.setdefault("viewgraphPass", "")
+    data.setdefault("beingGroupColor", False)
+    data.setdefault("beingShowQueTitle", True)
+    data.setdefault("beingImageAdaption", False)
+    data.setdefault("clippingMode", "default")
+    data.setdefault("frontCoverQueId", None)
+    data.setdefault("viewgraphLimitType", 1)
+    data.setdefault("viewgraphLimit", [])
+    data.setdefault("viewgraphLimitFormula", "")
+    data.setdefault("sortType", "defaultSort")
+    if not data.get("viewgraphSorts"):
+        sort_que_id = visible_que_id_values[0] if visible_que_id_values else 1
+        data["viewgraphSorts"] = [{"queId": sort_que_id, "beingSortAscend": True}]
+    data.setdefault("beingAuditRecordVisible", True)
+    data.setdefault("beingQrobotRecordVisible", False)
+    data.setdefault("beingPrintStatus", False)
+    data.setdefault("beingDefaultPrintTplStatus", False)
+    data.setdefault("printTpls", [])
+    data.setdefault("beingCommentStatus", False)
+    data.setdefault("usages", [])
+    data.setdefault("dataPermissionType", "CUSTOM")
+    data.setdefault("dataScope", "ALL")
+    data.setdefault("needPass", False)
+    data.setdefault("beingWorkflowNodeFutureListVisible", True)
+    data.setdefault("asosChartConfig", {"limitType": 1, "asosChartIdList": []})
+    data.setdefault("viewgraphGanttConfigVO", None)
+    data.setdefault("viewgraphHierarchyConfigVO", None)
+    data.setdefault("buttonConfigDTOList", [])
+    if "buttonConfig" not in data:
+        data["buttonConfig"] = {"topButtonList": [], "mainButtonDetailList": [], "moreButtonDetailList": []}
+    if view_type == "table":
+        data["viewgraphType"] = "tableView"
+        data["beingShowTitleQue"] = False
+        data["titleQue"] = None
+        data["groupQueId"] = None
+    elif view_type == "card":
+        data["viewgraphType"] = "cardView"
+        data["beingShowTitleQue"] = True
+        data["titleQue"] = visible_que_id_values[0] if visible_que_id_values else None
+        data["groupQueId"] = None
+    elif view_type == "board":
+        data["viewgraphType"] = "boardView"
+        data["beingShowTitleQue"] = True
+        data["titleQue"] = visible_que_id_values[0] if visible_que_id_values else None
+        data["groupQueId"] = group_que_id
+    return data
 
 
 def _infer_status_field_id(fields: list[dict[str, Any]]) -> str | None:
@@ -3142,14 +3436,25 @@ def _normalize_flow_stage_failure(stage: JSONObject, *, profile: str, app_key: s
             backend_code=backend_code,
             http_status=http_status,
         )
+    message = detail_text or "failed to apply workflow patch"
+    details = {"app_key": app_key, "entity_id": entity.get("entity_id"), "stage_result": public_stage_result}
+    public_http_status = http_status
+    if http_status == 404:
+        message = "workflow write route is unavailable for this app in the current route"
+        details["transport_error"] = {
+            "http_status": http_status,
+            "backend_code": backend_code,
+            "category": "http",
+        }
+        public_http_status = None
     return _failed(
         stage_error_code,
-        detail_text or "failed to apply workflow patch",
-        details={"app_key": app_key, "entity_id": entity.get("entity_id"), "stage_result": public_stage_result},
+        message,
+        details=details,
         suggested_next_call={"tool_name": "app_flow_plan", "arguments": {"profile": profile, "app_key": app_key}},
         request_id=request_id,
         backend_code=backend_code,
-        http_status=http_status,
+        http_status=public_http_status,
     )
 
 

package/src/qingflow_mcp/server_app_builder.py

@@ -22,6 +22,7 @@ def build_builder_server() -> FastMCP:
             "app_schema_plan/app_layout_plan/app_flow_plan/app_views_plan before writes when the target patch is non-trivial, "
             "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply to execute normalized patches; these apply tools publish by default unless publish=false. "
             "Use package_attach_app to attach apps to packages, and app_publish_verify for explicit final publish verification. "
+            "If builder writes are blocked by the current user's own edit lock, use app_release_edit_lock_if_mine with the lock owner details from the failed result. "
             "Do not handcraft internal solution payloads or rely on build_id/stage/repair."
         ),
     )
@@ -133,6 +134,20 @@ def build_builder_server() -> FastMCP:
     ) -> dict:
         return ai_builder.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title)
 
+    @server.tool()
+    def app_release_edit_lock_if_mine(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        lock_owner_email: str = "",
+        lock_owner_name: str = "",
+    ) -> dict:
+        return ai_builder.app_release_edit_lock_if_mine(
+            profile=profile,
+            app_key=app_key,
+            lock_owner_email=lock_owner_email,
+            lock_owner_name=lock_owner_name,
+        )
+
     @server.tool()
     def app_resolve(
         profile: str = DEFAULT_PROFILE,

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -59,6 +59,20 @@ class AiBuilderTools(ToolBase):
         ) -> JSONObject:
             return self.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title)
 
+        @mcp.tool()
+        def app_release_edit_lock_if_mine(
+            profile: str = DEFAULT_PROFILE,
+            app_key: str = "",
+            lock_owner_email: str = "",
+            lock_owner_name: str = "",
+        ) -> JSONObject:
+            return self.app_release_edit_lock_if_mine(
+                profile=profile,
+                app_key=app_key,
+                lock_owner_email=lock_owner_email,
+                lock_owner_name=lock_owner_name,
+            )
+
         @mcp.tool()
         def app_resolve(
             profile: str = DEFAULT_PROFILE,
@@ -269,6 +283,31 @@ class AiBuilderTools(ToolBase):
             suggested_next_call={"tool_name": "package_attach_app", "arguments": {"profile": profile, **normalized_args}},
         )
 
+    def app_release_edit_lock_if_mine(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        lock_owner_email: str = "",
+        lock_owner_name: str = "",
+    ) -> JSONObject:
+        normalized_args = {
+            "app_key": app_key,
+            "lock_owner_email": lock_owner_email,
+            "lock_owner_name": lock_owner_name,
+        }
+        return _safe_tool_call(
+            lambda: self._facade.app_release_edit_lock_if_mine(
+                profile=profile,
+                app_key=app_key,
+                lock_owner_email=lock_owner_email,
+                lock_owner_name=lock_owner_name,
+            ),
+            error_code="EDIT_LOCK_RELEASE_FAILED",
+            normalized_args=normalized_args,
+            suggested_next_call={"tool_name": "app_release_edit_lock_if_mine", "arguments": {"profile": profile, **normalized_args}},
+        )
+
     def app_resolve(self, *, profile: str, app_key: str = "", app_name: str = "", package_tag_id: int | None = None) -> JSONObject:
         normalized_args = {"app_key": app_key, "app_name": app_name, "package_tag_id": package_tag_id}
         return _safe_tool_call(
@@ -779,6 +818,8 @@ 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":
+        return "app is currently locked by another active editor session"
     if error.http_status != 404:
         return error.message
     mapping = {

package/src/qingflow_mcp/tools/workflow_tools.py

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 from mcp.server.fastmcp import FastMCP
 
+from ..backend_client import BackendRequestContext
 from ..config import DEFAULT_PROFILE
 from ..errors import QingflowApiError, raise_tool_error
 from ..json_types import JSONObject, JSONValue
@@ -70,13 +71,28 @@ class WorkflowTools(ToolBase):
     def workflow_add_node(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
         self._require_app_key(app_key)
         body = self._require_dict(payload)
-        return self._request(profile, "POST", f"/app/{app_key}/auditNodes", app_key=app_key, json_body=body)
+        return self._request_with_post_fallbacks(
+            profile=profile,
+            app_key=app_key,
+            path=f"/app/{app_key}/auditNodes",
+            json_body=body,
+            alternate_paths=[f"/app/{app_key}/auditNode"],
+        )
 
     def workflow_update_node(self, *, profile: str, app_key: str, audit_node_id: int, payload: JSONObject) -> JSONObject:
         self._require_app_key(app_key)
         self._require_positive("audit_node_id", audit_node_id)
         body = self._require_dict(payload)
-        return self._request(profile, "POST", f"/app/{app_key}/auditNodes/{audit_node_id}", app_key=app_key, audit_node_id=audit_node_id, json_body=body, risk_operation="update", risk_target="workflow node configuration")
+        return self._request_with_post_fallbacks(
+            profile=profile,
+            app_key=app_key,
+            path=f"/app/{app_key}/auditNodes/{audit_node_id}",
+            json_body=body,
+            alternate_paths=[f"/app/{app_key}/auditNode/{audit_node_id}"],
+            risk_operation="update",
+            risk_target="workflow node configuration",
+            audit_node_id=audit_node_id,
+        )
 
     def workflow_delete_node(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
         self._require_app_key(app_key)
@@ -110,12 +126,26 @@ class WorkflowTools(ToolBase):
     def workflow_update_global_settings(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
         self._require_app_key(app_key)
         body = self._require_dict(payload)
-        return self._request(profile, "POST", f"/app/{app_key}/workflow/global/setting", app_key=app_key, json_body=body, risk_operation="update", risk_target="workflow global settings")
+        return self._request_with_post_fallbacks(
+            profile=profile,
+            app_key=app_key,
+            path=f"/app/{app_key}/workflow/global/setting",
+            json_body=body,
+            alternate_paths=[],
+            risk_operation="update",
+            risk_target="workflow global settings",
+        )
 
     def workflow_publish(self, *, profile: str, app_key: str, payload: JSONObject) -> JSONObject:
         self._require_app_key(app_key)
         body = self._require_dict(payload)
-        return self._request(profile, "POST", f"/app/{app_key}/publish", app_key=app_key, json_body=body)
+        return self._request_with_post_fallbacks(
+            profile=profile,
+            app_key=app_key,
+            path=f"/app/{app_key}/publish",
+            json_body=body,
+            alternate_paths=[],
+        )
 
     def workflow_get_future_nodes(self, *, profile: str, app_key: str, apply_id: int) -> JSONObject:
         self._require_app_key(app_key)
@@ -229,6 +259,50 @@ class WorkflowTools(ToolBase):
 
         return self._run(profile, runner)
 
+    def _request_with_post_fallbacks(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        path: str,
+        json_body: JSONObject,
+        alternate_paths: list[str],
+        risk_operation: str | None = None,
+        risk_target: str | None = None,
+        **extra: JSONValue,
+    ) -> JSONObject:
+        def runner(session_profile, context):
+            attempted_contexts = [context]
+            if context.qf_version is not None:
+                attempted_contexts.append(
+                    BackendRequestContext(
+                        base_url=context.base_url,
+                        token=context.token,
+                        ws_id=context.ws_id,
+                        qf_version=None,
+                        qf_version_source="workflow_retry_without_qf_version",
+                    )
+                )
+            paths = [path, *alternate_paths]
+            last_error: QingflowApiError | None = None
+            for call_context in attempted_contexts:
+                for candidate_path in paths:
+                    try:
+                        result = self.backend.request("POST", call_context, candidate_path, json_body=json_body)
+                        response: JSONObject = {"profile": profile, "ws_id": session_profile.selected_ws_id, "result": result}
+                        response.update(extra)
+                        if risk_operation and risk_target:
+                            return self._attach_human_review_notice(response, operation=risk_operation, target=risk_target)
+                        return response
+                    except QingflowApiError as error:
+                        last_error = error
+                        if error.http_status != 404:
+                            raise
+            assert last_error is not None
+            raise last_error
+
+        return self._run(profile, runner)
+
     def _require_app_key(self, app_key: str) -> None:
         if not app_key:
             raise_tool_error(QingflowApiError.config_error("app_key is required"))