pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010202-runtime-assembly.md

# PJ2026-010202 Runtime装配

## 修改历史

| 版本 | 对应 commit id | 更新日期 | 变更说明 |
| --- | --- | --- | --- |

当前正文仍在规格治理草稿中；未定稿前不新增版本号，不为单次编辑追加 `待提交` 版本。

## 正文

## PJ2026-010202 Runtime装配需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010202 |
| 短名 | Runtime装配 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0102 Agent编排](PJ2026-0102-agent-orchestration.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 RuntimeAssembly、SecretRef、AipodSpec、gitbundle、session 和工具凭据装配的稳定使命、范围、术语、系统边界、内部分工和原子需求。

## 2. 目的和范围

### 2.1 目的

Runtime装配负责把一次 AgentRun 执行需要的镜像、provider profile、session、Git 资源、prompt、skills、tools 和工具凭据统一为受控 RuntimeAssembly，使 runner/backend 启动前的所有运行输入都有可追溯来源和明确边界。

### 2.2 范围内

- `BackendImageRef`、`ProfileRef`、`SessionRef`、`ResourceBundleRef` 四个一等运行时要素。
- provider credential、Git resource credential、tool credential 和 short-lived execution context 的 SecretRef/projection/redaction 归属。
- Git-only `ResourceBundleRef.kind="gitbundle"`、`bundles[]`、`promptRefs[]`、`requiredSkills[]`、workspace materialization 和实际 commit 摘要。
- AipodSpec YAML、`imageRef`、env image reuse、Artificer 默认装配和 `--aipod` render 入口。
- SessionRef 到 PVC 直接挂载、`CODEX_HOME`、profile runtime home 和 Secret projection 分离。

### 2.3 范围外

- run、command、event、runner lease 和 terminal status 的 durable authority 归 [AgentRun核心](PJ2026-010201-agentrun-core.md)。
- Codex app-server stdio、backend adapter 和 provider profile 管理归 [后端Profile](PJ2026-010204-backend-profile.md)。
- Queue task、Session API 和 scheduler 归 [队列会话](PJ2026-010203-queue-session.md)。
- YAML-first 平台配置真相、Secret sourceRef 下发和公共 ops primitive 归 [YAML运维](PJ2026-010603-yaml-first-ops.md)。
- GitOps、CI/CD、lane 和发布验收归 [发布流水](PJ2026-010601-controlled-release.md)，source truth 和 mirror 归 [源码同步](PJ2026-010602-source-sync.md)。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| RuntimeAssembly | runner/backend 启动前的装配模型，声明一次执行使用的镜像、profile、session、资源包和凭据范围。 |
| BackendImageRef | 描述 env/backend/runner 镜像来源和 digest-pinned image 的运行时要素。 |
| ProfileRef | 描述 backend profile 与 provider credential SecretRef 的运行时要素。 |
| SessionRef | 描述 backend 会话、thread、PVC 和续跑状态的运行时要素。 |
| ResourceBundleRef | 描述 Git-only 资源包、工具、skill、prompt 和实际物化 commit 的运行时要素。 |
| AipodSpec | 声明式 agent 装配 YAML，用于集中描述 imageRef、backendProfile、executionPolicy、resourceBundleRef 和 payloadDefaults。 |
| toolCredentials | 运行时工具授权的 SecretRef 装配项，例如 GitHub PR token、GitHub SSH key 或 UniDesk SSH passthrough token。 |
| transientEnv | 单次 runner job 的短期运行上下文，通过短期 Secret 投影，不作为 run durable fact。 |

## 4. 系统边界和接口

本规格把 Runtime装配作为 AgentRun 运行输入的装配系统看待；本章只描述输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | AgentRun核心、队列会话、HWLAB接入、后端Profile、runner job 和平台运维。 |
| 外部输入 | AipodSpec、run executionPolicy、backendProfile、SecretRef、gitbundle repo/ref、promptRefs、requiredSkills、sessionRef、toolCredentials 和 transientEnv。 |
| 受控资源 | RuntimeAssembly、Secret projection intent、git materialization、workspace、runtime home、session PVC、image identity 和 redacted assembly summary。 |
| 外部输出 | backend image digest/source、profile SecretRef 摘要、session/PVC 摘要、actual commit、bundle/skill/tool 摘要、projection intent 和 `valuesPrinted=false`。 |
| 用户接口 | AgentRun run 创建、Queue dispatch、Session send、AipodSpec render/apply 和 runner job dry-run。 |
| 系统边界 | Runtime装配负责运行输入的受控声明、解析和投影；不执行 backend turn，不决定业务授权，不把 Secret value、host path 或 prompt 内隐式环境变成运行事实。 |

## 5. 内部分工与规格索引

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-01020201 | 四要素模型 | 本规格 6.1 | BackendImageRef、ProfileRef、SessionRef、ResourceBundleRef 字段和边界 | AgentRun 核心 run policy | Runner、Backend、HWLAB 接入 |
| PJ2026-01020202 | Secret投影 | 本规格 6.2 | provider/tool/Git credential、projection 和 redaction | YAML运维、平台 Secret 来源 | Runner、Backend、Provider Profile |
| PJ2026-01020203 | GitBundle物化 | 本规格 6.3 | repo/ref、actual commit、bundles、promptRefs、skills、tools | Git mirror、AipodSpec、HWLAB repo | Backend、HarnessRL、Agent 执行 |
| PJ2026-01020204 | Session持久 | 本规格 6.4 | SessionRef、threadId、PVC 直接挂载和 profile 隔离 | AgentRun 核心 session facts | Queue会话、HWLAB接入 |
| PJ2026-01020205 | AipodSpec | 本规格 6.5 | imageRef、backendProfile、executionPolicy、resourceBundleRef 和 payloadDefaults | 发布流水 env image、源码同步 source truth | Queue会话、Session send、Artificer |

## 6. 原子需求

### 6.1 AR-RUNTIME-REQ-001 四要素装配模型

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-RUNTIME-REQ-001 | 四要素模型 | PJ2026-01020201 四要素模型 | [AgentRun核心](PJ2026-010201-agentrun-core.md)、[后端Profile](PJ2026-010204-backend-profile.md) |

Runtime装配应将一次执行收敛为 `BackendImageRef`、`ProfileRef`、`SessionRef` 和 `ResourceBundleRef` 四个一等要素，使 runner/backend 启动前能够明确镜像、profile、session 和资源来源。

executionPolicy、observabilityPolicy、tool credential、initial prompt、skill 注入、network 和 GC 不应成为第五个杂项运行时路径；它们必须归属到四要素或 run policy，并可追溯到 Git、SecretRef、配置引用或显式 null。

### 6.2 AR-RUNTIME-REQ-002 SecretRef 与敏感输出

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-RUNTIME-REQ-002 | Secret投影 | PJ2026-01020202 Secret投影 | [YAML运维](PJ2026-010603-yaml-first-ops.md)、[后端Profile](PJ2026-010204-backend-profile.md)、[发布流水](PJ2026-010601-controlled-release.md) |

Runtime装配应通过 SecretRef 和 projection intent 分发 provider credential、Git resource credential、tool credential 和短期 transientEnv，使 Secret value 不进入 Git source、GitOps branch、Postgres、event、trace、日志或 CLI 输出。

输出只能包含 SecretRef 名称、key 名、projection kind、presence、hash/fingerprint、ownerReference 状态和 `valuesPrinted=false`。provider API key、Codex `auth.json`、`config.toml`、DSN、token、SSH private key 和 transientEnv value 都不得以明文形式出现在响应、dry-run、event 或日志中。

### 6.3 AR-RUNTIME-REQ-003 GitBundle 资源物化

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-RUNTIME-REQ-003 | GitBundle | PJ2026-01020203 GitBundle物化 | [HWLAB接入](PJ2026-010205-hwlab-dispatch.md)、[源码同步](PJ2026-010602-source-sync.md)、[AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md) |

Runtime装配应以 `ResourceBundleRef.kind="gitbundle"` 物化代码、工具、skill 和 prompt，使 runner 使用的 repo URL、requested ref、actual commit、tree、bundles、promptRefs 和 requiredSkills 都能被查询。

gitbundle 不得引用 host path、Secret volume、用户上传临时目录、inline skill manifest 或旧 inline seed。required skill 缺失必须在 backend 启动前结构化失败，不能通过模型默认 skill、prompt 猜测或运行时补文件绕过。

### 6.4 AR-RUNTIME-REQ-004 SessionRef 持久化

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-RUNTIME-REQ-004 | Session持久 | PJ2026-01020204 Session持久 | [队列会话](PJ2026-010203-queue-session.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md)、[后端Profile](PJ2026-010204-backend-profile.md) |

Runtime装配应支持 SessionRef 到 backend thread/cache 的稳定映射，并在启用持久会话时使用 per-session RWO PVC 直接挂载到 `${CODEX_HOME}/<codex_rollout_subdir>`。

Session PVC 只保存 Codex rollout 会话文件；provider Secret、完整 `CODEX_HOME`、Git workspace、auth/config、state sqlite、tmp 和 skills 不进入 PVC。runner replacement 必须复用同一 sessionId、threadId、profile 和 PVC；不得通过新 session、拼接历史 prompt 或伪造 resume 形成续跑表象。

SessionRef 是 Web、CLI、Queue 和 HWLAB接入共享的会话连续性 authority。普通 follow-up、steer 和 result 轮询必须沿用同一 sessionId/threadId/profile/PVC 映射；session 不存在、failed、stale、canceled 或 PVC 不可用时，应返回结构化 blocker。Runtime装配不得自动创建替代 session，也不得把业务 conversationId、workspace project 或浏览器缓存当作 AgentRun session truth。

### 6.5 AR-RUNTIME-REQ-005 AipodSpec 声明式装配

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-RUNTIME-REQ-005 | AipodSpec | PJ2026-01020205 AipodSpec | [队列会话](PJ2026-010203-queue-session.md)、[发布流水](PJ2026-010601-controlled-release.md)、[源码同步](PJ2026-010602-source-sync.md) |

Runtime装配应提供 AipodSpec YAML，使 imageRef、backendProfile、executionPolicy、resourceBundleRef、model 和 payloadDefaults 可以从声明式规格进入 Queue submit 或 Session send。

AipodSpec 只声明装配意图，不保存 API key、SSH private key、token、`auth.json`、`config.toml` 或其他 Secret 明文。`imageRef` 必须指向可追溯的 env image Dockerfile source 和完整 commit，最终 runner job 只能使用解析后的 digest-pinned image 或结构化报告 build-required。