precis-cli 0.1.3__py3-none-any.whl

app/shared/services/llm/config/loader.py

@@ -0,0 +1,258 @@
+# 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 配置加载器
+
+功能概述:
+- 从 ~/.precis/ai_providers.yaml 加载 AI Provider 配置
+- 支持环境变量 ${VAR} 递归替换
+- API Key 加密存储（Fernet 对称加密）
+- 配置版本检查（仅兼容 2.x）
+- 首次使用自动创建默认配置模板
+- mtime 缓存避免重复文件读取
+
+设计原则:
+- AI Provider 配置是用户级全局设置，不属于项目仓库
+- 统一固定读取 ~/.precis/ai_providers.yaml
+- save() 始终写入用户级路径
+- api_key 加密存储：YAML 中以 "enc:" 前缀标记加密值
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from app.shared.core.config import ConfigPaths
+from app.shared.core.io.yaml import write_yaml_atomic
+
+from .crypto import decrypt_api_key, encrypt_api_key, is_encrypted
+from .models import AIConfig, AIProvider
+
+
+class ConfigLoader:
+    """
+    @classdesc 配置加载器 - 只支持 v2.0
+
+    AI Provider 配置固定存放在用户级路径 ~/.precis/ai_providers.yaml，
+    不再支持项目级或系统级配置查找。
+    """
+
+    CONFIG_FILENAME = "ai_providers.yaml"
+
+    _cached_config: AIConfig | None = None
+    _cached_mtime: float | None = None
+
+    def __init__(self, config_path: Path | None = None):
+        """
+        @methoddesc 初始化配置加载器
+
+        参数:
+            config_path: 可选，自定义配置文件路径。主要用于测试。
+                         未提供时固定使用 ~/.precis/ai_providers.yaml。
+        """
+        self._config_path = config_path
+        # §2.12: env 注入 api_key 的 provider id 集合（save 时剔除不落盘）
+        self._env_sourced_providers: set[str] = set()
+
+    @property
+    def config_path(self) -> Path:
+        """用户级 AI 配置文件路径（唯一真相源）"""
+        if self._config_path is not None:
+            return self._config_path
+        return ConfigPaths.ai_providers()
+
+    @config_path.setter
+    def config_path(self, value: Path) -> None:
+        """允许测试注入自定义路径。"""
+        self._config_path = value
+
+    @property
+    def USER_PATH(self) -> Path:  # noqa: N802
+        """用户级配置路径（save 的写入目标）"""
+        return self.config_path
+
+    def _expand_env(self, value: Any) -> Any:
+        """
+        @methoddesc 递归替换字符串中的环境变量 ${VAR}
+
+        支持字符串、字典、列表的递归处理。
+        如果环境变量不存在，替换为空字符串。
+        """
+        if isinstance(value, str):
+            return re.sub(r"\$\{([^}]+)\}", lambda m: os.getenv(m.group(1), ""), value)
+        elif isinstance(value, dict):
+            return {k: self._expand_env(v) for k, v in value.items()}
+        elif isinstance(value, list):
+            return [self._expand_env(v) for v in value]
+        return value
+
+    def _decrypt_api_keys(self, data: Any) -> Any:
+        """递归解密 api_key 字段中的加密值。"""
+        if isinstance(data, dict):
+            result: dict[Any, Any] = {}
+            for k, v in data.items():
+                if k == "api_key" and isinstance(v, str) and is_encrypted(v):
+                    result[k] = decrypt_api_key(v)
+                else:
+                    result[k] = self._decrypt_api_keys(v)
+            return result
+        elif isinstance(data, list):
+            return [self._decrypt_api_keys(item) for item in data]
+        return data
+
+    def _encrypt_api_keys(self, data: Any) -> Any:
+        """递归加密 api_key 字段中的明文值。"""
+        if isinstance(data, dict):
+            result: dict[Any, Any] = {}
+            for k, v in data.items():
+                if k == "api_key" and isinstance(v, str) and v and not is_encrypted(v) and not re.search(r"\$\{", v):
+                    result[k] = encrypt_api_key(v)
+                else:
+                    result[k] = self._encrypt_api_keys(v)
+            return result
+        elif isinstance(data, list):
+            return [self._encrypt_api_keys(item) for item in data]
+        return data
+
+    def load(self) -> AIConfig:
+        """
+        @methoddesc 加载 AI Provider 配置文件
+
+        固定读取 ~/.precis/ai_providers.yaml。
+        文件不存在时自动创建默认模板并返回。
+        """
+        config_path = self.config_path
+
+        if self._cached_config is not None and config_path.exists():
+            try:
+                current_mtime = config_path.stat().st_mtime
+                if current_mtime == self._cached_mtime:
+                    return self._cached_config
+            except OSError:
+                pass
+
+        if not config_path.exists():
+            config = self._create_default()
+            self.save(config)
+            return config
+
+        with open(config_path, encoding="utf-8") as f:
+            data = yaml.safe_load(f) or {}
+
+        version = data.get("version", "unknown")
+        if not isinstance(version, str) or not version.startswith("2."):
+            raise ValueError(f"Unsupported config version: {version}, expected 2.x")
+
+        data = self._expand_env(data)
+        data = self._decrypt_api_keys(data)
+        config = AIConfig(**data)
+        self._load_api_keys_from_env(config)
+
+        try:
+            self._cached_mtime = config_path.stat().st_mtime
+            self._cached_config = config
+        except OSError:
+            pass
+
+        return config
+
+    def _load_api_keys_from_env(self, config: AIConfig) -> None:
+        """从环境变量读取 API Key（优先级高于配置文件）。
+
+        §2.12: 注入的同时记录 env 来源的 provider id——save() 据此把 env 来源的
+        api_key 从落盘数据剔除，保持"env 覆盖是临时语义"；用户显式改 key 的路径
+        调 mark_api_key_manual() 后正常落盘。
+        """
+        for provider in config.providers:
+            env_key = f"{provider.id.upper().replace('-', '_')}_API_KEY"
+            api_key = os.getenv(env_key)
+
+            if not api_key:
+                provider_type = provider.type.value if hasattr(provider.type, "value") else str(provider.type)
+                env_key = f"{provider_type.upper()}_API_KEY"
+                api_key = os.getenv(env_key)
+
+            if api_key:
+                provider.api_key = api_key
+                self._env_sourced_providers.add(provider.id)
+
+    def mark_api_key_manual(self, provider_id: str) -> None:
+        """把 provider 的 api_key 标记为手工设置（save 时正常落盘，不再按 env 来源剔除）。"""
+        self._env_sourced_providers.discard(provider_id)
+
+    def save(self, config: AIConfig) -> None:
+        """
+        @methoddesc 将配置保存到用户级 YAML 文件
+
+        始终写入 ~/.precis/ai_providers.yaml。
+        使用原子写入（临时文件 + os.replace）：此文件含 API Key 等敏感配置，
+        裸 open("w") 在写入中途崩溃/断电会产生半截文件，导致用户配置丢失。
+
+        §2.12: env 注入的 api_key 不落盘（否则 env 覆盖被一次性写死进配置文件，
+        用户此后换 env 变量不再生效还以为 env 是活的）。
+        """
+        user_path = self.config_path
+        user_path.parent.mkdir(parents=True, exist_ok=True)
+
+        data = config.model_dump(exclude_none=True)
+        data = self._encrypt_api_keys(data)
+
+        if self._env_sourced_providers:
+            for provider_data in data.get("providers", []):
+                if provider_data.get("id") in self._env_sourced_providers:
+                    provider_data.pop("api_key", None)
+
+        write_yaml_atomic(user_path, data)
+
+        self.invalidate_cache()
+
+    def invalidate_cache(self) -> None:
+        """清除缓存，强制下次 load() 重新读取文件"""
+        self._cached_config = None
+        self._cached_mtime = None
+
+    def _create_default(self) -> AIConfig:
+        """创建默认配置模板（DeepSeek + Ollama Local）。"""
+        return AIConfig(
+            providers=[
+                AIProvider(
+                    id="deepseek",
+                    name="DeepSeek",
+                    type="openai",
+                    base_url="https://api.deepseek.com",
+                    api_key="${DEEPSEEK_API_KEY}",
+                    model="deepseek-v4-pro",
+                ),
+                AIProvider(
+                    id="ollama-local",
+                    name="Ollama Local",
+                    type="ollama",
+                    base_url="http://localhost:11434",
+                    api_key=None,
+                    model="llama3.2",
+                ),
+            ],
+            defaults={"chat": "deepseek"},
+        )
+
+
+# 全局实例
+loader = ConfigLoader()

