precis-cli 0.1.3__py3-none-any.whl

app/shared/services/llm/actions/specs.py

@@ -0,0 +1,259 @@
+# 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 AI 动作 Spec Pydantic 模型 — 结构校验单一事实源
+
+用类型系统编码动作 spec 的**结构性**约束（枚举、必填等），
+取代散落各处的手写 dict.get() + if 校验。
+
+设计原则：
+- 只做**结构校验**（不依赖项目运行时状态）：枚举值、字段存在性。
+- **上下文校验**（表/列/FK 是否存在、类型兼容性、参数完整性）仍留在各 validator 函数——
+  它们需要运行时加载的 schema，Pydantic 表达不了。
+- 与 registry.py 互补：registry 描述"有哪些动作"，specs 描述"每个动作的 spec 长什么样"。
+- 约束参数的完整性校验（如 Range min/max、Scripted expression/pattern）由
+  _constraint_validator 与 constraint_builder 负责，不在 Pydantic 层做。
+
+风格参照 config/models.py（领域 Pydantic 模型，非 API DTO）：
+- ConfigDict(extra="ignore") 容忍 LLM 多余字段（不严格 forbid，避免误杀）
+- populate_by_name 支持 camelCase（LLM 可能输出各种大小写）
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from app.shared.core.pydantic_messages import localize_pydantic_msg
+
+
+class EmptyParams(BaseModel):
+    """无参数约束（NotNull/Unique/Charset/Composite）的空参数模型。"""
+
+    model_config = ConfigDict(extra="ignore")
+
+
+# =============================================================================
+# 各动作 Spec 模型
+# =============================================================================
+
+
+class ConstraintSpec(BaseModel):
+    """约束动作的 spec（constraintSpec）。ADD/UPDATE/DELETE_CONSTRAINT_NODE 用。"""
+
+    model_config = ConfigDict(extra="ignore")
+
+    # type 设为可选（非 ...）：缺失 type 时 validator 用 missing_constraint_type 报错（有建议提示），
+    # 而非被 Pydantic 拦截为 spec_structure_invalid（无建议）。
+    type: str | None = Field(default=None, description="约束类型（标准名或别名）")
+    tableName: str | None = Field(default=None, description="目标表名")
+    targetNodeId: str | None = Field(default=None, description="目标表 ID")
+    targetColumn: str | None = Field(default=None, description="目标列名")
+    targetColumnId: str | None = Field(default=None, description="目标列 ID")
+    constraintId: str | None = Field(default=None, description="约束 ID")
+    # §2.11: 默认对齐消费方口径（get("isInline", False)）——原默认 True 与
+    # update_yaml_config/frontend_instructions 的 get 默认 False 漂移，谁改任一侧即炸。
+    # 消费方均读原始 dict，本默认值当前不参与运行时判定（行为锁定测试见 B4 回归）。
+    isInline: bool = Field(default=False, description="是否内联约束（默认 false=独立约束文件）")
+    params: dict[str, Any] | None = Field(default=None, description="约束参数")
+
+    # 注意：约束类型白名单、表信息存在性、参数完整性均不在 Pydantic 层校验——这些由
+    # _constraint_validator 负责（它有更精准的 "did you mean" 建议和 missing_required_param 错误类型），
+    # Scripted 空表达式等参数关系校验由 constraint_builder 落实。
+    # Pydantic 层对 ConstraintSpec 只做字段类型解析。
+
+
+class ValidateSpec(BaseModel):
+    """VALIDATE_PROJECT 的 spec（复用 constraintSpec 字段，但 type 可选、表信息可选）。
+
+    与 ConstraintSpec 区别：VALIDATE_PROJECT 可空壳（校验全部表），或只给 tableName。
+    """
+
+    model_config = ConfigDict(extra="ignore")
+    tableName: str | None = Field(default=None, description="目标表名（可选）")
+    targetNodeId: str | None = Field(default=None, description="目标表 ID（可选）")
+    tables: list[str] | None = Field(default=None, description="多表校验列表")
+    tableIds: list[str] | None = Field(default=None, description="多表校验列表（别名）")
+
+
+class SchemaColumnSpec(BaseModel):
+    """Schema 列定义。"""
+
+    model_config = ConfigDict(extra="ignore")
+    name: str = Field(..., description="列名")
+    type: str = Field(default="string", description="数据类型")
+
+
+class SchemaSpec(BaseModel):
+    """Schema 动作的 spec（schemaSpec）。"""
+
+    model_config = ConfigDict(extra="ignore")
+    name: str | None = Field(default=None, description="表名")
+    schemaId: str | None = Field(default=None, description="表 ID")
+    columns: list[SchemaColumnSpec] | None = Field(default=None, description="列定义")
+
+
+class RegexSpec(BaseModel):
+    """Regex 动作的 spec（regexSpec）。"""
+
+    model_config = ConfigDict(extra="ignore")
+    name: str | None = Field(default=None, description="正则节点名")
+    regexId: str | None = Field(default=None, description="正则节点 ID")
+    pattern: str | None = Field(default=None, description="正则表达式")
+    matchMode: str | None = Field(default="full", description="匹配模式 full/partial/extract")
+
+
+class TransformSpec(BaseModel):
+    """Transform 动作的 spec（transformSpec）。
+
+    注意：转换类型白名单不在 Pydantic 层校验——由 _transform_validator 负责（有建议）。
+    Pydantic 此处仅做字段类型与结构解析。
+    """
+
+    model_config = ConfigDict(extra="ignore")
+    type: str | None = Field(default=None, description="转换类型")
+    transformId: str | None = Field(default=None, description="转换节点 ID")
+    inputColumn: str | None = Field(default=None, description="输入列")
+    params: dict[str, Any] | None = Field(default=None, description="转换参数")
+    outputColumns: list[str] | None = Field(default=None, description="输出列")
+
+
+class SettingsSpec(BaseModel):
+    """Settings 动作的 spec（settingsSpec）。
+
+    注意：设置分类白名单不在 Pydantic 层校验——由 _settings_validator 负责（有建议）。
+    """
+
+    model_config = ConfigDict(extra="ignore")
+    category: str = Field(..., description="设置分类")
+    settings: dict[str, Any] = Field(..., description="设置键值")
+
+
+class CanvasSpec(BaseModel):
+    """ADD_TO_CANVAS 动作的 spec（canvasSpec）。
+
+    注意：资源类型白名单与存在性不在 Pydantic 层校验——由 _canvas_validator 负责
+    （查磁盘资源是否真实存在）。Pydantic 此处仅做字段结构解析。
+    """
+
+    model_config = ConfigDict(extra="ignore")
+    resourceKind: str = Field(..., description="资源类型 schema/regex/constraint/transform")
+    resourceId: str | None = Field(default=None, description="资源 ID")
+    resourceName: str | None = Field(default=None, description="资源名（兜底匹配）")
+    name: str | None = Field(default=None, description="资源名（别名）")
+
+
+# =============================================================================
+# 统一解析入口（适配层）
+# =============================================================================
+
+
+# actionType → spec 模型类的映射（从 registry 的 SPEC_FIELD_FOR 派生）
+_SPEC_MODEL_FOR: dict[str, type[BaseModel]] = {
+    "ADD_CONSTRAINT_NODE": ConstraintSpec,
+    "UPDATE_CONSTRAINT_NODE": ConstraintSpec,
+    "DELETE_CONSTRAINT_NODE": ConstraintSpec,
+    "VALIDATE_PROJECT": ValidateSpec,  # VALIDATE_PROJECT 的 constraintSpec 字段更宽松（type 可选）
+    "ADD_SCHEMA": SchemaSpec,
+    "UPDATE_SCHEMA": SchemaSpec,
+    "DELETE_SCHEMA": SchemaSpec,
+    "ADD_REGEX": RegexSpec,
+    "UPDATE_REGEX": RegexSpec,
+    "DELETE_REGEX": RegexSpec,
+    "ADD_TRANSFORM": TransformSpec,
+    "UPDATE_TRANSFORM": TransformSpec,
+    "DELETE_TRANSFORM": TransformSpec,
+    "UPDATE_SETTINGS": SettingsSpec,
+    "ADD_TO_CANVAS": CanvasSpec,
+}
+
+
+class SpecParseError(Exception):
+    """Spec 结构校验失败。message 含人类可读的错误描述。"""
+
+    def __init__(self, message: str, errors: list[str] | None = None):
+        super().__init__(message)
+        self.message = message
+        self.errors = errors or [message]
+
+
+# spec 字段名（constraintSpec 等内部名）→ 用户可读名称
+_SPEC_FIELD_ZH: dict[str, str] = {
+    "schemaSpec": "表结构配置",
+    "constraintSpec": "约束配置",
+    "regexSpec": "正则配置",
+    "transformSpec": "数据转换配置",
+    "settingsSpec": "项目设置",
+    "canvasSpec": "画布配置",
+}
+
+
+def _spec_field_zh(spec_field: str) -> str:
+    return _SPEC_FIELD_ZH.get(spec_field, spec_field)
+
+
+def parse_action_spec(action: dict[str, Any]) -> BaseModel:
+    """解析动作的 spec 字段并做**结构校验**。
+
+    根据 actionType 从 registry 查 spec 字段名，取出 spec dict，
+    用对应 Pydantic 模型校验。校验失败抛 SpecParseError（含全部错误列表）。
+
+    本函数只做结构校验；上下文校验（表/列/FK 是否存在）仍由各 validator 负责。
+
+    参数:
+        action: 动作字典，含 actionType 和对应 spec 字段
+
+    返回:
+        校验通过的 spec 模型实例
+
+    抛出:
+        SpecParseError: 结构校验失败（枚举非法、必填缺失、Range min>max 等）
+    """
+    from app.shared.services.llm.actions.registry import SPEC_FIELD_FOR
+
+    action_type = action.get("actionType", "")
+    spec_field = SPEC_FIELD_FOR.get(action_type)
+    model_cls = _SPEC_MODEL_FOR.get(action_type)
+
+    # 无 spec 字段要求的动作（理论上目前所有动作都有 spec，此分支为防御）
+    if spec_field is None or model_cls is None:
+        return EmptyParams()  # 返回空模型占位
+
+    spec_data = action.get(spec_field)
+    if spec_data is None:
+        # spec 缺失：对于 VALIDATE_PROJECT 是合法的（可空壳），其余视为结构错误
+        if action_type == "VALIDATE_PROJECT":
+            return EmptyParams()
+        raise SpecParseError(f"动作 {_spec_field_zh(spec_field)}缺失，请补全后重试")
+
+    if not isinstance(spec_data, dict):
+        raise SpecParseError(f"{_spec_field_zh(spec_field)}必须是对象，实际为 {type(spec_data).__name__}")
+
+    try:
+        return model_cls.model_validate(spec_data)
+    except Exception as e:  # noqa: BLE001  Pydantic ValidationError 及子类
+        # 提取 Pydantic 的字段级错误信息（英文校验消息做常见项中文映射，
+        # 未命中的保留原文；spec 字段名同步翻译，避免 constraintSpec 等内部名外露）
+        if isinstance(e, ValidationError):
+            messages = [
+                f"{'.'.join(str(x) for x in err['loc'])}: {localize_pydantic_msg(err['msg'])}" for err in e.errors()
+            ]
+        else:
+            messages = [str(e)]
+        raise SpecParseError(
+            f"{_spec_field_zh(spec_field)}校验失败: {'; '.join(localize_pydantic_msg(m) for m in messages)}",
+            messages,
+        ) from e

