@moredrive/sync 1.2.0 → 1.5.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.
package/README.md CHANGED
@@ -1,11 +1,15 @@
1
1
  # MoreDrive Sync
2
2
 
3
- 远端到本地的同步工具。需要 Node.js 22 或更新版本。支持 macOS Apple Silicon、Windows x64、Linux x64(glibc 2.34 或更新版本及 libgcc_s,不支持 Alpine/musl)。Windows 需要 Microsoft Visual C++ 2015–2022 x64 运行库。
3
+ 个人网盘与本地目录同步,支持下载、上传、双向同步、冲突处理和中断恢复。
4
4
 
5
- 安装:`npm install -g @moredrive/sync`
5
+ npm 安装:`npm install -g @moredrive/sync`;更新:`npm install -g @moredrive/sync@latest`。npm 入口需要 Node.js 22+,按平台选择原生程序,无安装脚本或安装时下载器。原生归档无需 Node.js,请完整解压并保留资源。程序不会自动替换自身。
6
6
 
7
- 更新:`npm install -g @moredrive/sync@latest`
7
+ 支持 macOS Apple Silicon、Windows x64、Linux x64(glibc 2.34+、libgcc_s;不支持 musl)。Windows 需要 Microsoft Visual C++ 2015–2022 x64 运行库。依赖许可证见 third-party(npm 安装时位于对应原生平台包)。
8
8
 
9
- 检查:`moredrive-sync --version`、`moredrive-sync --help`。先通过 MoreDrive CLI 登录,再按帮助配置同步目录,先 dry-run 验证计划。删除操作需显式启用。程序不会自动替换自身。
9
+ - [中文上手:配置、目录、dry-run、执行与检查](docs/getting-started.md)
10
+ - [全部使用文档](docs/README.md)
11
+ - [AI Skill](skills/moredrive-sync/SKILL.md),供直接读取,不自动安装到 agent 目录。
10
12
 
