feat(memory): 记忆整理「试算（dry-run）」入口 + 面板卡（契约 v0.75）
主人要「现在就想看到在 736 条上它会建议合并哪些」，而不是等 23:00 的低峰首跑。
- 后端：Tidier.DryRun + TidyService.DryRun，**复用同一条扫描→召回→判定→构造候选路径**（抽出 tidyRoundPolicy，生产轮与试算轮只差「候选出口」与「召回降级策略」两处；禁止第二套实现）
- 🔴 零副作用：不写 memory_tidy_candidates / memory_tidy_runs，绝不改 memory_items 任何列；机械证明 = 跑前跑后 cyrene.db 与 -wal 的 SHA256 一致（测试断言「表行数不变」）
- 失败码诚实：500 tidy_unavailable / 409 tidy_disabled / 500 tidy_recall_unavailable（**embedding 不可用不降级成 0 条**）/ 503 tidy_timeout / 500 tidy_dry_run_failed；**空数组唯一含义 = 算过了没建议**
- 端点 POST /api/v1/admin/memories/tidy/dry-run（writeAuth）；面板「记忆」页加试算卡（点了才跑、无轮询、三态分开、明写「仅试算，不会改动任何记忆」）
- 真机 e2e（741 条活库副本）：76 ms / 15 分区 / 53 候选 / 41 skipped / 1 vetoed(low_confidence)；样例 merge reason=fact_subset score=1.0000、link reason=similar_but_not_contained score=0.9248
- 变异：dry-run 顺手写库 ⇒ 两条测试红（行数 0→2）；自造阈值 ⇒ 红；失败回 200 空数组 ⇒ 红
- 如实登记：Compared=688 被 400/分区护栏截断、候选上限 20/分区被打满 ⇒ 护栏值需在 741 条量级重定（非 bug）
This commit is contained in:
AskaEth committed
1 parent
3d8c30dc99
commit
d6ed9cfa2b
18 files changed
+1631
-79
No files matched your search
@@ -0,0 +1,191 @@
|
||||
package gateway
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"net/http"
|
||||
"time"
|
||||
|
||||
apperr "git.yeij.top/AskaEth/Cyrene_v2/internal/errors"
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/memory"
|
||||
)
|
||||
|
||||
// 本文件承载记忆整理「试算（dry-run）」入口（契约 v0.75；切片 MT1）。
|
||||
//
|
||||
// 它回答的是主人的那句「**现在就想看到在 736 条上它会建议合并哪些**」：
|
||||
// 整理器本身是低峰定时任务（design/23 §4，默认 23:00–07:00 才跑），在它
|
||||
// 第一次开跑之前，库里既没有候选也没有留痕 —— 面板只能空着。本端点把同一套
|
||||
// 规则**当场算一遍并把候选直接回给面板**。
|
||||
//
|
||||
// 四条不可走样的口径：
|
||||
//
|
||||
// 1. **零副作用**：跑的是 `memory.Tidier.DryRun`，它不写 memory_tidy_candidates、
|
||||
// 不写 memory_tidy_runs、**绝不改 memory_items 的任何列**（单测逐行钉死）。
|
||||
// 2. **不写第二套规则**：候选由既有 rule engine / tidier 代码路径产出，端点只做
|
||||
// 线上投影；阈值/上限一律取既有配置（MEMORY_TIDY_RECALL_THRESHOLD /
|
||||
// SCAN_LIMIT / CANDIDATE_LIMIT），端点自己**不引入任何上限**。
|
||||
// 3. **诚实失败**：未接线 ⇒ `500 tidy_unavailable`；配置关闭 ⇒ `409 tidy_disabled`；
|
||||
// 语义召回不可用 ⇒ `500 tidy_recall_unavailable`；超时 ⇒ `503 tidy_timeout`。
|
||||
// **一律不回空候选数组假装「没有建议」** —— 那是把「没算出来」谎报成「算过了，没有」。
|
||||
// 4. **只算不写 ⇒ 不审计**：它是只读计算（与 /admin/config-facts 同一档），
|
||||
// 因此不写审计链，也不进 registerAdminWriteRoutes 那条 owner-only 写路径。
|
||||
//
|
||||
// 面板按下才跑，**不做自动轮询**：试算是一次真实规则计算（扫描 + 两两召回 +
|
||||
// 包含判定），不是看板指标。
|
||||
|
||||
// tidyDryRunTimeout 是试算处理的墙钟上限。试算在既有护栏内是有界的
|
||||
// （每分区扫描 ≤ SCAN_LIMIT、参与比对 ≤ maxTidyCompareItems），显式给一个上限
|
||||
// 只为让卡住的请求（如 embedding 服务半死不活）不占着连接；超时**如实报错**。
|
||||
const tidyDryRunTimeout = 3 * time.Minute
|
||||
|
||||
// MemoryTidyDryRunner 是记忆整理「试算」的注入出口（契约 v0.75；切片 MT1）。
|
||||
// 组合根注入的就是低峰心跳跑的那个 `*memory.TidyService` —— 同一套规则、同一份
|
||||
// 配置，因此试算给出的建议与今晚 23:00 那一轮是同一口径。
|
||||
type MemoryTidyDryRunner interface {
|
||||
// DryRun 跑一轮整理规则并返回候选，零副作用。
|
||||
DryRun(ctx context.Context) (memory.TidyDryRun, error)
|
||||
}
|
||||
|
||||
// AdminTidyDryRunCandidate 是试算响应里的一条候选（契约 v0.75 §4.12）。
|
||||
// 字段与 `memory_tidy_candidates` 的落库形状同构，但**没有 status / decided\***
|
||||
// —— 试算不落库，因此不存在「已决定」这回事；ID 也不下发（它没有任何后续动作）。
|
||||
//
|
||||
// Evidence 复用领域类型（`memory.TidyEvidence`，带 JSON tag）：面板的 diff 预览
|
||||
// 需要 A/B 原文、包含证据与否决原因，字段就是按它设计的。
|
||||
type AdminTidyDryRunCandidate struct {
|
||||
Action string `json:"action"`
|
||||
SourceIDs []string `json:"sourceIds"`
|
||||
TargetID string `json:"targetId,omitempty"`
|
||||
PersonaID string `json:"personaId"`
|
||||
Scope string `json:"scope"`
|
||||
ProjectID string `json:"projectId,omitempty"`
|
||||
Kind string `json:"kind,omitempty"`
|
||||
ProposedContent string `json:"proposedContent,omitempty"`
|
||||
MergedContent string `json:"mergedContent,omitempty"`
|
||||
Reason string `json:"reason"`
|
||||
RuleVersion string `json:"ruleVersion"`
|
||||
ScoreMin float64 `json:"scoreMin"`
|
||||
ScoreMax float64 `json:"scoreMax"`
|
||||
Evidence memory.TidyEvidence `json:"evidence"`
|
||||
}
|
||||
|
||||
// AdminTidyDryRunResponse 是 POST /api/v1/admin/memories/tidy/dry-run 的线上结构
|
||||
// （契约 v0.75 §4.12）。
|
||||
//
|
||||
// `dryRun` 恒为 true：这份响应**没有**改动任何记忆，客户端可据此把「仅试算」的
|
||||
// 文案与结构绑定，而不是只靠一段本地硬编码说明。
|
||||
type AdminTidyDryRunResponse struct {
|
||||
DryRun bool `json:"dryRun"`
|
||||
RecallMode string `json:"recallMode"`
|
||||
DurationMs int64 `json:"durationMs"`
|
||||
RuleVersion string `json:"ruleVersion"`
|
||||
// 观测口径（与真跑一轮同一套计数）：扫描分区数 / 扫描条数 / 参与比对条数 /
|
||||
// 召回对数 / 被否决对数与分布。
|
||||
Partitions int `json:"partitions"`
|
||||
Scanned int `json:"scanned"`
|
||||
Compared int `json:"compared"`
|
||||
Pairs int `json:"pairs"`
|
||||
Vetoed int `json:"vetoed"`
|
||||
VetoReasons map[string]int `json:"vetoReasons"`
|
||||
// Truncated 列出被护栏截断的分区标签（扫描/比对/候选上限），供运维放大配额。
|
||||
// 它**不是**候选；缺席表示本轮没有被截断。
|
||||
Truncated []string `json:"truncated,omitempty"`
|
||||
// Candidates 恒为非 null 数组：空数组 = 「算过了，这一轮没有建议」，与
|
||||
// 「没算出来」（那种情况是错误响应）**必须能区分**。
|
||||
Candidates []AdminTidyDryRunCandidate `json:"candidates"`
|
||||
}
|
||||
|
||||
// adminMemoryTidyDryRun 是「试算整理建议」的处理函数。它只读语义、不审计
|
||||
// （见文件头注释第 4 条），失败一律如实作答。
|
||||
func (s *Server) adminMemoryTidyDryRun(w http.ResponseWriter, r *http.Request) {
|
||||
if s.memoryTidy == nil {
|
||||
writeError(w, apperr.Wrap(apperr.ErrInternal, "tidy_unavailable", "记忆整理服务未接线"))
|
||||
return
|
||||
}
|
||||
ctx, cancel := context.WithTimeout(r.Context(), tidyDryRunTimeout)
|
||||
defer cancel()
|
||||
|
||||
result, err := s.memoryTidy.DryRun(ctx)
|
||||
if err != nil {
|
||||
s.writeTidyDryRunError(w, err)
|
||||
return
|
||||
}
|
||||
writeJSON(w, http.StatusOK, adminTidyDryRunResponse(result))
|
||||
}
|
||||
|
||||
// writeTidyDryRunError 把试算失败映射成**诚实**的错误码。用户可见的 message
|
||||
// 只说明「哪一类原因」，原始错误（可能含内部地址/凭据片段）只进日志。
|
||||
func (s *Server) writeTidyDryRunError(w http.ResponseWriter, err error) {
|
||||
switch {
|
||||
case errors.Is(err, memory.ErrTidyDisabled):
|
||||
writeError(w, &apperr.AppError{
|
||||
Code: "tidy_disabled",
|
||||
Message: "记忆整理已被配置关闭（MEMORY_TIDY_ENABLED=false），试算同样不上报候选",
|
||||
HTTPCode: http.StatusConflict,
|
||||
})
|
||||
case errors.Is(err, memory.ErrTidyRecallUnavailable):
|
||||
s.log.Error("memory tidy dry-run recall unavailable", "err", err)
|
||||
writeError(w, &apperr.AppError{
|
||||
Code: "tidy_recall_unavailable",
|
||||
Message: "语义召回（embedding）不可用，试算未产出候选（试算不做静默降级）",
|
||||
HTTPCode: http.StatusInternalServerError,
|
||||
})
|
||||
case errors.Is(err, context.DeadlineExceeded):
|
||||
s.log.Error("memory tidy dry-run timed out", "err", err)
|
||||
writeError(w, &apperr.AppError{
|
||||
Code: "tidy_timeout",
|
||||
Message: "记忆整理试算超时（未产出候选）",
|
||||
HTTPCode: http.StatusServiceUnavailable,
|
||||
})
|
||||
default:
|
||||
s.log.Error("memory tidy dry-run failed", "err", err)
|
||||
writeError(w, apperr.Wrap(apperr.ErrInternal, "tidy_dry_run_failed", "记忆整理试算失败"))
|
||||
}
|
||||
}
|
||||
|
||||
// adminTidyDryRunResponse 把领域结果投影成线上结构。它**不复制**任何阈值/上限：
|
||||
// 条数与截断标签都来自领域侧已经算好的结果（Candidates 已被每分区上限截断）。
|
||||
func adminTidyDryRunResponse(result memory.TidyDryRun) AdminTidyDryRunResponse {
|
||||
out := AdminTidyDryRunResponse{
|
||||
DryRun: true,
|
||||
RecallMode: result.RecallMode,
|
||||
DurationMs: result.DurationMS,
|
||||
RuleVersion: memory.TidyRuleVersion,
|
||||
Partitions: result.Stats.Partitions,
|
||||
Scanned: result.Stats.Scanned,
|
||||
Compared: result.Stats.Compared,
|
||||
Pairs: result.Stats.Pairs,
|
||||
Vetoed: result.Stats.Vetoed,
|
||||
VetoReasons: result.Stats.VetoReasons,
|
||||
Truncated: result.Stats.Truncated,
|
||||
Candidates: make([]AdminTidyDryRunCandidate, 0, len(result.Candidates)),
|
||||
}
|
||||
for _, c := range result.Candidates {
|
||||
out.Candidates = append(out.Candidates, adminTidyDryRunCandidate(c))
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// adminTidyDryRunCandidate 投影一条候选。SourceIDs 兜成非 null 数组（面板按数组读）。
|
||||
func adminTidyDryRunCandidate(c memory.TidyCandidate) AdminTidyDryRunCandidate {
|
||||
ids := c.SourceIDs
|
||||
if ids == nil {
|
||||
ids = []string{}
|
||||
}
|
||||
return AdminTidyDryRunCandidate{
|
||||
Action: string(c.Action),
|
||||
SourceIDs: ids,
|
||||
TargetID: c.TargetID,
|
||||
PersonaID: c.PersonaID,
|
||||
Scope: string(c.Scope),
|
||||
ProjectID: c.ProjectID,
|
||||
Kind: string(c.Kind),
|
||||
ProposedContent: c.ProposedContent,
|
||||
MergedContent: c.MergedContent,
|
||||
Reason: c.Reason,
|
||||
RuleVersion: c.RuleVersion,
|
||||
ScoreMin: c.ScoreMin,
|
||||
ScoreMax: c.ScoreMax,
|
||||
Evidence: c.Evidence,
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user