feat(memory): 记忆整理调优面板读写（三态 + 热生效 + 面板表单）

主人 2026-10-07 两条口径：「.env 只做兜底用，后端自动创建独立的面板配置文件
之后就走面板配置文件，这些键优先从面板配置上取」+「频率必须调，可以调到 1 小时
或者三小时，或者动态分配（白天短、静默期长）」。

此前 $DATA_DIR/config/memory-tidy.json 只有读路径（装配期读一次 + 启动播种）：
主人要改频率只能改文件 + 重启后端。本切片补上「读回来 → 改 → 落盘 → 当场生效」。

后端（读写端点，契约待塔登记 v0.92）：
- GET  /api/v1/admin/memories/tidy/tuning  读盘上 7 键值 + 取值规则 specs +
  缺位时 .env 档的进程生效值（与 /admin/config-facts 同源）
- PUT  同路径：三态补丁（键缺位 = 不改动 / 合法值 = 采用 / 非法值 = 400 且盘上一
  个字节都不动）+ null 清除哨兵（删键 ⇒ 回到下一档）+ writeAuth + 审计
  memory.tidy.tuning；值一个都没变时不落盘，文件解不开时拒绝覆盖（409）
- 落盘走 runtimeconfig.PatchMemoryTidyTuning（原子写 temp+rename，与
  SeedMemoryTidy/SaveWebSearch 同族同手法）；补丁语义保留下受管的其它键
  （t1Judge/t1PerWindow/autoApplyPerRound 原样保留）
- 热生效：保存后按「面板 > .env > 代码默认」重算并叠到运行期对象；整理档会
  重排心跳（否则新周期要等旧周期那一觉睡完），审查档当场改 ingestGate/tempTtlSec。
  未接线/失败时如实回 hot:false + hotError，绝不把「落盘了」说成「生效了」

前端（Miuix）：
- 记忆管理页新增「记忆整理调优」卡：7 键表单（中文标签、单位、留空⇒跟随谁、
  env 档当前值、坏值就地报错并拦住保存、保存后回显从磁盘读回的真值）
- 试算卡的 recallMode 按契约 v0.91 如实渲染：embedding / lexical（已降级）/
  mixed（部分分区降级）/ ""（无候选可比）——空串不再渲染成空标签；并把
  error.code=tidy_recall_unavailable 单列一句（「尝试过但向量源不可用」，与
  「没有候选可比」显式区分）

验证：go test ./internal/{services/gateway,runtime/memory,config/runtimeconfig}
全绿；三态/清除/坏文件拒写/同值不重写/热生效接线各有用例，并逐条做过变异自证；
tsc --noEmit + vite build 通过；两个 esbuild 前端测试 39 + 34 + 41 checks 通过。

internal/services/gateway/admin_memory_tuning.go

