跳到主要内容

defineEntrypoint

workflow.defineEntrypoint<Input, Output>() 定义 Workflow 项目中的一个可独立运行入口。每个入口拥有自己的 workflow、参数、输入构造、工具、token usage、调试 registry 和上下文扩展；平台选择入口后只执行该入口，不会先执行默认入口。

入口是同一项目下的扁平运行目录，不表示父子调用关系。需要把多个业务流程组合在一次 run 中时，应在 workflow 内显式调用 workflow.runWorkflow()。

签名​

workflow.defineEntrypoint<Input, Output>(
  definition: WorkflowEntrypointDefinition<Input, Output>,
): WorkflowEntrypointDefinition<Input, Output>

字段​

字段类型说明
idstring项目内唯一入口 ID。必须匹配 /^[a-z][a-z0-9_-]{0,63}$/。
titlestring非空展示标题。Desktop、Server Web、Embed、日志和回放使用该标题。
descriptionstring可选的入口说明。
workflowWorkflowDefinition<Input, Output>该入口实际执行的 workflow。必填。
paramsWorkflowParamDefinition[]该入口的结构化参数。
createInput(context) => Input把该入口的 args 和 paramValues 转成 workflow input。必填。
resolveParams(context) => WorkflowParamResolveResult该入口的参数联动回调。
requiredProvidersExecutorProviderName[]该入口需要的 provider；当前内置名称只有 "llm"。
toolsWorkflowToolPermissionDefinition[]该入口允许调用的工具和默认审批策略。
tokenUsageWorkflowTokenUsageDefinition该入口的 token 用量统计配置。
registryWorkflowNodeRegistryEntry[]该入口可单独调试的节点。
createContext(context) => Partial<WorkflowContext>为该入口增补 providers、metadata 和 hooks。KV、PersistentValue、conversation 和 files 仍由 runtime 注入。

createInput、resolveParams、registry entry 的 createInput 和 createContext 都会收到 WorkflowExecutorContext。Workflow 入口运行时，entrypointId 和 entrypointTitle 为当前所选入口；runtime 也会把这两个字段写入 WorkflowContext.metadata、runtime event 和最终 report。

Executor 目录​

Workflow executor 必须声明一个静态默认入口和非空入口数组：

export const executor = workflow.defineExecutor({
  projectType: "workflow",
  defaultEntrypoint: "main",
  entrypoints: [
    workflow.defineEntrypoint<MainInput, MainOutput>({
      id: "main",
      title: "完整流程",
      workflow: mainWorkflow,
      params: [],
      createInput() {
        return { errCode: 0, errMessage: "" };
      },
    }),
    workflow.defineEntrypoint<ValidateInput, ValidateOutput>({
      id: "validate",
      title: "数据校验",
      description: "仅执行校验阶段。",
      workflow: validateWorkflow,
      params: [],
      createInput() {
        return { errCode: 0, errMessage: "" };
      },
    }),
  ],
});

省略入口选择时运行 defaultEntrypoint。显式选择 validate 时只运行 validateWorkflow；mainWorkflow 不会先执行。

静态结构规则​

workflow-code structure 不执行配置代码，因此入口目录必须可以静态读取：

  • entrypoints 必须是非空数组字面量。
  • 每一项必须直接调用 workflow.defineEntrypoint({ ... })。
  • id、title、可选 description 和 defaultEntrypoint 必须是静态字符串。
  • workflow 必须引用项目源码中由 workflow.defineWorkflow(...) 定义的标识符；可以通过项目内相对路径使用命名、别名或 default import。Structure 会按实际 import/export 绑定解析定义，未引用的同名定义、外部包值或动态构造值都会产生 violation。
  • ID 必须合法且不能重复；defaultEntrypoint 必须命中其中一项。
  • Workflow executor 不再接受顶层 workflow、params、createInput、resolveParams、requiredProviders、tools、tokenUsage、registry 或 createContext。这些字段必须移动到具体入口。

结构报告在项目级返回 defaultEntrypoint 和 entrypoints[]。每个入口包含 id、title、可选 description、workflowName、execution、params、paramResolver、tools、tokenUsage 和 registry；Workflow 不再返回顶层 params 或 execution 兼容字段，也不会把各入口的 registry 聚合到 definitions.registry。

状态与隔离​

入口只隔离运行配置和界面草稿，不改变项目数据作用域：

数据行为
run / report / history每次运行记录实际入口 ID 和标题快照。
参数、附件、工具策略草稿宿主按项目、解析目标和入口隔离。
registry / debug node只读取所选入口的 registry。
context.storage.local/server同一项目的入口继续共享每个位置的 workflow namespace。需要业务隔离时由 workflow 自行设计 key。
Conversation不使用 defineEntrypoint，也不接受入口选择。

错误​

情况错误类型说明
ID 非法、标题为空或入口重复input_validationruntime 拒绝定义，structure 同时报告 violation。
默认入口不存在input_validationexecutor 无法加载。
运行未知入口input_validation错误 metadata 包含默认入口和允许入口列表。
Conversation 接收入口参数input_validationConversation 保持单入口，不会忽略或回退该参数。