name: vibe-chat-history description: > This skill should be used when the user asks about "vibe history", "chat history persistence", "vibe chat database", "ChatStore biz_type", "cc_sessions biz_type", "cc_chat_messages biz_type", "vibe MySQL", "vibe session save", "/api/vibe/sessions", "VibeHistory component", "handleVibeSessions", "handleVibeSessionMessages", "ListSessions", "GetMessages", "chat history sidebar", "load history session", "continue conversation from history", "vibe chatstore integration", "webuiSession chatStore", "chatStore is nil", "MySQL DSN format", "mysql driver log", "slogWriter", "chatstore log", "database operation log", "vite proxy /api/vibe", "404 api vibe sessions", "unified history", "IM history in vibe", "listAllSessionsSQL", "biz_type filter", "history includes IM", "history source tag", or needs to debug, extend, or understand how Vibe Coding chat messages are persisted to MySQL and loaded as browsable history in the frontend.

Vibe Coding Chat History Persistence

Purpose

Document how Vibe Coding chat messages are persisted to MySQL via the shared ChatStore infrastructure and how the frontend provides browsable/resumable chat history. This is a reference for extending chat persistence to other business types or adding new query patterns.

Core Design: Reuse ChatStore + biz_type 区分

不新建表。Vibe Coding 复用现有 cc_sessions + cc_chat_messages 表， 通过 biz_type 字段区分来源：

表结构变更

两张表各新增一列：

ALTER TABLE cc_sessions ADD COLUMN biz_type VARCHAR(32) NOT NULL DEFAULT 'im'
  COMMENT '业务类型: im=IM平台, vibe=Vibe Coding';

ALTER TABLE cc_chat_messages ADD COLUMN biz_type VARCHAR(32) NOT NULL DEFAULT 'im'
  COMMENT '业务类型: im=IM平台, vibe=Vibe Coding';

• DEFAULT 'im' 确保旧数据自动标记为 IM，完全向后兼容
• 升级逻辑在 NewMySQLChatStore() 中执行 ALTER（Duplicate column 错误静默忽略）
• 新表建表 DDL 已包含 biz_type 列和索引

Data Flow

写入路径（实时）

Browser WebSocket → webui.go handleVibeWS()
  ├─ "start" message → chatStore.EnsureSession(BizType:"vibe")
  ├─ "send" message  → chatStore.SaveMessage(Role:"user", BizType:"vibe")
  └─ parseEvent("result") → chatStore.SaveMessage(Role:"assistant", BizType:"vibe")
      └─ 同时 EnsureSession 更新 agent_session_id

读取路径（历史浏览）

Frontend VibeHistory 面板
  → GET /api/vibe/sessions?limit=50
    → WebUIServer.handleVibeSessions()
      → chatStore.ListSessions("vibe", 50)
        → SELECT ... FROM cc_sessions WHERE biz_type='vibe' ORDER BY updated_at DESC

  → GET /api/vibe/sessions/{id}/messages?limit=200
    → WebUIServer.handleVibeSessionMessages()
      → chatStore.GetMessages(sessionID, 200)
        → SELECT ... FROM cc_chat_messages WHERE session_id=? ORDER BY created_at ASC

导出路径（Markdown 下载）

Frontend (Active Tab 或 History Panel)
  → POST /api/vibe/export (JSON: metadata + messages[])
    → WebUIServer.handleVibeExportMarkdown()
      → buildExportMarkdown() → Markdown string
      → Content-Disposition: attachment → browser downloads .md file

History Panel 导出时会先调用 getVibeMessages() 获取消息，再 POST 到导出端点。 Active Tab 导出时直接使用内存中的 tab.messages（含 tool_use 等富信息）。 详见 webui-export-markdown skill。

File Map

ChatStore Interface

type ChatStore interface {
    // 写入（异步，非阻塞）
    SaveMessage(ctx context.Context, msg ChatMessage)
    EnsureSession(ctx context.Context, info ChatSessionInfo)

    // 读取（同步，返回结果）
    ListSessions(ctx context.Context, bizType string, limit int) ([]ChatSessionRecord, error)
    GetMessages(ctx context.Context, sessionID string, limit int) ([]ChatMessageRecord, error)

    Close() error
}

