precis-cli 0.1.3__py3-none-any.whl

app/shared/services/hardware.py

@@ -0,0 +1,237 @@
+# 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 系统硬件信息采集模块
+
+功能概述:
+- 采集操作系统、CPU、内存、磁盘、GPU 等硬件信息
+- 提供 HardwareSnapshot 数据类用于性能优化和错误报告
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class HardwareSnapshot:
+    """
+    @classdesc 硬件快照数据类
+
+    使用 frozen=True 确保实例不可变，线程安全。
+
+    字段说明：
+    - os_name: 操作系统名称（如 'Windows', 'Linux'）
+    - os_version: 操作系统版本号
+    - arch: 系统架构（如 'x86_64', 'AMD64'）
+    - cpu_cores: CPU 逻辑核心数
+    - memory_total_bytes: 物理内存总量（字节）
+    - disk_free_bytes: 磁盘可用空间（字节）
+    - has_nvidia_gpu: 是否存在 NVIDIA GPU
+    """
+
+    os_name: str
+    os_version: str
+    arch: str
+    cpu_cores: int
+    memory_total_bytes: int
+    disk_free_bytes: int
+    has_nvidia_gpu: bool
+
+
+def _cpu_cores() -> int:
+    """
+    @methoddesc 获取 CPU 逻辑核心数
+
+    实现逻辑：
+    1. 尝试使用 os.cpu_count() 获取核心数
+    2. 异常处理：若获取失败，返回默认值 1
+
+    返回:
+        CPU 逻辑核心数，至少为 1
+    """
+    try:
+        v = int(os.cpu_count() or 0)
+    except Exception:
+        logger.debug("获取 CPU 核心数失败", exc_info=True)
+        v = 0
+    return v if v > 0 else 1
+
+
+def _memory_total_bytes() -> int:
+    """
+    @methoddesc 获取系统物理内存总量
+
+    平台实现：
+    - Windows: 使用 ctypes 调用 kernel32.GlobalMemoryStatusEx
+    - Linux/Unix: 使用 os.sysconf 获取页大小和物理页数
+
+    返回:
+        物理内存总量（字节），获取失败返回 0
+    """
+    # Windows 平台实现
+    if os.name == "nt":
+        try:
+            import ctypes
+
+            # 定义 Windows MEMORYSTATUSEX 结构体
+            class _MEMORYSTATUSEX(ctypes.Structure):
+                _fields_ = [
+                    ("dwLength", ctypes.c_ulong),  # 结构体大小
+                    ("dwMemoryLoad", ctypes.c_ulong),  # 内存使用率
+                    ("ullTotalPhys", ctypes.c_ulonglong),  # 物理内存总量
+                    ("ullAvailPhys", ctypes.c_ulonglong),  # 物理内存可用量
+                    ("ullTotalPageFile", ctypes.c_ulonglong),  # 页面文件总量
+                    ("ullAvailPageFile", ctypes.c_ulonglong),  # 页面文件可用量
+                    ("ullTotalVirtual", ctypes.c_ulonglong),  # 虚拟内存总量
+                    ("ullAvailVirtual", ctypes.c_ulonglong),  # 虚拟内存可用量
+                    ("sullAvailExtendedVirtual", ctypes.c_ulonglong),  # 扩展虚拟内存
+                ]
+
+            stat = _MEMORYSTATUSEX()
+            stat.dwLength = ctypes.sizeof(_MEMORYSTATUSEX)
+            # 调用 Windows API 获取内存状态
+            # windll 是 Windows 专属属性，非 Windows 平台 typeshed 无此定义
+            if ctypes.windll.kernel32.GlobalMemoryStatusEx(ctypes.byref(stat)) == 0:  # type: ignore[attr-defined]
+                return 0
+            return int(stat.ullTotalPhys)
+        except Exception:
+            logger.debug("Windows 平台获取内存总量失败", exc_info=True)
+            return 0
+
+    # Linux/Unix 平台实现
+    if hasattr(os, "sysconf"):
+        try:
+            # 获取系统页大小（字节）
+            page = int(os.sysconf("SC_PAGE_SIZE"))
+            # 获取物理内存页数
+            pages = int(os.sysconf("SC_PHYS_PAGES"))
+            total = page * pages
+            return int(total) if total > 0 else 0
+        except Exception:
+            logger.debug("Linux/Unix 平台获取内存总量失败", exc_info=True)
+            return 0
+
+    return 0
+
+
+def _disk_free_bytes(path: str | None = None) -> int:
+    r"""
+    @methoddesc 获取指定路径所在磁盘的可用空间
+
+    路径解析逻辑：
+    - 若指定 path 参数：使用该路径
+    - 若未指定：
+      - Windows: 使用系统驱动器（默认 C:\）
+      - Linux/Unix: 使用用户主目录
+
+    参数:
+        path: 可选的磁盘路径
+
+    返回:
+        可用空间（字节），获取失败返回 0
+    """
+    p = path
+    if not p:
+        if os.name == "nt":
+            # Windows: 使用系统驱动器
+            p = os.environ.get("SystemDrive", "C:") + "\\"
+        else:
+            # Linux/Unix: 使用用户主目录
+            p = os.path.expanduser("~")
+    try:
+        usage = shutil.disk_usage(p)
+        return int(usage.free)
+    except Exception:
+        logger.debug(f"获取磁盘可用空间失败: path={p}", exc_info=True)
+        return 0
+
+
+def _has_nvidia_gpu(timeout_seconds: float = 1.2) -> bool:
+    """
+    @methoddesc 检测系统是否装有 NVIDIA GPU
+
+    实现机制：
+    通过执行 nvidia-smi -L 命令检测 GPU 存在性。
+    使用较短的超时时间（默认 1.2 秒）避免长时间阻塞。
+
+    参数:
+        timeout_seconds: 命令执行超时时间（秒）
+
+    返回:
+        存在 NVIDIA GPU 返回 True，否则返回 False
+    """
+    try:
+        # 执行 nvidia-smi -L 命令检测GPU
+        res = subprocess.run(
+            ["nvidia-smi", "-L"],
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            timeout=timeout_seconds,
+            check=False,
+        )
+        # 返回码为0表示命令成功执行，即存在GPU
+        return res.returncode == 0
+    except Exception:
+        logger.debug("NVIDIA GPU 检测失败", exc_info=True)
+        return False
+
+
+def snapshot() -> HardwareSnapshot:
+    """
+    @methoddesc 获取当前系统的硬件信息快照
+
+    采集的信息：
+    1. 操作系统信息：
+       - os_name: platform.system() 或 os.name
+       - os_version: platform.version() 或 platform.release()
+    2. 系统架构：platform.machine() 或 platform.architecture()
+    3. CPU 核心数：_cpu_cores()
+    4. 内存总量：_memory_total_bytes()
+    5. 磁盘可用空间：_disk_free_bytes()
+    6. GPU 检测：_has_nvidia_gpu()
+
+    返回:
+        HardwareSnapshot 实例，包含所有硬件信息
+    """
+    # 采集操作系统信息
+    os_name = platform.system() or os.name
+    os_version = platform.version() or platform.release() or ""
+    arch = platform.machine() or platform.architecture()[0] or sys.platform
+
+    # 采集各项硬件指标
+    cpu_cores = _cpu_cores()
+    memory_total = _memory_total_bytes()
+    disk_free = _disk_free_bytes()
+    has_gpu = _has_nvidia_gpu()
+
+    # 构建并返回硬件快照
+    return HardwareSnapshot(
+        os_name=os_name,
+        os_version=os_version,
+        arch=arch,
+        cpu_cores=cpu_cores,
+        memory_total_bytes=memory_total,
+        disk_free_bytes=disk_free,
+        has_nvidia_gpu=has_gpu,
+    )

