precis-cli 0.1.3__py3-none-any.whl

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

@@ -0,0 +1,78 @@
+# 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 相关动作（ADD_TRANSFORM/UPDATE_TRANSFORM/DELETE_TRANSFORM）
+的类型、参数合法性。
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from app.shared.services.llm.actions.registry import TRANSFORM_SUB_TYPES
+from app.shared.services.llm.actions.validation_types import ValidationError
+
+# 转换子类型白名单从注册表派生（单一事实源）
+VALID_TRANSFORM_TYPE_NAMES = TRANSFORM_SUB_TYPES
+
+
+def validate_transform_action(action: dict[str, Any], index: int) -> list[ValidationError]:
+    """验证 Transform 操作
+
+    检查 transformSpec 中的类型、参数合法性。
+    """
+    errors = []
+    action_type = action.get("actionType", "")
+    spec = action.get("transformSpec", {})
+
+    if action_type == "ADD_TRANSFORM":
+        transform_type = spec.get("type", "")
+        if not transform_type:
+            errors.append(
+                ValidationError(
+                    action_index=index,
+                    action_type=action_type,
+                    error_type="missing_transform_type",
+                    message="Transform 类型不能为空",
+                    suggestion=f"可选: {', '.join(sorted(VALID_TRANSFORM_TYPE_NAMES))}",
+                )
+            )
+        elif transform_type not in VALID_TRANSFORM_TYPE_NAMES:
+            errors.append(
+                ValidationError(
+                    action_index=index,
+                    action_type=action_type,
+                    error_type="invalid_transform_type",
+                    message=f"不支持的 Transform 类型: '{transform_type}'",
+                    suggestion=f"可选: {', '.join(sorted(VALID_TRANSFORM_TYPE_NAMES))}",
+                )
+            )
+
+    if action_type in ("UPDATE_TRANSFORM", "DELETE_TRANSFORM"):
+        transform_id = spec.get("transformId") or spec.get("id")
+        if not transform_id:
+            errors.append(
+                ValidationError(
+                    action_index=index,
+                    action_type=action_type,
+                    error_type="missing_transform_id",
+                    message="更新/删除 Transform 需要指定 transformId",
+                )
+            )
+
+    return errors

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

