feat(memory): 记忆整理**应用路径 + 调度修复 + 手动真跑**（TIDY-1，主人投诉的根因）
主人实测：memory_items 1191 行、候选 77 条全 pending、memory_tidy_runs 仅 1 行、两晚定时没跑。 根因两条（都在这片里修掉）： ① **以前根本没有执行面** —— 只有只读试算，候选永远 pending ② **调度被重启饿死** —— interval=24h 的 ticker 从进程启动算起，两天重启十几次 ⇒ 24h 永远走不完 - 应用路径：逐条 / 按 run 批量（默认 100、硬顶 500、超限 truncated）/ revert；**软合并** （status + merged_into/merged_from/merge_count，**绝不改 content、行不删**）+ 审计 （memory.tidy.apply / memory.tidy.revert）+ **幂等**（候选状态条件更新 + 行 status 闸两道） - 调度：改成**到点即跑**（catchUp：无历史+窗口内 / 距上次 run ≥ interval / 窗口起点晚于上次 run）， 「上次 run」以 memory_tidy_runs 为**持久事实**；注入时钟用例证明**重启不饿死** - 手动真跑端点 POST /admin/memories/tidy/run（同档鉴权 + 审计 + 回执：新增/合并/软删/耗时） - 候选表加 run_id 列 + 索引（前滚；顺序=建表→补列→建索引，否则既有库会 no such column） - 3 个变异自检（删 catchUp / 去掉两道 status 闸 / truncated 恒 false） ⚠️ 生产库零动作：1191 行真跑与 77 条候选应用**未执行**（按红线由主人确认后主会话执行） ⚠️ 契约段在报告里（candidates 列表/apply/revert/tidy.run），Docs/ 待登记
This commit is contained in:
AskaEth committed
1 parent
57d0e8c543
commit
454ddb0b70
18 files changed
+3181
-71
No files matched your search
@@ -0,0 +1,336 @@
|
||||
package gateway
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"net/http"
|
||||
"strconv"
|
||||
"time"
|
||||
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/auth"
|
||||
apperr "git.yeij.top/AskaEth/Cyrene_v2/internal/errors"
|
||||
"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/memory"
|
||||
)
|
||||
|
||||
// 本文件承载记忆整理**应用路径**的管理面（切片 TIDY-1；design/23 §7/§8/§11）。
|
||||
// 动因是主人的实测口径：整理只产候选、两天一条没应用（77 条全 pending），而现有
|
||||
// `POST …/tidy/dry-run` 是**只读试算**，改不了任何东西。
|
||||
//
|
||||
// 端点分工（DTO 在 admin_memory_tidy_apply_dto.go，手动真跑在
|
||||
// admin_memory_tidy_run.go —— 拆开只为守 AGENTS §10 的文件行数上限）：
|
||||
//
|
||||
// GET /api/v1/admin/memories/candidates 候选列表（含 id/runId/证据）
|
||||
// POST /api/v1/admin/memories/candidates/{id}/apply 按候选 id 应用（写记忆）
|
||||
// POST /api/v1/admin/memories/candidates/apply?runId=&limit= 批量应用（按 run / 全部待定）
|
||||
// POST /api/v1/admin/memories/candidates/{id}/revert 回滚一条已应用候选
|
||||
// POST /api/v1/admin/memories/tidy/run 手动**真跑**一轮（写候选）
|
||||
//
|
||||
// 口径：
|
||||
//
|
||||
// 1. **门同族**：全部走 `writeAuth`（owner|admin），与同族的 `GET /admin/memories`、
|
||||
// `POST …/tidy/dry-run`、`POST …/memories/{id}/revert` 同档 —— 候选正文含隐私，
|
||||
// design/23 §11 的既有取向是「含隐私正文的读侧不给 viewer」。⚠️ §11 表格把
|
||||
// candidates 写回滚标为 owner-only：那只需把 routes.go 里对应行的 `writeAuth`
|
||||
// 换成 `ownerAuth`（一行一处，本文件不用改）。
|
||||
// 2. **写动作落审计**：动作名 `memory.tidy.apply` / `memory.tidy.revert`（design/23
|
||||
// §8 的 `memory.tidy.*` 族），who 来自请求身份；审计只带计数/动作，**不带记忆正文**。
|
||||
// `POST …/tidy/run` 的审计由**领域侧**（TidyService 的 Audit 出口，design §8 的
|
||||
// `memory.tidy.run`，result 里带 trigger=manual + run_id + 计数）写，本文件不重复记
|
||||
// —— 一次手动点击只该有一条 memory.tidy.run。
|
||||
// 3. **诚实失败**：未接线 ⇒ 500 `tidy_unavailable`；候选不存在 ⇒ 404；
|
||||
// runId 查不到 ⇒ 404 `tidy_run_not_found`；配置关闭 ⇒ 409 `tidy_disabled`；
|
||||
// 超时 ⇒ 503 `tidy_timeout`。**绝不**把「没做」回成一份空结果。
|
||||
// 4. **不写第二套语义**：应用/回滚的真实动作全在 `memory.Store` 里（候选状态条件更新
|
||||
// 是幂等闸），端点只做鉴权、取参、投影与审计。
|
||||
// 5. **不加任何上限**：批量上限由领域侧（memory.DefaultTidyApplyBatchLimit 等代码
|
||||
// 默认值）决定，端点只解析 `limit` 并交给领域侧钳位（`.env` 冻结，不新增键）。
|
||||
|
||||
// MemoryTidyRunner 是记忆整理「真跑」的注入出口（切片 TIDY-1）。组合根注入的
|
||||
// 就是低峰心跳跑的那个 `*memory.TidyService`（与试算同一份配置、同一套规则）。
|
||||
//
|
||||
// 它与 `MemoryTidyDryRunner` 分开两个接口是**刻意**的：试算只读、真跑写候选 + 留痕，
|
||||
// 两者可分别接线；未实现本接口的替身（例如只做试算的测试桩）得到的是诚实的
|
||||
// 「真跑未接线」，而不是一条静默成功的假回执。
|
||||
type MemoryTidyRunner interface {
|
||||
// ManualRun 立即跑一轮**真跑**（写候选 + 写运行留痕 + 审计）。配置关闭时
|
||||
// 返回 memory.ErrTidyDisabled。
|
||||
ManualRun(ctx context.Context) (memory.TidyStats, error)
|
||||
}
|
||||
|
||||
// tidyApplyStore 是整理候选写面的窄视图，由 `*memory.Store` 实现。未实现它的
|
||||
// `Deps.Memories` 让本组端点回 500 `tidy_unavailable`（「没接线」与「没有候选」
|
||||
// 必须能分辨，与同族的 ingestReviewStore 同一手法）。
|
||||
type tidyApplyStore interface {
|
||||
ListTidyCandidates(ctx context.Context, status string, limit int) ([]memory.TidyCandidate, error)
|
||||
ApplyTidyCandidate(ctx context.Context, id string, opts memory.TidyApplyOptions) (memory.TidyApplyResult, error)
|
||||
ApplyTidyCandidates(ctx context.Context, runID string, opts memory.TidyApplyOptions) (memory.TidyApplyBatch, error)
|
||||
RevertTidyCandidate(ctx context.Context, id string, opts memory.TidyApplyOptions) (memory.TidyApplyResult, error)
|
||||
}
|
||||
|
||||
const (
|
||||
// tidyUnavailableCode 是「整理写面未接线」的线上错误码（与试算组的
|
||||
// tidy_unavailable 同名同义：它们背后是同一件事）。
|
||||
tidyUnavailableCode = "tidy_unavailable"
|
||||
// tidyApplyAction 是应用动作的审计动作名（design/23 §8）。
|
||||
tidyApplyAction = "memory.tidy.apply"
|
||||
// tidyRevertAction 是候选回滚动作的审计动作名。它与 D3 的
|
||||
// `memory.review.revert`（按**记忆 id**撤销一次软合并）**不同**：本条按**候选 id**
|
||||
// 回滚，并把候选退回 pending，因此不复用。
|
||||
tidyRevertAction = "memory.tidy.revert"
|
||||
// tidyRunTimeout 是手动真跑的墙钟上限。真跑要写候选 + 留痕，比试算多几次写入；
|
||||
// 上限存在的意义是「不让卡住的请求占着连接」，超时**如实报错**（503 tidy_timeout）。
|
||||
tidyRunTimeout = 5 * time.Minute
|
||||
)
|
||||
|
||||
// adminTidyCandidatesList 处理 GET /api/v1/admin/memories/candidates。
|
||||
// 只读、不审计（与同族只读管理端点同一档）。
|
||||
func (s *Server) adminTidyCandidatesList(w http.ResponseWriter, r *http.Request) {
|
||||
store := s.tidyCandidates()
|
||||
if store == nil {
|
||||
writeError(w, apperr.Wrap(apperr.ErrInternal, tidyUnavailableCode, "记忆整理候选未接线"))
|
||||
return
|
||||
}
|
||||
// limit 复用同族读侧那一个解析器（默认 100 / 钳到 500 / 非法 400）——
|
||||
// 本切片不复制第三份 limit 解析（AGENTS §10「三次复制必须抽取」，此处是第二次）。
|
||||
limit, ok := parseMemoryReviewLimit(r)
|
||||
if !ok {
|
||||
writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "invalid limit"))
|
||||
return
|
||||
}
|
||||
cands, err := store.ListTidyCandidates(r.Context(), r.URL.Query().Get("status"), limit)
|
||||
if err != nil {
|
||||
s.log.Error("list tidy candidates", "err", err)
|
||||
writeError(w, apperr.Wrap(apperr.ErrInternal, "tidy_candidates_failed", "读取整理候选失败"))
|
||||
return
|
||||
}
|
||||
out := AdminTidyCandidatesResponse{
|
||||
Candidates: make([]AdminTidyCandidate, 0, len(cands)),
|
||||
Count: len(cands),
|
||||
}
|
||||
for _, c := range cands {
|
||||
out.Candidates = append(out.Candidates, adminTidyCandidate(c))
|
||||
}
|
||||
writeJSON(w, http.StatusOK, out)
|
||||
}
|
||||
|
||||
// adminTidyCandidateApply 处理 POST /api/v1/admin/memories/candidates/{id}/apply：
|
||||
// 应用**一条**候选（唯一真正改记忆的粒度之一）。三种结果都如实作答：
|
||||
// 不存在 ⇒ 404；已决定/不可应用 ⇒ 200 + `status:skipped`（幂等不是错误）；
|
||||
// 真的改了 ⇒ 200 + `status:applied` + `affectedIds`。
|
||||
func (s *Server) adminTidyCandidateApply(w http.ResponseWriter, r *http.Request) {
|
||||
store := s.tidyCandidates()
|
||||
if store == nil {
|
||||
s.auditClaims(r, tidyApplyAction, "error")
|
||||
writeError(w, apperr.Wrap(apperr.ErrInternal, tidyUnavailableCode, "记忆整理候选未接线"))
|
||||
return
|
||||
}
|
||||
id := r.PathValue("id")
|
||||
if id == "" {
|
||||
s.auditClaims(r, tidyApplyAction, "error")
|
||||
writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "candidate id is required"))
|
||||
return
|
||||
}
|
||||
res, err := store.ApplyTidyCandidate(r.Context(), id, memory.TidyApplyOptions{Actor: s.tidyActor(r)})
|
||||
if err != nil {
|
||||
s.auditClaims(r, tidyApplyAction, "error")
|
||||
if errors.Is(err, memory.ErrTidyCandidateNotFound) {
|
||||
writeError(w, apperr.Wrap(apperr.ErrNotFound, "not_found", "整理候选 %q 不存在", id))
|
||||
return
|
||||
}
|
||||
s.log.Error("apply tidy candidate", "err", err, "candidate", id)
|
||||
writeError(w, apperr.Wrap(apperr.ErrInternal, "tidy_apply_failed", "应用整理候选失败"))
|
||||
return
|
||||
}
|
||||
s.auditClaims(r, tidyApplyAction, tidyApplyAuditResult(res))
|
||||
writeJSON(w, http.StatusOK, adminTidyApplyResult(res))
|
||||
}
|
||||
|
||||
// adminTidyCandidatesApplyBatch 处理 POST /api/v1/admin/memories/candidates/apply：
|
||||
// **批量**应用。`runId` 给出时只应用该轮产出的候选（按 run）；省略时应用全部待定
|
||||
// （「全部待定应用」这一档）。`limit` 省略 ⇒ 领域侧默认值。
|
||||
//
|
||||
// 逐条结果都在 `results` 里（失败隔离），超限如实回报 `truncated` + `total`。
|
||||
func (s *Server) adminTidyCandidatesApplyBatch(w http.ResponseWriter, r *http.Request) {
|
||||
store := s.tidyCandidates()
|
||||
if store == nil {
|
||||
s.auditClaims(r, tidyApplyAction, "error")
|
||||
writeError(w, apperr.Wrap(apperr.ErrInternal, tidyUnavailableCode, "记忆整理候选未接线"))
|
||||
return
|
||||
}
|
||||
limit, ok := parseTidyApplyLimit(r)
|
||||
if !ok {
|
||||
s.auditClaims(r, tidyApplyAction, "error")
|
||||
writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "invalid limit"))
|
||||
return
|
||||
}
|
||||
runID := r.URL.Query().Get("runId")
|
||||
batch, err := store.ApplyTidyCandidates(r.Context(), runID, memory.TidyApplyOptions{
|
||||
Actor: s.tidyActor(r),
|
||||
Limit: limit,
|
||||
})
|
||||
if err != nil {
|
||||
s.auditClaims(r, tidyApplyAction, "error")
|
||||
if errors.Is(err, memory.ErrTidyRunRecordNotFound) {
|
||||
writeError(w, apperr.Wrap(apperr.ErrNotFound, "tidy_run_not_found", "整理运行 %q 不存在", runID))
|
||||
return
|
||||
}
|
||||
s.log.Error("apply tidy candidates", "err", err, "run_id", runID)
|
||||
writeError(w, apperr.Wrap(apperr.ErrInternal, "tidy_apply_failed", "批量应用整理候选失败"))
|
||||
return
|
||||
}
|
||||
s.auditClaims(r, tidyApplyAction, tidyBatchAuditResult(batch))
|
||||
writeJSON(w, http.StatusOK, adminTidyApplyBatch(batch))
|
||||
}
|
||||
|
||||
// adminTidyCandidateRevert 处理 POST /api/v1/admin/memories/candidates/{id}/revert：
|
||||
// 回滚一条已应用候选（记忆行复原 + 候选退回 pending，行永不物理删除，design §8）。
|
||||
func (s *Server) adminTidyCandidateRevert(w http.ResponseWriter, r *http.Request) {
|
||||
store := s.tidyCandidates()
|
||||
if store == nil {
|
||||
s.auditClaims(r, tidyRevertAction, "error")
|
||||
writeError(w, apperr.Wrap(apperr.ErrInternal, tidyUnavailableCode, "记忆整理候选未接线"))
|
||||
return
|
||||
}
|
||||
id := r.PathValue("id")
|
||||
if id == "" {
|
||||
s.auditClaims(r, tidyRevertAction, "error")
|
||||
writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "candidate id is required"))
|
||||
return
|
||||
}
|
||||
res, err := store.RevertTidyCandidate(r.Context(), id, memory.TidyApplyOptions{Actor: s.tidyActor(r)})
|
||||
if err != nil {
|
||||
s.auditClaims(r, tidyRevertAction, "error")
|
||||
if errors.Is(err, memory.ErrTidyCandidateNotFound) {
|
||||
writeError(w, apperr.Wrap(apperr.ErrNotFound, "not_found", "整理候选 %q 不存在", id))
|
||||
return
|
||||
}
|
||||
s.log.Error("revert tidy candidate", "err", err, "candidate", id)
|
||||
writeError(w, apperr.Wrap(apperr.ErrInternal, "tidy_revert_failed", "回滚整理候选失败"))
|
||||
return
|
||||
}
|
||||
s.auditClaims(r, tidyRevertAction, tidyApplyAuditResult(res))
|
||||
writeJSON(w, http.StatusOK, adminTidyApplyResult(res))
|
||||
}
|
||||
|
||||
// tidyCandidates 返回当前接入的整理候选写面；`Memories` 未实现该视图时为 nil。
|
||||
func (s *Server) tidyCandidates() tidyApplyStore {
|
||||
if s.memories == nil {
|
||||
return nil
|
||||
}
|
||||
store, ok := s.memories.(tidyApplyStore)
|
||||
if !ok {
|
||||
return nil
|
||||
}
|
||||
return store
|
||||
}
|
||||
|
||||
// tidyActor 返回决定者的审计标签（落 memory_tidy_candidates.decided_by）。
|
||||
// 与 auditClaimsAccount 的 who 同口径，使面板「谁批的」与审计链能对上。
|
||||
func (s *Server) tidyActor(r *http.Request) string {
|
||||
if claims, ok := auth.ClaimsFromContext(r.Context()); ok {
|
||||
return claims.Sub + ":" + string(claims.Role)
|
||||
}
|
||||
return "anonymous"
|
||||
}
|
||||
|
||||
// parseTidyApplyLimit 解析批量的 limit：缺省/空 ⇒ 0（交给领域侧默认值），
|
||||
// 非整数或负数 ⇒ ok=false（调用方回 400）。上限由**领域侧**钳位，端点不复制那个常量。
|
||||
func parseTidyApplyLimit(r *http.Request) (int, bool) {
|
||||
raw := r.URL.Query().Get("limit")
|
||||
if raw == "" {
|
||||
return 0, true
|
||||
}
|
||||
v, err := strconv.Atoi(raw)
|
||||
if err != nil || v < 0 {
|
||||
return 0, false
|
||||
}
|
||||
return v, true
|
||||
}
|
||||
|
||||
// adminTidyCandidate 投影一条落库候选。SourceIDs 兜成非 null 数组；
|
||||
// 时间为 UTC RFC3339（与同族管理 DTO 同一口径）。
|
||||
func adminTidyCandidate(c memory.TidyCandidate) AdminTidyCandidate {
|
||||
ids := c.SourceIDs
|
||||
if ids == nil {
|
||||
ids = []string{}
|
||||
}
|
||||
return AdminTidyCandidate{
|
||||
ID: c.ID,
|
||||
Action: string(c.Action),
|
||||
Status: c.Status,
|
||||
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,
|
||||
RunID: c.RunID,
|
||||
ScoreMin: c.ScoreMin,
|
||||
ScoreMax: c.ScoreMax,
|
||||
CreatedAt: c.CreatedAt.UTC().Format(time.RFC3339),
|
||||
Evidence: c.Evidence,
|
||||
}
|
||||
}
|
||||
|
||||
// adminTidyApplyResult 投影一条应用/回滚结果。
|
||||
func adminTidyApplyResult(res memory.TidyApplyResult) AdminTidyApplyResult {
|
||||
ids := res.AffectedIDs
|
||||
if ids == nil {
|
||||
ids = []string{}
|
||||
}
|
||||
return AdminTidyApplyResult{
|
||||
CandidateID: res.CandidateID,
|
||||
Action: string(res.Action),
|
||||
Status: string(res.Status),
|
||||
Reason: res.Reason,
|
||||
TargetID: res.TargetID,
|
||||
AffectedIDs: ids,
|
||||
}
|
||||
}
|
||||
|
||||
// adminTidyApplyBatch 投影批量回执（results 恒为非 null 数组）。
|
||||
func adminTidyApplyBatch(batch memory.TidyApplyBatch) AdminTidyApplyBatchResponse {
|
||||
out := AdminTidyApplyBatchResponse{
|
||||
RunID: batch.RunID,
|
||||
Limit: batch.Limit,
|
||||
Total: batch.Total,
|
||||
Truncated: batch.Truncated,
|
||||
Applied: batch.Applied,
|
||||
Skipped: batch.Skipped,
|
||||
Failed: batch.Failed,
|
||||
Merged: batch.Merged,
|
||||
Archived: batch.Archived,
|
||||
Reclassified: batch.Reclassified,
|
||||
Results: make([]AdminTidyApplyResult, 0, len(batch.Results)),
|
||||
}
|
||||
for _, res := range batch.Results {
|
||||
out.Results = append(out.Results, adminTidyApplyResult(res))
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// tidyApplyAuditResult 渲染单条应用/回滚的审计 result。它**以 ok 开头**（与
|
||||
// 同族「result=ok/error」的既有口径一致，面板按前缀就能分桶），其后才挂动作与
|
||||
// 结果类别、受影响行数 —— 绝不带记忆正文或候选正文（design §8）。
|
||||
func tidyApplyAuditResult(res memory.TidyApplyResult) string {
|
||||
return "ok action=" + string(res.Action) +
|
||||
" status=" + string(res.Status) +
|
||||
" reason=" + res.Reason +
|
||||
" affected=" + strconv.Itoa(len(res.AffectedIDs))
|
||||
}
|
||||
|
||||
// tidyBatchAuditResult 渲染批量应用的审计 result（同样以 ok 开头）：带真总数与
|
||||
// 超限标记，因此审计能回答「这一轮到底批了多少、有没有被上限截住」。
|
||||
func tidyBatchAuditResult(batch memory.TidyApplyBatch) string {
|
||||
return "ok run_id=" + batch.RunID +
|
||||
" limit=" + strconv.Itoa(batch.Limit) +
|
||||
" total=" + strconv.Itoa(batch.Total) +
|
||||
" truncated=" + strconv.FormatBool(batch.Truncated) +
|
||||
" applied=" + strconv.Itoa(batch.Applied) +
|
||||
" skipped=" + strconv.Itoa(batch.Skipped) +
|
||||
" failed=" + strconv.Itoa(batch.Failed)
|
||||
}
|
||||
Reference in new issue
Block a user