@@ -0,0 +1,331 @@
+package gateway
+
+import (
+	"errors"
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"strings"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config/runtimeconfig"
+	apperr "git.yeij.top/AskaEth/Cyrene_v2/internal/errors"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/logger"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/memory"
+)
+
+// 本文件承载记忆整理「面板调优」的**管理读写端点**（契约待塔登记，见回报）：
+//
+//	GET /api/v1/admin/memories/tidy/tuning   读：盘上的 7 键值 + 取值规则
+//	PUT /api/v1/admin/memories/tidy/tuning   写：三态补丁 + 原子落盘 + 热生效
+//
+// 它回答的是主人的两句原话（逐字，见 M4 mission Context）：
+//
+//	「`.env` 只做兜底用 在除了第1次部署之后 后端自动创建 独立的面板配置文件之后就走
+//	 面板配置文件。这些键优先从面板配置上取」
+//	「频率必须调 可以调 1 小时或者三小时 或者动态分配，比如白天是间隔短一点 晚上到了
+//	 静默期稍微长一点」
+//
+// 此前 `$DATA_DIR/config/memory-tidy.json` **只有读路径**（`cmd/cyrene/wire_memory_tidy.go`
+// 在装配期读一次 + 启动播种）：主人要改频率只能 SSH 改文件 + 重启后端。本切片把
+// 「读回来 → 改 → 落盘」这条面板路径补上，**零新 env 键**（`.env` 已冻结，
+// design/13 §2.1）、**不新开文件家族**。
+//
+// 四条不可走样的口径：
+//
+//  1. **三态**（硬要求，与契约里 `plugin.saveProvider` 同族语义）：键**缺位** ⇒ 不动；
+//     **合法值** ⇒ 采用；**非法值** ⇒ `400 invalid_payload` 且**盘上一个字节都不动**。
+//     `null` 是这一族的清除哨兵（= 删掉该键、回到下一档兜底）。三态的实现与
+//     「非法值不落盘」的证据在 `admin_memory_tuning_file.go` 的
+//     `parseMemoryTidyTuningPatch`（解析阶段就拒，落盘只在解析成功之后发生）。
+//  2. **写端点带审计**（动作 `memory.tidy.tuning`），且**不改** `.env`、不重启后端。
+//  3. **热生效**：保存后把新值当场叠到运行期（可选能力，见 MemoryTidyTuningApplier）。
+//     能力不存在或失败时，响应 `hot:false` + `hotError`，面板**如实**说「已落盘、
+//     要重启后端」——绝不把「落盘了」说成「生效了」。
+//  4. **诚实回话**：写成功后的响应是**重新读盘**的结果（真值回显），不是「我以为
+//     写成了什么」；盘上文件解不开时读/写**都**拒绝（`409 tuning_corrupt`）并说明
+//     运行期此刻正回落 `.env`/代码默认。
+//
+// 权限：GET 与 PUT 都走 **writeAuth（owner|admin）**（与本族其它记忆端点
+// `/admin/memories`、`POST /admin/memories/{id}/revert` 同档）——它是私有记忆面的
+// 运行期旋钮，不是给 viewer 的监控投影。
+
+// memoryTuningLogSource 是本子功能的日志来源（模块/子功能可追溯，AGENTS §10）。
+const memoryTuningLogSource = "gateway/memory-tuning"
+
+// memoryTuningAuditAction 是写端点落审计的动作名（与 memory.tidy.apply /
+// memory.tidy.reject 同一族命名）。
+const memoryTuningAuditAction = "memory.tidy.tuning"
+
+// memoryTuningMaxBodyBytes 是写端点请求体的墙钟上限。这个文件是给人改的小配置
+// （11 个标量键），正常请求体不到 200 字节；给上限只为让畸形/超大请求不占内存，
+// 不是业务上限。
+const memoryTuningMaxBodyBytes = 16 << 10
+
+// MemoryTidyTuningApplier 是「把面板值当场叠到**整理自动档**」的可选能力。
+//
+// 它**不是**必需依赖：组合根注入的整理服务（`deps.MemoryTidy` = `*memory.TidyService`）
+// 实现了它 ⇒ 保存后立刻生效；没实现 ⇒ 值照旧落盘、但要等后端重启，响应里
+// `hot:false` 如实说出来（口径 3）。
+//
+// base 是**`.env` 层**（由 `memory.TidyConfigFromConfig` 从进程生效配置投影而来，
+// 与 wireMemoryTidy 用的是同一个唯一实现点）；panel 是刚落盘的那一份。实现必须按
+// 「面板 > `.env` > 代码默认」逐键重算，且**缺位键保持 base 的值** —— 也就是
+// wireMemoryTidy 当初那一遍的同一口径，只是可以随时再跑一次。
+type MemoryTidyTuningApplier interface {
+	ApplyPanelTuning(base memory.TidyConfig, panel runtimeconfig.MemoryTidyTuning) error
+}
+
+// MemoryIngestTuningApplier 同理，服务于**同步入库闸 / 入库前审查**一侧
+// （`ingestGate` / `tempTtlSec`）——它的持有者是记忆存储，因此由 `deps.Memories`
+// 那个出口解析（网关不为此新开依赖面）。
+type MemoryIngestTuningApplier interface {
+	ApplyIngestPanelTuning(panel runtimeconfig.MemoryTidyTuning) error
+}
+
+// AdminMemoryTidyTuningView 是 GET / PUT `/admin/memories/tidy/tuning` 的 data。
+type AdminMemoryTidyTuningView struct {
+	// Path 是面板配置文件的落点（**相对 `$DATA_DIR`**，如 `config/memory-tidy.json`）：
+	// 面板据此如实告诉主人改的是哪个文件，而不必把部署绝对路径下发。
+	Path string `json:"path"`
+	// Present 报告那份文件是否已存在且有内容。false = 还没播种（后端**下次启动**
+	// 会自动按当时生效值创建它，见 runtimeconfig.SeedMemoryTidy）。
+	Present bool `json:"present"`
+	// Hot 报告这次结果是否**当场生效**（true）。false = 已落盘，但要等后端重启 ——
+	// 面板必须照实说，不得显示成「已生效」。GET 里恒为 false：只读不改变任何东西，
+	// 「生效」这个问题在只读路径上没有意义。
+	Hot bool `json:"hot"`
+	// HotError 在「已保存、但没能在运行期立刻生效」时给出原因（`hot:false` 时才有）。
+	HotError string `json:"hotError,omitempty"`
+	// Specs 是这 7 个键的**取值规则**（类型/单位/上下界/兜底来源），随读下发 ⇒
+	// 面板的表单与就地校验都由它驱动，不会出现「面板允许、后端 400」的两套规则。
+	Specs []memoryTidyTuningSpec `json:"specs"`
+	// Values 是**盘上**的值：键缺位 ⇒ 整个键不出现（= 跟随兜底），不编一个 0 ——
+	// 「写了 0」（坏值，运行期会 WARN 回落）与「没写」在面板上必须看得出区别。
+	Values map[string]any `json:"values"`
+	// EnvValues 是缺位时**下一档（`.env`）**的进程生效值（只读下发）：面板据此写
+	// 「留空 ⇒ 跟随 `.env` 的 86400」，而不必自己猜一个数。与
+	// GET /admin/config-facts 同源（都取 `s.cfg`，网关绝不直接 fopen `.env`）。
+	// 某个键**连 `.env` 档也没有值**（未填 / 结构性无此键）时它不出现。
+	EnvValues map[string]int `json:"envValues,omitempty"`
+}
+
+// adminMemoryTidyTuningRead 是 GET 的处理函数：只读、不审计（与
+// /admin/config-facts、tidy 试算同一档：读事实不改状态）。
+func (s *Server) adminMemoryTidyTuningRead(w http.ResponseWriter, _ *http.Request) {
+	path, ok := s.memoryTidyTuningPath()
+	if !ok {
+		writeError(w, apperr.Wrap(apperr.ErrInternal, "tuning_unavailable", "数据目录未接线，面板配置文件落点无法确定"))
+		return
+	}
+	view, err := s.buildMemoryTidyTuningView(path)
+	if err != nil {
+		s.writeTuningCorrupt(w, err)
+		return
+	}
+	writeJSON(w, http.StatusOK, view)
+}
+
+// adminMemoryTidyTuningWrite 是 PUT 的处理函数：三态补丁 → 原子落盘 → 热生效 →
+// 审计。顺序是刻意的：**校验全部发生在落盘之前**（口径 1），落盘之后才谈生效。
+func (s *Server) adminMemoryTidyTuningWrite(w http.ResponseWriter, r *http.Request) {
+	body, err := io.ReadAll(io.LimitReader(r.Body, memoryTuningMaxBodyBytes))
+	if err != nil {
+		s.auditClaims(r, memoryTuningAuditAction, "error")
+		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "bad_request", "读取请求体失败"))
+		return
+	}
+	patch, err := parseMemoryTidyTuningPatch(body)
+	if err != nil {
+		// 非法值/未知键：**盘上一个字节都不动**（解析阶段就退出，写盘在下面）。
+		s.auditClaims(r, memoryTuningAuditAction, "error")
+		writeError(w, apperr.Wrap(apperr.ErrBadRequest, "invalid_payload", "%v", err))
+		return
+	}
+	path, ok := s.memoryTidyTuningPath()
+	if !ok {
+		s.auditClaims(r, memoryTuningAuditAction, "error")
+		writeError(w, apperr.Wrap(apperr.ErrInternal, "tuning_unavailable", "数据目录未接线，面板配置文件落点无法确定"))
+		return
+	}
+	// 落盘（补丁 + 原子写）交给 runtimeconfig 家族：它同时是「盘上那份能不能被
+	// 运行期读走」的**唯一**判定点（读不走的文件拒绝覆盖，见 ErrInvalidMemoryTidy）。
+	if !patch.empty() {
+		if err := s.commitMemoryTidyTuningPatch(path, patch); err != nil {
+			s.auditClaims(r, memoryTuningAuditAction, "error")
+			s.writeTuningWriteFailure(w, err)
+			return
+		}
+	}
+	view, err := s.buildMemoryTidyTuningView(path)
+	if err != nil {
+		// 刚落盘就解不开：这是本端点的编程/磁盘错误，如实回 500，绝不回一个
+		// 「已保存」的假成功。
+		s.auditClaims(r, memoryTuningAuditAction, "error")
+		s.writeTuningCorrupt(w, err)
+		return
+	}
+	hot, hotErr := s.applyMemoryTidyTuningHot(path)
+	view.Hot = hot
+	if hotErr != nil {
+		view.HotError = hotErr.Error()
+	}
+	s.auditClaims(r, memoryTuningAuditAction, "ok")
+	writeJSON(w, http.StatusOK, view)
+}
+
+// commitMemoryTidyTuningPatch 把补丁交给 runtimeconfig 家族原子落盘。值一个都没变
+// 时不落盘（「保存同样的值」不该在盘上留一次无意义的改写）。
+func (s *Server) commitMemoryTidyTuningPatch(path string, patch memoryTidyTuningPatch) error {
+	_, wrote, err := runtimeconfig.PatchMemoryTidyTuning(path, patch.set, patch.clear)
+	if err != nil {
+		return err
+	}
+	log := logger.WithSource(s.log, memoryTuningLogSource)
+	if !wrote {
+		log.Info("memory tidy tuning unchanged (no bytes written)", "path", path, "keys", patch.changed)
+		return nil
+	}
+	log.Info("memory tidy tuning saved", "path", path, "keys", patch.changed)
+	return nil
+}
+
+// buildMemoryTidyTuningView 读盘并组装面板视图（口径 4：响应就是**盘上真值**）。
+func (s *Server) buildMemoryTidyTuningView(path string) (AdminMemoryTidyTuningView, error) {
+	tuning, err := runtimeconfig.LoadMemoryTidyTuning(path)
+	if err != nil {
+		return AdminMemoryTidyTuningView{}, err
+	}
+	present, err := memoryTidyTuningPresent(path)
+	if err != nil {
+		return AdminMemoryTidyTuningView{}, err
+	}
+	return AdminMemoryTidyTuningView{
+		Path:      runtimeconfig.MemoryTidyConfigRelPath,
+		Present:   present,
+		Specs:     memoryTidyTuningSpecs(),
+		Values:    memoryTidyTuningValues(tuning),
+		EnvValues: s.memoryTidyTuningEnvValues(),
+	}, nil
+}
+
+// memoryTidyTuningPresent 报告面板配置文件是否已存在且**有内容**（全空白 = 还没配过，
+// 与 runtimeconfig.LoadMemoryTidyTuning 的口径一致）。
+func memoryTidyTuningPresent(path string) (bool, error) {
+	raw, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return false, nil
+		}
+		return false, fmt.Errorf("读取 %s：%w", path, err)
+	}
+	return len(strings.TrimSpace(string(raw))) > 0, nil
+}
+
+// memoryTidyTuningEnvValues 返回缺位时的**下一档（`.env`）**进程生效值。
+//
+// 只取 `s.cfg`（配置层已消化「进程环境 → `.env` → 声明默认」）：网关**绝不**
+// 直接 fopen `.env`，否则面板看到的是文件原文而不是运行实例在用的数。
+//
+// 三处刻意省略（省略 = 「这一档也没值，继续落到代码默认」，而不是编一个 0）：
+//   - `MEMORY_TIDY_INTERVAL_SEC` ≤ 0：非正数是坏值（运行期会 WARN 并回落），
+//     报出来会让人以为「留空就得到 0 秒」；
+//   - 安静时段两端**都为 0**：0/0 是「未填」，运行期会回落到设计默认窗口，
+//     此时报 0/0 等于把「未填」谎报成一个午夜窗口。
+//
+// 其余四个键（`quietIntervalSec` / `ingestGate` / `autoApply` / `tempTtlSec`）在
+// `.env` 里**结构性没有出处**（`.env` 已冻结，design/13 §2.1），因此不存在第二档，
+// 它们的下一档就是代码默认（specs 里的 fallback 已说明）。
+func (s *Server) memoryTidyTuningEnvValues() map[string]int {
+	out := map[string]int{}
+	if s.cfg == nil {
+		return out
+	}
+	if v := s.cfg.MemoryTidy.IntervalSec; v > 0 {
+		out["intervalSec"] = v
+	}
+	if start, end := s.cfg.MemoryTidy.QuietStartHour, s.cfg.MemoryTidy.QuietEndHour; start != 0 || end != 0 {
+		out["quietStartHour"] = start
+		out["quietEndHour"] = end
+	}
+	return out
+}
+
+// memoryTidyTuningPath 解析面板配置文件的绝对落点（`$DATA_DIR/config/memory-tidy.json`）。
+//
+// 数据目录的来源与图片上传端点同一口径：优先已解析的 `deps.DataDir`，为空时回退
+// `cfg.DataDir`；两者都空（未接线）时报 false，调用方如实回 `tuning_unavailable`，
+// 绝不猜一个目录去写。
+func (s *Server) memoryTidyTuningPath() (string, bool) {
+	dataDir := s.dataDir
+	if dataDir == "" && s.cfg != nil {
+		dataDir = s.cfg.DataDir
+	}
+	if dataDir == "" {
+		return "", false
+	}
+	return runtimeconfig.DefaultMemoryTidyPath(dataDir), true
+}
+
+// applyMemoryTidyTuningHot 把刚落盘的面板值当场叠到运行期（口径 3）。
+//
+// 返回 (hot, err)：hot=false 表示这次**没能在运行期生效**（能力未接线，或叠的过程
+// 报错），err 说明原因。两者只用于如实回话，**不影响**「已经落盘」这个事实 ——
+// 值不会因为热生效失败而丢。
+//
+// 能力用类型断言探测（可选能力，与 `plugin` 侧的可选接口同一手法）：网关**不为此**
+// 新增 Deps 字段/Server 字段 —— 整理服务本来就在 `s.memoryTidy` 里，审查器挂在
+// `deps.Memories` 的实现上。这样「有没有热生效」是一件可观测的事实，而不是一句
+// 靠不住的断言。
+func (s *Server) applyMemoryTidyTuningHot(path string) (hot bool, hotErr error) {
+	tuning, err := runtimeconfig.LoadMemoryTidyTuning(path)
+	if err != nil {
+		return false, fmt.Errorf("重读面板配置失败：%v", err)
+	}
+	applied := false
+	if applier, ok := s.memoryTidy.(MemoryTidyTuningApplier); ok {
+		base := memory.TidyConfig{}
+		if s.cfg != nil {
+			base = memory.TidyConfigFromConfig(s.cfg.MemoryTidy)
+		}
+		if err := applier.ApplyPanelTuning(base, tuning); err != nil {
+			return false, fmt.Errorf("整理自动档未能热生效：%v", err)
+		}
+		applied = true
+	}
+	if applier, ok := s.memories.(MemoryIngestTuningApplier); ok {
+		if err := applier.ApplyIngestPanelTuning(tuning); err != nil {
+			return false, fmt.Errorf("入库审查未能热生效：%v", err)
+		}
+		applied = true
+	}
+	if !applied {
+		return false, fmt.Errorf("运行期没有接线可热生效的实现（deps.MemoryTidy / deps.Memories）；新值已落盘，重启后端后生效")
+	}
+	return true, nil
+}
+
+// writeTuningCorrupt 把「盘上那份读不走」映射成 409 tuning_corrupt，并把**运行期的
+// 实际后果**写进文案：此刻它正整体回落 `.env`/代码默认（见 runtimeconfig 的读取口径），
+// 而面板**拒绝**在这个文件上覆盖 —— 坏文件请人工修复或删除。
+func (s *Server) writeTuningCorrupt(w http.ResponseWriter, cause error) {
+	logger.WithSource(s.log, memoryTuningLogSource).Warn(
+		"memory tidy tuning file unusable", "path", runtimeconfig.MemoryTidyConfigRelPath, "error", cause)
+	writeError(w, apperr.Wrap(apperr.ErrConflict, "tuning_corrupt",
+		"面板配置文件 %s 解不开（运行期正回落 .env / 代码默认）；面板拒绝在一个读不走的文件上覆盖，请人工修复或删除它：%v",
+		runtimeconfig.MemoryTidyConfigRelPath, cause))
+}
+
+// writeTuningWriteFailure 把落盘失败如实分类：**盘上那份读不走**（ErrInvalidMemoryTidy）
+// 是 409（拒绝覆盖，不是故障），其余（IO/权限/重读不一致）是 500。两种都带出处，
+// 绝不回一个「已保存」的假成功。
+func (s *Server) writeTuningWriteFailure(w http.ResponseWriter, cause error) {
+	if errors.Is(cause, runtimeconfig.ErrInvalidMemoryTidy) {
+		s.writeTuningCorrupt(w, cause)
+		return
+	}
+	logger.WithSource(s.log, memoryTuningLogSource).Error(
+		"memory tidy tuning write failed", "path", runtimeconfig.MemoryTidyConfigRelPath, "error", cause)
+	writeError(w, apperr.Wrap(apperr.ErrInternal, "tuning_write_failed",
+		"面板配置文件 %s 落盘失败（盘上内容未改动）：%v", runtimeconfig.MemoryTidyConfigRelPath, cause))
+}

