@josephyan/qingflow-app-builder-mcp 0.2.0-beta.11 → 0.2.0-beta.12

package/README.md

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

package/package.json

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

package/pyproject.toml

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

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

@@ -34,6 +34,7 @@ Note:
 - For flow presets, map natural language to canonical values before calling MCP:
   - “默认审批/基础审批/普通审批” -> `basic_approval`
   - “先填报再审批/提交后审批” -> `basic_fill_then_approve`
+- For first-time flow or view work in a session, read `builder_tool_contract` before planning so keys, aliases, presets, and minimal examples come from MCP instead of memory.
 - For workflow assignees, prefer roles over explicit members:
   - use `role_search` first
   - use `member_search` only when the user explicitly names members or no stable role exists
@@ -69,25 +70,29 @@ For builder work:
 
 For view work, keep the order strict:
 
-1. `app_read_fields`
-2. `app_read_views_summary`
-3. `app_views_plan`
-4. `app_views_apply`
+1. `builder_tool_contract`
+2. `app_read_fields`
+3. `app_read_views_summary`
+4. `app_views_plan`
+5. `app_views_apply`
+6. `app_read_views_summary` again whenever `app_views_apply` returns `failed` or `partial_success`
 
 For flow work, keep the order strict:
 
-1. `app_read_fields`
-2. `app_read_flow_summary`
-3. `role_search` or `member_search` if assignees need to come from the directory
-4. `role_create` if the user wants a reusable role and no suitable role exists yet
-5. Start from a canonical preset when possible
-6. Use patch-style edits to that skeleton instead of freehand full-graph generation
-7. Declare approver/fill/copy assignees explicitly:
+1. `builder_tool_contract`
+2. `app_read_fields`
+3. `app_read_flow_summary`
+4. `role_search` or `member_search` if assignees need to come from the directory
+5. `role_create` if the user wants a reusable role and no suitable role exists yet
+6. Start from a canonical preset when possible
+7. Use patch-style edits to that skeleton instead of freehand full-graph generation
+8. Declare approver/fill/copy assignees explicitly:
    - prefer `assignees.role_names`
    - support `assignees.member_names` / `assignees.member_emails` / `assignees.member_uids`
-8. When a node must edit specific fields, declare `permissions.editable_fields`
-9. `app_flow_plan`
-10. `app_flow_apply`
+9. When a node must edit specific fields, declare `permissions.editable_fields`
+10. `app_flow_plan`
+11. `app_flow_apply`
+12. `app_read_flow_summary` after apply whenever the user asked for verification or apply returns `partial_success`
 
 In `prod`, keep `plan` and `apply` as separate phases unless the user explicitly asks for a direct live execution.
 
@@ -112,6 +117,8 @@ For additive work on existing systems:
   - `assignees.role_names`
   - `assignees.member_names`
   - `permissions.editable_fields`
+- Reuse `app_flow_plan` output directly when it succeeds. Do not rewrite it into internal keys such as `role_entries` or `editable_que_ids`.
+- Reuse `app_views_plan` output directly when it succeeds. Do not re-expand aliases such as `column_names`.
 - Do not guess role ids or member ids. Resolve them from the directory first.
 - `app_schema_apply` does not treat package attachment as success criteria; if package ownership matters, verify `tag_ids_after` and call `package_attach_app` explicitly.
 - `package_attach_app` is the source of truth for package ownership; do not assume app creation or publish implicitly attaches the app.
@@ -125,7 +132,11 @@ For additive work on existing systems:
 - `app_publish_verify` is the publish source of truth.
 - If readback mismatches the UI, compare `request_route` and do not assume the builder hit the same `qf_version` as the browser
 - Treat post-write readback as the source of truth, not just write status codes
+- For views, a top-level `VIEW_APPLY_FAILED` does not prove all requested views failed. Read back the view list and verify which views actually landed.
 - In final user-facing summaries, distinguish clearly between:
+  - contract is visible / canonical shape is known
+  - plan succeeded
+  - apply landed and readback verified it
   - base template/skeleton applied
   - business-specific rules completed
   - remaining gaps or follow-up patches

package/skills/qingflow-app-builder/references/gotchas.md