@@ -0,0 +1,400 @@
+# 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 动作执行处理器模块
+
+功能概述:
+- 处理约束的 YAML 配置更新（添加、更新、删除）
+- 批量处理内联约束（同一 schema 合并为一次文件读写）
+- 执行项目数据校验
+- 生成前端渲染指令
+
+输入示例:
+    success, message = update_yaml_config(action, "/workspace")
+    results = process_inline_batch(actions, "/workspace")
+    result = execute_validate_project("/workspace", table_filter="users")
+
+输出示例:
+    (True, "notnull_users_email")
+    [{"action": action, "success": True, "message": "..."}]
+    {"success": True, "message": "校验通过", "details": {...}}
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from app.shared.core.project.constraint.types import ConstraintFile
+from app.shared.core.project.constraint.writer import save_constraint
+from app.shared.core.project.manifest.reader import load_manifest
+from app.shared.core.project.manifest.writer import ensure_constraint_ref, save_manifest
+from app.shared.services.llm.actions.regex_handlers import process_regex_action
+from app.shared.services.llm.actions.schema_handlers import process_schema_action
+from app.shared.services.llm.actions.settings_handlers import process_settings_action
+from app.shared.services.llm.actions.transform_handlers import process_transform_action
+from app.shared.services.llm.constraints.constraint_builder import (
+    CONSTRAINT_TYPE_MAP,
+    _build_constraint_params,
+    _build_constraint_refs,
+)
+from app.shared.services.llm.constraints.constraint_deletion import delete_constraint_file
+from app.shared.services.llm.constraints.constraint_id import _generate_constraint_id
+from app.shared.services.llm.constraints.frontend_instructions import generate_frontend_instructions
+from app.shared.services.llm.constraints.inline_batch import (
+    _collect_target_schema_id,
+    _is_inline_action,
+    process_inline_batch,
+)
+from app.shared.services.llm.validate_executor import execute_validate_project
+from app.shared.services.llm.yaml_io import FileLock, YamlUpdateError, atomic_write_yaml
+
+logger = logging.getLogger(__name__)
+
+# 重新导出子模块函数，保持向后兼容
+__all__ = [
+    "update_yaml_config",
+    "delete_constraint_file",
+    "generate_frontend_instructions",
+    "execute_validate_project",
+    "_collect_target_schema_id",
+    "_is_inline_action",
+    "process_inline_batch",
+    "process_schema_action",
+    "process_regex_action",
+    "process_transform_action",
+    "process_settings_action",
+]
+
+
+def _ensure_manifest_constraint_ref(workspace_path: str, constraint_id: str) -> None:
+    """确保 manifest 中包含指定独立约束的引用（镜像 _ensure_manifest_schema_ref）。
+
+    失败时抛出异常 —— 避免约束文件已写盘但 manifest 未登记，
+    导致校验引擎永不加载该约束（C1：静默失效）。
+    """
+    manifest_path = Path(workspace_path) / "project.precis.yaml"
+    if not manifest_path.exists():
+        return
+
+    manifest = load_manifest(manifest_path)
+    ensure_constraint_ref(manifest, constraint_id)
+    save_manifest(manifest, manifest_path)
+
+
+def _remove_manifest_constraint_ref(workspace_path: str, constraint_id: str) -> None:
+    """从 manifest 中移除指定独立约束的引用（镜像 _remove_manifest_schema_ref）。
+
+    失败时抛出异常 —— 避免约束文件已删除但 manifest 仍残留引用（dangling ref）。
+    """
+    manifest_path = Path(workspace_path) / "project.precis.yaml"
+    if not manifest_path.exists():
+        return
+
+    manifest = load_manifest(manifest_path)
+    manifest.constraints = [c for c in manifest.constraints if c.id != constraint_id]
+    save_manifest(manifest, manifest_path)
+
+
+def _delete_inline_constraint(
+    std_type: str,
+    workspace_path: str,
+    table_name: str,
+    target_column: str,
+    target_node_id: str,
+    target_column_id: str,
+) -> tuple[bool, str]:
+    """从 schema 文件中删除内联约束
+
+    定位方式与添加/更新内联约束保持一致：schema 按 id/name 匹配，
+    列按传入 ID 或名称解析，约束项按「同列 + 同类型」匹配（镜像内联分支的既有约束查找）。
+
+    参数:
+        std_type: 标准化后的约束类型（如 NotNull）
+        workspace_path: 项目工作区路径
+        table_name: 目标表名
+        target_column: 目标列名
+        target_node_id: 目标表节点 ID（优先用于匹配 schema 文件）
+        target_column_id: 目标列 ID（优先用于匹配列）
+
+    返回:
+        元组 (是否成功, 约束ID 或错误信息)
+    """
+    try:
+        schemas_dir = Path(workspace_path) / "schemas"
+        target_table_id = target_node_id or table_name
+        schema_file = None
+
+        for sf in schemas_dir.glob("*.yaml"):
+            with open(sf, encoding="utf-8") as f:
+                sd = yaml.safe_load(f) or {}
+            if sd.get("id") == target_table_id or sd.get("name") == table_name:
+                schema_file = sf
+                break
+
+        if not schema_file:
+            return False, f"未找到 schema 文件: {target_table_id}"
+
+        with FileLock(str(schema_file)):
+            # 重新读取文件（确保在锁保护下读取最新内容）
+            with open(schema_file, encoding="utf-8") as f:
+                schema_data = yaml.safe_load(f) or {}
+
+            columns = schema_data.get("columns", [])
+            column_id = target_column_id
+            if not column_id:
+                for col in columns:
+                    if col.get("name") == target_column:
+                        column_id = col.get("id")
+                        break
+
+            if not column_id:
+                return False, f"未找到列: {target_column}"
+
+            constraints = schema_data.get("constraints", [])
+            # 移除「同列 + 同类型」的内联约束项，其余保持不变
+            remaining = [c for c in constraints if not (c.get("column") == column_id and c.get("type") == std_type)]
+            if len(remaining) == len(constraints):
+                return False, f"未找到内联约束: {std_type} on {table_name}.{target_column}"
+
+            schema_data["constraints"] = remaining
+            # 必须全量替换写入：atomic_write_yaml 的 preserve_format 路径按 id
+            # 合并列表（只更新/追加、不删除），会把本次删除的约束"复活"
+            atomic_write_yaml(schema_file, schema_data, preserve_format=False)
+
+        constraint_id = _generate_constraint_id(std_type, table_name or "inline", target_column)
+        logger.info(f"[updateYamlConfig] 删除内联约束: {constraint_id}")
+        return True, f"inline:{constraint_id}"
+
+    except YamlUpdateError as e:
+        error_msg = f"删除内联约束失败: {str(e)}"
+        logger.error(f"[updateYamlConfig] {error_msg}")
+        return False, error_msg
+    except OSError as e:
+        error_msg = f"删除内联约束文件操作失败: {str(e)}"
+        logger.error(f"[updateYamlConfig] {error_msg}")
+        return False, error_msg
+    except Exception as e:
+        error_msg = f"删除内联约束失败: {str(e)}"
+        logger.error(f"[updateYamlConfig] {error_msg}")
+        return False, error_msg
+
+
+def update_yaml_config(action: dict[str, Any], workspace_path: str) -> tuple[bool, str]:
+    """
+    @methoddesc 更新 YAML 配置文件
+
+    将 LLM 返回的约束动作写入到项目的 constraints 目录或 schema 文件的内联约束中。
+    支持添加、更新、删除三种操作类型，以及内联和独立两种约束存储方式。
+
+    参数:
+        action: 动作字典，包含 actionType 和 constraintSpec
+        workspace_path: 工作区路径
+
+    返回:
+        元组 (是否成功, 错误信息或约束ID)
+
+    示例:
+        >>> success, msg = update_yaml_config(
+        ...     {"actionType": "ADD_CONSTRAINT_NODE", "constraintSpec": {...}},
+        ...     "/workspace"
+        ... )
+    """
+    action_type = action.get("actionType")
+    constraint_spec = action.get("constraintSpec", {})
+
+    constraint_type = constraint_spec.get("type", "")
+    table_name = constraint_spec.get("tableName", "")
+    target_column = constraint_spec.get("targetColumn", "")
+    target_node_id = constraint_spec.get("targetNodeId", "")
+    target_column_id = constraint_spec.get("targetColumnId", "")
+    is_inline = constraint_spec.get("isInline", False)
+
+    # 统一转换类型名
+    std_type = CONSTRAINT_TYPE_MAP.get(constraint_type, constraint_type)
+
+    if not std_type or not target_column:
+        error_msg = f"无效的约束规格: constraint_type={constraint_type}, std_type={std_type}, table_name={table_name}, target_column={target_column}"
+        logger.error(f"[updateYamlConfig] {error_msg}")
+        return False, error_msg
+
+    # 确定用于文件名的表标识符 (优先使用可读的名称)
+    filename_table = table_name or target_node_id or "unknown"
+    filename_column = target_column or target_column_id or "unknown"
+
+    # DELETE 动作必须先于 is_inline 分支处理：删除语义与存储形态无关，
+    # 旧实现 isInline=true 时先命中内联"添加"分支，只增不删还误报 success。
+    # 内联约束从 schema 文件的 constraints 列表移除，独立约束删除 .constraint.yaml 文件。
+    if action_type == "DELETE_CONSTRAINT_NODE":
+        if is_inline:
+            return _delete_inline_constraint(
+                std_type=std_type,
+                workspace_path=workspace_path,
+                table_name=table_name,
+                target_column=target_column,
+                target_node_id=target_node_id,
+                target_column_id=target_column_id,
+            )
+        # 删除独立约束文件
+        success, message = delete_constraint_file(std_type, filename_table, filename_column, workspace_path)
+        # 同步从 manifest 移除引用（避免 dangling ref）
+        if success:
+            try:
+                deleted_constraint_id = _generate_constraint_id(std_type, filename_table or "inline", filename_column)
+                _remove_manifest_constraint_ref(workspace_path, deleted_constraint_id)
+            except Exception as e:
+                # 文件已删成功，manifest 清理失败仅告警（不回滚文件删除）
+                logger.warning(f"[updateYamlConfig] 删除 manifest 引用失败（文件已删）: {e}")
+        return success, message
+
+    if is_inline:
+        logger.info(f"[updateYamlConfig] 内联约束: {std_type} on {filename_table}.{filename_column}")
+        constraint_id = _generate_constraint_id(std_type, filename_table or "inline", filename_column)
+
+        # 将内联约束添加到 schema 文件
+        try:
+            schemas_dir = Path(workspace_path) / "schemas"
+
+            # 查找匹配的 schema 文件
+            target_table_id = target_node_id or table_name
+            schema_file = None
+
+            for sf in schemas_dir.glob("*.yaml"):
+                with open(sf, encoding="utf-8") as f:
+                    sd = yaml.safe_load(f) or {}
+                if sd.get("id") == target_table_id or sd.get("name") == table_name:
+                    schema_file = sf
+                    break
+
+            if not schema_file:
+                # 找不到匹配的 schema 文件时必须返回失败，否则会静默成功
+                # 并触发前端生成幽灵节点（画布有、文件无）。对齐 process_inline_batch 的行为。
+                error_msg = f"未找到 schema 文件: {target_table_id}"
+                logger.warning(f"[updateYamlConfig] {error_msg}")
+                return False, error_msg
+
+            # 使用文件锁保护写入操作
+            with FileLock(str(schema_file)):
+                # 重新读取文件（确保在锁保护下读取最新内容）
+                with open(schema_file, encoding="utf-8") as f:
+                    schema_data = yaml.safe_load(f) or {}
+
+                columns = schema_data.get("columns", [])
+                if "constraints" not in schema_data:
+                    schema_data["constraints"] = []
+
+                # 查找目标列的 ID（优先使用传入的 ID，否则按名称查找）
+                column_id = target_column_id
+                if not column_id:
+                    for col in columns:
+                        if col.get("name") == target_column:
+                            column_id = col.get("id")
+                            break
+
+                if not column_id:
+                    # 目标列不存在时必须返回失败，否则会静默成功（与 process_inline_batch 对齐）。
+                    error_msg = f"未找到列: {target_column}"
+                    logger.warning(f"[updateYamlConfig] {error_msg}")
+                    return False, error_msg
+
+                # 构建内联约束结构
+                inline_constraint = {
+                    "id": constraint_id,
+                    "column": column_id,
+                    "type": std_type,
+                }
+                params = _build_constraint_params(std_type, constraint_spec)
+                if params:
+                    inline_constraint["params"] = params
+
+                # 检查是否已存在相同列和类型的约束
+                existing_idx = None
+                for idx, existing in enumerate(schema_data["constraints"]):
+                    if existing.get("column") == column_id and existing.get("type") == std_type:
+                        existing_idx = idx
+                        break
+
+                if existing_idx is not None:
+                    # 更新现有约束
+                    schema_data["constraints"][existing_idx] = inline_constraint
+                    logger.info(f"[updateYamlConfig] 更新内联约束: {constraint_id}")
+                else:
+                    # 添加新约束
+                    schema_data["constraints"].append(inline_constraint)
+                    logger.info(f"[updateYamlConfig] 添加内联约束: {constraint_id}")
+
+                # 原子性写入
+                atomic_write_yaml(schema_file, schema_data)
+                return True, f"inline:{constraint_id}"
+
+        except YamlUpdateError as e:
+            error_msg = f"YAML 更新失败: {str(e)}"
+            logger.error(f"[updateYamlConfig] {error_msg}")
+            return False, error_msg
+        except OSError as e:
+            error_msg = f"文件操作失败: {str(e)}"
+            logger.error(f"[updateYamlConfig] {error_msg}")
+            return False, error_msg
+        except Exception as e:
+            error_msg = f"保存约束配置失败: {str(e)}"
+            logger.error(f"[updateYamlConfig] {error_msg}")
+            return False, error_msg
+
+    else:
+        # 添加/更新独立约束文件
+        constraint_id = _generate_constraint_id(std_type, filename_table, filename_column)
+        constraint_file_path = Path(workspace_path) / "constraints" / f"{constraint_id}.constraint.yaml"
+
+        try:
+            # §2.4: ADD 存在性检查——原实现直写覆盖，同列第二个同类型约束静默顶掉第一个。
+            # 已存在时引导走 UPDATE；删除语义（DELETE 分支在前）不受影响。
+            if action_type == "ADD_CONSTRAINT_NODE" and constraint_file_path.exists():
+                error_msg = f"约束已存在（id={constraint_id}），如需修改请用 UPDATE，如需新建请先删除现有约束。"
+                logger.warning(f"[updateYamlConfig] {error_msg}")
+                return False, error_msg
+
+            # 构建约束配置
+            constraint_config = ConstraintFile(
+                version=2,
+                id=constraint_id,
+                type=std_type,
+                enabled=True,
+                description=None,
+                refs=_build_constraint_refs(std_type, table_name, target_column, constraint_spec, workspace_path),
+                params=_build_constraint_params(std_type, constraint_spec),
+                input_from_node=None,
+                input_column=None,
+            )
+
+            # 保存约束文件
+            save_constraint(constraint_config, str(constraint_file_path))
+            # 注册到 manifest（C1 修复：否则约束文件成为孤儿，校验引擎永不加载）
+            try:
+                _ensure_manifest_constraint_ref(workspace_path, constraint_id)
+            except Exception as e:
+                logger.error(f"[updateYamlConfig] 登记 manifest 失败，回滚约束文件: {e}")
+                constraint_file_path.unlink(missing_ok=True)
+                return False, f"更新 manifest 引用失败: {e}"
+            logger.info(f"[updateYamlConfig] 成功保存约束: {constraint_id}")
+            return True, constraint_id
+
+        except Exception as e:
+            error_msg = f"保存约束配置失败: {str(e)}"
+            logger.error(f"[updateYamlConfig] {error_msg}")
+            return False, error_msg

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

