TurboQuant+ 上游化实战指南：llama.cpp KV Cache 压缩分支的 4 阶段 PR 重构路线图-开发者社区

【免费下载链接】turboquant_plus

项目地址：https://gitcode.com/gh_mirrors/tu/turboquant_plus

本文档围绕仓库 docs/upstream-pr-plan.md 展开，系统梳理 TurboQuant+ 项目如何把自家 llama.cpp fork 上 43 个 commit 的 KV Cache 压缩分支，改造成符合 ggml-org/llama.cpp 上游评审标准、可逐步合并的 PR。读者读完将掌握：上游对新增量化类型（ggml_type扩展）的强制交付物清单、AI 使用政策与贡献者规则、从"先共识后代码"的 Phase 0 到 CPU-only 参考实现的 Phase 1 分阶段提交策略，以及 commit 级取舍、风险缓解与编码风格自查的完整操作框架。

1. 背景：一个 Metal-first 分支的上游化挑战

1.1 分支现状与目标

TurboQuant+ 项目的 llama.cpp fork 上维护着feature/turboquant-kv-cache分支，其体量与意图可以从 docs/upstream-pr-plan.md 开篇确认：

43 个 commit分布在 29 个文件上；
累计13,811 行插入；
目标是把 TurboQuant KV cache 压缩方案合并进 ggml-org/llama.cpp。

需要说明的是，本仓库（turboquant_plus）是项目的研究之家：Python 参考实现、验证论文与基准数据都在这里，而真正的 llama.cpp 生产实现位于独立的llama-cpp-turboquant生产 fork（详见 README.md 的 "Run It Today" 引擎对照表）。因此这份 PR 计划文档本质上是"研究 → 上游"的交接路线图，文档中的所有文件路径（ggml-common.h、src/llama-kv-cache.cpp、common/arg.cpp等）均指向上游 llama.cpp 源码树，而非本仓库。

1.2 上游化之前的既定事实

在进入 PR 计划之前，仓库已有大量验证沉淀可供 PR 引用：

质量基线：docs/benchmarks.md 记录了 M5 Max 128GB 上的 PPL 对照（turbo4 4.25 bits/val、3.8x 压缩、PPL +0.23% vs q8_0；turbo3 4.6x 压缩、+1.06%），以及 2K–32K 的 prefill context scaling 数据；
算法实现：PLAN.md 定义了 PolarQuant + QJL 的完整算法骨架；turboquant/polar_quant.py、turboquant/rotation.py、turboquant/codebook.py、turboquant/qjl.py 与 turboquant/turboquant.py 构成 Python 参考实现；
生产形态：README 明确生产实现弃用 QJL、仅用 MSE-only PolarQuant（详见 docs/papers/turbo4-resurrection.md 的消融研究），这与 PR 计划中 "MSE-only PolarQuant, no QJL" 的提交变体选择一致。

这些既有成果决定了 PR 计划的第一个关键判断：不能把现有分支直接清理后提交，必须重构。

2. 上游硬性门槛：规则、流程与贡献者体系

2.1 AI 使用政策（CRITICAL）

llama.cpp 上游项目对 AI 生成代码有严格政策，这是本计划列出的第一条"关键上游要求"：

项目不接受完全或主要由 AI 生成的 PR；
AI 仅可作为辅助工具（纠错、扩充冗长修改）；
由 AI 初步生成、随后人工编辑的代码仍视为 AI 生成；
AI 生成的帖子（bug report、PR 描述、讨论、回复人类）严格禁止；
反复违规 → 永久封禁；
如果使用了 AI，必须：① 明确披露 AI 的使用方式；② 提交前做全面人工审查；③ 准备好向维护者逐行解释每一行代码。

完整政策位于上游仓库的AGENTS.md。计划文档对"实战影响"给出务实判断（引用其原文要点）：诚实披露是有先例的——NVFP4 PR 披露了 Claude 的使用并顺利合并；真正的门槛是当维护者询问时能解释每一行——而 Tom（项目作者）构建了整个实现，能够做到；PR 描述与讨论帖必须由 Tom 本人撰写，而非 AI。该政策是倡导性的，实际执法落脚在"理解你的代码 + 诚实披露"。

2.2 贡献者等级体系

上游的协作角色决定了本计划的资源约束：

等级	权限与义务
Contributors（本项目当前所处位置）	无特殊特权，最多同时 1 个开放 PR
Collaborators (Triage)	重大贡献者，拥有部分代码所有权，参与评审与维护
Maintainers	评审并在 code owner 批准后合并 PR

