prompt-generator/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

Prompt Generator 是一个面向 Coding Agent 的提示词构建与历史复盘工具，帮助开发者通过标签系统和片段模板组装高质量 Prompt。界面语言为中文。

常用命令

本地开发

# 配置环境变量（必须）
cp .env.example .env
# 编辑 .env 填入数据库和 LLM 配置

# 直接运行
go run .

# 构建二进制
go build -o server .

Docker 部署

docker compose up -d

测试

当前项目无测试文件（无 _test.go）。

架构概览

技术栈

• 前端: 原生 HTML + Tailwind CSS (CDN) + JavaScript，无构建步骤
• 后端: Go 1.24，标准库 net/http (使用 Go 1.22+ 方法路由 HandleFunc("METHOD /path", ...))
• 数据库: MySQL 8.0，使用 github.com/go-sql-driver/mysql
• 会话管理: github.com/gorilla/sessions (Cookie-based)
• LLM: 兼容 OpenAI Chat Completions API (默认 DeepSeek)

目录结构

main.go                     # 入口，加载配置、初始化数据库、启动 HTTP 服务
frontend/                   # 静态前端
  index.html                # Prompt 构建器（核心页面）
  dashboard.html            # 历史复盘看板
  settings.html             # 设置页（LLM配置、主题）
  static/common.js          # 全局 JS：API 客户端、认证、Toast、主题
  static/common.css         # 全局样式、暗色/亮色主题变量
internal/
  auth/middleware.go         # 会话认证中间件
  config/config.go           # 环境变量加载到 Config 结构体
  db/db.go                   # MySQL 初始化、Schema 自动迁移、种子数据、设置持久化
  handlers/                  # HTTP 处理器
    auth.go                  # 登录/登出/认证检查
    builder.go               # Builder Session CRUD + Prompt 组装逻辑
    claude.go                # Claude Session/Prompt 查询（只读 prompts 表）
    dashboard.go             # 仪表盘项目/会话/Prompt 聚合查询
    settings.go              # LLM 设置读写（持久化到数据库）
    snippets.go              # 片段 CRUD
    suggestions.go           # LLM 智能建议端点
    tags.go                  # 标签和标签选项 CRUD
  llm/client.go              # OpenAI 兼容 LLM 客户端
  models/models.go           # 所有数据模型（Go 结构体 + JSON 标签）

数据库表

应用管理的表（自动迁移创建）：

• tags - 标签定义（system 或 personal 作用域）
• tag_options - 标签下的选项（标签 + 约束文本）
• snippets - 可复用片段模板
• builder_sessions - 保存的 Prompt 构建会话
• builder_session_tags - 会话与标签选项的多对多关联
• builder_session_snippets - 会话与片段的多对多关联
• settings - LLM 配置键值存储

只读表（由外部 Hook 服务写入）：

• prompts - 历史 Claude Code Prompt 记录

API 路由

无需认证：

• POST /api/auth/login - 密码登录（返回会话 Cookie）
• POST /api/auth/logout - 销毁会话
• GET /api/auth/check - 检查认证状态

需要认证（通过 AuthMiddleware 包装）：

• 标签: GET/POST /api/tags, PUT/DELETE /api/tags/{id}, POST /api/tags/{id}/options, PUT/DELETE /api/tag-options/{id}
• 片段: GET/POST /api/snippets, PUT/DELETE /api/snippets/{id}
• Builder 会话: GET/POST /api/builder/sessions, GET/PUT/DELETE /api/builder/sessions/{id}
• Claude 会话: GET /api/claude/sessions, GET /api/claude/sessions/{session_id}/prompts, GET /api/claude/sessions/{session_id}/builder
• 仪表盘: GET /api/dashboard/projects, GET /api/dashboard/projects/{name}/sessions, GET /api/dashboard/prompts
• 建议: POST /api/suggestions
• 设置: GET/PUT /api/settings

前端架构

前端是多页应用（非 SPA），每个页面是独立的 HTML 文件：

• / -> frontend/index.html（Prompt 构建器）
• /dashboard -> frontend/dashboard.html（历史复盘）
• /settings -> frontend/settings.html（设置）

共享资源在 frontend/static/ 目录：

• common.js 提供 API（带认证处理的 fetch 封装）、Auth（登录弹窗、会话检查、登出）、Toast（通知）、Theme（暗色/亮色主题）、Draft（localStorage 自动保存）、debounce()、renderNavbar() 等全局模块
• common.css 提供主题 CSS 变量和通用样式

环境变量

变量	说明	默认值
SERVER_PORT	服务端口	8080
SESSION_SECRET	会话密钥	default-secret-change-me
DB_HOST	MySQL 地址	127.0.0.1
DB_PORT	MySQL 端口	3306
DB_USER	数据库用户	root
DB_PASSWORD	数据库密码	-
DB_NAME	数据库名	prompt_generator
AUTH_PASSWORD	访问密码	admin
LLM_API_BASE_URL	LLM API 地址	https://api.deepseek.com/v1
LLM_API_KEY	LLM API Key	-
LLM_MODEL_NAME	模型名称	deepseek-chat

关键实现细节

1. 路由机制: 使用 Go 1.22+ 的方法路由语法 mux.HandleFunc("METHOD /path", handler)，无需第三方路由库。

2. 认证流程: 单密码认证（无用户系统），通过 Cookie 会话管理。所有 /api/ 路由（除 auth 外）都通过 AuthMiddleware 保护。

3. 数据库迁移: 启动时自动执行 db.AutoMigrate() 创建表结构，db.SeedData() 插入初始系统标签和片段数据。

4. Prompt 组装: 前端将标签选项的约束文本、选中片段、自定义文本拼接成最终 Prompt，后端 builder.go 提供保存/加载功能。

5. LLM 集成: internal/llm/client.go 实现 OpenAI 兼容的 Chat Completions 调用，用于智能建议功能。设置持久化到数据库的 settings 表。

6. 端口配置: Dockerfile 暴露端口 8080，docker-compose 映射 8083:8083，.env 设置 SERVER_PORT=8083。本地开发默认 8080。

7. 部署优化: Dockerfile 使用阿里云 Alpine 镜像和 goproxy.cn Go 代理，适配中国网络环境。