servicememeai · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026 · Oct 20, 2026
diff --git a/BRANCHING.md b/BRANCHING.md
@@ -2,23 +2,30 @@
 # CloudFile 三仓分支模型
 
 > **用途**：规定 `cloudfile-server`、`cloudfile-hub`、`cloudfile-docker` 共用的分支、发布和上游同步规则。
-> **适用版本**：CloudFile `14.0.0-cf.0`，基于 Seafile CE 14 源码重构。
+> **适用范围**：CloudFile V2 开发主线（Seafile CE 14 基线）；产品版本与 CE 版本分开标识，正式发布版本由冻结的构建清单声明。
 > **状态**：当前有效；构建 ref 以 [`release.yaml`](release.yaml) 为准，详细门槛见 [`docs/BRANCHES.md`](docs/BRANCHES.md)。
 
 ## 分支类型
 
+V2 只有一个持续集成主线：`dev`。分支名用于**隔离开发目的与产品代际**，不能代替 Server/Hub/Docker 的提交锁定。详细规则、历史分支治理和跨仓 CI 见 [docs/BRANCHES.md](docs/BRANCHES.md)。
+
 | 分支 | 用途 | 生命周期 |
 |---|---|---|
-| `dev` | 集成基线：扩展点、构建、部署和已验收能力；全部能力开关默认关闭 | 长期 |
-| `feature/<name>` | 单个耦合能力簇 | 验收后合回 `dev` 并删除 |
-| `fix/<name>` | 独立缺陷修复 | 验证后合回 `dev` 并删除 |
-| `sync/upstream-YYYYMMDD` | 三仓同步上游的临时工作分支 | 同步与回归完成后删除 |
-
-长期能力分支只用于不准备进入产品的客户定制、实验或许可证不兼容实现。能力不能长期各自分叉：构建脚本每仓只接受一个 ref，正式组合必须在 `dev` 上通过默认关闭的开关隔离和集成验证。
+| `dev` | 当前 CloudFile V2 集成线，非 V0.9 / CE14 原生快照 | 长期 |
+| `feat/v2/<work>-<topic>` | V2 能力（多仓耦合使用同一 work ID） | 验收后合入 `dev` 并删除 |
+| `fix/v2/<work>-<topic>` | V2 缺陷修复 | 验收后合入 `dev` 并删除 |
+| `docs/v2/<topic>` | V2 文档调整，不改变运行代码 | 评审后删除 |
+| `sync/ce14/<YYYYMMDD>` | Seafile CE14 上游同步 | 验收后删除 |
+| `release/v2.x.y` | 仅 Docker 仓的临时发布冻结工作线 | 打 Tag 后结束 |
+| `hotfix/v2.x.y/<topic>` | 从已冻结版本修复，只进入对应版本和 `dev` | 验证后删除 |
+| `maintenance/v0.9/<topic>` | 确需维护 V0.9 时，从归档旧版本派生 | 临时，严禁合并整枝到 V2 |
+| `archive/*`、`seafile/*` | 只读历史快照或上游来源 | 保留，不作为新任务基线 |
+
+旧 `dev2`、`dev2-clean`、`dev14`、`feature/v09-*` 不是新的 V2 开发入口；先确认外部引用及未移植差异，再执行非破坏性归档与清理。历史在途分支（例如 `feature/local-object-staging-20261020`）先完成原任务，不因规则发布而强制改名。
 
 ## 上游基线
 
