@xinhe-oa/cli 0.0.0-stage → 0.2.0

package/src/commands/skills.js

@@ -0,0 +1,1117 @@
+// 技能：`skills` 域（契约 §2 + docs/34 §5）。
+//
+// 两条腿，刻意分清楚：
+//
+// - **老四条**（`--list` / `--read` / `--install` / `--update --dest`）：
+//   `--list` / `--read` 先看**内嵌**技能（`src/spec/embedded_skills.json`，由
+//   `scripts/gen-embedded-skills.py` 从仓库 `skills/*/SKILL.md` 生成）—— **离线可用**；
+//   `--install` / `--update --dest` 从服务端拉（`GET /skills` + `GET /skills/{name}/bundle`），
+//   **内容寻址 + sha256 校验**：拉下来的每个文件都对着服务端给的 sha256 验一遍，
+//   不一致就一个字节都不落盘。半份技能比没有技能更难查 —— 目录里躺着"一半新一半旧"的
+//   SKILL.md 时，人只会以为技能本身写错了。
+// - **新八条**（`--create` / `--update <SKILL>` / `--delete` / `--mine` / `--share` /
+//   `--unshare` / `--conflicts` / `--publish`）：技能即应用，人人可造 —— 只自己用、
+//   分享给指定的几个人、或企业内共享（**最后一种要企业负责人审批**）。
+//
+// ## 本文件里最要紧的一条纪律
+//
+// **冲突绝不自动选**（docs/34 §3 第二步）。`--conflicts` 扫出冲突、`--publish` 撞上冲突，
+// 都只做一件事：把冲突项的 key / name / 创建人 / 更新时间 / **撞的是 key 还是 name**
+// 一条条摆出来，然后退出码 `5`，并给出两条出路（`--on-conflict rename --new-key <k>` 或
+// `--on-conflict update`）。CLI 不猜、不默认、不"帮你去重"—— 选哪条必须由人来表：
+// 覆盖别人的技能和换个名字重发，后果完全不同，机器替人选的那个一定有一半是错的。
+//
+// 内置名（`xo-core` / `xo-admin`）是**硬错误**（docs/34 §0 第 1 条），退出码 `5`：
+// 静默改名会让"我装的技能到底是谁的"说不清。
+
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+
+import { CliError, Kind, exactlyOne } from '../core/error.js';
+import { flagList, flagOn, flagValue } from '../core/args.js';
+import { createVisibility, onConflictPlan } from '../core/values.js';
+import { dataOf, requestSpec } from '../core/runtime.js';
+import { rustIoErrorText } from '../core/util.js';
+import { warn } from '../core/output.js';
+import embedded from '../spec/embedded_skills.json' with { type: 'json' };
+
+/** 内嵌技能（生成产物）。**离线可读**：这里一个网络请求都不发。 */
+const EMBEDDED = embedded.skills ?? [];
+
+/** 内置技能名（docs/34 §0 第 1 条）。服务端没告诉我们时用它兜底，好让 hint 说得出话。 */
+const KNOWN_BUILTINS = ['xo-core', 'xo-admin'];
+
+/** 两条出路（**必须显式选一条**）。只在错误的 `hint` 里说一遍，不在冲突清单里重复。 */
+const TWO_WAYS_OUT =
+  '两条出路（**必须显式选一条，CLI 绝不替你选**）：' +
+  '① 改名后分享：--on-conflict rename --new-key <新KEY> [--new-name <新名字>]；' +
+  '② 覆盖已有的那个（只有原创建者或企业负责人能选）：--on-conflict update';
+
+/** 合并视图里"有就带上、没有就不编"的字段（docs/34 §4 的 `GET /skills`）。 */
+const MERGED_FIELDS = ['source', 'visibility', 'status', 'owner', 'owner_name', 'kind'];
+
+/**
+ * `skills` 的分发。
+ *
+ * 动作按**旗标**判定，不按 `command.name`：`skills --list` 与 `skills --mine` 在规格里
+ * 是两条命令，但两条的参数面都能容下对方（`--list` / `--mine` 都是"源码里有、schema 没登记"
+ * 的布尔旗标），命令行解析器可能把 `skills --mine` 归到 `skills --list` 名下。
+ * 用旗标判定，两条实现的动作面才是同一份。
+ */
+export async function handleSkills({ args, positional, runtime }) {
+  const action = exactlyOne(
+    [
+      ['--list', flagOn(args, '--list')],
+      ['--read', flagOn(args, '--read')],
+      ['--install', flagOn(args, '--install')],
+      ['--update', flagOn(args, '--update')],
+      ['--create', flagOn(args, '--create')],
+      ['--delete', flagOn(args, '--delete')],
+      ['--mine', flagOn(args, '--mine')],
+      ['--share', flagOn(args, '--share')],
+      ['--unshare', flagOn(args, '--unshare')],
+      ['--conflicts', flagOn(args, '--conflicts')],
+      ['--publish', flagOn(args, '--publish')],
+    ],
+    'skills',
+    '例：xinhe-oa-cli skills --list --json；造一个：skills --create --name 财务月结 --readme ./SKILL.md',
+  );
+  switch (action) {
+    case '--list':
+      return list(runtime);
+    case '--read':
+      return read(runtime, requiredValue(flagValue(args, '--read'), '--read <NAME>'));
+    case '--install':
+      return install(runtime, args, false);
+    case '--update':
+      return updateAction(runtime, args, positional);
+    case '--create':
+      return create(runtime, args);
+    case '--delete':
+      return remove(runtime, args, requiredValue(flagValue(args, '--delete'), '--delete <SKILL>'));
+    case '--mine':
+      return mine(runtime);
+    case '--share':
+      return share(runtime, args, requiredValue(flagValue(args, '--share'), '--share <SKILL>'));
+    case '--unshare':
+      return unshare(runtime, args, requiredValue(flagValue(args, '--unshare'), '--unshare <SKILL>'));
+    case '--conflicts':
+      return conflicts(runtime, args);
+    default:
+      return publish(runtime, args, requiredValue(flagValue(args, '--publish'), '--publish <SKILL>'));
+  }
+}
+
+// ---------------------------------------------------------------------------
+// 老四条：内嵌清单 / 读 / 装 / 更新本地
+// ---------------------------------------------------------------------------
+/** `skills --list`：列**内嵌**技能（纯本地，离线可用）。 */
+function list(runtime) {
+  const items = EMBEDDED.map((entry) => ({
+    name: entry.name,
+    path: entry.path,
+    // 字节数而不是字符数：正文是中文，字符数与字节数能差三倍，"这个技能多大"问的是字节。
+    bytes: Buffer.byteLength(entry.content, 'utf8'),
+    source: 'embedded',
+    when_to_use: firstParagraph(entry.content),
+  }));
+  const count = items.length;
+  // 空清单**必须说清楚**：静默回一个空数组会让人以为"服务端没有技能"，
+  // 而真相反而是"包里没内嵌，服务端那份要用 --install 拉"。
+  const note =
+    count === 0
+      ? '本二进制**未内嵌**任何技能（构建时仓库 skills/ 目录为空或不存在）。' +
+        '技能本身在服务端有发布源，用下面的命令拉：'
+      : '内嵌技能 = 随二进制分发的那一份（离线可读）；服务端还有一份发布源可用 --install 拉取';
+  const nextStep =
+    count === 0
+      ? '拉取技能：xinhe-oa-cli skills --install --dest ./skills'
+      : '读一个：xinhe-oa-cli skills --read <名字>；我造的技能：xinhe-oa-cli skills --mine';
+  runtime.finish({ embedded: items, total: count, note, next_step: nextStep });
+}
+
+/**
+ * `skills --read <NAME>`：**内嵌优先**（离线可用），不是内嵌的才去服务端读。
+ *
+ * 服务端读不到时原样返回 404 —— "看不到的技能，连'存在'都不告诉"（docs/34 §0 第 3 条）。
+ */
+async function read(runtime, name) {
+  const found = EMBEDDED.find((entry) => entry.name === name || entry.path.includes(name));
+  if (found) {
+    runtime.finish({
+      name: found.name,
+      path: found.path,
+      source: 'embedded',
+      content: found.content,
+    });
+    return;
+  }
+  const target = `/skills/${name}`;
+  const spec = requestSpec();
+  if (runtime.dryRun) {
+    runtime.dryRunReport('GET', target, spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('GET', target, spec);
+  const data = dataOf(response);
+  if (isPlainObject(data)) {
+    data.source = 'platform';
+    data.next_step = '改正文：xinhe-oa-cli skills --update <SKILL> --readme ./SKILL.md --json';
+  }
+  runtime.finishFrom(response, data);
+}
+
+/** `--update` 的两种读法：给了 `<SKILL>` 改服务端技能；只给 `--dest` 更新本地已装技能。 */
+async function updateAction(runtime, args, positional) {
+  let skill = nonEmpty(flagValue(args, '--update')) ?? '';
+  if (skill.length === 0 && !flagOn(args, '--dest')) {
+    // 命令行层的已知缺陷（core/args.js，本文件不便改）：`consumeCommandPrefix()` 中途
+    // `break` 时只回 `{consumed, actions}`，把已经记下的取值丢了，于是
+    // `--update <SKILL>` 的 SKILL 到了这里变成 `true`（技能名整条消失）。
+    // 命令层拿不到原始 argv，只能从 `process.argv` 把紧跟 `--update` 的那个值捡回来。
+    // **这条兜底会自己失效**：core 一旦把取值传下来（`args['--update']` 是字符串），
+    // 整个分支就不会被走到，可以删掉。
+    skill = updateTargetFromArgv() ?? '';
+  }
+  const dest = nonEmpty(flagValue(args, '--dest'));
+  if (skill.length === 0) {
+    if (dest === null) {
+      throw CliError.usage(
+        '`skills --update` 要么给 <SKILL>（改服务端技能），要么给 --dest <目录>（更新已装技能）',
+      ).withHint(
+        '改正文：xinhe-oa-cli skills --update 财务月结 --readme ./SKILL.md --json；' +
+          '更新本地：xinhe-oa-cli skills --update --dest ./skills',
+      );
+    }
+    if (nonEmpty(flagValue(args, '--readme')) !== null || nonEmpty(flagValue(args, '--description')) !== null) {
+      throw CliError.usage(
+        '`--update --dest <目录>` 是从服务端重新拉取，不接受 --readme / --description',
+      ).withHint('改服务端技能的正文用：skills --update <SKILL> --readme ./SKILL.md');
+    }
+    return install(runtime, args, true);
+  }
+  if (dest !== null) {
+    throw CliError.usage(
+      '`skills --update <SKILL>`（改服务端技能）与 `--dest`（更新本地已装技能）不能同时给',
+    ).withHint(
+      '改服务端技能：xinhe-oa-cli skills --update 财务月结 --readme ./SKILL.md；' +
+        '更新本地：xinhe-oa-cli skills --update --dest ./skills',
+    );
+  }
+  if (nonEmpty(flagValue(args, '--readme')) === null && nonEmpty(flagValue(args, '--description')) === null) {
+    throw CliError.usage(
+      '`skills --update <SKILL>` 至少要给 --readme <文件> 或 --description <一句话>',
+    ).withHint('例：xinhe-oa-cli skills --update 财务月结 --description "月度结账"');
+  }
+  return updateRemote(runtime, args, skill, positional);
+}
+
+/**
+ * `skills --install` / `--update --dest`：从服务端拉技能落盘。
+ *
+ * `update=true` 时多一步"已经是最新就跳过"（读目录里的 `.xinhe-content-hash` 戳）。
+ */
+async function install(runtime, args, update) {
+  const dest = nonEmpty(flagValue(args, '--dest'));
+  if (dest === null) {
+    throw CliError.usage('`skills --install` 需要 --dest <目录>').withHint(
+      '例：xinhe-oa-cli skills --install --dest ./skills',
+    );
+  }
+  const destPath = path.resolve(dest);
+  const names = flagList(args, '--name')
+    .map((name) => String(name).trim())
+    .filter((name) => name.length > 0);
+
+  // ① 清单（服务端按令牌给**合并视图**：内置 + 我可得的用户技能，docs/34 §4）
+  const index = dataOf(await runtime.sendAuthed('GET', '/skills', requestSpec()));
+  const skills = Array.isArray(index?.skills) ? index.skills : [];
+  if (skills.length === 0) warn('服务端没有发布任何 skill');
+  const registryVersion =
+    typeof index?.version === 'string' ? index.version : 'unknown';
+
+  const wanted = skills.filter((item) => {
+    if (names.length === 0) return true;
+    return names.includes(item?.name);
+  });
+  if (wanted.length === 0 && names.length > 0) {
+    throw CliError.usage('--name 点的技能服务端一个都没有')
+      .withDetails({ requested: names })
+      .withHint('先看：xinhe-oa-cli skills --install --dest <目录>（不带 --name 装全部）');
+  }
+
+  if (runtime.dryRun) {
+    const plan = wanted.map((item) => {
+      const name = typeof item?.name === 'string' ? item.name : '?';
+      return {
+        name,
+        content_hash: item?.content_hash ?? null,
+        dest: rustJoin(dest, name),
+        ...mergedFields(item),
+      };
+    });
+    runtime.finish({
+      dry_run: true,
+      registry_version: registryVersion,
+      would_install: plan,
+      note: '每个 skill 走 GET /skills/{name}/bundle?format=json，逐文件校验 sha256 后再落盘',
+    });
+    return;
+  }
+
+  mkdirp(destPath, '建不了目录');
+
+  const installed = [];
+  const skipped = [];
+  const failed = [];
+  for (const item of wanted) {
+    const name = typeof item?.name === 'string' ? item.name : '';
+    const remoteHash = typeof item?.content_hash === 'string' ? item.content_hash : '';
+    const skillDir = path.join(destPath, name);
+    let bundle;
+    try {
+      bundle = await fetchBundle(runtime, name);
+    } catch (err) {
+      failed.push({
+        name,
+        error: { code: err.code ?? 'cli.error', message: err.message, details: err.details ?? {} },
+      });
+      continue;
+    }
+
+    const files = isPlainObject(bundle?.files) ? bundle.files : {};
+    // ② 先把全部文件在内存里算完哈希（顺带挡下 `..` / 绝对路径），全对才落盘。
+    const verified = [];
+    for (const relative of Object.keys(files).sort()) {
+      const bytes = Buffer.from(
+        files[relative] === undefined || files[relative] === null ? '' : String(files[relative]),
+        'utf8',
+      );
+      verified.push({ target: safeJoin(skillDir, relative), bytes, hash: sha256Hex(bytes) });
+    }
+
+    // ③ 与服务端 `GET /skills/{name}` 的逐文件 sha256 对一遍（有就去对）。
+    //    详情取不到不算失败：校验是"能对就一定要对"，不是"对不上就装不了"。
+    const mismatches = [];
+    let detail = null;
+    try {
+      detail = await fetchDetail(runtime, name);
+    } catch {
+      detail = null;
+    }
+    if (Array.isArray(detail?.files)) {
+      for (const row of detail.files) {
+        const relative = typeof row?.path === 'string' ? row.path : '';
+        const expected = typeof row?.sha256 === 'string' ? row.sha256 : '';
+        const hit = verified.find((entry) => pathEndsWith(entry.target, relative));
+        if (hit && expected.length > 0 && expected !== hit.hash) {
+          mismatches.push({ path: relative, expected, actual: hit.hash });
+        }
+      }
+    }
+    if (mismatches.length > 0) {
+      failed.push({
+        name,
+        error: 'sha256 校验失败：一个字节都没落盘',
+        mismatches,
+      });
+      continue;
+    }
+
+    if (update) {
+      // 已经是最新（目录里有 .xinhe-content-hash 且相同）→ 跳过。
+      const stamp = path.join(skillDir, '.xinhe-content-hash');
+      const existing = readTextIfExists(stamp);
+      if (existing !== null && existing.trim() === remoteHash && remoteHash.length > 0) {
+        skipped.push({
+          name,
+          reason: '已经是最新',
+          content_hash: remoteHash,
+          ...mergedFields(item),
+        });
+        continue;
+      }
+    }
+
+    let written = 0;
+    for (const entry of verified) {
+      mkdirp(path.dirname(entry.target), '建不了目录');
+      try {
+        fs.writeFileSync(entry.target, entry.bytes);
+      } catch (err) {
+        throw CliError.usage(`写不了 ${entry.target}：${err.message}`);
+      }
+      written += 1;
+    }
+    if (remoteHash.length > 0) {
+      try {
+        fs.writeFileSync(path.join(skillDir, '.xinhe-content-hash'), remoteHash);
+      } catch {
+        /* 戳写不上不影响技能本体，下次 --update 会当作没装过 */
+      }
+    }
+    installed.push({
+      name,
+      files: written,
+      content_hash: remoteHash,
+      dir: rustJoin(dest, name),
+      verified: true,
+      ...mergedFields(item),
+    });
+  }
+
+  runtime.finish({
+    dest,
+    registry_version: registryVersion,
+    installed,
+    skipped,
+    failed,
+    mode: update ? 'update' : 'install',
+    note: '内容寻址 + sha256 校验：校验不过就一个字节都不落盘',
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 造与改（docs/34 §5）
+// ---------------------------------------------------------------------------
+/** `skills --create`：`POST /skills`。**默认 private**（fail-closed，docs/34 §0 第 2 条）。 */
+async function create(runtime, args) {
+  const name = singleName(args, 'skills --create');
+  const readmePath = nonEmpty(flagValue(args, '--readme'));
+  if (readmePath === null) {
+    throw CliError.usage(
+      '`skills --create` 需要 --readme <文件>（SKILL.md 正文，给 LLM 读的提示词资产）',
+    ).withHint('例：xinhe-oa-cli skills --create --name 财务月结 --readme ./SKILL.md --json');
+  }
+  const readme = readText(readmePath);
+  // 不传 --visibility 就是 private：默认值必须是**最窄**的那一档，
+  // 否则"我随手建了个技能"会变成"全企业都看得见"。
+  const visibility = createVisibility(flagValue(args, '--visibility'));
+
+  const body = { name, readme, visibility };
+  const key = nonEmpty(flagValue(args, '--key'));
+  if (key !== null) body.key = key;
+  const description = nonEmpty(flagValue(args, '--description'));
+  if (description !== null) body.description = description;
+  const appId = nonEmpty(flagValue(args, '--from-application'));
+  // docs/34 §1.1：`--from-application` 写进 `app_id`（技能与它引用的应用要一起提交）。
+  if (appId !== null) body.app_id = appId;
+
+  const spec = requestSpec({ body: sortKeys(body) });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', '/skills', spec);
+    return;
+  }
+  const response = await runtime
+    .sendAuthed('POST', '/skills', spec)
+    .catch((err) => {
+      throw enrichSkillError(err);
+    });
+  const out = unwrapSkill(dataOf(response));
+  if (isPlainObject(out)) {
+    out.reserved = false;
+    out.next_step =
+      '分享给同事：xinhe-oa-cli skills --share <SKILL> --to-user <USER_ID>；' +
+      '分享到企业前先扫冲突：xinhe-oa-cli skills --conflicts --name <名字>';
+    out.note = '默认 private（fail-closed）：除你之外谁都看不到，连「存在」都不告诉';
+  }
+  runtime.finishFrom(response, out);
+}
+
+/** `skills --update <SKILL>`：`PATCH /skills/{id}`（乐观锁 `version`）。 */
+async function updateRemote(runtime, args, skill, positional = []) {
+  const body = {};
+  const readmePath = nonEmpty(flagValue(args, '--readme'));
+  if (readmePath !== null) body.readme = readText(readmePath);
+  const description = nonEmpty(flagValue(args, '--description'));
+  if (description !== null) body.description = description;
+  const version = versionOf(args, positional);
+  // docs/34 §1.1 的乐观锁：带上它，别人那一版就不会被自己这一版悄悄覆盖掉。
+  if (version !== null) body.version = version;
+
+  const spec = requestSpec({ body: sortKeys(body) });
+  const target = `/skills/${skill}`;
+  if (runtime.dryRun) {
+    runtime.dryRunReport('PATCH', target, spec);
+    return;
+  }
+  const response = await runtime
+    .sendAuthed('PATCH', target, spec)
+    .catch((err) => {
+      throw enrichSkillError(err);
+    });
+  const out = unwrapSkill(dataOf(response));
+  if (isPlainObject(out)) {
+    out.next_step = '看这一份：xinhe-oa-cli skills --read <SKILL> --json';
+    if (version === null) {
+      out.note =
+        '这次没带 --version（不做乐观锁校验）；并发改同一份时服务端可能报 write.version_conflict';
+    }
+  }
+  runtime.finishFrom(response, out);
+}
+
+/**
+ * `skills --delete <SKILL>`：`DELETE /skills/{id}`（软删）。
+ *
+ * **高风险写操作**：docs/34 §5 没写它的风险级别，但 CLI 里 `record --delete` /
+ * `attachment --delete` 一律是 `high-risk-write`，删除技能与之同级，所以同样要 `--yes`。
+ */
+async function remove(runtime, args, skill) {
+  runtime.requireYes(
+    'skills --delete（技能会被软删，别人再也读不到）',
+    `xinhe-oa-cli skills --delete ${skill}`,
+  );
+  const target = `/skills/${skill}`;
+  const spec = requestSpec();
+  if (runtime.dryRun) {
+    runtime.dryRunReport('DELETE', target, spec);
+    return;
+  }
+  const response = await runtime
+    .sendAuthed('DELETE', target, spec)
+    .catch((err) => {
+      throw enrichSkillError(err);
+    });
+  const out = dataOf(response);
+  if (isPlainObject(out)) {
+    out.skill = skill;
+    out.deleted = true;
+    out.note = '软删：服务端先断开所有点对点分享；待审的审批也随之失效';
+  }
+  runtime.finishFrom(response, out);
+}
+
+/** `skills --mine`：我造的（含 draft / pending / rejected）。 */
+async function mine(runtime) {
+  const spec = requestSpec();
+  if (runtime.dryRun) {
+    runtime.dryRunReport('GET', '/skills/mine', spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('GET', '/skills/mine', spec);
+  const data = dataOf(response);
+  const skills = Array.isArray(data?.skills) ? data.skills : Array.isArray(data?.items) ? data.items : [];
+  const total = data?.total ?? skills.length;
+  runtime.finishFrom(response, {
+    skills,
+    total,
+    next_step:
+      '改正文：xinhe-oa-cli skills --update <SKILL> --readme ./SKILL.md；' +
+      '申请企业共享：xinhe-oa-cli skills --publish <SKILL> --visibility tenant',
+    note: '这里连草稿 / 待审 / 被拒的都在（别人看不到未发布的技能）',
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 分享（点对点 / 企业）
+// ---------------------------------------------------------------------------
+/** `skills --share <SKILL> --to-user A [--to-user B]`：点对点，**直接生效、不需要审批**。 */
+async function share(runtime, args, skill) {
+  const users = flagList(args, '--to-user')
+    .map((user) => String(user).trim())
+    .filter((user) => user.length > 0);
+  if (users.length === 0) {
+    throw CliError.usage('`skills --share` 需要至少一个 --to-user <USER_ID>').withHint(
+      '看企业里有哪些人：xinhe-oa-cli member --list --json',
+    );
+  }
+  const target = `/skills/${skill}/share`;
+
+  if (runtime.dryRun) {
+    const requests = users.map((user) =>
+      runtime.dryRunRequest('POST', target, requestSpec({ body: { user_id: user } })),
+    );
+    runtime.finish({
+      dry_run: true,
+      skill,
+      requests,
+      note: `--dry-run：没有发出任何请求。真跑会按 --to-user 逐个发 ${users.length} 次 POST ${target}`,
+    });
+    return;
+  }
+
+  const results = [];
+  let firstError = null;
+  for (const user of users) {
+    try {
+      const response = await runtime.sendAuthed(
+        'POST',
+        target,
+        requestSpec({ body: { user_id: user } }),
+      );
+      results.push({ user_id: user, granted: true, data: dataOf(response) });
+    } catch (err) {
+      results.push({
+        user_id: user,
+        granted: false,
+        error: { code: err.code ?? 'cli.error', message: err.message },
+      });
+      if (firstError === null) firstError = err;
+    }
+  }
+
+  if (firstError !== null) {
+    // 部分成功也要如实说：谁成了、谁没成，一个都不许糊过去 ——
+    // "分享给了 5 个人"里有 2 个没成，不说清楚就会变成"他明明说分享过了"。
+    const granted = results.filter((row) => row.granted === true).length;
+    const hint = `共 ${results.length} 人：成功 ${granted}，失败 ${results.length - granted}；先把失败的那几个人解决掉（--to-user 可以逐个重试）`;
+    const details = isPlainObject(firstError.details) ? { ...firstError.details } : {};
+    details.results = results;
+    details.skill = skill;
+    throw firstError.withDetails(details).withHint(hint);
+  }
+
+  runtime.finish({
+    skill,
+    results,
+    shared_count: users.length,
+    next_step: '对方现在就能读到：xinhe-oa-cli skills --read <SKILL> --json（在他自己的机器上）',
+    note: '点对点分享直接生效，不需要审批；要收回用 skills --unshare <SKILL> --from-user <USER_ID>',
+  });
+}
+
+/** `skills --unshare <SKILL> --from-user <USER_ID>`：收回点对点分享。 */
+async function unshare(runtime, args, skill) {
+  const user = nonEmpty(flagValue(args, '--from-user'));
+  if (user === null) {
+    throw CliError.usage('`skills --unshare` 需要 --from-user <USER_ID>').withHint(
+      '看分享给了谁：xinhe-oa-cli skills --read <SKILL> --json',
+    );
+  }
+  const target = `/skills/${skill}/unshare`;
+  const spec = requestSpec({ body: { user_id: user } });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', target, spec);
+    return;
+  }
+  const response = await runtime
+    .sendAuthed('POST', target, spec)
+    .catch((err) => {
+      throw enrichSkillError(err);
+    });
+  const out = dataOf(response);
+  if (isPlainObject(out)) {
+    out.skill = skill;
+    out.user_id = user;
+    out.revoked = true;
+  }
+  runtime.finishFrom(response, out);
+}
+
+/**
+ * `skills --conflicts --name <n> [--key <k>]`：分享前的冲突扫描（docs/34 §3 第一步）。
+ *
+ * **发现冲突就是退出码 5**：扫描命令的结论是"你得先做个决定"，脚本据此分支；
+ * 调用方要的细节（key/name/创建人/时间/撞的是哪个）全在 `error.details.conflicts` 里。
+ * 扫描本身是只读的，但"扫出冲突"不是成功 —— 成功意味着"可以往下走"。
+ */
+async function conflicts(runtime, args) {
+  const nameList = flagList(args, '--name');
+  const name = nameList.length === 0 ? null : singleName(args, 'skills --conflicts');
+  const key = nonEmpty(flagValue(args, '--key'));
+  if (name === null && key === null) {
+    throw CliError.usage('`skills --conflicts` 至少要给 --name <名字> 或 --key <机器名>').withHint(
+      '例：xinhe-oa-cli skills --conflicts --name 财务月结 --key finance_monthly --json',
+    );
+  }
+  const query = [];
+  if (name !== null) query.push(['name', name]);
+  if (key !== null) query.push(['key', key]);
+  const spec = requestSpec({ query });
+  if (runtime.dryRun) {
+    runtime.dryRunReport('GET', '/skills/conflicts', spec);
+    return;
+  }
+  const response = await runtime.sendAuthed('GET', '/skills/conflicts', spec);
+  const scan = dataOf(response);
+
+  // 撞内置名 = 硬错误（docs/34 §0 第 1 条）：连"改名后重来"都得人先看见。
+  if (isReserved(scan)) {
+    throw reservedError(scan, name, key).withHumanDetails(describeConflicts(scan));
+  }
+  const found = conflictRows(scan);
+  if (found.length > 0) {
+    throw conflictError(scan, '<SKILL>').withHumanDetails(describeConflicts(scan));
+  }
+
+  runtime.finishFrom(response, {
+    reserved: false,
+    conflicts: found,
+    builtins: Array.isArray(scan?.builtins) ? scan.builtins : KNOWN_BUILTINS,
+    scanned: { name, key },
+    next_step: '没有冲突，可以直接提交：xinhe-oa-cli skills --publish <SKILL> --visibility tenant --json',
+  });
+}
+
+/**
+ * `skills --publish <SKILL> --visibility tenant|private [--on-conflict ...]`。
+ *
+ * 冲突时不自动选：服务端把冲突清单还回来，CLI 把它摆成人能读的样子，退出码 `5`。
+ */
+async function publish(runtime, args, skill) {
+  // `--publish` 的可见性是**必填**：分享到哪里必须显式表态（与 `--create` 的 fail-closed 不同 ——
+  // 那条是"不表态就最窄"，这条是"不表态就没法执行"）。
+  const raw = nonEmpty(flagValue(args, '--visibility'));
+  if (raw === null) {
+    throw CliError.usage('`skills --publish` 需要 --visibility tenant|private').withHint(
+      '分享给全企业：--visibility tenant；撤回成只有自己：--visibility private',
+    );
+  }
+  const visibility = createVisibility(raw);
+  const plan = onConflictPlan(
+    flagValue(args, '--on-conflict'),
+    flagValue(args, '--new-key'),
+    flagValue(args, '--new-name'),
+  );
+  const body = { visibility };
+  if (plan !== null && plan.kind === 'rename') {
+    body.on_conflict = 'rename';
+    body.new_key = plan.newKey;
+    if (plan.newName !== null && plan.newName !== undefined) body.new_name = plan.newName;
+  } else if (plan !== null) {
+    body.on_conflict = 'update';
+  }
+  // 不表态：把请求原样发出去，让服务端回"有冲突"（CLI 不替服务端猜有没有冲突）。
+  const spec = requestSpec({ body: sortKeys(body) });
+  const target = `/skills/${skill}/publish`;
+  if (runtime.dryRun) {
+    runtime.dryRunReport('POST', target, spec);
+    return;
+  }
+  let response;
+  try {
+    response = await runtime.sendAuthed('POST', target, spec);
+  } catch (rawError) {
+    const err = enrichSkillError(rawError);
+    if (isConflictPayload(err.details)) {
+      // 冲突清单要给人看：摆出来，再以 5 退出。
+      const hint = err.hint ? `${err.hint}；${TWO_WAYS_OUT}` : TWO_WAYS_OUT;
+      throw err.withHint(hint).withHumanDetails(describeConflicts(err.details));
+    }
+    throw err;
+  }
+  const data = dataOf(response);
+  runtime.finishFrom(response, publishOutcome(data, skill, visibility, plan));
+}
+
+/**
+ * `--publish` 成功后的输出：**提交人要看到下一步**（docs/34 §5 / §3 第三步）。
+ *
+ * 带了审批 id 时 `next_step` 写死 `xinhe-oa-cli approval --list --to-review` —— 那是
+ * **企业负责人**要看的清单；提交人自己看 `approval --mine`。
+ */
+function publishOutcome(data, skill, visibility, plan) {
+  const approvalId = approvalIdOf(data);
+  const onConflict =
+    plan === null
+      ? null
+      : plan.kind === 'rename'
+        ? { strategy: 'rename', new_key: plan.newKey }
+        : { strategy: 'update' };
+  const out = {
+    skill,
+    visibility,
+    on_conflict: onConflict,
+    approval_id: approvalId,
+    data,
+  };
+  if (approvalId !== null) {
+    out.next_step = 'xinhe-oa-cli approval --list --to-review';
+    out.note =
+      '已提交企业负责人审批：通过之前技能对企业其他人**不可见**（status=pending）；' +
+      '看进度：xinhe-oa-cli approval --show <APPROVAL_ID>；撤回：xinhe-oa-cli approval --cancel <APPROVAL_ID>';
+  } else {
+    out.next_step = 'xinhe-oa-cli skills --mine';
+    out.note = '这次没有产生审批（visibility=private 时是直接生效/撤回）';
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// 冲突的呈现与判定（纯函数，便于单测）
+// ---------------------------------------------------------------------------
+/** 冲突项清单（`conflicts` 数组）。 */
+export function conflictRows(scan) {
+  return Array.isArray(scan?.conflicts) ? scan.conflicts : [];
+}
+
+/** 是否撞了内置名（`reserved: true`）。 */
+export function isReserved(scan) {
+  return scan?.reserved === true;
+}
+
+/** 错误详情里是否带着一份冲突清单（服务端在 `--publish` 上的拒绝形状）。 */
+export function isConflictPayload(details) {
+  return conflictRows(details).length > 0 || isReserved(details);
+}
+
+/**
+ * 把冲突扫描结果渲染成人能读的一段话（key / name / 创建人 / 更新时间 / **撞的是哪个**）。
+ *
+ * 只负责"有哪些冲突"；两条出路在错误的 `hint` 里（`TWO_WAYS_OUT`）——
+ * 两边都印一遍只会让最要紧的那句话被淹掉。
+ */
+export function describeConflicts(scan) {
+  let out = '';
+  if (isReserved(scan)) {
+    out += `✗ 撞了内置技能名：内置技能优先级最高、不可覆盖，请换一个名字（内置：${builtinNames(scan).join(' / ')}）\n`;
+  }
+  const rows = conflictRows(scan);
+  if (rows.length > 0) {
+    out += `✗ 企业内已有 ${rows.length} 项同名/同 key 的已发布技能：\n`;
+    rows.forEach((row, index) => {
+      const key = textOf(row, 'key');
+      const name = textOf(row, 'name');
+      const same =
+        (Array.isArray(row?.same) ? row.same.filter((item) => typeof item === 'string') : []).join(',') ||
+        '?';
+      const ownerName = textOf(row, 'owner_name');
+      const ownerId = textOf(row, 'owner_user_id');
+      const owner =
+        ownerName.length > 0 && ownerId.length > 0
+          ? `${ownerName}（${ownerId}）`
+          : ownerName.length > 0
+            ? ownerName
+            : ownerId.length > 0
+              ? ownerId
+              : '?';
+      const updated = textOf(row, 'updated_at') || '?';
+      const hash = textOf(row, 'content_hash');
+      out +=
+        `  ${index + 1}. key=${key.length > 0 ? key : '?'}  name=${name.length > 0 ? name : '?'}` +
+        `  撞的是: ${same}  创建人: ${owner}  更新时间: ${updated}` +
+        `${hash.length > 0 ? `  content_hash=${shortHash(hash)}` : ''}\n`;
+    });
+    out += '（撞了就该有人做个决定：改名 rename 还是覆盖 update —— 见下方「下一步」）\n';
+  }
+  return out;
+}
+
+/** 冲突 → 退出码 5 的错误（**不新造服务端码**：这是 CLI 自己的判定，用 `cli.*`）。 */
+export function conflictError(scan, skill) {
+  const rows = conflictRows(scan);
+  const count = rows.length;
+  const options = [
+    {
+      on_conflict: 'rename',
+      args: ['--on-conflict', 'rename', '--new-key', '<新KEY>'],
+      说明: '换一个机器名（可再给 --new-name 换显示名）后重新提交',
+      example: `xinhe-oa-cli skills --publish ${skill} --visibility tenant --on-conflict rename --new-key <新KEY> --json`,
+    },
+    {
+      on_conflict: 'update',
+      args: ['--on-conflict', 'update'],
+      说明: '覆盖已有的那个企业级技能（发布新版本，version 递增）；只有原创建者或企业负责人能选',
+      example: `xinhe-oa-cli skills --publish ${skill} --visibility tenant --on-conflict update --json`,
+    },
+  ];
+  return new CliError(
+    Kind.Conflict,
+    'cli.skill_conflict',
+    `企业内已有 ${count} 项同名/同 key 的技能，你没有表态怎么处理`,
+  )
+    .withDetails({
+      reserved: isReserved(scan),
+      conflict_count: count,
+      conflicts: rows,
+      builtins: Array.isArray(scan?.builtins) ? scan.builtins : KNOWN_BUILTINS,
+      options,
+      next_step: `xinhe-oa-cli skills --publish ${skill} --visibility tenant --on-conflict rename --new-key <新KEY>`,
+    })
+    .withHint(TWO_WAYS_OUT);
+}
+
+/**
+ * 撞内置名 → 硬错误。退出码 **5**（理由见 `core/error.js` 的 `classify`：这个码只可能从服务端
+ * 回来，退出码 2 的判据写死了"本地判定、不发请求"；而出路与 `--on-conflict rename` 同类）。
+ */
+export function reservedError(scan, name, key) {
+  const builtins = builtinNames(scan);
+  const target = name ?? key ?? '<这个名字>';
+  return new CliError(
+    Kind.Conflict,
+    'skill.name_reserved',
+    `${target} 是内置技能名，不可覆盖`,
+  )
+    .withDetails({
+      reserved: true,
+      builtins,
+      name: name ?? null,
+      key: key ?? null,
+      conflicts: conflictRows(scan),
+    })
+    .withHint(
+      `内置技能优先级最高、不可被覆盖，请换个名字（内置：${builtins.join(' / ')}）：` +
+        '还没建就在 `skills --create --name <别的名字>` 换掉；' +
+        '已经建好要分享到企业就在 `skills --publish ... --on-conflict rename --new-key <新KEY>` 换掉',
+    );
+}
+
+/** 服务端返回的技能专属错误 → 把 hint 补成人能照做的下一步。 */
+export function enrichSkillError(err) {
+  if (err.code === 'skill.name_reserved') {
+    const details = isPlainObject(err.details) ? err.details : {};
+    const list = Array.isArray(details.builtins)
+      ? details.builtins.filter((name) => typeof name === 'string')
+      : [];
+    const builtins = list.length > 0 ? list.join(' / ') : KNOWN_BUILTINS.join(' / ');
+    const ours =
+      `内置技能不可覆盖，请换个名字（内置：${builtins}）；换个名字重来：` +
+      '`skills --create --name <别的名字>`，或分享时 `--publish ... --on-conflict rename --new-key <新KEY>`' +
+      '（内置技能本身没有任何改动）';
+    return err.withHint(err.hint ? `${ours}；服务端说法：${err.hint}` : ours);
+  }
+  if (err.code === 'skill.not_owner') {
+    // `--on-conflict update` 是覆盖别人的东西：能做的只有原创建者或企业负责人。
+    return err.withHint(
+      '`--on-conflict update` 是**覆盖已有的那个技能**，只有它的原创建者或该企业负责人能选；' +
+        '你没有这个权力 —— 要么找原创建者/企业负责人来做，要么改用 ' +
+        '`--on-conflict rename --new-key <新KEY>`',
+    );
+  }
+  return err;
+}
+
+// ---------------------------------------------------------------------------
+// 工具（都对照 Rust 的同名函数逐条对齐）
+// ---------------------------------------------------------------------------
+function builtinNames(scan) {
+  const list = Array.isArray(scan?.builtins)
+    ? scan.builtins.filter((name) => typeof name === 'string')
+    : [];
+  return list.length > 0 ? list : [...KNOWN_BUILTINS];
+}
+
+function textOf(row, key) {
+  return typeof row?.[key] === 'string' ? row[key] : '';
+}
+
+function shortHash(hash) {
+  return Array.from(hash).slice(0, 12).join('');
+}
+
+/** 服务端的技能对象可能在 `skill` 里，也可能就是 `data` 本身。 */
+function unwrapSkill(data) {
+  if (isPlainObject(data) && isPlainObject(data.skill)) return data.skill;
+  return data;
+}
+
+/** 审批 id 可能在四处（服务端两种信封 × 有没有 `skill`）。 */
+function approvalIdOf(data) {
+  for (const pointer of ['/approval_id', '/approval/id', '/data/approval_id', '/data/approval/id']) {
+    const value = pointerOf(data, pointer);
+    if (typeof value === 'string' && value.trim().length > 0) return value;
+  }
+  return null;
+}
+
+function pointerOf(value, pointer) {
+  let current = value;
+  for (const piece of pointer.split('/').slice(1)) {
+    if (!isPlainObject(current) && !Array.isArray(current)) return undefined;
+    current = current[piece];
+  }
+  return current;
+}
+
+/** 服务端合并视图的新字段：**有就带上，没有就不编**（老服务端照样能跑）。 */
+function mergedFields(item) {
+  const out = {};
+  for (const key of MERGED_FIELDS) {
+    if (isPlainObject(item) && item[key] !== undefined && item[key] !== null) out[key] = item[key];
+  }
+  return out;
+}
+
+function singleName(args, what) {
+  const names = flagList(args, '--name')
+    .map((name) => String(name).trim())
+    .filter((name) => name.length > 0);
+  if (names.length === 1) return names[0];
+  if (names.length === 0) {
+    throw CliError.usage(`\`${what}\` 需要 --name <名字>`).withHint(
+      '例：xinhe-oa-cli skills --create --name 财务月结 --readme ./SKILL.md',
+    );
+  }
+  throw CliError.usage(
+    `\`${what}\` 一次只能给一个 --name，收到 ${names.length} 个：${names.join(' / ')}`,
+  ).withHint('要一次装多个内置技能用：skills --install --dest <目录> --name A --name B');
+}
+
+function requiredValue(value, what) {
+  const text = nonEmpty(value);
+  // 与 Rust `required_value` 同一句话：`--read` 写成裸旗标时走的就是这里。
+  if (text === null) throw CliError.usage(`${what} 的值不能为空`);
+  return text;
+}
+
+/**
+ * `skills --update <SKILL> --version <N>` 的版本号。
+ *
+ * 为什么要看 `positional`：`--version` 同时是**全局旗标**（`-V/--version` 打印版本号），
+ * 命令行层会把它整个摘走，`4` 于是落进位置参数里（`args['--version']` 永远是 undefined）。
+ * Rust 侧两者不冲突（顶层 `--version` 与 `SkillsArgs::version` 是两个作用域），
+ * 所以这里按 Rust 的口径把那个整数捡回来；命令行层修好后 `args['--version']` 会先生效，这段可以删。
+ */
+function versionOf(args, positional) {
+  const direct = flagValue(args, '--version');
+  if (direct !== null && direct !== undefined && String(direct).trim().length > 0) {
+    const text = String(direct).trim();
+    if (!/^-?\d+$/.test(text)) {
+      throw CliError.usage(`\`--version\` 要一个整数，收到 ${JSON.stringify(direct)}`);
+    }
+    return Number.parseInt(text, 10);
+  }
+  const strays = positional.filter((token) => /^-?\d+$/.test(String(token).trim()));
+  if (strays.length === 1) return Number.parseInt(String(strays[0]).trim(), 10);
+  return null;
+}
+
+function updateTargetFromArgv() {
+  const argv = process.argv.slice(2);
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (token.startsWith('--update=')) return nonEmpty(token.slice('--update='.length));
+    if (token !== '--update') continue;
+    const next = argv[index + 1];
+    return next !== undefined && !next.startsWith('-') ? next : null;
+  }
+  return null;
+}
+
+function nonEmpty(raw) {
+  if (raw === null || raw === undefined) return null;
+  const text = String(raw).trim();
+  return text.length > 0 ? text : null;
+}
+
+function readText(file) {
+  let bytes;
+  try {
+    bytes = fs.readFileSync(file);
+  } catch (err) {
+    throw CliError.usage(`读不了文件 ${file}：${rustIoErrorText(err)}`);
+  }
+  try {
+    // 先解一遍再当字符串用：SKILL.md 必须是文本，二进制混进来要在这里就说清楚。
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch (err) {
+    throw CliError.usage(`${file} 不是 UTF-8 文本（SKILL.md 必须是文本）：${err.message}`);
+  }
+}
+
+function readTextIfExists(file) {
+  try {
+    return fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function mkdirp(directory, what) {
+  try {
+    fs.mkdirSync(directory, { recursive: true });
+  } catch (err) {
+    throw CliError.usage(`${what} ${directory}：${err.message}`);
+  }
+}
+
+async function fetchBundle(runtime, name) {
+  // `format=json`：不引入 tar/gzip 依赖也能逐文件校验（客户端只用标准库）。
+  const spec = requestSpec({ query: [['format', 'json']] });
+  const response = await runtime.sendAuthed('GET', `/skills/${name}/bundle`, spec);
+  return dataOf(response);
+}
+
+async function fetchDetail(runtime, name) {
+  const response = await runtime.sendAuthed('GET', `/skills/${name}`, requestSpec());
+  return dataOf(response);
+}
+
+/**
+ * 防目录穿越：bundle 里的相对路径不许 `..` 或绝对路径。
+ *
+ * 服务端发布源是**半可信**的输入：它能决定落盘的相对路径。少了这一条，
+ * 一个被投毒的技能就能往 `~/.ssh/authorized_keys` 写东西。
+ */
+function safeJoin(base, relative) {
+  const raw = String(relative ?? '');
+  const pieces = raw.split(/[/\\]/);
+  if (path.isAbsolute(raw) || pieces.includes('..')) {
+    throw CliError.usage(`skill bundle 里的路径不安全（${raw}）：拒绝落盘`).withHint(
+      '这是服务端发布源的问题，报给运维',
+    );
+  }
+  return path.join(base, raw);
+}
+
+/** `candidate` 的**路径分量尾部**是不是 `relative`（对齐 Rust `Path::ends_with`）。 */
+function pathEndsWith(candidate, relative) {
+  const wanted = String(relative ?? '')
+    .split(/[/\\]/)
+    .filter((piece) => piece.length > 0 && piece !== '.');
+  if (wanted.length === 0) return false;
+  const parts = String(candidate).split(path.sep).filter((piece) => piece.length > 0);
+  if (wanted.length > parts.length) return false;
+  const tail = parts.slice(parts.length - wanted.length);
+  return wanted.every((piece, index) => tail[index] === piece);
+}
+
+function sha256Hex(bytes) {
+  return crypto.createHash('sha256').update(bytes).digest('hex');
+}
+
+/**
+ * 拼一个"给人看的"路径（`dir` / `dest` 字段），与 Rust `PathBuf::display()` 同形：
+ * 保留调用方写的相对写法（`./skills/x` 不会变成 `skills/x`）。
+ */
+function rustJoin(dest, name) {
+  return `${String(dest).replace(/[/\\]+$/, '')}${path.sep}${name}`;
+}
+
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** 请求体的键按字典序（serde_json 的 Map 是 BTreeMap，请求体字节也照抄这个顺序）。 */
+function sortKeys(object) {
+  const out = {};
+  for (const key of Object.keys(object).sort()) out[key] = object[key];
+  return out;
+}
+
+/**
+ * 取 SKILL.md 的第一段（front-matter 与标题之后的描述）当"什么时候用"。
+ *
+ * 与 Rust `first_paragraph` 逐条同义：跳过 `---` 包起来的 front-matter，
+ * 跳过标题行，遇到空行收尾，按 160 **字符**（不是字节）截断并补省略号。
+ */
+export function firstParagraph(content) {
+  const lines = String(content ?? '').split('\n');
+  let index = 0;
+  if ((lines[0] ?? '').trim() === '---') {
+    index = 1;
+    while (index < lines.length && lines[index].trim() !== '---') index += 1;
+    index += 1;
+  }
+  let out = '';
+  for (; index < lines.length; index += 1) {
+    const trimmed = lines[index].trim();
+    if (trimmed.length === 0) {
+      if (out.length > 0) break;
+      continue;
+    }
+    if (trimmed.startsWith('#')) {
+      if (out.length > 0) break;
+      continue;
+    }
+    if (out.length > 0) out += ' ';
+    out += trimmed;
+    if (Array.from(out).length > 160) break;
+  }
+  const chars = Array.from(out);
+  const result = chars.slice(0, 160).join('');
+  return chars.length > 160 ? `${result}…` : result;
+}