221 lines
9.7 KiB
Markdown
221 lines
9.7 KiB
Markdown
# 贡献指南
|
||
|
||
<cite>
|
||
**本文档引用的文件**
|
||
- [README.md](file://README.md)
|
||
- [Cargo.toml](file://Cargo.toml)
|
||
- [Makefile](file://Makefile)
|
||
- [config.yml](file://config.yml)
|
||
- [install.md](file://install.md)
|
||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs)
|
||
- [crates/agent_runner/src/main.rs](file://crates/agent_runner/src/main.rs)
|
||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml)
|
||
- [crates/agent_runner/Cargo.toml](file://crates/agent_runner/Cargo.toml)
|
||
- [crates/pingora-proxy/src/config.rs](file://crates/pingora-proxy/src/config.rs)
|
||
- [crates/shared_types/src/service_config.rs](file://crates/shared_types/src/service_config.rs)
|
||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs)
|
||
- [crates/rcoder/tests/container_path_test.rs](file://crates/rcoder/tests/container_path_test.rs)
|
||
- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md)
|
||
- [.dockerignore](file://.dockerignore)
|
||
</cite>
|
||
|
||
## 目录
|
||
1. [贡献流程](#贡献流程)
|
||
2. [代码规范](#代码规范)
|
||
3. [测试要求](#测试要求)
|
||
4. [文档更新](#文档更新)
|
||
5. [配置选项](#配置选项)
|
||
6. [组件关系](#组件关系)
|
||
7. [常见问题与解决方案](#常见问题与解决方案)
|
||
|
||
## 贡献流程
|
||
|
||
本项目遵循标准的开源贡献流程，旨在确保代码质量和项目稳定性。贡献者应遵循以下步骤进行贡献：
|
||
|
||
1. **Fork 仓库**：首先在 GitHub 上 Fork 本项目仓库到自己的账户。
|
||
2. **创建特性分支**：基于主分支创建新的特性分支，命名规范为 `feature/功能描述`，例如 `feature/add-new-api-endpoint`。
|
||
3. **开发与提交**：在特性分支上进行开发，完成开发后提交更改，提交信息应清晰描述更改内容。
|
||
4. **推送分支**：将本地更改推送到自己 Fork 的仓库中。
|
||
5. **创建 Pull Request**：在 GitHub 上创建 Pull Request，目标为原仓库的主分支。PR 描述应详细说明更改的目的、实现方式和测试情况。
|
||
|
||
项目采用工作区（workspace）结构，包含多个独立的 crate，如 `rcoder`、`agent_runner`、`pingora-proxy` 等。每个 crate 都有其独立的 `Cargo.toml` 文件，但共享根目录的 `Cargo.toml` 中定义的依赖和配置。这种模块化设计使得各组件可以独立开发和测试，同时保持整体项目的一致性。
|
||
|
||
**Section sources**
|
||
- [README.md](file://README.md#L599-L610)
|
||
- [Cargo.toml](file://Cargo.toml#L1-L205)
|
||
|
||
## 代码规范
|
||
|
||
本项目遵循 Rust 社区的最佳实践和编码规范，确保代码的可读性、一致性和安全性。
|
||
|
||
### 通用规范
|
||
- **命名约定**：使用 `snake_case` 命名变量和函数，`PascalCase` 命名类型和模块。
|
||
- **代码格式化**：所有代码必须使用 `cargo fmt` 进行格式化，确保代码风格统一。
|
||
- **错误处理**：优先使用 `anyhow` 和 `thiserror` 库进行错误处理，提供清晰的错误信息。
|
||
- **异步编程**：使用 `tokio` 作为异步运行时，遵循异步编程的最佳实践，避免阻塞操作。
|
||
|
||
### 安全禁令
|
||
为确保系统安全，以下操作是严格禁止的：
|
||
- **绝对禁止**探测、扫描或访问内网IP地址（如 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16、127.0.0.0/8）。
|
||
- **绝对禁止**尝试访问本地服务（localhost、127.0.0.1、0.0.0.0）。
|
||
- **绝对禁止**端口扫描、网络探测、内网服务发现等行为。
|
||
- **绝对禁止**在代码中硬编码内网IP地址或私有网络地址。
|
||
|
||
### 前端开发规范
|
||
当涉及前端开发时，需遵循以下特定规范：
|
||
- **路由模式**：必须使用 hash 模式。例如，React Router 使用 `HashRouter`，Vue Router 配置 `mode: 'hash'`。
|
||
- **代码注入保护**：绝对禁止删除或修改被 `DEV-INJECT-START` 和 `DEV-INJECT-END` 标记包围的代码块。这些代码块由开发工具自动注入，必须完整保留。
|
||
|
||
**Section sources**
|
||
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L90-L96)
|
||
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L72-L73)
|
||
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L80-L81)
|
||
- [crates/agent_runner/src/utils/system_prompt.rs](file://crates/agent_runner/src/utils/system_prompt.rs#L87)
|
||
|
||
## 测试要求
|
||
|
||
为确保代码质量和功能正确性，所有贡献必须包含相应的测试。
|
||
|
||
### 单元测试
|
||
- **覆盖率**：所有新功能和关键路径必须有单元测试覆盖。
|
||
- **测试结构**：测试代码应放在 `tests` 目录下，与源代码对应。
|
||
- **断言库**：使用 `assert_eq!`、`assert_ne!` 等宏进行断言，确保测试的准确性。
|
||
|
||
### 集成测试
|
||
- **环境准备**：集成测试需要启动完整的应用环境，包括数据库、网络服务等。
|
||
- **测试用例**：覆盖主要的业务流程和边界情况，确保系统在各种场景下的稳定性。
|
||
- **运行命令**：使用 `cargo test --test integration` 运行集成测试。
|
||
|
||
### 测试示例
|
||
```rust
|
||
#[cfg(test)]
|
||
mod tests {
|
||
use super::*;
|
||
#[test]
|
||
fn test_default_container_path_template() {
|
||
let config = default_rcoder_service_config();
|
||
assert_eq!(
|
||
config.container_path_template,
|
||
"/app/project_workspace/{project_id}"
|
||
);
|
||
}
|
||
}
|
||
```
|
||
|
||
**Section sources**
|
||
- [crates/rcoder/tests/container_path_test.rs](file://crates/rcoder/tests/container_path_test.rs#L1-L94)
|
||
- [README.md](file://README.md#L452-L463)
|
||
|
||
## 文档更新
|
||
|
||
贡献者在添加新功能或修改现有功能时，必须同步更新相关文档。
|
||
|
||
### 文档位置
|
||
- **README.md**：项目概述、快速开始、配置说明等。
|
||
- **specs/**：设计文档，如 `agent-abstraction-layer-design.md`。
|
||
- **docs/**：详细的用户和开发者文档。
|
||
|
||
### 文档内容
|
||
- **功能描述**：清晰描述新功能的目的和使用场景。
|
||
- **API 文档**：更新 API 端点、请求参数、响应格式等。
|
||
- **配置说明**：更新配置文件的字段说明和示例。
|
||
|
||
### 文档示例
|
||
```yaml
|
||
# RCoder 配置文件
|
||
default_agent: "Claude"
|
||
projects_dir: "./project_workspace"
|
||
port: 8087
|
||
```
|
||
|
||
**Section sources**
|
||
- [README.md](file://README.md#L384-L438)
|
||
- [config.yml](file://config.yml#L1-L161)
|
||
- [specs/agent-abstraction-layer-design.md](file://specs/agent-abstraction-layer-design.md#L308-L367)
|
||
|
||
## 配置选项
|
||
|
||
本项目支持多种配置方式，优先级从高到低为：命令行参数 > 环境变量 > 配置文件 > 默认配置。
|
||
|
||
### 配置文件
|
||
配置文件 `config.yml` 支持以下主要选项：
|
||
- **default_agent**：默认使用的 AI 代理类型，可选值为 "Claude" 或 "Codex"。
|
||
- **projects_dir**：项目工作目录。
|
||
- **port**：主服务端口。
|
||
- **proxy_config**：Pingora 反向代理配置，包括监听端口、默认后端端口等。
|
||
|
||
### 命令行参数
|
||
| 参数 | 短参数 | 说明 | 示例 |
|
||
|------|--------|------|------|
|
||
| `--port` | `-p` | 设置主服务端口 | `--port 8087` |
|
||
| `--projects-dir` | `-d` | 设置项目工作目录 | `--projects-dir ./projects` |
|
||
| `--enable-proxy` | 无 | 启用 Pingora 反向代理 | `--enable-proxy` |
|
||
| `--proxy-port` | 无 | 设置 Pingora 监听端口 | `--proxy-port 8080` |
|
||
| `--default-backend-port` | 无 | 未指定端口时的默认后端端口 | `--default-backend-port 3000` |
|
||
|
||
### 环境变量
|
||
- `RCODER_PORT`：服务器端口。
|
||
- `DATABASE_URL`：数据库连接字符串。
|
||
- `CLAUDE_CODE_PATH`：Claude Code CLI 路径。
|
||
- `RUST_LOG`：日志级别。
|
||
|
||
**Section sources**
|
||
- [README.md](file://README.md#L88-L104)
|
||
- [config.yml](file://config.yml#L1-L161)
|
||
- [Cargo.toml](file://Cargo.toml#L414-L418)
|
||
|
||
## 组件关系
|
||
|
||
本项目由多个核心组件构成，各组件之间通过清晰的接口进行交互。
|
||
|
||
### 核心组件
|
||
- **rcoder**：主应用，负责业务 API、会话管理和 SSE 进度流。
|
||
- **agent_runner**：代理运行器，负责管理 AI 代理的生命周期。
|
||
- **pingora-proxy**：高性能反向代理，负责端口路由。
|
||
- **docker_manager**：Docker 容器管理器，负责容器的创建、启动和销毁。
|
||
|
||
### 组件交互
|
||
```mermaid
|
||
graph TB
|
||
A[Client] --> B[Axum HTTP Server]
|
||
A --> C[Pingora Proxy]
|
||
B --> D[API Routes]
|
||
B --> E[Agent Worker (LocalSet)]
|
||
C --> F[Backends: 127.0.0.1:{port}]
|
||
```
|
||
|
||
**Diagram sources**
|
||
- [README.md](file://README.md#L18-L25)
|
||
|
||
### 依赖关系
|
||
- **rcoder** 依赖于 `agent_runner` 和 `pingora-proxy`。
|
||
- **agent_runner** 依赖于 `docker_manager` 进行容器管理。
|
||
- **pingora-proxy** 独立运行，通过路径前缀 `/proxy/{port}/{path}` 转发请求。
|
||
|
||
**Section sources**
|
||
- [README.md](file://README.md#L16-L30)
|
||
- [crates/rcoder/Cargo.toml](file://crates/rcoder/Cargo.toml#L16-L77)
|
||
- [crates/agent_runner/Cargo.toml](file://crates/agent_runner/Cargo.toml#L16-L79)
|
||
|
||
## 常见问题与解决方案
|
||
|
||
### 端口被占用
|
||
**问题**：启动服务时提示端口被占用。
|
||
**解决方案**：使用 `--port` 参数指定其他端口，例如 `cargo run --bin rcoder -- --port 8087`。
|
||
|
||
### AI 代理连接失败
|
||
**问题**：AI 代理无法连接。
|
||
**解决方案**：检查 API 密钥和网络连接，确保环境变量 `ANTHROPIC_API_KEY` 已正确设置。
|
||
|
||
### 配置文件错误
|
||
**问题**：配置文件格式错误或字段名称不正确。
|
||
**解决方案**：检查 YAML 格式，确保字段名称和值正确。参考 `config.yml` 示例文件。
|
||
|
||
### Docker 容器启动失败
|
||
**问题**：Docker 容器无法启动。
|
||
**解决方案**：检查 Docker socket 路径是否正确，确保容器有权限访问 Docker API。查看日志获取详细错误信息。
|
||
|
||
**Section sources**
|
||
- [README.md](file://README.md#L620-L626)
|
||
- [crates/rcoder/src/main.rs](file://crates/rcoder/src/main.rs#L322-L351)
|
||
- [crates/docker_manager/src/manager.rs](file://crates/docker_manager/src/manager.rs#L51-L61) |