# PJ2026-010602 源码同步

## 修改历史

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

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

## 正文

## PJ2026-010602 源码同步需求规格

## 1. 文档控制

| 字段 | 内容 |
| --- | --- |
| 编号 | PJ2026-010602 |
| 短名 | 源码同步 |
| 层级 | L2 课题 |
| 状态 | 已生效 |
| 需求规格模板 | [ISO/IEC/IEEE 29148 需求规格模板](../../templates/iso-iec-ieee-29148-requirements-spec-template.md) |
| 上级规格 | [PJ2026-0106 平台运维](PJ2026-0106-platform-ops.md) |
| 规格治理索引 | [规格治理](spec-governance.md) |

本文采用 ISO/IEC/IEEE 29148 需求规格模板的项目裁剪版：正文只保留 Git mirror、source commit authority、GitOps 分支、artifact catalog、bundle/mirror URL 和运行面源码真相的通用稳定使命、范围、术语、系统边界、内部分工和原子需求。

## 2. 目的和范围

### 2.1 目的

源码同步负责让 HWLAB 平台服务运行面、CI/CD、RuntimeAssembly 和 gitbundle 资源装配都能引用明确、可验证、可追溯的 Git 来源，避免临时 clone、落后 worktree、运行面副本或不可复验 artifact 成为 source truth。具体服务的固定 branch、worktree、GitOps branch 和 artifact path 写入对应服务专项规格。

### 2.2 范围内

- G14、D601 和平台运行面使用的 Git mirror read/write URL、mirror cache、source branch 和固定 worktree 规则。
- HWLAB 各服务的 source branch、source worktree、GitOps branch、artifact catalog 和 runtime path 的通用 source truth 关系。
- RuntimeAssembly `ResourceBundleRef.kind="gitbundle"` 所需的 repo URL、ref、actual commit、bundle 摘要和 mirror 改写边界。
- GitOps desired state 与 source branch 分离，promotion 只写 artifact catalog 和 rendered manifests，不把运行副本变成源码真相。
- 运行面、CLI 和发布输出中的 source revision、artifact catalog、bundle/mirror URL 和 commit 摘要可见性。

### 2.3 范围外

- CI/CD 执行、镜像 promotion、rollout 和发布候选判定归 [发布流水](PJ2026-010601-controlled-release.md)。
- YAML target/lane/node/service 配置、SecretRef 下发和敏感输出约束归 [YAML运维](PJ2026-010603-yaml-first-ops.md)。
- 具体服务执行生命周期归对应业务规格；AgentRun run/command/runner job 执行生命周期归 [AgentRun核心](PJ2026-010201-agentrun-core.md)，AgentRun `v0.1` 专项 source truth 归 [AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md)。
- Agent workspace 中业务代码如何被模型修改、测试或提交归对应业务任务，不属于源码同步定义。
- GitHub issue/PR 过程记录、一次性迁移报告和长证据不进入本规格正文。

## 3. 术语表

| 术语 | 定义 |
| --- | --- |
| source truth | 某服务或资源装配的权威 Git 来源，包括 repo URL、branch/ref、commit 和必要的 GitOps artifact。 |
| Git mirror | 为目标运行面提供 Git read/write 缓存和 source sync 的平台基础设施。 |
| source worktree | 固定在目标节点上的 source branch 工作区，只作为预检、同步和直接轻量文档交付入口。 |
| GitOps branch | 与 source branch 分离的 desired state 分支，只保存渲染后运行面资源和 artifact catalog。 |
| artifact catalog | 记录 image、env identity、source commit、runtime path 和 manifest 摘要的发布产物索引。 |
| gitbundle | RuntimeAssembly 中通过 Git repo/ref/bundles 物化工具、skills、prompt 和 workspace 文件的资源包。 |
| actual commit | gitbundle 或 source checkout 实际解析并物化到运行面的 commit。 |

## 4. 系统边界和接口

本规格把源码同步作为平台运维内的 source truth 和 Git 资源同步系统看待；本章只描述输入、输出和责任边界。

| 边界项 | 内容 |
| --- | --- |
| 外部使用者 | 发布流水、Runtime装配、agent runner、服务维护者、平台运维 CLI 和业务模块。 |
| 外部输入 | Git remote、source branch、requested ref、commitId、GitOps branch、bundle paths、mirror target、promotion 请求和 source status 查询。 |
| 受控资源 | Git mirror、source worktree、GitOps branch、artifact catalog、gitbundle checkout、actual commit 摘要和 bundle/mirror URL。 |
| 外部输出 | source revision、mirror URL、actual commit、tree/bundle 摘要、artifact catalog path、GitOps revision 和 source sync 状态。 |
| 用户接口 | UniDesk CLI、服务自有 CLI source/status 输出、发布流水状态、RuntimeAssembly result/event 摘要。 |
| 系统边界 | 源码同步负责 Git 来源和 artifact 来源可追溯；不执行模型任务，不决定发布是否通过，不把运行面副本或临时目录提升为 source truth。 |

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

本规格前四个 L3 只承载服务无关的通用源码规则。AgentRun 固定 source branch、fixed worktree、GitOps branch、artifact catalog 和 mirror 细则只在 AgentRun 专项 L3 中展开，通用源码同步条款只保留可复用的 source truth 边界。

