如何使用IronQR与ChatGPT Codex
QR码积压通常以无序文件夹的形式到达,其中包含扫描的资产标签、现场手机照片、传真副本、扫描仪错误产生的零字节文件,以及没有代码的封面。 一个天真的循环逐个处理文件,在遇到第一个损坏的文件时停止,并且不跟踪哪些图像失败或失败的原因。
ChatGPT Codex是OpenAI的编码代理。 它在终端、IDE、ChatGPT桌面应用程序和云中运行,全部通过单次ChatGPT登录。 IronQR是Iron Software的.NET QR码库。
每个提示指示Codex执行任务,并生成一个结果文件,每个图像对应一行。 由于批处理作业可能会处理没有结果的文件,本指南引用的所有计数都来自这些结果文件,如提示中所示。
快速入门在包含您的图像文件夹的.NET控制台项目中启动Codex,并指定批处理要求。
$ironqr Add the IronQR package to this console project, then make Program.cs
decode every file in Backlog/sample/ with QrReader.ReadAsync. Write
out/quickstart.csv with one row per file (name, decoded value or empty, QR
type, exception type if the file threw) and print the decoded, empty, and
threw counts by reading that CSV back. Load the key out of the
IRONQR_LICENSE_KEY variable. Call Dispose() on each QrImageInput yourself
instead of a using block, which throws in IronQR 2026.10.1. Run dotnet build
and dotnet run and fix whatever fails.
$ironqr提及在Codex编写代码之前加载IronQR的技能。
最小工作流程(5 个步骤)
- 从NuGet下载C#二维码库
- 将IronQR的技能保存为
.agents/skills/ironqr/SKILL.md,以便$ironqr可以解析 - 提交含有库的QR解码规则的
AGENTS.md - 一次请求一种模式(顺序、
Parallel.ForEach,然后SemaphoreSlim),并将每个结果文件与上一个进行比较 - 查找每个成员 Codex 使用的API参考,并将最终结果文件与您的参考依据进行核对
什么是ChatGPT Codex,它如何适应.NET QR码工作?
Codex在您授予的权限内工作。 它编写解码器、运行图像、读取输出并修正代码。 从Codex CLI存储库中使用npm install -g @openai/codex安装CLI,并查看Codex CLI文档以了解终端使用情况。
拥有基准的积压使得审查变得简单。 虚构的成员会导致构建失败,错误的解码会以与Backlog/manifest.csv不一致的行显示。
代理可以以不同的方式组织每个批次,但解码器必须在任何线程计数下都返回相同的给定图像的值。 这种一致性属于库,IronQR覆盖了积压需要的部分。
- 在一次调用中处理照片和扫描件:
QrScanMode.Auto模式运行检测模型,当模型未找到时,重试基本扫描。 扫描模式指南将其与两种单次传递模式进行比较。 - 每个结果的符号类型:
QrResult.QrType将标准QR (QrEncoding.QRCode) 与微型QR和rMQR分开,因此验证器可以拒绝不是资产标签的标签。
如何编写IronQR提示并设置Codex?
有效的IronQR批处理提示涉及六个方面。 对于这个积压,输入为Backlog/images/中的每个PNG和JPEG,SemaphoreSlim根据--concurrency选项设置并发性,输出为out/pipeline.csv,每个文件一行。抛出错误的文件将得到一行,而批处理将继续。 证明是与out/sequential.csv的逐行匹配,约束是不新增包,默认自动。
OpenAI的幻觉研究发现训练和评估奖励猜测,而在批处理作业中,猜测通常是关闭摘要中的总计。
Codex在库的.agents/skills文件夹中发现技能,每个技能都是一个文件夹,其中包含一个带有前言名称和描述的SKILL.md。 将IronQR的skill.md保存为.agents/skills/ironqr/SKILL.md,以便解析$ironqr提及。 当任务与描述匹配时,Codex也可以在没有提及的情况下选择技能。
AGENTS.md携带每个会话开始的规则。 Codex从存储库根目录到启动它的文件夹中的每个目录中读取最多一个这样的文件,更深的文件会覆盖其上的指导。 /init命令起草一个。 下面的提示还将IronQR的llms.txt索引命名为API参考。
Create the repository's AGENTS.md with a section titled QR decoding. It
should say that IronQR (package IronQR, namespace IronQr) is the only QR
library here, that the ironqr skill in .agents/skills/ironqr/ and IronQR's
llms.txt documentation index are the API references, that the key is read
from IRONQR_LICENSE_KEY and never printed or written to a file, that
QrImageInput is disposed with an explicit Dispose() call and never a using
block, that Backlog/manifest.csv is ground truth and read-only, and that any
count, rate, or timing you report must come from a per-image results file
written in the same turn, named in your reply.
如何让Codex添加IronQR并解码第一个文件夹?
Show me the IronQR PackageReference in AssetBacklog.csproj and the installed
version. Then run dotnet list package --include-transitive and quote the lines
for IronQR.Slim and Microsoft.ML.OnnxRuntime, since the detection model
depends on them. Change no package references.
IronQR包引入了用于托管API的IronQR.Slim,用于检测的Microsoft.ML.OnnxRuntime,以及Windows本地阅读器。 仅在IronQR.Slim上的项目在Windows上还需要IronSoftware.ReaderInternals.Windows,仍用基本扫描读取,但无法运行检测模型。 该包是IronQR,第一个字母是大写,而命名空间是IronQr,因此using IronQR指令无法编译。固定发布前请检查IronQR变更日志。
IronQR不增加试用水印到读取中。 未授权的第一次读取会引发LicensingException,信息是'需要生产许可证',并且ReadAsync异常在任务等待时表面。 在批处理中,这将导致每个图像一个相同的失败行。
Move the license setup into a Startup.ApplyIronQrKey method called first in
Program.cs. If IRONQR_LICENSE_KEY is unset or License.IsLicensed is false,
exit with code 2 and one clear line on stderr before any image is opened,
because IronQR throws on the first read instead of degrading. Run the program
once as is and once with the variable removed for that single command, and
report both exit codes and what IsLicensed returned.
许可证密钥页面介绍了IronQR读取的试用密钥和配置文件。 异常类型是IronQr程序集的内部类型,因此按类型捕获LicensingException无法编译,错误代码为CS0122。
接下来是一个顺序解码器,其结果文件成为每个更快模式的参考。
Create Services/BacklogDecoder.cs with DecodeAsync(string path) returning an
ImageOutcome record: file, status (Decoded, Empty, Unreadable), values, QR
types, exception type and message, and milliseconds. Open the file with
AnyBitmap.FromFile, read with QrScanMode.Auto, and never let one file stop
the batch. Add a --sequential mode that runs it over Backlog/images/ one file
at a time, writes out/sequential.csv, and starts out/runs.csv with the mode
and wall time. Report the status counts and the wall time from those files.
如何使用IronQR并行解码文件夹?
异步和多线程指南将每次迭代调用单独的读取器视作安全默认选项,因为IronQR不保证共享实例的线程安全性。 下一个提示让Codex的内置资源管理器代理(一个重读代理用于代码库探索)在任何并行运行之前检查文档。
Ask the explorer agent to answer this without editing anything. Before the
decoder goes parallel, list every QrReader, QrImageInput, and AnyBitmap that
BacklogDecoder creates or keeps, say which could be shared across threads,
and back each answer with a quote from
https://ironsoftware.com/qr/csharp/how-to/async-multithreading/ or the
ironqr skill. Flag anything the documentation leaves unstated.
在校准中,通过32个线程共享一个阅读器产生了与每个文件一个阅读器相同的结果。未来版本可能有所不同,而每个文件一个阅读器几乎没有成本。
输入对象也需要注意。 在版本2026.10.1中,围绕它的using块即使在成功读取后退出时也会抛出NotImplementedException,因此批处理会将每个良好的图像记录为失败。 审查每个差异以一种方式进行。
对于并行版本,提示命名内置的工作代理,它在自己的线程中执行编辑。
Have the worker agent add a --parallel mode with Parallel.ForEach,
MaxDegreeOfParallelism from a --threads option (default
Environment.ProcessorCount), and a new QrReader per file. Use the synchronous
Read inside the loop body, since Parallel.ForEach does not await an async
lambda. Write out/parallel.csv sorted by file name, then compare its status
and value columns with out/sequential.csv and fix any row that differs
before you finish. Append mode, thread count, and wall time to out/runs.csv.
传递给Parallel.ForEach的异步lambda编译为async void,因此循环在读取完成之前返回,结果文件少。 与顺序文件的比较抓住了这一点。
如何使用ReadAsync限制并发读取?
并行循环为每次读取阻塞一个线程。 ReadAsync在SemaphoreSlim后面的代码保持固定数量的读取在进行中并保持调用线程空闲,这是异步指南给出的高容量批次的模式。 它接受IQrInput,且没有文件路径的重载,因此每个任务仍会打开自己的位图。
Add a --pipeline mode: Task.WhenAll over every file, each task waiting on a
SemaphoreSlim sized by --concurrency and awaiting ReadAsync. Run it at
concurrency 2, 8, and Environment.ProcessorCount, writing
out/pipeline-c<N>.csv for each and appending to out/runs.csv. Confirm each
file matches out/sequential.csv row for row, then tell me which setting was
fastest according to runs.csv.
检测模型已经在多个核心之间散布一次读取,因此更高的限制不需要更快。 让runs.csv为您的硬件选择限制,并保持信号量的可靠性,即限制内存使用。
批次应该使用哪种扫描模式?
检测模型读取基本通过错过的照片,并且它也占据了每次读取大部分时间。
Measure what the machine learning detector costs on this backlog. Run the
pipeline at the fastest concurrency from runs.csv, first under
QrScanMode.Auto and then under QrScanMode.OnlyBasicScan, writing
out/mode-auto.csv and out/mode-basic.csv with per-image milliseconds. Join
both with the category column of Backlog/manifest.csv and report decoded
count and median milliseconds per category for each mode. If either mode
reads files the other misses, keep Auto as the default and build a single
OnlyBasicScan retry of its Empty files into the decoder for every later run.
Rerun to out/mode-fallback.csv and count the recoveries.
两种模式读取每个干净扫描和传真副本,并且错过了不同数量的手机照片。 仅在基本通过读取的照片上,检测模型定位了代码而无法解码,因此自动从未回退。 用QrScanMode.OnlyBasicScan重试空文件恢复了每张照片。
如何验证解码值并报告失败?
批处理遇到三种类型的失败,每一种在代码中看起来不同。
| 输入 | 结果 | 现状 |
|---|---|---|
| 空,截断或非图像文件 | 在IronQR运行之前图像加载抛出 | 不可读 |
| 无代码或错误修正后的损坏 | 一个空集合从不为null | 空 |
| 任何代码,读取在仅检测模式下 | 角点,空Value,QrEncoding.None的QrType | 空,未解码 |
第三行是危险的。 我们的第一个顺序解码器会将其计为解码,因为它仅检查任何结果是否返回。
Backlog/README.md defines a valid asset tag. Add Services/TagValidator.cs and
apply it after each read: a decode only counts when the symbol is a standard
QR code (QrEncoding.QRCode), the value matches the documented pattern, and
the Luhn check digit holds. Give the others the statuses WrongSymbol,
InvalidFormat, or BadCheckDigit. Rerun the pipeline to out/validated.csv and
list every file whose status disagrees with expected_status in the manifest.
校验位是您数据的一部分,因此IronQR无法验证它。 读取内部的Reed-Solomon校正,它被校验和和容错指南描述,只能证明符号解码,结果不带有置信属性。 标错的校验位的标签扫描正常但仍然无效。
IronQR的错误消息指南展示了下一个提示应用于整个积压的逐文件日志模式。
Every file that is not Decoded needs a recorded reason. Write one JSON line
per file to out/decode-log.jsonl (file, status, exception type, message,
milliseconds), send IronQR's own log to out/ironqr-debug.log through
IronQr.Logging.Logger, and generate out/failures.md from the JSONL only: one
section per status other than Decoded, a count, and every file name. Then
check the section counts against out/validated.csv.
在2026.10.1版本中,IronQr.Logging.Logger日志记录每次读取采用的扫描路径,例如使用机器学习模型的检测扫描。 因为报告仅从JSONL构建,所以解码器从未记录的失败以与结果文件不一致的计数显示。
如何诊断无法解码的图像?
Codex可以查看图片。 启动会话时附加文件与codex --image或粘帖到撰写者中。
I attached IMG_0018.png from Backlog/images/ with codex --image. The pipeline
marks it Empty. Look at the picture and tell me whether it is a damaged code,
a page with no code, or a capture problem a rescan would fix. Then test your
answer: read it with all three QrScanMode values and write
out/retry-IMG_0018.csv. Do not change the pipeline.
在我们的运行中,该文件的所有三种模式都返回空值,在校准中,检测模型找不到定位。 代码本身已损坏,因此损失超出了错误修正恢复范围,另一次读取或重新扫描相同标签都不会改变这一点。 固定的解决方案是替换标签,如果您自己打印标签,则需要更高的错误修正级别。
如何从头到尾调试不正确的批处理输出?
Send the explorer agent into Jobs/NightlyImport.cs and Logs/nightly-2026-10-06/
before anything is edited. That run reported six unreadable files and no other
failure, yet Backlog/archive-index-gaps.csv lists assets the archive never
received. Find what the missing assets have in common, explain why the job
counted them as successes, and propose the smallest fix together with the
command that would prove it. Put the findings in out/nightly-diagnosis.md and
change no code.
在任何解决措施之前审批诊断结果。 好的诊断引用决定成功的那一行。 也要核对提议的修复与out/mode-fallback.csv。
如何将一次性代码转化为可重用的、经过测试的组件?
Put the worker agent on folding the modes into a BacklogJob class. Add the
Microsoft.Extensions.DependencyInjection package, register the job with it,
and configure it with a BacklogOptions record (input folder, concurrency,
scan mode, output folder). Keep the validator, the basic-scan retry, and the
logging in it, stay under 160 lines, and add XML doc comments. Before
finishing, run it over Backlog/images/ into out/final.csv and confirm every
row agrees with the manifest's expected_status and expected_value.
重构可以删除验证器、基本-扫描重试或逐文件阅读器而不会出现构建错误。 只有对基准结果的完全重跑才能捕捉到这一点。
Add an xUnit project, AssetBacklog.Tests, and cover BacklogJob with tests
that read real files from Backlog/images/: a clean scan decodes to its
manifest value, the zero-byte file comes back Unreadable without throwing, a
damaged image is Empty, a Micro QR label is WrongSymbol, a bad check digit is
BadCheckDigit, and a parallel run over 40 files matches a sequential one.
Assert on status and value. Run dotnet test and report the totals it prints.
清单修复状态和值,而计时从运行到运行变化。
在库中保留重复出现的 IronQR 问题。 OpenAI的自定义提示页面标记旧的~/.codex/prompts文件夹弃用了,取而代之是技能。
$ironqr Using the IronQR API reference, list every member of QrResult and say
whether IronQR reports a confidence or checksum score for a read. Then point
to the line in BacklogJob that decides a file is Decoded.
在我们的运行中,Codex列出了结果的四个成员,并跟踪了从作业到解码器到返回它的验证线的解码。
如何在另一图像文件夹上重用这些提示?
更改路径,并且上述每个提示将按写的那样运行。 AI编码助手指南从头到尾运行单次接受提示并发布结果。
在实际运行中这些提示生成了什么?
我们按顺序将上述每个提示发送到Codex,一个线程中,针对一个示例存储库。 它持有一个控制台应用程序和包括301个图像(干净扫描,手机照片,传真副本,损坏标签,空白封面,Micro QR货架标签,无效标签以及六个根本不是图像的文件)的积压,每个的预期状态和值清单。 会话后,我们在发布模式下重建项目并运行测试。 我们还独立解码每张图像以检查以下结果。
- 基本扫描重试将解码从256提升至264。在此之前,每种模式解码301中的256个,有16个文件在两者间不同。
- 在自动下一个干净扫描需要中位数360毫秒,在基本扫描下为35毫秒,整体积压在限制2下耗时7秒。
- 顺序解码器记录了256个解码,39个空和6个不可读在71秒内。
- 并行模式在32个线程中写下相同的301行,管道在55, 66和68秒内分别在限制2, 8和32下写下它们。
- 在快速入门中,12行中解码9行,2行返回空值和1个零字节文件抛出。
- 验证与清单匹配240个解码,31个空,8个错误符号,8个无效格式,8个错误检查数字和6个不可读。
- 失败报告包含61条记录,每个失败文件一条。
- 重构后,64行作业与清单在301行中匹配301行,6个测试中6个通过,再次在发布中。
- 所有16个提示都随着每个构建通过而运行,没有任何手动代码编辑。 提示13到16达到免费计划使用限制,在再次登录Codex后在同一线程中恢复。
- 调查提示前,我们添加了一个夜间作业,带有植入的故障、日志和差距列表。Codex发现的仅检测模式在照片JPEG上,成功检查接受任何结果。
Codex的版本、模型、计时和此运行的测试机器在共享的运行记录中。
故障排除
- 异步和多线程如果并行运行写的行少于图像
- 在IronQR中应用许可证密钥如果结果文件中的每行都显示相同的许可证失败
- 使用扫描模式读取QR码如果结果与角点一起返回但没有值
- 如果检测模型在发布后无法加载,则运行时复制异常
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。