139 lines
6.1 KiB
Markdown
139 lines
6.1 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
Prompt Generator 是一个面向 Coding Agent 的提示词构建与历史复盘工具，帮助开发者通过标签系统和片段模板组装高质量 Prompt。界面语言为中文。
|
||
|
||
## 常用命令
|
||
|
||
### 本地开发
|
||
```bash
|
||
# 配置环境变量（必须）
|
||
cp .env.example .env
|
||
# 编辑 .env 填入数据库和 LLM 配置
|
||
|
||
# 直接运行
|
||
go run .
|
||
|
||
# 构建二进制
|
||
go build -o server .
|
||
```
|
||
|
||
### Docker 部署
|
||
```bash
|
||
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 代理，适配中国网络环境。
|