📖 技能介绍

name: python-flask-vue-creator description: "创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。"

Flask + Vue.js 项目创建器

搭建 Flask 3.1 + Vue.js 全栈项目，采用单端口架构、结构化日志和独特的前端设计。

架构概述

层级	技术选型
Web 框架	Flask 3.1.0
前端	Vue.js (CDN, 单端口)
依赖管理	uv
日志	Python logging (TimedRotatingFileHandler)
端口	80 (统一)

单端口架构

所有请求由 Flask 在 80 端口统一处理。静态文件（HTML/CSS/JS）通过 Flask 路由从 templates/ 目录提供。

项目创建工作流

按顺序执行以下步骤：

收集需求 - 询问项目名称和简要描述
初始化项目结构 - 运行 scripts/init_project.py
配置依赖 - 使用 uv 设置 pyproject.toml
创建 Flask 入口 - 生成包含日志的主应用文件
设计前端 - 遵循前端设计指南（见下文）
更新 AGENTS.md - 任何更改后同步项目文档
验证并运行 - 测试项目正常启动

步骤 1：收集需求

向用户询问： - 项目名称（用于目录、文件名和应用标题） - 应用功能的简要描述 - 任何特定的设计偏好（配色方案、风格方向）

步骤 2：初始化项目结构

运行初始化脚本：

python scripts/init_project.py <project-name> --path <target-directory>

这将创建：

<project-name>/
├── AGENTS.md                    # AI Agent 项目指南（自动生成）
├── pyproject.toml               # uv 项目配置
├── uv.lock                      # uv 锁定文件（自动生成）
├── src/
│   ├── <project-name>.py        # Flask 主入口（含日志）
│   ├── templates/               # 前端资源
│   │   ├── <project-name>.html  # 主页面 (Vue.js)
│   │   ├── css/                 # 样式文件
│   │   ├── js/                  # JavaScript 文件
│   │   └── assets/              # 静态资源（图片、字体等）
│   ├── utils/                   # 核心工具模块
│   │   ├── __init__.py
│   │   └── logger.py            # 日志模块
│   └── log/                     # 日志输出目录
│       └── *.log                # 按模块分日志文件（按天轮转）

步骤 3：配置依赖

pyproject.toml 自动生成，包含 uv 镜像配置：

[tool.uv]
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

核心依赖：

dependencies = [
    "flask>=3.1.0",
]

步骤 4：创建 Flask 入口

生成的 <project-name>.py 包含集成的日志功能：

from flask import Flask, send_from_directory, send_file
from utils.logger import get_logger

app = Flask(__name__)
logger = get_logger('<project-name>')

@app.route('/')
def index():
    return send_file('templates/<project-name>.html')

# ... 静态文件路由 ...

if __name__ == '__main__':
    logger.info('启动服务器，端口 80...')
    app.run(host='0.0.0.0', port=80, debug=True)

步骤 5：设计前端

创建 HTML/CSS/JS 时应用前端设计指南。完整设计系统参见 references/frontend-design.md。

核心原则：

反 AI 风格：避免 Inter、Roboto、Arial、紫色渐变、emoji 图标
独特字体：使用独特的 Google Fonts 组合（参见 references/frontend-design.md "字体" 部分）
有意配色：选择特定场景的配色方案，而非通用渐变
仅用 SVG 图标：使用 Heroicons、Lucide 或 Simple Icons — 不用 emoji
Vue.js CDN 引入：在 HTML 中使用 Vue 3 CDN，Composition API 配合 <script setup> 模式

Vue.js 集成模式：

<script src="https://unpkg.com/vue@3/dist/vue.global.js"></script>
<div id="app">
  <!-- Vue 模板 -->
</div>
<script>
const { createApp, ref, computed, onMounted } = Vue

const app = createApp({
  setup() {
    // Composition API
    return {}
  }
})
app.mount('#app')
</script>

详细的 Vue.js 最佳实践参见 references/vue-guidelines.md。

步骤 6：更新 AGENTS.md

重要：任何项目修改后，更新 AGENTS.md 以反映变更。

AGENTS.md 文件在项目创建时自动生成，作为 AI Agent 项目指南。必须与实际项目状态保持同步。

何时更新 AGENTS.md： - 添加新路由或 API 端点 - 添加新工具模块或文件 - 更改项目结构 - 添加新依赖 - 修改日志配置 - 任何架构变更

更新内容： - 项目结构树（添加/删除文件和目录） - 架构描述（新路由、模块、功能） - 开发指南（新约定或模式） - 更新日志表（添加日期、版本、描述条目）

更新日志格式：

## 更新日志

| 日期 | 版本 | 变更内容 |
|------|------|---------|
| 2026-06-07 | 0.1.0 | 初始项目创建 |
| 2026-06-08 | 0.2.0 | 新增用户认证模块 |

步骤 7：验证并运行

cd <project-path>
uv sync
uv run python src/<project-name>.py

日志模块

概述

位置：src/utils/logger.py
日志目录：src/log/
格式：%(asctime)s | %(levelname)-8s | %(name)s | %(message)s
轮转：按天 (TimedRotatingFileHandler)，保留 30 天
输出：同时输出到控制台和文件

使用方法

from utils.logger import get_logger

logger = get_logger('module_name')
logger.info('操作成功完成')
logger.warning('发生了意外情况')
logger.error('发生错误: %s', error_detail)