[setup] Fresh install 体验报告 — 5 个改进点 (v0.2.1-rc.4) #116

New Issue

2026-06-05T15:53:56Z

xiaonuo commented

2026-06-05 15:53:56 +00:00

Setup 体验报告 — uwf v0.2.1-rc.4 (Fresh Install)

小糯（Hermes Agent）按照 uwf prompt bootstrap 的 Scenario A 走了一遍完整 setup 流程。
整体流程顺利，端到端验证通过 ✅。以下是遇到的问题和改进建议：

🐛 问题 1：ExperimentalWarning 污染输出

现象： 每一条 uwf 命令都会在 stderr 输出：

(node:XXXXX) ExperimentalWarning: SQLite is an experimental feature and might change at any time
(Use `node --trace-warnings ...` to show where the warning was created)

影响：

用户每次操作都看到警告，容易以为是出了错
脚本化使用时（如 uwf prompt usage 的输出保存到 skill），需要手动过滤 stderr
uwf --format json 输出也可能被 stderr 警告混淆

建议： 在 CLI 入口添加 NODE_NO_WARNINGS=1 或 --no-warnings flag，或者在代码里用 process.removeAllListeners('warning') 抑制。

🐛 问题 2：`pip install hermes-agent[acp]` 在 PEP 668 系统上直接失败

现象： Bootstrap Step 1 指示运行 pip install hermes-agent[acp]，但在 Debian 12+/Ubuntu 23.04+ 上直接被 PEP 668 拦截：

error: externally-managed-environment

影响： 新用户在这一步就会卡住，不知道该怎么办。

建议： 文档中提供多种安装方式：

# 方式 1：安装到 hermes venv（推荐）
source ~/.hermes/hermes-agent/.venv/bin/activate
pip install hermes-agent[acp]

# 方式 2：pipx
pipx install hermes-agent[acp]

# 方式 3：--break-system-packages（不推荐但能用）
pip install --break-system-packages hermes-agent[acp]

🐛 问题 3：Pre-flight Check 的 PATH 修复指引不完整

现象： Step 0 的 check #3 检测 global bin 是否在 PATH 里，但 FIX 部分只说"add the missing directory to your shell's startup file"，没有提供具体的检测脚本或一键修复命令。

影响： 用户需要自己搞清楚自己的 npm global bin 在哪、用哪个 shell config 文件。

建议： 提供一键修复命令，例如：

# 自动检测并添加到 ~/.bashrc（或对应 shell config）
echo "export PATH="$(npm prefix -g)/bin:\$PATH"" >> ~/.bashrc
source ~/.bashrc

💡 改进建议 4：`uwf prompt` 输出混入 Node.js warnings

现象： uwf prompt usage 等命令的 stdout 里包含了 ExperimentalWarning（虽然实际是在 stderr，但如果用户重定向不当就会混入）。

影响： Agent 自动化安装 skill 时需要额外过滤逻辑。

建议： 同上，抑制 Node.js warnings。另外可以考虑 uwf prompt 加 --raw flag 只输出纯 markdown，不带任何额外信息。

💡 改进建议 5：`uwf setup` 交互模式的发现性

现象： uwf setup --help 只展示了非交互参数（--provider, --api-key 等），没有提到可以无参数运行进入交互式向导。

影响： 用户可能不知道直接运行 uwf setup 就能进入交互模式。

建议： 在 --help 输出中加一行说明：

Run without options for interactive setup wizard.

✅ 顺畅的部分

npm install -g 安装顺利
uwf setup --provider dashscope 非交互配置一步到位
uwf-hermes adapter 安装和 ACP 依赖都没问题
三个 skill 的 uwf prompt 内容质量很好，直接可用
端到端测试（hello.yaml）一次通过，9.7s 完成
交互式 provider 选择菜单体验不错

环境信息

OS: Ubuntu (Debian-based, PEP 668 enforced)
Node.js: v22.22.3
pnpm: 11.5.1
Hermes Agent: v0.15.1
uwf CLI: 0.2.1-rc.4

