@coffic/cosy-ui 0.6.38 → 0.6.40

package/dist/card/CardCourse.astro

@@ -0,0 +1,32 @@
+---
+import { Image } from 'astro:assets';
+import bookCover from '../assets/book.png';
+
+interface Props {
+	title: string;
+	link: string;
+}
+
+const { title, link } = Astro.props;
+---
+
+<div>
+	<a href={link} class="justify-center flex no-underline text-base-content">
+		<div class="w-56 h-80">
+			<div
+				class="bg-gradient-to-br w-full h-full from-accent/50 to-primary/30 rounded-3xl shadow-lg backdrop-blur-sm">
+				<div
+					class="bg-base-100/60 w-full h-full rounded-3xl border border-base-content/30 hover:scale-105 hover:shadow-2xl transform duration-200 backdrop-filter backdrop-blur-sm">
+					<div class="card-body p-1 h-full">
+						<Image src={bookCover} alt={title} class="h-3/5 w-full" />
+						<div>
+							<h2 class="text-lg text-center font-medium">
+								{title}
+							</h2>
+						</div>
+					</div>
+				</div>
+			</div>
+		</div>
+	</a>
+</div>

package/dist/card/index.ts

@@ -1,6 +1,6 @@
 
-
 export { default as Card } from './Card.astro';
+export { default as CardCourse } from './CardCourse.astro';
 export { default as CardBasic } from './CardBasic.astro';
 export { default as CardWithImage } from './CardWithImage.astro';
 export { default as CardLink } from './CardLink.astro';

package/dist/cosy.ts

@@ -0,0 +1,6 @@
+import { Logger } from './utils/logger';
+
+export const NAME = 'Cosy-UI';
+export const ERROR_PREFIX = 'Cosy-UI: ';
+
+export const cosyLogger = new Logger(NAME);

package/dist/database/BaseDB.ts

@@ -1,5 +1,6 @@
 import { getCollection, getEntry, type CollectionEntry, type DataEntryMap } from 'astro:content';
-import { logger } from '../utils/logger';
+import { cosyLogger, ERROR_PREFIX } from '../cosy';
+import type { BaseDoc } from '..';
 
 /**
  * BaseDB 是所有数据库类的基类，提供了通用的文档操作功能。
@@ -24,172 +25,207 @@ import { logger } from '../utils/logger';
  * @template Doc - 文档类型，通常是自定义的文档类
  */
 export abstract class BaseDB<
