安装与环境问题¶

找不到 UCAgent 或 Python¶

现象：make 报 ucagent.py 不存在、Python 不可执行，或导入 examples.workflow_builder 失败。

影响：工作流无法启动，属于运行前阻断问题。

确认方法：

python setup.py --show
python setup.py --check
test -f "$UCAGENT_HOME/ucagent.py"
test -x "$UCAGENT_VENV/bin/python"

处理步骤：重新运行根目录 python setup.py，配置实际的 UCAgent 源码和虚拟环境路径。命令行临时覆盖可以用于验证，但长期值应保存到本地配置。不要把某台机器的绝对路径写进公共 config 或 GuideDoc。

预防：迁移机器后先执行 make configure-check，再启动业务工作区。

`ucagent_env` 与 setup.py 是什么关系¶

ucagent_env 通常是用户 shell 中已有的函数，用于激活 PATH、PYTHON 和 PYTHONPATH。Workflow Builder 根 setup.py 则把 Makefile 需要的本机默认路径保存到 .workflow_builder/local.mk。二者可以并存；setup.py 不写 ~/.bashrc，也不会让环境变量永久进入父 shell。

生成工作流根目录下还会有另一个 workflow/setup.py，它配置的是业务工作流运行环境。执行前必须通过 pwd 区分两个程序。

代理启用后仍连接失败¶

可能原因：代理地址错误、凭据缺失、服务端断流、继承了不兼容的 ALL_PROXY、模型请求过大或代理本身不稳定。

确认方法：检查当前进程实际继承的 HTTP_PROXY、HTTPS_PROXY 和 ALL_PROXY；用相同环境进行短请求；比较不经过代理时的结果。不要仅因为换了网络后仍失败，就断言与请求大小或服务端无关。

本地配置拒绝保存 URL 内嵌凭据。需要认证时，在当前 shell 或秘密管理系统中设置，不要写入版本库和文档截图。

端口或工具依赖缺失¶

MCP 和控制台端口必须为 1 到 65535。tmux、LibreOffice、Verilator 等系统工具要用各自版本命令检查。业务工具缺失应由生成工作流的 requirements.txt 和环境文档报告，不能由 Workflow Builder 安装未知系统包。

虚拟环境与系统 Python 混用¶

现象：同一回归通过根 make regression 可以运行，直接 python3 却因 typing.NotRequired、langgraph 或缺包失败。

确认方法：比较 which python3、$UCAGENT_VENV/bin/python --version 和两者 sys.path。根回归会传 venv Python，手工进入 regression 后可能退回系统解释器。

处理：显式执行 make -C regression PYTHON="$UCAGENT_VENV/bin/python" <target>。不要因为解释器依赖错误修改业务 Checker。

本地配置没有生效¶

使用 make configure-show 检查保存值，再以 make -n WS=... run 观察展开。命令行变量优先于本地配置；本地文件被手工破坏时重新运行 python setup.py，不要直接修 Make 语法。

代理凭据与业务依赖¶

setup 拒绝保存带账号密码的代理 URL。秘密通过运行时环境注入，并确保 tmux继承；共享日志前清除 Token 和认证 URL。“命令存在”只证明安装，不证明版本和功能满足要求，业务 setup/check 还应验证版本和关键能力。