266 lines
8.6 KiB
Markdown
266 lines
8.6 KiB
Markdown
# GitDataAI
|
||
|
||
> Where Humans & Agents Engineer Together.
|
||
>
|
||
> Every action is a command. Every command is versioned, auditable, and composable.
|
||
|
||
## 项目概述
|
||
|
||
GitDataAI 是一个面向 Agentic 时代的开发协作平台，通过 **Command as Service** 理念，将人类与 AI 代理的协作标准化。每一次操作——创建仓库、发起 PR、调度 Agent——都是一条可版本化、可回放、可组合的命令。CLI 即 API，工作流即可查询的命令流。
|
||
|
||
### 核心功能
|
||
|
||
- **Command as Service** — 所有操作均为版本化命令，CLI 即 API，支持回放与组合
|
||
- **Git Repositories** — 完整 Git 操作（分支、提交、合并），HTTP/SSH 访问，内置分支保护
|
||
- **Collaborative Rooms** — 人类与 AI 代理共存的实时命令执行空间
|
||
- **AI Agents** — 监听命令流，执行 Skill，报告结果，可持久化记忆
|
||
- **Issue & Pull Request** — 追踪、审查、Agent 自动化
|
||
- **Skill Registry** — 可复用的 Agent 行为包，通过命令调用
|
||
|
||
## 技术栈
|
||
|
||
### 后端 (Rust)
|
||
|
||
| 类别 | 技术 |
|
||
|--------|----------------------|
|
||
| 语言 | Rust 2024 Edition |
|
||
| Web 框架 | Actix-web |
|
||
| ORM | SeaORM |
|
||
| 数据库 | PostgreSQL |
|
||
| 缓存 | Redis |
|
||
| 实时通信 | WebSocket (actix-ws) |
|
||
| 消息队列 | Redis |
|
||
| 向量数据库 | Qdrant |
|
||
| Git 操作 | git2 / git2-ext |
|
||
| 认证 | JWT + Session |
|
||
| API 文档 | utoipa (OpenAPI) |
|
||
|
||
### 前端 (TypeScript/React)
|
||
|
||
| 类别 | 技术 |
|
||
|----------|----------------------------|
|
||
| 语言 | TypeScript 5.9 |
|
||
| 框架 | React 19 |
|
||
| 路由 | React Router v7 |
|
||
| 构建工具 | Vite 8 + SWC |
|
||
| UI 组件 | shadcn/ui + Tailwind CSS 4 |
|
||
| 状态管理 | TanStack Query |
|
||
| HTTP 客户端 | Axios + OpenAPI 生成 |
|
||
| Markdown | react-markdown + Shiki |
|
||
| 拖拽 | dnd-kit |
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
code/
|
||
├── apps/ # 应用程序入口
|
||
│ ├── app/ # 主 Web 应用
|
||
│ ├── gitserver/ # Git HTTP/SSH 服务器
|
||
│ ├── git-hook/ # Git Hook 处理服务
|
||
│ ├── email/ # 邮件发送服务
|
||
│ ├── migrate/ # 数据库迁移工具
|
||
│ └── operator/ # Kubernetes 操作器
|
||
├── libs/ # 共享库
|
||
│ ├── api/ # REST API 路由与处理器
|
||
│ ├── models/ # 数据库模型 (SeaORM)
|
||
│ ├── service/ # 业务逻辑层
|
||
│ ├── db/ # 数据库连接池
|
||
│ ├── config/ # 配置管理
|
||
│ ├── session/ # 会话管理
|
||
│ ├── git/ # Git 操作封装
|
||
│ ├── room/ # 实时聊天服务
|
||
│ ├── queue/ # 消息队列
|
||
│ ├── webhook/ # Webhook 处理
|
||
│ ├── rpc/ # RPC 服务 (gRPC/Tonic)
|
||
│ ├── email/ # 邮件发送
|
||
│ ├── agent/ # AI Agent 集成
|
||
│ ├── avatar/ # 头像处理
|
||
│ ├── transport/ # 传输层
|
||
│ └── migrate/ # 迁移脚本
|
||
├── src/ # 前端源代码
|
||
│ ├── app/ # 页面路由组件
|
||
│ ├── components/ # 可复用组件
|
||
│ ├── contexts/ # React Context
|
||
│ ├── client/ # API 客户端 (OpenAPI 生成)
|
||
│ ├── hooks/ # 自定义 Hooks
|
||
│ └── lib/ # 工具函数
|
||
├── docker/ # Docker 配置
|
||
├── scripts/ # 构建脚本
|
||
├── openapi.json # OpenAPI 规范文件
|
||
└── Cargo.toml # Rust Workspace 配置
|
||
```
|
||
|
||
## 快速开始
|
||
|
||
### 环境要求
|
||
|
||
- **Rust**: 最新稳定版 (Edition 2024)
|
||
- **Node.js**: >= 20
|
||
- **pnpm**: >= 10
|
||
- **PostgreSQL**: >= 14
|
||
- **Redis**: >= 6
|
||
|
||
### 安装步骤
|
||
|
||
1. **克隆仓库**
|
||
```bash
|
||
git clone <repository-url>
|
||
cd code
|
||
```
|
||
|
||
2. **配置环境变量**
|
||
```bash
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，配置数据库连接等信息
|
||
```
|
||
|
||
3. **启动数据库与 Redis**
|
||
```bash
|
||
# 使用 Docker 启动（推荐）
|
||
docker compose -f docker/docker-compose.yml up -d
|
||
```
|
||
|
||
4. **数据库迁移**
|
||
```bash
|
||
cargo run -p migrate
|
||
```
|
||
|
||
5. **启动后端服务**
|
||
```bash
|
||
cargo run -p app
|
||
```
|
||
|
||
6. **启动前端开发服务器**
|
||
```bash
|
||
pnpm install
|
||
pnpm dev
|
||
```
|
||
|
||
7. **访问应用**
|
||
- 前端: http://localhost:5173
|
||
- 后端 API: http://localhost:8080
|
||
|
||
## 开发指南
|
||
|
||
### 后端开发
|
||
|
||
```bash
|
||
# 运行所有测试
|
||
cargo test
|
||
|
||
# 运行特定模块测试
|
||
cargo test -p service
|
||
|
||
# 检查代码质量
|
||
cargo clippy --workspace
|
||
|
||
# 格式化代码
|
||
cargo fmt --workspace
|
||
|
||
# 生成 OpenAPI 文档
|
||
pnpm openapi:gen-json
|
||
```
|
||
|
||
### 前端开发
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pnpm install
|
||
|
||
# 启动开发服务器
|
||
pnpm dev
|
||
|
||
# 构建生产版本
|
||
pnpm build
|
||
|
||
# 代码检查
|
||
pnpm lint
|
||
|
||
# 生成 OpenAPI 客户端
|
||
pnpm openapi:gen
|
||
```
|
||
|
||
### 数据库迁移
|
||
|
||
```bash
|
||
# 创建新迁移
|
||
cd libs/migrate && cargo run -- create <migration_name>
|
||
|
||
# 执行迁移
|
||
cargo run -p migrate
|
||
```
|
||
|
||
## 配置说明
|
||
|
||
### 必需配置项
|
||
|
||
| 变量名 | 说明 | 示例 |
|
||
|--------------------|---------------|---------------------------------------|
|
||
| `APP_DATABASE_URL` | PostgreSQL 连接 | `postgresql://user:pass@localhost/db` |
|
||
| `APP_REDIS_URL` | Redis 连接 | `redis://localhost:6379` |
|
||
| `APP_AI_API_KEY` | AI 服务 API Key | `sk-xxxxx` |
|
||
| `APP_SMTP_*` | SMTP 邮件配置 | 见 `.env.example` |
|
||
|
||
### 可选配置项
|
||
|
||
| 变量名 | 默认值 | 说明 |
|
||
|--------------------------------|-------------|------------|
|
||
| `APP_DATABASE_MAX_CONNECTIONS` | 10 | 数据库连接池大小 |
|
||
| `APP_LOG_LEVEL` | info | 日志级别 |
|
||
| `APP_QDRANT_URL` | - | 向量数据库地址 |
|
||
| `APP_REPOS_ROOT` | /data/repos | Git 仓库存储路径 |
|
||
|
||
完整配置请参考 `.env.example`。
|
||
|
||
## API 文档
|
||
|
||
启动服务后访问 http://localhost:8080/swagger-ui 查看完整的 API 文档。
|
||
|
||
## 架构设计
|
||
|
||
### 后端分层架构
|
||
|
||
```
|
||
┌─────────────────────────────────────┐
|
||
│ apps/app │ ← 应用入口
|
||
├─────────────────────────────────────┤
|
||
│ libs/api │ ← HTTP 路由/Handler
|
||
├─────────────────────────────────────┤
|
||
│ libs/service │ ← 业务逻辑层
|
||
├─────────────────────────────────────┤
|
||
│ libs/models │ libs/db │ libs/git│ ← 数据访问层
|
||
├─────────────────────────────────────┤
|
||
│ PostgreSQL │ Redis │ Qdrant │ ← 存储层
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
### 前端目录结构
|
||
|
||
```
|
||
src/
|
||
├── app/ # 页面级组件 (按功能模块组织)
|
||
│ ├── project/ # 项目相关页面 (Issue、Settings)
|
||
│ ├── repository/ # 仓库相关页面 (PR、代码浏览)
|
||
│ └── settings/ # 用户设置
|
||
├── components/ # 可复用组件
|
||
│ ├── ui/ # 基础 UI 组件 (shadcn)
|
||
│ ├── project/ # 项目相关组件
|
||
│ ├── repository/ # 仓库相关组件
|
||
│ └── room/ # 聊天相关组件
|
||
├── contexts/ # React Context (用户、聊天室等)
|
||
├── client/ # OpenAPI 生成的客户端
|
||
└── lib/ # 工具函数与 Hooks
|
||
```
|
||
|
||
## 任务清单
|
||
|
||
项目当前开发任务详见 [task.md](./task.md)，按优先级分为：
|
||
|
||
- **P0** — 阻塞性问题（核心流程不通）
|
||
- **P1** — 核心体验（关键功能）
|
||
- **P2** — 体验优化（增强功能）
|
||
|
||
## 许可证
|
||
|
||
[待添加]
|