设计归档
设计归档解释 SOW 为什么采纳某项契约、否决了哪些替代方案，以及结论实际达到了哪一层证据。
文章按 date 排列，记录设计理由首次形成可维护正文的日期；lastmod 记录后续编辑或与
实现对齐的日期。功能实际在哪个版本交付，仍以发布注记与源码 Tag 为准。
“设计历史”系列把最初的 v0.1 产品计划、现存 44 份 ADR、112 份日期化证据报告，以及 v0.2 重置过程，提炼为少量可持续维护的叙事。原始规划 Prompt、评审与执行记录仍可通过不可变源码 Tag 和 Commit 查阅；它们是第一手史料，不是与本站并行的第二套文档目录。
权威与证据
本专栏是持续维护的设计理由与决策历史权威来源。当前命令、配置与运维行为仍以 SOW 文档为准；历史版本的精确行为则绑定对应源码 Tag 与发布注记。
每项运维结论都应与它真正达到的证据层一致：
前一层通过，不代表后一层自动通过。平台与集成 记录自动化客户端、Provider 与文件系统覆盖；Release 制品属于独立交付门禁。
协同发布决策记录
SOW v0.4.0 保留原生发布 Provider 的最终决策，以及未交付的早期 rclone 提案边界。
SOW 设计演进：从 Route Graph 收敛到 Repository Core
v0.1 如何退役、v0.2 如何交付单包体 Repository Core，以及 v0.3-v0.4 如何继续强化。
设计原则
SOW 用来约束所有权、派生状态、发布与证据的一组不变式。
系统模型
连接软件包、Dist、Generation 与发布目标的对象模型和状态迁移。
发布与恢复
发布、恢复、保留与安全删除仓库对象的 target-scoped 状态机。
为什么 SOW 每个仓库只保留一棵包体树
用唯一正典 Pool 与纯元数据视图，替代 RPM 视图内包体硬链接的设计决策。
SOW v0.1 到底证明了什么
整理 v0.1 的 112 份日期化证据报告：真实客户端、规模、故障、迁移与 Provider 结论证明了什么，又从未证明什么。
v0.2 重置：用 Plain 与 Managed 取代万能控制面
SOW 如何用两条小型执行路径、明确所有权、SQLite 状态与仓库核心，替换 v0.1 的 Git/CAS/Edge 平台。
SOW v0.1 决策账本：哪些被保留，哪些已退役
逐项整理 v0.1 现存的 44 份 ADR：当时解决什么问题，后来是延续、演化、仅服务迁移，还是随 V1 一同退役。
SOW v0.1 原始计划：软件仓库的 Git
SOW 为什么最初选择 Git/CAS/Route/Edge 控制面，这套模型解决了什么，又为何后来围绕更小的 Repository Core 重置。
-
协同发布决策记录
SOW 0.4.0 已完成最终决策 本记录的早期版本曾提议采用 rclone Executor、publish --dry-run 与独立 sow audit 命令。这些表面均未进入 0.4.0：SOW 不依赖 rclone，publish 没有 --dry-run，sow audit 也不是有效命令。 本页保留决策边界，避免历史提案被误解为当前产品。规范行为以 sow publish与 发布与恢复为准。 最终决策 SOW 0.4.0 保留原生 filesystem 与 r2 发布 …
SOW 0.4.0 已完成最终决策 本记录的早期版本曾提议采用 rclone Executor、publish --dry-run 与独立 sow audit 命令。这些表面均未进入 0.4.0：SOW 不依赖 rclone，publish 没有 --dry-run，sow audit 也不是有效命令。 本页保留决策边界，避免历史提案被误解为当前产品。规范行为以 sow publish与 发布与恢复为准。 最终决策 SOW 0.4.0 保留原生 filesystem 与 r2 发布 …
-
SOW 设计演进：从 Route Graph 收敛到 Repository Core
本文对应 2026-08-10 围绕 Repository Core 完成的 SOW 收敛决策。它从早期规划、ADR、评审、 迁移与验证目录中提炼值得维护的结论，但不会把每份过程制品都变成另一套产品文档。 部分封存目录使用“v0.2”“v0.3”表示连续的发布前设计线；下文版本号只指正式 Git Tag。 C2 硬链接开发线在 v0.2.0 打 Tag 之前已经被替换。 更详细的历史由四篇配套记录承载： v0.1 原始产品计划解释最初的产品野心，以及控制面为何变得过重； v0.1 决策账本逐项标 …
本文对应 2026-08-10 围绕 Repository Core 完成的 SOW 收敛决策。它从早期规划、ADR、评审、 迁移与验证目录中提炼值得维护的结论，但不会把每份过程制品都变成另一套产品文档。 部分封存目录使用“v0.2”“v0.3”表示连续的发布前设计线；下文版本号只指正式 Git Tag。 C2 硬链接开发线在 v0.2.0 打 Tag 之前已经被替换。 更详细的历史由四篇配套记录承载： v0.1 原始产品计划解释最初的产品野心，以及控制面为何变得过重； v0.1 决策账本逐项标 …
-
设计原则
SOW 首先不是一个“元数据生成器”，而是一个所有权与状态迁移系统，只是它的输出恰好是 APT 与 RPM 仓库。下面这些原则让整套系统保持可推理。 每个持久事实只有一个主人 每类持久事实都只有一个作用域与权威： 事实 所有者 包体与软件包身份 Repository Desired 成员关系与 Built 状态 Repository Generation 与 Changeset Repository 发布目标绑定与 Revision Repository + Target …
SOW 首先不是一个“元数据生成器”，而是一个所有权与状态迁移系统，只是它的输出恰好是 APT 与 RPM 仓库。下面这些原则让整套系统保持可推理。 每个持久事实只有一个主人 每类持久事实都只有一个作用域与权威： 事实 所有者 包体与软件包身份 Repository Desired 成员关系与 Built 状态 Repository Generation 与 Changeset Repository 发布目标绑定与 Revision Repository + Target …
-
系统模型
SOW 刻意把模型分层：配置表达意图，数据库记录有主状态，公共树是确定性投影。 任何一层都不能悄悄替代另一层。 对象层级 Workspace ├── Repository │ ├── Package Object │ ├── Dist │ │ └── Membership -> Package Object │ ├── Desired 状态 │ ├── Built Generation │ └── Retained Generation 引用 └── Publication Target └── …
SOW 刻意把模型分层：配置表达意图，数据库记录有主状态，公共树是确定性投影。 任何一层都不能悄悄替代另一层。 对象层级 Workspace ├── Repository │ ├── Package Object │ ├── Dist │ │ └── Membership -> Package Object │ ├── Desired 状态 │ ├── Built Generation │ └── Retained Generation 引用 └── Publication Target └── …
-
发布与恢复
构建与发布是两个独立状态迁移。构建产生与 target 无关的 Generation；发布把该 Generation 应用到一个供应商前缀，并记录足以在不猜测的前提下恢复的证据。 所有权拆分 Repository 作用域 Target prefix 作用域 Package Object Publication Attempt Desired 与 Built 状态 Applied Checkpoint Generation 与 Changeset 远端 inventory retained 包体/ …
构建与发布是两个独立状态迁移。构建产生与 target 无关的 Generation；发布把该 Generation 应用到一个供应商前缀，并记录足以在不猜测的前提下恢复的证据。 所有权拆分 Repository 作用域 Target prefix 作用域 Package Object Publication Attempt Desired 与 Built 状态 Applied Checkpoint Generation 与 Changeset 远端 inventory retained 包体/ …
-
为什么 SOW 每个仓库只保留一棵包体树
这项决策起草于 2026-08-05 的 v0.2 发布前设计收敛阶段，并在 2026-08-08 随 SOW v0.2.0 正式交付，随后延续为 v0.3 与 v0.4 的布局契约。它记录的是架构选择，不是笼统的兼容性 PASS：协议闭包、普通软件包客户端、镜像工具、静态托管与对象存储始终属于彼此独立的证据层。 最终决策 每个 SOW Repository 只拥有一棵公共树： <repository>/ pool/ # 正典包体 dists/ <dist>/ <architecture>/ # …
这项决策起草于 2026-08-05 的 v0.2 发布前设计收敛阶段，并在 2026-08-08 随 SOW v0.2.0 正式交付，随后延续为 v0.3 与 v0.4 的布局契约。它记录的是架构选择，不是笼统的兼容性 PASS：协议闭包、普通软件包客户端、镜像工具、静态托管与对象存储始终属于彼此独立的证据层。 最终决策 每个 SOW Repository 只拥有一棵公共树： <repository>/ pool/ # 正典包体 dists/ <dist>/ <architecture>/ # …
-
SOW v0.1 到底证明了什么
版本绑定的证据 本页每项结果都只属于当时记录的 v0.1 源码、布局、Fixture 与环境，不能证明当前 SOW 的兼容性或发布就绪。 v0.1 归档包含 112 份日期化 Evidence Report，覆盖 2026-07-11 至 2026-07-31。把它们全部 发布成博客只会降低公共站点的可用性：其中很多是窄故障闭包、重复的 Current-source Audit， 或某个具体实现 Seam 的执行记录。 但直接丢弃也会损失同样重要的信息。这些报告说明：哪些设计决定来自真实客户端 …
版本绑定的证据 本页每项结果都只属于当时记录的 v0.1 源码、布局、Fixture 与环境，不能证明当前 SOW 的兼容性或发布就绪。 v0.1 归档包含 112 份日期化 Evidence Report，覆盖 2026-07-11 至 2026-07-31。把它们全部 发布成博客只会降低公共站点的可用性：其中很多是窄故障闭包、重复的 Current-source Audit， 或某个具体实现 Seam 的执行记录。 但直接丢弃也会损失同样重要的信息。这些报告说明：哪些设计决定来自真实客户端 …
-
v0.2 重置：用 Plain 与 Managed 取代万能控制面
开发设计线不等于发布版本 归档中的“v0.2”设计线最初使用 C2 View-local RPM Hardlink。这是一条真实实现过的开发线， 但在最终 v0.2.0 Tag 之前已经被单包体设计替换。正式发布的 v0.2.0 已经使用唯一正典 Pool 与纯元数据 View。 归档中仍有数份 v0.2/v0.3 文件声称“v0.2.0”使用 C2 Hardlink；它们写于 Tag 产生之前， 当时的“v0.2.0”指计划中的 Build。实际交付边界由最终 0.2.0 …
开发设计线不等于发布版本 归档中的“v0.2”设计线最初使用 C2 View-local RPM Hardlink。这是一条真实实现过的开发线， 但在最终 v0.2.0 Tag 之前已经被单包体设计替换。正式发布的 v0.2.0 已经使用唯一正典 Pool 与纯元数据 View。 归档中仍有数份 v0.2/v0.3 文件声称“v0.2.0”使用 C2 Hardlink；它们写于 Tag 产生之前， 当时的“v0.2.0”指计划中的 Build。实际交付边界由最终 0.2.0 …
-
SOW v0.1 决策账本：哪些被保留，哪些已退役
历史决策账本 v0.1.0 Tag 中现存 44 份 ADR，编号从 0001 到 0045，其中缺少 0006。 本文保留它们的意义，但不会把每份历史实现契约重新发布成当前指南。 即使实现已经退役，ADR 仍有价值：它记录团队拒绝忽略的失败模式、当时选择的边界，以及危险 操作进入执行前必须取得的证据。 下面把每项决策分为四种命运： 命运 含义 保留 原则以基本相同的边界继续存在于当前 SOW。 演化 问题与安全规则仍在，但所有权或实现已经改变。 迁移历史 决策只服务一次性的 …
历史决策账本 v0.1.0 Tag 中现存 44 份 ADR，编号从 0001 到 0045，其中缺少 0006。 本文保留它们的意义，但不会把每份历史实现契约重新发布成当前指南。 即使实现已经退役，ADR 仍有价值：它记录团队拒绝忽略的失败模式、当时选择的边界，以及危险 操作进入执行前必须取得的证据。 下面把每项决策分为四种命运： 命运 含义 保留 原则以基本相同的边界继续存在于当前 SOW。 演化 问题与安全规则仍在，但所有权或实现已经改变。 迁移历史 决策只服务一次性的 …
-
SOW v0.1 原始计划：软件仓库的 Git
历史设计记录 本文描述 2026-07-11 启动、并在 2026-07-31 封存为 v0.1.0 源码基线的原始计划。 Git/CAS/Route/Edge 产品模型已经退役；当前行为以 SOW 文档和维护中的 系统模型为准。 SOW 最初并不是一个小型仓库索引器。原始目标是用一个 Go 控制面，替换 Pigsty 中庞大的 Makefile + rclone 工作流，统一管理 APT、YUM 与静态制品，覆盖本地状态、包生命周期、上游 同步、Channel、View、Snapshot、双 …
历史设计记录 本文描述 2026-07-11 启动、并在 2026-07-31 封存为 v0.1.0 源码基线的原始计划。 Git/CAS/Route/Edge 产品模型已经退役；当前行为以 SOW 文档和维护中的 系统模型为准。 SOW 最初并不是一个小型仓库索引器。原始目标是用一个 Go 控制面，替换 Pigsty 中庞大的 Makefile + rclone 工作流，统一管理 APT、YUM 与静态制品，覆盖本地状态、包生命周期、上游 同步、Channel、View、Snapshot、双 …