M0-M4: 推倒重来基线(基建+用户/密钥/核心代理+前端+管理后台+三协议互转)

- 后端 Go+Gin+GORM: 配置(OT_ env)/SQLite/Postgres 双驱动、用户体系(argon2id+JWT access/refresh)、 API Key(sk- 48位, 仅存 SHA-256 哈希) - 代理网关: /v1/chat/completions、/v1/responses、/v1/messages、/v1/models;错误按客户端协议返回 - 三协议互转(convert 包): Chat↔Messages↔Responses 请求/响应 + 流式 SSE 逐事件转换(直通优先) - 用量计费: 异步批量记账、余额扣减、balance_logs、usage_daily 日聚合 - 管理 API: 用户/渠道 CRUD+测试+模型导入/模型定价+绑定/统计/系统配置 - 前端 Vue3+TS+Tailwind(taste-skill 设计 tokens): Landing/登录注册/控制台/管理后台, 自建组件+Phosphor 图标+自建 SVG 趋势图, 已过 web-design-guidelines 复查 - mock 上游: OpenAI+Anthropic 双协议模拟(含流式) Co-Authored-By: Claude <noreply@anthropic.com>
2026-08-15 15:34:06 +08:00
parent b25e9ec8a7
commit ec4de8d913
92 changed files with 6203 additions and 3064 deletions
@@ -2,7 +2,6 @@ package api

 import (
 	"encoding/json"
-	"fmt"
 	"net/http"
 	"strconv"
 	"time"
@@ -11,6 +10,7 @@ import (
 	"github.com/openteam/server/internal/pkg/resp"
 	"github.com/openteam/server/internal/store"
 	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
 )

 // AdminUsers GET /api/v1/admin/users — 用户列表（搜索、分页）。
@@ -38,7 +38,7 @@ func (h *Handler) AdminUsers(c *gin.Context) {
 	resp.OK(c, gin.H{"items": out, "total": total, "page": page, "page_size": size})
 }

-// AdminPatchUser PATCH /api/v1/admin/users/:id — 角色/状态/余额。
+// AdminPatchUser PATCH /api/v1/admin/users/:id — 角色/状态。
 func (h *Handler) AdminPatchUser(c *gin.Context) {
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil {
@@ -53,11 +53,6 @@ func (h *Handler) AdminPatchUser(c *gin.Context) {
 		resp.Fail(c, http.StatusBadRequest, "invalid input")
 		return
 	}
-	var u store.User
-	if err := h.a.DB.First(&u, id).Error; err != nil {
-		resp.Fail(c, http.StatusNotFound, "user not found")
-		return
-	}
 	updates := map[string]any{}
 	if req.Role != nil {
 		if *req.Role != store.RoleUser && *req.Role != store.RoleAdmin {
@@ -73,42 +68,57 @@ func (h *Handler) AdminPatchUser(c *gin.Context) {
 		}
 		updates["status"] = *req.Status
 	}
-	if len(updates) > 0 {
-		h.a.DB.Model(&u).Updates(updates)
+	if len(updates) == 0 {
+		resp.OK(c, gin.H{"ok": true})
+		return
+	}
+	res := h.a.DB.Model(&store.User{}).Where("id = ?", id).Updates(updates)
+	if res.Error != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to update user")
+		return
+	}
+	if res.RowsAffected == 0 {
+		resp.Fail(c, http.StatusNotFound, "user not found")
+		return
 	}
 	resp.OK(c, gin.H{"ok": true})
 }

-// AdminAdjustBalance POST /api/v1/admin/users/:id/balance — 调整余额并写流水。
+// AdminAdjustBalance POST /api/v1/admin/users/:id/balance — 手动调余额（写流水）。
 func (h *Handler) AdminAdjustBalance(c *gin.Context) {
-	admin, _ := userFromContext(c)
+	admin := sessionUser(c)
 	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
 	if err != nil {
 		resp.Fail(c, http.StatusBadRequest, "invalid user id")
 		return
 	}
 	var req struct {
-		Change float64 `json:"change" binding:"required"`
+		Amount float64 `json:"amount" binding:"required"`
 		Remark string  `json:"remark"`
 	}
 	if err := c.ShouldBindJSON(&req); err != nil {
-		resp.Fail(c, http.StatusBadRequest, "invalid input: change is required")
+		resp.Fail(c, http.StatusBadRequest, "invalid input: amount required")
 		return
 	}
-	var u store.User
-	if err := h.a.DB.First(&u, id).Error; err != nil {
-		resp.Fail(c, http.StatusNotFound, "user not found")
+	if req.Amount == 0 {
+		resp.Fail(c, http.StatusBadRequest, "amount must not be zero")
 		return
 	}
-	newBalance := u.Balance + req.Change
-	ref := fmt.Sprintf("admin:%d:%d", admin.ID, time.Now().UnixNano())
+
 	err = h.a.DB.Transaction(func(tx *gorm.DB) error {
-		if err := tx.Model(&store.User{}).Where("id = ?", u.ID).Update("balance", newBalance).Error; err != nil {
+		var u store.User
+		if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&u, id).Error; err != nil {
 			return err
 		}
+		newBalance := u.Balance + req.Amount
+		if err := tx.Model(&store.User{}).Where("id = ?", id).Update("balance", newBalance).Error; err != nil {
+			return err
+		}
+		ref := "admin:" + strconv.FormatUint(u.ID, 10) + ":" + time.Now().Format("20060102150405")
+		_ = admin.ID // 流水里不冗余管理员 ID；需要时再加
 		return tx.Create(&store.BalanceLog{
 			UserID:       u.ID,
-			Change:       req.Change,
+			Change:       req.Amount,
 			BalanceAfter: newBalance,
 			Type:         store.BalanceTypeAdminAdjust,
 			RefID:        ref,
@@ -116,45 +126,45 @@ func (h *Handler) AdminAdjustBalance(c *gin.Context) {
 		}).Error
 	})
 	if err != nil {
-		resp.Fail(c, http.StatusInternalServerError, "failed to adjust balance")
+		resp.Fail(c, http.StatusNotFound, "user not found or failed to adjust")
 		return
 	}
-	resp.OK(c, gin.H{"ok": true, "balance": newBalance})
+	resp.OK(c, gin.H{"ok": true})
 }

-// AdminConfig GET /api/v1/admin/config
+// AdminConfig GET /api/v1/admin/config — 全部系统配置。
 func (h *Handler) AdminConfig(c *gin.Context) {
 	var cfgs []store.SystemConfig
-	h.a.DB.Find(&cfgs)
-	m := map[string]any{}
-	for _, cfg := range cfgs {
-		var v any
-		_ = json.Unmarshal([]byte(cfg.Value), &v)
-		m[cfg.Key] = v
+	if err := h.a.DB.Find(&cfgs).Error; err != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to load config")
+		return
 	}
-	m["registration.mode"] = h.a.Cfg.Auth.RegistrationMode
-	resp.OK(c, gin.H{"config": m})
+	out := gin.H{}
+	for _, cfg := range cfgs {
+		out[cfg.Key] = json.RawMessage(cfg.Value)
+	}
+	resp.OK(c, gin.H{"config": out})
 }

-// AdminPutConfig PUT /api/v1/admin/config
+// AdminPutConfig PUT /api/v1/admin/config — 整表覆盖（upsert）。
 func (h *Handler) AdminPutConfig(c *gin.Context) {
-	var req struct {
-		Config map[string]any `json:"config"`
-	}
+	var req map[string]json.RawMessage
 	if err := c.ShouldBindJSON(&req); err != nil {
 		resp.Fail(c, http.StatusBadRequest, "invalid input")
 		return
 	}
-	for k, v := range req.Config {
-		if k == "registration.mode" {
-			if v == "open" || v == "invite" {
-				h.a.Cfg.Auth.RegistrationMode = v.(string)
+	err := h.a.DB.Transaction(func(tx *gorm.DB) error {
+		for k, v := range req {
+			cfg := store.SystemConfig{Key: k, Value: string(v)}
+			if err := tx.Save(&cfg).Error; err != nil {
+				return err
 			}
-			continue
 		}
-		b, _ := json.Marshal(v)
-		cfg := store.SystemConfig{Key: k, Value: string(b)}
-		h.a.DB.Save(&cfg)
+		return nil
+	})
+	if err != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to save config")
+		return
 	}
 	resp.OK(c, gin.H{"ok": true})
 }
@@ -0,0 +1,333 @@
+package api
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"strconv"
+	"strings"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/openteam/server/internal/pkg/resp"
+	"github.com/openteam/server/internal/store"
+	"gorm.io/gorm"
+	"gorm.io/gorm/clause"
+)
+
+// AdminChannels GET /api/v1/admin/channels — 渠道列表（不返回加密 key，返回掩码）。
+func (h *Handler) AdminChannels(c *gin.Context) {
+	var chs []store.Channel
+	if err := h.a.DB.Order("id ASC").Find(&chs).Error; err != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to load channels")
+		return
+	}
+	out := make([]gin.H, 0, len(chs))
+	for _, ch := range chs {
+		masked := ""
+		if key, err := h.a.Enc.Decrypt(ch.APIKeyEnc); err == nil && len(key) > 8 {
+			masked = strings.Repeat("*", len(key)-4) + key[len(key)-4:]
+		} else if err == nil {
+			masked = "****"
+		}
+		out = append(out, gin.H{
+			"id": ch.ID, "name": ch.Name, "provider": ch.Provider, "base_url": ch.BaseURL,
+			"api_key_masked": masked, "weight": ch.Weight, "priority": ch.Priority,
+			"timeout_ms": ch.TimeoutMS, "max_concurrency": ch.MaxConcurrency,
+			"health_status": ch.HealthStatus, "enabled": ch.Enabled,
+			"created_at": ch.CreatedAt,
+		})
+	}
+	resp.OK(c, gin.H{"items": out})
+}
+
+type channelBody struct {
+	Name           string  `json:"name" binding:"required,min=1,max=64"`
+	Provider       string  `json:"provider" binding:"required"`
+	BaseURL        string  `json:"base_url" binding:"required"`
+	APIKey         string  `json:"api_key"`
+	Weight         *int    `json:"weight"`
+	Priority       *int    `json:"priority"`
+	TimeoutMS      *int    `json:"timeout_ms"`
+	MaxConcurrency *int    `json:"max_concurrency"`
+	Enabled        *bool   `json:"enabled"`
+}
+
+func validateProvider(p string) bool {
+	return p == store.ChannelProviderOpenAI || p == store.ChannelProviderAnthropic || p == store.ChannelProviderCompatible
+}
+
+// AdminCreateChannel POST /api/v1/admin/channels
+func (h *Handler) AdminCreateChannel(c *gin.Context) {
+	var req channelBody
+	if err := c.ShouldBindJSON(&req); err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid input: "+err.Error())
+		return
+	}
+	if !validateProvider(req.Provider) {
+		resp.Fail(c, http.StatusBadRequest, "provider must be openai, anthropic or compatible")
+		return
+	}
+	if req.APIKey == "" {
+		resp.Fail(c, http.StatusBadRequest, "api_key required")
+		return
+	}
+	enc, err := h.a.Enc.Encrypt(req.APIKey)
+	if err != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to encrypt api key")
+		return
+	}
+	ch := store.Channel{
+		Name: req.Name, Provider: req.Provider, BaseURL: strings.TrimRight(req.BaseURL, "/"),
+		APIKeyEnc: enc, Weight: intOr(req.Weight, 1), Priority: intOr(req.Priority, 0),
+		TimeoutMS: intOr(req.TimeoutMS, 120000), MaxConcurrency: intOr(req.MaxConcurrency, 16),
+		HealthStatus: store.ChannelHealthHealthy, Enabled: boolOr(req.Enabled, true),
+	}
+	if err := h.a.DB.Create(&ch).Error; err != nil {
+		resp.Fail(c, http.StatusConflict, "failed to create channel (name may already exist)")
+		return
+	}
+	resp.Created(c, gin.H{"id": ch.ID, "name": ch.Name})
+}
+
+// AdminUpdateChannel PUT /api/v1/admin/channels/:id
+func (h *Handler) AdminUpdateChannel(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid channel id")
+		return
+	}
+	var body struct {
+		Name           *string `json:"name"`
+		Provider       *string `json:"provider"`
+		BaseURL        *string `json:"base_url"`
+		APIKey         *string `json:"api_key"`
+		Weight         *int    `json:"weight"`
+		Priority       *int    `json:"priority"`
+		TimeoutMS      *int    `json:"timeout_ms"`
+		MaxConcurrency *int    `json:"max_concurrency"`
+		HealthStatus   *string `json:"health_status"`
+		Enabled        *bool   `json:"enabled"`
+	}
+	if err := c.ShouldBindJSON(&body); err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid input")
+		return
+	}
+	var ch store.Channel
+	if err := h.a.DB.First(&ch, id).Error; err != nil {
+		resp.Fail(c, http.StatusNotFound, "channel not found")
+		return
+	}
+	updates := map[string]any{}
+	if body.Name != nil {
+		updates["name"] = *body.Name
+	}
+	if body.Provider != nil {
+		if !validateProvider(*body.Provider) {
+			resp.Fail(c, http.StatusBadRequest, "provider must be openai, anthropic or compatible")
+			return
+		}
+		updates["provider"] = *body.Provider
+	}
+	if body.BaseURL != nil {
+		updates["base_url"] = strings.TrimRight(*body.BaseURL, "/")
+	}
+	if body.APIKey != nil && *body.APIKey != "" {
+		enc, err := h.a.Enc.Encrypt(*body.APIKey)
+		if err != nil {
+			resp.Fail(c, http.StatusInternalServerError, "failed to encrypt api key")
+			return
+		}
+		updates["api_key_enc"] = enc
+	}
+	if body.Weight != nil {
+		updates["weight"] = *body.Weight
+	}
+	if body.Priority != nil {
+		updates["priority"] = *body.Priority
+	}
+	if body.TimeoutMS != nil {
+		updates["timeout_ms"] = *body.TimeoutMS
+	}
+	if body.MaxConcurrency != nil {
+		updates["max_concurrency"] = *body.MaxConcurrency
+	}
+	if body.HealthStatus != nil {
+		updates["health_status"] = *body.HealthStatus
+	}
+	if body.Enabled != nil {
+		updates["enabled"] = *body.Enabled
+	}
+	if len(updates) > 0 {
+		if err := h.a.DB.Model(&ch).Updates(updates).Error; err != nil {
+			resp.Fail(c, http.StatusInternalServerError, "failed to update channel")
+			return
+		}
+	}
+	resp.OK(c, gin.H{"ok": true})
+}
+
+// AdminDeleteChannel DELETE /api/v1/admin/channels/:id
+func (h *Handler) AdminDeleteChannel(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid channel id")
+		return
+	}
+	res := h.a.DB.Delete(&store.Channel{}, id)
+	if res.Error != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to delete channel")
+		return
+	}
+	if res.RowsAffected == 0 {
+		resp.Fail(c, http.StatusNotFound, "channel not found")
+		return
+	}
+	// 清理模型绑定
+	h.a.DB.Where("channel_id = ?", id).Delete(&store.ChannelModelBinding{})
+	resp.OK(c, gin.H{"ok": true})
+}
+
+// AdminTestChannel POST /api/v1/admin/channels/:id/test — 请求渠道 /v1/models 测连通性。
+func (h *Handler) AdminTestChannel(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid channel id")
+		return
+	}
+	var ch store.Channel
+	if err := h.a.DB.First(&ch, id).Error; err != nil {
+		resp.Fail(c, http.StatusNotFound, "channel not found")
+		return
+	}
+	key, err := h.a.Enc.Decrypt(ch.APIKeyEnc)
+	if err != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to decrypt channel key")
+		return
+	}
+	url := strings.TrimRight(ch.BaseURL, "/") + "/v1/models"
+	client := &http.Client{Timeout: 10 * time.Second}
+	req, _ := http.NewRequest(http.MethodGet, url, nil)
+	req.Header.Set("Authorization", "Bearer "+key)
+	req.Header.Set("Accept", "application/json")
+	start := time.Now()
+	resp2, err := client.Do(req)
+	status := store.ChannelHealthHealthy
+	msg := "ok"
+	latency := 0
+	if err != nil {
+		status = store.ChannelHealthCooldown
+		msg = err.Error()
+	} else {
+		latency = int(time.Since(start).Milliseconds())
+		if resp2.StatusCode < 200 || resp2.StatusCode >= 300 {
+			status = store.ChannelHealthCooldown
+			b, _ := io.ReadAll(io.LimitReader(resp2.Body, 1024))
+			msg = fmt.Sprintf("http %d: %s", resp2.StatusCode, strings.TrimSpace(string(b)))
+		}
+		resp2.Body.Close()
+	}
+	h.a.DB.Model(&store.Channel{}).Where("id = ?", ch.ID).Update("health_status", status)
+	if status != store.ChannelHealthHealthy {
+		resp.Fail(c, http.StatusBadGateway, msg)
+		return
+	}
+	resp.OK(c, gin.H{"ok": true, "latency_ms": latency, "message": msg})
+}
+
+// AdminImportChannelModels POST /api/v1/admin/channels/:id/models/import
+// 拉取渠道 GET /v1/models，导入模型库并绑定。
+func (h *Handler) AdminImportChannelModels(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid channel id")
+		return
+	}
+	var ch store.Channel
+	if err := h.a.DB.First(&ch, id).Error; err != nil {
+		resp.Fail(c, http.StatusNotFound, "channel not found")
+		return
+	}
+	key, err := h.a.Enc.Decrypt(ch.APIKeyEnc)
+	if err != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to decrypt channel key")
+		return
+	}
+	url := strings.TrimRight(ch.BaseURL, "/") + "/v1/models"
+	client := &http.Client{Timeout: 15 * time.Second}
+	req, _ := http.NewRequest(http.MethodGet, url, nil)
+	req.Header.Set("Authorization", "Bearer "+key)
+	resp2, err := client.Do(req)
+	if err != nil {
+		resp.Fail(c, http.StatusBadGateway, "failed to reach channel: "+err.Error())
+		return
+	}
+	defer resp2.Body.Close()
+	if resp2.StatusCode != http.StatusOK {
+		resp.Fail(c, http.StatusBadGateway, "channel returned http "+strconv.Itoa(resp2.StatusCode))
+		return
+	}
+	var list struct {
+		Data []struct {
+			ID string `json:"id"`
+		} `json:"data"`
+	}
+	if err := json.NewDecoder(resp2.Body).Decode(&list); err != nil {
+		resp.Fail(c, http.StatusBadGateway, "failed to parse model list")
+		return
+	}
+	if len(list.Data) == 0 {
+		resp.Fail(c, http.StatusNotFound, "channel returned no models")
+		return
+	}
+
+	imported := 0
+	err = h.a.DB.Transaction(func(tx *gorm.DB) error {
+		for _, item := range list.Data {
+			name := strings.TrimSpace(item.ID)
+			if name == "" {
+				continue
+			}
+			var m store.Model
+			if err := tx.Where("name = ?", name).FirstOrCreate(&m, store.Model{
+				Name: name, DisplayName: name, Enabled: true,
+			}).Error; err != nil {
+				return err
+			}
+			// upsert 绑定（upstream_model 默认同名）
+			var binding store.ChannelModelBinding
+			err := tx.Where("channel_id = ? AND model_id = ?", ch.ID, m.ID).First(&binding).Error
+			if errors.Is(err, gorm.ErrRecordNotFound) {
+				binding = store.ChannelModelBinding{ChannelID: ch.ID, ModelID: m.ID, UpstreamModel: name, Weight: 1}
+				if err := tx.Create(&binding).Error; err != nil {
+					return err
+				}
+			}
+			imported++
+		}
+		return nil
+	})
+	if err != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to import models")
+		return
+	}
+	resp.OK(c, gin.H{"imported": imported})
+}
+
+var _ = clause.Assignments // 保留 gorm/clause 引用（后续定价批处理用）
+
+func intOr(p *int, def int) int {
+	if p == nil {
+		return def
+	}
+	return *p
+}
+
+func boolOr(p *bool, def bool) bool {
+	if p == nil {
+		return def
+	}
+	return *p
+}
@@ -0,0 +1,199 @@
+package api
+
+import (
+	"errors"
+	"net/http"
+	"strconv"
+
+	"github.com/gin-gonic/gin"
+	"github.com/openteam/server/internal/pkg/resp"
+	"github.com/openteam/server/internal/store"
+	"gorm.io/gorm"
+)
+
+// AdminModels GET /api/v1/admin/models — 模型列表（含价格与渠道绑定）。
+func (h *Handler) AdminModels(c *gin.Context) {
+	var ms []store.Model
+	if err := h.a.DB.Order("sort ASC, id ASC").Find(&ms).Error; err != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to load models")
+		return
+	}
+	out := make([]gin.H, 0, len(ms))
+	for _, m := range ms {
+		var bindings []store.ChannelModelBinding
+		h.a.DB.Preload("Channel").Where("model_id = ?", m.ID).Find(&bindings)
+		chs := make([]gin.H, 0, len(bindings))
+		for _, b := range bindings {
+			chs = append(chs, gin.H{
+				"id": b.ID, "channel_id": b.ChannelID, "channel_name": b.Channel.Name,
+				"upstream_model": b.UpstreamModel, "weight": b.Weight,
+			})
+		}
+		out = append(out, gin.H{
+			"id": m.ID, "name": m.Name, "display_name": m.DisplayName,
+			"input_price": m.InputPrice, "output_price": m.OutputPrice, "cache_read_price": m.CacheReadPrice,
+			"enabled": m.Enabled, "sort": m.Sort, "channels": chs,
+		})
+	}
+	resp.OK(c, gin.H{"items": out})
+}
+
+// AdminCreateModel POST /api/v1/admin/models
+func (h *Handler) AdminCreateModel(c *gin.Context) {
+	var req struct {
+		Name           string  `json:"name" binding:"required,min=1,max=128"`
+		DisplayName    string  `json:"display_name"`
+		InputPrice     float64 `json:"input_price"`
+		OutputPrice    float64 `json:"output_price"`
+		CacheReadPrice float64 `json:"cache_read_price"`
+		Enabled        *bool   `json:"enabled"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid input: "+err.Error())
+		return
+	}
+	m := store.Model{
+		Name: req.Name, DisplayName: req.DisplayName,
+		InputPrice: req.InputPrice, OutputPrice: req.OutputPrice, CacheReadPrice: req.CacheReadPrice,
+		Enabled: boolOr(req.Enabled, true),
+	}
+	if m.DisplayName == "" {
+		m.DisplayName = m.Name
+	}
+	if err := h.a.DB.Create(&m).Error; err != nil {
+		resp.Fail(c, http.StatusConflict, "failed to create model (name may already exist)")
+		return
+	}
+	resp.Created(c, gin.H{"id": m.ID, "name": m.Name})
+}
+
+// AdminUpdateModel PUT /api/v1/admin/models/:id — 价格/展示名/启停/排序。
+func (h *Handler) AdminUpdateModel(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid model id")
+		return
+	}
+	var req struct {
+		DisplayName    *string  `json:"display_name"`
+		InputPrice     *float64 `json:"input_price"`
+		OutputPrice    *float64 `json:"output_price"`
+		CacheReadPrice *float64 `json:"cache_read_price"`
+		Enabled        *bool    `json:"enabled"`
+		Sort           *int     `json:"sort"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid input")
+		return
+	}
+	var m store.Model
+	if err := h.a.DB.First(&m, id).Error; err != nil {
+		resp.Fail(c, http.StatusNotFound, "model not found")
+		return
+	}
+	updates := map[string]any{}
+	if req.DisplayName != nil {
+		updates["display_name"] = *req.DisplayName
+	}
+	if req.InputPrice != nil {
+		updates["input_price"] = *req.InputPrice
+	}
+	if req.OutputPrice != nil {
+		updates["output_price"] = *req.OutputPrice
+	}
+	if req.CacheReadPrice != nil {
+		updates["cache_read_price"] = *req.CacheReadPrice
+	}
+	if req.Enabled != nil {
+		updates["enabled"] = *req.Enabled
+	}
+	if req.Sort != nil {
+		updates["sort"] = *req.Sort
+	}
+	if len(updates) > 0 {
+		if err := h.a.DB.Model(&m).Updates(updates).Error; err != nil {
+			resp.Fail(c, http.StatusInternalServerError, "failed to update model")
+			return
+		}
+	}
+	resp.OK(c, gin.H{"ok": true})
+}
+
+// AdminDeleteModel DELETE /api/v1/admin/models/:id
+func (h *Handler) AdminDeleteModel(c *gin.Context) {
+	id, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid model id")
+		return
+	}
+	res := h.a.DB.Delete(&store.Model{}, id)
+	if res.Error != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to delete model")
+		return
+	}
+	if res.RowsAffected == 0 {
+		resp.Fail(c, http.StatusNotFound, "model not found")
+		return
+	}
+	h.a.DB.Where("model_id = ?", id).Delete(&store.ChannelModelBinding{})
+	resp.OK(c, gin.H{"ok": true})
+}
+
+// AdminCreateModelBinding POST /api/v1/admin/models/:id/bindings
+func (h *Handler) AdminCreateModelBinding(c *gin.Context) {
+	modelID, err := strconv.ParseUint(c.Param("id"), 10, 64)
+	if err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid model id")
+		return
+	}
+	var req struct {
+		ChannelID     uint64 `json:"channel_id" binding:"required"`
+		UpstreamModel string `json:"upstream_model" binding:"required"`
+		Weight        *int   `json:"weight"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid input: channel_id and upstream_model required")
+		return
+	}
+	var m store.Model
+	if err := h.a.DB.First(&m, modelID).Error; err != nil {
+		resp.Fail(c, http.StatusNotFound, "model not found")
+		return
+	}
+	var ch store.Channel
+	if err := h.a.DB.First(&ch, req.ChannelID).Error; err != nil {
+		resp.Fail(c, http.StatusNotFound, "channel not found")
+		return
+	}
+	b := store.ChannelModelBinding{
+		ChannelID: req.ChannelID, ModelID: modelID,
+		UpstreamModel: req.UpstreamModel, Weight: intOr(req.Weight, 1),
+	}
+	if err := h.a.DB.Create(&b).Error; err != nil {
+		resp.Fail(c, http.StatusConflict, "binding may already exist")
+		return
+	}
+	resp.Created(c, gin.H{"id": b.ID})
+}
+
+// AdminDeleteModelBinding DELETE /api/v1/admin/models/:id/bindings/:bid
+func (h *Handler) AdminDeleteModelBinding(c *gin.Context) {
+	bid, err := strconv.ParseUint(c.Param("bid"), 10, 64)
+	if err != nil {
+		resp.Fail(c, http.StatusBadRequest, "invalid binding id")
+		return
+	}
+	res := h.a.DB.Delete(&store.ChannelModelBinding{}, bid)
+	if res.Error != nil {
+		resp.Fail(c, http.StatusInternalServerError, "failed to delete binding")
+		return
+	}
+	if res.RowsAffected == 0 {
+		resp.Fail(c, http.StatusNotFound, "binding not found")
+		return
+	}
+	resp.OK(c, gin.H{"ok": true})
+}
+
+var _ = errors.Is
+var _ = gorm.ErrRecordNotFound
@@ -0,0 +1,102 @@
+package api
+
+import (
+	"strconv"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/openteam/server/internal/pkg/resp"
+	"github.com/openteam/server/internal/store"
+)
+
+// AdminStatsOverview GET /api/v1/admin/stats/overview — 运营总览。
+func (h *Handler) AdminStatsOverview(c *gin.Context) {
+	now := time.Now().UTC()
+	today := now.Format("2006-01-02")
+	month := now.Format("2006-01")
+
+	var totalUsers int64
+	h.a.DB.Model(&store.User{}).Count(&totalUsers)
+	var totalKeys int64
+	h.a.DB.Model(&store.APIKey{}).Count(&totalKeys)
+	var totalChannels int64
+	h.a.DB.Model(&store.Channel{}).Count(&totalChannels)
+	var totalModels int64
+	h.a.DB.Model(&store.Model{}).Count(&totalModels)
+
+	// 全局今日/本月汇总（跨用户）
+	var todayReq, monthReq int64
+	var todayCost, monthCost float64
+	var todayTokens, monthTokens int64
+	h.a.DB.Model(&store.UsageDaily{}).Where("date = ?", today).
+		Select("COALESCE(SUM(requests),0), COALESCE(SUM(cost),0), COALESCE(SUM(input_tokens+output_tokens+cache_read_tokens),0)").
+		Row().Scan(&todayReq, &todayCost, &todayTokens)
+	h.a.DB.Model(&store.UsageDaily{}).Where("date LIKE ?", month+"%").
+		Select("COALESCE(SUM(requests),0), COALESCE(SUM(cost),0), COALESCE(SUM(input_tokens+output_tokens+cache_read_tokens),0)").
+		Row().Scan(&monthReq, &monthCost, &monthTokens)
+
+	// 近 14 天趋势（日粒度）
+	var days []struct {
+		Date string
+		Req  int64
+		Cost float64
+	}
+	h.a.DB.Model(&store.UsageDaily{}).
+		Select("date, SUM(requests) req, SUM(cost) cost").
+		Where("date >= ?", now.AddDate(0, 0, -13).Format("2006-01-02")).
+		Group("date").Order("date").Scan(&days)
+	trend := make([]gin.H, 0, len(days))
+	for _, d := range days {
+		trend = append(trend, gin.H{"date": d.Date, "requests": d.Req, "cost": d.Cost})
+	}
+
+	resp.OK(c, gin.H{
+		"total_users": totalUsers, "total_keys": totalKeys,
+		"total_channels": totalChannels, "total_models": totalModels,
+		"today":    gin.H{"requests": todayReq, "cost": todayCost, "tokens": todayTokens},
+		"month":    gin.H{"requests": monthReq, "cost": monthCost, "tokens": monthTokens},
+		"trend_14d": trend,
+	})
+}
+
+// AdminUsage GET /api/v1/admin/usage — 全局用量日志（分页 + 过滤）。
+func (h *Handler) AdminUsage(c *gin.Context) {
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	size, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
+	if page < 1 {
+		page = 1
+	}
+	if size < 1 || size > 100 {
+		size = 20
+	}
+	q := h.a.DB.Model(&store.UsageLog{})
+	if from := c.Query("from"); from != "" {
+		q = q.Where("created_at >= ?", from+" 00:00:00")
+	}
+	if to := c.Query("to"); to != "" {
+		q = q.Where("created_at <= ?", to+" 23:59:59")
+	}
+	if model := c.Query("model"); model != "" {
+		q = q.Where("model_name = ?", model)
+	}
+	if user := c.Query("user_id"); user != "" {
+		q = q.Where("user_id = ?", user)
+	}
+	var total int64
+	q.Count(&total)
+	var logs []store.UsageLog
+	q.Order("id DESC").Offset((page - 1) * size).Limit(size).Find(&logs)
+	out := make([]gin.H, 0, len(logs))
+	for _, l := range logs {
+		var uname string
+		h.a.DB.Model(&store.User{}).Where("id = ?", l.UserID).Pluck("username", &uname)
+		out = append(out, gin.H{
+			"id": l.ID, "user": uname, "user_id": l.UserID, "model": l.ModelName, "protocol": l.Protocol,
+			"input_tokens": l.InputTokens, "output_tokens": l.OutputTokens,
+			"cache_read_tokens": l.CacheReadTokens, "cost": l.Cost,
+			"latency_ms": l.LatencyMS, "status": l.Status, "error_code": l.ErrorCode,
+			"created_at": l.CreatedAt,
+		})
+	}
+	resp.OK(c, gin.H{"items": out, "total": total, "page": page, "page_size": size})
+}
@@ -2,15 +2,16 @@
 package api

 import (
+	"encoding/json"
 	"net/http"
 	"strings"
 	"time"

 	"github.com/gin-gonic/gin"
 	"github.com/openteam/server/internal/app"
+	"github.com/openteam/server/internal/api/middleware"
 	"github.com/openteam/server/internal/pkg/resp"
 	"github.com/openteam/server/internal/store"
-	"gorm.io/gorm"
 )

 // Handler 聚合所有管理 API。
@@ -37,10 +38,21 @@ func (h *Handler) Register(c *gin.Context) {
 		resp.Fail(c, http.StatusBadRequest, "invalid input: "+err.Error())
 		return
 	}
-	if h.a.Cfg.Auth.RegistrationMode == "invite" {
+	// 注册模式优先读系统配置（管理后台可改），缺省用环境配置
+	mode := h.a.Cfg.Auth.RegistrationMode
+	var modeCfgRaw string
+	h.a.DB.Model(&store.SystemConfig{}).Where("key = ?", "registration_mode").Pluck("value", &modeCfgRaw)
+	var modeCfg string
+	_ = json.Unmarshal([]byte(modeCfgRaw), &modeCfg)
+	if modeCfg == "open" || modeCfg == "invite" {
+		mode = modeCfg
+	}
+	if mode == "invite" {
+		var icRaw string
+		h.a.DB.Model(&store.SystemConfig{}).Where("key = ?", "invite_codes").Pluck("value", &icRaw)
 		var ic string
-		h.a.DB.Model(&store.SystemConfig{}).Where("key = ?", "invite_codes").Pluck("value", &ic)
-		if !strings.Contains(ic, req.InviteCode) {
+		_ = json.Unmarshal([]byte(icRaw), &ic)
+		if req.InviteCode == "" || !strings.Contains(ic, req.InviteCode) {
 			resp.Fail(c, http.StatusForbidden, "valid invite code required")
 			return
 		}
@@ -182,16 +194,14 @@ func (h *Handler) publicUser(u *store.User) gin.H {
 }

 func sessionUser(c *gin.Context) *store.User {
-	u, _ := c.Get("session_user")
+	u, _ := c.Get(middleware.CtxSessionUser)
 	return u.(*store.User)
 }

 func userFromContext(c *gin.Context) (*store.User, bool) {
-	u, ok := c.Get("session_user")
+	u, ok := c.Get(middleware.CtxSessionUser)
 	if !ok {
 		return nil, false
 	}
 	return u.(*store.User), true
 }
-
-var _ = gorm.ErrRecordNotFound
@@ -12,11 +12,11 @@ import (
 )

 type createKeyReq struct {
-	Name              string    `json:"name" binding:"required,min=1,max=64"`
-	QuotaTokensPerDay *int64    `json:"quota_tokens_per_day"`
+	Name               *string  `json:"name" binding:"required,min=1,max=64"`
+	QuotaTokensPerDay  *int64   `json:"quota_tokens_per_day"`
 	QuotaRequestsPerDay *int    `json:"quota_requests_per_day"`
-	AllowedModels     []string  `json:"allowed_models"`
-	ExpiresAt         *string   `json:"expires_at"` // RFC3339
+	AllowedModels      []string `json:"allowed_models"`
+	ExpiresAt          *string  `json:"expires_at"` // RFC3339
 }

 // CreateKey POST /api/v1/keys — 创建密钥，明文仅此一次返回。
@@ -37,14 +37,14 @@ func (h *Handler) CreateKey(c *gin.Context) {
 		return
 	}
 	k := store.APIKey{
-		UserID:            u.ID,
-		Name:              req.Name,
-		KeyHash:           hash,
-		KeyPrefix:         prefix,
-		QuotaTokensPerDay: req.QuotaTokensPerDay,
+		UserID:              u.ID,
+		Name:                *req.Name,
+		KeyHash:             hash,
+		KeyPrefix:           prefix,
+		QuotaTokensPerDay:   req.QuotaTokensPerDay,
 		QuotaRequestsPerDay: req.QuotaRequestsPerDay,
-		AllowedModels:     req.AllowedModels,
-		Status:            store.KeyStatusActive,
+		AllowedModels:       req.AllowedModels,
+		Status:              store.KeyStatusActive,
 	}
 	if req.ExpiresAt != nil {
 		t, err := time.Parse(time.RFC3339, *req.ExpiresAt)
@@ -110,11 +110,11 @@ func (h *Handler) PatchKey(c *gin.Context) {
 		return
 	}
 	var req struct {
-		Name              *string   `json:"name"`
-		QuotaTokensPerDay *int64    `json:"quota_tokens_per_day"`
-		QuotaRequestsPerDay *int    `json:"quota_requests_per_day"`
-		AllowedModels     *[]string `json:"allowed_models"`
-		Status            *string   `json:"status"`
+		Name               *string   `json:"name"`
+		QuotaTokensPerDay  *int64    `json:"quota_tokens_per_day"`
+		QuotaRequestsPerDay *int     `json:"quota_requests_per_day"`
+		AllowedModels      *[]string `json:"allowed_models"`
+		Status             *string   `json:"status"`
 	}
 	if err := c.ShouldBindJSON(&req); err != nil {
 		resp.Fail(c, http.StatusBadRequest, "invalid input")
@@ -26,6 +26,7 @@ func NewRouter(a *app.App, gw *proxy.Gateway) *gin.Engine {
 	{
 		proxyGroup.Any("/chat/completions", gw.Auth, gw.Handle)
 		proxyGroup.Any("/responses", gw.Auth, gw.Handle)
+		proxyGroup.Any("/messages", gw.Auth, gw.Handle)
 		proxyGroup.Any("/models", gw.Auth, gw.Handle)
 	}
 	// 未匹配的 /v1/* 返回 OpenAI 风格 404（需先认证）
@@ -68,12 +69,31 @@ func NewRouter(a *app.App, gw *proxy.Gateway) *gin.Engine {

 		admin := api.Group("/admin", middleware.SessionAuth(a), middleware.AdminOnly)
 		{
+			// 用户
 			admin.GET("/users", h.AdminUsers)
 			admin.PATCH("/users/:id", h.AdminPatchUser)
 			admin.POST("/users/:id/balance", h.AdminAdjustBalance)
+			// 渠道
+			admin.GET("/channels", h.AdminChannels)
+			admin.POST("/channels", h.AdminCreateChannel)
+			admin.PUT("/channels/:id", h.AdminUpdateChannel)
+			admin.DELETE("/channels/:id", h.AdminDeleteChannel)
+			admin.POST("/channels/:id/test", h.AdminTestChannel)
+			admin.POST("/channels/:id/models/import", h.AdminImportChannelModels)
+			// 模型与定价
+			admin.GET("/models", h.AdminModels)
+			admin.POST("/models", h.AdminCreateModel)
+			admin.PUT("/models/:id", h.AdminUpdateModel)
+			admin.DELETE("/models/:id", h.AdminDeleteModel)
+			admin.POST("/models/:id/bindings", h.AdminCreateModelBinding)
+			admin.DELETE("/models/:id/bindings/:bid", h.AdminDeleteModelBinding)
+			// 统计与用量
+			admin.GET("/stats/overview", h.AdminStatsOverview)
+			admin.GET("/usage", h.AdminUsage)
+			// 配置
 			admin.GET("/config", h.AdminConfig)
 			admin.PUT("/config", h.AdminPutConfig)
-			// 渠道/模型/用量管理（M4）；充值审核（M5 预留）
+			// 充值审核（M6 预留）
 		}
 	}

@@ -0,0 +1,112 @@
+package api
+
+import (
+	"strconv"
+	"time"
+
+	"github.com/gin-gonic/gin"
+	"github.com/openteam/server/internal/pkg/resp"
+	"github.com/openteam/server/internal/store"
+)
+
+// UsageSummary GET /api/v1/usage/summary — 今日/本月汇总。
+func (h *Handler) UsageSummary(c *gin.Context) {
+	u, _ := userFromContext(c)
+	now := time.Now().UTC()
+	today := now.Format("2006-01-02")
+	month := now.Format("2006-01")
+
+	var todayReq, monthReq int64
+	var todayTok, monthTok int64
+	var todayCost, monthCost float64
+	h.a.DB.Model(&store.UsageDaily{}).Where("user_id = ? AND date = ?", u.ID, today).
+		Select("COALESCE(SUM(requests),0), COALESCE(SUM(input_tokens+output_tokens+cache_read_tokens),0), COALESCE(SUM(cost),0)").
+		Row().Scan(&todayReq, &todayTok, &todayCost)
+	h.a.DB.Model(&store.UsageDaily{}).Where("user_id = ? AND date LIKE ?", u.ID, month+"%").
+		Select("COALESCE(SUM(requests),0), COALESCE(SUM(input_tokens+output_tokens+cache_read_tokens),0), COALESCE(SUM(cost),0)").
+		Row().Scan(&monthReq, &monthTok, &monthCost)
+	resp.OK(c, gin.H{
+		"today": gin.H{"requests": todayReq, "tokens": todayTok, "cost": todayCost},
+		"month": gin.H{"requests": monthReq, "tokens": monthTok, "cost": monthCost},
+	})
+}
+
+// UsageStats GET /api/v1/usage/stats?from&to&group=day|model
+func (h *Handler) UsageStats(c *gin.Context) {
+	u, _ := userFromContext(c)
+	from := c.DefaultQuery("from", time.Now().Add(-30*24*time.Hour).Format("2006-01-02"))
+	to := c.DefaultQuery("to", time.Now().Format("2006-01-02"))
+	group := c.DefaultQuery("group", "day")
+
+	q := h.a.DB.Model(&store.UsageDaily{}).Where("user_id = ? AND date BETWEEN ? AND ?", u.ID, from, to)
+	out := make([]gin.H, 0, 64)
+	if group == "model" {
+		var rows []struct {
+			ModelID  uint64
+			Requests int64
+			Tokens   int64
+			Cost     float64
+		}
+		q.Select("model_id, SUM(requests) requests, SUM(input_tokens+output_tokens+cache_read_tokens) tokens, SUM(cost) cost").
+			Group("model_id").Scan(&rows)
+		for _, r := range rows {
+			var m store.Model
+			name := strconv.FormatUint(r.ModelID, 10)
+			if h.a.DB.First(&m, r.ModelID).Error == nil {
+				name = m.Name
+			}
+			out = append(out, gin.H{"model": name, "requests": r.Requests, "tokens": r.Tokens, "cost": r.Cost})
+		}
+	} else {
+		var rows []struct {
+			Date     string
+			Requests int64
+			Tokens   int64
+			Cost     float64
+		}
+		q.Select("date, SUM(requests) requests, SUM(input_tokens+output_tokens+cache_read_tokens) tokens, SUM(cost) cost").
+			Group("date").Order("date").Scan(&rows)
+		for _, r := range rows {
+			out = append(out, gin.H{"date": r.Date, "requests": r.Requests, "tokens": r.Tokens, "cost": r.Cost})
+		}
+	}
+	resp.OK(c, gin.H{"items": out})
+}
+
+// UsageLogs GET /api/v1/usage/logs?from&to&page&page_size&model
+func (h *Handler) UsageLogs(c *gin.Context) {
+	u, _ := userFromContext(c)
+	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
+	size, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
+	if page < 1 {
+		page = 1
+	}
+	if size < 1 || size > 100 {
+		size = 20
+	}
+	q := h.a.DB.Model(&store.UsageLog{}).Where("user_id = ?", u.ID)
+	if from := c.Query("from"); from != "" {
+		q = q.Where("created_at >= ?", from+" 00:00:00")
+	}
+	if to := c.Query("to"); to != "" {
+		q = q.Where("created_at <= ?", to+" 23:59:59")
+	}
+	if model := c.Query("model"); model != "" {
+		q = q.Where("model_name = ?", model)
+	}
+	var total int64
+	q.Count(&total)
+	var logs []store.UsageLog
+	q.Order("id DESC").Offset((page - 1) * size).Limit(size).Find(&logs)
+	out := make([]gin.H, 0, len(logs))
+	for _, l := range logs {
+		out = append(out, gin.H{
+			"id": l.ID, "request_id": l.RequestID, "model": l.ModelName, "protocol": l.Protocol,
+			"input_tokens": l.InputTokens, "output_tokens": l.OutputTokens,
+			"cache_read_tokens": l.CacheReadTokens, "cost": l.Cost,
+			"latency_ms": l.LatencyMS, "status": l.Status, "error_code": l.ErrorCode,
+			"created_at": l.CreatedAt,
+		})
+	}
+	resp.OK(c, gin.H{"items": out, "total": total, "page": page, "page_size": size})
+}
@@ -2,7 +2,6 @@ package api

 import (
 	"net/http"
-	"strconv"
 	"time"

 	"github.com/gin-gonic/gin"
@@ -24,10 +23,10 @@ func (h *Handler) UserBalance(c *gin.Context) {
 		Where("user_id = ? AND status = ? AND created_at >= ?", u.ID, store.UsageStatusSuccess, time.Now().Add(-30*24*time.Hour)).
 		Select("COALESCE(SUM(cost),0)").Scan(&spent)
 	resp.OK(c, gin.H{
-		"balance":           u.Balance,
-		"spent_last_30d":    spent,
-		"today":             h.todayUsage(c, u.ID),
-		"models_available":  h.availableModelCount(),
+		"balance":          u.Balance,
+		"spent_last_30d":   spent,
+		"today":            h.todayUsage(c, u.ID),
+		"models_available": h.availableModelCount(),
 	})
 }

@@ -62,104 +61,3 @@ func (h *Handler) UserModels(c *gin.Context) {
 	}
 	resp.OK(c, gin.H{"items": out})
 }
-
-// UsageSummary GET /api/v1/usage/summary — 今日/本月汇总。
-func (h *Handler) UsageSummary(c *gin.Context) {
-	u, _ := userFromContext(c)
-	now := time.Now().UTC()
-	today := now.Format("2006-01-02")
-	month := now.Format("2006-01")
-	var todayReq, monthReq int64
-	var todayTok, monthTok int64
-	var todayCost, monthCost float64
-	h.a.DB.Model(&store.UsageDaily{}).Where("user_id = ? AND date = ?", u.ID, today).
-		Select("COALESCE(SUM(requests),0), COALESCE(SUM(input_tokens+output_tokens+cache_read_tokens),0), COALESCE(SUM(cost),0)").
-		Row().Scan(&todayReq, &todayTok, &todayCost)
-	h.a.DB.Model(&store.UsageDaily{}).Where("user_id = ? AND date LIKE ?", u.ID, month+"%").
-		Select("COALESCE(SUM(requests),0), COALESCE(SUM(input_tokens+output_tokens+cache_read_tokens),0), COALESCE(SUM(cost),0)").
-		Row().Scan(&monthReq, &monthTok, &monthCost)
-	resp.OK(c, gin.H{
-		"today": gin.H{"requests": todayReq, "tokens": todayTok, "cost": todayCost},
-		"month": gin.H{"requests": monthReq, "tokens": monthTok, "cost": monthCost},
-	})
-}
-
-// UsageStats GET /api/v1/usage/stats?from&to&group=day|model
-func (h *Handler) UsageStats(c *gin.Context) {
-	u, _ := userFromContext(c)
-	from := c.DefaultQuery("from", time.Now().Add(-30*24*time.Hour).Format("2006-01-02"))
-	to := c.DefaultQuery("to", time.Now().Format("2006-01-02"))
-	group := c.DefaultQuery("group", "day")
-
-	q := h.a.DB.Model(&store.UsageDaily{}).Where("user_id = ? AND date BETWEEN ? AND ?", u.ID, from, to)
-	out := make([]gin.H, 0, 64)
-	if group == "model" {
-		var rows []struct {
-			ModelID  uint64
-			Requests int64
-			Tokens   int64
-			Cost     float64
-		}
-		q.Select("model_id, SUM(requests) requests, SUM(input_tokens+output_tokens+cache_read_tokens) tokens, SUM(cost) cost").
-			Group("model_id").Scan(&rows)
-		for _, r := range rows {
-			var m store.Model
-			name := strconv.FormatUint(r.ModelID, 10)
-			if h.a.DB.First(&m, r.ModelID).Error == nil {
-				name = m.Name
-			}
-			out = append(out, gin.H{"model": name, "requests": r.Requests, "tokens": r.Tokens, "cost": r.Cost})
-		}
-	} else {
-		var rows []struct {
-			Date     string
-			Requests int64
-			Tokens   int64
-			Cost     float64
-		}
-		q.Select("date, SUM(requests) requests, SUM(input_tokens+output_tokens+cache_read_tokens) tokens, SUM(cost) cost").
-			Group("date").Order("date").Scan(&rows)
-		for _, r := range rows {
-			out = append(out, gin.H{"date": r.Date, "requests": r.Requests, "tokens": r.Tokens, "cost": r.Cost})
-		}
-	}
-	resp.OK(c, gin.H{"items": out})
-}
-
-// UsageLogs GET /api/v1/usage/logs?from&to&page&page_size&model
-func (h *Handler) UsageLogs(c *gin.Context) {
-	u, _ := userFromContext(c)
-	page, _ := strconv.Atoi(c.DefaultQuery("page", "1"))
-	size, _ := strconv.Atoi(c.DefaultQuery("page_size", "20"))
-	if page < 1 {
-		page = 1
-	}
-	if size < 1 || size > 100 {
-		size = 20
-	}
-	q := h.a.DB.Model(&store.UsageLog{}).Where("user_id = ?", u.ID)
-	if from := c.Query("from"); from != "" {
-		q = q.Where("created_at >= ?", from+" 00:00:00")
-	}
-	if to := c.Query("to"); to != "" {
-		q = q.Where("created_at <= ?", to+" 23:59:59")
-	}
-	if model := c.Query("model"); model != "" {
-		q = q.Where("model_name = ?", model)
-	}
-	var total int64
-	q.Count(&total)
-	var logs []store.UsageLog
-	q.Order("id DESC").Offset((page - 1) * size).Limit(size).Find(&logs)
-	out := make([]gin.H, 0, len(logs))
-	for _, l := range logs {
-		out = append(out, gin.H{
-			"id": l.ID, "request_id": l.RequestID, "model": l.ModelName, "protocol": l.Protocol,
-			"input_tokens": l.InputTokens, "output_tokens": l.OutputTokens,
-			"cache_read_tokens": l.CacheReadTokens, "cost": l.Cost,
-			"latency_ms": l.LatencyMS, "status": l.Status, "error_code": l.ErrorCode,
-			"created_at": l.CreatedAt,
-		})
-	}
-	resp.OK(c, gin.H{"items": out, "total": total, "page": page, "page_size": size})
-}
@@ -102,7 +102,7 @@ func (a *App) Seed() error {
 			m := store.Model{
 				Name:        a.Cfg.Proxy.DefaultModel,
 				DisplayName: a.Cfg.Proxy.DefaultModel,
-				InputPrice:  0.15,  // 每百万 token，示例价
+				InputPrice:  0.15, // 每百万 token，示例价
 				OutputPrice: 0.60,
 				Enabled:     true,
 			}
@@ -1,6 +1,6 @@
-// Package channel 渠道仓储：选择、加解密、健康过滤。
-// M1 阶段实现最小选择逻辑（按优先级+权重取第一个健康启用的渠道），
-// 负载均衡/健康检查/故障转移在 M4 完善。
+// Package channel 渠道仓储：选择、密钥加解密、模型解析。
+// M1 实现最小选择逻辑（优先级+权重取第一个健康启用的渠道）；
+// 负载均衡/健康检查/故障转移在 M5 完善。
 package channel

 import (
@@ -48,21 +48,15 @@ func (s *Service) ResolveModel(modelName string) (*store.Channel, *store.Channel
 	}
 	var b store.ChannelModelBinding
 	if err := s.db.Where("model_id = ?", m.ID).
-		Joins("JOIN channels ON channels.id = channel_model_bindings.channel_id AND channels.enabled = ? AND channels.health_status = ?", true, store.ChannelHealthHealthy).
-		Order("channel_model_bindings.weight DESC").
-		First(&b).Error; err != nil {
+		Order("weight DESC, id ASC").First(&b).Error; err != nil {
 		return nil, nil, err
 	}
-	ch, err := s.Select()
-	if err != nil {
+	var ch store.Channel
+	if err := s.db.First(&ch, b.ChannelID).Error; err != nil {
 		return nil, nil, err
 	}
-	// 用绑定里的渠道（如果健康），否则回退默认渠道
-	if b.ChannelID != ch.ID {
-		var bound store.Channel
-		if err := s.db.First(&bound, b.ChannelID).Error; err == nil && bound.Enabled && bound.HealthStatus == store.ChannelHealthHealthy {
-			return &bound, &b, nil
-		}
+	if !ch.Enabled || ch.HealthStatus != store.ChannelHealthHealthy {
+		return nil, nil, ErrNoChannel
 	}
-	return ch, &b, nil
+	return &ch, &b, nil
 }
@@ -1,4 +1,5 @@
 // Package config 加载服务配置：.env / 环境变量 / 默认值（viper）。
+// 所有项均可用环境变量 OT_<KEY> 覆盖（点号转下划线，如 db.driver → OT_DB_DRIVER）。
 package config

 import (
@@ -25,13 +26,13 @@ type DBConfig struct {
 }

 type JWTConfig struct {
-	Secret          string
-	AccessTTL       time.Duration
-	RefreshTTL      time.Duration
-	Issuer          string
-	CookieName      string
-	CookieSecure    bool
-	CookieDomain    string
+	Secret       string
+	AccessTTL    time.Duration
+	RefreshTTL   time.Duration
+	Issuer       string
+	CookieName   string
+	CookieSecure bool
+	CookieDomain string
 }

 type AuthConfig struct {
@@ -51,7 +52,8 @@ type ProxyConfig struct {
 	Timeout            time.Duration
 }

-// loadDotEnv 读取 .env 文件并把 KEY=VALUE 注入环境变量（AutomaticEnv 会自动映射 OT_ 前缀）。
+// loadDotEnv 读取 .env 并把 KEY=VALUE 注入环境变量（AutomaticEnv 自动映射 OT_ 前缀）。
+// 已存在的环境变量优先，不覆盖。
 func loadDotEnv() {
 	data, err := os.ReadFile(".env")
 	if err != nil {
@@ -110,10 +112,6 @@ func Load() (*Config, error) {
 	v.SetDefault("proxy.default_model", "gpt-4o-mini")
 	v.SetDefault("proxy.timeout", "120s")

-	// 支持读取 .env 文件（可选，不强制）
-	v.SetConfigFile(".env")
-	_ = v.ReadInConfig()
-
 	return &Config{
 		Env:  v.GetString("env"),
 		Port: v.GetInt("port"),
@@ -5,7 +5,6 @@ package apikey
 import (
 	"crypto/rand"
 	"crypto/sha256"
-	"encoding/base64"
 	"encoding/hex"
 	"strings"
 )
@@ -47,6 +46,3 @@ func Prefix(key string) string {
 func Valid(key string) bool {
 	return strings.HasPrefix(key, prefix) && len(key) == len(prefix)+keyLen
 }
-
-// base64 占位，避免未使用导入告警
-var _ = base64.StdEncoding
@@ -2,32 +2,36 @@ package apikey

 import "testing"

-func TestGenerate(t *testing.T) {
+func TestGenerateValid(t *testing.T) {
 	plain, hash, prefix, err := Generate()
 	if err != nil {
-		t.Fatal(err)
+		t.Fatalf("Generate: %v", err)
 	}
 	if !Valid(plain) {
 		t.Fatalf("generated key invalid: %q", plain)
 	}
-	if len(plain) != 3+48 {
-		t.Fatalf("key length = %d, want 51", len(plain))
+	if len(plain) != len("sk-")+48 {
+		t.Fatalf("unexpected key length: %d", len(plain))
 	}
 	if Hash(plain) != hash {
 		t.Fatal("hash mismatch")
 	}
-	if len(prefix) > len(plain) || prefix != plain[:len(prefix)] {
-		t.Fatal("prefix must be prefix of plain key")
-	}
-	// 两次生成不重复
-	plain2, _, _, _ := Generate()
-	if plain == plain2 {
-		t.Fatal("keys should be unique")
+	if prefix != plain[:12] {
+		t.Fatalf("prefix mismatch: %s vs %s", prefix, plain[:12])
 	}
 }

-func TestValid(t *testing.T) {
-	if Valid("") || Valid("sk-short") || Valid("xxx") {
-		t.Fatal("invalid keys should be rejected")
+func TestHashStable(t *testing.T) {
+	if Hash("sk-test") != Hash("sk-test") {
+		t.Fatal("hash not stable")
+	}
+}
+
+func TestValidRejects(t *testing.T) {
+	cases := []string{"", "sk-abc", "abc-123456789012345678901234567890123456789012345678", "sk-1234567890123456789012345678901234567890123456789"}
+	for _, c := range cases {
+		if Valid(c) {
+			t.Fatalf("expected invalid: %q", c)
+		}
 	}
 }
@@ -14,6 +14,7 @@ import (
 	"golang.org/x/crypto/argon2"
 )

+// PasswordHasher argon2id 参数（来自配置）。
 type PasswordHasher struct {
 	Time    uint32
 	Memory  uint32
@@ -26,7 +27,7 @@ func NewPasswordHasher(time, memory uint32, threads uint8, keyLen uint32, saltLe
 	return &PasswordHasher{Time: time, Memory: memory, Threads: threads, KeyLen: keyLen, SaltLen: saltLen}
 }

-// HashPassword argon2id 编码为 $argon2id$v=19$m=...,t=...,p=...$salt$hash
+// HashPassword 编码为 $argon2id$v=19$m=...,t=...,p=...$salt$hash
 func (h *PasswordHasher) HashPassword(password string) (string, error) {
 	salt := make([]byte, h.SaltLen)
 	if _, err := rand.Read(salt); err != nil {
@@ -38,14 +39,13 @@ func (h *PasswordHasher) HashPassword(password string) (string, error) {
 		h.Memory, h.Time, h.Threads, enc.EncodeToString(salt), enc.EncodeToString(key)), nil
 }

-// VerifyPassword 校验密码，返回是否匹配（常数时间比较）。
+// VerifyPassword 校验密码，常数时间比较。
 func (h *PasswordHasher) VerifyPassword(encoded, password string) (bool, error) {
 	parts := strings.Split(encoded, "$")
 	if len(parts) != 6 || parts[1] != "argon2id" {
 		return false, errors.New("invalid hash format")
 	}
-	var memory uint32
-	var time uint32
+	var memory, time uint32
 	var threads uint8
 	if _, err := fmt.Sscanf(parts[3], "m=%d,t=%d,p=%d", &memory, &time, &threads); err != nil {
 		return false, err
@@ -66,6 +66,7 @@ func (h *PasswordHasher) VerifyPassword(encoded, password string) (bool, error)
 // ---------------------------------------------------------------------------
 // AES-GCM 渠道密钥加密

+// Encryptor 用主密钥加解密渠道上游 key。
 type Encryptor struct {
 	key []byte
 }
@@ -76,8 +77,7 @@ func NewEncryptor(master string) *Encryptor {
 	switch len(key) {
 	case 16, 24, 32:
 	default:
-		sum := sha256Sum(master)
-		key = sum
+		key = sha256Sum(master)
 	}
 	return &Encryptor{key: key}
 }
@@ -100,6 +100,7 @@ func (e *Encryptor) Encrypt(plain string) (string, error) {
 	return base64.StdEncoding.EncodeToString(append(nonce, ct...)), nil
 }

+// Decrypt 解析 Encrypt 的输出。
 func (e *Encryptor) Decrypt(enc string) (string, error) {
 	raw, err := base64.StdEncoding.DecodeString(enc)
 	if err != nil {
@@ -3,42 +3,43 @@ package crypto
 import "testing"

 func TestPasswordHashRoundTrip(t *testing.T) {
-	h := NewPasswordHasher(3, 64*1024, 2, 32, 16)
+	h := NewPasswordHasher(1, 64*1024, 1, 32, 16)
 	hash, err := h.HashPassword("s3cret-password")
 	if err != nil {
-		t.Fatalf("hash: %v", err)
+		t.Fatalf("HashPassword: %v", err)
 	}
 	ok, err := h.VerifyPassword(hash, "s3cret-password")
 	if err != nil || !ok {
-		t.Fatalf("verify correct password: ok=%v err=%v", ok, err)
+		t.Fatalf("VerifyPassword correct: ok=%v err=%v", ok, err)
 	}
 	ok, _ = h.VerifyPassword(hash, "wrong-password")
 	if ok {
-		t.Fatal("wrong password should not verify")
+		t.Fatal("VerifyPassword accepted wrong password")
 	}
 }

-func TestEncryptDecrypt(t *testing.T) {
-	e := NewEncryptor("master-key-0123456789abcdef")
+func TestEncryptorRoundTrip(t *testing.T) {
+	e := NewEncryptor("a-very-long-master-key-1234567890")
 	enc, err := e.Encrypt("sk-upstream-secret")
 	if err != nil {
-		t.Fatalf("encrypt: %v", err)
+		t.Fatalf("Encrypt: %v", err)
 	}
-	dec, err := e.Decrypt(enc)
-	if err != nil || dec != "sk-upstream-secret" {
-		t.Fatalf("decrypt: got %q err %v", dec, err)
+	if enc == "sk-upstream-secret" {
+		t.Fatal("ciphertext equals plaintext")
 	}
-	// 密文不可读
-	if dec == enc {
-		t.Fatal("ciphertext should differ from plaintext")
+	plain, err := e.Decrypt(enc)
+	if err != nil {
+		t.Fatalf("Decrypt: %v", err)
+	}
+	if plain != "sk-upstream-secret" {
+		t.Fatalf("round trip mismatch: %q", plain)
 	}
 }

-func TestShortMasterKeyDerived(t *testing.T) {
+func TestEncryptorShortKeyDerived(t *testing.T) {
+	// 短主密钥应派生 32 字节而非报错
 	e := NewEncryptor("short")
-	enc, _ := e.Encrypt("x")
-	dec, err := e.Decrypt(enc)
-	if err != nil || dec != "x" {
-		t.Fatalf("short key derive failed: %v", err)
+	if _, err := e.Encrypt("x"); err != nil {
+		t.Fatalf("Encrypt with short key: %v", err)
 	}
 }
@@ -8,6 +8,7 @@ import (
 	"github.com/golang-jwt/jwt/v5"
 )

+// Claims 用户声明；Subject 字段区分 "access" / "refresh"。
 type Claims struct {
 	UserID   uint64 `json:"uid"`
 	Username string `json:"uname"`
@@ -16,9 +17,9 @@ type Claims struct {
 }

 type Manager struct {
-	secret    []byte
-	issuer    string
-	accessTTL time.Duration
+	secret     []byte
+	issuer     string
+	accessTTL  time.Duration
 	refreshTTL time.Duration
 }

@@ -5,37 +5,41 @@ import (
 	"time"
 )

-func TestSignParse(t *testing.T) {
+func TestSignParseAccess(t *testing.T) {
 	m := NewManager("test-secret", "openteam", time.Hour, 24*time.Hour)
 	tok, exp, err := m.Sign(42, "alice", "admin", "access")
 	if err != nil {
-		t.Fatal(err)
+		t.Fatalf("Sign: %v", err)
 	}
-	if time.Until(exp) < 50*time.Minute {
-		t.Fatal("expiry too short")
+	if exp.Before(time.Now()) {
+		t.Fatal("expires in the past")
 	}
 	claims, err := m.Parse(tok)
 	if err != nil {
-		t.Fatal(err)
+		t.Fatalf("Parse: %v", err)
 	}
-	if claims.UserID != 42 || claims.Username != "alice" || claims.Role != "admin" || claims.Subject != "access" {
+	if claims.UserID != 42 || claims.Username != "alice" || claims.Role != "admin" {
 		t.Fatalf("claims mismatch: %+v", claims)
 	}
+	if claims.Subject != "access" {
+		t.Fatalf("subject mismatch: %s", claims.Subject)
+	}
+}
+
+func TestParseRejectsBadToken(t *testing.T) {
+	m := NewManager("test-secret", "openteam", time.Hour, 24*time.Hour)
+	if _, err := m.Parse("not-a-jwt"); err == nil {
+		t.Fatal("expected error for invalid token")
+	}
 }

 func TestExpiredToken(t *testing.T) {
-	m := NewManager("test-secret", "openteam", -time.Minute, time.Hour)
-	tok, _, _ := m.Sign(1, "a", "user", "access")
+	m := NewManager("test-secret", "openteam", -time.Hour, -time.Hour)
+	tok, _, err := m.Sign(1, "bob", "user", "access")
+	if err != nil {
+		t.Fatalf("Sign: %v", err)
+	}
 	if _, err := m.Parse(tok); err == nil {
-		t.Fatal("expired token should fail")
-	}
-}
-
-func TestWrongSecret(t *testing.T) {
-	m1 := NewManager("secret-a", "openteam", time.Hour, time.Hour)
-	m2 := NewManager("secret-b", "openteam", time.Hour, time.Hour)
-	tok, _, _ := m1.Sign(1, "a", "user", "access")
-	if _, err := m2.Parse(tok); err == nil {
-		t.Fatal("token signed with different secret should fail")
+		t.Fatal("expected error for expired token")
 	}
 }
@@ -32,8 +32,3 @@ func Created(c *gin.Context, data any) {
 func Fail(c *gin.Context, status int, message string) {
 	c.JSON(status, Body{Error: &Error{Message: message}})
 }
-
-// FailCode 带错误码的业务错误
-func FailCode(c *gin.Context, status int, code, message string) {
-	c.JSON(status, Body{Error: &Error{Message: message, Type: code}})
-}
@@ -0,0 +1,157 @@
+// Package convert 三协议互转：OpenAI Chat / OpenAI Responses / Anthropic Messages。
+// 网关以 OpenAI Chat 形状作为标准中间模型（PLANNING §5.1.1）。
+// 请求与响应（非流式）走 JSON 转换；流式走逐行 SSE 转换（见 stream.go）。
+package convert
+
+import (
+	"encoding/json"
+	"fmt"
+)
+
+// 协议标识。
+const (
+	ProtoChat      = "chat"
+	ProtoMessages  = "messages"
+	ProtoResponses = "responses"
+)
+
+// ConvertRequest 转换请求体。from==to 时原样返回。
+func ConvertRequest(body []byte, from, to string) ([]byte, error) {
+	if from == to {
+		return body, nil
+	}
+	switch {
+	case from == ProtoMessages && to == ProtoChat:
+		return messagesToChatReq(body)
+	case from == ProtoChat && to == ProtoMessages:
+		return chatToMessagesReq(body)
+	case from == ProtoResponses && to == ProtoChat:
+		return responsesToChatReq(body)
+	case from == ProtoChat && to == ProtoResponses:
+		return chatToResponsesReq(body)
+	case from == ProtoResponses && to == ProtoMessages:
+		mid, err := responsesToChatReq(body)
+		if err != nil {
+			return nil, err
+		}
+		return chatToMessagesReq(mid)
+	case from == ProtoMessages && to == ProtoResponses:
+		mid, err := messagesToChatReq(body)
+		if err != nil {
+			return nil, err
+		}
+		return chatToResponsesReq(mid)
+	}
+	return nil, fmt.Errorf("unsupported request conversion %s->%s", from, to)
+}
+
+// ConvertResponse 转换响应体（非流式）。from==to 时原样返回。
+func ConvertResponse(body []byte, from, to string) ([]byte, error) {
+	if from == to {
+		return body, nil
+	}
+	switch {
+	case from == ProtoMessages && to == ProtoChat:
+		return messagesToChatResp(body)
+	case from == ProtoChat && to == ProtoMessages:
+		return chatToMessagesResp(body)
+	case from == ProtoResponses && to == ProtoChat:
+		return responsesToChatResp(body)
+	case from == ProtoChat && to == ProtoResponses:
+		return chatToResponsesResp(body)
+	case from == ProtoResponses && to == ProtoMessages:
+		mid, err := responsesToChatResp(body)
+		if err != nil {
+			return nil, err
+		}
+		return chatToMessagesResp(mid)
+	case from == ProtoMessages && to == ProtoResponses:
+		mid, err := messagesToChatResp(body)
+		if err != nil {
+			return nil, err
+		}
+		return chatToResponsesResp(mid)
+	}
+	return nil, fmt.Errorf("unsupported response conversion %s->%s", from, to)
+}
+
+// NewStreamTransformer 构造流式逐行转换器：输入上游 SSE 一行，返回客户端 SSE 行。
+// 返回 nil 表示丢弃该行；(from==to 时无需转换)。
+func NewStreamTransformer(from, to string) func([]byte) []byte {
+	switch {
+	case from == ProtoMessages && to == ProtoChat:
+		return newMessagesToChat().line
+	case from == ProtoChat && to == ProtoMessages:
+		return newChatToMessages().line
+	case from == ProtoResponses && to == ProtoChat:
+		return newResponsesToChat().line
+	case from == ProtoChat && to == ProtoResponses:
+		return newChatToResponses().line
+	case from == ProtoResponses && to == ProtoMessages:
+		return newResponsesToMessages().line
+	case from == ProtoMessages && to == ProtoResponses:
+		return newMessagesToResponses().line
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// 工具函数
+
+// str 返回字符串字段；json.RawMessage 为字符串字面量时去引号。
+func str(raw json.RawMessage) string {
+	if len(raw) == 0 || string(raw) == "null" {
+		return ""
+	}
+	var s string
+	if json.Unmarshal(raw, &s) == nil {
+		return s
+	}
+	// 数组/对象：尝试取 type=text 的 text
+	var arr []map[string]any
+	if json.Unmarshal(raw, &arr) == nil {
+		var parts []string
+		for _, b := range arr {
+			if t, _ := b["type"].(string); t == "text" || t == "input_text" || t == "output_text" {
+				if txt, _ := b["text"].(string); txt != "" {
+					parts = append(parts, txt)
+				}
+			}
+		}
+		return joinNonEmpty(parts, "\n")
+	}
+	return ""
+}
+
+func joinNonEmpty(parts []string, sep string) string {
+	out := ""
+	for i, p := range parts {
+		if p == "" {
+			continue
+		}
+		if out != "" {
+			out += sep
+		}
+		out += p
+		_ = i
+	}
+	return out
+}
+
+// rawJSON 安全取字段；不存在或 null 返回 nil。
+func rawJSON(m map[string]json.RawMessage, key string) json.RawMessage {
+	raw, ok := m[key]
+	if !ok || string(raw) == "null" {
+		return nil
+	}
+	return raw
+}
+
+// decode 把 RawMessage 解到 map。
+func decode(raw json.RawMessage) (map[string]any, error) {
+	var m map[string]any
+	if err := json.Unmarshal(raw, &m); err != nil {
+		return nil, err
+	}
+	return m, nil
+}
@@ -0,0 +1,308 @@
+package convert
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func mustJSON(t *testing.T, v any) string {
+	t.Helper()
+	b, err := json.Marshal(v)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+	return string(b)
+}
+
+func TestChatToMessagesReq(t *testing.T) {
+	in := `{
+		"model":"claude-sonnet-5",
+		"messages":[
+			{"role":"system","content":"你是助手"},
+			{"role":"user","content":"hi"},
+			{"role":"assistant","content":"hello","tool_calls":[{"id":"call_1","function":{"name":"get_weather","arguments":"{\"city\":\"sz\"}"}}]},
+			{"role":"tool","tool_call_id":"call_1","content":"sunny"}
+		],
+		"tools":[{"type":"function","function":{"name":"get_weather","description":"查天气","parameters":{"type":"object"}}}],
+		"max_tokens":100,
+		"stream":true
+	}`
+	out, err := ConvertRequest([]byte(in), ProtoChat, ProtoMessages)
+	if err != nil {
+		t.Fatalf("convert: %v", err)
+	}
+	var m map[string]any
+	if err := json.Unmarshal(out, &m); err != nil {
+		t.Fatalf("unmarshal out: %v\n%s", err, out)
+	}
+	if m["system"] != "你是助手" {
+		t.Fatalf("system = %v", m["system"])
+	}
+	if m["max_tokens"] != float64(100) {
+		t.Fatalf("max_tokens = %v", m["max_tokens"])
+	}
+	msgs := m["messages"].([]any)
+	if len(msgs) != 3 {
+		t.Fatalf("messages len = %d", len(msgs))
+	}
+	// assistant 含 tool_use 块
+	assistant := msgs[1].(map[string]any)
+	content := assistant["content"].([]any)
+	foundToolUse := false
+	for _, c := range content {
+		cm := c.(map[string]any)
+		if cm["type"] == "tool_use" {
+			foundToolUse = true
+			if cm["name"] != "get_weather" || cm["id"] != "call_1" {
+				t.Fatalf("tool_use mismatch: %v", cm)
+			}
+		}
+	}
+	if !foundToolUse {
+		t.Fatal("expected tool_use block")
+	}
+	// tool 消息 → user 消息的 tool_result 块
+	tool := msgs[2].(map[string]any)
+	if tool["role"] != "user" {
+		t.Fatalf("tool message role = %v", tool["role"])
+	}
+}
+
+func TestMessagesToChatReq(t *testing.T) {
+	in := `{
+		"model":"gpt-4o-mini",
+		"system":"你是助手",
+		"messages":[
+			{"role":"user","content":"hi"},
+			{"role":"assistant","content":[{"type":"text","text":"hello"},{"type":"tool_use","id":"call_1","name":"get_weather","input":{"city":"sz"}}]},
+			{"role":"user","content":[{"type":"tool_result","tool_use_id":"call_1","content":"sunny"}]}
+		],
+		"tools":[{"name":"get_weather","description":"查天气","input_schema":{"type":"object"}}],
+		"max_tokens":100,
+		"stream":false
+	}`
+	out, err := ConvertRequest([]byte(in), ProtoMessages, ProtoChat)
+	if err != nil {
+		t.Fatalf("convert: %v", err)
+	}
+	var m map[string]any
+	_ = json.Unmarshal(out, &m)
+	msgs := m["messages"].([]any)
+	// system + user + assistant + tool = 4 条
+	if len(msgs) != 4 {
+		t.Fatalf("messages len = %d: %s", len(msgs), out)
+	}
+	if msgs[0].(map[string]any)["role"] != "system" {
+		t.Fatal("expected system message first")
+	}
+	assistant := msgs[2].(map[string]any)
+	if tc := assistant["tool_calls"]; tc == nil {
+		t.Fatalf("expected tool_calls in assistant: %s", out)
+	}
+	tool := msgs[3].(map[string]any)
+	if tool["role"] != "tool" || tool["tool_call_id"] != "call_1" {
+		t.Fatalf("tool message mismatch: %v", tool)
+	}
+}
+
+func TestResponsesToChatReq(t *testing.T) {
+	in := `{
+		"model":"claude-sonnet-5",
+		"instructions":"你是助手",
+		"input":"hello",
+		"tools":[{"type":"function","name":"get_weather","description":"查天气","parameters":{"type":"object"}}],
+		"max_output_tokens":200,
+		"stream":false
+	}`
+	out, err := ConvertRequest([]byte(in), ProtoResponses, ProtoChat)
+	if err != nil {
+		t.Fatalf("convert: %v", err)
+	}
+	var m map[string]any
+	_ = json.Unmarshal(out, &m)
+	msgs := m["messages"].([]any)
+	if len(msgs) != 2 {
+		t.Fatalf("messages len = %d: %s", len(msgs), out)
+	}
+	if msgs[0].(map[string]any)["role"] != "system" {
+		t.Fatal("expected system from instructions")
+	}
+	if m["max_tokens"] != float64(200) {
+		t.Fatalf("max_tokens = %v", m["max_tokens"])
+	}
+}
+
+func TestChatToResponsesReq(t *testing.T) {
+	in := mustJSON(t, map[string]any{
+		"model": "gpt-4o",
+		"messages": []any{
+			map[string]any{"role": "system", "content": "sys"},
+			map[string]any{"role": "user", "content": "hi"},
+		},
+		"max_tokens": 300,
+	})
+	out, err := ConvertRequest([]byte(in), ProtoChat, ProtoResponses)
+	if err != nil {
+		t.Fatalf("convert: %v", err)
+	}
+	var m map[string]any
+	_ = json.Unmarshal(out, &m)
+	if m["instructions"] != "sys" {
+		t.Fatalf("instructions = %v", m["instructions"])
+	}
+	if m["max_output_tokens"] != float64(300) {
+		t.Fatalf("max_output_tokens = %v", m["max_output_tokens"])
+	}
+}
+
+func TestMessagesToChatResp(t *testing.T) {
+	in := `{"id":"msg_abc","type":"message","role":"assistant","model":"claude-sonnet-5",
+		"content":[{"type":"text","text":"你好"},{"type":"tool_use","id":"call_1","name":"get_weather","input":{"city":"sz"}}],
+		"stop_reason":"tool_use","usage":{"input_tokens":10,"output_tokens":5}}`
+	out, err := ConvertResponse([]byte(in), ProtoMessages, ProtoChat)
+	if err != nil {
+		t.Fatalf("convert: %v", err)
+	}
+	var m map[string]any
+	_ = json.Unmarshal(out, &m)
+	choices := m["choices"].([]any)
+	msg := choices[0].(map[string]any)["message"].(map[string]any)
+	if msg["content"] != "你好" {
+		t.Fatalf("content = %v", msg["content"])
+	}
+	if msg["tool_calls"] == nil {
+		t.Fatal("expected tool_calls")
+	}
+	if choices[0].(map[string]any)["finish_reason"] != "tool_calls" {
+		t.Fatalf("finish_reason = %v", choices[0].(map[string]any)["finish_reason"])
+	}
+}
+
+func TestChatToMessagesResp(t *testing.T) {
+	in := `{"id":"chatcmpl-xyz","object":"chat.completion","model":"gpt-4o",
+		"choices":[{"index":0,"message":{"role":"assistant","content":"hi"},"finish_reason":"stop"}],
+		"usage":{"prompt_tokens":3,"completion_tokens":2,"total_tokens":5}}`
+	out, err := ConvertResponse([]byte(in), ProtoChat, ProtoMessages)
+	if err != nil {
+		t.Fatalf("convert: %v", err)
+	}
+	var m map[string]any
+	_ = json.Unmarshal(out, &m)
+	if m["stop_reason"] != "end_turn" {
+		t.Fatalf("stop_reason = %v", m["stop_reason"])
+	}
+	content := m["content"].([]any)
+	if content[0].(map[string]any)["text"] != "hi" {
+		t.Fatalf("content = %v", content)
+	}
+	usage := m["usage"].(map[string]any)
+	if usage["input_tokens"] != float64(3) || usage["output_tokens"] != float64(2) {
+		t.Fatalf("usage = %v", usage)
+	}
+}
+
+// ---------------------------------------------------------------------------
+// 流式转换
+
+func feedLines(t *testing.T, transformer func([]byte) []byte, lines []string) string {
+	t.Helper()
+	var sb strings.Builder
+	for _, l := range lines {
+		if out := transformer([]byte(l)); out != nil {
+			sb.Write(out)
+		}
+	}
+	return sb.String()
+}
+
+func TestStreamMessagesToChat(t *testing.T) {
+	tf := newMessagesToChat().line
+	out := feedLines(t, tf, []string{
+		"event: message_start\n",
+		`data: {"type":"message_start","message":{"id":"msg_1","model":"claude-sonnet-5"}}` + "\n\n",
+		"event: content_block_delta\n",
+		`data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"你好"}}` + "\n\n",
+		"event: message_delta\n",
+		`data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"input_tokens":10,"output_tokens":5}}` + "\n\n",
+		"event: message_stop\n",
+		`data: {"type":"message_stop"}` + "\n\n",
+	})
+	if !strings.Contains(out, `"content":"你好"`) {
+		t.Fatalf("missing content chunk: %s", out)
+	}
+	if !strings.Contains(out, `"finish_reason":"stop"`) {
+		t.Fatalf("missing finish chunk: %s", out)
+	}
+	if !strings.Contains(out, `"usage"`) {
+		t.Fatalf("missing usage chunk: %s", out)
+	}
+	if !strings.Contains(out, "data: [DONE]") {
+		t.Fatalf("missing [DONE]: %s", out)
+	}
+}
+
+func TestStreamChatToMessages(t *testing.T) {
+	tf := newChatToMessages().line
+	out := feedLines(t, tf, []string{
+		`data: {"id":"chatcmpl-1","object":"chat.completion.chunk","model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}` + "\n\n",
+		`data: {"id":"chatcmpl-1","object":"chat.completion.chunk","model":"gpt-4o","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}]}` + "\n\n",
+		`data: {"id":"chatcmpl-1","object":"chat.completion.chunk","model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}` + "\n\n",
+		`data: {"id":"chatcmpl-1","object":"chat.completion.chunk","model":"gpt-4o","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":9}}` + "\n\n",
+		"data: [DONE]\n\n",
+	})
+	if !strings.Contains(out, "event: message_start") {
+		t.Fatalf("missing message_start: %s", out)
+	}
+	if !strings.Contains(out, `"text":"你好"`) || !strings.Contains(out, `"type":"text_delta"`) {
+		t.Fatalf("missing content delta: %s", out)
+	}
+	if !strings.Contains(out, `"stop_reason":"end_turn"`) {
+		t.Fatalf("missing message_delta: %s", out)
+	}
+	if !strings.Contains(out, "event: message_stop") {
+		t.Fatalf("missing message_stop: %s", out)
+	}
+}
+
+func TestStreamResponsesToMessages(t *testing.T) {
+	tf := newResponsesToMessages().line
+	out := feedLines(t, tf, []string{
+		"event: response.created\n",
+		`data: {"type":"response.created","response":{"id":"resp_1","model":"claude-sonnet-5"}}` + "\n\n",
+		"event: response.output_text.delta\n",
+		`data: {"type":"response.output_text.delta","delta":"hi"}` + "\n\n",
+		"event: response.completed\n",
+		`data: {"type":"response.completed","response":{"id":"resp_1","status":"completed","usage":{"input_tokens":7,"output_tokens":8}}}` + "\n\n",
+	})
+	if !strings.Contains(out, "event: message_start") {
+		t.Fatalf("missing message_start: %s", out)
+	}
+	if !strings.Contains(out, `"text":"hi"`) {
+		t.Fatalf("missing content: %s", out)
+	}
+	if !strings.Contains(out, "event: message_stop") {
+		t.Fatalf("missing message_stop: %s", out)
+	}
+}
+
+func TestStreamMessagesToResponses(t *testing.T) {
+	tf := newMessagesToResponses().line
+	out := feedLines(t, tf, []string{
+		"event: message_start\n",
+		`data: {"type":"message_start","message":{"id":"msg_1","model":"claude-sonnet-5"}}` + "\n\n",
+		"event: content_block_delta\n",
+		`data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"hi"}}` + "\n\n",
+		"event: message_stop\n",
+		`data: {"type":"message_stop"}` + "\n\n",
+	})
+	if !strings.Contains(out, "event: response.created") {
+		t.Fatalf("missing response.created: %s", out)
+	}
+	if !strings.Contains(out, "event: response.output_text.delta") {
+		t.Fatalf("missing output_text.delta: %s", out)
+	}
+	if !strings.Contains(out, "event: response.completed") {
+		t.Fatalf("missing response.completed: %s", out)
+	}
+}
@@ -0,0 +1,457 @@
+package convert
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// ---------------------------------------------------------------------------
+// 请求：Chat → Messages
+
+type chatTool struct {
+	Type     string `json:"type"`
+	Function struct {
+		Name        string          `json:"name"`
+		Description string          `json:"description"`
+		Parameters  json.RawMessage `json:"parameters"`
+	} `json:"function"`
+}
+
+type chatMsg struct {
+	Role        string          `json:"role"`
+	Content     json.RawMessage `json:"content"`
+	ToolCallID  string          `json:"tool_call_id"`
+	ToolCalls   []struct {
+		ID       string `json:"id"`
+		Function struct {
+			Name      string `json:"name"`
+			Arguments string `json:"arguments"`
+		} `json:"function"`
+	} `json:"tool_calls"`
+}
+
+type chatReq struct {
+	Model       string          `json:"model"`
+	Messages    []chatMsg       `json:"messages"`
+	Tools       []chatTool      `json:"tools"`
+	Temperature *float64        `json:"temperature"`
+	TopP        *float64        `json:"top_p"`
+	MaxTokens   *int            `json:"max_tokens"`
+	Stop        []string        `json:"stop"`
+	Stream      bool            `json:"stream"`
+}
+
+// chatToMessagesReq 将 OpenAI Chat 请求转为 Anthropic Messages 请求。
+func chatToMessagesReq(body []byte) ([]byte, error) {
+	var req chatReq
+	if err := json.Unmarshal(body, &req); err != nil {
+		return nil, err
+	}
+	out := map[string]any{
+		"model":     req.Model,
+		"max_tokens": intOrNil(req.MaxTokens, 1024), // Anthropic 必填
+	}
+	if req.Stream {
+		out["stream"] = true
+	}
+	if req.Temperature != nil {
+		out["temperature"] = *req.Temperature
+	}
+	if req.TopP != nil {
+		out["top_p"] = *req.TopP
+	}
+	if len(req.Stop) > 0 {
+		out["stop_sequences"] = req.Stop
+	}
+
+	var system []string
+	msgs := make([]any, 0, len(req.Messages))
+	for _, m := range req.Messages {
+		if m.Role == "system" {
+			if s := str(m.Content); s != "" {
+				system = append(system, s)
+			}
+			continue
+		}
+		msgs = append(msgs, chatMsgToAnthropic(m))
+	}
+	if len(system) > 0 {
+		out["system"] = strings.Join(system, "\n")
+	}
+	out["messages"] = msgs
+
+	if len(req.Tools) > 0 {
+		tools := make([]any, 0, len(req.Tools))
+		for _, t := range req.Tools {
+			var params any
+			if len(t.Function.Parameters) > 0 && string(t.Function.Parameters) != "null" {
+				_ = json.Unmarshal(t.Function.Parameters, &params)
+			}
+			tools = append(tools, map[string]any{
+				"name":         t.Function.Name,
+				"description":  t.Function.Description,
+				"input_schema": params,
+			})
+		}
+		out["tools"] = tools
+	}
+	return json.Marshal(out)
+}
+
+// chatMsgToAnthropic 单条消息转 Anthropic 内容。
+func chatMsgToAnthropic(m chatMsg) any {
+	switch m.Role {
+	case "assistant":
+		content := make([]any, 0, 2)
+		if s := str(m.Content); s != "" {
+			content = append(content, map[string]any{"type": "text", "text": s})
+		}
+		for _, tc := range m.ToolCalls {
+			var input any
+			if tc.Function.Arguments != "" {
+				_ = json.Unmarshal([]byte(tc.Function.Arguments), &input)
+			}
+			content = append(content, map[string]any{
+				"type":  "tool_use",
+				"id":    tc.ID,
+				"name":  tc.Function.Name,
+				"input": input,
+			})
+		}
+		return map[string]any{"role": "assistant", "content": content}
+	case "tool":
+		return map[string]any{"role": "user", "content": []any{
+			map[string]any{"type": "tool_result", "tool_use_id": m.ToolCallID, "content": str(m.Content)},
+		}}
+	default: // user
+		var arr []map[string]any
+		if json.Unmarshal(m.Content, &arr) == nil && arr != nil {
+			blocks := make([]any, 0, len(arr))
+			for _, b := range arr {
+				switch b["type"] {
+				case "text", "input_text":
+					if t, _ := b["text"].(string); t != "" {
+						blocks = append(blocks, map[string]any{"type": "text", "text": t})
+					}
+				case "image_url":
+					var url string
+					if iu, ok := b["image_url"].(map[string]any); ok {
+						url, _ = iu["url"].(string)
+					}
+					if url != "" {
+						blocks = append(blocks, map[string]any{"type": "image", "source": map[string]any{"type": "url", "url": url}})
+					}
+				}
+			}
+			if len(blocks) > 0 {
+				return map[string]any{"role": "user", "content": blocks}
+			}
+		}
+		return map[string]any{"role": "user", "content": str(m.Content)}
+	}
+}
+
+// ---------------------------------------------------------------------------
+// 请求：Messages → Chat
+
+type messagesReq struct {
+	Model         string          `json:"model"`
+	System        json.RawMessage `json:"system"`
+	Messages      []struct {
+		Role    string          `json:"role"`
+		Content json.RawMessage `json:"content"`
+	} `json:"messages"`
+	Tools []struct {
+		Name        string          `json:"name"`
+		Description string          `json:"description"`
+		InputSchema json.RawMessage `json:"input_schema"`
+	} `json:"tools"`
+	Temperature  *float64 `json:"temperature"`
+	TopP         *float64 `json:"top_p"`
+	MaxTokens    *int     `json:"max_tokens"`
+	StopSequence []string `json:"stop_sequences"`
+	Stream       bool     `json:"stream"`
+}
+
+// messagesToChatReq 将 Anthropic Messages 请求转为 OpenAI Chat 请求。
+func messagesToChatReq(body []byte) ([]byte, error) {
+	var req messagesReq
+	if err := json.Unmarshal(body, &req); err != nil {
+		return nil, err
+	}
+	out := map[string]any{"model": req.Model}
+	if req.Stream {
+		out["stream"] = true
+	}
+	if req.Temperature != nil {
+		out["temperature"] = *req.Temperature
+	}
+	if req.TopP != nil {
+		out["top_p"] = *req.TopP
+	}
+	if req.MaxTokens != nil {
+		out["max_tokens"] = *req.MaxTokens
+	}
+	if len(req.StopSequence) > 0 {
+		out["stop"] = req.StopSequence
+	}
+
+	msgs := make([]any, 0, len(req.Messages)+1)
+	if s := str(req.System); s != "" {
+		msgs = append(msgs, map[string]any{"role": "system", "content": s})
+	}
+	for _, m := range req.Messages {
+		msgs = append(msgs, anthropicMsgToChat(m.Role, m.Content)...)
+	}
+	out["messages"] = msgs
+
+	if len(req.Tools) > 0 {
+		tools := make([]any, 0, len(req.Tools))
+		for _, t := range req.Tools {
+			tools = append(tools, map[string]any{
+				"type": "function",
+				"function": map[string]any{
+					"name":        t.Name,
+					"description": t.Description,
+					"parameters":  rawOrObject(t.InputSchema),
+				},
+			})
+		}
+		out["tools"] = tools
+	}
+	return json.Marshal(out)
+}
+
+// anthropicMsgToChat 将一条 Anthropic 消息拆成 0..N 条 Chat 消息。
+func anthropicMsgToChat(role string, content json.RawMessage) []any {
+	// 块数组优先（tool_use / tool_result 需要分块解析）
+	var blocks []map[string]any
+	if json.Unmarshal(content, &blocks) == nil && blocks != nil {
+		var out []any
+		var textParts []string
+		var toolCalls []any
+		for _, b := range blocks {
+			switch b["type"] {
+			case "text":
+				if t, _ := b["text"].(string); t != "" {
+					textParts = append(textParts, t)
+				}
+			case "tool_use":
+				id, _ := b["id"].(string)
+				name, _ := b["name"].(string)
+				args, _ := json.Marshal(b["input"])
+				toolCalls = append(toolCalls, map[string]any{
+					"id":   id,
+					"type": "function",
+					"function": map[string]any{
+						"name":      name,
+						"arguments": string(args),
+					},
+				})
+			case "tool_result":
+				callID, _ := b["tool_use_id"].(string)
+				res := strField(b["content"])
+				out = append(out, map[string]any{"role": "tool", "tool_call_id": callID, "content": res})
+			}
+		}
+		if len(textParts) > 0 || len(toolCalls) > 0 {
+			msg := map[string]any{"role": role}
+			if len(textParts) > 0 {
+				msg["content"] = strings.Join(textParts, "")
+			}
+			if len(toolCalls) > 0 {
+				msg["tool_calls"] = toolCalls
+			}
+			out = append(out, msg)
+		}
+		if len(out) > 0 {
+			return out
+		}
+	}
+	// 纯文本
+	if s := str(content); s != "" {
+		return []any{map[string]any{"role": role, "content": s}}
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// 响应：Messages → Chat
+
+type messagesResp struct {
+	ID         string `json:"id"`
+	Model      string `json:"model"`
+	Content    []struct {
+		Type  string `json:"type"`
+		Text  string `json:"text"`
+		ID    string `json:"id"`
+		Name  string `json:"name"`
+		Input json.RawMessage `json:"input"`
+	} `json:"content"`
+	StopReason string `json:"stop_reason"`
+	Usage      struct {
+		InputTokens  int64 `json:"input_tokens"`
+		OutputTokens int64 `json:"output_tokens"`
+	} `json:"usage"`
+}
+
+// messagesToChatResp 将 Anthropic Messages 响应（非流式）转为 Chat 响应。
+func messagesToChatResp(body []byte) ([]byte, error) {
+	var r messagesResp
+	if err := json.Unmarshal(body, &r); err != nil {
+		return nil, err
+	}
+	var text string
+	var toolCalls []any
+	for _, c := range r.Content {
+		switch c.Type {
+		case "text":
+			text += c.Text
+		case "tool_use":
+			args, _ := json.Marshal(c.Input)
+			toolCalls = append(toolCalls, map[string]any{
+				"id":   c.ID,
+				"type": "function",
+				"function": map[string]any{
+					"name":      c.Name,
+					"arguments": string(args),
+				},
+			})
+		}
+	}
+	msg := map[string]any{"role": "assistant", "content": text}
+	if len(toolCalls) > 0 {
+		msg["tool_calls"] = toolCalls
+	}
+	return json.Marshal(map[string]any{
+		"id":      "chatcmpl-" + strings.TrimPrefix(r.ID, "msg_"),
+		"object":  "chat.completion",
+		"model":   r.Model,
+		"created": 0,
+		"choices": []any{map[string]any{
+			"index":         0,
+			"message":       msg,
+			"finish_reason": messagesStopToChat(r.StopReason),
+		}},
+		"usage": map[string]any{
+			"prompt_tokens":     r.Usage.InputTokens,
+			"completion_tokens": r.Usage.OutputTokens,
+			"total_tokens":      r.Usage.InputTokens + r.Usage.OutputTokens,
+		},
+	})
+}
+
+// ---------------------------------------------------------------------------
+// 响应：Chat → Messages
+
+type chatResp struct {
+	ID      string `json:"id"`
+	Model   string `json:"model"`
+	Choices []struct {
+		Message struct {
+			Role      string `json:"role"`
+			Content   string `json:"content"`
+			ToolCalls []struct {
+				ID       string `json:"id"`
+				Function struct {
+					Name      string `json:"name"`
+					Arguments string `json:"arguments"`
+				} `json:"function"`
+			} `json:"tool_calls"`
+		} `json:"message"`
+		FinishReason string `json:"finish_reason"`
+	} `json:"choices"`
+	Usage struct {
+		PromptTokens     int64 `json:"prompt_tokens"`
+		CompletionTokens int64 `json:"completion_tokens"`
+	} `json:"usage"`
+}
+
+// chatToMessagesResp 将 Chat 响应（非流式）转为 Messages 响应。
+func chatToMessagesResp(body []byte) ([]byte, error) {
+	var r chatResp
+	if err := json.Unmarshal(body, &r); err != nil {
+		return nil, err
+	}
+	content := make([]any, 0, 2)
+	var finish = "end_turn"
+	if len(r.Choices) > 0 {
+		msg := r.Choices[0].Message
+		if msg.Content != "" {
+			content = append(content, map[string]any{"type": "text", "text": msg.Content})
+		}
+		for _, tc := range msg.ToolCalls {
+			var input any
+			_ = json.Unmarshal([]byte(tc.Function.Arguments), &input)
+			content = append(content, map[string]any{
+				"type":  "tool_use",
+				"id":    tc.ID,
+				"name":  tc.Function.Name,
+				"input": input,
+			})
+		}
+		finish = chatStopToMessages(r.Choices[0].FinishReason)
+	}
+	return json.Marshal(map[string]any{
+		"id":          "msg_" + strings.TrimPrefix(r.ID, "chatcmpl-"),
+		"type":        "message",
+		"role":        "assistant",
+		"model":       r.Model,
+		"content":     content,
+		"stop_reason": finish,
+		"usage": map[string]any{
+			"input_tokens":  r.Usage.PromptTokens,
+			"output_tokens": r.Usage.CompletionTokens,
+		},
+	})
+}
+
+// ---------------------------------------------------------------------------
+// 辅助
+
+func intOrNil(p *int, def int) any {
+	if p == nil {
+		return def
+	}
+	return *p
+}
+
+func rawOrObject(raw json.RawMessage) any {
+	if len(raw) == 0 || string(raw) == "null" {
+		return map[string]any{}
+	}
+	var m map[string]any
+	if json.Unmarshal(raw, &m) == nil {
+		return m
+	}
+	return map[string]any{}
+}
+
+func strField(v any) string {
+	if s, ok := v.(string); ok {
+		return s
+	}
+	return ""
+}
+
+func messagesStopToChat(s string) string {
+	switch s {
+	case "tool_use":
+		return "tool_calls"
+	case "max_tokens":
+		return "length"
+	default:
+		return "stop"
+	}
+}
+
+func chatStopToMessages(s string) string {
+	switch s {
+	case "tool_calls":
+		return "tool_use"
+	case "length":
+		return "max_tokens"
+	default:
+		return "end_turn"
+	}
+}
@@ -0,0 +1,318 @@
+package convert
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// ---------------------------------------------------------------------------
+// 请求：Responses → Chat
+
+// responsesToChatReq 将 OpenAI Responses 请求转为 Chat 请求。
+func responsesToChatReq(body []byte) ([]byte, error) {
+	var m map[string]json.RawMessage
+	if err := json.Unmarshal(body, &m); err != nil {
+		return nil, err
+	}
+	out := map[string]any{"model": str(rawJSON(m, "model"))}
+	if v, ok := m["stream"]; ok && string(v) == "true" {
+		out["stream"] = true
+	}
+	if v, ok := m["temperature"]; ok {
+		out["temperature"] = v
+	}
+	if v, ok := m["top_p"]; ok {
+		out["top_p"] = v
+	}
+	if v, ok := m["max_output_tokens"]; ok {
+		out["max_tokens"] = v
+	}
+
+	var msgs []any
+	if ins := str(rawJSON(m, "instructions")); ins != "" {
+		msgs = append(msgs, map[string]any{"role": "system", "content": ins})
+	}
+	msgs = append(msgs, responsesInputToChat(rawJSON(m, "input"))...)
+	out["messages"] = msgs
+
+	if raw := rawJSON(m, "tools"); raw != nil {
+		var tools []map[string]any
+		if json.Unmarshal(raw, &tools) == nil {
+			chatTools := make([]any, 0, len(tools))
+			for _, t := range tools {
+				chatTools = append(chatTools, map[string]any{
+					"type": "function",
+					"function": map[string]any{
+						"name":        t["name"],
+						"description": t["description"],
+						"parameters":  t["parameters"],
+					},
+				})
+			}
+			out["tools"] = chatTools
+		}
+	}
+	return json.Marshal(out)
+}
+
+// responsesInputToChat 把 Responses input 转成 Chat messages。
+func responsesInputToChat(raw json.RawMessage) []any {
+	if len(raw) == 0 || string(raw) == "null" {
+		return nil
+	}
+	// 字符串输入
+	if s := str(raw); s != "" {
+		return []any{map[string]any{"role": "user", "content": s}}
+	}
+	var items []map[string]any
+	if err := json.Unmarshal(raw, &items); err != nil || items == nil {
+		return nil
+	}
+	var out []any
+	for _, item := range items {
+		switch item["type"] {
+		case "function_call":
+			var args any
+			_ = json.Unmarshal([]byte(strField(item["arguments"])), &args)
+			out = append(out, map[string]any{
+				"role": "assistant",
+				"content": "",
+				"tool_calls": []any{map[string]any{
+					"id":   strField(item["call_id"]),
+					"type": "function",
+					"function": map[string]any{
+						"name":      strField(item["name"]),
+						"arguments": strField(item["arguments"]),
+					},
+				}},
+			})
+		case "function_call_output":
+			out = append(out, map[string]any{
+				"role":         "tool",
+				"tool_call_id": strField(item["call_id"]),
+				"content":      strField(item["output"]),
+			})
+		default: // message 条目
+			role, _ := item["role"].(string)
+			if role == "" {
+				role = "user"
+			}
+			if content, ok := item["content"].(string); ok {
+				out = append(out, map[string]any{"role": role, "content": content})
+			} else if blocks, ok := item["content"].([]any); ok {
+				var text []string
+				for _, b := range blocks {
+					if bm, ok := b.(map[string]any); ok {
+						if t, _ := bm["text"].(string); t != "" {
+							text = append(text, t)
+						}
+					}
+				}
+				out = append(out, map[string]any{"role": role, "content": strings.Join(text, "")})
+			}
+		}
+	}
+	return out
+}
+
+// ---------------------------------------------------------------------------
+// 请求：Chat → Responses
+
+// chatToResponsesReq 将 Chat 请求转为 Responses 请求。
+func chatToResponsesReq(body []byte) ([]byte, error) {
+	var req chatReq
+	if err := json.Unmarshal(body, &req); err != nil {
+		return nil, err
+	}
+	out := map[string]any{"model": req.Model}
+	if req.Stream {
+		out["stream"] = true
+	}
+	if req.Temperature != nil {
+		out["temperature"] = *req.Temperature
+	}
+	if req.TopP != nil {
+		out["top_p"] = *req.TopP
+	}
+	if req.MaxTokens != nil {
+		out["max_output_tokens"] = *req.MaxTokens
+	}
+
+	var system []string
+	var input []any
+	for _, m := range req.Messages {
+		if m.Role == "system" {
+			if s := str(m.Content); s != "" {
+				system = append(system, s)
+			}
+			continue
+		}
+		switch m.Role {
+		case "tool":
+			input = append(input, map[string]any{
+				"type":   "function_call_output",
+				"call_id": m.ToolCallID,
+				"output": str(m.Content),
+			})
+		case "assistant":
+			if len(m.ToolCalls) > 0 {
+				for _, tc := range m.ToolCalls {
+					input = append(input, map[string]any{
+						"type":      "function_call",
+						"call_id":   tc.ID,
+						"name":      tc.Function.Name,
+						"arguments": tc.Function.Arguments,
+					})
+				}
+			} else if s := str(m.Content); s != "" {
+				input = append(input, map[string]any{"type": "message", "role": "assistant", "content": []any{
+					map[string]any{"type": "input_text", "text": s},
+				}})
+			}
+		default:
+			if s := str(m.Content); s != "" {
+				input = append(input, map[string]any{"type": "message", "role": "user", "content": []any{
+					map[string]any{"type": "input_text", "text": s},
+				}})
+			}
+		}
+	}
+	if len(system) > 0 {
+		out["instructions"] = strings.Join(system, "\n")
+	}
+	if len(input) == 1 {
+		out["input"] = input[0] // 单条消息项
+	} else {
+		out["input"] = input
+	}
+
+	if len(req.Tools) > 0 {
+		tools := make([]any, 0, len(req.Tools))
+		for _, t := range req.Tools {
+			tools = append(tools, map[string]any{
+				"type":        "function",
+				"name":        t.Function.Name,
+				"description": t.Function.Description,
+				"parameters":  rawOrObject(t.Function.Parameters),
+			})
+		}
+		out["tools"] = tools
+	}
+	return json.Marshal(out)
+}
+
+// ---------------------------------------------------------------------------
+// 响应：Responses → Chat
+
+// responsesToChatResp 将 Responses 响应（非流式）转为 Chat 响应。
+func responsesToChatResp(body []byte) ([]byte, error) {
+	var m map[string]json.RawMessage
+	if err := json.Unmarshal(body, &m); err != nil {
+		return nil, err
+	}
+	var text string
+	var toolCalls []any
+	if raw := rawJSON(m, "output"); raw != nil {
+		var outputs []map[string]any
+		if json.Unmarshal(raw, &outputs) == nil {
+			for _, o := range outputs {
+				switch o["type"] {
+				case "message":
+					if content, ok := o["content"].([]any); ok {
+						for _, c := range content {
+							if cm, ok := c.(map[string]any); ok {
+								if t, _ := cm["text"].(string); t != "" {
+									text += t
+								}
+							}
+						}
+					}
+				case "function_call":
+					toolCalls = append(toolCalls, map[string]any{
+						"id":   strField(o["call_id"]),
+						"type": "function",
+						"function": map[string]any{
+							"name":      strField(o["name"]),
+							"arguments": strField(o["arguments"]),
+						},
+					})
+				}
+			}
+		}
+	}
+	msg := map[string]any{"role": "assistant", "content": text}
+	if len(toolCalls) > 0 {
+		msg["tool_calls"] = toolCalls
+	}
+	finish := "stop"
+	if string(rawJSON(m, "status")) == `"incomplete"` {
+		finish = "length"
+	}
+	var prompt, completion int64
+	if u := rawJSON(m, "usage"); u != nil {
+		var us struct {
+			InputTokens  int64 `json:"input_tokens"`
+			OutputTokens int64 `json:"output_tokens"`
+		}
+		_ = json.Unmarshal(u, &us)
+		prompt, completion = us.InputTokens, us.OutputTokens
+	}
+	return json.Marshal(map[string]any{
+		"id":      "chatcmpl-" + strings.TrimPrefix(str(rawJSON(m, "id")), "resp_"),
+		"object":  "chat.completion",
+		"model":   str(rawJSON(m, "model")),
+		"choices": []any{map[string]any{"index": 0, "message": msg, "finish_reason": finish}},
+		"usage": map[string]any{
+			"prompt_tokens":     prompt,
+			"completion_tokens": completion,
+			"total_tokens":      prompt + completion,
+		},
+	})
+}
+
+// ---------------------------------------------------------------------------
+// 响应：Chat → Responses
+
+// chatToResponsesResp 将 Chat 响应（非流式）转为 Responses 响应。
+func chatToResponsesResp(body []byte) ([]byte, error) {
+	var r chatResp
+	if err := json.Unmarshal(body, &r); err != nil {
+		return nil, err
+	}
+	output := make([]any, 0, 2)
+	var finish = "completed"
+	if len(r.Choices) > 0 {
+		msg := r.Choices[0].Message
+		if msg.Content != "" {
+			output = append(output, map[string]any{
+				"type":    "message",
+				"role":    "assistant",
+				"content": []any{map[string]any{"type": "output_text", "text": msg.Content}},
+			})
+		}
+		for _, tc := range msg.ToolCalls {
+			output = append(output, map[string]any{
+				"type":      "function_call",
+				"call_id":   tc.ID,
+				"name":      tc.Function.Name,
+				"arguments": tc.Function.Arguments,
+			})
+		}
+		if r.Choices[0].FinishReason == "length" {
+			finish = "incomplete"
+		}
+	}
+	status := finish
+	return json.Marshal(map[string]any{
+		"id":      "resp_" + strings.TrimPrefix(r.ID, "chatcmpl-"),
+		"object":  "response",
+		"model":   r.Model,
+		"status":  status,
+		"output":  output,
+		"usage": map[string]any{
+			"input_tokens":  r.Usage.PromptTokens,
+			"output_tokens": r.Usage.CompletionTokens,
+			"total_tokens":  r.Usage.PromptTokens + r.Usage.CompletionTokens,
+		},
+	})
+}
@@ -0,0 +1,478 @@
+package convert
+
+import (
+	"encoding/json"
+	"strings"
+)
+
+// sseState 记录上一行 event 名与通用状态。
+type sseState struct {
+	event string
+}
+
+// parseLine 解析一行 SSE；返回是否 data 行及其内容、是否 [DONE]。
+func (s *sseState) parseLine(line []byte) (isData bool, data string, done bool) {
+	str := strings.TrimRight(string(line), "\r\n")
+	switch {
+	case strings.HasPrefix(str, "event: "):
+		s.event = strings.TrimSpace(strings.TrimPrefix(str, "event: "))
+		return false, "", false
+	case str == "data: [DONE]":
+		return true, "[DONE]", true
+	case strings.HasPrefix(str, "data: "):
+		return true, strings.TrimPrefix(str, "data: "), false
+	default:
+		return false, "", false
+	}
+}
+
+func eventData(line string) map[string]any {
+	var m map[string]any
+	_ = json.Unmarshal([]byte(line), &m)
+	return m
+}
+
+func dataLine(obj any) []byte {
+	b, _ := json.Marshal(obj)
+	return append(append([]byte("data: "), b...), '\n', '\n')
+}
+
+func eventLine(name string, obj any) []byte {
+	b, _ := json.Marshal(obj)
+	out := append([]byte("event: "+name+"\ndata: "), b...)
+	return append(out, '\n', '\n')
+}
+
+// ---------------------------------------------------------------------------
+// Messages → Chat
+
+type messagesToChat struct {
+	sseState
+	id, model string
+}
+
+func newMessagesToChat() *messagesToChat { return &messagesToChat{} }
+
+func (t *messagesToChat) line(line []byte) []byte {
+	isData, data, done := t.parseLine(line)
+	if !isData {
+		return nil
+	}
+	if done {
+		return []byte("data: [DONE]\n\n")
+	}
+	m := eventData(data)
+	evt, _ := m["type"].(string)
+	switch evt {
+	case "message_start":
+		msg, _ := m["message"].(map[string]any)
+		t.id, _ = msg["id"].(string)
+		t.model, _ = msg["model"].(string)
+		return dataLine(map[string]any{
+			"id": "chatcmpl-" + strings.TrimPrefix(t.id, "msg_"), "object": "chat.completion.chunk", "model": t.model,
+			"choices": []any{map[string]any{"index": 0, "delta": map[string]any{"role": "assistant"}, "finish_reason": nil}},
+		})
+	case "content_block_delta":
+		delta, _ := m["delta"].(map[string]any)
+		text, _ := delta["text"].(string)
+		if text == "" {
+			return nil
+		}
+		return dataLine(map[string]any{
+			"id": "chatcmpl-" + strings.TrimPrefix(t.id, "msg_"), "object": "chat.completion.chunk", "model": t.model,
+			"choices": []any{map[string]any{"index": 0, "delta": map[string]any{"content": text}, "finish_reason": nil}},
+		})
+	case "message_delta":
+		delta, _ := m["delta"].(map[string]any)
+		stop, _ := delta["stop_reason"].(string)
+		var out [][]byte
+		out = append(out, dataLine(map[string]any{
+			"id": "chatcmpl-" + strings.TrimPrefix(t.id, "msg_"), "object": "chat.completion.chunk", "model": t.model,
+			"choices": []any{map[string]any{"index": 0, "delta": map[string]any{}, "finish_reason": messagesStopToChat(stop)}},
+		}))
+		if u, ok := m["usage"]; ok {
+			out = append(out, dataLine(map[string]any{
+				"id": "chatcmpl-" + strings.TrimPrefix(t.id, "msg_"), "object": "chat.completion.chunk", "model": t.model,
+				"choices": []any{}, "usage": u,
+			}))
+		}
+		return joinLines(out)
+	case "message_stop":
+		return []byte("data: [DONE]\n\n")
+	}
+	return nil
+}
+
+func joinLines(lines [][]byte) []byte {
+	return []byte(strings.Join(func() []string {
+		var s []string
+		for _, l := range lines {
+			s = append(s, string(l))
+		}
+		return s
+	}(), ""))
+}
+
+// ---------------------------------------------------------------------------
+// Chat → Messages
+
+type chatToMessages struct {
+	sseState
+	started      bool
+	blockStarted bool
+	model        string
+	stopReason   string
+	usage        any
+}
+
+func newChatToMessages() *chatToMessages { return &chatToMessages{} }
+
+func (t *chatToMessages) line(line []byte) []byte {
+	isData, data, done := t.parseLine(line)
+	if !isData {
+		return nil
+	}
+	if done {
+		// 汇聚最终 message_delta + content_block_stop + message_stop
+		md := map[string]any{"type": "message_delta", "delta": map[string]any{
+			"stop_reason": stopReasonOrEnd(t.stopReason), "stop_sequence": nil,
+		}}
+		if t.usage != nil {
+			md["usage"] = t.usage
+		}
+		var out [][]byte
+		out = append(out, eventLine("message_delta", md))
+		if t.blockStarted {
+			out = append(out, eventLine("content_block_stop", map[string]any{"type": "content_block_stop", "index": 0}))
+		}
+		out = append(out, eventLine("message_stop", map[string]any{"type": "message_stop"}))
+		return joinLines(out)
+	}
+	m := eventData(data)
+	// chat 块：delta / finish_reason 在 choices[0] 内
+	delta := map[string]any{}
+	if choices, ok := m["choices"].([]any); ok && len(choices) > 0 {
+		if c0, ok := choices[0].(map[string]any); ok {
+			if d, ok := c0["delta"].(map[string]any); ok {
+				delta = d
+			}
+			if fr, _ := c0["finish_reason"].(string); fr != "" {
+				t.stopReason = fr
+			}
+		}
+	}
+	if t.model == "" {
+		t.model, _ = m["model"].(string)
+	}
+	id, _ := m["id"].(string)
+
+	var out [][]byte
+	// 首个包含内容或角色的块前，先发 message_start + content_block_start
+	if !t.started {
+		role, _ := delta["role"].(string)
+		content, _ := delta["content"].(string)
+		if role == "assistant" || content != "" {
+			t.started = true
+			out = append(out, eventLine("message_start", map[string]any{
+				"type": "message_start",
+				"message": map[string]any{
+					"id": "msg_" + strings.TrimPrefix(id, "chatcmpl-"), "type": "message", "role": "assistant",
+					"model": t.model, "content": []any{}, "usage": map[string]any{"input_tokens": 0, "output_tokens": 0},
+				},
+			}))
+			out = append(out, eventLine("content_block_start", map[string]any{
+				"type": "content_block_start", "index": 0, "content_block": map[string]any{"type": "text", "text": ""},
+			}))
+			t.blockStarted = true
+		}
+	}
+	if content, _ := delta["content"].(string); content != "" {
+		if !t.started {
+			t.started = true
+			t.blockStarted = true
+			out = append(out, eventLine("message_start", map[string]any{
+				"type": "message_start",
+				"message": map[string]any{"id": "msg_" + strings.TrimPrefix(id, "chatcmpl-"), "type": "message", "role": "assistant", "model": t.model, "content": []any{}},
+			}))
+			out = append(out, eventLine("content_block_start", map[string]any{
+				"type": "content_block_start", "index": 0, "content_block": map[string]any{"type": "text", "text": ""},
+			}))
+		}
+		out = append(out, eventLine("content_block_delta", map[string]any{
+			"type": "content_block_delta", "index": 0, "delta": map[string]any{"type": "text_delta", "text": content},
+		}))
+	}
+	if u, ok := m["usage"]; ok {
+		t.usage = u
+	}
+	return joinLines(out)
+}
+
+func stopReasonOrEnd(s string) string {
+	if s == "" {
+		return "end_turn"
+	}
+	return chatStopToMessages(s)
+}
+
+// ---------------------------------------------------------------------------
+// Responses → Messages
+
+type responsesToMessages struct {
+	sseState
+	started bool
+	model   string
+	usage   any
+}
+
+func newResponsesToMessages() *responsesToMessages { return &responsesToMessages{} }
+
+func (t *responsesToMessages) line(line []byte) []byte {
+	isData, data, done := t.parseLine(line)
+	if !isData || done {
+		return nil
+	}
+	m := eventData(data)
+	evt, _ := m["type"].(string)
+	if resp, ok := m["response"].(map[string]any); ok {
+		if t.model == "" {
+			t.model, _ = resp["model"].(string)
+		}
+		if u, ok := resp["usage"]; ok {
+			t.usage = u
+		}
+	}
+	var out [][]byte
+	switch evt {
+	case "response.created":
+		if !t.started {
+			t.started = true
+			id, _ := m["response"].(map[string]any)
+			rid := ""
+			if id != nil {
+				rid, _ = id["id"].(string)
+			}
+			out = append(out, eventLine("message_start", map[string]any{
+				"type": "message_start",
+				"message": map[string]any{
+					"id": "msg_" + strings.TrimPrefix(rid, "resp_"), "type": "message", "role": "assistant",
+					"model": t.model, "content": []any{},
+				},
+			}))
+			out = append(out, eventLine("content_block_start", map[string]any{
+				"type": "content_block_start", "index": 0, "content_block": map[string]any{"type": "text", "text": ""},
+			}))
+		}
+	case "response.output_text.delta":
+		delta, _ := m["delta"].(string)
+		if delta != "" {
+			out = append(out, eventLine("content_block_delta", map[string]any{
+				"type": "content_block_delta", "index": 0, "delta": map[string]any{"type": "text_delta", "text": delta},
+			}))
+		}
+	case "response.completed":
+		out = append(out, eventLine("message_delta", map[string]any{
+			"type": "message_delta", "delta": map[string]any{"stop_reason": "end_turn", "stop_sequence": nil},
+		}))
+		out = append(out, eventLine("content_block_stop", map[string]any{"type": "content_block_stop", "index": 0}))
+		out = append(out, eventLine("message_stop", map[string]any{"type": "message_stop"}))
+	}
+	return joinLines(out)
+}
+
+// ---------------------------------------------------------------------------
+// Messages → Responses
+
+type messagesToResponses struct {
+	sseState
+	model string
+	usage any
+	done  bool
+}
+
+func newMessagesToResponses() *messagesToResponses { return &messagesToResponses{} }
+
+func (t *messagesToResponses) line(line []byte) []byte {
+	isData, data, done := t.parseLine(line)
+	if !isData || done {
+		return nil
+	}
+	m := eventData(data)
+	evt, _ := m["type"].(string)
+	if msg, ok := m["message"].(map[string]any); ok {
+		if t.model == "" {
+			t.model, _ = msg["model"].(string)
+		}
+		if u, ok := msg["usage"]; ok {
+			t.usage = u
+		}
+	}
+	if u, ok := m["usage"]; ok {
+		t.usage = u
+	}
+	var out [][]byte
+	switch evt {
+	case "message_start":
+		id, _ := m["message"].(map[string]any)
+		rid := ""
+		if id != nil {
+			rid, _ = id["id"].(string)
+		}
+		out = append(out, eventLine("response.created", map[string]any{
+			"type": "response.created",
+			"response": map[string]any{
+				"id": "resp_" + strings.TrimPrefix(rid, "msg_"), "object": "response", "model": t.model, "status": "in_progress",
+			},
+		}))
+	case "content_block_delta":
+		delta, _ := m["delta"].(map[string]any)
+		text, _ := delta["text"].(string)
+		if text != "" {
+			out = append(out, eventLine("response.output_text.delta", map[string]any{
+				"type": "response.output_text.delta", "delta": text, "item_id": "msg_1", "output_index": 0, "content_index": 0,
+			}))
+		}
+	case "message_stop":
+		if !t.done {
+			t.done = true
+			out = append(out, eventLine("response.completed", map[string]any{
+				"type": "response.completed",
+				"response": map[string]any{
+					"id": "resp_stream", "object": "response", "model": t.model, "status": "completed", "usage": t.usage,
+				},
+			}))
+		}
+	}
+	return joinLines(out)
+}
+
+// ---------------------------------------------------------------------------
+// Responses → Chat
+
+type responsesToChat struct {
+	sseState
+	id, model string
+}
+
+func newResponsesToChat() *responsesToChat { return &responsesToChat{} }
+
+func (t *responsesToChat) line(line []byte) []byte {
+	isData, data, done := t.parseLine(line)
+	if !isData {
+		return nil
+	}
+	if done {
+		return nil
+	}
+	m := eventData(data)
+	evt, _ := m["type"].(string)
+	if resp, ok := m["response"].(map[string]any); ok {
+		if t.model == "" {
+			t.model, _ = resp["model"].(string)
+		}
+		if t.id == "" {
+			t.id, _ = resp["id"].(string)
+		}
+	}
+	var out [][]byte
+	switch evt {
+	case "response.created":
+		out = append(out, dataLine(map[string]any{
+			"id": "chatcmpl-" + strings.TrimPrefix(t.id, "resp_"), "object": "chat.completion.chunk", "model": t.model,
+			"choices": []any{map[string]any{"index": 0, "delta": map[string]any{"role": "assistant"}, "finish_reason": nil}},
+		}))
+	case "response.output_text.delta":
+		delta, _ := m["delta"].(string)
+		if delta != "" {
+			out = append(out, dataLine(map[string]any{
+				"id": "chatcmpl-" + strings.TrimPrefix(t.id, "resp_"), "object": "chat.completion.chunk", "model": t.model,
+				"choices": []any{map[string]any{"index": 0, "delta": map[string]any{"content": delta}, "finish_reason": nil}},
+			}))
+		}
+	case "response.completed":
+		out = append(out, dataLine(map[string]any{
+			"id": "chatcmpl-" + strings.TrimPrefix(t.id, "resp_"), "object": "chat.completion.chunk", "model": t.model,
+			"choices": []any{map[string]any{"index": 0, "delta": map[string]any{}, "finish_reason": "stop"}},
+		}))
+		if u, ok := m["response"].(map[string]any); ok {
+			if usage, ok := u["usage"]; ok {
+				out = append(out, dataLine(map[string]any{
+					"id": "chatcmpl-" + strings.TrimPrefix(t.id, "resp_"), "object": "chat.completion.chunk", "model": t.model,
+					"choices": []any{}, "usage": usage,
+				}))
+			}
+		}
+		out = append(out, []byte("data: [DONE]\n\n"))
+	}
+	return joinLines(out)
+}
+
+// ---------------------------------------------------------------------------
+// Chat → Responses
+
+type chatToResponses struct {
+	sseState
+	model string
+	usage any
+	done  bool
+}
+
+func newChatToResponses() *chatToResponses { return &chatToResponses{} }
+
+func (t *chatToResponses) line(line []byte) []byte {
+	isData, data, done := t.parseLine(line)
+	if !isData {
+		return nil
+	}
+	if done {
+		if !t.done {
+			t.done = true
+			return eventLine("response.completed", map[string]any{
+				"type": "response.completed",
+				"response": map[string]any{
+					"id": "resp_stream", "object": "response", "model": t.model, "status": "completed", "usage": t.usage,
+				},
+			})
+		}
+		return nil
+	}
+	m := eventData(data)
+	if t.model == "" {
+		t.model, _ = m["model"].(string)
+	}
+	if u, ok := m["usage"]; ok {
+		t.usage = u
+	}
+	delta := map[string]any{}
+	var finish string
+	if choices, ok := m["choices"].([]any); ok && len(choices) > 0 {
+		if c0, ok := choices[0].(map[string]any); ok {
+			if d, ok := c0["delta"].(map[string]any); ok {
+				delta = d
+			}
+			finish, _ = c0["finish_reason"].(string)
+		}
+	}
+	var out [][]byte
+	if role, _ := delta["role"].(string); role == "assistant" {
+		out = append(out, eventLine("response.created", map[string]any{
+			"type": "response.created",
+			"response": map[string]any{"id": "resp_stream", "object": "response", "model": t.model, "status": "in_progress"},
+		}))
+	}
+	if content, _ := delta["content"].(string); content != "" {
+		out = append(out, eventLine("response.output_text.delta", map[string]any{
+			"type": "response.output_text.delta", "delta": content, "item_id": "msg_1", "output_index": 0, "content_index": 0,
+		}))
+	}
+	if finish != "" && !t.done {
+		t.done = true
+		out = append(out, eventLine("response.completed", map[string]any{
+			"type": "response.completed",
+			"response": map[string]any{
+				"id": "resp_stream", "object": "response", "model": t.model, "status": "completed", "usage": t.usage,
+			},
+		}))
+	}
+	return joinLines(out)
+}
@@ -1,5 +1,5 @@
-// Package proxy API 网关核心：代理 /v1/chat/completions、/v1/responses、/v1/models。
-// M1：对 OpenAI 渠道直通（passthrough），不转格式；M3 起加入协议转换。
+// Package proxy API 网关核心：代理 /v1/chat/completions、/v1/responses、/v1/messages、/v1/models。
+// M1 直通 OpenAI 渠道；M4 起按客户端协议 × 渠道协议自动转换（见 convert）。
 package proxy

 import (
@@ -12,6 +12,7 @@ import (
 	"github.com/openteam/server/internal/channel"
 	"github.com/openteam/server/internal/pkg/apikey"
 	"github.com/openteam/server/internal/pkg/crypto"
+	"github.com/openteam/server/internal/proxy/convert"
 	"github.com/openteam/server/internal/store"
 	"github.com/openteam/server/internal/usage"
 	"gorm.io/gorm"
@@ -43,29 +44,39 @@ func NewGateway(db *gorm.DB, enc *crypto.Encryptor, rec *usage.Recorder) *Gatewa

 // Auth 代理鉴权中间件：Bearer sk-xxx → 哈希查表 → 校验状态/过期/模型白名单。
 func (g *Gateway) Auth(c *gin.Context) {
+	// 先按路径确定客户端协议，保证 Auth 阶段错误也按协议格式返回
+	switch c.Request.URL.Path {
+	case "/v1/messages":
+		c.Set("protocol", convert.ProtoMessages)
+	case "/v1/responses":
+		c.Set("protocol", convert.ProtoResponses)
+	default:
+		c.Set("protocol", convert.ProtoChat)
+	}
+
 	auth := c.GetHeader("Authorization")
 	key := strings.TrimPrefix(auth, "Bearer ")
 	key = strings.TrimSpace(key)
 	if !apikey.Valid(key) {
-		openAIError(c, http.StatusUnauthorized, "invalid_api_key", "Invalid API key format. Expected: Bearer sk-...")
+		apiError(c, http.StatusUnauthorized, "invalid_api_key", "Invalid API key format. Expected: Bearer sk-...")
 		c.Abort()
 		return
 	}
 	hash := apikey.Hash(key)
 	var k store.APIKey
 	if err := g.db.Where("key_hash = ? AND status = ?", hash, store.KeyStatusActive).First(&k).Error; err != nil {
-		openAIError(c, http.StatusUnauthorized, "invalid_api_key", "Invalid API key")
+		apiError(c, http.StatusUnauthorized, "invalid_api_key", "Invalid API key")
 		c.Abort()
 		return
 	}
 	var u store.User
 	if err := g.db.First(&u, k.UserID).Error; err != nil || u.Status != store.UserStatusActive {
-		openAIError(c, http.StatusForbidden, "user_disabled", "User account is disabled")
+		apiError(c, http.StatusForbidden, "user_disabled", "User account is disabled")
 		c.Abort()
 		return
 	}
 	if k.ExpiresAt != nil && time.Now().After(*k.ExpiresAt) {
-		openAIError(c, http.StatusUnauthorized, "key_expired", "API key has expired")
+		apiError(c, http.StatusUnauthorized, "key_expired", "API key has expired")
 		c.Abort()
 		return
 	}
@@ -84,10 +95,12 @@ func (g *Gateway) Handle(c *gin.Context) {
 		g.chatCompletions(c)
 	case c.Request.URL.Path == "/v1/responses":
 		g.responses(c)
+	case c.Request.URL.Path == "/v1/messages":
+		g.messages(c)
 	case c.Request.URL.Path == "/v1/models" && c.Request.Method == http.MethodGet:
 		g.models(c)
 	default:
-		openAIError(c, http.StatusNotFound, "not_found", "Unknown endpoint: "+c.Request.URL.Path)
+		apiError(c, http.StatusNotFound, "not_found", "Unknown endpoint: "+c.Request.URL.Path)
 	}
 }

@@ -95,7 +108,7 @@ func (g *Gateway) Handle(c *gin.Context) {
 func (g *Gateway) models(c *gin.Context) {
 	var ms []store.Model
 	if err := g.db.Where("enabled = ?", true).Order("sort ASC, id ASC").Find(&ms).Error; err != nil {
-		openAIError(c, http.StatusInternalServerError, "internal_error", "failed to load models")
+		apiError(c, http.StatusInternalServerError, "internal_error", "failed to load models")
 		return
 	}
 	data := make([]gin.H, 0, len(ms))
@@ -110,12 +123,22 @@ func (g *Gateway) models(c *gin.Context) {
 	c.JSON(http.StatusOK, gin.H{"object": "list", "data": data})
 }

+// selectChannel 选渠道：优先按模型绑定解析，退化为全局选渠道。
+func (g *Gateway) selectChannel(c *gin.Context, model string) (*store.Channel, error) {
+	if model != "" {
+		if ch, _, err := g.ch.ResolveModel(model); err == nil {
+			return ch, nil
+		}
+	}
+	return g.ch.Select()
+}
+
 // resolveUser 取当前用户（含余额）。
 func (g *Gateway) resolveUser(c *gin.Context) (*store.User, bool) {
 	uid, _ := c.Get(CtxUserID)
 	var u store.User
 	if err := g.db.First(&u, uid).Error; err != nil {
-		openAIError(c, http.StatusUnauthorized, "invalid_api_key", "Invalid API key")
+		apiError(c, http.StatusUnauthorized, "invalid_api_key", "Invalid API key")
 		return nil, false
 	}
 	return &u, true
@@ -124,10 +147,63 @@ func (g *Gateway) resolveUser(c *gin.Context) (*store.User, bool) {
 // checkBalance 余额不足返回 402（PLANNING §4.4.3）。
 func (g *Gateway) checkBalance(c *gin.Context, u *store.User) bool {
 	if u.Balance <= 0 {
-		openAIError(c, http.StatusPaymentRequired, "insufficient_balance", "Insufficient balance. Please recharge or contact admin.")
+		apiError(c, http.StatusPaymentRequired, "insufficient_balance", "Insufficient balance. Please recharge or contact admin.")
 		return false
 	}
 	return true
 }

+// ---------------------------------------------------------------------------
+// 协议分派
+
+// upstreamProtoFor 根据渠道 provider 与客户端协议确定上游协议与路径。
+func upstreamProtoFor(provider, clientProto string) string {
+	switch provider {
+	case store.ChannelProviderAnthropic:
+		return convert.ProtoMessages
+	case store.ChannelProviderOpenAI:
+		if clientProto == convert.ProtoMessages {
+			return convert.ProtoChat
+		}
+		return clientProto
+	default: // compatible：假定 OpenAI Chat 形状
+		return convert.ProtoChat
+	}
+}
+
+func upstreamPath(proto string) string {
+	switch proto {
+	case convert.ProtoMessages:
+		return "/v1/messages"
+	case convert.ProtoResponses:
+		return "/v1/responses"
+	default:
+		return "/v1/chat/completions"
+	}
+}
+
+// upstreamPlan 描述一次代理请求的上游访问方式。
+type upstreamPlan struct {
+	path     string                 // 上游路径
+	body     []byte                 // 已转换的请求体
+	lineConv func([]byte) []byte    // 流式逐行转换（nil=直通）
+	bodyConv func([]byte) ([]byte, error) // 非流式响应体转换（nil=直通）
+}
+
+// prepareUpstream 计算上游访问计划：协议匹配直通，否则转换。
+func prepareUpstream(provider, clientProto string, body []byte) (*upstreamPlan, error) {
+	up := upstreamProtoFor(provider, clientProto)
+	plan := &upstreamPlan{path: upstreamPath(up), body: body}
+	if up != clientProto {
+		converted, err := convert.ConvertRequest(body, clientProto, up)
+		if err != nil {
+			return nil, err
+		}
+		plan.body = converted
+		plan.lineConv = convert.NewStreamTransformer(up, clientProto)
+		plan.bodyConv = func(b []byte) ([]byte, error) { return convert.ConvertResponse(b, up, clientProto) }
+	}
+	return plan, nil
+}
+
 var errNoChannel = errors.New("no available channel")
@@ -1,11 +1,10 @@
 package proxy

 import (
-	"encoding/json"
 	"net/http"

 	"github.com/gin-gonic/gin"
-	"github.com/openteam/server/internal/store"
+	"github.com/openteam/server/internal/proxy/convert"
 )

 // chatCompletions POST /v1/chat/completions
@@ -17,27 +16,28 @@ func (g *Gateway) chatCompletions(c *gin.Context) {
 	if !g.checkBalance(c, u) {
 		return
 	}
-
 	br, body, err := parseBody(c)
 	if err != nil {
-		openAIError(c, http.StatusBadRequest, "invalid_request_error", "failed to read request body")
+		apiError(c, http.StatusBadRequest, "invalid_request_error", "failed to read request body")
 		return
 	}
-	c.Set("protocol", "chat")
+	c.Set("protocol", convert.ProtoChat)
 	c.Set("model_name", br.Model)

-	ch, err := g.ch.Select()
+	ch, err := g.selectChannel(c, br.Model)
 	if err != nil {
-		openAIError(c, http.StatusServiceUnavailable, "no_channel", "No available upstream channel")
+		apiError(c, http.StatusServiceUnavailable, "no_channel", "No available upstream channel")
 		g.recordError(c, nil, nil, now(), "no_channel")
 		return
 	}
-
+	plan, err := prepareUpstream(ch.Provider, convert.ProtoChat, body)
+	if err != nil {
+		apiError(c, http.StatusInternalServerError, "conversion_error", "Failed to convert request: "+err.Error())
+		return
+	}
 	sink := &usageSink{}
 	c.Set("usage_raw", &sinkHolder{sink: sink})
-	g.doPassthrough(c, ch, "/v1/chat/completions", body, br.Stream, func(raw json.RawMessage) {
-		sink.push(raw)
-	})
+	g.doProxy(c, ch, plan, br.Stream, sink)
 }

 // responses POST /v1/responses（OpenAI Responses API）
@@ -49,33 +49,61 @@ func (g *Gateway) responses(c *gin.Context) {
 	if !g.checkBalance(c, u) {
 		return
 	}
-
 	br, body, err := parseBody(c)
 	if err != nil {
-		openAIError(c, http.StatusBadRequest, "invalid_request_error", "failed to read request body")
+		apiError(c, http.StatusBadRequest, "invalid_request_error", "failed to read request body")
 		return
 	}
-	c.Set("protocol", "responses")
+	c.Set("protocol", convert.ProtoResponses)
 	c.Set("model_name", br.Model)

-	ch, err := g.ch.Select()
+	ch, err := g.selectChannel(c, br.Model)
 	if err != nil {
-		openAIError(c, http.StatusServiceUnavailable, "no_channel", "No available upstream channel")
+		apiError(c, http.StatusServiceUnavailable, "no_channel", "No available upstream channel")
 		g.recordError(c, nil, nil, now(), "no_channel")
 		return
 	}
-	// M1 仅支持 OpenAI 原生渠道直通；Anthropic 渠道的转换在 M3
-	if ch.Provider != store.ChannelProviderOpenAI {
-		openAIError(c, http.StatusNotImplemented, "conversion_pending",
-			"Responses protocol on this channel requires format conversion (planned in M3)")
+	plan, err := prepareUpstream(ch.Provider, convert.ProtoResponses, body)
+	if err != nil {
+		apiError(c, http.StatusInternalServerError, "conversion_error", "Failed to convert request: "+err.Error())
 		return
 	}
-
 	sink := &usageSink{}
 	c.Set("usage_raw", &sinkHolder{sink: sink})
-	g.doPassthrough(c, ch, "/v1/responses", body, br.Stream, func(raw json.RawMessage) {
-		sink.push(raw)
-	})
+	g.doProxy(c, ch, plan, br.Stream, sink)
+}
+
+// messages POST /v1/messages（Anthropic Messages API）
+func (g *Gateway) messages(c *gin.Context) {
+	u, ok := g.resolveUser(c)
+	if !ok {
+		return
+	}
+	if !g.checkBalance(c, u) {
+		return
+	}
+	br, body, err := parseBody(c)
+	if err != nil {
+		apiError(c, http.StatusBadRequest, "invalid_request_error", "failed to read request body")
+		return
+	}
+	c.Set("protocol", convert.ProtoMessages)
+	c.Set("model_name", br.Model)
+
+	ch, err := g.selectChannel(c, br.Model)
+	if err != nil {
+		apiError(c, http.StatusServiceUnavailable, "no_channel", "No available upstream channel")
+		g.recordError(c, nil, nil, now(), "no_channel")
+		return
+	}
+	plan, err := prepareUpstream(ch.Provider, convert.ProtoMessages, body)
+	if err != nil {
+		apiError(c, http.StatusInternalServerError, "conversion_error", "Failed to convert request: "+err.Error())
+		return
+	}
+	sink := &usageSink{}
+	c.Set("usage_raw", &sinkHolder{sink: sink})
+	g.doProxy(c, ch, plan, br.Stream, sink)
 }

 // usageSinkHolder 桥接：gin context 里保存 sink 引用，供 finishUsage 读取最终 usage。
@@ -83,8 +111,17 @@ type sinkHolder struct {
 	sink *usageSink
 }

-// openAIError 按 OpenAI 错误格式返回（PLANNING §4.1.4）。
-func openAIError(c *gin.Context, status int, code, message string) {
+// apiError 按客户端协议返回错误体（PLANNING §5.1.4）。
+func apiError(c *gin.Context, status int, code, message string) {
+	if p, _ := c.Get("protocol"); p == convert.ProtoMessages {
+		// Anthropic 格式
+		c.AbortWithStatusJSON(status, gin.H{
+			"type": "error",
+			"error": gin.H{"type": errorTypeFor(status), "message": message},
+		})
+		return
+	}
+	// OpenAI 格式
 	c.AbortWithStatusJSON(status, gin.H{
 		"error": gin.H{
 			"message": message,
@@ -99,14 +136,10 @@ func errorTypeFor(status int) string {
 	switch status {
 	case http.StatusUnauthorized:
 		return "authentication_error"
-	case http.StatusForbidden:
+	case http.StatusForbidden, http.StatusPaymentRequired:
 		return "permission_error"
-	case http.StatusNotFound:
+	case http.StatusNotFound, http.StatusBadRequest:
 		return "invalid_request_error"
-	case http.StatusBadRequest:
-		return "invalid_request_error"
-	case http.StatusPaymentRequired:
-		return "insufficient_quota"
 	case http.StatusTooManyRequests:
 		return "rate_limit_error"
 	default:
@@ -43,24 +43,22 @@ func parseBody(c *gin.Context) (*bodyReq, []byte, error) {
 	return br, body, nil
 }

-// upstreamURL 组装上游地址：base_url + 客户端路径（/v1/chat/completions 等）。
+// upstreamURL 组装上游地址：base_url + 路径。
 func upstreamURL(ch *store.Channel, path string) string {
-	base := strings.TrimRight(ch.BaseURL, "/")
-	return base + path
+	return strings.TrimRight(ch.BaseURL, "/") + path
 }

-// doPassthrough 通用直通：替换 Authorization 为渠道密钥，转发请求。
-// convert 回调用于改写请求体（M1 直通为原样；M3 转换时改写）。
-func (g *Gateway) doPassthrough(c *gin.Context, ch *store.Channel, path string, body []byte, stream bool, outUsage func(usageRaw json.RawMessage)) {
+// doProxy 通用代理：替换 Authorization 为渠道密钥，转发请求；按 plan 决定路径与转换。
+func (g *Gateway) doProxy(c *gin.Context, ch *store.Channel, plan *upstreamPlan, stream bool, sink *usageSink) {
 	upKey, err := g.ch.UpstreamKey(ch)
 	if err != nil {
-		openAIError(c, http.StatusInternalServerError, "channel_error", "failed to decrypt channel key")
+		apiError(c, http.StatusInternalServerError, "channel_error", "failed to decrypt channel key")
 		return
 	}

-	upBody := body
-	// 流式 chat：注入 stream_options.include_usage，保证末块带 usage（OpenAI 行为）
-	if stream && path == "/v1/chat/completions" && !bytes.Contains(upBody, []byte(`"include_usage"`)) {
+	upBody := plan.body
+	// 直通 chat 流式：注入 stream_options.include_usage，保证末块带 usage（OpenAI 行为）
+	if stream && plan.path == "/v1/chat/completions" && plan.lineConv == nil && !bytes.Contains(upBody, []byte(`"include_usage"`)) {
 		var m map[string]any
 		if json.Unmarshal(upBody, &m) == nil {
 			m["stream_options"] = map[string]any{"include_usage": true}
@@ -72,9 +70,9 @@ func (g *Gateway) doPassthrough(c *gin.Context, ch *store.Channel, path string,

 	ctx, cancel := context.WithTimeout(c.Request.Context(), time.Duration(ch.TimeoutMS)*time.Millisecond)
 	defer cancel()
-	req, err := http.NewRequestWithContext(ctx, http.MethodPost, upstreamURL(ch, path), bytes.NewReader(upBody))
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, upstreamURL(ch, plan.path), bytes.NewReader(upBody))
 	if err != nil {
-		openAIError(c, http.StatusInternalServerError, "internal_error", "failed to build upstream request")
+		apiError(c, http.StatusInternalServerError, "internal_error", "failed to build upstream request")
 		return
 	}
 	req.Header.Set("Content-Type", "application/json")
@@ -83,6 +81,9 @@ func (g *Gateway) doPassthrough(c *gin.Context, ch *store.Channel, path string,
 	if ua := c.GetHeader("User-Agent"); ua != "" {
 		req.Header.Set("User-Agent", ua)
 	}
+	if plan.path == "/v1/messages" {
+		req.Header.Set("anthropic-version", "2023-06-01")
+	}
 	// 透传 OpenAI 生态请求头（组织/项目等）
 	for _, h := range []string{"OpenAI-Organization", "OpenAI-Project", "OpenAI-Beta"} {
 		if v := c.GetHeader(h); v != "" {
@@ -99,55 +100,57 @@ func (g *Gateway) doPassthrough(c *gin.Context, ch *store.Channel, path string,
 			status = http.StatusGatewayTimeout
 			msg = "Upstream request timed out"
 		}
-		openAIError(c, status, "upstream_error", msg)
+		apiError(c, status, "upstream_error", msg)
 		g.recordError(c, ch, nil, start, "upstream_error")
 		return
 	}
 	defer resp.Body.Close()

-	// 非 2xx：透传上游错误体（OpenAI 格式），并记录 error 用量
+	// 非 2xx：透传上游错误体，并记录 error 用量
 	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
 		errBody, _ := io.ReadAll(resp.Body)
 		status := resp.StatusCode
-		// 上游 5xx → 网关 502/504（重试逻辑 M4）
 		if status >= 500 {
 			status = http.StatusBadGateway
 		}
-		c.DataFromReader(status, int64(len(errBody)), "application/json", bytes.NewReader(errBody), nil)
 		c.Header("Content-Type", "application/json")
+		c.DataFromReader(status, int64(len(errBody)), "application/json", bytes.NewReader(errBody), nil)
 		g.recordError(c, ch, resp, start, "upstream_http_"+strconv.Itoa(resp.StatusCode))
 		return
 	}

-	// 成功响应
 	c.Header("Content-Type", resp.Header.Get("Content-Type"))
 	c.Status(http.StatusOK)
 	if stream {
-		g.streamCopy(c, ch, resp.Body, start, outUsage)
+		g.streamCopy(c, ch, resp.Body, start, plan.lineConv, sink)
 	} else {
-		g.copyAndCapture(c, ch, resp.Body, start, outUsage)
+		g.copyAndCapture(c, ch, resp.Body, start, plan.bodyConv, sink)
 	}
 }

-// copyAndCapture 非流式：整体转发 + 解析 usage + 记账。
-func (g *Gateway) copyAndCapture(c *gin.Context, ch *store.Channel, r io.Reader, start time.Time, outUsage func(json.RawMessage)) {
+// copyAndCapture 非流式：整体转发（可转换）+ 解析 usage + 记账。
+func (g *Gateway) copyAndCapture(c *gin.Context, ch *store.Channel, r io.Reader, start time.Time, bodyConv func([]byte) ([]byte, error), sink *usageSink) {
 	data, err := io.ReadAll(r)
 	if err != nil {
-		openAIError(c, http.StatusBadGateway, "upstream_error", "failed reading upstream response")
+		apiError(c, http.StatusBadGateway, "upstream_error", "failed reading upstream response")
 		g.recordError(c, ch, nil, start, "read_error")
 		return
 	}
-	// 尝试解析 usage（chat / responses 字段不同）
-	if usageRaw := extractUsage(data); usageRaw != nil {
-		outUsage(usageRaw)
+	if usageRaw := extractUsage(data); usageRaw != nil && sink != nil {
+		sink.push(usageRaw)
 	}
-	_, _ = c.Writer.Write(data)
+	out := data
+	if bodyConv != nil {
+		if converted, cerr := bodyConv(data); cerr == nil {
+			out = converted
+		}
+	}
+	_, _ = c.Writer.Write(out)
 	g.finishUsage(c, ch, start, store.UsageStatusSuccess, "")
 }

-// streamCopy 流式：边读上游 SSE 边写客户端，零缓冲转发；扫描 usage 行记账。
-// 客户端断连（ctx cancel）即中止上游读取。
-func (g *Gateway) streamCopy(c *gin.Context, ch *store.Channel, r io.Reader, start time.Time, outUsage func(json.RawMessage)) {
+// streamCopy 流式：边读上游 SSE 边写客户端，零缓冲转发；按 lineConv 转换；扫描 usage 记账。
+func (g *Gateway) streamCopy(c *gin.Context, ch *store.Channel, r io.Reader, start time.Time, lineConv func([]byte) []byte, sink *usageSink) {
 	w := c.Writer
 	flusher, ok := w.(http.Flusher)
 	if !ok {
@@ -158,19 +161,26 @@ func (g *Gateway) streamCopy(c *gin.Context, ch *store.Channel, r io.Reader, sta
 	for {
 		line, err := scanner.Next()
 		if line != nil {
-			if _, werr := w.Write(line); werr != nil {
-				// 客户端断开：取消上游（ctx cancel 由 request ctx 处理）
-				g.recordError(c, ch, nil, start, "client_disconnect")
-				return
+			out := line
+			if lineConv != nil {
+				out = lineConv(line)
 			}
-			flusher.Flush()
-			if usageRaw := scanUsage(line); usageRaw != nil {
-				outUsage(usageRaw)
+			if out != nil {
+				if _, werr := w.Write(out); werr != nil {
+					g.recordError(c, ch, nil, start, "client_disconnect")
+					return
+				}
+				flusher.Flush()
+			}
+			if usageRaw := scanUsage(line); usageRaw != nil && sink != nil {
+				sink.push(usageRaw)
 			}
 		}
 		if err != nil {
 			if err == io.EOF {
 				g.finishUsage(c, ch, start, store.UsageStatusSuccess, "")
+			} else if c.Request.Context().Err() != nil {
+				g.recordError(c, ch, nil, start, "client_disconnect")
 			} else {
 				g.recordError(c, ch, nil, start, "stream_read_error")
 			}
@@ -186,37 +196,34 @@ func (nopFlusher) Flush() {}
 // ---------------------------------------------------------------------------
 // usage 提取

-// usageShape 兼容 chat (prompt/completion) 与 responses (input/output) 两种命名。
+// usageShape 兼容 chat (prompt/completion)、responses (input/output)、messages (input/output) 命名。
 type usageShape struct {
-	PromptTokens     int64 `json:"prompt_tokens"`
-	CompletionTokens int64 `json:"completion_tokens"`
-	InputTokens      int64 `json:"input_tokens"`
-	OutputTokens     int64 `json:"output_tokens"`
-	TotalTokens      int64 `json:"total_tokens"`
-	// Claude 缓存口径（M3 接入）
-	CacheReadInputTokens    int64 `json:"cache_read_input_tokens"`
+	PromptTokens             int64 `json:"prompt_tokens"`
+	CompletionTokens         int64 `json:"completion_tokens"`
+	InputTokens              int64 `json:"input_tokens"`
+	OutputTokens             int64 `json:"output_tokens"`
+	TotalTokens              int64 `json:"total_tokens"`
+	CacheReadInputTokens     int64 `json:"cache_read_input_tokens"`
 	CacheCreationInputTokens int64 `json:"cache_creation_input_tokens"`
 }

-// extractUsage 从完整响应体提取 usage 子对象。
+// extractUsage 从完整响应体提取 usage 子对象（chat / responses / messages）。
 func extractUsage(data []byte) json.RawMessage {
 	var m map[string]json.RawMessage
 	if json.Unmarshal(data, &m) != nil {
 		return nil
 	}
-	if u, ok := m["usage"]; ok && string(u) != "null" {
+	if u := usageFromMap(m); u != nil {
 		return u
 	}
-	// responses 事件/响应：usage 嵌套在 response 对象内
 	if respRaw, ok := m["response"]; ok {
 		var resp map[string]json.RawMessage
 		if json.Unmarshal(respRaw, &resp) == nil {
-			if u, ok := resp["usage"]; ok && string(u) != "null" {
+			if u := usageFromMap(resp); u != nil {
 				return u
 			}
 		}
 	}
-	// chat 兜底：choices[].message.usage
 	if choices, ok := m["choices"]; ok {
 		var cs []map[string]json.RawMessage
 		if json.Unmarshal(choices, &cs) == nil {
@@ -224,7 +231,7 @@ func extractUsage(data []byte) json.RawMessage {
 				if msgRaw, ok := ch["message"]; ok {
 					var msg map[string]json.RawMessage
 					if json.Unmarshal(msgRaw, &msg) == nil {
-						if u, ok := msg["usage"]; ok && string(u) != "null" {
+						if u := usageFromMap(msg); u != nil {
 							return u
 						}
 					}
@@ -235,7 +242,7 @@ func extractUsage(data []byte) json.RawMessage {
 	return nil
 }

-// scanUsage 从 SSE 一行中提取 usage（OpenAI 末块 / responses completed 事件）。
+// scanUsage 从 SSE 一行中提取 usage（OpenAI 末块 / responses completed / messages message_delta 等）。
 func scanUsage(line []byte) json.RawMessage {
 	s := string(line)
 	if !strings.Contains(s, `"usage"`) {
@@ -252,14 +259,29 @@ func scanUsage(line []byte) json.RawMessage {
 	if json.Unmarshal([]byte(s), &m) != nil {
 		return nil
 	}
-	if u, ok := m["usage"]; ok && string(u) != "null" {
+	if u := usageFromMap(m); u != nil {
 		return u
 	}
-	// responses 流式：usage 在 response 对象内（response.completed 事件）
 	if respRaw, ok := m["response"]; ok {
 		var resp map[string]json.RawMessage
 		if json.Unmarshal(respRaw, &resp) == nil {
-			if u, ok := resp["usage"]; ok && string(u) != "null" {
+			if u := usageFromMap(resp); u != nil {
+				return u
+			}
+		}
+	}
+	return nil
+}
+
+// usageFromMap 从 map 顶层或 message 子对象中取 usage。
+func usageFromMap(m map[string]json.RawMessage) json.RawMessage {
+	if u, ok := m["usage"]; ok && string(u) != "null" {
+		return u
+	}
+	if msgRaw, ok := m["message"]; ok {
+		var msg map[string]json.RawMessage
+		if json.Unmarshal(msgRaw, &msg) == nil {
+			if u, ok := msg["usage"]; ok && string(u) != "null" {
 				return u
 			}
 		}
@@ -268,7 +290,6 @@ func scanUsage(line []byte) json.RawMessage {
 }

 // sseScanner 按 SSE 行边界读取（兼容 \n 与 \r\n），保留原始行内容。
-// 基于 bufio.Reader：行内可含任意内容，跨 chunk 自动拼接。
 type sseScanner struct {
 	r *bufio.Reader
 }
@@ -289,17 +310,43 @@ func (s *sseScanner) Next() ([]byte, error) {
 // ---------------------------------------------------------------------------
 // 记账

-// usageSink 累积流式多次 usage（取最后一次，即最终值）。
+// usageSink 累积多次 usage：合并各事件字段（message_start 给 input，message_delta 给 output）。
 type usageSink struct {
-	last json.RawMessage
+	us usageShape
 }

 func (u *usageSink) push(raw json.RawMessage) {
-	if len(raw) > 0 {
-		u.last = raw
+	if len(raw) == 0 {
+		return
+	}
+	var t usageShape
+	if json.Unmarshal(raw, &t) != nil {
+		return
+	}
+	// 零值不覆盖：不同事件携带不同字段
+	if t.PromptTokens > 0 {
+		u.us.PromptTokens = t.PromptTokens
+	}
+	if t.CompletionTokens > 0 {
+		u.us.CompletionTokens = t.CompletionTokens
+	}
+	if t.InputTokens > 0 {
+		u.us.InputTokens = t.InputTokens
+	}
+	if t.OutputTokens > 0 {
+		u.us.OutputTokens = t.OutputTokens
+	}
+	if t.CacheReadInputTokens > 0 {
+		u.us.CacheReadInputTokens = t.CacheReadInputTokens
+	}
+	if t.CacheCreationInputTokens > 0 {
+		u.us.CacheCreationInputTokens = t.CacheCreationInputTokens
 	}
 }

+// Shape 返回合并后的用量。
+func (u *usageSink) Shape() usageShape { return u.us }
+
 // finishUsage 落账：计算成本并异步写入。
 func (g *Gateway) finishUsage(c *gin.Context, ch *store.Channel, start time.Time, status, errCode string) {
 	uid, _ := c.Get(CtxUserID)
@@ -308,8 +355,8 @@ func (g *Gateway) finishUsage(c *gin.Context, ch *store.Channel, start time.Time

 	var us usageShape
 	if h, ok := c.Get("usage_raw"); ok {
-		if holder, ok := h.(*sinkHolder); ok && holder.sink != nil && len(holder.sink.last) > 0 {
-			_ = json.Unmarshal(holder.sink.last, &us)
+		if holder, ok := h.(*sinkHolder); ok && holder.sink != nil {
+			us = holder.sink.Shape()
 		}
 	}

@@ -340,43 +387,57 @@ func (g *Gateway) finishUsage(c *gin.Context, ch *store.Channel, start time.Time
 		p = "chat"
 	}
 	traceStr, _ := trace.(string)
-	errMsg := errCode
 	latency := int(time.Since(start).Milliseconds())

-	// 已写响应头但流中途出错：记 error
 	if status == store.UsageStatusSuccess && c.Writer.Status() >= 400 {
 		status = store.UsageStatusError
 	}

+	var errCodePtr *string
+	if errCode != "" {
+		errCodePtr = &errCode
+	}
+
+	var uidVal, kidVal uint64
+	if u, ok := uid.(uint64); ok {
+		uidVal = u
+	}
+	if k, ok := kid.(uint64); ok {
+		kidVal = k
+	}
+	var chID uint64
+	if ch != nil {
+		chID = ch.ID
+	}
+
 	g.rec.Record(&store.UsageLog{
-		RequestID:   fmt.Sprintf("trace-%s", traceStr),
-		TraceID:     traceStr,
-		UserID:      uid.(uint64),
-		KeyID:       kid.(uint64),
-		ChannelID:   ch.ID,
-		ModelID:     modelID,
-		ModelName:   mn,
-		Protocol:    p,
-		InputTokens: in,
-		OutputTokens: out,
-		CacheReadTokens: cacheRead,
+		RequestID:           fmt.Sprintf("trace-%s", traceStr),
+		TraceID:             traceStr,
+		UserID:              uidVal,
+		KeyID:               kidVal,
+		ChannelID:           chID,
+		ModelID:             modelID,
+		ModelName:           mn,
+		Protocol:            p,
+		InputTokens:         in,
+		OutputTokens:        out,
+		CacheReadTokens:     cacheRead,
 		CacheCreationTokens: cacheCreate,
-		InputPrice:  model.InputPrice,
-		OutputPrice: model.OutputPrice,
-		CacheReadPrice: model.CacheReadPrice,
-		Cost:        cost,
-		LatencyMS:   latency,
-		Status:      status,
-		ErrorCode:   &errMsg,
-		CreatedAt:   time.Now().UTC(),
+		InputPrice:          model.InputPrice,
+		OutputPrice:         model.OutputPrice,
+		CacheReadPrice:      model.CacheReadPrice,
+		Cost:                cost,
+		LatencyMS:           latency,
+		Status:              status,
+		ErrorCode:           errCodePtr,
+		CreatedAt:           time.Now().UTC(),
 	})
 }

 // recordError 失败请求的记账（不产生扣费，status=error）。
 func (g *Gateway) recordError(c *gin.Context, ch *store.Channel, resp *http.Response, start time.Time, code string) {
-	status := store.UsageStatusError
 	_ = resp
-	g.finishUsage(c, ch, start, status, code)
+	g.finishUsage(c, ch, start, store.UsageStatusError, code)
 }

 func now() time.Time { return time.Now() }
@@ -3,105 +3,123 @@ package proxy
 import (
 	"encoding/json"
 	"io"
+	"strings"
 	"testing"
 )

-func TestScanUsageChat(t *testing.T) {
-	line := []byte(`data: {"id":"x","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":9,"total_tokens":21}}`)
-	raw := scanUsage(line)
+func TestSSEScannerSplitsLines(t *testing.T) {
+	input := "event: message\ndata: {\"a\":1}\n\n" +
+		"data: {\"b\":2}\r\n\r\n" +
+		"data: [DONE]\n\n"
+	s := newSSEScanner(strings.NewReader(input))
+	var lines []string
+	for {
+		line, err := s.Next()
+		if line != nil {
+			lines = append(lines, string(line))
+		}
+		if err == io.EOF {
+			break
+		}
+		if err != nil {
+			t.Fatalf("Next: %v", err)
+		}
+	}
+	want := []string{
+		"event: message\n",
+		"data: {\"a\":1}\n",
+		"\n",
+		"data: {\"b\":2}\r\n",
+		"\r\n",
+		"data: [DONE]\n",
+		"\n",
+	}
+	if len(lines) != len(want) {
+		t.Fatalf("line count = %d, want %d (lines: %q)", len(lines), len(want), lines)
+	}
+	for i := range want {
+		if lines[i] != want[i] {
+			t.Fatalf("line[%d] = %q, want %q", i, lines[i], want[i])
+		}
+	}
+}
+
+func TestScanUsageChatStream(t *testing.T) {
+	chunk := `data: {"id":"x","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":9,"total_tokens":21}}`
+	raw := scanUsage([]byte(chunk + "\n"))
 	if raw == nil {
-		t.Fatal("chat usage not detected")
+		t.Fatal("expected usage extracted")
 	}
 	var us usageShape
 	if err := json.Unmarshal(raw, &us); err != nil {
-		t.Fatal(err)
+		t.Fatalf("unmarshal: %v", err)
 	}
 	if us.PromptTokens != 12 || us.CompletionTokens != 9 {
 		t.Fatalf("usage mismatch: %+v", us)
 	}
 }

-func TestScanUsageResponsesNested(t *testing.T) {
-	line := []byte(`data: {"response":{"id":"r","status":"completed","usage":{"input_tokens":15,"output_tokens":11,"total_tokens":26}},"type":"response.completed"}`)
-	raw := scanUsage(line)
+func TestScanUsageResponsesCompleted(t *testing.T) {
+	line := `data: {"type":"response.completed","response":{"id":"r1","status":"completed","usage":{"input_tokens":15,"output_tokens":11}}}`
+	raw := scanUsage([]byte(line + "\n"))
 	if raw == nil {
-		t.Fatal("responses nested usage not detected")
+		t.Fatal("expected usage extracted from response.completed")
 	}
 	var us usageShape
-	if err := json.Unmarshal(raw, &us); err != nil {
-		t.Fatal(err)
-	}
+	_ = json.Unmarshal(raw, &us)
 	if us.InputTokens != 15 || us.OutputTokens != 11 {
 		t.Fatalf("usage mismatch: %+v", us)
 	}
 }

-func TestScanUsageIgnoresNonData(t *testing.T) {
-	if scanUsage([]byte("event: response.completed")) != nil {
-		t.Fatal("event line should be ignored")
+func TestScanUsageIgnoresNonUsage(t *testing.T) {
+	if raw := scanUsage([]byte(`data: {"type":"response.output_text.delta","delta":"hi"}`)); raw != nil {
+		t.Fatalf("expected nil for non-usage line, got %s", raw)
 	}
-	if scanUsage([]byte("data: [DONE]")) != nil {
-		t.Fatal("[DONE] should be ignored")
-	}
-	if scanUsage([]byte("data: {\"choices\":[{\"delta\":{\"content\":\"hi\"}}]}")) != nil {
-		t.Fatal("content chunk without usage should be ignored")
+	if raw := scanUsage([]byte(`data: [DONE]`)); raw != nil {
+		t.Fatal("expected nil for [DONE]")
 	}
 }

-func TestExtractUsageFromFullBody(t *testing.T) {
-	body := []byte(`{"id":"x","choices":[{"message":{"content":"hi"}}],"usage":{"prompt_tokens":1,"completion_tokens":2}}`)
-	raw := extractUsage(body)
+func TestExtractUsageChatBody(t *testing.T) {
+	body := `{"id":"x","choices":[{"message":{"role":"assistant","content":"hi"}}],"usage":{"prompt_tokens":1,"completion_tokens":2,"total_tokens":3}}`
+	raw := extractUsage([]byte(body))
 	if raw == nil {
-		t.Fatal("usage not extracted from full body")
+		t.Fatal("expected usage")
+	}
+	if !strings.Contains(string(raw), `"prompt_tokens":1`) {
+		t.Fatalf("unexpected usage: %s", raw)
+	}
+}
+
+func TestExtractUsageResponsesNested(t *testing.T) {
+	// responses 顶层只有 response 对象，usage 嵌套其中
+	body := `{"id":"r1","object":"response","status":"completed","response":{"usage":{"input_tokens":7,"output_tokens":8}}}`
+	raw := extractUsage([]byte(body))
+	if raw == nil {
+		t.Fatal("expected nested usage")
 	}
 	var us usageShape
 	_ = json.Unmarshal(raw, &us)
-	if us.PromptTokens != 1 || us.CompletionTokens != 2 {
+	if us.InputTokens != 7 || us.OutputTokens != 8 {
 		t.Fatalf("usage mismatch: %+v", us)
 	}
 }

-func TestSSEScannerLines(t *testing.T) {
-	// 模拟分块写入的 SSE 流
-	data := "data: {\"a\":1}\n\ndata: {\"usage\":{\"input_tokens\":3}}\n\n"
-	parts := [][]byte{[]byte(data[:10]), []byte(data[10:20]), []byte(data[20:])}
-	reader := newChunkReader(parts)
-	s := newSSEScanner(reader)
-	var lines [][]byte
-	for {
-		line, err := s.Next()
-		if line != nil {
-			lines = append(lines, line)
-		}
-		if err != nil {
-			break
-		}
+func TestUsageSinkMergesFields(t *testing.T) {
+	// message_start 给 input，message_delta 给 output，合并后两者都在
+	s := &usageSink{}
+	s.push(json.RawMessage(`{"input_tokens":14,"output_tokens":0}`))
+	s.push(json.RawMessage(`{"output_tokens":10}`))
+	got := s.Shape()
+	if got.InputTokens != 14 || got.OutputTokens != 10 {
+		t.Fatalf("merge mismatch: %+v", got)
 	}
-	if len(lines) != 4 {
-		t.Fatalf("expected 4 lines, got %d", len(lines))
-	}
-	// 合并后应能还原原始数据
-	joined := ""
-	for _, l := range lines {
-		joined += string(l)
-	}
-	if joined != string(data) {
-		t.Fatalf("stream corrupted:\n got: %q\nwant: %q", joined, data)
+	// chat 末块同时携带两字段
+	s2 := &usageSink{}
+	s2.push(json.RawMessage(`{"prompt_tokens":12,"completion_tokens":9}`))
+	g := s2.Shape()
+	if g.PromptTokens != 12 || g.CompletionTokens != 9 {
+		t.Fatalf("chat usage mismatch: %+v", g)
 	}
 }
-
-type chunkReader struct {
-	parts [][]byte
-	idx   int
-}
-
-func newChunkReader(parts [][]byte) *chunkReader { return &chunkReader{parts: parts} }
-
-func (r *chunkReader) Read(p []byte) (int, error) {
-	if r.idx >= len(r.parts) {
-		return 0, io.EOF
-	}
-	n := copy(p, r.parts[r.idx])
-	r.idx++
-	return n, nil
-}
@@ -2,6 +2,9 @@ package store

 import (
 	"log"
+	"os"
+	"path/filepath"
+	"strings"

 	"github.com/glebarez/sqlite"
 	"gorm.io/gorm"
@@ -16,6 +19,10 @@ func Open(driver, dsn string) (*gorm.DB, error) {
 	case "postgres":
 		dialector = postgresDialector(dsn)
 	default:
+		// 确保 SQLite 文件所在目录存在
+		if dir := sqliteDir(dsn); dir != "" {
+			_ = os.MkdirAll(dir, 0o755)
+		}
 		dialector = sqlite.Open(dsn)
 	}

@@ -32,3 +39,18 @@ func Open(driver, dsn string) (*gorm.DB, error) {
 	log.Printf("store: connected driver=%s (migrated)", driver)
 	return db, nil
 }
+
+// sqliteDir 提取 SQLite DSN 中的目录部分（忽略 file: 前缀与查询参数）。
+func sqliteDir(dsn string) string {
+	d := dsn
+	if i := strings.IndexByte(d, '?'); i >= 0 {
+		d = d[:i]
+	}
+	if strings.HasPrefix(d, "file:") {
+		d = d[len("file:"):]
+	}
+	if d == "" || d == ":memory:" || strings.Contains(d, "::") {
+		return ""
+	}
+	return filepath.Dir(d)
+}
@@ -1,10 +1,8 @@
 // Package store 数据模型与仓储层（GORM）。
-// 字段设计对应 PLANNING.md §5：金额/价格 numeric(20,8)，token bigint，时间 UTC。
+// 字段设计对应 PLANNING.md §6：金额/价格 numeric(20,8)，token bigint，时间 UTC。
 package store

-import (
-	"time"
-)
+import "time"

 // 角色 / 状态枚举（字符串存库，便于阅读与迁移）
 const (
@@ -17,20 +15,20 @@ const (
 	KeyStatusActive  = "active"
 	KeyStatusRevoked = "revoked"

-	ChannelProviderOpenAI      = "openai"
-	ChannelProviderAnthropic   = "anthropic"
-	ChannelProviderCompatible  = "compatible"
-	ChannelHealthHealthy       = "healthy"
-	ChannelHealthDegraded      = "degraded"
-	ChannelHealthCooldown      = "cooldown"
+	ChannelProviderOpenAI     = "openai"
+	ChannelProviderAnthropic  = "anthropic"
+	ChannelProviderCompatible = "compatible"
+	ChannelHealthHealthy      = "healthy"
+	ChannelHealthDegraded     = "degraded"
+	ChannelHealthCooldown     = "cooldown"

 	UsageStatusSuccess  = "success"
 	UsageStatusError    = "error"
 	UsageStatusCanceled = "canceled"

-	BalanceTypeRecharge   = "recharge"
-	BalanceTypeUsage      = "usage"
-	BalanceTypeRefund     = "refund"
+	BalanceTypeRecharge    = "recharge"
+	BalanceTypeUsage       = "usage"
+	BalanceTypeRefund      = "refund"
 	BalanceTypeAdminAdjust = "admin_adjust"

 	RechargeStatusPending  = "pending"
@@ -40,7 +38,7 @@ const (
 	RechargeMethodOnline   = "online"
 )

-// User 用户（PLANNING §5.1）
+// User 用户（PLANNING §6.1）
 type User struct {
 	ID           uint64     `gorm:"primaryKey;autoIncrement" json:"id"`
 	Username     string     `gorm:"uniqueIndex;size:64;not null" json:"username"`
@@ -55,7 +53,7 @@ type User struct {
 	UpdatedAt    time.Time  `json:"updated_at"`
 }

-// APIKey 密钥（PLANNING §5.2）：库中只存 SHA-256 哈希 + 展示前缀
+// APIKey 密钥（PLANNING §6.2）：库中只存 SHA-256 哈希 + 展示前缀
 type APIKey struct {
 	ID                uint64     `gorm:"primaryKey;autoIncrement" json:"id"`
 	UserID            uint64     `gorm:"index;not null" json:"user_id"`
@@ -72,38 +70,38 @@ type APIKey struct {
 	UpdatedAt         time.Time  `json:"updated_at"`
 }

-// Channel 上游渠道（PLANNING §5.3）
+// Channel 上游渠道（PLANNING §6.3）
 type Channel struct {
-	ID            uint64    `gorm:"primaryKey;autoIncrement" json:"id"`
-	Name          string    `gorm:"uniqueIndex;size:64;not null" json:"name"`
-	Provider      string    `gorm:"size:16;not null" json:"provider"` // openai|anthropic|compatible
-	BaseURL       string    `gorm:"size:255;not null" json:"base_url"`
-	APIKeyEnc     string    `gorm:"size:1024;not null" json:"-"` // AES-GCM 密文
-	Weight        int       `gorm:"not null;default:1" json:"weight"`
-	Priority      int       `gorm:"not null;default:0" json:"priority"` // 数值小优先
-	TimeoutMS     int       `gorm:"not null;default:120000" json:"timeout_ms"`
-	MaxConcurrency int     `gorm:"not null;default:16" json:"max_concurrency"`
-	HealthStatus  string    `gorm:"size:16;not null;default:healthy" json:"health_status"`
-	Enabled       bool      `gorm:"not null;default:true" json:"enabled"`
-	CreatedAt     time.Time `json:"created_at"`
-	UpdatedAt     time.Time `json:"updated_at"`
+	ID             uint64    `gorm:"primaryKey;autoIncrement" json:"id"`
+	Name           string    `gorm:"uniqueIndex;size:64;not null" json:"name"`
+	Provider       string    `gorm:"size:16;not null" json:"provider"` // openai|anthropic|compatible
+	BaseURL        string    `gorm:"size:255;not null" json:"base_url"`
+	APIKeyEnc      string    `gorm:"size:1024;not null" json:"-"` // AES-GCM 密文
+	Weight         int       `gorm:"not null;default:1" json:"weight"`
+	Priority       int       `gorm:"not null;default:0" json:"priority"` // 数值小优先
+	TimeoutMS      int       `gorm:"not null;default:120000" json:"timeout_ms"`
+	MaxConcurrency int       `gorm:"not null;default:16" json:"max_concurrency"`
+	HealthStatus   string    `gorm:"size:16;not null;default:healthy" json:"health_status"`
+	Enabled        bool      `gorm:"not null;default:true" json:"enabled"`
+	CreatedAt      time.Time `json:"created_at"`
+	UpdatedAt      time.Time `json:"updated_at"`
 }

-// Model 全局模型 + 定价（PLANNING §5.4，价格按每百万 token，USD）
+// Model 全局模型 + 定价（PLANNING §6.4，价格按每百万 token，USD）
 type Model struct {
-	ID              uint64    `gorm:"primaryKey;autoIncrement" json:"id"`
-	Name            string    `gorm:"uniqueIndex;size:128;not null" json:"name"`
-	DisplayName     string    `gorm:"size:128" json:"display_name"`
-	InputPrice      float64   `gorm:"type:numeric(20,8);not null;default:0" json:"input_price"`
-	OutputPrice     float64   `gorm:"type:numeric(20,8);not null;default:0" json:"output_price"`
-	CacheReadPrice  float64   `gorm:"type:numeric(20,8);not null;default:0" json:"cache_read_price"`
-	Enabled         bool      `gorm:"not null;default:true" json:"enabled"`
-	Sort            int       `gorm:"not null;default:0" json:"sort"`
-	CreatedAt       time.Time `json:"created_at"`
-	UpdatedAt       time.Time `json:"updated_at"`
+	ID             uint64    `gorm:"primaryKey;autoIncrement" json:"id"`
+	Name           string    `gorm:"uniqueIndex;size:128;not null" json:"name"`
+	DisplayName    string    `gorm:"size:128" json:"display_name"`
+	InputPrice     float64   `gorm:"type:numeric(20,8);not null;default:0" json:"input_price"`
+	OutputPrice    float64   `gorm:"type:numeric(20,8);not null;default:0" json:"output_price"`
+	CacheReadPrice float64   `gorm:"type:numeric(20,8);not null;default:0" json:"cache_read_price"`
+	Enabled        bool      `gorm:"not null;default:true" json:"enabled"`
+	Sort           int       `gorm:"not null;default:0" json:"sort"`
+	CreatedAt      time.Time `json:"created_at"`
+	UpdatedAt      time.Time `json:"updated_at"`
 }

-// ChannelModelBinding 渠道↔模型绑定（多对多，PLANNING §5.4）
+// ChannelModelBinding 渠道↔模型绑定（多对多，PLANNING §6.4）
 type ChannelModelBinding struct {
 	ID            uint64 `gorm:"primaryKey;autoIncrement" json:"id"`
 	ChannelID     uint64 `gorm:"index:idx_ch_model,unique;not null" json:"channel_id"`
@@ -114,60 +112,60 @@ type ChannelModelBinding struct {
 	Model         Model   `gorm:"foreignKey:ModelID" json:"-"`
 }

-// UsageLog 请求级用量明细（PLANNING §5.5）
+// UsageLog 请求级用量明细（PLANNING §6.5）
 type UsageLog struct {
-	ID               uint64     `gorm:"primaryKey;autoIncrement" json:"id"`
-	RequestID        string     `gorm:"size:128" json:"request_id"` // 上游 request id
-	TraceID          string     `gorm:"size:64;index" json:"trace_id"`
-	UserID           uint64     `gorm:"index:idx_user_created;not null" json:"user_id"`
-	KeyID            uint64     `json:"key_id"`
-	ChannelID        uint64     `json:"channel_id"`
-	ModelID          uint64     `json:"model_id"`
-	ModelName        string     `gorm:"size:128" json:"model_name"`
-	Protocol         string     `gorm:"size:32" json:"protocol"` // responses|chat|messages
-	InputTokens      int64      `json:"input_tokens"`
-	OutputTokens     int64      `json:"output_tokens"`
-	CacheReadTokens  int64      `json:"cache_read_tokens"`
-	CacheCreationTokens int64   `json:"cache_creation_tokens"`
-	InputPrice       float64    `gorm:"type:numeric(20,8)" json:"input_price"`   // 快照
-	OutputPrice      float64    `gorm:"type:numeric(20,8)" json:"output_price"`  // 快照
-	CacheReadPrice   float64    `gorm:"type:numeric(20,8)" json:"cache_read_price"` // 快照
-	Cost             float64    `gorm:"type:numeric(20,8)" json:"cost"`
-	LatencyMS        int        `json:"latency_ms"`
-	Status           string     `gorm:"size:16;not null" json:"status"`
-	ErrorCode        *string    `json:"error_code,omitempty"`
-	CreatedAt        time.Time  `gorm:"index" json:"created_at"`
+	ID                  uint64    `gorm:"primaryKey;autoIncrement" json:"id"`
+	RequestID           string    `gorm:"size:128" json:"request_id"` // 上游 request id
+	TraceID             string    `gorm:"size:64;index" json:"trace_id"`
+	UserID              uint64    `gorm:"index:idx_user_created;not null" json:"user_id"`
+	KeyID               uint64    `json:"key_id"`
+	ChannelID           uint64    `json:"channel_id"`
+	ModelID             uint64    `json:"model_id"`
+	ModelName           string    `gorm:"size:128" json:"model_name"`
+	Protocol            string    `gorm:"size:32" json:"protocol"` // responses|chat|messages
+	InputTokens         int64     `json:"input_tokens"`
+	OutputTokens        int64     `json:"output_tokens"`
+	CacheReadTokens     int64     `json:"cache_read_tokens"`
+	CacheCreationTokens int64     `json:"cache_creation_tokens"`
+	InputPrice          float64   `gorm:"type:numeric(20,8)" json:"input_price"`      // 快照
+	OutputPrice         float64   `gorm:"type:numeric(20,8)" json:"output_price"`     // 快照
+	CacheReadPrice      float64   `gorm:"type:numeric(20,8)" json:"cache_read_price"` // 快照
+	Cost                float64   `gorm:"type:numeric(20,8)" json:"cost"`
+	LatencyMS           int       `json:"latency_ms"`
+	Status              string    `gorm:"size:16;not null" json:"status"`
+	ErrorCode           *string   `json:"error_code,omitempty"`
+	CreatedAt           time.Time `gorm:"index" json:"created_at"`
 }

-// UsageDaily 日粒度预聚合（PLANNING §5.6）
+// UsageDaily 日粒度预聚合（PLANNING §6.6）
 type UsageDaily struct {
-	ID            uint64    `gorm:"primaryKey;autoIncrement" json:"id"`
-	UserID        uint64    `gorm:"index:idx_daily_user_model,unique" json:"user_id"`
-	ModelID       uint64    `gorm:"index:idx_daily_user_model,unique" json:"model_id"`
-	Date          string    `gorm:"size:10;index:idx_daily_user_model,unique" json:"date"` // YYYY-MM-DD (UTC)
-	Requests      int64     `json:"requests"`
-	InputTokens   int64     `json:"input_tokens"`
-	OutputTokens  int64     `json:"output_tokens"`
+	ID              uint64  `gorm:"primaryKey;autoIncrement" json:"id"`
+	UserID          uint64  `gorm:"index:idx_daily_user_model,unique" json:"user_id"`
+	ModelID         uint64  `gorm:"index:idx_daily_user_model,unique" json:"model_id"`
+	Date            string  `gorm:"size:10;index:idx_daily_user_model,unique" json:"date"` // YYYY-MM-DD (UTC)
+	Requests        int64   `json:"requests"`
+	InputTokens     int64   `json:"input_tokens"`
+	OutputTokens    int64   `json:"output_tokens"`
 	CacheReadTokens int64   `json:"cache_read_tokens"`
-	Cost          float64   `gorm:"type:numeric(20,8)" json:"cost"`
+	Cost            float64 `gorm:"type:numeric(20,8)" json:"cost"`
 }

-// RechargeOrder 充值订单（PLANNING §5.7，预留：首版不做充值）
+// RechargeOrder 充值订单（PLANNING §6.7，预留：首版不做充值）
 type RechargeOrder struct {
-	ID           uint64     `gorm:"primaryKey;autoIncrement" json:"id"`
-	UserID       uint64     `gorm:"index;not null" json:"user_id"`
-	Amount       float64    `gorm:"type:numeric(20,8);not null" json:"amount"`
-	Status       string     `gorm:"size:16;not null;default:pending" json:"status"`
-	Method       string     `gorm:"size:16;not null;default:manual" json:"method"`
-	TransactionID string    `gorm:"size:128" json:"transaction_id,omitempty"`
-	ReviewedBy   *uint64    `json:"reviewed_by,omitempty"`
-	ReviewedAt   *time.Time `json:"reviewed_at,omitempty"`
-	Remark       string     `gorm:"size:512" json:"remark,omitempty"`
-	CreatedAt    time.Time  `json:"created_at"`
-	UpdatedAt    time.Time  `json:"updated_at"`
+	ID            uint64     `gorm:"primaryKey;autoIncrement" json:"id"`
+	UserID        uint64     `gorm:"index;not null" json:"user_id"`
+	Amount        float64    `gorm:"type:numeric(20,8);not null" json:"amount"`
+	Status        string     `gorm:"size:16;not null;default:pending" json:"status"`
+	Method        string     `gorm:"size:16;not null;default:manual" json:"method"`
+	TransactionID string     `gorm:"size:128" json:"transaction_id,omitempty"`
+	ReviewedBy    *uint64    `json:"reviewed_by,omitempty"`
+	ReviewedAt    *time.Time `json:"reviewed_at,omitempty"`
+	Remark        string     `gorm:"size:512" json:"remark,omitempty"`
+	CreatedAt     time.Time  `json:"created_at"`
+	UpdatedAt     time.Time  `json:"updated_at"`
 }

-// BalanceLog 余额流水（PLANNING §5.8，幂等：ref_id + type 唯一）
+// BalanceLog 余额流水（PLANNING §6.8，幂等：ref_id + type 唯一）
 type BalanceLog struct {
 	ID           uint64    `gorm:"primaryKey;autoIncrement" json:"id"`
 	UserID       uint64    `gorm:"index:idx_balance_user;not null" json:"user_id"`
@@ -179,7 +177,7 @@ type BalanceLog struct {
 	CreatedAt    time.Time `json:"created_at"`
 }

-// SystemConfig 系统配置（PLANNING §5.9）
+// SystemConfig 系统配置（PLANNING §6.9）
 type SystemConfig struct {
 	Key   string `gorm:"primaryKey;size:64" json:"key"`
 	Value string `gorm:"type:jsonb;not null" json:"value"`
@@ -1,4 +1,5 @@
 // Package usage 异步记账：请求完成后写入 usage_logs，批量落库（PLANNING §3.2）。
+// 每个请求在 flush 时同步完成：写明细 + 扣余额 + 写流水 + 日聚合。
 package usage

 import (
@@ -11,6 +12,7 @@ import (
 	"gorm.io/gorm/clause"
 )

+// Recorder 异步记账器：缓冲队列 + 批量事务落库。
 type Recorder struct {
 	db     *gorm.DB
 	ch     chan *store.UsageLog
@@ -36,7 +38,6 @@ func (r *Recorder) Record(l *store.UsageLog) {
 	select {
 	case r.ch <- l:
 	default:
-		// 队列积压：直接同步写，避免丢账
 		if err := r.flush([]*store.UsageLog{l}); err != nil {
 			log.Printf("usage: sync write failed: %v", err)
 		}
@@ -99,13 +100,15 @@ func (r *Recorder) flush(logs []*store.UsageLog) error {
 			if l.Status != store.UsageStatusSuccess || l.Cost <= 0 {
 				continue
 			}
-			// 扣余额（余额可为负，流式请求不中断；后续请求被拒）
+			// 扣余额（余额可为负：流式请求不中断；后续请求被拒）
 			var user store.User
 			if err := tx.Clauses(clause.Locking{Strength: "UPDATE"}).First(&user, l.UserID).Error; err != nil {
 				continue
 			}
 			newBalance := user.Balance - l.Cost
-			tx.Model(&store.User{}).Where("id = ?", l.UserID).Update("balance", newBalance)
+			if err := tx.Model(&store.User{}).Where("id = ?", l.UserID).Update("balance", newBalance).Error; err != nil {
+				continue
+			}
 			tx.Create(&store.BalanceLog{
 				UserID:       l.UserID,
 				Change:       -l.Cost,
@@ -118,18 +121,23 @@ func (r *Recorder) flush(logs []*store.UsageLog) error {
 			// 日聚合 upsert
 			date := l.CreatedAt.UTC().Format("2006-01-02")
 			tx.Clauses(clause.OnConflict{
-				Columns:   []clause.Column{{Name: "user_id"}, {Name: "model_id"}, {Name: "date"}},
+				Columns: []clause.Column{{Name: "user_id"}, {Name: "model_id"}, {Name: "date"}},
 				DoUpdates: clause.Assignments(map[string]any{
-					"requests":         gorm.Expr("requests + 1"),
-					"input_tokens":     gorm.Expr("input_tokens + ?", l.InputTokens),
-					"output_tokens":    gorm.Expr("output_tokens + ?", l.OutputTokens),
+					"requests":          gorm.Expr("requests + 1"),
+					"input_tokens":      gorm.Expr("input_tokens + ?", l.InputTokens),
+					"output_tokens":     gorm.Expr("output_tokens + ?", l.OutputTokens),
 					"cache_read_tokens": gorm.Expr("cache_read_tokens + ?", l.CacheReadTokens),
-					"cost":             gorm.Expr("cost + ?", l.Cost),
+					"cost":              gorm.Expr("cost + ?", l.Cost),
 				}),
 			}).Create(&store.UsageDaily{
-				UserID: l.UserID, ModelID: l.ModelID, Date: date,
-				Requests: 1, InputTokens: l.InputTokens, OutputTokens: l.OutputTokens,
-				CacheReadTokens: l.CacheReadTokens, Cost: l.Cost,
+				UserID:          l.UserID,
+				ModelID:         l.ModelID,
+				Date:            date,
+				Requests:        1,
+				InputTokens:     l.InputTokens,
+				OutputTokens:    l.OutputTokens,
+				CacheReadTokens: l.CacheReadTokens,
+				Cost:            l.Cost,
 			})
 		}
 		return nil