@josephyan/qingflow-cli 1.0.11 → 1.1.2

package/src/qingflow_mcp/response_trim.py

@@ -57,6 +57,13 @@ def trim_public_response(tool_name: str | None, payload: dict[str, Any]) -> dict
     if not isinstance(payload, 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",
+        }:
+            return trim_success_response(tool_name, payload)
         return _trim_returned_failure(payload)
     return trim_success_response(tool_name, payload)
 
@@ -66,8 +73,10 @@ def trim_success_response(tool_name: str | None, payload: dict[str, Any]) -> dic
         return payload
     trimmed = deepcopy(payload)
     drop_keys = COMMON_SUCCESS_DROP_TOP
-    if tool_name == "user:record_get":
+    if tool_name in {"user:record_get", "user:record_logs_get"}:
         drop_keys = COMMON_SUCCESS_DROP_TOP - {"output_profile"}
+    if tool_name in {"user:record_insert", "user:record_update", "user:record_delete"} and payload.get("ok") is False:
+        drop_keys = drop_keys - {"ok"}
     _drop_top_keys(trimmed, drop_keys)
     transformer = SUCCESS_POLICY_BY_TOOL.get(tool_name or "")
     if transformer is not None:
@@ -84,7 +93,12 @@ def trim_error_response(payload: dict[str, Any]) -> dict[str, Any]:
     _drop_deep_keys(trimmed.get("details"), {"request_route", "base_url", "normalized_args", "suggested_next_call", "transport", "response", "body", "raw"})
     details = trimmed.get("details")
     if isinstance(details, dict):
+        preserved = {}
+        for key in ("blocking_issues", "compiled_match_rules"):
+            if key in details:
+                preserved[key] = details.get(key)
         compact_details = _compact_scalar_dict(details)
+        compact_details.update(preserved)
         if compact_details:
             trimmed["details"] = compact_details
         else:
@@ -140,7 +154,7 @@ def _looks_like_failure_payload(payload: dict[str, Any]) -> bool:
     if payload.get("ok") is False:
         return True
     status = str(payload.get("status") or "").lower()
-    return status in {"failed", "blocked", "verification_failed"}
+    return status in {"failed", "blocked"}
 
 
 def _trim_returned_failure(payload: dict[str, Any]) -> dict[str, Any]:
@@ -149,7 +163,12 @@ def _trim_returned_failure(payload: dict[str, Any]) -> dict[str, Any]:
     _drop_deep_keys(trimmed.get("details"), {"request_route", "base_url", "normalized_args", "suggested_next_call", "transport", "response", "body", "raw"})
     details = trimmed.get("details")
     if isinstance(details, dict):
+        preserved = {}
+        for key in ("blocking_issues", "compiled_match_rules"):
+            if key in details:
+                preserved[key] = details.get(key)
         compact_details = _compact_scalar_dict(details)
+        compact_details.update(preserved)
         if compact_details:
             trimmed["details"] = compact_details
         else:
@@ -275,7 +294,7 @@ def _trim_workspace_get(payload: JSONObject) -> None:
         )
 
 
-def _trim_app_search_like(payload: JSONObject) -> None:
+def _trim_app_list_like(payload: JSONObject) -> None:
     payload.pop("apps", None)
     _trim_item_list(payload, "items", allowed=("app_key", "app_name", "package_name"))
 
@@ -368,10 +387,17 @@ def _trim_record_write(payload: JSONObject) -> None:
     data = payload.get("data")
     if not isinstance(data, dict):
         return
