@qingflow-tech/qingflow-cli 1.1.50-beta.3 → 1.1.50-beta.5

package/src/qingflow_mcp/builder_facade/service.py

@@ -163,9 +163,14 @@ FIELD_TYPE_TO_QUESTION_TYPE: dict[str, int] = {
     FieldType.relation.value: 25,
 }
 
+# code_block / q_linker 输出目标字段类型。后端写链无类型白名单(FormSvcImpl 原样
+# 落库),运行时 DataSvcImpl.getAnswerValueByString:attachment 按拆分 URL 写入、
+# subtable 整表组装(均有专门分支),rich_text/data_relation 走 Question.canImport
+# 兜底按字符串写入(不报错)——四者为存量合法配置,与 validator 侧白名单同口径。
 INTEGRATION_OUTPUT_TARGET_FIELD_TYPES: tuple[str, ...] = (
     FieldType.text.value,
     FieldType.long_text.value,
+    "rich_text",
     FieldType.number.value,
     FieldType.amount.value,
     FieldType.date.value,
@@ -173,6 +178,9 @@ INTEGRATION_OUTPUT_TARGET_FIELD_TYPES: tuple[str, ...] = (
     FieldType.single_select.value,
     FieldType.multi_select.value,
     FieldType.boolean.value,
+    FieldType.attachment.value,
+    "data_relation",
+    FieldType.subtable.value,
 )
 
 MATCH_TYPE_ACCURACY = 1
@@ -3925,7 +3933,7 @@ class AiBuilderFacade:
                         "reason_path": f"patch_buttons[{index}].button_id",
                         "button_id": selector_id,
                         "message": "button_id does not exist in the current app draft",
-                        "next_action": "call app_get and use custom_buttons[].button_id",
+                        "next_action": "call app_get_buttons with button_text to reuse an existing custom button; create only if absent via app_custom_buttons_apply",
                     }
                     issues.append(issue)
                     results.append({"index": index, "status": "failed", **issue})
@@ -4229,7 +4237,7 @@ class AiBuilderFacade:
                             "reason_path": f"upsert_buttons[{index}].button_id",
                             "button_id": button_id,
                             "message": "button_id does not exist in the current app draft",
-                            "next_action": "call app_get and use custom_buttons[].button_id",
+                            "next_action": "call app_get_buttons with button_text to reuse an existing custom button; create only if absent via app_custom_buttons_apply",
                         }
                     )
                     continue
@@ -4300,7 +4308,7 @@ class AiBuilderFacade:
                             "reason_path": f"remove_buttons[{index}].button_id",
                             "button_id": selector_id,
                             "message": "button_id does not exist in the current app draft",
-                            "next_action": "call app_get and use custom_buttons[].button_id",
+                            "next_action": "call app_get_buttons with button_text to reuse an existing custom button; create only if absent via app_custom_buttons_apply",
                         }
                     )
                     continue
@@ -7173,10 +7181,14 @@ class AiBuilderFacade:
         fields = cast(list[dict[str, Any]], state["parsed"]["fields"])
         return _chart_field_names_by_id_from_public_fields(app_key=app_key, fields=fields), None
 
-    def app_get_buttons(self, *, profile: str, app_key: str) -> JSONObject:
+    def app_get_buttons(self, *, profile: str, app_key: str, button_text: str | None = None) -> JSONObject:
         self.apps._require_app_key(app_key)
         warnings: list[dict[str, Any]] = []
         verification: dict[str, Any] = {"buttons_loaded": True, "view_configs_loaded": True}
+        normalized_text = str(button_text or "").strip() or None
+        normalized_args: dict[str, Any] = {"app_key": app_key}
+        if normalized_text is not None:
+            normalized_args["button_text"] = normalized_text
         try:
             raw = self.buttons.custom_button_list(profile=profile, app_key=app_key, being_draft=True)
         except (QingflowApiError, RuntimeError) as error:
@@ -7184,11 +7196,18 @@ class AiBuilderFacade:
             return _failed_from_api_error(
                 "BUTTONS_READ_FAILED",
                 api_error,
-                normalized_args={"app_key": app_key},
+                normalized_args=normalized_args,
                 details={"app_key": app_key},
                 suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
             )
         buttons = raw.get("items") if isinstance(raw.get("items"), list) else []
