Skip to content

contributing

Jump to bottom
Wiki Maintainer edited this page Aug 5, 2026 · 1 revision

贡献指南

开发流程

开发按里程碑（M0 → M9）顺序推进，每个里程碑串行执行以下 8 步：

1. 写开发文档（创建里程碑文档）
2. 和设计核对
3. 开发（前后端一起）
4. simplify
5. code review
6. 测试（100% 覆盖率）
7. 和设计再确认
8. 提交 + 完成里程碑

1. 写开发文档

每个里程碑开始前，在 docs/milestones/ 创建里程碑文档。

里程碑文档必须包含：

# M{N}: {标题}

## Context
前序阶段完成了什么，本阶段在整体产品中的位置。

## 产品边界
本阶段做什么、不做什么。

## 子任务清单
| 子任务 | 内容 | 前端/后端 | 状态 |
|--------|------|-----------|------|
| N.1 | ... | 后端 | ⬜ |
| N.2 | ... | 前端 | ⬜ |

## 子任务详细设计
...

## 设计核对点

2. 和设计核对

对照 docs/PRODUCT.md 检查：

  • 是否符合产品定位（单用户、自托管）
  • 架构是否一致（单二进制 + supervisor + worker）
  • 文件传输是否不经过浏览器
  • 是否引入了不该有的概念（RBAC、多用户）

3. 开发原则

  • 文档为先，不临时改方向
  • 不做文档外的大功能
  • 每个 commit 只包含一个完整子功能点
  • 不做一次性大提交

4. Simplify

开发完成后精简代码：

  • 是否有重复代码
  • 是否有过度设计
  • 是否提前实现了下一阶段能力
  • 是否符合 Rust workspace / Vue 功能域结构
  • 是否可以把大文件拆小

5. Code Review

审查维度：

  • 正确性、安全性、架构一致性
  • 测试覆盖、错误处理
  • 配置和密钥处理
  • 审计日志
  • 与里程碑文档是否一致

6. 测试

Rust 测试

cargo fmt --check
cargo clippy --workspace --all-targets
cargo test --workspace

前端测试

bun run type-check
bun run lint
bun run build

测试原则

  • 所有公开函数和关键逻辑路径必须有测试
  • Rust 测试代码依赖使用 workspace = true
  • 单元测试放在模块内 #[cfg(test)] mod tests
  • 前端测试只验证当前功能，不依赖外部服务

7. 和设计再确认

确保：

  • 实现和里程碑文档一致
  • 产品语义没变
  • 用户可见行为没变

8. 提交

提交约定

按功能拆分提交，每个 commit 只包含一个子功能点：

# ✅ 好的
git commit -m 'feat: add agent heartbeat model'
git commit -m 'feat: add agent list api'

# ❌ 不好
git commit -m 'feat: add agent management'

提交前检查

  • Rust 代码必须 cargo fmt
  • 前端 bun run type-check 通过
  • 前端 bun run lint 无 error

代码规范

Rust

  • 使用 cargo fmt 格式化
  • 使用 cargo clippy 检查
  • 依赖使用 workspace = true

前端

  • TypeScript 严格模式
  • ESLint 检查
  • 按功能域组织组件

项目结构

docs/
  PRODUCT.md              产品功能、架构决策
  DEVELOPMENT.md          开发索引
  architecture/           架构文档
  reference/              参考文档
  milestones/             里程碑文档

crates/
  rex-common/             通用类型、错误、配置解析
  rex-hub/                Hub 二进制
  rex-agent/              Agent 二进制
  rex-ssh/                SSH/SFTP 协议
  rex-mysql/              MySQL 协议
  rex-postgresql/         PostgreSQL 协议
  rex-redis/              Redis 协议
  rex-sqlite/             SQLite 协议
  rex-s3/                 S3/MinIO 协议
  rex-transfer/           文件传输引擎

packages/
  rex-console-web/        Vue 3 前端工程

Clone this wiki locally