docs/CONTRIBUTING_CN.md
感谢您对 Astron Agent 项目的关注！我们欢迎社区贡献，感谢您帮助改进这个项目。
本项目遵循行为准则。参与项目时，请遵守此准则。如遇到不当行为，请向项目维护者举报。
请阅读我们的行为准则，了解我们为所有贡献者提供欢迎和包容环境的承诺。
在开始贡献之前，请确保已安装以下工具：
git clone https://github.com/your-username/astron-agent.git
cd astron-agent
git remote add upstream https://github.com/iflytek/astron-agent.git
运行自动化设置脚本来安装所有必需工具并配置环境：
make dev-setup
此命令将：
如果您偏好手动设置或需要安装特定组件：
# 安装开发工具
make install-tools
# 检查工具安装状态
make check-tools
# 安装 Git 钩子
make hooks-install
我们使用 pre-commit 进行自动化代码质量检查和密钥扫描。这是确保代码质量的推荐方式。
# 安装 pre-commit（如果尚未安装）
pip install pre-commit
# 安装 pre-commit 钩子
pre-commit install
pre-commit install --hook-type commit-msg
Pre-commit 将在每次提交时自动运行：
详细使用说明请参阅 Pre-commit 使用指南。
Astron Agent 是一个基于微服务的平台，具有以下结构：
astron-agent/
├── console/ # 控制台子系统
│ ├── backend/ # Java Spring Boot 服务
│ │ ├── auth/ # 认证服务
│ │ ├── commons/ # 共享工具
│ │ ├── hub/ # 主要业务逻辑
│ │ ├── toolkit/ # 工具包服务
│ │ └── config/ # 质量配置
│ └── frontend/ # React TypeScript SPA
├── core/ # 核心平台服务
│ ├── agent/ # 智能体执行引擎 (Python)
│ ├── common/ # 共享 Python 库
│ ├── knowledge/ # 知识库服务 (Python)
│ ├── memory/ # 内存管理
│ ├── plugin/ # 插件系统
│ ├── tenant/ # 多租户服务 (Go)
│ └── workflow/ # 工作流编排 (Python)
├── docs/ # 文档
├── makefiles/ # 构建系统组件
└── .github/ # GitHub 配置
└── quality-requirements/ # 代码质量标准
遵循我们的分支命名约定：
| 分支类型 | 格式 | 示例 | 用途 |
|---|---|---|---|
| 功能分支 | feature/功能名 | feature/user-auth | 新功能开发 |
| 修复分支 | bugfix/问题名 | bugfix/login-error | Bug 修复 |
| 热修复分支 | hotfix/补丁名 | hotfix/security-patch | 紧急修复 |
| 文档分支 | doc/文档名 | doc/api-guide | 文档更新 |
使用 Makefile 命令创建一致的分支：
# 创建功能分支
make new-feature name=user-authentication
# 创建修复分支
make new-bugfix name=login-timeout
# 创建热修复分支
make new-hotfix name=security-vulnerability
# 格式化所有代码
make format
# 使用 pre-commit 运行代码质量检查（推荐）
pre-commit run --all-files
# 运行测试
make test
# 构建所有项目
make build
Astron Agent 支持多种编程语言，具有统一的质量标准：
| 语言 | 格式化 | 质量工具 | 标准 |
|---|---|---|---|
| Go | gofmt + goimports + gofumpt | golangci-lint + staticcheck | Go 标准格式，复杂度 ≤10 |
| Java | Spotless (Google Java Format) | Checkstyle + PMD + SpotBugs | Google Java 风格，复杂度 ≤10 |
| Python | black + isort | flake8 + mypy + pylint | PEP 8，复杂度 ≤10 |
| TypeScript | prettier | eslint + tsc | ESLint 规则，严格类型检查 |
所有代码必须通过以下检查：
我们使用 pre-commit 作为统一的代码质量检查工具。它会在提交时自动运行检查暂存的文件，你也可以手动运行：
# 仅检查暂存的文件（git commit 时自动运行）
pre-commit run
# 检查仓库中的所有文件
pre-commit run --all-files
# 运行特定的钩子
pre-commit run black --all-files
pre-commit run eslint-check --all-files
pre-commit run golangci-lint --all-files
详细信息请参阅 Pre-commit 使用指南。
# 运行所有测试
make test
# 运行特定语言测试
make test-go
make test-java
make test-python
make test-typescript
# 运行覆盖率测试
make test-coverage
遵循 Conventional Commits 规范：
<type>(<scope>): <description>
[optional body]
[optional footer(s)]
类型：
feat：新功能fix：Bug 修复docs：文档更新style：代码格式化refactor：代码重构test：测试相关变更chore：构建工具、依赖更新示例：
feat(auth): 添加 OAuth2 认证支持
fix(api): 修复用户信息查询接口
docs(guide): 完善快速开始指南
提交前，请确保：
pre-commit install && pre-commit install --hook-type commit-msg）pre-commit run --all-files）make test）提示：如果已安装 pre-commit 钩子，代码质量和提交消息格式将在每次提交时自动检查。
报告 Bug 时，请包含：
功能请求时，请包含：
## 描述
变更的简要描述
## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 破坏性变更
- [ ] 文档更新
## 测试
- [ ] 添加/更新单元测试
- [ ] 添加/更新集成测试
- [ ] 完成手动测试
## 检查清单
- [ ] 代码遵循项目风格指南
- [ ] 完成自我审查
- [ ] 更新文档
- [ ] 无破坏性变更（或已记录）
我们遵循语义化版本控制：
贡献者将在以下方面得到认可：
如果您对贡献有疑问，请：
docs/ 目录中的文档感谢您为 Astron Agent 做出贡献！🚀