prompt-generator/PRD.md

# PRD：Prompt Generator — Coding Agent 提示词构建 & 复盘工具

> 版本：v1.0 | 最后更新：2026-06-26

---

## 1. 产品概述

### 1.1 产品名称

Prompt Generator

### 1.2 一句话描述

面向团队的 Coding Agent 提示词构建与历史复盘工具，帮助用户通过标签、片段、模板快速组装高质量 Prompt，并可回溯历史会话进行优化迭代。

### 1.3 目标用户

- 团队内部开发人员，日常使用 Claude Code 等 Coding Agent 进行开发
- 需要系统化管理、复用、优化 Prompt 的工程师

### 1.4 核心价值

| 痛点 | 解决方案 |
|------|----------|
| 每次写 Prompt 重复劳动，遗漏关键约束 | 标签系统 + 片段模板，一键组装 |
| 不确定 Prompt 缺什么 | LLM 智能分析，推荐补充项 |
| 无法回顾历史 Prompt 的效果 | 按项目/会话结构化复盘看板 |
| 团队内 Prompt 经验无法共享 | 系统级标签和片段库，团队共享 |

---

## 2. 系统架构

### 2.1 技术栈

| 层 | 技术选型 |
|----|----------|
| 前端 | 纯 HTML + Tailwind CSS + 原生 JavaScript（无框架） |
| 后端 | Go（标准库 + 轻量路由） |
| 数据库 | MySQL 8.0（已有实例，共用） |
| LLM | 兼容 OpenAI 接口，默认 DeepSeek endpoint |
| 部署 | Docker Compose |

**前端构建说明**：
- 无 Node.js 构建流程，Tailwind CSS 使用 CDN 引入（`<script src="https://cdn.tailwindcss.com">`）
- 前端为纯静态文件，由 Go 后端直接 serve（`http.FileServer`）
- 目录结构：`frontend/` 下按页面组织（`index.html`, `dashboard.html`, `settings.html`），共享 `common.js` 和 `common.css`

### 2.2 架构图

```
┌─────────────────────────────────────────────────┐
│                   浏览器 (桌面端)                  │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ Prompt   │ │ 复盘看板  │ │     设置页       │ │
│  │ 构建器   │ │          │ │ (密码/LLM/主题)  │ │
│  └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
└───────┼────────────┼────────────────┼────────────┘
        │            │                │
        ▼            ▼                ▼
┌─────────────────────────────────────────────────┐
│              Go API Server (:8080)                │
│  ┌──────────┐ ┌──────────┐ ┌──────────────────┐ │
│  │ 构建 API │ │ 看板 API │ │ 智能建议 API     │ │
│  │          │ │          │ │ (调用 LLM)       │ │
│  └────┬─────┘ └────┬─────┘ └────────┬─────────┘ │
└───────┼────────────┼────────────────┼────────────┘
        │            │                │
        ▼            ▼                ▼
   ┌─────────┐  ┌─────────┐   ┌─────────────┐
   │ MySQL   │  │ MySQL   │   │ LLM API     │
   │ 读写新表 │  │ 只读旧表 │   │ (DeepSeek)  │
   └─────────┘  └─────────┘   └─────────────┘
```

### 2.3 数据库设计

#### 现有表（只读，禁止修改结构和数据）

