@milian/linker-cli 0.0.0-stage → 0.17.3

package/src/schema.js

@@ -0,0 +1,582 @@
+'use strict';
+
+/**
+ * 入参/出参结构转换（纯函数，不做任何 IO）。
+ *
+ * 平台要求 outboundApiParamList / outboundApiResultList 是「字段树」，
+ * 而人给的是 curl 或 JSON 示例。这里负责把示例推导成字段树。
+ *
+ * 平台权威规则（业务方给定）：
+ *   - requestParam / requestBody / requestHeader 三个根节点必须都在
+ *   - responseBody 根节点必须都在
+ *   - collective: 是否数组
+ *   - fieldType: object | number | string | boolean
+ *   - fieldLength: 仅 string 需要，不清楚填 255，其他 null
+ *   - basic: fieldType 是 object 则 false，否则 true
+ *   - paramType: header -> HEADER，body -> BODY，路径参数/query -> PARAM
+ *   - requestHeader / requestParam 的子级只能是 string
+ *   - requestBody 的子级可以是 object，需继续向下挂 children
+ *
+ * labelName（字段描述）**不由类型推导**——它应该是接口文档里的真实注释。
+ * 平台样例里那些「对象」「字符串数组」只是人工随手填的，不能当作规则。
+ * 没给注释就留空；给了就原样用，超过 MAX_LABEL_LENGTH 会截断并提示调用方去总结。
+ */
+
+const STRING_LENGTH = 255;
+
+const ROOT_LABEL = '根节点';
+const ROOT_PARAM = 'requestParam';
+const ROOT_BODY = 'requestBody';
+const ROOT_HEADER = 'requestHeader';
+const ROOT_RESULT = 'responseBody';
+
+const PARAM_TYPE_PARAM = 'PARAM';
+const PARAM_TYPE_BODY = 'BODY';
+const PARAM_TYPE_HEADER = 'HEADER';
+
+const FIELD_OBJECT = 'object';
+const FIELD_NUMBER = 'number';
+const FIELD_STRING = 'string';
+const FIELD_BOOLEAN = 'boolean';
+
+/** Content-Type 由 contentType 数字字段表达，不进 requestHeader（与平台前端一致） */
+const IGNORED_HEADERS = ['content-type'];
+
+/** 字段描述（labelName）长度上限。超了必须由 AI 总结后再提交 */
+const MAX_LABEL_LENGTH = 200;
+
+/** 注释的作用域 */
+const LABEL_SCOPES = ['request', 'response', 'param', 'header'];
+
+// ---------------------------------------------------------------- JSON 解析
+
+function parseJsonText(text, label) {
+  try {
+    return JSON.parse(text);
+  } catch (err) {
+    throw new Error(`${label} 不是合法 JSON：${err.message}`);
+  }
+}
+
+// ---------------------------------------------------------------- 类型推导
+
+/**
+ * 从示例值推导字段类型。只推类型/是否数组/长度，**不猜描述**。
+ * @returns {{fieldType:string, collective:boolean, fieldLength:number|null}}
+ */
+function classifyValue(value) {
+  if (Array.isArray(value)) {
+    const inner = classifyValue(value.length ? value[0] : '');
+    return {
+      fieldType: inner.fieldType,
+      collective: true,
+      fieldLength: inner.fieldType === FIELD_STRING ? STRING_LENGTH : null
+    };
+  }
+  if (value !== null && typeof value === 'object') {
+    return { fieldType: FIELD_OBJECT, collective: false, fieldLength: null };
+  }
+  if (typeof value === 'number') {
+    return { fieldType: FIELD_NUMBER, collective: false, fieldLength: null };
+  }
+  if (typeof value === 'boolean') {
+    return { fieldType: FIELD_BOOLEAN, collective: false, fieldLength: null };
+  }
+  return { fieldType: FIELD_STRING, collective: false, fieldLength: STRING_LENGTH };
+}
+
+// ---------------------------------------------------------------- 上下文
+
+function toList(raw) {
+  if (raw instanceof Set) return Array.from(raw);
+  if (Array.isArray(raw)) return raw.map((s) => String(s));
+  return String(raw == null ? '' : raw)
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/** 按字符数截断（平台对 labelName 有长度限制） */
+function clipLabel(text, max) {
+  const s = String(text == null ? '' : text);
+  const limit = Number.isFinite(max) && max > 0 ? max : MAX_LABEL_LENGTH;
+  return s.length > limit ? s.slice(0, limit) : s;
+}
+
+/** 'a=1' / ['a=1'] / {a:1} / Map → [[k,v]] */
+function toEntries(raw) {
+  if (!raw) return [];
+  if (raw instanceof Map) return Array.from(raw.entries());
+  if (Array.isArray(raw)) {
+    return raw
+      .map((item) => {
+        const s = String(item == null ? '' : item);
+        const i = s.indexOf('=');
+        return i > 0 ? [s.slice(0, i).trim(), s.slice(i + 1).trim()] : null;
+      })
+      .filter(Boolean);
+  }
+  if (typeof raw === 'object') return Object.entries(raw);
+  return [];
+}
+
+function isNormalizedLabels(x) {
+  return Boolean(x) && LABEL_SCOPES.every((s) => x[s] instanceof Map);
+}
+
+/**
+ * 归一化字段注释（labelName）。
+ *
+ * 支持三种来源：
+ *   1. 分域对象 { request:{path:注释}, response:{...}, param:{...}, header:{...} }
+ *   2. 扁平对象 { 'b.d': '订单号' }  → 同时作用于 request / response / param / header
+ *   3. 'path=注释' 数组（--label 的原始形态）
+ *   4. 已归一化过的结果（幂等）
+ *
+ * 超过 MAX_LABEL_LENGTH 的会被截断，并记入 clipped 供调用方提示"应当总结"。
+ * @returns {{labels:{request:Map,response:Map,param:Map,header:Map}, clipped:object[]}}
+ */
+function normalizeLabels(raw) {
+  if (isNormalizedLabels(raw)) return { labels: raw, clipped: [] };
+
+  const labels = { request: new Map(), response: new Map(), param: new Map(), header: new Map() };
+  const clipped = [];
+  const entries = toEntries(raw);
+  const scoped = entries.some(([k]) => LABEL_SCOPES.includes(k));
+
+  const put = (scope, path, text) => {
+    const key = String(path == null ? '' : path).trim();
+    if (!key) return;
+    const value = String(text == null ? '' : text);
+    const value2 = clipLabel(value);
+    if (value2.length !== value.length) clipped.push({ scope, path: key, length: value.length });
+    labels[scope].set(key, value2);
+  };
+
+  for (const [k, v] of entries) {
+    if (scoped) {
+      if (LABEL_SCOPES.includes(k)) {
+        for (const [p, t] of toEntries(v)) put(k, p, t);
+      }
+      continue;
+    }
+    // 扁平模式：同名路径在四个作用域都生效（键名通常不冲突，方便一次性给全）
+    for (const scope of LABEL_SCOPES) put(scope, k, v);
+  }
+
+  return { labels, clipped };
+}
+
+function labelOf(map, key, fallback) {
+  if (map && map.has(key)) return map.get(key);
+  return fallback == null ? '' : String(fallback);
+}
+
+// ---------------------------------------------------------------- 入参树
+
+function buildBodyNode(key, value, path, ctx) {
+  const c = classifyValue(value);
+  const node = {
+    fieldCode: key,
+    mandatory: ctx.required.has(path),
+    collective: c.collective,
+    fieldType: c.fieldType,
+    fieldLength: c.fieldLength,
+    labelName: labelOf(ctx.labels, path),
+    basic: c.fieldType !== FIELD_OBJECT,
+    paramType: PARAM_TYPE_BODY
+  };
+  if (c.fieldType === FIELD_OBJECT) {
+    const src = c.collective ? (Array.isArray(value) && value.length ? value[0] : {}) : value;
+    node.children = buildBodyChildren(src, path, ctx);
+  }
+  return node;
+}
+
+function buildBodyChildren(obj, parentPath, ctx) {
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) return [];
+  return Object.keys(obj).map((k) => buildBodyNode(k, obj[k], parentPath ? parentPath + '.' + k : k, ctx));
+}
+
+/** requestParam / requestHeader 的子级只能是 string */
+function buildLeafParam(key, paramType, fallbackLabel, ctx) {
+  return {
+    fieldCode: key,
+    mandatory: ctx.required.has(key),
+    collective: false,
+    fieldType: FIELD_STRING,
+    fieldLength: STRING_LENGTH,
+    labelName: labelOf(ctx.labels, key, fallbackLabel),
+    basic: true,
+    paramType
+  };
+}
+
+/**
+ * 三个根节点的公共骨架。
+ * 注意：官方样例里 requestHeader 根节点没有 fieldLength 字段（requestParam / requestBody 有），
+ * 这里逐字对齐，避免提交体与平台前端生成的形态出现差异。
+ */
+function buildRoot(fieldCode, paramType) {
+  const root = {
+    fieldCode,
+    mandatory: false,
+    collective: false,
+    fieldType: FIELD_OBJECT,
+    labelName: ROOT_LABEL
+  };
+  if (paramType !== PARAM_TYPE_HEADER) root.fieldLength = null;
+  root.paramType = paramType;
+  root.children = [];
+  root.basic = false;
+  return root;
+}
+
+function unique(list) {
+  const out = [];
+  for (const item of list || []) {
+    const s = String(item == null ? '' : item).trim();
+    if (s && !out.includes(s)) out.push(s);
+  }
+  return out;
+}
+
+/**
+ * 生成 outboundApiParamList（顺序固定：requestParam → requestBody → requestHeader）
+ * @param {object} options
+ * @param {string[]|string} [options.queryParams]   query 参数名列表
+ * @param {string[]|string} [options.pathParams]    路径参数名列表（url 里 {x} 抽出来的）
+ * @param {string[]|string} [options.headerParams]  请求头名列表
+ * @param {any} [options.bodyJson]                  请求体 JSON 示例
+ * @param {string[]|string} [options.required]      必填字段路径（如 b.d）
+ * @param {object|Map|string[]} [options.labels]    字段描述（来自接口文档注释），见 normalizeLabels
+ */
+function buildParamTree(options) {
+  const o = options || {};
+  const required = new Set(toList(o.required));
+  const { labels } = normalizeLabels(o.labels);
+
+  const pathKeys = unique(o.pathParams);
+  const queryKeys = unique(o.queryParams).filter((k) => !pathKeys.includes(k));
+  const headerKeys = unique(o.headerParams);
+
+  const paramCtx = { required, labels: labels.param };
+  const paramRoot = buildRoot(ROOT_PARAM, PARAM_TYPE_PARAM);
+  paramRoot.children = [
+    ...pathKeys.map((k) => buildLeafParam(k, PARAM_TYPE_PARAM, '路径参数', paramCtx)),
+    ...queryKeys.map((k) => buildLeafParam(k, PARAM_TYPE_PARAM, '', paramCtx))
+  ];
+
+  const bodyCtx = { required, labels: labels.request };
+  const bodyRoot = buildRoot(ROOT_BODY, PARAM_TYPE_BODY);
+  const body = o.bodyJson;
+  if (Array.isArray(body)) {
+    bodyRoot.collective = true;
+    bodyRoot.children = buildBodyChildren(body.length ? body[0] : {}, '', bodyCtx);
+  } else if (body !== null && typeof body === 'object') {
+    bodyRoot.children = buildBodyChildren(body, '', bodyCtx);
+  }
+
+  const headerCtx = { required, labels: labels.header };
+  const headerRoot = buildRoot(ROOT_HEADER, PARAM_TYPE_HEADER);
+  headerRoot.children = headerKeys.map((k) => buildLeafParam(k, PARAM_TYPE_HEADER, '', headerCtx));
+
+  return [paramRoot, bodyRoot, headerRoot];
+}
+
+// ---------------------------------------------------------------- 出参树
+
+/**
+ * 出参节点。
+ * 出参没有 mandatory / paramType / fieldLength，labelName 同样只来自注释。
+ */
+function buildResultNode(key, value, path, ctx) {
+  const c = classifyValue(value);
+  const node = {
+    fieldCode: key,
+    collective: c.collective,
+    fieldType: c.fieldType,
+    sensitiveFieldIds: null,
+    filterFlag: 0,
+    labelName: labelOf(ctx.labels, path),
+    basic: c.fieldType !== FIELD_OBJECT
+  };
+  if (c.fieldType === FIELD_OBJECT) {
+    const src = c.collective ? (Array.isArray(value) && value.length ? value[0] : {}) : value;
+    node.children = buildResultChildren(src, path, ctx);
+  }
+  return node;
+}
+
+function buildResultChildren(obj, parentPath, ctx) {
+  if (obj === null || typeof obj !== 'object' || Array.isArray(obj)) return [];
+  return Object.keys(obj).map((k) => buildResultNode(k, obj[k], parentPath ? parentPath + '.' + k : k, ctx));
+}
+
+/**
+ * 生成 outboundApiResultList（固定只有一个 responseBody 根节点）
+ * 注意：出参节点没有 mandatory / paramType / fieldLength（平台样例如此）
+ * @param {any} resultJson 出参示例
+ * @param {object} [opts] { labels } 字段描述（来自接口文档注释）
+ */
+function buildResultTree(resultJson, opts) {
+  const o = opts || {};
+  const { labels } = normalizeLabels(o.labels);
+  const ctx = { required: new Set(toList(o.required)), labels: labels.response };
+  const root = {
+    fieldCode: ROOT_RESULT,
+    collective: false,
+    fieldType: FIELD_OBJECT,
+    labelName: ROOT_LABEL,
+    sensitiveFieldIds: null,
+    filterFlag: 0,
+    children: [],
+    basic: false
+  };
+
+  if (resultJson === undefined || resultJson === null) return [root];
+
+  if (Array.isArray(resultJson)) {
+    root.collective = true;
+    root.children = buildResultChildren(resultJson.length ? resultJson[0] : {}, '', ctx);
+    return [root];
+  }
+  if (typeof resultJson === 'object') {
+    root.children = buildResultChildren(resultJson, '', ctx);
+  }
+  return [root];
+}
+
+// ---------------------------------------------------------------- url 处理
+
+const PATH_PARAM_RE = /\{\s*([A-Za-z0-9_.\-]+)\s*\}/g;
+
+/**
+ * 规范化 api 路径：
+ *   - 必须以 / 开头
+ *   - 去掉 host（只保留 path）
+ *   - 路径参数 /asd/{orderId}/asd → /asd/orderId/asd，并抽出 orderId
+ */
+function normalizeUrl(rawUrl) {
+  let u = String(rawUrl == null ? '' : rawUrl).trim();
+  if (!u) throw new Error('api 路径不能为空');
+
+  const hostMatch = /^[a-z][a-z0-9+.\-]*:\/\/[^/]+(\/.*)?$/i.exec(u);
+  if (hostMatch) u = hostMatch[1] || '/';
+  if (!u.startsWith('/')) u = '/' + u;
+
+  const pathParams = [];
+  u = u.replace(PATH_PARAM_RE, (_, key) => {
+    if (!pathParams.includes(key)) pathParams.push(key);
+    return key;
+  });
+
+  if (/\s/.test(u)) throw new Error(`api 路径 "${u}" 含空白字符，不符合路径规范`);
+
+  return { url: u, pathParams };
+}
+
+/** 只保留路径段允许的字符 */
+function sanitizeSegment(s) {
+  return String(s == null ? '' : s).replace(/[^A-Za-z0-9\-_.~]/g, '');
+}
+
+function applyUrlSuffix(url, suffix) {
+  const base = String(url == null ? '' : url).replace(/\/+$/, '');
+  const seg = sanitizeSegment(suffix);
+  return seg ? base + '/' + seg : base;
+}
+
+/**
+ * api 名称里的英文片段 → 小驼峰
+ * - get_user_info → getUserInfo
+ * - getUserInfo  → getUserInfo（已是驼峰就原样保留，不要压平）
+ * - 纯中文 → ''（无法提取）
+ */
+function asciiSlug(name) {
+  const parts = String(name == null ? '' : name)
+    .split(/[^A-Za-z0-9]+/)
+    .filter(Boolean);
+  if (!parts.length) return '';
+
+  // 只有一段且本身带大写，说明已经是驼峰，原样保留
+  if (parts.length === 1) {
+    const only = parts[0];
+    if (only.replace(/[^A-Za-z]/g, '').length < 2) return '';
+    return /[A-Z]/.test(only) ? only : only.toLowerCase();
+  }
+
+  const words = parts.map((w) => w.toLowerCase());
+  if (words.join('').replace(/[^A-Za-z]/g, '').length < 2) return '';
+  return words[0] + words.slice(1).map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+}
+
+/** 路径冲突时的候选后缀：优先用 api 名称里的英文，其次语义化单词池 */
+const FALLBACK_WORDS = ['query', 'list', 'data', 'detail', 'search', 'sync', 'info', 'fetch', 'exec', 'invoke'];
+
+function buildRetrySuffix(apiName, attempt) {
+  const n = Math.max(1, Number(attempt) || 1);
+  const slug = asciiSlug(apiName);
+  if (n === 1 && slug) return slug;
+  const idx = slug ? n - 2 : n - 1;
+  if (idx >= 0 && idx < FALLBACK_WORDS.length) return FALLBACK_WORDS[idx];
+  return 'v' + n;
+}
+
+/**
+ * 第 attempt 次发布使用的 url。
+ * attempt=1 用发布准备返回的 url；之后在「原始 url」后追加后缀（不是层层叠加）。
+ */
+function urlForAttempt(baseUrl, apiName, attempt, explicitSuffix) {
+  const n = Math.max(1, Number(attempt) || 1);
+  if (n <= 1) return String(baseUrl == null ? '' : baseUrl);
+  const suffix = n === 2 && explicitSuffix ? explicitSuffix : buildRetrySuffix(apiName, n - 1);
+  return applyUrlSuffix(baseUrl, suffix);
+}
+
+// ---------------------------------------------------------------- 命令行入参解析
+
+/** 'a=1&b=2' / ['a=1','b=2'] / '?a=1' → ['a','b'] */
+function parseQueryKeys(raw) {
+  const items = Array.isArray(raw) ? raw : [raw];
+  const keys = [];
+  for (const item of items) {
+    const s = String(item == null ? '' : item).trim().replace(/^\?/, '');
+    if (!s) continue;
+    for (const part of s.split('&')) {
+      const k = part.split('=')[0].trim();
+      if (k && !keys.includes(k)) keys.push(k);
+    }
+  }
+  return keys;
+}
+
+/** 'e: 2' / ['e: 2','x=1'] → ['e','x']；Content-Type 自动忽略 */
+function parseHeaderKeys(raw) {
+  const items = Array.isArray(raw) ? raw : [raw];
+  const keys = [];
+  for (const item of items) {
+    const s = String(item == null ? '' : item).trim();
+    if (!s) continue;
+    const sep = s.search(/[:=]/);
+    const k = (sep > 0 ? s.slice(0, sep) : s).trim();
+    if (!k) continue;
+    if (IGNORED_HEADERS.includes(k.toLowerCase())) continue;
+    if (!keys.includes(k)) keys.push(k);
+  }
+  return keys;
+}
+
+/** 'number' / '1' / '' → contentType；GET 默认 0，其余默认 1 */
+function parseContentType(raw, method) {
+  const v = String(raw == null ? '' : raw).trim();
+  if (!v) return String(method || '').toUpperCase() === 'GET' ? 0 : 1;
+  const n = Number(v);
+  if (!Number.isInteger(n) || n < 0 || n > 6) {
+    throw new Error(
+      `contentType "${v}" 不合法：0=none 1=json 2=soap+xml 3=xml 4=form 5=multipart 6=octet-stream`
+    );
+  }
+  return n;
+}
+
+/** 示例转字符串（paramExample / resultExample 平台存的是文本） */
+function prettyExample(value) {
+  if (value === undefined || value === null) return '';
+  if (typeof value === 'string') return value;
+  return JSON.stringify(value, null, 4);
+}
+
+function pickOutboundApiId(data) {
+  if (data === null || data === undefined || data === '') return '';
+  if (typeof data === 'string' || typeof data === 'number') return String(data);
+  if (typeof data === 'object') {
+    return String(data.outboundApiId || data.apiId || data.id || '');
+  }
+  return '';
+}
+
+// ---------------------------------------------------------------- 组装
+
+function buildSaveBody(v) {
+  const head = v.outboundApiId
+    ? { platformId: v.platformId, outboundApiId: v.outboundApiId, id: v.outboundApiId }
+    : { platformId: v.platformId };
+
+  return Object.assign(head, {
+    dynamicApi: true,
+    apiName: v.apiName,
+    serviceName: v.serviceName || '',
+    url: v.url,
+    httpMethod: v.httpMethod,
+    platformHostId: v.platformHostId,
+    remark: v.remark,
+    apiType: 0,
+    devStatus: 0,
+    execType: 0,
+    contentType: v.contentType,
+    outboundApiParamList: v.outboundApiParamList,
+    deleteParamList: [],
+    paramExample: v.paramExample || '',
+    outboundApiResultList: v.outboundApiResultList,
+    deleteResultList: [],
+    resultExample: v.resultExample || '',
+    httpCodeList: []
+  });
+}
+
+// ---------------------------------------------------------------- 展示
+
+function renderTree(nodes, indent) {
+  const pad = '  '.repeat(indent || 0);
+  const lines = [];
+  for (const n of nodes || []) {
+    const meta = [n.fieldType];
+    if (n.collective) meta.push('数组');
+    if (n.fieldLength) meta.push(`长度${n.fieldLength}`);
+    // labelName 为「必填 xxx」时不再重复标必填，避免出现「必填 必填 数字」
+    if (n.mandatory && !/^必填/.test(String(n.labelName || ''))) meta.push('必填');
+    if (n.labelName) meta.push(n.labelName);
+    lines.push(`${pad}${n.fieldCode}  (${meta.join(' ')})`);
+    if (n.children && n.children.length) lines.push(...renderTree(n.children, (indent || 0) + 1));
+  }
+  return lines;
+}
+
+module.exports = {
+  STRING_LENGTH,
+  ROOT_LABEL,
+  ROOT_PARAM,
+  ROOT_BODY,
+  ROOT_HEADER,
+  ROOT_RESULT,
+  PARAM_TYPE_PARAM,
+  PARAM_TYPE_BODY,
+  PARAM_TYPE_HEADER,
+  IGNORED_HEADERS,
+  FALLBACK_WORDS,
+  MAX_LABEL_LENGTH,
+  LABEL_SCOPES,
+  parseJsonText,
+  classifyValue,
+  clipLabel,
+  normalizeLabels,
+  isNormalizedLabels,
+  toEntries,
+  buildParamTree,
+  buildResultTree,
+  normalizeUrl,
+  sanitizeSegment,
+  applyUrlSuffix,
+  asciiSlug,
+  buildRetrySuffix,
+  urlForAttempt,
+  parseQueryKeys,
+  parseHeaderKeys,
+  parseContentType,
+  prettyExample,
+  pickOutboundApiId,
+  buildSaveBody,
+  renderTree,
+  toList
+};

