mirrors/pikasTech-unidesk

Fork 0

Files

T

AgentRun Codex 154d09a115 docs: 完成 PJ2026-02 终态规格审查

2026-07-13 07:29:32 +00:00

20 KiB

Raw Permalink Blame History

PJ2026-0207 平台交付需求规格

修改历史

版本	更新日期	变更说明
v0.1	2026-07-13	定义 Web 内置 Codex、隔离凭据、受控 K8s 部署、自动交付和运行验收的目标能力。

正文

PJ2026-0207 平台交付需求规格

1. 文档控制

字段	内容
编号	PJ2026-0207
短名	平台交付
层级	L1 方向
规格状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-02 智媒工厂总规格
规格治理索引	PJ2026-02 智媒工厂总规格第 7 章

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版。

正文边界如下：

只定义受控交付平台的预期终态、目标能力和验收契约；
不记录当前运行方式或实现进度。

2. 目的和范围

2.1 目的

平台交付的目标是：

以可复现、隔离、最小权限和自动验收的方式交付到 Kubernetes 运行面；
让用户从 Web 内置终端进入与后端版本一致的 Codex 工作环境；
在容器中提供随镜像交付的源码、CLI 和受限工具；
通过 YAML-first 配置、GitOps 自动链和公网 IP 原入口持续交付。

2.2 预期终态

平台交付终态必须具备：

