XAI-SDK

Appearance

贡献指南 ​

感谢您对XAI-SDK项目的关注！我们欢迎各种形式的贡献，包括但不限于代码、文档、测试、反馈和建议。

🤝 如何贡献 ​

报告问题 ​

如果您发现了bug或有功能建议：

  1. 搜索现有问题：首先检查GitHub Issues中是否已有相关问题
  2. 创建新问题：如果没有找到相关问题，请创建新的Issue
  3. 提供详细信息：包括复现步骤、预期行为、实际行为、环境信息等

问题模板 ​

Bug报告：

markdown
## Bug描述

简要描述遇到的问题

## 复现步骤

1. 执行...
2. 点击...
3. 看到错误...

## 预期行为

描述您期望发生的情况

## 实际行为

描述实际发生的情况

## 环境信息

- OS: [例如 macOS 12.0]
- Node.js版本: [例如 18.0.0]
- XAI-SDK版本: [例如 1.0.0]
- 浏览器: [如果适用]

## 附加信息

添加任何其他有助于解决问题的信息

功能请求：

markdown
## 功能描述

简要描述您希望添加的功能

## 使用场景

描述这个功能的使用场景和价值

## 建议实现

如果有具体的实现建议，请描述

## 替代方案

描述您考虑过的其他解决方案

贡献代码 ​

开发流程 ​

  1. Fork项目：在GitHub上fork XAI-SDK仓库

  2. 克隆仓库：

    bash
    git clone https://github.com/your-username/xai-sdk.git
cd xai-sdk

  3. 创建分支：

    bash
    git checkout -b feature/your-feature-name

  4. 安装依赖：

    bash
    pnpm install

  5. 开发和测试：

    bash
    # 运行测试
pnpm test

# 运行类型检查
pnpm type-check

# 运行代码检查
pnpm lint

  6. 提交更改：

    bash
    git add .
git commit -m "feat: add your feature description"

  7. 推送分支：

    bash
    git push origin feature/your-feature-name

  8. 创建Pull Request：在GitHub上创建PR

代码规范 ​

  • TypeScript：所有代码必须使用TypeScript编写
  • ESLint：遵循项目的ESLint配置
  • Prettier：使用Prettier进行代码格式化
  • 测试：新功能必须包含相应的测试用例
  • 文档：公共API必须包含JSDoc注释

提交信息规范 ​

我们使用Conventional Commits规范：

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

类型（type）：

  • feat: 新功能
  • fix: 修复bug
  • docs: 文档更新
  • style: 代码格式化（不影响功能）
  • refactor: 代码重构
  • test: 添加或修改测试
  • chore: 构建过程或辅助工具的变动
  • perf: 性能优化
  • ci: CI/CD相关更改

示例：

feat(adapter): add Google PaLM adapter support

fix(plugin): resolve memory leak in plugin manager

docs: update API documentation for chat method

test(core): add unit tests for batch processing

贡献文档 ​

文档改进同样重要：

  1. API文档：改进JSDoc注释
  2. 用户指南：添加使用示例和最佳实践
  3. 开发文档：改进开发环境设置和贡献指南
  4. 翻译：帮助翻译文档到其他语言

文档结构 ​

docs/
├── api/                 # API参考文档
├── guide/              # 用户指南
├── examples/           # 示例代码
└── contributing/       # 贡献相关文档

🧪 测试 ​

运行测试 ​

bash
# 运行所有测试
pnpm test

# 运行特定测试文件
pnpm test src/core/sdk.test.ts

# 运行测试并生成覆盖率报告
pnpm test:coverage

# 监听模式运行测试
pnpm test:watch

编写测试 ​

  • 单元测试：测试单个函数或类的功能
  • 集成测试：测试多个组件的协作
  • 端到端测试：测试完整的用户场景

测试示例 ​

typescript
import { describe, it, expect, beforeEach } from 'vitest';
import { XAI_SDK } from '../src/core/sdk';

