precis-cli 0.1.3__py3-none-any.whl

app/shared/services/llm/yaml_io.py

@@ -0,0 +1,406 @@
+# 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 原子写入与文件锁模块
+
+功能概述:
+- 跨平台文件锁（Windows msvcrt / Unix fcntl）保证并发安全
+- 原子性 YAML 文件写入（先写临时文件再重命名）
+- 优先使用 ruamel.yaml 保留注释和格式，回退到标准 yaml
+
+架构设计:
+- FileLock 上下文管理器实现跨平台文件锁
+- atomic_write_yaml 提供原子写入能力
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+import time
+import uuid
+from io import TextIOWrapper
+from pathlib import Path
+from types import TracebackType
+from typing import Any, Literal
+
+logger = logging.getLogger(__name__)
+
+# 陈旧锁判定阈值（秒）：锁文件 mtime 超过该值视为持有进程已崩溃残留。
+# 正常写 YAML 的持锁时长远小于该值；Windows 的 open(lock, "x") 独占创建
+# 在进程崩溃后不会自动释放（.lock 文件残留），只能按时间阈值接管。
+STALE_LOCK_SECONDS = 30.0
+
+# 文件锁导入（跨平台支持）
+msvcrt: Any = None
+fcntl: Any = None
+_HAS_FILE_LOCK = False
+
+try:
+    # Windows
+    import msvcrt
+
+    _HAS_FILE_LOCK = True
+    logger.debug("文件锁: 使用 Windows msvcrt 模式")
+except ImportError:
+    logger.debug("Windows文件锁模块未安装", exc_info=True)
+
+if not _HAS_FILE_LOCK:
+    try:
+        # Unix/Linux/Mac
+        import fcntl
+
+        _HAS_FILE_LOCK = True
+        logger.debug("文件锁: 使用 Unix fcntl 模式")
+    except ImportError:
+        pass
+
+if not _HAS_FILE_LOCK:
+    logger.warning("文件锁功能不可用，并发写入时可能存在竞态条件风险")
+
+
+class ActionParseError(Exception):
+    """
+    @classdesc 动作解析异常
+
+    当 LLM 返回的响应无法解析为有效 JSON 时抛出。
+    """
+
+    pass
+
+
+class YamlUpdateError(Exception):
+    """
+    @classdesc YAML 更新异常
+
+    当 YAML 文件的原子写入或文件锁操作失败时抛出。
+    """
+
+    pass
+
+
+class FileLock:
+    """
+    @classdesc 跨平台文件锁上下文管理器
+
+    支持 Windows(msvcrt) 和 Unix(fcntl) 两种文件锁实现，
+    通过上下文管理器确保并发写入安全。
+
+    使用场景:
+    - 多个进程/线程同时写入同一 YAML 文件时防止数据损坏
+    - 内联约束批量处理时的文件访问控制
+
+    使用示例:
+        with FileLock("/path/to/file.yaml"):
+            # 独占访问文件
+            with open("/path/to/file.yaml", 'w') as f:
+                yaml.dump(data, f)
+    """
+
+    def __init__(self, file_path: str, timeout: float = 10.0, stale_seconds: float = STALE_LOCK_SECONDS):
+        """
+        @methoddesc 初始化文件锁
+
+        参数:
+            file_path: 要加锁的文件路径
+            timeout: 获取锁的超时时间（秒），默认 10 秒
+            stale_seconds: 陈旧锁判定阈值（秒），锁文件 mtime 超过该值视为崩溃残留并接管
+        """
+        self.file_path = file_path
+        self.timeout = timeout
+        self.stale_seconds = stale_seconds
+        self.lock_file: TextIOWrapper | None = None
+        self.lock_path = f"{file_path}.lock"
+        # 本持有者的唯一令牌：获取锁时写入锁文件，释放前重验归属，避免误删他人重建的锁
+        self._lock_token: str | None = None
+
+    def _break_stale_lock(self) -> None:
+        """陈旧锁检测：锁文件 mtime 超过 stale_seconds 视为持有进程已崩溃，删除后可重试获取。
+
+        仅处理"进程崩溃残留"场景——持锁进程存活时其 mtime 会不断刷新吗？不会，
+        但正常持锁时长（单次 YAML 原子写入）远小于阈值，误接管的概率可忽略；
+        删除失败（他方并发占用）时静默返回，交由外层重试循环处理。
+        """
+        try:
+            stat_result = os.stat(self.lock_path)
+        except OSError:
+            return  # 锁文件不存在，无需处理
+        age = time.time() - stat_result.st_mtime
+        if age <= self.stale_seconds:
+            return
+        try:
+            os.remove(self.lock_path)
+            logger.warning(f"检测到陈旧文件锁（{age:.0f}s 前残留），已接管: {self.lock_path}")
+        except OSError:
+            logger.debug("删除陈旧锁文件失败（可能被并发占用）", exc_info=True)
+
+    def __enter__(self) -> FileLock:
+        """
+        @methoddesc 获取文件锁
+
+        进入上下文时尝试获取文件锁，如果锁已被占用则等待，
+        超过 timeout 时间后抛出 YamlUpdateError。
+        每次尝试前先做陈旧锁检测，避免崩溃进程残留的 .lock 文件导致永久超时。
+
+        返回:
+            FileLock 实例自身
+        """
+        if not _HAS_FILE_LOCK:
+            logger.debug(f"文件锁不可用，跳过加锁: {self.file_path}")
+            return self
+
+        start_time = time.time()
+
+        while True:
+            try:
+                if msvcrt:
+                    # Windows: 先做陈旧锁检测，再用独占模式打开锁文件
+                    self._break_stale_lock()
+                    self.lock_file = open(self.lock_path, "x")  # 独占创建
+                else:
+                    # Unix: 使用 fcntl 文件锁
+                    self.lock_file = open(self.lock_path, "w")
+                    fcntl.flock(self.lock_file.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+
+                # 写入唯一令牌（进程号 + 随机串）：释放前重验锁文件归属，
+                # 缓解"自己持有的锁已被陈旧检测接管、他人重建新锁"时的误删竞态
+                self._lock_token = f"{os.getpid()}-{uuid.uuid4().hex}"
+                try:
+                    self.lock_file.write(self._lock_token)
+                    self.lock_file.flush()
+                except OSError:
+                    # 令牌写入失败时释放路径退化为直接删除（保持旧行为）
+                    logger.debug("写入锁令牌失败", exc_info=True)
+
+                logger.debug(f"获取文件锁成功: {self.lock_path}")
+                return self
+
+            except OSError as e:
+                if self.lock_file:
+                    self.lock_file.close()
+                    self.lock_file = None
+
+                if time.time() - start_time > self.timeout:
+                    raise YamlUpdateError(f"获取文件锁超时: {self.lock_path}") from e
+
+                time.sleep(0.1)  # 100ms 后重试
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> Literal[False]:
+        """
+        @methoddesc 释放文件锁
+
+        退出上下文时释放文件锁并尝试删除锁文件。
+        删除前先 close 自身句柄，再重验锁文件内容是否仍为本次写入的令牌：
+        若内容已变（自己的锁被陈旧检测接管、他人重建了新锁）则跳过删除，避免误删他人锁。
+        不会吞掉异常。
+
+        返回:
+            False（不吞掉异常）
+        """
+        if self.lock_file:
+            try:
+                # 只在有 fcntl 模块的系统上解锁（Unix）
+                if fcntl is not None:
+                    fcntl.flock(self.lock_file.fileno(), fcntl.LOCK_UN)
+                # 先 close 自身句柄再删除，缩短"句柄未关即删"的窗口
+                self.lock_file.close()
+
+                # 删除前重验所有权：锁文件内容不再是自己的令牌 → 已被他人接管，跳过删除
+                if self._lock_token is not None:
+                    try:
+                        with open(self.lock_path, encoding="utf-8") as lf:
+                            current_token = lf.read()
+                        if current_token != self._lock_token:
+                            logger.debug("锁文件已被其他持有者接管，跳过删除: %s", self.lock_path)
+                            return False
+                    except FileNotFoundError:
+                        # 锁文件已不存在（被接管删除），无需再删
+                        return False
+                    except OSError:
+                        logger.debug("重读锁文件失败，按原行为尝试删除", exc_info=True)
+
+                # 尝试删除锁文件
+                try:
+                    os.remove(self.lock_path)
+                except OSError:
+                    logger.debug("删除锁文件失败", exc_info=True)
+
+                logger.debug(f"释放文件锁: {self.lock_path}")
+            except Exception as e:
+                logger.warning(f"释放文件锁时出错: {e}")
+
+        return False  # 不吞掉异常
+
+
+def atomic_write_yaml(file_path: Path, data: dict[str, Any], preserve_format: bool = True) -> None:
+    """
+    @methoddesc 原子性写入 YAML 文件
+
+    先写入临时文件，再重命名，确保不会因为崩溃导致原文件损坏。
+    当 preserve_format=True 且文件存在时，使用 ruamel.yaml 保留注释和空行。
+
+    参数:
+        file_path: 目标文件路径
+        data: 要写入的数据字典
+        preserve_format: 是否保留原有格式（注释、空行等）
+
+    异常:
+        YamlUpdateError: 写入失败时抛出
+
+    示例:
+        >>> atomic_write_yaml(Path("config.yaml"), {"version": 2})
+    """
+    import yaml
+
+    file_path = Path(file_path)
+
+    try:
+        # 如果文件已存在且需要保留格式，使用 ruamel.yaml
+        if preserve_format and file_path.exists():
+            try:
+                from ruamel.yaml import YAML
+
+                # 使用 ruamel.yaml 加载保留格式的 YAML
+                yaml_parser = YAML()
+                yaml_parser.preserve_quotes = True
+                yaml_parser.default_flow_style = False
+
+                with open(file_path, encoding="utf-8") as f:
+                    existing_data = yaml_parser.load(f)
+
+                if existing_data is not None:
+                    # 递归更新数据，保留格式
+                    _update_yaml_data(existing_data, data)
+
+                    # 原子性写入
+                    fd, temp_path = tempfile.mkstemp(
+                        dir=file_path.parent, prefix=f".{file_path.stem}_tmp_", suffix=".yaml"
+                    )
+
+                    try:
+                        with os.fdopen(fd, "w", encoding="utf-8") as f:
+                            yaml_parser.dump(existing_data, f)
+                        os.replace(temp_path, file_path)
+                        logger.debug(f"原子写入成功(保留格式): {file_path}")
+                        return
+                    except OSError:
+                        try:
+                            os.remove(temp_path)
+                        except OSError:
+                            logger.debug("删除临时文件失败", exc_info=True)
+                        raise
+            except ImportError:
+                logger.warning("ruamel.yaml 未安装，无法保留 YAML 格式")
+            except Exception as e:
+                logger.warning(f"使用 ruamel.yaml 失败，回退到标准方式: {e}")
+
+        # 标准写入方式（不保留格式）
+        fd, temp_path = tempfile.mkstemp(dir=file_path.parent, prefix=f".{file_path.stem}_tmp_", suffix=".yaml")
+
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as f:
+                yaml.safe_dump(data, f, allow_unicode=True, sort_keys=False)
+
+            os.replace(temp_path, file_path)
+            logger.debug(f"原子写入成功: {file_path}")
+
+        except OSError:
+            try:
+                os.remove(temp_path)
+            except OSError:
+                logger.debug("删除临时文件失败", exc_info=True)
+            raise
+
+    except Exception as e:
+        raise YamlUpdateError(f"原子写入失败: {file_path}") from e
+
+
+def _update_yaml_data(existing: Any, new: Any) -> None:
+    """
+    @methoddesc 递归更新 YAML 数据，保留现有格式
+
+    用于 ruamel.yaml 加载的数据结构，在保留注释和格式的前提下递归更新数据。
+
+    参数:
+        existing: 现有的 YAML 数据结构（来自 ruamel.yaml）
+        new: 新的数据字典
+    """
+    from ruamel.yaml.comments import CommentedMap, CommentedSeq
+
+    if isinstance(existing, CommentedMap) and isinstance(new, dict):
+        # 更新或添加键值
+        for key, value in new.items():
+            if key in existing:
+                if isinstance(value, dict) and isinstance(existing[key], CommentedMap):
+                    _update_yaml_data(existing[key], value)
+                elif isinstance(value, list) and isinstance(existing[key], CommentedSeq):
+                    _update_yaml_list(existing[key], value)
+                else:
+                    existing[key] = value
+            else:
+                # 新键，直接添加
+                existing[key] = value
+    elif isinstance(existing, CommentedSeq) and isinstance(new, list):
+        _update_yaml_list(existing, new)
+
+
+def _update_yaml_list(existing_list: Any, new_list: list) -> None:
+    """
+    @methoddesc 更新 YAML 列表，保留现有格式
+
+    用于更新 constraints 等列表，根据 id 匹配更新现有项或添加新项。
+    没有 id 的项直接追加到列表末尾。
+
+    参数:
+        existing_list: 现有的 YAML 列表（来自 ruamel.yaml）
+        new_list: 新的数据列表
+    """
+    from ruamel.yaml.comments import CommentedMap
+
+    if not new_list:
+        return
+
+    # 为现有项建立 id 到索引的映射
+    existing_ids = {}
+    for idx, item in enumerate(existing_list):
+        if isinstance(item, CommentedMap) and "id" in item:
+            existing_ids[item["id"]] = idx
+
+    # 处理新列表中的每一项
+    for new_item in new_list:
+        if isinstance(new_item, dict) and "id" in new_item:
+            item_id = new_item["id"]
+            if item_id in existing_ids:
+                # 更新现有项
+                idx = existing_ids[item_id]
+                existing_item = existing_list[idx]
+                if isinstance(existing_item, CommentedMap):
+                    _update_yaml_data(existing_item, new_item)
+                else:
+                    existing_list[idx] = new_item
+            else:
+                # 添加新项
+                existing_list.append(new_item)
+        else:
+            # 没有 id 的项，直接添加
+            if new_item not in existing_list:
+                existing_list.append(new_item)

app/shared/services/preview/__init__.py

@@ -0,0 +1,18 @@
+# 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 预览服务统一入口
+"""

app/shared/services/preview/loader.py

@@ -0,0 +1,145 @@
+# 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 预览专用数据加载器模块
+
+功能概述:
+- 预览场景专用数据加载入口
+- 使用新版 Spec + load_source_data 架构
+- header_enabled=False（预览不识别表头，对应旧版 header=None）
+- nrows 在加载时限制（CSV/Excel）
+- 不做空值清洗，保持原始值供 str() 转换
+
+架构设计:
+- 职责隔离：preview 有独立入口，不触碰 validation/loader.py
+- 直接利用新版架构（Spec → Loader → Registry），符合项目 V2 方向
+- 为后续扩展（encoding、delimiter 预览参数）提供清晰位置
+
+输入示例:
+    df, sheet_names = load_preview_data(
+        file_path="data/users.xlsx",
+        file_type="excel",
+        max_rows=100,
+        sheet_name="Sheet1"
+    )
+
+输出示例:
+    (DataFrame, sheet_names)
+    - sheet_names 仅在 excel 时返回，其他格式为 None
+"""
+
+from __future__ import annotations
+
+import logging
+
+import pandas as pd
+
+from app.shared.core.data_source.loaders import load_source_data
+from app.shared.core.data_source.loaders.excel_loader import get_excel_sheet_names
+from app.shared.core.data_source.specs.csv_source import CSVSourceSpec
+from app.shared.core.data_source.specs.excel_source import ExcelSourceSpec
+from app.shared.core.data_source.specs.json_source import JSONSourceSpec
+
+logger = logging.getLogger(__name__)
+
+
+def load_preview_data(
+    file_path: str,
+    file_type: str,
+    max_rows: int,
+    sheet_name: str | None = None,
+    source_config: dict | None = None,
+) -> tuple[pd.DataFrame, list[str] | None]:
+    """
+    @methoddesc 预览专用数据加载器
+
+    使用新版 Spec + load_source_data 架构加载预览数据。
+    - Excel/CSV：在加载时限制 nrows，不做空值清洗，保持原始数据供前端展示
+    - JSON：复用 JSONSourceSpec 加载（无 nrows 字段，加载后按 max_rows 截断）
+
+    参数:
+        file_path: 待加载文件的完整路径
+        file_type: 文件类型，可选值为 "excel" / "csv" / "json"
+        max_rows: 最大读取行数，用于限制预览数据量
+        sheet_name: Excel 工作表名称（仅 Excel 格式有效，可选）
+        source_config: 额外的源配置字典，如编码(encoding)、分隔符(delimiter)
+
+    返回:
+        元组 (DataFrame, sheet_names)
+        - DataFrame: 加载的原始数据（未清洗，保留空值和原始格式）
+        - sheet_names: 仅在 Excel 格式时返回工作表名称列表，其他格式返回 None
+
+    异常:
+        ValueError: 当 file_type 为不支持的类型时抛出
+        FileNotFoundError: 当文件不存在时抛出
+    """
+    # ======== Excel 格式处理 ========
+    if file_type == "excel":
+        # 构造 Excel 数据源规格，关闭表头识别、限制读取行数
+        spec: ExcelSourceSpec | CSVSourceSpec | JSONSourceSpec = ExcelSourceSpec(
+            path=file_path,
+            sheet=sheet_name,
+            header_enabled=False,
+            nrows=max_rows,
+        )
+        df = load_source_data(spec)
+
+        # 额外读取全部工作表名称，供前端切换展示。
+        # 引擎按扩展名自适应（.xls→xlrd），句柄在助手内确保关闭——
+        # 原实现硬编码 openpyxl 且依赖此处 close，曾致 .xls 必炸/句柄泄漏。
+        sheet_names = get_excel_sheet_names(file_path)
+
+        return df, sheet_names
+
+    # ======== CSV 格式处理 ========
+    if file_type == "csv":
+        # 从 source_config 提取编码和分隔符，使用默认值兜底
+        sc = source_config or {}
+        spec = CSVSourceSpec(
+            path=file_path,
+            header_enabled=False,
+            nrows=max_rows,
+            encoding=sc.get("encoding", "utf-8"),
+            delimiter=sc.get("delimiter", ","),
+        )
+        df = load_source_data(spec)
+        return df, None
+
+    # ======== JSON 格式处理（复用 JSONSourceSpec + load_source_data 管线） ========
+    if file_type == "json":
+        # 从 source_config 提取 JSON 格式与 json_path
+        sc = source_config or {}
+        # D8: format 必填,默认 array(顶层数组);.jsonl/.ndjson 文件强制 lines(与 validation 路径一致)
+        import os
+
+        ext = os.path.splitext(file_path)[1].lower()
+        if ext in [".jsonl", ".ndjson"]:
+            fmt = "lines"
+        else:
+            fmt = sc.get("json_format") or "array"
+        spec = JSONSourceSpec(
+            path=file_path,
+            format=fmt,
+            json_path=sc.get("json_path"),
+        )
+        df = load_source_data(spec)
+        # JSONSourceSpec 无 nrows 字段，加载后截断到预览行数上限
+        if len(df) > max_rows:
+            df = df.head(max_rows)
+        return df, None
+
+    # 如果走到这里，说明传入的文件类型不在支持列表中
+    raise ValueError(f"不支持的文件类型: {file_type}")