Version: 0.9.23.dev.260416
后端： 1. Memory 管理面 API 落地（“我的记忆”增删改查 + 恢复） - 补齐 List/Get/Create/Update/Delete/Restore 的 handler、请求模型与返回视图 - 注册 `/api/v1/memory/items*` 路由并接入 MemoryHandler - 新增 memory item not found / invalid memory type / invalid memory content 三类管理面错误码 2. Memory Module / Service / Repo 扩展为“可管理 + 可治理”门面 - 新增 NewModuleWithObserve / ObserveDeps，导出 GetItem / CreateItem / UpdateItem / DeleteItem / RestoreItem / RunDedupCleanup / MemoryObserver / MemoryMetrics - 新增手动新增、修改、恢复能力；删除链路切到 SoftDeleteByID；所有管理动作统一事务内写 audit，并桥接向量同步与管理面观测 - 补齐 CreateItemFields / UpdateItemFields、单条 Create、管理侧字段更新、软删/恢复，以及 dedup 扫描/归档所需 repo 能力 - 审计操作补齐 archive / restore 3. Memory 读侧与注入侧观测补齐 - HybridRetrieve 返回 telemetry，统一记录 pinned hit / semantic hit / dedup drop / degraded / RAG fallback，并上报读取命中、去重丢弃、RAG 降级指标 - AgentService 持有 memory observer / metrics；injectMemoryContext 对读取失败、空注入、成功注入补齐结构化日志与注入计数 4. Worker / 决策 / 向量同步链路治理增强 - 召回结果显式携带 fallbackMode；hash 精确命中、rag→mysql 降级、最终动作统一写入决策观测 - 接入 vectorSyncer / observer / metrics；为 job 重试、任务成功/失败、决策分布与 fallback 补齐打点；向量 upsert/delete 统一改走公共 Syncer，并收敛 parseMemoryID 解析逻辑 5. 启动层接入 Memory 观测依赖 - 启动时创建 LoggerObserver + MetricsRegistry，并通过 NewModuleWithObserve 注入 memory 模块 前端：无 仓库：无
This commit is contained in:
Losita
119
backend/memory/observe/log_fields.go
Normal file
119
backend/memory/observe/log_fields.go
Normal file
@@ -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
|
||||
}
|
||||
158
backend/memory/observe/metrics.go
Normal file
158
backend/memory/observe/metrics.go
Normal file
@@ -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()
|
||||
}
|
||||
109
backend/memory/observe/observer.go
Normal file
109
backend/memory/observe/observer.go
Normal file
@@ -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, " "))
|
||||
}
|
||||
Reference in New Issue
Block a user