@josephyan/qingflow-cli 0.2.0-beta.76 → 0.2.0-beta.78

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josephyan/qingflow-cli",
-  "version": "0.2.0-beta.76",
+  "version": "0.2.0-beta.78",
   "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.0b76"
+version = "0.2.0b78"
 description = "User-authenticated MCP server for Qingflow"
 readme = "README.md"
 license = "MIT"

package/src/qingflow_mcp/__init__.py

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

package/src/qingflow_mcp/builder_facade/models.py

@@ -291,7 +291,7 @@ class FieldSelector(StrictModel):
 
     @model_validator(mode="after")
     def validate_selector(self) -> "FieldSelector":
-        if not any((self.field_id, self.que_id, self.name)):
+        if self.field_id is None and self.que_id is None and self.name is None:
             raise ValueError("selector must include field_id, que_id, or name")
         return self
 

package/src/qingflow_mcp/builder_facade/service.py

@@ -3530,6 +3530,12 @@ class AiBuilderFacade:
             app_name=str(resolved["app_name"]),
             tag_ids=_coerce_int_list(resolved.get("tag_ids")),
         )
+        requested_app_name = str(app_name or "").strip() or None
+        requested_rename = requested_app_name if app_key else None
+        requested_icon = str(icon or "").strip() or None
+        requested_color = str(color or "").strip() or None
+        requested_app_base_update = bool(requested_rename or requested_icon or requested_color)
+        effective_app_name = target.app_name
         if not bool(resolved.get("created")):
             permission_outcome = self._guard_app_permission(
                 profile=profile,
@@ -3540,21 +3546,35 @@ 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)
+            if requested_app_base_update:
+                visual_result = self._ensure_app_base_visuals(
+                    profile=profile,
+                    app_key=target.app_key,
+                    fallback_title=target.app_name,
+                    app_name=requested_rename,
+                    icon=requested_icon,
+                    color=requested_color,
+                    normalized_args=normalized_args,
+                )
+                if visual_result.get("status") == "failed":
+                    return finalize(visual_result)
+                effective_app_name = str(visual_result.get("app_name_after") or target.app_name).strip() or target.app_name
+            else:
+                visual_result = {
+                    "status": "success",
+                    "updated": False,
+                    "app_icon": None,
+                    "app_name_before": target.app_name,
+                    "app_name_after": target.app_name,
+                    "request_id": None,
+                }
         else:
             visual_result = {
                 "status": "success",
                 "updated": False,
                 "app_icon": str(resolved.get("app_icon") or "").strip() or None,
+                "app_name_before": target.app_name,
+                "app_name_after": target.app_name,
                 "request_id": None,
             }
         if bool(resolved.get("created")) and not requested_field_changes:
@@ -3576,10 +3596,14 @@ class AiBuilderFacade:
                     "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,
+                    "app_base_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,
+                "app_name_before": str(visual_result.get("app_name_before") or target.app_name),
+                "app_name_after": str(visual_result.get("app_name_after") or target.app_name),
+                "app_base_updated": bool(visual_result.get("updated")),
                 "created": True,
                 "field_diff": {"added": [], "updated": [], "removed": []},
                 "verified": True,
@@ -3602,7 +3626,7 @@ class AiBuilderFacade:
                     details=_with_state_read_blocked_details({"app_key": target.app_key}, resource="schema", error=api_error),
                     suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": target.app_key}},
                 ))
-            schema_result = _empty_schema_result(target.app_name)
+            schema_result = _empty_schema_result(effective_app_name)
             _schema_source = "synthetic_new_app"
             schema_readback_delayed = True
         parsed = _parse_schema(schema_result)
@@ -3759,13 +3783,19 @@ class AiBuilderFacade:
         )
 
         if not added and not updated and not removed and not normalized_code_block_fields and not bool(resolved.get("created")):
-            tag_ids_after = _coerce_int_list((self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}).get("tagIds"))
+            base_info = self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}
+            tag_ids_after = _coerce_int_list(base_info.get("tagIds"))
             package_attached = None if package_tag_id is None else package_tag_id in tag_ids_after
