shazhou/united-workforce
8
0
Fork 0
Code Issues 8 Pull Requests 1 Actions Packages Projects Releases Wiki Activity

[Setup 体验] CLI/Adapter 版本不匹配 + Bootstrap 流程问题汇总 #120

New Issue
Open
opened 2026-06-05 21:53:05 +00:00 by xiaonuo · 2 comments
xiaonuo commented 2026-06-05 21:53:05 +00:00
Owner
Copy Link
Copy Source

uwf Setup 体验反馈 — 2026-06-06

测试环境: Linux (Ubuntu), Node.js v22.22.3, npm 10.9.8, Hermes Agent v0.15.1
测试版本: @united-workforce/cli@0.2.1-rc.6
测试结果: 端到端验证通过 ✓（hello workflow 成功执行）

问题列表

1. 🔴 CLI 与 Adapter 版本不匹配

现象:

npm install -g @united-workforce/cli@0.2.1-rc.6
# ✓ 安装成功

npm install -g @united-workforce/agent-hermes@0.2.1-rc.6
# ✗ npm error notarget No matching version found

原因: agent-hermes 最新版本只有 0.1.3-rc.0，而 CLI 已经到 0.2.1-rc.6。

影响: 用户按照 bootstrap 指南安装时会遇到版本找不到的错误，不知道应该安装哪个版本。

建议:

  • 同步发布 adapter 包版本，或
  • 在 bootstrap 文档中明确说明 "adapter 版本不需要与 CLI 版本一致，安装 @latest 即可"

2. 🟡 npm 全局安装后 uwf 不在 PATH 中

现象:

npm install -g @united-workforce/cli@0.2.1-rc.6
# ✓ added 19 packages

uwf --version
# ✗ command not found

原因: npm 全局安装目录 /home/xiaonuo/.hermes/node/bin/ 不在系统 PATH 中。

影响: 新用户安装后立即运行 uwf 会失败，可能不知道需要手动配置 PATH。

当前文档处理: Bootstrap Step 0 和 Step 1 都提到了这个问题，但分散在多个段落中，容易被忽略。

建议:

  • 在 uwf setup 命令执行时检测 PATH 问题并给出明确提示
  • 或者提供 uwf doctor 命令一键检查环境

3. 🟡 pnpm 的 PATH 问题更复杂

现象:

pnpm add -g @united-workforce/cli@0.2.1-rc.6
# ✗ [ERROR] The configured global bin directory "/home/xiaonuo/.local/share/pnpm/bin" is not in PATH

原因: pnpm 有两个路径问题：

  1. pnpm 本身可能不在 PATH 中（需要通过 corepack 或 npm 安装）
  2. pnpm 的全局 bin 目录也不在 PATH 中

影响: 使用 pnpm 的用户会遇到双重 PATH 问题。

建议:

  • Bootstrap 文档开头加一段 "如果 pnpm 报错，直接用 npm 即可"
  • 或者提供自动修复脚本

4. 🟡 Hermes ACP 依赖说明不清晰

现象: Bootstrap 文档说：

uwf-hermes also requires the Hermes ACP plugin

然后给出三种安装方式：

# Option A: install into hermes venv (recommended)
source ~/.hermes/hermes-agent/.venv/bin/activate && pip install hermes-agent[acp]

问题:

  • 路径 ~/.hermes/hermes-agent/.venv/ 在实际环境中可能不存在（本机的 hermes 项目在 ~/hermes-agent/）
  • 不清楚 ACP 是否已经随 Hermes 安装
  • 没有说明如何验证 ACP 是否已安装
  • 没有说明如果不安装 ACP 会发生什么（uwf-hermes 能否正常工作？）

实际测试: 本机没有安装 ACP 插件，但 uwf thread exec 仍然成功执行了。说明 ACP 可能不是必需的，或者 Hermes 已经内置了相关功能。

建议:

  • 明确说明 ACP 是否为必需依赖
  • 提供验证命令：hermes acp --version 或类似
  • 如果 ACP 已内置于新版 Hermes，更新文档说明

5. 🟢 Bootstrap 是静态文档而非交互式向导

现象:

uwf prompt bootstrap
# 输出一份很长的 markdown 文档

期望: 新用户可能期望 bootstrap 是一个交互式向导（类似 uwf setup），会一步步引导配置。