| 编号 | 模块或课题 | 规格文档 | 主责边界 | 上游依赖 | 下游支撑 |
| --- | --- | --- | --- | --- | --- |
| PJ2026-01060201 | Mirror同步 | 本规格 6.1 | Git mirror read/write URL、mirror cache 和 source branch 同步 | Git remote、平台网络 | 发布流水、Runtime装配 |
| PJ2026-01060202 | SourceTruth | 本规格 6.2 | fixed worktree、source branch、remote、clean/ff-only 状态 | Git mirror、项目仓库 | 服务 source 预检 |
| PJ2026-01060203 | GitOps目录 | 本规格 6.3 | GitOps branch、artifact catalog、runtime path 和 desired state | 发布流水 promotion | Argo sync、runtime 发布 |
| PJ2026-01060204 | GitBundle来源 | 本规格 6.4 | repoUrl/ref/actual commit/bundles 摘要和 mirror 改写 | Runtime装配、Git mirror | Agent runner、skills/tools |
| PJ2026-01060205 | AgentRun源码 | [PJ2026-01060205 AgentRun源码真相](PJ2026-01060205-agentrun-v01-source-truth.md) | AgentRun `v0.1` source branch、fixed worktree、GitOps branch、artifact catalog 和 mirror 细则 | Git mirror、发布流水 | AgentRun runtime、Runtime装配 |

## 6. 原子需求

### 6.1 OPS-SOURCE-REQ-001 Git Mirror 同步

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-SOURCE-REQ-001 | Mirror同步 | PJ2026-01060201 Mirror同步 | [发布流水](PJ2026-010601-controlled-release.md)、[Runtime装配](PJ2026-010202-runtime-assembly.md) |

源码同步应提供 Git mirror read/write 能力，使 CI/CD、RuntimeAssembly 和目标运行面优先通过平台 mirror 获取 GitHub 资源，避免把外网直连失败或临时 clone 作为源码阻塞。

mirror 输出应能说明 owner/repo、read URL、write URL、cache 状态和同步来源，但不得输出 Git credential、SSH private key 或可复制 token。

### 6.2 OPS-SOURCE-REQ-002 Source Truth 预检

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-SOURCE-REQ-002 | SourceTruth | PJ2026-01060202 SourceTruth | [发布流水](PJ2026-010601-controlled-release.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

源码同步应维护每条运行 lane 的 source truth，使固定 worktree、source branch、remote、clean 状态和 ff-only 同步结果可被发布流水和维护者确认。

具体服务的固定 source worktree、branch、remote 和历史废弃路径写入对应服务专项规格。开始开发、文档落库、发布或 render 前必须确认 source truth；临时 clone、运行副本、旧 worktree 或 master server 缓存不能替代它。

node/lane source truth 必须与当前任务目标一致。D601 legacy、G14 legacy、retired workspace、runner checkout、pod 内副本和一次性迁移目录只能作为对照或历史来源；当 issue/CLI 选择 D601 v0.3、G14 v0.2 或其他正式 lane 时，预检、文档落库、render、发布和验收都应从该 lane 的固定 source worktree 和 branch 开始。

### 6.3 OPS-SOURCE-REQ-003 GitOps 与 Artifact Catalog

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-SOURCE-REQ-003 | GitOps目录 | PJ2026-01060203 GitOps目录 | [发布流水](PJ2026-010601-controlled-release.md)、[YAML运维](PJ2026-010603-yaml-first-ops.md) |

源码同步应将 source branch 与 GitOps branch 分离，使 Tekton promotion 只把 artifact catalog 和 rendered manifests 写入 GitOps desired state，而不把运行面生成物回写到 source branch。

GitOps 输出应能追溯 source commit、runtime path、image digest、manifest revision 和 artifact catalog path。source branch 不应包含 CI 自动构造物、runtime dump、Secret data 或临时报告。

GitOps branch 只保存目标运行面 desired state 和 artifact catalog，不承载需求规格、阶段报告或手工 hotfix 过程记录。source branch 中的人写配置、源码和 OA 交叉引用是长期真相；GitOps promotion 产物不得被反向同步为 source truth。

### 6.4 OPS-SOURCE-REQ-004 GitBundle Source Authority

| 编号 | 短名 | 主责模块 | 关联模块 |
| --- | --- | --- | --- |
| OPS-SOURCE-REQ-004 | GitBundle来源 | PJ2026-01060204 GitBundle来源 | [Runtime装配](PJ2026-010202-runtime-assembly.md)、[Agent编排](PJ2026-0102-agent-orchestration.md) |

源码同步应为 gitbundle 装配提供 source authority，使 `ResourceBundleRef.repoUrl`、requested ref、actual commit、tree、bundles、promptRefs、tools 和 skills 的来源可验证。

runner materialization 可以按平台规则把 GitHub URL 改写到 G14 git mirror，但不得让 prompt、payload、host path、Secret volume、用户上传目录或运行时临时文件成为 gitbundle 的权威来源。event/result 只输出路径、hash、bytes、commit 和 bundle 摘要，不输出文件全文或凭据。