diff --git a/CLAUDE.md b/CLAUDE.md index 5d1f6a1..0cc8174 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,12 +9,12 @@ This monorepo implements a stateless workflow engine driven by a single-step CLI | Concept | What it is | |---------|-----------| | **Workflow** | A YAML definition (`WorkflowPayload`) with roles, status-based routing, and a directed graph. Stored as a CAS node, identified by its XXH64 hash. | -| **Thread** | A single execution of a workflow, identified by a ULID. State is an immutable CAS chain; active threads indexed in `threads.yaml`; completed threads in `history.jsonl`. | +| **Thread** | A single execution of a workflow, identified by a ULID. State is an immutable CAS chain; active threads indexed as `@uwf/thread/*` variables; completed threads as `@uwf/history/*` variables. | | **Role** | A named actor within a workflow. Each role has a system prompt and a JSON Schema `outputSchema`. | | **Moderator** | Status-based graph evaluator — determines the next role (or `$END`) with zero LLM cost. | | **Agent** | An external CLI command (`uwf-hermes`, etc.) spawned by `uwf thread step`. Produces frontmatter markdown output. | | **CAS** | Content-Addressed Storage via `@ocas/core` — all workflow definitions, thread nodes, and outputs are immutable CAS nodes. | -| **Registry** | `~/.uwf/registry.yaml` — maps workflow names to current CAS hashes. | +| **Registry** | `@uwf/registry/*` variables in `~/.ocas/variables.db` — maps workflow names to current CAS hashes. | ### Monorepo Structure @@ -274,10 +274,10 @@ examples/solve-issue.yaml — write a workflow YAML definition │ uwf workflow put ▼ ~/.ocas/ — Workflow stored as CAS node (unified CAS store) -~/.uwf/registry.yaml — name → hash mapping updated +~/.ocas/variables.db — @uwf/registry/* variable maps name → hash │ uwf thread start -p "..." ▼ -~/.uwf/threads.yaml — new thread head pointer +~/.ocas/variables.db — @uwf/thread/* variable tracks head pointer │ uwf thread step ▼ moderator → agent → extract — one step per invocation, repeat until $END diff --git a/README.md b/README.md index ef2f8d3..15c64a0 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,9 @@ -# @uncaged/workflow +# United Workforce (uwf) [![CI](https://github.com/shazhou-ww/uncaged-workflow/actions/workflows/ci.yml/badge.svg)](https://github.com/shazhou-ww/uncaged-workflow/actions/workflows/ci.yml) -[![npm](https://img.shields.io/npm/v/@uncaged/cli-workflow?label=%40uncaged%2Fcli-workflow)](https://www.npmjs.com/package/@uncaged/cli-workflow) -[![npm](https://img.shields.io/npm/v/@uncaged/workflow-protocol?label=%40uncaged%2Fworkflow-protocol)](https://www.npmjs.com/package/@uncaged/workflow-protocol) -[![npm](https://img.shields.io/npm/v/@uncaged/workflow-util-agent?label=%40uncaged%2Fworkflow-util-agent)](https://www.npmjs.com/package/@uncaged/workflow-util-agent) +[![npm](https://img.shields.io/npm/v/@united-workforce/cli?label=%40united-workforce%2Fcli)](https://www.npmjs.com/package/@united-workforce/cli) +[![npm](https://img.shields.io/npm/v/@united-workforce/protocol?label=%40united-workforce%2Fprotocol)](https://www.npmjs.com/package/@united-workforce/protocol) +[![npm](https://img.shields.io/npm/v/@united-workforce/util-agent?label=%40united-workforce%2Futil-agent)](https://www.npmjs.com/package/@united-workforce/util-agent) A stateless workflow engine driven by a single-step CLI. Workflows are YAML definitions with roles, status-based routing, and a directed graph. Threads are immutable CAS-linked chains — each `uwf thread step` runs one moderator→agent→extract cycle and exits. @@ -11,14 +11,14 @@ A stateless workflow engine driven by a single-step CLI. Workflows are YAML defi This monorepo implements **uwf**, a workflow engine with no long-running daemon. You register YAML workflow definitions in a content-addressed store (CAS), start a thread with an initial prompt, then invoke `uwf thread step` repeatedly until the moderator routes to `$END`. Each step is a complete process: the moderator evaluates status-based routing to pick the next role, an external agent CLI produces frontmatter markdown output, and an extract pipeline validates or structures that output against the role's JSON Schema. -Workflow state lives entirely on disk under `~/.uncaged/workflow/`: CAS nodes for definitions and step payloads, `registry.yaml` for workflow name→hash mappings, and `threads.yaml` for active thread head pointers. Completed threads are archived to `history.jsonl`. Because there is no server process, workflows are easy to debug, fork, and inspect with ordinary CLI tools. +Workflow state lives entirely on disk: CAS nodes under `~/.ocas/` for definitions and step payloads, and `~/.ocas/variables.db` for all metadata (`@uwf/registry/*` for workflow name→hash mappings, `@uwf/thread/*` for active thread head pointers, `@uwf/history/*` for completed/cancelled threads). Config is at `~/.uwf/config.yaml`. Because there is no server process, workflows are easy to debug, fork, and inspect with ordinary CLI tools. Agents are pluggable CLI binaries (`uwf-hermes`, `uwf-builtin`, `uwf-claude-code`, or custom commands). The engine spawns the configured agent with `` and ``, sets `UWF_EDGE_PROMPT` from the graph transition, and captures both the agent's markdown output and a detail CAS node for session replay. ## Install ```bash -npm install -g @uncaged/cli-workflow +npm install -g @united-workforce/cli ``` Requires [Bun](https://bun.sh/) runtime (used internally for TypeScript execution). @@ -75,14 +75,14 @@ See [docs/architecture.md](docs/architecture.md) for the full design — three-p | Package | npm | Description | Type | README | |---------|-----|-------------|------|--------| -| `cli-workflow` | `@uncaged/cli-workflow` | `uwf` CLI — thread lifecycle, workflow registry, CAS inspection, setup | cli | [README](packages/cli-workflow/README.md) | -| `workflow-protocol` | `@uncaged/workflow-protocol` | Shared TypeScript types and JSON Schema constants | lib | [README](packages/workflow-protocol/README.md) | -| `workflow-util-agent` | `@uncaged/workflow-util-agent` | `createAgent` factory, context builder, extract pipeline | lib | [README](packages/workflow-util-agent/README.md) | -| `workflow-util` | `@uncaged/workflow-util` | Crockford Base32, ULID, logger, frontmatter parsing, storage paths | lib | [README](packages/workflow-util/README.md) | -| `workflow-agent-hermes` | `@uncaged/workflow-agent-hermes` | `uwf-hermes` — spawns Hermes chat via ACP | agent | [README](packages/workflow-agent-hermes/README.md) | -| `workflow-agent-builtin` | `@uncaged/workflow-agent-builtin` | `uwf-builtin` — built-in LLM agent with file/shell tools | agent | [README](packages/workflow-agent-builtin/README.md) | -| `workflow-agent-claude-code` | `@uncaged/workflow-agent-claude-code` | `uwf-claude-code` — spawns Claude Code CLI | agent | [README](packages/workflow-agent-claude-code/README.md) | -| `workflow-dashboard` | `@uncaged/workflow-dashboard` | Web graph editor for workflow YAML (private, alpha) | app | [README](packages/workflow-dashboard/README.md) | +| `cli-workflow` | `@united-workforce/cli` | `uwf` CLI — thread lifecycle, workflow registry, CAS inspection, setup | cli | [README](packages/cli-workflow/README.md) | +| `workflow-protocol` | `@united-workforce/protocol` | Shared TypeScript types and JSON Schema constants | lib | [README](packages/workflow-protocol/README.md) | +| `workflow-util-agent` | `@united-workforce/util-agent` | `createAgent` factory, context builder, extract pipeline | lib | [README](packages/workflow-util-agent/README.md) | +| `workflow-util` | `@united-workforce/util` | Crockford Base32, ULID, logger, frontmatter parsing, storage paths | lib | [README](packages/workflow-util/README.md) | +| `workflow-agent-hermes` | `@united-workforce/agent-hermes` | `uwf-hermes` — spawns Hermes chat via ACP | agent | [README](packages/workflow-agent-hermes/README.md) | +| `workflow-agent-builtin` | `@united-workforce/agent-builtin` | `uwf-builtin` — built-in LLM agent with file/shell tools | agent | [README](packages/workflow-agent-builtin/README.md) | +| `workflow-agent-claude-code` | `@united-workforce/agent-claude-code` | `uwf-claude-code` — spawns Claude Code CLI | agent | [README](packages/workflow-agent-claude-code/README.md) | +| `workflow-dashboard` | `@united-workforce/dashboard` | Web graph editor for workflow YAML (private, alpha) | app | [README](packages/workflow-dashboard/README.md) | ## CLI Reference @@ -98,7 +98,7 @@ Global options: `-V, --version`, `--format `, `-h, --help`. | **skill** | `cli` — print markdown reference of all uwf commands | | **log** | `list`, `show`, `clean` — process-level debug logs | -Config is stored in `~/.uncaged/workflow/config.yaml`. API keys go in `~/.uncaged/workflow/.env`. +Config is stored in `~/.uwf/config.yaml`. API keys go in `~/.uwf/.env`. Detailed command usage, options, and examples: [packages/cli-workflow/README.md](packages/cli-workflow/README.md). diff --git a/docs/architecture.md b/docs/architecture.md index 8767dd4..d4e5914 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -14,11 +14,11 @@ The implementation lives in **5** active packages under `packages/`, plus two ex | Layer | Package | One-line role | |-------|---------|---------------| -| Contract | `@uncaged/workflow-protocol` → `workflow-protocol` | Shared TypeScript types (`WorkflowPayload`, `StepNodePayload`, `ModeratorContext`, `WorkflowConfig`, etc.). No runtime deps beyond `@ocas/fs`. | -| Shared infra | `@uncaged/workflow-util` → `workflow-util` | Crockford Base32, ULID generation, `createLogger`, frontmatter parsing/validation. | -| Agent framework | `@uncaged/workflow-util-agent` → `workflow-util-agent` | `createAgent` entrypoint factory, context builder, frontmatter fast-path extractor, LLM extract fallback, output format instruction builder. | -| Agent: Hermes | `@uncaged/workflow-agent-hermes` → `workflow-agent-hermes` | `uwf-hermes` CLI binary — spawns `hermes chat`, pipes prompt, captures session detail. | -| CLI | `@uncaged/cli-workflow` → `cli-workflow` | `uwf` binary — thread lifecycle, workflow registry, CAS inspection, setup. Includes status-based graph evaluator in `src/moderator/` (next role or `$END`). | +| Contract | `@united-workforce/protocol` → `workflow-protocol` | Shared TypeScript types (`WorkflowPayload`, `StepNodePayload`, `ModeratorContext`, `WorkflowConfig`, etc.). No runtime deps beyond `@ocas/fs`. | +| Shared infra | `@united-workforce/util` → `workflow-util` | Crockford Base32, ULID generation, `createLogger`, frontmatter parsing/validation. | +| Agent framework | `@united-workforce/util-agent` → `workflow-util-agent` | `createAgent` entrypoint factory, context builder, frontmatter fast-path extractor, LLM extract fallback, output format instruction builder. | +| Agent: Hermes | `@united-workforce/agent-hermes` → `workflow-agent-hermes` | `uwf-hermes` CLI binary — spawns `hermes chat`, pipes prompt, captures session detail. | +| CLI | `@united-workforce/cli` → `cli-workflow` | `uwf` binary — thread lifecycle, workflow registry, CAS inspection, setup. Includes status-based graph evaluator in `src/moderator/` (next role or `$END`). | ### External dependencies @@ -40,19 +40,19 @@ flowchart BT jcasfs["@ocas/fs"] end subgraph L0["Layer 0 — contract"] - protocol["@uncaged/workflow-protocol"] + protocol["@united-workforce/protocol"] end subgraph L1["Layer 1 — shared"] - util["@uncaged/workflow-util"] + util["@united-workforce/util"] end subgraph L2["Layer 2 — agent framework"] - kit["@uncaged/workflow-util-agent"] + kit["@united-workforce/util-agent"] end subgraph L3["Layer 3 — agent implementations"] - hermes["@uncaged/workflow-agent-hermes"] + hermes["@united-workforce/agent-hermes"] end subgraph L4["Layer 4 — CLI"] - cli["@uncaged/cli-workflow"] + cli["@united-workforce/cli"] end protocol --> jcasfs util --> protocol diff --git a/docs/builtin-agent-research.md b/docs/builtin-agent-research.md index 96c6f1a..936f7c8 100644 --- a/docs/builtin-agent-research.md +++ b/docs/builtin-agent-research.md @@ -597,7 +597,7 @@ flowchart TB Step --> Spawn end - subgraph builtin_pkg ["@uncaged/workflow-agent-builtin"] + subgraph builtin_pkg ["@united-workforce/agent-builtin"] Main["createBuiltinAgent() = createAgent({...})"] Prompt["buildBuiltinPrompt(ctx)"] Loop["runBuiltinLoop(provider, messages, tools)"] @@ -762,7 +762,7 @@ type ToolContext = { | 配置 | `config.yaml` 增加 `agents.builtin`;`uwf setup` 可选默认 agent | | 存储 | `resolveStorageRoot()` + `loadWorkflowConfig` + `getEnvPath`;与 Hermes 相同,**不**改 `threads.yaml` 写入方 | | 测试 | 单元测试:tool handlers、prompt 组装、mock LLM tool loop;集成测试:临时 storage root + fake provider | -| 发布 | 新包 `@uncaged/workflow-agent-builtin`,bin `uwf-builtin`,加入 `scripts/publish-all.mjs` | +| 发布 | 新包 `@united-workforce/agent-builtin`,bin `uwf-builtin`,加入 `scripts/publish-all.mjs` | **明确不做**: diff --git a/docs/wf-stateless-design.md b/docs/wf-stateless-design.md index b6b05ee..278a7c5 100644 --- a/docs/wf-stateless-design.md +++ b/docs/wf-stateless-design.md @@ -341,11 +341,11 @@ OPENROUTER_API_KEY=sk-or-... ``` packages/ -├── cli-workflow/ # @uncaged/cli-workflow — uwf CLI(thread/workflow 命令,含 src/moderator/) -├── workflow-util-agent/ # @uncaged/workflow-util-agent — Agent CLI 框架(含 extractor) -├── workflow-agent-hermes/ # @uncaged/workflow-agent-hermes — uwf-hermes CLI -├── workflow-agent-cursor/ # @uncaged/workflow-agent-cursor — uwf-cursor CLI -└── workflow-protocol/ # @uncaged/workflow-protocol — 共享类型定义 +├── cli-workflow/ # @united-workforce/cli — uwf CLI(thread/workflow 命令,含 src/moderator/) +├── workflow-util-agent/ # @united-workforce/util-agent — Agent CLI 框架(含 extractor) +├── workflow-agent-hermes/ # @united-workforce/agent-hermes — uwf-hermes CLI +├── workflow-agent-cursor/ # @united-workforce/agent-cursor — uwf-cursor CLI +└── workflow-protocol/ # @united-workforce/protocol — 共享类型定义 ``` **外部依赖:**