企业官网建设流程全解析

1. 项目概述：这不是AI模型部署，而是一场毛坯房级的Agent开发实战复盘

“pi agent 毛坯房装修踩坑”——这个标题乍看像家装博主的血泪史，实则精准击中了当前Agent开发圈最普遍、最隐蔽、也最容易被教程掩盖的真实困境：我们不是在搭建一个光鲜亮丽的成品智能体，而是在一片水泥钢筋裸露的毛坯房里，徒手接水电、砌隔断、铺地暖，连墙面找平都得自己调砂浆配比。“pi”不是指树莓派或Orange Pi硬件，而是指代Project Initialization（项目初始化）阶段的PI范式——即以最小可行闭环（Minimum Viable Loop）为起点，用最简依赖、最直白命令、最底层交互完成Agent核心执行链路的首次贯通。所谓“毛坯房”，就是彻底剥离所有封装框架、可视化界面、云托管服务后的原始开发环境：Windows + WSL2 + Ubuntu + Git Bash + 原生Python + 手动编译的依赖项。这里没有pip install agent-framework一键安装，只有curl下载源码、make编译C扩展、git commit --amend修正初始提交、bash -c "$(curl ...)"手动拉取构建脚本的硬核操作。

我过去三年带过17个Agent落地项目，从金融风控到工业质检，发现83%的新手卡点根本不在大模型调用或Prompt工程，而是在这个“毛坯房装修”阶段：WSL内核版本不匹配导致CUDA驱动失效、Git Bash路径解析错误引发/bin/bash: bad interpreter、PyTorch源码编译时因OpenMP版本冲突中断、甚至git config --global core.autocrlf true没设对，让换行符在Linux和Windows间反复撕裂代码逻辑。这些坑不会出现在HuggingFace文档里，但会真实消耗你3天调试时间。本文不讲LLM原理，不画架构图，只聚焦于如何用最原始的工具链，在Windows物理机上，用WSL2搭起一个能跑通agent execute命令的、可调试、可日志、可断点的最小Agent毛坯间。适合刚学完Python基础、想亲手造轮子而非调API的开发者，也适合被“开箱即用”宣传误导后陷入环境泥潭的中级工程师。你不需要懂Transformer，但必须知道/etc/wsl.conf里[wsl2] kernelCommandLine参数改错会导致整个子系统无法启动。

2. 核心思路拆解：为什么坚持“毛坯房”而非“精装交付”

2.1 拒绝黑盒封装：Agent开发的本质是控制流调试，不是模型调用

市面上90%的Agent框架教程，开场就是pip install langchain、from langchain.agents import AgentExecutor，看似高效，实则埋下三重隐患：
第一，依赖幻觉。当你在VSCode里按F5调试时，AgentExecutor.run()内部调用了多少层抽象？Tool类如何序列化传参？CallbackHandler的on_llm_start钩子在哪个线程触发？这些全被封装在__init__.py的1200行代码里。一旦出现agent execution terminated due to error.，你面对的是KeyError: 'intermediate_steps'这种无上下文报错，而非清晰的栈追踪。
第二，环境失真。生产环境是Docker容器+Kubernetes调度，而本地开发用conda虚拟环境+PyCharm，两者sys.path加载顺序、动态库链接路径、甚至os.environ变量注入时机都不同。我在某银行项目中遇到过：本地测试100%通过的Agent，在K8s Pod里因LD_LIBRARY_PATH未正确继承，调用libtorch.so时静默崩溃，日志只显示exit code 139。
第三，能力错配。新手误以为Agent = 大模型+工具链，实则Agent =状态机+决策引擎+可观测性管道。pi agent的“pi”恰恰强调：先让state_machine.py能读取input.json、输出output.json、记录trace.log，再谈接入LLM。就像装修毛坯房，必须先确认水电总闸能独立控制每个回路，才能装智能开关。

因此，本方案选择完全手动构建执行链路：

• 用bash脚本替代Makefile，因为make在WSL中常因/bin/sh软链接指向dash而非bash导致语法报错；
• 用git管理而非poetry，因poetry lock生成的poetry.lock文件在Windows路径下易出现\r\n换行符污染；
• PyTorch不走pip install torch，而用python setup.py build_ext --inplace源码编译，强制暴露CMAKE_PREFIX_PATH和TORCH_CUDA_ARCH_LIST等关键参数；
• git commit --amend成为每日必做操作，因为初始提交的.gitignore若漏掉__pycache__/，后续git status会持续提示未跟踪目录，干扰调试注意力。

