diff --git a/README.md b/README.md
index e96d2df..431b7f5 100644
--- a/README.md
+++ b/README.md
@@ -1,25 +1,63 @@
-# BitLogger
+
+
+
2026 MoonBit 国产基础软件生态开源大赛参赛作品
+
+
+
+
-BitLogger is a MoonBit logging library in early development.
+## 📖 介绍
-## Repository Layout
+BitLogger 是一个基于 MoonBit 编写的结构化日志库。
-- `bitlogger/`: library package, tests, and checked package README
-- `examples/basic/`: runnable example program
-- `docs/dev/`: development notes and MoonBit gotchas collected during implementation
+## ❇️ 特点
-## Current MVP
+- 🧩 核心能力清晰：先把 logging core 做稳，再继续扩展 `FileSink`、buffered/async 等能力。
+- 🏗️ 结构明确：按 `level / record / formatter / sinks / logger / global` 拆文件，便于继续维护。
+- 🔌 可扩展：支持 `fanout_sink(...)` 和 `callback_sink(...)`，方便后续桥接文件、指标或外部系统。
+- 📦 面向 MoonBit：API 和工程结构围绕 MoonBit 的 package / visibility / toolchain 现实约束设计。
-- log levels
-- structured fields
-- sink trait
-- console sink
-- JSON console sink
-- context fields
-- child target composition
-- fanout sink composition
-- callback sink
-- optional timestamps
-- global default logger helpers
+## 🚀 快速开始
+
+```moonbit
+let logger = Logger::new(console_sink(), min_level=Level::Info, target="demo")
+ .with_timestamp()
+ .with_context_fields([field("service", "bitlogger")])
+
+logger.info("starting", fields=[field("port", "8080")])
+```
+
+层级 target 示例：
+
+```moonbit
+let worker = Logger::new(console_sink(), target="app").child("worker")
+worker.info("job ready")
+```
+
+自定义 callback sink 示例：
+
+```moonbit
+let hook = Logger::new(
+ callback_sink(fn(rec) {
+ println("callback saw [\{rec.target}] \{rec.message}")
+ }),
+ target="hook",
+)
+
+hook.info("hello")
+```
+
+## 📂 仓库结构
+
+- `bitlogger/`：MoonBit 库 package，本体实现、测试与 Mooncake README
+- `examples/basic/`：最小可运行示例
+
+## 🔗 相关文档
+
+- [Mooncake 文档页](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
+- [English README](./docs/README-en.md)
-For the checked MoonBit example, see [bitlogger/README.mbt.md](./bitlogger/README.mbt.md).
diff --git a/bitlogger/README.mbt.md b/bitlogger/README.mbt.md
index b44dca4..ccf0089 100644
--- a/bitlogger/README.mbt.md
+++ b/bitlogger/README.mbt.md
@@ -2,20 +2,32 @@
BitLogger is a minimal structured logger for MoonBit.
-## Features
+BitLogger 是一个基于 MoonBit 的结构化日志库。
+
+## Features / 特性
- log levels: `Trace`, `Debug`, `Info`, `Warn`, `Error`
+- 日志级别：`Trace`、`Debug`、`Info`、`Warn`、`Error`
- structured key-value fields
+- 结构化字段：`field("key", "value")`
- sink abstraction
+- sink 抽象与组合边界
- default global console logger
+- 默认全局 logger 辅助函数
- context fields via `with_context_fields(...)`
+- 通过 `with_context_fields(...)` 添加上下文字段
- child target composition via `child(...)`
+- 通过 `child(...)` 组合层级 target
- optional timestamps via `with_timestamp()`
+- 通过 `with_timestamp()` 启用时间戳
- JSON console output via `json_console_sink()`
+- `json_console_sink()` 提供 JSON 控制台输出
- sink composition via `fanout_sink(...)`
+- `fanout_sink(...)` 支持多 sink 组合
- custom callback sink via `callback_sink(...)`
+- `callback_sink(...)` 支持自定义外部集成
-## Example
+## Example / 示例
```mbt check
test {
@@ -43,8 +55,22 @@ test {
}
```
-## Notes
+```mbt check
+test {
+ let logger = Logger::new(console_sink(), target="app").child("worker")
+ logger.info("ready")
+}
+```
+
+```mbt check
+test {
+ let logger = Logger::new(
+ callback_sink(fn(rec) {
+ println("callback saw [\{rec.target}] \{rec.message}")
+ }),
+ target="hook",
+ )
+ logger.info("hello")
+}
+```
-Current MVP includes plain-text output, JSON console output, context fields, child target composition, and simple sink fanout.
-The intended public entry points are `Logger`, sink constructor helpers, `field(...)`, and the default global logger helpers.
-Next useful steps are file sink and buffered or async delivery.
diff --git a/docs/README-en.md b/docs/README-en.md
new file mode 100644
index 0000000..f33524b
--- /dev/null
+++ b/docs/README-en.md
@@ -0,0 +1,58 @@
+# BitLogger
+
+BitLogger is a structured logging library written in MoonBit.
+
+## Overview
+
+BitLogger currently provides:
+
+- log levels: `Trace`, `Debug`, `Info`, `Warn`, `Error`
+- structured key-value fields
+- plain console output
+- JSON console output
+- child target composition via `child(...)`
+- context fields via `with_context_fields(...)`
+- optional timestamps via `with_timestamp()`
+- sink fanout via `fanout_sink(...)`
+- custom integration via `callback_sink(...)`
+- default global logger helpers
+
+## Quick Start
+
+```moonbit
+let logger = Logger::new(console_sink(), min_level=Level::Info, target="demo")
+ .with_timestamp()
+ .with_context_fields([field("service", "bitlogger")])
+
+logger.info("starting", fields=[field("port", "8080")])
+```
+
+Child target composition:
+
+```moonbit
+let worker = Logger::new(console_sink(), target="app").child("worker")
+worker.info("job ready")
+```
+
+Custom callback sink:
+
+```moonbit
+let hook = Logger::new(
+ callback_sink(fn(rec) {
+ println("callback saw [\{rec.target}] \{rec.message}")
+ }),
+ target="hook",
+)
+
+hook.info("hello")
+```
+
+## Repository Layout
+
+- `bitlogger/`: MoonBit library package, tests, and Mooncake package README
+- `examples/basic/`: runnable example package
+
+## Links
+
+- [Mooncake package page](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
+- [Chinese README](../README.md)