From a5c09adae6b85c23bba91d0f7746cb76c1f026e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=98=9F=E6=9C=88?= Date: Fri, 8 May 2026 10:17:40 +0800 Subject: [PATCH] docs: add README.md to all 8 packages Each README includes: package description, install instructions, usage example, API overview, and (for templates) role/moderator flow. Packages documented: - @uncaged/workflow (core) - @uncaged/cli-workflow (CLI) - @uncaged/workflow-agent-cursor - @uncaged/workflow-agent-hermes - @uncaged/workflow-agent-llm - @uncaged/workflow-template-develop - @uncaged/workflow-template-solve-issue - @uncaged/workflow-util-agent --- packages/cli-workflow/README.md | 76 +++++++++++++++++++ packages/workflow-agent-cursor/README.md | 36 +++++++++ packages/workflow-agent-hermes/README.md | 35 +++++++++ packages/workflow-agent-llm/README.md | 34 +++++++++ packages/workflow-template-develop/README.md | 53 +++++++++++++ .../workflow-template-solve-issue/README.md | 48 ++++++++++++ packages/workflow-util-agent/README.md | 34 +++++++++ packages/workflow/README.md | 36 +++++++++ 8 files changed, 352 insertions(+) create mode 100644 packages/cli-workflow/README.md create mode 100644 packages/workflow-agent-cursor/README.md create mode 100644 packages/workflow-agent-hermes/README.md create mode 100644 packages/workflow-agent-llm/README.md create mode 100644 packages/workflow-template-develop/README.md create mode 100644 packages/workflow-template-solve-issue/README.md create mode 100644 packages/workflow-util-agent/README.md create mode 100644 packages/workflow/README.md diff --git a/packages/cli-workflow/README.md b/packages/cli-workflow/README.md new file mode 100644 index 0000000..c07eb43 --- /dev/null +++ b/packages/cli-workflow/README.md @@ -0,0 +1,76 @@ +# @uncaged/cli-workflow + +Command-line interface for the Uncaged workflow engine (`uncaged-workflow`). + +The CLI reads and writes the workflow registry, starts and inspects threads, manages CAS blobs, and prints agent-oriented reference docs via `skill`. It uses the same storage layout as `@uncaged/workflow` (default `~/.uncaged/workflow`). + +## Install + +```bash +bun add @uncaged/cli-workflow +``` + +In this monorepo: `"@uncaged/cli-workflow": "workspace:*"`. Depends on `"@uncaged/workflow": "workspace:*"`. + +## Usage + +```bash +uncaged-workflow workflow list +uncaged-workflow run --prompt "Your task" +uncaged-workflow thread show +uncaged-workflow skill +``` + +Invoking the CLI with no command (or from this repo: `bun packages/cli-workflow/src/cli.ts`) prints: + +``` +uncaged-workflow — workflow engine CLI + +Workflow registry: + workflow add [--types ] Register a workflow bundle in the registry + workflow list List all registered workflows + workflow show Show details of a registered workflow + workflow rm Remove a workflow from the registry + workflow history Show version history of a workflow + workflow rollback [hash] Rollback a workflow to a previous version + +Thread execution: + thread run [--prompt ] [--max-rounds N] Start a new thread executing a workflow + thread list [name] List threads, optionally filtered by workflow name + thread show Show thread details and state + thread rm Remove a thread + thread fork [--from-role ] Fork a thread, optionally from a specific role + thread ps List running threads + thread kill Kill a running thread + thread live | --latest [--debug] [--role ] Attach to a thread and stream output live + thread pause Pause a running thread + thread resume Resume a paused thread + +Content-addressable storage: + cas get Retrieve content by hash from CAS + cas put Store content in CAS, prints hash + cas list List all hashes in CAS + cas rm Remove a CAS entry by hash + cas gc Garbage-collect unreferenced CAS entries + +Development: + init workspace Initialize a new workflow workspace + init template Initialize a new workflow template + +Shortcuts: + run [...] → thread run + live [...] → thread live + +Reference: + skill [topic] Agent-consumable docs (cli, develop, author) + +Use --help for subcommand details. + +Environment variables: + WORKFLOW_STORAGE_ROOT Override storage directory (default: ~/.uncaged/workflow) + UNCAGED_WORKFLOW_STORAGE_ROOT Internal override (takes priority over WORKFLOW_STORAGE_ROOT) +``` + +## API overview + +This package is bin-only; programmatic use is via `@uncaged/workflow`. Entry: `src/cli.ts` → `runCli` in `src/cli-dispatch.js`. diff --git a/packages/workflow-agent-cursor/README.md b/packages/workflow-agent-cursor/README.md new file mode 100644 index 0000000..ebd8f2f --- /dev/null +++ b/packages/workflow-agent-cursor/README.md @@ -0,0 +1,36 @@ +# @uncaged/workflow-agent-cursor + +`AgentFn` adapter that runs the `cursor-agent` CLI against a workspace path derived from the thread. + +The agent builds a full prompt (system + task + step history via `@uncaged/workflow-util-agent`), extracts the absolute workspace path with your `extract` + Zod schema, then spawns `cursor-agent` with `--workspace`, model, and non-interactive flags. + +## Install + +```bash +bun add @uncaged/workflow-agent-cursor @uncaged/workflow @uncaged/workflow-util-agent zod +``` + +In this monorepo: `"@uncaged/workflow-agent-cursor": "workspace:*"` plus `workspace:*` for `@uncaged/workflow` and `@uncaged/workflow-util-agent`. + +## Usage + +```typescript +import { createCursorAgent } from "@uncaged/workflow-agent-cursor"; + +const agent = createCursorAgent({ + model: null, // null → "auto" + timeout: 0, // ms; 0 = no limit (spawnCli timeout disabled) + extract: myExtractFn, +}); +``` + +## API overview + +| Export | Description | +|--------|-------------| +| `createCursorAgent(config)` | Returns `AgentFn` that runs `cursor-agent` with `buildAgentPrompt(ctx)` | +| `CursorAgentConfig` | `model`, `timeout`, `extract` (must supply workspace path) | +| `validateCursorAgentConfig` | Config validation result | +| `buildAgentPrompt` | Re-exported from `@uncaged/workflow-util-agent` | + +Requires `cursor-agent` on `PATH` at runtime. diff --git a/packages/workflow-agent-hermes/README.md b/packages/workflow-agent-hermes/README.md new file mode 100644 index 0000000..38f35c9 --- /dev/null +++ b/packages/workflow-agent-hermes/README.md @@ -0,0 +1,35 @@ +# @uncaged/workflow-agent-hermes + +`AgentFn` adapter that runs the `hermes` CLI in non-interactive `chat` mode (Nerve-style flags: `-q`, `--yolo`, `--quiet`, bounded `--max-turns`). + +The agent composes the same thread-aware prompt as other CLI-backed agents via `buildAgentPrompt` from `@uncaged/workflow-util-agent`, then spawns `hermes` and returns stdout on success. + +## Install + +```bash +bun add @uncaged/workflow-agent-hermes @uncaged/workflow @uncaged/workflow-util-agent +``` + +In this monorepo: use `workspace:*` for all three `@uncaged/*` packages. + +## Usage + +```typescript +import { createHermesAgent } from "@uncaged/workflow-agent-hermes"; + +const agent = createHermesAgent({ + model: "your-model", // or null to omit --model + timeout: 600_000, // ms, or null for no timeout +}); +``` + +## API overview + +| Export | Description | +|--------|-------------| +| `createHermesAgent(config)` | Returns `AgentFn` wrapping `hermes chat -q ...` | +| `HermesAgentConfig` | `model`, `timeout` | +| `validateHermesAgentConfig` | Config validation result | +| `buildAgentPrompt` | Re-exported from `@uncaged/workflow-util-agent` | + +Requires `hermes` on `PATH` at runtime. diff --git a/packages/workflow-agent-llm/README.md b/packages/workflow-agent-llm/README.md new file mode 100644 index 0000000..96ff225 --- /dev/null +++ b/packages/workflow-agent-llm/README.md @@ -0,0 +1,34 @@ +# @uncaged/workflow-agent-llm + +`AgentFn` adapter that calls an OpenAI-compatible `POST /chat/completions` endpoint using `@uncaged/workflow`’s `LlmProvider` (base URL, API key, model). + +Single-turn: system text is the current role’s `systemPrompt`, user text is the thread’s initial prompt (`ctx.start.content`). Errors from HTTP, JSON, or empty choices are thrown as `Error` with a JSON payload string. + +## Install + +```bash +bun add @uncaged/workflow-agent-llm @uncaged/workflow +``` + +In this monorepo: `"@uncaged/workflow-agent-llm": "workspace:*"`, `"@uncaged/workflow": "workspace:*"`. + +## Usage + +```typescript +import { createLlmAdapter } from "@uncaged/workflow-agent-llm"; + +const agent = createLlmAdapter({ + baseUrl: "https://api.openai.com/v1", + apiKey: process.env.OPENAI_API_KEY!, + model: "gpt-4.1-mini", +}); +``` + +## API overview + +| Export | Description | +|--------|-------------| +| `createLlmAdapter(provider)` | `LlmProvider` → `AgentFn` | +| `chatCompletionText({ provider, messages })` | Low-level `Result` helper | +| `LlmMessage` | `{ role: "system" \| "user" \| "assistant"; content: string }` | +| `LlmChatError` | Discriminated error kinds for failed completions | diff --git a/packages/workflow-template-develop/README.md b/packages/workflow-template-develop/README.md new file mode 100644 index 0000000..d43bf56 --- /dev/null +++ b/packages/workflow-template-develop/README.md @@ -0,0 +1,53 @@ +# @uncaged/workflow-template-develop + +Reference **develop** workflow template: plan phases, implement in a loop, review, test, then commit. + +Export a `WorkflowDefinition` and `createDevelopRun` so a host can bind agents/LLM and run the same graph the bundled `.esm.js` would use. Use `buildDevelopDescriptor()` when assembling `descriptor` metadata for a bundle. + +## Install + +```bash +bun add @uncaged/workflow-template-develop @uncaged/workflow zod +``` + +In this monorepo: `workspace:*` for `@uncaged/workflow-template-develop` and `@uncaged/workflow`. + +## Usage + +```typescript +import { createDevelopRun, developWorkflowDefinition } from "@uncaged/workflow-template-develop"; + +const run = createDevelopRun(binding, extract, llmProvider); +// run(...) executes the develop moderator graph with your AgentBinding +``` + +## Roles + +| Role | Purpose | +|------|---------| +| **planner** | Break work into ordered phases (hashes) | +| **coder** | Implement current phase; repeats until phases complete or limits hit | +| **reviewer** | Code review gate (`approved` vs send back to coder) | +| **tester** | Verify via tests/build/lint (`passed` vs send back to coder) | +| **committer** | Final commit step | + +Also exported: role factories/meta schemas (`plannerRole`, `coderRole`, …), `DevelopMeta`, `developRoles`. + +## Moderator flow + +1. **Start** → `planner` +2. After **planner** → `coder` +3. After **coder** → if all planned phases are done (or last phase completed) → `reviewer`; else `coder` again, until `maxRounds` then `END` +4. After **reviewer** → if approved → `tester`; else `coder` (or `END` if out of rounds) +5. After **tester** → if passed → `committer`; else `coder` (or `END` if out of rounds) +6. After **committer** → `END` + +## API overview + +| Export | Description | +|--------|-------------| +| `createDevelopRun` | `createWorkflow(developWorkflowDefinition, …)` factory | +| `developWorkflowDefinition` | `description`, `roles`, `developModerator` | +| `developModerator` | `Moderator` | +| `buildDevelopDescriptor` | `buildDescriptor({ … })` for bundle metadata | +| `DEVELOP_WORKFLOW_DESCRIPTION` | Human-readable one-liner | diff --git a/packages/workflow-template-solve-issue/README.md b/packages/workflow-template-solve-issue/README.md new file mode 100644 index 0000000..29ed002 --- /dev/null +++ b/packages/workflow-template-solve-issue/README.md @@ -0,0 +1,48 @@ +# @uncaged/workflow-template-solve-issue + +Reference **solve-issue** workflow template: prepare a repo, delegate implementation to the **develop** workflow, then submit (e.g. open a PR). + +`createSolveIssueRun` wires the `developer` role to `workflowAsAgent("develop")` by default; `binding.overrides.developer` wins if you pass one (for tests or custom hosts). + +## Install + +```bash +bun add @uncaged/workflow-template-solve-issue @uncaged/workflow zod +``` + +In this monorepo: `workspace:*` for this package and `@uncaged/workflow`. + +## Usage + +```typescript +import { createSolveIssueRun, solveIssueWorkflowDefinition } from "@uncaged/workflow-template-solve-issue"; + +const run = createSolveIssueRun(binding, extract, llmProvider); +``` + +## Roles + +| Role | Purpose | +|------|---------| +| **preparer** | Set up context / repo state for the issue | +| **developer** | Implementation; default runs the registered `develop` workflow as a sub-agent | +| **submitter** | Finalize and submit the outcome (e.g. PR) | + +Also exported: `preparerRole`, `developerRole`, `submitterRole` and their Zod meta schemas, `SolveIssueMeta`, `solveIssueRoles`. + +## Moderator flow + +1. **Start** → `preparer` +2. After **preparer** → `developer` +3. After **developer** → `submitter` +4. After **submitter** → `END` + +## API overview + +| Export | Description | +|--------|-------------| +| `createSolveIssueRun` | Merges `developer` override with `workflowAsAgent("develop")`, then `createWorkflow` | +| `solveIssueWorkflowDefinition` | `description`, `roles`, `solveIssueModerator` | +| `solveIssueModerator` | Linear `Moderator` | +| `buildSolveIssueDescriptor` | Descriptor helper for bundles | +| `SOLVE_ISSUE_WORKFLOW_DESCRIPTION` | Human-readable one-liner | diff --git a/packages/workflow-util-agent/README.md b/packages/workflow-util-agent/README.md new file mode 100644 index 0000000..0ddde8e --- /dev/null +++ b/packages/workflow-util-agent/README.md @@ -0,0 +1,34 @@ +# @uncaged/workflow-util-agent + +Shared helpers for CLI-backed workflow agents: assemble prompts from thread context and spawn subprocesses with timeouts. + +Used by `@uncaged/workflow-agent-cursor` and `@uncaged/workflow-agent-hermes`. Depends on `@uncaged/workflow` for CAS reads (`getContentMerklePayload`) and `Result` typing. + +## Install + +```bash +bun add @uncaged/workflow-util-agent @uncaged/workflow +``` + +In this monorepo: `workspace:*` for both packages. + +## Usage + +```typescript +import { buildAgentPrompt, spawnCli } from "@uncaged/workflow-util-agent"; + +const prompt = await buildAgentPrompt(agentContext); +const result = await spawnCli("my-cli", ["--json"], { cwd: "/tmp", timeoutMs: 60_000 }); +if (!result.ok) { /* handle SpawnCliError */ } +const stdout = result.value; +``` + +## API overview + +| Export | Description | +|--------|-------------| +| `buildAgentPrompt(ctx)` | System prompt + task + prior step summaries + latest body from CAS; appends `uncaged-workflow thread ` tool hint | +| `spawnCli(cmd, args, { cwd, timeoutMs })` | `Promise>`; captures stdout, non-zero exit and spawn failures as `err` | +| `SpawnCliConfig` | `cwd: string \| null`, `timeoutMs: number \| null` | +| `SpawnCliError` | `non_zero_exit` \| `timeout` \| `spawn_failed` | +| `SpawnCliResult` | Alias for `Result` | diff --git a/packages/workflow/README.md b/packages/workflow/README.md new file mode 100644 index 0000000..517b0a8 --- /dev/null +++ b/packages/workflow/README.md @@ -0,0 +1,36 @@ +# @uncaged/workflow + +Core workflow engine: registry, CAS, thread execution, bundle validation, and role/workflow types. + +This package implements the three-phase engine loop that runs single-file ESM workflow bundles (each exports `run` and `descriptor`). It persists threads under `~/.uncaged/workflow/` by default and hashes bundles with XXH64 (Crockford Base32). See the repo root [README](../../README.md) for workflow, bundle, thread, role, and registry concepts. + +## Install + +```bash +bun add @uncaged/workflow zod +``` + +In this monorepo, depend with `"@uncaged/workflow": "workspace:*"`. `zod` is a peer dependency (used by bundle/shape validation at the integration boundary). + +## Usage + +```typescript +import { createWorkflow, readWorkflowRegistry, executeThread } from "@uncaged/workflow"; +// Wire a WorkflowDefinition + AgentBinding + extract + optional LlmProvider into createWorkflow, +// then run the returned WorkflowFn inside your host (or use executeThread for disk-backed runs). +``` + +## API overview + +| Area | Exports (representative) | +|------|--------------------------| +| **Types** | `WorkflowDefinition`, `WorkflowFn`, `AgentFn`, `AgentBinding`, `Moderator`, `RoleDefinition`, `ThreadContext`, `LlmProvider`, `Result` shape via `ok` / `err`, `START` / `END` | +| **Bundle** | `buildDescriptor`, `extractBundleExports`, `validateWorkflowBundle`, `validateWorkflowDescriptor`, `WorkflowDescriptor`, `WorkflowRoleDescriptor` | +| **Registry** | `readWorkflowRegistry`, `writeWorkflowRegistry`, `registerWorkflowVersion`, `workflowRegistryPath`, YAML helpers | +| **CAS** | `createCasStore`, `createThreadCas`, Merkle helpers (`putStepMerkleNode`, `getContentMerklePayload`, …), `hashWorkflowBundleBytes` | +| **Engine** | `createWorkflow`, `executeThread`, `parseThreadDataJsonl`, fork helpers, `garbageCollectCas` | +| **Extract / LLM tools** | `llmExtract`, `reactExtract`, `createExtract`, `getExtractProvider` | +| **Agent bridge** | `workflowAsAgent` — expose a registered workflow as an agent-backed role | +| **Utilities** | `createLogger`, ULID / Crockford Base32 codecs, `getDefaultWorkflowStorageRoot`, paths | + +Full surface is re-exported from `src/index.ts`.