# PJ2026-01060205 AgentRun源码真相

## 修改历史

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

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

## 正文

## PJ2026-01060205 AgentRun源码真相需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-01060205 |
| 短名 | AgentRun源码 |
| 层级 | L3 子课题 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-010602 源码同步](PJ2026-010602-source-sync.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 AgentRun `v0.1` 的 source branch、fixed worktree、Git mirror、GitOps branch、artifact catalog 和 gitbundle source authority。

## 2. 目的和范围

### 2.1 目的

AgentRun源码真相负责定义 AgentRun `v0.1` 的 Git source truth，使开发、规格落库、CI/CD、GitOps promotion、RuntimeAssembly 和 runner materialization 都引用同一 source branch、fixed worktree、mirror 和 artifact catalog。

### 2.2 范围内

- AgentRun `v0.1` source repo、source branch、G14 fixed source worktree、worktree root 和 remote。
- Git mirror read/write URL、mirror cache 和 promotion 时的 source/GitOps 分离。
- `v0.1-gitops` branch、artifact catalog、runtime path 和 source revision 可追溯关系。
- AgentRun gitbundle materialization 中 GitHub URL 到 G14 git mirror 的改写和 actual commit 摘要。
- 固定 source truth 预检、ff-only 同步、clean 状态和禁止临时 clone/运行副本成为 source truth。

### 2.3 范围外

- 通用源码同步、Git mirror 和 artifact catalog 规则归 [源码同步](PJ2026-010602-source-sync.md)。
- AgentRun 发布、Pipeline、runtime namespace 和真实联调归 [AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md)。
- AgentRun run、command、event 和 terminal status 归 [AgentRun核心](PJ2026-010201-agentrun-core.md)。
- RuntimeAssembly 对 gitbundle 的字段语义归 [Runtime装配](PJ2026-010202-runtime-assembly.md)。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| fixed source worktree | AgentRun `v0.1` 在 G14 上的固定 source truth 工作区。 |
| v0.1-gitops | AgentRun `v0.1` 的 GitOps desired state 分支。 |
| artifact catalog | AgentRun CI promotion 生成的 artifact 索引文件，记录 image、source commit 和 runtime manifest 摘要。 |
| runtime path | GitOps branch 中 AgentRun `v0.1` runtime manifests 的路径。 |
| mirror read URL | CI/CD 或 runner materialization 拉取 AgentRun/相关 repo 时优先使用的 Git mirror 地址。 |

## 4. 系统边界和接口

本规格把 AgentRun源码真相作为源码同步下的 AgentRun 专项 source truth 看待；本章只描述输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | AgentRun 维护者、发布流水、Runtime装配、runner materialization 和平台运维。 |
| 外部输入 | AgentRun source branch、requested ref、GitOps promotion 请求、mirror sync 请求、gitbundle repo/ref 和 source status 查询。 |
| 受控资源 | G14 fixed source worktree、Git mirror、GitOps branch、artifact catalog、runtime path 和 actual commit 摘要。 |
| 外部输出 | source commit、remote、branch、clean/ff-only 状态、mirror URL、GitOps revision、artifact catalog path 和 gitbundle actual commit。 |
| 用户接口 | UniDesk trans/CLI 预检入口、AgentRun CI/CD CLI、RuntimeAssembly event/result source 摘要。 |
| 系统边界 | AgentRun源码真相只定义 AgentRun `v0.1` Git 来源和 artifact 来源；不执行发布、不判断功能通过、不把运行面副本或临时目录变成 source truth。 |

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

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-0106020501 | SourceWorktree | 本规格 6.1 | source repo、branch、G14 fixed worktree、remote 和 clean/ff-only 预检 | Git remote、Git mirror | 发布流水、规格落库 |
| PJ2026-0106020502 | GitOpsArtifact | 本规格 6.2 | GitOps branch、artifact catalog、runtime path 和 source revision | 发布流水 promotion | Argo runtime |
| PJ2026-0106020503 | MirrorMaterialize | 本规格 6.3 | mirror URL、gitbundle actual commit、bundle 摘要和 source event | Runtime装配、Git mirror | runner materialization |

## 6. 原子需求

### 6.1 AR-SOURCE-REQ-001 AgentRun Fixed Source Worktree

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-SOURCE-REQ-001 | SourceWorktree | PJ2026-0106020501 SourceWorktree | [发布流水](PJ2026-010601-controlled-release.md)、[AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md) |

AgentRun `v0.1` source truth 应固定为 `git@github.com:pikasTech/agentrun.git` 的 `v0.1` branch，并在 G14 fixed source worktree 中保持可预检、可 ff-only 同步和可确认 clean 状态。

固定 source worktree 只作为 source truth、规格直接落库和轻量文档交付入口。普通源码/配置开发应按 AgentRun 仓库规则进入独立 worktree；临时 clone、旧 dev/prod worktree、运行面副本、master server 缓存或一次性目录不得替代 AgentRun `v0.1` source truth。

### 6.2 AR-SOURCE-REQ-002 AgentRun GitOps 与 Artifact Catalog

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-SOURCE-REQ-002 | GitOpsArtifact | PJ2026-0106020502 GitOpsArtifact | [AgentRun发布Lane](PJ2026-01060105-agentrun-v01-release-lane.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md) |

AgentRun `v0.1` 应使用独立 GitOps branch 和 runtime path 保存 rendered desired state，并用 artifact catalog 记录 source commit、image digest、env identity 和 manifest 摘要。

source branch 与 GitOps branch 必须分离。Tekton promotion 只能把 artifact catalog 和 rendered manifests 写入 GitOps branch；不得把 live DB dump、runtime pod 状态、Secret data、CI 临时输出或执行报告回写到 source branch。

### 6.3 AR-SOURCE-REQ-003 AgentRun GitBundle Source

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| AR-SOURCE-REQ-003 | MirrorMaterialize | PJ2026-0106020503 MirrorMaterialize | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[AgentRun核心](PJ2026-010201-agentrun-core.md) |

AgentRun gitbundle materialization 应优先使用 G14 Git mirror 拉取 GitHub repo，并在 event/result 中记录 requested ref、actual commit、tree、bundle path、hash、bytes 和 mirror 摘要。

Git mirror 改写只能发生在 materialization 阶段，不能改变 AipodSpec 或 run payload 中的 source authority。非 GitHub URL 不应被强行改写；缺少 mirror cache 是基础设施缺口，不能通过 prompt、host path、Secret volume 或用户上传目录绕过。
