diff --git a/README.md b/README.md
index ee49520..d2201cc 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,9 @@
## 📖 介绍
-BitLogger 是一个使用 MoonBit 编写的结构化日志库
+BitLogger 是一个使用 MoonBit 编写的结构化日志库，目标是提供可组合、可配置、可跨端编译的日志基础设施。
+
+README 仅保留项目定位、关键特性和最小使用入口。详细 API 请查看 `docs/api/`。
## 🧭 后端兼容
@@ -23,21 +25,14 @@ BitLogger 是一个使用 MoonBit 编写的结构化日志库
| `bitlogger_async` | 支持原生 worker 语义 | 支持兼容实现 |
| `examples/async_basic` | 支持 | 受 `async fn main` 入口限制, 当前不提供 |
-## ❇️ 特点
+## ❇️ 关键特性
-- 🧩 基础能力: 支持 level, formatter, sink, context field 和全局 logger.
-- 🏗️ 结构清晰: 按 `level / record / formatter / sinks / logger / global` 拆分文件, 便于维护.
-- 🔌 可扩展: 支持 `fanout_sink(...)` 和 `callback_sink(...)`, 方便接入文件, 指标或外部系统.
-- 🔀 可分流: 支持 `split_sink(...)` / `split_by_level(...)`, 可按谓词或 level 将日志路由到不同 sink.
-- 🧱 可组合: 支持 `buffered_sink(...)` 和 `filter_sink(...)`, 可以组合不同输出策略.
-- 🔎 可复用过滤: 提供 `target_has_prefix(...)`, `message_contains(...)`, `level_at_least(...)`, `field_equals(...)` 等过滤辅助函数.
-- 🩹 可变换 Record: 支持 `with_patch(...)`, `patch_sink(...)` 以及脱敏, 补字段, message 变换 helper.
-- 🧷 可绑定上下文: 支持 `bind(...)` 与 `fields(...)`, 便于复用上下文字段.
-- 📮 显式队列: 支持 `queued_sink(...)` / `with_queue(...)`, 支持有界积压和溢出策略.
-- 🧾 可配置文本格式: 支持 `text_formatter(...)`, `format_text(...)`, `text_console_sink(...)`, `formatted_callback_sink(...)` 和模板化 `template` 输出.
-- 🎨 轻量样式标签: 支持 `color_mode`, inline markup, `TextStyle`, `StyleTagRegistry`, 自定义标签与内置标签覆盖.
-- 💾 Native 文件输出: 支持 `file_sink(...)`, 基础 size rotation / backup retention, 显式 `reopen()` / `reopen_with_current_policy()` / `reopen_append()` / `reopen_truncate()` 与失败计数, 仅在 `native/llvm` backend 可用.
-- 📦 MoonBit 适配: API 和工程结构与 MoonBit 的 package / visibility / toolchain 模型保持一致.
+- 结构化日志基础能力：level、record、formatter、sink、target、context field。
+- 组合式设计：支持 filter、patch、fanout、split、callback、queued sink 等组合能力。
+- 配置驱动：支持 JSON 配置解析、导出与 `build_logger(...)` / `build_async_logger(...)` 运行时组装。
+- 文本格式化：支持 `text_formatter(...)`、template、style tag、`color_mode` / `style_markup`。
+- Native 文件输出：支持 file sink、基础 size rotation、reopen、failure counter 与运行时状态读取。
+- 异步层：提供独立 `bitlogger_async` package，支持 queue、worker lifecycle、runtime state 和跨端兼容实现。
## 🚀 快速开始
@@ -49,338 +44,44 @@ let logger = Logger::new(console_sink(), min_level=Level::Info, target="demo")
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")
-```
-基础 buffered sink 示例
-
-```moonbit
-let sink = buffered_sink(console_sink(), flush_limit=2)
-let logger = Logger::new(sink, target="buffered")
-
-logger.info("one")
-logger.info("two")
-sink.flush()
-```
-基础 filter sink 示例
-
-```moonbit
-let sink = filter_sink(console_sink(), fn(rec) {
- rec.target == "kept"
+let logger = async_logger(console_sink(), target="async.demo")
+@async.with_task_group(group => {
+ group.spawn_bg(() => logger.run())
+ logger.info("started")
+ logger.shutdown()
})
-
-let kept = Logger::new(sink, target="kept")
-let dropped = Logger::new(sink, target="dropped")
-
-kept.info("visible")
-dropped.info("hidden")
```
-Logger 链式 filter 示例
-
-```moonbit
-let logger = Logger::new(console_sink(), target="service")
- .with_filter(all_of([
- target_has_prefix("service"),
- message_contains("visible"),
- ]))
-
-logger.info("hidden")
-logger.child("api").info("visible")
-```
-Record patch 示例
-
-```moonbit
-let logger = Logger::new(console_sink(), target="auth")
- .with_patch(compose_patches([
- prefix_message("[safe] "),
- redact_fields(["token"]),
- append_fields([field("service", "bitlogger")]),
- ]))
-
-logger.info("login", fields=[field("user", "alice"), field("token", "secret")])
-```
-bind 上下文示例
-
-```moonbit
-let logger = Logger::new(console_sink(), target="audit")
- .bind(fields([("service", "bitlogger"), ("scope", "login")]))
-
-logger.info("accepted", fields=[field("user", "alice")])
-```
-
-显式 queue sink 示例
-
-```moonbit
-let logger = Logger::new(console_sink(), target="queue")
- .with_queue(max_pending=2, overflow=QueueOverflowPolicy::DropOldest)
-
-logger.info("one")
-logger.info("two")
-logger.info("three")
-ignore(logger.sink.flush())
-```
-按 level 分流 sink 示例
-
-```moonbit
-let logger = Logger::new(
- split_by_level(
- callback_sink(fn(rec) {
- println("high priority: \{rec.level.label()} \{rec.message}")
- }),
- console_sink(),
- min_level=Level::Warn,
- ),
- min_level=Level::Trace,
- target="split",
-)
-
-logger.info("normal output")
-logger.warn("warning output")
-```
-
-自定义文本 formatter 示例
-
-```moonbit
-let formatter = text_formatter(
- show_timestamp=false,
- field_separator=",",
- template="[{level}] {target} {message} :: {fields}",
- color_mode=ColorMode::Always,
-)
-let logger = Logger::new(text_console_sink(formatter), target="pretty")
-
-logger.info("hello", fields=[field("mode", "pretty")])
-```
-
-inline style tag 示例
-
-```moonbit
-let formatter = text_formatter(
- show_timestamp=false,
- color_mode=ColorMode::Always,
-).with_style_tags(
- default_style_tag_registry()
- .set_tag("accent", fg=Some("#4cc9f0"), bold=true)
- .define_alias("danger", "red"),
-)
-
-let logger = Logger::new(text_console_sink(formatter), target="styled")
-
-logger.info("styled output and alert")
-```
-
-关闭 style markup 解析示例
-
-```moonbit
-let formatter = text_formatter(
- color_mode=ColorMode::Always,
-).without_style_markup()
-
-let logger = Logger::new(text_console_sink(formatter), target="raw")
-
-logger.info("kept as raw text")
-```
-
-JSON 配置加载示例
-
-```moonbit
-let config = parse_logger_config_text(
- "{\"min_level\":\"debug\",\"target\":\"config.demo\",\"timestamp\":true,\"sink\":{\"kind\":\"text_console\",\"text_formatter\":{\"show_timestamp\":false,\"field_separator\":\",\",\"template\":\"[{level}] {target} {message} :: {fields}\",\"color_mode\":\"always\"}},\"queue\":{\"max_pending\":2,\"overflow\":\"DropOldest\"}}",
-)
-
-let logger = build_logger(config)
-
-logger.info("configured from json")
-ignore(logger.flush())
-```
-
-JSON style_tags 示例
-
-```moonbit
-let config = parse_logger_config_text(
- "{\"sink\":{\"kind\":\"text_console\",\"text_formatter\":{\"show_timestamp\":false,\"color_mode\":\"always\",\"style_tags\":{\"accent\":{\"fg\":\"#4cc9f0\",\"bold\":true}}}}}",
-)
-
-let logger = build_logger(config)
-
-logger.info("styled from json")
-```
-
-JSON style_markup 模式示例
-
-```moonbit
-let config = parse_logger_config_text(
- "{\"sink\":{\"kind\":\"text_console\",\"text_formatter\":{\"color_mode\":\"always\",\"style_markup\":\"disabled\"}}}",
-)
-
-let logger = build_logger(config)
-
-logger.info("still raw")
-```
-
-native 文件 sink 示例
-
-```moonbit
-if native_files_supported() {
- let logger = Logger::new(
- file_sink("bitlogger.log", rotation=Some(file_rotation(128, max_backups=2))),
- target="file",
- )
- logger.info("hello", fields=[field("kind", "file")])
- ignore(logger.sink.flush())
- ignore(logger.sink.close())
-}
-```
-file runtime state dump 示例
-
-```moonbit
-let logger = build_logger(
- LoggerConfig::new(
- sink=SinkConfig::new(kind=SinkKind::File, path="bitlogger-runtime.log"),
- queue=Some(QueueConfig::new(16)),
- ),
-)
-
-logger.info("queued hello")
-
-match logger.file_runtime_state() {
- Some(snapshot) => println(stringify_runtime_file_state(snapshot, pretty=true))
- None => ()
-}
-```
-