Veyra-NRVideo 2.1.1 基线核对与仓库瘦身实战:从 132 个分支、101 个工作树收敛到一条可维护主线

原创2026-11-14 12:37:092,191 阅读
文章标签:音视频视频处理图像处理桌面应用直播

Veyra-NRVideo 2.1.1 基线核对与仓库瘦身实战:从 132 个分支、101 个工作树收敛到一条可维护主线

本文以仓库内的《Veyra 2.1.1 基线核对与项目整理方案》为骨架,完整还原一次大型 Windows 视频播放/采集增强项目(Veyra-NRVideo)的仓库治理过程:先证明“2.1.1 已完整在 main”,再用可复核的磁盘盘点定位膨胀来源,然后按“先保全、再回收、后拆分”的顺序收拢分支、工作树、文档与巨型源文件。读完后你应能独立复制这套方法:用 git 判定基线是否真正合入、用文件 ID 去重估算真实可回收空间、用 Git bundle 保证历史可恢复,并把一个 9000 行的 QML 桥接文件拆成可编译的领域模块。

说明:原方案中的数字是执行前快照。用户随后授权全部实施,完成状态与回收量以执行记录为准;不要把文中的 132 分支 / 101 工作树误读为当前剩余规模。

一、方案的边界:先声明“不做什么”,再谈清理

原方案在最前面就限定了本轮交付的性质:只做主线核对与清理方案,不删除、不移动任何产物,不删除分支或工作树,不修改产品代码、驱动、运行库或用户配置,也不推送或发布。

这条边界不是客套话,而是这类仓库治理任务的核心约束。Veyra-NRVideo 同时包含播放器、采集卡接入、超分(SR)、降噪(NR)、补帧(FG)、颜色处理、字幕、导出与串流等多条链路,运行库、模型和驱动属于不可重建资产;一旦在大扫除中顺手改了源码或删了依赖,回归成本远高于省下的磁盘。因此文档把“盘点”和“执行”拆成两个阶段:方案阶段只读,执行阶段按第 0 步先建立可恢复清单。

对读者而言,这意味着本文给出的每条结论都带有可验证依据:要么是可复现的 git 命令输出,要么是文件系统元数据,要么是仓库内的源码与 CMake 清单。

二、先固定一个事实:2.1.1 已完整在 main

所有清理动作的前提是“我知道哪条线是当前产品基线”。原方案用四条互相独立的证据把这件事钉死,而不是凭印象判断。

2.1.1 基线核对证据链

核对项 观测结果 判读
发行提交 2fecacfedd05266ca98ad6efa46e4ef4d0be0365 v2.1.1 与 v2.1.1-sources 解引用后指向同一提交
本地 main / nrvideo/main / 远端 main 三者均为 95209469e62e8ded5ba399875b99ab5e3edb3623 远端与本地未分叉
git merge --ff-only v2.1.1 返回 Already up to date.,exit 0 无需重复合并,也不该为此制造空的合并提交
git diff v2.1.1 main -- src include apps qml i18n shaders CMakeLists.txt 无变化 代码面已等价;其后的两条提交是发布记录与迁移文档
正式包与应用源码 SHA256 与旁边 .sha256 逐项比较一致 才可作为“保留基线”

这五条覆盖了三个容易出错的维度:

  1. 引用等价 ≠ 内容等价。标签解引用相同只说明 ref 指向同一对象,所以还要用 git diff 限定到真正的产品目录(src include apps qml i18n shaders CMakeLists.txt),把“文档提交”排除在比较范围外。
  2. 能快进却不合并不等于漏合并。--ff-only 返回 Already up to date. 说明 main 已包含该提交,此时再执行一次合并只会得到空提交,污染历史。
  3. 哈希要逐项比,不能只看有没有文件。方案要求重新计算两个正式包及应用源码的 SHA256,并与随包 .sha256 比对,通过后才登记为保留基线。

同时方案明确保留原有施工树与构建目录(E:/项目/Veyra/worktrees/screen-recording-fix-20261022 与 E:/项目/Veyra/build/claude-screen-recording-20261022),理由是不为目录更名破坏 CMake 缓存。这一条在仓库的开发说明里也有对应要求:构建目录只有在准备独立配置时才新建,见开发与验证入口。

三、规模诊断:问题不是“文件多”,而是“事实有几百个版本”

盘点阶段给出了这组数字,它们是后续所有决策的输入:

