precis-cli 0.1.3__py3-none-any.whl

app/api/models/workspace.py

@@ -0,0 +1,118 @@
+# 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.
+# backend/app/api/models/workspace.py
+"""
+@fileoverview 工作区请求/响应模型
+
+功能概述:
+- 定义工作区和数据源相关的 Pydantic 数据模型
+- 包含外部数据源、UI 偏好设置、工作区配置等模型
+
+输入示例:
+    WorkspaceConfig(
+        version="1.0",
+        data_sources=[ExternalDataSource(id="ds1", name="users.xlsx", fileId="...")],
+        ui_preferences=UIPreferences(expanded_folders={"schemas": True})
+    )
+
+输出示例:
+    WorkspaceConfig(
+        version="1.0",
+        data_sources=[...],
+        alias_mappings={"/path/to/file.xlsx": "users"},
+        last_updated="2024-01-01T00:00:00Z"
+    )
+"""
+
+from pydantic import BaseModel, Field
+
+
+class ExternalDataSource(BaseModel):
+    """
+    外部数据源模型
+
+    描述一个外部数据源（如 Excel、CSV 文件）的元信息。
+    支持两种数据读取模式：
+    - IndexedDB 模式：浏览器环境，从 IndexedDB 读取文件内容
+    - 本地文件模式：Electron 环境，从本地文件系统读取
+
+    Attributes:
+        id: 数据源唯一标识符
+        name: 数据源显示名称（别名）
+        fileId: 文件标识（IndexedDB key 或本地文件路径）
+        type: 文件类型（如 excel、csv）
+        status: 数据源状态（ready/missing/loading）
+        addedAt: 添加到系统的时间
+        lastUsed: 最后一次使用的时间
+        alias: 数据源别名（可选）
+        error: 错误信息（如果有）
+        sourceMode: 数据读取模式（indexeddb/localfile）
+        localPath: 本地文件路径（Electron 模式专用）
+    """
+
+    id: str = Field(..., description="数据源唯一标识符")
+    name: str = Field(..., description="数据源显示名称")
+    fileId: str = Field(..., description="文件ID (IndexedDB key 或本地路径)")
+    type: str = Field(..., description="文件类型 (excel/csv)")
+    status: str = Field(default="ready", description="数据源状态 (ready/missing/loading)")
+    addedAt: str = Field(default="", description="添加时间")
+    lastUsed: str = Field(default="", description="最后使用时间")
+    alias: str | None = Field(None, description="数据源别名")
+    error: str | None = Field(None, description="错误信息")
+    size: int | None = Field(None, description="文件大小(字节)")
+    sourceMode: str | None = Field(None, description="数据来源模式 (indexeddb/localfile)")
+    localPath: str | None = Field(None, description="本地文件路径（Electron 模式专用）")
+    folderPath: str | None = Field(None, description="文件夹路径（用于分组显示）")
+
+
+class UIPreferences(BaseModel):
+    """
+    UI 偏好设置模型
+
+    存储用户界面的个性化配置选项。
+
+    Attributes:
+        expanded_folders: 文件树中各文件夹的展开/折叠状态
+        startup_loading_enabled: Electron 启动时是否显示加载弹窗
+    """
+
+    expanded_folders: dict[str, bool] = Field(
+        default={"input-staging": True, "schemas": True, "patterns": False, "constraints": False},
+        description="文件夹展开状态",
+    )
+    startup_loading_enabled: bool = Field(default=True, description="是否在 Electron 启动时显示加载弹窗")
+
+
+class WorkspaceConfig(BaseModel):
+    """
+    工作区配置模型
+
+    完整的工作区设置，包含所有持久化的配置信息。
+    通常存储在 workspace.json 或类似的配置文件中。
+
+    Attributes:
+        version: 配置版本号
+        data_sources: 数据源列表
+        alias_mappings: 文件路径到别名的映射
+        ui_preferences: UI 偏好设置
+        last_updated: 最后更新时间
+    """
+
+    version: str = Field(default="1.0", description="配置版本")
+    data_sources: list[ExternalDataSource] = Field(default=[], description="数据源列表")
+    alias_mappings: dict[str, str] = Field(default={}, description="路径到别名的映射")
+    ui_preferences: UIPreferences = Field(default=UIPreferences(), description="UI偏好设置")
+    last_updated: str = Field(default="", description="最后更新时间")