app/shared/services/llm/__init__.py

@@ -0,0 +1,62 @@
+# 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 LLM 服务模块聚合导出
+
+功能概述:
+- 聚合导出 AI Provider 配置、Provider 实现、服务发现、配置生成等子模块
+- 为上层业务提供统一的 LLM 服务入口
+
+架构设计:
+- 通过 __init__.py 聚合子模块公共接口，降低外部导入复杂度
+- 遵循显式导出原则，使用 __all__ 控制公开 API
+- 各子模块职责分离：config 负责配置，providers 负责调用，discovery 负责发现，generation 负责生成
+
+输入示例:
+    from app.shared.services.llm import AIConfig, BaseProvider, ConfigGenerationService
+
+输出示例:
+    AIConfig 实例可用于配置管理
+    BaseProvider 子类可用于执行对话
+    ConfigGenerationService 可用于生成项目配置
+"""
+
+from .config import AIConfig, AIProvider, DeploymentType, ProviderType, loader
+from .discovery import DiscoveredService, scanner
+from .generation import ConfigGenerationService, GenerationOptions, ProfilingOptions
+from .providers import BaseProvider, ChatMessage, ChatRequest, ChatResponse, create
+
+__all__ = [
+    # 配置
+    "AIConfig",
+    "AIProvider",
+    "ProviderType",
+    "DeploymentType",
+    "loader",
+    # Provider
+    "BaseProvider",
+    "ChatMessage",
+    "ChatRequest",
+    "ChatResponse",
+    "create",
+    # 发现
+    "scanner",
+    "DiscoveredService",
+    # 配置生成
+    "ConfigGenerationService",
+    "GenerationOptions",
+    "ProfilingOptions",
+]

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

@@ -0,0 +1,42 @@
+# 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 动作解析与执行子包
+
+功能概述:
+- registry: 动作类型与约束别名的单一事实源（无依赖叶子模块）
+- action_parser: 动作类型映射 + 向后兼容导出
+- action_processor: process_actions() 批量处理
+- action_handlers: update_yaml_config() + 协调函数
+- action_validator: ActionValidator 预验证器
+
+架构设计:
+- 管道模式: 解析 → 验证 → 执行
+- 批量优化: 内联约束按 schema 分组合并 IO
+
+导入说明:
+本 __init__.py 故意不做包级 re-export。原因：action_handlers 依赖
+constraints.constraint_builder/frontend_instructions，而这些模块从 registry 派生常量——
+若在此处包级 import 会形成循环（actions/__init__ → action_handlers →
+constraint_builder → actions 包），导致 test_constraint_builder_behavior.py 等独立
+运行时 ImportError。
+
+调用方请直接 import 具体子模块，例如:
+    from app.shared.services.llm.actions.action_processor import process_actions
+    from app.shared.services.llm.actions.action_handlers import update_yaml_config
+    from app.shared.services.llm.actions.action_parser import CONSTRAINT_TYPE_MAP
+    from app.shared.services.llm.actions.registry import CONSTRAINT_TYPE_ALIASES
+"""