```sql
-- 已存在的表，由外部 Hook 服务写入
-- 本工具仅 SELECT 查询
CREATE TABLE `prompts` (
    `id` bigint NOT NULL AUTO_INCREMENT,
    `session_id` varchar(128) NOT NULL,
    `project_name` varchar(255) NOT NULL DEFAULT '',
    `prompt` text NOT NULL,
    `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    KEY `idx_session_id` (`session_id`),
    KEY `idx_project_name` (`project_name`),
    KEY `idx_created_at` (`created_at`)
);
```

#### 新增表

> **迁移策略**：新表通过 Go 后端启动时自动检查并创建（`CREATE TABLE IF NOT EXISTS`）。
> 对已存在的 `prompts` 表不做任何 DDL 操作，仅 SELECT 查询。

```sql
-- 标签定义表
CREATE TABLE `tags` (
    `id` bigint NOT NULL AUTO_INCREMENT,
    `name` varchar(64) NOT NULL COMMENT '标签名称，如 Git规范',
    `description` varchar(255) NOT NULL DEFAULT '' COMMENT '标签说明',
    `scope` enum('system', 'personal') NOT NULL DEFAULT 'system' COMMENT 'system=系统预设, personal=用户自建',
    `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    KEY `idx_scope` (`scope`)
);

-- 标签选项表（每个标签下的枚举值）
CREATE TABLE `tag_options` (
    `id` bigint NOT NULL AUTO_INCREMENT,
    `tag_id` bigint NOT NULL,
    `label` varchar(128) NOT NULL COMMENT '选项显示名称',
    `constraint_text` text NOT NULL COMMENT '选中后注入到 Prompt 的约束文本',
    `sort_order` int NOT NULL DEFAULT 0,
    `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    KEY `idx_tag_id` (`tag_id`)
);

-- 片段模板表
CREATE TABLE `snippets` (
    `id` bigint NOT NULL AUTO_INCREMENT,
    `name` varchar(128) NOT NULL COMMENT '片段名称',
    `content` text NOT NULL COMMENT '片段内容（纯静态文本）',
    `category` varchar(64) NOT NULL DEFAULT '' COMMENT '分类',
    `scope` enum('system', 'personal') NOT NULL DEFAULT 'system',
    `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    KEY `idx_scope` (`scope`)
);

-- 构建会话表（用户在工具中的操作会话）
CREATE TABLE `builder_sessions` (
    `id` bigint NOT NULL AUTO_INCREMENT,
    `title` varchar(255) NOT NULL DEFAULT '' COMMENT '会话标题',
    `project_name` varchar(255) NOT NULL DEFAULT '' COMMENT '关联项目名',
    `final_prompt` text COMMENT '最终生成的 Prompt 全文',
    `claude_session_id` varchar(128) DEFAULT NULL COMMENT '可选：关联的 Claude Code session_id',
    `created_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP,
    `updated_at` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    PRIMARY KEY (`id`),
    KEY `idx_project_name` (`project_name`),
    KEY `idx_claude_session_id` (`claude_session_id`)
);

-- 构建会话与标签选项的关联
CREATE TABLE `builder_session_tags` (
    `id` bigint NOT NULL AUTO_INCREMENT,
    `builder_session_id` bigint NOT NULL,
    `tag_id` bigint NOT NULL,
    `tag_option_id` bigint NOT NULL,
    PRIMARY KEY (`id`),
    KEY `idx_session_id` (`builder_session_id`)
);

-- 构建会话与片段的关联
CREATE TABLE `builder_session_snippets` (
    `id` bigint NOT NULL AUTO_INCREMENT,
    `builder_session_id` bigint NOT NULL,
    `snippet_id` bigint NOT NULL,
    `sort_order` int NOT NULL DEFAULT 0,
    PRIMARY KEY (`id`),
    KEY `idx_session_id` (`builder_session_id`)
);
```

#### ER 关系

```
tags 1──N tag_options
tags N──M builder_sessions (via builder_session_tags)
snippets N──M builder_sessions (via builder_session_snippets)
builder_sessions N──1 prompts (via claude_session_id, 可选关联)
```

### 2.4 API 设计

#### 统一响应格式

```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

错误时 `code` 非 0，`message` 包含错误描述。

#### API 端点清单

