# craft

**Repository Path**: atlaslee/craft

## Basic Information

- **Project Name**: craft
- **Description**: No description available
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-11
- **Last Updated**: 2026-05-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Craft — AI Agent 服务平台

> 面向开发者的智能代码生成与部署平台，支持对话式交互、自动化工作流、多云部署与按量计费。

---

## 🏗️ 架构概览

```
┌─────────────────────────────────────────────────────────────────────────┐
│                              客户端层                                     │
│   ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────────────┐       │
│   │ Web Chat │  │  Admin   │  │  Mobile  │  │   IDE Plugin     │       │
│   │ (React)  │  │ Dashboard│  │  (H5)    │  │  (VSCode/JetBrains│      │
│   └────┬─────┘  └────┬─────┘  └────┬─────┘  └────────┬─────────┘       │
└────────┼─────────────┼─────────────┼─────────────────┼─────────────────┘
         │             │             │                 │
         ▼             ▼             ▼                 ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                            网关层 (Nginx)                                │
│         SSL 终止 / 负载均衡 / 静态资源 / WebSocket 代理                   │
└─────────────────────────────────────────────────────────────────────────┘
         │
         ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           应用层 (FastAPI)                               │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐   │
│  │   会话管理   │ │   消息网关   │ │    HITL     │ │   知识库管理     │   │
│  │  (JWT+RBAC) │ │(WebSocket/ │ │ 人工介入     │ │ (CRUD+检索)     │   │
│  │             │ │   SSE)      │ │             │ │                 │   │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘   │
│  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐   │
│  │   计费中心   │ │   工作流     │ │   审计日志   │ │   多云部署       │   │
│  │(Token计量/钱包│ │(LangGraph) │ │ 合规追踪     │ │(阿里云/腾讯/华为/│   │
│  │/充值/熔断)   │ │             │ │             │ │  AWS)           │   │
│  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
         │
    ┌────┴────┬──────────┬──────────┬──────────┐
    ▼         ▼          ▼          ▼          ▼
┌──────┐ ┌──────┐ ┌──────────┐ ┌────────┐ ┌──────────┐
│Postgre│ │ Redis│ │  LiteLLM │ │  Mem0  │ │  沙箱    │
│SQL+   │ │(缓存/ │ │  Proxy   │ │(记忆)  │ │(Docker)  │
│pgvector│ │限流) │ │          │ │        │ │          │
└──────┘ └──────┘ └──────────┘ └────────┘ └──────────┘
```

---

## 🚀 快速开始

### 环境要求

- Python 3.12+
- Docker & Docker Compose
- Node.js 18+（前端开发）

### 1. 克隆仓库

```bash
git clone git@gitee.com:atlaslee/craft.git
cd craft
```

### 2. 配置环境变量

```bash
cp .env.example .env
# 编辑 .env，填入数据库、Redis、LLM 等配置
```

### 3. 启动基础设施

```bash
docker-compose -f docker-compose.dev.yml up -d postgres redis litellm
```

### 4. 数据库迁移

```bash
pip install -e ".[dev]"
alembic upgrade head
```

### 5. 启动后端服务

```bash
uvicorn craft.main:app --reload --host 0.0.0.0 --port 8000
```

### 6. 启动前端（可选）

```bash
cd frontend
npm install
npm run dev
```

---

## 🧪 测试与质量

| 类别 | 数量 | 覆盖率 |
|------|------|--------|
| 单元测试 | 48 个文件 | — |
| 集成测试 | 19 个文件 | — |
| 安全测试 | 5 个文件 | — |
| 性能测试 | 9 个文件 | — |
| **合计** | **626 passing** | **89.06%** |

```bash
# 运行全部测试
pytest tests/ -v --cov=craft --cov-report=term-missing

# 运行安全扫描
bash tests/security/run_security_suite.sh

# 运行性能基准
bash tests/performance/run_performance_suite.sh

# 代码质量检查
flake8 craft/ tests/
bandit -r craft/ -f json -o bandit-report.json
```

---

## 📦 技术栈

| 层级 | 技术选型 |
|------|----------|
| **后端框架** | FastAPI + SQLAlchemy 2.0 (async) + Pydantic v2 |
| **数据库** | PostgreSQL 15 + pgvector（向量检索） |
| **缓存** | Redis 7（缓存、限流、分布式锁） |
| **LLM 网关** | LiteLLM Proxy（统一路由 100+ 模型） |
| **工作流引擎** | LangGraph（10 步状态机 + 检查点 + Time-Travel） |
| **记忆系统** | Mem0（多租户隔离 + 语义检索） |
| **代码执行** | Crush / Aider / Kimi CLI（沙箱化运行） |
| **前端** | React 18 + TypeScript + Vite |
| **部署** | Docker + Kubernetes + 多云（阿里云/腾讯云/华为云/AWS） |

---

## 🗓️ 里程碑

| 里程碑 | 功能 | 状态 |
|--------|------|------|
| MS0 | 基础设施 POC | ✅ 已验收 |
| MS1 | 核心骨架（认证、多租户、ORM） | ✅ 已验收 |
| MS2 | 基础能力（LLM 网关、记忆、消息） | ✅ 已验收 |
| MS3 | 对话循环（检索 + 回复、知识库） | ✅ 已验收 |
| MS4 | 完整工作流（LangGraph 10 步 + HITL + Time-Travel） | ✅ 已验收 |
| MS5 | 代码执行（Crush/Aider/Kimi + 沙箱 + CI/CD） | ✅ 已验收 |
| MS6 | 客户交互（WebSocket/SSE + HITL UI + Admin） | ✅ 已验收 |
| MS7 | 计费系统（Token 计量、钱包、充值、熔断） | ✅ 已验收 |
| MS8 | 智能化增强（混合检索、摘要、Prompt A/B、归档、审计、用户映射） | ✅ 已验收 |
| MS9 | 多云与扩展（腾讯/华为/AWS、模型路由、Fallback、国产 LLM） | ✅ 已验收 |

完整验收报告见 [`docs/planning/product-acceptance-report.md`](docs/planning/product-acceptance-report.md)。

---

## 🛡️ 安全合规

- **认证鉴权**: JWT + RBAC 权限模型
- **租户隔离**: 数据库行级隔离 + 中间件注入
- **沙箱执行**: Docker 容器化运行用户代码
- **密钥管理**: 禁止硬编码密钥，统一走环境变量 / 密钥管理服务
- **安全扫描**: Bandit（静态分析）+ Safety（依赖漏洞）+ 自定义渗透测试套件

---

## 🚀 部署

### Staging 环境

```bash
# 一键部署
cp .env.staging.example .env.staging
bash scripts/deploy-staging.sh
```

详见 [`docker-compose.staging.yml`](docker-compose.staging.yml) 和 [`scripts/deploy-staging.sh`](scripts/deploy-staging.sh)。

### Kubernetes

```bash
kubectl apply -f k8s/
```

---

## 📄 文档索引

| 文档 | 路径 |
|------|------|
| 架构设计 | [`docs/design/architecture-design.md`](docs/design/architecture-design.md) |
| 执行计划 | [`docs/planning/execution-plan.md`](docs/planning/execution-plan.md) |
| 产品验收报告 | [`docs/planning/product-acceptance-report.md`](docs/planning/product-acceptance-report.md) |
| 产品用户手册 | [`docs/user-manual.md`](docs/user-manual.md) |

---

## 📜 License

MIT License © 2026 Craft Team