# sdpy

**Repository Path**: clarkstore/sdpy

## Basic Information

- **Project Name**: sdpy
- **Description**: py项目目录结构生成
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-04
- **Last Updated**: 2026-09-24

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SDPY: Python 项目脚手架 + 统一工具集

🚀 **SDPY** (Standard Directory Project for Python) 的核心内容只有两点：

1. **统一目录结构脚手架**：CLI 命令 `sdpy init` 快速生成标准化、现代化的 Python 项目结构；
2. **开箱即用的工具集**：生成的业务项目内置 `kit/` 统一工具包（数据库、AI、MCP、Redis、文件、文档、向量库等），并以 `sdpy-kit` 独立发布到 PyPI（`publish/` 为发布目录），脱离脚手架也可直接安装使用。

## ✨ 主要特性

- 🏗️ **多种项目模板**: 支持 FastAPI、FastMCP、全栈应用三种项目类型
- 🧰 **统一工具集**: 生成项目内置 `kit/` 工具包：统一数据库访问层（`kit/db`）+ 三个数据库 Kit（PG/MySQL/SQLite）、AI 服务池、MCP 客户端、Redis/文件/文档/向量库/MinerU 工具，并以 `sdpy-kit` 发布 PyPI
- 📦 **uv依赖管理**: 自动配置现代化的uv包管理工具
- 🔧 **精简开发工具**: 预配置Black、Ruff、Pytest等核心代码质量工具
- 🐳 **Docker支持**: 自动生成Dockerfile和docker-compose.yml
- 🖥️ **全栈支持**: app类型含前端UI页面 + 打包发布脚本
- 📝 **完整文档**: 自动生成README、贡献指南、变更日志等文档
- ⚙️ **灵活配置**: 支持配置文件和命令行参数自定义
- 🎨 **美观界面**: 使用Rich库提供友好的命令行界面

## 🎯 支持的项目类型

| 类型          | 描述           | 主要依赖                     |
| ----------- | ------------ | ------------------------ |
| **fastapi** | 现代化Web API项目 | FastAPI, Uvicorn, Loguru |
| **fastmcp** | MCP服务器项目     | FastMCP, Loguru          |
| **app**     | 全栈应用（含前端UI） | FastAPI, Uvicorn, Loguru |

## 📚 文档导航

> 本 README 为概要；**详细规范、模块手册、操作手册与代码样板一律下沉到 `docs/agents/` 分层文档**，按需查阅。

| 层级 | 文档 | 内容 |
|------|------|------|
| **规范** | [docs/agents/conventions.md](docs/agents/conventions.md) | 命名、编码、依赖、测试规则 |
| **模块手册** | [docs/agents/modules/overview.md](docs/agents/modules/overview.md) | 技术选型、目录结构、模块依赖、导出符号 |
| | [docs/agents/modules/config.md](docs/agents/modules/config.md) | Settings 配置项、日志入口 |
| | [docs/agents/modules/core-generator.md](docs/agents/modules/core-generator.md) | 生成器、ProjectConfig/Generator |
| | [docs/agents/modules/kit-db.md](docs/agents/modules/kit-db.md) | 统一数据库工具（`kit/db` + 三个 `*Kit`） |
| **操作手册** | [docs/agents/operations/build-test-run.md](docs/agents/operations/build-test-run.md) | 跑测试、格式化、质量检查、完成标准 |
| | [docs/agents/operations/generate-and-package.md](docs/agents/operations/generate-and-package.md) | 生成项目、打包、一键启动、sdpy-kit 发布 |
| | [docs/agents/operations/add-module.md](docs/agents/operations/add-module.md) | 新增 Kit/工具类/项目类型/修改模板 |
| **参考资料** | [docs/agents/reference/code-patterns.md](docs/agents/reference/code-patterns.md) | 代码样板：模型/CRUD/事务/异常/日志 |
| | [docs/agents/reference/config-samples.md](docs/agents/reference/config-samples.md) | 配置样板：.env/docker/数据库连接 |

