ARTICLE · 1375394
还在啃1000页PDF?Qoder+AGENTS.md让采集器DLL集成从3天压到10分钟
还在啃1000页PDF?Qoder+AGENTS.md让采集器DLL集成从3天压到10分钟如果你手上有一台带 UDP 网口的 FPGA 数据采集器,供应商给你丢过来一个 DLL,说"调用这个就能采波形"。 你打开头文件一看,七八百行函数声明: mstar_ethbridge_open、scan_device、get_device、axilite_read、axifull_write、collect_start、collect_waitstop…… 命名风格是小写下划线,参数有句柄、地址、缓冲区、长度,还有MHANDLE、MBOOL、EthBridgeInfo、collectinforst这些自定义类型。文档厚达一千多页,PDF 里还夹着"必须按顺序调用"、"不能同时打开两个实例"之类的红字。 你的第一反应:下周才能出 Demo。 但今天,我想分享一个可能改变这个判断的做法——把 SDK 交给 Qoder(或其他 AI IDE),让 AI 替你啃文档。 实测:从装好 SDK 到跑通采集 Demo,最快 10 分钟。 在讲怎么做之前,先讲清楚为什么"上位机开发"这件事这么劝退。 大多数人以为 UDP 就是send + recv。但数据采集设备要的不是"发个包收个包",而是: 广播发现局域网内的设备 处理 64KB 大包的 IP 分片与重组 区分控制命令、AXI 读请求、AXI 写请求、DMA 数据流 保证一包丢包时不卡 UI 这些如果都让上位机自己实现,一个熟悉 socket 的老手也得折腾两三周。 FPGA 里挂了一堆 IP 核、DDR、ADC 控制器,对外暴露的是AXI4-Lite 寄存器空间和AXI4-Full 的 DMA 缓冲区。 上位机要做的不是简单的读写,而是要知道: 哪个地址是采样率配置 哪个地址是量程选择 DMA 缓冲区在哪一段 DDR 地址 半满标志、停止标志在哪个偏移 没有厂商封装好一层,客户自己读寄存器手册能读到眼花。 一次完整的采集流程大致是这样: 顺序错了、少调一步、超时短了都会导致结果不对。更坑的是,出问题时 DLL 往往只返回一个 -1,你连是哪一步错都不知道。 大部分采集器厂商的"SDK"其实是这样一套: 客户拿到以后,要么啃 PDF,要么问客服。客服的答复速度决定了你项目进度。 更糟糕的是——这些 API 的调用规则,写在 PDF 的第 237 页脚注里,一句话没写完: 你甚至不知道"避免"是"绝对不行"还是"最好别"。 Qoder、Cursor、Windsurf 这类 AI IDE 有一个共同特性——它们会自动读取项目根目录下的AGENTS.md文件。 这份文件不是给人看的,是给 AI 看的。 我们把 SDK 目录结构改成这样: 关键就是AGENTS.md和SKILL.md。 不是函数手册,而是一份行为说明书。里面有几类东西:
这张表是核心。它把人类的自然语言映射到 API,AI 读了这张表就能直接生成代码。 不展开解释,只列结构。因为 AI 懂 pack(1)、懂 C 结构体,不需要人话。 四份"三段式"完整可跑的代码,AI 只需要改改参数。
为什么这一节重要? 因为 AI 有个"坏习惯"——它会臆造 API。你不告诉它不能怎么写,它就会自作聪明地编一个EthBridge_Read()出来,看着像那么回事,其实根本不存在。 这一节就是围栏。把 AI 关在正确的 API 集合里。 Qoder 的 Skill 系统可以配置成根据关键词自动激活。 SKILL.md的 frontmatter 里有这么一段: 当用户在 Qoder 里输入: Qoder 自动识别到关键词MStarEthernetBridge,激活mstar-dll-apiSkill,把整份 SKILL.md 内容作为上下文喂给模型。 用户不需要告诉 AI “去读那个文档”,AI 自己会读。 我们把 SDK 打开,用 Qoder 新建会话,看它到底能生成什么样的代码。 用户输入: AI 输出(节选): 关键:AI没有臆造ReadDmaData这种不存在的 API,因为它读了"拉数据用axifull_read"这条硬性规则。 用户输入: AI 输出: 关键:AI 正确使用了Pack = 1,没有踩结构体对齐坑——因为 SKILL.md 明确写了#pragma pack(1)。 用户输入: AI 输出:直接生成了main.cpp、WaveformWidget.cpp、CMakeLists.txt三件套,采集线程用QThread包住collect_waitstop,符合硬性规则第 3 条:禁止在 UI 线程调collect_waitstop。 用户输入: AI 输出(LabVIEW 是图形化编程,AI 输出"搭建蓝图"而不是代码): 关键:AI 特别提示了"Thread 必须选 Run in any thread"——这条经验就写在 SKILL.md 里,是传统 DLL 文档最容易漏的细节。 你让它发明一个 DLL 的调用范式,它会瞎编(因为 DLL 是专有 API,网上没有)。 但你把 API 清单、映射表、模板、规则全给它,让它把中文需求"翻译"成代码——这件事它的准确率可以到 95% 以上。 AGENTS.md的本质就是把"发明"降级成"翻译"。 客户踩到"采到的波形全 0"时,他不知道是量程没设、探头没接、还是 ADC 没初始化。 但厂商知道——这些坑都踩过。把这些经验写成排查表塞进AGENTS.md,AI 就变成"有经验的现场工程师"。 这是传统 PDF 文档做不到的事:PDF 写得再全,客户也懒得翻;AI 会在客户描述现象的第一时间主动匹配。 一套 DLL,四类客户: 做算法验证的:Python 做工业软件的:C# 做仪器级上位机的:Qt/C++ 做实验室集成的:LabVIEW 以前每种语言要维护一份示例和文档。现在一份AGENTS.md+ 一个examples/,四种语言的代码都由 AI 生成,厂商的维护成本降到 1/4。 如果你也在做硬件配套软件(不只是采集器,还包括光谱仪、运动控制卡、示波器、传感器网关),可以考虑按这个模板重构你的 SDK: 给人看 :入门教程、安装步骤、示例代码说明 给 AI 看 :API 清单、场景映射表、硬性规则、错误排查表 Qoder / Cursor / Windsurf 都会自动读。 硬件类 SDK 最怕 AI 瞎编 API。一定要写硬性规则,比如: Qoder 支持.qoder/skills/,Cursor 支持.cursor/rules/。把"遇到 xx 关键词时读这份剧本"配好。 二进制走网盘 / 邮件 / Release 页;源码走 Git。AI 能读到 examples,客户能直接编译,厂商也能保持技术壁垒。 我们拿 20 个客户真实提过的问题在 Qoder 上跑了一遍:
平均一次通过率85%。剩下 15% 的问题几乎都是"少调一步",AI 会在客户追问时立刻修正。 对比没有AGENTS.md的场景(直接扔 PDF):一次通过率大约40%——AI 会大量臆造 API 名。 差距是剧本带来的。 如果你想直接体验,三步: 下载 SDK :https://gitee.com/mstar_ypc/mstar-udpbridge-sdk (仓库只含头文件、文档、示例;DLL 二进制走 Release 页或联系客服) 在 Qoder 里打开 SDK 目录 :AI 会自动加载AGENTS.md 对 AI 说你的需求 : 第一次跑通 Demo 之后,把examples/里的代码改成你自己的项目结构——这一步也是 AI 更擅长。 数据采集器的上位机开发,过去难,不是因为 DLL 有多复杂,而是因为: 知识被文档化、但没有被结构化 经验被口耳相传、但没有被剧本化 当 SDK 作者愿意把"客户会怎么问、API 应该怎么调、坑在哪里"这些知识整理成一份 AI 读得懂的剧本,整个生态的入门门槛就会塌陷式下降。 这不是 AI 有多聪明——是文档的写法终于跟上了编程工具的样子。 如果你的产品也有配套 DLL/SDK,也许可以试试:别再写第 300 页 PDF 了,写一份 300 行的AGENTS.md吧。 SDK 仓库 :https://gitee.com/mstar_ypc/mstar-udpbridge-sdk 上位机示波器 :https://gitee.com/mstar_ypc/mstar-oscilloscope FPGA 参考工程 :https://gitee.com/mstar_ypc/mstar-collect-fpga
还在啃 1000 页 PDF?Qoder + AGENTS.md 让采集器 DLL 集成从 3 天压到 10 分钟
一份剧本、一次对话,上位机开发的门槛正在塌陷式下降
写在前面
传统上位机开发的"三座大山"
第一座山:UDP 协议栈
第二座山:AXI 总线与寄存器语义
第三座山:采集时序状态机
init → set_range → set_freq → set_oversample→ set_channel_mode × N→ start(dma_addr, len, pretrig_len)→ waitstop(timeout)→ axifull_read(dma_addr, buf, len)→ addata_tovolt(buf)
供应商的传统做法:扔一份 PDF 给你
SDK/├── MStarEthernetBridge.dll├── MStarEthernetBridge.lib├── MstarEthBridge.h├── MstarCollect.h├── API_手册_v1.2.pdf ← 一千多页└── demo.exe ← 但没源码
“在 Windows 多线程环境下,请避免在 UI 线程直接调用 collect_waitstop。”
破局思路:给 AI 写剧本,而不是给人写文档
SDK/├── AGENTS.md ← AI 剧本(不是给人看的 PDF)├── README.md ← 给人看的入门├── CHANGELOG.md├── LICENSE├── .qoder/skills/mstar-dll-api/SKILL.md ← Skill 自动触发├── include/│ ├── MstarEthBridge.h│ └── MstarCollect.h├── lib/x64/Release/ ← DLL 二进制(通过网盘分发)├── docs/│ ├── API_Help.md│ └── AI_WaveformApp_Template.md└── examples/├── Qt_CPP/├── Python_ctypes/├── CSharp_PInvoke/└── LabVIEW/
AGENTS.md 里写了什么
1. 客户请求 → API 映射表
2. 关键类型速查
typedef void* MHANDLE;typedef int32_t MBOOL;struct EthBridgeInfo { // #pragma pack(1)uint32_t state;uint16_t clientnum, reserved;uint16_t build; // 高位=年-2025,低 4 位=月uint8_t type, revision;char ip[20], mac[20];uint16_t port, speed;};
3. 代码模板(C++ / Python / C# / LabVIEW)
4. 常见错误排查表
5. 硬性规则(最重要的一节)
1. API 命名一律 snake_case,禁止臆造 PascalCase2. 必须先 mstar_ethbridge_open,参数 nullptr = 广播3. 必须检查 get_udpclient_size() > 0 再调 get_device(0)4. 必须在程序退出前:device_handle_release(h) → mstar_ethbridge_close()5. collect_start 的 bufaddress 是 FPGA DDR 中的地址6. 拉数据用 axifull_read,不是采集层的某个 Read 函数7. 电压转换:批量走 collect_arryaddata_tovolt,采样线程内联走 collect_get_channelscale
SKILL.md:让 AI 自动"知道"这是采集器场景
---name: mstar-dll-apidescription: MStarEthernetBridge DLL API 使用指南。当客户编写调用MStarEthernetBridge.dll 的上位机程序、查询 DLL 函数用法、排查通信/采集问题时使用。---
“帮我用 MStarEthernetBridge 这个 DLL 采一次波形”
效果演示:四种语言,四句自然语言
场景 1:Python 采集一次波形
用 Python ctypes 调用这个 DLL,扫描设备、采 1024 点、存成 CSV
import ctypes, os, csvos.add_dll_directory("./lib/x64/Release")dll = ctypes.WinDLL("MStarEthernetBridge.dll")dll.mstar_ethbridge_open.argtypes = [ctypes.c_char_p]dll.mstar_ethbridge_open.restype = ctypes.c_intdll.get_device.argtypes = [ctypes.c_size_t]dll.get_device.restype = ctypes.c_void_pdll.axifull_read.argtypes = [ctypes.c_void_p, ctypes.c_uint64,ctypes.POINTER(ctypes.c_uint8), ctypes.c_uint64]dll.collect_addata_tovolt.argtypes = [ctypes.c_void_p, ctypes.c_uint, ctypes.c_int]dll.collect_addata_tovolt.restype = ctypes.c_floatassert dll.mstar_ethbridge_open(None) > 0, "open failed"dll.scan_device()n = dll.get_udpclient_size()assert n > 0, "no device"h = dll.get_device(0)dll.device_lock(h)assert dll.verify(h), "signature not loaded"dll.collect_device_init(h)# ... 设量程 / 采样率 / 启动 / 等待 / 读数据 / 转电压 / 写 CSV ...
场景 2:C# 读取设备信息
用 C
P/Invoke,扫描设备,把每台设备的 IP/MAC/型号 打印出来
using System.Runtime.InteropServices;public static class MstarBridge {const string DLL = "MStarEthernetBridge.dll";[StructLayout(LayoutKind.Sequential, Pack = 1)]public struct EthBridgeInfo {public uint state;public ushort clientnum, reserved;public ushort build;public byte type, revision;[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 20)] public string ip;[MarshalAs(UnmanagedType.ByValTStr, SizeConst = 20)] public string mac;public ushort port, speed;}[DllImport(DLL, CharSet = CharSet.Ansi)]publicstaticexternintmstar_ethbridge_open(string strip);[DllImport(DLL)]publicstaticexternintget_devinfor(IntPtr h, out EthBridgeInfo info);// ...}class Program {staticvoidMain() {MstarBridge.mstar_ethbridge_open(null);MstarBridge.scan_device();int n = MstarBridge.get_udpclient_size();for (int i = 0; i < n; ++i) {var h = MstarBridge.get_device((UIntPtr)i);MstarBridge.get_devinfor(h, out var info);Console.WriteLine($"{info.ip} / {info.mac} / {info.speed} Mbps");}}}
场景 3:Qt/C++ 完整采集 + 波形显示
做一个 Qt 程序,一个按钮启动采集,采到的波形显示在 QCustomPlot 上
场景 4:LabVIEW 搭建蓝图
我要用 LabVIEW 调这个 DLL,帮我搭 CLFN
Front Panel 控件清单:• sDeviceIP String 默认 ""• numChannels I32 默认 8• numSamples I32 默认 1024• bStart Button• gWaveform Waveform GraphBlock Diagram 骨架:While Loop > Event Structure [bStart上升沿] > Case True >Sequence Structure (13 帧),每帧一个 CLFN + Case Structure 包错误处理关键 CLFN 配置:• Library : MStarEthernetBridge.dll (拷到 labview.exe 同级)• Convention : cdecl• Thread : Run in any thread ★强制要求
为什么这套做法能成?三个底层原因
1. AI 擅长"翻译",不擅长"发明"
2. 错误排查比正向调用更需要"经验"
3. 多语言绑同一套 API 的成本被摊平了
这套思路的普适性:SDK 设计者的新范式
1. 把文档拆成"给人看"和"给 AI 看"两份
2. 在仓库根目录放 AGENTS.md
3. 明确"AI 不能做什么"
禁止臆造 PascalCase 函数名禁止假设"应该有个 xxx_init" —— 只有本表列出的函数存在禁止在 UI 线程调 xxx_wait / xxx_block 类阻塞函数
4. 为常见 IDE 配置 Skill / Subagent
5. 开源 examples,不开源核心二进制
实测:AI 生成代码的准确率
客户反馈的两句原话
“我以为还得找你们要个工程师远程帮我调一周。结果我对着 Qoder 说了三遍"启动采集”,它就把 Python 示例改好了。" ——某电力监测项目负责人
“我们用的是 LabVIEW,以前从来没供应商能给我们 LabVIEW 的完整示例。这次 AI 直接把 CLFN 搭建蓝图一步步列出来,两个实习生半天搞定了。” ——某汽车零部件测试实验室















































































