docs: rebuild Threading API content

docs/api/XCEngine/Threading/TaskSystem/TaskSystem.md

@@ -6,35 +6,72 @@
 
 **头文件**: `XCEngine/Threading/TaskSystem.h`
 
-**描述**: 定义 `XCEngine/Threading` 子目录中的 `TaskSystem` public API。
+**描述**: 提供全局任务调度入口、工作线程池、主线程回调队列以及任务组创建接口。
 
 ## 概述
 
-`TaskSystem.h` 是 `XCEngine/Threading` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`TaskSystem` 想解决的是“把零散后台工作统一交给一套中央调度器管理”这个问题。它当前暴露的 API 形状已经覆盖了商用引擎任务系统常见的几个入口：
 
-## 声明概览
+- 单例式全局访问。
+- 工作线程池初始化与关闭。
+- 按优先级提交任务。
+- 批量任务入口 `ParallelFor()`。
+- 任务组创建与销毁。
+- 回投主线程的回调队列。
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `TaskSystem` | `class` | 头文件中的公开声明。 |
+这种设计方向本身是对的。商业级引擎很少要求上层系统自己手搓 `std::thread`，而是倾向于通过中央 job system 统一调度、限流、统计和同步。
 
-## 公共方法
+## 当前实现边界
 
-| 方法 | 描述 |
+当前 `TaskSystem` 仍然明显处于原型阶段，尤其要注意以下事实：
+
+- [Submit](Submit.md) 当前存在严重生命周期问题: 任务指针被压入队列后，对应 `unique_ptr` 却会在函数返回时销毁对象，导致队列中留下悬空指针。
+- 工作线程取任务时，`GetNextTask()` 访问 `m_taskQueue` 没有使用与入队一致的 `m_queueMutex`，当前存在未同步并发访问。
+- [Wait](Wait.md) 还是空实现。
+- [ParallelFor](ParallelFor.md) 会立即返回，不会等待所有分片完成。
+- [Initialize](Initialize.md) 只真正使用了 `TaskSystemConfig::workerThreadCount`，其余配置项当前都被忽略。
+- [Shutdown](Shutdown.md) 之后 `m_shutdown` 不会恢复为 `false`，重新初始化路径当前基本不可用。
+- [TaskGroup](../TaskGroup/TaskGroup.md) 创建出来后，只是被登记到列表里，并没有接入任务执行与完成统计。
+
+因此，当前 `TaskSystem` 不应被当成商业级 job system 使用。更准确的定位是: API 轮廓已经出现，但核心正确性还没有收敛。
+
+## 公开方法
+
+| 方法 | 说明 |
 |------|------|
-| [Get](Get.md) | 获取相关状态或对象。 |
-| [Initialize](Initialize.md) | 初始化内部状态。 |
-| [Shutdown](Shutdown.md) | 关闭并清理内部状态。 |
-| [Submit](Submit.md) | 公开方法，详见头文件声明。 |
-| [CreateTaskGroup](CreateTaskGroup.md) | 创建新对象或资源。 |
-| [DestroyTaskGroup](DestroyTaskGroup.md) | 公开方法，详见头文件声明。 |
-| [Wait](Wait.md) | 公开方法，详见头文件声明。 |
-| [GetWorkerThreadCount](GetWorkerThreadCount.md) | 获取相关状态或对象。 |
-| [Update](Update.md) | 更新运行时状态。 |
-| [ParallelFor](ParallelFor.md) | 公开方法，详见头文件声明。 |
-| [RunOnMainThread](RunOnMainThread.md) | 公开方法，详见头文件声明。 |
+| [Get](Get.md) | 取得全局单例实例。 |
+| [Initialize](Initialize.md) | 初始化工作线程池。 |
+| [Shutdown](Shutdown.md) | 停止工作线程并关闭系统。 |
+| [Submit](Submit.md) | 提交一个任务对象或 lambda。 |
+| [CreateTaskGroup](CreateTaskGroup.md) | 创建任务组。 |
+| [DestroyTaskGroup](DestroyTaskGroup.md) | 销毁任务组。 |
+| [Wait](Wait.md) | 等待指定任务完成。 |
+| [GetWorkerThreadCount](GetWorkerThreadCount.md) | 查询当前配置的工作线程数。 |
+| [Update](Update.md) | 执行主线程回调队列。 |
+| [ParallelFor](ParallelFor.md) | 把区间拆成多个高优先级任务提交。 |
+| [RunOnMainThread](RunOnMainThread.md) | 把回调排入主线程队列。 |
+
+## 设计说明
+
+为什么引擎仍然需要这样的中心化系统，而不是到处直接开线程：
+
+- 线程数量需要统一治理，否则很容易过量创建后台线程。
+- 优先级、主线程回投、profiling 和依赖图等能力，通常都需要一个公共调度中心。
+- 资源加载、脚本预处理、导航构建、烘焙和编辑器后台任务，往往都需要共享同一套任务基础设施。
+
+这也是为什么很多商业引擎会把“线程原语”和“任务系统”都保留下来:
+
+- 锁和线程解决底层同步与平台适配问题。
+- 任务系统解决更高层的批处理、吞吐量和生命周期协调问题。
+
+## 使用建议
+
+- 当前源码中，低层同步原语比 `TaskSystem` 更成熟。
+- 如果确实要继续推进这个模块，优先修正任务所有权、队列同步、等待语义和关闭语义，再谈 profiling、work stealing 或任务依赖图。
 
 ## 相关文档
 
-- [当前目录](../Threading.md) - 返回 `Threading` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前模块](../Threading.md)
+- [TaskSystemConfig](../TaskSystemConfig/TaskSystemConfig.md)
+- [TaskGroup](../TaskGroup/TaskGroup.md)
+- [Synchronization And Task System Limits](../../../_guides/Threading/Synchronization-And-TaskSystem-Limits.md)