| 方法 | 路径 | 说明 |
|------|------|------|
| **认证** | | |
| POST | `/api/auth/login` | 密码验证，成功返回 Session Cookie |
| POST | `/api/auth/logout` | 注销 |
| GET | `/api/auth/check` | 检查当前认证状态 |
| **标签** | | |
| GET | `/api/tags` | 获取所有标签及其选项（系统+当前用户个人） |
| POST | `/api/tags` | 创建个人标签 |
| PUT | `/api/tags/:id` | 更新个人标签 |
| DELETE | `/api/tags/:id` | 删除个人标签（仅限 personal） |
| POST | `/api/tags/:id/options` | 为标签新增选项 |
| PUT | `/api/tag-options/:id` | 更新标签选项 |
| DELETE | `/api/tag-options/:id` | 删除标签选项 |
| **片段** | | |
| GET | `/api/snippets` | 获取所有片段（系统+当前用户个人），支持 `?category=` 筛选 |
| POST | `/api/snippets` | 创建个人片段 |
| PUT | `/api/snippets/:id` | 更新个人片段 |
| DELETE | `/api/snippets/:id` | 删除个人片段（仅限 personal） |
| **构建会话** | | |
| GET | `/api/builder/sessions` | 获取构建会话列表 |
| POST | `/api/builder/sessions` | 创建/保存构建会话 |
| GET | `/api/builder/sessions/:id` | 获取构建会话详情（含标签、片段关联） |
| PUT | `/api/builder/sessions/:id` | 更新构建会话 |
| DELETE | `/api/builder/sessions/:id` | 删除构建会话 |
| **Claude Sessions（只读）** | | |
| GET | `/api/claude/sessions?project_name=` | 按项目查询不重复的 session_id 列表 |
| GET | `/api/claude/sessions/:session_id/prompts` | 查询指定 session 的最近 N 条 Prompt |
| **复盘看板** | | |
| GET | `/api/dashboard/projects` | 获取所有项目列表（从 prompts 表聚合） |
| GET | `/api/dashboard/projects/:name/sessions` | 获取项目下的 session 列表 |
| GET | `/api/dashboard/prompts?session_id=` | 获取 session 下的 Prompt 列表（分页） |
| **智能建议** | | |
| POST | `/api/suggestions` | 发送 Prompt + CLAUDE.md，获取 LLM 建议列表 |
| **设置** | | |
| GET | `/api/settings` | 获取当前配置（LLM 模型名等，不含 Key） |
| PUT | `/api/settings` | 更新 LLM 配置 |

---

## 3. 功能模块

### 3.1 Prompt 构建器（优先级 P0）

#### 3.1.1 页面布局

```
┌─────────────────────────────────────────────────────────┐
│ [Logo] Prompt Generator    [构建器] [复盘看板] [设置]    │ ← 顶部 Tab 导航
├────────────────────────┬────────────────────────────────┤
│                        │                                │
│   左侧面板（配置区）    │   右侧面板（预览区）            │
│                        │                                │
│   ┌─ 项目/会话 ──────┐ │   ┌─ 最终 Prompt 预览 ────────┐│
│   │ 项目名: [______] │ │   │                          ││
│   │ Claude Session:  │ │   │  [系统提示]               ││
│   │   [选择/不关联]   │ │   │                          ││
│   └──────────────────┘ │   │  [标签约束区]             ││
│                        │   │  - Git 规范: xxx          ││
│   ┌─ 标签选择 ──────┐ │   │  - 环境: xxx              ││
│   │ ☑ Git规范       │ │   │                          ││
│   │   ▼ 标准commit  │ │   │  [片段内容区]             ││
│   │ ☐ 环境背景      │ │   │  ...片段文本...            ││
│   │ ☐ 工具约束      │ │   │                          ││
│   │ ☐ 提交策略      │ │   │  [用户自定义内容]         ││
│   │ ...更多标签      │ │   │                          ││
│   └──────────────────┘ │   └──────────────────────────┘│
│                        │                                │
│   ┌─ 片段选择 ──────┐ │   [复制到剪贴板]  [智能建议]   │
│   │ ☑ 架构说明      │ │                                │
│   │ ☐ 测试要求      │ │   ┌─ 智能建议区（触发后出现）──┐│
│   │ ☐ 自建片段...   │ │   │ ☑ 建议1: 补充错误处理约束  ││
│   └──────────────────┘ │   │ ☐ 建议2: 添加性能要求      ││
│                        │   │ ☑ 建议3: 添加代码风格约束  ││
│   ┌─ 自定义输入 ────┐ │   └──────────────────────────┘│
│   │ [自由文本区域]   │ │                                │
│   └──────────────────┘ │                                │
│                        │                                │
└────────────────────────┴────────────────────────────────┘
```

