企业官网建设流程全解析

llama.cpp 代码评审技能：PR 前自检清单与高频审查陷阱全解（skills/code-review）

【免费下载链接】llama.cppLLM inference in C/C++项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp

llama.cpp 在仓库的 skills/code-review/SKILL.md 中内置了一个结构化的代码评审技能，它把项目约定（AGENTS.md、CONTRIBUTING.md）与维护者在历次 PR 中最常标记的问题固化为可执行的检查清单。本文以该技能文档为主体，逐节还原其两种评审模式、按路径分桶的清单选择机制、必跑的"快速否决"门禁与"安全审查"，并结合仓库源码（CUDA warp 尺寸宏、include/llama.h回调、gguf-py张量映射等）说明每条规则背后的实现依据，帮助你在推送 PR 之前自行完成一次高保真的"预评审"。

1. 技能定位：两种评审模式与"私有笔记"硬规则

该技能的描述为：在 PR 提交前，对照项目约定与常见审查陷阱评审 llama.cpp 的变更。它提供两种模式：

• 自评审（默认模式）：评审贡献者本人的本地变更——未提交的工作，或分支相对master的差异，作为 PR 前的预检。若无法判断评审对象，应先询问；默认使用git diff master...HEAD加未提交变更。
• 只读评审（PR/文件模式）：当用户指向某个 PR 编号或具体文件（包括别人写的代码）时，评审这些内容并汇报发现。

无论哪种模式，输出都是供用户自己阅读和处理的私有评审笔记，绝不是可以直接发布的评论。这是 AGENTS.md 中的硬规则（见其 "Prohibited Actions" 一节，AGENTS.md#L89-L99）：Agent 在任何情况下都不得代写 PR 描述、PR 评论、审查评论或对 reviewer 的回复，包括通过gh命令的任何方式；技能明确要求"不要主动提出代写；若用户要求发布评审笔记，应拒绝并指出该规则"。

前置阅读：开始评审前，若上下文中还没有，应先读 AGENTS.md 和 CONTRIBUTING.md——其中 "Coding guidelines"、"Naming guidelines" 与 AI 使用政策章节就是本评审执行的基线。如果 diff 涉及新增模型架构，还应读 docs/development/HOWTO-add-model.md，并考虑配套的 add-new-model 技能。

2. Step 0：划定 diff 范围，选择适用的检查清单

评审的第一步是搞清楚"到底改了什么、哪些区域清单适用"。运行git diff --stat（PR 模式下可用gh pr view <n> --json files），然后把触碰到的路径分桶：

规则是："范围与快速否决门禁"、"安全审查"、"General" 三份清单每次都跑；路径被触碰到的每个区域清单也要跑。此外，如果 diff 引入了新组件、新子系统或新基础设施（新文件/类/模块、新抽象、手工造轮子），还要额外运行"方法与设计"评审。执行时要告诉用户你跑了哪些清单、为什么跑。

3. 范围与快速否决门禁（始终执行）

技能强调：以下模式是让 PR 不经过完整评审就被直接关闭的情形，必须最先检查——这里的一条发现比任何代码细节都重要，因为它意味着这个变更当前形态下根本不该以 PR 出现：

