> 「手写中文版 claude code」教学系列：codeAgent 是我从零手写的 claude code 复刻——不套壳不翻译，从界面到 Agent 主循环一行行实现，注释全是中文大白话，适合当 Agent 开发教材从头读到尾。
> 协议层的坑补完了，往上一层走：工具在你的 Python 进程里怎么跑——同步工具别把整个事件循环冻住，子代理的工牌怎么带。
> 仓库：https://github.com/Harvil1/codeAgent


## 收银台比方

asyncio 程序 = **只有一台收银台的小店**。异步工具是扫码支付（不占台）；同步工具是趴在收银台上数一麻袋硬币——他数多久，整条队冻多久：心跳停、信号不响应、其他协程全部卡死。表现为"CPU 不高但界面死了"，最难排查的那种。

## 第一层：to_thread 丢线程池

`tools/registry.py` 的分发函数：

```python
async def dispatch(self, name: str, args: dict, **kwargs) -> str:
    """把 LLM 发起的工具调用转交给对应的干活函数，返回 JSON 字符串结果。

    怎么跑：
    - async handler（如 MCP / delegate 这些）：直接 await
    - 同步 handler（内置的同步工具）：丢到线程池里跑，不阻塞事件循环，
      handler 内部代码一行都不用改
    """
    ...
```

## 第二层：contextvars 的坑（重点）

线程池解决卡顿，但引出新问题。我的子代理跑在独立的 git worktree 里，"我在哪个目录干活"存在 ContextVar 里。换线程执行时**上下文会不会跟着走**，不同 API 答案不同：

```python
# 必须用 asyncio.to_thread（而不是 anyio.to_thread.run_sync）：
# 它会自动把当前 context（上下文变量，如 workspace_cwd）复制到
# 工作线程，否则 worktree 子代理拿到的还是主进程目录而非自己的
# 工作区目录（anyio 版本默认不带回 context）。
import asyncio as _asyncio
result = await _asyncio.to_thread(handler, args, **kwargs)
```

注释里写得很清楚：anyio 的版本默认不带 context 回来，子代理就会在**错误的目录**里改文件——不报错、不崩溃，就是安静地改错地方。这种 bug 上线了能把人逼疯。

## 为什么用 ContextVar 而不是 os.chdir

`agent/workspace_context.py` 文件头给了完整答案：

```python
"""子代理的工作目录（cwd）隔离机制——用 ContextVar 取代 os.chdir。

为什么需要：
    os.chdir 改的是整个进程共用的"当前目录"，就好比全家共用一块白板：
    线程 A 刚写上自己的目录，线程 B 一擦写上自己的，A 的就被踩了。
    ThreadPoolExecutor 并发跑子代理时必然互相打架。

    解法：contextvars.ContextVar 相当于给每个线程发一块自己的小白板，
    各写各的，互看不见（线程隔离），并发就安全了。
"""
_workspace_cwd: "contextvars.ContextVar[Optional[str]]" = contextvars.ContextVar(
    "codeagent_workspace_cwd", default=None,
)
```

## 小结

1. 同步工具必须离台：asyncio.to_thread 丢线程池，async 工具直接 await
2. 换线程丢上下文是隐形炸弹：anyio 默认不带回 context，子代理会跑错目录
3. 进程级状态（cwd）用 ContextVar 隔离，别用 os.chdir 全家共用一块白板

下一篇：**同一个 Ctrl+C 走两条路——Windows 下信号翻译的玄学坑**（附双通道兜底源码）。

---

仓库在这，注释全中文，欢迎 Star ⭐：https://github.com/Harvil1/codeAgent

**标签**：`Python` `asyncio` `contextvars` `Agent`

「手写中文版 claude code」教学系列：codeAgent 是我从零手写的 claude code 复刻——不套壳不翻译，从界面到 Agent 主循环一行行实现，注释全是中文大白话，适合当 Agent 开发教材从头读到尾。 协议层的坑补完了，往上一层走：工具在你的 Python 进程里怎么跑——同步工具别把整个事件循环冻住，子代理的工牌怎么带。 仓库：https://github.com/Harvil1/codeAgent

to_thread 与上下文变量

Agent 主程序是 asyncio 的，工具函数却是同步的——直接调会冻住整个事件循环（界面卡死、心跳全停）。本文附 codeAgent 真实源码：registry.dispatch 用 asyncio.to_thread 把同步工具丢线程池；更深的坑是子代理目录存在 ContextVar 里，anyio 版 to_thread 默认不带上下文、子代理会跑错目录。一行选型，决定多代理体系对不对。

编程语言

开发工具

后端

手写中文版Claude Code的codeAgent项目：详解同步工具通过asyncio.to_thread丢线程池避免阻塞事件循环，解决ContextVar线程传递的坑，用ContextVar替代os.chdir实现子代理工作目录隔离，仓库注释全中文，适合Agent开发学习。

代码解释

Windows

Python

Agent

JSON

2026上云采购 | AI焕新·智启新局

cpay

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

to_thread 与上下文变量-腾讯云开发者社区-腾讯云

to_thread 与上下文变量

to_thread 与上下文变量

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