precis-cli 0.1.3__py3-none-any.whl

app/shared/core/project/loader/loader_parts/inspector_uniqueness_checks.py

@@ -0,0 +1,286 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Schema 唯一性检查模块。
+
+检测两类 blocker 级冲突：
+1. 多个 schema 文件使用同一 ID（SchemaIdDuplicate）
+2. 多个 schema 指向同一数据源（SchemaSourceDuplicate）
+
+本模块不依赖 inspector_helpers，独立性最高（内联构造 actions）。
+
+依赖：→ inspection_ids + LoadingError
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from app.shared.core.project.loader.loader_parts import inspection_ids as ids
+from app.shared.core.project.loader.types import LoadingError
+
+if TYPE_CHECKING:
+    from app.shared.core.project.manifest.types import ProjectManifest
+    from app.shared.core.project.schema.types import TableSchemaFile
+
+
+def _schema_entity_label(path: str, name: str | None, schema_id: str) -> str:
+    """生成 schema 实体的用户可读显示名：优先文件名 basename，扫描时已解析出表名则附上。
+
+    表名与 id/basename 完全相同时不重复附加（如 id=name=users 的常见配置），避免噪音。
+    """
+    label = Path(path).name if path else ""
+    cleaned = (name or "").strip()
+    if cleaned and cleaned != schema_id and cleaned != label:
+        label = f"{label}（{cleaned}）" if label else cleaned
+    return label
+
+
+def _schema_involved_entity(schema_id: str, path: str, name: str | None, navigable: bool) -> dict:
+    """构造 context.involved 实体条目（前后端契约，镜像前端 InspectionInvolvedEntity）。
+
+    唯一性冲突的实体固定标注 role='conflicting'（冲突方）。字段说明:
+        - kind: 实体类型（当前仅 schema）
+        - id: 实体 id（schema id）
+        - path: 相对配置文件路径（未知时为空串，前端据此隐藏"打开文件"）
+        - label: 用户可读显示名（优先文件名 basename）
+        - navigable: 画布节点可否按 id 唯一寻址（id 冲突时为 False，
+          前端不渲染"定位到节点"，因为同 id 节点无法区分）
+    """
+    return {
+        "kind": "schema",
+        "id": schema_id,
+        "path": path,
+        "label": _schema_entity_label(path, name, schema_id),
+        "navigable": navigable,
+        "role": "conflicting",
+    }
+
+
+def _report_schema_id_duplicates(
+    id_to_refs: dict[str, list[tuple[str, str]]],
+    loading_errors: list[LoadingError],
+) -> None:
+    """根据 id → refs 索引上报重复 id 的 blocker 错误。
+
+    被 inspect_schema_id_orphan_conflict 调用，基于磁盘扫描结果上报。
+    ref_keys 为 (相对文件路径, 文件内表名) 元组列表（schemas/xxx.schema.yaml）。
+    """
+    for sid, ref_keys in id_to_refs.items():
+        count = len(ref_keys)
+        if count > 1:
+            primary_ref = ref_keys[0][0]
+            # 结构化涉事实体清单：列出全部冲突文件（id 冲突，画布节点无法按 id 区分 → 不可导航）
+            involved = [_schema_involved_entity(sid, path, name, False) for path, name in ref_keys]
+            loading_errors.append(
+                LoadingError(
+                    id=ids.schema_id_duplicate(sid),
+                    severity="blocker",
+                    title=f"表 ID「{sid}」重复",
+                    description=(
+                        f"表 ID「{sid}」被 {count} 个 schema 文件同时使用。"
+                        f"约束按 ID 引用表，ID 重复会导致约束引用指向错误的表。"
+                        f"请确保每个 schema 的 id 字段唯一。"
+                    ),
+                    fix_hint=f"请打开下方任一冲突文件，把其中一个 schema 的 id 字段改为新的唯一值（当前均为「{sid}」）。",
+                    error_type="SchemaIdDuplicate",
+                    # 归属到第一个冲突 schema 文件，前端"按文件"分组可见
+                    file_path=primary_ref,
+                    ref_id=sid,
+                    message="",
+                    suggestion="修改其中一个 schema 文件的 id 字段，使其与其他 schema 不同",
+                    context={"involved": involved},
+                    actions=[
+                        # 导航到画布中第一个重复 schema 节点，便于用户定位修改
+                        # （画布节点以 schema id 为节点 id，target 必须是 sid 而非文件路径）
+                        {
+                            "type": "navigate",
+                            "label": "定位到节点",
+                            "label_key": "inspection.actions.navigateToNode",
+                            "target": sid,
+                        },
+                        # 复制重复 ID，便于排查
+                        {
+                            "type": "copy",
+                            "label": "复制 ID",
+                            "label_key": "inspection.actions.copyId",
+                            "text": sid,
+                        },
+                        # 允许忽略（此类问题需用户手动决策保留哪个，无法自动修复）
+                        {
+                            "type": "dismiss",
+                            "label": "忽略",
+                            "label_key": "inspection.actions.dismiss",
+                        },
+                    ],
+                    title_key="inspection.issues.schemaIdDuplicate.title",
+                    description_key="inspection.issues.schemaIdDuplicate.description",
+                    fix_hint_key="inspection.issues.schemaIdDuplicate.fixHint",
+                    message_params={"schemaId": sid, "count": count},
+                )
+            )
+
+
+def inspect_schema_id_orphan_conflict(
+    config_path: Path,
+    manifest: ProjectManifest,
+    schema_files: dict[str, TableSchemaFile],
+    loading_errors: list[LoadingError],
+) -> None:
+    """检测磁盘上多个 schema 文件使用同一 ID（blocker）。
+
+    本函数是 schema ID 唯一性检测的唯一入口。直接扫磁盘所有 .schema.yaml 文件，
+    按「文件内 id」建索引，同一 id 被 ≥2 个文件使用即报 blocker。
+
+    旧实现遍历 schema_files dict，但该 dict 按 id 做 key，冲突时后者会被吞掉，
+    永远检测不到重复。基于磁盘的检测不依赖 manifest 白名单，因此在两条路径下
+    都生效：
+    - load_project（运行时校验，schema_files 只含 manifest 白名单文件）
+    - get_v2_full_config（前端资源树，schema_files 含 effective_manifest 合并的孤儿）
+
+    参数:
+        config_path: 项目根目录（manifest 所在目录）
+        manifest: 项目清单（保留参数，当前实现基于磁盘扫描，不依赖白名单）
+        schema_files: 已加载的 schema dict（保留参数，兼容 inspect_config 调用签名）
+        loading_errors: 错误收集列表（会被修改）
+    """
+    schemas_dir = config_path / "schemas"
+    if not schemas_dir.is_dir():
+        return
+
+    from app.shared.core.io.yaml import read_yaml
+
+    # 扫磁盘所有 .schema.yaml，按「文件内 id」索引到 (相对路径, 文件内表名)
+    # 表名一并收集，用于构造 involved 实体的友好显示名
+    id_to_refs: dict[str, list[tuple[str, str]]] = {}
+    for filename in os.listdir(schemas_dir):
+        if not filename.lower().endswith(".schema.yaml"):
+            continue
+        abs_path = schemas_dir / filename
+        try:
+            raw = read_yaml(abs_path)
+        except Exception:
+            continue
+        if not isinstance(raw, dict):
+            continue
+        file_id = raw.get("id")
+        if not isinstance(file_id, str) or not file_id.strip():
+            continue
+        file_name = raw.get("name")
+        id_to_refs.setdefault(file_id.strip(), []).append(
+            (f"schemas/{filename}", file_name.strip() if isinstance(file_name, str) else "")
+        )
+
+    # 同一 id 被 ≥2 个文件使用 → 冲突
+    conflict_index = {sid: refs for sid, refs in id_to_refs.items() if len(refs) > 1}
+
+    if conflict_index:
+        _report_schema_id_duplicates(conflict_index, loading_errors)
+
+
+def inspect_source_uniqueness(
+    schema_files: dict[str, TableSchemaFile],
+    loading_errors: list[LoadingError],
+    schema_paths: dict[str, str] | None = None,
+) -> None:
+    """检测两个 schema 指向同一数据源（blocker）。
+
+    schema_paths: schema id → 文件相对路径（来自 manifest 引用），
+    用于把问题归属到具体配置文件；缺省时留空，由前端兜底展示。
+    """
+    from app.shared.core.project.schema.types_parts.schema_id import normalize_source_key
+
+    resolved_schema_paths = schema_paths or {}
+    source_map: dict[tuple[str, str | None], list[str]] = {}
+    for sid, sdoc in schema_files.items():
+        source = getattr(sdoc, "source", None)
+        if source is None:
+            continue
+        path = getattr(source, "path", None) or ""
+        sheet = getattr(source, "sheet", None)
+        if not path:
+            continue
+        key = normalize_source_key(path, sheet)
+        source_map.setdefault(key, []).append(sid)
+
+    for key, sids in source_map.items():
+        if len(sids) > 1:
+            path_str, sheet_str = key
+            source_display = f"{path_str}"
+            if sheet_str:
+                source_display += f" ({sheet_str})"
+            primary_ref = sids[0]
+            # 结构化涉事实体清单：列出全部指向同一数据源的 schema（id 各不相同 → 可导航）
+            involved = [
+                _schema_involved_entity(
+                    sid,
+                    resolved_schema_paths.get(sid, ""),
+                    getattr(schema_files[sid], "name", None),
+                    True,
+                )
+                for sid in sids
+            ]
+            loading_errors.append(
+                LoadingError(
+                    id=ids.schema_source_duplicate(path_str, sheet_str),
+                    severity="blocker",
+                    title=f"有表指向了同一个数据文件：{source_display}",
+                    description=(
+                        f"数据源 '{source_display}' 被 {len(sids)} 个 schema 引用: {', '.join(sids)}。"
+                        f"每个数据源只能被一个 schema 定义，否则读取会冲突。请删除重复的 schema 或修改其 source.path。"
+                    ),
+                    fix_hint=f"请保留其中一个 schema（如 {sids[0]}），删除或修改其他的。涉事实体见下方清单。",
+                    error_type="SchemaSourceDuplicate",
+                    # 归属到第一个引用该数据源的 schema 文件，前端"按文件"分组可见
+                    file_path=resolved_schema_paths.get(primary_ref, ""),
+                    ref_id=primary_ref,
+                    message="",
+                    suggestion=f"保留 schema '{sids[0]}'，删除或修改: {', '.join(sids[1:])}",
+                    context={"involved": involved},
+                    actions=[
+                        # 导航到第一个重复 schema 节点
+                        {
+                            "type": "navigate",
+                            "label": "定位到节点",
+                            "label_key": "inspection.actions.navigateToNode",
+                            "target": primary_ref,
+                        },
+                        # 复制数据源路径，便于排查
+                        {
+                            "type": "copy",
+                            "label": "复制数据源",
+                            "label_key": "inspection.actions.copyFilePath",
+                            "text": source_display,
+                        },
+                        # 允许忽略（需用户手动决策保留哪个 schema）
+                        {
+                            "type": "dismiss",
+                            "label": "忽略",
+                            "label_key": "inspection.actions.dismiss",
+                        },
+                    ],
+                    title_key="inspection.issues.sourceDuplicate.title",
+                    description_key="inspection.issues.sourceDuplicate.description",
+                    fix_hint_key="inspection.issues.sourceDuplicate.fixHint",
+                    message_params={
+                        "sourceDisplay": source_display,
+                        "count": len(sids),
+                        "schemas": ", ".join(sids),
+                        "primarySchema": primary_ref,
+                    },
+                )
+            )

