zsjz-ai/ai-electron/electron/service/codex/skillService.ts

import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
import { basename, dirname, join, relative, resolve, sep } from 'node:path';
import { randomUUID } from 'node:crypto';
import { fromBuffer, type Entry, type ZipFile } from 'yauzl';
import { getSkillsDir, isInsideDir, MAX_SKILL_NAME_LENGTH, SKILL_NAME_PATTERN } from './codexHome';
import type { CodexRuntime, CodexSkillSummary, JsonValue } from './codexRuntime';

/**
 * Skill 的文件层管理。Codex app-server 只给了 skills/list 与 skills/config/write（启停），
 * 没有安装/卸载接口，所以目录的增删由本模块负责，启停仍走原生 RPC。
 *
 * 目录布局：<CODEX_HOME>/skills/<kebab-name>/SKILL.md（+ 可选 agents/ scripts/ references/ assets/）。
 * Codex 会把内置 skill 实体化到同级的 .system/.curated/.experimental，这些一律不可删改。
 */

const MAX_ENTRY_COUNT = 300;
const MAX_FILE_BYTES = 2 * 1024 * 1024;
const MAX_TOTAL_BYTES = 25 * 1024 * 1024;
const MAX_SKILL_MD_BYTES = 64 * 1024;
const SKILL_FILE_NAME = 'SKILL.md';
const STAGING_PREFIX = '.staging-';

const ALLOWED_EXTENSIONS = new Set([
  'md', 'txt', 'json', 'yaml', 'yml', 'toml',
  'py', 'js', 'mjs', 'cjs', 'ts', 'sh', 'ps1', 'bat',
  'png', 'jpg', 'jpeg', 'gif', 'webp', 'svg', 'csv',
]);

export interface SkillListItem extends CodexSkillSummary {
  /** 是否落在本模块可管理的用户目录里（内置 skill 为 false，不允许删除） */
  managed: boolean;
}

export interface SkillFileEntry {
  path: string;
  size: number;
}

export interface SkillReadResult {
  dir: string;
  content: string;
  files: SkillFileEntry[];
}

export interface SkillInstallOptions {
  /** 覆盖 frontmatter 里的 name；不传则用 frontmatter 的 name */
  name?: string | null;
  overwrite?: boolean;
}

export interface SkillTarget {
  path?: string | null;
  name?: string | null;
}

type SkillRuntime = Pick<CodexRuntime, 'listSkills' | 'setSkillEnabled'> &
  Partial<Pick<CodexRuntime, 'readConfig' | 'writeConfigValue'>>;

export interface SkillServiceOptions {
  /** 默认取 <CODEX_HOME>/skills；单测注入临时目录 */
  skillsDir?: string;
  /** 非致命问题的上报口（诊断日志），避免异常被静默吞掉 */
  onDiagnostic?: (line: string) => void;
}

export class SkillService {
  readonly #runtime: SkillRuntime;
  readonly #skillsDir: string;
  readonly #options: SkillServiceOptions;

  constructor(runtime: SkillRuntime, options: SkillServiceOptions = {}) {
    this.#runtime = runtime;
    this.#options = options;
    this.#skillsDir = options.skillsDir ?? getSkillsDir();
  }

  get skillsDir(): string {
    return this.#skillsDir;
  }