-未 fork 组件按 `release.yaml` 的 `upstream` SHA 锁定；CloudFile fork 使用 `forks` 下的 URL/ref。上游未发布 CE 14 tag，不能用 Pro tag 代替 CE 基线。
+未 fork 组件按 `release.yaml` 的 `upstream` SHA 锁定；CloudFile fork 使用 `forks` 下的 URL/ref。上游已有 CE14 发布 Tag；基线使用 `release.yaml` 的 `ce_anchor` 与固定源码提交，不得用 Pro Tag 或移动分支代替。
 
 ```bash
 python3 build/cloudfile_14.0/read-manifest.py release.yaml forks.cloudfile_server.ref
@@ -177,8 +184,7 @@ CloudFile 的改动跟着文件走，登记路径随之改写：
 跨 Hub/Server 的语义先更新共享规格和用例，再同步实现。
 
 发布时将三个仓库的最终提交写入 `release.yaml` 的 `server_commit`、`hub_commit`、`docker_commit`，
-然后在 GitHub Actions 中从 `prod` 分支手动运行 `CloudFile production build`，填写版本并
-选择 `incremental` 或 `full`。日常小改用增量路径，正式复核、上游升级或缓存对照用保留的
+然后在 GitHub Actions 中选择**确实存在且已冻结发布清单的 Docker ref**，手动运行 `CloudFile production build`，填写版本并选择 `incremental` 或 `full`。当前三仓没有 `prod` 分支，不再把旧文档中的 `prod` 当作已配置的发布入口。日常小改用增量路径，正式复核、上游升级或缓存对照用保留的
 CE 全量路径；通过后再使用同一版本 tag。普通 push 不触发生产编译；增量构建计划会校验
 声明的 Server/Hub 提交与实际解析结果一致。未填写提交的开发清单不能当作可追溯发布记录。
 

diff --git a/docs/BRANCHES.md b/docs/BRANCHES.md
@@ -2,7 +2,7 @@
 # 分支与上游跟随
 
 > **用途**：定义 CloudFile 三仓当前有效的分支类型、合并门槛、发布 ref 与上游同步规则。
-> **适用版本**：CloudFile `14.0.0-cf.0`，基于 Seafile CE 14 源码重构。
+> **适用范围**：CloudFile V2 DEV（Seafile CE14 基线）。V2 是产品代际、CE14 是上游版本，均不等同于镜像发布号。
 > **状态**：当前有效；实际发布 ref 以 [`../release.yaml`](../release.yaml) 为唯一真相。
 > **边界**：CE 提供上游基线；CloudFile 维护扩展点、能力和门禁；官方/第三方组件的版本、许可证与可用性独立管理。
 
@@ -16,25 +16,56 @@ cloudfile-hub      Web、API、后台任务
 cloudfile-docker   构建、镜像、部署与跨仓规格
 ```
 
-只使用两类开发分支：
+分支只负责代码隔离，**产品代际由命名固定，三仓兼容由 SHA 组合验证**：
 
-| 类型 | 命名 | 生命周期 | 内容 |
-|---|---|---|---|
-| 集成基线 | `dev` | 长期 | 已验收能力、扩展点、构建与部署；默认值见 [`configuration.md`](configuration.md) |
-| 能力分支 | `feature/<name>` | 临时 | 单个耦合能力簇；验收后合回 `dev` 并删除 |
+| 类型 | 命名 | 起点与去向 |
+|---|---|---|
+| 唯一开发主线 | `dev` | 三仓当前均代表 V2；不再另开 dev2/dev3/dev14 |
+| 新特性 | `feat/v2/<work>-<topic>` | 从各仓 `dev` 创建，只建确有改动的仓；测试后合回各仓 `dev` |
+| 修复 | `fix/v2/<work>-<topic>` | 从 `dev` 创建；修复完成后删除 |
+| 文档 | `docs/v2/<topic>` | 从 `dev` 创建；不混入运行代码 |
+| 同步上游 | `sync/ce14/<YYYYMMDD>` | 在受影响仓从 `dev` 创建，更新 CE anchor 后删除 |
+| 发版冻结 | `release/v2.x.y` | 只在 Docker 建立；临时冻结三仓 SHA，发布后使用不可变 Tag |
+| 发布修复 | `hotfix/v2.x.y/<topic>` | 从目标已发布 Tag 派生，完成后按评审同步到 `dev` |
+| 遗留维护 | `maintenance/v0.9/<topic>` | 仅从 V0.9 归档建立，不直接合入 V2；所需修复单独移植 |
+| 只读来源 | `archive/*`、`seafile/*` | 历史 / 上游，不接受常规开发提交 |
 
