AgentRun Codex
17 KiB
17 KiB
PJ2026-0205 流水线平台需求规格
修改历史
| 版本 | 更新日期 | 变更说明 |
|---|---|---|
| v0.1 | 2026-07-13 | 定义 YAML-first、TypeScript CLI、异步作业、用量计费和 Web 编辑台的目标能力。 |
正文
PJ2026-0205 流水线平台需求规格
1. 文档控制
| 字段 | 内容 |
|---|---|
| 编号 | PJ2026-0205 |
| 短名 | 流水线平台 |
| 层级 | L1 方向 |
| 规格状态 | 已生效 |
| 需求规格模板 | 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 追溯契约
- 每个步骤、作业、尝试、用量记录和正式工件应能追溯到期次、配置引用摘要和上游结果。
- 自动生成文件、纯配置、锁文件和二进制工件应由对应生成器、校验器或 owning YAML 提供稳定归属。
7.2 原入口验收
- 运行配置计划、价格计划、依赖检查和步骤列表，验证输出可解析且不泄露 Secret。
- 创建独立期次，分别验证一个单步、一个区间流水线和一个默认完整流水线。
- 在作业运行中查询状态和日志，确认活动步骤、分子分母进度、耗时和错误可见。
- 验证失败、取消和重试：
- 旧作业事实保留；
- 新作业具有不同标识；
- 不产生半写正式工件。
- 构建并启动同源 Web，检查桌面、窄屏、媒体 Range、章节跳转、用量、费用和全部工件。
- 验证步骤卡片本身不可点击，独立运行按钮提交前出现确认框。
- 验证视觉计划可审查，低置信重点区域可以手工调整并单步重跑。
7.3 安全和运行控制
- API key、凭据正文和敏感请求内容不得出现在 CLI、日志、工件或 Web。
- 公网服务未配置 TLS 和访问控制时只用于有界验收，不存放不应公开的草稿或来源原始响应。
- 服务状态、健康和日志必须可通过受控 CLI 查看；非明确要求不以手工进程和临时端口替代正式入口。
- 依赖版本、模型文件和哈希变化先更新 owning YAML，再执行安装计划和检查。
- 平台错误不得通过降低各 L1 质量门、跳过工件或伪造作业成功来缓解。
7.4 回写边界
- 某步骤结果业务错误回写拥有该结果定义的 L1，不因表面发生在 CLI 或 Web 就归平台。
- 只有完成标准是配置、调度、状态、日志、结果、成本、工件索引或控制面行为时，才主归属本 L1。
- 发布批准和平台投放归 发布运营。
- 稳定步骤、作业、用量或工件契约变化时先更新本规格，再进入实现。