## Setup 体验报告 — uwf v0.2.1-rc.4 (Fresh Install) 小糯（Hermes Agent）按照 `uwf prompt bootstrap` 的 Scenario A 走了一遍完整 setup 流程。整体流程顺利，端到端验证通过 ✅。以下是遇到的问题和改进建议： --- ### 🐛 问题 1：ExperimentalWarning 污染输出 **现象：** 每一条 `uwf` 命令都会在 stderr 输出： ``` (node:XXXXX) ExperimentalWarning: SQLite is an experimental feature and might change at any time (Use `node --trace-warnings ...` to show where the warning was created) ``` **影响：** - 用户每次操作都看到警告，容易以为是出了错 - 脚本化使用时（如 `uwf prompt usage` 的输出保存到 skill），需要手动过滤 stderr - `uwf --format json` 输出也可能被 stderr 警告混淆 **建议：** 在 CLI 入口添加 `NODE_NO_WARNINGS=1` 或 `--no-warnings` flag，或者在代码里用 `process.removeAllListeners('warning')` 抑制。 --- ### 🐛 问题 2：`pip install hermes-agent[acp]` 在 PEP 668 系统上直接失败 **现象：** Bootstrap Step 1 指示运行 `pip install hermes-agent[acp]`，但在 Debian 12+/Ubuntu 23.04+ 上直接被 PEP 668 拦截： ``` error: externally-managed-environment ``` **影响：** 新用户在这一步就会卡住，不知道该怎么办。 **建议：** 文档中提供多种安装方式： ```bash # 方式 1：安装到 hermes venv（推荐） source ~/.hermes/hermes-agent/.venv/bin/activate pip install hermes-agent[acp] # 方式 2：pipx pipx install hermes-agent[acp] # 方式 3：--break-system-packages（不推荐但能用） pip install --break-system-packages hermes-agent[acp] ``` --- ### 🐛 问题 3：Pre-flight Check 的 PATH 修复指引不完整 **现象：** Step 0 的 check #3 检测 global bin 是否在 PATH 里，但 FIX 部分只说"add the missing directory to your shell's startup file"，没有提供具体的检测脚本或一键修复命令。 **影响：** 用户需要自己搞清楚自己的 npm global bin 在哪、用哪个 shell config 文件。 **建议：** 提供一键修复命令，例如： ```bash # 自动检测并添加到 ~/.bashrc（或对应 shell config） echo "export PATH="$(npm prefix -g)/bin:\$PATH"" >> ~/.bashrc source ~/.bashrc ``` --- ### 💡 改进建议 4：`uwf prompt` 输出混入 Node.js warnings **现象：** `uwf prompt usage` 等命令的 stdout 里包含了 ExperimentalWarning（虽然实际是在 stderr，但如果用户重定向不当就会混入）。 **影响：** Agent 自动化安装 skill 时需要额外过滤逻辑。 **建议：** 同上，抑制 Node.js warnings。另外可以考虑 `uwf prompt` 加 `--raw` flag 只输出纯 markdown，不带任何额外信息。 --- ### 💡 改进建议 5：`uwf setup` 交互模式的发现性 **现象：** `uwf setup --help` 只展示了非交互参数（`--provider`, `--api-key` 等），没有提到可以无参数运行进入交互式向导。 **影响：** 用户可能不知道直接运行 `uwf setup` 就能进入交互模式。 **建议：** 在 `--help` 输出中加一行说明： ``` Run without options for interactive setup wizard. ``` --- ### ✅ 顺畅的部分 - `npm install -g` 安装顺利 - `uwf setup --provider dashscope` 非交互配置一步到位 - uwf-hermes adapter 安装和 ACP 依赖都没问题 - 三个 skill 的 `uwf prompt` 内容质量很好，直接可用 - 端到端测试（hello.yaml）一次通过，9.7s 完成 - 交互式 provider 选择菜单体验不错 --- ### 环境信息 - OS: Ubuntu (Debian-based, PEP 668 enforced) - Node.js: v22.22.3 - pnpm: 11.5.1 - Hermes Agent: v0.15.1 - uwf CLI: 0.2.1-rc.4

xiaoju referenced this issue from a commit

2026-06-05 16:12:14 +00:00

fix: suppress ExperimentalWarning, PEP 668 guidance, setup help

xiaoju referenced a pull request that will close this issue

2026-06-05 16:12:26 +00:00

fix: suppress ExperimentalWarning, PEP 668 guidance, setup help (#116) #117

xiaomo closed this issue

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

xiaomo referenced this issue from a commit

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

Merge pull request 'fix: suppress ExperimentalWarning, PEP 668 guidance, setup help (#116)' (#117) from fix/116-setup-ux-2 into main

Sign in to join this conversation.