企业官网建设流程全解析

Hermes Agent 启动脚本 3 处改造：60 秒跑通依赖检查

【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent

执行./setup-hermes.sh卡在第 3 步，打出uv: command not found后再无输出，这是 Hermes Agent 启动脚本依赖检查的典型翻车现场：脚本停了，你却不知道缺的是哪个依赖。先花 30 秒定位，再改 3 处，就能跑通。

🔍 先定位：三步自检清单

改代码之前，先判断你的问题属于哪一层。按顺序跑下面 3 条命令，看哪一步先失败：

1. 工具缺没缺：uv、git、rg在不在系统里
2. Python 版本适不适配：有没有可用的 3.10 以上版本
3. 配置填没填：.env里的必需变量是否为空值

把这三行放进启动脚本前 10 行，哪一层死掉都能先拿到结论，不用再翻整屏日志。

type -p uv git rg uv python list 2>/dev/null | head -3 grep -cE '^[A-Z_]+=.+' .env 2>/dev/null || echo "0 # .env 缺失或无有效值"

跑完你会看到三段输出：第 1 步出现not found是缺工具，第 2 步为空是 Python 版本不对，第 3 步为 0 是配置问题。三类各对应下一节的 1 处改造。

🔧 三处关键改造

改造 1：用hash重写依赖探测

原脚本用command -v探测依赖并把输出丢进 /dev/null，失败时你连缺了哪个都看不到。

改用hash做探测、type -p打印真实路径，缺什么直接暴露：

probe() { local bin=$1 if hash "$bin" 2>/dev/null; then printf '[OK] %-4s -> %s\n' "$bin" "$(type -p "$bin")" else printf '[MISS] %-4s 缺失，待安装\n' "$bin" fi } for b in uv git rg; do probe "$b"; done

跑完终端会打印 3 行：装好的显示[OK] uv -> /usr/local/bin/uv，缺失的显示[MISS]，你要装什么一目了然。

改造 2：安装失败用一个退出码收口

安装失败时原逻辑继续往下走，真正的报错拖到后面步骤才冒出来，你已经分不清是哪个安装步骤坏的。

兜底规则：失败就打印错误并立刻以固定退出码 127 退出，环境没确认前不重试：

install_dep() { local pkg=$1 if ! pip install --user "$pkg" >/dev/null 2>&1; then echo "ERROR: $pkg 安装失败，请检查网络或 pip 源配置" >&2 exit 127 fi export PATH="$HOME/.local/bin:$PATH" hash "$pkg" >/dev/null 2>&1 || echo "WARN: $pkg 不在 PATH，请重开终端" echo "[OK] $pkg 安装完成" }

这步最容易翻车。安装失败时终端只出现一行 ERROR，脚本停在退出码 127；成功时只留一行[OK] uv 安装完成，不会被几百行 pip 日志刷屏。

改造 3：.env逐键校验

.env文件存在但值全空，报错要等到 Agent 第一次调 API 才出现。

改法：不只看文件是否存在，逐个检查必需变量有没有非空值：

[ -f .env ] || { echo "ERROR: 缺少 .env，请先从 .env.example 复制一份"; exit 1; } for k in ANTHROPIC_API_KEY OPENAI_API_KEY; do grep -qE "^[[:space:]]*${k}=.+" .env \ || echo "WARN: ${k} 为空，启动前请填入" done echo "[OK] .env 校验完成"

跑完你看到的是：变量齐全时输出一行[OK] .env 校验完成；有空值时，每个空变量各打一行 WARN，填哪一行直接看输出。

避坑速查表

新环境报错时先对这张表，表里没覆盖的再回头看自检清单：

✅ 跑一遍验证

最后别靠猜，整条流程跑一遍，用脚本自己说话（没装 shellcheck 就跳过第 2 行）：

bash -n setup-hermes.sh shellcheck -S warning setup-hermes.sh ./setup-hermes.sh

3 条都退出码为 0，且最后停在 Hermes Agent 桌面端的欢迎界面，说明改造生效：

• 自检清单负责秒级判断问题在哪一层
• 三处改造分别堵住缺工具、装失败、配置空三个出口
• 速查表留给下次新环境再出状况时对照

验证通过后，用这一条命令启动：

git clone https://gitcode.com/GitHub_Trending/he/hermes-agent && cd hermes-agent && ./setup-hermes.sh

【免费下载链接】hermes-agentThe agent that grows with you项目地址: https://gitcode.com/GitHub_Trending/he/hermes-agent