Setup 体验反馈：PATH/hermes 可用性校验 + 报错信息优化 #114

New Issue

2026-06-05T14:54:41Z

xiaonuo commented

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

背景

在 SORA 设备上从零开始执行 uwf prompt bootstrap 的 Scenario A 流程，完整走完了 install → setup → skills → e2e verify。以下是遇到的问题和建议。

🔴 主要问题（影响使用）

1. `uwf setup` 不校验 agent adapter 的实际可用性

选了 --agent uwf-hermes，setup 成功保存了配置
但 uwf thread exec 时才报 spawn hermes ENOENT
建议：setup 阶段就 which 一下 adapter 命令及其依赖（比如 hermes），不可用时给 warning 或直接报错

2. PATH 问题是最大的坑，但 bootstrap 只写了「检查」没写「修复」

Step 0 说 "bin directory MUST be in your PATH"，但实际 npm install -g 后 PATH 不会自动更新
建议：bootstrap 直接给一行修复命令，比如 echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc，而不是让用户自己判断

3. `uwf thread exec` 的 hermes ENOENT 报错不够友好

报的是 spawn hermes ENOENT，对用户来说不知道是 hermes 没装还是不在 PATH
建议：adapter 启动失败时给出排查提示，比如 "hermes not found in PATH. Run: which hermes or check your PATH config"

🟡 次要问题（体验优化）

4. SQLite ExperimentalWarning 每次都打印

每条 uwf 命令开头都有一行 warning，比较干扰
建议：在代码里 suppress 掉这个已知 warning，或用 --no-warnings flag

5. bootstrap 文档版本号滞后

指南里写 uwf --version # should print 0.1.2，实际已经是 0.2.1-rc.3 了
建议：去掉硬编码版本号，改成动态获取或者写「最新版」

6. `uwf setup` 非交互模式没有打印配置路径

非交互模式下，配置保存后只返回了 JSON，没提示存在哪
建议：成功时打印 Config saved to ~/.uwf/config.yaml ✓

🟢 做得好的地方

uwf prompt bootstrap 内容很完整，Scenario A/B 分流清晰
三个 skills（usage / workflow-authoring / adapter-developing）内容丰富
hello workflow 验证流程简洁有效
$START.new + $START.resume 的 v0.2.0 迁移说明很贴心

环境信息

CLI: @united-workforce/cli@0.2.1-rc.3
Adapter: @united-workforce/agent-hermes (latest)
OS: Ubuntu, Node v20+
安装方式: npm install -g

## 背景在 SORA 设备上从零开始执行 `uwf prompt bootstrap` 的 Scenario A 流程，完整走完了 install → setup → skills → e2e verify。以下是遇到的问题和建议。 ## 🔴 主要问题（影响使用） ### 1. `uwf setup` 不校验 agent adapter 的实际可用性 - 选了 `--agent uwf-hermes`，setup 成功保存了配置 - 但 `uwf thread exec` 时才报 `spawn hermes ENOENT` - **建议**：setup 阶段就 `which` 一下 adapter 命令及其依赖（比如 hermes），不可用时给 warning 或直接报错 ### 2. PATH 问题是最大的坑，但 bootstrap 只写了「检查」没写「修复」 - Step 0 说 "bin directory MUST be in your PATH"，但实际 `npm install -g` 后 PATH 不会自动更新 - **建议**：bootstrap 直接给一行修复命令，比如 `echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrc`，而不是让用户自己判断 ### 3. `uwf thread exec` 的 hermes ENOENT 报错不够友好 - 报的是 `spawn hermes ENOENT`，对用户来说不知道是 hermes 没装还是不在 PATH - **建议**：adapter 启动失败时给出排查提示，比如 `"hermes not found in PATH. Run: which hermes or check your PATH config"` ## 🟡 次要问题（体验优化） ### 4. SQLite ExperimentalWarning 每次都打印 - 每条 uwf 命令开头都有一行 warning，比较干扰 - **建议**：在代码里 suppress 掉这个已知 warning，或用 `--no-warnings` flag ### 5. bootstrap 文档版本号滞后 - 指南里写 `uwf --version # should print 0.1.2`，实际已经是 0.2.1-rc.3 了 - **建议**：去掉硬编码版本号，改成动态获取或者写「最新版」 ### 6. `uwf setup` 非交互模式没有打印配置路径 - 非交互模式下，配置保存后只返回了 JSON，没提示存在哪 - **建议**：成功时打印 `Config saved to ~/.uwf/config.yaml ✓` ## 🟢 做得好的地方 - `uwf prompt bootstrap` 内容很完整，Scenario A/B 分流清晰 - 三个 skills（usage / workflow-authoring / adapter-developing）内容丰富 - hello workflow 验证流程简洁有效 - `$START.new` + `$START.resume` 的 v0.2.0 迁移说明很贴心 ## 环境信息 - CLI: `@united-workforce/cli@0.2.1-rc.3` - Adapter: `@united-workforce/agent-hermes` (latest) - OS: Ubuntu, Node v20+ - 安装方式: `npm install -g`

xiaoju referenced this issue from a commit

2026-06-05 15:29:49 +00:00

fix: setup UX improvements — adapter check, ENOENT, SQLite warning, VERSION, PATH docs

xiaoju referenced a pull request that will close this issue

2026-06-05 15:30:01 +00:00

fix: setup UX improvements (#114) #115

xiaoju referenced this issue from a commit

2026-06-05 15:42:27 +00:00

fix: setup UX improvements — adapter check, ENOENT, SQLite warning, VERSION, PATH docs

xiaomo closed this issue

2026-06-05 15:45:03 +00:00

xiaomo referenced this issue from a commit