dsh-memory-engine 0.6.0 → 0.7.0-beta.2b

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 阿木
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,7 +2,23 @@
 
 DSH 插件的本地记忆引擎，带神经网络可视化。它让 agent 保存、召回和管理跨会话记忆，也能把你已有的记忆文件导进来。
 
-当前版本：0.5.2。Node ≥22，零新增依赖；DSH 宿主提供 `@deepseek-ai/dsh-tools@0.2.1-rc.3`。本机安装已启用，无需重复安装。
+当前版本：0.7.0-beta.2b。Node ≥22，零新增依赖。恢复应用内点击神经元的只读详情卡片，Canvas 与离线 HTML 继续共用唯一绘制实现。
+
+## 0.7.0 分步交付
+
+| 阶段 | 内容 | 独立验收 |
+| --- | --- | --- |
+| 第 1 步 · 已完成 | 宿主路由、共享图谱计算、同源 iframe | 原独立端口无监听，按钮能打开图，JSON 接口返回当前记忆 |
+| 第 2 步 · 已完成 | React 内直接绘制 Canvas | 浮层无 iframe；旋转、缩放、选中可用，关闭后动画停止 |
+| 渲染合并 · 已完成 | canvas.js 是唯一绘制源码，界面构建与离线 HTML 共用 | 画面不变，构建幂等，未构建的源码改动会使测试失败 |
+| 点击回归 · 本版完成 | 恢复右侧只读详情卡片 | 可见字段、切换、关闭、高亮和复制；长正文可滚动 |
+| 第 3 步 · 待交付 | 记忆列表、搜索、编辑、删除、导出 | 可浏览、修改和删除；写操作先备份 |
+| 引导小修 · 已完成 | 空库和手动回看共用三步卡片 | 编号步骤、复制提示词、刷新和关闭卡片可用 |
+
+- [x] 引导回看：右上角「?」、中央卡片、复制提示词、知道了/Esc 关闭。
+- [x] 按钮开关：hideButton、showGuideOnEmpty；配置请求失败时保留按钮并警告。
+
+界面已改为应用内 canvas 渲染，不再使用 iframe；`/memory-engine/` 整页 HTML 保留给 CLI 与浏览器直接访问。七个 agent 工具继续可用，记忆管理留给后续独立交付。
 
 ## 支持的 DSH 版本
 
@@ -20,15 +36,60 @@ 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** 退出。每次打开都会读取当前记忆库重新生成；大库会先显示“正在生成”。
+点击后全屏显示图谱，右上角 **关闭 ×** 退出。每次打开都会读取当前记忆库，在内存中计算当前图谱，不写入离线 HTML。
+
+点击神经元，右侧滑入约 350px 的只读详情卡片，显示分类、标题、重要度、留存、连接数、本地日期和正文；有情绪标签时才显示情绪行。空标题取正文前 20 字，长标题换行、长正文在卡片内滚动。点另一个节点只更新内容，不重复滑入。
+
+卡片的 **在图里高亮它** 调用现有激活效果；**复制正文** 复制全文，成功后显示「已复制 ✓」，1.8 秒后恢复。点图上空白处或卡片 × 关闭详情，图谱继续显示。关闭整个浮层或刷新图谱会清空选中状态。本版不提供编辑、删除或记忆列表。
+
+**记忆库为空时，默认自动弹出中央引导卡片**；已经有记忆时，点右上角、关闭按钮左侧的 **?** 随时回看。同一张卡片显示三步说明、提示词和数据目录；「复制这段提示词」成功后显示「已复制 ✓」，「刷新图谱」重新载入当前记忆。
+
+点「知道了」关闭引导，图谱和已打开的详情仍在。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 仍可点击查看原文。
+
+### 客户端构建
+
+`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 可直接双击打开。
 
-拖拽旋转、滚轮缩放、点击神经元看原文。服务默认监听 `127.0.0.1:18886`；端口被占用时记忆工具仍可用，可以运行 `node <插件目录>/scripts/render-map.mjs --open`，或直接打开 `~/.dsh/memory-engine/starmap.html`。修改端口需要同时修改 config.json 的 uiPort 和 client.js 的 VIEW_URL，见后文。
+`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 }`；nodes 已含原布局计算结果 |
+| GET | `/memory-engine/api/stats` | 记忆总数、分类、衰减状态及存储位置 |
+| GET | `/memory-engine/api/onboard` | `{ empty, prompt, steps, dataDir }`，空库和手动帮助共用 |
+| GET | `/memory-engine/api/config` | 仅 `{ hideButton, showGuideOnEmpty }`，不暴露其他配置 |
+
+JSON 成功返回 `{ "ok": true, "data": ... }`，失败返回 `{ "ok": false, "error": "说明" }`。接口仅接受本机 Host，严格限制路径，拒绝路径穿越；本阶段只开放 GET，其他方法返回 405。只读接口不接收请求体，已声明超过 1MB 的请求体返回 413，其余非空或分块请求体直接拒绝，不在内存中收集。写入接口和对应的 JSON 解析、备份操作在第 3 步加入。
 
 也可以让 agent 调用 `memory_map()`，生成可双击、离线打开的单文件 HTML：
 
@@ -164,9 +225,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 +237,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 +249,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 +264,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,8 +289,12 @@ 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 到包里。
 
 文件写入仍继承原 MemoryStore 的单进程同步事务方式；多个独立宿主同时修改同一文件不提供跨进程锁。历史验收和本次截图、反向验证 HTML、文件变更清单位于相邻的 dsh-memory-engine-deliveries 目录。
+
+## 许可
+
+MIT。可以商用、可以修改、可以再发布，保留版权声明即可（见 [LICENSE](./LICENSE)）。