提示：不要追求“一次配置永久生效”。WSL每次重启可能重置/etc/resolv.conf，导致curl超时；Git Bash升级后/usr/bin/bash路径可能变更；甚至Windows更新后WSL2内核会自动降级。把每次环境重置视为一次验证机会，而非故障。

2.2 工具链选型逻辑：为什么是WSL2+Git Bash+Ubuntu而非Docker或原生Linux

对比三种主流开发环境：

选择WSL2的核心理由在于调试可见性。当Agent执行卡在subprocess.Popen()时，ps aux | grep python能直接看到进程树；当libtorch报undefined symbol: omp_get_num_threads，ldd -r ./build/lib.linux-x86_64-cpython-310/torch/_C.cpython-310-x86_64-linux-gnu.so可定位缺失符号；当git commit --amend失败提示fatal: Unable to create '/mnt/c/Users/xxx/.git/index.lock'，立刻意识到是Windows资源管理器正占用该目录。这些信息在Docker容器里要么被日志截断，要么需多层docker exec穿透获取。

注意：WSL2安装到D盘并非技术必需，而是规避C盘空间焦虑。但wsl --import导入时，--version 2参数必须显式声明，否则默认创建WSL1（无systemd支持，无法运行systemctl管理服务）。

2.3 “毛坯房”验收标准：五个不可妥协的基线能力

真正的毛坯房不是“能跑就行”，而是具备可维护、可诊断、可演进的基础能力。我们定义五个硬性验收指标：

1. 可中断执行：Agent进程必须响应Ctrl+C并执行atexit.register()清理临时文件、关闭数据库连接、释放GPU显存。测试方法：在agent.py中插入time.sleep(300)，运行后按Ctrl+C，检查/tmp/agent_*.log是否被删除、nvidia-smi是否显示显存已释放。
2. 可追溯日志：所有日志必须包含[PID][TIMESTAMP][LEVEL]前缀，且DEBUG级别日志需记录sys._getframe().f_code.co_filename和lineno。禁用print()，统一用logging.getLogger(__name__).debug()。
3. 可复现构建：build.sh脚本执行后，生成的dist/agent-0.1.0-py3-none-any.whl文件，其sha256sum在任意WSL2实例中必须一致。这意味着setup.py中不能依赖datetime.now()生成版本号，而应从git describe --tags获取。
4. 可隔离测试：pytest tests/test_agent_execution.py必须在无网络、无GPU的环境下通过，所有外部依赖（如LLM API）需用pytest-mock打桩，且桩函数返回值必须与真实API响应结构完全一致（包括字段名大小写、空值类型）。
5. 可审计配置：所有配置项（如API密钥、超时时间）必须从config.yaml读取，且config.yaml不得提交至Git。git status应始终显示config.yaml在untracked状态，git check-ignore config.yaml返回config.yaml。

这五条标准，每一条都对应一个曾让我团队加班到凌晨三点的真实事故：第1条缺失导致Agent在K8s中OOM Kill后残留GPU句柄；第2条缺失让线上问题排查耗时从2小时延长至17小时；第3条缺失造成测试环境与生产环境行为不一致；第4条缺失使单元测试通过率虚高，上线后因API限流策略变更直接熔断；第5条缺失导致密钥泄露至GitHub公开仓库。

3. 核心环节实现：从WSL安装到Agent首次执行的全流程拆解

3.1 WSL2环境筑基：绕过微软商店的纯净安装法

WSL2官方安装流程（wsl --install）在企业网络下常因https://aka.ms/wslubuntu2004重定向失败而卡死。更可靠的方法是手动下载发行版并导入，全程可控：

