为AI编程助手构建算子知识库：让Agent先查后用，告别重复造轮子

1. 为什么需要一份算子知识库

1.1 算子开发的重复悲剧：Agent不是解药，而是放大器

写算子是件很磨人的事。以面向AI异构计算的CANN环境为例，一个看起来不起眼的算子要落到NPU上跑得快，背后是一整套策略：计算引擎怎么选、数据怎么搬运、tiling怎么切、核间怎么同步、buffer怎么对齐。任何一个环节拍脑袋，性能都可能掉一大截。这个领域里最大的浪费，往往不是单个算子研发周期长，而是同一个算子在团队里被反复“重新发明”。我做过的项目里就有这样的场景：一个逐元素运算的归一化算子，在三个不同模块里各有一份实现，接口叫法也不一样，性能差出两倍，但没一个人敢说哪份是标准版。

AI编程助手本来应该缓解这个问题，结果在一些团队里反而把它放大了。Agent的训练数据里塞满了全网各种算子的写法，你只要说一句“帮我写个LayerNorm的kernel”，它就能非常自然地生成一份“看起来没问题”的新代码。可它不知道你们仓库里已经有一版调过tiling、压过瓶颈、修过三个边界bug的实现。如果不是先让它查知识库，它一定会很勤快地帮你造出第四份轮子。这个现象的本质是信息断层：Agent有能力生成代码，但缺少对存量资产的感知能力。知识库就是用来补上这一层的。

1.2 面向Agent与面向人的知识库，是两回事

不少人听到“知识库”三个字，第一反应是搭一个wiki或者内部文档站，让新人去读。但我们做这个知识库的出发点不是给人看，而是给Agent查，这决定了它的形态完全不同。人喜欢叙事，喜欢图文并茂的文档，喜欢读到背景故事；Agent恰恰相反，它更适合结构化的、带约束条件的、能够被检索逻辑消费的数据。把同样的内容写成几百行readme，Agent只能大概理解个意思；切成一张算子卡片和一段可解析的JSON，它就能准确复用。

所以整个设计方向变得很明确：每条知识记录，必须回答“这个算子是什么、能不能用、有什么限制、在什么条件下优先使用”，而不是写“XX团队在XX项目中完成的一项出色工作”。我在做知识库内容模板时，最初也想放很多团队荣誉和过程叙事，后来全删了，只保留跟复用决策相关的要素。原因很简单：Agent不会因为有故事的文档就信任一个算子，它只会因为字段完整、约束清楚、测试数据可复现而做出正确判断。想让它真正用起来，知识库就得先从“给人讲故事”切换成“给Agent喂规则”。

2. 知识库里的算子卡片：沉淀哪些内容才算有价值

2.1 一张算子卡片的必备字段

我习惯把一张算子卡片分成六块：功能语义、接口签名、tiling与buffer策略、性能基线、已知问题、决策建议。这六个部分不是随手拍的，而是从Agent写代码时需要的上下文反推出来的。

功能语义用于消歧。比如两个都叫“归一化”的算子，一个对通道维度做，一个对空间维度做，语义不写清，Agent查到了也会用错。接口签名必须包括输入数据布局、精度、输出维度，以及是否支持原地操作。这些是Agent后续生成对接代码时的硬约束，少一个字段，它就可能编一个默认值出来。tiling与buffer策略是性能的核心，数据切多大、缓存怎么分、多核如何协同，都要留档。性能基线记录不同shape下的时延和吞吐，这样Agent才能判断“直接复用”还是“扩展新的tiling分支”。已知问题则是给后续生成避雷的，比如某个实现不支持非连续输入、某个实现不能在动态shape下使用，这些信息若不写，Agent大概率会在一百次生成里踩中同样的坑。最后一个决策建议是整个卡片里最关键的，它直接告诉Agent：什么条件下复用、什么条件下扩展、什么条件下重新写。

这些字段合在一起，就是一条完整的算子知识实体。我见过有些团队只存代码，不存约束和性能，结果Agent检索到一份过期的低性能实现，还当宝贝引用，导致上线后性能崩了。教训就是：只存代码的库根本不叫知识库，顶多叫代码备份。

2.2 模板、反模式与决策树：让Agent少走弯路

除了存成功实现，知识库还应该沉淀两类经常被忽视的内容：模板和反模式。

模板解决的是“骨架生锈”的问题。算子开发里很多步骤是固定的，比如核函数入口、tiling计算、数据搬运、主计算、后处理与同步。把一套经过验证的模板放进去，Agent不用从头编排流程，只要往里填策略和参数即可。模板的价值不只是省token，更是让生成结果在结构上稳定，便于后续人工审查和性能分析。