11
- 安装时会按平台选择对应的原生程序,无安装脚本或安装时下载器。原生包附有依赖许可证。
13
+ 检查 `moredrive-sync --version` 和 `moredrive-sync --help`;帮助显示实际资源路径。已有登录配置可以复用;CLI 仅辅助登录,Sync 运行无需 CLI。首次同步先检查 dry-run,保留状态库与工作区。
14
+
15
+ v1.5 新建同步对默认 auto,已有同步对保持 raw。auto 支持媒体转换和成功上传后的自动封面;常用图片缩略图内置,视频需显式配置兼容 FFmpeg。原件与封面结果分别报告,失败封面不会在静止轮次自动补齐。状态库升级为 schema 4,模式切换和回退须先停止调度并处理在途操作,详见[媒体模式与升级](docs/media-v1.5.md)。包内 build-info.json 标明版本和构建来源;validationOnly 的材料仅供本地验证,不能视为完整发行集。
@@ -17,6 +17,17 @@ try {
17
17
  const native = JSON.parse(readFileSync(manifestPath, 'utf8'));
18
18
  const wrapper = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
19
19
  if (native.version !== wrapper.version) throw new Error('Native package version does not match wrapper');
20
+ // Local validation builds may reuse an already published version number.
21
+ // Do not silently run the older registry binary with newer bundled guidance.
22
+ if (wrapper.private === true) {
23
+ const build = JSON.parse(readFileSync(new URL('../build-info.json', import.meta.url), 'utf8'));
24
+ const nativeBuild = JSON.parse(readFileSync(join(dirname(manifestPath), 'build-info.json'), 'utf8'));
25
+ if (build.validationOnly !== true || nativeBuild.validationOnly !== true
26
+ || !build.buildId || !build.buildSha
27
+ || nativeBuild.buildId !== build.buildId || nativeBuild.buildSha !== build.buildSha) {
28
+ throw new Error('Validation build identity does not match; install both tarballs from the same validation build');
29
+ }
30
+ }
20
31
  binary = join(dirname(manifestPath), 'bin', process.platform === 'win32' ? 'moredrive-sync.exe' : 'moredrive-sync');
21
32
  } catch (error) {
22
33
  console.error(`MoreDrive Sync: ${error.message}. Install with optional dependencies enabled.`);
package/build-info.json CHANGED
@@ -1,4 +1,6 @@
1
1
  {
2
- "buildSha": "b4af4bf9c3cdf641592e61f613c7c84da65596ef",
3
- "version": "1.2.0"
2
+ "buildSha": "1eba40e4d93abf33d341e4bf1d0aa6c19b44fe7d",
3
+ "buildId": "release-v1.5-20261117",
4
+ "validationOnly": false,
5
+ "version": "1.5.0"
4
6
  }
package/docs/README.md ADDED
@@ -0,0 +1,19 @@
1
+ # MoreDrive Sync 使用说明
2
+
3
+ Sync 将个人网盘目录与本地目录同步,支持远端到本地、本地到远端和双向同步,并保留状态、冲突与恢复材料。这份文档随当前 1.5.0 候选程序源码组装;实际包版本查看 `moredrive-sync --version` 和包内 `build-info.json`。本地验证包不等于已公开发布的同版本包。
4
+
5
+ 从[中文上手流程](getting-started.md)开始:安装 → 登录配置 → 准备目录 → 选择方向 → dry-run → 执行 → 检查结果。
6
+
7
+ | 需要做什么 | 阅读 |
8
+ | --- | --- |
9
+ | once、watch、pair、后台服务 | [命令](commands.md) |
10
+ | 登录配置、忽略规则、并发与限速 | [配置](config.md) |
11
+ | 自动化、退出码和完成判定 | [JSON / JSONL](json-contract.md) |
12
+ | 删除批准、冲突与历史恢复 | [删除与冲突策略](delete-and-conflict-policy.md) |
13
+ | 登录失效、目录缺失、空间不足、中断 | [排障](troubleshooting.md) |
14
+ | 状态库位置与升级 | [状态库](state-db.md) |
15
+ | 下载核验边界 | [内容核验](download-verification.md) |
16
+
17
+ `moredrive-sync --help` 显示当前包中使用文档和 AI Skill 的实际位置。原生归档需完整解压;仅复制二进制会丢失文档。Skill 供 AI 直接读取包内文件,不自动安装到 agent 目录。
18
+
19
+ v1.5 新建 pair 默认 auto,旧 pair 缺字段时保持 raw。auto 固定本地明文与远端普通/弱加密形式,原件转换失败停止单项;成功新上传可利用本批本地源生成封面。详见 [媒体模式与升级](media-v1.5.md)。本地候选验收仍在进行,不代表已发布。
@@ -0,0 +1,176 @@
1
+ # Sync Commands
2
+
3
+ ## `once`
4
+
5
+ Run one fixed batch and exit. Direction defaults to remote-to-local; select
6
+ `--direction remote-to-local|local-to-remote|bidirectional` explicitly for v2 reports.
7
+
8
+ ```bash
9
+ moredrive-sync once remote:/docs ~/Documents/MoreDrive/docs --json
10
+ moredrive-sync once --pair docs --json
11
+ moredrive-sync once remote:/docs ~/Documents/MoreDrive/docs --dry-run
12
+ ```
13
+
14
+ Useful options:
15
+
16
+ | Option | Meaning |
17
+ | --- | --- |
18
+ | `--pair <name>` | Use a saved pair. |
19
+ | `--profile <name>` | Use a config profile. |
20
+ | `--dry-run` | Read-only sync plan; credentials may still refresh in the shared config. |
21
+ | `--delete --yes` | Enable `delete-local` for this run. |
22
+ | `--conflict keep-both\|prefer-remote\|fail` | Legacy download policy; new modes use explicit conflict resolution (see below). |
23
+ | `--concurrency <n>` | Set parallel downloads. |
24
+ | `--download-connections <n>` | Set the concurrent Range request cap for one large file. |
25
+ | `--max-transfer-requests <n>` | Set the total concurrent download request cap for this pair. |
26
+ | `--follow-symlinks` | Retained CLI flag; the verified sync engine rejects link traversal. |
27
+ | `--json` | Print a summary JSON object. |
28
+ | `--jsonl` | Print line-delimited events. |
29
+
30
+ ## `watch`
31
+
32
+ Run foreground periodic sync. It is not a daemon.
33
+
34
+ ```bash
35
+ moredrive-sync watch remote:/docs ~/Documents/MoreDrive/docs --interval 10m --jsonl
36
+ moredrive-sync watch --pair docs --interval 60s
37
+ ```
38
+
39
+ `watch` handles Ctrl+C and SIGTERM. Shutdown timing differs between the legacy and v2 paths; retain the same DB/workspace to resume unfinished work. A normal process exit does not prove all pairs completed.
40
+
41
+ Files at or above the configured multi-range threshold use bounded Range requests.
42
+ `--download-connections` controls per-file concurrency, while
43
+ `--max-transfer-requests` controls the total download requests for the pair.
44
+
45
+ ## `upload-once`
46
+
47
+ Upload one local file to Personal Drive and exit.
48
+
49
+ ```bash
50
+ moredrive-sync upload-once ./release.zip remote:/releases/release.zip --jsonl
51
+ moredrive-sync upload-once ./release.zip remote:/releases/release.zip --upload-connections 4 --json
52
+ moredrive-sync upload-once ./release.zip remote:/releases/release.zip --dry-run --json
53
+ ```
54
+
55
+ The command negotiates an upload plan with the Worker, uploads missing slices
56
+ directly through the issued ticket, refreshes expired tickets when allowed, and
57
+ calls upload finish only after every required slice completes. It uploads one
58
+ explicit file; it does not change the folder sync direction.
59
+
60
+ ## `pair`
61
+
62
+ Manage saved sync pairs in the sync state DB.
63
+
64
+ ```bash
65
+ moredrive-sync pair add docs remote:/docs ~/Documents/MoreDrive/docs
66
+ moredrive-sync pair list --json
67
+ moredrive-sync pair enable docs
68
+ moredrive-sync pair disable docs
69
+ moredrive-sync pair remove docs --yes
70
+ ```
71
+
72
+ Enabled pairs cannot use overlapping local roots unless `pair add` is called with `--allow-overlap`.
73
+
74
+ ## `status`
75
+
76
+ Print saved pairs and their last run.
77
+
78
+ ```bash
79
+ moredrive-sync status --json
80
+ moredrive-sync status --pair docs
81
+ ```
82
+
83
+ ## `doctor`
84
+
85
+ Check config, profile presence, state DB readability, local roots, remote roots, and overlapping pair roots. Doctor does not migrate the DB.
86
+
87
+ ```bash
88
+ moredrive-sync doctor --json
89
+ moredrive-sync doctor --pair docs
90
+ ```
91
+
92
+ ## 方向、恢复与后台服务
93
+
94
+ 以下命令由当前程序提供。这里的示例说明用法,不代表所有平台的服务登录/注销场景均经过验收。
95
+
96
+ ```bash
97
+ moredrive-sync once remote:/docs ~/Documents/MoreDrive/docs --direction bidirectional --json
98
+ moredrive-sync once --pair docs --verify-content --json
99
+ moredrive-sync pair add uploads remote:/uploads ~/Documents/MoreDrive/uploads --direction local-to-remote
100
+ moredrive-sync pair approve-deletions docs --plan-hash HASH
101
+ moredrive-sync conflict list --pair docs
102
+ moredrive-sync conflict show CONFLICT_ID --pair docs
103
+ moredrive-sync conflict resolve CONFLICT_ID --pair docs --keep both
104
+ moredrive-sync history list --pair docs
105
+ moredrive-sync history restore HISTORY_ID --pair docs --target restored.txt
106
+ moredrive-sync daemon run
107
+ moredrive-sync service install
108
+ moredrive-sync service start
109
+ moredrive-sync service status
110
+ moredrive-sync service stop
111
+ moredrive-sync service uninstall
112
+ ```
113
+
114
+ New direction and verification options select JSON v2. The default download
115
+ command retains JSON v1 and now shares the verified-baseline executor. Both
116
+ roots must exist for new modes. Only an unbound legacy download can create its
117
+ explicit local destination. Missing or replaced bound roots stop the pair.
118
+ `--rebind` explicitly confirms a binding/direction change. The verified sync engine rejects
119
+ `--follow-symlinks`, including the legacy download entry.
120
+
121
+ `--delete-policy keep-extra|propagate` is independent of direction.
122
+ Compatibility policy differences between legacy and new modes are documented in
123
+ [删除与冲突策略](delete-and-conflict-policy.md). Legacy
124
+ `keep-local-extra|delete-local|fail-on-delete` names remain accepted. Propagation
125
+ requires two complete missing observations at least 30 seconds apart and a
126
+ verified unchanged survivor. Bulk deletion additionally requires its exact plan
127
+ hash approval; `--yes` does not bypass that check. Replaced/deleted targets are
128
+ retained in owned history, with a default 10 GiB logical budget on each side.
129
+ `--history-budget BYTES` changes this pair's budget; there is no automatic history
130
+ eviction. Restore requires an absent destination.
131
+
132
+ Keep-both conflicts remain unresolved until explicitly resolved and return v2
133
+ exit 2. Resolution revalidates the generation and recorded versions. One-way
134
+ pairs reject a choice that would require modifying their source. File/directory
135
+ conflicts remain blocked for manual inspection; the executor does not recursively
136
+ remove a directory to make room for a file.
137
+
138
+ The daemon reloads pair controls every five seconds. Service registration pins
139
+ the current absolute native binary and its SHA-256; reinstall after changing the
140
+ binary. Uninstall removes startup registration and preserves user files, config,
141
+ DB and history. Use `service --help` for platform support and inspect the registered service status.
142
+
143
+ Unresolved conflict records retain the original choices. A later external change
144
+ is linked under `relatedVersions` and rejects stale resolution; repeated scans
145
+ do not create another visible copy. Windows currently rehashes local files
146
+ because timestamp-only fingerprints can alias rapid same-size writes.
147
+
148
+ `upload-once` 的实际上传也使用持久 staging、原 key 恢复、旧目标历史保全和无覆盖发布。目标父目录必须已存在。JSON v1 原字段保留,成功时新增可选 `data.historyPairId`;人工输出也显示此 ID,可用于 `history list --pair <id>` 及 `history restore <history-id> --pair <id> --target <relative-path>`。完成的单文件绑定被归档,不加入后台调度;显式恢复会检查账号、根和其他活动绑定,结束或返回错误后保持归档。未决上传继续使用同一命令对账,不通过换 key 重新提交。
149
+
150
+ `upload-once --history-budget BYTES` 可显式调整该单文件绑定的历史预算。预算不足会保留原目标并阻止发布;调大后重跑原命令会复用已核验的候选和持久意图。
151
+
152
+
153
+ ## 常用恢复与服务顺序
154
+
155
+ 先完成一次前台 dry-run 和 once,再考虑后台调度。`pair add` 默认启用,daemon 调度所有启用的 pair;开始前检查 `pair list --json`,将不希望后台运行的 pair 用 `pair disable NAME` 暂停。
156
+
157
+ ```sh
158
+ moredrive-sync daemon run
159
+ # 或安装用户服务,保持与前台相同的绝对配置与 DB 路径:
160
+ moredrive-sync --config /absolute/config.json --state-db /absolute/state.db service install
161
+ moredrive-sync service start
162
+ moredrive-sync service status
163
+ ```
164
+
165
+ 不要让手工 daemon 和已安装服务同时执行同一组任务。更新程序后停止旧服务并重新 install,注册会绑定原生程序绝对路径和摘要。npm 全局更新也可能改变此路径或摘要。`service uninstall` 只移除启动注册,不删除配置、DB、用户文件或历史。
166
+
167
+ 历史释放与保护材料检查:
168
+
169
+ ```sh
170
+ moredrive-sync history release HISTORY_ID --pair docs
171
+ moredrive-sync history release HISTORY_ID --pair docs --confirm PREVIEW_HASH
172
+ moredrive-sync candidate list --pair docs
173
+ moredrive-sync root review --pair docs
174
+ ```
175
+
176
+ `history release` 无确认值时只预览;精确确认值来自当前预览,永久释放不可当作普通恢复步骤。`candidate release`、`root confirm` 和 `retry` 的前提先读当前子命令帮助及[排障](troubleshooting.md)。`audit --pair docs --path relative/file --dry-run` 可预览针对性审计;`--verify-content` 或不带路径的 audit 可能读取大量内容,不作为日常运行默认步骤。
package/docs/config.md ADDED
@@ -0,0 +1,126 @@
1
+ # Sync Config
2
+
3
+ 配置选择优先级:`--config <文件>` → `MOREDRIVE_CONFIG` → 操作系统默认目录。默认路径:
4
+
5
+ | 平台 | 默认配置 |
6
+ | --- | --- |
7
+ | macOS | `~/Library/Application Support/moredrive/config.json` |
8
+ | Linux | `$XDG_CONFIG_HOME/moredrive/config.json`,未设置时 `~/.config/moredrive/config.json` |
9
+ | Windows | `%APPDATA%\moredrive\config.json` |
10
+
11
+ CLI 与 Sync 的默认路径在部分平台不同。复用 CLI 登录时,建议两者显式设置同一个 `MOREDRIVE_CONFIG`,或给 Sync 加 `--config`。配置文件中的 profile 优先由 `--profile` / pair 指定,其次 `defaultProfile`,最后 `default`。
12
+
13
+ 当前 CLI 保存 `moredrive.config.v2` 会话;下列仅说明结构,凭据和到期时间为占位值,实际以登录生成的文件为准:
14
+
15
+ ```json
16
+ {
17
+ "schemaVersion": "moredrive.config.v2",
18
+ "defaultProfile": "default",
19
+ "profiles": {
20
+ "default": {
21
+ "baseUrl": "https://moredrive-api.rdfstu.com/api",
22
+ "accessToken": "YOUR_ACCESS_TOKEN",
23
+ "refreshToken": "YOUR_REFRESH_TOKEN",
24
+ "expiresAt": 0,
25
+ "refreshExpiresAt": 0
26
+ }
27
+ }
28
+ }
29
+ ```
30
+
31
+ Sync 自行刷新会话并原子写回共享配置,配置目录需可写。旧 `token` profile 仍能读取,但没有 refreshToken 的令牌不能自动刷新。**Sync 不读取 `MOREDRIVE_TOKEN`**,也没有 login 子命令。CLI 是可选的登录辅助工具,不是 Sync 运行依赖;保护配置文件访问权限,不粘贴完整配置到日志。
32
+
33
+ Saved sync pairs may also be placed under `sync.pairs`, though `moredrive-sync pair add` stores runtime-managed pairs in the sync state DB:
34
+
35
+ ```json
36
+ {
37
+ "schemaVersion": "moredrive.config.v1",
38
+ "defaultProfile": "default",
39
+ "profiles": {
40
+ "default": {
41
+ "baseUrl": "https://moredrive-api.rdfstu.com/api",
42
+ "token": "YOUR_LEGACY_APP_TOKEN"
43
+ }
44
+ },
45
+ "sync": {
46
+ "stateDir": "~/.local/state/moredrive",
47
+ "pairs": {
48
+ "docs": {
49
+ "enabled": true,
50
+ "profile": "default",
51
+ "direction": "remote-to-local",
52
+ "remote": "remote:/docs",
53
+ "local": "~/Documents/MoreDrive/docs",
54
+ "intervalSeconds": 600,
55
+ "deletePolicy": "keep-local-extra",
56
+ "conflictPolicy": "keep-both",
57
+ "concurrency": 3,
58
+ "ignoreFile": ".moredriveignore"
59
+ }
60
+ }
61
+ }
62
+ }
63
+ ```
64
+
65
+ Rules:
66
+
67
+ - `remote` must start with `remote:/`.
68
+ - `local` must be absolute or start with `~/`.
69
+ - Pair names may contain only letters, numbers, dot, underscore, and dash.
70
+ - `deletePolicy` defaults to `keep-local-extra`.
71
+ - `conflictPolicy` defaults to `keep-both`.
72
+ - `concurrency` must be greater than zero.
73
+
74
+ Download transfer fields are enforced:
75
+
76
+ ```json
77
+ {
78
+ "sync": {
79
+ "transfer": {
80
+ "downloadPartSizeBytes": 67108864,
81
+ "downloadMultiRangeMinBytes": 20971520,
82
+ "downloadConnections": 4,
83
+ "maxTransferRequestsPerPair": 8,
84
+ "globalMaxTransferRequests": 16,
85
+ "downloadInflightBytes": 536870912,
86
+ "uploadChunkSizeBytes": 4194304,
87
+ "uploadMaxConnectionsPerFile": 6,
88
+ "dlinkSoftTtlSeconds": 27900,
89
+ "maxLeaseRefreshPerTask": 4
90
+ }
91
+ }
92
+ }
93
+ ```
94
+
95
+ `downloadConnections` is the preferred short name for the per-file range
96
+ connection limit. The older `downloadMaxConnectionsPerFile` name is still
97
+ accepted for compatibility. Files at or above `downloadMultiRangeMinBytes`
98
+ use multi-range download when the size is known and `downloadConnections > 1`;
99
+ smaller files continue to use single-stream download.
100
+
101
+ Upload uses 4 MiB parts and defaults to six simultaneous part requests per
102
+ file. `uploadMaxConnectionsPerFile` can be lowered on memory-constrained or
103
+ unstable networks, and `upload-once --upload-connections` overrides it for one
104
+ run.
105
+
106
+
107
+ ## 限速与执行预算
108
+
109
+ Sync 的限速在顶层 `sync.transfer`,不是 CLI profile 的 `transfer`:
110
+
111
+ ```json
112
+ {
113
+ "sync": {
114
+ "transfer": {
115
+ "uploadSpeedLimit": 524288,
116
+ "downloadSpeedLimit": 2097152
117
+ }
118
+ }
119
+ }
120
+ ```
121
+
122
+ 单位为整数字节/秒,默认 `0` 不限速,最大 10737418240(10 GiB/s)。非法类型、负数、小数或越界值报错。修改后重启 Sync。每个进程的全部任务、文件、连接和重试按上传/下载方向共享额度;控制 API 不受该字节限速影响,不同进程不共享额度。
123
+
124
+ `onceExecutionLimitSeconds` 默认 86400,`once --execution-limit-seconds` 可覆盖;`0` 只运行一个调度轮次,适合诊断,不表示等待全部完成。`stagingBudgetBytes` 默认 20 GiB;`spaceReserveBytes` 可指定物理剩余空间保留字节,`workspaceRoot` 可指定本地工作区根。调整前阅读[排障](troubleshooting.md),不要移动或删除未决工作区来腾空间。
125
+
126
+ 忽略规则默认取本地根的 `.moredriveignore`。规则控制同步范围,控制文件不作为普通数据传播;修改规则可能使原删除观察和批准失效。升级遇到本地范围确认时先检查规则,再按帮助使用 `--confirm-local-scope`,不能无条件加确认开关。
@@ -0,0 +1,40 @@
1
+ # 删除、冲突和历史
2
+
3
+ 方向与删除策略独立。默认 `keep-local-extra`(别名 `keep-extra`)保留目标端额外内容;`delete-local`(别名 `propagate`)按当前方向传播有充分依据的删除;双向会涉及两端。`fail-on-delete` 是兼容参数:旧下载入口会将待删除工作标为受阻;新模式不启用传播,但不要依赖它得到与旧入口完全相同的失败分类。远端到本地不会为了消除冲突上传本地修改;本地到远端也不修改源文件。
4
+
5
+ ## 删除批准
6
+
7
+ `once --delete --yes` 是临时启用传播的兼容入口;也可在显式方向下使用 `--delete-policy propagate`。启用之前先 dry-run 并核对根和计划。删除需要共同基线、至少相隔 30 秒的两次完整缺失观察及未变化的存活版本;缺失根、扫描失败不是删除证据。根目录不会被删除,越界路径拒绝。
8
+
9
+ 批量删除额外要求精确计划批准:
10
+
11
+ ```sh
12
+ moredrive-sync pair approve-deletions docs --plan-hash PLAN_HASH
13
+ ```
14
+
15
+ PLAN_HASH 来自该 pair 当前执行保存的待批准计划。dry-run 不保存新计划,因此仅预览所得 hash 不能保证可批准。先运行已授权的同步使程序停在 `pending-deletion`,审阅报告,再批准当前计划并重跑同一 pair。`--yes` 不绕过批量批准;方向、根、账号、generation 或范围变化可能使批准失效。
16
+
17
+ ## 冲突
18
+
19
+ 默认 `keep-both` 保留双方版本,并留下未决冲突,v2 返回退出 2。旧下载入口的 `prefer-remote` 可将文件/文件冲突转为保留目标历史后下载,`fail` 保留冲突并使工作失败。当前 v2 新模式虽然接受这些兼容参数,但不会据此自动执行旧入口的 prefer-remote/fail 分支;仍应通过 conflict list/show/resolve 明确解决。不要依赖旧的冲突副本文件名格式来判断状态。
20
+
21
+ ```sh
22
+ moredrive-sync conflict list --pair docs
23
+ moredrive-sync conflict show CONFLICT_ID --pair docs
24
+ moredrive-sync conflict resolve CONFLICT_ID --pair docs --keep both
25
+ ```
26
+
27
+ `--keep` 支持 local、remote、both。依据用户意图选择;解决时重新核验 generation 和双方版本,外部变化会阻止过期解决。单向 pair 拒绝要求修改其源端的选择。文件/目录冲突需人工检查,程序不递归删除目录为文件让路。解决后再次运行并查看状态,不能把命令被接受当作已收敛。
28
+
29
+ ## 历史恢复和释放
30
+
31
+ 替换或删除前保留 owned history,默认每端逻辑预算 10 GiB,可用 `--history-budget BYTES` 调整;超预算阻止相关工作,不自动淘汰历史。
32
+
33
+ ```sh
34
+ moredrive-sync history list --pair docs
35
+ moredrive-sync history restore HISTORY_ID --pair docs --target restored.txt
36
+ ```
37
+
38
+ 目标为根内相对路径,必须不存在;仍需匹配账号、根和绑定。不要直接移动工作区中的保留文件。`pair remove --yes` 移除调度记录、归档绑定,不等于删除用户数据或释放历史。
39
+
40
+ 永久释放已完成历史先运行 `history release HISTORY_ID --pair docs` 预览,核对条目后再用精确 `--confirm PREVIEW_HASH`。未决材料的处置规则不同,见[排障](troubleshooting.md)。
@@ -0,0 +1,9 @@
1
+ # 下载与内容核验
2
+
3
+ Sync 通过 HTTPS 下载远端内容,检查传输完成、预期大小和已绑定版本,候选写入并持久化后才发布。当前目录同步执行器使用双方观察、实际读取的内容摘要和持久证据判断基线及恢复;不会仅因 HTTP 成功或上传切片完成就宣布整项同步成功。
4
+
5
+ 百度接口的 `md5` 是不透明 cloud hash,不能直接与本地文件 MD5 比较来证明内容相同。远端身份、大小、cloud hash、时间等元数据用于判断版本,和实际字节校验是不同的证据。
6
+
7
+ `--verify-content` 绕过可用缓存重新核验内容,可能读取大量数据,不应默认添加。针对故障可先预览 `audit --pair NAME --path relative/file --dry-run`,再按需要执行有界核验。`verificationBytes` 是该轮扫描核验字节,不包含所有进程 IO;其他传输与读取统计见[输出说明](json-contract.md)。
8
+
9
+ 重启下载保留同一 DB、根和工作区,程序仅复用版本与内容证据仍有效的候选/分段。不要手工把未完成 `.part` 或 staging 文件改名为最终文件。
@@ -0,0 +1,74 @@
1
+ # 中文上手流程
2
+
3
+ ## 安装与准备
4
+
5
+ npm 安装需要 Node.js 22 或更新版本:
6
+
7
+ ```sh
8
+ npm install -g @moredrive/sync
9
+ moredrive-sync --version
10
+ moredrive-sync --help
11
+ ```
12
+
13
+ 支持 macOS Apple Silicon、Windows x64、Linux x64(glibc 2.34+ 和 libgcc_s,不支持 Alpine/musl)。Windows 需 Microsoft Visual C++ 2015–2022 x64 运行库。原生归档无需 Node.js:完整解压,将程序所在目录加入 PATH,保留相邻的 README、docs、skills 和 third-party。程序不自行更新;npm 更新用 `npm install -g @moredrive/sync@latest`,原生更新替换完整归档。注册过服务时,换程序后需重新注册服务。
14
+
15
+ Sync 没有 login 命令。已有 MoreDrive 登录配置可直接复用,用 `--config` 指向实际文件;默认路径与 CLI 在部分平台可能不同,详见[配置](config.md)。Sync 能自行刷新有效 refreshToken,不依赖 CLI 常驻。没有配置时,可另装 CLI(`npm install -g @moredrive/cli`),使用其 `login --password-stdin --save` 创建配置。也可从可信环境安全迁移自己的配置;不要将他人账号凭据或占位值当作可用登录。
16
+
17
+ ## 完整示例:网盘下载到本地
18
+
19
+ 若已经运行 daemon 或注册服务,请先停止使用同一配置/DB 的后台执行器再按本节预览。`pair add` 默认启用新 pair,运行中的 daemon 可能立即开始同步;不能靠随后执行 dry-run 阻止它。完成前台检查后再恢复后台调度。
20
+
21
+ 下例用于 bash/zsh。将账号和目录改为自己的值;远端 `/docs` 必须已存在,可在网盘界面创建。本地用绝对路径,不能传 `./docs`。示例显式指定同一配置路径,避免 macOS 默认目录差异。已有配置时跳过登录步骤并调整路径即可。
22
+
23
+ ```sh
24
+ export MOREDRIVE_CONFIG="$HOME/.config/moredrive/config.json"
25
+ # 可选:首次登录。通过终端隐藏输入,避免密码进入历史记录。
26
+ if [ -n "${ZSH_VERSION:-}" ]; then
27
+ read -r -s 'MD_PASSWORD?Password: '
28
+ else
29
+ read -r -s -p 'Password: ' MD_PASSWORD
30
+ fi
31
+ printf '%s' "$MD_PASSWORD" | moredrive login --username YOUR_USERNAME --password-stdin --save --json
32
+ unset MD_PASSWORD
33
+
34
+ mkdir -p "$HOME/Documents/MoreDrive/docs"
35
+ moredrive-sync pair list --json
36
+ # 名称 docs 尚未被使用时保存同步对;如已存在,先检查原 pair 的根和方向。
37
+ moredrive-sync pair add docs remote:/docs "$HOME/Documents/MoreDrive/docs" --direction remote-to-local
38
+ moredrive-sync once --pair docs --direction remote-to-local --dry-run --json
39
+ # 阅读 plan.actions 后,在计划符合预期时执行:
40
+ moredrive-sync once --pair docs --direction remote-to-local --json
41
+ moredrive-sync status --pair docs --json
42
+ ```
43
+
44
+ 上面隐藏输入会按 bash/zsh 自动选择语法。登录的 JSON 输出可能含账号信息,不要原样分享。若不希望保存 pair,也可将 `--pair docs` 替换为 `remote:/docs "$HOME/Documents/MoreDrive/docs"`,但后续恢复要保持原根、配置与状态库。
45
+
46
+ PowerShell 使用 `$env:MOREDRIVE_CONFIG = "$HOME/.config/moredrive/config.json"`,目录创建用 `New-Item -ItemType Directory -Force "$HOME/Documents/MoreDrive/docs"`。Sync 命令本身相同;密码输入可用 `$mdPassword = Read-Host -MaskInput`(PowerShell 7.1+),`$mdPassword | moredrive login --username YOUR_USERNAME --password-stdin --save --json` 后 `Remove-Variable mdPassword`。原生程序若不在 PATH,PowerShell 用 `& 'C:\完整路径\moredrive-sync.exe' ...` 调用。不要把 bash 的环境变量赋值或续行语法直接粘贴到 PowerShell。
47
+
48
+ dry-run 会读取目录和必要内容以规划,不写同步文件、不创建/迁移持久状态库;登录过期时仍可能刷新共享配置。`pair add` 本身保存 DB 记录,并不传输文件。执行报告 `dryRun: false`、`status: up-to-date` 且退出码 0 才表示本轮完成;`planned` 是预览,冲突、待删除批准、恢复中和暂停均未完成。还应检查逐项 `results`、可选 `errors` 与 status;参见[输出说明](json-contract.md)。
49
+
50
+ ## 选择其他方向
51
+
52
+ 参数顺序始终是 **远端目录、本地目录**,上传时也不对调。两端根先建好;每个例子使用不同根,避免和已有 pair 重叠。
53
+
54
+ ```sh
55
+ moredrive-sync pair add uploads remote:/uploads "$HOME/Documents/MoreDrive/uploads" --direction local-to-remote
56
+ moredrive-sync once --pair uploads --direction local-to-remote --dry-run --json
57
+ moredrive-sync once --pair uploads --direction local-to-remote --json
58
+
59
+ moredrive-sync pair add shared remote:/shared "$HOME/Documents/MoreDrive/shared" --direction bidirectional
60
+ moredrive-sync once --pair shared --direction bidirectional --dry-run --json
61
+ moredrive-sync once --pair shared --direction bidirectional --json
62
+ ```
63
+
64
+ 默认不传播删除,冲突默认保留双方供后续解决。首次使用不启用删除传播。更改已绑定方向、账号或根必须先检查状态与未决工作,确实要改变时才使用 `--rebind`;它不是通用排障开关。
65
+
66
+ ## 日常运行
67
+
68
+ `once` 处理本轮发现的固定任务集合,默认执行上限 86400 秒,到期保留未决工作;新出现的文件留给下轮。`watch` 周期扫描并保持前台运行:
69
+
70
+ ```sh
71
+ moredrive-sync watch --pair docs --direction remote-to-local --interval 10m --jsonl
72
+ ```
73
+
74
+ Ctrl+C 停止前台进程;重启继续使用同一 pair、配置与 DB。后台持续同步用 `daemon run` 或服务注册,详见[命令](commands.md)。限速在[配置](config.md)的 `sync.transfer` 下设置,修改后重启进程。遇到异常先查[排障](troubleshooting.md),保留 DB、历史与工作区。
@@ -0,0 +1,38 @@
1
+ # Sync JSON / JSONL 与完成判定
2
+
3
+ `--json`、`--jsonl` 互斥。帮助是人工文本;普通命令的 stdout 不附带文档提示。stderr 独立消费,不能混入 JSON 解析。输出可能包含本地路径,分享前脱敏。
4
+
5
+ ## v2 单次同步
6
+
7
+ 显式 `--direction`(包括 remote-to-local)、`--verify-content`、`--rebind`、`--delete-policy` 等新模式参数选择 v2;已保存的非下载方向 pair 也使用 v2。为自动化明确输出形状,可显式指定所需方向。例:
8
+
9
+ ```sh
10
+ moredrive-sync once --pair docs --direction remote-to-local --json
11
+ ```
12
+
13
+ v2 报告直接包含 `schemaVersion: moredrive.sync.v2`、`pairId`、`generation`、`dryRun`、`status`、`plan`、`results`,不是普通 CLI 的 `ok/data` 外壳。逐项结果有 `path/status/reason`,可选 `errors` 保留详细故障。`plan.actions` 包含动作、原因及 `logical_bytes`,`plan.deletion_hash` 表示特定删除集合。统计还包括扫描数量、`verificationBytes`、`bytesDownloaded`、`bytesTransferred`、`localReads`、`payload`;核验字节不能当作全部进程 IO,传输字节也不等于已完成逻辑字节。
14
+
15
+ | v2 once 状态 | 退出码 | 判定 |
16
+ | --- | --- | --- |
17
+ | `up-to-date` | 0 | 本批次完成;检查逐项结果与错误 |
18
+ | `planned` | 0 | dry-run 计划完成,尚未执行 |
19
+ | `conflict`、`pending-deletion`、`recovering`、`paused` | 2 | 未完成;保留原状态继续处理 |
20
+ | `blocked` 或其他失败状态 | 1 | 受阻/失败,检查原因 |
21
+
22
+ 新模式的顶层错误也可能是 `ok: false` 的错误对象,而非 run 报告;不能假设每个对象都有 `plan`。参数解析错误使用 clap 文本并退出 2,不是同步冲突。结合实际 JSON 内容和退出码分类。
23
+
24
+ v2 once 的 `--jsonl` 当前输出一个完整报告行;watch 会随轮次持续输出报告/错误,不采用 CLI 的唯一顶层 `result` / `failed` 事件协议。不要以“出现一行”或“进程退出 0”推断所有 watch/daemon 任务成功;检查每个 pair 当前状态和未决工作。
25
+
26
+ ## 兼容 v1 路径
27
+
28
+ 未显式选新模式的默认 remote-to-local 仍使用 `moredrive.sync.v1` 外壳,含 `ok`、`data.summary` 等字段。退出码通常成功 0、错误 1(顶层 recovering 可为 2)。**`ok: true` 不能单独证明没有未决冲突**:keep-both 可能保留双方而没有增加 failed 计数。检查 `summary.conflicts`、`failed`,再查绑定的 status / conflict;新脚本优先显式方向使用 v2。
29
+
30
+ v1 JSONL 有 `run.started`、扫描/计划事件、`run.completed` 或 `run.failed`,最后 `run.summary`;错误对象可能提前结束流程。当前共享执行器不保证逐文件实时进度事件。流截断或只有开始事件都不代表成功。
31
+
32
+ `upload-once` 保留 v1 外壳。成功时可有 `data.historyPairId`,用于历史 list/restore;dry-run 不创建持久上传绑定。未决上传用同一命令恢复。
33
+
34
+ `pair list`、`status` 等命令的形状随绑定/方向有所区别;v2 status 可带 `runtime`、`work`、时间线和累计统计。读取实际 `schemaVersion` 后按命令解析,不将所有响应当作 run 报告。`doctor` 要检查全部 `checks`;服务管理还可能输出人工文本,不能假定所有命令都有统一 JSON 外壳。
35
+
36
+ ## schema 边界
37
+
38
+ 源码目录中保留的 `contracts/schemas` 与 fixtures 是历史工程材料。现有 v2 schema 对额外字段有限制,与当前新增统计/工作状态等输出不完全匹配;本说明不推荐用它们校验当前全量输出,也不将其随用户包发布。当前以本版命令行为和上述字段含义为准。本任务不新增 schema 查询接口、不修改全部历史 schema。
@@ -0,0 +1,21 @@
1
+ # 媒体模式与升级
2
+
3
+ 新建 pair 默认 `mediaMode: auto`;已有 DB 或配置缺少模式字段时为 raw。pair 模式不继承 CLI profile 的默认值;once/watch/daemon 使用同一持久模式。原件传输仍走既有直传/下载通道。
4
+
5
+ ```sh
6
+ moredrive-sync pair add photos remote:/photos /absolute/local/photos --direction bidirectional --media-mode auto
7
+ moredrive-sync once --pair photos --dry-run
8
+ moredrive-sync once --pair photos
9
+ ```
10
+
11
+ auto 本地必须为明文,远端按新项的有效目录策略选择普通或 `.__md1x` 弱媒体形式。已有对应不随策略关闭变为普通文件;普通对应遇必须加密的新策略会阻断该项。转换、未知标记、名称碰撞失败不会退回 raw,不会推进基线;无关项继续。审计、冲突、重命名及历史恢复保留两侧各自的字节证据。
12
+
13
+ pair 配置字段为 `mediaMode`、`thumbnails`(auto/off)和 `decoderPath`(绝对路径)。`pair add` 支持 `--media-mode`、`--thumbnails`、`--decoder`。pair decoder 优先于绑定 profile 的 `media.decoderPath`。Sync 内置 JPEG/PNG/WebP 图片缩略图;视频需要用户提供兼容 FFmpeg。不会搜索 PATH、自动下载 FFmpeg,也不依赖 CLI/Node/Desktop。
14
+
15
+ 已有 DB pair 也可以通过配置文件中同名 pair 的 `thumbnails`、`decoderPath` 调整后续运行;这些字段有配置来源时以配置为准(缺省分别为 auto、未指定),没有配置来源时使用 DB 保存值。once/watch/daemon 和恢复入口采用相同读取规则。`mediaMode` 必须与 DB/绑定一致,不能用配置覆盖模式;模式冲突或配置错误会在历史恢复、冲突解决等写操作前停止。已归档 pair 的显式历史恢复沿用原绑定模式,不重新启用调度。
16
+
17
+ 封面仅在本次新上传成功后生成,本批本地源直接读取,不追加源快照或摘要校验。输出 `thumbnails` 独立于原件结果;缺依赖、解码失败、预算耗尽等显示未完成,原件仍成功。失败后显式补图,无变化轮次、重启或更改 decoder 不自动重试。off 不生成新封面,但已发起的 generation/包切换仍须对账或安全回退。真实缩略图包仅从 auto 自动调度中排除,raw 与 CLI 显式下载仍保留原名原字节。
18
+
19
+ 模式不能原位更改。需要不同模式时:停止 watch/daemon → 完成或处置未决原件/包操作 → `pair remove <旧名称>` 清理配置来源并归档绑定 → 使用新名称新建 pair → dry-run/首次检查。disable 不释放端点,不删除 DB 来绕过绑定。保留历史、冲突与恢复材料;首次已有两端内容需要核验,不能移植旧基线。
20
+
21
+ 状态库升级为 schema 4,旧记录按 raw 保留,旧 binary 会拒绝新状态。回退前停止所有调度,保全升级后的 DB、配置和在途记录,核对升级后的远端修改;不要恢复旧 DB 后直接启动旧程序。
@@ -0,0 +1,61 @@
1
+ # Sync State DB
2
+
3
+ The sync client stores pair metadata, run history, entry fingerprints, tasks, errors, and conflicts in SQLite.
4
+
5
+ Default paths:
6
+
7
+ | Platform | Path |
8
+ | --- | --- |
9
+ | macOS | `~/Library/Application Support/MoreDrive/sync/state.db` |
10
+ | Linux | `~/.local/state/moredrive/sync/state.db` |
11
+ | Windows | `%LOCALAPPDATA%\\MoreDrive\\sync\\state.db` |
12
+
13
+ Override with:
14
+
15
+ ```bash
16
+ moredrive-sync --state-db ./tmp/sync-state.db status --json
17
+ ```
18
+
19
+ Tables:
20
+
21
+ - `schema_migrations`
22
+ - `sync_pairs`
23
+ - `sync_entries`
24
+ - `sync_runs`
25
+ - `sync_tasks`
26
+
27
+ Users should not edit this DB directly. Do not delete or replace it to bypass unfinished work. Before any backup or maintenance, stop all watch/daemon/service executors and use a consistent SQLite backup including committed WAL data.
28
+
29
+ Health check:
30
+
31
+ ```bash
32
+ moredrive-sync doctor --json
33
+ ```
34
+
35
+ ## 当前迁移与恢复
36
+
37
+ 当前 schema 为 4(包括范围/忽略规则、pair 媒体模式和两侧表示证据;旧 pair 保持 raw)。Schema 2 adds verified two-sided baselines, root/account bindings, missing
38
+ observations, history and per-pair runtime records. Durable remote intents and
39
+ entry/conflict jobs extend `sync_tasks`. Old `sync_entries` remain historical
40
+ weak evidence and cannot authorize deletion. Current legacy download commands
41
+ use the same verified baselines as new modes.
42
+
43
+ Before upgrading a persistent v1/v2 DB, SQLite `VACUUM INTO` creates a consistent
44
+ `state.db.v<old-version>-backup-UUID.db` snapshot including committed WAL data, then schema
45
+ changes commit in one transaction. Older binaries reject a schema newer than they support. Keep the
46
+ backup for downgrade; stop all executors and disable automatic scheduling before
47
+ restoring it. Treat restored observations as stale and perform a complete
48
+ content review before enabling propagation. Never replace a live DB or combine
49
+ it with another DB's WAL/SHM files.
50
+
51
+ Dry-run opens existing state read-only and never migrates it; if no DB exists,
52
+ planning uses memory. Generation changes invalidate old missing observations
53
+ and deletion approvals. For a strategy/ignore change with identical direction,
54
+ roots and account, strong synchronization facts are retained, while fresh
55
+ missing observations must satisfy the new generation's 30-second rule. Account,
56
+ root or direction rebinding cannot inherit those facts for deletion authority.
57
+
58
+ Case-only 文件或目录改名使用既有 work-record 存储中的 `v2-case-rename`:原/新相对路径、共同 generation、两端原观察、owned staging 位置、两个持久 move intent 及 prepared/staged/published/committed 阶段。只有唯一身份和实际内容都与共同基线相符才规划;未知移动不换 key 重提。目标抢占时保留中间候选并阻止覆盖,完成后将新路径确认基线并将旧拼写记作 tombstone。目录还在同一 work record 的可选 `tree` 中保存两端完整子树的相对路径、强身份及文件实际 SHA;恢复时重新核对来源和保留候选,发现新增、缺失或改写子项即停止。移动导致不透明元数据变化时须重新读内容确认,不将新元数据直接当内容证明。最终完整核验后,一次 SQLite 事务提交根和所有子项的新 B / 旧拼写 tombstone;旧文件 record 缺该字段仍可恢复。
59
+
60
+
61
+ 共同baseline JSON可含 `local_cache_safe`,缺省false。它证明该本地观察的SHA在mtime/ctime稳定期之后实际读取过;不改变版本、内容等价、冲突ID或删除授权。相同共同本地版本的证据升级批量事务落盘;旧记录及从未决任务恢复的瞬时观察必须重新核验,不能把经过的时间当证据。运行内Observation证据标志不写入写意图和输出合同。
@@ -0,0 +1,45 @@
1
+ # Sync 常见问题
2
+
3
+ 先保留错误输出与退出码,用同一 `--config`、`--state-db` 和 pair 检查:
4
+
5
+ ```sh
6
+ moredrive-sync pair list --json
7
+ moredrive-sync status --pair docs --json
8
+ moredrive-sync doctor --pair docs --json
9
+ ```
10
+
11
+ `doctor` 会检查本地状态并访问远端;帮助不需要登录、不启动同步。日志分享前去除凭据、原始 dlink 和不应公开的路径。不要输出整个配置。
12
+
13
+ ## 登录失效或 profile 缺失
14
+
15
+ 检查实际配置路径、profile 名及文件权限。Sync 不读取 `MOREDRIVE_TOKEN`;有效 refreshToken 会自动刷新,无法刷新时使用 CLI 对同一配置重新登录:
16
+
17
+ ```sh
18
+ moredrive login --username YOUR_USERNAME --password-stdin --save --json
19
+ ```
20
+
21
+ 密码经 stdin 安全输入并关闭输入流;具体 shell 示例见[上手](getting-started.md)。重新登录后恢复原命令;若登录成不同账号,不强行 `--rebind` 继续原任务。持续认证错误不做无界重试。
22
+
23
+ ## 本地或远端根缺失
24
+
25
+ 首次同步之前创建两端目录并确认权限;已绑定的根突然缺失通常应先恢复原磁盘/网络挂载或原目录,不能当作整树删除。重建同名空目录不一定保留根身份。检查远端可用 CLI `moredrive ls /docs --json`,或网盘界面。
26
+
27
+ 被判定替换、身份变化的根先 `root review --pair docs` 查看;确认是用户意图且未决工作可处理后,按帮助使用精确确认或 `--rebind`。不要默认确认,也不要用新 pair 绕过保护。
28
+
29
+ 重叠根优先改为独立目录。`--allow-overlap` 只用于明确需要的登记,不保证所有运行时互斥检查都会放行。符号链接遍历仍被拒绝,`--follow-symlinks` 不是绕过开关。
30
+
31
+ ## 空间不足或历史预算耗尽
32
+
33
+ 分别检查本地目标盘、源工作区盘、远端可用空间,以及报告中的 staging/history 预算。新增、替换和保留历史可能同时占用空间。清理与本任务无关且允许删除的材料,或按需要提高 `sync.transfer.stagingBudgetBytes` / pair 的 `--history-budget BYTES`;配置修改后重启。不要通过删除 `.moredrive-sync`、未决候选或数据库释放恢复材料。
34
+
35
+ 需要释放已完成历史时,先 `history list --pair docs`,再 `history release HISTORY_ID --pair docs` 只读预览;确认选定历史可以永久删除后,传该预览的精确 `--confirm` 值。没有自动淘汰历史。保留中的候选先 `candidate list --pair docs`,仅按当前帮助和明确授权处置。
36
+
37
+ ## 冲突与删除待批准
38
+
39
+ 见[删除与冲突](delete-and-conflict-policy.md)。keep-both 只是保留版本,不能宣布冲突已解决。目录与文件冲突需要人工检查;不递归删除目录为文件让路。
40
+
41
+ ## 中断、恢复中与状态库错误
42
+
43
+ 重启原命令,保持同一配置、账号、pair、状态库、两端根及工作区。恢复会核对原候选和提交结果;上传响应丢失不等于失败,不能换 key 重新提交。`recovering` / `unknown` 期间保留状态,检查具体原因;确定性错误未经修复不重复重试。
44
+
45
+ 状态库错误时停止相关 watch/daemon/service,先做一致性备份并检查磁盘、权限和版本兼容性。不要改用空 DB、清库、删除工作区或手改 SQLite 来跳过未决状态。升级/备份规则见[状态库](state-db.md)。需要进一步诊断时,优先针对出错路径进行有界核验;全量 audit 或全文回读不是默认恢复步骤。
package/package.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
- "version": "1.2.0",
2
+ "version": "1.5.0",
3
3
  "license": "UNLICENSED",
4
4
  "publishConfig": {
5
5
  "access": "public",
6
6
  "registry": "https://registry.npmjs.org/"
7
7
  },
8
8
  "name": "@moredrive/sync",
9
- "description": "MoreDrive remote-to-local synchronization client",
9
+ "description": "MoreDrive directory synchronization and recovery client",
10
10
  "type": "module",
11
11
  "engines": {
12
12
  "node": ">=22"
@@ -18,11 +18,12 @@
18
18
  "bin/",
19
19
  "*.md",
20
20
  "docs/",
21
+ "skills/",
21
22
  "build-info.json"
22
23
  ],
23
24
  "optionalDependencies": {
24
- "@moredrive/sync-darwin-arm64": "1.2.0",
25
- "@moredrive/sync-win32-x64": "1.2.0",
26
- "@moredrive/sync-linux-x64": "1.2.0"
25
+ "@moredrive/sync-darwin-arm64": "1.5.0",
26
+ "@moredrive/sync-win32-x64": "1.5.0",
27
+ "@moredrive/sync-linux-x64": "1.5.0"
27
28
  }
28
29
  }
