dsh-memory-engine 0.6.1 → 0.7.0-beta.4

package/README.md

@@ -2,7 +2,24 @@
 
 DSH 插件的本地记忆引擎，带神经网络可视化。它让 agent 保存、召回和管理跨会话记忆，也能把你已有的记忆文件导进来。
 
-当前版本：0.5.2。Node ≥22，零新增依赖；DSH 宿主提供 `@deepseek-ai/dsh-tools@0.2.1-rc.3`。本机安装已启用，无需重复安装。
+当前版本：0.7.0-beta.4。Node ≥22，零新增依赖。新增中心角色卡、确定性球壳布局和可配置慢速自转；保留记忆管理和详情卡片，Canvas 与离线 HTML 继续共用唯一绘制实现。
+
+## 0.7.0 分步交付
+
+| 阶段 | 内容 | 独立验收 |
+| --- | --- | --- |
+| 第 1 步 · 已完成 | 宿主路由、共享图谱计算、同源 iframe | 原独立端口无监听，按钮能打开图，JSON 接口返回当前记忆 |
+| 第 2 步 · 已完成 | React 内直接绘制 Canvas | 浮层无 iframe；旋转、缩放、选中可用，关闭后动画停止 |
+| 渲染合并 · 已完成 | canvas.js 是唯一绘制源码，界面构建与离线 HTML 共用 | 画面不变，构建幂等，未构建的源码改动会使测试失败 |
+| 点击回归 · 已完成 | 恢复右侧只读详情卡片 | 可见字段、切换、关闭、高亮和复制；长正文可滚动 |
+| 第 3 步 · 已完成 | 记忆列表、搜索、编辑、删除、导出和清空 | 分页、筛选、确认与错误提示；写操作先备份 |
+| 中心角色卡 · 本版完成 | 固定角色核心、分层球壳、慢速自转 | 角色卡全文与复制；拖拽暂停，松手 2 秒恢复；缺省退回原布局 |
+| 引导小修 · 已完成 | 空库和手动回看共用三步卡片 | 编号步骤、复制提示词、刷新和关闭卡片可用 |
+
+- [x] 引导回看：右上角「?」、中央卡片、复制提示词、知道了/Esc 关闭。
+- [x] 按钮开关：hideButton、showGuideOnEmpty；配置请求失败时保留按钮并警告。
+
+界面使用应用内 canvas 渲染；`/memory-engine/` 整页 HTML 保留给 CLI 与浏览器直接访问。七个 agent 工具继续可用，记忆管理在应用内的「记忆」「设置」页完成。
 
 ## 支持的 DSH 版本
 
@@ -20,15 +37,92 @@ DSH 插件的本地记忆引擎，带神经网络可视化。它让 agent 保存
 
 peerDependencies 已放宽为 >=0.1.0-rc.8 <0.3.0 并标为 optional——宿主自带这份 SDK，不该因为版本号不匹配而装不上。
 
+0.7.0 的 GUI 还要求宿主提供 `webServer.register({ kind, path, handler })`。服务端声明 `inject = ['tools', 'webServer']`，插件生命周期结束时注销路由。原有 `ctx.effect` 和 `defineTool` 兼容逻辑保留；直接调用初始化时若路由注册失败，会记录提示，已注册的工具仍可用。
+
 ## 界面
 
 安装并启用插件后，完全退出 DSH 再打开。进入任意会话，头部第一行会出现 **🧠 记忆图谱** 按钮。
 
