@anytowork/cli 0.12.20 → 0.12.21

package/README.md

@@ -309,6 +309,26 @@ anytowork set-profile-intro --file intro.md
 
 全局开关：`--profile <名字>`（同机多 Agent 隔离）、`--json`（机器可读输出）、`--idempotency-key <str>`（重试幂等键）。
 
+## 空间与工作空间（CLI 0.12.21 起）
+
+空间是主人的私人文件库。主人自己绑定的 Agent 可以读写它；发起方还可以给一单任务指定空间里的一个文件夹作为工作空间，接单方的 Agent 在这一单里拉取和推送。做法是「同步」：拉到本地，用你自己的工具改，只把改动推回去。
+
+```bash
+# 主人自己绑定的 Agent
+anytowork space ls [路径]
+anytowork space pull <路径> --to <本地目录> [--force]     # 路径写 / 表示整个空间；本地改过且与空间不同的文件默认不覆盖
+anytowork space push <本地目录> [--to <路径>] [--note "说明"] [--delete] [--tidy]
+#   只上传改动，整次推送在空间里记成一个版本，主人可整批退回；--delete 才同步删除本地已删的文件；--tidy 用于按主人要求整理
+#   拉取后本地目录里有隐藏文件 .anytowork-sync.json，记着每个文件拉取时的样子，请保留，不要当作成果交付
+
+# 接单方的 Agent（只在这一单进行期间；只能碰这一单的工作空间）
+anytowork task workspace pull <task_id> --to <本地目录>
+anytowork task workspace push <task_id> --from <本地目录> [--delete]    # 只在进行中能推送，验收之后才并入发起方的空间
+anytowork task workspace status <task_id>
+```
+
+空间已满、本月下载用完、这一单的推送超过上限时，命令会把平台的话原样打出来，转告主人即可；请求太频繁时会按平台说的时间自动等一会再试。`anytowork space --help`、`anytowork task workspace --help` 中英双语。完整说明：https://a2a.linger.chimap.cn/docs/guide/space
+
 ## 平台地址
 
 默认连官方平台 `https://a2a.linger.chimap.cn`。开发 / 本地测试用环境变量覆盖：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anytowork/cli",
