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 的目录收口口径
2026-05-05 19:31:39 +08:00
parent d7184b776b
commit 2a96f4c6f9
72 changed files with 2775 additions and 291 deletions
--- a/backend/services/memory/observe/log_fields.go
+++ b/backend/services/memory/observe/log_fields.go
@@ -0,0 +1,119 @@
+package observe
+
+import (
+	"context"
+	"errors"
+	"strings"
+)
+
+const (
+	ComponentRead    = "read"
+	ComponentWrite   = "write"
+	ComponentInject  = "inject"
+	ComponentManage  = "manage"
+	ComponentCleanup = "cleanup"
+
+	OperationRetrieve = "retrieve"
+	OperationDecision = "decision"
+	OperationInject   = "inject"
+	OperationManage   = "manage"
+	OperationDedup    = "dedup"
+
+	MetricJobTotal               = "memory_job_total"
+	MetricJobRetryTotal          = "memory_job_retry_total"
+	MetricDecisionTotal          = "memory_decision_total"
+	MetricDecisionFallbackTotal  = "memory_decision_fallback_total"
+	MetricRetrieveHitTotal       = "memory_retrieve_hit_total"
+	MetricRetrieveDedupDropTotal = "memory_retrieve_dedup_drop_total"
+	MetricInjectItemTotal        = "memory_inject_item_total"
+	MetricRAGFallbackTotal       = "memory_rag_fallback_total"
+	MetricManageTotal            = "memory_manage_total"
+	MetricCleanupRunTotal        = "memory_cleanup_run_total"
+	MetricCleanupArchivedTotal   = "memory_cleanup_archived_total"
+)
+
+type fieldsContextKey struct{}
+
+// WithFields 把 memory 链路公共字段挂进上下文，供下游日志复用。
+//
+// 职责边界：
+// 1. 只负责字段透传与覆盖，不负责真正打印日志；
+// 2. 只保留有意义的字段，避免结构化日志长期堆积空值；
+// 3. 若上游已写入同名字段，则以后写值为准，方便链路逐层补齐上下文。
+func WithFields(ctx context.Context, fields map[string]any) context.Context {
+	if len(fields) == 0 {
+		return ctx
+	}
+	if ctx == nil {
+		ctx = context.Background()
+	}
+
+	merged := FieldsFromContext(ctx)
+	for key, value := range fields {
+		key = strings.TrimSpace(key)
+		if key == "" || !shouldKeepField(value) {
+			continue
+		}
+		merged[key] = value
+	}
+	if len(merged) == 0 {
+		return ctx
+	}
+	return context.WithValue(ctx, fieldsContextKey{}, merged)
+}
+
+// FieldsFromContext 读取当前上下文中已经累积的观测字段。
+func FieldsFromContext(ctx context.Context) map[string]any {
+	if ctx == nil {
+		return map[string]any{}
+	}
+	raw, ok := ctx.Value(fieldsContextKey{}).(map[string]any)
+	if !ok || len(raw) == 0 {
+		return map[string]any{}
+	}
+
+	result := make(map[string]any, len(raw))
+	for key, value := range raw {
+		result[key] = value
+	}
+	return result
+}
+
+// MergeFields 合并多份结构化字段，后写同名字段覆盖先写字段。
+func MergeFields(parts ...map[string]any) map[string]any {
+	result := make(map[string]any)
+	for _, part := range parts {
+		for key, value := range part {
+			key = strings.TrimSpace(key)
+			if key == "" || !shouldKeepField(value) {
+				continue
+			}
+			result[key] = value
+		}
+	}
+	return result
+}
+
+// ClassifyError 把常见错误压成稳定错误码，便于日志与指标统一聚合。
+func ClassifyError(err error) string {
+	switch {
+	case err == nil:
+		return ""
+	case errors.Is(err, context.DeadlineExceeded):
+		return "deadline_exceeded"
+	case errors.Is(err, context.Canceled):
+		return "canceled"
+	default:
+		return "memory_error"
+	}
+}
+
+func shouldKeepField(value any) bool {
+	if value == nil {
+		return false
+	}
+	if text, ok := value.(string); ok {
+		return strings.TrimSpace(text) != ""
+	}
+	return true
+}
--- a/backend/services/memory/observe/metrics.go
+++ b/backend/services/memory/observe/metrics.go
@@ -0,0 +1,158 @@
+package observe
+
+import (
+	"sort"
+	"strings"
+	"sync"
+)
+
+// CounterSnapshot 是轻量计数器的快照视图，供后续排障或接平台时读取。
+type CounterSnapshot struct {
+	Name   string
+	Labels map[string]string
+	Value  int64
+}
+
+// MetricsRecorder 描述 memory 模块对计数器的最小依赖。
+type MetricsRecorder interface {
+	AddCounter(name string, delta int64, labels map[string]string)
+	Snapshot() []CounterSnapshot
+}
+
+// NewNopMetrics 返回空实现，保证无观测平台时仍可安全运行。
+func NewNopMetrics() MetricsRecorder {
+	return nopMetrics{}
+}
+
+type nopMetrics struct{}
+
+func (nopMetrics) AddCounter(string, int64, map[string]string) {}
+
+func (nopMetrics) Snapshot() []CounterSnapshot {
+	return nil
+}
+
+// MetricsRegistry 是 memory 模块当前阶段的轻量内存计数器实现。
+//
+// 职责边界：
+// 1. 只做线程安全计数，不负责导出协议；
+// 2. 标签做低基数归一化，避免治理期临时字段把指标打爆；
+// 3. 后续若项目统一接 Prometheus，可直接保留调用口径并替换实现。
+type MetricsRegistry struct {
+	mu       sync.RWMutex
+	counters map[string]*counterRecord
+}
+
+type counterRecord struct {
+	name   string
+	labels map[string]string
+	value  int64
+}
+
+func NewMetricsRegistry() *MetricsRegistry {
+	return &MetricsRegistry{
+		counters: make(map[string]*counterRecord),
+	}
+}
+
+// AddCounter 追加计数值；delta<=0 时直接忽略，避免脏数据污染快照。
+func (r *MetricsRegistry) AddCounter(name string, delta int64, labels map[string]string) {
+	if r == nil || delta <= 0 {
+		return
+	}
+
+	name = strings.TrimSpace(name)
+	if name == "" {
+		return
+	}
+	normalizedLabels := normalizeLabels(labels)
+	key := buildCounterKey(name, normalizedLabels)
+
+	r.mu.Lock()
+	defer r.mu.Unlock()
+	if existing, ok := r.counters[key]; ok {
+		existing.value += delta
+		return
+	}
+	r.counters[key] = &counterRecord{
+		name:   name,
+		labels: normalizedLabels,
+		value:  delta,
+	}
+}
+
+// Snapshot 返回当前全部计数器快照，便于后续排障或测试读取。
+func (r *MetricsRegistry) Snapshot() []CounterSnapshot {
+	if r == nil {
+		return nil
+	}
+
+	r.mu.RLock()
+	defer r.mu.RUnlock()
+	if len(r.counters) == 0 {
+		return nil
+	}
+
+	keys := make([]string, 0, len(r.counters))
+	for key := range r.counters {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+
+	result := make([]CounterSnapshot, 0, len(keys))
+	for _, key := range keys {
+		record := r.counters[key]
+		labels := make(map[string]string, len(record.labels))
+		for labelKey, labelValue := range record.labels {
+			labels[labelKey] = labelValue
+		}
+		result = append(result, CounterSnapshot{
+			Name:   record.name,
+			Labels: labels,
+			Value:  record.value,
+		})
+	}
+	return result
+}
+
+func normalizeLabels(labels map[string]string) map[string]string {
+	if len(labels) == 0 {
+		return nil
+	}
+
+	result := make(map[string]string, len(labels))
+	for key, value := range labels {
+		key = strings.TrimSpace(key)
+		value = strings.TrimSpace(value)
+		if key == "" || value == "" {
+			continue
+		}
+		result[key] = value
+	}
+	if len(result) == 0 {
+		return nil
+	}
+	return result
+}
+
+func buildCounterKey(name string, labels map[string]string) string {
+	if len(labels) == 0 {
+		return name
+	}
+
+	keys := make([]string, 0, len(labels))
+	for key := range labels {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+
+	var sb strings.Builder
+	sb.WriteString(name)
+	for _, key := range keys {
+		sb.WriteString("|")
+		sb.WriteString(key)
+		sb.WriteString("=")
+		sb.WriteString(labels[key])
+	}
+	return sb.String()
+}
--- a/backend/services/memory/observe/observer.go
+++ b/backend/services/memory/observe/observer.go
@@ -0,0 +1,109 @@
+package observe
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"sort"
+	"strings"
+)
+
+// Level 表示 memory 结构化观测事件等级。
+type Level string
+
+const (
+	LevelInfo  Level = "info"
+	LevelWarn  Level = "warn"
+	LevelError Level = "error"
+)
+
+// Event 描述一次 memory 模块内部结构化观测事件。
+//
+// 职责边界：
+// 1. 只承载稳定字段，不绑定具体日志平台；
+// 2. 组件与操作名尽量保持低基数，避免后续指标聚合失控；
+// 3. 字段内容应偏“排障与治理”，不承载大段原始文本。
+type Event struct {
+	Level     Level
+	Component string
+	Operation string
+	Fields    map[string]any
+}
+
+// Observer 是 memory 模块的最小观测接口。
+type Observer interface {
+	Observe(ctx context.Context, event Event)
+}
+
+// ObserverFunc 允许用函数快速适配 Observer。
+type ObserverFunc func(ctx context.Context, event Event)
+
+func (f ObserverFunc) Observe(ctx context.Context, event Event) {
+	if f == nil {
+		return
+	}
+	f(ctx, event)
+}
+
+// NewNopObserver 返回空实现，保证观测能力不会反向阻塞主链路。
+func NewNopObserver() Observer {
+	return ObserverFunc(func(context.Context, Event) {})
+}
+
+// NewLoggerObserver 返回标准日志实现，当前阶段默认打到后端进程日志。
+func NewLoggerObserver(logger *log.Logger) Observer {
+	if logger == nil {
+		logger = log.Default()
+	}
+	return &loggerObserver{logger: logger}
+}
+
+type loggerObserver struct {
+	logger *log.Logger
+}
+
+func (o *loggerObserver) Observe(ctx context.Context, event Event) {
+	if o == nil || o.logger == nil {
+		return
+	}
+
+	level := strings.TrimSpace(string(event.Level))
+	if level == "" {
+		level = string(LevelInfo)
+	}
+	component := strings.TrimSpace(event.Component)
+	if component == "" {
+		component = "unknown"
+	}
+	operation := strings.TrimSpace(event.Operation)
+	if operation == "" {
+		operation = "unknown"
+	}
+
+	fields := FieldsFromContext(ctx)
+	for key, value := range event.Fields {
+		key = strings.TrimSpace(key)
+		if key == "" || !shouldKeepField(value) {
+			continue
+		}
+		fields[key] = value
+	}
+
+	parts := []string{
+		"memory",
+		fmt.Sprintf("level=%s", level),
+		fmt.Sprintf("component=%s", component),
+		fmt.Sprintf("operation=%s", operation),
+	}
+
+	keys := make([]string, 0, len(fields))
+	for key := range fields {
+		keys = append(keys, key)
+	}
+	sort.Strings(keys)
+	for _, key := range keys {
+		parts = append(parts, fmt.Sprintf("%s=%v", key, fields[key]))
+	}
+
+	o.logger.Print(strings.Join(parts, " "))
+}