#### 3.1.2 标签系统

**标签结构**：每个标签 = 名称 + 描述 + 多个单选枚举选项，每个选项 = 显示名 + 注入的约束文本。

**标签层级**：
- **系统标签**（system）：预置，所有用户可见，不可编辑
- **个人标签**（personal）：用户自建，仅自己可见

**标签选择交互**：
- 标签默认折叠，仅显示标签名称和勾选框
- 点击展开后显示该标签下的所有选项（单选 radio）
- 未勾选的标签不展开，不占用空间
- 系统标签和个人标签分两个区域展示，个人标签区域支持"新增标签"按钮
- 标签支持搜索/过滤（当标签数量较多时）

**预设系统标签（不少于 10 个）**：

| # | 标签名 | 选项示例 | 说明 |
|---|--------|----------|------|
| 1 | Git 规范 | ① 标准 commit，禁止 push ② 标准 commit，允许 push ③ 仅允许 commit，禁止 merge/rebase | 控制 Git 操作范围 |
| 2 | 环境背景 | ① 服务端环境（Linux 生产） ② 本地开发环境 ③ CI/CD 环境 ④ 测试环境 | 提供运行环境上下文 |
| 3 | 工具约束 | ① 必须使用 AskUserQuestion 提问 ② 优先使用专用工具而非 shell ③ 禁止使用 Agent 工具 | 限制可用工具 |
| 4 | 提交策略 | ① 每完成一个小任务 commit 一次 ② 全部完成后一次性 commit ③ 按功能模块分别 commit | 控制提交粒度 |
| 5 | 阅读策略 | ① 先读 docs/ 了解架构再读代码 ② 直接读代码 ③ 先读 README 和 CLAUDE.md | 信息获取顺序 |
| 6 | 输出格式 | ① Markdown ② JSON ③ 纯文本 ④ 代码块优先 | 约束输出格式 |
| 7 | 安全约束 | ① 禁止访问外部网络 ② 禁止修改系统文件 ③ 禁止执行危险命令 | 安全边界 |
| 8 | 代码风格 | ① 遵循项目现有风格 ② 严格 ESLint/Prettier ③ 自由风格 | 代码规范 |
| 9 | 测试要求 | ① 必须编写单元测试 ② 仅手动验证 ③ TDD 方式 | 测试策略 |
| 10 | 错误处理 | ① 遇到不确定先问用户 ② 尽可能自行判断 ③ 遇错停止等待指示 | 异常行为 |
| 11 | 上下文策略 | ① 节约上下文，精简输出 ② 详细输出，不省略 ③ 平衡模式 | Token 使用策略 |
| 12 | 工作模式 | ① 规划优先，先出方案再执行 ② 直接执行，边做边调 ③ 探索模式，先研究再动手 | 工作风格 |

#### 3.1.3 片段系统

**片段结构**：名称 + 分类 + 纯静态文本内容。

**片段层级**：
- **系统片段**（system）：预置模板
- **个人片段**（personal）：用户自建

**组合方式**：模板嵌入 — 各片段按用户选择的顺序，嵌入到 Prompt 的对应区域。

**预设系统片段示例**：
- 项目架构概述
- 技术栈说明
- 目录结构描述
- 编码规范要求
- 测试框架配置
- 部署流程说明
- PR 规范
- Code Review 要点

**片段选择交互**：
- 片段按分类（category）分组展示，使用可折叠的分组标题
- 每个片段显示名称和内容预览（前 50 字符，hover 显示完整内容）
- 支持搜索：输入关键词实时过滤片段列表
- 已选片段显示在右侧预览区，并保持选择顺序
- 用户可拖拽调整已选片段的顺序（nice-to-have，v1.0 可省略）

#### 3.1.4 操作流程

```
用户打开构建器
  → 输入项目名（可选）
  → 选择是否关联 Claude Code Session（可选）
  → 勾选标签并选择各标签下的选项
  → 选择需要的片段
  → 在自定义输入区补充自由文本（可选）
  → 右侧实时预览最终 Prompt
  → 点击 [智能建议] → LLM 分析当前 Prompt → 展示建议列表 → 勾选采纳
  → 点击 [复制到剪贴板]
  → 粘贴到 Claude Code 使用
```

