rol-websocket-channel 1.4.2 → 1.4.8

package/dist/src/admin/methods/skills.js

@@ -1,528 +1,528 @@
-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.js';
-import { JsonRpcException, JSON_RPC_ERRORS } from '../jsonrpc.js';
-const execFileAsync = promisify(execFile);
-export const listInstalledSkills = async (_params, context) => {
-    const items = await getInstalledSkillsFromCli(context);
-    return {
-        count: items.length,
-        items
-    };
-};
-export const installSkillFromNpm = async (params, context) => {
-    const objectParams = expectObject(params);
-    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 = async (params, context) => {
-    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.openclawRoot, context.openclawRoot);
-    return {
-        ok: true,
-        query,
-        ...result
-    };
-};
-export const installSkillFromClawHub = async (params, context) => {
-    const objectParams = expectObject(params);
-    const slug = expectString(objectParams.slug, 'slug');
-    const result = await runClawHubSkillCommandWithFallback('install', slug, context.openclawRoot, context.openclawRoot);
-    return {
-        ok: true,
-        slug,
-        ...result
-    };
-};
-export const updateSkillFromClawHub = async (params, context) => {
-    const objectParams = expectObject(params);
-    const slug = expectString(objectParams.slug, 'slug');
-    const result = await runClawHubSkillCommandWithFallback('update', slug, context.openclawRoot, context.openclawRoot);
-    return {
-        ok: true,
-        slug,
-        ...result
-    };
-};
-export async function getInstalledSkillsFromCli(context) {
-    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) {
-    if (!value || Array.isArray(value) || typeof value !== 'object') {
-        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Params must be an object');
-    }
-    return value;
-}
-function expectString(value, fieldName) {
-    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) {
-    return rawScope === 'workspace' ? 'workspace' : 'global';
-}
-function resolveInstallRoot(openclawRoot, scope) {
-    return scope === 'workspace'
-        ? path.join(openclawRoot, 'workspace', '.openclaw', 'skills')
-        : path.join(openclawRoot, 'skills');
-}
-async function npmPack(packageSpec, cwd) {
-    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;
-}
-export function buildClawHubSkillCommandPlan(action, slug) {
-    const args = action === 'install' && slug === 'proactive-agent'
-        ? [action, slug, '--force']
-        : [action, slug];
-    return [
-        {
-            command: process.env.CLAWHUB_BIN || 'clawhub',
-            args
-        }
-    ];
-}
-async function runOpenClawSkillCommand(args, cwd, openclawRoot) {
-    const command = process.env.OPENCLAW_BIN || 'openclaw';
-    return await runSkillCommand(command, args, cwd, openclawRoot);
-}
-async function runClawHubSkillCommandWithFallback(action, slug, cwd, openclawRoot) {
-    const attempts = [];
-    for (const invocation of buildClawHubSkillCommandPlan(action, slug)) {
-        try {
-            return await runSkillCommand(invocation.command, invocation.args, cwd, openclawRoot);
-        }
-        catch (err) {
-            const data = err instanceof JsonRpcException && isRecord(err.data) ? err.data : {};
-            attempts.push({
-                command: invocation.command,
-                args: invocation.args,
-                stdout: typeof data.stdout === 'string' ? data.stdout : '',
-                stderr: typeof data.stderr === 'string' ? data.stderr : '',
-                error: err instanceof Error ? err.message : String(err)
-            });
-        }
-    }
-    const lastAttempt = attempts.at(-1);
-    throw new JsonRpcException(JSON_RPC_ERRORS.internalError, `ClawHub skill ${action} command failed: ${lastAttempt?.error ?? 'unknown error'}`, {
-        action,
-        slug,
-        attempts
-    });
-}
-async function runSkillCommand(command, args, cwd, openclawRoot) {
-    const options = buildOpenClawExecOptions(cwd, openclawRoot);
-    const openclawBin = process.env.OPENCLAW_BIN || '';
-    const clawhubBin = process.env.CLAWHUB_BIN || '';
-    const openclawHome = options.env?.OPENCLAW_HOME || '';
-    const home = options.env?.HOME || '';
-    console.log(`[skills] exec start: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, CLAWHUB_BIN=${clawhubBin}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}`);
-    try {
-        const { stdout, stderr } = await execFileAsync(command, args, options);
-        console.log(`[skills] exec success: command=${command}, args=${JSON.stringify(args)}, stdoutLength=${stdout.length}, stderrLength=${stderr.length}`);
-        return {
-            stdout,
-            stderr,
-            parsed: parseJsonOutput(stdout)
-        };
-    }
-    catch (err) {
-        const stdout = typeof err?.stdout === 'string' ? err.stdout : '';
-        const stderr = typeof err?.stderr === 'string' ? err.stderr : '';
-        console.error(`[skills] exec failed: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, CLAWHUB_BIN=${clawhubBin}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}, stdout=${JSON.stringify(stdout)}, stderr=${JSON.stringify(stderr)}`);
-        throw new JsonRpcException(JSON_RPC_ERRORS.internalError, `OpenClaw skill command failed: ${err instanceof Error ? err.message : String(err)}`, {
-            command,
-            args,
-            stdout,
-            stderr
-        });
-    }
-}
-function parseJsonOutput(stdout) {
-    const trimmed = stdout.trim();
-    if (!trimmed) {
-        return null;
-    }
-    try {
-        return JSON.parse(trimmed);
-    }
-    catch {
-        return null;
-    }
-}
-async function queryOpenClawSkills(context) {
-    const command = process.env.OPENCLAW_BIN || 'openclaw';
-    const options = buildOpenClawExecOptions(context.openclawRoot, context.openclawRoot);
-    try {
-        const { stdout } = await execFileAsync(command, ['skills', 'list', '--json'], options);
-        const parsed = JSON.parse(stdout);
-        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 buildOpenClawExecOptions(cwd, openclawRoot) {
-    const env = { ...process.env };
-    const openclawHome = resolveOpenClawHomeForCli(openclawRoot);
-    if (openclawHome) {
-        env.OPENCLAW_HOME = openclawHome;
-    }
-    if (openclawRoot && path.basename(path.resolve(openclawRoot)) === '.openclaw') {
-        const home = path.dirname(path.resolve(openclawRoot));
-        env.HOME = home;
-        if (process.platform === 'win32') {
-            env.USERPROFILE = home;
-        }
-    }
-    if (process.platform === 'win32') {
-        return {
-            cwd,
-            shell: true,
-            env
-        };
-    }
-    return { cwd, env };
-}
-function resolveOpenClawHomeForCli(openclawRoot) {
-    if (!openclawRoot) {
-        return process.env.OPENCLAW_HOME;
-    }
-    const resolvedRoot = path.resolve(openclawRoot);
-    if (path.basename(resolvedRoot) === '.openclaw') {
-        return path.dirname(resolvedRoot);
-    }
-    return process.env.OPENCLAW_HOME;
-}
-function normalizeCliSkill(skill, skillState) {
-    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, enabledSkills) {
-    const roots = [
-        { scope: 'global', dir: path.join(context.openclawRoot, 'skills') },
-        { scope: 'workspace', dir: path.join(context.openclawRoot, 'workspace', '.openclaw', 'skills') }
-    ];
-    const items = [];
-    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) {
-    const skillJsonPath = path.join(skillDir, 'skill.json');
-    const packageJsonPath = path.join(skillDir, 'package.json');
-    if (await pathExists(skillJsonPath)) {
-        return await readJsonFile(skillJsonPath);
-    }
-    if (await pathExists(packageJsonPath)) {
-        return await readJsonFile(packageJsonPath);
-    }
-    return {};
-}
-async function readInstallMeta(skillDir) {
-    const installMetaPath = path.join(skillDir, '.openclaw-admin-bridge-install.json');
-    if (!(await pathExists(installMetaPath))) {
-        return {};
-    }
-    return await readJsonFile(installMetaPath);
-}
-function mergeSkillSources(officialSkills, customSkills) {
-    const merged = new Map();
-    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);
-    }
-    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) {
-    const configPath = path.join(context.openclawRoot, 'openclaw.json');
-    if (!(await pathExists(configPath))) {
-        return {
-            enabledCustomSkills: new Set(),
-            allowBundled: null,
-            entriesEnabled: new Map()
-        };
-    }
-    const config = await readJsonFile(configPath);
-    const skills = config.agents?.defaults?.skills;
-    const enabledCustomSkills = new Set(Array.isArray(skills)
-        ? skills.filter((item) => typeof item === 'string')
-        : []);
-    const allowBundled = Array.isArray(config.skills?.allowBundled)
-        ? new Set(config.skills?.allowBundled.filter((item) => typeof item === 'string'))
-        : null;
-    const entriesEnabled = new Map();
-    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) {
-    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-function isObject(value) {
-    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
-}
-function pickString(value) {
-    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
-}
-function pickBoolean(value) {
-    return typeof value === 'boolean' ? value : undefined;
-}
-function invertBoolean(value) {
-    return value === undefined ? undefined : !value;
-}
-function resolveBundledEnabled(slug, skill, allowBundled) {
-    if (allowBundled === null) {
-        return (pickBoolean(skill.enabled)
-            ?? pickBoolean(skill.active)
-            ?? invertBoolean(pickBoolean(skill.disabled))
-            ?? true);
-    }
-    return allowBundled.has(slug);
-}
-async function extractTarball(tarballPath, extractRoot) {
-    await execFileAsync('tar', ['-xzf', tarballPath, '-C', extractRoot]);
-}
-async function resolvePackedPackageRoot(extractRoot) {
-    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) {
-    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, packageSpec) {
-    const skillJsonPath = path.join(packageRoot, 'skill.json');
-    let manifest = null;
-    if (await pathExists(skillJsonPath)) {
-        manifest = await readJsonFile(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) {
-    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) {
-    return value
-        .replace(/^@/, '')
-        .replace(/[\\/]/g, '-')
-        .replace(/[^a-zA-Z0-9._-]+/g, '-')
-        .replace(/-+/g, '-')
-        .replace(/^-|-$/g, '')
-        .toLowerCase();
-}
-function buildCustomSkillAliases(slug, displayName, dirName, packageName) {
-    const values = new Set();
-    const add = (value) => {
-        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);
-}
+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.js';
+import { JsonRpcException, JSON_RPC_ERRORS } from '../jsonrpc.js';
+const execFileAsync = promisify(execFile);
+export const listInstalledSkills = async (_params, context) => {
+    const items = await getInstalledSkillsFromCli(context);
+    return {
+        count: items.length,
+        items
+    };
+};
+export const installSkillFromNpm = async (params, context) => {
+    const objectParams = expectObject(params);
+    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 = async (params, context) => {
+    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.openclawRoot, context.openclawRoot);
+    return {
+        ok: true,
+        query,
+        ...result
+    };
+};
+export const installSkillFromClawHub = async (params, context) => {
+    const objectParams = expectObject(params);
+    const slug = expectString(objectParams.slug, 'slug');
+    const result = await runClawHubSkillCommandWithFallback('install', slug, context.openclawRoot, context.openclawRoot);
+    return {
+        ok: true,
+        slug,
+        ...result
+    };
+};
+export const updateSkillFromClawHub = async (params, context) => {
+    const objectParams = expectObject(params);
+    const slug = expectString(objectParams.slug, 'slug');
+    const result = await runClawHubSkillCommandWithFallback('update', slug, context.openclawRoot, context.openclawRoot);
+    return {
+        ok: true,
+        slug,
+        ...result
+    };
+};
+export async function getInstalledSkillsFromCli(context) {
+    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) {
+    if (!value || Array.isArray(value) || typeof value !== 'object') {
+        throw new JsonRpcException(JSON_RPC_ERRORS.invalidParams, 'Params must be an object');
+    }
+    return value;
+}
+function expectString(value, fieldName) {
+    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) {
+    return rawScope === 'workspace' ? 'workspace' : 'global';
+}
+function resolveInstallRoot(openclawRoot, scope) {
+    return scope === 'workspace'
+        ? path.join(openclawRoot, 'workspace', '.openclaw', 'skills')
+        : path.join(openclawRoot, 'skills');
+}
+async function npmPack(packageSpec, cwd) {
+    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;
+}
+export function buildClawHubSkillCommandPlan(action, slug) {
+    const args = action === 'install' && slug === 'proactive-agent'
+        ? [action, slug, '--force']
+        : [action, slug];
+    return [
+        {
+            command: process.env.CLAWHUB_BIN || 'clawhub',
+            args
+        }
+    ];
+}
+async function runOpenClawSkillCommand(args, cwd, openclawRoot) {
+    const command = process.env.OPENCLAW_BIN || 'openclaw';
+    return await runSkillCommand(command, args, cwd, openclawRoot);
+}
+async function runClawHubSkillCommandWithFallback(action, slug, cwd, openclawRoot) {
+    const attempts = [];
+    for (const invocation of buildClawHubSkillCommandPlan(action, slug)) {
+        try {
+            return await runSkillCommand(invocation.command, invocation.args, cwd, openclawRoot);
+        }
+        catch (err) {
+            const data = err instanceof JsonRpcException && isRecord(err.data) ? err.data : {};
+            attempts.push({
+                command: invocation.command,
+                args: invocation.args,
+                stdout: typeof data.stdout === 'string' ? data.stdout : '',
+                stderr: typeof data.stderr === 'string' ? data.stderr : '',
+                error: err instanceof Error ? err.message : String(err)
+            });
+        }
+    }
+    const lastAttempt = attempts.at(-1);
+    throw new JsonRpcException(JSON_RPC_ERRORS.internalError, `ClawHub skill ${action} command failed: ${lastAttempt?.error ?? 'unknown error'}`, {
+        action,
+        slug,
+        attempts
+    });
+}
+async function runSkillCommand(command, args, cwd, openclawRoot) {
+    const options = buildOpenClawExecOptions(cwd, openclawRoot);
+    const openclawBin = process.env.OPENCLAW_BIN || '';
+    const clawhubBin = process.env.CLAWHUB_BIN || '';
+    const openclawHome = options.env?.OPENCLAW_HOME || '';
+    const home = options.env?.HOME || '';
+    console.log(`[skills] exec start: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, CLAWHUB_BIN=${clawhubBin}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}`);
+    try {
+        const { stdout, stderr } = await execFileAsync(command, args, options);
+        console.log(`[skills] exec success: command=${command}, args=${JSON.stringify(args)}, stdoutLength=${stdout.length}, stderrLength=${stderr.length}`);
+        return {
+            stdout,
+            stderr,
+            parsed: parseJsonOutput(stdout)
+        };
+    }
+    catch (err) {
+        const stdout = typeof err?.stdout === 'string' ? err.stdout : '';
+        const stderr = typeof err?.stderr === 'string' ? err.stderr : '';
+        console.error(`[skills] exec failed: command=${command}, args=${JSON.stringify(args)}, cwd=${cwd}, CLAWHUB_BIN=${clawhubBin}, OPENCLAW_BIN=${openclawBin}, OPENCLAW_HOME=${openclawHome}, HOME=${home}, stdout=${JSON.stringify(stdout)}, stderr=${JSON.stringify(stderr)}`);
+        throw new JsonRpcException(JSON_RPC_ERRORS.internalError, `OpenClaw skill command failed: ${err instanceof Error ? err.message : String(err)}`, {
+            command,
+            args,
+            stdout,
+            stderr
+        });
+    }
+}
+function parseJsonOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (!trimmed) {
+        return null;
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+}
+async function queryOpenClawSkills(context) {
+    const command = process.env.OPENCLAW_BIN || 'openclaw';
+    const options = buildOpenClawExecOptions(context.openclawRoot, context.openclawRoot);
+    try {
+        const { stdout } = await execFileAsync(command, ['skills', 'list', '--json'], options);
+        const parsed = JSON.parse(stdout);
+        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 buildOpenClawExecOptions(cwd, openclawRoot) {
+    const env = { ...process.env };
+    const openclawHome = resolveOpenClawHomeForCli(openclawRoot);
+    if (openclawHome) {
+        env.OPENCLAW_HOME = openclawHome;
+    }
+    if (openclawRoot && path.basename(path.resolve(openclawRoot)) === '.openclaw') {
+        const home = path.dirname(path.resolve(openclawRoot));
+        env.HOME = home;
+        if (process.platform === 'win32') {
+            env.USERPROFILE = home;
+        }
+    }
+    if (process.platform === 'win32') {
+        return {
+            cwd,
+            shell: true,
+            env
+        };
+    }
+    return { cwd, env };
+}
+function resolveOpenClawHomeForCli(openclawRoot) {
+    if (!openclawRoot) {
+        return process.env.OPENCLAW_HOME;
+    }
+    const resolvedRoot = path.resolve(openclawRoot);
+    if (path.basename(resolvedRoot) === '.openclaw') {
+        return path.dirname(resolvedRoot);
+    }
+    return process.env.OPENCLAW_HOME;
+}
+function normalizeCliSkill(skill, skillState) {
+    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, enabledSkills) {
+    const roots = [
+        { scope: 'global', dir: path.join(context.openclawRoot, 'skills') },
+        { scope: 'workspace', dir: path.join(context.openclawRoot, 'workspace', '.openclaw', 'skills') }
+    ];
+    const items = [];
+    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) {
+    const skillJsonPath = path.join(skillDir, 'skill.json');
+    const packageJsonPath = path.join(skillDir, 'package.json');
+    if (await pathExists(skillJsonPath)) {
+        return await readJsonFile(skillJsonPath);
+    }
+    if (await pathExists(packageJsonPath)) {
+        return await readJsonFile(packageJsonPath);
+    }
+    return {};
+}
+async function readInstallMeta(skillDir) {
+    const installMetaPath = path.join(skillDir, '.openclaw-admin-bridge-install.json');
+    if (!(await pathExists(installMetaPath))) {
+        return {};
+    }
+    return await readJsonFile(installMetaPath);
+}
+function mergeSkillSources(officialSkills, customSkills) {
+    const merged = new Map();
+    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);
+    }
+    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) {
+    const configPath = path.join(context.openclawRoot, 'openclaw.json');
+    if (!(await pathExists(configPath))) {
+        return {
+            enabledCustomSkills: new Set(),
+            allowBundled: null,
+            entriesEnabled: new Map()
+        };
+    }
+    const config = await readJsonFile(configPath);
+    const skills = config.agents?.defaults?.skills;
+    const enabledCustomSkills = new Set(Array.isArray(skills)
+        ? skills.filter((item) => typeof item === 'string')
+        : []);
+    const allowBundled = Array.isArray(config.skills?.allowBundled)
+        ? new Set(config.skills?.allowBundled.filter((item) => typeof item === 'string'))
+        : null;
+    const entriesEnabled = new Map();
+    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) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function isObject(value) {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+function pickString(value) {
+    return typeof value === 'string' && value.trim().length > 0 ? value.trim() : undefined;
+}
+function pickBoolean(value) {
+    return typeof value === 'boolean' ? value : undefined;
+}
+function invertBoolean(value) {
+    return value === undefined ? undefined : !value;
+}
+function resolveBundledEnabled(slug, skill, allowBundled) {
+    if (allowBundled === null) {
+        return (pickBoolean(skill.enabled)
+            ?? pickBoolean(skill.active)
+            ?? invertBoolean(pickBoolean(skill.disabled))
+            ?? true);
+    }
+    return allowBundled.has(slug);
+}
+async function extractTarball(tarballPath, extractRoot) {
+    await execFileAsync('tar', ['-xzf', tarballPath, '-C', extractRoot]);
+}
+async function resolvePackedPackageRoot(extractRoot) {
+    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) {
+    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, packageSpec) {
+    const skillJsonPath = path.join(packageRoot, 'skill.json');
+    let manifest = null;
+    if (await pathExists(skillJsonPath)) {
+        manifest = await readJsonFile(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) {
+    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) {
+    return value
+        .replace(/^@/, '')
+        .replace(/[\\/]/g, '-')
+        .replace(/[^a-zA-Z0-9._-]+/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^-|-$/g, '')
+        .toLowerCase();
+}
+function buildCustomSkillAliases(slug, displayName, dirName, packageName) {
+    const values = new Set();
+    const add = (value) => {
+        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);
+}