-点击后全屏显示图谱，右上角 **关闭 ×** 或 **Escape** 退出。每次打开都会读取当前记忆库重新生成；大库会先显示“正在生成”。
+点击后全屏显示图谱，顶部有 **图谱 / 记忆 / 设置** 三个 tab，右上角 **关闭 ×** 退出。每次打开或从其他 tab 返回图谱都会读取当前记忆库，在内存中计算当前图谱，不写入离线 HTML。离开图谱 tab 时停止 Canvas 动画。
+
+**记忆 tab** 按正文或标题搜索（250ms 防抖），可筛选知识、印象、对话、事件、日记，按最近、最老、快忘了或连接最多排序。每页 50 条，底部显示过滤后的总数和「加载更多」。点一条展开全文，再点「编辑」修改正文、分类、重要度或相关人；保存失败保留草稿并显示服务端错误，取消不发送写请求。删除必须再次确认。
+
+**设置 tab** 显示数据目录、条数、文件大小，支持复制路径和下载全部记忆。导出文件结构为 `{ ok: true, data: { total, items } }`，保留原始条目的全部字段。清空必须输入大写 `DELETE`，输入错误不会发请求；成功后回到空库引导。界面不重复提供导入，仍使用 `memory_import` 工具。
+
+点击神经元，右侧滑入约 350px 的只读详情卡片，显示分类、标题、重要度、留存、连接数、本地日期和正文；有情绪标签时才显示情绪行。空标题取正文前 20 字，长标题换行、长正文在卡片内滚动。点另一个节点只更新内容，不重复滑入。
+
+卡片的 **在图里高亮它** 调用现有激活效果；**复制正文** 复制全文，成功后显示「已复制 ✓」，1.8 秒后恢复。点图上空白处或卡片 × 关闭详情，图谱继续显示。关闭整个浮层、切换 tab 或刷新图谱会清空选中状态；编辑和删除在「记忆」tab 完成。
+
+**记忆库为空时，默认自动弹出中央引导卡片**；已经有记忆时，点右上角、关闭按钮左侧的 **?** 随时回看。同一张卡片显示三步说明、提示词和数据目录；「复制这段提示词」成功后显示「已复制 ✓」，「刷新图谱」重新载入当前记忆。
+
+点「知道了」关闭引导，图谱和已打开的详情仍在。Esc 按 **引导卡片 → 详情卡片 → 整个图谱浮层** 的顺序逐层关闭。引导通过结构化 JSON 和 React 组件显示，不注入 HTML、不跳转整页。
+
+### 按钮与空库引导开关
+
+在 `{DSH_HOME}/memory-engine/config.json`（默认 `~/.dsh/memory-engine/config.json`）的现有对象中合并以下字段，然后完全退出 DSH 再打开：
+
+```json
+{
+  "hideButton": false,
+  "showGuideOnEmpty": true
+}
+```
+
+`hideButton: true` 隐藏会话头部的 🧠 按钮，七个记忆工具照常可用。`showGuideOnEmpty: false` 让空库不自动弹出引导，仍可点 **?** 查看。未配置时分别默认 false/true，只有明确的布尔值才改变默认行为；现有 bridgeRoot/diaryDir 等字段请保留。
+
+配置请求失败、返回无效内容或超过 5 秒时，客户端记录一条警告并按默认显示按钮，避免网络错误让入口消失。
 
-**记忆库为空时，这个按钮打开的不是星图，而是一张上手引导页**：说明为什么是空的、给出可一键复制的提示词、列出导入命令。第一次装完点开不会看到一片黑。
+拖拽旋转、滚轮缩放（0.3～4.5），点击神经元激活并查看详情。详情直接使用节点已有数据，不请求新接口，也不写入记忆。客户端使用相对路径 `/memory-engine/api/map` 获取数据，由 React 管理 Canvas；关闭浮层或卸载组件会停止动画、取消请求并清理监听。桌面端经 DSH 的原生协议转发，无需知道宿主端口。旧 `config.json` 中的 `uiPort` 不再使用，可保留或删除。还可以运行 `node <插件目录>/scripts/render-map.mjs --open` 生成并打开离线图谱，整页 HTML 仍可点击查看原文。
 
