pikasTech-unidesk/project-management/PJ2026-02/specs/PJ2026-0205-pipeline-platform.md

PJ2026-0205 流水线平台需求规格

修改历史

版本	对应 commit id	更新日期	变更说明
v0.1	2fdadce8	2026-07-13	定义 YAML-first、TypeScript CLI、异步作业、用量计费和 Web 编辑台的目标能力。

正文

PJ2026-0205 流水线平台需求规格

1. 文档控制

字段	内容
编号	PJ2026-0205
短名	流水线平台
层级	L1 方向
规格状态	已生效
实现引用版本	draft-2026-07-13-p0
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-02 智媒工厂总规格
规格治理索引	PJ2026-02 智媒工厂总规格 第 7 章

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。正文只定义配置、调度、作业、工件、计量和可视控制面的预期终态与验收契约。

2. 目的和范围

2.1 目的

流水线平台的目标是：

• 让各生产能力能够被一致配置、单步调试、组合运行、观察、重试和复现；
• 坚持 CLI-first；
• 让每个步骤先具备稳定的 TypeScript CLI 契约；
• 让完整流水线和 Web 复用同一调度与作业事实；
• 避免可视界面成为另一套不可调试实现。

2.2 范围内

• owning YAML、configRef、模式校验、配置计划、依赖计划和失败策略。
• 期次创建、步骤目录、单步运行、区间运行和完整流水线组合。
• 异步作业、状态、进度、步骤状态、结构化日志、结果、取消、重试和终态。
• 期次工件契约、原子写入、路径安全、字节数、哈希、媒体类型和清单。
• 同源 HTTP API、Web 编辑台、媒体范围请求、服务器生命周期和公网 IP 预览。
• LLM 请求级 Token、质量门结果、公开目录价估算、汇总和 Web/CLI 展示。
• 本地开源依赖安装、版本与模型哈希检查，以及无付费媒体生成服务边界。

2.3 范围外

• 定义选题、文稿、视觉、音频或发布结果是否业务正确；这些由相应 L1 负责。
• 把某个 CLI 命令、Web 页面、服务端口、框架或仓库本身作为能力目标。
• 从运行环境、日志或 API 响应反解并保存 Secret。
• 无明确用户授权的多租户公网生产服务、账号系统、自动扩容、商业账单或平台支付。
• 为追求“全自动”而移除人工中间件、单步入口或失败证据。

3. 术语表

术语	定义
CLI-first	所有正式生产能力先通过可组合的 TypeScript CLI 和工件契约实现，再由其他入口复用。
单步	只执行一个正式生产阶段，并明确读取上游工件、输出结果和失败状态。
区间流水线	在步骤 DAG 中从指定起点到终点运行闭区间内步骤。
异步作业	提交后立即返回标识，在后台运行并通过状态、日志和结果观察的任务。
作业事实	作业请求、状态、进度、步骤状态、时间、日志路径、结果路径、进程和错误的权威记录。
工件清单	记录期次工件路径、媒体类型、字节数、哈希和生成步骤的结构化索引。
配置计划	只读展示有效配置、引用来源和摘要的 CLI 输出，不执行生产变更。
公开目录价估算	按公开模型价格和响应 Token 用量计算的参考成本，不等价于实际账单。
同源控制面	Web 页面和 HTTP API 由同一服务 origin 提供，并读取同一作业与期次事实。
工业控制台	面向生产调试的紧凑高信息密度 Web，使用直角或极小倒角，不复用媒体内容主题。

4. 系统边界和接口

本规格把流水线平台作为生产调度和可观察控制面看待，不接管各内容能力域的正确性定义。

边界项	内容
外部使用者	编辑者、开发调试者、自动化任务、Web 预览用户和发布审核者。
外部输入	owning YAML、CLI/API 请求、期次标识、步骤范围、人工文件、Secret 引用和本地依赖。
受控资源	配置快照、作业记录、日志、结果、期次目录、工件清单、用量记录、服务状态和前端构建。
外部输出	机器可解析 CLI/API 响应、作业进度、日志、结果、工件链接、费用摘要和 Web 控制面。
用户接口	TypeScript CLI、HTTP API、Web 编辑台和文件系统工件。
系统边界	平台负责“如何可靠运行和观察”；各 L1 负责“结果为何正确”。

