From f11571856431901fda127957aaa45514114d2623 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=B0=8F=E6=A9=98?= Date: Sun, 24 May 2026 11:41:02 +0000 Subject: [PATCH] chore: cleanup dead code and update CLI docs - Remove cmdThreadRunning dead code (CLI uses --status running now) - Remove step read from README (command not registered) - Update cli-reference.ts to reflect new four-layer commands Refs #463 --- packages/cli-workflow/README.md | 4 +-- packages/cli-workflow/src/commands/thread.ts | 13 +------- packages/workflow-util/src/cli-reference.ts | 32 ++++++++++++-------- 3 files changed, 21 insertions(+), 28 deletions(-) diff --git a/packages/cli-workflow/README.md b/packages/cli-workflow/README.md index 32b7e7a..2ca507c 100644 --- a/packages/cli-workflow/README.md +++ b/packages/cli-workflow/README.md @@ -16,7 +16,7 @@ workflow → thread → step → turn - **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) +- **Turn** (layer 4): Agent-internal interactions (use `step show` or CAS to inspect) This package has no library `src/index.ts` — it is consumed as a CLI binary only. @@ -72,7 +72,6 @@ uwf thread stop 01ARZ3NDEKTSV4RRFFQ69G5FAV |---------|-------------| | `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: @@ -80,7 +79,6 @@ Examples: ```bash uwf step list 01ARZ3NDEKTSV4RRFFQ69G5FAV uwf step show 32GCDE899RRQ3 -uwf step read 32GCDE899RRQ3 --before 3 uwf step fork 32GCDE899RRQ3 ``` diff --git a/packages/cli-workflow/src/commands/thread.ts b/packages/cli-workflow/src/commands/thread.ts index 556801f..b3fe01a 100644 --- a/packages/cli-workflow/src/commands/thread.ts +++ b/packages/cli-workflow/src/commands/thread.ts @@ -9,7 +9,6 @@ import type { AgentConfig, CasRef, ModeratorContext, - RunningThreadsOutput, StartNodePayload, StartOutput, StepContext, @@ -23,12 +22,7 @@ import type { import { createProcessLogger, generateUlid, type ProcessLogger } from "@uncaged/workflow-util"; import { config as loadDotenv } from "dotenv"; import { parse, stringify } from "yaml"; -import { - createMarker, - deleteMarker, - isThreadRunning, - listRunningThreads, -} from "../background/index.js"; +import { createMarker, deleteMarker, isThreadRunning } from "../background/index.js"; import { appendThreadHistory, createUwfStore, @@ -1016,8 +1010,3 @@ export async function cmdThreadCancel( return { thread: threadId, cancelled: true }; } - -export async function cmdThreadRunning(storageRoot: string): Promise { - const threads = await listRunningThreads(storageRoot); - return { threads }; -} diff --git a/packages/workflow-util/src/cli-reference.ts b/packages/workflow-util/src/cli-reference.ts index effa463..96274d8 100644 --- a/packages/workflow-util/src/cli-reference.ts +++ b/packages/workflow-util/src/cli-reference.ts @@ -15,7 +15,7 @@ uwf setup --provider --base-url \\ ## Workflow Commands \`\`\` -uwf workflow put # register a workflow from YAML file +uwf workflow add # register a workflow from YAML file uwf workflow show # show workflow by name or CAS hash uwf workflow list # list all registered workflows \`\`\` @@ -24,20 +24,27 @@ uwf workflow list # list all registered workflows \`\`\` uwf thread start -p # create a thread (no execution) -uwf thread step # execute one moderator→agent→extract cycle +uwf thread exec # execute one moderator→agent→extract cycle [--agent ] # override agent command [-c, --count ] # run multiple steps (default: 1) + [--background] # run in background uwf thread show # show thread head pointer -uwf thread list # list active threads - [--all] # include archived threads -uwf thread kill # terminate and archive a thread -uwf thread steps # list all steps in a thread +uwf thread list # list threads + [--status ] # filter: idle, running, or completed uwf thread read # render thread context as markdown [--quota ] # max output characters (default 32000) [--before ] # load steps before this hash (exclusive) [--start] # include start step in output -uwf thread fork # fork a thread from a specific step -uwf thread step-details # dump full detail node of a step as YAML +uwf thread stop # stop background execution (keep thread active) +uwf thread cancel # cancel thread (stop + move to history) +\`\`\` + +## Step Commands + +\`\`\` +uwf step list # list all steps in a thread +uwf step show # show details of a specific step +uwf step fork # fork a thread from a specific step \`\`\` ## CAS Commands @@ -78,10 +85,9 @@ uwf -V, --version # print version ## Key Concepts - **Workflow**: YAML definition with roles, conditions, and a routing graph; stored as a CAS node identified by its XXH64 hash. -- **Thread**: A single workflow execution (ULID). State is an immutable CAS chain; active threads are indexed in \`threads.yaml\`. -- **Step**: One moderator→agent→extract cycle. Run \`uwf thread step\` repeatedly until \`$END\`. -- **CAS**: Content-Addressed Storage — all nodes are immutable and identified by hash. -- **Role**: Named actor with goal, capabilities, procedure, output, and frontmatter schema; the moderator routes between roles. -- **Edge Prompt**: Required instruction on each graph edge — the moderator's dispatch message to the agent. +- **Thread**: A running instance of a workflow; points to a chain of CAS step nodes. +- **Step**: One moderator→agent→extract cycle; stored as a CAS node with output + detail refs. +- **Turn**: Agent-internal interaction (within a single step); stored per-turn in the detail node. +- **CAS**: Content-addressable store; every artifact (workflows, steps, details, turns) is hashed. `; }