+    if payload.get("mode") == "batch" or data.get("mode") == "batch":
+        _trim_record_write_batch(payload, data)
+        return
     data.pop("debug", 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
     resource = _compact_record_resource(data.get("resource"))
     if resource:
         data["resource"] = resource
@@ -397,6 +423,44 @@ def _trim_record_write(payload: JSONObject) -> None:
             data.pop(key, None)
 
 
+def _trim_record_write_batch(payload: JSONObject, data: JSONObject) -> None:
+    data.pop("items", None)
+    data.pop("debug", None)
+    for key in ("summary", "app_key", "mode"):
+        if data.get(key) in (None, [], {}, ""):
+            data.pop(key, None)
+    items = payload.get("items")
+    if isinstance(items, list):
+        payload["items"] = [
+            _pick(
+                item,
+                (
+                    "index",
+                    "row_number",
+                    "status",
+                    "record_id",
+                    "apply_id",
+                    "write_executed",
+                    "verification_status",
+                    "safe_to_retry",
+                    "update_route",
+                    "tried_routes",
+                    "failed_fields",
+                    "confirmation_requests",
+                    "blockers",
+                    "error",
+                    "warnings",
+                    "resource",
+                    "verification",
+                ),
+            )
+            for item in items
+            if isinstance(item, dict)
+        ]
+    if payload.get("items") in (None, [], {}, ""):
+        payload.pop("items", None)
+
+
 def _trim_record_get(payload: JSONObject) -> None:
     if payload.get("fields") is not None or payload.get("semantic_context") is not None:
         _trim_detail_context_record_get(payload)
@@ -538,7 +602,7 @@ def _trim_detail_context_record_get(payload: JSONObject) -> None:
     associated_resources = payload.get("associated_resources")
     if isinstance(associated_resources, list):
         payload["associated_resources"] = [
-            _pick(item, ("type", "name", "app_key", "app_name", "view_key", "chart_key", "view_type", "data_access"))
+            _pick(item, ("type", "resource_type", "name", "app_key", "app_name", "view_key", "chart_key", "view_type", "report_source", "data_access"))
             for item in associated_resources
             if isinstance(item, dict)
         ]
@@ -610,6 +674,49 @@ def _trim_record_access(payload: JSONObject) -> None:
     payload.update(compact)
 
 
+def _trim_record_logs(payload: JSONObject) -> None:
+    compact: dict[str, Any] = {}
+    for key in (
+        "ok",
+        "status",
+        "output_profile",
+        "app",
+        "view",
+        "record",
+        "local_dir",
+        "summary_path",
+        "warnings",
+        "unavailable_context",
+        "context_integrity",
+    ):
+        value = payload.get(key)
+        if value is not None:
+            compact[key] = value
+    for key in ("data_logs", "workflow_logs"):
+        node = payload.get(key)
+        if isinstance(node, dict):
+            compact[key] = _pick(
+                node,
+                (
+                    "status",
+                    "visible",
+                    "source",
+                    "reason",
+                    "complete",
+                    "items_count",
+                    "pages_fetched",
+                    "page_size",
+                    "reported_total",
+                    "local_path",
+                    "preview_items",
+                    "warnings",
+                    "stopped_reason",
+                ),
+            )
+    payload.clear()
+    payload.update(compact)
+
+
 def _trim_record_analyze(payload: JSONObject) -> None:
     summary: dict[str, Any] = {}
     completeness = payload.get("completeness")
@@ -656,13 +763,18 @@ def _trim_record_delete(payload: JSONObject) -> None:
     if not isinstance(data, dict):
         return
     resource = data.get("resource")
-    deleted_ids: list[str] = []
-    if isinstance(resource, dict):
+    deleted_ids = payload.get("deleted_ids") if isinstance(payload.get("deleted_ids"), list) else data.get("deleted_ids")
+    failed_ids = payload.get("failed_ids") if isinstance(payload.get("failed_ids"), list) else data.get("failed_ids")
+    if not isinstance(deleted_ids, list):
+        deleted_ids = []
+    if not isinstance(failed_ids, list):
+        failed_ids = []
+    if not deleted_ids and isinstance(resource, dict):
         raw_ids = resource.get("record_ids") or resource.get("apply_ids") or resource.get("applyIds")
         if isinstance(raw_ids, list):
             deleted_ids = [str(item) for item in raw_ids if item not in (None, "")]
-    data["deleted_ids"] = deleted_ids
-    data.setdefault("failed_ids", [])
+    data["deleted_ids"] = [str(item) for item in deleted_ids if item not in (None, "")]
+    data["failed_ids"] = [str(item) for item in failed_ids if item not in (None, "")]
     for key in (
         "resource",
         "action",
@@ -730,6 +842,19 @@ def _compact_schema_field(item: Any, *, template_map: dict[str, Any] | None) ->
         compact["required"] = bool(item.get("required"))
     if template_map is not None and isinstance(title, str) and title in template_map:
         compact["template"] = template_map.get(title)
+    for key in (
+        "format_hint",
+        "example_value",
+        "linkage",
+        "may_become_required",
+        "activation_sources",
+        "requirement_reason",
+        "accepts_natural_input",
+        "requires_upload",
+    ):
+        value = item.get(key)
+        if value not in (None, [], {}, ""):
+            compact[key] = value
     candidate_hint = item.get("candidate_hint")
     if isinstance(candidate_hint, dict):
         compact["candidate_hint"] = candidate_hint
@@ -883,7 +1008,11 @@ def _trim_builder_envelope(payload: JSONObject) -> None:
         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"})
+            preserved = {}
+            if isinstance(details.get("compiled_match_rules"), dict):
+                preserved["compiled_match_rules"] = details.get("compiled_match_rules")
             compact = _compact_scalar_dict(details)
+            compact.update(preserved)
             if compact:
                 payload["details"] = compact
             else:
@@ -904,7 +1033,7 @@ _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("auth_use_credential", "auth_wh
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("auth_logout",), _trim_auth_logout)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("workspace_list",), _trim_workspace_list)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("workspace_get", "workspace_select"), _trim_workspace_get)
-_register_policy((USER_DOMAIN,), ("app_list", "app_search"), _trim_app_search_like)
+_register_policy((USER_DOMAIN,), ("app_list",), _trim_app_list_like)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("app_get",), _trim_app_get)
 _register_policy((BUILDER_DOMAIN,), ("app_repair_code_blocks",), _trim_builder_list_like)
 _register_policy((USER_DOMAIN, BUILDER_DOMAIN), ("portal_list", "portal_get", "view_get", "chart_get"), _trim_builder_list_like)
