@skrupellose/code-helper 0.1.0

package/dist/init.js

@@ -0,0 +1,279 @@
+import { mkdir, readdir, rename, rmdir, stat } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { FEATURE_KEYS } from "./constants.js";
+import { loadConfig, saveConfig } from "./config.js";
+import { ensureDirectory, projectPath, upsertManagedMarkdownBlock, upsertMarkdownSection, readTextIfExists, writeText } from "./fs-utils.js";
+import { listProjectSkillRegistrations, registerProjectSkills, resolveSkillRegistrationTargets } from "./skills.js";
+import { getHookTemplates, getRuleTemplates, getSkillTemplates, renderEntryBlock } from "./templates.js";
+/**
+ * 初始化项目中的 code-helper 工作区和协作规则。
+ * 该流程默认是非破坏性的：已有专题文档只跳过，入口文档只更新受控区块。
+ */
+export async function initializeProject(options) {
+    const config = await loadConfig(options.projectRoot);
+    const operations = [];
+    await detectEntryFiles(options.projectRoot, config);
+    const skillRegistrationTargets = await resolveSkillRegistrationTargets(options.projectRoot);
+    operations.push(...(await migrateLegacyAgentWorkspace(options.projectRoot, config)));
+    await createDirectories(options.projectRoot, config, operations);
+    await saveConfig(options.projectRoot, config);
+    operations.push({
+        path: projectPath(options.projectRoot, `${config.directories.workspace}/config.json`),
+        action: "updated",
+        message: "已写入或刷新 code-helper 配置"
+    });
+    operations.push(...(await installEntryDocuments(options.projectRoot, config)));
+    operations.push(...(await installRuleTemplates(options.projectRoot, config)));
+    operations.push(...(await installSkillTemplates(options.projectRoot, config)));
+    operations.push(...(await installProjectSkillRegistrations(options.projectRoot, config, skillRegistrationTargets)));
+    operations.push(...(await installHookTemplates(options.projectRoot, config)));
+    operations.push(await writeStateFile(options.projectRoot, config));
+    return { config, operations };
+}
+/**
+ * 注册项目级 skills。
+ * 初始化按当前项目入口文件注册对应 agent；关闭功能开关时只展示跳过结果，便于用户理解 init 行为。
+ */
+async function installProjectSkillRegistrations(projectRoot, config, targets) {
+    const operations = [];
+    if (!config.features.skillRegistration.enabled) {
+        const statuses = (await Promise.all(targets.map((target) => listProjectSkillRegistrations(projectRoot, target)))).flat();
+        return statuses.map((status) => ({
+            path: status.path,
+            action: "skipped",
+            message: "Skills 管理功能已关闭，跳过项目级注册"
+        }));
+    }
+    for (const target of targets) {
+        operations.push(...(await registerProjectSkills(projectRoot, target)));
+    }
+    return operations;
+}
+/**
+ * 迁移旧版工作区到新版布局。
+ * 内部状态保留在 `.code-helper`，可读协作文档迁移到 `code-helper-docs`。
+ */
+async function migrateLegacyAgentWorkspace(projectRoot, config) {
+    const migrations = [
+        { from: ".agent/code-helper", to: config.directories.workspace },
+        { from: ".agent/user-rules", to: config.directories.userRules },
+        { from: ".agent/plan-doc", to: config.directories.planDoc },
+        { from: ".agent/result-doc", to: config.directories.resultDoc },
+        { from: ".agent/status-doc", to: config.directories.statusDoc },
+        { from: ".code-helper/user-rules", to: config.directories.userRules },
+        { from: ".code-helper/plan-doc", to: config.directories.planDoc },
+        { from: ".code-helper/result-doc", to: config.directories.resultDoc },
+        { from: ".code-helper/status-doc", to: config.directories.statusDoc }
+    ];
+    const operations = [];
+    for (const migration of migrations) {
+        operations.push(...(await migratePath(projectRoot, migration.from, migration.to)));
+    }
+    await removeEmptyDirectoryIfPossible(projectPath(projectRoot, ".agent"));
+    return operations;
+}
+/**
+ * 迁移一个文件或目录。
+ * 目标不存在时直接 rename；目标存在时递归合并，且遇到同名目标不覆盖。
+ */
+async function migratePath(projectRoot, fromRelativePath, toRelativePath) {
+    const fromPath = projectPath(projectRoot, fromRelativePath);
+    const toPath = projectPath(projectRoot, toRelativePath);
+    const sourceStat = await statIfExists(fromPath);
+    const operations = [];
+    if (sourceStat === undefined) {
+        return operations;
+    }
+    const targetStat = await statIfExists(toPath);
+    if (targetStat === undefined) {
+        await mkdir(dirname(toPath), { recursive: true });
+        await rename(fromPath, toPath);
+        operations.push({
+            path: toPath,
+            action: "updated",
+            message: `已从旧路径迁移：${fromRelativePath}`
+        });
+        return operations;
+    }
+    if (sourceStat.isDirectory() && targetStat.isDirectory()) {
+        const entries = await readdir(fromPath);
+        for (const entry of entries) {
+            operations.push(...(await migratePath(projectRoot, join(fromRelativePath, entry), join(toRelativePath, entry))));
+        }
+        await removeEmptyDirectoryIfPossible(fromPath);
+        return operations;
+    }
+    operations.push({
+        path: fromPath,
+        action: "skipped",
+        message: `迁移目标已存在，为避免覆盖已保留旧路径：${toRelativePath}`
+    });
+    return operations;
+}
+/**
+ * 安全读取路径状态。
+ * 不存在时返回 undefined，其他错误继续抛出。
+ */
+async function statIfExists(path) {
+    try {
+        return await stat(path);
+    }
+    catch (error) {
+        if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+}
+/**
+ * 尝试删除空目录。
+ * 如果目录不存在或非空，保持现状，避免误删用户未知内容。
+ */
+async function removeEmptyDirectoryIfPossible(path) {
+    try {
+        await rmdir(path);
+    }
+    catch {
+        // 目录不存在、非空或被系统占用时都不处理，迁移逻辑不应破坏用户文件。
+    }
+}
+/**
+ * 创建所有固定目录。
+ * 目录创建本身幂等，因此统一标记为 updated，表示已确保存在。
+ */
+async function createDirectories(projectRoot, config, operations) {
+    const directories = [
+        config.directories.workspace,
+        `${config.directories.workspace}/templates`,
+        `${config.directories.workspace}/skills`,
+        `${config.directories.workspace}/hooks`,
+        `${config.directories.workspace}/checks`,
+        `${config.directories.workspace}/archives`,
+        config.directories.userRules,
+        config.directories.planDoc,
+        `${config.directories.planDoc}/archive`,
+        config.directories.resultDoc,
+        `${config.directories.resultDoc}/archive`,
+        config.directories.statusDoc,
+        `${config.directories.statusDoc}/archive`
+    ];
+    for (const directory of directories) {
+        const absolutePath = projectPath(projectRoot, directory);
+        await ensureDirectory(absolutePath);
+        operations.push({
+            path: absolutePath,
+            action: "updated",
+            message: "已确保目录存在"
+        });
+    }
+}
+/**
+ * 安装或更新 AGENTS.md / CLAUDE.md 入口文档。
+ * 已存在文档只替换 code-helper 管理区块，不触碰用户其他内容。
+ */
+async function installEntryDocuments(projectRoot, config) {
+    const operations = [];
+    const entryBlock = renderEntryBlock(config);
+    if (config.entryFiles.agents) {
+        operations.push(await upsertManagedMarkdownBlock(projectPath(projectRoot, "AGENTS.md"), entryBlock));
+    }
+    if (config.entryFiles.claude) {
+        operations.push(await upsertManagedMarkdownBlock(projectPath(projectRoot, "CLAUDE.md"), entryBlock));
+    }
+    return operations;
+}
+/**
+ * 安装专题规则模板。
+ * 老项目已有同名规则时不会覆盖，避免丢失用户维护的规则。
+ */
+async function installRuleTemplates(projectRoot, config) {
+    const operations = [];
+    for (const template of getRuleTemplates(config)) {
+        const targetPath = projectPath(projectRoot, join(config.directories.userRules, template.fileName));
+        operations.push(await upsertMarkdownSection(targetPath, "## 调用入口文件", renderEntryFileList(config), template.content));
+    }
+    return operations;
+}
+/**
+ * 检测用户已经手动创建的入口文件。
+ * 已有入口文件优先代表当前项目实际使用的 agent；完全没有入口文件的新项目才默认维护 AGENTS.md。
+ */
+async function detectEntryFiles(projectRoot, config) {
+    const agentsExists = (await readTextIfExists(projectPath(projectRoot, "AGENTS.md"))) !== undefined;
+    const claudeExists = (await readTextIfExists(projectPath(projectRoot, "CLAUDE.md"))) !== undefined;
+    if (agentsExists || claudeExists) {
+        config.entryFiles.agents = agentsExists;
+        config.entryFiles.claude = claudeExists;
+        return;
+    }
+    if (!config.entryFiles.agents && !config.entryFiles.claude) {
+        config.entryFiles.agents = true;
+    }
+}
+/**
+ * 渲染专题规则中的调用入口文件列表。
+ * 该段会在 init 时同步到已有规则文件，确保手动新增 CLAUDE.md 后规则入口也一致。
+ */
+function renderEntryFileList(config) {
+    const entries = [
+        config.entryFiles.agents ? "- `AGENTS.md`" : undefined,
+        config.entryFiles.claude ? "- `CLAUDE.md`" : undefined
+    ].filter((entry) => entry !== undefined);
+    return entries.join("\n");
+}
+/**
+ * 安装内置 skill 模板副本。
+ * 这些文件是 code-helper 工作区资产，可以在新版本初始化时安全刷新。
+ */
+async function installSkillTemplates(projectRoot, config) {
+    const operations = [];
+    for (const template of getSkillTemplates()) {
+        const targetPath = projectPath(projectRoot, join(config.directories.workspace, "skills", template.fileName));
+        await writeText(targetPath, template.content);
+        operations.push({
+            path: targetPath,
+            action: "updated",
+            message: "已刷新内置 skill 模板"
+        });
+    }
+    return operations;
+}
+/**
+ * 安装可选 hook 模板。
+ * 即使 gitHooks 功能关闭，也只生成 sample 文件，不写入 .git/hooks。
+ */
+async function installHookTemplates(projectRoot, config) {
+    const operations = [];
+    for (const template of getHookTemplates()) {
+        const targetPath = projectPath(projectRoot, join(config.directories.workspace, "hooks", template.fileName));
+        await writeText(targetPath, template.content);
+        operations.push({
+            path: targetPath,
+            action: config.features.gitHooks.enabled ? "updated" : "skipped",
+            message: config.features.gitHooks.enabled
+                ? "已刷新可选 Git hook 模板"
+                : "Git hooks 默认关闭，仅保留 sample 模板"
+        });
+    }
+    return operations;
+}
+/**
+ * 写入 code-helper 状态文件。
+ * 该文件记录工具自身最近一次初始化状态，不替代业务项目 status-doc。
+ */
+async function writeStateFile(projectRoot, config) {
+    const enabledFeatures = FEATURE_KEYS.filter((feature) => config.features[feature].enabled);
+    const targetPath = projectPath(projectRoot, `${config.directories.workspace}/state.json`);
+    const state = {
+        initializedAt: new Date().toISOString(),
+        enabledFeatures,
+        note: "此文件由 code-helper 维护，仅记录工具状态，不承载业务项目状态。"
+    };
+    await writeText(targetPath, `${JSON.stringify(state, null, 2)}\n`);
+    return {
+        path: targetPath,
+        action: "updated",
+        message: "已刷新 code-helper 运行状态"
+    };
+}
+//# sourceMappingURL=init.js.map

package/dist/init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"init.js","sourceRoot":"","sources":["../src/init.ts"],"names":[],"mappings":"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"}

