Core API 总览
Core API 分组记录业务 workflow 可直接使用的workflow.* 运行时 API。这里的边界以 core/runtime-api.ts 为准：平台、CLI、App 和 server 会把这些方法注入到 globalThis.workflow，业务 workflow 不需要从 "workflow-code" 导入它们。
入口边界
| 入口 | 说明 |
|---|---|
workflow.* | 业务 workflow 使用的全局 API，来源是 core/runtime-api.ts。 |
workflow-code 包入口 | CLI、App、server、测试和高级宿主使用的工具入口，来源是 core/index.ts。 |
Runtime API 索引
| API | 说明 |
|---|---|
defineWorkflow | 定义 workflow 本体，描述主执行函数。 |
defineExecutor | 定义平台如何把参数转成 workflow input，并声明 params、registry、conversation。 |
createInputNode | 创建输入解析节点。 |
createFileInputNode | 创建文件输入节点，把 file param 引用解析成文件对象。 |
createLLMNode | 创建非流式 LLM 调用节点。 |
createLLMStreamNode | 创建流式 LLM 调用节点。 |
createLLMProviderFromEnv | 从 workflow runtime 环境变量创建 LLM provider。 |
createLLMProviderRef | 创建可延迟解析的 provider 引用。 |
createOutputNode | 创建同步或流式输出节点，最终输出 WorkflowOutputItem[]。 |
createDetailsOutputNode | 创建独立可折叠 output item 的便捷输出节点。 |
createTimerNode / endTimer | 创建业务计时节点，并在显式结束或 workflow 收尾时写入计时卡片。 |
createToolApprovalGate | 创建工具审批包装器；结合 executor tools 注册项和 context.toolPermissions 复用 user-input 等待/恢复协议审批工具调用。 |
createQuestionClassifierNode | 创建基于 LLM 的问题分类节点。 |
runNode | 执行普通节点并触发节点执行 hook。 |
runStreamNode | 执行流式节点，收集 chunks，并产出 finalize 结果。 |
runIf | 执行 if / else-if / else 分支，并把分支选择写入运行报告和 Diagram。 |
runFor | 执行可追踪的 for 循环，并让 Diagram 用循环容器展示循环体。 |
runWhile | 执行可追踪的 while 循环，并让 Diagram 用循环容器展示循环体。 |
runWorkflow | 在当前上下文中调用另一个 workflow，复用 KV、会话、provider、token usage 和 trace。 |
Knowledge Documents | 通过 PersistentValue 管理项目内 markdown 知识库文档。 |
getEnv | 读取当前 runtime 环境中的非空变量。 |
getRuntimePlatform / isCli / isWeb / isApp | 判断当前 workflow 的执行宿主是 CLI、App 还是 server web。 |
getLLMProvider | 按上下文、节点名和 provider source 解析 LLM provider。 |
WorkflowError | 标准 workflow 错误类型。 |
核心运行对象
多数 API 会围绕input、context、node 和 payload 运行。
| 对象 | 类型 | 说明 |
|---|---|---|
input | Input 或节点 Output | 当前 workflow 或节点的输入数据。 |
context | WorkflowContext / NodeContext | 包含 provider、KV、conversation、files、metadata、hooks、abortSignal。 |
payload | WorkflowPayload 子类型 | 节点 payload 应继承 WorkflowPayload，成功时 errCode: 0、errMessage: ""。 |
provider | LLMProviderSource / LLMProvider | LLM 节点通过 provider source 解析实际 provider。 |
NodeContext 核心字段
| 字段 | 类型 | 说明 |
|---|---|---|
providers | ProviderRegistry | LLM provider 注册表和绑定表。 |
kv | WorkflowKVContext | 全局、workflow、conversation 三层 KV。 |
persistentValue | WorkflowPersistentValueContext | server 数据库持久值入口，三层 scope 与 KV 同构；CLI/App 已连接 server 时可用，未连接且未注入 store 时调用报错。 |
conversation | WorkflowConversationContext | 会话状态读写入口。setTitle 可安全建议 UI 标题；未启用会话时其它读写会抛错。 |
files | WorkflowFileStore | undefined | 文件引用解析入口；createFile 可生成 server-backed 运行文件。 |
metadata | object | undefined | 当前执行元信息，例如 workflow、runId、conversationId。 |
nodeHooks | NodeExecutionHooks | undefined | 节点开始、chunk、完成等事件回调。 |
timers | WorkflowTimerContext | undefined | 业务计时节点上下文；createTimerNode 启动计时，endTimer 结束计时。 |
toolPermissions | WorkflowToolPermissionContext | undefined | 当前 run 的工具权限上下文。按 executor tools 默认值和宿主覆盖值解析，供 createToolApprovalGate() 或自定义工具调用逻辑判断启用、自动批准和人工审批。 |
abortSignal | AbortSignal | undefined | 中断执行和 provider 调用。 |
Payload 约束
| 字段 | 说明 |
|---|---|
errCode | 业务错误码。成功值为 0。 |
errMessage | 错误说明。成功时统一为空字符串。 |
追踪
本文档由 issue #46 记录。Runtime platform helper 由 issue #84 记录。PersistentValue、知识库 helper 与 runtime 生成文件由 issue #86 记录。工具权限审批由 issue #92 记录。Runtime API 对齐core/runtime-api.ts。