taskgroup 是 python 3.11 引入的结构化并发机制，解决 asyncio.gather() 在错误传播、资源清理和取消语义上的根本缺陷，实现“一挂全收”，异常聚合后重抛，子任务生命周期统一管理。
TaskGroup 是 Python 3.11 引入的真正可用、值得默认启用的异步任务管理机制，它解决了 asyncio.gather() 长期以来在错误传播、资源清理和取消语义上的根本缺陷。
为什么 asyncio.gather() 在出错时不可靠
用 asyncio.gather() 并发跑多个协程时，只要有一个抛异常，其余还在运行的任务不会自动取消——它们变成“孤儿协程”，继续占用事件循环、可能泄漏资源或产生副作用。
常见错误现象包括：
- 日志里只看到第一个异常，但后台 HTTP 请求仍在发、数据库连接没关
- 用
return_exceptions=True后所有结果都包成Exception对象，业务逻辑要额外判别是否真失败 - 无法区分“某个子任务被父任务取消”和“子任务自己出错”，调试困难
这些不是写法问题，是 gather() 的设计限制：它不参与结构化并发（structured concurrency）。
TaskGroup 怎么做到“一个挂，全收手”
TaskGroup 强制要求所有子任务在同一个作用域内启动，并在退出时统一处理生命周期。它的核心保障是：任一子任务 raise 异常或被 cancel，整个 group 立即进入“终止阶段”：未完成的子任务全部被 cancel，已抛的异常聚合后重新 raise。
实操建议：
仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...
- 用
async with asyncio.TaskGroup() as tg:包裹所有并发任务，不要手动创建asyncio.create_task() - 子任务通过
tg.create_task(coro)启动，而非asyncio.create_task()—— 这是关键区别，否则不进 group 管理 - 若需提前取消某子任务，调用
task.cancel()即可；group 会感知并触发整体清理 - 异常类型保留原样，不会被包装，
except ValueError:能直接捕获子任务抛的ValueError
示例片段：
async with asyncio.TaskGroup() as tg:
task1 = tg.create_task(fetch_url("https://a.com"))
task2 = tg.create_task(fetch_url("https://b.com"))
task3 = tg.create_task(parse_data())
# 这里 task1/task2/task3 要么全成功，要么某个失败时其余被 cancel 并抛出 GroupExeption
和 asyncio.timeout() 配合时要注意什么
TaskGroup 和超时组合使用很自然，但容易忽略取消顺序问题：如果外层 asyncio.timeout() 触发，它会 cancel 整个 async with 块，而 TaskGroup 的退出逻辑必须在 cancel 完成后再执行清理。Python 3.11.2+ 已修复此竞态，但低版本仍可能遇到 RuntimeError: Task group is closed。
安全做法：
- 升级到 Python ≥ 3.11.2（推荐）
- 避免在
TaskGroup内部再套一层asyncio.timeout()；改用asyncio.wait_for(tg.create_task(...), timeout=5) - 若必须嵌套，确保外层 timeout 的
__aexit__不早于TaskGroup.__aexit__执行——实际中更稳妥的是把 timeout 放在 group 外围
你可能没意识到的兼容性细节
TaskGroup 不是语法糖，它改变了 asyncio 的调度行为：子任务共享同一 cancellation scope，且 asyncio.current_task().get_coro() 返回的协程对象，在被 cancel 后状态变为 CORO_CLOSED，而不是 CORO_SUSPENDED。这对依赖协程状态做判断的库（比如某些自定义调试器或监控中间件）可能有影响。
另外，TaskGroup 目前不支持 “仅取消部分子任务后继续运行其他任务” —— 它是原子性的。如果业务需要“尽力而为 + 忽略个别失败”，仍得回退到 gather(return_exceptions=True)，或者手动用 create_task() + asyncio.shield() 控制取消边界。
真正健壮的异步管理，不在于能并发多少任务，而在于失败时能否清晰归因、可控收口。这点上 TaskGroup 把门槛降到了写对缩进就能用好的程度——但前提是，你得真把它当结构化并发的基石来用，而不是另一个 gather 替代品。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
