如何使用IronQR与Cursor
ZXing.Net是ZXing条形码库的开源.NET移植。 当您向人工智能代理请求读取客户照片中的QR码的C#代码时,即使您指定使用IronQR,它也可能采用ZXing.Net的约定,例如比较Result.Text、筛选QR_CODE格式或将QrImageInput包装在using语句中。 在IronQR 2026.10.1中,以这种方式处理输入会引发NotImplementedException。
Cursor是一个基于VS Code代码库的人工智能代码编辑器。 生成IronQR代码或ZXing.Net翻译取决于两个功能。 代理遵循您提供的文档链接,并应用.cursor/rules中的项目规则。 本指南通过一个从客户照片中提取序列号和注册链接的保修录入服务来演示两者,并将该服务从ZXing.Net迁移到IronQR。 IronQR支持QR、Micro QR和rMQR符号。
本指南专注于使用Cursor编写代码。 有关IronQR读取选项的详细信息,请参考扫描模式指南、QR类型指南和值和坐标指南。
快速入门在Cursor中打开录入项目,并从代理面板发送此请求。
@src/WarrantyIntake/ @TestData/claims/ Before writing code, fetch
https://ironsoftware.com/qr/csharp/llms.txt and the scan modes page it links.
Add the IronQR package to src/WarrantyIntake. Give Program.cs a second entry
point so that `dotnet run -- --modes <photo>` reads one photo three times, once
per QrScanMode value, and prints each result's QrType, Value, Url, and four
Points. Set License.LicenseKey from IRONQR_LICENSE_KEY at startup, never from
a literal. Leave Claims/StickerReader.cs and its ZXing.Net reference untouched.
Run the new mode on TestData/claims/claim-0004.jpg and show me what it printed.
请勿在聊天消息中包含许可证密钥。 代理创建文件并运行终端命令,因此粘贴的密钥可能会出现在源代码、提交或日志中。 许可证密钥指南列出了支持的存储位置。
最小工作流程(5 个步骤)
- 从NuGet下载C#二维码库
- 在
.cursor/rules中提交一个名为IronQR并链接其文档的.mdc规则。 - 列出规则替换的ZXing.Net和QRCoder习惯。
- 在每个请求中提及读取器文件和一个实际客户照片文件夹。
- 将每个解码的序列与已知列表进行比较。
您应该使用哪种Cursor模型进行QR码工作?
Composer是Cursor自己的代理模型。 模型选择器还提供Cursor共同开发的SpaceXAI的Grok模型,以及来自OpenAI,Anthropic,Google和其他实验室的模型。 下面的测试运行使用了Grok 4.7。
日常照片工作,如为索赔记录添加字段或重新运行照片文件夹,适合快速模型。 当一批照片因不明原因停止解码时,切换到需要更长时间推理的模型。 模型以不同的方式读取请求,因此在每个请求中指定照片文件夹和输出应匹配的序列号。
如何将IronQR文档提供给Cursor?
将IronQR的文档链接放入请求中,或保存在已提交的规则中,以免有人需要粘贴它。 llms.txt索引链接指南和API参考,llms-full.txt在一个文件中总结了44页文档。截至2026年10月,Cursor的@菜单附加文件、文件夹、终端、聊天、Git差异和浏览器,因此IronQR的文档通过链接到达代理。
IronQR的枚举容易被放错位置。 QrScanMode和QrEncoding位于IronQr.Enum中,而QrErrorCorrectionLevel位于IronQr中,从内存编写代码时,如果出错无法构建。
@src/WarrantyIntake/Program.cs Answer from https://ironsoftware.com/qr/csharp/llms.txt
and the pages it links, and leave every file as it is.
Which namespace declares QrScanMode and QrEncoding, and which declares
QrErrorCorrectionLevel? Which scan mode does a QrImageInput get when the
constructor is given only an image? What do IronQR's pages say OnlyDetectionModel
returns, and does that match the --modes output from the last turn? Put the
page URL under each answer.
如何编写项目规则以编码您的IronQR约定?
项目规则是.mdc文件,位于.cursor/rules中。 它们与代码一起提交,因此每个克隆都具有相同的规则。 该文件夹中的普通.md文件会被忽略,因为它没有前置信息来说明何时适用。
该规则设置globs并关闭alwaysApply,因此每当读取器或其测试在上下文中时附加,并避开从未涉及照片的请求。 将其保存为.cursor/rules/ironqr-photos.mdc。
---
description: IronQR conventions for reading QR codes from customer photos
globs: src/WarrantyIntake/Claims/**/*.cs, tests/**/*.cs
alwaysApply: false
---
# Reading customer photos with IronQR
- Read and write QR codes with IronQR only. The NuGet package is IronQR, or
IronQR.Linux for a Linux build, and the namespace is IronQr. Do not add
ZXing.Net, QRCoder, or any other QR package, and remove them where they
are already referenced.
- Documentation: https://ironsoftware.com/qr/csharp/llms.txt
- Never inline a license key. Read it from the IRONQR_LICENSE_KEY environment
variable.
- Do not put QrImageInput in a using statement. Its IDisposable.Dispose throws
NotImplementedException in IronQR 2026.10.1.
- Load only image files with AnyBitmap.FromFile. It throws on a CSV.
- Compare QrResult.Value with stored strings, never Url.ToString().
- Do not invent IronQR members. If one is uncertain, say so and cite the page.
AGENTS.md。 它没有前置信息,因此无法按文件模式进行范围限定。 将按模式范围限定的IronQR规则保存在.cursor/rules中。规则适用于Agent请求。 根据Cursor的文档,它们不会影响Tab,并且用户规则不适用于内联编辑。 自行检查那些功能的建议与规则。
如何将ZXing.Net调用映射到IronQR?
仅说“使用IronQR”的规则让模型去猜测每个ZXing.Net调用变为何物。 列出等价物可以消除猜测。
| ZXing.Net或QRCoder | IronQR |
|---|---|
BarcodeReader解码调用 | 用于Read的QrReader,返回每个代码 |
Result.Text | QrResult.Value |
QR_CODE格式检查和过滤 | 在读取后对QrResult.QrType进行检查 |
| 更深入的扫描选项 | 在输入上的扫描模式 |
Result.ResultPoints,模式中心 | QrResult.Points,四个角 |
| QRCoder的生成器 | QrWriter.Write及其保存调用 |
ZXing.Net的BarcodeFormat枚举没有Micro QR或rMQR成员,其README列出QR码但没有较小的符号,因此ZXing.Net读取器返回仅包含Micro QR序列的贴纸为无。
将该表添加到规则中作为另外两行。
- Translate ZXing.Net instead of porting it. Result.Text becomes QrResult.Value,
BarcodeFormat checks become QrResult.QrType checks, and ResultPoints (finder
pattern centres) become QrResult.Points (corners).
- Write test stickers with QrWriter.Write(...).Save().SaveAs(path), not QRCoder.
如何计划和执行迁移到IronQR?
在发送此请求之前使用Shift+Tab将聊天切换到计划模式,Cursor将草拟计划作为您可以编辑的文件。
@src/WarrantyIntake/Claims/ @tests/WarrantyIntake.Tests/ @TestData/claims/expected.csv
StickerReader decodes claim photos with ZXing.Net and the tests draw stickers
with QRCoder. Newer products carry a Micro QR serial that ZXing.Net never
returns. Plan the move of both projects to IronQR. For each ZXing.Net or
QRCoder call, name the IronQR member that replaces it and the file it sits in,
state which QrScanMode the reader will use and why, and keep ClaimSticker and
the public Read(string) signature unchanged. No code until I approve.
纠正计划中的错误,然后点击构建,或在Agent中发送下一个请求。
Build the approved plan and follow @ironqr-photos. Remove the ZXing.Net and
QRCoder package references, run dotnet build and dotnet test, then run the app
over TestData/claims and compare each printed row with
TestData/claims/expected.csv. Report how many rows matched before the change
and after it, and show the diff.
从@菜单中选择,@ironqr-photos按名称附加规则,即使其模式会错过文件。干净的构建不能显示Micro QR序列是否返回。 匹配计数显示结果。
Cursor功能适合哪个变化?
根据变化的范围选择一个。 Tab处理可预测的下一次编辑,内联编辑处理一项选择,这一项由一句话描述。 代理处理需要多个文件、更改规则或构建循环的修改。当撤销错误更改的成本超过计划成本时,计划模式收益良多,而云代理适合不需要监视的工作。
一个新产品线新增了一个矩形电缆标签,通过rMQR码携带其序列,IronQR报告为QrEncoding.RMQRCode。 在阅读器中选择结果循环,并按Ctrl+Shift+L(macOS上Cmd+Shift+L)将选择添加到聊天中,然后在代理中发送此请求。
In StickerReader.Read, treat a result whose QrType is QrEncoding.RMQRCode the
same way as a Micro QR result, so its Value becomes the serial.
迁移后的读取器已经返回了标签照片的SN-61518,因为它将任何不是URL的值视为序列号。 编辑替换这个猜测为对符号类型的检查,因此即使其文本看起来像URL,Micro QR或rMQR值也会成为序列号。
如何调试缺失的QR码值?
每种扫描模式都会改变返回的内容。
Auto是默认模式。 IronQR的API参考将其描述为机器学习模型,当模型找不到时,基本蛮力读取作为后备。- 蛮力读取单独在
OnlyBasicScan下运行,模型被跳过。 OnlyDetectionModel定位代码而不解码它们。 扫描模式指南将其输出列为坐标。
如果模型报告它无法解码的框,则回退永远不会运行,Auto不返回值。 整体框照片会触发此问题,在4000x3000帧中约110像素宽的贴纸。 检查代理的修复是否在没有返回值时重试OnlyBasicScan。
@src/WarrantyIntake/Claims/StickerReader.cs @TestData/claims/far/
Customers who photograph the whole box send pictures like these. Since the move
to IronQR none of them returns a serial, though the ZXing.Net reader read every
one. Before changing code, read each photo with all three QrScanMode values and
show what each mode returned. Then fix StickerReader without losing any photo
it reads today, and report the match count for TestData/claims and for
TestData/claims/far against their expected.csv files.
从IronQR的打印输出中提取每个序列,询问产生它的命令。
角顺序也依赖于模式。 当模型定位代码时,四个点从左上、右上、左下、右下运行,正如扫描模式指南所述。 OnlyBasicScan按顺时针返回代码自身的角,与贴纸一起旋转。 从坐标计算轮廓而不是假定顺序。
如何编写QR读取的回归测试?
比较解码值与已知列表的测试在库升级时存活,而比较图像字节的测试在渲染变化时可能失败。 云代理可以在隔离的云VM中运行此提示。 在您启动云代理之前,在云代理仪表板中将IRONQR_LICENSE_KEY添加为秘密。
@tests/WarrantyIntake.Tests/ @TestData/claims/ Write xUnit tests for StickerReader
that prove every row in TestData/claims/expected.csv and
TestData/claims/far/expected.csv matches, that a Micro QR and an rMQR sticker
made with QrWriter read back to their serials, that a photo with no code gives a
null serial and no exception, and that a link sticker's serial comes from Value,
not Url.ToString(). Copy TestData into the test output. Run dotnet test and
report passed and failed counts.
最后一个断言对一个其全部值是裸地址的贴纸很重要。 从IronQR的扫描模式指南读取示例图像给出的Value为http://en.m.wikipedia.org,并提供了一个带尾部斜线的Url,因为Uri标准化了地址。 对于此服务中的链接,其中序列为最后路径段,该断言不会失败。
IronQR的人工智能编码助理指南在定义的通过标准下运行一个IronQR任务从头到尾。
您应该部署哪个IronQR包?
IronQR.Slim提供IronQr命名空间和基本扫描。 完整的IronQR包添加了检测器和ONNX运行时。IronQR的NuGet包指南指出仅限Slim的项目还需要其操作系统的IronSoftware.ReaderInternals包。
@src/WarrantyIntake/WarrantyIntake.csproj @src/WarrantyIntake/Claims/StickerReader.cs
The service ships as a win-x64 folder, and someone asked whether IronQR.Slim
could replace IronQR. Settle it with numbers. Publish for win-x64 as things
stand and record the folder size. Then swap to IronQR.Slim plus the native
package its documentation says it needs, publish again, and rerun
TestData/claims and TestData/claims/far against their expected.csv files. Keep
the swap only if every row still matches, and list which QrScanMode values the
reader can still use afterward.
仅有IronQR.Slim时,Auto没有模型,直接进行基本扫描,OnlyDetectionModel会引发IronQrException。 IronQR的API参考警告说,没有模型的读取较慢且质量较低。 在切换包之前,请先用您自己的客户照片进行测试。
在实际运行中这些提示生成了什么?
这八个提示按顺序发送到Cursor以对样例保修输入存储库进行。 它包含一个带有ZXing.Net读取器的控制台应用程序,一个用QRCoder绘制贴纸的xUnit项目,以及具有已知序列号的十二张索赔照片。 规则、电缆标签照片和整体照片立即在使用它们的提示之前添加。 许可证密钥仅在环境中设置。 运行结束后,每次提交的全新发布版本都从迁移中重新读取照片文件夹,并重现了IronQR读取器的匹配计数及以下测试结果。
- 索赔照片匹配ZXing.Net读取器的8/12和迁移到IronQR后的12/12。
- 每次扫描模式读取一次,claim-0004在自动和OnlyBasicScan下给出了两个带值的代码,并在OnlyDetectionModel下给出了两个空值结果。
- rMQR更改使索赔照片在更改前后保持在13/13。
- 修复之前,Auto读取0/4的整体照片。 OnlyDetectionModel找到了3、1、3和2个没有值的框,而OnlyBasicScan读取了4/4。
- 修复后整体照片读取4/4,索赔照片13/13。
- xUnit套件通过了22/22的测试。
- 为win-x64发布生成了75,624,980字节,使用
IronQR和19,510,306使用IronQR.Slim。 我们的重建给出了75,624,288和19,509,614。 - 在
IronQR.Slim上,读取器仍然匹配13/13的索赔照片和4/4的整体照片。 - 每个Release构建有0错误且无需手动编辑。
- 并非每一步都按此处所写运行。 提示是手动发送的,提及被粘贴为文本,代理通过搜索其名称找到规则文件。 计划通过发送下一个提示得到批准,构建从未点击,云代理提示在代理模式下本地运行。
运行记录保存了每个指南的包版本、模型、时间和测试机器。
故障排除
- 在IronQR中应用许可证密钥,当生成的代码引发许可异常时
- 使用扫描模式读取QR码,当照片返回位置但无值时
- QR码类型指南,当Micro QR或rMQR序列丢失时
- IronQR NuGet包,在
IronQR、IronQR.Slim和平台包之间进行选择时
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。