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

package/src/qingflow_mcp/server_app_user.py

@@ -33,6 +33,7 @@ def build_user_server() -> FastMCP:
 
 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.
 
@@ -48,7 +49,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.
 
@@ -59,11 +60,11 @@ Call `record_import_schema_get` when the import field mapping is unclear before
 
 `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`.
 Inside `optional_fields`, any field with `may_become_required=true` is still writable, but may become required when linked visibility or option-driven runtime rules activate.
-`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; a missing field means it is not readable in that view.
 `searchQueIds` is a backend full-text search scope, not an output-column/projection mechanism.
-`record_code_block_schema_get` returns code-block-ready schema for exact code block field selection.
+`record_code_block_schema_get` returns code-block-ready schema for exact code block field selection when the applicant schema is readable.
 `record_import_schema_get` returns import-ready column metadata.
 
 - Hidden fields are omitted.
@@ -105,8 +106,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`
 `portal_list -> portal_get -> chart_get / view_get`
 `portal_get -> view_get -> record_list`
 
@@ -117,14 +118,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 update 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 update 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.
@@ -142,7 +143,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.
@@ -191,7 +193,7 @@ Use export only when the user explicitly asks to export/download/generate an Exc
 - `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`.
 - Treat `task_action_execute` as the tool-level action enum surface; the current task's real actions are only the ones listed in `task_get.capabilities.available_actions`.
 - Use `task_action_execute(action="save_only", fields=...)` when the user wants to save editable field changes on the current node without advancing the workflow.
@@ -263,10 +265,11 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     def record_export_start(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
-        view_id: str = "system:all",
+        view_id: str = "",
         columns: list[dict | int] | None = None,
         where: list[dict] | None = None,
         order_by: list[dict] | None = None,
+        record_id: str | int | None = None,
         record_ids: list[str | int] | None = None,
         include_workflow_log: bool = False,
     ) -> dict:
@@ -277,6 +280,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
             columns=columns or [],
             where=where or [],
             order_by=order_by or [],
+            record_id=record_id,
             record_ids=record_ids or [],
             include_workflow_log=include_workflow_log,
         )
@@ -304,10 +308,11 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
     def record_export_direct(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
-        view_id: str = "system:all",
+        view_id: str = "",
         columns: list[dict | int] | None = None,
         where: list[dict] | None = None,
         order_by: list[dict] | None = None,
+        record_id: str | int | None = None,
         record_ids: list[str | int] | None = None,
         include_workflow_log: bool = False,
         download_to_path: str | None = None,
@@ -320,6 +325,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
             columns=columns or [],
             where=where or [],
             order_by=order_by or [],
+            record_id=record_id,
             record_ids=record_ids or [],
             include_workflow_log=include_workflow_log,
             download_to_path=download_to_path,
@@ -474,7 +480,7 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
 
     code_block_tools.register(server)
     task_context_tools.register(server)
-    directory_tools.register(server)
+    directory_tools.register_frontend_search(server)
 
     return server
 

package/src/qingflow_mcp/session_store.py

@@ -176,17 +176,21 @@ class SessionStore:
             return memory_session
         if not session_profile:
             return None
-        token = self._get_secret(self._token_key(profile)) if session_profile.persisted else None
-        if not token:
-            token = session_profile.token
+        token = session_profile.token
+        if not token and session_profile.persisted:
+            token = self._get_secret(self._token_key(profile))
         if not token:
             return None
-        login_token = self._get_secret(self._login_token_key(profile)) if session_profile.persisted else None
-        credential = self._get_secret(self._credential_key(profile)) if session_profile.persisted else None
+        login_token = session_profile.login_token
+        if not login_token and session_profile.persisted:
+            login_token = self._get_secret(self._login_token_key(profile))
+        credential = session_profile.credential
+        if not credential and session_profile.persisted:
+            credential = self._get_secret(self._credential_key(profile))
         backend_session = BackendSession(
             token=token,
-            login_token=login_token or session_profile.login_token,
-            credential=credential or session_profile.credential,
+            login_token=login_token,
+            credential=credential,
             profile=profile,
             base_url=session_profile.base_url,
             qf_version=session_profile.qf_version,

package/src/qingflow_mcp/solution/executor.py

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

package/src/qingflow_mcp/tools/ai_builder_tools.py

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