-	Collection extends keyof DataEntryMap,
-	Entry extends CollectionEntry<Collection>,
-	Doc,
+    Collection extends keyof DataEntryMap,
+    Entry extends CollectionEntry<Collection>,
+    Doc extends BaseDoc<Collection, Entry>,
 > {
-	/** 集合名称，必须在子类中指定 */
-	protected abstract collectionName: Collection;
-
-	/**
-	 * 创建文档实例的方法，必须在子类中实现
-	 * @param entry - 集合条目
-	 * @returns 文档实例
-	 */
-	protected abstract createDoc(entry: Entry): Doc;
-
-	/**
-	 * 获取所有文档的ID
-	 * @returns 返回所有文档的ID数组
-	 */
-	async getAllIds(): Promise<string[]> {
-		const entries = await getCollection(this.collectionName);
-		return entries.map((entry) => entry.id);
-	}
-
-	/**
-	 * 获取集合中的所有条目
-	 * @returns 返回所有条目的数组
-	 */
-	async getEntries(): Promise<Entry[]> {
-		const entries = await getCollection(this.collectionName);
-		return entries.map((entry) => entry as Entry);
-	}
-
-	/**
-	 * 获取指定深度的文档
-	 * 深度是指文档 ID 中斜杠的数量加1
-	 * 例如：
-	 * - "blog.md" 深度为1
-	 * - "zh-cn/blog.md" 深度为2
-	 * - "zh-cn/tech/blog.md" 深度为3
-	 *
-	 * @param depth - 文档深度
-	 * @returns 返回指定深度的文档数组
-	 */
-	async getDocsByDepth(depth: number): Promise<Doc[]> {
-		const entries = await getCollection(
-			this.collectionName,
-			({ id }) => id.split('/').length === depth
-		);
-		return entries.map((entry) => this.createDoc(entry as Entry));
-	}
-
-	/**
-	 * 根据ID查找单个文档
-	 * @param id - 文档ID
-	 * @returns 返回找到的文档，如果不存在则返回null
-	 */
-	async find(id: string): Promise<Doc | null> {
-		const debug = false;
-		if (debug) {
-			logger.info(`查找文档，ID: ${id}`);
-		}
-
-		if (typeof id !== 'string') {
-			throw new Error('ID must be a string, but got ' + typeof id);
-		}
-
-		// 获取所有文档的ID并排好顺序
-		if (debug) {
-			const allIds = (await this.getAllIds()).sort();
-			logger.array('所有文档的ID', allIds);
-		}
-
-		// 根据ID查找文档
-		const entry = await getEntry(this.collectionName, id);
-		return entry ? this.createDoc(entry as Entry) : null;
-	}
-
-	/**
-	 * 获取指定文档的直接子文档（不包括更深层级的文档）
-	 * 例如对于文档 "zh-cn/blog"：
-	 * - "zh-cn/blog/post1.md" 会被包含
-	 * - "zh-cn/blog/2024/post2.md" 不会被包含
-	 *
-	 * @param parentId - 父文档ID
-	 * @returns 返回子文档数组
-	 */
-	async getChildren(parentId: string): Promise<Doc[]> {
-		const parentLevel = parentId.split('/').length;
-		const childrenLevel = parentLevel + 1;
-
-		const entries = await getCollection(
-			this.collectionName,
-			({ id }) => id.startsWith(parentId) && id.split('/').length === childrenLevel
-		);
-
-		return entries.map((entry) => this.createDoc(entry as Entry));
-	}
-
-	/**
-	 * 获取指定文档的所有后代文档（包括所有层级）
-	 * 例如对于文档 "zh-cn/blog"，以下都会被包含：
-	 * - "zh-cn/blog/post1.md"
-	 * - "zh-cn/blog/2024/post2.md"
-	 * - "zh-cn/blog/2024/tech/post3.md"
-	 *
-	 * @param parentId - 父文档ID
-	 * @returns 返回所有后代文档数组
-	 */
-	async getDescendantDocs(parentId: string): Promise<Doc[]> {
-		const entries = await getCollection(this.collectionName, ({ id }) => id.startsWith(parentId));
-		return entries.map((entry) => this.createDoc(entry as Entry));
-	}
-
-	/**
-	 * 获取指定语言的顶级文档
-	 * 通过检查文档ID是否以指定语言代码开头来筛选
-	 *
-	 * @param lang - 语言代码（如 'zh-cn', 'en'）
-	 * @returns 返回指定语言的顶级文档数组
-	 */
-	async allDocsByLang(lang: string): Promise<Doc[]> {
-		const debug = false;
-		const docs = await this.getDocsByDepth(2);
-
-		if (debug) {
-			logger.array('所有顶级文档', docs);
-		}
-
-		return docs.filter((doc) => {
-			const id = (doc as any).getId();
-			return id && typeof id === 'string' && id.startsWith(lang);
-		});
-	}
-
-	/**
-	 * 获取用于 Astro 静态路由生成的路径参数
-	 * 为每个文档生成包含语言和slug的路径参数
-	 *
-	 * @returns 返回路径参数数组，每个元素包含 lang 和 slug
-	 * @example
-	 * ```typescript
-	 * const paths = await db.getStaticPaths();
-	 * // 返回格式：
-	 * // [
-	 * //   { params: { lang: 'zh-cn', slug: 'post1' } },
-	 * //   { params: { lang: 'en', slug: 'post1' } }
-	 * // ]
-	 * ```
-	 */
-	async getStaticPaths() {
-		const debug = false;
-		const docs = await this.getDescendantDocs('');
-		const paths = docs.map((doc) => {
-			const docWithMethods = doc as any;
-			return {
-				params: {
-					lang: docWithMethods.getLang?.() || '',
-					slug: docWithMethods.getSlug?.() || '',
-				},
-			};
-		});
-
-		if (debug) {
-			logger.array('所有文档的路径', paths);
-		}
-
-		return paths;
-	}
+    /** 集合名称，必须在子类中指定 */
+    protected abstract collectionName: Collection;
+
+    /**
+     * 创建文档实例的方法，必须在子类中实现
+     * @param entry - 集合条目
+     * @returns 文档实例
+     */
+    protected abstract createDoc(entry: Entry): Doc;
+
+    /**
+     * 获取所有文档的ID
+     * @returns 返回所有文档的ID数组
+     */
+    protected async getAllIds(): Promise<string[]> {
+        const entries = await getCollection(this.collectionName);
+        return entries.map(entry => entry.id);
+    }
+
+    /**
+     * 获取集合中的所有条目
+     * @returns 返回所有条目的数组
+     */
+    protected async getEntries(): Promise<Entry[]> {
+        return await getCollection(this.collectionName);
+    }
+
+    /**
+     * 获取指定深度的文档
+     * 深度是指文档 ID 中斜杠的数量加1
+     * 例如：
+     * - "blog.md" 深度为1
+     * - "zh-cn/blog.md" 深度为2
+     * - "zh-cn/tech/blog.md" 深度为3
+     *
+     * @param depth - 文档深度
+     * @returns 返回指定深度的文档数组
+     */
+    protected async getDocsByDepth(depth: number): Promise<Doc[]> {
+        const entries = await getCollection(
+            this.collectionName,
+            ({ id }: { id: string }) => id.split('/').length === depth
+        );
+
+        if (entries.length === 0) {
+            cosyLogger.warn(`[BaseDB] 没有找到深度为${depth}的文档(collection=${this.collectionName as string})`);
+            const allEntries = await getCollection(this.collectionName);
+            cosyLogger.array('[BaseDB] 所有文档', allEntries.map(entry => entry.id));
+            return [];
+        }
+
+        return entries.map(entry => this.createDoc(entry as Entry));
+    }
+
+    /**
+     * 根据ID查找单个文档
+     * @param id - 文档ID
+     * @param debug - 是否启用调试模式, 默认为false
+     * @throws 如果ID不是字符串类型，则抛出错误
+     * @throws 如果文档不存在，则返回null
+     * @throws 如果发生其他错误，则抛出错误
+     * @returns 返回找到的文档，如果不存在则返回null
+     */
+    async find(id: string, debug: boolean = false): Promise<Doc | null> {
+        if (debug) {
+            cosyLogger.info(`查找文档，ID: ${id}`);
+        }
+
+        if (id == undefined) {
+            cosyLogger.error('ID is undefined');
+            throw new Error(ERROR_PREFIX + 'ID is undefined');
+        }
+
+        if (typeof id !== 'string') {
+            cosyLogger.error('ID must be a string, but got ' + typeof id);
+            cosyLogger.debug(id);
+            throw new Error(ERROR_PREFIX + 'ID must be a string, but got ' + typeof id);
+        }
+
+        // 获取所有文档的ID并排好顺序
+        if (debug) {
+            const allIds = (await this.getAllIds()).sort();
+            cosyLogger.array('所有文档的ID', allIds);
+        }
+
+        // 根据ID查找文档
+        const entry = await getEntry(this.collectionName, id);
+        return entry ? this.createDoc(entry as Entry) : null;
+    }
+
+    /**
+     * 获取指定文档的直接子文档（不包括更深层级的文档）
+     * 例如对于文档 "zh-cn/blog"：
+     * - "zh-cn/blog/post1.md" 会被包含
+     * - "zh-cn/blog/2024/post2.md" 不会被包含
+     *
+     * @param parentId - 父文档ID
+     * @returns 返回子文档数组
+     */
+    async getChildren(parentId: string): Promise<Doc[]> {
+        const parentLevel = parentId.split('/').length;
+        const childrenLevel = parentLevel + 1;
+
+        const entries = await getCollection(
+            this.collectionName,
+            ({ id }: { id: string }) => id.startsWith(parentId) && id.split('/').length === childrenLevel
+        );
+
+        return entries.map(entry => this.createDoc(entry as Entry));
+    }
+
+    /**
+     * 获取指定文档的所有后代文档（包括所有层级）
+     * 例如对于文档 "zh-cn/blog"，以下都会被包含：
+     * - "zh-cn/blog/post1.md"
+     * - "zh-cn/blog/2024/post2.md"
+     * - "zh-cn/blog/2024/tech/post3.md"
+     *
+     * @param parentId - 父文档ID
+     * @returns 返回所有后代文档数组
+     */
+    async getDescendantDocs(parentId: string): Promise<Doc[]> {
+        const entries = await getCollection(this.collectionName, ({ id }: { id: string }) => id.startsWith(parentId));
+        return entries.map(entry => this.createDoc(entry as Entry));
+    }
+
+    /**
+     * 获取指定语言和级别的文档
+     * 通过检查文档ID是否以指定语言代码开头来筛选
+     *
+     * @param lang - 语言代码（如 'zh-cn', 'en'）
+     * @param level - 文档级别
+     * @returns 返回指定语言和级别的文档数组
+     */
+    protected async allDocsByLangAndLevel(lang: string, level: number = 1, debug: boolean = false): Promise<Doc[]> {
+        const collectionName = this.collectionName as string;
+        const docs = await this.getDocsByDepth(level);
+
+        if (debug) {
+            cosyLogger.array(`[BaseDB] 所有${level}级文档(lang=any,collection=${collectionName})`, docs);
+        }
+
+        if (docs.length === 0) {
+            cosyLogger.warn(`[BaseDB] 没有找到${level}级文档(lang=any,collection=${collectionName})`);
+            return [];
+        }
+
+        const filteredDocs = docs.filter((doc) => {
+            const id = (doc as any).getId();
+            return id && typeof id === 'string' && id.startsWith(lang);
+        });
+
+        if (debug) {
+            cosyLogger.array(`[BaseDB] 所有${level}级文档(lang=${lang},collection=${collectionName})`, filteredDocs);
+        }
+
+        if (filteredDocs.length === 0) {
+            cosyLogger.warn(`[BaseDB] 没有找到${level}级文档(lang=${lang},collection=${collectionName})`);
+            cosyLogger.array(`[BaseDB] 所有${level}级文档`, docs.map((doc) => doc.getId()));
+            return [];
+        }
+
+        return filteredDocs;
+    }
+
+    /**
+     * 获取用于 Astro 静态路由生成的路径参数
+     * 为每个文档生成包含语言和slug的路径参数
+     *
+     * @returns 返回路径参数数组，每个元素包含 lang 和 slug
+     * @example
+     * ```typescript
+     * const paths = await db.getStaticPaths();
+     * // 返回格式：
+     * // [
+     * //   { params: { lang: 'zh-cn', slug: 'post1' } },
+     * //   { params: { lang: 'en', slug: 'post1' } }
+     * // ]
+     * ```
+     */
+    async getStaticPaths() {
+        const debug = false;
+        const docs = await this.getDescendantDocs('');
+        const paths = docs.map((doc) => {
+            const docWithMethods = doc as any;
+            return {
+                params: {
+                    lang: docWithMethods.getLang?.() || '',
+                    slug: docWithMethods.getSlug?.() || '',
+                },
+            };
+        });
+
+        if (debug) {
+            cosyLogger.array('所有文档的路径', paths);
+        }
+
+        return paths;
+    }
 }