"最多 1 个开放 PR"直接催生了本计划的核心洞见——不能把一次宝贵的 PR 机会浪费在未解决的设计问题上（详见第 3 节 Codex 审查与第 5 节 Phase 0）。

2.3 新量化类型的 8 项强制交付物

新增ggml_type扩展（本计划的GGML_TYPE_TURBO3_0即属于此类）必须满足以下 8 项强制要求：

#	交付物	说明
1	GGUF 模型转换	转换一个小模型并上传到 HuggingFace
2	PPL vs FP16/BF16	在 wikitext-2 上用`llama-perplexity`，以原生精度为基线
3	PPL vs 相似大小类型	与 q4_0、q3_K 等同类位宽类型对比
4	KL 散度 vs FP16/BF16	`llama-perplexity --kl-divergence`（logit 文件可达 11–37 GiB）
5	KL 散度 vs 相似大小类型	与第 4 项同一对比集合
6	CPU 性能	仅 CPU 运行`llama-bench`，与相似大小类型对比
7	测试用例	加入`test-backend-ops`验证后端一致性（要求 2+ 后端）
8	完整 CI 本地通过	`bash ./ci/run.sh ./tmp/results ./tmp/mnt`

计划文档随后在 Phase 1 的"必需交付物"表中逐项给出了当前状态（见第 5.2 节），其中多项标注为"❌ Not yet"，也有若干项（GGUF 上传）因 KV-cache-only 类型这一特殊性被标注为"❓ 需在 Phase 0 澄清"——这正是第 3 节 Codex 审查发现 #2 的落地。

2.4 过程与代码规范

过程规则（原文逐条继承）：

