@modusensus/dsh-mneme 0.7.9 → 0.7.10

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Changelog
 
-> **完整版本历史见 [dsh-mneme/CHANGELOG.md](dsh-mneme/CHANGELOG.md)**（正式版本正源，0.3.8 → 0.7.8）。以下为仓库早期开发记录（0.1.0–0.2.x，2026-08-13~14，已归档）。
+> **完整版本历史见 [dsh-mneme/CHANGELOG.md](dsh-mneme/CHANGELOG.md)**（正式版本正源，0.3.8 → 0.7.9）。以下为仓库早期开发记录（0.1.0–0.2.x，2026-08-13~14，已归档）。
 
 All notable changes to dsh-mneme are documented here.
 

package/CONTRIBUTING.md

@@ -23,7 +23,7 @@ dsh-mneme-1/
 └── dsh-mneme/            # the plugin itself
     ├── src/              # source (ESM) — all feature work happens here
     ├── lib/              # build output; DSH actually loads lib/index.js
-    ├── scripts/          # sync-lib.js, e2e-dsh.js, stress-dsh.js, benchmark-*
+    ├── scripts/          # sync-lib.js, check-sync.js, e2e-dsh.js, stress-dsh.js, benchmark-*
     ├── test/             # node:test test suite
     ├── docs/             # SEMANTIC / SLEEP / ENTITIES / MIGRATION deep-dives
     ├── package.json      # plugin metadata and scripts
@@ -33,8 +33,8 @@ dsh-mneme-1/
 **Key convention: `src/` is the single source of truth; `lib/` is build output.**
 
 - Write code only in `src/`, then run `npm run sync` to mirror changes into `lib/`.
