Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
/**
* 引擎无关的 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 };
}