@skyroc/scripts 2.5.1 → 2.5.2

package/README.md

@@ -144,10 +144,13 @@ pnpm sa create-admin my-admin --install
 
 从 `apps/admin` 生成 `packages/@core/scripts/templates/admin`。`apps/admin` 是唯一源码，模板目录是发布快照，不手工维护。
 
-同步产出两样东西：
+同步产出三样东西：
 
-1. `templates/admin/` —— `apps/admin` 的逐字节镜像。跳过 `node_modules`、`dist`、`.turbo`、`.tanstack`、`coverage`、`.DS_Store`、本地 `.env.*.local` 和 `src/features/router/routeTree.gen.ts`，再根据模板自身的 `src/pages` 重新生成 `routeTree.gen.ts`。
-2. `templates/admin.meta.json` —— 物化元数据。**只有在 monorepo 内才解析得出**，所以必须在同步期算好：解析后的依赖版本、展平后的 tsconfig 与 oxlint 配置、根级 `overrides`、以及未发布的 workspace 包清单。`create-admin` 的 standalone 模式只读这份文件做替换，不需要 monorepo 在场。
+1. `templates/admin-root/` + `templates/admin-root.manifest.json` —— 仓库根级工程文件快照。包含 Git 已跟踪的根级点文件/点目录，以及 `AGENTS.md`、`CLAUDE.md`、`skills-lock.json`；排除 `.git`、缓存、构建产物、本机文件，以及 admin 模板已经自带的 `.oxlintrc.json`。manifest 用于还原 npm 固定忽略的 `.npmignore`、`.npmrc` 等点文件及符号链接。
+2. `templates/admin/` —— `apps/admin` 的逐字节镜像。跳过 `node_modules`、`dist`、`.turbo`、`.tanstack`、`coverage`、`.DS_Store`、本地 `.env.*.local` 和 `src/features/router/routeTree.gen.ts`，再根据模板自身的 `src/pages` 重新生成 `routeTree.gen.ts`。
+3. `templates/admin.meta.json` —— 物化元数据。**只有在 monorepo 内才解析得出**，所以必须在同步期算好：解析后的依赖版本、展平后的 tsconfig 与 oxlint 配置、根级 `overrides`、以及未发布的 workspace 包清单。`create-admin` 的 standalone 模式只读这份文件做替换，不需要 monorepo 在场。
+
+`create-admin` 会先复制 `admin-root`，再覆盖 `admin`。因此协作说明、编辑器配置、skills 和格式化配置会进入新项目；`package.json`、`README.md`、`.oxlintrc.json` 等应用已有文件只取 admin 模板版本。
 
 元数据放在 `templates/admin/` **外层**，这样快照目录仍是纯镜像，逐字节比对不需要为 sidecar 开特例。
 

package/dist/cli.mjs

@@ -1,4 +1,4 @@
-import { h as genChangelog, i as release, l as createAdminTemplate, m as cleanup, n as updatePkg, o as gitCommit, r as syncAdminTemplate, s as gitCommitVerify, t as loadCliOptions } from "./config-BKkdncJS.mjs";
+import { h as genChangelog, i as release, l as createAdminTemplate, m as cleanup, n as updatePkg, o as gitCommit, r as syncAdminTemplate, s as gitCommitVerify, t as loadCliOptions } from "./config-Cj9IzlRz.mjs";
 import process from "node:process";
 import { blue, lightGreen, red } from "kolorist";
 import { cac } from "cac";

package/dist/{config-BKkdncJS.mjs → config-Cj9IzlRz.mjs}

@@ -2,7 +2,7 @@ import { createRequire } from "node:module";
 import { generateChangelog, generateTotalChangelog } from "@soybeanjs/changelog";
 import { rimraf } from "rimraf";
 import { existsSync, readFileSync } from "node:fs";
-import { cp, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { cp, lstat, mkdir, mkdtemp, readFile, readdir, readlink, rm, stat, symlink, writeFile } from "node:fs/promises";
 import path from "node:path";
 import process from "node:process";
 import { bgRed, cyan, green, red, yellow } from "kolorist";
@@ -249,6 +249,12 @@ function toStoragePrefix(name) {
 function getTemplateDir() {
 	return path.join(getPackageRoot(), "templates", TEMPLATE_NAME$1);
 }
+function getRootTemplateDir() {
+	return path.join(getPackageRoot(), "templates", "admin-root");
+}
+function getRootTemplateManifestPath() {
+	return path.join(getPackageRoot(), "templates", "admin-root.manifest.json");
+}
 function getShellTemplateDir() {
 	return path.join(getPackageRoot(), "templates", "admin-shell");
 }
@@ -288,6 +294,28 @@ async function installDependencies(cwd) {
 		stdio: "inherit"
 	});
 }