指标 数量 备注
本地分支 132 其中 121 个是 main 的祖先(含 main 本身),11 个不是
工作树 101 有未提交状态的 6 个,合计 516 条状态记录
Git 标签 461 发行与源码标签并存
受控文档 636 名称含 PLAN 的 155 个
AGENTS.md 约 151 KiB 规则与授权混写
WORKLOG.md 约 1.55 MiB / 10142 行 逐条追加
CURRENT_STATUS.md 692 行 大量内容是历史时点

这组数据的真正风险不是磁盘占用(分支名本身几乎不占空间),而是状态歧义:后接手的 Agent 或开发者很容易把早期写的“未合并”“未发布”误读为当前事实。方案对此的判断很直接——文档需要一个“现在”,而不是几百个“现在”。

源码层面同样有独立的维护问题

方案点名了三个超大文件:

  • QmlPlayerBridge.cpp 9233 行
  • ProPage.qml 3213 行
  • DialogHost.qml 2277 行

并给出关键限定:这些要按职责拆分,而不是凭文件大小删除;并且 SMAA 查表等生成数据不能当普通冗余代码清掉。

后面这条最容易踩坑。在仓库构建系统里,SMAA 的权重纹理是按预设生成的着色器变体:

CMakeLists.txt:463  veyra_add_compute_shader(veyra_shader_aa_smaa_edges AaSmaaEdges)
CMakeLists.txt:464  veyra_add_compute_shader_variant(veyra_shader_aa_smaa_weights_low AaSmaaWeights AaSmaaWeightsLow SMAA_PRESET_LOW)
CMakeLists.txt:465  veyra_add_compute_shader_variant(veyra_shader_aa_smaa_weights_medium AaSmaaWeights AaSmaaWeightsMedium SMAA_PRESET_MEDIUM)
CMakeLists.txt:466  veyra_add_compute_shader_variant(veyra_shader_aa_smaa_weights_high AaSmaaWeights AaSmaaWeightsHigh SMAA_PRESET_HIGH)
CMakeLists.txt:467  veyra_add_compute_shader_variant(veyra_shader_aa_smaa_weights_ultra AaSmaaWeights AaSmaaWeightsUltra SMAA_PRESET_ULTRA)

对应生成脚本为 scripts/generate-smaa-lookup-tables.py,着色器源码在 shaders/AaSmaaWeights.hlsl 与 shaders/AaSmaaEdges.hlsl。这类“看起来像重复常量”的文件其实是抗锯齿链路的行为输入,属于典型的“体积可疑但不可删”资产。

四、磁盘盘点方法论:为什么不能把各目录 GiB 相加

方案里最值得复用的一段是它的计量口径。扫描 E 盘项目与桌面旧工程,共 792045 个文件路径,跳过 junction/symlink,枚举错误 0。三个关键设计:

  1. 文件身份用 os.stat 的卷 ID + 文件 ID,而不是路径。同一个物理文件被多处链接时,只算一次。
  2. 分配量用 FileStandardInfo.AllocationSize,而不是逻辑长度。文件“有多长”和“占了多少簇”是两件事。
  3. 无法取得分配量的文件 0 个,说明口径完整,不存在“取不到就当 0”的静默丢失。

原始文档还提供了 API 口径参考(Microsoft FileStandardInfo),并特别提醒:文件长度和分配空间不同,删除一个硬链接也不等于释放全部对应数据。

盘点结果

  • E 盘项目:逻辑文件长度约 148.01 GiB;按文件 ID 去重后的分配量约 128.27 GiB。
  • C 盘桌面旧工程:去重后分配量约 11.77 GiB。
  • 分配量不包含所有目录/MFT 元数据,实际执行后需以卷可用空间变化再核对。
  • 表中各目录可能共享文件 ID,不能直接把各行求和。
E 盘目录 按文件 ID 去重的分配量 GiB 方案给出的处置建议
deps 27.25 保留 SDK、模型、patched FFmpeg 原件;另做来源/在用版本审计
build 19.57 保留当前构建,优先清旧 CMake 缓存和可重建产物
logs 15.29 保留文本证据与关键样本;历史抓帧按 hash 去重/无损归档
test-packages 12.78 仅留当前运行供体;过时非正式包清理
archives 12.69 先做恢复验证与覆盖关系,不按日期整体删除
tmp 9.90 先提取唯一脚本、配置与诊断输出,再清临时运行副本
releases 8.72 保留 2.0.7 及以后正式资产和对应源码
worktrees 8.56 先处理干净已合分支,脏树和暂停研究保留
downloads 7.04 SDK/运行库来源原件、许可证、对应源码保留;逐项审计冗余下载
tests 4.70 保留测试源码/脚本/证据,回收重复 app/runtime
verify 4.03 正式 ZIP 已验证,解压验证副本可在复核后移除
reports 0.44 作为验收与证据索引保留

