Skip to content

Commit 2df646b

Browse files
authored
feat(capacity): 容量水位预警与无损回收入口(#275) (#623)
feat(#275): 容量预警——库体积/归档规模过线在 /health 与面板上报(空间维度)
2 parents 355f5fc + 3a5fc29 commit 2df646b

18 files changed

Lines changed: 757 additions & 21 deletions

‎dsh-mneme/CHANGELOG.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,13 @@
44

55
## 🆕 新增
66

7+
- **容量预警(#275 空间维度):库体积 / 归档区规模过线时,`/health` 与面板都看得见**。维护者 2026-10-21 对照 `main` 的现状盘点里,这是「还缺什么」第 2 条:保留期(`retentionDays`)给了时间维度,空间维度一直缺着——库在涨、归档区在涨,但没有任何地方会说过线。接手口径点得很直白:「`/health` 已经有镜像健康卡,加一个库体积卡是同一条路径」。
8+
9+
- **三道阈值,全是观察口(`src/config.js`)**:`capacityWarning.dbSizeWarnMb`(256 MB)、`capacityWarning.archivedRowsWarn`(5000 行)、`capacityWarning.archivedRatioWarn`(0.95)。默认值全部锚定 #275 议题自己的实测,不拍脑袋——55 MB 库 VACUUM 0.8s,256 MB 起代价才值得先看数字(议题「现在便宜、以后贵」);归档 5,000 是「数千条这个量级」的上沿(议题实测 2,400 时还没坏);占比健康区就在 0.8~0.9(活跃数百 / 归档数千,议题实测 0.90),预警线刻意放 0.95,不然对着健康库天天报警。**没有 enabled 总开关**:预警没有周期性消费者(`/health` 被读到才算一次),也不自动归档 / 删除任何东西(#275 拍板:真删由人显式确认)——数字恒在,某条检查不要就把阈值设 0(0 = 显式关)。
10+
- **判级一层、答复一处(`src/service.js` + `src/api.js`)**:`service.getCapacityHealth` 与镜像健康的 fail-safe 同款——读失败显式 `status:"unknown"`,绝不伪装 ok;store 关掉不抛。`GET /api/dsh-mneme/health` 的四个答复分支全带上 `capacity` 块(镜像读失败不该把容量数字一起藏掉,两个半张互相独立)。每条检查回 `value / threshold`,报警要能对上数字;`:memory:` 库的体积检查**缺席**而不是 ok(「量不到」≠「零体积」);答复只带数字、**不带库文件路径**(storageStats 里有 path,`/health` 是半张对外面)。
11+
- **面板「库体积」卡(`lib/client.js`)**:进「库内一览」组,大数字是磁盘足迹,行给活跃 / 归档(含占比)/ 可回收空闲页;过线的检查逐条列出并走 `--mneme-warn` 预警色(新增 `.mneme-statrow--warn` / `.mneme-statusnum--warn` 两层,`StatusCard` 加了 `numWarn` 与逐行 `warn` 两个可选参数,不传的卡渲染逐字节不变)。三种拿不到数据的情况(fetch 失败 / 老宿主没这个块 / 后端 unknown)全部 fail-closed 渲染「未知」。增速刻意不算:归档净增速率是 recall-stats `archive` 块的第五指标,同一个数字长两处就会分叉。
12+
- **键的三件套成对登记**:`settings.js` 白名单(两个 int 走 `FEATURE_FLAG_INT_RANGES`、占比浮点走 `FEATURE_FLAG_NUMBER_RANGES`)+ `api.js` 的 `NESTED_FLAG_PATHS` 三个点号键 + 计数锁 121 → 124。阈值改动是启动快照(与 `panel_mode` 同节奏),面板显示「待重启」。
13+
- **文档与验证**:`docs/CONFIGURATION.md` 新增「容量预警」一节、`docs/STORAGE.md` 补「容量预警(#275 空间维度)」节(含三道阈值的过线含义与读法边界)、README 键表补 `capacityWarning` 行(docs-config-keys 的全键闸与键名断言都要过)。`test/capacity-warning.test.js` 新增 9 条(行数口径、schema 边界、三道检查各自的过线与关闭、fail-safe、`/health` 挂载与不泄露路径、没接线时显式 null);`test/client.test.js` 新增面板卡形状锁(fail-closed 表达式、warn class、i18n 双语键各出现两次);`test/api.test.js` 往返测试补三个点号键。全量 3164 用例 / 3163 通过 / 0 失败 / 1 跳过;check-sync 通过。
714
- **目录归属文档(#278 第 3 子项)**:新增 [docs/DIRECTORIES.md](docs/DIRECTORIES.md),把散在注释里的「哪个目录是什么」收成一处总账。开篇钉死三个相似名:`~/.dsh/memory` 是记忆库(SQLite 正本 + 镜像 md + 候选 / 提议 / 观察 / 日记 / 文档目录),`~/.dsh/mneme` 是模型与运行时缓存(**不是记忆库**,可整目录删掉重来),`~/.dsh-mneme` 是 CLI 连接配置——把模型缓存当成记忆库是这个项目真实踩过的坑。每个落点标了拥有者(人改 / 机器写 / 外部只读)与出处文件,另附「删了会怎样」速查、七张路径配置键的展开规则差异(`memoryDir` 一族做 `~` 展开、模型 / 运行时一族不做)、与已知坑(`documents.md` ≠ `documents/`、镜像手改窗口、两个 CLI 的默认落点各站一边)。README 中英文档表与 AGENTS.md 模块地图同步加了索引行。#278 的另两个子项(`~/.dsh` 迁出、统一导出)是大活,按 issue 建议拆批另行落地。
815

916
- **会话头顶那个日记入口撤了;「写今天 / 存到这个项目」补进面板**。两处入口同时存在时,用户点哪一个都像「又开了一本」,而右栏那套是旧版遗留下来的:会话头一个按钮 → 右栏页签 → 里面才是写与导出。现在只留一个入口:记忆面板的「日记」标签页。

‎dsh-mneme/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -518,6 +518,7 @@ dsh plugin --profile web add "C:/path/to/modusensus-dsh-mneme-0.9.0.tgz"
518518
| `writeAdmission` | `{enabled:false, enforce:false}` | 写入准入(issue #254,默认关):把「这条该不该进库」前移到 LLM 之前。第 1 级是零 LLM 的确定性判据——空白 / 纯噪声 + 密钥 / PII(判据来源是 #164 A2,经 `sensitiveScan` 注入,本批只定义接口)。`enabled` 跑判据并落审计行(`llm_audit_logs` 的 `metadata.deny`),`enforce` 才真的拒(`store.save` 之前返回,`memory_save` 返回 `action:"denied"` + `reason`);只开 `enabled` = 仅告警、写入不拦。去重键命中不进第 1 级(归 write-update 放行),G1/G2 阈值只计量。也走 feature_flags 白名单 |
519519
| `preInjectGate` | `{enabled:false, enforce:false}` | 注入前判定(issue #380,默认关):每帧注入候选出池后、进入 system prompt 前,一次池级 LLM 调用判出「会向本次请求注入意见/立场」的记忆(判定协议与 E12 实验同源;实测过滤把谄媚 26.9%→2.5%,且判定结果绝不进模型上下文——给模型看标记的线已被 E2/E3 关闭)。`enabled` 跑判定并落审计行(真实 token 用量 + 被标记记忆 id),`enforce` 才在缓存命中帧真滤除;冷缓存首帧降级为原样注入(宿主注入渲染是同步回调,判定走 prefetch+cache)。pin 池与检索线索行豁免;判定失败原样注入不阻塞;整池被标记时放弃本次滤除(fail-open);判定连续失败 3 次熔断一个冷却期;无默认路由时审计行 `model_id` 落 `unknown` 占位;`llmAudit` 关闭时本闸不运行;lightMode 强制关。也走 feature_flags 白名单 |
520520
| `distillRecords` | `{enabled:false, retentionDays:90}` | 蒸馏原文留存 + 记忆级溯源(issue #399,默认关):把蒸馏从「替换」降级为「叠加索引」——蒸过的窗口原文旁路落 `distill_records`(一个事件一行,主键 `(session_id, seq)`,`INSERT OR IGNORE` 幂等),每条新记忆落 `memory_provenance` 回指来源窗口(`(memory_id, session_id, seq_start, seq_end)` 唯一)。**渲染与落盘共用同一隐私谓词**:私有推理链、插件注入的机器内容(AGENTS.md / skill 正文 / 文件变更通知)两条路都不进;工具调用入参与结果、code 输出**只进渲染、不落盘**(渲染是 `codingRetrospect` 的输入,落盘只留对话)。留存文本**不受** `distillMaxChars` / 工具裁剪约束(原文就是原文)。到期裁剪只删 `distill_records`,溯源链接保留指向空区间(面板显示「来源已过期」),**绝不级联删记忆**;删记忆时显式清链接。无历史回填、从未蒸馏的窗口不留记录。进 `dsh-mneme reclaim` 报告第三项;lightMode 强制关。也走 feature_flags 白名单 |
521+
| `capacityWarning` | `{dbSizeWarnMb:256, archivedRowsWarn:5000, archivedRatioWarn:0.95}` | 容量预警(issue #275,空间维度):库体积 / 归档区规模过线时在 `GET /api/dsh-mneme/health` 的 `capacity` 块与面板「库体积」卡上报。三道阈值都是**观察口**,不是动作触发——没有周期性消费者,预警也永不自动归档 / 删除(真删由人显式确认),出口是维护卡的无损回收(`dsh-mneme reclaim`)。阈值判 `>=` 过线、**0 = 关掉该条检查**;判级 fail-safe(读失败显式 unknown,绝不伪装 ok)。默认值锚定 #275 议题的形态区间(活跃数百 / 归档数千;占比健康区就在 0.8~0.9,故 0.95 起才算过线)。答复只带数字、不带库文件路径;归档净增速率是 recall-stats `archive` 块的第五指标,不在这里重复。也走 feature_flags 白名单(改动启动快照生效,面板显示「待重启」) |
521522
| `conflictFreezeEnabled` | `false` | 冲突冻结(v0.4.4):dream 发现矛盾对不自动裁决,冻结进冲突队列;状态页「冲突队列」支持并排对比与人工确认(保留 A / 保留 B / 仅标记已处理,v0.8.0) |
522523
| `conflictFreezeMaxPending` | `100` | 冲突冻结队列最大挂起数(1-1000):超出后不再入队(防队列无限膨胀) |
523524
| `escapePromptVariables` | `true` | 注入文本花括号转义(v0.8.0 恢复,issue #162):注入边界把 `{{...}}` 转义,防止 hot memory / 记忆原文里的 Go template / Vue 语法触发宿主 interpolate 抛错卡死会话(v0.7.4 曾修复、v0.7.11 误删) |

‎dsh-mneme/docs/CONFIGURATION.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,18 @@
2828
| `memoryDir` | `~/.dsh/memory` | SQLite 记忆库目录 | WAL + busy_timeout 已为多进程就绪;两个宿主共用库时 `externalApiEnabled` 与 `autoDream` 只能一边开 |
2929
| `lightMode` | `false` | 轻量档总闸:一键关掉全部重型路径,保留核心循环(见文末清单) | 面板 `panel_mode=light` 等效为 `true` 且优先于 bundle 配置 |
3030

31+
## 容量预警(#275,空间维度)
32+
33+
库体积 / 归档区规模过线时在 `GET /api/dsh-mneme/health` 的 `capacity` 块与面板「库体积」卡上报。三道阈值都是**观察口**,不是动作触发:没有周期性消费者(`/health` 被读到才算一次),预警也永不自动归档 / 删除——真删由人显式确认(#275 拍板),出口是维护卡的无损回收(`dsh-mneme reclaim`,见 [STORAGE.md](STORAGE.md))。判级实现 `service.getCapacityHealth`,与镜像健康 fail-safe 同款:读失败显式 `status:"unknown"`,绝不伪装 ok。
34+
35+
| 键 | 默认 | 作用 | 开启后果 / 冲突 |
36+
|---|---|---|---|
37+
| `capacityWarning.dbSizeWarnMb` | `256` | 库磁盘足迹(主文件 + WAL + SHM)预警线,整数 MB | **0 = 关掉这条检查**。默认锚定议题实测:55 MB 库 VACUUM 0.8s,256 MB 起代价才值得先看数字再动手(议题「现在便宜、以后贵」) |
38+
| `capacityWarning.archivedRowsWarn` | `5000` | 归档区行数预警线 | **0 = 关**。锚定议题形态区间「归档是数千条这个量级」的上沿(实测 2,400 时还没坏) |
39+
| `capacityWarning.archivedRatioWarn` | `0.95` | 归档占比(归档 / 全部)预警线,浮点 0–1 | **0 = 关**。健康形态本身就落在 0.8~0.9(活跃数百 / 归档数千),0.9 会对着健康库报警;0.95 起才是「归档区吞掉活跃区」的形态 |
40+
41+
三个键都走 feature_flags 白名单(面板可改,改动是**启动快照**,与 `panel_mode` 同节奏,面板显示「待重启」);两个整数走 INT_RANGES、占比浮点走 NUMBER_RANGES。不设 `enabled` 总开关:数字恒在 `/health`,把某条检查关掉就是把对应阈值设 0。`:memory:` 库没有磁盘足迹,`db_size` 检查缺席(不是 ok);答复只带数字、不带库文件路径。归档增速(净增速率)是 recall-stats `archive` 块的第五指标,不在这里重复。
42+
3143
## 逐会话无痕(issue #539)
3244

3345
命中会话后,Mneme 不向该会话注入记忆、用户设置或工具指引,不接受其 `memory_*` / `set_scope_state` 工具调用,不对它蒸馏,也不由压缩抢救、M.O. 记账或自动提议路径保存该会话的内容。

‎dsh-mneme/docs/STORAGE.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -82,6 +82,27 @@ VACUUM 是 O(库大小),且需要排他写锁:库越大越慢,期间的写
8282
- 想保留活跃面:工具带 `keep_evidence_active: true`(注册器参数是 `archiveEvidence: false`);
8383
- 重注册同一份文档(出新版)时,那些已归档的 evidence 行仍可为**它所属的那份文档**背书;换个文档拿归档 id 当证据,照旧按捏造拒绝。
8484

85+
## 容量预警(#275 空间维度)
86+
87+
回收入口是「人主动按」的;容量预警补的是另一半:**让人知道该按了**。库体积 / 归档区规模过线时,`GET /api/dsh-mneme/health` 的 `capacity` 块与面板「库体积」卡(库内一览组)同时上报——维护者 2026-10-21 的接手口径:保留期(`retentionDays`)给了时间维度,这块补空间维度。
88+
89+
三道阈值,全部**观察口**:没有周期性消费者(`/health` 被读到才算一次),预警永不自动归档 / 删除(#275 拍板:真删由人显式确认)。
90+
91+
| 检查 | 键 | 默认 | 过线含义 |
92+
|---|---|---|---|
93+
| `db_size` | `capacityWarning.dbSizeWarnMb` | `256` | 磁盘足迹(主文件 + WAL + SHM)到线:VACUUM 的 O(库大小) 代价开始值得先看数字再动手 |
94+
| `archived_rows` | `capacityWarning.archivedRowsWarn` | `5000` | 归档区行数到「数千条这个量级」的上沿 |
95+
| `archived_ratio` | `capacityWarning.archivedRatioWarn` | `0.95` | 归档占比(归档 / 全部)到「归档区吞掉活跃区」——健康形态本身在 0.8~0.9,预警线刻意不放那里 |
96+
97+
读法与边界:
98+
99+
- 判级在 `service.getCapacityHealth`,与镜像健康同款 fail-safe:读失败显式 `status:"unknown"`,绝不伪装 ok。每条检查回 `value / threshold`,报警要能对上数字;**阈值 0 = 显式关掉那条检查**(判级前先看启用条件,不靠比较碰巧不成立)。
100+
- `:memory:` 库没有磁盘足迹:`file_bytes` 为 `null`,`db_size` 检查**缺席**而不是 ok——「量不到」和「零体积」是两回事。
101+
- 答复只带数字,**不带库文件路径**(storageStats 里有 path,`/health` 是半张对外面,不外带本机布局)。
102+
- 默认值锚定 #275 议题的形态区间,依据写在 config.js 的键注释里;三个键都走 feature_flags 白名单(面板可改,启动快照生效)。
103+
- 增速指标(归档净增速率 + 可压掉行数)是 recall-stats `archive` 块的第五指标,见下一节——预警卡刻意不算速率,同一个数字长两处就会分叉。
104+
- 过线之后先跑本入口(`dsh-mneme reclaim` / 维护卡);归档区同主题堆积是出口问题,归 #254 的写入准入与整理动作面,预警不碰内容。
105+
85106
## 第五指标:归档净增速率 + 可压掉行数
86107

87108
面板「记忆复用」卡与 `GET /api/dsh-mneme/recall-stats` 的返回里多了一个 `archive` 块(#275 拍板:与既有指标同位):

‎dsh-mneme/lib/api.js‎

Lines changed: 23 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -304,7 +304,12 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
304304
// Issue #471:政策轴——作用域级可逆闸门。两个键都是嵌套子字段,漏登记的后果
305305
// 同上(effective 静默缺键、面板读不到也 PUT 不进)。
306306
"scopeState.enabled": ["scopeState", "enabled"],
307-
"scopeState.enforce": ["scopeState", "enforce"]
307+
"scopeState.enforce": ["scopeState", "enforce"],
308+
// #275 容量预警:三个阈值都是嵌套子字段(两个整数走 INT_RANGES、一个浮点走
309+
// NUMBER_RANGES),漏登记的后果同上——effective 静默缺键、面板读不到也 PUT 不进。
310+
"capacityWarning.dbSizeWarnMb": ["capacityWarning", "dbSizeWarnMb"],
311+
"capacityWarning.archivedRowsWarn": ["capacityWarning", "archivedRowsWarn"],
312+
"capacityWarning.archivedRatioWarn": ["capacityWarning", "archivedRatioWarn"]
308313
// sensitiveScanEnabled(#164 A2)是顶层扁平键,不需要进这张表——走 configFlagValue
309314
// 的默认分支即可。
310315
};
@@ -2232,7 +2237,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
22322237
}
22332238
});
22342239

2235-
// --- health: mirror sync state (F-NEW-03 / v0.3.6) ---
2240+
// --- health: mirror sync state (F-NEW-03 / v0.3.6) + capacity (#275) ---
22362241
// Auth-gated; only returns a sanitized error code (never raw last_error which
22372242
// may leak paths/token-like strings/internal hosts). On state read failure it
22382243
// reports unknown/degraded (fail-closed) instead of a false dirty=false.
@@ -2241,23 +2246,34 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
22412246
path: "/api/dsh-mneme/health",
22422247
policy: "token",
22432248
handler(req, res) {
2249+
// 容量预警(#275 空间维度):与镜像状态同面但**互相独立**——镜像读失败不该
2250+
// 把容量数字一起藏掉,所以每个分支都带上。getCapacityHealth 自身 fail-safe
2251+
// (读失败回 status:"unknown");?.() 兜住没接线的老 mock service(此时显式
2252+
// capacity:null,面板渲染成「未知」,不冒充正常)。
2253+
let capacity = null;
2254+
try {
2255+
capacity = service.getCapacityHealth?.() ?? null;
2256+
} catch {
2257+
capacity = null;
2258+
}
22442259
let state = null;
22452260
try {
22462261
state = service.getMirrorHealth?.() ?? null;
22472262
} catch {
22482263
// read failure is itself a health signal: do not report a false clean
2249-
sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null } });
2264+
sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null }, capacity });
22502265
return;
22512266
}
22522267
if (!state) {
2253-
sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null } });
2268+
sendJson(res, 200, { mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null }, capacity });
22542269
return;
22552270
}
22562271
// Real read failure surfaces as dirty === null (peer blocker 5): report
22572272
// unknown explicitly instead of collapsing into a false "ok"/"degraded".
22582273
if (state.dirty === null) {
22592274
sendJson(res, 200, {
2260-
mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null }
2275+
mirror: { dirty: null, status: "unknown", last_error: null, last_attempt: null, success_at: null },
2276+
capacity
22612277
});
22622278
return;
22632279
}
@@ -2275,7 +2291,8 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
22752291
last_error: code,
22762292
last_attempt: state.last_attempt ?? null,
22772293
success_at: state.success_at ?? null
2278-
}
2294+
},
2295+
capacity
22792296
});
22802297
}
22812298
});

0 commit comments

Comments
 (0)