# cmd-tool

**Repository Path**: wanmisy/cmd-tool

## Basic Information

- **Project Name**: cmd-tool
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-29
- **Last Updated**: 2026-02-03

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Cola Tools

企业级命令行工具包 - 重构版

## 简介

Cola Tools 是一个企业级命令行工具包，提供了丰富的命令和功能，支持多种工作模式。经过重构，项目现在具有更清晰的架构、更好的可扩展性和更现代化的配置管理。

### 重构亮点

- **模块化架构**：采用清晰的模块划分，提高代码可维护性
- **现代化配置**：支持多种配置源（环境变量、JSON文件等）
- **增强异常处理**：提供结构化异常处理机制
- **可扩展日志系统**：支持日志轮转和多输出目标
- **优化命令系统**：改进命令注册和执行机制
- **现代化界面**：提升命令行用户体验

## 安装

使用 pip 安装（推荐）：
```bash
pip install -r requirements.txt
```

或安装开发依赖：
```bash
pip install -r requirements-dev.txt
```

### 使用阿里云镜像加速（推荐中国用户）

```bash
pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/
```

## 使用方式

### 命令行模式

```bash
python -m src.main --model cmd
```

### AI 模式

```bash
python -m src.main --model ai
```

### 配置文件支持

现在支持配置文件（config.json）和环境变量的混合配置方式：
- 配置文件默认位置：`~/.cola-tool/config.json`
- 环境变量文件：`.env`

## 项目架构

```
src/
├── common/           # 公共组件
│   ├── config/       # 配置管理
│   ├── exceptions/   # 异常处理
│   └── logging/      # 日志系统
├── commands/         # 命令系统
│   ├── base.py       # 命令基类
│   ├── factory.py    # 命令工厂
│   ├── registry.py   # 命令注册
│   └── impl/         # 命令实现
├── modes/            # 应用模式
│   ├── cmd.py        # 命令行模式
│   ├── ai_mode.py    # AI模式
│   └── interfaces.py # 模式接口
├── utils/            # 工具函数
└── main.py           # 应用入口
```

## 配置管理

重构后的配置系统支持：

- **多源配置**：环境变量、配置文件、默认值
- **类型安全**：使用数据类定义配置结构
- **灵活扩展**：支持自定义配置项
- **JSON序列化**：支持配置保存和加载

### 配置选项

- `mode`: 应用模式 (cmd/ai)
- `dashscope_api_key`: DashScope API密钥
- `admin_token`: 管理员令牌
- `log_level`: 日志级别 (DEBUG/INFO/WARNING/ERROR)
- `log_file`: 日志文件路径

## 异常处理

采用层次化异常体系：

- `ColaToolException`: 基础异常类
- `ModeError`: 模式相关错误
- `CommandError`: 命令执行错误
- `ConfigurationError`: 配置错误
- `ValidationError`: 验证错误
- `NetworkError`: 网络错误
- `FileOperationError`: 文件操作错误

## 日志系统

- **多级别支持**：DEBUG, INFO, WARNING, ERROR, CRITICAL
- **日志轮转**：自动轮转大日志文件
- **多输出**：控制台和文件同时输出
- **结构化格式**：统一的日志格式

## 开发指南

### 添加新命令

1. 继承 `commands.base.Command` 基类
2. 实现 `build_parser` 和 `execute` 方法
3. 在命令类中定义 `name` 和 `description` 属性
4. 新命令会自动注册

示例：

```python
from commands.command_base import Command


class MyCommand(Command):
    name = 'my_command'
    description = 'My custom command'

    def build_parser(self, parser):
        parser.add_argument('--option', help='Some option')
        return parser

    def execute(self, args):
        print(f"Executing my command with option: {args.option}")
```

### 运行测试

```bash
# 运行所有单元测试
python -m pytest tests/unit/ -v

# 运行特定测试
python -m pytest tests/unit/test_config.py
```

### 代码格式化

使用 black 格式化代码：
```bash
black src/
```

## 可用命令

运行 `help` 命令查看所有可用命令。

## 贡献

1. Fork 项目
2. 创建功能分支
3. 提交更改
4. 发起 Pull Request

## 许可证

[MIT License](LICENSE)

## MCP 服务器模式（用于 Cherry Studio 等客户端）

### 直接运行

```bash
python src/mcp_server.py
```

### 使用启动脚本运行

#### Windows (cmd/PowerShell)

```bash
scripts\start_mcp.bat
```

#### Linux/macOS (bash)

```bash
bash scripts/start_mcp.sh
```

### 在 Cherry Studio 中配置 MCP 服务器

1. 打开 Cherry Studio
2. 进入设置 -> MCP 服务器
3. 添加新的 MCP 服务器
4. 选择 "STDIO" 类型
5. 设置命令和参数路径
6. 保存并启用服务器