Wingman

Appearance

API: wingman.task ​

异步任务模块，提供任务提交与生命周期管理功能，支持重试、超时等特性。

模块概述 ​

task 模块提供任务管理功能：

  • 提交任务 - 提交任务执行（默认在调用线程同步执行，async: true 时后台线程执行）
  • 状态查询 - 获取任务状态
  • 等待完成 - 等待任务执行完成
  • 获取结果 - 获取任务执行结果
  • 取消任务 - 取消正在执行的任务
  • 暂停 / 恢复 - 协作式暂停执行中的任务，恢复后继续
  • 重试任务 - 重试失败的任务

提交任务 ​

submit(work, options?) / submit(work, options?) ​

说明：提交一个任务。

函数签名：

python
submit(work: Callable, options: dict = None) -> str
lua
submit(work: function, options: table = nil) -> string

参数：

  • work - 工作函数，接收上下文对象。默认 async: false，在调用线程同步执行；options.async = true 时才在后台线程执行（脚本回调不支持跨线程，后台任务的结果/事件经内部线程转投）
  • options - 可选配置
    • async / async - 是否后台线程执行，默认 false（同步）
    • timeoutMs / timeoutMs - 超时时间（毫秒），默认 30000
    • maxRetries / maxRetries - 最大重试次数，默认 0
    • backoffMs / backoffMs - 重试退避基数（毫秒），默认 500
    • backoffFactor / backoffFactor - 退避因子，默认 2.0
    • metadata / metadata - 元数据（任意对象）

返回：

  • 任务 ID
python
from wingman import task

# 提交任务
def my_work(ctx):
    # 执行一些耗时操作
    return {"result": 42}

task_id = task.submit(my_work, {
    "timeoutMs": 5000,
    "retry": {"max": 3, "backoffMs": 500}
})

获取任务状态 ​

status(task_id) / status(taskId) ​

说明：获取任务状态。

函数签名：

python
status(task_id: str) -> str
lua
status(taskId: string) -> string

参数：

  • task_id / taskId - 任务 ID

返回：

  • 状态字符串："pending", "running", "paused", "succeeded", "failed", "canceled", "timeout"
python
from wingman import task

# 检查状态
status = task.status(task_id)
print(f"任务状态: {status}")

等待任务完成 ​

wait(task_id, timeout_ms?) / wait(taskId, timeoutMs?) ​

说明：等待任务完成。

函数签名：

python
wait(task_id: str, timeout_ms: int = 30000) -> bool
lua
wait(taskId: string, timeoutMs: number = 30000) -> boolean

参数：

  • task_id / taskId - 任务 ID
  • timeout_ms / timeoutMs - 可选，等待超时（毫秒），默认 30000

返回：

  • 是否在超时前完成
python
from wingman import task

# 等待完成
if task.wait(task_id, 10000):
    result = task.result(task_id)
    print(f"任务完成: {result}")
else:
    error = task.error(task_id)
    print(f"任务失败: {error}")

获取任务结果 ​

result(task_id) / result(taskId) ​

说明：获取任务结果。

函数签名：

python
result(task_id: str) -> Any
lua
result(taskId: string) -> any

参数：

  • task_id / taskId - 任务 ID

返回：

  • Python: 任务返回值，如果任务失败或未完成返回 None
  • Lua: 任务返回值，如果任务失败或未完成返回 nil

获取错误信息 ​

error(task_id) / error(taskId) ​

说明：获取任务错误信息。

函数签名：

python
error(task_id: str) -> str
lua
error(taskId: string) -> string

参数：

  • task_id / taskId - 任务 ID

返回：

  • 错误信息字符串，无错误返回空字符串

取消任务 ​

cancel(task_id) / cancel(taskId) ​

说明：取消任务。

函数签名：

python
cancel(task_id: str) -> bool
lua
cancel(taskId: string) -> boolean

参数：

  • task_id / taskId - 任务 ID

返回：

  • 是否成功
python
from wingman import task

# 取消任务
task.cancel(task_id)

暂停 / 恢复任务 ​

pause(task_id) / pause(taskId) ​

