Version: 0.9.76.dev.260505

后端：
1.阶段 6 agent / memory 服务化收口
- 新增 cmd/agent 独立进程入口，承载 agent zrpc server、agent outbox relay / consumer 和运行时依赖初始化
- 补齐 services/agent/rpc 的 Chat stream 与 conversation meta/list/timeline、schedule-preview、context-stats、schedule-state unary RPC
- 新增 gateway/client/agent 与 shared/contracts/agent，将 /api/v1/agent chat 和非 chat 门面切到 agent zrpc
- 收缩 gateway 本地 AgentService 装配，双 RPC 开关开启时不再初始化本地 agent 编排、LLM、RAG 和 memory reader fallback
- 将 backend/memory 物理迁入 services/memory，私有实现收入 internal，保留 module/model/observe 作为 memory 服务门面
- 调整 memory outbox、memory reader 和 agent 记忆渲染链路的 import 与服务边界，cmd/memory 独占 memory worker / consumer
- 关闭 gateway 侧 agent outbox worker 所有权，agent relay / consumer 由 cmd/agent 独占，gateway 仅保留 HTTP/SSE 门面与迁移期开关回退
- 更新阶段 6 文档，记录 agent / memory 当前切流点、smoke 结果，以及 backend/client 与 gateway/shared 的目录收口口径

backend/services/agent/rpc/agent.proto

@@ -0,0 +1,42 @@
+syntax = "proto3";
+
+package smartflow.agent;
+
+option go_package = "github.com/LoveLosita/smartflow/backend/services/agent/rpc/pb";
+
+service Agent {
+  rpc Ping(StatusResponse) returns (StatusResponse);
+  rpc Chat(ChatRequest) returns (stream ChatChunk);
+  rpc GetConversationMeta(JSONRequest) returns (JSONResponse);
+  rpc GetConversationList(JSONRequest) returns (JSONResponse);
+  rpc GetConversationTimeline(JSONRequest) returns (JSONResponse);
+  rpc GetSchedulePlanPreview(JSONRequest) returns (JSONResponse);
+  rpc GetContextStats(JSONRequest) returns (JSONResponse);
+  rpc SaveScheduleState(JSONRequest) returns (JSONResponse);
+}
+
+message ChatRequest {
+  string message = 1;
+  string thinking = 2;
+  string model = 3;
+  int32 user_id = 4;
+  string conversation_id = 5;
+  bytes extra_json = 6;
+}
+
+message ChatChunk {
+  string payload = 1;
+  bool done = 2;
+  bytes error_json = 3;
+}
+
+message StatusResponse {
+}
+
+message JSONRequest {
+  bytes payload_json = 1;
+}
+
+message JSONResponse {
+  bytes data_json = 1;
+}

backend/services/agent/rpc/errors.go

@@ -0,0 +1,76 @@
+package rpc
+
+import (
+	"errors"
+	"log"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/respond"
+	"google.golang.org/genproto/googleapis/rpc/errdetails"
+	"google.golang.org/grpc/codes"
+	"google.golang.org/grpc/status"
+	"gorm.io/gorm"
+)
+
+var errAgentServiceNotReady = errors.New("agent service dependency not initialized")
+
+const agentErrorDomain = "smartflow.agent"
+
+// grpcErrorFromServiceError 负责把 agent 内部错误转换为 gRPC status。
+//
+// 职责边界：
+// 1. respond.Response 保留项目内部 status/info，供 gateway 反解；
+// 2. 未分类错误只暴露通用内部错误，详细信息留在服务日志；
+// 3. 不在 RPC 层重判业务规则，业务语义仍由 agent/sv 决定。
+func grpcErrorFromServiceError(err error) error {
+	if err == nil {
+		return nil
+	}
+	if errors.Is(err, gorm.ErrRecordNotFound) {
+		return grpcErrorFromResponse(respond.ConversationNotFound)
+	}
+	var resp respond.Response
+	if errors.As(err, &resp) {
+		return grpcErrorFromResponse(resp)
+	}
+	log.Printf("agent rpc internal error: %v", err)
+	return status.Error(codes.Internal, "agent service internal error")
+}
+
+func grpcErrorFromResponse(resp respond.Response) error {
+	code := grpcCodeFromRespondStatus(resp.Status)
+	message := strings.TrimSpace(resp.Info)
+	if message == "" {
+		message = strings.TrimSpace(resp.Status)
+	}
+	st := status.New(code, message)
+	detail := &errdetails.ErrorInfo{
+		Domain: agentErrorDomain,
+		Reason: resp.Status,
+		Metadata: map[string]string{
+			"info": resp.Info,
+		},
+	}
+	withDetails, err := st.WithDetails(detail)
+	if err != nil {
+		return st.Err()
+	}
+	return withDetails.Err()
+}
+
+func grpcCodeFromRespondStatus(statusValue string) codes.Code {
+	switch strings.TrimSpace(statusValue) {
+	case respond.MissingToken.Status, respond.InvalidToken.Status, respond.InvalidClaims.Status,
+		respond.ErrUnauthorized.Status, respond.WrongTokenType.Status, respond.UserLoggedOut.Status:
+		return codes.Unauthenticated
+	case respond.ConversationNotFound.Status:
+		return codes.NotFound
+	case respond.MissingParam.Status, respond.WrongParamType.Status, respond.ParamTooLong.Status,
+		respond.WrongUserID.Status, respond.MissingConversationID.Status:
+		return codes.InvalidArgument
+	}
+	if strings.HasPrefix(strings.TrimSpace(statusValue), "5") {
+		return codes.Internal
+	}
+	return codes.InvalidArgument
+}