5. 内部分工与下级索引

编号	模块或课题	规格位置	主责边界	上游依赖	下游支撑
PJ2026-020501	配置治理	本规格 6.1	owning YAML、引用、模式、计划、Secret 边界	全部能力域配置	CLI 调度、作业执行
PJ2026-020502	步骤调度	本规格 6.2	步骤 DAG、单步、区间、完整流程和同一实现	各 L1 步骤契约	作业运行
PJ2026-020503	作业运行	本规格 6.3	异步执行、状态、进度、日志、结果、取消和重试	步骤调度	CLI、API、Web
PJ2026-020504	工件事实	本规格 6.4	期次目录、输入输出、原子落盘、清单、哈希和路径安全	各生产步骤	Web、发布运营
PJ2026-020505	用量成本	本规格 6.5	LLM 请求用量、公开目录价、质量门结果和汇总	编辑策划、价格 YAML	CLI、Web、发布复核
PJ2026-020506	可视控制	本规格 6.6	同源 API、Web、媒体预览、服务生命周期和公网入口	作业事实、工件事实	编辑者和审核者

本章图形描述流水线平台的预期终态数据面。

5.1 目标数据面架构图

flowchart LR
  YAML[owning YAML / configRefs] --> Config[配置校验与有效计划]
  CLI[TypeScript CLI] --> Jobs[异步作业核心]
  API[同源 HTTP API] --> Jobs
  Web[Web 编辑台] --> API
  Config --> Jobs
  Jobs --> Runner[步骤调度器]
  Runner --> Steps[各 L1 正式步骤]
  Steps --> Artifacts[期次工件与清单]
  Steps --> Logs[结构化日志与进度]
  Steps --> Usage[LLM 用量与费用]
  Artifacts --> API
  Logs --> API
  Usage --> API

CLI 和 API 只能通过同一异步作业核心运行步骤。Web 不直接执行媒体命令或修改期次文件，以免形成第二套状态和失败语义。

5.2 目标数据流图

flowchart TD
  Request[CLI / API 作业请求] --> Validate[配置与期次校验]
  Validate --> Job[持久化作业事实]
  Job --> Worker[后台步骤运行器]
  Worker --> Input[读取已登记上游工件]
  Input --> Step[执行选中正式步骤]
  Step --> Progress[进度与结构化日志]
  Step --> Output[原子写入步骤工件]
  Step --> Usage[LLM 用量与费用记录]
  Output --> Result[步骤结果与工件索引]
  Progress --> ReadModel[CLI / API 查询投影]
  Usage --> ReadModel
  Result --> ReadModel
  ReadModel --> Web[Web 编辑台]

作业、日志、用量和工件可以有不同文件，但必须由同一作业标识和期次标识关联。查询投影不得凭空补造步骤成功或媒体工件。

5.3 关键时序图

sequenceDiagram
  participant U as CLI / Web 用户
  participant C as CLI / 同源 API
  participant J as 异步作业核心
  participant W as 后台运行器
  participant S as 正式步骤
  participant A as 作业与期次工件
  U->>C: 提交单步、区间或完整流水线
  C->>J: 校验请求并创建作业
  J->>A: 写入 queued 作业事实
  J-->>C: 立即返回 jobId
  J->>W: 启动后台运行
  loop 每个选中步骤
    W->>S: 传入期次、配置、取消信号
    S->>A: 读取上游并持续写进度日志
    S->>A: 原子写入结果工件
    S-->>W: 返回步骤摘要
  end
  W->>A: 写入终态与结果
  U->>C: 查询 status / logs / result
  C->>A: 读取同一作业事实
  A-->>U: 返回进度、错误或工件

取消必须传播到后台运行器。重试从旧请求创建新作业，不覆盖旧作业的终态、错误、日志和费用。

6. 原子需求

6.1 PLATFORM-L1-REQ-001 YAML-first 配置

编号	短名	主责模块	关联模块
PLATFORM-L1-REQ-001	配置治理	PJ2026-020501 配置治理	资讯源、编辑策划、视觉制作、音频成片

