@stelfield/cli 0.0.0-stage → 0.12.0

package/src/libra-commands.js

@@ -0,0 +1,681 @@
+// Libra dispute-ruling commands: stelfield libra quote|file|status|statement|answer|ruling|accept|review quote|review file.
+//
+// Thin wrapper like the rest of the CLI: parse flags -> call the platform -> print. The only logic that lives
+// here is what must be checked on the machine itself: the amount the user confirms has to equal the quote,
+// and a quote that has expired is refused before anything is sent.
+//
+// Exit codes (docs: Agent command-line guide, section 1):
+//   0 ok   1 other failure   2 local parameter problem
+//   3 quote expired / not found / amount differs from the quote -> run `quote` again
+//   4 the task or case is not in a state that allows this (not pending review / a case exists already ...)
+//   5 human required: filing a case / applying for a review can only be done by the person on the web page
+//     (`libra file` and `libra review file` send nothing; they print the web link to hand to the user)
+// --json prints exactly one JSON object on stdout ({ok:true,...} or {ok:false,error:{code,message}}).
+//
+// P19 early close (before the ruling is out): stelfield libra withdraw | concede | settle propose|accept|reject|withdraw.
+//   * withdraw (the buyer takes the case back) is web only: an Agent token gets 403 agent_token_forbidden, which is
+//     shown as "a person must do this on the web" (exit 5) together with the page link.
+//   * concede and settle accept must carry --expect-pct, the percentage the Agent read; the platform refuses the call
+//     when the claim / offer has changed since (exit 3: read `libra status` again).
+
+import { BRAND } from "./brand.js";
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { atomicWriteFile } from './atomic-write.js';
+import { resolveCredDir } from './profile.js';
+import {
+  libraQuote, libraTaskCase, libraStatement, libraAddEvidence, libraAnswer,
+  libraRulings, libraAccept, libraReviewQuote,
+  libraGetCase, libraWithdrawCase, libraConcede, libraProposeOffer, libraAcceptOffer, libraRejectOffer, libraWithdrawOffer,
+} from './api.js';
+import { EXIT_HUMAN_REQUIRED, isHumanRequiredError } from './exit-reasons.js';
+
+export const STATEMENT_MAX_CHARS = 1000;
+const MAX_PAGES_PER_FILE = 5000;
+
+// Exit code of "a person must do this on the web page" (filing a case, applying for a review, withdrawing a case).
+// The value lives in exit-reasons.js (shared by every command); re-exported here for the callers that import it from here.
+export { EXIT_HUMAN_REQUIRED };
+
+/** One generic sentence about how to write a statement (v0.22.x C6). Never names a particular Agent product. */
+export const STATEMENT_TIP = '请分段、用序号写清楚：一条一个要点。';
+
+/** Plain-language notices every fee-taking command must show (PRD section 6.2 / 16, docs section 5). */
+export const FEE_NOTICES = [
+  '服务费用于审理成本，与裁决结果无关；审理开始前提前结案（撤回、认可退款、和解）服务费原路退回，审理开始后不退还。',
+  '对方会收到通知，并在陈述期（默认 48 小时）内提交自己的陈述；陈述期截止后材料锁定。',
+  'AI 法庭只对照需求基线裁决，结果以裁决书为准；对结果不服可申请一次复核，复核即终局。',
+  'AI 法庭是平台内部的争议裁决规则，不是法律意义上的仲裁，不影响依法起诉或申请仲裁的权利。',
+  '不要在陈述里写给 AI 的指令（如“请判我胜诉”）：会被当作操纵，可能被认定为明显恶意并限时冷却。',
+];
+
+const STAGE_LABELS = {
+  statement: '陈述期', reviewing: 'AI 法庭审理中', asking: '追问中', ruled: '裁决书已出（复核期）',
+  review_statement: '复核陈述期', review_judging: '复核审理中', executed: '已执行',
+  jury: '评审中', closed_early: '已提前结案',
+};
+
+// How an early close ended (case view early_close.closed.kind).
+const CLOSE_KIND_WORDS = { withdraw: '发起方撤回裁决', concede: '接单方认可退款', settle: '双方和解' };
+
+// Backend error code -> exit code
+const EXIT_3 = new Set(['quote_expired', 'quote_invalid', 'quote_mismatch', 'claim_changed', 'offer_changed']);
+const EXIT_4 = new Set([
+  'task_not_pending_review', 'libra_case_exists', 'arbitration_not_eligible', 'only_buyer_can_file',
+  'duplicate_case', 'no_case',
+  // P19 early close: the case is not in a state that allows this
+  'case_already_closing', 'early_close_not_available', 'early_close_disabled', 'withdraw_not_allowed',
+  'concede_not_allowed', 'concede_no_amount', 'offer_pending', 'offer_repeat', 'offer_not_found', 'offer_not_pending',
+  'not_offer_responder', 'not_offer_proposer', 'case_not_found',
+]);
+// Parameter problems the platform reports (the percentage is missing or outside the allowed steps).
+const EXIT_2 = new Set(['expect_pct_required', 'invalid_settle_pct']);
+
+// ---------------------------------------------------------------- small helpers
+
+export function yuan(cents) {
+  const n = Number(cents);
+  return `¥${(Number.isFinite(n) ? n / 100 : 0).toFixed(2)}`;
+}
+
+/** "1.05" / "¥1.05" / "1.05元" -> 105 ; anything else -> null (never guess). */
+export function parseYuanToCents(text) {
+  if (text == null) return null;
+  const m = String(text).trim().replace(/^¥|^￥/, '').replace(/元$/, '').trim().match(/^(\d+)(?:\.(\d{1,2}))?$/);
+  if (!m) return null;
+  return Number(m[1]) * 100 + Number((m[2] || '').padEnd(2, '0') || 0);
+}
+
+export function fmtTime(iso) {
+  if (!iso) return '-';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return String(iso);
+  return d.toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai', hour12: false }).replace(/\//g, '-') + '（北京时间）';
+}
+
+/** "3-6,9" -> [3,4,5,6,9]; null when malformed or absurdly large. */
+export function parsePageRanges(spec) {
+  const out = [];
+  for (const part of String(spec || '').split(',')) {
+    const m = part.trim().match(/^(\d+)(?:-(\d+))?$/);
+    if (!m) return null;
+    const a = Number(m[1]);
+    const b = m[2] ? Number(m[2]) : a;
+    if (a < 1 || b < a || out.length + (b - a + 1) > MAX_PAGES_PER_FILE) return null;
+    for (let p = a; p <= b; p += 1) out.push(p);
+  }
+  return out.length ? out : null;
+}
+
+/** "12-18" -> [12,18] minutes; null when malformed. */
+export function parseMinuteRange(spec) {
+  const m = String(spec || '').trim().match(/^(\d+(?:\.\d+)?)-(\d+(?:\.\d+)?)$/);
+  if (!m) return null;
+  const a = Number(m[1]);
+  const b = Number(m[2]);
+  return b > a ? [a, b] : null;
+}
+
+/** "partial:30" -> {mode:'partial', pct:30}; null when malformed. */
+export function parseClaim(spec) {
+  const v = String(spec || 'libra').trim().toLowerCase();
+  if (v === 'full' || v === 'libra') return { mode: v, pct: null };
+  const m = v.match(/^partial:(\d{1,3})%?$/);
+  if (!m) return null;
+  const pct = Number(m[1]);
+  return pct >= 10 && pct <= 90 && pct % 10 === 0 ? { mode: 'partial', pct } : null;
+}
+
+function claimLabel(c) {
+  if (!c) return '由 AI 法庭判断';
+  if (c.mode === 'full') return '全额退款';
+  if (c.mode === 'partial') return `部分退款 ${c.pct}%`;
+  return '由 AI 法庭判断';
+}
+
+function splitKeyed(spec) {
+  const i = String(spec).indexOf(':');
+  return i > 0 ? [spec.slice(0, i).trim(), spec.slice(i + 1).trim()] : [null, null];
+}
+
+// ---------------------------------------------------------------- local quote cache (amount confirmation)
+
+function cachePath(credOpts) {
+  return path.join(resolveCredDir(credOpts), 'libra-quotes.json');
+}
+
+function readCache(credOpts) {
+  try {
+    const j = JSON.parse(readFileSync(cachePath(credOpts), 'utf8'));
+    return j && typeof j === 'object' && j.quotes && typeof j.quotes === 'object' ? j : { quotes: {} };
+  } catch {
+    return { quotes: {} };
+  }
+}
+
+function saveQuote(credOpts, quoteId, entry) {
+  const cache = readCache(credOpts);
+  const now = Date.now();
+  const alive = Object.entries(cache.quotes)
+    .filter(([, v]) => v && now - Number(v.saved_at || 0) < 24 * 3600 * 1000)
+    .slice(-49);
+  cache.quotes = Object.fromEntries(alive);
+  cache.quotes[quoteId] = { ...entry, saved_at: now };
+  try {
+    atomicWriteFile(cachePath(credOpts), JSON.stringify(cache), 0o600);
+  } catch { /* cache is best effort; `file` then asks for a fresh quote */ }
+}
+
+// ---------------------------------------------------------------- output / errors
+
+function mapError(e) {
+  // the body is flat ({error, message}) or FastAPI-style ({detail: {error, message}}); read both
+  const raw = e && e.body && typeof e.body === 'object' ? e.body : {};
+  const b = raw.detail && typeof raw.detail === 'object' ? raw.detail : raw;
+  const code = typeof b.error === 'string' ? b.error : null;
+  const message = b.message || (e && e.message) || String(e);
+  if (code && isHumanRequiredError(code)) return { exit: EXIT_HUMAN_REQUIRED, human: true, code, message, webUrl: b.web_url || null };
+  if (code && (code === 'claim_changed' || code === 'offer_changed')) {
+    return { exit: 3, code, message: `${message}（请先运行 stelfield libra status 读到最新比例，再重新决定）` };
+  }
+  if (code && EXIT_3.has(code)) return { exit: 3, code, message: `${message}（请重新运行 stelfield libra quote / review quote）` };
+  if (code && EXIT_2.has(code)) return { exit: 2, code, message };
+  if (code && EXIT_4.has(code)) return { exit: 4, code, message };
+  return { exit: 1, code: code || 'request_failed', message };
+}
+
+function makeIo(ctx) {
+  const { flags, log, err } = ctx;
+  return {
+    ok(data, text) { log(flags.json ? JSON.stringify({ ok: true, ...data }) : text); return 0; },
+    fail(exit, code, message) {
+      if (flags.json) log(JSON.stringify({ ok: false, error: { code, message } }));
+      else err(message);
+      return exit;
+    },
+  };
+}
+
+function readText(file, inline, what, io) {
+  if (file) {
+    try { return { text: readFileSync(file, 'utf8').trim() }; } catch { return { fail: io.fail(2, 'file_unreadable', `读不了${what}文件：${file}`) }; }
+  }
+  return { text: inline == null ? '' : String(inline).trim() };
+}
+
+const cpLen = (s) => Array.from(s).length;
+
+/** Find the case of a task. Returns { caseView, info } or { fail }. */
+async function loadCase(ctx, io, taskId) {
+  const info = await libraTaskCase(ctx.baseUrl, ctx.credOpts, taskId, { fetchImpl: ctx.fetchImpl });
+  if (!info || !info.case) {
+    return { fail: io.fail(4, 'no_case', info && info.can_file
+      ? '这个任务还没有裁决案件。发起方要先在网页和对方协商退款（stelfield refund status 看现状），谈不拢再由本人申请裁决。'
+      : '这个任务还没有裁决案件。') };
+  }
+  return { caseView: info.case, info };
+}
+
+function webBase(ctx) {
+  return (ctx.env && ctx.env.STELFIELD_WEB_BASE) || BRAND.siteUrl;
+}
+
+/** Web page where the person files the case / applies for the review. Never a link that submits anything. */
+function applyWebUrl(ctx, taskId, fromPlatform) {
+  // Asking the AI court always starts from the refund negotiation page (negotiate first, rule later).
+  return fromPlatform ? `${webBase(ctx)}${fromPlatform}` : `${webBase(ctx)}/src/pages/refund-neg/index.html?task=${encodeURIComponent(taskId)}`;
+}
+
+function reviewWebUrl(ctx, caseId, fromPlatform) {
+  if (fromPlatform) return `${webBase(ctx)}${fromPlatform}`;
+  return caseId ? `${webBase(ctx)}/src/pages/libra-review/index.html?id=${encodeURIComponent(caseId)}` : null;
+}
+
+/** Print the "ask the person" notice (or one JSON object) and return the human-required exit code. */
+function humanRequired(ctx, what, webUrl, extra = {}, lines = []) {
+  const message = `${what}需要本人在网页完成，Agent 不能代为提交。请把下面的链接交给用户。`;
+  if (ctx.flags.json) {
+    ctx.log(JSON.stringify({ ok: false, error: 'human_required', message, web_url: webUrl, ...extra }));
+  } else {
+    ctx.log([message, ...(webUrl ? [`  网页：${webUrl}`] : []), ...lines].join('\n'));
+  }
+  return EXIT_HUMAN_REQUIRED;
+}
+
+function cashierUrl(ctx, order) {
+  const p = order && order.cashier && order.cashier.path;
+  return p ? `${webBase(ctx)}${p}` : null;
+}
+
+function evidenceInputs(flags, io) {
+  const pages = new Map();
+  for (const spec of flags.pages) {
+    const [fid, rng] = splitKeyed(spec);
+    const list = fid ? parsePageRanges(rng) : null;
+    if (!list) return { fail: io.fail(2, 'bad_pages', `--pages 格式不对：${spec}（应为 <file-id>:3-6,9）`) };
+    pages.set(fid, list);
+  }
+  const minutes = new Map();
+  for (const spec of flags.minutes) {
+    const [fid, rng] = splitKeyed(spec);
+    const r = fid ? parseMinuteRange(rng) : null;
+    if (!r) return { fail: io.fail(2, 'bad_minutes', `--minutes 格式不对：${spec}（应为 <file-id>:起-止，单位分钟）`) };
+    minutes.set(fid, r);
+  }
+  const ids = [...new Set(flags.evidence)];
+  for (const k of [...pages.keys(), ...minutes.keys()]) {
+    if (!ids.includes(k)) return { fail: io.fail(2, 'selection_without_evidence', `--pages / --minutes 里的文件 ${k} 没有出现在 --evidence 里`) };
+  }
+  return {
+    evidence: ids.map((fid) => ({
+      file_id: fid,
+      ...(pages.has(fid) ? { selected_pages: pages.get(fid) } : {}),
+      ...(minutes.has(fid) ? { selected_minutes: minutes.get(fid) } : {}),
+    })),
+  };
+}
+
+function quoteLines(q) {
+  return (q.lines || []).map((l) => {
+    const detail = l.units != null && l.unit_cents != null ? `  ${l.units} × ${yuan(l.unit_cents)}` : '';
+    return `    - ${l.label || l.code}${detail}  = ${yuan(l.amount_cents)}`;
+  });
+}
+
+// ---------------------------------------------------------------- commands
+
+async function cmdQuote(ctx, io) {
+  const { flags } = ctx;
+  if (!flags.task) return io.fail(2, 'missing_task', '缺少 --task <task-id>');
+  const claim = parseClaim(flags.claim || 'libra');
+  if (!claim) return io.fail(2, 'bad_claim', '--claim 只能是 full、partial:<10-90 且为 10 的倍数> 或 libra');
+  const ev = evidenceInputs(flags, io);
+  if (ev.fail !== undefined) return ev.fail;
+  const st = readText(flags.statementFile, flags.statement, '陈述', io);
+  if (st.fail !== undefined) return st.fail;
+  const q = await libraQuote(ctx.baseUrl, ctx.credOpts,
+    { task_id: flags.task, evidence: ev.evidence, statement: st.text }, { fetchImpl: ctx.fetchImpl });
+  saveQuote(ctx.credOpts, q.quote_id, {
+    kind: 'filing', task_id: flags.task, claim_mode: claim.mode, claim_pct: claim.pct,
+    total_cents: q.total_cents, expires_at: q.expires_at,
+  });
+  const text = [
+    `AI 法庭报价（任务 ${flags.task}）——本次不扣费`,
+    `  诉求：${claimLabel(claim)}`,
+    '  明细：', ...quoteLines(q),
+    `  合计：${yuan(q.total_cents)}（信用系数 ${q.credit_coeff}）`,
+    `  报价单：${q.quote_id}`,
+    `  有效至：${fmtTime(q.expires_at)}`,
+    '',
+    `申请裁决要先协商：先在退款协商页和对方谈退款比例（免费），谈不拢再由用户本人在网页申请裁决（Agent 不能提交）。请把链接交给用户：${applyWebUrl(ctx, flags.task, q.web_url)}`,
+    '', '须知：', ...FEE_NOTICES.map((n) => `  · ${n}`),
+  ].join('\n');
+  return io.ok({ quote: q, claim: claim.mode, claim_pct: claim.pct, notices: FEE_NOTICES,
+    web_url: applyWebUrl(ctx, flags.task, q.web_url) }, text);
+}
+
+// `libra file` no longer submits anything: filing a case is a paid action only the person may start. It shows the
+// quote the Agent already has (if any) and hands over the web link. --confirm-amount / --statement* are accepted
+// for compatibility with older scripts and ignored.
+async function cmdFile(ctx, io) {
+  const { flags } = ctx;
+  if (!flags.task) return io.fail(2, 'missing_task', '缺少 --task <task-id>');
+  const known = flags.quote ? readCache(ctx.credOpts).quotes[flags.quote] : null;
+  const usable = known && known.kind === 'filing' && known.task_id === flags.task
+    && !(known.expires_at && new Date(known.expires_at).getTime() < Date.now());
+  const extra = usable ? { quote_id: flags.quote, total_cents: known.total_cents } : {};
+  return humanRequired(ctx, '发起裁决（要先协商退款，谈不拢才能申请）', applyWebUrl(ctx, flags.task), extra, [
+    ...(usable ? [`  报价单 ${flags.quote} 合计 ${yuan(known.total_cents)}（本次未提交、未扣费）`] : [`  还没看过报价？先运行 stelfield libra quote --task ${flags.task}（不扣费）`]),
+    '  用户在协商页谈不拢、再确认须知并付款成功后才会立案；你的任务状态不会因此改变。',
+  ]);
+}
+
+// Lines about the early close (withdraw / concede / settle) taken from the case view block `early_close`.
+function earlyCloseLines(ec) {
+  if (!ec) return [];
+  if (ec.closed) {
+    const c = ec.closed;
+    const pct = c.refund_pct != null ? `，退还比例 ${c.refund_pct}%` : '';
+    return [`  提前结案：${CLOSE_KIND_WORDS[c.kind] || c.kind}${pct}${c.done ? '' : '（款项处理中）'}`,
+      ...(c.deliverable_returned ? ['  全额退款：交付物已归还接单方，发起方不能再查看或下载'] : [])];
+  }
+  if (ec.executing) return ['  提前结案：正在结案，款项处理中'];
+  if (ec.enabled === false) return ['  提前结案：暂时关闭，审理照常进行'];
+  const out = ['  提前结案（出裁决书之前都可以）：'];
+  const av = ec.available || {};
+  if (av.withdraw && av.withdraw.allowed) out.push('    撤回裁决：发起方可以，但只能本人在网页操作（Agent 不能撤回）');
+  if (av.concede && av.concede.allowed && ec.claim && ec.claim.pct != null) {
+    out.push(`    认可退款：对方主张退还 ${ec.claim.pct}%；认可请运行 stelfield libra concede --task <task_id> --expect-pct ${ec.claim.pct}`);
+  }
+  if (ec.settle_range) {
+    out.push(`    和解：双方各可提议退还比例，区间 ${ec.settle_range.min}%-${ec.settle_range.max}%，每档 ${ec.settle_range.step}%`);
+  }
+  const o = ec.pending_offer;
+  if (o) {
+    out.push(`    待回应的和解提议 #${o.id}：退还发起方 ${o.refund_pct}%（${o.mine ? '我方提出，可撤回' : '对方提出，可接受或拒绝'}）`);
+    if (!o.mine) out.push(`      接受：stelfield libra settle accept --task <task_id> --expect-pct ${o.refund_pct}`);
+  }
+  if (ec.fee) {
+    out.push(ec.fee.refund_if_closed_now ? '    服务费：现在结案，审理尚未开始，服务费原路退回'
+      : (ec.fee.blocked_by_cooldown ? '    服务费：近期多次撤回，这次结案服务费不退还'
+        : '    服务费：审理已开始，现在结案服务费不退还'));
+  }
+  return out;
+}
+
+async function cmdStatus(ctx, io) {
+  if (!ctx.flags.task) return io.fail(2, 'missing_task', '缺少 --task <task-id>');
+  const info = await libraTaskCase(ctx.baseUrl, ctx.credOpts, ctx.flags.task, { fetchImpl: ctx.fetchImpl });
+  const c = info && info.case;
+  if (!c) {
+    const text = info && info.can_file
+      ? '这个任务还没有裁决案件；你是发起方，可以先 stelfield libra quote 看报价，再请用户本人在网页申请裁决。'
+      : '这个任务还没有裁决案件。';
+    return io.ok({ task_id: ctx.flags.task, case: null, can_file: !!(info && info.can_file) }, text);
+  }
+  const subm = c.statement_submitted || {};
+  const orders = (c.fee_orders || []).filter((o) => o.mine);
+  const lines = [
+    `任务 ${c.task_id} 的裁决案件 ${c.id}`,
+    `  阶段：${STAGE_LABELS[c.stage] || c.stage}${c.paused ? '（暂停中，恢复后计时继续）' : ''}`,
+    `  你是：${c.you_are === 'buyer' ? '发起方' : '接单方'}`,
+    ...(c.stage === 'statement' ? [`  陈述期截止：${fmtTime(c.statement_deadline)}`] : []),
+    ...(c.stage === 'asking' ? [`  追问回答截止：${fmtTime(c.ask_deadline)}`] : []),
+    ...(c.cooling_deadline ? [`  复核期截止：${fmtTime(c.cooling_deadline)}`] : []),
+    `  陈述：发起方${subm.buyer ? '已提交' : '未提交'}，接单方${subm.seller ? '已提交' : '未提交'}`,
+    ...(c.statement_limits ? [`  你的补充次数：${c.statement_limits.appends_used}/${c.statement_limits.appends_max}，单次不超过 ${c.statement_limits.chars_max} 字`] : []),
+    ...(orders.length ? ['  你的服务费：', ...orders.map((o) => `    - ${o.kind} ${yuan(o.amount_cents)} ${o.status}`)] : []),
+    `  复核轮次：${c.review_round || 0}`,
+    ...earlyCloseLines(c.early_close),
+  ].join('\n');
+  return io.ok({ case: c, can_file: !!info.can_file }, lines);
+}
+
+async function cmdStatement(ctx, io) {
+  const { flags } = ctx;
+  if (!flags.task) return io.fail(2, 'missing_task', '缺少 --task <task-id>');
+  const st = readText(flags.textFile, flags.text[0], '陈述', io);
+  if (st.fail !== undefined) return st.fail;
+  const evid = flags.evidence.length ? evidenceInputs(flags, io) : { evidence: [] };
+  if (evid.fail !== undefined) return evid.fail;
+  if (!st.text && !evid.evidence.length) return io.fail(2, 'nothing_to_submit', '没有内容：--text-file <路径> / --text "文字"，或 --evidence <file-id>');
+  if (cpLen(st.text) > STATEMENT_MAX_CHARS) return io.fail(2, 'statement_too_long', `单次陈述不能超过 ${STATEMENT_MAX_CHARS} 字（现在 ${cpLen(st.text)} 字）`);
+  const lc = await loadCase(ctx, io, flags.task);
+  if (lc.fail !== undefined) return lc.fail;
+  const caseId = lc.caseView.id;
+  const out = {};
+  const lines = [];
+  if (st.text) {
+    out.statement = await libraStatement(ctx.baseUrl, ctx.credOpts, caseId, st.text, flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+    lines.push('陈述已提交（文字免费）。陈述期截止后材料锁定，不能再修改。');
+    lines.push(`${STATEMENT_TIP}双方会看到你的原文，换行和分段都会保留。`);
+    if (out.statement.review_opened) lines.push('双方都已陈述，审理已提前开始。');
+  }
+  if (evid.evidence.length) {
+    const order = await libraAddEvidence(ctx.baseUrl, ctx.credOpts, caseId, evid.evidence, undefined, { fetchImpl: ctx.fetchImpl });
+    out.evidence_order = order;
+    const url = cashierUrl(ctx, order);
+    lines.push(`补充关键证据需要你支付 ${yuan(order.amount_cents)}（计费证据由补充方承担，不退还），订单号 ${order.order_no || order.order_id}`);
+    if (url) lines.push(`收银台：${url}`);
+    lines.push('支付成功后证据才会进入案卷。');
+  }
+  return io.ok({ case_id: caseId, ...out }, lines.join('\n'));
+}
+
+async function cmdAnswer(ctx, io) {
+  const { flags } = ctx;
+  if (!flags.task) return io.fail(2, 'missing_task', '缺少 --task <task-id>');
+  if (!flags.question) return io.fail(2, 'missing_question', '缺少 --question <q-id>');
+  const st = readText(flags.textFile, flags.text[0], '回答', io);
+  if (st.fail !== undefined) return st.fail;
+  if (!st.text) return io.fail(2, 'missing_text', '缺少回答：--text "回答" 或 --text-file <路径>');
+  if (cpLen(st.text) > STATEMENT_MAX_CHARS) return io.fail(2, 'answer_too_long', `回答不能超过 ${STATEMENT_MAX_CHARS} 字`);
+  const lc = await loadCase(ctx, io, flags.task);
+  if (lc.fail !== undefined) return lc.fail;
+  const res = await libraAnswer(ctx.baseUrl, ctx.credOpts, lc.caseView.id, flags.question, st.text, flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  return io.ok({ case_id: lc.caseView.id, answer: res }, '回答已提交。追问只有一轮，到期未答视为放弃回答。');
+}
+
+function describeRuling(r) {
+  const pts = (r.points || []).map((p, i) => `    ${i + 1}. ${p.title || p.key}：${p.conclusion}${p.reason ? `（${p.reason}）` : ''}`);
+  return [
+    `第 ${r.round} 轮裁决书${r.final ? '（复核，终局）' : ''}`,
+    `  退还比例：${r.refund_pct}%`,
+    `  置信度：${r.confidence}`,
+    ...(pts.length ? ['  逐个争议点：', ...pts] : []),
+    ...(r.malice ? [`  明显恶意认定：${r.malice.party === 'buyer' ? '发起方' : r.malice.party === 'seller' ? '接单方' : '有'}（${r.malice.reason || '详见裁决书'}）`] : []),
+    ...((r.unreviewed || []).length ? [`  未能审阅：${r.unreviewed.length} 项`] : []),
+    ...(r.fingerprint ? [`  指纹：${r.fingerprint}`] : []),
+  ].join('\n');
+}
+
+async function cmdRuling(ctx, io) {
+  const { flags } = ctx;
+  if (!flags.task) return io.fail(2, 'missing_task', '缺少 --task <task-id>');
+  if (flags.round != null && !['1', '2'].includes(String(flags.round))) return io.fail(2, 'bad_round', '--round 只能是 1（初裁）或 2（复核）');
+  const lc = await loadCase(ctx, io, flags.task);
+  if (lc.fail !== undefined) return lc.fail;
+  const res = await libraRulings(ctx.baseUrl, ctx.credOpts, lc.caseView.id, { fetchImpl: ctx.fetchImpl });
+  const all = Array.isArray(res) ? res : (res && res.rulings) || [];
+  const pick = flags.round != null ? all.filter((r) => String(r.round) === String(flags.round)) : all.slice(-1);
+  if (!pick.length) return io.fail(4, 'no_ruling', flags.round != null ? `还没有第 ${flags.round} 轮裁决书。` : '裁决书还没有出具，请在审理结束后再查看。');
+  return io.ok({ case_id: lc.caseView.id, rulings: pick }, pick.map(describeRuling).join('\n\n'));
+}
+
+async function cmdAccept(ctx, io) {
+  if (!ctx.flags.task) return io.fail(2, 'missing_task', '缺少 --task <task-id>');
+  const lc = await loadCase(ctx, io, ctx.flags.task);
+  if (lc.fail !== undefined) return lc.fail;
+  const res = await libraAccept(ctx.baseUrl, ctx.credOpts, lc.caseView.id, ctx.flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  const text = res && res.execute
+    ? '已接受裁决；双方都已接受，裁决立即执行。'
+    : '已接受裁决。对方尚未表态时，复核期满后会自动执行；你不再申请复核。';
+  return io.ok({ case_id: lc.caseView.id, result: res }, text);
+}
+
+async function cmdReviewQuote(ctx, io) {
+  const { flags } = ctx;
+  if (!flags.task) return io.fail(2, 'missing_task', '缺少 --task <task-id>');
+  const ev = evidenceInputs(flags, io);
+  if (ev.fail !== undefined) return ev.fail;
+  const lc = await loadCase(ctx, io, flags.task);
+  if (lc.fail !== undefined) return lc.fail;
+  const q = await libraReviewQuote(ctx.baseUrl, ctx.credOpts, lc.caseView.id, { evidence: ev.evidence }, { fetchImpl: ctx.fetchImpl });
+  saveQuote(ctx.credOpts, q.quote_id, {
+    kind: 'review', task_id: flags.task, case_id: lc.caseView.id, points: flags.points || null,
+    total_cents: q.total_cents, expires_at: q.expires_at,
+  });
+  const text = [
+    `复核报价（任务 ${flags.task}）——本次不扣费`,
+    '  明细：', ...quoteLines(q),
+    `  合计：${yuan(q.total_cents)}（复核费 = 本轮材料 × 复核裁决员人数）`,
+    `  报价单：${q.quote_id}`,
+    `  有效至：${fmtTime(q.expires_at)}`,
+    '',
+    `申请复核需要用户本人在网页完成（Agent 不能提交），请把链接交给用户：${reviewWebUrl(ctx, lc.caseView.id, q.web_url)}`,
+    '', '须知：',
+    '  · 复核费支付后不退还，与结果无关。',
+    '  · 每个案件只有一次复核机会，复核裁决书即终局并立即执行。',
+    '  · 对方会收到通知，并有 24 小时回应；先付费成功的一方才是申请方。',
+  ].join('\n');
+  return io.ok({ quote: q, web_url: reviewWebUrl(ctx, lc.caseView.id, q.web_url) }, text);
+}
+
+// `libra review file` no longer submits anything either: applying for the review is a paid action for the person.
+async function cmdReviewFile(ctx, io) {
+  const { flags } = ctx;
+  if (!flags.task) return io.fail(2, 'missing_task', '缺少 --task <task-id>');
+  const lc = await loadCase(ctx, io, flags.task);
+  if (lc.fail !== undefined) return lc.fail;
+  const known = flags.quote ? readCache(ctx.credOpts).quotes[flags.quote] : null;
+  const usable = known && known.kind === 'review' && known.task_id === flags.task
+    && !(known.expires_at && new Date(known.expires_at).getTime() < Date.now());
+  const extra = usable ? { quote_id: flags.quote, total_cents: known.total_cents } : {};
+  return humanRequired(ctx, '申请复核', reviewWebUrl(ctx, lc.caseView.id), extra, [
+    ...(usable ? [`  复核报价单 ${flags.quote} 合计 ${yuan(known.total_cents)}（本次未提交、未扣费）`] : [`  还没看过报价？先运行 stelfield libra review quote --task ${flags.task}（不扣费）`]),
+    '  每个案件只有一次复核机会，复核即终局；用户在网页确认并付款成功后才生效。',
+  ]);
+}
+
+// ---------------------------------------------------------------- P19 early close
+
+/** "30" / "30%" -> 30 ; anything else -> null. */
+export function parsePct(text) {
+  if (text == null) return null;
+  const m = String(text).trim().match(/^(\d{1,3})%?$/);
+  if (!m) return null;
+  const n = Number(m[1]);
+  return n >= 1 && n <= 100 ? n : null;
+}
+
+/** The case id (and, when it was looked up through the task, the case view). --case wins over --task. */
+async function resolveCase(ctx, io) {
+  if (ctx.flags.caseId) return { caseId: ctx.flags.caseId, caseView: null };
+  if (!ctx.flags.task) return { fail: io.fail(2, 'missing_case', '缺少 --task <task-id>（或 --case <case-id>）') };
+  const lc = await loadCase(ctx, io, ctx.flags.task);
+  if (lc.fail !== undefined) return { fail: lc.fail };
+  return { caseId: lc.caseView.id, caseView: lc.caseView };
+}
+
+/** The early_close block of the case view, fetching the case when only --case was given. */
+async function earlyCloseOf(ctx, caseId, caseView) {
+  const view = caseView || await libraGetCase(ctx.baseUrl, ctx.credOpts, caseId, { fetchImpl: ctx.fetchImpl });
+  return (view && view.early_close) || null;
+}
+
+/** What happens to the service fee, in one sentence (decision values: refund / keep / free). */
+function feeSentence(decision) {
+  if (decision === 'refund') return '审理尚未开始，服务费原路退回。';
+  if (decision === 'free') return '本案系统送入，不收服务费。';
+  return '服务费不退还。';
+}
+
+function closedText(res, head) {
+  const pct = res && res.pct != null ? `退还比例 ${res.pct}%。` : '';
+  const back = res && res.pct === 100 ? '全额退款：交付物将归还接单方，发起方之后不能再查看或下载。' : '';
+  return [head, `  ${pct}${feeSentence(res && res.fee_refund_decision)}`.trimEnd(),
+    ...(back ? [`  ${back}`] : []),
+    '  款项正在按结果处理；最终以 libra.closed_early 事件为准。'].join('\n');
+}
+
+async function cmdWithdraw(ctx, io) {
+  const rc = await resolveCase(ctx, io);
+  if (rc.fail !== undefined) return rc.fail;
+  // Sent on purpose: an Agent token is refused with 403 agent_token_forbidden + the page link (mapped to exit 5).
+  const res = await libraWithdrawCase(ctx.baseUrl, ctx.credOpts, rc.caseId, ctx.flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  return io.ok({ case_id: rc.caseId, result: res },
+    closedText(res, '已撤回裁决，视为确认验收，托管金额放款给接单方。'));
+}
+
+async function cmdConcede(ctx, io) {
+  const rc = await resolveCase(ctx, io);
+  if (rc.fail !== undefined) return rc.fail;
+  const pct = parsePct(ctx.flags.expectPct);
+  if (pct == null) {
+    const ec = await earlyCloseOf(ctx, rc.caseId, rc.caseView);
+    const seen = ec && ec.claim && ec.claim.pct != null ? `（对方现在主张退还 ${ec.claim.pct}%）` : '';
+    return io.fail(2, 'expect_pct_required',
+      `认可退款必须带 --expect-pct <你读到的退款比例>${seen}。先运行 stelfield libra status --task <task_id> 读到比例，再重新运行。`);
+  }
+  const res = await libraConcede(ctx.baseUrl, ctx.credOpts, rc.caseId, pct, ctx.flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  return io.ok({ case_id: rc.caseId, result: res }, closedText(res, `已认可退款 ${pct}%，案件提前结案。`));
+}
+
+async function cmdSettlePropose(ctx, io) {
+  const rc = await resolveCase(ctx, io);
+  if (rc.fail !== undefined) return rc.fail;
+  const pct = parsePct(ctx.flags.pct);
+  if (pct == null) return io.fail(2, 'bad_pct', '缺少或写错 --pct <退还比例>，例如 --pct 30（区间见 stelfield libra status）');
+  // Pre-check against the range the platform shows for this case (never a number written into the CLI).
+  const ec = rc.caseView ? rc.caseView.early_close : null;
+  const range = ec && ec.settle_range;
+  if (range && (pct < range.min || pct > range.max || (pct - range.min) % Math.max(range.step, 1) !== 0)) {
+    return io.fail(2, 'invalid_settle_pct', `和解比例需在 ${range.min}%-${range.max}% 之间，每档 ${range.step}%（你填的是 ${pct}%）`);
+  }
+  const res = await libraProposeOffer(ctx.baseUrl, ctx.credOpts, rc.caseId, pct, ctx.flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  const offer = res && res.offer;
+  const text = [
+    `已向对方提出和解：退还发起方 ${pct}%${offer ? `（提议 #${offer.id}）` : ''}。`,
+    '  对方接受即按此结案；拒绝则审理继续；裁决书出具前没有回应，提议随裁决书失效。',
+    '  同一时间只能有一个待回应的提议；想改比例，先 stelfield libra settle withdraw 撤回再重新提。',
+  ].join('\n');
+  return io.ok({ case_id: rc.caseId, offer: offer || null }, text);
+}
+
+/** The offer to act on: --offer <id>, else the pending one. Returns { offerId, pending } or { fail }. */
+async function resolveOffer(ctx, io, rc) {
+  const ec = await earlyCloseOf(ctx, rc.caseId, rc.caseView);
+  const pending = ec && ec.pending_offer;
+  if (ctx.flags.offer) return { offerId: ctx.flags.offer, pending: pending && String(pending.id) === String(ctx.flags.offer) ? pending : null };
+  if (!pending) return { fail: io.fail(4, 'offer_not_found', '现在没有待回应的和解提议。') };
+  return { offerId: pending.id, pending };
+}
+
+async function cmdSettleAccept(ctx, io) {
+  const rc = await resolveCase(ctx, io);
+  if (rc.fail !== undefined) return rc.fail;
+  const ro = await resolveOffer(ctx, io, rc);
+  if (ro.fail !== undefined) return ro.fail;
+  const pct = parsePct(ctx.flags.expectPct);
+  if (pct == null) {
+    const seen = ro.pending ? `（当前待回应的提议：退还发起方 ${ro.pending.refund_pct}%）` : '';
+    return io.fail(2, 'expect_pct_required',
+      `接受和解必须带 --expect-pct <你读到的比例>${seen}。确认比例后重新运行：stelfield libra settle accept --case ${rc.caseId} --expect-pct <比例>`);
+  }
+  const res = await libraAcceptOffer(ctx.baseUrl, ctx.credOpts, rc.caseId, ro.offerId, pct, ctx.flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  return io.ok({ case_id: rc.caseId, offer_id: ro.offerId, result: res }, closedText(res, `已接受和解（退还 ${pct}%），案件提前结案。`));
+}
+
+async function cmdSettleReject(ctx, io) {
+  const rc = await resolveCase(ctx, io);
+  if (rc.fail !== undefined) return rc.fail;
+  const ro = await resolveOffer(ctx, io, rc);
+  if (ro.fail !== undefined) return ro.fail;
+  const res = await libraRejectOffer(ctx.baseUrl, ctx.credOpts, rc.caseId, ro.offerId, ctx.flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  return io.ok({ case_id: rc.caseId, offer_id: ro.offerId, result: res }, '已拒绝和解提议，审理继续。');
+}
+
+async function cmdSettleWithdraw(ctx, io) {
+  const rc = await resolveCase(ctx, io);
+  if (rc.fail !== undefined) return rc.fail;
+  const ro = await resolveOffer(ctx, io, rc);
+  if (ro.fail !== undefined) return ro.fail;
+  const res = await libraWithdrawOffer(ctx.baseUrl, ctx.credOpts, rc.caseId, ro.offerId, ctx.flags.idempotencyKey || undefined, { fetchImpl: ctx.fetchImpl });
+  return io.ok({ case_id: rc.caseId, offer_id: ro.offerId, result: res }, '已撤回你提出的和解提议。');
+}
+
+const HANDLERS = {
+  'libra:quote': cmdQuote, 'libra:file': cmdFile, 'libra:status': cmdStatus, 'libra:statement': cmdStatement,
+  'libra:answer': cmdAnswer, 'libra:ruling': cmdRuling, 'libra:accept': cmdAccept,
+  'libra:review-quote': cmdReviewQuote, 'libra:review-file': cmdReviewFile,
+  // P19 early close
+  'libra:withdraw': cmdWithdraw, 'libra:concede': cmdConcede,
+  'libra:settle-propose': cmdSettlePropose, 'libra:settle-accept': cmdSettleAccept,
+  'libra:settle-reject': cmdSettleReject, 'libra:settle-withdraw': cmdSettleWithdraw,
+};
+
+// What the person has to do on the web, per command (used in the exit-5 notice).
+const HUMAN_WHAT = { 'libra:withdraw': '撤回裁决' };
+
+export function isLibraCommand(command) {
+  return Object.prototype.hasOwnProperty.call(HANDLERS, command);
+}
+
+/**
+ * Run one libra command. ctx: { command, flags, baseUrl, credOpts, fetchImpl, env, log, err }.
+ * Platform errors are mapped to the documented exit codes; upgrade-required errors are left to the caller.
+ */
+export async function runLibra(ctx) {
+  const io = makeIo(ctx);
+  try {
+    return await HANDLERS[ctx.command](ctx, io);
+  } catch (e) {
+    if (e && e.upgradeRequired) throw e;
+    const m = mapError(e);
+    if (m.human) {
+      const url = m.webUrl ? `${webBase(ctx)}${m.webUrl}` : null;
+      return humanRequired(ctx, HUMAN_WHAT[ctx.command] || '这个操作', url, { code: m.code });
+    }
+    return io.fail(m.exit, m.code, m.message);
+  }
+}