@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/core/args.js

@@ -0,0 +1,901 @@
+// 参数解析（对齐 Rust 版 clap 的接受面与报错口径）。
+//
+// 三条硬规矩，与 Rust 版逐条对应：
+//
+// 1. **参数即约束**：能力面由 `src/spec/command_surface.json`（从 Rust 产物生成，
+//    见 `scripts/gen-spec.py`）决定。解析不出来的旗标一律**退出码 2、不发请求** ——
+//    绝没有"任意旗标透传"这种口子。
+// 2. **多动作 / 缺动作是用法错误**：`bitable base --list --create` 与
+//    `bitable base`（什么都不给）都在本地判死（退出码 2）。
+// 3. **高风险写操作必须 `--yes`**：`schema` 里 `requires_yes=true` 的命令少了它，
+//    同样退出码 2 并明确提示"要加 --yes"。这条检查在**发请求之前**做。
+
+import { readFileSync } from 'node:fs';
+import { CliError, Kind } from './error.js';
+
+/** 全局旗标（对所有子命令生效，位置任意）。 */
+export const GLOBAL_FLAGS = Object.freeze({
+  '--base-url': { key: 'baseUrl', value: 'URL' },
+  '--profile': { key: 'profile', value: 'NAME' },
+  '--json': { key: 'json', bool: true },
+  '--dry-run': { key: 'dryRun', bool: true },
+  '--yes': { key: 'yes', bool: true },
+  '--timeout': { key: 'timeout', value: 'SECONDS' },
+  '-v': { key: 'verbose', bool: true },
+  '--verbose': { key: 'verbose', bool: true },
+  '--quiet': { key: 'quiet', bool: true },
+  '--no-color': { key: 'noColor', bool: true },
+  '--format': { key: 'format', value: 'FORMAT' },
+  '--help': { key: 'help', bool: true },
+  '-h': { key: 'help', bool: true },
+  '--version': { key: 'version', bool: true },
+  '-V': { key: 'version', bool: true },
+});
+
+const SURFACE_URL = new URL('../spec/command_surface.json', import.meta.url);
+
+let cachedSurface = null;
+
+/** 命令面规格（懒加载 + 缓存；只在进程内读一次）。 */
+export function commandSurface() {
+  if (cachedSurface === null) {
+    cachedSurface = JSON.parse(readFileSync(SURFACE_URL, 'utf8'));
+  }
+  return cachedSurface;
+}
+
+/**
+ * 规格里的每条命令 → 便于查询的形状。
+ *
+ * 旗标来自两处，缺一不可：
+ *   * `params`：`schema --json` 登记过的（人读的那份）；
+ *   * `extra_flags`：**源码里有、schema 没登记**的布尔旗标（`config --show` 就是）——
+ *     漏掉它会把合法命令判成"不认识这个旗标"（本项目第一次自测的翻车点）。
+ * 另有 `rejected_flags`：属于**兄弟子命令**的动作旗标，本命令必须拒
+ * （`member --list --offboard x` 在 Rust 版是用法错误）。
+ */
+function indexSurface(surface) {
+  const commands = surface.commands.map((entry) => {
+    const tokens = entry.name.split(' ');
+    const flags = new Map();
+    const add = (flag, shape) => {
+      const existing = flags.get(flag) ?? {
+        takesValue: false,
+        variadic: false,
+        optional: true,
+        sourceShape: null,
+        placeholder: '',
+      };
+      flags.set(flag, {
+        takesValue: existing.takesValue || shape.takesValue,
+        variadic: existing.variadic || shape.variadic,
+        optional: existing.optional && shape.optional,
+        sourceShape: shape.sourceShape ?? existing.sourceShape,
+        placeholder: shape.placeholder || existing.placeholder,
+      });
+    };
+
+    // 散文那侧（`schema --json` 的 `params`）：只用来定"必填/可选"与占位符 ——
+    // **取值吃不吃下一个词一律以源码事实为准**（见下），因为散文里
+    // `--offboard <USER_ID>` 会被写成裸 `--offboard`。
+    const declared = new Set();
+    for (const param of entry.params) {
+      if (!param.flag) continue;
+      declared.add(param.flag);
+      add(param.flag, {
+        takesValue: false,
+        variadic: Boolean(param.variadic),
+        optional: Boolean(param.optional),
+        placeholder: param.value ?? '',
+      });
+    }
+    for (const flag of entry.extra_flags ?? []) {
+      declared.add(flag);
+      add(flag, { takesValue: false, optional: true });
+    }
+
+    // 必填只认真·必填：散文里写着必填、**且**源码类型不是 `Option`/`Vec` 的。
+    //
+    // 两个坑都在这里躲开：
+    //   * `member --search` 的散文写的是 `--name <TEXT> --phone <PHONE> --dept <DEPT_ID>`
+    //     （三个都没加方括号），但契约是"**至少给一个**"—— 当三个都必填校验，
+    //     合法调用会被判死。`Option<String>` 在 clap 里天然可选，所以以源码为准。
+    //   * 全局旗标（`--yes` / `--dry-run`）由 `extractGlobals()` 提前摘走，
+    //     算成必填会让 33 条 `requires_yes` 的命令**永远**解析失败。
+    const requiredFlags = entry.params
+      .filter((param) => param.flag && !param.optional && !(param.flag in GLOBAL_FLAGS))
+      .filter((param) => {
+        const shape = (entry.flags ?? {})[param.flag];
+        // 源码类型是 `Option`/`Vec` ⇒ clap 层面可选，散文里的"没加方括号"不算数
+        // （`member --search` 的 `--name/--phone/--dept` 就是"至少给一个"）。
+        // 有默认值的（`--resource-type` → `record`）同样不必给。
+        if (shape !== undefined && shape.optional_value === true) return false;
+        return shape === undefined || shape.required === true;
+      })
+      .map((param) => param.flag);
+
+    // 源码事实那侧（`spec.flags` 来自 `args.rs` 的字段类型）：
+    // **取值语义以它为准，但只对它声明的旗标生效**。
+    //
+    // 两件事必须分开：
+    //   * **有哪些旗标** → 以**本命令的 `params`（散文）**为准。`spec.flags` 是整个
+    //     结构体的旗标表，而 `MemberArgs` 一个结构体承载 16 条命令；拿它当"这条命令
+    //     接受什么"，`member --list --reason x` 也会被放过去（clap 按子命令校验，会拒）。
+    //   * **吃不吃取值** → 以源码为准。散文里 `--offboard <USER_ID>` 可能被写成裸
+    //     `--offboard`，照散文解析会把 `member --offboard usr_x` 读成"裸旗标 + 位置参数"。
+    for (const flag of flags.keys()) {
+      const shape = (entry.flags ?? {})[flag];
+      // 全局旗标一般由 `extractGlobals()` 提前摘走，不在这里定形状。
+      // **例外**：源码说它是取值型业务参数（`report rule --update --version 3` 的
+      // `--version`）—— 那就得让它有形状，否则"它吃不吃取值"永远是 false，
+      // `--version` 的取值会掉进位置参数、请求体里丢掉 version。
+      if (flag in GLOBAL_FLAGS && shape?.takes_value !== true) continue;
+      if (shape === undefined || shape.takes_value !== true) continue;
+      add(flag, {
+        takesValue: true,
+        // **有默认值的旗标也是可选**（clap 的 `default_value = "record"`）：
+        // 散文里 `--resource-type <record>` 没写方括号，但"不给就用默认值"。
+        optional: shape.optional_value === true || shape.optional === true,
+        sourceShape: shape.optional_value === true ? 'optional' : 'required',
+      });
+    }
+
+    // `args.rs` 的 `only(...)` 白名单：**它约束的是"业务参数"，不是动作旗标**
+    // （`report --list` 的白名单里没有 `--list`，但 `--list` 当然是这条命令的一部分）。
+    // 所以判据是"在命令自己的旗标表里 **且**（在白名单里 **或** 是动作旗标）"。
+    // **同义词**：同族命令的另一个名字旗标（`member --set-manager` ↔ `--clear-manager`）。
+    // 它们与命令名里的旗标同等看待：可以写、算动作。
+    const synonyms = new Set(entry.synonym_flags ?? []);
+    for (const flag of synonyms) {
+      if (!flags.has(flag)) add(flag, { takesValue: false, optional: true });
+    }
+
+    // 动作旗标 = 命令名里出现的那些 + 旗标表里不吃取值的那些。
+    // **命令名里出现的一律无条件允许**：`report --show <ID>` / `bitable table --show <ID>`
+    // 的动作旗标本身就吃取值，只按"不吃取值"判会把它们判成"不认识"。
+    const actionFlagNames = new Set([
+      ...actionFlagNamesOf({ tokens, flags }),
+      ...(entry.synonym_flags ?? []),
+    ]);
+    const allowed = (entry.allowed_flags ?? []).filter((flag) => !(flag in GLOBAL_FLAGS));
+    const allowedNames = allowed.length > 0 ? new Set(allowed) : null;
+
+    return {
+      entry,
+      tokens,
+      flags,
+      allowedNames,
+      actionFlagNames,
+      // 必填 = 散文里必填的 + 命令名里的动作旗标（`org --move` 的 `--move`）。
+      requiredFlags: [
+        ...new Set([...requiredFlags, ...tokens.filter((token) => token.startsWith('-'))]),
+      ],
+      // 同义词从"被拒"里摘掉：`--clear-manager` 是**这条命令**的备选写法，
+      // 不是"别的命令的动作"（命令层用它来分流 `--set-manager` / `--clear-manager`）。
+      rejected: new Set((entry.rejected_flags ?? []).filter((flag) => !synonyms.has(flag))),
+      name: entry.name,
+    };
+  });
+  // 出现在**某条命令名里**的旗标（`org --archive`、`file --visibility`、`schema --agent`）
+  // 与"会吃掉下一个词的旗标"，都是命令名收集要用的信息。
+  const nameFlags = new Set();
+  const requiredAnywhere = new Set();
+  const optionalAnywhere = new Set();
+  for (const command of commands) {
+    for (const token of command.tokens) {
+      if (token.startsWith('-')) nameFlags.add(token);
+    }
+    // 同义词也是"可以出现在名字位置"的旗标（`member --clear-manager`）。
+    for (const flag of command.entry.synonym_flags ?? []) nameFlags.add(flag);
+    for (const [flag, shape] of Object.entries(command.entry.flags ?? {})) {
+      if (shape.takes_value !== true) continue;
+      if (shape.optional_value === true) optionalAnywhere.add(flag);
+      else requiredAnywhere.add(flag);
+    }
+  }
+  // 被**任何命令**声明成取值型业务参数的旗标名。目前只有 `--version`
+  // （顶层是 `-V/--version`，`report rule --update` 拿来当乐观锁版本号）。
+  const commandValueFlags = new Set();
+  for (const command of surface.commands) {
+    for (const [flag, shape] of Object.entries(command.flags ?? {})) {
+      if (shape.takes_value === true) commandValueFlags.add(flag);
+    }
+  }
+
+  // 名字收集时的"到此为止"判据：**只在任何命令里都吃取值**的旗标才算（`--visibility`）。
+  // 取值可省的（`--show`）不算 —— 否则 `file --show att_1` 会被读成
+  // `file --visibility <ID> --show` 那种形状（本项目的真实翻车点）。
+  const valueTaking = new Set(
+    [...requiredAnywhere].filter((flag) => !optionalAnywhere.has(flag)),
+  );
+  // 同族命令的名字旗标同义词（`--clear-manager` 之于 `member --set-manager`）。
+  // 键是旗标名，值是**它以命令名身份出现时对应的那条规格**。
+  const synonymFlags = new Set();
+  const synonymTargets = new Map();
+  // 索引后的候选名（`commands` 此时已经有 `tokens` 了）。
+  for (const command of commands) {
+    for (const flag of command.entry.synonym_flags ?? []) {
+      synonymFlags.add(flag);
+      // 把它换掉命令名里**最后一个**旗标，其余词不动 ——
+      // `member --set-manager` + `--clear-manager` → `member --clear-manager`。
+      const lastFlag = command.tokens.filter((token) => token.startsWith('-')).pop();
+      if (lastFlag === undefined) continue;
+      const replaced = [
+        ...command.tokens.slice(0, command.tokens.lastIndexOf(lastFlag)),
+        flag,
+      ].join(' ');
+      synonymTargets.set(replaced, { name: replaced, target: command.name });
+    }
+  }
+
+  return {
+    surface,
+    commands,
+    nameFlags,
+    synonymFlags,
+    synonymTargets,
+    valueTaking,
+    requiredValueFlags: valueTaking,
+    commandValueFlags,
+  };
+}
+
+/**
+ * 这个旗标在**这条命令**里吃不吃取值（`'required'` / `'optional'` / `null`）。
+ *
+ * 必须是**每条命令各算**：`--show` 在 `bitable table --show <ID>` 里吃取值，
+ * 在 `file --visibility <ID> --show` 里是裸旗标。用一张全局的"哪些旗标吃取值"表，
+ * 两种写法里必然有一种被解析错（本项目踩过）。
+ */
+function valueShapeOf(declared, flag) {
+  if (declared === undefined) return null;
+  if (declared.sourceShape === 'required' || declared.sourceShape === 'optional') {
+    return declared.sourceShape;
+  }
+  return null;
+}
+
+/** 最近一次解析的 argv（仅供报错排序用；CLI 是单次进程，没有并发问题）。 */
+let lastArgv = [];
+
+let cachedIndex = null;
+
+function surfaceIndex() {
+  if (cachedIndex === null) cachedIndex = indexSurface(commandSurface());
+  return cachedIndex;
+}
+
+/** 全局旗标先摘出来（它们在命令行里的位置是任意的）。 */
+function extractGlobals(argv) {
+  const globals = {
+    baseUrl: null,
+    profile: null,
+    json: false,
+    dryRun: false,
+    yes: false,
+    timeout: null,
+    verbose: false,
+    quiet: false,
+    noColor: false,
+    format: null,
+    help: false,
+    version: false,
+  };
+  const rest = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    const equal = token.startsWith('--') ? token.indexOf('=') : -1;
+    const name = equal > 0 ? token.slice(0, equal) : token;
+    const spec = GLOBAL_FLAGS[name];
+    if (!spec) {
+      rest.push(token);
+      continue;
+    }
+    // `--version` 是顶层 `-V/--version` 与某些命令的业务参数（`report rule --update
+    // --version 3` 是乐观锁版本号）**同名**。Rust/clap 那里命令级声明覆盖全局；
+    // 这里必须照做 —— 无条件把它当全局旗标，那 3 就掉进位置参数、请求体里没有 version。
+    // 判据：这个旗标被某条命令声明成取值型 **且** 后面确实跟着取值
+    // （只看前者的话，裸 `xinhe-oa-cli --version` 也会被当业务参数，版本号就打不出来）。
+    if (surfaceIndex().commandValueFlags.has(name)) {
+      // `--version=4` 与 `--version 4` 两种写法都要留给命令解析：
+      // 前者拆成两个 token（后面对命令来说是"取值"），否则 `4` 会连着 `=` 一起丢，
+      // 命令层拿不到版本号 —— `file --download --version 4` 会**静默下最新版**。
+      if (equal > 0) {
+        rest.push(name, token.slice(equal + 1));
+        continue;
+      }
+      const next = argv[index + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        rest.push(token);
+        continue;
+      }
+    }
+    if (spec.bool) {
+      globals[spec.key] = true;
+      continue;
+    }
+    if (equal > 0) {
+      globals[spec.key] = token.slice(equal + 1);
+      continue;
+    }
+    const next = argv[index + 1];
+    if (next === undefined || next.startsWith('--')) {
+      throw CliError.usage(`\`${name}\` 需要一个取值`).withHint(
+        `例：xinhe-oa-cli ${name} <${spec.value ?? '值'}>`,
+      );
+    }
+    globals[spec.key] = next;
+    index += 1;
+  }
+  return { globals, rest };
+}
+
+/**
+ * 找命令（对齐 Rust 侧"最长命令名优先，再看哪条参数面能容下这些旗标"）。
+ *
+ * 命令名的形状是 `<域> [<资源>] --<动作>`：**动作是名字的一部分**（`org --archive`、
+ * `file --visibility --set`）。所以"名字 token"不能只收第一个旗标之前的那几个词 ——
+ * 那样 `org --archive ou_1` 只会拿 `org` 去匹配，最后撞在 `org --tree 不认识 --archive`
+ * 上（本项目踩过的真实缺陷）。规则：逐个词看，**不带取值的旗标**算名字的一部分，
+ * 带取值的旗标从它开始就是参数了。
+ */
+function nameTokens(rest) {
+  const { commands, nameFlags, synonymFlags, valueTaking } = surfaceIndex();
+  const names = commands.map((command) => command.name.split(' '));
+  const words = [];
+
+  const wordsSoFar = () => words.map((word) => word.token);
+
+  /** 当前收到的这些词，**恰好**是某条命令名（收完了）。 */
+  const completesSomeName = () => {
+    const joined = wordsSoFar().join(' ');
+    return names.some((tokens) => tokens.join(' ') === joined);
+  };
+
+  /** 当前收到的这些词，还是某条命令名的前缀（还能继续收）。 */
+  const prefixesSomeName = () => {
+    const joined = wordsSoFar().join(' ');
+    return names.some(
+      (tokens) => tokens.join(' ').startsWith(joined) && tokens.length > words.length,
+    );
+  };
+
+  for (const [index, token] of rest.entries()) {
+    if (token.startsWith('-')) {
+      if (GLOBAL_FLAGS[token]) break;
+      if (!nameFlags.has(token) && !synonymFlags.has(token)) break;
+      words.push({ token, index, flag: true });
+      // **命令名收完就停**：`org --explain-scope --user usr_1` 里 `--user` 是参数，
+      // 继续往名字里塞会让参数解析跳过它、取值掉进位置参数（本项目刚踩的坑）。
+      if (completesSomeName() && !prefixesSomeName()) break;
+      // 取值型的名字旗标（`--delete <ID>`）：它的取值**也要收进来**（标成
+      // `flag: false`），否则 `consumeCommandPrefix` 找不到它。
+      // 判据只看"后面那个词是不是旗标"：`--clear-manager --user usr_1` 里
+      // `--user` 是旗标，不会被误当成取值。
+      if (valueTaking.has(token)) {
+        const value = rest[index + 1];
+        if (value !== undefined && !value.startsWith('-')) {
+          words.push({ token: value, index: index + 1, flag: false });
+        }
+        break;
+      }
+      continue;
+    }
+    words.push({ token, index, flag: false });
+    if (completesSomeName() && !prefixesSomeName()) break;
+  }
+  return words;
+}
+
+/**
+ * 命令名吃掉了 `words` 里的前几个词，剩下的才是命令参数。
+ *
+ * 关键点：**只有真正属于命令名的那几个旗标词才算"被吃掉"**。`org --archive ou_1`
+ * 里 `--archive` 既是名字的一部分、又要被解析成动作旗标 —— 直接按词数切，
+ * 命令参数就从 `ou_1` 之后开始了，解析器于是抱怨"必须带 --archive"（本项目踩过）。
+ */
+function consumeCommandPrefix(words, candidateName) {
+  const nameTokensList = candidateName.split(' ');
+  const actions = [];
+  const consumed = new Set();
+  let index = 0;
+  for (const word of words) {
+    if (nameTokensList[index] === word.token) {
+      // **只吃非旗标的名字词**（`file` / `bitable` / `table`）：它们是命令名的骨架，
+      // 不该出现在位置参数里。
+      if (!word.flag) consumed.add(word.index);
+      // 旗标（`--visibility` / `--delete` / `--show` / `--tree`…）一律**留在 tokens 里**，
+      // 由 `parseCommandArgs` 的主循环按"这条命令的旗标表"统一解析 ——
+      // 那样取值、布尔、可省取值三种形状都只有一处判据。
+      // 只有"名字末尾的裸旗标"（`file --visibility --show` 的 `--show`）需要在这里
+      // 记一笔：它不是名字 token、但要算进这条命令的动作里。
+      index += 1;
+      if (index === nameTokensList.length) {
+        const next = words[words.indexOf(word) + 1];
+        if (next !== undefined && next.flag) actions.push(next.token);
+        break;
+      }
+      continue;
+    }
+    if (!word.flag) break;
+  }
+  return { consumed, actions };
+}
+
+/**
+ * 解析命令行。
+ *
+ * 返回 `{ globals, command, args, positional }`：
+ *   * `command` 是命中的规格条目（`name` / `risk` / `requires_yes` / `endpoints`）；
+ *   * `args` 是旗标 → 取值（布尔旗标为 `true`，可重复的是数组）；
+ *   * `positional` 是位置参数（只有 `schema [COMMAND]` 用得上）。
+ */
+/**
+ * 找出可能的命令：拿 argv 开头那些词（含命令名里的旗标）去跟规格里的命令名对齐，
+ * 取"最长的那段前缀"命中的全部候选。
+ *
+ * 例：`file --visibility att_1 --show` → 前缀 `file --visibility` 命中两条
+ * （`file --visibility --show` / `--set`），由后面的排序决定是哪一条。
+ */
+function candidatesFor(rest) {
+  const { commands } = surfaceIndex();
+
+  const words = nameTokens(rest);
+  const tokens = words.map((word) => word.token);
+  const { synonymTargets } = surfaceIndex();
+  for (let take = tokens.length; take >= 1; take -= 1) {
+    const prefix = tokens.slice(0, take).join(' ');
+    // **同义词旗标**（`member --clear-manager`）：没有哪条命令叫这个名字，
+    // 它对应的其实是 `member --set-manager`。查表换过去、按目标名取候选 ——
+    // 这一步必须在"名字前缀匹配"**之前**：同义词前缀永远匹配不上任何命令名，
+    // 放在后面会被 `continue` 跳过（本项目刚踩的坑）。
+    const synonym = synonymTargets.get(prefix);
+    if (synonym !== undefined) {
+      const target = commands.filter((command) => command.name === synonym.target);
+      if (target.length > 0) return { matched: target, words };
+    }
+    const matched = commands.filter(
+      (command) => command.name === prefix || command.name.startsWith(`${prefix} `),
+    );
+    if (matched.length === 0) continue;
+    return { matched, words };
+  }
+  return { matched: [], words };
+}
+
+export function parseArgv(argv) {
+  const { globals, rest } = extractGlobals(argv);
+  // `--help` 先于一切取值的合法性检查：clap 也是这样 ——
+  // `login --phone --help` 该打出帮助，而不是抱怨"`--phone` 需要一个取值"。
+  if (globals.help) return { globals, command: null, args: {}, positional: [] };
+  if (globals.version && rest.length === 0) return { globals, command: null, args: {}, positional: [] };
+  if (rest.length === 0) {
+    throw CliError.usage('缺命令').withHint(
+      '看全部命令：xinhe-oa-cli schema；最短上手：xinhe-oa-cli login --phone <号码>',
+    );
+  }
+
+  const { matched, words } = candidatesFor(rest);
+  if (matched.length === 0) {
+    const domain = rest.find((token) => !token.startsWith('-'));
+    if (domain === undefined) {
+      throw CliError.usage(`不认识的旗标 ${JSON.stringify(rest[0])}`).withHint(
+        '看全部命令：xinhe-oa-cli schema',
+      );
+    }
+    throw CliError.usage(`不认识的命令 ${JSON.stringify(domain)}`).withHint(
+      '看全部命令：xinhe-oa-cli schema',
+    );
+  }
+
+  const errors = [];
+  const parsedCandidates = [];
+  lastArgv = rest;
+  for (const candidate of matched) {
+    // 每条候选名吃掉的名字长度不同（`org --move` 吃两个词、`org` 只吃一个词），
+    // 所以要**按候选**算命令参数；而且必须切 `rest` 而不是 `words` ——
+    // 带取值的旗标不在 `words` 里，按词数切会把它们的取值丢掉。
+    // 命令名吃掉的是**具体的几个 token**（不是"前 N 个"）：`file --show att_1` 里
+    // `--show` 属于名字、`att_1` 是它的取值，按界限切就会把取值一起切掉。
+    const { consumed, actions } = consumeCommandPrefix(words, candidate.name);
+    const commandArgs = rest.filter((_, position) => !consumed.has(position));
+    try {
+      const parsed = parseCommandArgs(candidate, commandArgs, globals, actions);
+      if (parsed === null) continue; // 缺取值：留给同命令的其他候选
+      parsedCandidates.push({ candidate, ...parsed });
+    } catch (err) {
+      if (err instanceof CliError) err.candidateName = candidate.name;
+      errors.push(err);
+    }
+  }
+  if (parsedCandidates.length > 0) {
+    // 变体选择（**只按"名字里的旗标"判**，不看参数面容不容得下 ——
+    // 同一个结构体的兄弟命令参数面彼此容得下，那是误判的来源）：
+    //   0) **名字里的动作旗标被调用方写上了**（`attachment --delete <ID>` 的 `--delete`）
+    //      —— 这是最硬的信号，写了它就是这条命令，权重给足；
+    //   1) 名字里缺的动作旗标越少越好；
+    //   2) 名字与 argv 前缀吻合越长越好（`file --visibility --show` 胜过 `file --show`）；
+    //   3) 用上的旗标越多越具体；4) 可选旗标占比越低越专用。
+    parsedCandidates.sort((left, right) => {
+      const byAction = matchedNameFlags(right) * 1000 - matchedNameFlags(left) * 1000;
+      if (byAction !== 0) return byAction;
+      const byActionMissing = missingActionCount(left) * 100 - missingActionCount(right) * 100;
+      if (byActionMissing !== 0) return byActionMissing;
+      const byRequiredMissing = missingRequiredCount(left) * 10 - missingRequiredCount(right) * 10;
+      if (byRequiredMissing !== 0) return byRequiredMissing;
+      const byName = nameMatchLength(right) - nameMatchLength(left);
+      if (byName !== 0) return byName;
+      const byFlags = providedFlagCount(right) - providedFlagCount(left);
+      if (byFlags !== 0) return byFlags;
+      return optionalRatio(left.candidate) - optionalRatio(right.candidate);
+    });
+    // **变体只挑"动作齐了"的那些**：`file --visibility <ID> --set internal` 同时能被
+    // `file --visibility --show` 与 `… --set` 容下，但前者要求 `--show`（没给就把它排除）。
+    // 少了这道过滤，`attachment --delete <ID>` 会被判给 `attachment --upload`
+    // （两者同属一个结构体、参数面彼此容得下），错误文案于是指到别的命令上。
+    const complete = parsedCandidates.filter((item) => missingActionCount(item) === 0);
+    const best = (complete.length > 0 ? complete : parsedCandidates)[0];
+    return { globals, command: best.candidate, args: best.args, positional: best.positional };
+  }
+  // 没有一条参数面能容下：报**最贴切**那条命令的错。
+  // 判据：动作旗标给得越多越贴切（`attachment --delete <ID>` 的错要来自
+  // `attachment --delete`，而不是同结构体的 `attachment --upload`）。
+  const ranked = [...errors].sort(
+    (left, right) => actionHitsOf(right) - actionHitsOf(left),
+  );
+  throw ranked[0] ?? CliError.usage('参数不对');
+}
+
+/**
+ * 调用方写的旗标里，有几个出现在这条候选的**命令名**里。
+ *
+ * 这是"他要的是哪个动作"最直接的回答：`org --move ou_1 --parent ou_2` 里
+ * argv 有 `--move`，而 `org --move` 的名字里也有它 —— 1 分；`org --create` 是 0 分。
+ */
+function matchedNameFlags(parsed) {
+  let hits = 0;
+  for (const token of parsed.candidate.tokens) {
+    if (!token.startsWith('-')) continue;
+    const declared = parsed.candidate.flags.get(token);
+    const written = declared?.takesValue
+      ? parsed.args[token] !== undefined && parsed.args[token] !== true
+      : parsed.args[token] === true;
+    if (written) hits += 1;
+  }
+  return hits;
+}
+
+/**
+ * 这条候选缺了几个**必填旗标**（散文里必填的 + 命令名里的动作旗标）。
+ *
+ * "命令名里的动作旗标"要算进去：`attachment --upload` 的 `--upload` 在散文里被写成
+ * 裸旗标（必填），但它其实写在命令名里、不会出现在 `args` 里 —— 不算进去，
+ * 就会在一条**别的**候选上抛"`attachment --upload` 必须带 --upload"。
+ */
+function missingRequiredCount(parsed) {
+  let missing = 0;
+  for (const flag of parsed.candidate.requiredFlags) {
+    if (parsed.args[flag] === undefined) missing += 1;
+  }
+  for (const token of parsed.candidate.tokens) {
+    if (!token.startsWith('-')) continue;
+    const declared = parsed.candidate.flags.get(token);
+    if (declared?.takesValue) {
+      if (parsed.args[token] === undefined || parsed.args[token] === true) missing += 1;
+    } else if (parsed.args[token] !== true) {
+      missing += 1;
+    }
+  }
+  return missing;
+}
+
+/** 这条候选的**动作**齐不齐（只看动作旗标，不看普通必填参数）。 */
+function missingActionCount(parsed) {
+  let missing = 0;
+  for (const token of parsed.candidate.tokens) {
+    if (!token.startsWith('-')) continue;
+    const declared = parsed.candidate.flags.get(token);
+    if (declared?.takesValue) {
+      if (parsed.args[token] === undefined || parsed.args[token] === true) missing += 1;
+    } else if (parsed.args[token] !== true) {
+      missing += 1;
+    }
+  }
+  return missing;
+}
+
+/**
+ * 报错排序用：这条错误对应的候选，动作旗标被调用方写了几个。
+ *
+ * `errors` 里存的是 `CliError`，它身上带着出错时那条候选的名字；
+ * 名字里的旗标有几个出现在原始 argv 里，就是几个"动作命中"。
+ */
+function actionHitsOf(error) {
+  const name = error?.candidateName ?? '';
+  let hits = 0;
+  for (const token of name.split(' ')) {
+    if (token.startsWith('-') && lastArgv.includes(token)) hits += 1;
+  }
+  return hits;
+}
+
+/** 命令名与 argv 前缀吻合到第几个词（越长说明这条候选越贴切）。 */
+function nameMatchLength(parsed) {
+  let length = 0;
+  for (const token of parsed.candidate.tokens) {
+    if (parsed.args[token] !== undefined || !token.startsWith('-')) length += 1;
+    else break;
+  }
+  return length;
+}
+
+/** 这条候选命令"被用上了几个旗标"（越多越具体）。 */
+function providedFlagCount(parsed) {
+  return Object.keys(parsed.args).length;
+}
+
+/**
+ * 候选**自己声明的**旗标里，有几个被调用方用上了。
+ *
+ * 这是"哪条命令更贴切"最直接的信号：`member --offboard usr_x --reason 离职 --yes`
+ * 同时能被 `--list` / `--grants` / `--transfer-list` 容下（它们只看"有没有不认识的旗标"），
+ * 但只有 `--offboard` 自己声明的旗标全被用上了。
+ */
+function ownMatchCount(parsed) {
+  let hits = 0;
+  for (const flag of parsed.candidate.flags.keys()) {
+    // 被拒的兄弟动作旗标不算"命中"：`member --offboard usr_x` 里 `--offboard`
+    // 在 `member --list` 的旗标表里也存在，但那只是同一个结构体的兄弟动作。
+    if (parsed.candidate.rejected.has(flag)) continue;
+    // **只算动作旗标**（命令名里出现的那些）。把可选参数也算进来会让
+    // "参数恰好同形"的候选追平真实候选，最后靠名字长度分胜负 ——
+    // `org --move <ID> --parent <ID>` 就是这么被判给 `org --explain-scope` 的。
+    if (parsed.actionFlags === undefined) {
+      parsed.actionFlags = new Set(
+        parsed.candidate.entry.params
+          .filter((param) => param.flag && !param.optional && param.value === undefined)
+          .map((param) => param.flag),
+      );
+    }
+    if (!parsed.actionFlags.has(flag)) continue;
+    if (parsed.args[flag] !== undefined) hits += 1;
+  }
+  return hits;
+}
+
+/** 可选旗标占比：越小越"专用"（`config --show` 是 0，`config --list` 是 1/4）。 */
+function optionalRatio(candidate) {
+  const total = candidate.flags.size;
+  if (total === 0) return 0;
+  let optional = 0;
+  for (const spec of candidate.flags.values()) if (spec.optional) optional += 1;
+  return optional / total;
+}
+
+/** 动作旗标个数（`--list` / `--show` 这类；用来打破 `config --list` 与 `config --show` 的平局）。 */
+function actionCount(candidate) {
+  return candidate.requiredFlags.length;
+}
+
+function parseCommandArgs(candidate, tokens, globals, namedActions = []) {
+  const args = {};
+  const positional = [];
+  // 命令名里的旗标（`--delete <ID>` / `--visibility <ID> --show` / `org --tree`）：
+  // 它们的取值由 `consumeCommandPrefix` 连同旗标一起交过来，这里**先**记进 `args`，
+  // 并在主循环里**跳过**这些旗标 —— 一处处理，不留第二次机会去误判。
+  // （以前是"注入一次、主循环再解析一次"，于是取值可能被覆盖成 `true`。）
+  const namedTokens = new Set();
+  for (const flag of namedActions) {
+    if (!candidate.flags.has(flag) || candidate.rejected.has(flag)) continue;
+    namedTokens.add(flag);
+    if (args[flag] === undefined) args[flag] = true;
+  }
+
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (!token.startsWith('-')) {
+      positional.push(token);
+      continue;
+    }
+    const equal = token.startsWith('--') ? token.indexOf('=') : -1;
+    const name = equal > 0 ? token.slice(0, equal) : token;
+    // 命令名里的旗标已经处理过了（见函数开头）。
+    if (namedTokens.has(name)) continue;
+    if (namedTokens.has(name)) continue;
+    if (GLOBAL_FLAGS[name]) {
+      // 全局旗标已经摘过了；走到这里说明它出现在命令名之后，按原样吃掉。
+      // （`--profile` 之类允许写在命令后面：`me --profile staging`。）
+      //
+      // **例外**：它同时是这条命令的取值型业务参数（`--version`）——
+      // 那就得把取值留下，否则请求体里会少一个字段。
+      const commandShape = candidate.flags.get(name);
+      if (commandShape !== undefined && commandShape.takesValue) {
+        let value = equal > 0 ? token.slice(equal + 1) : undefined;
+        if (value === undefined && tokens[index + 1] !== undefined && !tokens[index + 1].startsWith('-')) {
+          value = tokens[index + 1];
+          index += 1;
+        }
+        args[name] = value ?? true;
+        continue;
+      }
+      const spec = GLOBAL_FLAGS[name];
+      if (spec.bool) continue;
+      if (equal > 0) continue;
+      if (tokens[index + 1] !== undefined) index += 1;
+      continue;
+    }
+    const declared = candidate.flags.get(name);
+    // 非全局旗标必须在**这条命令**的声明里：`member --list --reason x` 里的 `--reason`
+    // 是兄弟命令的旗标，Rust 的 clap 会按子命令拒掉它；这里不单独判，
+    // 会和 `rejected` 一起在下面的 "严格参数面" 里统一处理。
+    if (!declared || candidate.rejected.has(name)) {
+      // 提示里给**这条命令**的域名（`config --show` 报错时提示看 `config` 那一组），
+      // 不要拼一个"可能不存在"的命令名出来 —— 现场照抄一条跑不通的命令最伤人。
+      const domain = candidate.name.split(' ').slice(0, 2).join(' ');
+      throw CliError.usage(`${candidate.name} 不认识 ${name}`).withHint(
+        `跑 \`xinhe-oa-cli schema "${domain}"\` 看这一组命令的参数`,
+      );
+    }
+    let value = equal > 0 ? token.slice(equal + 1) : undefined;
+    const shape = valueShapeOf(declared, name);
+    if (value === undefined && shape !== null) {
+      // `--show` 这类"取值可省"的旗标：后面跟着的不是旗标就吃掉它当取值，否则当裸旗标。
+      const mayOmit = shape === 'optional';
+      const next = tokens[index + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        value = next;
+        index += 1;
+      } else if (!mayOmit) {
+        throw CliError.usage(`\`${name}\` 需要一个取值`).withHint(
+          `例：${name} <${declared.placeholder || '值'}>`,
+        );
+      }
+    }
+    if (value === undefined) {
+      // 裸旗标：布尔 true；但可重复的旗标要能给"出现多次"记账。
+      args[name] = declared.variadic && Array.isArray(args[name]) ? args[name] : true;
+      continue;
+    }
+    if (declared.variadic || args[name] !== undefined) {
+      const list = Array.isArray(args[name]) ? args[name] : args[name] === undefined ? [] : [args[name]];
+      list.push(value);
+      args[name] = list;
+      continue;
+    }
+    args[name] = value;
+  }
+
+  // 必填旗标。**同义词在场的算满足**：`member --clear-manager` 就是
+  // `member --set-manager <ID>` 那个动作的另一种写法（Rust 的 `action()` 判"恰好一个"），
+  // 不能因为 `--set-manager` 没出现就报"必须带 --set-manager"。
+  const satisfiedBySynonym = new Set();
+  for (const [flag, value] of Object.entries(args)) {
+    if (value === undefined) continue;
+    const command = candidate.entry.synonym_flags?.includes(flag) ? candidate.name : null;
+    if (command !== null) {
+      for (const token of candidate.tokens) {
+        if (token.startsWith('-')) satisfiedBySynonym.add(token);
+      }
+    }
+  }
+  for (const flag of candidate.requiredFlags) {
+    if (satisfiedBySynonym.has(flag)) continue;
+    if (args[flag] === undefined) {
+      const declared = candidate.flags.get(flag);
+      throw CliError.usage(`${candidate.name} 必须带 ${flag}`).withHint(
+        `例：${flag} <${declared?.placeholder || '值'}>`,
+      );
+    }
+  }
+
+  // **严格参数面**：这条命令声明之外的旗标一律拒。
+  // 少了这道检查，`member --list --reason x` 会被"容下"（`--reason` 是 `MemberArgs`
+  // 的字段），于是多条命令同时命中、解析结果变得看运气 —— 而 Rust 的 clap
+  // 是按子命令校验的，会直接报错。
+  for (const flag of Object.keys(args)) {
+    if (flag in GLOBAL_FLAGS) continue;
+    const inOwnSurface = candidate.flags.has(flag) && !candidate.rejected.has(flag);
+    const inAllowList =
+      candidate.allowedNames === null ||
+      candidate.allowedNames.has(flag) ||
+      candidate.actionFlagNames.has(flag);
+    if (inOwnSurface && inAllowList) continue;
+    const domain = candidate.name.split(' ').slice(0, 2).join(' ');
+    throw CliError.usage(`${candidate.name} 不认识 ${flag}`).withHint(
+      `跑 \`xinhe-oa-cli schema "${domain}"\` 看这一组命令的参数`,
+    );
+  }
+
+  // 动作互斥：同一条命令的多个"动作旗标"（规格里带值的那些，如 `--list` / `--create` /
+  // `--archive`）一次只能给一个 —— 与 Rust 的 clap `ArgGroup(multiple=false)` 同义。
+  const actionFlags = candidate.entry.params
+    .filter((param) => param.flag && !param.optional && param.value === undefined)
+    .map((param) => param.flag);
+  const picked = actionFlags.filter(
+    (flag) => args[flag] === true && !candidate.flags.get(flag)?.takesValue,
+  );
+  if (picked.length > 1) {
+    throw CliError.usage(
+      `\`${candidate.name.split(' ').slice(0, 2).join(' ')}\` 一次只能给一个动作，收到 ${picked.length} 个：${picked.join(' / ')}`,
+    );
+  }
+
+  // **`--yes` 闸门不在这里判**：各域 handler 都调 `runtime.requireYes`，
+  // 而 Rust 的 `what` 文案是**每处调用自己写的**（`file --visibility --set（一次可能
+  // 放开一批人或收掉一批人）`），解析层拼不出逐字一样的 hint。
+  // 在这里抢答会让"缺 --yes"的 error JSON 与 Rust 不一致（退出码 2 与零请求仍然对）。
+  // `schema` 的 `requires_yes` 仍用于文档与校验前的提示（见 `missingActionCount`）。
+
+  return { args, positional, actionFlagNames: new Set(actionFlags) };
+}
+
+/**
+ * 这条命令的**动作旗标**名：命令名里出现的那些（`org --archive` 的 `--archive`）
+ * 加上旗标表里不吃取值的那些（`config --show` 的 `--show`）。
+ */
+function actionFlagNamesOf(candidate) {
+  const names = new Set(candidate.tokens.filter((token) => token.startsWith('-')));
+  for (const [flag, spec] of candidate.flags) {
+    if (!spec.takesValue) names.add(flag);
+  }
+  return [...names];
+}
+
+/** 取旗标值（`--flag <v>`）：没给就是 null；给了但写成裸旗标则给空串。 */
+export function flagValue(args, flag) {
+  const value = args[flag];
+  if (value === undefined || value === true) return value === true ? '' : null;
+  if (Array.isArray(value)) return value[value.length - 1] ?? null;
+  return value;
+}
+
+/** 取可重复旗标（`[--store x]...`）：没给就是空数组。 */
+export function flagList(args, flag) {
+  const value = args[flag];
+  if (value === undefined || value === true) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+/** 布尔旗标是否给了。 */
+export function flagOn(args, flag) {
+  return args[flag] !== undefined;
+}
+
+/**
+ * 取值转整数（供 `--limit` / `--workers` / `--timeout` 这类用）。
+ *
+ * 越界与非法都在**本地**判死（退出码 2、不发请求）—— 这正是 Rust 版的做法：
+ * 服务端 `Query(le=1000)` 的 422 不该原样丢给调用方。
+ */
+export function intFlag(args, flag, { min = null, max = null, fallback = null } = {}) {
+  const raw = flagValue(args, flag);
+  if (raw === null) return fallback;
+  const text = String(raw).trim();
+  if (!/^-?\d+$/.test(text)) {
+    throw CliError.usage(`\`${flag}\` 要一个整数，收到 ${JSON.stringify(raw)}`);
+  }
+  const value = Number.parseInt(text, 10);
+  if (min !== null && value < min) {
+    throw CliError.usage(`\`${flag}\` 不能小于 ${min}（收到 ${value}）`);
+  }
+  if (max !== null && value > max) {
+    throw CliError.usage(`\`${flag}\` 不能大于 ${max}（收到 ${value}）`);
+  }
+  return value;
+}
+
+/** 把 `--type 列=类型` 这类 `K=V` 解析成 `[K, V]`（右侧可以为空）。 */
+export function splitPair(raw, flag) {
+  const index = String(raw).indexOf('=');
+  if (index <= 0) {
+    throw CliError.usage(`\`${flag}\` 要写成 K=V，收到 ${JSON.stringify(raw)}`);
+  }
+  return [String(raw).slice(0, index), String(raw).slice(index + 1)];
+}
+
+/** 规格里所有命令名（`schema` 用）。 */
+export function commandNames() {
+  return commandSurface().commands.map((entry) => entry.name);
+}
+
+export { Kind };