internal/services/gateway/admin_memory_tuning_file.go

@@ -0,0 +1,275 @@
+package gateway
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config/runtimeconfig"
+)
+
+// 本文件是记忆整理「面板调优」的**键规格与三态校验**层（文件读写与原子落盘在
+// `internal/config/runtimeconfig` 家族里，见 memorytidy_save.go —— 落点是那一族的
+// 职责，网关只负责 API 契约这一侧的取值规则）。
+//
+// 它管的是 `$DATA_DIR/config/memory-tidy.json` 里主人能调的 7 个旋钮（design/13 §2.1：
+// 调优/门槛/上限/开关类参数走 `$DATA_DIR/config/**` + 代码默认值，不进 `.env`）。
+//
+// 三态与清除哨兵（与契约里 `plugin.saveProvider` 同族语义）：
+//   - 键**没出现** ⇒ 不动它（`changed` 里也不出现）；
+//   - 值为 `null` ⇒ 从面板文件里**删掉**这个键（回到下一档兜底：`.env` → 代码默认）；
+//   - 值合法 ⇒ 采用；
+//   - 值非法（类型不对 / 超界 / 不是 JSON 对象 / 有不认识的键）⇒ 一律**在解析阶段**
+//     被拒（调用方回 400 且盘上一个字节都不动），**绝不静默忽略** —— 静默忽略会让
+//     主人以为改了而实际没改（把 `quietEndHour` 拼成 `quietEnd` 就正是这种形态）。
+
+const (
+	// tuningKindInt / tuningKindBool 是本切片管得到的两种键型。
+	tuningKindInt  = "int"
+	tuningKindBool = "bool"
+	// tuningUnitSec / tuningUnitHour 是 int 键的单位（面板据此写「秒 / 点」）。
+	tuningUnitSec  = "sec"
+	tuningUnitHour = "hour"
+	// tuningSecMin 是三个秒键的下界：**必须为正**（≤0 的周期不是「没配」，而是一个
+	// 会让整理退化成空转的值；运行期口径同样把非正数当坏值回落，见
+	// memory.ApplyTidyScheduleTuning 与 runtimeconfig.MemoryTidyTuning 的注释）。
+	tuningSecMin = 1
+	// tuningHourMin / tuningHourMax 是钟点键的取值域（本地钟点 0..23）。
+	tuningHourMin = 0
+	tuningHourMax = 23
+
+	// tuningCodeDefault 是「缺位时落到代码默认」这一类兜底来源的标识（面板文案用）。
+	// 它**只说来源、不带数值**：数值的唯一真源在 memory 侧（normalizeTidyConfig /
+	// normalizeReviewConfig），网关不另抄一份默认值 —— 抄一份就是第二个真源。
+	tuningCodeDefault = "code-default"
+)
+
+// memoryTidyTuningSpec 是一个可写键的**取值规则**（唯一真源）。
+//
+// 它既驱动写侧校验，也随 GET 下发给面板（`specs`）：面板据此渲染表单与就地报错，
+// 因此不会出现「面板允许、后端 400」的两套规则（与 /admin/llm 下发
+// reasoningKinds / personaProviderOptions 同一手法）。
+type memoryTidyTuningSpec struct {
+	Key string `json:"key"`
+	// Kind ∈ int | bool；面板据此选输入控件类型。
+	Kind string `json:"kind"`
+	// Unit ∈ sec | hour（仅 int 键）：面板据此写单位，不自己猜。
+	Unit string `json:"unit,omitempty"`
+	// Min / Max 是闭区间上下界（缺省 = 该端无约束）。
+	Min *int `json:"min,omitempty"`
+	Max *int `json:"max,omitempty"`
+	// Fallback 报告这个键**缺位（或面板 `null` 清除）时**生效值从哪来：
+	//   - `env:MEMORY_TIDY_*` ⇒ 回落 `.env` 的同名键（进程生效值见
+	//     GET /admin/config-facts 的同名事实行）；
+	//   - `panel:<key>`      ⇒ 回落面板文件里另一个键；
+	//   - `code-default`     ⇒ 回落代码默认。
+	// 它只给**来源**，不给数值：数值的真源在各自那一档（见 tuningCodeDefault）。
+	Fallback string `json:"fallback"`
+}
+
+// memoryTidyTuningSpecs 是面板可写 7 键的**唯一清单**（顺序 = 面板显示顺序）。
+//
+// 为什么是这 7 个：主人要能调**整理频率**（白天短、静默期长）与**入库审查的两个
+// 开关/时长**，而 `.env` 已冻结（design/13 §2.1）⇒ 这些旋钮只能落面板配置文件，
+// 面板必须能**写**它。
+//
+// 刻意**不在**这里的两类键：
+//   - `t1Judge` / `t1PerWindow` / `t1WindowSec` / `autoApplyPerRound`：同文件的其它
+//     旋钮，本切片的面板卡片不呈现，写端点也不接受它们（未知键一律 400，免得主人
+//     以为改了、其实没动）。它们仍**原样保留**在文件里（补丁语义）。
+func memoryTidyTuningSpecs() []memoryTidyTuningSpec {
+	secMin := tuningSecMin
+	hourMin := tuningHourMin
+	hourMax := tuningHourMax
+	return []memoryTidyTuningSpec{
+		{
+			Key: "intervalSec", Kind: tuningKindInt, Unit: tuningUnitSec, Min: &secMin,
+			Fallback: "env:MEMORY_TIDY_INTERVAL_SEC",
+		},
+		{
+			Key: "quietIntervalSec", Kind: tuningKindInt, Unit: tuningUnitSec, Min: &secMin,
+			Fallback: "panel:intervalSec",
+		},
+		{
+			Key: "quietStartHour", Kind: tuningKindInt, Unit: tuningUnitHour,
+			Min: &hourMin, Max: &hourMax, Fallback: "env:MEMORY_TIDY_QUIET_START_HOUR",
+		},
+		{
+			Key: "quietEndHour", Kind: tuningKindInt, Unit: tuningUnitHour,
+			Min: &hourMin, Max: &hourMax, Fallback: "env:MEMORY_TIDY_QUIET_END_HOUR",
+		},
+		{Key: "ingestGate", Kind: tuningKindBool, Fallback: tuningCodeDefault},
+		{Key: "autoApply", Kind: tuningKindBool, Fallback: tuningCodeDefault},
+		{Key: "tempTtlSec", Kind: tuningKindInt, Unit: tuningUnitSec, Min: &secMin, Fallback: tuningCodeDefault},
+	}
+}
+
+// memoryTidyTuningManagedKeys 返回可写键的键名（specs 顺序），供错误文案与审计用。
+func memoryTidyTuningManagedKeys() []string {
+	specs := memoryTidyTuningSpecs()
+	out := make([]string, 0, len(specs))
+	for _, s := range specs {
+		out = append(out, s.Key)
+	}
+	return out
+}
+
+// memoryTidyTuningPatch 是一次写请求**已校验**的补丁。
+//
+// set / clear 是交给 runtimeconfig.PatchMemoryTidyTuning 的动作（clear = 删掉该键
+// ⇒ 回到下一档兜底）；changed 是本次真正出现的键（specs 顺序，含被清除的），空表示
+// 一个键都没提交（此时**不写盘**，文件字节保持不变）。
+type memoryTidyTuningPatch struct {
+	set     map[string]json.RawMessage
+	clear   []string
+	changed []string
+}
+
+// empty 报告这次请求没有提交任何受管的键。
+func (p memoryTidyTuningPatch) empty() bool { return len(p.changed) == 0 }
+
+// parseMemoryTidyTuningPatch 把请求体解析成一次已校验的补丁（三态的唯一实现点）。
+//
+// 未知键也归入「非法」：本端点**不静默忽略**任何提交上来的键 —— 静默忽略会让主人
+// 以为改了而实际没改。
+func parseMemoryTidyTuningPatch(body []byte) (memoryTidyTuningPatch, error) {
+	var raw map[string]json.RawMessage
+	if err := json.Unmarshal(body, &raw); err != nil {
+		return memoryTidyTuningPatch{}, fmt.Errorf("请求体必须是一个 JSON 对象：%w", err)
+	}
+	if raw == nil {
+		// JSON 的 `null` 解到 map 上是 nil 且**不报错**：它不是一个「提交了 0 个键」
+		// 的请求，而是一个形状不对的请求，如实拒掉（空补丁请用 `{}`）。
+		return memoryTidyTuningPatch{}, errors.New("请求体必须是一个 JSON 对象（收到 null）")
+	}
+	specs := memoryTidyTuningSpecs()
+	known := make(map[string]memoryTidyTuningSpec, len(specs))
+	for _, s := range specs {
+		known[s.Key] = s
+	}
+	if err := rejectUnknownTuningKeys(raw, known); err != nil {
+		return memoryTidyTuningPatch{}, err
+	}
+	patch := memoryTidyTuningPatch{set: map[string]json.RawMessage{}}
+	for _, s := range specs {
+		value, ok := raw[s.Key]
+		if !ok {
+			continue
+		}
+		patch.changed = append(patch.changed, s.Key)
+		if isJSONNull(value) {
+			patch.clear = append(patch.clear, s.Key)
+			continue
+		}
+		if err := validateTuningValue(s, value); err != nil {
+			return memoryTidyTuningPatch{}, err
+		}
+		patch.set[s.Key] = value
+	}
+	return patch, nil
+}
+
+// rejectUnknownTuningKeys 拒绝请求体里任何不受管的键（含拼错的键）。
+func rejectUnknownTuningKeys(raw map[string]json.RawMessage, known map[string]memoryTidyTuningSpec) error {
+	unknown := make([]string, 0)
+	for k := range raw {
+		if _, ok := known[k]; !ok {
+			unknown = append(unknown, k)
+		}
+	}
+	if len(unknown) == 0 {
+		return nil
+	}
+	sort.Strings(unknown)
+	return fmt.Errorf("不认识的键：%s（本端点只写 %s；同文件其它旋钮请人工编辑）",
+		strings.Join(unknown, "、"), strings.Join(memoryTidyTuningManagedKeys(), "、"))
+}
+
+// validateTuningValue 校验一个键的值（类型 + 取值域）。错误文案直接回给面板显示，
+// 因此带上**收到的原始值**，让主人一眼看出该改什么。
+func validateTuningValue(spec memoryTidyTuningSpec, raw json.RawMessage) error {
+	switch spec.Kind {
+	case tuningKindBool:
+		var b bool
+		if err := json.Unmarshal(raw, &b); err != nil {
+			return fmt.Errorf("%s 必须是 true 或 false（收到 %s）", spec.Key, clipJSON(raw))
+		}
+		return nil
+	case tuningKindInt:
+		var n int
+		if err := json.Unmarshal(raw, &n); err != nil {
+			return fmt.Errorf("%s 必须是整数（收到 %s）", spec.Key, clipJSON(raw))
+		}
+		if spec.Min != nil && n < *spec.Min {
+			return fmt.Errorf("%s 必须 ≥ %d（%s），收到 %d", spec.Key, *spec.Min, tuningUnitLabel(spec), n)
+		}
+		if spec.Max != nil && n > *spec.Max {
+			return fmt.Errorf("%s 必须 ≤ %d（%s），收到 %d", spec.Key, *spec.Max, tuningUnitLabel(spec), n)
+		}
+		return nil
+	default:
+		// 规格表自己写错了型别（编程错误，不是客户端错）：如实报出来，不猜一种校验。
+		return fmt.Errorf("%s 的键规格未定义（kind=%q）", spec.Key, spec.Kind)
+	}
+}
+
+// tuningUnitLabel 返回单位的中文说明（错误文案用）。
+func tuningUnitLabel(spec memoryTidyTuningSpec) string {
+	switch spec.Unit {
+	case tuningUnitSec:
+		return "秒"
+	case tuningUnitHour:
+		return "本地钟点 0-23"
+	default:
+		return "整数"
+	}
+}
+
+// clipJSON 把收到的原始 JSON 片段截断成可安全回显的短串（错值可能很长）。
+func clipJSON(raw json.RawMessage) string {
+	const maxClip = 40
+	s := strings.TrimSpace(string(raw))
+	if len(s) <= maxClip {
+		return s
+	}
+	return s[:maxClip] + "…"
+}
+
+// isJSONNull 报告这段原始值是不是 JSON 的 `null`（清除哨兵）。
+func isJSONNull(raw json.RawMessage) bool {
+	return strings.TrimSpace(string(raw)) == "null"
+}
+
+// memoryTidyTuningValues 把盘上的调优结构投影成面板要的 7 键值表：**键缺位 ⇒ 整个
+// 键不出现**（面板据此渲染「未设置、跟随兜底」），而不是回一个编出来的 0 ——
+// 「0 秒」与「没配」在面板上必须看得出区别。
+//
+// 它刻意**不**回显同文件的其它键（t1Judge 等）：那些不在本卡片的编辑范围，混进来
+// 只会让人以为这张卡能改它们。
+func memoryTidyTuningValues(t runtimeconfig.MemoryTidyTuning) map[string]any {
+	out := map[string]any{}
+	if t.IntervalSec != nil {
+		out["intervalSec"] = *t.IntervalSec
+	}
+	if t.QuietIntervalSec != nil {
+		out["quietIntervalSec"] = *t.QuietIntervalSec
+	}
+	if t.QuietStartHour != nil {
+		out["quietStartHour"] = *t.QuietStartHour
+	}
+	if t.QuietEndHour != nil {
+		out["quietEndHour"] = *t.QuietEndHour
+	}
+	if t.IngestGate != nil {
+		out["ingestGate"] = *t.IngestGate
+	}
+	if t.AutoApply != nil {
+		out["autoApply"] = *t.AutoApply
+	}
+	if t.TempTtlSec != nil {
+		out["tempTtlSec"] = *t.TempTtlSec
+	}
+	return out
+}