describe('XAI_SDK', () => {
  let sdk: XAI_SDK;

  beforeEach(() => {
    sdk = new XAI_SDK({
      defaultAdapter: 'openai',
      adapters: {
        openai: {
          apiKey: 'test-key',
        },
      },
    });
  });

  it('should initialize successfully', async () => {
    await expect(sdk.initialize()).resolves.not.toThrow();
  });

  it('should handle chat requests', async () => {
    const response = await sdk.chat([{ role: 'user', content: 'Hello' }]);

    expect(response).toBeDefined();
    expect(response.content).toBeTruthy();
  });
});

🔍 代码审查 ​

Pull Request检查清单 ​

在提交PR之前，请确保：

  • [ ] 代码遵循项目的编码规范
  • [ ] 所有测试通过
  • [ ] 添加了必要的测试用例
  • [ ] 更新了相关文档
  • [ ] 提交信息符合规范
  • [ ] 没有引入破坏性变更（如有，请在PR中说明）

审查过程 ​

  1. 自动检查：CI/CD会自动运行测试和代码检查
  2. 人工审查：维护者会审查代码质量、设计和实现
  3. 反馈处理：根据审查意见修改代码
  4. 合并：审查通过后合并到主分支

🏗️ 项目结构 ​

xai-sdk/
├── src/                 # 源代码
│   ├── core/           # 核心功能
│   ├── adapters/       # 适配器实现
│   ├── plugins/        # 插件系统
│   ├── tools/          # 工具系统
│   └── utils/          # 工具函数
├── tests/              # 测试文件
├── docs/               # 文档
├── examples/           # 示例代码
├── scripts/            # 构建脚本
└── packages/           # 子包（如果有）

🚀 发布流程 ​

版本管理 ​

我们使用Semantic Versioning：

  • MAJOR：不兼容的API更改
  • MINOR：向后兼容的功能添加
  • PATCH：向后兼容的bug修复

发布步骤 ​

  1. 更新版本号：

    bash
    pnpm version patch|minor|major

  2. 更新CHANGELOG：记录本次发布的变更

  3. 创建发布标签：

    bash
    git tag -a v1.0.0 -m "Release v1.0.0"
git push origin v1.0.0

  4. 发布到npm：

    bash
    pnpm publish

🎯 贡献指导原则 ​

设计原则 ​

  1. 简单性：API应该简单易用
  2. 一致性：保持API和代码风格的一致性
  3. 可扩展性：设计应该支持未来的扩展
  4. 性能：考虑性能影响，避免不必要的开销
  5. 安全性：确保代码安全，避免安全漏洞

最佳实践 ​

  1. 小步提交：每次提交应该是一个逻辑完整的更改
  2. 清晰命名：使用有意义的变量和函数名
  3. 适当注释：为复杂逻辑添加注释
  4. 错误处理：妥善处理错误情况
  5. 性能考虑：避免不必要的计算和内存使用

📞 获取帮助 ​

如果您在贡献过程中遇到问题：

  1. 查看文档：首先查看相关文档
  2. 搜索Issues：查看是否有类似问题
  3. 提问：在GitHub Issues中提问
  4. 社区讨论：加入我们的Discord社区

🏆 贡献者认可 ​

我们重视每一个贡献，会在以下地方认可贡献者：

  1. CONTRIBUTORS.md：列出所有贡献者
  2. 发布说明：在发布说明中感谢贡献者
  3. 社交媒体：在社交媒体上分享重要贡献
  4. 贡献者徽章：为活跃贡献者提供特殊徽章

📋 贡献者协议 ​

通过向本项目贡献代码，您同意：

  1. 您拥有所贡献代码的版权
  2. 您同意将代码以MIT许可证发布
  3. 您的贡献不侵犯任何第三方权利

再次感谢您的贡献！每一个贡献都让XAI-SDK变得更好。

Released under the MIT License.

Copyright © 2024 AI-SDK Team