-- **Never edit `lib/` by hand** — the next sync overwrites it. The only exception is `lib/client.js` (the Web-panel bundle, authored independently; sync never touches it).
-- `npm pack` / `npm publish` run sync automatically via the `prepack` hook, so a published tarball always ships a fresh `lib/`.
+- **Never edit `lib/` by hand** — the next sync overwrites it.
+- Publish from the **repo root**: root `prepack` runs `scripts/check-sync.js`, which asserts `src/` ↔ `lib/` match file-for-file and fails the publish on any drift (issue #65). So run `npm run sync` (in `dsh-mneme/`) and commit the `lib/` changes **before** publishing.
 
 ---
 
@@ -71,6 +71,7 @@ Common scripts (all run under `dsh-mneme/`):
 - New features require corresponding tests; **changing core logic (e.g. model routing, decision validation) must update the affected test assertions** so the suite stays green before committing.
 - Test files live in `test/`, named `*.test.js`; shared mocks go in `test/helpers/` (e.g. `dream-mock.js`).
 - Known environment dependency: a few cases in `reranker.test.js` need `@huggingface/transformers` (locally this one case fails without the package; it is unrelated to repo logic and CI installs it and passes).
+- The published artifact is covered too: `test/lib-smoke.test.js` imports from `lib/` and asserts `src/` ↔ `lib/` are file-for-file identical (issue #65 regression guard).
 
 ---
 
@@ -127,7 +128,7 @@ Versioning follows semantic versioning (`MAJOR.MINOR.PATCH`). Full flow:
 3. **Full test pass**: `npm test` must be green.
 4. **Commit and push**: commit → `git push origin main` → `git tag vX.Y.Z` → `git push origin vX.Y.Z`.
 5. **Create a GitHub Release**: title `vX.Y.Z`, body referencing the matching CHANGELOG entry (review before publishing).
-6. **Publish to npm**: run `npm publish` from the **repository root** (`prepublishOnly` copies the version from `dsh-mneme/package.json` into the root `package.json`; `prepack` syncs `lib/`).
+6. **Publish to npm**: run `npm publish` from the **repository root** (`prepublishOnly` copies the version from `dsh-mneme/package.json` into the root `package.json`; `prepack` runs `scripts/check-sync.js` and fails if `src/` ↔ `lib/` drifted — ensure `npm run sync` + commit ran first).
 
 ---
 
@@ -170,7 +171,7 @@ dsh-mneme-1/
 └── dsh-mneme/            # 插件本体
     ├── src/              # 源码（ESM），所有功能都在这里开发
     ├── lib/              # 构建产物，DSH 实际加载的是 lib/index.js
-    ├── scripts/          # sync-lib.js、e2e-dsh.js、stress-dsh.js、benchmark-*
+    ├── scripts/          # sync-lib.js、check-sync.js、e2e-dsh.js、stress-dsh.js、benchmark-*
     ├── test/             # node:test 测试
     ├── docs/             # SEMANTIC / SLEEP / ENTITIES / MIGRATION 等专题文档
     ├── package.json      # 插件包元数据与 scripts
@@ -180,8 +181,8 @@ dsh-mneme-1/
 **关键约定：`src/` 是唯一的事实来源，`lib/` 是构建产物。**
 
 - 所有代码改动只写 `src/`，改完必须运行 `npm run sync` 同步到 `lib/`。
-- **不要手工编辑 `lib/`**——下次 sync 会覆盖你的改动。唯一的例外是 `lib/client.js`（Web 面板打包产物，独立创作，sync 不会触碰它）。
-- `npm pack` / `npm publish` 会通过 `prepack` 钩子自动执行 sync，所以发布产物永远是新鲜的 `lib/`。
+- **不要手工编辑 `lib/`**——下次 sync 会覆盖你的改动。
+- 发布在**仓库根**执行：root `prepack` 会跑 `scripts/check-sync.js`，逐文件断言 `src/` ↔ `lib/` 一致，有漂移直接发布失败（issue #65 教训）。所以发布前务必先在 `dsh-mneme/` 里跑 `npm run sync` 并把 `lib/` 改动一起提交。
 
 ---
 
@@ -218,6 +219,7 @@ npm run test:coverage # c8 覆盖率
 - 新增功能必须有对应测试；**修改核心逻辑（如模型路由、决策校验）时必须同步更新受影响用例的断言**，保证全量测试通过后提交。
 - 测试文件放在 `test/`，命名 `*.test.js`；共享 mock 放 `test/helpers/`（如 `dream-mock.js`）。
 - 已知环境依赖：`reranker.test.js` 的个别用例需要 `@huggingface/transformers`（本地未安装该包时这 1 例会失败，与本仓库逻辑无关，CI 会正常安装并通过）。
+- 发布产物也被覆盖：`test/lib-smoke.test.js` 从 `lib/` 直接导入复跑关键用例，并断言 src↔lib 逐文件一致（issue #65 防再犯）。
 
 ---
 
@@ -274,7 +276,7 @@ DSH 上游仍处于 developer preview 阶段，API 与服务接口变动频繁
 3. **全量测试**：`npm test` 确认通过。
 4. **提交并推送**：commit → `git push origin main` → `git tag vX.Y.Z` → `git push origin vX.Y.Z`。
 5. **创建 GitHub Release**：标题为 `vX.Y.Z`，正文引用 CHANGELOG 对应条目（发布前需人工过目）。
-6. **发布 npm**：在**仓库根目录**执行 `npm publish`（`prepublishOnly` 会自动把 `dsh-mneme/package.json` 的版本号写入根 `package.json`，`prepack` 自动 sync `lib/`）。
+6. **发布 npm**：在**仓库根目录**执行 `npm publish`（`prepublishOnly` 会自动把 `dsh-mneme/package.json` 的版本号写入根 `package.json`，`prepack` 会跑 `scripts/check-sync.js` 校验 src↔lib 一致性，漂移则发布失败——发布前须先 `npm run sync` 并提交 `lib/` 改动）。
 
 ---
 

package/README.md

@@ -10,7 +10,7 @@
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-3E63DD?style=flat-square" alt="license"></a>
   <a href="https://github.com/modusensus/dsh-mneme/actions"><img src="https://img.shields.io/github/actions/workflow/status/modusensus/dsh-mneme/test.yml?style=flat-square&label=CI" alt="CI"></a>
   <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-24%2B-3E63DD?style=flat-square&logo=nodedotjs&logoColor=white" alt="node"></a>
-  <a href="https://github.com/modusensus/dsh-mneme"><img src="https://img.shields.io/badge/tests-812%20passed-3E63DD?style=flat-square" alt="tests"></a>
+  <a href="https://github.com/modusensus/dsh-mneme"><img src="https://img.shields.io/badge/tests-815%20passed-3E63DD?style=flat-square" alt="tests"></a>
   <a href="https://codecov.io/gh/modusensus/dsh-mneme"><img src="https://img.shields.io/codecov/c/github/modusensus/dsh-mneme/main?style=flat-square" alt="coverage"></a>
   <a href="https://github.com/awesome-dsh-plugin/awesome-dsh-plugin"><img src="https://awesome-dsh-plugin.com/badge.svg" alt="Awesome"></a>
 </p>
@@ -69,7 +69,7 @@ dsh web
 | 删除对话时保留记忆 | `sessionLifecycleEnabled` | `false` | 改为 `true` |
 | 让 AI 自动提取结构化信息 | `entityExtractionEnabled` | `false` | 改为 `true` |
 
-> 在 DSH 设置面板 → 记忆库设置 中修改。完整配置说明见 [配置文档](dsh-mneme/docs/CONFIG.md)。
+> 在 DSH 设置面板 → 记忆库设置 中修改。完整配置说明见 [配置章节](dsh-mneme/README.md)。
 
 ## 隐私承诺
 
@@ -111,6 +111,7 @@ dsh web
 | **v0.7.6** | issue #48 修复：截断/前缀 id 也能精确操作（统一 resolveMemoryId）+ client.js 改 src 正源 | ✅ |
 | **v0.7.7** | issue #23 图谱回填：sleep 批量实体抽取 phase + node:sqlite 兼容修复 | ✅ |
 | **v0.7.8** | issues #58 #59 修复：DSH 0.1.2-rc.1 兼容——Session.events 改为 snapshotEvents() 垫片，autoSummarize 与 hot-context 注入恢复 | ✅ |
+| **v0.7.9** | issue #65 修复：v0.7.8 的 snapshotEvents 适配只改了 src/ 未同步 npm 实际加载的 lib/——补齐 lib 并加发布前 src/lib 一致性校验（check-sync.js 闸门）+ lib 冒烟测试 | ✅ |
 | **v0.8.0** | 图谱增强：兴趣漂移可视化 + scope 隔离（issue #17）+ 跨 workspace 共享 | 🚧 计划中（9 月末） |
 
 ## 🧪 本地开发
@@ -118,7 +119,7 @@ dsh web
 ```bash
 cd dsh-mneme
 npm install
-npm test          # 812 个测试
+npm test          # 815 个测试
 npm run stress    # 三轴线压测
 npm run sync      # src → lib 同步
 ```
@@ -178,7 +179,7 @@ Works out of the box. Enable these as needed:
 | Keep memories when deleting sessions | `sessionLifecycleEnabled` | `false` | Change to `true` |
 | Structured entity extraction | `entityExtractionEnabled` | `false` | Change to `true` |
 
-> Change in DSH Settings Panel → Memory Settings. Full config docs [here](dsh-mneme/docs/CONFIG.md).
+> Change in DSH Settings Panel → Memory Settings. Full config docs in the [Configuration section](dsh-mneme/README.md).
 
 ## Privacy
 
@@ -220,6 +221,7 @@ Works out of the box. Enable these as needed:
 | **v0.7.6** | Issue #48 fix: truncated/prefix ids resolve for exact ops (unified resolveMemoryId) + client.js now src-authored | ✅ |
 | **v0.7.7** | Issue #23 graph backfill: sleep batch entity extraction phase + node:sqlite compat fix | ✅ |
 | **v0.7.8** | Issues #58 #59 fix: DSH 0.1.2-rc.1 compat — Session.events moved to snapshotEvents() shim; autoSummarize & hot-context injection restored | ✅ |
+| **v0.7.9** | Issue #65 fix: v0.7.8's snapshotEvents shim only landed in src/, never in the npm-loaded lib/ — synced lib + added a pre-publish src↔lib consistency gate (check-sync.js) + lib smoke tests | ✅ |
 | **v0.8.0** | Graph enhancement: interest-drift visualization + scope isolation (issue #17) + cross-workspace sharing | 🚧 Planned (late Sep) |
 
 ## 🧪 Local Development
@@ -227,7 +229,7 @@ Works out of the box. Enable these as needed:
 ```bash
 cd dsh-mneme
 npm install
-npm test          # 812 tests
+npm test          # 815 tests
 npm run stress    # three-axis stress test
 npm run sync      # src → lib sync
 ```

package/dsh-mneme/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## [0.7.10] - 2026-09-07
+
+### 🆕 Web 面板体验升级：类型色点 / 图谱平移缩放 / 设置页重排 / 侧边栏冲突修复
+
+- **记忆类型色点体系**：新增 `MEMORY_TYPE_COLORS` 调色板（preference 琥珀 / project 绿 / decision 蓝 / summary 紫 / user 琥珀 / fact 绿 / history 灰，与图谱实体色同一风格的中饱和固定色相，明暗主题均可读）与 `.mneme-xdot` 色点组件，贯穿三处——类型筛选行（「全部」为空心环保持对齐）、时间树每一行、详情 meta。同一颜色在任何位置都代表同一记忆类型，扫视时间树即可分辨构成。分类计数改为 `margin-left:auto` 右对齐，色点不挤计数。
+- **图谱画布平移 + 滚轮缩放 + 重置视图**：此前画布仅有节点拖拽，`cursor: grab` 暗示的画布拖动从未实现。新增 `viewRef`（translate+scale）视口状态与 `<g transform>` 包裹层——空白处按住拖动平移整图；滚轮缩放以光标为锚点（0.5x–3x，native 非 passive wheel 监听，React 合成 `onWheel` 为 passive 无法 `preventDefault`）；节点 `mousedown` 增加 `stopPropagation` 防止误触发平移；节点拖拽灵敏度按缩放系数换算，放大后拖节点不再"飘"；图谱工具栏新增「重置视图」一键复原；画布高度提升至 320px；操作提示更新为「拖拽节点调整布局 · 空白处拖动平移 · 滚轮缩放」。
+- **设置页分区重排（借鉴 Claude App 设置排版）**：设置内容改为 `.mneme-set-sec` 分区呈现——用户画像 → 规则 → 自定义指令 → 自动打标签 → 侧边栏入口 → 向量搜索 → API Token（高级项移至最后），每区标题 + 一句话说明 + 细分隔线；规则行重做：编号圆点 + 圆角行 + 悬停浮现删除按钮，输入框回车直接添加；命令行 `/名称` 主题蓝高亮；全部输入控件统一 `.mneme-set-input`（聚焦品牌蓝描边）与 `.mneme-btn`。中英文提示全部重写为口语化文案（如规则区"给 Agent 立下必须遵守的规矩，随时增删，下一轮即生效"）。0.7.3 引入的自动打标签与侧边栏入口开关功能原样保留，仅归入新排版。
+- **侧边栏入口同标签冲突修复**：会话 tab 在 DOM 上不带注册 id，旧激活逻辑取"文档中第一个文字匹配的 `[role=tab]`"——安装其他插件后，同名标签或隐藏的设置分页会被误激活（表现为点击「记忆」无反应或跳错视图）。现改为 `findExplorerTabs` 多候选：先以 `offsetParent` 过滤不可见面板，点击后验证 `.mneme-x` 确实渲染才算成功，失败自动尝试下一个候选，全部失败仍回退全屏覆盖层。`test/client.test.js` 新增两条契约断言（渲染验证 + 隐藏面板过滤）。
+- **详情 meta 精排**：来源 `session:<uuid>` 截断为 200px 省略（完整值悬停可见），创建时间只显日期、更新时间改相对时间（超一周回退日期，完整时间戳保留在 tooltip），meta 恢复单行。
+- **新增只读端点 `GET /api/dsh-mneme/entities`**：实体清单（名称/类型/提及次数/首末见时间，`limit` 上限 1000），为实体目录 UI 与后续视图供数；exact 路由 19 → 20 条。
+- **工程**：`scripts/e2e-dsh.js` 的路由数断言从失真的 9 条修正为与 `src/api.js` 返回值一致的 20 条；client 测试同步适配新激活契约。
+- 全套 **815 测试通过**（含 client 激活契约 2 个新断言）。
+
 ## [0.7.9] - 2026-09-06
 
 ### 🐛 修复：v0.7.8 的 rc.1 snapshotEvents 适配未同步到 lib/（issue #65）

package/dsh-mneme/README.md

@@ -5,7 +5,7 @@
 [![npm version](https://img.shields.io/npm/v/@modusensus/dsh-mneme?color=blue&label=npm)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
 [![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 [![Awesome](https://awesome-dsh-plugin.com/badge.svg)](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
-[![tests](https://img.shields.io/badge/tests-812%20passed-success)](https://github.com/modusensus/dsh-mneme)
+[![tests](https://img.shields.io/badge/tests-815%20passed-success)](https://github.com/modusensus/dsh-mneme)
 [![CI](https://img.shields.io/github/actions/workflow/status/modusensus/dsh-mneme/test.yml)](https://github.com/modusensus/dsh-mneme/actions)
 [![node](https://img.shields.io/badge/node-24%2B-blue)](https://nodejs.org)
 [![npm downloads](https://img.shields.io/npm/dm/@modusensus/dsh-mneme?color=blue&label=downloads)](https://www.npmjs.com/package/@modusensus/dsh-mneme)
@@ -241,6 +241,8 @@ v0.3.0 起新增**记忆基因**层：从记忆里抽取**命名实体**、**带
 
 | 版本 | 亮点 |
 |------|------|
+| **v0.7.10** | Web 面板体验升级：记忆类型色点体系（筛选/时间树/详情三处贯穿）+ 图谱画布平移/滚轮缩放/重置视图（补齐 `cursor: grab` 暗示却缺失的交互）+ 设置页 Claude 风格分区重排（编号规则行、悬停删除、口语化文案）+ 侧边栏入口同标签冲突修复（可见性过滤 + 渲染验证 + 多候选重试）+ 详情 meta 精排（来源截断、相对时间）+ 新增只读 `GET /api/dsh-mneme/entities` 实体清单端点（19→20 条路由）；815 测试全绿 |
+| **v0.7.9** | issue #65 修复：v0.7.8 的 snapshotEvents 适配只改了 `src/`，npm 实际加载的 `lib/` 从未同步——静默失效；补齐 lib 三处垫片 + 新增 `scripts/check-sync.js` 发布前 src↔lib 一致性闸门（root prepack 调用，漂移直接 fail）+ `test/lib-smoke.test.js` 从 lib 导入复跑 + 一致性断言（CI 双保险）；815 测试全绿 |
 | **v0.7.8** | DSH 0.1.2-rc.1 兼容（issues #58 #59）：官方移除 `Session.events` 属性改为 `snapshotEvents()` 方法，autoSummarize 与 hot-context（短期上下文）注入取不到事件而失效；改用兼容垫片 `session.snapshotEvents?.() ?? session.events`，新旧 DSH 通吃，老版本行为不受影响；新增 2 个回归用例；812 测试全绿 |
 | **v0.7.7** | issue #23 实体图谱回填：sleep 批量实体抽取 phase（`sleepEntityExtractionEnabled` 默认关；最老优先、SQL LIMIT/OFFSET 分页下沉为有界查询不整表扫描；`pending_extracted_at` 幂等防重、成功/失败清除；metadata 合并不覆盖其他路径写入）；node:sqlite 兼容修复（pluck→all+map、`forgotten=0` 查询条件）；810 测试全绿 |
 | **v0.7.6** | issue #48 修复：`memory_update`/`memory_delete`/`memory_forget`/`memory_archive` 支持截断/前缀短 id（新增 `service.resolveMemoryId`：精确命中优先 + 唯一前缀解析 + 多命中拒绝列出候选 + `memory_delete` 未命中幂等补 `logger.warn`；纯通配符/空白兜底）；Web bundle `client.js` 改 src 正源；801 测试全绿 |
@@ -301,6 +303,7 @@ v0.3.0 起新增**记忆基因**层：从记忆里抽取**命名实体**、**带
 | **v0.7.7** | ✅ 完成 | issue #23 图谱回填 | sleep 批量实体抽取 phase：默认关 `sleepEntityExtractionEnabled`，按最老优先、SQL LIMIT/OFFSET 分页（下沉为有界查询，不再整表扫描）批量抽取未打标记忆的实体（修复 issue #23 实体图谱空白）；`pending_extracted_at` 幂等防重、成功/失败清除，metadata 合并不覆盖；node:sqlite 兼容修复（pluck→all+map、`forgotten=0` 查询条件）；810 测试全绿 |
 | **v0.7.8** | ✅ 完成 | DSH 0.1.2-rc.1 兼容（issues #58 #59） | 官方移除 `Session.events` 属性、改用 `snapshotEvents()` 方法后 autoSummarize 与 hot-context 注入失效；改为兼容垫片 `session.snapshotEvents?.() ?? session.events`，新旧 DSH 通吃，老版本不受影响；新增 2 个回归用例；812 测试全绿 |
 | **v0.7.6** | ✅ 完成 | issue #48 修复 | 四工具统一 `service.resolveMemoryId`：截断/前缀短 id 也能精确操作（精确命中优先、唯一前缀解析、多命中拒绝并列出候选、`memory_delete` 未命中幂等返回 + `logger.warn` 留痕）；Web bundle `client.js` 改 src 正源；801 测试全绿 |
+| **v0.7.9** | ✅ 完成 | issue #65 修复 | v0.7.8 的 snapshotEvents 适配未同步 lib/（npm 实际加载 lib/）导致发布产物静默失效；补齐 lib 三处垫片 + 发布前 src↔lib 一致性校验（`scripts/check-sync.js`，root prepack 调用，漂移 exit 1）+ `test/lib-smoke.test.js` 从 lib 导入复跑 + 一致性断言；815 测试全绿 |
 | **v0.8.0** | 🚧 计划中（9 月末） | 图谱增强 | 兴趣漂移可视化 + scope 隔离（issue #17）+ 跨 workspace 记忆共享 + 更多 heat 信号 |
 
 > 新能力一律做成**可开关的功能**（配置启用/关闭），默认保守开启、不破坏现有行为。`failure_memories` 表与 autoDream 决策引擎已为后续反思性成长铺好路。
@@ -309,7 +312,7 @@ v0.3.0 起新增**记忆基因**层：从记忆里抽取**命名实体**、**带
 
 ### 前置条件
 
-- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）— 兼容 DSH 0.1.x，已验证 0.1.2-rc.1（`Session.events` → `snapshotEvents()` 变更已由插件垫片兼容，新旧版本通吃）
+- [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness)（DSH）— 兼容 DSH 0.1.x，已验证 0.1.2-rc.1（`Session.events` → `snapshotEvents()` 变更已由插件垫片兼容，新旧版本通吃；v0.7.9 确保该垫片真正进入发布产物 lib/）
 - Node 24+（`node:sqlite`）
 
 ### 安装步骤
@@ -465,9 +468,9 @@ src/
 ├── api.js            # HTTP 路由（Web 面板数据通道）
 ├── client.js         # Web 面板 bundle（ModuleLoader 自注册；v0.7.6 起 src 正源）
 └── index.js          # 插件接线
-lib/                  # src 的同步分发产物（npm run sync，prepack 自动执行；无手写例外）
-test/                 # 812 个 node:test 测试（含审计与三轴线压测不变量）
-scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步 · benchmark-recall.js 召回基准
+lib/                  # src 的同步分发产物（npm run sync；发布前由 root prepack 的 check-sync.js 校验一致性，无手写例外）
+test/                 # 815 个 node:test 测试（含 lib-smoke.test.js：lib 产物冒烟 + src↔lib 一致性断言；审计与三轴线压测不变量）
+scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压测 · sync-lib.js 同步 · check-sync.js 发布闸门 · benchmark-recall.js 召回基准
 ```
 
 ## 🧪 开发
@@ -475,7 +478,7 @@ scripts/              # e2e-dsh.js 端到端演示 · stress-dsh.js 三轴线压
 ```bash
 cd dsh-mneme
 npm install        # 安装 peer 依赖（以 devDependencies 形式，用于本地测试）
-npm test           # 运行 812 个测试
+npm test           # 运行 815 个测试
 npm run stress     # 三轴线压测：长会话检索 / 冲突仲裁 / 多 Agent 并发（离线 mock LLM）
 npm run sync       # 把 src/ 同步到 lib/（发布时由 prepack 钩子自动执行）
 ```

package/dsh-mneme/lib/api.js

@@ -637,6 +637,25 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
     }
   });
 
+  // --- entity directory (entity gene v0.3.0): read-only list for the UI ---
+  // Flat entity list (newest-seen first). Attributes and relations stay on
+  // their own per-entity endpoints, the directory only carries the columns
+  // the rail needs: name, type, mention_count, first/last seen.
+  register({
+    kind: "exact",
+    path: "/api/dsh-mneme/entities",
+    handler(req, res) {
+      try {
+        const url = new URL(req.url, "http://localhost");
+        const limit = Math.min(1000, Math.max(1, Number(url.searchParams.get("limit") ?? 500) || 500));
+        const entities = service.listEntities?.({ limit }) ?? [];
+        sendJson(res, 200, { entities, total: entities.length });
+      } catch {
+        sendJson(res, 500, { error: "internal" });
+      }
+    }
+  });
+
   // --- health: mirror sync state (F-NEW-03 / v0.3.6) ---
   // Auth-gated; only returns a sanitized error code (never raw last_error which
   // may leak paths/token-like strings/internal hosts). On state read failure it
@@ -799,7 +818,7 @@ export function createApi(ctx, service, settings, commands, embedder, semantic =
   });
 
   return {
-    routes: 19,
+    routes: 20,
     dispose: () => {
       for (const dispose of disposers) dispose();
     }