docs: add PRD for Prompt Generator tool

PRD.md

@@ -0,0 +1,752 @@
+# 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.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 中的那段文字 |