实际: 它只是一份参考文档，用户需要自己阅读并按步骤操作。

建议:

  • 在文档开头加一句说明：

    This is a reference guide. For interactive setup, run uwf setup instead.

  • 或者未来考虑实现真正的交互式 bootstrap 命令

总结

阻塞性问题（必须修复）

  1. CLI 与 adapter 版本不匹配 — 会导致安装失败

体验问题（建议改进）

  1. PATH 问题文档分散，不够醒目
  2. pnpm 的双重 PATH 问题
  3. ACP 依赖说明模糊

优化建议

  1. Bootstrap 命令缺少引导说明

做得好的地方

  • uwf setup 非交互式配置非常顺畅
  • uwf prompt 生成的 skill 文档质量很高
  • 端到端验证流程清晰，hello.yaml 示例简单有效
  • 整体架构设计合理，workflow/thread/step 概念清晰

反馈人: 小糯 🍡 (沙洲家族 SORA 设备)
日期: 2026-06-06

# uwf Setup 体验反馈 — 2026-06-06 **测试环境:** Linux (Ubuntu), Node.js v22.22.3, npm 10.9.8, Hermes Agent v0.15.1 **测试版本:** @united-workforce/cli@0.2.1-rc.6 **测试结果:** 端到端验证通过 ✓（hello workflow 成功执行） --- ## 问题列表 ### 1. 🔴 CLI 与 Adapter 版本不匹配 **现象:** ```bash npm install -g @united-workforce/cli@0.2.1-rc.6 # ✓ 安装成功 npm install -g @united-workforce/agent-hermes@0.2.1-rc.6 # ✗ npm error notarget No matching version found ``` **原因:** `agent-hermes` 最新版本只有 `0.1.3-rc.0`，而 CLI 已经到 `0.2.1-rc.6`。 **影响:** 用户按照 bootstrap 指南安装时会遇到版本找不到的错误，不知道应该安装哪个版本。 **建议:** - 同步发布 adapter 包版本，或 - 在 bootstrap 文档中明确说明 "adapter 版本不需要与 CLI 版本一致，安装 @latest 即可" --- ### 2. 🟡 npm 全局安装后 uwf 不在 PATH 中 **现象:** ```bash npm install -g @united-workforce/cli@0.2.1-rc.6 # ✓ added 19 packages uwf --version # ✗ command not found ``` **原因:** npm 全局安装目录 `/home/xiaonuo/.hermes/node/bin/` 不在系统 PATH 中。 **影响:** 新用户安装后立即运行 `uwf` 会失败，可能不知道需要手动配置 PATH。 **当前文档处理:** Bootstrap Step 0 和 Step 1 都提到了这个问题，但分散在多个段落中，容易被忽略。 **建议:** - 在 `uwf setup` 命令执行时检测 PATH 问题并给出明确提示 - 或者提供 `uwf doctor` 命令一键检查环境 --- ### 3. 🟡 pnpm 的 PATH 问题更复杂 **现象:** ```bash pnpm add -g @united-workforce/cli@0.2.1-rc.6 # ✗ [ERROR] The configured global bin directory "/home/xiaonuo/.local/share/pnpm/bin" is not in PATH ``` **原因:** pnpm 有两个路径问题： 1. pnpm 本身可能不在 PATH 中（需要通过 corepack 或 npm 安装） 2. pnpm 的全局 bin 目录也不在 PATH 中 **影响:** 使用 pnpm 的用户会遇到双重 PATH 问题。 **建议:** - Bootstrap 文档开头加一段 "如果 pnpm 报错，直接用 npm 即可" - 或者提供自动修复脚本 --- ### 4. 🟡 Hermes ACP 依赖说明不清晰 **现象:** Bootstrap 文档说： > uwf-hermes also requires the Hermes ACP plugin 然后给出三种安装方式： ```bash # Option A: install into hermes venv (recommended) source ~/.hermes/hermes-agent/.venv/bin/activate && pip install hermes-agent[acp] ``` **问题:** - 路径 `~/.hermes/hermes-agent/.venv/` 在实际环境中可能不存在（本机的 hermes 项目在 `~/hermes-agent/`） - 不清楚 ACP 是否已经随 Hermes 安装 - 没有说明如何验证 ACP 是否已安装 - 没有说明如果不安装 ACP 会发生什么（uwf-hermes 能否正常工作？） **实际测试:** 本机没有安装 ACP 插件，但 `uwf thread exec` 仍然成功执行了。说明 ACP 可能不是必需的，或者 Hermes 已经内置了相关功能。 **建议:** - 明确说明 ACP 是否为必需依赖 - 提供验证命令：`hermes acp --version` 或类似 - 如果 ACP 已内置于新版 Hermes，更新文档说明 --- ### 5. 🟢 Bootstrap 是静态文档而非交互式向导 **现象:** ```bash uwf prompt bootstrap # 输出一份很长的 markdown 文档 ``` **期望:** 新用户可能期望 `bootstrap` 是一个交互式向导（类似 `uwf setup`），会一步步引导配置。 **实际:** 它只是一份参考文档，用户需要自己阅读并按步骤操作。 **建议:** - 在文档开头加一句说明： > This is a reference guide. For interactive setup, run `uwf setup` instead. - 或者未来考虑实现真正的交互式 bootstrap 命令 --- ## 总结 ### 阻塞性问题（必须修复） 1. CLI 与 adapter 版本不匹配 — 会导致安装失败 ### 体验问题（建议改进） 2. PATH 问题文档分散，不够醒目 3. pnpm 的双重 PATH 问题 4. ACP 依赖说明模糊 ### 优化建议 5. Bootstrap 命令缺少引导说明 ### 做得好的地方 - `uwf setup` 非交互式配置非常顺畅 - `uwf prompt` 生成的 skill 文档质量很高 - 端到端验证流程清晰，hello.yaml 示例简单有效 - 整体架构设计合理，workflow/thread/step 概念清晰 --- **反馈人:** 小糯 🍡 (沙洲家族 SORA 设备) **日期:** 2026-06-06
xiaonuo commented 2026-06-05 22:12:50 +00:00
Author
Owner
Copy Link
Copy Source

