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

package/README.md

@@ -2,7 +2,7 @@
 
 DSH 插件的本地记忆引擎，带神经网络可视化。它让 agent 保存、召回和管理跨会话记忆，也能把你已有的记忆文件导进来。
 
-当前版本：0.7.0-beta.2b。Node ≥22，零新增依赖。恢复应用内点击神经元的只读详情卡片，Canvas 与离线 HTML 继续共用唯一绘制实现。
+当前版本：0.7.0-beta.4。Node ≥22，零新增依赖。新增中心角色卡、确定性球壳布局和可配置慢速自转；保留记忆管理和详情卡片，Canvas 与离线 HTML 继续共用唯一绘制实现。
 
 ## 0.7.0 分步交付
 
@@ -11,14 +11,15 @@ DSH 插件的本地记忆引擎，带神经网络可视化。它让 agent 保存
 | 第 1 步 · 已完成 | 宿主路由、共享图谱计算、同源 iframe | 原独立端口无监听，按钮能打开图，JSON 接口返回当前记忆 |
 | 第 2 步 · 已完成 | React 内直接绘制 Canvas | 浮层无 iframe；旋转、缩放、选中可用，关闭后动画停止 |
 | 渲染合并 · 已完成 | canvas.js 是唯一绘制源码，界面构建与离线 HTML 共用 | 画面不变，构建幂等，未构建的源码改动会使测试失败 |
-| 点击回归 · 本版完成 | 恢复右侧只读详情卡片 | 可见字段、切换、关闭、高亮和复制；长正文可滚动 |
-| 第 3 步 · 待交付 | 记忆列表、搜索、编辑、删除、导出 | 可浏览、修改和删除；写操作先备份 |
+| 点击回归 · 已完成 | 恢复右侧只读详情卡片 | 可见字段、切换、关闭、高亮和复制；长正文可滚动 |
+| 第 3 步 · 已完成 | 记忆列表、搜索、编辑、删除、导出和清空 | 分页、筛选、确认与错误提示；写操作先备份 |
+| 中心角色卡 · 本版完成 | 固定角色核心、分层球壳、慢速自转 | 角色卡全文与复制；拖拽暂停，松手 2 秒恢复；缺省退回原布局 |
 | 引导小修 · 已完成 | 空库和手动回看共用三步卡片 | 编号步骤、复制提示词、刷新和关闭卡片可用 |
 
 - [x] 引导回看：右上角「?」、中央卡片、复制提示词、知道了/Esc 关闭。
 - [x] 按钮开关：hideButton、showGuideOnEmpty；配置请求失败时保留按钮并警告。
 
-界面已改为应用内 canvas 渲染，不再使用 iframe；`/memory-engine/` 整页 HTML 保留给 CLI 与浏览器直接访问。七个 agent 工具继续可用，记忆管理留给后续独立交付。
+界面使用应用内 canvas 渲染；`/memory-engine/` 整页 HTML 保留给 CLI 与浏览器直接访问。七个 agent 工具继续可用，记忆管理在应用内的「记忆」「设置」页完成。
 
 ## 支持的 DSH 版本
 
@@ -42,11 +43,15 @@ peerDependencies 已放宽为 >=0.1.0-rc.8 <0.3.0 并标为 optional——宿主
 
 安装并启用插件后，完全退出 DSH 再打开。进入任意会话，头部第一行会出现 **🧠 记忆图谱** 按钮。
 
