@ruan-cat/vitepress-preset-config 2.5.0 → 2.6.0

package/dist/config.d.mts

@@ -5,7 +5,6 @@ import { generateSidebar } from 'vitepress-sidebar';
 import llmstxt from 'vitepress-plugin-llms';
 import { GitChangelog, GitChangelogMarkdownSectionOptions } from '@nolebase/vitepress-plugin-git-changelog/vite';
 import { defineTeekConfig } from 'vitepress-theme-teek/config';
-export { addChangelog2doc, copyChangelogMd, copyClaudeAgents, copyReadmeMd } from '@ruan-cat/utils/node-esm';
 
 type LlmstxtSettings = NonNullable<Parameters<typeof llmstxt>[0]>;
 type GitChangelogOptions = NonNullable<Parameters<typeof GitChangelog>[0]>;
@@ -45,6 +44,98 @@ interface ExtraConfig {
     teekConfig?: TeekConfigOptions;
 }
 
+/**
+ * 将 README.md 文件移动到指定要求的位置内，并重命名为 index.md
+ * @description
+ * 该函数相当于实现 `cpx README.md docs` 命令
+ */
+declare function copyReadmeMd(/** 目标文件夹 */ target: string): void;
+
+/**
+ * 将 .claude/agents 文件夹复制到指定位置的配置选项
+ */
+interface CopyClaudeAgentsOptions {
+    /**
+     * 目标文件夹路径（必须是相对路径，相对于当前工作目录）
+     * @description
+     * **重要**：此参数仅接受相对路径，不接受绝对路径（禁止以 `/` 或盘符如 `C:\` 开头）。
+     * 使用绝对路径会抛出错误，这是为了防止意外覆盖系统目录。
+     *
+     * 该地址是写相对路径的 不能写绝对路径，容易导致意外。
+     * vitepress 命令运行在 apps/admin 目录内，该地址是相对于该运行目录的。
+     * 比如期望将 `.claude/agents` 复制到 `apps/admin/src/docs/prompts/agents` 文件夹。
+     * 则写 `src/docs/prompts/agents` 即可。
+     *
+     * @throws {Error} 当传入绝对路径时抛出错误
+     * @example
+     * // ✅ 正确：相对路径
+     * "src/docs/prompts/agents"
+     * "dist/agents"
+     * "./public/claude"
+     *
+     * @example
+     * // ❌ 错误：绝对路径（会抛出错误）
+     * "/var/www/agents"           // Unix 绝对路径
+     * "C:\\Users\\agents"         // Windows 绝对路径
+     */
+    target: string;
+    /**
+     * 可选的根目录路径，支持相对路径（如 `../../../` 表示向上三级目录）
+     * @description
+     * - 如果不传入，将自动向上查找包含 pnpm-workspace.yaml 的 monorepo 根目录
+     * - 相对路径会基于当前工作目录 (process.cwd()) 解析为绝对路径
+     * - 绝对路径将直接使用
+     * @example
+     * // 相对路径：向上三级目录
+     * '../../../'
+     *
+     * // 绝对路径
+     * '/absolute/path/to/monorepo'
+     */
+    rootDir?: string;
+}
+/**
+ * 将 .claude/agents 文件夹复制到指定位置
+ * @param options - 配置选项
+ * @throws {Error} 当 `options.target` 为绝对路径时抛出错误
+ * @description
+ * 该函数相当于实现 `cpx .claude/agents <target>` 命令。
+ * 从根目录的 .claude/agents 复制到目标位置。
+ *
+ * **安全限制**：`target` 参数必须是相对路径，禁止使用绝对路径，以防止意外覆盖系统目录。
+ *
+ * @example
+ * // ✅ 自动检测 monorepo 根目录，复制到当前目录的 dist 文件夹
+ * copyClaudeAgents({ target: 'dist' })
+ *
+ * // ✅ 手动指定根目录为向上三级，复制到 build 文件夹
+ * copyClaudeAgents({
+ *   target: 'build',
+ *   rootDir: '../../../'
+ * })
+ *
+ * // ✅ 使用绝对路径指定根目录（rootDir 允许绝对路径）
+ * copyClaudeAgents({
+ *   target: 'dist',  // target 必须是相对路径
+ *   rootDir: '/absolute/path/to/monorepo'  // rootDir 可以是绝对路径
+ * })
+ *
+ * @example
+ * // ❌ 错误用法：target 使用绝对路径会抛出错误
+ * copyClaudeAgents({ target: '/var/www/agents' })  // 抛出 Error
+ * copyClaudeAgents({ target: 'C:\\Windows\\agents' })  // 抛出 Error
+ */
+declare function copyClaudeAgents(options: CopyClaudeAgentsOptions): void;
+
+interface AddChangelog2docOptions<T = Record<string, any>> {
+    /** 目标文件夹 */
+    target: string;
+    /** 被插入到md头部的数据 */
+    data: T;
+}
+/** 将变更日志添加到指定的文档目录内 并提供参数 */
+declare function addChangelog2doc<T>(options: AddChangelog2docOptions<T>): void;
+
 type VitePressSidebarOptions = Parameters<typeof generateSidebar>[0];
 /**
  * 设置自动生成侧边栏的配置
@@ -54,4 +145,4 @@ declare function setGenerateSidebar(options?: VitePressSidebarOptions): vitepres
 /** 设置vitepress主配置 */
 declare function setUserConfig(config?: UserConfig<DefaultTheme.Config>, extraConfig?: ExtraConfig): UserConfig<DefaultTheme.Config>;
 
