# 贡献指南

<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)