precis-cli 0.1.3__py3-none-any.whl

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

@@ -0,0 +1,158 @@
+# 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/switch.py
+"""
+@fileoverview AI Provider 切换命令模块
+
+功能概述:
+- 提供 ai switch 子命令切换默认 AI Provider
+- 支持交互式菜单选择与直接指定 Provider ID
+- 验证目标 Provider 是否有 API Key，无 Key 则拒绝切换
+
+架构设计:
+- AISwitchCommand 继承 Command 基类
+- execute() 根据是否有参数决定交互式切换或直接切换
+- 通过 CLI 配置管理器设置默认 Provider
+
+输入示例:
+    ai switch
+    ai switch openai
+
+输出示例:
+    CommandResult.ok("已切换 Provider")
+    CommandResult.error("Provider 'xxx' 未配置")
+"""
+
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+from app.cli.shell.config_storage import get_cli_config
+from app.cli.shell.formatter import Formatter
+from app.cli.shell.interactive_menu import InteractiveMenu
+
+
+class AISwitchCommand(Command):
+    """切换默认 AI Provider 命令。
+
+    支持交互式菜单或直接指定 Provider ID 切换。
+    """
+
+    def __init__(self) -> None:
+        super().__init__("switch")
+        self._cli_config = get_cli_config()
+
+    @property
+    def description(self) -> str:
+        return "切换默认 AI Provider"
+
+    @property
+    def usage(self) -> str:
+        return "ai switch <provider_id>"
+
+    @property
+    def help_text(self) -> str:
+        return """
+用法: ai switch <provider_id>
+
+示例:
+  ai switch openai   # 切换到 OpenAI
+  ai switch kimi     # 切换到 Kimi
+
+说明:
+  切换到已配置的 Provider。
+  使用 'ai status' 查看可用的 Provider。
+        """.strip()
+
+    def execute(self, args: list[str], context: ProjectContext) -> CommandResult:
+        """执行切换命令。
+
+        Args:
+            args: 命令参数列表，可能包含 Provider ID
+            context: 项目上下文
+
+        Returns:
+            切换成功或失败的结果
+        """
+        providers = self._cli_config.list_providers()
+
+        if not providers:
+            return CommandResult.error("没有已配置的 Provider\n请先使用 'setup' 命令进行配置")
+
+        if not args:
+            # 无参数时进入交互式选择（支持方向键）
+            return self._interactive_switch(providers)
+
+        # 4.4: 大小写不敏感匹配——原实现把参数强转小写后查存储原名（含大写的
+        # provider 恒查不到），交互菜单走原值正常，参数路径自相矛盾
+        raw_id = args[0]
+        provider_id = next(
+            (p.id for p in providers if p.id.lower() == raw_id.lower()),
+            raw_id,
+        )
+        return self._do_switch(provider_id)
+
+    def _interactive_switch(self, providers: list) -> CommandResult:
+        """交互式切换 Provider（支持方向键导航）。
+
+        显示菜单让用户选择要切换到的 Provider。
+
+        Args:
+            providers: 已配置的 Provider 列表
+
+        Returns:
+            切换结果或取消结果
+        """
+        print(Formatter.header("\n切换 AI Provider"))
+
+        active = self._cli_config.get_active_provider()
+
+        # 创建菜单
+        menu = InteractiveMenu("请选择要切换的 Provider:")
+
+        for p in providers:
+            status = ""
+            if active and active.id == p.id:
+                status = " [当前]"
+            key_status = "[有密钥]" if p.api_key else "[无密钥]"
+            label = f"{p.name} {key_status}{status}"
+            menu.add_item(p.id, label, f"模型: {p.model}")
+
+        provider_id = menu.show()
+
+        if provider_id is None:
+            return CommandResult.ok("已取消")
+
+        return self._do_switch(provider_id)
+
+    def _do_switch(self, provider_id: str) -> CommandResult:
+        """执行切换操作。
+
+        验证 Provider 存在，然后设置为默认。
+
+        Args:
+            provider_id: 要切换到的 Provider ID
+
+        Returns:
+            切换成功或失败的结果
+        """
+        provider = self._cli_config.get_provider(provider_id)
+        if not provider:
+            return CommandResult.error(f"Provider '{provider_id}' 未配置\n请先使用 'setup {provider_id}' 进行配置")
+
+        if self._cli_config.set_active_provider(provider_id):
+            print(Formatter.success(f"\n[*] 已切换到 {provider.name}"))
+            print(Formatter.info(f"  模型: {provider.model}"))
+            return CommandResult.ok("已切换 Provider")
+        else:
+            return CommandResult.error("切换失败")

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