• 是否有对应的前置 issue/discussion？按 CONTRIBUTING.md 的 "Pull requests (for contributors & collaborators)" 一节，功能必须先以 issue 起步而不是 PR——"Features must begin with an issue, not a PR"。如果这是一个非平凡功能却没有关联 issue，应标记并建议先开 issue。
• 是否与已有/进行中的工作重复？建议用gh search prs/gh search issues检索该功能；历史上很多被关闭的 PR 都是排队中工作的重复。
• 是否自包含、单一目的？多个不相关的变更/优化打包在一起会被要求拆分。标记无关变更，建议拆成独立 PR（对应 CONTRIBUTING.md "Create separate PRs for each feature or fix"）。
• 是否同时动了多个 ggml backend？按 CONTRIBUTING.md，新模型/新功能的初始 PR 应只做 CPU 支持，CUDA 等其他 backend 作为后续 PR。把 CUDA/Metal/Vulkan 等改动打包进功能的首个 PR 要被标记。
• 是否新增ggml_type/ 量化类型？这带来不成比例的维护负担，需要完整的论证材料包（GGUF 样例上传、对 FP16/BF16 与相近尺寸类型的困惑度对比、KL 散度数据、纯 CPU 性能数据）——CONTRIBUTING.md 明确列出了这些最低附加标准。缺少这些材料，无论代码质量如何都会被拒。
• 是否过于侵入式？新子系统、核心 API 重塑、修改其他模型不需要的共享 graph/sampler 代码——应标记并建议先与维护者讨论再投入。
• 是否是小众/厂商特定的实现，且会增加无人长期认领的维护负担？标记维护归属问题（呼应 CODEOWNERS 的协作人/维护人机制）。
• 语义是否正确，还是"看起来像修复"但其实误解了代码？要核对真实行为，而不只是验证能编译。
• AI 披露：如果 AI 有实质贡献，PR 模板的披露部分是否已填写（模板见 .github/pull_request_template.md）。提醒用户即可；永远不要建议替用户写 PR 描述或提交信息。

4. 安全审查（每次必做，任何发现都是阻断级）

这是每个评审的强制部分。技能的总原则是：GGUF 元数据、张量形状、tokenizer/grammar 输入、以及所有 server/RPC 字段都是攻击者可控的——使用前必须做边界约束。具体检查点：

• 来自张量维度的大小/数量：分配前校验。ne[i]*nb[i]这类乘积在构造的维度下可能溢出，导致分配过小继而堆溢出。溢出检查必须先于它所守护的算术运算执行——padding/alignment 宏在接近SIZE_MAX时会环绕到 0，因此 padding 之后再检查是无效的。
• GGUF 字符串/数组：使用声明的长度与元素数量来定循环或缓冲区大小之前，必须先封顶；在对数组转指针或读取固定下标（[i+1]、[0..2]）之前，先校验元素类型与长度。
• 元素类型混淆：把gguf_get_arr_data()或tensor->data强转成float */int32_t *之前必须做元素类型检查（先gguf_get_kv_type() == GGUF_TYPE_ARRAY再gguf_get_arr_type()；张量则type == GGML_TYPE_F32）。UINT8数组或I8张量能通过所有长度检查，然后被按每元素 4 字节读取——"附近有个长度检查"不等于类型检查。
• 加载器：对文件派生值做GGML_ASSERT会直接终止进程；在调用方已有异常捕获的路径上（vocab、模型加载器、clip）应改为抛异常。
• 文件提供的数量索引固定数组：索引任何计数（如指向LLAMA_MAX_*数组的层/块数量）之前必须先限界；注意那些仅在某个可选 key 存在时才触发的检查。
• 声明长度 vs 实际数组长度：GGUF 数组的声明长度要与实际读取的个数比对，而不是只与缓冲区大小比对。
• 边界比较：标记可能绕过长度检查、导致越界拷贝的窄化强转（size_t->int32_t）与有符号/无符号混用。
• 解析/派生索引：对stoi/atoi结果做范围检查并捕获解析异常；在没有边界检查的情况下，绝不能用默认或派生的 token id（EOS/BOS 等）直接当索引。
• 复用/预留缓冲区：缓冲区缩小或复用之后重新检查边界；注意reserve()后按"假定大小"索引、以及在长度检查之前读取头字段。
• Server JSON 整数：客户端提供的整数（token/discard 计数、偏移量）在到达索引/指针算术前，必须被钳位到非负与上界。
• RPC 反序列化字段：把每个字段（type/buffer/data/ne/nb/op_params）都当作敌意的——使用前校验。空/零缓冲区跳过校验、攻击者数据指针、越界类型索引、负 stride 符号扩展越过"仅在角落检查"的断言，都可以造成任意读/写。
• 生命周期/UAF：标记指向调用方/临时存储的裸指针、指向之后会被 free 的缓冲区的缓存指针、源可能在完成前被释放的异步操作、free/realloc 时未失效的结构体。解引用前检查条件构建的或"非必需"的张量。

5. 方法与设计评审（引入新组件/基础设施时）

