@qingflow-tech/qingflow-app-user-mcp 1.0.11 → 1.0.13

package/src/qingflow_mcp/cli/main.py

@@ -5,7 +5,7 @@ import json
 import sys
 from typing import Any, Callable, TextIO
 
-from ..errors import QingflowApiError
+from ..errors import QingflowApiError, backend_code_value_int, message_looks_like_invalid_token
 from ..public_surface import cli_public_tool_spec_from_namespace
 from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
 from ..tools.ai_builder_tools import _attach_builder_apply_envelope
@@ -323,6 +323,8 @@ def _emit_error(payload: dict[str, Any], *, json_mode: bool, stdout: TextIO, std
         f"Category: {payload.get('category') or 'error'}",
         f"Message: {payload.get('message') or 'Unknown error'}",
     ]
+    if payload.get("error_code"):
+        lines.append(f"Error Code: {payload.get('error_code')}")
     if payload.get("backend_code") is not None:
         lines.append(f"Backend Code: {payload.get('backend_code')}")
     if payload.get("request_id"):
@@ -337,23 +339,65 @@ def _emit_error(payload: dict[str, Any], *, json_mode: bool, stdout: TextIO, std
 
 
 def _error_exit_code(payload: dict[str, Any]) -> int:
-    category = str(payload.get("category") or "").lower()
-    if category in {"auth", "workspace"}:
+    if _is_auth_or_workspace_payload(payload):
         return 3
     return 4
 
 
+def _is_auth_or_workspace_payload(payload: dict[str, Any]) -> bool:
+    category = str(payload.get("category") or "").lower()
+    error_code = str(payload.get("error_code") or "").upper()
+    http_status = backend_code_value_int(payload.get("http_status"))
+    if category in {"auth", "workspace"} or error_code in {"AUTH_REQUIRED", "WORKSPACE_NOT_SELECTED"}:
+        return True
+    if http_status == 401 or message_looks_like_invalid_token(payload.get("message")):
+        return True
+    return False
+
+
 def _result_exit_code(result: dict[str, Any]) -> int:
     if not isinstance(result, dict):
         return 0
+    if _is_executed_nonfatal_result(result):
+        return 0
+    if _is_auth_or_workspace_payload(result):
+        return 3
     if result.get("ok") is False:
         return 4
     status = str(result.get("status") or "").lower()
+    if status == "partial_success" and result.get("ok") is not True and not _has_readback_unavailable_verification(result):
+        return 4
     if status in {"failed", "blocked"}:
         return 4
     return 0
 
 
+def _is_executed_nonfatal_result(result: dict[str, Any]) -> bool:
+    status = str(result.get("status") or "").lower()
+    executed = bool(
+        result.get("write_executed")
+        or result.get("delete_executed")
+        or result.get("action_executed")
+        or result.get("export_executed")
+    )
+    return executed and status in {"partial_success", "verification_failed", "running", "queued", "unknown"}
+
+
+def _has_readback_unavailable_verification(result: dict[str, Any]) -> bool:
+    verification = result.get("verification")
+    if not isinstance(verification, dict):
+        return False
+    return any(
+        bool(verification.get(key))
+        for key in (
+            "readback_unavailable",
+            "readback_pending",
+            "metadata_unverified",
+            "views_read_unavailable",
+        )
+    )
+
+
 def _emit_cli_effective_context_notice(args: argparse.Namespace, context: CliContext, *, stream: TextIO) -> None:
     spec = cli_public_tool_spec_from_namespace(args)
     if spec is None or not spec.cli_show_effective_context:

package/src/qingflow_mcp/errors.py

@@ -9,11 +9,24 @@ from .json_types import JSONObject, JSONScalar
 INVALID_TOKEN_MARKERS = (
     "invalid token",
     "token invalid",
+    "token expired",
+    "expired token",
     "token失效",
     "无效token",
     "登录失效",
+    "登录过期",
+    "会话过期",
+    "session expired",
+    "session invalid",
     "login token invalid",
     "access token invalid",
+    "not logged in",
+    "not login",
+    "please login",
+    "please log in",
+    "未登录",
+    "请登录",
+    "重新登录",
 )
 
 
@@ -36,8 +49,7 @@ class QingflowApiError(Exception):
         return self.as_json()
 
     def looks_like_invalid_token(self) -> bool:
-        text = self.message.lower()
-        return any(marker in text for marker in INVALID_TOKEN_MARKERS)
+        return message_looks_like_invalid_token(self.message)
 
     @classmethod
     def auth_required(cls, profile: str) -> "QingflowApiError":
@@ -64,3 +76,32 @@ class QingflowApiError(Exception):
 
 def raise_tool_error(error: QingflowApiError) -> None:
     raise RuntimeError(error.as_json())
+
+
+def backend_code_value_int(code: JSONScalar) -> int | None:
+    if isinstance(code, bool) or code is None:
+        return None
+    if isinstance(code, int):
+        return code
+    if isinstance(code, str):
+        text = code.strip()
+        if text:
+            try:
+                return int(text)
+            except ValueError:
+                return None
+    return None
+
+
+def backend_code_int(error: QingflowApiError) -> int | None:
+    return backend_code_value_int(error.backend_code)
+
+
+def message_looks_like_invalid_token(message: object) -> bool:
+    text = str(message or "").lower()
+    return any(marker in text for marker in INVALID_TOKEN_MARKERS)
+
+
+def is_auth_like_error(error: QingflowApiError) -> bool:
+    category = str(error.category or "").strip().lower()
+    return category == "auth" or error.http_status == 401 or error.looks_like_invalid_token()

package/src/qingflow_mcp/public_surface.py

@@ -51,35 +51,40 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
         "record_schema_get",
         cli_route=("record", "schema", "applicant"),
         mcp_public=False,
+        cli_public=False,
     ),
     PublicToolSpec(
         USER_DOMAIN,
         "record_browse_schema_get",
         ("record_browse_schema_get_public",),
         ("record", "schema", "browse"),
+        cli_show_effective_context=True,
     ),
     PublicToolSpec(
         USER_DOMAIN,
         "record_insert_schema_get",
         ("record_insert_schema_get_public",),
         ("record", "schema", "insert"),
+        cli_show_effective_context=True,
     ),
     PublicToolSpec(
         USER_DOMAIN,
         "record_update_schema_get",
         ("record_update_schema_get_public",),
         ("record", "schema", "update"),
+        cli_show_effective_context=True,
     ),