反模式解决的是“重复踩坑”的问题。很多写法看起来能跑，但性能惨不忍睹：比如在循环里逐张量搬运而不是用批量DMA，频繁同步导致流水线空转，或者在热点路径上做无谓的格式转换。每条反模式在知识库里可以存成三元组：错误模式、严重后果、修正方向。Agent在生成新代码前先看一眼自己是不是触发了这些模式，相当于提前打了一针免疫。

决策树负责解决“我到底该不该新写一个算子”。Agent普遍缺乏成本意识，上来就想按通用框架写。我在知识库里特意加了一套规则：如果已有算子覆盖了当前需求80%以上的性能基线，优先扩展；如果新shape和已知实现相差不到一个数量级，考虑增加tiling分支；如果语义完全一致且无附加约束，直接复用。这些规则让Agent在生成前先走一遍判断逻辑，而不是闷头开工。事实也证明，加了这个字段后，团队的无效产出明显变少。

3. Agent如何“先查后用”，而不是把知识库当摆设

3.1 构建一个Agent能主动调用的检索入口

想让Agent真正遵守“先查后用”，不能只把知识库挂到内网wiki上，然后对它说“你有空去看看”。它大概率不会看。更稳的做法是把知识库封装成检索工具，注册为Agent可用的一项能力，并在生成算子前强制调用一次“算子复用检查”接口。这个接口接收自然语言描述或结构化参数，返回命中的算子卡片、复用建议和模板片段，格式最好是统一的JSON。

我实际试下来，这样设计非常有效。AI编程助手的执行链是围绕工具调用展开的，你在系统提示词或工具列表里写明“生成算子前必须调用lookupOperator，若返回高置信度的已存实现，则在该实现基础上修改或直接复用”，Agent的行为就会被约束住。千万别把这个要求放在温和的注释里——放在注释里它会忽略，放在工具调用链里它就必须执行。就像是给固执的实习生一份必须填写的审批表，他再怎么有自己的想法，流程上也得先过这一关。

这里有一个关键细节：返回结果里除了算子卡片原信息，还要包含recommendation字段，建议取值为reuse、extend、rewrite。Agent拿到结果后可以形成清晰分支逻辑：confidence高且recommendation为reuse，就直接输出引用；为extend，就调取模板和原实现做增量修改；为rewrite，才允许从零开始。少了这个字段，Agent即使查到现有算子，也不知道应该怎么处理，最后大概率还是按自己的理解重新写一遍。

3.2 从单向检索到Agent反向回写

很多团队做知识库时只考虑Agent从里面“取”信息，忽略了Agent也应该往里“存”信息。但Agent每天会生成大量新算子实现，其中一部分通过了测试、跑赢了基线、覆盖了新的shape范围，这些高质量产出如果不回写，知识库就会慢慢老化，最终又不被信任。理想的流程是：Agent完成一个算子并通过验证后，自动起草一张候选算子卡片，提交人工审核；审核通过后入库，并更新对应的性能基线。这样知识库不是建完就结束的静态资产，而是跟着项目演进持续生长的活系统。

回写时有两个坑必须避开。第一，不要无门槛发布。Agent的幻觉问题在代码生成里仍然存在，明明只覆盖了部分shape的实现，可能被它描述成“通用实现”。如果无人审核，这类错误信息会在库内扩散，误导后续所有复用行为。第二，回写时一定要保留来源和实验环境。芯片型号、CANN版本、shape范围、精度设置、测试时间，这些字段缺了，那张卡片等到版本升级后就毫无可信度。我们在实践中强制要求人工确认“适用条件”一栏没有夸大，才允许入库。审核是有成本，但相比知识库变成垃圾场的代价，这个成本完全值得。

4. 动手搭一个算子知识库：完整实操过程

4.1 第一步：盘点存量代码，别迷信“应该有”

搭知识库的第一步不是设计数据库，而是先把仓库里已经存在的算子“挖”出来。我在团队里做过好几次盘点，问有没有现成的归一化算子，所有人说“应该没有”，结果一搜代码，翻出三四个实现，只是名字分别叫normalize_layer、norm_kernel、row_l2_norm，互相之间毫无关联。这种情况很常见，所以必须要用脚本先做候选识别，再人工确认。

一段非常粗的盘点脚本逻辑可以长这样：

import os, re from pathlib import Path # 示例：扫描目录下所有 C++ 文件中的候选函数入口 root = Path("./src") pattern_kernel = re.compile( r"(?:void|int|float|__global__)\s+([A-Za-z_][A-Za-z0-9_]*)\s*\(" ) candidates = [] for path in root.rglob("*"): if path.suffix not in {".cpp", ".cc", ".h", ".cuh"}: continue text = path.read_text(errors="ignore") for m in pattern_kernel.finditer(text): candidates.append((path, m.group(1)))

