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

package/src/qingflow_mcp/cli/commands/app.py

@@ -13,30 +13,17 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     app_subparsers = parser.add_subparsers(dest="app_command", required=True)
 
     list_parser = app_subparsers.add_parser("list", help="列出可见应用")
+    list_parser.add_argument("--query", default="", help="按关键词在可见应用列表中本地过滤")
+    list_parser.add_argument("--keyword", default="", help="兼容别名；建议使用 --query")
     list_parser.set_defaults(handler=_handle_list, format_hint="app_list")
 
-    search = app_subparsers.add_parser("search", help="搜索应用")
-    search.add_argument("--keyword", default="")
-    search.add_argument("--page", type=int, default=1)
-    search.add_argument("--page-size", type=int, default=50)
-    search.set_defaults(handler=_handle_search, format_hint="app_search")
-
     get = app_subparsers.add_parser("get", help="读取应用可访问视图与导入能力")
     get.add_argument("--app-key", help="不传时在交互终端中选择应用")
     get.set_defaults(handler=_handle_get, format_hint="app_get")
 
 
 def _handle_list(args: argparse.Namespace, context: CliContext) -> dict:
-    return context.app.app_list(profile=args.profile)
-
-
-def _handle_search(args: argparse.Namespace, context: CliContext) -> dict:
-    return context.app.app_search(
-        profile=args.profile,
-        keyword=args.keyword,
-        page_num=args.page,
-        page_size=args.page_size,
-    )
+    return context.app.app_list(profile=args.profile, query=args.query, keyword=args.keyword)
 
 
 def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:

package/src/qingflow_mcp/cli/commands/builder.py

@@ -42,6 +42,11 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     contract.add_argument("--tool-name", required=True)
     contract.set_defaults(handler=_handle_contract, format_hint="builder_summary")
 
+    icon = builder_subparsers.add_parser("icon", help="工作区图标目录")
+    icon_subparsers = icon.add_subparsers(dest="builder_icon_command", required=True)
+    icon_catalog = icon_subparsers.add_parser("catalog", help="读取应用、应用包、门户可用图标目录")
+    icon_catalog.set_defaults(handler=_handle_icon_catalog, format_hint="builder_summary")
+
     member = builder_subparsers.add_parser("member", help="成员目录")
     member_subparsers = member.add_subparsers(dest="builder_member_command", required=True)
     member_search = member_subparsers.add_parser("search", help="搜索成员")
@@ -78,6 +83,11 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     solution_install.add_argument("--solution-source", default="solutionDetail")
     solution_install.set_defaults(handler=_handle_solution_install, format_hint="builder_summary")
 
+    package_list = package_subparsers.add_parser("list", help="列出应用包")
+    package_list.add_argument("--trial-status", default="all")
+    package_list.add_argument("--query", default="")
+    package_list.set_defaults(handler=_handle_package_list, format_hint="builder_summary")
+
     package_get = package_subparsers.add_parser("get", help="读取应用包详情")
     package_get.add_argument("--package-id", type=int, required=True)
     package_get.set_defaults(handler=_handle_package_get, format_hint="builder_summary")
@@ -157,7 +167,9 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     portal_apply.add_argument("--dash-name", default="")
     portal_apply.add_argument("--package-id", type=int)
     portal_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
+    portal_apply.add_argument("--payload-file")
     portal_apply.add_argument("--sections-file")
+    portal_apply.add_argument("--layout-preset", default="")
     portal_apply.add_argument("--visibility-file")
     portal_apply.add_argument("--auth-file")
     portal_apply.add_argument("--icon")
