@qingflow-tech/qingflow-app-user-mcp 1.0.32 → 1.0.34

package/README.md

@@ -3,13 +3,13 @@
 Install:
 
 ```bash
-npm install @qingflow-tech/qingflow-app-user-mcp@1.0.32
+npm install @qingflow-tech/qingflow-app-user-mcp@1.0.34
 ```
 
 Run:
 
 ```bash
-npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.32 qingflow-app-user-mcp
+npx -y -p @qingflow-tech/qingflow-app-user-mcp@1.0.34 qingflow-app-user-mcp
 ```
 
 Environment:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qingflow-tech/qingflow-app-user-mcp",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "description": "Operational end-user MCP for Qingflow records, tasks, comments, and directory workflows.",
   "license": "MIT",
   "type": "module",

package/pyproject.toml

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

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

@@ -32,6 +32,22 @@ Default modeling rules:
 - Another business object -> a separate app, not a text field
 - Cross-object links -> relation fields, not text fields
 
+## Route First
+
+Before any builder write, classify the request:
+
+- **Complete system / app package**: the user asks for a system, package, workspace module set, or several related forms/apps. Use `package_apply` for the package, then one `app_schema_apply(apps=[...])` for the app shells and fields. Do not squeeze several business objects into one app.
+- **Single app**: the user names one form/app or gives one `app_key`. Use `app_resolve`/`app_get`, then `app_schema_apply` and the app-scoped apply tools.
+- **Record/user operation**: the user wants to add, edit, delete, approve, or analyze data. Route to the record/task skills instead of builder tools.
+
+For complete systems, `apps[]` should use stable `client_key` values. Same-call relation fields may use `target_app_ref` for a client key or `target_app` for another app name. Prefer `target_app_ref` when names may collide.
+
+Builder schema inputs should follow agent-intuitive semantics:
+
+- icons may be `icon/color`, `icon_name/icon_color`, `icon_config`, or `icon: {name, color}`
+- `single_select` / `multi_select` options may be strings or objects such as `{label, value}`; tools normalize to option labels
+- relation fields need a target plus `display_field` and `visible_fields`
+
 ## Public Tools You Should Think In
 
 - Package: `package_get`, `package_apply`
@@ -51,7 +67,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
   - use `package_apply(...)` for package creation, rename, icon, visibility, grouping, ordering, and app/portal layout
 - Multi-app schema work:
   - use one `app_schema_apply(apps=[...])` / CLI `builder schema apply --apps-file` when creating several apps in one package
-  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`
+  - same-call relation fields may use `target_app_ref` to point at another `apps[].client_key`, or `target_app` to point at another `apps[].app_name`
 - App base permissions:
   - trust `app_get.editability.can_edit_app_base` for app base-info writes like app name, icon, and visibility
   - `can_edit_form` only means schema/form-route capability; it no longer implies app base-info write capability
@@ -107,11 +123,15 @@ Treat these as the official surface. Do not default to `package_create`, `packag
 
 1. Trust the current MCP/session when it is already injected by the runtime; only run auth/workspace recovery after a tool explicitly reports an auth, credential, or workspace error
 2. Confirm whether the task is read-only or write-impacting
-3. Resolve the smallest stable target:
+3. Classify the build scope:
+   - complete system/package -> `package_apply` or `package_get`, then one `app_schema_apply(apps=[...])`
+   - single app -> `app_resolve` / `app_get`, then app-scoped apply tools
+   - record/task/data request -> leave builder and use the matching record/task skill
+4. Resolve the smallest stable target:
    - app-scoped work -> `app_resolve`
    - package-scoped work with known id -> `package_get`
    - portal inventory -> `portal_list`
-4. Read only the smallest config slice needed:
+5. Read only the smallest config slice needed:
    - app map -> `app_get` (default entry; includes compact views, charts, custom buttons, and associated resource pool)
    - fields -> `app_get_fields`
    - layout -> `app_get_layout`
@@ -119,8 +139,8 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - flow -> `app_get_flow`
    - charts -> `app_get_charts` only when the app_get compact list is not enough
    - portal -> `portal_get`
