docs: rebuild Threading API content

docs/api/XCEngine/Threading/Threading.md

@@ -4,11 +4,42 @@
 
 **类型**: `module`
 
-**描述**: 线程封装、同步原语和任务系统。
+**描述**: 提供线程封装、基础同步原语和一套早期任务系统骨架。
 
-## 概览
+## 概述
 
-该目录与 `XCEngine/Threading` 对应的 public headers 保持平行，用于承载唯一的 canonical API 文档入口。
+`XCEngine::Threading` 当前由两部分组成：
+
+- `Mutex`、`SpinLock`、`ReadWriteLock` 和 `Thread` 这类直接可用的并发基础设施。
+- `ITask`、`TaskGroup`、`TaskSystem` 这类面向 job system 的任务抽象。
+
+这种分层很符合商业引擎常见做法：底层仍然需要明确的锁和线程封装，上层再逐步演进到任务图、主线程回调和并行 for 之类的调度模型。
+
+## 当前实现成熟度
+
+这一组 API 的成熟度差异很大，需要分开看：
+
+- `Mutex` 与 `SpinLock` 本质上是对标准库原语的薄封装，语义相对直接。
+- `ReadWriteLock` 实现了写者优先的读写锁，但没有 try-lock、升级/降级或 RAII 辅助类型。
+- `Thread` 可以封装 `std::thread` 生命周期，但线程名称只是本地字符串，不会设置 OS 线程名，而且 ID 口径与 `GetCurrentId()` 不一致。
+- `ITask` 与 `LambdaTask` 的抽象形状已经具备，但 `TaskGroup` 和 `TaskSystem` 目前仍然明显属于“骨架阶段”。
+- `TaskSystem` 当前存在严重的生命周期和同步问题，因此不能把它当成商用级 job system 使用。
+
+## 设计要点
+
+- 大写接口如 `Lock()` / `Unlock()` 更接近引擎自身命名风格。
+- 小写接口如 `lock()` / `unlock()` / `try_lock()` 的存在，是为了兼容 `std::lock_guard` 这类标准 Lockable 习惯用法。
+- `ITask` 采用侵入式引用计数，说明这套任务系统原本是朝“跨线程提交和自动释放任务对象”这个方向设计的。
+
+## 测试覆盖现状
+
+当前测试只覆盖了：
+
+- `Mutex`
+- `SpinLock`
+- `ITask` / `LambdaTask` 的最基础行为
+
+`ReadWriteLock`、`Thread`、`TaskGroup` 和 `TaskSystem` 当前没有看到对应单测，因此相关文档会更强调源码现状和风险边界。
 
 ## 头文件
 
@@ -23,6 +54,10 @@
 - [Thread](Thread/Thread.md) - `Thread.h`
 - [Threading](Threading/Threading.md) - `Threading.h`
 
+## 相关指南
+
+- [Synchronization And Task System Limits](../../_guides/Threading/Synchronization-And-TaskSystem-Limits.md) - 解释为什么引擎要同时保留锁、线程和任务系统抽象，以及当前实现距离商业级 job system 还差哪些关键能力。
+
 ## 相关文档
 
 - [上级目录](../XCEngine.md)