feat(gateway): 消息mode落库(A3) — 持久化真实写入渲染模式

- POST /api/v1/chat 与 ws.chat 上行新增可选 mode（行为模式 design/01 §3/design/16 §5.1）
- Web路径经ctx透传本轮mode到编排器持久化(persistUserMessages/persistAssistantReply)，缺省回落chat
- pendingMsg记录mode，恢复/续接路径沿用发起轮次mode
- IM路径(persistToMain/persistIsolated)恒为chat
- 新增/扩充测试：REST/WS/orchestrator/channelbridge 覆盖mode写入
- Docs/api-client.md v0.20 同步mode字段

internal/services/gateway/session_persist.go

@@ -13,14 +13,47 @@ import (
 // turn settles. Both are silent no-ops when no history store is wired, so the
 // orchestrator runs unchanged without a store (tests / an unwired gateway).
 
+// modeChat is the behavior mode persisted when a turn carries none (design/01 §3,
+// design/16 §5.1). It is also the only mode the IM paths ever write, because IM
+// carries chat text alone.
+const modeChat = "chat"
+
+// modeOrDefault returns mode, or modeChat when the caller supplied none, so a
+// persisted message never carries an empty behavior mode (design/16 §5.1).
+func modeOrDefault(mode string) string {
+	if mode == "" {
+		return modeChat
+	}
+	return mode
+}
+
+// messageModeContextKey is the context key carrying a turn's behavior mode
+// (design/01 §3, design/16 §5.1) from the HTTP/WS boundary into the orchestrator's
+// persistence, so each persisted message is tagged with the mode it was sent in.
+type messageModeContextKey struct{}
+
+// withMode returns a context carrying mode so the orchestrator can tag the
+// persisted user message and assistant reply. An empty mode is a no-op (the
+// persistence layer falls back to modeChat).
+func withMode(ctx context.Context, mode string) context.Context {
+	return context.WithValue(ctx, messageModeContextKey{}, mode)
+}
+
+// modeFrom returns the behavior mode carried by ctx, or "" when none was set.
+func modeFrom(ctx context.Context) string {
+	v, _ := ctx.Value(messageModeContextKey{}).(string)
+	return v
+}
+
 // persistUserMessages writes each RoleUser message of a submitted turn to the
 // history store so the raw user stream is durable before the turn resolves, then
 // notifies the transport so every browser of the same account can append it
 // without a manual refresh (design/16 §3.3, §4.2). deviceID tags the message with
-// the sending client (design/16 §4.5). It is a no-op when no history store is
-// wired. Rejected turns (empty, pending-full) never reach it, so nothing vacuous
-// is persisted.
-func (o *Orchestrator) persistUserMessages(ctx context.Context, sessionID string, messages []model.Message, deviceID string) {
+// the sending client (design/16 §4.5) and mode is the behavior mode the turn was
+// sent in (design/16 §5.1), falling back to modeChat when empty. It is a no-op
+// when no history store is wired. Rejected turns (empty, pending-full) never
+// reach it, so nothing vacuous is persisted.
+func (o *Orchestrator) persistUserMessages(ctx context.Context, sessionID string, messages []model.Message, deviceID, mode string) {
 	if o.history == nil {
 		return
 	}
@@ -32,7 +65,7 @@ func (o *Orchestrator) persistUserMessages(ctx context.Context, sessionID string
 		if text == "" && image == "" {
 			continue
 		}
-		full, err := o.history.AppendFull(ctx, history.Message{SessionID: sessionID, Role: history.RoleUser, Content: text, Image: image, DeviceID: deviceID})
+		full, err := o.history.AppendFull(ctx, history.Message{SessionID: sessionID, Role: history.RoleUser, Content: text, Image: image, DeviceID: deviceID, Mode: modeOrDefault(mode)})
 		if err != nil {
 			o.log.Error("orchestrator persist user", "err", err, "session", sessionID, "device_id", deviceID)
 			continue
@@ -43,15 +76,16 @@ func (o *Orchestrator) persistUserMessages(ctx context.Context, sessionID string
 
 // persistAssistantReply writes the final assistant text of a settled turn to the
 // history store, then notifies the transport (design/16 §3.3, §4.2). deviceID tags
-// the reply with the client that sent the turn (design/16 §4.5). It is a no-op
-// when no history store is wired or the turn produced no text (interrupted/errored
-// turns leave res nil). The write runs under a fresh background context so a
-// canceled turn context never aborts it.
-func (o *Orchestrator) persistAssistantReply(sessionID string, res *loop.Result, deviceID string) {
+// the reply with the client that sent the turn (design/16 §4.5) and mode is the
+// behavior mode of that turn (design/16 §5.1), falling back to modeChat when
+// empty. It is a no-op when no history store is wired or the turn produced no text
+// (interrupted/errored turns leave res nil). The write runs under a fresh
+// background context so a canceled turn context never aborts it.
+func (o *Orchestrator) persistAssistantReply(sessionID string, res *loop.Result, deviceID, mode string) {
 	if o.history == nil || res == nil || res.Text == "" {
 		return
 	}
-	full, err := o.history.AppendFull(context.Background(), history.Message{SessionID: sessionID, Role: history.RoleAssistant, Content: res.Text, DeviceID: deviceID})
+	full, err := o.history.AppendFull(context.Background(), history.Message{SessionID: sessionID, Role: history.RoleAssistant, Content: res.Text, DeviceID: deviceID, Mode: modeOrDefault(mode)})
 	if err != nil {
 		o.log.Error("orchestrator persist assistant", "err", err, "session", sessionID, "device_id", deviceID)
 		return