-点击后全屏显示图谱，右上角 **关闭 ×** 退出。每次打开都会读取当前记忆库，在内存中计算当前图谱，不写入离线 HTML。
+点击后全屏显示图谱，顶部有 **图谱 / 记忆 / 设置** 三个 tab，右上角 **关闭 ×** 退出。每次打开或从其他 tab 返回图谱都会读取当前记忆库，在内存中计算当前图谱，不写入离线 HTML。离开图谱 tab 时停止 Canvas 动画。
+
+**记忆 tab** 按正文或标题搜索（250ms 防抖），可筛选知识、印象、对话、事件、日记，按最近、最老、快忘了或连接最多排序。每页 50 条，底部显示过滤后的总数和「加载更多」。点一条展开全文，再点「编辑」修改正文、分类、重要度或相关人；保存失败保留草稿并显示服务端错误，取消不发送写请求。删除必须再次确认。
+
+**设置 tab** 显示数据目录、条数、文件大小，支持复制路径和下载全部记忆。导出文件结构为 `{ ok: true, data: { total, items } }`，保留原始条目的全部字段。清空必须输入大写 `DELETE`，输入错误不会发请求；成功后回到空库引导。界面不重复提供导入，仍使用 `memory_import` 工具。
 
 点击神经元，右侧滑入约 350px 的只读详情卡片，显示分类、标题、重要度、留存、连接数、本地日期和正文；有情绪标签时才显示情绪行。空标题取正文前 20 字，长标题换行、长正文在卡片内滚动。点另一个节点只更新内容，不重复滑入。
 
-卡片的 **在图里高亮它** 调用现有激活效果；**复制正文** 复制全文，成功后显示「已复制 ✓」，1.8 秒后恢复。点图上空白处或卡片 × 关闭详情，图谱继续显示。关闭整个浮层或刷新图谱会清空选中状态。本版不提供编辑、删除或记忆列表。
+卡片的 **在图里高亮它** 调用现有激活效果；**复制正文** 复制全文，成功后显示「已复制 ✓」，1.8 秒后恢复。点图上空白处或卡片 × 关闭详情，图谱继续显示。关闭整个浮层、切换 tab 或刷新图谱会清空选中状态；编辑和删除在「记忆」tab 完成。
 
 **记忆库为空时，默认自动弹出中央引导卡片**；已经有记忆时，点右上角、关闭按钮左侧的 **?** 随时回看。同一张卡片显示三步说明、提示词和数据目录；「复制这段提示词」成功后显示「已复制 ✓」，「刷新图谱」重新载入当前记忆。
 
@@ -69,6 +74,24 @@ peerDependencies 已放宽为 >=0.1.0-rc.8 <0.3.0 并标为 optional——宿主
 
 拖拽旋转、滚轮缩放（0.3～4.5），点击神经元激活并查看详情。详情直接使用节点已有数据，不请求新接口，也不写入记忆。客户端使用相对路径 `/memory-engine/api/map` 获取数据，由 React 管理 Canvas；关闭浮层或卸载组件会停止动画、取消请求并清理监听。桌面端经 DSH 的原生协议转发，无需知道宿主端口。旧 `config.json` 中的 `uiPort` 不再使用，可保留或删除。还可以运行 `node <插件目录>/scripts/render-map.mjs --open` 生成并打开离线图谱，整页 HTML 仍可点击查看原文。
 
+### 中心角色卡与自转
+
+在现有 `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。
@@ -77,19 +100,29 @@ peerDependencies 已放宽为 >=0.1.0-rc.8 <0.3.0 并标为 optional——宿主
 
 `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` 发布前重新构建。记忆管理面板仍留给后续阶段。
+`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/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 }`，不暴露其他配置 |
+| 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、时间、强化次数或触发相似合并。
 
-JSON 成功返回 `{ "ok": true, "data": ... }`，失败返回 `{ "ok": false, "error": "说明" }`。接口仅接受本机 Host，严格限制路径，拒绝路径穿越；本阶段只开放 GET，其他方法返回 405。只读接口不接收请求体，已声明超过 1MB 的请求体返回 413，其余非空或分块请求体直接拒绝，不在内存中收集。写入接口和对应的 JSON 解析、备份操作在第 3 步加入。
+管理写操作统一先调用 `MemoryStore.backup()`，再调用已有 `write()` 临时文件加 rename 原子落盘。`memories.json.bak-<毫秒时间戳>` 操作备份保留最新五份，同毫秒时自动加序号。备份失败不写入，原子替换失败保留原文件；同步任务的 `bak-sync-*` 备份保留原有策略。切回图谱重新取数即可看到编辑或删除的结果。
 
 也可以让 agent 调用 `memory_map()`，生成可双击、离线打开的单文件 HTML：