uncaged/workflow
10
0
Fork 0
Code Issues 6 Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: split @uncaged/workflow-runtime from engine #121

New Issue
Closed
opened 2026-05-08 06:16:26 +00:00 by xiaoju · 1 comment
xiaoju commented 2026-05-08 06:16:26 +00:00
Owner
Copy Link
Copy Source

What

将 @uncaged/workflow 拆为两个包：

  • @uncaged/workflow-runtime — bundle 的唯一依赖，极小，零 I/O
  • @uncaged/workflow — engine，动态加载 bundle，拥有所有持久化和编排逻辑

Why

当前 bundle import from "@uncaged/workflow" 会拖入 engine、CAS 实现、registry、merkle 等它完全不需要的东西。Bundle 应该只依赖它实际用到的类型和 createWorkflow。

核心原则：从 bundle 的两个 export（WorkflowFn + WorkflowDescriptor）反推依赖，所有不被它们需要的东西都不进 runtime。

Runtime 边界（@uncaged/workflow-runtime）

仅包含 bundle 编译/运行所需的最小集：

  • Types: WorkflowFn, RoleOutput, ThreadInput, WorkflowCompletion, WorkflowFnOptions, WorkflowDefinition, RoleDefinition, RoleMeta, AgentBinding, AgentFn, AgentContext, ModeratorContext, ExtractContext, ExtractFn, CasStore(type only), LlmProvider(type only), ExtractMode
  • Constants: START, END
  • Functions: createWorkflow（纯编排，CAS 和 ExtractFn 通过参数注入，内部无 I/O）
  • Descriptor: WorkflowDescriptor, WorkflowRoleDescriptor, validateWorkflowDescriptor
  • Util: Result, ok, err

关键约束：

  • 零 node:fs import
  • 零外部依赖（zod 保持 peerDependency）
  • CasStore 只是 type 定义，createCasStore 实现留在 engine
  • createWorkflow 的 CAS 操作通过注入的 CasStore 接口完成，不直接 import 实现

Engine 留在 @uncaged/workflow

  • executeThread / supervisor
  • createCasStore / merkle / GC
  • extractBundleExports（dynamic import，engine 是唯一做 dynamic import 的地方）
  • resolveModel / config
  • ExtractFn 的具体实现（llmExtract, reactExtract）
  • registry / storage
  • fork / worker / logger

依赖关系

bundle.esm.js -> @uncaged/workflow-runtime (轻量)
@uncaged/workflow (engine) -> @uncaged/workflow-runtime
@uncaged/cli-workflow -> @uncaged/workflow (engine)
workflow-agent-* -> @uncaged/workflow-runtime
workflow-template-* -> @uncaged/workflow-runtime

Migration

  • Bundle 改为 import from @uncaged/workflow-runtime
  • Engine 通过 resolveModel(config, scene) 解析 LLM 配置，构造 ExtractFn 注入给 bundle
  • 不做向后兼容 re-export，直接 breaking change
## What 将 `@uncaged/workflow` 拆为两个包： - **`@uncaged/workflow-runtime`** — bundle 的唯一依赖，极小，零 I/O - **`@uncaged/workflow`** — engine，动态加载 bundle，拥有所有持久化和编排逻辑 ## Why 当前 bundle `import from "@uncaged/workflow"` 会拖入 engine、CAS 实现、registry、merkle 等它完全不需要的东西。Bundle 应该只依赖它实际用到的类型和 createWorkflow。 核心原则：从 bundle 的两个 export（WorkflowFn + WorkflowDescriptor）反推依赖，所有不被它们需要的东西都不进 runtime。 ## Runtime 边界（@uncaged/workflow-runtime） 仅包含 bundle 编译/运行所需的最小集： - **Types**: WorkflowFn, RoleOutput, ThreadInput, WorkflowCompletion, WorkflowFnOptions, WorkflowDefinition, RoleDefinition, RoleMeta, AgentBinding, AgentFn, AgentContext, ModeratorContext, ExtractContext, ExtractFn, CasStore(type only), LlmProvider(type only), ExtractMode - **Constants**: START, END - **Functions**: createWorkflow（纯编排，CAS 和 ExtractFn 通过参数注入，内部无 I/O） - **Descriptor**: WorkflowDescriptor, WorkflowRoleDescriptor, validateWorkflowDescriptor - **Util**: Result, ok, err **关键约束**： - 零 node:fs import - 零外部依赖（zod 保持 peerDependency） - CasStore 只是 type 定义，createCasStore 实现留在 engine - createWorkflow 的 CAS 操作通过注入的 CasStore 接口完成，不直接 import 实现 ## Engine 留在 @uncaged/workflow - executeThread / supervisor - createCasStore / merkle / GC - extractBundleExports（dynamic import，engine 是唯一做 dynamic import 的地方） - resolveModel / config - ExtractFn 的具体实现（llmExtract, reactExtract） - registry / storage - fork / worker / logger ## 依赖关系 ``` bundle.esm.js -> @uncaged/workflow-runtime (轻量) @uncaged/workflow (engine) -> @uncaged/workflow-runtime @uncaged/cli-workflow -> @uncaged/workflow (engine) workflow-agent-* -> @uncaged/workflow-runtime workflow-template-* -> @uncaged/workflow-runtime ``` ## Migration - Bundle 改为 import from @uncaged/workflow-runtime - Engine 通过 resolveModel(config, scene) 解析 LLM 配置，构造 ExtractFn 注入给 bundle - 不做向后兼容 re-export，直接 breaking change
xiaoju commented 2026-05-08 06:18:18 +00:00
Author
Owner
Copy Link
Copy Source

Phase 拆分

Phase 1: 创建 @uncaged/workflow-runtime 包

Phase 2: 解耦 createWorkflow 的 I/O 依赖

Phase 3: 迁移下游包到 workflow-runtime

Phase 4: 清理 engine 包 + 最终验证

## Phase 拆分 ### Phase 1: 创建 @uncaged/workflow-runtime 包 - Testing issue: #122 ### Phase 2: 解耦 createWorkflow 的 I/O 依赖 - Testing issue: #123 ### Phase 3: 迁移下游包到 workflow-runtime - Testing issue: #124 ### Phase 4: 清理 engine 包 + 最终验证 - Testing issue: #125
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
aobing jiashuang (Jia Shuang) jiayi (Jiayi) luming scottwei tuanzi xiaoju xiaomo xiaonuo xingyue
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: uncaged/workflow#121
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?