xiaoju
e29d1bf345
- Align REST API contracts for Dashboard (threads list, detail, SSE) - Add content resolution from CAS in thread show + API responses - Rename dataWatcher → threadsJsonWatcher in SSE routes - Update docs (CLAUDE.md, architecture.md, skill.ts) to reflect CAS storage - Zero .data.jsonl code paths in production code - All 166 tests pass, bun run check clean Refs #155, closes #160 小橘 <xiaoju@shazhou.work>
72 lines
3.0 KiB
Markdown
72 lines
3.0 KiB
Markdown
# @uncaged/workflow
|
|
|
|
A workflow engine that executes single-file ESM bundles. Each workflow is a self-contained `.esm.js` file identified by its XXH64 hash (Crockford Base32).
|
|
|
|
## Core Concepts
|
|
|
|
| Concept | Description |
|
|
|---------|-------------|
|
|
| **Workflow** | A single-file ESM module exporting `run` (workflow function) and `descriptor` (metadata). Identified by its XXH64 hash. |
|
|
| **Bundle** | The physical `.esm.js` file stored in `~/.uncaged/workflow/bundles/`. |
|
|
| **Thread** | A single execution of a workflow, identified by a ULID. CAS-backed chain plus `threads.json` / `history/*.jsonl`; `.info.jsonl` for debug logs. |
|
|
| **Role** | A named actor within a workflow. Each role produces output with typed `meta`. Roles live inside template packages (`src/roles/`). |
|
|
| **Registry** | `workflow.yaml` — maps workflow names to current/historical bundle hashes. |
|
|
| **CAS** | Content-Addressed Storage — bundles are immutable and addressed by hash. |
|
|
|
|
## Monorepo Packages
|
|
|
|
```
|
|
packages/
|
|
workflow/ # @uncaged/workflow — core lib (types, engine, hash, ULID, registry)
|
|
cli-workflow/ # @uncaged/cli-workflow — CLI (`uncaged-workflow` command)
|
|
workflow-template-develop/ # @uncaged/workflow-template-develop — develop workflow template (includes roles)
|
|
workflow-template-solve-issue/ # @uncaged/workflow-template-solve-issue — solve-issue workflow template (includes roles)
|
|
workflow-agent-hermes/ # @uncaged/workflow-agent-hermes — Hermes agent adapter
|
|
workflow-agent-cursor/ # @uncaged/workflow-agent-cursor — Cursor agent adapter
|
|
workflow-agent-llm/ # @uncaged/workflow-agent-llm — LLM agent adapter
|
|
workflow-util-agent/ # @uncaged/workflow-util-agent — agent utilities (buildAgentPrompt, spawnCli)
|
|
```
|
|
|
|
Managed with **bun workspace** using the `workspace:*` protocol.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# Install dependencies
|
|
bun install
|
|
|
|
# Build all packages
|
|
bun run build
|
|
|
|
# Register a workflow bundle
|
|
uncaged-workflow workflow add solve-issue dist/packages/workflow-template-solve-issue/solve-issue.esm.js
|
|
|
|
# Run a workflow
|
|
uncaged-workflow run solve-issue --prompt "Fix bug #42"
|
|
```
|
|
|
|
## CLI Usage
|
|
|
|
```bash
|
|
uncaged-workflow # Print full command usage (exits with status 1)
|
|
uncaged-workflow workflow list # List registered workflows
|
|
uncaged-workflow run <name> # Start a workflow thread
|
|
uncaged-workflow thread list # List all threads
|
|
uncaged-workflow thread show <id> # Inspect a thread
|
|
uncaged-workflow skill # Agent-consumable reference docs
|
|
```
|
|
|
|
Run `uncaged-workflow` with no arguments to print usage, or `uncaged-workflow skill cli` for the full CLI skill reference.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
bun run check # Biome lint + format check
|
|
bun run format # Auto-format with Biome
|
|
bun test # Run tests
|
|
```
|
|
|
|
## Architecture
|
|
|
|
See [docs/architecture.md](docs/architecture.md) for the full design — three-phase engine loop, bundle contract, storage layout, and design decisions.
|