尧图网站建设 
llama.cpp 代码评审技能PR 前自检清单与高频审查陷阱全解skills/code-review【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cppllama.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-L99Agent 在任何情况下都不得代写 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 --statPR 模式下可用gh pr view n --json files然后把触碰到的路径分桶触碰路径适用清单conversion/、gguf-py/、src/models/、src/llama-arch.*新模型 / 架构ggml/任意 backend、op 或ggml.hggml / backendinclude/llama.h与其他公共头文件公共 APItools/server/Server其余所有路径并且以上所有General始终运行规则是范围与快速否决门禁、安全审查、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 字符串/数组使用声明的长度与元素数量来定循环或缓冲区大小之前必须先封顶在对数组转指针或读取固定下标[i1]、[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 idEOS/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 上为 32HIP/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. 公共 APIinclude/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_tsnake_caseclass_methodclass_action_noun枚举值大写且以枚举名作前缀不透明类型用_t后缀。避免对已导出函数无谓的签名/ABI 变更。每个新 API 需要在同一个 PR里附带一个真正调用它的可用示例/工具——维护者要求把它接进server、embedding、perplexity等工具分别位于tools/server/、examples/embedding/、tools/perplexity/以此找出真实 bug。9. Servertools/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_caseC/C 文件名含.h头用kebab-case小写加连字符Python 文件用小写下划线。命名按最长公共前缀优化number_small而非small_number。CONTRIBUTING.md Naming guidelinesCONTRIBUTING.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. 报告格式按严重度分组的发现评审结果按严重度分组让用户一眼看出什么真正阻断合入阻断Blocking——快速否决/范围问题与正确性 bug这些可以在其他一切做得再好时也沉掉这个 PR。会拖慢评审Will slow the review——约定/命名/注释违规缺测试/文档/性能数据缺 API 正当性或示例。小问题Nits——次要风格问题、可选清理。每条发现都要指向具体文件与行号并具体说明改什么、为什么。不要未经请求就重写整个 diff——让贡献者自己修改这样修复归他所有、他也真正理解。同样不要代拟任何 PR 文案、提交信息或 reviewer 回复——那是贡献者自己的事。13. 把技能串进工作流一次完整的自评审路径结合 add-new-model 技能 的收尾要求推荐的落地顺序是在本地完成功能开发后运行git diff --stat划定范围本技能 Step 0确定要跑哪些清单依次执行范围与快速否决门禁→安全审查→各区域清单→General清单若引入了新组件加跑方法与设计评审对发现的每一项按三档严重度整理成私有笔记全部阻断项清零、拖慢项处理完毕后由贡献者本人撰写 PR 描述填写 .github/pull_request_template.md 的 AI 披露部分并提交若 diff 属于新模型还应在推 PR 前完成 HOWTO 文档中的验证清单GGUF 转换、logits 验证、量化后复验、困惑度、CPU 优先。这套流程的价值在于它把维护者合入后无限期维护每一行代码的成本意识AGENTS.md 的核心论点前移到推送之前用可执行的清单替代了事后返工。【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 llama.cpp 代码评审技能：PR 前自检清单与高频审查陷阱全解（skills/code-review）
llama.cpp 代码评审技能PR 前自检清单与高频审查陷阱全解skills/code-review【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cppllama.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-L99Agent 在任何情况下都不得代写 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 --statPR 模式下可用gh pr view n --json files然后把触碰到的路径分桶触碰路径适用清单conversion/、gguf-py/、src/models/、src/llama-arch.*新模型 / 架构ggml/任意 backend、op 或ggml.hggml / backendinclude/llama.h与其他公共头文件公共 APItools/server/Server其余所有路径并且以上所有General始终运行规则是范围与快速否决门禁、安全审查、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 字符串/数组使用声明的长度与元素数量来定循环或缓冲区大小之前必须先封顶在对数组转指针或读取固定下标[i1]、[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 idEOS/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 上为 32HIP/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. 公共 APIinclude/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_tsnake_caseclass_methodclass_action_noun枚举值大写且以枚举名作前缀不透明类型用_t后缀。避免对已导出函数无谓的签名/ABI 变更。每个新 API 需要在同一个 PR里附带一个真正调用它的可用示例/工具——维护者要求把它接进server、embedding、perplexity等工具分别位于tools/server/、examples/embedding/、tools/perplexity/以此找出真实 bug。9. Servertools/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_caseC/C 文件名含.h头用kebab-case小写加连字符Python 文件用小写下划线。命名按最长公共前缀优化number_small而非small_number。CONTRIBUTING.md Naming guidelinesCONTRIBUTING.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. 报告格式按严重度分组的发现评审结果按严重度分组让用户一眼看出什么真正阻断合入阻断Blocking——快速否决/范围问题与正确性 bug这些可以在其他一切做得再好时也沉掉这个 PR。会拖慢评审Will slow the review——约定/命名/注释违规缺测试/文档/性能数据缺 API 正当性或示例。小问题Nits——次要风格问题、可选清理。每条发现都要指向具体文件与行号并具体说明改什么、为什么。不要未经请求就重写整个 diff——让贡献者自己修改这样修复归他所有、他也真正理解。同样不要代拟任何 PR 文案、提交信息或 reviewer 回复——那是贡献者自己的事。13. 把技能串进工作流一次完整的自评审路径结合 add-new-model 技能 的收尾要求推荐的落地顺序是在本地完成功能开发后运行git diff --stat划定范围本技能 Step 0确定要跑哪些清单依次执行范围与快速否决门禁→安全审查→各区域清单→General清单若引入了新组件加跑方法与设计评审对发现的每一项按三档严重度整理成私有笔记全部阻断项清零、拖慢项处理完毕后由贡献者本人撰写 PR 描述填写 .github/pull_request_template.md 的 AI 披露部分并提交若 diff 属于新模型还应在推 PR 前完成 HOWTO 文档中的验证清单GGUF 转换、logits 验证、量化后复验、困惑度、CPU 优先。这套流程的价值在于它把维护者合入后无限期维护每一行代码的成本意识AGENTS.md 的核心论点前移到推送之前用可执行的清单替代了事后返工。【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考