feat(memory): D3 从「异步后置」改成「同步入库闸」—— 由整理层决定入库形态
主人 2026-10-07 裁定：「把记忆整理功能接到昔涟和记忆库中间做审查，由整理功能 进行入库」。现状是**异步 + 入库后软合并** ⇒ 行已经落库才审，面板/召回先脏后清， 而写入速率实测 ~25 条/小时（≈600/天）⇒ 清理永远追不上。 落法（三条硬规格，全部落地）： ① **同步闸但有界**：闸在 `store.go:247` 的 `planIngest`（INSERT **之前**）， 本体 `preinsert_gate.go`。墙钟预算 **150ms**（实测最坏 p95 仅 4~7ms ⇒ 20~50 倍 余量）、候选扫描上限 **100**（比异步侧 200 更紧，因为它在写路径上）。 🔴 **零远端 embedding**：闸恒用词项余弦（`deps.Embedder` 根本不参与）—— 远端 embedding 一次 2.3~3.0s 且对同文本返回不同向量（不可复现），不许摆在同步 路径上拍板。 ② **fail-open，绝不丢记忆**：候选源报错 ⇒ `gate:candidates_unavailable`；超预算 ⇒ `gate:budget_exceeded` ⇒ **照常 insert(active) + 投既有队列 + 留痕 + WARN**。 ③ **三态落库（落 merged，而不是"不插入"）**：确定性命中（字面重复 / 归一化等价 / 真包含）⇒ INSERT **直接带 `status='merged'` + `merged_into=<存活行>`**，存活行 `merged_from` 追加、`merge_count`+1 ⇒ **新行从不进 active、从不建向量索引**， 而**行与原文都在表里 ⇒ revert 无损**。若"干脆不插"，那条文本从未存在过行， revert 无从下手，违反 design/23 §8 的红线。 - **不与异步 D3 重复审**：闸做决定的那条 `Async=false`（留痕由闸自己落， 审计动作名 `memory.ingest.gate`）；真新/拿不准的走原有队列（留痕仍归异步层）。 - **开关**：`$DATA_DIR/config/memory-tidy.json` 的 `{"ingestGate": false}` ⇒ 一键回到 「只插不审」（= 改动前的异步行为）。**零新 env 键**（`.env` 未碰）。 - 顺手把 `store.go` 的行映射拆到 `store_rows.go`（守 §10 的 ≤500 行）。 验收（主会话复跑 + 亲自变异）：`go build ./...` + `go vet` 绿；memory 包测试绿； 我用 -overlay 摘掉闸的预算 ⇒ `TestIngestGate_Add墙钟有界` 与 `…failOpen_超预算绝不丢记忆` 变红（"Add 等了 2.0s，越过闸预算 150ms"）。 子代理另做 2 个变异（去掉预算 / 把 fail-open 改成 fail-closed）全红，并实测 **闸开 vs 关的 `Add` 额外墙钟：p50 ≈2.5~3.1ms、p95 ≈4~7ms**（基线批均值 35.8µs）。 ⚠️ 未部署（要一次 build + restart）；⚠️ 已知边界（如实）：闸只用词项余弦 ⇒ 「同义但字面差得远」拦不住（有意为之，由异步层/夜间整理兜）；闸的候选是**最新 100 条**（更老的重复闸看不到）；**并发同内容双写**仍可能两条都落 active（既有竞态， SELECT 与 INSERT 不在同一事务，非本次引入，第二层会清）。
This commit is contained in:
AskaEth committed
1 parent
f310173b4c
commit
90f430216a
13 files changed
+1448
-140
No files matched your search
@@ -102,6 +102,24 @@ type ReviewConfig struct {
|
||||
// 入库前审查与夜间整理必须用同一把尺子，否则同一对条目会有两个结论。
|
||||
// 非正用设计稿默认值。
|
||||
Threshold float64
|
||||
// DisableIngestGate 关闭**同步入库闸**（任务书规格 3 的开关）。
|
||||
//
|
||||
// 它是**反向**字段，且这是刻意的：bool 的零值必须落在「默认行为」上 ——
|
||||
// 同步闸本机制的默认取向（主人 2026-10-07「把记忆整理功能接到昔涟和记忆库
|
||||
// 中间做审查，由整理功能进行入库」），若写成正向的 EnableIngestGate，任何没
|
||||
// 显式配过的地方（含测试与组合根构造的一半配置）都会被读成「关掉」，与默认
|
||||
// 相反。要一键回到「只插不审」（= 本次改动之前的异步行为），写
|
||||
// `$DATA_DIR/config/memory-tidy.json` 的 `{"ingestGate": false}`（**零新
|
||||
// env 键**：`.env` 已冻结，design/13 §2.1）。
|
||||
DisableIngestGate bool
|
||||
// GateBudget 是同步入库闸的**总墙钟预算**（任务书规格 1：写入路径不许变慢）。
|
||||
// 非正用代码默认值 defaultReviewGateBudget。超预算一律 fail-open（照常插入 +
|
||||
// 留痕），绝不静默丢。
|
||||
GateBudget time.Duration
|
||||
// GateScanLimit 是同步入库闸的候选扫描上限。它比异步队列更紧（后者
|
||||
// ScanLimit 默认 200），因为它在**写入路径**上：非正用代码默认值
|
||||
// defaultReviewGateScanLimit，且最终还会被 cfg.ScanLimit 收紧取小。
|
||||
GateScanLimit int
|
||||
}
|
||||
|
||||
// ReviewDeps 是注入给入库前审查的依赖。Store 必需；其余可空并优雅降级。
|
||||
@@ -118,6 +136,10 @@ type ReviewDeps struct {
|
||||
Now func() time.Time
|
||||
// Log 是基础日志器，来源标记为 "memory/review"。
|
||||
Log *slog.Logger
|
||||
// GateCandidates 是**同步入库闸**的候选读取出口。为 nil 时用 store 的
|
||||
// 生产口径（Store.listReviewCandidates，分区过滤写在 SQL 里）。测试用它
|
||||
// 注入慢/坏的候选源，验证「预算有界」与「超时 fail-open」这两条。
|
||||
GateCandidates func(ctx context.Context, p tidyPartition, excludeID string, limit int) ([]MemoryItem, error)
|
||||
}
|
||||
|
||||
// IngestReview 是一条入库前审查留痕（design/23 §15 D3-8）。它**不含记忆正文**：
|
||||
@@ -143,17 +165,6 @@ type IngestReview struct {
|
||||
CreatedAt time.Time
|
||||
}
|
||||
|
||||
// ReviewStats 是审查的观测计数（进程内累计，供日志/测试断言）。
|
||||
type ReviewStats struct {
|
||||
Reviewed int
|
||||
Skipped int
|
||||
Merged int
|
||||
Modified int
|
||||
Created int
|
||||
Dropped int
|
||||
Failed int
|
||||
}
|
||||
|
||||
// PreInsertReviewer 是入库前审查服务。用 NewPreInsertReviewer 构建，用 Start
|
||||
// 拉起工作协程、Stop 停它；Review 是同步入口（测试与手动核查用）。
|
||||
type PreInsertReviewer struct {
|
||||
@@ -206,9 +217,34 @@ func normalizeReviewConfig(cfg ReviewConfig) ReviewConfig {
|
||||
if cfg.Threshold <= 0 {
|
||||
cfg.Threshold = defaultTidyRecallThreshold
|
||||
}
|
||||
if cfg.GateBudget <= 0 {
|
||||
cfg.GateBudget = defaultReviewGateBudget
|
||||
}
|
||||
if cfg.GateScanLimit <= 0 {
|
||||
cfg.GateScanLimit = defaultReviewGateScanLimit
|
||||
}
|
||||
return cfg
|
||||
}
|
||||
|
||||
// gateEnabled 报告**同步入库闸**是否生效（任务书规格 3 的开关）。
|
||||
// 总开关关闭或闸被显式关掉时它都为 false，此时写入路径逐字回到「只插不审」。
|
||||
func (r *PreInsertReviewer) gateEnabled() bool {
|
||||
return r != nil && r.cfg.Enabled && !r.cfg.DisableIngestGate
|
||||
}
|
||||
|
||||
// gateScanLimit 返回同步闸实际使用的候选上限：配置值与其默认值的较小者 ——
|
||||
// 写入路径上的扫描必须比异步队列更紧（任务书规格 1）。
|
||||
func (r *PreInsertReviewer) gateScanLimit() int {
|
||||
limit := r.cfg.GateScanLimit
|
||||
if limit <= 0 {
|
||||
limit = defaultReviewGateScanLimit
|
||||
}
|
||||
if r.cfg.ScanLimit > 0 && r.cfg.ScanLimit < limit {
|
||||
return r.cfg.ScanLimit
|
||||
}
|
||||
return limit
|
||||
}
|
||||
|
||||
// SessionID 返回审查运行的会话标识：**复用既有的 sess-memorytidy 装配**
|
||||
// （design/23 §4.1 B；§15 D3 要求「走记忆管理会话」，不许造第二形态会话）。
|
||||
func (r *PreInsertReviewer) SessionID() string { return TidySessionID }
|
||||
@@ -253,6 +289,9 @@ func (r *PreInsertReviewer) Start(ctx context.Context) {
|
||||
"timeout", r.cfg.Timeout.String(),
|
||||
"recall_threshold", r.cfg.Threshold,
|
||||
"rule_version", IngestRuleVersion,
|
||||
"sync_gate", r.gateEnabled(),
|
||||
"gate_budget", r.cfg.GateBudget.String(),
|
||||
"gate_scan_limit", r.gateScanLimit(),
|
||||
"sweep_interval", DefaultIngestReviewGCInterval.String(),
|
||||
"retention", DefaultIngestReviewRetention.String(),
|
||||
"max_reviews", DefaultIngestReviewMaxRows)
|
||||
@@ -380,7 +419,7 @@ func (r *PreInsertReviewer) Review(ctx context.Context, item MemoryItem) (Ingest
|
||||
// 一次已经生效的合并（回滚会把审查看成比结论更权威，那更危险）。
|
||||
r.log.Warn("memory ingest review record insert failed", "item_id", item.ID, "error", err)
|
||||
}
|
||||
r.audit(rev)
|
||||
r.auditWith(reviewAuditVerb, rev)
|
||||
r.recordDecision(rev)
|
||||
return rev, nil
|
||||
}
|
||||
@@ -432,44 +471,3 @@ func (r *PreInsertReviewer) buildRecord(item MemoryItem, v ingestVerdict, merged
|
||||
}
|
||||
return rev
|
||||
}
|
||||
|
||||
// audit 写一条审计。它**只带决定与 id，不带任何记忆正文**。
|
||||
func (r *PreInsertReviewer) audit(rev IngestReview) {
|
||||
result := fmt.Sprintf("decision=%s reason=%s item=%s target=%s degraded=%t score=%.3f",
|
||||
rev.Decision, rev.Reason, rev.ItemID, rev.TargetID, rev.Degraded, rev.Score)
|
||||
if r.deps.Audit == nil {
|
||||
r.log.Debug("memory ingest review audit (no sink configured)", "what", reviewAuditVerb, "result", result)
|
||||
return
|
||||
}
|
||||
r.deps.Audit(reviewAuditWho, reviewAuditVerb, result)
|
||||
}
|
||||
|
||||
// recordDecision 累计观测计数（含降级计数，便于运维判读）。
|
||||
func (r *PreInsertReviewer) recordDecision(rev IngestReview) {
|
||||
r.bump(func(s *ReviewStats) {
|
||||
s.Reviewed++
|
||||
switch rev.Decision {
|
||||
case IngestSkip:
|
||||
s.Skipped++
|
||||
case IngestMerge:
|
||||
s.Merged++
|
||||
case IngestModify:
|
||||
s.Modified++
|
||||
default:
|
||||
s.Created++
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
// bump 在互斥下修改计数（工作协程与手动 Review 都可能调用）。
|
||||
func (r *PreInsertReviewer) bump(apply func(*ReviewStats)) {
|
||||
r.statsMu.Lock()
|
||||
defer r.statsMu.Unlock()
|
||||
apply(&r.stats)
|
||||
}
|
||||
|
||||
// reviewStatsLabel 把计数渲染成一条稳定日志串。
|
||||
func reviewStatsLabel(s ReviewStats) string {
|
||||
return fmt.Sprintf("reviewed=%d skip=%d merge=%d modify=%d create=%d dropped=%d failed=%d",
|
||||
s.Reviewed, s.Skipped, s.Merged, s.Modified, s.Created, s.Dropped, s.Failed)
|
||||
}
|
||||
Reference in new issue
Block a user