package/dist/database/BlogDB.ts

@@ -1,6 +1,6 @@
 import BlogDoc from '../entities/BlogDoc';
 import type Tag from '../entities/Tag';
-import { logger } from '../utils/logger';
+import { cosyLogger } from '../cosy';
 import { type CollectionEntry } from 'astro:content';
 import { BaseDB } from './BaseDB';
 
@@ -40,7 +40,7 @@ class BlogDB extends BaseDB<typeof COLLECTION_BLOG, BlogEntry, BlogDoc> {
 		const entries = await this.getDocsByDepth(2);
 
 		if (debug) {
-			logger.array('所有博客文档', entries);
+			cosyLogger.array('所有博客文档', entries);
 		}
 
 		return entries;
@@ -62,10 +62,10 @@ class BlogDB extends BaseDB<typeof COLLECTION_BLOG, BlogEntry, BlogDoc> {
 	/**
 	 * 获取用于 Astro 静态路由生成的路径参数，专门配合 [lang]/blogs/[slug].astro 使用
 	 *
+	 * @param debug - 是否开启调试模式
 	 * @returns 返回路径参数数组
 	 */
-	async getStaticPaths() {
-		const debug = false;
+	async getStaticPaths(debug: boolean = false) {
 		const docs = await this.allBlogs();
 
 		const paths = docs.map((doc) => {
@@ -78,7 +78,7 @@ class BlogDB extends BaseDB<typeof COLLECTION_BLOG, BlogEntry, BlogDoc> {
 		});
 
 		if (debug) {
-			logger.array('所有博客文档的路径', paths);
+			cosyLogger.array('所有博客文档的路径', paths);
 		}
 
 		return paths;
@@ -123,7 +123,7 @@ class BlogDB extends BaseDB<typeof COLLECTION_BLOG, BlogEntry, BlogDoc> {
 		const posts = await this.allBlogsByLang(lang);
 
 		if (debug) {
-			logger.array('posts', posts);
+			cosyLogger.array('posts', posts);
 		}
 
 		if (posts.length === 0) {
@@ -140,7 +140,7 @@ class BlogDB extends BaseDB<typeof COLLECTION_BLOG, BlogEntry, BlogDoc> {
 		});
 
 		if (debug) {
-			logger.array('tags', Array.from(tagsMap.values()));
+			cosyLogger.array('tags', Array.from(tagsMap.values()));
 		}
 
 		return Array.from(tagsMap.values());
@@ -187,7 +187,7 @@ class BlogDB extends BaseDB<typeof COLLECTION_BLOG, BlogEntry, BlogDoc> {
 		});
 
 		if (debug) {
-			logger.array('所有的标签路径', paths);
+			cosyLogger.array('所有的标签路径', paths);
 		}
 
 		return paths;

package/dist/database/CourseDB.ts

@@ -11,9 +11,9 @@ export type CourseEntry = CollectionEntry<typeof COLLECTION_COURSE>;
  * 目录结构：
  * ```
  * courses/
- * ├── zh-cn/
- * │   ├── web-development/
- * │   │   ├── index.md
+ * ├── zh-cn/                  # 中文版本
+ * │   ├── web-development/    # 课程1
+ * │   │   ├── index.md        # 课程文档
  * │   │   ├── chapter1
  * │   │   │   ├── index.md
  * │   │   │   ├── content.md
@@ -22,10 +22,10 @@ export type CourseEntry = CollectionEntry<typeof COLLECTION_COURSE>;
  * │   │       ├── index.md
  * │   │       ├── content.md
  * │   │       └── ...
- * │   └── mobile-dev/
+ * │   └── mobile-dev/        # 课程2
  * │       ├── index.md
  * │       └── ...
- * └── en/
+ * └── en/                    # 英文版本
  *     └── ...
  * ```
  */

package/dist/database/ExperimentDB.ts

@@ -1,7 +1,7 @@
 import { type CollectionEntry } from 'astro:content';
 import { BaseDB } from './BaseDB';
 import ExperimentDoc from '../entities/ExperimentDoc';
-import { logger } from '../utils/logger';
+import { cosyLogger } from '../cosy';
 
 export const COLLECTION_EXPERIMENT = 'experiments' as const;
 export type ExperimentEntry = CollectionEntry<typeof COLLECTION_EXPERIMENT>;
@@ -13,7 +13,7 @@ export type ExperimentEntry = CollectionEntry<typeof COLLECTION_EXPERIMENT>;
  * ```
  * experiments/
  * ├── safari_itp/           # 实验目录
- * │   ├── images/          # 实验图片资源
+ * │   ├── images/           # 实验图片资源
  * │   ├── components/                  # 课程组件
  * │   ├── en/                          # 英文版本
  * │   │   ├── index.mdx                # 课程首页
@@ -61,14 +61,14 @@ class ExperimentDB extends BaseDB<typeof COLLECTION_EXPERIMENT, ExperimentEntry,
 	/**
 	 * 获取用于 Astro 静态路由生成的路径参数
 	 *
+	 * @param debug - 是否开启调试模式
 	 * @returns 返回路径参数数组
 	 */
-	async getStaticPaths() {
-		const debug = false;
+	async getStaticPaths(debug: boolean = false) {
 		const docs = await this.getEntries();
 
 		if (debug) {
-			logger.array('所有文档', docs);
+			cosyLogger.array('所有文档', docs);
 		}
 
 		const paths = docs.map((doc) => {
@@ -91,7 +91,7 @@ class ExperimentDB extends BaseDB<typeof COLLECTION_EXPERIMENT, ExperimentEntry,
 		});
 
 		if (debug) {
-			logger.array('所有文档的路径', paths);
+			cosyLogger.array('所有文档的路径', paths);
 		}
 
 		return paths;

package/dist/database/LessonDB.ts

@@ -1,7 +1,7 @@
 import { type CollectionEntry } from 'astro:content';
 import { BaseDB } from './BaseDB';
 import LessonDoc from '../entities/LessonDoc';
-import { logger } from '../utils/logger';
+import { cosyLogger } from '../cosy';
 
 export const COLLECTION_LESSON = 'lessons' as const;
 export type LessonEntry = CollectionEntry<typeof COLLECTION_LESSON>;
@@ -60,15 +60,15 @@ class LessonDB extends BaseDB<typeof COLLECTION_LESSON, LessonEntry, LessonDoc>
 
 	/**
 	 * 获取用于 Astro 静态路由生成的路径参数
-	 *
+	 * 
+	 * @param debug - 是否开启调试模式
 	 * @returns 返回路径参数数组
 	 */
-	async getStaticPaths() {
-		const debug = false;
+	async getStaticPaths(debug: boolean = false) {
 		const docs = await this.getEntries();
 
 		if (debug) {
-			logger.array('所有文档', docs);
+			cosyLogger.array('所有文档', docs);
 		}
 
 		const paths = docs.map((doc) => {
@@ -91,7 +91,7 @@ class LessonDB extends BaseDB<typeof COLLECTION_LESSON, LessonEntry, LessonDoc>
 		});
 
 		if (debug) {
-			logger.array('所有文档的路径', paths);
+			cosyLogger.array('所有文档的路径', paths);
 		}
 
 		return paths;

package/dist/database/MetaDB.ts

@@ -1,5 +1,5 @@
 import MetaDoc from '../entities/MetaDoc';
-import { logger } from '../utils/logger';
+import { cosyLogger } from '../cosy';
 import { type CollectionEntry } from 'astro:content';
 import { BaseDB } from './BaseDB';
 
@@ -47,10 +47,10 @@ class MetaDB extends BaseDB<typeof COLLECTION_META, MetaEntry, MetaDoc> {
 	/**
 	 * 获取用于 Astro 静态路由生成的路径参数，专门配合 [lang]/meta/[slug].astro 使用
 	 *
+	 * @param debug - 是否开启调试模式
 	 * @returns 返回路径参数数组
 	 */
-	async getStaticPaths() {
-		const debug = false;
+	async getStaticPaths(debug: boolean = false) {
 		const docs = await this.getDescendantDocs('');
 
 		const paths = docs.map((doc) => {
@@ -63,7 +63,7 @@ class MetaDB extends BaseDB<typeof COLLECTION_META, MetaEntry, MetaDoc> {
 		});
 
 		if (debug) {
-			logger.array('所有元数据文档的路径', paths);
+			cosyLogger.array('所有元数据文档的路径', paths);
 		}
 
 		return paths;

package/dist/entities/BaseDoc.ts

@@ -1,6 +1,6 @@
 import { render, type RenderResult, type CollectionEntry, type DataEntryMap } from 'astro:content';
 import { SidebarItemEntity, type SidebarProvider } from './SidebarItem';
-import { logger } from '../utils/logger';
+import { cosyLogger, ERROR_PREFIX } from '../cosy';
 
 /**
  * 文档基类，提供所有文档类型共享的基本功能
@@ -8,8 +8,7 @@ import { logger } from '../utils/logger';
 export abstract class BaseDoc<
 	Collection extends keyof DataEntryMap,
 	T extends CollectionEntry<Collection>,
-> implements SidebarProvider
-{
+> implements SidebarProvider {
 	protected entry: T;
 
 	constructor(entry: T) {
@@ -54,6 +53,28 @@ export abstract class BaseDoc<
 	 */
 	getAncestorId(level: number): string {
 		const ancestorIds = this.getAncestorIds();
+
+		if (level < 1) {
+			cosyLogger.error('Level must be greater than 0');
+			throw new Error(ERROR_PREFIX + 'Level must be greater than 0');
+		}
+
+		if (level >= this.getLevel()) {
+			cosyLogger.debug("当前文档的ID：" + this.entry.id);
+			cosyLogger.debug("当前文档的Level：" + this.getLevel());
+			cosyLogger.debug("正在获取祖先ID，level：" + level);
+
+			throw new Error(ERROR_PREFIX + 'Level must be less than the document level');
+		}
+
+		if (ancestorIds.length < level) {
+			cosyLogger.debug("当前文档的ID\n" + this.entry.id);
+			cosyLogger.array("当前文档的祖先IDs", ancestorIds);
+			cosyLogger.debug("正在获取祖先ID，level:\n" + level);
+
+			throw new Error(ERROR_PREFIX + 'Level must be greater than 0');
+		}
+
 		return ancestorIds[level - 1];
 	}
 
@@ -93,6 +114,12 @@ export abstract class BaseDoc<
 	 * 子类可以根据需要覆盖此方法
 	 */
 	getTopDocId(): string {
+		const level = this.getLevel();
+
+		if (level <= 2) {
+			return this.entry.id;
+		}
+
 		return this.getAncestorId(2);
 	}
 
@@ -155,7 +182,7 @@ export abstract class BaseDoc<
 		const childItems = await Promise.all(children.map((child) => child.toSidebarItem()));
 
 		if (debug) {
-			logger.info(`${this.entry.id} 的侧边栏项目`);
+			cosyLogger.info(`${this.entry.id} 的侧边栏项目`);
 			console.log(childItems);
 		}
 

package/dist/entities/BlogDoc.ts

@@ -5,6 +5,46 @@ import { BaseDoc } from './BaseDoc';
 import { COLLECTION_BLOG } from '../database/BlogDB';
 import { blogDB } from '../database/BlogDB';
 
+/**
+ * 博客文档类，配合 BlogDB 使用
+ * 
+ * 目录结构：
+ * ```
+ * blogs/
+ * ├── zh-cn/                        # 中文博客目录
+ * │   ├── typescript-intro.md      # 文章内容
+ * │   ├── images/                  # 文章相关图片
+ * │   └── web-performance.md
+ * └── en/                          # 英文博客目录
+ *     ├── typescript-intro.md
+ *     ├── images/
+ *     └── web-performance.md
+ * ```
+ *
+ * 说明：
+ * - 每个语言（如 zh-cn, en）是一个独立的目录，存放该语言下的所有博客文章
+ * - 每篇博客为一个 markdown 文件，文件名即为 slug
+ * - 每个语言目录下可包含 images 文件夹，存放该语言博客相关图片
+ * - 支持多语言博客内容，便于国际化
+ * - 博客目录可作为 git 子模块独立管理
+ *
+ * 相关：
+ * - BlogDB：博客数据库管理类，负责博客文档的增删查改
+ * - BlogDoc：博客文档实体类，封装单篇博客的相关操作
+ *
+ * 用法示例：
+ * ```typescript
+ * import BlogDoc from '../entities/BlogDoc';
+ * import { blogDB } from '../database/BlogDB';
+ *
+ * // 获取所有中文博客
+ * const blogs = await blogDB.allBlogsByLang('zh-cn');
+ *
+ * // 获取博客链接
+ * const link = blogs[0].getLink();
+ * ```
+ */
+
 export default class BlogDoc extends BaseDoc<typeof COLLECTION_BLOG, BlogEntry> {
 	private constructor(entry: BlogEntry) {
 		super(entry);

package/dist/entities/CourseDoc.ts

@@ -1,4 +1,4 @@
-import { logger } from '../utils/logger';
+import { cosyLogger } from '../cosy';
 import { SidebarItemEntity } from './SidebarItem';
 import type { CourseEntry } from '../database/CourseDB';
 import { courseDB } from '../database/CourseDB';
@@ -36,12 +36,12 @@ export default class CourseDoc extends BaseDoc<typeof COLLECTION_COURSE, CourseE
 	async getAncestor(level: number): Promise<CourseDoc | null> {
 		const debug = false;
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的祖先文档，level: ${level}`);
+			cosyLogger.info(`获取 ${this.entry.id} 的祖先文档，level: ${level}`);
 		}
 
 		if (level >= this.getLevel()) {
 			if (debug) {
-				logger.info(`祖先文档为自身`);
+				cosyLogger.info(`祖先文档为自身`);
 			}
 			return this;
 		}
@@ -61,7 +61,7 @@ export default class CourseDoc extends BaseDoc<typeof COLLECTION_COURSE, CourseE
 			(a, b) => a.getOrder() - b.getOrder()
 		);
 		if (debug && children.length > 0) {
-			logger.array(
+			cosyLogger.array(
 				`${this.entry.id} 的子文档(${children.length})`,
 				children.map((child) => `#${child.getOrder()} ${child.entry.id}`)
 			);
@@ -79,7 +79,7 @@ export default class CourseDoc extends BaseDoc<typeof COLLECTION_COURSE, CourseE
 		}
 
 		if (debug) {
-			logger.info(`${this.entry.id} 的侧边栏项目`);
+			cosyLogger.info(`${this.entry.id} 的侧边栏项目`);
 			console.log(childItems);
 		}
 

package/dist/entities/ExperimentDoc.ts

@@ -1,6 +1,6 @@
 import type { ExperimentEntry } from '../database/ExperimentDB';
 import { experimentDB } from '../database/ExperimentDB';
-import { logger } from '../utils/logger';
+import { cosyLogger } from '../cosy';
 import { SidebarItemEntity } from './SidebarItem';
 import { LinkUtil } from '../utils/link';
 import { COLLECTION_EXPERIMENT } from '../database/ExperimentDB';
@@ -31,7 +31,7 @@ export default class ExperimentDoc extends BaseDoc<typeof COLLECTION_EXPERIMENT,
 		const link = LinkUtil.getExperimentLink(lang, this.getId());
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的链接: ${link}`);
+			cosyLogger.info(`获取 ${this.entry.id} 的链接: ${link}`);
 		}
 
 		return link;
@@ -51,7 +51,7 @@ export default class ExperimentDoc extends BaseDoc<typeof COLLECTION_EXPERIMENT,
 		const lang = parts[1];
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的语言: ${lang}`);
+			cosyLogger.info(`获取 ${this.entry.id} 的语言: ${lang}`);
 		}
 
 		return lang;
@@ -61,7 +61,7 @@ export default class ExperimentDoc extends BaseDoc<typeof COLLECTION_EXPERIMENT,
 		const debug = false;
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的 HTML`);
+			cosyLogger.info(`获取 ${this.entry.id} 的 HTML`);
 		}
 
 		return this.entry.rendered?.html || '';
@@ -71,7 +71,7 @@ export default class ExperimentDoc extends BaseDoc<typeof COLLECTION_EXPERIMENT,
 		const debug = false;
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的 headings`);
+			cosyLogger.info(`获取 ${this.entry.id} 的 headings`);
 		}
 
 		return (this.entry.rendered?.metadata?.headings as IHeadingType[]) || [];
