Metadata-Version: 2.4
Name: asf-scaffold
Version: 0.1.0
Summary: ASF (AI Service Framework) 开发脚手架 —— 一键创建/校验 SU 模块
Author: Haiyue AI Team
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Python: >=3.8
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.0
Description-Content-Type: text/markdown

# ASF Scaffold

ASF (AI Service Framework) 开发脚手架 —— 一键创建、列表、校验 SU (Service Unit) 模块。

## 安装

```bash
pip install asf-scaffold
```

本地开发安装：

```bash
cd tools/cli
pip install -e .
```

## 依赖

- Python >= 3.8
- click >= 8.0
- jinja2 >= 3.0

## 命令一览

| 命令 | 说明 | 示例 |
|------|------|------|
| `create <category> <name>` | 创建新 SU 模块 | `asf create ai my_service` |
| `list [category]` | 列出所有 SU（扫描文件系统） | `asf list` / `asf list ai` |
| `validate <category> <name>` | 校验 SU 结构 | `asf validate ai sample` |

## 使用流程

### 1. 创建新 SU 模块

```bash
# 创建
asf create ai my_service

# 强制覆盖已存在的模块
asf create ai my_service --force
```

CLI 不会修改 `modules.conf`，需手动注册。

创建后自动生成以下文件结构：

```
server/app/ai/my_service/
├── __init__.py           # APIRouter 聚合
├── api.py                # API 端点
├── README.md             # 模块文档
├── requirements.txt      # Python 依赖
├── Dockerfile            # 容器构建
├── docker-compose.yml    # 容器编排
├── logger.yaml           # 日志配置
├── errors/
│   ├── __init__.py
│   └── error_codes.py    # 错误码定义 (ASF_ 前缀)
└── nginx/
    └── default.conf      # Nginx 反向代理
```

### 2. 查看已有模块

```bash
# 列出所有（扫描 server/app/ 文件系统）
asf list

# 按分类过滤
asf list ai

# 详细信息（含关键文件校验）
asf list --detail
```

### 3. 校验模块结构

```bash
asf validate ai my_service

# 自动补全缺失文件
asf validate ai my_service --repair
```

## 模板变量

模板文件位于 `src/asf_scaffold/templates/su_template/`，使用 Jinja2 语法，可用变量：

| 变量 | 示例值 (ai/my_service) |
|------|------------------------|
| `{{category}}` | `ai` |
| `{{name}}` | `my_service` |
| `{{class_name}}` | `AiMyService` |
| `{{error_prefix}}` | `AI_MY_SERVICE` |
| `{{category_title}}` | `Ai` |
| `{{name_title}}` | `MyService` |
| `{{log_path}}` | `logs/ai/my_service/my_service.log` |
| `{{image_tag}}` | `registry.inspures.com/ai_su/my_service:latest` |

## 项目结构

```
tools/cli/
├── pyproject.toml                # 包配置
├── README.md                     # 本文档
├── LICENSE                       # MIT 许可证
├── src/
│   └── asf_scaffold/            # 主包目录
│       ├── __init__.py           # 包初始化
│       ├── cli.py                # CLI 主入口
│       └── templates/           # SU 模块模板
├── tests/                       # 测试目录
└── docs/                        # 文档目录
```

## 发布到 PyPI

查看 [PyPI 发布流程文档](docs/pypi-publish.md) 了解详细的发布步骤。

## 许可证

MIT License
