pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-01060205-agentrun-v01-source-truth.md

PJ2026-01060205 AgentRun源码真相

修改历史

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

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

正文

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

1. 文档控制

字段	内容
编号	PJ2026-01060205
短名	AgentRun源码
层级	L3 子课题
状态	已生效
需求规格模板	ISO/IEC/IEEE 29148 需求规格模板
上级规格	PJ2026-010602 源码同步
规格治理索引	规格治理

本文采用 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 规则归 源码同步。
• AgentRun 发布、Pipeline、runtime namespace 和真实联调归 AgentRun发布Lane。
• AgentRun run、command、event 和 terminal status 归 AgentRun核心。
• RuntimeAssembly 对 gitbundle 的字段语义归 Runtime装配。

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	发布流水、AgentRun发布Lane

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、YAML运维

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装配、AgentRun核心

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 或用户上传目录绕过。