@@ -0,0 +1,52 @@
+# 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/utils.py
+"""
+@fileoverview AI 命令共享工具模块
+
+功能概述:
+- 提供 AI 命令的通用工具函数
+- 支持 API Key 脱敏
+
+架构设计:
+- mask_api_key: 对 API Key 进行脱敏处理，保护密钥安全
+
+输入示例:
+    mask_api_key("sk-abcdef1234567890")
+    resolve_table_name("users", "/path/to/project")
+    confirm_actions(actions, reply)
+
+输出示例:
+    "sk-abc...7890"
+    "users_table_id"
+    True/False
+"""
+
+
+def mask_api_key(api_key: str) -> str:
+    """脱敏 API Key，只显示前 6 位和后 4 位。
+
+    如果密钥过短，则显示掩码 ***。
+
+    Args:
+        api_key: 原始 API Key 字符串
+
+    Returns:
+        脱敏后的字符串
+    """
+    if not api_key or len(api_key) < 10:
+        return "***"
+    return f"{api_key[:6]}...{api_key[-4:]}"

app/cli/shell/commands/base.py

@@ -0,0 +1,343 @@
+# 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/base.py
+"""
+@fileoverview CLI Shell 命令基类模块
+
+功能概述:
+- 定义所有 Shell 命令的抽象基类 Command，统一命令的名称、别名、描述与执行接口
+- 提供命令执行结果数据类 CommandResult，支持成功、错误、退出三种结果状态
+- 提供命令执行上下文 CommandContext 与项目上下文 ProjectContext，用于保存运行时状态
+
+架构设计:
+- Command 抽象基类规范命令的基本属性与接口：
+  - name: 命令名称
+  - aliases: 命令别名列表
+  - description: 命令描述（抽象属性，子类必须实现）
+  - usage: 命令用法示例
+  - help_text: 自动生成完整帮助文本
+  - execute(): 执行命令的核心方法（抽象方法，子类必须实现）
+  - add_subcommand()/get_subcommand(): 支持子命令注册与查找
+- CommandResult 使用静态工厂方法 ok()/error()/exit() 快速创建结果对象
+- ProjectContext 继承 CommandContext，额外维护当前打开的项目路径和配置
+  - 通过 @property.setter 自动同步到父类的状态字典，确保数据一致性
+
+输入示例:
+    result = CommandResult.ok("操作成功", data={"key": "value"})
+    result = CommandResult.error("文件不存在")
+    result = CommandResult.exit("再见")
+
+输出示例:
+    CommandResult(success=True, message="操作成功", data={'key': 'value'}, should_exit=False)
+    CommandResult(success=False, message="文件不存在", data=None, should_exit=False)
+    CommandResult(success=True, message="再见", data=None, should_exit=True)
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class CommandResult:
+    """命令执行结果数据类。
+
+    封装命令执行后的返回信息，包括是否成功、提示消息、
+    附加数据以及是否需要退出 Shell。
+
+    Attributes:
+        success: 命令是否执行成功
+        message: 返回给用户的提示消息
+        data: 附加数据字典，可选
+        should_exit: 是否触发 Shell 退出，默认为 False
+        exit_code: 显式进程退出码（仅单发模式生效），默认 None 表示由调用方
+            按 success 推导（成功 0 / 失败 1）。用于区分"校验发现数据违规"
+            （1）与"工具自身错误"（2）等不同失败类别
+    """
+
+    success: bool
+    message: str
+    data: dict[str, Any] | None = None
+    should_exit: bool = False
+    exit_code: int | None = None
+
+    @staticmethod
+    def ok(message: str, data: dict[str, Any] | None = None) -> "CommandResult":
+        """创建成功结果。
+
+        Args:
+            message: 成功的提示消息
+            data: 可选的附加数据
+
+        Returns:
+            一个表示成功的 CommandResult 实例
+        """
+        return CommandResult(success=True, message=message, data=data)
+
+    @staticmethod
+    def error(message: str, data: dict[str, Any] | None = None, exit_code: int | None = None) -> "CommandResult":
+        """创建错误结果。
+
+        Args:
+            message: 错误的提示消息
+            data: 可选的附加数据
+            exit_code: 可选的显式进程退出码（仅单发模式生效），
+                如工具自身错误（参数错误/文件不存在）传 2
+
+        Returns:
+            一个表示失败的 CommandResult 实例
+        """
+        return CommandResult(success=False, message=message, data=data, exit_code=exit_code)
+
+    @staticmethod
+    def exit(message: str = "再见!") -> "CommandResult":
+        """创建退出结果。
+
+        当返回此结果时，Shell 主循环检测到 should_exit=True 后会终止运行。
+
+        Args:
+            message: 退出前的告别消息，默认为 "再见!"
+
+        Returns:
+            一个触发退出的 CommandResult 实例
+        """
+        return CommandResult(success=True, message=message, should_exit=True)
+
+
+class Command(ABC):
+    """命令抽象基类。
+
+    所有 CLI 命令都应继承此类并实现 execute() 方法。
+    子类需要提供 name（命令名）、description（描述）以及 execute（执行逻辑）。
+
+    Attributes:
+        name: 命令名称，用户在 Shell 中输入的标识
+        aliases: 命令别名列表，用于简化输入
+        _subcommands: 子命令字典，键为子命令名，值为子命令实例
+    """
+
+    def __init__(self, name: str, aliases: list[str] | None = None):
+        """初始化命令。
+
+        Args:
+            name: 命令名称
+            aliases: 命令别名列表，默认为空列表
+        """
+        self.name = name
+        self.aliases = aliases or []
+        # 子命令字典：用于聚合命令模式，如 project 命令包含 open/status 子命令
+        self._subcommands: dict[str, Command] = {}
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """命令描述（抽象属性）。
+
+        子类必须实现此属性，返回简短的命令说明文字。
+
+        Returns:
+            命令描述字符串
+        """
+        pass
+
+    @property
+    def usage(self) -> str:
+        """命令用法示例。
+
+        Returns:
+            默认返回命令名称，子类可覆盖提供更详细的用法说明
+        """
+        return self.name
+
+    @property
+    def help_text(self) -> str:
+        """完整的帮助文本。
+
+        自动生成包含用法、描述和别名的帮助信息。
+
+        Returns:
+            格式化的多行帮助文本
+        """
+        lines = [
+            f"用法: {self.usage}",
+            "",
+            self.description,
+        ]
+        if self.aliases:
+            lines.append(f"别名: {', '.join(self.aliases)}")
+        return "\n".join(lines)
+
+    @abstractmethod
+    def execute(self, args: list[str], context: "ProjectContext") -> CommandResult:
+        """执行命令（抽象方法）。
+
+        子类必须实现此方法，包含命令的核心业务逻辑。
+
+        Args:
+            args: 命令参数列表（按空格分割后的字符串数组）
+            context: 项目上下文，包含共享状态和项目信息
+
+        Returns:
+            命令执行结果（CommandResult）
+        """
+        pass
+
+    def add_subcommand(self, name: str, command: "Command") -> None:
+        """添加子命令。
+
+        用于聚合命令模式，例如 project 命令包含 open/status/history 等子命令。
+
+        Args:
+            name: 子命令名称
+            command: 子命令实例
+        """
+        self._subcommands[name] = command
+
+    def get_subcommand(self, name: str) -> Optional["Command"]:
+        """获取子命令。
+
+        Args:
+            name: 子命令名称
+
+        Returns:
+            子命令实例，如果不存在则返回 None
+        """
+        return self._subcommands.get(name)
+
+    def list_subcommands(self) -> list[str]:
+        """列出所有已注册的子命令名称。
+
+        Returns:
+            子命令名称列表
+        """
+        return list(self._subcommands.keys())
+
+
+class CommandContext:
+    """命令执行上下文。
+
+    提供命令执行期间需要访问的共享状态。
+    本质上是一个键值对容器，允许不同命令之间传递数据。
+
+    使用示例:
+        context.set("username", "admin")
+        value = context.get("username")  # "admin"
+    """
+
+    def __init__(self) -> None:
+        # 内部状态字典，存储所有上下文键值对
+        self._state: dict[str, Any] = {}
+
+    def set(self, key: str, value: Any) -> None:
+        """设置上下文值。
+
+        Args:
+            key: 键名
+            value: 任意类型的值
+        """
+        self._state[key] = value
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """获取上下文值。
+
+        Args:
+            key: 键名
+            default: 键不存在时返回的默认值
+
+        Returns:
+            键对应的值，如果键不存在则返回 default
+        """
+        return self._state.get(key, default)
+
+    def has(self, key: str) -> bool:
+        """检查上下文是否存在指定键。
+
+        Args:
+            key: 键名
+
+        Returns:
+            如果键存在于上下文中则返回 True，否则返回 False
+        """
+        return key in self._state
+
+
+class ProjectContext(CommandContext):
+    """项目上下文，扩展命令上下文。
+
+    在 CommandContext 的基础上，增加了项目相关的专用属性：
+    - project_path: 当前打开的项目目录路径
+    - project_config: 当前项目的配置字典（通常从 project.precis.yaml 解析）
+
+    通过 @property.setter 设置 project_path 或 project_config 时，
+    会自动同步到父类的状态字典中，确保数据一致性。
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._project_path: str | None = None
+        self._project_config: dict[str, Any] | None = None
+
+    @property
+    def project_path(self) -> str | None:
+        """当前项目路径。
+
+        Returns:
+            已打开项目的绝对路径，未打开则返回 None
+        """
+        return self._project_path
+
+    @project_path.setter
+    def project_path(self, path: str | None) -> None:
+        """设置当前项目路径。
+
+        同时自动同步到上下文字典中，便于统一访问。
+
+        Args:
+            path: 项目目录的绝对路径，或 None 表示关闭项目
+        """
+        self._project_path = path
+        self.set("project_path", path)
+
+    @property
+    def project_config(self) -> dict[str, Any] | None:
+        """当前项目配置。
+
+        Returns:
+            项目配置字典（通常包含 project、settings、schemas 等字段），
+            如果未加载则返回 None
+        """
+        return self._project_config
+
+    @project_config.setter
+    def project_config(self, config: dict[str, Any] | None) -> None:
+        """设置当前项目配置。
+
+        同时自动同步到上下文字典中。
+
+        Args:
+            config: 项目配置字典，或 None 表示清空配置
+        """
+        self._project_config = config
+        self.set("project_config", config)
+
+    @property
+    def is_project_open(self) -> bool:
+        """是否已打开项目。
+
+        Returns:
+            如果 project_path 不为 None，说明已打开项目，返回 True
+        """
+        return self._project_path is not None