说明：暂停任务。协作式语义——无法挂起正在执行的工作函数本身，暂停在 生命周期检查点生效：开工前驻留不执行、工作完成后结果扣住不落账、重试间隙 不进入下一次尝试；超时时钟在暂停期间停走。pending / running 之外的 状态（含不存在的任务）返回 false。

函数签名：

python
pause(task_id: str) -> bool
lua
pause(taskId: string) -> boolean

参数：

  • task_id / taskId - 任务 ID

返回：

  • 是否成功进入暂停（任务不存在或非可暂停状态返回 false）

resume(task_id) / resume(taskId) ​

说明：恢复暂停中的任务，放行全部驻留检查点（开工、结果落账、重试）。 仅 paused 状态返回 true，其他状态返回 false。

函数签名：

python
resume(task_id: str) -> bool
lua
resume(taskId: string) -> boolean

参数：

  • task_id / taskId - 任务 ID

返回：

  • 是否成功恢复（任务不存在或不在暂停状态返回 false）
python
from wingman import task

# 暂停执行中的任务
task.pause(task_id)

# 恢复执行
task.resume(task_id)

重试任务 ​

retry(task_id, options?) / retry(taskId, options?) ​

说明：重试失败的任务。

函数签名：

python
retry(task_id: str, options: dict = None) -> bool
lua
retry(taskId: string, options: table = nil) -> boolean

参数：

  • task_id / taskId - 任务 ID
  • options - 可选重试配置
    • maxRetries / maxRetries - 最大重试次数
    • backoffMs / backoffMs - 重试退避基数

返回：

  • 是否成功发起重试
python
from wingman import task

# 重试失败的任务
task.retry(task_id, {"maxRetries": 5, "backoffMs": 1000})

可用接口 ​

Python 函数Lua 函数说明参数
submit(work, options?)submit(work, options?)提交任务work: 工作函数
options: 配置(可选)
返回: 任务ID
cancel(taskId)cancel(taskId)取消任务taskId: 任务ID
返回: 是否成功
pause(taskId)pause(taskId)暂停任务(协作式)taskId: 任务ID
返回: 是否进入暂停
resume(taskId)resume(taskId)恢复暂停的任务taskId: 任务ID
返回: 是否恢复
status(taskId)status(taskId)获取状态taskId: 任务ID
返回: 状态字符串
wait(taskId, timeoutMs?)wait(taskId, timeoutMs?)等待完成taskId: 任务ID
timeoutMs: 等待超时(默认30000)
返回: 是否完成
result(taskId)result(taskId)获取结果taskId: 任务ID
返回: 任务结果
error(taskId)error(taskId)获取错误taskId: 任务ID
返回: 错误信息
retry(taskId, options?)retry(taskId, options?)重试任务taskId: 任务ID
options: 重试配置(可选)
返回: 是否成功

生命周期事件 ​

任务生命周期会触发以下事件。所有事件的载荷统一为 taskId, status, metadata 三个字段（不含 error——失败原因不随事件携带，需用 task.error(taskId) 查询）：

事件名说明载荷字段
task.submitted任务已提交taskId, status, metadata
task.started任务开始执行taskId, status, metadata
task.paused任务已暂停taskId, status, metadata
task.resumed任务已恢复taskId, status, metadata
task.succeeded任务成功taskId, status, metadata
task.failed任务失败taskId, status, metadata
task.canceled任务已取消taskId, status, metadata
task.timeout任务超时taskId, status, metadata
task.error任务入队被拒（async: true 且回调非线程安全时发出）error
python
from wingman import event

event.on("task.submitted", lambda e: print(f"任务提交: {e['payload']['taskId']}"))
event.on("task.started", lambda e: print("任务开始"))
event.on("task.paused", lambda e: print("任务暂停"))
event.on("task.resumed", lambda e: print("任务恢复"))
event.on("task.succeeded", lambda e: print("任务成功"))
event.on("task.failed", lambda e: print("任务失败，用 task.error(task_id) 查原因"))
event.on("task.canceled", lambda e: print("任务取消"))
event.on("task.timeout", lambda e: print("任务超时"))
event.on("task.error", lambda e: print(f"任务错误: {e['payload']['error']}"))