@casatwy/deyo 0.1.7 → 0.2.0

package/skill-manager.mjs

@@ -0,0 +1,1344 @@
+import { constants as fsConstants } from 'node:fs'
+import {
+  access,
+  chmod,
+  lstat,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  readlink,
+  rename,
+  unlink,
+} from 'node:fs/promises'
+import { spawn } from 'node:child_process'
+import { createHash, randomBytes } from 'node:crypto'
+import { homedir } from 'node:os'
+import { basename, dirname, isAbsolute, join, normalize, resolve } from 'node:path'
+import process from 'node:process'
+
+export const SKILL_PLATFORMS = ['codex', 'claude', 'gemini', 'openclaw']
+export const SKILL_SCOPES = ['user', 'workspace', 'global']
+
+const MARKETPLACE_NAME = 'deyo-official'
+const PLUGIN_ID = `deyo@${MARKETPLACE_NAME}`
+const GITHUB_REPOSITORY = 'casatwy/deyo-skill'
+const GIT_SOURCE_URL = 'https://github.com/casatwy/deyo-skill.git'
+const OPENCLAW_SKILL = '@casatwy/deyo'
+
+const DEFAULT_SCOPES = {
+  codex: 'user',
+  claude: 'user',
+  gemini: 'user',
+  openclaw: 'global',
+}
+
+const SUPPORTED_SCOPES = {
+  codex: new Set(['user']),
+  claude: new Set(['user', 'workspace']),
+  gemini: new Set(['user']),
+  openclaw: new Set(['workspace', 'global']),
+}
+
+// These hashes are generated with hashLegacyTree() from official deyo/ trees
+// previously published in github.com/casatwy/deyo-skill. Directory entries,
+// paths, file bytes, modes, and symlink targets all participate in the digest.
+// Unknown trees are intentionally never migrated automatically.
+const OFFICIAL_LEGACY_HASHES = new Map([
+  ['sha256:0dc4e4a2ac1a616d79e7deaf365dcbf4c26bf70ec5a4554806a5b68760c584ca', 'c98b981237aadae462019a822509b463ff2900cd'],
+  ['sha256:fe3fc055413da24e48ca4e3a3d24319fa7033f2d494df803243b175e121053ac', '6fe78e74728fbab6aba75f6acc92cee5c143af3d'],
+  ['sha256:38112030ae205c4c58b90e8ef7497a590b4ee3485311bd6aa1a777b4c7ed29f1', '91d001299aa82a1411e037bb267e463d171885c6'],
+  ['sha256:a19f75e873ff6d6e28555a08cc83388e3d7a5cace25d8d59c736d07c2764a8bf', '13b2e5d555f1596810b5e6835804bd3ba18dbe4a'],
+  ['sha256:0e8d8b3d418bd1be05799f35bab08e40d99cae553c706371675da26adf614e38', 'f1e25f0cbfb0740d7834cce2f25f27a5d00392b1'],
+  ['sha256:bb2349e66a15d6f63914a079556b440e6374e16d6091bf7cb6d667ff77b4cc88', '96d5e851e14e89b8318428f580d4b15660549570'],
+  ['sha256:6eae6dbb865422639c9d6ab79293c803712b78e7eb223401bc2421e46cfec301', 'da0039cee32a4756378770ece55577da43cac243'],
+  ['sha256:3c82cc30d4376618ad3c059411fb52ffd82f14523627fcb80c6eff6f3807c5dd', 'b5c884e03f047e5372720c9fe86f2127803d0c58'],
+  ['sha256:d2debbabc20d4efc1e054e2e46a05e2ab809fd8a84ad325fd38018d0a0c6469e', '0442925dd7a9a18be7adaefaa351dd5b79ace607'],
+  ['sha256:cb3958fcd77bdf674a85153c978bccfd658ab25292bca138c0a2846580b4ea9c', 'b497324d0091e45f6cd57612e1295ea593b0c2b4'],
+  ['sha256:6e556a96701f00baa4eaf3d9a10a38eb4d852e6b9c853aea474286cd35565d3b', '4fed0be6d69dd99179403f02b03bf4a5f5c3f334'],
+])
+
+class SkillManagerError extends Error {
+  constructor(message, code = 'skill_error') {
+    super(message)
+    this.code = code
+  }
+}
+
+class SkillCommandReportedError extends Error {
+  constructor(exitCode = 1) {
+    super('Deyo Skill 命令已报告错误')
+    this.name = 'SkillCommandReportedError'
+    this.exitCode = exitCode
+  }
+}
+
+function expandConfiguredPath(name, value, fallback, expansionHome = homedir()) {
+  if (!value) return normalize(fallback)
+  let expanded = String(value)
+  if (expanded === '~') expanded = expansionHome
+  else if (/^~[\\/]/.test(expanded)) expanded = join(expansionHome, expanded.slice(2))
+  if (!isAbsolute(expanded)) {
+    throw new SkillManagerError(`${name} 必须是绝对路径`, 'invalid_config_path')
+  }
+  return normalize(expanded)
+}
+
+function getHomeDirectory() {
+  if (process.env.HOME) {
+    return expandConfiguredPath('HOME', process.env.HOME, homedir())
+  }
+  if (process.env.USERPROFILE) {
+    return expandConfiguredPath('USERPROFILE', process.env.USERPROFILE, homedir())
+  }
+  return normalize(homedir())
+}
+
+function getCodexHome() {
+  const home = getHomeDirectory()
+  return expandConfiguredPath('CODEX_HOME', process.env.CODEX_HOME, join(home, '.codex'), home)
+}
+
+function getClaudeHome() {
+  const home = getHomeDirectory()
+  return expandConfiguredPath(
+    'CLAUDE_CONFIG_DIR',
+    process.env.CLAUDE_CONFIG_DIR,
+    join(home, '.claude'),
+    home,
+  )
+}
+
+function getGeminiHome() {
+  const home = getHomeDirectory()
+  const geminiRoot = expandConfiguredPath(
+    'GEMINI_CLI_HOME',
+    process.env.GEMINI_CLI_HOME,
+    home,
+    home,
+  )
+  return join(geminiRoot, '.gemini')
+}
+
+function getOpenClawHome() {
+  const home = getHomeDirectory()
+  if (process.env.OPENCLAW_STATE_DIR) {
+    return expandConfiguredPath(
+      'OPENCLAW_STATE_DIR',
+      process.env.OPENCLAW_STATE_DIR,
+      join(home, '.openclaw'),
+      home,
+    )
+  }
+  const openClawHome = expandConfiguredPath(
+    'OPENCLAW_HOME',
+    process.env.OPENCLAW_HOME,
+    home,
+    home,
+  )
+  return join(openClawHome, '.openclaw')
+}
+
+function getDefaultScope(platform) {
+  return DEFAULT_SCOPES[platform]
+}
+
+function validatePlatform(platform) {
+  if (!SKILL_PLATFORMS.includes(platform)) {
+    throw new SkillManagerError(
+      `--platform 必须是 ${SKILL_PLATFORMS.join('、')} 之一`,
+      'invalid_platform',
+    )
+  }
+}
+
+function validateScope(platform, scope) {
+  if (!SKILL_SCOPES.includes(scope)) {
+    throw new SkillManagerError(
+      `--scope 必须是 ${SKILL_SCOPES.join('、')} 之一`,
+      'invalid_scope',
+    )
+  }
+
+  if (!SUPPORTED_SCOPES[platform].has(scope)) {
+    const supported = [...SUPPORTED_SCOPES[platform]].join('、')
+    throw new SkillManagerError(
+      `${platform} 的原生安装器不支持 ${scope} scope；可用 scope：${supported}`,
+      'unsupported_scope',
+    )
+  }
+}
+
+function parseSha256(value) {
+  const normalized = String(value || '').trim().toLowerCase()
+  if (!/^sha256:[a-f0-9]{64}$/.test(normalized)) {
+    throw new SkillManagerError(
+      '--replace-legacy 必须使用 status 显示的完整 sha256:<64位摘要>',
+      'invalid_legacy_hash',
+    )
+  }
+  return normalized
+}
+
+export function printSkillUsage(stream = process.stdout) {
+  stream.write(`用法:
+  deyo skill install --platform codex|claude|gemini|openclaw
+                     [--scope user|workspace|global]
+                     [--replace-legacy sha256:<observed-hash>]
+                     [--json]
+  deyo skill status [--platform codex|claude|gemini|openclaw] [--json]
+
+默认 scope:
+  codex=user，claude=user，gemini=user，openclaw=global
+
+说明:
+  status 只读取本地配置和 manifest，不联网、不检查更新，也不修改 cache/lockfile。
+  install 只调用各平台原生管理器；不会用 --force、--all、固定 --ref 或 --consent。
+  legacy 目录只有在完整树哈希属于官方历史版本，且 --replace-legacy 精确匹配时才会备份迁移。
+`)
+}
+
+function parseSkillCommandArgs(argv) {
+  const requestedAction = argv[1] || ''
+  const action = requestedAction === '-h' || requestedAction === '--help' ? '' : requestedAction
+  const result = {
+    action,
+    platform: '',
+    scope: '',
+    replaceLegacy: '',
+    json: false,
+    help: requestedAction === '-h' || requestedAction === '--help',
+  }
+  const seen = new Set()
+
+  function markSeen(option) {
+    if (seen.has(option)) {
+      throw new SkillManagerError(`skill 参数不能重复：${option}`, 'duplicate_argument')
+    }
+    seen.add(option)
+  }
+
+  function readOptionValue(option, index) {
+    const value = argv[index + 1]
+    if (!value || value.startsWith('-')) {
+      throw new SkillManagerError(`${option} 缺少参数值`, 'missing_argument_value')
+    }
+    return value
+  }
+
+  for (let index = 2; index < argv.length; index += 1) {
+    const current = argv[index]
+    if (current === '-h' || current === '--help') {
+      result.help = true
+      continue
+    }
+    if (current === '--json') {
+      markSeen(current)
+      result.json = true
+      continue
+    }
+    if (current === '--platform') {
+      markSeen(current)
+      result.platform = readOptionValue(current, index)
+      index += 1
+      continue
+    }
+    if (current === '--scope') {
+      markSeen(current)
+      result.scope = readOptionValue(current, index)
+      index += 1
+      continue
+    }
+    if (current === '--replace-legacy') {
+      markSeen(current)
+      result.replaceLegacy = readOptionValue(current, index)
+      index += 1
+      continue
+    }
+    throw new SkillManagerError(`未知 skill 参数：${current}`, 'unknown_argument')
+  }
+
+  if (!action && !result.help) {
+    throw new SkillManagerError('缺少 skill 子命令 install 或 status', 'missing_action')
+  }
+  if (!['install', 'status'].includes(action) && !result.help) {
+    throw new SkillManagerError(`不支持的 skill 子命令：${action}`, 'invalid_action')
+  }
+  if (action === 'install' && !result.platform && !result.help) {
+    throw new SkillManagerError('skill install 必须提供 --platform', 'missing_platform')
+  }
+  if (action === 'status' && result.scope) {
+    throw new SkillManagerError('skill status 不接受 --scope；它检查各平台默认生效 scope', 'status_scope')
+  }
+  if (action === 'status' && result.replaceLegacy) {
+    throw new SkillManagerError('skill status 不接受 --replace-legacy', 'status_replace_legacy')
+  }
+
+  return result
+}
+
+async function pathLstat(path) {
+  try {
+    return await lstat(path)
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null
+    throw error
+  }
+}
+
+async function readUtf8IfExists(path) {
+  try {
+    return await readFile(path, 'utf8')
+  } catch (error) {
+    if (error?.code === 'ENOENT') return null
+    throw error
+  }
+}
+
+async function readJsonIfExists(path) {
+  const content = await readUtf8IfExists(path)
+  if (content === null) return null
+  try {
+    return JSON.parse(content)
+  } catch {
+    throw new SkillManagerError(`JSON 文件无法解析：${path}`, 'invalid_json')
+  }
+}
+
+async function inspectJsonMetadata(path) {
+  const stats = await pathLstat(path)
+  if (!stats) return { exists: false, safe: true, value: null }
+  if (stats.isSymbolicLink() || !stats.isFile()) {
+    return { exists: true, safe: false, value: null }
+  }
+  try {
+    return { exists: true, safe: true, value: JSON.parse(await readFile(path, 'utf8')) }
+  } catch {
+    return { exists: true, safe: false, value: null }
+  }
+}
+
+function updateLengthPrefixed(hash, value) {
+  const buffer = Buffer.isBuffer(value) ? value : Buffer.from(String(value), 'utf8')
+  const length = Buffer.alloc(8)
+  length.writeBigUInt64BE(BigInt(buffer.length))
+  hash.update(length)
+  hash.update(buffer)
+}
+
+function updateMode(hash, mode) {
+  const buffer = Buffer.alloc(4)
+  buffer.writeUInt32BE(mode & 0o7777)
+  hash.update(buffer)
+}
+
+function sortNames(names) {
+  return [...names].sort((first, second) => Buffer.compare(
+    Buffer.from(first, 'utf8'),
+    Buffer.from(second, 'utf8'),
+  ))
+}
+
+export async function hashLegacyTree(rootPath) {
+  const rootStats = await pathLstat(rootPath)
+  if (!rootStats) return null
+
+  const hash = createHash('sha256')
+  hash.update('deyo-legacy-tree-v1\0')
+
+  async function visit(path, relativePath) {
+    const entryStats = await lstat(path)
+    if (entryStats.isDirectory()) {
+      hash.update('D')
+      updateLengthPrefixed(hash, relativePath)
+      updateMode(hash, entryStats.mode)
+      const names = sortNames(await readdir(path))
+      for (const name of names) {
+        await visit(join(path, name), relativePath === '.' ? name : `${relativePath}/${name}`)
+      }
+      return
+    }
+
+    if (entryStats.isFile()) {
+      hash.update('F')
+      updateLengthPrefixed(hash, relativePath)
+      updateMode(hash, entryStats.mode)
+      updateLengthPrefixed(hash, await readFile(path))
+      return
+    }
+
+    if (entryStats.isSymbolicLink()) {
+      hash.update('L')
+      updateLengthPrefixed(hash, relativePath)
+      updateMode(hash, entryStats.mode)
+      updateLengthPrefixed(hash, await readlink(path))
+      return
+    }
+
+    throw new SkillManagerError(
+      `legacy 路径包含不支持的文件类型：${path}`,
+      'unsupported_legacy_entry',
+    )
+  }
+
+  await visit(rootPath, '.')
+  return `sha256:${hash.digest('hex')}`
+}
+
+function getLegacyPaths(platform, scope) {
+  const home = getHomeDirectory()
+  if (platform === 'codex') {
+    return [
+      join(getCodexHome(), 'skills', 'deyo'),
+      join(home, '.agents', 'skills', 'deyo'),
+    ]
+  }
+  if (platform === 'claude') {
+    return scope === 'workspace'
+      ? [resolve('.claude', 'skills', 'deyo')]
+      : [join(getClaudeHome(), 'skills', 'deyo')]
+  }
+  if (platform === 'gemini') {
+    return scope === 'workspace'
+      ? [resolve('.gemini', 'skills', 'deyo')]
+      : [join(getGeminiHome(), 'skills', 'deyo')]
+  }
+  return scope === 'global'
+    ? [join(getOpenClawHome(), 'skills', 'deyo')]
+    : [resolve('skills', 'deyo')]
+}
+
+function getOpenClawOriginPath(skillPath) {
+  return join(skillPath, '.clawhub', 'origin.json')
+}
+
+async function inspectLegacy(platform, scope) {
+  const entries = []
+  for (const path of getLegacyPaths(platform, scope)) {
+    const stats = await pathLstat(path)
+    if (!stats) continue
+    if (platform === 'openclaw' && stats.isDirectory() && !stats.isSymbolicLink()) {
+      const originStats = await pathLstat(getOpenClawOriginPath(path))
+      if (originStats?.isFile() && !originStats.isSymbolicLink()) continue
+    }
+    const hash = await hashLegacyTree(path)
+    entries.push({
+      path,
+      hash,
+      recognized: OFFICIAL_LEGACY_HASHES.has(hash),
+      officialRevision: OFFICIAL_LEGACY_HASHES.get(hash) || null,
+      type: stats.isDirectory() ? 'directory' : stats.isSymbolicLink() ? 'symlink' : 'other',
+    })
+  }
+  return entries
+}
+
+async function migrateLegacy(entries, expectedHash) {
+  if (!entries.length) {
+    if (expectedHash) {
+      throw new SkillManagerError(
+        '--replace-legacy 已提供，但当前 scope 没有发现 legacy Deyo Skill',
+        'legacy_not_found',
+      )
+    }
+    return null
+  }
+  if (entries.length !== 1) {
+    throw new SkillManagerError(
+      `发现多个 legacy Deyo Skill，拒绝自动处理：${entries.map(entry => entry.path).join('、')}`,
+      'multiple_legacy_installs',
+    )
+  }
+
+  const entry = entries[0]
+  if (!expectedHash) {
+    throw new SkillManagerError(
+      `发现 legacy Deyo Skill：${entry.path}（${entry.hash}）。确认没有本地修改后，用 --replace-legacy ${entry.hash} 重试`,
+      'legacy_confirmation_required',
+    )
+  }
+  if (entry.hash !== expectedHash) {
+    throw new SkillManagerError(
+      `legacy 哈希已变化：当前 ${entry.hash}，参数为 ${expectedHash}`,
+      'legacy_hash_changed',
+    )
+  }
+  if (!entry.recognized) {
+    throw new SkillManagerError(
+      `legacy 内容不是已知官方历史版本，拒绝覆盖：${entry.path}`,
+      'unknown_legacy_content',
+    )
+  }
+
+  const recheckedHash = await hashLegacyTree(entry.path)
+  if (recheckedHash !== expectedHash) {
+    throw new SkillManagerError('legacy 内容在迁移前发生变化，已停止', 'legacy_race')
+  }
+
+  const backupPath = `${entry.path}.deyo-backup-${Date.now()}-${randomBytes(4).toString('hex')}`
+  await rename(entry.path, backupPath)
+  const backupHash = await hashLegacyTree(backupPath)
+  if (backupHash !== expectedHash) {
+    await rename(backupPath, entry.path).catch(() => {})
+    throw new SkillManagerError('legacy 备份复算哈希不一致，已停止并尝试恢复', 'legacy_backup_mismatch')
+  }
+
+  return {
+    originalPath: entry.path,
+    backupPath,
+    hash: expectedHash,
+    async restore() {
+      if (await pathLstat(entry.path)) {
+        const failedInstallPath = `${entry.path}.deyo-failed-install-${Date.now()}-${randomBytes(4).toString('hex')}`
+        await rename(entry.path, failedInstallPath)
+      }
+      await rename(backupPath, entry.path)
+    },
+  }
+}
+
+function normalizeRepositorySource(value) {
+  let normalized = String(value || '').trim().toLowerCase()
+  if (!normalized) return ''
+  normalized = normalized.replace(/^git\+/, '')
+  normalized = normalized.replace(/^git@github\.com:/, '')
+  normalized = normalized.replace(/^ssh:\/\/git@github\.com\//, '')
+  normalized = normalized.replace(/^https?:\/\/github\.com\//, '')
+  normalized = normalized.replace(/#.*$/, '')
+  normalized = normalized.replace(/\.git\/?$/, '')
+  normalized = normalized.replace(/^\/+|\/+$/g, '')
+  return normalized
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}
+
+function repositorySourceCandidates(value) {
+  if (typeof value === 'string') return [value]
+  if (!isPlainObject(value)) return []
+
+  if (isPlainObject(value.marketplaceSource)) {
+    const marketplaceSource = value.marketplaceSource
+    if (typeof marketplaceSource.source === 'string') return [marketplaceSource.source]
+    return repositorySourceCandidates(marketplaceSource)
+  }
+  if (isPlainObject(value.installSource)) {
+    const installSource = value.installSource
+    if (typeof installSource.source === 'string') return [installSource.source]
+    return repositorySourceCandidates(installSource)
+  }
+  if (isPlainObject(value.source)) {
+    return repositorySourceCandidates(value.source)
+  }
+  for (const key of ['repo', 'repository', 'url', 'gitUrl']) {
+    if (typeof value[key] === 'string') return [value[key]]
+  }
+  return typeof value.source === 'string' ? [value.source] : []
+}
+
+function hasOfficialRepositorySource(value) {
+  return repositorySourceCandidates(value)
+    .some(item => normalizeRepositorySource(item) === GITHUB_REPOSITORY)
+}
+
+function parseJsonOutput(result, commandLabel) {
+  try {
+    return JSON.parse(result.stdout || 'null')
+  } catch {
+    throw new SkillManagerError(`${commandLabel} 没有返回合法 JSON`, 'manager_invalid_json')
+  }
+}
+
+function flattenArray(value, preferredKeys = []) {
+  if (Array.isArray(value)) return value
+  if (!value || typeof value !== 'object') return []
+  for (const key of preferredKeys) {
+    if (Array.isArray(value[key])) return value[key]
+  }
+  return []
+}
+
+async function findExecutable(command) {
+  const pathValue = process.env.PATH || ''
+  const suffixes = process.platform === 'win32'
+    ? (process.env.PATHEXT || '.EXE;.CMD;.BAT').split(';')
+    : ['']
+  for (const directory of pathValue.split(process.platform === 'win32' ? ';' : ':')) {
+    if (!directory) continue
+    for (const suffix of suffixes) {
+      const candidate = resolve(directory, `${command}${suffix}`)
+      try {
+        await access(candidate, fsConstants.X_OK)
+        return candidate
+      } catch {}
+    }
+  }
+  return null
+}
+
+async function requireExecutable(command) {
+  const executable = await findExecutable(command)
+  if (!executable) {
+    throw new SkillManagerError(
+      `未找到 ${command}。请先安装对应平台 CLI，再重试`,
+      'manager_not_found',
+    )
+  }
+  return executable
+}
+
+async function runManager(command, args, options = {}) {
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd || process.cwd(),
+      env: process.env,
+      stdio: options.interactive ? ['inherit', 'pipe', 'pipe'] : ['ignore', 'pipe', 'pipe'],
+    })
+    const stdout = []
+    const stderr = []
+
+    child.stdout.on('data', (chunk) => {
+      stdout.push(Buffer.from(chunk))
+      if (options.interactive) {
+        ;(options.jsonMode ? process.stderr : process.stdout).write(chunk)
+      }
+    })
+    child.stderr.on('data', (chunk) => {
+      stderr.push(Buffer.from(chunk))
+      if (options.interactive) process.stderr.write(chunk)
+    })
+    child.on('error', (error) => {
+      if (error?.code === 'ENOENT') {
+        rejectPromise(new SkillManagerError(`未找到 ${command}`, 'manager_not_found'))
+        return
+      }
+      rejectPromise(error)
+    })
+    child.on('close', (exitCode, signal) => {
+      const result = {
+        exitCode: exitCode ?? 1,
+        signal: signal || null,
+        stdout: Buffer.concat(stdout).toString('utf8'),
+        stderr: Buffer.concat(stderr).toString('utf8'),
+      }
+      if (result.exitCode !== 0 && !options.allowFailure) {
+        const detail = result.stderr.trim() || result.stdout.trim() || `exit ${result.exitCode}`
+        rejectPromise(new SkillManagerError(
+          `${command} ${args.join(' ')} 失败：${detail}`,
+          'manager_failed',
+        ))
+        return
+      }
+      resolvePromise(result)
+    })
+  })
+}
+
+function findMarketplace(list, name) {
+  return flattenArray(list, ['marketplaces']).find(item => item?.name === name) || null
+}
+
+function findPlugin(list, pluginId) {
+  const entries = [
+    ...flattenArray(list, ['installed', 'plugins']),
+    ...(Array.isArray(list?.available) ? list.available : []),
+  ]
+  return entries.find(item => (
+    item?.pluginId === pluginId
+    || item?.id === pluginId
+    || (item?.name === 'deyo' && item?.marketplaceName === MARKETPLACE_NAME)
+  ) && item?.installed !== false) || null
+}
+
+function findForeignDeyoPlugin(list) {
+  const entries = [
+    ...flattenArray(list, ['installed', 'plugins']),
+    ...(Array.isArray(list?.available) ? list.available : []),
+  ]
+  return entries.find(item => {
+    const id = item?.pluginId || item?.id || ''
+    const installed = item?.installed !== false
+    return installed && (
+      (item?.name === 'deyo' && item?.marketplaceName !== MARKETPLACE_NAME)
+      || (id.startsWith('deyo@') && id !== PLUGIN_ID)
+    )
+  }) || null
+}
+
+async function buildCodexInstallPlan(jsonMode) {
+  const codex = await requireExecutable('codex')
+  const marketplaceList = parseJsonOutput(
+    await runManager(codex, ['plugin', 'marketplace', 'list', '--json']),
+    'codex plugin marketplace list',
+  )
+  const marketplace = findMarketplace(marketplaceList, MARKETPLACE_NAME)
+  if (marketplace && !hasOfficialRepositorySource(marketplace)) {
+    throw new SkillManagerError(
+      `Codex 已有同名 marketplace ${MARKETPLACE_NAME}，但来源不是 ${GITHUB_REPOSITORY}`,
+      'marketplace_source_conflict',
+    )
+  }
+
+  const pluginList = parseJsonOutput(
+    await runManager(codex, ['plugin', 'list', '--json']),
+    'codex plugin list',
+  )
+  const foreign = findForeignDeyoPlugin(pluginList)
+  if (foreign) {
+    throw new SkillManagerError('Codex 已安装同名异源 Deyo plugin，拒绝覆盖', 'plugin_source_conflict')
+  }
+  const installed = findPlugin(pluginList, PLUGIN_ID)
+
+  return async () => {
+    const actions = []
+    if (!marketplace) {
+      await runManager(codex, ['plugin', 'marketplace', 'add', GITHUB_REPOSITORY], {
+        interactive: true,
+        jsonMode,
+      })
+      actions.push('marketplace_added')
+    }
+    if (!installed) {
+      await runManager(codex, ['plugin', 'add', PLUGIN_ID], {
+        interactive: true,
+        jsonMode,
+      })
+      actions.push('plugin_installed')
+    } else {
+      actions.push('already_installed')
+    }
+    return { actions, activation: 'new_session' }
+  }
+}
+
+function getClaudeSettingsPath(scope) {
+  return scope === 'workspace'
+    ? resolve('.claude', 'settings.json')
+    : join(getClaudeHome(), 'settings.json')
+}
+
+function claudeSourceMatches(entry) {
+  return hasOfficialRepositorySource(entry)
+}
+
+async function validateClaudeSettingsParent(path, create = false) {
+  const parent = dirname(path)
+  let stats = await pathLstat(parent)
+  if (!stats && create) {
+    await mkdir(parent, { recursive: true, mode: 0o700 })
+    stats = await pathLstat(parent)
+  }
+  if (stats?.isSymbolicLink()) {
+    throw new SkillManagerError(`拒绝通过符号链接设置目录写入：${parent}`, 'settings_symlink')
+  }
+  if (stats && !stats.isDirectory()) {
+    throw new SkillManagerError(`Claude 设置目录不是普通目录：${parent}`, 'settings_not_directory')
+  }
+}
+
+function validateClaudeSettingsShape(settings, path) {
+  if (!isPlainObject(settings)) {
+    throw new SkillManagerError(`Claude 设置必须是 JSON object：${path}`, 'settings_invalid_shape')
+  }
+  const marketplaces = settings.extraKnownMarketplaces
+  if (marketplaces !== undefined && !isPlainObject(marketplaces)) {
+    throw new SkillManagerError(
+      `Claude extraKnownMarketplaces 必须是 JSON object：${path}`,
+      'settings_invalid_shape',
+    )
+  }
+  const existing = marketplaces?.[MARKETPLACE_NAME]
+  if (existing !== undefined && !isPlainObject(existing)) {
+    throw new SkillManagerError(
+      `Claude marketplace ${MARKETPLACE_NAME} 配置必须是 JSON object`,
+      'settings_invalid_shape',
+    )
+  }
+  if (existing && !claudeSourceMatches(existing)) {
+    throw new SkillManagerError(
+      `Claude 设置中已有同名 marketplace ${MARKETPLACE_NAME}，但来源不同`,
+      'marketplace_source_conflict',
+    )
+  }
+}
+
+async function readClaudeSettingsSnapshot(scope) {
+  const path = getClaudeSettingsPath(scope)
+  await validateClaudeSettingsParent(path)
+  const stats = await pathLstat(path)
+  if (stats?.isSymbolicLink()) {
+    throw new SkillManagerError(`拒绝写入符号链接设置文件：${path}`, 'settings_symlink')
+  }
+  if (stats && !stats.isFile()) {
+    throw new SkillManagerError(`Claude 设置路径不是普通文件：${path}`, 'settings_not_file')
+  }
+  const content = stats ? await readFile(path, 'utf8') : null
+  let settings = {}
+  if (content !== null) {
+    try {
+      settings = JSON.parse(content)
+    } catch {
+      throw new SkillManagerError(`JSON 文件无法解析：${path}`, 'invalid_json')
+    }
+  }
+  validateClaudeSettingsShape(settings, path)
+  return { path, content, settings }
+}
+
+async function validateClaudeSettings(scope) {
+  return (await readClaudeSettingsSnapshot(scope)).path
+}
+
+async function readAtomicTarget(path) {
+  const stats = await pathLstat(path)
+  if (stats?.isSymbolicLink()) {
+    throw new SkillManagerError(`拒绝写入符号链接设置文件：${path}`, 'settings_symlink')
+  }
+  if (stats && !stats.isFile()) {
+    throw new SkillManagerError(`Claude 设置路径不是普通文件：${path}`, 'settings_not_file')
+  }
+  return {
+    content: stats ? await readFile(path, 'utf8') : null,
+    mode: stats ? stats.mode & 0o777 : 0o600,
+  }
+}
+
+async function writeJsonAtomic(path, value, expectedContent) {
+  await validateClaudeSettingsParent(path, true)
+  const existingStats = await pathLstat(path)
+  if (existingStats?.isSymbolicLink()) {
+    throw new SkillManagerError(`拒绝写入符号链接设置文件：${path}`, 'settings_symlink')
+  }
+  if (existingStats && !existingStats.isFile()) {
+    throw new SkillManagerError(`Claude 设置路径不是普通文件：${path}`, 'settings_not_file')
+  }
+  const mode = existingStats ? existingStats.mode & 0o777 : 0o600
+  const temporaryPath = join(
+    dirname(path),
+    `.${basename(path)}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`,
+  )
+  const handle = await open(temporaryPath, 'wx', mode)
+  let temporaryExists = true
+  try {
+    try {
+      await handle.writeFile(`${JSON.stringify(value, null, 2)}\n`, 'utf8')
+      await handle.sync()
+    } finally {
+      await handle.close()
+    }
+    await chmod(temporaryPath, mode)
+    const current = await readAtomicTarget(path)
+    if (current.content !== expectedContent) {
+      throw new SkillManagerError(
+        `Claude 设置在写入期间发生变化，已停止以避免覆盖：${path}`,
+        'settings_changed',
+      )
+    }
+    await rename(temporaryPath, path)
+    temporaryExists = false
+  } finally {
+    if (temporaryExists) await unlink(temporaryPath).catch(() => {})
+  }
+}
+
+async function withClaudeSettingsLock(path, callback) {
+  await validateClaudeSettingsParent(path, true)
+  const lockPath = join(dirname(path), `.${basename(path)}.deyo.lock`)
+  let handle
+  try {
+    handle = await open(lockPath, 'wx', 0o600)
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      throw new SkillManagerError(
+        `Claude 设置正被另一个 Deyo 安装进程处理：${path}`,
+        'settings_busy',
+      )
+    }
+    throw error
+  }
+  try {
+    return await callback()
+  } finally {
+    await handle.close().catch(() => {})
+    await unlink(lockPath).catch(() => {})
+  }
+}
+
+async function enableClaudeAutoUpdate(scope) {
+  const path = getClaudeSettingsPath(scope)
+  return await withClaudeSettingsLock(path, async () => {
+    const snapshot = await readClaudeSettingsSnapshot(scope)
+    const settings = snapshot.settings
+    settings.extraKnownMarketplaces ||= {}
+    const existing = settings.extraKnownMarketplaces[MARKETPLACE_NAME] || {}
+    settings.extraKnownMarketplaces[MARKETPLACE_NAME] = {
+      ...existing,
+      source: {
+        source: 'github',
+        repo: GITHUB_REPOSITORY,
+      },
+      autoUpdate: true,
+    }
+    await writeJsonAtomic(path, settings, snapshot.content)
+    return path
+  })
+}
+
+async function buildClaudeInstallPlan(scope, jsonMode) {
+  const claude = await requireExecutable('claude')
+  await validateClaudeSettings(scope)
+  const nativeScope = scope === 'workspace' ? 'project' : 'user'
+  const marketplaces = parseJsonOutput(
+    await runManager(claude, ['plugin', 'marketplace', 'list', '--json']),
+    'claude plugin marketplace list',
+  )
+  const marketplace = findMarketplace(marketplaces, MARKETPLACE_NAME)
+  if (marketplace && !hasOfficialRepositorySource(marketplace)) {
+    throw new SkillManagerError(
+      `Claude 已有同名 marketplace ${MARKETPLACE_NAME}，但来源不是 ${GITHUB_REPOSITORY}`,
+      'marketplace_source_conflict',
+    )
+  }
+
+  const plugins = parseJsonOutput(
+    await runManager(claude, ['plugin', 'list', '--json']),
+    'claude plugin list',
+  )
+  const foreign = findForeignDeyoPlugin(plugins)
+  if (foreign) {
+    throw new SkillManagerError('Claude 已安装同名异源 Deyo plugin，拒绝覆盖', 'plugin_source_conflict')
+  }
+  const installed = flattenArray(plugins, ['plugins', 'installed']).find(item => (
+    (item?.id === PLUGIN_ID || item?.pluginId === PLUGIN_ID)
+    && (!item?.scope || item.scope === nativeScope)
+  )) || null
+
+  return async () => {
+    const actions = []
+    if (!marketplace) {
+      await runManager(claude, [
+        'plugin', 'marketplace', 'add', GITHUB_REPOSITORY, '--scope', nativeScope,
+      ], { interactive: true, jsonMode })
+      actions.push('marketplace_added')
+    }
+    const settingsPath = await enableClaudeAutoUpdate(scope)
+    actions.push('auto_update_enabled')
+    if (!installed) {
+      await runManager(claude, [
+        'plugin', 'install', PLUGIN_ID, '--scope', nativeScope,
+      ], { interactive: true, jsonMode })
+      actions.push('plugin_installed')
+    } else {
+      actions.push('already_installed')
+    }
+    return { actions, activation: 'reload_plugins_or_new_session', settingsPath }
+  }
+}
+
+function getGeminiExtensionPath() {
+  return join(getGeminiHome(), 'extensions', 'deyo')
+}
+
+async function inspectGeminiExtension() {
+  const path = getGeminiExtensionPath()
+  const stats = await pathLstat(path)
+  if (!stats) {
+    return { installed: false, path, manifest: null, install: null }
+  }
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    return {
+      installed: true,
+      path,
+      manifest: null,
+      install: null,
+      version: null,
+      officialSource: false,
+      autoUpdate: false,
+      safe: false,
+    }
+  }
+  const manifestMetadata = await inspectJsonMetadata(join(path, 'gemini-extension.json'))
+  const installMetadata = await inspectJsonMetadata(join(path, '.gemini-extension-install.json'))
+  const manifest = manifestMetadata.value
+  const install = installMetadata.value
+  const safe = manifestMetadata.safe && installMetadata.safe
+  return {
+    installed: true,
+    path,
+    manifest,
+    install,
+    version: manifest?.version || install?.version || null,
+    officialSource: safe && hasOfficialRepositorySource(install),
+    autoUpdate: safe && (install?.autoUpdate === true || install?.auto_update === true),
+    safe,
+  }
+}
+
+async function buildGeminiInstallPlan(jsonMode) {
+  const gemini = await requireExecutable('gemini')
+  const extension = await inspectGeminiExtension()
+  if (extension.installed && !extension.officialSource) {
+    throw new SkillManagerError(
+      `Gemini 已存在 deyo extension，但安装来源不是 ${GITHUB_REPOSITORY} 或无法确认`,
+      'extension_source_conflict',
+    )
+  }
+  if (extension.installed && !extension.autoUpdate) {
+    throw new SkillManagerError(
+      'Gemini 的现有 Deyo extension 未启用 auto-update；原生 CLI 没有安全的原地切换命令，请先用 Gemini 原生管理器卸载后重试',
+      'gemini_auto_update_disabled',
+    )
+  }
+
+  return async () => {
+    if (extension.installed) {
+      return { actions: ['already_installed'], activation: 'restart' }
+    }
+    await runManager(gemini, [
+      'extensions', 'install', GIT_SOURCE_URL, '--auto-update',
+    ], { interactive: true, jsonMode })
+    return { actions: ['extension_installed'], activation: 'restart' }
+  }
+}
+
+function getOpenClawSkillPath(scope) {
+  return scope === 'global'
+    ? join(getOpenClawHome(), 'skills', 'deyo')
+    : resolve('skills', 'deyo')
+}
+
+function isOfficialOpenClawOrigin(origin) {
+  if (!isPlainObject(origin)) return false
+  for (const key of ['ref', 'source', 'package']) {
+    if (typeof origin[key] === 'string' && origin[key].trim().toLowerCase() === OPENCLAW_SKILL) {
+      return true
+    }
+  }
+  const owner = origin.owner || origin.publisher || origin.publisherHandle || origin.namespace
+  const slug = origin.slug || origin.skill || origin.name || origin.package
+  return String(owner || '').replace(/^@/, '').toLowerCase() === 'casatwy'
+    && String(slug || '').replace(/^@casatwy\//, '').toLowerCase() === 'deyo'
+}
+
+async function inspectOpenClawSkill(scope) {
+  const path = getOpenClawSkillPath(scope)
+  const stats = await pathLstat(path)
+  if (!stats) {
+    return {
+      path,
+      installed: false,
+      managed: false,
+      officialSource: false,
+      origin: null,
+      version: null,
+      safe: true,
+    }
+  }
+  if (stats.isSymbolicLink() || !stats.isDirectory()) {
+    return {
+      path,
+      installed: true,
+      managed: false,
+      officialSource: false,
+      origin: null,
+      version: null,
+      safe: false,
+    }
+  }
+  const originPath = getOpenClawOriginPath(path)
+  const metadata = await inspectJsonMetadata(originPath)
+  const origin = metadata.value
+  return {
+    path,
+    installed: true,
+    managed: metadata.exists,
+    officialSource: metadata.safe && isOfficialOpenClawOrigin(origin),
+    origin,
+    version: origin?.version || origin?.skillVersion || null,
+    safe: metadata.safe,
+  }
+}
+
+async function buildOpenClawInstallPlan(scope, jsonMode) {
+  const openclaw = await requireExecutable('openclaw')
+  const skill = await inspectOpenClawSkill(scope)
+  if (skill.managed && !skill.officialSource) {
+    throw new SkillManagerError(
+      `OpenClaw 当前 scope 已存在异源 deyo skill：${skill.path}`,
+      'openclaw_source_conflict',
+    )
+  }
+
+  return async () => {
+    const scopeArgs = scope === 'global' ? ['--global'] : []
+    if (skill.managed) {
+      await runManager(openclaw, [
+        'skills', 'update', OPENCLAW_SKILL, ...scopeArgs,
+      ], { interactive: true, jsonMode })
+      return { actions: ['skill_updated'], activation: 'invoke_again_if_updated' }
+    }
+    await runManager(openclaw, [
+      'skills', 'install', OPENCLAW_SKILL, ...scopeArgs,
+    ], { interactive: true, jsonMode })
+    return { actions: ['skill_installed'], activation: 'next_invocation' }
+  }
+}
+
+async function buildPlatformInstallPlan(platform, scope, jsonMode) {
+  if (platform === 'codex') return await buildCodexInstallPlan(jsonMode)
+  if (platform === 'claude') return await buildClaudeInstallPlan(scope, jsonMode)
+  if (platform === 'gemini') return await buildGeminiInstallPlan(jsonMode)
+  return await buildOpenClawInstallPlan(scope, jsonMode)
+}
+
+function extractTomlSection(content, sectionName) {
+  if (!content) return ''
+  const lines = content.split(/\r?\n/)
+  const exactHeader = `[${sectionName}]`
+  const start = lines.findIndex(line => line.trim() === exactHeader)
+  if (start < 0) return ''
+  const section = []
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^\s*\[/.test(lines[index])) break
+    section.push(lines[index])
+  }
+  return section.join('\n')
+}
+
+function readTomlString(section, key) {
+  const match = section.match(new RegExp(`^\\s*${key}\\s*=\\s*["']([^"']*)["']`, 'm'))
+  return match?.[1] || ''
+}
+
+function readTomlBoolean(section, key) {
+  const match = section.match(new RegExp(`^\\s*${key}\\s*=\\s*(true|false)\\s*$`, 'm'))
+  return match ? match[1] === 'true' : null
+}
+
+async function inspectCodexManaged() {
+  const configPath = join(getCodexHome(), 'config.toml')
+  const content = await readUtf8IfExists(configPath) || ''
+  const pluginSection = extractTomlSection(content, `plugins."${PLUGIN_ID}"`)
+  const marketplaceSection = extractTomlSection(content, `marketplaces.${MARKETPLACE_NAME}`)
+  const source = readTomlString(marketplaceSection, 'source')
+  let version = null
+  const pluginCache = join(getCodexHome(), 'plugins', 'cache', MARKETPLACE_NAME, 'deyo')
+  try {
+    const versions = (await readdir(pluginCache))
+      .filter(item => /^\d+\.\d+\.\d+$/.test(item))
+      .sort((first, second) => {
+        const firstParts = first.split('.').map(Number)
+        const secondParts = second.split('.').map(Number)
+        return firstParts[0] - secondParts[0]
+          || firstParts[1] - secondParts[1]
+          || firstParts[2] - secondParts[2]
+      })
+    version = versions.at(-1) || null
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error
+  }
+  return {
+    installed: Boolean(pluginSection),
+    enabled: readTomlBoolean(pluginSection, 'enabled'),
+    version,
+    source: source || null,
+    officialSource: normalizeRepositorySource(source) === GITHUB_REPOSITORY,
+    autoUpdate: 'host_startup_refresh',
+    configPath,
+  }
+}
+
+async function inspectClaudeManaged(scope) {
+  const settingsPath = getClaudeSettingsPath(scope)
+  const settings = await readJsonIfExists(settingsPath) || {}
+  const marketplace = settings.extraKnownMarketplaces?.[MARKETPLACE_NAME] || null
+  const installedIndexPath = join(getClaudeHome(), 'plugins', 'installed_plugins.json')
+  const installedIndex = await readJsonIfExists(installedIndexPath) || {}
+  const nativeScope = scope === 'workspace' ? 'project' : 'user'
+  const records = installedIndex.plugins?.[PLUGIN_ID] || []
+  const record = (Array.isArray(records) ? records : [records]).find(item => item?.scope === nativeScope) || null
+  return {
+    installed: Boolean(record || settings.enabledPlugins?.[PLUGIN_ID] === true),
+    enabled: settings.enabledPlugins?.[PLUGIN_ID] ?? null,
+    version: record?.version || null,
+    source: marketplace?.source || null,
+    officialSource: marketplace ? hasOfficialRepositorySource(marketplace) : false,
+    autoUpdate: marketplace?.autoUpdate === true,
+    settingsPath,
+    installPath: record?.installPath || null,
+  }
+}
+
+async function inspectPlatformManaged(platform, scope) {
+  if (platform === 'codex') return await inspectCodexManaged()
+  if (platform === 'claude') return await inspectClaudeManaged(scope)
+  if (platform === 'gemini') {
+    const extension = await inspectGeminiExtension()
+    return {
+      installed: extension.installed,
+      version: extension.version || null,
+      source: extension.install || null,
+      officialSource: extension.officialSource || false,
+      autoUpdate: extension.autoUpdate || false,
+      installPath: extension.path,
+    }
+  }
+  const skill = await inspectOpenClawSkill(scope)
+  return {
+    installed: skill.installed,
+    version: skill.version,
+    source: skill.origin,
+    officialSource: skill.officialSource,
+    autoUpdate: 'throttled_on_invocation',
+    installPath: skill.path,
+  }
+}
+
+async function getSkillStatus(platform) {
+  const scope = getDefaultScope(platform)
+  const managed = await inspectPlatformManaged(platform, scope)
+  const legacy = await inspectLegacy(platform, scope)
+  const command = platform === 'openclaw' ? 'openclaw' : platform
+  return {
+    platform,
+    scope,
+    managerAvailable: Boolean(await findExecutable(command)),
+    installed: Boolean(managed.installed),
+    version: managed.version || null,
+    officialSource: Boolean(managed.officialSource),
+    autoUpdate: managed.autoUpdate ?? null,
+    managed,
+    legacy,
+    healthy: Boolean(managed.installed && managed.officialSource && legacy.length === 0),
+  }
+}
+
+async function installSkill(options) {
+  validatePlatform(options.platform)
+  const scope = options.scope || getDefaultScope(options.platform)
+  validateScope(options.platform, scope)
+  const expectedHash = options.replaceLegacy ? parseSha256(options.replaceLegacy) : ''
+
+  // All source-conflict and manager checks happen before the legacy directory
+  // is moved or any provider configuration is mutated.
+  const execute = await buildPlatformInstallPlan(options.platform, scope, options.json)
+  const legacy = await inspectLegacy(options.platform, scope)
+  let migration = null
+  try {
+    migration = await migrateLegacy(legacy, expectedHash)
+    const provider = await execute()
+    return {
+      command: 'skill.install',
+      platform: options.platform,
+      scope,
+      provider,
+      legacyMigration: migration ? {
+        originalPath: migration.originalPath,
+        backupPath: migration.backupPath,
+        hash: migration.hash,
+      } : null,
+    }
+  } catch (error) {
+    if (migration) {
+      try {
+        await migration.restore()
+      } catch (restoreError) {
+        throw new SkillManagerError(
+          `${error instanceof Error ? error.message : String(error)}；legacy 自动恢复失败：${restoreError instanceof Error ? restoreError.message : String(restoreError)}`,
+          'legacy_restore_failed',
+        )
+      }
+    }
+    throw error
+  }
+}
+
+function printInstallResult(result) {
+  process.stdout.write(`Deyo Skill 已处理：${result.platform}（scope: ${result.scope}）\n`)
+  for (const action of result.provider.actions) {
+    process.stdout.write(`- ${action}\n`)
+  }
+  if (result.legacyMigration) {
+    process.stdout.write(`legacy 备份：${result.legacyMigration.backupPath}\n`)
+  }
+  process.stdout.write(`生效方式：${result.provider.activation}\n`)
+}
+
+function formatAutoUpdate(value) {
+  if (value === true) return 'enabled'
+  if (value === false) return 'disabled'
+  return value || 'unknown'
+}
+
+function printStatusResult(result) {
+  for (const item of result.platforms) {
+    const state = item.installed ? `installed${item.version ? ` v${item.version}` : ''}` : 'not installed'
+    process.stdout.write(`${item.platform} (${item.scope}): ${state}\n`)
+    process.stdout.write(`  manager: ${item.managerAvailable ? 'available' : 'missing'}\n`)
+    process.stdout.write(`  official source: ${item.officialSource ? 'yes' : 'no'}\n`)
+    process.stdout.write(`  auto update: ${formatAutoUpdate(item.autoUpdate)}\n`)
+    for (const legacy of item.legacy) {
+      process.stdout.write(`  legacy: ${legacy.path}\n`)
+      process.stdout.write(`    hash: ${legacy.hash}\n`)
+      process.stdout.write(`    official historical tree: ${legacy.recognized ? 'yes' : 'no'}\n`)
+    }
+  }
+}
+
+export async function handleSkillCommand(argv, cliVersion) {
+  const wantsJson = argv.includes('--json')
+  try {
+    const args = parseSkillCommandArgs(argv)
+    if (args.help) {
+      printSkillUsage()
+      return
+    }
+    if (args.platform) validatePlatform(args.platform)
+
+    if (args.action === 'install') {
+      const result = await installSkill(args)
+      const output = { cliVersion, ...result }
+      if (args.json) process.stdout.write(`${JSON.stringify(output)}\n`)
+      else printInstallResult(output)
+      return
+    }
+
+    const platforms = args.platform ? [args.platform] : SKILL_PLATFORMS
+    const result = {
+      command: 'skill.status',
+      cliVersion,
+      offline: true,
+      platforms: [],
+    }
+    for (const platform of platforms) {
+      result.platforms.push(await getSkillStatus(platform))
+    }
+    if (args.json) process.stdout.write(`${JSON.stringify(result)}\n`)
+    else printStatusResult(result)
+  } catch (error) {
+    const payload = {
+      command: 'skill.error',
+      error: error?.code || 'skill_error',
+      message: error instanceof Error ? error.message : String(error),
+    }
+    if (wantsJson) process.stdout.write(`${JSON.stringify(payload)}\n`)
+    else process.stderr.write(`Deyo Skill 操作失败：${payload.message}\n`)
+    throw new SkillCommandReportedError(1)
+  }
+}
+
+export const __test = {
+  GITHUB_REPOSITORY,
+  GIT_SOURCE_URL,
+  MARKETPLACE_NAME,
+  OFFICIAL_LEGACY_HASHES,
+  OPENCLAW_SKILL,
+  PLUGIN_ID,
+  getGeminiHome,
+  getLegacyPaths,
+  getOpenClawHome,
+  inspectLegacy,
+  normalizeRepositorySource,
+  writeJsonAtomic,
+}