-export { setGenerateSidebar, setUserConfig };
+export { addChangelog2doc, copyClaudeAgents, copyReadmeMd, setGenerateSidebar, setUserConfig };

package/dist/config.mjs

@@ -2,17 +2,147 @@
 import { defineConfig } from "vitepress";
 import { generateSidebar } from "vitepress-sidebar";
 import { vitepressDemoPlugin } from "vitepress-demo-plugin";
-import { merge as merge2, isUndefined, cloneDeep as cloneDeep2 } from "lodash-es";
+import { merge as merge2, isUndefined as isUndefined2, cloneDeep as cloneDeep2 } from "lodash-es";
+
+// src/config/copy-readme.ts
+import fs from "fs";
+import path from "path";
 import consola from "consola";
-import {
-  addChangelog2doc,
-  hasChangelogMd,
-  copyReadmeMd,
-  copyClaudeAgents,
-  copyChangelogMd
-} from "@ruan-cat/utils/node-esm";
-import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
-import { copyOrDownloadAsMarkdownButtons } from "vitepress-plugin-llms";
+import { isConditionsSome } from "@ruan-cat/utils";
+var capitalReadmeMd = "README.md";
+var lowerCaseReadmeMd = "readme.md";
+function hasCapitalReadmeMd() {
+  const res = fs.existsSync(path.resolve(process.cwd(), capitalReadmeMd));
+  if (!res) {
+    consola.warn(`\u5F53\u524D\u9879\u76EE\u6839\u76EE\u5F55\u4E0D\u5B58\u5728 ${capitalReadmeMd} \u6587\u4EF6`);
+  }
+  return res;
+}
+function hasLowerCaseReadmeMd() {
+  const res = fs.existsSync(path.resolve(process.cwd(), lowerCaseReadmeMd));
+  if (!res) {
+    consola.log(`\u5F53\u524D\u9879\u76EE\u6839\u76EE\u5F55\u4E0D\u5B58\u5728 ${lowerCaseReadmeMd} \u6587\u4EF6`);
+  }
+  return res;
+}
+function hasReadmeMd() {
+  const res = isConditionsSome([() => hasCapitalReadmeMd(), () => hasCapitalReadmeMd()]);
+  return res;
+}
+function copyReadmeMd(target) {
+  if (!hasReadmeMd()) {
+    return;
+  }
+  let readmeFileName = capitalReadmeMd;
+  if (hasCapitalReadmeMd()) {
+    readmeFileName = capitalReadmeMd;
+  } else if (hasLowerCaseReadmeMd()) {
+    readmeFileName = lowerCaseReadmeMd;
+  }
+  const source = path.resolve(process.cwd(), readmeFileName);
+  const destination = path.resolve(process.cwd(), target, "index.md");
+  fs.copyFileSync(source, destination);
+}
+
+// src/config/copy-claude-agents.ts
+import fs2 from "fs";
+import path2 from "path";
+import consola2 from "consola";
+function findMonorepoRoot() {
+  let currentDir = process.cwd();
+  const root = path2.parse(currentDir).root;
+  while (currentDir !== root) {
+    const workspaceFile2 = path2.join(currentDir, "pnpm-workspace.yaml");
+    if (fs2.existsSync(workspaceFile2)) {
+      return currentDir;
+    }
+    currentDir = path2.dirname(currentDir);
+  }
+  const workspaceFile = path2.join(root, "pnpm-workspace.yaml");
+  if (fs2.existsSync(workspaceFile)) {
+    return root;
+  }
+  return null;
+}
+function resolveRootDir(rootDir) {
+  if (rootDir) {
+    return path2.resolve(process.cwd(), rootDir);
+  }
+  const monorepoRoot = findMonorepoRoot();
+  if (monorepoRoot) {
+    return monorepoRoot;
+  }
+  return process.cwd();
+}
+function hasClaudeAgents(options) {
+  const root = resolveRootDir(options == null ? void 0 : options.rootDir);
+  const claudeAgentsPath = path2.join(root, ".claude/agents");
+  const exists = fs2.existsSync(claudeAgentsPath);
+  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");
+  }
+  return exists;
+}
+function copyClaudeAgents(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"`
+    ].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}`);
+}
+
+// src/config/add-changelog-to-doc.ts
+import path4 from "path";
+
+// src/utils/copy-changelog.ts
+import fs3 from "fs";
+import path3 from "path";
+import consola3 from "consola";
+function hasChangelogMd() {
+  const res = fs3.existsSync(path3.resolve(process.cwd(), "CHANGELOG.md"));
+  if (!res) {
+    consola3.log("\u5F53\u524D\u9879\u76EE\u6839\u76EE\u5F55\u4E3A\uFF1A", process.cwd());
+    consola3.warn("\u5F53\u524D\u9879\u76EE\u6839\u76EE\u5F55\u4E0D\u5B58\u5728 CHANGELOG.md \u6587\u4EF6");
+  }
+  return res;
+}
+function copyChangelogMd(target) {
+  if (!hasChangelogMd()) {
+    return;
+  }
+  const source = path3.resolve(process.cwd(), "CHANGELOG.md");
+  const destination = path3.resolve(process.cwd(), target, "CHANGELOG.md");
+  fs3.copyFileSync(source, destination);
+}
+
+// src/config/add-changelog-to-doc.ts
+import { writeYaml2md } from "@ruan-cat/utils/node-esm";
+function addChangelog2doc(options) {
+  const { data, target } = options;
+  if (!hasChangelogMd()) {
+    return;
+  }
+  copyChangelogMd(target);
+  const mdPath = path4.resolve(process.cwd(), target, "CHANGELOG.md");
+  writeYaml2md({
+    mdPath,
+    data
+  });
+}
 
 // src/config/plugins.ts
 import vitepressPluginLlmstxt from "vitepress-plugin-llms";
@@ -48,6 +178,23 @@ function handlePlugins(userConfig, extraConfig) {
   userConfig.vite.plugins = getPlugins(extraConfig);
 }
 
+// src/config/changelog-nav.ts
+import consola4 from "consola";
+import { isUndefined } from "lodash-es";
+function handleChangeLog(userConfig) {
+  var _a;
+  if (!hasChangelogMd()) {
+    consola4.warn(` \u672A\u627E\u5230\u53D8\u66F4\u65E5\u5FD7\u6587\u4EF6\uFF0C\u4E0D\u6DFB\u52A0\u53D8\u66F4\u65E5\u5FD7\u5BFC\u822A\u680F\u3002 `);
+    return;
+  }
+  const nav = (_a = userConfig == null ? void 0 : userConfig.themeConfig) == null ? void 0 : _a.nav;
+  if (isUndefined(nav)) {
+    consola4.error(` \u5F53\u524D\u7684\u7528\u6237\u914D\u7F6E\u4E3A\uFF1A `, userConfig);
+    throw new Error(` nav \u9ED8\u8BA4\u63D0\u4F9B\u7684\u5BFC\u822A\u680F\u914D\u7F6E\u4E3A\u7A7A\u3002\u4E0D\u7B26\u5408\u9ED8\u8BA4\u914D\u7F6E\uFF0C\u8BF7\u68C0\u67E5\u3002 `);
+  }
+  nav.push({ text: "\u66F4\u65B0\u65E5\u5FD7", link: "/CHANGELOG.md" });
+}
+
 // src/config/teek.ts
 import { defineTeekConfig } from "vitepress-theme-teek/config";
 import { merge, cloneDeep } from "lodash-es";
@@ -117,6 +264,8 @@ function handleTeekConfig(userConfig, extraConfig) {
 }
 
 // src/config.mts
+import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
+import { copyOrDownloadAsMarkdownButtons } from "vitepress-plugin-llms";
 import { MermaidPlugin } from "@leelaa/vitepress-plugin-extended";
 import { defineTeekConfig as defineTeekConfig2 } from "vitepress-theme-teek/config";
 var defaultSidebarOptions = {
@@ -145,7 +294,7 @@ var defaultSidebarOptions = {
   debugPrint: false
 };
 function getMergeSidebarOptions(options) {
-  return merge2({}, cloneDeep2(defaultSidebarOptions), isUndefined(options) ? {} : options);
+  return merge2({}, cloneDeep2(defaultSidebarOptions), isUndefined2(options) ? {} : options);
 }
 function setGenerateSidebar(options) {
   return generateSidebar(getMergeSidebarOptions(options));
@@ -174,7 +323,7 @@ var defaultUserConfig = {
     sidebar: setGenerateSidebar(),
     socialLinks: [{ icon: "github", link: "https://github.com/ruan-cat" }],
     editLink: {
-      pattern: "https://github.com/ruan-cat/monorepo/blob/dev/packages/vitepress-preset-config/src/docs/lesson/index.md",
+      pattern: "https://github.com/ruan-cat/monorepo/blob/dev/packages/vitepress-preset-config/src/docs/please-reset-themeConfig-editLink.md",
       text: "\u5728 github \u4E0A\u6253\u5F00\u6B64\u9875\u9762\u4EE5\u9884\u89C8\u539F\u7248 markdown \u6587\u6863"
     }
   },
@@ -222,21 +371,8 @@ var defaultUserConfig = {
     }
   }
 };
-function handleChangeLog(userConfig) {
-  var _a;
-  if (!hasChangelogMd()) {
-    consola.warn(` \u672A\u627E\u5230\u53D8\u66F4\u65E5\u5FD7\u6587\u4EF6\uFF0C\u4E0D\u6DFB\u52A0\u53D8\u66F4\u65E5\u5FD7\u5BFC\u822A\u680F\u3002 `);
-    return;
-  }
-  const nav = (_a = userConfig == null ? void 0 : userConfig.themeConfig) == null ? void 0 : _a.nav;
-  if (isUndefined(nav)) {
-    consola.error(` \u5F53\u524D\u7684\u7528\u6237\u914D\u7F6E\u4E3A\uFF1A `, userConfig);
-    throw new Error(` nav \u9ED8\u8BA4\u63D0\u4F9B\u7684\u5BFC\u822A\u680F\u914D\u7F6E\u4E3A\u7A7A\u3002\u4E0D\u7B26\u5408\u9ED8\u8BA4\u914D\u7F6E\uFF0C\u8BF7\u68C0\u67E5\u3002 `);
-  }
-  nav.push({ text: "\u66F4\u65B0\u65E5\u5FD7", link: "/CHANGELOG.md" });
-}
 function setUserConfig(config, extraConfig) {
-  const resUserConfig = merge2({}, cloneDeep2(defaultUserConfig), isUndefined(config) ? {} : config);
+  const resUserConfig = merge2({}, cloneDeep2(defaultUserConfig), isUndefined2(config) ? {} : config);
   handleChangeLog(resUserConfig);
   handlePlugins(resUserConfig, extraConfig);
   handleTeekConfig(resUserConfig, extraConfig);
@@ -244,7 +380,6 @@ function setUserConfig(config, extraConfig) {
 }
 export {
   addChangelog2doc,
-  copyChangelogMd,
   copyClaudeAgents,
   copyReadmeMd,
   defineConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ruan-cat/vitepress-preset-config",
-  "version": "2.5.0",
+  "version": "2.6.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.13.0"
+    "@ruan-cat/utils": "^4.14.0"
   },
   "devDependencies": {
     "@types/lodash-es": "^4.17.12",

package/src/config/add-changelog-to-doc.ts

@@ -0,0 +1,29 @@
+import path from "node:path";
+
+import { copyChangelogMd, hasChangelogMd } from "../utils/copy-changelog";
+import { writeYaml2md } from "@ruan-cat/utils/node-esm";
+
+export interface AddChangelog2docOptions<T = Record<string, any>> {
+	/** 目标文件夹 */
+	target: string;
+
+	/** 被插入到md头部的数据 */
+	data: T;
+}
+
+/** 将变更日志添加到指定的文档目录内 并提供参数 */
+export function addChangelog2doc<T>(options: AddChangelog2docOptions<T>) {
+	const { data, target } = options;
+
+	if (!hasChangelogMd()) {
+		return;
+	}
+
+	copyChangelogMd(target);
+
+	const mdPath = path.resolve(process.cwd(), target, "CHANGELOG.md");
+	writeYaml2md({
+		mdPath,
+		data,
+	});
+}

package/src/config/changelog-nav.ts

@@ -0,0 +1,30 @@
+// 为变更日志写入vitepress侧边栏排序yaml信息 并在导航栏内增加顶部入口便于快速阅读
+
+import { type UserConfig, type DefaultTheme } from "vitepress";
+import consola from "consola";
+import { isUndefined } from "lodash-es";
+import { hasChangelogMd } from "../utils/copy-changelog";
+
+/**
+ * 设置导航栏的变更日志
+ * @description
+ * 在导航栏内添加一行 变更日志 的入口
+ *
+ * 直接修改外部传递进来的配置对象即可
+ * @private 内部使用即可
+ */
+export function handleChangeLog(userConfig: UserConfig<DefaultTheme.Config>) {
+	if (!hasChangelogMd()) {
+		consola.warn(` 未找到变更日志文件，不添加变更日志导航栏。 `);
+		return;
+	}
+
+	const nav = userConfig?.themeConfig?.nav;
+
+	if (isUndefined(nav)) {
+		consola.error(` 当前的用户配置为： `, userConfig);
+		throw new Error(` nav 默认提供的导航栏配置为空。不符合默认配置，请检查。 `);
+	}
+
+	nav.push({ text: "更新日志", link: "/CHANGELOG.md" });
+}

package/src/config/copy-claude-agents.ts

@@ -0,0 +1,194 @@
+import fs from "node:fs";
+import path from "node:path";
+import consola from "consola";
+
+/**
+ * 从当前工作目录向上查找 monorepo 根目录
+ * @returns monorepo 根目录的绝对路径，如果找不到则返回 null
+ * @description
+ * 通过查找 pnpm-workspace.yaml 文件来定位 monorepo 根目录。
+ * 从 process.cwd() 开始向上遍历，直到找到该文件或到达文件系统根目录。
+ */
+function findMonorepoRoot(): string | null {
+	let currentDir = process.cwd();
+	const root = path.parse(currentDir).root;
+
+	while (currentDir !== root) {
+		const workspaceFile = path.join(currentDir, "pnpm-workspace.yaml");
+		if (fs.existsSync(workspaceFile)) {
+			return currentDir;
+		}
+		currentDir = path.dirname(currentDir);
+	}
+
+	// 检查根目录本身
+	const workspaceFile = path.join(root, "pnpm-workspace.yaml");
+	if (fs.existsSync(workspaceFile)) {
+		return root;
+	}
+
+	return null;
+}
+
+/**
+ * 解析根目录路径
+ * @param rootDir - 根目录路径，支持相对路径（如 `../../../`）或绝对路径
+ * @returns 解析后的绝对路径
+ * @description
+ * 路径解析优先级：
+ * 1. 如果传入 rootDir，将相对路径基于 process.cwd() 解析为绝对路径
+ * 2. 如果未传入 rootDir，自动向上查找包含 pnpm-workspace.yaml 的 monorepo 根目录
+ * 3. 如果自动查找失败，回退到 process.cwd()
+ */
+function resolveRootDir(rootDir?: string): string {
+	if (rootDir) {
+		// 将相对路径或绝对路径解析为绝对路径
+		return path.resolve(process.cwd(), rootDir);
+	}
+
+	// 自动查找 monorepo 根目录
+	const monorepoRoot = findMonorepoRoot();
+	if (monorepoRoot) {
+		return monorepoRoot;
+	}
+
+	// 回退到当前工作目录
+	return process.cwd();
+}
+
+/**
+ * 检查指定根目录是否存在 .claude/agents 文件夹
+ * @param options - 配置选项
+ * @param options.rootDir - 可选的根目录路径，支持相对路径（如 `../../../` 表示向上三级目录）。
+ *                          如果不传入，将自动向上查找包含 pnpm-workspace.yaml 的 monorepo 根目录。
+ *                          相对路径会基于当前工作目录 (process.cwd()) 解析为绝对路径。
+ * @returns 是否存在 .claude/agents 文件夹
+ * @example
+ * // 自动检测 monorepo 根目录
+ * hasClaudeAgents()
+ *
+ * // 手动指定相对路径（从当前工作目录向上三级）
+ * hasClaudeAgents({ rootDir: '../../../' })
+ *
+ * // 手动指定绝对路径
+ * hasClaudeAgents({ rootDir: '/path/to/monorepo' })
+ */
+function hasClaudeAgents(options?: { rootDir?: string }): boolean {
+	const root = resolveRootDir(options?.rootDir);
+	const claudeAgentsPath = path.join(root, ".claude/agents");
+	const exists = fs.existsSync(claudeAgentsPath);
+
+	if (!exists) {
+		consola.log("检测的根目录为：", root);
+		consola.warn("该根目录不存在 .claude/agents 文件夹");
+	}
+
+	return exists;
+}
+
+/**
+ * 将 .claude/agents 文件夹复制到指定位置的配置选项
+ */
+export interface CopyClaudeAgentsOptions {
+	/**
+	 * 目标文件夹路径（必须是相对路径，相对于当前工作目录）
+	 * @description
+	 * **重要**：此参数仅接受相对路径，不接受绝对路径（禁止以 `/` 或盘符如 `C:\` 开头）。
+	 * 使用绝对路径会抛出错误，这是为了防止意外覆盖系统目录。
+	 *
+	 * 该地址是写相对路径的 不能写绝对路径，容易导致意外。
+	 * vitepress 命令运行在 apps/admin 目录内，该地址是相对于该运行目录的。
+	 * 比如期望将 `.claude/agents` 复制到 `apps/admin/src/docs/prompts/agents` 文件夹。
+	 * 则写 `src/docs/prompts/agents` 即可。
+	 *
+	 * @throws {Error} 当传入绝对路径时抛出错误
+	 * @example
+	 * // ✅ 正确：相对路径
+	 * "src/docs/prompts/agents"
+	 * "dist/agents"
+	 * "./public/claude"
+	 *
+	 * @example
+	 * // ❌ 错误：绝对路径（会抛出错误）
+	 * "/var/www/agents"           // Unix 绝对路径
+	 * "C:\\Users\\agents"         // Windows 绝对路径
+	 */
+	target: string;
+
+	/**
+	 * 可选的根目录路径，支持相对路径（如 `../../../` 表示向上三级目录）
+	 * @description
+	 * - 如果不传入，将自动向上查找包含 pnpm-workspace.yaml 的 monorepo 根目录
+	 * - 相对路径会基于当前工作目录 (process.cwd()) 解析为绝对路径
+	 * - 绝对路径将直接使用
+	 * @example
+	 * // 相对路径：向上三级目录
+	 * '../../../'
+	 *
+	 * // 绝对路径
+	 * '/absolute/path/to/monorepo'
+	 */
+	rootDir?: string;
+}
+
+/**
+ * 将 .claude/agents 文件夹复制到指定位置
+ * @param options - 配置选项
+ * @throws {Error} 当 `options.target` 为绝对路径时抛出错误
+ * @description
+ * 该函数相当于实现 `cpx .claude/agents <target>` 命令。
+ * 从根目录的 .claude/agents 复制到目标位置。
+ *
+ * **安全限制**：`target` 参数必须是相对路径，禁止使用绝对路径，以防止意外覆盖系统目录。
+ *
+ * @example
+ * // ✅ 自动检测 monorepo 根目录，复制到当前目录的 dist 文件夹
+ * copyClaudeAgents({ target: 'dist' })
+ *
+ * // ✅ 手动指定根目录为向上三级，复制到 build 文件夹
+ * copyClaudeAgents({
+ *   target: 'build',
+ *   rootDir: '../../../'
+ * })
+ *
+ * // ✅ 使用绝对路径指定根目录（rootDir 允许绝对路径）
+ * copyClaudeAgents({
+ *   target: 'dist',  // target 必须是相对路径
+ *   rootDir: '/absolute/path/to/monorepo'  // rootDir 可以是绝对路径
+ * })
+ *
+ * @example
+ * // ❌ 错误用法：target 使用绝对路径会抛出错误
+ * copyClaudeAgents({ target: '/var/www/agents' })  // 抛出 Error
+ * copyClaudeAgents({ target: 'C:\\Windows\\agents' })  // 抛出 Error
+ */
+export function copyClaudeAgents(options: CopyClaudeAgentsOptions): void {
+	// 验证 target 不能是绝对路径
+	if (path.isAbsolute(options.target)) {
+		const errorMessage = [
+			`target 参数不允许使用绝对路径，这可能导致意外的文件覆盖。`,
+			`当前传入的路径: "${options.target}"`,
+			`请使用相对路径，例如: "src/docs/prompts/agents"`,
+		].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 });
+
+	// 递归复制文件夹
+	fs.cpSync(source, destination, { recursive: true });
+
+	consola.success(`已成功复制 .claude/agents 到 ${destination}`);
+}

package/src/config/copy-readme.ts

@@ -0,0 +1,60 @@
+import fs from "node:fs";
+import path from "node:path";
+import consola from "consola";
+
+// 有疑惑 这个写法都不对么？ 这个写法对于 vitepress 文档构建来说 是会引发报错的
+// import { isConditionsSome } from "@ruan-cat/utils/src/conditions.ts";
+import { isConditionsSome } from "@ruan-cat/utils";
+
+/** 大写字母的文件 */
+const capitalReadmeMd = "README.md" as const;
+
+/** 小写字母的文件 */
+const lowerCaseReadmeMd = "readme.md" as const;
+
+/** 检查当前运行的根目录 是否存在文件名大写的 `README.md` 文件 */
+function hasCapitalReadmeMd() {
+	const res = fs.existsSync(path.resolve(process.cwd(), capitalReadmeMd));
+	if (!res) {
+		consola.warn(`当前项目根目录不存在 ${capitalReadmeMd} 文件`);
+	}
+	return res;
+}
+
+/** 检查当前运行的根目录 是否存在文件名小写的 `readme.md` 文件 */
+function hasLowerCaseReadmeMd() {
+	const res = fs.existsSync(path.resolve(process.cwd(), lowerCaseReadmeMd));
+	if (!res) {
+		consola.log(`当前项目根目录不存在 ${lowerCaseReadmeMd} 文件`);
+	}
+	return res;
+}
+
+/** 检查当前运行的根目录 是否存在任意一个大小写命名的 README.md 文件 */
+function hasReadmeMd() {
+	const res = isConditionsSome([() => hasCapitalReadmeMd(), () => hasCapitalReadmeMd()]);
+	return res;
+}
+
+/**
+ * 将 README.md 文件移动到指定要求的位置内，并重命名为 index.md
+ * @description
+ * 该函数相当于实现 `cpx README.md docs` 命令
+ */
+export function copyReadmeMd(/** 目标文件夹 */ target: string) {
+	if (!hasReadmeMd()) {
+		return;
+	}
+
+	let readmeFileName: string = capitalReadmeMd;
+	if (hasCapitalReadmeMd()) {
+		readmeFileName = capitalReadmeMd;
+	} else if (hasLowerCaseReadmeMd()) {
+		readmeFileName = lowerCaseReadmeMd;
+	}
+
+	const source = path.resolve(process.cwd(), readmeFileName);
+	const destination = path.resolve(process.cwd(), target, "index.md");
+
+	fs.copyFileSync(source, destination);
+}

package/src/config/index.ts

@@ -1,4 +1,9 @@
 // 专门为 packages\vitepress-preset-config\src\config.mts 服务的文件 提供额外配置
 
+export * from "./page-order-config";
+export * from "./copy-readme";
+export * from "./copy-claude-agents";
+export * from "./add-changelog-to-doc";
 export * from "./plugins";
+export * from "./changelog-nav";
 export * from "./teek";

package/src/config/page-order-config.ts

@@ -0,0 +1,17 @@
+/**
+ * 页面排序配置
+ * 预期设计为一个常量 用于给一些固定的，杂项的页面做侧边栏排序
+ *
+ * 数字越大，排序越靠后
+ */
+export const pageOrderConfig = {
+	/** 提示词页面排序 */
+	prompts: {
+		order: 8000,
+	},
+
+	/** 变更日志页面排序 */
+	changelog: {
+		order: 9000,
+	},
+};

package/src/config.mts

@@ -9,20 +9,15 @@ import { merge, isUndefined, cloneDeep } from "lodash-es";
 import consola from "consola";
 import type { ExtraConfig } from "./types.ts";
 
-import {
-	addChangelog2doc,
-	hasChangelogMd,
-	copyReadmeMd,
-	copyClaudeAgents,
-	copyChangelogMd,
-} from "@ruan-cat/utils/node-esm";
-export { addChangelog2doc, copyReadmeMd, copyClaudeAgents, copyChangelogMd };
+// import { addChangelog2doc, copyReadmeMd, copyClaudeAgents } from "@ruan-cat/utils/node-esm";
+import { addChangelog2doc, copyReadmeMd, copyClaudeAgents } from "./config/index.ts";
+export { addChangelog2doc, copyReadmeMd, copyClaudeAgents };
 
 import { transformerTwoslash } from "@shikijs/vitepress-twoslash";
 
 import llmstxt, { copyOrDownloadAsMarkdownButtons } from "vitepress-plugin-llms";
 
-import { defaultTeekConfig, handleTeekConfig, handlePlugins } from "./config/index.ts";
+import { defaultTeekConfig, handleTeekConfig, handlePlugins, handleChangeLog } from "./config/index.ts";
 
 /** @see https://vitepress-ext.leelaa.cn/Mermaid.html#扩展-md-插件 */
 import { MermaidPlugin } from "@leelaa/vitepress-plugin-extended";
@@ -118,7 +113,7 @@ const defaultUserConfig: UserConfig<DefaultTheme.Config> = {
 
 		editLink: {
 			pattern:
-				"https://github.com/ruan-cat/monorepo/blob/dev/packages/vitepress-preset-config/src/docs/lesson/index.md",
+				"https://github.com/ruan-cat/monorepo/blob/dev/packages/vitepress-preset-config/src/docs/please-reset-themeConfig-editLink.md",
 			text: "在 github 上打开此页面以预览原版 markdown 文档",
 		},
 	},
@@ -180,30 +175,6 @@ const defaultUserConfig: UserConfig<DefaultTheme.Config> = {
 	},
 };
 
-/**
- * 设置导航栏的变更日志
- * @description
- * 在导航栏内添加一行 变更日志 的入口
- *
- * 直接修改外部传递进来的配置对象即可
- * @private 内部使用即可
- */
-function handleChangeLog(userConfig: UserConfig<DefaultTheme.Config>) {
-	if (!hasChangelogMd()) {
-		consola.warn(` 未找到变更日志文件，不添加变更日志导航栏。 `);
-		return;
-	}
-
-	const nav = userConfig?.themeConfig?.nav;
-
-	if (isUndefined(nav)) {
-		consola.error(` 当前的用户配置为： `, userConfig);
-		throw new Error(` nav 默认提供的导航栏配置为空。不符合默认配置，请检查。 `);
-	}
-
-	nav.push({ text: "更新日志", link: "/CHANGELOG.md" });
-}
-
 /** 设置vitepress主配置 */
 export function setUserConfig(
 	config?: UserConfig<DefaultTheme.Config>,

package/src/utils/copy-changelog.ts

@@ -0,0 +1,29 @@
+import fs from "node:fs";
+import path from "node:path";
+import consola from "consola";
+
+/** 检查当前运行的根目录 是否存在 CHANGELOG.md 文件 */
+export function hasChangelogMd() {
+	const res = fs.existsSync(path.resolve(process.cwd(), "CHANGELOG.md"));
+	if (!res) {
+		consola.log("当前项目根目录为：", process.cwd());
+		consola.warn("当前项目根目录不存在 CHANGELOG.md 文件");
+	}
+	return res;
+}
+
+/**
+ * 将 CHANGELOG.md 文件移动到指定要求的位置内
+ * @description
+ * 该函数相当于实现 `cpx CHANGELOG.md docs` 命令
+ */
+export function copyChangelogMd(/** 目标文件夹 */ target: string) {
+	if (!hasChangelogMd()) {
+		return;
+	}
+
+	const source = path.resolve(process.cwd(), "CHANGELOG.md");
+	const destination = path.resolve(process.cwd(), target, "CHANGELOG.md");
+
+	fs.copyFileSync(source, destination);
+}