@modusensus/dsh-mneme 0.8.13 → 0.8.15

package/docs/DAEMON.md

@@ -0,0 +1,46 @@
+# dsh-mneme 独立服务(daemon)
+
+`dsh-mneme-serve`:在 DSH 宿主之外把 mneme 跑成一个常驻数据面。#363(Mneme Bridge)确立的方向——第三方集成需要长期挂载,而 DSH 不必一直开着;这是官方推荐姿势,lib 直挂的 embedded 模式降级为无网兜底。
+
+## 1. 职责边界
+
+daemon 是**数据面**,不是第二个宿主:
+
+- **有**:存储(SQLite)、检索(关键词 + BM25 + 向量,`/search` 统一召回,与宿主共用 `src/semantic.js` 同一套装配)、注入候选(`/context`,issue #370,与宿主注入管线同一份 `injectCandidates`)、镜像同步与人改合并、`/maintenance/reclaim`、`/bootstrap`、recall_runs 检索/注入回执。
+- **没有(第一期,无 LLM)**:巩固(autoDream)、蒸馏(autoSummarize)、实体抽取、sleep、注入/工具/面板路由。前两者是**结构性缺失**而非开关——daemon 装配里没有 LLM 句柄,巩固只属于 DSH 宿主进程。这就是 daemon 与宿主「单写者」的机械保证(AGENTS.md externalApi/autoDream 单侧纪律的 daemon 版),不依赖用户自觉。
+
+与宿主装配(`src/index.js` apply)的关系:`src/serve.js` 只搬数据面那一半,每步注释锚定 index.js 来源行号;刻意不抽公共装配函数(apply 其余环节与宿主 ctx 纠缠,防御段纪律「最后动或不动」)。装配漂移风险由 `test/serve-bin.test.js` 的多进程共存用例兜底(两进程真开同一个库互写互读)。
+
+## 2. 对外接口
+
+路由面 = `src/api-standalone.js` 全表(health/status/profile/rules/memories 读写/search/context/maintenance/bootstrap),鉴权同源(Bearer + timingSafeEqual,`GET /health` 免鉴权)。daemon 自身零新路由;#370 的 `/context` 落在 api-standalone 工厂里,宿主外部访问与 daemon 自动同享(参数、scope 语义与 recall_runs 注入分账见包 README 路由表)。daemon 侧唯一自有选项是 `strictPort`(见 §4)。
+
+CLI:
+
+```bash
+dsh-mneme-serve [--memory-dir <dir>] [--port <n>] [--host <addr>] [--embed <provider>]
+```
+
+- `memoryDir`:CLI > env `DSH_MNEME_MEMORY_DIR` > `~/.dsh/memory`(与宿主 config.js 同默认,支持前导 `~`)。
+- `--embed`:语义检索提供方。`local`(默认:自管 runtime 与嵌入模型缺失时**自动取件**,download 档,约 200MB;失败降级关键词并打可操作日志)| `ollama` | `openai`(读宿主面板存的 vector-config)| `off`(纯关键词 + BM25)。取件来源可用 env 换道:`DSH_MNEME_RUNTIME_DIR`(自管 runtime 目录)、`DSH_MNEME_RUNTIME_TARBALL_DIR`(离线 .tgz 目录,优先于联网)、`DSH_MNEME_RUNTIME_MIRROR`(registry 镜像前缀)。
+- port/host 解析链与宿主「外部访问」一致:显式参数 > kv `external_api` 持久值 > 默认 8790 / 127.0.0.1。
+- token 与 DSH 面板 / CLI **共用同一份**(kv `external_api`,首次启动自动生成并持久化)——三方零配置互通。
+- 安全:daemon 使用明文 HTTP,不提供原生 TLS。指定非回环 `--host` 时,请勿直接把服务暴露给不可信网络;远程访问请走 TLS 终止代理或 SSH 隧道。
+- stdout 只在就绪时打一行 `dsh-mneme-serve listening on http://host:port (pid N)`(机器可读,脚本/测试解析端口用);日志全走 stderr。
+- SIGINT/SIGTERM 优雅收库后 exit 0;Windows 强杀由 WAL 回放兜底。
+
+## 3. 内部文件
+
+- `src/serve.js` — `createServeRuntime({memoryDir, port, host, logger, strictPort, embed, embedder, reranker})`:装配链 createStore → createSettings → createMirror → createService(最小 config)→ recoverMirror → 人改镜像合并闭包 → vectorIndex + semantic → recall recorder → createMaintenance → createStandaloneApi(带 `embedder: embedder ?? semantic?.embedder ?? null`,供 `/context` 查询嵌入),每步锚定 index.js 行号。返回 `{api, store, service, settings, maintenance, semantic, tokenExisted, dispose}`;第三方可 import 它自行托管生命周期(bin 只是薄壳),`embedder/reranker` 参数供注入自管嵌入。
+- `src/semantic.js` — embedder/reranker 装配 + boot 自动回填,**纯搬移自 index.js**(PR2),宿主与 daemon 共用同一份;`backfillMissingEmbeddings` 经 index.js barrel 再出口(测试照旧从 index.js import)。
+- `bin/dsh-mneme-serve.mjs` — CLI 壳。独立成 bin 而非 cli.mjs 子命令:CONTRIBUTING 禁止给 cli.mjs 加 import;命名循 dsh-mneme-mcp 先例。
+- `src/api-standalone.js` 的 `strictPort` 选项 — daemon 自己引入的唯一数据面改动,默认关闭(daemon 侧显式传 true)。#370 起该工厂另增 `/context` 路由与可选 `embedder` 注入,宿主外部访问同享。
+
+## 4. 已知坑
+
+1. **端口互斥,二选一**:daemon 与 DSH 的「外部访问」抢同一个默认端口。daemon 侧 strictPort 报错退出;反方向( daemon 先占 8790,DSH 后开外部访问)宿主侧会**静默顺延**到下一端口(宿主旁路的多实例恢复语义,api-standalone.js listenWithRetry)——面板显示的端口会变,别当 bug 报。
+2. **双进程写并发**:与 DSH 同时运行是设计内场景(WAL + busy_timeout 先序,store.js createStore)。但 `saveWithDedupe` 的 (type,title,scope) 去重是先查后写、库层无 UNIQUE 约束,两进程并发写同一三元组有极小概率产生重复条目——已知限制,勿当强保证宣传(要不要加 UNIQUE 索引属 schema 防御段,单独决策)。
+3. **镜像双写竞态**:daemon 与宿主都会渲镜像 .md;可再生物,失败由 recoverMirror 自愈,极端并发下单文件可能短暂脏,下次同步覆盖。
+4. **版本偏斜**:库迁移是幂等加法式(PRAGMA 检查 + ALTER),旧代码读新 schema 一般无碍,但该组合无人测过——daemon 与插件请同版本升级。
+5. **第一期不吃宿主配置**:daemon 不加载 config schema(schemastery 是宿主 peer 依赖),面板/feature_flags 对它不生效;它只有 CLI 参数 + 上述固定最小 config(`language: zh`、document 子系统关闭;语义键默认值逐键锚定 config.js,见 `src/serve.js` 的 `daemonSemanticCfg`)。`--embed local` 首次启动会自动取件 runtime + 模型(均有日志);取件/嵌入失败统一降级关键词 + BM25,不影响读写。
+6. **验收锚点**:`test/serve.test.js`(in-process 全链路 + token 复用 + recall_runs 回执 + 注入假 embedder 的向量轴锁)、`test/serve-bin.test.js`(真子进程 + 多进程互写互读)、`test/standalone-api.test.js` 的 strictPort 用例(busy → reject,默认路径仍顺延)、`test/reindex-backfill.test.js`(semantic 纯搬移后宿主行为不变)。

package/docs/ENTITIES.md

@@ -0,0 +1,245 @@
+# 实体结构化记忆（Entity Gene，v0.3.0）
+
+> dsh-mneme 的**记忆基因**层：从记忆文本里抽取**命名实体**、**带时间轴的属性**、**实体间关系**，并支持按实体/属性精确召回记忆。与 autoDream 联动——update 记录 supersedes、merge 迁移属性归属。
+
+v0.3.0 四个阶段全部落地：
+
+| 阶段 | 内容 |
+|------|------|
+| P1 | 三表 Schema（entities / entity_attrs / entity_relations）+ 索引 + store CRUD |
+| P2 | LLM 抽取器（JSON 抽取 + resolveEntity 去重 + saveAttr 时间轴 + saveRelation + fail-safe） |
+| P3 | 前缀搜索（`entity:` / `attr:`），attr 精确 = 1.0 > keyword 提及 = 0.7 |
+| P4 | autoDream 联动（applyUpdate 写 supersedes 自引用；applyMerge 迁移 loser attrs） |
+
+存储层（建表 + CRUD）**始终可用**，不依赖任何 LLM；只有 `entityExtractionEnabled=true` 时流水线才会自动抽取。
+
+---
+
+## 一、三表结构
+
+所有建表语句在 `src/store.js` 的 `SCHEMA` 中，`CREATE TABLE IF NOT EXISTS` + `CREATE INDEX IF NOT EXISTS`，对旧库幂等。
+
+### `entities` — 命名实体
+
+```sql
+CREATE TABLE IF NOT EXISTS entities (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,            -- 规范化名称（全名/主名）
+  type TEXT,                     -- person|project|concept|technology|organization
+  first_seen TEXT NOT NULL,      -- 首次出现时间
+  last_seen TEXT NOT NULL,       -- 最近出现时间
+  mention_count INTEGER DEFAULT 1, -- 提及次数（同名去重后递增）
+  canonical_memory_id TEXT       -- 规范来源记忆（保留位）
+);
+CREATE INDEX IF NOT EXISTS idx_entities_name ON entities(name);
+CREATE INDEX IF NOT EXISTS idx_entities_type ON entities(type);
+```
+
+### `entity_attrs` — 属性（快照式时间轴）
+
+```sql
+CREATE TABLE IF NOT EXISTS entity_attrs (
+  id TEXT PRIMARY KEY,
+  entity_id TEXT NOT NULL,
+  attr_key TEXT NOT NULL,
+  attr_value TEXT NOT NULL,
+  memory_id TEXT,                -- 属性出处记忆
+  valid_from TEXT NOT NULL,
+  valid_until TEXT,              -- NULL = 当前有效
+  confidence REAL DEFAULT 1.0,
+  source TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_attrs_entity ON entity_attrs(entity_id);
+CREATE INDEX IF NOT EXISTS idx_attrs_key    ON entity_attrs(attr_key);
+CREATE INDEX IF NOT EXISTS idx_attrs_valid  ON entity_attrs(valid_from, valid_until);
+CREATE INDEX IF NOT EXISTS idx_attrs_memory ON entity_attrs(memory_id);
+```
+
+### `entity_relations` — 关系（追加式）
+
+```sql
+CREATE TABLE IF NOT EXISTS entity_relations (
+  id TEXT PRIMARY KEY,
+  from_entity TEXT NOT NULL,
+  to_entity TEXT NOT NULL,
+  relation_type TEXT NOT NULL,   -- uses|depends_on|part_of|related_to|supersedes
+  memory_id TEXT,
+  created_at TEXT NOT NULL,
+  metadata TEXT                  -- JSON 自由字段
+);
+CREATE INDEX IF NOT EXISTS idx_relations_from ON entity_relations(from_entity);
+CREATE INDEX IF NOT EXISTS idx_relations_to   ON entity_relations(to_entity);
+CREATE INDEX IF NOT EXISTS idx_relations_type ON entity_relations(relation_type);
+```
+
+---
+
+## 二、valid_until 时间轴机制
+
+属性采用**快照式**写入：同一 `entity_id + attr_key` 只允许**一行当前有效**（`valid_until IS NULL`）。
+
+```
+saveAttr(entity=X, key=role, value="前端工程师")
+  → 先把 X/role 的现有有效行 valid_until 置为 now（invalidateOldAttr）
+  → 再插入新行 valid_from=now, valid_until=NULL
+```
+
+读取语义：
+
+- `getCurrentAttrs(entityId)` — 只返回有效行（`valid_until IS NULL`），即"当前值"
+- `getAttrHistory(entityId)` — 按 valid_from 升序返回全部历史行（含已失效），用于追溯演变
+- `findMemoriesByAttr(key, value)` — 返回携带该属性**当前有效**行的记忆（去重）
+  - **value 非空**：精确匹配 `attr_value`
+  - **value 为空 / undefined / null**：返回该 `attr_key` 的全部当前有效记忆（"`attr:key` 无 `=value`"契约）
+
+> ⚠️ 迁移时注意：同一 entity+key 连存两次会**失效前一行**（快照语义）。要保留多条同 key 的当前值，应把它们挂到**不同实体**上。
+
+---
+
+## 三、Store CRUD
+
+`createStore` 暴露以下实体 API（`src/store.js`）：
+
+| 方法 | 说明 |
+|------|------|
+| `createEntity({ name, type })` | 建实体，`first_seen=last_seen=now`，`mention_count=1` |
+| `findEntityByName(name)` | 按规范化名称查（去重锚点） |
+| `findEntityById(id)` | 按 id 查 |
+| `updateEntity(id, patch)` | 部分更新；默认 `mention_count+1`、刷新 `last_seen`；可用 `patch.mention_count` 显式覆盖 |
+| `saveAttr({ entity_id, attr_key, attr_value, memory_id, confidence, source })` | 写属性（先失效旧行） |
+| `invalidateOldAttr(entityId, attrKey, now)` | 手动失效；返回受影响行数 |
+| `getCurrentAttrs(entityId)` | 当前有效属性列表 |
+| `getAttrHistory(entityId)` | 全部属性历史（最旧在前） |
+| `getAttrsByMemory(memoryId)` | 某记忆关联的全部属性（autoDream update 用） |
+| `findMemoriesByAttr(key, value)` | 按属性召回记忆（value 空 = 该 key 全部当前有效） |
+| `saveRelation({ from_entity, to_entity, relation_type, memory_id, metadata })` | 追加关系 |
+| `getRelations(entityId)` | 某实体任一侧（from/to）的关系 |
+| `migrateAttrsToMemory(fromId, toId, now)` | 把 from 记忆的属性 memory_id 改指 to（keeper 已有同 entity+key 当前行则失效）；返回 `{ migrated, invalidated }` |
+
+---
+
+## 四、LLM 抽取器
+
+`src/entities/extractor.js` → `extractEntities(memory, { store, config, callLLM })`。
+
+### 触发方式
+
+`service.saveWithDedupe` 在 **created** 后 fire-and-forget 触发，仅当：
+
+1. `config.entityExtractionEnabled === true`
+2. service 已通过 `service.setEntityExtractor(...)` 注入抽取钩子（`index.js` 在插件启动时接好）
+
+抽取**异步执行**、失败绝不阻塞记忆写入（fail-safe）。
+
+### LLM JSON 契约
+
+```
+{
+  "entities": [
+    {"name": "string", "type": "person|project|concept|technology|organization",
+     "attrs": [{"key": "string", "value": "string", "confidence": 0.9}]}
+  ],
+  "relations": [
+    {"from": "entityName", "to": "entityName", "type": "uses|depends_on|part_of|related_to"}
+  ]
+}
+```
+
+抽取管线：
+
+1. `buildSystemPrompt` — 约束上限（`entityExtractionMaxEntities` / `entityExtractionMaxAttrs`）、禁编造、用规范化名
+2. `extractJsonFromText` — 先直接 `JSON.parse`，失败再抓首个 `{...}` 块
+3. `sanitizeExtractedData` — 非法 type → `concept`；非法 relation type → `related_to`；非法 confidence → 0.9；超限截断；relations 的 from/to 必须引用实体清单
+4. `resolveEntity` — **同名去重**：`findEntityByName` 命中 → `updateEntity(id, {})`（`mention_count+1`），未命中 → 建新实体
+5. 逐条 `saveAttr`（挂 `memory_id` + `source: "llm_extract"`）→ 逐条 `saveRelation`
+6. 单实体/属性/关系失败只 `skipCount++` 并告警，不中断整批
+
+### 返回 / fail-safe
+
+```js
+{ ok: true, entities: [{ name, type, attrs, entity_id }], attrs: [...], relations: [...], skipped: n }
+{ ok: false, error: "..." }
+```
+
+- 缺失 content、LLM 返回空、JSON 解析失败、sanitize 抛错、`callLLM` reject → 一律 `{ ok: false }`，**绝不向上抛异常**
+- `entityExtractionEnabled=false` 时钩子完全不触发，存储层照常可用
+
+---
+
+## 五、搜索：`entity:` / `attr:` 前缀
+
+`service.searchMemories` 在 `config.entitySearchEnabled === true`（默认 true）时识别前缀路由：
+
+```
+entity:阿尔托        → searchByEntity("阿尔托")
+attr:国籍=芬兰       → searchByAttr("国籍", "芬兰")   精确匹配
+attr:国籍           → searchByAttr("国籍", undefined) 该 key 全部当前有效
+```
+
+### searchByEntity 排序
+
+**合并优先级：attr 精确关联 = 1.0 > 关键词提及 = 0.7**，attr 命中不覆盖、keyword 只补充召回，最终按 `_score` 降序取 topK：
+
+| 来源 | 分数 |
+|------|------|
+| `entity_attrs.memory_id` 精确关联（当前有效） | `_score = 1.0`，`_source = "entity_attr"` |
+| 标题/内容/标签含实体名 | `_score = 0.7`，`_source = "keyword"` |
+
+`entitySearchEnabled=false` 时前缀不做路由，按普通关键词搜索（`entity:xxx` 字面串极少命中 → 通常返回空）。
+
+---
+
+## 六、autoDream 联动
+
+`applyDecisions` 在 `config.entityExtractionEnabled === true` 时启用实体副作用，**仅记录、绝不阻断主流程**：
+
+- **applyUpdate（supersedes）**：事务提交成功后，为该记忆关联的每条实体属性建立**自引用** supersedes 关系，表示"此属性版本已被替代"：
+
+  ```js
+  saveRelation({ from_entity: attr.entity_id, to_entity: attr.entity_id,
+                 relation_type: "supersedes", memory_id: id,
+                 metadata: { attr_key, old_value } })
+  ```
+
+- **applyMerge（属性迁移）**：将 loser 记忆关联的 `entity_attrs.memory_id` 迁移到 keeper；若 keeper 已有同 `entity+key` 的当前有效属性，则 loser 行被**失效**（keeper 值优先）：
+
+  ```
+  { migrated, invalidated } = store.migrateAttrsToMemory(loserId, keeperId, now)
+  ```
+
+- `entityExtractionEnabled=false` 时两条副作用**完全跳过**（update/merge 本身照常生效）。
+
+---
+
+## 七、配置项
+
+| 键 | 默认值 | 说明 |
+|----|--------|------|
+| `entityExtractionEnabled` | `false` | 实体抽取总开关（默认关；存储层恒可用） |
+| `entityExtractionModel` | `""` | 抽取专用模型（空 = 用 agent 默认模型） |
+| `entityExtractionMaxEntities` | `10` | 每次抽取实体数上限 |
+| `entityExtractionMaxAttrs` | `20` | 每实体属性数上限 |
+| `entitySearchEnabled` | `true` | `entity:` / `attr:` 前缀搜索开关 |
+
+```yaml
+# ~/.dsh/profiles/web/cordis.patch.yml
+- id: dsh-mneme
+  config:
+    entityExtractionEnabled: true
+    entityExtractionModel: deepseek-chat   # 可选，默认用 agent 默认模型
+    entitySearchEnabled: true
+```
+
+---
+
+## 八、迁移说明
+
+- 实体三表在 `createStore` 的 `SCHEMA` 中 `CREATE TABLE IF NOT EXISTS` 创建，**旧库打开自动建表**，幂等（重复打开/重启无副作用，`test/entities.test.js` 有覆盖）。
+- 无需人工迁移数据；现有 `memories` 表不变，实体表是**旁挂**结构。
+- 抽取开启后，新写入的记忆自动补实体；存量记忆可通过触发抽取或后续 backfill 补全（v0.3.0 未内置存量回扫）。
+
+---
+
+## 测试
+
+`test/entities.test.js`（31 条，node:test）：Schema 三表 + 索引 + 旧库幂等迁移 / 实体 CRUD / 属性时间轴（saveAttr 失效旧行、getCurrentAttrs / getAttrHistory）/ `findMemoriesByAttr`（精确匹配 + **空 value 契约** + 过期行排除）/ 抽取器（mock LLM 写入、同名去重、垃圾 JSON / LLM 故障 fail-safe、开关触发）/ 前缀搜索（1.0 > 0.7 排序、attr 精确、attr 空值、开关关闭不路由）/ autoDream（supersedes、merge 迁移与失效、开关关闭跳过）/ fail-safe（抽取失败不阻塞写入）。

package/docs/LOCAL_MODEL.md

@@ -0,0 +1,222 @@
+# dsh-mneme 本地模型部署指南
+
+- **日期**：2026-08-15
+- **范围**：为 dsh-mneme 配置完全离线的本地语义模型（Embedding + Rerank），覆盖 ONNX（transformers.js）与 Ollama 两种路径
+
+## 1. 前置要求
+
+| 项目 | 要求 | 说明 |
+|------|------|------|
+| Node.js | ≥ 22.5（建议 24+） | 插件依赖 `node:sqlite`（22.5 起可用，24 稳定） |
+| 磁盘空间 | ≥ 300MB（推荐 1GB+） | bge-small-zh-v1.5 量化约 100MB，bge-reranker-base 约 250MB；Ollama 模型另计 |
+| 内存 | ≥ 1GB 可用 | 纯 CPU 推理亦可运行 |
+| GPU（可选） | 显存 ≥ 2GB | 开启 `localEmbedDevice: "gpu"`（onnxruntime 需要额外安装 cuda 后端） |
+| 网络 | 仅首次下载模型需要 | 已下载后可完全离线（默认走 Hugging Face，可换镜像源） |
+
+> 依赖解析分三层：① **插件自管运行时目录**（`~/.dsh/mneme/runtime/`，见 §2.5，优先）；② 宿主 profile 里已装的 `@huggingface/transformers`；③ 都没有则本地推理不可用，检索自动降级为关键词/BM25（读写在任何情况下都不受影响）。
+>
+> 从本版起 `@huggingface/transformers` 已从 `dependencies` 降为**可选 peer**（`peerDependenciesMeta.optional`），安装插件时不会再带上它和它那套原生闭包；第 ② 层因此只对「自己装过这份依赖」或「从旧版本升级上来、尚未被 prune」的环境有效。**正在使用本地嵌入的用户请在升级前按 §2.5 收编一份**，否则升级后本地嵌入不可用（读写信道不受影响）。
+>
+> `onnxruntime-node` 作为可选原生后端列在 `allowScripts`（首次安装需确认脚本），无需手动额外安装。
+
+## 2. 模型安装 / 下载
+
+### 2.1 自动下载（默认，推荐）
+
+首次使用本地 Embedder 时会**自动从 Hugging Face Hub 下载**对应模型到本地缓存，无需手动操作：
+
+```bash
+node scripts/benchmark-embed.js --provider local --model Xenova/bge-small-zh-v1.5
+# 首次运行会显示下载进度 → 加载模型 → 输出基准表格
+```
+
+默认缓存目录：`~/.dsh/mneme/models`（用户级，重装/升级依赖不丢；`embedModelCacheDir` 留空时启用）。transformers.js 把模型存成 `<cacheDir>/<org>/<name>/`（实测 4.2.0，例如 `~/.dsh/mneme/models/Xenova/bge-small-zh-v1.5/`）：
+
+- Linux/macOS：`~/.dsh/mneme/models/`
+- Windows：`%USERPROFILE%\.dsh\mneme\models\`
+
+> 实测 transformers.js 4.2.0 在离线加载（`allowRemoteModels=false`）时按 `<cacheDir>/<org>/<model>/` 解析模型文件，例如 `<cacheDir>/Xenova/bge-small-zh-v1.5/config.json`。与本段上面描述的 `hub/models--…` 布局不一致时，以实际报错里给出的路径为准；缓存不在默认位置时按 §2.5 用 `--cache-dir` 指过去。
+
+### 2.2 手动指定缓存目录
+
+内存受限/离线机器可把模型缓存放到指定位置（迁移、共享缓存）：
+
+```js
+// 配置示例（插件配置里设置 embedModelCacheDir）
+const embedder = createEmbedderByProvider("local", {
+  cacheDir: "/data/hf-models",   // 模型缓存目录
+  model: "Xenova/bge-small-zh-v1.5"
+});
+```
+
+### 2.3 Ollama 路径
+
+如果本机已有 Ollama：
+
+```bash
+ollama pull nomic-embed-text   # 或 bge-m3（多语言）
+```
+
+Ollama Embedder 走 `/api/embeddings`，**不下载任何文件到插件缓存**，模型由 Ollama 管理。
+
+### 2.4 断点续传
+
+下载基于 Hugging Face Hub 缓存协议，**中断后重试自动续传**（按分片断点续传，不重新下载已完成部分）。若反复中断导致缓存损坏，删除对应模型的缓存目录后重跑即可：
+
+```bash
+rm -rf ~/.dsh/mneme/models/hub/models--Xenova--bge-small-zh-v1.5
+```
+
+### 2.5 自管运行时（收编 / 校验 / 排查）
+
+本地推理真正要用的是一整套依赖闭包：`@huggingface/transformers` + `onnxruntime-node` + `sharp`（本机实测从宿主 node_modules 收编时是 **49 个包、3203 个文件、约 393MB**）。插件支持把它收编到自管目录 `~/.dsh/mneme/runtime/`，与宿主 profile 的依赖图解耦；收编**优先使用硬链接**，同盘时几乎不额外占盘。
+
+**为什么要独立出来**：这份闭包此前留在插件 `dependencies` 里，而 profile 是所有插件共用的依赖图，于是「装任何插件」都要替它重走一遍整条链，弱网下极慢。摘掉该声明后，运行时由自管目录承接——所以要**先收编、再升级**，否则升级后本地嵌入不可用。
+
+**三条取件来源，按可用性依次尝试**（面板按钮、`memory_runtime` 工具、CLI 三者共用同一套编排）：
+
+| 顺序 | 来源 | 特点 |
+|---|---|---|
+| ① | 收编本机 profile 的 `node_modules` | **零网络**；同盘硬链接，几乎不占额外空间 |
+| ② | `runtimeTarballDir` 指向的本地 `.tgz` 目录 | 某个包网络下不到时用（文件名按 npm 约定 `<basename>-<version>.tgz`） |
+| ③ | npm registry（`runtimeMirror` 可换镜像） | 按随包发布的 `runtime-manifest.json` 逐个取，**每个 tarball 先校验 sha512 再落盘** |
+
+走 ③ 时体积是 **win32-x64 实测约 33 个包、2142 个文件、数百 MB**（各平台不同，故不写死数值）——比①少，因为清单剔除了 `onnxruntime-web`（127.7MB，占全量三分之一）：transformers 的 Node 构建从不 import 它（把一个空的 `onnxruntime-web` 打桩进去，嵌入结果逐字节相同），风险由 `verify` 的真实推理兜底。清单本身**平台无关**（数据源是 `package-lock.json` 里所有平台的条目），下载时按各包的 `os`/`cpu` 过滤，所以 win32 / darwin / linux × x64 / arm64 都被覆盖 —— 不需要谁在某个系统上先跑一次生成脚本。
+
+```bash
+# 在插件目录下运行（例如 node_modules/@modusensus/dsh-mneme）
+
+# 1) 看状态：在哪、来源、结构完不完整（不加载模型，秒回）
+node scripts/mneme-runtime.mjs status
+
+# 2) 收编宿主里已有的那份（只读源、只写自管目录，不安装任何东西）
+node scripts/mneme-runtime.mjs adopt --from ~/.dsh/profiles/<profile>/node_modules
+
+# 3) 真加载运行时并跑一次推理，确认可用
+node scripts/mneme-runtime.mjs verify --cache-dir ~/.dsh/mneme/models
+```
+
+- 退出码：`0` 健康 / `1` 不健康或失败 / `2` 用法错误（便于脚本直接 gate，区分「没装」和「装坏了」看输出里的 `status`）。加 `--json` 得到机器可读结果。
+- `verify` 的功能验证**不触网**（`allowRemoteModels=false`）：模型必须已在缓存目录里，否则会明确失败——这是有意的，验证不该偷偷触网。缓存不在默认位置时用 `--cache-dir` 指到与 `embedModelCacheDir` 一致的位置。
+- 三条入口（CLI / 面板 / `memory_runtime`）的判据是同一份：缓存目录取 `embedModelCacheDir`（**留空即用户级默认目录**，与真实嵌入同一处解析），探针模型取 `localEmbedModel`（留空即默认小模型）。也就是说验证用的就是真实推理用的那份模型——CLI 不需要额外 `--cache-dir`，面板也不会跑到包内去找（#387 修的就是这个不一致）。
+- 收编来的目录没有可比对的原始产物，完整性如实标 `unverified`，不假装验过；结构检查通过 ≠ 功能可用，两者分开报。
+- `status` 只做结构检查，所以 `functional` 恒为 `unknown`——要看真实推理结果就跑 `verify`。
+- 运行时不可用时插件不会崩：检索降级为关键词/BM25，读写在任何情况下都不受影响；错误信息会带上 `adopt` 的具体命令。
+- 同一份状态也能从 `GET /api/dsh-mneme/semantic` 的 `localRuntime` 字段读到（面板与 CLI 同源）。
+
+#### 不用命令行也可以
+
+- **面板**：记忆面板的「向量索引」卡片在本地 provider 且运行时不就绪时，会显示**代价说明**（要额外一份运行时、解包后数百 MB）、先试收编、没有再下载，并按实际走的那一档分开报结果。卡片下面还有一个「取回本地运行时」按钮，点一下即完成。
+- **让 agent 代做**：`memory_runtime` 工具提供三个动作——`status`（只读，**返回里带代价说明**，便于 agent 先告知你再动手）、`provision`（走上面三档来源）、`verify`（真跑一次推理）。所以即便你不看面板，也可以直接让 agent 处理。
+- **这条路由与其它写路由走同一道门**：`POST /api/dsh-mneme/runtime/provision` 是唯一会联网拉数百 MB 并写盘的写面，鉴权规则与其他写路由完全一致——配了 `apiToken` 就必须带 token，**没配就等于不校验**（这是插件既有的鉴权模型，不是这条路由特有的）。本机默认部署下它开箱可用；但若这个端口能被别的页面/机器够到，请照第 3.1 节配上 `apiToken`。面板按钮与 `memory_runtime` 都走这道门，不需要额外配置。
+- **平台过滤的取向是「宽松优先」**：清单是平台无关的一份（含所有平台的包），下载时按本机 `os`/`cpu` 过滤；Linux 上如果**确认**了本机是 glibc，还会剔掉另一套 libc 的变体（`sharp` 与 `libvips` 的 musl 包，十几 MB）。拿不到 libc 证据时一律不过滤——多下十几兆，好过赌错方向装出一份跑不起来的运行时。
+- **宿主那份 transformers 会被版本门禁**：第 ② 层（宿主裸 specifier）只接受 `>=4.2.0` 且 `<5` 的版本；宿主装到 v5 时不会被静默使用，而是明确报出「版本越界」并退到第 ③ 层的可操作提示。版本读不到（某些打包形态）时不拦，以免这层对老用户整体失效。
+
+```yaml
+# 两个可选配置键（默认留空 = 不改变任何行为）
+runtimeTarballDir: ""   # 本地 .tgz 目录：有它就优先于联网
+runtimeMirror: ""       # registry 镜像前缀，例如 https://npmmirror.com/mirrors/npm/
+```
+
+#### 升级前必做（否则本地嵌入会断）
+
+如果你正在使用本地嵌入（`embedProvider: local`），**在升级到已摘掉 `dependencies` 声明的版本之前**先执行一次 `adopt` + `verify`。顺序不能反：升级时 pnpm 会 prune 掉宿主里那份依赖，那之后就没有可收编的源了，只剩联网下载一条路。
+
+#### 自己取一份来收编（相对上面的手动路径）
+
+上面的面板按钮 / `provision` 已经能在没有可收编副本时自行下载。但如果你希望**完全掌控取件过程**（例如用自己的镜像、或先在一处统一缓存），仍然可以手工取一份再收编——不必逐个下载包：
+
+```bash
+# Windows（PowerShell / cmd）
+mkdir %TEMP%\mneme-fetch && cd /d %TEMP%\mneme-fetch
+npm i @huggingface/transformers@^4.2.0
+node "<插件目录>\scripts\mneme-runtime.mjs" adopt --from "%TEMP%\mneme-fetch\node_modules"
+
+# Linux / macOS
+mkdir -p /tmp/mneme-fetch && cd /tmp/mneme-fetch
+npm i @huggingface/transformers@^4.2.0
+node "<插件目录>/scripts/mneme-runtime.mjs" adopt --from /tmp/mneme-fetch/node_modules
+```
+
+- **安装脚本必须能执行**：npm 默认会执行生命周期脚本，而 `onnxruntime-node` / `sharp` 正是靠 postinstall 取原生二进制；加 `--ignore-scripts` 会得到一个装不起来的闭包。pnpm 10+ 默认拦截构建脚本，所以这里用 npm 更省事。
+- 收编完那个临时目录可以直接删掉：闭包已经在 `~/.dsh/mneme/runtime/` 里了（硬链接时几乎不额外占盘）。
+- 收编后**仍然建议跑一次 `verify`**——结构完整不等于能推理。
+
+## 3. 配置
+
+### 3.1 插件配置（`~/.dsh/profiles/web/cordis.patch.yml`）
+
+```yaml
+- id: dsh-mneme
+  name: '@modusensus/dsh-mneme'
+  config:
+    # ── Embedding ──────────────────────────────
+    embedProvider: local        # local | ollama | openai（默认 openai，保持 v0.1 行为）
+    localEmbedModel: Xenova/bge-small-zh-v1.5
+    localEmbedDimension: 512    # 与模型匹配的向量维度
+    localEmbedDevice: cpu       # cpu | gpu（仅 local 生效）
+    localEmbedBatchSize: 8      # 分批嵌入条数，内存紧张调小
+    embedModelCacheDir: ""      # 模型缓存目录（空=用户级 ~/.dsh/mneme/models；注意：不做 ~ 展开，要指别处必须写绝对路径）
+    ollamaBaseUrl: "http://localhost:11434"   # 仅 ollama 生效
+    ollamaModel: "nomic-embed-text"           # 仅 ollama 生效（openai 端点走面板 vector-config）
+    # ── Rerank（Phase 2，可选）─────────────────
+    rerankEnabled: false        # 开启向量召回后的精排
+    rerankModel: Xenova/bge-reranker-base
+```
+
+### 3.2 环境变量（可选）
+
+| 变量 | 作用 |
+|------|------|
+| `HF_ENDPOINT` | Hugging Face 镜像源，例如 `https://hf-mirror.com`（国内加速） |
+| `HF_HUB_CACHE` | 覆盖默认缓存目录 |
+
+### 3.3 各后端配置对照
+
+| 配置 | local (ONNX) | ollama | openai |
+|------|--------------|--------|--------|
+| `localEmbedModel` | HF 模型 id（如 `Xenova/bge-small-zh-v1.5`） | —（用 `ollamaModel`） | —（用面板 vector-config） |
+| `ollamaBaseUrl` | — | `http://localhost:11434`（默认） | — |
+| `ollamaModel` | — | Ollama 模型名（如 `nomic-embed-text`） | — |
+| `localEmbedDevice` | ✅ | — | — |
+| `localEmbedBatchSize` | ✅ | — | — |
+| `embedModelCacheDir` | ✅ | — | — |
+
+## 4. 首次使用
+
+1. 配置 `embedProvider`（或保持 `openai` 不动）
+2. 保存配置并重启 DSH，或直接跑 `scripts/benchmark-embed.js` 验证
+3. 首次触发本地模型时，transformers.js 自动下载 → `init()` 打印 `local embedder ready: <model> (dim=512, device=cpu)`
+4. 之后所有 `memory_save` 写入自动补向量；已有记忆可用「重建索引」批量补建
+
+> 注意：切换 `localEmbedModel` 或 `embedDimension` 后，旧向量与新向量维度不同、无法混算，需**重建索引**（复用 v0.1 的 `reindexMissing` 机制）。
+
+## 5. 常见问题
+
+### Q1：模型下载失败 / 下载超慢
+
+- 国内网络：设置镜像源 `HF_ENDPOINT=https://hf-mirror.com`（或 `export HF_ENDPOINT=https://hf-mirror.com`）
+- 公司代理拦截：检查 `HTTPS_PROXY` / `HTTP_PROXY` 环境变量
+- 磁盘不足：清理缓存或用 `embedModelCacheDir` 换目录
+
+### Q2：`Xenova/bge-small-zh-v1.5` 加载报错 / 显存不足（OOM）
+
+- 默认 `device: cpu`、`dtype: q8`，内存占用已最小化
+- 尝试 `embedBatchSize` 调小（如 4/2）降低峰值内存
+- 显存不足：`device: gpu` 时改回 `cpu`；或检查 onnxruntime-node 是否安装了 GPU 后端
+
+### Q3：中英文混排 / CJK 文本处理
+
+- `bge-small-zh-v1.5` 对中文与中英混排均优化良好；纯英文场景可换 Ollama 的 `nomic-embed-text`
+- 单条文本上限 8000 字符（与 v0.1 一致），超长自动截断
+- 检索时 query 与记忆正文走同一 Embedder、同一归一化（mean pooling + L2），余弦分数才可比
+
+### Q4：换模型后结果变差 / 向量混乱
+
+- 换模型（尤其维度不同）后旧向量不可复用，必须重建索引
+- 若在 Web 面板/API 配置过 v0.1 的 `vector-config`，v0.2 会优先采用插件配置，旧配置仅作降级路径
+
+### Q5：本地模型加载很慢（首次/每次启动）
+
+- 首次含下载，属正常；已缓存后每次启动仅加载进内存（数百 ms 级）
+- 大模型（如 bge-m3）可考虑换用更小的 `Xenova/bge-small-zh-v1.5`（量化 q8 约 100MB）