数据飞轮流水线编排与算子插件需求文档 草案
本文属于数据飞轮专题，定义流水线编排与算子插件两个模块要帮助用户完成的工作，作为后续设计、AI 开发与验收的共同依据。核心目标是：开发者交付一个有明确契约和版本的算子，用户将已启用算子组合成流程，固定版本运行，并能够解释结果、失败及恢复方式。
文档版本为 0.1，状态为待需求评审。 代码阅读日期为 2026 年 10 月 1 日，依据本地 data-flywheel 工作区当时的实现，包括尚未提交的改动。文中的优先级、交付边界和验收要求是本草案的建议，需要在评审时确认；它们不代表已经批准的排期。
本文区分三类信息：代码基线表示当前代码支持的行为；需求表示希望稳定交付的用户行为；待确认表示尚需产品或工程决策的范围。本次进行了代码和测试文件阅读，没有重新执行应用测试或验证生产环境，不能据此认定功能已经完成验收。
后续研究： 2026 年 10 月 7 日的流水线与算子插件设计评审补充了最新代码差异，以及 Harness、ComfyUI 和数据闭环平台的可借鉴机制。新增范围仍需评审，不自动改变本文的需求状态。
1 背景与产品目标
数据处理通常包含接入、清洗、切分、打标、向量化和结果输出。若每增加一种算法都需要修改平台主服务，算法交付就会与平台发布绑定；若流程只存在于脚本中，参数、依赖和版本难以复核；若运行只有一个最终状态，用户又无法判断任务是在排队、执行、受阻还是失败。
两个模块承担不同职责。算子插件负责把处理能力交付成可验证、可选择的版本；流水线负责表达这些能力之间的数据依赖，保存流程版本，并管理一次次具体运行。模型效果和数据业务质量需要另行约定，不能由“插件验证通过”或“流水线运行成功”代替。
本轮建议以以下结果判断价值：
- 开发者能够按照公开 SDK 与模板接入一个算子，完成上传、验证、发布和项目启用。
- 编排者能够选择项目可用的算子版本，配置并保存有效流程，明确运行哪个版本。
- 运行人员能够定位失败节点，查看输入输出、日志和产物来源，并使用适用的恢复操作。
- 管理者能够限制项目访问和关键动作，追踪发布、启用、保存、启动及取消记录。
2 范围与交付层次
建议首轮范围是现有项目体系下的编排、版本、插件发布和运行管理，先在已经准备好的单一本地目标环境中，以受限 CPU JSON 插件证明端到端交付。首轮不承诺自动准备任意环境；需要固定并记录镜像、wheel、SDK、Worker 与执行服务，确认实际可用后验收。已有内置媒体算子继续作为相关业务场景的背景，但不据此承诺上传插件自动拥有相同的模型、文件和网络能力。
| 层次 | 纳入内容 | 完成依据 |
|---|---|---|
| 首轮必须验收 | 算子目录、可视化 DAG、参数校验、草稿保护、不可变版本、插件验证发布启用、固定版本运行、权限、失败解释与产物追踪 | 本文 P0 需求和相应验收场景全部通过 |
| 后续运行管理 | 部署修订、固定间隔触发、数据到达触发、触发历史、分区补跑、执行环境与 WorkerPool 选择 | 本文 P1 场景通过；每个可选环境实际具备固定镜像、wheel 与 SDK，资源绑定由执行器兑现 |
| 按业务另行立项 | 上传插件的媒体读写、GPU、依赖镜像构建、跨项目共享、版本停用退役、节点并行、Cron、人工任务 | 先补相应契约与验收口径，再进入设计 |
优先级表示本草案建议的交付顺序，不是缺陷严重程度。已有代码满足的需求应复用并验收，无需重新开发；只有差距进入实施任务。已经实现的 P1 能力应继续保留，P1 不代表必须删除或推迟现有行为。
本轮不覆盖完整的数据采集、标注、训练、模型评测系统，也不建设在线 IDE、任意第三方依赖安装或 Kubernetes 集群管理。数据飞轮最终如何连接训练与评测反馈，需要单独的业务需求。
2.1 两条执行轨道
| 轨道 | 交付与执行方式 | 信任与首轮边界 |
|---|---|---|
| 管理员安装的可信算子 | 管理员安装并按允许名单加载插件；本地 subprocess Worker 接收 JSON 并校验结果 [C2] | 仅用于可信代码；清理应用环境变量和限制超时不构成安全沙箱，不能作为上传代码的隔离保证 |
| 用户上传的 CPU JSON 插件 | pure Python wheel 经候选验证、发布和启用后，在固定摘要的 OCI 镜像中运行；绑定 wheel 与 SDK 摘要 [C7][C8] | 采用容器资源与网络限制；首轮验收以这条受限轨道为准，不承诺媒体文件、GPU 或任意依赖能力 |
两条轨道共享图契约与版本规则，但执行限制、制品准备和信任条件分别验收。涉及首轮范围的开放决策紧接下节列出，其中受保护日志入口是否纳入需先确认。
3 需求评审需要确认的事项
以下结论会改变实施范围，在确认前保持为开放项：
| 问题 | 本草案建议 | 会影响什么 |
|---|---|---|
| 首轮主要用户是谁 | 先覆盖算子开发者、编排者和运行人员 | 模板、配置易用性和排障信息的投入顺序 |
| 首轮代表性负载与环境是什么 | 先在已准备好的单一本地环境运行受限 CPU JSON 插件 | 是否立即需要媒体授权、模型依赖、GPU、网络或多环境分发 |
| 首轮是否增加运行日志入口 | 建议给有权限用户受保护的日志查看入口；Dagster 深链接是可选方案 | F07、A06 的新增范围；跨系统项目鉴权与日志可访问性 |
| 部署、事件和补跑是否属于首轮 | 作为 P1；若无人值守生产是首轮目标则提升到 P0 | 调度、凭据配置与页面交付范围 |
| 是否要求跨项目共享 | 先保留项目隔离，独立发布；共享另定授权协议 | 制品所有权、可见性与项目启用模型 |
| 是否必须支持版本停用与退役 | 多人生产使用前需确认；本轮先明确缺口 | 引用影响、历史保留、紧急封禁与恢复规则 |
| 如何处理随机或近似输出 | 首轮沿用精确样例比较 | 验证报告、数值容差与模型质量判定 |
| 性能和数据规模目标是多少 | 按真实工作负载约定，不套用代码最大值 | 并发、容量、存储与压测标准 |
| 谁确认需求并验收 | 明确需求负责人和最终验收人 | 范围变更、完成判断与交付责任 |
4 当前代码基线
以下只描述当前实现。旧文章和 9 月的设计说明可作为背景，遇到差异以本次代码阅读为准。代码依据编号见文末。
| 能力 | 当前代码支持 | 需要保留的边界 |
|---|---|---|
| 编排与配置 | 节点、连线、参数表单与 JSON 编辑、撤销重做、布局保存、导入导出、离开保护 [C1] | 有效图为 1 至 40 节点；前端体验不能代替服务端校验 |
| 图契约 | 项目可用算子、节点唯一、类型匹配、具名多输入、无环校验 [C2] | 支持分支和汇合；未提供通用多输出端口 |
| 流程版本 | 保存生成不可变版本，固定图和算子快照；并发保存检测冲突 [C3] | 历史版本能否再次运行还取决于实现摘要和环境是否可用 |
| 运行管理 | 持久派发意图、带幂等键提交、后台派发、状态对账、取消及符合条件的提交恢复 [C4] | 提交结果未知时禁止盲目重复启动；无键请求视为新意图；不是任意失败节点续跑 |
| 节点执行 | 安全节点自动重试、按契约缓存、产物与血缘记录 [C5] | 单次运行的节点目前串行执行；DAG 分支不等于并行执行 |
| 插件交付 | 模板、候选上传、异步验证、报告、正式发布、项目启用；文本草稿可恢复 [C6] | 验证、发布、启用分别有门禁；wheel 文件需重新选择 |
| 插件身份 | 项目内插件及算子版本唯一，执行核对 wheel、SDK、runtime 和实现摘要 [C7] | 跨项目独立发布同名版本不等于共享同一发布制品 |
| 上传插件运行 | pure Python wheel、固定 SDK 与镜像、受限容器执行 [C8] | 禁网络，固定 1 CPU、512 MiB；不在线安装任意依赖 |
| 部署与触发 | 不可变部署修订，手动、固定间隔、认证数据事件，事件去重与分区补跑 API [C9] | 补跑和触发历史尚缺完整页面；数据事件凭据依赖服务端配置 |
| 资源与项目 | 执行环境、资源池、授权与并发额度检查，运行固定执行快照 [C10] | 资源选择必须由实际 launcher 兑现；记录 GPU 池不证明 GPU 任务已运行 |
当前上传插件限定 9 种产物类型，单个产物最多 5,000 条记录、8 MiB；这与本地可信算子的执行上限不同。需求和验收应明确采用哪条执行路径，不能把较大的本地上限套到上传插件。[C2][C8]
4.1 需求与当前代码的差距
下表是代码阅读得到的初步差距分类，不表示测试或验收已通过。设计阶段仍需逐项核对。
| 需求组 | 分类 | 复用能力与需要补齐的部分 |
|---|---|---|
| F02 F04：图约束与草稿 | 已支持 | DAG、端口精确绑定、撤销、离开保护与并发保存保护已有实现；仍按 A02 A03 验收 |
| F06 F08 F09：提交与执行策略 | 已支持 | 带幂等键提交、对账、取消、重试/缓存覆盖及血缘已有实现；按下文明确语义核验 |
| F10 至 F14：插件交付 | 部分支持 | 候选、验证、版本门禁、发布启用已有实现；端到端真实执行与环境交付需验收，算子版本聚合及节点升级入口需核对补齐，具名声明冲突拒绝是建议新增规则 |
| F05：版本操作 | 部分支持 | 保存与历史只读查看已有实现；版本比较、从历史创建草稿及指定历史版本运行需核对补齐 |
| F07 F18：运行排障 | 部分支持／建议新增 | 状态、等待原因、错误、尝试与产物已有返回；运行 API 无日志字段，受保护日志入口及状态更新时间需补齐或确认方案 |
| F15 F16：部署与资源 | 部分支持 | 修订、事件和补跑 API 已有实现；完整历史/补跑页面与逐环境制品可用性验收需补齐 |
| F01 F03 F17：目录、表单与治理 | 部分支持 | 已有目录、表单、授权与审计基础；分页筛选覆盖、接受的 Schema 编辑能力和动作权限需逐项核对 |
5 用户角色与关键场景
角色表达职责，不预设固定角色名称。实际动作由项目权限决定，同一人可以承担多个职责。
| 用户职责 | 核心任务 | 最关心的信息 |
|---|---|---|
| 算子开发者 | 编写、提交、验证和修订插件 | 契约、模板、失败用例、日志与下一步操作 |
| 发布负责人 | 判断某个候选能否正式发布 | 精确版本、验证依据、运行环境和变更说明 |
| 项目管理员 | 启用项目需要的插件与执行资源 | 可见范围、权限、可用版本及依赖 |
| 流水线编排者 | 组合算子、配置参数、保存并运行 | 可连接类型、版本、草稿和校验错误 |
| 运行人员 | 查看任务、排障、取消和恢复 | 当前阶段、失败位置、恢复条件和产物来源 |
场景一：接入新处理能力。 开发者从模板开始，在本地构建候选包，上传声明和成功、异常样例；验证失败时能定位原因并创建新候选；验证通过后由有权限人员发布，再由项目显式启用。编排者随后能在目录中找到准确版本。
场景二：配置并运行流程。 编排者选择 source、transform、sink，连接声明的输入端口，填写参数；发现类型不匹配时获得具体解释；保存有效版本后启动运行，运行详情与页面所选版本一致。
场景三：调整流程并核对历史。 用户修改参数或算子版本，产生新流水线版本；旧版本和已有运行保持原身份。多人编辑发生冲突时，用户能够保留自己的草稿，并明确比较或加载哪个版本。
场景四：处理运行异常。 用户能够区分排队、资源不足、提交受阻、执行失败和取消中。已存在的运行在网络恢复后继续对账；恢复提交与创建一次新运行具有不同语义，并由界面明确说明。
6 对象与业务规则
| 对象 | 含义 | 核心规则 |
|---|---|---|
| 算子版本 | 一个有确定输入、输出和参数契约的处理能力 | 显式版本；不得以同一身份静默改变行为 |
| 插件版本 | 一次包含一个或多个算子的交付 | 制品、声明、验证报告与执行环境身份相互绑定 |
| 流水线版本 | 某次保存的完整流程定义 | 图、配置和算子快照不可变；修改生成新版本 |
| 流水线运行 | 对固定流程版本发起的一次执行 | 有独立身份、启动者、状态、节点记录及结果 |
| 数据产物 | 某次节点执行产生或复用的结果 | 有项目、类型、内容身份、来源及父产物关系 |
| 部署修订 | 固定版本、参数与执行资源的可触发配置 | 调整生成新修订；暂停不取消已有运行 |
必须保持以下规则：
- 版本关系明确。 插件版本、算子版本、流水线版本和部署修订分别表达；启用新插件不得自动改写已有流程。
- 编辑与执行一致。 页面显示当前查看版本、草稿基线和待运行版本；有未保存修改时，必须先保存或明确放弃草稿再运行。
- 发布与使用分开。 上传成功是候选，验证通过不等于已发布，发布不等于已启用，已启用不等于任意环境可执行。
- 项目是访问边界。 列表、详情、产物、报告和写动作均检查目标项目；按钮隐藏不能替代服务端授权。
- 恢复不能扩大副作用。 客户端为一次启动意图生成
idempotency_key，重复点击及响应未知后的网络重试复用同一键；同一项目和操作者上下文内，同键同内容返回原运行，同键不同运行选项返回 HTTP 409。未提供键的请求视为新意图，不承诺去重。提交结果未知时先对账；节点重试依据重试安全契约，不承诺自动获得 exactly-once。 - 验证结论有适用范围。 插件样例通过证明当前契约和提交样例符合规则；业务质量、吞吐、成本与生产可用性需要单独证据。
- 版本占用不可覆盖。 项目内候选创建即占用
(plugin_id, version)，验证失败也不释放该身份；修订候选使用新插件版本。插件版本与算子版本独立：改变插件版本不会避开已发布(operator_id, version)的冲突，需要分别选择新版本。[C7] - 触发去重有修订边界。 去重只在
(deployment_id, event_key)内生效；新部署修订有新deployment_id，相同外部事件可以产生新运行。补跑在同一修订内以request_key和分区派生事件键；同键同分区返回原运行，换键可显式重跑。[C9]
7 功能需求
7.1 流水线编排与版本
| 编号 | 优先级 | 用户需求与预期行为 | 验收 |
|---|---|---|---|
| F01 | P0 | 按当前项目查看、搜索和分页访问流水线与已启用算子；空目录说明下一步入口，刷新保留必要的项目与对象上下文 | A01 A09 |
| F02 | P0 | 在画布添加、删除和连接节点；支持声明的具名输入、分支与汇合；拖线和参数区选择上游使用相同约束 | A02 |
| F03 | P0 | 参数表单覆盖平台允许发布的 Schema 范围；常用字段可直接编辑，复杂结构有 JSON 入口；默认值、类型及错误位置一致 | A02 |
| F04 | P0 | 节点、连线与布局操作可撤销重做；离开时保护草稿；并发冲突保留本地修改，说明基线与最新版本 | A03 |
| F05 | P0 | 保存前服务端校验；保存生成新版本；查看历史、比较差异、基于历史创建新草稿和显式选择运行版本 | A03 A04 |
F02 的汇合仅在算子已声明具名输入时成立，不能把多个上游塞入单输入端口。图与运行输入的端口集合必须与声明精确相等，缺失或额外端口均拒绝。建议新增契约规则： 非空 input_ports 必须配合 input_type=null，不能同时声明单输入类型和具名输入；模板、上传、注册及执行契约使用同一规则。当前代码优先使用 input_ports 并忽略同时声明的 input_type，尚未拒绝这一冲突，不能视为已有门禁。[C2][C8]
F03 不要求首轮支持全部 JSON Schema 标准，但平台接受发布的契约必须有可用编辑方式；不支持的组合应在发布前说明并拒绝，而不是运行时才暴露。
F05 中版本比较、恢复和指定历史版本运行需要逐项核对现有实现。恢复应形成新版本，保留原历史；旧实现或制品不可用时给出原因，不得改用当前实现冒充历史运行。
7.2 运行与结果管理
| 编号 | 优先级 | 用户需求与预期行为 | 验收 |
|---|---|---|---|
| F06 | P0 | 从已保存版本启动异步运行，固定图、算子、参数及执行身份；防止重复点击和网络重试产生额外运行 | A04 A05 |
| F07 | P0 | 运行列表可分页筛选；详情先说明当前阶段、等待原因、失败节点与适用操作，再展示节点状态、尝试、输入输出和时间；受保护日志入口为待决定新增范围 | A06 A09 |
| F08 | P0 | 依据真实状态提供取消与提交恢复；失败后可显式用指定版本创建新运行；提交恢复保留原运行身份与原选项 | A05 A06 |
| F09 | P0 | 依据确定性、副作用及缓存/重试声明决定策略；展示缓存来源、节点尝试与产物血缘，支持结果预览和授权下载 | A07 |
F07 的日志入口是待决定的新增范围：当前运行 API 返回节点错误、尝试和产物，没有日志字段。建议首轮提供按运行/节点定位的受保护日志查看入口；可采用 Dagster 深链接或平台内查看，具体方案在设计时确定。任何入口都须保持项目鉴权，不能用公开执行服务地址绕过平台权限。A06 中日志验收以评审确认纳入为前提。
F09 采用以下策略，重试与缓存独立计算：[C5]
| 条件 | 自动重试 | 缓存资格 |
|---|---|---|
对应声明为 true / false | retry_safe 显式值优先 | cacheable 显式值优先 |
对应声明未提供或为 null | deterministic && !side_effects | deterministic && !side_effects |
| 最终策略生效 | 安全节点最多自动重试 2 次，共最多 3 次执行；不安全节点不自动重试 | 仅资格为真且运行 use_cache=true 时使用缓存 |
use_cache=false 只关闭缓存，不改变重试策略；显式覆盖不会因确定性或副作用默认值被再次否定，发布评审应确认声明符合算子行为。
首轮不要求从任意节点续跑。进度估计、输入输出数量和最终成功状态分别表达：缓存命中不是本次重新计算，部分节点成功也不是整条流程成功。未知提交、迟到执行和取消需要在设计阶段确定可审计的收敛机制。
7.3 算子插件开发与发布
| 编号 | 优先级 | 用户需求与预期行为 | 验收 |
|---|---|---|---|
| F10 | P0 | 下载可独立使用的 SDK 模板与示例说明；明确支持的包格式、产物、输入端口、参数、依赖和执行限制 | A08 |
| F11 | P0 | 上传 wheel、manifest 和测试样例形成候选；静态拒绝非法包或身份冲突；保护文本草稿，提示文件需重新选择 | A03 A08 |
| F12 | P0 | 异步验证候选；分别显示排队、运行、通过、失败、受阻；展示用例结论、期望与实际差异、日志和历史，受阻有解释与恢复方式 | A06 A08 |
| F13 | P0 | 仅发布对应制品、SDK 和运行环境验证通过的候选；发布与项目启用独立鉴权；执行重新核对身份，拒绝漂移 | A04 A08 A10 |
| F14 | P0 | 算子目录按身份组织版本，展示来源、契约和可用版本；节点升级由用户选择并重新校验，不自动替换旧引用 | A04 A08 |
测试至少覆盖每个算子的成功输出；异常、边界输入应按算子实际行为补充。首轮采用现有的精确产物与异常类型比较，不将其包装为模型效果评测。涉及随机输出或近似数值比较时，先定义新的判定规则。
7.4 部署与治理
| 编号 | 优先级 | 用户需求与预期行为 | 验收 |
|---|---|---|---|
| F15 | P1 | 将指定版本及参数保存为部署修订；查看执行环境、WorkerPool、资源池和可用性；逐环境确认固定 image、wheel 与 SDK 实际可用，所选资源由 launcher 兑现；暂停仅阻止新触发 | A11 |
| F16 | P1 | 手动、固定间隔和认证数据到达触发；展示触发历史与关联运行；仅在部署修订内按事件键去重；同 request_key 与分区的补跑返回原运行，换键可重跑并显示结果 | A11 A12 |
| F17 | P0 | 按目标项目授权读取、开发、发布、启用、保存、启动和取消；重要操作留下可追踪的审计记录 | A10 |
| F18 | P0 | 缺少 Worker、镜像、SDK、制品或执行服务时明确说明受阻原因；显示状态更新时间，避免把历史验证通过当作当前可用 | A06 A08 |
F16 的固定间隔按经过秒数调度，不等于 Cron。当前实现将停机错过的多个触发合并成一次；本草案建议保留该语义，需要逐批恢复时由显式补跑完成。若业务要求按本地日历、节假日或每个遗漏时点补齐，应作为新的调度需求。
8 验收场景
验收以用户行为和结果为单位。自动测试、真实执行与用户操作记录分别提供证据；模拟执行不能替代真实插件与执行引擎验收。
| 编号 | 场景与操作 | 通过条件 |
|---|---|---|
| A01 | 在无流水线、无启用插件的项目进入工作台 | 能查看空状态和创建入口；无可用算子时能转到插件工作台；不得用模拟运行显示成功 |
| A02 | 建立合法分支汇合；分别尝试环、缺失/额外端口、类型不匹配、重复节点、非法参数及具名输入与非空 input_type 同时声明 | 合法图保存成功；图输入端口精确绑定；所有非法入口均被服务端拒绝并定位错误；声明冲突拒绝作为建议新增规则验收 |
| A03 | 删除节点后撤销；误关候选表单；两人基于同一版本先后保存 | 图可恢复；文本草稿可恢复；后保存者得到冲突并保留修改，不能静默覆盖他人版本 |
| A04 | 发布插件新版本、修改流程；选择两个流程版本比较节点/参数/算子差异；从历史版本创建草稿、修改并保存；查看旧运行并显式运行旧版本 | 比较结果与保存定义一致；历史草稿基于所选版本且保存为新版本，原历史和运行不被覆盖；旧版本运行固定实现，不可用则清楚受阻 |
| A05 | 客户端为启动意图生成键；重复点击、同键同内容重发、同键改变版本/缓存/资源选项；省略键重复提交；模拟响应丢失并复用原键重试 | 同键同内容返回同一平台运行；同键异内容 HTTP 409；无键每次视为新意图；未知提交先对账，不盲目派发；最终对账或明确人工处理 |
| A06 | 模拟 Worker/执行服务离线、超时、节点失败、API 重启及取消期间迟到执行；打开运行与节点详情，逐项核对日志入口、输入输出及状态更新时间 | 历史可读且原因可解释；授权用户可定位输入输出及更新时间；若确认纳入日志入口，能访问对应日志且无权用户被拒绝；恢复保留原选项，取消终态不被迟到结果错误覆盖 |
| A07 | 组合检查 deterministic、side_effects、retry_safe、cacheable；让默认安全节点显式禁重试/缓存，让默认不安全节点显式启重试/缓存；再切换 use_cache 并注入可重复失败 | 显式覆盖优先，未声明按默认公式；安全节点最多 2 次自动重试/3 次执行，不安全节点无自动重试；use_cache 不改变重试；缓存资格、尝试、父来源/缓存来源准确，越权下载被拒绝 |
| A08 | 用模板构建 CPU JSON 插件完成上传、真实容器验证、发布、启用和流程执行；失败候选同版本重传、换插件版本但复用已发布算子版本；提交具名输入声明冲突和缺失/额外端口 | 门禁与摘要正确且真实产生预期产物；失败候选已占插件版本不可覆盖；独立算子版本碰撞在发布时拒绝；端口精确绑定，声明冲突按建议新增规则拒绝；超限/依赖不支持可解释 |
| A09 | 创建超过单页上限的流程、版本、插件或运行记录，搜索历史目标 | 服务端搜索、过滤和分页能找到目标；空结果不能由截断列表导致；筛选与总数口径一致 |
| A10 | 用只读、开发、发布、启用等不同权限访问两项目并直接调用接口 | 动作权限独立；无权读取与写入被拒绝；有效项目上下文正确；关键操作有操作者、对象和结果记录 |
| A11 | 创建部署、修改同名配置形成新修订；同修订重复触发同事件，再在新修订触发同事件；暂停部署；分别选择可用及缺少固定制品的环境/WorkerPool | 部署固定版本、参数与资源；旧修订暂停而已有运行继续；同修订同事件返回原运行，跨修订可形成新运行；逐环境核对 image/wheel/SDK 和资源绑定，缺少时受阻，历史可查询 |
| A12 | 数据事件使用合法/非法凭据；调度跨停机；同修订同 request_key 补跑同分区，再换 request_key 重跑该分区 | 非法事件拒绝；恢复符合合并语义；分区输入绑定正确；同键同分区返回原 run_id，换键创建新运行；去重不跨部署修订 |
A08 是首轮集成验收的必要条件。若目标改为“上传插件读取真实关键帧、执行模型并写回对象存储”，必须增加资产授权、模型依赖、GPU/网络和质量指标验收，不能用 JSON 元数据过滤代替。
9 非功能要求与验证口径
以下是建议的交付约束。性能数值和规模尚未确认，本草案不承诺未经测量的响应时间或吞吐。
| 维度 | 要求 | 验证方法 |
|---|---|---|
| 安全 | API 不导入上传代码；上传插件在固定 OCI 受限环境执行；可信本地 subprocess 不作为安全沙箱；项目隔离；秘密不进入普通参数、日志或产物 | 非法包、越权、输出与资源超限测试；运行环境配置检查 |
| 正确性 | 编辑版本、运行版本、实现与制品身份一致；校验规则不能从其他入口绕过 | 版本漂移、并发冲突及接口绕过场景 |
| 恢复 | 派发意图持久化；重启后能对账；租约过期和迟到结果有明确规则 | 进程中断、超时、重复请求与取消演练 |
| 可解释性 | 排队、受阻、失败分别显示；关键状态附更新时间；错误能关联节点或用例 | 目标用户完成排障任务并说明下一步 |
| 可部署性 | 首轮在已准备好的单一本地目标环境交付固定 wheel、镜像、SDK、Worker 与执行器；P1 每个可选环境单独核对制品与 SDK 可用性 | 首轮完成 A08 并保留准备步骤、实际配置和结果；P1 按 A11 验证逐环境可用性 |
| 可用性 | 画布、表单和报告在桌面与窄屏能访问；常规操作不无提示丢失输入 | 隔离浏览器走查和草稿、撤销、冲突场景 |
| 性能与规模 | 按明确负载检查列表、编排、验证排队、运行和下载；服务故障时不因逐项同步查询拖垮列表 | 先确认数据量、并发、产物大小、统计口径与目标值，再压测 |
正式验收至少记录：环境与版本、操作或测试命令、输入夹具、期望结果、实际结果、运行与制品引用、未通过项。已有测试文件只能说明覆盖意图，实际执行记录才说明该环境下是否通过。
10 建议交付顺序
| 阶段 | 输出 | 进入下一阶段的条件 |
|---|---|---|
| 需求对齐 | 本文的确认版本、首轮范围、待确认问题的结论、验收责任人 | 目标、范围、关键规则及验收口径明确 |
| 契约与差距核对 | 需求到当前代码的映射、需要补齐的差距、对象与状态契约 | 区分复用、修复和新增，避免将旧文档缺口误当新任务 |
| 首轮功能交付 | P0 的界面、控制面、真实执行路径和部署说明 | A01 至 A10 按适用范围通过，未通过项有明确结论 |
| 运行管理交付 | P1 的部署、事件、补跑及历史页面 | A11 A12 在目标环境通过 |
| 业务扩展 | 真实媒体、模型、资源和跨项目能力的独立需求 | 相应业务目标与验收先确认，再决定技术方案 |
这里不预估开发天数或资源成本。工程方案和差距评估完成后，再给出容量依据、负责人和承诺时间。
11 如何用于 AI 开发
合理的 AI 开发流程首先要对齐需求。 对齐至少回答：谁遇到什么问题、这轮完成什么、哪些行为不能改变、用什么证据判定完成。已有代码是约束和复用依据，不应直接变成全部产品需求。
需求确认不要求在写第一行代码之前消除所有不确定性。对于关键未知，可以先做边界明确的小实验，记录结果后更新需求与设计；但不能把实验原型的行为直接当成用户已经接受的产品规则。
交给 AI 的单个任务应包含：需求编号、对应验收场景、相关代码范围、已确认业务规则、允许改动的范围和需要返回的验证证据。例如：
完成 F12 中验证受阻状态的解释与恢复，对照 A06 和 A08。先核对当前验证状态、租约和 Worker 路径；复用已有实现，仅补实际差距。展示当前阶段、受阻原因及适用操作，保留原验证历史。返回改动说明、测试结果和真实执行中尚未验证的部分。
任务执行中的范围变化应回到需求记录，并重新评估相关验收。代码评审关注实现正确性，用户验收关注需求是否达成，两者分别保留结论。
12 代码依据与背景资料
下列路径相对于本次读取的 data-flywheel 仓库。行号用于定位 2026 年 10 月 1 日工作区的实现，后续改动可能使其变化；由于包含未提交代码，本文不将远端仓库链接冒充这一版本的证据。
- C1 编排与草稿：
apps/web/src/pages/PipelinesPage.tsx第 336、374、395、448 行；apps/web/src/pipeline-graph.ts第 19 行。 - C2 图与契约：
apps/api/app/pipeline_runtime.py第 105、151、179 行；packages/flywheel-sdk/src/flywheel_sdk/__init__.py第 18、49、65 行。 - C3 不可变版本：
apps/api/app/pipeline_models.py第 27 行；apps/api/app/pipeline_api.py第 378、389、397 行。 - C4 持久提交与恢复：
apps/api/app/media_api.py第 270、282、333、342、353 行；apps/api/app/pipeline_api.py第 203 行。 - C5 重试缓存与串行执行：
apps/api/app/media_dagster.py第 89、120、125、158、192、221 行。 - C6 插件工作台：
apps/web/src/pages/OperatorsPage.tsx第 60 行；apps/web/src/components/PluginDevelopmentWorkspace.tsx第 24、38、50 行；apps/web/src/components/PluginCandidateForm.tsx第 63、98、117 行。 - C7 版本身份与项目作用域：
apps/api/app/plugin_release_models.py第 13、55 行；apps/api/app/plugin_release_service.py第 318、340、363、374 行；apps/api/app/plugin_release_adapter.py第 41 行。 - C8 上传与受限执行：
apps/api/app/plugin_release_service.py第 36、191、255 行；apps/api/app/plugin_release_runner.py第 69、80 行；infra/plugin-runtime/runner.py第 15、62、84、103 行。 - C9 部署与触发：
apps/api/app/pipeline_deployments_service.py第 20、52、60、81、118、132 行；apps/api/app/pipeline_deployments_api.py第 166、192、196 行；apps/web/src/components/PipelineDeployments.tsx第 34、49、68 行。 - C10 执行资源：
apps/api/app/execution_resources.py中的validate_execution_binding、freeze_execution、reserve_execution；资源绑定受实际 launcher 配置约束。
已有测试分别位于 apps/api/tests/test_pipelines.py、test_plugin_releases.py、test_plugin_named_inputs.py、test_plugin_release_runner.py、test_media_dagster.py、test_dispatch_worker.py、test_pipeline_deployments.py 和 apps/web/e2e/pipelines.spec.ts。这些是后续验收可复用的测试入口，本次未执行，不作为通过证明。
相关设计背景可阅读数据平台算子插件设计讨论与数据平台需求管理。它们保留原有讨论语境；本文对当前实现与本轮需求的判断独立于旧文中的状态描述。