@united-workforce/cli 0.4.0 → 0.5.0

package/src/cli.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env -S node --disable-warning=ExperimentalWarning
 
-import type { CasRef, ThreadId, ThreadStatus } from "@united-workforce/protocol";
+import type { CasRef, OutputSchemaName, ThreadId, ThreadStatus } from "@united-workforce/protocol";
 import { Command } from "commander";
 import { cmdConfigGet, cmdConfigList, cmdConfigSet } from "./commands/config.js";
 import { cmdLogClean, cmdLogList, cmdLogShow } from "./commands/log.js";
@@ -32,12 +32,61 @@ import {
   cmdWorkflowShow,
   cmdWorkflowValidate,
 } from "./commands/workflow.js";
-import { formatOutput, type OutputFormat } from "./format.js";
-import { resolveStorageRoot } from "./store.js";
+import {
+  formatOutput,
+  isOutputFormat,
+  type OutputFormat,
+  SUPPORTED_FORMATS,
+  writeEnvelope,
+} from "./format.js";
+import {
+  toStepDetailPayload,
+  toStepListPayload,
+  toThreadExecPayload,
+  toThreadListPayload,
+  toThreadStartPayload,
+  toThreadStatusPayload,
+  toValidateResultPayload,
+  toWorkflowAddPayload,
+  toWorkflowDetailPayload,
+  toWorkflowListPayload,
+} from "./output-mappers.js";
+import { createUwfStore, resolveStorageRoot } from "./store.js";
+
+function getFormat(): OutputFormat {
+  const raw = program.opts().format as string;
+  if (!isOutputFormat(raw)) {
+    process.stderr.write(
+      `Invalid --format: ${raw}. Must be one of: ${SUPPORTED_FORMATS.join(", ")}\n`,
+    );
+    process.exit(1);
+  }
+  return raw;
+}
+
+async function writeOutput(
+  payload: unknown,
+  schemaName: OutputSchemaName,
+  storageRoot: string,
+): Promise<void> {
+  const fmt = getFormat();
+  const uwf = await createUwfStore(storageRoot);
+  await writeEnvelope(payload, schemaName, {
+    format: fmt,
+    store: uwf.store,
+    schemas: uwf.schemas,
+  });
+}
 
-function writeOutput(data: unknown): void {
-  const fmt = program.opts().format as OutputFormat;
-  process.stdout.write(`${formatOutput(data, fmt)}\n`);
+/**
+ * Legacy raw output for commands without an output schema (log/config/setup).
+ * Always emits text/JSON/YAML based on the active --format. For `text`
+ * (the default) it renders via the per-command registry when available
+ * and falls back to JSON.
+ */
+function writeRawOutput(data: unknown, commandPath?: string): void {
+  const fmt = getFormat();
+  process.stdout.write(`${formatOutput(data, fmt, commandPath)}\n`);
 }
 
 function runAction(action: () => Promise<void>): void {
@@ -60,7 +109,11 @@ program
       "  workflow → thread → step → turn",
   )
   .version(pkg.default.version, "-V, --version");
-program.option("--format <fmt>", "Output format: json or yaml", "json");
+program.option(
+  "--format <fmt>",
+  "Output format: text (default), json, yaml, raw-json, raw-yaml",
+  "text",
+);
 
 const workflow = program
   .command("workflow")
@@ -74,7 +127,7 @@ workflow
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdWorkflowAdd(storageRoot, file);
-      writeOutput(result);
+      await writeOutput(toWorkflowAddPayload(result), "workflow-add", storageRoot);
     });
   });
 
@@ -83,9 +136,13 @@ workflow
   .description("Validate a workflow YAML without registering it (CI-friendly)")
   .argument("<file>", "Workflow YAML file")
   .action((file: string) => {
+    const storageRoot = resolveStorageRoot();
     runAction(async () => {
-      await cmdWorkflowValidate(file);
-      // silent on success — do not call writeOutput
+      const errors = await cmdWorkflowValidate(file);
+      await writeOutput(toValidateResultPayload(errors), "validate-result", storageRoot);
+      if (errors.length > 0) {
+        process.exit(1);
+      }
     });
   });
 
@@ -97,7 +154,7 @@ workflow
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdWorkflowShow(storageRoot, id, process.cwd());
-      writeOutput(result);
+      await writeOutput(toWorkflowDetailPayload(result), "workflow-detail", storageRoot);
     });
   });
 
