Veyra-NRVideo 2.1.1 基线核对与仓库瘦身实战:从 132 个分支、101 个工作树收敛到一条可维护主线
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 逐项比较一致 |
才可作为“保留基线” |
这五条覆盖了三个容易出错的维度:
- 引用等价 ≠ 内容等价。标签解引用相同只说明 ref 指向同一对象,所以还要用
git diff限定到真正的产品目录(src include apps qml i18n shaders CMakeLists.txt),把“文档提交”排除在比较范围外。 - 能快进却不合并不等于漏合并。
--ff-only返回Already up to date.说明 main 已包含该提交,此时再执行一次合并只会得到空提交,污染历史。 - 哈希要逐项比,不能只看有没有文件。方案要求重新计算两个正式包及应用源码的 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.cpp9233 行ProPage.qml3213 行DialogHost.qml2277 行
并给出关键限定:这些要按职责拆分,而不是凭文件大小删除;并且 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。三个关键设计:
- 文件身份用
os.stat的卷 ID + 文件 ID,而不是路径。同一个物理文件被多处链接时,只算一次。 - 分配量用
FileStandardInfo.AllocationSize,而不是逻辑长度。文件“有多长”和“占了多少簇”是两件事。 - 无法取得分配量的文件 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 步:建立可恢复清单
- 保存 refs、worktree HEAD/status、卷空间、在用进程、当前正式包 SHA。只读盘点已完成。
- 处理脏树前保存原始字节、index 和 worktree patch、未跟踪文件;不要只备份已提交的 Git 历史。唯一模型/输入媒体和忽略脚本也要单列。
- 移除分支前使用一份 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
两条命令对应两个检查:
verify确认 bundle 自身完整、且包含声明的 refs;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 条长期约束,这是避免半年后重复同一场清理的关键:
- 依赖只留有身份清单的共享原件;
C:/veyra-depsJunction 保留;patched FFmpeg 与对应源码、许可证保留。 - 一个任务一份可用运行目录,不同用例使用不同
data-dir/log/TEMP;只有需要修改运行内容的故障注入才额外复制,结束即回收。 - 已发布资产只有
releases下的正式归档为长期入口;test-packages和verify不再长期重复保留。 - 每次交付记录“当前分支 / 是否合 main / 保留的构建与运行供体 / 可清理目录 / 新增与回收空间 / 未验边界”。
- 清理执行前重新查进程、绝对路径、父链 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:只读核对
git ls-remote与本地 main、每条候选线的 tip 三方比对。git merge --ff-only <tag>判定是否已合;返回Already up to date.即结束,不造空提交。git diff <tag> main -- <产品目录...>限定到代码目录,排除文档提交。- 正式包与源码重新计算 SHA256,与随包
.sha256逐项比。 - 记录卷空间、在用进程、当前构建目录,作为后续净变化的基准。
阶段 B:可恢复性
- 保存 refs、worktree HEAD/status、脏树原字节、index/worktree patch、未跟踪文件、忽略目录清单。
- 生成一份 bundle 并
git bundle verify,确认能按 tip 恢复。 - 确认共用
.git对象库的真实位置,标记为不可搬移项。
阶段 C:回收(先证据,后删除)
- 逐组列出候选:旧 CMake 构建、被替代的测试包、解压验证副本。
- 先保全脚本/配置/日志/源码记录/必要 EXE,再删可重建内容。
- 遇到 junction/symlink/reparse point:记录目标、剪枝不遍历,只删已验证的链接入口。
- 删除前复核文件身份/mtime/size;删除后以卷可用空间核对,而非按目录名统计。
阶段 D:收拢
- 干净且已合的工作树用
git worktree remove(不加强制);脏树与暂停线保留。 - 分支按“已等价并入 / 历史计划 / 交付记录 / 未完成工具 / 用户暂停 / 已撤回实验”分类后归档。
- 远端分支、发行标签、
gc --prune=now、强推、重写历史一律不进本轮范围。
阶段 E:结构与文档
- 超大源文件按领域拆分,公有头与配置格式不动;共享有状态资源(缓存、GDI+ 初始化)全球唯一。
- 用“方法体 SHA 逐项比对 + 翻译条目一致 + QML
objectName集合一致”证明只是搬家。 - 构建 + 相关回归 + 真实启动检查;行为敏感链路(采集/音频/补帧/颜色)与磁盘清理分开提交。
- 文档只留一个“现在”,历史进索引 + 路径映射。
十四、适用前提与未验证边界
为了让这套方案被正确引用,需要明确它的约束条件:
- 数字有时点。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 交替接手的复杂桌面项目,这套顺序比任何单条清理命令都更有价值。