app/shared/services/llm/config/models.py

@@ -0,0 +1,202 @@
+# 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 Provider 配置模型
+
+功能概述:
+- 定义 AI Provider 的配置结构（AIProvider、AIConfig）
+- 定义 Provider 类型枚举（ProviderType、DeploymentType）
+- 定义网络配置模型（NetworkConfig）
+- 支持根据 base_url 自动推断部署类型（本地/远程）
+
+架构设计:
+- 使用 Pydantic BaseModel 进行数据校验和序列化
+- 字段验证器自动推断 deployment 字段
+- 配置版本固定为 2.0，确保向前兼容
+
+输入示例:
+    # ~/.precis/ai_providers.yaml
+    version: "2.0"
+    providers:
+      - id: ollama-local
+        name: Ollama
+        type: ollama
+        base_url: http://localhost:11434
+        api_key: null
+        model: llama3.2
+
+输出示例:
+    AIConfig(
+      version="2.0",
+      providers=[AIProvider(id="ollama-local", ..., deployment=DeploymentType.LOCAL)],
+      defaults={"chat": "ollama-local"}
+    )
+"""
+
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class ProviderType(str, Enum):
+    """
+    @classdesc Provider 类型枚举
+
+    定义支持的 AI Provider 类型：
+    - OPENAI: OpenAI 兼容 API（云端/本地通用）
+    - OLLAMA: Ollama 原生 API
+    """
+
+    OPENAI = "openai"  # OpenAI 兼容 API（云端/本地通用）
+    OLLAMA = "ollama"  # Ollama 原生 API
+
+
+class DeploymentType(str, Enum):
+    """
+    @classdesc 部署类型枚举
+
+    根据 base_url 自动推断部署位置：
+    - LOCAL: 本地（localhost/127.0.0.1）
+    - REMOTE: 远程（内网/公网）
+    """
+
+    LOCAL = "local"  # 本地（localhost/127.0.0.1）
+    REMOTE = "remote"  # 远程（内网/公网）
+
+
+class NetworkConfig(BaseModel):
+    """
+    @classdesc 网络连接配置
+
+    控制与 AI Provider 通信时的超时和 SSL 校验行为。
+
+    Attributes:
+        timeout: 请求超时时间（秒），范围 5~300，默认 60
+        verify_ssl: 是否验证 SSL 证书，默认 True
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    timeout: int = Field(default=60, ge=5, le=300, description="请求超时时间（秒）")
+    verify_ssl: bool = Field(default=True, description="是否验证 SSL 证书")
+
+
+class AICacheConfig(BaseModel):
+    """
+    @classdesc LLM 响应缓存配置
+
+    控制 CachedProvider 的缓存行为。默认关闭，显式开启才生效。
+
+    Attributes:
+        enabled: 是否启用缓存，默认 False
+        ttl_seconds: 缓存条目过期时间（秒），默认 3600
+        max_entries: 缓存最大条目数（LRU 驱逐），默认 100
+        cache_temperature_above_zero: 是否缓存 temperature > 0 的请求，默认 False
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    enabled: bool = Field(default=False, description="是否启用 LLM 响应缓存")
+    ttl_seconds: float = Field(default=3600, ge=1, description="缓存条目过期时间（秒）")
+    max_entries: int = Field(default=100, ge=1, description="缓存最大条目数")
+    cache_temperature_above_zero: bool = Field(default=False, description="是否缓存 temperature > 0 的请求")
+
+
+class AIProvider(BaseModel):
+    """
+    @classdesc AI Provider 配置模型
+
+    定义一个 LLM 服务提供者的完整配置信息。
+    设计简化：所有核心字段必填，无向后兼容逻辑。
+
+    Attributes:
+        id: Provider 唯一标识符（如 "openai", "ollama-local"）
+        name: 显示名称（用于界面展示）
+        type: Provider 类型枚举（OPENAI 或 OLLAMA）
+        base_url: API 基础 URL（如 https://api.openai.com/v1）
+        api_key: API 密钥，本地服务可设为 null
+        model: 默认使用的模型名称（如 "gpt-4", "llama3.2"）
+        context_window: 模型最大上下文窗口（tokens），None 则自动推断
+        deployment: 部署类型（LOCAL/REMOTE），根据 base_url 自动推断
+        network: 网络连接配置（可选）
+        meta: 额外元数据字典（可选）
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    id: str = Field(..., description="唯一标识")
+    name: str = Field(..., description="显示名称")
+    type: ProviderType = Field(..., description="Provider 类型")
+
+    base_url: str = Field(..., description="API 基础 URL")
+    api_key: str | None = Field(default=None, description="API 密钥（本地服务可为 null）")
+    model: str = Field(..., description="默认模型名称")
+    context_window: int | None = Field(
+        default=None,
+        ge=1024,
+        description="模型最大上下文窗口（tokens），None 时由 Provider 根据模型名自动推断",
+    )
+
+    # 运行时推断字段（不序列化到配置文件）
+    deployment: DeploymentType | None = Field(default=None, exclude=True, description="部署类型（自动推断）")
+
+    # 可选扩展配置
+    network: NetworkConfig | None = Field(default=None, description="网络配置")
+    meta: dict[str, Any] | None = Field(default=None, description="额外元数据")
+
+    @model_validator(mode="after")
+    def _infer_deployment(self) -> "AIProvider":
+        """
+        @methoddesc 根据 base_url 推断部署类型
+
+        如果 URL 中包含 localhost、127.0.0.1 等本地地址，
+        则推断为 LOCAL，否则为 REMOTE。
+        使用 model_validator 确保在所有字段初始化后执行。
+        """
+        if self.deployment is None:
+            local_hosts = ["localhost", "127.0.0.1", "0.0.0.0", "::1"]
+            if any(h in self.base_url for h in local_hosts):
+                self.deployment = DeploymentType.LOCAL
+            else:
+                self.deployment = DeploymentType.REMOTE
+        return self
+
+
+class AIConfig(BaseModel):
+    """
+    @classdesc AI 配置根对象
+
+    对应 ~/.precis/ai_providers.yaml 的完整配置结构。
+
+    Attributes:
+        version: 配置格式版本，固定为 "2.0"
+        providers: 所有 AI Provider 的列表
+        defaults: 各场景默认使用的 Provider ID，如 {"chat": "ollama-local", "generate": "openai"}
+    """
+
+    model_config = ConfigDict(use_enum_values=True)
+
+    version: str = Field(default="2.0", description="配置版本号")
+    providers: list[AIProvider] = Field(default_factory=list, description="Provider 列表")
+
+    # 系统设置
+    defaults: dict[str, str] = Field(
+        default_factory=dict, description="各场景默认 Provider，如 {'chat': 'ollama-local'}"
+    )
+
+    # LLM 响应缓存配置（默认关闭）
+    cache: AICacheConfig = Field(default_factory=AICacheConfig, description="LLM 响应缓存配置")