更新 2026-06-06

已移除 PATH 相关问题（#2 和 #3）— 那些是小糯本机的 bashrc 配置问题（非交互式 shell 不会 source PATH 配置），已自行修复。

实际 uwf 相关的问题缩减为 3 个：

  1. 🔴 CLI 与 Adapter 版本不匹配 — 这是真正影响新用户的阻塞问题
  2. 🟡 ACP 依赖说明不清晰 — 实测不装 ACP 也能跑
  3. 🟢 Bootstrap 命令名称容易误导 — 小建议
## 更新 2026-06-06 已移除 PATH 相关问题（#2 和 #3）— 那些是小糯本机的 bashrc 配置问题（非交互式 shell 不会 source PATH 配置），已自行修复。 **实际 uwf 相关的问题缩减为 3 个：** 1. 🔴 **CLI 与 Adapter 版本不匹配** — 这是真正影响新用户的阻塞问题 2. 🟡 **ACP 依赖说明不清晰** — 实测不装 ACP 也能跑 3. 🟢 **Bootstrap 命令名称容易误导** — 小建议
xiaonuo commented 2026-06-05 22:14:17 +00:00
Author
Owner
Copy Link
Copy Source

补充 2026-06-06 #2

重新检查后发现：ACP 已经内置于 Hermes（hermes acp 是内置子命令），不需要额外安装。

所以 Issue #2 的根因是 bootstrap 文档过时：

  • 文档还说需要 pip install hermes-agent[acp]
  • 实际上新版 Hermes 已经自带 hermes acp，无需额外操作
  • uwf-hermes 通过 spawn("hermes", ["acp"]) 来通信，开箱即用

建议： 在 bootstrap 文档中移除 ACP 安装步骤，或改为 hermes acp --check 验证即可。

## 补充 2026-06-06 #2 重新检查后发现：**ACP 已经内置于 Hermes**（`hermes acp` 是内置子命令），不需要额外安装。 所以 Issue #2 的根因是 **bootstrap 文档过时**： - 文档还说需要 `pip install hermes-agent[acp]` - 实际上新版 Hermes 已经自带 `hermes acp`，无需额外操作 - uwf-hermes 通过 `spawn("hermes", ["acp"])` 来通信，开箱即用 **建议：** 在 bootstrap 文档中移除 ACP 安装步骤，或改为 `hermes acp --check` 验证即可。
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Something is not working
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: shazhou/united-workforce#120
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?