+            actual_app_name = str(base_info.get("formTitle") or effective_app_name).strip() or effective_app_name
+            actual_app_icon = str(base_info.get("appIcon") or visual_result.get("app_icon") or "").strip() or None
+            expected_app_icon = str(visual_result.get("app_icon") or "").strip() or None
+            app_base_verified = actual_app_name == effective_app_name and actual_app_icon == expected_app_icon
+            verified = app_base_verified and relation_target_metadata_verified
             response = {
-                "status": "success",
-                "error_code": None,
-                "recoverable": False,
-                "message": "updated app visuals; schema already matches requested state" if bool(visual_result.get("updated")) else "schema already matches requested state",
+                "status": "success" if verified else "partial_success",
+                "error_code": None if verified else "APP_BASE_READBACK_PENDING",
+                "recoverable": not verified,
+                "message": "updated app base metadata; 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]},
@@ -3777,14 +3807,18 @@ class AiBuilderFacade:
                 "verification": {
                     "fields_verified": True,
                     "relation_field_limit_verified": relation_limit_verified,
-                    "app_visuals_verified": True,
+                    "app_visuals_verified": app_base_verified,
+                    "app_base_verified": app_base_verified,
                     "relation_target_metadata_verified": relation_target_metadata_verified,
                 },
                 "app_key": target.app_key,
                 "app_icon": str(visual_result.get("app_icon") or "").strip() or None,
+                "app_name_before": str(visual_result.get("app_name_before") or target.app_name),
+                "app_name_after": effective_app_name,
+                "app_base_updated": bool(visual_result.get("updated")),
                 "created": False,
                 "field_diff": {"added": [], "updated": [], "removed": []},
-                "verified": True,
+                "verified": verified,
                 "tag_ids_after": tag_ids_after,
                 "package_attached": package_attached,
             }
@@ -3796,7 +3830,7 @@ class AiBuilderFacade:
             return finalize(self._append_publish_result(profile=profile, app_key=target.app_key, publish=publish, response=response))
 
         payload = _build_form_payload_from_fields(
-            title=schema_result.get("formTitle") or target.app_name,
+            title=effective_app_name,
             current_schema=schema_result,
             fields=current_fields,
             layout=layout,
@@ -3904,7 +3938,7 @@ class AiBuilderFacade:
                     suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": target.app_key}},
                 )
             rebound_payload = _build_form_payload_from_fields(
-                title=rebound_schema.get("formTitle") or target.app_name,
+                title=effective_app_name,
                 current_schema=rebound_schema,
                 fields=rebound_fields,
                 layout=rebound_layout,
@@ -3948,11 +3982,15 @@ class AiBuilderFacade:
                 "fields_verified": False,
                 "package_attached": None,
                 "app_visuals_verified": True,
+                "app_base_verified": True,
                 "relation_field_limit_verified": relation_limit_verified,
                 "relation_target_metadata_verified": relation_target_metadata_verified,
             },
             "app_key": target.app_key,
             "app_icon": str(visual_result.get("app_icon") or resolved.get("app_icon") or "").strip() or None,