@@ -0,0 +1,33 @@
1
+ ---
2
+ name: moredrive-sync
3
+ description: 使用 MoreDrive Sync 执行目录单向或双向同步、保存 pair、持续同步、查看冲突和恢复中断任务。普通网盘文件操作、登录和显式媒体转换查阅 MoreDrive CLI。
4
+ ---
5
+
6
+ # MoreDrive Sync
7
+
8
+ 先运行当前程序的 `--version`、`--help` 和相关子命令 `--help`。使用帮助显示的包内 Skill 路径阅读本文件;引用相对此文件解析。本期不自动安装到 agent 目录,也不保证单独复制本 Skill 后文档仍可达。
9
+
10
+ ## 选择并执行
11
+
12
+ 1. 读取[上手流程](../../docs/getting-started.md)与[配置](../../docs/config.md)。Sync 自身读取配置 profile,不读取 CLI 的 `MOREDRIVE_TOKEN`;复用现有配置时显式指定路径。登录由普通 CLI 辅助完成,Sync 运行不需要 CLI 常驻。
13
+ 2. 用 `pair list --json`、`status --pair NAME --json` 检查已有绑定、方向和未决任务;沿用同一配置、pair、DB 和工作区。新 pair 的 `pair add` 默认启用;如有使用同一配置/DB 的 daemon 或服务运行,先停止该后台执行器再预览,避免尚未审阅就开始同步。确认两端目录存在,按用户意图选择 `remote-to-local`、`local-to-remote` 或 `bidirectional`。方向不明确时才澄清。
14
+ 3. 先执行对应 `once --dry-run --json`。显式指定 `--direction` 可使用信息更完整的 v2 报告;检查路径、动作、冲突和删除计划。dry-run 是只读计划,不是已完成同步,也不会保存删除批准所需的新计划。
15
+ 4. 在已有授权范围内执行同一 pair 的 `once` 或 `watch`,不要机械重复确认。删除传播、改变绑定、冲突取舍和历史永久释放须符合用户意图及命令要求;不能用 `--yes` 绕过精确计划批准。命令详见[命令索引](../../docs/commands.md)。
16
+
17
+ ## 判断结果
18
+
19
+ 按[输出说明](../../docs/json-contract.md)解析实际 `schemaVersion`、退出码、状态和逐项结果。不要套用普通 CLI 的 `ok/data` 或 `result/failed` 终止事件规则。
20
+
21
+ - v2 `once` 的 `up-to-date` 且退出 0 才表示该批次完成;`planned` 仅表示计划完成。`conflict`、`pending-deletion`、`recovering`、`paused` 均未完成。查看 `results` 和可选 `errors`。
22
+ - v1 即使 `ok: true` 也要查看冲突计数及 pair 状态。不要把 keep-both 的保留副本报告为已解决冲突。
23
+ - watch/daemon 是持续进程;持续消费 stdout/stderr,按轮次与 pair 判断结果。进程启动或正常停止不能证明全部同步成功。不要默认追加全量审计、`--verify-content` 或全文回读。
24
+
25
+ ## 恢复与处置
26
+
27
+ 按[排障](../../docs/troubleshooting.md)、[删除与冲突](../../docs/delete-and-conflict-policy.md)、[状态库](../../docs/state-db.md)处理。登录失效先修复原 profile;根缺失先恢复原挂载/目录;空间不足先检查磁盘、staging 和历史预算。保留原未决意图及恢复材料,不通过清库、换 pair 或删除工作区跳过未决任务。
28
+
29
+ 先读取冲突详情再选择 `local|remote|both`;历史恢复目标必须不存在。历史释放先无 `--confirm` 预览,再使用该预览的精确确认值;只释放用户授权的条目。失去响应时沿原命令对账,不换 key 无限重试。相同确定性错误未经修复不重试;网络暂态只做有界重试。
30
+
31
+ 凭据只经安全输入或配置传递,不输出 token、密码、原始 dlink 或完整配置。分享日志前检查本地路径及账号信息。新 pair 默认 auto,旧 pair 缺字段为 raw。auto 固定本地明文,对远端支持标记自动转换;本地密文请使用独立 raw pair。不能原位改模式,须停止调度、完成未决操作、pair remove 归档后新建。详见[媒体模式与升级](../../docs/media-v1.5.md)。
32
+
33
+ pair 支持 `--media-mode auto|raw`、`--thumbnails auto|off`、`--decoder <absolute-path>`;decoder 优先于 profile 的 `media.decoderPath`,不搜索 PATH、不自动安装。Sync 图片内置解码,视频需兼容 FFmpeg。`thumbnails` 结果独立于原件完成状态:失败显式补图,无变化/重启不自动重试;off 仍保留已发起包操作对账及安全回退。不要把本地生成、未确认发布说成封面已完成。
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "MoreDrive Sync"
3
+ short_description: "目录同步、保存同步对、检查冲突与恢复中断任务的操作指南"
4
+ default_prompt: "使用 $moredrive-sync 检查现有同步对,预览计划并按我的意图完成同步。"