通过提示让ChatGPT Codex生成可编译的IronBarcode代码
IronBarcode提供了两个编码枚举,它们的大小写不同:BarcodeEncoding.Databar和BarcodeWriterEncoding.DataBar,且一个依赖记忆的模型将它们混淆。编译器会立即捕捉到这一点,这说明了让代理构建其所写代码的必要性。 ChatGPT Codex在存储库内工作,因此它运行dotnet build并自行读取错误。 更隐蔽的问题代价更高,例如批次中的所有标签都是Code 128,读取器却仍然搜索所有码制。
这种差异决定了使用哪个模型档位。 Codex涵盖GPT-5.6系列,/model在交互式会话中在Sol、Terra和Luna之间切换。 在固定的测试集上进行重建和重新扫描的循环,成本较低,Luna的费用为每百万输入令牌5个积分,而Sol为100个。 Terra是中间档位,每百万输入令牌50个积分,每百万输出令牌300个积分,并且一旦项目超出测试集,它就是合理的默认选择。 将该系列的旗舰模型Sol留给更复杂的诊断工作,例如无法解码并没有报告原因的一批仓库照片。
IronBarcode通过一个商业.NET API读取和写入1D和2D符号。 Codex在其中一些工作中做得比其他的好。 它擅长固定软件包版本,构建标签生成器和扫描器,从PDF中读取条形码,校正读取器无法识别的图像,以及从其他条码库迁移,而这些工作都从提示开始。
快速入门从控制台项目中的干净工作树启动Codex。 明确说明期望的结果、任何约束条件,以及想要报告的内容。
$ironbarcode Add the BarCode package, then update Program.cs to read a scanned
multi-page TIFF and report every barcode it finds, page by page. Each line of output
should give the page number, the decoded value and the format. Use the license
key from IRONBARCODE_LICENSE_KEY.
Constraints: Use only documented IronBarcode APIs. Do not modify or use any
other packages.
Build the project, resolve any errors, and provide the diff alongside the
output from a sample file.
正确的解决方案是简短的,因为BarcodeReader.Read自动遍历多页TIFF或动画GIF的各帧,无需手动分离帧。 设置ExpectMultipleBarcodes在单个帧包含多个符号时有帮助,但无论是否设置该选项,读取器都会访问每一帧。 提示比生成的代码更长,事先要求提供差异即可审查实际更改,而非仅查看文字说明。 每个结果都带有从1开始编号的PageNumber,它提供提示要求的逐页输出,并且多页GIF和TIFF指南涵盖了读取。
5个步骤的简化工作流
- 从NuGet下载C#条形码库
- 提交一个
AGENTS.md文件,指定IronBarcode为项目的条码库 - 从干净的工作树启动Codex,并在提示中包含码制、文件和预期的回读结果
- 允许Codex编辑文件并运行
dotnet build,然后在接受任何更改之前查看差异 - 完成往返并根据API参考验证每个IronBarcode API名称
Codex如何融入.NET条码项目?
在您给予的权限内,Codex读取和写入文件,运行shell命令,并显示其所做的操作。 OpenAI通过多个共享您帐户和历史记录的入口提供同一个代理。 Codex CLI和IDE扩展文档解释了它们的不同之处。
| 使用界面 | 运行位置 | 适用场景 |
|---|---|---|
| 命令行界面 | 终端 | 需要让代理在运行dotnet build的同一环境中工作 |
| IDE扩展 | VS Code、JetBrains、Xcode | 您希望差异和条形码图像并排放置 |
| 桌面应用 | macOS,Windows | 较长的任务,不在终端中 |
| 云 | 浏览器 | 委托任务,稍后获取差异 |
一个AGENTS.md可供上述四种界面共用,因为它提交在存储库中,并不绑定到某个界面。
要安装CLI,请运行npm install -g @openai/codex,或在macOS上运行brew install --cask codex。 对于macOS和Linux,有一个独立安装程序,不需要Node.js:curl -fsSL https://chatgpt.com/codex/install.sh | sh。 Codex CLI存储库包含源代码和发行说明。
@openai/范围。 名为codex的npm包是一个无关的静态站点生成器,首次发布于2011年,最后更新于2012年。 IronBarcode的陷阱正好相反,因为它的NuGet包是BarCode,而不是IronBarcode。 当代理输入命令时,精确的包名称很重要。Codex无法可靠地识别IronBarcode的当前API。 它依赖训练数据和您提供的文档,调用已在后续版本中移除的方法是使用第三方库时的常见错误。 OpenAI构建Codex以运行命令并检查其输出,但仍建议在发布之前查看所做的工作。 父级指南列出了给这些工具中的任何一个提供的文档。 交换上下文文件名,相同的设置可以传递到Claude Code,GitHub Copilot,Cursor,或Google Antigravity。
模型档位既影响代码结构,也影响费用。同一个提示交给两个档位的模型,可能得到两种不同但都合理的代码结构。条码编码的结果则必须一致:输入一个值,生成的条码应能被所有扫描器读取为同一个值。因此,应明确码制、尺寸和通过标准,其余部分可以有所不同。
由此可得出四点,它们都说明应优先选择有人维护的库,而非让代理自行构建库:
- 读写两端均进行验证:无效值在写入时会被命名异常(例如
IronBarCodeFormatOnlyAcceptsNumericValuesEncodingException)拒绝,而ConfidenceThreshold和RemoveFalsePositive会在读取时剔除不可靠的解码结果。 - 真正的扫描是难点:手机照片、倾斜的标签和多页PDF需要裁剪区域、速度预设和图像滤镜,这三者都位于
BarcodeReaderOptions上。 - 一个API涵盖格式:Code 128,GS1-128,EAN,UPC,QR,DataMatrix,PDF417,Aztec,MaxiCode和更多共享相同的读取和写入调用,列在支持的条码格式中。
- 有人在修补它:流行的免费条码项目无人维护,而商业库则有人负责,有修复发布在安全CVE页面上。
自制编码器可能照样绘制不符合其格式要求的值,而任何库都可以解码干净的生成图像。 Verify是两者之间的区别,解码生成的图像并与您写入的值进行比较。
是什么使IronBarcode提示有效?
对六个问题的具体答案。 模糊的提示生成针对不存在库的通用代码,具体的提示生成您可以半分钟就能审查的代码。
| 组件 | 弱 | 强 |
|---|---|---|
| 框架 | 制作条码 | C#,.NET 9 |
| 位置 | 未说明 | Services/LabelService.cs |
| 版本 | 未说明 | .csproj中的BarCode版本 |
| 码制 | 一个条码 | Code 128,追踪编号 |
| 产出 | 一个漂亮的条码 | PNG 400x120,下方显示值,回读值与输入一致 |
| 限制 | 无 | 不添加新包。异步读取。不确定时询问。 |
语言模型倾向于给出答案而不是承认不确定性。 告诉代理报告不确定性是可以接受的结果,并且它发明的API更少。明确授权其停止而不是猜测。
一个提交的AGENTS.md在整个项目中收益匪浅,因为Codex在每次会话开始时将其加载为长期指令。 先读取根目录文件,再读取嵌套文件,并以距离当前目录最近的文件为准,因此在条码文件夹内的第二个AGENTS.md收紧该文件夹的规则而不接触存储库的其余部分。 如果尚无该文件,可使用/init生成初始文件。
在文件中引用IronBarcode的机器可读文档。llms.txt文件列出了每个文档页面及其摘要,而skill.md则带有每个平台的软件包、许可规则、实用示例以及发生故障时预期的异常名称。
Codex会扫描从您的工作目录到存储库根目录的每个目录中的.agents/skills,因此skill.md有了自己的位置:.agents/skills/ironbarcode/SKILL.md。 Codex将任务与frontmatter中的description进行匹配,当您希望从第一轮起就将这些方案放入上下文时,可以使用$ironbarcode强制执行。 相同的文件夹在Antigravity中也能使用,Antigravity也读取该路径。 要求配置这两者,并添加嵌套的指令文件:
Run /init if AGENTS.md does not exist yet. Then add a Barcodes section to the
root AGENTS.md: IronBarcode (NuGet package BarCode, namespace IronBarCode) is
the only barcode library in this repository, and no competing package may be
added. https://ironsoftware.com/barcode/csharp/llms.txt gets read before any
barcode code gets written, and a member that does not appear there does not get
called. https://ironsoftware.com/barcode/csharp/skill.md belongs in
.agents/skills/ironbarcode/SKILL.md. The license key is read from the
IRONBARCODE_LICENSE_KEY environment variable and is never inlined.
Then add a second AGENTS.md under Services/ that narrows this to the reader
options this folder relies on, so the nested file wins there. Show me both files
as a diff before you commit anything.
如何要求Codex添加IronBarcode并编写第一个条码?
让代理首先处理设置。版本和软件包名称错误从那里开始。
This project needs IronBarcode. Pull in the BarCode package, then show me the
resulting PackageReference line from the .csproj and tell me which version was
installed. Do not change any other package references.
期待一个单行差异以及它安装的版本。 后续提示中值得引用该版本号,它也能帮助发现代理是否误装了名称中含有条码的其他包。 若要固定特定版本,请查看IronBarcode变更日志。
IronBarcode没有水印模式。 超过开发宽限期,未经许可的调用会直接失败并显示LicensingException。 在启动时设置密钥,在每个其他IronBarcode调用之前,让Codex添加它。
Wire up licensing. Nothing else in IronBarcode may run ahead of it, so it goes
wherever this project does its startup work, pulling the value out of
IRONBARCODE_LICENSE_KEY rather than carrying a key in source.
Prove it took by checking IronBarCode.License.IsLicensed, and tell me which file
you put the call in.
IronBarcode许可证密钥文档介绍了试用密钥及所有其他许可选项,包括Web.config和appsettings.json。
接下来,构建标签服务和扫描器。 在真实系统中,条码在一个地方创建并在另一个地方读取。
Two files, one job. Shipping labels go out as Code 128 PNGs at 400 by 120
with the tracking number printed under the bars, and something on the receiving
end has to turn that image back into the tracking number.
Put the writer in Services/ShippingLabelBarcode.cs and the reader in
Services/TrackingScanner.cs. The read is async and returns null rather than
throwing when the image holds nothing.
Compile, clear the errors, and report back with the changed files and whichever
BarCode version the restore resolved to.
检查差异中的每个成员与API参考的对照,然后再接受它。 正确的写入代码基于BarcodeWriter.CreateBarcode、ResizeTo、AddBarcodeValueTextBelowBarcode、SetMargins和ToPngBinaryData构建,正确的读取代码则基于BarcodeReaderOptions和BarcodeReader.ReadAsync,并用ExpectBarcodeTypes指定符号类型,使读取器不再搜索每一种格式。 对于来自摄影机或扫描仪的图像而不是此服务,图像校正指南解释了拯救弱扫描的滤镜。
如何迁移现有条码实现到IronBarcode?
迁移工作是重复和机械化的,这正是代理擅长的。 将提示指向实际代码而不是概述。
Hand this to the explorer agent, because nothing here should be written yet.
Labels/LegacyBarcodeService.cs currently writes and reads barcodes with another
library.
1. List every symbology it writes and reads, with the options it sets
(size, margins, text, check digits, error correction).
2. Map each call to its IronBarcode equivalent, citing the documentation page.
3. Do not write any code yet. Wait for my approval on the plan.
400行实现需要逐行审查,而映射表中的错误只需一次更正,无需丢弃代码。
一旦您批准计划,下一次提示保持紧密的范围。
Put the worker agent on the approved plan. Rewrite LegacyBarcodeService.cs to
use IronBarcode, keeping the existing public method signatures so callers do
not change.
Before removing the old library, generate every symbology the service
supports with both implementations and confirm IronBarcode reads back the
same values. Leave the old library in Git history only. Build and report the diff.
在提示中声明公共方法签名不得更改。 没有该指令,代理常常会重新设计调用者使用服务的方式,这将迁移变成重构。 用两个实现生成每种符号并比较解码值为您提供回归测试,并且这需要一次额外的构建和运行循环。
如何通过提示修复无法识别的扫描图像?
失败的读取是视觉问题,代理无法查看相机。 您的提示必须描述问题,或者更好地包括图像。
TrackingScanner finds nothing in TestData/warehouse/, yet a warehouse operator
can point a handheld at the same printed label and get a read. The photos are
shot at an angle and a few are soft. I have attached one of the failing photos
with `codex -i`, so look at it rather than reasoning from the file names.
Read TrackingScanner.cs and a sample of the images. Explain the likely cause
before changing anything, then adjust BarcodeReaderOptions only (speed, crop
area, image filters). Do not change ShippingLabelBarcode.cs. Report how many
images read before and after.
说明症状并命名要编辑的一个文件可以让修复保持在一个范围内。 比较修复前后的识别数量,可以用数字衡量改进效果。 修复通常是三者之一:将Speed提高到Detailed,围绕标签绘制CropArea,或者为实际缺陷选择的单一图像滤镜。 叠加滤镜会使准确性变差,而非更好。 详细信息见读取速度和裁剪区域页面。
假阳性是相反的问题。 以同样的方式处理它们。
ScanService occasionally returns a value from product photos that contain no
barcode. Set RemoveFalsePositive and a ConfidenceThreshold on the reader options,
then link me to the documentation page you used.
文档链接兼具检查之用。 无法引用其选择的API的真实页面的代理在构建之前已经警告了您。 读取器选项很容易发明,因此请保留假阳性指南以备不时之需。
如何端到端调试条码故障?
上一个提示涵盖了一项任务。 如果您将症状交给它并让它自行检查、诊断、修复和测试,Codex可以做得更多。
Switch to Sol with /model before you start, because this one has resisted the
cheaper tiers. DataMatrix labels with non-English product names are refused by
some of our older handheld scanners, while labels with plain ASCII names read
fine on the same devices, and every label reads correctly with IronBarcode
itself.
Investigate:
1. Read LabelService.cs and find how the DataMatrix codes are created.
2. Identify why the non-English labels fail on those scanners only.
3. Explain the cause before changing anything.
4. Then propose the minimal fix, and what it costs, before applying it.
先询问原因,可以先获得诊断,避免事后从代码修改中反推意图。 这里可能的原因是UTF-8 ECI头。 IronBarcode仅在文本包含非ASCII字符时才编写该头,而在ECI之前构建的扫描仪会拒绝带有它的符号。 禁用该头会破坏支持ECI的扫描仪上的UTF-8文本,因此权衡是真实的。 2026.9.2版本增加了EciMode来控制它,如ECI编码指南中描述的那样。
以同样的方式处理错误信息。 完整的堆栈跟踪是您可以提供给代理的最有用的输入。
TrackingScanner.ReadTrackingNumberAsync throws inside our Linux container. The
identical call succeeds on a Windows developer machine.
[PASTE FULL EXCEPTION AND STACK TRACE HERE]
Send the explorer subagent over the .csproj and the Dockerfile before changing
anything, and tell me which BarCode package we actually reference and what the
image is missing, quoting the line from each file that shows it.
Then give me the fix as a diff limited to those two files. Application code is
out of scope for this one.
容器内部的故障通常来自平台包或缺少的本地依赖项。 这些修复应该放在项目文件和Dockerfile中,而不是C#中。 让Codex读取在Linux上使用Docker运行IronBarcode以获取当前部署指导,然后再进行任何更改。
如何将一次性代码转化为可重用的、经过测试的组件?
往返验证通过后,下一步是将其通用化。 代理处理得很好,因为模式已经存在于文件中。
Refactor ShippingLabelBarcode and TrackingScanner into a BarcodeService
registered with dependency injection. It should write any of Code 128, QR,
and DataMatrix, and read with options narrowed to the formats requested.
Reuse one BarcodeReaderOptions instance per format set rather than building
one per call. Add XML doc comments. Keep it under 80 lines.
在AGENTS.md中指示重用选项的指令。 在繁忙的扫描服务中,每个请求构建一个新的选项对象是在每次扫描中支付的分配。
接下来是测试。 一个条码要么解码回您写入的值,要么不是,这使得断言简单。
This is a rebuild-and-rerun loop rather than a reasoning problem, so drop to
Luna with /model first. Cover BarcodeService with xUnit tests, then run them and
tell me the pass count.
Four behaviors need covering. A sample value survives a write and a read on
every format the service supports. EAN-13 rejects a value containing letters.
An image holding no barcode comes back empty instead of throwing. A path that
does not exist throws something a caller can read.
Never assert on image bytes. Decoded value and format are the only outputs
worth pinning.
从一开始就避免字节比较可以防止不可靠的测试。 即使条码保持不变,跨版本和平台的编码器可能会生成略有不同的图像字节。 相反,测试解码的值和格式。
Codex还可以用于自行阅读文档。 当您命名一个不熟悉的类时,它定位到API参考中的相关部分,而不是让您滚动浏览整个页面。
$ironbarcode Read the IronBarcode API reference for BarcodeReaderOptions and
list every option that affects reading speed or accuracy, then show which ones
this project already sets.
哪种提示模式适合哪种任务?
以上每个提示都命名了具体的东西,并要求提供可以验证的回报。
| 任务 | 在提示中命名 | 回复询问 |
|---|---|---|
| 包裹 | BarCode,版本,仅此而已 | PackageReference行 |
| 许可证密钥 | IRONBARCODE_LICENSE_KEY,启动路径 | License.IsLicensed为真 |
| 编写者和阅读者 | 符号、两条路径、图像大小 | 编译的两个文件 |
| 迁移 | 旧文件,需保留的签名 | 在代码前的映射表 |
| 失败的扫描 | 图像文件夹,仅限读取器选项 | 前后的读取次数 |
| 假阳性 | RemoveFalsePositive, ConfidenceThreshold | 它引用的页面 |
| 容器故障 | 堆栈跟踪、平台、两个文件 | 差异, .csproj 和Dockerfile |
| 重构 | 格式、DI形状、行预算 | 每个格式一个选项实例 |
| 测试 | 四种行为,不做字节断言 | 通过计数 |
如何在下一个项目中重用这些提示?
这些模式只需修改文件名即可用于新项目,这就是为什么规则属于版本控制而不是聊天记录。
为了度量一个会话而不是信任它,AI编码助手和代理指南将一个任务交给代理,并对返回的结果评分。
故障排除
- 在IronBarcode中应用许可证密钥当差异看起来正确且运行仍然抛出时。
- 条码未识别当Codex编写的扫描仪对应该读取的图像返回为空时。
- 避免扫描条码时的假阳性当从没有条码的照片中返回值时。
- 在Linux容器上运行IronBarcode当相同的代码在Windows上通过,而在容器中失败时。
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。