byy/qiming

Files

2026-06-01 13:54:52 +08:00

9.7 KiB

Raw Blame History

贡献指南

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

贡献流程

本项目遵循标准的开源贡献流程，旨在确保代码质量和项目稳定性。贡献者应遵循以下步骤进行贡献：

Fork 仓库：首先在 GitHub 上 Fork 本项目仓库到自己的账户。
创建特性分支：基于主分支创建新的特性分支，命名规范为 feature/功能描述，例如 feature/add-new-api-endpoint。
开发与提交：在特性分支上进行开发，完成开发后提交更改，提交信息应清晰描述更改内容。
推送分支：将本地更改推送到自己 Fork 的仓库中。
创建 Pull Request：在 GitHub 上创建 Pull Request，目标为原仓库的主分支。PR 描述应详细说明更改的目的、实现方式和测试情况。

项目采用工作区（workspace）结构，包含多个独立的 crate，如 rcoder、agent_runner、pingora-proxy 等。每个 crate 都有其独立的 Cargo.toml 文件，但共享根目录的 Cargo.toml 中定义的依赖和配置。这种模块化设计使得各组件可以独立开发和测试，同时保持整体项目的一致性。

Section sources

代码规范

本项目遵循 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

测试要求

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

单元测试

覆盖率：所有新功能和关键路径必须有单元测试覆盖。
测试结构：测试代码应放在 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

文档更新

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

文档位置

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

文档内容

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

文档示例

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

Section sources

配置选项

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

配置文件

配置文件 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

组件关系

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

核心组件

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

常见问题与解决方案

端口被占用

问题：启动服务时提示端口被占用。 解决方案：使用 --port 参数指定其他端口，例如 cargo run --bin rcoder -- --port 8087。

AI 代理连接失败

问题：AI 代理无法连接。 解决方案：检查 API 密钥和网络连接，确保环境变量 ANTHROPIC_API_KEY 已正确设置。

配置文件错误

问题：配置文件格式错误或字段名称不正确。 解决方案：检查 YAML 格式，确保字段名称和值正确。参考 config.yml 示例文件。

Docker 容器启动失败

问题：Docker 容器无法启动。 解决方案：检查 Docker socket 路径是否正确，确保容器有权限访问 Docker API。查看日志获取详细错误信息。

Section sources

9.7 KiB Raw Blame History Unescape Escape

贡献指南

目录

贡献流程

代码规范

通用规范

安全禁令

前端开发规范

测试要求

单元测试

集成测试

测试示例

文档更新

文档位置

文档内容

文档示例

配置选项

配置文件

命令行参数

环境变量

组件关系

核心组件

组件交互

依赖关系

常见问题与解决方案

端口被占用

AI 代理连接失败

配置文件错误

Docker 容器启动失败

9.7 KiB

Raw Blame History