From 4b0c739c07c784f6028e64c59a64fa64e8c85faf Mon Sep 17 00:00:00 2001 From: shuiyu1123 Date: Sat, 25 Apr 2026 13:26:05 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md: 重写中文文档，补充特性说明、项目结构、使用指南 - README.en.md: 重写英文文档，与中文版对齐 - CHANGELOG.md: 补充 v5.0.0 更新日志 - CONTRIBUTING.md: 新增贡献指南 - HELP.md: 更新使用指南，适配 v5.0.0 --- CHANGELOG.md | 35 +++++- CONTRIBUTING.md | 148 +++++++++++++++++++++++ HELP.md | 234 +++++++++++++++++++++++------------- README.en.md | 175 +++++++++++++++++++++++---- README.md | 309 ++++++++++++++++++++++++++++++++++++------------ 5 files changed, 714 insertions(+), 187 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 35f63fa..faae98f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,13 +1,38 @@ # 更新日志 +所有重要更改都记录在此文件中。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.0.0/)。 + +--- + +## v5.0.0 (2026-04-25) + +### 🚀 新增功能 +- **TUI v2** — 全新 TUI 界面，对标 Claude Code / OpenCode，暗色主题 + 现代布局 +- **完整 MCP 协议支持** — 为所有插件添加 MCP (Model Context Protocol) 定义 +- **代码统计 Skill** (`code_stats`) — 新增 Skill 协议示例 +- **工程化自动化插件** — 新增 3 个工程化自动化插件（`auto_engineer`、`project_analyzer`、`git_workflow`） +- **任务调度器** (`scheduler`) — 定时任务支持 + +### 🏗️ 架构改进 +- **重写代码沙箱** — 全新的安全沙箱实现，支持超时控制和资源限制 +- **完整测试套件** — 192 个测试用例，覆盖核心功能 +- **Skill handler 修复** — 修复 Skill 协议参数解析问题 +- **MarkdownSkill MCP** — MCP 定义改为从元数据动态生成 + +### 🐛 修复 +- 修复 MarkdownSkill MCP 定义硬编码问题 +- 修复 Skill handler 参数解析错误 + +--- + ## v3.6.0-release (2026-04-25) ### 🚀 新增功能 -- **精准代码编辑器** (`code_editor`) - 搜索替换、批量编辑、diff 对比、行级操作 -- **代码搜索理解** (`code_search`) - 跨文件搜索、正则匹配、符号提取、依赖分析 -- **Git 版本控制** (`git_tools`) - 完整 Git 操作支持 -- **TUI 默认模式** - 图形化界面为默认启动方式 -- **彩蛋** - 运行 `python easter_egg.py` 发现惊喜 +- **精准代码编辑器** (`code_editor`) — 搜索替换、批量编辑、diff 对比、行级操作 +- **代码搜索理解** (`code_search`) — 跨文件搜索、正则匹配、符号提取、依赖分析 +- **Git 版本控制** (`git_tools`) — 完整 Git 操作支持 +- **TUI 默认模式** — 图形化界面为默认启动方式 +- **彩蛋** — 运行 `python easter_egg.py` 发现惊喜 ### 🏗️ 架构重构 - 拆分 `ai_cli.py`（3860行）为模块化 `xiaoli/` 包 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..52dcf11 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,148 @@ +# 贡献指南 + +感谢你对小狸 Pro-CLI 项目的关注！以下是参与贡献的方式和规范。 + +## 如何贡献 + +### 报告 Bug + +1. 在 Gitee 上创建 [Issue](https://gitee.com/shuiyu1123/xiaoli-cli/issues) +2. 描述清楚问题的复现步骤、期望行为和实际行为 +3. 附上相关的日志输出或截图 +4. 注明你的 Python 版本和操作系统 + +### 提交功能建议 + +1. 创建 Issue，标题以 `[Feature]` 开头 +2. 描述你想要的功能和使用场景 +3. 如果可能，提供实现思路 + +### 提交代码 + +```bash +# 1. Fork 并克隆 +git clone https://gitee.com/你的用户名/xiaoli-cli.git +cd xiaoli-cli + +# 2. 创建特性分支 +git checkout -b feat/你的功能名 + +# 3. 开发并测试 +# ... 编写代码 ... +python -m pytest tests/ + +# 4. 提交 +git add . +git commit -m "feat: 描述你的改动" + +# 5. 推送并创建 PR +git push origin feat/你的功能名 +``` + +## 提交规范 + +使用 [Conventional Commits](https://www.conventionalcommits.org/) 格式： + +``` +(): + +[可选 body] + +[可选 footer] +``` + +### Type 类型 + +| 类型 | 说明 | +|------|------| +| `feat` | 新功能 | +| `fix` | Bug 修复 | +| `docs` | 文档更新 | +| `style` | 代码格式（不影响功能） | +| `refactor` | 重构 | +| `perf` | 性能优化 | +| `test` | 测试相关 | +| `chore` | 构建/工具链 | +| `ci` | CI/CD | + +### 示例 + +``` +feat(plugins): 新增 Docker 管理插件 +fix(sandbox): 修复超时后进程未正确终止 +docs: 更新 README 安装说明 +refactor(engines): 统一引擎初始化逻辑 +``` + +## 插件开发 + +### 新建插件 + +1. 在 `plugins/` 目录创建 `your_plugin.py` +2. 实现 `Plugin` 类： + +```python +class Plugin: + """插件描述""" + + def __init__(self): + self.usage = "使用说明" + self.cli = None + + def set_cli(self, cli): + self.cli = cli + + def get_tool_info(self): + return { + "name": "your_plugin", + "description": "插件描述", + "keywords": ["关键词1", "关键词2"], + "usage": self.usage + } + + def handle(self, args: str) -> str: + try: + # 实现逻辑 + return "结果" + except Exception as e: + return f"错误: {e}" +``` + +3. 可选：实现 `get_mcp_definition()` 支持 MCP 协议 +4. 在 `tests/` 中添加对应测试 + +### 插件检查清单 + +- [ ] 类名是 `Plugin` +- [ ] 实现了 `get_tool_info()` 和 `handle()` +- [ ] 返回值是字符串 +- [ ] 所有异常被捕获 +- [ ] 包含 `usage` 属性 +- [ ] 通过基本测试 + +## 代码风格 + +- 遵循 PEP 8 +- 使用 4 空格缩进 +- 函数和变量使用 `snake_case` +- 类名使用 `PascalCase` +- 字符串优先使用双引号 +- 添加必要的注释和 docstring + +## 测试 + +```bash +# 运行全部测试 +python -m pytest tests/ + +# 运行并显示覆盖率 +python -m pytest tests/ -v --tb=short +``` + +新功能必须包含测试，Bug 修复应补充回归测试。 + +## 问题？ + +如有疑问，欢迎在 Gitee 上提 Issue 或通过以下方式联系： + +- 📦 仓库：https://gitee.com/shuiyu1123/xiaoli-cli diff --git a/HELP.md b/HELP.md index 0b64651..85b1a00 100644 --- a/HELP.md +++ b/HELP.md @@ -1,80 +1,154 @@ -# 小狸 Pro-CLI 使用指南 - -## 基本操作 - -### 启动和退出 -- 启动程序: 运行 `python ai_cli.py` -- 退出程序: 输入 `/quit` - -### 帮助命令 -- `/help` - 显示帮助信息 - -## AI引擎管理 - -### 切换AI引擎 -- `/model spark` - 切换到讯飞星火AI引擎 - -## 聊天记录管理 - -### 保存聊天记录 -- `/chat save <名称>` - 将当前对话保存为指定名称的聊天记录 - -### 查看聊天记录 -- `/chat list` - 显示所有已保存的聊天记录 - -### 加载聊天记录 -- `/chat open <名称>` - 加载指定名称的聊天记录并继续对话 - -## 插件工具 - -AI可以自动调用以下工具来帮助您完成各种任务： - -### 文件管理工具 -- 功能：读取、写入、追加、删除、复制、移动文件和目录操作 -- 用法示例： - - `file_manager list` - 列出当前目录内容 - - `file_manager read test.txt` - 读取文件内容 - - `file_manager write test.txt 内容` - 写入文件 - - `file_manager append test.txt 内容` - 追加内容到文件 - - `file_manager delete test.txt` - 删除文件 - - `file_manager create test.txt` - 创建空文件 - - `file_manager mkdir new_dir` - 创建目录 - - `file_manager copy source.txt dest.txt` - 复制文件 - - `file_manager move source.txt dest.txt` - 移动文件 - - `file_manager info test.txt` - 查看文件信息 - - `file_manager tree` - 显示目录树结构 - -### 音频播放工具 -- 功能：播放音频文件 -- 用法示例： - - `audio_player play` - 播放Ciallo～(∠・ω- )⌒☆-.mp3音频文件 - - `/ciallo` - 播放音频文件 - -## 基本操作命令 - -### 系统信息命令 -- `/about` - 显示程序信息和版本详情 - -## 使用技巧 - -1. **自然语言交互**：直接用自然语言与AI对话，AI会理解您的意图并自动调用相应工具。 - -2. **工具调用**：当AI需要执行特定任务时，会自动调用相应的插件工具，并在屏幕上显示执行结果。 - -3. **聊天记录管理**：可以随时保存当前对话，在需要时加载之前的对话继续交流。 - -4. **路径操作**： - - 支持用户主目录下的绝对路径操作 - - 支持项目目录和当前目录下的相对路径操作 - - 文件大小限制为50MB - -5. **等待动画**：AI思考时会显示随机的温馨句子，每5秒更换一次。 - -6. **插件命令**：可以使用 `/命令名` 直接调用插件功能，如 `/file`、`/read`、`/write`、`/ciallo` 等。 - -## 注意事项 - -- 请勿尝试访问系统关键目录（如Windows系统目录、/etc等） -- 文件操作大小限制为50MB -- 音频播放需要系统支持相应的音频格式 -- 可以随时使用 `/help` 命令查看帮助信息 \ No newline at end of file +# 小狸 Pro-CLI 使用指南 + +## 快速上手 + +### 启动 + +```bash +# TUI 模式（默认） +python -m xiaoli + +# CLI 模式 +python -m xiaoli --cli + +# 指定引擎 +python -m xiaoli --engine ollama +``` + +### 基本操作 + +- **退出程序**: 输入 `/quit` 或 `Ctrl+C` +- **查看帮助**: 输入 `/help` +- **查看版本**: 输入 `/about` + +--- + +## AI 引擎管理 + +### 切换引擎 + +``` +/model ollama # 切换到 Ollama 本地模型 +/model mimo # 切换到小米 MiMo +/model glm # 切换到智谱 GLM +/model qwq # 切换到 QwQ 深度思考 +``` + +### 查看可用引擎 + +``` +/engine list +``` + +--- + +## 聊天记录管理 + +| 命令 | 说明 | +|------|------| +| `/chat save <名称>` | 保存当前对话 | +| `/chat list` | 列出所有保存的对话 | +| `/chat open <名称>` | 加载历史对话 | + +--- + +## 内置工具 + +小狸会根据你的自然语言描述自动选择合适的工具。以下是主要工具： + +### 代码编辑器 (`code_editor`) + +用于精准的代码编辑操作： + +- **替换代码** — 指定文件和要替换的内容 +- **批量编辑** — 一次修改多处 +- **查看代码** — 按行号范围查看 + +### 代码搜索 (`code_search`) + +用于理解和搜索代码库： + +- **项目结构** — 查看目录树 +- **搜索代码** — 按关键词搜索文件 +- **符号提取** — 提取函数、类定义 +- **代码统计** — 代码行数、文件数统计 + +### Git 操作 (`git_tools`) + +- `status` — 查看状态 +- `diff` — 查看变更 +- `log` — 查看提交历史 +- `commit <消息>` — 提交更改 + +### 文件管理 (`file_manager`) + +| 操作 | 说明 | +|------|------| +| `list` | 列出目录内容 | +| `read <路径>` | 读取文件 | +| `write <路径> -c "内容"` | 写入文件 | +| `append <路径> -c "内容"` | 追加内容 | +| `delete <路径>` | 删除文件 | +| `mkdir <路径>` | 创建目录 | +| `copy <源> <目标>` | 复制文件 | +| `move <源> <目标>` | 移动文件 | +| `info <路径>` | 查看文件信息 | +| `tree` | 显示目录树 | + +### 命令执行 (`cmd_executor`) + +直接在沙箱中执行系统命令，支持超时控制。 + +### AI 搜索 (`ai_search`) + +使用 AI 进行智能搜索和问答。 + +--- + +## 自然语言交互 + +你不需要记住命令格式，直接用自然语言描述需求即可： + +``` +"帮我看看 src/app.py 的第 10 到 20 行" +"搜索项目里所有用到 requests.get 的地方" +"提交代码，消息是修复登录bug" +"统计一下这个项目的代码量" +``` + +AI 会自动理解你的意图并调用合适的工具。 + +--- + +## 远程连接 + +### 启动 WebSocket 服务 + +``` +/remote start <端口> <密码> +``` + +### 代理模式 + +``` +/remote proxy <中继地址> <服务器密码> <本地端口> <本地密码> +``` + +--- + +## 使用技巧 + +1. **TUI 模式** — 默认启动 TUI 图形界面，体验更好；使用 `--cli` 切换到传统模式 +2. **引擎选择** — 本地开发用 `ollama`，深度思考用 `qwq`，通用场景用 `mimo` +3. **代码编辑** — 描述需求即可，AI 会自动使用代码编辑器 +4. **Git 工作流** — 自然语言描述，AI 自动执行 Git 操作 +5. **插件扩展** — 可以自行开发插件，详见 [开发文档](开发文档/开发文档.md) + +--- + +## 注意事项 + +- 文件操作大小限制为 50MB +- 代码执行在沙箱环境中，有超时限制 +- 音频播放需要系统支持相应格式 +- TUI 模式需要安装 `textual` 和 `rich` diff --git a/README.en.md b/README.en.md index 8c5bc1e..66824e3 100644 --- a/README.en.md +++ b/README.en.md @@ -1,36 +1,161 @@ -# xiaoli cli +# XiaoLi Pro-CLI -#### Description -本仓库用于提交xiaoli系列源代码，本仓库源于github 2024年九月项目，因账户2fa码丢失，现已迁移至gitee +

