@josephyan/qingflow-cli 0.2.0-beta.64 → 0.2.0-beta.66

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @josephyan/qingflow-cli@0.2.0-beta.64
+npm install @josephyan/qingflow-cli@0.2.0-beta.66
 ```
 
 Run:
 
 ```bash
-npx -y -p @josephyan/qingflow-cli@0.2.0-beta.64 qingflow
+npx -y -p @josephyan/qingflow-cli@0.2.0-beta.66 qingflow
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "0.2.0-beta.64",
+  "version": "0.2.0-beta.66",
   "description": "Human-friendly Qingflow command line interface for auth, record operations, import, tasks, and stable builder flows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

package/src/qingflow_mcp/builder_facade/models.py

@@ -639,6 +639,7 @@ class CustomButtonPatch(StrictModel):
     background_color: str = Field(validation_alias=AliasChoices("background_color", "backgroundColor"))
     text_color: str = Field(validation_alias=AliasChoices("text_color", "textColor"))
     button_icon: str = Field(validation_alias=AliasChoices("button_icon", "buttonIcon"))
+    icon_color: str | None = Field(default=None, validation_alias=AliasChoices("icon_color", "iconColor"))
     trigger_action: PublicButtonTriggerAction = Field(validation_alias=AliasChoices("trigger_action", "triggerAction"))
     trigger_link_url: str | None = Field(default=None, validation_alias=AliasChoices("trigger_link_url", "triggerLinkUrl"))
     trigger_add_data_config: CustomButtonAddDataConfigPatch | None = Field(
@@ -678,6 +679,7 @@ class ViewButtonBindingPatch(StrictModel):
     button_id: int = Field(validation_alias=AliasChoices("button_id", "buttonId", "id"))
     button_text: str | None = Field(default=None, validation_alias=AliasChoices("button_text", "buttonText"))
     button_icon: str | None = Field(default=None, validation_alias=AliasChoices("button_icon", "buttonIcon"))
+    icon_color: str | None = Field(default=None, validation_alias=AliasChoices("icon_color", "iconColor"))
     background_color: str | None = Field(default=None, validation_alias=AliasChoices("background_color", "backgroundColor"))
     text_color: str | None = Field(default=None, validation_alias=AliasChoices("text_color", "textColor"))
     trigger_action: str | None = Field(default=None, validation_alias=AliasChoices("trigger_action", "triggerAction"))
@@ -994,6 +996,7 @@ FieldPatch.model_rebuild()
 class AppReadSummaryResponse(StrictModel):
     app_key: str
     title: str | None = None
+    app_icon: str | None = None
     tag_ids: list[int] = Field(default_factory=list)
     publish_status: int | None = None
     field_count: int = 0
@@ -1051,6 +1054,8 @@ class SchemaPlanRequest(StrictModel):
     app_key: str = ""
     package_tag_id: int | None = None
     app_name: str = Field(default="", validation_alias=AliasChoices("app_name", "app_title", "title"))
+    icon: str | None = None
+    color: str | None = None
     create_if_missing: bool = False
     add_fields: list[FieldPatch] = Field(default_factory=list)
     update_fields: list[FieldUpdatePatch] = Field(default_factory=list)

package/src/qingflow_mcp/builder_facade/service.py

@@ -16,7 +16,7 @@ from ..list_type_labels import RECORD_LIST_TYPE_LABELS, SYSTEM_VIEW_ID_TO_LIST_T
 from ..solution.build_assembly_store import BuildAssemblyStore, default_artifacts, default_manifest
 from ..solution.compiler.chart_compiler import qingbi_workspace_visible_auth
 from ..solution.compiler.form_compiler import build_question, default_form_payload, default_member_auth
-from ..solution.compiler.icon_utils import encode_workspace_icon
+from ..solution.compiler.icon_utils import encode_workspace_icon_with_defaults
 from ..solution.compiler.view_compiler import VIEW_TYPE_MAP
 from ..solution.executor import _build_viewgraph_questions, _compact_dict, extract_field_map
 from ..solution.spec_models import FieldType, FormLayoutRowSpec, FormLayoutSectionSpec, ViewSpec
@@ -1968,6 +1968,7 @@ class AiBuilderFacade:
         response = AppReadSummaryResponse(
             app_key=app_key,
             title=state["base"].get("formTitle"),
+            app_icon=str(state["base"].get("appIcon") or "").strip() or None,
             tag_ids=_coerce_int_list(state["base"].get("tagIds")),
             publish_status=state["base"].get("appPublishStatus"),
             field_count=len(parsed["fields"]),
@@ -2674,6 +2675,7 @@ class AiBuilderFacade:
             "app": {
                 "app_key": app_key,
                 "title": base_result.get("formTitle"),
+                "app_icon": str(base_result.get("appIcon") or "").strip() or None,
                 "tag_ids": _coerce_int_list(base_result.get("tagIds")),
                 "publish_status": base_result.get("appPublishStatus"),
             },
@@ -2706,6 +2708,8 @@ class AiBuilderFacade:
         app_key: str = "",
         package_tag_id: int | None = None,
         app_name: str = "",
+        icon: str | None = None,
+        color: str | None = None,
         create_if_missing: bool = False,
         publish: bool = True,
         add_fields: list[FieldPatch],
@@ -2716,6 +2720,8 @@ class AiBuilderFacade:
             "app_key": app_key,
             "package_tag_id": package_tag_id,
             "app_name": app_name,
+            "icon": icon,
+            "color": color,
             "create_if_missing": create_if_missing,
             "publish": publish,
             "add_fields": [patch.model_dump(mode="json") for patch in add_fields],
@@ -2766,6 +2772,8 @@ class AiBuilderFacade:
                 profile=profile,
                 app_name=app_name,
                 package_tag_id=package_tag_id,
+                icon=icon,
+                color=color,
             )
             if resolved.get("status") == "failed":
                 if not isinstance(resolved.get("normalized_args"), dict) or not resolved.get("normalized_args"):
@@ -2789,6 +2797,23 @@ class AiBuilderFacade:
             if permission_outcome.block is not None:
                 return permission_outcome.block
             permission_outcomes.append(permission_outcome)
+            visual_result = self._ensure_app_base_visuals(
+                profile=profile,
+                app_key=target.app_key,
+                fallback_title=target.app_name,
+                icon=icon,
+                color=color,
+                normalized_args=normalized_args,
+            )
+            if visual_result.get("status") == "failed":
+                return finalize(visual_result)
+        else:
+            visual_result = {
+                "status": "success",
+                "updated": False,
+                "app_icon": str(resolved.get("app_icon") or "").strip() or None,
+                "request_id": None,
+            }
         if bool(resolved.get("created")) and not requested_field_changes:
             return finalize({
                 "status": "success",
@@ -2807,9 +2832,11 @@ class AiBuilderFacade:
                     "fields_verified": True,
                     "package_attached": None if package_tag_id is None else package_tag_id in target.tag_ids,
                     "relation_field_limit_verified": True,
+                    "app_visuals_verified": True,
                     "publish_skipped": True,
                 },
                 "app_key": target.app_key,
+                "app_icon": str(resolved.get("app_icon") or visual_result.get("app_icon") or "").strip() or None,
                 "created": True,
                 "field_diff": {"added": [], "updated": [], "removed": []},
                 "verified": True,
@@ -2931,17 +2958,22 @@ class AiBuilderFacade:
                 "status": "success",
                 "error_code": None,
                 "recoverable": False,
-                "message": "schema already matches requested state",
+                "message": "updated app visuals; schema already matches requested state" if bool(visual_result.get("updated")) else "schema already matches requested state",
                 "normalized_args": normalized_args,
                 "missing_fields": [],
                 "allowed_values": {"field_types": [item.value for item in PublicFieldType]},
                 "details": {},
                 "request_id": None,
                 "suggested_next_call": None if package_attached is not False else {"tool_name": "package_attach_app", "arguments": {"profile": profile, "tag_id": package_tag_id, "app_key": target.app_key}},
-                "noop": True,
+                "noop": not bool(visual_result.get("updated")),
                 "warnings": relation_warnings,
-                "verification": {"fields_verified": True, "relation_field_limit_verified": relation_limit_verified},
+                "verification": {
+                    "fields_verified": True,
+                    "relation_field_limit_verified": relation_limit_verified,
+                    "app_visuals_verified": True,
+                },
                 "app_key": target.app_key,
+                "app_icon": str(visual_result.get("app_icon") or "").strip() or None,
                 "created": False,
                 "field_diff": {"added": [], "updated": [], "removed": []},
                 "verified": True,
@@ -3013,9 +3045,11 @@ class AiBuilderFacade:
             "verification": {
                 "fields_verified": False,
                 "package_attached": None,
+                "app_visuals_verified": True,
                 "relation_field_limit_verified": relation_limit_verified,
             },
             "app_key": target.app_key,
+            "app_icon": str(visual_result.get("app_icon") or resolved.get("app_icon") or "").strip() or None,
             "created": bool(resolved.get("created")),
             "field_diff": {
                 "added": added,
@@ -5482,9 +5516,17 @@ class AiBuilderFacade:
         profile: str,
         app_name: str,
         package_tag_id: int | None,
+        icon: str | None,
+        color: str | None,
     ) -> JSONObject:
         payload: JSONObject = {
             "appName": app_name or "未命名应用",
+            "appIcon": encode_workspace_icon_with_defaults(
+                icon=icon,
+                color=color,
+                title=app_name or "未命名应用",
+                fallback_icon_name="template",
+            ),
             "auth": default_member_auth(),
             "tagIds": [package_tag_id] if package_tag_id and package_tag_id > 0 else [],
         }
@@ -5530,6 +5572,7 @@ class AiBuilderFacade:
                 "suggested_next_call": None,
                 "app_key": new_app_key,
                 "app_name": app_name or "未命名应用",
+                "app_icon": payload.get("appIcon"),
                 "tag_ids": [package_tag_id] if package_tag_id and package_tag_id > 0 else [],
                 "created": True,
             }
@@ -5541,10 +5584,103 @@ class AiBuilderFacade:
             "suggested_next_call": None,
             "app_key": new_app_key,
             "app_name": base.get("formTitle") or app_name or "未命名应用",
+            "app_icon": str(base.get("appIcon") or payload.get("appIcon") or "").strip() or None,
             "tag_ids": _coerce_int_list(base.get("tagIds")),
             "created": True,
         }
 