@@ -0,0 +1,63 @@
+# 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 Chat 动作解析器模块
+
+功能概述:
+- 解析 LLM 返回的 JSON 动作列表并执行对应的业务操作
+- 支持约束创建、更新、删除，Schema 更新，项目校验等动作
+- 本模块为入口文件，具体的 YAML IO、Schema 解析、约束构建、动作处理
+  已拆分到同目录下的专用子模块中
+
+架构设计:
+- ActionParser 类负责 LLM 响应的解析与验证（见 chat/response_parser.py）
+- process_actions() 为业务入口，协调各子模块完成动作执行（见 actions/action_processor.py）
+
+输入示例:
+    actions = [
+        {
+            "action": "create_constraint",
+            "tableName": "users",
+            "constraintType": "Unique",
+            "columnNames": ["email"]
+        }
+    ]
+    result = process_actions(actions, workspace_path="/path/to/project")
+
+输出示例:
+    {
+        "success": True,
+        "message": "成功处理 1 个动作",
+        "details": [{"action": "create_constraint", "status": "success"}]
+    }
+"""
+
+from __future__ import annotations
+
+# 重新导出 process_actions，保持向后兼容。
+# 注意：ActionParser 不在此 re-export——它在 response_parser.py 定义，
+# 而 response_parser 现在依赖 actions.registry，re-export 会形成循环导入
+# （response_parser → actions.registry → actions/__init__ → action_parser → response_parser）。
+# 调用方应直接 from app.shared.services.llm.chat.response_parser import ActionParser。
+from app.shared.services.llm.actions.action_processor import process_actions
+from app.shared.services.llm.actions.registry import CONSTRAINT_TYPE_ALIASES as CONSTRAINT_TYPE_MAP
+from app.shared.services.llm.yaml_io import ActionParseError
+
+__all__ = [
+    "ActionParseError",
+    "CONSTRAINT_TYPE_MAP",
+    "process_actions",
+]