app/shared/core/project/loader/loader_parts/loading_error_messages.py

@@ -0,0 +1,298 @@
+# SPDX-License-Identifier: Apache-2.0
+#
+# Copyright 2026 Precis Team
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""
+@fileoverview 加载期错误友好文案生成
+
+功能概述:
+- 把加载阶段(main.py)产生的技术性异常，转换为面向普通用户的友好 LoadingError 字段
+- 统一管理 title / description / fix_hint / severity，避免散落在各处硬编码
+- 为每类加载错误提供 i18n key，前端可优先用本地化文案渲染
+
+设计原则:
+- 纯函数，返回 dict（可直接解包进 LoadingError 构造参数）
+- 文案以用户视角描述问题（"文件找不到了"而非"FileNotFoundError"）
+- 原始技术细节保留在 message 字段，前端折叠展示供高级用户排查
+
+覆盖的错误类型:
+- 路径校验失败 (PathValidationError)
+- 文件不存在 (NotFound)
+- 文件解析失败 (ParseError) — 含 YAML 语法 / Pydantic 校验两种子类
+- 模板展开失败 (TemplateExpansionError)
+"""
+
+from __future__ import annotations
+
+import os
+
+from app.shared.core.project.loader.loader_parts.inspector_helpers import (
+    file_entity_label,
+    involved_entity,
+)
+
+# 文件类型 → 中文友好名称映射（用于文案插值）
+# key 为小写化的 file_type（main.py 传入 "ManualData" 等首字母大写形式）
+_RESOURCE_LABELS: dict[str, str] = {
+    "schema": "数据表定义",
+    "constraint": "约束规则",
+    "regex": "正则规则",
+    "transform": "数据转换",
+    "template": "模板",
+    "manualdata": "手动数据",
+}
+
+
+def _resource_label(file_type: str) -> str:
+    """获取文件类型的友好中文名称，未知类型回退到原名。"""
+    key = (file_type or "").lower()
+    return _RESOURCE_LABELS.get(key, file_type or "配置文件")
+
+
+def _resource_kind(file_type: str) -> str:
+    """文件类型 → involved 实体 kind（小写化；ManualData 归一为 manual_data，与 id 检查一致）。"""
+    kind = (file_type or "").strip().lower()
+    return "manual_data" if kind == "manualdata" else kind
+
+
+def _file_involved(file_type: str, ref_id: str, file_path: str) -> dict:
+    """加载期错误的涉事实体：出问题的文件本身（role=file，文件无画布节点 → 不可导航）。"""
+    return involved_entity(
+        kind=_resource_kind(file_type),
+        entity_id=ref_id,
+        path=file_path,
+        label=file_entity_label(file_path),
+        navigable=False,
+        role="file",
+    )
+
+
+def path_validation_error(file_type: str, ref_id: str, raw_message: str, file_path: str = "") -> dict:
+    """路径校验失败（路径越界/非法字符等）。
+
+    Args:
+        file_type: 文件类型（schema/constraint/...）
+        ref_id: manifest 中的引用 ID
+        raw_message: 原始异常字符串（保留供排查）
+        file_path: 校验失败的目标文件路径（绝对路径，供 involved 实体展示）
+
+    Returns:
+        LoadingError 友好字段 dict（title/description/fix_hint/severity 等）
+    """
+    label = _resource_label(file_type)
+    return {
+        "severity": "blocker",
+        "title": f"{label}的路径存在问题",
+        "description": f"项目清单里指向「{label}」的路径（编号 {ref_id}）无法被安全访问。这通常是路径写错了，或指向了项目目录之外的位置。",
+        "fix_hint": "请检查项目清单中该资源的 path 是否正确，确保它指向项目目录内的文件。",
+        "message": raw_message,
+        "context": {"involved": [_file_involved(file_type, ref_id, file_path)]},
+        "title_key": "inspection.issues.load.pathValidation.title",
+        "description_key": "inspection.issues.load.pathValidation.description",
+        "fix_hint_key": "inspection.issues.load.pathValidation.fixHint",
+        "message_params": {"resourceLabel": label, "refId": ref_id},
+    }
+
+
+def file_not_found_error(file_type: str, ref_id: str, file_path: str) -> dict:
+    """引用的文件不存在。
+
+    Args:
+        file_type: 文件类型
+        ref_id: manifest 中的引用 ID
+        file_path: 缺失的文件绝对路径
+
+    Returns:
+        LoadingError 友好字段 dict
+    """
+    label = _resource_label(file_type)
+    # 文件名单独抽出，避免长路径直接糊在描述里
+    filename = os.path.basename(file_path) if file_path else ""
+    return {
+        "severity": "blocker",
+        "title": f"{label}文件找不到了",
+        "description": f"项目清单里引用的「{label}」（编号 {ref_id}）对应的文件「{filename or file_path}」不存在。可能文件被移动、删除或改名了。",
+        "fix_hint": "请确认该文件是否还在，或从项目清单中移除这条已经失效的引用。",
+        "message": f"{file_type} 文件不存在: {file_path}",
+        "context": {"involved": [_file_involved(file_type, ref_id, file_path)]},
+        "title_key": "inspection.issues.load.notFound.title",
+        "description_key": "inspection.issues.load.notFound.description",
+        "fix_hint_key": "inspection.issues.load.notFound.fixHint",
+        "message_params": {"resourceLabel": label, "refId": ref_id, "filename": filename},
+    }
+
+
+def parse_error(file_type: str, ref_id: str, file_path: str, raw_exception: BaseException) -> dict:
+    """文件解析失败（YAML 语法错或 Pydantic 校验错）。
+
+    把冗长的原始异常归类为两种用户可理解的子类，原始信息保留在 message。
+
+    Args:
+        file_type: 文件类型
+        ref_id: manifest 中的引用 ID
+        file_path: 出错文件路径
+        raw_exception: 原始异常对象
+
+    Returns:
+        LoadingError 友好字段 dict
+    """
+    label = _resource_label(file_type)
+    raw_text = str(raw_exception)
+    # 区分 YAML 语法错误 vs 字段校验错误，给出不同的修复方向
+    is_yaml_syntax = _looks_like_yaml_error(raw_exception, raw_text)
+    if is_yaml_syntax:
+        fix_hint = "请打开文件检查 YAML 缩进、冒号、引号是否正确，尤其是列表和键值对的格式。"
+        desc = (
+            f"「{label}」（编号 {ref_id}）的文件无法按配置格式解析，通常是 YAML 语法写错了（比如缩进不对、漏了冒号）。"
+        )
+    else:
+        fix_hint = "请打开文件检查必填字段是否完整、取值是否符合规范，参考同类型的其他配置文件。"
+        desc = f"「{label}」（编号 {ref_id}）的文件格式不对，缺少必要字段或字段取值不符合要求。"
+
+    return {
+        "severity": "blocker",
+        "title": f"{label}文件内容格式有误",
+        "description": desc,
+        "fix_hint": fix_hint,
+        "message": f"{file_type} 文件解析失败: {raw_text}",
+        "context": {"involved": [_file_involved(file_type, ref_id, file_path)]},
+        "title_key": "inspection.issues.load.parseError.title",
+        "description_key": "inspection.issues.load.parseError.description",
+        "fix_hint_key": "inspection.issues.load.parseError.fixHint",
+        "message_params": {"resourceLabel": label, "refId": ref_id},
+    }
+
+
+def template_expansion_error(instance_id: str, raw_exception: BaseException, file_path: str = "") -> dict:
+    """模板展开失败。
+
+    Args:
+        instance_id: 模板实例 ID
+        raw_exception: 原始异常
+        file_path: 模板实例所在配置文件路径（通常是 project.precis.yaml），供 involved 实体展示
+
+    Returns:
+        LoadingError 友好字段 dict
+    """
+    return {
+        "severity": "blocker",
+        "title": "模板无法正常展开",
+        "description": f"画布上的模板（编号 {instance_id}）在展开成具体规则时出错了。可能是模板参数没填全，或模板定义本身有问题。",
+        "fix_hint": "请检查该模板的参数是否完整、引用的列/表是否存在，必要时删除该模板重新创建。",
+        "message": f"模板实例 '{instance_id}' 展开失败: {raw_exception}",
+        "context": {"involved": [_file_involved("template", instance_id, file_path)]},
+        "title_key": "inspection.issues.load.templateExpansion.title",
+        "description_key": "inspection.issues.load.templateExpansion.description",
+        "fix_hint_key": "inspection.issues.load.templateExpansion.fixHint",
+        "message_params": {"instanceId": instance_id},
+    }
+
+
+def template_node_expansion_error(instance_id: str, node_id: str, message: str, file_path: str = "") -> dict:
+    """模板内单个节点展开失败（其余节点正常展开，仅该节点产物缺失）。
+
+    Args:
+        instance_id: 模板实例 ID
+        node_id: 展开失败的模板节点本地 ID
+        message: 节点级展开失败的原始异常信息
+        file_path: 模板实例所在配置文件路径（通常是 project.precis.yaml），供 involved 实体展示
+
+    Returns:
+        LoadingError 友好字段 dict
+    """
+    ref_id = f"{instance_id}/{node_id}"
+    return {
+        "severity": "warning",
+        "title": "模板部分内容未能展开",
+        "description": f"模板（编号 {instance_id}）中的某个节点（编号 {node_id}）在展开成具体规则时出错了，该节点的约束/转换没有生成，其余节点已正常展开。",
+        "fix_hint": "请检查该节点的参数配置与引用的列/表是否存在，修正后重新加载项目；缺失的规则在此之前不会参与校验。",
+        "message": f"模板实例 '{instance_id}' 的节点 '{node_id}' 展开失败: {message}",
+        "context": {"involved": [_file_involved("template", ref_id, file_path)]},
+        "title_key": "inspection.issues.load.templateNodeExpansion.title",
+        "description_key": "inspection.issues.load.templateNodeExpansion.description",
+        "fix_hint_key": "inspection.issues.load.templateNodeExpansion.fixHint",
+        "message_params": {"instanceId": instance_id, "nodeId": node_id},
+    }
+
+
+def manifest_version_missing(supported: str) -> dict:
+    """manifest 顶层缺少 version 字段。
+
+    P0-1 版本识别：version 字段在 Pydantic 模型中有默认值，缺失会被静默吞掉，
+    故在解析前显式检查并在 loading_errors 通道报错。
+
+    Args:
+        supported: 当前支持的版本号列表描述（如 "2"）
+
+    Returns:
+        LoadingError 友好字段 dict
+    """
+    return {
+        "severity": "blocker",
+        "title": "配置文件缺少 version 字段",
+        "description": f"项目清单没有写 version 字段，无法识别配置格式。当前支持的版本为 {supported}。",
+        "fix_hint": f"请在 project.precis.yaml 顶层添加一行「version: {supported}」。",
+        "message": "缺少 version 字段，当前支持版本为 " + supported,
+        "context": {"involved": []},
+        "title_key": "inspection.issues.load.manifestVersionMissing.title",
+        "description_key": "inspection.issues.load.manifestVersionMissing.description",
+        "fix_hint_key": "inspection.issues.load.manifestVersionMissing.fixHint",
+        "message_params": {"supported": supported},
+    }
+
+
+def manifest_version_unsupported(version: object, supported: str) -> dict:
+    """manifest 顶层 version 字段不是受支持的版本。
+
+    Args:
+        version: 文件中实际写的 version 值（可能为任意 YAML 类型）
+        supported: 当前支持的版本号列表描述（如 "2"）
+
+    Returns:
+        LoadingError 友好字段 dict
+    """
+    return {
+        "severity": "blocker",
+        "title": f"配置版本 {version} 不被支持",
+        "description": f"项目清单写的版本是 {version!r}，当前支持的版本为 {supported}。旧版配置需要先升级才能使用。",
+        "fix_hint": (
+            f"请将配置升级到 V2 格式：顶层改为「version: {supported}」，schema 使用 columns+source 结构、"
+            "约束拆分为 constraints/*.constraint.yaml 独立文件（refs+params 分离）。"
+            "可参考仓库 qa_test/qa_simple/ 示例项目对照迁移。"
+        ),
+        "message": f"不支持的项目配置版本: {version!r}，当前支持版本为 {supported}",
+        "context": {"involved": []},
+        "title_key": "inspection.issues.load.manifestVersionUnsupported.title",
+        "description_key": "inspection.issues.load.manifestVersionUnsupported.description",
+        "fix_hint_key": "inspection.issues.load.manifestVersionUnsupported.fixHint",
+        "message_params": {"version": str(version), "supported": supported},
+    }
+
+
+def _looks_like_yaml_error(exc: BaseException, text: str) -> bool:
+    """判断异常是否为 YAML 语法错误（而非字段校验错误）。"""
+    # yaml.YAMLError 及其子类
+    if exc.__class__.__module__.startswith("yaml"):
+        return True
+    # 文本特征：YAML 错误通常含 "while parsing"/"mapping"/"expected"/"found character" 等
+    lowered = text.lower()
+    yaml_markers = (
+        "while parsing",
+        "mapping values are not allowed",
+        "could not determine a constructor",
+        "found character that cannot start",
+        "expected '<document start>'",
+        "while scanning",
+    )
+    return any(m in lowered for m in yaml_markers)