@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/file.js

@@ -0,0 +1,1474 @@
+// 文件：`file --upload|--show|--download|--versions|--delete|--compare|--lookup|--search`
+// `|--visibility|--move|--acl-list|--acl-revoke|--permission-request|--permission-assign`
+// （FILE-001 / FILE-002 / FILE-003 / FILE-005 / FILE-006，docs/37 §3、
+// docs/issues/FILE-00x §3、docs/31 §2.1.1~§2.1.3）—— 第 17 个顶层域。
+//
+// 文件与附件（`attachment` 域）是**同一个对象**：同一张表、同一条版本链、同一个身份键。
+// 差别只在"入口的语义"：
+//
+// - `file --upload` 走 `POST /files`：`--key` 是**业务主键**（`<type>:<business-id>`，
+//   如 `contract:HT-2026-001`）、`--summary` 必填（摘要由客户端给，平台不做文档智能）；
+//   `--expected-version` 是乐观锁，`0` = 只创建不覆盖。
+// - 其余命令（元数据 / 下载 / 版本 / 删除）复用 `/attachments` 面；`--compare` /
+//   `--lookup` 走 `GET /files/by-key`。
+//
+// 四件事在 CLI 本地判定（退出码 2、**不发请求**，docs/31 §3.2 的判据），
+// 因为它们是"客户端完全能提前知道"的事，而服务端的 422 会被归到退出码 6
+// （`write.validation_failed` + 422 → 服务端错误），直接透传会把"调用方漏了参数"
+// 误导成"服务端故障"：
+//
+// 1. `--upload` 缺 `--file` / `--key` / `--summary`（或给了空白值）、
+//    `--expected-version` 为负；
+// 2. `--compare` 缺 `--file` / `--key`；`--lookup` 缺 `--key`；
+// 3. 高风险动作（`--delete` / `--visibility --set` / `--move`）必须 `--yes`；
+// 4. `--search` 的参数越界（`--limit`、`--since/--until`、单字符查询串、`--match` 枚举）。
+//
+// **上传遇 409 绝不自动重试**：丢 `--expected-version` 再发一次、或改成服务端给的
+// `current_version` 再发一次，都会把"冲突"变成"用本地内容覆盖了别人的版本"。
+// 没有 `--force`。
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+
+import { CliError, Kind, exactlyOne } from '../core/error.js';
+import { flagOn, flagValue, intFlag } from '../core/args.js';
+import { Auth, multipartBody, requestSpec } from '../core/http.js';
+import { dataOf, idempotencyKey, readFileBytes } from '../core/runtime.js';
+import { warn } from '../core/output.js';
+import {
+  FILE_SEARCH_MAX_LIMIT,
+  FILE_SEARCH_MAX_WORKERS,
+  FILE_SEARCH_MIN_QUERY,
+  FILE_VISIBILITY_TIERS,
+  fileNameOf,
+  queryPairs,
+} from '../core/values.js';
+
+/** 一次 `--all` 最多翻到第几行（护栏：别把服务端拖住；与 `record --list` 同源）。 */
+const MAX_SEARCH_OFFSET = 100_000;
+
+/** `file` 一次只能给一个动作时的 hint（与 Rust 的 `exactly_one` 逐字一致）。 */
+const FILE_ACTION_HINT =
+  '例：xinhe-oa-cli file --upload --file ./合同扫描件.pdf --key contract:HT-2026-001 --summary "2026 年度技术服务合同" --tenant kashu';
+
+/**
+ * `file` 的动作分发。
+ *
+ * **先做"恰好一个动作"的判定**，与 Rust 的 clap `ArgGroup(action, multiple=false)` 同义。
+ * 这一步不能省：规格驱动的解析器只对"注册在 `params` 里的布尔动作旗标"查互斥，
+ * 而 `file` 的动作旗标一半来自 `extra_flags`、一半是**带取值的**（`--delete <ID>`），
+ * 于是 `file --download a --delete a` 这种命令行能过解析 —— Rust 会拒（退出码 2、
+ * 不发请求），所以必须在这里补上同一道闸门，否则我们会替调用方"挑一个执行"。
+ *
+ * `--visibility <文件>` 是**带子动作的动作**（Rust 里刻意不在 clap 的 action 组里）：
+ * 真正的动作是 `--show`（读）或 `--set <档位>`（写），两者仍互斥。
+ */
+export async function handleFile({ args, positional, runtime, command }) {
+  const picked = exactlyOne(
+    [
+      ['--upload', flagOn(args, '--upload')],
+      ['--show', args['--show'] !== undefined],
+      ['--download', args['--download'] !== undefined],
+      ['--versions', args['--versions'] !== undefined],
+      ['--delete', args['--delete'] !== undefined],
+      ['--compare', flagOn(args, '--compare')],
+      ['--lookup', flagOn(args, '--lookup')],
+      ['--search', flagOn(args, '--search')],
+      ['--move', args['--move'] !== undefined],
+      ['--acl-list', args['--acl-list'] !== undefined],
+      ['--acl-revoke', args['--acl-revoke'] !== undefined],
+      ['--permission-request', args['--permission-request'] !== undefined],
+      ['--permission-assign', args['--permission-assign'] !== undefined],
+      ['--set', args['--set'] !== undefined],
+    ],
+    'file',
+    FILE_ACTION_HINT,
+  );
+
+  if (args['--visibility'] !== undefined) return visibility(runtime, args);
+  if (picked === '--upload') return upload(runtime, args);
+  if (picked === '--show') return show(runtime, args);
+  if (picked === '--download') return download(runtime, args, positional ?? [], command);
+  if (picked === '--versions') return versions(runtime, args);
+  if (picked === '--delete') return deleteFile(runtime, args);
+  if (picked === '--compare') return compare(runtime, args);
+  if (picked === '--lookup') return lookup(runtime, args);
+  if (picked === '--search') return search(runtime, args);
+  if (picked === '--move') return move(runtime, args);
+  if (picked === '--acl-list') return aclList(runtime, args);
+  if (picked === '--acl-revoke') return aclRevoke(runtime, args);
+  if (picked === '--permission-request') return permissionRequest(runtime, args);
+  if (picked === '--permission-assign') return permissionAssign(runtime, args);
+  // `--set` 只与 `--visibility <文件>` 一起用（单独出现 = 用法错误）。
+  throw CliError.usage('`file` 的 --set 只与 --visibility <文件> 一起用').withHint(
+    '例：xinhe-oa-cli file --visibility contract:HT-2026-001 --set internal --yes --json',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// 共用件：企业解析 + 签名 URL 下载
+//
+// 这两件在 Rust 侧分别住在 `commands/tenant.rs` 与 `commands/attachment.rs`，
+// Node 版把它们放在 `file.js` 里由 attachment / event 两个域 import：
+// 三个域的移植是同一批改动，放在**被依赖方**（file.js 不反向 import 另两个域）
+// 才不会出现 ESM 循环导入。
+// ---------------------------------------------------------------------------
+
+/**
+ * 企业 id：显式 `--tenant` 优先，否则用当前唯一可见企业（那是一次 `GET /me`）。
+ *
+ * 与 Rust `tenant::resolve_tenant` 逐条同义：
+ * - 显式值 trim 后非空 → 直接用，**不发请求**；
+ * - 否则 `GET /me`，从 `data.scope.tenants` 里取：恰好 1 个才自动选；
+ *   0 个 → 调用方给"必须指明企业"的用法错误；多个 → 退出码 2 + `visible_tenants` 明细
+ *   （"你有多个可见企业"是**调用方**要解决的事，不能替它猜）。
+ */
+export async function resolveTenant(runtime, requested, action) {
+  const explicit = requested === null || requested === undefined ? '' : String(requested).trim();
+  if (explicit.length > 0) return explicit;
+  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;
+    if (typeof id === 'string' && id.length > 0) return id;
+    throw tenantUsage(action);
+  }
+  if (tenants.length === 0) throw tenantUsage(action);
+  throw CliError.usage('你有多个可见企业，请用 --tenant <TENANT_ID> 指明').withDetails({
+    visible_tenants: tenants,
+    hint: 'xinhe-oa-cli tenant --list',
+  });
+}
+
+function tenantUsage(action) {
+  return CliError.usage(`${action}必须指明企业`).withHint(
+    '加 --tenant <TENANT_ID>；用 `xinhe-oa-cli tenant --list` 看有哪些企业',
+  );
+}
+
+/**
+ * 取签名 URL → **匿名**下载 → 落盘 + sha256 校验（`attachment --download` 与
+ * `file --download` 共用；Rust 侧同为一段实现：文件与附件是同一条版本链，
+ * 下载语义各写一遍迟早漂移 —— 比如只记得一边补 sha256 删除落地文件）。
+ *
+ * 返回 `{response, data}`；`data` 的键是
+ * `{attachment_id, version, path, bytes, sha256, content_hash_verified, expires_at}`，
+ * 由调用方决定把 `attachment_id` 改名成 `file_id`（file 域的契约键名）。
+ */
+export async function downloadWithSignedUrl(runtime, attachmentId, version, output) {
+  // ① 取签名 URL（这一步带身份：没有读权限会 403）
+  const query = queryPairs([
+    ['version', version === null || version === undefined ? null : String(version)],
+  ]);
+  const urlPath = `/attachments/${attachmentId}/download-url`;
+  const response = await runtime.sendAuthed('POST', urlPath, requestSpec({ query }));
+  const signed = dataOf(response);
+  const url = typeof signed?.url === 'string' ? signed.url : null;
+  if (url === null) {
+    throw new CliError(Kind.Server, 'cli.bad_response', '服务端没有回签名 URL（data.url）');
+  }
+  const expectedHash = typeof signed?.content_hash === 'string' ? signed.content_hash : null;
+  const remoteName = typeof signed?.name === 'string' ? signed.name : 'attachment.bin';
+
+  // ② 用签名 URL **匿名**下载（签名即授权；这里刻意不带 Authorization）
+  const baseUrl = runtime.requireBaseUrl();
+  const relative = url.startsWith(baseUrl) ? url.slice(baseUrl.length) : url;
+  const http = runtime.anonymousHttp();
+  let downloaded;
+  try {
+    downloaded = await http.send('GET', relative, Auth.none(), requestSpec(), 'attachment --download');
+  } catch (err) {
+    if (err instanceof CliError) {
+      // 签名 URL 有效期默认 300 秒：失败时最可能的原因就是它过期了。
+      err.hint = '签名 URL 有效期默认 300 秒：过期就重跑一次这个命令（第 ① 步会换新链接）';
+    }
+    throw err;
+  }
+  // 二进制响应走 `response.raw`（`core/http.js` 对非 JSON 响应把原始字节放这里）。
+  const content = downloaded.raw === null || downloaded.raw === undefined ? Buffer.alloc(0) : downloaded.raw;
+  if (content.length === 0) {
+    throw new CliError(Kind.Server, 'cli.bad_response', '下载到 0 字节（附件没有文件体？）')
+      .withDetails({ attachment_id: attachmentId })
+      .withHint('`attachment --show <id>` 看 storage_backend：none 表示只有元数据、没有文件体');
+  }
+
+  // ③ 落盘 + 校验 sha256（传输坏了要当场发现，而不是让人拿着坏文件干活）
+  const target = resolveOutput(output, remoteName);
+  const parent = path.dirname(target);
+  if (parent.length > 0 && parent !== '.') {
+    try {
+      fs.mkdirSync(parent, { recursive: true });
+    } catch (err) {
+      throw CliError.usage(`建不了目录 ${parent}：${err.message}`);
+    }
+  }
+  try {
+    fs.writeFileSync(target, content);
+  } catch (err) {
+    throw CliError.usage(`写不了 ${target}：${err.message}`);
+  }
+
+  const actualHash = sha256Hex(content);
+  const verified = expectedHash === null ? null : expectedHash === actualHash;
+  if (verified === false) {
+    // 落到盘上的内容与服务端不一致：删掉，别让人拿着坏文件干活。
+    fs.rmSync(target, { force: true });
+    throw new CliError(
+      Kind.Server,
+      'cli.checksum_mismatch',
+      '下载内容与附件不一致（sha256 不符），已删除落地文件',
+    )
+      .withDetails({
+        expected_sha256: expectedHash,
+        actual_sha256: actualHash,
+        attachment_id: attachmentId,
+      })
+      .withHint('重跑一次；若持续不符，把 attachment_id 与 request_id 给运维');
+  }
+
+  return {
+    response,
+    data: {
+      attachment_id: attachmentId,
+      version: signed?.version ?? null,
+      path: target,
+      bytes: content.length,
+      sha256: actualHash,
+      content_hash_verified: verified,
+      expires_at: signed?.expires_at ?? null,
+    },
+  };
+}
+
+/**
+ * `--output` 的解析（与 Rust `attachment::resolve_output` 逐条同义）：
+ * 目录（以 `/` 结尾，或已存在且是目录）就拼远端文件名，否则原样当文件路径。
+ */
+export function resolveOutput(argsOutput, remoteName) {
+  if (argsOutput === null || argsOutput === undefined) return remoteName;
+  const value = String(argsOutput);
+  let isDir = value.endsWith('/');
+  if (!isDir) {
+    try {
+      isDir = fs.statSync(value).isDirectory();
+    } catch {
+      isDir = false;
+    }
+  }
+  return isDir ? path.join(value, remoteName) : value;
+}
+
+// ---------------------------------------------------------------------------
+// `--upload` / `--show` / `--download` / `--versions` / `--delete`
+// ---------------------------------------------------------------------------
+
+/**
+ * `file --upload --file <PATH> --key <KEY> --summary <TEXT> --tenant <TENANT_ID>`。
+ *
+ * 校验顺序照抄 Rust：三件必填 + `--expected-version` 先在**本地**判（一个请求都不发），
+ * 再读文件（读不了也是用法错误），最后才解析企业（那一步才可能联网）。
+ */
+async function upload(runtime, args) {
+  const file = requiredText(
+    flagValue(args, '--file'),
+    '`file --upload` 需要 --file <路径>',
+    '例：xinhe-oa-cli file --upload --file ./合同扫描件.pdf --key contract:HT-2026-001 --summary "2026 年度技术服务合同" --tenant kashu',
+  );
+  const key = requiredText(
+    flagValue(args, '--key'),
+    '`file --upload` 需要 --key <业务主键>',
+    '格式 --key <type>:<business-id>（例：--key contract:HT-2026-001）；类型段是文档类型，不许用部门/可见性等保留字',
+  );
+  const summary = requiredText(
+    flagValue(args, '--summary'),
+    '`file --upload` 需要 --summary <摘要>',
+    '摘要由客户端生成（1..2000 字符），平台不做文档智能；例：--summary "2026 年度技术服务合同，含保密条款"',
+  );
+  const expectedVersion = expectedVersionValue(args);
+
+  const bytes = readFileBytes(file);
+  const uploadName = fileNameOf(file);
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'), '上传文件');
+
+  const fields = [
+    ['tenant', tenant],
+    ['key', key],
+    ['summary', summary],
+  ];
+  // `--name` / `--mime-type` 给了就进表单（空串也是"给了"—— 与 Rust 的
+  // `if let Some(...)` 同义；缺省时显示名由服务端取文件名）。
+  const name = flagValue(args, '--name');
+  if (name !== null) fields.push(['name', name]);
+  const mime = flagValue(args, '--mime-type');
+  if (mime !== null) fields.push(['mime_type', mime]);
+  if (expectedVersion !== null) {
+    // 乐观锁：服务端据此判"我读到的版本有没有被别人改过"（0 = 只创建不覆盖）。
+    fields.push(['expected_version', String(expectedVersion)]);
+  }
+
+  const form = multipartBody(fields, ['file', uploadName, bytes]);
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', '/files', requestSpec({ multipart: form }));
+    return;
+  }
+  // **绝不自动重试**：409 直接向上抛（含 details），由调用方解冲突。
+  const response = await runtime.sendUpload('/files', form, idempotencyKey('file-upload'));
+  runtime.finishFrom(response, {
+    file: dataOf(response),
+    next_step: '挂到记录上：xinhe-oa-cli attachment --link <FILE_ID> --resource-id <RECORD_ID>',
+  });
+}
+
+/** `file --show <FILE_ID>`：元数据 + 版本 + 引用（同一端点，读 `data` 整体）。 */
+async function show(runtime, args) {
+  const reference = fileReference(
+    flagValue(args, '--show'),
+    'file --show',
+    '--show <FILE_ID>',
+    '例：xinhe-oa-cli file --show att_123 --json',
+  );
+  const spec = requestSpec();
+  const requestPath = `/attachments/${reference}`;
+  if (runtime.dryRun) {
+    runtime.dryRunReport('GET', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('GET', requestPath, spec);
+  runtime.finishFrom(response, { file: dataOf(response) });
+}
+
+/** `file --download <FILE_ID> [--version N] [--output <PATH>]`。 */
+async function download(runtime, args, positional, command) {
+  const fileId = String(args['--download'] ?? '');
+  const version =
+    positiveVersionValue(args, '`file --download` 的 --version 必须是正整数') ??
+    versionFromPositional(positional, command);
+  if (runtime.dryRun) {
+    const query = queryPairs([['version', version === null ? null : String(version)]]);
+    runtime.dryRunReport(
+      'POST',
+      `/attachments/${fileId}/download-url`,
+      requestSpec({ query }),
+    );
+    return;
+  }
+  const { response, data } = await downloadWithSignedUrl(
+    runtime,
+    fileId,
+    version,
+    flagValue(args, '--output'),
+  );
+  // 输出键名按 file 域的契约：file_id，不是 attachment_id（同一个对象，两种域叫法）。
+  const renamed = { ...data, file_id: data.attachment_id };
+  delete renamed.attachment_id;
+  runtime.finishFrom(response, renamed);
+}
+
+/**
+ * `--version` 的取值兜底。
+ *
+ * ⚠️ `--version` 同时是**全局旗标**（`xinhe-oa-cli --version`）：core 的
+ * `extractGlobals()` 在挑命令之前就把它摘进 `globals.version`，它后面的取值
+ * （`--version 4` 里的 `4`）于是掉进 `positional`。Rust 侧没有这个问题
+ * （clap 的子命令参数优先于全局 `--version`），实测 `file --download att_1
+ * --version 4` 在 Rust 版发出的是 `?version=4`。
+ *
+ * 所以这里把"唯一的、纯数字的位置参数"认回版本号：不认的话会**静默下载最新版**
+ * （用户以为下的是 v4）—— 那比"多认一种写法"危险得多。core 修好后这条自然失效
+ * （`args['--version']` 有了值，走不到这里）。
+ */
+function versionFromPositional(positional, command) {
+  if (!Array.isArray(positional) || positional.length === 0) return null;
+  const nameWords = String(command?.name ?? '')
+    .split(' ')
+    .filter((word) => word.length > 0 && !word.startsWith('-'));
+  // 命令名自身有时也会出现在 `positional` 里（core 的实现细节），只容忍这一种前缀；
+  // 剩下的恰好一个纯数字 token 才认作被摘走的 `--version` 取值。
+  const head = positional.slice(0, -1);
+  const headIsCommandName =
+    head.length <= nameWords.length && head.every((word, index) => word === nameWords[index]);
+  if (!headIsCommandName) return null;
+  const text = String(positional[positional.length - 1]).trim();
+  if (!/^\d+$/.test(text) || !Number.isSafeInteger(Number.parseInt(text, 10))) return null;
+  const value = Number.parseInt(text, 10);
+  if (value === 0) {
+    throw CliError.usage('`file --download` 的 --version 必须是正整数').withHint(
+      '版本号从 1 开始；不带 --version 就是最新版本',
+    );
+  }
+  return value;
+}
+
+/** `file --versions <FILE_ID>`：版本链（版本号倒序；同一端点的 `data.versions`）。 */
+async function versions(runtime, args) {
+  const fileId = String(args['--versions'] ?? '');
+  const spec = requestSpec();
+  const requestPath = `/attachments/${fileId}`;
+  if (runtime.dryRun) {
+    runtime.dryRunReport('GET', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('GET', requestPath, spec);
+  const detail = dataOf(response);
+  runtime.finishFrom(response, {
+    file_id: fileId,
+    versions: detail?.versions ?? null,
+  });
+}
+
+/** `file --delete <FILE_ID> [--reason <TEXT>]`（高风险：必须 `--yes`）。 */
+async function deleteFile(runtime, args) {
+  const fileId = String(args['--delete'] ?? '');
+  // ⚠️ 这里的 example **带** `--yes`：Rust 传的就是 `… --delete {id} --yes`，
+  // 而 `gate_high_risk` 还会再拼一个 ` --yes`，于是 Rust 实际的 hint 是
+  // `确认后重跑：xinhe-oa-cli file --delete att_1 --yes --yes`。
+  // 看着别扭，但"行为等价"优先：hint 在 `--json` 的 error 段里，判卷会比。
+  runtime.requireYes('file --delete', `xinhe-oa-cli file --delete ${fileId} --yes`);
+  const spec = requestSpec({ query: queryPairs([['reason', flagValue(args, '--reason')]]) });
+  const requestPath = `/attachments/${fileId}`;
+  if (runtime.dryRun) {
+    runtime.dryRunReport('DELETE', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('DELETE', requestPath, spec);
+  const body = dataOf(response);
+  // 两个分支（本次删除 / already_deleted）对外都是同一形状：软删完成。
+  runtime.finishFrom(response, {
+    file_id: typeof body?.attachment_id === 'string' ? body.attachment_id : fileId,
+    status: 'deleted',
+    deleted_at: body?.deleted_at ?? null,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// FILE-005：可见性 / 移动 / 显式 ACL（docs/31 §2.1.2）
+// ---------------------------------------------------------------------------
+// 三个写动作（`--set` / `--move` / `--acl-revoke`）由 CLI **自动生成幂等键**：
+// 网络抖动后重跑同一条命令不会重复作废 ACL、不会重复写审计。
+// 文件引用一律走 `<file>` 段：`att_...` id 或业务 `key`（`<type>:<business-id>`）
+// 都能收，CLI 原样拼进路径（服务端对两种形状做同一件事）。
+
+/** `file --visibility <file> --show|--set <档位>` 的子动作分发。 */
+async function visibility(runtime, args) {
+  const reference = fileReference(
+    flagValue(args, '--visibility'),
+    'file --visibility',
+    '文件 <FILE_ID|KEY>',
+    '例：xinhe-oa-cli file --visibility contract:HT-2026-001 --show --json',
+  );
+  // 到这里 `handleFile` 已经保证"14 个动作旗标里恰好一个"，而 `--visibility` 在场时
+  // 那个动作只可能是 `--show`（裸旗标）或 `--set <档位>`；`--set` 优先认。
+  if (args['--set'] !== undefined) {
+    return visibilitySet(runtime, args, reference, String(args['--set']));
+  }
+  if (args['--show'] !== true) {
+    // `--visibility <文件> --show <值>`：把两种用法混在了一起（Rust 由 clap 在语法层拒）。
+    throw CliError.usage(
+      '`file --visibility <文件> --show` 的 --show 不接受值（文件写在 --visibility 后面）',
+    ).withHint('例：xinhe-oa-cli file --visibility contract:HT-2026-001 --show --json');
+  }
+  return visibilityShow(runtime, args, reference);
+}
+
+/** `GET /files/{id_or_key}/visibility`（read）：声明档位 + 夹紧后的有效档位 + ACL。 */
+async function visibilityShow(runtime, args, reference) {
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'), '查看文件可见性');
+  const requestPath = `/files/${reference}/visibility`;
+  const spec = requestSpec({ query: [['tenant', tenant]] });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('GET', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('GET', requestPath, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/**
+ * `POST /files/{id_or_key}/visibility`：**高风险写**（一次可能放开或收掉一批人）。
+ *
+ * 顺序照抄 Rust：先本地校验档位（`public` 本地就拒）、再 `--yes` 闸门、
+ * 最后才解析企业 —— 没确认过的命令一个请求都不许发。
+ */
+async function visibilitySet(runtime, args, reference, rawTier) {
+  const tier = validatedTier(rawTier);
+  runtime.requireYes(
+    'file --visibility --set（一次可能放开一批人或收掉一批人）',
+    `xinhe-oa-cli file --visibility ${reference} --set ${tier}`,
+  );
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'), '改文件可见性');
+  const body = { visibility: tier };
+  // `--dept` / `--expected-epoch` 只在给的时候进 body：不传 = 不校验（服务端向后兼容）。
+  const dept = trimmedOrNull(flagValue(args, '--dept'));
+  if (dept !== null) body.dept_id = dept;
+  const epoch = expectedEpochValue(args);
+  if (epoch !== null) body.expected_epoch = epoch;
+  const requestPath = `/files/${reference}/visibility`;
+  const spec = requestSpec({
+    body,
+    query: [['tenant', tenant]],
+    idempotencyKey: idempotencyKey('file-visibility'),
+  });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('POST', requestPath, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/**
+ * `file --move <file> --to-dept <ou_id> --yes`：**高风险写**（换归属部门会夹紧档位
+ * 并作废越出容器的 ACL）。成功响应（`visibility_after` / `revoked_acl` /
+ * `affected_users` / `inherit_epoch`）原样透传，CLI 不做二次加工 ——
+ * 操作者要当场看见代价。
+ */
+async function move(runtime, args) {
+  const reference = fileReference(
+    flagValue(args, '--move'),
+    'file --move',
+    '--move <FILE_ID|KEY>',
+    '例：xinhe-oa-cli file --move contract:HT-2026-001 --to-dept ou_legal --yes --json',
+  );
+  const toDept = fileReference(
+    flagValue(args, '--to-dept'),
+    'file --move',
+    '--to-dept <OU_ID>',
+    '例：xinhe-oa-cli file --move contract:HT-2026-001 --to-dept ou_legal --yes --json',
+  );
+  const epoch = expectedEpochValue(args);
+  runtime.requireYes(
+    'file --move（换归属部门会夹紧档位并作废越出容器的 ACL）',
+    `xinhe-oa-cli file --move ${reference} --to-dept ${toDept}`,
+  );
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'), '移动文件');
+  const body = { to_dept_id: toDept };
+  if (epoch !== null) body.expected_epoch = epoch;
+  const requestPath = `/files/${reference}/move`;
+  const spec = requestSpec({
+    body,
+    query: [['tenant', tenant]],
+    idempotencyKey: idempotencyKey('file-move'),
+  });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('POST', requestPath, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `file --acl-list <file>`（read）：显式 ACL（点名到人 / 点名到部门）。 */
+async function aclList(runtime, args) {
+  const reference = fileReference(
+    flagValue(args, '--acl-list'),
+    'file --acl-list',
+    '--acl-list <FILE_ID|KEY>',
+    '例：xinhe-oa-cli file --acl-list contract:HT-2026-001 --json',
+  );
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'), '列出文件 ACL');
+  const requestPath = `/files/${reference}/acl`;
+  const spec = requestSpec({ query: [['tenant', tenant]] });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('GET', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('GET', requestPath, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/**
+ * `file --acl-revoke <file> --from-user <user_id>|--from-dept <ou_id> --action read|write`：
+ * **write**（降险动作，故意不卡 `--yes` —— "发现给错了、赶紧收回"不该变慢）。
+ */
+async function aclRevoke(runtime, args) {
+  const reference = fileReference(
+    flagValue(args, '--acl-revoke'),
+    'file --acl-revoke',
+    '--acl-revoke <FILE_ID|KEY>',
+    '例：xinhe-oa-cli file --acl-revoke contract:HT-2026-001 --from-user usr_wang --action read --json',
+  );
+  const subject = aclSubject(
+    args,
+    'file --acl-revoke',
+    '--from-user',
+    '--from-dept',
+    '点名到人：--from-user usr_xxx；点名到部门：--from-dept ou_xxx',
+    '例：xinhe-oa-cli file --acl-revoke contract:HT-2026-001 --from-user usr_wang --action read --json',
+  );
+  const action = aclAction(flagValue(args, '--action'), 'file --acl-revoke');
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'), '收回文件 ACL');
+  // 服务端的模型是 `{from_user | from_dept, action}`（多态主体在**线上**用两个可选键表达）。
+  const body = subject.dept
+    ? { from_dept: subject.id, action }
+    : { from_user: subject.id, action };
+  const requestPath = `/files/${reference}/acl/revoke`;
+  const spec = requestSpec({
+    body,
+    query: [['tenant', tenant]],
+    idempotencyKey: idempotencyKey('file-acl-revoke'),
+  });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('POST', requestPath, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+// ---------------------------------------------------------------------------
+// FILE-006：`--permission-request` / `--permission-assign`（docs/31 §2.1.3）
+// ---------------------------------------------------------------------------
+// 申请走 `base.approval` 的 `file_permission`：只创建审批、`acl_written: false`，
+// **批准之前什么权限都不会发生**；分配是所有者/管理员的**直接写**（不经审批）。
+// 两条都是 `write`（不是 high-risk），都由 CLI 自动生成幂等键。
+
+/** `file --permission-request <file> --action read|write [--reason] [--expires-at]`。 */
+async function permissionRequest(runtime, args) {
+  const reference = fileReference(
+    flagValue(args, '--permission-request'),
+    'file --permission-request',
+    '--permission-request <FILE_ID|KEY>',
+    '例：xinhe-oa-cli file --permission-request contract:HT-2026-001 --action read --reason "对账需要" --json',
+  );
+  if (hasAssignSubject(args)) {
+    throw CliError.usage(
+      '`file --permission-request` 不接受 --to-user / --to-dept：申请交给谁由审批人定',
+    ).withHint(
+      '直接分配（不经审批）用：xinhe-oa-cli file --permission-assign <FILE_ID|KEY> --to-user usr_... | --to-dept ou_... --action read --json',
+    );
+  }
+  const action = aclAction(flagValue(args, '--action'), 'file --permission-request');
+  const body = { action };
+  const reason = trimmedOrNull(flagValue(args, '--reason'));
+  if (reason !== null) body.reason = reason;
+  const expiresAt = expiresAtValue(args);
+  if (expiresAt !== null) body.expires_at = expiresAt;
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'), '申请文件权限');
+  const requestPath = `/files/${reference}/permission-request`;
+  const spec = requestSpec({
+    body,
+    query: [['tenant', tenant]],
+    idempotencyKey: idempotencyKey('file-permission-request'),
+  });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('POST', requestPath, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+/** `file --permission-assign <file> --to-user|--to-dept --action read|write [...]`。 */
+async function permissionAssign(runtime, args) {
+  const reference = fileReference(
+    flagValue(args, '--permission-assign'),
+    'file --permission-assign',
+    '--permission-assign <FILE_ID|KEY>',
+    '例：xinhe-oa-cli file --permission-assign contract:HT-2026-001 --to-user usr_wang --action read --json',
+  );
+  const subject = aclSubject(
+    args,
+    'file --permission-assign',
+    '--to-user',
+    '--to-dept',
+    '--to-user usr_... | --to-dept ou_...',
+    '--to-user usr_... | --to-dept ou_...',
+  );
+  const action = aclAction(flagValue(args, '--action'), 'file --permission-assign');
+  const body = subject.dept
+    ? { to_dept: subject.id, action }
+    : { to_user: subject.id, action };
+  const reason = trimmedOrNull(flagValue(args, '--reason'));
+  if (reason !== null) body.reason = reason;
+  const expiresAt = expiresAtValue(args);
+  if (expiresAt !== null) body.expires_at = expiresAt;
+  // 两道墙由服务端判：授出 ⊆ 持有、不得突破文件有效可见性上限；CLI 只保证参数本地合法。
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'), '分配文件权限');
+  const requestPath = `/files/${reference}/permission-assign`;
+  const spec = requestSpec({
+    body,
+    query: [['tenant', tenant]],
+    idempotencyKey: idempotencyKey('file-permission-assign'),
+  });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', requestPath, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('POST', requestPath, spec);
+  runtime.finishFrom(response, dataOf(response));
+}
+
+// ---------------------------------------------------------------------------
+// FILE-003：`file --compare` / `file --lookup`
+// ---------------------------------------------------------------------------
+
+/**
+ * `file --compare --tenant <T> --key <K> --file <PATH> [--base-version N]`：
+ * **只读预检**，不发任何写请求。
+ *
+ * 为什么 `behind` 归退出码 **5**（而不是 2 或 6）：它**不是参数错** —— 退出码 2 的
+ * 判据写死了"CLI 本地判定、**不发请求**"，而这个判决只可能从一次**已经发生的**读
+ * （`GET /files/by-key`）里长出来；它也**不是服务端 5xx** —— 服务端一切正常。
+ * 这份结果与文件**当时**的状态冲突，重跑一次/解冲突后重提就能拿到一致的结果，
+ * 与 `cli.paging_unstable`、`cli.skill_conflict` 同一类（契约 §3.2 的两条补充）。
+ */
+async function compare(runtime, args) {
+  const file = requiredText(
+    flagValue(args, '--file'),
+    '`file --compare` 需要 --file <本地文件>',
+    '例：xinhe-oa-cli file --compare --file ./合同修订版.pdf --key contract:HT-2026-001 --base-version 3',
+  );
+  const key = requiredText(
+    flagValue(args, '--key'),
+    '`file --compare` 需要 --key <业务主键>',
+    '例：--key contract:HT-2026-001（与要上传的 --key 一致）',
+  );
+  const baseVersion = baseVersionValue(args);
+  const bytes = readFileBytes(file);
+  const localSha256 = sha256Hex(bytes);
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'), '文件比对');
+  const spec = requestSpec({
+    query: [
+      ['tenant', tenant],
+      ['key', key],
+    ],
+  });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('GET', '/files/by-key', spec);
+    return;
+  }
+  // 404（`attachment.not_found`）= 服务端没有这个 key（absent）；其余错误原样抛出，绝不猜。
+  let response = null;
+  try {
+    response = await runtime.sendAuthed('GET', '/files/by-key', spec);
+  } catch (err) {
+    if (err instanceof CliError && err.code === 'attachment.not_found') response = null;
+    else throw err;
+  }
+  const remote = response === null ? null : dataOf(response);
+  const verdict = compareVerdict(localSha256, remote, baseVersion);
+  if (verdict === 'behind') {
+    // 只有一个请求（GET /files/by-key），且**没有任何 POST**。
+    throw behindError(key, localSha256, file, baseVersion, remote);
+  }
+  runtime.finishFrom(response, {
+    verdict,
+    key,
+    local: { base_version: baseVersion, sha256: localSha256, path: file },
+    remote: remote === null ? null : remoteSummary(remote),
+    how_to_resolve: howToResolve(verdict),
+  });
+}
+
+/** `file --lookup --tenant <T> --key <K>`：按业务主键取文件（与 `--show` 同形）。 */
+async function lookup(runtime, args) {
+  const key = requiredText(
+    flagValue(args, '--key'),
+    '`file --lookup` 需要 --key <业务主键>',
+    '例：xinhe-oa-cli file --lookup --key contract:HT-2026-001 --tenant kashu --json',
+  );
+  const tenant = await resolveTenant(runtime, flagValue(args, '--tenant'), '按主键取文件');
+  const spec = requestSpec({
+    query: [
+      ['tenant', tenant],
+      ['key', key],
+    ],
+  });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('GET', '/files/by-key', spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('GET', '/files/by-key', spec);
+  runtime.finishFrom(response, { file: dataOf(response) });
+}
+
+/**
+ * 本地文件哈希 vs 服务端当前状态（纯函数）。
+ *
+ * **哈希相同优先报 `same`** —— 即使 `--base-version` 落后，内容一样就没有冲突可解。
+ * 判据只认版本号，不认时间戳。
+ */
+export function compareVerdict(localSha256, remote, baseVersion) {
+  if (remote === null || remote === undefined) return 'absent';
+  const remoteHash = typeof remote.content_hash === 'string' ? remote.content_hash : '';
+  if (remoteHash === localSha256) return 'same';
+  if (baseVersion === null) return 'unknown';
+  const remoteVersion = Number.isInteger(remote.version) && remote.version >= 0 ? remote.version : 0;
+  // `N == remote.version` → ahead；`N > remote.version`（本地自认更新，服务端不这么认为）
+  // 同样算 ahead；只有 `N < remote.version` 才是 behind。
+  return baseVersion >= remoteVersion ? 'ahead' : 'behind';
+}
+
+/** `--compare` 的下一步提示（`how_to_resolve`；第一条永远是"别自动覆盖"）。 */
+function howToResolve(verdict) {
+  if (verdict === 'behind') {
+    return [
+      '先 `file --download <remote.id> --version <remote.version>` 拿服务端最新版',
+      '在本地合并后，用刚拿到的版本号重新提交：--expected-version <remote.version>',
+      '合并不了就交给人工决定，**不要**用 --upload 覆盖别人的版本',
+    ];
+  }
+  if (verdict === 'absent') return ['直接 --upload（会创建 v1）'];
+  if (verdict === 'same') return ['不要传：内容与服务端一致，上传也只会得到 no_change'];
+  return ['直接提交并接受可能的 409（--expected-version 会再判一次）'];
+}
+
+/** `remote` 的展示形状（与 409 `details.current` 同源：版本 / 哈希 / 上传人 / 时间）。 */
+function remoteSummary(remote) {
+  return {
+    id: remote?.id ?? null,
+    version: remote?.version ?? null,
+    content_hash: remote?.content_hash ?? null,
+    size_bytes: remote?.size_bytes ?? null,
+    created_by: remote?.created_by ?? null,
+    created_at: remote?.created_at ?? null,
+    name: remote?.name ?? null,
+  };
+}
+
+/**
+ * Behind（冲突）的失败形状：`cli.file_conflict` + 冻结的 `details`。
+ *
+ * 必须**显式构造 `Kind.Conflict`**：`error.js` 的 `classify()` 不认 `cli.*` 码，
+ * 归 5 的判据与 `cli.paging_unstable` 同一类。`details` 是机器面（解冲突的输入），
+ * `human` 是给人看的同一件事（两份各自稳定）。
+ */
+function behindError(key, localSha256, filePath, baseVersion, remote) {
+  const summary = remoteSummary(remote);
+  const details = {
+    key,
+    local: { base_version: baseVersion, sha256: localSha256, path: filePath },
+    remote: summary,
+    how_to_resolve: howToResolve('behind'),
+  };
+  const human =
+    `本地文件落后于服务端：key=${key} base_version=${optionDebug(baseVersion)} ` +
+    `remote_version=${jsonDisplay(summary.version)}\n` +
+    `解冲突：先 \`file --download ${typeof summary.id === 'string' ? summary.id : '<id>'} ` +
+    `--version ${jsonDisplay(summary.version)}\`，合并后用 ` +
+    `--expected-version ${jsonDisplay(summary.version)} 重新提交`;
+  return new CliError(
+    Kind.Conflict,
+    'cli.file_conflict',
+    `文件 ${key} 已被别人更新，本地文件基于的版本已落后`,
+  )
+    .withDetails(details)
+    .withHumanDetails(human);
+}
+
+// ---------------------------------------------------------------------------
+// FILE-002：`file --search`（三个维度 + 服务端匹配 + `--all` 翻页自检）
+// ---------------------------------------------------------------------------
+
+/**
+ * `file --search --tenant <T> [--name] [--summary] [--match] [--since/--until]
+ * [--include-deleted] [--limit] [--offset] [--all] [--workers]`。
+ *
+ * **只定位、不取链接**：输出永不含 `storage_ref`，也不发签名 URL ——
+ * 取链接走 `file --download`（那里才是"谁拿了下载链接"的独立审计点）。
+ */
+async function search(runtime, args) {
+  const plan = validateSearch(args);
+  // fuzzy 对短中文串的告警在**企业检查之前**：告警讲的是"这个检索大概率搜不到"，
+  // 与后面成不成功无关（Rust 同序）。`--quiet` 静音，但**不拒绝**。
+  const warning = fuzzyWarningMessage(plan, runtime.quiet);
+  if (warning !== null) warn(warning);
+
+  // `--tenant` 必填：没有"搜我所有企业"的形态（本地判、不发请求）。
+  const tenantRaw = flagValue(args, '--tenant');
+  const tenant = tenantRaw === null ? '' : String(tenantRaw).trim();
+  if (tenant.length === 0) {
+    throw CliError.usage('`file --search` 必须指明 --tenant <TENANT_ID>').withHint(
+      '检索只在自己可见的企业内做，没有跨企业全局检索',
+    );
+  }
+
+  if (runtime.dryRun) {
+    runtime.dryRunReport(
+      'GET',
+      '/files',
+      requestSpec({ query: searchQuery(plan, tenant, plan.offset) }),
+    );
+    return;
+  }
+
+  if (!plan.all) {
+    const response = await fetchSearchPage(runtime, plan, tenant, plan.offset);
+    // 服务端的 `data` 就是契约形状（files/total/count/limit/offset/has_more/
+    // next_offset/order/match），原样透传。
+    runtime.finishFrom(response, dataOf(response));
+    return;
+  }
+
+  const start = plan.offset;
+  const collected = [];
+  let lastResponse = null;
+  let reachedEnd = false;
+  let total = null;
+
+  // 第一页永远串行：既拿 `total`（并发翻页要用它算页数），也顺带确认这条路走得通。
+  {
+    const response = await fetchSearchPage(runtime, plan, tenant, start);
+    const data = dataOf(response);
+    const files = searchPageFiles(data);
+    total = unsignedOrNull(data?.total);
+    collected.push(...files);
+    lastResponse = response;
+    reachedEnd = files.length < plan.limit;
+  }
+
+  if (!reachedEnd) {
+    const coveredToEnd = total !== null && start + collected.length >= total;
+    if (coveredToEnd) {
+      reachedEnd = true;
+    } else if (plan.workers > 1 && total !== null) {
+      // 并发取页的前提是知道总行数；页与页彼此独立，结果按 offset 排序后拼接。
+      const count = total;
+      const offsets = [];
+      let next = start + plan.limit;
+      while (next < count) {
+        if (next > MAX_SEARCH_OFFSET) break;
+        offsets.push(next);
+        next += plan.limit;
+      }
+      if (offsets.length === 0) {
+        reachedEnd = true;
+      } else {
+        const covered = offsets[offsets.length - 1] + plan.limit >= count;
+        const pages = await fetchSearchPages(runtime, plan, tenant, offsets, plan.workers);
+        for (const response of pages) {
+          const data = dataOf(response);
+          collected.push(...searchPageFiles(data));
+          lastResponse = response;
+        }
+        reachedEnd = covered;
+      }
+    } else {
+      let offset = start + plan.limit;
+      for (;;) {
+        if (offset > MAX_SEARCH_OFFSET) {
+          warn(`翻页超过 10 万条，停下（避免把服务端拖住）；要接着搜：--offset ${offset}`);
+          break;
+        }
+        const response = await fetchSearchPage(runtime, plan, tenant, offset);
+        const data = dataOf(response);
+        const files = searchPageFiles(data);
+        const hasMore =
+          typeof data?.has_more === 'boolean' ? data.has_more : files.length >= plan.limit;
+        collected.push(...files);
+        lastResponse = response;
+        if (!hasMore || files.length < plan.limit) {
+          reachedEnd = true;
+          break;
+        }
+        offset += plan.limit;
+      }
+    }
+  }
+
+  // 完整性自检：`--all` 号称"搜全了"，那就得真的是全的 —— 宁可让调用方重跑一次，
+  // 也不要把"看着像全量"的半份数据交出去。
+  const integrity = searchPagingIntegrity(collected, total, start, reachedEnd);
+  const integrityError = searchIntegrityError(integrity, plan, tenant);
+  if (integrityError !== null) throw integrityError;
+
+  const count = collected.length;
+  const out = {
+    files: collected,
+    total,
+    count,
+    limit: plan.limit,
+    offset: start,
+    has_more: !reachedEnd,
+    next_offset: reachedEnd ? null : start + count,
+    order: 'created_at:desc,id:desc',
+    match: plan.matchMode,
+  };
+  if (lastResponse === null) runtime.finish(out);
+  else runtime.finishFrom(lastResponse, out);
+}
+
+/**
+ * `--search` 的本地校验与解析：参数越界一律退出码 2、**不发请求**。
+ *
+ * 拦四类本地可判的错：`--limit` 越界、`--name`/`--summary` 空白或单字符、
+ * `--since` 晚于 `--until`、`--match` 不在枚举内。服务端的 422 是给非 CLI
+ * 调用方的兜底 —— 直接透传会被归到退出码 6，误导成服务端故障。
+ */
+export function validateSearch(args) {
+  const limit = intFlag(args, '--limit', { fallback: 20 });
+  if (limit < 1 || limit > FILE_SEARCH_MAX_LIMIT) {
+    throw CliError.usage(
+      `\`file --search\` 的 --limit 必须在 1..=${FILE_SEARCH_MAX_LIMIT}（服务端上限 ${FILE_SEARCH_MAX_LIMIT}），收到 ${limit}`,
+    ).withHint('文件行比记录行重（summary 上限 2000 字符），所以上限比 record --list 小；翻全量用 --all');
+  }
+  const matchRaw = trimmedOrNull(flagValue(args, '--match'));
+  let matchMode = 'substring';
+  if (matchRaw !== null) {
+    const lowered = matchRaw.toLowerCase();
+    if (lowered !== 'substring' && lowered !== 'fuzzy') {
+      throw CliError.usage(
+        `\`file --search\` 的 --match 只支持 substring|fuzzy，收到 ${JSON.stringify(matchRaw)}`,
+      ).withHint('substring（默认，子串匹配）或 fuzzy（pg_trgm 相似度 ≥ 0.3）');
+    }
+    matchMode = lowered;
+  }
+  const name = searchTerm(flagValue(args, '--name'), '--name');
+  const summary = searchTerm(flagValue(args, '--summary'), '--summary');
+  const since = trimmedOrNull(flagValue(args, '--since'));
+  const until = trimmedOrNull(flagValue(args, '--until'));
+  // **只在两端都给时才解析**（与 Rust 同序）：只给一端时原样发给服务端，
+  // 由它去解释 —— 客户端不替服务端判"这个时间写法对不对"。
+  if (since !== null && until !== null) {
+    const startAt = parseSearchTime(since, '--since', false);
+    const endAt = parseSearchTime(until, '--until', true);
+    if (startAt > endAt) {
+      throw CliError.usage('`file --search` 的 --since 晚于 --until（空区间）').withHint(
+        '闭区间要求 since <= until；`--until YYYY-MM-DD` 含当天 23:59:59Z',
+      );
+    }
+  }
+  const offset = intFlag(args, '--offset', { fallback: 0, min: 0 });
+  const workers = intFlag(args, '--workers', { fallback: 1 });
+  return {
+    name,
+    summary,
+    matchMode,
+    since,
+    until,
+    includeDeleted: flagOn(args, '--include-deleted'),
+    limit,
+    offset,
+    all: flagOn(args, '--all'),
+    // 与 Rust 的 `.clamp(1, 16)` 同义：越界的 workers 是"夹紧"而不是"拒绝"。
+    workers: Math.min(Math.max(workers, 1), FILE_SEARCH_MAX_WORKERS),
+  };
+}
+
+/** 一个检索维度：空白（给了等于没给）与单字符都在本地拒（退出码 2）。 */
+function searchTerm(raw, flag) {
+  if (raw === null || raw === undefined) return null;
+  const trimmed = String(raw).trim();
+  if (trimmed.length === 0) {
+    throw CliError.usage(`\`file --search\` 的 ${flag} 不能为空`).withHint(
+      '不给就是不按这个维度筛；要搜就给至少 2 个字符',
+    );
+  }
+  if (Array.from(trimmed).length < FILE_SEARCH_MIN_QUERY) {
+    throw CliError.usage(
+      `\`file --search\` 的 ${flag} 至少需要 ${FILE_SEARCH_MIN_QUERY} 个字符：少于 3 个字符生成不出 trigram，\`ILIKE\` 会退化成全表扫描`,
+    ).withHint('中文双字词（如「合同」）就够；单字请配合别的维度缩小范围');
+  }
+  return trimmed;
+}
+
+const DAY_PATTERN = /^(\d{4})-(\d{2})-(\d{2})$/;
+/** RFC3339：**必须带时区**（本地时间本地拒 —— 服务端要的是绝对时刻）。 */
+const RFC3339_PATTERN = /^\d{4}-\d{2}-\d{2}[Tt ]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+
+/**
+ * `--since` / `--until` 的时间解析（只用于本地比较先后）。
+ *
+ * `YYYY-MM-DD`：起点补 00:00:00Z、终点补 23:59:59Z（**闭区间**，含当天末尾）。
+ * 其余按 RFC3339 解析（必须带时区；解析不了是本地退出码 2）。
+ */
+function parseSearchTime(raw, flag, end) {
+  const day = DAY_PATTERN.exec(raw);
+  if (day !== null) {
+    const year = Number(day[1]);
+    const month = Number(day[2]);
+    const date = Number(day[3]);
+    // 格式对但日期不存在（2026-02-30）也要拒：Rust 的 NaiveDate 同样拒。
+    if (month < 1 || month > 12 || date < 1 || date > daysInMonth(year, month)) {
+      throw searchTimeError(flag, raw);
+    }
+    const millis = Date.UTC(
+      year,
+      month - 1,
+      date,
+      end ? 23 : 0,
+      end ? 59 : 0,
+      end ? 59 : 0,
+    );
+    return millis;
+  }
+  if (RFC3339_PATTERN.test(raw)) {
+    const millis = Date.parse(raw);
+    if (!Number.isNaN(millis)) return millis;
+  }
+  throw searchTimeError(flag, raw);
+}
+
+function searchTimeError(flag, raw) {
+  return CliError.usage(`\`file --search\` 的 ${flag} 不是合法时间：${JSON.stringify(raw)}`).withHint(
+    '接受 ISO8601（2026-08-01T00:00:00Z）或 YYYY-MM-DD（2026-08-01）',
+  );
+}
+
+function daysInMonth(year, month) {
+  const lengths = [
+    31,
+    (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0 ? 29 : 28,
+    31,
+    30,
+    31,
+    30,
+    31,
+    31,
+    30,
+    31,
+    30,
+    31,
+  ];
+  return lengths[month - 1];
+}
+
+function isCjk(ch) {
+  const code = ch.codePointAt(0);
+  return (
+    (code >= 0x3400 && code <= 0x4dbf) ||
+    (code >= 0x4e00 && code <= 0x9fff) ||
+    (code >= 0xf900 && code <= 0xfaff)
+  );
+}
+
+/**
+ * `--match fuzzy` 对"全中文且 < 4 字"的查询串几乎不会命中（trigram 相似度远低于 0.3）。
+ *
+ * **告警而不是拒绝**：拒绝会让跨语言关键词（`HT-2026-001`）被误伤 ——
+ * fuzzy 的用武之地正是拉丁字母 / 编号 / 拼写错误。
+ */
+export function fuzzyShortCjkWarning(plan) {
+  if (plan.matchMode !== 'fuzzy') return null;
+  const terms = [plan.name, plan.summary].filter((term) => term !== null);
+  const short = terms.find(
+    (term) => Array.from(term).length < 4 && Array.from(term).every(isCjk),
+  );
+  if (short === undefined) return null;
+  return (
+    `fuzzy 对短中文串几乎不会命中（similarity(${JSON.stringify(short)}, …) 远低于 0.3），` +
+    '建议用默认的 --match substring'
+  );
+}
+
+/** 该不该把 fuzzy 告警打到 stderr（`--quiet` 下静音）。 */
+export function fuzzyWarningMessage(plan, quiet) {
+  if (quiet) return null;
+  return fuzzyShortCjkWarning(plan);
+}
+
+/** 检索的查询参数（单页 / 串行 / 并发共用同一段，避免三条路径漂移）。 */
+function searchQuery(plan, tenant, offset) {
+  const query = [
+    ['tenant', tenant],
+    ['limit', String(plan.limit)],
+    ['offset', String(offset)],
+    ['match', plan.matchMode],
+  ];
+  if (plan.name !== null) query.push(['name', plan.name]);
+  if (plan.summary !== null) query.push(['summary', plan.summary]);
+  if (plan.since !== null) query.push(['since', plan.since]);
+  if (plan.until !== null) query.push(['until', plan.until]);
+  if (plan.includeDeleted) query.push(['include_deleted', 'true']);
+  return query;
+}
+
+/** 取检索的一页（`GET /files`）。 */
+function fetchSearchPage(runtime, plan, tenant, offset) {
+  return runtime.sendAuthed(
+    'GET',
+    '/files',
+    requestSpec({ query: searchQuery(plan, tenant, offset) }),
+  );
+}
+
+/**
+ * 并发取多页（`--all --workers N`）：页与页彼此独立，一次发一批。
+ *
+ * 并发前先续期一次凭据（续期是"读改写"的一次性令牌，不能并发做）；
+ * 同一波里按 offset 排序后拼接 —— 结果与串行翻页逐行一致。
+ */
+async function fetchSearchPages(runtime, plan, tenant, offsets, workers) {
+  await runtime.ensureFreshToken();
+  const out = [];
+  const queue = [...offsets];
+  while (queue.length > 0) {
+    const take = Math.min(workers, queue.length);
+    const batch = queue.splice(0, take);
+    const settled = await Promise.all(
+      batch.map(async (offset) => ({
+        offset,
+        response: await fetchSearchPage(runtime, plan, tenant, offset),
+      })),
+    );
+    settled.sort((left, right) => left.offset - right.offset);
+    for (const item of settled) out.push(item.response);
+  }
+  return out;
+}
+
+/** 一页里的 `files` 数组：**缺键 = 契约错误**（退出码 6），绝不静默当空数组。 */
+export function searchPageFiles(data) {
+  if (data !== null && typeof data === 'object' && Array.isArray(data.files)) return data.files;
+  const keys =
+    data !== null && typeof data === 'object' && !Array.isArray(data) ? Object.keys(data).sort() : [];
+  throw new CliError(
+    Kind.Server,
+    'cli.contract',
+    'GET /files 的响应里没有 `files` 数组 —— 客户端与服务端的响应形状对不上',
+  )
+    .withDetails({ expected_keys: ['files'], response_keys: keys })
+    .withHint('先升级客户端：xinhe-oa-cli doctor --upgrade；仍复现就把 response_keys 报上来');
+}
+
+/** `--all` 到底取回了什么（纯函数，便于单测）。 */
+export function searchPagingIntegrity(rows, total, startOffset, reachedEnd) {
+  const fetched = rows.length;
+  // 只按 `id` 去重：`id` 是主键，"两条文件同一个 id"就是服务端把同一行发了两遍。
+  const ids = [];
+  for (const row of rows) {
+    if (row !== null && typeof row === 'object' && typeof row.id === 'string') ids.push(row.id);
+  }
+  const withoutId = fetched - ids.length;
+  const unique = new Set(ids).size + withoutId;
+  const duplicates = Math.max(0, fetched - unique);
+  const expected = total === null ? null : Math.max(0, total - startOffset);
+  const missing =
+    expected !== null && reachedEnd ? Math.max(0, expected - unique) : 0;
+  return {
+    fetched,
+    unique,
+    duplicates,
+    expected,
+    missing,
+    reachedEnd,
+    consistent: duplicates === 0 && missing === 0,
+  };
+}
+
+/**
+ * 完整性不过关时把"残缺结果"变成一条**错误**（退出码 5、`cli.paging_unstable`）。
+ *
+ * 与 `cli.file_conflict` 同一条判据：它只可能从一次**已经发生的**读里长出来，
+ * 不是参数错（2），也不是服务端 5xx（6）—— 重跑一次就能拿到一致的结果。
+ */
+export function searchIntegrityError(integrity, plan, tenant) {
+  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({
+      tenant,
+      name: plan.name,
+      summary: plan.summary,
+      match: plan.matchMode,
+      limit: plan.limit,
+      fetched: integrity.fetched,
+      unique: integrity.unique,
+      duplicates: integrity.duplicates,
+      expected: integrity.expected,
+      missing: integrity.missing,
+      reached_end: integrity.reachedEnd,
+    })
+    .withHint(
+      '重跑一次（多半是翻页期间有人上传了新文件）；要一致的结果就缩小时间窗 / 只看一页走 next_offset',
+    );
+}
+
+// ---------------------------------------------------------------------------
+// 取值解析（本地校验；全部退出码 2、不发请求）
+// ---------------------------------------------------------------------------
+
+/** 必填文本：缺失或全空白 → 用法错误（`what` / `hint` 与 Rust 逐字一致）。 */
+function requiredText(raw, what, hint) {
+  const value = raw === null || raw === undefined ? '' : String(raw).trim();
+  if (value.length === 0) throw CliError.usage(what).withHint(hint);
+  return value;
+}
+
+/** 文件引用：`att_...` id 或业务 `key`；空白 = 没给（退出码 2、不发请求）。 */
+function fileReference(raw, action, what, example) {
+  const value = raw === null || raw === undefined ? '' : String(raw).trim();
+  if (value.length === 0) throw CliError.usage(`\`${action}\` 需要 ${what}`).withHint(example);
+  return value;
+}
+
+function trimmedOrNull(raw) {
+  if (raw === null || raw === undefined) return null;
+  const value = String(raw).trim();
+  return value.length === 0 ? null : value;
+}
+
+/**
+ * `--expected-version`：非负整数（`0` = 只创建不覆盖）。
+ *
+ * 负数在本地就判死（FILE-003 §2.5）：负数是客户端完全能提前知道的事，
+ * 而服务端的 422 只是给非 CLI 调用方的兜底。
+ */
+function expectedVersionValue(args) {
+  const raw = flagValue(args, '--expected-version');
+  if (raw === null) return null;
+  const text = String(raw).trim();
+  if (!/^-?\d+$/.test(text) || !Number.isSafeInteger(Number.parseInt(text, 10))) {
+    throw CliError.usage(`\`file --upload\` 的 --expected-version 要一个整数，收到 ${JSON.stringify(text)}`).withHint(
+      '0 = 只创建不覆盖；不给 = 不比对版本；要基于已有版本提交就写它的版本号',
+    );
+  }
+  const value = Number.parseInt(text, 10);
+  if (value < 0) {
+    throw CliError.usage('`file --upload` 的 --expected-version 不能为负').withHint(
+      '0 = 只创建不覆盖；不给 = 不比对版本；要基于已有版本提交就写它的版本号',
+    );
+  }
+  return value;
+}
+
+/** `--base-version`：非负整数（服务端是 u64，负数在 clap 层就解析不出）。 */
+function baseVersionValue(args) {
+  const raw = flagValue(args, '--base-version');
+  if (raw === null) return null;
+  const text = String(raw).trim();
+  if (!/^\d+$/.test(text) || !Number.isSafeInteger(Number.parseInt(text, 10))) {
+    throw CliError.usage(`\`file --compare\` 的 --base-version 要一个非负整数，收到 ${JSON.stringify(text)}`).withHint(
+      '不给 = 只比内容、不判先后；要判先后就写本地文件基于的版本号',
+    );
+  }
+  return Number.parseInt(text, 10);
+}
+
+/** `--download --version`：正整数（版本号从 1 开始）。 */
+function positiveVersionValue(args, message) {
+  const raw = flagValue(args, '--version');
+  if (raw === null) return null;
+  const text = String(raw).trim();
+  if (!/^\d+$/.test(text) || !Number.isSafeInteger(Number.parseInt(text, 10))) {
+    throw CliError.usage(message).withHint('版本号从 1 开始；不带 --version 就是最新版本');
+  }
+  const value = Number.parseInt(text, 10);
+  if (value === 0) {
+    throw CliError.usage(message).withHint('版本号从 1 开始；不带 --version 就是最新版本');
+  }
+  return value;
+}
+
+/**
+ * `--expected-epoch`（`--set` / `--move`）：非负整数。
+ *
+ * 服务端的 `inherit_epoch` 从 1 起，`0` 只可能来自陈旧的客户端；负数 / 非数字
+ * 都是本地退出码 2、不发请求。**不要丢掉它自动重试** —— 那等于用旧状态覆盖
+ * 别人刚做的修改。
+ */
+function expectedEpochValue(args) {
+  const raw = flagValue(args, '--expected-epoch');
+  if (raw === null) return null;
+  const text = String(raw).trim();
+  const value = /^\d+$/.test(text) ? Number.parseInt(text, 10) : Number.NaN;
+  if (!Number.isSafeInteger(value)) {
+    throw CliError.usage(
+      `\`file --expected-epoch\` 只能是非负整数（inherit_epoch 从 1 起），收到 ${JSON.stringify(text)}`,
+    ).withHint('先 `xinhe-oa-cli file --visibility <文件> --show --json` 拿最新 inherit_epoch，再原样传回来');
+  }
+  return value;
+}
+
+/**
+ * 可见性档位：只有 `private|dept|internal`。
+ *
+ * `public` **本地就拒**（退出码 2、不发请求）：档位定义保留（决策 65），但写入
+ * 一律被拒（服务端 400 `file.visibility_not_available`）—— 让用户跑一趟网络
+ * 换回一个 400，不如在本地把"本期没有对外分享入口"直接说清楚。
+ */
+function validatedTier(raw) {
+  const text = String(raw ?? '').trim();
+  const lowered = text.toLowerCase();
+  if (lowered === 'public') {
+    throw CliError.usage('`file --visibility --set` 不支持 public：本期没有对外链接分享入口').withHint(
+      '档位只能是 private|dept|internal；服务端对 public 回 400 file.visibility_not_available',
+    );
+  }
+  if (!FILE_VISIBILITY_TIERS.includes(lowered)) {
+    throw CliError.usage(
+      `\`file --visibility --set\` 的档位只能是 private|dept|internal，收到 ${JSON.stringify(text)}`,
+    ).withHint('private（默认；只有所有者 + 点名 ACL）| dept（归属部门子树）| internal（本企业在职成员）');
+  }
+  return lowered;
+}
+
+/**
+ * `--from-user` / `--to-user`（user）与 `--from-dept` / `--to-dept`（dept）恰好一个。
+ *
+ * 两个 `hint` 由调用方给：Rust 侧 `acl_subject` 与 `assign_subject` 的措辞不同
+ * （前者点名到人/部门，后者给的是可照抄的两种写法），这里逐字照抄，不合并。
+ */
+function aclSubject(args, action, userFlag, deptFlag, conflictHint, missingHint) {
+  const user = trimmedOrNull(flagValue(args, userFlag));
+  const dept = trimmedOrNull(flagValue(args, deptFlag));
+  if (user !== null && dept !== null) {
+    throw CliError.usage(`\`${action}\` 的 ${userFlag} 与 ${deptFlag} 只能给一个`).withHint(
+      conflictHint,
+    );
+  }
+  if (user !== null) return { dept: false, id: user };
+  if (dept !== null) return { dept: true, id: dept };
+  throw CliError.usage(`\`${action}\` 需要 ${userFlag} <USER_ID> 或 ${deptFlag} <OU_ID>`).withHint(
+    missingHint,
+  );
+}
+
+/** `--action`：只认 `read|write`（文件 ACL 的 ALL_ACTIONS 冻结，下载 = read）。 */
+function aclAction(raw, what) {
+  const text = String(raw ?? '').trim().toLowerCase();
+  if (text !== 'read' && text !== 'write') {
+    throw CliError.usage(`\`${what}\` 的 --action 只支持 read|write，收到 ${JSON.stringify(String(raw ?? '').trim())}`).withHint(
+      '文件 ACL 只有 read / write 两个动作（下载 = read）',
+    );
+  }
+  return text;
+}
+
+/** `--permission-request` 要拒掉 `--to-user` / `--to-dept`（申请交给谁由审批人定）。 */
+function hasAssignSubject(args) {
+  return (
+    trimmedOrNull(flagValue(args, '--to-user')) !== null ||
+    trimmedOrNull(flagValue(args, '--to-dept')) !== null
+  );
+}
+
+/** `--expires-at`：必须是**带时区**的 RFC3339（服务端要绝对时刻；本地时间本地拒）。 */
+function expiresAtValue(args) {
+  const raw = trimmedOrNull(flagValue(args, '--expires-at'));
+  if (raw === null) return null;
+  if (!RFC3339_PATTERN.test(raw)) {
+    throw CliError.usage(
+      `\`file --permission-*\` 的 --expires-at 必须是带时区的 RFC3339，收到 ${JSON.stringify(raw)}`,
+    ).withHint('例：--expires-at 2026-12-31T23:59:59+08:00（不带时区的本地时间会被拒）');
+  }
+  return raw;
+}
+
+/** u64 形状的字段：非整数 / 负数一律当"没有"（对齐 serde_json 的 `as_u64`）。 */
+function unsignedOrNull(value) {
+  return Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+/** Rust `Option<u64>` 的 `{:?}` 展示（`Some(3)` / `None`）。 */
+function optionDebug(value) {
+  return value === null ? 'None' : `Some(${value})`;
+}
+
+/** serde_json `Value` 的 Display：字符串带引号，其余与 JSON 一致。 */
+function jsonDisplay(value) {
+  return typeof value === 'string' ? JSON.stringify(value) : JSON.stringify(value ?? null);
+}
+
+function sha256Hex(bytes) {
+  return createHash('sha256').update(bytes).digest('hex');
+}