Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

9.0 KB
Raw Blame
/**
 * 引擎无关的 customization 文件系统扫描器。
 *
 * 提供通用的目录扫描、SKILL.md 解析、frontmatter 提取能力。
 * 各 agent 通过提供自己的 SourceDef[] (路径 + engine 标签) 复用本模块。
 */

import fs from 'node:fs';
import path from 'node:path';
import matter from 'gray-matter';

import type {
  AgentCustomization,
  AgentCustomizationFile,
  ListCustomizationsResult,
} from '../../types/customizations.js';
import { shouldPruneSkillScanDirectory } from './skill-scan-limits.js';

export interface SourceDef {
  engine: 'claude-code' | 'codex' | 'pi';
  kind: 'skill' | 'command' | 'agent';
  scope: string;
  dir: string;
  workingDir?: string;
  runtimeStatus?: AgentCustomization['runtimeStatus'];
  /** Optional physical root that the skill source, folder, and SKILL.md must stay inside. */
  skillContainWithin?: string;
}

export function parseFrontmatter(raw: string): {
  description?: string;
  frontmatter?: Record<string, unknown>;
  parseError?: string;
} {
  try {
    const parsed = matter(raw);
    if (parsed.data && typeof parsed.data === 'object') {
      const fm = parsed.data as Record<string, unknown>;
      const desc = fm.description;
      return {
        frontmatter: fm,
        ...(typeof desc === 'string' && desc.trim()
          ? { description: desc.trim().slice(0, 500) }
          : {}),
      };
    }
    return {};
  } catch (err) {
    return { parseError: err instanceof Error ? err.message : String(err) };
  }
}

function readChildKind(parent: string, dirent: fs.Dirent): AgentCustomizationFile['kind'] {
  if (dirent.isDirectory()) return 'dir';
  if (!dirent.isSymbolicLink()) return 'file';

  try {
    return fs.statSync(path.join(parent, dirent.name)).isDirectory() ? 'dir' : 'file';
  } catch {
    return 'file';
  }
}

function readFolderSkill(source: SourceDef, folder: string, mdPath: string): AgentCustomization {
  const name = path.basename(folder);

  let description: string | undefined;
  let frontmatter: Record<string, unknown> | undefined;
  let parseError: string | undefined;
  try {
    const raw = fs.readFileSync(mdPath, 'utf-8');
    ({ description, frontmatter, parseError } = parseFrontmatter(raw));
  } catch (err) {
    parseError = err instanceof Error ? err.message : String(err);
  }

  let files: AgentCustomizationFile[] = [];
  try {
    files = fs.readdirSync(folder, { withFileTypes: true })
      .map((s) => ({ name: s.name, kind: readChildKind(folder, s) }))
      .sort((a, b) => {
        if (a.name === 'SKILL.md') return -1;
        if (b.name === 'SKILL.md') return 1;
        if (a.kind !== b.kind) return a.kind === 'dir' ? -1 : 1;
        return a.name.localeCompare(b.name);
      });
  } catch {
    // best-effort
  }

  return {
    engine: source.engine,
    kind: source.kind,
    scope: source.scope,
    name,
    description,
    absolutePath: folder,
    mdPath,
    files,
    frontmatter,
    parseError,
    ...(source.workingDir ? { workingDir: source.workingDir } : {}),
    ...(source.runtimeStatus ? { runtimeStatus: source.runtimeStatus } : {}),
  };
}

function readFileCustomization(source: SourceDef, mdPath: string): AgentCustomization {
  const name = path.basename(mdPath, path.extname(mdPath));

  let description: string | undefined;
  let frontmatter: Record<string, unknown> | undefined;
  let parseError: string | undefined;
  try {
    const raw = fs.readFileSync(mdPath, 'utf-8');
    ({ description, frontmatter, parseError } = parseFrontmatter(raw));
  } catch (err) {
    parseError = err instanceof Error ? err.message : String(err);
  }

  return {
    engine: source.engine,
    kind: source.kind,
    scope: source.scope,
    name,
    description,
    absolutePath: mdPath,
    mdPath,
    files: [],
    frontmatter,
    parseError,
    ...(source.workingDir ? { workingDir: source.workingDir } : {}),
    ...(source.runtimeStatus ? { runtimeStatus: source.runtimeStatus } : {}),
  };
}

type PathContainmentApi = Pick<typeof path, 'relative' | 'isAbsolute'>;

export function isCustomizationPathInside(
  parent: string,
  child: string,
  pathApi: PathContainmentApi = path,
): boolean {
  const relative = pathApi.relative(parent, child);
  return relative === '' || (!relative.startsWith('..') && !pathApi.isAbsolute(relative));
}

function realPathInside(parentRealPath: string, candidate: string): boolean {
  try {
    return isCustomizationPathInside(parentRealPath, fs.realpathSync(candidate));
  } catch {
    return false;
  }
}

