pikasTech-unidesk/project-management/PJ2026-01/specs/PJ2026-010602-source-sync.md

PJ2026-010602 源码同步

修改历史

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

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

正文

PJ2026-010602 源码同步需求规格

1. 文档控制

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

本文采用 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 和发布候选判定归 发布流水。
• YAML target/lane/node/service 配置、SecretRef 下发和敏感输出约束归 YAML运维。
• 具体服务执行生命周期归对应业务规格；AgentRun run/command/runner job 执行生命周期归 AgentRun核心，AgentRun v0.1 专项 source truth 归 AgentRun源码真相。
• 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源码真相	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同步	发布流水、Runtime装配

源码同步应提供 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	发布流水、Agent编排

源码同步应维护每条运行 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目录	发布流水、YAML运维

源码同步应将 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装配、Agent编排

源码同步应为 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 摘要，不输出文件全文或凭据。