@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/schema.js

@@ -0,0 +1,75 @@
+// 自描述命令：`schema [command]` / `schema --agent`（契约 §2）。
+//
+// 这份描述符是**机器可读的能力面清单**：LLM 与判卷都靠它知道"这个 CLI 能干什么"。
+// Node 版的正文来自 `src/spec/command_surface.json`（由 `scripts/gen-spec.py` 从
+// Rust 产物的 `schema --json` 生成）—— 两条实现的命令面因此不可能各说各话。
+
+import { readFileSync } from 'node:fs';
+
+import { CliError } from '../core/error.js';
+import { commandSurface } from '../core/args.js';
+import { VERSION } from '../version.js';
+
+const AGENT_GUIDE = readFileSync(new URL('../spec/agent_guide.md', import.meta.url), 'utf8');
+
+/**
+ * 按查询串过滤命令（与 Rust `schema::lookup` 逐条同义）：
+ *
+ * 1. 先 `trim()`；trim 后为空串 == 不筛（**返回全部，不是错误、不是空列表**）；
+ * 2. 判据 = 精确相等 **或** 前缀匹配（`bitable record` 命中 5 条）；
+ * 3. **大小写敏感**，无模糊/子串/后缀匹配；
+ * 4. 命中结果保持声明顺序。
+ */
+export function lookup(query) {
+  const needle = String(query ?? '').trim();
+  return commandSurface().commands.filter((entry) => entry.name.startsWith(needle));
+}
+
+/** `schema --json` 的 `data` 段。 */
+export function schemaJson(query) {
+  const surface = commandSurface();
+  const commands = query === null || query === undefined ? surface.commands : lookup(query);
+  return {
+    commands: commands.map((entry) => ({
+      endpoints: entry.endpoints,
+      examples: entry.examples,
+      name: entry.name,
+      output_schema: entry.output_schema,
+      // 逐字回显 Rust 那边的写法（`[--store S01:总院]...`）：这是给人看的正文，
+      // 反渲染必然漂移，所以规格里存的就是原文（`params_raw`）。
+      params: entry.params_raw,
+      requires_yes: entry.requires_yes,
+      risk: entry.risk,
+    })),
+    count: commands.length,
+    field_types: surface.field_types,
+    note: surface.note,
+    output_contract: surface.output_contract,
+    roles: surface.roles,
+    version: VERSION,
+  };
+}
+
+
+/** `schema [command]` / `schema --agent`。 */
+export async function handleSchema({ args, positional, runtime }) {
+  if (args['--agent'] === true) {
+    // `--agent` 给的是人/LLM 读的自举说明（**不是** MCP，只是文本）。
+    // 优先级高于位置参数：`schema bitable --agent` 也回自举说明。
+    const data = {
+      agent_guide: AGENT_GUIDE,
+      commands: commandSurface().commands.length,
+      note: '这是一段说明文本。本 CLI **没有** MCP 面，也没有任意路径/任意 SQL。',
+    };
+    runtime.finish(data);
+    return;
+  }
+
+  const query = positional.length > 0 ? positional[0] : null;
+  if (query !== null && lookup(query).length === 0) {
+    throw CliError.usage(`没有匹配 \`${query}\` 的命令`).withHint(
+      '跑 `xinhe-oa-cli schema`（不带参数）看全部命令；例：xinhe-oa-cli schema bitable record',
+    );
+  }
+  runtime.finish(schemaJson(query));
+}

package/src/commands/session.js

