From c5eb8b79d1010c5045b472eb3c1800f139065a87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= Date: Fri, 5 Jun 2026 10:35:01 +0000 Subject: [PATCH] fix: expand bootstrap prompt with full onboarding and upgrade guide - Fresh install: CLI + adapter install, uwf setup, skills, e2e verify - Upgrade: update packages, regenerate skills, migrate workflows - Explicitly tells agent to ask user for provider/api-key/model - Lists all available adapters with install commands - Documents v0.2.0 $START migration Fixes #104 --- .changeset/bootstrap-onboarding.md | 9 ++ packages/cli/src/__tests__/prompt.test.ts | 10 ++ packages/cli/src/commands/prompt.ts | 132 ++++++++++++++++++---- 3 files changed, 132 insertions(+), 19 deletions(-) create mode 100644 .changeset/bootstrap-onboarding.md diff --git a/.changeset/bootstrap-onboarding.md b/.changeset/bootstrap-onboarding.md new file mode 100644 index 0000000..b0e6798 --- /dev/null +++ b/.changeset/bootstrap-onboarding.md @@ -0,0 +1,9 @@ +--- +"@united-workforce/cli": patch +--- + +fix: expand bootstrap prompt with full onboarding and upgrade guide + +Bootstrap now covers two scenarios: +- Fresh install: CLI + adapter installation, `uwf setup` configuration, skill installation, end-to-end verification +- Upgrade: package update, skill regeneration, breaking change migrations (e.g. $START new/resume) diff --git a/packages/cli/src/__tests__/prompt.test.ts b/packages/cli/src/__tests__/prompt.test.ts index 3a2cb66..21d5288 100644 --- a/packages/cli/src/__tests__/prompt.test.ts +++ b/packages/cli/src/__tests__/prompt.test.ts @@ -71,12 +71,22 @@ describe("prompt commands", () => { test("prompt bootstrap returns framework-agnostic setup instructions", () => { const result = cmdPromptBootstrap(); expect(typeof result).toBe("string"); + // Skills installation expect(result).toContain("uwf prompt usage"); expect(result).toContain("uwf prompt workflow-authoring"); expect(result).toContain("uwf prompt adapter-developing"); expect(result).toContain("uwf-usage"); expect(result).toContain("uwf-workflow-authoring"); expect(result).toContain("uwf-adapter-developing"); + // Fresh install scenario + expect(result).toContain("Fresh Install"); + expect(result).toContain("uwf setup"); + expect(result).toContain("--provider"); + expect(result).toContain("--api-key"); + expect(result).toContain("agent adapter"); + // Upgrade scenario + expect(result).toContain("Upgrade"); + expect(result).toContain("Migrate"); // Should NOT contain Hermes-specific paths expect(result).not.toContain("~/.hermes/skills/"); expect(result).not.toContain("> ~/.hermes/"); diff --git a/packages/cli/src/commands/prompt.ts b/packages/cli/src/commands/prompt.ts index 24a7381..60c5a97 100644 --- a/packages/cli/src/commands/prompt.ts +++ b/packages/cli/src/commands/prompt.ts @@ -22,33 +22,126 @@ export function cmdPromptList(): ReadonlyArray { } export function cmdPromptBootstrap(): string { - return `# uwf Skill Bootstrap + return `# uwf Bootstrap -Install or update the uwf (United Workforce) skills for your agent. +Set up or upgrade uwf (United Workforce) — from zero to running your first workflow. -## Steps +## Scenario A: Fresh Install -1. **Check if uwf CLI is installed:** - \`\`\`bash - uwf --help - \`\`\` - If not installed: \`npm install -g @united-workforce/cli\` - Current version: ${VERSION} +### Step 1 — Install CLI and agent adapter -2. **Install the skills** by running each command below and creating a skill from its output: - - Run \`uwf prompt usage\` → create a skill named \`uwf-usage\` - - Run \`uwf prompt workflow-authoring\` → create a skill named \`uwf-workflow-authoring\` - - Run \`uwf prompt adapter-developing\` → create a skill named \`uwf-adapter-developing\` +\`\`\`bash +npm install -g @united-workforce/cli +uwf --version # should print ${VERSION} +\`\`\` - Each command outputs a complete SKILL.md with YAML frontmatter — use your agent framework's skill creation API to save them. +Install an agent adapter (at least one is required): -3. **Verify** the skills are loadable by your agent framework. +| Adapter | Install | When to use | +|---------|---------|-------------| +| uwf-hermes | \`npm install -g @united-workforce/agent-hermes\` | When your agent framework is Hermes Agent | +| uwf-claude-code | \`npm install -g @united-workforce/agent-claude-code\` | When using Claude Code CLI directly | +| uwf-builtin | \`npm install -g @united-workforce/agent-builtin\` | Lightweight built-in agent (no external dependency) | -## Updating +Verify the adapter is installed: \`uwf-hermes --version\` (or whichever you chose). -When \`uwf\` is upgraded, re-run \`uwf prompt bootstrap\` and follow the steps again. -The skill content is bundled with the CLI — always use \`uwf prompt \` to get -content matching your installed version. +### 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 ] +\`\`\` + +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 + +Example: +\`\`\`bash +uwf setup --provider openrouter --api-key sk-or-... --model anthropic/claude-sonnet-4 --agent uwf-hermes +\`\`\` + +If the user doesn't know what to choose, suggest \`openrouter\` with \`anthropic/claude-sonnet-4\` as a sensible default. + +Config is saved to \`~/.uwf/config.yaml\`. Verify with \`cat ~/.uwf/config.yaml\`. + +### Step 3 — Install skills + +Run each command and create a skill from its output: + +\`\`\`bash +uwf prompt usage # → save as skill "uwf-usage" +uwf prompt workflow-authoring # → save as skill "uwf-workflow-authoring" +uwf prompt adapter-developing # → save as skill "uwf-adapter-developing" +\`\`\` + +Each command outputs a complete SKILL.md with YAML frontmatter. Use your agent framework's skill creation API to save them (e.g. \`skill_manage(action='create', name='uwf-usage', content=)\`). + +Verify skills are installed by listing them (e.g. \`skills_list()\`) and confirming all three appear. + +### Step 4 — Verify end-to-end + +Run a quick smoke test with the built-in eval workflow: + +\`\`\`bash +# Start a thread with the example workflow +uwf thread start examples/eval-simple.yaml -p "Hello, test run" + +# Execute one step +uwf thread exec + +# Check result +uwf thread show +\`\`\` + +If the thread reaches \`$END\` or produces output, the setup is working. + +## Scenario B: Upgrade from Previous Version + +### Step 1 — Update packages + +\`\`\`bash +npm install -g @united-workforce/cli@latest +uwf --version # should print ${VERSION} + +# Also update your adapter(s) +npm install -g @united-workforce/agent-hermes@latest +\`\`\` + +### Step 2 — Regenerate skills + +Skill content is bundled with the CLI — always regenerate after upgrading: + +\`\`\`bash +uwf prompt usage # → update skill "uwf-usage" +uwf prompt workflow-authoring # → update skill "uwf-workflow-authoring" +uwf prompt adapter-developing # → update skill "uwf-adapter-developing" +\`\`\` + +### Step 3 — Migrate workflow YAML files (if needed) + +Check the changelog for breaking changes. Known migrations: + +- **v0.2.0**: \`$START._\` → \`$START.new\` + \`$START.resume\`. All workflow YAML files must be updated: + \`\`\`yaml + # Before (v0.1.x) + $START: + _: { role: planner, prompt: "..." } + + # After (v0.2.0+) + $START: + new: { role: planner, prompt: "..." } + resume: { role: planner, prompt: "Review previous run and continue." } + \`\`\` + +Update all \`.workflow/\` and \`.workflows/\` YAML files in your projects. \`uwf workflow add\` will reject files with the old \`_\` syntax. + +### Step 4 — Verify + +\`\`\`bash +uwf thread start -p "upgrade test" +uwf thread exec +\`\`\` ## Available prompts @@ -57,6 +150,7 @@ uwf prompt list # list available prompt names uwf prompt usage # CLI usage guide uwf prompt workflow-authoring # workflow YAML design guide uwf prompt adapter-developing # building agent adapters +uwf prompt bootstrap # this guide \`\`\` `; } -- 2.43.0