diff --git a/packages/cli-workflow/README.md b/packages/cli-workflow/README.md index 12affdc..32b7e7a 100644 --- a/packages/cli-workflow/README.md +++ b/packages/cli-workflow/README.md @@ -6,6 +6,18 @@ Layer 4 entry point for the workflow engine. The `uwf` binary orchestrates one step per invocation: load thread head from `threads.yaml`, run the moderator, spawn the configured agent CLI, run extract, append a CAS step node, and update the head pointer (or archive when `$END`). +### Four-Layer Architecture + +``` +workflow → thread → step → turn +模板定义 执行实例 单步结果 agent内部交互 +``` + +- **Workflow** (layer 1): YAML template with roles and routing graph +- **Thread** (layer 2): Single workflow execution instance +- **Step** (layer 3): One moderator→agent→extract cycle +- **Turn** (layer 4): Agent-internal interactions (use `step read` or CAS to inspect) + This package has no library `src/index.ts` — it is consumed as a CLI binary only. **Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`, `@uncaged/workflow-agent-kit`, `@uncaged/workflow-moderator`, `@uncaged/workflow-protocol`, `@uncaged/workflow-util`, `commander`, `dotenv`, `yaml` @@ -30,34 +42,53 @@ bun link packages/cli-workflow -h, --help Show help ``` -### Thread +### Thread (Layer 2: Execution Instances) | Command | Description | |---------|-------------| | `uwf thread start -p ` | Create a thread without executing | -| `uwf thread step [--agent ] [-c ]` | Execute one or more moderator→agent→extract cycles | +| `uwf thread exec [--agent ] [-c ] [--background]` | Execute one or more moderator→agent→extract cycles | | `uwf thread show ` | Show thread head pointer | -| `uwf thread list [--all]` | List active threads (`--all` includes archived) | -| `uwf thread steps ` | List all steps chronologically | +| `uwf thread list [--status ]` | List threads, optionally filtered by status | | `uwf thread read [--quota N] [--before ] [--start]` | Render thread as readable markdown | -| `uwf thread fork ` | Fork from a specific step | -| `uwf thread step-details ` | Dump full detail node as YAML | -| `uwf thread kill ` | Terminate and archive | +| `uwf thread stop ` | Stop background execution (keep thread active) | +| `uwf thread cancel ` | Cancel thread (stop + archive to history) | Examples: ```bash uwf thread start solve-issue -p "Fix the login redirect bug" -uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV -uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV -c 3 --agent uwf-builtin +uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV +uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV -c 3 --agent uwf-builtin +uwf thread exec 01ARZ3NDEKTSV4RRFFQ69G5FAV --background +uwf thread list --status running uwf thread read 01ARZ3NDEKTSV4RRFFQ69G5FAV --quota 8000 +uwf thread stop 01ARZ3NDEKTSV4RRFFQ69G5FAV ``` -### Workflow +### Step (Layer 3: Single Cycle Results) | Command | Description | |---------|-------------| -| `uwf workflow put ` | Register a workflow from YAML | +| `uwf step list ` | List all steps in a thread chronologically | +| `uwf step show ` | Show step metadata and frontmatter | +| `uwf step read [--before N]` | Read step output as markdown | +| `uwf step fork ` | Fork a thread from a specific step | + +Examples: + +```bash +uwf step list 01ARZ3NDEKTSV4RRFFQ69G5FAV +uwf step show 32GCDE899RRQ3 +uwf step read 32GCDE899RRQ3 --before 3 +uwf step fork 32GCDE899RRQ3 +``` + +### Workflow (Layer 1: Templates) + +| Command | Description | +|---------|-------------| +| `uwf workflow add ` | Register a workflow from YAML | | `uwf workflow show ` | Show workflow definition | | `uwf workflow list` | List registered workflows | @@ -99,6 +130,52 @@ Config: `~/.uncaged/workflow/config.yaml`. API keys: `~/.uncaged/workflow/.env`. | `uwf log show [--thread ] [--process ] [--date YYYY-MM-DD]` | Show filtered log entries | | `uwf log clean [--before YYYY-MM-DD]` | Delete old log files | +## Migration Guide + +### Breaking Changes (v0.x → v1.x) + +The CLI was reorganized to clarify the four-layer architecture. **No backward compatibility** — old commands have been removed. + +#### Renamed Commands + +| Old Command | New Command | Notes | +|------------|-------------|-------| +| `workflow put` | `workflow add` | More intuitive verb | +| `thread step` | `thread exec` | Eliminates ambiguity with "step" noun | +| `thread list --all` | `thread list --status completed` | Unified status filtering | + +#### Removed Commands (Merged) + +| Old Command | New Command | Notes | +|------------|-------------|-------| +| `thread running` | `thread list --status running` | Merged into unified list | + +#### Removed Commands (Split) + +| Old Command | New Commands | Notes | +|------------|-------------|-------| +| `thread kill` | `thread stop` or `thread cancel` | `stop` keeps thread active, `cancel` archives it | + +#### Moved Commands + +| Old Command | New Command | Notes | +|------------|-------------|-------| +| `thread steps` | `step list` | Moved to step layer | +| `thread step-details` | `step show` | Moved to step layer | +| `thread fork` | `step fork` | Moved to step layer (forks are step-based) | + +#### Deprecation Errors + +Old commands now show helpful error messages: + +```bash +$ uwf thread step 01ARZ3NDEKTSV4RRFFQ69G5FAV +Error: Command 'thread step' has been removed. +Use 'thread exec' instead. + +For more information, see: uwf help thread exec +``` + ## Internal Structure ``` @@ -109,8 +186,9 @@ src/ ├── validate.ts Workflow YAML validation ├── schemas.ts CLI-local schema registration └── commands/ - ├── thread.ts Thread lifecycle and step execution - ├── workflow.ts Workflow registry (put/show/list) + ├── thread.ts Thread lifecycle and exec + ├── step.ts Step operations (list/show/read/fork) + ├── workflow.ts Workflow registry (add/show/list) ├── cas.ts CAS inspection and schema ops ├── setup.ts Interactive/non-interactive setup ├── skill.ts Built-in skill references diff --git a/packages/cli-workflow/src/cli.ts b/packages/cli-workflow/src/cli.ts index b7f1a76..04e2cfd 100755 --- a/packages/cli-workflow/src/cli.ts +++ b/packages/cli-workflow/src/cli.ts @@ -52,11 +52,18 @@ const program = new Command(); const pkg = await import("../package.json", { with: { type: "json" } }); program .name("uwf") - .description("Stateless workflow CLI") + .description( + "Stateless workflow CLI\n\n" + + "Four-layer architecture:\n" + + " workflow → thread → step → turn\n" + + " 模板定义 执行实例 单步结果 agent内部交互", + ) .version(pkg.default.version, "-V, --version"); program.option("--format ", "Output format: json or yaml", "json"); -const workflow = program.command("workflow").description("Workflow registry and CAS"); +const workflow = program + .command("workflow") + .description("Workflow definitions (layer 1: templates)"); workflow .command("add") @@ -93,7 +100,9 @@ workflow }); }); -const thread = program.command("thread").description("Thread lifecycle and execution"); +const thread = program + .command("thread") + .description("Thread execution (layer 2: instances)"); thread .command("start") @@ -240,7 +249,7 @@ thread }, ); -const step = program.command("step").description("Step operations"); +const step = program.command("step").description("Step results (layer 3: single cycle)"); step .command("list") @@ -292,6 +301,103 @@ step }); }); +// ── Deprecation Handlers ────────────────────────────────────────────────────── +// These commands have been removed. Show helpful error messages. + +workflow + .command("put") + .description("[DEPRECATED] Use 'workflow add' instead") + .argument("", "Workflow YAML file") + .action(() => { + process.stderr.write(`Error: Command 'workflow put' has been removed. +Use 'workflow add' instead. + +For more information, see: uwf help workflow add +`); + process.exit(1); + }); + +thread + .command("step") + .description("[DEPRECATED] Use 'thread exec' instead") + .argument("", "Thread ULID") + .allowUnknownOption() + .action(() => { + process.stderr.write(`Error: Command 'thread step' has been removed. +Use 'thread exec' instead. + +For more information, see: uwf help thread exec +`); + process.exit(1); + }); + +thread + .command("steps") + .description("[DEPRECATED] Use 'step list' instead") + .argument("", "Thread ULID") + .action(() => { + process.stderr.write(`Error: Command 'thread steps' has been removed. +Use 'step list' instead. + +For more information, see: uwf help step list +`); + process.exit(1); + }); + +thread + .command("step-details") + .description("[DEPRECATED] Use 'step show' instead") + .argument("", "Step hash") + .action(() => { + process.stderr.write(`Error: Command 'thread step-details' has been removed. +Use 'step show' instead. + +For more information, see: uwf help step show +`); + process.exit(1); + }); + +thread + .command("fork") + .description("[DEPRECATED] Use 'step fork' instead") + .argument("", "Step hash") + .action(() => { + process.stderr.write(`Error: Command 'thread fork' has been removed. +Use 'step fork' instead. + +For more information, see: uwf help step fork +`); + process.exit(1); + }); + +thread + .command("kill") + .description("[DEPRECATED] Use 'thread stop' or 'thread cancel' instead") + .argument("", "Thread ULID") + .action(() => { + process.stderr.write(`Error: Command 'thread kill' has been removed. +Use 'thread stop' to stop background execution (keep thread active), +or 'thread cancel' to cancel and archive the thread. + +For more information, see: + uwf help thread stop + uwf help thread cancel +`); + process.exit(1); + }); + +thread + .command("running") + .description("[DEPRECATED] Use 'thread list --status running' instead") + .action(() => { + process.stderr.write(`Error: Command 'thread running' has been removed. +Use 'thread list --status running' instead. + +For more information, see: uwf help thread list +`); + process.exit(1); + }); + const skill = program.command("skill").description("Built-in skill references for agents"); skill