@@ -41,6 +41,10 @@
 - Do not repeat create steps after `app_key` already exists
 - For backend rejects, keep the retry narrow: retry only the failed tool, not the whole chain
 - For `VALIDATION_ERROR`, do not keep guessing. Reuse `suggested_next_call`, `canonical_arguments`, `allowed_keys`, and `allowed_values` first.
+- For flow work, do not replay internal keys from old logs or plan outputs. Public builder calls should stay on:
+  - `assignees.role_ids` / `assignees.member_uids` / `assignees.member_emails`
+  - `permissions.editable_fields`
+- For view work, treat `columns` as the only canonical public key. `app_read_views_summary` and `app_views_plan/apply` should all be read and written in that shape.
 - If a view or flow write fails, report the smallest next action:
   - wrong key -> switch to canonical key
   - unsupported preset -> switch to allowed canonical preset

package/skills/qingflow-app-builder/references/tool-selection.md

@@ -62,9 +62,9 @@ These execute normalized patches and publish by default unless `publish=false`.
 - Tidy layout:
   `app_read_layout_summary -> app_layout_plan -> app_layout_apply`
 - Add workflow:
-  `app_read_fields -> app_read_flow_summary -> role_search/member_search -> app_flow_plan -> app_flow_apply`
+  `builder_tool_contract -> app_read_fields -> app_read_flow_summary -> role_search/member_search -> app_flow_plan -> app_flow_apply -> app_read_flow_summary`
 - Add views:
-  `app_read_fields -> app_read_views_summary -> app_views_plan -> app_views_apply`
+  `builder_tool_contract -> app_read_fields -> app_read_views_summary -> app_views_plan -> app_views_apply -> app_read_views_summary`
 
 ## Avoid
 
@@ -73,6 +73,7 @@ These execute normalized patches and publish by default unless `publish=false`.
 - Do not create a new package without first asking the user to confirm package creation
 - Do not skip summary reads before flow or view work
 - Do not emit `column_names`; always use `columns`
+- Do not reuse internal flow keys such as `role_entries` or `editable_que_ids` in public builder calls
 - Do not pass natural-language preset guesses such as `default_approval`; map them to canonical preset values first
 - Do not omit assignees on approval/fill/copy nodes
 - Do not guess role ids, member ids, or editable field ids; resolve names first

package/skills/qingflow-app-builder/references/update-flow.md

@@ -4,14 +4,16 @@ Use this when the app already exists and the task is only about workflow.
 
 ## Minimal sequence
 
-1. `app_read_fields`
-2. `app_read_flow_summary`
-3. `role_search` or `member_search`
-4. `role_create` if the user wants a reusable directory role and no good role exists
-5. start from a canonical preset when possible
-6. patch the skeleton instead of freehanding a full graph
-7. `app_flow_plan`
-8. `app_flow_apply`
+1. `builder_tool_contract(tool_name="app_flow_plan")`
+2. `app_read_fields`
+3. `app_read_flow_summary`
+4. `role_search` or `member_search`
+5. `role_create` if the user wants a reusable directory role and no good role exists
+6. start from a canonical preset when possible
+7. patch the skeleton instead of freehanding a full graph
+8. `app_flow_plan`
+9. `app_flow_apply`
+10. `app_read_flow_summary` when apply returns `partial_success` or the user asked for verification
 
 If you are unsure about presets or node shapes, call `builder_tool_contract(tool_name="app_flow_apply")` before guessing.
 