-    PublicToolSpec(USER_DOMAIN, "record_import_schema_get", ("record_import_schema_get",), ("record", "schema", "import")),
+    PublicToolSpec(USER_DOMAIN, "record_import_schema_get", ("record_import_schema_get",), ("record", "schema", "import"), cli_show_effective_context=True),
     PublicToolSpec(
         USER_DOMAIN,
         "record_code_block_schema_get",
         ("record_code_block_schema_get_public",),
         ("record", "schema", "code-block"),
+        cli_show_effective_context=True,
     ),
-    PublicToolSpec(USER_DOMAIN, "record_member_candidates", ("record_member_candidates",), ("record", "member-candidates")),
-    PublicToolSpec(USER_DOMAIN, "record_department_candidates", ("record_department_candidates",), ("record", "department-candidates")),
-    PublicToolSpec(USER_DOMAIN, "record_analyze", ("record_analyze",), ("record", "analyze"), mcp_public=False),
+    PublicToolSpec(USER_DOMAIN, "record_member_candidates", ("record_member_candidates",), ("record", "member-candidates"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_department_candidates", ("record_department_candidates",), ("record", "department-candidates"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_analyze", ("record_analyze",), ("record", "analyze"), mcp_public=False, cli_public=False),
     PublicToolSpec(USER_DOMAIN, "record_list", ("record_list",), ("record", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_access", ("record_access",), ("record", "access"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_get", ("record_get_public",), ("record", "get"), cli_show_effective_context=True),
@@ -87,11 +92,11 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "record_insert", ("record_insert_public",), ("record", "insert"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(USER_DOMAIN, "record_update", ("record_update_public",), ("record", "update"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(USER_DOMAIN, "record_delete", ("record_delete_public",), ("record", "delete"), cli_show_effective_context=True, cli_context_write=True),
-    PublicToolSpec(USER_DOMAIN, "record_import_template_get", ("record_import_template_get",), ("import", "template")),
-    PublicToolSpec(USER_DOMAIN, "record_import_verify", ("record_import_verify",), ("import", "verify")),
+    PublicToolSpec(USER_DOMAIN, "record_import_template_get", ("record_import_template_get",), ("import", "template"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_import_verify", ("record_import_verify",), ("import", "verify"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_import_repair_local", ("record_import_repair_local",), ("import", "repair")),
-    PublicToolSpec(USER_DOMAIN, "record_import_start", ("record_import_start",), ("import", "start")),
-    PublicToolSpec(USER_DOMAIN, "record_import_status_get", ("record_import_status_get",), ("import", "status")),
+    PublicToolSpec(USER_DOMAIN, "record_import_start", ("record_import_start",), ("import", "start"), cli_show_effective_context=True, cli_context_write=True),
+    PublicToolSpec(USER_DOMAIN, "record_import_status_get", ("record_import_status_get",), ("import", "status"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_export_start", ("record_export_start",), ("export", "start"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_export_status_get", ("record_export_status_get",), ("export", "status"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_export_get", ("record_export_get",), ("export", "get"), cli_show_effective_context=True),
@@ -109,12 +114,12 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     ),
     PublicToolSpec(USER_DOMAIN, "task_workflow_log_get", ("task_workflow_log_get",), ("task", "log"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "directory_search", ("directory_search",), cli_public=False),
-    PublicToolSpec(USER_DOMAIN, "directory_list_internal_users", ("directory_list_internal_users",), cli_public=False),
-    PublicToolSpec(USER_DOMAIN, "directory_list_all_internal_users", ("directory_list_all_internal_users",), cli_public=False),
-    PublicToolSpec(USER_DOMAIN, "directory_list_internal_departments", ("directory_list_internal_departments",), cli_public=False),
-    PublicToolSpec(USER_DOMAIN, "directory_list_all_departments", ("directory_list_all_departments",), cli_public=False),
-    PublicToolSpec(USER_DOMAIN, "directory_list_sub_departments", ("directory_list_sub_departments",), cli_public=False),
-    PublicToolSpec(USER_DOMAIN, "directory_list_external_members", ("directory_list_external_members",), cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_internal_users", ("directory_list_internal_users",), mcp_public=False, cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_all_internal_users", ("directory_list_all_internal_users",), mcp_public=False, cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_internal_departments", ("directory_list_internal_departments",), mcp_public=False, cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_all_departments", ("directory_list_all_departments",), mcp_public=False, cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_sub_departments", ("directory_list_sub_departments",), mcp_public=False, cli_public=False),
+    PublicToolSpec(USER_DOMAIN, "directory_list_external_members", ("directory_list_external_members",), mcp_public=False, cli_public=False),
 )
 
 
@@ -157,7 +162,7 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(BUILDER_DOMAIN, "app_views_apply", ("app_views_apply",), ("builder", "views", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "app_charts_apply", ("app_charts_apply",), ("builder", "charts", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "portal_apply", ("portal_apply",), ("builder", "portal", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
-    PublicToolSpec(BUILDER_DOMAIN, "app_publish_verify", ("app_publish_verify",), ("builder", "publish", "verify"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "app_publish_verify", ("app_publish_verify",), ("builder", "publish", "verify"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
 )
 
 
@@ -235,6 +240,7 @@ def cli_route_from_namespace(args: Namespace) -> tuple[str, ...] | None:
     builder_command = getattr(args, "builder_command", None)
     if not isinstance(builder_command, str) or not builder_command:
         return None
+    builder_command = "associated-resource" if builder_command == "associated-resources" else builder_command
     if builder_command == "contract":
         return ("builder", "contract")
     if builder_command == "app":

package/src/qingflow_mcp/response_trim.py

@@ -47,7 +47,6 @@ COMMON_ERROR_DROP_TOP = {
     "allowed_values",
     "missing_fields",
     "noop",
-    "ok",
 }
 
 SUCCESS_POLICY_BY_TOOL: dict[str, TransformFn] = {}
@@ -58,11 +57,18 @@ def trim_public_response(tool_name: str | None, payload: dict[str, Any]) -> dict
         return payload
     if _looks_like_failure_payload(payload):
         status = str(payload.get("status") or "").lower()
-        if tool_name in {"user:record_insert", "user:record_update", "user:record_delete"} and status in {
-            "blocked",
-            "needs_confirmation",
-            "partial_success",
-        }:
+        if _is_executed_nonfatal_payload(payload) or (
+            tool_name in {"user:record_insert", "user:record_update", "user:record_delete"}
+            and status in {
+                "blocked",
+                "needs_confirmation",
+                "partial_success",
+            }
+        ) or (
+            tool_name == "user:record_import_verify"
+            and status == "failed"
+            and "can_import" in payload
+        ):
             return trim_success_response(tool_name, payload)
         return _trim_returned_failure(payload)
     return trim_success_response(tool_name, payload)
@@ -151,12 +157,25 @@ def _parse_runtime_error_payload(exc: RuntimeError) -> dict[str, Any] | None:
 
 
 def _looks_like_failure_payload(payload: dict[str, Any]) -> bool:
+    if _is_executed_nonfatal_payload(payload):
+        return False
     if payload.get("ok") is False:
         return True
     status = str(payload.get("status") or "").lower()
     return status in {"failed", "blocked"}
 
 
+def _is_executed_nonfatal_payload(payload: dict[str, Any]) -> bool:
+    status = str(payload.get("status") or "").lower()
+    executed = bool(
+        payload.get("write_executed")
+        or payload.get("delete_executed")
+        or payload.get("action_executed")
+        or payload.get("export_executed")
+    )
+    return executed and status in {"partial_success", "verification_failed", "running", "queued", "unknown"}
+
+
 def _trim_returned_failure(payload: dict[str, Any]) -> dict[str, Any]:
     trimmed = deepcopy(payload)
     _drop_top_keys(trimmed, COMMON_ERROR_DROP_TOP)
@@ -325,15 +344,22 @@ def _trim_import_schema(payload: JSONObject) -> None:
         columns = [item for item in payload.get("expected_columns", []) if isinstance(item, dict)]
     if columns is not None:
         payload["columns"] = [_compact_import_column(item) for item in columns]
+    import_capability = payload.get("import_capability") if isinstance(payload.get("import_capability"), dict) else {}
+    if import_capability:
+        verification = payload.get("verification") if isinstance(payload.get("verification"), dict) else {}
+        if not isinstance(payload.get("verification"), dict):
+            payload["verification"] = verification
+        verification.setdefault("import_auth_source", import_capability.get("auth_source"))
+        verification.setdefault("import_capability_can_import", import_capability.get("can_import"))
     payload.pop("expected_columns", None)
     payload.pop("schema_fingerprint", None)
     payload.pop("import_capability", None)
     payload.pop("request_route", None)
-    payload.pop("verification", None)
 
     if _looks_like_import_verify(payload):
         _trim_import_verify_payload(payload)
         return
+    payload.pop("verification", None)
     if "applied_repairs" in payload or "repaired_file_path" in payload:
         _trim_import_repair_payload(payload)
         return
@@ -394,10 +420,14 @@ def _trim_record_write(payload: JSONObject) -> None:
     data.pop("normalized_payload", None)
     data.pop("human_review", None)
     data.pop("action", None)
-    for key in ("update_route", "tried_routes"):
-        value = payload.get(key)
-        if value not in (None, [], {}, ""):
-            data[key] = value
+    if payload.get("status") == "success":
+        data.pop("tried_routes", None)
+    update_route = payload.get("update_route")
+    if update_route not in (None, [], {}, ""):
+        data["update_route"] = update_route
+    tried_routes = payload.get("tried_routes")
+    if payload.get("status") != "success" and tried_routes not in (None, [], {}, ""):
+        data["tried_routes"] = tried_routes
     resource = _compact_record_resource(data.get("resource"))
     if resource:
         data["resource"] = resource
@@ -441,6 +471,7 @@ def _trim_record_write_batch(payload: JSONObject, data: JSONObject) -> None:
                     "record_id",
                     "apply_id",
                     "write_executed",
+                    "write_succeeded",
                     "verification_status",
                     "safe_to_retry",
                     "update_route",
@@ -887,6 +918,12 @@ def _compact_import_column(item: dict[str, Any]) -> dict[str, Any]:
         compact["options"] = options
     if bool(item.get("accepts_natural_input")):
         compact["accepts_natural_input"] = True
+    import_value_format = item.get("import_value_format")
+    if isinstance(import_value_format, str) and import_value_format:
+        compact["import_value_format"] = import_value_format
+    format_hint = item.get("format_hint")
+    if isinstance(format_hint, str) and format_hint:
+        compact["format_hint"] = format_hint
     if bool(item.get("requires_upload")):
         compact["requires_upload"] = True
     target_app_key = item.get("target_app_key")
@@ -902,13 +939,37 @@ def _compact_import_column(item: dict[str, Any]) -> dict[str, Any]:
 
 
 def _looks_like_import_verify(payload: JSONObject) -> bool:
-    return "verification_id" in payload and "can_import" in payload
+    if "verification_id" in payload and "can_import" in payload:
+        return True
+    return "can_import" in payload and (
+        "error_code" in payload
+        or "issues" in payload
+        or "file_path" in payload
+    )
 
 
 def _trim_import_verify_payload(payload: JSONObject) -> None:
     issues = payload.get("issues") if isinstance(payload.get("issues"), list) else []
     issue_summary = _summarize_import_issues(issues)
     payload["issue_summary"] = issue_summary
+    verification = payload.get("verification") if isinstance(payload.get("verification"), dict) else {}
+    compact_verification = {
+        key: verification.get(key)
+        for key in (
+            "import_auth_prechecked",
+            "import_auth_precheck_passed",
+            "import_auth_source",
+            "import_capability_can_import",
+            "local_precheck_passed",
+            "backend_verification_passed",
+            "auto_normalized",
+        )
+        if key in verification
+    }
+    if compact_verification:
+        payload["verification"] = compact_verification
+    else:
+        payload.pop("verification", None)
     columns = payload.get("columns")
     if "expected_columns" not in payload and isinstance(columns, list):
         payload["expected_columns"] = columns
@@ -1004,7 +1065,7 @@ def _trim_feedback(payload: JSONObject) -> None:
 
 
 def _trim_builder_envelope(payload: JSONObject) -> None:
-    if str(payload.get("status") or "").lower() == "success":
+    if str(payload.get("status") or "").lower() in {"success", "partial_success", "verification_failed"}:
         details = payload.get("details")
         if isinstance(details, dict):
             _drop_deep_keys(details, {"request_route", "base_url", "normalized_args", "suggested_next_call", "transport", "response", "body", "raw"})

package/src/qingflow_mcp/server.py

@@ -50,6 +50,7 @@ All resource tools operate with the logged-in user's Qingflow permissions.
 
 If `app_key` is unknown, use `app_list` first. Pass `query` to filter visible apps by keyword.
 If the app is known but the data range is not, use `app_get` first and choose from `accessible_views`.
+Treat an explicit `view_id` as the exact frontend view context. If `system:all` fails, do not silently switch to `system:initiated`, `system:todo`, or another system view unless the user, frontend URL, or `app_get.accessible_views` explicitly selects that view.
 If an accessible view has `analysis_supported=false`, do not use it for `record_access` or `record_list`. `boardView` and `ganttView` are special UI views, not data-access targets.
 `view_get(view_id=...)` also returns `export_capability`; it only means there is a supported export route, not that export permission has been verified.
 
@@ -57,7 +58,7 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 
 Call `record_insert_schema_get` before `record_insert`.
 For simple field changes after the target record is clear, call `record_update` directly. Use `record_update_schema_get` for diagnostics, ambiguous fields, or complex writable-scope inspection.
-Call `record_code_block_schema_get` before `record_code_block_run`.
+Prefer `record_code_block_schema_get` before `record_code_block_run` when field selection or binding diagnostics are unclear; if the exact code-block field id is already known from record/task detail, run directly.
 Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, `record_get`, or `record_logs_get`.
 Call `record_import_schema_get` when the import field mapping is unclear before template download or verify.
 
@@ -67,7 +68,7 @@ Call `record_import_schema_get` when the import field mapping is unclear before
 ## Schema Scope
 
 `record_insert_schema_get` returns the current user's insert-ready applicant schema; read `required_fields`, `optional_fields`, `runtime_linked_required_fields`, and `payload_template`.
-`record_update_schema_get` returns the current record's overall update-ready writable field set and route diagnostics across matched accessible views; read `writable_fields`, `payload_template`, `available_update_routes`, and `recommended_update_route`.
+`record_update_schema_get` returns the current record's update-ready writable field set and route diagnostics. When `view_id` is explicit, it is the exact frontend view context and must not be silently replaced by another view.
 `record_browse_schema_get(view_id=...)` returns the same readable fields shown in the selected Qingflow table view header.
 `record_access.fields` / CSV columns and `record_list.columns / where / order_by / query_fields` use that exact same view schema.
 `record_code_block_schema_get` returns code-block-ready schema for exact code block field selection.
@@ -106,8 +107,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 `app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get / record_logs_get`
 `record_insert_schema_get -> record_insert(items)`
 `record_update` for simple updates; `record_update_schema_get -> record_update` when the writable field scope is unclear.
-`record_list / record_get -> record_delete`
-`record_code_block_schema_get -> record_code_block_run`
+`record_list / record_get -> record_delete(system view_id)`
+`record_code_block_run` directly when the exact code-block field is known; otherwise `record_code_block_schema_get -> record_code_block_run`
 
 - Use `columns` as `[{{field_id}}]`
 - Use `record_list(query=..., query_fields=[{{field_id}}])` for fuzzy single-record lookup, then follow `lookup.next_action`; `query_fields` is search scope and `columns` is display shape.
@@ -116,14 +117,14 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - Legacy forms such as bare integer `field_id`, `fieldId`, `operator`, `values`, or `order` may still parse, but they are compatibility-only and not the canonical DSL
 
 - `record_insert` defaults to an applicant-node `items` array; each item contains a field-title keyed `fields` map. A single insert is one item.
-- `record_update` uses a field-title keyed `fields` map. It first tries the data-manager direct update route, then falls back to the frontend custom-view detail edit route when the selected view can cover the payload; if a unique current-user todo task for the same record exposes editable fields, it can finally use the workflow save-only route. Read `update_route` and `tried_routes` after execution.
+- `record_update` uses a field-title keyed `fields` map. It first tries the data-manager direct update route, then falls back to the frontend custom-view detail edit route when the selected view can cover the payload; if a unique current-user todo task for the same record exposes editable fields, it can finally use the workflow save-only route. On success, read `status`, `update_route`, and `verification_status`; on failure, read the failure reason and route diagnostics.
 - For insert, `runtime_linked_required_fields` means required-but-not-directly-writable fields that are usually supplied by runtime linkage or upstream context.
 - For insert, fields marked `may_become_required=true` stay in `optional_fields`; they are still directly writable, but linked visibility or option-driven rules can make them required at runtime.
 - Read field-level `linkage` whenever present on `record_insert_schema_get` or `record_update_schema_get`; it is the static hint for linked visibility, reference-driven auto fill, and formula/default auto-fill behavior.
 - `linkage.sources` lists upstream field titles that influence the current field; `linkage.affects_fields` lists downstream fields that may change when the current field changes.
 - `linkage.kind=logic_visibility` means linked visibility or option-driven rules are involved; `linkage.kind=reference_fill` means reference/default matching logic is involved; `linkage.kind=formula_fill` means formula/default auto-fill logic is involved.
-- `record_update_schema_get` exposes the overall writable field set and route candidates for the record, but not every field combination is guaranteed; `record_update` still needs data-manager permission, one single matched custom view that can cover the payload, or one unique editable current-user todo task.
-- `record_delete` deletes by `record_id` or `record_ids`.
+- `record_update_schema_get` exposes the writable field set and route candidates for the record; with an explicit `view_id`, diagnostics stay scoped to that selected frontend view. Not every field combination is guaranteed; `record_update` still needs data-manager permission, one single matched custom view that can cover the payload, or one unique editable current-user todo task.
+- `record_delete` deletes by `record_id` or `record_ids`, and requires an accessible system `view_id`; use custom views only to locate records, not as the delete route.
 - `record_get` is the single-record frontend detail context tool. It returns detail-page visible fields, one-level relation targets, first-page data/workflow logs, associated views/reports, local readable image assets, local downloadable file assets, unavailable context, and `semantic_context`.
 - Use `record_logs_get` only when the user needs the full visible data/workflow log history for a specific record. It writes JSONL files locally and returns file paths plus completeness metadata; do not expect full log arrays in the response.
 - Read record images from `record_get.media_assets.items[].local_path` when `readable_by_agent=true`; read attachments/documents/tables from `record_get.file_assets.items[].local_path` and `extraction.text_path` when present. `record_get` follows the frontend storage cookie redirect path for Qingflow attachments, and remote file URLs should not be treated as directly readable.
@@ -140,7 +141,8 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 Use `record_code_block_run` when the user wants to execute a form code-block field against an existing record.
 
-- Always resolve the exact code-block field from `record_code_block_schema_get` first.
+- Prefer resolving the exact code-block field from `record_code_block_schema_get`, but do not treat applicant-schema 40002 as final denial when record/task detail already exposes the code-block field id.
+- `record_code_block_run` uses the record/task detail answers for the execution context; when applicant schema is unavailable it can still execute with a numeric code-block field id, but schema-bound relation writeback may be skipped.
 - Treat code-block execution as write-capable, not read-only.
 - If the code block is bound to relation outputs, Qingflow may calculate target answers and write them back automatically.
 - For safe debugging, pass `apply_writeback=false` and inspect the parsed alias results plus `relation.calculated_answers_preview` before allowing any writeback.
@@ -186,7 +188,7 @@ Use `record_code_block_run` when the user wants to execute a form code-block fie
 - `task_action_execute(task_id=..., action=...)` is also supported; MCP resolves the current todo locator internally before calling the real action route.
 - `task_workflow_log_get(task_id=...)` and `task_associated_report_detail_get(task_id=...)` are also supported for the current todo context.
 - Use `task_associated_report_detail_get` for associated view or report details.
-- Use `task_workflow_log_get` for the current task context workflow log page. For full record-level data/workflow logs, use `record_logs_get(app_key, record_id, view_id?)`.
+- Use `task_workflow_log_get` for the current task context workflow log page. For full record-level data/workflow logs, first choose an accessible view with `app_get`, then call `record_logs_get(app_key, record_id, view_id)` with that same explicit `view_id`.
 - Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
 
 ## Time Handling

package/src/qingflow_mcp/server_app_builder.py

@@ -43,9 +43,10 @@ def build_builder_server() -> FastMCP:
             "Builder apply/write outputs include schema_version, operation, summary, and resources[]; use resources[].id/key/name/ids/parent as the stable UI and agent display entry, and keep legacy fields such as field_diff/views_diff/chart_results only for compatibility or troubleshooting. "
             "For existing object parameter replacement, prefer patch_views, patch_buttons, patch_resources, and patch_charts with set/unset; the tool reads current config and full-saves internally, while upsert_* is for creation or full target configuration and should not be used as an incomplete partial update. "
             "For builder delete/remove apply results, separate delete execution from readback verification: after DELETE is sent, resources expose delete_executed, readback_status, and safe_to_retry_delete=false. If readback_status is unavailable or still_exists, do not blindly repeat the delete; confirm later with app_get/view_get/chart_get or the relevant apply readback. Views/buttons use single-item readback; associated resources use one app-level resource-pool readback because there is no confirmed single-item GET. "
+            "For builder write/apply results, separate write execution from final readback verification: status=partial_success with write_executed=true and safe_to_retry=false means the write was sent or succeeded, while final readback, publish verification, or metadata confirmation is pending or permission-restricted. Report it as written but unverified; do not repeat the same write blindly. "
             "For app_schema_apply, configure data title and data cover directly in field JSON with as_data_title=true and as_data_cover=true; data title is required and exactly one field may be marked, while data cover is optional and must be a top-level attachment field. For multi-app creation, pass apps[]/--apps-file on app_schema_apply; each item may have client_key, and relation fields may use target_app_ref to point at another same-call client_key. "
-            "For app_views_apply, keep fixed saved filters in filters and configure the frontend query panel separately with query_conditions; query_conditions.rows is a matrix of field names compiled to backend queryCondition queIds. New views default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless associated_resources is explicitly patched. "
-            "For custom button body create/update/delete and view placement, use app_custom_buttons_apply. For addData buttons, prefer trigger_add_data_config.target_app_key + field_mappings/default_values; do not ask agents to write raw que_relation unless maintaining a legacy config. field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id means current record id (-17), 编号/record_number means visible record number (0). To fill a target relation with the current record, map {'source_field': '数据ID', 'target_field': '目标引用字段'}; default_values is only for static constants. View button bindings merge by default and merge-mode view_configs must include buttons; use view_configs[].mode=replace or explicit buttons=[] only when clearing/replacing existing bindings is intended. Builder view_key arguments are raw keys from app_get.views[].view_key and must not be prefixed with custom:. "
+            "For app_views_apply, keep fixed saved filters in filters and configure the frontend query panel separately with query_conditions; query_conditions.rows is a matrix of field names compiled to backend queryCondition queIds. New views default associated report/view display to visible with limit_type=all; existing views preserve their current associated display unless associated_resources is explicitly patched. View writes use ViewManagementAuth (beingViewManageStatus), falling back to DataManageAuth when advanced app permissions are not enabled. "
+            "For custom button body create/update/delete and view placement, use app_custom_buttons_apply. Button body writes require EditAppAuth; view_configs placement writes require ViewManagementAuth, matching the backend viewConfig route. For addData buttons, prefer trigger_add_data_config.target_app_key + field_mappings/default_values; do not ask agents to write raw que_relation unless maintaining a legacy config. field_mappings.source_field accepts source schema fields and supported system fields: 数据ID/row_record_id/apply_id/_id means current record id (-17), 编号/record_number means visible record number (0). To fill a target relation with the current record, map {'source_field': '数据ID', 'target_field': '目标引用字段'}; default_values is only for static constants. View button bindings merge by default and merge-mode view_configs must include buttons; use view_configs[].mode=replace or explicit buttons=[] only when clearing/replacing existing bindings is intended. Builder view_key arguments are raw keys from app_get.views[].view_key and must not be prefixed with custom:. "
             "For BI reports, keep report-body development separate from Qingflow in-app display: use app_charts_apply to create, update, remove, or reorder app-source QingBI chart bodies/configs with dataSourceType=qingflow; chart dimension/metric/filter/query fields must come from app_get_fields.chart_fields, not record schema or form-only fields; dataset BI reports are not created or edited by app_charts_apply yet and should be created in QingBI first, then attached with app_associated_resources_apply using report_source=dataset. "
             "For associated views/reports, use app_associated_resources_apply. Use match_mappings for filtering associated resources: dynamic current-record conditions use source_field, static conditions use value. match_mappings also supports 数据ID(-17) and 编号(0). Do not ask agents to write raw match_rules unless preserving a legacy backend config. "
             "For associated reports/views, use app_associated_resources_apply for both the app-level associated_resources pool and per-view display config; associated_item_id is the app-level form_asos_chart.id, and view_configs/remove/reorder may also pass an existing resource's chart_id/chart_key/view_key because the tool resolves those to the internal id. Before creating an associated resource, read app_get.associated_resources and reuse an existing matching target_app_key + view_key/chart_key through patch_resources; client_key only works inside one apply call and is not persisted. Do not ask agents to pass backend raw sourceType: views infer the internal Qingflow view source, reports default to BI app reports, and dataset reports use report_source=dataset. "