docs: sync all README.md files with current codebase

- Root README: add all 9 packages to table, update architecture diagram, refresh CLI reference from uwf --help - New READMEs for 8 packages (cli-workflow, workflow-protocol, workflow-moderator, workflow-agent-kit, workflow-agent-hermes, workflow-agent-builtin, workflow-agent-claude-code, workflow-dashboard) - Updated workflow-util README to match current exports - All API sections verified against src/index.ts exports 小橘 🍊（NEKO Team）
2026-05-23 15:00:05 +00:00
parent aff0ee6fea
commit ffc31a8c19
10 changed files with 1164 additions and 72 deletions
@@ -0,0 +1,193 @@
+# @uncaged/workflow-protocol
+
+Shared TypeScript types and JSON Schema constants for the workflow engine.
+
+## Overview
+
+This is the contract layer (Layer 0). It defines `WorkflowPayload`, thread node payloads, moderator context, CLI output shapes, and configuration types used across every other package. It has no runtime logic beyond exporting schema objects from `@uncaged/json-cas`.
+
+**Dependencies:** `@uncaged/json-cas`, `@uncaged/json-cas-fs`
+
+## Installation
+
+```bash
+bun add @uncaged/workflow-protocol
+```
+
+## API
+
+All exports come from `src/index.ts`.
+
+### JSON Schema constants
+
+```typescript
+START_NODE_SCHEMA: JSONSchema
+STEP_NODE_SCHEMA: JSONSchema
+WORKFLOW_SCHEMA: JSONSchema
+```
+
+### Core identifiers
+
+```typescript
+type CasRef = string      // XXH64 hash, 13-char Crockford Base32
+type ThreadId = string    // ULID, 26-char Crockford Base32
+type WorkflowName = string
+type RoleName = string
+```
+
+### Workflow definition
+
+```typescript
+type RoleDefinition = {
+  description: string;
+  goal: string;
+  capabilities: string[];
+  procedure: string;
+  output: string;
+  frontmatter: CasRef;
+};
+
+type Transition = {
+  role: string;
+  condition: string | null;
+  prompt: string;
+};
+
+type ConditionDefinition = {
+  description: string;
+  expression: string;
+};
+
+type WorkflowPayload = {
+  name: string;
+  description: string;
+  roles: Record<string, RoleDefinition>;
+  conditions: Record<string, ConditionDefinition>;
+  graph: Record<string, Transition[]>;
+};
+```
+
+### Thread nodes
+
+```typescript
+type StepRecord = {
+  role: string;
+  output: CasRef;
+  detail: CasRef;
+  agent: string;
+  edgePrompt: string;
+};
+
+type StartNodePayload = {
+  workflow: CasRef;
+  prompt: string;
+};
+
+type StepNodePayload = StepRecord & {
+  start: CasRef;
+  prev: CasRef | null;
+};
+```
+
+### Moderator context
+
+```typescript
+type StepContext = Omit<StepRecord, "output"> & { output: unknown };
+
+type ModeratorContext = {
+  start: StartNodePayload;
+  steps: StepContext[];
+};
+```
+
+### Configuration
+
+```typescript
+type ProviderAlias = string;
+type ModelAlias = string;
+type AgentAlias = string;
+
+type ProviderConfig = { baseUrl: string; apiKeyEnv: string };
+type ModelConfig = {
+  provider: ProviderAlias;
+  name: string;
+};
+
+type AgentConfig = {
+  command: string;
+  args: string[];
+};
+
+type WorkflowConfig = {
+  providers: Record<ProviderAlias, ProviderConfig>;
+  models: Record<ModelAlias, ModelConfig>;
+  agents: Record<AgentAlias, AgentConfig>;
+  defaultAgent: AgentAlias;
+  agentOverrides: Record<WorkflowName, Record<RoleName, AgentAlias>> | null;
+  defaultModel: ModelAlias;
+  modelOverrides: Record<Scenario, ModelAlias> | null;
+};
+```
+
+### CLI output types
+
+```typescript
+type StartOutput = { workflow: CasRef; thread: ThreadId };
+
+type StepOutput = {
+  workflow: CasRef;
+  thread: ThreadId;
+  head: CasRef;
+  done: boolean;
+};
+
+type StepEntry = {
+  hash: CasRef;
+  role: string;
+  output: unknown;
+  detail: CasRef;
+  agent: string;
+  timestamp: number;
+};
+
+type StartEntry = {
+  hash: CasRef;
+  workflow: CasRef;
+  prompt: string;
+  timestamp: number;
+};
+
+type ThreadStepsOutput = {
+  thread: ThreadId;
+  workflow: CasRef;
+  steps: [StartEntry, ...StepEntry[]];
+};
+
+type ThreadForkOutput = {
+  thread: ThreadId;
+  forkedFrom: { step: CasRef };
+};
+
+type ThreadListItem = {
+  thread: ThreadId;
+  workflow: CasRef;
+  head: CasRef;
+};
+
+type ThreadsIndex = Record<ThreadId, CasRef>;
+
+type Scenario = string;
+```
+
+## Internal Structure
+
+```
+src/
+├── index.ts      Public re-exports
+├── types.ts      All type definitions
+└── schemas.ts    START_NODE_SCHEMA, STEP_NODE_SCHEMA, WORKFLOW_SCHEMA
+```
+
+## Configuration
+
+This package defines `WorkflowConfig` types only. Runtime config loading lives in `@uncaged/workflow-agent-kit` (`loadWorkflowConfig`).