From a536efee000e6328febb293140ae64975d8a97e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= Date: Fri, 5 Jun 2026 08:52:35 +0000 Subject: [PATCH] fix: simplify prompt subcommands, framework-agnostic bootstrap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - `uwf prompt usage` now outputs only the usage skill (was three combined) - `uwf prompt bootstrap` replaces `setup` with framework-agnostic instructions - Remove `usage-reference` and `setup` subcommands - Remove `generateBootstrapReference` from util (moved to cli) Fixes #99 小橘 🍊（NEKO Team） --- packages/cli/src/__tests__/prompt.test.ts | 65 +++++++---------------- packages/cli/src/cli.ts | 24 ++------- packages/cli/src/commands/prompt.ts | 63 ++++++++-------------- packages/util/src/bootstrap-reference.ts | 40 -------------- packages/util/src/index.ts | 1 - 5 files changed, 45 insertions(+), 148 deletions(-) delete mode 100644 packages/util/src/bootstrap-reference.ts diff --git a/packages/cli/src/__tests__/prompt.test.ts b/packages/cli/src/__tests__/prompt.test.ts index 63b42ee..3a2cb66 100644 --- a/packages/cli/src/__tests__/prompt.test.ts +++ b/packages/cli/src/__tests__/prompt.test.ts @@ -9,31 +9,25 @@ import { cmdPromptAdapterDeveloping, cmdPromptBootstrap, cmdPromptList, - cmdPromptSetup, cmdPromptUsage, - cmdPromptUsageReference, cmdPromptWorkflowAuthoring, } from "../commands/prompt.js"; describe("prompt commands", () => { - test("prompt list returns new prompt names", () => { + test("prompt list returns prompt names (no bootstrap)", () => { const result = cmdPromptList(); expect(result).toBeInstanceOf(Array); expect(result).toContain("usage"); expect(result).toContain("workflow-authoring"); expect(result).toContain("adapter-developing"); - expect(result).toContain("bootstrap"); - expect(result).not.toContain("user"); - expect(result).not.toContain("author"); - expect(result).not.toContain("developer"); - expect(result).not.toContain("adapter"); + expect(result).not.toContain("bootstrap"); for (const name of result) { expect(name).toMatch(/^\S+$/); } }); - test("prompt usage-reference returns non-empty markdown string with frontmatter", () => { - const result = cmdPromptUsageReference(); + test("prompt usage returns only the usage reference with frontmatter", () => { + const result = cmdPromptUsage(); expect(typeof result).toBe("string"); expect(result).toContain("uwf"); expect(result).toContain("thread"); @@ -42,6 +36,9 @@ describe("prompt commands", () => { expect(result).toContain("---"); expect(result).toContain("name:"); expect(result).toContain("version:"); + // Should NOT contain other references + expect(result).not.toContain("Workflow Authoring Reference"); + expect(result).not.toContain("Adapter Developing Reference"); expect(result.length).toBeGreaterThan(500); }); @@ -71,44 +68,19 @@ describe("prompt commands", () => { expect(result.length).toBeGreaterThan(500); }); - test("prompt bootstrap returns non-empty skill with frontmatter", () => { + test("prompt bootstrap returns framework-agnostic setup instructions", () => { const result = cmdPromptBootstrap(); expect(typeof result).toBe("string"); - expect(result).toContain("uwf"); - expect(result).toContain("---"); - expect(result.length).toBeGreaterThan(100); - }); - - test("prompt usage combines remaining references (no developer)", () => { - const result = cmdPromptUsage(); - expect(typeof result).toBe("string"); - expect(result).toContain("Usage Reference"); - expect(result).toContain("Workflow Authoring Reference"); - expect(result).toContain("Adapter Developing Reference"); - expect(result).not.toContain("Developer Reference"); - expect(result).toContain("---"); - expect(result.length).toBeGreaterThan(2000); - }); - - test("prompt setup returns simplified setup instructions", () => { - const result = cmdPromptSetup(); - expect(typeof result).toBe("string"); - expect(result).toContain("uwf Skill Setup"); - expect(result).toContain("uwf prompt bootstrap"); - expect(result).toContain("SKILL.md"); - expect(result).toContain("version"); - expect(result).not.toMatch(/\bbun (install|run|test|changeset|version|release)\b/); - }); - - test("prompt setup references new subcommand names", () => { - const result = cmdPromptSetup(); expect(result).toContain("uwf prompt usage"); expect(result).toContain("uwf prompt workflow-authoring"); expect(result).toContain("uwf prompt adapter-developing"); - expect(result).not.toContain("uwf prompt user"); - expect(result).not.toContain("uwf prompt author"); - expect(result).not.toContain("uwf prompt developer"); - expect(result).not.toMatch(/uwf prompt adapter\b(?!-developing)/); + expect(result).toContain("uwf-usage"); + expect(result).toContain("uwf-workflow-authoring"); + expect(result).toContain("uwf-adapter-developing"); + // Should NOT contain Hermes-specific paths + expect(result).not.toContain("~/.hermes/skills/"); + expect(result).not.toContain("> ~/.hermes/"); + expect(result.length).toBeGreaterThan(100); }); test("prompt help subcommand is suppressed", { timeout: 30_000 }, () => { @@ -119,11 +91,12 @@ describe("prompt commands", () => { }); expect(output).not.toMatch(/help\s+\[command\]/i); expect(output).toContain("usage"); - expect(output).toContain("setup"); + expect(output).toContain("bootstrap"); expect(output).toContain("workflow-authoring"); expect(output).toContain("adapter-developing"); - expect(output).toContain("bootstrap"); expect(output).toContain("list"); - expect(output).not.toContain("developer"); + // Removed subcommands should not appear as command names + expect(output).not.toMatch(/^\s+setup\s/m); + expect(output).not.toContain("usage-reference"); }); }); diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts index 64f2d42..17e775d 100755 --- a/packages/cli/src/cli.ts +++ b/packages/cli/src/cli.ts @@ -8,9 +8,7 @@ import { cmdPromptAdapterDeveloping, cmdPromptBootstrap, cmdPromptList, - cmdPromptSetup, cmdPromptUsage, - cmdPromptUsageReference, cmdPromptWorkflowAuthoring, } from "./commands/prompt.js"; import { cmdSetup, cmdSetupInteractive } from "./commands/setup.js"; @@ -509,23 +507,16 @@ prompt.addHelpCommand(false); prompt .command("usage") - .description("Print the complete skill content (all references combined)") + .description("Print the usage reference (CLI guide + typical workflows)") .action(() => { console.log(cmdPromptUsage()); }); prompt - .command("setup") - .description("Print setup instructions for installing the uwf skill") + .command("bootstrap") + .description("Print setup instructions for installing uwf skills") .action(() => { - console.log(cmdPromptSetup()); - }); - -prompt - .command("usage-reference") - .description("Print the usage reference (CLI guide + typical workflows)") - .action(() => { - console.log(cmdPromptUsageReference()); + console.log(cmdPromptBootstrap()); }); prompt @@ -542,13 +533,6 @@ prompt console.log(cmdPromptAdapterDeveloping()); }); -prompt - .command("bootstrap") - .description("Print the bootstrap skill YAML for Hermes agents") - .action(() => { - console.log(cmdPromptBootstrap()); - }); - prompt .command("list") .description("List all available prompt names") diff --git a/packages/cli/src/commands/prompt.ts b/packages/cli/src/commands/prompt.ts index 70fbe2d..24a7381 100644 --- a/packages/cli/src/commands/prompt.ts +++ b/packages/cli/src/commands/prompt.ts @@ -1,14 +1,13 @@ import { generateAdapterDevelopingReference, - generateBootstrapReference, generateUsageReference, generateWorkflowAuthoringReference, + VERSION, } from "@united-workforce/util"; export { generateAdapterDevelopingReference as cmdPromptAdapterDeveloping, - generateBootstrapReference as cmdPromptBootstrap, - generateUsageReference as cmdPromptUsageReference, + generateUsageReference as cmdPromptUsage, generateWorkflowAuthoringReference as cmdPromptWorkflowAuthoring, }; @@ -16,24 +15,16 @@ const PROMPT_ENTRIES: ReadonlyArray<{ name: string; generate: () => string }> = { name: "usage", generate: generateUsageReference }, { name: "workflow-authoring", generate: generateWorkflowAuthoringReference }, { name: "adapter-developing", generate: generateAdapterDevelopingReference }, - { name: "bootstrap", generate: generateBootstrapReference }, ]; export function cmdPromptList(): ReadonlyArray { return PROMPT_ENTRIES.map((e) => e.name); } -export function cmdPromptUsage(): string { - return PROMPT_ENTRIES.filter((e) => e.name !== "bootstrap") - .map((e) => e.generate()) - .join("\n\n---\n\n"); -} +export function cmdPromptBootstrap(): string { + return `# uwf Skill Bootstrap -export function cmdPromptSetup(): string { - return `# uwf Skill Setup - -You are being asked to install or update the uwf (United Workforce) skill -so that you know how to use the \`uwf\` CLI for workflow orchestration. +Install or update the uwf (United Workforce) skills for your agent. ## Steps @@ -42,40 +33,30 @@ so that you know how to use the \`uwf\` CLI for workflow orchestration. uwf --help \`\`\` If not installed: \`npm install -g @united-workforce/cli\` + Current version: ${VERSION} -2. **Clean up old versions of the skill** (if any exist): - - Look for any existing uwf/workflow skill files in your skill directories - (e.g. \`~/.hermes/skills/uwf/SKILL.md\` or similar paths). - - If a skill exists, read its \`version\` from the YAML frontmatter. - - If the version matches the current CLI version (\`uwf --version\`), you're done — no update needed. - - If the version is older, **delete the old skill file** before proceeding. +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\` -3. **Install the bootstrap skill:** - \`\`\`bash - uwf prompt bootstrap > ~/.hermes/skills/uwf/SKILL.md - \`\`\` - The bootstrap prompt already includes complete YAML frontmatter — no editing needed. + Each command outputs a complete SKILL.md with YAML frontmatter — use your agent framework's skill creation API to save them. -4. **Verify** the skill is loadable by your agent framework. +3. **Verify** the skills are loadable by your agent framework. -## Individual prompts +## Updating -Each prompt outputs a complete SKILL.md with frontmatter — pipe directly to a file: +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. + +## Available prompts \`\`\`bash -uwf prompt list # list available prompt names -uwf prompt usage > ~/.hermes/skills/uwf-usage/SKILL.md # CLI usage guide -uwf prompt workflow-authoring > ~/.hermes/skills/uwf-workflow-authoring/SKILL.md -uwf prompt adapter-developing > ~/.hermes/skills/uwf-adapter-developing/SKILL.md -uwf prompt bootstrap > ~/.hermes/skills/uwf/SKILL.md # bootstrap skill +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 \`\`\` - -## Notes - -- The skill content is bundled with the CLI and versioned with it — always use - \`uwf prompt usage\` to get the content matching your installed version. -- Do NOT hand-edit the skill body. If the CLI is updated, re-run \`uwf prompt setup\` - and follow the steps again. -- When upgrading, always delete the old skill first to avoid stale instructions. `; } diff --git a/packages/util/src/bootstrap-reference.ts b/packages/util/src/bootstrap-reference.ts deleted file mode 100644 index 66d5121..0000000 --- a/packages/util/src/bootstrap-reference.ts +++ /dev/null @@ -1,40 +0,0 @@ -export function generateBootstrapReference(): string { - return `--- -name: uwf -description: "United Workforce (uwf) — YAML 状态机工作流引擎。任务涉及 workflow 时加载此 skill。" -tags: [workflow, uwf] -triggers: - - uwf - - workflow - - 工作流 ---- - -# uwf (United Workforce) - -YAML 状态机工作流引擎。当用户提到「workflow」「工作流」时，指的是 **uwf workflow**（YAML 定义的状态机），不是 Hermes skill。用 \`uwf\` CLI 操作，不要混淆。 - -## 首次使用 - -运行以下命令获取完整用法： - -\`\`\`bash -uwf prompt usage # 完整用法文档（所有引用合并） -uwf prompt workflow-authoring # workflow 编写指南（role 定义、graph 路由、schema） -uwf prompt adapter-developing # adapter 开发指南（构建新的 agent adapter） -\`\`\` - -## 快速参考 - -\`\`\`bash -uwf workflow list # 查看已注册 workflow -uwf workflow add # 注册 workflow -uwf thread start -p "prompt" # 创建 thread -uwf thread exec -c 10 # 执行最多 10 步 -uwf thread list # 查看所有 thread -\`\`\` - -## 示例 workflow - -参考项目 \`examples/\` 目录下的 YAML 文件（analyze-topic、debate、solve-issue）。 -`; -} diff --git a/packages/util/src/index.ts b/packages/util/src/index.ts index 3ac9725..3d32ccf 100644 --- a/packages/util/src/index.ts +++ b/packages/util/src/index.ts @@ -2,7 +2,6 @@ export { generateActorReference } from "./actor-reference.js"; export { generateAdapterDevelopingReference } from "./adapter-developing-reference.js"; export { generateArchitectureReference } from "./architecture-reference.js"; export { encodeUint64AsCrockford } from "./base32.js"; -export { generateBootstrapReference } from "./bootstrap-reference.js"; export { generateCliReference } from "./cli-reference.js"; export { env } from "./env.js"; export type {