摘要我正在从零开发一个新项目AI Workload Platform。它是一个面向 Agent能够围绕目标调用模型、工具或外部服务的软件组件与确定性程序任务主要按照预先编写的固定规则执行的程序任务的可靠运行时和调度平台目标是让由多个步骤组成、可能运行较长时间并且可能中途失败的后台工作能够被追踪、重试和恢复。本篇不是在科普一个泛泛的工作流产品而是学习并设计该项目的第一个核心内核在一台机器上不依赖容器一种隔离程序及其运行依赖的技术、云服务和真实模型先把任务定义、DAGDirected Acyclic Graph中文为“有向无环图”用来表示不会形成循环的任务依赖、状态、重试、超时、取消和重启恢复这些最基础的行为设计清楚。读完本文后你应该能理解为什么要区分工作流定义和一次运行为什么重试不等于可靠以及为什么模块 1 先选择当前的实现语言、模拟执行器和本地 JSON 存储。目录本章要解决的问题前置知识一句话理解单机内核核心概念生活类比最小工作流示例不设计可靠内核会发生什么在 AI Workload Platform 中的位置从提交到恢复的数据流方案选择与替代方案常见错误和失败场景如何验证进一步思考总结与限制官方参考资料1. 本章要解决的问题假设我们要处理一个数据文件步骤是读取文件、清洗内容、调用模型把文本转换为便于检索的数值表示也就是向量再更新用于快速查找内容的搜索索引。正常路径并不难写难的是发生异常时该怎么办清洗失败时生成向量能不能开始模型调用超时时应该立即失败还是重试进程在任务成功后、保存状态前崩溃重启后会不会重复执行用户取消时已经在运行的任务和还没开始的任务应该分别如何处理如果每个脚本都自己决定这些事一开始可能很快但很难保证所有任务的行为一致。模块 1 的目标就是先在单机上把这些边界说清楚、测清楚。2. 前置知识本文不要求你使用过任何现成的工作流平台只需理解以下概念程序可以被计算机执行的指令集进程Process程序一次正在运行的实例文件保存在磁盘上、进程结束后仍可读取的数据JSON一种用文本表示对象和数组的数据格式方便程序互相传递Go一种编译型编程语言。程序会先被编译成可执行文件它随语言提供的基础代码库也就是标准库支持同时处理多个任务、取消、文件和测试适合本模块的目标。3. 一句话理解单机内核单机可靠工作流内核是在一个 Go 进程内使用明确的任务状态、依赖规则和持久化状态统一决定任务何时执行、失败后是否重试以及进程重启后如何继续。这不是一个永远不会失败的系统。“可靠”指的是失败、超时、取消和崩溃发生时系统仍然能说清楚发生了什么不会静默丢失任务并能按已定策略继续或停止。4. 核心概念4.1 工作流定义和运行实例工作流定义Workflow Definition是“要做什么”的静态说明包括任务、依赖和重试配置。工作流运行实例Workflow Run是这份说明的一次执行。同一份定义可以执行多次每次运行都要有自己的标识ID和状态。区分二者很重要如果把“任务定义”和“任务执行状态”写在同一份数据里第二次运行很容易误读第一次运行的结果。4.2 TaskRun 和 Attempt任务运行实例Task Run是一次工作流运行中的一个任务。执行尝试Attempt是该任务真正被执行一次的记录。一个 TaskRun 可以有多个 Attempt第一次失败第二次重试它们不应该互相覆盖。这个分层能回答一个实际问题“任务现在最终成功了还是第二次尝试才成功”4.3 调度器和执行器调度器Scheduler是根据依赖和资源上限决定“现在调度哪些任务”的组件。执行器Executor负责真正调用一个任务。模块 1 计划使用 Mock Executor模拟执行器它不调用真实模型或工具而是按测试预设返回成功、失败、延迟或超时。这里模拟的是通用任务执行边界不是真实 Agent。并发上限Concurrency Limit是同一时间允许运行的任务数上限。上限为1时可用于确定性测试上限大于1时才能让 DAG 中无直接依赖的任务同时运行。4.4 状态机状态机State Machine规定一个对象可以处于哪些状态以及什么事件可以让它进入下一个状态。例如任务可以从“等待依赖”到“可执行”但不应该从“等待依赖”直接跳到“成功”。4.5 持久化和快照持久化Persistence是把数据保存到进程退出后仍可读取的介质例如本地文件或数据库。状态快照Snapshot是某一时刻的完整状态记录。模块 1 的设计计划同时保存快照和状态事件快照用于快速恢复状态事件记录每次状态变化帮助说明运行过程。4.6 可控时钟可控时钟Controllable Clock是一个可在测试中手动前进时间的接口。如果直接调用系统时钟测试一个 30 秒超时就可能真等 30 秒可控时钟可以让测试虚拟时间已经过去。4.7 至少执行一次和幂等至少执行一次At-Least-Once Execution表示任务不会静默丢失但可能重复执行。例如执行器已经成功但进程在保存成功状态前崩溃恢复后只能重新执行。幂等Idempotency表示同一个操作执行一次或多次业务结果仍然一致。不能将“任务不重复执行”当作恢复的前提应该在执行器或业务操作中单独设计。4.8 协作式取消协作式取消Cooperative Cancellation是指调度器发出取消信号执行器主动检查并停止。它不等于强制杀掉一个不响应的进程。在 Go 中执行器通常可以使用context.Context用于传递取消、超时和请求范围信息的 Go 类型传递取消和超时信号。但context只负责传播信号任务状态、Attempt 结果和恢复规则仍由工作流内核定义。4.9 TaskKey 和内部编译索引TaskKey是用户在工作流中提供的任务唯一标识例如clean-document。模块 1 规定它长 1 到 64 个字符只允许小写英文字母、数字、连字符和下划线。它比自动分配的整数更适合表达依赖和阅读日志build-index依赖clean-document比“任务 7 依赖任务 3”更容易理解。这不意味着调度器要在每次调度时都用字符串查找。工作流提交时校验器在同一次遍历中建立TaskKey - 数组下标的哈希映射索引。哈希映射Map是一种按键查找值的数据结构这里的键是 TaskKey值是数组下标。然后校验器把字符串依赖转换为整数邻接表。数组下标只是内部位置不是第二个任务 ID也不对用户暴露。时间复杂度Time Complexity用于描述输入规模增大时算法的操作次数如何增长。大 O 记号关注增长趋势不表示一个固定的毫秒数。在O(V E)中V是 Vertex顶点的数量在工作流 DAG 中就是任务数E是 Edge边的数量在 DAG 中就是任务之间的依赖关系数。例如A - B A - C B - D C - D这个 DAG 有 4 个任务所以V 4有 4 条依赖所以E 4。编译工作流时算法做三类工作每个任务遍历一次校验 TaskKey 并建立索引成本是O(V)每条依赖遍历一次建立整数邻接表和依赖计数成本是O(E)检测循环依赖时每个任务和每条依赖最多再被处理一次成本是O(V E)。将这些线性步骤相加后增长趋势仍然是O(V E)。它不是O(V × E)因为算法不会为每个任务重新扫描所有依赖。这里按哈希映射平均一次查找的耗时不会随任务总数线性增加来计算TaskKey 长度又被限制为最多 64 个字符。运行时使用数组和依赖计数也不需要反复扫描完整任务列表实际耗时仍要通过基准测试确认。4.10 依赖列表与未满足依赖计数depends_on告诉调度器“当前任务必须等哪些任务成功”。这些依赖由工作流作者显式写入 JSON调度器不会根据任务名称或业务含义自动猜测。仍以这个 DAG 为例A - B A - C B - D C - D提交工作流时编译结果可以表示为TaskKey - 数组下标 A0, B1, C2, D3 successors直接下游任务 A - [B, C] B - [D] C - [D] D - [] remainingDeps尚未成功的依赖数量 A0, B1, C1, D2邻接表Adjacency List是按每个任务保存其直接相邻任务的数据结构。这里保存直接下游任务是因为上游成功后调度器需要快速知道应检查谁。remainingDeps则记录某次运行中每个任务还有几个依赖尚未成功。它的初始值等于该任务的入度In-degree即指向该任务的依赖边数量运行后remainingDeps会随着上游成功而递减入度本身并不改变。运行开始时只有remainingDeps 0的A可以执行。A第一次进入成功状态后调度器沿着A - [B, C]把B和C的计数各减为0二者就可以并发执行。随后B成功只能把D从2减为1直到C也成功D才会变为可执行。因此调度热路径也就是运行时被频繁执行的代码路径不必反复扫描D的完整依赖列表只需在上游成功时更新受影响的下游计数再判断计数是否为0。但完整依赖结构仍会保留在创建后不再修改的编译结果中用于校验、失败传播和恢复时重算计数。这里还有三个可靠性边界只有某个任务第一次进入成功状态时才能递减下游计数重复收到同一成功结果不能重复递减否则下游可能被提前解锁某个依赖最终失败时下游任务应进入“已跳过”而不是把失败也当作已满足的依赖恢复工作流时应根据完整依赖结构和各任务已保存的成功、失败、取消等最终状态重新计算remainingDeps而不是完全相信可能在崩溃前只更新了一半的旧计数。同一份工作流定义的多个 WorkflowRun 可以共享 TaskKey 索引和邻接表但每次运行都必须有独立的任务状态数组和remainingDeps。共享的是“依赖关系”不是“执行进度”。5. 生活类比可以把调度器想成一位店长工作流定义是菜单描述要做哪些步骤WorkflowRun 是一次具体订单保存这次到底做到哪一步依赖是“洗菜后才能切菜”这样的前置条件并发上限是同时开放几个工作台Mock Executor 是练习用厨师可以按指定演示成功、失败或延迟快照和事件是订单和操作记录让店长重新上班时知道哪些菜已经做完。这个类比有一个重要边界如果菜已经做好但店长没来得及在订单上盖章重新开店时可能会再做一份。这就是“至少执行一次”和幂等性问题。6. 最小工作流示例设计中模块 1 的 CLICommand-Line Interface命令行界面将从 JSON 文件读取工作流定义。下面是一个示意定义表示先读取文件再清洗最后生成结果{id:document-pipeline,concurrency:2,tasks:[{key:read,action:mock-read,retry:{max_attempts:2,interval_ms:100},timeout_ms:3000},{key:clean,action:mock-clean,depends_on:[read],timeout_ms:3000},{key:summarize,action:mock-summarize,depends_on:[clean],timeout_ms:5000}]}6.1 输入工作流的id标识工作流定义任务的key就是该工作流内唯一的TaskKeytasks是任务列表depends_on表示当前任务依赖哪些任务concurrency是同时允许执行的任务数max_attempts和interval_ms描述重试策略timeout_ms描述一次执行的最长时间。6.2 执行过程校验器先检查 TaskKey 和依赖确认没有环read没有依赖进入“可执行”read成功后clean被解锁clean成功后summarize被解锁任意一次尝试失败时根据max_attempts决定是否重试所有任务成功且状态已保存后工作流才标记为“成功”。6.3 非法输入以下工作流不应进入调度{id:invalid,tasks:[{key:a,depends_on:[b]},{key:b,depends_on:[a]}]}a - b - a形成依赖环。如果仍然接受调度器会永远找不到可开始的任务在提交时拒绝能让错误立即返回。7. 不设计可靠内核会发生什么直接把三个脚本串起来只能表达正常路径读取 - 清洗 - 生成结果但这个脚本很难单独解决读取成功、清洗失败后应该不应该继续生成进程在清洗后崩溃重启后是否知道读取不用重复清洗超时时重试会不会把同一份结果写两遍取消到底是只停止新任务还是还要通知正在运行的任务可靠内核不是把所有任务都写得更复杂而是用统一状态和规则管理这些失败路径。8. 在 AI Workload Platform 中的位置模块 1 是这个新项目计划实现的第一个核心内核后续模块都会建立在它之上。这里的控制面是接收客户端请求、保存运行状态并管理工作流执行的服务层Agent Runtime是为 Agent 提供模型、工具、上下文和权限边界的运行时Worker是实际领取并执行任务的节点租约是带有效期的任务占用权Kubernetes是用于部署和管理容器化应用的开源平台。后续模块路线如下模块 1单机内核 - 模块 2控制面 API 与持久化存储 - 模块 3Agent Runtime、模型与工具执行 - 模块 4多 Worker、租约、心跳与故障恢复 - 模块 5可观测性、故障注入与性能验证 - 模块 6受限执行环境与 Kubernetes - 模块 7真实场景、最小控制台与开源发布如果模块 1 没有明确的状态、重试和恢复语义后面引入网络控制面、Agent Runtime 或多 Worker 只会把模糊扩大。先实现单机调度也是为了把核心正确性与数据库、容器和网络问题分开。自然语言生成工作流是模块 3 的必做产品演示但不是可靠内核的前置条件。9. 从提交到恢复的数据流以下数据流描述的是计划中的实现不是已经完成的业务代码或实验结果。9.1 提交时先校验工作流进入运行前先检查TaskKey 是否合法且在当前工作流内唯一所有依赖任务是否存在是否存在循环依赖并发上限、重试次数和超时是否合法。全部校验通过后系统才创建运行实例。这样可以把“定义本身无效”和“合法任务执行失败”明确区分开TaskKey 索引、邻接表和依赖计数的编译过程见 4.9 和 4.10。9.2 状态更新的先后顺序在计划的实现中当任务可以开始时调度器先把任务和 Attempt 写为“执行中”再调用 Mock Executor。任务返回成功后先保存 Attempt 结果和 TaskRun 成功再解锁下游任务。这样做的原因是下游任务只能依赖已经被保存的成功状态。如果先解锁、后保存进程在两步之间崩溃就可能出现“下游已经开始上游却仍然是未完成”的矛盾状态。9.3 进程重启后恢复进程重启时从文件读取最后一份快照已成功的任务不再调度根据编译后的完整依赖结构和已保存的任务状态重新计算未满足依赖计数保存为“执行中”的 Attempt 无法确认执行器是否已经完成因此标记为“被中断”如果还有尝试次数重新安排该任务如果重试耗尽记为失败并向下游传播跳过。10. 方案选择与替代方案10.1 为什么选择 Go而不是 Python 或 Rust模块 1 计划选择 Go是因为它的标准库已经提供并发控制、取消信号、encoding/json包负责 JSON 编解码、文件操作和测试工具能够在不引入第三方框架的前提下实现本模块。编译后得到单个可执行文件也便于后续把同一内核放到本机进程、容器或节点中运行。Python一种常用于 AI 和数据处理的编程语言的生态更丰富编写原型也通常更快但模块 1 首先验证的是并发调度、状态恢复和取消语义若同时引入解释器运行时和大量外部库会扩大需要排除的变量。Rust一种强调内存安全和性能控制的编程语言适合后续受限执行节点等更底层的场景代价是当前学习和实现复杂度更高反而会掩盖工作流内核本身的设计问题。选择 Go 的代价是它不会自动解决持久化一致性、分布式协调或任务幂等语言和并发原语只是实现工具。如果后续基准表明核心存储或执行隔离存在更高要求应分别评估 SQLite、PostgreSQL 等存储方案以及 Rust 等实现语言。10.2 分层内核与单体调度器本项目选择分层内核把校验、状态机、调度器、执行器、存储和时钟分开。这些名词不是为了增加文件数量而是为了使每个边界可以独立测试。另一种做法是把所有逻辑放入一个调度器对象。这在很小的原型中代码量较少但并发、重试和恢复会很快互相影响不利于测试失败场景。10.3 进程内 Mock Executor 与真实执行模块 1 计划使用进程内 Mock Executor。它不创建子进程而是在同一个 Go 进程中按预定脚本返回结果。这能让测试稳定模拟失败、延迟和取消。它不调用模型、选择工具或执行 Agent 决策因此未使用 Mock Agent 这个容易造成范围误解的名称。不选择本地脚本执行是因为子进程会引入环境变量、进程清理、资源限制和安全风险。这些问题会在受限执行模块单独处理。10.4 本地 JSON 与 YAML、SQLite计划将 JSON 作为模块 1 的工作流文件格式因为 Go 标准库中的encoding/json包可以直接处理它。YAML 是另一种更适合人工书写的文本配置格式但需要额外解析依赖SQLite 是嵌入应用进程、用表组织关联数据的轻量关系型数据库更适合查询和事务。事务是“要么全部成功要么全部失败”的一组数据操作但使用 SQLite 会引入数据库驱动和新的测试边界。计划中的 JSON 存储将在状态变化时写入完整快照因此任务数和事件数增加后文件读写可能成为主要瓶颈。这正是 12.5 要单独测量快照成本的原因而不是假设 JSON 一定能满足后续规模。当运行实例变多、需要并发查询或多进程写入时本地 JSON 文件就不再适合应重新评估 SQLite 或 PostgreSQL运行在独立服务中的关系型数据库。10.5 固定间隔与指数退避、随机抖动固定间隔指每次重试都等待同样的时间指数退避则让等待时间逐次增长例如1秒、2秒、4秒。随机抖动是在等待时间上加入小范围的随机变化用于降低大量任务同时重试形成的瞬时压力。设计选择固定间隔因为只有单机和 Mock Executor主要目标是验证重试次数和状态变化。连接大量外部服务时再引入指数退避和随机抖动。10.6 为什么不用自增整数作任务标识自增整数适合数据库内部主键但不适合作为工作流文件中的业务标识。使用clean-document这样的 TaskKey用户可以在提交前直接写出依赖并且在日志中直观识别任务。如果使用3和7工作流的任务排序、复制和比较都更容易出现混淆。另一种常见方案是 UUIDUniversally Unique Identifier通用唯一标识符。它适合生成跨工作流也很难重复的运行 ID但字符串较长不适合让用户频繁手写依赖。TaskKey 只要求在一份工作流定义内唯一既保留可读性又能在提交时可靠校验。这不是用字符串换取性能4.9 的校验阶段使用 TaskKey 建立一次索引调度热路径使用数组下标。字符串是对外的可读名称数组下标是对内的访问优化二者不是两个业务 ID。11. 常见错误和失败场景11.1 把定义和运行状态混在一起一个工作流可以多次执行。如果将“清洗任务”的配置和“清洗任务已成功”保存在同一层对象中重新运行时就会出现状态污染。应该分开 WorkflowDefinition、WorkflowRun 和 TaskRun。11.2 只用一个布尔值表示状态is_running和is_finished无法清楚表示“等待重试”、“已跳过”和“被中断”。显式状态机虽然会多几个状态值但能拒绝不合法的跳转。11.3 只在内存里记录状态进程退出后内存消失。如果没有快照重启后无法分辨任务是没开始、正在运行还是已经成功。持久化也不等于不会重复执行它只是让系统能够知道自己上次停在哪里。11.4 在调用执行器前就标记成功成功状态必须来自执行器的结果而且要在状态已经保存后才解锁下游任务。否则进程在执行之前崩溃系统会得到一个虚假成功。11.5 以为超时一定等于没有执行超时表示在限定时间内没有收到可确认的结果不一定代表任务没有产生副作用。副作用是任务对文件、数据库或外部服务产生的可观察改变例如写入一条记录或发送一次请求。强制取消、幂等写入和结果去重是后续执行器需要考虑的问题。11.6 重试所有错误参数错误、权限错误和依赖不存在时重试可能只是重复消耗资源。内核需要区分临时执行错误和永久执行错误而不是把所有错误都简化成“再试一次”。11.7 把文件更新当成原子操作如果直接覆盖 JSON 文件进程在写入一半时崩溃重启时可能无法解析文件。模块 1 的文件存储应该先在目标文件所在目录写临时文件再尝试通过原子替换更新目标文件。原子替换指读取方只能看到旧的完整文件或新的完整文件不会看到只写了一半的内容。临时文件与目标文件位于同一文件系统是重要前提但 Go 的os.Rename并不承诺所有操作系统都有相同的原子行为因此模块 1 还必须限定支持平台并通过崩溃测试验证这个边界。12. 如何验证本文写的是设计和验证计划不是已发生的业务实验结果。在模块 1 实现后将使用 Go 标准库的testing包和go test命令进行以下验证。12.1 单元测试非法或重复 TaskKey、缺失依赖、循环依赖和非法配置被拒绝TaskKey 索引、整数邻接表和依赖计数编译正确上游任务第一次成功时正确递减下游计数重复成功结果不会重复递减合法状态转换通过非法转换被拒绝任务只在所有依赖成功后变为可执行重试次数、固定间隔和重试耗尽逻辑正确超时、取消和被中断产生正确的 Attempt 结果并发任务数不超过配置上限文件存储能够完成快照写入、读取和事件保存。12.2 调度器集成测试简单串行工作流成功无直接依赖的任务可并发执行临时失败后重试并最终成功重试耗尽后下游任务跳过超时后按策略重试取消后运行中任务停止未开始任务取消进程重启后执行中任务记为中断并按策略恢复恢复时从完整依赖和任务状态重算依赖计数不依赖旧计数恰好写完持久化失败后不继续调度新任务。12.3 CLI 验收模块 1 实现后使用本地 JSON 示例运行提交工作流 - 获取运行 ID 查询运行状态 - 查看任务和工作流状态 前台执行时按 CtrlC - 查看取消结果命令行程序可以通过os/signal包接收 CtrlC 产生的中断信号再将它转换为内核能够处理的取消请求。设计上按运行 ID 取消是内核接口和自动化测试的能力但不在模块 1 中通过另一次 CLI 调用远程操作前台运行。这避免为了一个命令提前引入后台服务和进程间通信。12.4 预期验证命令gotest./... go vet ./...go vet是 Go 自带的静态分析命令用于发现代码中可能的格式错误、可疑调用和其他常见问题它不能替代单元测试。所有自动化测试必须使用 Mock Executor 和本地临时目录不访问外部网络不调用真实模型服务。12.5 性能基准与规模验证后续使用 Go Benchmark也就是 Go 标准测试工具提供的基准测试机制测量10,000 个任务的 TaskKey 唯一性校验和索引建立10,000 个任务及其依赖的 DAG 编译和环检测1,000 个活跃 WorkflowRun 共享编译后工作流时的内存占用相同运行规模下共享同一编译结果与分别持有不同编译结果的内存对照JSON 快照在不同任务数和事件数下的写入、读取和恢复成本。这些是必测场景不是尚未经过实验的性能承诺。完成首轮基准后需要记录机器环境、输入规模、原始结果和瓶颈再制定可接受的延迟、吞吐和内存阈值。13. 进一步思考如果一个任务已经产生外部写入重启后重试如何保证幂等固定间隔在外部服务限制请求频率时是否足够什么时候需要指数退避和随机抖动当工作流扩展到多节点时谁来保证两个节点不会同时领取同一个任务如果存储文件不可写调度器是应该暂停、进入故障状态还是尝试换一个存储位置这些问题是进入代码和故障实验后需要继续验证的方向目前还不是模块 1 已经解决的问题。14. 总结与限制模块 1 先用一个单机 Go 进程回答可靠工作流的基础问题工作流定义与一次运行分开任务必须在依赖成功后才能执行重试、超时和取消都有明确状态重启后根据已保存状态恢复但承认至少执行一次带来的重复可能使用分层接口和 Mock Executor使测试不依赖外部服务。限制也很明确没有多节点租约、容器隔离、外部模型、完整日志或性能数据。本文是技术学习和设计基础不能代替后续代码、业务测试和故障实验。15. 官方参考资料Gocontext包https://pkg.go.dev/contextGoencoding/json包https://pkg.go.dev/encoding/jsonGoos.Rename文档https://pkg.go.dev/os#RenameGoos/signal包https://pkg.go.dev/os/signalGotesting包https://pkg.go.dev/testing