@@ -101,7 +101,7 @@ export default class ExperimentDoc extends BaseDoc<typeof COLLECTION_EXPERIMENT,
 		}
 
 		if (debug) {
-			logger.info(`${this.entry.id} 的侧边栏项目`);
+			cosyLogger.info(`${this.entry.id} 的侧边栏项目`);
 			console.log(childItems);
 		}
 

package/dist/entities/LessonDoc.ts

@@ -1,12 +1,46 @@
 import type { LessonEntry } from '../database/LessonDB';
 import { lessonDB } from '../database/LessonDB';
-import { logger } from '../utils/logger';
+import { cosyLogger } from '../cosy';
 import { SidebarItemEntity } from './SidebarItem';
 import { LinkUtil } from '../utils/link';
 import { COLLECTION_LESSON } from '../database/LessonDB';
 import { BaseDoc } from './BaseDoc';
 import type { IHeadingType } from '../types/heading';
 
+/**
+ * 课程文档类，配合 LessonDB 使用
+ * 
+ * 目录结构：
+ * ```
+ * lessons/
+ * ├── build_your_own_web_toolbox/      # 课程目录
+ * │   ├── images/                      # 课程图片资源
+ * │   ├── components/                  # 课程组件
+ * │   ├── en/                          # 英文版本
+ * │   │   ├── index.mdx                # 课程首页
+ * │   │   ├── 1.mdx                    # 第一章
+ * │   │   └── 2.mdx                    # 第二章
+ * │   └── zh-cn/                       # 中文版本
+ * │       ├── index.mdx                # 课程首页
+ * │       ├── 1.mdx                    # 第一章
+ * │       └── 2.mdx                    # 第二章
+ * └── learn_astro/                     # 另一个课程
+ *     ├── en/
+ *     │   ├── index.mdx
+ *     │   ├── 1.mdx
+ *     │   └── 2.mdx
+ *     └── zh-cn/
+ *         ├── index.mdx
+ *         ├── 1.mdx
+ *         └── 2.mdx
+ * ```
+ *
+ * 说明：
+ * - 每个课程（如 build_your_own_web_toolbox）是一个独立的目录
+ * - 课程目录可以包含多语言版本（en, zh-cn 等）
+ * - 每个语言版本包含完整的课程内容
+ * - 课程目录可以作为 git 子模块独立管理
+ */
 export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonEntry> {
 	constructor(entry: LessonEntry) {
 		super(entry);
@@ -31,7 +65,7 @@ export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonE
 		const link = LinkUtil.getLessonLink(lang, this.getId());
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的链接: ${link}`);
+			cosyLogger.info(`获取 ${this.entry.id} 的链接: ${link}`);
 		}
 
 		return link;
@@ -51,7 +85,7 @@ export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonE
 		const lang = parts[1];
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的语言: ${lang}`);
+			cosyLogger.info(`获取 ${this.entry.id} 的语言: ${lang}`);
 		}
 
 		return lang;