backend/services/agent/rpc/handler.go

@@ -0,0 +1,256 @@
+package rpc
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"strings"
+
+	"github.com/LoveLosita/smartflow/backend/model"
+	"github.com/LoveLosita/smartflow/backend/respond"
+	"github.com/LoveLosita/smartflow/backend/services/agent/rpc/pb"
+	agentsv "github.com/LoveLosita/smartflow/backend/services/agent/sv"
+	agentcontracts "github.com/LoveLosita/smartflow/backend/shared/contracts/agent"
+)
+
+type Handler struct {
+	pb.UnimplementedAgentServer
+	svc *agentsv.AgentService
+}
+
+func NewHandler(svc *agentsv.AgentService) *Handler {
+	return &Handler{svc: svc}
+}
+
+// Ping 供调用方在启动期确认 agent zrpc 已可用。
+func (h *Handler) Ping(ctx context.Context, req *pb.StatusResponse) (*pb.StatusResponse, error) {
+	if err := h.ensureReady(req); err != nil {
+		return nil, err
+	}
+	return &pb.StatusResponse{}, nil
+}
+
+// Chat 把 agent 内部 channel 输出适配为 gRPC server-stream。
+//
+// 职责边界：
+// 1. RPC 层只负责协议转换，不改写 agent/sv 的图编排、工具调用和持久化语义；
+// 2. AgentService 内部仍使用 channel 解耦节点输出，跨进程边界统一转换为 stream.Send；
+// 3. 业务错误通过 error_json chunk 传给 Gateway，由 Gateway 保持原 SSE 错误体输出。
+func (h *Handler) Chat(req *pb.ChatRequest, stream pb.Agent_ChatServer) error {
+	if err := h.ensureReady(req); err != nil {
+		return err
+	}
+	extra, err := decodeExtra(req.ExtraJson)
+	if err != nil {
+		return grpcErrorFromServiceError(respond.WrongParamType)
+	}
+
+	outChan, errChan := h.svc.AgentChat(
+		stream.Context(),
+		req.Message,
+		req.Thinking,
+		req.Model,
+		int(req.UserId),
+		req.ConversationId,
+		extra,
+	)
+
+	for outChan != nil || errChan != nil {
+		select {
+		case err, ok := <-errChan:
+			if !ok {
+				// 1. errChan 关闭表示当前没有更多异步错误；置 nil 后让 select 不再命中该分支。
+				// 2. 若继续读取已关闭 channel，会形成忙等并拖慢长连接 stream。
+				errChan = nil
+				continue
+			}
+			if err == nil {
+				continue
+			}
+			errorJSON := buildStreamErrorJSON(err)
+			return stream.Send(&pb.ChatChunk{Done: true, ErrorJson: errorJSON})
+		case payload, ok := <-outChan:
+			if !ok {
+				outChan = nil
+				return stream.Send(&pb.ChatChunk{Done: true})
+			}
+			if err := stream.Send(&pb.ChatChunk{Payload: payload}); err != nil {
+				return err
+			}
+			if strings.TrimSpace(payload) == "[DONE]" {
+				// 1. AgentService 旧链路已经把 OpenAI 兼容的 [DONE] 当作普通 payload 推给前端。
+				// 2. RPC 层只负责跨进程透传；这里直接结束 stream，避免 Gateway 再补一帧重复 [DONE]。
+				return nil
+			}
+		case <-stream.Context().Done():
+			return stream.Context().Err()
+		}
+	}
+	return stream.Send(&pb.ChatChunk{Done: true})
+}
+
+// GetConversationMeta 透传查询单个会话元信息。
+//
+// 职责边界：
+// 1. RPC 层只负责 JSON 契约反序列化和响应序列化；
+// 2. 会话归属、404 语义和 DTO 组装继续由 AgentService 决定；
+// 3. Gateway 仍负责 HTTP query 绑定和最终响应包装。
+func (h *Handler) GetConversationMeta(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	var payload agentcontracts.ConversationQueryRequest
+	if err := h.decodeJSONRequest(req, &payload); err != nil {
+		return nil, err
+	}
+	resp, err := h.svc.GetConversationMeta(ctx, payload.UserID, payload.ConversationID)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return jsonResponseFromPayload(resp)
+}
+
+// GetConversationList 透传查询当前用户会话列表。
+func (h *Handler) GetConversationList(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	var payload agentcontracts.ConversationListRequest
+	if err := h.decodeJSONRequest(req, &payload); err != nil {
+		return nil, err
+	}
+	resp, err := h.svc.GetConversationList(ctx, payload.UserID, payload.Page, payload.PageSize, payload.Status)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return jsonResponseFromPayload(resp)
+}
+
+// GetConversationTimeline 透传查询会话时间线。
+func (h *Handler) GetConversationTimeline(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	var payload agentcontracts.ConversationQueryRequest
+	if err := h.decodeJSONRequest(req, &payload); err != nil {
+		return nil, err
+	}
+	resp, err := h.svc.GetConversationTimeline(ctx, payload.UserID, payload.ConversationID)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return jsonResponseFromPayload(resp)
+}
+
+// GetSchedulePlanPreview 透传查询会话内排程预览。
+func (h *Handler) GetSchedulePlanPreview(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	var payload agentcontracts.ConversationQueryRequest
+	if err := h.decodeJSONRequest(req, &payload); err != nil {
+		return nil, err
+	}
+	resp, err := h.svc.GetSchedulePlanPreview(ctx, payload.UserID, payload.ConversationID)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return jsonResponseFromPayload(resp)
+}
+
+// GetContextStats 透传查询会话上下文 token 统计 JSON。
+func (h *Handler) GetContextStats(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	var payload agentcontracts.ConversationQueryRequest
+	if err := h.decodeJSONRequest(req, &payload); err != nil {
+		return nil, err
+	}
+	statsJSON, err := h.svc.GetContextStats(ctx, payload.UserID, payload.ConversationID)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.JSONResponse{DataJson: []byte(strings.TrimSpace(statsJSON))}, nil
+}
+
+// SaveScheduleState 透传保存会话内排程拖拽状态。
+//
+// 职责边界：
+// 1. RPC 层只把跨进程契约转换为 AgentService 既有模型；
+// 2. 快照读取、归属校验、坐标转换和 Redis 回写仍由 AgentService 完成；
+// 3. 成功时返回空 JSON 响应，Gateway 继续保持 data=null 的 HTTP 语义。
+func (h *Handler) SaveScheduleState(ctx context.Context, req *pb.JSONRequest) (*pb.JSONResponse, error) {
+	var payload agentcontracts.SaveScheduleStateRequest
+	if err := h.decodeJSONRequest(req, &payload); err != nil {
+		return nil, err
+	}
+	if err := h.svc.SaveScheduleState(ctx, payload.UserID, payload.ConversationID, toModelScheduleStateItems(payload.Items)); err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.JSONResponse{}, nil
+}
+
+func (h *Handler) ensureReady(req any) error {
+	if h == nil || h.svc == nil {
+		return grpcErrorFromServiceError(errAgentServiceNotReady)
+	}
+	if req == nil {
+		return grpcErrorFromServiceError(respond.MissingParam)
+	}
+	return nil
+}
+
+func (h *Handler) decodeJSONRequest(req *pb.JSONRequest, out any) error {
+	if err := h.ensureReady(req); err != nil {
+		return err
+	}
+	if len(req.PayloadJson) == 0 {
+		return grpcErrorFromServiceError(respond.MissingParam)
+	}
+	if err := json.Unmarshal(req.PayloadJson, out); err != nil {
+		return grpcErrorFromServiceError(respond.WrongParamType)
+	}
+	return nil
+}
+
+func jsonResponseFromPayload(payload any) (*pb.JSONResponse, error) {
+	raw, err := json.Marshal(payload)
+	if err != nil {
+		return nil, grpcErrorFromServiceError(err)
+	}
+	return &pb.JSONResponse{DataJson: raw}, nil
+}
+
+func toModelScheduleStateItems(items []agentcontracts.SaveScheduleStatePlacedItem) []model.SaveScheduleStatePlacedItem {
+	if len(items) == 0 {
+		return nil
+	}
+	result := make([]model.SaveScheduleStatePlacedItem, 0, len(items))
+	for _, item := range items {
+		result = append(result, model.SaveScheduleStatePlacedItem{
+			TaskItemID:         item.TaskItemID,
+			Week:               item.Week,
+			DayOfWeek:          item.DayOfWeek,
+			StartSection:       item.StartSection,
+			EndSection:         item.EndSection,
+			EmbedCourseEventID: item.EmbedCourseEventID,
+		})
+	}
+	return result
+}
+
+func decodeExtra(raw []byte) (map[string]any, error) {
+	if len(raw) == 0 || string(raw) == "null" {
+		return nil, nil
+	}
+	var extra map[string]any
+	if err := json.Unmarshal(raw, &extra); err != nil {
+		return nil, err
+	}
+	return extra, nil
+}
+
+func buildStreamErrorJSON(err error) []byte {
+	errorBody := map[string]any{
+		"message": err.Error(),
+		"type":    "server_error",
+	}
+	var respErr respond.Response
+	if errors.As(err, &respErr) {
+		errorBody["code"] = respErr.Status
+		if respErr.Info != "" {
+			errorBody["message"] = respErr.Info
+		}
+	}
+	raw, marshalErr := json.Marshal(map[string]any{"error": errorBody})
+	if marshalErr != nil {
+		return []byte(`{"error":{"message":"agent stream error","type":"server_error"}}`)
+	}
+	return raw
+}