#### 3.1.6 草稿自动保存

- 构建器的当前状态（标签选择、片段选择、自定义输入）自动保存到浏览器 localStorage
- 防抖保存：用户操作停止 1 秒后自动写入
- 用户再次打开构建器时，自动恢复上次的草稿状态
- 提供"清空重置"按钮，清除草稿并恢复默认状态
- 保存到后端（builder_sessions）为手动操作，需用户点击"保存"按钮

#### 3.1.5 Prompt 组装结构

最终 Prompt 按以下顺序拼接：

```
┌──────────────────────────────┐
│ [项目上下文]                  │  ← 项目名 + Claude Session 历史（如有）
├──────────────────────────────┤
│ [用户自定义内容]              │  ← 用户在自定义输入区填写的内容
├──────────────────────────────┤
│ [标签约束区]                  │  ← 各标签选项的 constraint_text
│ - Git 规范: ...              │
│ - 环境背景: ...              │
│ - 工具约束: ...              │
├──────────────────────────────┤
│ [片段内容区]                  │  ← 所选片段按顺序拼接
│ --- 片段: 架构说明 ---        │
│ ...                          │
│ --- 片段: 编码规范 ---        │
│ ...                          │
├──────────────────────────────┤
│ [智能建议补充]                │  ← 用户采纳的 LLM 建议
└──────────────────────────────┘
```

---

### 3.2 历史复盘看板（优先级 P1）

#### 3.2.1 数据层级

```
项目 (project_name)
  └── 会话 (session_id)
        └── 具体 Prompt (prompts 表记录)
```

#### 3.2.2 页面布局

```
┌─────────────────────────────────────────────────────────┐
│ [Logo] Prompt Generator    [构建器] [复盘看板] [设置]    │
├──────────────┬──────────────────────────────────────────┤
│              │                                          │
│  左侧项目树  │   右侧内容区                              │
│              │                                          │
│  ▼ 项目A     │   会话: sess_abc123  (2026-06-25)        │
│    ▼ 会话1   │   ┌──────────────────────────────────┐   │
│      Prompt1 │   │ [文本视图]  [结构视图]  ← 切换   │   │
│      Prompt2 │   │                                  │   │
│    ▼ 会话2   │   │ 文本视图:                        │   │
│      Prompt3 │   │   原始 Prompt 全文                │   │
│  ▼ 项目B     │   │                                  │   │
│    ▼ 会话3   │   │ 结构视图:                        │   │
│      ...     │   │   标签: Git规范=标准commit        │   │
│              │   │   片段: 架构说明, 编码规范        │   │
│              │   │   自定义: ...                     │   │
│              │   └──────────────────────────────────┘   │
│              │                                          │
│              │   [导出 Markdown] [导出 JSON] [导出文本]  │
│              │                                          │
└──────────────┴──────────────────────────────────────────┘
```

#### 3.2.3 核心功能

- **按项目分组**：左侧树形结构，项目 → 会话 → Prompt
- **时间线浏览**：会话按时间倒序排列
- **双视图切换**：
  - 文本视图：显示原始 Prompt 全文
  - 结构视图：还原当时的标签选择和片段构成（需从 `builder_session_tags` 和 `builder_session_snippets` 表读取）
- **导出**：支持 Markdown / JSON / 纯文本三种格式
- **分页**：Prompt 列表默认每页 20 条，支持加载更多或翻页
- **搜索**：支持按 Prompt 内容关键词搜索（在 prompts 表的 prompt 字段上 LIKE 查询）

#### 3.2.4 Prompt 内容渲染

`prompts` 表的 `prompt` 字段中会混入 IDE 和系统自动注入的 XML 标签（如 `<ide_opened_file>`、`<system-reminder>`、`<gitStatus>` 等）。这些内容直接展示会影响阅读体验，需要做折叠处理。