@@ -277,6 +289,10 @@ def _handle_contract(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.builder_tool_contract(tool_name=args.tool_name)
 
 
+def _handle_icon_catalog(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.workspace_icon_catalog_get(profile=args.profile)
+
+
 def _handle_member_search(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.member_search(
         profile=args.profile,
@@ -320,6 +336,10 @@ def _handle_package_get(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.package_get(profile=args.profile, package_id=args.package_id)
 
 
+def _handle_package_list(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.builder.package_list(profile=args.profile, trial_status=args.trial_status, query=args.query)
+
+
 def _handle_package_apply(args: argparse.Namespace, context: CliContext) -> dict:
     config = load_object_arg(args.config_file, option_name="--config-file")
     if not isinstance(config, dict):
@@ -557,9 +577,13 @@ def _handle_charts_apply(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
+    payload = load_object_arg(args.payload_file, option_name="--payload-file") if getattr(args, "payload_file", None) else None
+    payload_obj = payload if isinstance(payload, dict) else {}
+    effective_dash_name = (args.dash_name or str(payload_obj.get("dash_name") or payload_obj.get("dashName") or payload_obj.get("name") or "")).strip()
+    effective_package_id = args.package_id if args.package_id is not None else payload_obj.get("package_id") or payload_obj.get("packageId") or payload_obj.get("package_tag_id")
     has_dash_key = bool((args.dash_key or "").strip())
-    has_dash_name = bool((args.dash_name or "").strip())
-    has_package_id = args.package_id is not None
+    has_dash_name = bool(effective_dash_name)
+    has_package_id = effective_package_id is not None
     if has_dash_key and has_package_id:
         raise_config_error(
             "portal apply accepts exactly one selector mode.",
@@ -578,6 +602,7 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
         package_id=args.package_id,
         publish=bool(args.publish),
         sections=sections,
+        layout_preset=args.layout_preset,
         visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
         auth=load_object_arg(args.auth_file, option_name="--auth-file"),
         icon=args.icon,
@@ -585,6 +610,7 @@ def _handle_portal_apply(args: argparse.Namespace, context: CliContext) -> dict:
         hide_copyright=args.hide_copyright,
         dash_global_config=load_object_arg(args.dash_global_config_file, option_name="--dash-global-config-file"),
         config=load_object_arg(args.config_file, option_name="--config-file"),
+        payload=payload,
     )
 
 

package/src/qingflow_mcp/cli/commands/record.py

@@ -13,7 +13,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     record_subparsers = parser.add_subparsers(
         dest="record_command",
         required=True,
-        metavar="{schema,list,access,get,insert,update,delete,member-candidates,department-candidates,code-block-run}",
+        metavar="{schema,list,access,get,logs,insert,update,delete,member-candidates,department-candidates,code-block-run}",
     )
 
     schema = record_subparsers.add_parser("schema", help="读取记录相关表结构")
@@ -102,6 +102,12 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     get.add_argument("--view-id")
     get.set_defaults(handler=_handle_get, format_hint="record_get")
 
+    logs = record_subparsers.add_parser("logs", help="读取单条记录全量日志并写入本地 JSONL")
+    logs.add_argument("--app-key", required=True)
+    logs.add_argument("--record-id", required=True)
+    logs.add_argument("--view-id")
+    logs.set_defaults(handler=_handle_logs, format_hint="record_logs")
+
     insert = record_subparsers.add_parser("insert", help="新增记录")
     insert.add_argument("--app-key", required=True)
     insert.add_argument("--fields-file", help=argparse.SUPPRESS)
@@ -328,6 +334,15 @@ def _handle_get(args: argparse.Namespace, context: CliContext) -> dict:
     )
 
 
+def _handle_logs(args: argparse.Namespace, context: CliContext) -> dict:
+    return context.record.record_logs_get(
+        profile=args.profile,
+        app_key=args.app_key,
+        record_id=args.record_id,
+        view_id=args.view_id,
+    )
+
+
 def _handle_insert(args: argparse.Namespace, context: CliContext) -> dict:
     if args.items_file:
         if args.fields_file:

package/src/qingflow_mcp/cli/formatters.py

@@ -292,6 +292,37 @@ def _format_record_get(result: dict[str, Any]) -> str:
     return "\n".join(lines) + "\n"
 
 
+def _format_record_logs(result: dict[str, Any]) -> str:
+    app = result.get("app") if isinstance(result.get("app"), dict) else {}
+    view = result.get("view") if isinstance(result.get("view"), dict) else {}
+    record = result.get("record") if isinstance(result.get("record"), dict) else {}
+    data_logs = result.get("data_logs") if isinstance(result.get("data_logs"), dict) else {}
+    workflow_logs = result.get("workflow_logs") if isinstance(result.get("workflow_logs"), dict) else {}
+    integrity = result.get("context_integrity") if isinstance(result.get("context_integrity"), dict) else {}
+    lines = [
+        f"Status: {result.get('status') or '-'}",
+        f"App: {app.get('app_name') or app.get('app_key') or '-'} ({app.get('app_key') or '-'})",
+        f"View: {view.get('name') or view.get('view_id') or '-'}",
+        f"Record: {record.get('title') or '-'} ({record.get('record_id') or '-'})",
+        f"Data logs: {data_logs.get('status') or '-'} / count={data_logs.get('items_count')} / pages={data_logs.get('pages_fetched')} / complete={data_logs.get('complete')}",
+        f"Workflow logs: {workflow_logs.get('status') or '-'} / count={workflow_logs.get('items_count')} / pages={workflow_logs.get('pages_fetched')} / complete={workflow_logs.get('complete')}",
+        f"Safe for full log conclusion: {integrity.get('safe_for_full_log_conclusion')}",
+    ]
+    if result.get("local_dir"):
+        lines.append(f"Local dir: {result.get('local_dir')}")
+    if data_logs.get("local_path"):
+        lines.append(f"Data logs file: {data_logs.get('local_path')}")
+    if workflow_logs.get("local_path"):
+        lines.append(f"Workflow logs file: {workflow_logs.get('local_path')}")
+    if result.get("summary_path"):
+        lines.append(f"Summary file: {result.get('summary_path')}")
+    _append_warnings(lines, result.get("warnings"))
+    unavailable = result.get("unavailable_context") if isinstance(result.get("unavailable_context"), list) else []
+    if unavailable:
+        lines.append(f"Unavailable contexts: {len(unavailable)}")
+    return "\n".join(lines) + "\n"
+
+
 def _format_task_list(result: dict[str, Any]) -> str:
     data = result.get("data") if isinstance(result.get("data"), dict) else {}
     items = data.get("items") if isinstance(data.get("items"), list) else []
@@ -788,11 +819,11 @@ _FORMATTERS = {
     "workspace_get": _format_workspace_get,
     "workspace_select": _format_workspace_select,
     "app_list": _format_app_items,
-    "app_search": _format_app_items,
     "app_get": _format_app_get,
     "record_list": _format_record_list,
     "record_access": _format_record_access,
     "record_get": _format_record_get,
+    "record_logs": _format_record_logs,
     "task_list": _format_task_list,
     "task_workbench": _format_task_workbench,
     "task_get": _format_task_get,

package/src/qingflow_mcp/public_surface.py

@@ -38,7 +38,6 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "workspace_get", ("workspace_get",), ("workspace", "get")),
     PublicToolSpec(USER_DOMAIN, "workspace_select", ("workspace_select",), ("workspace", "select")),
     PublicToolSpec(USER_DOMAIN, "app_list", ("app_list",), ("app", "list"), cli_show_effective_context=True),
-    PublicToolSpec(USER_DOMAIN, "app_search", ("app_search",), ("app", "search"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "app_get", ("app_get",), ("app", "get"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "portal_list", ("portal_list",), ("portal", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "portal_get", ("portal_get",), ("portal", "get"), cli_show_effective_context=True),
@@ -84,6 +83,7 @@ USER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(USER_DOMAIN, "record_list", ("record_list",), ("record", "list"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_access", ("record_access",), ("record", "access"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_get", ("record_get_public",), ("record", "get"), cli_show_effective_context=True),
+    PublicToolSpec(USER_DOMAIN, "record_logs_get", ("record_logs_get",), ("record", "logs"), cli_show_effective_context=True),
     PublicToolSpec(USER_DOMAIN, "record_insert", ("record_insert_public",), ("record", "insert"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(USER_DOMAIN, "record_update", ("record_update_public",), ("record", "update"), cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(USER_DOMAIN, "record_delete", ("record_delete_public",), ("record", "delete"), cli_show_effective_context=True, cli_context_write=True),
@@ -127,6 +127,8 @@ BUILDER_PUBLIC_TOOL_SPECS: tuple[PublicToolSpec, ...] = (
     PublicToolSpec(BUILDER_DOMAIN, "file_upload_local", ("file_upload_local",), ("builder", "file", "upload-local"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "feedback_submit", ("feedback_submit",), ("builder", "feedback", "submit"), has_contract=True),
     PublicToolSpec(BUILDER_DOMAIN, "builder_tool_contract", ("builder_tool_contract",), ("builder", "contract"), has_contract=False),
+    PublicToolSpec(BUILDER_DOMAIN, "workspace_icon_catalog_get", ("workspace_icon_catalog_get",), ("builder", "icon", "catalog"), has_contract=True, cli_show_effective_context=True),
+    PublicToolSpec(BUILDER_DOMAIN, "package_list", ("package_list",), ("builder", "package", "list"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "package_get", ("package_get",), ("builder", "package", "get"), has_contract=True, cli_show_effective_context=True),
     PublicToolSpec(BUILDER_DOMAIN, "package_apply", ("package_apply",), ("builder", "package", "apply"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),
     PublicToolSpec(BUILDER_DOMAIN, "solution_install", ("solution_install",), ("builder", "solution", "install"), has_contract=True, cli_show_effective_context=True, cli_context_write=True),

package/src/qingflow_mcp/response_trim.py

@@ -73,7 +73,7 @@ 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"}
@@ -294,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"))
 
@@ -394,6 +394,10 @@ def _trim_record_write(payload: JSONObject) -> None:
     data.pop("normalized_payload", None)
     data.pop("human_review", None)
     data.pop("action", None)
+    for key in ("update_route", "tried_routes"):
+        value = payload.get(key)
+        if value not in (None, [], {}, ""):
+            data[key] = value
     resource = _compact_record_resource(data.get("resource"))
     if resource:
         data["resource"] = resource
@@ -439,6 +443,8 @@ def _trim_record_write_batch(payload: JSONObject, data: JSONObject) -> None:
                     "write_executed",
                     "verification_status",
                     "safe_to_retry",
+                    "update_route",
+                    "tried_routes",
                     "failed_fields",
                     "confirmation_requests",
                     "blockers",
@@ -668,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")
@@ -984,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)
@@ -1027,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)
@@ -1067,6 +1117,8 @@ _register_policy(
     (BUILDER_DOMAIN,),
     (
         "builder_tool_contract",
+        "workspace_icon_catalog_get",
+        "package_list",
         "package_get",
         "package_apply",
         "solution_install",

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`
+`app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get / record_logs_get`
 `record_insert_schema_get -> record_insert(items)`
-`record_update_schema_get -> record_update`
+`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`
 
@@ -116,15 +116,16 @@ 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 and internally selects the first accessible view that can execute the current payload.
+- `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.
@@ -185,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,16 +35,18 @@ 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, "
+            "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_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_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, 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. "
+            "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; 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 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. "
@@ -177,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)
@@ -533,9 +543,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,
@@ -543,10 +556,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.",
@@ -561,9 +578,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,
@@ -571,6 +591,7 @@ def build_builder_server() -> FastMCP:
             hide_copyright=hide_copyright,
             dash_global_config=dash_global_config,
             config=config or {},
+            payload=payload,
         )
 
     @server.tool()

package/src/qingflow_mcp/server_app_user.py

@@ -31,7 +31,7 @@ def build_user_server() -> FastMCP:
 
 ## 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.
@@ -47,9 +47,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.
@@ -59,7 +59,7 @@ 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 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; 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.
@@ -102,9 +102,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`
+`app_get -> record_browse_schema_get(view_id=...) -> record_list / record_get / record_logs_get`
 `record_insert_schema_get -> record_insert(items)`
-`record_update_schema_get -> record_update`
+`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`
 `portal_list -> portal_get -> chart_get / view_get`
@@ -117,15 +117,16 @@ 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 and internally selects the first accessible view that can execute the current payload.
+- `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 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_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.
@@ -190,7 +191,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 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`.
 - 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.
@@ -360,12 +361,8 @@ If the current MCP capability is unsupported, the workflow is awkward, or the us
         )
 
     @server.tool()
-    def app_list(profile: str = DEFAULT_PROFILE) -> dict:
-        return apps.app_list(profile=profile)
-
-    @server.tool()
-    def app_search(profile: str = DEFAULT_PROFILE, keyword: str = "", page_num: int = 1, page_size: int = 50) -> dict:
-        return apps.app_search(profile=profile, keyword=keyword, page_num=page_num, page_size=page_size)
+    def app_list(profile: str = DEFAULT_PROFILE, query: str = "", keyword: str = "") -> dict:
+        return apps.app_list(profile=profile, query=query, keyword=keyword)
 
     @server.tool()
     def app_get(profile: str = DEFAULT_PROFILE, app_key: str = "") -> dict: