npm - @xiaoyuyu6420/dsh-backup - Versions diffs - 0.5.2 → 0.6.0 - Mend

@xiaoyuyu6420/dsh-backup 0.5.2 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,6 +1,11 @@
 # dsh-backup
 [![dsh-plugin](https://img.shields.io/badge/ecosystem-dsh--plugin-8b5cf6)](https://github.com/topics/dsh-plugin)
+[![npm](https://img.shields.io/npm/v/@xiaoyuyu6420/dsh-backup)](https://www.npmjs.com/package/@xiaoyuyu6420/dsh-backup)
+[![Publish to npm](https://github.com/xiaoyuyu6420/dsh-backup/actions/workflows/publish.yml/badge.svg)](https://github.com/xiaoyuyu6420/dsh-backup/actions/workflows/publish.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+English | [简体中文](README.zh.md)
 One-command backup **and restore** for DeepSeek Harness user data — sessions,
 settings, credentials, skills, and plugin config under `~/.dsh`, excluding
@@ -14,9 +19,10 @@ macOS, Linux, and Windows.
 - **`/backup list`** — list existing backups (name + size) and auto-backup status
 - **`/backup verify [prefix|all]`** — validate archive checksums (default: the newest)
 - **`/backup restore <prefix|latest> [--dry-run]`** — restore `~/.dsh` from an archive
-- **`/backup auto <N>|off|status`** — auto-backup every N hours (1–720; keeps 3 copies below 24h, 7 otherwise; persisted across restarts)
+- **`/backup auto <N>|off|status`** — auto-backup every N hours (1–720; retains 3 copies below 24h, 7 otherwise, unless `config.keep` overrides; persisted across restarts)
 - **`/backup --keep N`** — override the rotation count (default 7)
-- **`/backup github status|sync`** — GitHub sync status / push now
+- **`/backup github status|sync|repo <address|off>`** — GitHub sync status / push now / set the sync repository
+- **`/backup delete|rm <prefix|latest>`** — delete a backup and its checksum sidecar
 - **`backup_dsh` tool** — same capability for the model (`mode=backup|list|verify|restore|auto`)
 ## GitHub sync
@@ -70,13 +76,13 @@ Plugin `config` in the active cordis profile:
   name: 'dsh-backup'
   config:
     destination: '~/Backups/dsh'   # default ~/Desktop/dsh-backups
-    keep: 10                       # default rotation count
+    keep: 10                       # manual rotation count (default 7); when set, also the auto-backup retention — auto keeps 3 copies below 24h, 7 otherwise by default
     exclude:                       # extra tar --exclude patterns
       - '*cache*'
     githubRepo: 'name/dsh-backups' # optional GitHub sync (see below)
 ```
-Auto-backup state lives in `<destination>/auto.json` and resumes after restart.
+Auto-backup state lives in `<destination>/auto.json` and resumes after restart — the next run is scheduled from the last auto-backup time, never reset by the restart.
 ## Security note
@@ -93,11 +99,24 @@ does not apply to host-owned storage.
 ## Install
 ```sh
-dsh plugin --profile web add dsh-backup
+dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
+# or from git:
+dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
 ```
-Then restart `dsh web` (plugin discovery is cached per process) and run `/backup`,
-or open Settings → Plugins → Backup.
+> ⚠️ The npm package name is the **scoped** `@xiaoyuyu6420/dsh-backup`. The
+> unscoped `dsh-backup` on npm is an unrelated third-party package — don't
+> install it.
+## Quickstart
+Your first backup is about 30 seconds away:
+1. Install the plugin — `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup`
+2. Restart `dsh web` — plugin discovery is cached per process.
+3. Run `/backup` — the archive and its sha256 sidecar land in `~/Desktop/dsh-backups/`.
+Prefer clicking? The same flow lives in Settings → Plugins → Backup.
 ## Requirements
@@ -106,6 +125,12 @@ or open Settings → Plugins → Backup.
   and fall back to an in-process hash on Windows)
 - DSH `0.1.0-rc.6` or compatible
+## Troubleshooting
+- **Plugin fails to load with `client api: method "backupPanel/remove" conflicts with its namespace service`** — you are on v0.5.0, whose delete-endpoint method name collided with a reserved name in the DSH client (issues [#2](https://github.com/xiaoyuyu6420/dsh-backup/issues/2), [#5](https://github.com/xiaoyuyu6420/dsh-backup/issues/5)). v0.5.1 renamed the method to `removeEntry`; upgrade with `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup@latest` and restart `dsh web`.
+- **Which `tar` on Windows?** Either one works — Windows ships bsdtar in System32, and Git Bash provides GNU tar. Checksums prefer `sha256sum`/`shasum` when present and fall back to an in-process hash, so `/backup verify` works in both shells.
+- **Installed the wrong package** — the npm package is the **scoped** `@xiaoyuyu6420/dsh-backup`; the unscoped `dsh-backup` is an unrelated third-party package. Check your profile's plugin list and reinstall with the scoped name.
 ## Development
 Zero runtime dependencies — the host plugin is `lib/index.js`. The browser half
@@ -118,6 +143,15 @@ node scripts/smoke.mjs          # host smoke suite (real temp dir, mocked DSH se
 node scripts/smoke-client.mjs   # client bundle: handshake, schemas, tab registration, SSR
 ```
+## Acknowledgements
+- [@beastrobin](https://github.com/beastrobin) — the reserved-method-name root
+  cause analysis in #1 that directly led to the v0.5.1 fix
+- [@mlosun](https://github.com/mlosun) — the thorough reproduction and root
+  cause report in #2
+- [@Choi-Peng](https://github.com/Choi-Peng) — triage help pointing affected
+  users to the fix in #5
 ## License
 MIT

package/README.zh.md CHANGED Viewed

@@ -1,6 +1,11 @@
 # dsh-backup
 [![dsh-plugin](https://img.shields.io/badge/ecosystem-dsh--plugin-8b5cf6)](https://github.com/topics/dsh-plugin)
+[![npm](https://img.shields.io/npm/v/@xiaoyuyu6420/dsh-backup)](https://www.npmjs.com/package/@xiaoyuyu6420/dsh-backup)
+[![Publish to npm](https://github.com/xiaoyuyu6420/dsh-backup/actions/workflows/publish.yml/badge.svg)](https://github.com/xiaoyuyu6420/dsh-backup/actions/workflows/publish.yml)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[English](README.md) | 简体中文
 一键备份**与恢复** DeepSeek Harness 用户数据——`~/.dsh` 下的会话、设置、凭据、
 技能与插件配置（排除可重装的 node_modules），自动生成 sha256 校验和、完整性
@@ -12,9 +17,10 @@
 - **`/backup list`** —— 列出已有备份（名称 + 大小）与自动备份状态
 - **`/backup verify [前缀|all]`** —— 校验归档完整性（缺省校验最新一份）
 - **`/backup restore <前缀|latest> [--dry-run]`** —— 从归档恢复 `~/.dsh`
-- **`/backup auto <N小时>|off|status`** —— 每 N 小时自动备份（1~720；<24h 保留 3 份，否则 7 份；状态持久化，重启续跑）
+- **`/backup auto <N小时>|off|status`** —— 每 N 小时自动备份（1~720；保留份数默认 <24h 3 份、否则 7 份，config.keep 可覆盖；状态持久化，重启续跑）
 - **`/backup --keep N`** —— 覆盖轮换保留份数（默认 7）
-- **`/backup github status|sync`** —— GitHub 同步状态 / 立即推送
+- **`/backup github status|sync|repo <地址|off>`** —— GitHub 同步状态 / 立即推送 / 设置同步仓库
+- **`/backup delete|rm <前缀|latest>`** —— 删除指定备份（归档 + 校验边车）
 - **`backup_dsh` 工具** —— 模型可调用同一能力（`mode=backup|list|verify|restore|auto`）
 ## GitHub 同步
@@ -64,13 +70,13 @@ credential 文件（不进进程参数）。推送为 `HEAD:main --force-with-le
   name: 'dsh-backup'
   config:
     destination: '~/Backups/dsh'   # 默认 ~/Desktop/dsh-backups
-    keep: 10                       # 默认轮换保留份数
+    keep: 10                       # 手动备份轮换份数（默认 7）；配置后同时作为自动备份保留份数（未配置时 auto 默认 <24h 3 份 / 否则 7 份）
     exclude:                       # 额外的 tar --exclude 模式
       - '*cache*'
     githubRepo: '账号/dsh-backups' # 可选 GitHub 同步（见下文）
 ```
-自动备份状态保存在 `<destination>/auto.json`，重启后续跑。
+自动备份状态保存在 `<destination>/auto.json`，重启后按上次自动执行时间推算下次触发（不重置节奏）。
 ## 安全说明
@@ -85,11 +91,23 @@ credential 文件（不进进程参数）。推送为 `HEAD:main --force-with-le
 ## 安装
 ```sh
-dsh plugin --profile web add dsh-backup
+dsh plugin --profile web add @xiaoyuyu6420/dsh-backup
+# 或从 git 安装：
+dsh plugin --profile web add github:xiaoyuyu6420/dsh-backup
 ```
-然后重启 `dsh web`（插件发现按进程缓存），输入 `/backup` 或打开
-Settings → Plugins → 备份。
+> ⚠️ npm 包名是 **scoped** 的 `@xiaoyuyu6420/dsh-backup`。npm 上不带 scope
+> 的 `dsh-backup` 是无关的第三方包，请勿安装。
+## 快速上手
+约 30 秒拿到第一个备份：
+1. 安装插件 —— `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup`
+2. 重启 `dsh web` —— 插件发现按进程缓存。
+3. 跑 `/backup` —— 归档连同 sha256 校验文件落到 `~/Desktop/dsh-backups/`。
+更喜欢点鼠标？同一套流程在 Settings → Plugins → 备份 标签页。
 ## 依赖
@@ -98,6 +116,12 @@ Settings → Plugins → 备份。
   Windows 上回退进程内哈希）
 - DSH `0.1.0-rc.6` 或兼容版本
+## 故障排查
+- **插件加载失败，报 `client api: method "backupPanel/remove" conflicts with its namespace service`** —— 你装的是 v0.5.0：删除接口的方法名撞上了 DSH 客户端的保留方法名（见 [#2](https://github.com/xiaoyuyu6420/dsh-backup/issues/2)、[#5](https://github.com/xiaoyuyu6420/dsh-backup/issues/5)）。v0.5.1 已将方法改名 `removeEntry` 修复；执行 `dsh plugin --profile web add @xiaoyuyu6420/dsh-backup@latest` 升级后重启 `dsh web` 即可。
+- **Windows 上用哪个 `tar`？** 都可以——Windows 自带 System32 里的 bsdtar，Git Bash 里则是 GNU tar。校验和优先用 `sha256sum`/`shasum`，缺失时自动回退进程内哈希，两种 shell 下 `/backup verify` 都能正常工作。
+- **装错了包** —— npm 包名是 **scoped** 的 `@xiaoyuyu6420/dsh-backup`；不带 scope 的 `dsh-backup` 是无关的第三方包。检查 profile 的插件列表，改用 scoped 名重装。
 ## 开发
 运行时零依赖——宿主插件就是 `lib/index.js`。浏览器半边源码在 `src/`，
@@ -110,6 +134,12 @@ node scripts/smoke.mjs          # 宿主冒烟（真实临时目录 + 模拟 DSH
 node scripts/smoke-client.mjs   # 客户端 bundle：握手/schema/标签页注册/SSR
 ```
+## 致谢
+- [@beastrobin](https://github.com/beastrobin) —— #1 中对保留方法名的根因分析，直接促成 v0.5.1 修复
+- [@mlosun](https://github.com/mlosun) —— #2 中详尽的复现与根因报告
+- [@Choi-Peng](https://github.com/Choi-Peng) —— #5 中协助把受影响用户指引到修复版本
 ## 许可证
 MIT

package/lib/client.js CHANGED Viewed

@@ -330,5 +330,5 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
   max-height: 10em;
   overflow: auto;
 }
-`;var jn="settings.backupPanel",Kf="dsh-backup",Bf=["slots","locale","remote"],Wf=x.object({destination:x.string(),dshHome:x.string(),keepDefault:x.number().int(),autoHours:x.number().int(),lastAuto:x.string().nullable(),backups:x.array(x.object({name:x.string(),size:x.number().int().nullable()}))}),Xf=x.object({ok:x.boolean(),summary:x.string(),path:x.string(),sha:x.string(),stale:x.number().int(),keep:x.number().int()}),qf=x.object({ok:x.boolean(),summary:x.string(),results:x.array(x.object({name:x.string(),ok:x.boolean(),note:x.string()}))}),Hf=x.object({ok:x.boolean(),dryRun:x.boolean(),summary:x.string(),archive:x.string().nullable().optional(),files:x.number().int().nullable().optional(),aside:x.string().nullable().optional(),snapshotPath:x.string().nullable().optional(),sample:x.array(x.string()).optional()}),Yf=x.object({ok:x.boolean(),hours:x.number().int(),summary:x.string()}),Qf=x.object({repoRaw:x.string().nullable(),repo:x.string().nullable(),tokenSet:x.boolean(),syncDir:x.string(),lastPush:x.string().nullable(),lastError:x.string().nullable()}),eg=x.object({ok:x.boolean(),summary:x.string(),pushed:x.boolean(),tooBig:x.array(x.string())}),tg=x.object({ok:x.boolean(),summary:x.string()}),rg=x.object({ok:x.boolean(),repo:x.string().nullable(),summary:x.string()}),ng={name:"keep",wire:"keep",source:"json",codec:{mode:"strict",typeSymbol:"dsh-backup/types#keep",schema:x.number().int().positive().optional()},acceptsUndefined:!0},Nu={name:"selector",wire:"selector",source:"json",codec:{mode:"strict",typeSymbol:"dsh-backup/types#selector",schema:x.string().optional()},acceptsUndefined:!0},ig={name:"dryRun",wire:"dryRun",source:"json",codec:{mode:"strict",typeSymbol:"dsh-backup/types#dryRun",schema:x.boolean().optional()},acceptsUndefined:!0},og={name:"hours",wire:"hours",source:"json",codec:{mode:"strict",typeSymbol:"dsh-backup/types#hours",schema:x.number().int().min(0).max(720)},acceptsUndefined:!0},ag={name:"repo",wire:"repo",source:"json",codec:{mode:"strict",typeSymbol:"dsh-backup/types#repo",schema:x.string().optional()},acceptsUndefined:!0};function le(t,r,i,o){return Object.freeze({id:`dsh-backup#backupPanel/${t}`,service:"backupPanel",namespace:"backupPanel",method:t,invocation:Object.freeze({kind:"direct"}),parameters:Object.freeze(r.map(e=>Object.freeze({...e,codec:Object.freeze(e.codec)}))),...o?{cancellation:Object.freeze({parameter:"signal"})}:{},result:Object.freeze({mode:"strict",typeSymbol:`dsh-backup/types#${t}Result`,schema:i})})}var Ld=Object.freeze({package:"dsh-backup",descriptors:Object.freeze([le("status",[],Wf,!1),le("backup",[ng],Xf,!0),le("verify",[Nu],qf,!0),le("restore",[Nu,ig],Hf,!0),le("setAuto",[og],Yf,!1),le("githubStatus",[],Qf,!1),le("githubSyncNow",[],eg,!0),le("removeEntry",[Nu],tg,!0),le("setGithubRepo",[ag],rg,!1)])});function de(t){if(!t.ok){let r=t.error;throw new Error(r&&r.message?`${r.code}: ${r.message}`:"backupPanel \u8C03\u7528\u5931\u8D25")}return t.value}async function cg(t){t.effect(()=>t.locale.register(jn,{zh:Ed,en:Ad}),"dsh-backup: dictionaries"),t.effect(()=>Rd(),"dsh-backup: stylesheet"),await t.remote.$mount(Ld),t.inject(["remote.backupPanel"],r=>{let i=r.locale.bind(jn),o=()=>r.remote.backupPanel,e={status:async()=>de(await o().status()),backup:async n=>de(await o().backup(n)),verify:async n=>de(await o().verify(n)),restore:async(n,a)=>de(await o().restore(n,a)),setAuto:async n=>de(await o().setAuto(n)),githubStatus:async()=>de(await o().githubStatus()),githubSyncNow:async()=>de(await o().githubSyncNow()),removeEntry:async n=>de(await o().removeEntry(n)),setGithubRepo:async n=>de(await o().setGithubRepo(n))};r.slots.inject("settings.plugins.tab",()=>r.slots.register({name:"settings.plugins.tab",id:"backup",order:35,label:()=>i("tab"),locale:jn,inject:()=>({panel:e})},Td))})}
+`;var jn="settings.backupPanel",Kf="dsh-backup",Bf=["slots","locale","remote"],Wf=x.object({destination:x.string(),dshHome:x.string(),keepDefault:x.number().int(),autoHours:x.number().int(),lastAuto:x.string().nullable(),backups:x.array(x.object({name:x.string(),size:x.number().int().nullable()}))}),Xf=x.object({ok:x.boolean(),summary:x.string(),path:x.string(),sha:x.string(),stale:x.number().int(),keep:x.number().int()}),qf=x.object({ok:x.boolean(),summary:x.string(),results:x.array(x.object({name:x.string(),ok:x.boolean(),note:x.string()}))}),Hf=x.object({ok:x.boolean(),dryRun:x.boolean(),summary:x.string(),archive:x.string().nullable().optional(),files:x.number().int().nullable().optional(),aside:x.string().nullable().optional(),snapshotPath:x.string().nullable().optional(),sample:x.array(x.string()).optional()}),Yf=x.object({ok:x.boolean(),hours:x.number().int(),summary:x.string()}),Qf=x.object({repoRaw:x.string().nullable(),repo:x.string().nullable(),tokenSet:x.boolean(),syncDir:x.string(),lastPush:x.string().nullable(),lastError:x.string().nullable()}),eg=x.object({ok:x.boolean(),summary:x.string(),pushed:x.boolean(),tooBig:x.array(x.string())}),tg=x.object({ok:x.boolean(),summary:x.string()}),rg=x.object({ok:x.boolean(),repo:x.string().nullable(),summary:x.string()}),ng={name:"keep",wire:"keep",source:"json",codec:{mode:"strict",typeSymbol:"dsh-backup/types#keep",schema:x.number().int().positive().optional()},acceptsUndefined:!0},Nu={name:"selector",wire:"selector",source:"json",codec:{mode:"strict",typeSymbol:"dsh-backup/types#selector",schema:x.string().optional()},acceptsUndefined:!0},ig={name:"dryRun",wire:"dryRun",source:"json",codec:{mode:"strict",typeSymbol:"dsh-backup/types#dryRun",schema:x.boolean().optional()},acceptsUndefined:!0},og={name:"hours",wire:"hours",source:"json",codec:{mode:"strict",typeSymbol:"dsh-backup/types#hours",schema:x.number().int().min(0).max(720)},acceptsUndefined:!0},ag={name:"repo",wire:"repo",source:"json",codec:{mode:"strict",typeSymbol:"dsh-backup/types#repo",schema:x.string().optional()},acceptsUndefined:!0};function le(t,r,i,o){return Object.freeze({id:`dsh-backup#backupPanel/${t}`,service:"backupPanel",namespace:"backupPanel",method:t,invocation:Object.freeze({kind:"direct"}),parameters:Object.freeze(r.map(e=>Object.freeze({...e,codec:Object.freeze(e.codec)}))),...o?{cancellation:Object.freeze({parameter:"signal"})}:{},result:Object.freeze({mode:"strict",typeSymbol:`dsh-backup/types#${t}Result`,schema:i})})}var Ld=Object.freeze({package:"dsh-backup",descriptors:Object.freeze([le("status",[],Wf,!1),le("backup",[ng],Xf,!0),le("verify",[Nu],qf,!0),le("restore",[Nu,ig],Hf,!0),le("setAuto",[og],Yf,!1),le("githubStatus",[],Qf,!1),le("githubSyncNow",[],eg,!0),le("removeEntry",[Nu],tg,!0),le("setGithubRepo",[ag],rg,!1)])});function de(t){if(!t.ok){let r=t.error;throw new Error(r&&r.message?`${r.code}: ${r.message}`:"backupPanel \u8C03\u7528\u5931\u8D25")}return t.value}async function cg(t){t.effect(()=>t.locale.register(jn,{zh:Ed,en:Ad}),"dsh-backup: dictionaries"),t.effect(()=>Rd(),"dsh-backup: stylesheet"),t.effect(await t.remote.$mount(Ld),"dsh-backup: remote contribution"),t.inject(["remote.backupPanel"],r=>{let i=r.locale.bind(jn),o=()=>r.remote.backupPanel,e={status:async()=>de(await o().status()),backup:async n=>de(await o().backup(n)),verify:async n=>de(await o().verify(n)),restore:async(n,a)=>de(await o().restore(n,a)),setAuto:async n=>de(await o().setAuto(n)),githubStatus:async()=>de(await o().githubStatus()),githubSyncNow:async()=>de(await o().githubSyncNow()),removeEntry:async n=>de(await o().removeEntry(n)),setGithubRepo:async n=>de(await o().setGithubRepo(n))};r.slots.inject("settings.plugins.tab",()=>r.slots.register({name:"settings.plugins.tab",id:"backup",order:35,label:()=>i("tab"),locale:jn,inject:()=>({panel:e})},Td))})}
 return module.exports; } });

package/lib/index.js CHANGED Viewed

@@ -9,8 +9,11 @@
  * - `/backup list`                         列出已有备份（含大小）+ 自动备份状态
  * - `/backup verify [前缀|all]`            校验备份完整性（缺省校验最新一份）
  * - `/backup restore <前缀|latest> [--dry-run]`  恢复（先校验 + 自动快照当前数据）
- * - `/backup auto <N小时>|off|status`      定时自动备份（1~720；<24h 保留 3 份，否则 7 份）
- * - `/backup github status|sync`           GitHub 同步状态 / 立即同步
+ * - `/backup auto <N小时>|off|status`      定时自动备份（1~720；保留份数由 config.keep
+ *                                          支配，未配置时 <24h 3 份、否则 7 份；重启按
+ *                                          上次执行时间推算下次，不重置节奏）
+ * - `/backup github status|sync|repo <地址|off>`  GitHub 同步状态 / 立即同步 / 设置仓库
+ * - `/backup delete|rm <前缀|latest>`      删除备份（归档 + 校验边车）
  * - `/backup --keep N`                     覆盖本次保留份数
  * - `backup_dsh` 模型工具：mode=backup|list|verify|restore|auto
  * - cordis.yml `config`：destination / keep / exclude / githubRepo（见 README）
@@ -30,7 +33,7 @@
  */
 import { createHash } from 'node:crypto';
 import { createReadStream } from 'node:fs';
-import { mkdir, copyFile, readdir, readFile, stat as fsStat, writeFile } from 'node:fs/promises';
+import { mkdir, open, copyFile, readdir, readFile, rename, stat as fsStat, unlink, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { defineTool } from '@deepseek-ai/dsh-tools';
 import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
@@ -38,7 +41,7 @@ import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
 export const name = 'dsh-backup';
 export const inject = ['subprocess', 'commands', 'timer', 'tools'];
-/** Windows 下的删除/移动没有 POSIX rm/mv 可用，统一走 cmd.exe 内置命令。 */
+/** Windows 无 POSIX chmod 语义（用户目录 ACL 默认私有）。 */
 const IS_WIN = process.platform === 'win32';
 /** sha256 回退路径（node:fs 读取 + node:crypto）的内存上限。 */
 const HASH_MAX_BYTES = 256 * 1024 * 1024;
@@ -144,6 +147,25 @@ class BackupPanelService extends TypertRemoteService {
 export function apply(ctx, pluginConfig) {
   // ---------- 工具函数 ----------
+  /**
+   * 读取 subprocess 收集的输出流。dsh-subprocess 的收集契约：输出超过
+   * maxBytes（8192）时内存窗口只保留尾部（readFrom 返回 lossy: true），
+   * 完整输出 spill 到 spillPath——restore 的 `tar -tvzf` 校验清单必须看
+   * 全量，否则大归档的校验可被清单前段的恶意条目绕过（8KB 尾窗看不到）。
+   */
+  async function collectOutput(col) {
+    const read = col?.readFrom(0);
+    if (!read) return '';
+    if (read.lossy && read.spillPath) {
+      try {
+        return await readFile(read.spillPath, 'utf8');
+      } catch {
+        // spill 文件不可读时降级为内存尾窗文本（截断，但比失败好）
+      }
+    }
+    return read.text ?? '';
+  }
   async function spawnRun(argv, cwd, signal) {
     const proc = ctx.subprocess.spawn({
       argv,
@@ -157,8 +179,18 @@ export function apply(ctx, pluginConfig) {
       },
     });
     const outcome = await proc.done;
-    const out = proc.collected.stdout?.readFrom(0).text ?? '';
-    const err = proc.collected.stderr?.readFrom(0).text ?? '';
+    const out = await collectOutput(proc.collected?.stdout);
+    const err = await collectOutput(proc.collected?.stderr);
+    // 取消优先于一切结果分类：用户取消不是"命令失败"。进程已正常退出后、
+    // 结果返回前的毫秒窗口内 abort 同样报"操作已取消"——刻意取舍：真取消
+    // 绝不得误报成功，窗口期误报取消（R7 的反向错误）比误报成功危害小。
+    if (signal?.aborted) {
+      throw new Error('操作已取消');
+    }
+    // loose 检查：smoke 桩与部分平台下 signal 字段可能为 undefined。
+    if (outcome.signal != null) {
+      throw new Error(`命令被终止（signal=${outcome.signal}）`);
+    }
     if (outcome.exitCode !== 0) {
       throw new Error(`命令失败 exit=${outcome.exitCode}: ${err || out}`);
     }
@@ -199,29 +231,24 @@ export function apply(ctx, pluginConfig) {
   }
   /**
-   * 删除 dir 下的文件。Windows 走 cmd del：cmd 内置命令不接受正斜杠路径、
-   * 经 argv 转义的内嵌引号也会被破坏，因此统一以 dir 为 cwd、用纯文件名调用。
+   * 删除 dir 下的文件。纯 Node fs.unlink（零 shell）：文件名来自备份目录
+   * 内容，拼接进 cmd/rm 命令行会构成命令注入面（Windows 下 cmd 的
+   * `del /f /q ${names}` 可被 `dsh-x & calc &x.tar.gz` 之类文件名利用）。
    */
   async function removeFiles(names, dir, signal) {
     if (!names.length) return;
-    if (IS_WIN) {
-      const cmd = await ctx.subprocess.resolveExecutable('cmd');
-      await spawnRun([cmd, '/d', '/c', `del /f /q ${names.join(' ')}`], dir, signal);
-    } else {
-      const rm = await ctx.subprocess.resolveExecutable('rm');
-      await spawnRun([rm, '-f', ...names.map((n) => `${dir}/${n}`)], dir, signal);
-    }
+    if (signal?.aborted) throw new Error('操作已取消');
+    await Promise.all(names.map((n) => unlink(`${dir}/${n}`).catch((err) => {
+      // 目标已不存在等价 rm -f 的静默成功；其余错误照常抛出
+      if (err && err.code === 'ENOENT') return;
+      throw err;
+    })));
   }
   /** 把 dir 下的文件/目录改名为同目录下的另一个名字（恢复时挪开现有数据）。 */
   async function renameBeside(dir, srcName, dstName, signal) {
-    if (IS_WIN) {
-      const cmd = await ctx.subprocess.resolveExecutable('cmd');
-      await spawnRun([cmd, '/d', '/c', `move /y ${srcName} ${dstName}`], dir, signal);
-    } else {
-      const mv = await ctx.subprocess.resolveExecutable('mv');
-      await spawnRun([mv, `${dir}/${srcName}`, `${dir}/${dstName}`], dir, signal);
-    }
+    if (signal?.aborted) throw new Error('操作已取消');
+    await rename(`${dir}/${srcName}`, `${dir}/${dstName}`);
   }
   async function listBackups() {
@@ -230,7 +257,7 @@ export function apply(ctx, pluginConfig) {
     try {
       dirents = await readdir(root, { withFileTypes: true });
     } catch {
-      // 备份目录尚不存在（首次使用）——视为空列表而非错误
+      // 备份目录缺失或不可读时视为空列表（首次使用前 / EACCES 容错）
       return [];
     }
     const backups = [];
@@ -240,6 +267,7 @@ export function apply(ctx, pluginConfig) {
       try {
         size = (await fsStat(`${root}/${d.name}`)).size;
       } catch {
+        // 归档在列表与 stat 之间被删除（轮换/删除竞态）——大小显示为未知而非报错
         size = undefined;
       }
       backups.push({ name: d.name, size });
@@ -373,6 +401,7 @@ export function apply(ctx, pluginConfig) {
       try {
         await spawnRun([git, 'init', '-b', 'main'], syncDir, signal);
       } catch {
+        // git 版本不支持 -b 时回退 init + branch -M
         await spawnRun([git, 'init'], syncDir, signal);
         await spawnRun([git, 'branch', '-M', 'main'], syncDir, signal);
       }
@@ -384,20 +413,33 @@ export function apply(ctx, pluginConfig) {
     if (cfg.token) {
       // 正斜杠路径：msys git 会把反斜杠绝对路径当相对路径解析（怪名化）
       const creds = `${syncDir}/.git-credentials`;
-      await writeOwned(creds, `https://x-access-token:${cfg.token}@github.com\n`);
-      if (!IS_WIN) {
-        const chmod = await ctx.subprocess.resolveExecutable('chmod');
-        await spawnRun([chmod, '600', creds], syncDir, signal);
+      // 独占创建（0600）：凭据文件不留 umask 默认权限窗口；已存在时普通
+      // 打开后显式 chmod 收紧——open 的 mode 参数只作用于新建文件，对已
+      // 存在文件（如 0644 残留）不生效。
+      let fh;
+      try {
+        fh = await open(creds, 'wx', 0o600);
+      } catch (e) {
+        if (!(e && e.code === 'EEXIST')) throw e;
+        fh = await open(creds, 'w', 0o600);
+        if (!IS_WIN) await fh.chmod(0o600);
+      }
+      try {
+        await fh.writeFile(`https://x-access-token:${cfg.token}@github.com\n`, 'utf8');
+      } finally {
+        await fh.close();
       }
       await spawnRun([git, 'config', 'credential.helper', `store --file=${creds}`], syncDir, signal);
     }
     // token 文件绝不能进仓库：git add -A 会把它当普通文件提交
     await writeOwned(`${syncDir}/.gitignore`, '.git-credentials\n');
-    // 镜像工作树：只保留 .gitignore 与当前备份集（归档+边车），其余一切
-    // 文件（旧副本、凭据残留、误入杂物）清理——git add -A 因此只会收录
-    // 归档；轮换删除与误入文件一并同步移除。
+    // 镜像工作树：只保留 .gitignore、凭据文件（.git-credentials，token
+    // 配置时在 keep 集内保留）与当前备份集（归档+边车），其余文件
+    // （旧副本、误入杂物）清理——git add -A 因此只会收录归档；轮换
+    // 删除与误入文件一并同步移除。
     const keep = new Set(['.gitignore']);
+    if (cfg.token) keep.add('.git-credentials');
     for (const b of await listBackups()) {
       keep.add(b.name);
       keep.add(`${b.name}.sha256`);
@@ -406,6 +448,7 @@ export function apply(ctx, pluginConfig) {
     try {
       entries = await readdir(syncDir, { withFileTypes: true });
     } catch {
+      // 同步目录刚创建或不可读时视为空
       entries = [];
     }
     const stale = entries
@@ -464,6 +507,7 @@ export function apply(ctx, pluginConfig) {
       });
       createReadStream(abs).on('error', () => { res.destroy(); }).pipe(res);
     } catch {
+      // 任何读取/解析失败按 404 处理（下载是尽力而为的附件通道）
       if (!res.headersSent) res.writeHead(404);
       res.end();
     }
@@ -506,6 +550,49 @@ export function apply(ctx, pluginConfig) {
     return { ok: true, name: picked.name, summary: `已删除备份: ${picked.name}` };
   }
+  /**
+   * 解析 `tar -tvzf` 单行输出，返回 { type, name }；布局不匹配返回 null。
+   * 兼容三种 verbose 布局（locale 无关锚定，不依赖英文月份缩写）：
+   * 1. GNU tar：mode owner size YYYY-MM-DD 时间|年份 name——以 YYYY-MM-DD
+   *    字段为锚，name 起点 = 该字段 + 2（跳过 date 与 time/年份）。
+   * 2. bsdtar：mode uid gid size 月 日 时间 name（中文 locale 月份形如
+   *    `8月`，英文 `Aug`）——以最后一个 HH:MM 字段为锚，name 起点 = 其后 1。
+   * 3. bsdtar 跨年条目无时间字段（月 日 年份）——以最后一个 4 位数字为锚
+   *    （年份；size 恰为 4 位数字时年份更靠右仍正确），name 起点 = 其后 1。
+   * name 保留含空格路径并去掉目录尾部的斜杠。
+   * 已知边界：POSIX 文件名恰为 HH:MM 形态（如 `12:30`）会被误取为时间锚
+   * （Windows 文件名禁 `:`，故 Windows 不受影响）——极端误取，保守接受。
+   */
+  function parseTarEntry(line) {
+    const f = line.trim().split(/\s+/);
+    if (f.length < 6) return null;
+    let nameIdx = -1;
+    for (let i = 1; i < f.length; i++) {
+      if (/^\d{4}-\d{2}-\d{2}$/.test(f[i])) {
+        nameIdx = i + 2;
+        break;
+      }
+    }
+    if (nameIdx < 0) {
+      for (let i = f.length - 1; i >= 1; i--) {
+        if (/^\d{1,2}:\d{2}$/.test(f[i])) {
+          nameIdx = i + 1;
+          break;
+        }
+      }
+    }
+    if (nameIdx < 0) {
+      for (let i = f.length - 1; i >= 1; i--) {
+        if (/^\d{4}$/.test(f[i])) {
+          nameIdx = i + 1;
+          break;
+        }
+      }
+    }
+    if (nameIdx < 0 || nameIdx >= f.length) return null;
+    return { type: f[0][0], name: f.slice(nameIdx).join(' ').replace(/\/$/, '') };
+  }
   async function restoreArchive(selector, dryRun, signal) {
     const { home, dshHome, root } = paths();
     const picked = await pickArchive(selector);
@@ -519,12 +606,33 @@ export function apply(ctx, pluginConfig) {
     const parent = dshHome.slice(0, -(base.length + 1)) || '/';
     const tar = await ctx.subprocess.resolveExecutable('tar');
     // 同 doBackup：cwd 为备份目录，-f 用纯文件名，规避 Windows GNU tar 的盘符冒号问题。
-    const listed = await spawnRun([tar, '-tzf', picked.name], root, signal);
-    const entries = listed.out.split('\n').map((s) => s.trim()).filter(Boolean);
-    // tar 路径穿越防护：归档由本插件生成，条目必须都在备份根目录之下。
-    const bad = entries.filter((e) => e !== base && !e.startsWith(`${base}/`));
+    const listed = await spawnRun([tar, '-tvzf', picked.name], root, signal);
+    // tar 路径穿越防护：逐行解析 -tvzf 输出（双布局，见 parseTarEntry），
+    // 条目必须是普通文件/目录、相对路径且位于备份根目录之下；任一违规
+    // 即整体拒绝，恢复绝不触碰备份根之外的文件。
+    const entries = [];
+    const bad = [];
+    for (const line of listed.out.split('\n')) {
+      const s = line.trim();
+      if (!s) continue;
+      const parsed = parseTarEntry(s);
+      // 反斜杠归一化后再做全部路径检查：`.dsh/..\..\escape.txt` 与
+      // `/` 分隔的 `..` 段同样拒绝（Windows 风格路径变体）
+      const name = parsed ? parsed.name.replace(/\\/g, '/').replace(/\/$/, '') : null;
+      if (
+        !parsed || !name
+        || (parsed.type !== '-' && parsed.type !== 'd')
+        || name.startsWith('/') || /^[A-Za-z]:/.test(name)
+        || name.split('/').includes('..')
+        || (name !== base && !name.startsWith(`${base}/`))
+      ) {
+        bad.push(parsed ? name : s);
+      } else {
+        entries.push(name);
+      }
+    }
     if (bad.length) {
-      throw new Error(`归档包含 "${base}/" 之外的条目（疑似被替换）：${bad.slice(0, 3).join(', ')}，恢复已中止`);
+      throw new Error(`归档包含不安全条目（拒绝恢复）：${bad.slice(0, 3).join(', ')}，恢复已中止`);
     }
     if (dryRun) return { archive, files: entries.length, sample: entries.slice(0, 12), aside: null, snapshotPath: null, dryRun: true };
@@ -536,7 +644,10 @@ export function apply(ctx, pluginConfig) {
     try {
       await fsStat(dshHome);
       current = true;
-    } catch {
+    } catch (err) {
+      // dshHome 不存在（ENOENT）视为首次恢复、无现有数据可移开；其他 stat
+      // 失败（如 EACCES）中止恢复，不跳过 aside 直接覆盖现有数据
+      if (!err || err.code !== 'ENOENT') throw err;
       current = false;
     }
     if (current) {
@@ -552,11 +663,18 @@ export function apply(ctx, pluginConfig) {
   let autoDispose = null;
   let autoHours = 0;
   let lastAuto = null;
+  let lastAutoAt = null;
   let githubState = { repo: null, lastPush: null, lastError: null };
+  /** 自动备份的保留份数：config.keep 支配（未配置时 <24h 3 份、否则 7 份）。 */
+  function autoKeep() {
+    const k = Number(pluginConfig?.keep);
+    return Number.isFinite(k) && k > 0 ? Math.floor(k) : (autoHours >= 24 ? 7 : 3);
+  }
   async function saveAutoState() {
     const { root } = paths();
-    await writeOwned(`${root}/auto.json`, `${JSON.stringify({ hours: autoHours, github: githubState })}\n`);
+    await writeOwned(`${root}/auto.json`, `${JSON.stringify({ hours: autoHours, lastAutoAt, github: githubState })}\n`);
   }
   async function loadAutoState() {
@@ -571,24 +689,54 @@ export function apply(ctx, pluginConfig) {
           lastError: typeof parsed.github.lastError === 'string' ? parsed.github.lastError : null,
         };
       }
+      lastAutoAt = typeof parsed?.lastAutoAt === 'string' && !Number.isNaN(Date.parse(parsed.lastAutoAt))
+        ? parsed.lastAutoAt
+        : null;
       return Number.isFinite(h) && h >= 1 && h <= 720 ? Math.floor(h) : 0;
-    } catch {
+    } catch (err) {
+      console.warn(`[dsh-backup] auto.json 无法读取，自动备份计划已重置: ${String(err && err.message ? err.message : err)}`);
       return 0;
     }
   }
+  /** 下次自动备份触发时间（毫秒）：上次执行 + 周期；无锚点从当前时间起算。 */
+  function nextAutoAt() {
+    const cycle = autoHours * 3600 * 1000;
+    // 非法/缺失 lastAutoAt 按 0 处理：从当前时间起算，避免 NaN 传染延迟计算
+    const anchor = (Number(new Date(lastAutoAt)) || 0) + cycle;
+    return Math.max(anchor, Date.now());
+  }
   function autoSummary() {
     if (!autoDispose) return '自动备份未开启（/backup auto <N小时> 开启）';
-    const next = new Date(Date.now() + autoHours * 3600 * 1000).toLocaleString();
+    // 绝对节奏：下次 = 上次执行 + 周期；错过（重启间隔超周期）则按现在显示，调度会立即补跑。
+    const next = new Date(nextAutoAt()).toLocaleString();
     return `自动备份已开启：每 ${autoHours} 小时一次（已持久化，重启续跑），下次约 ${next}${lastAuto ? `；上次自动备份: ${lastAuto}` : ''}`;
   }
+  /** 链式 timeout 调度：每次触发后按上次执行时间推算下一次，重启后节奏不重置。 */
+  function scheduleAuto() {
+    // 关闭竞态保护：auto off 时 in-flight 备份完成后的续链会以 autoHours=0
+    // 算出 delay=0，形成无限备份循环——关闭后绝不续链。
+    if (autoHours <= 0) return;
+    const delay = nextAutoAt() - Date.now();
+    autoDispose = ctx.timeout(async () => {
+      await runAutoBackup();
+      scheduleAuto();
+    }, delay);
+  }
   async function runAutoBackup() {
     try {
-      const r = await doBackup(autoHours >= 24 ? 7 : 3);
+      const r = await doBackup(autoKeep());
       lastAuto = r.path.split('/').pop();
+      lastAutoAt = new Date().toISOString();
+      await saveAutoState();
       console.log(`[dsh-backup] 自动备份完成: ${r.path} (sha ${r.sha.slice(0, 12)}…)`);
     } catch (err) {
+      // 失败也推进内存锚点：否则下次 delay=0 立即重试形成热循环。不落盘
+      // （失败路径 auto.json 大概率也写失败），下次成功备份会持久化。
+      lastAutoAt = new Date().toISOString();
       console.error(`[dsh-backup] 自动备份失败: ${String(err && err.message ? err.message : err)}`);
     }
   }
@@ -596,7 +744,8 @@ export function apply(ctx, pluginConfig) {
   async function setAuto(h) {
     if (autoDispose) { autoDispose(); autoDispose = null; }
     autoHours = h;
-    if (h > 0) autoDispose = ctx.interval(runAutoBackup, h * 3600 * 1000);
+    lastAutoAt = null;
+    if (h > 0) scheduleAuto();
     await saveAutoState();
   }
@@ -703,7 +852,7 @@ export function apply(ctx, pluginConfig) {
             return { kind: 'error', text: '小时数需为 1~720 之间的数字（如 /backup auto 12）' };
           }
           await setAuto(h);
-          return { kind: 'success', text: `✅ 自动备份已开启：每 ${h} 小时执行一次（保留 ${h >= 24 ? 7 : 3} 份，已持久化）。\n${autoSummary()}` };
+          return { kind: 'success', text: `✅ 自动备份已开启：每 ${h} 小时执行一次（保留 ${autoKeep()} 份，已持久化）。\n${autoSummary()}` };
         }
         let keep;
@@ -930,12 +1079,12 @@ export function apply(ctx, pluginConfig) {
     }), 'dsh-backup: download route');
   });
-  // 启动时恢复持久化的定时备份计划（不阻塞插件装配）。
+  // 启动时恢复持久化的定时备份计划（不阻塞插件装配）；错过则 delay=0 立即补跑。
   void (async () => {
     const h = await loadAutoState();
     if (h > 0 && !autoDispose) {
       autoHours = h;
-      autoDispose = ctx.interval(runAutoBackup, h * 3600 * 1000);
+      scheduleAuto();
     }
   })();
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@xiaoyuyu6420/dsh-backup",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Backup, restore, download and GitHub-sync DeepSeek Harness user data (~/.dsh): /backup, scheduled auto-backup that survives restarts, sha256 checksums, integrity verify, rotation and a visual Settings panel. Cross-platform (macOS/Linux/Windows). 一键备份与恢复 DSH 数据：定时自动备份、完整性校验、下载与 GitHub 同步，附 Settings 可视面板。",
   "type": "module",
   "main": "lib/index.js",