**渲染规则**：

- 识别 prompt 中所有 XML 标签包裹的内容块
- 所有系统注入的标签块统一折叠，只显示一个可点击的展开行（显示标签名称）
- 用户点击后展开查看完整内容，再次点击收起
- 用户实际输入的文本正常展示，保留原始格式

**渲染示例**：

```
┌──────────────────────────────────────────────────┐
│ ▶ ide_opened_file                                 │
├──────────────────────────────────────────────────┤
│                                                   │
│ 我感觉信息都挺全面的，不过你可以自己检查一下，     │
│ 有没有什么遗漏                                    │
│                                                   │
├──────────────────────────────────────────────────┤
▶ system-reminder                                   │
├──────────────────────────────────────────────────┤
▶ gitStatus                                         │
└──────────────────────────────────────────────────┘
```

**列表预览**：在 Prompt 列表中显示截断预览时，自动跳过 XML 标签内容，只提取用户实际输入的文本作为预览摘要（前 150 字符）。

---

### 3.3 智能建议（优先级 P2）

#### 3.3.1 触发方式

用户在构建器中完成 Prompt 组装后，点击 [智能建议] 按钮触发。

#### 3.3.2 工作流程

```
用户点击 [智能建议]
  → 前端将当前 Prompt 全文 + 可选的 CLAUDE.md 内容发送到后端
  → 后端调用 LLM API，Prompt 如下：

    "你是一个 Prompt 工程专家。用户正在构建一个用于 Coding Agent 的 Prompt。
    当前 Prompt 内容如下：
    ---
    {current_prompt}
    ---
    用户的 CLAUDE.md 内容（如有）：
    ---
    {claude_md_content}
    ---
    请分析当前 Prompt，找出缺失的关键约束或可以改进的地方。
    以 JSON 数组返回建议，每条建议包含：
    - title: 建议标题
    - description: 详细说明
    - constraint_text: 建议注入的约束文本"

  → LLM 返回建议列表
  → 前端以列表+勾选框展示
  → 用户勾选采纳的建议
  → 采纳的 constraint_text 追加到 Prompt 的 [智能建议补充] 区域
```

#### 3.3.3 UI 交互

- 建议以列表形式展示，每条包含标题和描述
- 用户逐条勾选，勾选后实时更新右侧 Prompt 预览
- 支持全选/全不选
- 建议可忽略，不影响已有 Prompt

#### 3.3.4 LLM 调用异常处理

| 异常场景 | 处理方式 |
|----------|----------|
| API 超时（默认 30s） | 前端展示"请求超时，请重试"，按钮恢复可点击 |
| API 返回错误（4xx/5xx） | 展示具体错误信息（如余额不足、Key 无效等） |
| 返回内容非 JSON 格式 | 展示"AI 返回格式异常，请重试"，后端记录原始响应 |
| 网络断开 | 前端捕获 fetch 错误，展示"网络异常" |

- 后端设置 LLM 调用超时：30 秒
- 前端在等待期间展示 loading 状态（骨架屏或 spinner）
- 按钮在请求期间禁用，防止重复提交

---

### 3.4 CLAUDE.md 联动（优先级 P3）

#### 3.4.1 功能说明

CLAUDE.md 是 Claude Code 每个 Session 自动读取的项目配置文件。本功能允许用户手动粘贴 CLAUDE.md 内容，作为智能建议的参考上下文。

#### 3.4.2 交互方式

- 构建器中提供一个可展开的文本区域，标题为 "CLAUDE.md 内容（可选）"
- 用户粘贴 CLAUDE.md 的内容
- 点击 [智能建议] 时，该内容会一并发送给 LLM 分析
- LLM 会对比 CLAUDE.md 中已有的约束，建议 Prompt 中缺失的部分

#### 3.4.3 注意事项

- CLAUDE.md 内容**不会**注入到最终 Prompt 中（因为它已由 Claude Code 自动加载）
- 仅作为 LLM 分析的参考，用于发现 Prompt 中遗漏的约束

---

### 3.5 Claude Session 关联（补充说明）

#### 3.5.1 数据来源