Vibe Session ID 约定

• 格式：vibe-{UnixNano} (如 vibe-1711468800000000000)
• 每次 WebSocket "start" 消息创建新 ID
• session_key 格式：vibe:{workDir} (如 vibe:/Users/ywwl/project-a)

Frontend Architecture

VibeHistory 侧边面板

┌─ VibeCoding 容器 ──────────────────────────────────┐
│ [Tab 栏]                              [历史记录 📋] │ ← 点击打开侧边面板
│ ┌─ VibeSession ─────────────────────┐              │
│ │ 聊天 UI                           │              │
│ └───────────────────────────────────┘              │
└────────────────────────────────────────────────────┘

点击"历史记录"后：
┌──────────────────────────────┬─── VibeHistory ──┐
│       当前聊天界面            │ 📋 历史记录      │
│                              │ ───────────────  │
│                              │ [项目A]  2m ago  │
│                              │  最后一条消息...  │
│                              │ [项目B]  1h ago  │
│                              │  最后一条消息...  │
│                              │ [项目C]  3d ago  │
└──────────────────────────────┴──────────────────┘

加载历史流程

1. 用户点击历史会话 → getVibeMessages(sessionId) 获取消息
2. 创建新 Tab，messages 设为历史消息，workDir 设为项目路径
3. 用户可只读浏览历史
4. 用户可点击"启动"按钮重新连接 WebSocket 继续对话

举一反三：添加新的 biz_type

当需要为其他业务场景（如 API 调用、定时任务）添加聊天持久化时：

1. 定义新 biz_type 常量：如 "api", "cron", "webhook"
2. 写入时设置 BizType：在调用 SaveMessage/EnsureSession 时传入对应值
3. 读取时按 biz_type 过滤：chatStore.ListSessions("api", limit)
4. 前端按需添加历史面板：复用 VibeHistory 组件模式

无需修改表结构、无需新建表、无需改 ChatStore 接口。

举一反三：为 IM 消息也添加数据库历史浏览

当前 IM 消息的 Management API (GET /projects/{project}/sessions/{id}) 读取的是 JSON 文件/内存，不是 MySQL。如果想改为 MySQL 读取：

1. 在 management.go 中注入 ChatStore
2. handleProjectSessions 调用 chatStore.ListSessions("im", limit) 替代 JSON 读取
3. handleProjectSessionDetail 调用 chatStore.GetMessages(id, limit) 替代内存读取

接口完全一致，只需切换数据源。

统一历史：IM + Vibe 混合展示

历史记录面板默认展示所有类型的会话（Vibe + IM），通过颜色标签区分来源。

后端：biz_type 查询参数

GET /api/vibe/sessions 支持可选的 biz_type 参数：

实现方式：两条 SQL 常量

// 按 biz_type 过滤
listSessionsSQL = `SELECT ... WHERE s.biz_type = ? ORDER BY s.updated_at DESC LIMIT ?`

// 不过滤（查所有类型）
listAllSessionsSQL = `SELECT ... ORDER BY s.updated_at DESC LIMIT ?`

ListSessions 方法根据 bizType 是否为空选择 SQL：

func (s *MySQLChatStore) ListSessions(ctx, bizType, limit) {
    if bizType == "" {
        rows, err = s.db.QueryContext(ctx, listAllSessionsSQL, limit)
    } else {
        rows, err = s.db.QueryContext(ctx, listSessionsSQL, bizType, limit)
    }
}

前端：来源标签

VibeHistory.tsx 每条记录显示颜色标签区分来源：

<span className={cn(
  'text-[10px] px-1.5 py-0.5 rounded',
  session.biz_type === 'vibe'
    ? 'text-emerald-600 bg-emerald-50'     // 绿色 = Vibe
    : 'text-blue-600 bg-blue-50'           // 蓝色 = IM
)}>
  {session.biz_type === 'vibe' ? 'Vibe' : 'IM'}
</span>

举一反三：添加前端筛选 Tab

如果未来需要前端按来源筛选，只需在 VibeHistory 中添加 Tab 切换：