# 步骤1：下载Ubuntu 22.04 LTS离线包（约300MB） # 访问 https://cloud-images.ubuntu.com/releases/22.04/release/ 下载 ubuntu-22.04-server-cloudimg-amd64-wsl.rootfs.tar.gz # 将文件保存至 C:\wsl\ubuntu2204.tar.gz # 步骤2：启用WSL功能（管理员PowerShell） dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart # 重启电脑 # 步骤3：设置WSL2为默认版本 wsl --set-default-version 2 # 步骤4：导入Ubuntu（非微软商店安装） mkdir C:\wsl\ubuntu2204 wsl --import Ubuntu-22.04 C:\wsl\ubuntu2204 C:\wsl\ubuntu2204.tar.gz --version 2 # 步骤5：设置默认用户（避免首次启动卡在root） # 创建 C:\wsl\ubuntu2204\etc\wsl.conf，内容如下： [wsl2] kernelCommandLine = "systemd.unified_cgroup_hierarchy=1" # [automount] # enabled = true # root = /mnt/ # options = "metadata,uid=1000,gid=1000,umask=22,fmask=11" # 步骤6：启动并初始化用户 wsl -d Ubuntu-22.04 # 在WSL终端中执行： sudo useradd -m -s /bin/bash devuser sudo passwd devuser echo "devuser ALL=(ALL) NOPASSWD:ALL" | sudo tee -a /etc/sudoers exit # 步骤7：设置默认登录用户（修改注册表） # Windows PowerShell（管理员）执行： Get-ChildItem "HKCU:\Software\Microsoft\Windows\CurrentVersion\Lxss\" | ForEach-Object { $distroName = (Get-ItemProperty $_.PSPath).DistributionName if ($distroName -eq "Ubuntu-22.04") { Set-ItemProperty $_.PSPath "DefaultUid" 1000 } }

关键细节说明：

• wsl --import比wsl --install更稳定，因它跳过微软CDN，直接使用本地tar包；
• kernelCommandLine = "systemd.unified_cgroup_hierarchy=1"是必须项，否则systemctl无法启动，影响后续Agent服务化部署；
• DefaultUid 1000确保WSL启动时自动登录devuser而非root，避免权限混乱；
• wsl.conf中注释掉[automount]段，因企业环境中/mnt/c挂载可能触发防病毒软件扫描，导致ls /mnt/c卡顿数秒。

实操心得：WSL2首次启动后，务必执行sudo apt update && sudo apt upgrade -y。Ubuntu 22.04初始镜像中的curl版本为7.81.0，存在HTTP/2连接复用bug，升级后变为7.85.0可修复。此问题会导致Agent调用LLM API时偶发Connection reset by peer。

3.2 Git与Bash环境精调：解决Windows路径与Linux生态的撕裂

Git Bash和WSL2的/bin/bash本质不同：前者是MinGW编译的POSIX层，后者是完整Linux内核。但二者在路径处理上极易混淆，典型症状是git clone https://github.com/xxx/pi-agent.git后，cd pi-agent报错No such file or directory。根源在于Windows路径分隔符\与Linux/的转换逻辑差异。

解决方案分三层：

第一层：WSL2内Git配置

# 在WSL2中执行 git config --global core.autocrlf input git config --global core.filemode false git config --global init.defaultBranch main # 关键！禁用Windows风格路径转换 git config --global core.precomposeunicode true

core.autocrlf input确保Windows编辑器保存的\r\n在提交时转为\n，检出时不转换；core.filemode false避免因Windows文件系统无执行权限位导致git status持续提示chmod变更；core.precomposeunicode true解决macOS/Windows文件名Unicode规范化差异。

第二层：Git Bash专用配置
在Git Bash中，编辑~/.bashrc添加：

# 强制Git Bash使用WSL2的Python解释器 export PATH="/mnt/wsl/ubuntu2204/usr/bin:$PATH" alias python="/mnt/wsl/ubuntu2204/usr/bin/python3" # 解决Windows路径在bash中解析错误 winpath() { echo "$1" | sed 's/\\/\//g' | sed 's/C:/\/mnt\/c/g' | sed 's/D:/\/mnt\/d/g' }

这样在Git Bash中执行python $(winpath "C:\project\agent.py")即可调用WSL2的Python，避免/bin/bash: bad interpreter错误。

第三层：VSCode无缝调试配置
在VSCode中安装Remote - WSL插件，打开WSL2工作区后，创建.vscode/settings.json：

{ "python.defaultInterpreterPath": "/usr/bin/python3", "python.testing.pytestArgs": ["tests/"], "terminal.integrated.profiles.linux": { "WSL Bash": { "path": "C:\\Windows\\System32\\wsl.exe", "args": ["-d", "Ubuntu-22.04"] } } }

此时VSCode终端自动启动WSL2，调试器直接附加到WSL2进程，breakpoint()可正常命中。

常见陷阱：git commit --amend失败时，若提示fatal: cannot run hooks，检查.git/hooks/pre-commit是否为Windows格式（含\r\n）。用dos2unix .git/hooks/pre-commit修复，或在Git Bash中用unix2dos反向转换。

3.3 PyTorch源码编译：绕过pip安装的CUDA兼容性雷区