app/api/routers/__init__.py

@@ -0,0 +1,56 @@
+# 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 API 路由聚合入口模块
+
+功能概述:
+- 聚合并导出所有子模块的路由器实例
+- 统一暴露项目、AI、预览、校验、工作空间等路由
+
+说明:
+- 所有路由器（含 AI）均在包导入时直接实例化并注册端点，确保 `app.include_router`
+  在任意环境（Linux/Windows、Py3.12/3.13）下都能确定性地拷贝到全部路由。
+- 此前曾用 `_LazyAIRouter` 代理延迟加载 AI 路由，但其 `__getattr__` 转发在
+  CI(Linux) 环境下会导致 stream.py 等子模块的端点不稳定地漏注册（manifest 为
+  /ai/jobs/{id}/cancel、/ai/chat/{id}/confirm 等返回 404）。AI 子模块的可选依赖
+  (openai/aiohttp/psutil) 均已在各自模块内做懒加载守卫，启动期直接导入安全。
+"""
+
+from __future__ import annotations
+
+from .ai import router as ai_router
+from .core.connection_rules import router as connection_rules_router
+from .core.data_sources import router as data_sources_router
+from .core.regex import router as regex_router
+from .core.reporting import router as reporting_router
+from .files import router as files_router
+from .preview import router as preview_router
+from .project import router as project_router
+from .projects import router as projects_router
+from .validation import router as validation_router
+
+__all__ = [
+    "project_router",
+    "projects_router",
+    "files_router",
+    "connection_rules_router",
+    "ai_router",
+    "preview_router",
+    "validation_router",
+    "data_sources_router",
+    "regex_router",
+    "reporting_router",
+]

app/api/routers/ai/__init__.py

@@ -0,0 +1,36 @@
+# 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 路由包入口
+
+功能概述:
+- 作为 AI 相关 API 路由的统一出口
+- 从 router 模块导入主路由实例，保持与旧代码的兼容性
+- 导出 models 子模块供外部使用
+
+输入示例:
+    from app.api.routers.ai import router
+    app.include_router(router, prefix="/ai")
+
+输出示例:
+    router: APIRouter 实例，包含所有 AI 相关端点
+    models: AI 相关数据模型子模块
+"""
+
+from . import models
+from .router import router
+
+__all__ = ["router", "models"]

app/api/routers/ai/chat.py

