From 6aee2ed5efcd4f4e3dcf3edfc3f302f0ee6c8bf0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= Date: Fri, 5 Jun 2026 16:41:35 +0000 Subject: [PATCH 1/2] =?UTF-8?q?fix:=20bootstrap=20docs=20=E2=80=94=20pnpm/?= =?UTF-8?q?npm=20parity,=20adapter=20order,=20preset=20table=20(#118)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Show pnpm and npm install commands side-by-side - Clarify adapter must be installed before uwf setup --agent - Add version verification steps with PATH troubleshooting - --agent takes adapter command name (uwf-hermes), not npm package - Preset providers shown as table with default base URLs - Non-preset providers must specify --base-url manually Fixes #118 (#2, #3, #4, #5) --- .changeset/bootstrap-ux-3.md | 13 +++++ packages/cli/src/commands/prompt.ts | 82 +++++++++++++++++++++++------ 2 files changed, 80 insertions(+), 15 deletions(-) create mode 100644 .changeset/bootstrap-ux-3.md diff --git a/.changeset/bootstrap-ux-3.md b/.changeset/bootstrap-ux-3.md new file mode 100644 index 0000000..cf11d3b --- /dev/null +++ b/.changeset/bootstrap-ux-3.md @@ -0,0 +1,13 @@ +--- +"@united-workforce/cli": patch +--- + +fix: improve bootstrap docs — pnpm/npm parity, adapter install order, preset provider table (#118) + +- Step 1: show pnpm and npm side-by-side (not just pnpm with a comment) +- Step 1: add "adapter must be installed before `uwf setup --agent`" note +- Step 1: add `uwf --version` and adapter version verification with PATH troubleshooting +- Step 2: `--agent` takes adapter command name (e.g. `uwf-hermes`), not npm package +- Step 2: preset providers listed as a table with names and default base URLs +- Step 2: non-preset providers must specify `--base-url` manually +- Upgrade scenario: also show npm alternatives diff --git a/packages/cli/src/commands/prompt.ts b/packages/cli/src/commands/prompt.ts index 3ebe3b2..d427e75 100644 --- a/packages/cli/src/commands/prompt.ts +++ b/packages/cli/src/commands/prompt.ts @@ -90,18 +90,39 @@ which hermes ### Step 1 — Install CLI and agent adapter +Install the CLI using **either** pnpm or npm: + +\`\`\`bash +# Using pnpm (recommended) +pnpm add -g @united-workforce/cli + +# Using npm +npm install -g @united-workforce/cli +\`\`\` + +Verify the CLI is available: + \`\`\`bash -pnpm add -g @united-workforce/cli # or: npm install -g @united-workforce/cli uwf --version # should print ${CLI_VERSION} \`\`\` -Install an agent adapter (at least one is required): +If \`uwf\` is not found, your global bin directory is not in PATH — go back to Step 0 check #3. -| Adapter | Install | When to use | -|---------|---------|-------------| -| uwf-hermes | \`pnpm add -g @united-workforce/agent-hermes\` | When your agent framework is Hermes Agent | -| uwf-claude-code | \`pnpm add -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly | -| uwf-builtin | \`pnpm add -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) | +Next, install an agent adapter (**must be installed before running \`uwf setup --agent\`**): + +| Adapter | Install (pnpm / npm) | When to use | +|---------|----------------------|-------------| +| uwf-hermes | \`pnpm add -g @united-workforce/agent-hermes\` / \`npm i -g @united-workforce/agent-hermes\` | When your agent framework is Hermes Agent | +| uwf-claude-code | \`pnpm add -g @united-workforce/agent-claude-code\` / \`npm i -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly | +| uwf-builtin | \`pnpm add -g @united-workforce/agent-builtin\` / \`npm i -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) | + +Verify the adapter is installed: + +\`\`\`bash +uwf-hermes --version # (or uwf-claude-code / uwf-builtin) +\`\`\` + +If the command is not found, check your global bin PATH (Step 0 check #3). **uwf-hermes** also requires the Hermes ACP plugin: \`\`\`bash @@ -115,18 +136,35 @@ pipx install 'hermes-agent[acp]' pip install -e '.[acp]' \`\`\` -Verify the adapter is installed: \`uwf-hermes --version\` (or whichever you chose). - ### Step 2 — Configure provider and model uwf needs an LLM provider to run agents. **Ask the user** for their provider, API key, and model, then run: \`\`\`bash -uwf setup --provider --base-url --api-key --model [--agent ] +uwf setup --provider --api-key --model --agent \`\`\` -Preset providers (base-url is auto-filled when using a preset name): -openai, xai, openrouter, venice, dashscope, deepseek, siliconflow, volcengine, kimi, glm, stepfun, minimax, ollama +**Note:** \`--agent\` takes the adapter **command name** (e.g. \`uwf-hermes\`), not the npm package name. + +**Preset providers** — when using a preset name, \`--base-url\` is auto-filled and can be omitted: + +| Provider | Name | Default base URL | +|----------|------|-----------------| +| OpenAI | \`openai\` | https://api.openai.com/v1 | +| xAI | \`xai\` | https://api.x.ai/v1 | +| OpenRouter | \`openrouter\` | https://openrouter.ai/api/v1 | +| Venice | \`venice\` | https://api.venice.ai/api/v1 | +| Dashscope | \`dashscope\` | https://dashscope.aliyuncs.com/compatible-mode/v1 | +| DeepSeek | \`deepseek\` | https://api.deepseek.com/v1 | +| SiliconFlow | \`siliconflow\` | https://api.siliconflow.cn/v1 | +| VolcEngine | \`volcengine\` | https://ark.cn-beijing.volces.com/api/v3 | +| Kimi (Moonshot) | \`kimi\` | https://api.moonshot.cn/v1 | +| GLM (Zhipu AI) | \`glm\` | https://open.bigmodel.cn/api/paas/v4 | +| StepFun | \`stepfun\` | https://api.stepfun.com/v1 | +| MiniMax | \`minimax\` | https://api.minimax.io/v1 | +| Ollama (local) | \`ollama\` | http://localhost:11434/v1 | + +For **non-preset providers**, you must specify \`--base-url\` manually. Example: \`\`\`bash @@ -196,11 +234,25 @@ If the thread reaches \`$END\` with status \`completed\`, the setup is working. ### Step 1 — Update packages \`\`\`bash -pnpm add -g @united-workforce/cli@latest # or: npm install -g @united-workforce/cli@latest -uwf --version # should print ${CLI_VERSION} +# Using pnpm +pnpm add -g @united-workforce/cli@latest -# Also update your adapter(s) +# Using npm +npm install -g @united-workforce/cli@latest +\`\`\` + +\`\`\`bash +uwf --version # should print ${CLI_VERSION} +\`\`\` + +Also update your adapter(s): + +\`\`\`bash +# pnpm pnpm add -g @united-workforce/agent-hermes@latest + +# npm +npm install -g @united-workforce/agent-hermes@latest \`\`\` ### Step 2 — Regenerate skills -- 2.43.0 From caba82fe36fef56b7ab9fc796635eb0fa4bf06da Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= Date: Fri, 5 Jun 2026 16:45:33 +0000 Subject: [PATCH 2/2] =?UTF-8?q?fix:=20bootstrap=20PATH=20fix=20guidance=20?= =?UTF-8?q?=E2=80=94=20find=20binary=20location=20+=20update=20shell=20con?= =?UTF-8?q?fig=20(#118=20#1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/cli/src/commands/prompt.ts | 24 ++++++++++++++---------- 1 file changed, 14 insertions(+), 10 deletions(-) diff --git a/packages/cli/src/commands/prompt.ts b/packages/cli/src/commands/prompt.ts index d427e75..a2d323d 100644 --- a/packages/cli/src/commands/prompt.ts +++ b/packages/cli/src/commands/prompt.ts @@ -100,14 +100,6 @@ pnpm add -g @united-workforce/cli npm install -g @united-workforce/cli \`\`\` -Verify the CLI is available: - -\`\`\`bash -uwf --version # should print ${CLI_VERSION} -\`\`\` - -If \`uwf\` is not found, your global bin directory is not in PATH — go back to Step 0 check #3. - Next, install an agent adapter (**must be installed before running \`uwf setup --agent\`**): | Adapter | Install (pnpm / npm) | When to use | @@ -116,13 +108,25 @@ Next, install an agent adapter (**must be installed before running \`uwf setup - | uwf-claude-code | \`pnpm add -g @united-workforce/agent-claude-code\` / \`npm i -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly | | uwf-builtin | \`pnpm add -g @united-workforce/agent-builtin\` / \`npm i -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) | -Verify the adapter is installed: +**After installing, verify that \`uwf\` and the adapter command (e.g. \`uwf-hermes\`) are available in PATH.** Run: \`\`\`bash +uwf --version # should print ${CLI_VERSION} uwf-hermes --version # (or uwf-claude-code / uwf-builtin) \`\`\` -If the command is not found, check your global bin PATH (Step 0 check #3). +If either command is not found, the global bin directory is not in the current shell's PATH. **You must fix this before continuing:** + +1. Find where the binary was installed: + \`\`\`bash + find ~/.local ~/.hermes /usr/local -name uwf -type f 2>/dev/null + npm prefix -g # global prefix — bin is /bin + \`\`\` +2. Add the directory to PATH permanently by appending to the user's shell config (e.g. \`~/.bashrc\`, \`~/.zshrc\`, \`~/.profile\`, or fish config): + \`\`\`bash + export PATH=":$PATH" + \`\`\` +3. Source the updated config or open a new shell, then re-verify the commands work. **uwf-hermes** also requires the Hermes ACP plugin: \`\`\`bash -- 2.43.0