pip install torch在WSL2中常因CUDA版本错配失败。例如Windows宿主机CUDA 12.2，而pip默认安装的torch-2.1.0+cu118要求CUDA 11.8，导致import torch时报OSError: libcudart.so.11.8: cannot open shared object file。根本解法是源码编译，强制绑定宿主机CUDA版本：

# 步骤1：确认宿主机CUDA版本 # Windows PowerShell执行： nvidia-smi | Select-String "CUDA Version" # 输出：CUDA Version: 12.2 # 步骤2：在WSL2中安装匹配的CUDA Toolkit # 访问 https://developer.nvidia.com/cuda-toolkit-archive 下载 cuda_12.2.0_535.54.03_linux.run # 上传至WSL2 /tmp/ 目录 sudo sh /tmp/cuda_12.2.0_535.54.03_linux.run --silent --no-opengl-libs --override # 步骤3：设置环境变量（添加至 ~/.bashrc） export CUDA_HOME=/usr/local/cuda-12.2 export PATH=$CUDA_HOME/bin:$PATH export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH # 步骤4：克隆PyTorch源码并编译 git clone --recursive https://github.com/pytorch/pytorch cd pytorch # 设置编译参数（关键！） export TORCH_CUDA_ARCH_LIST="8.6" # 根据nvidia-smi显示的GPU架构设置，如RTX 4090为8.9，RTX 3090为8.6 export USE_CUDNN=1 export BUILD_SHARED_LIBS=ON # 编译（4核CPU约需45分钟） python setup.py build_ext --inplace python setup.py install

参数详解：

• TORCH_CUDA_ARCH_LIST必须精确匹配GPU架构，查表地址：https://developer.nvidia.com/cuda-gpus。填错会导致编译通过但运行时报invalid device function；
• USE_CUDNN=1启用cuDNN加速，否则CNN推理速度下降3倍；
• BUILD_SHARED_LIBS=ON生成动态库，避免静态链接导致的libtorch.so体积膨胀至2GB。

验证编译成功：

import torch print(torch.__version__) # 应输出类似 2.1.0+cu122 print(torch.cuda.is_available()) # 应返回 True print(torch.cuda.get_device_name(0)) # 应显示GPU型号

实操心得：编译过程若卡在[ 87%] Building NVCC，检查nvidia-smi是否显示GPU被其他进程占用。WSL2中nvidia-smi有时显示No running processes found却实际有进程，用sudo fuser -v /dev/nvidia*强制释放。

3.4 Agent最小执行链路搭建：从零实现pi agent execute

“pi agent”的核心不是模型，而是执行协议。我们定义最简协议：

• 输入：input.json，含{"query": "北京天气", "tools": ["weather_api"]}
• 输出：output.json，含{"result": "晴，25°C", "steps": [{"tool": "weather_api", "input": "北京"}]}
• 日志：trace.log，记录每步耗时、内存占用、GPU显存变化

实现步骤：

步骤1：创建项目骨架

mkdir -p pi-agent/{src/{agent,tools},tests,docs,scripts} touch src/agent/__init__.py src/agent/executor.py src/tools/__init__.py src/tools/weather_api.py

步骤2：编写src/agent/executor.py

import json import logging import time import psutil import torch from typing import Dict, Any # 配置日志 logging.basicConfig( level=logging.DEBUG, format='[%(process)d][%(asctime)s][%(levelname)s] %(message)s', handlers=[logging.FileHandler('trace.log', encoding='utf-8')] ) logger = logging.getLogger(__name__) class AgentExecutor: def __init__(self): self.tools = {} def register_tool(self, name: str, func): self.tools[name] = func def execute(self, input_data: Dict[str, Any]) -> Dict[str, Any]: start_time = time.time() result = {"result": "", "steps": []} # 记录初始资源 mem_before = psutil.virtual_memory().used gpu_mem_before = torch.cuda.memory_allocated(0) if torch.cuda.is_available() else 0 try: for tool_name in input_data.get("tools", []): if tool_name not in self.tools: raise ValueError(f"Tool {tool_name} not registered") tool_start = time.time() tool_result = self.tools[tool_name](input_data["query"]) tool_end = time.time() step = { "tool": tool_name, "input": input_data["query"], "output": tool_result, "duration_ms": int((tool_end - tool_start) * 1000) } result["steps"].append(step) result["result"] = tool_result logger.debug(f"Executed {tool_name}: {tool_result} in {step['duration_ms']}ms") except Exception as e: logger.error(f"Execution failed: {str(e)}", exc_info=True) result["error"] = str(e) # 记录资源消耗 mem_after = psutil.virtual_memory().used gpu_mem_after = torch.cuda.memory_allocated(0) if torch.cuda.is_available() else 0 total_time = int((time.time() - start_time) * 1000) logger.info(f"Execution completed in {total_time}ms. " f"Memory delta: {mem_after - mem_before} bytes. " f"GPU memory delta: {gpu_mem_after - gpu_mem_before} bytes.") return result # 全局执行器实例 executor = AgentExecutor()