app/shared/services/llm/actions/transform_handlers.py

@@ -0,0 +1,279 @@
+# 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 Transform 动作处理器模块
+
+功能概述:
+- 处理 AI 生成的 Transform CRUD 动作（ADD_TRANSFORM / UPDATE_TRANSFORM / DELETE_TRANSFORM）
+- 通过 core 层 writer 持久化 Transform YAML 文件
+- 同步更新 project.precis.yaml 中的 TransformRef
+
+架构设计:
+- 复用 core/project/transform/writer.py 的 save_transform()
+- 复用 TransformFile Pydantic 模型确保类型安全
+- 使用 atomic_write_yaml 保证文件写入安全
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from app.shared.core.project.manifest.reader import load_manifest
+from app.shared.core.project.manifest.types import TransformRef
+from app.shared.core.project.manifest.writer import save_manifest
+from app.shared.core.project.transform.types import TransformFile
+from app.shared.core.project.transform.writer import save_transform
+from app.shared.services.llm.yaml_io import FileLock, atomic_write_yaml
+
+logger = logging.getLogger(__name__)
+
+# 转换子类型白名单从注册表派生（单一事实源）
+from app.shared.services.llm.actions.registry import TRANSFORM_SUB_TYPES as VALID_TRANSFORM_TYPES
+
+
+def _sanitize_resource_id(resource_id: str) -> str:
+    cleaned = os.path.basename(resource_id)
+    if "/" in resource_id or "\\" in resource_id or ".." in resource_id:
+        raise ValueError(f"非法的资源 ID: {resource_id!r}")
+    return cleaned
+
+
+def process_transform_action(action: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """
+    @methoddesc 处理 Transform 动作
+
+    根据 actionType 分发到对应的处理函数。
+
+    参数:
+        action: 动作字典，包含 actionType 和 transformSpec
+        workspace_path: 项目工作区路径
+
+    返回:
+        处理结果字典 {"success": bool, "message": str}
+    """
+    action_type = action.get("actionType", "")
+    spec = action.get("transformSpec", {})
+
+    if action_type == "ADD_TRANSFORM":
+        return _add_transform(spec, workspace_path)
+    elif action_type == "UPDATE_TRANSFORM":
+        return _update_transform(spec, workspace_path)
+    elif action_type == "DELETE_TRANSFORM":
+        return _delete_transform(spec, workspace_path)
+    else:
+        return {"success": False, "message": f"未知的 Transform 动作类型: {action_type}"}
+
+
+def _add_transform(spec: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """创建新的 Transform YAML 文件"""
+    transform_type = spec.get("type", "")
+    transform_id = spec.get("transformId") or spec.get("id") or _generate_transform_id(transform_type)
+    try:
+        transform_id = _sanitize_resource_id(transform_id)
+    except ValueError:
+        return {"success": False, "message": f"非法的 Transform ID: {transform_id}"}
+    description = spec.get("description")
+    input_from_node = spec.get("inputFromNode")
+    input_column = spec.get("inputColumn")
+    params = spec.get("params", {})
+    output_columns = spec.get("outputColumns", [])
+
+    if not transform_type:
+        return {"success": False, "message": "Transform 类型不能为空"}
+
+    if transform_type not in VALID_TRANSFORM_TYPES:
+        return {"success": False, "message": f"不支持的 Transform 类型: {transform_type}"}
+
+    workspace = Path(workspace_path)
+    transforms_dir = workspace / "transforms"
+    transforms_dir.mkdir(parents=True, exist_ok=True)
+
+    transform_file = transforms_dir / f"{transform_id}.transform.yaml"
+    if transform_file.exists():
+        # 提示 Agent 改用 ADD_TO_CANVAS（同 schema_handlers 的引导逻辑）
+        return {
+            "success": False,
+            "message": (
+                f"Transform 文件已存在: {transform_id}.transform.yaml。"
+                f"若用户想把已存在的资源显示到画布，请改用 actionType=ADD_TO_CANVAS"
+                f"（canvasSpec.resourceKind='transform'），它不会重复创建文件。"
+            ),
+        }
+
+    try:
+        transform = TransformFile(
+            version=2,
+            id=transform_id,
+            type=transform_type,
+            enabled=True,
+            description=description,
+            input_from_node=input_from_node,
+            input_column=input_column,
+            params=params,
+            output_columns=output_columns,
+        )
+        save_transform(transform, transform_file)
+    except Exception as e:
+        return {"success": False, "message": f"写入 Transform 文件失败: {e}"}
+
+    # 更新 manifest
+    _ensure_manifest_transform_ref(workspace_path, transform_id)
+
+    logger.info(f"[TransformHandler] 创建 Transform: {transform_id}")
+    return {"success": True, "message": transform_id}
+
+
+def _update_transform(spec: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """更新现有 Transform"""
+    transform_id = spec.get("transformId") or spec.get("id", "")
+    try:
+        transform_id = _sanitize_resource_id(transform_id)
+    except ValueError:
+        return {"success": False, "message": f"非法的 Transform ID: {transform_id}"}
+
+    if not transform_id:
+        return {"success": False, "message": "缺少 Transform ID"}
+
+    transform_file = _find_transform_file(workspace_path, transform_id)
+    if not transform_file:
+        return {"success": False, "message": f"Transform 文件不存在: {transform_id}"}
+
+    try:
+        with FileLock(str(transform_file)):
+            with open(transform_file, encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+
+            if spec.get("type") and spec["type"] in VALID_TRANSFORM_TYPES:
+                data["type"] = spec["type"]
+            if "description" in spec:
+                data["description"] = spec["description"]
+            if "params" in spec:
+                data["params"] = spec["params"]
+            if "inputFromNode" in spec:
+                data["input_from_node"] = spec["inputFromNode"]
+            if "inputColumn" in spec:
+                data["input_column"] = spec["inputColumn"]
+            if "outputColumns" in spec:
+                data["output_columns"] = spec["outputColumns"]
+
+            # §2.10: UPDATE 显式整体替换语义——preserve_format 默认 True 的递归合并
+            # "只增不删"，旧输出列 C 会残留在文件里（用户想把输出改成 A、B 结果是 A/B/C）
+            atomic_write_yaml(transform_file, data, preserve_format=False)
+
+    except Exception as e:
+        return {"success": False, "message": f"更新 Transform 失败: {e}"}
+
+    logger.info(f"[TransformHandler] 更新 Transform: {transform_id}")
+    return {"success": True, "message": transform_id}
+
+
+def _delete_transform(spec: dict[str, Any], workspace_path: str) -> dict[str, Any]:
+    """删除 Transform 文件"""
+    transform_id = spec.get("transformId") or spec.get("id", "")
+    try:
+        transform_id = _sanitize_resource_id(transform_id)
+    except ValueError:
+        return {"success": False, "message": f"非法的 Transform ID: {transform_id}"}
+
+    if not transform_id:
+        return {"success": False, "message": "缺少 Transform ID"}
+
+    transform_file = _find_transform_file(workspace_path, transform_id)
+    if not transform_file:
+        return {"success": False, "message": f"Transform 文件不存在: {transform_id}"}
+
+    try:
+        transform_file.unlink()
+    except OSError as e:
+        return {"success": False, "message": f"删除 Transform 文件失败: {e}"}
+
+    _remove_manifest_transform_ref(workspace_path, transform_id)
+
+    logger.info(f"[TransformHandler] 删除 Transform: {transform_id}")
+    return {"success": True, "message": transform_id}
+
+
+def _find_transform_file(workspace_path: str, transform_id: str) -> Path | None:
+    """在工作区中查找 transform 文件"""
+    transforms_dir = Path(workspace_path) / "transforms"
+    if not transforms_dir.exists():
+        return None
+
+    for tf in transforms_dir.glob("*.yaml"):
+        try:
+            with open(tf, encoding="utf-8") as f:
+                data = yaml.safe_load(f) or {}
+            if data.get("id") == transform_id:
+                return tf
+        except Exception:
+            continue
+
+    candidate = transforms_dir / f"{transform_id}.transform.yaml"
+    if candidate.exists():
+        return candidate
+
+    return None
+
+
+def _generate_transform_id(transform_type: str) -> str:
+    """生成 Transform ID"""
+    import re
+
+    safe = re.sub(r"[^a-z0-9_]", "_", transform_type.lower())
+    return f"{safe}_{_short_hash()}"
+
+
+def _short_hash() -> str:
+    """生成短随机哈希（§2.5: uuid4 前 8 位十六进制——原 random.randint(100,999)
+    仅 900 个桶，批量建 transform 时生日悖论约 35 个即碰撞过半，碰撞报"文件已存在"
+    会诱导 LLM 走错误的 ADD_TO_CANVAS/放弃路径）"""
+    import uuid
+
+    return uuid.uuid4().hex[:8]
+
+
+def _ensure_manifest_transform_ref(workspace_path: str, transform_id: str) -> None:
+    """确保 manifest 中包含指定 Transform 引用"""
+    manifest_path = Path(workspace_path) / "project.precis.yaml"
+    if not manifest_path.exists():
+        return
+
+    try:
+        manifest = load_manifest(manifest_path)
+        existing = next((t for t in manifest.transforms if t.id == transform_id), None)
+        if not existing:
+            manifest.transforms.append(TransformRef(id=transform_id, path=f"transforms/{transform_id}.transform.yaml"))
+            save_manifest(manifest, manifest_path)
+    except Exception as e:
+        logger.warning(f"[TransformHandler] 更新 manifest 引用失败: {e}")
+
+
+def _remove_manifest_transform_ref(workspace_path: str, transform_id: str) -> None:
+    """从 manifest 中移除指定 Transform 引用"""
+    manifest_path = Path(workspace_path) / "project.precis.yaml"
+    if not manifest_path.exists():
+        return
+
+    try:
+        manifest = load_manifest(manifest_path)
+        manifest.transforms = [t for t in manifest.transforms if t.id != transform_id]
+        save_manifest(manifest, manifest_path)
+    except Exception as e:
+        logger.warning(f"[TransformHandler] 更新 manifest 引用失败: {e}")

app/shared/services/llm/actions/validation_types.py

@@ -0,0 +1,147 @@
+# 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 动作验证器数据类型与格式化工具
+
+定义:
+- ValidationError: 验证错误信息数据类
+- ValidationResult: 验证结果聚合数据类
+- format_validation_result: 将结果格式化为可读文本
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ValidationError:
+    """验证错误信息
+
+    Attributes:
+        action_index: 动作在列表中的索引
+        action_type: 动作类型
+        error_type: 错误类型标识
+        message: 错误描述
+        suggestion: 修正建议（可选）
+        auto_fixable: 是否可以自动修正
+    """
+
+    action_index: int
+    action_type: str
+    error_type: str
+    message: str
+    suggestion: str | None = None
+    auto_fixable: bool = False
+
+
+@dataclass
+class ValidationResult:
+    """验证结果
+
+    Attributes:
+        errors: 错误列表（阻止执行）
+        warnings: 警告列表（不阻止执行）
+        valid_actions: 有效的动作列表
+        invalid_action_indices: 无效的动作索引集合
+    """
+
+    errors: list[ValidationError] = field(default_factory=list)
+    warnings: list[ValidationError] = field(default_factory=list)
+    valid_actions: list[dict[str, Any]] = field(default_factory=list)
+    invalid_action_indices: set[int] = field(default_factory=set)
+
+    @property
+    def has_errors(self) -> bool:
+        """是否有错误"""
+        return len(self.errors) > 0
+
+    @property
+    def has_warnings(self) -> bool:
+        """是否有警告"""
+        return len(self.warnings) > 0
+
+    @property
+    def all_valid(self) -> bool:
+        """是否全部有效"""
+        return len(self.errors) == 0 and len(self.invalid_action_indices) == 0
+
+    @property
+    def partial_valid(self) -> bool:
+        """是否部分有效（有错误但也有有效动作）"""
+        return len(self.errors) > 0 and len(self.valid_actions) > 0
+
+
+def action_display_name(action_type: str) -> str:
+    """把动作类型枚举（ADD_SCHEMA 等）翻译成用户可读的中文名。
+
+    派生规则：动词前缀 + registry 里的 category；特殊只读动作单独映射；
+    未登记的枚举回退原文（新增动作漏配时不会显示空白）。
+    """
+    special = {"VALIDATE_PROJECT": "校验项目", "ADD_TO_CANVAS": "添加到画布"}
+    if action_type in special:
+        return special[action_type]
+    verbs = {"ADD": "新增", "UPDATE": "修改", "DELETE": "删除"}
+    categories = {
+        "constraint": "约束",
+        "schema": "表结构",
+        "regex": "正则",
+        "transform": "数据转换",
+        "settings": "项目设置",
+    }
+    from app.shared.services.llm.actions.registry import get_action_def
+
+    d = get_action_def(action_type)
+    if d is not None:
+        verb = verbs.get(action_type.split("_", 1)[0], "")
+        category = categories.get(d.category)
+        if verb and category:
+            return f"{verb}{category}"
+    return action_type
+
+
+def format_validation_result(result: ValidationResult) -> str:
+    """格式化验证结果为可读文本
+
+    参数:
+        result: 验证结果
+
+    返回:
+        格式化后的文本
+    """
+    lines = []
+
+    if result.all_valid and not result.warnings:
+        return "所有操作验证通过"
+
+    if result.errors:
+        lines.append(f"发现 {len(result.errors)} 个问题：")
+        for error in result.errors:
+            lines.append(f"\n  [{error.action_index + 1}] {action_display_name(error.action_type)}")
+            lines.append(f"      问题: {error.message}")
+            if error.suggestion:
+                lines.append(f"      建议: {error.suggestion}")
+
+    if result.warnings:
+        lines.append(f"\n另有 {len(result.warnings)} 个提醒：")
+        for warning in result.warnings:
+            lines.append(f"  - {warning.message}")
+
+    if result.partial_valid:
+        lines.append(f"\n其中 {len(result.valid_actions)} 个操作有效，{len(result.invalid_action_indices)} 个操作无效")
+
+    return "\n".join(lines)