## 🗂️ 仓库分区说明

| 分区 | 角色 |
|------|------|
| `core/` + `config/` | 脚手架本体（生成器 + 配置与 AI/MCP 档案素材） |
| `kit/` | 工具集本体（PyPI 包 `sdpy-kit` 的源） |
| `tests/` | 测试 |
| `research/` | 技术调研（独立运行，不进生成项目与 PyPI 包） |
| `publish/` | `sdpy-kit` PyPI 发布目录 |
| `ui/` / `scripts/` / `docker/` | 生成素材：仅供 `sdpy init` 复制到生成项目，与主工程运行无关 |

## 🚀 快速开始

### 安装

#### 方法1：从源码安装

```bash
# 克隆仓库
git clone https://gitee.com/clarkstore/sdpy.git
cd sdpy

# 安装uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装依赖
uv sync

# 安装SDPY到系统
uv pip install -e .
```

#### 方法2：直接使用

```bash
# 下载并进入目录
git clone https://gitee.com/clarkstore/sdpy.git
cd sdpy

# 使用uv直接运行
uv run python main.py --help
```

### 基本使用

#### 生成全栈应用项目（默认类型）

```bash
# 默认生成含前端UI的全栈应用（--type app 可省略）
uv run sdpy init my-app --author "Clark" --email "changhongyuan@126.com"

# 等价于
uv run sdpy init my-app --type app --author "Clark" --email "changhongyuan@126.com"
```

全栈应用额外包含：
- `ui/dist/index.html` — 前端问候页（后续替换为真实前端构建产物）
- `scripts/package.ps1` — 打包发布脚本（生成含 Python 运行时的 zip 包）
- `scripts/start.ps1` — 一键启动脚本（兼容开发模式和发布包模式）

#### 生成 FastAPI / FastMCP 项目（需指定 --type）

```bash
# FastAPI 项目（需显式指定 --type fastapi）
uv run sdpy init my-api --type fastapi --author "Clark" --email "changhongyuan@126.com"

# FastMCP 项目（需显式指定 --type fastmcp）
uv run sdpy init my-mcp --type fastmcp --description "A useful MCP server"
```

#### 查看可用模板

```bash
# 列出所有可用的项目模板
sdpy templates
```

#### 生成项目配置文件

```bash
# 生成配置文件模板
sdpy init-config my-project --type fastapi --output project-config.yaml

# 编辑配置文件后使用
sdpy init my-project --config project-config.yaml
```

> 生成器 CLI 的完整选项见 [docs/agents/operations/generate-and-package.md](docs/agents/operations/generate-and-package.md)。

## 📁 生成的项目结构

### FastAPI项目结构示例

```
my-api/
├── app/                    # 源代码目录（即源码根，导入路径保持 config.*/kit.*）
│   ├── api/               # API路由模块
│   │   ├── __init__.py
│   │   └── router.py
│   ├── config/            # 配置模块（复制自主工程 config/）
│   │   ├── __init__.py
│   │   ├── sys_config.py  #   应用配置（精简版）
│   │   ├── ai_models.json #   AI 模型档案（chat/embedding/rerank/image）
│   │   └── mcp_servers.json # MCP 服务器档案
│   ├── kit/               # 统一工具集（完整复制自主工程 kit/）
│   │   ├── config/        #   kit 配置（Settings）+ 日志入口
│   │   ├── ai/            #   AI 服务池
│   │   ├── db/            #   统一数据库访问层
│   │   ├── mcp_kit.py     #   MCP 客户端
│   │   └── ...            #   common/file/redis/doc/zvec/mineru 工具
│   ├── models/            # 数据模型
│   │   ├── __init__.py
│   │   └── base.py
│   └── utils/             # 工具函数
│       ├── __init__.py
│       └── helpers.py
├── docker/                # Docker相关文件
│   ├── .dockerignore      # Docker忽略文件
│   ├── Dockerfile         # Docker镜像配置
│   └── docker-compose.yml # Docker Compose配置
├── main.py                # 主入口文件
├── pyproject.toml         # 项目配置和依赖
├── .gitignore             # Git忽略文件
├── .env.example           # 环境变量模板
├── README.md              # 项目说明文档
├── CHANGELOG.md           # 变更日志
├── CONTRIBUTING.md        # 贡献指南
└── LICENSE                # 许可证文件
```

