@anytowork/cli 0.12.20 → 0.12.22

package/src/space-sync.js

@@ -0,0 +1,608 @@
+// Sync engine for the space and for a task's workspace (v0.31, CLI 0.12.21).
+//
+// Plain words: the Agent pulls a folder to its own computer, edits it with its own tools, and pushes back only what
+// changed. The same engine serves both sides, only the addresses differ:
+//   * the owner's own Agent  -> /space/sync/*            (changes go straight into the owner's space)
+//   * the seller's Agent     -> /tasks/{id}/workspace/*  (changes are only recorded on the task until accepted)
+//
+// How "only the changes" works: every file is compared by its content fingerprint (sha256). A small state file
+// (STATE_FILE) is written into the local folder on every pull, listing the fingerprint each file had when it was
+// pulled. A push sends only files whose fingerprint differs from that list (plus brand new ones), and tells the
+// platform which version each edit started from (base_sha256) so the platform can spot a clash with someone else's
+// later edit. Nothing is ever pushed for files that did not change - that would overwrite newer remote content.
+import fs from 'node:fs';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { authedGetWithRefresh, authedPostWithRefresh } from './api.js';
+import { uploadMultipart, MULTIPART_THRESHOLD } from './multipart-upload.js';
+import { atomicWriteFile } from './atomic-write.js';
+import { mimeFor } from './file-deliver.js';
+import { flatBodyOf } from './error-map.js';
+import { describeStorageFailure, classifyStorageFailure } from './storage-put.js';
+
+/** Hidden file inside the local folder that remembers what each file looked like when it was pulled. */
+export const STATE_FILE = '.anytowork-sync.json';
+const PART_SUFFIX = '.anytowork-part';
+const SIGN_BATCH = 50;            // download addresses asked for at once (the platform allows up to 200)
+const DOWNLOAD_CONCURRENCY = 3;
+const UPLOAD_CONCURRENCY = 2;
+const HASH_CONCURRENCY = 3;
+const DOWNLOAD_RETRIES = 3;
+const MAX_RATE_RETRIES = 5;       // how many times a 429 is waited out before giving up
+const MAX_WAIT_S = 120;           // longest single wait on a 429
+const DEFAULT_WAIT_S = 5;         // used when the platform does not say how long to wait
+
+const defaultSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** A problem found on this machine or in the transfer itself (not a platform refusal). `exit` is the process code. */
+export class SyncError extends Error {
+  constructor(message, { code = 'sync_failed', exit = 1, extra = {} } = {}) {
+    super(message);
+    this.name = 'SyncError';
+    this.code = code;
+    this.exit = exit;
+    this.extra = extra;
+  }
+}
+
+// ---------------------------------------------------------------- platform calls (with 429 back-off)
+
+/** Seconds the platform asked us to wait: the body's retry_after, else the Retry-After header, else a default. */
+export function retryAfterSeconds(e) {
+  const body = flatBodyOf(e);
+  const n = Number(body.retry_after != null ? body.retry_after : e && e.retryAfter);
+  return Number.isFinite(n) && n > 0 ? Math.min(MAX_WAIT_S, Math.ceil(n)) : DEFAULT_WAIT_S;
+}
+
+/**
+ * Run one platform call; on 429 wait for as long as the platform said (retry_after) and try again.
+ * ctx: { sleep?, progress? }. Any other error, or too many 429s in a row, is thrown as it is.
+ */
+export async function withBackoff(ctx, fn) {
+  const sleep = ctx.sleep || defaultSleep;
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await fn();
+    } catch (e) {
+      if (!e || e.status !== 429 || attempt >= MAX_RATE_RETRIES) throw e;
+      const wait = retryAfterSeconds(e);
+      if (ctx.progress) ctx.progress(`请求太频繁，${wait} 秒后自动重试…`);
+      await sleep(wait * 1000);
+    }
+  }
+}
+
+function qs(params) {
+  const sp = new URLSearchParams();
+  for (const [k, v] of Object.entries(params || {})) if (v != null && v !== '') sp.set(k, String(v));
+  const s = sp.toString();
+  return s ? `?${s}` : '';
+}
+
+// ctx.headers: extra request headers (v0.32: `anytowork space` sends the workbench session, see space-commands.js)
+export function apiGet(ctx, pathAndQuery) {
+  return withBackoff(ctx, () => authedGetWithRefresh(ctx.baseUrl, pathAndQuery, ctx.credOpts, { fetchImpl: ctx.fetchImpl, headers: ctx.headers }));
+}
+
+export function apiPost(ctx, pathStr, body) {
+  return withBackoff(ctx, () => authedPostWithRefresh(ctx.baseUrl, pathStr, ctx.credOpts, body, null, { fetchImpl: ctx.fetchImpl, headers: ctx.headers }));
+}
+
+/** The fetch used for the object storage (signed addresses carry their own credentials, no login header). */
+function storageFetch(ctx) {
+  return ctx.putFetch || ctx.fetchImpl || globalThis.fetch;
+}
+
+// ---------------------------------------------------------------- what the user sees when the platform says no
+
+const HINTS = {
+  space_full: () => ['本地改动没有丢。请告诉主人去空间清理历史版本或删掉不用的文件，清理后重新运行同一条命令。'],
+  download_quota: (v) => [
+    `主人本月的下载额度已用完${v.resume_on ? `，${v.resume_on} 恢复` : ''}。请告诉主人；已经拉到本地的文件不受影响，恢复后重新运行同一条命令。`,
+  ],
+  workspace_push_too_large: () => ['已经记下的改动不受影响。请减少这次要推送的内容后重新运行同一条命令。'],
+  workspace_push_closed: () => ['这单现在不在进行中（已交付待验收期间只能拉取，不能推送）。对方请你改稿后才能再推送。'],
+  workspace_window_closed: () => ['这单的工作空间只在选定你接单之后、任务结束之前可以访问。'],
+  not_task_seller: () => ['只有这单当前的接单方可以访问它的工作空间。'],
+  push_expired: () => ['这次推送已过期（超过 24 小时没有提交），本地改动没有丢，重新运行同一条命令即可。'],
+  push_incomplete: (v) => [
+    `有文件没传完，这次的改动没有提交：${(v.paths || []).join('、')}`,
+    '本地改动没有丢，重新运行同一条命令即可。',
+  ],
+  rate_limit_exceeded: () => ['已按平台要求自动等待重试，仍然太频繁。请稍后重新运行同一条命令。'],
+};
+
+/**
+ * Turn a platform refusal into lines for the screen: the platform's own words first (unchanged), then at most one
+ * short line saying what to do. Returns null for errors that are not a platform refusal with a stable code.
+ */
+export function describeApiError(e) {
+  const body = flatBodyOf(e);
+  const code = typeof body.error === 'string' ? body.error : null;
+  if (!code) return null;
+  const vars = body.vars && typeof body.vars === 'object' ? { ...body, ...body.vars } : body;
+  const lines = [`${body.message || code}【${code}】`];
+  if (HINTS[code]) for (const h of HINTS[code](vars)) lines.push(`  ${h}`);
+  return { code, message: body.message || '', lines, body };
+}
+
+// ---------------------------------------------------------------- local files
+
+export function normalizeRemotePath(p) {
+  return String(p == null ? '' : p).trim().replace(/\\/g, '/').replace(/^\/+|\/+$/g, '').normalize('NFC');
+}
+
+/** Join a remote relative path onto a local folder; refuses anything that would land outside it. */
+export function safeJoin(root, rel) {
+  const parts = String(rel).split('/');
+  if (!rel || path.isAbsolute(rel) || parts.some((s) => s === '..' || s === '' )) return null;
+  const abs = path.join(root, ...parts);
+  return abs.startsWith(root + path.sep) ? abs : null;
+}
+
+export async function hashFile(abs) {
+  const h = createHash('sha256');
+  await new Promise((resolve, reject) => {
+    const s = fs.createReadStream(abs);
+    s.on('data', (c) => h.update(c));
+    s.on('error', reject);
+    s.on('end', resolve);
+  });
+  return h.digest('hex');
+}
+
+/** Run `worker` over `items` with at most n at once; the first failure stops handing out new items and is thrown. */
+export async function pool(items, n, worker) {
+  const queue = items.slice();
+  let failure = null;
+  const run = async () => {
+    while (!failure) {
+      const item = queue.shift();
+      if (item === undefined) return;
+      try { await worker(item); } catch (e) { failure = e; return; }
+    }
+  };
+  await Promise.all(Array.from({ length: Math.max(1, Math.min(n, items.length)) }, run));
+  if (failure) throw failure;
+}
+
+/**
+ * Walk a local folder. Returns the regular files (with absolute path and size), the folders that hold nothing, and
+ * what was left out (symlinks, sockets...). Names are compared in NFC because the platform stores NFC.
+ */
+export async function scanLocal(root) {
+  const files = new Map();
+  const emptyFolders = [];
+  const skipped = [];
+  async function walk(absDir, relDir) {
+    const entries = await fsp.readdir(absDir, { withFileTypes: true });
+    let seen = 0;
+    for (const ent of entries) {
+      if (ent.name === STATE_FILE || ent.name.endsWith(PART_SUFFIX)) continue;
+      const rel = (relDir ? `${relDir}/${ent.name}` : ent.name).normalize('NFC');
+      const abs = path.join(absDir, ent.name);
+      if (ent.isSymbolicLink()) { skipped.push({ path: rel, reason: 'symlink' }); continue; }
+      if (ent.isDirectory()) { seen += 1; await walk(abs, rel); continue; }
+      if (ent.isFile()) {
+        seen += 1;
+        const st = await fsp.stat(abs);
+        files.set(rel, { abs, size: st.size });
+        continue;
+      }
+      skipped.push({ path: rel, reason: 'special' });
+    }
+    if (seen === 0 && relDir) emptyFolders.push(relDir.normalize('NFC'));
+  }
+  await walk(root, '');
+  return { files, emptyFolders, skipped };
+}
+
+// ---------------------------------------------------------------- state file
+
+/** What the last pull / push left in the folder; null when there is none (or it is unreadable). */
+export function readState(dir) {
+  try {
+    const s = JSON.parse(fs.readFileSync(path.join(dir, STATE_FILE), 'utf8'));
+    if (s && s.version === 1 && s.files && typeof s.files === 'object') return s;
+  } catch { /* no state yet */ }
+  return null;
+}
+
+export function writeState(dir, state) {
+  atomicWriteFile(path.join(dir, STATE_FILE), JSON.stringify(state, null, 1), 0o644);
+}
+
+/** A folder already tied to one remote place must not be reused for another: that would mix two places up. */
+function checkStateTarget(state, target) {
+  if (state && (state.kind !== target.kind || state.remote !== target.remote)) {
+    throw new SyncError(
+      `这个本地目录已经和${state.kind === 'task' ? '任务' : '空间'}「${state.remote || '/'}」同步过，不能再用来同步「${target.remote || '/'}」。请换一个空目录。`,
+      { code: 'dir_in_use', exit: 2 },
+    );
+  }
+}
+
+// ---------------------------------------------------------------- where to talk to
+
+/** The owner's own space (or a folder of it): used by the owner's Agent. */
+export function spaceTarget(spacePath) {
+  const remote = normalizeRemotePath(spacePath);
+  return {
+    kind: 'space',
+    remote,
+    label: remote || '空间根目录',
+    manifestUrl: (q) => `/api/v1/space/sync/manifest${qs({ path: remote, ...q })}`,
+    downloadUrls: '/api/v1/space/sync/download-urls',
+    pushUrl: '/api/v1/space/sync/push',
+    commitUrl: (pushId) => `/api/v1/space/sync/push/${pushId}/commit`,
+    uploadStartUrl: '/api/v1/space/uploads',
+    uploadCompleteUrl: (fileId) => `/api/v1/space/uploads/${fileId}/complete`,
+    multipartBase: '/api/v1/space/uploads/multipart',
+    pushBody: ({ mode, note }) => ({ path: remote, mode, ...(note ? { note } : {}) }),
+  };
+}
+
+/** The workspace folder of one task: used by the seller's Agent. The folder itself is the root. */
+export function taskTarget(taskId) {
+  const base = `/api/v1/tasks/${encodeURIComponent(taskId)}/workspace`;
+  return {
+    kind: 'task',
+    remote: String(taskId),
+    label: `任务 ${taskId} 的工作空间`,
+    manifestUrl: (q) => `${base}/manifest${qs(q)}`,
+    downloadUrls: `${base}/download-urls`,
+    pushUrl: `${base}/push`,
+    commitUrl: (pushId) => `${base}/push/${pushId}/commit`,
+    uploadStartUrl: `${base}/uploads`,
+    uploadCompleteUrl: (fileId) => `${base}/uploads/${fileId}/complete`,
+    multipartBase: `${base}/uploads/multipart`,
+    // the folder is the root, so there is no path to name and no mode / note to give
+    pushBody: () => ({ path: '' }),
+  };
+}
+
+// ---------------------------------------------------------------- manifest
+
+/**
+ * Read the whole list of files under the target, page by page. Every page after the first carries `at` = the
+ * snapshot id of the first page, so a file changed in the middle of reading cannot shift the list.
+ */
+export async function fetchManifest(ctx, target) {
+  const files = [];
+  const folders = new Set();
+  let head = null;
+  let root = null;
+  let cursor = null;
+  for (let page = 0; page < 10000; page += 1) {
+    const r = await apiGet(ctx, target.manifestUrl({ at: head, cursor }));
+    if (head == null) head = r.head_change_id != null ? r.head_change_id : null;
+    if (!root) root = r.root || null;
+    for (const f of r.files || []) files.push(f);
+    for (const d of r.folders || []) folders.add(normalizeRemotePath(d));
+    cursor = r.next_cursor || null;
+    if (!cursor) break;
+  }
+  return { files, folders: [...folders], head, root };
+}
+
+// ---------------------------------------------------------------- pull
+
+/**
+ * Fetch one file from its signed address into `abs` (via a part file, so a broken download never leaves a half
+ * file under the real name). Checks size and fingerprint; retries on its own. `resign()` gets a fresh address.
+ * @returns {Promise<string>} the sha256 of what was written
+ */
+async function downloadOne(ctx, url, abs, expect, resign) {
+  const fetchFn = storageFetch(ctx);
+  const tmp = `${abs}${PART_SUFFIX}`;
+  await fsp.mkdir(path.dirname(abs), { recursive: true });
+  let lastMsg = '';
+  let address = url;
+  for (let attempt = 0; attempt <= DOWNLOAD_RETRIES; attempt += 1) {
+    try {
+      const resp = await fetchFn(address, { method: 'GET' });
+      if (!resp.ok) {
+        lastMsg = `存储返回 ${resp.status}`;
+        if (resp.status === 403 && resign) address = await resign(); // the address went stale: ask for a new one
+      } else {
+        const hash = createHash('sha256');
+        let written = 0;
+        const fh = await fsp.open(tmp, 'w');
+        try {
+          if (resp.body && typeof resp.body[Symbol.asyncIterator] === 'function') {
+            for await (const chunk of resp.body) {
+              hash.update(chunk);
+              written += chunk.length;
+              await fh.write(chunk);
+            }
+          } else {
+            const buf = Buffer.from(await resp.arrayBuffer());
+            hash.update(buf);
+            written = buf.length;
+            await fh.write(buf);
+          }
+        } finally {
+          await fh.close();
+        }
+        const digest = hash.digest('hex');
+        if (expect.size != null && written !== expect.size) {
+          lastMsg = `大小不对（收到 ${written}，应为 ${expect.size}）`;
+        } else if (expect.sha256 && digest !== expect.sha256) {
+          lastMsg = '内容校验没通过';
+        } else {
+          await fsp.rename(tmp, abs);
+          return digest;
+        }
+      }
+    } catch (netErr) {
+      lastMsg = `网络错误：${netErr && netErr.message ? netErr.message : netErr}`;
+    }
+    if (attempt < DOWNLOAD_RETRIES) await (ctx.sleep || defaultSleep)(Math.min(8000, 1000 * 2 ** attempt));
+  }
+  try { await fsp.unlink(tmp); } catch { /* nothing to clean */ }
+  throw new SyncError(lastMsg, { code: 'download_failed' });
+}
+
+/**
+ * Pull the target into `dir`.
+ *
+ * What it will and will not touch (so the Agent's own unsent edits are never lost):
+ *   * a file that is missing locally, or untouched since the last pull, is downloaded when the remote changed;
+ *   * a file edited locally since the last pull is kept; if the remote changed too it is listed as a clash and
+ *     only overwritten with `force`;
+ *   * a folder that was never pulled before: files that already exist there with other content count as clashes.
+ *   * files the remote no longer has are removed locally only when untouched since the last pull.
+ *
+ * @returns {Promise<object>} summary: { total, downloaded, upToDate, keptLocal, clashes, removed, notPulled,
+ *                                       failed, bytes, headChangeId, quotaStopped }
+ */
+export async function pull(ctx, target, dir, { force = false } = {}) {
+  const absRoot = path.resolve(dir);
+  const state = readState(absRoot);
+  checkStateTarget(state, target);
+  await fsp.mkdir(absRoot, { recursive: true });
+
+  const manifest = await fetchManifest(ctx, target);
+  const oldFiles = (state && state.files) || {};
+  const newFiles = { ...oldFiles };
+  const summary = {
+    total: manifest.files.length, downloaded: [], upToDate: 0, keptLocal: [], clashes: [], removed: [],
+    keptRemoteDeleted: [], notPulled: [], failed: [], bytes: 0, headChangeId: manifest.head, quotaStopped: false,
+  };
+
+  for (const folder of manifest.folders) {
+    const abs = safeJoin(absRoot, folder);
+    if (abs) await fsp.mkdir(abs, { recursive: true });
+  }
+
+  // 1) decide, file by file, what has to be downloaded
+  const todo = [];
+  await pool(manifest.files, HASH_CONCURRENCY, async (m) => {
+    const rel = normalizeRemotePath(m.path);
+    const abs = safeJoin(absRoot, rel);
+    if (!abs) { summary.failed.push({ path: m.path, reason: '路径不合法' }); return; }
+    let local = null;
+    try {
+      const st = await fsp.stat(abs);
+      if (st.isFile()) local = { size: st.size, sha256: await hashFile(abs) };
+    } catch { /* not there */ }
+    const base = oldFiles[rel] || null;
+    if (!local) { todo.push({ m, rel, abs }); return; }
+    const sameAsRemote = m.sha256
+      ? local.sha256 === m.sha256
+      : Boolean(base && base.blob_id && base.blob_id === m.blob_id && base.sha256 === local.sha256);
+    if (sameAsRemote) {
+      summary.upToDate += 1;
+      newFiles[rel] = { sha256: local.sha256, size: local.size, blob_id: m.blob_id || null };
+      return;
+    }
+    if (force) { todo.push({ m, rel, abs }); return; }
+    const touchedLocally = !base || local.sha256 !== base.sha256;
+    if (!touchedLocally) { todo.push({ m, rel, abs }); return; }           // untouched locally, remote changed
+    const remoteMoved = !base || !m.sha256 || m.sha256 !== base.sha256;     // did the remote change since the pull?
+    if (remoteMoved) summary.clashes.push(rel); else summary.keptLocal.push(rel);
+  });
+  todo.sort((a, b) => (a.rel < b.rel ? -1 : 1));
+
+  // 2) download in small batches: addresses are short-lived, so ask for them right before using them
+  for (let i = 0; i < todo.length && !summary.quotaStopped; i += SIGN_BATCH) {
+    const batch = todo.slice(i, i + SIGN_BATCH);
+    const signed = await apiPost(ctx, target.downloadUrls, {
+      node_ids: batch.map((x) => x.m.node_id),
+      ...(manifest.head != null ? { at: manifest.head } : {}),
+    });
+    const urls = (signed && signed.urls) || {};
+    const ready = [];
+    for (const item of batch) {
+      const u = urls[item.m.node_id];
+      if (u && u.url) ready.push({ ...item, url: u.url });
+      else if (u && u.error === 'download_quota') summary.quotaStopped = true;
+      else summary.failed.push({ path: item.rel, reason: (u && u.error) || '平台没有给出下载地址' });
+    }
+    await pool(ready, DOWNLOAD_CONCURRENCY, async (item) => {
+      const resign = async () => {
+        const again = await apiPost(ctx, target.downloadUrls, {
+          node_ids: [item.m.node_id], ...(manifest.head != null ? { at: manifest.head } : {}),
+        });
+        const u = again && again.urls && again.urls[item.m.node_id];
+        if (!u || !u.url) throw new SyncError('重新取下载地址失败', { code: 'download_failed' });
+        return u.url;
+      };
+      try {
+        const digest = await downloadOne(ctx, item.url, item.abs, { size: item.m.size_bytes, sha256: item.m.sha256 || null }, resign);
+        summary.downloaded.push(item.rel);
+        summary.bytes += item.m.size_bytes || 0;
+        newFiles[item.rel] = { sha256: digest, size: item.m.size_bytes, blob_id: item.m.blob_id || null };
+        if (ctx.progress) ctx.progress(`已拉取 ${summary.downloaded.length}/${todo.length}：${item.rel}`);
+      } catch (e) {
+        if (!(e instanceof SyncError)) throw e;
+        summary.failed.push({ path: item.rel, reason: e.message });
+      }
+    });
+    if (summary.quotaStopped) {
+      for (const item of todo.slice(i)) {
+        if (!summary.downloaded.includes(item.rel) && !summary.failed.some((f) => f.path === item.rel)) summary.notPulled.push(item.rel);
+      }
+    }
+  }
+
+  // 3) files the remote no longer has: drop the local copy only if it is still exactly what was pulled
+  const remoteSet = new Set(manifest.files.map((m) => normalizeRemotePath(m.path)));
+  for (const [rel, base] of Object.entries(oldFiles)) {
+    if (remoteSet.has(rel)) continue;
+    const abs = safeJoin(absRoot, rel);
+    delete newFiles[rel];
+    if (!abs) continue;
+    try {
+      if (await hashFile(abs) === base.sha256) { await fsp.unlink(abs); summary.removed.push(rel); }
+      else summary.keptRemoteDeleted.push(rel);
+    } catch { /* already gone locally */ }
+  }
+
+  // 4) remember the new starting point. Files that were failed, held back or kept local still carry their old entry
+  //    (newFiles began as a copy of the old list), so a later push still knows which version they came from.
+  writeState(absRoot, {
+    version: 1, kind: target.kind, remote: target.remote, head_change_id: manifest.head,
+    pulled_at: new Date().toISOString(), files: newFiles, folders: manifest.folders,
+  });
+  return summary;
+}
+
+// ---------------------------------------------------------------- push
+
+/** Upload one file the platform asked for (action "upload"): one PUT for small files, parts for big ones. */
+async function uploadOne(ctx, target, action, local, rel, { pushId, sha256 } = {}) {
+  const size = local.size;
+  // the platform already counted this size when it made the plan: a file that grew or shrank since would not match
+  const now = await fsp.stat(local.abs);
+  if (now.size !== size) {
+    throw new SyncError(`${rel} 在推送过程中被改动了，这次的改动没有提交。请等它改完后重新运行同一条命令。`, { code: 'file_changed' });
+  }
+  if (!action.file_id) {
+    // The plan only says "upload": reserve the file under this push first (POST .../uploads with push_id). That
+    // gives its id and, for a single PUT, the signed address. The path is relative to the pushed folder, as in the plan.
+    const reserved = await apiPost(ctx, target.uploadStartUrl, {
+      parent_id: null, rel_path: rel, name: rel.split('/').pop(), size_bytes: size,
+      mime_type: mimeFor(rel), sha256: sha256 || null, push_id: pushId,
+    });
+    action = { ...action, file_id: reserved.file_id, mode: reserved.mode, signed_put_url: reserved.signed_put_url };
+  }
+  const makeError = (msg) => new SyncError(msg, { code: 'upload_failed' });
+  if (action.mode === 'multipart' || size >= MULTIPART_THRESHOLD) {
+    await uploadMultipart({
+      baseUrl: ctx.baseUrl, credOpts: ctx.credOpts, fetchImpl: ctx.fetchImpl, putFetch: ctx.putFetch,
+      fileId: action.file_id, absPath: local.abs, size, filename: rel, makeError,
+      pathBase: target.multipartBase, wrap: (fn) => withBackoff(ctx, fn),
+      progress: ctx.progress,
+    });
+    return;
+  }
+  const buf = await fsp.readFile(local.abs);
+  let resp;
+  try {
+    resp = await storageFetch(ctx)(action.signed_put_url, { method: 'PUT', headers: { 'Content-Type': mimeFor(rel) }, body: buf });
+  } catch (netErr) {
+    throw makeError(`上传 ${rel} 失败（网络错误）：${netErr && netErr.message ? netErr.message : netErr}。可重新运行同一条命令。`);
+  }
+  if (!resp.ok) {
+    let text = '';
+    try { text = await resp.text(); } catch { /* the status alone is enough */ }
+    throw makeError(describeStorageFailure(classifyStorageFailure(resp.status, text), rel, resp.status));
+  }
+  await apiPost(ctx, target.uploadCompleteUrl(action.file_id), {});
+}
+
+/**
+ * Push the changes in `dir` to the target.
+ *
+ * Only changed or new files are sent (see the header of this file). Local deletions are sent only with `del`.
+ * The platform answers with a plan (skip / reuse / upload per file); only "upload" files travel. The whole push is
+ * committed in one step at the end, so a push that breaks half way changes nothing on the platform.
+ *
+ * @param {object} opts { note?, tidy?, del? }
+ * @returns {Promise<object>} summary: { nothing, considered, unchanged, sent, uploaded, reused, skipped, bytes,
+ *                                       deletesSent, localDeleted, changes, conflicts, kept, skippedLocal }
+ */
+export async function push(ctx, target, dir, { note = null, tidy = false, del = false } = {}) {
+  const absRoot = path.resolve(dir);
+  let isDir = false;
+  try { isDir = (await fsp.stat(absRoot)).isDirectory(); } catch { /* handled below */ }
+  if (!isDir) throw new SyncError(`本地目录不存在：${dir}`, { code: 'dir_missing', exit: 2 });
+
+  const state = readState(absRoot);
+  checkStateTarget(state, target);
+  const base = (state && state.files) || {};
+  const scan = await scanLocal(absRoot);
+
+  // fingerprints of everything that is here now
+  const hashes = new Map();
+  await pool([...scan.files.keys()], HASH_CONCURRENCY, async (rel) => {
+    hashes.set(rel, await hashFile(scan.files.get(rel).abs));
+  });
+
+  // only what differs from the fingerprint it had when pulled (or is new) is worth sending
+  const files = [];
+  let unchanged = 0;
+  for (const [rel, info] of [...scan.files.entries()].sort((a, b) => (a[0] < b[0] ? -1 : 1))) {
+    const sha = hashes.get(rel);
+    const b = base[rel];
+    if (b && b.sha256 === sha) { unchanged += 1; continue; }
+    files.push({ path: rel, size_bytes: info.size, sha256: sha, base_sha256: b ? b.sha256 : null, mime_type: mimeFor(rel) });
+  }
+  const gone = Object.keys(base).filter((rel) => !scan.files.has(rel)).sort();
+  const deletes = del ? gone.map((rel) => ({ path: rel, base_sha256: base[rel].sha256 })) : [];
+  const knownFolders = new Set((state && state.folders) || []);
+  const folders = scan.emptyFolders.filter((f) => !knownFolders.has(f));
+
+  const summary = {
+    nothing: false, considered: scan.files.size, unchanged, sent: files.length, uploaded: [], reused: [], skipped: [],
+    bytes: 0, deletesSent: deletes.length, localDeleted: del ? [] : gone, changes: [], conflicts: [], kept: [],
+    skippedLocal: scan.skipped,
+  };
+  if (files.length === 0 && deletes.length === 0 && folders.length === 0) {
+    summary.nothing = true;
+    return summary;
+  }
+
+  // ask for the plan
+  const planBody = {
+    ...target.pushBody({ mode: tidy ? 'tidy' : 'sync', note }),
+    files, deletes, folders,
+  };
+  const plan = await apiPost(ctx, target.pushUrl, planBody);
+  const actions = new Map(((plan && plan.actions) || []).map((a) => [normalizeRemotePath(a.path), a]));
+
+  // send what the plan says has to travel
+  const toUpload = [];
+  for (const f of files) {
+    const a = actions.get(f.path);
+    if (!a || a.action === 'skip') { summary.skipped.push(f.path); continue; }
+    if (a.action === 'reuse') { summary.reused.push(f.path); continue; }
+    toUpload.push({ f, a });
+  }
+  await pool(toUpload, UPLOAD_CONCURRENCY, async ({ f, a }) => {
+    await uploadOne(ctx, target, a, scan.files.get(f.path), f.path, { pushId: plan.push_id, sha256: f.sha256 });
+    summary.uploaded.push(f.path);
+    summary.bytes += f.size_bytes;
+    if (ctx.progress) ctx.progress(`已上传 ${summary.uploaded.length}/${toUpload.length}：${f.path}`);
+  });
+
+  // one commit = one batch on the platform
+  const done = await apiPost(ctx, target.commitUrl(plan.push_id), {});
+  summary.changes = (done && done.changes) || [];
+  summary.conflicts = (done && done.conflicts) || [];
+  summary.kept = (done && done.kept) || [];
+
+  // remember the new starting point: sent files are now what the platform has; deleted files are gone
+  const next = { ...base };
+  for (const f of files) next[f.path] = { sha256: f.sha256, size: f.size_bytes, blob_id: null };
+  const keptPaths = new Set(summary.kept.map((k) => normalizeRemotePath(k.path)));
+  for (const d of deletes) if (!keptPaths.has(d.path)) delete next[d.path];
+  writeState(absRoot, {
+    version: 1, kind: target.kind, remote: target.remote, head_change_id: state ? state.head_change_id : null,
+    pulled_at: state ? state.pulled_at : null, pushed_at: new Date().toISOString(),
+    files: next, folders: [...new Set([...knownFolders, ...folders])],
+  });
+  return summary;
+}