qiming/qiming-rcoder/.qoder/repowiki/zh/content/贡献指南.md

贡献指南

**本文档引用的文件** - [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)

目录

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
• Cargo.toml

代码规范

本项目遵循 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
• crates/agent_runner/src/utils/system_prompt.rs
• crates/agent_runner/src/utils/system_prompt.rs
• crates/agent_runner/src/utils/system_prompt.rs

测试要求

为确保代码质量和功能正确性，所有贡献必须包含相应的测试。

单元测试

• 覆盖率：所有新功能和关键路径必须有单元测试覆盖。
• 测试结构：测试代码应放在 tests 目录下，与源代码对应。
• 断言库：使用 assert_eq!、assert_ne! 等宏进行断言，确保测试的准确性。

集成测试

• 环境准备：集成测试需要启动完整的应用环境，包括数据库、网络服务等。
• 测试用例：覆盖主要的业务流程和边界情况，确保系统在各种场景下的稳定性。
• 运行命令：使用 cargo test --test integration 运行集成测试。

测试示例

#[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
• README.md

文档更新

贡献者在添加新功能或修改现有功能时，必须同步更新相关文档。

文档位置

• README.md：项目概述、快速开始、配置说明等。
• specs/：设计文档，如 agent-abstraction-layer-design.md。
• docs/：详细的用户和开发者文档。

文档内容

• 功能描述：清晰描述新功能的目的和使用场景。
• API 文档：更新 API 端点、请求参数、响应格式等。
• 配置说明：更新配置文件的字段说明和示例。

文档示例

# RCoder 配置文件
default_agent: "Claude"
projects_dir: "./project_workspace"
port: 8087

Section sources

• README.md
• config.yml
• specs/agent-abstraction-layer-design.md

配置选项

本项目支持多种配置方式，优先级从高到低为：命令行参数 > 环境变量 > 配置文件 > 默认配置。

配置文件

配置文件 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
• config.yml
• Cargo.toml

组件关系

本项目由多个核心组件构成，各组件之间通过清晰的接口进行交互。

核心组件

• rcoder：主应用，负责业务 API、会话管理和 SSE 进度流。
• agent_runner：代理运行器，负责管理 AI 代理的生命周期。
• pingora-proxy：高性能反向代理，负责端口路由。
• docker_manager：Docker 容器管理器，负责容器的创建、启动和销毁。

组件交互

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

依赖关系

• rcoder 依赖于 agent_runner 和 pingora-proxy。
• agent_runner 依赖于 docker_manager 进行容器管理。
• pingora-proxy 独立运行，通过路径前缀 /proxy/{port}/{path} 转发请求。

Section sources

• README.md
• crates/rcoder/Cargo.toml
• crates/agent_runner/Cargo.toml

常见问题与解决方案

端口被占用

问题：启动服务时提示端口被占用。 解决方案：使用 --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
• crates/rcoder/src/main.rs
• crates/docker_manager/src/manager.rs