每当 diff 新增组件、子系统或基础设施时就运行此清单。技能指出：评审往往止步于"能不能跑"——一个 diff 可以是正确的，但仍然是错误的方法；一个糟糕的设计长期代价高于一个 bug。要评估的是方法本身而不是行为，提出更干净的方案是高价值发现而非吹毛求疵；看到更好的设计时，要具体描述它，而不是只说现在的不好：

• 上游有更简单的方法：最大的收益往往是换一种数据模型/设计，整块地消掉子系统，而不是微调现有代码。复杂度必须由问题本身证明必要，而不是"因为第一个方案能跑"。
• 复用优先于重造：新增前先 grep 现有 helper、库、对象或机制。重实现代码库已有的东西，会重新引入已解决的 bug 并增加维护面。
• 清晰的归属/生命周期：优先 RAII 与显式归属，而不是手动存活标志、手工追踪的指针和"它还活着吗"检查——手动生命周期管理是反复出现的微妙 bug 来源。
• 匹配规模的机制：标记冗余、过度设计、超出需要的原语与抽象；只用设计真正需要的最小机制。
• 正确的结构与契合度：新类型要"挣得"自己的位置（承担两种角色就拆开）；遵循既有模式、惯用法与命名，避免项目排斥的写法。
• 根因 vs 症状：在修复上层层打补丁，说明需要修正的是设计，而不是继续加防护。

6. 新模型 / 架构清单（评审时子集）

完整的模型添加流程见 docs/development/HOWTO-add-model.md 与 add-new-model 技能；以下是评审中最常被抓住的子集：

• 不要在真实依赖是某个配置/能力值时去分支model.arch——应该以 hparam/能力为准入门，而不是架构枚举。
• 如果模型是既有架构的近似变体，增量是否站得住脚？优先复用/继承既有 arch/模型类而不是复制。近似重复的类或src/models/<name>.cpp会被要求与姊妹类合并。
• 新张量名称必须走 gguf-py/gguf/tensor_mapping.py，而不是临时的名称匹配。
• QKV 场景：用ggml_view切分的是激活，而不是权重张量；依赖 ggml 广播，而不是手工复制张量。
• 新 graph 输入声明在图构建函数顶部，而不是内联在首次使用处。
• 模型没有它就无法正确运行的 hparam 必须是强制项（缺失即硬错误），而不是静默默认值回退；只有真正"跨配置可选"的值才用回退访问器。
• 新增/可选的权重张量（scale 等）必须走build_lora_mm与既有 helper，符合约定（参见 src/llama-graph.cpp），不要留下从别的架构抄来的裸 matmul。
• 不要用自定义 sin/cos 实现去 hack RoPE。如果ggml_rope_ext确实表达不了，那是需要讨论的 issue，而不是 PR。
• 要测量化 KV 路径（-ctk/-ctv q8_0），而不只是默认 f16——新的 speculative/attention 特性在那里会静默损坏。
• 从别处复制代码时保留模型特性相关的解释性注释；注明出处（"copied from X, with Y added"）。
• 删除从参考实现移植残留的死代码/分支。

7. ggml / backend 清单

