@josephyan/qingflow-app-user-mcp 0.2.0-beta.6 → 0.2.0-beta.8

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-app-user-mcp",
-  "version": "0.2.0-beta.6",
+  "version": "0.2.0-beta.8",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory 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.0b8"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/builder_facade/models.py

@@ -332,6 +332,8 @@ def _normalize_field_payload(value: Any) -> Any:
     if not isinstance(value, dict):
         return value
     payload = dict(value)
+    if "fields" in payload and "subfields" not in payload:
+        payload["subfields"] = payload.pop("fields")
     raw_type = payload.get("type")
     if isinstance(raw_type, str):
         normalized = FIELD_TYPE_ALIASES.get(raw_type.strip().lower())

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,115 @@ 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}},
+            )
+        identity = self._resolve_current_user_identity(profile=profile)
+        current_email = str(identity.get("email") or "").strip().lower()
+        current_name = str(identity.get("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": identity.get("email"),
+                    "current_user_name": identity.get("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": identity.get("email"),
+                    "current_user_name": identity.get("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": identity.get("email"),
+                "current_user_name": identity.get("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 +1457,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 +1634,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 +1676,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",
@@ -1968,6 +2119,33 @@ class AiBuilderFacade:
         payload.setdefault("ws_id", session_profile.selected_ws_id)
         return payload
 
+    def _resolve_current_user_identity(self, *, profile: str) -> JSONObject:
+        session_profile = self.apps.sessions.get_profile(profile)
+        backend_session = self.apps.sessions.get_backend_session(profile)
+        current_email = str((session_profile.email if session_profile else None) or "").strip()
+        current_name = str((session_profile.nick_name if session_profile else None) or "").strip()
+        if current_email or current_name or session_profile is None or backend_session is None:
+            return {"email": current_email or None, "nick_name": current_name or None}
+        try:
+            user_info = self.apps.backend.request(
+                "GET",
+                BackendRequestContext(
+                    base_url=backend_session.base_url,
+                    token=backend_session.token,
+                    ws_id=session_profile.selected_ws_id,
+                    qf_version=backend_session.qf_version,
+                    qf_version_source=backend_session.qf_version_source,
+                ),
+                "/user",
+            )
+        except (QingflowApiError, RuntimeError):
+            return {"email": current_email or None, "nick_name": current_name or None}
+        if not isinstance(user_info, dict):
+            return {"email": current_email or None, "nick_name": current_name or None}
+        resolved_email = str(user_info.get("email") or "").strip() or None
+        resolved_name = str(user_info.get("nickName") or user_info.get("displayName") or user_info.get("name") or "").strip() or None
+        return {"email": resolved_email, "nick_name": resolved_name}
+
     def _attach_app_to_package(self, *, profile: str, app_key: str, app_title: str, package_tag_id: int) -> None:
         detail = self.packages.package_get(profile=profile, tag_id=package_tag_id, include_raw=True)
         result = detail.get("result") if isinstance(detail.get("result"), dict) else {}
@@ -2032,9 +2210,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 +2242,7 @@ def _failed_from_api_error(
             },
         )
     return _failed(
-        error_code,
+        effective_error_code,
         public_message,
         recoverable=recoverable,
         normalized_args=normalized_args,
@@ -2095,6 +2292,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 +2314,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 +3073,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 +3275,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 +3464,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/solution/compiler/form_compiler.py

@@ -249,7 +249,7 @@ def build_question(field: dict[str, Any], temp_id: int) -> tuple[dict[str, Any],
             sub_question, next_temp_id = build_question(subfield, next_temp_id)
             sub_questions.append(sub_question)
         question["subQuestions"] = sub_questions
-        question["innerQuestions"] = deepcopy(sub_questions)
+        question["innerQuestions"] = [deepcopy(sub_questions)]
         question["queDefaultValues"] = {"queId": temp_id, "queTitle": field["label"], "queType": que_type, "values": [], "tableValues": []}
     return question, next_temp_id
 

package/src/qingflow_mcp/solution/compiler/workflow_compiler.py

@@ -36,6 +36,11 @@ def compile_workflow(entity: EntitySpec) -> dict[str, Any] | None:
     actions: list[dict[str, Any]] = []
     seen_node_ids: set[str] = set()
     created_extra_branch_lanes: set[str] = set()
+    start_node_ids = {
+        node.node_id
+        for node in workflow.nodes
+        if node.node_type == WorkflowNodeType.start
+    }
     for node in workflow.nodes:
         if node.node_type == WorkflowNodeType.start:
             seen_node_ids.add(node.node_id)
@@ -69,7 +74,7 @@ def compile_workflow(entity: EntitySpec) -> dict[str, Any] | None:
                     "auditNodeName": node.name,
                     "type": WORKFLOW_TYPE_MAP[node.node_type]["type"],
                     "dealType": WORKFLOW_TYPE_MAP[node.node_type]["dealType"],
-                    "prevNodeRef": _prev_node_ref(node, branch_lane_ref),
+                    "prevNodeRef": _prev_node_ref(node, branch_lane_ref, start_node_ids),
                     "auditUserInfos": _build_audit_user_infos(node)
                     if node.node_type in {WorkflowNodeType.audit, WorkflowNodeType.fill, WorkflowNodeType.copy}
                     else None,
@@ -106,11 +111,13 @@ def _build_audit_user_infos(node) -> dict[str, Any]:
     return audit_user_infos
 
 
-def _prev_node_ref(node, branch_lane_ref: str | None) -> str:
+def _prev_node_ref(node, branch_lane_ref: str | None, start_node_ids: set[str]) -> str:
     if branch_lane_ref:
         if node.parent_node_id and node.parent_node_id != node.branch_parent_id:
             return node.parent_node_id
         return branch_lane_ref
+    if node.parent_node_id in start_node_ids:
+        return "__applicant__"
     return node.parent_node_id or "__applicant__"
 
 

package/src/qingflow_mcp/solution/executor.py

@@ -415,13 +415,13 @@ class SolutionExecutor:
         current_nodes = _coerce_workflow_nodes(existing_nodes)
         existing_nodes_by_name = {
             node.get("auditNodeName"): int(node_id)
-            for node_id, node in existing_nodes.items()
+            for node_id, node in current_nodes.items()
             if isinstance(node, dict) and node.get("auditNodeName")
         }
         applicant_node_id = next(
             (
                 int(node_id)
-                for node_id, node in existing_nodes.items()
+                for node_id, node in current_nodes.items()
                 if isinstance(node, dict) and node.get("type") == 0 and node.get("dealType") == 3
             ),
             None,
@@ -429,11 +429,24 @@ class SolutionExecutor:
         if applicant_node_id is not None:
             node_artifacts.setdefault("__applicant__", applicant_node_id)
 
-        current_global_settings = self.workflow_tools.workflow_get_global_settings(profile=profile, app_key=app_key).get("result") or {}
-        global_settings = deepcopy(current_global_settings if isinstance(current_global_settings, dict) else {})
-        global_settings.update(entity.workflow_plan["global_settings"])
-        global_settings["editVersionNo"] = workflow_edit_version_no or global_settings.get("editVersionNo") or 1
-        self.workflow_tools.workflow_update_global_settings(profile=profile, app_key=app_key, payload=global_settings)
+        desired_global_settings = deepcopy(entity.workflow_plan["global_settings"])
+        explicit_global_settings = _has_explicit_workflow_global_settings(desired_global_settings)
+        current_global_settings: dict[str, Any] = {}
+        if explicit_global_settings:
+            current_global_settings = self.workflow_tools.workflow_get_global_settings(profile=profile, app_key=app_key).get("result") or {}
+        else:
+            try:
+                current_global_settings = self.workflow_tools.workflow_get_global_settings(profile=profile, app_key=app_key).get("result") or {}
+            except (QingflowApiError, RuntimeError) as error:
+                api_error = QingflowApiError(**_coerce_nested_error_payload(error))
+                if api_error.http_status != 404:
+                    raise
+                current_global_settings = {}
+        if explicit_global_settings:
+            global_settings = deepcopy(current_global_settings if isinstance(current_global_settings, dict) else {})
+            global_settings.update(desired_global_settings)
+            global_settings["editVersionNo"] = workflow_edit_version_no or global_settings.get("editVersionNo") or 1
+            self.workflow_tools.workflow_update_global_settings(profile=profile, app_key=app_key, payload=global_settings)
         for action in entity.workflow_plan["actions"]:
             if action["action"] == "create_sub_branch" and node_artifacts.get(action["node_id"]) is not None:
                 continue
@@ -2046,6 +2059,20 @@ def _find_created_sub_branch_lane_id(
     return candidates[0] if candidates else None
 
 
+def _has_explicit_workflow_global_settings(global_settings: dict[str, Any] | None) -> bool:
+    if not isinstance(global_settings, dict):
+        return False
+    for key, value in global_settings.items():
+        if key == "editVersionNo":
+            continue
+        if value is None:
+            continue
+        if isinstance(value, (list, dict)) and not value:
+            continue
+        return True
+    return False
+
+
 def _is_navigation_plugin_unavailable(error: QingflowApiError) -> bool:
     try:
         backend_code = int(error.backend_code)

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import json
+import time
 
 from pydantic import ValidationError
 
@@ -59,6 +60,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,
@@ -262,12 +277,47 @@ class AiBuilderTools(ToolBase):
 
     def package_attach_app(self, *, profile: str, tag_id: int, app_key: str, app_title: str = "") -> JSONObject:
         normalized_args = {"tag_id": tag_id, "app_key": app_key, "app_title": app_title}
-        return _safe_tool_call(
+        result = _safe_tool_call(
             lambda: self._facade.package_attach_app(profile=profile, tag_id=tag_id, app_key=app_key, app_title=app_title),
             error_code="PACKAGE_ATTACH_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "package_attach_app", "arguments": {"profile": profile, **normalized_args}},
         )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.package_attach_app(
+                profile=profile,
+                tag_id=tag_id,
+                app_key=app_key,
+                app_title=app_title,
+            ),
+        )
+
+    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}
@@ -537,7 +587,7 @@ class AiBuilderTools(ToolBase):
             "update_fields": [patch.model_dump(mode="json") for patch in parsed_update],
             "remove_fields": [patch.model_dump(mode="json") for patch in parsed_remove],
         }
-        return _safe_tool_call(
+        result = _safe_tool_call(
             lambda: self._facade.app_schema_apply(
                 profile=profile,
                 app_key=app_key,
@@ -553,6 +603,17 @@ class AiBuilderTools(ToolBase):
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_schema_apply", "arguments": {"profile": profile, **normalized_args}},
         )
+        return self._retry_after_self_lock_release(profile=profile, result=result, retry_call=lambda: self._facade.app_schema_apply(
+            profile=profile,
+            app_key=app_key,
+            package_tag_id=package_tag_id,
+            app_name=effective_app_name,
+            create_if_missing=create_if_missing,
+            publish=publish,
+            add_fields=parsed_add,
+            update_fields=parsed_update,
+            remove_fields=parsed_remove,
+        ))
 
     def app_layout_apply(self, *, profile: str, app_key: str, mode: str = "merge", publish: bool = True, sections: list[JSONObject]) -> JSONObject:
         try:
@@ -593,12 +654,23 @@ class AiBuilderTools(ToolBase):
             "publish": publish,
             "sections": [section.model_dump(mode="json") for section in parsed_sections],
         }
-        return _safe_tool_call(
+        result = _safe_tool_call(
             lambda: self._facade.app_layout_apply(profile=profile, app_key=app_key, mode=parsed_mode, publish=publish, sections=parsed_sections),
             error_code="LAYOUT_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_layout_apply", "arguments": {"profile": profile, **normalized_args}},
         )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.app_layout_apply(
+                profile=profile,
+                app_key=app_key,
+                mode=parsed_mode,
+                publish=publish,
+                sections=parsed_sections,
+            ),
+        )
 
     def app_flow_apply(
         self,
@@ -641,7 +713,7 @@ class AiBuilderTools(ToolBase):
             "nodes": [node.model_dump(mode="json") for node in request.nodes],
             "transitions": [transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
         }
-        return _safe_tool_call(
+        result = _safe_tool_call(
             lambda: self._facade.app_flow_apply(
                 profile=profile,
                 app_key=request.app_key,
@@ -654,6 +726,18 @@ class AiBuilderTools(ToolBase):
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_flow_apply", "arguments": {"profile": profile, **normalized_args}},
         )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.app_flow_apply(
+                profile=profile,
+                app_key=request.app_key,
+                mode=request.mode,
+                publish=publish,
+                nodes=[node.model_dump(mode="json") for node in request.nodes],
+                transitions=[transition.model_dump(mode="json", by_alias=True) for transition in request.transitions],
+            ),
+        )
 
     def app_views_apply(
         self,
@@ -685,21 +769,98 @@ class AiBuilderTools(ToolBase):
             "upsert_views": [view.model_dump(mode="json") for view in parsed_views],
             "remove_views": list(remove_views),
         }
-        return _safe_tool_call(
+        result = _safe_tool_call(
             lambda: self._facade.app_views_apply(profile=profile, app_key=app_key, publish=publish, upsert_views=parsed_views, remove_views=remove_views),
             error_code="VIEWS_APPLY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_views_apply", "arguments": {"profile": profile, **normalized_args}},
         )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.app_views_apply(
+                profile=profile,
+                app_key=app_key,
+                publish=publish,
+                upsert_views=parsed_views,
+                remove_views=remove_views,
+            ),
+        )
 
     def app_publish_verify(self, *, profile: str, app_key: str, expected_package_tag_id: int | None = None) -> JSONObject:
         normalized_args = {"app_key": app_key, "expected_package_tag_id": expected_package_tag_id}
-        return _safe_tool_call(
+        result = _safe_tool_call(
             lambda: self._facade.app_publish_verify(profile=profile, app_key=app_key, expected_package_tag_id=expected_package_tag_id),
             error_code="PUBLISH_VERIFY_FAILED",
             normalized_args=normalized_args,
             suggested_next_call={"tool_name": "app_publish_verify", "arguments": {"profile": profile, **normalized_args}},
         )
+        return self._retry_after_self_lock_release(
+            profile=profile,
+            result=result,
+            retry_call=lambda: self._facade.app_publish_verify(
+                profile=profile,
+                app_key=app_key,
+                expected_package_tag_id=expected_package_tag_id,
+            ),
+        )
+
+    def _retry_after_self_lock_release(self, *, profile: str, result: JSONObject, retry_call) -> JSONObject:
+        if not isinstance(result, dict) or result.get("status") != "failed" or result.get("error_code") != "APP_EDIT_LOCKED":
+            return result
+        suggested = result.get("suggested_next_call")
+        if not isinstance(suggested, dict) or suggested.get("tool_name") != "app_release_edit_lock_if_mine":
+            return result
+        arguments = suggested.get("arguments")
+        if not isinstance(arguments, dict):
+            return result
+        app_key = str(arguments.get("app_key") or "")
+        lock_owner_email = str(arguments.get("lock_owner_email") or "")
+        lock_owner_name = str(arguments.get("lock_owner_name") or "")
+        release_attempts: list[JSONObject] = []
+        retried: JSONObject = result
+        for _ in range(3):
+            release_result = 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,
+            )
+            release_attempts.append(release_result)
+            if not isinstance(release_result, dict) or release_result.get("status") != "success":
+                result.setdefault("details", {})
+                if isinstance(result["details"], dict):
+                    result["details"]["edit_lock_release_result"] = release_result
+                    result["details"]["edit_lock_release_attempts"] = release_attempts
+                return result
+            retried = retry_call()
+            if not (
+                isinstance(retried, dict)
+                and retried.get("status") == "failed"
+                and retried.get("error_code") == "APP_EDIT_LOCKED"
+            ):
+                break
+            time.sleep(0.2)
+        if (
+            isinstance(retried, dict)
+            and retried.get("status") == "failed"
+            and retried.get("error_code") == "APP_EDIT_LOCKED"
+        ):
+            retried = {
+                **retried,
+                "error_code": "PERSISTENT_SELF_LOCK",
+                "message": "app remains locked by the current user's active editor session after repeated forced release attempts",
+                "recoverable": True,
+                "suggested_next_call": None,
+            }
+        if isinstance(retried, dict):
+            retried.setdefault("details", {})
+            if isinstance(retried["details"], dict):
+                retried["details"]["edit_lock_release_result"] = release_attempts[-1] if release_attempts else None
+                retried["details"]["edit_lock_release_attempts"] = release_attempts
+            retried["edit_lock_released"] = bool(release_attempts)
+            retried["retried_after_edit_lock_release"] = True
+        return retried
 
 
 def _validation_failure(detail: str, *, suggested_next_call: JSONObject | None = None) -> JSONObject:
@@ -779,6 +940,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"))