@qingflow-tech/qingflow-cli 1.1.60 → 1.1.61-beta.2

package/src/qingflow_mcp/app_form_validator.py

@@ -11,9 +11,15 @@ from .app_form_compat import normalize_app_form_declaration
 from .builder_facade.app_form_schema import AppFormContractError, compact_schema_errors, schema_error_message
 
 
+#: code_block / q_linker 输出目标字段类型。后端写链无类型白名单(FormSvcImpl
+#: 原样落库),运行时 DataSvcImpl.getAnswerValueByString:选项/数字/日期有专门
+#: 分支;attachment 按拆分 URL 写入(专门分支);subtable 整表组装(专门分支);
+#: rich_text/data_relation 走 Question.canImport 兜底按字符串写入(不报错)。
+#: 四者为存量合法配置(提取读得出、apply 必须写回,两闸门同口径)。
 _INTEGRATION_OUTPUT_TARGET_FIELD_TYPES = {
     "text",
     "long_text",
+    "rich_text",
     "number",
     "amount",
     "date",
@@ -21,6 +27,9 @@ _INTEGRATION_OUTPUT_TARGET_FIELD_TYPES = {
     "single_choice",
     "single_select",
     "multi_select",
+    "attachment",
+    "data_relation",
+    "subtable",
 }
 _Q_LINKER_TEMPLATE_RE = re.compile(r"\{\{(?P<key>[^{}\s]+)\}\}")
 _FORMULA_IDENTIFIER_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
@@ -218,19 +227,32 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
             widths = ["width" in field for field in fields if isinstance(field, dict)]
             if widths and any(widths) and not all(widths):
                 errors.append((row_path, "width must be present on every field in the row or omitted from all"))
-            if widths and all(widths) and sum(field.get("width", 0) for field in fields if isinstance(field, dict)) != 100:
-                errors.append((row_path, "field widths must total 100"))
+            # 行宽契约(与后端语义对齐):任意 1-100 整数 + 全有或全无。
+            # 后端 html_width 无取值/总和校验,存量存在 33/34 三等分与字段删除后
+            # 留白(如 3×25=75)的行;get 读出的原布局必须能原样过校验
+            # (apply(get(S)) ≡ S 命题的必要条件)。
+            if widths and all(widths):
+                bad = [f.get("width") for f in fields if isinstance(f, dict) and not (isinstance(f.get("width"), int) and 1 <= f["width"] <= 100)]
+                if bad:
+                    errors.append((row_path, "field widths must be an integer between 1 and 100"))
             for field_index, field in enumerate(fields):
                 if isinstance(field, dict):
                     top_fields.append((f"{row_path}/{field_index}", field))
     def resolve_local_selector(selector: Any) -> tuple[str, tuple[str, dict[str, Any]] | None]:
-        """Resolve against the declared body, preserving backend-dependent ID-only cases."""
+        """Resolve against the declared body, preserving backend-dependent ID-only cases.
+
+        返回态:resolved(唯一定位)/ invalid(定位失败)/ ambiguous(方案 A:name-only
+        命中多个同名字段,调用方须报 AMBIGUOUS_FIELD_SELECTOR)/ unknown(存在未命名
+        字段,后端侧再判)/ schema(结构不完整,交给 Schema 校验)。
+        """
         if not isinstance(selector, dict):
             return "schema", None
         raw_que_id = selector.get("queId")
         que_id = raw_que_id if isinstance(raw_que_id, int) and not isinstance(raw_que_id, bool) else None
         raw_name = selector.get("name")
-        name = raw_name if isinstance(raw_name, str) and raw_name else ""
+        # name 两侧 strip:存量字段名带前导/尾随空格,queId 已同时给出不构成歧义
+        # (与 compiler 侧三个 resolve 函数同口径)。
+        name = raw_name.strip() if isinstance(raw_name, str) and raw_name.strip() else ""
         if raw_que_id is not None and que_id is None:
             return "schema", None
         if raw_name is not None and not name:
@@ -239,26 +261,52 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
             matches = [(path, field) for path, field in top_fields if field.get("queId") == que_id]
             if len(matches) != 1:
                 return "invalid", None
-            declared_name = str(matches[0][1].get("name") or "")
+            declared_name = str(matches[0][1].get("name") or "").strip()
             if name and declared_name and name != declared_name:
                 return "invalid", None
             return "resolved", matches[0]
         if name:
-            matches = [(path, field) for path, field in top_fields if str(field.get("name") or "") == name]
+            matches = [(path, field) for path, field in top_fields if str(field.get("name") or "").strip() == name]
             if len(matches) == 1:
                 return "resolved", matches[0]
             if len(matches) > 1:
-                return "invalid", None
+                return "ambiguous", None
             if any(not str(field.get("name") or "") for _, field in top_fields):
                 return "unknown", None
             return "invalid", None
         return "schema", None
 
+    def ambiguity_message(selector: Any, subject: str) -> str:
+        name = str((selector or {}).get("name") or "").strip()
+        candidate_ids = sorted(
+            {
+                field.get("queId")
+                for _, field in top_fields
+                if str(field.get("name") or "").strip() == name
+                and isinstance(field.get("queId"), int)
+                and not isinstance(field.get("queId"), bool)
+            }
+        )
+        return (
+            f"AMBIGUOUS_FIELD_SELECTOR: {subject} name {name!r} matches multiple fields "
+            f"(candidate queIds: {candidate_ids}); duplicate names are allowed but "
+            "selectors must use queId to disambiguate"
+        )
+
     title_selector = spec.get("dataTitleField")
     if top_fields:
         if "dataTitleField" not in spec and "appKey" in payload:
             pass
-        elif title_selector is None or resolve_local_selector(title_selector)[0] == "invalid":
+        elif title_selector is None:
+            # dataTitleField=null 仅在带 appKey 的更新/round-trip 场景放行:后端写链
+            # FormSvcImpl.normalizeDataTitleQueId 对 null 自动 fallback 到第一个可用
+            # 字段,get 读面在后端未设置时原样输出 null。创建场景(无 appKey)仍需
+            # 显式 selector。
+            if "appKey" not in payload:
+                errors.append(("/spec/dataTitleField", "dataTitleField must resolve to exactly one top-level field"))
+        elif resolve_local_selector(title_selector)[0] == "ambiguous":
+            errors.append(("/spec/dataTitleField", ambiguity_message(title_selector, "dataTitleField")))
+        elif resolve_local_selector(title_selector)[0] == "invalid":
             errors.append(("/spec/dataTitleField", "dataTitleField must resolve to exactly one top-level field"))
     elif title_selector is not None:
         errors.append(("/spec/dataTitleField", "dataTitleField must be null when body is empty"))
@@ -266,11 +314,15 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
     cover_selector = spec.get("dataCoverField")
     if cover_selector is not None:
         cover_resolution, cover = resolve_local_selector(cover_selector)
-        if cover_resolution == "invalid":
+        if cover_resolution == "ambiguous":
+            errors.append(("/spec/dataCoverField", ambiguity_message(cover_selector, "dataCoverField")))
+        elif cover_resolution == "invalid":
             errors.append(("/spec/dataCoverField", "dataCoverField must resolve to exactly one top-level field"))
         elif cover_resolution == "resolved" and cover is not None and _field_type(cover[1]) != "attachment":
             errors.append(("/spec/dataCoverField", "dataCoverField must select a top-level attachment field"))
-    names: dict[str, str] = {}
+    # 方案 A(duplicate-field-name):同父级允许同名(后端以 queId 为身份,40013
+    # 实测 1624 组),不再报 duplicate name;歧义在 selector 解析处以
+    # AMBIGUOUS_FIELD_SELECTOR 显式拒绝。
     fields_by_id = {
         field.get("queId"): field
         for _, field in top_fields
@@ -278,12 +330,6 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
     }
     output_targets: dict[str, tuple[str, str]] = {}
     for path, field in top_fields:
-        name = str(field.get("name") or "")
-        if name:
-            if name in names:
-                errors.append((f"{path}/name", f"duplicate top-level field name; first declared at {names[name]}"))
-            else:
-                names[name] = f"{path}/name"
         field_type = _field_type(field)
         if field_type == "data_relation":
             config = field.get("config") if isinstance(field.get("config"), dict) else {}
@@ -329,6 +375,9 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
             selector = item.get("field") if isinstance(item.get("field"), dict) else {}
             input_path = f"{path}/config/{binding_name}/inputs/{index}"
             resolution, selected = resolve_local_selector(selector)
+            if resolution == "ambiguous":
+                errors.append((f"{input_path}/field", ambiguity_message(selector, f"{binding_name}.inputs[{index}].field")))
+                continue
             if resolution == "invalid":
                 errors.append((f"{input_path}/field", "input field must resolve to exactly one top-level field"))
                 continue
@@ -380,13 +429,16 @@ def _static_errors(payload: dict[str, Any]) -> list[tuple[str, str]]:
                         )
                     )
 