Claude Code 的 Session 数据存储在已有 `prompts` 表中，由外部 Hook 服务写入。本工具对该表**只读**。

#### 3.5.2 构建器中的 Session 选择流程

```
用户输入项目名
  → 后端查询 prompts 表，返回该项目下不重复的 session_id 列表（按 created_at 倒序）
  → 前端展示为下拉选择器，格式："{session_id 前8位}... ({Prompt数量}条, {最近时间})"
  → 用户选择一个 session（或选择"不关联"）
  → 后端查询该 session 下最近 N 条（默认 10 条）Prompt 记录
  → 前端在"项目上下文"区域展示这些历史 Prompt 作为参考（折叠式，可展开查看）
```

#### 3.5.3 历史 Prompt 参考区的展示

- 位于构建器左侧面板顶部的"项目/会话"区域内
- 以折叠列表形式展示，每条显示：时间 + Prompt 前 100 字符（截断）
- 点击可展开查看完整 Prompt 全文
- 该区域**仅作参考**，内容不会自动注入到最终 Prompt 中
- 用户可手动将有用的内容复制到"自定义输入区"

#### 3.5.4 复盘看板中的 Session 关联

- 复盘看板中，如果某条 Prompt 的 session_id 与 `builder_sessions` 中的 `claude_session_id` 匹配
- 则在该 Prompt 旁显示关联标记，点击可跳转查看对应的构建会话详情（标签构成、片段选择等）

---

## 4. 认证与权限

### 4.1 认证方式

- 访问网站时弹出密码输入弹窗
- 输入正确密码后，通过 Session Cookie 维持登录态
- 密码在服务端 `.env` 文件中配置

### 4.2 权限模型

- 单用户模式，密码仅用于隐私保护，无多用户隔离

---

## 5. LLM 集成

### 5.1 接口规范

- 使用兼容 OpenAI Chat Completions API 的接口
- 默认 endpoint：DeepSeek API
- 可在 `.env` 中配置：

```env
LLM_API_BASE_URL=https://api.deepseek.com/v1
LLM_API_KEY=sk-xxx
LLM_MODEL_NAME=deepseek-chat
```

### 5.2 模型切换

- 设置页面提供模型配置区域
- 支持填写自定义 API Base URL、API Key、模型名称
- 配置保存在服务端，前端不暴露 Key

### 5.3 调用场景

| 场景 | 触发方式 | 输入 | 输出 |
|------|----------|------|------|
| 智能建议 | 用户点击按钮 | 当前 Prompt + CLAUDE.md | 建议列表 JSON |

---

## 6. 页面与导航

### 6.1 页面清单

| 页面 | 路由 | 说明 |
|------|------|------|
| Prompt 构建器 | `/` (默认页) | 核心功能页 |
| 复盘看板 | `/dashboard` | 历史 Prompt 浏览 |
| 设置 | `/settings` | 密码修改、LLM 配置、主题切换 |

### 6.2 导航方式

- 顶部 Tab 栏切换页面
- 未认证时所有页面重定向到密码弹窗

### 6.3 主题

- 支持亮色 / 暗色主题切换
- 默认跟随系统偏好
- 切换状态保存在 localStorage

---

## 7. 部署方案

### 7.1 Docker Compose 结构

```yaml
services:
  app:
    build: .
    ports:
      - "8080:8080"
    env_file: .env

# MySQL 为已有的远程实例，通过公网 IP 连接
# 在 .env 中配置 DB_HOST 为远程 MySQL 地址
```

### 7.2 环境变量 (.env)

```env
# 服务配置
SERVER_PORT=8080
SESSION_SECRET=your-random-secret-key

# 数据库（连接已有的远程 MySQL 实例）
DB_HOST=your-mysql-public-ip
DB_PORT=3306
DB_USER=your-db-user
DB_PASSWORD=your-db-password
DB_NAME=prompt_generator

# 认证
AUTH_PASSWORD=your-access-password

# LLM
LLM_API_BASE_URL=https://api.deepseek.com/v1
LLM_API_KEY=sk-xxx
LLM_MODEL_NAME=deepseek-chat
```