@@ -0,0 +1,243 @@
+# 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 聊天 API 路由模块
+
+功能概述:
+- 提供统一的 AI 聊天接口，支持流式和非流式响应
+- 兼容前端 AI Chat 编排器的负载格式
+- 提供 OpenAI 兼容的 /chat/completions 端点
+
+架构设计:
+- 使用统一的 AI Chat 编排器处理业务逻辑
+- 支持通过 X-Project-Config-Path Header 传递项目上下文
+- 流式响应使用 SSE 格式返回
+
+输入示例:
+    POST /ai/chat
+    {
+        "message": "分析这个数据文件",
+        "context": {"hasContext": false, "selectedNodes": []},
+        "history": []
+    }
+
+输出示例:
+    {
+        "status": "success",
+        "reply": "分析结果...",
+        "actions": [],
+        "frontend_instructions": [],
+        "error": null
+    }
+"""
+
+import json
+import logging
+from collections.abc import AsyncIterator
+from typing import Any
+
+from fastapi import Header, HTTPException
+from fastapi.responses import StreamingResponse
+
+from ....shared.services.ai.chat_orchestrator import execute_ai_chat_unified
+from ....shared.services.ai.failure_messages import describe_ai_failure
+from ....shared.services.llm.config import loader
+from ....shared.services.llm.providers import ChatMessage, ChatRequest, create
+from .models import AgentMeta, AiChatRequest, AiChatResponse, ChatRequestInput
+
+# 从 router 模块导入 router 实例（与旧代码保持一致）
+from .router import router
+
+
+@router.post(
+    "/chat",
+    response_model=AiChatResponse,
+    summary="与前端对齐的 AI 聊天接口",
+    responses={
+        400: {"description": "未配置默认 Provider"},
+        404: {"description": "Provider 未找到"},
+        502: {"description": "AI 服务调用失败"},
+    },
+)
+async def chat(request: AiChatRequest, x_project_config_path: str | None = Header(None)) -> AiChatResponse:
+    """
+    与前端对齐的 AI 聊天接口
+
+    接收前端特定的负载格式，并使用统一的 AI Chat 编排器来处理。
+    先从配置中加载默认 Provider，然后将请求转发给编排器执行。
+
+    Args:
+        request: AI 聊天请求，包含消息、上下文和历史记录
+        x_project_config_path: 项目配置文件路径（通过 Header 传递，用于编排器上下文）
+
+    Returns:
+        包含 AI 回复、状态和前端指令的响应对象
+    """
+    config = loader.load()
+
+    # 校验项目路径（修复 #10：防止 X-Project-Config-Path 任意目录读写）
+    from .utils import validate_project_path
+
+    safe_project_path = validate_project_path(x_project_config_path)
+
+    # 获取默认 provider
+    provider_id = config.defaults.get("chat")
+    if not provider_id:
+        raise HTTPException(400, detail="尚未设置默认的 AI 模型，请先在设置中选择一个 AI 模型")
+
+    # 查找 Provider 配置
+    provider_cfg = next((p for p in config.providers if p.id == provider_id), None)
+    if not provider_cfg:
+        raise HTTPException(404, detail=f"未找到对应的 AI 模型配置，可能已被删除（ID: {provider_id}）")
+
+    # 转换上下文节点（将 Pydantic 模型转为字典）
+    context_nodes = [node.model_dump() for node in request.context.selectedNodes]
+
+    # 转换画布节点快照（供 read_canvas 工具查询画布真实状态）
+    canvas_nodes = [node.model_dump() for node in request.context.canvasNodes]
+
+    # 转换对话历史（将 Pydantic 模型转为简单字典列表）
+    history = [{"role": h.role, "content": h.content} for h in (request.history or [])]
+
+    # 调用统一编排器执行 AI 聊天
+    try:
+        result = await execute_ai_chat_unified(
+            message=request.message,
+            project_path=safe_project_path,
+            provider=provider_cfg,
+            context_nodes=context_nodes,
+            history=history,
+            agent_mode=request.agent_mode,
+            canvas_nodes=canvas_nodes,
+        )
+    except Exception as exc:
+        logging.getLogger(__name__).exception("AI chat failed")
+        raise HTTPException(status_code=502, detail=describe_ai_failure(exc))
+
+    # agent_meta 仅在 agent_mode=true 时填充，旧路径保持 None
+    agent_meta = AgentMeta(iterations=result.iterations, tool_steps=result.tool_steps) if request.agent_mode else None
+
+    # 根据编排器结果组装响应
+    if not result.success:
+        return AiChatResponse(
+            status="error",
+            reply=result.reply or "",
+            actions=[],
+            frontend_instructions=[],
+            agent_meta=agent_meta,
+            error=result.error,
+        )
+
+    return AiChatResponse(
+        status="success",
+        reply=result.reply,
+        actions=result.actions,
+        frontend_instructions=result.frontend_instructions,
+        agent_meta=agent_meta,
+        error=None,
+    )
+
+
+@router.post(
+    "/chat/completions",
+    summary="OpenAI 兼容的聊天接口",
+    response_model=None,
+    responses={
+        400: {"description": "未指定 Provider"},
+        404: {"description": "Provider 未找到"},
+        502: {"description": "AI 服务调用失败"},
+    },
+)
+async def chat_completions(request: ChatRequestInput) -> StreamingResponse | dict[str, Any]:
+    """
+    OpenAI 兼容的聊天接口
+
+    与 OpenAI API 格式兼容，便于前端使用标准客户端。
+    支持流式（SSE）和非流式两种响应模式。
+
+    Args:
+        request: OpenAI 兼容格式的聊天请求
+
+    Returns:
+        流式模式下返回 SSE 响应，非流式返回 JSON 对象
+    """
+    config = loader.load()
+
+    provider_id = request.provider_id or config.defaults.get("chat")
+    if not provider_id:
+        raise HTTPException(400, detail="尚未指定要使用的 AI 模型，请先在设置中选择")
+
+    provider_cfg = next((p for p in config.providers if p.id == provider_id), None)
+    if not provider_cfg:
+        raise HTTPException(404, detail=f"未找到对应的 AI 模型配置，可能已被删除（ID: {provider_id}）")
+
+    provider = create(provider_cfg)
+    # 构建聊天请求对象
+    chat_req = ChatRequest(
+        messages=[ChatMessage(role=m.role, content=m.content) for m in request.messages],
+        model=request.model or provider_cfg.model,
+        stream=request.stream,
+        temperature=request.temperature,
+    )
+
+    if request.stream:
+        # 流式响应模式：使用 SSE 格式逐块返回
+
+        async def generate() -> AsyncIterator[str]:
+            """
+            @methoddesc SSE 流式响应生成器
+
+            业务用途:
+            - 在流式聊天请求下，构造与 OpenAI 兼容的 SSE 事件流
+            - 起始事件携带 assistant 角色标识；中间事件逐块回传 delta.content；末尾发送 [DONE] 终止标记
+
+            @yields str - 形如 ``data: {json}\\n\\n`` 的 SSE 帧
+            """
+            # 发送 SSE 起始事件，标识助手角色
+            yield '{"id":"chatcmpl-start","object":"chat.completion.chunk","choices":[{"delta":{"role":"assistant"}}]}\n\n'
+
+            try:
+                # 逐块获取流式输出，提取 delta 文本（该端点为纯文本兼容流，不处理 tool_calls）
+                # 注意: json 已在模块级导入。此前 import json 写在循环体内——若首个 chunk
+                # 之前就抛错，except 分支引用的 json 未绑定，会以 NameError 掩盖真实错误。
+                async for chunk in provider.chat_stream(chat_req):
+                    if chunk.type == "delta" and chunk.text:
+                        # 构建 SSE 数据包，格式与 OpenAI 兼容
+                        data = {"object": "chat.completion.chunk", "choices": [{"delta": {"content": chunk.text}}]}
+                        yield f"data: {json.dumps(data)}\n\n"
+            except Exception as exc:
+                logging.getLogger(__name__).exception("Chat stream failed")
+                yield f"data: {json.dumps({'error': str(exc)})}\n\n"
+
+            # 发送 SSE 结束标记
+            yield "data: [DONE]\n\n"
+
+        return StreamingResponse(generate(), media_type="text/event-stream")
+    else:
+        # 非流式响应模式：直接返回完整结果
+        try:
+            resp = await provider.chat(chat_req)
+        except Exception as exc:
+            logging.getLogger(__name__).exception("Chat completion failed")
+            raise HTTPException(status_code=502, detail=describe_ai_failure(exc))
+        return {
+            "id": "chatcmpl-local",
+            "object": "chat.completion",
+            "model": resp.model or provider_cfg.model,
+            "choices": [
+                {"index": 0, "message": {"role": "assistant", "content": resp.content}, "finish_reason": "stop"}
+            ],
+        }

app/api/routers/ai/generate.py

@@ -0,0 +1,156 @@
+# 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 配置生成 API 路由模块 (V2)
+
+功能概述:
+- 同步生成 V2 项目配置（manifest、schema、constraint、regex）
+- 调用 ConfigGenerationService 分析数据文件并生成配置
+- 支持自定义采样行数、列数、生成选项等参数
+
+架构设计:
+- 依赖 get_project_config_path 获取项目路径
+- 使用 ConfigGenerationService 封装 AI 配置生成逻辑
+- 对生成过程中的各类异常进行分层处理
+
+输入示例:
+    POST /ai/config/generate
+    {
+        "file_paths": ["data/users.xlsx"],
+        "project_name": "用户数据项目",
+        "project_id": "user-data",
+        "options": {
+            "sample_rows": 100,
+            "generate_schemas": true,
+            "generate_constraints": true
+        }
+    }
+
+输出示例:
+    {
+        "success": true,
+        "yaml_preview": "version: 2...",
+        "manifest": {...},
+        "schemas": {...},
+        "constraints": {...},
+        "regex_nodes": {},
+        "warnings": [],
+        "error": null
+    }
+"""
+
+import logging
+
+from fastapi import Depends, HTTPException
+
+from app.api.dependencies import get_project_config_path
+from app.shared.services.llm.generation import (
+    CancelledError,
+    ConfigGenerationService,
+    GenerationOptions,
+    GenerationParseError,
+    ProfilingOptions,
+)
+
+from .models import ConfigGenerateRequest, ConfigGenerateResponse
+from .router import router
+
+
+@router.post(
+    "/config/generate",
+    response_model=ConfigGenerateResponse,
+    summary="同步生成 V2 配置",
+    responses={
+        400: {"description": "参数错误"},
+        409: {"description": "生成任务已取消"},
+        422: {"description": "AI 响应解析失败"},
+        500: {"description": "服务器内部错误"},
+    },
+)
+async def generate_v2_config(
+    payload: ConfigGenerateRequest,
+    config_path: str = Depends(get_project_config_path),
+) -> ConfigGenerateResponse:
+    """
+    同步生成 V2 配置
+
+    使用配置的 AI Provider 分析数据文件并生成项目配置。
+    包括数据探查（Profiling）和配置生成两个主要阶段。
+
+    Args:
+        payload: 配置生成请求，包含文件路径、项目信息和生成选项
+        config_path: 项目配置文件路径（由依赖注入提供）
+
+    Returns:
+        包含生成结果、YAML 预览和错误信息的响应对象
+
+    Raises:
+        HTTPException: 参数错误(400)、AI解析失败(422)、任务取消(409)、服务器错误(500)
+    """
+    # 构建数据探查选项（控制采样策略）
+    profiling_opts = ProfilingOptions(
+        sample_rows=payload.options.sample_rows,
+        sample_values_per_column=payload.options.sample_values_per_column,
+        max_files=payload.options.max_files,
+        max_cell_chars=payload.options.max_cell_chars,
+    )
+
+    # 构建生成选项（控制输出内容）
+    gen_opts = GenerationOptions(
+        generate_schemas=payload.options.generate_schemas,
+        generate_constraints=payload.options.generate_constraints,
+        generate_regex_nodes=payload.options.generate_regex_nodes,
+        keep_existing=payload.options.keep_existing,
+    )
+
+    # 创建配置生成服务实例（指定使用的 AI Provider）
+    service = ConfigGenerationService(provider_id=payload.provider_id)
+
+    try:
+        # 调用服务执行配置生成
+        result = await service.generate(
+            file_paths=payload.file_paths,
+            project_name=payload.project_name,
+            project_id=payload.project_id,
+            config_path=config_path,
+            profiling_options=profiling_opts,
+            generation_options=gen_opts,
+        )
+    except ValueError as e:
+        # 参数校验失败（如文件不存在、Provider 未配置等）
+        raise HTTPException(status_code=400, detail=f"生成请求无法处理：{e}")
+    except GenerationParseError as e:
+        # AI 返回的内容无法解析为有效配置
+        raise HTTPException(status_code=422, detail=f"AI 响应解析失败: {e}")
+    except CancelledError:
+        # 生成任务被用户取消
+        raise HTTPException(status_code=409, detail="生成任务已取消")
+    except Exception:
+        # 其他未预期的服务器错误
+        logging.getLogger(__name__).exception("Config generation failed")
+        raise HTTPException(status_code=500, detail="配置生成失败，请稍后重试")
+
+    # 组装响应对象
+    return ConfigGenerateResponse(
+        success=result["success"],
+        yaml_preview=result["yaml_preview"],
+        manifest=result["manifest"],
+        schemas=result["schemas"],
+        constraints=result["constraints"],
+        regex_nodes=result["regex_nodes"],
+        warnings=result.get("warnings", []),
+        error=result.get("error"),
+    )