+            "app_name_before": str(visual_result.get("app_name_before") or target.app_name),
+            "app_name_after": effective_app_name,
+            "app_base_updated": bool(visual_result.get("updated")),
             "created": bool(resolved.get("created")),
             "field_diff": {
                 "added": added,
@@ -3999,16 +4037,23 @@ class AiBuilderFacade:
             base_info = self.apps.app_get_base(profile=profile, app_key=target.app_key, include_raw=True).get("result") or {}
             tag_ids_after = _coerce_int_list(base_info.get("tagIds"))
             package_attached = None if package_tag_id is None else package_tag_id in tag_ids_after
+            actual_app_name = str(base_info.get("formTitle") or effective_app_name).strip() or effective_app_name
+            actual_app_icon = str(base_info.get("appIcon") or visual_result.get("app_icon") or "").strip() or None
+            expected_app_icon = str(visual_result.get("app_icon") or "").strip() or None
+            app_base_verified = actual_app_name == effective_app_name and actual_app_icon == expected_app_icon
         except (QingflowApiError, RuntimeError) as error:
             base_error = _coerce_api_error(error)
             if verification_error is None:
                 verification_error = base_error
             tag_ids_after = []
             package_attached = None if package_tag_id is None else False
+            app_base_verified = False
         response["verification"]["fields_verified"] = verification_ok
         response["verification"]["package_attached"] = package_attached
+        response["verification"]["app_visuals_verified"] = app_base_verified
+        response["verification"]["app_base_verified"] = app_base_verified
         response["verification"]["relation_field_limit_verified"] = relation_limit_verified
-        response["verified"] = verification_ok
+        response["verified"] = verification_ok and app_base_verified
         response["tag_ids_after"] = tag_ids_after
         response["package_attached"] = package_attached
         if package_attached is False:
@@ -4018,14 +4063,18 @@ class AiBuilderFacade:
                     "profile": profile,
                     "tag_id": package_tag_id,
                     "app_key": target.app_key,
-                    "app_title": app_name or target.app_name,
+                    "app_title": effective_app_name,
                 },
             }
         publish_failed = bool(response.get("publish_requested")) and not bool(response.get("published"))
-        if verification_ok and package_attached is not False and not publish_failed:
+        if verification_ok and app_base_verified and package_attached is not False and not publish_failed:
             response["status"] = "success"
         else:
             response["status"] = "partial_success"
+        if not app_base_verified and verification_error is None:
+            response["recoverable"] = True
+            response["error_code"] = response.get("error_code") or "APP_BASE_READBACK_PENDING"
+            response["message"] = f"{response.get('message') or 'apply succeeded'}; app base readback pending"
         if verification_error is not None:
             response["recoverable"] = True
             response["error_code"] = response.get("error_code") or (
@@ -6535,17 +6584,11 @@ class AiBuilderFacade:
         profile: str,
         app_key: str,
         fallback_title: str,
+        app_name: str | None,
         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:
@@ -6559,22 +6602,25 @@ class AiBuilderFacade:
             )
         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 "未命名应用"
+        desired_title = str(app_name or effective_title).strip() or effective_title
         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,
+            title=desired_title,
             fallback_icon_name="template",
             existing_icon=existing_icon,
         )
-        if desired_icon == existing_icon:
+        if desired_icon == existing_icon and desired_title == effective_title:
             return {
                 "status": "success",
                 "updated": False,
-                "app_icon": desired_icon,
+                "app_icon": desired_icon or existing_icon,
+                "app_name_before": effective_title,
+                "app_name_after": desired_title,
                 "request_id": None,
             }
-        payload = self._build_app_base_update_payload(raw_base=raw_base, form_title=effective_title, app_icon=desired_icon)
+        payload = self._build_app_base_update_payload(raw_base=raw_base, form_title=desired_title, app_icon=desired_icon)
         if payload is None:
             return _failed(
                 "APP_VISUAL_UPDATE_UNSUPPORTED",
@@ -6598,6 +6644,8 @@ class AiBuilderFacade:
             "status": "success",
             "updated": True,
             "app_icon": desired_icon,
+            "app_name_before": effective_title,
+            "app_name_after": desired_title,
             "request_id": update_result.get("request_id") if isinstance(update_result, dict) else None,
         }
 
@@ -8455,6 +8503,8 @@ def _hydrate_relation_field_configs(
     for field in resolved_fields:
         if not isinstance(field, dict) or field.get("type") != FieldType.relation.value:
             continue
+        if not bool(field.get("_relation_config_explicit")) and isinstance(field.get("_reference_config_template"), dict):
+            continue
         target_app_key = str(field.get("target_app_key") or "").strip()
         if not target_app_key:
             continue
@@ -8613,13 +8663,13 @@ def _parse_field(question: dict[str, Any], *, field_id_hint: str | None = None)
         field["relation_mode"] = _relation_mode_from_optional_data_num(reference.get("optionalDataNum"))
         refer_questions = reference.get("referQuestions") if isinstance(reference.get("referQuestions"), list) else []
         visible_fields: list[dict[str, Any]] = []
-        display_field_que_id = _coerce_positive_int(reference.get("referQueId"))
+        display_field_que_id = _coerce_nonnegative_int(reference.get("referQueId"))
         display_field_name: str | None = None
         for item in refer_questions:
             if not isinstance(item, dict):
                 continue
             selector = {
-                "que_id": _coerce_positive_int(item.get("queId")),
+                "que_id": _coerce_nonnegative_int(item.get("queId")),
                 "name": str(item.get("queTitle") or "").strip() or None,
             }
             visible_fields.append(selector)
@@ -8634,6 +8684,8 @@ def _parse_field(question: dict[str, Any], *, field_id_hint: str | None = None)
         }
         field["visible_fields"] = visible_fields
         field["field_name_show"] = bool(reference.get("fieldNameShow", True))