-5. If the public shape is unclear, call `builder_tool_contract`
-6. Apply the smallest patch tool that fits:
+6. If the public shape is unclear, call `builder_tool_contract`
+7. Apply the smallest patch tool that fits:
    - fields -> `app_schema_apply`
    - layout -> `app_layout_apply`
    - flow -> `app_flow_apply`
@@ -130,7 +150,7 @@ Treat these as the official surface. Do not default to `package_create`, `packag
    - existing charts -> `app_charts_apply.patch_charts`; new/full charts -> `app_charts_apply.upsert_charts`
    - portal -> `portal_apply`
    - package metadata/layout -> `package_apply`
-7. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
+8. Use `app_publish_verify` only when the user explicitly wants final publish/live verification or you need a dedicated verification pass
 
 ## Safe Usage Rules
 

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

@@ -9,6 +9,7 @@ Do not use this playbook when the user is really asking for a system/package wit
 2. create the related apps in one `app_schema_apply(apps=[...])` call
 3. keep package ownership on the public `package_id` path instead of a separate attach step
 4. add same-call relation fields with `target_app_ref` when one new app references another new app
+5. choose explicit non-template `icon + color` for each new package/app
 
 Hierarchy reminder:
 
@@ -50,7 +51,8 @@ Create a new package only after the user confirms package creation:
   "arguments": {
     "profile": "default",
     "package_name": "研发项目管理",
-    "create_if_missing": true
+    "create_if_missing": true,
+    "icon": {"name": "briefcase", "color": "azure"}
   }
 }
 ```
@@ -76,6 +78,7 @@ Apply schema for a new app:
     "profile": "default",
     "app_name": "客户订单",
     "package_id": 1218950,
+    "icon": {"name": "delivery-box-1", "color": "emerald"},
     "create_if_missing": true,
     "publish": true,
     "add_fields": [
@@ -83,7 +86,7 @@ Apply schema for a new app:
       {"name": "客户名称", "type": "text", "required": true},
       {"name": "订单封面", "type": "attachment", "as_data_cover": true},
       {"name": "订单金额", "type": "amount"},
-      {"name": "状态", "type": "single_select", "options": ["草稿", "进行中", "已完成"], "required": true}
+      {"name": "状态", "type": "single_select", "options": [{"label": "草稿"}, {"label": "进行中"}, {"label": "已完成"}], "required": true}
     ],
     "update_fields": [],
     "remove_fields": []
