docs: rebuild Threading API content

docs/api/XCEngine/Threading/Task/AddRef.md

@@ -0,0 +1,24 @@
+# ITask::AddRef
+
+增加任务对象引用计数。
+
+```cpp
+void AddRef();
+```
+
+## 行为说明
+
+当前头文件内联实现执行：
+
+```cpp
+m_refCount.fetch_add(1);
+```
+
+## 返回值
+
+- 无。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [Release](Release.md)

docs/api/XCEngine/Threading/Task/Destructor.md

@@ -0,0 +1,20 @@
+# ITask::Destructor
+
+通过基类指针安全销毁任务对象。
+
+```cpp
+virtual ~ITask() = default;
+```
+
+## 行为说明
+
+虚析构函数保证派生任务能够通过 `ITask*` 正确析构。
+
+## 返回值
+
+- 无。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [Release](Release.md)

docs/api/XCEngine/Threading/Task/Execute.md

@@ -0,0 +1,20 @@
+# ITask::Execute
+
+执行任务主体。
+
+```cpp
+virtual void Execute() = 0;
+```
+
+## 行为说明
+
+这是纯虚接口，具体任务逻辑由派生类实现。
+
+## 返回值
+
+- 无。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [OnComplete](OnComplete.md)

docs/api/XCEngine/Threading/Task/GetId.md

@@ -0,0 +1,20 @@
+# ITask::GetId
+
+读取任务 ID。
+
+```cpp
+uint64_t GetId() const;
+```
+
+## 行为说明
+
+当前头文件内联实现直接返回 `m_id`。
+
+## 返回值
+
+- `uint64_t` - 当前任务 ID。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [SetId](SetId.md)

docs/api/XCEngine/Threading/Task/GetPriority.md

@@ -0,0 +1,20 @@
+# ITask::GetPriority
+
+读取任务优先级。
+
+```cpp
+TaskPriority GetPriority() const;
+```
+
+## 行为说明
+
+当前头文件内联实现直接返回 `m_priority`。
+
+## 返回值
+
+- `TaskPriority` - 当前任务优先级。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [SetPriority](SetPriority.md)

docs/api/XCEngine/Threading/Task/GetStatus.md

@@ -0,0 +1,20 @@
+# ITask::GetStatus
+
+读取任务状态。
+
+```cpp
+TaskStatus GetStatus() const;
+```
+
+## 行为说明
+
+当前头文件内联实现通过 `m_status.load()` 返回原子状态值。
+
+## 返回值
+
+- `TaskStatus` - 当前任务状态。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [SetStatus](SetStatus.md)

docs/api/XCEngine/Threading/Task/OnCancel.md

@@ -0,0 +1,20 @@
+# ITask::OnCancel
+
+任务取消时的回调钩子。
+
+```cpp
+virtual void OnCancel() {}
+```
+
+## 行为说明
+
+当前基类默认实现为空，不做任何事。
+
+## 返回值
+
+- 无。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [OnComplete](OnComplete.md)

docs/api/XCEngine/Threading/Task/OnComplete.md

@@ -0,0 +1,20 @@
+# ITask::OnComplete
+
+任务完成后的回调钩子。
+
+```cpp
+virtual void OnComplete() {}
+```
+
+## 行为说明
+
+当前基类默认实现为空，不做任何事。
+
+## 返回值
+
+- 无。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [Execute](Execute.md)

docs/api/XCEngine/Threading/Task/Release.md

@@ -0,0 +1,28 @@
+# ITask::Release
+
+释放一次任务对象引用。
+
+```cpp
+void Release();
+```
+
+## 行为说明
+
+当前头文件内联实现会：
+
+1. 执行 `m_refCount.fetch_sub(1)`
+2. 如果旧值正好是 `1`，则执行 `delete this`
+
+## 返回值
+
+- 无。
+
+## 注意事项
+
+- 这是一套侵入式引用计数协议，默认假设对象是 `new` 出来的。
+- 如果对栈对象调用 `Release()` 并走到 `delete this`，会产生未定义行为。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [AddRef](AddRef.md)

docs/api/XCEngine/Threading/Task/SetId.md

@@ -0,0 +1,24 @@
+# ITask::SetId
+
+设置任务 ID。
+
+```cpp
+void SetId(uint64_t id);
+```
+
+## 行为说明
+
+当前头文件内联实现直接执行 `m_id = id`。
+
+## 参数
+
+- `id` - 要写入的任务 ID。
+
+## 返回值
+
+- 无。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [GetId](GetId.md)

docs/api/XCEngine/Threading/Task/SetPriority.md

