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

package/src/qingflow_mcp/tools/code_block_tools.py

@@ -5,7 +5,7 @@ from typing import cast
 from mcp.server.fastmcp import FastMCP
 
 from ..config import DEFAULT_PROFILE, DEFAULT_RECORD_LIST_TYPE
-from ..errors import QingflowApiError, raise_tool_error
+from ..errors import QingflowApiError, backend_code_int, backend_code_value_int, is_auth_like_error, message_looks_like_invalid_token, raise_tool_error
 from ..json_types import JSONObject, JSONValue
 from .base import tool_cn_name
 from .record_tools import (
@@ -19,9 +19,11 @@ from .record_tools import (
     FieldIndex,
     FormField,
     RecordTools,
+    _build_answer_backed_field_index,
     _coerce_count,
     _collect_question_relations,
     _field_ref_payload,
+    _merge_field_indexes,
     _normalize_optional_text,
     _relation_ids_from_answer,
     _stringify_json,
@@ -31,6 +33,7 @@ from .record_tools import (
 CODE_BLOCK_QUE_TYPE = 26
 CODE_BLOCK_RELATION_TYPE = 3
 SUPPORTED_CODE_BLOCK_ROLES = {1, 2, 3, 5}
+_CODE_BLOCK_SCHEMA_PERMISSION_CODES = {40002, 40027, 404}
 
 
 class CodeBlockTools(RecordTools):
@@ -65,6 +68,36 @@ class CodeBlockTools(RecordTools):
         self._form_cache[cache_key] = normalized
         return normalized
 
+    def _get_code_block_relation_schema_optional(
+        self,
+        profile: str,
+        context,  # type: ignore[no-untyped-def]
+        app_key: str,
+        *,
+        force_refresh: bool,
+        warnings: list[JSONObject],
+    ) -> JSONObject:
+        try:
+            return self._get_code_block_relation_schema(
+                profile,
+                context,
+                app_key,
+                force_refresh=force_refresh,
+            )
+        except QingflowApiError as exc:
+            if not _is_optional_code_block_schema_error(exc):
+                raise
+            warnings.append(
+                {
+                    "code": "CODE_BLOCK_SCHEMA_UNAVAILABLE",
+                    "message": "applicant form schema was not readable in this permission context; code-block execution will use record/task answers and skip schema-bound relation writeback.",
+                    "backend_code": exc.backend_code,
+                    "http_status": exc.http_status,
+                    "request_id": exc.request_id,
+                }
+            )
+            return {}
+
     def register(self, mcp: FastMCP) -> None:
         """注册当前工具到 MCP 服务。"""
         super().register(mcp)
@@ -84,7 +117,8 @@ class CodeBlockTools(RecordTools):
             description=(
                 "Run a form code-block field against the current record data, parse alias results, and optionally "
                 "reuse Qingflow's existing relation-calculation chain to compute bound outputs and write them back. "
-                "Use record_code_block_schema_get first and choose an exact code-block field selector. "
+                "Use record_code_block_schema_get when field selection or binding diagnostics are unclear; "
+                "if the exact code-block field id is known from record/task detail, run directly. "
                 "For safe debugging, pass apply_writeback=false to inspect parsed results without writing back."
             )
         )
@@ -93,6 +127,7 @@ class CodeBlockTools(RecordTools):
             app_key: str = "",
             record_id: str = "",
             code_block_field: str = "",
+            view_id: str | None = None,
             role: int = 1,
             workflow_node_id: int | None = None,
             answers: list[JSONObject] | None = None,
@@ -108,6 +143,7 @@ class CodeBlockTools(RecordTools):
                 app_key=app_key,
                 record_id=record_id,
                 code_block_field=code_block_field,
+                view_id=view_id,
                 role=role,
                 workflow_node_id=workflow_node_id,
                 answers=answers or [],
@@ -133,8 +169,45 @@ class CodeBlockTools(RecordTools):
         normalized_output_profile = self._normalize_public_output_profile(output_profile)
 
         def runner(session_profile, context):
-            relation_schema = self._get_code_block_relation_schema(profile, context, app_key, force_refresh=False)
-            index = self._get_applicant_top_level_field_index(profile, context, app_key, force_refresh=False)
+            try:
+                relation_schema = self._get_code_block_relation_schema(profile, context, app_key, force_refresh=False)
+                index = self._get_applicant_top_level_field_index(profile, context, app_key, force_refresh=False)
+            except QingflowApiError as exc:
+                if not _is_optional_code_block_schema_error(exc):
+                    raise
+                return {
+                    "profile": profile,
+                    "ws_id": session_profile.selected_ws_id,
+                    "ok": False,
+                    "status": "failed",
+                    "error_code": "CODE_BLOCK_SCHEMA_UNAVAILABLE",
+                    "message": (
+                        "applicant form schema was not readable in this permission context; "
+                        "record schema code-block is only a diagnostic helper. "
+                        "If the code-block field is known from record/task detail, run record code-block-run directly."
+                    ),
+                    "backend_code": exc.backend_code,
+                    "http_status": exc.http_status,
+                    "request_id": exc.request_id,
+                    "request_route": self._request_route_payload(context),
+                    "warnings": [
+                        {
+                            "code": "CODE_BLOCK_SCHEMA_UNAVAILABLE",
+                            "message": "schema diagnostic unavailable; code-block run can still use record/task answers when code_block_field is known.",
+                            "backend_code": exc.backend_code,
+                            "http_status": exc.http_status,
+                            "request_id": exc.request_id,
+                        }
+                    ],
+                    "app_key": app_key,
+                    "schema_scope": "code_block_ready",
+                    "code_block_fields": [],
+                    "input_fields": [],
+                    "suggested_next_call": {
+                        "tool_name": "record_code_block_run",
+                        "required": ["app_key", "record_id", "code_block_field"],
+                    },
+                }
             input_fields = [
                 self._ready_schema_field_payload(
                     profile,
@@ -199,6 +272,7 @@ class CodeBlockTools(RecordTools):
         app_key: str,
         record_id: int | str,
         code_block_field: str,
+        view_id: str | None = None,
         role: int = 1,
         workflow_node_id: int | None = None,
         answers: list[JSONObject] | None = None,
@@ -220,14 +294,42 @@ class CodeBlockTools(RecordTools):
             raise_tool_error(QingflowApiError.config_error("code_block_field is required"))
 
         def runner(session_profile, context):
-            relation_schema = self._get_code_block_relation_schema(
+            warnings: list[JSONObject] = []
+            current_answers = self._load_record_answers_for_code_block(
+                context,
+                profile=profile,
+                app_key=app_key,
+                apply_id=normalized_record_id,
+                view_id=view_id,
+                role=role,
+                audit_node_id=workflow_node_id,
+            )
+            answer_index = _build_answer_backed_field_index(current_answers)
+            schema_index: FieldIndex | None = None
+            relation_schema = self._get_code_block_relation_schema_optional(
                 profile,
                 context,
                 app_key,
                 force_refresh=force_refresh_form,
+                warnings=warnings,
             )
-            index = self._get_field_index(profile, context, app_key, force_refresh=force_refresh_form)
-            code_block = self._resolve_field_selector(code_block_field, index, location="code_block_field")
+            try:
+                schema_index = self._get_field_index(profile, context, app_key, force_refresh=force_refresh_form)
+            except QingflowApiError as exc:
+                if not _is_optional_code_block_schema_error(exc):
+                    raise
+                if not any(item.get("code") == "CODE_BLOCK_SCHEMA_UNAVAILABLE" for item in warnings):
+                    warnings.append(
+                        {
+                            "code": "CODE_BLOCK_SCHEMA_UNAVAILABLE",
+                            "message": "applicant form schema was not readable in this permission context; code-block execution will use record/task answers and skip schema-bound relation writeback.",
+                            "backend_code": exc.backend_code,
+                            "http_status": exc.http_status,
+                            "request_id": exc.request_id,
+                        }
+                    )
+            index = _merge_field_indexes(schema_index, answer_index) if schema_index is not None else answer_index
+            code_block = self._resolve_code_block_field_for_run(code_block_field, index)
             if code_block.que_type != CODE_BLOCK_QUE_TYPE:
                 raise_tool_error(
                     QingflowApiError(
@@ -241,14 +343,6 @@ class CodeBlockTools(RecordTools):
                         },
                     )
                 )
-
-            current_answers = self._load_record_answers_for_code_block(
-                context,
-                app_key=app_key,
-                apply_id=normalized_record_id,
-                role=role,
-                audit_node_id=workflow_node_id,
-            )
             override_answers = (
                 self._resolve_answers(
                     profile,
@@ -257,12 +351,13 @@ class CodeBlockTools(RecordTools):
                     answers=answers or [],
                     fields=fields or {},
                     force_refresh_form=force_refresh_form,
+                    field_index_override=index,
                 )
                 if answers or fields
                 else []
             )
             merged_answers = self._merge_record_answers(current_answers, override_answers) if override_answers else current_answers
-            key_que_values = self._answers_to_open_match_values(merged_answers, index)
+            key_que_values = self._answers_to_open_match_values(merged_answers, index, exclude_que_ids={code_block.que_id})
             run_body: JSONObject = {
                 "role": role,
                 "manual": bool(manual),
@@ -289,6 +384,7 @@ class CodeBlockTools(RecordTools):
             relation_items: list[JSONObject] = []
             calculated_answers: list[JSONObject] = []
             relation_result: JSONObject | None = None
+            relation_transport_error: JSONObject | None = None
             if relation_target_fields:
                 relation_body: JSONObject = {
                     "role": role,
@@ -306,26 +402,38 @@ class CodeBlockTools(RecordTools):
                     relation_result = self.backend.request("POST", context, relation_route, json_body=relation_body)
                     relation_items = _relation_result_items(relation_result)
                 except QingflowApiError as exc:
-                    if exc.http_status != 404:
-                        raise
-                    relation_route = "/que/actuator"
-                    relation_result = self.backend.request("POST", context, relation_route, json_body=relation_body)
-                    relation_items = _relation_result_items(relation_result)
-                if not relation_items:
+                    if exc.http_status == 404:
+                        relation_route = "/que/actuator"
+                        try:
+                            relation_result = self.backend.request("POST", context, relation_route, json_body=relation_body)
+                            relation_items = _relation_result_items(relation_result)
+                        except QingflowApiError as fallback_exc:
+                            relation_transport_error = _code_block_transport_error(fallback_exc)
+                    else:
+                        relation_transport_error = _code_block_transport_error(exc)
+                if relation_transport_error is None and not relation_items:
                     # Keep compatibility with legacy runtime deployments and lightweight test doubles
                     # that still stub the older relation-calculation route only.
                     relation_route = "/que/actuator"
-                    relation_result = self.backend.request("POST", context, relation_route, json_body=relation_body)
-                    relation_items = _relation_result_items(relation_result)
+                    try:
+                        relation_result = self.backend.request("POST", context, relation_route, json_body=relation_body)
+                        relation_items = _relation_result_items(relation_result)
+                        relation_transport_error = None
+                    except QingflowApiError as exc:
+                        relation_transport_error = relation_transport_error or _code_block_transport_error(exc)
                 relation_errors = _relation_result_errors(relation_items)
                 calculated_answers = _relation_result_answers(relation_items)
             write_result: JSONObject | None = None
+            write_error: JSONObject | None = None
             verification: JSONObject | None = None
             writeback_attempted = False
             writeback_applied = False
             status = "completed"
             ok = True
-            if relation_errors:
+            if relation_transport_error is not None:
+                status = "relation_failed"
+                ok = False
+            elif relation_errors:
                 status = "relation_failed"
                 ok = False
             elif not apply_writeback:
@@ -335,21 +443,28 @@ class CodeBlockTools(RecordTools):
                 if workflow_node_id is not None:
                     write_body["auditNodeId"] = workflow_node_id
                 writeback_attempted = True
-                write_result = cast(
-                    JSONObject,
-                    self.backend.request(
-                        "POST",
-                        context,
-                        f"/app/{app_key}/apply/{normalized_record_id}",
-                        json_body=write_body,
-                    ),
-                )
-                writeback_applied = True
-                if verify_writeback:
+                try:
+                    write_result = cast(
+                        JSONObject,
+                        self.backend.request(
+                            "POST",
+                            context,
+                            f"/app/{app_key}/apply/{normalized_record_id}",
+                            json_body=write_body,
+                        ),
+                    )
+                    writeback_applied = True
+                except QingflowApiError as exc:
+                    write_error = _code_block_transport_error(exc)
+                    status = "writeback_failed"
+                    ok = False
+                if writeback_applied and verify_writeback:
                     verification = self._verify_code_block_writeback_result(
                         context,
+                        profile=profile,
                         app_key=app_key,
                         apply_id=normalized_record_id,
+                        view_id=view_id,
                         expected_answers=calculated_answers,
                         index=index,
                         role=role,
@@ -357,7 +472,16 @@ class CodeBlockTools(RecordTools):
                     )
                     if not bool(verification.get("verified")):
                         status = "verification_failed"
-                        ok = False
+                        ok = True
+                        warnings.append(
+                            {
+                                "code": "CODE_BLOCK_WRITEBACK_VERIFICATION_FAILED",
+                                "message": (
+                                    "code-block execution and writeback completed, but field-level readback "
+                                    "could not verify the written values; do not treat this as writeback denial."
+                                ),
+                            }
+                        )
             else:
                 status = "no_writeback"
             response: JSONObject = {
@@ -369,9 +493,14 @@ class CodeBlockTools(RecordTools):
                 "apply_id": normalized_record_id,
                 "status": status,
                 "ok": ok,
+                "write_executed": writeback_applied,
+                "write_succeeded": writeback_applied,
+                "safe_to_retry": not writeback_applied,
+                "warnings": warnings,
                 "code_block_field": _field_ref_payload(code_block),
                 "execution": {
                     "executed": True,
+                    "view_id": _normalize_optional_text(view_id),
                     "role": role,
                     "workflow_node_id": workflow_node_id,
                     "manual": bool(manual),
@@ -389,6 +518,7 @@ class CodeBlockTools(RecordTools):
                     "calculated_answer_count": len(calculated_answers),
                     "calculated_answers_preview": calculated_answers,
                     "errors": relation_errors,
+                    "transport_error": relation_transport_error,
                 },
                 "writeback": {
                     "enabled": bool(apply_writeback),
@@ -398,10 +528,15 @@ class CodeBlockTools(RecordTools):
                     "verify_writeback": verify_writeback,
                     "write_verified": bool(verification.get("verified")) if verification is not None else None,
                     "result": write_result,
+                    "error": write_error,
                     "verification": verification,
                 },
                 "resource": {"apply_id": normalized_record_id},
             }
+            if not ok:
+                failure_error = relation_transport_error if relation_transport_error is not None else write_error
+                failure_context = "relation" if relation_transport_error is not None else "writeback"
+                response.update(_code_block_failure_fields(failure_error, context=failure_context))
             if normalized_output_profile == "verbose":
                 response["debug"] = {
                     "run_body": run_body,
@@ -415,16 +550,66 @@ class CodeBlockTools(RecordTools):
 
         return self._run_record_tool(profile, runner)
 
+    def _resolve_code_block_field_for_run(self, selector: str | int, index: FieldIndex) -> FormField:
+        field_id = _coerce_count(selector)
+        if field_id is not None and str(field_id) not in index.by_id:
+            return FormField(
+                que_id=field_id,
+                que_title=str(field_id),
+                que_type=CODE_BLOCK_QUE_TYPE,
+                required=False,
+                readonly=False,
+                system=False,
+                options=[],
+                aliases=[],
+                target_app_key=None,
+                target_app_name_hint=None,
+                member_select_scope_type=None,
+                member_select_scope=None,
+                dept_select_scope_type=None,
+                dept_select_scope=None,
+                raw={"queId": field_id, "queTitle": str(field_id), "queType": CODE_BLOCK_QUE_TYPE},
+            )
+        return self._resolve_field_selector(selector, index, location="code_block_field")
+
     def _load_record_answers_for_code_block(
         self,
         context,  # type: ignore[no-untyped-def]
         *,
+        profile: str,
         app_key: str,
         apply_id: int,
+        view_id: str | None,
         role: int,
         audit_node_id: int | None,
     ) -> list[JSONObject]:
         """执行内部辅助逻辑。"""
+        normalized_view_id = _normalize_optional_text(view_id)
+        if normalized_view_id:
+            try:
+                resolved_view, _warnings = self._resolve_accessible_view_route(
+                    profile,
+                    context,
+                    app_key,
+                    view_id=normalized_view_id,
+                    list_type=None,
+                    view_key=None,
+                    view_name=None,
+                    allow_default=False,
+                )
+                record, _used_list_type, _used_role = self._record_get_apply_detail(
+                    context,
+                    app_key=app_key,
+                    record_id=apply_id,
+                    resolved_view=resolved_view,
+                    audit_node_id=audit_node_id,
+                )
+                answers = record.get("answers") if isinstance(record, dict) else None
+                return [item for item in answers if isinstance(item, dict)] if isinstance(answers, list) else []
+            except QingflowApiError as exc:
+                if not _is_optional_code_block_record_read_error(exc):
+                    raise
+
         last_error: QingflowApiError | None = None
         for list_type in self._INTERNAL_GET_LIST_TYPE_FALLBACKS:
             params: JSONObject = {"role": role, "listType": list_type}
@@ -436,19 +621,28 @@ class CodeBlockTools(RecordTools):
                 return [item for item in answers if isinstance(item, dict)] if isinstance(answers, list) else []
             except QingflowApiError as exc:
                 last_error = exc
-                if exc.backend_code == 40002:
+                if _is_code_block_permission_error(exc):
                     continue
                 raise
         if last_error is not None:
             raise last_error
         raise_tool_error(QingflowApiError.config_error("record answers could not be loaded for code-block execution"))
 
-    def _answers_to_open_match_values(self, answers: list[JSONObject], index: FieldIndex) -> list[JSONObject]:
+    def _answers_to_open_match_values(
+        self,
+        answers: list[JSONObject],
+        index: FieldIndex,
+        *,
+        exclude_que_ids: set[int] | None = None,
+    ) -> list[JSONObject]:
         """执行内部辅助逻辑。"""
         values: list[JSONObject] = []
         for answer in answers:
             if not isinstance(answer, dict):
                 continue
+            que_id = _coerce_count(answer.get("queId", answer.get("que_id")))
+            if que_id is not None and exclude_que_ids is not None and que_id in exclude_que_ids:
+                continue
             open_match = self._answer_to_open_match_value(answer, index)
             if open_match is None:
                 continue
@@ -507,8 +701,10 @@ class CodeBlockTools(RecordTools):
         self,
         context,  # type: ignore[no-untyped-def]
         *,
+        profile: str,
         app_key: str,
         apply_id: int,
+        view_id: str | None,
         expected_answers: list[JSONObject],
         index: FieldIndex,
         role: int,
@@ -526,8 +722,10 @@ class CodeBlockTools(RecordTools):
             )
         actual_answers = self._load_record_answers_for_code_block(
             context,
+            profile=profile,
             app_key=app_key,
             apply_id=apply_id,
+            view_id=view_id,
             role=role,
             audit_node_id=audit_node_id,
         )
@@ -619,6 +817,42 @@ def _normalize_code_block_value_item(value: JSONValue, field: FormField) -> str
     return text if text is not None else None
 
 
+def _code_block_transport_error(error: QingflowApiError) -> JSONObject:
+    payload: JSONObject = {
+        "category": error.category,
+        "message": error.message,
+    }
+    if error.backend_code is not None:
+        payload["backend_code"] = error.backend_code
+    if error.http_status is not None:
+        payload["http_status"] = error.http_status
+    if error.request_id:
+        payload["request_id"] = error.request_id
+    if error.details:
+        payload["details"] = error.details
+    return payload
+
+
+def _code_block_failure_fields(error: JSONObject | None, *, context: str) -> JSONObject:
+    default_code = "CODE_BLOCK_RELATION_FAILED" if context == "relation" else "CODE_BLOCK_WRITEBACK_FAILED"
+    permission_code = "CODE_BLOCK_RELATION_PERMISSION_DENIED" if context == "relation" else "CODE_BLOCK_WRITEBACK_PERMISSION_DENIED"
+    payload: JSONObject = {
+        "error_code": default_code,
+    }
+    if not isinstance(error, dict):
+        return payload
+    category = str(error.get("category") or "").strip().lower()
+    http_status = backend_code_value_int(error.get("http_status"))
+    if category == "auth" or http_status == 401 or message_looks_like_invalid_token(error.get("message")):
+        payload["error_code"] = "AUTH_REQUIRED"
+    elif backend_code_value_int(error.get("backend_code")) in {40002, 40027}:
+        payload["error_code"] = permission_code
+    for key in ("category", "backend_code", "http_status", "request_id"):
+        if key in error:
+            payload[key] = error.get(key)
+    return payload
+
+
 def _selector_numeric_or_text(value: JSONValue, keys: tuple[str, ...], *, allow_text: bool) -> str | None:
     numeric = _coerce_count(value)
     if numeric is not None:
@@ -775,3 +1009,26 @@ def _relation_result_errors(items: list[JSONObject]) -> list[JSONObject]:
             }
         )
     return errors
+
+
+def _is_optional_code_block_record_read_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = _code_block_backend_code(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404
+
+
+def _is_optional_code_block_schema_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    return _code_block_backend_code(error) in _CODE_BLOCK_SCHEMA_PERMISSION_CODES or error.http_status == 404
+
+
+def _is_code_block_permission_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    return _code_block_backend_code(error) in {40002, 40027}
+
+
+def _code_block_backend_code(error: QingflowApiError) -> int | None:
+    return backend_code_int(error)

package/src/qingflow_mcp/tools/custom_button_tools.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 from copy import deepcopy
 
 from ..config import DEFAULT_PROFILE
-from ..errors import QingflowApiError, raise_tool_error
+from ..errors import QingflowApiError, backend_code_int, is_auth_like_error, raise_tool_error
 from ..json_types import JSONObject
 from .base import ToolBase, tool_cn_name
 
@@ -31,12 +31,26 @@ class CustomButtonTools(ToolBase):
         self._require_app_key(app_key)
 
         def runner(session_profile, context):
-            result = self.backend.request(
-                "GET",
-                context,
-                f"/app/{app_key}/customButton",
-                params={"beingDraft": being_draft},
-            )
+            effective_being_draft = being_draft
+            fallback_error: QingflowApiError | None = None
+            try:
+                result = self.backend.request(
+                    "GET",
+                    context,
+                    f"/app/{app_key}/customButton",
+                    params={"beingDraft": being_draft},
+                )
+            except QingflowApiError as exc:
+                if not being_draft or not _is_optional_draft_button_read_error(exc):
+                    raise
+                fallback_error = exc
+                effective_being_draft = False
+                result = self.backend.request(
+                    "GET",
+                    context,
+                    f"/app/{app_key}/customButton",
+                    params={"beingDraft": False},
+                )
             items = []
             raw_items = result.get("result") if isinstance(result, dict) and isinstance(result.get("result"), list) else []
             for item in raw_items:
@@ -47,11 +61,23 @@ class CustomButtonTools(ToolBase):
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "app_key": app_key,
-                "being_draft": being_draft,
+                "being_draft": effective_being_draft,
+                "requested_being_draft": being_draft,
                 "items": result if include_raw else items,
                 "count": len(items),
                 "compact": not include_raw,
             }
+            if fallback_error is not None:
+                response["warnings"] = [
+                    {
+                        "code": "CUSTOM_BUTTON_DRAFT_LIST_UNAVAILABLE",
+                        "message": "draft custom button list is unavailable; returned published custom buttons instead",
+                        "backend_code": fallback_error.backend_code,
+                        "http_status": fallback_error.http_status,
+                        "request_id": fallback_error.request_id,
+                    }
+                ]
+                response["verification"] = {"draft_readable": False, "published_fallback_used": True}
             if include_raw:
                 response["summary"] = items
             return response
@@ -74,16 +100,37 @@ class CustomButtonTools(ToolBase):
 
         def runner(session_profile, context):
             params = {"beingDraft": being_draft}
-            result = self.backend.request("GET", context, f"/app/{app_key}/customButton/{button_id}", params=params)
+            effective_being_draft = being_draft
+            fallback_error: QingflowApiError | None = None
+            try:
+                result = self.backend.request("GET", context, f"/app/{app_key}/customButton/{button_id}", params=params)
+            except QingflowApiError as exc:
+                if not being_draft or not _is_optional_draft_button_read_error(exc):
+                    raise
+                fallback_error = exc
+                effective_being_draft = False
+                result = self.backend.request("GET", context, f"/app/{app_key}/customButton/{button_id}", params={"beingDraft": False})
             response = {
                 "profile": profile,
                 "ws_id": session_profile.selected_ws_id,
                 "app_key": app_key,
                 "button_id": button_id,
-                "being_draft": being_draft,
+                "being_draft": effective_being_draft,
+                "requested_being_draft": being_draft,
                 "result": result if include_raw else self._compact_button_detail(result if isinstance(result, dict) else {}),
                 "compact": not include_raw,
             }
+            if fallback_error is not None:
+                response["warnings"] = [
+                    {
+                        "code": "CUSTOM_BUTTON_DRAFT_DETAIL_UNAVAILABLE",
+                        "message": "draft custom button detail is unavailable; returned published custom button detail instead",
+                        "backend_code": fallback_error.backend_code,
+                        "http_status": fallback_error.http_status,
+                        "request_id": fallback_error.request_id,
+                    }
+                ]
+                response["verification"] = {"draft_readable": False, "published_fallback_used": True}
             if include_raw:
                 response["summary"] = self._compact_button_detail(result if isinstance(result, dict) else {})
             return response
@@ -198,3 +245,10 @@ class CustomButtonTools(ToolBase):
             else None,
             "trigger_wings_config": deepcopy(item.get("triggerWingsConfig")) if isinstance(item.get("triggerWingsConfig"), dict) else None,
         }
+
+
+def _is_optional_draft_button_read_error(error: QingflowApiError) -> bool:
+    if is_auth_like_error(error):
+        return False
+    backend_code = backend_code_int(error)
+    return backend_code in {40002, 40027, 404} or error.http_status == 404