系统应以一个配置入口通过显式 configRefs 引用各职责 owning YAML，并在运行前校验版本、类型、必填字段、枚举、数值范围、路径和引用摘要。

可调业务事实只能由 owning YAML 定义。代码可以提供模式和渲染逻辑，但不得在字段缺失时静默选择另一套模型、来源、端口、语速、视觉主题、质量门或价格。

配置计划和依赖计划必须：

• 只读；
• 输出机器可解析结果；
• 披露引用路径和内容摘要；
• 只报告 Secret 的存在性和非敏感指纹。

Secret 只允许通过受控引用在运行时读取，计划输出不得显示值。

6.2 PLATFORM-L1-REQ-002 可组合单步流水线

编号	短名	主责模块	关联模块
PLATFORM-L1-REQ-002	步骤调度	PJ2026-020502 步骤调度	全部 L1

系统应把以下能力定义为正式步骤：

• 采集、文稿、来源视觉、本地 OCR、画面规划和幻灯；
• 配音、字幕、渲染和检查。

每个步骤必须有明确上游工件、下游工件、进度、日志、结果和失败契约，并可以通过 TypeScript CLI 独立运行。

流水线组合必须遵守：

• 完整流水线和区间流水线调用同一单步实现；
• 不复制步骤逻辑；
• from 和 to 形成合法闭区间；
• 上游工件缺失或不合法时明确失败；
• 不跨期次查找旧文件补齐。

模板文稿模式应作为显式作业参数传递，只影响需要 LLM 的步骤。下游步骤消费统一文稿工件，不需要知道文稿来自 LLM 还是模板。

6.3 PLATFORM-L1-REQ-003 可观察异步作业

编号	短名	主责模块	关联模块
PLATFORM-L1-REQ-003	作业运行	PJ2026-020503 作业运行	全部 L1

所有耗时生产命令应采用 Fire-and-Forget：提交后立即返回作业标识，后台执行，用户通过状态、日志和结果观察，不在 CLI 前台等待网络、LLM、TTS、浏览器或编码完成。

作业事实至少包含：

• 请求、重试来源、排队、开始和结束时间；
• 进程、活动步骤、总进度和步骤状态；
• 日志、结果和结构化错误。

长步骤应持续更新进度，不允许数分钟只显示“运行中”而没有可判断位置的消息。

取消只作用于指定活动作业并向步骤传播信号。重试创建新的作业标识、保留旧请求和失败证据；已结束作业不能因取消或重试被改写为未发生。

6.4 PLATFORM-L1-REQ-004 稳定期次与工件契约

编号	短名	主责模块	关联模块
PLATFORM-L1-REQ-004	工件事实	PJ2026-020504 工件事实	发布运营、全部生产 L1

系统应以安全期次标识隔离每一期输入和输出，并保存标题、期数、报道日期和创建时间。正式工件路径应固定、可枚举、可校验，禁止路径穿越和跨期次隐式读取。

步骤完成时应登记：

• 工件相对路径和媒体类型；
• 字节数和 SHA-256。

最终清单应覆盖来源、文稿、视觉、音频、字幕、视频、时间线、用量、引用和检查报告。Web 与发布运营不应重新扫描和猜测文件类型。

正式媒体和关键 JSON 应原子落盘。中断时允许保留明确标记的可恢复缓存，但不能让半写文件被登记为成功工件。

6.5 PLATFORM-L1-REQ-005 完整 LLM 用量与成本

编号	短名	主责模块	关联模块
PLATFORM-L1-REQ-005	用量成本	PJ2026-020505 用量成本	编辑策划、发布运营

系统应为每次 LLM 请求记录期次、作业、尝试、请求标识、请求模型、响应模型、服务层、时间、HTTP 状态、用量状态、Token 明细、质量门结果和费用估算。

Token 明细至少区分：

• 输入、缓存输入和缓存写入；
• 输出、推理和总量。

成功接受、质量门拒绝、HTTP 失败、缺失用量和无效用量都应形成记录。任何失败尝试不能从期次汇总中静默消失。

模型价格管理要求如下：

