Setup 体验报告：Bootstrap 流程中的 5 个 UX 问题 #118

New Issue

2026-06-05T16:36:13Z

xiaonuo commented

2026-06-05 16:36:13 +00:00

背景

在 SORA 设备上从零开始执行 uwf prompt bootstrap 的完整 setup 流程，遇到了以下体验问题。

问题 1：`uwf-hermes` PATH 检测不够智能，警告信息误导用户

现象：运行 uwf setup --agent uwf-hermes 后输出：

⚠ uwf-hermes not found in PATH. Install it: pnpm add -g @united-workforce/agent-hermes

但实际上 uwf-hermes 已经装好了，在 /home/xiaonuo/.hermes/node/bin/uwf-hermes，只是这个目录不在当前 shell 的 $PATH 中。

问题：

uwf setup 只检查当前 $PATH，没有检查常见的 npm/pnpm 全局 bin 路径
警告信息说"没装"，但实际是"装了但 PATH 不对"，误导用户重复安装

建议：

检查常见路径：~/.hermes/node/bin、~/.local/share/pnpm、/usr/local/bin、npm prefix 等
警告信息改为：uwf-hermes not found in PATH. Common locations: ~/.hermes/node/bin, ~/.local/share/pnpm. Add the correct directory to your PATH.

问题 2：Bootstrap 文档假设 pnpm 可用

文档中所有安装命令都写的是 pnpm add -g ...，但很多用户（包括本机）没有安装 pnpm。实际用 npm install -g 也能正常工作。

建议：文档应该明确说 pnpm（推荐）或 npm 都可以，并给出两种命令示例。

问题 3：Bootstrap 没有提到安装后 PATH 验证

Step 0 检查了 Node.js、包管理器、bin 目录等，但 Step 1 装完 uwf 后没有验证步骤。本机装完后 uwf 命令不在 PATH 中，需要用完整路径 /home/xiaonuo/.hermes/node/bin/uwf 才能运行。

建议：Step 1 安装完成后加一个 uwf --version 验证步骤，如果失败就提示用户修复 PATH。

问题 4：Adapter 安装时机不明确

Bootstrap 文档在 Step 1 先让用户装 CLI，再装 adapter，但 Step 2 的 --agent 参数需要 adapter 已存在。文档没有明确说"先装 adapter 再跑 setup"。

建议：明确标注 adapter 必须在 uwf setup --agent 之前安装。

问题 5：`--base-url` 对 preset provider 的行为未说明

uwf setup 对 preset providers（如 dashscope）会自动填充 base URL，但 bootstrap 文档没有明确说明哪些 provider 是 preset、哪些需要手动指定 --base-url。

建议：在文档中列出所有 preset providers 及其对应的默认 base URL。

## 背景在 SORA 设备上从零开始执行 `uwf prompt bootstrap` 的完整 setup 流程，遇到了以下体验问题。 ## 问题 1：`uwf-hermes` PATH 检测不够智能，警告信息误导用户 **现象**：运行 `uwf setup --agent uwf-hermes` 后输出： ``` ⚠ uwf-hermes not found in PATH. Install it: pnpm add -g @united-workforce/agent-hermes ``` 但实际上 `uwf-hermes` 已经装好了，在 `/home/xiaonuo/.hermes/node/bin/uwf-hermes`，只是这个目录不在当前 shell 的 `$PATH` 中。 **问题**： 1. `uwf setup` 只检查当前 `$PATH`，没有检查常见的 npm/pnpm 全局 bin 路径 2. 警告信息说"没装"，但实际是"装了但 PATH 不对"，误导用户重复安装 **建议**： 1. 检查常见路径：`~/.hermes/node/bin`、`~/.local/share/pnpm`、`/usr/local/bin`、npm prefix 等 2. 警告信息改为：`uwf-hermes not found in PATH. Common locations: ~/.hermes/node/bin, ~/.local/share/pnpm. Add the correct directory to your PATH.` ## 问题 2：Bootstrap 文档假设 pnpm 可用文档中所有安装命令都写的是 `pnpm add -g ...`，但很多用户（包括本机）没有安装 pnpm。实际用 `npm install -g` 也能正常工作。 **建议**：文档应该明确说 `pnpm`（推荐）或 `npm` 都可以，并给出两种命令示例。 ## 问题 3：Bootstrap 没有提到安装后 PATH 验证 Step 0 检查了 Node.js、包管理器、bin 目录等，但 Step 1 装完 uwf 后没有验证步骤。本机装完后 `uwf` 命令不在 PATH 中，需要用完整路径 `/home/xiaonuo/.hermes/node/bin/uwf` 才能运行。 **建议**：Step 1 安装完成后加一个 `uwf --version` 验证步骤，如果失败就提示用户修复 PATH。 ## 问题 4：Adapter 安装时机不明确 Bootstrap 文档在 Step 1 先让用户装 CLI，再装 adapter，但 Step 2 的 `--agent` 参数需要 adapter 已存在。文档没有明确说"先装 adapter 再跑 setup"。 **建议**：明确标注 adapter 必须在 `uwf setup --agent` 之前安装。 ## 问题 5：`--base-url` 对 preset provider 的行为未说明 `uwf setup` 对 preset providers（如 dashscope）会自动填充 base URL，但 bootstrap 文档没有明确说明哪些 provider 是 preset、哪些需要手动指定 `--base-url`。 **建议**：在文档中列出所有 preset providers 及其对应的默认 base URL。

xiaoju referenced this issue from a commit

2026-06-05 16:41:41 +00:00

fix: bootstrap docs — pnpm/npm parity, adapter order, preset table (#118)

xiaoju referenced a pull request that will close this issue

2026-06-05 16:41:53 +00:00

fix: bootstrap docs — pnpm/npm parity, adapter order, preset table (#118) #119

xiaoju referenced this issue from a commit

2026-06-05 16:45:36 +00:00

fix: bootstrap PATH fix guidance — find binary location + update shell config (#118 #1)

xiaomo closed this issue

2026-06-05 16:48:48 +00:00

xiaomo referenced this issue from a commit