diff --git a/README.md b/README.md
index aae4e4e..a762626 100644
--- a/README.md
+++ b/README.md
@@ -1,55 +1,22 @@
-
-
-
2026 MoonBit 国产基础软件生态开源大赛参赛作品
-
-
-
-
+# BitLogger
-## 📖 介绍
+BitLogger 是一个使用 MoonBit 编写的结构化日志库，适合命令行工具、服务和需要统一日志输出的项目。
-BitLogger 是一个使用 MoonBit 编写的结构化日志库，目标是提供可组合、可配置、可跨端编译的日志基础设施。
+- [Mooncake 文档页](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
+- [English README](./docs/README-en.md)
-## 🧭 后端兼容
+## 介绍
-当前仓库已验证目标：`native`、`js`、`wasm`、`wasm-gc`。
+BitLogger 提供统一的日志级别、目标名、结构化字段和可定制格式，既可以直接输出到控制台，也可以在 native 环境写入文件，并提供异步日志版本。
-`llvm` 目前仍应视为实验性目标：当前环境未完成验证，本地复核依赖 nightly / llvm toolchain 条件，现阶段不作为与 `native` 同等级的稳定承诺。
-
-| 模块 / 能力 | 已验证目标 | `llvm` |
-| --- | --- | --- |
-| `src` 主包 | `native`、`js`、`wasm`、`wasm-gc` 已验证 | 实验性；当前环境未完成验证 |
-| `file(...)` / `file_sink(...)` | 仅 `native` 已验证；非 native 下不支持，`native_files_supported()` 返回 `false` | 不作为已验证能力声明 |
-| `src-async` | `native`、`wasm` 已本地复核通过；其余非 native 仍按兼容实现表述 | 实验性；当前环境未完成验证 |
-| portable examples (`console_basic` / `text_formatter` / `style_tags` / `config_build` / `presets`) | `native`、`wasm-gc` 已验证 | 当前未完成验证 |
-| `examples/file_rotation` | `native` 已验证；非 native 会清晰提示 file sink 不可用 | 当前未完成验证 |
-| `examples/async_basic` | `native` 已验证；非 native 受 `async fn main` 入口限制, 当前不提供 | 当前未完成验证 |
-
-## ❇️ 关键特性
-
-- 结构化日志基础能力：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 与运行时状态读取。
-- 异步层：提供独立 `src-async` package，支持 queue、worker lifecycle、runtime state 和跨端兼容实现。
-
-## 🚀 快速开始
+## 快速开始
```moonbit
let logger = build_logger(
- with_queue(
- text_console(
- min_level=Level::Info,
- target="demo",
- text_formatter=TextFormatterConfig::new(show_timestamp=false, separator=" | "),
- ),
- max_pending=32,
- overflow=QueueOverflowPolicy::DropOldest,
+ text_console(
+ min_level=Level::Info,
+ target="demo",
+ text_formatter=TextFormatterConfig::new(show_timestamp=false, separator=" | "),
),
)
@@ -57,42 +24,39 @@ logger.info("starting", fields=[field("port", "8080")])
ignore(logger.flush())
```
-推荐先从 `presets + build_logger(...)` 路径开始：`console(...)` / `json_console(...)` / `text_console(...)` / `file(...)` 负责拼装 `LoggerConfig`，`with_queue(...)` / `with_file_rotation(...)` 负责做小范围组合，然后再交给 `build_logger(...)` 构建运行时 logger。
+推荐从 `console(...)`、`json_console(...)`、`text_console(...)`、`file(...)` 这几个入口开始，再按需配合 `with_queue(...)` 或 `with_file_rotation(...)`。
-当你需要 `fanout`、`split`、`callback`、`patch` 这类自定义 sink 图组合时，再优先使用 `Logger::new(...)` 直接进行运行时拼装。
+如果你需要自己组合 sink，比如 `fanout`、`split`、`callback`，再使用 `Logger::new(...)`。
-跨端优先时，优先选择 console / json_console / text_console / config parser 这类 portable surface；file sink / file preset 仍然是 native 能力，建议先用 `native_files_supported()` 做能力判断。
+## 支持情况
-异步入口示例：
+- 当前已验证目标：`native`、`js`、`wasm`、`wasm-gc`
+- `llvm` 目前按实验性目标处理，当前环境未完成验证
+- 文件输出是 native 能力；跨端代码里建议先判断 `native_files_supported()`
+- `src-async` 可用，但示例 `examples/async_basic` 目前仍按 native 入口提供
-```moonbit
-let logger = async_logger(console_sink(), target="async.demo")
-@async.with_task_group(group => {
- group.spawn_bg(() => logger.run())
- logger.info("started")
- logger.shutdown()
-})
-```
+## 主要能力
-## 📂 仓库结构
+- 结构化日志：level、target、message、fields
+- 多种输出方式：console、json console、text console、file
+- 可定制文本格式：模板、style tag、颜色控制
+- 配置驱动构建：`build_logger(...)`、`build_async_logger(...)`
+- 组合能力：queue、filter、patch、fanout、split、callback
+- 异步日志：独立 `src-async` package
-- `src/`: 主日志库 package。
-- `src-async/`: 基于 `moonbitlang/async` 的异步日志层。
-- `docs/api/`: 单接口粒度 API 文档。
-- `examples/basic/`: breadth 示例；文件开头就是推荐的 presets + `build_logger(...)` 同步入口，后续继续覆盖更广能力面。
-- `examples/console_basic/`: portable 的 console 与 json console 最小输出示例。
-- `examples/text_formatter/`: portable 的 text formatter / template 示例。
-- `examples/style_tags/`: portable 的 style tag / colored formatter 示例。
-- `examples/file_rotation/`: target-sensitive 的 file sink / rotation 示例，非 native 会直接提示跳过原因。
-- `examples/config_build/`: portable 的 `build_logger(...)` 配置驱动示例。
-- `examples/presets/`: portable-first 的 presets + `build_logger(...)` 示例；native 下额外演示 file preset。
-- `examples/async_basic/`: native-only 异步 logger 示例，并说明限制来自 `async fn main` 入口而不是 `src-async` API 缺失。
+## 示例
-## 🔗 文档入口
+- `examples/console_basic/`：最小 console / json console 示例
+- `examples/text_formatter/`：文本格式与模板示例
+- `examples/style_tags/`：style tag 与彩色输出示例
+- `examples/config_build/`：配置构建示例
+- `examples/presets/`：常用预设组合示例
+- `examples/file_rotation/`：文件输出与轮转示例，仅适用于 native
+- `examples/async_basic/`：异步日志示例
+
+## 文档
-- [Mooncake 文档页](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
-- [English README](./docs/README-en.md)
-- [src package README](./src/README.mbt.md)
- [API 索引](./docs/api/index.md)
-- 推荐起步 API: `text_console(...)` / `file(...)` / `with_queue(...)` / `build_logger(...)`
-- facade API: `build_application_logger(...)` / `build_library_logger(...)` / `build_application_async_logger(...)`
+- [src package README](./src/README.mbt.md)
+
+常用入口：`text_console(...)`、`file(...)`、`with_queue(...)`、`build_logger(...)`、`build_async_logger(...)`
diff --git a/docs/README-en.md b/docs/README-en.md
index a834489..841caa0 100644
--- a/docs/README-en.md
+++ b/docs/README-en.md
@@ -1,49 +1,22 @@
# BitLogger
-BitLogger is a structured logging library written in MoonBit.
+BitLogger is a structured logging library for MoonBit projects.
-This README focuses on project positioning, core capabilities, and entry points. Detailed API coverage now lives in `docs/api/`.
+- [Mooncake package page](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
+- [Chinese README](../README.md)
## Overview
-BitLogger is designed to provide composable, configurable, and cross-target logging infrastructure for MoonBit projects.
-
-## Backend Compatibility
-
-Currently verified targets: `native`, `js`, `wasm`, and `wasm-gc`.
-
-`llvm` should still be treated as experimental here: verification did not complete in the current environment, and local reproduction depends on nightly / llvm toolchain conditions, so it is not presented as a stable promise at the same level as `native`.
-
-| Module / capability | Verified targets | `llvm` |
-| --- | --- | --- |
-| `src` core package | Verified on `native`, `js`, `wasm`, and `wasm-gc` | Experimental; not fully verified in the current environment |
-| `file(...)` / `file_sink(...)` | Verified only on `native`; unavailable on non-native targets and `native_files_supported()` returns `false` | Not presented as a verified capability |
-| `src-async` | Local verification passed on `native` and `wasm`; other non-native targets still follow the compatibility-implementation wording | Experimental; not fully verified in the current environment |
-| portable examples (`console_basic` / `text_formatter` / `style_tags` / `config_build` / `presets`) | Verified on `native` and `wasm-gc` | Not yet verified here |
-| `examples/file_rotation` | Verified on `native`; non-native targets print a clear skip message because file sinks are unavailable | Not yet verified here |
-| `examples/async_basic` | Verified on `native`; non-native example shipping is still limited by the current `async fn main` entry path | Not yet verified here |
-
-## Key Features
-
-- Structured logging with levels, targets, and key-value fields.
-- Composable sinks, filters, patches, fanout, routing, and queue wrappers.
-- Config-driven runtime assembly through JSON parse/export helpers and `build_logger(...)` / `build_async_logger(...)`.
-- Configurable text formatting with templates, style tags, and color control.
-- Native file sink support with basic rotation, reopen helpers, and runtime observability.
-- Separate async layer with bounded queueing, worker lifecycle control, runtime state, and cross-target compatibility.
+BitLogger gives you consistent levels, targets, structured fields, configurable text output, native file logging, and an async logging layer.
## Quick Start
```moonbit
let logger = build_logger(
- with_queue(
- text_console(
- min_level=Level::Info,
- target="demo",
- text_formatter=TextFormatterConfig::new(show_timestamp=false, separator=" | "),
- ),
- max_pending=32,
- overflow=QueueOverflowPolicy::DropOldest,
+ text_console(
+ min_level=Level::Info,
+ target="demo",
+ text_formatter=TextFormatterConfig::new(show_timestamp=false, separator=" | "),
),
)
@@ -51,54 +24,39 @@ logger.info("starting", fields=[field("port", "8080")])
ignore(logger.flush())
```
-Start new synchronous code with `presets + build_logger(...)`: use `console(...)`, `json_console(...)`, `text_console(...)`, or `file(...)` to assemble `LoggerConfig`, optionally extend it with `with_queue(...)` or `with_file_rotation(...)`, then call `build_logger(...)`.
+Start with `console(...)`, `json_console(...)`, `text_console(...)`, or `file(...)`, then add `with_queue(...)` or `with_file_rotation(...)` only when needed.
-Switch to `Logger::new(...)` when you need direct runtime sink composition such as `fanout`, `split`, `callback`, or custom patch/filter graphs.
+Use `Logger::new(...)` when you want to assemble custom sink graphs directly.
-For cross-target code, prefer the console, json console, text console, and config-parser paths first. File sinks and file presets remain native-sensitive and should be gated with `native_files_supported()`.
+## Support Status
-Async entry example:
+- Currently verified targets: `native`, `js`, `wasm`, `wasm-gc`
+- `llvm` is still treated as experimental in the current release context
+- File output is a native capability; check `native_files_supported()` in cross-target code
+- `src-async` is available, while `examples/async_basic` is still shipped as a native entry example
-```moonbit
-let logger = async_logger(console_sink(), target="async.demo")
-@async.with_task_group(group => {
- group.spawn_bg(() => logger.run())
- logger.info("started")
- logger.shutdown()
-})
-```
+## Main Features
-## Repository Layout
+- Structured logs with levels, targets, messages, and fields
+- Multiple outputs: console, JSON console, text console, and file
+- Custom text formatting with templates, style tags, and color control
+- Config-based builders: `build_logger(...)` and `build_async_logger(...)`
+- Composition helpers: queue, filter, patch, fanout, split, callback
+- Separate async package under `src-async`
-- `src/`: core logging package.
-- `src-async/`: async logging layer built on `moonbitlang/async`.
-- `docs/api/`: one-file-per-interface API documentation.
-- `examples/basic/`: breadth example; starts with the recommended presets-based sync path and then sweeps broader capabilities.
-- `examples/console_basic/`: portable minimal console and JSON console output.
-- `examples/text_formatter/`: portable text formatter and template example.
-- `examples/style_tags/`: portable style tag and colored formatter example.
-- `examples/file_rotation/`: target-sensitive file sink and rotation example with an explicit non-native skip path.
-- `examples/config_build/`: portable config-driven `build_logger(...)` example.
-- `examples/presets/`: portable-first presets example; adds file preset usage only when native file support is available.
-- `examples/async_basic/`: native-only async logger example; the limitation is the `async fn main` entry path, not the absence of `src-async` compatibility APIs.
+## Examples
-## Documentation Entry Points
+- `examples/console_basic/`: minimal console and JSON console example
+- `examples/text_formatter/`: text formatting and template example
+- `examples/style_tags/`: style tags and colored output example
+- `examples/config_build/`: config-based build example
+- `examples/presets/`: common preset combinations
+- `examples/file_rotation/`: native file logging and rotation example
+- `examples/async_basic/`: async logging example
-- [Mooncake package page](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
-- [Chinese README](../README.md)
+## Documentation
+
+- [API index](./api/index.md)
- [src package README](../src/README.mbt.md)
-- Recommended sync starting APIs: `text_console(...)`, `file(...)`, `with_queue(...)`, `build_logger(...)`
-- Selected API docs in `docs/api/`:
-- [logger-new.md](./api/logger-new.md)
-- [async-logger.md](./api/async-logger.md)
-- [build-logger.md](./api/build-logger.md)
-- [build-async-logger.md](./api/build-async-logger.md)
-- [build-application-logger.md](./api/build-application-logger.md)
-- [build-library-logger.md](./api/build-library-logger.md)
-- [build-application-async-logger.md](./api/build-application-async-logger.md)
-## Notes
-
-- `docs/README-en.md` no longer acts as an API catalog.
-- Detailed API references, config fields, runtime control helpers, and lifecycle surfaces now live under `docs/api/`.
-- For concrete runnable flows, prefer `examples/`.
+Common entry points: `text_console(...)`, `file(...)`, `with_queue(...)`, `build_logger(...)`, `build_async_logger(...)`