-        producer = name or str(field.get("queId") or field_type)
+        producer = str(field.get("name") or "") or str(field.get("queId") or field_type)
         for index, item in enumerate(binding.get("outputs") or []):
             if not isinstance(item, dict):
                 continue
             selector = item.get("targetField")
             target_path = f"{path}/config/{binding_name}/outputs/{index}/targetField"
             resolution, selected = resolve_local_selector(selector)
+            if resolution == "ambiguous":
+                errors.append((target_path, ambiguity_message(selector, f"{binding_name}.outputs[{index}].targetField")))
+                continue
             if resolution == "invalid":
                 errors.append((target_path, "targetField must resolve to exactly one top-level field"))
                 continue

package/src/qingflow_mcp/backend_client.py

@@ -304,18 +304,40 @@ class BackendClient:
             "body": body,
         }
 
-    def download_binary(self, url: str, *, headers: dict[str, str] | None = None) -> bytes:
+    def _get_binary_response(
+        self, url: str, *, headers: dict[str, str] | None = None,
+        follow_redirects: bool | None = None, max_bytes: int | None = None,
+    ) -> tuple[httpx.Response, bytes]:
+        options: dict[str, Any] = {"headers": headers or None}
+        if follow_redirects is not None:
+            options["follow_redirects"] = follow_redirects
+        if max_bytes is None:
+            response = self._client.get(url, **options)
+            return response, response.content
+        with self._client.stream("GET", url, **options) as response:
+            content = bytearray()
+            for chunk in response.iter_bytes():
+                if len(content) + len(chunk) > max_bytes:
+                    raise QingflowApiError(
+                        category="file_size_limit", message="附件超过单文件或总大小预算",
+                    )
+                content.extend(chunk)
+            return response, bytes(content)
+
+    def download_binary(
+        self, url: str, *, headers: dict[str, str] | None = None, max_bytes: int | None = None,
+    ) -> bytes:
         try:
