precis-cli 0.1.3__py3-none-any.whl

app/cli/shell/commands/ai/executor.py

@@ -0,0 +1,225 @@
+# 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 聊天命令的主入口
+- 辅助函数已拆分到 executor_utils.py / diff.py / display.py
+"""
+
+from __future__ import annotations
+
+import logging
+
+from app.cli.shell.commands.base import CommandResult, ProjectContext
+from app.cli.shell.formatter import Formatter
+from app.shared.services.ai.chat_orchestrator import AIChatOrchestrator, ChatOptions
+from app.shared.services.llm.providers.base import compute_token_budgets, resolve_context_window
+
+from .display import _display_execution_results, _display_tool_trail
+from .executor_utils import (
+    SpinnerController,
+    _collect_all_config_files,
+    _collect_declared_new_files,
+    _get_provider_display,
+    _get_provider_with_key,
+)
+from .interaction import confirm_actions as base_confirm_actions
+from .resolver import resolve_ambiguities as base_resolve_ambiguities
+
+# 为模型回复预留的 token 预算
+RESERVED_OUTPUT_TOKENS = 8000
+
+logger = logging.getLogger(__name__)
+
+
+def execute_ai_chat(
+    message: str,
+    context: ProjectContext,
+    interactive: bool = False,
+    history: list[dict[str, str]] | None = None,
+    agent_mode: bool = True,
+) -> CommandResult:
+    """执行 AI 对话（统一版本）。
+
+    这是 CLI 中执行 AI 对话的核心入口函数，负责：
+    1. 检查项目是否已打开
+    2. 获取并验证 Provider 配置
+    3. 构建 AIChatOrchestrator 和 ChatOptions
+    4. 在后台运行异步对话任务
+    5. 显示结果和 diff
+
+    Args:
+        message: 用户输入的消息内容
+        context: 命令上下文，必须包含打开的项目路径
+        interactive: 是否为交互模式（显示 spinner、提示确认等）
+        history: 对话历史记录列表，每个元素包含 role 和 content
+        agent_mode: 是否启用 Agent 深度模式（默认 True），CLI 无画布时仍走 Agent 工具循环
+
+    Returns:
+        命令执行结果，成功时 data 包含 reply、actions 和 frontend_instructions
+    """
+    if not context.is_project_open:
+        return CommandResult.error("未打开项目，请先使用 'open <path>' 命令打开项目")
+
+    project_path = context.project_path
+
+    # 获取用于显示的 Provider 配置（脱敏，用于日志或展示）
+    provider_config_display = _get_provider_display()
+    if not provider_config_display:
+        return CommandResult.error("没有可用的 LLM Provider 配置，请先运行 'setup' 命令配置 AI Provider")
+
+    # 获取包含完整 API Key 的 Provider 配置（用于实际调用 API）
+    provider_config = _get_provider_with_key()
+    if not provider_config:
+        return CommandResult.error("无法获取 Provider 配置信息")
+
+    # 创建 AI 对话编排器，负责与 AI 模型通信
+    orchestrator = AIChatOrchestrator(provider_config)
+
+    from app.cli.shell.commands.ai.interaction import build_context_data
+
+    # 构建上下文数据：提取项目中的 schema 信息作为 AI 的上下文
+    context_data = build_context_data(message, context)
+    context_nodes = context_data.get("context", {}).get("selectedNodes", [])
+
+    # 创建 spinner 控制器（仅在交互模式下启用）
+    spinner = SpinnerController() if interactive else None
+
+    # 包装回调函数，在调用前暂停 spinner，调用后恢复 spinner
+    # 避免 spinner 动画与用户输入提示重叠
+    def confirm_actions_wrapper(actions: list[dict], reply: str) -> bool:
+        if spinner:
+            spinner.pause()
+        try:
+            return base_confirm_actions(actions, reply)
+        finally:
+            if spinner:
+                spinner.resume()
+
+    def ambiguity_resolver_wrapper(actions: list[dict], project_path: str) -> bool:
+        if spinner:
+            spinner.pause()
+        try:
+            return base_resolve_ambiguities(actions, project_path)
+        finally:
+            if spinner:
+                spinner.resume()
+
+    # 根据模型上下文窗口计算历史预算（用户输入 > 自动探测 > 全局回退）。
+    # 4.24: 预算经 compute_token_budgets 按窗裁剪——原 max(cw-8000, 4096) 在
+    # cw<12k 时输入+输出预算之和超过窗口，每次请求必超窗
+    context_window = resolve_context_window(provider_config)
+    max_history_tokens, _output_budget = compute_token_budgets(context_window)
+
+    # 配置对话选项
+    options = ChatOptions(
+        history=history or [],
+        max_history_tokens=max_history_tokens,
+        temperature=0.1,
+        enable_interactive=interactive,
+        return_frontend_instructions=True,
+        confirm_callback=confirm_actions_wrapper if interactive else None,
+        ambiguity_resolver=ambiguity_resolver_wrapper if interactive else None,
+        agent_mode=agent_mode,
+        max_agent_iterations=5,
+        canvas_nodes=[],
+    )
+
+    try:
+        import asyncio
+
+        # 收集原始文件内容（仅在交互模式下，用于 diff 对比）。
+        # 4.25: AI 本次新建的文件纳入执行前缓存（登记为空内容）——执行后它们
+        # 存在而缓存里没有，diff 生成器会跳过，新建文件的变更在摘要里永不显示
+        original_files_cache = {}
+        if interactive and project_path:
+            original_files_cache = _collect_all_config_files(project_path)
+
+        # 启动 spinner 动画，提示用户 AI 正在处理
+        if spinner:
+            spinner.start()
+
+        # 执行 AI 对话（CLI 是同步环境：asyncio.run 创建一次性事件循环并在结束时确保关闭，
+        # 不再使用已弃用的 get_event_loop + run_until_complete，避免循环泄漏）
+        result = asyncio.run(
+            orchestrator.execute_chat(
+                message=message,
+                project_path=project_path,
+                context_nodes=context_nodes,
+                options=options,
+            )
+        )
+
+        # 停止 spinner 动画
+        if spinner:
+            spinner.stop()
+
+        # 处理结果：如果失败则返回错误
+        if not result.success:
+            error_msg = result.error or "AI 对话失败"
+            if interactive:
+                print(Formatter.error(f"\n{error_msg}"))
+            return CommandResult.error(error_msg)
+
+        reply = result.reply
+        actions = result.actions
+
+        # 在交互模式下显示 AI 的文本回复
+        if interactive:
+            if reply:
+                print(reply)
+
+        # 在交互模式下显示 Agent 工具轨迹（仅 Agent 模式有 tool_steps）
+        if interactive and agent_mode and result.tool_steps:
+            _display_tool_trail(result.tool_steps)
+
+        # 在交互模式下显示执行结果和 diff。
+        # 4.25: AI 本次新建的文件先登记进缓存（空内容）——执行后它们存在而缓存
+        # 没有，diff 生成器会跳过，新建文件的变更在摘要里永不显示
+        if interactive and actions and project_path is not None:
+            for declared in _collect_declared_new_files(result, project_path):
+                original_files_cache.setdefault(declared, "")
+            _display_execution_results(result, project_path, original_files_cache)
+
+        return CommandResult.ok(
+            reply if not interactive else "",
+            data={
+                "reply": reply,
+                "actions": actions,
+                "frontend_instructions": result.frontend_instructions,
+            },
+        )
+
+    except Exception as e:
+        # 发生异常时确保 spinner 停止，避免动画残留
+        if spinner:
+            spinner.stop()
+
+        logger.error(f"AI 对话失败: {e}", exc_info=True)
+        error_msg = f"AI 对话失败: {str(e)}"
+
+        if interactive:
+            print(Formatter.error(error_msg))
+            # 针对 HTTP 400 错误提供诊断提示
+            if "HTTP 400" in str(e) or "Bad Request" in str(e):
+                print(Formatter.warning("\n[诊断提示]"))
+                print(Formatter.info("  1. 检查模型名称是否正确（如 qwen-turbo, qwen-max 等）"))
+                print(Formatter.info("  2. 检查 API Key 是否有效"))
+                print(Formatter.info("  3. 检查网络连接是否正常"))
+                print(Formatter.info("  4. 某些模型可能不支持某些参数，尝试切换模型"))
+
+        return CommandResult.error(error_msg)

app/cli/shell/commands/ai/executor_utils.py

@@ -0,0 +1,271 @@
+# 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/cli/shell/commands/ai/executor_utils.py
+"""
+@fileoverview AI 对话执行器模块
+
+功能概述:
+- 统一执行 AI 对话，确保 CLI 与 API 使用相同的底层逻辑
+- 支持交互式确认、歧义解析、流式输出与 diff 展示
+- 集成 Spinner 控制器（加载动画）与文件修改前后对比
+- 负责将 AI 返回的动作（如添加约束）应用到项目配置文件中
+
+架构设计:
+- SpinnerController: 独立的线程控制器，在 AI 处理请求时显示旋转动画
+- _get_provider_with_key(): 获取包含完整 API Key 的 Provider 配置
+- _get_provider_display(): 获取用于显示的 Provider 配置（API Key 脱敏）
+- _collect_all_config_files(): 在执行 AI 前收集所有配置文件内容，用于后续 diff 对比
+- _generate_diff(): 使用 Python 标准库 difflib 生成统一差异格式（unified diff）
+- _show_diff_summary(): 显示修改摘要（新增/删除/修改）并询问是否查看详细 diff
+- _display_detailed_diff(): 使用颜色高亮显示详细的 diff 内容
+- _display_execution_results(): 主入口，根据是否有文件修改决定如何展示结果
+- execute_ai_chat(): 对外暴露的统一执行函数，协调所有子模块完成一次 AI 对话
+
+输入示例:
+    result = execute_ai_chat(
+        message="在 users 表的 email 列添加非空约束",
+        context=project_context,
+        interactive=True,
+        history=[],
+    )
+
+输出示例:
+    CommandResult(
+        success=True,
+        message="",
+        data={
+            "reply": "已为您添加非空约束...",
+            "actions": [...],
+            "frontend_instructions": [...],
+        },
+    )
+"""
+
+import logging
+import threading
+import time
+from pathlib import Path
+
+from app.cli.shell.commands.ai.utils import mask_api_key
+from app.cli.shell.config_storage import get_cli_config
+from app.cli.shell.formatter import Colors, Formatter
+from app.shared.services.llm.config.models import AIProvider
+
+logger = logging.getLogger(__name__)
+
+
+class SpinnerController:
+    """Spinner 控制器，支持暂停和恢复。
+
+    在 AI 处理请求期间，在终端显示一个旋转的动画字符，
+    提示用户程序正在工作中。支持在需要用户交互时暂停动画。
+
+    Attributes:
+        _stop_event: 线程事件，用于通知 spinner 线程停止
+        _pause_event: 线程事件，用于通知 spinner 线程暂停
+        _thread: spinner 后台线程实例
+        _chars: 旋转动画使用的 Unicode 字符列表
+    """
+
+    def __init__(self) -> None:
+        self._stop_event = threading.Event()
+        self._pause_event = threading.Event()
+        self._thread: threading.Thread | None = None
+        # Unicode Braille 点字图案，用于终端旋转动画
+        self._chars = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+
+    def start(self) -> None:
+        """启动 spinner 动画。
+
+        创建并启动一个后台守护线程，循环显示旋转字符。
+        """
+        self._stop_event.clear()
+        self._pause_event.clear()
+        self._thread = threading.Thread(target=self._run, daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        """停止 spinner 动画。
+
+        设置停止标志，等待线程结束，并清除终端上的 spinner 残留。
+        """
+        self._stop_event.set()
+        self._pause_event.set()  # 确保线程能退出（如果正处于暂停状态）
+        if self._thread:
+            self._thread.join(timeout=1)
+        # 清除 spinner 行：用空格覆盖并回车
+        print(f"\r{' ' * 20}\r", end="", flush=True)
+
+    def pause(self) -> None:
+        """暂停 spinner（用于显示确认提示等需要用户输入的场景）。"""
+        self._pause_event.set()
+        # 清除当前 spinner 行，避免与后续输出重叠
+        print(f"\r{' ' * 20}\r", end="", flush=True)
+
+    def resume(self) -> None:
+        """恢复 spinner 动画。"""
+        self._pause_event.clear()
+
+    def _run(self) -> None:
+        """spinner 主循环。
+
+        后台线程的运行方法，循环显示旋转字符直到收到停止信号。
+        """
+        i = 0
+        while not self._stop_event.is_set():
+            if not self._pause_event.is_set():
+                char = self._chars[i % len(self._chars)]
+                print(f"\r{Formatter.colorize('AI> ', Colors.CYAN)}{char}", end="", flush=True)
+                i += 1
+            time.sleep(0.1)
+
+
+def _get_provider_with_key() -> AIProvider | None:
+    """
+    获取包含完整 API Key 的 Provider 配置。
+
+    从 CLI 配置中读取当前激活的 Provider（已通过 ConfigLoader 解密 api_key）。
+
+    Returns:
+        AIProvider 实例，如果未配置则返回 None
+    """
+    cli_config = get_cli_config()
+    provider = cli_config.get_active_provider()
+
+    if provider and provider.api_key:
+        return provider
+    return None
+
+
+def _get_provider_display() -> dict[str, object] | None:
+    """获取用于显示的 Provider 配置（API Key 脱敏）。
+
+    将 API Key 替换为掩码形式（如 abc123...xyz），避免在终端泄露密钥。
+
+    Returns:
+        脱敏后的 Provider 信息字典，如果未配置则返回 None
+    """
+    cli_config = get_cli_config()
+    provider = cli_config.get_active_provider()
+
+    if provider and provider.api_key:
+        # 统一使用 AIProvider 的 type 字段（ProviderType 枚举）
+        provider_type = provider.type.value if hasattr(provider.type, "value") else str(provider.type)
+        return {
+            "id": provider.id,
+            "provider": provider_type,
+            "api_key": mask_api_key(provider.api_key),
+            "base_url": provider.base_url,
+            "model": provider.model,
+        }
+    return None
+
+
+def _collect_all_config_files(project_path: str) -> dict[str, str]:
+    """收集项目所有配置文件的内容（用于 diff 对比）。
+
+    在执行 AI 操作前调用，保存 schemas、constraints 和根配置文件的原始内容。
+    AI 执行后，通过对比原始内容与修改后内容生成 diff。
+
+    Args:
+        project_path: 项目根目录路径
+
+    Returns:
+        字典，键为文件绝对路径，值为文件原始内容字符串
+    """
+    files_content = {}
+    project = Path(project_path)
+
+    # 收集 schemas 目录下的所有 .yaml 文件
+    schemas_dir = project / "schemas"
+    if schemas_dir.exists():
+        for sf in schemas_dir.glob("*.yaml"):
+            try:
+                files_content[str(sf)] = sf.read_text(encoding="utf-8")
+            except Exception:
+                logger.error("读取 schema 文件失败", exc_info=True)
+
+    # 收集 constraints 目录下的所有 .constraint.yaml 文件
+    constraints_dir = project / "constraints"
+    if constraints_dir.exists():
+        for cf in constraints_dir.glob("*.constraint.yaml"):
+            try:
+                files_content[str(cf)] = cf.read_text(encoding="utf-8")
+            except Exception:
+                logger.error("读取 constraint 文件失败", exc_info=True)
+
+    # 4.25: 收集范围对齐 V2 目录结构——regex/、transforms/ 目录变更不在原范围，
+    # AI 建正则/转换后的变更摘要永不显示（用户看不到 AI 到底改了什么）
+    regex_dir = project / "regex"
+    if regex_dir.exists():
+        for rf in regex_dir.glob("*.regex.yaml"):
+            try:
+                files_content[str(rf)] = rf.read_text(encoding="utf-8")
+            except Exception:
+                logger.error("读取 regex 文件失败", exc_info=True)
+
+    transforms_dir = project / "transforms"
+    if transforms_dir.exists():
+        for tf in transforms_dir.glob("*.transform.yaml"):
+            try:
+                files_content[str(tf)] = tf.read_text(encoding="utf-8")
+            except Exception:
+                logger.error("读取 transform 文件失败", exc_info=True)
+
+    # 收集项目根目录下的核心配置文件
+    for config_file in ["project.precis.yaml", "patterns.precis.yaml"]:
+        config_path = project / config_file
+        if config_path.exists():
+            try:
+                files_content[str(config_path)] = config_path.read_text(encoding="utf-8")
+            except Exception:
+                logger.error("读取配置文件失败", exc_info=True)
+
+    return files_content
+
+
+def _collect_declared_new_files(result: object, project_path: str) -> list[str]:
+    """4.25: 从 AI 执行结果/动作声明中提取本次新建的配置文件路径。
+
+    扫描约束/正则/转换动作声明的 ID，按 V2 目录约定推导文件路径（文件此时
+    可能尚未写盘——调用方仅用于登记缓存键，路径不存在即为"新建"）。
+    """
+    project = Path(project_path)
+    candidates: list[str] = []
+    actions: list[dict] = []
+    # 兼容 ChatAgentResult 形状（.actions）与裸 dict（{"actions": [...]}）
+    if isinstance(result, dict):
+        actions = result.get("actions", []) or []
+    else:
+        actions = getattr(result, "actions", None) or []
+
+    for action in actions:
+        if not isinstance(action, dict):
+            continue
+        action_type = str(action.get("actionType", ""))
+        spec = action.get("constraintSpec") or action.get("regexSpec") or action.get("transformSpec") or {}
+        if not isinstance(spec, dict):
+            continue
+        raw_id = spec.get("constraintId") or spec.get("regexId") or spec.get("transformId") or spec.get("id")
+        if not raw_id or not isinstance(raw_id, str):
+            continue
+        if action_type.startswith("ADD_CONSTRAINT"):
+            candidates.append(str(project / "constraints" / f"{raw_id}.constraint.yaml"))
+        elif action_type.startswith("ADD_REGEX"):
+            candidates.append(str(project / "regex" / f"{raw_id}.regex.yaml"))
+        elif action_type.startswith("ADD_TRANSFORM"):
+            candidates.append(str(project / "transforms" / f"{raw_id}.transform.yaml"))
+    return candidates