comfy-prompt-studio: Instructions file for Claude Code

CLAUDE.md

• 本文件为 CLAUDE 记忆文件，只记录最新的项目状态，保持文件内容的准确性，避免历史记录的干扰
• 使用中文
• 项目必须工程化，方便维护，永远保持文件位置正确
• 永远保证 CLAUDE.md, README.md, AGENTS.md 的内容是准确的,文档和代码一致
• 使用设计模式，保持代码结构清晰，方便维护
• 修复 bug 请先 debug 确认问题所在，再进行修复
• 新增功能先验证功能是否正常，再进行新增
• windows 下必须使用 utf-8 编码，避免中文乱码问题

if sys.platform == 'win32':
    sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')

• 根目录 CLAUDE.md, README.md, AGENTS.md 禁止删除

AI 图像生成 Web 应用：Ollama 提示词增强 + ComfyUI 工作流 + Flask WebSocket 实时更新

架构设计

数据流： 用户输入 → Ollama（提示词增强）→ ComfyUI（图像生成）→ WebSocket → 前端展示

核心模块：

• src/cli/run.py - 应用启动入口
• src/cli/serve.py - Flask 服务器
• src/app/__init__.py - Flask 应用工厂
• src/core/prompt/ - 提示词生成服务（Ollama/Gemini）
• src/core/comfyui/ - ComfyUI API 集成，自动选择工作流
• src/core/history/ - SQLite 历史记录管理服务

工作流系统：

• config/workflows/flowv_normal.json - 普通文生图工作流
• config/workflows/flow_face.json - 人脸替换工作流
• 自动选择逻辑：有 image_path 参数时使用人脸工作流

快速启动

前置要求： ComfyUI (127.0.0.1:8188) + Ollama (localhost:11434)

环境配置：

# 1. 复制环境变量模板
cp .env.example .env

# 2. 编辑 .env 文件，填入你的 API 密钥等敏感信息
# 注意：.env 文件包含敏感信息，已在 .gitignore 中忽略

# 3. 安装依赖
pip install -r requirements.txt

启动应用：

python -m src.cli.run

访问: http://localhost:5000

目录结构（工程化）

comfyui/
├── .github/                    # GitHub 配置
│   ├── ISSUE_TEMPLATE/        # Issue 模板
│   │   ├── bug_report.md     # Bug 报告模板
│   │   └── feature_request.md # 功能请求模板
│   ├── PULL_REQUEST_TEMPLATE.md # PR 模板
│   └── workflows/             # GitHub Actions（待添加）
├── src/                        # 源代码目录
│   ├── app/                    # Flask 应用模块
│   │   ├── __init__.py        # 应用工厂
│   │   ├── config.py          # 应用配置
│   │   ├── extensions.py      # Flask 扩展
│   │   ├── routes/            # 路由蓝图
│   │   │   ├── api.py         # API 路由
│   │   │   └── web.py         # Web 路由
│   │   ├── services/          # 业务服务
│   │   │   └── generation.py # 图像生成服务
│   │   └── events/            # WebSocket 事件
│   │       └── generation.py  # 生成事件处理
│   ├── cli/                    # 命令行工具
│   │   ├── run.py             # 应用启动入口
│   │   ├── serve.py           # Flask 服务器
│   │   ├── check_import.py    # 导入验证工具
│   │   └── migrate_to_sqlite.py  # 数据迁移工具
│   ├── core/                   # 核心业务逻辑
│   │   ├── comfyui/           # ComfyUI 集成
│   │   │   └── client.py      # ComfyUI 客户端
│   │   ├── history/           # 历史记录管理
│   │   │   └── manager.py     # 历史记录管理器
│   │   └── prompt/            # 提示词生成
│   │       └── generator.py   # 提示词生成器
│   ├── legacy/                 # 向后兼容代码
│   ├── models/                 # 数据模型
│   ├── routes/                 # 路由模块（待迁移）
│   ├── services/               # 业务服务（待迁移）
│   │   └── prompt_service.py  # 提示词服务（单例）
│   ├── utils/                  # 工具函数
│   └── workers/                # 后台任务
├── config/                     # 配置文件
│   ├── workflows/             # ComfyUI 工作流
│   │   ├── flowv_normal.json # 普通文生图
│   │   └── flow_face.json    # 人脸替换
│   └── settings.py           # 全局配置类
├── templates/                  # Jinja2 模板
│   ├── layouts/               # 布局模板
│   │   └── base.html         # 基础布局
│   ├── partials/              # 组件模板
│   │   ├── gallery.html      # 图片画廊
│   │   ├── history_panel.html # 历史面板
│   │   └── ...               # 其他组件
│   └── index.html            # 主页
├── static/                     # 静态资源
│   ├── css/                   # 样式文件
│   │   └── index.css         # 主样式
│   ├── js/                    # JavaScript 文件
│   │   └── index.js          # 主逻辑
│   └── generated/             # 生成图片（旧，向后兼容）
├── data/                       # 数据目录
│   ├── generated/             # 生成的图片（不提交）
│   ├── upload/                # 上传的图片（不提交）
│   └── history.db             # SQLite 历史记录（不提交）
├── tests/                      # 测试文件
├── .env                        # 环境变量（不提交，敏感信息）
├── .env.example               # 环境变量模板
├── .gitignore                 # Git 忽略配置
├── requirements.txt           # Python 依赖
├── LICENSE                     # MIT 许可证
├── CHANGELOG.md               # 版本更新日志
├── CONTRIBUTING.md            # 贡献指南
├── CLAUDE.md                   # 项目技术文档（本文件）
├── README.md                   # 快速开始指南（用户文档）
└── AGENTS.md                   # AI 代理配置说明