Version: 0.4.4.dev.260307

feat: 🚀 增强会话管理与缓存机制

* 会话 ID 空值兜底，若 `conversation_id` 为空时自动生成 UUID
* 在响应头写入 `X-Conversation-ID`，供前端使用，保持同一会话状态

perf: ⚡ 会话状态缓存优化

* 当缓存未命中但 DB 已确认/创建会话后，调用 `SetConversationStatus` 回写 Redis
* 缓存写回失败时记录日志，不中断聊天主流程，确保业务流畅性

fix: 🐛 修复历史消息顺序问题与编译错误

* 修复历史消息顺序问题，保证返回的 N 条历史消息按时间正序喂给模型

  * 通过反转 `created_at desc` 查询结果的切片，确保模型输入顺序正确
* 修复 `fmt.Errorf` 参数不匹配问题，修正编译错误
* 整理 `agent-cache.go` 为标准 UTF-8 编码，避免 Go 编译报错 `invalid UTF-8 encoding`

feat: 🛠️ 独立构建 MCP 服务器

* 使用 `Codex` 构建独立于后端的 MCP 服务器，简化与 Codex 的协作
* 通过该服务器方便 Codex 直接测试和查看 Redis 与 MySQL 中的数据

infra/smartflow-mcp-server/internal/tools/integration_test.go

