贡献指南

感谢您对 AIS 项目的关注和贡献！本文档将指导您如何参与项目开发，确保代码质量和项目的持续发展。

🤝 参与方式

贡献类型

🐛 Bug 修复: 修复已知问题
✨ 新功能: 添加新的功能特性
📝 文档改进: 改进或翻译文档
🧪 测试增强: 增加测试覆盖率
🎨 UI/UX 改进: 改善用户体验
🔧 性能优化: 优化代码性能

贡献流程

Fork 项目 - 创建您的项目副本
创建分支 - 基于 main 分支创建功能分支
开发实现 - 实现您的功能或修复
测试验证 - 确保代码通过所有测试
提交 PR - 提交拉取请求等待审查

🚀 开发环境设置

环境要求

Python 3.8+
Git
支持的操作系统：Linux、macOS

快速设置

bash

# 1. Fork 并克隆项目
git clone https://github.com/YOUR_USERNAME/ais.git
cd ais

# 2. 创建虚拟环境
python -m venv .venv
source .venv/bin/activate

# 3. 安装开发依赖
source .venv/bin/activate && python3 -m pip install -e .

# 4. 验证安装
python -m pytest tests/ -v
ais --version

开发工具配置

bash

# 安装代码质量工具
pip install black flake8 autopep8 mypy

# 运行代码质量检查
source .venv/bin/activate && black src/ tests/ && autopep8 --in-place --aggressive --aggressive --max-line-length=100 src/ tests/ -r && flake8 src/ tests/ --max-line-length=100

# 运行测试
python -m pytest tests/ -v

📝 代码规范

代码风格

PEP 8: 遵循 Python 官方代码风格
行长度: 最大 79 字符
命名规范:
- 类名：CamelCase
- 函数名：snake_case
- 常量：UPPER_CASE
- 私有成员：_leading_underscore

代码格式化

bash

# 自动格式化代码（建议使用项目配置的命令）
source .venv/bin/activate && black src/ tests/ && autopep8 --in-place --aggressive --aggressive --max-line-length=100 src/ tests/ -r && flake8 src/ tests/ --max-line-length=100

# 单独运行各个工具
black src/ tests/
autopep8 --in-place --aggressive --aggressive --max-line-length=100 src/ tests/ -r
flake8 src/ tests/ --max-line-length=100

导入规范

python

# 标准库导入
import os
import sys
from pathlib import Path

# 第三方库导入
import click
from rich.console import Console

# 本地导入（基于实际项目结构）
from ..core.config import get_config
from ..core.ai import ask_ai
from ..ui.panels import panels

🧪 测试要求

测试策略

单元测试: 测试单个函数和类
集成测试: 测试组件交互
端到端测试: 测试完整用户场景
覆盖率目标: 80%+

测试编写

python

# 测试文件命名: test_*.py
# 测试函数命名: test_*

import pytest
from unittest.mock import Mock, patch
from ais.core.ai import ask_ai
from ais.core.config import get_config

class TestAIModule:
    def test_ask_ai_basic(self):
        """测试基本问答功能"""
        config = get_config()
        result = ask_ai("test question", config)
        assert result is not None
        
    @patch('ais.core.ai.httpx')
    def test_ask_ai_with_mock(self, mock_httpx):
        """测试带模拟的问答功能"""
        mock_response = Mock()
        mock_response.json.return_value = {
            "choices": [{"message": {"content": "test response"}}]
        }
        mock_httpx.post.return_value = mock_response
        
        config = get_config()
        result = ask_ai("test question", config)
        assert "test response" in result

运行测试

bash

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

# 运行特定测试文件
python -m pytest tests/test_ai.py -v

# 运行特定测试
python -m pytest tests/test_ai.py::TestAIModule::test_ask_ai_basic -v

# 运行覆盖率测试
python -m pytest tests/ --cov=src/ais --cov-report=html

📋 提交规范

提交信息格式

<type>(<scope>): <subject>

<body>

<footer>

提交类型

feat: 新功能
fix: Bug 修复
docs: 文档更新
style: 代码风格修改
refactor: 代码重构
test: 测试相关
chore: 构建/工具相关

提交示例

bash

# 好的提交信息
feat(ask): 添加流式输出支持

添加了 AI 问答的流式输出功能，提升用户体验：
- 实时显示 AI 处理进度
- 支持三种显示模式
- 可通过配置开启/关闭

Closes #123

# 避免的提交信息
fix bug
update code

🔄 拉取请求流程

PR 准备清单

[ ] 代码通过所有测试
[ ] 代码符合风格规范
[ ] 添加了必要的测试
[ ] 更新了相关文档
[ ] 提交信息符合规范

PR 模板

markdown

## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 文档更新
- [ ] 重构
- [ ] 性能优化

## 变更描述
简要描述此次变更的内容和目的。

## 测试
- [ ] 添加了新的测试
- [ ] 所有测试通过
- [ ] 手动测试通过

## 相关问题
Closes #123

审查流程

自动检查: CI/CD 自动运行测试
代码审查: 维护者审查代码质量
功能验证: 验证功能是否正常
文档检查: 确保文档完整性
合并: 通过审查后合并到主分支

📖 文档贡献

文档类型

