Development Guidelines

为了确保项目的代码质量、可维护性和协作效率，所有贡献者都应遵守以下开发准则。

1. 代码提交前检查

在提交任何代码之前，必须使用 ruff 进行代码格式化和质量检查。这有助于统一代码风格，并及早发现潜在问题。

ruff check . --fix
ruff format .

2. 测试文件的存放

所有测试文件都应统一放置在项目根目录下的 test/ 目录中。请确保测试文件的命名清晰，并与被测试的模块相对应。

3. AI 辅助编程后的审查

我们鼓励使用 AI 工具（如 GitHub Copilot）来提高开发效率，但严禁直接提交由 AI 生成的未经审查的代码。您必须：

• 理解每一行代码：确保您完全理解 AI 生成的代码的功能和逻辑。
• 进行代码审查：像审查他人代码一样，仔细检查 AI 生成的代码是否存在逻辑错误、安全漏洞或不符合项目规范的地方。
• 承担最终责任：请记住，您是代码的最终负责人。

4. 清理无用的 Markdown 文件

由 AI 工具生成的、与项目无关的 Markdown 文件（例如 README.md 的变体、示例文件等）应当被删除。如果这些文件包含有价值的信息，请将其移动到 docs/ 目录下，并进行适当的整理。

5. 明确标注未完成的功能

如果您提交的代码包含了未完全实现的功能，必须在相关代码位置使用 TODO 注释进行明确标注。注释中应简要说明待办事项。

# TODO: 实现用户认证逻辑
def login(username, password):
    pass

6. 保持专业，避免个人纠纷

本项目是一个协作的开源社区。请将所有讨论和交流集中在技术和项目本身。严禁将个人恩怨或与项目无关的争论带入到 issue、pull request 或任何其他项目相关的沟通渠道中。

7. 分支管理策略

• develop 分支：所有新功能开发和代码修改都应提交到 develop 分支。请基于最新的 develop 分支创建您的特性分支。
• master 分支：master 分支是稳定版本分支，只接受来自 develop 分支的合并请求（Merge Request）。严禁直接向 master 分支推送代码。

8. 保持模块独立性

在添加新模块时，请遵循“高内聚，低耦合”的原则。

• 独立性：新模块应尽可能独立，减少对项目其他部分的直接依赖。
• 接口清晰：如果需要与核心代码交互，应通过定义清晰的 API 或事件来进行，而不是直接修改核心逻辑。
• 例外：对于项目基础核心功能的提交，可以不受此限制，但需要经过更严格的审查。