• owning YAML 中的价格从公开官方页面核验；
• 保留币种、单位、服务层、长上下文阈值、抓取时间和来源；
• 未知模型、未知服务层或缺失用量标记为无法估价；
• 无法估价时给出 warning，不能按零元处理；
• CLI 和 Web 明确这是公开目录价估算，而非实际账单。

6.6 PLATFORM-L1-REQ-006 同源可视控制面

编号	短名	主责模块	关联模块
PLATFORM-L1-REQ-006	可视控制	PJ2026-020506 可视控制	发布运营、全部生产 L1

系统应在 CLI 完整流程可用后提供前后端可视控制面，通过同源 API 展示期次、步骤 DAG、作业、进度、日志、错误、用量和全部工件，并支持与 CLI 等价的受控动作。

Web 工厂和控制台应采用工业风视觉：

• 紧凑高信息密度；
• 清晰的数据表、状态区、分栏和终端区域；
• 直角或极小倒角；
• 克制的状态色和低装饰背景；
• 不复用生成内容的暖色大圆角、纸纹和宽松卡片布局。

单步执行卡片应满足：

• 只展示步骤信息和状态；
• 卡片本身不得触发运行；
• 每张卡片提供独立运行按钮；
• 点击运行按钮后弹出确认框；
• 确认框明确期次、步骤和预期覆盖范围后才能提交作业。

Web 应提供视觉计划审查入口。

自动重点区域不能由 OCR 或来源事实验证时，编辑者可以：

• 手工调整矩形；
• 手工调整出现时段和放大倍率；
• 单步重跑幻灯或渲染。

音频和视频工件应支持 HTTP Range 以便拖动预览。Web 应在桌面和窄屏可用，不以颜色单独表达状态，不依赖外部字体、分析脚本或付费生成服务。

服务入口要求如下：

• 监听、端口、轮询和健康超时由 owning YAML 配置；
• 公网 IPv4 直连只能用于临时验收；
• 明文 HTTP 且无鉴权时必须明确风险；
• 持续公开服务应由对应规格明确 TLS、访问控制和发布权限；
• 不能把临时公网入口默认升级为多用户生产服务。

7. 过程控制

7.1 实现引用契约

• 相关源码文件应标记：
  • SPEC: PJ2026-0205 流水线平台 draft-2026-07-13-p0。
• 自动生成文件、纯配置、锁文件和二进制工件可以不加文件头：
  • 对应生成器、校验器或 owning YAML 入口必须能追溯到本规格。
• 实现状态、源码路径、期次工件和运行证据只进入阶段报告、任务报告、偏离记录或执行 issue。

7.2 原入口验收

• 运行配置计划、价格计划、依赖检查和步骤列表，验证输出可解析且不泄露 Secret。
• 创建独立期次，分别验证一个单步、一个区间流水线和一个默认完整流水线。
• 在作业运行中查询状态和日志，确认活动步骤、分子分母进度、耗时和错误可见。
• 验证失败、取消和重试：
  • 旧作业事实保留；
  • 新作业具有不同标识；
  • 不产生半写正式工件。
• 构建并启动同源 Web，检查桌面、窄屏、媒体 Range、章节跳转、用量、费用和全部工件。
• 验证步骤卡片本身不可点击，独立运行按钮提交前出现确认框。
• 验证视觉计划可审查，低置信重点区域可以手工调整并单步重跑。

7.3 安全和运行控制

• API key、凭据正文和敏感请求内容不得出现在 CLI、日志、工件或 Web。
• 公网服务未配置 TLS 和访问控制时只用于有界验收，不存放不应公开的草稿或来源原始响应。
• 服务状态、健康和日志必须可通过受控 CLI 查看；非明确要求不以手工进程和临时端口替代正式入口。
• 依赖版本、模型文件和哈希变化先更新 owning YAML，再执行安装计划和检查。
• 平台错误不得通过降低各 L1 质量门、跳过工件或伪造作业成功来缓解。

7.4 回写边界

• 某步骤结果业务错误回写拥有该结果定义的 L1，不因表面发生在 CLI 或 Web 就归平台。
• 只有完成标准是配置、调度、状态、日志、结果、成本、工件索引或控制面行为时，才主归属本 L1。
• 发布批准和平台投放归 发布运营。
• 稳定步骤、作业、用量或工件契约变化时先更新本规格，再进入实现。