package/src/ui.js

@@ -0,0 +1,57 @@
+'use strict';
+
+/** 终端显示宽度：CJK 字符占 2 列，否则中文表格会错行 */
+function dispWidth(s) {
+  let w = 0;
+  for (const ch of String(s == null ? '' : s)) {
+    w += /[\u1100-\u115F\u2E80-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE4F\uFF00-\uFF60\uFFE0-\uFFE6]/.test(ch)
+      ? 2
+      : 1;
+  }
+  return w;
+}
+
+function pad(s, n) {
+  const str = String(s == null ? '' : s);
+  const w = dispWidth(str);
+  return w >= n ? str : str + ' '.repeat(n - w);
+}
+
+/**
+ * 渲染对齐表格。
+ * @param {string[]} header 表头
+ * @param {string[][]} rows 数据行（已转字符串）
+ * @returns {string} 完整表格文本（含表头、分隔线）
+ */
+function renderTable(header, rows) {
+  if (!rows.length) return '';
+  const widths = header.map((h, ci) => Math.max(dispWidth(h), ...rows.map((row) => dispWidth(row[ci]))));
+  const lines = [];
+  lines.push(header.map((h, i) => pad(h, widths[i])).join('  '));
+  lines.push(widths.map((w) => '-'.repeat(w)).join('  '));
+  for (const row of rows) {
+    lines.push(row.map((c, i) => pad(c, widths[i])).join('  '));
+  }
+  return lines.join('\n');
+}
+
+/**
+ * 按显示宽度截断，超出用省略号收尾。
+ * 用于列宽失控的场景（如工具名可能长达上百列），避免整表错行、刷屏。
+ */
+function truncate(s, max) {
+  const str = String(s == null ? '' : s);
+  const limit = Math.max(1, Number(max) || 1);
+  if (dispWidth(str) <= limit) return str;
+  let out = '';
+  let w = 0;
+  for (const ch of str) {
+    const cw = dispWidth(ch);
+    if (w + cw > limit - 1) break;
+    out += ch;
+    w += cw;
+  }
+  return out + '…';
+}
+
+module.exports = { dispWidth, pad, truncate, renderTable };