@@ -947,6 +1076,7 @@ _register_policy((USER_DOMAIN,), ("record_insert", "record_update"), _trim_recor
 _register_policy((USER_DOMAIN,), ("record_get",), _trim_record_get)
 _register_policy((USER_DOMAIN,), ("record_list",), _trim_record_list)
 _register_policy((USER_DOMAIN,), ("record_access",), _trim_record_access)
+_register_policy((USER_DOMAIN,), ("record_logs_get",), _trim_record_logs)
 _register_policy((USER_DOMAIN,), ("record_analyze",), _trim_record_analyze)
 _register_policy((USER_DOMAIN,), ("record_code_block_run",), _trim_code_block_run)
 _register_policy((USER_DOMAIN,), ("task_list",), _trim_task_list)
@@ -987,6 +1117,8 @@ _register_policy(
     (BUILDER_DOMAIN,),
     (
         "builder_tool_contract",
+        "workspace_icon_catalog_get",
+        "package_list",
         "package_get",
         "package_apply",
         "solution_install",
@@ -996,11 +1128,8 @@ _register_policy(
         "app_release_edit_lock_if_mine",
         "app_resolve",
         "button_style_catalog_get",
-        "app_custom_button_list",
-        "app_custom_button_get",
-        "app_custom_button_create",
-        "app_custom_button_update",
-        "app_custom_button_delete",
+        "app_custom_buttons_apply",
+        "app_associated_resources_apply",
         "app_get_fields",
         "app_repair_code_blocks",
         "app_get_layout",

package/src/qingflow_mcp/server.py

@@ -48,7 +48,7 @@ All resource tools operate with the logged-in user's Qingflow permissions.
 
 ## App Discovery
 
-If `app_key` is unknown, use `app_list` or `app_search` first.
+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`.
 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.
@@ -56,9 +56,9 @@ If an accessible view has `analysis_supported=false`, do not use it for `record_
 ## Schema-First Rule
 
 Call `record_insert_schema_get` before `record_insert`.
-Call `record_update_schema_get` before `record_update`.
+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`.
-Call `app_get` first when the data range is unclear, then use `record_browse_schema_get(view_id=...)` before `record_access`, `record_list`, or `record_get`.
+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.
 
 - All `field_id` values must come from the schema response.
@@ -67,7 +67,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 across matched accessible views; read `writable_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_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.
@@ -103,9 +103,9 @@ Analysis answers must include concrete numbers. When applicable, include percent
 
 ## Record CRUD Path
 
-`app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get`
-`record_insert_schema_get -> record_insert`
-`record_update_schema_get -> record_update`
+`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`
 
@@ -115,22 +115,25 @@ Analysis answers must include concrete numbers. When applicable, include percent
 - Use `order_by` items as `{{field_id, direction}}`
 - 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` uses an applicant-node `fields` map keyed by field title.
-- `record_update` uses a field-title keyed `fields` map and internally selects the first accessible view that can execute the current payload.
+- `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.
 - 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 for the record, but not every field combination is guaranteed; `record_update` still needs one single matched accessible view that can cover the payload.
+- `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_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.
 - `record_get.columns` are focus hints only; they do not project the detail fields. Read facts from top-level `fields[]`.
 - When readback shape matters after insert or update, prefer `record_get` for human/detail-page context, or `record_list(..., output_profile="normalized")` for batch-shaped normalized rows.
 
 - Read relation targets from `record_insert_schema_get` / `record_update_schema_get` relation metadata before preparing relation writes.
-- Member and department fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to `record_member_candidates` or `record_department_candidates` when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- Member, department, and relation fields may be written with natural strings directly on `record_insert` / `record_update`; only fall back to candidate tools when the user wants explicit candidate browsing or the write returns ambiguity that needs confirmation.
+- CLI-only agents can use `qingflow record member-candidates --app-key APP_KEY --field-id FIELD_ID --keyword NAME --json` or `qingflow record department-candidates --app-key APP_KEY --field-id FIELD_ID --keyword DEPT --json` for that fallback; pass `--record-id`, `--workflow-node-id`, and `--fields-file` only when the candidate scope must match an existing runtime context.
+- For batch insert `partial_success`, read `created_record_ids`, failed `items[].row_number`, and `failed_fields`; repair only failed rows and never retry the whole batch after any row has `write_executed=true`.
 - If explicit candidate browsing is needed for default-all member or department fields, prefer those field candidate tools instead of starting with `directory_*`.
 
 ## Code Block Path
@@ -183,7 +186,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 full workflow log history.
+- 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?)`.
 - Task actions operate on `app_key + record_id + workflow_node_id`, not `task_id`.
 
 ## Time Handling

package/src/qingflow_mcp/server_app_builder.py

@@ -35,13 +35,23 @@ def build_builder_server() -> FastMCP:
             "Follow the resource path resolve -> summary read -> apply -> publish_verify. "
             "Use builder_tool_contract when you need a machine-readable contract, aliases, allowed enums, or a minimal valid example for a public builder tool. "
             "Use solution_install when the user explicitly wants to install a packaged solution/template by solution_key, optionally copying bundled demo data. "
-            "If creating or updating an app package may be appropriate, use package_apply with explicit user intent; otherwise use package_get and app_resolve to locate resources, "
-            "app_get/app_get_fields/app_repair_code_blocks/app_get_layout/app_get_views/app_get_flow/app_get_charts/portal_list/portal_get/view_get/chart_get for configuration reads, "
+            "Use package_list to find visible app packages by keyword and package_get to read package detail before editing; if creating or updating an app package may be appropriate, use package_apply with explicit user intent; otherwise use app_resolve to locate app resources, "
+            "Use workspace_icon_catalog_get before creating app packages, apps, or portals when supported icon/color candidates are needed; new workspace resources require explicit non-template icon + color, and the CLI validates choices without inferring business defaults. "
+            "app_get as the default app map read, then app_get_fields/app_repair_code_blocks/app_get_layout/app_get_views/app_get_flow/app_flow_get/app_flow_get_schema/app_get_charts/portal_list/portal_get/view_get/chart_get for focused configuration reads, "
             "member_search/role_search/role_create when workflow assignees must come from the directory or role catalog, preferring roles over explicit members unless the user explicitly names members, "
-            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, publish=false only guarantees draft/base-info updates, and flow should use publish=false whenever you only want draft/precheck behavior. "
+            "then app_schema_apply/app_layout_apply/app_flow_apply/app_views_apply/app_custom_buttons_apply/app_associated_resources_apply/app_charts_apply/portal_apply to execute normalized patches; these apply tools perform planning, normalization, and dependency checks internally where applicable. Schema/layout/views noop requests skip publish, app_custom_buttons_apply and app_associated_resources_apply publish after at least one write succeeds and expose no draft-only parameter, charts are immediate-live without publish and resolve targets by chart_id first then exact unique chart name, portal updates use replace semantics only when sections are supplied and edit-mode base-info-only updates may omit sections, portal pc layout is a 24-column grid and mobile is a 6-column grid so omit position or use layout_preset when unsure, publish=false only guarantees draft/base-info updates for tools that still expose that parameter, and flow should use publish=false whenever you only want draft/precheck behavior. "
+            "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 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 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. "
             "For code_block fields with output bindings, always use qf_output assignment rather than const/let qf_output, and use app_repair_code_blocks when an existing form hangs because output-bound fields stay loading. "
             "Use package_apply to manage package metadata, visibility, grouping, and ordering, and app_publish_verify for explicit final publish verification. "
-            "For workflow edits, keep the public builder surface on stable linear flows only: start/approve/fill/copy/webhook/end. Branch and condition nodes are intentionally disabled because the backend workflow route is not front-end stable for those node types. Declare node assignees and editable fields explicitly. "
+            "For workflow edits, use app_flow_get_schema and app_flow_get (GET-first), author a complete WorkflowSpecDTO in spec, then app_flow_apply; CLI equivalent is qingflow builder flow schema|get|apply --spec-file. Do not use general-server legacy workflow config reads (auditNodes list/detail, global settings, qsource config reads); they are removed. "
             "If builder writes are blocked by the current user's own edit lock, use app_release_edit_lock_if_mine with the lock owner details from the failed result. "
             "Do not handcraft internal solution payloads or rely on build_id/stage/repair. "
             "If the current MCP capability is unsupported, the workflow is awkward, or the user's need still cannot be satisfied after reasonable use, first summarize the gap, ask whether to submit feedback, and call feedback_submit only after explicit user confirmation."
@@ -169,6 +179,14 @@ def build_builder_server() -> FastMCP:
     def builder_tool_contract(tool_name: str = "") -> dict:
         return ai_builder.builder_tool_contract(tool_name=tool_name)
 
+    @server.tool()
+    def workspace_icon_catalog_get(profile: str = DEFAULT_PROFILE) -> dict:
+        return ai_builder.workspace_icon_catalog_get(profile=profile)
+
+    @server.tool()
+    def package_list(profile: str = DEFAULT_PROFILE, trial_status: str = "all", query: str = "") -> dict:
+        return ai_builder.package_list(profile=profile, trial_status=trial_status, query=query)
+
     @server.tool()
     def package_get(profile: str = DEFAULT_PROFILE, package_id: int = 0) -> dict:
         return ai_builder.package_get(profile=profile, package_id=package_id)
@@ -295,29 +313,42 @@ def build_builder_server() -> FastMCP:
         return ai_builder.button_style_catalog_get(profile=profile)
 
     @server.tool()
-    def app_custom_button_list(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
-        return ai_builder.app_custom_button_list(profile=profile, app_key=app_key)
-
-    @server.tool()
-    def app_custom_button_get(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> dict:
-        return ai_builder.app_custom_button_get(profile=profile, app_key=app_key, button_id=button_id)
-
-    @server.tool()
-    def app_custom_button_create(profile: str = DEFAULT_PROFILE, app_key: str = "", payload: dict | None = None) -> dict:
-        return ai_builder.app_custom_button_create(profile=profile, app_key=app_key, payload=payload or {})
-
-    @server.tool()
-    def app_custom_button_update(
+    def app_custom_buttons_apply(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
-        button_id: int = 0,
-        payload: dict | None = None,
+        upsert_buttons: list[dict] | None = None,
+        patch_buttons: list[dict] | None = None,
+        remove_buttons: list[dict] | None = None,
+        view_configs: list[dict] | None = None,
     ) -> dict:
-        return ai_builder.app_custom_button_update(profile=profile, app_key=app_key, button_id=button_id, payload=payload or {})
+        return ai_builder.app_custom_buttons_apply(
+            profile=profile,
+            app_key=app_key,
+            upsert_buttons=upsert_buttons or [],
+            patch_buttons=patch_buttons or [],
+            remove_buttons=remove_buttons or [],
+            view_configs=view_configs or [],
+        )
 
     @server.tool()
-    def app_custom_button_delete(profile: str = DEFAULT_PROFILE, app_key: str = "", button_id: int = 0) -> dict:
-        return ai_builder.app_custom_button_delete(profile=profile, app_key=app_key, button_id=button_id)
+    def app_associated_resources_apply(
+        profile: str = DEFAULT_PROFILE,
+        app_key: str = "",
+        upsert_resources: list[dict] | None = None,
+        patch_resources: list[dict] | None = None,
+        remove_associated_item_ids: list[int] | None = None,
+        reorder_associated_item_ids: list[int] | None = None,
+        view_configs: list[dict] | None = None,
+    ) -> dict:
+        return ai_builder.app_associated_resources_apply(
+            profile=profile,
+            app_key=app_key,
+            upsert_resources=upsert_resources or [],
+            patch_resources=patch_resources or [],
+            remove_associated_item_ids=remove_associated_item_ids or [],
+            reorder_associated_item_ids=reorder_associated_item_ids or [],
+            view_configs=view_configs or [],
+        )
 
     @server.tool()
     def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict:
@@ -387,7 +418,30 @@ def build_builder_server() -> FastMCP:
         add_fields: list[dict] | None = None,
         update_fields: list[dict] | None = None,
         remove_fields: list[dict] | None = None,
+        apps: list[dict] | None = None,
     ) -> dict:
+        if apps:
+            if app_key or app_name or app_title or add_fields or update_fields or remove_fields:
+                return _config_failure(
+                    "app_schema_apply multi-app mode accepts package_id/create_if_missing plus apps only.",
+                    fix_hint="Use `apps` for batch mode, or use the single-app arguments without `apps`.",
+                )
+            if package_id is None:
+                return _config_failure(
+                    "app_schema_apply multi-app mode requires package_id.",
+                    fix_hint="Pass `package_id` and `apps[].app_name` for new apps, or `apps[].app_key` for existing apps.",
+                )
+            return ai_builder.app_schema_apply(
+                profile=profile,
+                package_id=package_id,
+                visibility=visibility,
+                create_if_missing=create_if_missing,
+                publish=publish,
+                add_fields=[],
+                update_fields=[],
+                remove_fields=[],
+                apps=apps,
+            )
         has_app_key = bool((app_key or "").strip())
         has_app_name = bool((app_name or "").strip())
         has_app_title = bool((app_title or "").strip())
@@ -417,6 +471,7 @@ def build_builder_server() -> FastMCP:
             add_fields=add_fields or [],
             update_fields=update_fields or [],
             remove_fields=remove_fields or [],
+            apps=[],
         )
 
     @server.tool()
@@ -429,22 +484,30 @@ def build_builder_server() -> FastMCP:
     ) -> dict:
         return ai_builder.app_layout_apply(profile=profile, app_key=app_key, mode=mode, publish=publish, sections=sections or [])
 
+    @server.tool()
+    def app_flow_get(profile: str = DEFAULT_PROFILE, app_key: str = "", version_id: str = "") -> dict:
+        return ai_builder.app_get_flow(profile=profile, app_key=app_key, version_id=version_id or None)
+
+    @server.tool()
+    def app_flow_get_schema(profile: str = DEFAULT_PROFILE, schema_version: str = "") -> dict:
+        return ai_builder.app_flow_get_schema(profile=profile, schema_version=schema_version or None)
+
     @server.tool()
     def app_flow_apply(
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
-        mode: str = "replace",
         publish: bool = True,
-        nodes: list[dict] | None = None,
-        transitions: list[dict] | None = None,
+        spec: dict | None = None,
+        idempotency_key: str = "",
+        schema_version: str = "",
     ) -> dict:
         return ai_builder.app_flow_apply(
             profile=profile,
             app_key=app_key,
-            mode=mode,
             publish=publish,
-            nodes=nodes or [],
-            transitions=transitions or [],
+            spec=spec or {},
+            idempotency_key=idempotency_key or None,
+            schema_version=schema_version or None,
         )
 
     @server.tool()
@@ -453,6 +516,7 @@ def build_builder_server() -> FastMCP:
         app_key: str = "",
         publish: bool = True,
         upsert_views: list[dict] | None = None,
+        patch_views: list[dict] | None = None,
         remove_views: list[str] | None = None,
     ) -> dict:
         return ai_builder.app_views_apply(
@@ -460,6 +524,7 @@ def build_builder_server() -> FastMCP:
             app_key=app_key,
             publish=publish,
             upsert_views=upsert_views or [],
+            patch_views=patch_views or [],
             remove_views=remove_views or [],
         )
 
@@ -468,6 +533,7 @@ def build_builder_server() -> FastMCP:
         profile: str = DEFAULT_PROFILE,
         app_key: str = "",
         upsert_charts: list[dict] | None = None,
+        patch_charts: list[dict] | None = None,
         remove_chart_ids: list[str] | None = None,
         reorder_chart_ids: list[str] | None = None,
     ) -> dict:
@@ -475,6 +541,7 @@ def build_builder_server() -> FastMCP:
             profile=profile,
             app_key=app_key,
             upsert_charts=upsert_charts or [],
+            patch_charts=patch_charts or [],
             remove_chart_ids=remove_chart_ids or [],
             reorder_chart_ids=reorder_chart_ids or [],
         )
@@ -484,9 +551,12 @@ def build_builder_server() -> FastMCP:
         profile: str = DEFAULT_PROFILE,
         dash_key: str = "",
         dash_name: str = "",
+        name: str = "",
         package_id: int | None = None,
         publish: bool = True,
         sections: list[dict] | None = None,
+        pages: list[dict] | None = None,
+        layout_preset: str = "",
         visibility: dict | None = None,
         auth: dict | None = None,
         icon: str | None = None,
@@ -494,10 +564,14 @@ def build_builder_server() -> FastMCP:
         hide_copyright: bool | None = None,
         dash_global_config: dict | None = None,
         config: dict | None = None,
+        payload: dict | None = None,
     ) -> dict:
