如何使用 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# QR Code程式庫
- 將 IronQR 的技能儲存為
.agents/skills/ironqr/SKILL.md以使$ironqr得以解析 - 提交一個
AGENTS.md,附上版本庫的 QR 解碼規則 - 一次請求一種模式(依序、
Parallel.ForEach,然後是SemaphoreSlim)並將每個結果文件與最後一次比較 - 在API 參考資料中查找 Codex 使用的每個成員,並將最終的結果文件與您的真實資料相較
什麼是 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)與 Micro QR 和 rMQR 分開,因此驗證器可以拒絕不是資產標籤的標籤。
如何撰寫 IronQR 提示並設置 Codex 以供使用?
有效的 IronQR 批次提示有六件事。 就此積壓而言,輸入為 Backlog/images/ 中的每個 PNG 和 JPEG,SemaphoreSlim 由 --concurrency 選項設置並發數,輸出為每個文件一行的 out/pipeline.csv。拋出錯誤的文件會獲得一行,而批次繼續。 證明是與 out/sequential.csv 的逐行匹配,且限制是不允許新軟體包且默認為 Auto。
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 套裝引入 IronQR.Slim 以供管理 API 使用,Microsoft.ML.OnnxRuntime 發現和 Windows 原生讀取器。 單靠 IronQR.Slim 的專案,於 Windows 還需 IronSoftware.ReaderInternals.Windows,仍然使用基本掃描進行讀取,但無法運行偵測模型。 軟體包是 IronQR,帶有大寫 R,而命名空間是 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 中,使用區塊包裹的東西在退出時拋出 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 編譯為非同步 void,因此迴圈在讀取完成前返回,結果文件出現短缺。 與順序文件的比較捕捉到這個。
如何使用 ReadAsync 限制並行讀取?
一個並行循環每讀取阻塞一個線程。 在 SemaphoreSlim 後的 ReadAsync 維持固定數量處於飛行中的讀取,並釋放呼叫線程,為高容量批次提供了非同步指南給出的模式。 它接受 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.
兩種模式讀取每個乾淨掃描和傳真副本,且每個錯失間幾個手機照片。 只有基本通過讀取的照片,偵測模型找到代碼但無法解碼,所以 Auto 從未恢復。 使用 QrScanMode.OnlyBasicScan 重試空文件恢復了每張照片。
如何驗證解碼的值並報告失敗?
批次遇到三種失敗,每個在代碼中看起來不同。
| 輸入 | 結果 | 狀態 |
|---|---|---|
| 空白、被截斷或非圖像文件 | 圖像載入在 IronQR 運行前拋出 | 不可讀 |
| 無代碼,或損壞超過錯誤校正 | 零長度集合,永不為空 | 空白 |
| 任何代碼,在僅偵測模式中讀取 | 角點,空 Value,QrType 的 QrEncoding.None | 空白,非解碼 |
第三行是危險的。 我們的第一個順序解碼器會將其計算為解碼,因為它只檢查是否有任何結果返回。
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 列出了結果的四個成員,並追蹤 Decoded 從工作經由解碼函數到返回的驗證器行。
如何在另一圖像文件夾上重用這些提示?
更改路徑,然後上面每個提示按寫法運行。 AI 編程助手指南從頭到尾運行單次接受提示,並發佈結果。
在實際運行中,這些提示產生了什麼結果?
我們按順序將上面每個提示發送到 Codex 中,在一個線程中,針對一個範例存儲庫。 它持有一個控制台應用程式和 301 張圖像(乾淨掃描、手機照片、傳真副本、損壞的標籤、空白首頁、Micro QR 擱板標籤、無效標籤和六個不是圖像的文件),每一個預期狀態和值有具體的清單。 會話後,我們在 Release 中重建了專案並執行測試。 我們也獨立解碼每個圖像以檢查下列結果。
- 基本掃描重試將解碼從 256 提升到 264。在此之前,每模式解碼 256 中的 301,其中 16 個文件在兩者間有差異。
- 乾淨掃描在 Auto 下花費中間值 360 ms,而基本掃描耗時 35 ms,於上限 2 中在 7 秒內運行整個積壓。
- 順序解碼器在 71 秒內記錄 256 解碼,39 空白和 6 不可讀。
- 並行模式在 60 秒內於 32 線程寫下相同的 301 行,而在上限 2、8 和 32 網管分別以 55、66 和 68 秒寫下它們。
- 在快速啟動中,12 行中的 9 行被解碼,2 行返回空白及一份零位元組文件拋出。
- 驗證與清單匹配,有 240 解碼,31 空白,8 符號錯誤,8 格式無效,8 檢查數字錯誤及 6 不可讀。
- 失敗報告持有 61 條記錄,每失敗文件一條。
- 重構後,64 行工作在 301 中的 301 行匹配上清單,6 於 6 測試通過,於 Release 中再次。
- 所有 16 提示在每個建構運行且未進行人工代碼編輯。 提示 13 到 16 達到免費計畫使用限制,之後登進 Codex 並於相同線程中恢復。
- 在調查提示之前,我們新增一個夜間工作並插入錯誤,其中的日誌和間隙清單。Codex 在照片 JPEG 上找到了僅偵測模式並發現了接受任何結果的成功檢查。
Codex的版本、模型、計時和這次運行的測試機反應在其共享的運行記錄中。
疑難排解
- 非同步及多線程若並行運行寫入行數小於圖像數
- 在 IronQR 中應用授權鍵若結果文件中的每行顯示相同的授權失敗
- 用掃描模式讀取 QR 碼若結果返回帶有角點且無值
- 運行時複製例外,若偵測模型在發佈後無法加載
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。