+        total_count = len(buttons)
+        if normalized_text is not None:
+            buttons = [
+                item
+                for item in buttons
+                if isinstance(item, dict) and str(item.get("buttonText") or item.get("button_text") or "").strip() == normalized_text
+            ]
         view_configs: list[dict[str, Any]] = []
         view_config_read_errors: list[dict[str, Any]] = []
         try:
@@ -7208,7 +7227,7 @@ class AiBuilderFacade:
         if view_config_read_errors:
             verification["view_configs_loaded"] = False
             warnings.append(_warning("BUTTON_VIEW_CONFIGS_PARTIAL", "some view button binding configs could not be read back"))
-        return {
+        response: JSONObject = {
             "status": "success",
             "error_code": None,
             "recoverable": False,
@@ -7223,6 +7242,11 @@ class AiBuilderFacade:
             "verification": verification,
             "details": {"view_config_read_errors": view_config_read_errors} if view_config_read_errors else {},
         }
+        if normalized_text is not None:
+            response["button_text_filter"] = normalized_text
+            response["total_count"] = total_count
+            verification["button_text_exact_match"] = True
+        return response
 
     def app_get_associated_resources(self, *, profile: str, app_key: str) -> JSONObject:
         self.apps._require_app_key(app_key)
@@ -9507,6 +9531,7 @@ class AiBuilderFacade:
                         "view_name": patch.get("name"),
                     }
                     for issue in filter_issues
+                    if issue.get("error_code")
                 )
             if translated_filters:
                 patch["filters"] = [dict(rule) for rule in (patch.get("filters") or [])]
@@ -12406,6 +12431,7 @@ class AiBuilderFacade:
             and _extract_view_name(view) not in removed
             and _extract_view_key(view) not in removed_keys
         ]
+        stale_warnings: list[dict[str, Any]] = []
         for ordinal, patch in ((1, upsert_views[0]),) if operation == "upsert" and upsert_views else ():
             apply_columns = _resolve_view_visible_que_ids(patch)
             if patch.type in {PublicViewType.table, PublicViewType.card} and patch.columns and not apply_columns:
@@ -12415,65 +12441,37 @@ class AiBuilderFacade:
                     normalized_args=normalized_args,
                     details={"app_key": app_key, "view_name": patch.name},
                 )
+            # 死引用(字段已从表单删除,后端保存视图时原样透传)降级为警告透传,不再整视图拒绝
             missing_columns = [
                 que for que in apply_columns
                 if not _is_known_system_view_que_id(que) and que not in fields_by_que_id
             ]
             if missing_columns:
-                return _failed(
-                    "UNKNOWN_VIEW_FIELD",
-                    "view columns reference unknown fields",
-                    normalized_args=normalized_args,
-                    details={
-                        "app_key": app_key,
-                        "view_name": patch.name,
-                        "missing_fields": missing_columns,
-                    },
-                    missing_fields=missing_columns,
-                    suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
+                stale_warnings.append(
+                    _stale_view_reference_warning(scope="columns", view_name=patch.name, field_ids=missing_columns)
                 )
             if patch.group_que_id and patch.group_que_id not in fields_by_que_id:
-                return _failed(
-                    "UNKNOWN_VIEW_FIELD",
-                    f"group_by references unknown field '{patch.group_que_id}'",
-                    normalized_args=normalized_args,
-                    details={
-                        "app_key": app_key,
-                        "view_name": patch.name,
-                        "missing_fields": [patch.group_que_id],
-                    },
-                    missing_fields=[patch.group_que_id],
-                    suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
+                stale_warnings.append(
+                    _stale_view_reference_warning(scope="group_que_id", view_name=patch.name, field_ids=[patch.group_que_id])
                 )
-            for gantt_que_id in (patch.start_que_id, patch.end_que_id, patch.title_que_id):
-                if gantt_que_id and gantt_que_id not in fields_by_que_id:
-                    return _failed(
-                        "UNKNOWN_VIEW_FIELD",
-                        f"gantt configuration references unknown field '{gantt_que_id}'",
-                        normalized_args=normalized_args,
-                        details={
-                            "app_key": app_key,
-                            "view_name": patch.name,
-                            "missing_fields": [gantt_que_id],
-                        },
-                        missing_fields=[gantt_que_id],
-                        suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
+            for ref_scope, ref_que_id in (
+                ("gantt.start_que_id", patch.start_que_id),
+                ("gantt.end_que_id", patch.end_que_id),
+                ("title_que_id", patch.title_que_id),
+            ):
+                # 系统字段(提交人/提交时间等)可作标题/时间轴;业务字段死引用仅警告透传
+                if ref_que_id and not _is_known_system_view_que_id(ref_que_id) and ref_que_id not in fields_by_que_id:
+                    stale_warnings.append(
+                        _stale_view_reference_warning(scope=ref_scope, view_name=patch.name, field_ids=[ref_que_id])
                     )
             for group_name, config_que_ids in _iter_view_config_group_field_names(patch):
-                missing_config_fields = [que for que in config_que_ids if que not in fields_by_que_id]
+                missing_config_fields = [
+                    que for que in config_que_ids
+                    if que not in fields_by_que_id and not _is_known_system_view_que_id(que)
+                ]
                 if missing_config_fields:
-                    return _failed(
-                        "UNKNOWN_VIEW_FIELD",
-                        f"view {group_name} configuration references unknown fields",
-                        normalized_args=normalized_args,
-                        details={
-                            "app_key": app_key,
-                            "view_name": patch.name,
-                            "missing_fields": missing_config_fields,
-                            "reason_path": f"{group_name}",
-                        },
-                        missing_fields=missing_config_fields,
-                        suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
+                    stale_warnings.append(
+                        _stale_view_reference_warning(scope=group_name, view_name=patch.name, field_ids=missing_config_fields)
                     )
             hierarchy_root_filter_groups: list[list[dict[str, Any]]] | None = None
             if patch.hierarchy is not None and patch.hierarchy.root_filter:
@@ -12483,8 +12481,19 @@ class AiBuilderFacade:
                         fields_by_que_id=fields_by_que_id,
                         filters=root_filter_group,
                     )
-                    if hierarchy_filter_issues:
-                        first_issue = hierarchy_filter_issues[0]
+                    for issue in hierarchy_filter_issues:
+                        if issue.get("warning_code") == "STALE_OPTION_REFERENCE":
+                            stale_warnings.append(
+                                _stale_view_reference_warning(
+                                    scope="hierarchy.root_filter",
+                                    view_name=patch.name,
+                                    values=issue.get("details", {}).get("unresolved_values") or [],
+                                    option=True,
+                                )
+                            )
+                    hierarchy_filter_errors = [issue for issue in hierarchy_filter_issues if issue.get("error_code")]
+                    if hierarchy_filter_errors:
+                        first_issue = hierarchy_filter_errors[0]
                         return _failed(
                             str(first_issue.get("error_code") or "UNKNOWN_VIEW_FIELD"),
                             "view hierarchy root_filter references invalid fields or values",
@@ -12512,20 +12521,32 @@ class AiBuilderFacade:
             else:
                 translated_filters, filter_issues = _build_view_filter_groups(fields_by_que_id=fields_by_que_id, filters=patch.filters)
             if filter_issues:
-                first_issue = filter_issues[0]
-                return _failed(
-                    str(first_issue.get("error_code") or "UNKNOWN_VIEW_FIELD"),
-                    "view filters reference invalid fields or values",
-                    normalized_args=normalized_args,
-                    details={
-                        "app_key": app_key,
-                        "view_name": patch.name,
-                        **first_issue,
-                    },
-                    missing_fields=list(first_issue.get("missing_fields") or []),
-                    allowed_values=first_issue.get("allowed_values") or {"view_types": [member.value for member in PublicViewType], "view.filter.operator": [member.value for member in ViewFilterOperator]},
-                    suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
-                )
+                for issue in filter_issues:
+                    if issue.get("warning_code") == "STALE_OPTION_REFERENCE":
+                        stale_warnings.append(
+                            _stale_view_reference_warning(
+                                scope="filters",
+                                view_name=patch.name,
+                                values=issue.get("details", {}).get("unresolved_values") or [],
+                                option=True,
+                            )
+                        )
+                filter_errors = [issue for issue in filter_issues if issue.get("error_code")]
+                if filter_errors:
+                    first_issue = filter_errors[0]
+                    return _failed(
+                        str(first_issue.get("error_code") or "UNKNOWN_VIEW_FIELD"),
+                        "view filters reference invalid fields or values",
+                        normalized_args=normalized_args,
+                        details={
+                            "app_key": app_key,
+                            "view_name": patch.name,
+                            **first_issue,
+                        },
+                        missing_fields=list(first_issue.get("missing_fields") or []),
+                        allowed_values=first_issue.get("allowed_values") or {"view_types": [member.value for member in PublicViewType], "view.filter.operator": [member.value for member in ViewFilterOperator]},
+                        suggested_next_call={"tool_name": "app_get_fields", "arguments": {"profile": profile, "app_key": app_key}},
+                    )
             if patch.preserve_query_conditions:
                 query_condition_payload = None
                 expected_query_conditions = None
@@ -12606,7 +12627,10 @@ class AiBuilderFacade:
                         },
                         missing_fields=list(first_issue.get("missing_fields") or []),
                         allowed_values=first_issue.get("allowed_values") or {"view_types": [member.value for member in PublicViewType], "view.filter.operator": [member.value for member in ViewFilterOperator]},
-                        suggested_next_call={"tool_name": "app_get", "arguments": {"profile": profile, "app_key": app_key}},
+                        suggested_next_call={
+                            "tool_name": "app_get_buttons",
+                            "arguments": {"profile": profile, "app_key": app_key},
+                        },
                     )
                 expected_button_summary = _normalize_expected_view_buttons_for_compare(
                     explicit_button_dtos or [],
@@ -13509,7 +13533,8 @@ class AiBuilderFacade:
                 "http_status": first_failure.get("http_status"),
                 "noop": noop,
                 "warnings": (
-                    (
+                    list(stale_warnings)
+                    + (
                         [_warning("VIEW_FILTERS_UNVERIFIED", "view definitions may exist, but saved filter behavior is not fully verified")]
                         if (filter_readback_pending or filter_mismatches)
                         else []
@@ -13564,6 +13589,7 @@ class AiBuilderFacade:
             }
             return finish_with_publish(response)
         warnings: list[dict[str, Any]] = []
+        warnings.extend(stale_warnings)
         if filter_readback_pending or filter_mismatches:
             warnings.append(_warning("VIEW_FILTERS_UNVERIFIED", "view definitions were applied, but saved filter behavior is not fully verified"))
         if query_condition_readback_pending or query_condition_mismatches:
@@ -17438,7 +17464,7 @@ def _resolve_custom_button_view_button_ref(
             "reason_path": reason_path,
             "button_ref": button_ref,
             "message": "button_ref id does not exist in the current app draft or was removed in this apply",
-            "next_action": "call app_get and use custom_buttons[].button_id, or use a client_key from upsert_buttons",
+            "next_action": "call app_get_buttons with button_text to find an existing button_id, or use a client_key from upsert_buttons",
         }
     ref_text = str(button_ref or "").strip()
     if ref_text in client_key_map:
@@ -20942,6 +20968,8 @@ def _normalize_portal_view_type(view: dict[str, Any]) -> str:
         "ganttView": "ganttView",
         "hierarchy": "hierarchyView",
         "hierarchyView": "hierarchyView",
+        "calendar": "calendarView",
+        "calendarView": "calendarView",
     }
     return mapping.get(raw, "tableView")
 
@@ -23215,6 +23243,23 @@ def _apply_field_mutation(field: dict[str, Any], mutation: Any) -> None:
         field.pop("_question_rebuild_required", None)
 
 
+class AmbiguousFieldSelector(ValueError):
+    """name-only selector 命中多个同名字段。
+
+    方案 A(duplicate-field-name):后端以 queId 为字段身份、允许同父级同名;
+    name 命中多个字段时禁止静默取第一个,必须显式失败并给出候选 queId。
+    compiler 包装层(app_form)把它转写为 AMBIGUOUS_FIELD_SELECTOR 错误码。
+    """
+
+    def __init__(self, location: str, candidates: list[int]) -> None:
+        self.location = location
+        self.candidates = candidates
+        super().__init__(
+            f"{location} matches multiple fields with the same name; "
+            f"use queId to disambiguate (candidate queIds: {sorted(candidates)})"
+        )
+
+
 def _resolve_field_selector_with_uniqueness(
     *,
     fields: list[dict[str, Any]],
@@ -23230,7 +23275,12 @@ def _resolve_field_selector_with_uniqueness(
         name = str(selector.name or "").strip()
         matched = [field for field in fields if str(field.get("name") or "").strip() == name]
         if len(matched) > 1:
-            raise ValueError(f"{location} matched multiple fields with the same name; use field_id or que_id")
+            candidate_ids = [
+                ref
+                for candidate in matched
+                if (ref := _coerce_any_int(candidate.get("que_id"))) is not None
+            ]
+            raise AmbiguousFieldSelector(location, candidate_ids)
     else:
         matched = []
     if len(matched) != 1:
@@ -26778,7 +26828,7 @@ def _merge_view_summary_with_config(
             and str(entry.get("name") or "").strip()
             and str(entry.get("name") or "").strip() not in _KNOWN_SYSTEM_VIEW_COLUMNS
         ]
-        summary["columns"] = canonical_display_column_ids
+        summary["columns"] = canonical_display_columns
         summary["display_columns"] = canonical_display_columns
         summary["display_column_ids"] = canonical_display_column_ids
         summary["column_details"] = canonical_display_entries
@@ -27556,6 +27606,7 @@ def _serialize_view_button_binding(
                 "reason_path": "buttons[].button_id",
                 "missing_fields": [],
                 "details": {"button_id": binding.button_id},
+                "next_action": "call app_get_buttons with the intended button_text to reuse an existing custom button; create only if absent via app_custom_buttons_apply",
             }
         ]
     translated_limits, limit_issues = _build_view_button_limit_groups(
@@ -27616,6 +27667,11 @@ def _build_view_button_limit_groups(
                 issue["reason_path"] = "buttons[].button_limit[].values"
                 issues.append(issue)
                 continue
+            stale_warning = translated_rule.pop("_stale_warning", None)
+            if stale_warning is not None:
+                stale_warning = deepcopy(stale_warning)
+                stale_warning["reason_path"] = "buttons[].button_limit[].values"
+                issues.append(stale_warning)
             translated_rules.append(translated_rule)
         if translated_rules:
             translated_groups.append(translated_rules)
@@ -29741,6 +29797,8 @@ def _normalize_view_type_name(value: Any) -> str:
         return "board"
     if "hierarchy" in normalized:
         return "hierarchy"
+    if "calendar" in normalized:
+        return "calendar"
     if "card" in normalized:
         return "card"
     return "table"
@@ -29847,6 +29905,10 @@ def _build_view_update_payload(
         payload["viewgraphType"] = "hierarchyView"
         payload["beingShowTitleQue"] = True
         payload.pop("groupQueId", None)
+    elif normalized_type == "calendar":
+        payload["viewgraphType"] = "calendarView"
+        payload["beingShowTitleQue"] = True
+        payload.pop("groupQueId", None)
     return _hydrate_view_backend_payload(
         payload=payload,
         view_type=normalized_type,
@@ -29949,6 +30011,7 @@ def _build_minimal_view_payload(
             "board": "boardView",
             "gantt": "ganttView",
             "hierarchy": "hierarchyView",
+            "calendar": "calendarView",
         }[patch.type.value],
         "ordinal": ordinal,
         "viewgraphQueIds": visible_que_id_values,
@@ -30067,6 +30130,11 @@ def _hydrate_view_backend_payload(
         data["beingShowTitleQue"] = True
         data["groupQueId"] = None
         data["viewgraphGanttConfigVO"] = None
+    elif view_type == "calendar":
+        data["viewgraphType"] = "calendarView"
+        data["beingShowTitleQue"] = True
+        data["groupQueId"] = None
+        data["viewgraphGanttConfigVO"] = None
     if view_filters is not None:
         data["viewgraphLimit"] = deepcopy(view_filters)
         data["viewgraphLimitType"] = 1
@@ -30164,6 +30232,13 @@ def _apply_view_config_groups(
             "rootNodeFilter": deepcopy(hierarchy_filter_groups) if hierarchy_filter_groups is not None else [],
         }
         data["titleQue"] = patch.hierarchy.title_que_id
+    if patch.calendar is not None and view_type == "calendar":
+        data["viewgraphCalendarConfigVO"] = {
+            "titleQueId": patch.calendar.title_que_id,
+            "dateQueId": patch.calendar.date_que_id,
+            "colorQueId": patch.calendar.color_que_id,
+        }
+        data["titleQue"] = patch.calendar.title_que_id
     display = patch.display
     if display is not None:
         if display.row_height is not None:
@@ -30202,6 +30277,33 @@ def _apply_view_config_groups(
             data["beingPrintStatus"] = share.print_enabled
 
 
+def _stale_view_reference_warning(
+    *,
+    scope: str,
+    view_name: str,
+    field_ids: list[Any] | None = None,
+    values: list[Any] | None = None,
+    option: bool = False,
+) -> dict[str, Any]:
+    """存量死引用(已删字段/已删选项)透传警告:后端保存视图不校验引用存在性并原样透传,
+    CLI 同口径透传写回,仅以警告留痕,不再整视图拒绝(apply(get(S))≡S 重放兼容)。"""
+    warning = _warning(
+        "STALE_OPTION_REFERENCE" if option else "STALE_FIELD_REFERENCE",
+        (
+            f"view {scope} references option values not present in the current form; original values passed through (backend tolerates stale references)"
+            if option
+            else f"view {scope} references fields not present in the current form; ids passed through (backend tolerates stale references)"
+        ),
+        scope=scope,
+        view_name=view_name,
+    )
+    if field_ids:
+        warning["field_ids"] = list(field_ids)
+    if values:
+        warning["values"] = list(values)
+    return warning
+
+
 def _iter_view_config_group_field_names(patch: ViewUpsertPatch) -> list[tuple[str, list[int]]]:
     """枚举 complete 档新字段组引用的 queId(用于 UNKNOWN_VIEW_FIELD 校验)。"""
     groups: list[tuple[str, list[int]]] = []
@@ -30231,6 +30333,11 @@ def _iter_view_config_group_field_names(patch: ViewUpsertPatch) -> list[tuple[st
             groups.append(("gantt", gantt_ids))
     if patch.hierarchy is not None:
         groups.append(("hierarchy", [patch.hierarchy.title_que_id, patch.hierarchy.children_que_id]))
+    if patch.calendar is not None:
+        calendar_ids = [patch.calendar.title_que_id, patch.calendar.date_que_id]
+        if patch.calendar.color_que_id is not None:
+            calendar_ids.append(patch.calendar.color_que_id)
+        groups.append(("calendar", calendar_ids))
     return groups
 
 
@@ -30241,6 +30348,8 @@ def _resolve_view_visible_que_ids(patch: ViewUpsertPatch) -> list[int]:
     extra_ids: list[int | None] = []
     if patch.hierarchy is not None:
         extra_ids.extend([patch.hierarchy.title_que_id, patch.hierarchy.children_que_id])
+    if patch.calendar is not None:
+        extra_ids.extend([patch.calendar.title_que_id, patch.calendar.date_que_id, patch.calendar.color_que_id])
     for value in [*patch.columns, patch.title_que_id, patch.start_que_id, patch.end_que_id, patch.group_que_id, *extra_ids]:
         que_id = _coerce_any_int(value)
         if que_id is not None and (que_id > 0 or _is_known_system_view_que_id(que_id)) and que_id not in ordered:
@@ -30328,6 +30437,9 @@ def _build_view_filter_groups(
         if issue:
             issues.append(issue)
             continue
+        stale_warning = translated_rule.pop("_stale_warning", None)
+        if stale_warning is not None:
+            issues.append(stale_warning)
         translated_rules.append(translated_rule)
     return ([translated_rules] if translated_rules else []), issues
 
@@ -30338,9 +30450,9 @@ def _translate_view_filter_rule(*, field: dict[str, Any], rule: dict[str, Any])
     field_type = str(field.get("type") or FieldType.text.value)
     que_id = _coerce_positive_int(field.get("que_id")) or 0
     que_type = _coerce_positive_int(field.get("que_type")) or FIELD_TYPE_TO_QUESTION_TYPE.get(field_type, 2)
-    judge_values, judge_value_details, issue = _resolve_view_filter_values(field=field, values=values)
-    if issue:
-        return {}, issue
+    judge_values, judge_value_details, value_issue = _resolve_view_filter_values(field=field, values=values)
+    if value_issue and value_issue.get("error_code"):
+        return {}, value_issue
     payload: dict[str, Any] = {
         "queId": que_id,
         "queTitle": str(field.get("name") or ""),
@@ -30372,6 +30484,9 @@ def _translate_view_filter_rule(*, field: dict[str, Any], rule: dict[str, Any])
     elif operator == "not_empty":
         payload["judgeType"] = JUDGE_UNEQUAL
         payload["judgeValues"] = []
+    if value_issue is not None:
+        # 死选项透传:规则照常写入,warning 随 payload 携带由上层收集(_build_view_filter_groups 弹出)
+        payload["_stale_warning"] = value_issue
     return payload, None
 
 
@@ -30403,15 +30518,15 @@ def _resolve_view_filter_values(
             continue
         resolved_details.append({"id": resolved.get("id"), "value": str(resolved.get("value") or resolved.get("id"))})
     if unresolved_values and not resolved_details:
-        # 全部值都解析不出(选项已删):返回错误让上层判定(该规则已死语义)
+        # 全部值都解析不出(选项已删):原值透传(后端对存量死选项引用原样保存),
+        # 以 STALE_OPTION_REFERENCE 警告留痕,不再整视图失败
         return (
-            [],
-            [],
+            [_stringify_condition_value(value) for value in values],
+            _build_view_filter_value_details(values),
             {
-                "error_code": "UNKNOWN_VIEW_FILTER_VALUE",
+                "warning_code": "STALE_OPTION_REFERENCE",
                 "reason_path": "filters[].values",
                 "missing_fields": [],
-                "allowed_values": {"filter_values": sorted(option_by_value.keys())},
                 "details": {
                     "field_name": str(field.get("name") or ""),
                     "unresolved_values": unresolved_values,

package/src/qingflow_mcp/builder_facade/views_extract.py

@@ -25,6 +25,7 @@ _VIEW_TYPE_BY_BACKEND = {
     "boardView": "board",
     "ganttView": "gantt",
     "hierarchyView": "hierarchy",
+    "calendarView": "calendar",
 }
 
 # 后端 dataScope → 公开 data_permission.scope(与 _DATA_PERMISSION_SCOPE_MAP 对称)
@@ -68,7 +69,6 @@ _SYSTEM_COLUMN_NAMES = {
 # complete 契约不覆盖、读面存在的配置键(进入 SKIP 账本,evaluation.md §4.3)
 _UNCOVERED_READBACK_KEYS = (
     "attachVisibleOnlyConfig",
-    "viewgraphCalendarConfigVO",
     "beingRemarkStatus",
     "querySearchStatus",
     "beingDefaultPrintTplStatus",
@@ -417,6 +417,26 @@ def extract_complete_view_declaration(
         declaration["hierarchy"] = hierarchy
         _optionally(declaration, "title_que_id", title_que)
 
+    if view_type == "calendar":
+        calendar_raw = view_info.get("viewgraphCalendarConfigVO") if isinstance(view_info.get("viewgraphCalendarConfigVO"), dict) else {}
+        title_que = _coerce_positive_int(calendar_raw.get("titleQueId"))
+        date_que = _coerce_any_int(calendar_raw.get("dateQueId"))
+        color_que = _coerce_positive_int(calendar_raw.get("colorQueId"))
+        if title_que is None or title_que not in fields_by_que_id:
+            gaps.append(_gap("calendar.title_que_id", "unresolved_calendar_config", "calendar title queId does not resolve; view is not extractable", que_id=title_que))
+            return {}, gaps
+        if date_que is None or (date_que not in {2, 3} and date_que not in fields_by_que_id):
+            gaps.append(_gap("calendar.date_que_id", "unresolved_calendar_config", "calendar date queId does not resolve; view is not extractable", que_id=date_que))
+            return {}, gaps
+        calendar: dict[str, Any] = {"title_que_id": title_que, "date_que_id": date_que}
+        if color_que is not None:
+            if color_que not in fields_by_que_id:
+                gaps.append(_gap("calendar.color_que_id", "unresolved_que_id", "calendar color queId does not resolve", que_id=color_que))
+                return {}, gaps
+            calendar["color_que_id"] = color_que
+        declaration["calendar"] = calendar
+        declaration["title_que_id"] = title_que
+
     if view_type in {"card", "board"}:
         _optionally(declaration, "title_que_id", _coerce_positive_int(view_info.get("titleQue")))
 

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

@@ -225,6 +225,7 @@ def register(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) ->
     button_get.add_argument("--app-key", default="")
     button_get.add_argument("--app-keys", default="", help="逗号分隔的多应用 app_key；用于批量读取按钮配置")
     button_get.add_argument("--app-keys-file", help="JSON 字符串数组；用于批量读取按钮配置")
+    button_get.add_argument("--button-text", default="", help="按按钮文案精确查重；命中复用其 button_id，未命中再创建")
     button_get.set_defaults(handler=_handle_button_get, format_hint="builder_summary")
 
     button_apply = button_subparsers.add_parser("apply", help="声明式创建、更新或删除自定义按钮")
@@ -898,12 +899,13 @@ def _handle_associated_resource_apply(args: argparse.Namespace, context: CliCont
 
 
 def _handle_button_get(args: argparse.Namespace, context: CliContext) -> dict:
+    button_text = str(getattr(args, "button_text", "") or "").strip() or None
     app_keys = _app_keys_from_args(args)
     if app_keys is not None:
-        return context.builder.app_get_buttons(profile=args.profile, app_key="", app_keys=app_keys)
+        return context.builder.app_get_buttons(profile=args.profile, app_key="", app_keys=app_keys, button_text=button_text)
     if not (args.app_key or "").strip():
         raise_config_error("builder button get requires --app-key unless --app-keys or --app-keys-file is provided")
-    return context.builder.app_get_buttons(profile=args.profile, app_key=args.app_key)
+    return context.builder.app_get_buttons(profile=args.profile, app_key=args.app_key, button_text=button_text)
 
 
 def _handle_associated_resource_get(args: argparse.Namespace, context: CliContext) -> dict:

package/src/qingflow_mcp/server_app_builder.py

@@ -471,8 +471,8 @@ def build_builder_server() -> FastMCP:
         return ai_builder.app_get_charts(profile=profile, app_key=app_key, app_keys=app_keys)
 
     @server.tool()
-    def app_get_buttons(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:
-        return ai_builder.app_get_buttons(profile=profile, app_key=app_key, app_keys=app_keys)
+    def app_get_buttons(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None, button_text: str | None = None) -> dict:
+        return ai_builder.app_get_buttons(profile=profile, app_key=app_key, app_keys=app_keys, button_text=button_text)
 
     @server.tool()
     def app_get_associated_resources(profile: str = DEFAULT_PROFILE, app_key: str = "", app_keys: list[str] | None = None) -> dict:

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

@@ -12,6 +12,7 @@ VIEW_TYPE_MAP = {
     ViewType.board: "boardView",
     ViewType.gantt: "ganttView",
     ViewType.hierarchy: "hierarchyView",
+    ViewType.calendar: "calendarView",
 }
 
 
@@ -32,7 +33,7 @@ def compile_views(entity: EntitySpec) -> list[dict[str, Any]]:
                     "viewgraphQueIds": list(view.field_ids),
                     "viewgraphQuestions": [],
                     "ordinal": ordinal,
-                    "beingShowTitleQue": view.type in (ViewType.card, ViewType.board, ViewType.gantt, ViewType.hierarchy),
+                    "beingShowTitleQue": view.type in (ViewType.card, ViewType.board, ViewType.gantt, ViewType.hierarchy, ViewType.calendar),
                     "beingShowCover": False,
                     "viewgraphLimitType": 1,
                     "viewgraphLimit": view.filters,