步骤3：编写src/tools/weather_api.py（模拟工具）

import time import random def weather_api(query: str) -> str: """模拟天气API，实际项目中替换为requests.post""" time.sleep(0.5) # 模拟网络延迟 # 随机返回结果，避免缓存干扰 results = [ f"{query}晴，{random.randint(20,30)}°C", f"{query}多云，{random.randint(18,28)}°C", f"{query}小雨，{random.randint(15,25)}°C" ] return random.choice(results)

步骤4：编写scripts/run_agent.sh

#!/bin/bash # 脚本需在WSL2中执行 set -e # 任何命令失败即退出 # 检查输入文件 if [ ! -f "input.json" ]; then echo "Error: input.json not found" exit 1 fi # 导入Python模块路径 export PYTHONPATH="${PYTHONPATH}:/mnt/c/project/pi-agent/src" # 执行Agent python3 -c " import json from agent.executor import executor from tools.weather_api import weather_api # 注册工具 executor.register_tool('weather_api', weather_api) # 读取输入 with open('input.json', 'r', encoding='utf-8') as f: input_data = json.load(f) # 执行 result = executor.execute(input_data) # 写入输出 with open('output.json', 'w', encoding='utf-8') as f: json.dump(result, f, ensure_ascii=False, indent=2) print('Agent executed successfully. Check output.json and trace.log') "

步骤5：首次执行验证

# 创建input.json echo '{"query": "北京天气", "tools": ["weather_api"]}' > input.json # 赋予脚本执行权限 chmod +x scripts/run_agent.sh # 运行 ./scripts/run_agent.sh

预期输出：

• output.json包含"result": "北京天气晴，25°C"等随机结果；
• trace.log首行应为[1234][2023-10-01 10:00:00,000][INFO] Execution completed in 520ms...；
• ps aux | grep python应显示python3 -c ...进程，Ctrl+C可立即终止。

注意事项：PYTHONPATH必须包含/mnt/c/project/pi-agent/src，因WSL2中C:\project\pi-agent映射为/mnt/c/project/pi-agent。若用/c/project/pi-agent会报ModuleNotFoundError。

4. 常见问题与排查技巧实录：那些让开发者彻夜难眠的毛坯房裂缝

4.1 WSL2内核更新失败：wsl needs updating your version of windows subsystem for linux

现象：执行wsl --update报错The operation was canceled，或wsl --list --verbose显示VERSION为Kernel: 5.10.102.1（旧版）。

根因分析：
Windows Update服务被组策略禁用，或WSL2内核更新包（wsl_update_x64.msi）下载被防火墙拦截。

三步排查法：

1. 验证Windows版本：

   # PowerShell执行 Get-ComputerInfo | Select-Object WindowsVersion, OsHardwareAbstractionLayer

   要求WindowsVersion≥22H2（即22621），OsHardwareAbstractionLayer≥10.0.22621.0。若不满足，需升级Windows。

2. 手动下载内核更新包：
   访问 https://wslstorestorage.blob.core.windows.net/wslblob/wsl_update_x64.msi ，下载后双击安装。安装后重启WSL2：

   wsl --shutdown wsl -d Ubuntu-22.04

3. 强制刷新WSL2内核：
   若仍失败，在Windows PowerShell（管理员）执行：

   wsl --update --web-download # --web-download参数强制从微软官网下载，绕过本地缓存

独家技巧：若公司网络严格限制外网，可将wsl_update_x64.msi拷贝至同事电脑，用wsl --update --install命令离线安装。

4.2 Git Bash中文乱码：git log显示??而非汉字

现象：在Git Bash中执行git log --oneline，中文提交信息显示为??。

根因：Git Bash默认字符集为ISO-8859-1，而UTF-8编码的中文需显式声明。

解决方案：