app/cli/shell/commands/config/__init__.py

@@ -0,0 +1,131 @@
+# 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 CLI Shell 配置管理命令模块入口
+
+功能概述:
+- 提供 config 命令聚合配置相关子命令
+- 支持 show、edit、list、init、get、set、check 子命令分发
+
+架构设计:
+- ConfigCommand 作为聚合命令，包含多个子命令实例
+- 使用字典映射子命令名到实例，实现快速分发
+- execute() 方法负责参数校验和子命令路由
+
+输入示例:
+    config show
+    config get project.precis.yaml project.name
+
+输出示例:
+    子命令的执行结果
+"""
+
+from __future__ import annotations
+
+from app.cli.shell.commands.base import Command, CommandResult, ProjectContext
+from app.cli.shell.commands.config.check import ConfigCheckCommand
+from app.cli.shell.commands.config.edit import ConfigEditCommand
+from app.cli.shell.commands.config.get import ConfigGetCommand
+from app.cli.shell.commands.config.init import ConfigInitCommand
+from app.cli.shell.commands.config.inspect import ConfigInspectCommand
+from app.cli.shell.commands.config.list import ConfigListCommand
+from app.cli.shell.commands.config.set import ConfigSetCommand
+from app.cli.shell.commands.config.show import ConfigShowCommand
+
+
+class ConfigCommand(Command):
+    """配置管理命令。
+
+    聚合所有配置相关的子命令，包括查看、编辑、列表、初始化、获取、设置、检查。
+    """
+
+    def __init__(self) -> None:
+        super().__init__("config")
+        self._show_cmd = ConfigShowCommand()
+        self._edit_cmd = ConfigEditCommand()
+        self._list_cmd = ConfigListCommand()
+        self._init_cmd = ConfigInitCommand()
+        self._get_cmd = ConfigGetCommand()
+        self._set_cmd = ConfigSetCommand()
+        self._check_cmd = ConfigCheckCommand()
+        self._inspect_cmd = ConfigInspectCommand()
+
+        # 注册子命令
+        self.add_subcommand("show", self._show_cmd)
+        self.add_subcommand("edit", self._edit_cmd)
+        self.add_subcommand("list", self._list_cmd)
+        self.add_subcommand("init", self._init_cmd)
+        self.add_subcommand("get", self._get_cmd)
+        self.add_subcommand("set", self._set_cmd)
+        self.add_subcommand("check", self._check_cmd)
+        self.add_subcommand("inspect", self._inspect_cmd)
+
+    @property
+    def description(self) -> str:
+        return "管理项目配置文件"
+
+    @property
+    def usage(self) -> str:
+        return "config <show|edit|list|init|get|set|check|inspect>"
+
+    def execute(self, args: list[str], context: ProjectContext) -> CommandResult:
+        """执行配置管理命令。
+
+        校验参数并分发给对应的子命令执行。
+
+        Args:
+            args: 命令参数列表，第一个元素为子命令名
+            context: 项目上下文
+
+        Returns:
+            子命令执行结果或错误提示
+        """
+        if not args:
+            return CommandResult.error(
+                "请指定子命令: show, edit, list, init, get, set, check, inspect\n"
+                "用法: config <subcommand> [options]\n\n"
+                "子命令说明:\n"
+                "  show    - 显示配置文件内容\n"
+                "  edit    - 编辑配置文件\n"
+                "  list    - 列出所有配置文件\n"
+                "  init    - 初始化新配置文件\n"
+                "  get     - 获取配置项值\n"
+                "  set     - 设置配置项值\n"
+                "  check   - 检查配置文件语法格式\n"
+                "  inspect - 执行配置跨文件一致性自检"
+            )
+
+        subcommand = args[0]
+        sub_args = args[1:]
+
+        subcommands: dict[str, Command] = {
+            "show": self._show_cmd,
+            "edit": self._edit_cmd,
+            "list": self._list_cmd,
+            "init": self._init_cmd,
+            "get": self._get_cmd,
+            "set": self._set_cmd,
+            "check": self._check_cmd,
+            "inspect": self._inspect_cmd,
+        }
+
+        if subcommand in subcommands:
+            return subcommands[subcommand].execute(sub_args, context)
+        else:
+            return CommandResult.error(f"未知子命令: {subcommand}")
+
+
+__all__ = ["ConfigCommand"]