初始 PR 仅包含 CPU 支持，Metal/CUDA 在后续 PR 中跟进；
新贡献者最多 1 个开放 PR；
维护者采用 squash-merge（提交格式：<module> : <commit title> (#<issue_number>)）；
无第三方依赖、无额外文件、无额外头文件；
跨 OS 与跨架构兼容；
命名与格式：snake_case、4 空格缩进、clang-format v15+；
用struct foo {}而非typedef struct；
公共 API 使用定长整型（int32_t而非int）；
枚举值 UPPERCASE 且以枚举名作前缀；
命名遵循<class>_<method>（其中<method>为<action>_<noun>）；
使用最长公共前缀命名（如number_small/number_big，而非small_number/big_number）；
C/C++ 文件名小写带连字符，.h/.c/.cpp；
张量以行主序存储（dim 0 = 列、1 = 行、2 = 矩阵）；
ggml_mul_mat(ctx, A, B)的语义是C^T = A * B^T ⟺ C = B * A^T——这是一个非常规约定，移植时最容易出错。

2.5 社区背景：量化类型泛滥的担忧

计划文档记录了上游社区对"新增量化格式"的阻力背景：

存在 Issue #20977（由 mudler 提交的功能请求）与 Discussion #20969；
维护者 JohannesGaessler 明确表态："除非 PR 作者被公认为专家，否则我们不应继续增加量化格式"；
维护负担现实：新量化类型会增大二进制体积、延长编译时间，并要求 CUDA、Metal、Vulkan 等后端协同扩展。

这条背景直接解释了为什么 Phase 0（社区共识）被设计为 BLOCKING 级别的步骤，也解释了为什么计划要求展示"quality-per-bit 相对现有类型的优势"来证明维护负担值得承担。

3. Codex 审查发现的 6 个关键问题及对策

计划文档记录了对初版计划的 Codex 5.4 审查，共发现 6 个关键问题，且全部已在修订版计划中解决：

#	Codex 发现	对策
1	提交的确切变体质量未证明——PPL 165.6 危机仍留在文档中	必须证明确切提交的 CPU 代码路径质量稳定（参见 docs/turboquant-plus-experiments.md 的 Key Learning #6："Always run perplexity. 'Coherent text' evaluation caught nothing when PPL was 165"——速度数字若无质量验证毫无意义）
2	GGUF 要求可能不适用于 KV-cache-only 类型——TurboQuant 是运行时 cache 类型，不是模型量化格式	与维护者澄清，放入 Phase 0 的开放问题
3	在 Phase 1（代码）之前需要 Phase 0（共识）——不要在一次 PR 机会上赌未解决的设计问题	先在 Issue #20977 发帖
4	维护者赞助是阻塞项，而非锦上添花	提交前先找到愿意支持 PR 的 collaborator/maintainer
5	commit 结构太粗	将图（graph）改动与类型/管道改动分开，每个 commit 必须可构建
6	旋转数据头文件应生成而非静态——12K+ 行预计算数据会遭抵制	在代码中确定性生成

其中第 6 点与仓库源码直接呼应：turboquant/rotation.py 中的random_rotation_dense(d, rng)（第 25 行起）正是"以种子为输入的确定性旋转生成"——QR 分解得到 Haar 分布正交矩阵，并用slogdet保证 det = +1；tests/test_rotation.py 的test_deterministic_same_seed验证了"同种子 → 同矩阵"。这为上游"生成式旋转矩阵"提供了算法蓝本。

4. 核心矛盾：Metal-first 分支 vs CPU-first 上游

计划文档明确指出了无法直接 PR 的根因：

我们的 43 个 commit 围绕 Metal GPU 优化构建，而上游要求 CPU-first。不能只是清理分支然后提交——必须重构。

更隐蔽的第二重问题（Codex 补充）：CPU 与 Metal 可能实现的不是同一算法变体——CPU 在 C 代码中使用 dense rotation，Metal 使用 WHT（Walsh-Hadamard Transform），二者产生数值不同的结果。因此提交的 CPU 路径必须自洽且被独立验证。

这一点同样有仓库源码佐证：turboquant/rotation.py 同时实现了两种旋转：

random_rotation_dense（第 25 行起）：稠密 QR 旋转，O(d²) 矩阵乘，精确；
random_rotation_fast（第 75 行起）+fast_walsh_hadamard_transform（第 99 行起）：D1 @ H @ D2结构化旋转，O(d log d)，近似。

计划文档在第 8 节风险评估中把"跨后端语义分歧（CPU dense vs Metal WHT）"列为 MEDIUM 风险，缓解措施是"Phase 1 仅 CPU，暂时不成问题；为 Phase 2 记录文档"。

5. 4 阶段 PR 策略

修订后计划从"3 阶段、Metal-first 分支清理、静态头文件、营销式 PR 语言"转变为4 阶段、先社区共识、手工干净重写、生成式旋转数据、中性 PR 语言、维护者赞助作为阻塞项。

5.1 Phase 0：社区共识（BLOCKING —— 任何代码之前）

目标：在写一行 PR 代码之前，先获得维护者对设计的认可。

动作清单：

在 Issue #20977 发帖，包含：
- 确切的算法变体：MSE-only PolarQuant、无 QJL、block size 32、graph 侧 WHT 旋转；
- block 结构布局的字节级细节；
- 基准表：PPL vs FP16、vs q8_0、vs q4_0、vs q3_K；
- KLD 数据；
- CPUllama-bench数字；
- 开放问题（详见第 10 节）：
  - KV-cache-only 的ggml_type是否要求 GGUF 模型上传，还是可复现的基准脚本即足够？
  - 确定性旋转矩阵生成是否可接受，还是维护者偏好更小的查找表？
  - 命名偏好：turbo3_0vstq3_0vs 其他？
- fork 链接供任何人测试；
找到愿意支持的 collaborator/maintainer 作为赞助者；
等待设计反馈后再继续。

退出标准：至少一位维护者/collaborator 确认了方案且未提出阻塞性问题。

关于"确切的算法变体"，仓库源码可提供精确对照：MSE-only 即 turboquant/turboquant.py 中的TurboQuantMSE类（第 152 行起，纯 PolarQuant 无 QJL 阶段）；block 的 norm 存储对应 polar_quant.py 的 norm 提取与 rescale 逻辑（第 56–119 行）；graph 侧旋转即 docs/pre-rotate-queries-plan.md 描述的 pre-rotate-queries 技巧。

5.2 Phase 1：最小 CPU 参考实现（PR #1）

目标：让GGML_TYPE_TURBO3_0作为仅含 CPU 后端的新 KV cache 类型被接受。

算法变体冻结策略：冻结在 CPU 上经过质量验证的任意变体。若 block-32 + MSE-only + pre-rotate 在 CPU 上验证通过（PPL 确认），就使用它；否则回退到 block-128（最后已知正确者），在 Phase 2 再优化。注意：计划中冻结的是"block size 32"，而仓库 docs/papers/block-size-experiment.md 显示 block-128 可达 5.12x 压缩且 PPL 不变——这正是"回退方案"的底气来源。

包含内容：

文件（上游源码树）	内容
`ggml-common.h`	`block_turbo3_0`结构体定义
`ggml.h`/`ggml.c`	`GGML_TYPE_TURBO3_0`注册、类型特性
`ggml-turbo-quant.c`	CPU 量化/反量化（MSE-only，无 QJL）
`ggml-cpu/ops.cpp`	CPU 后端对 turbo3 的支持
`src/llama-kv-cache.cpp`	turbo3 的 KV cache 分配
`src/llama-graph.cpp`	graph 侧 WHT 旋转（pre-rotate-queries）
`common/arg.cpp`	`--cache-type-k turbo3 --cache-type-v turbo3`CLI 标志
`tests/test-backend-ops.cpp`	turbo3 的后端一致性测试
旋转矩阵生成代码	确定性生成，而非静态头文件

排除内容：

所有 Metal kernel 代码；
所有 Metal 专属头文件（turbo-wht.h、turbo-matrices.h）；
GGML_OP_TURBO_WHT；
质量门脚本；
所有文档类 commit；
静态旋转数据头文件（替换为生成代码）。

Commit 结构（4 个 commit，每个均可构建）：

#	Commit 标题	范围
1	`ggml : add GGML_TYPE_TURBO3_0 type with block struct and traits`	类型枚举、block_turbo3_0、type_traits、size/alignment
2	`ggml : add TurboQuant CPU quantize and dequantize`	ggml-turbo-quant.c、旋转矩阵生成、centroid 表
3	`llama : add TurboQuant KV cache support with graph-side rotation`	KV cache 初始化、graph 旋转张量、CLI 标志
4	`tests : add TurboQuant backend-ops and round-trip tests`	test-backend-ops 条目、独立 round-trip 测试

注：维护者最终 squash-merge，因此这些 commit 合并后变为 1 个 commit；但评审期间 4 个可构建的 commit 使评审成为可能。

必需交付物（当前状态）：

交付物	状态	备注
PPL vs FP16 on wikitext-2	❌ 未完成	需要 f16 基线，而非仅 q8_0
PPL vs q8_0、q4_0、q3_K	❌ 未完成	必须做相似大小对比
KL 散度 vs FP16	❌ 未完成	需要 11–37 GiB 基线 logits 文件
KL 散度 vs q4_0、q3_K	❌ 未完成	同一对比集合
CPU`llama-bench`vs q8_0、q4_0、q3_K	❌ 未完成	纯 CPU，无 Metal
GGUF 模型上传（如要求）	❓ Phase 0 澄清	可能不适用于 KV-cache-only 类型
test-backend-ops 集成	❌ 未完成	需要 2+ 后端
本地完整 CI 通过	❌ 未完成	`bash ./ci/run.sh`
PR 描述中的 AI 披露	❌ 草稿待写	必须由 Tom 撰写，而非 AI
基于最新 master 的 rebase	❌ 未完成	提交前立即执行
维护者/collaborator 赞助	❌ 未完成	BLOCKING—— 来自 Phase 0
CPU 路径端到端验证	❌ 未完成	验证 CPU 反量化 + graph 旋转在无 Metal 时可用

PR 描述指南（原文要点）：

由 Tom（人类）撰写，而非 AI 生成；
中性、技术性语气，无营销语言；
以基准数据开篇，而非声明；
不要说"与 q8_0 相差 1% 以内"——给出表格，让评审者自行判断；
引用论文（arXiv 2504.19874）说明算法细节；
明确披露 AI 使用，示例措辞："Claude 用于代码库导航与调试。所有代码均经人工审查与测试。";
引用 Issue #20977。

5.3 Phase 2：Metal 后端（PR #2，在 Phase 1 合并之后）

目标：为 turbo3 KV cache 添加 Metal GPU 支持。

包含内容：

Metal 反量化 kernels（dequantize_turbo3_0、dequantize_turbo3_0_t4）；
turbo3 的 flash attention 模板实例化；
fp16 centroid LUT 优化；
float norm 广播优化；
turbo-wht.h（Metal Fast Walsh-Hadamard）；
GGML_OP_TURBO_WHT（自定义 graph op，Metal 路径需要时）。

必需交付物：

Metalllama-bench结果 vs CPU 与 q8_0；
上下文扩展验证（2K–32K）；
现有 Metal 测试无回归；
数值一致性：Metal 与 CPU 输出一致（或记录/接受可接受的分歧）。

仓库端 docs/pre-rotate-queries-plan.md 提供了该阶段所需的底层细节：pre-rotate-queries 技巧的数学基础是⟨q, R^T·centroids[idx]⟩ = ⟨R·q, centroids[idx]⟩——即把每次 dequant 时对每个 KV 位置做的 128 次 WHT 逆旋转，换成对单个 query 做一次旋转；该文档还记录了 Codex 的 7 项审查确认（旋转固定共享、归一化一致、以 KV cache 配置类型而非瞬时张量类型作为门控等）。

5.4 Phase 3：高级功能（PR #3+，可选）

层自适应 KV cache（per-layer 精度）；
turbo2/turbo4 类型；
非对称 K/V 压缩。

这些与仓库实验路线一一对应：层自适应见 docs/experiment-layer-adaptive-extended.md（"最后 8 层承担了 turbo3 几乎全部质量损失"），非对称 K/V 见 docs/papers/asymmetric-kv-compression.md 与 README.md 的"V compression is free"关键发现。

6. 当前分支 → PR 映射：commit 级取舍

6.1 Phase 1 的 7 个关键 commit（正确性参考）

Phase 1 PR 将是对分支中 CPU-only 代码的干净提取，而非 cherry-pick。原因是：① 分支是 Metal-first 而 Phase 1 仅 CPU；② 静态旋转头文件需替换为生成代码；③ 确切算法变体必须先冻结并在 CPU 上验证；④ 代码需遵循上游命名/风格约定（snake_case 等）。

作为正确性参考的关键 commit：

Commit	用途
`4ff5bf8`	核心类型定义（block 结构布局）
`099ceab`	TURBO_D=128 与 block size 解耦
`a696962`	block size 32 格式
`3032b23`	MSE-only 模式（无 QJL）
`1f02172`	逆旋转修复（关键质量 bug）
`2bbe32f`	pre-rotate-queries 方法（graph 侧旋转逻辑）
`ccbac3f`	优化反量化（字节提取模式）

6.2 完全丢弃与推迟的 commit

完全丢弃：

12 个纯文档/调查类 commit；
2 个失败的实验 commit（c6aa8ce、e40ca6f）。

推迟到 Phase 2（Metal）：

bf0e223、48da1d8、cf8ac72：Metal kernels 与旋转矩阵；
8e5e663、8d682bd：Metal 专属修复；
8aa0999：WHT 基础（Metal）；
69af339：GGML_OP_TURBO_WHT；
676f929、e4e0bde、640e10e、c84e124：graph WHT 优化；
a0e8a65、ccbac3f：反量化优化（Metal 路径）；
654647a、aa6a3a1：decode 速度优化；
9cd0431：质量门脚本。

这一取舍逻辑与 docs/turboquant-plus-experiments.md 的"MERGED（in production）"清单（speed-optimization、context-scaling-fix 分支）吻合——Metal 侧的优化成果（fp16 WHT、half4 butterfly、graph-side rotation、block-32）正是 Phase 2 的素材。

7. 按优先级排序的工作项

7.1 BLOCKING（提交 PR 前必须完成）

#	工作项	阻塞原因	状态
1	Phase 0：在 Issue #20977 发帖	无维护者认可无法提交 PR	❌
2	找到维护者/collaborator 赞助	新 ggml_type 被接受的前提	❌
3	冻结 CPU 上的算法变体	必须证明确切提交的代码质量稳定	❌
4	用生成代码替换静态旋转头文件	12K 行静态数据会被拒绝	❌
5	CPU 端到端验证	验证 CPU 反量化 + graph 旋转在无 Metal 下可用	❌
6	PPL vs FP16 基线	强制交付物	❌
7	PPL vs 相似大小类型（q4_0、q3_K）	强制交付物	❌
8	KL 散度 vs FP16	强制交付物（11–37 GiB logit 文件）	❌
9	KL 散度 vs 相似大小类型	强制交付物	❌
10	CPU`llama-bench`	强制交付物	❌
11	test-backend-ops 集成	新 ggml 算子的强制要求	❌
12	完整 CI 通过	`bash ./ci/run.sh ./tmp/results ./tmp/mnt`	❌
13	基于最新 master rebase	提交前立即执行	❌
14	人工撰写的 PR 描述	AI 生成的帖子被禁止	❌
15	AI 披露声明	政策要求	❌

7.2 STRENGTHENING（提高接受概率）

#	工作项	影响
16	多模型 PPL（Qwen + LLaMA）	证明普适性
17	各上下文长度的 NIAH 测试结果	展示实际质量
18	与 q4_0 对比 quality-per-bit	证明维护负担值得
19	CODEOWNERS 条目	表明长期承诺
20	澄清 KV-cache-only 类型的 GGUF 要求（Phase 0）	避免照抄清单式的应付

其中第 17 项可直接取材于仓库 proof/niah 目录的 NIAH 验证结果与 docs/benchmarks.md 的检索数据（turbo4 单针检索 31/33，甚至超过 q8_0 的 30/33）。

8. 风险评估与缓解

风险	严重度	缓解
"量化类型太多"被拒	高	Phase 0 共识 + 展示对现有类型的 quality-per-bit 优势
AI 生成代码疑虑	高	为 PR 手工干净重写、诚实披露、逐行解释
CPU 性能可能不佳	中	O(d²) 旋转按 batch 而非按 token 摊销；先基准测试，若不佳则 CPU 实现 FWHT
旋转数据体积受抵制	中	在代码中确定性生成，而非静态头文件
"侵入过深"——同时触及 ggml 类型系统与 llama graph	中	干净拆分 commit，每个 commit 最小且可构建
block-32 质量在 CPU 未证明	中	必要时回退 block-128，之后再优化
跨后端语义分歧（CPU dense vs Metal WHT）	中	Phase 1 仅 CPU 所以暂不成问题；为 Phase 2 记录文档
KLD logit 文件 11–37 GiB	低	提前规划磁盘空间
rebase 冲突（master 变动快）	低	提交前立即 rebase，保持 PR 小巧
找不到维护者赞助	高	若 Phase 0 无进展，重新评估上游化是否可行 vs 维护 fork

9. 编码风格核对清单

提交前必须逐项验证（来自上游 CONTRIBUTING.md）：

函数、变量、类型使用 snake_case
4 空格缩进，花括号同行
指针/引用空格规范（void * ptr、int & a）
struct foo {}而非typedef struct foo {} foo
C++ 中省略可选的struct/enum关键字（如llama_context * ctx而非struct llama_context * ctx）
公共 API 使用定长整型（int32_t而非int）
枚举值 UPPERCASE 且带枚举名前缀（GGML_TYPE_TURBO3_0）
<class>_<method>命名 + 最长公共前缀
C/C++ 文件名小写带连字符
无行尾空白
clang-format v15+ 兼容
无第三方依赖
跨平台兼容（CPU 路径无 Apple 专属代码）
为可读性做垂直对齐

10. Phase 0 开放问题

KV-cache-only 的ggml_type是否要求 GGUF 模型上传？还是"可复现的基准脚本 + 参考模型"即足够？
确定性旋转矩阵生成（seeded PRNG → 正交矩阵）是否可接受？还是维护者偏好其他方案（如纯 Hadamard、无随机成分）？
类型命名偏好：GGML_TYPE_TURBO3_0、GGML_TYPE_TQ3_0还是其他？
graph 侧旋转（修改build_attn以插入 Q 旋转的ggml_mul_mat）对量化 PR 而言是否是可接受的改动范围？还是应作为独立功能 PR？
维护者希望旋转放在反量化路径内部（图更简单、更慢），还是 graph 侧（更快、但触及更多文件）？

其中第 2 问在仓库中已有两种候选答案：random_rotation_dense（随机 QR 正交矩阵）与 random_rotation_fast（Hadamard + 随机符号，无随机旋转成分的纯结构化方案）；后者正是 README 所述上游已合并的 Hadamard KV 旋转思路的雏形。

11. 总结：从"清理分支"到"先共识后最小化交付"

计划的对照总结（原文要点）：

旧计划：3 阶段、Metal-first 分支清理、静态头文件、PR 中带营销语言；
新计划：4 阶段、始于社区共识、手工干净重写 CPU 路径、生成式旋转数据、中性 PR 语言、数据先行呈现、维护者赞助作为阻塞项。

贯穿全文的核心洞察来自 Codex 审查：不要把唯一的一次 PR 机会浪费在未解决的设计问题上——先获得认可，再交付最小的正确产物。对任何准备把自研 KV cache 压缩方案推进 llama.cpp 上游的团队而言，这份计划的"Phase 0 → 8 项强制交付物 → CPU-only 最小 PR → 分阶段后端扩展"路径，本身就是一个可复用的开源贡献模板；而对 TurboQuant+ 而言，它把仓库中已验证的算法成果（MSE-only PolarQuant、pre-rotate-queries、确定性旋转生成、norm correction）与上游规则逐一对齐，给出了从"研究之家"走向"上游合入"的具体行动清单。