-客户定制、实验性或许可证不兼容且不准备进入产品的实现，才允许长期保留独立分支。历史分支存在性不能从文档推断，应直接执行 `git branch -a`。
+`<work>` 可以是 Issue ID 或统一短工作编号；跨仓任务使用同一 ID 和语义（例如 `feat/v2/cf-123-local-object-staging`）。同名仅用于识别任务，**不能当成版本兼容证明**。历史在途分支不强制改名，先完成现有 PR 再按新命名执行。
 
-## 发布 ref
+长期客户定制与产品主线隔离，不能用未经验证的长期 `feat/*` 来充当可发布版本。
 
-`release.yaml` 是构建唯一真相。当前清单默认从 CloudFile fork 的 `dev` 构建；本地验证可用 `CF_SERVER_REF`、`CF_HUB_REF` 临时覆盖，不能把 ref 或 SHA 写死进构建脚本。
+## 三仓组合与发布清单
+
+1. **开发快照**：在 Docker 主导的一次集成验证中，实际解析并记录 `server_sha`、`hub_sha`、`docker_sha`、CE 基线、构建时间与 API/DB 契约；CI 用固定 SHA 运行整个测试过程。可以从 `dev` 或同一工作项的在途分支解析，但不得在测试过程中再读取可移动的 `dev`。
+2. **跨仓能力**：先验证 Server、Hub、Docker 的同一提交组合，再按兼容顺序合并。若需要双边同时升级，使用兼容过渡接口或短暂冻结集成，不能仅因为同名分支存在就分别合并。
+3. **发行冻结**：`release.yaml` 保持唯一的正式发行清单，三个 `*_commit` 必须是不可变 40 位 SHA，并验证与所构建源码一致；生成镜像后记录 Digest 与源代码组合。正式发版不能使用空提交字段或仅依赖浮动 `ref: dev`。
+4. **版本分离**：CloudFile 产品版本（如 `v2.0.0`）、Seafile CE 版本（如 `v14.0.8-server`）、实际构建组合 ID、镜像 Tag/Digest 逐个标注；绝不把上游 CE 14、旧 CloudFile V0.9 与 V2 混为同一分支版本。
+5. **历史测试隔离**：`build/v2/source-set.json` 当前固定旧的 Server/Hub overlay 提交，`v2-clean.yml` 是指定旧快照的隔离测试。不得以该工作流通过声称最新 `dev` 组合已经通过。若希望覆盖当前 V2，需另建或更新使用当前三仓固定 SHA 的集成门禁；保留原隔离测试的独立身份。
+6. **发布入口**：现有三仓没有 `prod` 分支。Docker 可以在现有 `dev` 上冻结并经审查发布，也可以短暂使用 `release/v2.x.y`，但不得假设文档中的 `prod` 已存在。创建新长期 `prod` 非必需。
+
+`release.yaml` 中用于日常开发的 `forks.*.ref: dev` 可以保留；发布与测试收据都必须记录经解析的确切提交，不能把“开发默认”误认为“发布锁”。
+
+## 旧分支退役检查（2026-10-20 快照）
+
+- `dev2-clean` 在三仓均是 `dev` 的祖先，已于 2026-10-20 迁移到 `archive/dev2-clean-20261020` 并移除原分支。`dev14` 仍存在，按引用复核后再处理；`v2-clean.yml` 当前仍有过期的 `dev2-clean` 触发名，需单独修复。
+- `dev2` 在三仓均与 `dev` 分叉，不得整枝合入。已于 2026-10-20 创建 `archive/dev2-retired-20261020`，确认 SHA 与 `archive/dev2-m1-20261016` / 原 `dev2` 一致，再移除原 `dev2` 分支。独有提交仅供历史移植评估。
+- `archive/v0.9-dev-20261016` 保留为旧版来源，`feature/v09-directory-access` 不可直接合并进当前 V2。
+- Hub 旧 `feature/v2-*`、`fix/v2-*` 的未合入提交及开放 PR 必须逐个核对；需要的能力重新从 `dev` 派生，不做自动批量合并或删除。
+- `seafile/*`、`master`、`seahub-ce` 等上游来源按照用途保留，不因名称看起来“旧”就删除。
+- 现存 `feature/local-object-staging-20261020` 三仓均从各自当前 `dev` 向前推进，原分支继续验收；未来新工作项采用带 `v2/` 的统一前缀。
+
+旧分支清理遵循：先记录最后 SHA、PR / CI / 构建引用、上游需要保留的证据和可替代 Tag，之后再决定只读、归档或删除。GitHub 分支保护和“必须先过跨仓 CI”需要由仓库管理员或可用 ruleset 配置，单靠命名文档不会自动生效。
+
+## 发布 ref 与门禁
+
+现有正式镜像构建从 `release.yaml` 解析 Server/Hub refs；开发 ref 可为 `dev`，但发布前必须将解析出的 SHA 写入冻结清单。避免新增第二套常设发行事实来源。旧流程的 `CF_SERVER_REF` 和 `CF_HUB_REF` 仅用于明确的开发/联验覆盖，不能绕过发布锁。
 
 ```bash
 python3 build/cloudfile_14.0/read-manifest.py release.yaml forks.cloudfile_server.ref
 python3 build/cloudfile_14.0/read-manifest.py release.yaml forks.cloudfile_hub.ref
 ```
 
-上游未发布 CE 14 分支或 CE 14 tag，因此未 fork 组件必须在 `release.yaml` 中锁定提交 SHA。当前基线结论见 [`overview.md`](overview.md)，完整决策过程在 [`history/`](history/README.md)。
+CE14 已存在正式发布 Tag；上游源码锚点与未 fork 组件 SHA 分开固定在 `release.yaml`。
 
 ## 能力合并门槛
 
@@ -78,7 +109,7 @@ docs/upstream-patches/cloudfile-docker.txt
 
 ## 上游同步
 
-1. 在三仓建立同名同步分支，例如 `sync/upstream-YYYYMMDD`。
+1. 在受影响仓建立同一工作项的同步分支，例如 `sync/ce14/20261020`。
 2. 合入或重放上游改动，逐项解决登记文件中的冲突。
 3. 更新 `release.yaml` 的上游 SHA；CloudFile fork ref 仍按待验证分支显式覆盖。
 4. 运行快速检查、基线门禁和受影响能力门禁。
@@ -88,14 +119,14 @@ docs/upstream-patches/cloudfile-docker.txt
 
 ## 并发与跨仓协作
 
-- 三仓使用同名能力分支，提交说明标明受影响仓库和共享契约。
+- 只有受影响仓库建立同一工作项标识的能力分支；每个 PR 写明 Server/Hub/Docker 精确 SHA、影响的契约和基线。
 - 先改规格与共享用例，再同时实现 Hub 与 Server，最后更新 docker 构建/部署门禁。
-- 不把多个未验收能力临时拼成发布分支；组合集成在 `dev` 上、由开关隔离。
-  修改说明（2026-09-22）：隔离依赖“未验收能力默认关闭”，而不再是“全部开关默认关闭”。
+- 不把多个未验收能力临时拼成发布分支；组合集成在 `dev` 上，依赖快照和既有能力的真实启用条件隔离。
+  历史开关规则仅适用于保留开关的旧能力；V2 已经默认常开的 ACL/原生 Tag/Checkout 不允许人为恢复废弃开关来规避验证。
 - 合并前确认能力分支不是 `dev` 的祖先，避免快进后误以为能力代码仍存在：
 
   ```bash
-  git merge-base --is-ancestor feature/<name> dev
+  git merge-base --is-ancestor feat/v2/<work>-<topic> dev
   ```
 
 旧排期、历史成本计数与 ACL 分支重建过程保留在 [`history/特性分支与持续维护-旧版.md`](history/特性分支与持续维护-旧版.md)，不作为当前操作依据。