可从智媒工厂 Web 直接访问的内置 Codex 终端；
包含版本化源码、TypeScript CLI 和运行依赖的后端容器；
通过 PVC 持久化的 Codex session、supervisor 恢复元数据和重启自动续接；
YAML-first Secret sourceRef 到 ~/.env/TOKEN 的独立只读投影；
受控 ~/.codex/*.pika 源路径到运行时 Codex home 的独立模型配置与 API key 投影；
无 ServiceAccount token、无 kubeconfig、无 Kubernetes 或主机权限的终端沙箱；
GitHub、mirror、PaC、Tekton、GitOps 和 Argo 组成的自动交付链；
由 owning YAML 选定公网 IPv4 原入口执行的部署后运行验收。

2.3 范围内

Web 内置终端、Codex 进程、会话身份、终端重连和用户可见状态。
与已部署后端版本一致的容器镜像、源码快照、TypeScript CLI 和运行依赖。
面向 Agent 的受限 Skill、HTTP API 和工件访问能力。
PVC 上的 ~/.codex/sessions、supervisor 恢复元数据、自动恢复和滚动重启续接。
后端 API ~/.env/TOKEN 的 YAML-first sourceRef、运行时投影、权限和脱敏。
Codex 模型配置与 API key 从受控 ~/.codex/*.pika 源路径到运行时 Codex home 的独立投影。
无 ServiceAccount token、无 kubeconfig、无 Kubernetes 管理能力和无主机权限的隔离边界。
YAML-first Kubernetes 工作负载、服务、健康检查、资源限制和公网 IP 暴露。
GitHub、镜像、Pipeline as Code、Tekton、GitOps、Argo 和部署后验收的自动链。

2.4 范围外

允许 Codex 或终端用户直接运行 kubectl、读取集群凭据或修改 Kubernetes 对象。
向终端挂载宿主机目录、容器运行时套接字、主机网络、主机进程或特权设备。
在镜像、Git 仓库、日志、工件、ConfigMap、环境变量列表或 Web 响应中保存明文 Token。
让流水线构建步骤直接修改生产 Deployment，或让 Argo 从未经构建验证的工作区读取源码。
把临时 NodePort、手工 SSH、手工复制镜像或主机进程作为正式交付真相。
多租户计费、开放注册和互联网任意用户的共享终端；这些需要独立身份与运营规格。

3. 术语表

术语	定义
内置终端	由工业风智媒工厂 Web 提供、连接到受控后端会话的紧凑浏览器终端。
Agent 工具面	Codex 在容器内可调用的源码、CLI、受限 Skill、HTTP API 和工件入口集合。
会话 PVC	只保存 `~/.codex/sessions` 与 supervisor 恢复元数据的持久卷，不保存源码工作区或集群管理凭据。
自动恢复	终端或后端容器重启后，根据 PVC 中的 Codex session 与 supervisor 恢复元数据续接会话。
`sourceRef`	owning YAML 对外部 Secret 对象、键和目标文件的声明式引用。
`~/.env/TOKEN`	容器用户家目录下由 Secret 运行时投影生成的 Token 文件目标，不进入镜像或源码。
运行时 Codex home	容器内供 Codex 读取模型配置和 API key 的专用目录，只接收受控 `~/.codex/*.pika` 源路径投影。
PaC	Pipeline as Code；把 Git 变更映射为受审查 Tekton 流水线运行的入口。
GitOps	以声明式目标配置仓库作为部署期望状态，由控制器协调运行面。
公网 IP 原入口	用户实际访问的公网 IPv4 Web、API 和终端入口，用于部署后验收。

4. 系统边界和接口

本规格把平台交付作为智媒工厂的受控运行与持续交付能力看待，不重新定义内容生产步骤的业务正确性。

边界项	内容
外部使用者	智媒编辑者、受控 Codex Agent、发布审核者和交付自动化。
外部输入	GitHub 提交、owning YAML、镜像上下文、后端 Secret `sourceRef`、Codex 配置 `sourceRef`、期次工件和终端动作。
受控资源	后端容器、Web 终端、会话 PVC、运行时 Codex home、受限工具、镜像摘要、GitOps 目标、K8s 工作负载和验收记录。
外部输出	公网 IP Web/API/终端、可恢复 Codex session、部署版本、健康状态、自动交付轨迹和验收结论。
用户接口	Web 内置终端、TypeScript CLI、同源 HTTP API、公网 IPv4 和只读交付状态。
系统边界	平台拥有应用交付和会话恢复；Agent 只拥有内容工作区和受限工具，不拥有集群或主机控制权。

5. 内部分工与下级索引

编号	模块或课题	规格位置	主责边界	上游依赖	下游支撑
PJ2026-020701	内置终端	本规格 6.1	Web 终端、Codex 进程、会话连接、重连和用户状态	Web、后端容器、会话 PVC	编辑调试
PJ2026-020702	Agent 工具	本规格 6.2	版本化源码、TypeScript CLI、受限 Skill/API 和工件访问	构建产物、流水线平台	Codex Agent
PJ2026-020703	隔离凭据	本规格 6.3	两类凭据的独立投影、权限、脱敏和负面边界	owning YAML、外部 Secret	内置终端、Agent 工具
PJ2026-020704	受控部署	本规格 6.4	YAML-first K8s 工作负载、资源、健康和公网 IP	镜像摘要、配置与 Secret 引用	自动交付、运行验收
PJ2026-020705	自动交付	本规格 6.5	GitHub、mirror、PaC、Tekton、GitOps 和 Argo 链	源码与 owning YAML	受控部署
PJ2026-020706	运行验收	本规格 6.6	公网原入口、版本、终端、恢复、隔离和自动链证据	全部平台交付模块	发布运营、平台维护者

本章图形全部描述平台交付的预期终态数据面。

5.1 目标数据面架构图

flowchart LR
  subgraph Delivery[自动交付控制面]
    GitHub[GitHub 源码]
    Mirror[受控镜像]
    PaC[Pipeline as Code]
    Tekton[Tekton 构建与验证]
    Registry[摘要固定镜像]
    GitOps[GitOps 目标配置]
    Argo[Argo 协调]
  end
  subgraph Runtime[Kubernetes 应用数据面]
    Public[公网 IPv4 Service]
    Web[Web 与同源 API]
    Terminal[终端会话代理]
    Backend[后端容器、源码与 CLI]
    PVC[会话 PVC]
    BackendSecret[只读后端 Token 投影]
    CodexSecret[只读 Codex 配置投影]
  end
  GitHub --> Mirror
  Mirror --> PaC
  PaC --> Tekton
  Tekton --> Registry
  Tekton --> GitOps
  GitOps --> Argo
  Argo --> Backend
  Registry --> Backend
  Public --> Web
  Web --> Terminal
  Terminal --> Backend
  Backend --> PVC
  BackendSecret --> Backend
  CodexSecret --> Backend

自动交付控制面拥有构建和部署协调权限。应用数据面不获得控制面凭据，Codex 只能在后端容器的受控工作区内运行。

5.2 目标数据流图

flowchart TD
  SourceVersion[GitHub 交付源版本] --> Sync[mirror 同步]
  Sync --> Build[PaC 触发 Tekton]
  Build --> Test[源码、CLI 与镜像验证]
  Test --> Digest[不可变镜像摘要]
  Digest --> Desired[更新 GitOps 期望状态]
  Desired --> Reconcile[Argo 协调 K8s]
  Config[owning YAML] --> Render[受控配置渲染]
  BackendRef[后端 Token sourceRef] --> Render
  CodexRef[Codex pika sourceRef] --> Render
  Render --> Reconcile
  Reconcile --> Pod[后端 Pod]
  Pod --> Token[只读 ~/.env/TOKEN]
  Pod --> CodexHome[运行时 Codex home]
  Pod --> Session[PVC Codex sessions 与恢复元数据]
  Browser[公网 IP 浏览器] --> Web[Web 内置终端]
  Web --> Codex[容器内 Codex]
  CodexHome --> Codex
  Codex --> Session
  Codex --> Tools[受限 Skill / API / CLI]
  Pod --> Acceptance[部署后运行验收]

Secret 数据不经过 GitHub、mirror、构建日志或 GitOps 明文：

后端 API Token 独立投影到 ~/.env/TOKEN；
Codex 模型配置和 API key 从受控 ~/.codex/*.pika 源路径投影到运行时 Codex home；
两类凭据不得共享目标文件、环境变量或日志字段。

5.3 自动交付关键时序图

sequenceDiagram
  participant G as GitHub
  participant M as mirror / PaC
  participant T as Tekton
  participant R as 镜像仓库
  participant O as GitOps 目标仓库
  participant A as Argo
  participant K as Kubernetes
  participant V as 运行验收
  G->>M: 推送受审查提交
  M->>T: 触发交付源版本固定的 PipelineRun
  T->>T: 校验源码、CLI、镜像和配置
  T->>R: 发布不可变镜像摘要
  T->>O: 提交摘要固定的目标配置
  O->>A: 目标 revision 可见
  A->>K: 协调 Deployment、Service 与 Secret 引用
  K-->>A: rollout 健康
  A->>V: 触发部署后原入口验收
  V->>K: 通过公网 IP 检查 Web、API、终端与恢复
  V-->>A: 返回通过或明确阻塞

Tekton 不直接修改生产工作负载。只有经过验证并写入 GitOps 目标的镜像摘要，才由 Argo 协调到运行面。

5.4 终端恢复关键时序图

sequenceDiagram
  participant U as 编辑者浏览器
  participant W as Web / 终端代理
  participant B as 后端容器
  participant P as 会话 PVC
  participant C as Codex CLI
  U->>W: 打开内置终端
  W->>B: 创建或连接会话
  B->>P: 读取 Codex sessions 与 supervisor 元数据
  alt 存在可续接 session
    B->>C: 使用稳定 sessionId 恢复
  else 新会话
    B->>C: 创建 Codex session
    C->>P: 保存 Codex session
    B->>P: 保存 supervisor 恢复元数据
  end
  C-->>U: 流式终端输出
  B--xW: Pod 滚动重启或连接中断
  U->>W: 自动重连
  W->>B: 连接新容器实例
  B->>P: 恢复 session 与 supervisor 状态
  B->>C: 续接既有 session
  C-->>U: 返回恢复后的终端状态

自动恢复只读取 PVC 中的业务会话事实。恢复过程不得依赖旧 Pod 内存、宿主机目录、ServiceAccount token 或 kubeconfig。

6. 原子需求

6.1 DELIVERY-L1-REQ-001 Web 内置 Codex 终端

编号	短名	主责模块	关联模块
DELIVERY-L1-REQ-001	内置终端	PJ2026-020701 内置终端	流水线平台、PJ2026-020703 隔离凭据

平台应在智媒工厂 Web 内提供可访问的 Codex 终端，使编辑者能够从同一公网 IP 入口进入与后端版本一致的内容生产环境。

内置终端和相邻控制区应遵循控制台视觉边界：

工业风；
紧凑高信息密度；
直角或极小倒角；
优先展示连接、session、进程、命令和错误状态；
不使用生成 HTML、PPT 和视频的暖色大圆角卡片主题。

终端应显示：

连接、启动和运行状态；
重连、恢复、失败和关闭状态。

浏览器关闭或网络短暂中断不应自动终止后台 Codex session。重新连接时应回到同一业务会话，不能伪造新的空终端。

专用 PVC 应保存：

~/.codex/sessions；
supervisor 恢复元数据。

会话 PVC 不承担源码工作区持久化。

需要跨重启保存的源码变更必须进入受控变更流。未来如需持久化源码工作区，应另行定义：

数据生命周期；
版本冲突处理；
回收要求。

后端容器或 Pod 重启后，平台应自动发现并续接可恢复会话。恢复失败时输出明确原因，不以新会话冒充恢复成功。

6.2 DELIVERY-L1-REQ-002 版本一致的 Agent 工具面

编号	短名	主责模块	关联模块
DELIVERY-L1-REQ-002	Agent 工具	PJ2026-020702 Agent 工具	流水线平台、发布运营

后端容器镜像应包含与部署交付源版本一致的智媒工厂源码和工具链：

TypeScript CLI；
运行依赖；
必要开源媒体工具。

Codex 应能在容器内执行正式单步、查看作业和复核工件。

Agent 工具面只暴露 owning YAML 允许的：

Skill；
CLI 子命令；
同源 HTTP API；
期次工件路径。

工具策略应声明允许动作、只读或写入边界、超时和输出脱敏。没有声明的外部 API、集群入口和主机能力默认不可用。

镜像内源码是版本化实现参考，不是运行时可变部署真相：

Codex 不能直接改写已部署容器层或 GitOps 目标；
需要持久化的源码修改必须进入受控变更流；
会话 PVC 不保存源码工作副本。

6.3 DELIVERY-L1-REQ-003 YAML-first 隔离凭据

编号	短名	主责模块	关联模块
DELIVERY-L1-REQ-003	隔离凭据	PJ2026-020703 隔离凭据	PJ2026-020701 内置终端、PJ2026-020702 Agent 工具、PJ2026-020704 受控部署

凭据必须由 owning YAML 使用 sourceRef、targetKey 和目标路径声明，并分成两个互不复用的投影：

后端 API Token：
- 从受控 Secret sourceRef 读取；
- 只读投影到容器用户的 ~/.env/TOKEN。
Codex 模型配置和 API key：
- 从受控 ~/.codex/*.pika 源路径对应的独立 sourceRef 读取；
- 投影到运行时 Codex home 中 Codex 需要的配置和认证目标；
- 不与后端 API Token 共用 Secret 对象、targetKey、目标文件或环境变量。

两类文件权限都应限制为容器用户可读，凭据值不得进入镜像、Git、ConfigMap、日志、规格或 Web。

日志、规格、状态和验收输出只允许披露：

sourceRef；
targetKey；
presence；
非敏感 fingerprint。

平台不得保存、回显或从运行中 Pod、环境变量、进程参数、日志和工件反解凭据值。

终端和后端 Pod 必须满足以下负面边界：

automountServiceAccountToken: false 或等价禁止挂载；
不包含 kubeconfig、云控制面凭据或 Kubernetes 客户端配置；
不允许访问 Kubernetes API、宿主机文件、容器运行时套接字和特权设备；
不使用 hostPath、hostNetwork、hostPID、hostIPC 或特权容器；
只挂载声明的会话 PVC、只读配置和两类相互隔离的只读 Secret 文件。

6.4 DELIVERY-L1-REQ-004 YAML-first 受控部署

编号	短名	主责模块	关联模块
DELIVERY-L1-REQ-004	受控部署	PJ2026-020704 受控部署	PJ2026-020703 隔离凭据、PJ2026-020705 自动交付

owning YAML 应定义：

目标集群、命名空间和镜像摘要；
配置引用、Secret sourceRef 和 PVC；
资源限制、健康检查、服务和公网暴露。

代码或手工命令中不得保留第二套部署事实。

Kubernetes 工作负载应：

使用非 root 用户；
使用只读根文件系统或等价最小写面；
明确 CPU、内存和临时存储限制；
把可写内容限制在声明的会话 PVC 和必要临时目录。

公网入口应通过 YAML 声明的 IPv4 和端口暴露：

Web；
同源 API；
终端代理。

验收使用该公网 IP 原入口，不以 Pod IP、端口转发、SSH、临时 NodePort 或集群内部地址替代。

6.5 DELIVERY-L1-REQ-005 GitOps 自动交付链

编号	短名	主责模块	关联模块
DELIVERY-L1-REQ-005	自动交付	PJ2026-020705 自动交付	PJ2026-020704 受控部署、PJ2026-020706 运行验收

平台应建立以下自动交付链：

GitHub 提交进入受控 mirror；
Pipeline as Code 触发交付源版本固定的 Tekton 流水线；
Tekton 验证源码、CLI、配置和镜像；
验证通过后发布不可变镜像摘要；
更新 GitOps 目标；
Argo 协调 Kubernetes。

交付职责边界如下：

mirror 只提供受控源码同步，不成为可手工修改的第二真相；
Tekton 负责构建、检查和产物发布，不直接修改生产 Deployment；
Argo 只消费通过审核和验证的 GitOps 目标 revision。

任何链路失败都应保留以下对象之间的追溯关系：

交付源版本；
流水线；
镜像摘要；
GitOps revision；
Argo 协调；
运行验收。

自动重试不能跳过失败门禁或回退到手工复制。

6.6 DELIVERY-L1-REQ-006 公网原入口运行验收

编号	短名	主责模块	关联模块
DELIVERY-L1-REQ-006	运行验收	PJ2026-020706 运行验收	本规格 6.1 至 6.5

每次自动交付完成后，平台应从 YAML 选中的公网 IPv4 原入口验证健康、Web、同源 API、内置终端、Codex 启动、正式 CLI、工件读取和版本可见性。

运行验收应完成以下会话恢复检查：

主动触发一次有界终端会话并记录 sessionId；
执行无外部写入的 CLI 只读命令；
重启或滚动更新后端；
验证同一 session 依靠 PVC 中的 Codex sessions 与 supervisor 元数据自动恢复。

安全负面验收至少检查：

容器没有 ServiceAccount token 和 kubeconfig；
不能访问 Kubernetes API；
没有宿主机目录、容器运行时套接字、主机命名空间或特权能力；
~/.env/TOKEN 只报告 sourceRef、targetKey、presence 和 fingerprint；
运行时 Codex home 的 pika 配置只报告 sourceRef、targetKey、presence 和 fingerprint；
两类凭据值都不出现在日志、规格、API、终端回显或工件；
运行交付源版本、镜像摘要、GitOps revision 和公网验收结果可以关联。

7. 过程控制

7.1 追溯契约

每个部署版本应能追溯到交付源版本、镜像摘要、GitOps 目标、运行版本和验收结论。
纯 YAML、生成文件、锁文件和二进制镜像应由 owning YAML、渲染器、容器构建入口或交付流水线提供稳定归属。

7.2 安全门禁

发现 ServiceAccount token、kubeconfig、Kubernetes API 可达、hostPath、容器套接字或特权能力时，运行验收必须失败。
任一后端或 Codex 凭据值出现在日志、规格、终端、API、工件或镜像层时，必须停止交付并轮换受影响凭据。
终端不能直接调用部署控制面；需要部署动作时只能通过受控自动交付入口产生可审查变更。
受限 Skill/API 策略变化先更新 owning YAML；扩大集群或主机权限必须先更新本规格并重新评审边界。

7.3 原入口验收

使用公网 IPv4 打开 Web 并创建 Codex 终端。
验证容器内交付源版本、CLI 版本和已部署镜像摘要一致。
通过终端执行配置计划、步骤列表或等价只读命令。
重启后端 Pod，验证同一 sessionId 和终端上下文依靠 PVC 中的 Codex sessions 与 supervisor 元数据恢复。
检查 ~/.env/TOKEN 的 sourceRef、targetKey、presence、文件权限和 fingerprint。
检查运行时 Codex home 的 pika 配置 sourceRef、targetKey、presence、文件权限和 fingerprint。
不读取、保存或输出任一凭据值。
运行权限负面检查和 GitHub 到 Argo 的交付追溯检查。

7.4 回写边界

内容步骤、作业、日志或工件契约问题回写流水线平台。
发布包、人工批准和平台发布材料问题回写发布运营。
Web 终端、容器、凭据隔离、Kubernetes、自动链和部署后验收主归属本 L1。
稳定安全边界、部署数据流、自动链或原入口验收变化时，先更新本规格和 L0 总规格。

20 KiB Raw Permalink Blame History Unescape Escape

PJ2026-0207 平台交付需求规格

修改历史

正文

PJ2026-0207 平台交付需求规格

1. 文档控制

2. 目的和范围

2.1 目的

2.2 预期终态

2.3 范围内

2.4 范围外

3. 术语表

4. 系统边界和接口

5. 内部分工与下级索引

5.1 目标数据面架构图

5.2 目标数据流图

5.3 自动交付关键时序图

5.4 终端恢复关键时序图

6. 原子需求

6.1 DELIVERY-L1-REQ-001 Web 内置 Codex 终端

6.2 DELIVERY-L1-REQ-002 版本一致的 Agent 工具面

6.3 DELIVERY-L1-REQ-003 YAML-first 隔离凭据

6.4 DELIVERY-L1-REQ-004 YAML-first 受控部署

6.5 DELIVERY-L1-REQ-005 GitOps 自动交付链

6.6 DELIVERY-L1-REQ-006 公网原入口运行验收

7. 过程控制

7.1 追溯契约

7.2 安全门禁

7.3 原入口验收

7.4 回写边界

20 KiB

Raw Permalink Blame History