295 lines
8.0 KiB
Markdown
295 lines
8.0 KiB
Markdown
# 小狸 Pro-CLI
|
||
|
||
<p align="center">
|
||
<strong>智能编程助手 — 支持精准代码编辑、代码搜索、Git 版本控制、多 AI 引擎切换</strong>
|
||
</p>
|
||
|
||
<p align="center">
|
||
<img src="https://img.shields.io/badge/version-5.1.1-blue" alt="version">
|
||
<img src="https://img.shields.io/badge/python-3.8+-green" alt="python">
|
||
<img src="https://img.shields.io/badge/license-MIT-orange" alt="license">
|
||
</p>
|
||
|
||
---
|
||
|
||
## ✨ 特性
|
||
|
||
- 🤖 **多 AI 引擎** — 支持 Ollama 本地模型 + OpenAI 兼容格式（DeepSeek、Grok、硅基流动等），随时切换
|
||
- 🔧 **精准代码编辑** — 搜索替换、批量编辑、diff 对比、行级操作
|
||
- 🔍 **代码搜索理解** — 跨文件搜索、正则匹配、符号提取、依赖分析
|
||
- 🔄 **Git 版本控制** — 完整 Git 操作支持
|
||
- 🎨 **双模式界面** — TUI 图形化界面（默认）+ 传统命令行模式
|
||
- 🧩 **三协议插件系统** — Plugin 协议 / Skill 协议 / MCP 协议
|
||
- 🌐 **WebSocket 远程** — 支持远程连接
|
||
- 🛡️ **代码沙箱** — 安全的代码执行环境
|
||
|
||
## 📦 快速开始
|
||
|
||
### 安装
|
||
|
||
```bash
|
||
# 克隆仓库
|
||
git clone https://gitee.com/shuiyu1123/xiaoli-cli.git
|
||
cd xiaoli-cli
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 启动
|
||
|
||
```bash
|
||
# TUI 模式（默认，需 textual）
|
||
python -m xiaoli
|
||
|
||
# CLI 模式
|
||
python -m xiaoli --cli
|
||
|
||
# 指定引擎
|
||
python -m xiaoli --engine openai
|
||
|
||
# 查看版本
|
||
python -m xiaoli --version
|
||
```
|
||
|
||
### 依赖
|
||
|
||
**核心依赖：**
|
||
|
||
| 包名 | 用途 |
|
||
|------|------|
|
||
| `colorama` | 终端彩色输出 |
|
||
| `openai` | OpenAI 兼容接口 |
|
||
| `requests` | HTTP 请求 |
|
||
| `Pillow` | 图像处理 |
|
||
| `numpy` | 数值计算 |
|
||
|
||
**可选依赖：**
|
||
|
||
| 包名 | 用途 |
|
||
|------|------|
|
||
| `textual` | TUI 模式 |
|
||
| `opencv-python` | 图像处理增强 |
|
||
| `pygame` | 音频播放 |
|
||
| `websockets` | WebSocket 远程 |
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
```
|
||
xiaoli-cli/
|
||
├── xiaoli/ # 核心包（v3.6+ 模块化架构）
|
||
│ ├── __init__.py # 版本信息
|
||
│ ├── __main__.py # 入口点 (python -m xiaoli)
|
||
│ ├── app.py # 主应用（编排层）
|
||
│ ├── config.py # 配置管理
|
||
│ ├── engines.py # AI 引擎管理
|
||
│ ├── sandbox.py # 代码安全沙箱
|
||
│ ├── prompt.py # 系统提示词
|
||
│ ├── tui.py # TUI 界面
|
||
│ ├── conversation/ # 对话处理
|
||
│ │ ├── __init__.py # 响应解析器
|
||
│ │ └── history.py # 聊天记录
|
||
│ └── display/ # 显示输出
|
||
│ └── __init__.py # CLI/TUI 双模式
|
||
│
|
||
├── plugins/ # 插件（Plugin 协议）
|
||
│ ├── code_editor.py # 精准代码编辑器 ⭐
|
||
│ ├── code_search.py # 代码搜索理解 ⭐
|
||
│ ├── git_tools.py # Git 版本控制 ⭐
|
||
│ ├── file_manager.py # 文件管理
|
||
│ ├── cmd_executor.py # 命令执行
|
||
│ ├── ai_search.py # AI 搜索
|
||
│ ├── auto_engineer.py # 自动工程化
|
||
│ ├── project_analyzer.py # 项目分析
|
||
│ ├── git_workflow.py # Git 工作流
|
||
│ ├── scheduler.py # 任务调度
|
||
│ └── ...
|
||
│
|
||
├── skills/ # 技能（Skill 协议）
|
||
│ ├── base.py # 技能基类
|
||
│ ├── code_stats.py # 代码统计
|
||
│ └── file-manager/ # 文件管理技能
|
||
│
|
||
├── ai_engines/ # AI 引擎
|
||
│ ├── ollama_engine.py # Ollama 本地模型
|
||
│ └── openai_engine.py # OpenAI 兼容格式（DeepSeek/Grok/硅基流动等）
|
||
│
|
||
├── image_engine/ # 图像引擎
|
||
├── core/ # 旧版核心模块（兼容）
|
||
├── tests/ # 测试套件
|
||
├── 开发文档/ # 开发文档
|
||
├── ai_cli.py # 旧版入口（兼容）
|
||
├── launcher.py # 启动器
|
||
├── websocket_server.py # WebSocket 服务
|
||
└── requirements.txt # 依赖清单
|
||
```
|
||
|
||
## 🎮 使用指南
|
||
|
||
### 内置命令
|
||
|
||
| 命令 | 说明 |
|
||
|------|------|
|
||
| `/help` | 显示帮助信息 |
|
||
| `/quit` | 退出程序 |
|
||
| `/about` | 显示版本信息 |
|
||
| `/model <引擎>` | 切换 AI 引擎 |
|
||
| `/engine list` | 列出可用引擎 |
|
||
| `/chat save <名称>` | 保存聊天记录 |
|
||
| `/chat list` | 列出聊天记录 |
|
||
| `/chat open <名称>` | 加载聊天记录 |
|
||
| `/file.read <路径>` | 读取文件 |
|
||
| `/tui` | 切换 TUI 模式 |
|
||
|
||
### 核心工具
|
||
|
||
#### 代码编辑器 (`code_editor`)
|
||
|
||
```bash
|
||
# 精准替换
|
||
{"action":"use_tool","tool":"code_editor","args":"edit src/app.py
|
||
def old():
|
||
pass
|
||
<<<>>>
|
||
def new():
|
||
return True"}
|
||
|
||
# 批量编辑
|
||
{"action":"use_tool","tool":"code_editor","args":"multi src/app.py [{\"old\":\"old1\",\"new\":\"new1\"}]"}
|
||
|
||
# 查看代码
|
||
{"action":"use_tool","tool":"code_editor","args":"read_range src/app.py 10 20"}
|
||
```
|
||
|
||
#### 代码搜索 (`code_search`)
|
||
|
||
```bash
|
||
# 项目结构
|
||
{"action":"use_tool","tool":"code_search","args":"structure ."}
|
||
|
||
# 搜索代码
|
||
{"action":"use_tool","tool":"code_search","args":"find . process *.py"}
|
||
|
||
# 符号提取
|
||
{"action":"use_tool","tool":"code_search","args":"symbols ."}
|
||
|
||
# 代码统计
|
||
{"action":"use_tool","tool":"code_search","args":"stats ."}
|
||
```
|
||
|
||
#### Git 操作 (`git_tools`)
|
||
|
||
```bash
|
||
{"action":"use_tool","tool":"git_tools","args":"status"}
|
||
{"action":"use_tool","tool":"git_tools","args":"diff"}
|
||
{"action":"use_tool","tool":"git_tools","args":"log --oneline 10"}
|
||
{"action":"use_tool","tool":"git_tools","args":"commit 修复bug"}
|
||
```
|
||
|
||
### AI 引擎
|
||
|
||
| 引擎 | 类型 | 说明 |
|
||
|------|------|------|
|
||
| `ollama` | 本地 | Ollama 本地模型，无需 API 密钥 |
|
||
| `openai` | 云端/本地 | OpenAI 兼容格式，支持 DeepSeek、Grok、硅基流动、本地 vLLM 等 |
|
||
|
||
#### OpenAI 兼容引擎配置示例
|
||
|
||
```json
|
||
{
|
||
"api": {
|
||
"engines": {
|
||
"openai": {
|
||
"api_key": "你的API密钥",
|
||
"base_url": "https://api.deepseek.com/v1",
|
||
"model": "deepseek-chat"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 远程连接
|
||
|
||
```bash
|
||
# 启动 WebSocket 服务
|
||
/remote start 9079 your_password
|
||
|
||
# 代理模式
|
||
/remote proxy relay.example.com:9079 server_pwd 12345 pc_pwd
|
||
```
|
||
|
||
## 🔌 插件开发
|
||
|
||
小狸支持三种插件协议，详见 [开发文档](开发文档/开发文档.md)。
|
||
|
||
### Plugin 协议
|
||
|
||
```python
|
||
class Plugin:
|
||
"""我的插件"""
|
||
|
||
def __init__(self):
|
||
self.usage = "使用说明"
|
||
self.cli = None
|
||
|
||
def get_tool_info(self):
|
||
return {
|
||
"name": "my_tool",
|
||
"description": "工具描述",
|
||
"keywords": ["关键词"],
|
||
"usage": self.usage
|
||
}
|
||
|
||
def handle(self, args: str) -> str:
|
||
return "处理结果"
|
||
```
|
||
|
||
### Skill 协议
|
||
|
||
```python
|
||
from skills.base import Skill, SkillResult
|
||
|
||
class MySkill(Skill):
|
||
name = "my_skill"
|
||
description = "技能描述"
|
||
|
||
def run(self, **kwargs) -> SkillResult:
|
||
return SkillResult(success=True, message="完成")
|
||
```
|
||
|
||
### MCP 协议
|
||
|
||
支持 Anthropic/OpenAI 标准的 Model Context Protocol，可与外部工具无缝集成。
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
python -m pytest tests/
|
||
|
||
# 运行特定测试
|
||
python -m pytest tests/test_sandbox.py
|
||
```
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎贡献！请阅读 [贡献指南](CONTRIBUTING.md)。
|
||
|
||
1. Fork 本仓库
|
||
2. 创建特性分支 (`git checkout -b feat/amazing-feature`)
|
||
3. 提交更改 (`git commit -m 'feat: add amazing feature'`)
|
||
4. 推送分支 (`git push origin feat/amazing-feature`)
|
||
5. 创建 Pull Request
|
||
|
||
## 📄 许可证
|
||
|
||
本项目采用 [MIT License](LICENSE) 开源许可证。
|
||
|
||
## 🔗 链接
|
||
|
||
- 📦 Gitee: https://gitee.com/shuiyu1123/xiaoli-cli
|
||
- 📖 [开发文档](开发文档/开发文档.md)
|
||
- 📋 [更新日志](CHANGELOG.md)
|
||
- ❓ [使用指南](HELP.md)
|