-拖拽旋转、滚轮缩放、点击神经元看原文。服务默认监听 `127.0.0.1:18886`；端口被占用时记忆工具仍可用，可以运行 `node <插件目录>/scripts/render-map.mjs --open`，或直接打开 `~/.dsh/memory-engine/starmap.html`。修改端口需要同时修改 config.json 的 uiPort 和 client.js 的 VIEW_URL，见后文。
+### 中心角色卡与自转
+
+在现有 `config.json` 对象里合并以下字段（路径使用你自己的角色卡）：
+
+```json
+{
+  "personaFile": "C:/path/to/role.md",
+  "personaTitle": "阿鲸",
+  "spinSpeed": 0.35
+}
+```
+
+也可使用 `personaText` 直接配置正文，最多 4000 个 Unicode 字符；非空 `personaText` 优先于文件。文件只读、取前 4000 字，读取失败记录警告并退回原布局。标题默认「角色卡」，速度范围 0.05～1.5，默认 0.35（正常帧率下约 90 秒一圈）。配置后重新打开图谱即可读取；升级插件本身需要重新加载或重启 DSH。
+
+角色卡只作为图谱里的虚拟中心，不写入记忆库，也不参与评分、关联、复习、列表或导出。它固定在原点，点击显示 `[人格] 标题`、可滚动正文和「复制全文」。印象、知识、事件位于内层球壳，日记、对话和其他类别在外层；旧记忆更靠外。同一份数据的布局确定不变；没有角色卡时保留原来的脑状布局。
+
+打开后自动慢速旋转，拖拽时暂停，松手或取消拖拽 2 秒后恢复。关闭图谱或切换 tab 停止动画。离线 HTML 使用同一份布局和 Canvas，支持中心角色卡与全文复制。
+
+### 客户端构建
+
+`lib/render/canvas.js` 是唯一绘制源码，导出 `createRenderer(canvas, data, options)`，每个实例独立维护相机、节点缓存、脉冲和动画生命周期。它不导入模块，也不依赖 ModuleLoader。
+
+`lib/client.src.js` 是 ModuleLoader 工厂模板；修改它或 Canvas 源码后运行 `pnpm build`（也可 `npm run build`），生成单文件 `lib/client.js`。产物头部标有「别直接改这个文件」。构建先写同目录临时文件，再原子替换；相同输入得到逐字节相同的产物，失败会非零退出。
+
+`lib/render/render.mjs` 只保留 HTML、标题、图例、复习清单和原有详情外壳，读取同一份 Canvas 源码并内联。两个消费者共用 `scripts/lib/strip-export.mjs` 去掉导出声明，发布客户端和离线 HTML 都不需要运行时模块加载。离线 HTML 可直接双击打开。
+
+`pnpm test`（或 `npm test`）包含 `build-freshness` 检查：改了源码却忘记构建会失败，并提示「跑 pnpm build」；测试不会自动修复产物。`prepack` 保证 `pnpm pack` / `npm pack` 发布前重新构建。
+
+同源接口：
+
+| 方法 | 路径 | 返回内容 |
+| --- | --- | --- |
+| GET | `/memory-engine/` | 独立浏览器可直接访问的整页 HTML 图谱；应用内界面不再加载此页面 |
+| GET | `/memory-engine/api/map` | `{ nodes, links, review, stats, generatedAt, core, spinSpeed }`；配置角色卡时 nodes[0] 为 isCore，core 含 id/title/preview，否则为 null；stats 统计图谱节点 |
+| GET | `/memory-engine/api/stats` | 记忆总数、分类、衰减状态及存储位置 |
+| GET | `/memory-engine/api/onboard` | `{ empty, prompt, steps, dataDir }`，空库和手动帮助共用 |
+| GET | `/memory-engine/api/config` | 仅 `{ hideButton, showGuideOnEmpty, hasPersona, personaTitle, spinSpeed }`，不暴露正文或路径 |
+| GET | `/memory-engine/api/list?q=&kind=&sort=&limit=&offset=` | `{ total, allTotal, limit, offset, items }`；包含留存、连接数和 60 字预览 |
+| GET | `/memory-engine/api/item/:id` | 完整条目、留存和连接数；不存在返回 404 |
+| PUT | `/memory-engine/api/item/:id` | 仅更新传入的 text/kind/heat/who；返回更新条目和 backup |
+| DELETE | `/memory-engine/api/item/:id` | 删除一条，返回 `{ deleted, backup }` |
+| GET | `/memory-engine/api/export` | `{ total, items }`，条目原样导出 |
+| POST | `/memory-engine/api/clear` | 请求 `{ confirm: "DELETE" }`，返回 `{ removed, backup }` |
+
+JSON 成功返回 `{ "ok": true, "data": ... }`，失败返回 `{ "ok": false, "error": "说明" }`。本版仅给 map/config 增加角色卡字段，保留已有字段；stats/list/export 仍只统计实际记忆。接口仅接受本机 Host，严格限制路径，拒绝路径穿越；不允许的方法返回 405。只读接口不接收请求体，PUT 和 POST 只接收 JSON 对象，声明大小和实际分块累计大小都限制在 1MB。
+
+列表默认最近优先、每页 50 条，limit 上限 200；搜索为不区分大小写的包含匹配，kind 精确匹配。留存复用 `decay.retention()`，连接数复用全库 `scoreMemories()`，筛选不会改变连接数。编辑只允许 text（1～2000 字符且非全空白）、kind（1～20 字符）、heat（整数 1/2/3）、who（0～40 字符）；不会改动 id、时间、强化次数或触发相似合并。
+
+管理写操作统一先调用 `MemoryStore.backup()`，再调用已有 `write()` 临时文件加 rename 原子落盘。`memories.json.bak-<毫秒时间戳>` 操作备份保留最新五份，同毫秒时自动加序号。备份失败不写入，原子替换失败保留原文件；同步任务的 `bak-sync-*` 备份保留原有策略。切回图谱重新取数即可看到编辑或删除的结果。
 
 也可以让 agent 调用 `memory_map()`，生成可双击、离线打开的单文件 HTML：
 