+    def _build_app_base_update_payload(
+        self,
+        *,
+        raw_base: dict[str, Any],
+        form_title: str,
+        app_icon: str,
+    ) -> JSONObject | None:
+        auth = deepcopy(raw_base.get("auth"))
+        if not isinstance(auth, dict):
+            return None
+        payload: JSONObject = {
+            "formTitle": form_title,
+            "auth": auth,
+            "appIcon": app_icon,
+        }
+        tag_ids = _coerce_int_list(raw_base.get("tagIds"))
+        if tag_ids:
+            payload["tagIds"] = tag_ids
+        return payload
+
+    def _ensure_app_base_visuals(
+        self,
+        *,
+        profile: str,
+        app_key: str,
+        fallback_title: str,
+        icon: str | None,
+        color: str | None,
+        normalized_args: dict[str, Any],
+    ) -> JSONObject:
+        if not icon and not color:
+            return {
+                "status": "success",
+                "updated": False,
+                "app_icon": None,
+                "request_id": None,
+            }
+        try:
+            base_result = self.apps.app_get_base(profile=profile, app_key=app_key, include_raw=True)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "APP_VISUAL_READ_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        raw_base = base_result.get("result") if isinstance(base_result.get("result"), dict) else {}
+        effective_title = str(raw_base.get("formTitle") or fallback_title or "未命名应用").strip() or "未命名应用"
+        existing_icon = str(raw_base.get("appIcon") or "").strip() or None
+        desired_icon = encode_workspace_icon_with_defaults(
+            icon=icon,
+            color=color,
+            title=effective_title,
+            fallback_icon_name="template",
+            existing_icon=existing_icon,
+        )
+        if desired_icon == existing_icon:
+            return {
+                "status": "success",
+                "updated": False,
+                "app_icon": desired_icon,
+                "request_id": None,
+            }
+        payload = self._build_app_base_update_payload(raw_base=raw_base, form_title=effective_title, app_icon=desired_icon)
+        if payload is None:
+            return _failed(
+                "APP_VISUAL_UPDATE_UNSUPPORTED",
+                "app base info did not include editable auth payload required for icon update",
+                normalized_args=normalized_args,
+                details={"app_key": app_key},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        try:
+            update_result = self.apps.app_update_base(profile=profile, app_key=app_key, payload=payload)
+        except (QingflowApiError, RuntimeError) as error:
+            api_error = _coerce_api_error(error)
+            return _failed_from_api_error(
+                "APP_VISUAL_UPDATE_FAILED",
+                api_error,
+                normalized_args=normalized_args,
+                details={"app_key": app_key, "app_icon": desired_icon},
+                suggested_next_call={"tool_name": "app_read_summary", "arguments": {"profile": profile, "app_key": app_key}},
+            )
+        return {
+            "status": "success",
+            "updated": True,
+            "app_icon": desired_icon,
+            "request_id": update_result.get("request_id") if isinstance(update_result, dict) else None,
+        }
+
     def _current_request_route(self, profile: str) -> JSONObject:
         session_profile = self.apps.sessions.get_profile(profile)
         backend_session = self.apps.sessions.get_backend_session(profile)
@@ -5727,6 +5863,8 @@ def _serialize_custom_button_payload(payload: CustomButtonPatch) -> dict[str, An
         "buttonIcon": data["button_icon"],
         "triggerAction": data["trigger_action"],
     }
+    if str(data.get("icon_color") or "").strip():
+        serialized["iconColor"] = data["icon_color"]
     if str(data.get("trigger_link_url") or "").strip():
         serialized["triggerLinkUrl"] = data["trigger_link_url"]
     trigger_add_data_config = data.get("trigger_add_data_config")
@@ -5816,6 +5954,7 @@ def _normalize_custom_button_summary(item: dict[str, Any]) -> dict[str, Any]:
         "button_id": _coerce_positive_int(item.get("button_id") or item.get("buttonId") or item.get("id")),
         "button_text": str(item.get("button_text") or item.get("buttonText") or "").strip() or None,
         "button_icon": str(item.get("button_icon") or item.get("buttonIcon") or "").strip() or None,
+        "icon_color": str(item.get("icon_color") or item.get("iconColor") or "").strip() or None,
         "background_color": str(item.get("background_color") or item.get("backgroundColor") or "").strip() or None,
         "text_color": str(item.get("text_color") or item.get("textColor") or "").strip() or None,
         "used_in_chart_count": _coerce_nonnegative_int(item.get("used_in_chart_count") or item.get("userInChartCount")),
@@ -6572,11 +6711,12 @@ def _build_public_portal_base_payload(
     effective_name = str(dash_name or data.get("dashName") or "").strip() or "未命名门户"
     effective_hide_copyright = hide_copyright if hide_copyright is not None else bool(data.get("hideCopyright", False))
     if icon or color or not data.get("dashIcon"):
-        data["dashIcon"] = encode_workspace_icon(
+        data["dashIcon"] = encode_workspace_icon_with_defaults(
             icon=icon,
             color=color,
             title=effective_name,
             fallback_icon_name="view-grid",
+            existing_icon=str(data.get("dashIcon") or "").strip() or None,
         )
     data["dashName"] = effective_name
     data["auth"] = deepcopy(auth if auth is not None else data.get("auth") or default_member_auth())
@@ -8593,6 +8733,7 @@ def _normalize_view_button_entry(entry: dict[str, Any]) -> dict[str, Any]:
     for public_key, source_key in (
         ("default_button_text", "defaultButtonText"),
         ("button_icon", "buttonIcon"),
+        ("icon_color", "iconColor"),
         ("background_color", "backgroundColor"),
         ("text_color", "textColor"),
         ("trigger_link_url", "triggerLinkUrl"),
@@ -8622,17 +8763,21 @@ def _normalize_view_buttons_for_compare(value: Any) -> list[dict[str, Any]]:
     normalized_entries: list[dict[str, Any]] = []
     for entry in entries:
         normalized = _normalize_view_button_entry(entry)
+        is_custom = normalized.get("button_type") == "CUSTOM"
         normalized_entries.append(
             {
                 "button_type": normalized.get("button_type"),
                 "config_type": normalized.get("config_type"),
-                "button_id": normalized.get("button_id") if normalized.get("button_type") == "CUSTOM" else None,
+                "button_id": normalized.get("button_id") if is_custom else None,
                 "button_text": normalized.get("button_text"),
                 "button_icon": normalized.get("button_icon"),
+                "icon_color": normalized.get("icon_color"),
                 "background_color": normalized.get("background_color"),
                 "text_color": normalized.get("text_color"),
                 "trigger_action": normalized.get("trigger_action"),
-                "trigger_link_url": normalized.get("trigger_link_url"),
+                # Custom button trigger details are verified by dedicated button CRUD readback.
+                # View binding verification should focus on binding/display semantics and tolerate resource-owned URLs.
+                "trigger_link_url": None if is_custom else normalized.get("trigger_link_url"),
                 "being_main": bool(normalized.get("being_main", False)),
                 "print_tpls": _normalize_print_tpls_for_compare(normalized.get("print_tpls")),
                 "button_formula": str(normalized.get("button_formula") or ""),
@@ -8701,13 +8846,13 @@ def _normalize_expected_view_buttons_for_compare(
                 for key in (
                     "button_text",
                     "button_icon",
+                    "icon_color",
                     "background_color",
                     "text_color",
                     "trigger_action",
-                    "trigger_link_url",
                 ):
                     value = detail.get(key)
-                    if value not in {None, ""}:
+                    if enriched.get(key) in {None, ""} and value not in {None, ""}:
                         enriched[key] = deepcopy(value)
         enriched_entries.append(enriched)
     return enriched_entries
@@ -8881,9 +9026,11 @@ def _serialize_view_button_binding(
         "buttonFormulaType": binding.button_formula_type,
         "printTpls": _serialize_print_tpl_ids(binding.print_tpls),
     }
-    if binding.button_type == PublicViewButtonType.system:
+    if binding.button_type in {PublicViewButtonType.system, PublicViewButtonType.custom}:
         dto["buttonText"] = binding.button_text
         dto["buttonIcon"] = binding.button_icon
+        if str(binding.icon_color or "").strip():
+            dto["iconColor"] = binding.icon_color
         dto["backgroundColor"] = binding.background_color
         dto["textColor"] = binding.text_color
         dto["triggerAction"] = binding.trigger_action

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

@@ -93,6 +93,8 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     schema_apply_apply.add_argument("--package-tag-id", type=int)
     schema_apply_apply.add_argument("--app-name", default="")
     schema_apply_apply.add_argument("--app-title", default="")
+    schema_apply_apply.add_argument("--icon")
+    schema_apply_apply.add_argument("--color")
     schema_apply_apply.add_argument("--create-if-missing", action="store_true")
     schema_apply_apply.add_argument("--publish", action=argparse.BooleanOptionalAction, default=True)
     schema_apply_apply.add_argument("--add-fields-file")
@@ -198,6 +200,8 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
         package_tag_id=args.package_tag_id,
         app_name=args.app_name,
         app_title=args.app_title,
+        icon=args.icon,
+        color=args.color,
         create_if_missing=bool(args.create_if_missing),
         publish=bool(args.publish),
         add_fields=load_list_arg(args.add_fields_file, option_name="--add-fields-file"),

package/src/qingflow_mcp/server_app_builder.py

@@ -280,6 +280,8 @@ def build_builder_server() -> FastMCP:
         package_tag_id: int | None = None,
         app_name: str = "",
         app_title: str = "",
+        icon: str = "",
+        color: str = "",
         create_if_missing: bool = False,
         publish: bool = True,
         add_fields: list[dict] | None = None,
@@ -292,6 +294,8 @@ def build_builder_server() -> FastMCP:
             package_tag_id=package_tag_id,
             app_name=app_name,
             app_title=app_title,
+            icon=icon,
+            color=color,
             create_if_missing=create_if_missing,
             publish=publish,
             add_fields=add_fields or [],

package/src/qingflow_mcp/solution/compiler/icon_utils.py

@@ -1,44 +1,57 @@
 from __future__ import annotations
 
 import json
+import re
 
 
 DEFAULT_ICON_COLOR = "qing-orange"
-SUPPORTED_EX_ICONS = {
-    "ex-alert-outlined",
-    "ex-clock-outlined",
-    "ex-folder-outlined",
-    "ex-form-outlined",
-    "ex-home-outlined",
-    "ex-user-outlined",
+DEFAULT_ICON_STYLE_POOL: tuple[tuple[str, str], ...] = (
+    ("briefcase", "qing-orange"),
+    ("calendar", "emerald"),
+    ("files-folder", "azure"),
+    ("shield-check", "indigo"),
+    ("user-group", "qing-purple"),
+    ("chart-square-bar", "blue"),
+    ("clock", "pink"),
+    ("document-text", "green"),
+    ("home", "orange"),
+    ("globe", "red"),
+)
+LEGACY_EX_ICON_MAP = {
+    "ex-alert-outlined": "exclamation-circle",
+    "ex-clock-outlined": "clock",
+    "ex-folder-outlined": "folder",
+    "ex-form-outlined": "template",
+    "ex-home-outlined": "home",
+    "ex-user-outlined": "user",
 }
 
 ICON_ALIAS_MAP = {
-    "archive-box": "ex-form-outlined",
-    "beaker": "ex-form-outlined",
-    "briefcase": "ex-folder-outlined",
-    "building-office": "ex-form-outlined",
-    "calendar": "ex-clock-outlined",
-    "chat": "ex-clock-outlined",
-    "chat-bubble-left-right": "ex-clock-outlined",
-    "chart-bar": "ex-form-outlined",
-    "chart-square-bar": "ex-form-outlined",
-    "check-badge": "ex-alert-outlined",
-    "check-circle": "ex-alert-outlined",
-    "clipboard-check": "ex-form-outlined",
-    "clock": "ex-clock-outlined",
-    "cube": "ex-form-outlined",
-    "document-text": "ex-form-outlined",
-    "folder": "ex-folder-outlined",
-    "home": "ex-home-outlined",
-    "office-building": "ex-form-outlined",
-    "shield-check": "ex-alert-outlined",
-    "template": "ex-form-outlined",
-    "user": "ex-user-outlined",
-    "user-group": "ex-user-outlined",
-    "users": "ex-user-outlined",
-    "view-grid": "ex-home-outlined",
-    "warning": "ex-alert-outlined",
+    "archive-box": "template",
+    "beaker": "beaker",
+    "briefcase": "briefcase",
+    "building-office": "office-building",
+    "calendar": "calendar",
+    "chat": "chat",
+    "chat-bubble-left-right": "chat",
+    "chart-bar": "chart-bar",
+    "chart-square-bar": "chart-square-bar",
+    "check-badge": "badge-check",
+    "check-circle": "check-circle",
+    "clipboard-check": "clipboard-check",
+    "clock": "clock",
+    "cube": "cube-transparent",
+    "document-text": "document-text",
+    "folder": "files-folder",
+    "home": "home",
+    "office-building": "office-building",
+    "shield-check": "shield-check",
+    "template": "template",
+    "user": "user",
+    "user-group": "user-group",
+    "users": "user-group",
+    "view-grid": "view-grid",
+    "warning": "exclamation-circle",
 }
 
 
@@ -52,8 +65,6 @@ def encode_workspace_icon(
     if icon and _looks_like_icon_json(icon):
         return icon
     normalized_icon_name = normalize_workspace_icon_name(icon or fallback_icon_name)
-    if normalized_icon_name and normalized_icon_name.startswith("ex-") and not color:
-        return normalized_icon_name
     icon_name = normalized_icon_name
     icon_color = color or DEFAULT_ICON_COLOR
     if icon_name:
@@ -78,6 +89,65 @@ def encode_workspace_icon(
     )
 
 
+def choose_default_workspace_icon_style(*, title: str) -> tuple[str, str]:
+    seed_text = (title or "未命名").strip() or "未命名"
+    digest = 0
+    for index, char in enumerate(seed_text):
+        digest = (digest * 131 + ord(char) + index) % 1_000_003
+    return DEFAULT_ICON_STYLE_POOL[digest % len(DEFAULT_ICON_STYLE_POOL)]
+
+
+def parse_workspace_icon(value: str | None) -> tuple[str | None, str | None, str | None]:
+    if not value:
+        return None, None, None
+    stripped = str(value).strip()
+    if not stripped:
+        return None, None, None
+    if _looks_like_icon_json(stripped):
+        try:
+            payload = json.loads(stripped)
+        except Exception:
+            return normalize_workspace_icon_name(stripped), None, None
+        icon_name = normalize_workspace_icon_name(payload.get("iconName"))
+        icon_color = str(payload.get("iconColor") or "").strip() or None
+        icon_text = str(payload.get("iconText") or "").strip() or None
+        return icon_name, icon_color, icon_text
+    return normalize_workspace_icon_name(stripped), None, None
+
+
+def encode_workspace_icon_with_defaults(
+    *,
+    icon: str | None,
+    color: str | None,
+    title: str,
+    fallback_icon_name: str | None = None,
+    existing_icon: str | None = None,
+) -> str:
+    if icon and _looks_like_icon_json(icon):
+        return icon
+    if not icon and not color and existing_icon:
+        existing_payload = str(existing_icon).strip()
+        if existing_payload:
+            return existing_payload
+    existing_icon_name, existing_icon_color, _ = parse_workspace_icon(existing_icon)
+    default_icon, default_color = choose_default_workspace_icon_style(title=title)
+    resolved_icon = icon or existing_icon_name
+    resolved_color = color or existing_icon_color
+    if not resolved_icon:
+        if icon is None and color is None:
+            resolved_icon = default_icon
+        else:
+            resolved_icon = fallback_icon_name or default_icon
+    if not resolved_color:
+        resolved_color = default_color
+    return encode_workspace_icon(
+        icon=resolved_icon,
+        color=resolved_color,
+        title=title,
+        fallback_icon_name=fallback_icon_name,
+    )
+
+
 def normalize_workspace_icon_name(icon: str | None) -> str | None:
     if not icon:
         return None
@@ -85,27 +155,31 @@ def normalize_workspace_icon_name(icon: str | None) -> str | None:
         try:
             payload = json.loads(icon)
         except Exception:
-            return "ex-form-outlined"
-        return normalize_workspace_icon_name(payload.get("iconName")) or "ex-form-outlined"
-    if icon in SUPPORTED_EX_ICONS:
-        return icon
+            return "template"
+        return normalize_workspace_icon_name(payload.get("iconName")) or "template"
     normalized = icon.strip().lower()
+    if normalized in LEGACY_EX_ICON_MAP:
+        return LEGACY_EX_ICON_MAP[normalized]
     if normalized in ICON_ALIAS_MAP:
         return ICON_ALIAS_MAP[normalized]
     for token in normalized.replace("_", "-").split("-"):
         if token in ICON_ALIAS_MAP:
             return ICON_ALIAS_MAP[token]
     if "folder" in normalized or "package" in normalized:
-        return "ex-folder-outlined"
-    if "home" in normalized or "portal" in normalized or "dashboard" in normalized:
-        return "ex-home-outlined"
+        return "files-folder"
+    if "home" in normalized:
+        return "home"
+    if "portal" in normalized or "dashboard" in normalized:
+        return "view-grid"
     if "user" in normalized or "member" in normalized or "contact" in normalized:
-        return "ex-user-outlined"
+        return "user"
     if "clock" in normalized or "time" in normalized or "schedule" in normalized or "log" in normalized:
-        return "ex-clock-outlined"
+        return "clock"
     if "risk" in normalized or "alert" in normalized or "warn" in normalized or "safety" in normalized:
-        return "ex-alert-outlined"
-    return "ex-form-outlined"
+        return "exclamation-circle"
+    if re.fullmatch(r"[a-z0-9-]+", normalized):
+        return normalized
+    return "template"
 
 
 def _looks_like_icon_json(value: str) -> bool:

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -228,6 +228,8 @@ class AiBuilderTools(ToolBase):
             package_tag_id: int | None = None,
             app_name: str = "",
             app_title: str = "",
+            icon: str = "",
+            color: str = "",
             create_if_missing: bool = False,
             publish: bool = True,
             add_fields: list[JSONObject] | None = None,
@@ -240,6 +242,8 @@ class AiBuilderTools(ToolBase):
                 package_tag_id=package_tag_id,
                 app_name=app_name,
                 app_title=app_title,
+                icon=icon,
+                color=color,
                 create_if_missing=create_if_missing,
                 publish=publish,
                 add_fields=add_fields or [],
@@ -713,6 +717,8 @@ class AiBuilderTools(ToolBase):
         app_key: str = "",
         package_tag_id: int | None = None,
         app_name: str = "",
+        icon: str = "",
+        color: str = "",
         create_if_missing: bool = False,
         add_fields: list[JSONObject],
         update_fields: list[JSONObject],
@@ -724,6 +730,8 @@ class AiBuilderTools(ToolBase):
                     "app_key": app_key,
                     "package_tag_id": package_tag_id,
                     "app_name": app_name,
+                    "icon": icon,
+                    "color": color,
                     "create_if_missing": create_if_missing,
                     "add_fields": add_fields,
                     "update_fields": update_fields,
@@ -742,6 +750,8 @@ class AiBuilderTools(ToolBase):
                         "app_key": app_key,
                         "package_tag_id": package_tag_id,
                         "app_name": app_name,
+                        "icon": icon,
+                        "color": color,
                         "create_if_missing": create_if_missing,
                         "add_fields": [{"name": "字段名称", "type": "text"}],
                         "update_fields": [],
@@ -889,6 +899,8 @@ class AiBuilderTools(ToolBase):
         package_tag_id: int | None = None,
         app_name: str = "",
         app_title: str = "",
+        icon: str = "",
+        color: str = "",
         create_if_missing: bool = False,
         publish: bool = True,
         add_fields: list[JSONObject],
@@ -901,6 +913,8 @@ class AiBuilderTools(ToolBase):
             package_tag_id=package_tag_id,
             app_name=app_name,
             app_title=app_title,
+            icon=icon,
+            color=color,
             create_if_missing=create_if_missing,
             publish=publish,
             add_fields=add_fields,
@@ -916,6 +930,8 @@ class AiBuilderTools(ToolBase):
                 package_tag_id=package_tag_id,
                 app_name=app_name,
                 app_title=app_title,
+                icon=icon,
+                color=color,
                 create_if_missing=create_if_missing,
                 publish=publish,
                 add_fields=add_fields,
@@ -932,6 +948,8 @@ class AiBuilderTools(ToolBase):
         package_tag_id: int | None = None,
         app_name: str = "",
         app_title: str = "",
+        icon: str = "",
+        color: str = "",
         create_if_missing: bool = False,
         publish: bool = True,
         add_fields: list[JSONObject],
@@ -945,6 +963,8 @@ class AiBuilderTools(ToolBase):
                 app_key=app_key,
                 package_tag_id=package_tag_id,
                 app_name=effective_app_name,
+                icon=icon,
+                color=color,
                 create_if_missing=create_if_missing,
                 add_fields=add_fields,
                 update_fields=update_fields,
@@ -976,6 +996,8 @@ class AiBuilderTools(ToolBase):
                         "app_key": str(plan_args.get("app_key") or app_key),
                         "package_tag_id": plan_args.get("package_tag_id", package_tag_id),
                         "app_name": str(plan_args.get("app_name") or effective_app_name),
+                        "icon": str(plan_args.get("icon") or icon),
+                        "color": str(plan_args.get("color") or color),
                         "create_if_missing": bool(plan_args.get("create_if_missing", create_if_missing)),
                         "publish": publish,
                         "add_fields": plan_args.get("add_fields") or [{"name": "字段名称", "type": "text", "required": False}],
@@ -988,6 +1010,8 @@ class AiBuilderTools(ToolBase):
             "app_key": str(plan_args.get("app_key") or app_key),
             "package_tag_id": plan_args.get("package_tag_id", package_tag_id),
             "app_name": str(plan_args.get("app_name") or effective_app_name),
+            "icon": str(plan_args.get("icon") or icon or ""),
+            "color": str(plan_args.get("color") or color or ""),
             "create_if_missing": bool(plan_args.get("create_if_missing", create_if_missing)),
             "publish": publish,
             "add_fields": [patch.model_dump(mode="json") for patch in parsed_add],
@@ -1000,6 +1024,8 @@ class AiBuilderTools(ToolBase):
                 app_key=str(plan_args.get("app_key") or app_key),
                 package_tag_id=plan_args.get("package_tag_id", package_tag_id),
                 app_name=str(plan_args.get("app_name") or effective_app_name),
+                icon=str(plan_args.get("icon") or icon or ""),
+                color=str(plan_args.get("color") or color or ""),
                 create_if_missing=bool(plan_args.get("create_if_missing", create_if_missing)),
                 publish=publish,
                 add_fields=parsed_add,
@@ -1744,6 +1770,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "payload.backgroundColor": "payload.background_color",
             "payload.textColor": "payload.text_color",
             "payload.buttonIcon": "payload.button_icon",
+            "payload.iconColor": "payload.icon_color",
             "payload.triggerAction": "payload.trigger_action",
             "payload.triggerLinkUrl": "payload.trigger_link_url",
             "payload.triggerAddDataConfig": "payload.trigger_add_data_config",
@@ -1762,6 +1789,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 "background_color": "#FFFFFF",
                 "text_color": "#494F57",
                 "button_icon": "ex-add-outlined",
+                "icon_color": "#494F57",
                 "trigger_action": "link",
                 "trigger_link_url": "https://example.com",
             },
@@ -1775,6 +1803,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "payload.backgroundColor": "payload.background_color",
             "payload.textColor": "payload.text_color",
             "payload.buttonIcon": "payload.button_icon",
+            "payload.iconColor": "payload.icon_color",
             "payload.triggerAction": "payload.trigger_action",
             "payload.triggerLinkUrl": "payload.trigger_link_url",
             "payload.triggerAddDataConfig": "payload.trigger_add_data_config",
@@ -1794,6 +1823,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
                 "background_color": "#FFFFFF",
                 "text_color": "#494F57",
                 "button_icon": "ex-link-outlined",
+                "icon_color": "#494F57",
                 "trigger_action": "link",
                 "trigger_link_url": "https://example.com/detail",
             },
@@ -1810,7 +1840,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_schema_plan": {
-        "allowed_keys": ["app_key", "package_tag_id", "app_name", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
+        "allowed_keys": ["app_key", "package_tag_id", "app_name", "icon", "color", "create_if_missing", "add_fields", "update_fields", "remove_fields"],
         "aliases": {
             "app_title": "app_name",
             "title": "app_name",
@@ -1835,6 +1865,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "app_name": "研发项目管理",
             "package_tag_id": 1001,
+            "icon": "template",
+            "color": "emerald",
             "create_if_missing": True,
             "add_fields": [{"name": "项目名称", "type": "text"}],
             "update_fields": [],
@@ -1858,7 +1890,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "app_schema_apply": {
-        "allowed_keys": ["app_key", "package_tag_id", "app_name", "create_if_missing", "publish", "add_fields", "update_fields", "remove_fields"],
+        "allowed_keys": ["app_key", "package_tag_id", "app_name", "icon", "color", "create_if_missing", "publish", "add_fields", "update_fields", "remove_fields"],
         "aliases": {
             "app_title": "app_name",
             "title": "app_name",
@@ -1888,6 +1920,8 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "profile": "default",
             "app_name": "研发项目管理",
             "package_tag_id": 1001,
+            "icon": "template",
+            "color": "emerald",
             "create_if_missing": True,
             "publish": True,
             "add_fields": [{"name": "项目名称", "type": "text"}],

package/src/qingflow_mcp/tools/custom_button_tools.py

@@ -147,6 +147,7 @@ class CustomButtonTools(ToolBase):
             "button_id": item.get("buttonId"),
             "button_text": item.get("buttonText"),
             "button_icon": item.get("buttonIcon"),
+            "icon_color": item.get("iconColor"),
             "background_color": item.get("backgroundColor"),
             "text_color": item.get("textColor"),
             "creator_user_info": {
@@ -165,6 +166,7 @@ class CustomButtonTools(ToolBase):
             "button_id": item.get("buttonId"),
             "button_text": item.get("buttonText"),
             "button_icon": item.get("buttonIcon"),
+            "icon_color": item.get("iconColor"),
             "background_color": item.get("backgroundColor"),
             "text_color": item.get("textColor"),
             "trigger_action": item.get("triggerAction"),