package/dist/input-utils.d.ts

@@ -0,0 +1,5 @@
+/**
+ * 解析用户输入或终端拖拽产生的文件路径。
+ * 终端拖拽通常会粘贴引号、反斜杠转义空格或 file:// URL，这里统一归一化。
+ */
+export declare function normalizeDroppedPath(input: string, projectRoot: string): string;

package/dist/input-utils.js

@@ -0,0 +1,94 @@
+import { isAbsolute, relative, resolve, win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * 解析用户输入或终端拖拽产生的文件路径。
+ * 终端拖拽通常会粘贴引号、反斜杠转义空格或 file:// URL，这里统一归一化。
+ */
+export function normalizeDroppedPath(input, projectRoot) {
+    const cleanedInput = stripWrappingQuotes(input.trim());
+    const decodedPath = cleanedInput.startsWith("file://")
+        ? decodeFileUrlPath(cleanedInput)
+        : decodePlainPath(cleanedInput);
+    const normalizedPath = decodedPath.trim();
+    if (isWindowsAbsolutePath(normalizedPath)) {
+        const relativePath = win32.relative(win32.resolve(projectRoot), win32.normalize(normalizedPath));
+        if (isProjectRelativePath(relativePath, "\\")) {
+            return relativePath;
+        }
+        return normalizedPath;
+    }
+    if (isWindowsAbsolutePath(projectRoot) && isWindowsPathLike(normalizedPath)) {
+        return normalizedPath;
+    }
+    if (isAbsolute(normalizedPath)) {
+        const relativePath = relative(resolve(projectRoot), normalizedPath);
+        if (isProjectRelativePath(relativePath, "/")) {
+            return relativePath;
+        }
+    }
+    return normalizedPath;
+}
+/**
+ * 去掉拖拽路径外层可能出现的单引号或双引号。
+ */
+function stripWrappingQuotes(value) {
+    if ((value.startsWith("'") && value.endsWith("'")) ||
+        (value.startsWith("\"") && value.endsWith("\""))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+/**
+ * 解析 file:// URL。
+ * Windows 终端可能粘贴 file:///C:/...，在非 Windows 测试环境下需要保留 C: 盘符形态，避免变成 /C:/...。
+ */
+function decodeFileUrlPath(value) {
+    const url = new URL(value);
+    const decodedPath = decodeURIComponent(url.pathname);
+    if (/^\/[A-Za-z]:\//u.test(decodedPath)) {
+        return decodedPath.slice(1).replace(/\//gu, "\\");
+    }
+    return fileURLToPath(value);
+}
+/**
+ * 解析普通路径输入。
+ * Windows 路径中的反斜杠是路径分隔符，不能按 POSIX shell 转义处理。
+ */
+function decodePlainPath(value) {
+    if (isWindowsPathLike(value)) {
+        return value;
+    }
+    return unescapeShellPath(value);
+}
+/**
+ * 处理 shell 风格反斜杠转义。
+ * 只移除反斜杠本身，保留被转义字符，例如 a\ b.md -> a b.md。
+ */
+function unescapeShellPath(value) {
+    return value.replace(/\\(.)/gu, "$1");
+}
+/**
+ * 判断是否是 Windows 绝对路径。
+ * 同时支持盘符路径和 UNC 网络路径。
+ */
+function isWindowsAbsolutePath(value) {
+    return /^[A-Za-z]:[\\/]/u.test(value) || /^\\\\/u.test(value);
+}
+/**
+ * 判断是否看起来像 Windows 路径。
+ * 相对路径 docs\需求.md 也要保留反斜杠，不能当成 shell 转义。
+ */
+function isWindowsPathLike(value) {
+    if (value.startsWith("/")) {
+        return false;
+    }
+    return /^[A-Za-z]:[\\/]/u.test(value) || /^\\\\/u.test(value) || /\\\S/u.test(value);
+}
+/**
+ * 判断绝对路径是否位于项目目录下。
+ * 空字符串表示就是项目根目录，不能作为需求文档路径返回。
+ */
+function isProjectRelativePath(value, separator) {
+    return value !== "" && value !== ".." && !value.startsWith(`..${separator}`);
+}
+//# sourceMappingURL=input-utils.js.map

package/dist/input-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"input-utils.js","sourceRoot":"","sources":["../src/input-utils.ts"],"names":[],"mappings":"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"}

package/dist/skills.d.ts

@@ -0,0 +1,41 @@
+import type { OperationResult } from "./types.js";
+/**
+ * 当前支持的项目级 skill 注册目标。
+ * codex 写入 `.agents/skills`，claudecode 写入 `.claude/skills`。
+ */
+export type SkillRegistrationTarget = "codex" | "claudecode";
+/**
+ * 单个项目级 skill 的注册状态。
+ * CLI 用它展示当前项目是否已经注册 code-helper skills。
+ */
+export interface SkillRegistrationStatus {
+    target: SkillRegistrationTarget;
+    name: string;
+    path: string;
+    registered: boolean;
+}
+/**
+ * 注册 code-helper 内置 skills 到当前项目。
+ * 注册结果按目标写入 `.agents/skills` 或 `.claude/skills`，只影响当前项目。
+ */
+export declare function registerProjectSkills(projectRoot: string, target?: SkillRegistrationTarget): Promise<OperationResult[]>;
+/**
+ * 取消注册 code-helper 项目级 skills。
+ * 只删除 `.agents/skills/code-helper-*` 或 `.claude/skills/code-helper-*` 受控目录，不触碰用户自己的 skills。
+ */
+export declare function unregisterProjectSkills(projectRoot: string, target?: SkillRegistrationTarget): Promise<OperationResult[]>;
+/**
+ * 查看 code-helper 项目级 skills 注册状态。
+ * 该函数只检查 code-helper 管理的 skill 名称，不扫描用户自定义 skills。
+ */
+export declare function listProjectSkillRegistrations(projectRoot: string, target?: SkillRegistrationTarget): Promise<SkillRegistrationStatus[]>;
+/**
+ * 解析 CLI 输入中的注册目标。
+ * 不带值时只返回 Codex；交互命令的“按当前项目注册”会使用 resolveSkillRegistrationTargets 单独推断。
+ */
+export declare function parseSkillRegistrationTargets(value: string | undefined): SkillRegistrationTarget[];
+/**
+ * 根据当前项目实际入口文件推断需要注册的 agent 工具。
+ * 根目录已有 AGENTS.md 或 CLAUDE.md 时，以这些文件作为实际使用状态；完全没有入口文件的新项目默认注册全部。
+ */
+export declare function resolveSkillRegistrationTargets(projectRoot: string): Promise<SkillRegistrationTarget[]>;

package/dist/skills.js

@@ -0,0 +1,201 @@
+import { readdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { loadConfig } from "./config.js";
+import { projectPath, readTextIfExists, writeText } from "./fs-utils.js";
+import { getSkillTemplates } from "./templates.js";
+/**
+ * 所有支持的注册目标。
+ * 显式传入 all 时才会使用完整列表，避免默认行为误注册未使用的 agent 工具。
+ */
+const ALL_SKILL_REGISTRATION_TARGETS = ["codex", "claudecode"];
+/**
+ * code-helper 内置 skill 到项目级目录的映射。
+ * directoryName 使用 skill frontmatter 中的 name，便于不同 agent 工具直接识别。
+ */
+const CODE_HELPER_SKILL_REGISTRATIONS = [
+    {
+        templateFileName: "memory-tuning.SKILL.md",
+        directoryName: "code-helper-memory-tuning"
+    },
+    {
+        templateFileName: "plan-workbench.SKILL.md",
+        directoryName: "code-helper-plan-workbench"
+    },
+    {
+        templateFileName: "document-archive.SKILL.md",
+        directoryName: "code-helper-document-archive"
+    }
+];
+/**
+ * Codex 项目级 skills 根目录。
+ * 该目录只影响当前项目，不会注册到用户全局 skills。
+ */
+const CODEX_PROJECT_SKILLS_DIRECTORY = ".agents/skills";
+/**
+ * Claude Code 项目级 skills 根目录。
+ * 该目录只影响当前项目，不会注册到用户全局 `~/.claude/skills`。
+ */
+const CLAUDE_CODE_PROJECT_SKILLS_DIRECTORY = ".claude/skills";
+/**
+ * 注册 code-helper 内置 skills 到当前项目。
+ * 注册结果按目标写入 `.agents/skills` 或 `.claude/skills`，只影响当前项目。
+ */
+export async function registerProjectSkills(projectRoot, target = "codex") {
+    assertSupportedTarget(target);
+    const config = await loadConfig(projectRoot);
+    if (!config.features.skillRegistration.enabled) {
+        throw new Error("Skills 管理功能已关闭，请先执行 `code-helper features enable skillRegistration`。");
+    }
+    const operations = [];
+    const templates = getSkillTemplates();
+    for (const registration of CODE_HELPER_SKILL_REGISTRATIONS) {
+        const template = templates.find((item) => item.fileName === registration.templateFileName);
+        if (template === undefined) {
+            throw new Error(`缺少内置 skill 模板：${registration.templateFileName}`);
+        }
+        const targetPath = getSkillFilePath(projectRoot, target, registration.directoryName);
+        const existing = await readTextIfExists(targetPath);
+        if (existing === template.content) {
+            operations.push({
+                path: targetPath,
+                action: "skipped",
+                message: "项目级 skill 已是最新内容"
+            });
+            continue;
+        }
+        await writeText(targetPath, template.content);
+        operations.push({
+            path: targetPath,
+            action: existing === undefined ? "created" : "updated",
+            message: `已注册 ${formatTargetName(target)} 项目级 skill`
+        });
+    }
+    return operations;
+}
+/**
+ * 取消注册 code-helper 项目级 skills。
+ * 只删除 `.agents/skills/code-helper-*` 或 `.claude/skills/code-helper-*` 受控目录，不触碰用户自己的 skills。
+ */
+export async function unregisterProjectSkills(projectRoot, target = "codex") {
+    assertSupportedTarget(target);
+    const operations = [];
+    for (const registration of CODE_HELPER_SKILL_REGISTRATIONS) {
+        const targetDirectory = projectPath(projectRoot, join(getProjectSkillsDirectory(target), registration.directoryName));
+        const targetPath = join(targetDirectory, "SKILL.md");
+        const existing = await readTextIfExists(targetPath);
+        if (existing === undefined) {
+            operations.push({
+                path: targetPath,
+                action: "skipped",
+                message: "项目级 skill 未注册"
+            });
+            continue;
+        }
+        await rm(targetDirectory, { recursive: true, force: true });
+        operations.push({
+            path: targetDirectory,
+            action: "updated",
+            message: `已取消注册 ${formatTargetName(target)} 项目级 skill`
+        });
+    }
+    const targetRoot = getProjectSkillsDirectory(target);
+    await removeEmptyDirectory(projectPath(projectRoot, targetRoot));
+    await removeEmptyDirectory(projectPath(projectRoot, dirname(targetRoot)));
+    return operations;
+}
+/**
+ * 查看 code-helper 项目级 skills 注册状态。
+ * 该函数只检查 code-helper 管理的 skill 名称，不扫描用户自定义 skills。
+ */
+export async function listProjectSkillRegistrations(projectRoot, target = "codex") {
+    assertSupportedTarget(target);
+    const statuses = [];
+    for (const registration of CODE_HELPER_SKILL_REGISTRATIONS) {
+        const targetPath = getSkillFilePath(projectRoot, target, registration.directoryName);
+        statuses.push({
+            target,
+            name: registration.directoryName,
+            path: targetPath,
+            registered: (await readTextIfExists(targetPath)) !== undefined
+        });
+    }
+    return statuses;
+}
+/**
+ * 解析 CLI 输入中的注册目标。
+ * 不带值时只返回 Codex；交互命令的“按当前项目注册”会使用 resolveSkillRegistrationTargets 单独推断。
+ */
+export function parseSkillRegistrationTargets(value) {
+    if (value === undefined || value === "" || value === "codex") {
+        return ["codex"];
+    }
+    if (value === "claudecode" || value === "claude-code" || value === "claude") {
+        return ["claudecode"];
+    }
+    if (value === "all") {
+        return [...ALL_SKILL_REGISTRATION_TARGETS];
+    }
+    throw new Error(`不支持的 skills 注册目标：${value}。当前支持 codex、claudecode 或 all。`);
+}
+/**
+ * 根据当前项目实际入口文件推断需要注册的 agent 工具。
+ * 根目录已有 AGENTS.md 或 CLAUDE.md 时，以这些文件作为实际使用状态；完全没有入口文件的新项目默认注册全部。
+ */
+export async function resolveSkillRegistrationTargets(projectRoot) {
+    const agentsExists = (await readTextIfExists(projectPath(projectRoot, "AGENTS.md"))) !== undefined;
+    const claudeExists = (await readTextIfExists(projectPath(projectRoot, "CLAUDE.md"))) !== undefined;
+    const targets = [];
+    if (agentsExists || claudeExists) {
+        if (agentsExists) {
+            targets.push("codex");
+        }
+        if (claudeExists) {
+            targets.push("claudecode");
+        }
+        return targets;
+    }
+    return [...ALL_SKILL_REGISTRATION_TARGETS];
+}
+/**
+ * 返回项目级 SKILL.md 绝对路径。
+ */
+function getSkillFilePath(projectRoot, target, directoryName) {
+    return projectPath(projectRoot, join(getProjectSkillsDirectory(target), directoryName, "SKILL.md"));
+}
+/**
+ * 校验注册目标。
+ * 这个函数让公开 API 即使传入非字面量字符串也能得到明确错误。
+ */
+function assertSupportedTarget(target) {
+    if (target !== "codex" && target !== "claudecode") {
+        throw new Error(`不支持的 skills 注册目标：${target}。当前支持 codex 或 claudecode。`);
+    }
+}
+/**
+ * 返回不同 agent 工具的项目级 skills 目录。
+ */
+function getProjectSkillsDirectory(target) {
+    return target === "codex" ? CODEX_PROJECT_SKILLS_DIRECTORY : CLAUDE_CODE_PROJECT_SKILLS_DIRECTORY;
+}
+/**
+ * 返回面向用户展示的 agent 工具名称。
+ */
+function formatTargetName(target) {
+    return target === "codex" ? "Codex" : "Claude Code";
+}
+/**
+ * 删除空目录。
+ * 目录不存在或非空时保持现状，避免误删用户自定义 skills。
+ */
+async function removeEmptyDirectory(path) {
+    try {
+        const entries = await readdir(path);
+        if (entries.length === 0) {
+            await rm(path, { recursive: false, force: true });
+        }
+    }
+    catch {
+        // 目录不存在或不可删除时不处理，取消注册不应影响用户文件。
+    }
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}