如何使用 IronQR 與 Cursor
ZXing.Net 是 ZXing 條碼程式庫的開源 .NET 移植版。 當您要求 AI 代理提供從顧客照片中讀取 QR 代碼的 C# 程式碼時,即使您指定使用 IronQR,它可能還是會應用 ZXing.Net 的約定,例如比較 Result.Text、篩選 QR_CODE 格式,或在 using 語句內包裝 QrImageInput。 在 IronQR 2026.10.1 中,以那種方式處置輸入會拋出 NotImplementedException。
Cursor 是基於 VS Code 程式碼庫的 AI 程式碼編輯器。 它生成 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# QR Code程式庫
- 在
.cursor/rules中提交一個.mdc規則,命名 IronQR 並連結其文檔 - 列出規則替換的 ZXing.Net 和 QRCoder 習慣
- 每次請求中提到閱讀器檔案和真正顧客照片的文件夾
- 將每個解碼的序列與已知清單進行比較
您應該使用哪個 Cursor 模型來進行 QR 代碼工作?
Composer是Cursor自己的代理模型。 模型選擇器還提供了Cursor共同開發的SpaceXAI的Grok模型以及來自OpenAI、Anthropic、Google和其他實驗室的模型。 下面的測試運行使用了Grok 4.7。
常規照片工作,如在索賠記錄中添加字段或重新運行照片文件夾,適合快速型號。 當一批照片因不明原因停止解碼時,切換到需要更長時間推理的模型。 模型以不同方式讀取請求,因此請在每次請求中命名照片文件夾和輸出應匹配的序列。
如何向 Cursor 提供 IronQR 文檔?
將 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 解碼調用 | QrReader 與 Read,返回每個代碼 |
Result.Text | QrResult.Value |
QR_CODE 格式檢查和篩選 | 在閱讀之後檢查 QrResult.QrType |
| 更深度的掃描選項 | 輸入的掃描模式 |
Result.ResultPoints,模式中心 | QrResult.Points,四個角 |
| QRCoder 的生成器 | QrWriter.Write 及其保存調用 |
ZXing.Net 的 BarcodeFormat 列舉型沒有 Micro QR 或 rMQR 成員,其說明檔中列出了 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.
修正計劃中錯誤的內容,然後點選建置,或者在代理中發送下一個請求。
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 不返回任何值。 全框照片容易遇到這種情況,貼紙寬約 110 像素,在 4000x3000 框架中。 檢查代理的修復是否在沒有值時重試 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 的 AI 程式碼助理指南從頭到尾跑了一個 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 專案及已知序列的 12 張索賠照片。 規則、電纜標籤照片及全框照片在使用它們的提示之前立即被添加。 授權金鑰僅設置在環境中。 運行後,來自遷移的每個提交的新 Release 版本重新閱讀照片文件夾並複製了 IronQR 閱讀器的匹配計數及下述測試結果。
- ZXing.Net 閱讀器匹配了 12 張索賠照片中的 8 張。在轉移到 IronQR 之後,則是 12 張中的 12 張。
- 以每個掃描模式讀取一次,claim-0004 在 Auto 和 OnlyBasicScan 下給出了兩個有值的代碼,但在 OnlyDetectionModel 下為兩個空值結果。
- rMQR 更改讓索賠照片在之前和之後都是 13 張中的 13 張。
- 在修復之前,Auto 解讀了 4 張全框照片中的 0 張。 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 張索賠照片中的所有和 4 張全框照片中的所有。 - 每個 Release 構建中有 0 個錯誤,不需人工編輯。
- 並非每步都按照此處所寫的運行。 提示是手動發送的,提及被粘貼為文字,代理通過查找名稱找到了規則文件。 批准計劃是通過發送下個提示而從未點擊過建置,專用代理提示在代理模式下本地運行。
運行記錄保有包的版本、模型、時間和每個指南的測試機器。
疑難排解
- 當生成的程式碼拋出授權例外時,在IronQR中應用授權金鑰
- 當照片返回位置但沒有值時,使用掃描模式讀取QR碼
- 當Micro QR或rMQR序列丟失時,QR碼類型指南
- 在選擇
IronQR、IronQR.Slim和平台套件時,IronQR NuGet套件
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。