@@ -164,9 +258,9 @@ path 必须是本地绝对路径。单条正文超过 2000 字、日期无效等
 - **颜色**：知识绿色、印象浅蓝、日记紫色、对话橙红，其他类型采用原工具包的默认配色。
 - **红色虚环**：提示快忘的记忆；左下角列出留存最低的复习清单。
 
-拖动旋转、滚轮缩放、点击神经元查看正文与关联扩散。图谱基于 neuron-memory-map 的脑状椭球和 Canvas 视觉；关联改为关键词倒排索引：从标题和正文提取 2～8 字片段，过滤纯数字和格式噪声，用关键词树匹配较长句子中的已提取片段；拉丁缩写只匹配完整片段。只为共享关键词的文档配对，每对最多 3 条关键词证据，boost 按这些证据累加。
+拖动旋转、滚轮缩放、点击神经元查看正文并激活关联。图谱基于 neuron-memory-map 的脑状椭球和 Canvas 视觉；关联改为关键词倒排索引：从标题和正文提取 2～8 字片段，过滤纯数字和格式噪声，用关键词树匹配较长句子中的已提取片段；拉丁缩写只匹配完整片段。只为共享关键词的文档配对，每对最多 3 条关键词证据，boost 按这些证据累加。
 
-关键词至少出现在 2 条记忆中；为避免泛词形成大团，DF 上限收紧为 `min(总数×30%, max(2, 总数×2%))`，实际 298 条时最高 DF 为 5。树突数量 `min(9, 4+round(sqrt(degree)×1.2))`，半径加成 `min(1.4, sqrt(degree)×0.18)`，让连接多的节点保留大小差别。本机当前图有 298 个节点、307 条边，已检查默认视图和点击激活。
+关键词至少出现在 2 条记忆中；为避免泛词形成大团，DF 上限收紧为 `min(总数×30%, max(2, 总数×2%))`，实际 298 条时最高 DF 为 5。树突数量 `min(9, 4+round(sqrt(degree)×1.2))`，半径加成 `min(1.4, sqrt(degree)×0.18)`，让连接多的节点保留大小差别。节点和边数随记忆库变化；图谱仍复用原渲染模块。
 
 图中的评分是渲染器的视图值，留存公式没有改；关联和 boost 的输入变化会影响图中留存。agent 召回、衰减、排序和扩散仍使用记忆引擎原有公式，不会因浏览图谱改变。
 
@@ -176,7 +270,7 @@ path 必须是本地绝对路径。单条正文超过 2000 字、日期无效等
 
 记忆库默认是 `~/.dsh/memory-engine/memories.json`，图是 `~/.dsh/memory-engine/starmap.html`，配置是 `~/.dsh/memory-engine/config.json`。
 