function isSymlinkDirectory(target: string): boolean {
  try {
    return fs.lstatSync(target).isSymbolicLink();
  } catch {
    return false;
  }
}

function findSkillMd(folder: string): string | null {
  for (const name of ['SKILL.md', 'skill.md']) {
    const candidate = path.join(folder, name);
    try {
      if (fs.statSync(candidate).isFile()) return candidate;
    } catch {
      // A missing or inaccessible candidate is not a skill folder.
    }
  }
  return null;
}

function scanSkillFolders(
  source: SourceDef,
  containmentRoot: string | null,
  items: AgentCustomization[],
  errors: Array<{ path?: string; message: string }>,
): void {
  const pushSkill = (folder: string, mdPath: string): void => {
    if (
      containmentRoot &&
      (!realPathInside(containmentRoot, folder) || !realPathInside(containmentRoot, mdPath))
    ) {
      return;
    }
    items.push(readFolderSkill(source, folder, mdPath));
  };

  const readDir = (dir: string): fs.Dirent[] | null => {
    try {
      return fs.readdirSync(dir, { withFileTypes: true });
    } catch (err) {
      errors.push({ path: dir, message: err instanceof Error ? err.message : String(err) });
      return null;
    }
  };

  const topLevelEntries = readDir(source.dir);
  if (!topLevelEntries) return;
  topLevelEntries.sort((a, b) => a.name.localeCompare(b.name));

  for (const ent of topLevelEntries) {
    if (ent.name.startsWith('.') || /\.bak\.\d+$/.test(ent.name)) continue;
    const folder = path.join(source.dir, ent.name);
    const mdPath = findSkillMd(folder);
    if (mdPath) {
      pushSkill(folder, mdPath);
      // A skill's child directories are resources, not discoverable skills.
      continue;
    }

    // Dirent can report a Windows junction as a directory; lstat keeps the
    // no-recursive-symlink guarantee consistent across platforms.
    const isSymlink = ent.isSymbolicLink() || (ent.isDirectory() && isSymlinkDirectory(folder));
    if (isSymlink || !ent.isDirectory() || shouldPruneSkillScanDirectory(ent.name)) continue;

    // At most one namespace/author level: <root>/<namespace>/<skill>.
    const namespaceEntries = readDir(folder);
    if (!namespaceEntries) continue;
    namespaceEntries.sort((a, b) => a.name.localeCompare(b.name));
    for (const nested of namespaceEntries) {
      if (nested.name.startsWith('.') || /\.bak\.\d+$/.test(nested.name)) continue;
      const nestedFolder = path.join(folder, nested.name);
      const nestedMd = findSkillMd(nestedFolder);
      if (nestedMd) pushSkill(nestedFolder, nestedMd);
    }
  }
}

function scanOneSource(source: SourceDef): {
  items: AgentCustomization[];
  errors: Array<{ path?: string; message: string }>;
} {
  const errors: Array<{ path?: string; message: string }> = [];
  try {
    if (!fs.existsSync(source.dir)) return { items: [], errors };
    const stat = fs.statSync(source.dir);
    if (!stat.isDirectory()) return { items: [], errors };
    let containmentRoot: string | null = null;
    if (source.skillContainWithin) {
      try {
        containmentRoot = fs.realpathSync(source.skillContainWithin);
      } catch {
        return { items: [], errors };
      }
      if (!realPathInside(containmentRoot, source.dir)) return { items: [], errors };
    }

    const items: AgentCustomization[] = [];
    if (source.kind === 'skill') {
      scanSkillFolders(source, containmentRoot, items, errors);
      return { items, errors };
    }

    const entries = fs.readdirSync(source.dir, { withFileTypes: true });
    for (const ent of entries) {
      if (ent.name.startsWith('.')) continue;
      if (/\.bak\.\d+$/.test(ent.name)) continue;
      if (!ent.isFile()) continue;
      if (!ent.name.toLowerCase().endsWith('.md')) continue;
      items.push(readFileCustomization(source, path.join(source.dir, ent.name)));
    }

    return { items, errors };
  } catch (err) {
    errors.push({ path: source.dir, message: err instanceof Error ? err.message : String(err) });
    return { items: [], errors };
  }
}

/**
 * 通用文件系统扫描入口。
 *
 * 接受预构建的 SourceDef[],逐目录扫描并返回合并结果(不排序)。
 * 各引擎 wrapper 负责构建 sources 并对结果排序。
 */
export function scanCustomizationSources(
  sources: SourceDef[],
  kindFilter?: Set<string> | null,
): ListCustomizationsResult {
  const filtered = kindFilter
    ? sources.filter((s) => kindFilter.has(s.kind))
    : sources;

  const items: AgentCustomization[] = [];
  const errors: Array<{ path?: string; message: string }> = [];

  for (const src of filtered) {
    const r = scanOneSource(src);
    items.push(...r.items);
    errors.push(...r.errors);
  }

  return { items, errors };
}