bootstrap: pnpm 未正确安装导致 PATH 级联失败 #112

New Issue

2026-06-05T13:59:46Z

xiaonuo commented

2026-06-05 13:59:46 +00:00

问题描述

小糯在执行 uwf prompt bootstrap 初始化配置时，遇到了由 pnpm 安装问题引发的 PATH 级联失败。

实际经过

1. pnpm 二进制缺失

~/.local/share/pnpm/bin/ 目录存在，但里面没有 pnpm 本身的可执行文件（只有 ocas、pn、pnpx 等其他工具）。导致 pnpm add -g @united-workforce/cli 无法执行。

2. 被迫回退到 npm，安装路径不在 PATH 中

因为 pnpm 不可用，小糯改用 npm install -g 安装。npm 全局包安装到了 ~/.hermes/node/lib/node_modules/，bin 在 ~/.hermes/node/bin/——这个路径不在默认 PATH 中。

3. uwf 命令找不到

装完后 uwf 命令不在 PATH 里，需要手动 export PATH=.../node/bin:$PATH。

4. hermes 命令也找不到

uwf thread exec 执行时报 spawn hermes ENOENT——hermes CLI 的 symlink 在 ~/.local/bin/hermes，虽然 ~/.local/bin 在 PATH 中，但 symlink 指向的 ~/hermes-agent/.venv/bin/hermes 也需要 venv bin 在 PATH 中才能被 uwf-hermes adapter 找到。

根因分析

三个问题（uwf 找不到、hermes 找不到、pnpm 不能用）其实是同一个根因：本机 pnpm 环境没有正确初始化。

如果 pnpm 正常工作：

pnpm add -g uwf → 装到 ~/.local/share/pnpm/bin/ → 已在 PATH 中 ✅
pnpm add -g uwf-hermes → 同理 ✅
hermes symlink ~/.local/bin/hermes → 已在 PATH 中 ✅

这不是 bootstrap prompt 的问题

bootstrap prompt 假定用户已有正常的包管理器环境，这个假设是合理的。问题出在 agent 宿主机的 pnpm 初始化环节。

建议

shazhou-family-onboard skill 或 hermes-harness 的初始化流程中，应增加 pnpm 自检步骤：确认 pnpm 二进制存在且可用
如果 pnpm 不可用，给出明确的修复指引（如 corepack enable pnpm 或 npm install -g pnpm），而不是让 agent 自己摸索回退到 npm
考虑在 onboard 流程中统一验证 ~/.local/bin 和 pnpm bin 目录都在 PATH 中

## 问题描述小糯在执行 `uwf prompt bootstrap` 初始化配置时，遇到了由 pnpm 安装问题引发的 PATH 级联失败。 ## 实际经过 ### 1. pnpm 二进制缺失 `~/.local/share/pnpm/bin/` 目录存在，但里面没有 pnpm 本身的可执行文件（只有 ocas、pn、pnpx 等其他工具）。导致 `pnpm add -g @united-workforce/cli` 无法执行。 ### 2. 被迫回退到 npm，安装路径不在 PATH 中因为 pnpm 不可用，小糯改用 `npm install -g` 安装。npm 全局包安装到了 `~/.hermes/node/lib/node_modules/`，bin 在 `~/.hermes/node/bin/`——这个路径**不在默认 PATH 中**。 ### 3. uwf 命令找不到装完后 `uwf` 命令不在 PATH 里，需要手动 `export PATH=.../node/bin:$PATH`。 ### 4. hermes 命令也找不到 `uwf thread exec` 执行时报 `spawn hermes ENOENT`——hermes CLI 的 symlink 在 `~/.local/bin/hermes`，虽然 `~/.local/bin` 在 PATH 中，但 symlink 指向的 `~/hermes-agent/.venv/bin/hermes` 也需要 venv bin 在 PATH 中才能被 uwf-hermes adapter 找到。 ## 根因分析 **三个问题（uwf 找不到、hermes 找不到、pnpm 不能用）其实是同一个根因：本机 pnpm 环境没有正确初始化。** 如果 pnpm 正常工作： - `pnpm add -g uwf` → 装到 `~/.local/share/pnpm/bin/` → 已在 PATH 中 ✅ - `pnpm add -g uwf-hermes` → 同理 ✅ - hermes symlink `~/.local/bin/hermes` → 已在 PATH 中 ✅ ## 这不是 bootstrap prompt 的问题 bootstrap prompt 假定用户已有正常的包管理器环境，这个假设是合理的。问题出在 **agent 宿主机的 pnpm 初始化环节**。 ## 建议 1. **shazhou-family-onboard skill 或 hermes-harness 的初始化流程中**，应增加 pnpm 自检步骤：确认 `pnpm` 二进制存在且可用 2. 如果 pnpm 不可用，给出明确的修复指引（如 `corepack enable pnpm` 或 `npm install -g pnpm`），而不是让 agent 自己摸索回退到 npm 3. 考虑在 onboard 流程中统一验证 `~/.local/bin` 和 pnpm bin 目录都在 PATH 中

xiaoju referenced this issue from a commit

2026-06-05 14:11:31 +00:00

fix: bootstrap adds Step 0 environment pre-flight check

xiaoju referenced a pull request that will close this issue

2026-06-05 14:11:41 +00:00

fix: bootstrap adds Step 0 environment pre-flight check #113

xiaoju referenced this issue from a commit

2026-06-05 14:11:52 +00:00

chore: add changeset for #112

xiaomo closed this issue

2026-06-05 14:34:13 +00:00

Sign in to join this conversation.