+        field["_reference_config_template"] = deepcopy(reference)
+        field["_relation_config_explicit"] = False
     if field_type == FieldType.department:
         department_scope = _normalize_department_scope_from_question(question)
         if department_scope is not None:
@@ -9293,7 +9345,7 @@ def _build_selector_map(fields: list[dict[str, Any]]) -> dict[str, int]:
     for index, field in enumerate(fields):
         field_id = str(field.get("field_id") or "")
         field_name = str(field.get("name") or "")
-        que_id = _coerce_positive_int(field.get("que_id"))
+        que_id = _coerce_nonnegative_int(field.get("que_id"))
         if field_id:
             mapping[f"field_id:{field_id}"] = index
         if field_name:
@@ -9308,7 +9360,7 @@ def _resolve_selector(selector_map: dict[str, int], selector: FieldSelector) ->
         value = selector_map.get(f"field_id:{selector.field_id}")
         if value is not None:
             return value
-    if selector.que_id:
+    if selector.que_id is not None:
         value = selector_map.get(f"que_id:{selector.que_id}")
         if value is not None:
             return value
@@ -9356,6 +9408,7 @@ def _field_patch_to_internal(patch: FieldPatch) -> dict[str, Any]:
         "que_id": None,
         "default_type": 1,
         "default_value": None,
+        "_relation_config_explicit": patch.type == PublicFieldType.relation,
     }
 
 
@@ -9426,7 +9479,7 @@ def _field_selector_payload_equal(left: Any, right: Any) -> bool:
         return False
     return (
         str(left.get("field_id") or "") == str(right.get("field_id") or "")
-        and _coerce_positive_int(left.get("que_id")) == _coerce_positive_int(right.get("que_id"))
+        and _coerce_nonnegative_int(left.get("que_id")) == _coerce_nonnegative_int(right.get("que_id"))
         and str(left.get("name") or "") == str(right.get("name") or "")
     )
 
@@ -9581,6 +9634,10 @@ def _code_block_binding_equal(left: Any, right: Any) -> bool:
 
 def _apply_field_mutation(field: dict[str, Any], mutation: Any) -> None:
     payload = mutation.model_dump(mode="json", exclude_none=True)
+    relation_config_explicit = (
+        payload.get("type") == FieldType.relation.value
+        or any(key in payload for key in ("target_app_key", "display_field", "visible_fields", "relation_mode"))
+    )
     if "name" in payload:
         field["name"] = payload["name"]
     if "type" in payload:
@@ -9623,6 +9680,11 @@ def _apply_field_mutation(field: dict[str, Any], mutation: Any) -> None:
         field["custom_button_text"] = payload["custom_button_text"]
     if "subfields" in payload:
         field["subfields"] = [_field_patch_to_internal(item) for item in payload["subfields"]]