+ Intelligent Programming Assistant — Precise Code Editing, Code Search, Git Integration, Multi-AI Engine Support +

-#### Software Architecture -Software architecture description +

+ version + python + license +

-#### Installation +--- -1. xxxx -2. xxxx -3. xxxx +## ✨ Features -#### Instructions +- 🤖 **Multi AI Engines** — Ollama, MiMo, GLM, QwQ, MaaS and more +- 🔧 **Precise Code Editing** — Search & replace, batch edits, diff comparison, line-level operations +- 🔍 **Code Search & Understanding** — Cross-file search, regex matching, symbol extraction, dependency analysis +- 🔄 **Git Integration** — Full Git workflow support +- 🎨 **Dual UI Modes** — TUI graphical interface (default) + traditional CLI mode +- 🧩 **Triple Protocol Plugin System** — Plugin / Skill / MCP protocols +- 🌐 **WebSocket Remote** — Remote connections and QQ bot integration +- 🛡️ **Code Sandbox** — Secure code execution environment -1. xxxx -2. xxxx -3. xxxx +## 📦 Quick Start -#### Contribution +### Installation -1. Fork the repository -2. Create Feat_xxx branch -3. Commit your code -4. Create Pull Request +```bash +git clone https://gitee.com/shuiyu1123/xiaoli-cli.git +cd xiaoli-cli +pip install -r requirements.txt +``` +### Usage -#### Gitee Feature +```bash +# TUI mode (default, requires textual) +python -m xiaoli -1. You can use Readme\_XXX.md to support different languages, such as Readme\_en.md, Readme\_zh.md -2. Gitee blog [blog.gitee.com](https://blog.gitee.com) -3. Explore open source project [https://gitee.com/explore](https://gitee.com/explore) -4. The most valuable open source project [GVP](https://gitee.com/gvp) -5. The manual of Gitee [https://gitee.com/help](https://gitee.com/help) -6. The most popular members [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/) +# CLI mode +python -m xiaoli --cli + +# Specify engine +python -m xiaoli --engine mimo + +# Show version +python -m xiaoli --version +``` + +### Dependencies + +**Core:** + +| Package | Purpose | +|---------|---------| +| `colorama` | Terminal colored output | +| `openai` | OpenAI compatible API | +| `requests` | HTTP requests | +| `Pillow` | Image processing | +| `numpy` | Numerical computation | + +**Optional:** + +| Package | Purpose | +|---------|---------| +| `textual` | TUI mode | +| `opencv-python` | Enhanced image processing | +| `pygame` | Audio playback | +| `websockets` | WebSocket remote | + +## 🏗️ Architecture + +``` +xiaoli-cli/ +├── xiaoli/ # Core package (v3.6+ modular architecture) +│ ├── __main__.py # Entry point (python -m xiaoli) +│ ├── app.py # Main application (orchestration layer) +│ ├── config.py # Configuration management +│ ├── engines.py # AI engine management +│ ├── sandbox.py # Code execution sandbox +│ ├── prompt.py # System prompts +│ ├── tui.py # TUI interface +│ ├── conversation/ # Conversation handling +│ └── display/ # Display output (CLI/TUI dual mode) +│ +├── plugins/ # Plugins (Plugin protocol) +│ ├── code_editor.py # Precise code editor ⭐ +│ ├── code_search.py # Code search & understanding ⭐ +│ ├── git_tools.py # Git version control ⭐ +│ └── ... # 20+ plugins +│ +├── skills/ # Skills (Skill protocol) +├── ai_engines/ # AI engine implementations +├── image_engine/ # Image processing engines +├── tests/ # Test suite +└── requirements.txt # Dependencies +``` + +## 🎮 Commands + +| Command | Description | +|---------|-------------| +| `/help` | Show help | +| `/quit` | Exit | +| `/about` | Show version info | +| `/model ` | Switch AI engine | +| `/engine list` | List available engines | +| `/chat save ` | Save conversation | +| `/chat list` | List conversations | +| `/chat open ` | Load conversation | +| `/tui` | Toggle TUI mode | + +## 🔌 Plugin Development + +XiaoLi supports three plugin protocols. See [Development Documentation](开发文档/开发文档.md) for details. + +### Plugin Protocol + +```python +class Plugin: + def get_tool_info(self): + return {"name": "my_tool", "description": "...", "keywords": [...]} + + def handle(self, args: str) -> str: + return "result" +``` + +### Skill Protocol + +```python +from skills.base import Skill, SkillResult + +class MySkill(Skill): + name = "my_skill" + def run(self, **kwargs) -> SkillResult: + return SkillResult(success=True, message="Done") +``` + +### MCP Protocol + +Supports Anthropic/OpenAI Model Context Protocol for seamless external tool integration. + +## 🤝 Contributing + +1. Fork the repository +2. Create a feature branch (`git checkout -b feat/amazing-feature`) +3. Commit your changes (`git commit -m 'feat: add amazing feature'`) +4. Push to the branch (`git push origin feat/amazing-feature`) +5. Create a Pull Request + +## 📄 License + +This project is licensed under the [MIT License](LICENSE). + +## 🔗 Links + +- 📦 Gitee: https://gitee.com/shuiyu1123/xiaoli-cli +- 📖 [Development Docs](开发文档/开发文档.md) +- 📋 [Changelog](CHANGELOG.md) diff --git a/README.md b/README.md index 4fa189b..7fb0a39 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,155 @@ # 小狸 Pro-CLI -智能编程助手 — 支持精准代码编辑、代码搜索、Git 版本控制、多 AI 引擎切换。 +

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

