docs: rebuild Debug API content

docs/api/XCEngine/Debug/FileLogSink/FileLogSink.md

@@ -6,28 +6,56 @@
 
 **头文件**: `XCEngine/Debug/FileLogSink.h`
 
-**描述**: 定义 `XCEngine/Debug` 子目录中的 `FileLogSink` public API。
+**描述**: 将日志追加写入文件，并在失败时回退到 `stderr`。
 
 ## 概述
 
-`FileLogSink.h` 是 `XCEngine/Debug` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`FileLogSink` 负责把 `LogEntry` 序列化成文本并落盘。它适合编辑器、集成测试和长时间运行的工具程序，因为这类场景通常需要保留会话级日志以便复盘。
 
-## 声明概览
+当前实现中的关键行为：
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `FileLogSink` | `class` | 继承自 `ILogSink` 的公开声明。 |
+- 构造时尝试以追加模式打开目标文件。
+- 每次写入后立即 `Flush`，优先保证可追溯性，而不是吞吐量。
+- 如果文件句柄不可用，会在 `Log` 时尝试重新打开。
+- 如果重新打开或写入失败，会把错误和原始日志内容写到 `stderr`。
 
-## 公共方法
+## 生命周期
 
-| 方法 | 描述 |
+- [Constructor](Constructor.md) 保存目标路径并尝试打开文件。
+- [Destructor](Destructor.md) 关闭底层 `FileWriter`。
+- [Flush](Flush.md) 将缓冲区刷到磁盘。
+
+## 线程语义
+
+- `FileLogSink` 自身没有显式加锁。
+- 通过 `Logger` 使用时，调用会被 `Logger` 串行化。
+- 当前实现使用 `std::localtime` 生成时间文本；如果绕过 `Logger` 并发调用，线程安全性由调用方承担。
+
+## 输出格式
+
+当前实现输出格式为：
+
+```text
+[YYYY-MM-DD HH:MM:SS] [LEVEL] [Category] message
+```
+
+注意：
+
+- 使用的是 `LogEntry::timestamp` 的本地时间表示。
+- 当前不会把 `file`、`line`、`function` 或 `threadId` 写入文件。
+
+## 公开方法
+
+| 方法 | 说明 |
 |------|------|
-| [FileLogSink()](Constructor.md) | 构造对象。 |
-| [~FileLogSink()](Destructor.md) | 销毁对象并释放相关资源。 |
-| [Log](Log.md) | 公开方法，详见头文件声明。 |
-| [Flush](Flush.md) | 公开方法，详见头文件声明。 |
+| [Constructor](Constructor.md) | 构造文件日志 sink。 |
+| [Destructor](Destructor.md) | 析构 sink 并关闭文件。 |
+| [Log](Log.md) | 将日志条目写入文件。 |
+| [Flush](Flush.md) | 刷新底层文件。 |
 
 ## 相关文档
 
-- [当前目录](../Debug.md) - 返回 `Debug` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前模块](../Debug.md)
+- [Logger](../Logger/Logger.md)
+- [ILogSink](../ILogSink/ILogSink.md)
+- [Logging Architecture](../../../_guides/Debug/Logging-Architecture.md)