@aiform/cli-platform 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# @aiform/cli-platform
+
+Hive 平台维护 CLI（`hive-platform`）—— 通过 hive **platform** 服务的 HTTP API 管理租户、平台管理员、岗位、技能、new-api 同步队列。不直连数据库。
+
+租户管理员视角的账号/节点动作在另一个包：[`@aiform/cli-workspace`](https://www.npmjs.com/package/@aiform/cli-workspace)。
+
+## 安装
+
+```bash
+npm i -g @aiform/cli-platform       # 或 pnpm add -g / npx @aiform/cli-platform
+```
+
+## 配置
+
+| 选项 | 环境变量 | 默认 | 用途 |
+|---|---|---|---|
+| `--url <url>` | `PLATFORM_URL` | `http://localhost:3100`（本地 dev） | platform base URL |
+| `--email <email>` | `HIVE_ADMIN_EMAIL` | —（多数命令必填） | 登录用 platform admin email |
+| `--password <pw>` | `HIVE_ADMIN_PASSWORD` | 无则交互输入 | 登录密码 |
+| `--bootstrap-token <t>` | `PLATFORM_BOOTSTRAP_TOKEN` | — | **仅** `platform admin add` 用（首位 admin 还不存在、无 session 时） |
+
+线上 platform：`https://platform.hiv.aiform.com`（对应 workspace：`https://app.hiv.aiform.com`）。
+`PLATFORM_BOOTSTRAP_TOKEN` 也要配在 platform 服务端（启用 `POST /api/platform-admins`）。
+
+## 子命令
+
+```bash
+export PLATFORM_URL=https://platform.hiv.aiform.com   # 本地 dev 省略，默认 http://localhost:3100
+
+# 引导首位 platform 管理员（不需要登录，用 bootstrap token）
+PLATFORM_BOOTSTRAP_TOKEN=... hive-platform platform admin add admin@aiform.com
+
+# 之后用该 admin 登录做其它操作
+export HIVE_ADMIN_EMAIL=admin@aiform.com HIVE_ADMIN_PASSWORD=...
+
+# 租户（POST/GET /api/tenants）
+hive-platform tenant add 'Acme Intelligence' --handle acme.co --plan pro --owner maya@acme.co --seats 50 --logo https://cdn.acme.co/logo.png
+hive-platform tenant list
+
+# 代某租户管理 workspace 成员（POST/GET /api/tenants/:id/users）——引导租户首位成员等
+hive-platform tenant user add maya@acme.co --tenant acme.co --password 'init-pw-123'
+hive-platform tenant user list --tenant acme.co
+
+# new-api 同步队列（POST /api/newapi-outbox/drain、GET /api/newapi-outbox、POST /api/newapi-outbox/:id/requeue）
+hive-platform outbox drain
+hive-platform outbox list --pending
+hive-platform outbox list --dead
+hive-platform outbox requeue <id>
+
+# 岗位（/api/positions*）
+hive-platform position add 'Data Analyst' --code DATA_ANALYST --capability sql --skill <skillId> --publish
+hive-platform position list --status published
+hive-platform position publish <positionId>
+hive-platform position archive <positionId>
+hive-platform position enable  <positionId> --tenant acme.co
+hive-platform position disable <positionId> --tenant acme.co
+
+# 技能发布（多文件文件夹 → POST /api/skills + /versions）
+hive-platform skill publish ./my-skill-folder --name my_skill --version 1.2.0 --label 'My Skill'
+```
+
+## 退码
+
+`0` 成功；`1` API/网络错误；`2` 参数错误；`130` 交互输入被 Ctrl-C 取消。

package/bin/hive-platform.mjs

@@ -0,0 +1,562 @@
+#!/usr/bin/env node
+// hive-platform — 平台维护人员 CLI（租户 / 平台管理员 / 岗位 / 技能 / new-api 同步）
+//
+// 通过 platform 的 HTTP API 操作（不直连 DB）。多数命令以 platform admin 身份登录；
+// `platform admin add` 例外 —— 走 PLATFORM_BOOTSTRAP_TOKEN（首位 admin 还不存在时无 session 可用）。
+//
+// 全局选项（root 上）：
+//   --url <url>            platform base URL（默认 PLATFORM_URL，否则 http://localhost:3100）
+//   --email <email>        登录 email（默认 HIVE_ADMIN_EMAIL）
+//   --password <pw>        登录密码（默认 HIVE_ADMIN_PASSWORD，否则交互输入）
+//   --bootstrap-token <t>  platform admin add 用（默认 PLATFORM_BOOTSTRAP_TOKEN）
+//
+// 子命令：
+//   tenant add <name> --handle <h> [--plan ..] [--status ..] [--owner ..] [--seats N] ...
+//   tenant list
+//   tenant topup <handle> --credits N --reason prepaid|renewal|gift|correction [--note ..]
+//   platform admin add <email> [--password <pw>] [--name <displayName>]
+//   outbox drain | outbox list [--limit N] [--pending] [--dead] | outbox requeue <id>
+//   position add <name> --code <code> [--emoji] [--color] [--summary] [--category]
+//                       [--base-model] [--rubric ..]* [--capability ..]* [--skill ..]* [--publish]
+//   position list [--status draft|published|archived]
+//   position publish <id> | position archive <id>
+//   position enable|disable <positionId> --tenant <handle>
+//   skill publish <folder> --version <semver> [--name <name>] [--label] [--description] ...
+//     （name 默认从 <folder>/SKILL.md frontmatter 解析；--name 为可选覆盖，不一致会报错）
+//
+// 租户管理员动作（建账号 / 节点）见 `hive-workspace`。
+
+import { promises as fsp } from 'node:fs';
+import path from 'node:path';
+import { Command } from 'commander';
+import { ApiClient, resolveBaseUrl, resolveCreds, runAction, promptHidden, die } from '@aiform/cli-core';
+
+const TAG = 'hive-platform';
+
+const program = new Command();
+program
+  .name('hive-platform')
+  .description('hive 平台维护 CLI（租户 / 平台管理员 / 岗位 / 技能 / new-api 同步）— 通过 platform HTTP API 操作')
+  .option('--url <url>', 'platform base URL（默认 PLATFORM_URL env 或 http://localhost:3100）')
+  .option('--email <email>', '登录 email（默认 HIVE_ADMIN_EMAIL env）')
+  .option('--password <pw>', '登录密码（默认 HIVE_ADMIN_PASSWORD env，否则交互输入）')
+  .option('--bootstrap-token <token>', 'platform admin add 用的 bootstrap token（默认 PLATFORM_BOOTSTRAP_TOKEN env）')
+  // 用 --cli-version 而不是 --version：让 `skill publish --version <semver>` 不被全局版本标记吞掉。
+  .version('0.1.0', '-V, --cli-version', '显示 CLI 版本');
+
+function baseUrl() {
+  return resolveBaseUrl(program.opts().url, 'PLATFORM_URL', 'http://localhost:3100');
+}
+
+/** 取一个已登录的 ApiClient（platform admin session）。 */
+async function client() {
+  const creds = await resolveCreds(program.opts(), {
+    tag: TAG,
+    emailEnv: 'HIVE_ADMIN_EMAIL',
+    passwordEnv: 'HIVE_ADMIN_PASSWORD',
+  });
+  const c = new ApiClient(baseUrl());
+  await c.login(creds);
+  return c;
+}
+
+function parseRepeat(value, prev = []) {
+  return prev.concat([value]);
+}
+
+// ── 租户 ─────────────────────────────────────────────────────────────
+
+const tenantCmd = program.command('tenant').description('租户管理');
+
+tenantCmd
+  .command('add <name>')
+  .description('创建租户（= platform UI /tenants/new；同步触发 new-api provision）')
+  .requiredOption('--handle <handle>', '租户 handle，如 acme.co')
+  .option('--plan <plan>', '套餐：enterprise|pro|standard|trial', 'standard')
+  .option('--status <status>', '初始状态：active|trial|suspended', 'active')
+  .option('--seats <n>', '席位上限', '0')
+  .option('--spend-limit <n>', '月度花费上限（¥）', '0')
+  .option('--token-cap <n>', 'Token 上限（M）', '0')
+  .option('--owner <email>', '主管理员邮箱')
+  .option('--notes <text>', '备注')
+  .option('--logo <url>', '徽标 URL（http/https 直链）')
+  .action(runAction(TAG, async (name, opts) => {
+    const c = await client();
+    const r = await c.post('/api/tenants', {
+      name,
+      handle: opts.handle,
+      plan: opts.plan,
+      status: opts.status,
+      seats: Number.parseInt(opts.seats, 10) || 0,
+      spendLimit: Number.parseFloat(opts.spendLimit) || 0,
+      tokenCap: Number.parseFloat(opts.tokenCap) || 0,
+      ownerEmail: opts.owner || null,
+      adminEmails: opts.owner ? [opts.owner] : [],
+      notes: opts.notes || null,
+      logoUrl: opts.logo || null,
+    });
+    const t = r.tenant;
+    console.log(`[${TAG}] tenant added id=${t.id} handle=${t.handle} plan=${t.plan} status=${t.status}`);
+    const p = r.provisioning;
+    if (p) {
+      if (p.status === 'ok') {
+        console.log(`[${TAG}] new-api 子账号已创建 (newapi_user_id=${p.newapiUserId ?? '?'})`);
+      } else {
+        console.warn(`[${TAG}] new-api provision ${p.status}: ${p.errorCode ?? ''} — ${p.errorMessage ?? ''}`);
+        console.warn(`[${TAG}] tenant 行已落库；修好后 \`hive-platform outbox drain\` 重试，或在 platform UI 详情页"立即 provision"`);
+      }
+    }
+  }));
+
+tenantCmd
+  .command('list')
+  .description('列出所有租户')
+  .action(runAction(TAG, async () => {
+    const c = await client();
+    const r = await c.get('/api/tenants');
+    console.table(r.tenants);
+  }));
+
+tenantCmd
+  .command('topup <handle>')
+  .description('给租户充值 new-api 额度（= spend_limit 增量；提交后同步 quota）')
+  .requiredOption('--credits <n>', '充值 credits（正整数）')
+  .requiredOption('--reason <reason>', '原因：prepaid|renewal|gift|correction')
+  .option('--note <note>', '备注（选填）')
+  .action(runAction(TAG, async (handle, opts) => {
+    // 本地早校验（client() 之前，无需登录即可拦明显错误）；端点 Zod 才是权威。
+    const credits = Number.parseInt(opts.credits, 10);
+    if (!Number.isInteger(credits) || credits <= 0) die(TAG, 'credits 须为正整数', 2);
+    const REASONS = ['prepaid', 'renewal', 'gift', 'correction'];
+    if (!REASONS.includes(opts.reason)) die(TAG, `reason 须为 ${REASONS.join('|')}`, 2);
+    const c = await client();
+    const tenantId = await resolveTenantId(c, handle);
+    const r = await c.post(`/api/tenants/${encodeURIComponent(tenantId)}/newapi/topup`, {
+      credits,
+      reason: opts.reason,
+      note: opts.note ?? null,
+    });
+    const usd = typeof r.deltaUsd === 'number' ? r.deltaUsd.toFixed(2) : r.deltaUsd;
+    console.log(
+      `[${TAG}] topup ok: +${credits} credits（≈$${usd}）新总额 $${r.spendLimitAfter} synced=${r.synced} ledger=${r.ledgerId}` +
+        (r.message ? ` — ${r.message}` : ''),
+    );
+  }));
+
+// 平台代某租户管理 workspace 成员（POST/GET /api/tenants/[id]/users）。
+// 引导租户首位成员、运营帮租户加人时用；租户管理员自助加人走 `hive-workspace user add`。
+const tenantUserCmd = tenantCmd.command('user').description('租户成员（平台代操作）');
+
+tenantUserCmd
+  .command('add <email>')
+  .description('在指定租户下新增 workspace 成员（平台代建）')
+  .requiredOption('--tenant <handle>', '目标租户的 handle')
+  .option('--password <pw>', '初始密码（≥8 位；不传则交互输入）')
+  .option('--slug <slug>', 'user_slug（默认按 email 自动生成并去重）')
+  .action(runAction(TAG, async (email, opts) => {
+    let pw = opts.password;
+    if (!pw) {
+      try {
+        pw = await promptHidden('member password: ');
+      } catch {
+        die(TAG, 'aborted', 130);
+      }
+    }
+    if (!pw) die(TAG, 'password 不能为空', 2);
+    const c = await client();
+    const tenantId = await resolveTenantId(c, opts.tenant);
+    const r = await c.post(`/api/tenants/${encodeURIComponent(tenantId)}/users`, {
+      email,
+      password: pw,
+      slug: opts.slug,
+    });
+    const u = r.user;
+    console.log(`[${TAG}] member added id=${u.id} email=${u.email} slug=${u.userSlug} tenant=${String(opts.tenant).toLowerCase()}`);
+  }));
+
+tenantUserCmd
+  .command('list')
+  .description('列出指定租户的成员')
+  .requiredOption('--tenant <handle>', '目标租户的 handle')
+  .action(runAction(TAG, async (opts) => {
+    const c = await client();
+    const tenantId = await resolveTenantId(c, opts.tenant);
+    const r = await c.get(`/api/tenants/${encodeURIComponent(tenantId)}/users`);
+    console.table(r.users);
+  }));
+
+// ── Platform 管理员（bootstrap token 通道）──────────────────────────
+
+const platformCmd = program.command('platform').description('Platform 管控台运维');
+const platformAdminCmd = platformCmd.command('admin').description('Platform 管理员');
+
+platformAdminCmd
+  .command('add <email>')
+  .description('引导新建 platform 管理员（用 --bootstrap-token / PLATFORM_BOOTSTRAP_TOKEN，不需要登录）')
+  .option('--password <pw>', '密码（≥8 位；不传则交互输入）')
+  .option('--name <displayName>', '展示名')
+  .action(runAction(TAG, async (email, opts) => {
+    const token = program.opts().bootstrapToken || process.env.PLATFORM_BOOTSTRAP_TOKEN;
+    if (!token) die(TAG, '--bootstrap-token 或环境变量 PLATFORM_BOOTSTRAP_TOKEN 必填', 2);
+    let pw = opts.password;
+    if (!pw) {
+      try {
+        pw = await promptHidden('platform admin password: ');
+      } catch {
+        die(TAG, 'aborted', 130);
+      }
+    }
+    if (!pw) die(TAG, 'password 不能为空', 2);
+
+    const c = new ApiClient(baseUrl());
+    const r = await c.post(
+      '/api/platform-admins',
+      { email, password: pw, displayName: opts.name || null },
+      { headers: { Authorization: `Bearer ${token}` } },
+    );
+    const a = r.admin;
+    console.log(`[${TAG}] platform admin added id=${a.id} email=${a.email}`);
+  }));
+
+// ── new-api outbox ──────────────────────────────────────────────────
+
+const outboxCmd = program.command('outbox').description('new-api 同步队列');
+
+outboxCmd
+  .command('drain')
+  .description('手动 drain 一批 outbox 行')
+  .action(runAction(TAG, async () => {
+    const c = await client();
+    const r = await c.post('/api/newapi-outbox/drain');
+    const s = r.stats || {};
+    console.log(`[${TAG}] outbox drain: picked=${s.picked ?? '?'} succeeded=${s.succeeded ?? '?'} failed=${s.failed ?? '?'} dead=${s.dead ?? '?'}`);
+    if (s.dead > 0) console.log(`[${TAG}] note: ${s.dead} 条进死信；\`outbox list --dead\` 查看，\`outbox requeue <id>\` 复活`);
+  }));
+
+outboxCmd
+  .command('list')
+  .description('列出最近 outbox 行')
+  .option('--limit <n>', '行数上限', '50')
+  .option('--pending', '仅未完成')
+  .option('--dead', '仅死信（attempts >= 12 且 done_at 已设）')
+  .action(runAction(TAG, async (opts) => {
+    const c = await client();
+    const r = await c.get('/api/newapi-outbox', {
+      query: { limit: opts.limit, pending: opts.pending, dead: opts.dead },
+    });
+    console.table(r.rows);
+  }));
+
+outboxCmd
+  .command('requeue <id>')
+  .description('把指定死信行重置回待办')
+  .action(runAction(TAG, async (id) => {
+    const numId = Number(id);
+    if (!Number.isInteger(numId) || numId <= 0) die(TAG, `id 必须为正整数: ${id}`, 2);
+    const c = await client();
+    await c.post(`/api/newapi-outbox/${numId}/requeue`);
+    console.log(`[${TAG}] outbox row ${numId} requeued`);
+  }));
+
+// ── 岗位 ─────────────────────────────────────────────────────────────
+
+const positionCmd = program.command('position').description('岗位管理');
+
+positionCmd
+  .command('add <name>')
+  .description('创建岗位草稿（--publish 则创建后立即发布）')
+  .requiredOption('--code <code>', '岗位代码（A-Z 0-9 _ -），全平台唯一')
+  .option('--emoji <emoji>', 'emoji 标识')
+  .option('--color <color>', 'hex 颜色，如 #2a42ff')
+  .option('--summary <text>', '简介')
+  .option('--category <cat>', '分类')
+  .option('--base-model <model>', '默认模型')
+  .option('--rubric <text>', '交付准则（可重复）', parseRepeat, [])
+  .option('--capability <tag>', '能力 tag（可重复）', parseRepeat, [])
+  .option('--skill <id>', '挂载的 skill id（可重复）', parseRepeat, [])
+  .option('--publish', '创建后立即发布', false)
+  .action(runAction(TAG, async (name, opts) => {
+    const c = await client();
+    const r = await c.post('/api/positions', {
+      name,
+      code: opts.code,
+      emoji: opts.emoji || null,
+      color: opts.color || null,
+      summary: opts.summary || null,
+      category: opts.category || null,
+      baseModel: opts.baseModel || null,
+      rubric: opts.rubric,
+      capabilities: opts.capability,
+      skillIds: opts.skill,
+    });
+    const p = r.position;
+    let status = p.status;
+    if (opts.publish) {
+      await c.post(`/api/positions/${encodeURIComponent(p.id)}/publish`);
+      status = 'published';
+    }
+    console.log(`[${TAG}] position added id=${p.id} code=${p.code} status=${status}`);
+  }));
+
+positionCmd
+  .command('list')
+  .description('列出岗位')
+  .option('--status <status>', '过滤 draft|published|archived')
+  .action(runAction(TAG, async (opts) => {
+    if (opts.status && !['draft', 'published', 'archived'].includes(opts.status)) {
+      die(TAG, `status 不合法: ${opts.status}`, 2);
+    }
+    const c = await client();
+    const r = await c.get('/api/positions');
+    const rows = opts.status ? r.positions.filter((p) => p.status === opts.status) : r.positions;
+    console.table(rows);
+  }));
+
+positionCmd
+  .command('publish <id>')
+  .description('草稿 → 已发布')
+  .action(runAction(TAG, async (id) => {
+    const c = await client();
+    const r = await c.post(`/api/positions/${encodeURIComponent(id)}/publish`);
+    console.log(`[${TAG}] published ${id}${r.position?.code ? ` (code=${r.position.code})` : ''}`);
+  }));
+
+positionCmd
+  .command('archive <id>')
+  .description('任意状态 → 已归档（级联取消所有租户启用）')
+  .action(runAction(TAG, async (id) => {
+    const c = await client();
+    const r = await c.post(`/api/positions/${encodeURIComponent(id)}/archive`);
+    console.log(`[${TAG}] archived ${id}${r.position?.code ? ` (code=${r.position.code})` : ''}`);
+  }));
+
+/** handle → tenantId（用 GET /api/tenants）。 */
+async function resolveTenantId(c, handle) {
+  const r = await c.get('/api/tenants');
+  const t = (r.tenants || []).find((x) => x.handle === String(handle).toLowerCase());
+  if (!t) die(TAG, `tenant not found by handle: ${handle}`, 2);
+  return t.id;
+}
+
+positionCmd
+  .command('enable <positionId>')
+  .description('代某租户启用此岗位')
+  .requiredOption('--tenant <handle>', '目标租户的 handle')
+  .action(runAction(TAG, async (positionId, opts) => {
+    const c = await client();
+    const tenantId = await resolveTenantId(c, opts.tenant);
+    await c.post(`/api/positions/${encodeURIComponent(positionId)}/tenants`, { tenantId, enabled: true });
+    console.log(`[${TAG}] enabled position=${positionId} for tenant=${String(opts.tenant).toLowerCase()}`);
+  }));
+
+positionCmd
+  .command('disable <positionId>')
+  .description('代某租户关闭此岗位')
+  .requiredOption('--tenant <handle>', '目标租户的 handle')
+  .action(runAction(TAG, async (positionId, opts) => {
+    const c = await client();
+    const tenantId = await resolveTenantId(c, opts.tenant);
+    await c.post(`/api/positions/${encodeURIComponent(positionId)}/tenants`, { tenantId, enabled: false });
+    console.log(`[${TAG}] disabled position=${positionId} for tenant=${String(opts.tenant).toLowerCase()}`);
+  }));
+
+// ── 技能发布（多文件 → POST /api/skills + /versions）────────────────
+
+const skillCmd = program.command('skill').description('平台技能管理');
+
+const SKILL_IGNORE = new Set(['.DS_Store', '.git', '.svn', '.hg', 'node_modules', '.idea', '.vscode', 'Thumbs.db']);
+const SKILL_FILE_MAX_BYTES = 262_144; // 256 KB
+const SKILL_VERSION_MAX_FILES = 50;
+// 段内禁字符：NUL+控制字符 + Windows 保留 (<>:"\|?*)。`:` 顺带挡掉 C: 盘符。
+const FORBIDDEN_SKILL_PATH_SEG_CHARS = /[<>:"\\|?*\x00-\x1f\x7f]/;
+const SEMVER_RE =
+  /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
+
+/** 与 platform/src/lib/server/skills-validation.ts:isValidSkillFilePath 同步。 */
+function isValidSkillFilePath(s) {
+  if (typeof s !== 'string') return false;
+  if (s.length === 0 || s.length > 200) return false;
+  if (s.startsWith('/')) return false;
+  for (const seg of s.split('/')) {
+    if (seg.length === 0) return false;
+    if (seg === '.' || seg === '..') return false;
+    if (seg !== seg.trim()) return false;
+    if (FORBIDDEN_SKILL_PATH_SEG_CHARS.test(seg)) return false;
+  }
+  return true;
+}
+
+/** raw Buffer 当文本读：含 NUL 或非法 UTF-8 → null（视为二进制，跳过）。 */
+function decodeAsText(buf) {
+  if (buf.includes(0)) return null;
+  try {
+    return new TextDecoder('utf-8', { fatal: true }).decode(buf);
+  } catch {
+    return null;
+  }
+}
+
+function fmtBytes(n) {
+  if (n < 1024) return `${n}B`;
+  return `${(n / 1024).toFixed(1)}KB`;
+}
+
+/** 与 platform/src/lib/server/skills-validation.ts:SKILL_NAME_RE 同步（kebab-case）。 */
+const SKILL_NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/** 解析 SKILL.md 顶部 YAML frontmatter 的顶层标量键（name/description 等）。
+ *  极简零依赖实现：只取首个 `---`…`---` 块内的 `key: value`，去引号；缩进/列表等非标量行忽略。
+ *  无 frontmatter → 返回 {}。 */
+function parseSkillFrontmatter(text) {
+  if (typeof text !== 'string') return {};
+  const body = text.charCodeAt(0) === 0xfeff ? text.slice(1) : text; // 剥前导 BOM
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(body);
+  if (!m) return {};
+  const out = {};
+  for (const line of m[1].split(/\r?\n/)) {
+    if (!line.trim() || line.trimStart().startsWith('#')) continue;
+    if (/^\s/.test(line) || line.trimStart().startsWith('-')) continue; // 跳过嵌套 / 列表项
+    const kv = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    let val = kv[2].trim();
+    if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
+      val = val.slice(1, -1);
+    }
+    out[kv[1]] = val;
+  }
+  return out;
+}
+
+/** 递归读 folder → { files: [{path, content_text, byte_size}], manifest, skipped }。 */
+async function readSkillFolder(folder) {
+  const stat = await fsp.stat(folder).catch(() => null);
+  if (!stat || !stat.isDirectory()) throw new Error(`folder not found or not a directory: ${folder}`);
+  const entries = await fsp.readdir(folder, { recursive: true, withFileTypes: true });
+  const files = [];
+  const skipped = [];
+  let manifest = null;
+  for (const ent of entries) {
+    if (!ent.isFile()) continue;
+    if (SKILL_IGNORE.has(ent.name)) continue;
+    const parent = ent.parentPath ?? ent.path ?? folder;
+    const full = path.join(parent, ent.name);
+    const rel = path.relative(folder, full).split(path.sep).join('/');
+    if (rel.split('/').some((seg) => SKILL_IGNORE.has(seg))) continue;
+
+    const buf = await fsp.readFile(full);
+    const byteSize = buf.byteLength;
+    const content = decodeAsText(buf);
+
+    if (rel === 'manifest.json') {
+      if (content === null) throw new Error('manifest.json is not valid UTF-8 text');
+      try {
+        manifest = JSON.parse(content);
+        if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) {
+          throw new Error('manifest.json must be a JSON object');
+        }
+      } catch (err) {
+        throw new Error(`manifest.json parse error: ${err.message}`);
+      }
+      continue;
+    }
+
+    if (!isValidSkillFilePath(rel)) {
+      throw new Error(`invalid file path '${rel}' (绝对路径、空段、./.. 段、控制字符或 Windows 保留字符)`);
+    }
+    if (content === null) {
+      skipped.push({ path: rel, reason: 'binary', bytes: byteSize });
+      continue;
+    }
+    if (byteSize > SKILL_FILE_MAX_BYTES) {
+      skipped.push({ path: rel, reason: 'oversize', bytes: byteSize });
+      continue;
+    }
+    files.push({ path: rel, content_text: content, byte_size: byteSize });
+  }
+
+  if (files.length === 0) throw new Error(`no eligible files in ${folder}`);
+  if (files.length > SKILL_VERSION_MAX_FILES) throw new Error(`${files.length} files exceeds limit ${SKILL_VERSION_MAX_FILES}`);
+  return { files, manifest: manifest ?? {}, skipped };
+}
+
+skillCmd
+  .command('publish <folder>')
+  .description('把文件夹作为新版本发布到 platform')
+  .option('--name <name>', '技能 name（默认从 SKILL.md frontmatter 的 name 解析；kebab-case，全局唯一；与 frontmatter 不一致会报错）')
+  .requiredOption('--version <semver>', '版本号（合法 SemVer 2.0）')
+  .option('--label <text>', '展示名（仅新建时生效）')
+  .option('--description <text>', '简介（仅新建时生效）')
+  .option('--category <cat>', '分类（仅新建时生效）', 'core')
+  .option('--cert <level>', '认证等级（official|certified|community|deprecated；仅新建时生效）', 'official')
+  .action(runAction(TAG, async (folder, opts) => {
+    if (!SEMVER_RE.test(opts.version)) die(TAG, `invalid semver: ${opts.version}`, 2);
+
+    const url = baseUrl();
+    console.log(`[${TAG}] platform = ${url}`);
+    console.log(`[${TAG}] reading folder ${folder}`);
+    const { files, manifest, skipped } = await readSkillFolder(folder);
+
+    if (skipped.length > 0) {
+      console.warn(`[${TAG}] skipped ${skipped.length} file(s) — platform 只接受 UTF-8 文本，单文件 ≤ ${fmtBytes(SKILL_FILE_MAX_BYTES)}:`);
+      for (const s of skipped) {
+        const why = s.reason === 'binary' ? 'binary (NUL/非 UTF-8)' : `oversize (${fmtBytes(s.bytes)})`;
+        console.warn(`  - ${s.path}  [${why}]`);
+      }
+    }
+    const totalBytes = files.reduce((a, f) => a + f.byte_size, 0);
+    console.log(`[${TAG}] found ${files.length} files: ${files.map((f) => `${f.path} (${fmtBytes(f.byte_size)})`).join(', ')}`);
+    if (manifest && Object.keys(manifest).length > 0) console.log(`[${TAG}] manifest.json found, will use as version manifest`);
+
+    // Agent Skills 规范（https://agentskills.io/specification）：技能根目录必须有 SKILL.md，
+    // frontmatter 必填 name（与技能名一致）+ description；--name 为可选覆盖，不一致则报错。
+    const skillMd = files.find((f) => f.path === 'SKILL.md');
+    if (!skillMd) die(TAG, '缺少 SKILL.md：规范要求技能根目录必须有 SKILL.md（见 https://agentskills.io/specification）', 2);
+    const fm = parseSkillFrontmatter(skillMd.content_text);
+    const fmName = typeof fm.name === 'string' ? fm.name.trim().toLowerCase() : '';
+    const cliName = opts.name ? String(opts.name).trim().toLowerCase() : '';
+    if (!fmName) die(TAG, 'SKILL.md frontmatter 缺少 name', 2);
+    if (cliName && fmName !== cliName) {
+      die(TAG, `name 冲突：SKILL.md frontmatter name='${fmName}' 与 --name='${cliName}' 不一致，请删掉 --name 或改成一致`, 2);
+    }
+    const lookupName = fmName;
+    if (lookupName.length > 64 || !SKILL_NAME_RE.test(lookupName)) {
+      die(TAG, `invalid name '${lookupName}'：需 1–64 kebab-case（小写字母数字连字符，不能前导/末尾/连续连字符）`, 2);
+    }
+    const fmDesc = typeof fm.description === 'string' ? fm.description.trim() : '';
+    if (!fmDesc) die(TAG, 'SKILL.md frontmatter 缺少 description（规范要求必填、非空）', 2);
+    if (fmDesc.length > 1024) die(TAG, `description 超长（${fmDesc.length} > 1024）`, 2);
+    console.log(`[${TAG}] skill name = ${lookupName} (来源：SKILL.md frontmatter)`);
+
+    const c = await client();
+    console.log(`[${TAG}] login OK`);
+
+    const listed = await c.get('/api/skills');
+    let skill = (listed.skills || []).find((s) => s.name === lookupName) ?? null;
+    if (!skill) {
+      console.log(`[${TAG}] skill '${lookupName}' not found, creating ...`);
+      const created = await c.post('/api/skills', {
+        name: lookupName,
+        label: opts.label || lookupName,
+        description: opts.description || fmDesc || null,
+        category: opts.category,
+        cert: opts.cert,
+      });
+      skill = created.skill;
+      console.log(`[${TAG}] skill created (id=${skill.id})`);
+    } else {
+      console.log(`[${TAG}] skill '${lookupName}' exists (id=${skill.id}), reusing`);
+    }
+
+    console.log(`[${TAG}] publishing version ${opts.version} (${files.length} files, ${fmtBytes(totalBytes)} total) ...`);
+    const result = await c.post(`/api/skills/${encodeURIComponent(skill.id)}/versions`, {
+      version: opts.version,
+      files: files.map((f) => ({ path: f.path, content_text: f.content_text })),
+      manifest,
+    });
+    console.log(`[${TAG}] version published ✅`);
+    console.log(`  version_id:   ${result.version.id}`);
+    console.log(`  content_hash: ${result.version.contentHash}`);
+    console.log(`  beta_pointer_updated: ${result.betaPointerUpdated}`);
+  }));
+
+program.parseAsync(process.argv);

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@aiform/cli-platform",
+  "version": "0.1.0",
+  "description": "hive 平台维护 CLI — 通过 platform HTTP API 管理租户/平台管理员/岗位/技能/new-api 同步",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "hive-platform": "./bin/hive-platform.mjs"
+  },
+  "files": [
+    "bin"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "@aiform/cli-core": "^0.1.0"
+  }
+}