@summerscar/dsh-mnemon-sync 0.1.4 → 0.1.6

package/CHANGELOG.md

@@ -0,0 +1,53 @@
+# 更新日志
+
+本项目遵循[语义化版本](https://semver.org/lang/zh-CN/)。
+
+## 0.1.5
+
+**新增**
+
+- 备份文件名带设备名：`mnemon-sync-<设备名>-<时间戳>.zip`。设备名取自 dsh-mnemon 的 `state/machine.json`，多台机器备份到同一目录也能分辨来源。
+
+**修复**
+
+- 保留策略按运行时间排序，不再按文件名字符串。加了设备名后文件名以设备开头，旧逻辑会按设备分组，可能删掉本机较新的备份而留下其他机器最旧的。
+
+## 0.1.4
+
+**修复**
+
+- 备份列表按创建时间倒序。此前用字符串比较 RFC1123 日期，跨天时会排错（`09 Nov 23:00` 排在了 `10 Nov 01:00` 前面）。现改为解析时间戳比较，同时兼容 S3 的 ISO 格式。
+
+## 0.1.3
+
+**修复**
+
+- **标签页不显示**。Source 入口改为标准 Cordis 插件形态（`inject` + `apply` + `installMemory`），并把 bundle patch 拆成两个 Entry（Host 引擎 + Source）。
+- SDK 改用 `createRequire` 同步加载，先试裸包名、失败再按 `DSH_PROFILE_DIR` 拼绝对路径 —— 修复 `link:` 安装下静态 `import` 报 `ERR_MODULE_NOT_FOUND` 的问题。
+
+## 0.1.2
+
+**变更**
+
+- 插件 meta 文案与功能对齐：标题改为「同步备份」，描述改为三组件任选 + 备份列表 + 选择性恢复。
+- README 精简，安装命令改为 npm 包名。
+
+## 0.1.1
+
+**修复**
+
+- **关键**：恢复掩码密钥时不再把掩码本身写进配置。此前 `/run` 接口接受页面草稿配置却未做掩码还原，会把 `••••••••` 当成真实密码存盘，导致配置看着正确、备份却一直 401。
+
+**新增**
+
+- 运行记录支持一键清空（只清本地日志，不动目标上的备份包）。
+
+## 0.1.0
+
+首个版本。
+
+- 三组件（记忆空间 / 项目档案 / 运行时记忆）任意组合备份
+- S3 兼容存储（手写 SigV4）与 WebDAV 两种目标
+- 定时备份：关闭 · 每小时 · 3/6/12 小时 · 每天 · 3/7 天
+- 备份列表、明细查看、选择性恢复
+- 数据库走 `node:sqlite` 的 `backup()` 在线备份，每文件 SHA-256 校验

package/README.md

@@ -1,18 +1,41 @@
+<div align="center">
+
 # dsh-mnemon-sync
 
-为 [dsh-mnemon](https://github.com/omdsh-dev/dsh-mnemon) 提供备份与恢复：把记忆组件打包上传到 S3 兼容存储或 WebDAV，需要时挑一个包恢复回来。安装后在记忆系统里多一个「同步备份」标签页。
+**为 dsh-mnemon 的记忆做备份与恢复 —— 打包到 S3 兼容存储或 WebDAV，随时挑一个包还原回来。**
+
+[![npm version](https://img.shields.io/npm/v/@summerscar/dsh-mnemon-sync?style=flat-square&color=blue)](https://www.npmjs.com/package/@summerscar/dsh-mnemon-sync)
+[![npm downloads](https://img.shields.io/npm/dm/@summerscar/dsh-mnemon-sync?style=flat-square)](https://www.npmjs.com/package/@summerscar/dsh-mnemon-sync)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![DeepSeek Harness](https://img.shields.io/badge/DeepSeek%20Harness-plugin-4B6BFB?style=flat-square)](https://github.com/deepseek-ai/deepseek-harness)
+
+[快速开始](#快速开始) · [功能](#功能) · [配置](#配置) · [常见问题](#常见问题) · [更新日志](CHANGELOG.md)
 
-## 安装
+</div>
+
+---
+
+`dsh-mnemon` 把长期记忆存在本地 SQLite 和一批 Markdown 文件里。这个插件给它们加上**异地备份**和**按需恢复**：装好后在记忆系统里多一个「同步备份」标签页。
+
+```
+记忆系统 → 同步备份
+  ├── 备份范围   记忆空间 / 项目档案 / 运行时记忆（可任选）
+  ├── 备份目标   S3 兼容存储 或 WebDAV
+  ├── 自动备份   关闭 · 每小时 · 3/6/12 小时 · 每天 · 3/7 天
+  └── 备份列表   查看明细 · 选择组件恢复
+```
+
+## 快速开始
 
 ```sh
 dsh plugin --profile web add @summerscar/dsh-mnemon-sync
 ```
 
-装完重启 DSH 生效。没有 `dsh-mnemon` 时插件仍可运行，只是不显示标签页。
+重启 DSH，打开记忆系统即可看到「同步备份」。没装 `dsh-mnemon` 时插件仍可运行，只是不显示标签页。
 
-## 能备份什么
+## 功能
 
-三个组件任意组合，默认全选：
+**三个组件，任意组合**（默认全选）
 
 | 组件 | 内容 |
 |---|---|
@@ -22,23 +45,117 @@ dsh plugin --profile web add @summerscar/dsh-mnemon-sync
 
 `MNEMON_DATA_DIR` 未设置时取 `~/.mnemon`。
 
-## 备份目标
+**两种备份目标**
 
-- **S3 兼容** — 手写 AWS Signature V4，适用于 Cloudflare R2、MinIO、Backblaze B2 等
+- **S3 兼容** — 手写 AWS Signature V4，适用于 Cloudflare R2、MinIO、Backblaze B2、阿里云 OSS 等
 - **WebDAV** — Basic 认证，自动创建远端目录
 
-凭据存在 `<MNEMON_DATA_DIR>/state/mnemon-sync.json`，权限 `0600`，不写入 DSH 配置，也不进备份包。页面只回显掩码，回传掩码表示不修改。
+**备份文件按设备区分**
+
+```
+mnemon-sync-<设备名>-2026-11-09T01-20-27.875Z.zip
+```
+
+设备名取自 dsh-mnemon 的 `state/machine.json`，多台机器备份到同一目录也能一眼分辨来源。
+
+**一致性有保证**
+
+- 数据库走 `node:sqlite` 的 `backup()` 在线备份，写入方的 WAL 不会把副本撕开
+- 每个文件记录 SHA-256，上传前自校验，恢复前再校验一次
+- 恢复默认只做预览，确认后才写盘；写数据库前先删同名 `-wal` / `-shm`，避免 SQLite 重放恢复文件里没有的事务
+
+## 配置
+
+在「同步备份」页面填好即可，配置存在 `<MNEMON_DATA_DIR>/state/mnemon-sync.json`（权限 `0600`），不写入 DSH 配置，也不会进备份包。
+
+<details>
+<summary><b>S3 / Cloudflare R2 示例</b></summary>
+
+| 字段 | 示例 |
+|---|---|
+| Endpoint | `https://<account>.r2.cloudflarestorage.com` |
+| Bucket | `my-mnemon-backup` |
+| Region | `auto` |
+| Access Key ID | 你的 R2 Access Key |
+| Secret Access Key | 你的 R2 Secret |
+| 强制 path-style | R2 和 MinIO 通常需要勾选 |
+
+</details>
+
+<details>
+<summary><b>WebDAV 示例</b></summary>
 
-## 自动备份
+| 字段 | 示例 |
+|---|---|
+| 地址 | `http://192.168.100.134:5005` |
+| 用户名 | 你的 WebDAV 账号 |
+| 密码 | 你的 WebDAV 密码 |
+| 远端目录 | `config-backup/mnemon-sync` |
+
+> 地址带不带结尾斜杠都可以，插件会归一化。
+
+</details>
+
+页面只回显掩码，回传掩码表示不修改。想换密钥就直接填新值。
+
+## 常见问题
+
+<details>
+<summary><b>装好了但看不到标签页？</b></summary>
+
+1. **重启 DSH** —— Host 侧的 Source 注册和浏览器端代码都要重启才加载
+2. 确认 `dsh-mnemon` 已安装且版本 ≥ 0.5.40
+3. 确认 `dsh.profile.bundles` 里有 `@summerscar/dsh-mnemon-sync`
+4. 强刷页面（Ctrl+Shift+R）绕开浏览器缓存
+
+</details>
+
+<details>
+<summary><b>备份报 401 Not Authorized？</b></summary>
+
+凭据问题。检查用户名密码，以及 WebDAV 服务是否真的在运行。注意有些 NAS 的 WebDAV 改配置后需要重启服务才生效。
+
+</details>
 
-关闭 · 每小时 · 每 3 / 6 / 12 小时 · 每天 · 每 3 天 · 每 7 天
+<details>
+<summary><b>为什么不用 litestream？</b></summary>
 
-## 恢复
+litestream 一个实例只盯一个数据库，v0.5 每个库只允许一个副本 —— 备份整个 `data` 目录就得为每个记忆空间养一个常驻进程。另外它接管 WAL checkpoint 并持锁，实测会让 `mnemon.db-wal` 停在非零字节，而 dsh-mnemon 自己的备份导出有这条检查，会直接报错：
 
-从备份列表查看明细，选择要恢复的组件后执行；缺少的组件会明确提示。恢复默认只做预览，确认后才写盘。
+```js
+if (existsSync(wal) && statSync(wal).size > 0)
+  throw new Error(`Memory Space ${id} is busy (...-wal is not checkpointed)`)
+```
+
+</details>
+
+<details>
+<summary><b>保留份数怎么算？</b></summary>
+
+按运行时间保留最新的 N 个，超出后删除最旧的。删除依据是插件自己的运行记录，不会去 LIST 远端目录。
+
+</details>
+
+## 开发
+
+```sh
+git clone https://github.com/summerscar/dsh-mnemon-sync.git
+cd dsh-mnemon-sync
+```
+
+| 文件 | 职责 |
+|---|---|
+| `index.js` | Host 入口：HTTP 接口、调度装配、备份引擎 |
+| `source.js` | 承载页面身份的记忆 Source（不存记忆） |
+| `snapshot.js` | 组件识别、数据库在线备份、manifest 与校验 |
+| `scheduler.js` | 定时器与运行历史 |
+| `store.js` | 设置存取（0600）与规范化 |
+| `targets.js` | S3 SigV4 / WebDAV 的上传、下载、列目录、删除 |
+| `zip.js` | 零依赖 ZIP 读写（基于 `node:zlib`） |
+| `client.js` | 浏览器端页面与标签注册 |
 
-数据库用 `node:sqlite` 的 `backup()` 在线备份，副本一致；写回前会删掉同名 `-wal` / `-shm`，避免 SQLite 重放不存在的事务。每个文件都有 SHA-256 校验。
+零外部运行时依赖。
 
 ## 许可
 
-MIT
+[MIT](LICENSE)

package/index.js

@@ -20,6 +20,7 @@
 
 import { createHash } from 'node:crypto'
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { hostname } from 'node:os'
 import { dirname, join, resolve } from 'node:path'
 
 import { SyncHistory, SyncScheduler } from './scheduler.js'
@@ -83,9 +84,44 @@ async function readJsonBody(req) {
   return JSON.parse(text)
 }
 
-/** `mnemon-sync-2026-11-09T041500Z.zip`: sorts lexicographically by time. */
-export function archiveKey(at = new Date()) {
-  return `${ARCHIVE_PREFIX}${at.toISOString().replace(/:/gu, '-')}.zip`
+/**
+ * The name this machine goes by in an archive name.
+ *
+ * Read from dsh-mnemon's own identity file (`state/machine.json`) so a backup
+ * uploaded from several machines stays tellable apart. Falls back to the
+ * hostname, then to a fixed word, so the key never ends up with an empty
+ * segment. Characters that would be awkward in a filename — slashes, spaces,
+ * anything a WebDAV path segment must escape — collapse to a single dash.
+ */
+export function deviceName(home) {
+  let label = ''
+  try {
+    const identity = JSON.parse(readFileSync(join(home, 'state', 'machine.json'), 'utf8'))
+    if (typeof identity?.label === 'string') label = identity.label
+  } catch {
+    // No identity file yet: the hostname is the same fallback dsh-mnemon uses.
+  }
+  if (label.trim() === '') {
+    try {
+      label = hostname()
+    } catch {
+      label = ''
+    }
+  }
+  const cleaned = label.trim().replace(/[^\p{L}\p{N}._-]+/gu, '-').replace(/^-+|-+$/gu, '')
+  return cleaned === '' ? 'device' : cleaned.slice(0, 60)
+}
+
+/**
+ * `mnemon-sync-<device>-2026-11-09T00-53-57.903Z.zip`
+ *
+ * The device name sits after the prefix and before the timestamp, so archives
+ * from different machines sort together by time within one device and are
+ * still obvious at a glance in a shared folder.
+ */
+export function archiveKey(at = new Date(), device = 'device') {
+  const stamp = at.toISOString().replace(/:/gu, '-')
+  return `${ARCHIVE_PREFIX}${device}-${stamp}.zip`
 }
 
 export function apply(ctx, config = {}) {
@@ -108,7 +144,7 @@ export function apply(ctx, config = {}) {
     try {
       const snapshot = await buildSnapshot(home, staging, { components: current.components })
       verifySnapshot(staging)
-      const key = archiveKey()
+      const key = archiveKey(new Date(), deviceName(home))
       const archive = createZip(collect(staging), { level: 6 })
       const uploaded = await uploadArchive(target, key, archive, { signal })
       const removed = await applyRetention(history, target, current.retention.keep, { signal })
@@ -610,11 +646,21 @@ function collect(root, prefix = '') {
  * as removed.
  */
 async function applyRetention(history, target, keep, options) {
+  // Sort by when the run happened, not by key. With a device name in the key,
+  // lexical order groups by device first, so "keep the newest N" would delete
+  // this machine's newest archive before another machine's oldest one.
   const uploaded = history.read()
     .filter((run) => run.ok && typeof run.key === 'string')
-    .map((run) => run.key)
-  const unique = [...new Set(uploaded)].sort()
-  const overflow = unique.slice(0, Math.max(0, unique.length - keep))
+    .map((run) => ({ key: run.key, at: Date.parse(run.finishedAt ?? run.startedAt ?? '') || 0 }))
+  const seen = new Set()
+  const unique = []
+  for (const entry of uploaded) {
+    if (seen.has(entry.key)) continue
+    seen.add(entry.key)
+    unique.push(entry)
+  }
+  unique.sort((left, right) => right.at - left.at)
+  const overflow = unique.slice(keep).map((entry) => entry.key)
   const removed = []
   for (const key of overflow) {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@summerscar/dsh-mnemon-sync",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Back up and restore dsh-mnemon memory components (memory spaces, project documents, runtime memory) to S3-compatible storage or WebDAV.",
   "type": "module",
   "main": "index.js",
@@ -9,7 +9,8 @@
     "./client": "./client.js",
     "./locale/*.json": "./locale/*.json",
     "./icon": "./icon.svg",
-    "./source": "./source.js"
+    "./source": "./source.js",
+    "./package.json": "./package.json"
   },
   "files": [
     "index.js",
@@ -24,19 +25,25 @@
     "locale/*.json",
     "icon.svg",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "keywords": [
+    "dsh",
     "dsh-plugin",
     "deepseek-harness",
     "deepseek-harness-plugin",
+    "cordis",
     "dsh-mnemon",
     "mnemon",
+    "agent-memory",
     "backup",
     "restore",
     "memory",
+    "sqlite",
     "webdav",
-    "s3"
+    "s3",
+    "cloudflare-r2"
   ],
   "license": "MIT",
   "engines": {
@@ -62,6 +69,25 @@
         "@deepseek-ai/dsh-client-locale",
         "dsh-mnemon/client"
       ]
+    },
+    "catalog": {
+      "category": "tool",
+      "summary": {
+        "en": "Back up and restore dsh-mnemon memory to S3-compatible storage or WebDAV, with scheduled backups and selective restore.",
+        "zh": "把 dsh-mnemon 的记忆备份到 S3 兼容存储或 WebDAV，支持定时备份与选择性恢复。"
+      },
+      "capabilities": [
+        "webServer",
+        "mnemonMemory",
+        "slots",
+        "locale"
+      ]
+    },
+    "compatibility": {
+      "dsh": ">=0.2.1-rc.1 <0.3.0-0",
+      "profiles": [
+        "web"
+      ]
     }
   },
   "repository": {
@@ -74,5 +100,6 @@
   "homepage": "https://github.com/summerscar/dsh-mnemon-sync#readme",
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "icon": "./icon.svg"
 }