dsh-home-sync 0.2.2 → 0.2.4
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.
- package/README.md +7 -5
- package/README.zh-CN.md +95 -46
- package/lib/sync.js +5 -1
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
|
|
1
|
+
# dsh-home-sync
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/dsh-home-sync)
|
|
4
4
|
[](https://github.com/OverDustD7/dsh-home-sync)
|
|
5
5
|
|
|
6
|
-
English | [
|
|
6
|
+
English | [简体中文](README.zh-CN.md)
|
|
7
7
|
|
|
8
8
|
Git-based sync for DSH configuration and Mnemon memory plugin data, with automatic two-way sync, cross-device migration, initialization backups, conflict detection, and a web UI.
|
|
9
9
|
|
|
@@ -44,13 +44,13 @@ A `link:` installation reads that source directory directly: restart DSH web aft
|
|
|
44
44
|
Build a tarball and copy it to the target machine:
|
|
45
45
|
|
|
46
46
|
```powershell
|
|
47
|
-
npm pack --
|
|
47
|
+
npm pack --pack-destination dist
|
|
48
48
|
```
|
|
49
49
|
|
|
50
50
|
On the target, run the following from the directory containing the archive:
|
|
51
51
|
|
|
52
52
|
```powershell
|
|
53
|
-
dsh plugin --profile web add ./dsh-home-sync-0.2.
|
|
53
|
+
dsh plugin --profile web add ./dsh-home-sync-0.2.3.tgz
|
|
54
54
|
```
|
|
55
55
|
|
|
56
56
|
If the package manager cannot install a local tarball, extract it into a permanent directory and install the extracted `package` subdirectory using `link:`. Do not use a temporary extraction directory as a permanent link target.
|
|
@@ -116,7 +116,7 @@ Configuration is stored at `<DSH_HOME>/dsh-home-sync.json`.
|
|
|
116
116
|
| `autoPullOnStartup` | Pull when the plugin starts |
|
|
117
117
|
| `autoSync` | Run periodic full synchronization |
|
|
118
118
|
| `syncIntervalSeconds` | Integer from 15 to 86,400 |
|
|
119
|
-
| `commitMessage` | Commit message, 1
|
|
119
|
+
| `commitMessage` | Commit message, 1–1,000 characters |
|
|
120
120
|
| `sshBatch` | Use SSH batch mode |
|
|
121
121
|
|
|
122
122
|
The legacy `autoSyncOnStartup` setting migrates to `autoSync`. If both are present, `autoSync` takes precedence.
|
|
@@ -132,6 +132,8 @@ npm run check
|
|
|
132
132
|
npm test
|
|
133
133
|
```
|
|
134
134
|
|
|
135
|
+
Save documentation as UTF-8. When editing it with scripts, specify UTF-8 for both reading and writing; do not rely on a system code page. `npm run check:docs` validates the README text and language links, and runs as part of `npm run check` and the normal npm packaging lifecycle. Avoid `--ignore-scripts` when packing, because it skips this check.
|
|
136
|
+
|
|
135
137
|
Tests use system temporary directories, synthetic files, and local Git remotes. They do not access your real DSH home or accounts. Test repositories are retained in temporary directories for diagnosis.
|
|
136
138
|
|
|
137
139
|
Browser tests use a separate temporary Chrome/Edge profile and are skipped if no supported browser is found. Set `CHROME_PATH` to select a browser. Restricted environments may require running browser tests with normal user permissions.
|
package/README.zh-CN.md
CHANGED
|
@@ -1,81 +1,130 @@
|
|
|
1
|
-
|
|
1
|
+
# dsh-home-sync
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/dsh-home-sync)
|
|
4
4
|
[](https://github.com/OverDustD7/dsh-home-sync)
|
|
5
5
|
|
|
6
|
-
[English](README.md) |
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
6
|
+
[English](README.md) | 简体中文
|
|
7
|
+
|
|
8
|
+
DSH 配置与 Mnemon 记忆插件数据的 Git 同步工具，支持自动双向同步、跨设备迁移、初始化备份、冲突检测和 Web 可视化管理。0.2.1 补齐维护建议，并修复复审发现的历史检查、初始化和状态显示遗漏。
|
|
9
|
+
|
|
10
|
+
需要 Node.js 20 或更新版本、Git，以及提供 `webServer`、`timer`、`connection.requestRejection` 的 DSH 宿主。本机兼容性验证使用 DSH 0.1.2-rc.1、Node 24.20.0、Git 2.55.0.windows.4。
|
|
11
|
+
|
|
12
|
+
## 安装与生效
|
|
13
|
+
|
|
14
|
+
### 从 npm 安装（推荐）
|
|
11
15
|
|
|
12
16
|
```powershell
|
|
13
17
|
dsh plugin --profile web add dsh-home-sync
|
|
14
18
|
```
|
|
15
19
|
|
|
16
|
-
|
|
17
|
-
|
|
20
|
+
装完重启 DSH web，刷新浏览器加载界面。已发布包无需构建或第三方依赖。
|
|
21
|
+
|
|
22
|
+
### 从 GitHub 安装
|
|
18
23
|
|
|
19
24
|
```powershell
|
|
20
25
|
dsh plugin --profile web add github:OverDustD7/dsh-home-sync
|
|
21
26
|
```
|
|
22
27
|
|
|
23
|
-
###
|
|
28
|
+
### 本地开发（从源码）
|
|
24
29
|
|
|
25
30
|
```powershell
|
|
26
31
|
dsh plugin --profile web add link:D:/Project/DSH/dsh-home-sync
|
|
27
32
|
```
|
|
28
33
|
|
|
29
|
-
`link:`
|
|
30
|
-
|
|
34
|
+
`link:` 安装直接读取该源码目录：后端改动后重启 DSH web，界面改动刷新浏览器即可。
|
|
35
|
+
|
|
36
|
+
### 离线/隔离网络设备
|
|
37
|
+
|
|
38
|
+
先本地生成安装包再拷到目标机：
|
|
31
39
|
|
|
32
|
-
鍏堟湰鍦扮敓鎴愬畨瑁呭寘鍐嶆嫹鍒扮洰鏍囨満锛?
|
|
33
40
|
```powershell
|
|
34
|
-
npm pack --
|
|
41
|
+
npm pack --pack-destination dist
|
|
35
42
|
```
|
|
36
43
|
|
|
37
|
-
|
|
44
|
+
目标机在压缩包所在目录执行：
|
|
38
45
|
|
|
39
46
|
```powershell
|
|
40
|
-
dsh plugin --profile web add ./dsh-home-sync-0.2.
|
|
47
|
+
dsh plugin --profile web add ./dsh-home-sync-0.2.3.tgz
|
|
41
48
|
```
|
|
42
49
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
50
|
+
若目标机器的包管理器无法使用本地 tarball，可把包解压到任意持久目录，再将该目录中的 `package` 子目录以 `link:` 安装；避免把临时解压目录作为长期链接目标。
|
|
51
|
+
|
|
52
|
+
## 同步行为
|
|
53
|
+
|
|
54
|
+
- “拉取”检查远端并尝试快进，遇到分叉或可能覆盖本地修改时失败，不会创建本地提交。显式禁用 `merge.autoStash`，避免自动恢复暂存时发生冲突却误报成功；合并结束还会检查未解决的索引冲突。
|
|
55
|
+
- “同步到远端”先 fetch 并检查文件范围，再提交允许同步的修改、整合远端，最后推送。工作区干净时仍会重试尚未上传的提交。
|
|
56
|
+
- 自动同步按间隔执行完整同步，本地没有变化时也会检查远端。保存开关和间隔后立即重建任务；操作正在执行时，设置保存和其他写请求返回忙碌，请待其结束后重试。
|
|
57
|
+
- 当前分支必须与设置中的分支一致。分支分叉可以尝试普通 Git 合并；同一内容冲突时停止推送、撤销此次未完成合并并保留本地提交。需手动解决 Git 冲突后重试，不会自动 force push。
|
|
58
|
+
- 状态区每 15 秒刷新，区分待提交、待推送、待拉取和读取失败，新增目录按实际文件计数。领先/落后数量以最近成功 fetch 的远端快照为准。
|
|
59
|
+
- 操作反馈使用 toast；面板底部“操作记录”默认折叠，按需展开查看、选择并复制备份路径和恢复指引。最近 100 条后台/手动操作记录保存在主目录旁的 `<DSH_HOME>.home-sync-history.json`，重启后仍可查询，不参与 Git 同步。记录包含操作结果、时间和备份路径，不记录文件正文。记录文件损坏时保留原文件并报告错误；记录写入失败不会撤销已经成功的同步。
|
|
60
|
+
- 打开的面板与浮动按钮随宿主和系统主题变化重新配色，保留当前输入及展开状态。
|
|
61
|
+
|
|
62
|
+
所有 HTTP 数据接口都使用宿主的身份和 Host/Origin 校验；缺少此服务时插件不启用。POST 只接受 JSON。界面脚本本身不含用户数据。
|
|
63
|
+
|
|
64
|
+
## 允许同步的文件
|
|
65
|
+
|
|
66
|
+
- `.gitignore`、`settings.yaml`、根目录 `cordis.patch.yml`。
|
|
67
|
+
- `profiles/web/` 下的 `package.json`、`pnpm-lock.yaml`、`pnpm-workspace.yaml`、`cordis.yml`、`cordis.patch.yml`、`.dsh-market/state.json`。
|
|
68
|
+
- `mnemon/` 下非隐藏文件，但排除名称为 data、state、credential(s)、secret(s) 的路径段，以及 `.log`、`.wal`、`.shm` 文件。
|
|
69
|
+
|
|
70
|
+
凭据、会话、附件、node_modules 等不加入提交。已暂存或已跟踪的禁止文件会阻止同步；推送前检查 HEAD 的完整可达历史（最多 1000 个提交），不以拉取仓库已有历史作为免检范围，因此拉取/推送地址不同或多个推送地址同样受保护。历史中曾出现禁止文件时停止发布，即使该文件已被删除；超过检查上限需先人工整理为干净同步历史。推送只更新所选分支，不自动跟随标签或镜像其他引用。多个目标的网络推送不具备跨仓库事务性，部分失败时需重试。允许文件内部的文本不做字段级脱敏，因此不要在允许同步的配置或记忆里保存不希望上传的内容。
|
|
71
|
+
|
|
72
|
+
只接受普通文件。符号链接、硬链接、子模块、越界路径、Windows 保留名称和大小写冲突会被拒绝。Git hooks 和提交签名仍遵循用户自己的 Git 配置；Git 子进程设置了超时及非交互凭据模式。
|
|
73
|
+
|
|
74
|
+
## 设备初始化与恢复
|
|
75
|
+
|
|
76
|
+
两种初始化模式都会备份。`merge` 表示备份后需要手动合并，并不表示自动把两份记忆合并。
|
|
77
|
+
|
|
78
|
+
1. 从远端抓取到独立临时仓库，检查所有目标路径和文件类型。
|
|
79
|
+
2. 检查本机碰撞，备份所有可能覆盖/删除的文件、原 Git 元数据和插件配置。
|
|
80
|
+
3. 验证备份期间本地文件没有变化，再应用允许的文件并设置目标分支、origin、upstream。
|
|
81
|
+
4. 成功后暂停自动同步与启动拉取，等待用户核对、手动合并及重新开启。
|
|
82
|
+
|
|
83
|
+
支持全新目录、已执行 `git init` 但尚未首次提交的独立仓库，以及再次初始化到历史不相关的远端。成功响应返回实际配置，界面立即刷新自动开关；初始化视为显式重置设置，当前表单以服务端配置为准。
|
|
84
|
+
|
|
85
|
+
备份位于 DSH_HOME 旁边的 `<DSH_HOME>.home-sync-backups/init-*`，不在被同步的工作区内。默认主目录时类似 `~/.dsh.home-sync-backups/init-*`。
|
|
86
|
+
|
|
87
|
+
- `files/`：原文件。
|
|
88
|
+
- `repository/`：原 `.git`，包含本地历史、索引和远端配置。
|
|
89
|
+
- `config.json`：原插件配置（原先存在时）。
|
|
90
|
+
- `manifest.json`：目标、阶段、原文件存在状态和校验值。
|
|
91
|
+
- `MERGE.md`：恢复说明。
|
|
92
|
+
|
|
93
|
+
可捕获的执行错误会尝试自动恢复。断电或强制结束进程不能保证自动恢复：先停止 DSH，依据 manifest 恢复 files，将 repository 恢复为 `.git`，恢复原配置，并移除清单中原先不存在的新文件。不要在 DSH 正写入记忆时执行恢复。Git worktree 或链接 `.git` 的初始化目前会明确拒绝。
|
|
94
|
+
|
|
95
|
+
初始化期间仍需避免其他程序写入同步文件；插件锁只协调本插件实例，不能暂停其他插件或人工 Git 操作。
|
|
96
|
+
|
|
97
|
+
## 配置与运行锁
|
|
98
|
+
|
|
99
|
+
配置位于 `<DSH_HOME>/dsh-home-sync.json`，支持：branch、autoPullOnStartup、autoSync、syncIntervalSeconds（15–86400）、commitMessage（1–1000 字符）、sshBatch。旧 autoSyncOnStartup 会迁移为 autoSync；同时存在时以 autoSync 为准。
|
|
100
|
+
|
|
101
|
+
损坏配置不会退回并开启默认自动任务。需修复或恢复此 JSON 后重启 DSH。写入通过临时文件同步落盘后替换，初始化另外保留配置备份。
|
|
102
|
+
|
|
103
|
+
跨进程锁目录为 `<DSH_HOME>.home-sync-lock`。异常退出可能留下锁；确认没有 DSH 同步任务运行后，才可移除这个锁目录。未完成的初始化应先按备份恢复。
|
|
104
|
+
|
|
105
|
+
## 验证
|
|
67
106
|
|
|
68
107
|
```powershell
|
|
69
108
|
npm run check
|
|
70
109
|
npm test
|
|
71
110
|
```
|
|
72
111
|
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
112
|
+
文档统一保存为 UTF-8。使用脚本修改时，读取和写入都应显式指定 UTF-8，不能依赖系统默认代码页。`npm run check:docs` 检查 README 正文和语言链接，并已接入 `npm run check` 与正常 npm 打包流程；打包时不要使用 `--ignore-scripts`，否则会跳过该检查。
|
|
113
|
+
|
|
114
|
+
测试使用系统临时目录、虚构文件与本地 Git 远端，不访问真实 DSH 主目录或真实账号。测试仓库保留在系统临时目录便于诊断。
|
|
115
|
+
|
|
116
|
+
浏览器测试使用独立临时 Chrome/Edge 配置；没有浏览器时跳过，可通过 `CHROME_PATH` 指定。受限环境可能需要在正常用户权限下运行浏览器测试。宿主兼容性测试可用 `DSH_HOST_MODULES` 指向已安装 DSH 的 `node_modules/@deepseek-ai`，未找到时跳过；此测试复用真实宿主路由与来源校验方法，身份 Cookie 验证使用虚构实现。
|
|
117
|
+
|
|
118
|
+
开发与审计文档（检查/修复/复核报告及 `audit/` 证据）为本地内部资料，不随本仓库分发；`test/` 与 `npm test` 是公开可复现的验证入口。
|
|
119
|
+
|
|
120
|
+
## 历史复核记录（2026-09-07，已被后续复审补充）
|
|
121
|
+
|
|
122
|
+
**以下是 0.2.0 的历史记录，其"未发现新的高风险缺陷"结论已被后续复审推翻。** 开发与审计文档（含 0.2.1 二次审查报告）为本地内部资料，未随本仓库分发，本段仅作历史追溯；默认隐藏即时日志的交互保持，新增独立折叠操作记录入口。
|
|
77
123
|
|
|
78
|
-
|
|
79
|
-
鍦ㄤ慨澶嶅畬鎴愭姤鍛婁箣鍚庯紝瀵?0.2.0 婧愮爜杩涜浜嗙嫭绔嬬殑鍙澶嶆牳涓庢祴璇曞璺戯細
|
|
124
|
+
在修复完成报告之后，对 0.2.0 源码进行了独立的只读复核与测试复跑：
|
|
80
125
|
|
|
81
|
-
-
|
|
126
|
+
- **复核范围**：`lib/index.js`、`lib/sync.js`、`lib/ui.js`、`package.json`、`cordis.patch.yml`，与两份报告逐条对照。
|
|
127
|
+
- **结果**：原审计 17 项（F01–F17）修复均已落实到当前源码，抽查关键实现与本页“同步行为/允许同步的文件/设备初始化/验证”描述一致；报告所述 35 项测试在本机（Node 24.20.0 + Git 2.55.0.windows.4，真实 Git 临时仓库与虚构远端）复跑**35/35 通过，0 失败**。
|
|
128
|
+
- **复核中修正的一处界面回归**：界面操作反馈改为底部 toast 浮窗（不再显示卡片内日志框）；`#log` 保留但改为视觉隐藏，仅作 aria-live 供屏幕阅读器使用，避免再次出现用户已否决的“保存后在下方显示提示”。
|
|
129
|
+
- **复核结论**：`npm run check` 与 `npm test` 全绿；未发现新的高风险缺陷。
|
|
130
|
+
- **已知边界（与报告一致，非缺陷）**：两种初始化模式底层行为相同（备份 → 重置 → 暂停自动任务），`mode` 仅影响提示文案；“已用机器合并”需要按备份与 `MERGE.md` 手动挑拣；HTTP 接口仅接受已登录的可信会话（未登录直连返回 401 属预期）；后端（index/sync）改动需重启 DSH web 后生效，界面（ui.js）改动 Ctrl+F5 即生效。
|
package/lib/sync.js
CHANGED
|
@@ -108,8 +108,12 @@ export function createHomeSync(directory = process.env.DSH_HOME || path.join(os.
|
|
|
108
108
|
for (const key of Object.keys(env)) if (/^GIT_(DIR|WORK_TREE|COMMON_DIR|INDEX_FILE|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES|NAMESPACE|CONFIG_COUNT|CONFIG_KEY_.*|CONFIG_VALUE_.*|CONFIG_PARAMETERS|CEILING_DIRECTORIES|DISCOVERY_ACROSS_FILESYSTEM|PREFIX|SSH|SSH_COMMAND)$/.test(key)) delete env[key]
|
|
109
109
|
env.GIT_TERMINAL_PROMPT = '0'; env.GCM_INTERACTIVE = 'never'; env.GIT_OPTIONAL_LOCKS = '0'; env.GIT_NO_REPLACE_OBJECTS = '1'
|
|
110
110
|
if (cfg.sshBatch) env.GIT_SSH_COMMAND = 'ssh -o BatchMode=yes -o StrictHostKeyChecking=accept-new -o ConnectTimeout=15'
|
|
111
|
+
// `safe.directory=*` skips Git's "dubious ownership" check: we only run
|
|
112
|
+
// Git inside the validated DSH home or our own temp repositories, so a
|
|
113
|
+
// directory legitimately owned by another Windows user (e.g. created by
|
|
114
|
+
// an elevated prompt) must not block sync/init.
|
|
111
115
|
return new Promise(resolve => {
|
|
112
|
-
const child = execFile('git', ['--literal-pathspecs', '-C', cwd, ...args],
|
|
116
|
+
const child = execFile('git', ['-c', 'safe.directory=*', '--literal-pathspecs', '-C', cwd, ...args],
|
|
113
117
|
{ env, timeout: 90000, windowsHide: true, maxBuffer: 16 * 1024 * 1024 }, (error, stdout, stderr) => {
|
|
114
118
|
resolve({ ok: !error, code: error?.code ?? 0, stdout: String(stdout || ''), stderr: String(stderr || ''), timedOut: !!error?.killed })
|
|
115
119
|
})
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dsh-home-sync",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.4",
|
|
4
4
|
"description": "Git-based sync for DSH configuration and Mnemon memory plugin data, with automatic two-way sync, cross-device migration, initialization backups, conflict detection, and a web UI.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "lib/index.js",
|
|
@@ -8,7 +8,9 @@
|
|
|
8
8
|
"engines": { "node": ">=20" },
|
|
9
9
|
"scripts": {
|
|
10
10
|
"test": "node --test test/*.test.mjs",
|
|
11
|
-
"check": "node --check lib/index.js && node --check lib/sync.js && node --check lib/ui.js"
|
|
11
|
+
"check": "node --check lib/index.js && node --check lib/sync.js && node --check lib/ui.js && npm run check:docs",
|
|
12
|
+
"check:docs": "node scripts/check-docs.mjs",
|
|
13
|
+
"prepack": "npm run check:docs"
|
|
12
14
|
},
|
|
13
15
|
"repository": { "type": "git", "url": "https://github.com/OverDustD7/dsh-home-sync.git" },
|
|
14
16
|
"homepage": "https://github.com/OverDustD7/dsh-home-sync#readme",
|