注意 deps 排第一(27.25 GiB)而建议是“保留 + 审计”,reports 只有 0.44 GiB 但明确“保留”。体积排序不等于清理优先级,这是一个很实用的判断示范。

日志为什么是隐藏大头

方案给了一个具体证据:logs 并非全是几 KB 的文字。

  • perf-nr-20261004 约 6.61 GiB,其中单张 4K RGBA 抓帧为 33,177,600 字节(3840 × 2160 × 4)。
  • sr-visual-quality-20261010 约 3.46 GiB。

结论是保留策略要分层:文本结果 + 关键 A/B 帧 + 可恢复归档,而不是全尺寸历史画面无限堆积。这也解释了为什么执行记录里强调“先保全脚本/配置/日志/源码记录及应用 EXE”,再删可重建内容。

五、11 个未直接合入的分支:分类,而不是一刀切

132 个分支中,121 个是 main 祖先(无需再合),真正需要判断的是 11 个“不是祖先”的分支。方案逐个定性:

分支 分类 处理
claude/amd-sr-off-20261022 已等价纳入 git cherry 为 -,通过另一提交进入主线;保留原始补丁来源后可归档原分支
claude/rtss-compat-20261003 历史计划 两条独有提交只涉及性能研究计划;转历史索引,不把计划当新功能
codex/article-2.1.0-20261019 文章交付记录 独有内容是工作日志里的文章交付记录,保留文章和来源索引即可
codex/avermedia-51-switch-20260917 未完成诊断工具 旧 AverMedia probe 与 CMake 接线,归档为研究工具,不能整分支合入主线
codex/beauty-node-plan-20261016 已实现功能的早期计划 产品功能已在后续版本落地;这里是早期方案文档,按历史归档保留
codex/beta-latency-ab-20260918 旧版诊断夹具 1.4.2beta 延迟对照工具,归档保留;未来测量按当前链路重新设计
codex/doc-cleanup-vram-amd-20261020 待折叠的文档纠偏 只改文档,共 57 文件;逐项提取仍有效的纠偏,避免用旧状态覆盖 2.1.1
codex/github-source-archive 历史独立源码线 旧源码快照的独立历史,保留 bundle 和固定提交,不合入产品主线
codex/lecram-native-20261019 暂停保留 用户已明确暂停,保留源码、分支和唯一依赖;不继续、不合并
codex/lecram-nr-113-20261019 暂停保留 同上
codex/smooth-motion-experiment 已撤回的旧实验 内部补帧互斥策略已被后续用户决定取代;封存,不重新合入

这段表格的方法论价值高于结论本身:“不是 main 祖先”有至少六种不同含义——已等价并入、纯计划、纯记录、没做完的工具、被取代的实验、用户明确暂停。把它们统称为“未合并分支”会直接导致两类错误:把计划当功能重复实现,或把暂停研究当废弃代码删除。

方案还给出了替代“逐个 merge”的操作路径:

先记录 分支名 → tip → 纳入版本,用一份可验证的 Git bundle 保存必要的非主线历史;释放关联的干净工作树后,再使用安全的分支删除。原分支名字本身几乎不占空间,收益主要来自检出副本和它们的构建/运行目录。

这句话是两个判断的合并:删除分支本身收益极低;真正的空间在检出副本 + 各自构建/运行目录。所以执行顺序必须是“先收工作树,后收分支引用”。

六、6 个脏工作树是保护区

工作树 状态记录数 处置
C:/Users/123/Desktop/Veyra DLSS Video Player 466 保存 index/worktree diff、未跟踪文件与忽略目录清单;逐文件辨别是否已被后续实现吸收,保持原路径和字节
E:/项目/Veyra/worktrees/dlss45-sr-20261011 9 同上
E:/项目/Veyra/worktrees/jelly-latency-20261012 5 同上
E:/项目/Veyra/worktrees/main-merge-20261002 7 同上
E:/项目/Veyra/worktrees/obs-resize-20261002 11 同上
E:/项目/Veyra/worktrees/ui-fixes-20261005 18 同上

