shuiyu1123
4b0c739c07
- README.md: 重写中文文档，补充特性说明、项目结构、使用指南 - README.en.md: 重写英文文档，与中文版对齐 - CHANGELOG.md: 补充 v5.0.0 更新日志 - CONTRIBUTING.md: 新增贡献指南 - HELP.md: 更新使用指南，适配 v5.0.0
149 lines
3.0 KiB
Markdown
149 lines
3.0 KiB
Markdown
# 贡献指南
|
|
|
|
感谢你对小狸 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/) 格式：
|
|
|
|
```
|
|
<type>(<scope>): <description>
|
|
|
|
[可选 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
|