@@ -61,7 +95,7 @@ export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonE
 		const debug = false;
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的 HTML`);
+			cosyLogger.info(`获取 ${this.entry.id} 的 HTML`);
 		}
 
 		return this.entry.rendered?.html || '';
@@ -71,7 +105,7 @@ export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonE
 		const debug = false;
 
 		if (debug) {
-			logger.info(`获取 ${this.entry.id} 的 headings`);
+			cosyLogger.info(`获取 ${this.entry.id} 的 headings`);
 		}
 
 		return (this.entry.rendered?.metadata?.headings as IHeadingType[]) || [];
@@ -101,7 +135,7 @@ export default class LessonDoc extends BaseDoc<typeof COLLECTION_LESSON, LessonE
 		}
 
 		if (debug) {
-			logger.info(`${this.entry.id} 的侧边栏项目`);
+			cosyLogger.info(`${this.entry.id} 的侧边栏项目`);
 			console.log(childItems);
 		}
 

package/dist/index.ts

@@ -1,3 +1,3 @@
 export * from './index_astro';
 export * from './index_utils';
-export * from './index_icons';
+export * from './index_icons';

package/dist/utils/language.ts

@@ -1,16 +1,15 @@
-/**
- * 语言工具模块
- *
- * 提供语言相关的工具函数，用于多语言支持
- */
-
 import { getRelativeLocaleUrl } from 'astro:i18n';
-import { logger } from './logger';
 import type { AstroGlobal } from 'astro';
+import { cosyLogger } from '../cosy';
 
 // 默认语言
 export const DEFAULT_LANGUAGE = 'en';
 
+/**
+ * 语言工具模块
+ *
+ * 提供语言相关的工具函数，用于多语言支持
+ */
 export class LanguageUtil {
 	static getRelativeLink(locale: string, astro: AstroGlobal): string {
 		const debug = false;
@@ -19,7 +18,7 @@ export class LanguageUtil {
 		const result = getRelativeLocaleUrl(locale, originalPath.replaceAll('/' + currentLocale, ''));
 
 		if (debug) {
-			logger.debug(
+			cosyLogger.debug(
 				`getRelativeLink: locale=${locale}, currentPath=${originalPath}, currentLocale=${currentLocale}, result=${result}`
 			);
 		}

package/dist/utils/link.ts

@@ -1,4 +1,4 @@
-import { logger } from './logger';
+import { cosyLogger } from '../cosy';
 
 export class LinkUtil {
 	// 从 astro.config.ts 中获取基础路径
@@ -78,7 +78,7 @@ export class LinkUtil {
 		const blogIdWithoutLang = blogId.replace(`${lang}/`, '');
 
 		if (debug) {
-			logger.info(`获取博客文档链接，博客文档ID: ${blogId}`);
+			cosyLogger.info(`获取博客文档链接，博客文档ID: ${blogId}`);
 		}
 
 		return `/${lang}/blogs/${blogIdWithoutLang}`;
@@ -90,7 +90,7 @@ export class LinkUtil {
 		const courseIdWithoutLang = courseId.replace(`${lang}/`, '');
 
 		if (debug) {
-			logger.info(`获取课程文档链接，课程文档ID: ${courseId}`);
+			cosyLogger.info(`获取课程文档链接，课程文档ID: ${courseId}`);
 		}
 
 		return LinkUtil.createUrl(`/${lang}/courses/${courseIdWithoutLang}`);

package/dist/utils/logger.ts

@@ -5,110 +5,126 @@ const SHOW_TIMESTAMP = false;
 
 // ANSI 颜色代码
 const colors = {
-	reset: '\x1b[0m',
-	debug: '\x1b[36m', // 青色
-	info: '\x1b[32m', // 绿色
-	warn: '\x1b[33m', // 黄色
-	error: '\x1b[31m', // 红色
-	gray: '\x1b[90m', // 灰色用于时间戳
+    reset: '\x1b[0m',
+    debug: '\x1b[36m', // 青色
+    info: '\x1b[32m', // 绿色
+    warn: '\x1b[33m', // 黄色
+    error: '\x1b[31m', // 红色
+    gray: '\x1b[90m', // 灰色用于时间戳
 };
 
-class Logger {
-	private formatArray(arr: any[]): string {
-		const MAX_LINES = 70;
-		const MAX_LENGTH = 100;
-
-		const truncateString = (str: string): string => {
-			return str.length > MAX_LENGTH ? str.slice(0, MAX_LENGTH) + '...' : str;
-		};
-
-		const truncateObject = (obj: any): any => {
-			if (typeof obj !== 'object' || obj === null) {
-				return typeof obj === 'string' ? truncateString(obj) : obj;
-			}
-
-			const result: any = Array.isArray(obj) ? [] : {};
-			for (const [key, value] of Object.entries(obj)) {
-				result[key] =
-					typeof value === 'string'
-						? truncateString(value)
-						: typeof value === 'object'
-							? truncateObject(value)
-							: value;
-			}
-			return result;
-		};
-
-		const items = arr.slice(0, MAX_LINES).map((item) => {
-			const truncatedItem = truncateObject(item);
-			// 使用2个空格缩进，并在每行前添加 "  • "
-			const jsonString = JSON.stringify(truncatedItem, null, 2)
-				.split('\n')
-				.map((line, index) => (index === 0 ? `  • ${line}` : `    ${line}`))
-				.join('\n');
-			return jsonString;
-		});
-
-		let output = items.join('\n');
-		if (arr.length > MAX_LINES) {
-			const remainingCount = arr.length - MAX_LINES;
-			output += `\n  ⋮ ... and ${remainingCount} more items`;
-		}
-
-		return output;
-	}
-
-	private log(level: LogLevel, message: string | object | any[]) {
-		// 使用本地时间，并格式化为 HH:mm:ss 格式
-		const timestamp = new Date().toLocaleTimeString('zh-CN', {
-			hour12: false,
-			hour: '2-digit',
-			minute: '2-digit',
-			second: '2-digit',
-		});
-
-		const formattedMessage = Array.isArray(message)
-			? this.formatArray(message)
-			: typeof message === 'object'
-				? JSON.stringify(message, null, 2)
-				: message;
-
-		const timestampPart = SHOW_TIMESTAMP ? `${colors.gray}${timestamp}${colors.reset} ` : '';
-
-		const emoji = {
-			debug: '🔍',
-			info: '🐳',
-			warn: '🚨',
-			error: '❌',
-		}[level];
-
-		console.log(
-			timestampPart +
-				`${colors[level]}${emoji} ${level.toUpperCase()}${colors.reset} ` +
-				`${colors.gray}:${colors.reset} ` +
-				`${colors[level]}${formattedMessage}${colors.reset}`
-		);
-	}
-
-	debug(message: string | object) {
-		this.log('debug', message);
-	}
-
-	info(message: string | object) {
-		this.log('info', message);
-	}
-
-	warn(message: string | object) {
-		this.log('warn', message);
-	}
-
-	error(message: string | object) {
-		this.log('error', message);
-	}
-
-	array(title: string, arr: any[]) {
-		this.log('info', title + '\n' + this.formatArray(arr));
-	}
+export class Logger {
+    private topic: string = '';
+
+    private formatArray(arr: any[]): string {
+        const MAX_LINES = 70;
+        const MAX_LENGTH = 100;
+
+        const truncateString = (str: string): string => {
+            return str.length > MAX_LENGTH ? str.slice(0, MAX_LENGTH) + '...' : str;
+        };
+
+        const truncateObject = (obj: any): any => {
+            if (typeof obj !== 'object' || obj === null) {
+                return typeof obj === 'string' ? truncateString(obj) : obj;
+            }
+
+            const result: any = Array.isArray(obj) ? [] : {};
+            for (const [key, value] of Object.entries(obj)) {
+                result[key] =
+                    typeof value === 'string'
+                        ? truncateString(value)
+                        : typeof value === 'object'
+                            ? truncateObject(value)
+                            : value;
+            }
+            return result;
+        };
+
+        const items = arr.slice(0, MAX_LINES).map((item) => {
+            const truncatedItem = truncateObject(item);
+            // 使用2个空格缩进，并在每行前添加 "  • "
+            const jsonString = JSON.stringify(truncatedItem, null, 2)
+                .split('\n')
+                .map((line, index) => (index === 0 ? `  • ${line}` : `    ${line}`))
+                .join('\n');
+            return jsonString;
+        });
+
+        let output = items.join('\n');
+        if (arr.length > MAX_LINES) {
+            const remainingCount = arr.length - MAX_LINES;
+            output += `\n  ⋮ ... and ${remainingCount} more items`;
+        }
+
+        return output;
+    }
+
+    private log(level: LogLevel, message: string | object | any[], newLine: boolean = false) {
+        // 使用本地时间，并格式化为 HH:mm:ss 格式
+        const timestamp = new Date().toLocaleTimeString('zh-CN', {
+            hour12: false,
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+        });
+
+        const formattedMessage = Array.isArray(message)
+            ? this.formatArray(message)
+            : typeof message === 'object'
+                ? JSON.stringify(message, null, 2)
+                : message;
+
+        const timestampPart = SHOW_TIMESTAMP ? `${colors.gray}${timestamp}${colors.reset} ` : '';
+
+        const emoji = {
+            debug: '🔍',
+            info: '🐳',
+            warn: '🚨',
+            error: '❌',
+        }[level];
+
+        if (newLine) {
+            console.log("")
+        }
+
+        console.log(
+            timestampPart +
+            `${colors[level]}${emoji} ` +
+            this.getPrefix() +
+            `${level.toUpperCase()}${colors.reset} ` +
+            `${colors.gray}:${colors.reset} ` +
+            `${colors[level]}${formattedMessage}${colors.reset}`
+        );
+    }
+
+    private getPrefix() {
+        return this.topic ? `[${this.topic}] ` : '';
+    }
+
+    constructor(topic: string = '') {
+        this.topic = topic;
+    }
+
+    debug(message: string | object) {
+        this.log('debug', message);
+    }
+
+    info(message: string | object) {
+        this.log('info', message);
+    }
+
+    warn(message: string | object) {
+        this.log('warn', message);
+    }
+
+    error(message: string | object) {
+        this.log('error', message, true);
+    }
+
+    array(title: string, arr: any[]) {
+        this.log('info', title + '\n' + this.formatArray(arr));
+    }
 }
 
-export const logger = new Logger();
+export const defaultLogger = new Logger();

package/dist/utils/path.ts

@@ -1,4 +1,4 @@
-import { logger } from './logger';
+import { cosyLogger } from '../cosy';
 
 /**
  * 判断当前路径是否匹配目标路径
@@ -10,13 +10,13 @@ export function isPathMatch(currentPath: string, targetPath: string): boolean {
 	const debug = false;
 
 	if (debug) {
-		logger.info(`判断 ${currentPath} 是否匹配 ${targetPath}`);
+		cosyLogger.info(`判断 ${currentPath} 是否匹配 ${targetPath}`);
 	}
 
 	// 如果完全匹配，直接返回
 	if (currentPath === targetPath) {
 		if (debug) {
-			logger.info(`${currentPath} 完全匹配 ${targetPath}`);
+			cosyLogger.info(`${currentPath} 完全匹配 ${targetPath}`);
 		}
 		return true;
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@coffic/cosy-ui",
-    "version": "0.6.38",
+    "version": "0.6.40",
     "description": "An astro component library",
     "author": {
         "name": "nookery",