用户文档: 使用指南和教程
API 文档: 代码接口文档
开发文档: 开发者指南

文档规范

语言: 中文为主，英文为辅
格式: Markdown 格式
结构: 清晰的层次结构
示例: 包含实际可运行的示例

文档构建

bash

# 进入文档目录
cd docs

# 安装依赖
npm install

# 本地预览
npm run dev

# 构建静态文件
npm run build

🐛 问题报告

问题类型

Bug 报告: 软件错误或异常
功能请求: 新功能建议
性能问题: 性能相关问题
文档问题: 文档错误或缺失

问题模板

markdown

## 问题描述
清晰描述遇到的问题。

## 重现步骤
1. 运行命令 `ais ask "test"`
2. 观察输出结果
3. 发现错误信息

## 预期行为
描述预期的正常行为。

## 实际行为
描述实际发生的行为。

## 环境信息
- OS: Ubuntu 22.04
- Python: 3.9.7
- AIS: 0.3.2

## 日志信息
粘贴相关的错误日志。

🎯 开发指南

新功能开发

bash

# 1. 创建功能分支
git checkout -b feature/new-feature

# 2. 实现功能
# 编写代码...

# 3. 添加测试
# 编写测试...

# 4. 运行测试
pytest tests/

# 5. 提交变更
git add .
git commit -m "feat: 添加新功能"

# 6. 推送分支
git push origin feature/new-feature

Bug 修复

bash

# 1. 创建修复分支
git checkout -b fix/bug-description

# 2. 重现问题
# 编写测试用例重现 bug

# 3. 修复问题
# 修改代码...

# 4. 验证修复
pytest tests/

# 5. 提交修复
git commit -m "fix: 修复特定问题"

📊 代码质量

质量指标

测试覆盖率: 目标 80%+
代码复杂度: 控制在合理范围
静态检查: 通过 flake8 和 mypy
安全检查: 通过 bandit 扫描

质量检查工具

bash

# 代码覆盖率
pytest tests/ --cov=src/ais --cov-report=term-missing

# 代码复杂度
radon cc src/ --min C

# 安全检查
bandit -r src/

# 依赖检查
safety check

🚀 发布流程

版本号规范

遵循 Keep a Changelog 最佳实践：

主版本: 重大变更，不兼容更新
次版本: 新功能，向后兼容
修订版本: Bug 修复，向后兼容

发布步骤

更新 CHANGELOG.md（必须）
运行完整测试和代码质量检查
提交详细的 git commit
创建发布标签
推送到远程仓库
触发 Package Release 工作流

注意事项

每次改动后必须提交详细的 git commit
git commit 中不要包含 🤖 Generated with Claude Code 等标识
发布前后要同步远程仓库以避免冲突

🎉 贡献者认可

贡献者列表

所有贡献者都会在 README.md 中得到认可。

贡献统计

代码贡献: 按提交数量和代码行数
文档贡献: 按文档页数和质量
问题解决: 按解决问题数量和复杂度

联系方式

GitHub Issues: 报告问题和建议
讨论区: 技术讨论和问答
邮件: 项目相关询问

提示

新贡献者建议从标记为 "good first issue" 的问题开始，逐步熟悉项目结构。

代码审查

所有代码都需要经过审查，这是确保代码质量的重要步骤。

注意

请确保您的代码符合项目的许可证要求，不要包含版权争议的代码。

贡献指南 ​

🤝 参与方式 ​

贡献类型 ​

贡献流程 ​

🚀 开发环境设置 ​

环境要求 ​

快速设置 ​

开发工具配置 ​

📝 代码规范 ​

代码风格 ​

代码格式化 ​

导入规范 ​

🧪 测试要求 ​

测试策略 ​

测试编写 ​

运行测试 ​

📋 提交规范 ​

提交信息格式 ​

提交类型 ​

提交示例 ​

🔄 拉取请求流程 ​

PR 准备清单 ​

PR 模板 ​

审查流程 ​

📖 文档贡献 ​

文档类型 ​

文档规范 ​

文档构建 ​

🐛 问题报告 ​

问题类型 ​

问题模板 ​

🎯 开发指南 ​

新功能开发 ​

Bug 修复 ​

📊 代码质量 ​

质量指标 ​

质量检查工具 ​

🚀 发布流程 ​

版本号规范 ​

发布步骤 ​

注意事项 ​

🎉 贡献者认可 ​

贡献者列表 ​

贡献统计 ​

联系方式 ​

贡献指南

🤝 参与方式

贡献类型

贡献流程

🚀 开发环境设置

环境要求

快速设置

开发工具配置

📝 代码规范

代码风格

代码格式化

导入规范

🧪 测试要求

测试策略

测试编写

运行测试

📋 提交规范

提交信息格式

提交类型

提交示例

🔄 拉取请求流程

PR 准备清单

PR 模板

审查流程

📖 文档贡献

文档类型

文档规范

文档构建

🐛 问题报告

问题类型

问题模板

🎯 开发指南

新功能开发

Bug 修复

📊 代码质量

质量指标

质量检查工具

🚀 发布流程

版本号规范

发布步骤

注意事项

🎉 贡献者认可

贡献者列表

贡献统计

联系方式