---

## 8. 开发优先级与排期

### Phase 1：Prompt 构建器（P0）

- [ ] 数据库新表创建（tags, tag_options, snippets, builder_sessions, builder_session_tags, builder_session_snippets）
- [ ] Go 后端：标签 CRUD API
- [ ] Go 后端：片段 CRUD API
- [ ] Go 后端：构建会话 API（保存/读取）
- [ ] Go 后端：Prompt 组装逻辑
- [ ] 前端：构建器页面（左右分栏布局）
- [ ] 前端：标签选择交互（展开/折叠、单选枚举）
- [ ] 前端：片段选择交互
- [ ] 前端：Prompt 实时预览
- [ ] 前端：一键复制到剪贴板
- [ ] 预设系统标签数据初始化（≥12 个）
- [ ] 预设系统片段数据初始化（≥8 个）

### Phase 2：历史复盘看板（P1）

- [ ] Go 后端：按项目/会话查询 prompts 表（只读）
- [ ] Go 后端：关联查询 builder_sessions 还原标签构成
- [ ] 前端：左侧项目树
- [ ] 前端：右侧双视图（文本 / 结构）
- [ ] 前端：导出功能（Markdown / JSON / 纯文本）

### Phase 3：智能建议（P2）

- [ ] Go 后端：LLM API 调用封装
- [ ] Go 后端：智能建议 API（接收 Prompt + CLAUDE.md，返回建议列表）
- [ ] 前端：建议列表 UI + 勾选交互
- [ ] 前端：采纳建议后实时更新 Prompt 预览

### Phase 4：CLAUDE.md 联动（P3）

- [ ] 前端：CLAUDE.md 粘贴区域
- [ ] 前端：与智能建议联动（传入 LLM 分析）

### Phase 5：基础设施

- [ ] 认证：密码弹窗 + Session Cookie
- [ ] 设置页面：LLM 配置、主题切换
- [ ] Docker Compose 部署配置
- [ ] 亮色/暗色主题实现

---

## 9. 非功能需求

| 维度 | 要求 |
|------|------|
| 语言 | 中文界面 |
| 适配 | 仅桌面端浏览器（≥1280px 宽度） |
| 主题 | 亮色 / 暗色切换 |
| 性能 | 页面加载 < 2s，Prompt 预览实时更新 < 100ms |
| 安全 | 密码不明文传输（bcrypt 或 HTTPS），API Key 仅存服务端 |
| 兼容 | Chrome / Firefox / Edge 最新两个大版本 |

---

## 10. 边界与约束

### 10.1 做什么

- Prompt 构建、组装、预览、复制
- 历史 Prompt 按项目/会话浏览和导出
- LLM 驱动的智能建议
- CLAUDE.md 作为分析参考

### 10.2 不做什么（v1.0）

- ~~Prompt 评分/标注~~
- ~~Prompt 导入~~
- ~~移动端适配~~
- ~~多用户认证/权限隔离~~
- ~~Prompt 直接发送到 Claude Code~~
- ~~实时双向同步 Claude Code Session~~

---

## 11. 附录

### 11.1 prompts 表字段说明

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 自增主键 |
| session_id | varchar(128) | Claude Code 会话 ID |
| project_name | varchar(255) | 项目名称 |
| prompt | text | 用户发送的 Prompt 原文 |
| created_at | datetime | 创建时间 |

### 11.2 术语表

| 术语 | 含义 |
|------|------|
| 标签 (Tag) | 一类约束的容器，下含多个单选枚举选项 |
| 标签选项 (Tag Option) | 标签下的具体选择，选中后注入对应的约束文本 |
| 片段 (Snippet) | 一段预定义的静态文本模板，可被选择并嵌入 Prompt |
| 构建会话 (Builder Session) | 用户在工具中的一次 Prompt 构建操作记录 |
| Claude Session | Claude Code 中的一次对话会话，由外部 Hook 记录到 prompts 表 |
| 约束文本 (Constraint Text) | 标签选项被选中后，实际注入到 Prompt 中的那段文字 |