@@ -0,0 +1,95 @@
+package tools
+
+import (
+	"context"
+	"os"
+	"strconv"
+	"testing"
+	"time"
+
+	"github.com/LoveLosita/smartflow/infra/smartflow-mcp-server/internal/config"
+	"github.com/LoveLosita/smartflow/infra/smartflow-mcp-server/internal/security"
+	"github.com/LoveLosita/smartflow/infra/smartflow-mcp-server/internal/store"
+)
+
+func TestIntegrationMySQLReadOnlyTool(t *testing.T) {
+	if os.Getenv("MCP_IT_RUN") != "1" {
+		t.Skip("set MCP_IT_RUN=1 to run integration tests")
+	}
+
+	port := 3306
+	if p := os.Getenv("MYSQL_PORT"); p != "" {
+		if n, err := strconv.Atoi(p); err == nil {
+			port = n
+		}
+	}
+
+	mysqlCfg := config.MySQLConfig{
+		Host:     os.Getenv("MYSQL_HOST"),
+		Port:     port,
+		User:     os.Getenv("MYSQL_USER"),
+		Password: os.Getenv("MYSQL_PASSWORD"),
+		Database: os.Getenv("MYSQL_DATABASE"),
+		Params:   "charset=utf8mb4&parseTime=true&loc=Local",
+	}
+	if mysqlCfg.Host == "" || mysqlCfg.User == "" || mysqlCfg.Database == "" {
+		t.Skip("missing MYSQL_* env for integration test")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	client, err := store.NewMySQLClient(ctx, mysqlCfg)
+	if err != nil {
+		t.Fatalf("mysql not available: %v", err)
+	}
+	defer func() { _ = client.Close() }()
+
+	validator := security.NewSQLValidator(mysqlCfg.Database, false, nil, nil)
+	tool := NewMySQLReadOnlyTool(client, validator, 10)
+	res, err := tool.Execute(ctx, map[string]any{"sql": "SELECT 1 AS ok"})
+	if err != nil {
+		t.Fatalf("tool execute failed: %v", err)
+	}
+	if res["rowCount"].(int) < 1 {
+		t.Fatalf("expected rowCount >= 1")
+	}
+}
+
+func TestIntegrationRedisTools(t *testing.T) {
+	if os.Getenv("MCP_IT_RUN") != "1" {
+		t.Skip("set MCP_IT_RUN=1 to run integration tests")
+	}
+
+	db := 0
+	if p := os.Getenv("REDIS_DB"); p != "" {
+		if n, err := strconv.Atoi(p); err == nil {
+			db = n
+		}
+	}
+	redisCfg := config.RedisConfig{
+		Addr:     os.Getenv("REDIS_ADDR"),
+		Password: os.Getenv("REDIS_PASSWORD"),
+		DB:       db,
+	}
+	if redisCfg.Addr == "" {
+		t.Skip("REDIS_ADDR is empty")
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	client, err := store.NewRedisClient(ctx, redisCfg)
+	if err != nil {
+		t.Fatalf("redis not available: %v", err)
+	}
+	defer func() { _ = client.Close() }()
+
+	getTool := NewRedisGetTool(client, 10, 128)
+	if _, err := getTool.Execute(ctx, map[string]any{"key": "__integration_missing_key__"}); err != nil {
+		t.Fatalf("redis_get failed: %v", err)
+	}
+
+	scanTool := NewRedisScanTool(client, 10, 10)
+	if _, err := scanTool.Execute(ctx, map[string]any{"pattern": "*", "count": float64(5)}); err != nil {
+		t.Fatalf("redis_scan failed: %v", err)
+	}
+}

infra/smartflow-mcp-server/internal/tools/mysql_readonly.go

@@ -0,0 +1,95 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/LoveLosita/smartflow/infra/smartflow-mcp-server/internal/security"
+	"github.com/LoveLosita/smartflow/infra/smartflow-mcp-server/internal/store"
+)
+
+type MySQLReadOnlyTool struct {
+	client    *store.MySQLClient
+	validator *security.SQLValidator
+	maxRows   int
+}
+
+func NewMySQLReadOnlyTool(client *store.MySQLClient, validator *security.SQLValidator, maxRows int) *MySQLReadOnlyTool {
+	return &MySQLReadOnlyTool{client: client, validator: validator, maxRows: maxRows}
+}
+
+func (t *MySQLReadOnlyTool) Name() string {
+	return "mysql_query_readonly"
+}
+
+func (t *MySQLReadOnlyTool) Description() string {
+	return "Execute read-only SQL on MySQL. Only SELECT/SHOW/DESCRIBE/EXPLAIN are allowed."
+}
+
+func (t *MySQLReadOnlyTool) InputSchema() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"sql": map[string]any{
+				"type":        "string",
+				"description": "Read-only SQL statement",
+			},
+			"params": map[string]any{
+				"type":        "array",
+				"description": "Optional bind parameters",
+				"items": map[string]any{
+					"type": []string{"string", "number", "boolean", "null"},
+				},
+			},
+		},
+		"required":             []string{"sql"},
+		"additionalProperties": false,
+	}
+}
+
+func (t *MySQLReadOnlyTool) Execute(ctx context.Context, args map[string]any) (map[string]any, error) {
+	rawSQL, ok := args["sql"].(string)
+	if !ok || rawSQL == "" {
+		return nil, fmt.Errorf("sql must be a non-empty string")
+	}
+	if err := t.validator.ValidateReadOnlySQL(rawSQL); err != nil {
+		return nil, err
+	}
+
+	params, err := normalizeParams(args["params"])
+	if err != nil {
+		return nil, err
+	}
+
+	res, err := t.client.QueryReadOnly(ctx, rawSQL, params, t.maxRows)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{
+		"columns":    res.Columns,
+		"rows":       res.Rows,
+		"rowCount":   res.RowCount,
+		"truncated":  res.Truncated,
+		"durationMs": res.DurationMs,
+	}, nil
+}
+
+func normalizeParams(raw any) ([]any, error) {
+	if raw == nil {
+		return nil, nil
+	}
+	arr, ok := raw.([]any)
+	if !ok {
+		return nil, fmt.Errorf("params must be an array")
+	}
+	out := make([]any, 0, len(arr))
+	for _, item := range arr {
+		switch v := item.(type) {
+		case string, float64, bool, nil:
+			out = append(out, v)
+		default:
+			return nil, fmt.Errorf("params contains unsupported type")
+		}
+	}
+	return out, nil
+}

infra/smartflow-mcp-server/internal/tools/redis_tools.go