app/shared/services/llm/actions/_canvas_validator.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 ADD_TO_CANVAS 动作验证器
+
+验证 AI 生成 ADD_TO_CANVAS 动作的合法性：
+- canvasSpec.resourceKind 必须是 schema/regex/constraint/transform 之一
+- resourceId 或 resourceName 至少有一个
+- 目标资源在项目配置中必须真实存在（避免把不存在的资源"显示"到画布）
+
+与其它验证器不同：本验证器是纯读校验（ADD_TO_CANVAS 不写盘），
+但仍接入预验证链以拦截"显示不存在的资源"这类语义错误，把错误回灌给 LLM 自我修正。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from app.shared.services.llm.actions.registry import CANVAS_RESOURCE_KINDS
+from app.shared.services.llm.actions.validation_types import ValidationError
+
+# 支持的资源类型从注册表派生（单一事实源，与前端 ProjectResourceKind 对齐）
+VALID_CANVAS_RESOURCE_KINDS = CANVAS_RESOURCE_KINDS
+
+
+def _list_existing_resource_ids(workspace_path: str, kind: str) -> set[str]:
+    """扫描项目配置目录，返回指定 kind 的已存在资源 ID 集合。
+
+    用于校验 ADD_TO_CANVAS 的目标资源是否真实存在。
+    扫描逻辑与 get_project_overview / 各 handler 的文件定位保持一致。
+    """
+    root = Path(workspace_path)
+    ids: set[str] = set()
+
+    dir_map = {
+        "schema": ("schemas", "*.schema.yaml"),
+        "regex": ("regex", "*.regex.yaml"),
+        "constraint": ("constraints", "*.constraint.yaml"),
+        "transform": ("transforms", "*.transform.yaml"),
+    }
+    if kind not in dir_map:
+        return ids
+
+    subdir, pattern = dir_map[kind]
+    target_dir = root / subdir
+    if not target_dir.exists():
+        return ids
+
+    for f in target_dir.glob(pattern):
+        try:
+            with open(f, encoding="utf-8") as fh:
+                data = yaml.safe_load(fh) or {}
+            rid = data.get("id") or data.get("name")
+            if rid:
+                ids.add(str(rid))
+                # 同时收录 name 作为兜底匹配键（resourceName 常用 name）
+                name = data.get("name")
+                if name and str(name) != str(rid):
+                    ids.add(str(name))
+        except Exception:
+            continue
+
+    return ids
+
+
+def validate_canvas_action(action: dict[str, Any], index: int, workspace_path: str) -> list[ValidationError]:
+    """验证 ADD_TO_CANVAS 操作
+
+    检查 canvasSpec 的 resourceKind 合法性、resourceId/resourceName 存在性，
+    以及目标资源在项目配置中是否真实存在。
+    """
+    errors: list[ValidationError] = []
+    action_type = action.get("actionType", "")
+    spec = action.get("canvasSpec", {})
+
+    if not isinstance(spec, dict):
+        errors.append(
+            ValidationError(
+                action_index=index,
+                action_type=action_type,
+                error_type="missing_canvas_spec",
+                message="ADD_TO_CANVAS 需要 canvasSpec 字段",
+            )
+        )
+        return errors
+
+    kind = spec.get("resourceKind", "")
+    resource_id = spec.get("resourceId", "")
+    resource_name = spec.get("resourceName") or spec.get("name", "")
+
+    # 1. resourceKind 必须合法
+    if kind not in VALID_CANVAS_RESOURCE_KINDS:
+        errors.append(
+            ValidationError(
+                action_index=index,
+                action_type=action_type,
+                error_type="invalid_resource_kind",
+                message=f"不支持的资源类型: '{kind}'",
+                suggestion=f"可用类型: {', '.join(sorted(VALID_CANVAS_RESOURCE_KINDS))}",
+            )
+        )
+        return errors
+
+    # 2. resourceId 或 resourceName 至少有一个
+    if not resource_id and not resource_name:
+        errors.append(
+            ValidationError(
+                action_index=index,
+                action_type=action_type,
+                error_type="missing_resource_identifier",
+                message="ADD_TO_CANVAS 需要指定 resourceId 或 resourceName",
+                suggestion="可用 read_project 查询资源 ID/名称",
+            )
+        )
+        return errors
+
+    # 3. 目标资源必须真实存在（避免"显示不存在的资源"）
+    existing_ids = _list_existing_resource_ids(workspace_path, kind)
+    target_keys = {str(resource_id), str(resource_name)} - {""}
+    if existing_ids and not (target_keys & existing_ids):
+        errors.append(
+            ValidationError(
+                action_index=index,
+                action_type=action_type,
+                error_type="resource_not_found",
+                message=f"资源不存在: {kind} '{resource_id or resource_name}'",
+                suggestion="该资源未在项目配置中找到，请先创建（如用 ADD_SCHEMA）或检查名称拼写",
+            )
+        )
+
+    return errors