internal/services/gateway/admin_memory_tuning_test.go

@@ -0,0 +1,524 @@
+package gateway
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/auth"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/config/runtimeconfig"
+	"git.yeij.top/AskaEth/Cyrene_v2/internal/runtime/memory"
+)
+
+// 本文件锁定记忆整理「面板调优」读写端点（`GET|PUT /api/v1/admin/memories/tidy/tuning`）
+// 的判据：
+//  ① 读侧如实回显**盘上值**（键缺位 ⇒ 该键不出现）+ 取值规则 specs + `.env` 兜底值，
+//     且不回显同文件里不受管的键；
+//  ② 写侧**三态**：键缺位 ⇒ 逐字节不动（含「不重写文件」）；合法值 ⇒ 采用且保留
+//     同文件其它键；非法值 ⇒ `400 invalid_payload` 且**盘上一个字节都不动**；
+//  ③ 盘上文件解不开 ⇒ 读/写都 `409 tuning_corrupt` 且绝不覆盖；
+//  ④ `null` 是清除哨兵（删键 ⇒ 回到下一档兜底）；
+//  ⑤ RBAC 走 writeAuth（owner|admin）、写落审计 `memory.tidy.tuning`；
+//  ⑥ 热生效**如实**：接线了 ⇒ hot=true 且真把值交给运行期；没接线/失败 ⇒ hot=false +
+//     hotError，绝不把「落盘了」说成「生效了」。
+
+// tuneEnvT 是一个注入了数据目录（= 面板配置文件落点所在）的网关测试环境。
+type tuneEnvT struct {
+	srv *Server
+	ts  *httptest.Server
+	dir string
+	jwt *auth.JWTService
+}
+
+// newTuneEnv 构造环境。`cfg.MemoryTidy` 被显式填上，用来验证读侧下发的
+// 「缺位时 `.env` 那一档」确实取自进程生效配置（而不是网关自己编的数）。
+func newTuneEnv(t *testing.T, deps Deps) *tuneEnvT {
+	t.Helper()
+	dir := t.TempDir()
+	cfg := cfgDefault()
+	cfg.MemoryTidy = config.MemoryTidyConfig{IntervalSec: 86400, QuietStartHour: 23, QuietEndHour: 7}
+	deps.DataDir = dir
+	srv, ts, jwt := buildEnv(t, cfg, deps)
+	return &tuneEnvT{srv: srv, ts: ts, dir: dir, jwt: jwt}
+}
+
+func (e *tuneEnvT) url() string {
+	return e.ts.URL + "/api/v1/admin/memories/tidy/tuning"
+}
+
+func (e *tuneEnvT) path() string {
+	return filepath.Join(e.dir, filepath.FromSlash(runtimeconfig.MemoryTidyConfigRelPath))
+}
+
+func (e *tuneEnvT) token(t *testing.T, role auth.Role) string {
+	t.Helper()
+	return signAny(t, e.jwt, "acct-"+string(role), role)
+}
+
+// seed 写入一份面板配置并返回写后的字节（后续逐字节比对用）。
+func (e *tuneEnvT) seed(t *testing.T, body string) []byte {
+	t.Helper()
+	if err := os.MkdirAll(filepath.Dir(e.path()), 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	if err := os.WriteFile(e.path(), []byte(body), 0o600); err != nil {
+		t.Fatalf("seed: %v", err)
+	}
+	return e.bytes(t)
+}
+
+// bytes 读回盘上的原始字节：「非法值不落盘」的证据就是它与之前相等。
+func (e *tuneEnvT) bytes(t *testing.T) []byte {
+	t.Helper()
+	raw, err := os.ReadFile(e.path())
+	if err != nil {
+		t.Fatalf("read tuning file: %v", err)
+	}
+	return raw
+}
+
+func (e *tuneEnvT) put(t *testing.T, token, raw string) (*http.Response, []byte) {
+	t.Helper()
+	return doRaw(t, http.MethodPut, e.url(), raw, token)
+}
+
+func (e *tuneEnvT) get(t *testing.T, token string) (*http.Response, []byte) {
+	t.Helper()
+	return doReq(t, http.MethodGet, e.url(), nil, token)
+}
+
+// view 解一次成功响应的 data。
+func (e *tuneEnvT) view(t *testing.T, body []byte) AdminMemoryTidyTuningView {
+	t.Helper()
+	var view AdminMemoryTidyTuningView
+	if err := json.Unmarshal(decodeBody(t, body)["data"], &view); err != nil {
+		t.Fatalf("decode view: %v (body=%s)", err, body)
+	}
+	return view
+}
+
+// assertErrorCode 断言响应是错误信封且 code 匹配。
+func assertErrorCode(t *testing.T, body []byte, want string) {
+	t.Helper()
+	var eobj struct {
+		Code string `json:"code"`
+	}
+	if err := json.Unmarshal(decodeBody(t, body)["error"], &eobj); err != nil {
+		t.Fatalf("decode error: %v (body=%s)", err, body)
+	}
+	if eobj.Code != want {
+		t.Fatalf("error code = %q, want %q (body=%s)", eobj.Code, want, body)
+	}
+}
+
+// diskDoc 解出盘上的文档（键 → 原样 JSON 值）。
+func (e *tuneEnvT) diskDoc(t *testing.T) map[string]json.RawMessage {
+	t.Helper()
+	doc := map[string]json.RawMessage{}
+	if err := json.Unmarshal(e.bytes(t), &doc); err != nil {
+		t.Fatalf("decode disk: %v", err)
+	}
+	return doc
+}
+
+// TestAdminMemoryTidyTuningRead_EchoesDiskValues 读侧：回显盘上 7 键（缺位不下发）、
+// 下发取值规则与 `.env` 兜底值，且**不回显**同文件里不受管的键。
+func TestAdminMemoryTidyTuningRead_EchoesDiskValues(t *testing.T) {
+	t.Parallel()
+	env := newTuneEnv(t, Deps{})
+	env.seed(t, `{
+  "intervalSec": 3600,
+  "quietStartHour": 23,
+  "quietEndHour": 7,
+  "ingestGate": false,
+  "t1PerWindow": 120
+}`)
+	resp, body := env.get(t, env.token(t, auth.RoleOwner))
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("read status = %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	view := env.view(t, body)
+	if view.Path != runtimeconfig.MemoryTidyConfigRelPath || !view.Present {
+		t.Fatalf("view path/present = %q/%v", view.Path, view.Present)
+	}
+	if got := view.Values["intervalSec"]; got != float64(3600) {
+		t.Fatalf("values.intervalSec = %#v, want 3600", got)
+	}
+	if got := view.Values["ingestGate"]; got != false {
+		t.Fatalf("values.ingestGate = %#v, want false", got)
+	}
+	// 键缺位 ⇒ 不出现（「没配」与「配成 0」必须分得开）。
+	for _, absent := range []string{"quietIntervalSec", "autoApply", "tempTtlSec"} {
+		if _, ok := view.Values[absent]; ok {
+			t.Fatalf("values 不该出现 %s（盘上没这个键）：%#v", absent, view.Values)
+		}
+	}
+	// 不受管的键（t1PerWindow）不进 values：这张卡改不了它，混进来会误导。
+	if _, ok := view.Values["t1PerWindow"]; ok {
+		t.Fatalf("values 不该出现不受管的 t1PerWindow：%#v", view.Values)
+	}
+	if len(view.Specs) != len(memoryTidyTuningManagedKeys()) {
+		t.Fatalf("specs = %d 条, want %d", len(view.Specs), len(memoryTidyTuningManagedKeys()))
+	}
+	if view.EnvValues["intervalSec"] != 86400 || view.EnvValues["quietStartHour"] != 23 {
+		t.Fatalf("envValues = %#v, want intervalSec=86400 / quietStartHour=23", view.EnvValues)
+	}
+	if view.Hot {
+		t.Fatal("只读响应里 hot 必须为 false（读不改变任何东西）")
+	}
+}
+
+// TestAdminMemoryTidyTuningRead_MissingFileIsNotAnError 文件还没播种时：正常回 200、
+// present=false、values 为空 —— 「还没配过」不是错误（与 runtimeconfig 的读取口径一致）。
+func TestAdminMemoryTidyTuningRead_MissingFileIsNotAnError(t *testing.T) {
+	t.Parallel()
+	env := newTuneEnv(t, Deps{})
+	resp, body := env.get(t, env.token(t, auth.RoleOwner))
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	view := env.view(t, body)
+	if view.Present || len(view.Values) != 0 {
+		t.Fatalf("view = %+v, want present=false / 无值", view)
+	}
+}
+
+// TestAdminMemoryTidyTuningRead_ViewerForbidden RBAC：viewer 403、匿名 401。
+func TestAdminMemoryTidyTuningRead_ViewerForbidden(t *testing.T) {
+	t.Parallel()
+	env := newTuneEnv(t, Deps{})
+	env.seed(t, `{"intervalSec": 3600}`)
+	resp, body := env.get(t, env.token(t, auth.RoleViewer))
+	if resp.StatusCode != http.StatusForbidden {
+		t.Fatalf("viewer read status = %d, want 403 (body=%s)", resp.StatusCode, body)
+	}
+	resp, _ = env.get(t, "")
+	if resp.StatusCode != http.StatusUnauthorized {
+		t.Fatalf("anonymous read status = %d, want 401", resp.StatusCode)
+	}
+}
+
+// TestAdminMemoryTidyTuningWrite_AdoptsValidValuesAndKeepsOtherKeys 写侧「合法值 ⇒ 采用」：
+// 7 键都能落盘，同文件里不受管的键**原样保留**（一次面板保存绝不抹掉别的旋钮）。
+func TestAdminMemoryTidyTuningWrite_AdoptsValidValuesAndKeepsOtherKeys(t *testing.T) {
+	t.Parallel()
+	env := newTuneEnv(t, Deps{})
+	env.seed(t, `{"t1Judge": false, "t1PerWindow": 120}`)
+	// 用 admin 角色也走同一道门（writeAuth = owner|admin）。
+	resp, body := env.put(t, env.token(t, auth.RoleAdmin), `{
+  "intervalSec": 10800,
+  "quietIntervalSec": 3600,
+  "quietStartHour": 23,
+  "quietEndHour": 7,
+  "ingestGate": true,
+  "autoApply": true,
+  "tempTtlSec": 604800
+}`)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("write status = %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	view := env.view(t, body)
+	for key, want := range map[string]any{
+		"intervalSec": float64(10800), "quietIntervalSec": float64(3600),
+		"quietStartHour": float64(23), "quietEndHour": float64(7),
+		"ingestGate": true, "autoApply": true, "tempTtlSec": float64(604800),
+	} {
+		if got := view.Values[key]; got != want {
+			t.Fatalf("回显 values[%s] = %#v, want %#v", key, got, want)
+		}
+	}
+	doc := env.diskDoc(t)
+	if string(doc["intervalSec"]) != "10800" || string(doc["t1PerWindow"]) != "120" {
+		t.Fatalf("disk = %s", string(env.bytes(t)))
+	}
+	if _, ok := doc["t1Judge"]; !ok {
+		t.Fatalf("不受管的 t1Judge 被抹掉了：%s", string(env.bytes(t)))
+	}
+	// 未接运行期 ⇒ 如实说「已落盘、重启后生效」。
+	if view.Hot || view.HotError == "" {
+		t.Fatalf("未接热生效时 hot/hotError = %v/%q, want false/非空", view.Hot, view.HotError)
+	}
+}
+
+// TestAdminMemoryTidyTuningWrite_AbsentKeyLeavesBytesUntouched 三态之一：键**缺位** ⇒
+// 不改动。空补丁连文件都不重写（mtime 都不动）；只提交一个键时另一个键逐字节不动。
+func TestAdminMemoryTidyTuningWrite_AbsentKeyLeavesBytesUntouched(t *testing.T) {
+	t.Parallel()
+	env := newTuneEnv(t, Deps{})
+	before := env.seed(t, `{"intervalSec": 86400, "quietStartHour": 23}`)
+	past := time.Now().Add(-time.Hour)
+	if err := os.Chtimes(env.path(), past, past); err != nil {
+		t.Fatalf("chtimes: %v", err)
+	}
+	tok := env.token(t, auth.RoleOwner)
+	resp, body := env.put(t, tok, `{}`)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("empty patch status = %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	if after := env.bytes(t); string(after) != string(before) {
+		t.Fatalf("空补丁改动了盘上内容：\nbefore=%s\nafter=%s", before, after)
+	}
+	info, err := os.Stat(env.path())
+	if err != nil {
+		t.Fatalf("stat: %v", err)
+	}
+	if !info.ModTime().Equal(past) {
+		t.Fatalf("空补丁重写了文件（mtime %v ⇒ %v）", past, info.ModTime())
+	}
+	if resp, body := env.put(t, tok, `{"quietStartHour": 22}`); resp.StatusCode != http.StatusOK {
+		t.Fatalf("partial patch status = %d (body=%s)", resp.StatusCode, body)
+	}
+	doc := env.diskDoc(t)
+	if string(doc["intervalSec"]) != "86400" || string(doc["quietStartHour"]) != "22" {
+		t.Fatalf("partial patch 结果 = %s", string(env.bytes(t)))
+	}
+}
+
+// TestAdminMemoryTidyTuningWrite_InvalidValueNeverTouchesDisk 三态之三（本文件的核心
+// 证据）：任何非法输入都 `400 invalid_payload`，且**盘上一个字节都不动**。
+func TestAdminMemoryTidyTuningWrite_InvalidValueNeverTouchesDisk(t *testing.T) {
+	t.Parallel()
+	cases := []struct{ name, body string }{
+		{"字符串冒充整数", `{"intervalSec": "3600"}`},
+		{"小数不是整数", `{"tempTtlSec": 1.5}`},
+		{"周期为 0（会让整理空转）", `{"intervalSec": 0}`},
+		{"周期为负", `{"quietIntervalSec": -60}`},
+		{"钟点越上界", `{"quietStartHour": 24}`},
+		{"钟点越下界", `{"quietEndHour": -1}`},
+		{"钟点不是数字", `{"quietEndHour": "07"}`},
+		{"开关不是布尔", `{"ingestGate": "yes"}`},
+		{"未知键（拼错的 quietEnd）", `{"quietEnd": 7}`},
+		{"请求体不是对象", `[1, 2]`},
+		{"请求体是 null", `null`},
+		{"请求体是空串", ``},
+		{"合法键与非法键同时提交", `{"intervalSec": 3600, "autoApply": "on"}`},
+	}
+	for _, tc := range cases {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			env := newTuneEnv(t, Deps{})
+			before := env.seed(t, `{
+  "intervalSec": 86400,
+  "quietStartHour": 23,
+  "quietEndHour": 7,
+  "t1Judge": false
+}`)
+			resp, body := env.put(t, env.token(t, auth.RoleOwner), tc.body)
+			if resp.StatusCode != http.StatusBadRequest {
+				t.Fatalf("status = %d, want 400 (body=%s)", resp.StatusCode, body)
+			}
+			assertErrorCode(t, body, "invalid_payload")
+			if after := env.bytes(t); string(after) != string(before) {
+				t.Fatalf("非法输入改动了盘上内容：\nbefore=%s\nafter=%s", before, after)
+			}
+		})
+	}
+	// 盘上**没有**文件时，非法输入也不得创建它（「先落盘再校验」同样是落盘）。
+	t.Run("文件不存在时也不创建", func(t *testing.T) {
+		env := newTuneEnv(t, Deps{})
+		resp, body := env.put(t, env.token(t, auth.RoleOwner), `{"intervalSec": 0}`)
+		if resp.StatusCode != http.StatusBadRequest {
+			t.Fatalf("status = %d, want 400 (body=%s)", resp.StatusCode, body)
+		}
+		if _, err := os.Stat(env.path()); !os.IsNotExist(err) {
+			t.Fatalf("非法输入创建了文件：err=%v", err)
+		}
+	})
+}
+
+// TestAdminMemoryTidyTuningWrite_NullClearsKey 清除哨兵：`null` 删掉该键（回到下一档
+// 兜底），同文件其它键不受影响。
+func TestAdminMemoryTidyTuningWrite_NullClearsKey(t *testing.T) {
+	t.Parallel()
+	env := newTuneEnv(t, Deps{})
+	env.seed(t, `{"intervalSec": 3600, "quietIntervalSec": 7200, "t1Judge": false}`)
+	resp, body := env.put(t, env.token(t, auth.RoleOwner), `{"intervalSec": null}`)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("clear status = %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	view := env.view(t, body)
+	if _, ok := view.Values["intervalSec"]; ok {
+		t.Fatalf("清除后不该再回显 intervalSec：%#v", view.Values)
+	}
+	if got := view.Values["quietIntervalSec"]; got != float64(7200) {
+		t.Fatalf("清除一个键影响了别的键：%#v", view.Values)
+	}
+	doc := env.diskDoc(t)
+	if _, ok := doc["intervalSec"]; ok {
+		t.Fatalf("盘上仍有 intervalSec：%s", string(env.bytes(t)))
+	}
+	if _, ok := doc["t1Judge"]; !ok {
+		t.Fatalf("清除一个键抹掉了别的键：%s", string(env.bytes(t)))
+	}
+}
+
+// TestAdminMemoryTidyTuningWrite_RefusesCorruptFile 盘上那份运行期读不走时，**读与写
+// 都**拒绝（`409 tuning_corrupt`）且绝不覆盖 —— 否则面板会说「已保存」而运行期仍在
+// 整体回落 `.env` 并记 WARN。
+func TestAdminMemoryTidyTuningWrite_RefusesCorruptFile(t *testing.T) {
+	t.Parallel()
+	for _, tc := range []struct{ name, body string }{
+		{"类型写错", `{"intervalSec": "3600"}`},
+		{"根本不是 JSON", `not json at all`},
+		{"顶层不是对象", `[1, 2, 3]`},
+	} {
+		tc := tc
+		t.Run(tc.name, func(t *testing.T) {
+			env := newTuneEnv(t, Deps{})
+			before := env.seed(t, tc.body)
+			tok := env.token(t, auth.RoleOwner)
+			resp, body := env.put(t, tok, `{"intervalSec": 3600}`)
+			if resp.StatusCode != http.StatusConflict {
+				t.Fatalf("write status = %d, want 409 (body=%s)", resp.StatusCode, body)
+			}
+			assertErrorCode(t, body, "tuning_corrupt")
+			if string(env.bytes(t)) != string(before) {
+				t.Fatalf("坏文件被覆盖了：%s", string(env.bytes(t)))
+			}
+			// 读侧同样如实报坏，而不是回一份空配置假装「没配过」。
+			rresp, rbody := env.get(t, tok)
+			if rresp.StatusCode != http.StatusConflict {
+				t.Fatalf("read status = %d, want 409 (body=%s)", rresp.StatusCode, rbody)
+			}
+			assertErrorCode(t, rbody, "tuning_corrupt")
+		})
+	}
+}
+
+// TestAdminMemoryTidyTuningWrite_SameValueDoesNotRewrite 「保存同样的值」不该在盘上留
+// 一次无意义的改写（内容逐字节相同 ⇒ 不落盘、mtime 不动）。
+func TestAdminMemoryTidyTuningWrite_SameValueDoesNotRewrite(t *testing.T) {
+	t.Parallel()
+	env := newTuneEnv(t, Deps{})
+	env.seed(t, `{"intervalSec": 3600}`)
+	past := time.Now().Add(-time.Hour)
+	if err := os.Chtimes(env.path(), past, past); err != nil {
+		t.Fatalf("chtimes: %v", err)
+	}
+	resp, body := env.put(t, env.token(t, auth.RoleOwner), `{"intervalSec": 3600}`)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	info, err := os.Stat(env.path())
+	if err != nil {
+		t.Fatalf("stat: %v", err)
+	}
+	if !info.ModTime().Equal(past) {
+		t.Fatalf("同值保存重写了文件（mtime %v ⇒ %v）", past, info.ModTime())
+	}
+	if string(env.bytes(t)) != `{"intervalSec": 3600}` {
+		t.Fatalf("盘上内容变了：%s", string(env.bytes(t)))
+	}
+}
+
+// fakeTuningTidy 既是整理服务的只读出口，也是「可热生效」的实现（记录收到的值）。
+type fakeTuningTidy struct {
+	fakeTidyDryRunner
+	gotBase   *memory.TidyConfig
+	gotTuning *runtimeconfig.MemoryTidyTuning
+	err       error
+}
+
+func (f *fakeTuningTidy) ApplyPanelTuning(base memory.TidyConfig, panel runtimeconfig.MemoryTidyTuning) error {
+	f.gotBase = &base
+	f.gotTuning = &panel
+	return f.err
+}
+
+// fakeTuningMemories 同时实现 MemoryStore 与「入库侧可热生效」。
+type fakeTuningMemories struct {
+	got *runtimeconfig.MemoryTidyTuning
+	err error
+}
+
+func (f *fakeTuningMemories) List(context.Context) ([]memory.MemoryItem, error) {
+	return []memory.MemoryItem{}, nil
+}
+
+func (f *fakeTuningMemories) ApplyIngestPanelTuning(panel runtimeconfig.MemoryTidyTuning) error {
+	f.got = &panel
+	return f.err
+}
+
+// TestAdminMemoryTidyTuningWrite_HotAppliesAndAudits 接线了热生效实现时：保存后当场把
+// **新值**交给运行期（hot=true），并落一条审计 `memory.tidy.tuning`/ok。
+func TestAdminMemoryTidyTuningWrite_HotAppliesAndAudits(t *testing.T) {
+	t.Parallel()
+	tidy := &fakeTuningTidy{}
+	mems := &fakeTuningMemories{}
+	env := newTuneEnv(t, Deps{MemoryTidy: tidy, Memories: mems})
+	env.seed(t, `{"intervalSec": 86400}`)
+	resp, body := env.put(t, env.token(t, auth.RoleAdmin), `{"intervalSec": 10800, "tempTtlSec": 259200}`)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	view := env.view(t, body)
+	if !view.Hot || view.HotError != "" {
+		t.Fatalf("hot/hotError = %v/%q, want true/空", view.Hot, view.HotError)
+	}
+	if tidy.gotTuning == nil || tidy.gotTuning.IntervalSec == nil || *tidy.gotTuning.IntervalSec != 10800 {
+		t.Fatalf("整理档没收到面板值：%#v", tidy.gotTuning)
+	}
+	if mems.got == nil || mems.got.TempTtlSec == nil || *mems.got.TempTtlSec != 259200 {
+		t.Fatalf("入库侧没收到面板值：%#v", mems.got)
+	}
+	// base 是 `.env` 层（进程生效配置投影），不是面板值本身。
+	if tidy.gotBase == nil || tidy.gotBase.IntervalSec != 86400 {
+		t.Fatalf("base 不是 .env 层：%#v", tidy.gotBase)
+	}
+	recs, err := env.srv.obs.audit.List(context.Background(), 50)
+	if err != nil {
+		t.Fatalf("list audit: %v", err)
+	}
+	found := false
+	for _, rec := range recs {
+		if rec.What == memoryTuningAuditAction && rec.Result == "ok" {
+			found = true
+		}
+	}
+	if !found {
+		t.Fatalf("审计链里没有 %s/ok 的记录：%#v", memoryTuningAuditAction, recs)
+	}
+}
+
+// TestAdminMemoryTidyTuningWrite_HotFailureIsHonest 热生效实现报错时：**值照旧留在盘上**
+// （不丢），但响应如实 `hot:false` + 原因，绝不说成「已生效」。
+func TestAdminMemoryTidyTuningWrite_HotFailureIsHonest(t *testing.T) {
+	t.Parallel()
+	tidy := &fakeTuningTidy{err: errors.New("boom")}
+	env := newTuneEnv(t, Deps{MemoryTidy: tidy})
+	env.seed(t, `{"intervalSec": 86400}`)
+	resp, body := env.put(t, env.token(t, auth.RoleOwner), `{"intervalSec": 10800}`)
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("status = %d, want 200 (body=%s)", resp.StatusCode, body)
+	}
+	view := env.view(t, body)
+	if view.Hot || view.HotError == "" {
+		t.Fatalf("hot/hotError = %v/%q, want false/非空", view.Hot, view.HotError)
+	}
+	if got := view.Values["intervalSec"]; got != float64(10800) {
+		t.Fatalf("热生效失败不该丢值：%#v", view.Values)
+	}
+}
+
+// TestAdminMemoryTidyTuning_UnavailableWithoutDataDir 数据目录未接线时如实报「没有落点」，
+// 绝不猜一个目录去写（端点据此回 500 tuning_unavailable）。
+func TestAdminMemoryTidyTuning_UnavailableWithoutDataDir(t *testing.T) {
+	t.Parallel()
+	srv, err := New(cfgDefault(), Deps{
+		Auth: auth.New(config.AuthConfig{AdminUser: "a", AdminPass: "b", JWTSecret: testSecret}),
+	})
+	if err != nil {
+		t.Fatalf("new server: %v", err)
+	}
+	if _, ok := srv.memoryTidyTuningPath(); ok {
+		t.Fatal("没有数据目录时不该解析出落点")
+	}
+}

internal/services/gateway/routes.go

@@ -259,6 +259,16 @@ func (s *Server) registerAdminRoutes(
 	// 幂等；审计 `memory.tidy.reject`。见 admin_memory_tidy_reject.go。
 	mux.Handle("POST /api/v1/admin/memories/candidates/reject", writeAuth(http.HandlerFunc(s.adminTidyCandidatesReject)))
 	mux.Handle("POST /api/v1/admin/memories/tidy/run", writeAuth(http.HandlerFunc(s.adminMemoryTidyRun)))
+	// 记忆整理「面板调优」的读写（切片 MEMPANEL / M4；契约由塔登记）：
+	// 读 .../memories/tidy/tuning 回显 `$DATA_DIR/config/memory-tidy.json` 里本卡片
+	// 管的 7 个旋钮 + 它们的取值规则（specs）；写同一条路径是**三态补丁**
+	// （键缺位 = 不改动 / 合法值 = 采用 / 非法值 = 400 且盘上不动）+ 原子落盘
+	// + 审计（memory.tidy.tuning）。两条都走 writeAuth（owner|admin）—— 与同族的
+	// GET /admin/memories、POST /admin/memories/{id}/revert 同档：它是私有记忆面的
+	// 运行期旋钮，不是给 viewer 的监控投影；也**不是** owner-only（写的是面板配置
+	// 文件，不是身份/凭据面）。见 admin_memory_tuning.go。
+	mux.Handle("GET /api/v1/admin/memories/tidy/tuning", writeAuth(http.HandlerFunc(s.adminMemoryTidyTuningRead)))
+	mux.Handle("PUT /api/v1/admin/memories/tidy/tuning", writeAuth(http.HandlerFunc(s.adminMemoryTidyTuningWrite)))
 	mux.Handle("GET /api/v1/admin/observability/audit", writeAuth(http.HandlerFunc(s.adminObservabilityAudit)))
 	mux.Handle("GET /api/v1/admin/sessions/{id}/export", writeAuth(http.HandlerFunc(s.adminExportSession)))
 	mux.Handle("POST /api/v1/admin/rag/query", writeAuth(http.HandlerFunc(s.adminSearchRag)))