### 全栈应用项目结构示例

```
my-app/
├── app/                    # 源代码目录（同 FastAPI 结构）
│   ├── api/               # API路由模块
│   ├── config/            # 配置模块
│   ├── kit/               # 数据库与工具类
│   ├── models/            # 数据模型
│   └── utils/             # 工具函数
├── ui/                     # 前端目录
│   └── dist/              #   前端构建产物（含 index.html 问候页）
├── scripts/                # 脚本目录
│   ├── package.ps1        #   打包发布脚本
│   └── start.ps1          #   一键启动脚本
├── docker/                # Docker相关文件
├── main.py                # 主入口文件
└── pyproject.toml         # 项目配置和依赖
```

## ⚙️ 高级配置

### 使用配置文件

创建一个YAML配置文件来自定义项目生成：

```yaml
# project-config.yaml
project_name: "my-project"
project_type: "fastapi"
description: "An awesome FastAPI project"
author: "Clark"
email: "changhongyuan@126.com"
version: "0.1.0"
license: "MIT"

# 功能选项
use_uv: true
init_git: true
use_docker: true

# 自定义依赖
dependencies:
  - "fastapi"
  - "uvicorn"
  - "loguru"
  - "sqlalchemy"  # 额外的数据库依赖

dev_dependencies:
  - "pytest"
  - "black"
  - "ruff"
```

然后使用配置文件生成项目：

```bash
uv run sdpy init my-project --config project-config.yaml
```

### 命令行选项

```bash
# 查看所有选项
uv run sdpy init --help

# 常用选项
uv run sdpy init my-project \
  --type fastapi \
  --author "Clark" \
  --email "changhongyuan@126.com" \
  --description "Project description" \
  --target-dir ./projects \
  --no-git \
  --no-uv \
  --no-docker
```

> 完整命令与打包/启动流程见 [docs/agents/operations/generate-and-package.md](docs/agents/operations/generate-and-package.md)。

## 🛠️ 开发指南

### 生成项目后的开发流程

1. **进入项目目录**
   ```bash
   cd my-project
   ```
2. **安装依赖**
   ```bash
   uv sync
   ```
3. **激活虚拟环境**（可选）
   ```bash
   source .venv/bin/activate  # Linux/macOS
   # 或
   .venv\Scripts\activate     # Windows
   ```
4. **运行项目**
   ```bash
   # FastAPI项目
   uv run uvicorn main:app --reload

   # 其他项目
   uv run python main.py
   ```
5. **代码质量检查**
   ```bash
   # 代码格式化
   uv run black .

   # 代码检查
   uv run ruff check .
   ```
6. **运行测试**
   ```bash
   # 运行所有测试
   uv run pytest
   ```

### Docker部署

生成的项目包含完整的Docker配置：

```bash
# 构建镜像
docker build -t my-project .

# 运行容器
docker run -p 8000:8000 my-project

# 使用docker-compose
docker-compose up -d
```

## 📚 API参考

### Python API

SDPY也提供了Python API供程序化使用：

```python
from core import ProjectGenerator, ProjectConfig

# 创建配置
config = ProjectConfig(
    project_name="my-project",
    project_type="fastapi",
    author="Clark",
    email="changhongyuan@126.com"
)

# 创建生成器
generator = ProjectGenerator(config)

# 生成项目
success = generator.generate_project(
    project_name="my-project",
    target_dir="./output"
)
```