-  "version": "0.12.20",
+  "version": "0.12.21",
   "description": "AnytoWork 平台命令行工具——让任何能执行 shell 命令的 Agent 用一条命令接入 AnytoWork：登录、发单接单、管理能力。",
   "type": "module",
   "bin": {

package/src/cli-parse.js

@@ -79,6 +79,8 @@ import { matchRetired } from './retired-commands.js';
 //   libra settle propose|accept|reject|withdraw → 'libra:settle-<动作>'（和解提议）
 //   discover show <showcase_id> → 'discover:show'（按成果编号看公开成果，只读）
 //   refund status|respond|reply|start|cancel --task <id> → 'refund:<动作>'（退款先协商；start/cancel 只给网页链接）
+//   space ls|pull|push ...                       → 'space:<动作>'（v0.31：主人的 Agent 读写空间；只传改动）
+//   task workspace pull|push|status <task_id>    → 'task:workspace-<动作>'（v0.31：接单 Agent 拉取 / 推送这单的工作空间）
 //
 //   能力上架
 //   capability report-skills ...   → 'capability:report-skills'（agent 上报技能清单）
@@ -269,6 +271,11 @@ export function parseArgs(argv) {
     deferDays: null,       // task extension request|respond --defer-days <days> (old form, server converts days * 24)
     deferHours: null,      // task extension request|respond --defer-hours <hours> (authoritative since the server's v0.24.22)
     decision: null,        // task extension respond|confirm --decision <word>
+    help: false,           // --help / -h anywhere: show the help of that command group (space, task workspace)
+    from: null,            // task workspace push --from <local folder>
+    delete: false,         // space push / task workspace push --delete: also delete what was deleted locally
+    tidy: false,           // space push --tidy: the push is a tidy-up the owner asked for
+    force: false,          // space pull / task workspace pull --force: overwrite local files with the remote version
   };
   const positionals = [];
 
@@ -538,6 +545,16 @@ export function parseArgs(argv) {
     } else if (a === '--auto-redact') {
       // v0.23.25: task create --auto-redact (boolean switch, off by default)
       flags.autoRedact = true;
+    } else if (a === '--help' || a === '-h') {
+      flags.help = true;
+    } else if (a === '--from') {
+      flags.from = args.shift() ?? null;
+    } else if (a === '--delete') {
+      flags.delete = true;
+    } else if (a === '--tidy') {
+      flags.tidy = true;
+    } else if (a === '--force') {
+      flags.force = true;
     } else if (a.startsWith('--')) {
       // 未知开关：暂忽略
     } else {
@@ -602,6 +619,8 @@ export function parseArgs(argv) {
       case 'collab':        command = 'task:collab'; break;
       // P19: ask the seller for one more revision round (sub-command is the 3rd positional)
       case 'extension':     command = 'task:extension'; break;
+      // v0.31: the workspace of one task (sub-command is the 3rd positional; none = show the help)
+      case 'workspace':     command = c2 === undefined ? 'task:workspace-help' : (['pull', 'push', 'status'].includes(c2) ? `task:workspace-${c2}` : 'unknown'); break;
       default:             command = 'unknown';
     }
   } else if (c0 === 'capability') {
@@ -642,6 +661,9 @@ export function parseArgs(argv) {
   } else if (c0 === 'discover') {
     // v0.26.60: anytowork discover show <showcase_id>
     command = c1 === 'show' ? 'discover:show' : 'unknown';
+  } else if (c0 === 'space') {
+    // v0.31: anytowork space ls|pull|push (none = show the help)
+    command = c1 === undefined ? 'space:help' : (['ls', 'pull', 'push'].includes(c1) ? `space:${c1}` : 'unknown');
   } else if (c0 === 'profiles') {
     // 列出本机已登录的 profile（同机多 Agent 总览）
     command = 'profiles';

package/src/format.js

@@ -484,6 +484,28 @@ function fmtPct(pct) {
   return Number.isInteger(pct) ? `${pct}%` : `${pct.toFixed(1)}%`;
 }
 
+/** Size in the unit people read: 1.5KB / 12.3MB. */
+function workspaceSizeText(n) {
+  const v = Number(n);
+  if (!Number.isFinite(v) || v < 0) return '?';
+  if (v < 1024) return `${v}B`;
+  if (v < 1024 * 1024) return `${(v / 1024).toFixed(1)}KB`;
+  return `${(v / 1024 / 1024).toFixed(1)}MB`;
+}
+
+/** Lines under `task show` for the seller: this task has a workspace, and how to pull / push it (v0.31). */
+export function workspaceBriefLines(wb, taskId) {
+  if (!wb || !wb.name) return [];
+  const lines = [`  📁 这单有工作空间：${wb.name} · ${wb.file_count != null ? wb.file_count : 0} 个文件 · ${workspaceSizeText(wb.size_bytes)}`];
+  if (wb.pull_open !== false) lines.push(`     拉取到本地：anytowork task workspace pull ${taskId} --to <本地目录>`);
+  if (wb.push_open) {
+    lines.push(`     把改动记到这一单：anytowork task workspace push ${taskId} --from <本地目录>（验收之后才并入发起方的空间）`);
+  } else {
+    lines.push('     现在只能拉取，不能推送（只在任务进行中能推送）');
+  }
+  return lines;
+}
+
 export function formatTaskDetail(data, { json = false } = {}) {
   if (json) return asJson(data);
   const lines = [];
@@ -553,6 +575,9 @@ export function formatTaskDetail(data, { json = false } = {}) {
   if (data.collab && data.collab.can && data.collab.can.ask === true) {
     lines.push(`  💬 如对需求有疑问，可用 anytowork task ask ${data.task_id || data.id || '<task_id>'} 向发起方提问（见 anytowork task --help）`);
   }
+  // v0.31: the platform sends workspace_brief only to the seller of this task: tell the Agent the task has a workspace
+  // and which commands pull / push it (what the buyer picked is never listed, only name / count / size)
+  for (const l of workspaceBriefLines(data.workspace_brief, data.task_id || data.id || '<task_id>')) lines.push(l);
   for (const l of taskDetailSafetyLines(data)) lines.push(l);
   for (const l of continuationLines(data.continuation)) lines.push(l);
   for (const l of sameOfLines(data.same_of)) lines.push(l);

package/src/index.js

@@ -125,6 +125,7 @@ import { runDiscover, isDiscoverCommand } from './discover-commands.js';
 import { runExtension } from './extension-commands.js';
 import { mapApiError } from './error-map.js';
 import { runContinue } from './cont-commands.js';
+import { runSpace, runTaskWorkspace, isSpaceCommand, isTaskWorkspaceCommand, SPACE_HELP, TASK_WORKSPACE_HELP } from './space-commands.js';
 import { checkQuoteArgs, checkPassArgs, mapQuoteError, rangeText, PASS_REASONS } from './quote-pass.js';
 import { checkApplyModels } from './model-pledge.js';   // v0.27.25: model pledge on `task apply`
 
@@ -445,6 +446,17 @@ const HELP = `${BRAND.name} CLI v${PKG_VERSION}
     [--after <编号>]                  只看该编号之后的新记录
     [--json]
 
+── 空间与工作空间 / Space and task workspace ───────────────────
+  space ls [路径]                     列出主人的空间（只有主人自己绑定的 Agent 能用）
+  space pull <路径> --to <本地目录>   把空间里的文件夹拉到本地（路径写 / 表示整个空间）
+  space push <本地目录> [--to <路径>] 只上传改动，整次推送在空间里记成一个版本
+    [--note "<说明>"] [--delete] [--tidy]
+  task workspace pull <task_id> --to <本地目录>      接单后拉取这一单的工作空间
+  task workspace push <task_id> --from <本地目录>    只上传改动，记在这一单里，验收后才并入发起方的空间
+  task workspace status <task_id>     看这一单目前记下的改动
+    List, pull and push the owner's space (the owner's own Agent), and pull / push the workspace of one task (its seller).
+    Only changes are uploaded. 详细说明 / Details: anytowork space --help，anytowork task workspace --help
+
 ── 发现（别人公开的成果）────────────────────────────────────────
   discover show <成果编号>              按成果编号看一个公开成果：标题、需求、公开的成果文件和原单附件、成交价、公开页链接（只读，需要登录）
                                        做同款的单会在 task show 里带上它的成果编号，用它参考原成果；这里不会给原任务编号，也不下发原成果文件
@@ -668,6 +680,15 @@ export async function run(argv, deps = {}) {
     err('不认识这条命令。运行 `anytowork` 查看可用命令。');
     return 2;
   }
+  // v0.31: the help of the space commands needs no login (bilingual, printed as it is)
+  if (command === 'space:help' || (flags.help && isSpaceCommand(command))) {
+    log(SPACE_HELP);
+    return 0;
+  }
+  if (command === 'task:workspace-help' || (flags.help && isTaskWorkspaceCommand(command))) {
+    log(TASK_WORKSPACE_HELP);
+    return 0;
+  }
 
   try {
     // auth login 单独处理（走 OAuth flow）
@@ -826,6 +847,14 @@ export async function run(argv, deps = {}) {
       return await runContinue({ baseUrl, credOpts, positionals, flags, idemKey, fetchImpl, log, err });
     }
 
+    // v0.31: the owner's Agent reads and writes the space; the seller's Agent pulls / pushes a task's workspace
+    if (isSpaceCommand(command)) {
+      return await runSpace({ command, positionals, flags, baseUrl, credOpts, fetchImpl, deps, log, err });
+    }
+    if (isTaskWorkspaceCommand(command)) {
+      return await runTaskWorkspace({ command, positionals, flags, baseUrl, credOpts, fetchImpl, deps, log, err });
+    }
+
     if (command === 'task:apply') {
       // positionals = ['task', 'apply', '<task_id>'] → [2] 是 task_id
       const taskId = positionals[2];

package/src/multipart-upload.js

@@ -13,14 +13,18 @@ const PART_RETRIES = 4;
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
-function call(baseUrl, credOpts, fetchImpl, action, body) {
-  return authedPostWithRefresh(baseUrl, `/api/v1/uploads/multipart/${action}`, credOpts, body, null, { fetchImpl });
+/** Where the part endpoints live by default; the space and a task's workspace have their own (v0.31, CLI 0.12.21). */
+export const DEFAULT_MULTIPART_BASE = '/api/v1/uploads/multipart';
+
+function callPart(baseUrl, credOpts, fetchImpl, action, body, base = DEFAULT_MULTIPART_BASE, wrap = (fn) => fn()) {
+  return wrap(() => authedPostWithRefresh(baseUrl, `${base}/${action}`, credOpts, body, null, { fetchImpl }));
 }
 
 /**
  * Upload one registered file (POST /uploads already gave its file_id) in parts.
  *
- * @param {object} p { baseUrl, credOpts, fetchImpl?, putFetch?, fileId, absPath, size, filename, progress?(msg), makeError(msg) }
+ * @param {object} p { baseUrl, credOpts, fetchImpl?, putFetch?, fileId, absPath, size, filename, progress?(msg), makeError(msg),
+ *                   pathBase? (part endpoints, default the task-attachment ones), wrap? (runs every platform call, e.g. to wait out a 429) }
  * @throws whatever makeError builds, with a Chinese message
  */
 export async function uploadMultipart(p) {
@@ -28,10 +32,13 @@ export async function uploadMultipart(p) {
   const putFetch = p.putFetch || fetchImpl || globalThis.fetch;
   const progress = p.progress || (() => {});
   const base = { file_id: fileId };
+  const pathBase = p.pathBase || DEFAULT_MULTIPART_BASE;
+  const wrap = p.wrap || ((fn) => fn());
+  const call = (action, body) => callPart(baseUrl, credOpts, fetchImpl, action, body, pathBase, wrap);
 
   let init;
   try {
-    init = await call(baseUrl, credOpts, fetchImpl, 'init', base);
+    init = await call('init', base);
   } catch (e) {
     if (e && e.upgradeRequired) throw e;
     throw makeError(`开始分片上传 ${filename} 失败：${e && e.message ? e.message : e}`);
@@ -44,7 +51,7 @@ export async function uploadMultipart(p) {
   const urls = {};
   const sign = async (nums) => {
     for (let i = 0; i < nums.length; i += 100) {
-      const r = await call(baseUrl, credOpts, fetchImpl, 'sign', { ...base, upload_id: uploadId, part_numbers: nums.slice(i, i + 100) });
+      const r = await call('sign', { ...base, upload_id: uploadId, part_numbers: nums.slice(i, i + 100) });
       Object.assign(urls, r.urls);
     }
   };
@@ -95,7 +102,7 @@ export async function uploadMultipart(p) {
 
     // an ETag the storage did not let us read is taken from the server's list of stored parts
     if (numbers.some((n) => !etags[String(n)])) {
-      const listed = await call(baseUrl, credOpts, fetchImpl, 'parts', { ...base, upload_id: uploadId });
+      const listed = await call('parts', { ...base, upload_id: uploadId });
       for (const part of listed.parts || []) {
         if (!etags[String(part.part_number)]) etags[String(part.part_number)] = part.etag;
       }
@@ -103,12 +110,12 @@ export async function uploadMultipart(p) {
     const parts = numbers.map((n) => ({ part_number: n, etag: etags[String(n)] }));
     if (parts.some((x) => !x.etag)) throw makeError(`上传 ${filename} 没有传完整，请重新运行同一条命令。`);
     try {
-      await call(baseUrl, credOpts, fetchImpl, 'complete', { ...base, upload_id: uploadId, parts });
+      await call('complete', { ...base, upload_id: uploadId, parts });
     } catch (e) {
       throw makeError(`合并 ${filename} 失败：${e && e.message ? e.message : e}。可重新运行同一条命令。`);
     }
   } catch (e) {
-    try { await call(baseUrl, credOpts, fetchImpl, 'abort', { ...base, upload_id: uploadId }); } catch { /* the platform clears leftovers by itself */ }
+    try { await call('abort', { ...base, upload_id: uploadId }); } catch { /* the platform clears leftovers by itself */ }
     throw e;
   } finally {
     await fh.close();

package/src/space-commands.js

@@ -0,0 +1,363 @@
+// Commands that read and write the owner's space and a task's workspace (v0.31, CLI 0.12.21):
+//
+//   anytowork space ls [path]                            list the space (owner's own Agent)
+//   anytowork space pull <path> --to <dir>               pull a folder to this computer
+//   anytowork space push <dir> [--to <path>] ...         push only what changed back
+//   anytowork task workspace pull <task> --to <dir>      pull the workspace folder of a task (seller's Agent)
+//   anytowork task workspace push <task> --from <dir>    record changes on the task (not in the owner's space yet)
+//   anytowork task workspace status <task>               what has been recorded so far
+//
+// The transfer itself lives in space-sync.js. This file checks the arguments, calls it, and says what happened in
+// words an Agent can pass on to its owner. Exit codes: 0 done / 1 refused or failed / 2 a problem with the arguments.
+import path from 'node:path';
+import { apiGet, spaceTarget, taskTarget, pull, push, normalizeRemotePath, readState, SyncError, describeApiError } from './space-sync.js';
+import { humanSize } from './media-upload.js';
+
+// ---------------------------------------------------------------- help (Chinese and English side by side)
+
+export const SPACE_HELP = `anytowork space — 读写主人的空间 / read and write the owner's space
+只有主人自己绑定的 Agent 能用。 / Only for an Agent bound by the owner.
+
+用法 / Usage
+  anytowork space ls [路径] [--json]
+      列出空间或某个文件夹里的内容。
+      List the space or one folder.
+
+  anytowork space pull <路径> --to <本地目录> [--force] [--json]
+      把空间里的文件夹拉到本地，并记下这次拉取时每个文件的样子。路径写 / 表示整个空间。
+      Pull a folder to a local directory and remember what each file looked like. Use / for the whole space.
+      本地已有、内容不同的文件默认不覆盖（会列出来）；加 --force 才用空间里的版本覆盖。
+      Local files with other content are kept and listed; --force overwrites them with the space's version.
+
+  anytowork space push <本地目录> [--to <路径>] [--note "<说明>"] [--delete] [--tidy] [--json]
+      只上传改动（新增、修改），没变的不传。整次推送在空间里记成一个版本，主人可以整批退回。
+      Upload only what changed. The whole push becomes one version in the space; the owner can undo it as a whole.
+      --to      不写时，用这个目录上次拉取的位置。 / Without it, the place this directory was last pulled from.
+      --note    一句话说明改了什么，显示在版本记录里。 / One line on what changed, shown in the version history.
+      --delete  把本地删掉的文件也在空间里删除（默认不删）。 / Also delete in the space what you deleted locally (off by default).
+      --tidy    按主人的要求整理文件时加上，版本会显示为「整理」。 / Add it when tidying up for the owner; the version shows as "tidy".
+
+说明 / Notes
+  拉取后本地目录里有一个隐藏文件 .anytowork-sync.json，记着每个文件拉取时的样子。请保留它，不要当作成果交付。
+  A hidden file .anytowork-sync.json in the folder remembers each file as pulled. Keep it, and do not deliver it.
+
+  拉取之后文件在空间里又被改过时，推送照常写入你的版本，旧版本留在历史版本里；命令会把这些文件列出来，请告诉主人。
+  If a file was changed in the space after you pulled it, the push still writes your version and the old one stays in the
+  version history; the command lists those files, so tell the owner.
+
+  空间已满、本月下载用完时，命令会原样打出平台的话，请转告主人。请求太频繁时会自动等一会再试。
+  When the space is full or the month's downloads are used up, the command prints the platform's own words; pass them on
+  to the owner. If requests come too fast it waits and retries by itself.`;
+
+export const TASK_WORKSPACE_HELP = `anytowork task workspace — 这一单的工作空间 / the workspace of one task
+只有这单当前的接单方能用，从选定你接单起到任务结束止。 / Only for the seller of this task, from being chosen until the task ends.
+
+用法 / Usage
+  anytowork task workspace pull <任务编号> --to <本地目录> [--force] [--json]
+      把这单的工作空间文件夹拉到本地，并记下每个文件拉取时的样子。
+      Pull the workspace folder of this task to a local directory and remember each file as pulled.
+
+  anytowork task workspace push <任务编号> --from <本地目录> [--delete] [--json]
+      只上传改动，记在这一单里。验收之后才会并入发起方的空间，空间里不会出现没验收的东西。
+      Upload only what changed, recorded on this task. It joins the owner's space only after acceptance.
+      只能在任务进行中（含改稿进行中）推送；已交付待验收期间只能拉取。
+      You can push only while the task is in progress (including revisions); after delivery you can only pull.
+      交付时，当时记下的改动会一起定格进那一轮交付。 / On delivery, the changes recorded so far are frozen into that delivery.
+
+  anytowork task workspace status <任务编号> [--json]
+      看这一单目前记下的改动清单（改 / 新 / 删）。
+      Show the changes recorded on this task so far (modified / new / deleted).
+
+说明 / Notes
+  同一个文件以最后一次推送为准。拉取后别人又改过的文件，命令会列出来。
+  For the same file the last push wins. Files that changed after you pulled them are listed.
+  拉取会计入发起方本月的下载量，但不会因此被拦。 / Pulling counts toward the owner's monthly downloads, but is never blocked.
+  推送总量超过上限时，平台的话会原样打出，已经记下的改动不受影响。
+  If the push total goes over the limit the platform's words are printed as they are; changes already recorded stay.`;
+
+// ---------------------------------------------------------------- small formatting helpers
+
+const MAX_LISTED = 10;
+
+/** "a, b, c …等 12 个": a short list the Agent can read at a glance. */
+function listed(paths) {
+  const shown = paths.slice(0, MAX_LISTED).join('、');
+  return paths.length > MAX_LISTED ? `${shown} …等 ${paths.length} 个` : shown;
+}
+
+function dayOf(iso) {
+  return typeof iso === 'string' && iso.length >= 10 ? iso.slice(0, 10) : '';
+}
+
+const OP_LABEL = { modify: '改', create: '新', delete: '删', move: '移' };
+
+/** Counts of what a commit did, from either shape: space batches carry `summary`, task changes carry `op`. */
+function changeCounts(changes) {
+  const out = { modify: 0, create: 0, delete: 0, move: 0 };
+  for (const c of changes || []) {
+    if (c && c.summary) {
+      for (const k of Object.keys(out)) out[k] += Number(c.summary[k]) || 0;
+    } else if (c && c.op && out[c.op] !== undefined) {
+      out[c.op] += 1;
+    }
+  }
+  return out;
+}
+
+function countsText(c) {
+  const parts = [];
+  if (c.create) parts.push(`新增 ${c.create}`);
+  if (c.modify) parts.push(`修改 ${c.modify}`);
+  if (c.delete) parts.push(`删除 ${c.delete}`);
+  if (c.move) parts.push(`移动 ${c.move}`);
+  return parts.join('，');
+}
+
+// ---------------------------------------------------------------- running a command safely
+
+/**
+ * Run one command body; turn the ways it can fail into screen output and an exit code.
+ * Platform refusals print the platform's own words (see describeApiError); an "upgrade the CLI" refusal is passed up
+ * unchanged so the shared handler gives it the fixed exit code 4.
+ */
+async function guarded(io, body) {
+  try {
+    return await body();
+  } catch (e) {
+    if (e && e.upgradeRequired) throw e;
+    if (e instanceof SyncError) {
+      if (io.json) io.log(JSON.stringify({ ok: false, error: e.code, message: e.message, ...e.extra }));
+      else io.err(e.message);
+      return e.exit;
+    }
+    const known = describeApiError(e);
+    if (known) {
+      if (io.json) io.log(JSON.stringify({ ok: false, error: known.code, message: known.message, ...flatVars(known.body) }));
+      else for (const line of known.lines) io.err(line);
+      return 1;
+    }
+    throw e;
+  }
+}
+
+/** The numbers the platform put next to its refusal (resume_on, max_bytes ...), for the --json output. */
+function flatVars(body) {
+  const v = body && typeof body.vars === 'object' && body.vars ? body.vars : {};
+  const out = {};
+  for (const k of ['resume_on', 'quota_bytes', 'used_bytes', 'max_bytes', 'retry_after', 'status', 'paths']) {
+    if (v[k] !== undefined) out[k] = v[k];
+    else if (body && body[k] !== undefined) out[k] = body[k];
+  }
+  return out;
+}
+
+function usage(io, message) {
+  if (io.json) io.log(JSON.stringify({ ok: false, error: 'bad_arguments', message }));
+  else io.err(message);
+  return 2;
+}
+
+function makeCtx({ baseUrl, credOpts, fetchImpl, deps, err }) {
+  return {
+    baseUrl, credOpts, fetchImpl,
+    putFetch: deps && deps.putFetch,
+    sleep: deps && deps.sleep,
+    // progress goes to stderr, so --json output on stdout stays one clean document
+    progress: (m) => err(m),
+  };
+}
+
+// ---------------------------------------------------------------- space ls / pull / push
+
+async function runLs(c) {
+  const spacePath = normalizeRemotePath(c.positionals[2]);
+  const items = [];
+  let parent = null;
+  let cursor = null;
+  for (let page = 0; page < 200; page += 1) {
+    const q = new URLSearchParams({ limit: '1000' });
+    if (spacePath) q.set('path', spacePath);
+    if (cursor) q.set('cursor', cursor);
+    const r = await apiGet(c.ctx, `/api/v1/space/nodes?${q}`);
+    if (page === 0) parent = r.parent || null;
+    for (const n of r.items || []) items.push(n);
+    cursor = r.next_cursor || null;
+    if (!cursor) break;
+  }
+  if (c.json) { c.log(JSON.stringify({ ok: true, path: spacePath, parent, items }, null, 2)); return 0; }
+  const folders = items.filter((n) => n.kind === 'folder').length;
+  c.log(`${spacePath ? `空间 / ${spacePath}` : '空间'}：${folders} 个文件夹，${items.length - folders} 个文件`);
+  for (const n of items) {
+    if (n.kind === 'folder') {
+      c.log(`  ${n.name}/    ${n.file_count != null ? `${n.file_count} 个文件 · ` : ''}${humanSize(n.size_bytes || 0)}    ${dayOf(n.updated_at)}`);
+    } else {
+      c.log(`  ${n.name}    ${humanSize(n.size_bytes || 0)}    ${dayOf(n.updated_at)}`);
+    }
+  }
+  return 0;
+}
+
+/** Shared by `space pull` and `task workspace pull`: print what the pull did; failed / quota-stopped files make it exit 1. */
+function reportPull(c, target, dir, s) {
+  const problems = s.failed.length > 0 || s.quotaStopped;
+  if (c.json) {
+    c.log(JSON.stringify({
+      ok: !problems, target: { kind: target.kind, remote: target.remote }, dir: path.resolve(dir),
+      total: s.total, downloaded: s.downloaded.length, up_to_date: s.upToDate, bytes: s.bytes,
+      kept_local: s.keptLocal, clashes: s.clashes, removed: s.removed, kept_remote_deleted: s.keptRemoteDeleted,
+      not_pulled: s.notPulled, failed: s.failed, quota_stopped: s.quotaStopped, head_change_id: s.headChangeId,
+    }, null, 2));
+    return problems ? 1 : 0;
+  }
+  c.log(`已把${target.label}拉到 ${path.resolve(dir)}：共 ${s.total} 个文件，新拉取 ${s.downloaded.length} 个（${humanSize(s.bytes)}），已是最新 ${s.upToDate} 个。`);
+  if (s.clashes.length) {
+    c.log(`这些文件本地和这边内容不同，没有覆盖：${listed(s.clashes)}`);
+    c.log('  想用这边的版本覆盖本地，加 --force 重新拉取；要保留本地的，直接改好后推送即可。');
+  }
+  if (s.keptLocal.length) c.log(`这些文件你本地改过、这边没有变化，已保留本地版本：${listed(s.keptLocal)}`);
+  if (s.removed.length) c.log(`这边已经删除、本地没动过的文件，已从本地移除：${listed(s.removed)}`);
+  if (s.keptRemoteDeleted.length) c.log(`这边已经删除，但你本地改过，已保留：${listed(s.keptRemoteDeleted)}`);
+  if (s.quotaStopped) {
+    c.err(`主人本月的下载额度已用完，还有 ${s.notPulled.length} 个文件没有拉取：${listed(s.notPulled)}`);
+    c.err('  已经拉到本地的文件不受影响。请告诉主人；额度恢复后重新运行同一条命令，会接着拉剩下的。');
+  }
+  if (s.failed.length) {
+    c.err(`这些文件没有拉下来：${s.failed.slice(0, MAX_LISTED).map((f) => `${f.path}（${f.reason}）`).join('、')}${s.failed.length > MAX_LISTED ? ` …等 ${s.failed.length} 个` : ''}`);
+    c.err('  可以重新运行同一条命令，已经拉好的文件不会重复下载。');
+  }
+  return problems ? 1 : 0;
+}
+
+/** Shared by `space push` and `task workspace push`. */
+function reportPush(c, target, s) {
+  const counts = changeCounts(s.changes);
+  if (c.json) {
+    c.log(JSON.stringify({
+      ok: true, target: { kind: target.kind, remote: target.remote }, nothing: s.nothing, considered: s.considered,
+      unchanged: s.unchanged, sent: s.sent, uploaded: s.uploaded.length, reused: s.reused.length, skipped: s.skipped.length,
+      bytes: s.bytes, deletes_sent: s.deletesSent, local_deleted_not_synced: s.localDeleted,
+      changes: s.changes, conflicts: s.conflicts, kept: s.kept, skipped_local: s.skippedLocal,
+    }, null, 2));
+    return 0;
+  }
+  if (s.nothing) {
+    c.log('没有需要推送的改动。');
+  } else {
+    c.log(`已推送到${target.label}：改动 ${s.sent + s.deletesSent} 处（${countsText(counts) || '无实际变化'}）。上传 ${s.uploaded.length} 个文件（${humanSize(s.bytes)}），沿用已有内容 ${s.reused.length} 个，内容相同未传 ${s.skipped.length + s.unchanged} 个。`);
+    c.log(target.kind === 'task'
+      ? '改动已记在这一单里，发起方验收之后才会并入他的空间。'
+      : '这次推送在空间里记成一个版本，主人可以在历史版本里整批退回。');
+  }
+  if (s.conflicts.length) {
+    c.log(`这些文件在你拉取之后又被改过，已按你的版本写成最新，旧版本留在历史版本里。请告诉主人：${listed(s.conflicts.map((x) => x.path))}`);
+  }
+  if (s.kept.length) {
+    c.log(`这些文件你本地删了，但拉取之后这边又改过，所以没有删除：${listed(s.kept.map((x) => x.path))}`);
+  }
+  if (s.localDeleted.length) {
+    c.log(`本地已删除 ${s.localDeleted.length} 个文件，这次没有同步删除：${listed(s.localDeleted)}。需要同步删除时加 --delete。`);
+  }
+  if (s.skippedLocal.length) c.log(`跳过了 ${s.skippedLocal.length} 个符号链接或特殊文件：${listed(s.skippedLocal.map((x) => x.path))}`);
+  return 0;
+}
+
+async function runSpacePull(c) {
+  const rawPath = c.positionals[2];
+  if (rawPath == null || !c.flags.to) {
+    return usage(c, '用法：anytowork space pull <路径> --to <本地目录>（路径写 / 表示整个空间）。更多见 anytowork space --help');
+  }
+  const target = spaceTarget(rawPath);
+  const summary = await pull(c.ctx, target, c.flags.to, { force: c.flags.force });
+  return reportPull(c, target, c.flags.to, summary);
+}
+
+async function runSpacePush(c) {
+  const dir = c.positionals[2];
+  if (!dir) return usage(c, '用法：anytowork space push <本地目录> [--to <路径>]。更多见 anytowork space --help');
+  let to = c.flags.to;
+  if (to == null) {
+    // without --to, go back to where this directory was pulled from
+    const state = readState(path.resolve(dir));
+    if (!state || state.kind !== 'space') {
+      return usage(c, '这个目录不是从空间拉取的，请用 --to <路径> 说明要推送到空间的哪个文件夹（/ 表示整个空间）。');
+    }
+    to = state.remote;
+  }
+  const target = spaceTarget(to);
+  const summary = await push(c.ctx, target, dir, { note: c.flags.note, tidy: c.flags.tidy, del: c.flags.delete });
+  return reportPush(c, target, summary);
+}
+
+/**
+ * anytowork space <ls|pull|push>
+ * @param {object} p { command, positionals, flags, baseUrl, credOpts, fetchImpl, deps?, log, err }
+ */
+export async function runSpace(p) {
+  const { command, positionals, flags, baseUrl, credOpts, fetchImpl, log, err } = p;
+  const c = { positionals, flags, json: flags.json, log, err, ctx: makeCtx({ baseUrl, credOpts, fetchImpl, deps: p.deps, err }) };
+  return guarded(c, () => {
+    if (command === 'space:ls') return runLs(c);
+    if (command === 'space:pull') return runSpacePull(c);
+    return runSpacePush(c);
+  });
+}
+
+// ---------------------------------------------------------------- task workspace pull / push / status
+
+async function runTaskPull(c) {
+  const taskId = c.positionals[3];
+  if (!taskId || !c.flags.to) {
+    return usage(c, '用法：anytowork task workspace pull <任务编号> --to <本地目录>。更多见 anytowork task workspace --help');
+  }
+  const target = taskTarget(taskId);
+  const summary = await pull(c.ctx, target, c.flags.to, { force: c.flags.force });
+  return reportPull(c, target, c.flags.to, summary);
+}
+
+async function runTaskPush(c) {
+  const taskId = c.positionals[3];
+  if (!taskId || !c.flags.from) {
+    return usage(c, '用法：anytowork task workspace push <任务编号> --from <本地目录>。更多见 anytowork task workspace --help');
+  }
+  const target = taskTarget(taskId);
+  const summary = await push(c.ctx, target, c.flags.from, { del: c.flags.delete });
+  return reportPush(c, target, summary);
+}
+
+async function runTaskStatus(c) {
+  const taskId = c.positionals[3];
+  if (!taskId) return usage(c, '用法：anytowork task workspace status <任务编号>。更多见 anytowork task workspace --help');
+  const r = await apiGet(c.ctx, `/api/v1/tasks/${encodeURIComponent(taskId)}/workspace/status`);
+  if (c.json) { c.log(JSON.stringify({ ok: true, ...r }, null, 2)); return 0; }
+  const changes = r.changes || [];
+  const limit = r.max_bytes != null ? `（已记 ${humanSize(r.used_bytes || 0)}，上限 ${humanSize(r.max_bytes)}）` : '';
+  c.log(changes.length === 0 ? `这一单还没有记下任何改动${limit}。` : `这一单已记下 ${changes.length} 处改动${limit}：`);
+  for (const ch of changes) {
+    c.log(`  ${OP_LABEL[ch.op] || ch.op}  ${ch.path}    ${ch.op === 'delete' ? '' : humanSize(ch.size_bytes || 0)}    ${dayOf(ch.pushed_at)}`);
+  }
+  if (r.frozen_round != null) c.log(`第 ${r.frozen_round} 轮交付时记下的改动已经定格，发起方验收看到的就是那一份。`);
+  return 0;
+}
+
+/**
+ * anytowork task workspace <pull|push|status>  (positionals: task workspace <sub> <task_id>)
+ * @param {object} p { command, positionals, flags, baseUrl, credOpts, fetchImpl, deps?, log, err }
+ */
+export async function runTaskWorkspace(p) {
+  const { command, positionals, flags, baseUrl, credOpts, fetchImpl, log, err } = p;
+  const c = { positionals, flags, json: flags.json, log, err, ctx: makeCtx({ baseUrl, credOpts, fetchImpl, deps: p.deps, err }) };
+  return guarded(c, () => {
+    if (command === 'task:workspace-pull') return runTaskPull(c);
+    if (command === 'task:workspace-push') return runTaskPush(c);
+    return runTaskStatus(c);
+  });
+}
+
+/** Command names that belong to this file (used by the dispatcher). */
+export function isSpaceCommand(command) {
+  return typeof command === 'string' && command.startsWith('space:');
+}
+
+export function isTaskWorkspaceCommand(command) {
+  return typeof command === 'string' && command.startsWith('task:workspace-');
+}

package/src/space-sync.js

@@ -0,0 +1,607 @@
+// 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}` : '';
+}
+
+export function apiGet(ctx, pathAndQuery) {
+  return withBackoff(ctx, () => authedGetWithRefresh(ctx.baseUrl, pathAndQuery, ctx.credOpts, { fetchImpl: ctx.fetchImpl }));
+}
+
+export function apiPost(ctx, pathStr, body) {
+  return withBackoff(ctx, () => authedPostWithRefresh(ctx.baseUrl, pathStr, ctx.credOpts, body, null, { fetchImpl: ctx.fetchImpl }));
+}
+
+/** 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;
+}