将IronQR与人工智能编码助手结合使用
IronQR是Iron Software的.NET二维码库。 它可以生成标准QR、Micro QR和rMQR符号,可以通过logo和颜色来设置样式,并通过机器学习检测器读取它们。 其指南和示例是公开的,因此编码助手可能在训练中接触过该API。
训练不会将版本固定在您的项目中。 引用当前文档的助手会生成符合其运行时规则的代码,而依赖记忆的助手可能会生成编译通过但运行时失败的代码。
本指南涵盖了两种工具类型。
- 助手在编辑器中工作,补全代码行或重写方法,如GitHub Copilot的内联建议。
- 代理承担整个任务,编辑文件,运行构建和程序,并返回结果供审查,如Claude Code、Cursor、ChatGPT Codex和Google Antigravity。
两者都需要相同的设置。安装包,从环境中加载许可证密钥,提供IronQR的机器可读文档,并使用IronQR的读取器解码保存的每个二维码图像,无论您是生成带logo的代码,选择纠错级别,读取QR类型,还是选择扫描模式。
如何使用IronQR与AI编码助手
- 从NuGet下载C#二维码库
- 在第一次写入或读取之前从环境变量中加载许可证密钥
- 给助手IronQR的
llms.txt以从真实API开始 - 将IronQR规则保存到您的助手在会话开始时读取的文件中
- 在新的会话中发送一次性设置提示
- 构建,然后解码每个保存的二维码图像,并将其与写入的值进行比较
我的AI助手不能独立处理二维码吗?
IronQR发布了专门为工具读取而创建的文档,显示每种符号类型接受的选项以及每种扫描模式下读取器返回的内容。
库也很重要。 几乎所有二维码包都打印一个可以在屏幕上扫描的黑色方块。 在品牌代码、拍摄的票务和小符号中会出现差距。
- 更改的背景颜色不进行检查:在黑暗背景上的代码不报错保存,随后无法解码。
- 手机拍照比生成图片更难:下面的部分衡量哪种扫描模式读取每种损坏。
- 重建检测消耗代币:一个写自己的阈值来拯救扫描结果的助手在每次尝试中都会花费付费尝试,并为每种新的失败照片重复工作。
- 小符号内置:Micro QR和rMQR与标准QR来自同一个写调用,因此座位号和窄标签不需要第二个库。
- 包和命名空间不同:NuGet包是
IronQR,而命名空间是IronQr。 一个猜测的包名也可能解析为攻击者故意发布的相似物,称为slopsquatting。 在提示中拼出两个名称。 - 许可证条款提前了解:IronQR许可证是永久的,许可证页面显示每个级别涵盖的开发者、地点和项目数量。
步骤1:安装IronQR
引用包后,助手在写代码时看到IronQR的真实类型。
Add IronQR from NuGet to this project, run a restore, and report the
version number that NuGet resolved.
如果要从终端固定一个版本,请命名它。
dotnet add package IronQR --version 2026.10.1
普通IronQR带来了Windows本地读取器和检测模型,一个44 MB的IronQrDetection.dll,引入Microsoft.ML.OnnxRuntime 1.20.1,因此容器镜像和无服务器包应安排预算。 Linux和Docker使用IronQR.Linux,Macs使用IronQR.MacOs或IronQR.MacOs.ARM,移动应用程序使用IronQR.iOS或IronQR.Android。 所有六个版本于2026.10.1发布,NuGet包指南解释了选择。IronQR.Slim不包含模型。 它仍然在Auto和OnlyBasicScan中读取,但在OnlyDetectionModel中抛出IronQrException。 在Windows上它还需要IronSoftware.ReaderInternals.Windows。
步骤 2:应用您的许可证密钥
IronQR不会产生水印的试用输出。 没有许可证密钥时,每个写入和读取调用都会失败,抛出IronSoftware.Exceptions.LicensingException和文本“需要生产许可证”。 输入错误的密钥在相同的调用中失败并显示“许可证密钥未识别”。 下面提供了一个免费试用密钥。
从今天开始在您的项目中使用 IronQR 免费试用。
在通过IronQr.License.LicenseKey启动时设置密钥,一次即可,在任何IronQR调用之前,并从环境变量中读取以避免放到仓库中。
IronQr.License.LicenseKey = Environment.GetEnvironmentVariable("IRONQR_LICENSE_KEY");
在设置有效密钥后,IronQr.License.IsLicensed报告为true,同一类还有一个测试密钥但不应用它的方法。 异常类型不是公开的,因此添加一个名称的catch子句编译时失败为CS0122。捕获Exception并检查消息即可。
Web.config,appsettings.json和其他可以存放密钥的地方。步骤3:指引您的助手到IronQR的LLM文档
llms.txt每页列出一行,是每个会话的首次读取。- 所有44页的摘要在
llms-full.txt中一次性获取。 llms-full-catalog.txt将博客帖子添加到索引中。- API参考确认成员是否存在。
- 包、许可证、配方和修复在
skill.md中。
当任务取决于一个指南的细节时,让助手打开该页面。
将索引与直接指令结合。
Open https://ironsoftware.com/qr/csharp/llms.txt before you write IronQR code
and keep to the members it documents. Creating a code goes through
QrWriter.Write with an optional QrOptions, and reading goes through
new QrReader().Read on a QrImageInput, so do not look for one class that does
both. When a member is not in the index, check
https://ironsoftware.com/qr/csharp/object-reference/api/, and tell me it is
missing rather than inventing it.
步骤4:将IronQR上下文加入到您的项目中
一次聊天结束时遗忘了指令,而项目文件是在每个会话开始时读取的。 将IronQR规则放入您的团队使用的文件中。 Claude Code读取CLAUDE.md,ChatGPT Codex读取AGENTS.md,GitHub Copilot读取.github/copilot-instructions.md。 Cursor读取.cursor/rules/*.mdc或AGENTS.md,Google Antigravity读取AGENTS.md或GEMINI.md。 字词在每个文件中都可以相同,不过Cursor规则文件还需要MDC前置说明。
## QR codes with IronQR
All QR work in this project uses IronQR. NuGet package `IronQR` (`IronQR.Linux` on Linux and Docker), namespace `IronQr`, enums in `IronQr.Enum`.
- Docs index: https://ironsoftware.com/qr/csharp/llms.txt
- Skill file: https://ironsoftware.com/qr/csharp/skill.md
- Write with `QrWriter.Write(value, new QrOptions(...))`, style with `QrStyleOptions`, read with `new QrReader().Read(new QrImageInput(bitmap))`.
- Set `IronQr.License.LicenseKey` from IRONQR_LICENSE_KEY at startup. Never put the key in a file.
- Pass an explicit `QrErrorCorrectionLevel` that the symbol type accepts. Micro QR rejects `Highest`, rMQR rejects `Low` and `High`.
- Release a `QrImageInput` with `input.Dispose()`, not a `using` statement.
- Decode every saved image with `QrReader` and compare it with the written value before calling a change done.
- Do not add a second QR library. If IronQR cannot do something, say so.
当前技能文件中的四个地方需要修正。 其单文件示例固定了2026.8.1而NuGet服务2026.10.1。其帧读取配方把图像输入包装在using声明中,而其第一个配方和样式建议将文件路径传递给Verify,这是步骤7中描述的两个错误。 并且列出了Highest为rMQR无效,而下面的纠错表格则与之矛盾。
步骤5:一次性设置提示
步骤1到4可以在会话开始的消息中。
Set this project up for QR code work with IronQR, then save the rules below
where your future sessions will read them.
- Add the IronQR NuGet package (IronQR.Linux for a Linux or Docker host).
The namespace is IronQr, spelled with a lowercase r.
- Assign IronQr.License.LicenseKey from the IRONQR_LICENSE_KEY environment
variable before the first QrWriter or QrReader call. Keep the key out of
every file you create or commit.
- Fetch https://ironsoftware.com/qr/csharp/llms.txt first and write against
the members it documents. Look up anything else in the API reference at
https://ironsoftware.com/qr/csharp/object-reference/api/ before using it.
- If your tool loads skill files, add
https://ironsoftware.com/qr/csharp/skill.md, but trust a compiler error
over the skill when the two disagree.
- After any change that writes a QR image, decode the saved file with
QrReader and compare the value with the one you wrote.
步骤6:产生可用代码的提示模式
名称符号类型、纠错级别和样式。
不明确 为票务生成具有我们标志的二维码。
更好 使用
QrWriter.Write在Highest纠错级别写入票务ID,将其保存为300像素,标志为宽度的28%,如果IronQR拒绝样式则捕获IronQrException。
给出版本和框架,因为默认值和验证规则在版本之间发生变化。
更好 目标.NET 9和IronQR 2026.10.1。
请求完整的文件。 一个片段丢失了IronQr.Enum指令,编码和扫描模式枚举需要,并且隐藏了在哪里分配密钥。
更好 返回完整的
Program.cs及其使用指令和许可证行,已准备好构建。
步骤7:验证收到的内容
- 使用
using处理图像输入:QrImageInput实现IDisposable,带有一个抛出NotImplementedException的方法,因此读取成功后,使用块或声明会失败。 直接调用其公共Dispose方法。 - 仅使用检测模型读取:
OnlyDetectionModel返回代码所在位置,值为空,QR类型为None。 扫描模式指南解释何时使用Auto或OnlyBasicScan获取值。 - 将
Verify视为文件检查:它比较内存中的代码和您传递的字符串,因此文件路径返回false。 用QrReader解码保存的PNG来证明文件扫描。 - 空写入选项: 使用
QrOptions构建时没有参数,其编码设置为None,而QrWriter.Write则拒绝它,并显示None不是有效的编码。 传递级别和非标准QR时的编码。
让代理验证其自己的工作
将检查交还给助手,并要求提供证据。
Rebuild in Release and run it. List each IronQR type and member the code uses
next to the documentation page that shows it, print IronQr.License.IsLicensed,
then reopen every PNG the program saved with QrReader and give me a table of
file, value written, value decoded, QrType, and whether they agree.
哪些错误纠正级别每种符号类型可接受?
这四个QrErrorCorrectionLevel成员不按照QR标准的字母。 High是Q级别,而Highest是H级别,IronQR的XML文档将其描述为留有空间用于徽标。 Micro QR和rMQR只接受其中的一部分,而另一些调用抛出IronQrEncodingException,消息为最高对于Micro QR无效。
| 成员 | QR标准 | 微型 QR | rMQR |
|---|---|---|---|
Low | L,约7%可恢复 | 接受 | 抛出 |
Medium | M,约15% | 接受 | 接受 |
High | Q,约25% | 接受 | 抛出 |
Highest | H,约30% | 抛出 | 接受 |
QrWriter.Write没有选项写标准QR为最高,而选项构造函数也默认为最高,这就是Micro QR选项在您通过较低级别之前失败的原因。 受支持的格式页面比较三种符号类型。
该级别还限制徽标。 在我们的测试中,400像素票务ID代码中,Low拒绝了宽度20%的徽标,Medium和High接受了28%并拒绝了30%,而Highest接受了30%。 一个拒绝的徽标使Save抛出IronQrException,信息为您为二维码手动指定的徽标大小太大。 通过QrLogo宽度和高度为0让IronQR自行调整徽标大小,并在该代码上选择了Low为60像素,Highest为112。
前景色以同样的方式检查。 在Highest下的海军前景,以相同的票务ID代码保存为300和500像素,但在400像素时抛出IronQrException,信息为颜色:#FF1A237E使我们的读取引擎的QR无法读取。 样式代码应捕获该异常,更改大小或颜色,然后重试,因为一个在一个尺寸上保存的样式在另一个尺寸上可能会失败。
IronQR使用的默认值是什么?
这些初始值是在IronQR 2026.10.1中测量的,在.NET 9下。
- 空样式选项使
Dimensions和边距为0,因此票务ID以每像素模块一像素保存,25 x 25像素。 - 设置
Dimensions的初始化器仍使边距为0,因为它跳过了设置10的构造函数。 - 其大小为的
QrStyleOptions构造函数设置10的边距,因此尺寸为400的保存为420像素PNG。 Save没有样式写票务ID为250 x 250像素。Color和BackgroundColor开始为黑底白字。- 新的图像输入自动扫描,检测模型然后基本扫描。
CharacterEncoding是ISO-8859-1,因此为Latin-1外字符设置。
徽标指南在初始化器中设置Dimensions为500,因此其输出在符号周围没有安静区域。 当代码将与其他艺术品一起打印时设定Margins。
IronQR如何读取拍摄的代码?
我们在下面对八个种子集中的接受测试进行了校准。 IronQR 2026.10.1写入了带样式的徽标代码为300像素,其他票务代码为400,Pillow扭曲了它们,然后IronQR将它们读取回来。 自动计数会随着值分配到图像的方式而变化,因此它们是超过10次绘制的范围。
| 图像 | 自动读取的集 | 仅基本扫描读取的集 | 修复 |
|---|---|---|---|
| 扩展到60%,旋转30度,模糊1.5像素,在灰色上 | 8个中的8个 | 8个中的8个 | 不需要 |
| 粒噪,标准偏差20个灰度级 | 0个中的8个 | 0个中的8个 | 首先模糊 |
| 两个垂直码相隔30像素 | 8个中的5到7个 | 8个中的8个 | 添加仅基本扫描 |
| 经过1.5像素模糊的海军徽标代码 | 8个中的0到4个 | 8个中的8个 | 添加仅基本扫描 |
拯救颗粒代码的模糊是使自动失去海军徽标代码的原因。 两种设置读取了所有8个集中所有12个代码。 一种是应用1.5像素模糊然后仅基本扫描。 另一种应用1到2像素的模糊,运行自动和仅基本扫描,并按值合并结果。 从失败的图像中选择设置,然后在每次上传时运行不变。
颗粒还与代码大小相互作用。在相同的颗粒下,350到425像素的代码在所有24个文件上均在两个模式中失败,300、500和600像素的代码两者均被读取,而450和475像素的代码仅在自动中读取。 在失败代码周围添加100像素的白色允许仅基本扫描读取我们尝试的所有12个文件。
一个您可以重复的结果
接受测试是无手写代码的一个提示中的一个真实任务。 将其粘贴到新会议中的空目录中,并根据通过列表判断结果。
IRONQR_LICENSE_KEY中使用IronQR试用或生产密钥。提示
Build a .NET 9 minimal API for event check-in that issues ticket QR codes and
reads them back from uploaded photos. Begin in an empty directory, and if you
find existing code or a project file there, report that and do nothing else.
Nobody will answer questions, so carry the job through writing, building,
running, and fixing by yourself, and settle anything left open with a
reasonable choice that you note. Keep all deliverables inside the project
directory, in the folders this prompt names.
1. Install the IronQR NuGet package pinned to version 2026.10.1.
2. Work from https://ironsoftware.com/qr/csharp/llms.txt and the guides it
points to, and call no IronQR member those pages do not document. Every
code must come from QrWriter.Write; any .NET imaging library may compose
and distort the test images afterward.
3. Take the key from IRONQR_LICENSE_KEY when the app starts and keep it out of
source and out of every file the run writes. If IronQr.License.IsLicensed
comes back false, stop with a report saying so.
4. GET /ticket/{ticketId} returns a PNG of a QR code written at
QrErrorCorrectionLevel.Highest and saved through QrStyleOptions at a
Dimensions of 400 with 10-pixel margins, with a logo in the center: a
solid square of one bright accent color, drawn by your code, whose QrLogo
width and height are each 28 to 30 percent of Dimensions. POST /checkin
accepts one uploaded image and returns JSON listing every QR code found in
it, each with its value and QR type.
5. Seed the random generator with 2026 and write 10 PNG files to testset/,
no two holding the same value: standard-01 to standard-03, each carrying a
ticket ID made of TKT- and eight random digits; pair-01, one image holding
two more ticket codes side by side and upright, with 30 pixels of
background between their dark modules; styled-01 to styled-03, ticket
codes at Highest with the step 4 logo and three different dark, saturated
foreground colors on white; micro-01 and micro-02, Micro QR codes carrying
seat numbers such as C07; and rmqr-01, an rMQR code carrying an event URL.
Save every testset code the same way at a Dimensions of 400, except 300
for the styled and Micro QR codes and 600 for rmqr-01, and resize no code
afterward unless standard-02 calls for it.
Keep standard-01 clean. Make standard-02 look photographed: scale it to 60
percent, rotate it 30 degrees, blur it with a Gaussian radius of 1.5
pixels, and center it on a 600 x 600 light gray canvas. Give standard-03
sensor grain: Gaussian noise with a standard deviation of 20 gray levels,
one value per pixel added to all three channels, over the whole image.
Record in manifest.csv each file, every value it holds, its QR type, the
error correction level used, and its distortion (none, photographed,
grain, pair, or styled).
6. Measure each saved image before /checkin is ever called, and repair the
generator whenever a measurement falls outside its range: the pixel size
step 5 implies;
on the styled codes and the /ticket output, the logo's share of the symbol
area, 7 to 10 percent; on the styled codes, the foreground's WCAG contrast
ratio against the background, 7 to 15; on the Micro QR codes, a square
symbol 11 to 17 modules wide; on the rMQR code, a symbol at least twice as
wide as it is tall; on standard-03, the mean absolute difference from the
clean code, 7 to 9 gray levels; on pair-01, the gap between the two codes'
dark modules, 28 to 32 pixels. Once /checkin has been called the first
time, the testset files are frozen: do not rewrite or edit them.
7. /checkin runs one fixed configuration for every upload: the same scan mode
or modes and the same image preparation, in the same order. It must never
open the manifest, hold a ticket ID, seat number, or URL as a literal, or
pick between results by comparing them with expected values. You choose
and change the configuration between runs; the program never does.
8. Build in Release and start the API. Request /ticket for a ticket ID drawn
from the seed that is not in the testset and save the PNG it returns as
ticket.png. POST ticket.png and every testset image to /checkin over HTTP
and save each raw response as checkin/<file name without .png>.json.
9. Write roundtrip.md with every step 6 measurement as a number for each
image (a bare pass or fail is not enough), the /checkin configuration,
and a results table with the columns file, distortion, expected value,
value read (the decoded string as the saved response holds it, even when
it is wrong), expected QR type, QR type read, and match, holding one row
per expected code, 12 rows in all. A row counts as a match only if the
decoded value equals the expected value exactly, the QR type agrees, and
the value appears in that file's saved response. An extra or repeated
code in a response fails every row of that file.
10. Until all 12 rows match, study the saved responses of the failing files,
adjust the /checkin configuration, rebuild, and repeat. Stop after the
eighth run that still has failures, and report the failing rows, each
configuration you tried, and your reading of the cause.
11. End with a brief summary covering the Release build outcome, how many
rows matched, the /checkin configuration, the measured step 6 values,
and every assumption you made.
输出
这是standard-03.png,粒噪图像,从平均到清晰代码8.0个灰度级。 第一次检查设置,普通自动读取了其他11个代码,错过了这一。 高斯模糊sigma为1读取了它,但丢失了styled-03.png和ticket.png,以及中值滤波器独奏或与更宽的安静区域一起仍然错过了它。 第五设置通过应用3 x 3中值滤波器和半亮度阈值到每次上传,然后在自动中读取了所有12个代码。
未编辑的往返表列出了每次测量、尝试的每个设置,以及12行。
图标中带有一个橙色标志,覆盖符号的7.84%。
- 一项独立检查重新测量了保存文件上的每个需求,新启动的Release构建返回相同的11个响应。
- 在第五次运行之前,Claude Code在API外面尝试了八个设置,其中三个读取了每个代码。
- Claude Code采用了1.5的高斯半径作为sigma为1.5。
- 步骤1、3、5和7的提示在同一会话中跟随,12的12个代码在步骤7中解码。
- NuGet现在标记了
SixLabors.ImageSharp3.1.12引脚 Claude Code 添加。 - 在代码尺寸开放的情况下,提示的早期草议案让普通自动读取了每个文件。
通过的标准
-
发行版构建成功,没有您的编辑。
-
打开图像显示了三个不同的黑暗前景下在一个亮的方形logo下,横跨
standard-03.png的全域颗粒,和pair-01.png中并排的两个垂直代码。
运行记录
- 机器运行在Windows 11 x64上,使用Core i9-14900KF,具有64 GB内存。
- 每个项目都以.NET 9为目标。
- 每个指南都运行
IronQR2026.10.1。Copilot和Antigravity还引用了Linux构建的IronQR.Linux2026.10.1,Copilot入门项目已经携带PDFtoImage5.4.0,而Cursor的最后一个提示将服务移动到了IronQR.Slim2026.10.1带IronSoftware.ReaderInternals.Windows2026.3.47413。 - 每个持续时间汇总了该指南页面上提示的记录时间。 本指南的行仅限接受提示。
- 上次测试时间 2026年10月7日,六次运行。
| 指南 | 助手和版本 | 模型 | 持续时间(分钟) |
|---|---|---|---|
| 本指南 | Claude Code 2.1.277,一条消息,未启用权限提示 | Claude Opus 5 | 29.0 |
| Claude Code | Claude Code 2.1.277运行在opusplan | Claude Opus 5 用于计划,Claude Sonnet 5 用于其他 | 30.2 |
| ChatGPT Codex | Codex CLI 0.160.0 | GPT-6 Luna | 37.2 |
| GitHub Copilot | GitHub Copilot CLI 1.0.91 | GPT-6 Luna,由Auto引导 | 26.9 |
| Cursor | Cursor 3.23.23桌面应用 | Grok 4.7 | 50.8 |
| Google Antigravity | Antigravity CLI 1.3.1 | Gemini 3.8 Flash(高) | 53.6 |
代理特定指南
下面的每个指南将上述步骤应用于一个工具和一个二维码任务。
- 将IronQR与Claude Code结合使用用于品牌营销代码,解码徽标、颜色、边距、尺寸和错误校正的每种变体
- 将IronQR与ChatGPT Codex结合使用用于并行解码扫描和拍摄图像的积压,方便
ReadAsync,并报告每个失败 - 将IronQR与GitHub Copilot结合使用将验证代码盖在现有PDF页面上,包括受密码保护的文件,在文档管道中
- 将IronQR与Cursor结合使用用于从客户照片中用正确的扫描模式、二维码类型和角点读取代码,根据保持其他QR库在外的规则
- 将IronQR与Google Antigravity结合使用用于Blazor服务器扫描页面,在服务器上解码上传并在真实浏览器中进行检查
故障排除
- 运行时复制异常如果机器学习DLL未从运行时文件夹中复制出来
- 在IronQR中应用许可证密钥
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。