asyncio

Python中处理并发有三种主要范式：多线程（threading）、多进程（multiprocessing）和异步IO（asyncio）

Agentica采用async-first（异步优先）架构，基于Python的asyncio生态构建

asyncio需要整个调用链都支持async/await，改造成本极高

对于等待子进程完成这类IO密集型任务，线程切换的开销远小于收益，多线程比asyncio更适合

Python的asyncio是Python 3.4引入的标准库

Python的asyncio是基于单线程事件循环的协程并发模型，asyncio.gather并非真正的CPU并行，而是I/O并发

PyO3是Rust语言的Python绑定库，通过Rust的类型系统和所有权机制封装CPython API的底层细节

AgentScope的运行要求使用异步编程（async/await），对话方法需用async def定义、调用模型处使用await，启动时须使用asyncio.run()之类的异步入口，不能直接同步调用。

在 asyncio 中，Task.cancel() 注入的 CancelledError 仍会触发 finally，但如果 finally 内部有 await 且取消信号再次到达，释放逻辑可能被中断。

为避免同一仓库并发建图竞争，RepoBuddy 为每个仓库维护一个 `asyncio.Task` 并用 `asyncio.shield` 保护，让所有调用方共享同一次构建结果（请求合并模式）。

在 asyncio 环境下，SQLAlchemy 隐式懒加载会触发 MissingGreenlet 错误，且往往在序列化响应时才爆发。

将 async 视为基础设施层关注点、把数据获取与业务决策分离的做法（如 decide_checkout 接收 order 和 profile 参数而非自行获取），可让业务逻辑与基础设施解耦，保持可测试和可复用

async def 定义的函数返回协程对象，必须由事件循环驱动执行；await 关键字只能在 async 函数内部使用，因此一旦某一层是异步的，所有调用它的同步函数都必须改为 async（函数着色问题）

流式播放方案使用asyncio.create_subprocess_exec启动ffmpeg进程，参数指定pipe:0作为输入、s16le为输出格式、48000Hz采样率、双声道，循环从响应流读取1024字节的块写入ffmpeg stdin。

批量摄取使用asyncio.Semaphore(10)限制并发，防止嵌入服务被压垮。

Python 3.11 引入 tomllib 模块用于 TOML 解析，并带来 asyncio 的 TaskGroup 和 timeout() 特性以及 datetime.UTC 别名。

摄入管线通过计算文档内容的SHA256哈希（取前16位）作为chunk_hash来实现幂等性，批量摄入使用asyncio.Semaphore(10)控制并发。

单用户场景下阻塞事件循环的代价为零，因为一个 2.3 秒的阻塞调用看起来就像一个 2.3 秒的 LLM 调用。

开启 asyncio 调试模式并设置 loop.slow_callback_duration = 0.1 可以记录每个超过阈值的回调及其对应任务，但调试模式有额外开销，不适合生产环境。

延迟监控器通过周期性 asyncio.sleep 任务检测事件循环延迟，开销几乎为零，可长期在生产环境运行。