xiaoli-cli/README.md

小狸 Pro-CLI

智能编程助手 — 支持精准代码编辑、代码搜索、Git 版本控制、多 AI 引擎切换

---

✨ 特性

• 🤖 多 AI 引擎 — 支持 Ollama 本地模型 + OpenAI 兼容格式（DeepSeek、Grok、硅基流动等），随时切换
• 🔧 精准代码编辑 — 搜索替换、批量编辑、diff 对比、行级操作
• 🔍 代码搜索理解 — 跨文件搜索、正则匹配、符号提取、依赖分析
• 🔄 Git 版本控制 — 完整 Git 操作支持
• 🎨 双模式界面 — TUI 图形化界面（默认）+ 传统命令行模式
• 🧩 三协议插件系统 — Plugin 协议 / Skill 协议 / MCP 协议
• 🌐 WebSocket 远程 — 支持远程连接
• 🛡️ 代码沙箱 — 安全的代码执行环境

📦 快速开始

安装

# 克隆仓库
git clone https://gitee.com/shuiyu1123/xiaoli-cli.git
cd xiaoli-cli

# 安装依赖
pip install -r requirements.txt

启动

# 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)

# 精准替换
{"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)

# 项目结构
{"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)

{"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 兼容引擎配置示例

{
  "api": {
    "engines": {
      "openai": {
        "api_key": "你的API密钥",
        "base_url": "https://api.deepseek.com/v1",
        "model": "deepseek-chat"
      }
    }
  }
}

远程连接

# 启动 WebSocket 服务
/remote start 9079 your_password

# 代理模式
/remote proxy relay.example.com:9079 server_pwd 12345 pc_pwd

🔌 插件开发

小狸支持三种插件协议，详见 开发文档。

Plugin 协议

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 协议

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，可与外部工具无缝集成。

🧪 测试

# 运行所有测试
python -m pytest tests/

# 运行特定测试
python -m pytest tests/test_sandbox.py

🤝 贡献

欢迎贡献！请阅读 贡献指南。

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 开源许可证。

🔗 链接

• 📦 Gitee: https://gitee.com/shuiyu1123/xiaoli-cli
• 📖 开发文档
• 📋 更新日志
• ❓ 使用指南