dsh-memory-cloud 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dsh-memory-cloud contributors
+
+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

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# dsh-memory-cloud
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm version](https://img.shields.io/npm/v/dsh-memory-cloud.svg)](https://www.npmjs.com/package/dsh-memory-cloud)
+[![license](https://img.shields.io/npm/l/dsh-memory-cloud.svg)](./LICENSE)
+
+把当前 DSH（DeepSeek Harness）的**全部会话记忆**聚合成一幅可交互的 **3D 星云图**，并提供「神经元信号」皮肤切换。
+
+DSH 没有独立的记忆库：每一条持久记忆都是 `$DSH_HOME/sessions` 里某个会话日志中的一条已提交事件。本插件冷读所有 `session.v4.jsonl.zstd`（concatenated zstd frames 包裹的 JSONL），把每个会话折叠成一个记忆星云团，再依据 fork 血缘、共同话题、同工作区、共享工具与时间邻近计算会话之间的关联边，最后用纯 Canvas 2D 自实现的 3D 投影渲染。
+
+## 功能
+
+- **记忆聚合**：zstd 分帧解码 → 提取标题、真实工作目录、消息碎片、工具集、fork 血缘、关键词；过滤运行时上下文/技能目录/纯标点等注入文本。
+- **关联图**：TF-IDF 加权的话题余弦相似度 + 共享工具 + 同工作区 + 时间邻近 + fork 血缘，输出带 `kind`/权重/共享词的加权边；每节点与全局上限抑制"万能 hub"。
+- **两种皮肤**
+  - **星云**（默认）：不规则絮状气体云（无球核、无硬边界，参考 NASA 星系云团），团间用细电弧连接；电流靠**沿线明暗渐变**表现传递，暗区纯黑、余晖自然衰减。
+  - **神经元**：细胞体 + 递归分叉的树状树突 + 突触终扣 + 弯曲轴突，共用同一套信号波与流速。
+- **规模映射真实数据**：云团凝聚核数、光斑数、纤维/尘埃密度、记忆星数量、树突主干数与分叉深度，全部按该会话的实际碎片数/事件数归一化缩放。
+- **分级细节（LOD）**：缩放即钻取，每放大一级就多露出一层记忆——
+  | 等级 | 徽章 | 触发缩放 | 显示内容 |
+  |---|---|---|---|
+  | 0 | 全景 | < 1.5× | 云团 + 会话标题 |
+  | 1 | 星团 | ≥ 1.5× | 标题 + 记忆条数/对话数/工具数 |
+  | 2 | 记忆摘要 | ≥ 2.8× | 自动聚焦最近星团并浮现碎片摘要 + 话题关键词 |
+  | 3 | 记忆全文 | ≥ 5× | 按需拉取该会话**完整未截断**碎片（含全文标记） |
+
+  放大到 2 级以上时视角会平滑"飞入"目标星团，其余云团退到四周雾中；缩回后自动释放焦点。双击星团可直接钻到底。
+- **交互**：拖拽/单指旋转、滚轮/双指捏合缩放、悬停 tooltip、点击云团展开该会话记忆、按标题/正文/工作区搜索、点击图例聚焦工作区。
+- **移动端适配**：`viewport-fit=cover` + safe-area、横向图例、全宽底部抽屉、触摸命中放大、dpr 上限 1.25。
+- **性能**：离屏渐变精灵缓存、按颜色/深度批量绘制；电流相位由真实时钟连续推进（不量化到固定帧率），渐变采样点随链路屏幕长度自适应（约每 6px 一个色标），因此波峰是亚色标级平滑移动。降级策略优先**减少采样精度**而非降低帧率，只有在持续掉帧时才回落到 30fps；移动端 dpr 上限 1.25。
+
+## 安装
+
+已发布到 npm：**<https://www.npmjs.com/package/dsh-memory-cloud>**
+
+```bash
+# 方式一：DSH CLI
+dsh plugin --profile web add dsh-memory-cloud
+
+# 方式二：在 DSH 对话里让 agent 安装
+plugin_manager install_bundle dsh-memory-cloud
+```
+
+也可以在 **Settings → Plugins** 里安装。安装后 bundle 会在当前 profile 全局启用。
+
+本地开发时改成安装目录即可（该方式为软链接，改动即时生效）：
+
+```bash
+plugin_manager install_bundle D:\dsh-memory-cloud
+```
+
+安装成功后，从左侧栏底部的「记忆星云」按钮打开；也可直接访问：
+
+```
+http://127.0.0.1:3080/memory-cloud/
+```
+
+> 该 URL 无需 DSH Web GUI 的启动 token（插件路由自带 Host 头校验，仅允许 localhost）。
+
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-memory-cloud
+```
+
+## 结构
+
+| 文件 | 作用 |
+|---|---|
+| `index.js` | Host 半：扫描/解码会话日志、聚合记忆与关联、注册 `/memory-cloud/*` HTTP 路由 |
+| `client.js` | Client 半：`sidebar.footer.action` 入口按钮 + `shell.overlay` 全屏层 + locale |
+| `nebula.js` | 3D 投影、两种皮肤渲染、信号波、交互与命中测试 |
+| `nebula.html` / `nebula.css` | 页面骨架与响应式深色样式 |
+| `cordis.patch.yml` | Loader patch，插入插件行并声明配置 |
+| `locale/*.json` | Plugin Manager 显示用的中英文标题/描述 |
+| `icon.svg` / `assets/icon.svg` | 插件图标 |
+
+## 配置
+
+`cordis.patch.yml` 中可调整：
+
+```yaml
+sessionsDir: !!js dshHomePath('sessions')  # 会话日志目录
+maxSessions: 400        # 最多聚合多少个会话
+maxFragments: 28        # 每个会话抽样的记忆碎片上限
+maxFragmentChars: 220   # 单条碎片字数上限
+trustedHosts: []        # 额外允许访问插件路由的 Host
+```
+
+## 数据接口
+
+`GET /memory-cloud/api/memories` —— 聚合摘要（每会话最多抽样 `maxFragments` 条碎片）：
+
+```json
+{
+  "generatedAt": 0,
+  "sessions": [{ "id", "title", "workspaceLabel", "counts", "fragments", "topics", "tools", "parentSession", "createdAt", "updatedAt" }],
+  "workspaces": [{ "id", "label", "sessions" }],
+  "relations": [{ "source", "target", "weight", "kind", "kinds", "shared" }],
+  "stats": { "sessions", "relations", "fragments", "events", "user", "assistant", "tools", "turns", "oldest", "newest" }
+}
+```
+
+`GET /memory-cloud/api/session/:id` —— 单个会话的**完整**碎片（LOD 3 按需拉取，按文件 mtime 缓存；未知 id 返回 404）：
+
+```json
+{ "id", "title", "workspaceLabel", "createdAt", "updatedAt", "counts", "fragments": [{ "kind", "text", "truncated", "time", "seq" }] }
+```
+
+插件对会话日志与 profile **只读**，不写入任何状态；唯一的持久化是浏览器 `localStorage` 里的皮肤选择。
+
+## 许可
+
+MIT

package/assets/icon.svg

@@ -0,0 +1,32 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <defs>
+    <radialGradient id="core" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#fff7d6"/>
+      <stop offset="35%" stop-color="#ffb45e"/>
+      <stop offset="70%" stop-color="#b455d8" stop-opacity="0.75"/>
+      <stop offset="100%" stop-color="#3b2a80" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="glow" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#7c5cff" stop-opacity="0.55"/>
+      <stop offset="100%" stop-color="#7c5cff" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+  <rect width="64" height="64" rx="14" fill="#0d1030"/>
+  <circle cx="32" cy="32" r="27" fill="url(#glow)"/>
+  <g fill="none" stroke-linecap="round">
+    <path d="M11 36c8-14 22-20 40-13" stroke="#66d9ff" stroke-width="2.4" opacity="0.85"/>
+    <path d="M14 43c10-9 23-11 36-4" stroke="#b98bff" stroke-width="2.2" opacity="0.8"/>
+    <path d="M17 25c9-8 20-9 31-3" stroke="#ff9bc6" stroke-width="1.8" opacity="0.7"/>
+  </g>
+  <circle cx="32" cy="32" r="12" fill="url(#core)"/>
+  <g fill="#ffffff">
+    <circle cx="14" cy="35" r="1.5" opacity="0.9"/>
+    <circle cx="50" cy="23" r="1.7" opacity="0.95"/>
+    <circle cx="20" cy="18" r="1.1" opacity="0.8"/>
+    <circle cx="47" cy="45" r="1.3" opacity="0.85"/>
+    <circle cx="27" cy="50" r="1" opacity="0.75"/>
+    <circle cx="38" cy="14" r="1" opacity="0.7"/>
+    <circle cx="9" cy="47" r="0.9" opacity="0.7"/>
+    <circle cx="55" cy="35" r="1" opacity="0.8"/>
+  </g>
+</svg>

package/client.js

@@ -0,0 +1,169 @@
+/**
+ * Client half of the Memory Nebula bundle.
+ *
+ * Two additive slot registrations share one tiny observable store:
+ *   - `sidebar.footer.action`: a button beside Settings that opens the nebula.
+ *   - `shell.overlay`: the full-frame layer that hosts the nebula iframe.
+ *
+ * The iframe loads a same-origin page served by the Host half. The nebula is
+ * dark-only by design, so this half only bridges open/close and Escape — it
+ * never forwards the host's light/dark theme. No Harness Client UI package is
+ * imported as a module.
+ */
+window.__ModuleLoader__.load({
+  id: 'dsh-memory-cloud',
+  factory(require) {
+    const React = require('react')
+    const h = React.createElement
+    const { useEffect, useSyncExternalStore } = React
+
+    const NS = 'dsh-memory-cloud'
+    const DICTS = {
+      en: { title: 'Memory nebula', hint: 'Explore all DSH memories as a 3D nebula' },
+      zh: { title: '记忆星云', hint: '以 3D 星云图探索全部 DSH 记忆' },
+    }
+
+    // Locale-aware translation for the sidebar button. The nebula iframe page
+    // carries its own fixed copy; here we follow the host's active locale.
+    let localeApi = null
+    function useT() {
+      const snap = useSyncExternalStore(
+        fn => localeApi ? localeApi.subscribe(fn) : () => {},
+        () => localeApi ? localeApi.getSnapshot().revision : 0,
+        () => 0,
+      )
+      void snap
+      return key => {
+        const active = localeApi ? localeApi.getLocale().active : 'en'
+        const dict = DICTS[active] || DICTS.en
+        return dict[key] || DICTS.en[key] || key
+      }
+    }
+
+    // --- shared open/close store -------------------------------------------
+    let open = false
+    const listeners = new Set()
+    const store = {
+      subscribe(fn) { listeners.add(fn); return () => listeners.delete(fn) },
+      getSnapshot() { return open },
+      getServerSnapshot() { return false },
+      set(value) {
+        if (value === open) return
+        open = value
+        for (const fn of listeners) fn()
+      },
+    }
+
+    // --- nebula glyph ------------------------------------------------------
+    function NebulaGlyph(size) {
+      return h('svg', {
+        width: size, height: size, viewBox: '0 0 24 24', fill: 'none',
+        'aria-hidden': true, style: { display: 'block' },
+      },
+        h('circle', { cx: 12, cy: 12, r: 3.2, fill: '#ffd591' }),
+        h('circle', { cx: 12, cy: 12, r: 6.5, stroke: 'currentColor', strokeWidth: 1, opacity: 0.55 }),
+        h('path', { d: 'M3 12c3-5 7-7 12-6', stroke: 'currentColor', strokeWidth: 1.3, strokeLinecap: 'round', opacity: 0.9 }),
+        h('path', { d: 'M4 15c4-3 9-3 15-1', stroke: 'currentColor', strokeWidth: 1.2, strokeLinecap: 'round', opacity: 0.8 }),
+        h('path', { d: 'M6 8c4-3 8-3 12-1', stroke: 'currentColor', strokeWidth: 1, strokeLinecap: 'round', opacity: 0.7 }),
+        h('circle', { cx: 4, cy: 13, r: 0.9, fill: 'currentColor' }),
+        h('circle', { cx: 20, cy: 9, r: 1, fill: 'currentColor' }),
+        h('circle', { cx: 18, cy: 18, r: 0.9, fill: 'currentColor' }),
+        h('circle', { cx: 8, cy: 5, r: 0.8, fill: 'currentColor' }),
+      )
+    }
+
+    // --- footer action button ---------------------------------------------
+    function NebulaFooterButton(props) {
+      const wide = props && props.wide
+      const active = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot)
+      const t = useT()
+      return h('button', {
+        type: 'button',
+        onClick: () => store.set(!active),
+        title: t('hint'),
+        'aria-label': t('title'),
+        'aria-pressed': active,
+        style: {
+          display: 'flex', alignItems: 'center', gap: 8, width: '100%',
+          padding: '7px 8px', border: 0, borderRadius: 8, cursor: 'pointer',
+          background: active ? 'var(--dsw-alias-bg-layer-2)' : 'transparent',
+          color: active ? 'var(--dsw-alias-brand-primary)' : 'var(--dsw-alias-label-secondary)',
+          font: 'inherit', fontSize: 13, textAlign: 'left',
+        },
+        onMouseEnter: e => { if (!active) e.currentTarget.style.background = 'var(--dsw-alias-bg-layer-1)' },
+        onMouseLeave: e => { if (!active) e.currentTarget.style.background = 'transparent' },
+      },
+        h('span', { style: { flex: '0 0 auto', display: 'grid', placeItems: 'center', width: 18, height: 18 } }, NebulaGlyph(18)),
+        wide ? h('span', { style: { whiteSpace: 'nowrap', overflow: 'hidden', textOverflow: 'ellipsis' } }, t('title')) : null,
+      )
+    }
+
+    // --- full-frame overlay ------------------------------------------------
+    function NebulaOverlay() {
+      const isOpen = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot)
+
+      useEffect(() => {
+        if (!isOpen) return undefined
+        const onMessage = event => {
+          if (event.origin !== location.origin || event.data?.source !== 'dsh-memory-cloud') return
+          if (event.data.type === 'close') store.set(false)
+        }
+        const onKeyDown = event => { if (event.key === 'Escape') store.set(false) }
+        window.addEventListener('message', onMessage)
+        window.addEventListener('keydown', onKeyDown)
+        return () => {
+          window.removeEventListener('message', onMessage)
+          window.removeEventListener('keydown', onKeyDown)
+        }
+      }, [isOpen])
+
+      if (!isOpen) return null
+      return h('div', {
+        style: {
+          position: 'fixed', inset: 0, zIndex: 1200, pointerEvents: 'auto',
+          // Dark-only surface: never inherit a light host background.
+          background: '#070a1c',
+        },
+        role: 'dialog', 'aria-modal': true, 'aria-label': '记忆星云',
+      },
+        h('iframe', {
+          id: 'dsh-memory-cloud-frame',
+          title: '记忆星云 · Memory nebula',
+          src: '/memory-cloud/',
+          style: { display: 'block', width: '100%', height: '100%', border: 0 },
+        }),
+      )
+    }
+
+    return {
+      inject: ['slots', 'locale'],
+      apply(ctx) {
+        localeApi = ctx.locale
+        const disposers = []
+        for (const [id, dict] of Object.entries(DICTS)) {
+          try { disposers.push(ctx.locale.register(NS, id, dict)) } catch (_) { /* namespace already owned on re-apply */ }
+        }
+        const label = () => {
+          const active = ctx.locale.getLocale().active
+          return (DICTS[active] || DICTS.en).title
+        }
+        disposers.push(ctx.slots.inject('sidebar.footer.action', () => ctx.slots.register({
+          name: 'sidebar.footer.action',
+          id: 'dsh-memory-cloud',
+          order: 60,
+          label,
+        }, NebulaFooterButton)))
+        disposers.push(ctx.slots.inject('shell.overlay', () => ctx.slots.register({
+          name: 'shell.overlay',
+          id: 'dsh-memory-cloud',
+          order: 100,
+          label,
+        }, NebulaOverlay)))
+        ctx.effect(() => () => {
+          for (const dispose of disposers) { try { dispose() } catch (_) {} }
+          localeApi = null
+        }, 'memory-cloud: ui registrations')
+      },
+    }
+  },
+})

package/cordis.patch.yml

@@ -0,0 +1,12 @@
+- insert:
+    - id: dsh-memory-cloud
+      name: 'dsh-memory-cloud'
+      config:
+        # All durable DSH memories live in the session logs under $DSH_HOME.
+        sessionsDir: !!js dshHomePath('sessions')
+        # Upper bounds keep the nebula responsive on profiles with long histories.
+        maxSessions: 400
+        maxFragments: 28
+        maxFragmentChars: 220
+        # Extra authorities the Host-header check accepts (host or host:port).
+        trustedHosts: []

package/icon.svg

@@ -0,0 +1,32 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">
+  <defs>
+    <radialGradient id="core" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#fff7d6"/>
+      <stop offset="35%" stop-color="#ffb45e"/>
+      <stop offset="70%" stop-color="#b455d8" stop-opacity="0.75"/>
+      <stop offset="100%" stop-color="#3b2a80" stop-opacity="0"/>
+    </radialGradient>
+    <radialGradient id="glow" cx="50%" cy="50%" r="50%">
+      <stop offset="0%" stop-color="#7c5cff" stop-opacity="0.55"/>
+      <stop offset="100%" stop-color="#7c5cff" stop-opacity="0"/>
+    </radialGradient>
+  </defs>
+  <rect width="64" height="64" rx="14" fill="#0d1030"/>
+  <circle cx="32" cy="32" r="27" fill="url(#glow)"/>
+  <g fill="none" stroke-linecap="round">
+    <path d="M11 36c8-14 22-20 40-13" stroke="#66d9ff" stroke-width="2.4" opacity="0.85"/>
+    <path d="M14 43c10-9 23-11 36-4" stroke="#b98bff" stroke-width="2.2" opacity="0.8"/>
+    <path d="M17 25c9-8 20-9 31-3" stroke="#ff9bc6" stroke-width="1.8" opacity="0.7"/>
+  </g>
+  <circle cx="32" cy="32" r="12" fill="url(#core)"/>
+  <g fill="#ffffff">
+    <circle cx="14" cy="35" r="1.5" opacity="0.9"/>
+    <circle cx="50" cy="23" r="1.7" opacity="0.95"/>
+    <circle cx="20" cy="18" r="1.1" opacity="0.8"/>
+    <circle cx="47" cy="45" r="1.3" opacity="0.85"/>
+    <circle cx="27" cy="50" r="1" opacity="0.75"/>
+    <circle cx="38" cy="14" r="1" opacity="0.7"/>
+    <circle cx="9" cy="47" r="0.9" opacity="0.7"/>
+    <circle cx="55" cy="35" r="1" opacity="0.8"/>
+  </g>
+</svg>