@@ -142,6 +144,8 @@ Only after that should you use explicit nodes:
 }
 ```
 
+After `app_flow_plan` succeeds, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite the result into internal fields such as `role_entries` or `editable_que_ids`.
+
 ## Common failures
 
 ### `FLOW_ASSIGNEE_REQUIRED`
@@ -159,6 +163,13 @@ Preferred fix order:
 
 The workflow depends on fields that do not exist yet, usually `status`. Fix schema first.
 
+Preferred recovery:
+
+1. use the returned `suggested_next_call`
+2. apply the minimal schema patch
+3. rerun `app_read_fields`
+4. rerun `app_flow_plan`
+
 ### `INVALID_FLOW_EDGE`
 
 One or more transitions reference unknown nodes or create an invalid graph.
@@ -193,6 +204,11 @@ Do not keep guessing preset names or node shapes. First:
    - `assignees.member_names`
    - `permissions.editable_fields`
 
+Do not copy internal keys from old plan outputs or logs, including:
+
+- `role_entries`
+- `editable_que_ids`
+
 ## Notes
 
 - `mode=replace` is the only supported flow apply mode

package/skills/qingflow-app-builder/references/update-views.md

@@ -4,10 +4,12 @@ Use this when the task is only about table, card, board, or gantt views.
 
 ## Minimal sequence
 
-1. `app_read_fields`
-2. `app_read_views_summary`
-3. `app_views_plan`
-4. `app_views_apply`
+1. `builder_tool_contract(tool_name="app_views_plan")`
+2. `app_read_fields`
+3. `app_read_views_summary`
+4. `app_views_plan`
+5. `app_views_apply`
+6. `app_read_views_summary` again whenever apply returns `failed` or `partial_success`
 
 If you are unsure about keys or view types, call `builder_tool_contract(tool_name="app_views_apply")` before guessing.
 
@@ -62,6 +64,8 @@ Apply it:
 }
 ```
 