-            response = self._client.get(url, headers=headers or None)
+            response, content = self._get_binary_response(url, headers=headers, max_bytes=max_bytes)
         except httpx.RequestError as exc:
             raise QingflowApiError(category="network", message=str(exc))
         if response.status_code >= 400:
             raise QingflowApiError(
                 category="http",
-                message=self._extract_message(response.text) or f"HTTP {response.status_code}",
+                message=self._extract_message(content.decode(response.encoding or "utf-8", errors="replace")) or f"HTTP {response.status_code}",
                 http_status=response.status_code,
             )
-        return response.content
+        return content
 
     def download_binary_with_cookie(
         self,
@@ -324,6 +346,7 @@ class BackendClient:
         *,
         cookie_name: str,
         headers: dict[str, str] | None = None,
+        max_bytes: int | None = None,
     ) -> BackendBinaryResponse:
         qf_version, _source = self._resolve_qf_version(context.qf_version)
         request_headers = {
@@ -337,7 +360,9 @@ class BackendClient:
             cookie_parts.append(f"qfVersion={qf_version}")
         request_headers["Cookie"] = "; ".join(cookie_parts)
         try:
-            response = self._client.get(url, headers=request_headers, follow_redirects=False)
+            response, content = self._get_binary_response(
+                url, headers=request_headers, follow_redirects=False, max_bytes=max_bytes,
+            )
         except httpx.RequestError as exc:
             raise QingflowApiError(category="network", message=str(exc))
         redirected = 300 <= response.status_code < 400 and bool(response.headers.get("location"))
@@ -345,17 +370,17 @@ class BackendClient:
             redirect_headers = {key: value for key, value in request_headers.items() if key.lower() != "cookie"}
             redirect_url = urljoin(str(response.url), response.headers["location"])
             try:
-                response = self._client.get(redirect_url, headers=redirect_headers)
+                response, content = self._get_binary_response(redirect_url, headers=redirect_headers, max_bytes=max_bytes)
             except httpx.RequestError as exc:
                 raise QingflowApiError(category="network", message=str(exc))
         if response.status_code >= 400:
             raise QingflowApiError(
                 category="http",
-                message=self._extract_message(response.text) or f"HTTP {response.status_code}",
+                message=self._extract_message(content.decode(response.encoding or "utf-8", errors="replace")) or f"HTTP {response.status_code}",
                 http_status=response.status_code,
             )
         return BackendBinaryResponse(
-            content=response.content,
+            content=content,
             headers=dict(response.headers),
             http_status=response.status_code,
             final_url=str(response.url),