其中最关键的一条警告值得单独强调:

尤其不能直接删桌面旧工程:所有工作树共用的 Git 对象库目前还在 C:/Users/123/Desktop/Veyra DLSS Video Player/.git。它同时是 466 条未提交状态记录的旧树。若未来迁移主仓库,应单独设计 .git/worktree 注册信息与外置子模块路径的迁移及恢复验证,不能当普通目录搬走。

这是一个真实的架构性陷阱:“工作树目录”和“Git 对象库”不在同一位置。删掉看起来像“旧副本”的桌面目录,等于删掉所有工作树的对象库。方案因此在第 0 步要求保存 refs、worktree HEAD/status,并把脏树按原字节、index、worktree patch、未跟踪文件完整保全。

七、执行顺序:五步,严格串行

方案把执行拆成 0–4 五步,顺序本身就是设计。

第 0 步:建立可恢复清单

  1. 保存 refs、worktree HEAD/status、卷空间、在用进程、当前正式包 SHA。只读盘点已完成。
  2. 处理脏树前保存原始字节、index 和 worktree patch、未跟踪文件;不要只备份已提交的 Git 历史。唯一模型/输入媒体和忽略脚本也要单列。
  3. 移除分支前使用一份 bundle 并执行 verify,验证能恢复指定 tip;不每个任务完整复制仓库,也不为每个旧分支额外创建一个 checkpoint。

第 2 条是脏树保全的核心:未提交状态的 516 条记录里,可能包含从未进过 Git 对象库的内容,只备份提交历史等于没备份。

第 1 步:先收回可重建的大副本

候选组 候选文件 ID 对应 仅靠该组链接保存的分配量
34 套旧 CMake 构建 11.14 GiB 约 11.14 GiB
7 组被 2.1.1 替代的测试包 9.02 GiB 约 7.27 GiB
2 组解压验证副本 4.03 GiB 约 4.03 GiB
三组合并后 — 22.45 GiB

三个限定条件必须一起读:

  • 这是保存必要资料之前的候选测算,实际回收要扣除保留资料与归档成本。
  • 最终以执行后卷空间为准。
  • 完整目录清单在 candidate-scope-estimates.json 和 CLEANUP_PLAN.json,不是“目录名匹配就全部删”。

方案还特别标注:当前正式版 staging 先保留,直到选定唯一 NVIDIA/AMD 运行供体并核对正式归档 SHA,之后才能清掉 staging 中重复 ZIP/源码与多余运行副本;2.0.7–2.1.1 的正式 ZIP/对应源码不动。这与仓库里 docs/CURRENT_STATUS.md 记录的正式产物路径互相印证。

第 2 步:收拢分支与工作树

  • 先归档并移除干净、已合入 main 的旧工作树;检查所有 ignored 文件,尤其任务脚本与 runtime 原件;使用 git worktree remove,不强制绕过脏状态。把历史构建引用和脚本入口先移出这些旧树。
  • 已合分支在清单和 Git 历史可恢复后退出日常分支列表。main 保留;Lecram 两条暂停线保留;尚有独有文档/研究的分支先入档。
  • 远端分支与现有发行标签另列清单;方案不包含远端删除、强推、重写历史或 gc --prune=now。
  • 日常只保留 main 与少量正在做的任务。暂停工作放入明确的暂停清单,已交付任务关闭。

git worktree remove 不带强制参数是一条安全阀:脏树会让它失败,失败的提示正好是“这里需要人工判断”。

第 3 步:让文档有一个现在,而不是几百个现在

  • AGENTS.md 只保留当前有效规则、依赖根、产物路径、权限/许可与当前入口;逐日授权原文移到带日期的历史记录,保持可追溯。
  • docs/CURRENT_STATUS.md 只记录当前正式版、当前开发基线、活动工作、暂停项、已知问题和验收边界,历史交付转索引。不要用旧“未合 main”覆盖今天的事实。
  • docs/WORKLOG.md 按月份或版本归档,首页只保留当前记录和链接;历史 PLAN/REPORT 通过索引查,不要求每个 Agent 逐篇读。
  • codex/doc-cleanup-vram-amd-20261020 的文档纠偏按当前事实人工折叠,不能整分支覆盖当前文档。移动文档后扫描相对链接和脚本硬编码,保留必要入口桥接。

这一条在仓库中已经落地:历史资料统一进入 docs/history/INDEX.md,按 plans / reports / releases / rules / status / worklog 六类归档;旧路径与新路径的映射保存在 docs/history/PATH_MAP.json,形如:

{
  "docs/5060_PRESETS_BITMAP_PLAN_2026-09-18.md": "docs/history/plans/5060_PRESETS_BITMAP_PLAN_2026-09-18.md",
  "docs/AMD_NR_044_PLAN_2026-10-18.md": "docs/history/plans/AMD_NR_044_PLAN_2026-10-18.md"
}

当前目录结构可直接清点:plans 155 份、reports 344 份、releases 110 份,另有 rules、status、worklog 各 1 份;合计与执行记录中的“611 份历史文档/原规则移入 history”一致。索引首页第一句就写明性质:“这些文件描述其标题或日期对应的历史状态,不是当前任务或授权。”

第 4 步:单独处理代码维护成本

  • 先为 QmlPlayerBridge 按“片源与播放 / 增强设置 / 字幕与音频 / 导出与录制 / 设备状态”拆职责;然后拆 ProPage/DialogHost 的页面和对话框。每次一个边界,保留现有接口与配置格式。
  • 旧 Win32 界面还被 CMake 和部分字幕/测试目标引用,不能因为当前主界面是 QML 就直接删除 apps/veyra。先查依赖与实际构建目标,再迁移共用代码、做独立删除变更。
  • 整理 scripts/acceptance:正式回归入口集中维护,历史任务脚本入档;当前 610 个 scripts 文件不能简单按日期删除。
  • 每次拆分都先构建和做相应回归;采集/音频/补帧/颜色属于行为敏感链路,避免和磁盘卫生混在一个大变更里。

“不能删 apps/veyra”这条在构建脚本里能直接找到证据——旧 Win32 目标仍在被真实编译:

CMakeLists.txt:1635  add_executable(veyra WIN32 apps/veyra/main.cpp apps/veyra/ui/AppShell.cpp apps/veyra/ui/CapturePanel.cpp apps/veyra/ui/SubtitleOverlay.cpp apps/veyra/SettingsWindow.cpp apps/veyra/TelemetryWindow.cpp)
CMakeLists.txt:1642  add_executable(veyra_settings_layout_tests tests/integration/SettingsPageLayoutTests.cpp apps/veyra/SettingsWindow.cpp)
CMakeLists.txt:788   target_include_directories(veyra_control_paint_tests PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/apps/veyra/ui)

更隐蔽的是字幕:QML 桥接库仍在编译 apps/veyra/ui 下的 ASS 渲染器。

CMakeLists.txt:1132  ... apps/veyra/ui/SubtitleOverlay.cpp
CMakeLists.txt:1227  target_sources(veyra_qml_bridge PRIVATE apps/veyra/ui/AssSubtitleRenderer.cpp apps/veyra/ui/AssSubtitleRenderer.h)

也就是说 apps/veyra 名义上是“旧界面”,实际是共用实现宿主。这就是文档强调“先查依赖、再迁移共用代码、最后做独立删除变更”的原因。

关于脚本数量的口径:原方案记录当时为 610 个 scripts 文件;当前仓库 scripts/acceptance 下可直接清点为 417 个条目,说明该目录在此期间仍有增删。引用数量时应标注时点,这也正是本方案反复强调“快照不等于现状”的实践含义。

八、拆分落地后的真实形态(仓库现状核对)

方案的第 4 步已在仓库中执行完毕,形态可从 docs/ARCHITECTURE.md 与源码直接核对:

  • 公有入口 include/veyra/ui/QmlPlayerBridge.h 继续定义原有属性、方法与信号(当前包含 356 个 Q_PROPERTY、201 个 Q_INVOKABLE 声明)。
  • src/ui/QmlPlayerBridge.cpp 只保留启动、生命周期与轮询接线,当前 648 行(原 9233 行)。
  • src/ui/QmlPlayerBridge_p.h 集中保存原有私有状态、内部共享声明与无状态文本转换,962 行,并且明确“不是新公有 API”。

领域实现按职责分到 14 个独立编译单元:

