@js-eyes/protocol 2.4.0

package/index.js

@@ -0,0 +1,267 @@
+'use strict';
+
+const pkg = require('./package.json');
+
+const DEFAULT_SERVER_HOST = 'localhost';
+const DEFAULT_SERVER_PORT = 18080;
+const DEFAULT_REQUEST_TIMEOUT_SECONDS = 1800;
+const REQUEST_TIMEOUT_MS = DEFAULT_REQUEST_TIMEOUT_SECONDS * 1000;
+const PROTOCOL_VERSION = '1.0';
+const PACKAGE_VERSION = pkg.version;
+const SKILLS_REGISTRY_URL = 'https://js-eyes.com/skills.json';
+const RELEASE_BASE_URL = 'https://github.com/imjszhang/js-eyes/releases/download';
+
+const FORWARDABLE_ACTIONS = [
+  'open_url',
+  'close_tab',
+  'get_html',
+  'execute_script',
+  'inject_css',
+  'get_cookies',
+  'get_cookies_by_domain',
+  'get_page_info',
+  'upload_file_to_tab',
+];
+
+const SENSITIVE_TOOL_NAMES = Object.freeze([
+  'js_eyes_execute_script',
+  'js_eyes_get_cookies',
+  'js_eyes_get_cookies_by_domain',
+  'js_eyes_inject_css',
+  'js_eyes_upload_file',
+  'js_eyes_upload_file_to_tab',
+  'js_eyes_install_skill',
+]);
+
+const LOOPBACK_HOSTS = Object.freeze(['localhost', '127.0.0.1', '::1', '::ffff:127.0.0.1', '0:0:0:0:0:0:0:1']);
+
+const DEFAULT_ALLOWED_ORIGINS = Object.freeze([
+  'chrome-extension://*',
+  'moz-extension://*',
+  'http://localhost',
+  'https://localhost',
+  'http://127.0.0.1',
+  'https://127.0.0.1',
+  'http://[::1]',
+  'https://[::1]',
+]);
+
+const DEFAULT_TASK_ORIGIN_CONFIG = Object.freeze({
+  enabled: true,
+  sources: ['user-message', 'skill-platforms', 'active-tab', 'fetched-links'],
+});
+
+const DEFAULT_TAINT_CONFIG = Object.freeze({
+  enabled: true,
+  mode: 'canary+substring',
+  minValueLength: 6,
+});
+
+const DEFAULT_PROFILE_CONFIG = Object.freeze({
+  default: 'full',
+});
+
+const POLICY_ENFORCEMENT_LEVELS = Object.freeze(['off', 'soft', 'strict']);
+
+const DEFAULT_SECURITY_CONFIG = Object.freeze({
+  allowAnonymous: false,
+  allowedOrigins: DEFAULT_ALLOWED_ORIGINS.slice(),
+  allowRemoteBind: false,
+  allowRawEval: false,
+  requireLockfile: true,
+  enforcement: 'soft',
+  taskOrigin: { ...DEFAULT_TASK_ORIGIN_CONFIG, sources: DEFAULT_TASK_ORIGIN_CONFIG.sources.slice() },
+  egressAllowlist: [],
+  taint: { ...DEFAULT_TAINT_CONFIG },
+  profile: { ...DEFAULT_PROFILE_CONFIG },
+  toolPolicies: {
+    js_eyes_execute_script: 'confirm',
+    js_eyes_get_cookies: 'confirm',
+    js_eyes_get_cookies_by_domain: 'confirm',
+    js_eyes_inject_css: 'confirm',
+    js_eyes_upload_file: 'confirm',
+    js_eyes_upload_file_to_tab: 'confirm',
+    js_eyes_install_skill: 'confirm',
+  },
+  sensitiveCookieDomains: [
+    'bank',
+    'paypal.com',
+    'google.com',
+    'live.com',
+    'apple.com',
+    'icloud.com',
+    'aws.amazon.com',
+    'amazon.com',
+    'office.com',
+    'microsoft.com',
+    'github.com',
+  ],
+});
+
+const WS_CLOSE_CODE_AUTH_REQUIRED = 4401;
+const WS_CLOSE_CODE_FORBIDDEN_ORIGIN = 4403;
+
+const COMPATIBILITY_MATRIX = Object.freeze({
+  protocolVersion: PROTOCOL_VERSION,
+  cliVersion: PACKAGE_VERSION,
+  extensionVersion: PACKAGE_VERSION,
+  serverCoreVersion: PACKAGE_VERSION,
+  clientSdkVersion: PACKAGE_VERSION,
+  openclawPluginVersion: PACKAGE_VERSION,
+  skillClientSdkVersion: PACKAGE_VERSION,
+});
+
+function isLoopbackHost(host) {
+  if (!host) return false;
+  const normalized = String(host).toLowerCase();
+  if (LOOPBACK_HOSTS.includes(normalized)) return true;
+  if (normalized.startsWith('127.')) return true;
+  if (normalized === '::ffff:127.0.0.1') return true;
+  return false;
+}
+
+function normalizeOriginPattern(pattern) {
+  if (!pattern) return null;
+  const trimmed = String(pattern).trim().toLowerCase();
+  if (!trimmed) return null;
+  return trimmed.replace(/\/$/, '');
+}
+
+function matchesOriginPattern(origin, pattern) {
+  if (!origin || !pattern) return false;
+  const normOrigin = String(origin).trim().toLowerCase().replace(/\/$/, '');
+  const normPattern = normalizeOriginPattern(pattern);
+  if (!normPattern) return false;
+  if (normPattern === '*') return true;
+  if (normPattern.endsWith('://*')) {
+    const scheme = normPattern.slice(0, -3);
+    return normOrigin.startsWith(scheme);
+  }
+  if (normPattern.includes('*')) {
+    const regex = new RegExp(
+      '^' + normPattern.split('*').map(escapeRegex).join('.*') + '$',
+    );
+    return regex.test(normOrigin);
+  }
+  if (normOrigin === normPattern) return true;
+  if (normOrigin.startsWith(normPattern + ':')) return true;
+  if (normOrigin.startsWith(normPattern + '/')) return true;
+  return false;
+}
+
+function escapeRegex(text) {
+  return text.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+
+function isOriginAllowed(origin, allowedOrigins) {
+  if (!Array.isArray(allowedOrigins)) return false;
+  for (const pattern of allowedOrigins) {
+    if (matchesOriginPattern(origin, pattern)) return true;
+  }
+  return false;
+}
+
+function resolveSecurityConfig(config = {}) {
+  const raw = (config && config.security && typeof config.security === 'object')
+    ? config.security
+    : {};
+  const merged = {
+    ...DEFAULT_SECURITY_CONFIG,
+    ...raw,
+    allowedOrigins: Array.isArray(raw.allowedOrigins) && raw.allowedOrigins.length
+      ? Array.from(new Set([
+        ...DEFAULT_SECURITY_CONFIG.allowedOrigins,
+        ...raw.allowedOrigins,
+      ]))
+      : DEFAULT_SECURITY_CONFIG.allowedOrigins.slice(),
+    toolPolicies: {
+      ...DEFAULT_SECURITY_CONFIG.toolPolicies,
+      ...(raw.toolPolicies || {}),
+    },
+    sensitiveCookieDomains: Array.isArray(raw.sensitiveCookieDomains)
+      ? raw.sensitiveCookieDomains.slice()
+      : DEFAULT_SECURITY_CONFIG.sensitiveCookieDomains.slice(),
+    enforcement: POLICY_ENFORCEMENT_LEVELS.includes(raw.enforcement)
+      ? raw.enforcement
+      : DEFAULT_SECURITY_CONFIG.enforcement,
+    taskOrigin: mergeTaskOriginConfig(raw.taskOrigin),
+    egressAllowlist: Array.isArray(raw.egressAllowlist)
+      ? raw.egressAllowlist.slice()
+      : DEFAULT_SECURITY_CONFIG.egressAllowlist.slice(),
+    taint: mergeTaintConfig(raw.taint),
+    profile: mergeProfileConfig(raw.profile),
+  };
+  if (process.env.JS_EYES_INSECURE === '1') {
+    merged.allowAnonymous = true;
+  }
+  if (process.env.JS_EYES_ALLOW_REMOTE_BIND === '1') {
+    merged.allowRemoteBind = true;
+  }
+  if (process.env.JS_EYES_POLICY_ENFORCEMENT && POLICY_ENFORCEMENT_LEVELS.includes(process.env.JS_EYES_POLICY_ENFORCEMENT)) {
+    merged.enforcement = process.env.JS_EYES_POLICY_ENFORCEMENT;
+  }
+  return merged;
+}
+
+function mergeTaskOriginConfig(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return { ...DEFAULT_TASK_ORIGIN_CONFIG, sources: DEFAULT_TASK_ORIGIN_CONFIG.sources.slice() };
+  }
+  return {
+    enabled: typeof raw.enabled === 'boolean' ? raw.enabled : DEFAULT_TASK_ORIGIN_CONFIG.enabled,
+    sources: Array.isArray(raw.sources) && raw.sources.length
+      ? raw.sources.slice()
+      : DEFAULT_TASK_ORIGIN_CONFIG.sources.slice(),
+  };
+}
+
+function mergeTaintConfig(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return { ...DEFAULT_TAINT_CONFIG };
+  }
+  return {
+    enabled: typeof raw.enabled === 'boolean' ? raw.enabled : DEFAULT_TAINT_CONFIG.enabled,
+    mode: typeof raw.mode === 'string' && raw.mode ? raw.mode : DEFAULT_TAINT_CONFIG.mode,
+    minValueLength: Number.isFinite(raw.minValueLength) && raw.minValueLength > 0
+      ? Math.floor(raw.minValueLength)
+      : DEFAULT_TAINT_CONFIG.minValueLength,
+  };
+}
+
+function mergeProfileConfig(raw) {
+  if (!raw || typeof raw !== 'object') {
+    return { ...DEFAULT_PROFILE_CONFIG };
+  }
+  return {
+    default: typeof raw.default === 'string' && raw.default
+      ? raw.default
+      : DEFAULT_PROFILE_CONFIG.default,
+  };
+}
+
+module.exports = {
+  DEFAULT_ALLOWED_ORIGINS,
+  DEFAULT_SECURITY_CONFIG,
+  DEFAULT_TASK_ORIGIN_CONFIG,
+  DEFAULT_TAINT_CONFIG,
+  DEFAULT_PROFILE_CONFIG,
+  POLICY_ENFORCEMENT_LEVELS,
+  DEFAULT_SERVER_HOST,
+  DEFAULT_SERVER_PORT,
+  DEFAULT_REQUEST_TIMEOUT_SECONDS,
+  LOOPBACK_HOSTS,
+  REQUEST_TIMEOUT_MS,
+  PROTOCOL_VERSION,
+  PACKAGE_VERSION,
+  SKILLS_REGISTRY_URL,
+  RELEASE_BASE_URL,
+  FORWARDABLE_ACTIONS,
+  SENSITIVE_TOOL_NAMES,
+  COMPATIBILITY_MATRIX,
+  WS_CLOSE_CODE_AUTH_REQUIRED,
+  WS_CLOSE_CODE_FORBIDDEN_ORIGIN,
+  isLoopbackHost,
+  isOriginAllowed,
+  matchesOriginPattern,
+  resolveSecurityConfig,
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@js-eyes/protocol",
+  "version": "2.4.0",
+  "description": "Shared protocol constants for JS Eyes runtime packages",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "skills.js",
+    "zip-extract.js"
+  ],
+  "license": "MIT",
+  "author": "imjszhang <ortle3x3@gmail.com>",
+  "homepage": "https://js-eyes.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/imjszhang/JS-Eyes.git",
+    "directory": "packages/protocol"
+  },
+  "bugs": {
+    "url": "https://github.com/imjszhang/JS-Eyes/issues"
+  },
+  "keywords": [
+    "js-eyes",
+    "protocol",
+    "browser-automation",
+    "openclaw"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills.js

@@ -0,0 +1,581 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { extractZipBuffer } = require('./zip-extract');
+
+const SKILL_CONTRACT_FILE = 'skill.contract.js';
+const INTEGRITY_FILE = '.integrity.json';
+const INSTALL_MANIFEST_FILE = 'skills-install.json';
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function readJson(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+}
+
+function loadSkillContract(skillDir) {
+  const contractPath = path.resolve(skillDir, SKILL_CONTRACT_FILE);
+  if (!fs.existsSync(contractPath)) return null;
+  delete require.cache[require.resolve(contractPath)];
+  return require(contractPath);
+}
+
+function hasSkillContract(skillDir) {
+  return fs.existsSync(path.join(skillDir, SKILL_CONTRACT_FILE));
+}
+
+function resolveSkillsDir(paths, config = {}) {
+  if (config.skillsDir) {
+    return path.resolve(config.skillsDir);
+  }
+  if (paths && paths.skillsDir) {
+    return paths.skillsDir;
+  }
+  if (paths && paths.baseDir) {
+    return path.join(paths.baseDir, 'skills');
+  }
+  return path.resolve('skills');
+}
+
+function getOpenClawConfigPath(options = {}) {
+  const env = options.env || process.env;
+  const home = options.home || os.homedir();
+
+  if (env.OPENCLAW_CONFIG_PATH) {
+    return path.resolve(env.OPENCLAW_CONFIG_PATH);
+  }
+  if (env.OPENCLAW_STATE_DIR) {
+    return path.resolve(env.OPENCLAW_STATE_DIR, 'openclaw.json');
+  }
+  if (env.OPENCLAW_HOME) {
+    return path.resolve(env.OPENCLAW_HOME, '.openclaw', 'openclaw.json');
+  }
+  return path.join(home, '.openclaw', 'openclaw.json');
+}
+
+function normalizeSkillMetadata(skillDir) {
+  const contract = loadSkillContract(skillDir);
+  const pkg = readJson(path.join(skillDir, 'package.json')) || {};
+  const cli = contract && contract.cli ? contract.cli : {};
+  const openclaw = contract && contract.openclaw ? contract.openclaw : {};
+  const tools = Array.isArray(openclaw.tools)
+    ? openclaw.tools.map((tool) => tool.name)
+    : [];
+  const commands = Array.isArray(cli.commands)
+    ? cli.commands.map((command) => command.name)
+    : [];
+
+  return {
+    id: contract?.id || pkg.name || path.basename(skillDir),
+    name: contract?.name || pkg.name || path.basename(skillDir),
+    version: contract?.version || pkg.version || '1.0.0',
+    description: contract?.description || pkg.description || '',
+    skillDir,
+    cliEntry: cli.entry ? path.resolve(skillDir, cli.entry) : path.join(skillDir, 'index.js'),
+    commands,
+    tools,
+    runtime: contract?.runtime || {},
+    contract,
+  };
+}
+
+function discoverLocalSkills(skillsDir) {
+  if (!fs.existsSync(skillsDir)) return [];
+  const entries = fs.readdirSync(skillsDir, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => path.join(skillsDir, entry.name))
+    .filter((skillDir) => hasSkillContract(skillDir))
+    .map((skillDir) => normalizeSkillMetadata(skillDir))
+    .filter((skill) => skill && skill.id);
+}
+
+function readSkillById(skillsDir, skillId) {
+  const skillDir = path.join(skillsDir, skillId);
+  if (!fs.existsSync(skillDir) || !hasSkillContract(skillDir)) return null;
+  return normalizeSkillMetadata(skillDir);
+}
+
+async function fetchSkillsRegistry(registryUrl) {
+  const response = await fetch(registryUrl, {
+    headers: { Accept: 'application/json' },
+  });
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+  return response.json();
+}
+
+function resolveOpenClawPluginEntry(definition) {
+  try {
+    const sdk = require('openclaw/plugin-sdk/plugin-entry');
+    if (typeof sdk.definePluginEntry === 'function') {
+      return sdk.definePluginEntry(definition);
+    }
+  } catch {
+    // Fallback for local development without the OpenClaw SDK package installed.
+  }
+  return definition.register;
+}
+
+function getSkillsState(config = {}) {
+  const state = config && typeof config === 'object' ? config.skillsEnabled : null;
+  if (!state || typeof state !== 'object' || Array.isArray(state)) {
+    return {};
+  }
+  return state;
+}
+
+function getLegacyOpenClawSkillState(options = {}) {
+  const {
+    openclawConfigPath = getOpenClawConfigPath(options),
+    skillIds = null,
+  } = options;
+
+  if (!fs.existsSync(openclawConfigPath)) {
+    return {};
+  }
+
+  let config = null;
+  try {
+    config = JSON.parse(fs.readFileSync(openclawConfigPath, 'utf8'));
+  } catch {
+    return {};
+  }
+
+  const entries = config?.plugins?.entries;
+  if (!entries || typeof entries !== 'object') {
+    return {};
+  }
+
+  const allowedSkillIds = Array.isArray(skillIds) && skillIds.length > 0
+    ? new Set(skillIds)
+    : null;
+  const state = {};
+
+  for (const [skillId, entry] of Object.entries(entries)) {
+    if (skillId === 'js-eyes') {
+      continue;
+    }
+    if (allowedSkillIds && !allowedSkillIds.has(skillId)) {
+      continue;
+    }
+    if (!entry || typeof entry !== 'object' || entry.enabled === undefined) {
+      continue;
+    }
+    state[skillId] = entry.enabled !== false;
+  }
+
+  return state;
+}
+
+function isSkillEnabled(config = {}, skillId, legacyState = {}) {
+  const state = getSkillsState(config);
+  if (Object.prototype.hasOwnProperty.call(state, skillId)) {
+    return state[skillId] !== false;
+  }
+  if (legacyState && Object.prototype.hasOwnProperty.call(legacyState, skillId)) {
+    return legacyState[skillId] !== false;
+  }
+  return false;
+}
+
+function registerOpenClawTools(api, adapter, options = {}) {
+  const logger = options.logger || api.logger || console;
+  const registeredNames = options.registeredNames || null;
+  const sourceName = options.sourceName || adapter?.id || 'js-eyes-skill';
+  const declaredTools = Array.isArray(options.declaredTools) && options.declaredTools.length > 0
+    ? new Set(options.declaredTools)
+    : null;
+  const wrapTool = typeof options.wrapTool === 'function' ? options.wrapTool : null;
+  const summary = {
+    registered: [],
+    skipped: [],
+    failed: [],
+  };
+
+  for (const tool of adapter.tools || []) {
+    if (!tool || !tool.name) {
+      summary.skipped.push({ name: '(anonymous)', reason: 'missing-name' });
+      logger.warn(`[js-eyes] Skipping tool with missing name from ${sourceName}`);
+      continue;
+    }
+    if (declaredTools && !declaredTools.has(tool.name)) {
+      summary.skipped.push({ name: tool.name, reason: 'undeclared' });
+      logger.warn(`[js-eyes] Skipping undeclared tool "${tool.name}" from ${sourceName}`);
+      continue;
+    }
+    if (registeredNames && registeredNames.has(tool.name)) {
+      summary.skipped.push({ name: tool.name, reason: 'duplicate-name' });
+      logger.warn(`[js-eyes] Skipping duplicate tool "${tool.name}" from ${sourceName}`);
+      continue;
+    }
+
+    try {
+      const definition = {
+        name: tool.name,
+        label: tool.label,
+        description: tool.description,
+        parameters: tool.parameters,
+        execute: tool.execute,
+      };
+      const wrapped = wrapTool ? wrapTool(definition, { source: sourceName }) : definition;
+      api.registerTool(wrapped, tool.optional ? { optional: true } : undefined);
+      if (registeredNames) {
+        registeredNames.add(tool.name);
+      }
+      summary.registered.push(tool.name);
+    } catch (error) {
+      summary.failed.push({ name: tool.name, reason: error.message });
+      logger.warn(`[js-eyes] Failed to register tool "${tool.name}" from ${sourceName}: ${error.message}`);
+    }
+  }
+
+  return summary;
+}
+
+function sha256(buffer) {
+  return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+
+function isMainRefUrl(url) {
+  if (typeof url !== 'string') return false;
+  return /\/(refs\/heads\/)?main(?=[/?])/.test(url);
+}
+
+async function downloadBuffer(urls, logger = console) {
+  let lastError = null;
+  for (const url of urls) {
+    try {
+      const response = await fetch(url);
+      if (response.ok) {
+        const buf = Buffer.from(await response.arrayBuffer());
+        return { buffer: buf, url };
+      }
+      lastError = new Error(`HTTP ${response.status} (${url})`);
+    } catch (error) {
+      lastError = error;
+    }
+    if (logger && typeof logger.warn === 'function') {
+      logger.warn(`[js-eyes] Download failed (${url}): ${lastError?.message || 'unknown'}`);
+    }
+  }
+  throw lastError || new Error('Download failed for all URLs');
+}
+
+function detectPackageManager(targetDir) {
+  if (fs.existsSync(path.join(targetDir, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (fs.existsSync(path.join(targetDir, 'yarn.lock'))) return 'yarn';
+  if (fs.existsSync(path.join(targetDir, 'package-lock.json'))) return 'npm';
+  return null;
+}
+
+function installSkillDependencies(targetDir, options = {}) {
+  const pkgJson = path.join(targetDir, 'package.json');
+  if (!fs.existsSync(pkgJson)) return { ran: false, manager: null };
+
+  const requireLockfile = options.requireLockfile !== false;
+  const manager = detectPackageManager(targetDir);
+
+  if (requireLockfile && manager !== 'npm') {
+    throw new Error('安装拒绝执行：缺少 package-lock.json（开启 security.requireLockfile=false 可放宽）');
+  }
+
+  const ignoreScripts = options.allowPostinstall ? [] : ['--ignore-scripts'];
+  const command = manager === 'npm' ? 'ci' : 'install';
+  const args = [command, ...ignoreScripts, '--no-audit', '--no-fund'];
+
+  const result = spawnSync('npm', args, {
+    cwd: targetDir,
+    stdio: options.stdio || 'pipe',
+    windowsHide: true,
+    env: { ...process.env, npm_config_ignore_scripts: options.allowPostinstall ? 'false' : 'true' },
+  });
+
+  if (result.status !== 0) {
+    const stderr = result.stderr ? String(result.stderr) : '';
+    throw new Error(`npm ${args.join(' ')} 失败 (status=${result.status}): ${stderr.slice(0, 500)}`);
+  }
+
+  return { ran: true, manager: manager || 'npm', allowPostinstall: Boolean(options.allowPostinstall) };
+}
+
+function listFilesRecursive(dir) {
+  const out = [];
+  function walk(current) {
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const full = path.join(current, entry.name);
+      const rel = path.relative(dir, full);
+      if (rel === INTEGRITY_FILE || rel === INSTALL_MANIFEST_FILE) continue;
+      if (rel.split(path.sep)[0] === 'node_modules') continue;
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (entry.isFile()) {
+        out.push(rel.split(path.sep).join('/'));
+      }
+    }
+  }
+  walk(dir);
+  return out.sort();
+}
+
+function writeIntegrityManifest(targetDir, payload = {}) {
+  const files = {};
+  for (const rel of listFilesRecursive(targetDir)) {
+    const full = path.join(targetDir, rel);
+    files[rel] = sha256(fs.readFileSync(full));
+  }
+  const manifest = {
+    version: 1,
+    createdAt: new Date().toISOString(),
+    skillId: payload.skillId || null,
+    sourceUrl: payload.sourceUrl || null,
+    bundleSha256: payload.bundleSha256 || null,
+    declaredTools: payload.declaredTools || [],
+    files,
+  };
+  const filePath = path.join(targetDir, INTEGRITY_FILE);
+  fs.writeFileSync(filePath, JSON.stringify(manifest, null, 2) + '\n');
+  try { fs.chmodSync(filePath, 0o600); } catch {}
+  return manifest;
+}
+
+function readSkillIntegrity(skillDir) {
+  const filePath = path.join(skillDir, INTEGRITY_FILE);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function verifySkillIntegrity(skillDir) {
+  const manifest = readSkillIntegrity(skillDir);
+  if (!manifest || !manifest.files) {
+    return { hasIntegrity: false, ok: false, mismatches: [], missing: [], extra: [], checked: 0 };
+  }
+  const expected = manifest.files;
+  const expectedKeys = Object.keys(expected);
+  const present = new Set(listFilesRecursive(skillDir));
+
+  const mismatches = [];
+  const missing = [];
+
+  for (const rel of expectedKeys) {
+    const full = path.join(skillDir, rel);
+    if (!fs.existsSync(full)) {
+      missing.push(rel);
+      continue;
+    }
+    const actual = sha256(fs.readFileSync(full));
+    if (actual !== expected[rel]) {
+      mismatches.push(rel);
+    }
+  }
+
+  const extra = [...present].filter((rel) => !Object.prototype.hasOwnProperty.call(expected, rel));
+
+  return {
+    hasIntegrity: true,
+    ok: mismatches.length === 0 && missing.length === 0,
+    mismatches,
+    missing,
+    extra,
+    checked: expectedKeys.length,
+  };
+}
+
+async function planSkillInstall(options) {
+  const {
+    skillId,
+    registryUrl,
+    skillsDir,
+    stagingDir = path.join(os.tmpdir(), `js-eyes-skill-staging-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`),
+    force = false,
+    logger = console,
+  } = options;
+
+  ensureDir(skillsDir);
+  const registry = await fetchSkillsRegistry(registryUrl);
+  const skill = registry.skills?.find((entry) => entry.id === skillId);
+  if (!skill) {
+    const ids = (registry.skills || []).map((entry) => entry.id).join(', ');
+    throw new Error(`技能 "${skillId}" 未在注册表中找到。可用技能: ${ids || '无'}`);
+  }
+
+  const targetDir = path.join(skillsDir, skillId);
+  if (fs.existsSync(targetDir) && !force) {
+    throw new Error(`技能 "${skillId}" 已安装在 ${targetDir}（使用 force=true 覆盖）`);
+  }
+
+  if (!skill.sha256 || typeof skill.sha256 !== 'string') {
+    throw new Error(`技能 "${skillId}" 注册表条目缺少 sha256 校验和，拒绝下载`);
+  }
+
+  const candidateUrls = [skill.downloadUrl];
+  if (skill.downloadUrlFallback) {
+    if (isMainRefUrl(skill.downloadUrlFallback)) {
+      logger?.warn?.(`[js-eyes] Ignoring @main fallback URL for ${skillId} (use a tagged URL)`);
+    } else {
+      candidateUrls.push(skill.downloadUrlFallback);
+    }
+  }
+
+  const { buffer, url } = await downloadBuffer(candidateUrls.filter(Boolean), logger);
+  const digest = sha256(buffer);
+  if (digest !== skill.sha256.toLowerCase()) {
+    throw new Error(`技能 "${skillId}" 哈希不符: expected ${skill.sha256}, got ${digest}`);
+  }
+  if (typeof skill.size === 'number' && buffer.length !== skill.size) {
+    throw new Error(`技能 "${skillId}" 大小不符: expected ${skill.size}, got ${buffer.length}`);
+  }
+
+  ensureDir(stagingDir);
+  if (fs.existsSync(stagingDir) && fs.readdirSync(stagingDir).length > 0) {
+    fs.rmSync(stagingDir, { recursive: true, force: true });
+    ensureDir(stagingDir);
+  }
+  extractZipBuffer(buffer, stagingDir);
+
+  const stagedFiles = listFilesRecursive(stagingDir);
+  const declaredTools = Array.isArray(skill.tools) ? skill.tools.slice() : [];
+
+  return {
+    plan: {
+      skillId,
+      registryUrl,
+      sourceUrl: url,
+      bundleSha256: digest,
+      bundleSize: buffer.length,
+      targetDir,
+      stagingDir,
+      declaredTools,
+      stagedFiles,
+      registryEntry: skill,
+      hasLockfile: fs.existsSync(path.join(stagingDir, 'package-lock.json')),
+      hasPackageJson: fs.existsSync(path.join(stagingDir, 'package.json')),
+    },
+    skill,
+    registry,
+  };
+}
+
+function cleanupStaging(stagingDir) {
+  if (stagingDir && fs.existsSync(stagingDir)) {
+    fs.rmSync(stagingDir, { recursive: true, force: true });
+  }
+}
+
+function applySkillInstall(plan, options = {}) {
+  if (!plan || !plan.stagingDir || !plan.targetDir) {
+    throw new Error('applySkillInstall: invalid plan');
+  }
+  const requireLockfile = options.requireLockfile !== false;
+  if (plan.hasPackageJson && requireLockfile && !plan.hasLockfile) {
+    cleanupStaging(plan.stagingDir);
+    throw new Error('技能包缺少 package-lock.json，拒绝安装（设置 security.requireLockfile=false 可放宽）');
+  }
+
+  installSkillDependencies(plan.stagingDir, {
+    requireLockfile,
+    allowPostinstall: Boolean(options.allowPostinstall),
+  });
+
+  if (fs.existsSync(plan.targetDir)) {
+    fs.rmSync(plan.targetDir, { recursive: true, force: true });
+  }
+  ensureDir(path.dirname(plan.targetDir));
+  fs.renameSync(plan.stagingDir, plan.targetDir);
+
+  const integrity = writeIntegrityManifest(plan.targetDir, {
+    skillId: plan.skillId,
+    sourceUrl: plan.sourceUrl,
+    bundleSha256: plan.bundleSha256,
+    declaredTools: plan.declaredTools,
+  });
+
+  const installManifest = {
+    skillId: plan.skillId,
+    sourceUrl: plan.sourceUrl,
+    bundleSha256: plan.bundleSha256,
+    bundleSize: plan.bundleSize,
+    installedAt: integrity.createdAt,
+    declaredTools: plan.declaredTools,
+  };
+  const installManifestPath = path.join(plan.targetDir, INSTALL_MANIFEST_FILE);
+  fs.writeFileSync(installManifestPath, JSON.stringify(installManifest, null, 2) + '\n');
+  try { fs.chmodSync(installManifestPath, 0o600); } catch {}
+
+  return {
+    targetDir: plan.targetDir,
+    integrity,
+    installManifest,
+  };
+}
+
+async function installSkillFromRegistry(options) {
+  const { plan, skill, registry } = await planSkillInstall(options);
+  const apply = applySkillInstall(plan, {
+    requireLockfile: options.requireLockfile,
+    allowPostinstall: options.allowPostinstall,
+  });
+  return {
+    registry,
+    skill,
+    targetDir: apply.targetDir,
+    integrity: apply.integrity,
+    installManifest: apply.installManifest,
+    plan,
+  };
+}
+
+function runSkillCli(options) {
+  const { skillDir, argv = [], stdio = 'inherit', env = process.env } = options;
+  const skill = normalizeSkillMetadata(skillDir);
+  if (!fs.existsSync(skill.cliEntry)) {
+    throw new Error(`技能 ${skill.id} 缺少 CLI 入口: ${skill.cliEntry}`);
+  }
+
+  return spawnSync(process.execPath, [skill.cliEntry, ...argv], {
+    cwd: skillDir,
+    env: { ...env, JS_EYES_SKILL_DIR: skillDir },
+    stdio,
+    encoding: stdio === 'pipe' ? 'utf8' : undefined,
+  });
+}
+
+module.exports = {
+  INSTALL_MANIFEST_FILE,
+  INTEGRITY_FILE,
+  SKILL_CONTRACT_FILE,
+  applySkillInstall,
+  cleanupStaging,
+  discoverLocalSkills,
+  fetchSkillsRegistry,
+  getLegacyOpenClawSkillState,
+  getOpenClawConfigPath,
+  getSkillsState,
+  installSkillFromRegistry,
+  isSkillEnabled,
+  loadSkillContract,
+  normalizeSkillMetadata,
+  planSkillInstall,
+  readSkillById,
+  readSkillIntegrity,
+  registerOpenClawTools,
+  resolveSkillsDir,
+  resolveOpenClawPluginEntry,
+  runSkillCli,
+  verifySkillIntegrity,
+  writeIntegrityManifest,
+};

package/zip-extract.js

@@ -0,0 +1,208 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+
+const EOCD_SIGNATURE = 0x06054b50;
+const ZIP64_EOCD_LOCATOR = 0x07064b50;
+const ZIP64_EOCD = 0x06064b50;
+const CENTRAL_DIR_HEADER = 0x02014b50;
+const LOCAL_HEADER = 0x04034b50;
+
+const DEFAULT_MAX_TOTAL_SIZE = 100 * 1024 * 1024;
+const DEFAULT_MAX_FILE_SIZE = 20 * 1024 * 1024;
+const DEFAULT_MAX_ENTRIES = 5000;
+
+function readUInt16(buf, off) { return buf.readUInt16LE(off); }
+function readUInt32(buf, off) { return buf.readUInt32LE(off); }
+
+function findEndOfCentralDirectory(buf) {
+  const minLen = 22;
+  if (buf.length < minLen) {
+    throw new Error('zip: file too small');
+  }
+  const maxBack = Math.min(buf.length, 65536 + minLen);
+  for (let i = buf.length - minLen; i >= buf.length - maxBack; i--) {
+    if (i < 0) break;
+    if (readUInt32(buf, i) === EOCD_SIGNATURE) {
+      return i;
+    }
+  }
+  throw new Error('zip: end-of-central-directory not found');
+}
+
+function parseEntries(buf) {
+  const eocdOffset = findEndOfCentralDirectory(buf);
+  let cdSize = readUInt32(buf, eocdOffset + 12);
+  let cdOffset = readUInt32(buf, eocdOffset + 16);
+  let entryCount = readUInt16(buf, eocdOffset + 10);
+
+  if (cdOffset === 0xffffffff || cdSize === 0xffffffff || entryCount === 0xffff) {
+    const locatorOffset = eocdOffset - 20;
+    if (locatorOffset >= 0 && readUInt32(buf, locatorOffset) === ZIP64_EOCD_LOCATOR) {
+      const zip64Offset = Number(buf.readBigUInt64LE(locatorOffset + 8));
+      if (zip64Offset >= 0 && readUInt32(buf, zip64Offset) === ZIP64_EOCD) {
+        entryCount = Number(buf.readBigUInt64LE(zip64Offset + 32));
+        cdSize = Number(buf.readBigUInt64LE(zip64Offset + 40));
+        cdOffset = Number(buf.readBigUInt64LE(zip64Offset + 48));
+      }
+    }
+  }
+
+  const entries = [];
+  let offset = cdOffset;
+
+  for (let i = 0; i < entryCount; i++) {
+    if (readUInt32(buf, offset) !== CENTRAL_DIR_HEADER) {
+      throw new Error(`zip: bad central directory at entry ${i}`);
+    }
+    const versionMadeBy = readUInt16(buf, offset + 4);
+    const generalFlag = readUInt16(buf, offset + 8);
+    const method = readUInt16(buf, offset + 10);
+    let compressedSize = readUInt32(buf, offset + 20);
+    let uncompressedSize = readUInt32(buf, offset + 24);
+    const fileNameLength = readUInt16(buf, offset + 28);
+    const extraLength = readUInt16(buf, offset + 30);
+    const commentLength = readUInt16(buf, offset + 32);
+    const externalAttrs = readUInt32(buf, offset + 38);
+    let localHeaderOffset = readUInt32(buf, offset + 42);
+    const fileName = buf.slice(offset + 46, offset + 46 + fileNameLength).toString('utf8');
+
+    let extraOffset = offset + 46 + fileNameLength;
+    const extraEnd = extraOffset + extraLength;
+    while (extraOffset + 4 <= extraEnd) {
+      const id = readUInt16(buf, extraOffset);
+      const size = readUInt16(buf, extraOffset + 2);
+      if (id === 0x0001) {
+        let p = extraOffset + 4;
+        if (uncompressedSize === 0xffffffff && p + 8 <= extraEnd) {
+          uncompressedSize = Number(buf.readBigUInt64LE(p)); p += 8;
+        }
+        if (compressedSize === 0xffffffff && p + 8 <= extraEnd) {
+          compressedSize = Number(buf.readBigUInt64LE(p)); p += 8;
+        }
+        if (localHeaderOffset === 0xffffffff && p + 8 <= extraEnd) {
+          localHeaderOffset = Number(buf.readBigUInt64LE(p)); p += 8;
+        }
+      }
+      extraOffset += 4 + size;
+    }
+
+    const isUnix = (versionMadeBy >>> 8) === 3;
+    const unixMode = isUnix ? (externalAttrs >>> 16) & 0xffff : 0;
+    const isSymlink = isUnix && (unixMode & 0xf000) === 0xa000;
+
+    entries.push({
+      fileName,
+      method,
+      compressedSize,
+      uncompressedSize,
+      localHeaderOffset,
+      generalFlag,
+      isSymlink,
+      isDirectory: fileName.endsWith('/') || (isUnix && (unixMode & 0xf000) === 0x4000),
+      unixMode,
+    });
+
+    offset += 46 + fileNameLength + extraLength + commentLength;
+  }
+
+  return entries;
+}
+
+function readEntryData(buf, entry) {
+  const lhOffset = entry.localHeaderOffset;
+  if (readUInt32(buf, lhOffset) !== LOCAL_HEADER) {
+    throw new Error(`zip: bad local header for ${entry.fileName}`);
+  }
+  const fileNameLen = readUInt16(buf, lhOffset + 26);
+  const extraLen = readUInt16(buf, lhOffset + 28);
+  const dataStart = lhOffset + 30 + fileNameLen + extraLen;
+  const compressed = buf.slice(dataStart, dataStart + entry.compressedSize);
+
+  if (entry.method === 0) {
+    return compressed;
+  }
+  if (entry.method === 8) {
+    return zlib.inflateRawSync(compressed);
+  }
+  throw new Error(`zip: unsupported compression method ${entry.method} for ${entry.fileName}`);
+}
+
+function isPathInside(parent, child) {
+  const rel = path.relative(parent, child);
+  return !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function safeJoin(targetDir, fileName) {
+  const normalized = fileName.replace(/\\/g, '/').replace(/^\/+/, '');
+  if (normalized.split('/').some((segment) => segment === '..')) {
+    throw new Error(`zip: refusing path traversal entry ${fileName}`);
+  }
+  const dest = path.resolve(targetDir, normalized);
+  if (!isPathInside(path.resolve(targetDir), dest)) {
+    throw new Error(`zip: entry escapes target dir: ${fileName}`);
+  }
+  return dest;
+}
+
+function extractZipBuffer(buffer, targetDir, options = {}) {
+  const maxTotal = options.maxTotalSize || DEFAULT_MAX_TOTAL_SIZE;
+  const maxFile = options.maxFileSize || DEFAULT_MAX_FILE_SIZE;
+  const maxEntries = options.maxEntries || DEFAULT_MAX_ENTRIES;
+
+  const entries = parseEntries(buffer);
+  if (entries.length > maxEntries) {
+    throw new Error(`zip: too many entries (${entries.length} > ${maxEntries})`);
+  }
+
+  let totalSize = 0;
+  for (const entry of entries) {
+    if (entry.uncompressedSize > maxFile) {
+      throw new Error(`zip: entry ${entry.fileName} exceeds max file size (${entry.uncompressedSize})`);
+    }
+    totalSize += entry.uncompressedSize;
+    if (totalSize > maxTotal) {
+      throw new Error(`zip: total uncompressed size exceeds limit (${totalSize} > ${maxTotal})`);
+    }
+  }
+
+  fs.mkdirSync(targetDir, { recursive: true });
+
+  const written = [];
+  for (const entry of entries) {
+    if (entry.isSymlink) {
+      throw new Error(`zip: symlinks are not allowed (${entry.fileName})`);
+    }
+    if (entry.isDirectory) {
+      const dest = safeJoin(targetDir, entry.fileName);
+      fs.mkdirSync(dest, { recursive: true });
+      continue;
+    }
+    const dest = safeJoin(targetDir, entry.fileName);
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const data = readEntryData(buffer, entry);
+    if (data.length > maxFile) {
+      throw new Error(`zip: decompressed entry exceeds limit (${entry.fileName})`);
+    }
+    fs.writeFileSync(dest, data);
+    written.push(path.relative(targetDir, dest));
+  }
+
+  return { entries: entries.length, written };
+}
+
+function extractZipFile(zipPath, targetDir, options = {}) {
+  const buffer = fs.readFileSync(zipPath);
+  return extractZipBuffer(buffer, targetDir, options);
+}
+
+module.exports = {
+  DEFAULT_MAX_FILE_SIZE,
+  DEFAULT_MAX_TOTAL_SIZE,
+  DEFAULT_MAX_ENTRIES,
+  extractZipBuffer,
+  extractZipFile,
+  parseEntries,
+};