+    if relation_config_explicit:
+        field["_relation_config_explicit"] = True
+    elif payload.get("type") and payload.get("type") != FieldType.relation.value:
+        field.pop("_relation_config_explicit", None)
+        field.pop("_reference_config_template", None)
 
 
 def _resolve_field_selector_with_uniqueness(
@@ -9634,8 +9696,8 @@ def _resolve_field_selector_with_uniqueness(
     selector = FieldSelector.model_validate(selector_payload)
     if selector.field_id:
         matched = [field for field in fields if str(field.get("field_id") or "") == str(selector.field_id)]
-    elif selector.que_id:
-        matched = [field for field in fields if _coerce_positive_int(field.get("que_id")) == _coerce_positive_int(selector.que_id)]
+    elif selector.que_id is not None:
+        matched = [field for field in fields if _coerce_nonnegative_int(field.get("que_id")) == _coerce_nonnegative_int(selector.que_id)]
     elif selector.name:
         name = str(selector.name or "").strip()
         matched = [field for field in fields if str(field.get("name") or "").strip() == name]
@@ -11094,7 +11156,7 @@ def _field_to_question(field: dict[str, Any], *, temp_id: int) -> dict[str, Any]
         },
         temp_id,
     )
-    if field.get("que_id"):
+    if _coerce_nonnegative_int(field.get("que_id")) is not None:
         question["queId"] = field["que_id"]
     else:
         question["queTempId"] = temp_id
@@ -11104,13 +11166,23 @@ def _field_to_question(field: dict[str, Any], *, temp_id: int) -> dict[str, Any]
     if "default_value" in field:
         question["queDefaultValue"] = field.get("default_value")
     if field.get("type") == FieldType.relation.value:
-        reference = question.get("referenceConfig") if isinstance(question.get("referenceConfig"), dict) else {}
-        reference["referAppKey"] = field.get("target_app_key")
-        reference["_targetEntityId"] = field.get("target_app_key")
-        if field.get("target_field_que_id"):
-            reference["referQueId"] = field.get("target_field_que_id")
-        reference["optionalDataNum"] = _relation_mode_to_optional_data_num(field.get("relation_mode"))
-        question["referenceConfig"] = reference
+        preserved_reference = (
+            deepcopy(field.get("_reference_config_template"))
+            if not bool(field.get("_relation_config_explicit")) and isinstance(field.get("_reference_config_template"), dict)
+            else None
+        )
+        if preserved_reference is not None:
+            preserved_reference["referAppKey"] = field.get("target_app_key")
+            preserved_reference["_targetEntityId"] = field.get("target_app_key")
+            question["referenceConfig"] = preserved_reference
+        else:
+            reference = question.get("referenceConfig") if isinstance(question.get("referenceConfig"), dict) else {}
+            reference["referAppKey"] = field.get("target_app_key")
+            reference["_targetEntityId"] = field.get("target_app_key")
+            if field.get("target_field_que_id") is not None:
+                reference["referQueId"] = field.get("target_field_que_id")
+            reference["optionalDataNum"] = _relation_mode_to_optional_data_num(field.get("relation_mode"))
+            question["referenceConfig"] = reference
     if field.get("type") == FieldType.department.value:
         scope_type, scope_payload = _serialize_department_scope_for_question(field.get("department_scope"))
         question["deptSelectScopeType"] = scope_type

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

@@ -458,13 +458,13 @@ def _handle_schema_apply(args: argparse.Namespace, context: CliContext) -> dict:
     has_app_title = bool((args.app_title or "").strip())
     has_package_tag_id = args.package_tag_id is not None
     if has_app_key:
-        if args.create_if_missing or has_app_name or has_package_tag_id or has_app_title:
+        if args.create_if_missing or has_package_tag_id:
             raise_config_error(
-                "schema apply edit mode only accepts --app-key as the resource selector.",
-                fix_hint="For existing apps, pass `--app-key` only. For create mode, use `--package-tag-id --app-name --create-if-missing`.",
+                "schema apply edit mode accepts --app-key and optional --app-name only.",
+                fix_hint="For existing apps, use `--app-key` and optionally `--app-name`. For create mode, use `--package-tag-id --app-name --create-if-missing`.",
             )
     else:
-        if not args.create_if_missing or not has_package_tag_id or not has_app_name:
+        if not args.create_if_missing or not has_package_tag_id or not (has_app_name or has_app_title):
             raise_config_error(
                 "schema apply create mode requires --package-tag-id, --app-name, and --create-if-missing.",
                 fix_hint="Use `--app-key` for existing apps, or pass `--package-tag-id --app-name --create-if-missing` to create a new app.",

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

@@ -73,8 +73,10 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
 
     update = record_subparsers.add_parser("update", help="更新记录")
     update.add_argument("--app-key", required=True)
-    update.add_argument("--record-id", required=True, type=int)
-    update.add_argument("--fields-file", required=True)
+    update.add_argument("--record-id", type=int)
+    update.add_argument("--fields-file")
+    update.add_argument("--items-file")
+    update.add_argument("--dry-run", action=argparse.BooleanOptionalAction, default=False)
     update.add_argument("--verify-write", action=argparse.BooleanOptionalAction, default=True)
     update.set_defaults(handler=_handle_update, format_hint="")
 
@@ -242,6 +244,31 @@ def _handle_insert(args: argparse.Namespace, context: CliContext) -> dict:
 
 
 def _handle_update(args: argparse.Namespace, context: CliContext) -> dict:
+    if args.items_file:
+        if args.record_id is not None or args.fields_file:
+            raise_config_error(
+                "record update batch mode does not accept --record-id or --fields-file.",
+                fix_hint="Use `record update --app-key APP_KEY --items-file ITEMS.json [--dry-run]` for batch updates.",
+            )
+        return context.record.record_update_public(
+            profile=args.profile,
+            app_key=args.app_key,
+            record_id=None,
+            fields=None,
+            items=require_list_arg(args.items_file, option_name="--items-file"),
+            dry_run=bool(args.dry_run),
+            verify_write=bool(args.verify_write),
+        )
+    if args.dry_run:
+        raise_config_error(
+            "record update --dry-run currently requires --items-file.",
+            fix_hint="Use `record update --app-key APP_KEY --items-file ITEMS.json --dry-run` for batch preflight.",
+        )
+    if args.record_id is None or not args.fields_file:
+        raise_config_error(
+            "record update single mode requires --record-id and --fields-file.",
+            fix_hint="Use `record update --app-key APP_KEY --record-id RECORD_ID --fields-file FIELDS.json`.",
+        )
     return context.record.record_update_public(
         profile=args.profile,
         app_key=args.app_key,

package/src/qingflow_mcp/cli/main.py

@@ -6,6 +6,7 @@ import sys
 from typing import Any, Callable, TextIO
 
 from ..errors import QingflowApiError
+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 .context import CliContext, build_cli_context
 from .formatters import emit_json_result, emit_text_result
@@ -49,6 +50,8 @@ def run(
         return 2
     context = context_factory()
     try:
+        if not bool(args.json):
+            _emit_cli_effective_context_notice(args, context, stream=err)
         result = handler(args, context)
     except RuntimeError as exc:
         payload = trim_error_response(_parse_error_payload(exc))
@@ -145,5 +148,31 @@ def _result_exit_code(result: dict[str, Any]) -> int:
     return 0
 
 
+def _emit_cli_effective_context_notice(args: argparse.Namespace, context: CliContext, *, stream: TextIO) -> None:
+    spec = cli_public_tool_spec_from_namespace(args)
+    if spec is None or not spec.cli_show_effective_context:
+        return
+    sessions = getattr(context, "sessions", None)
+    if sessions is None or not hasattr(sessions, "get_profile"):
+        return
+    profile_name = str(getattr(args, "profile", "default") or "default")
+    try:
+        session_profile = sessions.get_profile(profile_name)
+    except Exception:
+        session_profile = None
+    workspace_id = getattr(session_profile, "selected_ws_id", None) if session_profile is not None else None
+    workspace_name = getattr(session_profile, "selected_ws_name", None) if session_profile is not None else None
+    if workspace_id is None:
+        workspace_label = "(not selected)"
+    elif workspace_name:
+        workspace_label = f"{workspace_name} ({workspace_id})"
+    else:
+        workspace_label = str(workspace_id)
+    lines = [f"Context: profile={profile_name} workspace={workspace_label}"]
+    if spec.cli_context_write and profile_name == "default":
+        lines.append("Warning: using default profile for a workspace-sensitive write command")
+    stream.write("\n".join(lines) + "\n")
+
+
 if __name__ == "__main__":
     main()