但脚本只是第一步，候选名绝不能直接入库。我在盘点中踩过最深的坑是：有些历史遗留代码看着像算子入口，实际是旧框架的辅助函数，真正的主算子入口是通过注册表注册的。如果盘点阶段搞错对象，后续的卡片全都建在错误目标上。所以每次盘点都配有人工确认环节，由熟悉业务的人判断这个函数到底是不是一个算子、是否还有别入口、是否处于废弃状态。宁可慢一点，也不要让知识库从第一个词条开始就跑偏。

4.2 第二步：设计算子卡片的Schema，加版本号

盘点完成之后，就要定义统一的记录格式。我用JSON Schema做结构化，一个算子卡片的常用字段如下：

字段不要贪多。很多团队一开始恨不得把几十个属性塞进卡片，结果填写成本太高，没人愿意维护，最后沦为摆设。我的原则是“宁可少而精，能被Agent稳定消费的字段才有意义”。以decision字段为例，如果它没写清楚，Agent检索到一堆性能数据依然无法判断该复用还是该重写，所以这个字段要尽量写成可执行规则，而不是一段模糊描述。

Schema本身也要版本化。老记录在没有constraints字段的情况下，不能直接套用新schema去解析。我会给每个枚举字段设默认值，并在后端做一次数据校验，保证Agent读到任何一张卡片都能按明确规则处理。升级时还会跑一遍老数据的迁移脚本，而不是将来四处打兼容补丁。这个细节看起来小，但在后面Agent决策质量上影响很大。

4.3 第三步：检索API与Agent插件

知识库不能只是一个静态文件目录，它需要被Agent稳定调用。我通常会做一个轻量服务，最少提供两个接口：POST /search负责语义检索，POST /lookup负责精确匹配。前者接收自然语言描述，后者接收算子ID。检索能力早期我用全文索引，结果发现“同名不同义”的情况很多，后来补上Embedding向量召回和别名表，口语化表述也能召回正确算子，效果才算可用。

一个最简单的检索请求长这样：

POST /search { "query": "对输入feature map做通道维度的L2归一化，输出与输入同shape", "top_k": 5, "filters": {"status": "active"} }

返回结果里会带匹配得分和每张卡片的摘要。Agent拿到结果后，可以顺着recommendation字段决定下一步动作。接AI编程助手时，我偏向用工具注册方式，而不是把整个知识库文件塞进上下文。因为全文塞进去既烧token又不聚焦，工具调用则让Agent带着问题来查，检索结果更准确。我给AI助手的函数列表增加了一个cann_kb_lookup，并在description里明确写了一句“必须在生成算子之前判断是否已有实现时调用”。这等于给Agent立了一条可执行的规矩，而不是一句口头建议。

4.4 知识库的更新与审核机制

知识库的更新不能靠一时热情。实际操作里，我设定了两个更新周期：每周一次主动审查，处理存量卡片的过期问题；每次新算子通过验证后的即时回写，沉淀增量成果。主动审查要关注算子在新版本CANN环境下性能是否退化，如果退化就要及时打上deprecated标记，避免Agent继续复用旧路线。即时回写则要跑完刚才说的审核流程，防止低质量信息混入。

如果团队没人长期盯维护，知识库三个月后就会变成一座过时信息的垃圾山。上线时轰轰烈烈，最后被Agent和开发同事一起抛弃，这种情况我见得太多了。所以我的建议是：一个人或一个小工作组持续运营，比上线时投入十个开发写内容更重要。知识库是活体，不喂养就会死。

5. 上线之后：效果怎么衡量，问题怎么排查

5.1 用四个指标衡量知识库的真实价值

知识库上线只是开始，不是终点。想判断它到底有没有发挥作用，我建议盯四个指标：

• 重复生成率：同语义算子在知识库已经覆盖的情况下，Agent仍然重新生成的占比。这个值要努力降下来。
• 算子复用率：Agent在最终生成流程中实际引用了已有算子卡片或模板的比例。复用率上去，说明“先查后用”真正落地了。
• 首次通过率：Agent生成的新算子第一次跑通且性能达到基线的比例。反模式和模板的沉淀会明显抬高这个数字。
• 评审驳回率：人工评审Agent提交代码时的驳回比例。理想情况下这个值应当下降，但如果知识库本身引入了错误信息，驳回率也可能反弹，这时要回过头检查内容质量。

这四个指标是一条逻辑链：重复生成率低，说明Agent不造轮子；复用率高，说明它确实把检索结果用了起来；首次通过率提升，证明复用和扩展整体是靠谱的；评审驳回率则用来监控有没有被错误信息带偏。团队每周拉一次数据，按算子和shape拆开看，很快就能定位到底是哪个环节失效。

