@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/bitable.js

@@ -0,0 +1,3040 @@
+// 多维表格：`bitable base|table|field|record|view|form`（契约 §2.1、§5）。
+//
+// 参数 → 服务端路径的对应全部是**常量**（没有一条由用户输入拼出来），
+// 所以"没有裸调面"这件事是可以逐行核对的。
+//
+// 本文件是 `cli/crates/xinhe-oa-cli/src/commands/bitable.rs`（含 `bitable/import_cmd.rs`、
+// `bitable/visibility.rs`）的 Node 移植。注释里凡是"为什么"的部分都照抄了 Rust 侧的现场结论——
+// 这个域几乎每条口径都是踩出来的，删掉理由就等于把坑重新埋回去。
+
+import { CliError, Kind, exactlyOne } from '../core/error.js';
+import { flagList, flagOn, flagValue } from '../core/args.js';
+import { filtersToAst, orderParam, parsePairs, parseSetPairs, valuesObject } from '../core/values.js';
+import { dataOf, idempotencyKey, readFileBytes } from '../core/runtime.js';
+import { multipartBody, requestSpec } from '../core/http.js';
+import { newIdempotencyKey } from '../core/util.js';
+import { progress, renderTable, verbose, warn } from '../core/output.js';
+import * as checkpoint from '../core/checkpoint.js';
+import * as imp from '../core/import.js';
+import { fileNameOf } from '../core/values.js';
+
+/** 单页读记录的条数上限（与服务端 `rows_limit_max`、`/me` 的公布值同源）。 */
+const MAX_PAGE_LIMIT = 1000;
+/** `--all` 并发取页的硬上限。 */
+const MAX_PAGE_WORKERS = 16;
+/** 一次 `--all` 最多翻到第几行（护栏，防止把服务端拖住）。 */
+const MAX_PAGING_OFFSET = 100_000;
+/** 视图取数（游标分页）一次 `--all` 最多翻几页（游标没有"第几行"这个概念）。 */
+const MAX_VIEW_PAGES = 200;
+/** 单批请求体的字节上限：服务端 `max_body_kb` 默认 1024KB，留 ~10% 余量。 */
+const MAX_BODY_BYTES = 900 * 1024;
+/** 并发发批的硬上限（超过这个数，客户端先于服务端成为瓶颈）。 */
+const MAX_WORKERS = 16;
+/** 同一批最多重投几次（429/5xx 之后重新排队）。 */
+const MAX_BATCH_ATTEMPTS = 5;
+
+/**
+ * `bitable` 六个子域的分发。
+ *
+ * **动作由 `args` 决定，不由规格条目名决定** —— 这一条与 Rust 逐字同源：
+ * Rust 那边 `BaseArgs` / `TableArgs` 这些结构体承载一整组动作，clap 只负责把旗标收进来，
+ * "这次到底是 --list 还是 --archive" 是 `BaseArgs::action()` 在**代码里**判的。
+ * Node 版的解析层同样会把 `bitable base --archive bs_1` 归到某一条规格条目上
+ * （条目名只说明"这是 base 这一组"），所以按条目名分发会在 `--archive` / `--visibility`
+ * 这些动作上悄悄走错分支。按 `args` 判既稳，也与 Rust 的组合约束一一对应。
+ */
+export async function handleBitable({ args, runtime, command }) {
+  const tokens = String(command?.name ?? '').split(' ');
+  const resource = tokens[1];
+  switch (resource) {
+    case 'base':
+      return runBase(runtime, args);
+    case 'table':
+      return runTable(runtime, args);
+    case 'field':
+      return runField(runtime, args);
+    case 'record':
+      return runRecord(runtime, args);
+    case 'view':
+      return runView(runtime, args);
+    case 'form':
+      return runForm(runtime, args);
+    default:
+      throw CliError.usage(`\`${command?.name ?? 'bitable'}\` 还没有实现`).withHint(
+        '跑 `xinhe-oa-cli schema bitable` 看这个域的命令面',
+      );
+  }
+}
+
+/** `bitable base` 的动作收口（逐条对应 Rust 的 `BaseArgs::action()`）。 */
+async function runBase(runtime, args) {
+  const vis = visibilityFlags(args);
+  // 组合约束在本地判定：参数拼错 = 退出码 2、不发请求。
+  if (flagOn(args, '--include-archived') && !flagOn(args, '--list')) {
+    throw CliError.usage('`--include-archived` 只对 `--list` 有意义').withHint(
+      '例：xinhe-oa-cli bitable base --list --include-archived --json',
+    );
+  }
+  const showState = visibilityShowState(args, vis);
+  if (showState.bareShow && vis.visibility === null) {
+    // 裸 `--show` 只用于 `--visibility <ID> --show`；进了 action 组就会与 `--visibility`
+    // 被判互斥（文件域 `file --show` 同一取舍），所以这三条在代码里判。
+    throw CliError.usage(
+      '裸 `--show` 只用于 `--visibility <BASE_ID> --show`；看详情请给 `--show <BASE_ID>`',
+    ).withHint('例：xinhe-oa-cli bitable base --show <ID> --json');
+  }
+  if (vis.visibility !== null && args['--show'] !== undefined && !showState.bareShow) {
+    throw CliError.usage(
+      '`--show <BASE_ID>` 与 `--visibility <BASE_ID>` 不能同时给：它们各自已经在指名对象',
+    ).withHint('例：xinhe-oa-cli bitable base --visibility <ID> --show --json');
+  }
+  if (vis.visibility !== null) {
+    validateVisibilityAction('bitable base', vis, showState.visShow);
+  }
+  if (vis.investorVisibility !== null && vis.investorSet === null) {
+    throw CliError.usage(
+      '`--investor-visibility <BASE_ID>` 还要给 `--investor-set open|closed`',
+    ).withHint('例：xinhe-oa-cli bitable base --investor-visibility <ID> --investor-set open --yes');
+  }
+  const picked = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--create', flagOn(args, '--create')],
+      ['--show', args['--show'] !== undefined && !showState.visShow],
+      ['--archive', vis.archive],
+      ['--visibility', vis.visibility !== null],
+      ['--share', vis.share !== null],
+      ['--acl-list', vis.aclList !== null],
+      ['--acl-revoke', vis.aclRevoke !== null],
+      ['--move', vis.move !== null],
+      ['--investor-visibility', vis.investorVisibility !== null],
+    ],
+    'bitable base',
+    '例：xinhe-oa-cli bitable base --list --json',
+  );
+  switch (picked) {
+    case '--list':
+      return baseList(runtime, args);
+    case '--create':
+      return baseCreate(runtime, args);
+    case '--show':
+      return baseShow(runtime, args);
+    case '--archive':
+      return baseArchive(runtime, args);
+    case '--visibility':
+      return showState.visShow
+        ? showVisibility(runtime, args, 'base', vis.visibility)
+        : setVisibility(runtime, args, 'base', vis.visibility, vis.set);
+    case '--share':
+      return share(runtime, args, 'base');
+    case '--acl-list':
+      return aclList(runtime, args, 'base');
+    case '--acl-revoke':
+      return aclRevoke(runtime, args, 'base');
+    case '--move':
+      return moveObject(runtime, args, 'base');
+    default:
+      return investorVisibility(runtime, args, 'base');
+  }
+}
+
+/** `bitable table` 的动作收口（逐条对应 Rust 的 `TableArgs::action()`）。 */
+async function runTable(runtime, args) {
+  const vis = visibilityFlags(args);
+  const appended = flagOn(args, '--append');
+  if (appended && !flagOn(args, '--import')) {
+    throw CliError.usage(
+      '`--append` 只对 `--import` 有意义（把数据追加到已存在的同 key/同表名表）',
+    ).withHint(
+      '例：xinhe-oa-cli bitable table --import --file 9月.csv --base <BASE_ID> --name 结算明细 --append',
+    );
+  }
+  if (flagOn(args, '--include-archived') && !flagOn(args, '--list')) {
+    throw CliError.usage('`--include-archived` 只对 `--list` 有意义').withHint(
+      '例：xinhe-oa-cli bitable table --list --base <BASE_ID> --include-archived --json',
+    );
+  }
+  const showState = visibilityShowState(args, vis);
+  if (showState.bareShow && vis.visibility === null) {
+    throw CliError.usage(
+      '裸 `--show` 只用于 `--visibility <TABLE_ID> --show`；看详情请给 `--show <TABLE_ID>`',
+    ).withHint('例：xinhe-oa-cli bitable table --show <ID> --json');
+  }
+  if (vis.visibility !== null && args['--show'] !== undefined && !showState.bareShow) {
+    throw CliError.usage(
+      '`--show <TABLE_ID>` 与 `--visibility <TABLE_ID>` 不能同时给：它们各自已经在指名对象',
+    ).withHint('例：xinhe-oa-cli bitable table --visibility <ID> --show --json');
+  }
+  if (vis.visibility !== null) {
+    validateVisibilityAction('bitable table', vis, showState.visShow);
+  }
+  if (vis.investorVisibility !== null && vis.investorSet === null) {
+    throw CliError.usage(
+      '`--investor-visibility <TABLE_ID>` 还要给 `--investor-set open|closed`',
+    ).withHint('例：xinhe-oa-cli bitable table --investor-visibility <ID> --investor-set open --yes');
+  }
+  const picked = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--create', flagOn(args, '--create')],
+      ['--show', args['--show'] !== undefined && !showState.visShow],
+      ['--archive', vis.archive],
+      ['--import', flagOn(args, '--import')],
+      ['--visibility', vis.visibility !== null],
+      ['--share', vis.share !== null],
+      ['--acl-list', vis.aclList !== null],
+      ['--acl-revoke', vis.aclRevoke !== null],
+      ['--move', vis.move !== null],
+      ['--investor-visibility', vis.investorVisibility !== null],
+    ],
+    'bitable table',
+    '例：xinhe-oa-cli bitable table --import --file 单据.csv --base-name 开叔企业 --name 公账流水',
+  );
+  switch (picked) {
+    case '--list':
+      return tableList(runtime, args);
+    case '--create':
+      return tableCreate(runtime, args);
+    case '--show':
+      return tableShow(runtime, args);
+    case '--archive':
+      return tableArchive(runtime, args);
+    case '--import':
+      return importTable(runtime, args);
+    case '--visibility':
+      return showState.visShow
+        ? showVisibility(runtime, args, 'table', vis.visibility)
+        : setVisibility(runtime, args, 'table', vis.visibility, vis.set);
+    case '--share':
+      return share(runtime, args, 'table');
+    case '--acl-list':
+      return aclList(runtime, args, 'table');
+    case '--acl-revoke':
+      return aclRevoke(runtime, args, 'table');
+    case '--move':
+      return moveObject(runtime, args, 'table');
+    default:
+      return investorVisibility(runtime, args, 'table');
+  }
+}
+
+/** `bitable field` 的动作收口（逐条对应 Rust 的 `FieldArgs::action()`）。 */
+async function runField(runtime, args) {
+  const picked = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--create', flagOn(args, '--create')],
+      ['--update', args['--update'] !== undefined],
+      ['--show', args['--show'] !== undefined],
+    ],
+    'bitable field',
+    '例：xinhe-oa-cli bitable field --create --table <table_id> --name 金额 --type currency',
+  );
+  if (picked === '--list') return fieldList(runtime, args);
+  if (picked === '--create') return fieldCreate(runtime, args);
+  if (picked === '--update') return fieldUpdate(runtime, args);
+  return fieldShow(runtime, args);
+}
+
+/** `bitable record` 的动作收口（逐条对应 Rust 的 `RecordArgs::action()`）。 */
+async function runRecord(runtime, args) {
+  const picked = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--create', flagOn(args, '--create')],
+      ['--update', args['--update'] !== undefined],
+      ['--delete', args['--delete'] !== undefined],
+      ['--show', args['--show'] !== undefined],
+    ],
+    'bitable record',
+    '例：xinhe-oa-cli bitable record --list --table <table_id> --json',
+  );
+  // ORG-003：`--dept` 只属于取数动作（表取数的 GET 查询参数是 `dept`）。
+  if (args['--dept'] !== undefined && picked !== '--list') {
+    throw CliError.usage(`\`bitable record ${picked}\` 不接受 --dept`).withHint(
+      '--dept 只用于：xinhe-oa-cli bitable record --list --table <TABLE_ID> --dept <DEPT_ID>',
+    );
+  }
+  if (picked === '--list') return recordList(runtime, args);
+  if (picked === '--create') return recordCreate(runtime, args);
+  if (picked === '--update') return recordUpdate(runtime, args);
+  if (picked === '--delete') return recordDelete(runtime, args);
+  return recordShow(runtime, args);
+}
+
+/** `bitable view` 的动作收口（逐条对应 Rust 的 `ViewArgs::action()`）。 */
+async function runView(runtime, args) {
+  const picked = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--create', flagOn(args, '--create')],
+      ['--query', flagOn(args, '--query')],
+      ['--aggregate', flagOn(args, '--aggregate')],
+      ['--show', args['--show'] !== undefined],
+    ],
+    'bitable view',
+    '例：xinhe-oa-cli bitable view --query --view <view_id> --json',
+  );
+  if (picked === '--list') return viewList(runtime, args);
+  if (picked === '--create') return viewCreate(runtime, args);
+  if (picked === '--query') return viewQuery(runtime, args);
+  if (picked === '--aggregate') return viewAggregate(runtime, args);
+  return viewShow(runtime, args);
+}
+
+/** `bitable form` 的动作收口（逐条对应 Rust 的 `FormArgs::action()`）。 */
+async function runForm(runtime, args) {
+  const picked = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--create', flagOn(args, '--create')],
+      ['--submit', flagOn(args, '--submit')],
+      ['--show', args['--show'] !== undefined],
+    ],
+    'bitable form',
+    '例：xinhe-oa-cli bitable form --submit --form <form_id> --set 金额=1200',
+  );
+  if (picked === '--list') return formList(runtime, args);
+  if (picked === '--create') return formCreate(runtime, args);
+  if (picked === '--submit') return formSubmit(runtime, args);
+  return formShow(runtime, args);
+}
+
+/** `ObjectVisibilityArgs` 那组旗标（库与表共用一份）。 */
+function visibilityFlags(args) {
+  return {
+    visibility: optionalId(args, '--visibility'),
+    set: flagValue(args, '--set'),
+    share: optionalId(args, '--share'),
+    aclList: optionalId(args, '--acl-list'),
+    aclRevoke: optionalId(args, '--acl-revoke'),
+    move: optionalId(args, '--move'),
+    investorVisibility: optionalId(args, '--investor-visibility'),
+    investorSet: flagValue(args, '--investor-set'),
+    archive: args['--archive'] !== undefined,
+  };
+}
+
+/** 裸 `--show`（无值）与"带 ID 的 --show"是两件事：前者是 `--visibility` 的读形态。 */
+function visibilityShowState(args, vis) {
+  const showText = flagValue(args, '--show');
+  const bareShow = args['--show'] !== undefined && (showText === null || showText.trim().length === 0);
+  return { bareShow, visShow: vis.visibility !== null && bareShow };
+}
+
+/** `--visibility <ID>` 必须再给一个动作：`--show`（读）或 `--set <档位>`（写），互斥。 */
+function validateVisibilityAction(domain, vis, showGiven) {
+  if (showGiven === (vis.set !== null)) {
+    throw CliError.usage(
+      `\`${domain} --visibility <ID>\` 还要给 \`--show\`（读）或 \`--set private|dept|internal\`（写）`,
+    ).withHint(`例：xinhe-oa-cli ${domain} --visibility <ID> --show --json`);
+  }
+  if (vis.set !== null) {
+    const mode = String(vis.set).trim().toLowerCase();
+    if (!['private', 'dept', 'internal'].includes(mode)) {
+      throw CliError.usage(
+        `\`--set\` 只能是 private | dept | internal（收到 ${JSON.stringify(mode)}）；                     \`public\` 本期没有对外入口`,
+      ).withHint(`例：xinhe-oa-cli ${domain} --visibility <ID> --set internal --yes`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 参数小工具
+// ---------------------------------------------------------------------------
+/** 取一个"必须给的 ID 位置"旗标（`--archive` / `--show` / `--visibility` …）。 */
+function requireId(args, flag, what) {
+  const value = flagValue(args, flag);
+  if (value === null || value.trim().length === 0) {
+    throw CliError.usage(`\`${what} ${flag}\` 需要 <ID>`).withHint(
+      `例：xinhe-oa-cli ${what} ${flag} <ID> --json`,
+    );
+  }
+  return value.trim();
+}
+
+/** 取一个必填的文本旗标。 */
+function requireText(args, flag, what, hint) {
+  const value = flagValue(args, flag);
+  if (value === null) {
+    const error = CliError.usage(`\`${what}\` 需要 ${flag}`);
+    throw hint ? error.withHint(hint) : error;
+  }
+  return value;
+}
+
+/**
+ * 整数旗标。
+ *
+ * `min` / `max` 是**本地**约束（契约 §2「参数即约束」）：越界在发请求之前判死，
+ * 而不是把服务端的 422 原样丢给调用方。
+ */
+function intFlag(args, flag, { min = null, max = null, fallback = null } = {}) {
+  const raw = flagValue(args, flag);
+  if (raw === null) return fallback;
+  const text = String(raw).trim();
+  if (text.length === 0) {
+    throw CliError.usage(`\`${flag}\` 需要一个取值`).withHint(`例：${flag} 50`);
+  }
+  if (!/^[+-]?\d+$/.test(text)) {
+    throw CliError.usage(`\`${flag}\` 要一个整数，收到 ${JSON.stringify(raw)}`);
+  }
+  const value = Number.parseInt(text, 10);
+  if (min !== null && value < min) throw CliError.usage(`\`${flag}\` 不能小于 ${min}（收到 ${value}）`);
+  if (max !== null && value > max) throw CliError.usage(`\`${flag}\` 不能大于 ${max}（收到 ${value}）`);
+  return value;
+}
+
+/** 取 `<ID>` 这类旗标；没给就是 null（不报错）。 */
+function optionalId(args, flag) {
+  const value = flagValue(args, flag);
+  if (value === null) return null;
+  const trimmed = value.trim();
+  return trimmed.length === 0 ? null : trimmed;
+}
+
+/** 服务端把 refresh 绑在设备上；`GET /me` 是"我属于哪家企业"的唯一事实源。 */
+async function resolveTenant(runtime, requested) {
+  const value = requested === null || requested === undefined ? '' : String(requested).trim();
+  if (value.length > 0) return value;
+  const response = await runtime.sendAuthed('GET', '/me', requestSpec());
+  const data = dataOf(response);
+  const tenants = Array.isArray(data?.scope?.tenants) ? data.scope.tenants : [];
+  if (tenants.length === 1) {
+    const id = tenants[0]?.id;
+    return typeof id === 'string' ? id : null;
+  }
+  if (tenants.length === 0) return null;
+  throw CliError.usage('你有多个可见企业，请用 --tenant <TENANT_ID> 指明').withDetails({
+    visible_tenants: tenants,
+    hint: 'xinhe-oa-cli tenant --list',
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Base
+// ---------------------------------------------------------------------------
+async function baseList(runtime, args) {
+  // 列表**不需要**"唯一可见企业"：不点名就列全部可见企业的库（服务端按权限裁剪）。
+  // 只有**建**东西时才必须落在某一家企业里（那时才走 resolveTenant）。
+  const query = [];
+  const tenant = flagValue(args, '--tenant');
+  if (tenant !== null && tenant.trim().length > 0) query.push(['tenant', tenant.trim()]);
+  query.push(['limit', String(intFlag(args, '--limit', { min: 0, fallback: 100 }))]);
+  const includeArchived = flagOn(args, '--include-archived');
+  // 归档的库默认不出现（服务端 include_archived 默认 false）；要看就显式要。
+  if (includeArchived) query.push(['include_archived', 'true']);
+  const response = await runtime.sendAuthed('GET', '/bases', requestSpec({ query }));
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    bases: Array.isArray(data?.bases) ? data.bases : [],
+    total: data?.total ?? null,
+    include_archived: includeArchived,
+    next_step: '看某个库里的表：xinhe-oa-cli bitable table --list --base <BASE_ID> --json',
+  });
+}
+
+async function baseCreate(runtime, args) {
+  const name = requireText(args, '--name', 'bitable base --create', '例：xinhe-oa-cli bitable base --create --name 开叔企业 --tenant kashu');
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'));
+  if (tenant === null) {
+    throw CliError.usage('建库必须指明企业').withHint(
+      '加 --tenant <TENANT_ID>；用 `xinhe-oa-cli tenant --list` 看有哪些企业',
+    );
+  }
+  // 机器名：不给就按显示名推导（中文 → 报错让人显式给，绝不静默造一个 t_1727…）。
+  const key = flagValue(args, '--key') ?? deriveKey(name);
+  const body = {
+    tenant,
+    key,
+    name,
+    description: flagValue(args, '--description'),
+  };
+  const spec = requestSpec({ body });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', '/bases', spec);
+  const response = await runtime.sendAuthed('POST', '/bases', spec);
+  const data = dataOf(response);
+  const baseId = typeof data?.id === 'string' ? data.id : '';
+  runtime.finishFrom(response, {
+    base: data,
+    next_step: `建表：xinhe-oa-cli bitable table --create --base ${baseId} --name <表名>`,
+  });
+}
+
+async function baseShow(runtime, args) {
+  const baseId = requireId(args, '--show', 'bitable base');
+  const response = await runtime.sendAuthed('GET', `/bases/${baseId}`, requestSpec());
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/**
+ * `bitable base --archive`：走服务端 `PATCH /bases/{id}` 的 `status="archived"`。
+ *
+ * 服务端**没有**硬删端点（只有归档）：归档后其下所有表不再可写、历史仍可读、
+ * 默认列表里不再出现 —— 这就是"把探路建的垃圾库清掉"在 CLI 时代的正解。
+ */
+async function baseArchive(runtime, args) {
+  const baseId = requireId(args, '--archive', 'bitable base');
+  runtime.requireYes(
+    'bitable base --archive（归档整个库：其下所有表不再可写）',
+    `xinhe-oa-cli bitable base --archive ${baseId}`,
+  );
+  const spec = archiveSpec();
+  if (runtime.dryRun) return runtime.dryRunReport('PATCH', `/bases/${baseId}`, spec);
+  const response = await runtime.sendAuthed('PATCH', `/bases/${baseId}`, spec);
+  const data = dataOf(response);
+  runtime.finishFrom(
+    response,
+    archiveOutput('base', data, {
+      next_step:
+        '确认它不在默认列表里了：xinhe-oa-cli bitable base --list --json（要看归档的加 --include-archived）',
+    }),
+  );
+}
+
+/**
+ * 从显示名推一个合法的数据 key（`^[a-z][a-z0-9_]{0,63}$`）。
+ *
+ * 中文名/数字开头**直接报错**：机器名创建后不可变，静默造一个 `t_1727…`
+ * 客户第二天就认不出来是什么了。
+ */
+export function deriveKey(name) {
+  let key = '';
+  for (const ch of String(name ?? '')) {
+    if (/[A-Za-z0-9]/.test(ch)) key += ch.toLowerCase();
+    else if (ch.charCodeAt(0) < 128) key += '_';
+  }
+  while (key.includes('__')) key = key.split('__').join('_');
+  key = key.replace(/^_+/, '').replace(/_+$/, '');
+  if (key.length > 48) key = key.slice(0, 48);
+  if (key.length === 0 || !/^[a-z]/.test(key)) {
+    throw CliError.usage(
+      `显示名 ${JSON.stringify(name)} 推不出合法的机器名（key 只能是小写字母开头 + 字母/数字/下划线）`,
+    ).withHint('显式给一个：--key kashu（机器名创建后不可变，显示名随时可改）');
+  }
+  return key;
+}
+
+/** 推不出 key 时的兜底（服务端只要求形状合法，形状之外没有语义）。 */
+function fallbackKey(prefix) {
+  return `${prefix}${newIdempotencyKey('x').split(':')[1].slice(0, 8)}`;
+}
+
+// ---------------------------------------------------------------------------
+// Table
+// ---------------------------------------------------------------------------
+async function tableList(runtime, args) {
+  const baseId = requireText(args, '--base', 'bitable table --list', '先看有哪些库：xinhe-oa-cli bitable base --list --json');
+  const includeArchived = flagOn(args, '--include-archived');
+  const query = [];
+  // 归档的表默认不出现（服务端 include_archived 默认 false）。
+  if (includeArchived) query.push(['include_archived', 'true']);
+  const response = await runtime.sendAuthed(
+    'GET',
+    `/bases/${baseId}/tables`,
+    requestSpec({ query }),
+  );
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    tables: Array.isArray(data?.tables) ? data.tables : [],
+    total: data?.total ?? null,
+    include_archived: includeArchived,
+    next_step: '看表里的字段：xinhe-oa-cli bitable field --list --table <TABLE_ID> --json',
+  });
+}
+
+async function tableCreate(runtime, args) {
+  const baseId = requireText(args, '--base', 'bitable table --create', '先看有哪些库：xinhe-oa-cli bitable base --list --json');
+  const name = requireText(args, '--name', 'bitable table --create');
+  const key = optionalId(args, '--key') ?? safeDeriveKey(name, 't');
+  const body = {
+    key,
+    name,
+    description: flagValue(args, '--description'),
+    semantic_kind: flagValue(args, '--semantic-kind'),
+  };
+  const spec = requestSpec({ body });
+  const path = `/bases/${baseId}/tables`;
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  const data = dataOf(response);
+  const tableId = typeof data?.id === 'string' ? data.id : '';
+  runtime.finishFrom(response, {
+    table: data,
+    next_step: `建字段：xinhe-oa-cli bitable field --create --table ${tableId} --name 金额 --type currency`,
+  });
+}
+
+function safeDeriveKey(name, prefix) {
+  try {
+    return deriveKey(name);
+  } catch {
+    return fallbackKey(prefix);
+  }
+}
+
+async function tableShow(runtime, args) {
+  const tableId = requireId(args, '--show', 'bitable table');
+  const response = await runtime.sendAuthed('GET', `/tables/${tableId}`, requestSpec());
+  runtime.finishFrom(response, dataOf(response));
+}
+
+async function tableArchive(runtime, args) {
+  const tableId = requireId(args, '--archive', 'bitable table');
+  runtime.requireYes(
+    'bitable table --archive（归档这张表：不再可写、默认列表不再出现）',
+    `xinhe-oa-cli bitable table --archive ${tableId}`,
+  );
+  // 归档前先看一眼它属于哪个 base：归档完的下一步就是"回那个库里确认它不在了"。
+  let baseId = optionalId(args, '--base');
+  if (baseId === null) {
+    try {
+      const response = await runtime.sendAuthed('GET', `/tables/${tableId}`, requestSpec());
+      const data = dataOf(response);
+      baseId = typeof data?.base_id === 'string' ? data.base_id : null;
+    } catch (err) {
+      // 读不到详情不该挡住归档本身（服务端仍是权威）。
+      warn(`归档前读表详情失败（${err.code ?? 'cli.error'}：${err.message}），继续归档`);
+      baseId = null;
+    }
+  }
+  const spec = archiveSpec();
+  if (runtime.dryRun) return runtime.dryRunReport('PATCH', `/tables/${tableId}`, spec);
+  const response = await runtime.sendAuthed('PATCH', `/tables/${tableId}`, spec);
+  const data = dataOf(response);
+  const nextStep =
+    baseId !== null
+      ? `确认它不在默认列表里了：xinhe-oa-cli bitable table --list --base ${baseId} --json（要看归档的加 --include-archived）`
+      : '确认它不在默认列表里了：xinhe-oa-cli bitable table --list --base <BASE_ID> --json（要看归档的加 --include-archived）';
+  runtime.finishFrom(response, archiveOutput('table', data, { next_step: nextStep }));
+}
+
+/** 归档请求体：服务端只认 `status`（`active` / `archived`）。 */
+function archiveSpec() {
+  return requestSpec({ body: { status: 'archived' } });
+}
+
+/** 归档结果：人类可读面要能一眼看到"哪一张、现在什么状态"。 */
+function archiveOutput(kind, data, extra) {
+  const out = {
+    archived: true,
+    [kind]: data,
+    id: data?.id ?? null,
+    name: data?.name ?? null,
+    status: data?.status ?? 'archived',
+    note: '归档 = 不再接受写入、历史仍可读、默认列表里不再出现；服务端没有硬删端点，归档就是 CLI 的删表动作',
+  };
+  for (const [key, value] of Object.entries(extra ?? {})) out[key] = value;
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Field
+// ---------------------------------------------------------------------------
+async function fieldList(runtime, args) {
+  const tableId = requireText(args, '--table', 'bitable field --list');
+  const response = await runtime.sendAuthed('GET', `/tables/${tableId}/fields`, requestSpec());
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    fields: Array.isArray(data?.fields) ? data.fields : [],
+    total: data?.total ?? null,
+    note: '写记录时 `--set` 的键可以是 semantic_key，也可以是 field_id',
+  });
+}
+
+async function fieldCreate(runtime, args) {
+  const tableId = requireText(args, '--table', 'bitable field --create');
+  const name = requireText(args, '--name', 'bitable field --create');
+  const fieldType = requireText(
+    args,
+    '--type',
+    'bitable field --create',
+    `类型只能是：${imp.FIELD_TYPES.join(' / ')}`,
+  );
+  if (!imp.FIELD_TYPES.includes(fieldType)) {
+    throw CliError.usage(`不支持的字段类型 ${JSON.stringify(fieldType)}`).withHint(
+      `类型只能是：${imp.FIELD_TYPES.join(' / ')}`,
+    );
+  }
+  const semanticKey = optionalId(args, '--semantic-key') ?? safeDeriveKey(name, 'f');
+  const body = {
+    semantic_key: semanticKey,
+    name,
+    type: fieldType,
+  };
+  const description = flagValue(args, '--description');
+  if (description !== null) body.description = description;
+  if (flagOn(args, '--required')) body.is_required = true;
+  if (flagOn(args, '--sensitive')) body.is_sensitive = true;
+  const options = flagValue(args, '--options');
+  if (options !== null) {
+    const items = options
+      .split(',')
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0);
+    if (items.length === 0) {
+      throw CliError.usage('--options 里没有有效选项').withHint('例：--options 待审,已审,已驳回');
+    }
+    if (fieldType !== 'single_select' && fieldType !== 'multi_select') {
+      throw CliError.usage(
+        `--options 只对 single_select / multi_select 有意义（当前 --type ${fieldType}）`,
+      );
+    }
+    body.options = items;
+  }
+  const spec = requestSpec({ body });
+  const path = `/tables/${tableId}/fields`;
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    field: data,
+    note: 'semantic_key 与 type 创建后不可变；要改类型 = 新建字段 + 回填',
+  });
+}
+
+async function fieldUpdate(runtime, args) {
+  const fieldId = requireId(args, '--update', 'bitable field');
+  const body = {};
+  const name = flagValue(args, '--name');
+  if (name !== null) body.name = name;
+  const description = flagValue(args, '--description');
+  if (description !== null) body.description = description;
+  if (flagOn(args, '--required')) body.is_required = true;
+  if (flagOn(args, '--archive')) body.status = 'archived';
+  const options = flagValue(args, '--options');
+  if (options !== null) {
+    body.options = options
+      .split(',')
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0);
+  }
+  if (Object.keys(body).length === 0) {
+    throw CliError.usage('`bitable field --update` 至少要给一个要改的东西').withHint(
+      '例：--name 金额（含税）| --options a,b | --archive',
+    );
+  }
+  if (flagValue(args, '--type') !== null || flagValue(args, '--semantic-key') !== null) {
+    throw CliError.usage('semantic_key 与 type 创建后不可变，不能改').withHint(
+      '要改类型就新建一个字段再回填数据（服务端也是这个口径）',
+    );
+  }
+  const spec = requestSpec({ body });
+  const path = `/fields/${fieldId}`;
+  if (runtime.dryRun) return runtime.dryRunReport('PATCH', path, spec);
+  const response = await runtime.sendAuthed('PATCH', path, spec);
+  runtime.finishFrom(response, { field: dataOf(response) });
+}
+
+async function fieldShow(_runtime, args) {
+  // 服务端没有 `GET /fields/{id}`：字段详情从所在表的字段列表里挑。
+  const fieldId = requireId(args, '--show', 'bitable field');
+  throw CliError.usage('`bitable field --show` 需要知道字段属于哪张表').withHint(
+    `用 xinhe-oa-cli bitable field --list --table <TABLE_ID> --json，再按 id 找 ${fieldId}`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Record —— 取数（表取数 = limit/offset；视图 = 游标）
+// ---------------------------------------------------------------------------
+async function recordList(runtime, args) {
+  const tableId = requireText(args, '--table', 'bitable record --list');
+  const viewId = optionalId(args, '--view');
+  const dept = optionalId(args, '--dept');
+  const offsetRaw = flagValue(args, '--offset');
+  const offset = offsetRaw === null ? null : intFlag(args, '--offset', { min: 0 });
+  const limit = intFlag(args, '--limit', { fallback: 50 });
+  const all = flagOn(args, '--all');
+
+  // 带 `--view` 就走视图取数（服务端会套用视图的过滤/排序/列）。
+  if (viewId !== null) {
+    if (dept !== null) {
+      // `--dept` 是 `GET /tables/{id}/records` 上的查询参数；视图取数是另一个入口
+      // （`POST /views/{id}/query`，按视图自己的过滤走）。静默忽略会让调用方
+      // 以为"收窄了"，实际没窄 —— 那正是 ORG-003 要防的事，所以这里判死。
+      throw CliError.usage(
+        '`--dept` 只用于表取数（`bitable record --list --table <TABLE_ID>`）',
+      ).withHint(
+        `视图取数请把部门条件写进视图过滤：xinhe-oa-cli bitable view --query --view ${viewId} --filter <字段>:eq:<值>`,
+      );
+    }
+    if (offset !== null) {
+      // 视图取数是**游标**分页（回 `next_cursor`），服务端根本没有 offset 这个参数。
+      // 与其让 `--offset` 被静默忽略（调用方以为翻页了，实际每次都是第一页），
+      // 不如在这里说清楚续页该用哪个参数。
+      throw CliError.usage(
+        '`--offset` 只用于 `bitable record --list --table`（表取数是 limit/offset 分页）',
+      ).withHint(
+        '视图取数是游标分页：续页用 `xinhe-oa-cli bitable view --query --view <VIEW_ID> --cursor <上一页的 next_cursor>`',
+      );
+    }
+    return recordListViaView(runtime, viewId, { limit, all, filters: flagList(args, '--filter') });
+  }
+
+  // 服务端 `GET /tables/{id}/records` 的 limit 上界是 1000。超了服务端回
+  // `request.invalid` —— 那个 422 指不到参数名；契约 §2「参数即约束」要求在这里本地
+  // 判成用法错误（退出码 2、不发请求）。
+  if (limit < 1 || limit > MAX_PAGE_LIMIT) {
+    throw CliError.usage(
+      `--limit 必须在 1..=${MAX_PAGE_LIMIT}（服务端上限 ${MAX_PAGE_LIMIT}），收到 ${limit}`,
+    ).withHint(
+      `翻全表用 --all（每页 ${MAX_PAGE_LIMIT} 自动翻，可用 --workers 并发取页）；只取一页用 --limit N --offset N`,
+    );
+  }
+
+  const ast = filtersToAst(flagList(args, '--filter'));
+  if (ast !== null && !all) {
+    // 服务端的 `GET /tables/{id}/records` 不接受任意过滤条件（只有 order/limit）；
+    // 有过滤就翻页在**客户端**筛 —— 这正是"业务计算在客户端"的口径。
+    verbose(runtime.verbose, '服务端记录列表不支持过滤条件：改在客户端筛选（--all 会翻完各页）');
+  }
+  if (ast !== null && offset !== null) {
+    // 过滤在客户端做，而 offset 是**服务端结果里**的位置：两者叠加时下一页要看
+    // `next_offset`（服务端位置），不能拿"这一页返回了几条"去推。
+    verbose(
+      runtime.verbose,
+      '过滤在客户端做：--offset 指服务端（过滤前）的位置，这一页过滤后可能不足 --limit 条；续页看 next_offset',
+    );
+  }
+
+  const startOffset = offset ?? 0;
+  const workers = clamp(intFlag(args, '--workers', { fallback: 1 }), 1, MAX_PAGE_WORKERS);
+  const store = optionalId(args, '--store');
+  // 表取数用 `limit/offset` 翻页 —— 那就**必须**用一个全序排序，否则页边界会飘。
+  const order = recordOrderParam(flagValue(args, '--order'));
+  const collected = [];
+  let currentOffset = startOffset;
+  let pageLen = 0;
+  let fetched = 0;
+  let total = null;
+  let reachedEnd = false;
+  const requestIds = [];
+  let lastResponse = null;
+
+  const pageQuery = (at) => recordPageQuery({ limit, order, store, dept }, at);
+
+  // 第一页永远串行：既拿 `total`（后面并发翻页要用它算页数），也顺带确认
+  // "这条路走得通"——第一页就 4xx 时不该先并发开一堆注定失败的请求。
+  {
+    const response = await runtime.sendAuthed(
+      'GET',
+      `/tables/${tableId}/records`,
+      requestSpec({ query: pageQuery(currentOffset) }),
+    );
+    if (response.request_id) requestIds.push(response.request_id);
+    const data = dataOf(response);
+    const page = pageRecords(data);
+    total = data?.total ?? total;
+    pageLen = page.length;
+    fetched += pageLen;
+    collected.push(...page);
+    lastResponse = response;
+    // 不带 `--all`（只取一页）或第一页就没取满（已经到底了）。
+    reachedEnd = all && pageLen < limit;
+  }
+
+  if (all && !reachedEnd) {
+    const knownTotal = typeof total === 'number' && Number.isInteger(total) ? total : null;
+    // 并发翻页的**前提**是知道总行数（不然不知道要取几页，只能一页页问到空为止）。
+    // 有 total 时页与页彼此独立，一次发出去比串行快一个量级。
+    if (workers > 1 && knownTotal !== null && knownTotal > startOffset + pageLen) {
+      const offsets = [];
+      let next = startOffset + limit;
+      while (next < knownTotal) {
+        if (next > MAX_PAGING_OFFSET) break;
+        offsets.push(next);
+        next += limit;
+      }
+      if (offsets.length > 0) {
+        verbose(runtime.verbose, `--all 并发取页：${offsets.length} 页 / 并发 ${workers}`);
+        // 只有"这批页确实盖到了 total"才算翻到底；被 10 万条护栏截断时不能
+        // 对外声称"整表"，完整性自检也就不该下结论。
+        const last = offsets[offsets.length - 1];
+        const coveredToEnd = last + limit >= knownTotal;
+        const pages = await fetchRecordPages(runtime, tableId, pageQuery, offsets, workers);
+        // 已按 offset 排好序：拼接结果与串行翻页逐行一致。
+        for (const response of pages) {
+          if (response.request_id) requestIds.push(response.request_id);
+          const data = dataOf(response);
+          const page = pageRecords(data);
+          pageLen = page.length;
+          fetched += pageLen;
+          collected.push(...page);
+          total = data?.total ?? total;
+          lastResponse = response;
+        }
+        reachedEnd = coveredToEnd;
+      }
+    } else {
+      for (;;) {
+        currentOffset += limit;
+        if (currentOffset > MAX_PAGING_OFFSET) {
+          // 护栏只挡"一次翻完"，不挡续取：这里的 offset 就是下一页的入口
+          // （输出里的 next_offset 与它一致，has_more 仍是 true）。
+          warn(`翻页超过 10 万条，停下（避免把服务端拖住）；要接着取：--offset ${currentOffset}`);
+          break;
+        }
+        const response = await runtime.sendAuthed(
+          'GET',
+          `/tables/${tableId}/records`,
+          requestSpec({ query: pageQuery(currentOffset) }),
+        );
+        if (response.request_id) requestIds.push(response.request_id);
+        const data = dataOf(response);
+        const page = pageRecords(data);
+        total = data?.total ?? total;
+        pageLen = page.length;
+        fetched += pageLen;
+        collected.push(...page);
+        lastResponse = response;
+        if (pageLen < limit) {
+          reachedEnd = true;
+          break;
+        }
+      }
+    }
+  }
+
+  // 完整性自检：`--all` 号称"整表"，那就得真的是整表。
+  //
+  // 这一条是现场复测逼出来的：`--all --limit 50` 翻 910 行，返回 910 条里只有
+  // 683 个唯一值（227 行重复、227 行没取到），**还不报错** —— 调用方拿到一个
+  // 看着完整的残缺结果。服务端已经补了稳定排序，但"服务端排序不稳定"
+  // （老部署）与"翻页期间表被写过"（页边界错位）都可能再犯，
+  // 所以这里在客户端兜一道：**宁可报错，也不静默交半份数据**。
+  const integrity = pagingIntegrity(collected, total, startOffset, reachedEnd);
+  const failure = integrityError(integrity, tableId, order, limit);
+  if (failure !== null) throw failure;
+
+  // 客户端过滤
+  let filtered = collected;
+  if (ast !== null) {
+    const before = collected.length;
+    filtered = collected.filter((record) => recordMatches(record, ast));
+    verbose(runtime.verbose, `客户端过滤：${before} → ${filtered.length} 条`);
+  }
+
+  const count = filtered.length;
+  const [nextOffset, hasMore] = pagingState(startOffset, fetched, pageLen, limit, total);
+  const out = {
+    records: filtered,
+    total,
+    count,
+    limit,
+    // 本页第一条在服务端结果里的位置（= 调用方给的 `--offset`，不传是 0）。
+    offset: startOffset,
+    // **实际发出去的**排序（CLI 总会补一个唯一的 `id` 打破并列）。
+    order,
+    // 服务端实际取回的行数（**客户端过滤之前**；`--all` 时是所有页之和）。
+    fetched,
+    unique: integrity.unique,
+    consistent: integrity.consistent,
+    has_more: hasMore,
+    next_offset: hasMore ? nextOffset : null,
+    filtered_by_client: ast !== null,
+    request_ids: requestIds,
+    next_step: recordNextStep(tableId, limit, hasMore ? nextOffset : null),
+  };
+  if (lastResponse !== null) runtime.finishFrom(lastResponse, out);
+  else runtime.finish(out);
+}
+
+/** 表取数（`limit/offset` 分页）**实际发出去**的 `order`。 */
+function recordOrderParam(raw) {
+  const trimmed = raw === null || raw === undefined ? '' : String(raw).trim();
+  // 不给 `--order`（或给了空串/只有空白）= 服务端的默认口径：最新在前。
+  const normalized = trimmed.length > 0 ? orderParam(trimmed) : 'created_at:desc';
+  const pieces = normalized.split(',');
+  if (pieces.some((piece) => piece.split(':')[0].trim() === 'id')) return normalized;
+  // 打破键的方向跟随最后一个键：`created_at:desc` → 并列段里新的在前；
+  // `created_at:asc` → 并列段里旧的在前。方向本身不影响正确性（只要是全序），
+  // 跟着走只是让"同一批导入的 200 行"在两种排序下都保持插入顺序。
+  const last = pieces[pieces.length - 1];
+  const colon = last.lastIndexOf(':');
+  const direction = colon > 0 ? last.slice(colon + 1).trim().toLowerCase() : '';
+  return `${normalized},id:${direction === 'asc' ? 'asc' : 'desc'}`;
+}
+
+/** 记录列表的查询参数（串行与并发共用同一段，避免两条路径漂移）。 */
+function recordPageQuery({ limit, order, store, dept }, offset) {
+  const query = [
+    ['limit', String(limit)],
+    ['offset', String(offset)],
+    // 永远显式带上 order（以唯一的 `id` 收尾的全序）：老服务端的默认排序只有
+    // `created_at DESC`、并列段顺序不保证 —— 靠客户端把 `id` 补上才不重不漏。
+    ['order', order],
+  ];
+  if (store !== null && store !== undefined) query.push(['store_id', store]);
+  // ORG-003：部门过滤（只收窄）。不传时这一段什么都不发 ——
+  // 授权自带的部门档位由服务端夹着，CLI 不参与放宽。
+  if (dept !== null && dept !== undefined) query.push(['dept', dept]);
+  return query;
+}
+
+/**
+ * 并发取多页（`--all --workers N`）：页与页彼此独立，一次发一批。
+ *
+ * 并发前先取一次凭据，**续期不在并发里做**（refresh 是一次性令牌，
+ * 并发刷新会互相吊销）。同一波里按 offset 排序后再拼接：并发返回顺序不定，
+ * 而 `--all` 的结果必须与串行翻页**逐行一致**。
+ */
+async function fetchRecordPages(runtime, tableId, pageQuery, offsets, workers) {
+  await runtime.ensureFreshToken();
+  const out = [];
+  const queue = [...offsets];
+  while (queue.length > 0) {
+    const take = Math.min(workers, queue.length);
+    const wave = queue.splice(0, take);
+    const results = await Promise.all(
+      wave.map(async (offset) => {
+        const response = await runtime.sendAuthed(
+          'GET',
+          `/tables/${tableId}/records`,
+          requestSpec({ query: pageQuery(offset) }),
+        );
+        return { offset, response };
+      }),
+    );
+    results.sort((left, right) => left.offset - right.offset);
+    for (const item of results) out.push(item.response);
+  }
+  return out;
+}
+
+/** 响应里的行数组：**缺键或类型不对 = 契约错误**，绝不静默当空数组。 */
+function contractError(data, expected, what) {
+  const keys = data && typeof data === 'object' && !Array.isArray(data) ? Object.keys(data).sort() : [];
+  const expectedText = expected.map((key) => `\`${key}\``).join(' 或 ');
+  return new CliError(
+    Kind.Server,
+    'cli.contract',
+    `${what} 的响应里没有 ${expectedText} 数组 —— 客户端与服务端的响应形状对不上`,
+  )
+    .withDetails({ expected_keys: expected, response_keys: keys })
+    .withHint('先升级客户端：xinhe-oa-cli doctor --upgrade；仍复现就把 response_keys 报上来');
+}
+
+function requiredRows(data, key, what) {
+  const rows = data?.[key];
+  if (Array.isArray(rows)) return rows;
+  throw contractError(data, [key], what);
+}
+
+/** 表取数（`GET /tables/{id}/records`）的一页 `records`。 */
+function pageRecords(data) {
+  return requiredRows(data, 'records', '表取数');
+}
+
+/**
+ * 视图取数 / 视图聚合的行数组。
+ *
+ * 服务端的键是 **`items`**（`query_engine.list_records` / `aggregate_records`）；`records`
+ * 只作为对更早服务端形状的回落。0.1.4 的缺陷（docs/issues/CLI-089）是只读 `records`
+ * —— 于是**有数据的视图读成空**，`ok:true`、不报错、不告警。契约错位以后还可能再犯，
+ * 但"读不到就说读不到"必须钉死：宁可退出码 6，也不把空结果当答案交出去。
+ */
+function viewItems(data, what) {
+  for (const key of ['items', 'records']) {
+    if (Array.isArray(data?.[key])) return data[key];
+  }
+  throw contractError(data, ['items', 'records'], what);
+}
+
+/** 翻页结果的完整性：唯一行数、是否有重复、是否与 `total` 对得上。 */
+function pagingIntegrity(records, total, startOffset, reachedEnd) {
+  const fetched = records.length;
+  // 只按 `id` 去重：`id` 是主键，"两条记录同一个 id"就是服务端把同一行发了两遍。
+  // 没有 `id` 的项（投影坏了才会有）不参与去重，免得把"缺字段"误报成"重复"。
+  const ids = records
+    .map((item) => (item && typeof item.id === 'string' ? item.id : null))
+    .filter((id) => id !== null);
+  const withoutId = fetched - ids.length;
+  const unique = new Set(ids).size + withoutId;
+  const duplicates = Math.max(fetched - unique, 0);
+  const expected = typeof total === 'number' && Number.isInteger(total)
+    ? Math.max(total - startOffset, 0)
+    : null;
+  const missing = expected !== null && reachedEnd ? Math.max(expected - unique, 0) : 0;
+  return {
+    fetched,
+    unique,
+    duplicates,
+    expected,
+    missing,
+    reached_end: reachedEnd,
+    consistent: duplicates === 0 && missing === 0,
+  };
+}
+
+/**
+ * 完整性不过关时把"残缺结果"变成一条**错误**。
+ *
+ * 纪律：宁可让调用方重跑一次，也不要把"看着像全量"的半份数据交出去
+ * —— 现场那次 910 行只回 683 个唯一值，就是因为没人报错。
+ */
+function integrityError(integrity, tableId, order, limit) {
+  if (integrity.consistent) return null;
+  const why =
+    integrity.duplicates > 0
+      ? `翻页读到的 ${integrity.fetched} 行里只有 ${integrity.unique} 个唯一记录（${integrity.duplicates} 行重复）`
+      : `翻完了却只读到 ${integrity.unique} 行，服务端说有 ${integrity.expected ?? 0} 行（少 ${integrity.missing} 行）`;
+  return new CliError(
+    Kind.Conflict,
+    'cli.paging_unstable',
+    `${why} —— 这份结果不是一致的快照，已拒绝按全量返回`,
+  )
+    .withDetails({
+      table_id: tableId,
+      order,
+      limit,
+      fetched: integrity.fetched,
+      unique: integrity.unique,
+      duplicates: integrity.duplicates,
+      expected: integrity.expected,
+      missing: integrity.missing,
+      reached_end: integrity.reached_end,
+    })
+    .withHint(
+      `重跑一次（多半是翻页期间有人在写这张表）；要一致的快照用视图的游标分页：` +
+        `xinhe-oa-cli bitable view --query --view <VIEW_ID> --all --json（排序键已含 id：${order}）`,
+    );
+}
+
+/** 分页进度：`next_offset`（下一页从哪开始）与 `has_more`。 */
+function pagingState(startOffset, fetched, pageLen, limit, total) {
+  const nextOffset = startOffset + fetched;
+  const hasMore =
+    typeof total === 'number' && Number.isInteger(total) ? nextOffset < total : pageLen >= limit;
+  return [nextOffset, hasMore];
+}
+
+/** 下一页 / 下一步该敲哪条命令（还有下一页时优先回答"怎么翻页"）。 */
+function recordNextStep(tableId, limit, nextOffset) {
+  if (nextOffset !== null) {
+    return `还有下一页：xinhe-oa-cli bitable record --list --table ${tableId} --limit ${limit} --offset ${nextOffset} --json`;
+  }
+  return '改一条记录：xinhe-oa-cli bitable record --update <RECORD_ID> --version <N> --set 键=值';
+}
+
+/**
+ * `record --list --view <VIEW_ID>`：视图取数（游标分页），输出键仍是 `records`。
+ *
+ * 注意 `--cursor`：Rust 0.1.7 的 `view --query` 收下了 `--cursor` 却**从不使用**
+ * （`cursor` 从 `None` 起步，只由响应里的 `next_cursor` 推进）。这里**照抄该行为**：
+ * 行为等价优先于"顺手修一个上游缺陷"——两条实现同参数必须发同样的请求体，
+ * 否则对拍永远红。真要用它，得 Rust 与 Node 一起改（记在交付说明里）。
+ */
+async function recordListViaView(runtime, viewId, { limit, all, filters }) {
+  const collected = [];
+  let cursor = null;
+  const pageSize = clamp(limit, 1, 1000);
+  let lastResponse = null;
+  let pages = 0;
+  let truncated = null;
+  for (;;) {
+    pages += 1;
+    const body = { limit: pageSize };
+    if (cursor !== null) body.cursor = cursor;
+    const ast = filtersToAst(filters);
+    if (ast !== null) body.filters = ast;
+    const response = await runtime.sendAuthed(
+      'POST',
+      `/views/${viewId}/query`,
+      requestSpec({ body }),
+    );
+    const data = dataOf(response);
+    collected.push(...viewItems(data, '视图取数（record --list --view）'));
+    cursor = typeof data?.next_cursor === 'string' ? data.next_cursor : null;
+    const hasMore = data?.has_more === true;
+    lastResponse = response;
+    if (!all || !hasMore || cursor === null) break;
+    if (pages >= MAX_VIEW_PAGES) {
+      truncated = cursor;
+      warn(
+        `视图取数到 ${MAX_VIEW_PAGES} 页停下（每页 ${pageSize} 条）：这**不是**全量；` +
+          `续取：xinhe-oa-cli bitable view --query --view ${viewId} --cursor ${truncated ?? ''}`,
+      );
+      break;
+    }
+  }
+  const out = {
+    records: collected,
+    total: collected.length,
+    pages,
+    view_id: viewId,
+    truncated: truncated !== null,
+    next_step: '聚合：xinhe-oa-cli bitable view --aggregate --view <VIEW_ID> --measure 金额:sum',
+  };
+  if (truncated !== null) out.next_cursor = truncated;
+  if (lastResponse !== null) runtime.finishFrom(lastResponse, out);
+  else runtime.finish(out);
+}
+
+/** 客户端过滤：`values` 里的字段与字面量比较（与服务端算子同名的最小子集）。 */
+function recordMatches(record, ast) {
+  const children = Array.isArray(ast?.children) ? ast.children : null;
+  if (children === null) return true;
+  return children.every((leaf) => {
+    const field = typeof leaf?.field === 'string' ? leaf.field : '';
+    const operator =
+      typeof leaf?.operator === 'string' ? leaf.operator.toLowerCase() : 'eq';
+    const wanted = leaf?.value ?? null;
+    const actual = record?.values?.[field] ?? null;
+    return compare(actual, operator, wanted);
+  });
+}
+
+/** 与 Rust 的 `compare` 逐条同义：数值能解析就按数值比，否则按**字典序**。 */
+function compare(actual, operator, wanted) {
+  const actualText = asText(actual);
+  const wantedText = asText(wanted);
+  switch (operator) {
+    case 'eq':
+    case '=':
+      return actualText === wantedText;
+    case 'ne':
+    case '!=':
+      return actualText !== wantedText;
+    case 'contains':
+      return actualText.includes(wantedText);
+    case 'not_contains':
+      return !actualText.includes(wantedText);
+    case 'starts_with':
+      return actualText.startsWith(wantedText);
+    case 'ends_with':
+      return actualText.endsWith(wantedText);
+    case 'gt':
+    case 'gte':
+    case 'lt':
+    case 'lte': {
+      const left = parseNumberStrict(actualText);
+      const right = parseNumberStrict(wantedText);
+      if (left !== null && right !== null) {
+        if (operator === 'gt') return left > right;
+        if (operator === 'gte') return left >= right;
+        if (operator === 'lt') return left < right;
+        return left <= right;
+      }
+      if (operator === 'gt') return actualText > wantedText;
+      if (operator === 'gte') return actualText >= wantedText;
+      if (operator === 'lt') return actualText < wantedText;
+      return actualText <= wantedText;
+    }
+    case 'is_empty':
+      return actualText.length === 0;
+    case 'is_not_empty':
+      return actualText.length > 0;
+    default:
+      return false;
+  }
+}
+
+/** Rust 的 `str::parse::<f64>()`：整串都必须是数字（`''`、`12abc` 都不算）。 */
+function parseNumberStrict(text) {
+  if (!/^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/.test(text)) return null;
+  const value = Number(text);
+  return Number.isFinite(value) ? value : null;
+}
+
+/** 值 → 比较用的文本（与 Rust 的 `as_text` 同形；日期因此是**字典序**比较）。 */
+function asText(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') return String(value);
+  if (Array.isArray(value)) return value.map(asText).join(',');
+  return JSON.stringify(value);
+}
+
+// ---------------------------------------------------------------------------
+// Record —— 写
+// ---------------------------------------------------------------------------
+async function recordCreate(runtime, args) {
+  const tableId = requireText(args, '--table', 'bitable record --create');
+  const pairs = parseSetPairs(flagList(args, '--set'), '--set');
+  const attach = flagList(args, '--attach');
+  if (pairs.length === 0 && attach.length === 0) {
+    throw CliError.usage('`bitable record --create` 至少要给 --set 或 --attach').withHint(
+      '例：--set 金额=1200 --set 日期=2026-03-01',
+    );
+  }
+  const body = {
+    values: valuesObject(pairs),
+    source: flagValue(args, '--source') ?? 'cli',
+  };
+  const reason = flagValue(args, '--reason');
+  if (reason !== null) body.reason = reason;
+  const store = optionalId(args, '--store');
+  if (store !== null) body.store_id = store;
+  const path = `/tables/${tableId}/records`;
+  const spec = requestSpec({
+    body,
+    idempotencyKey: idempotencyKey('base-record-create', flagValue(args, '--idempotency-key')),
+  });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', path, spec);
+    for (const attachment of attach) {
+      warn(`（还会上传附件 ${attachment} 并挂到对应字段）`);
+    }
+    return;
+  }
+  const response = await runtime.sendAuthed('POST', path, spec);
+  const data = dataOf(response);
+  const recordId = typeof data?.id === 'string' ? data.id : '';
+
+  // `--attach 字段=文件`：上传 + 关联（关联后再把附件 id 写进该字段）。
+  const attachments = [];
+  if (attach.length > 0) {
+    for (const [field, file] of parsePairs(attach, '--attach')) {
+      const uploaded = await uploadFile(runtime, file, null, null);
+      const attachmentId = typeof uploaded?.id === 'string' ? uploaded.id : '';
+      if (attachmentId.length === 0) {
+        warn(`附件 ${file} 上传后没有拿到 id，跳过关联`);
+        continue;
+      }
+      // 关联到记录（字段可选：先按字段名/键找 field_id，找不到就只关联到记录）
+      const fieldId = await resolveFieldId(runtime, tableId, field);
+      const linkSpec = requestSpec({
+        body: { resource_type: 'record', resource_id: recordId, field_id: fieldId },
+      });
+      const linkResponse = await runtime.sendAuthed(
+        'POST',
+        `/attachments/${attachmentId}/links`,
+        linkSpec,
+      );
+      attachments.push({
+        field,
+        field_id: fieldId,
+        attachment_id: attachmentId,
+        link: dataOf(linkResponse),
+      });
+      // 把附件 id 写进该字段（`attachment_ref` 字段要求非空字符串）
+      const patchSpec = requestSpec({
+        body: { values: { [field]: attachmentId }, version: data?.version ?? 1 },
+        idempotencyKey: newIdempotencyKey('base-record-attach'),
+      });
+      try {
+        await runtime.sendAuthed('PATCH', `/records/${recordId}`, patchSpec);
+      } catch (err) {
+        // 附件已经传上去、也关联到记录了；字段没写进去只是"少一个便捷键"。
+        warn(`附件已上传并关联到记录，但写进字段 ${field} 失败（${err.code}）：${err.message}`);
+      }
+    }
+  }
+
+  runtime.finishFrom(response, {
+    record: data,
+    attachments,
+    note: '写操作带幂等键：同一个键重放会拿回首次结果（不会写两条）',
+  });
+}
+
+/** 把字段名（显示名或 semantic_key 或 field_id）解析成 field_id。 */
+async function resolveFieldId(runtime, tableId, field) {
+  if (String(field).startsWith('fld_')) return field;
+  try {
+    const response = await runtime.sendAuthed(
+      'GET',
+      `/tables/${tableId}/fields`,
+      requestSpec(),
+    );
+    const data = dataOf(response);
+    const fields = Array.isArray(data?.fields) ? data.fields : [];
+    for (const item of fields) {
+      if (item?.name === field || item?.semantic_key === field) {
+        return typeof item.id === 'string' ? item.id : null;
+      }
+    }
+  } catch {
+    return null;
+  }
+  return null;
+}
+
+async function recordUpdate(runtime, args) {
+  const recordId = requireId(args, '--update', 'bitable record');
+  const pairs = parseSetPairs(flagList(args, '--set'), '--set');
+  if (pairs.length === 0) {
+    throw CliError.usage('`bitable record --update` 需要 --set 键=值').withHint('例：--set 状态=已审');
+  }
+  // version 可以省：先 GET 一次拿最新的（乐观锁的语义仍是"基于我读到的版本"）。
+  const version = await resolveVersion(runtime, recordId, flagValue(args, '--version'), true);
+  const reason = flagValue(args, '--reason');
+  const body = { values: valuesObject(pairs), version, reason };
+  const spec = requestSpec({
+    body,
+    idempotencyKey: idempotencyKey('base-record-update', flagValue(args, '--idempotency-key')),
+  });
+  const path = `/records/${recordId}`;
+  if (runtime.dryRun) return runtime.dryRunReport('PATCH', path, spec);
+  const response = await runtime.sendAuthed('PATCH', path, spec);
+  runtime.finishFrom(response, { record: dataOf(response) });
+}
+
+/** 乐观锁版本：给了就用，没给就先读一次（读不到 = 服务端形状不对，退出码 6）。 */
+async function resolveVersion(runtime, recordId, raw, verboseFlag) {
+  if (raw !== null) {
+    const text = String(raw).trim();
+    if (!/^[+-]?\d+$/.test(text)) {
+      throw CliError.usage(`\`--version\` 要一个整数，收到 ${JSON.stringify(raw)}`);
+    }
+    return Number.parseInt(text, 10);
+  }
+  const response = await runtime.sendAuthed('GET', `/records/${recordId}`, requestSpec());
+  const data = dataOf(response);
+  const version = data?.version;
+  if (typeof version !== 'number' || !Number.isInteger(version)) {
+    throw new CliError(
+      Kind.Server,
+      'cli.bad_response',
+      '读不到记录的 version（乐观锁必须用它）',
+    ).withRequestId(response.request_id ?? null);
+  }
+  if (verboseFlag) verbose(runtime.verbose, `自动读到 version=${version}`);
+  return version;
+}
+
+async function recordDelete(runtime, args) {
+  const recordId = requireId(args, '--delete', 'bitable record');
+  runtime.requireYes(
+    'bitable record --delete（软删一条记录）',
+    `xinhe-oa-cli bitable record --delete ${recordId}`,
+  );
+  const version = await resolveVersion(runtime, recordId, flagValue(args, '--version'), false);
+  const query = [['version', String(version)]];
+  const reason = flagValue(args, '--reason');
+  if (reason !== null) query.push(['reason', reason]);
+  const spec = requestSpec({
+    query,
+    idempotencyKey: idempotencyKey('base-record-delete', flagValue(args, '--idempotency-key')),
+  });
+  const path = `/records/${recordId}`;
+  if (runtime.dryRun) return runtime.dryRunReport('DELETE', path, spec);
+  const response = await runtime.sendAuthed('DELETE', path, spec);
+  runtime.finishFrom(response, {
+    record: dataOf(response),
+    note: '软删：数据还在，可复盘',
+  });
+}
+
+async function recordShow(runtime, args) {
+  const recordId = requireId(args, '--show', 'bitable record');
+  const response = await runtime.sendAuthed('GET', `/records/${recordId}`, requestSpec());
+  runtime.finishFrom(response, { record: dataOf(response) });
+}
+
+// ---------------------------------------------------------------------------
+// View
+// ---------------------------------------------------------------------------
+async function viewList(runtime, args) {
+  const tableId = requireText(args, '--table', 'bitable view --list');
+  const response = await runtime.sendAuthed('GET', `/tables/${tableId}/views`, requestSpec());
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    views: Array.isArray(data?.views) ? data.views : [],
+    total: data?.total ?? null,
+    next_step: '按视图取数：xinhe-oa-cli bitable view --query --view <VIEW_ID> --all --json',
+  });
+}
+
+async function viewCreate(runtime, args) {
+  const tableId = requireText(args, '--table', 'bitable view --create');
+  const name = requireText(args, '--name', 'bitable view --create');
+  const viewType = flagValue(args, '--view-type') ?? 'grid';
+  if (!['grid', 'kanban', 'form'].includes(viewType)) {
+    throw CliError.usage(`--view-type 只能是 grid / kanban / form（收到 ${JSON.stringify(viewType)}）`);
+  }
+  const visibility = flagValue(args, '--visibility') ?? 'public';
+  if (!['public', 'personal'].includes(visibility)) {
+    throw CliError.usage(`--visibility 只能是 public / personal（收到 ${JSON.stringify(visibility)}）`);
+  }
+  const key = optionalId(args, '--key') ?? safeDeriveKey(name, 'v');
+  const body = { key, name, view_type: viewType, visibility };
+  const ast = filtersToAst(flagList(args, '--filter'));
+  if (ast !== null) body.filters = ast;
+  const spec = requestSpec({ body });
+  const path = `/tables/${tableId}/views`;
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, { view: dataOf(response) });
+}
+
+async function viewQuery(runtime, args) {
+  const viewId = requireId(args, '--view', 'bitable view');
+  const pageSize = intFlag(args, '--page-size', { fallback: 50 });
+  const all = flagOn(args, '--all');
+  const filters = flagList(args, '--filter');
+  const collected = [];
+  let cursor = null;
+  let pages = 0;
+  let truncated = null;
+  let lastResponse = null;
+  for (;;) {
+    pages += 1;
+    const body = { limit: pageSize };
+    if (cursor !== null) body.cursor = cursor;
+    const ast = filtersToAst(filters);
+    if (ast !== null) body.filters = ast;
+    const response = await runtime.sendAuthed(
+      'POST',
+      `/views/${viewId}/query`,
+      requestSpec({ body }),
+    );
+    const data = dataOf(response);
+    collected.push(...viewItems(data, '视图取数（view --query）'));
+    cursor = typeof data?.next_cursor === 'string' ? data.next_cursor : null;
+    const hasMore = data?.has_more === true;
+    lastResponse = response;
+    if (!all || !hasMore || cursor === null) break;
+    if (pages >= MAX_VIEW_PAGES) {
+      truncated = cursor;
+      warn(
+        `视图取数到 ${MAX_VIEW_PAGES} 页停下（每页 ${pageSize} 条）：这**不是**全量；` +
+          `续取：xinhe-oa-cli bitable view --query --view ${viewId} --cursor ${truncated ?? ''}`,
+      );
+      break;
+    }
+  }
+  const out = {
+    records: collected,
+    total: collected.length,
+    pages,
+    view_id: viewId,
+    truncated: truncated !== null,
+  };
+  if (truncated !== null) out.next_cursor = truncated;
+  if (lastResponse !== null) runtime.finishFrom(lastResponse, out);
+  else runtime.finish(out);
+}
+
+async function viewAggregate(runtime, args) {
+  const viewId = requireId(args, '--view', 'bitable view');
+  const measures = flagList(args, '--measure');
+  if (measures.length === 0) {
+    throw CliError.usage('`bitable view --aggregate` 需要 --measure 字段:sum').withHint(
+      '聚合算子：sum | avg | max | min | count；例：--measure 金额:sum',
+    );
+  }
+  const metrics = [];
+  for (const measure of measures) {
+    const colon = String(measure).lastIndexOf(':');
+    if (colon <= 0) {
+      throw CliError.usage(
+        `--measure 的写法是 \`字段:算子\`，收到 ${JSON.stringify(measure)}`,
+      ).withHint('例：--measure 金额:sum');
+    }
+    const field = String(measure).slice(0, colon).trim();
+    const agg = String(measure).slice(colon + 1).trim().toLowerCase();
+    if (!['sum', 'avg', 'max', 'min', 'count'].includes(agg)) {
+      throw CliError.usage(`不支持的聚合算子 ${JSON.stringify(agg)}`).withHint(
+        '算子：sum | avg | max | min | count',
+      );
+    }
+    metrics.push({ field, agg });
+  }
+  // 分组来自视图配置（服务端口径）；`--group-by` 用于在结果里挑出分组列名（提示用）。
+  const spec = requestSpec({ body: { metrics } });
+  const path = `/views/${viewId}/aggregate`;
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  const data = dataOf(response);
+  // 行/分组数组的键与视图取数同源：服务端给的是 `items`（`aggregate_records`）。
+  // 旧实现取 `groups` 并把整个 `data` 当兜底，于是结果落在 `data.groups.items` 这个
+  // 错位的形状里（docs/issues/CLI-089）：不丢数据，但按文档取 `data.groups` 取到的是整个响应体。
+  let groups;
+  if (data?.items !== undefined) groups = data.items;
+  else if (data?.groups !== undefined) groups = data.groups;
+  else groups = [];
+  runtime.finishFrom(response, {
+    groups,
+    totals: data?.totals ?? null,
+    count: data?.count ?? null,
+    group_by: data?.group_by ?? null,
+    view_id: viewId,
+    // `--group-by` 在 Rust 那边是 `Vec<String>`：不给就是 `[]`（不是 null）。
+    group_by_hint: flagList(args, '--group-by'),
+    note: '分组来自视图自身的 groups 配置；要换分组先 PATCH 视图（服务端口径）',
+  });
+}
+
+async function viewShow(runtime, args) {
+  const viewId = requireId(args, '--show', 'bitable view');
+  const response = await runtime.sendAuthed('GET', `/views/${viewId}`, requestSpec());
+  runtime.finishFrom(response, dataOf(response));
+}
+
+// ---------------------------------------------------------------------------
+// Form
+// ---------------------------------------------------------------------------
+async function formList(runtime, args) {
+  const tableId = requireText(args, '--table', 'bitable form --list');
+  const response = await runtime.sendAuthed('GET', `/tables/${tableId}/forms`, requestSpec());
+  const data = dataOf(response);
+  runtime.finishFrom(response, {
+    forms: Array.isArray(data?.forms) ? data.forms : [],
+    total: data?.total ?? null,
+    next_step: '提交：xinhe-oa-cli bitable form --submit --form <FORM_ID> --set 键=值',
+  });
+}
+
+async function formCreate(runtime, args) {
+  const tableId = requireText(args, '--table', 'bitable form --create');
+  const name = requireText(args, '--name', 'bitable form --create');
+  const submitMode = flagValue(args, '--submit-mode') ?? 'create';
+  if (!['create', 'update'].includes(submitMode)) {
+    throw CliError.usage(`--submit-mode 只能是 create / update（收到 ${JSON.stringify(submitMode)}）`);
+  }
+  const key = optionalId(args, '--key') ?? safeDeriveKey(name, 'f');
+  const spec = requestSpec({ body: { key, name, submit_mode: submitMode } });
+  const path = `/tables/${tableId}/forms`;
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, { form: dataOf(response) });
+}
+
+async function formSubmit(runtime, args) {
+  const formId = requireText(args, '--form', 'bitable form --submit');
+  const pairs = parseSetPairs(flagList(args, '--set'), '--set');
+  if (pairs.length === 0) {
+    throw CliError.usage('`bitable form --submit` 需要 --set 键=值');
+  }
+  const submitMode = flagValue(args, '--submit-mode') ?? 'create';
+  const record = optionalId(args, '--record');
+  if (submitMode === 'update' && record === null) {
+    throw CliError.usage(
+      '提交方式为 update 时必须给 --record <RECORD_ID>（乐观锁还要 --version）',
+    ).withHint('先看记录：xinhe-oa-cli bitable record --list --table <TABLE_ID> --json');
+  }
+  const versionRaw = flagValue(args, '--version');
+  let version = null;
+  if (versionRaw !== null) {
+    if (!/^[+-]?\d+$/.test(String(versionRaw).trim())) {
+      throw CliError.usage(`\`--version\` 要一个整数，收到 ${JSON.stringify(versionRaw)}`);
+    }
+    version = Number.parseInt(String(versionRaw).trim(), 10);
+  }
+  const body = { values: valuesObject(pairs), record_id: record, version };
+  const spec = requestSpec({
+    body,
+    idempotencyKey: idempotencyKey('base-form-submit', flagValue(args, '--idempotency-key')),
+  });
+  const path = `/forms/${formId}/submit`;
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, { record: dataOf(response) });
+}
+
+async function formShow(runtime, args) {
+  const formId = requireId(args, '--show', 'bitable form');
+  const response = await runtime.sendAuthed('GET', `/forms/${formId}`, requestSpec());
+  runtime.finishFrom(response, dataOf(response));
+}
+
+// ---------------------------------------------------------------------------
+// 可见性与分享（TABLE-001 #96 / TABLE-002 #97）—— 库与表共用一份实现
+// ---------------------------------------------------------------------------
+/** URL 段（复数）与 CLI 词（单数）：提示里给的是"照着抄就能跑"的命令。 */
+function kindOf(kind) {
+  return kind === 'base'
+    ? { segment: 'bases', label: '库', cli: 'base' }
+    : { segment: 'tables', label: '表', cli: 'table' };
+}
+
+/**
+ * 这次请求要用哪家企业。
+ *
+ * **`--dry-run` 不联网**：它只该把"将要发出的请求"打出来，所以在 dry-run 下
+ * 用 `<TENANT_ID>` 占位、绝不为了问企业去发 `GET /me`。
+ */
+async function tenantOf(runtime, args, action) {
+  const tenant = flagValue(args, '--tenant');
+  if (tenant !== null && tenant.trim().length > 0) return tenant.trim();
+  if (runtime.dryRun) return '<TENANT_ID>';
+  const resolved = await resolveTenant(runtime, null);
+  if (resolved === null) {
+    throw CliError.usage(`${action}必须指明企业`).withHint(
+      '加 --tenant <TENANT_ID>；用 `xinhe-oa-cli tenant --list` 看有哪些企业',
+    );
+  }
+  return resolved;
+}
+
+const tenantQuery = (tenant) => [['tenant', tenant]];
+
+/** `--expected-epoch`：先 `--show` 拿 `inherit_epoch` 原样传回（乐观锁）。 */
+function epochValue(raw) {
+  if (raw === null || raw === undefined) return null;
+  const text = String(raw).trim();
+  if (!/^[+-]?\d+$/.test(text)) {
+    throw CliError.usage(`\`--expected-epoch\` 必须是整数（收到 ${JSON.stringify(text)}）`).withHint(
+      '先 `--visibility <ID> --show` 拿 inherit_epoch 原样传回',
+    );
+  }
+  return Number.parseInt(text, 10);
+}
+
+/** `--visibility <ID> --show`：读档位 + **夹紧后的有效档位**。 */
+async function showVisibility(runtime, args, kind, id) {
+  const tenant = await tenantOf(runtime, args, '读可见性');
+  const path = `/${kindOf(kind).segment}/${id}/visibility`;
+  const spec = requestSpec({ query: tenantQuery(tenant) });
+  if (runtime.dryRun) return runtime.dryRunReport('GET', path, spec);
+  const response = await runtime.sendAuthed('GET', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `--visibility <ID> --set private|dept|internal`：改档位（**高风险**）。 */
+async function setVisibility(runtime, args, kind, id, rawTier) {
+  const tier = String(rawTier).trim().toLowerCase();
+  if (!['private', 'dept', 'internal'].includes(tier)) {
+    // `public` 本期没有对外入口：本地拒（退出码 2、不发请求），与文件域同一条红线。
+    const hint = `例：xinhe-oa-cli bitable ${kindOf(kind).cli} --visibility <ID> --set internal --yes`;
+    throw CliError.usage(
+      `\`--set\` 只能是 private | dept | internal（收到 ${JSON.stringify(tier)}）；                     \`public\` 本期没有对外入口`,
+    ).withHint(hint);
+  }
+  runtime.requireYes(
+    `${kindOf(kind).cli} --visibility --set（一次可能放开一批人或收掉一批人）`,
+    `xinhe-oa-cli bitable ${kindOf(kind).cli} --visibility ${id} --set ${tier} --yes`,
+  );
+  const tenant = await tenantOf(runtime, args, '改可见性');
+  const body = { visibility: tier };
+  const dept = optionalId(args, '--dept');
+  if (dept !== null) body.dept_id = dept;
+  const epoch = epochValue(flagValue(args, '--expected-epoch'));
+  if (epoch !== null) body.expected_epoch = epoch;
+  const path = `/${kindOf(kind).segment}/${id}/visibility`;
+  const spec = requestSpec({
+    body,
+    query: tenantQuery(tenant),
+    idempotencyKey: newIdempotencyKey('object-visibility'),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `--move <ID> --to-dept <OU_ID>`：换归属 = **重算继承**（**高风险**）。 */
+async function moveObject(runtime, args, kind) {
+  const id = requireId(args, '--move', `bitable ${kindOf(kind).cli}`);
+  const toDept = optionalId(args, '--to-dept');
+  if (toDept === null) {
+    throw CliError.usage('`--move` 需要 `--to-dept <OU_ID>`').withHint(
+      `例：xinhe-oa-cli bitable ${kindOf(kind).cli} --move <${kind === 'base' ? 'BASE' : 'TABLE'}_ID> --to-dept ou_xxx --yes`,
+    );
+  }
+  runtime.requireYes(
+    `${kindOf(kind).label} --move（换归属会夹紧档位并作废越出容器的分享）`,
+    `xinhe-oa-cli bitable ${kindOf(kind).cli} --move ${id} --to-dept ${toDept} --yes`,
+  );
+  const tenant = await tenantOf(runtime, args, '移动归属');
+  const body = { to_dept: toDept };
+  const epoch = epochValue(flagValue(args, '--expected-epoch'));
+  if (epoch !== null) body.expected_epoch = epoch;
+  const path = `/${kindOf(kind).segment}/${id}/move`;
+  const spec = requestSpec({
+    body,
+    query: tenantQuery(tenant),
+    idempotencyKey: newIdempotencyKey('object-move'),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `--share <ID> --to-user|--to-dept [--acl-action read|write]`（**默认给读**）。 */
+async function share(runtime, args, kind) {
+  const id = requireId(args, '--share', `bitable ${kindOf(kind).cli}`);
+  const toUser = optionalId(args, '--to-user');
+  const toDept = optionalId(args, '--to-dept');
+  if ((toUser === null) === (toDept === null)) {
+    throw CliError.usage(
+      '`--share` 需要 `--to-user <USER_ID>` 与 `--to-dept <OU_ID>` **恰好一个**',
+    ).withHint(
+      `例：xinhe-oa-cli bitable ${kindOf(kind).cli} --share <ID> --to-user usr_xxx --json`,
+    );
+  }
+  const action = (flagValue(args, '--acl-action') ?? 'read').trim().toLowerCase();
+  if (!['read', 'write'].includes(action)) {
+    throw CliError.usage(
+      `\`--acl-action\` 只能是 read | write（收到 ${JSON.stringify(action)}）；不传就是 read`,
+    ).withHint('例：--acl-action write（写分享默认 90 天到期）');
+  }
+  const tenant = await tenantOf(runtime, args, '分享');
+  const body = {};
+  if (toUser !== null) body.to_user = toUser;
+  if (toDept !== null) body.to_dept = toDept;
+  body.action = action;
+  const expires = optionalId(args, '--expires-at');
+  if (expires !== null) body.expires_at = expires;
+  const path = `/${kindOf(kind).segment}/${id}/share`;
+  const spec = requestSpec({
+    body,
+    query: tenantQuery(tenant),
+    idempotencyKey: newIdempotencyKey('object-share'),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `--acl-list <ID>`：这张表/库被分享给了谁（读）。 */
+async function aclList(runtime, args, kind) {
+  const id = requireId(args, '--acl-list', `bitable ${kindOf(kind).cli}`);
+  const tenant = await tenantOf(runtime, args, '读分享清单');
+  const path = `/${kindOf(kind).segment}/${id}/acl`;
+  const spec = requestSpec({ query: tenantQuery(tenant) });
+  if (runtime.dryRun) return runtime.dryRunReport('GET', path, spec);
+  const response = await runtime.sendAuthed('GET', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `--acl-revoke <ID> --from-user|--from-dept --acl-action`：收回一条分享（**降险，不卡 `--yes`**）。 */
+async function aclRevoke(runtime, args, kind) {
+  const id = requireId(args, '--acl-revoke', `bitable ${kindOf(kind).cli}`);
+  const fromUser = optionalId(args, '--from-user');
+  const fromDept = optionalId(args, '--from-dept');
+  if ((fromUser === null) === (fromDept === null)) {
+    throw CliError.usage(
+      '`--acl-revoke` 需要 `--from-user <USER_ID>` 与 `--from-dept <OU_ID>` **恰好一个**',
+    ).withHint(
+      `例：xinhe-oa-cli bitable ${kindOf(kind).cli} --acl-revoke <ID> --from-user usr_xxx --acl-action read`,
+    );
+  }
+  const action = (flagValue(args, '--acl-action') ?? 'read').trim().toLowerCase();
+  if (!['read', 'write'].includes(action)) {
+    throw CliError.usage(
+      `\`--acl-action\` 只能是 read | write（收到 ${JSON.stringify(action)}）`,
+    ).withHint('收回哪一条分享就写哪个动作；不传 = read');
+  }
+  const tenant = await tenantOf(runtime, args, '收回分享');
+  const body = {};
+  if (fromUser !== null) body.from_user = fromUser;
+  if (fromDept !== null) body.from_dept = fromDept;
+  body.action = action;
+  const path = `/${kindOf(kind).segment}/${id}/acl/revoke`;
+  const spec = requestSpec({
+    body,
+    query: tenantQuery(tenant),
+    idempotencyKey: newIdempotencyKey('object-acl-revoke'),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `--investor-visibility <ID> --investor-set open|closed`（TABLE-002，**高风险**）。 */
+async function investorVisibility(runtime, args, kind) {
+  const id = requireId(args, '--investor-visibility', `bitable ${kindOf(kind).cli}`);
+  const raw = (flagValue(args, '--investor-set') ?? '').trim().toLowerCase();
+  let wanted;
+  if (raw === 'open') wanted = true;
+  else if (raw === 'closed') wanted = false;
+  else {
+    throw CliError.usage(
+      `\`--investor-set\` 只能是 open | closed（收到 ${JSON.stringify(raw)}）`,
+    ).withHint(
+      `例：xinhe-oa-cli bitable ${kindOf(kind).cli} --investor-visibility <ID> --investor-set open --yes`,
+    );
+  }
+  runtime.requireYes(
+    `${kindOf(kind).label} --investor-visibility（一次可能让外部投资人看到一批数据）`,
+    `xinhe-oa-cli bitable ${kindOf(kind).cli} --investor-visibility ${id} --investor-set ${raw} --yes`,
+  );
+  const tenant = await tenantOf(runtime, args, '开关投资人可见性');
+  const path = `/${kindOf(kind).segment}/${id}/investor-visibility`;
+  const spec = requestSpec({
+    body: { investor_visible: wanted },
+    query: tenantQuery(tenant),
+    idempotencyKey: newIdempotencyKey('object-investor-visibility'),
+  });
+  if (runtime.dryRun) return runtime.dryRunReport('POST', path, spec);
+  const response = await runtime.sendAuthed('POST', path, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+// ---------------------------------------------------------------------------
+// 附件（`--keep-source` / `record --create --attach` 共用）
+// ---------------------------------------------------------------------------
+/** 上传一个文件到 `/attachments`（multipart 的字段与服务端口径逐字一致）。 */
+async function uploadFile(runtime, file, tenant, name) {
+  const bytes = readFileBytes(file);
+  const fileName = fileNameOf(file);
+  let resolvedTenant = tenant === null || tenant === undefined ? '' : String(tenant).trim();
+  if (resolvedTenant.length === 0) {
+    const found = await resolveTenant(runtime, null);
+    if (found === null) {
+      throw CliError.usage('上传附件必须指明企业').withHint(
+        '加 --tenant <TENANT_ID>；用 `xinhe-oa-cli tenant --list` 看有哪些企业',
+      );
+    }
+    resolvedTenant = found;
+  }
+  const form = multipartBody(
+    [
+      ['tenant', resolvedTenant],
+      ['name', name ?? fileName],
+    ],
+    ['file', fileName, bytes],
+  );
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', '/attachments', requestSpec({ multipart: form }));
+    return { dry_run: true };
+  }
+  const response = await runtime.sendUpload('/attachments', form, newIdempotencyKey('attachment-upload'));
+  return dataOf(response);
+}
+
+// ---------------------------------------------------------------------------
+// 导入：`bitable table --import`
+// ---------------------------------------------------------------------------
+/**
+ * 解析文件 → 找或建库 → 建表 → 建字段 → 分批写记录（契约 §2.1、§5、§6.2）。
+ *
+ * `--append` 是"每月例行更新"的正解。它的三条硬语义：
+ *
+ * 1. **绝不静默建新表**：同 `--key` / 同 `--name` 的表找不到 → 报可读的错（列出候选）；
+ * 2. **字段沿用已有的**：按显示名匹配，其次机器名；类型以**表里那个字段**为准；
+ * 3. **幂等键由文件内容决定**：同一个文件重跑 = 重放，不会写两遍。
+ */
+async function importTable(runtime, args) {
+  const file = flagValue(args, '--file');
+  if (file === null) {
+    throw CliError.usage('`bitable table --import` 需要 --file <x.csv|x.xlsx>').withHint(
+      '例：xinhe-oa-cli bitable table --import --file 公账流水.csv --base-name 开叔企业 --name 公账流水',
+    );
+  }
+  const tableName = flagValue(args, '--name');
+  if (tableName === null) {
+    throw CliError.usage('`bitable table --import` 需要 --name <表名>').withHint('例：--name 公账流水');
+  }
+
+  // ① 解析（类型覆盖在解析里生效）
+  const overrides = imp.parseTypeOverrides(flagList(args, '--type'));
+  const parsed = imp.parseFile(
+    file,
+    flagValue(args, '--sheet'),
+    overrides,
+    flagOn(args, '--no-infer'),
+  );
+  parsed.file = file;
+  verbose(
+    runtime.verbose,
+    `解析 ${file}：${parsed.columns.length} 列 × ${parsed.rows.length} 行（${parsed.sourceFormat}）`,
+  );
+
+  // ② `--store-column` 先校验：这是"参数拼错"，必须在**建表之前**报出来，
+  //    否则表建好了才发现列名写错，白白留下半张表。
+  const storeColumn = flagValue(args, '--store-column');
+  let storeColumnIndex = null;
+  if (storeColumn !== null) {
+    storeColumnIndex = parsed.columns.findIndex((column) => column.name === storeColumn);
+    if (storeColumnIndex < 0) {
+      throw CliError.usage(
+        `--store-column 里的列 ${JSON.stringify(storeColumn)} 不在文件的表头里`,
+      ).withDetails({ available_columns: parsed.columns.map((column) => column.name) });
+    }
+  }
+
+  // ③ 目标库 / 目标表（`--append` 时表必须已存在，绝不静默新建）
+  const target = await resolveTarget(runtime, args, tableName);
+  // ④ 列的落点：新建全部字段；追加则按 显示名 → 机器名 沿用已有字段
+  const resolved = resolveColumns(parsed, target.existingFields);
+
+  // ⑤ `--dry-run`：打印完整计划，一个请求都不发
+  if (runtime.dryRun) {
+    const plan = buildPlan(runtime, {
+      file,
+      parsed,
+      target,
+      columns: resolved,
+      batchSize: importBatchSize(args),
+      keepSource: flagOn(args, '--keep-source'),
+      storeColumn,
+      storeColumnIndex,
+    });
+    const data = {
+      dry_run: true,
+      plan,
+      note: '--dry-run：一个请求都没发，也没写任何东西；库/表是否已存在未联网确认（计划里标了"未确认"）',
+    };
+    return runtime.finishWithHuman(data, (markdown) => planHuman(plan, markdown));
+  }
+
+  // ⑥ 建表（`--append` 时跳过：目标表已经在 ③ 里找到了）
+  let tableId = target.tableId;
+  if (tableId === null) {
+    const baseId = target.baseId ?? '';
+    const tableBody = {
+      key: target.tableKey,
+      name: tableName,
+      description: flagValue(args, '--description') ?? `由 ${file} 导入`,
+      semantic_kind: flagValue(args, '--semantic-kind') ?? 'ledger',
+    };
+    const response = await runtime.sendAuthed(
+      'POST',
+      `/bases/${baseId}/tables`,
+      requestSpec({ body: tableBody }),
+    );
+    const table = dataOf(response);
+    if (typeof table?.id !== 'string') {
+      throw new CliError(Kind.Server, 'cli.bad_response', '建表后没有拿到 table_id').withRequestId(
+        response.request_id ?? null,
+      );
+    }
+    tableId = table.id;
+  }
+  const tableCreated = !flagOn(args, '--append');
+
+  // ⑦ 建字段：只建"这次文件里有、表里还没有"的列（追加时已有的字段原样沿用）
+  const fieldsCreated = [];
+  const fieldErrors = [];
+  for (const [index, item] of resolved.entries()) {
+    if (item.action !== 'create') continue;
+    const payload = imp.fieldPayload(item.column, index);
+    try {
+      const response = await runtime.sendAuthed(
+        'POST',
+        `/tables/${tableId}/fields`,
+        requestSpec({ body: payload }),
+      );
+      fieldsCreated.push(dataOf(response));
+    } catch (err) {
+      // 一个字段失败不该让整张表白建：记下来，最后如实报告。
+      warn(`字段 ${item.column.name} 建失败（${err.code}：${err.message}），继续`);
+      fieldErrors.push({
+        column: item.column.name,
+        semantic_key: item.column.semanticKey,
+        error: { code: err.code, message: err.message, details: err.details ?? {} },
+      });
+    }
+  }
+
+  // ⑧ 分批写记录：并发发批 + 断点续传 + 每批进度
+  const fileHash = imp.fileFingerprint(parsed);
+  const [recordsCreated, batchReports] = await writeBatches(runtime, {
+    args,
+    parsed,
+    columns: resolved,
+    file,
+    tableId,
+    fileHash,
+    storeColumnIndex,
+  });
+
+  // ⑨ 可选：把原文件作为附件挂上
+  const attachment = await keepSourceAttachment(runtime, args, file, batchReports);
+
+  const columnsReport = resolved.map((item) => ({
+    column: item.column.name,
+    semantic_key: item.writeKey,
+    field_id: item.fieldId,
+    type: item.existingType ?? item.column.columnType,
+    type_source:
+      item.existingType !== null
+        ? 'existing_field'
+        : item.column.overridden
+          ? 'override'
+          : 'inferred',
+    action: item.action,
+    matched_by: item.matchedBy,
+    reason: item.column.reason,
+  }));
+  const fieldsReused = resolved.filter((item) => item.action === 'reuse').length;
+  const appended = flagOn(args, '--append');
+  const out = {
+    base_id: target.baseId,
+    base_created: target.baseAction === 'create',
+    table_id: tableId,
+    table_name: tableName,
+    table_created: tableCreated,
+    appended,
+    source_file: file,
+    source_format: parsed.sourceFormat,
+    sheet: parsed.sheetName,
+    fields_created: fieldsCreated.length,
+    fields_reused: fieldsReused,
+    records_created: recordsCreated,
+    rows_in_file: parsed.rows.length,
+    skipped_empty_rows: parsed.skippedEmptyRows,
+    batches: batchReports.length,
+    batch_size: Math.min(importBatchSize(args), imp.MAX_BATCH),
+    columns: columnsReport,
+    field_errors: fieldErrors,
+    batch_reports: batchReports,
+    attachment,
+    next_step: `看数据：xinhe-oa-cli bitable record --list --table ${tableId} --limit 5 --json`,
+    note: appended
+      ? '解析、类型推断、分批全在客户端完成；追加：字段沿用目标表已有的（按显示名→机器名匹配），记录按内容幂等键写入'
+      : '解析、类型推断、分批全在客户端完成；平台只存结果（契约 §6.2）。中途失败重跑时加 --append 会补进这张表，不会再建一张',
+  };
+  // 人类可读面：**列 → 字段的映射**才是导完之后要照着用的东西
+  //（通用渲染会挑到 batch_reports 那张表，把映射藏起来）。
+  runtime.finishWithHuman(out, (markdown) => importHuman(out, markdown));
+}
+
+/** 一次导入的目标（库 + 表）：`--append` 时表必须已存在。 */
+async function resolveTarget(runtime, args, tableName) {
+  const appended = flagOn(args, '--append');
+  const tableAction = appended ? 'append' : 'create';
+  const tableKey = optionalId(args, '--key') ?? safeDeriveKey(tableName, 't');
+
+  // ---- 库 ----
+  let baseId = optionalId(args, '--base');
+  let baseName = null;
+  let baseAction;
+  if (baseId !== null) {
+    baseAction = 'given';
+  } else {
+    const wanted = flagValue(args, '--base-name');
+    if (wanted === null) {
+      throw CliError.usage(
+        '`bitable table --import` 需要 --base <BASE_ID> 或 --base-name <库名>',
+      ).withHint('例：--base-name 开叔企业（新表时找不到就建一个）');
+    }
+    baseName = wanted;
+    if (runtime.dryRun) {
+      // dry-run 不联网：库是否存在留到计划里标"未确认"。
+      baseAction = 'find-or-create';
+    } else {
+      const found = await findBaseByName(runtime, wanted);
+      if (found !== null) {
+        baseId = found;
+        baseAction = 'reuse';
+      } else if (appended) {
+        // 追加语义：目标必须已存在 —— 连库都没有，就不该悄悄建一个。
+        const names = await visibleBaseNames(runtime);
+        throw CliError.usage(
+          `--append 要追加到已存在的库，但没找到名为 ${JSON.stringify(wanted)} 的库（追加不会新建库）`,
+        )
+          .withDetails({ wanted_base_name: wanted, visible_bases: names })
+          .withHint('确认库名（或改用 --base <BASE_ID>）；要新建库就去掉 --append');
+      } else {
+        baseId = await createBase(runtime, args, wanted, tableName);
+        baseAction = 'create';
+      }
+    }
+  }
+
+  const target = {
+    baseId,
+    baseName,
+    baseAction,
+    tableId: null,
+    tableKey,
+    tableName,
+    tableAction,
+    existingFields: [],
+  };
+
+  // ---- 表 ----
+  if (runtime.dryRun) return target;
+  const baseRef = baseId ?? '';
+  // 追加时要能看见归档的表（好给出"这张表已归档，写不进去"这种可读的错）。
+  const tables = await listTables(runtime, baseRef, appended);
+
+  if (appended) {
+    const found = pickAppendTarget(tables, args, tableName);
+    const foundId = typeof found?.id === 'string' ? found.id : '';
+    target.tableId = foundId;
+    target.existingFields = await fetchFields(runtime, foundId);
+    verbose(
+      runtime.verbose,
+      `追加到已有表 ${found?.name ?? ''}（${foundId}，key=${found?.key ?? ''}）`,
+    );
+    return target;
+  }
+
+  // 建新表：同名 / 同 key 的表已存在就报错 —— **不静默再建一张同名的**
+  // （现场问题：探路导一次、正式再导一次，库里就多了一张同名表，而 key 还被占着）。
+  const existing = findExistingTable(tables, args, tableName);
+  if (existing !== null) {
+    const existingId = typeof existing.id === 'string' ? existing.id : '';
+    const existingName = typeof existing.name === 'string' ? existing.name : '';
+    const existingKey = typeof existing.key === 'string' ? existing.key : '';
+    const matched = optionalId(args, '--key') === existingKey && existingKey.length > 0 ? '--key' : '--name';
+    throw CliError.usage(
+      `这个库里已经有一张表叫 ${JSON.stringify(existingName)}（${existingId}，key=${existingKey}），撞的是 ${matched}`,
+    )
+      .withDetails({
+        existing_table: { id: existingId, name: existingName, key: existingKey },
+        base_id: baseRef,
+      })
+      .withHint(
+        `要往它里面追加：加 --append（xinhe-oa-cli bitable table --import --file <文件> --base ${baseRef} --name ${existingName} --append）；要另建一张：换个 --name 或 --key`,
+      );
+  }
+  return target;
+}
+
+/** 列一遍可见的库，按显示名找（名字相同取第一个；机器名才是身份）。 */
+async function findBaseByName(runtime, wanted) {
+  const response = await runtime.sendAuthed('GET', '/bases', requestSpec());
+  const data = dataOf(response);
+  const bases = Array.isArray(data?.bases) ? data.bases : [];
+  const hit = bases.find((item) => item?.name === wanted);
+  return typeof hit?.id === 'string' ? hit.id : null;
+}
+
+/** 报错时列出可见库名（让人一眼看出是不是名字记错了）。 */
+async function visibleBaseNames(runtime) {
+  const response = await runtime.sendAuthed('GET', '/bases', requestSpec());
+  const data = dataOf(response);
+  const bases = Array.isArray(data?.bases) ? data.bases : [];
+  return bases
+    .map((item) => (typeof item?.name === 'string' ? item.name : null))
+    .filter((name) => name !== null);
+}
+
+/** 建库（只有**不追加**时才会走到这里）。 */
+async function createBase(runtime, args, wanted, tableName) {
+  // key 由库名推导，推不出来就用表名 + 随机后缀（合法且稳定到"这次导入"）。
+  let key;
+  try {
+    key = deriveKey(wanted);
+  } catch {
+    let tableKey = 't';
+    try {
+      tableKey = deriveKey(tableName);
+    } catch {
+      /* 表名也推不出来就用 't' */
+    }
+    key = `b${newIdempotencyKey('x').split(':')[1].slice(0, 6)}_${tableKey}`;
+  }
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'));
+  if (tenant === null) {
+    throw CliError.usage('导入必须落在某家企业里，但看不出你属于哪一家').withHint(
+      '用 `xinhe-oa-cli me --json` 看 scope.tenants，或 `tenant --list`；也可显式 --tenant <TENANT_ID>',
+    );
+  }
+  const body = {
+    tenant,
+    key,
+    name: wanted,
+    description: '由 bitable table --import 自动创建',
+  };
+  const response = await runtime.sendAuthed('POST', '/bases', requestSpec({ body }));
+  const data = dataOf(response);
+  if (typeof data?.id !== 'string') {
+    throw new CliError(Kind.Server, 'cli.bad_response', '建库后没有拿到 base_id').withRequestId(
+      response.request_id ?? null,
+    );
+  }
+  verbose(runtime.verbose, `新建库 ${wanted}（${data.id}）`);
+  return data.id;
+}
+
+/** 列 base 下的表（`--append` 时带上已归档的：好把"表已归档"说清楚）。 */
+async function listTables(runtime, baseId, includeArchived) {
+  const query = [];
+  if (includeArchived) query.push(['include_archived', 'true']);
+  const response = await runtime.sendAuthed(
+    'GET',
+    `/bases/${baseId}/tables`,
+    requestSpec({ query }),
+  );
+  const data = dataOf(response);
+  return Array.isArray(data?.tables) ? data.tables : [];
+}
+
+async function fetchFields(runtime, tableId) {
+  const response = await runtime.sendAuthed('GET', `/tables/${tableId}/fields`, requestSpec());
+  const data = dataOf(response);
+  return Array.isArray(data?.fields) ? data.fields : [];
+}
+
+/** 表的一行摘要（报错时列候选、计划里说明目标用）。 */
+function tableBrief(table) {
+  return {
+    id: table?.id ?? null,
+    key: table?.key ?? null,
+    name: table?.name ?? null,
+    status: table?.status ?? null,
+  };
+}
+
+/**
+ * 追加目标：`--key` 优先（key 是身份，显示名可以改），否则按显示名。
+ *
+ * 找不到 / 撞多张 / 已归档 → 三种可读的错，**绝不静默建新表**。
+ */
+function pickAppendTarget(tables, args, tableName) {
+  const key = optionalId(args, '--key');
+  const matches =
+    key !== null
+      ? tables.filter((table) => table?.key === key)
+      : tables.filter((table) => table?.name === tableName);
+  const wanted = key !== null ? `key=${key}` : `表名 ${JSON.stringify(tableName)}`;
+  const catalogue = tables.map(tableBrief);
+  if (matches.length === 0) {
+    throw CliError.usage(
+      `--append 要追加到已存在的表，但这个库里没有 ${wanted} 的表（追加不会新建表）`,
+    )
+      .withDetails({ tables_in_base: catalogue })
+      .withHint(
+        '确认表名/--key，或先不带 --append 导入建表；`bitable table --list --base <BASE_ID> --include-archived` 看全部表',
+      );
+  }
+  if (matches.length === 1) {
+    const only = matches[0];
+    if (only?.status === 'archived') {
+      throw CliError.usage(
+        `${wanted} 指向的表已归档（${only?.id ?? ''}），归档的表不再接受写入`,
+      )
+        .withDetails({ table: tableBrief(only) })
+        .withHint('去掉 --append 用新名字建一张表，或换一张没归档的表（`table --list --base <BASE_ID>`）');
+    }
+    return only;
+  }
+  throw CliError.usage(
+    `--append 找到 ${matches.length} 张 ${wanted} 的表，CLI 不替你选`,
+  )
+    .withDetails({ candidates: matches.map(tableBrief) })
+    .withHint('用 --key 指明是哪一张（表名可以重复，机器名不行）');
+}
+
+/** 建新表前的"防重"：同名或同 key 的表已经存在。 */
+function findExistingTable(tables, args, tableName) {
+  const key = optionalId(args, '--key');
+  const hit = tables.find(
+    (table) =>
+      (key !== null && table?.key === key) || table?.name === tableName,
+  );
+  return hit ?? null;
+}
+
+/**
+ * 把解析出来的列落到目标表的字段上。
+ *
+ * - 目标表已有这张表（`--append`）：按**显示名**匹配，其次**机器名**；
+ *   命中的列沿用那个字段（键用它的 semantic_key，类型用它的 type），只有新列才建字段；
+ * - 建新表：全部新建。
+ */
+function resolveColumns(parsed, existingFields) {
+  return parsed.columns.map((column) => {
+    let hit = existingFields.find((field) => field?.name === column.name);
+    let matchedBy = hit === undefined ? null : 'name';
+    if (hit === undefined) {
+      hit = existingFields.find((field) => field?.semantic_key === column.semanticKey);
+      matchedBy = hit === undefined ? null : 'semantic_key';
+    }
+    if (hit === undefined) {
+      return {
+        writeKey: column.semanticKey,
+        column,
+        action: 'create',
+        fieldId: null,
+        existingType: null,
+        matchedBy: null,
+      };
+    }
+    const writeKey =
+      typeof hit.semantic_key === 'string' && hit.semantic_key.length > 0
+        ? hit.semantic_key
+        : column.semanticKey;
+    const existingType = typeof hit.type === 'string' ? hit.type : 'text';
+    // 值按**表里那个字段的类型**转；推断类型只在新建字段时才有意义。
+    const columnType = imp.columnTypeFromServer(existingType) ?? imp.ColumnType.Text;
+    return {
+      writeKey,
+      column: {
+        name: column.name,
+        semanticKey: writeKey,
+        columnType,
+        reason: `沿用表里已有的字段（服务端类型 ${existingType}）`,
+        maxScale: column.maxScale,
+        overridden: column.overridden,
+      },
+      action: 'reuse',
+      fieldId: typeof hit.id === 'string' ? hit.id : null,
+      existingType,
+      matchedBy,
+    };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 批次计划与写批
+// ---------------------------------------------------------------------------
+/** 一个批次在计划里的位置。**边界一旦落进 checkpoint 就不再变**。 */
+function planBatches(parsed, columns, file, tableId, fileHash, batchSize, storeColumnIndex) {
+  const out = [];
+  const queue = imp.batchIndices(parsed.rows.length, batchSize);
+  while (queue.length > 0) {
+    const [start, end] = queue.shift();
+    if (end > start + 1) {
+      const storeId = batchStoreId(parsed, storeColumnIndex, start, end);
+      const body = batchBody(parsed, columns, file, out.length, start, end, storeId);
+      if (bodyBytes(body) > MAX_BODY_BYTES) {
+        // 宽表先撞 1MB 的字节上限：按体积二分（服务端只会回一句"请求体过大"）。
+        const mid = start + Math.floor((end - start) / 2);
+        queue.unshift([mid, end]);
+        queue.unshift([start, mid]);
+        continue;
+      }
+    }
+    const index = out.length;
+    out.push({
+      index,
+      start,
+      end,
+      // 幂等键由**文件内容 + 批序号**决定：同一个文件重跑 = 重放，不会写第二遍。
+      idempotencyKey: `import:${fileHash}:${tableId}:${index}`,
+    });
+  }
+  return out;
+}
+
+function bodyBytes(body) {
+  return Buffer.byteLength(JSON.stringify(body), 'utf8');
+}
+
+/**
+ * 一批记录的请求体（真实写入与 dry-run 计划**共用同一段构造**，免得两处漂移）。
+ */
+function batchBody(parsed, columns, file, batchIndex, start, end, storeId) {
+  const records = parsed.rows.slice(start, end).map((row) => ({
+    values: imp.rowValues(columns, row),
+  }));
+  const body = {
+    records,
+    source: `import:${fileNameOf(file)}`,
+    reason: `bitable table --import：${fileNameOf(file)} 第 ${batchIndex + 1} 批（${start}..${end}）`,
+  };
+  if (storeId !== null && storeId !== undefined) body.store_id = storeId;
+  return body;
+}
+
+/**
+ * 门店归属：指定了门店列、且**这一批**的门店一致时，整批落到那个门店。
+ *
+ * 重新算而不是存进 checkpoint：它只由文件内容与这一批的范围决定，
+ * 存下来反而多一处可能与源数据不一致的副本。
+ */
+function batchStoreId(parsed, storeColumnIndex, start, end) {
+  if (storeColumnIndex === null || storeColumnIndex === undefined) return null;
+  const seen = [];
+  for (const row of parsed.rows.slice(start, end)) {
+    const raw = String(row[storeColumnIndex] ?? '').trim();
+    if (raw.length === 0) return null;
+    if (!seen.includes(raw)) seen.push(raw);
+  }
+  return seen.length === 1 ? seen[0] : null;
+}
+
+/**
+ * ⑧ 的实体：并发发批 + 断点续传 + 进度。返回 `[写入行数, 逐批报告]`。
+ *
+ * 为什么并发是安全的：批与批之间**没有顺序依赖** —— 每批自带幂等键、
+ * 自带门店归属、写入是单事务；服务端对同一张表的并发写只是各自加行。
+ * 真正需要串行的只有凭据续期（见循环里的注释）。
+ */
+async function writeBatches(runtime, { args, parsed, columns, file, tableId, fileHash, storeColumnIndex }) {
+  const quiet = runtime.quiet;
+  const batchSize = clamp(importBatchSize(args), 1, imp.MAX_BATCH);
+  const workers = clamp(intFlag(args, '--workers', { fallback: 3 }), 1, MAX_WORKERS);
+  const path = `/tables/${tableId}/records`;
+  const checkpointPath = checkpoint.pathFor(runtime.paths, tableId, fileHash);
+  const planned = planBatches(parsed, columns, file, tableId, fileHash, batchSize, storeColumnIndex);
+
+  // ---- 断点续传：只有"同一个文件 + 同一张表 + 同一套批划分"才敢续 ----
+  let state = checkpoint.newCheckpoint({
+    tableId,
+    fileFingerprint: fileHash,
+    rows: parsed.rows.length,
+    batchSize,
+    batches: planned,
+    updatedAt: nowRfc3339(),
+  });
+  let resumed = false;
+  if (!flagOn(args, '--fresh')) {
+    const existing = checkpoint.load(checkpointPath);
+    if (existing !== null && checkpoint.samePlan(existing, tableId, planned) && checkpoint.doneCount(existing) > 0) {
+      resumed = true;
+      state = existing;
+    } else if (existing !== null && !checkpoint.samePlan(existing, tableId, planned)) {
+      warn(
+        `发现同文件的旧进度（${existing.rows} 行 / ${existing.batches.length} 批），但这次的批划分与它不同` +
+          `（--batch-size ${existing.batch_size} → ${batchSize}）——幂等键跟着批走，续传会重复写入；` +
+          `本次从头开始（旧进度保留在 ${checkpointPath}）`,
+      );
+    }
+  }
+  if (flagOn(args, '--fresh') && checkpoint.exists(checkpointPath)) {
+    checkpoint.remove(checkpointPath);
+  }
+  if (resumed) {
+    if (checkpoint.isComplete(state)) {
+      progress(
+        quiet,
+        `· 这个文件上次已经导完（${state.batches.length} 批 / ${checkpoint.doneRecords(state)} 行）：` +
+          `本次全部走**幂等重放**，不会重复写入。要重新导一遍（比如表被归档后重建）加 --fresh`,
+      );
+    } else {
+      progress(
+        quiet,
+        `· 续传：已完成 ${checkpoint.doneCount(state)}/${state.batches.length} 批` +
+          `（${checkpoint.doneRecords(state)} 行），只补剩余 ${state.batches.length - checkpoint.doneCount(state)} 批`,
+      );
+    }
+  }
+
+  const totalRows = parsed.rows.length;
+  const started = Date.now();
+  let recordsCreated = checkpoint.doneRecords(state);
+  const batchReports = [];
+  const pending = state.batches.filter((batch) => !batch.done).map((batch) => batch.index);
+  const attempts = new Array(state.batches.length).fill(0);
+  let wave = workers;
+
+  while (pending.length > 0) {
+    // 每一波都取一次凭据：**续期只发生在主循环里**（并发刷新会互相吊销，
+    // 服务端把 refresh 当一次性令牌用）。波与波之间共享同一枚 access。
+    await runtime.ensureFreshToken();
+
+    const take = Math.min(wave, pending.length);
+    const indexes = pending.splice(0, take);
+    const settled = await Promise.all(
+      indexes.map(async (index) => {
+        const batch = state.batches[index];
+        const storeId = batchStoreId(parsed, storeColumnIndex, batch.start, batch.end);
+        const spec = requestSpec({
+          body: batchBody(parsed, columns, file, batch.index, batch.start, batch.end, storeId),
+          idempotencyKey: batch.idempotency_key,
+        });
+        try {
+          const response = await runtime.sendAuthed('POST', path, spec);
+          return { index, response };
+        } catch (error) {
+          return { index, error };
+        }
+      }),
+    );
+
+    let softFailure = false;
+    let tokenExpired = false;
+    for (const item of settled) {
+      const { index } = item;
+      if (item.response !== undefined) {
+        const outcome = batchOutcome(state.batches[index], item.response);
+        state.batches[index].done = true;
+        recordsCreated += outcome.created;
+        const batch = state.batches[index];
+        const storeId = batchStoreId(parsed, storeColumnIndex, batch.start, batch.end);
+        // **每批成功就落盘**：checkpoint 的价值在于"进程被 kill 也不丢"，
+        // 攒到最后一起写就等于没有。
+        state.updated_at = nowRfc3339();
+        checkpoint.save(checkpointPath, state);
+        const done = checkpoint.doneCount(state);
+        const doneRows = checkpoint.doneRecords(state);
+        const elapsed = (Date.now() - started) / 1000;
+        const rate = elapsed > 0 ? doneRows / elapsed : 0;
+        progress(
+          quiet,
+          `batch ${done}/${state.batches.length} · ${doneRows}/${totalRows} 行 · elapsed ${elapsed.toFixed(0)}s · ${rate.toFixed(1)} 行/秒`,
+        );
+        batchReports.push({
+          batch: batch.index + 1,
+          range: [batch.start, batch.end],
+          records: outcome.created,
+          store_id: storeId,
+          record_ids: dataOf(item.response)?.record_ids ?? null,
+          request_id: item.response.request_id ?? null,
+          replayed: outcome.replayed,
+        });
+        continue;
+      }
+      const err = item.error;
+      if (err?.code === 'auth.token_expired') {
+        // 下一波开头会重新取凭据；这一批原样重投（幂等键不变）。
+        tokenExpired = true;
+        pending.unshift(index);
+        continue;
+      }
+      if (isPressure(err)) {
+        attempts[index] += 1;
+        if (attempts[index] >= MAX_BATCH_ATTEMPTS) {
+          throw resumeError(err, state, checkpointPath, index, totalRows);
+        }
+        // 服务端在喊"慢一点"：**降并发**，并把这一批放回队头。
+        // 只重试不降并发，等于把限流当网络抖动，会把服务端按得更死。
+        if (wave > 1) {
+          wave -= 1;
+          warn(
+            `服务端压力信号（${err.httpStatus ?? 0} ${err.code}）：并发降到 ${wave}，` +
+              `这一批稍后重投（第 ${attempts[index]}/${MAX_BATCH_ATTEMPTS} 次）`,
+          );
+        }
+        softFailure = true;
+        pending.unshift(index);
+        continue;
+      }
+      throw resumeError(err, state, checkpointPath, index, totalRows);
+    }
+    // 压力过去了就慢慢把并发加回去（一步加一，避免抖动）
+    if (!softFailure && !tokenExpired && wave < workers) wave += 1;
+    if (softFailure) await sleep(500);
+  }
+
+  // 全部完成：删掉 checkpoint（下次重跑是"新的一次导入"，而不是"已完成的续传"）
+  checkpoint.remove(checkpointPath);
+  const elapsed = (Date.now() - started) / 1000;
+  const rate = elapsed > 0 ? recordsCreated / elapsed : 0;
+  progress(
+    quiet,
+    `· 导入完成：${recordsCreated} 行 / ${state.batches.length} 批 · ${elapsed.toFixed(0)}s · ${rate.toFixed(1)} 行/秒（并发 ${workers}）`,
+  );
+  return [recordsCreated, batchReports];
+}
+
+/** 服务端"压力信号"：限流 / 暂不可用。这类失败要降并发重投，不是直接失败。 */
+function isPressure(err) {
+  const status = err?.httpStatus;
+  if ([429, 500, 502, 503, 504].includes(status)) return true;
+  const code = String(err?.code ?? '');
+  return code.startsWith('rate.') || code === 'rate.limited';
+}
+
+/**
+ * 失败收尾：把"已经写到哪了、怎么续"说清楚，而不是只抛一个网络错误。
+ *
+ * 现场教训（2026-09-29）：三次中断各丢掉几千行的工作量，而且**没有任何续传能力**，
+ * 只能靠人工做多重集比对才敢接着导。所以这里必须打印 checkpoint 的绝对路径。
+ */
+function resumeError(err, state, checkpointPath, index, totalRows) {
+  const done = checkpoint.doneCount(state);
+  const doneRows = checkpoint.doneRecords(state);
+  const batch = state.batches[index];
+  const remaining = Math.max(totalRows - doneRows, 0);
+  const error =
+    err instanceof CliError ? err : new CliError(Kind.Server, 'cli.internal', String(err?.message ?? err));
+  return error.withHint(
+    `已写入 ${doneRows} 行（${done}/${state.batches.length} 批）。**直接重跑同一条命令会自动续传**` +
+      `（只补剩余批次，不会写重复）；进度存在 ${checkpointPath}。要重新来过加 --fresh；` +
+      `剩余 ${remaining} 行也可以另存一份 CSV 用 --append --file 续。` +
+      `失败的批是第 ${batch.index + 1} 批（第 ${batch.start}..${batch.end} 行）`,
+  );
+}
+
+function batchOutcome(batch, response) {
+  const data = dataOf(response);
+  const created =
+    typeof data?.created === 'number' && Number.isInteger(data.created) ? data.created : batch.records;
+  const rules = Array.isArray(response?.body?.applied_rules) ? response.body.applied_rules : [];
+  const replayed = rules.some((rule) => rule === 'idempotent_replay');
+  return { created, replayed };
+}
+
+/** `--keep-source`：把原文件传上去并挂到第一条记录上（挂不上也如实说明）。 */
+async function keepSourceAttachment(runtime, args, file, batchReports) {
+  if (!flagOn(args, '--keep-source')) return null;
+  try {
+    const uploaded = await uploadFile(runtime, file, null, null);
+    const attachmentId = typeof uploaded?.id === 'string' ? uploaded.id : '';
+    // 关联到"表"这个资源：服务端本期支持 `record`；
+    // 没有记录可挂时如实说明，不假装挂上了。
+    const first = batchReports[0]?.record_ids;
+    const anchorRecord =
+      Array.isArray(first) && typeof first[0] === 'string' ? first[0] : null;
+    let linkResult = null;
+    let linkNote = null;
+    if (anchorRecord !== null) {
+      try {
+        const response = await runtime.sendAuthed(
+          'POST',
+          `/attachments/${attachmentId}/links`,
+          requestSpec({ body: { resource_type: 'record', resource_id: anchorRecord } }),
+        );
+        linkResult = dataOf(response);
+      } catch (err) {
+        linkNote = `关联失败（${err.code}：${err.message}）—— 附件已上传，可用 attachment --link 重试`;
+      }
+    } else {
+      linkNote = '表里没有记录可挂：附件已上传，可用 attachment --link 挂到别处';
+    }
+    return {
+      attachment: uploaded,
+      linked_to_record: anchorRecord,
+      link: linkResult,
+      note: linkNote,
+    };
+  } catch (err) {
+    warn(`--keep-source 上传失败（${err.code}：${err.message}）：数据已经导进去了，只有原文件没挂上`);
+    return {
+      error: { code: err.code, message: err.message },
+      note: '表与记录已经建好；重跑 attachment --upload 即可补上原文件',
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// `--dry-run` 的完整计划
+// ---------------------------------------------------------------------------
+/**
+ * 拼一份**完整**的导入计划（现场问题：以前只打印"建表"那一个请求，
+ * 分批写记录、字段与推断类型都看不见，等于没法预检）。
+ *
+ * 一条纪律：**不联网**。所以"库/表是否已存在"只能标成"未确认"，
+ * 请求里的 `<base_id>` / `<table_id>` 是占位符。
+ */
+function buildPlan(runtime, ctx) {
+  const baseRef = ctx.target.baseId ?? '<base_id>';
+  const tableRef = ctx.target.tableId ?? '<table_id>';
+  const batches = imp.batchIndices(ctx.parsed.rows.length, ctx.batchSize);
+  const fileHash = imp.fileFingerprint(ctx.parsed);
+  // 追加模式 + dry-run（不联网）：字段的"沿用还是新建"没法确认，
+  // 按最坏情况（都要新建）列出来，并把这句话说清楚。
+  const appendUnconfirmed =
+    ctx.target.tableAction === 'append' && ctx.target.existingFields.length === 0;
+
+  const fields = ctx.columns.map((item) => ({
+    column: item.column.name,
+    semantic_key: item.writeKey,
+    field_id: item.fieldId,
+    type: item.existingType ?? item.column.columnType,
+    action: item.action,
+    reason: item.column.reason,
+    max_scale: item.column.maxScale,
+  }));
+
+  const batchRows = batches.map(([start, end], index) => ({
+    batch: index + 1,
+    range: [start, end],
+    records: end - start,
+  }));
+
+  const requests = [];
+  const push = (kind, entry) => {
+    entry.step = requests.length + 1;
+    entry.kind = kind;
+    requests.push(entry);
+  };
+
+  // 库：只有"可能要建"才列出来（--base 直用时不会建）
+  if (ctx.target.baseAction === 'create' || ctx.target.baseAction === 'find-or-create') {
+    const body = {
+      tenant: '<你的可见企业；--tenant 可指定>',
+      key: '<由库名推导>',
+      name: ctx.target.baseName,
+      description: '由 bitable table --import 自动创建',
+    };
+    const request = runtime.dryRunRequest('POST', '/bases', requestSpec({ body }));
+    push('create_base', {
+      path: '/bases',
+      conditional: ctx.target.baseAction === 'find-or-create',
+      note:
+        ctx.target.baseAction === 'find-or-create'
+          ? '先按名字找；只有找不到才建（dry-run 未确认，实际可能一个请求都不发）'
+          : '库不存在，会新建',
+      request,
+    });
+  }
+  // 表：建 or 追加
+  if (ctx.target.tableAction === 'create') {
+    const body = {
+      key: ctx.target.tableKey,
+      name: ctx.target.tableName,
+      description: `由 ${ctx.file} 导入`,
+      semantic_kind: 'ledger',
+    };
+    const request = runtime.dryRunRequest(
+      'POST',
+      `/bases/${baseRef}/tables`,
+      requestSpec({ body }),
+    );
+    push('create_table', {
+      path: `/bases/${baseRef}/tables`,
+      note: '建一张新表（同名/同 key 的表已存在时，真实运行会报错并提示加 --append）',
+      request,
+    });
+  }
+  // 字段
+  ctx.columns.forEach((item, index) => {
+    if (item.action !== 'create') return;
+    const payload = imp.fieldPayload(item.column, index);
+    const request = runtime.dryRunRequest(
+      'POST',
+      `/tables/${tableRef}/fields`,
+      requestSpec({ body: payload }),
+    );
+    push('create_field', {
+      path: `/tables/${tableRef}/fields`,
+      conditional: appendUnconfirmed,
+      column: item.column.name,
+      semantic_key: item.writeKey,
+      type: item.column.columnType,
+      reason: item.column.reason,
+      request,
+    });
+  });
+  // 记录批次
+  batches.forEach(([start, end], index) => {
+    const storeId = batchStoreId(ctx.parsed, ctx.storeColumnIndex, start, end);
+    const body = batchBody(ctx.parsed, ctx.columns, ctx.file, index, start, end, storeId);
+    const spec = requestSpec({
+      body,
+      idempotencyKey: `import:${fileHash}:${tableRef}:${index}`,
+    });
+    const request = runtime.dryRunRequest('POST', `/tables/${tableRef}/records`, spec);
+    let sample = null;
+    if (Array.isArray(request.body?.records)) {
+      const total = request.body.records.length;
+      sample = request.body.records[0] ?? null;
+      // 200 条 × N 批全量打印没有意义（人只看首条对不对），但**批次一条不少**。
+      request.body.records = request.body.records.slice(0, 1);
+      request.body.records_total = total;
+      request.body.records_omitted = Math.max(total - 1, 0);
+    }
+    push('write_records', {
+      path: `/tables/${tableRef}/records`,
+      batch: index + 1,
+      range: [start, end],
+      records: end - start,
+      store_id: storeId,
+      sample_record: sample,
+      note: 'records 数组只留首条（其余同构）；幂等键 = 文件内容 + 表 id + 批次下标',
+      request,
+    });
+  });
+  // 原文件附件
+  if (ctx.keepSource) {
+    const request = runtime.dryRunRequest(
+      'POST',
+      '/attachments',
+      requestSpec({ multipart: multipartBody([['kind', 'source']], null) }),
+    );
+    push('upload_source', {
+      path: '/attachments',
+      file: ctx.file,
+      note: '--keep-source：上传原文件并挂到第一条记录上',
+      request,
+    });
+  }
+
+  return {
+    source: {
+      file: ctx.file,
+      format: ctx.parsed.sourceFormat,
+      sheet: ctx.parsed.sheetName,
+      rows: ctx.parsed.rows.length,
+      columns: ctx.parsed.columns.length,
+      skipped_empty_rows: ctx.parsed.skippedEmptyRows,
+    },
+    base: {
+      action: ctx.target.baseAction,
+      base_id: ctx.target.baseId,
+      name: ctx.target.baseName,
+      confirmed: ctx.target.baseId !== null,
+    },
+    table: {
+      action: ctx.target.tableAction,
+      table_id: ctx.target.tableId,
+      key: ctx.target.tableKey,
+      name: ctx.target.tableName,
+      confirmed: ctx.target.tableId !== null && ctx.target.tableAction === 'append',
+      note:
+        ctx.target.tableAction === 'append'
+          ? '追加模式：不会建表；真实运行会先按 --key/--name 找已存在的表（找不到就报错，不会新建）'
+          : '新建一张表',
+    },
+    fields,
+    fields_note: appendUnconfirmed
+      ? '追加模式：真实运行会先按显示名 → 机器名匹配目标表已有的字段（命中的沿用、不重建）；dry-run 不联网，这里按"都要新建"列出'
+      : null,
+    fields_to_create: ctx.columns.filter((item) => item.action === 'create').length,
+    fields_to_reuse: ctx.columns.filter((item) => item.action === 'reuse').length,
+    batches: batchRows,
+    records_total: ctx.parsed.rows.length,
+    batch_size: Math.min(ctx.batchSize, imp.MAX_BATCH),
+    store_column: ctx.storeColumn,
+    keep_source: ctx.keepSource,
+    requests_total: requests.length,
+    requests,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 人类可读渲染（`table` / `md` 面；`--json` 的形状一个字都不变）
+// ---------------------------------------------------------------------------
+function stringOf(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  return JSON.stringify(value);
+}
+
+/** 列 → 字段的表格（计划与导入结果共用同一段渲染）。 */
+function fieldsTable(entries, markdown) {
+  const rows = entries.map((field) => [
+    stringOf(field.column),
+    stringOf(field.semantic_key),
+    stringOf(field.type),
+    field.action === 'reuse' ? '沿用' : '新建',
+    stringOf(field.reason),
+  ]);
+  return renderTable(['列名', '机器名', '类型', '动作', '依据'], rows, markdown);
+}
+
+/** 导入结果的人类可读视图：落到哪张表 / 列与类型的映射 / 写了多少条。 */
+function importHuman(out, markdown) {
+  const action = out.appended === true ? '追加到已有表' : '新建表';
+  let text = `${stringOf(out.table_name)}（${action}）：${stringOf(out.records_created)} 条记录\n`;
+  text += renderTable(
+    ['项', '值'],
+    [
+      ['表 id', stringOf(out.table_id)],
+      ['库 id', stringOf(out.base_id)],
+      ['源文件', stringOf(out.source_file)],
+      [
+        '行/批次',
+        `${stringOf(out.rows_in_file)} 行 → ${stringOf(out.records_created)} 条，${stringOf(out.batches)} 批（每批 ≤${stringOf(out.batch_size)}）`,
+      ],
+      ['字段', `新建 ${stringOf(out.fields_created)} / 沿用已有 ${stringOf(out.fields_reused)}`],
+      ['下一步', stringOf(out.next_step)],
+    ],
+    markdown,
+  );
+  const columns = Array.isArray(out.columns) ? out.columns : [];
+  text += `\n\n字段映射（${columns.length} 列）\n`;
+  text += fieldsTable(columns, markdown);
+  const errors = Array.isArray(out.field_errors) ? out.field_errors : [];
+  if (errors.length > 0) {
+    text += `\n注意：有 ${errors.length} 个字段没建成功（见 --json 的 field_errors）\n`;
+  }
+  text += `\n${stringOf(out.note)}\n`;
+  return text.replace(/\s+$/, '');
+}
+
+/** 给人看的计划：文件 / 目标 / 字段与推断类型 / 分批 / 将发的请求。 */
+function planHuman(plan, markdown) {
+  let out = '导入计划（--dry-run：一个请求都不会发，也不会写任何东西）\n';
+  const source = plan.source;
+  const skipped =
+    typeof source.skipped_empty_rows === 'number' && source.skipped_empty_rows > 0
+      ? `；跳过全空行 ${source.skipped_empty_rows}`
+      : '';
+  out += renderTable(
+    ['项', '值'],
+    [
+      [
+        '文件',
+        `${stringOf(source.file)}（${stringOf(source.format)}；${source.rows} 行 × ${source.columns} 列${skipped}）`,
+      ],
+      ['目标库', baseLine(plan.base)],
+      ['目标表', tableLine(plan.table)],
+    ],
+    markdown,
+  );
+  out += '\n';
+
+  const fields = Array.isArray(plan.fields) ? plan.fields : [];
+  out += `字段（${fields.length} 个：新建 ${plan.fields_to_create} / 沿用已有 ${plan.fields_to_reuse})\n`;
+  out += fieldsTable(fields, markdown);
+  if (typeof plan.fields_note === 'string' && plan.fields_note.length > 0) {
+    out += `\n注意：${plan.fields_note}`;
+  }
+  out += '\n';
+
+  const batches = Array.isArray(plan.batches) ? plan.batches : [];
+  out += `记录批次（${batches.length} 批，共 ${plan.records_total} 条）\n`;
+  out += renderTable(
+    ['批次', '区间', '条数'],
+    batches.map((batch) => [
+      stringOf(batch.batch),
+      `${stringOf(batch.range?.[0])}..${stringOf(batch.range?.[1])}`,
+      stringOf(batch.records),
+    ]),
+    markdown,
+  );
+  out += '\n';
+
+  const requests = Array.isArray(plan.requests) ? plan.requests : [];
+  out += `将发送的请求（${requests.length} 个）\n`;
+  const requestRows = requests.map((entry) => {
+    const kind = stringOf(entry.kind);
+    let detail = '';
+    if (kind === 'write_records') {
+      detail = `（${entry.records} 条，第 ${entry.batch} 批，幂等键 ${stringOf(entry.request?.headers?.['Idempotency-Key'])}）`;
+    } else if (kind === 'create_field') {
+      detail = `（${stringOf(entry.column)} → ${stringOf(entry.type)}${entry.conditional === true ? '，追加时缺了才建' : ''}）`;
+    } else if (kind === 'create_base' && entry.conditional === true) {
+      detail = '（按名字找不到才建）';
+    } else if (kind === 'create_table') {
+      detail = `（key=${stringOf(entry.request?.body?.key)}）`;
+    } else if (kind === 'upload_source') {
+      detail = '（--keep-source）';
+    }
+    return [stringOf(entry.step), kindLabel(kind), stringOf(entry.request?.method), `${stringOf(entry.path)}${detail}`];
+  });
+  out += renderTable(['#', '动作', '方法', '路径'], requestRows, markdown);
+  out +=
+    '\n注意：`--dry-run` 不联网 —— 库/表是否已存在未确认；`<base_id>` / `<table_id>` 是占位符，\n' +
+    '真实运行时才由服务端返回。计划里字段的"类型"就是建字段时会用的类型（推断或 --type 覆盖）。';
+  return out;
+}
+
+function baseLine(base) {
+  const name = typeof base.name === 'string' ? base.name : '<未指定>';
+  switch (base.action) {
+    case 'given':
+      return `${stringOf(base.base_id)}（--base 直接指定）`;
+    case 'reuse':
+      return `${name}（已存在，复用 ${stringOf(base.base_id)}）`;
+    case 'create':
+      return `${name}（不存在，会新建）`;
+    default:
+      return `${name}（--base-name：先按名字找，找不到才新建；dry-run 未确认）`;
+  }
+}
+
+function tableLine(table) {
+  const name = stringOf(table.name);
+  if (table.action === 'append') {
+    const suffix =
+      typeof table.table_id === 'string' && table.table_id.length > 0
+        ? `；目标 ${table.table_id}`
+        : '；dry-run 未联网，目标未确认';
+    return `${name}（追加到已存在的表；找不到就报错，不会新建${suffix}）`;
+  }
+  return `${name}（新建；key=${stringOf(table.key)}）`;
+}
+
+function kindLabel(kind) {
+  switch (kind) {
+    case 'create_base':
+      return '建库';
+    case 'create_table':
+      return '建表';
+    case 'create_field':
+      return '建字段';
+    case 'write_records':
+      return '写记录';
+    case 'upload_source':
+      return '传原文件';
+    default:
+      return '追加目标';
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 小工具
+// ---------------------------------------------------------------------------
+/** `--batch-size`：默认 200，落到 1..=500（= 服务端 `row_ops_batch_max`）。 */
+function importBatchSize(args) {
+  return clamp(intFlag(args, '--batch-size', { fallback: 200 }), 1, imp.MAX_BATCH);
+}
+
+function clamp(value, min, max) {
+  const number = Number.isFinite(value) ? value : min;
+  return Math.min(Math.max(number, min), max);
+}
+
+function nowRfc3339() {
+  return new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+}
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    const handle = setTimeout(resolve, ms);
+    if (typeof handle.unref === 'function') handle.unref();
+  });
+}