-## 快速开始 +

+ version + python + license +

+ +--- + +## ✨ 特性 + +- 🤖 **多 AI 引擎** — 支持 Ollama、MiMo、智谱 GLM、QwQ、MaaS 等，随时切换 +- 🔧 **精准代码编辑** — 搜索替换、批量编辑、diff 对比、行级操作 +- 🔍 **代码搜索理解** — 跨文件搜索、正则匹配、符号提取、依赖分析 +- 🔄 **Git 版本控制** — 完整 Git 操作支持 +- 🎨 **双模式界面** — TUI 图形化界面（默认）+ 传统命令行模式 +- 🧩 **三协议插件系统** — Plugin 协议 / Skill 协议 / MCP 协议 +- 🌐 **WebSocket 远程** — 支持远程连接和 QQ 机器人集成 +- 🛡️ **代码沙箱** — 安全的代码执行环境 + +## 📦 快速开始 + +### 安装 ```bash +# 克隆仓库 +git clone https://gitee.com/shuiyu1123/xiaoli-cli.git +cd xiaoli-cli + # 安装依赖 -pip install colorama openai requests Pillow numpy - -# 启动 CLI -python -m xiaoli - -# 或指定引擎 -python -m xiaoli --engine mimo - -# 启动 TUI 模式（需要 textual） -python -m xiaoli --tui +pip install -r requirements.txt ``` -## 核心能力 +### 启动 + +```bash +# TUI 模式（默认，需 textual） +python -m xiaoli + +# CLI 模式 +python -m xiaoli --cli + +# 指定引擎 +python -m xiaoli --engine mimo + +# 查看版本 +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 本地模型 +│ ├── mimo_engine.py # 小米 MiMo +│ ├── GLM_http_engine.py # 智谱 GLM +│ ├── qwq_engine.py # QwQ 深度思考 +│ ├── xfyun_spark_engine.py # 讯飞星火 +│ ├── SDK_openAI.py # OpenAI 兼容 SDK +│ └── ... +│ +├── 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`) -### 代码编辑 (code_editor) ```bash # 精准替换 {"action":"use_tool","tool":"code_editor","args":"edit src/app.py @@ -37,7 +166,8 @@ def new(): {"action":"use_tool","tool":"code_editor","args":"read_range src/app.py 10 20"} ``` -### 代码搜索 (code_search) +#### 代码搜索 (`code_search`) + ```bash # 项目结构 {"action":"use_tool","tool":"code_search","args":"structure ."} @@ -52,7 +182,8 @@ def new(): {"action":"use_tool","tool":"code_search","args":"stats ."} ``` -### Git 操作 (git_tools) +#### Git 操作 (`git_tools`) + ```bash {"action":"use_tool","tool":"git_tools","args":"status"} {"action":"use_tool","tool":"git_tools","args":"diff"} @@ -60,74 +191,98 @@ def new(): {"action":"use_tool","tool":"git_tools","args":"commit 修复bug"} ``` -## 命令 - -| 命令 | 说明 | -|------|------| -| `/help` | 帮助信息 | -| `/quit` | 退出 | -| `/model <引擎>` | 切换 AI 引擎 | -| `/engine list` | 列出可用引擎 | -| `/chat save/list/open` | 聊天记录管理 | -| `/file.read <路径>` | 读取文件 | -| `/tui` | 切换 TUI 模式 | - -## AI 引擎 +### AI 引擎 | 引擎 | 类型 | 说明 | |------|------|------| -| ollama | 本地 | Ollama 本地模型 | -| mimo | 云端 | 小米 MiMo | -| glm_http | 云端 | 智谱 GLM | -| qwq | 云端 | QwQ 深度思考 | -| maas_http | 云端 | MaaS | +| `ollama` | 本地 | Ollama 本地模型，无需 API 密钥 | +| `mimo` | 云端 | 小米 MiMo | +| `glm_http` | 云端 | 智谱 GLM | +| `qwq` | 云端 | QwQ 深度思考引擎 | +| `maas_http` | 云端 | MaaS | +| `spark` | 云端 | 讯飞星火 | +| `iflow` | 云端 | iFlow API | -## 架构 - -``` -xiaoli/ # 新架构（v3.6） -├── __init__.py # 版本信息 -├── __main__.py # 入口点 (python -m xiaoli) -├── app.py # 主应用（薄编排层） -├── config.py # 配置管理 -├── engines.py # AI 引擎管理 -├── sandbox.py # 代码安全沙箱 -├── prompt.py # 系统提示词 -├── conversation/ # 对话处理 -│ ├── __init__.py # 响应解析器 -│ └── history.py # 聊天记录 -└── display/ # 显示输出 - └── __init__.py # CLI/TUI 双模式 - -plugins/ # 插件（Liugin 协议） -├── code_editor.py # 精准代码编辑器 ⭐ -├── code_search.py # 代码搜索理解 ⭐ -├── git_tools.py # Git 版本控制 ⭐ -├── file_manager.py # 文件管理 -├── ai_search.py # AI 搜索 -├── cmd_executor.py # 命令执行 -└── ... - -ai_engines/ # AI 引擎 -├── ollama_engine.py -├── mimo_engine.py -├── GLM_http_engine.py -└── ... -``` - -## 开发 +### 远程连接 ```bash -# 克隆 -git clone https://gitee.com/shuiyu1123/xiaoli-cli.git +# 启动 WebSocket 服务 +/remote start 9079 your_password -# 安装依赖 -pip install -r requirements.txt - -# 运行 -python -m xiaoli +# 代理模式 +/remote proxy relay.example.com:9079 server_pwd 12345 pc_pwd ``` -## 许可证 +## 🔌 插件开发 -MIT License +小狸支持三种插件协议，详见 [开发文档](开发文档/开发文档.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)