@@ -0,0 +1,130 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/LoveLosita/smartflow/infra/smartflow-mcp-server/internal/store"
+)
+
+type RedisGetTool struct {
+	client         *store.RedisClient
+	valueMaxItems  int
+	maxStringBytes int
+}
+
+func NewRedisGetTool(client *store.RedisClient, valueMaxItems int, maxStringBytes int) *RedisGetTool {
+	return &RedisGetTool{client: client, valueMaxItems: valueMaxItems, maxStringBytes: maxStringBytes}
+}
+
+func (t *RedisGetTool) Name() string {
+	return "redis_get"
+}
+
+func (t *RedisGetTool) Description() string {
+	return "Get a Redis key by name and return its type and value."
+}
+
+func (t *RedisGetTool) InputSchema() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"key": map[string]any{
+				"type":        "string",
+				"description": "Redis key",
+			},
+		},
+		"required":             []string{"key"},
+		"additionalProperties": false,
+	}
+}
+
+func (t *RedisGetTool) Execute(ctx context.Context, args map[string]any) (map[string]any, error) {
+	key, ok := args["key"].(string)
+	if !ok || key == "" {
+		return nil, fmt.Errorf("key must be a non-empty string")
+	}
+	res, err := t.client.GetWithType(ctx, key, t.valueMaxItems, t.maxStringBytes)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{
+		"exists":     res.Exists,
+		"key":        res.Key,
+		"type":       res.Type,
+		"value":      res.Value,
+		"truncated":  res.Truncated,
+		"durationMs": res.DurationMs,
+	}, nil
+}
+
+type RedisScanTool struct {
+	client       *store.RedisClient
+	maxKeys      int
+	maxScanCount int
+}
+
+func NewRedisScanTool(client *store.RedisClient, maxKeys int, maxScanCount int) *RedisScanTool {
+	return &RedisScanTool{client: client, maxKeys: maxKeys, maxScanCount: maxScanCount}
+}
+
+func (t *RedisScanTool) Name() string {
+	return "redis_scan"
+}
+
+func (t *RedisScanTool) Description() string {
+	return "Scan Redis keys by pattern with capped result size."
+}
+
+func (t *RedisScanTool) InputSchema() map[string]any {
+	return map[string]any{
+		"type": "object",
+		"properties": map[string]any{
+			"pattern": map[string]any{
+				"type":        "string",
+				"description": "Pattern, for example user:*",
+			},
+			"count": map[string]any{
+				"type":        "number",
+				"description": "Optional scan count hint",
+			},
+		},
+		"required":             []string{"pattern"},
+		"additionalProperties": false,
+	}
+}
+
+func (t *RedisScanTool) Execute(ctx context.Context, args map[string]any) (map[string]any, error) {
+	pattern, ok := args["pattern"].(string)
+	if !ok || pattern == "" {
+		return nil, fmt.Errorf("pattern must be a non-empty string")
+	}
+
+	count := int64(20)
+	if rawCount, ok := args["count"]; ok {
+		number, ok := rawCount.(float64)
+		if !ok {
+			return nil, fmt.Errorf("count must be a number")
+		}
+		if number <= 0 {
+			return nil, fmt.Errorf("count must be > 0")
+		}
+		count = int64(number)
+	}
+	if count > int64(t.maxScanCount) {
+		count = int64(t.maxScanCount)
+	}
+
+	res, err := t.client.ScanKeys(ctx, pattern, count, t.maxKeys)
+	if err != nil {
+		return nil, err
+	}
+	return map[string]any{
+		"pattern":    res.Pattern,
+		"keys":       res.Keys,
+		"returned":   res.Returned,
+		"nextCursor": res.NextCursor,
+		"truncated":  res.Truncated,
+		"durationMs": res.DurationMs,
+	}, nil
+}

infra/smartflow-mcp-server/internal/tools/registry.go

@@ -0,0 +1,53 @@
+package tools
+
+import (
+	"context"
+	"fmt"
+	"sort"
+)
+
+type Tool interface {
+	Name() string
+	Description() string
+	InputSchema() map[string]any
+	Execute(ctx context.Context, args map[string]any) (map[string]any, error)
+}
+
+type Registry struct {
+	tools map[string]Tool
+}
+
+func NewRegistry(toolList ...Tool) (*Registry, error) {
+	r := &Registry{tools: make(map[string]Tool, len(toolList))}
+	for _, t := range toolList {
+		name := t.Name()
+		if _, exists := r.tools[name]; exists {
+			return nil, fmt.Errorf("duplicated tool name: %s", name)
+		}
+		r.tools[name] = t
+	}
+	return r, nil
+}
+
+func (r *Registry) Find(name string) (Tool, bool) {
+	t, ok := r.tools[name]
+	return t, ok
+}
+
+func (r *Registry) List() []map[string]any {
+	out := make([]map[string]any, 0, len(r.tools))
+	names := make([]string, 0, len(r.tools))
+	for name := range r.tools {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	for _, name := range names {
+		t := r.tools[name]
+		out = append(out, map[string]any{
+			"name":        t.Name(),
+			"description": t.Description(),
+			"inputSchema": t.InputSchema(),
+		})
+	}
+	return out
+}