+async function restoreRootTemplateFiles(targetDir) {
+	const manifestPath = getRootTemplateManifestPath();
+	if (!existsSync(manifestPath)) throw new Error(`Admin root template manifest is missing: ${manifestPath}`);
+	const entries = JSON.parse(await readFile(manifestPath, "utf8"));
+	await Promise.all(entries.map(async (entry) => {
+		const target = path.resolve(targetDir, entry.path);
+		const relativeTarget = path.relative(targetDir, target);
+		if (path.isAbsolute(entry.path) || relativeTarget.startsWith("..") || path.isAbsolute(relativeTarget)) throw new Error(`Invalid admin root template path: ${entry.path}`);
+		await mkdir(path.dirname(target), { recursive: true });
+		if (entry.type === "symlink") {
+			if (!entry.target) throw new Error(`Admin root template symlink target is missing: ${entry.path}`);
+			await rm(target, {
+				force: true,
+				recursive: true
+			});
+			await symlink(entry.target, target);
+			return;
+		}
+		if (entry.content === void 0) throw new Error(`Admin root template content is missing: ${entry.path}`);
+		await writeFile(target, Buffer.from(entry.content, "base64"));
+	}));
+}
 /** 独立模式下把 monorepo 协议物化掉，并把物化过程中发现的隐患打印出来。 */
 async function applyStandaloneMaterialization(targetDir, packageName, description) {
 	const metaPath = getTemplateMetaPath();
@@ -309,7 +337,9 @@ async function createAdminTemplate(name, options = {}) {
 	const directoryName = packageName.replace(/^@[^/]+\//, "");
 	const targetDir = path.resolve(process.cwd(), options.target || path.join("apps", directoryName));
 	const templateDir = getTemplateDir();
+	const rootTemplateDir = getRootTemplateDir();
 	if (!existsSync(templateDir)) throw new Error(`Admin template is missing: ${templateDir}`);
+	if (!existsSync(rootTemplateDir)) throw new Error(`Admin root template is missing: ${rootTemplateDir}`);
 	if (existsSync(targetDir) && !await isDirectoryEmpty(targetDir)) {
 		if (!options.force) throw new Error(`Target directory is not empty: ${targetDir}. Use --force to overwrite it.`);
 		await rm(targetDir, {
@@ -318,6 +348,11 @@ async function createAdminTemplate(name, options = {}) {
 		});
 	}
 	await mkdir(path.dirname(targetDir), { recursive: true });
+	await cp(rootTemplateDir, targetDir, {
+		recursive: true,
+		verbatimSymlinks: true
+	});
+	await restoreRootTemplateFiles(targetDir);
 	await cp(templateDir, targetDir, { recursive: true });
 	if (options.workspace) await updatePackageJson(targetDir, packageName, description);
 	else {
@@ -698,9 +733,21 @@ async function resolveTemplateMeta(options) {
 //#endregion
 //#region src/commands/sync-admin-template.ts
 const TEMPLATE_NAME = "admin";
-/** shell 源码模板目录名，与 templates/admin 平级，保持 admin/ 仍是 apps/admin 的逐字节镜像。 */
+/** 仓库根级工程文件模板目录；生成项目时先铺这一层，再由 admin 应用文件覆盖同名项。 */
+const ROOT_TEMPLATE_NAME = "admin-root";
+/** Npm 会主动忽略部分点文件，因此另存一份可完整还原根快照的清单。 */
+const ROOT_TEMPLATE_MANIFEST_FILE = "admin-root.manifest.json";
+/** 不以点开头、但应随新项目保留的仓库根级文件。 */
+const ROOT_TEMPLATE_FILES = [
+	"AGENTS.md",
+	"CLAUDE.md",
+	"skills-lock.json"
+];
+/** Admin 应用模板已有自己的版本，不再从仓库根重复复制。 */
+const ROOT_TEMPLATE_EXCLUDED_FILES = new Set([".oxlintrc.json"]);
+/** Shell 源码模板目录名，与 templates/admin 平级，保持 admin/ 仍是 apps/admin 的逐字节镜像。 */
 const SHELL_TEMPLATE_NAME = "admin-shell";
-/** shell 里会被复制进生成项目 src/framework 的运行时目录；配置、测试与文档不属于产物。 */
+/** Shell 里会被复制进生成项目 src/framework 的运行时目录；配置、测试与文档不属于产物。 */
 const SHELL_RUNTIME_DIRS = [
 	"i18n",
 	"layouts",
@@ -716,6 +763,7 @@ const MAX_REPORTED_DIFFERENCES = 20;
 const TECHNICAL_DIRS = new Set([
 	".tanstack",
 	".turbo",
+	"__pycache__",
 	"coverage",
 	"dist",
 	"node_modules"
@@ -731,7 +779,7 @@ function isTechnicalGeneratedPath(relativePath) {
 	if (!relativePath) return false;
 	const segments = relativePath.split("/");
 	const basename = segments.at(-1);
-	return basename === ".DS_Store" || basename?.endsWith(".tsbuildinfo") || basename?.endsWith(".log") || isLocalEnvFile(relativePath) || segments.some((segment) => TECHNICAL_DIRS.has(segment));
+	return basename === ".DS_Store" || basename?.endsWith(".pyc") || basename?.endsWith(".tsbuildinfo") || basename?.endsWith(".log") || isLocalEnvFile(relativePath) || segments.some((segment) => TECHNICAL_DIRS.has(segment));
 }
 function isRouteTreeFile(relativePath) {
 	return relativePath === "src/features/router/routeTree.gen.ts";
@@ -748,6 +796,46 @@ function resolveSourceDir(workspaceRoot, source) {
 function resolveTargetDir(target) {
 	return path.resolve(process.cwd(), target || path.join(getPackageRoot(), "templates", TEMPLATE_NAME));
 }
+async function collectTrackedRootTemplateFiles(workspaceRoot) {
+	const { execa } = await import("execa");
+	const { stdout } = await execa("git", [
+		"ls-files",
+		"-z",
+		"--",
+		".*",
+		...ROOT_TEMPLATE_FILES
+	], { cwd: workspaceRoot });
+	return stdout.split("\0").map(normalizeRelativePath).filter(Boolean).filter((relativePath) => !ROOT_TEMPLATE_EXCLUDED_FILES.has(relativePath)).filter((relativePath) => !isTechnicalGeneratedPath(relativePath));
+}
+async function copyRootSource(workspaceRoot, targetDir) {
+	await rm(targetDir, {
+		force: true,
+		recursive: true
+	});
+	const files = await collectTrackedRootTemplateFiles(workspaceRoot);
+	const manifestEntries = [];
+	for (const relativePath of files) {
+		const source = path.join(workspaceRoot, relativePath);
+		const target = path.join(targetDir, relativePath);
+		const sourceStat = await lstat(source);
+		await mkdir(path.dirname(target), { recursive: true });
+		await cp(source, target, {
+			recursive: true,
+			verbatimSymlinks: true
+		});
+		if (sourceStat.isSymbolicLink()) manifestEntries.push({
+			path: relativePath,
+			target: await readlink(source),
+			type: "symlink"
+		});
+		else if (sourceStat.isFile()) manifestEntries.push({
+			content: (await readFile(source)).toString("base64"),
+			path: relativePath,
+			type: "file"
+		});
+	}
+	await writeFile(path.join(path.dirname(targetDir), ROOT_TEMPLATE_MANIFEST_FILE), `${JSON.stringify(manifestEntries, null, 2)}\n`);
+}
 async function copyAdminSource(sourceDir, targetDir) {
 	await rm(targetDir, {
 		force: true,
@@ -861,6 +949,7 @@ async function generateSnapshot(workspaceRoot, sourceDir, targetDir) {
 	if (!existsSync(sourceDir)) throw new Error(`Admin source is missing: ${sourceDir}`);
 	const shellSourceDir = path.join(workspaceRoot, "packages/web/admin");
 	const shellTargetDir = path.join(path.dirname(targetDir), SHELL_TEMPLATE_NAME);
+	await copyRootSource(workspaceRoot, path.join(path.dirname(targetDir), ROOT_TEMPLATE_NAME));
 	await copyAdminSource(sourceDir, targetDir);
 	await copyShellSource(shellSourceDir, shellTargetDir);
 	await generateRouteTree(targetDir);
@@ -891,11 +980,22 @@ async function checkAdminTemplate(workspaceRoot, sourceDir, targetDir) {
 		const { metaContent } = await generateSnapshot(workspaceRoot, sourceDir, generatedDir);
 		const differences = await compareDirectories(targetDir, generatedDir);
 		const shellDifferences = await compareDirectories(path.join(path.dirname(targetDir), SHELL_TEMPLATE_NAME), path.join(tempDir, SHELL_TEMPLATE_NAME));
-		differences.push(...shellDifferences.map((item) => ({
+		const rootDifferences = await compareDirectories(path.join(path.dirname(targetDir), ROOT_TEMPLATE_NAME), path.join(tempDir, ROOT_TEMPLATE_NAME));
+		differences.push(...rootDifferences.map((item) => ({
+			...item,
+			path: `${ROOT_TEMPLATE_NAME}/${item.path}`
+		})), ...shellDifferences.map((item) => ({
 			...item,
 			path: `${SHELL_TEMPLATE_NAME}/${item.path}`
 		})));
 		const currentMetaContent = await readMetaContent(path.join(path.dirname(targetDir), TEMPLATE_META_FILE));
+		const rootManifestPath = path.join(path.dirname(targetDir), ROOT_TEMPLATE_MANIFEST_FILE);
+		const generatedRootManifestPath = path.join(tempDir, ROOT_TEMPLATE_MANIFEST_FILE);
+		const [currentRootManifest, generatedRootManifest] = await Promise.all([readMetaContent(rootManifestPath), readMetaContent(generatedRootManifestPath)]);
+		if (currentRootManifest !== generatedRootManifest) differences.push({
+			path: ROOT_TEMPLATE_MANIFEST_FILE,
+			type: currentRootManifest ? "changed" : "added"
+		});
 		if (currentMetaContent !== metaContent) differences.push({
 			path: TEMPLATE_META_FILE,
 			type: currentMetaContent ? "changed" : "added"

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as createCommitMessageRegExp, c as locales, d as replaceEnvValue, f as toStoragePrefix, h as genChangelog, i as release, l as createAdminTemplate, m as cleanup, n as updatePkg, o as gitCommit, p as toTitle, r as syncAdminTemplate, s as gitCommitVerify, t as loadCliOptions, u as normalizePackageName } from "./config-BKkdncJS.mjs";
+import { a as createCommitMessageRegExp, c as locales, d as replaceEnvValue, f as toStoragePrefix, h as genChangelog, i as release, l as createAdminTemplate, m as cleanup, n as updatePkg, o as gitCommit, p as toTitle, r as syncAdminTemplate, s as gitCommitVerify, t as loadCliOptions, u as normalizePackageName } from "./config-Cj9IzlRz.mjs";
 
 //#region src/index.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyroc/scripts",
-  "version": "2.5.1",
+  "version": "2.5.2",
   "type": "module",
   "description": "Skyroc admin CLI - changelog, release, git-commit, cleanup and other project automation scripts",
   "keywords": [
@@ -67,8 +67,8 @@
     "tsx": "^4.21.0",
     "typescript": "^6.0.3",
     "vitest": "^4.0.18",
-    "@skyroc/config": "1.0.0",
-    "@skyroc/tsconfig": "1.0.0"
+    "@skyroc/tsconfig": "1.0.0",
+    "@skyroc/config": "1.0.0"
   },
   "scripts": {
     "build": "tsdown",

package/templates/admin/package.json

@@ -39,6 +39,10 @@
     "update-pkg": "sa update-pkg"
   },
   "dependencies": {
+    "@better-scroll/core": "catalog:web",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
     "@skyroc/axios": "workspace:*",
     "@skyroc/color": "workspace:*",
     "@skyroc/core-state": "workspace:*",
@@ -68,7 +72,7 @@
     "@iconify/json": "catalog:ui-shared",
     "@iconify/react": "catalog:ui-shared",
     "@iconify/types": "catalog:ui-shared",
-    "@sa/uno-config": "workspace:*",
+    "@skyroc/uno-config": "workspace:*",
     "@skyroc/scripts": "workspace:*",
     "@skyroc/web-admin-vite": "workspace:*",
     "@svgr/core": "catalog:web",

package/templates/admin/src/assets/svg-icon/logo.svg

@@ -1,3 +1,3 @@
 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 160 160" role="img" aria-label="Skyroc 天鹏">
-  <path fill="#6366F1" fill-rule="evenodd" d="M 8.31 49.69 Q 8.00 51.38 8.00 54.15 Q 8.00 56.92 8.46 59.08 Q 8.92 61.23 9.85 63.54 Q 10.77 65.85 12.31 68.15 Q 13.85 70.46 15.77 72.38 Q 17.69 74.31 19.85 75.85 Q 22.00 77.38 24.46 78.62 Q 26.92 79.85 30.85 81.00 Q 34.77 82.15 31.92 82.23 Q 29.08 82.31 27.38 82.00 Q 25.69 81.69 23.85 81.08 Q 22.00 80.46 19.23 78.92 Q 16.46 77.38 16.38 78.08 Q 16.31 78.77 16.77 80.15 Q 17.23 81.54 18.15 83.23 Q 19.08 84.92 22.08 87.92 Q 25.08 90.92 28.15 92.46 Q 31.23 94.00 36.00 94.77 Q 40.77 95.54 44.62 95.23 Q 48.46 94.92 53.85 93.69 Q 59.23 92.46 62.15 92.46 Q 65.08 92.46 67.38 93.38 Q 69.69 94.31 70.85 95.46 Q 72.00 96.62 72.46 97.54 Q 72.92 98.46 72.77 100.77 Q 72.62 103.08 71.54 105.38 Q 70.46 107.69 66.92 113.23 Q 63.38 118.77 62.92 120.31 Q 62.46 121.85 62.46 123.54 Q 62.46 125.23 63.08 126.92 Q 63.69 128.62 64.69 129.62 Q 65.69 130.62 69.00 123.92 Q 72.31 117.23 73.92 111.15 Q 75.54 105.08 75.62 108.38 Q 75.69 111.69 74.31 118.31 Q 72.92 124.92 72.77 126.92 Q 72.62 128.92 72.92 130.62 Q 73.23 132.31 74.15 134.31 Q 75.08 136.31 77.31 139.00 Q 79.54 141.69 80.00 141.69 Q 80.46 141.69 81.31 140.85 Q 82.15 140.00 83.85 137.69 Q 85.54 135.38 86.46 132.46 Q 87.38 129.54 87.23 127.08 Q 87.08 124.62 85.69 117.54 Q 84.31 110.46 84.38 107.62 Q 84.46 104.77 86.23 111.31 Q 88.00 117.85 91.00 124.23 Q 94.00 130.62 95.00 129.77 Q 96.00 128.92 96.77 127.23 Q 97.54 125.54 97.54 123.38 Q 97.54 121.23 97.08 119.85 Q 96.62 118.46 93.38 113.54 Q 90.15 108.62 88.77 105.54 Q 87.38 102.46 87.23 100.77 Q 87.08 99.08 88.00 97.38 Q 88.92 95.69 90.08 94.69 Q 91.23 93.69 93.23 92.92 Q 95.23 92.15 97.54 92.15 Q 99.85 92.15 107.08 93.69 Q 114.31 95.23 118.31 95.23 Q 122.31 95.23 126.31 94.15 Q 130.31 93.08 133.08 91.38 Q 135.85 89.69 138.69 86.54 Q 141.54 83.38 142.69 80.38 Q 143.85 77.38 139.08 79.54 Q 134.31 81.69 132.62 82.00 Q 130.92 82.31 128.23 82.23 Q 125.54 82.15 129.00 81.15 Q 132.46 80.15 135.54 78.62 Q 138.62 77.08 140.31 75.85 Q 142.00 74.62 144.69 71.77 Q 147.38 68.92 148.77 66.46 Q 150.15 64.00 150.92 61.54 Q 151.69 59.08 151.85 55.08 Q 152.00 51.08 151.54 49.08 Q 151.08 47.08 150.77 47.08 Q 150.46 47.08 147.85 51.08 Q 145.23 55.08 140.69 59.15 Q 136.15 63.23 131.08 66.00 Q 126.00 68.77 119.69 70.92 Q 113.38 73.08 109.69 74.77 Q 106.00 76.46 101.85 79.85 Q 97.69 83.23 97.46 83.15 Q 97.23 83.08 98.77 80.92 Q 100.31 78.77 103.62 75.92 Q 106.92 73.08 110.62 71.08 Q 114.31 69.08 119.54 67.08 Q 124.77 65.08 129.54 62.46 Q 134.31 59.85 137.31 57.15 Q 140.31 54.46 141.85 52.31 Q 143.38 50.15 144.77 46.31 Q 146.15 42.46 146.15 38.62 Q 146.15 34.77 145.38 32.00 Q 144.62 29.23 143.54 26.92 Q 142.46 24.62 139.92 21.46 Q 137.38 18.31 136.54 22.69 Q 135.69 27.08 134.62 29.85 Q 133.54 32.62 130.00 38.00 Q 126.46 43.38 121.62 48.08 Q 116.77 52.77 108.15 59.38 Q 99.54 66.00 95.08 70.77 Q 90.62 75.54 89.92 75.00 Q 89.23 74.46 88.46 73.08 Q 87.69 71.69 87.38 68.92 Q 87.08 66.15 88.15 63.69 Q 89.23 61.23 90.54 60.08 Q 91.85 58.92 93.15 58.54 Q 94.46 58.15 93.77 57.15 Q 93.08 56.15 88.92 56.31 Q 84.77 56.46 82.62 57.69 Q 80.46 58.92 78.69 60.85 Q 76.92 62.77 77.85 62.77 Q 78.77 62.77 76.62 66.77 Q 74.46 70.77 72.85 72.38 Q 71.23 74.00 70.15 74.46 Q 69.08 74.92 64.46 70.15 Q 59.85 65.38 51.23 58.77 Q 42.62 52.15 38.08 47.77 Q 33.54 43.38 31.54 40.77 Q 29.54 38.15 27.85 35.08 Q 26.15 32.00 25.08 28.92 Q 24.00 25.85 23.31 22.08 Q 22.62 18.31 20.23 21.31 Q 17.85 24.31 16.77 26.46 Q 15.69 28.62 14.77 31.85 Q 13.85 35.08 13.85 38.77 Q 13.85 42.46 15.23 46.31 Q 16.62 50.15 18.15 52.31 Q 19.69 54.46 23.62 57.77 Q 27.54 61.08 30.77 62.77 Q 34.00 64.46 40.00 66.77 Q 46.00 69.08 50.46 71.54 Q 54.92 74.00 57.77 76.69 Q 60.62 79.38 61.77 81.46 Q 62.92 83.54 60.46 81.23 Q 58.00 78.92 55.23 77.08 Q 52.46 75.23 49.69 74.00 Q 46.92 72.77 39.85 70.46 Q 32.77 68.15 27.69 65.23 Q 22.62 62.31 19.00 59.00 Q 15.38 55.69 12.38 51.31 Q 9.38 46.92 9.00 47.46 Q 8.62 48.00 8.31 49.69 Z"/>
+  <path fill="currentColor" fill-rule="evenodd" d="M 8.31 49.69 Q 8.00 51.38 8.00 54.15 Q 8.00 56.92 8.46 59.08 Q 8.92 61.23 9.85 63.54 Q 10.77 65.85 12.31 68.15 Q 13.85 70.46 15.77 72.38 Q 17.69 74.31 19.85 75.85 Q 22.00 77.38 24.46 78.62 Q 26.92 79.85 30.85 81.00 Q 34.77 82.15 31.92 82.23 Q 29.08 82.31 27.38 82.00 Q 25.69 81.69 23.85 81.08 Q 22.00 80.46 19.23 78.92 Q 16.46 77.38 16.38 78.08 Q 16.31 78.77 16.77 80.15 Q 17.23 81.54 18.15 83.23 Q 19.08 84.92 22.08 87.92 Q 25.08 90.92 28.15 92.46 Q 31.23 94.00 36.00 94.77 Q 40.77 95.54 44.62 95.23 Q 48.46 94.92 53.85 93.69 Q 59.23 92.46 62.15 92.46 Q 65.08 92.46 67.38 93.38 Q 69.69 94.31 70.85 95.46 Q 72.00 96.62 72.46 97.54 Q 72.92 98.46 72.77 100.77 Q 72.62 103.08 71.54 105.38 Q 70.46 107.69 66.92 113.23 Q 63.38 118.77 62.92 120.31 Q 62.46 121.85 62.46 123.54 Q 62.46 125.23 63.08 126.92 Q 63.69 128.62 64.69 129.62 Q 65.69 130.62 69.00 123.92 Q 72.31 117.23 73.92 111.15 Q 75.54 105.08 75.62 108.38 Q 75.69 111.69 74.31 118.31 Q 72.92 124.92 72.77 126.92 Q 72.62 128.92 72.92 130.62 Q 73.23 132.31 74.15 134.31 Q 75.08 136.31 77.31 139.00 Q 79.54 141.69 80.00 141.69 Q 80.46 141.69 81.31 140.85 Q 82.15 140.00 83.85 137.69 Q 85.54 135.38 86.46 132.46 Q 87.38 129.54 87.23 127.08 Q 87.08 124.62 85.69 117.54 Q 84.31 110.46 84.38 107.62 Q 84.46 104.77 86.23 111.31 Q 88.00 117.85 91.00 124.23 Q 94.00 130.62 95.00 129.77 Q 96.00 128.92 96.77 127.23 Q 97.54 125.54 97.54 123.38 Q 97.54 121.23 97.08 119.85 Q 96.62 118.46 93.38 113.54 Q 90.15 108.62 88.77 105.54 Q 87.38 102.46 87.23 100.77 Q 87.08 99.08 88.00 97.38 Q 88.92 95.69 90.08 94.69 Q 91.23 93.69 93.23 92.92 Q 95.23 92.15 97.54 92.15 Q 99.85 92.15 107.08 93.69 Q 114.31 95.23 118.31 95.23 Q 122.31 95.23 126.31 94.15 Q 130.31 93.08 133.08 91.38 Q 135.85 89.69 138.69 86.54 Q 141.54 83.38 142.69 80.38 Q 143.85 77.38 139.08 79.54 Q 134.31 81.69 132.62 82.00 Q 130.92 82.31 128.23 82.23 Q 125.54 82.15 129.00 81.15 Q 132.46 80.15 135.54 78.62 Q 138.62 77.08 140.31 75.85 Q 142.00 74.62 144.69 71.77 Q 147.38 68.92 148.77 66.46 Q 150.15 64.00 150.92 61.54 Q 151.69 59.08 151.85 55.08 Q 152.00 51.08 151.54 49.08 Q 151.08 47.08 150.77 47.08 Q 150.46 47.08 147.85 51.08 Q 145.23 55.08 140.69 59.15 Q 136.15 63.23 131.08 66.00 Q 126.00 68.77 119.69 70.92 Q 113.38 73.08 109.69 74.77 Q 106.00 76.46 101.85 79.85 Q 97.69 83.23 97.46 83.15 Q 97.23 83.08 98.77 80.92 Q 100.31 78.77 103.62 75.92 Q 106.92 73.08 110.62 71.08 Q 114.31 69.08 119.54 67.08 Q 124.77 65.08 129.54 62.46 Q 134.31 59.85 137.31 57.15 Q 140.31 54.46 141.85 52.31 Q 143.38 50.15 144.77 46.31 Q 146.15 42.46 146.15 38.62 Q 146.15 34.77 145.38 32.00 Q 144.62 29.23 143.54 26.92 Q 142.46 24.62 139.92 21.46 Q 137.38 18.31 136.54 22.69 Q 135.69 27.08 134.62 29.85 Q 133.54 32.62 130.00 38.00 Q 126.46 43.38 121.62 48.08 Q 116.77 52.77 108.15 59.38 Q 99.54 66.00 95.08 70.77 Q 90.62 75.54 89.92 75.00 Q 89.23 74.46 88.46 73.08 Q 87.69 71.69 87.38 68.92 Q 87.08 66.15 88.15 63.69 Q 89.23 61.23 90.54 60.08 Q 91.85 58.92 93.15 58.54 Q 94.46 58.15 93.77 57.15 Q 93.08 56.15 88.92 56.31 Q 84.77 56.46 82.62 57.69 Q 80.46 58.92 78.69 60.85 Q 76.92 62.77 77.85 62.77 Q 78.77 62.77 76.62 66.77 Q 74.46 70.77 72.85 72.38 Q 71.23 74.00 70.15 74.46 Q 69.08 74.92 64.46 70.15 Q 59.85 65.38 51.23 58.77 Q 42.62 52.15 38.08 47.77 Q 33.54 43.38 31.54 40.77 Q 29.54 38.15 27.85 35.08 Q 26.15 32.00 25.08 28.92 Q 24.00 25.85 23.31 22.08 Q 22.62 18.31 20.23 21.31 Q 17.85 24.31 16.77 26.46 Q 15.69 28.62 14.77 31.85 Q 13.85 35.08 13.85 38.77 Q 13.85 42.46 15.23 46.31 Q 16.62 50.15 18.15 52.31 Q 19.69 54.46 23.62 57.77 Q 27.54 61.08 30.77 62.77 Q 34.00 64.46 40.00 66.77 Q 46.00 69.08 50.46 71.54 Q 54.92 74.00 57.77 76.69 Q 60.62 79.38 61.77 81.46 Q 62.92 83.54 60.46 81.23 Q 58.00 78.92 55.23 77.08 Q 52.46 75.23 49.69 74.00 Q 46.92 72.77 39.85 70.46 Q 32.77 68.15 27.69 65.23 Q 22.62 62.31 19.00 59.00 Q 15.38 55.69 12.38 51.31 Q 9.38 46.92 9.00 47.46 Q 8.62 48.00 8.31 49.69 Z"/>
 </svg>

package/templates/admin/uno.config.ts

@@ -1,4 +1,4 @@
-import { presetSoybeanAdmin } from '@sa/uno-config';
+import { presetSoybeanAdmin } from '@skyroc/uno-config';
 import { defineConfig, presetWind3, transformerDirectives, transformerVariantGroup } from 'unocss';
 
 export default defineConfig({

package/templates/admin-root/.agents/skills/component-doc/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: component-doc
+description: 为 @skyroc/web-ui 组件编写文档。当用户说出组件名（如 Button、Accordion、AlertDialog）时触发。自动定位组件源码、playground demo、已有文档，按照项目文档规范生成或更新 MDX 文档。
+argument-hint: 组件名，如 Button、Accordion、AlertDialog
+---
+
+# Component Documentation Workflow
+
+为 `@skyroc/web-ui` 组件库编写文档的专用工作流。
+
+## 文件定位规则
+
+给定组件名 `$COMPONENT`（用户输入，如 `Button`），将其转为 kebab-case `$slug`（如 `button`），然后按以下路径查找：
+
+| 用途 | 路径 |
+|---|---|
+| 组件源码 | `packages/web/ui/shadcn/src/components/$slug/` |
+| Playground Demo | `apps/web-ui-playground/src/app/[locale]/(demo)/$slug/modules/` |
+| 文档 MDX | `apps/web-ui-docs/content/docs/components/$slug.mdx` |
+
+**文档基础设施文件**（不需要每次都读，但需要了解）：
+
+| 文件 | 作用 |
+|---|---|
+| `apps/web-ui-docs/components/props-table.tsx` | `<PropsTable>` — API 属性表格 |
+| `apps/web-ui-docs/components/type-table.tsx` | `<TypeTable>` + `<UnionType>` — 类型定义区 |
+| `apps/web-ui-docs/components/type-anchor.tsx` | 类型链接解析（PascalCase 自定义类型 → 蓝色可点击锚点） |
+| `apps/web-ui-docs/components/type-registry.ts` | 跨页面类型链接注册表 |
+| `apps/web-ui-docs/components/demo/index.tsx` | `<Demo>` — 从 playground 加载 live demo |
+| `apps/web-ui-docs/components/mdx.tsx` | MDX 组件注册（Demo / PropsTable / TypeTable / UnionType） |
+
+## 执行流程
+
+### Phase 1: 源码阅读与行为校验
+
+1. 读取 `packages/web/ui/shadcn/src/components/$slug/` 下所有文件
+   - 重点关注：`index.ts`（导出）、`types.ts`（Props 定义）、`*-variants.ts`（样式变体）、主组件文件
+2. 读取 `apps/web-ui-playground/src/app/[locale]/(demo)/$slug/modules/` 下所有 demo
+   - 如果目录不存在或 demo 数量不足以覆盖文档需要的功能章节，标记为"需创建 demo"
+3. 如果 preset 包装器存在，读取 `packages/web/ui/shadcn/src/preset/$slug/` 了解预设封装和 `useComponentConfig` 集成
+4. 如果已有文档 MDX，读取 `apps/web-ui-docs/content/docs/components/$slug.mdx`
+5. 读取一个已完成的文档作为参考模板（优先 `alert.mdx`，其次 `button.mdx`）
+
+#### 实现一致性校验（必须执行）
+
+文档不是 API 想象稿，必须从 **源码、类型、demo、实际行为** 四者交叉验证。
+
+写文档前必须同时检查：
+
+- `types.ts` 声明了哪些 public props / types
+- 主组件实际解构了哪些 props
+- props 是否真的传递给对应子组件或底层库
+- 默认值实际在哪里设置
+- `classNames` / slot props / `size` / `variant` / `color` 等样式控制是否真的生效
+- `index.ts` 实际导出了哪些组件和类型
+
+如果发现 **类型/API 承诺** 与 **实现行为** 不一致：
+
+1. 先明确指出这是实现问题或 API 语义不一致
+2. 如果任务允许修改代码，应优先修实现或类型，而不是在文档里规避
+3. 如果不能修改实现，必须在最终说明中列为风险/阻塞，并在文档中避免承诺未实现能力
+4. 不允许只降低文档表述来掩盖实现 bug
+
+典型例子：
+
+- `BottomSheetProps.size` 声明为主组件尺寸，但主组件没有传给 `BottomSheetContent`：这是实现 bug，应提出或修复
+- props 被解构但没有使用：不要在文档中承诺该能力已生效
+- 类型继承了底层库 props，但封装组件覆盖或丢弃了其中一部分：以实际封装行为为准
+
+### Phase 2: 文档编写
+
+#### MDX 结构（必须遵循）
+
+```mdx
+---
+title: $COMPONENT
+description: 一句话描述组件用途
+---
+
+组件概述段落。
+
+\`\`\`tsx
+import { ... } from '@skyroc/web-ui';
+\`\`\`
+
+## 何时使用
+
+- 使用场景 1
+- 使用场景 2
+- 与相似组件的区分
+
+## 功能章节 1（如"颜色"、"变体"、"尺寸"等）
+
+说明文字 + 表格（可选）
+
+<Demo src="@playground/$slug/modules/DemoName" />
+
+\`\`\`tsx
+// 内联代码作为 API 快速参考
+<Component prop="value" />
+\`\`\`
+
+## 功能章节 N
+
+...
+
+## API
+
+### $COMPONENT
+
+通用属性参考说明。
+
+<PropsTable data={[...]} />
+
+### 子组件（如有）
+
+<PropsTable data={[...]} />
+
+## 类型
+
+<TypeTable data={[...]} />
+<UnionType name="..." description="..." type="..." />
+```
+
+#### Demo + 内联代码的组合模式（必须遵循）
+
+每个功能章节的示例由两部分组成，缺一不可：
+
+1. **`<Demo>` 标签**（必须）：引用 playground 源码，用户可在文档中看到交互式 live demo 和完整源码。
+2. **内联代码块**（推荐）：紧跟在 `<Demo>` 后面，提供简洁的 API 用法速查。
+
+内联代码块的编写原则：
+- 不需要完整组件结构，只展示关键 API 用法（最核心的 props 组合）
+- Hooks 类的章节用 1-3 行代码展示调用签名即可
+- 如果 Demo 本身已经足够简单直观，可以省略内联代码
+- 纯展示类章节（如尺寸枚举、变体枚举）可以用表格代替内联代码
+
+示例：
+
+```mdx
+## 受控模式
+
+通过 `page` + `onPageChange` 实现受控分页。
+
+<Demo src="@playground/pagination/modules/Controlled" />
+
+\`\`\`tsx
+const [page, setPage] = useState(1);
+
+<Pagination
+  total={200}
+  itemsPerPage={10}
+  page={page}
+  onPageChange={setPage}
+/>
+\`\`\`
+```
+
+#### PropsTable 书写规则
+
+- `type` 字段：短字面量联合类型必须直接内联，不要另起 PascalCase 类型名，也不要在 `## 类型` 区域写 `<UnionType>`。
+- 典型需要内联的类型：
+  - 主题色：`"'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'carbon' | 'secondary' | 'accent'"`
+  - 尺寸：`"'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'"`
+  - 状态 / 方向 / 位置 / 形状等短联合：`"boolean | 'indeterminate'"`、`"'horizontal' | 'vertical'"`、`"'left' | 'right'"`、`"'square' | 'rounded'"`
+- 对象类型、复杂派生类型、外部库大型类型、子组件 Props、classNames/slots 配置，使用 PascalCase 类型名引用。
+- PascalCase 类型名由 `typeToReactNode` 自动渲染为蓝色可点击链接，跳转到当前页类型定义或 `type-registry.ts` 注册的跨页锚点。
+- `default` 用字符串表示，如 `"'md'"`、`'false'`
+- `required: true` 仅在属性必填时添加
+
+#### 类型完整性规则（严格遵循）
+
+**核心原则：PropsTable / TypeTable 中出现的每一个非内置 PascalCase 类型名，都必须在当前页 `## 类型` 区域有对应定义，或在 `type-registry.ts` 中注册了跨页面链接。不允许出现"引用了但未定义"的类型。**
+
+检查清单（写完文档后逐项核对）：
+
+1. 遍历所有 `<PropsTable>` 的 `type` 字段，收集全部 PascalCase 类型名
+2. 遍历所有 `<TypeTable>` 的 `fields[].type`，收集全部 PascalCase 类型名
+3. 排除内置类型（`ReactNode`、`HTMLElement`、`Record`、`Partial` 等，见 `type-anchor.tsx` 的 `BUILTIN_TYPE_NAMES`）
+4. 对剩余的每一个类型名，确认以下之一成立：
+   - 在当前页的 `<TypeTable>` 中作为 `name` 定义
+   - 在当前页的 `<UnionType>` 中作为 `name` 定义
+   - 在 `type-registry.ts` 中注册了跨页面链接
+5. 如有遗漏，补充定义后再输出
+6. 如果遗漏类型只是短字面量联合类型（如 ThemeSize、ThemeColor、方向、位置、形状、简单状态），不要补 `<UnionType>`，应改为在 `type` 字段直接内联。
+
+特别注意：
+
+- **子组件 Props 类型**：如果组件有 `titleProps: AlertTitleProps`、`descriptionProps: AlertDescriptionProps` 等 props，这些类型也必须在 TypeTable 中定义，包含各自的字段列表
+- **组件本目录导出的 public 类型**：`index.ts` / `types.ts` 导出的 Props、ClassNames/Ui、Slots、ItemData、Option、Variant 等类型，都必须在当前页类型区定义或跨页注册
+- **封装依赖类型**：如果组件类型继承 `StyledComponentProps<T>`、`HTMLComponentProps<T>`、Radix Props、Vaul Props 等，需要在类型区说明这些包装类型和关键字段
+- **不要展开无关大类型**：如果引用外部组件的大型 Props（如 `ButtonProps`、`DropdownMenuProps`），且该类型不属于当前组件，可以只引用并通过 `type-registry.ts` 跨页链接；不要在当前页复制展开全部字段
+- **共享主题类型**：`ThemeColor`、`ThemeSize` 这类短联合直接内联；`ClassValue` 这类复杂类型可以在类型区保留定义。
+- **BUILTIN_TYPE_NAMES 维护**：如果文档中用到了 PascalCase 类型名但它并非当前组件定义的自定义类型（如 `DeepPartial`、`ElementType`、`StandardSchema`、`Values` 等泛型/外部类型），需要确认它已在 `type-anchor.tsx` 的 `BUILTIN_TYPE_NAMES` 中注册。如果没有注册，会生成错误的本地锚点链接。遇到这种情况需要将其添加到 `BUILTIN_TYPE_NAMES` 中。
+
+#### 常用内联类型（直接复制使用）
+
+以下类型在多数组件文档中都需要，按需取用：
+
+```mdx
+type: "'primary' | 'destructive' | 'success' | 'warning' | 'info' | 'carbon' | 'secondary' | 'accent'"
+
+type: "'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl'"
+
+<UnionType name="ClassValue" description="CSS 类名类型" type="string | null | undefined | Record<string, boolean> | ClassValue[]" />
+```
+
+#### 类型定义规则
+
+- 页面底部 `## 类型` 区域定义本页引用的所有非内置类型
+- `<TypeTable>` — 对象类型（有字段列表的类型，如 ClassNames、子组件 Props）
+- `<UnionType>` — 复杂联合、外部库派生类型、确实需要解释的类型定义；短字面量联合不要使用 `<UnionType>`，直接内联到表格
+- 类型名与 PropsTable 中的 `type` 字段一致，系统自动生成锚点 ID
+- 排列顺序建议：先 `<TypeTable>`（对象类型），再 `<UnionType>`（联合类型）
+
+#### 跨页面类型引用
+
+当 PropsTable 中引用了定义在**其他页面**的类型（如 AlertDialog 引用 ButtonProps）：
+
+1. 在 `apps/web-ui-docs/components/type-registry.ts` 中注册映射
+2. 格式：`TypeName: '/docs/components/target-page#anchor'`
+3. 无需在当前页重复定义该类型
+
+#### Demo 引用规则
+
+- 格式：`<Demo src="@playground/$slug/modules/DemoModuleName" />`
+- **每个功能章节必须有 Demo**，Demo 是文档的核心展示方式，不可省略
+- 优先复用 playground 中已经存在、能代表功能点的 demo
+- 引用 demo 前检查 demo 文件是否依赖本地 `./shared`、同目录模块、图片、路由组件或其他非 scope 内容
+- 如果 demo 不是自包含的，必须确认当前 Demo transformer / react-live 环境能处理这些 import
+- 如果不能处理，选择以下方式之一：
+  - 调整 playground demo 使其可在文档中运行
+  - 新增 docs 专用 demo
+  - 在最终说明中明确该 demo 存在运行时风险
+- 不允许假设所有 playground demo 都能被 react-live 直接执行
+
+#### 创建缺失的 Playground Demo（必须执行）
+
+当 playground `modules/` 目录不存在或缺少所需 demo 时，**必须创建**，不能因为缺 demo 而只写内联代码。
+
+**创建 demo 文件的规范：**
+
+1. 文件路径：`apps/web-ui-playground/src/app/[locale]/(demo)/$slug/modules/$DemoName.tsx`
+2. 文件结构模板：
+
+```tsx
+'use client';
+
+import { ... } from '@skyroc/web-ui';
+
+const $DemoName = () => {
+  // demo 实现
+  return (
+    <div className="...">
+      ...
+    </div>
+  );
+};
+
+export default $DemoName;
+```
+
+3. 创建规则：
+   - 必须添加 `'use client'` 指令
+   - 组件使用箭头函数 + PascalCase 命名
+   - 必须使用 `export default` 导出
+   - 从 `@skyroc/web-ui` 导入 UI 组件，不要从内部路径导入
+   - 图标从 `lucide-react` 导入
+   - 避免依赖外部 `shared.tsx`，demo 应自包含（如需共享常量直接内联到各 demo 中）
+   - 使用 tailwind 类名进行布局样式
+   - 每个 demo 聚焦展示一个功能点，保持简洁
+
+4. 同步 `page.tsx`：如果 `page.tsx` 不存在或未引用新 demo，需要一并创建/更新
+
+**判断流程：**
+
+```
+读取 playground/$slug/modules/ 目录
+  ├── 已有 demo 覆盖文档需要的功能点 → 直接引用
+  ├── 有 page.tsx 但缺少部分 demo → 补充缺失的 demo 模块
+  └── 目录不存在 → 创建全部 demo 模块 + page.tsx
+```
+
+#### react-live scope 注意事项
+
+Demo 在 `react-live` 沙箱中执行，scope 定义在 `apps/web-ui-docs/components/demo/scope.ts`。需注意：
+
+- scope 中同时导入了 `@skyroc/web-ui` 和 `lucide-react`，后者也导出部分同名组件（如 `Badge`）
+- 当前 scope 的赋值顺序保证 `@skyroc/web-ui` 优先（最后赋值覆盖同名导出）
+- 如果新增的组件名与 `lucide-react` 图标同名，需确认 scope 中不存在冲突，或调整赋值顺序
+
+#### 工作区边界
+
+- 默认只新增或修改目标文档 `apps/web-ui-docs/content/docs/components/$slug.mdx`
+- 不要回滚、格式化或整理与当前组件文档无关的用户改动
+- 如果组件源码已有未提交改动，必须基于当前工作区实现写文档
+- 只有当实现问题会导致文档无法正确描述组件时，才修改组件源码或类型；修改前先说明发现的问题
+- 最终回复中要明确区分：本次修改的文件、已有但未处理的工作区改动、验证结果或未验证原因
+
+## 参考范例
+
+以 `apps/web-ui-docs/content/docs/components/alert.mdx` 为首选参考，`button.mdx` 为辅助参考。
+
+`alert.mdx` 展示了完整的类型引用模式：PropsTable 使用类型名引用 → 类型区包含全部 TypeTable 和 UnionType 定义 → 无遗漏。