+After `app_views_plan` succeeds, prefer reusing its `suggested_next_call.arguments` directly. Do not rewrite aliases back into non-canonical keys such as `column_names`.
+
 Board example:
 
 ```json
@@ -146,12 +150,14 @@ Do not repeat `app_views_apply` with guessed keys. First:
 
 1. check `suggested_next_call`
 2. reuse `canonical_arguments` if present
-3. if needed, call `builder_tool_contract`
-4. retry only the minimal failed view patch
+3. call `app_read_views_summary` to see whether any requested views landed anyway
+4. if needed, call `builder_tool_contract`
+5. retry only the minimal failed view patch
 
 ## Notes
 
 - `fields` is accepted as an alias for `columns`, but skill examples should still use `columns`
 - `column_names` should not appear in skill examples
+- `app_read_views_summary` should be treated as canonical readback and now returns `columns`
 - `filters` are ANDed together as one flat condition group
 - `app_views_apply` publishes by default

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/builder_facade/service.py

@@ -679,6 +679,58 @@ class AiBuilderFacade:
             normalized_nodes.append(normalized_node)
         return normalized_nodes, issues
 
+    def _canonicalize_flow_nodes_for_public_output(self, nodes: list[dict[str, Any]]) -> list[dict[str, Any]]:
+        public_nodes: list[dict[str, Any]] = []
+        for node in nodes:
+            if not isinstance(node, dict):
+                continue
+            payload = deepcopy(node)
+            assignees = payload.get("assignees") if isinstance(payload.get("assignees"), dict) else {}
+            permissions = payload.get("permissions") if isinstance(payload.get("permissions"), dict) else {}
+            public_assignees: dict[str, Any] = {}
+            role_ids = [
+                role_id
+                for role_id in (
+                    _coerce_positive_int(entry.get("roleId"))
+                    for entry in (assignees.get("role_entries") or [])
+                    if isinstance(entry, dict)
+                )
+                if role_id is not None
+            ]
+            member_uids = [
+                member_uid
+                for member_uid in (_coerce_positive_int(value) for value in (assignees.get("member_uids") or []))
+                if member_uid is not None
+            ]
+            if role_ids:
+                public_assignees["role_ids"] = role_ids
+            if member_uids:
+                public_assignees["member_uids"] = member_uids
+            if bool(assignees.get("include_sub_departs")):
+                public_assignees["include_sub_departs"] = True
+            public_permissions: dict[str, Any] = {}
+            editable_fields = [str(name) for name in (permissions.get("editable_fields") or []) if str(name or "").strip()]
+            if editable_fields:
+                public_permissions["editable_fields"] = editable_fields
+            config_payload = payload.get("config") if isinstance(payload.get("config"), dict) else {}
+            if isinstance(config_payload, dict):
+                config_payload = deepcopy(config_payload)
+                config_payload.pop("conditionFormatMatrix", None)
+            if public_assignees:
+                payload["assignees"] = public_assignees
+            else:
+                payload.pop("assignees", None)
+            if public_permissions:
+                payload["permissions"] = public_permissions
+            else:
+                payload.pop("permissions", None)
+            if config_payload:
+                payload["config"] = config_payload
+            else:
+                payload.pop("config", None)
+            public_nodes.append(payload)
+        return public_nodes
+
     def package_attach_app(
         self,
         *,
@@ -1287,7 +1339,8 @@ class AiBuilderFacade:
         if fields_result.get("status") == "failed":
             return fields_result
         current_fields = fields_result.get("fields", [])
-        nodes, resolution_issues = self._normalize_flow_nodes(profile=profile, current_fields=current_fields, nodes=nodes)
+        normalized_nodes, resolution_issues = self._normalize_flow_nodes(profile=profile, current_fields=current_fields, nodes=nodes)
+        public_nodes = self._canonicalize_flow_nodes_for_public_output(normalized_nodes)
         if resolution_issues:
             first_issue = resolution_issues[0]
             suggested_call = None
@@ -1304,17 +1357,17 @@ class AiBuilderFacade:
                     "app_key": request.app_key,
                     "mode": str(request.mode or "replace"),
                     "preset": request.preset.value if request.preset else None,
-                    "nodes": nodes,
+                    "nodes": public_nodes,
                     "transitions": transitions,
                 },
                 details={"issues": resolution_issues},
                 suggested_next_call=suggested_call,
             )
         status_field_present = _infer_status_field_id(current_fields) is not None
-        node_types = {str(node.get("type") or "") for node in nodes}
+        node_types = {str(node.get("type") or "") for node in normalized_nodes}
         assignee_required_nodes = [
             node.get("id")
-            for node in nodes
+            for node in normalized_nodes
             if str(node.get("type") or "") in {"approve", "fill", "copy"}
             and not (
                 (node.get("assignees") or {}).get("role_entries")
@@ -1329,7 +1382,7 @@ class AiBuilderFacade:
                     "app_key": request.app_key,
                     "mode": str(request.mode or "replace"),
                     "preset": request.preset.value if request.preset else None,
-                    "nodes": nodes,
+                    "nodes": public_nodes,
                     "transitions": transitions,
                 },
                 details={"node_ids": assignee_required_nodes, "policy": "prefer role assignees; explicit members are also supported"},
@@ -1342,7 +1395,7 @@ class AiBuilderFacade:
                 normalized_args={
                     "app_key": request.app_key,
                     "mode": str(request.mode or "replace"),
-                    "nodes": nodes,
+                    "nodes": public_nodes,
                     "transitions": transitions,
                 },
                 details={"missing_dependencies": ["status field"]},
@@ -1359,12 +1412,12 @@ class AiBuilderFacade:
                     },
                 },
             )
-        workflow = _build_public_workflow_spec(nodes=nodes, transitions=transitions)
+        workflow = _build_public_workflow_spec(nodes=normalized_nodes, transitions=transitions)
         if workflow.get("status") == "failed":
             workflow["normalized_args"] = {
                 "app_key": request.app_key,
                 "mode": str(request.mode or "replace"),
-                "nodes": nodes,
+                "nodes": public_nodes,
                 "transitions": transitions,
             }
             workflow["suggested_next_call"] = {
@@ -1373,7 +1426,7 @@ class AiBuilderFacade:
                     "profile": profile,
                     "app_key": request.app_key,
                     "mode": "replace",
-                    "nodes": nodes,
+                    "nodes": public_nodes,
                     "transitions": transitions,
                 },
             }
@@ -1381,7 +1434,7 @@ class AiBuilderFacade:
         normalized_args = {
             "app_key": request.app_key,
             "mode": str(request.mode or "replace"),
-            "nodes": nodes,
+            "nodes": public_nodes,
             "transitions": transitions,
         }
         return {
@@ -2030,7 +2083,9 @@ class AiBuilderFacade:
             )
         entity = _entity_spec_from_app(base_info=base, schema=schema, views=None)
         current_fields = _parse_schema(schema)["fields"]
-        nodes, resolution_issues = self._normalize_flow_nodes(profile=profile, current_fields=current_fields, nodes=nodes)
+        normalized_nodes, resolution_issues = self._normalize_flow_nodes(profile=profile, current_fields=current_fields, nodes=nodes)
+        public_nodes = self._canonicalize_flow_nodes_for_public_output(normalized_nodes)
+        normalized_args["nodes"] = public_nodes
         if resolution_issues:
             first_issue = resolution_issues[0]
             suggested_call = None
@@ -2049,7 +2104,7 @@ class AiBuilderFacade:
             )
         assignee_required_nodes = [
             node.get("id")
-            for node in nodes
+            for node in normalized_nodes
             if str(node.get("type") or "") in {"approve", "fill", "copy"}
             and not (
                 (node.get("assignees") or {}).get("role_entries")
@@ -2064,13 +2119,13 @@ class AiBuilderFacade:
                 details={"node_ids": assignee_required_nodes, "policy": "prefer role assignees; explicit members are also supported"},
                 suggested_next_call={"tool_name": "role_search", "arguments": {"profile": profile, "keyword": ""}},
             )
-        workflow_spec = _build_public_workflow_spec(nodes=nodes, transitions=transitions)
+        workflow_spec = _build_public_workflow_spec(nodes=normalized_nodes, transitions=transitions)
         if workflow_spec.get("status") == "failed":
             workflow_spec["normalized_args"] = normalized_args
             workflow_spec.setdefault("request_id", None)
             workflow_spec["suggested_next_call"] = {"tool_name": "app_flow_plan", "arguments": {"profile": profile, **normalized_args}}
             return workflow_spec
-        desired_node_count = len([node for node in nodes if node.get("type") != "end"])
+        desired_node_count = len([node for node in normalized_nodes if node.get("type") != "end"])
         current_workflow, _workflow_unavailable = self._load_workflow_result(profile=profile, app_key=app_key, tolerate_404=True)
         current_node_count = len(_summarize_workflow_nodes(current_workflow))
         if current_node_count == desired_node_count and desired_node_count > 0:
@@ -2124,7 +2179,7 @@ class AiBuilderFacade:
                 arguments.setdefault("profile", profile)
                 arguments.setdefault("app_key", app_key)
                 arguments.setdefault("mode", mode)
-                arguments.setdefault("nodes", nodes)
+                arguments.setdefault("nodes", public_nodes)
                 arguments.setdefault("transitions", transitions)
                 suggested_next_call["arguments"] = arguments
             failed["suggested_next_call"] = suggested_next_call
@@ -2216,14 +2271,17 @@ class AiBuilderFacade:
             if isinstance(field, dict) and str(field.get("name") or "")
         }
         removed: list[str] = []
+        view_results: list[dict[str, Any]] = []
         for name in remove_views:
             key = existing_by_name.get(name)
             if key:
                 self.views.view_delete(profile=profile, viewgraph_key=key)
                 removed.append(name)
                 existing_by_name.pop(name, None)
+                view_results.append({"name": name, "type": None, "status": "removed"})
         created: list[str] = []
         updated: list[str] = []
+        failed_views: list[dict[str, Any]] = []
         existing_view_list = [
             view
             for view in (existing_views if isinstance(existing_views, list) else [])
@@ -2301,6 +2359,7 @@ class AiBuilderFacade:
                     )
                     self.views.view_update(profile=profile, viewgraph_key=existing_key, payload=payload)
                     updated.append(patch.name)
+                    view_results.append({"name": patch.name, "type": patch.type.value, "status": "updated"})
                 else:
                     template_key = _pick_view_template_key(existing_view_list, desired_type=patch.type.value)
                     if patch.type.value == "table" and template_key:
@@ -2326,9 +2385,13 @@ class AiBuilderFacade:
                         )
                         self.views.view_create(profile=profile, payload=payload)
                     created.append(patch.name)
+                    view_results.append({"name": patch.name, "type": patch.type.value, "status": "created"})
             except (QingflowApiError, RuntimeError) as error:
                 api_error = _coerce_api_error(error)
-                if api_error.backend_code == 48104:
+                should_retry_minimal = api_error.backend_code == 48104 or (
+                    patch.type.value == "table" and bool(patch.filters) and api_error.http_status is not None and api_error.http_status >= 500
+                )
+                if should_retry_minimal:
                     try:
                         if existing_key or created_key:
                             target_key = created_key or existing_key or ""
@@ -2342,8 +2405,14 @@ class AiBuilderFacade:
                             self.views.view_update(profile=profile, viewgraph_key=target_key, payload=fallback_payload)
                             if existing_key:
                                 updated.append(patch.name)
+                                view_results.append(
+                                    {"name": patch.name, "type": patch.type.value, "status": "updated", "fallback_applied": True}
+                                )
                             else:
                                 created.append(patch.name)
+                                view_results.append(
+                                    {"name": patch.name, "type": patch.type.value, "status": "created", "fallback_applied": True}
+                                )
                             continue
                         fallback_payload = _build_minimal_view_payload(
                             app_key=app_key,
@@ -2354,6 +2423,7 @@ class AiBuilderFacade:
                         )
                         self.views.view_create(profile=profile, payload=fallback_payload)
                         created.append(patch.name)
+                        view_results.append({"name": patch.name, "type": patch.type.value, "status": "created", "fallback_applied": True})
                         continue
                     except (QingflowApiError, RuntimeError) as fallback_error:
                         api_error = _coerce_api_error(fallback_error)
@@ -2362,11 +2432,17 @@ class AiBuilderFacade:
                         self.views.view_delete(profile=profile, viewgraph_key=created_key)
                     except Exception:
                         pass
-                return _failed_from_api_error(
-                    "VIEW_APPLY_FAILED",
-                    api_error,
-                    normalized_args=normalized_args,
-                    details={
+                failure_entry = {
+                    "name": patch.name,
+                    "type": patch.type.value,
+                    "status": "failed",
+                    "error_code": "VIEW_APPLY_FAILED",
+                    "message": _public_error_message("VIEW_APPLY_FAILED", api_error),
+                    "request_id": api_error.request_id,
+                    "backend_code": api_error.backend_code,
+                    "http_status": None if api_error.http_status == 404 else api_error.http_status,
+                    "operation": "update" if existing_key or created_key else "create",
+                    "details": {
                         "app_key": app_key,
                         "view_name": patch.name,
                         "view_type": patch.type.value,
@@ -2377,12 +2453,16 @@ class AiBuilderFacade:
                         "end_field": patch.end_field,
                         "title_field": patch.title_field,
                         "operation": "update" if existing_key or created_key else "create",
+                        "transport_error": {
+                            "http_status": api_error.http_status,
+                            "backend_code": api_error.backend_code,
+                            "category": api_error.category,
+                        },
                     },
-                    suggested_next_call={
-                        "tool_name": "app_views_plan",
-                        "arguments": {"profile": profile, "app_key": app_key},
-                    },
-                )
+                }
+                failed_views.append(failure_entry)
+                view_results.append(failure_entry)
+                continue
         try:
             verified_view_result, verified_views_unavailable = self._load_views_result(profile=profile, app_key=app_key, tolerate_404=True)
         except (QingflowApiError, RuntimeError) as error:
@@ -2401,6 +2481,63 @@ class AiBuilderFacade:
         }
         verified = (not verified_views_unavailable) and all(name in verified_names for name in created + updated) and all(name not in verified_names for name in removed)
         noop = not created and not updated and not removed
+        if failed_views:
+            successful_changes = bool(created or updated or removed)
+            verification_by_view = []
+            for item in view_results:
+                if item.get("status") in {"created", "updated"}:
+                    verification_by_view.append(
+                        {
+                            "name": item.get("name"),
+                            "type": item.get("type"),
+                            "status": item.get("status"),
+                            "present_in_readback": None if verified_views_unavailable else item.get("name") in verified_names,
+                        }
+                    )
+                elif item.get("status") == "removed":
+                    verification_by_view.append(
+                        {
+                            "name": item.get("name"),
+                            "type": item.get("type"),
+                            "status": "removed",
+                            "present_in_readback": None if verified_views_unavailable else item.get("name") not in verified_names,
+                        }
+                    )
+                else:
+                    verification_by_view.append(
+                        {
+                            "name": item.get("name"),
+                            "type": item.get("type"),
+                            "status": "failed",
+                            "present_in_readback": None,
+                            "error_code": item.get("error_code"),
+                        }
+                    )
+            first_failure = failed_views[0]
+            response = {
+                "status": "partial_success" if successful_changes else "failed",
+                "error_code": "VIEW_APPLY_PARTIAL" if successful_changes else "VIEW_APPLY_FAILED",
+                "recoverable": True,
+                "message": "applied some view patches; at least one view failed" if successful_changes else "one or more view patches failed",
+                "normalized_args": normalized_args,
+                "missing_fields": [],
+                "allowed_values": {"view_types": [member.value for member in PublicViewType], "view.filter.operator": [member.value for member in ViewFilterOperator]},
+                "details": {"per_view_results": view_results},
+                "request_id": first_failure.get("request_id"),
+                "suggested_next_call": {"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
+                "backend_code": first_failure.get("backend_code"),
+                "http_status": first_failure.get("http_status"),
+                "noop": noop,
+                "verification": {
+                    "views_verified": verified,
+                    "views_read_unavailable": verified_views_unavailable,
+                    "by_view": verification_by_view,
+                },
+                "app_key": app_key,
+                "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": failed_views},
+                "verified": verified,
+            }
+            return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
         response = {
             "status": "success" if verified else "partial_success",
             "error_code": None if not verified_views_unavailable else "VIEWS_READBACK_PENDING",
@@ -2413,9 +2550,9 @@ class AiBuilderFacade:
             "request_id": None,
             "suggested_next_call": None if not verified_views_unavailable else {"tool_name": "app_read_views_summary", "arguments": {"profile": profile, "app_key": app_key}},
             "noop": noop,
-            "verification": {"views_verified": verified, "views_read_unavailable": verified_views_unavailable},
+            "verification": {"views_verified": verified, "views_read_unavailable": verified_views_unavailable, "by_view": view_results},
             "app_key": app_key,
-            "views_diff": {"created": created, "updated": updated, "removed": removed},
+            "views_diff": {"created": created, "updated": updated, "removed": removed, "failed": []},
             "verified": verified,
         }
         return self._append_publish_result(profile=profile, app_key=app_key, publish=publish, response=response)
@@ -3694,13 +3831,20 @@ def _summarize_views(result: Any) -> list[dict[str, Any]]:
     for view in result:
         if not isinstance(view, dict):
             continue
+        name = view.get("viewgraphName") or view.get("viewName") or view.get("title")
+        view_key = view.get("viewgraphKey") or view.get("viewKey")
+        view_type = _normalize_view_type_name(view.get("viewgraphType") or view.get("type"))
+        columns = view.get("columnNames") or view.get("columns") or []
+        group_by = view.get("groupBy") or view.get("group_by")
+        if not any((name, view_key, view_type, columns, group_by)):
+            continue
         items.append(
             {
-                "name": view.get("viewgraphName") or view.get("viewName") or view.get("title"),
-                "view_key": view.get("viewgraphKey") or view.get("viewKey"),
-                "type": view.get("viewgraphType") or view.get("type"),
-                "column_names": view.get("columnNames") or view.get("columns") or [],
-                "group_by": view.get("groupBy") or view.get("group_by"),
+                "name": name,
+                "view_key": view_key,
+                "type": view_type,
+                "columns": columns,
+                "group_by": group_by,
             }
         )
     return items
@@ -4080,6 +4224,8 @@ def _pick_view_template_key(existing_views: list[dict[str, Any]], *, desired_typ
 
 def _normalize_view_type_name(value: Any) -> str:
     normalized = str(value or "").strip().lower()
+    if not normalized:
+        return ""
     if "gantt" in normalized:
         return "gantt"
     if "board" in normalized:

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -1319,6 +1319,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "node.type": [member.value for member in PublicFlowNodeType],
             "node.condition.operator": [member.value for member in FlowConditionOperator],
         },
+        "dependency_hints": [
+            "approval-style workflows require an explicit status field",
+            "approve/fill/copy nodes require at least one assignee",
+        ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -1396,6 +1400,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "node.type": [member.value for member in PublicFlowNodeType],
             "node.condition.operator": [member.value for member in FlowConditionOperator],
         },
+        "dependency_hints": [
+            "approval-style workflows require an explicit status field",
+            "approve/fill/copy nodes require at least one assignee",
+        ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",
@@ -1516,6 +1524,10 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "view.type": [member.value for member in PublicViewType],
             "view.filter.operator": [member.value for member in ViewFilterOperator],
         },
+        "execution_notes": [
+            "apply may return partial_success when some views land and others fail",
+            "read back app_read_views_summary after any failed or partial view apply",
+        ],
         "minimal_example": {
             "profile": "default",
             "app_key": "APP_KEY",