@@ -108,7 +165,7 @@ workflow
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdWorkflowList(storageRoot, process.cwd());
-      writeOutput(result);
+      await writeOutput(toWorkflowListPayload(result), "workflow-list", storageRoot);
     });
   });
 
@@ -130,7 +187,7 @@ thread
         process.cwd(),
         opts.cwd ?? process.cwd(),
       );
-      writeOutput(result);
+      await writeOutput(toThreadStartPayload(result), "thread-start", storageRoot);
     });
   });
 
@@ -167,11 +224,7 @@ thread
           background,
           backgroundWorker,
         );
-        if (results.length === 1) {
-          writeOutput(results[0]);
-        } else {
-          writeOutput(results);
-        }
+        await writeOutput(toThreadExecPayload(results), "thread-exec", storageRoot);
       });
     },
   );
@@ -184,7 +237,7 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadShow(storageRoot, threadId);
-      writeOutput(result);
+      await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
     });
   });
 
@@ -292,7 +345,7 @@ thread
           take,
           showAll,
         );
-        writeOutput(result);
+        await writeOutput(toThreadListPayload(result), "thread-list", storageRoot);
       });
     },
   );
@@ -314,7 +367,7 @@ thread
         supplement,
         agentOverride,
       );
-      writeOutput(result);
+      await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
     });
   });
 
@@ -334,7 +387,7 @@ thread
         opts.prompt,
         agentOverride,
       );
-      writeOutput(result);
+      await writeOutput(toThreadStatusPayload(result), "thread-status", storageRoot);
     });
   });
 
@@ -346,7 +399,7 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadStop(storageRoot, threadId);
-      writeOutput(result);
+      writeRawOutput(result, "thread stop");
     });
   });
 
@@ -358,7 +411,7 @@ thread
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdThreadCancel(storageRoot, threadId);
-      writeOutput(result);
+      writeRawOutput(result, "thread cancel");
     });
   });
 
@@ -401,7 +454,7 @@ step
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdStepList(storageRoot, threadId);
-      writeOutput(result);
+      await writeOutput(toStepListPayload(result), "step-list", storageRoot);
     });
   });
 
@@ -413,7 +466,11 @@ step
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const detail = await cmdStepShow(storageRoot, stepHash as CasRef);
-      writeOutput(detail);
+      await writeOutput(
+        toStepDetailPayload(stepHash as CasRef, detail),
+        "step-detail",
+        storageRoot,
+      );
     });
   });
 
@@ -475,7 +532,7 @@ step
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdStepFork(storageRoot, stepHash as CasRef);
-      writeOutput(result);
+      writeRawOutput(result);
     });
   });
 
@@ -618,7 +675,7 @@ program
   .command("setup")
   .description(
     "Configure the default agent. Run without --agent for interactive wizard.\n" +
-      "LLM provider/model configuration lives in <storage>/config.yaml under providers and models.",
+      "Each adapter owns its own LLM configuration — the engine config is LLM-free.",
   )
   .option("--agent <name>", "Default agent adapter (e.g. hermes → uwf-hermes)")
   .action((opts: { agent?: string }) => {
@@ -626,7 +683,7 @@ program
     runAction(async () => {
       if (opts.agent !== undefined && opts.agent !== "") {
         const result = await cmdSetup({ agent: opts.agent, storageRoot });
-        writeOutput(result);
+        writeRawOutput(result);
       } else {
         await cmdSetupInteractive(storageRoot);
       }
@@ -642,7 +699,7 @@ log
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdLogList(storageRoot);
-      writeOutput(result);
+      writeRawOutput(result, "log list");
     });
   });
 
@@ -665,7 +722,7 @@ log
           process: opts.process ?? null,
           date: opts.date ?? null,
         });
-        writeOutput(result);
+        writeRawOutput(result, "log show");
       });
     },
   );
@@ -678,7 +735,7 @@ log
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdLogClean(storageRoot, opts.before);
-      writeOutput(result);
+      writeRawOutput(result);
     });
   });
 
@@ -691,7 +748,7 @@ config
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdConfigList(storageRoot);
-      writeOutput(result);
+      writeRawOutput(result, "config list");
     });
   });
 
@@ -706,7 +763,7 @@ config
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdConfigGet(storageRoot, key);
-      writeOutput({ value: result });
+      writeRawOutput({ value: result }, "config get");
     });
   });
 