# 在Git Bash中执行 git config --global core.quotepath false git config --global i18n.logOutputEncoding utf-8 git config --global i18n.commitEncoding utf-8 # 重启Git Bash

core.quotepath false禁用路径转义，i18n.*参数强制Git使用UTF-8编码读写日志。

实操验证：创建含中文的提交git commit -m "修复天气API超时问题"，再执行git log --oneline，应正常显示中文。

4.3 PyTorch CUDA初始化失败：CUDA error: no kernel image is available for execution on the device

现象：import torch成功，但torch.cuda.is_available()返回False，或执行x = torch.randn(3,3).cuda()时报错。

根因：CUDA Toolkit版本与GPU驱动版本不兼容。例如CUDA 12.2要求NVIDIA驱动≥525.60.13，而Windows宿主机驱动为516.94。

排查步骤：

1. 确认驱动版本：

   # Windows PowerShell nvidia-smi | Select-String "Driver Version" # 输出：Driver Version: 516.94

2. 查询CUDA兼容矩阵：
   访问 https://docs.nvidia.com/cuda/cuda-toolkit-release-notes/index.html ，找到CUDA 12.2对应的最低驱动版本（525.60.13）。

3. 升级驱动：

   • 访问 https://www.nvidia.com/Download/index.aspx
   • 手动选择GPU型号，下载Studio驱动（非Game Ready），因其对CUDA支持更稳定；
   • 安装时勾选“执行清洁安装”。

4. 验证CUDA：

   # WSL2中执行 nvcc --version # 应输出 release 12.2, V12.2.128 /usr/local/cuda-12.2/samples/1_Utilities/deviceQuery/deviceQuery # 应显示 Result = PASS

注意：驱动升级后需重启Windows，否则WSL2无法识别新驱动。

4.4 Agent执行卡死：agent execution terminated due to error.无堆栈

现象：运行./scripts/run_agent.sh后终端无输出，ps aux | grep python显示进程存在但CPU占用0%，Ctrl+C无效。

根因：Python进程陷入无限等待，常见于：

• subprocess.Popen()未设置timeout，子进程挂起；
• threading.Lock()未释放，线程死锁；
• torch.cuda.synchronize()等待GPU任务，但GPU被其他进程占用。

四步诊断法：

1. 查看进程状态：

   ps -o pid,ppid,comm,wchan -p $(pgrep -f "run_agent.sh") # wchan列显示进程等待的内核函数，如'schedule'表示休眠，'futex_wait_queue_me'表示锁等待

2. 抓取线程堆栈：

   # 获取Python进程PID PID=$(pgrep -f "run_agent.sh" | head -1) # 生成线程堆栈 sudo gdb -p $PID -ex "thread apply all bt" -ex "quit" 2>/dev/null | grep -A 20 "File"

3. 检查GPU占用：

   nvidia-smi --query-compute-apps=pid,used_memory --format=csv,noheader,nounits # 若有其他PID占用GPU，用 sudo kill -9 <PID> 释放

4. 添加超时保护：
   修改executor.py中的execute方法，在try块内添加：

   import signal def timeout_handler(signum, frame): raise TimeoutError("Agent execution timeout") signal.signal(signal.SIGALRM, timeout_handler) signal.alarm(300) # 5分钟超时 # ...原有逻辑... signal.alarm(0) # 取消报警

实操心得：在trace.log中添加logging.info(f"Thread count: {threading.active_count()}")，可快速发现线程泄漏。

4.5 Git提交失败：fatal: unable to access 'https://github.com/xxx/pi-agent.git/': Could not resolve host: github.com

现象：在WSL2中git push失败，但Windows浏览器可正常访问GitHub。

根因：WSL2使用Windows DNS，但/etc/resolv.conf被WSL2自动生成，且可能被防病毒软件劫持。

解决方案：

1. 禁用WSL2自动生成resolv.conf：
   在/etc/wsl.conf中添加：

   [network] generateResolvConf = false

2. 手动配置DNS：

   echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf echo "nameserver 1.1.1.1" | sudo tee -a /etc/resolv.conf

3. 验证DNS：

   nslookup github.com # 应返回IP地址 curl -I https://github.com # 应返回HTTP 200

注意：每次WSL2重启后/etc/resolv.conf会被重写，故必须在wsl.conf中设generateResolvConf = false。

5. 毛坯房进阶：从可运行到可量产的关键加固

5.1 构建可复现的Docker镜像：毛坯房的精装交付

毛坯房调试完成后，需封装为Docker镜像用于CI/CD。关键