@stelfield/cli 0.0.0-stage → 0.12.0

package/src/extension-commands.js

@@ -0,0 +1,236 @@
+// "Ask for one more revision round" commands: stelfield task extension <status|request|respond|confirm|withdraw|notify-owner>.
+//
+// Plain words: when the revision count is used up, the buyer may ask the seller for one more round, with an
+// optional extra fee (paid first into escrow) and an optional deferral of the hard deadline. The seller agrees,
+// declines or answers with new terms; the buyer then accepts or rejects the new terms. Declining never hurts
+// the seller's credit. This file is a thin wrapper over routes/revision_extensions.py: parse flags, call, print.
+// All money checks (cap, room for the extra fee, currency) are the platform's; the CLI never repeats them.
+//
+// Exit codes: 0 ok · 1 other failure (prices: code + message + amounts) · 2 local parameter problem ·
+//             4 the request / task is not in a state that allows this · 5 a person must do this on the web
+//             (payment is only done by the buyer in person; the command prints the payment link).
+// --json prints exactly one JSON object on stdout ({ok:true,...} or {ok:false,error,message,...}).
+
+import { BRAND } from "./brand.js";
+import {
+  getRevisionExtensions, createRevisionExtension, respondRevisionExtension,
+  confirmRevisionExtension, withdrawRevisionExtension, notifyOwnerRevisionExtension,
+} from './api.js';
+import { SHELL_PREFIX } from './exit-reasons.js';
+import { errorBodyOf } from './format.js';
+import { mapApiError, moneyText } from './error-map.js';
+
+export const EXT_SUBCOMMANDS = ['status', 'request', 'respond', 'confirm', 'withdraw', 'notify-owner'];
+
+const STATUS_WORDS = {
+  awaiting_payment: '等发起方付附加费用',
+  awaiting_seller: '等接单方回应',
+  awaiting_buyer: '等发起方确认新条件',
+  awaiting_topup: '等发起方补付差额',
+  agreed: '已同意，已进入改稿',
+  declined: '接单方已婉拒',
+  buyer_rejected: '发起方没有接受新条件',
+  withdrawn: '发起方已撤回',
+  expired: '已自动结束',
+};
+
+const REASON_WORDS = {
+  revisions_left: '还有改稿次数，直接用 stelfield task revise 即可',
+  closed: '接单方已结束改稿',
+  not_pending_review: '任务现在不在待验收状态',
+  in_arbitration: '任务正在裁决中',
+  already_open: '已经有一条进行中的申请',
+  blocked_after_decline: '这一轮交付的申请已被婉拒或未达成，不能再申请',
+  feature_off: '「再改一轮」暂时不开放',
+};
+
+// Refusals that mean "this request / task is not in a state that allows it" -> exit 4.
+const STATE_ERRORS = new Set(['extension_not_open', 'extension_not_eligible', 'extension_disabled', 'not_current_seller']);
+
+const webBase = (ctx) => (ctx.env && ctx.env.STELFIELD_WEB_BASE) || BRAND.siteUrl;
+
+function money(cents, currency) {
+  return moneyText(cents, currency) || '-';
+}
+
+// Deferral as "N 小时" (below a day or not a whole day) or "N 天"; old servers only send days.
+function deferText(hours, days) {
+  const h = hours != null ? Number(hours) : Number(days) * 24;
+  if (!(h > 0)) return '不顺延';
+  return h % 24 === 0 ? `顺延 ${h / 24} 天` : `顺延 ${h} 小时`;
+}
+
+function fail(ctx, exit, code, message, extra = {}) {
+  if (ctx.flags.json) ctx.log(JSON.stringify({ ok: false, error: code, message, ...extra }));
+  else ctx.err(message);
+  return exit;
+}
+
+function ok(ctx, data, text) {
+  ctx.log(ctx.flags.json ? JSON.stringify({ ok: true, ...data }) : text);
+  return 0;
+}
+
+/** Lines telling the person where to pay (the buyer pays in person; an Agent only passes the link on). */
+function paymentLines(ctx, pay) {
+  if (!pay) return [];
+  return [
+    `  需要用户本人在网页付款：${money(pay.amount_cents, pay.currency)}`,
+    `  付款链接：${webBase(ctx)}${pay.cashier_path}${pay.expires_at ? `（${pay.expires_at} 前有效）` : ''}`,
+    '  付款成功前不会通知接单方；超时未付款自动撤回。附加费用先放在托管里，接单方同意后才并入任务金额，',
+    '  被婉拒、撤回或超时都会原路退回。',
+  ];
+}
+
+/** The extension to act on: the id given on the command line, else the one that is open now. */
+async function resolveExtensionId(ctx, taskId, given) {
+  if (given) return { extId: given };
+  const view = await getRevisionExtensions(ctx.baseUrl, ctx.credOpts, taskId, { fetchImpl: ctx.fetchImpl });
+  if (!view || !view.current) {
+    return { fail: fail(ctx, 4, 'extension_not_open', '这个任务现在没有进行中的「再改一轮」申请。') };
+  }
+  return { extId: view.current.id, current: view.current };
+}
+
+function describeExtension(x) {
+  const lines = [`  申请 ${x.id}：${STATUS_WORDS[x.status] || x.status}`,
+    `    附加费用 ${money(x.fee_cents, x.currency)}，${deferText(x.defer_hours, x.defer_days)}`];
+  if (x.counter_fee_cents != null || x.counter_defer_days != null || x.counter_defer_hours != null) {
+    lines.push(`    接单方改的条件：附加费用 ${money(x.counter_fee_cents != null ? x.counter_fee_cents : x.fee_cents, x.currency)}，`
+      + `${x.counter_defer_hours != null || x.counter_defer_days != null ? deferText(x.counter_defer_hours, x.counter_defer_days) : deferText(x.defer_hours, x.defer_days)}`);
+  }
+  if (x.expires_at) lines.push(`    付款截止：${x.expires_at}`);
+  if (x.revision_note) lines.push(`    改稿意见：${SHELL_PREFIX}${x.revision_note}`);
+  return lines;
+}
+
+async function cmdStatus(ctx, taskId) {
+  const view = await getRevisionExtensions(ctx.baseUrl, ctx.credOpts, taskId, { fetchImpl: ctx.fetchImpl });
+  const el = (view && view.eligibility) || {};
+  const lines = [`任务 ${taskId} 的「再改一轮」`];
+  lines.push(el.can_apply ? '  现在可以申请（发起方）' : `  现在不能申请：${REASON_WORDS[el.reason] || el.reason || '-'}`);
+  if (view && view.current) lines.push('  进行中的申请：', ...describeExtension(view.current).map((l) => `  ${l}`));
+  const hist = (view && view.history) || [];
+  if (hist.length) lines.push(`  历史申请 ${hist.length} 条，最近一条：${STATUS_WORDS[hist[0].status] || hist[0].status}`);
+  return ok(ctx, { task_id: taskId, ...(view || {}) }, lines.join('\n'));
+}
+
+async function cmdRequest(ctx, taskId) {
+  const { flags } = ctx;
+  const note = flags.note ? String(flags.note).trim() : '';
+  if (!note) return fail(ctx, 2, 'missing_note', '缺少 --note "<改稿意见>"：告诉接单方这一轮要改什么。');
+  if (Number.isNaN(flags.feeCents)) return fail(ctx, 2, 'bad_fee', '--fee-cents 必须是不小于 0 的整数（单位：分）。');
+  if (Number.isNaN(flags.deferDays)) return fail(ctx, 2, 'bad_defer', '--defer-days 必须是不小于 0 的整数（天）。');
+  if (Number.isNaN(flags.deferHours)) return fail(ctx, 2, 'bad_defer', '--defer-hours 必须是不小于 0 的整数（小时）。');
+  const body = { revision_note: note, fee_cents: flags.feeCents || 0 };
+  if (flags.deferHours != null) body.defer_hours = flags.deferHours;
+  else body.defer_days = flags.deferDays || 0;
+  const res = await createRevisionExtension(ctx.baseUrl, ctx.credOpts, taskId, body, flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  const x = res.extension || {};
+  const lines = [`已提出「再改一轮」申请（申请号 ${x.id}）：附加费用 ${money(x.fee_cents, x.currency)}，${deferText(x.defer_hours, x.defer_days)}。`];
+  if (res.payment_required) {
+    lines.push(...paymentLines(ctx, res.payment_required));
+  } else {
+    lines.push('  已通知接单方；验收倒计时结束前没有回应，申请自动撤回。');
+  }
+  lines.push('  对方婉拒不会影响你；想撤回用 stelfield task extension withdraw <task_id>。');
+  return ok(ctx, res, lines.join('\n'));
+}
+
+async function cmdRespond(ctx, taskId, extIdArg) {
+  const { flags } = ctx;
+  const decision = flags.decision;
+  if (!['agree', 'decline', 'counter'].includes(decision)) {
+    return fail(ctx, 2, 'bad_decision', '--decision 只能是 agree（同意）、decline（婉拒）或 counter（改条件）。');
+  }
+  if (Number.isNaN(flags.feeCents)) return fail(ctx, 2, 'bad_fee', '--fee-cents 必须是不小于 0 的整数（单位：分）。');
+  if (Number.isNaN(flags.deferDays)) return fail(ctx, 2, 'bad_defer', '--defer-days 必须是不小于 0 的整数（天）。');
+  if (Number.isNaN(flags.deferHours)) return fail(ctx, 2, 'bad_defer', '--defer-hours 必须是不小于 0 的整数（小时）。');
+  if (decision === 'counter' && flags.feeCents == null && flags.deferDays == null && flags.deferHours == null) {
+    return fail(ctx, 2, 'counter_empty', '改条件至少要给 --fee-cents（只能保持或调高附加费用）或 --defer-hours 其中一项。');
+  }
+  const re = await resolveExtensionId(ctx, taskId, extIdArg);
+  if (re.fail !== undefined) return re.fail;
+  const body = { decision };
+  if (decision === 'counter') {
+    if (flags.feeCents != null) body.counter_fee_cents = flags.feeCents;
+    if (flags.deferHours != null) body.counter_defer_hours = flags.deferHours;
+    else if (flags.deferDays != null) body.counter_defer_days = flags.deferDays;
+  }
+  if (flags.note) body.note = flags.note;
+  const res = await respondRevisionExtension(ctx.baseUrl, ctx.credOpts, taskId, re.extId, body, flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  const x = res.extension || {};
+  const text = {
+    agree: `已同意再改一轮，任务进入改稿；请在改稿时限内重新交付。附加费用 ${money(x.fee_cents, x.currency)} 并入任务金额。`,
+    decline: '已婉拒再改一轮，不影响你的信用；发起方已付的附加费用会原路退回。',
+    counter: '已把新条件发回发起方，等 TA 确认。发起方接受并补付差额后才会进入改稿。',
+  }[decision];
+  return ok(ctx, res, text);
+}
+
+async function cmdConfirm(ctx, taskId, extIdArg) {
+  const { flags } = ctx;
+  if (!['accept', 'reject'].includes(flags.decision)) {
+    return fail(ctx, 2, 'bad_decision', '--decision 只能是 accept（接受新条件）或 reject（不接受）。');
+  }
+  const re = await resolveExtensionId(ctx, taskId, extIdArg);
+  if (re.fail !== undefined) return re.fail;
+  const res = await confirmRevisionExtension(ctx.baseUrl, ctx.credOpts, taskId, re.extId, { decision: flags.decision }, flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  if (flags.decision === 'reject') return ok(ctx, res, '已拒绝新条件，申请结束；已付的附加费用会原路退回。');
+  if (res.payment_required) {
+    return ok(ctx, res, ['已接受新条件，还差一步：', ...paymentLines(ctx, res.payment_required)].join('\n'));
+  }
+  return ok(ctx, res, '已接受新条件，任务进入改稿。');
+}
+
+async function cmdWithdraw(ctx, taskId, extIdArg) {
+  const re = await resolveExtensionId(ctx, taskId, extIdArg);
+  if (re.fail !== undefined) return re.fail;
+  const res = await withdrawRevisionExtension(ctx.baseUrl, ctx.credOpts, taskId, re.extId, ctx.flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  const refund = res.refund_cents ? `；已付的附加费用 ${money(res.refund_cents, res.extension && res.extension.currency)} 会原路退回` : '';
+  return ok(ctx, res, `已撤回「再改一轮」申请${refund}。`);
+}
+
+async function cmdNotifyOwner(ctx, taskId, extIdArg) {
+  const re = await resolveExtensionId(ctx, taskId, extIdArg);
+  if (re.fail !== undefined) return re.fail;
+  const res = await notifyOwnerRevisionExtension(ctx.baseUrl, ctx.credOpts, taskId, re.extId, ctx.flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  return ok(ctx, res, res.notified ? '已请接单方本人来决定（每个申请只通知一次）。' : '已经通知过接单方本人，不再重复通知。');
+}
+
+/**
+ * Run `stelfield task extension <sub> <task_id> [<extension_id>]`.
+ * ctx: { positionals, flags, baseUrl, credOpts, fetchImpl, env, log, err }. Returns the exit code.
+ */
+export async function runExtension(ctx) {
+  const [, , sub, taskId, extId] = ctx.positionals;
+  if (!EXT_SUBCOMMANDS.includes(sub)) {
+    return fail(ctx, 2, 'bad_subcommand', `用法：stelfield task extension <${EXT_SUBCOMMANDS.join('|')}> <task_id> [<extension_id>]`);
+  }
+  if (!taskId) return fail(ctx, 2, 'missing_task', `缺少 task_id。用法：stelfield task extension ${sub} <task_id>`);
+  try {
+    switch (sub) {
+      case 'status': return await cmdStatus(ctx, taskId);
+      case 'request': return await cmdRequest(ctx, taskId);
+      case 'respond': return await cmdRespond(ctx, taskId, extId);
+      case 'confirm': return await cmdConfirm(ctx, taskId, extId);
+      case 'withdraw': return await cmdWithdraw(ctx, taskId, extId);
+      default: return await cmdNotifyOwner(ctx, taskId, extId);
+    }
+  } catch (e) {
+    if (e && e.upgradeRequired) throw e;
+    const body = errorBodyOf(e);
+    // not eligible: say why in plain words
+    if (STATE_ERRORS.has(body.error)) {
+      const why = body.reason ? `（${REASON_WORDS[body.reason] || body.reason}）` : '';
+      return fail(ctx, 4, body.error, `${body.message}${why}`, body.reason ? { reason: body.reason } : {});
+    }
+    // prices / web-only steps: the shared mapping; everything else is left to the generic handler of the caller
+    const mapped = mapApiError(e, { json: ctx.flags.json, webBase: webBase(ctx) });
+    if (mapped) {
+      if (mapped.toStdout) ctx.log(mapped.text); else ctx.err(mapped.text);
+      return mapped.exit;
+    }
+    throw e;
+  }
+}

package/src/file-deliver.js

@@ -0,0 +1,220 @@
+// Ordinary file delivery for sellers, in one command (CLI 0.10.7).
+//
+// What this does for the user: `stelfield deliver upload --task <id> --file <path> [--file <path>…] [--note "说明"]`
+// hands in one or more files as the delivery of a task. The buyer then sees each file under its real name
+// (with the right extension) and the note as the "交付说明". Steps, all offered by the platform already:
+//   1. ask for an upload address per file (POST /uploads, kind=deliverable, with the real filename)
+//   2. PUT the bytes straight to storage
+//   3. deliver with the normal deliver flow: every file uploaded in this round belongs to the new version
+//
+// Before this command an agent had to call `task request-upload` (filename optional, usually left out),
+// PUT by itself and `task deliver --file-id` (no room for a note) - files arrived nameless and without a note.
+
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, extname } from 'node:path';
+import { getTaskDeliverables, requestUpload, runtimeAct } from './api.js';
+import { humanSize } from './media-upload.js';
+import { buildWebDeliverIdemKey, usageFields, WebDeliverError } from './web-deliver.js';
+
+/** Same cap as the backend upload route (_MAX_FILE_SIZE_BYTES). */
+export const FILE_MAX_BYTES = 50 * 1024 * 1024;
+/** Files per delivery command (keeps one command reasonable; more files -> zip them). */
+export const FILES_MAX = 20;
+/** Upper bound for the note; long reports belong in a file. */
+export const NOTE_MAX_CHARS = 5000;
+
+// Extension -> MIME type. Unknown extensions go up as application/octet-stream (the real filename keeps
+// the extension, so the buyer can still open it).
+export const MIME_BY_EXT = {
+  '.pdf': 'application/pdf',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.ppt': 'application/vnd.ms-powerpoint',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  '.csv': 'text/csv',
+  '.txt': 'text/plain',
+  '.md': 'text/markdown',
+  '.json': 'application/json',
+  '.html': 'text/html',
+  '.htm': 'text/html',
+  '.zip': 'application/zip',
+  '.7z': 'application/x-7z-compressed',
+  '.rar': 'application/vnd.rar',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.svg': 'image/svg+xml',
+  '.mp3': 'audio/mpeg',
+  '.m4a': 'audio/mp4',
+  '.wav': 'audio/wav',
+  '.mp4': 'video/mp4',
+  '.mov': 'video/quicktime',
+  '.webm': 'video/webm',
+};
+
+/** MIME type for a local path (by extension). */
+export function mimeFor(path) {
+  return MIME_BY_EXT[extname(path).toLowerCase()] || 'application/octet-stream';
+}
+
+/**
+ * Check every file and the note before anything goes to the network.
+ * @returns {Array<{absPath:string, filename:string, mime:string, size:number, buf:Buffer, sha:string}>}
+ * @throws {WebDeliverError} exit code 2 (the caller can fix it and retry)
+ */
+export function prepareFiles(paths, note) {
+  const list = (paths || []).filter((p) => p != null && p !== '');
+  if (list.length === 0) {
+    throw new WebDeliverError('缺少 --file 参数：请给出要交付的文件路径（可写多个 --file）。', { exitCode: 2 });
+  }
+  if (list.length > FILES_MAX) {
+    throw new WebDeliverError(`一次最多交付 ${FILES_MAX} 个文件，你给了 ${list.length} 个。文件太多时请先打成一个 zip。`, { exitCode: 2 });
+  }
+  if (note != null && note.length > NOTE_MAX_CHARS) {
+    throw new WebDeliverError(`交付说明有 ${note.length} 字，超过 ${NOTE_MAX_CHARS} 字上限。长内容请写进文件里一起交付，说明只写要点。`, { exitCode: 2 });
+  }
+  const out = [];
+  const seen = new Set();
+  for (const file of list) {
+    let absPath;
+    let st;
+    try {
+      absPath = realpathSync(file);
+      st = statSync(absPath);
+    } catch {
+      throw new WebDeliverError(`找不到文件：${file}。请检查路径。`, { exitCode: 2 });
+    }
+    if (!st.isFile()) {
+      throw new WebDeliverError(`${file} 不是文件。文件夹请先压缩成 zip 再交付。`, { exitCode: 2 });
+    }
+    if (seen.has(absPath)) continue; // the same file given twice: upload once
+    seen.add(absPath);
+    if (st.size === 0) {
+      throw new WebDeliverError(`${file} 是空文件。请确认内容已生成，再重新交付。`, { exitCode: 2 });
+    }
+    if (st.size > FILE_MAX_BYTES) {
+      throw new WebDeliverError(`${file} 有 ${humanSize(st.size)}，超过单个文件 50MB 上限。请压缩或拆分后再交付。`, { exitCode: 2 });
+    }
+    let buf;
+    try {
+      buf = readFileSync(absPath);
+    } catch {
+      throw new WebDeliverError(`读不了文件：${file}。`, { exitCode: 2 });
+    }
+    out.push({
+      absPath,
+      filename: basename(absPath),
+      mime: mimeFor(absPath),
+      size: st.size,
+      buf,
+      sha: createHash('sha256').update(buf).digest('hex'),
+    });
+  }
+  return out;
+}
+
+/**
+ * Run upload (each file) -> deliver.
+ *
+ * @param {object} ctx { baseUrl, credOpts, fetchImpl?, token, taskId, files: string[], note?, idemKey?, onProgress?(msg) }
+ * @returns {Promise<object>} { taskId, round, files: [{fileId, filename, sizeBytes}], note, deliver }
+ * @throws {WebDeliverError} message already in Chinese
+ */
+export async function deliverFiles(ctx) {
+  const { baseUrl, credOpts, fetchImpl, token, taskId, idemKey, onProgress } = ctx;
+  const note = ctx.note != null && String(ctx.note).trim() !== '' ? String(ctx.note).trim() : null;
+  const prepared = prepareFiles(ctx.files, note);
+  const progress = onProgress || (() => {});
+
+  const wrap = (e, step) => {
+    if (e instanceof WebDeliverError) return e;
+    if (e && e.upgradeRequired) throw e; // let the top-level handler print the upgrade hint (exit 4)
+    const text = `${step}失败：${e && e.message ? e.message : String(e)}`;
+    return new WebDeliverError(text, { status: e && typeof e.status === 'number' ? e.status : null });
+  };
+
+  const uploaded = [];
+  const putFetch = fetchImpl || globalThis.fetch;
+  for (const f of prepared) {
+    // 1. upload address. The key depends on the bytes, so re-running the same command reuses the same file_id.
+    progress(`申请上传（${f.filename}，${humanSize(f.size)}）…`);
+    let req;
+    try {
+      req = await requestUpload(baseUrl, credOpts, {
+        task_id: taskId,
+        kind: 'deliverable',
+        mime_type: f.mime,
+        size_bytes: f.size,
+        filename: f.filename,
+      }, { fetchImpl, idempotencyKey: `file-upload-${taskId}-${f.sha.slice(0, 32)}` });
+    } catch (e) {
+      throw wrap(e, `申请上传 ${f.filename} `);
+    }
+    if (!req || !req.signed_put_url || !req.file_id) {
+      throw new WebDeliverError('平台没有返回上传地址，请稍后重试。');
+    }
+    // 2. direct upload
+    progress(`上传 ${f.filename}…`);
+    let putResp;
+    try {
+      putResp = await putFetch(req.signed_put_url, { method: 'PUT', headers: { 'Content-Type': f.mime }, body: f.buf });
+    } catch (netErr) {
+      throw new WebDeliverError(`上传 ${f.filename} 失败（网络错误）：${netErr && netErr.message ? netErr.message : netErr}。可重新运行同一条命令。`);
+    }
+    if (!putResp.ok) {
+      throw new WebDeliverError(`上传 ${f.filename} 失败（状态 ${putResp.status}），可重新运行同一条命令。`, { status: putResp.status });
+    }
+    uploaded.push({ fileId: req.file_id, filename: f.filename, sizeBytes: f.size });
+  }
+
+  // 3. deliver: the platform puts every file uploaded in this round into the new version
+  progress('提交交付…');
+  const resultPayload = { file_id: uploaded[0].fileId, type: 'file', ...usageFields(ctx.models, ctx.tokens) };
+  if (note) resultPayload.text = note;
+  const deliverKey = idemKey || buildWebDeliverIdemKey(taskId, token, note, uploaded.map((u) => u.fileId).join(','));
+  let deliver;
+  try {
+    deliver = await runtimeAct(baseUrl, credOpts, 'deliver_job', { job_id: taskId, result_payload: resultPayload }, deliverKey, { fetchImpl });
+  } catch (e) {
+    throw wrap(e, '提交交付');
+  }
+
+  // Best effort: read back the version number. Delivery already succeeded.
+  let round = null;
+  try {
+    const view = await getTaskDeliverables(baseUrl, credOpts, taskId, { fetchImpl });
+    const versions = Array.isArray(view && view.versions) ? view.versions : [];
+    const hit = versions.find((v) => Array.isArray(v.files) && v.files.some((x) => x.file_id === uploaded[0].fileId));
+    if (hit) round = hit.round ?? null;
+  } catch { /* summary only */ }
+
+  return { taskId, round, files: uploaded, note, deliver };
+}
+
+/** Human-readable success summary (or JSON). */
+export function formatFileDeliver(r, { json = false } = {}) {
+  if (json) {
+    return JSON.stringify({
+      ok: true,
+      task_id: r.taskId,
+      version: r.round,
+      files: r.files.map((f) => ({ file_id: f.fileId, filename: f.filename, size_bytes: f.sizeBytes })),
+      note: r.note,
+      status: r.deliver && r.deliver.to_status ? r.deliver.to_status : null,
+    }, null, 2);
+  }
+  const lines = ['文件已交付！（系统自动进入待验收）'];
+  lines.push(`  任务 ID：${r.taskId}`);
+  lines.push(`  交付版本：${r.round != null ? `第 ${r.round} 版` : '（已提交）'}`);
+  for (const f of r.files) lines.push(`  文件：${f.filename}（${humanSize(f.sizeBytes)}）`);
+  lines.push(r.note ? '  交付说明：已附上' : '  交付说明：未填写（建议用 --note 写清交付了什么、怎么用、关键结论）');
+  if (r.deliver && r.deliver.from_status && r.deliver.to_status) {
+    lines.push(`  状态变更：${r.deliver.from_status} → ${r.deliver.to_status}`);
+  }
+  return lines.join('\n');
+}