### CLI命令参考

| 命令                            | 描述     |
| ----------------------------- | ------ |
| `uv run sdpy init <name>`     | 生成新项目（默认 `app`） |
| `uv run sdpy templates`       | 列出可用模板 |
| `uv run sdpy init-config <name>` | 生成配置文件 |
| `uv run sdpy version`         | 显示版本信息 |

### 内置工具集（kit 体系）

生成的项目内置统一工具包，可直接使用；也可脱离脚手架单独安装：`pip install sdpy-kit`。

- **统一数据库访问层** `kit/db`：引擎管理、`CRUDBase`、`session_scope`、`@transactional`
- **数据库 Kit**：`PgKit` / `MySqlKit` / `SQLiteKit`（三库 API 完全一致，切换只需改 import）
- **AI 服务池** `kit/ai`：chat / embedding / rerank / image，多厂商候选链 + 故障转移
- **MCP 客户端** `kit/mcp_kit`：档案驱动多服务器（streamable-http / sse）
- **其他工具**：`CommonKit` / `FileKit` / `RedisKit` / `Md2DocKit` / `ZvecKit` / `MinerUKit`

> kit 体系详细 API 与配置见 [docs/agents/modules/kit-db.md](docs/agents/modules/kit-db.md) 与 [docs/agents/modules/config.md](docs/agents/modules/config.md)。

## 🤝 贡献指南

我们欢迎各种形式的贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细信息。

### 开发环境设置

```bash
# 克隆仓库
git clone https://gitee.com/clarkstore/sdpy.git
cd sdpy

# 安装开发依赖
uv sync --dev

# 运行测试
uv run pytest
```

## 📄 许可证

本项目采用 MIT 许可证。详情请查看 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [uv](https://github.com/astral-sh/uv) - 现代Python包管理器
- [FastAPI](https://fastapi.tiangolo.com/) - 现代Web框架
- [Click](https://click.palletsprojects.com/) - 命令行界面库
- [Rich](https://rich.readthedocs.io/) - 丰富的终端输出库
- [Loguru](https://loguru.readthedocs.io/) - 简化的日志库

## 📞 支持

如果您遇到问题或有建议，请：

1. 查看 [FAQ](docs/faq.md)
2. 搜索 [Issues](https://gitee.com/clarkstore/sdpy/issues)
3. 创建新的 Issue
4. 联系维护者

## 🧹 清理Python缓存文件

在开发过程中，Python会产生各种缓存文件，您可以使用以下命令进行清理：

### 清理Python缓存文件

```
# 删除Python字节码缓存文件
find . -type d -name __pycache__ -exec rm -rf {} +
find . -name "*.pyc" -delete
find . -name "*.pyo" -delete

# Windows PowerShell命令
Get-ChildItem -Path . -Recurse -Name "__pycache__" | Remove-Item -Recurse -Force
Get-ChildItem -Path . -Recurse -Name "*.pyc" | Remove-Item -Force
```

### 清理项目特定缓存

```
# 删除测试缓存
rm -rf .pytest_cache/
rm -rf .coverage
rm -rf htmlcov/

# 删除构建缓存
rm -rf build/
rm -rf dist/
rm -rf *.egg-info/

# 删除日志文件
rm -rf logs/*.log

# 删除类型检查缓存
rm -rf .mypy_cache/
```

### 一键清理脚本

您也可以创建一个清理脚本 `cleanup.sh`：

```
#!/bin/bash
echo "清理Python缓存文件..."
find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
find . -name "*.pyc" -delete 2>/dev/null || true
find . -name "*.pyo" -delete 2>/dev/null || true
rm -rf .pytest_cache/ .coverage htmlcov/ build/ dist/ *.egg-info/ .mypy_cache/ 2>/dev/null || true
echo "清理完成！"
```

***

**让Python项目开发更简单！** 🐍✨