实现文件(src/ui/bridge) 职责
Hardware.cpp 适配器、能力检测与缓存、可用后端选择
Capture.cpp 采集格式/音频设置与异步查询、屏幕采集与游戏模式接线
RemotePlay.cpp PS5/PC/Xbox 串流与手柄控制入口
Playback.cpp 文件/网络播放、源打开和播放命令
Enhancement.cpp NR/SR/AA/美颜等增强参数映射与校验
FrameGeneration.cpp 补帧后端、倍率、光流、显示同步/VRR 选择
Colour.cpp 调色参数表、曲线、LUT 与色彩 look
Subtitles.cpp 字幕加载/样式与音频同步;GDI+ 初始化仍只有一个实例
Recording.cpp 实时录制的界面控制与状态发布
Export.cpp 图片/视频导出设置、任务与状态
Chain.cpp 处理链/节点编辑与预设操作
Preferences.cpp 偏好、快捷键、组件信息及历史/导出入界面入口
Status.cpp GPU/阶段耗时、负载与运行状态
View.cpp 保护区域、对照与画面布局选择

拆分过程中有一条经验特别值得记录:共享的有状态资源不能在拆分中被复制。文档明确写着“带状态的硬件缓存、GDI+ 初始化和生命周期所有权没有复制到头文件;共享状态的布局和方法体保持”。执行记录给出了这条原则的反面案例——首次编译发现共享的 ensureGdiplus 仍留在字幕匿名命名空间,解决办法是“改成私有声明 + 唯一外部定义”,而不是在每个模块里各初始化一次。

QML 侧同理:

文件 拆分后行数 角色
qml/Veyra/DialogHost.qml 134 只做路由、遮罩和统一宿主
qml/Veyra/DialogLayer.qml 162 保持原有尺寸、动画和原生视频遮挡合同
qml/Veyra/ProPage.qml 2132 原 3213 行,保留原兼容类型与 HDR 观测可见性合同
qml/Veyra/ProAudioPanel.qml 99 音频面板复用组件
qml/Veyra/ProDisplayPanel.qml 698 显示面板复用组件

兼容入口被显式保留:DialogHost.VTextField 兼容名保留,旧 ProPage.PerfOrb / PerfOrbs / StatusSummary / PresentationRows 等入口保留兼容包装,节点页继续复用。这种“拆实现但不拆接口”的策略,是把重构风险限制在编译期和结构检查上的关键。

九、如何验证拆分没有改变行为

执行记录中的验证手段值得作为模板复用,因为它回答了“怎么证明只是搬家”:

  • 翻译一致性:翻译提取器读取桥接子目录和私有头,2681 条翻译及三种语言逐项一致。
  • 方法体逐项比对:681 个桥接方法体逐项 SHA 相同,QML 文案和 objectName 集合一致。
  • 结构迁移校验:发现三条 objectName 被宽泛 host 替换误改后,改为只重命名词法标识符、保护字符串和成员字段,最终恢复全部原名。
  • 构建:修复 ensureGdiplus 后产品构建 52.7 秒通过,随后 10 目标构建 23.2 秒通过。
  • 自动化与真实启动:run_checks.py 共 16 组通过;QtQuick 117 通过 / 0 失败 / 1 跳过;四次真实渲染器启动(软件/GPU/兼容重启、已选 SR 模型保存恢复)无 QML 错误;最终 shell_check 在两种模式各打开五个页签、十个对话框,完成 37% NR 比例预设的保存→改值→恢复并核对效果仍关闭;软件/GPU 两次私有配置播放各实际呈现 290 帧,退出码 0、无 QML/D3D 错误。

同时明确标注了边界:整个流程不连接采集卡或真实串流主机,没有重复实卡采集或 NR/GPU 全硬件推理/性能测试,相关引擎与运行库未改。这种“验了什么 / 没验什么”的成对记录,比单写“测试通过”更可审计。

十、恢复能力:bundle 是可验证的最小历史存档

方案把“可恢复”写成了强制步骤:需要移除分支前,用一份 bundle 并执行 verify,验证能恢复指定 tip。执行后的恢复手册在 docs/BRANCH_ARCHIVE.md 中给出可直接复制的命令:

git bundle verify E:/项目/Veyra/archives/project-maintenance-execution-20261027/source-before.bundle
git fetch E:/项目/Veyra/archives/project-maintenance-execution-20261027/source-before.bundle refs/heads/codex/release-2.1.1-20261027:refs/heads/codex/release-2.1.1-20261027

