@ruan-cat/vitepress-preset-config 2.9.0 → 2.11.0

package/dist/config.d.mts

@@ -52,31 +52,37 @@ interface ExtraConfig {
 declare function copyReadmeMd(/** 目标文件夹 */ target: string): void;
 
 /**
- * 将 .claude/agents 文件夹复制到指定位置的配置选项
+ * Claude 文件夹名称类型
  */
-interface CopyClaudeAgentsOptions {
+type ClaudeFolderName = "agents" | "commands";
+/**
+ * 将 .claude 相关文件夹复制到指定位置的配置选项
+ */
+interface CopyClaudeFilesOptions {
     /**
-     * 目标文件夹路径（必须是相对路径，相对于当前工作目录）
+     * 目标父文件夹路径（必须是相对路径，相对于当前工作目录）
      * @description
      * **重要**：此参数仅接受相对路径，不接受绝对路径（禁止以 `/` 或盘符如 `C:\` 开头）。
      * 使用绝对路径会抛出错误，这是为了防止意外覆盖系统目录。
      *
      * 该地址是写相对路径的 不能写绝对路径，容易导致意外。
      * vitepress 命令运行在 apps/admin 目录内，该地址是相对于该运行目录的。
-     * 比如期望将 `.claude/agents` 复制到 `apps/admin/src/docs/prompts/agents` 文件夹。
-     * 则写 `src/docs/prompts/agents` 即可。
+     * 比如期望将 `.claude/agents` 和 `.claude/commands` 复制到 `apps/admin/src/docs/prompts/` 文件夹下。
+     * 则写 `src/docs/prompts` 即可，最终会生成：
+     *   - `apps/admin/src/docs/prompts/agents/`
+     *   - `apps/admin/src/docs/prompts/commands/`
      *
      * @throws {Error} 当传入绝对路径时抛出错误
      * @example
      * // ✅ 正确：相对路径
-     * "src/docs/prompts/agents"
-     * "dist/agents"
+     * "src/docs/prompts"
+     * "dist"
      * "./public/claude"
      *
      * @example
      * // ❌ 错误：绝对路径（会抛出错误）
-     * "/var/www/agents"           // Unix 绝对路径
-     * "C:\\Users\\agents"         // Windows 绝对路径
+     * "/var/www/claude"           // Unix 绝对路径
+     * "C:\\Users\\claude"         // Windows 绝对路径
      */
     target: string;
     /**
@@ -93,39 +99,64 @@ interface CopyClaudeAgentsOptions {
      * '/absolute/path/to/monorepo'
      */
     rootDir?: string;
+    /**
+     * 要复制的 Claude 文件夹列表
+     * @description
+     * 指定要复制的文件夹名称数组。如果不传入，默认复制所有文件夹（'agents' 和 'commands'）。
+     * 对于不存在的文件夹，会打印警告并跳过，不会影响其他文件夹的复制。
+     *
+     * @default ['agents', 'commands']
+     * @example
+     * // 只复制 agents 文件夹
+     * items: ['agents']
+     *
+     * // 只复制 commands 文件夹
+     * items: ['commands']
+     *
+     * // 复制所有文件夹（默认行为）
+     * items: ['agents', 'commands']
+     */
+    items?: ClaudeFolderName[];
 }
 /**
- * 将 .claude/agents 文件夹复制到指定位置
+ * 将 .claude 相关文件夹（agents 和 commands）复制到指定位置
  * @param options - 配置选项
  * @throws {Error} 当 `options.target` 为绝对路径时抛出错误
  * @description
- * 该函数相当于实现 `cpx .claude/agents <target>` 命令。
- * 从根目录的 .claude/agents 复制到目标位置。
+ * 该函数会将指定的 `.claude` 文件夹（默认为 `agents` 和 `commands`）复制到目标位置的子目录中。
+ * 从根目录的 .claude 文件夹复制到目标位置，自动创建对应的子文件夹。
  *
  * **安全限制**：`target` 参数必须是相对路径，禁止使用绝对路径，以防止意外覆盖系统目录。
  *
  * @example
- * // ✅ 自动检测 monorepo 根目录，复制到当前目录的 dist 文件夹
- * copyClaudeAgents({ target: 'dist' })
+ * // ✅ 自动检测 monorepo 根目录，复制所有文件夹到当前目录的 dist 文件夹
+ * // 会生成：dist/agents/ 和 dist/commands/
+ * copyClaudeFiles({ target: 'dist' })
+ *
+ * // ✅ 只复制 agents 文件夹
+ * copyClaudeFiles({
+ *   target: 'dist',
+ *   items: ['agents']
+ * })
  *
  * // ✅ 手动指定根目录为向上三级，复制到 build 文件夹
- * copyClaudeAgents({
+ * copyClaudeFiles({
  *   target: 'build',
  *   rootDir: '../../../'
  * })
  *
  * // ✅ 使用绝对路径指定根目录（rootDir 允许绝对路径）
- * copyClaudeAgents({
+ * copyClaudeFiles({
  *   target: 'dist',  // target 必须是相对路径
  *   rootDir: '/absolute/path/to/monorepo'  // rootDir 可以是绝对路径
  * })
  *
  * @example
  * // ❌ 错误用法：target 使用绝对路径会抛出错误
- * copyClaudeAgents({ target: '/var/www/agents' })  // 抛出 Error
- * copyClaudeAgents({ target: 'C:\\Windows\\agents' })  // 抛出 Error
+ * copyClaudeFiles({ target: '/var/www/claude' })  // 抛出 Error
+ * copyClaudeFiles({ target: 'C:\\Windows\\claude' })  // 抛出 Error
  */
-declare function copyClaudeAgents(options: CopyClaudeAgentsOptions): void;
+declare function copyClaudeFiles(options: CopyClaudeFilesOptions): void;
 
 interface AddChangelog2docOptions<T extends Record<string, any> = Record<string, any>> {
     /** 目标文件夹 */
@@ -145,4 +176,4 @@ declare function setGenerateSidebar(options?: VitePressSidebarOptions): vitepres
 /** 设置vitepress主配置 */
 declare function setUserConfig(config?: UserConfig<DefaultTheme.Config>, extraConfig?: ExtraConfig): UserConfig<DefaultTheme.Config>;
 
-export { addChangelog2doc, copyClaudeAgents, copyReadmeMd, setGenerateSidebar, setUserConfig };
+export { addChangelog2doc, copyClaudeFiles, copyReadmeMd, setGenerateSidebar, setUserConfig };

package/dist/config.mjs

@@ -56,7 +56,7 @@ function copyReadmeMd(target) {
   fs.copyFileSync(source, destination);
 }
 
-// src/config/copy-claude-agents.ts
+// src/config/copy-claude-files.ts
 import fs2 from "fs";
 import path2 from "path";
 import consola2 from "consola";
@@ -86,35 +86,44 @@ function resolveRootDir(rootDir) {
   }
   return process.cwd();
 }
-function hasClaudeAgents(options) {
+function hasClaudeFolder(folderPath, options) {
   const root = resolveRootDir(options == null ? void 0 : options.rootDir);
-  const claudeAgentsPath = path2.join(root, ".claude/agents");
-  const exists = fs2.existsSync(claudeAgentsPath);
+  const claudeFolderPath = path2.join(root, folderPath);
+  const exists = fs2.existsSync(claudeFolderPath);
   if (!exists) {
     consola2.log("\u68C0\u6D4B\u7684\u6839\u76EE\u5F55\u4E3A\uFF1A", root);
-    consola2.warn("\u8BE5\u6839\u76EE\u5F55\u4E0D\u5B58\u5728 .claude/agents \u6587\u4EF6\u5939");
+    consola2.warn(`\u8BE5\u6839\u76EE\u5F55\u4E0D\u5B58\u5728 ${folderPath} \u6587\u4EF6\u5939`);
   }
   return exists;
 }
-function copyClaudeAgents(options) {
+function copyClaudeFiles(options) {
   if (path2.isAbsolute(options.target)) {
     const errorMessage = [
       `target \u53C2\u6570\u4E0D\u5141\u8BB8\u4F7F\u7528\u7EDD\u5BF9\u8DEF\u5F84\uFF0C\u8FD9\u53EF\u80FD\u5BFC\u81F4\u610F\u5916\u7684\u6587\u4EF6\u8986\u76D6\u3002`,
       `\u5F53\u524D\u4F20\u5165\u7684\u8DEF\u5F84: "${options.target}"`,
-      `\u8BF7\u4F7F\u7528\u76F8\u5BF9\u8DEF\u5F84\uFF0C\u4F8B\u5982: "src/docs/prompts/agents"`
+      `\u8BF7\u4F7F\u7528\u76F8\u5BF9\u8DEF\u5F84\uFF0C\u4F8B\u5982: "src/docs/prompts"`
     ].join("\n");
     consola2.error(errorMessage);
     throw new Error(errorMessage);
   }
-  if (!hasClaudeAgents({ rootDir: options.rootDir })) {
-    return;
-  }
   const root = resolveRootDir(options.rootDir);
-  const source = path2.join(root, ".claude/agents");
-  const destination = path2.resolve(process.cwd(), options.target);
-  fs2.mkdirSync(path2.dirname(destination), { recursive: true });
-  fs2.cpSync(source, destination, { recursive: true });
-  consola2.success(`\u5DF2\u6210\u529F\u590D\u5236 .claude/agents \u5230 ${destination}`);
+  const itemsToProcess = options.items ?? ["agents", "commands"];
+  let successCount = 0;
+  for (const folderName of itemsToProcess) {
+    const claudeFolderPath = `.claude/${folderName}`;
+    if (!hasClaudeFolder(claudeFolderPath, { rootDir: options.rootDir })) {
+      continue;
+    }
+    const source = path2.join(root, claudeFolderPath);
+    const destination = path2.resolve(process.cwd(), options.target, folderName);
+    fs2.mkdirSync(path2.dirname(destination), { recursive: true });
+    fs2.cpSync(source, destination, { recursive: true });
+    consola2.success(`\u5DF2\u6210\u529F\u590D\u5236 ${claudeFolderPath} \u5230 ${destination}`);
+    successCount++;
+  }
+  if (successCount === 0) {
+    consola2.warn("\u6CA1\u6709\u6210\u529F\u590D\u5236\u4EFB\u4F55 .claude \u6587\u4EF6\u5939");
+  }
 }
 
 // src/config/add-changelog-to-doc.ts
@@ -532,7 +541,7 @@ function setUserConfig(config, extraConfig) {
 }
 export {
   addChangelog2doc,
-  copyClaudeAgents,
+  copyClaudeFiles,
   copyReadmeMd,
   defineConfig,
   setGenerateSidebar,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruan-cat/vitepress-preset-config",
-  "version": "2.9.0",
+  "version": "2.11.0",
   "description": "用于给大多数的vitepress项目提供一个预设的配置文件。",
   "homepage": "https://vitepress-preset.ruancat6312.top",
   "types": "./src/config.mts",
@@ -19,7 +19,7 @@
     "vitepress-sidebar": "^1.33.0",
     "vitepress-theme-teek": "^1.4.6",
     "vue": "^3.5.21",
-    "@ruan-cat/utils": "^4.15.0"
+    "@ruan-cat/utils": "^4.16.0"
   },
   "devDependencies": {
     "@types/lodash-es": "^4.17.12",
@@ -77,23 +77,17 @@
     "registry": "https://registry.npmjs.org/",
     "tag": "beta"
   },
-  "typesVersions": {
-    "*": {
-      "*": [
-        "./dist/*",
-        "./*"
-      ]
-    }
-  },
   "files": [
     "!**/.vercel/**",
-    "dist",
+    "!**/.vitepress/**",
     "src",
-    "!src/docs/**",
-    "!src/**/tests",
-    "!src/**/*.md",
-    "!src/.vitepress/cache",
-    "!src/.vitepress/dist"
+    "dist/**",
+    "tsconfig.json",
+    "README.md",
+    "!src/**/docs/**",
+    "!src/**/tests/**",
+    "!*.test.*",
+    "!src/**/*.md"
   ],
   "scripts": {
     "docs:dev": "vitepress dev src/docs --port 8080",

package/src/config/{copy-claude-agents.ts → copy-claude-files.ts}

@@ -2,6 +2,11 @@ import fs from "node:fs";
 import path from "node:path";
 import consola from "consola";
 
+/**
+ * Claude 文件夹名称类型
+ */
+export type ClaudeFolderName = "agents" | "commands";
+
 /**
  * 从当前工作目录向上查找 monorepo 根目录
  * @returns monorepo 根目录的绝对路径，如果找不到则返回 null
@@ -57,61 +62,56 @@ function resolveRootDir(rootDir?: string): string {
 }
 
 /**
- * 检查指定根目录是否存在 .claude/agents 文件夹
+ * 检查指定根目录是否存在指定的 Claude 文件夹
+ * @param folderPath - Claude 文件夹的相对路径（如 '.claude/agents' 或 '.claude/commands'）
  * @param options - 配置选项
  * @param options.rootDir - 可选的根目录路径，支持相对路径（如 `../../../` 表示向上三级目录）。
  *                          如果不传入，将自动向上查找包含 pnpm-workspace.yaml 的 monorepo 根目录。
  *                          相对路径会基于当前工作目录 (process.cwd()) 解析为绝对路径。
- * @returns 是否存在 .claude/agents 文件夹
- * @example
- * // 自动检测 monorepo 根目录
- * hasClaudeAgents()
- *
- * // 手动指定相对路径（从当前工作目录向上三级）
- * hasClaudeAgents({ rootDir: '../../../' })
- *
- * // 手动指定绝对路径
- * hasClaudeAgents({ rootDir: '/path/to/monorepo' })
+ * @returns 是否存在指定的 Claude 文件夹
+ * @internal 该函数为内部使用，不对外暴露
  */
-function hasClaudeAgents(options?: { rootDir?: string }): boolean {
+function hasClaudeFolder(folderPath: string, options?: { rootDir?: string }): boolean {
 	const root = resolveRootDir(options?.rootDir);
-	const claudeAgentsPath = path.join(root, ".claude/agents");
-	const exists = fs.existsSync(claudeAgentsPath);
+	const claudeFolderPath = path.join(root, folderPath);
+	const exists = fs.existsSync(claudeFolderPath);
 
 	if (!exists) {
 		consola.log("检测的根目录为：", root);
-		consola.warn("该根目录不存在 .claude/agents 文件夹");
+		consola.warn(`该根目录不存在 ${folderPath} 文件夹`);
 	}
 
 	return exists;
 }
 
 /**
- * 将 .claude/agents 文件夹复制到指定位置的配置选项
+ * 将 .claude 相关文件夹复制到指定位置的配置选项
  */
-export interface CopyClaudeAgentsOptions {
+export interface CopyClaudeFilesOptions {
 	/**
-	 * 目标文件夹路径（必须是相对路径，相对于当前工作目录）
+	 * 目标父文件夹路径（必须是相对路径，相对于当前工作目录）
 	 * @description
 	 * **重要**：此参数仅接受相对路径，不接受绝对路径（禁止以 `/` 或盘符如 `C:\` 开头）。
 	 * 使用绝对路径会抛出错误，这是为了防止意外覆盖系统目录。
 	 *
 	 * 该地址是写相对路径的 不能写绝对路径，容易导致意外。
 	 * vitepress 命令运行在 apps/admin 目录内，该地址是相对于该运行目录的。
-	 * 比如期望将 `.claude/agents` 复制到 `apps/admin/src/docs/prompts/agents` 文件夹。
-	 * 则写 `src/docs/prompts/agents` 即可。
+	 * 比如期望将 `.claude/agents` 和 `.claude/commands` 复制到 `apps/admin/src/docs/prompts/` 文件夹下。
+	 * 则写 `src/docs/prompts` 即可，最终会生成：
+	 *   - `apps/admin/src/docs/prompts/agents/`
+	 *   - `apps/admin/src/docs/prompts/commands/`
 	 *
 	 * @throws {Error} 当传入绝对路径时抛出错误
 	 * @example
 	 * // ✅ 正确：相对路径
-	 * "src/docs/prompts/agents"
-	 * "dist/agents"
+	 * "src/docs/prompts"
+	 * "dist"
 	 * "./public/claude"
 	 *
 	 * @example
 	 * // ❌ 错误：绝对路径（会抛出错误）
-	 * "/var/www/agents"           // Unix 绝对路径
-	 * "C:\\Users\\agents"         // Windows 绝对路径
+	 * "/var/www/claude"           // Unix 绝对路径
+	 * "C:\\Users\\claude"         // Windows 绝对路径
 	 */
 	target: string;
 
@@ -129,66 +129,112 @@ export interface CopyClaudeAgentsOptions {
 	 * '/absolute/path/to/monorepo'
 	 */
 	rootDir?: string;
+
+	/**
+	 * 要复制的 Claude 文件夹列表
+	 * @description
+	 * 指定要复制的文件夹名称数组。如果不传入，默认复制所有文件夹（'agents' 和 'commands'）。
+	 * 对于不存在的文件夹，会打印警告并跳过，不会影响其他文件夹的复制。
+	 *
+	 * @default ['agents', 'commands']
+	 * @example
+	 * // 只复制 agents 文件夹
+	 * items: ['agents']
+	 *
+	 * // 只复制 commands 文件夹
+	 * items: ['commands']
+	 *
+	 * // 复制所有文件夹（默认行为）
+	 * items: ['agents', 'commands']
+	 */
+	items?: ClaudeFolderName[];
 }
 
 /**
- * 将 .claude/agents 文件夹复制到指定位置
+ * 将 .claude 相关文件夹（agents 和 commands）复制到指定位置
  * @param options - 配置选项
  * @throws {Error} 当 `options.target` 为绝对路径时抛出错误
  * @description
- * 该函数相当于实现 `cpx .claude/agents <target>` 命令。
- * 从根目录的 .claude/agents 复制到目标位置。
+ * 该函数会将指定的 `.claude` 文件夹（默认为 `agents` 和 `commands`）复制到目标位置的子目录中。
+ * 从根目录的 .claude 文件夹复制到目标位置，自动创建对应的子文件夹。
  *
  * **安全限制**：`target` 参数必须是相对路径，禁止使用绝对路径，以防止意外覆盖系统目录。
  *
  * @example
- * // ✅ 自动检测 monorepo 根目录，复制到当前目录的 dist 文件夹
- * copyClaudeAgents({ target: 'dist' })
+ * // ✅ 自动检测 monorepo 根目录，复制所有文件夹到当前目录的 dist 文件夹
+ * // 会生成：dist/agents/ 和 dist/commands/
+ * copyClaudeFiles({ target: 'dist' })
+ *
+ * // ✅ 只复制 agents 文件夹
+ * copyClaudeFiles({
+ *   target: 'dist',
+ *   items: ['agents']
+ * })
  *
  * // ✅ 手动指定根目录为向上三级，复制到 build 文件夹
- * copyClaudeAgents({
+ * copyClaudeFiles({
  *   target: 'build',
  *   rootDir: '../../../'
  * })
  *
  * // ✅ 使用绝对路径指定根目录（rootDir 允许绝对路径）
- * copyClaudeAgents({
+ * copyClaudeFiles({
  *   target: 'dist',  // target 必须是相对路径
  *   rootDir: '/absolute/path/to/monorepo'  // rootDir 可以是绝对路径
  * })
  *
  * @example
  * // ❌ 错误用法：target 使用绝对路径会抛出错误
- * copyClaudeAgents({ target: '/var/www/agents' })  // 抛出 Error
- * copyClaudeAgents({ target: 'C:\\Windows\\agents' })  // 抛出 Error
+ * copyClaudeFiles({ target: '/var/www/claude' })  // 抛出 Error
+ * copyClaudeFiles({ target: 'C:\\Windows\\claude' })  // 抛出 Error
  */
-export function copyClaudeAgents(options: CopyClaudeAgentsOptions): void {
+export function copyClaudeFiles(options: CopyClaudeFilesOptions): void {
 	// 验证 target 不能是绝对路径
 	if (path.isAbsolute(options.target)) {
 		const errorMessage = [
 			`target 参数不允许使用绝对路径，这可能导致意外的文件覆盖。`,
 			`当前传入的路径: "${options.target}"`,
-			`请使用相对路径，例如: "src/docs/prompts/agents"`,
+			`请使用相对路径，例如: "src/docs/prompts"`,
 		].join("\n");
 
 		consola.error(errorMessage);
 		throw new Error(errorMessage);
 	}
 
-	// 检查源目录是否存在
-	if (!hasClaudeAgents({ rootDir: options.rootDir })) {
-		return;
-	}
-
 	const root = resolveRootDir(options.rootDir);
-	const source = path.join(root, ".claude/agents");
-	const destination = path.resolve(process.cwd(), options.target);
 
-	// 确保目标文件夹的父目录存在
-	fs.mkdirSync(path.dirname(destination), { recursive: true });
+	// 确定要处理的文件夹列表，默认为所有文件夹
+	const itemsToProcess = options.items ?? ["agents", "commands"];
 
-	// 递归复制文件夹
-	fs.cpSync(source, destination, { recursive: true });
+	// 记录成功复制的文件夹数量
+	let successCount = 0;
+
+	// 遍历每个要处理的文件夹
+	for (const folderName of itemsToProcess) {
+		const claudeFolderPath = `.claude/${folderName}`;
+
+		// 使用 hasClaudeFolder 检查文件夹是否存在
+		// 如果不存在，hasClaudeFolder 会自动打印警告
+		if (!hasClaudeFolder(claudeFolderPath, { rootDir: options.rootDir })) {
+			continue; // 跳过不存在的文件夹
+		}
 
-	consola.success(`已成功复制 .claude/agents 到 ${destination}`);
+		// 构建源路径和目标路径
+		const source = path.join(root, claudeFolderPath);
+		const destination = path.resolve(process.cwd(), options.target, folderName);
+
+		// 确保目标文件夹的父目录存在
+		fs.mkdirSync(path.dirname(destination), { recursive: true });
+
+		// 递归复制文件夹
+		fs.cpSync(source, destination, { recursive: true });
+
+		consola.success(`已成功复制 ${claudeFolderPath} 到 ${destination}`);
+		successCount++;
+	}
+
+	// 如果没有成功复制任何文件夹，给出提示
+	if (successCount === 0) {
+		consola.warn("没有成功复制任何 .claude 文件夹");
+	}
 }

package/src/config/index.ts

@@ -2,7 +2,7 @@
 
 export * from "./page-order-config";
 export * from "./copy-readme";
-export * from "./copy-claude-agents";
+export * from "./copy-claude-files";
 export * from "./add-changelog-to-doc";
 export * from "./plugins";
 export * from "./changelog-nav";

package/src/config.mts

@@ -9,9 +9,7 @@ import { merge, isUndefined, cloneDeep } from "lodash-es";
 import consola from "consola";
 import type { ExtraConfig } from "./types.ts";
 
-// import { addChangelog2doc, copyReadmeMd, copyClaudeAgents } from "@ruan-cat/utils/node-esm";
-import { addChangelog2doc, copyReadmeMd, copyClaudeAgents } from "./config/index.ts";
-export { addChangelog2doc, copyReadmeMd, copyClaudeAgents };
+export { addChangelog2doc, copyReadmeMd, copyClaudeFiles } from "./config/index.ts";
 
 import { transformerTwoslash } from "@shikijs/vitepress-twoslash";