• supports_op（以及任何分派/门控条件）必须精确限定到被改动的 case——为少数量化类型设计的条件不能顺手启用/禁用其他所有情况。supports_op是 backend 注册的分派入口，定义见 ggml/src/ggml-backend-impl.h。
• 不要硬编码 warp/lane 尺寸——使用ggml_cuda_get_physical_warp_size()（CUDA 上为 32，HIP/ROCm 上为 64）与可移植 helper。该函数定义在 ggml/src/ggml-cuda/common.cuh#L374，在fwht.cu、fattn-mma-f16.cuh、cumsum.cu等大量 kernel 中被统一调用，正是这条规则的落地形态。
• 评审前剥离残留的 debug/profiling/logging 代码。
• 新增或修改 op？更新 docs/ops.md 与所触碰 backend 对应的docs/ops/*.csv（仓库中已有CPU.csv、CUDA.csv、Metal.csv、Vulkan.csv、WebGPU.csv、SYCL.csv、OpenCL.csv、BLAS.csv等文件，与docs/ops/目录一一对应）。
• 新 op 或算子变更需要对应的test-backend-ops用例（见 tests/test-backend-ops.cpp），并且按 CONTRIBUTING.md 要求至少两个 backend 上的一致性验证。
• 新 kernel 预期附带具体性能数据（现实张量形状下的吞吐），而不只是正确性。
• 不要让 backend 为了省事去变更 cgraph——那是未决的架构问题，不是可以夹带的东西。
• 预期ggml/的变更需要两位维护者批准；这属于正常现象，不代表有问题。
• CUDA 专项：避免过度模板化 kernel，只有看得见性能收益时才加模板。

8. 公共 API（include/llama.h）清单

公共 API 变更的门槛高于内部变更（见 CONTRIBUTING.md "New CLI or public API additions carry a higher bar"）。评审要点：

• 正当性：为什么既有机制不够用（例如cb_eval回调，见 include/llama.h#L386-L387 中的ggml_backend_sched_eval_callback cb_eval字段，或既有的 batch/sampler 参数）？如果既有机制够用，这个变更就不该新增公共面。这是这类 PR 被拒的最常见单一原因。
• 实验性或权宜性的接口应放在侧边头文件 src/llama-ext.h，而不是llama.h。
• 保持最小且通用：一个通用调用胜过若干狭窄的便捷封装；新调用要面向未来兼容（例如混合模态 batch），不要假设今天的形状。
• C API 是一等、稳定、定义 ABI 的公共面——不要提议用并行的 C++ API 替代它；include/llama-cpp.h 保持薄便利层。
• 类型与命名：定长整型（尺寸/偏移用int32_t、size_t）；snake_case；<class>_<method>=<class>_<action>_<noun>；枚举值大写且以枚举名作前缀；不透明类型用_t后缀。避免对已导出函数无谓的签名/ABI 变更。
• 每个新 API 需要在同一个 PR里附带一个真正调用它的可用示例/工具——维护者要求把它接进server、embedding、perplexity等工具（分别位于tools/server/、examples/embedding/、tools/perplexity/），以此找出真实 bug。

9. Server（tools/server/）清单

• 功能是否在 server 的定义范围之内？检查 tools/server/README-dev.md——超出范围的功能会被拒绝。
• 安全：不要信任客户端提供的头（例如X-Forwarded-For），也不要引入"陷阱"设计；IP 白名单这类东西应放在反向代理上，除非有可信代理的明确设计。
• 新行为要正确接入既有的请求/响应与 checkpoint 路径；留意跨请求的资源泄漏。

10. 多模态（tools/mtmd/）清单

• 张量名必须以v.、a.、mm.或a.mm.为前缀（旧命名不遵循此约定是可以接受的，但新代码应遵循）。
• RoPE 不要用显式 sin/cos，使用ggml_rope_ext，参见 docs/development/HOWTO-add-model.md；若它表达不了所需行为，那是设计讨论而非 PR。
• 新 GGML op 不允许在同一个 PR 中引入，必须单独提 PR。
• 多数情况下build_vit就足以构建视觉模型的 transformer 图（实现见 tools/mtmd/clip.cpp 与 tools/mtmd/clip-graph.h）。除非有非常充分的理由，不要手工加循环构建 transformer 图；如果确实要加，请在 PR 描述中说明原因。
• 如果需要专用 preprocessor，大概率可以从既有 preprocessor 派生子类——添加新 preprocessor 类之前先仔细检查。
• 如果模型需要 tools/mtmd/ 中mtmd.h的新公共 API，先开 discussion。
• 音频生成模型见 tools/mtmd/README-dev.md。

11. General 清单（始终执行）

对每一行变更都执行 AGENTS.md / CONTRIBUTING.md 的编码与命名规范——这是独立于"代码能不能跑"的一次专门检查，同样决定评审速度：

• 代码与注释中只用 ASCII：不用 emdash、unicode 箭头、×、…；用-、->、x、...的 ASCII 等价物（AGENTS.md "Code and Commit Standards" 一节同样强调）。
• 注释简洁，解释不显然的why而不是what。标记：冗长注释、复述代码的注释、引用当前任务/PR 的注释、被硬折行到固定列宽的注释。AGENTS.md 给出的对照示例很典型：n_ctx = read_metadata("context_length", 1024);本身就是最好的"注释"，而// reset here, as we will release the slot below这类解释不变量的短注释才是合格写法（见 AGENTS.md#L116-L189）。
• 不要把散文/注释强行折行到固定字符数，或把一句话拆成多行。
• 命名：snake_case；C/C++ 文件名（含.h头）用kebab-case（小写加连字符）；Python 文件用小写下划线。命名按最长公共前缀优化（number_small而非small_number）。CONTRIBUTING.md "Naming guidelines"（CONTRIBUTING.md#L114-L169）给出了完整示例：枚举值如LLAMA_VOCAB_TYPE_SPM、<class>_<method>模式如llama_model_init()、llama_sampler_get_seed()，以及不透明类型的_t后缀。
• 4 空格缩进、大括号同行、void * ptr、int & a、行尾无空白；与周围风格保持一致（CONTRIBUTING.md "Coding guidelines" 还有补充：公共 API 用定长整型、struct foo {}声明风格、C++ 中省略不必要的struct/enum关键字；注意本项目张量按行主序存储，且ggml_mul_mat的语义是非传统的 $C^T = A B^T$，读 backend 代码时不要按常规矩阵乘法直觉理解）。
• 复用既有基础设施，而不是引入新组件；除非有充分理由，不加新的第三方依赖、额外头文件或文件。
• 保持简单：做到 90% 的简单变更通常优于做到 100% 的复杂变更；标记不必要的模板/花式 STL——普通for循环在这里完全没问题。
• 每一行新增代码都应是贡献者能在没有 AI 帮助下向 reviewer 解释并为之辩护的——标记任何"抄来但不理解"的内容（对应 AGENTS.md 开篇声明："AI-generated code is allowed. What is not allowed is submitting code you do not understand."）。
• Co-authored-by:必须保留给人类共同作者；AI 贡献（claude、cursor、codex 等）必须使用Assisted-by:（AGENTS.md 的提交示例给出Assisted-by: Claude Sonnet的规范写法，并明确禁止git push、gh pr create、gh pr comment等代理操作，见 AGENTS.md#L213-L227）。违反这一点属于阻断级发现。
• 任何提及 Minja 的地方都必须视为阻断级——llama.cpp 并不使用名为 Minja 的库，它有一个自研的 Jinja 引擎位于 common/jinja/（无专门名字）；这一澄清同样写在 AGENTS.md 的"AI agents 常见错误"一节。

12. 报告格式：按严重度分组的发现

评审结果按严重度分组，让用户一眼看出什么真正阻断合入：

1. 阻断（Blocking）——快速否决/范围问题与正确性 bug；这些可以在其他一切做得再好时也沉掉这个 PR。
2. 会拖慢评审（Will slow the review）——约定/命名/注释违规，缺测试/文档/性能数据，缺 API 正当性或示例。
3. 小问题（Nits）——次要风格问题、可选清理。

每条发现都要指向具体文件与行号，并具体说明改什么、为什么。不要未经请求就重写整个 diff——让贡献者自己修改，这样修复归他所有、他也真正理解。同样，不要代拟任何 PR 文案、提交信息或 reviewer 回复——那是贡献者自己的事。

13. 把技能串进工作流：一次完整的自评审路径

结合 add-new-model 技能 的收尾要求，推荐的落地顺序是：

1. 在本地完成功能开发后，运行git diff --stat划定范围（本技能 Step 0），确定要跑哪些清单；
2. 依次执行"范围与快速否决门禁"→"安全审查"→各区域清单→"General"清单；
3. 若引入了新组件，加跑"方法与设计"评审；
4. 对发现的每一项，按三档严重度整理成私有笔记；
5. 全部阻断项清零、拖慢项处理完毕后，由贡献者本人撰写 PR 描述（填写 .github/pull_request_template.md 的 AI 披露部分）并提交；
6. 若 diff 属于新模型，还应在推 PR 前完成 HOWTO 文档中的验证清单（GGUF 转换、logits 验证、量化后复验、困惑度、CPU 优先）。

这套流程的价值在于：它把维护者"合入后无限期维护每一行代码"的成本意识（AGENTS.md 的核心论点）前移到推送之前，用可执行的清单替代了事后返工。

【免费下载链接】llama.cppLLM inference in C/C++项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp