@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/core/xlsx.js

@@ -0,0 +1,321 @@
+// 最小 XLSX 读取器：只用 `node:zlib` 的 `inflateRawSync` 解 zip，自己解 XML。
+//
+// 为什么自己写而不是装 `xlsx` / `exceljs`：这个 CLI 要**零运行时依赖**地装进客户机器
+// （`cli-node/package.json` 的 dependencies 是空的）。一个 xlsx 库带进来的是几十个包、
+// 几十兆体积与一条供应链，而我们真正需要的只有三样东西：
+//
+//   1. `xl/sharedStrings.xml` —— 字符串单元格的真实取值（`t="s"` 的单元格只存下标）；
+//   2. `xl/workbook.xml` + `xl/_rels/workbook.xml.rels` —— 工作表名与它的 XML 路径
+//      （**默认读第一个工作表**，`--sheet` 按名精确匹配）；
+//   3. `xl/styles.xml` 的 `cellXfs` —— 每个样式用的 `numFmtId`，用来判断
+//      "这个数字单元格是不是日期"（Excel 的日期就是序列号 + 日期格式）。
+//
+// 日期按 Rust 版 `excel_serial_to_date` 的口径转（序列号 1 = 1900-01-01、
+// 跳过 Excel 的 1900 假闰日 60、`>=60` 减 1），见 `core/import.js` —— 转换放在那边，
+// 这里只负责把"这个单元格是日期格式"这个事实带出去。
+
+import fs from 'node:fs';
+import zlib from 'node:zlib';
+
+import { CliError } from './error.js';
+import { rustIoErrorText } from './util.js';
+
+// ---------------------------------------------------------------------------
+// zip（只读：中央目录 → 本地头 → inflateRaw）
+// ---------------------------------------------------------------------------
+const EOCD_SIG = 0x06054b50;
+const CENTRAL_SIG = 0x02014b50;
+const LOCAL_SIG = 0x04034b50;
+
+/**
+ * 读 zip 里的若干条目。
+ *
+ * @returns {Map<string, Buffer>} 文件名 → 解压后的字节
+ */
+function readZipEntries(bytes, wanted) {
+  const eocd = findEocd(bytes);
+  if (eocd < 0) throw CliError.usage('这不是一个 zip（xlsx 就是 zip）：找不到中央目录');
+  const total = bytes.readUInt16LE(eocd + 10);
+  let offset = bytes.readUInt32LE(eocd + 16);
+  const out = new Map();
+  for (let index = 0; index < total; index += 1) {
+    if (offset + 46 > bytes.length || bytes.readUInt32LE(offset) !== CENTRAL_SIG) break;
+    const method = bytes.readUInt16LE(offset + 10);
+    const compressedSize = bytes.readUInt32LE(offset + 20);
+    const nameLength = bytes.readUInt16LE(offset + 28);
+    const extraLength = bytes.readUInt16LE(offset + 30);
+    const commentLength = bytes.readUInt16LE(offset + 32);
+    const localOffset = bytes.readUInt32LE(offset + 42);
+    const name = bytes.toString('utf8', offset + 46, offset + 46 + nameLength);
+    offset += 46 + nameLength + extraLength + commentLength;
+    if (wanted !== null && !wanted.has(name)) continue;
+    if (compressedSize === 0xffffffff || localOffset === 0xffffffff) {
+      throw CliError.usage('这个 xlsx 用了 ZIP64（超大文件），本期读不了');
+    }
+    if (bytes.readUInt32LE(localOffset) !== LOCAL_SIG) {
+      throw CliError.usage('xlsx 的 zip 结构坏了：本地文件头签名不对');
+    }
+    const localNameLength = bytes.readUInt16LE(localOffset + 26);
+    const localExtraLength = bytes.readUInt16LE(localOffset + 28);
+    const start = localOffset + 30 + localNameLength + localExtraLength;
+    const raw = bytes.subarray(start, start + compressedSize);
+    if (method === 0) out.set(name, Buffer.from(raw));
+    else if (method === 8) {
+      try {
+        out.set(name, zlib.inflateRawSync(raw));
+      } catch (err) {
+        throw CliError.usage(`解不开 xlsx 里的 ${name}：${err.message}`);
+      }
+    } else {
+      throw CliError.usage(`xlsx 用了不支持的压缩方式 ${method}（${name}）`);
+    }
+  }
+  return out;
+}
+
+/** 从尾部往回找 EOCD（注释最长 64KB，所以只搜最后 64KB+22 字节）。 */
+function findEocd(bytes) {
+  const from = Math.max(0, bytes.length - (0xffff + 22));
+  for (let index = bytes.length - 22; index >= from; index -= 1) {
+    if (bytes.readUInt32LE(index) === EOCD_SIG) return index;
+  }
+  return -1;
+}
+
+// ---------------------------------------------------------------------------
+// XML（够用就好的抽取：这些文件的结构由 Excel 生成，形状稳定）
+// ---------------------------------------------------------------------------
+function decodeXmlText(text) {
+  return String(text)
+    .replace(/&#x([0-9a-fA-F]+);/g, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (_, digits) => String.fromCodePoint(Number.parseInt(digits, 10)))
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&apos;/g, "'")
+    .replace(/&amp;/g, '&');
+}
+
+/** 取一个标签的属性（没有就是 null）。 */
+function attr(tagText, name) {
+  const match = new RegExp(`\\s${name}\\s*=\\s*"([^"]*)"`).exec(tagText);
+  return match === null ? null : decodeXmlText(match[1]);
+}
+
+/** 取 `<tag ...>...</tag>` 的正文（非贪婪；这些文件里嵌套同名标签不存在）。 */
+function bodyOf(xml, tag) {
+  const match = new RegExp(`<${tag}(?:\\s[^>]*)?>([\\s\\S]*?)</${tag}>`).exec(xml);
+  return match === null ? null : match[1];
+}
+
+// ---------------------------------------------------------------------------
+// 三个部件
+// ---------------------------------------------------------------------------
+/** 共享字符串表：`<si>` 里可能有多段 `<t>`（富文本），拼起来才是完整取值。 */
+function parseSharedStrings(xml) {
+  const out = [];
+  const items = xml.match(/<si(?:\s[^>]*)?>[\s\S]*?<\/si>|<si\s*\/>/g) ?? [];
+  for (const item of items) {
+    const texts = item.match(/<t(?:\s[^>]*)?>[\s\S]*?<\/t>|<t\s*\/>/g) ?? [];
+    out.push(texts.map((piece) => decodeXmlText(piece.replace(/^<t(?:\s[^>]*)?>|<\/t>$/g, ''))).join(''));
+  }
+  return out;
+}
+
+/** 样式：`cellXfs` 里第 i 个 `<xf>` 的 `numFmtId`（单元格的 `s="i"` 指向它）。 */
+function parseStyles(xml) {
+  const custom = new Map();
+  const numFmts = bodyOf(xml, 'numFmts');
+  if (numFmts !== null) {
+    for (const tag of numFmts.match(/<numFmt\s[^>]*\/?>/g) ?? []) {
+      const id = attr(tag, 'numFmtId');
+      const code = attr(tag, 'formatCode');
+      if (id !== null && code !== null) custom.set(Number(id), code);
+    }
+  }
+  const xfsBody = bodyOf(xml, 'cellXfs');
+  const numFmtIds = [];
+  if (xfsBody !== null) {
+    for (const tag of xfsBody.match(/<xf\s[^>]*?\/?>|<xf\s[^>]*?>/g) ?? []) {
+      const id = attr(tag, 'numFmtId');
+      numFmtIds.push(id === null ? 0 : Number(id));
+    }
+  }
+  return { numFmtIds, custom };
+}
+
+/**
+ * 内置日期格式 id（ECMA-376 §18.8.30）。
+ *
+ * 14–22 是标准里的日期/时间格式；27–36 与 50–58 是 CJK 区域的日期格式
+ * （Excel 中文版把 `yyyy/m/d` 之类落在这些 id 上 —— 只认 14–22 会把
+ * 中文环境导出的日期列全部当数字）。45–47 是时间/时长。
+ */
+const BUILTIN_DATE_FORMATS = new Set([
+  14, 15, 16, 17, 18, 19, 20, 21, 22, 27, 28, 29, 30, 31, 32, 33, 34, 35, 36, 45, 46, 47, 50, 51,
+  52, 53, 54, 55, 56, 57, 58,
+]);
+
+/** 自定义格式里只要出现未被引号包住的 y/m/d/h/s，就当日期（`0.00` 这类不是）。 */
+function looksLikeDateFormat(code) {
+  const stripped = String(code ?? '')
+    .replace(/"[^"]*"/g, '')
+    .replace(/\[[^\]]*\]/g, '')
+    .replace(/\\./g, '');
+  return /[ymdhs]/i.test(stripped);
+}
+
+function isDateStyle(styles, styleIndex) {
+  if (styleIndex === null || styleIndex === undefined) return false;
+  const numFmtId = styles.numFmtIds[styleIndex];
+  if (numFmtId === undefined) return false;
+  if (BUILTIN_DATE_FORMATS.has(numFmtId)) return true;
+  const code = styles.custom.get(numFmtId);
+  return code === undefined ? false : looksLikeDateFormat(code);
+}
+
+/** `xl/workbook.xml` + rels：按声明顺序给出 `[{name, target}]`。 */
+function parseSheets(workbookXml, relsXml, entryNames) {
+  const body = bodyOf(workbookXml, 'sheets') ?? workbookXml;
+  const sheets = [];
+  for (const tag of body.match(/<sheet\s[^>]*\/?>/g) ?? []) {
+    const name = attr(tag, 'name');
+    const relId = attr(tag, 'r:id') ?? attr(tag, 'id');
+    let target = null;
+    if (relsXml !== null && relId !== null) {
+      for (const rel of relsXml.match(/<Relationship\s[^>]*\/?>/g) ?? []) {
+        if (attr(rel, 'Id') === relId) {
+          target = attr(rel, 'Target');
+          break;
+        }
+      }
+    }
+    if (target === null) {
+      // 关系文件缺失/对不上时的兜底：按 sheet 的出现顺序猜 `sheetN.xml`。
+      const guess = `xl/worksheets/sheet${sheets.length + 1}.xml`;
+      target = entryNames.has(guess) ? guess : null;
+    } else {
+      target = target.replace(/^\//, '').replace(/^xl\//, 'xl/');
+      if (!target.startsWith('xl/')) target = `xl/${target}`;
+      if (!entryNames.has(target)) target = null;
+    }
+    sheets.push({ name: name ?? `Sheet${sheets.length + 1}`, target });
+  }
+  return sheets;
+}
+
+/** 列引用 `BC12` → 列下标（0 起）。 */
+function columnOf(reference) {
+  const letters = /^([A-Z]+)/.exec(String(reference ?? ''))?.[1] ?? '';
+  let index = 0;
+  for (const ch of letters) index = index * 26 + (ch.charCodeAt(0) - 64);
+  return index - 1;
+}
+
+/** 单元格取值 → 字符串（**与 Rust 的 `cell_to_string` 同一口径**）。 */
+function cellToString(cell, sharedStrings, styles, formatFloat, serialToDate) {
+  const type = attr(cell, 't');
+  const styleIndexRaw = attr(cell, 's');
+  const styleIndex = styleIndexRaw === null ? null : Number(styleIndexRaw);
+  const valueBody = bodyOf(cell, 'v');
+  const value = valueBody === null ? null : decodeXmlText(valueBody);
+
+  if (type === 'inlineStr') {
+    const inline = bodyOf(cell, 'is');
+    const texts = inline === null ? [] : inline.match(/<t(?:\s[^>]*)?>[\s\S]*?<\/t>|<t\s*\/>/g) ?? [];
+    return texts.map((piece) => decodeXmlText(piece.replace(/^<t(?:\s[^>]*)?>|<\/t>$/g, ''))).join('').trim();
+  }
+  if (type === 's') {
+    if (value === null) return '';
+    const text = sharedStrings[Number(value)];
+    return text === undefined ? '' : text.trim();
+  }
+  if (type === 'str') return value === null ? '' : value.trim();
+  if (type === 'b') return value === '1' ? 'true' : 'false';
+  if (type === 'e') return `#错误(${value ?? ''})`;
+  if (type === 'd') return value === null ? '' : value; // ISO 日期（少见的写法）
+  if (value === null || value === '') return '';
+  const number = Number(value);
+  if (!Number.isFinite(number)) return value;
+  if (isDateStyle(styles, styleIndex)) {
+    const date = serialToDate(number);
+    if (date !== null) return date;
+  }
+  return formatFloat(number);
+}
+
+/** 读一个工作表 → 行 × 列的字符串网格（缺的格子是空串）。 */
+function parseWorksheet(xml, sharedStrings, styles, helpers) {
+  const rows = [];
+  const sheetData = bodyOf(xml, 'sheetData');
+  if (sheetData === null) return rows;
+  for (const rowTag of sheetData.match(/<row(?:\s[^>]*)?>[\s\S]*?<\/row>|<row\s[^>]*\/>/g) ?? []) {
+    const cells = [];
+    for (const cellTag of rowTag.match(/<c(?:\s[^>]*)?>[\s\S]*?<\/c>|<c\s[^>]*\/>/g) ?? []) {
+      const at = columnOf(attr(cellTag, 'r'));
+      const text = cellToString(cellTag, sharedStrings, styles, helpers.formatFloat, helpers.serialToDate);
+      if (at < 0) cells.push(text);
+      else cells[at] = text;
+    }
+    for (let index = 0; index < cells.length; index += 1) {
+      if (cells[index] === undefined) cells[index] = '';
+    }
+    rows.push(cells);
+  }
+  return rows;
+}
+
+// ---------------------------------------------------------------------------
+// 对外入口
+// ---------------------------------------------------------------------------
+/**
+ * 读 xlsx：默认第一个工作表，`sheet` 按名精确匹配。
+ *
+ * @param {string} file
+ * @param {string|null} sheet
+ * @param {{formatFloat: (n:number)=>string, serialToDate: (n:number)=>string|null}} helpers
+ *   数值/日期的渲染由 `core/import.js` 提供 —— 那里才是有 Rust 口径注释的地方。
+ * @returns {{sheetName: string, grid: string[][]}}
+ */
+export function readXlsx(file, sheet, helpers) {
+  let bytes;
+  try {
+    bytes = fs.readFileSync(file);
+  } catch (err) {
+    throw CliError.usage(`打不开 xlsx ${file}：${rustIoErrorText(err)}`);
+  }
+  // 一次把要用的部件都解出来（内部条目名固定）。
+  const entries = readZipEntries(bytes, null);
+  const names = new Set(entries.keys());
+  const workbookXml = entries.get('xl/workbook.xml')?.toString('utf8') ?? null;
+  if (workbookXml === null) {
+    throw CliError.usage(`打不开 xlsx ${file}：压缩包里没有 xl/workbook.xml`);
+  }
+  const relsXml = entries.get('xl/_rels/workbook.xml.rels')?.toString('utf8') ?? null;
+  const sheets = parseSheets(workbookXml, relsXml, names);
+  if (sheets.length === 0) throw CliError.usage(`xlsx ${file} 里一个工作表都没有`);
+  let chosen;
+  if (sheet === null || sheet === undefined) {
+    [chosen] = sheets;
+  } else {
+    chosen = sheets.find((item) => item.name === sheet) ?? null;
+    if (chosen === null) {
+      throw CliError.usage(`xlsx 里没有工作表 ${JSON.stringify(sheet)}`).withDetails({
+        sheets: sheets.map((item) => item.name),
+      });
+    }
+  }
+  if (chosen.target === null) {
+    throw CliError.usage(`读不了工作表 ${JSON.stringify(chosen.name)}：找不到它的 XML`);
+  }
+  const sheetXml = entries.get(chosen.target)?.toString('utf8') ?? null;
+  if (sheetXml === null) {
+    throw CliError.usage(`读不了工作表 ${JSON.stringify(chosen.name)}：${chosen.target} 不在压缩包里`);
+  }
+  const sharedStrings = parseSharedStrings(
+    entries.get('xl/sharedStrings.xml')?.toString('utf8') ?? '',
+  );
+  const styles = parseStyles(entries.get('xl/styles.xml')?.toString('utf8') ?? '');
+  const grid = parseWorksheet(sheetXml, sharedStrings, styles, helpers);
+  return { sheetName: chosen.name, grid };
+}

package/src/main.js

@@ -0,0 +1,205 @@
+// CLI 入口：解析 → 建运行时 → 分发 → **退出码统一收口**（契约 §3.2）。
+//
+// 退出码是判卷与脚本读的第一样东西，所以它只在这里算一次：
+//   0 成功 · 2 用法 · 3 未登录 · 4 权限 · 5 冲突 · 6 服务端 · 7 网络 · 8 版本过旧。
+
+import { CliError, EXIT_OK, EXIT_SERVER, Kind } from './core/error.js';
+import { parseArgv, commandSurface } from './core/args.js';
+import { Runtime } from './core/runtime.js';
+import { Format, Meta, parseFormat, renderFailure } from './core/output.js';
+import { commandLabel, handlerFor } from './commands/index.js';
+import { VERSION } from './version.js';
+
+const ABOUT = '心河 OA 客户端：多维表格 / 应用 / 权限的唯一命令行入口';
+
+/**
+ * 跑一次 CLI。
+ *
+ * @param {string[]} argv 不含 `node` 与脚本名的参数
+ * @returns {Promise<number>} 退出码
+ */
+export async function runCli(argv) {
+  let parsed = null;
+  let format = Format.Table;
+  try {
+    parsed = parseArgv(argv);
+    format = parsed.globals.format
+      ? parseFormat(parsed.globals.format)
+      : parsed.globals.json
+        ? Format.Json
+        : Format.Table;
+  } catch (err) {
+    // 连 `--json` 都没解析出来时的兜底：`--format json` 还认得出就按 JSON 报错。
+    const guess = guessFormat(argv);
+    return reportFailure(err, guess ?? format, labelFromArgv(argv));
+  }
+
+  const { globals } = parsed;
+
+  if (globals.version && parsed.command === null) {
+    process.stdout.write(`xinhe-oa-cli ${VERSION}\n`);
+    return EXIT_OK;
+  }
+  if (globals.help || parsed.command === null) {
+    process.stdout.write(helpText(parsed.command?.name ?? null));
+    return EXIT_OK;
+  }
+
+  // `meta.command` 在**成功**路径上比失败路径更细：Rust 是把
+  // `Runtime::new(global, "<细标签>")` 里那个字符串写进 meta 的
+  // （`config --list` / `login --phone --code` / `report rule`），
+  // 而失败路径用的是 `main.rs::command_label()` 的域标签（`config` / `login`）。
+  const label = commandLabel(parsed.command.name);
+  // 失败路径的 `meta.command`：Rust 的 `main.rs::command_label()` 对 `Command::Login`
+  // 用的是 `format!("login {}", args.kind())`（**从参数推**，见 `LoginArgs::kind()`），
+  // 其余域就是域名。与成功路径的细标签在这里恰好一致。
+  const failureLabel = label === 'login' ? runtimeLabel(parsed.command.name) : label;
+  let runtime;
+  try {
+    runtime = new Runtime(globals, runtimeLabel(parsed.command.name));
+  } catch (err) {
+    return reportFailure(err, format, failureLabel);
+  }
+
+  const handler = handlerFor(parsed.command.name);
+  if (handler === null) {
+    return reportFailure(
+      CliError.usage(`这条命令在 Node 版上还没实现：${parsed.command.name}`).withHint(
+        '先用 Rust 版：https://github.com/xinhe-oa/cli；或跑 `xinhe-oa-cli schema` 看已实现的面',
+      ),
+      format,
+      failureLabel,
+    );
+  }
+
+  try {
+    await handler({ args: parsed.args, positional: parsed.positional, runtime, command: parsed.command });
+    return EXIT_OK;
+  } catch (err) {
+    return reportFailure(err, format, failureLabel);
+  }
+}
+
+/** 失败出口：按格式渲染，返回退出码。 */
+function reportFailure(err, format, label) {
+  const error =
+    err instanceof CliError
+      ? err
+      : new CliError(Kind.Server, 'cli.internal', `内部错误：${err?.message ?? String(err)}`);
+  if (!(err instanceof CliError) && err?.stack) {
+    // 非预期异常（代码缺陷）与"用法错误"必须一眼分得开：把栈打到 stderr，
+    // 但**不进** `--json` 的 error 段（那是对外契约，形状不能变）。
+    process.stderr.write(`${err.stack}\n`);
+  }
+  // 失败路径的 `meta` 也要如实：`request_id` 取服务端回显的那个（判卷靠它与服务端
+  // 审计对齐），`profile` 取真实 profile 而不是写死 default。
+  const meta = new Meta({
+    command: label,
+    cliVersion: VERSION,
+    requestId: error.requestId ?? null,
+    profile: error.profile ?? process.env.XINHE_OA_PROFILE ?? 'default',
+  });
+  try {
+    renderFailure(error, meta, format);
+  } catch {
+    process.stderr.write(`✗ ${error.code}: ${error.message}\n`);
+  }
+  // 退出码表里没有 1：任何没归类的意外都算服务端/内部错误（6）。
+  return error.exitCode ?? EXIT_SERVER;
+}
+
+/** 参数都没解析出来时，尽量猜出"要不要 JSON"（否则报错格式会跟用户要的相反）。 */
+function guessFormat(argv) {
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token === '--json') return Format.Json;
+    if (token === '--format' || token.startsWith('--format=')) {
+      const raw = token.includes('=') ? token.split('=').slice(1).join('=') : argv[index + 1];
+      if (raw) {
+        try {
+          return parseFormat(raw);
+        } catch {
+          return Format.Table;
+        }
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * 成功路径的 `meta.command`（对齐 Rust 的 `Runtime::new(global, …)` 实参）。
+ *
+ * 只有三处与域标签不同，其余就是域名本身：
+ *   * `config --list|--show|--set|--use` → 各自的名字；
+ *   * `login …` → `login --phone` / `login --phone --code` / `login --password` /
+ *     `login --adopt-session`（由参数推，见 Rust `LoginArgs::kind()`）；
+ *   * `bitable base|table|…` 与 `report rule` 本来就是域名形式。
+ */
+function runtimeLabel(specName) {
+  const domain = commandLabel(specName);
+  // `config` 与 `login` 是仅有的两处"细标签"；其余就是域名本身
+  // （`bitable base` / `report rule` 已经带子资源）。
+  if (specName.startsWith('config ')) return specName;
+  if (domain === 'login') return specName;
+  return domain;
+}
+
+/** 从 argv 里取出域名，好在解析失败时也能给出 `meta.command`。 */
+function labelFromArgv(argv) {
+  for (const token of argv) {
+    if (token.startsWith('-')) continue;
+    const surface = commandSurface();
+    const hit = surface.commands.find(
+      (entry) => entry.name === token || entry.name.startsWith(`${token} `),
+    );
+    if (hit) return commandLabel(hit.name);
+    return token;
+  }
+  return '';
+}
+
+/** 顶层帮助（`--help` / 无参数）。 */
+function helpText(commandName) {
+  const surface = commandSurface();
+  const lines = [];
+  if (commandName === null) {
+    lines.push(`xinhe-oa-cli ${VERSION} —— ${ABOUT}`);
+    lines.push('');
+    lines.push('用法：xinhe-oa-cli <域> [<资源>] --<动作> [旗标]');
+    lines.push('');
+    lines.push(`全部命令（${surface.commands.length} 条，用 \`xinhe-oa-cli schema --json\` 取机器可读版）：`);
+    const seen = new Set();
+    for (const entry of surface.commands) {
+      const label = commandLabel(entry.name);
+      if (seen.has(label)) continue;
+      seen.add(label);
+      lines.push(`  ${label}`);
+    }
+    lines.push('');
+    lines.push('全局旗标：--base-url --profile --json --dry-run --yes --timeout -v/--verbose --quiet --no-color --format table|md|json');
+    lines.push('');
+    lines.push('最短上手：');
+    lines.push('  xinhe-oa-cli config --set base_url=<后端地址>');
+    lines.push('  xinhe-oa-cli login --phone <号码>');
+    lines.push('  xinhe-oa-cli me --json');
+    return `${lines.join('\n')}\n`;
+  }
+  const matched = surface.commands.filter(
+    (entry) => entry.name === commandName || entry.name.startsWith(`${commandName} `),
+  );
+  lines.push(`${commandName} —— ${matched.length} 条命令`);
+  lines.push('');
+  for (const entry of matched) {
+    lines.push(`  ${entry.name}  [${entry.risk}]`);
+    if (entry.params.length > 0) {
+      for (const param of entry.params) {
+        const value = param.value ? ` <${param.value}>` : '';
+        const optional = param.optional ? `[${param.flag}${value}]` : `${param.flag}${value}`;
+        lines.push(`      ${optional}${param.variadic ? '...' : ''}`);
+      }
+    }
+    if (entry.examples.length > 0) lines.push(`      例：${entry.examples[0]}`);
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/spec/agent_guide.md

@@ -0,0 +1,55 @@
+# xinhe-oa-cli 自举说明
+
+你（LLM）在客户机器上干活只有一条路：`xinhe-oa-cli`。
+令牌由 CLI 自己维护（0600 的凭据文件），**你看不到令牌，也不需要**。
+
+## 最短路径
+
+```bash
+xinhe-oa-cli config --set base_url=<后端地址>
+xinhe-oa-cli login --phone <号码>            # 发码
+xinhe-oa-cli login --phone <号码> --code <码> # 换凭据（CLI 落盘）
+xinhe-oa-cli me --json                       # 我是谁、能做什么、缺什么
+xinhe-oa-cli bitable base --list --json      # 看有什么
+```
+
+## 纪律
+
+- 一切通过**命令面**：没有任意路径、没有 SQL、没有绕过口。
+- 写操作自动带幂等键；`--dry-run` 只打印将发送的请求。
+- 高风险命令（`record --delete`、`application --copy|--install`、`workflow --run`、`event --replay`）**必须** `--yes`。
+- 退出码即结论：3=要重新登录、4=缺权限（看 `error.details.missing_scopes`）、5=冲突（重读再写）。
+- 版本过旧（退出码 8 / `cli.too_old`）→ `xinhe-oa-cli doctor --upgrade`：用已有登录凭据下载 + sha256 校验 + 原地替换；**退出码 0 不代表升成功**（看 `data.upgrade.replaced` 或 `--version`），升完重开终端再重试原命令。先 `doctor --upgrade --dry-run` 预演（只问一次只读的 `/cli/latest`，**不下载、不替换**）；只想把产物写到别处用 `doctor --upgrade --out <路径>`（**不动当前这个可执行文件**，且与本机是不是最新无关）。
+- 每个错误都带 `error.hint`：那就是下一步该敲的命令。
+- 长任务（导入 / 全表翻页）默认往 **stderr** 打进度；脚本里用全局 `--quiet` 关掉（告警不受影响）。导入可 `--workers N` 并发发批（默认 3），**断了直接重跑同一条命令**：checkpoint 只补剩余批次（`--fresh` 才从头来）；读表 `--all --workers N` 并发取页。
+- 用 `--json` 解析，别去刮表格文本。
+
+## 企业里的常见活
+
+业务员要「上传一份单据」= 建表 + 灌数据，一条命令：
+
+```bash
+xinhe-oa-cli bitable table --import --file 公账流水.csv \
+  --base-name 开叔企业 --name 公账流水 --keep-source
+```
+
+客户端负责解析（CSV/XLSX → 推断字段类型 → 建表 → 建字段 → 分批写记录），
+平台只存结果 —— 业务计算全在客户端。
+
+## 造技能 / 分享 / 审批（技能即应用）
+
+```bash
+xinhe-oa-cli skills --create --name 财务月结 --readme ./SKILL.md --json  # 默认 private
+xinhe-oa-cli skills --share 财务月结 --to-user usr_x --json              # 点对点，直接生效
+xinhe-oa-cli skills --conflicts --name 财务月结 --json                  # 先扫冲突
+xinhe-oa-cli skills --publish 财务月结 --visibility tenant \
+  --on-conflict rename --new-key finance_monthly_v2 --json           # 提交企业审批
+xinhe-oa-cli approval --list --to-review --json                     # 企业负责人看这个
+xinhe-oa-cli approval --approve apr_x --yes --json                  # 高风险：必须 --yes
+```
+
+- 冲突**绝不自动选**：`--conflicts` / `--publish` 撞上冲突就退出码 5，并列出冲突项的
+  key / name / 创建人 / 更新时间 / 撞的是 key 还是 name；你必须显式选
+  `--on-conflict rename --new-key <k>` 或 `--on-conflict update`。
+- 内置名（`xo-core` / `xo-admin`）不可覆盖：直接报 `skill.name_reserved`，换个名字。
+- `approval --list --to-review` 在非企业负责人身份下返回**空列表是正常的**，不是错误。