两条命令对应两个检查:

  1. verify 确认 bundle 自身完整、且包含声明的 refs;
  2. fetch 把表里具名分支的原 tip 取回到同名本地 ref,工作树再用 git worktree add 单独创建。

归档表本身记录了 122 个旧分支的完整 tip 与“原先是否为 main 祖先”,例如 claude/amd-sr-off-20261022 的 tip 为 1b94bae8e162266f7702455c96e906ec296a41e1、祖先标记为 False,codex/doc-cleanup-vram-amd-20261020 为 674536857305afad029738068b91500bc984ee2b、False。这份表的价值在于:即使 bundle 文件损坏,也还能按 tip 从其他副本比对恢复。

执行记录里对应的动作与读数是:source-before.bundle 已 verify 并覆盖全部原引用;退休产物证据 ZIP 为 341,177,909 字节,保存 12,160 份文件并逐 SHA 验证;cleanup_native.ps1 复核 54,827 个文件身份/mtime/size 后删除 43 个目录,E 卷空闲增加 24,123,240,448 字节(删除阶段读数,整体净变化另计)。

其中一条工程细节尤其重要:

首次准备检查发现六个旧构建内有 runtime junction,拒绝按普通目录处理;已改为记录链接目标、剪枝不遍历。执行时只删除已验证的链接入口,绝不递归其目标。

这直接呼应第 4 节的“硬链接/junction 不能按路径相加”。如果清理脚本按递归删除目录处理,runtime junction 会把删除操作导向它指向的真实运行库,后果不可逆。

十一、收尾与预防再次膨胀

方案最后给出 5 条长期约束,这是避免半年后重复同一场清理的关键:

  1. 依赖只留有身份清单的共享原件;C:/veyra-deps Junction 保留;patched FFmpeg 与对应源码、许可证保留。
  2. 一个任务一份可用运行目录,不同用例使用不同 data-dir/log/TEMP;只有需要修改运行内容的故障注入才额外复制,结束即回收。
  3. 已发布资产只有 releases 下的正式归档为长期入口;test-packages 和 verify 不再长期重复保留。
  4. 每次交付记录“当前分支 / 是否合 main / 保留的构建与运行供体 / 可清理目录 / 新增与回收空间 / 未验边界”。
  5. 清理执行前重新查进程、绝对路径、父链 reparse point、mtime/hash/link ID;执行后复核脏树、正式资产和当前构建。保留一份逐项回执及恢复映射,不改历史 guard/start 来伪造验证。

第 4 条的字段清单可以直接当作团队模板使用:它把“这次做了什么”变成六个可机械核对的槽位,其中“未验边界”是最容易被省略、也最容易被后来者误读的一项。

第 5 条的最后半句是整份文档态度最硬的地方——不允许为了让检查通过而修改历史脚本。这与仓库现状一致:历史 guard/start 未被改写,需要重跑旧诊断时应先按归档清单恢复历史环境(见 docs/history/INDEX.md 首页说明)。

十二、实际执行结果(对照快照与现状)

用户在执行记录中明确授权按方案执行 1–4 全部工作,施工分支 codex/project-maintenance-20261027,基线 main 7bf02d4,结构整理提交 d4b1034。结果可以按方案的分步结构核对:

维度 执行前快照 执行后
本地分支 132 10
工作树 101 12(收尾施工分支移除后)
退休产物目录 — 43 个已删除
已移除 E 盘干净工作树 — 89 个
退休分支引用 — 122 个(入 bundle)
历史文档归档 636 份受控文档 611 份移入 docs/history
E 盘空闲空间 — 相对开工前净增约 28.14 GiB(含保全归档/测试目录成本)

保留项与快照中的判断完全对应:main 为产品基线;6 个旧脏树(516 条状态记录)保留原位并已逐字节保全;Lecram 两条暂停线保留;带独有忽略内容的 C 盘树与 Codex 托管的脱离分支树保留;发行标签和远端 refs 不动;桌面共用 Git 库不迁移。

文档收尾也如期完成:根 AGENTS.md 从约 151 KiB 降到约 7 KiB,WORKLOG 改为短日志,CURRENT_STATUS 只保留当前事实,README/DEVELOPMENT/ARCHITECTURE/BRANCH_ARCHIVE 提供日常入口。当前 docs/ 目录下的 CURRENT_STATUS.md、DEVELOPMENT.md、ARCHITECTURE.md 就是这套“单一现在”的成品。

