rol-websocket-channel 1.0.0

package/src/admin/methods/skills.ts

@@ -0,0 +1,651 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+import { ensureDir, pathExists, readJsonFile } from '../lib/fs.ts';
+import { JsonRpcException, JSON_RPC_ERRORS } from '../jsonrpc.ts';
+import type { JsonValue, MethodContext, MethodHandler } from '../types.ts';
+
+const execFileAsync = promisify(execFile);
+
+interface SkillManifest {
+  slug?: string;
+  name?: string;
+  version?: string;
+  description?: string;
+  author?: string;
+  tags?: string[];
+  [key: string]: JsonValue | undefined;
+}
+
+interface InstallSkillParams {
+  package: string;
+  scope?: string;
+}
+
+interface ClawHubSearchParams {
+  query?: string;
+}
+
+interface ClawHubSkillParams {
+  slug: string;
+}
+
+interface ResolvedSkillIdentity {
+  slug: string;
+  displayName: string;
+  dirName: string;
+}
+
+interface OpenClawConfig {
+  agents?: {
+    defaults?: {
+      skills?: string[];
+      [key: string]: JsonValue | undefined;
+    };
+    [key: string]: JsonValue | undefined;
+  };
+  skills?: {
+    allowBundled?: string[];
+    entries?: Record<string, { enabled?: boolean; [key: string]: JsonValue | undefined }>;
+    [key: string]: JsonValue | undefined;
+  };
+  [key: string]: JsonValue | undefined;
+}
+
+interface CustomInstalledSkill {
+  slug: string;
+  name: string;
+  description: string;
+  version: string | null;
+  source: 'custom-npm';
+  bundled: false;
+  custom: true;
+  installed: true;
+  enabled: boolean;
+  eligible: boolean;
+  scope: 'global' | 'workspace';
+  installPath: string;
+  package: string | null;
+  aliases: string[];
+  actions: {
+    canToggle: true;
+    canUninstall: true;
+    canAttach: true;
+  };
+}
+
+export const listInstalledSkills: MethodHandler = async (_params, context): Promise<JsonValue> => {
+  const items = await getInstalledSkillsFromCli(context);
+  return {
+    count: items.length,
+    items
+  };
+};
+
+export const installSkillFromNpm: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const objectParams = expectObject(params) as unknown as InstallSkillParams;
+  const packageSpec = expectString(objectParams.package, 'package');
+  const scope = normalizeScope(objectParams.scope);
+  const installRoot = resolveInstallRoot(context.openclawRoot, scope);
+
+  await ensureDir(installRoot);
+
+  const tempRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'openclaw-skill-install-'));
+
+  try {
+    const tarballName = await npmPack(packageSpec, tempRoot);
+    const tarballPath = path.join(tempRoot, tarballName);
+    const extractRoot = path.join(tempRoot, 'extract');
+    await ensureDir(extractRoot);
+    await extractTarball(tarballPath, extractRoot);
+
+    const packageRoot = await resolvePackedPackageRoot(extractRoot);
+    await assertSkillPackage(packageRoot);
+
+    const skillInfo = await resolveSkillIdentity(packageRoot, packageSpec);
+    const targetDir = path.join(installRoot, skillInfo.dirName);
+
+    await fs.rm(targetDir, { recursive: true, force: true });
+    await fs.cp(packageRoot, targetDir, { recursive: true });
+
+    await fs.writeFile(
+      path.join(targetDir, '.openclaw-admin-bridge-install.json'),
+      JSON.stringify(
+        {
+          source: 'npm',
+          package: packageSpec,
+          scope,
+          installedAt: new Date().toISOString()
+        },
+        null,
+        2
+      ),
+      'utf8'
+    );
+
+    return {
+      ok: true,
+      scope,
+      package: packageSpec,
+      slug: skillInfo.slug,
+      skillName: skillInfo.displayName,
+      installPath: targetDir
+    };
+  } finally {
+    await fs.rm(tempRoot, { recursive: true, force: true });
+  }
+};
+
+export const searchClawHubSkills: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const objectParams = isObject(params) ? params : {};
+  const query = typeof objectParams.query === 'string' ? objectParams.query.trim() : '';
+  const args = query ? ['skills', 'search', query, '--json'] : ['skills', 'search', '--json'];
+  const result = await runOpenClawSkillCommand(args, context.projectRoot);
+
+  return {
+    ok: true,
+    query,
+    ...result
+  };
+};
+
+export const installSkillFromClawHub: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const objectParams = expectObject(params) as unknown as ClawHubSkillParams;
+  const slug = expectString(objectParams.slug, 'slug');
+  const result = await runOpenClawSkillCommand(['skills', 'install', slug], context.projectRoot);
+
+  return {
+    ok: true,
+    slug,
+    ...result
+  };
+};
+
+export const updateSkillFromClawHub: MethodHandler = async (params, context): Promise<JsonValue> => {
+  const objectParams = expectObject(params) as unknown as ClawHubSkillParams;
+  const slug = expectString(objectParams.slug, 'slug');
+  const result = await runOpenClawSkillCommand(['skills', 'update', slug], context.projectRoot);
+
+  return {
+    ok: true,
+    slug,
+    ...result
+  };
+};
+
+export async function getInstalledSkillsFromCli(context: MethodContext): Promise<JsonValue[]> {
+  const skillState = await getSkillState(context);
+  const cliItems = await queryOpenClawSkills(context);
+  const officialSkills = cliItems.map((item) => normalizeCliSkill(item, skillState));
+  const customSkills = await listCustomInstalledSkills(context, skillState.enabledCustomSkills);
+  return mergeSkillSources(officialSkills, customSkills);
+}
+
+function expectObject(value: JsonValue | undefined): Record<string, JsonValue> {
+  if (!value || Array.isArray(value) || typeof value !== 'object') {
+    throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Params must be an object');
+  }
+
+  return value as Record<string, JsonValue>;
+}
+
+function expectString(value: JsonValue | undefined, fieldName: string): string {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.invalidParams,
+      `Field '${fieldName}' must be a non-empty string`
+    );
+  }
+
+  return value.trim();
+}
+
+function normalizeScope(rawScope: string | undefined): 'global' | 'workspace' {
+  return rawScope === 'workspace' ? 'workspace' : 'global';
+}
+
+function resolveInstallRoot(openclawRoot: string, scope: 'global' | 'workspace'): string {
+  return scope === 'workspace'
+    ? path.join(openclawRoot, 'workspace', '.openclaw', 'skills')
+    : path.join(openclawRoot, 'skills');
+}
+
+async function npmPack(packageSpec: string, cwd: string): Promise<string> {
+  const { stdout } = await execFileAsync('npm', ['pack', packageSpec], { cwd });
+  const tarballName = stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .at(-1);
+
+  if (!tarballName || !tarballName.endsWith('.tgz')) {
+    throw new JsonRpcException(JSON_RPC_ERRORS.internalError, 'npm pack did not return a tarball name', {
+      package: packageSpec,
+      stdout
+    });
+  }
+
+  return tarballName;
+}
+
+async function runOpenClawSkillCommand(
+  args: string[],
+  cwd: string
+): Promise<{ stdout: string; stderr: string; parsed: JsonValue | null }> {
+  const command = process.env.OPENCLAW_BIN || 'openclaw';
+
+  try {
+    const { stdout, stderr } = await execFileAsync(command, args, { cwd });
+    return {
+      stdout,
+      stderr,
+      parsed: parseJsonOutput(stdout)
+    };
+  } catch (err: any) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.internalError,
+      `OpenClaw skill command failed: ${err instanceof Error ? err.message : String(err)}`,
+      {
+        command,
+        args,
+        stdout: typeof err?.stdout === 'string' ? err.stdout : '',
+        stderr: typeof err?.stderr === 'string' ? err.stderr : ''
+      }
+    );
+  }
+}
+
+function parseJsonOutput(stdout: string): JsonValue | null {
+  const trimmed = stdout.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  try {
+    return JSON.parse(trimmed) as JsonValue;
+  } catch {
+    return null;
+  }
+}
+
+async function queryOpenClawSkills(context: MethodContext): Promise<unknown[]> {
+  const command = process.env.OPENCLAW_BIN || 'openclaw';
+
+  try {
+    const { stdout } = await execFileAsync(command, ['skills', 'list', '--json'], {
+      cwd: context.projectRoot
+    });
+    const parsed = JSON.parse(stdout) as unknown;
+
+    if (Array.isArray(parsed)) {
+      return parsed;
+    }
+
+    if (isRecord(parsed)) {
+      const items = parsed.items;
+      const skills = parsed.skills;
+      if (Array.isArray(items)) return items;
+      if (Array.isArray(skills)) return skills;
+    }
+
+    throw new Error('Unexpected JSON shape returned by OpenClaw CLI');
+  } catch (err) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.internalError,
+      `Failed to query OpenClaw skills list: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+
+function normalizeCliSkill(
+  skill: unknown,
+  skillState: {
+    enabledCustomSkills: Set<string>;
+    allowBundled: Set<string> | null;
+    entriesEnabled: Map<string, boolean>;
+  }
+): Record<string, JsonValue> {
+  if (!isRecord(skill)) {
+    return {
+      raw: skill
+    };
+  }
+
+  const slug = pickString(skill.slug)
+    ?? pickString(skill.name)
+    ?? pickString(skill.id)
+    ?? 'unknown';
+
+  const bundled = pickBoolean(skill.bundled) ?? false;
+  const source = bundled ? 'bundled' : 'official';
+  const enabledFromEntry = skillState.entriesEnabled.get(slug);
+  const enabled = enabledFromEntry ?? (
+    bundled
+      ? resolveBundledEnabled(slug, skill, skillState.allowBundled)
+      : (
+          pickBoolean(skill.enabled)
+          ?? pickBoolean(skill.active)
+          ?? invertBoolean(pickBoolean(skill.disabled))
+          ?? skillState.enabledCustomSkills.has(slug)
+        )
+  );
+
+  return {
+    ...skill,
+    slug,
+    name: pickString(skill.name) ?? slug,
+    installed: true,
+    enabled,
+    bundled,
+    custom: false,
+    source,
+    actions: {
+      canToggle: true,
+      canUninstall: !bundled,
+      canAttach: true
+    }
+  };
+}
+
+async function listCustomInstalledSkills(
+  context: MethodContext,
+  enabledSkills: Set<string>
+): Promise<CustomInstalledSkill[]> {
+  const roots: Array<{ scope: 'global' | 'workspace'; dir: string }> = [
+    { scope: 'global', dir: path.join(context.openclawRoot, 'skills') },
+    { scope: 'workspace', dir: path.join(context.openclawRoot, 'workspace', '.openclaw', 'skills') }
+  ];
+  const items: CustomInstalledSkill[] = [];
+
+  for (const root of roots) {
+    if (!(await pathExists(root.dir))) {
+      continue;
+    }
+
+    const entries = await fs.readdir(root.dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      const installPath = path.join(root.dir, entry.name);
+      const manifest = await readSkillManifest(installPath);
+      const installMeta = await readInstallMeta(installPath);
+      const installPackage = pickString(installMeta.package);
+      const fallbackBase = installPackage && installPackage.trim().length > 0 ? installPackage.trim() : entry.name;
+      const fallbackSegment = extractSkillSegment(fallbackBase);
+      const slug = pickString(manifest.slug) ?? sanitizeDirName(fallbackSegment);
+      const displayName = pickString(manifest.name) ?? slug;
+      const aliases = buildCustomSkillAliases(slug, displayName, entry.name, installPackage);
+
+      items.push({
+        slug,
+        name: displayName,
+        description: pickString(manifest.description) ?? '',
+        version: pickString(manifest.version) ?? null,
+        source: 'custom-npm',
+        bundled: false,
+        custom: true,
+        installed: true,
+        enabled: enabledSkills.has(slug),
+        eligible: true,
+        scope: root.scope,
+        installPath,
+        package: pickString(installMeta.package) ?? null,
+        aliases,
+        actions: {
+          canToggle: true,
+          canUninstall: true,
+          canAttach: true
+        }
+      });
+    }
+  }
+
+  return items;
+}
+
+async function readSkillManifest(skillDir: string): Promise<SkillManifest> {
+  const skillJsonPath = path.join(skillDir, 'skill.json');
+  const packageJsonPath = path.join(skillDir, 'package.json');
+
+  if (await pathExists(skillJsonPath)) {
+    return await readJsonFile<SkillManifest>(skillJsonPath);
+  }
+
+  if (await pathExists(packageJsonPath)) {
+    return await readJsonFile<SkillManifest>(packageJsonPath);
+  }
+
+  return {};
+}
+
+async function readInstallMeta(skillDir: string): Promise<Record<string, JsonValue>> {
+  const installMetaPath = path.join(skillDir, '.openclaw-admin-bridge-install.json');
+  if (!(await pathExists(installMetaPath))) {
+    return {};
+  }
+
+  return await readJsonFile<Record<string, JsonValue>>(installMetaPath);
+}
+
+function mergeSkillSources(
+  officialSkills: Record<string, JsonValue>[],
+  customSkills: CustomInstalledSkill[]
+): JsonValue[] {
+  const merged = new Map<string, JsonValue>();
+
+  for (const skill of officialSkills) {
+    const slug = typeof skill.slug === 'string' ? skill.slug : null;
+    if (slug) {
+      merged.set(slug, skill);
+    }
+  }
+
+  for (const custom of customSkills) {
+    const existing = merged.get(custom.slug);
+    if (existing && isRecord(existing)) {
+      merged.set(custom.slug, {
+        ...existing,
+        custom: true,
+        customInstallPath: custom.installPath,
+        customPackage: custom.package,
+        customAliases: custom.aliases,
+        actions: {
+          canToggle: true,
+          canUninstall: true,
+          canAttach: true
+        }
+      });
+      continue;
+    }
+
+    merged.set(custom.slug, custom as unknown as JsonValue);
+  }
+
+  return Array.from(merged.values()).sort((a, b) => {
+    const aSlug = isRecord(a) && typeof a.slug === 'string' ? a.slug : '';
+    const bSlug = isRecord(b) && typeof b.slug === 'string' ? b.slug : '';
+    return aSlug.localeCompare(bSlug);
+  });
+}
+
+async function getSkillState(
+  context: MethodContext
+): Promise<{
+  enabledCustomSkills: Set<string>;
+  allowBundled: Set<string> | null;
+  entriesEnabled: Map<string, boolean>;
+}> {
+  const configPath = path.join(context.openclawRoot, 'openclaw.json');
+  if (!(await pathExists(configPath))) {
+    return {
+      enabledCustomSkills: new Set<string>(),
+      allowBundled: null,
+      entriesEnabled: new Map<string, boolean>()
+    };
+  }
+
+  const config = await readJsonFile<OpenClawConfig>(configPath);
+  const skills = config.agents?.defaults?.skills;
+  const enabledCustomSkills = new Set(
+    Array.isArray(skills)
+      ? skills.filter((item): item is string => typeof item === 'string')
+      : []
+  );
+  const allowBundled = Array.isArray(config.skills?.allowBundled)
+    ? new Set(config.skills?.allowBundled.filter((item): item is string => typeof item === 'string'))
+    : null;
+  const entriesEnabled = new Map<string, boolean>();
+  if (config.skills?.entries && typeof config.skills.entries === 'object') {
+    for (const [key, value] of Object.entries(config.skills.entries)) {
+      if (value && typeof value === 'object' && typeof value.enabled === 'boolean') {
+        entriesEnabled.set(key, value.enabled);
+      }
+    }
+  }
+
+  return {
+    enabledCustomSkills,
+    allowBundled,
+    entriesEnabled
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function isObject(value: JsonValue | undefined): value is Record<string, JsonValue> {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function pickString(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function pickBoolean(value: unknown): boolean | undefined {
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function invertBoolean(value: boolean | undefined): boolean | undefined {
+  return value === undefined ? undefined : !value;
+}
+
+function resolveBundledEnabled(
+  slug: string,
+  skill: Record<string, any>,
+  allowBundled: Set<string> | null
+): boolean {
+  if (allowBundled === null) {
+    return (
+      pickBoolean(skill.enabled)
+      ?? pickBoolean(skill.active)
+      ?? invertBoolean(pickBoolean(skill.disabled))
+      ?? true
+    );
+  }
+
+  return allowBundled.has(slug);
+}
+
+async function extractTarball(tarballPath: string, extractRoot: string): Promise<void> {
+  await execFileAsync('tar', ['-xzf', tarballPath, '-C', extractRoot]);
+}
+
+async function resolvePackedPackageRoot(extractRoot: string): Promise<string> {
+  const packageRoot = path.join(extractRoot, 'package');
+  if (await pathExists(packageRoot)) {
+    return packageRoot;
+  }
+
+  throw new JsonRpcException(JSON_RPC_ERRORS.internalError, 'Packed npm artifact did not contain package/ root', {
+    extractRoot
+  });
+}
+
+async function assertSkillPackage(packageRoot: string): Promise<void> {
+  if (!(await pathExists(path.join(packageRoot, 'SKILL.md')))) {
+    throw new JsonRpcException(
+      JSON_RPC_ERRORS.invalidParams,
+      'npm package is not a valid skill package: missing SKILL.md'
+    );
+  }
+}
+
+async function resolveSkillIdentity(packageRoot: string, packageSpec: string): Promise<ResolvedSkillIdentity> {
+  const skillJsonPath = path.join(packageRoot, 'skill.json');
+  let manifest: SkillManifest | null = null;
+
+  if (await pathExists(skillJsonPath)) {
+    manifest = await readJsonFile<SkillManifest>(skillJsonPath);
+  }
+
+  const fallbackBase = packageSpec && packageSpec.trim().length > 0 ? packageSpec.trim() : packageSpec;
+  const fallbackSegment = extractSkillSegment(fallbackBase);
+  const slug = pickString(manifest?.slug) ?? sanitizeDirName(fallbackSegment);
+  const displayName = pickString(manifest?.name) ?? slug;
+  const dirName = sanitizeDirName(slug);
+
+  return { slug, displayName, dirName };
+}
+
+/**
+ * 从包名中提取用于推断 slug 的片段：
+ * - scoped 包（@foo/bar）→ 取 scope 部分 foo（与 OpenClaw CLI 行为一致）
+ * - 普通带斜杠包（foo/bar）→ 取最后段 bar
+ * - 无斜杠（foo）→ 原样返回
+ */
+function extractSkillSegment(packageName: string): string {
+  if (packageName.startsWith('@') && packageName.includes('/')) {
+    // @foo/bar → foo
+    return packageName.split('/')[0].replace(/^@/, '');
+  }
+  if (packageName.includes('/')) {
+    // foo/bar → bar
+    return packageName.split('/').at(-1) ?? packageName;
+  }
+  return packageName;
+}
+
+function sanitizeDirName(value: string): string {
+  return value
+    .replace(/^@/, '')
+    .replace(/[\\/]/g, '-')
+    .replace(/[^a-zA-Z0-9._-]+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+    .toLowerCase();
+}
+
+function buildCustomSkillAliases(
+  slug: string,
+  displayName: string,
+  dirName: string,
+  packageName: string | undefined
+): string[] {
+  const values = new Set<string>();
+  const add = (value: string | undefined) => {
+    if (!value) return;
+    const trimmed = value.trim();
+    if (!trimmed) return;
+    values.add(trimmed);
+  };
+
+  add(slug);
+  add(displayName);
+  add(dirName);
+  add(sanitizeDirName(dirName));
+  add(packageName);
+
+  if (packageName) {
+    const lastSegment = packageName.includes('/') ? (packageName.split('/').at(-1) ?? packageName) : packageName;
+    add(lastSegment);
+    add(sanitizeDirName(lastSegment));
+  }
+
+  return Array.from(values);
+}