docs(cli): add deprecation handlers and update documentation (#463)
Complete the CLI refactoring with deprecation error handlers, updated help text, and comprehensive migration guide. ## Changes ### Deprecation Handlers Add error handlers for all removed commands with helpful migration messages: - `workflow put` → suggests `workflow add` - `thread step` → suggests `thread exec` - `thread steps` → suggests `step list` - `thread step-details` → suggests `step show` - `thread fork` → suggests `step fork` - `thread kill` → suggests `thread stop` or `thread cancel` - `thread running` → suggests `thread list --status running` Error messages follow the format: ``` Error: Command 'X' has been removed. Use 'Y' instead. For more information, see: uwf help Y ``` ### Help Documentation Updated CLI help text to explain four-layer architecture: - Main help shows architecture diagram with Chinese labels - Command group descriptions reference layers: - `workflow` → "Workflow definitions (layer 1: templates)" - `thread` → "Thread execution (layer 2: instances)" - `step` → "Step results (layer 3: single cycle)" - Deprecated commands appear in help with [DEPRECATED] tag ### README Updates Comprehensive documentation updates: - Added "Four-Layer Architecture" section with diagram - Updated all command tables with new command names - Added complete migration guide with: - Renamed commands table - Merged commands table - Split commands table - Moved commands table - Example deprecation error output - Updated "Internal Structure" to show new step.ts module ## Testing - ✅ All 124 tests pass - ✅ Build completes successfully - ✅ Deprecation handlers tested manually - ✅ Help output verified for main, thread, and step commands Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -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 <workflow> -p <prompt>` | Create a thread without executing |
|
||||
| `uwf thread step <thread-id> [--agent <cmd>] [-c <count>]` | Execute one or more moderator→agent→extract cycles |
|
||||
| `uwf thread exec <thread-id> [--agent <cmd>] [-c <count>] [--background]` | Execute one or more moderator→agent→extract cycles |
|
||||
| `uwf thread show <thread-id>` | Show thread head pointer |
|
||||
| `uwf thread list [--all]` | List active threads (`--all` includes archived) |
|
||||
| `uwf thread steps <thread-id>` | List all steps chronologically |
|
||||
| `uwf thread list [--status <idle\|running\|completed>]` | List threads, optionally filtered by status |
|
||||
| `uwf thread read <thread-id> [--quota N] [--before <hash>] [--start]` | Render thread as readable markdown |
|
||||
| `uwf thread fork <step-hash>` | Fork from a specific step |
|
||||
| `uwf thread step-details <step-hash>` | Dump full detail node as YAML |
|
||||
| `uwf thread kill <thread-id>` | Terminate and archive |
|
||||
| `uwf thread stop <thread-id>` | Stop background execution (keep thread active) |
|
||||
| `uwf thread cancel <thread-id>` | 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 <file.yaml>` | Register a workflow from YAML |
|
||||
| `uwf step list <thread-id>` | List all steps in a thread chronologically |
|
||||
| `uwf step show <step-hash>` | Show step metadata and frontmatter |
|
||||
| `uwf step read <step-hash> [--before N]` | Read step output as markdown |
|
||||
| `uwf step fork <step-hash>` | 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 <file.yaml>` | Register a workflow from YAML |
|
||||
| `uwf workflow show <name-or-hash>` | 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 <id>] [--process <pid>] [--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
|
||||
|
||||
Reference in New Issue
Block a user