  async list(options: { forceReload?: boolean } = {}): Promise<SkillListItem[]> {
    const skills = await this.#runtime.listSkills({ forceReload: options.forceReload ?? false });
    return skills.map((skill) => ({
      ...skill,
      managed: isManagedSkillPath(this.#skillsDir, skill.path),
    }));
  }

  async setEnabled(target: SkillTarget, enabled: boolean): Promise<boolean> {
    const selector = await this.#resolveSelector(target);
    return this.#runtime.setSkillEnabled(selector, enabled);
  }

  async read(target: SkillTarget): Promise<SkillReadResult> {
    const dir = await this.#resolveReadableDir(target);
    const content = await readFile(join(dir, SKILL_FILE_NAME), 'utf8');
    const files = await collectFiles(dir);
    return { dir, content, files };
  }

  /** 从一个已存在的目录安装（配合 osCtl.selectDirectory 选目录） */
  async installFromFolder(srcPath: string, options: SkillInstallOptions = {}): Promise<SkillListItem[]> {
    const source = resolve(srcPath);
    const sourceStat = await stat(source).catch(() => null);
    if (!sourceStat?.isDirectory()) throw new Error('源路径不是一个目录');

    const staging = await this.#createStagingDir();
    try {
      const manifest = await copyFolderChecked(source, staging);
      const name = await finalizeStagedSkill(staging, manifest, options);
      await this.#promoteStaging(staging, name, options.overwrite === true);
    } catch (error) {
      await rm(staging, { recursive: true, force: true }).catch(() => undefined);
      throw error;
    }
    return this.list({ forceReload: true });
  }

  /** 从 zip 字节安装（渲染进程读文件后把字节传过来，主进程不需要拿到本机路径） */
  async installFromZip(data: Uint8Array, options: SkillInstallOptions = {}): Promise<SkillListItem[]> {
    if (!data || data.byteLength === 0) throw new Error('zip 内容为空');
    if (data.byteLength > MAX_TOTAL_BYTES) throw new Error(`zip 超过 ${MAX_TOTAL_BYTES / 1024 / 1024} MiB 上限`);

    const staging = await this.#createStagingDir();
    try {
      const manifest = await extractZipChecked(data, staging);
      const root = await resolveZipRoot(staging, manifest);
      const name = await finalizeStagedSkill(root, manifest, options);
      await this.#promoteStaging(staging, name, options.overwrite === true, root);
    } catch (error) {
      await rm(staging, { recursive: true, force: true }).catch(() => undefined);
      throw error;
    }
    return this.list({ forceReload: true });
  }

  async remove(target: SkillTarget): Promise<SkillListItem[]> {
    const dir = await this.#resolveManagedDir(target);
    await rm(dir, { recursive: true, force: true });
    await this.#clearStaleConfig(dir, basename(dir));
    return this.list({ forceReload: true });
  }

  /**
   * 删掉目录后清掉 config.toml 里的 [[skills.config]] 残留条目。
   * 不清的话，将来装回同名 skill 会直接继承旧的 enabled=false，表现为「装了但不生效」。
   */
  async #clearStaleConfig(dir: string, name: string): Promise<void> {
    const runtime = this.#runtime;
    if (typeof runtime.readConfig !== 'function' || typeof runtime.writeConfigValue !== 'function') return;
    try {
      // 必须按方法调用，解构出来会丢 this 绑定
      const config = await runtime.readConfig();
      const skills = asRecord(config.skills);
      const entries = Array.isArray(skills?.config) ? (skills.config as unknown[]) : null;
      if (!entries) return;
      const kept = entries.filter((item) => !isStaleEntry(item, dir, name));
      if (kept.length === entries.length) return;
      await runtime.writeConfigValue('skills.config', kept as JsonValue[]);
    } catch (error) {
      // 目录已经删掉了，清理失败不该让删除整体失败，但一定要上报，否则表现为配置里有幽灵条目
      this.#options.onDiagnostic?.(
        `清理 skill 配置残留失败：${error instanceof Error ? error.message : String(error)}`,
      );
    }
  }

  /** 把 UI 传来的 path/name 收敛成一个「确实在用户 skills 目录内」的绝对路径 */
  async #resolveManagedDir(target: SkillTarget): Promise<string> {
    const skillsDir = this.#skillsDir;
    if (target.path) {
      const dir = resolve(toSkillDir(target.path));
      assertManagedSkillDir(skillsDir, dir);
      const manifest = await stat(join(dir, SKILL_FILE_NAME)).catch(() => null);
      if (!manifest?.isFile()) throw new Error('该目录下没有 SKILL.md');
      return dir;
    }
    if (target.name) {
      const name = normalizeSkillName(target.name);
      const dir = join(skillsDir, name);
      assertManagedSkillDir(skillsDir, dir);
      const manifest = await stat(join(dir, SKILL_FILE_NAME)).catch(() => null);
      if (!manifest?.isFile()) throw new Error(`未找到名为 ${name} 的 skill`);
      return dir;
    }
    throw new Error('必须提供 skill 的 path 或 name');
  }

  /**
   * 只读解析：内置（.system/.curated/.experimental）与暂存目录允许「查看」，只是不可删改。
   * 与 {@link #resolveManagedDir} 的区别就是不要求一级子目录、也不拦点号目录，
   * 边界仍然锁在 skills 目录内且必须有 SKILL.md。
   */
  async #resolveReadableDir(target: SkillTarget): Promise<string> {
    const skillsDir = this.#skillsDir;
    let dir: string;
    if (target.path) {
      dir = resolve(toSkillDir(target.path));
    } else if (target.name) {
      // 点号目录进不了 normalizeSkillName，所以按 name 只能查到用户自装 skill
      dir = join(skillsDir, normalizeSkillName(target.name));
    } else {
      throw new Error('必须提供 skill 的 path 或 name');
    }
    if (!isInsideDir(skillsDir, dir)) throw new Error('只能查看 skills 目录内的 skill');
    const manifest = await stat(join(dir, SKILL_FILE_NAME)).catch(() => null);
    if (!manifest?.isFile()) {
      throw new Error(target.path ? '该目录下没有 SKILL.md' : `未找到名为 ${target.name} 的 skill`);
    }
    return dir;
  }

  async #resolveSelector(target: SkillTarget): Promise<{ path?: string; name?: string }> {
    if (target.path) return { path: target.path };
    if (target.name) return { name: normalizeSkillName(target.name) };
    throw new Error('必须提供 skill 的 path 或 name');
  }

  async #createStagingDir(): Promise<string> {
    const staging = join(this.#skillsDir, `${STAGING_PREFIX}${randomUUID()}`);
    await mkdir(staging, { recursive: true });
    return staging;
  }

  /** staging → skills/<name>，用 rename 保证原子性 */
  async #promoteStaging(
    staging: string,
    name: string,
    overwrite: boolean,
    stagedRoot = staging,
  ): Promise<void> {
    const target = join(this.#skillsDir, name);
    const existing = await stat(target).catch(() => null);
    if (existing) {
      if (!overwrite) throw new Error(`skill「${name}」已存在，需显式覆盖`);
      await rm(target, { recursive: true, force: true });
    }
    await mkdir(this.#skillsDir, { recursive: true });
    await rename(stagedRoot, target);
    if (resolve(stagedRoot) !== resolve(staging)) {
      // zip 里带了一层外壳目录：搬完内层后清掉外壳
      await rm(staging, { recursive: true, force: true }).catch(() => undefined);
    }
  }
}

/**
 * Codex 的 skills/list 与 skills/config 都用 SKILL.md 文件路径标识一个 skill（见 scripts/codex-ipc-probe.json），
 * UI 把该 path 原样回传，这里先收敛成目录，否则 join(dir, 'SKILL.md') 会拼出不存在的路径。
 */
function toSkillDir(pathOrFile: string): string {
  return basename(pathOrFile) === SKILL_FILE_NAME ? dirname(pathOrFile) : pathOrFile;
}

/** 内置目录（.system/.curated/.experimental）与暂存目录一律不可管理 */
function isManagedSkillPath(skillsDir: string, skillPath: string): boolean {
  if (!isInsideDir(skillsDir, skillPath)) return false;
  const rel = relative(skillsDir, skillPath);
  const first = rel.split(sep)[0] ?? '';
  return Boolean(first) && !first.startsWith('.') && !rel.includes(`..${sep}`);
}

function assertManagedSkillDir(skillsDir: string, dir: string): void {
  if (!isInsideDir(skillsDir, dir)) throw new Error('只能管理用户 skills 目录内的 skill');
  const rel = relative(skillsDir, dir);
  const segments = rel.split(sep);
  // 先判内置/暂存目录，否则 .system/imagegen 会先撞上「一级子目录」的报错，信息不准
  if (segments[0]?.startsWith('.')) throw new Error('内置或暂存目录不可删改');
  if (segments.length !== 1 || !segments[0]) throw new Error('skill 必须是 skills 目录下的一级子目录');
  if (!SKILL_NAME_PATTERN.test(segments[0])) throw new Error('skill 目录名不合法');
}

export function normalizeSkillName(raw: string): string {
  const name = raw
    .trim()
    .toLowerCase()
    .replace(/[\s_]+/gu, '-')
    .replace(/[^a-z0-9-]/gu, '')
    .replace(/-{2,}/gu, '-')
    .replace(/^-|-$/gu, '');
  if (!name || name.length > MAX_SKILL_NAME_LENGTH) {
    throw new Error(`skill 名称非法（需为小写连字符命名，长度 ≤ ${MAX_SKILL_NAME_LENGTH}）`);
  }
  if (!SKILL_NAME_PATTERN.test(name)) throw new Error('skill 名称只能是字母数字与连字符的组合');
  return name;
}

/** 校验并落定 staged skill：必须有合法 frontmatter，返回最终 skill 名 */
async function finalizeStagedSkill(
  root: string,
  manifest: FileManifest,
  options: SkillInstallOptions,
): Promise<string> {
  if (manifest.totalBytes > MAX_TOTAL_BYTES) {
    throw new Error(`skill 内容超过 ${MAX_TOTAL_BYTES / 1024 / 1024} MiB 上限`);
  }
  const skillMd = join(root, SKILL_FILE_NAME);
  const skillStat = await stat(skillMd).catch(() => null);
  if (!skillStat?.isFile()) throw new Error('缺少 SKILL.md');
  if (skillStat.size > MAX_SKILL_MD_BYTES) throw new Error(`SKILL.md 超过 ${MAX_SKILL_MD_BYTES / 1024} KiB 上限`);

  const frontmatter = parseFrontmatter(await readFile(skillMd, 'utf8'));
  const rawName = options.name?.trim() || frontmatter.name;
  if (!rawName) throw new Error('SKILL.md 的 frontmatter 缺少 name');
  if (!frontmatter.description) throw new Error('SKILL.md 的 frontmatter 缺少 description');
  return normalizeSkillName(rawName);
}

interface FileManifest {
  entries: number;
  totalBytes: number;
  paths: string[];
}

function assertAllowedExtension(relPath: string): void {
  const ext = basename(relPath).split('.').pop()?.toLowerCase() ?? '';
  if (!basename(relPath).includes('.')) return;
  if (!ALLOWED_EXTENSIONS.has(ext)) throw new Error(`不允许的文件类型：${relPath}`);
}

/** 相对路径安全校验：拒绝绝对路径、`..`、盘符、UNC 与 macOS 垃圾目录。yauzl 也会拦一层，这里是第二道防线 */
export function assertSafeRelativePath(relPath: string): string {
  if (!relPath || relPath.length > 512) throw new Error('条目路径非法');
  if (relPath.startsWith('__MACOSX/') || relPath.includes('/__MACOSX/')) {
    throw new Error('zip 含 __MACOSX 元数据目录');
  }
  const normalized = relPath.replace(/\\/gu, '/');
  if (/^[a-zA-Z]:/u.test(normalized) || normalized.startsWith('/') || normalized.startsWith('//')) {
    throw new Error('zip 含绝对路径条目');
  }
  const segments = normalized.split('/').filter(Boolean);
  if (!segments.length) throw new Error('zip 条目路径为空');
  for (const segment of segments) {
    if (segment === '..') throw new Error('zip 含路径穿越条目');
    if (segment === '.' || segment.startsWith(STAGING_PREFIX)) throw new Error('zip 条目路径非法');
    if (segment.length > 128) throw new Error('zip 条目路径过长');
  }
  return segments.join('/');
}

async function copyFolderChecked(source: string, staging: string): Promise<FileManifest> {
  const manifest: FileManifest = { entries: 0, totalBytes: 0, paths: [] };
  const walk = async (dir: string): Promise<void> => {
    for (const entry of await readdir(dir, { withFileTypes: true })) {
      const abs = join(dir, entry.name);
      const rel = relative(source, abs).split(sep).join('/');
      if (entry.isSymbolicLink()) throw new Error('源目录含符号链接，拒绝安装');
      if (entry.name.startsWith('.')) continue;
      if (entry.isDirectory()) {
        await mkdir(join(staging, rel), { recursive: true });
        await walk(abs);
        continue;
      }
      if (!entry.isFile()) throw new Error(`不支持的条目类型：${rel}`);
      assertSafeRelativePath(rel);
      assertAllowedExtension(rel);
      const info = await stat(abs);
      if (info.size > MAX_FILE_BYTES) throw new Error(`文件超过单文件 2 MiB 上限：${rel}`);
      manifest.entries += 1;
      manifest.totalBytes += info.size;
      manifest.paths.push(rel);
      if (manifest.entries > MAX_ENTRY_COUNT) throw new Error(`条目数超过 ${MAX_ENTRY_COUNT} 上限`);
      if (manifest.totalBytes > MAX_TOTAL_BYTES) throw new Error('内容总量超过上限');
      await mkdir(dirname(join(staging, rel)), { recursive: true });
      await writeFile(join(staging, rel), await readFile(abs));
    }
  };
  await walk(source);
  if (!manifest.entries) throw new Error('源目录是空的');
  return manifest;
}

function isSymlinkEntry(entry: Entry): boolean {
  // zip 的 Unix mode 存在 externalFileAttributes 高 16 位
  const mode = (entry.externalFileAttributes ?? 0) >>> 16;
  return (mode & 0o170000) === 0o120000;
}

async function extractZipChecked(data: Uint8Array, staging: string): Promise<FileManifest> {
  const manifest: FileManifest = { entries: 0, totalBytes: 0, paths: [] };
  const zip: ZipFile = await new Promise((resolvePromise, rejectPromise) => {
    fromBuffer(Buffer.from(data), { lazyEntries: true, autoClose: false }, (error, zipFile) => {
      // yauzl 的原文是英文且面向 zip 格式细节，页面会直接展示 message，这里包一层可读提示
      if (zipFile && !error) {
        resolvePromise(zipFile);
        return;
      }
      rejectPromise(new Error(`无法解析 zip 文件：${error?.message ?? '格式不正确'}`));
    });
  });

  try {
    await new Promise<void>((resolvePromise, reject) => {
      zip.once('error', reject);
      zip.once('end', () => resolvePromise());
      zip.on('entry', (entry: Entry) => {
        void handleEntry(entry).then(
          () => zip.readEntry(),
          (error: unknown) => reject(error instanceof Error ? error : new Error(String(error))),
        );
      });

      async function handleEntry(entry: Entry): Promise<void> {
        const rawName = entry.fileName.replace(/\\/gu, '/');
        if (isSymlinkEntry(entry)) throw new Error(`zip 含符号链接条目：${rawName}`);
        const isDir = rawName.endsWith('/');
        const rel = assertSafeRelativePath(isDir ? rawName.slice(0, -1) : rawName);
        if (isDir) {
          await mkdir(join(staging, rel), { recursive: true });
          return;
        }
        if (entry.uncompressedSize > MAX_FILE_BYTES) {
          throw new Error(`文件超过单文件 2 MiB 上限：${rel}`);
        }
        assertAllowedExtension(rel);
        manifest.entries += 1;
        if (manifest.entries > MAX_ENTRY_COUNT) throw new Error(`条目数超过 ${MAX_ENTRY_COUNT} 上限`);
        manifest.totalBytes += entry.uncompressedSize;
        if (manifest.totalBytes > MAX_TOTAL_BYTES) throw new Error('解压总量超过 25 MiB 上限');
        manifest.paths.push(rel);

        const buffer = await new Promise<Buffer>((resolveBuffer, rejectBuffer) => {
          zip.openReadStream(entry, (error, stream) => {
            if (error || !stream) {
              rejectBuffer(error ?? new Error(`无法读取 zip 条目：${rel}`));
              return;
            }
            const chunks: Buffer[] = [];
            let received = 0;
            stream.on('data', (chunk: Buffer) => {
              received += chunk.length;
              // 防 zip bomb：实际解压量超过声明值或超过单文件上限就立即中止
              if (received > MAX_FILE_BYTES || received > entry.uncompressedSize) {
                stream.destroy();
                rejectBuffer(new Error(`zip 条目解压量异常：${rel}`));
                return;
              }
              chunks.push(chunk);
            });
            stream.once('error', rejectBuffer);
            stream.once('end', () => resolveBuffer(Buffer.concat(chunks)));
          });
        });
        const destination = join(staging, rel);
        await mkdir(join(destination, '..'), { recursive: true });
        await writeFile(destination, buffer);
      }

      zip.readEntry();
    });
  } finally {
    zip.close();
  }
  if (!manifest.entries) throw new Error('zip 内没有可用文件');
  return manifest;
}

/** zip 常见形态是「一层外壳目录 + SKILL.md」，此时把内层当作 skill 根 */
async function resolveZipRoot(staging: string, manifest: FileManifest): Promise<string> {
  if (manifest.paths.includes(SKILL_FILE_NAME)) return staging;
  const tops = new Set(manifest.paths.map((item) => item.split('/')[0]!));
  if (tops.size === 1) {
    const candidate = join(staging, [...tops][0]!);
    const inner = await stat(join(candidate, SKILL_FILE_NAME)).catch(() => null);
    if (inner?.isFile()) return candidate;
  }
  throw new Error('zip 根目录（或唯一的外壳目录）下没有 SKILL.md');
}

async function collectFiles(dir: string): Promise<SkillFileEntry[]> {
  const files: SkillFileEntry[] = [];
  const walk = async (current: string): Promise<void> => {
    for (const entry of await readdir(current, { withFileTypes: true })) {
      const abs = join(current, entry.name);
      if (entry.isDirectory()) {
        await walk(abs);
        continue;
      }
      if (!entry.isFile()) continue;
      const info = await stat(abs);
      files.push({ path: relative(dir, abs).split(sep).join('/'), size: info.size });
    }
  };
  await walk(dir);
  return files.sort((left, right) => left.path.localeCompare(right.path));
}

/** 只取 YAML frontmatter 里的 name / description 单行标量，够用且不引 YAML 依赖 */
export function parseFrontmatter(content: string): { name: string | null; description: string | null } {
  const match = /^\uFEFF?---\r?\n([\s\S]*?)\r?\n---/u.exec(content);
  if (!match) return { name: null, description: null };
  const fields: Record<string, string> = {};
  for (const line of match[1]!.split(/\r?\n/u)) {
    const pair = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/u.exec(line.trim());
    if (!pair) continue;
    fields[pair[1]!.toLowerCase()] = stripQuotes(pair[2]!.trim());
  }
  return { name: fields.name || null, description: fields.description || null };
}

function stripQuotes(value: string): string {
  if (value.length >= 2 && ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'")))) {
    return value.slice(1, -1);
  }
  return value.replace(/^>\s*|^\|\s*/u, '').trim();
}

/** 配置条目可能按 path（指向 SKILL.md）记录，也可能只按 name 记录 */
function isStaleEntry(item: unknown, removedDir: string, removedName: string): boolean {
  const record = asRecord(item);
  if (!record) return false;
  const entryPath = readString(record.path);
  if (entryPath) {
    const target = resolve(entryPath);
    const dir = resolve(removedDir);
    return target === dir || target.startsWith(dir + sep) || dirname(target) === dir;
  }
  const entryName = readString(record.name);
  return Boolean(entryName) && entryName === removedName;
}

function asRecord(value: unknown): Record<string, unknown> | null {
  return value && typeof value === 'object' && !Array.isArray(value)
    ? (value as Record<string, unknown>)
    : null;
}

function readString(value: unknown): string | null {
  return typeof value === 'string' ? value : null;
}