跳到主要内容

defineEntrypoint

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

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

签名​

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

入口可选的分区元数据是静态对象：

interface EntrypointGroupDefinition {
  id: string;
  title: string;
  order?: number;
}

字段​

字段类型说明
idstring项目内唯一入口 ID。必须匹配 /^[a-z][a-z0-9_-]{0,63}$/。
titlestring非空展示标题。CLI Web、日志和回放使用该标题。
descriptionstring可选的入口说明。
groupEntrypointGroupDefinition可选的入口分区。相同分区 id 的入口必须使用完全一致的 title 和 order。
workflowDefinition<Input, Output>该入口实际执行的 workflow。必填。
paramsParamDeclaration[]该入口的有序参数与动作入口声明，详见 defineExecutor 参数。
createInput(context) => Input把该入口的 args 和 paramValues 转成 workflow input。必填。
resolveParams(context) => ParamResolveResult该入口的参数联动回调。
requiredProvidersExecutorProviderName[]该入口需要的 provider；当前内置名称只有 "llm"。
toolsToolPermissionDefinition[]该入口允许调用的工具和默认审批策略。
tokenUsageTokenUsageDefinition该入口的 token 用量统计配置。
registryNodeRegistryEntry[]该入口可单独调试的节点。
createContext(context) => Partial<RunContext>为该入口增补 providers、metadata 和 hooks。KV、PersistentValue、conversation 和 files 仍由 runtime 注入。

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

Executor 目录​

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

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

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

静态结构规则​

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

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

结构报告在项目级返回 defaultEntrypoint 和 entrypoints[]。每个入口包含 id、title、可选 description、group、projectName、execution、展平的 params、保存动作顺序的 paramLayout、paramResolver、tools、tokenUsage 和 registry；Workflow 不再返回顶层 params 或 execution 兼容字段，也不会把各入口的 registry 聚合到 definitions.registry。静态分析无法读取或发现分区元数据冲突时，会在 diagnostics.violations 中报告明确原因。

状态与隔离​

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

数据行为
run / report / history每次运行记录实际入口 ID 和标题快照。
参数、附件、工具策略草稿宿主按项目、解析目标和入口隔离。
入口分区展开状态共享运行界面和 CLI Web 仅在声明了至少一个分区时启用分区界面；按 projectId + resolved target 使用版本化 localStorage 键持久化分区展开状态，未分组入口归入本地化“未分组”分区。
registry / debug node只读取所选入口的 registry。
context.storage.local/server同一项目的入口继续共享每个位置的 workflow namespace。需要业务隔离时由 workflow 自行设计 key。
Conversation不使用 defineEntrypoint，也不接受入口选择。

错误​

情况错误类型说明
ID 非法、标题为空或入口重复input_validationruntime 拒绝定义，structure 同时报告 violation。
分区不是静态内联对象、字段无效或同一 ID 的元数据冲突input_validationruntime 拒绝定义；静态分析和 structure report 在对应位置报告 violation。
默认入口不存在input_validationexecutor 无法加载。
运行未知入口input_validation错误 metadata 包含默认入口和允许入口列表。
Conversation 接收入口参数input_validationConversation 保持单入口，不会忽略或回退该参数。