@@ -105,6 +108,7 @@ Apply schema for multiple apps in one call:
       {
         "client_key": "customer",
         "app_name": "客户",
+        "icon": {"name": "business-personalcard", "color": "emerald"},
         "add_fields": [
           {"name": "客户名称", "type": "text", "required": true, "as_data_title": true}
         ]
@@ -112,6 +116,7 @@ Apply schema for multiple apps in one call:
       {
         "client_key": "order",
         "app_name": "订单",
+        "icon": {"name": "delivery-box-1", "color": "blue"},
         "add_fields": [
           {"name": "订单编号", "type": "text", "required": true, "as_data_title": true},
           {

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

@@ -19,6 +19,12 @@ Before picking tools, decide which layer the request targets:
 
 If the user asks for multiple forms/modules that relate to each other, this is a package-level multi-app task, not a single-app create.
 
+Use this split consistently:
+
+- Complete system/package: `package_apply` first, then one `app_schema_apply(apps=[...])`.
+- Single app: `app_resolve/app_get` first, then app-scoped apply tools.
+- Record/task/data operation: leave builder and use record/task skills.
+
 ## Resolve
 
 - `package_get`: read one known package by `package_id`; it reads package `baseInfo` first and may warn `PACKAGE_DETAIL_READ_DEGRADED` when the richer detail endpoint needs package edit/add-app permission. Treat that warning as degraded detail, not as package-read failure.
@@ -65,7 +71,7 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Create a brand new package, then create one app in it:
   `package_apply(create_if_missing=true) -> app_schema_apply`
 - Create a brand new multi-app system/package:
-  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`
+  `package_apply(create_if_missing=true) -> app_schema_apply(apps[])`; use `apps[].client_key` plus `target_app_ref`, or `target_app` when referencing by app name
 - Update fields on an existing app:
   `app_resolve -> app_get_fields -> app_schema_apply`
 - Tidy layout:
@@ -97,3 +103,4 @@ For object-level updates, the safe partial syntax is `patch_*` with the object's
 - Do not omit assignees on approval/fill/copy nodes
 - Do not patch preset flows with brand new approval/fill node ids unless you are intentionally replacing the skeleton; reuse preset ids like `approve_1` and `fill_1`
 - Do not guess role ids, member ids, or editable field ids; resolve names first
+- Do not force agent-authored schema into backend-internal names when public aliases exist: icons may use `icon_config` / `icon:{name,color}`, options may use `{label,value}`, and same-call relation targets may use `target_app_ref` / `target_app`.

package/skills/qingflow-task-ops/SKILL.md

@@ -62,7 +62,7 @@ Use one of these two modes:
    2. Discover the exact target with `task_list`
    3. If the target or action requirements are ambiguous, read `task_get`; otherwise go straight to `task_action_execute`
    4. Execute through `task_action_execute`
-   5. After actions, report the exact `app_key`, `record_id`, `workflow_node_id`, executed action, and any warnings
+   5. After actions, report whether it succeeded, the `task_id`, the executed action, the final route/status, and any warnings
 
 ## Task-Center Rules
 
@@ -111,7 +111,7 @@ Use one of these two modes:
 - Do not execute `task_action_execute` until the user explicitly confirms the chosen action
 - Exception: if the user has already explicitly authorized a concrete action on exact targets, you may execute directly after exact target resolution
 - Avoid actions on ambiguous tasks or records
-- Summarize the final action and the exact `app_key / record_id / workflow_node_id`
+- Summarize the final action by `task_id`; include `app_key`, `record_id`, or `workflow_node_id` only as read-only context when the tool returns them, not as the action locator
 - `reject` requires `payload.audit_feedback`
 - For approve/reject, trust the current task detail or an explicit frontend-provided `formId`; app baseInfo is only a fallback. A baseInfo `40002` is not final task-action denial when `formId` is already known.
 - `save_only` requires non-empty `fields` and is only available when the backend exposes editable fields for the current node

package/src/qingflow_mcp/builder_facade/models.py

@@ -2292,6 +2292,8 @@ def _normalize_field_payload(value: Any) -> Any:
     payload = dict(value)
     if "fields" in payload and "subfields" not in payload:
         payload["subfields"] = payload.pop("fields")
+    if "options" in payload:
+        payload["options"] = _normalize_field_options(payload.get("options"))
     raw_type = payload.get("type")
     if isinstance(raw_type, int):
         normalized_from_id = FIELD_TYPE_ID_ALIASES.get(raw_type)
@@ -2324,6 +2326,34 @@ def _normalize_field_payload(value: Any) -> Any:
     return payload
 
 
+def _normalize_field_options(value: Any) -> Any:
+    if not isinstance(value, list):
+        return value
+    normalized: list[str] = []
+    for item in value:
+        if isinstance(item, str):
+            normalized.append(item)
+            continue
+        if isinstance(item, (int, float, bool)):
+            normalized.append(str(item))
+            continue
+        if isinstance(item, dict):
+            label = (
+                item.get("label")
+                or item.get("name")
+                or item.get("title")
+                or item.get("value")
+                or item.get("text")
+                or item.get("optValue")
+                or item.get("optName")
+            )
+            if label is not None:
+                normalized.append(str(label))
+                continue
+        normalized.append(str(item))
+    return normalized
+
+
 def _slugify_title(title: str) -> str:
     normalized = "".join(ch.lower() if ch.isalnum() else "_" for ch in str(title or ""))
     collapsed = "_".join(part for part in normalized.split("_") if part)

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

@@ -4,6 +4,7 @@ import argparse
 
 from ..context import CliContext
 from .common import load_list_arg, load_object_arg, raise_config_error, require_list_arg
+from ..json_io import load_json_value
 
 
 def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
@@ -476,26 +477,30 @@ def _handle_chart_get(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
-    apps = load_list_arg(args.apps_file, option_name="--apps-file")
+    apps_payload = _load_apps_file_arg(args.apps_file)
+    apps = apps_payload["apps"]
+    package_id = args.package_id
+    if package_id is None and apps_payload.get("package_id") is not None:
+        package_id = int(apps_payload["package_id"])
     if args.apps_file:
         if not apps:
             raise_config_error(
                 "schema apply multi-app mode requires a non-empty --apps-file.",
-                fix_hint="Pass a JSON array with at least one app item.",
+                fix_hint="Pass a JSON array, or a JSON object like {\"package_id\":1001,\"apps\":[...]} with at least one app item.",
             )
         if args.app_key or args.app_name or args.app_title or args.add_fields_file or args.update_fields_file or args.remove_fields_file:
             raise_config_error(
                 "schema apply multi-app mode accepts --package-id/--create-if-missing plus --apps-file only.",
                 fix_hint="Use `--apps-file` for batch mode, or remove `--apps-file` and use the single-app arguments.",
             )
-        if args.package_id is None:
+        if package_id is None:
             raise_config_error(
                 "schema apply multi-app mode requires --package-id.",
-                fix_hint="Pass `--package-id` and app names inside --apps-file.",
+                fix_hint="Pass `--package-id`, or put `package_id` at the top level of --apps-file. `package_name` alone does not create the package here; run `builder package apply` first.",
             )
         return context.builder.app_schema_apply(
             profile=args.profile,
-            package_id=args.package_id,
+            package_id=package_id,
             visibility=load_object_arg(args.visibility_file, option_name="--visibility-file"),
             create_if_missing=bool(args.create_if_missing),
             publish=bool(args.publish),
@@ -537,6 +542,29 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
     )
 
 
+def _load_apps_file_arg(path: str | None) -> dict[str, object]:
+    if not path:
+        return {"apps": []}
+    payload = load_json_value(path, option_name="--apps-file")
+    if isinstance(payload, list):
+        return {"apps": payload}
+    if isinstance(payload, dict):
+        apps = payload.get("apps")
+        if not isinstance(apps, list):
+            raise_config_error(
+                "--apps-file JSON object requires an apps array.",
+                fix_hint="Use {\"package_id\":1001,\"apps\":[...]} or pass a raw JSON array.",
+            )
+        result: dict[str, object] = {"apps": apps}
+        if payload.get("package_id") is not None:
+            result["package_id"] = payload.get("package_id")
+        return result
+    raise_config_error(
+        "--apps-file must be a JSON array or an object containing apps.",
+        fix_hint="Use [{...}] or {\"package_id\":1001,\"apps\":[...]}",
+    )
+
+
 def _handle_layout_apply(args: argparse.Namespace, context: CliContext) -> dict:
     return context.builder.app_layout_apply(
         profile=args.profile,

package/src/qingflow_mcp/cli/main.py

@@ -9,6 +9,7 @@ from ..errors import QingflowApiError, backend_code_value_int, message_looks_lik
 from ..public_surface import cli_public_tool_spec_from_namespace
 from ..response_trim import resolve_cli_tool_name, trim_error_response, trim_public_response
 from ..tools.ai_builder_tools import _attach_builder_apply_envelope
+from ..version import get_cli_version
 from .context import CliContext, build_cli_context
 from .formatters import emit_json_result, emit_text_result
 from .commands import register_all_commands
@@ -34,7 +35,10 @@ def build_parser() -> argparse.ArgumentParser:
     parser = _QingflowArgumentParser(prog="qingflow", description="Qingflow CLI")
     parser.add_argument("--profile", default="default", help="会话 profile，默认 default")
     parser.add_argument("--json", action="store_true", help="输出 JSON")
+    parser.add_argument("--version", action="store_true", help="输出 Qingflow CLI 版本")
     subparsers = parser.add_subparsers(dest="command", required=True)
+    version_parser = subparsers.add_parser("version", help="输出 Qingflow CLI 版本")
+    version_parser.set_defaults(handler=_handle_version, format_hint="version")
     register_all_commands(subparsers)
     return parser
 
@@ -54,6 +58,8 @@ def run(
     err = stderr or sys.stderr
     parser = build_parser()
     normalized_argv = _normalize_global_args(list(argv) if argv is not None else sys.argv[1:])
+    if "--version" in normalized_argv:
+        return _emit_version(json_mode=_should_force_json_output_argv_for_version(normalized_argv), stdout=out)
     try:
         args = parser.parse_args(normalized_argv)
     except _CliArgumentError as exc:
@@ -76,6 +82,8 @@ def run(
     setattr(args, "_stdin", sys.stdin)
     setattr(args, "_stdout_stream", out)
     setattr(args, "_stderr_stream", err)
+    if getattr(args, "command", "") == "version":
+        return _emit_version(json_mode=bool(args.json), stdout=out)
     handler = getattr(args, "handler", None)
     if handler is None:
         parser.print_help(out)
@@ -111,6 +119,37 @@ def run(
     return exit_code
 
 
+def _handle_version(_args: argparse.Namespace, _context: CliContext) -> dict[str, Any]:
+    version = get_cli_version()
+    return {
+        "ok": True,
+        "status": "success",
+        "version": version,
+        "package": "@qingflow-tech/qingflow-cli",
+    }
+
+
+def _emit_version(*, json_mode: bool, stdout: TextIO) -> int:
+    version = get_cli_version()
+    if json_mode:
+        emit_json_result(
+            {
+                "ok": True,
+                "status": "success",
+                "version": version,
+                "package": "@qingflow-tech/qingflow-cli",
+            },
+            stream=stdout,
+        )
+    else:
+        stdout.write(f"{version}\n")
+    return 0
+
+
+def _should_force_json_output_argv_for_version(argv: list[str]) -> bool:
+    return "--json" in argv
+
+
 def _normalize_global_args(argv: list[str]) -> list[str]:
     global_args: list[str] = []
     remaining: list[str] = []
@@ -121,6 +160,10 @@ def _normalize_global_args(argv: list[str]) -> list[str]:
             global_args.append(token)
             index += 1
             continue
+        if token == "--version":
+            global_args.append(token)
+            index += 1
+            continue
         if token == "--profile":
             global_args.append(token)
             if index + 1 >= len(argv):

package/src/qingflow_mcp/tools/ai_builder_tools.py

@@ -146,8 +146,11 @@ class AiBuilderTools(ToolBase):
             package_id: int | None = None,
             package_name: str | None = None,
             create_if_missing: bool = False,
-            icon: str | None = None,
+            icon: str | JSONObject | None = None,
             color: str | None = None,
+            icon_name: str | None = None,
+            icon_color: str | None = None,
+            icon_config: JSONObject | None = None,
             visibility: JSONObject | None = None,
             items: list[dict] | None = None,
             allow_detach: bool = False,
@@ -159,6 +162,9 @@ class AiBuilderTools(ToolBase):
                 create_if_missing=create_if_missing,
                 icon=icon,
                 color=color,
+                icon_name=icon_name,
+                icon_color=icon_color,
+                icon_config=icon_config,
                 visibility=visibility,
                 items=items or None,
                 allow_detach=allow_detach,
@@ -364,8 +370,11 @@ class AiBuilderTools(ToolBase):
             package_id: int | None = None,
             app_name: str = "",
             app_title: str = "",
-            icon: str = "",
+            icon: str | JSONObject = "",
             color: str = "",
+            icon_name: str | None = None,
+            icon_color: str | None = None,
+            icon_config: JSONObject | None = None,
             visibility: JSONObject | None = None,
             create_if_missing: bool = False,
             publish: bool = True,
@@ -423,6 +432,9 @@ class AiBuilderTools(ToolBase):
                 app_title=app_title,
                 icon=icon,
                 color=color,
+                icon_name=icon_name,
+                icon_color=icon_color,
+                icon_config=icon_config,
                 visibility=visibility,
                 create_if_missing=create_if_missing,
                 publish=publish,
@@ -733,13 +745,23 @@ class AiBuilderTools(ToolBase):
         package_id: int | None = None,
         package_name: str | None = None,
         create_if_missing: bool = False,
-        icon: str | None = None,
+        icon: str | JSONObject | None = None,
         color: str | None = None,
+        icon_name: str | None = None,
+        icon_color: str | None = None,
+        icon_config: JSONObject | None = None,
         visibility: JSONObject | None = None,
         items: list[dict] | None = None,
         allow_detach: bool = False,
     ) -> JSONObject:
         """执行分组与包相关逻辑。"""
+        icon, color = _normalize_builder_icon_args(
+            icon=icon,
+            color=color,
+            icon_name=icon_name,
+            icon_color=icon_color,
+            icon_config=icon_config,
+        )
         visibility_patch = None
         if visibility is not None:
             try:
@@ -1650,8 +1672,11 @@ class AiBuilderTools(ToolBase):
         package_id: int | None = None,
         app_name: str = "",
         app_title: str = "",
-        icon: str = "",
+        icon: str | JSONObject = "",
         color: str = "",
+        icon_name: str | None = None,
+        icon_color: str | None = None,
+        icon_config: JSONObject | None = None,
         visibility: JSONObject | None = None,
         create_if_missing: bool = False,
         publish: bool = True,
@@ -1661,7 +1686,15 @@ class AiBuilderTools(ToolBase):
         apps: list[JSONObject] | None = None,
     ) -> JSONObject:
         """执行应用相关逻辑。"""
+        icon, color = _normalize_builder_icon_args(
+            icon=icon,
+            color=color,
+            icon_name=icon_name,
+            icon_color=icon_color,
+            icon_config=icon_config,
+        )
         if apps:
+            apps = [_normalize_schema_app_item(item) if isinstance(item, dict) else item for item in apps]
             result = self._app_schema_apply_multi(
                 profile=profile,
                 package_id=package_id,
@@ -1801,6 +1834,7 @@ class AiBuilderTools(ToolBase):
             )
 
         client_key_to_app_key: dict[str, str] = {}
+        app_name_to_app_key: dict[str, str] = {}
         created_app_keys: list[str] = []
         results: list[JSONObject] = []
         any_write_executed = False
@@ -1864,11 +1898,14 @@ class AiBuilderTools(ToolBase):
                 created_app_keys.append(resolved_key)
             if client_key:
                 client_key_to_app_key[client_key] = resolved_key
+            resolved_name = str(public_shell.get("app_name_after") or public_shell.get("app_name") or app_name or "").strip()
+            if resolved_name:
+                app_name_to_app_key[resolved_name] = resolved_key
             results.append({
                 "index": index,
                 "row_number": index + 1,
                 "client_key": client_key or None,
-                "app_name": str(public_shell.get("app_name_after") or public_shell.get("app_name") or app_name or "").strip() or None,
+                "app_name": resolved_name or None,
                 "app_key": resolved_key,
                 "status": "shell_ready",
                 "created": bool(public_shell.get("created")),
@@ -1888,7 +1925,7 @@ class AiBuilderTools(ToolBase):
             item = deepcopy(raw_item)
             app_key = str(existing.get("app_key") or "").strip()
             try:
-                compiled_item = _compile_multi_app_schema_item_refs(item, client_key_to_app_key)
+                compiled_item = _compile_multi_app_schema_item_refs(item, client_key_to_app_key, app_name_to_app_key)
             except ValueError as error:
                 final_items.append({
                     **{key: existing.get(key) for key in ("index", "row_number", "client_key", "app_name", "app_key", "created")},
@@ -2786,8 +2823,58 @@ def _multi_app_item_failure(index: int, item: object, error_code: str, message:
     }
 
 
-def _compile_multi_app_schema_item_refs(item: JSONObject, client_key_to_app_key: dict[str, str]) -> JSONObject:
+def _normalize_builder_icon_args(
+    *,
+    icon: str | JSONObject | None,
+    color: str | None,
+    icon_name: str | None = None,
+    icon_color: str | None = None,
+    icon_config: JSONObject | None = None,
+) -> tuple[str | None, str | None]:
+    payloads: list[JSONObject] = []
+    if isinstance(icon_config, dict):
+        payloads.append(icon_config)
+    if isinstance(icon, dict):
+        payloads.append(icon)
+
+    normalized_icon = None if isinstance(icon, dict) else icon
+    normalized_color = color
+    for payload in payloads:
+        normalized_icon = normalized_icon or payload.get("icon") or payload.get("icon_name") or payload.get("iconName") or payload.get("name")
+        normalized_color = normalized_color or payload.get("color") or payload.get("icon_color") or payload.get("iconColor")
+    normalized_icon = normalized_icon or icon_name
+    normalized_color = normalized_color or icon_color
+    return (
+        str(normalized_icon).strip() if normalized_icon is not None else None,
+        str(normalized_color).strip() if normalized_color is not None else None,
+    )
+
+
+def _normalize_schema_app_item(item: JSONObject) -> JSONObject:
+    normalized = deepcopy(item)
+    icon, color = _normalize_builder_icon_args(
+        icon=normalized.get("icon"),
+        color=normalized.get("color"),
+        icon_name=normalized.get("icon_name") or normalized.get("iconName"),
+        icon_color=normalized.get("icon_color") or normalized.get("iconColor"),
+        icon_config=normalized.get("icon_config") or normalized.get("iconConfig"),
+    )
+    if icon:
+        normalized["icon"] = icon
+    if color:
+        normalized["color"] = color
+    for key in ("icon_name", "iconName", "icon_color", "iconColor", "icon_config", "iconConfig"):
+        normalized.pop(key, None)
+    return normalized
+
+
+def _compile_multi_app_schema_item_refs(
+    item: JSONObject,
+    client_key_to_app_key: dict[str, str],
+    app_name_to_app_key: dict[str, str] | None = None,
+) -> JSONObject:
     compiled = deepcopy(item)
+    app_name_to_app_key = app_name_to_app_key or {}
 
     def visit(value):
         if isinstance(value, list):
@@ -2807,6 +2894,13 @@ def _compile_multi_app_schema_item_refs(item: JSONObject, client_key_to_app_key:
             if not target_app_key:
                 raise ValueError(f"target_app_ref '{ref_key}' did not match any apps[].client_key")
             payload["target_app_key"] = target_app_key
+        target_app = payload.pop("target_app", None) or payload.pop("targetApp", None)
+        if target_app is not None and not str(payload.get("target_app_key") or "").strip():
+            target_name = str(target_app or "").strip()
+            target_app_key = app_name_to_app_key.get(target_name)
+            if not target_app_key:
+                raise ValueError(f"target_app '{target_name}' did not match any apps[].app_name in the same call")
+            payload["target_app_key"] = target_app_key
         return payload
 
     return visit(compiled)
@@ -2855,7 +2949,7 @@ def _contains_multi_app_target_ref(value: object) -> bool:
     if not isinstance(value, dict):
         return False
     for key, entry in value.items():
-        if key in {"target_app_ref", "targetAppRef", "target_app_client_key", "targetAppClientKey"}:
+        if key in {"target_app_ref", "targetAppRef", "target_app_client_key", "targetAppClientKey", "target_app", "targetApp"}:
             return True
         if _contains_multi_app_target_ref(entry):
             return True
@@ -4054,13 +4148,29 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         },
     },
     "package_apply": {
-        "allowed_keys": ["package_id", "package_name", "create_if_missing", "icon", "color", "visibility", "items", "allow_detach"],
+        "allowed_keys": [
+            "package_id",
+            "package_name",
+            "create_if_missing",
+            "icon",
+            "color",
+            "icon_name",
+            "icon_color",
+            "icon_config",
+            "visibility",
+            "items",
+            "allow_detach",
+        ],
         "aliases": {
             "packageId": "package_id",
             "packageName": "package_name",
             "createIfMissing": "create_if_missing",
             "iconName": "icon",
             "iconColor": "color",
+            "icon_config.name": "icon",
+            "icon_config.icon_name": "icon",
+            "icon_config.color": "color",
+            "icon_config.icon_color": "color",
             "allowDetach": "allow_detach",
         },
         "allowed_values": {
@@ -4072,6 +4182,7 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
         "execution_notes": [
             "create or update package metadata, visibility, grouping, and ordering in one call",
             "creating a package requires explicit icon + color; icon=template is blocked because it is too generic",
+            "icon can be passed as icon/color, icon_name/icon_color, icon_config, or icon={name,color}; all forms normalize to icon/color",
             "updating a package preserves existing icon/color when omitted; explicit icon/color values are still validated",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             "metadata keys omitted on update are preserved",
@@ -4575,6 +4686,9 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "app_title",
             "icon",
             "color",
+            "icon_name",
+            "icon_color",
+            "icon_config",
             "visibility",
             "create_if_missing",
             "publish",
@@ -4587,11 +4701,15 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "apps[].app_name",
             "apps[].icon",
             "apps[].color",
+            "apps[].icon_name",
+            "apps[].icon_color",
+            "apps[].icon_config",
             "apps[].visibility",
             "apps[].add_fields",
             "apps[].update_fields",
             "apps[].remove_fields",
             "apps[].add_fields[].target_app_ref",
+            "apps[].add_fields[].target_app",
         ],
         "aliases": {
             "app_title": "app_name",
@@ -4601,8 +4719,16 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "apps[].appKey": "apps[].app_key",
             "apps[].appName": "apps[].app_name",
             "apps[].appTitle": "apps[].app_name",
+            "apps[].iconName": "apps[].icon",
+            "apps[].iconColor": "apps[].color",
+            "apps[].icon_config.name": "apps[].icon",
+            "apps[].icon_config.color": "apps[].color",
             "field.targetAppRef": "field.target_app_ref",
             "field.targetAppClientKey": "field.target_app_ref",
+            "field.targetApp": "field.target_app",
+            "field.options[].label": "field.options[]",
+            "field.options[].value": "field.options[]",
+            "field.options[].optValue": "field.options[]",
             "field.title": "field.name",
             "field.label": "field.name",
             "field.fields": "field.subfields",
@@ -4642,10 +4768,13 @@ _BUILDER_TOOL_CONTRACTS: dict[str, JSONObject] = {
             "create mode follows backend CreateAppBean: package add_app permission is checked on the target package; package edit_app is not required for the create precheck",
             "multi-app mode: pass package_id + create_if_missing + apps[]; do not mix apps with top-level app_key/app_name/add_fields/update_fields/remove_fields",
             "multi-app relation fields may use target_app_ref to point at another apps[].client_key; the tool creates/resolves app shells first and compiles it to target_app_key",
+            "multi-app relation fields may also use target_app with another apps[].app_name; prefer target_app_ref/client_key when names may collide",
             "multi-app mode is not transactional; read created_app_keys and apps[].status before retrying, and retry only failed app items",
             "create mode defaults new app visibility to workspace/not when visibility is omitted; edit mode preserves current visibility when omitted",
             "create mode requires explicit icon + color; icon=template is blocked because it is too generic",
+            "icon can be passed as icon/color, icon_name/icon_color, icon_config, or icon={name,color}; all forms normalize to icon/color",
             "multi-app create mode requires each new app item to include a distinct non-template icon and a valid color",
+            "single_select and multi_select options accept strings or objects such as {label,value}; builder normalizes them to option labels before writing",
             "edit mode preserves existing icon/color when omitted; explicit icon/color values are still validated",
             "call workspace_icon_catalog_get or `qingflow --json builder icon catalog` for supported icon/color candidates",
             *_VISIBILITY_EXECUTION_NOTES,

package/src/qingflow_mcp/version.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+import json
+from importlib import metadata
+from pathlib import Path
+
+
+def get_cli_version() -> str:
+    package_json_version = _find_package_json_version()
+    if package_json_version:
+        return package_json_version
+    try:
+        return metadata.version("qingflow-mcp")
+    except metadata.PackageNotFoundError:
+        return "0+local"
+
+
+def _find_package_json_version() -> str | None:
+    current = Path(__file__).resolve()
+    for parent in current.parents:
+        package_json = parent / "package.json"
+        if not package_json.exists():
+            continue
+        try:
+            payload = json.loads(package_json.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        name = str(payload.get("name") or "")
+        version = str(payload.get("version") or "")
+        if version and name in {
+            "qingflow-mcp-workspace",
+            "@qingflow-tech/qingflow-cli",
+            "@qingflow-tech/qingflow-app-user-mcp",
+            "@qingflow-tech/qingflow-app-builder-mcp",
+            "@josephyan/qingflow-cli",
+            "@josephyan/qingflow-app-user-mcp",
+            "@josephyan/qingflow-app-builder-mcp",
+        }:
+            return version
+    return None