1. 从标题拆解：Kernel 与 Shader 的 Agent Harness 到底在解决什么问题
第一次看到 "Kernel & Shader agent harness" 这个组合，很多人会愣一下：Kernel 是操作系统或计算框架里的底层执行单元，Shader 是 GPU 上跑图形或通用计算的程序，Agent 是能自主决策的执行体，Harness 是"挽具、约束框架"。把这四个词拼在一起，它描述的其实是一件事——给"能自己写 Kernel 和 Shader 的智能体"套上一副可控、可测、可复现的挽具。
我接触这个方向是从 LuisaCompute 和 eDSL 这两个关键词开始的。LuisaCompute 是一套跨后端的并行计算框架，它用一套统一的 DSL 描述计算，然后编译到不同的后端（CUDA、Metal、DX 等）。eDSL 就是"embedded DSL"，把领域特定语言嵌进宿主语言里。当你让一个 Agent 去生成 Kernel 或 Shader 代码时，最大的痛点不是"它写不出来"，而是"它写出来的东西没法验证、没法约束、没法批量回归"。Harness 就是来解决这个的。
所以这篇东西适合谁看？三类人：一是做 GPU 计算、图形渲染，想把手写 Kernel/Shader 的重复劳动交给 Agent 的工程师；二是做 AI 代码生成、想让模型产出可执行并行代码的研究者；三是做编译器、DSL、运行时，想搭一套自动化测试与约束框架的人。哪怕你只是被"卡到 installing kernel"或者"kernel header files not in any"这类报错折磨过，理解 harness 的思路也能帮你把问题定位得更快。
核心价值一句话：Harness 把"Agent 生成 Kernel/Shader"从一次性的、靠运气的尝试，变成可约束、可度量、可迭代的工程流程。下面我按自己实际搭这套东西的顺序，把设计思路、关键细节、实操过程和踩坑记录完整拆开讲。
2. 整体设计与思路拆解：为什么是 Harness 而不是普通脚本
2.1 Harness 和 Agent 的区别，先把这个说清楚
热词里有个"harness和agent区别"，这问题问得特别到位，因为很多人把两者混为一谈。我的理解是：
- Agent 是"决策者"：它接收任务描述，决定生成什么 Kernel、用什么并行策略、怎么切分线程块。它是有"意图"的。
- Harness 是"约束与度量层"：它不关心 Agent 想干什么，它只负责给 Agent 提供受控的执行环境、把生成结果编译运行、收集正确性和性能数据、把失败原因结构化地反馈回去。
打个比方，Agent 是赛车手，Harness 是赛道加计时系统加安全护栏。赛车手可以很激进，但护栏保证他不会冲出赛道，计时系统保证每圈成绩可比较。没有 Harness 的 Agent 生成代码，就像在没有护栏的山路上飙车——偶尔能跑出好成绩，但你不敢让它连续跑一百次。
这个区分直接决定了架构：Agent 侧要尽量"薄"，Harness 侧要尽量"厚"。Agent 只输出结构化的代码和元数据，所有编译、执行、校验、统计的脏活都压在 Harness 里。这样换一个 Agent（换个模型、换个 prompt 策略）时，Harness 完全不用动。
2.2 为什么选 LuisaCompute + eDSL 这条路线
选型这块我纠结过很久。直接让 Agent 生成 CUDA C++ 行不行？行，但有几个硬伤：
第一，后端绑定太死。生成 CUDA 就只能跑在特定硬件上，换台机器就废了。LuisaCompute 的好处是它有一套统一 DSL，同一段计算描述能编译到多个后端，Harness 的测试矩阵一下子就能铺开。
第二，eDSL 天然适合做约束。因为计算是用宿主语言（比如 C++）里的 API 拼出来的，Agent 生成的其实是"调用序列"而不是"一整块自由文本"。调用序列可以被静态检查——参数类型对不对、维度匹配不匹配、有没有越界，这些在编译期就能拦下来。而自由文本的 CUDA 代码，你只能靠编译器和运行时报错，反馈链路长得多。
第三，可复现性。eDSL 生成的中间表示（IR）是确定的，同样的输入必然得到同样的 IR。这对 Harness 做回归测试太重要了——你可以把 IR 的哈希存下来，Agent 改一版就对比一次，任何非预期的变化都能立刻发现。
提示：如果你的场景强绑定某一家的硬件，直接用原生方案可能更省事。但只要你有"多后端"或"长期回归"的需求，eDSL 路线的收益会迅速超过前期投入。
2.3 Harness 的四个核心模块
我把 Harness 拆成四块，每块职责单一：
| 模块 | 职责 | 关键产出 |
|---|---|---|
| 约束层 Constraint | 静态检查生成代码的合法性 | 通过/拒绝 + 结构化原因 |
| 执行层 Runtime | 编译、加载、运行 Kernel/Shader | 运行结果 + 耗时 + 资源占用 |
| 校验层 Validator | 对比参考实现，判断正确性 | 误差指标 + 是否通过阈值 |
| 反馈层 Feedback | 把失败原因整理成 Agent 能懂的信号 | 结构化错误报告 |
这四块串起来就是一个闭环：Agent 生成 → 约束层拦一道 → 执行层跑起来 → 校验层判对错 → 反馈层把结果喂回 Agent。Agent 下一轮就能带着"上次哪里错了"的信息继续改。这个闭环是整套东西的灵魂，缺了反馈层，Agent 就只是在盲猜。
3. 核心细节解析与实操要点：约束层和执行层怎么落地
3.1 约束层：把"能编译"和"能跑对"分开
新手最容易犯的错，是把所有检查都堆到运行之后。结果就是 Agent 生成一段代码，编译报错，你拿到一个几百行的模板报错，根本不知道从哪改。约束层的意义就是在编译之前，先把明显不合法的东西挡掉。
具体检查什么？我列一下自己实际用的清单：
- 维度一致性：Kernel 的线程块大小、共享内存大小、输入张量形状，三者必须自洽。比如你声明了
block_size = 256，但共享内存按 128 个元素分配，这就是矛盾。 - 类型匹配：eDSL 里每个变量都有类型，Agent 经常把
float和half混用。静态检查能在编译前抓到。 - 资源上限：每个后端对寄存器数、共享内存、线程数都有硬上限。超了要么编译失败，要么性能暴跌。约束层应该提前算一遍。
- 访问边界：数组下标、纹理坐标，这些越界访问在 GPU 上往往是静默错误（不报错但结果错），必须静态或动态插桩检查。
这里有个实操心得：约束层不要追求"全知全能"，要追求"快速失败 + 清晰原因"。我一开始想把所有规则都塞进去，结果约束层自己变成了一个几百行的怪物，维护成本比 Agent 还高。后来改成"只拦高频错误 + 每条规则独立可关"，清爽多了。
3.2 执行层：编译缓存是性能关键
执行层看着简单——编译、跑、收数据。但真跑起来，编译时间会吃掉你大部分预算。一个中等复杂度的 Kernel，从 eDSL 到后端二进制，编译可能要几秒到几十秒。如果 Agent 每轮都重新编译，迭代速度直接崩。
我的做法是两级缓存：
第一级是IR 缓存。eDSL 生成的 IR 做哈希，命中就直接复用，跳过前端。这一级能省掉大部分解析和类型检查时间。
第二级是二进制缓存。编译产物按"IR 哈希 + 后端 + 编译选项"做键存起来。同一段 Kernel 换个后端要重编，但同后端重复跑就直接加载。
实测下来，两级缓存能把平均迭代时间从十几秒压到一两秒。这个提升对 Agent 的迭代效率是决定性的——Agent 一轮快，你就能在同样时间里让它多试几十次。
注意：缓存键一定要包含编译选项。我踩过一次坑，改了优化等级但缓存没失效，结果拿旧二进制跑了一整天，数据全是错的。后来把编译选项的哈希也拼进键里才解决。
3.3 校验层：参考实现从哪来
校验层要判断 Agent 生成的 Kernel 对不对，就得有个"标准答案"。标准答案有三个来源，各有取舍：
- 手写参考实现：最可靠，但工作量大，而且手写实现本身可能有 bug。
- CPU 版本：把同样的计算用 CPU 跑一遍，作为基准。好处是容易写、容易调试；坏处是慢，而且浮点误差和 GPU 不完全一致。
- 高精度版本：用双精度或更高精度算一遍，作为"真值"，然后看 GPU 单精度结果落在误差范围内没有。
我一般用 CPU 版本做功能校验，用高精度版本做数值校验。功能校验看"结果对不对"，数值校验看"误差可接受吗"。两个都过才算通过。
误差阈值怎么定？这取决于你的计算类型。累加类操作（比如归约求和）误差会随规模增长，得用相对误差加绝对误差的组合判据。我通常设相对误差 1e-4、绝对误差 1e-5，超过就标记为可疑，人工看一眼。
3.4 反馈层：让 Agent 看得懂错误
反馈层是最容易被忽视、但价值最高的一块。Agent 拿到一个原始报错，和拿到一份结构化诊断，改代码的效率差好几倍。
我的反馈格式大概长这样：
{ "stage": "constraint", "rule": "dimension_mismatch", "location": "shared_memory_alloc", "expected": 256, "actual": 128, "hint": "共享内存元素数应等于 block_size，当前声明为 128 但 block_size 为 256" }关键是那个hint字段——它把机器能理解的错误翻译成 Agent 能理解的建议。这个 hint 不用很智能，模板化就行，但一定要具体到"改哪个值、改成什么"。
4. 实操过程与核心环节实现：从零搭一个最小可用 Harness
4.1 环境准备与依赖梳理
先把环境说清楚。我用的组合是 LuisaCompute 作为计算框架，eDSL 层用它的 C++ 嵌入接口，Agent 侧接一个能输出结构化代码的模型接口。依赖上要注意几点：
- 编译器版本：eDSL 对宿主编译器版本敏感，太新太旧都可能出问题。我固定在某个 LTS 版本上，避免"昨天还能编今天就不行"。
- 后端 SDK：每个后端要装对应的驱动和工具链。这块最容易卡在"installing kernel"之类的环节——通常是驱动版本和工具链版本不匹配。
- Python 环境：如果 Harness 的调度部分用 Python 写，注意"不再支持与所选 kernel 关联的 python 版本"这类报错，本质是 Jupyter 或某个运行时绑定的解释器版本和当前环境不一致。解决办法是显式指定解释器路径，别依赖自动发现。
提示：环境这块我强烈建议用容器固化。Kernel/Shader 开发对工具链版本极其敏感，裸机环境迟早会乱。
4.2 约束层的代码骨架
约束层我用一个规则列表实现，每条规则是一个函数，输入是 Agent 生成的结构化描述，输出是通过或一条诊断。骨架大概这样：
class Constraint: def check(self, kernel_desc): raise NotImplementedError class DimensionConsistency(Constraint): def check(self, kernel_desc): block = kernel_desc["block_size"] smem = kernel_desc["shared_memory_elems"] if smem != block: return Fail( rule="dimension_mismatch", location="shared_memory_alloc", expected=block, actual=smem, hint=f"共享内存元素数应等于 block_size({block})，当前为 {smem}" ) return Pass() def run_constraints(desc, constraints): for c in constraints: r = c.check(desc) if isinstance(r, Fail): return r return Pass()这个结构的好处是加规则就是加一个类，删规则就是删一个类，互不影响。我一开始用一个大函数写所有检查，后来规则一多就完全没法维护了。
4.3 执行层的编译与运行封装
执行层要处理的核心是"把 eDSL 描述变成能跑的东西，并收集数据"。流程是：
- 从 Agent 输出解析出 Kernel 描述（结构化 JSON 或类似形式）。
- 用 eDSL API 把描述翻译成实际的 Kernel 对象。
- 查缓存，命中就加载，没命中就编译。
- 准备输入数据，分配设备内存。
- 启动 Kernel，同步等待完成。
- 收集输出、耗时、资源占用。
第 5 步的同步等待有个坑：GPU 是异步的，如果你不等同步就取结果，拿到的可能是垃圾数据。我见过有人因为忘了同步，校验层一直报错，查了半天才发现是时序问题。所有性能计时和结果读取之前，必须显式同步。
计时也要注意：第一次运行往往包含初始化开销（比如上下文创建、内存分配），不能算进 Kernel 耗时。我的做法是预热跑几次，再正式计时取平均。这样数据才稳定可比。
4.4 校验层的对比逻辑
校验层的核心是对比。我一般这样组织：
def validate(gpu_result, cpu_result, rtol=1e-4, atol=1e-5): diff = abs(gpu_result - cpu_result) tol = atol + rtol * abs(cpu_result) bad = diff > tol if bad.any(): idx = bad.nonzero() return Fail( rule="numerical_mismatch", count=int(bad.sum()), max_rel_err=float((diff / (abs(cpu_result) + 1e-12)).max()), first_bad_index=idx[0] if len(idx) else None, hint="数值超出容差，检查归约顺序或精度类型" ) return Pass()这里first_bad_index特别有用——它告诉你第一个出错的位置，往往能直接指向 bug 所在。比如第一个错的位置正好在某个边界，那大概率是边界处理有问题。
4.5 反馈层的组装与回灌
反馈层把前面各层的诊断汇总，按严重程度排序，然后拼成一段 Agent 能读的文本或 JSON。我一般按这个优先级排：
- 约束层失败（最优先，因为根本没跑起来）
- 编译失败
- 运行崩溃
- 数值校验失败
- 性能不达标
Agent 拿到反馈后，下一轮就针对最高优先级的问题改。这个优先级顺序很重要——如果 Agent 同时看到"编译失败"和"性能不达标"，它应该先解决编译，因为性能数据在编译失败时根本没意义。
回灌的时候，我会把历史几轮的反馈也带上，让 Agent 知道"这个问题我改过几次了"。避免它在同一个坑里反复横跳。
5. 常见问题与排查技巧实录
5.1 编译类问题速查
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| kernel header files not in any | 头文件搜索路径没配 | 检查 include 路径和工具链根目录 |
| 卡在 installing kernel | 驱动与工具链版本不匹配 | 对齐驱动和 SDK 版本 |
| 不再支持所选 kernel 关联的 python 版本 | 解释器版本与运行时绑定不一致 | 显式指定解释器路径 |
| 编译超时 | Kernel 太复杂或优化等级过高 | 降优化等级，拆分 Kernel |
"kernel header files not in any"这个报错我印象很深。它本质是构建系统找不到内核头文件目录。在 Linux 内核模块开发里，这通常意味着你没指定正确的内核源码路径。在 eDSL 场景里，类似的问题会表现为"找不到某个后端的内置头文件"。解决办法都是显式指定搜索路径，别依赖默认值。
5.2 运行类问题排查
运行阶段最烦的是"静默错误"——不崩溃，但结果不对。这类问题排查思路是二分定位：
先把输入规模缩到最小（比如 1 个元素），看结果对不对。如果小规模对、大规模错，那大概率是并行归约或同步的问题。如果小规模就错，那是基础逻辑问题。
然后逐步放大规模，找到第一个出错的规模。这个临界点往往能揭示问题——比如规模超过线程块大小时才错，那就是跨块同步没处理好。
注意：GPU 上的越界访问经常不报错，只是读到垃圾数据。所以校验层一定要覆盖边界情况，别只测"正常规模"。
5.3 性能类问题排查
性能不达标时，先别急着改代码，先确认测量方法对不对。我见过太多"性能问题"其实是测量问题：
- 没预热，第一次运行的初始化开销被算进去了。
- 没同步，计时器测的是"提交任务"的时间而不是"执行完成"的时间。
- 没排除数据传输，把主机到设备的内存拷贝时间也算进 Kernel 耗时了。
确认测量没问题后，再看 Kernel 本身。常见的性能瓶颈：线程块太小导致占用率低、共享内存 bank 冲突、全局内存访问不连续、分支发散。这些每个都能单独写一篇，这里不展开，但排查顺序建议是先看占用率，再看内存访问模式，最后看指令效率。
5.4 我踩过的三个坑
第一个坑：缓存键漏了编译选项。前面提过，改了优化等级但缓存没失效，白跑一天。教训是缓存键要包含所有影响产物的因素。
第二个坑：反馈信息太长。一开始我把完整报错原样喂给 Agent，结果它被几百行模板信息淹没，改不到点子上。后来改成只给结构化摘要加一句 hint，效果好太多。
第三个坑：约束层规则互相冲突。有两条规则对同一个字段提出了不同要求，导致合法代码被拒。后来我给规则加了优先级和互斥标记，冲突时按优先级裁决。
6. 扩展方向与个人经验
这套 Harness 搭起来之后，能扩展的地方很多。比如把性能数据也纳入反馈，让 Agent 不只追求"跑对"还追求"跑快"；比如把多个后端的测试结果横向对比，自动发现某个后端的特有问题；再比如把历史所有 Agent 的生成记录存下来，做失败模式分析，反过来优化约束层的规则。
我个人在实际操作中的体会是：Harness 的价值不在于它多智能，而在于它多稳定。Agent 可以很聪明，但如果 Harness 本身不稳定——今天能跑明天不能跑、同样的输入给不同的结果——那整个流程就没法信任。所以我在 Harness 上花的调试时间，比在 Agent 上多得多。这个投入是值得的，因为 Harness 一旦稳了，Agent 的迭代就是线性的、可预测的。
最后分享一个小技巧：给 Harness 加一个"最小复现"模式。当某个 Kernel 失败时，自动把它缩减到能复现问题的最小规模，然后把这个最小案例存下来。时间一长，你就有了一个失败案例库，既能用来回归测试，也能用来分析 Agent 的典型错误模式。这个库的价值，随着你跑的次数增加会越来越高。
