📝 add Chinese examples and extension docs

docs/zh/extend/composition.md

@@ -0,0 +1,42 @@
+# Sink 组合
+
+Preset 覆盖常见的控制台和文件配置。只有当记录需要路由或多个输出目的地时，才直接构造 `Logger::new(...)`。
+
+## 同时发送到两个目的地
+
+```moonbit
+let logger = @log.Logger::new(
+  @log.fanout_sink(@log.console_sink(), @log.json_console_sink()),
+  min_level=@log.Level::Info,
+  target="service",
+)
+
+logger.info("request complete", fields=[@log.field("status", "200")])
+```
+
+`fanout_sink(...)` 将同一记录写入每个子 Sink，因此应用可以同时保留面向人的控制台输出和面向采集器的 JSON 输出。
+
+## 单独处理警告以上日志
+
+```moonbit
+let logger = @log.Logger::new(
+  @log.split_by_level(
+    @log.callback_sink(fn(rec) {
+      println("alert: \{rec.message}")
+    }),
+    @log.console_sink(),
+    min_level=@log.Level::Warn,
+  ),
+  min_level=@log.Level::Trace,
+  target="service",
+)
+```
+
+只有当路由规则属于应用设计时才使用直接 Sink 组合；单一输出时，preset 更容易审查和维护。
+
+## 英文 API
+
+- [`Logger::new(...)`](../../api/logger-new.md)
+- [`fanout_sink(...)`](../../api/fanout-sink.md)
+- [`split_by_level(...)`](../../api/split-by-level.md)
+- [`callback_sink(...)`](../../api/callback-sink.md)

docs/zh/extend/formatting.md

@@ -0,0 +1,44 @@
+# 文本格式与样式
+
+格式化只改变呈现，记录本身的 level、target、message 和 fields 不变。面向人时使用文本输出；由其他系统解析时使用 JSON。
+
+## 自定义文本形状
+
+```moonbit
+let logger = @log.build_logger(
+  @log.text_console(
+    min_level=@log.Level::Info,
+    target="service",
+    text_formatter=@log.TextFormatterConfig::new(
+      show_timestamp=false,
+      field_separator=",",
+      template="[{level}] {target} {message} :: {fields}",
+    ),
+  ),
+)
+
+logger.info("ready", fields=[@log.field("port", "8080")])
+```
+
+模板控制可见顺序。fields 应保持独立于 message，以便不同 Sink 一致渲染。
+
+## 添加命名样式
+
+```moonbit
+let formatter = @log.text_formatter(
+  show_timestamp=false,
+  color_mode=@log.ColorMode::Always,
+).with_style_tags(
+  @log.default_style_tag_registry()
+  .set_tag("accent", fg=Some("#4cc9f0"), bold=true),
+)
+```
+
+样式标签是终端呈现元数据，不应作为唯一的业务或运维语义；语义仍应保存在 level、target 与 fields 中。
+
+## 英文 API
+
+- [`text_console(...)`](../../api/text-console.md)
+- [`TextFormatterConfig`](../../api/text-formatter-config.md)
+- [`text_formatter(...)`](../../api/text-formatter.md)
+- [`ColorMode`](../../api/color-mode.md)

docs/zh/extend/index.md

@@ -0,0 +1,14 @@
+# 扩展 Logger
+
+先完成一个[示例流程](../examples/index.md)，再一次只加入一种扩展能力。这些页面说明某个抽象何时有用，以及它会引入什么运行时边界。
+
+## 扩展地图
+
+| 需求 | 扩展 | 主要取舍 |
+| --- | --- | --- |
+| 吸收短时输出突发 | [队列](./queue.md) | 必须选择溢出与 flush 行为。 |
+| 同时发送到多个位置或按 level 路由 | [Sink 组合](./composition.md) | 比 preset 更需要显式构造。 |
+| 调整终端可读性 | [文本格式](./formatting.md) | 格式只改变呈现，不改变记录结构。 |
+| 在 native 与 web 目标之间共享代码 | [目标平台边界](./targets.md) | 文件与异步运行时行为因后端而异。 |
+
+需要精确函数签名时，沿页面链接进入[英文 API 参考](../../api/index.md)。

docs/zh/extend/queue.md

@@ -0,0 +1,30 @@
+# 队列与溢出策略
+
+当短时日志突发不应立即写入输出 Sink 时使用队列。队列是显式能力，因为丢弃策略必须由应用决定。
+
+## 加入同步队列
+
+```moonbit
+let config = @log.with_queue(
+  @log.text_console(target="service"),
+  max_pending=128,
+  overflow=@log.QueueOverflowPolicy::DropOldest,
+)
+let logger = @log.build_logger(config)
+
+logger.info("queued record")
+ignore(logger.flush())
+```
+
+`DropOldest` 在队列已满时保留最新运行信息。若更重视先到的记录，可选择 `DropNewest`。在退出边界调用 `flush()`，让待处理记录策略在应用代码中清晰可见。
+
+## 何时改用异步 Logger
+
+同步队列只是普通运行时 Logger 的一层配置。当 native 异步应用需要 worker 生命周期和批处理时，转到[异步日志生命周期](../examples/async.md)。
+
+## 英文 API
+
+- [`with_queue(...)`](../../api/with-queue.md)
+- [`QueueConfig`](../../api/queue-config.md)
+- [`QueueOverflowPolicy`](../../api/queue-overflow-policy.md)
+- [`flush()`](../../api/configured-logger-flush.md)

docs/zh/extend/targets.md

@@ -0,0 +1,33 @@
+# 目标平台边界
+
+BitLogger 保持可移植的结构化日志表面，但 native 文件输出与异步 worker 行为依赖目标平台。应把这些边界写在应用代码中，而不是假设每种 Sink 在所有后端都相同。
+
+## 可移植默认值
+
+`console(...)`、`json_console(...)`、结构化 fields、filter、patch 与普通 Logger 表面适合作为跨端共享代码的起点。
+
+## 仅 native 的文件输出
+
+```moonbit
+if @log.native_files_supported() {
+  let logger = @log.build_logger(@log.file("service.log") catch {
+    err => {
+      ignore(err)
+      return
+    }
+  })
+  logger.info("file output enabled")
+}
+```
+
+文件 Sink 需要 native 文件系统支持。面向 web 目标的代码不应无条件构造只包含文件输出的配置。
+
+## 异步库与异步入口
+
+异步库在声明目标上提供兼容表面，但可执行 `async fn main` 的入口支持更严格。请把 native-only 可执行示例与可移植库代码分开。
+
+## 英文 API
+
+- [`native_files_supported()`](../../api/native-files-supported.md)
+- [目标验证](../../api/target-verification.md)
+- [异步日志生命周期](../examples/async.md)