backend/services/agent/rpc/pb/agent.pb.go

@@ -0,0 +1,68 @@
+package pb
+
+import proto "github.com/golang/protobuf/proto"
+
+var _ = proto.Marshal
+
+const _ = proto.ProtoPackageIsVersion3
+
+type ChatRequest struct {
+	Message              string   `protobuf:"bytes,1,opt,name=message,proto3" json:"message,omitempty"`
+	Thinking             string   `protobuf:"bytes,2,opt,name=thinking,proto3" json:"thinking,omitempty"`
+	Model                string   `protobuf:"bytes,3,opt,name=model,proto3" json:"model,omitempty"`
+	UserId               int32    `protobuf:"varint,4,opt,name=user_id,json=userId,proto3" json:"user_id,omitempty"`
+	ConversationId       string   `protobuf:"bytes,5,opt,name=conversation_id,json=conversationId,proto3" json:"conversation_id,omitempty"`
+	ExtraJson            []byte   `protobuf:"bytes,6,opt,name=extra_json,json=extraJson,proto3" json:"extra_json,omitempty"`
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *ChatRequest) Reset()         { *m = ChatRequest{} }
+func (m *ChatRequest) String() string { return proto.CompactTextString(m) }
+func (*ChatRequest) ProtoMessage()    {}
+
+type ChatChunk struct {
+	Payload              string   `protobuf:"bytes,1,opt,name=payload,proto3" json:"payload,omitempty"`
+	Done                 bool     `protobuf:"varint,2,opt,name=done,proto3" json:"done,omitempty"`
+	ErrorJson            []byte   `protobuf:"bytes,3,opt,name=error_json,json=errorJson,proto3" json:"error_json,omitempty"`
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *ChatChunk) Reset()         { *m = ChatChunk{} }
+func (m *ChatChunk) String() string { return proto.CompactTextString(m) }
+func (*ChatChunk) ProtoMessage()    {}
+
+type StatusResponse struct {
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *StatusResponse) Reset()         { *m = StatusResponse{} }
+func (m *StatusResponse) String() string { return proto.CompactTextString(m) }
+func (*StatusResponse) ProtoMessage()    {}
+
+type JSONRequest struct {
+	PayloadJson          []byte   `protobuf:"bytes,1,opt,name=payload_json,json=payloadJson,proto3" json:"payload_json,omitempty"`
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *JSONRequest) Reset()         { *m = JSONRequest{} }
+func (m *JSONRequest) String() string { return proto.CompactTextString(m) }
+func (*JSONRequest) ProtoMessage()    {}
+
+type JSONResponse struct {
+	DataJson             []byte   `protobuf:"bytes,1,opt,name=data_json,json=dataJson,proto3" json:"data_json,omitempty"`
+	XXX_NoUnkeyedLiteral struct{} `json:"-"`
+	XXX_unrecognized     []byte   `json:"-"`
+	XXX_sizecache        int32    `json:"-"`
+}
+
+func (m *JSONResponse) Reset()         { *m = JSONResponse{} }
+func (m *JSONResponse) String() string { return proto.CompactTextString(m) }
+func (*JSONResponse) ProtoMessage()    {}