+        payload = payload if isinstance(payload, dict) else {}
         has_dash_key = bool((dash_key or "").strip())
-        has_dash_name = bool((dash_name or "").strip())
-        has_package_id = package_id is not None
+        effective_dash_name = (dash_name or name or str(payload.get("dash_name") or payload.get("dashName") or payload.get("name") or "")).strip()
+        has_dash_name = bool(effective_dash_name)
+        effective_package_id = package_id if package_id is not None else payload.get("package_id") or payload.get("packageId") or payload.get("package_tag_id")
+        has_package_id = effective_package_id is not None
         if has_dash_key and has_package_id:
             return _config_failure(
                 "portal_apply accepts exactly one selector mode.",
@@ -512,9 +586,12 @@ def build_builder_server() -> FastMCP:
             profile=profile,
             dash_key=dash_key,
             dash_name=dash_name,
+            name=name,
             package_id=package_id,
             publish=publish,
             sections=sections or [],
+            pages=pages or [],
+            layout_preset=layout_preset,
             visibility=visibility,
             auth=auth,
             icon=icon,
@@ -522,6 +599,7 @@ def build_builder_server() -> FastMCP:
             hide_copyright=hide_copyright,
             dash_global_config=dash_global_config,
             config=config or {},
+            payload=payload,
         )
 
     @server.tool()