@@ -719,7 +776,7 @@ config
     const storageRoot = resolveStorageRoot();
     runAction(async () => {
       const result = await cmdConfigSet(storageRoot, key, value);
-      writeOutput(result);
+      writeRawOutput(result, "config set");
     });
   });
 

package/src/commands/config.ts

@@ -21,6 +21,11 @@ const VALID_CONFIG_KEYS: Record<
     // No knownFields — workflow/role names are user-defined
   },
   defaultAgent: { nested: false },
+  concurrency: {
+    nested: true,
+    knownFields: ["maxRunning"],
+    minDepth: 2,
+  },
 };
 
 /**
@@ -264,6 +269,12 @@ export async function cmdConfigSet(
   let parsedValue: unknown = value;
   if (lastSegment === "args") {
     parsedValue = parseArgsValue(value);
+  } else if (lastSegment === "maxRunning") {
+    const num = Number(value);
+    if (!Number.isInteger(num) || num < 1) {
+      throw new Error("Value for 'maxRunning' must be a positive integer");
+    }
+    parsedValue = num;
   }
 
   // Validate we're not setting a property on a non-object

package/src/commands/prompt.ts

@@ -148,44 +148,36 @@ pipx install 'hermes-agent[acp]'
 pip install -e '.[acp]'
 \`\`\`
 
-### Step 2 — Configure provider and model
+### Step 2 — Configure default agent
 
-uwf needs an LLM provider to run agents. **Ask the user** for their provider, API key, and model, then run:
+Run the interactive wizard:
 
 \`\`\`bash
-uwf setup --provider <name> --api-key <key> --model <model> --agent <adapter-command>
+uwf setup
 \`\`\`
 
-**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:
+Or configure non-interactively:
+
 \`\`\`bash
-uwf setup --provider openrouter --api-key sk-or-... --model anthropic/claude-sonnet-4 --agent uwf-hermes
+uwf setup --agent <adapter-command>
+\`\`\`
+
+**Note:** \`--agent\` takes the adapter **command name** (e.g. \`uwf-hermes\`, \`uwf-claude-code\`), not the npm package name.
+
+Config is saved to \`~/.uwf/config.yaml\`:
+
+\`\`\`yaml
+agents:
+  hermes:
+    command: uwf-hermes
+    args: []
+defaultAgent: hermes
+agentOverrides: {}
 \`\`\`
 
-If the user doesn't know what to choose, suggest \`openrouter\` with \`anthropic/claude-sonnet-4\` as a sensible default.
+**LLM configuration** is per-adapter — each adapter manages its own provider, model, and API key settings independently (typically via environment variables like \`CLAUDE_MODEL\`, \`ANTHROPIC_API_KEY\`, etc.). The engine config (\`~/.uwf/config.yaml\`) is LLM-free.
 
-Config is saved to \`~/.uwf/config.yaml\`. Verify with \`cat ~/.uwf/config.yaml\`.
+Verify with \`cat ~/.uwf/config.yaml\`.
 
 ### Step 3 — Install skills
 
@@ -339,5 +331,26 @@ uwf prompt workflow-authoring  # workflow YAML design guide
 uwf prompt adapter-developing  # building agent adapters
 uwf prompt bootstrap           # this guide
 \`\`\`
+
+## What's next — introduce uwf to the user
+
+After setup is complete, give the user a brief introduction to what uwf can do
+and invite them to try it. Cover these three things:
+
+1. **Run workflows** — execute pre-built workflows to automate multi-step tasks.
+   Setup auto-registers example workflows, ready to use immediately.
+2. **Create workflows** — design custom YAML workflows for their own recurring tasks
+   (code review, issue triage, release pipelines, etc.). Use \`uwf prompt workflow-authoring\`
+   for the authoring guide.
+3. **Debug & improve workflows** — iterate on workflow definitions, inspect thread state
+   with \`uwf thread show\`, replay failed steps with \`uwf thread poke\`, and refine
+   role procedures based on real execution results.
+
+**Discover & try built-in examples:**
+
+Run \`uwf workflow list\` to see which workflows are registered (setup auto-registers
+several built-in examples). Show the user what's available, then invite them to try
+one — for instance, suggest a fun debate topic like "AI 是否会抢了人类的工作？" and
+offer to kick it off for them.
 `;
 }

package/src/commands/setup.ts

@@ -1,9 +1,11 @@
 import { execFileSync } from "node:child_process";
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { stdin as input, stdout as output } from "node:process";
 import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
 import { parse, stringify } from "yaml";
+import { cmdWorkflowAdd } from "./workflow.js";
 
 export type SetupArgs = {
   agent: string;
@@ -261,10 +263,56 @@ export function _checkAdapterAvailability(agentName: string): string[] {
   return warnings;
 }
 
+// ──────────────────────────────────────────────────────────────────────────────
+// Bundled example workflows
+// ──────────────────────────────────────────────────────────────────────────────
+
+/** Resolve the examples/ directory bundled with the CLI package. */
+function _findExamplesDir(): string | null {
+  // Walk up from this file (src/commands/ or dist/commands/) to the package root
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 5; i++) {
+    const candidate = join(dir, "examples");
+    if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+      return candidate;
+    }
+    dir = dirname(dir);
+  }
+  return null;
+}
+
+/**
+ * Register bundled example workflows. Non-destructive — silently skips
+ * any that fail (e.g. already registered with same hash).
+ * Returns list of successfully registered workflow names.
+ */
+export async function _registerBundledExamples(storageRoot: string): Promise<string[]> {
+  const examplesDir = _findExamplesDir();
+  if (examplesDir === null) return [];
+
+  const registered: string[] = [];
+  const files = readdirSync(examplesDir)
+    .filter((f) => f.endsWith(".yaml"))
+    .sort();
+
+  for (const file of files) {
+    try {
+      const result = await cmdWorkflowAdd(storageRoot, join(examplesDir, file));
+      registered.push(result.name);
+      console.error(`  ✓ ${result.name}`);
+    } catch {
+      // Skip silently — workflow may already exist or be invalid
+    }
+  }
+
+  return registered;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+
 /**
  * Non-interactive setup. Engine config is LLM-free — only writes
- * agents + defaultAgent. LLM provider/model configuration lives in
- * config.yaml under `providers` and `models`.
+ * agents + defaultAgent. Each adapter owns its own LLM configuration.
  */
 export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>> {
   const { storageRoot } = args;
@@ -287,16 +335,20 @@ export async function cmdSetup(args: SetupArgs): Promise<Record<string, unknown>
     console.error(`⚠ ${w}`);
   }
 
+  // Auto-register bundled example workflows
+  const registeredExamples = await _registerBundledExamples(storageRoot);
+
   return {
     configPath,
     defaultAgent: merged.defaultAgent,
     adapterWarnings,
+    registeredExamples,
   };
 }
 
 /**
- * Interactive setup — prompts the user only for the default agent. LLM
- * configuration lives in config.yaml under `providers` and `models`.
+ * Interactive setup — prompts the user only for the default agent.
+ * Each adapter owns its own LLM configuration.
  */
 export async function cmdSetupInteractive(storageRoot: string): Promise<Record<string, unknown>> {
   const rl = createInterface({ input, output });
@@ -313,8 +365,6 @@ export async function cmdSetupInteractive(storageRoot: string): Promise<Record<s
     console.log('  uwf thread start <name> -p "..."    Start a thread');
     console.log("  uwf thread exec <thread-id>         Execute next step");
     console.log("");
-    console.log("LLM config: edit ~/.uwf/config.yaml (providers + models sections).");
-    console.log("");
 
     return null as unknown as Record<string, unknown>;
   } finally {

package/src/commands/thread.ts

@@ -43,6 +43,7 @@ import {
   isThreadRunning,
   readMarker,
 } from "../background/index.js";
+import { acquireSlot, DEFAULT_MAX_RUNNING, installSlotCleanup } from "../concurrency/index.js";
 import { createIncludeTag } from "../include.js";
 import { evaluate } from "../moderator/index.js";
 import {
@@ -60,6 +61,7 @@ import {
 } from "../store.js";
 import { checkWorkflowFilenameConsistency, isCasRef, parseWorkflowPayload } from "../validate.js";
 import { validateWorkflow } from "../validate-semantic.js";
+import { getConfigPath, getNestedValue, loadConfig, parseDotPath } from "./config.js";
 import {
   type ChainState,
   collectOrderedSteps,
@@ -992,6 +994,15 @@ type EvaluateLastOutput = Record<string, unknown>;
 
 const STATUS_KEY = "$status";
 
+/**
+ * Strip YAML frontmatter (---...---) from a raw markdown string,
+ * returning only the body portion.
+ */
+function stripFrontmatter(raw: string): string {
+  const match = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/);
+  return match ? raw.slice(match[0].length).trim() : raw.trim();
+}
+
 function resolveEvaluateArgs(
   uwf: UwfStore,
   chain: ChainState,
@@ -1011,6 +1022,13 @@ function resolveEvaluateArgs(
       ? (raw as Record<string, unknown>)
       : {};
 
+  // Inject _body — the markdown body (after frontmatter) from the last step's
+  // assistant output. Workflow edge prompts can reference it via {{ _body }}.
+  const content = extractLastAssistantContent(uwf, lastStep.detail);
+  if (content !== null) {
+    base._body = stripFrontmatter(content);
+  }
+
   return {
     lastRole: lastStep.role,
     lastOutput: base,
@@ -1020,10 +1038,10 @@ function resolveEvaluateArgs(
 function loadWorkflowPayload(uwf: UwfStore, workflowRef: CasRef): WorkflowPayload {
   const node = uwf.store.cas.get(workflowRef);
   if (node === null) {
-    fail(`workflow CAS node not found: ${workflowRef}`);
+    throw new Error(`workflow CAS node not found: ${workflowRef}`);
   }
   if (node.type !== uwf.schemas.workflow) {
-    fail(`node ${workflowRef} is not a Workflow`);
+    throw new Error(`node ${workflowRef} is not a Workflow`);
   }
   return node.payload as WorkflowPayload;
 }
@@ -1406,6 +1424,25 @@ export function validateCount(count: number): void {
   }
 }
 
+/**
+ * Resolve the effective maxRunning limit.
+ * Priority: config file > DEFAULT_MAX_RUNNING (2).
+ */
+async function resolveMaxRunning(storageRoot: string): Promise<number> {
+  try {
+    const configPath = getConfigPath(storageRoot);
+    const config = loadConfig(configPath);
+    const path = parseDotPath("concurrency.maxRunning");
+    const value = getNestedValue(config, path);
+    if (typeof value === "number" && Number.isInteger(value) && value > 0) {
+      return value;
+    }
+  } catch {
+    // Config file missing or invalid — fall through to default
+  }
+  return DEFAULT_MAX_RUNNING;
+}
+
 export async function cmdThreadExec(
   storageRoot: string,
   threadId: ThreadId,
@@ -1446,6 +1483,13 @@ export async function cmdThreadExec(
     processStartTime: getProcessStartTime(process.pid),
   });
 
+  // Resolve concurrency limit: config > default
+  const effectiveMaxRunning = await resolveMaxRunning(storageRoot);
+
+  // Acquire concurrency slot (blocks if at capacity)
+  const slotHandle = await acquireSlot(storageRoot, effectiveMaxRunning);
+  const uninstallCleanup = installSlotCleanup(slotHandle);
+
   try {
     const results: StepOutput[] = [];
     for (let i = 0; i < count; i++) {
@@ -1457,6 +1501,8 @@ export async function cmdThreadExec(
     }
     return results;
   } finally {
+    uninstallCleanup();
+    await slotHandle.release();
     await deleteMarker(storageRoot, threadId);
   }
 }

package/src/commands/workflow.ts

@@ -126,7 +126,7 @@ export async function materializeWorkflowPayload(
  * returns silently (no stdout/stderr) and exits 0. On any error, writes a
  * single message to stderr and exits 1.
  */
-export async function cmdWorkflowValidate(filePath: string): Promise<void> {
+export async function cmdWorkflowValidate(filePath: string): Promise<string[]> {
   let text: string;
   try {
     text = await readFile(filePath, "utf8");
@@ -150,14 +150,10 @@ export async function cmdWorkflowValidate(filePath: string): Promise<void> {
 
   const filenameError = checkWorkflowFilenameConsistency(filePath, payload);
   if (filenameError !== null) {
-    fail(filenameError);
+    return [filenameError];
   }
 
-  const semanticErrors = validateWorkflow(payload);
-  if (semanticErrors.length > 0) {
-    fail(`workflow validation failed:\n${semanticErrors.map((e) => `  - ${e}`).join("\n")}`);
-  }
-  // success: silent return
+  return validateWorkflow(payload);
 }
 
 export async function cmdWorkflowAdd(