-**记忆存储、导入和图谱生成不上传记忆，不访问外部网络，不将数据发往远程服务器。** GUI 仅访问本机回环图谱服务。除本地配置/记忆目录、你明确指定的导入路径和配置的可选 QQ 来源之外，插件不会扫描其他个人文件。通用导入的格式适配可能使用系统临时目录，完成后自动清理。agent 使用外部模型时，调用上下文和工具结果的发送仍由 DSH 自身配置管理。
+**记忆存储、导入和图谱生成不上传记忆，不访问外部网络，不将数据发往远程服务器。** GUI 仅访问本机 DSH 宿主的同源路由。除本地配置/记忆目录、你明确指定的导入路径和配置的可选 QQ 来源之外，插件不会扫描其他个人文件。通用导入的格式适配可能使用系统临时目录，完成后自动清理。agent 使用外部模型时，调用上下文和工具结果的发送仍由 DSH 自身配置管理。
 
 | 文件 | 内容 |
 |---|---|
@@ -188,15 +282,13 @@ path 必须是本地绝对路径。单条正文超过 2000 字、日期无效等
 
 记忆和图谱只写本机，生成过程不调用外部服务，也不需要联网。记忆正文中的网址按普通文本保留，不作为图谱资源加载。
 
-示例配置（普通用户只需默认 uiPort）：
+普通用户无需配置图谱端口，也无需创建 config.json。可选的空配置为：
 
 ```json
-{ "uiPort": 18886 }
+{}
 ```
 
-图谱服务只监听 `127.0.0.1`，不提供 memories.json/config.json 等原始文件，只允许根页面、index.html/starmap.html 和 pages/N.html。端口被占用时只记录警告，agent 记忆工具仍可用，也可用离线 HTML。
-
-如需改端口，请同时修改 config.json 的 uiPort 和 `lib/client.js` 中 VIEW_URL 的端口，再完全退出并重开 DSH。默认二者均为 **18886**，没有自动发现机制。
+路由不提供 memories.json/config.json 等任意文件下载，只暴露本版表格列出的页面和接口。所有响应禁用缓存；图谱页面限制为同源嵌入，不加载外部脚本或资源。原独立服务 `lib/serve.js` 已删除。
 
 ## QQ 桥接适配器
 
@@ -205,7 +297,7 @@ path 必须是本地绝对路径。单条正文超过 2000 字、日期无效等
 适配器从 `QQ_BRIDGE_DIR` 环境变量取目录；未设置或无有效目录时再试本机 config.json 的 bridgeRoot，均不可用时给出配置提示。包内已去掉机器专属的桥接根路径。
 
 ```json
-{ "uiPort": 18886, "bridgeRoot": "D:/my-bot/qq-bridge-main" }
+{ "bridgeRoot": "D:/my-bot/qq-bridge-main" }
 ```
 
 日记来源也需明确配置：`QQ_DIARY_DIR` 环境变量 → config.json 的 `diaryDir` → 跳过。例如在上面的配置对象中添加 `"diaryDir": "D:/my-bot/diaries"`。未配置时返回“未配置日记目录，跳过日记导入”，其他类别仍正常导入；包内不带任何用户日记路径。
@@ -230,7 +322,7 @@ node scripts/sync-qq.mjs --dry
 node --test test/*.test.mjs
 ```
 
-通过包安装生成命令后也可运行 `dsh-memory-map`。测试使用隔离的临时记忆库。现有 33 项回归按新增 GUI/第七个工具更新相应声明断言，加上 8 项可视化、导入、服务及 CLI 测试，以及 4 项日记配置/关键词/平方根/性能测试，总共 45 项通过。
+通过包安装生成命令后也可运行 `dsh-memory-map`。测试使用隔离的临时记忆库。本版保留原有 56 项回归，新增配置默认值与白名单、非空库引导数据、异步按钮开关、配置失败和超时回退测试。
 
 本地开发安装：将本包作为目标 DSH profile 的 link 依赖，并启用同名 bundle；客户端入口已声明为 web/immediately。完全退出再打开 DSH。不要复制宿主 SDK 到包里。