app/shared/services/llm/config/presets.py

@@ -0,0 +1,128 @@
+# 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 Provider 预设定义
+
+功能概述:
+- 定义内置的服务商预设配置（base_url、默认模型、可用模型列表）
+- 所有 OpenAI 兼容服务商统一为 type=openai
+- 后端扩展新服务商时只需在此文件添加预设条目
+
+架构设计:
+- PROVIDER_PRESETS 为字典，key 为预设 ID，value 为预设配置
+- 预设配置包含服务商元信息和可用模型列表
+- API 端点 GET /providers/presets 返回预设列表供前端和 CLI 使用
+- 这是 Provider 元数据的唯一来源，前端和 CLI 共用
+- 字典顺序即前端设置页下拉与 CLI 菜单的展示顺序（国内主流在前、本地服务在后）
+- base_url 必须是 OpenAI 兼容端点（openai SDK 会在其后拼接 /chat/completions），
+  含版本路径的厂商必须带全（如 /v1、/compatible-mode/v1、/api/paas/v4、/api/v3）
+
+维护约定:
+- 各厂商 base_url / 模型 ID / 鉴权要点 / 更新 SOP 见同目录 AI_PROVIDER_PRESETS.md
+- 模型列表有时效性（厂商滚动升级），更新时须对照官方模型列表并同步维护文档的核对日期
+
+输入示例:
+    preset = PROVIDER_PRESETS["deepseek"]
+
+输出示例:
+    ProviderPreset(id="deepseek", name="DeepSeek", type="openai",
+                   base_url="https://api.deepseek.com",
+                   default_model="deepseek-v4-flash",
+                   models=["deepseek-v4-flash", "deepseek-v4-pro"])
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+PROVIDER_PRESETS: dict[str, dict[str, Any]] = {
+    "deepseek": {
+        "id": "deepseek",
+        "name": "DeepSeek",
+        "type": "openai",
+        "base_url": "https://api.deepseek.com",
+        "default_model": "deepseek-v4-pro",
+        "models": ["deepseek-v4-pro", "deepseek-v4-flash"],
+    },
+    "qwen": {
+        "id": "qwen",
+        "name": "通义千问 Qwen",
+        "type": "openai",
+        "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+        "default_model": "qwen3.8-max",
+        "models": ["qwen3.8-max", "qwen3.7-plus", "qwen3.8-flash"],
+    },
+    "glm": {
+        "id": "glm",
+        "name": "智谱 GLM",
+        "type": "openai",
+        "base_url": "https://open.bigmodel.cn/api/paas/v4",
+        "default_model": "glm-5.3",
+        "models": ["glm-5.3", "glm-5.3-flash", "glm-5.2"],
+    },
+    "kimi": {
+        "id": "kimi",
+        "name": "月之暗面 Kimi",
+        "type": "openai",
+        "base_url": "https://api.moonshot.cn/v1",
+        "default_model": "kimi-k3",
+        "models": ["kimi-k3", "kimi-k2.7-code", "kimi-k2.6", "kimi-latest"],
+    },
+    "minimax": {
+        "id": "minimax",
+        "name": "MiniMax",
+        "type": "openai",
+        "base_url": "https://api.minimaxi.com/v1",
+        "default_model": "MiniMax-M3",
+        "models": ["MiniMax-M3", "MiniMax-M2.5", "MiniMax-M2.7-highspeed"],
+    },
+    "mimo": {
+        "id": "mimo",
+        "name": "Xiaomi MiMo",
+        "type": "openai",
+        "base_url": "https://api.xiaomimimo.com/v1",
+        "default_model": "mimo-v2.5",
+        "models": ["mimo-v2.5", "mimo-v2.5-pro"],
+    },
+    "ollama": {
+        "id": "ollama-local",
+        "name": "Ollama Local",
+        "type": "ollama",
+        "base_url": "http://localhost:11434",
+        "default_model": "llama3.2",
+        "models": [],
+    },
+}
+
+
+def get_preset_list() -> list[dict[str, Any]]:
+    """返回所有预设的列表（不含内部字段）"""
+    return [
+        {
+            "id": v["id"],
+            "name": v["name"],
+            "type": v["type"],
+            "base_url": v["base_url"],
+            "default_model": v["default_model"],
+            "models": list(v["models"]),
+        }
+        for v in PROVIDER_PRESETS.values()
+    ]
+
+
+def get_preset(preset_id: str) -> dict[str, Any] | None:
+    """按 ID 获取预设，不存在返回 None"""
+    return PROVIDER_PRESETS.get(preset_id)