5.2 排查实录：我遇到过的诡问题

知识库上线后前几个月，我遇到过几个典型问题，分享出来免得大家再踩。

第一个问题是Agent检索到过期算子。某个算子在新版本软硬件环境下性能大幅劣化，但知识库里那条旧卡片的性能基线还是老版本的漂亮数据。Agent检索后把它当成最优实现输出了，结果性能测试不通过。排查下来，根因是知识库检索时没有把“适用版本”当作硬性过滤条件。我们后来在检索API里强制传入当前编译环境版本，过滤掉不兼容和废弃状态的卡片，这个坑才算填住。

第二个问题是检索召回率低。团队里有人习惯用“LN”称呼LayerNorm，有人写全称“layer_norm”，但知识库里只存了全称和少量别名，Agent查“LN”查不到，于是又开始从头生成。后来我们给每个算子卡片维护了一份带同义别名的标签表，加上Embedding向量召回，把字面匹配之外的语义相近内容也找出来。两招一起上，召回率才明显好转。

第三个问题是Agent回写污染。回写功能上线后，有的Agent把单元测试一次通过直接描述成“已验证”，忽略了动态shape和边界case没有测过。这个错误信息一旦入库，会影响后续所有复用的Agent，直到线上出问题才发现。好在我们一直保留人工审核环节，把这类记录退回补充验证范围。现在团队里达成了共识：Agent可以起草卡片，但任何入库都要人工确认“验证到什么程度”。

第四个问题出现在schema升级时。我们新增了一个alignment字段，但老记录没有这个字段，Agent读取时取了一个不合适的默认值，导致某些shape组合下性能退化。后来我们规定所有枚举字段必须显式设默认值，并且升级时跑老数据迁移，避免“缺字段就当不存在”的隐晦行为。这类问题不大，但会影响所有下游决策，值得警惕。

这些坑与其说是技术问题，不如说是信息治理问题。知识库的每条记录都承担着“教Agent做决定”的职责，字段不严谨，最后一定会反馈到性能或质量上。

5.3 知识库与Agent之间的信任边界

知识库解决了信息不对称，但没解决信任问题。Agent给出“复用已有实现”的建议时，我们仍会保留人工复核，尤其对性能敏感或正在上线的算子。一个可行的做法是：知识库只负责提供候选和规则建议，最终选择交给人工或自动优化器。Agent可以承担80%的初筛工作，最后把关还是得靠可信的测试和评审流程。这不是保守，而是现阶段人机协作里必要的安全垫。等到Agent对知识库的语义理解足够稳定，这个比例可以再往自动化方向推，但信任边界的建立必须靠一次次成功案例累积，而不是靠口号。

6. 从知识库运营里得到的个人体会

6.1 知识库改变的不只是代码量，还有团队讨论方式

这个知识库上线之后，我的感受并不只是“重复代码变少了”这一件事。真正让我觉得值回票价的，是团队讨论算子的方式变了。以前同事之间沟通是“我写了个卷积融合”“我这有一个类似的你看看还能不能快一点”；现在大家会直接打开知识库，对着算子卡片上的tiling策略和已知问题清单讨论“这张卡片还缺什么”“哪种shape还没覆盖”。Agent也从“一个写代码的机器”变成了“一个有团队记忆的协作者”。这个变化，比技术指标上的提升更让我高兴。

知识库让团队对“已有资产”形成了一种共同的敏感度。新人入职不再靠口口相传去了解哪些算子存在，而是先翻一遍卡片目录，带着全局视角进入开发。老同事也不會再因为担心“自己的实现不被承认”而各自为战，因为知识库的决策规则是透明的，谁写得更快谁就可以被复用，这反而促进了良性竞争。

如果你也想做类似的事，我建议从小范围起步，先选三五个你最在意的核心算子做成卡片，把Agent的检索和回写流程跑通，再逐步扩展。别一上来就追求千人千面的大规模知识库，规模越大，维护成本越高，就越容易被放弃。一个只有二十张卡片但每张都准确可用的知识库，胜过堆了一千条垃圾记录的庞然大物。

6.2 给Agent立一条硬规矩，比任何提示词都管用

最后分享一个特别实用的小技巧。在Agent的系统提示词最前面写一行：“在写任何算子之前，先查知识库；没有命中，才能新写。”就这一句话，我们团队一个月的重复生成率下降了四成。原因是Agent在执行长任务时很容易被中间步骤带偏，如果你不在最前面立规矩，它大概率会先凭自己的语料直接生成一份代码，等到最后才想起来检查，那时已经晚了。让“先查后用”成为流程里的硬约束，知识库才能真正发挥作用。固执的Agent需要一条硬规矩，而不是一句温和的建议。