@@ -0,0 +1,516 @@
+// 会话：`login` / `logout` / `me`（契约 §2 会话行、§4 凭据与设备指纹、§5 首次使用）。
+//
+// 这一域回答三个问题：**怎么进来 / 怎么出去 / 我是谁**，也是唯一会写凭据文件的地方。
+// 逐行对照 `cli/crates/xinhe-oa-cli/src/commands/session.rs` 移植，几处看起来"绕"的
+// 地方就地写清了原因。
+//
+// ## 为什么 `device_id` 必须先落盘，再发那个请求
+//
+// 服务端把 refresh 令牌绑在 `HMAC(User-Agent + X-Device-Id)` 上（契约 §4）。
+// "拿验证码换凭据"成功的那一刻，服务端记下的是**这次请求头里**那个 device_id：
+//
+//   * 临时生成、不落盘 —— 本次登录看起来一切正常；但 CLI 下一次续期时只能再随机
+//     一个（或读到空的）device_id，服务端立刻回 `auth.device_mismatch`，
+//     用户被迫重新走一遍短信登录。**这个坑只在"下一次"才炸**，所以必须在第一次就落盘。
+//   * 因此 `runtime.ensureDeviceId()` 在**建 HTTP 客户端之前**调用，之后再从落盘凭据里取。
+//
+// 注意"发验证码"那一步（`login --phone` 只给手机号）与 Rust 一样**不落盘** device_id：
+// 它只是一次匿名请求，服务端此时还没签发任何东西。真正把指纹钉下来的是
+// `--code` 换凭据那一步（`--password` 同理）。
+//
+// ## 为什么 `logout` 允许用"已经过期的 access"
+//
+// 登出的语义是"把这个会话链吊销掉、把本机凭据删掉"，而**令牌过期恰恰是最常见的登出时机**
+// （放了一夜回来想退出登录）。所以 `auth.logout` 用 refresh 当凭据、access 只是"能用就带上"；
+// 服务端已经吊销 / 网络不通 / 报任何错，都不该挡住"本地把凭据删干净"这个用户按下去了的动作 ——
+// 失败只进 `data.warning`（契约 §3.2 的退出码仍然照常返回）。
+//
+// ## 令牌纪律
+//
+// `--json` 里只出现掩码（`maskToken` / `maskPhone`）；`--password` 的口令只从 stdin 读；
+// 短信验证码除了 `dev_code` 那次开发模式回显外，不进日志、不进错误。
+
+import { flagOn, flagValue } from '../core/args.js';
+import {
+  adoptSession,
+  envelopeData,
+  loginWithPassword,
+  logout as logoutSession,
+  readSecretFromStdin,
+  verifyOtp,
+} from '../core/auth.js';
+import { CliError } from '../core/error.js';
+import { requestSpec } from '../core/http.js';
+import { renderTable } from '../core/output.js';
+import { maskPhone, maskToken, nowRfc3339, sortKeysDeep } from '../core/util.js';
+
+/** `me` 的人类可读视图里逐条列出的权限上限（Rust 侧的 `SCOPE_CAP`）。 */
+const SCOPE_CAP = 50;
+
+/**
+ * `login` 到底走了哪条路（对齐 Rust `LoginArgs::kind` 的**分支顺序**）。
+ *
+ * 顺序不是随手写的：clap 的 `ArgGroup(multiple = false)` 保证四选一，
+ * 但"既有 code 又 adopt"这种组合在 Rust 里由 adopt 先赢 —— `meta.command` 要一致。
+ */
+function loginKind({ adopt, password, hasCode }) {
+  if (adopt) return '--adopt-session';
+  if (password) return '--password';
+  if (hasCode) return '--phone --code';
+  return '--phone';
+}
+
+/** `login`：发码 / 校验验证码 / 口令 / 交接会话。 */
+export async function handleLogin({ args, runtime }) {
+  const adopt = flagOn(args, '--adopt-session');
+  const password = flagOn(args, '--password');
+  const phone = flagValue(args, '--phone');
+  const code = flagValue(args, '--code');
+  const account = flagValue(args, '--account');
+
+  // `meta.command` 是判卷字段。Rust 按"用户实际走了哪条登录路径"细分标签
+  // （`login --phone` / `login --phone --code` / `login --password` / `login --adopt-session`），
+  // 而 Node 的命令表按域名折叠成 `login`。这里在收尾（以及发请求）之前把它校正成
+  // Rust 的形态，`--json` 的 `meta.command` 才逐字一致。
+  runtime.command = `login ${loginKind({ adopt, password, hasCode: code !== null })}`;
+
+  // ① 交接会话（install.sh 用）：不联网，只把它写进自己的凭据文件。
+  if (adopt) return adoptFromStdin(runtime);
+
+  // ② 口令登录（仅引导账号；口令从 stdin 读，**不进 argv**）。
+  if (password) return loginByPassword(runtime, account);
+
+  // ③ 拿验证码换凭据。
+  //
+  // 判空用 `=== null`（而不是 falsy）：`--phone=` 这种显式空串在 Rust 里是
+  // `Some("")`，会被原样发给服务端，由服务端回"号码不合法" —— CLI 不替它判。
+  if (phone === null) {
+    throw CliError.usage('`login` 需要 --phone <手机号>').withHint(
+      '例：xinhe-oa-cli login --phone 13800000000',
+    );
+  }
+  if (code !== null) return loginByCode(runtime, phone, code);
+
+  // ④ 只给手机号 = 发码。
+  return requestOtp(runtime, phone);
+}
+
+/**
+ * `login --password --account`：仅引导账号，口令从 stdin 读。
+ *
+ * 三步的顺序是刻意的（与 Rust 一致）：**先落盘 device_id，再读口令，最后才碰网络**。
+ * 口令读失败（stdin 是空的）时，device_id 已经存好了 —— 用户重跑一次不会换指纹。
+ */
+async function loginByPassword(runtime, account) {
+  if (account === null) {
+    throw CliError.usage('`login --password` 需要 --account <账号>').withHint(
+      "例：printf '%s' \"$PW\" | xinhe-oa-cli login --password --account 18772318183",
+    );
+  }
+  const deviceId = runtime.ensureDeviceId();
+  const secret = await readSecretFromStdin('口令（从 stdin 读，不回显）：');
+  const http = runtime.anonymousHttp();
+  if (runtime.dryRun) {
+    // 口令**不回显**：dry-run 报告里只放占位符（连长度都不给）。
+    return runtime.dryRunReport(
+      'POST',
+      '/auth/login',
+      requestSpec({ body: { account, password: '<从 stdin 读，不打印>' } }),
+    );
+  }
+  const credential = await loginWithPassword(http, account, secret, deviceId);
+  return saveAndReport(runtime, credential, 'password');
+}
+
+/** `login --phone --code`：校验验证码并落盘凭据。 */
+async function loginByCode(runtime, phone, code) {
+  // **先落盘再用**（见文件头）：这一步之后，请求头里的 X-Device-Id
+  // 与将来续期时从凭据文件里读到的那个一定是同一个。
+  const deviceId = runtime.ensureDeviceId();
+  const http = runtime.anonymousHttp();
+  if (runtime.dryRun) {
+    return runtime.dryRunReport('POST', '/auth/otp/verify', requestSpec({ body: { code, phone } }));
+  }
+  const credential = await verifyOtp(http, phone, code, deviceId);
+  return saveAndReport(runtime, credential, 'otp');
+}
+
+/**
+ * `login --phone`（只给手机号）：发验证码。
+ *
+ * 两点与 Rust 一致、且只看契约看不出来：
+ *
+ * 1. **不落盘 device_id**（见文件头）：这是匿名请求，服务端还没签发任何东西。
+ *    `--dry-run` 时连生成都不生成（报告里 `X-Device-Id` 是 `<未生成>`）。
+ * 2. 号码在请求成功之后写进 profile：凭据失效时的 `hint` 要能给出**完整**的登录命令，
+ *    而号码不是机密（contract §4 的 hint 要求带号码）。
+ */
+async function requestOtp(runtime, phone) {
+  const spec = requestSpec({ body: { phone, purpose: 'login' } });
+  if (runtime.dryRun) {
+    return runtime.dryRunReport('POST', '/auth/otp/request', spec);
+  }
+  const response = await runtime.sendAnonymous('POST', '/auth/otp/request', spec);
+  // `data` 不是对象时（null / 标量 / 数组）Rust 的 `data["k"] = v` 会把它整个换成对象，
+  // 这里用 {} 起手是同一个意思 —— 服务端正常回的是对象，这条只是别在畸形响应上崩掉。
+  const payload = asObject(envelopeData(response));
+  runtime.config.setPhone(phone);
+  runtime.config.save();
+  decorateOtpSent(payload, phone);
+  return runtime.finishFrom(response, payload);
+}
+
+/** 补 `phone_masked` 与 `next_step`（Rust 里就是在 `data` 上原地加这两个键）。 */
+function decorateOtpSent(payload, phone) {
+  payload.phone_masked = maskPhone(phone);
+  if (typeof payload.dev_code === 'string') {
+    // 开发模式（服务端 `OTP_DEV_ECHO`）回显验证码：把完整命令拼好，自动化能直接照抄。
+    payload.next_step =
+      `开发模式已回显验证码。下一步：xinhe-oa-cli login --phone ${phone} --code ${payload.dev_code}`;
+  } else {
+    payload.next_step = `把收到的验证码交给 CLI：xinhe-oa-cli login --phone ${phone} --code <验证码>`;
+  }
+}
+
+/**
+ * `login --adopt-session`：从 stdin 读 install.sh 交接的会话 JSON 并落盘。
+ *
+ * 不联网，所以也没有"服务端说对不对"这一层：交接体里的 `device_id` 必须沿用
+ * （换一个 = 第一次续期就 `auth.device_mismatch`，见 `core/auth.js::adoptSession`）。
+ */
+async function adoptFromStdin(runtime) {
+  const raw = await readStdinText();
+  if (raw.trim().length === 0) {
+    throw CliError.usage('标准输入里没有会话交接体（JSON）').withHint(
+      '用法：echo "$SESSION_JSON" | xinhe-oa-cli login --adopt-session',
+    );
+  }
+  const credential = adoptSession(raw, runtime.baseUrl ?? '');
+  // 交接体里的 base_url 才是这次会话真正的后端：写进 profile。
+  //
+  // 这里**刻意不 `config.save()`**：Rust 的 `adopt_session` 同样只改内存
+  // （它调 `set_current_base_url` 后就 `finish` 了）。落盘的是 credentials.json，
+  // 里面那份 `base_url` 已经跟着凭据走了；config.json 的地址由 install.sh 的
+  // `config --set base_url=…` 负责。两条实现必须一样，否则"同一串操作两边的
+  // 配置文件不同"会在对拍时变成噪声。
+  runtime.config.setCurrentBaseUrl(credential.base_url);
+  runtime.baseUrl = credential.base_url;
+  runtime.credentials.put(runtime.profile, credential);
+
+  return runtime.finish(
+    {
+      adopted: true,
+      profile: runtime.profile,
+      base_url: credential.base_url,
+      device_id: credential.device_id,
+      user: credential.user ?? null,
+      access_token: maskToken(credential.tokens.access_token),
+      next_step: '已经可以直接用了：xinhe-oa-cli me --json',
+      note: '会话由 install.sh 交接；device_id 与 UA 与交接方一致，续期不会被 auth.device_mismatch 拒',
+    },
+    null,
+    null,
+  );
+}
+
+/**
+ * 登录成功后的统一落盘与汇报（`save_and_report`）。
+ *
+ * 顺序与 Rust 一致：先记号码（config.json）、再写凭据（credentials.json）。
+ * 号码写进 profile 是为了让"凭据失效"的 hint 能给出带号码的完整登录命令。
+ */
+function saveAndReport(runtime, credential, method) {
+  credential.updated_at = nowRfc3339();
+  if (credential.phone) {
+    runtime.config.setPhone(credential.phone);
+    runtime.config.save();
+  }
+  runtime.credentials.put(runtime.profile, credential);
+
+  const fileMode = runtime.credentials.fileMode();
+  return runtime.finish(
+    {
+      profile: runtime.profile,
+      base_url: credential.base_url ?? null,
+      user: credential.user ?? null,
+      auth_method: method,
+      device_id: credential.device_id,
+      credentials_file: runtime.paths.credentialsFile,
+      // Rust 是 `format!("{mode:o}")`（八进制字符串）；Windows 上没有这个概念 → null。
+      credentials_file_mode: fileMode === null ? null : fileMode.toString(8),
+      access_token: maskToken(credential.tokens?.access_token ?? ''),
+      refresh_token: maskToken(credential.tokens?.refresh_token ?? ''),
+      access_expires_at: credential.tokens?.access_expires_at ?? null,
+      next_step: '看一下自己是谁、能做什么：xinhe-oa-cli me --json',
+      note: '令牌已落盘（0600）。CLI 之外的任何程序都读不到它，argv 与日志里也没有。',
+    },
+    null,
+    null,
+  );
+}
+
+/** `logout`：吊销会话链 + 删掉本地凭据。 */
+export async function handleLogout({ runtime }) {
+  const credential = runtime.credentials.get(runtime.profile);
+  if (credential === null) {
+    // 本来就没登录：**不是错误**（重复登出是幂等的），更不该为它发一次网络请求。
+    return runtime.finish(
+      { revoked: false, local_credentials_removed: false, note: '本机本来就没有凭据' },
+      null,
+      null,
+    );
+  }
+
+  if (runtime.dryRun) {
+    // 与 Rust 一致：dry-run 只描述"将会发什么"。凭据里只有 access、没有 refresh 时
+    // 也照打 refresh 占位符 —— dry-run 报告是给人看的说明，不是把请求体重放一遍。
+    return runtime.dryRunReport(
+      'POST',
+      '/auth/logout',
+      requestSpec({ body: { refresh_token: '<从凭据文件读，不打印>' } }),
+    );
+  }
+
+  const http = runtime.anonymousHttp();
+  let serverResponse;
+  let warning = null;
+  try {
+    serverResponse = await logoutSession(http, credential);
+  } catch (err) {
+    // 服务端已吊销 / 网络不通 / 令牌过期都不该挡住登出（见文件头）：
+    // 记一句 warning，把本地那枚凭据删干净才是用户要的结果。
+    serverResponse = {};
+    warning = `服务端吊销失败（${err.code}：${err.message}），本地凭据已删除`;
+  }
+  runtime.credentials.remove(runtime.profile);
+
+  return runtime.finish(
+    {
+      revoked: true,
+      local_credentials_removed: true,
+      profile: runtime.profile,
+      server_response: serverResponse,
+      warning,
+    },
+    null,
+    null,
+  );
+}
+
+/** `me`：我是谁、可见企业与门店、角色、能力、缺什么权限。 */
+export async function handleMe({ runtime }) {
+  const response = await runtime.sendAuthed('GET', '/me', requestSpec());
+  const profile = asObjectOrNull(envelopeData(response));
+
+  // 能力清单（`GET /me/endpoints`）：**失败不该挡住 `me`** —— 它是补充信息，
+  // 而"我是谁"已经拿到了。失败只把错误码/消息放进 `endpoints.error` 一起交出去。
+  let endpoints;
+  try {
+    const endpointsResponse = await runtime.sendAuthed('GET', '/me/endpoints', requestSpec());
+    endpoints = asObjectOrNull(envelopeData(endpointsResponse));
+  } catch (err) {
+    // 兜底给一个 code：Rust 的 `err` 必然是 CliError（一定带 code），
+    // 这里万一是别的异常，也不该吐出一个缺键的 error 形状。
+    endpoints = {
+      error: { code: err?.code ?? 'cli.internal', message: err?.message ?? String(err) },
+    };
+  }
+
+  // `capabilities` 只在**键不存在**时兜底成 []（键在但值是 null 就原样给 null）——
+  // 与 Rust 的 `.get(...).cloned().unwrap_or(json!([]))` 同义。
+  const capabilities = endpoints?.capabilities !== undefined ? endpoints.capabilities : [];
+  const hidden = Array.isArray(endpoints?.hidden_endpoints) ? endpoints.hidden_endpoints.length : 0;
+  const catalog = endpoints?.capability_catalog;
+  const missing = Array.isArray(catalog)
+    ? catalog
+        .filter((item) => item?.granted === false)
+        .map((item) => ({
+          capability: item?.capability ?? null,
+          description: item?.description ?? null,
+          how_to_fix:
+            '让企业管理员（tenant_owner）或 super_admin 赋角色：xinhe-oa-cli member --role <你的 user_id>',
+        }))
+    : [];
+
+  const data = {
+    user: profile?.user ?? null,
+    auth: profile?.auth ?? null,
+    scope: profile?.scope ?? null,
+    rate_limits: profile?.rate_limits ?? null,
+    datasets: profile?.datasets ?? null,
+    capabilities,
+    missing,
+    endpoints: {
+      visible: endpoints?.counts?.visible ?? null,
+      hidden,
+      list: endpoints?.endpoints ?? null,
+    },
+    next_steps: [
+      'bitable base --list --json  看自己能访问哪些库',
+      'member --list --json        看本企业的人（企业负责人及以上）',
+      'bitable table --import      上传一份单据（CSV/XLSX）',
+    ],
+  };
+
+  // 人类可读面**补齐身份 / 范围 / 能力 / 缺什么**：通用表格渲染会抓第一个
+  // "对象数组"字段（datasets）当列表，于是 `me` 只剩一张 datasets 表 ——
+  // 而"我是谁、能看什么、能做什么、还缺什么"才是这个命令存在的理由。
+  // `--json` 一个字都不变（机器面稳定）。
+  return runtime.finishFromWithHuman(response, data, (markdown) => meHuman(data, markdown));
+}
+
+/**
+ * `me` 的人类可读视图：把 `--json` 的几个关键段落摆成给人看的样子。
+ *
+ * 口径与 `--json` 完全一致（不多不少）：身份 / 可见范围 / 权限范围 / 能力 /
+ * 接口可见性 / **缺什么** / 下一步。逐行照 Rust 的 `me_human` 拼，
+ * 连"markdown 模式下表格自带尾换行、table 模式下被 trim 掉"这种细节都对齐 ——
+ * 否则 `--format md` 的对拍会差在空行上。
+ */
+function meHuman(data, markdown) {
+  const user = data.user;
+  const auth = data.auth;
+  const scope = data.scope;
+  let out = '';
+
+  // ---- 身份 ----
+  out += '身份\n';
+  out += renderTable(
+    ['字段', '值'],
+    [
+      ['用户', textOf(user?.name)],
+      ['user_id', textOf(user?.id)],
+      ['角色', textOf(user?.roles)],
+      ['bootstrap', textOf(user?.is_bootstrap)],
+      ['认证方式', textOf(auth?.method)],
+      ['会话', textOf(auth?.session_id)],
+      [
+        '令牌有效期',
+        `access ${textOf(auth?.access_token_ttl_seconds)}s / refresh ${textOf(auth?.refresh_token_ttl_seconds)}s`,
+      ],
+    ],
+    markdown,
+  );
+
+  // ---- 可见范围 ----
+  out += '\n可见范围\n';
+  const pending = scope?.pending_endorsements;
+  const pendingText =
+    !Array.isArray(pending) || pending.length === 0
+      ? '—'
+      : `${textOf(pending)}（共 ${pending.length} 家：企业还没背书，所以看不到 —— 不是没权限，是等对方确认）`;
+  out += renderTable(
+    ['字段', '值'],
+    [
+      [
+        '企业',
+        scope?.is_super_admin === true
+          ? `${textOf(scope?.tenants)}（super_admin：全部）`
+          : textOf(scope?.tenants),
+      ],
+      ['门店', textOf(scope?.stores)],
+      ['待背书企业', pendingText],
+      ['权限范围', `${Array.isArray(scope?.scopes) ? scope.scopes.length : 0} 条（下面逐条列出）`],
+    ],
+    markdown,
+  );
+
+  // ---- 权限范围（逐条）----
+  const scopes = Array.isArray(scope?.scopes) ? scope.scopes.map(textOf) : [];
+  out += `\n权限范围（${scopes.length} 条）\n`;
+  if (scopes.length === 0) {
+    out += '（一条都没有：默认拒绝，找企业管理员赋角色）\n';
+  } else {
+    out += renderTable(['scope'], scopes.slice(0, SCOPE_CAP).map((item) => [item]), markdown);
+    if (scopes.length > SCOPE_CAP) {
+      out += `\n（只列前 ${SCOPE_CAP} 条；${scopes.length} 条完整清单用 --json）\n`;
+    } else {
+      out += '\n';
+    }
+  }
+
+  // ---- 能力 ----
+  const capabilities = Array.isArray(data.capabilities) ? data.capabilities.map(textOf) : [];
+  out += `能力（${capabilities.length} 项）\n`;
+  if (capabilities.length === 0) {
+    out += '（还没有任何接口级能力）\n';
+  } else {
+    out += renderTable(['capability'], capabilities.map((item) => [item]), markdown);
+    out += '\n';
+  }
+  out +=
+    `接口可见性：可见 ${textOf(data.endpoints?.visible)} 个 / 隐藏 ${textOf(data.endpoints?.hidden)} 个` +
+    '（完整清单见 `me --json` 的 endpoints）\n';
+
+  // ---- 缺什么 ----
+  const missing = Array.isArray(data.missing) ? data.missing : [];
+  out += `\n缺什么（${missing.length} 项）\n`;
+  if (missing.length === 0) {
+    out += '（没有缺的权限：上面列出的就是你现在的全部能力）\n';
+  } else {
+    out += renderTable(
+      ['capability', '说明', '怎么拿到'],
+      missing.map((item) => [
+        textOf(item?.capability),
+        textOf(item?.description),
+        textOf(item?.how_to_fix),
+      ]),
+      markdown,
+    );
+    out += '\n';
+  }
+
+  // ---- 下一步 ----
+  const steps = data.next_steps;
+  if (Array.isArray(steps) && steps.length > 0) {
+    out += '\n下一步\n';
+    for (const step of steps) out += `- ${textOf(step)}\n`;
+  }
+  return out.trimEnd();
+}
+
+/**
+ * 值的单行文本（`null` / 空串 / 空数组 → `—`，与人类可读表格的空值口径一致）。
+ *
+ * 对象取 `名字（id）`：服务端的 `scope.tenants` / `scope.stores` 是
+ * `{"id":…,"name":…,"status":…}` 这样的对象数组，把 JSON 原样摊进表格没法看。
+ */
+function textOf(value) {
+  if (value === null || value === undefined) return '—';
+  if (typeof value === 'string') return value.length === 0 ? '—' : value;
+  if (typeof value === 'boolean') return value ? 'true' : 'false';
+  if (typeof value === 'number') return String(value);
+  if (Array.isArray(value)) {
+    return value.length === 0 ? '—' : value.map(textOf).join(', ');
+  }
+  if (typeof value === 'object') {
+    const name = typeof value.name === 'string' ? value.name : null;
+    const id = typeof value.id === 'string' ? value.id : null;
+    if (name !== null && id !== null) return `${name}（${id}）`;
+    if (name !== null) return name;
+    if (id !== null) return id;
+    // 兜底：Rust 的 serde_json Map 是 BTreeMap（键有序），这里也排一遍键，
+    // 免得同一个对象在两种实现下打印出不同的键序。
+    return JSON.stringify(sortKeysDeep(value));
+  }
+  return String(value);
+}
+
+/** 服务端的 `data` 不是对象时（null / 标量 / 数组），Rust 的 `data["k"] = v` 会把它整个换成对象。 */
+function asObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : {};
+}
+
+/** 只读用：非对象一律当"没有"（后续全是可选链，`null` 比 `{}` 更能表达"服务端没给"）。 */
+function asObjectOrNull(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value) ? value : null;
+}
+
+/** 读完整个 stdin（`--adopt-session` 的 JSON 可能是多行的）。 */
+async function readStdinText() {
+  const chunks = [];
+  for await (const chunk of process.stdin) {
+    chunks.push(typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk);
+  }
+  return Buffer.concat(chunks).toString('utf8');
+}