@@ -0,0 +1,24 @@
+# ITask::SetPriority
+
+设置任务优先级。
+
+```cpp
+void SetPriority(TaskPriority priority);
+```
+
+## 行为说明
+
+当前头文件内联实现直接执行 `m_priority = priority`。
+
+## 参数
+
+- `priority` - 要写入的优先级。
+
+## 返回值
+
+- 无。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [GetPriority](GetPriority.md)

docs/api/XCEngine/Threading/Task/SetStatus.md

@@ -0,0 +1,24 @@
+# ITask::SetStatus
+
+设置任务状态。
+
+```cpp
+void SetStatus(TaskStatus status);
+```
+
+## 行为说明
+
+当前头文件内联实现直接把 `status` 写入原子成员 `m_status`。
+
+## 参数
+
+- `status` - 要写入的新状态。
+
+## 返回值
+
+- 无。
+
+## 相关文档
+
+- [返回类型总览](Task.md)
+- [GetStatus](GetStatus.md)

docs/api/XCEngine/Threading/Task/Task.md

@@ -1,36 +1,74 @@
-# Task
+# ITask
 
 **命名空间**: `XCEngine::Threading`
 
-**类型**: `enum class`
+**类型**: `class (abstract interface)` + `enum class`
 
 **头文件**: `XCEngine/Threading/Task.h`
 
-**描述**: 定义 `XCEngine/Threading` 子目录中的 `Task` public API。
+**描述**: 定义任务优先级、任务状态以及带侵入式引用计数的抽象任务基类 `ITask`。
 
 ## 概述
 
-`Task.h` 是 `XCEngine/Threading` 子目录 下的 public header，当前页面作为平行目录中的 canonical 总览，用于汇总该头文件暴露的主要声明。
+`Task.h` 暴露了三类核心概念：
 
-## 声明概览
+- `TaskPriority`：任务优先级枚举。
+- `TaskStatus`：任务状态枚举。
+- `ITask`：任务执行、完成回调、取消回调和引用计数的统一基类。
 
-| 声明 | 类型 | 说明 |
-|------|------|------|
-| `TaskPriority` | `enum class` | 头文件中的公开声明。 |
-| `TaskStatus` | `enum class` | 头文件中的公开声明。 |
-| `ITask` | `class` | 头文件中的公开声明。 |
+这种设计很像很多商业引擎早期 job system 的起点：先用一个稳定任务抽象把“执行单元”统一起来，再围绕它搭调度器、主线程回调和任务组。
 
-## 枚举值
+## 枚举
 
-| 枚举值 | 数值 | 描述 |
-|--------|------|------|
-| `Critical` | `0` | 枚举项。 |
-| `High` | `1` | 枚举项。 |
-| `Normal` | `2` | 枚举项。 |
-| `Low` | `3` | 枚举项。 |
-| `Idle` | `4` | 枚举项。 |
+### `TaskPriority`
+
+当前优先级从高到低依次是：
+
+- `Critical`
+- `High`
+- `Normal`
+- `Low`
+- `Idle`
+
+### `TaskStatus`
+
+当前状态包括：
+
+- `Pending`
+- `Scheduled`
+- `Running`
+- `Completed`
+- `Failed`
+- `Canceled`
+
+## 当前实现边界
+
+- `ITask` 采用侵入式引用计数；`Release()` 在计数归零时直接 `delete this`，因此这套生命周期默认假设任务对象位于堆上。
+- `m_status` 是原子值，但 `m_priority` 和 `m_id` 不是。
+- 当前 `TaskSystem` 并没有完整使用这套状态机，例如提交时不会自动写入 `Scheduled`。
+
+## 公开方法
+
+| 方法 | 说明 |
+|------|------|
+| [Destructor](Destructor.md) | 虚析构函数。 |
+| [Execute](Execute.md) | 执行任务主体。 |
+| [OnComplete](OnComplete.md) | 完成回调。 |
+| [OnCancel](OnCancel.md) | 取消回调。 |
+| [GetPriority](GetPriority.md) | 读取优先级。 |
+| [GetStatus](GetStatus.md) | 读取状态。 |
+| [GetId](GetId.md) | 读取任务 ID。 |
+| [SetId](SetId.md) | 设置任务 ID。 |
+| [SetPriority](SetPriority.md) | 设置优先级。 |
+| [SetStatus](SetStatus.md) | 设置状态。 |
+| [AddRef](AddRef.md) | 增加引用计数。 |
+| [Release](Release.md) | 释放引用。 |
+
+## 已知实现
+
+- [LambdaTask](../LambdaTask/LambdaTask.md)
 
 ## 相关文档
 
-- [当前目录](../Threading.md) - 返回 `Threading` 平行目录
-- [API 总索引](../../../main.md) - 返回顶层索引
+- [当前模块](../Threading.md)
+- [TaskSystem](../TaskSystem/TaskSystem.md)