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)
日志文件
每个日志记录器名称创建单独的日志文件：src/log/<logger_name>.log
文件在午夜轮转，命名模式：<logger_name>.log.YYYY-MM-DD
交付前检查清单
交付前验证：
- [ ] 项目结构符合指定布局
- [ ]
pyproject.toml包含[tool.uv]清华镜像配置 - [ ]
pyproject.toml位于项目根目录（与 src 同级） - [ ] Flask 路由服务所有静态文件目录
- [ ] 日志模块已集成到 Flask 入口
- [ ]
src/log/目录存在且包含.gitkeep - [ ]
AGENTS.md存在且反映当前项目状态 - [ ] HTML 使用 Vue 3 CDN 和 Composition API
- [ ] 无 emoji 图标（仅用 SVG）
- [ ] 字体独特（非 Inter/Roboto/Arial）
- [ ] 配色方案符合场景
- [ ] 所有交互元素有
cursor-pointer - [ ] 文本对比度达到 4.5:1 最低要求
- [ ] 在 375px、768px、1024px、1440px 响应式适配