一个值得借鉴的处理细节:codex/doc-cleanup-vram-amd-20261020 里的文档纠偏没有整分支覆盖,而是“保留 10/20 用户确认:NV 显存增长已解决、AMD 用户实测无问题”,并且明确“不扩张成本轮新增硬件验证”。这既保留了有效事实,又没把旧状态当新结论。

十三、可直接复用的操作清单

把方案与执行记录压成一份顺序清单,便于在同类仓库上迁移:

阶段 A:只读核对

  1. git ls-remote 与本地 main、每条候选线的 tip 三方比对。
  2. git merge --ff-only <tag> 判定是否已合;返回 Already up to date. 即结束,不造空提交。
  3. git diff <tag> main -- <产品目录...> 限定到代码目录,排除文档提交。
  4. 正式包与源码重新计算 SHA256,与随包 .sha256 逐项比。
  5. 记录卷空间、在用进程、当前构建目录,作为后续净变化的基准。

阶段 B:可恢复性

  1. 保存 refs、worktree HEAD/status、脏树原字节、index/worktree patch、未跟踪文件、忽略目录清单。
  2. 生成一份 bundle 并 git bundle verify,确认能按 tip 恢复。
  3. 确认共用 .git 对象库的真实位置,标记为不可搬移项。

阶段 C:回收(先证据,后删除)

  1. 逐组列出候选:旧 CMake 构建、被替代的测试包、解压验证副本。
  2. 先保全脚本/配置/日志/源码记录/必要 EXE,再删可重建内容。
  3. 遇到 junction/symlink/reparse point:记录目标、剪枝不遍历,只删已验证的链接入口。
  4. 删除前复核文件身份/mtime/size;删除后以卷可用空间核对,而非按目录名统计。

阶段 D:收拢

  1. 干净且已合的工作树用 git worktree remove(不加强制);脏树与暂停线保留。
  2. 分支按“已等价并入 / 历史计划 / 交付记录 / 未完成工具 / 用户暂停 / 已撤回实验”分类后归档。
  3. 远端分支、发行标签、gc --prune=now、强推、重写历史一律不进本轮范围。

阶段 E:结构与文档

  1. 超大源文件按领域拆分,公有头与配置格式不动;共享有状态资源(缓存、GDI+ 初始化)全球唯一。
  2. 用“方法体 SHA 逐项比对 + 翻译条目一致 + QML objectName 集合一致”证明只是搬家。
  3. 构建 + 相关回归 + 真实启动检查;行为敏感链路(采集/音频/补帧/颜色)与磁盘清理分开提交。
  4. 文档只留一个“现在”,历史进索引 + 路径映射。

十四、适用前提与未验证边界

为了让这套方案被正确引用,需要明确它的约束条件:

  • 数字有时点。132 分支、101 工作树、636 文档、22.45 GiB 候选回收量都是 2026-10-27 的只读快照;执行后的实际值见 docs/PROJECT_MAINTENANCE_EXECUTION_2026-10-27.md 与 docs/CURRENT_STATUS.md。
  • 分配量不等于释放量。AllocationSize 不含目录/MFT 元数据,且硬链接/共享文件 ID 会让“删一处”不等于“释放全部”;最终必须以卷可用空间为准。
  • 验证范围有边界。结构整理轮的实际验证不连接采集卡或真实串流主机,未做 NR/GPU 全硬件推理与性能测试;相关引擎、运行库、着色器未改,所以“结构一致”不能外推为“所有硬件组合已验收”。
  • 路径是 Windows 风格。方案中的 E:/项目/Veyra/... 与现实构建(MSVC / Ninja / Qt 6.8.3)强绑定;换平台复用时,只有方法论(文件 ID 去重、bundle 验证、按职责拆分)可移植,具体命令需重写。
  • 本方案不涉及发布授权。push、Release、资产上传仍按用户当次请求单独授权;本轮只做本地整理与整合。

在这个项目里,这份方案真正解决的问题不是“省下 28 GiB”,而是把可验证的事实从数百份互相矛盾的历史陈述里分离出来:用一个 commit 证明基线,用一份 bundle 证明历史可恢复,用一次 SHA 比对证明资产未变,用一组领域文件证明代码还能被读懂。对于任何长期迭代、单人/多 Agent 交替接手的复杂桌面项目,这套顺序比任何单条清理命令都更有价值。

登录后查看全文
Veyra-NRVideo