const [filter, setFilter] = useState<'' | 'vibe' | 'im'>('');
// 调用时传 biz_type 参数
listVibeSessions(50, filter);

API 层 listVibeSessions 添加 bizType 参数即可。

AgentSystemPrompt 项目感知

core/interfaces.go 的 AgentSystemPrompt() 包含 "Project management" 段， 告知 Claude Code agent 关于 /project 命令的存在：

### Project management
cc-connect manages multiple projects, each with its own work_dir.
The current project name is in the CC_PROJECT environment variable.

When the user asks about "projects", "switch project", "list projects",
"current project", or similar, tell them to use the /project command:
  - /project         — list all configured projects
  - /project <name>  — switch to a different project

Do NOT try to list projects by scanning the filesystem.

这避免了 Claude Code 在收到"展示当前项目"等自然语言时去执行 ls 扫描文件系统， 而是引导用户使用 /project 命令查看 cc-connect 配置中的项目列表。

Related Skills

• webui-vibe-coding — Vibe Coding 完整架构（WebSocket 协议、Go 后端、配置）
• webui-export-markdown — 聊天记录导出 Markdown（POST /api/vibe/export、全栈数据流）
• frontend-multi-tab — 多 Tab 架构模式（状态管理、组件拆分）
• add-new-feature — 通用功能添加 checklist（含 Management API 模式）
• config-startup-validation — 启动配置校验（database.dsn 必填）

Database Operation Logging

所有数据库操作都有 slog.Info (成功) 和 slog.Error (失败) 日志：

MySQL Driver 日志桥接

go-sql-driver 的内部日志（如 packets.go:58 unexpected EOF）通过 slogWriter 桥接到 slog：

// chatstore_mysql.go
func init() {
    _ = mysqldriver.SetLogger(log.New(slogWriter{}, "[mysql] ", 0))
}

type slogWriter struct{}
func (slogWriter) Write(p []byte) (int, error) {
    slog.Error("chatstore: mysql driver", "detail", strings.TrimSpace(string(p)))
    return len(p), nil
}

这确保底层 MySQL 协议错误也通过 cc-connect 的 slog 体系输出，不会因日志级别被过滤。

Vite Dev Proxy 配置

/api/vibe/* 的 REST 端点注册在 WebUIServer (9830)，不是 Management API (9820)。 Vite 开发代理必须将 /api/vibe 转发到 9830，且规则要写在 /api 之前：

// web/vite.config.ts
proxy: {
  '/api/vibe/ws': { target: 'http://localhost:9830', ws: true },
  '/api/vibe':    { target: 'http://localhost:9830' },   // ← REST API
  '/api':         { target: 'http://localhost:9820' },   // ← Management API
}

常见问题：GET /api/vibe/sessions 返回 404 原因：缺少 /api/vibe 代理规则，请求被 /api 规则转发到 9820 修复：在 vite.config.ts 中添加 /api/vibe 代理

Troubleshooting

问题: chatStore_nil=true

日志中 webui: creating vibe session chatStore_nil=true 表示 chatStore 未注入。

排查步骤：

1. 看启动日志有无 chatstore: MySQL connected → 没有说明连接失败
2. 看有无 chatstore: MySQL ping failed → DSN 格式或网络问题
3. 看有无 chatstore: mysql driver detail=[mysql] unexpected EOF → MySQL 拒绝连接

问题: DSN 格式错误

go-sql-driver/mysql 要求 tcp(host:port) 格式：

错误: hw3:pass@172.17.6.38:3309/db
正确: hw3:pass@tcp(172.17.6.38:3309)/db?charset=utf8mb4&parseTime=true

parseTime=true 是必须的，否则 DATETIME 列扫描会失败。

问题: unexpected EOF / invalid connection

通常是 MySQL 服务端拒绝连接（IP 白名单、max_connections 已满、SSL 不匹配）。 用 mysql -h host -P port -u user -p 命令行测试确认。

问题: context deadline exceeded

连接超时（默认 10 秒）。可能是网络不通或 DNS 解析慢。 在 DSN 中添加 timeout=5s 可缩短超时时间以快速失败。