uni-flow 公开 API（中文注解）

---

uni-flow 公开 API（中文注解） / UniFlowClient

Class: UniFlowClient

Defined in: sdk/client.ts:50

TypeScript SDK 客户端。

• 有 baseUrl：远程 HTTP 客户端（对接 Orchestrator）
• 无 baseUrl：进程内回退（本地工厂 + createWorkflowEngine）

主流程通常是：validateYaml →（远程）loadAndRegister 或（本地）register → startWorkflow → getRun。

Example

// 进程内：先 register，再同步跑一遍
const client = createUniFlowClient();
client.register('demo', () => ({ config: myWorkflowConfig }));
const run = await client.startWorkflow('demo', { q: 'hi' }, { sync: true });

// 远程：校验 YAML 后 from-yaml 注册
const remote = createUniFlowClient({ baseUrl: 'http://127.0.0.1:8080' });
await remote.validateYaml(yamlText);
await remote.loadAndRegister(yamlText, {
  'child.unit': { type: 'http', endpoint: 'http://127.0.0.1:4001/execute' },
});

Constructors

Constructor

new UniFlowClient(options?, defaultEngineOptions?): UniFlowClient

Defined in: sdk/client.ts:65

Parameters

options?

UniFlowClientOptions = {}

客户端模式与 HTTP 相关选项

defaultEngineOptions?

WorkflowEngineOptions = {}

进程内创建 Engine 时的默认选项

Returns

UniFlowClient

Accessors

mode

Get Signature

get mode(): "remote" | "in-process"

Defined in: sdk/client.ts:75

当前模式：remote（有 baseUrl）或 in-process。

Returns

"remote" | "in-process"

Methods

getRun()

getRun(workflowId, runId): Promise<RunRecord>

Defined in: sdk/client.ts:174

查询某次 run 状态与结果。

Parameters

workflowId

string

工作流 id

runId

string

run id

Returns

Promise<RunRecord>

对应的 RunRecord

---

health()

health(): Promise<{ ok: boolean; workflows?: string[]; }>

Defined in: sdk/client.ts:95

健康检查。

Returns

Promise<{ ok: boolean; workflows?: string[]; }>

进程内返回本地已注册 workflow 列表；远程则请求 GET /health

---

loadAndRegister()

loadAndRegister(yaml, bindings?): Promise<{ workflowId: string; }>

Defined in: sdk/client.ts:137

远程：POST /workflows/from-yaml，把 YAML（及可选 HTTP bindings）注册到 Orchestrator。 需要已配置 baseUrl；进程内请改用 createEngineFromYaml / register。

Parameters

yaml

string

Workflow YAML 文本

bindings?

Record<string, { endpoint: string; headers?: Record<string, string>; type: "http"; }>

可选：uses 名 → HTTP Unit 绑定（type: 'http' + endpoint）

Returns

Promise<{ workflowId: string; }>

注册后的 { workflowId }

---

register()

register(workflowId, factory): void

Defined in: sdk/client.ts:84

进程内注册工作流工厂；远程模式下调用会被忽略（请用 loadAndRegister）。

Parameters

workflowId

string

工作流 id

factory

() => object

返回 WorkflowConfig 与可选 Engine options 的工厂

Returns

void

---

respondHITL()

respondHITL(workflowId, runId, approved, responder?): Promise<RunRecord>

Defined in: sdk/client.ts:229

回应 HITL（人工审核）请求；进程内会先 respondToHITL 再 resume。

Parameters

workflowId

string

工作流 id

runId

string

run id

approved

boolean

是否批准

responder?

string = 'sdk'

回应者标识（默认 "sdk"）

Returns

Promise<RunRecord>

更新后的 RunRecord

---

resume()

resume(workflowId, runId, snapshotId?): Promise<RunRecord>

Defined in: sdk/client.ts:193

从检查点恢复 run。

Parameters

workflowId

string

工作流 id

runId

string

run id

snapshotId?

string

可选快照 id

Returns

Promise<RunRecord>

更新后的 RunRecord

---

searchMemory()

searchMemory(query, topK?): Promise<{ results: object[]; }>

Defined in: sdk/client.ts:254

远程记忆检索（GET /memory/search）；进程内当前返回空结果列表。

Parameters

query

string

查询文本

topK?

number = 5

返回条数上限（默认 5）

Returns

Promise<{ results: object[]; }>

{ results: [...] }

---

startWorkflow()

startWorkflow(workflowId, input?, opts?): Promise<RunRecord>

Defined in: sdk/client.ts:154

启动一次 run。

Parameters

workflowId

string

已注册的工作流 id

input?

Record<string, unknown>

写入初始 SharedState 的输入对象

opts?

选项；sync 为 true 时等待跑完再返回（进程内与远程均支持该语义）

sync?

boolean

Returns

Promise<RunRecord>

RunRecord（含 runId / status / 可选 result）

---

validateYaml()

validateYaml(source): Promise<{ ok: true; workflowId: string; }>

Defined in: sdk/client.ts:115

用已发布的 JSON Schema 校验 Workflow YAML（始终在本地执行，不调用 Orchestrator）。

source 可以是文件路径或内联 YAML 文本：若路径可读则按文件加载，否则当作 YAML 字符串。

Parameters

source

string

文件路径或 YAML 文本

Returns

Promise<{ ok: true; workflowId: string; }>

{ ok: true, workflowId }，workflowId 来自文档 metadata.id

Example

const client = createUniFlowClient();
const { workflowId } = await client.validateYaml('./uniflow.workflow.yaml');