backend/services/agent/rpc/pb/agent_grpc.pb.go

@@ -0,0 +1,313 @@
+package pb
+
+import (
+	context "context"
+	io "io"
+
+	grpc "google.golang.org/grpc"
+	codes "google.golang.org/grpc/codes"
+	status "google.golang.org/grpc/status"
+)
+
+const (
+	Agent_Ping_FullMethodName                    = "/smartflow.agent.Agent/Ping"
+	Agent_Chat_FullMethodName                    = "/smartflow.agent.Agent/Chat"
+	Agent_GetConversationMeta_FullMethodName     = "/smartflow.agent.Agent/GetConversationMeta"
+	Agent_GetConversationList_FullMethodName     = "/smartflow.agent.Agent/GetConversationList"
+	Agent_GetConversationTimeline_FullMethodName = "/smartflow.agent.Agent/GetConversationTimeline"
+	Agent_GetSchedulePlanPreview_FullMethodName  = "/smartflow.agent.Agent/GetSchedulePlanPreview"
+	Agent_GetContextStats_FullMethodName         = "/smartflow.agent.Agent/GetContextStats"
+	Agent_SaveScheduleState_FullMethodName       = "/smartflow.agent.Agent/SaveScheduleState"
+)
+
+type AgentClient interface {
+	Ping(ctx context.Context, in *StatusResponse, opts ...grpc.CallOption) (*StatusResponse, error)
+	Chat(ctx context.Context, in *ChatRequest, opts ...grpc.CallOption) (Agent_ChatClient, error)
+	GetConversationMeta(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	GetConversationList(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	GetConversationTimeline(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	GetSchedulePlanPreview(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	GetContextStats(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+	SaveScheduleState(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error)
+}
+
+type agentClient struct {
+	cc grpc.ClientConnInterface
+}
+
+func NewAgentClient(cc grpc.ClientConnInterface) AgentClient {
+	return &agentClient{cc}
+}
+
+func (c *agentClient) Ping(ctx context.Context, in *StatusResponse, opts ...grpc.CallOption) (*StatusResponse, error) {
+	out := new(StatusResponse)
+	err := c.cc.Invoke(ctx, Agent_Ping_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *agentClient) Chat(ctx context.Context, in *ChatRequest, opts ...grpc.CallOption) (Agent_ChatClient, error) {
+	stream, err := c.cc.NewStream(ctx, &Agent_ServiceDesc.Streams[0], Agent_Chat_FullMethodName, opts...)
+	if err != nil {
+		return nil, err
+	}
+	client := &agentChatClient{stream}
+	if err := client.ClientStream.SendMsg(in); err != nil {
+		return nil, err
+	}
+	if err := client.ClientStream.CloseSend(); err != nil {
+		return nil, err
+	}
+	return client, nil
+}
+
+func (c *agentClient) GetConversationMeta(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Agent_GetConversationMeta_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *agentClient) GetConversationList(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Agent_GetConversationList_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *agentClient) GetConversationTimeline(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Agent_GetConversationTimeline_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *agentClient) GetSchedulePlanPreview(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Agent_GetSchedulePlanPreview_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *agentClient) GetContextStats(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Agent_GetContextStats_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+func (c *agentClient) SaveScheduleState(ctx context.Context, in *JSONRequest, opts ...grpc.CallOption) (*JSONResponse, error) {
+	out := new(JSONResponse)
+	err := c.cc.Invoke(ctx, Agent_SaveScheduleState_FullMethodName, in, out, opts...)
+	return out, err
+}
+
+type Agent_ChatClient interface {
+	Recv() (*ChatChunk, error)
+	grpc.ClientStream
+}
+
+type agentChatClient struct {
+	grpc.ClientStream
+}
+
+func (x *agentChatClient) Recv() (*ChatChunk, error) {
+	m := new(ChatChunk)
+	if err := x.ClientStream.RecvMsg(m); err != nil {
+		if err == io.EOF {
+			return nil, err
+		}
+		return nil, err
+	}
+	return m, nil
+}
+
+type AgentServer interface {
+	Ping(context.Context, *StatusResponse) (*StatusResponse, error)
+	Chat(*ChatRequest, Agent_ChatServer) error
+	GetConversationMeta(context.Context, *JSONRequest) (*JSONResponse, error)
+	GetConversationList(context.Context, *JSONRequest) (*JSONResponse, error)
+	GetConversationTimeline(context.Context, *JSONRequest) (*JSONResponse, error)
+	GetSchedulePlanPreview(context.Context, *JSONRequest) (*JSONResponse, error)
+	GetContextStats(context.Context, *JSONRequest) (*JSONResponse, error)
+	SaveScheduleState(context.Context, *JSONRequest) (*JSONResponse, error)
+}
+
+type UnimplementedAgentServer struct{}
+
+func (UnimplementedAgentServer) Ping(context.Context, *StatusResponse) (*StatusResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method Ping not implemented")
+}
+
+func (UnimplementedAgentServer) Chat(*ChatRequest, Agent_ChatServer) error {
+	return status.Errorf(codes.Unimplemented, "method Chat not implemented")
+}
+
+func (UnimplementedAgentServer) GetConversationMeta(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method GetConversationMeta not implemented")
+}
+
+func (UnimplementedAgentServer) GetConversationList(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method GetConversationList not implemented")
+}
+
+func (UnimplementedAgentServer) GetConversationTimeline(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method GetConversationTimeline not implemented")
+}
+
+func (UnimplementedAgentServer) GetSchedulePlanPreview(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method GetSchedulePlanPreview not implemented")
+}
+
+func (UnimplementedAgentServer) GetContextStats(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method GetContextStats not implemented")
+}
+
+func (UnimplementedAgentServer) SaveScheduleState(context.Context, *JSONRequest) (*JSONResponse, error) {
+	return nil, status.Errorf(codes.Unimplemented, "method SaveScheduleState not implemented")
+}
+
+func RegisterAgentServer(s grpc.ServiceRegistrar, srv AgentServer) {
+	s.RegisterService(&Agent_ServiceDesc, srv)
+}
+
+type Agent_ChatServer interface {
+	Send(*ChatChunk) error
+	grpc.ServerStream
+}
+
+type agentChatServer struct {
+	grpc.ServerStream
+}
+
+func (x *agentChatServer) Send(m *ChatChunk) error {
+	return x.ServerStream.SendMsg(m)
+}
+
+func _Agent_Ping_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(StatusResponse)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AgentServer).Ping(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{
+		Server:     srv,
+		FullMethod: Agent_Ping_FullMethodName,
+	}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AgentServer).Ping(ctx, req.(*StatusResponse))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _Agent_GetConversationMeta_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(JSONRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AgentServer).GetConversationMeta(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{Server: srv, FullMethod: Agent_GetConversationMeta_FullMethodName}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AgentServer).GetConversationMeta(ctx, req.(*JSONRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _Agent_GetConversationList_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(JSONRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AgentServer).GetConversationList(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{Server: srv, FullMethod: Agent_GetConversationList_FullMethodName}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AgentServer).GetConversationList(ctx, req.(*JSONRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _Agent_GetConversationTimeline_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(JSONRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AgentServer).GetConversationTimeline(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{Server: srv, FullMethod: Agent_GetConversationTimeline_FullMethodName}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AgentServer).GetConversationTimeline(ctx, req.(*JSONRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _Agent_GetSchedulePlanPreview_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(JSONRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AgentServer).GetSchedulePlanPreview(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{Server: srv, FullMethod: Agent_GetSchedulePlanPreview_FullMethodName}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AgentServer).GetSchedulePlanPreview(ctx, req.(*JSONRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _Agent_GetContextStats_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(JSONRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AgentServer).GetContextStats(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{Server: srv, FullMethod: Agent_GetContextStats_FullMethodName}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AgentServer).GetContextStats(ctx, req.(*JSONRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _Agent_SaveScheduleState_Handler(srv interface{}, ctx context.Context, dec func(interface{}) error, interceptor grpc.UnaryServerInterceptor) (interface{}, error) {
+	in := new(JSONRequest)
+	if err := dec(in); err != nil {
+		return nil, err
+	}
+	if interceptor == nil {
+		return srv.(AgentServer).SaveScheduleState(ctx, in)
+	}
+	info := &grpc.UnaryServerInfo{Server: srv, FullMethod: Agent_SaveScheduleState_FullMethodName}
+	handler := func(ctx context.Context, req interface{}) (interface{}, error) {
+		return srv.(AgentServer).SaveScheduleState(ctx, req.(*JSONRequest))
+	}
+	return interceptor(ctx, in, info, handler)
+}
+
+func _Agent_Chat_Handler(srv interface{}, stream grpc.ServerStream) error {
+	m := new(ChatRequest)
+	if err := stream.RecvMsg(m); err != nil {
+		return err
+	}
+	return srv.(AgentServer).Chat(m, &agentChatServer{stream})
+}
+
+var Agent_ServiceDesc = grpc.ServiceDesc{
+	ServiceName: "smartflow.agent.Agent",
+	HandlerType: (*AgentServer)(nil),
+	Methods: []grpc.MethodDesc{
+		{MethodName: "Ping", Handler: _Agent_Ping_Handler},
+		{MethodName: "GetConversationMeta", Handler: _Agent_GetConversationMeta_Handler},
+		{MethodName: "GetConversationList", Handler: _Agent_GetConversationList_Handler},
+		{MethodName: "GetConversationTimeline", Handler: _Agent_GetConversationTimeline_Handler},
+		{MethodName: "GetSchedulePlanPreview", Handler: _Agent_GetSchedulePlanPreview_Handler},
+		{MethodName: "GetContextStats", Handler: _Agent_GetContextStats_Handler},
+		{MethodName: "SaveScheduleState", Handler: _Agent_SaveScheduleState_Handler},
+	},
+	Streams: []grpc.StreamDesc{
+		{StreamName: "Chat", Handler: _Agent_Chat_Handler, ServerStreams: true},
+	},
+	Metadata: "services/agent/rpc/agent.proto",
+}

backend/services/agent/rpc/server.go

@@ -0,0 +1,60 @@
+package rpc
+
+import (
+	"errors"
+	"strings"
+	"time"
+
+	"github.com/LoveLosita/smartflow/backend/services/agent/rpc/pb"
+	agentsv "github.com/LoveLosita/smartflow/backend/services/agent/sv"
+	"github.com/zeromicro/go-zero/core/service"
+	"github.com/zeromicro/go-zero/zrpc"
+	"google.golang.org/grpc"
+)
+
+const (
+	defaultListenOn = "0.0.0.0:9089"
+	defaultTimeout  = 0
+)
+
+type ServerOptions struct {
+	ListenOn string
+	Timeout  time.Duration
+	Service  *agentsv.AgentService
+}
+
+// NewServer 创建 agent zrpc 服务端。
+//
+// 职责边界：
+// 1. 只负责 zrpc server 配置与 gRPC handler 注册；
+// 2. 不创建数据库、Redis、LLM 或业务服务，它们由 cmd/agent 管理；
+// 3. Chat 是长连接 server-stream，默认不设置 RPC timeout，避免截断 SSE 转发。
+func NewServer(opts ServerOptions) (*zrpc.RpcServer, string, error) {
+	if opts.Service == nil {
+		return nil, "", errors.New("agent service dependency not initialized")
+	}
+
+	listenOn := strings.TrimSpace(opts.ListenOn)
+	if listenOn == "" {
+		listenOn = defaultListenOn
+	}
+	timeout := opts.Timeout
+	if timeout < 0 {
+		timeout = defaultTimeout
+	}
+
+	server, err := zrpc.NewServer(zrpc.RpcServerConf{
+		ServiceConf: service.ServiceConf{
+			Name: "agent.rpc",
+			Mode: service.DevMode,
+		},
+		ListenOn: listenOn,
+		Timeout:  int64(timeout / time.Millisecond),
+	}, func(grpcServer *grpc.Server) {
+		pb.RegisterAgentServer(grpcServer, NewHandler(opts.Service))
+	})
+	if err != nil {
+		return nil, "", err
+	}
+	return server, listenOn, nil
+}