Jak używać IronQR z Cursor

Curtis Chau
Curtis Chau
Zaktualizowano: 9 października 2026

ZXing.Net to open-source'owy port .NET biblioteki kodów kreskowych ZXing. Kiedy poprosisz agenta AI o kod C#, który odczytuje kody QR z fotografii klientów, może on zastosować konwencje ZXing.Net nawet jeśli określisz IronQR, takie jak porównywanie Result.Text, filtrowanie według formatu QR_CODE lub opakowanie QrImageInput w instrukcji using. W IronQR 2026.10.1, usunięcie danych wejściowych w ten sposób zgłasza NotImplementedException.

Cursor to edytor kodu AI oparty na bazie kodowej VS Code. To, czy generuje kod IronQR, czy tłumaczenie ZXing.Net, zależy od dwóch cech. Agent postępuje zgodnie z linkami w dokumentacji, które dostarczasz, i stosuje zasady projektu z .cursor/rules. Ten przewodnik demonstruje oba z usługą przyjmowania zgłoszeń gwarancyjnych, która wydobywa numery seryjne i linki do rejestracji z fotografii klientów, i przenosi tę usługę z ZXing.Net do IronQR. IronQR obsługuje symbole QR, Micro QR i rMQR.

Ten przewodnik skupia się na pisaniu kodu z Cursor. Szczegóły dotyczące opcji odczytu IronQR znajdziesz w przewodniku trybów skanowania, przewodniku typu QR i przewodniku wartości i współrzędnych.

Szybki start
NuGetInstalacja z NuGet

PM > Install-Package IronQR

Zainstaluj IronQR, wykonując powyższe polecenie w konsoli Menedżera Pakietów NuGet lub wyszukaj pakiet w Menedżerze Pakietów NuGet.

Otworzyć projekt przyjmowania zgłoszeń w Cursor i wysłać to żądanie z panelu Agenta.

@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.
Text

Trzymać klucz licencyjny z dala od wiadomości na czacie. Agent tworzy pliki i uruchamia polecenia terminala, więc wklejony klucz może trafić do kodu źródłowego, commitów lub logów. Przewodnik po kluczach licencyjnych zawiera listę obsługiwanych miejsc przechowywania.



Jaki model Cursor używać do pracy z kodami QR?

Composer to własny agentyczny model Cursor. Wybór modelu oferuje także modele SpaceXAI Grok, które Cursor współtworzył, oraz modele od OpenAI, Anthropic, Google i innych laboratoriów. Test przeprowadzony poniżej używał wersji Grok 4.7.

Rutynowa praca ze zdjęciami, taka jak dodawanie pola do rekordu zgłoszenia lub ponowne uruchamianie folderu ze zdjęciami, pasuje do szybkiego modelu. Gdy partia zdjęć przestaje być dekodowana bez wyraźnego powodu, należy przełączyć się na model, który dłużej analizuje. Modele odczytują żądania inaczej, dlatego w każdym żądaniu należy nazwać folder zdjęć i numery seryjne, które wynik powinien dopasować.

Jak przekazać dokumentację IronQR do Cursor?

Umieść link do dokumentacji IronQR w żądaniu lub trzymaj go w zatwierdzonej regule, aby nikt nie musiał go wklejać. llms.txt indeks łączy przewodniki i dokumentację API, a llms-full.txt podsumowuje 44 strony dokumentacji w jednym pliku. Od października 2026 r., menu @ Cursor łączy pliki, foldery, terminale, czaty, różnice Git i przeglądarkę, więc dokumentacja IronQR dociera do agenta jako link.

Enumy IronQR łatwo się gubią. QrScanMode i QrEncoding żyją w IronQr.Enum, podczas gdy QrErrorCorrectionLevel znajduje się w IronQr, a kod pisany z pamięci nie zbuduje się, kiedy zostanie to niepoprawnie wykonane.

@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.
Text
Porady: Traktuj odpowiedź bez strony jako niezweryfikowaną, dopóki nie znajdziesz członka w dokumentacji API.

Jak napisać zasady projektu, które kodują konwencje IronQR?

Reguły projektu to pliki .mdc w .cursor/rules. Są zatwierdzane z kodem, więc każdy klon dostaje te same zasady. Zwykły plik .md w tym folderze jest ignorowany, ponieważ nie ma nagłówka, który mówi, kiedy się stosuje.

Ta reguła ustawia globs i pozostawia alwaysApply wyłączony, dzięki czemu dołącza się zawsze, gdy czytelnik lub jego testy są w kontekście i pozostaje poza żądaniami, które nigdy nie mają do czynienia ze zdjęciem. Zapisz to jako .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.
Markdown
Uwaga: Cursor odczytuje także AGENTS.md w katalogu głównym projektu i w podkatalogach. Nie ma nagłówka, więc nie może być zakresowane przez wzorce plików. Zachowaj zasadę IronQR w zasięgu wzorca w .cursor/rules.

Zasady mają zastosowanie do żądań Agenta. Zgodnie z dokumentacją Cursor nie wpływają one na zakładki, a zasady użytkownika nie stosują się do edycji w linii. Samodzielnie sprawdź sugestie z tych funkcji względem reguły.

Jak zmapować wywołania ZXing.Net do IronQR?

Reguła, która mówi tylko "użyj IronQR", pozostawia modelowi do zgadywania, w co zmienia się każde wywołanie ZXing.Net. Wymienienie odpowiedników usuwa zgadywanie.

ZXing.Net lub QRCoderIronQR
BarcodeReader wywołania dekodująceQrReader z Read, które zwracają każdy kod
Result.TextQrResult.Value
QR_CODE sprawdzenia i filtry formatuSprawdzenie QrResult.QrType po odczycie
Opcja głębszego skanowaniaTryb skanowania dla danych wejściowych
Result.ResultPoints, centra wzorcówQrResult.Points, cztery rogi
Generator QRCoderQrWriter.Write i jego wywołania zapisu

Enum BarcodeFormat ZXing.Net nie ma członka Micro QR ani rMQR, a jego README wymienia kod QR, ale nie mniejsze symbole, więc czytnik ZXing.Net nie zwróci nic dla naklejki, która nosi tylko numer seryjny Micro QR.

Dodaj tabelę do reguły jako dwie dodatkowe linie.

- 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.
Markdown

Jak zaplanować i przeprowadzić migrację do IronQR?

Przełączyć czat na Tryb Planowania za pomocą Shift+Tab przed wysłaniem tego żądania, a Cursor napisze plan jako plik, który można edytować.

@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.
Text

Poprawić wszystko, co plan źle zinterpretował, a następnie kliknąć Buduj, lub wysłać następne żądanie w Agencie.

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.
Text

Wybrany z menu @, @ironqr-photos dołącza regułę po nazwie, nawet gdy jego wzorce omijają plik. Czysta kompilacja nie pokazuje, czy numery seryjne Micro QR teraz wracają. Liczba dopasowań robi to.

Która funkcja Cursor pasuje do każdej zmiany?

Wybierz jedną według tego, jak daleko zmiana sięga. Tab obsługuje przewidywalną następną edycję, a edycja w lini obsługuje jedną selekcję, którą obejmuje jedno zdanie. Agent przyjmuje zmianę, która wymaga kilku plików, reguły lub pętli budowania. Tryb Planowania opłaca się, gdy cofnięcie złej zmiany kosztuje więcej niż jej zaplanowanie, a Cloud Agent nadaje się do pracy, którą nikt nie musi obserwować.

Nowa linia produktów dodaje prostokątną etykietę kablową, która przenosi swój numer seryjny w kodzie rMQR, który IronQR zgłasza jako QrEncoding.RMQRCode. Zaznaczyć pętlę wyników w czytniku i nacisnąć Ctrl+Shift+L (Cmd+Shift+L na macOS), aby dodać zaznaczenie do czatu, a następnie wysłać to żądanie w Agencie.

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.
Text

Czytnik po migracji już zwrócił SN-61518 dla zdjęcia etykiety, ponieważ traktował każdą wartość, która nie jest URL-em, jako numer seryjny. Edycja zastępuje to zgadywanie sprawdzeniem typu symbolu, więc wartość Micro QR lub rMQR staje się numerem seryjnym, nawet jeśli jego tekst wygląda jak URL.

Jak debugować brakujące wartości kodów QR?

Każdy tryb skanowania zmienia to, co się zwraca.

  • Auto jest domyślny. Dokumentacja API IronQR opisuje go jako model uczenia maszynowego, z podstawowym czytaniem brute-force jako metodą awaryjną, gdy model nic nie znajdzie.
  • Podstawowe czytanie brute-force działa samotnie pod OnlyBasicScan, z pominięciem modelu.
  • OnlyDetectionModel lokalizuje kody bez ich dekodowania. Przewodnik trybów skanowania wymienia jego wyjście jako współrzędne.

Jeśli model zgłosi pole, którego nie można zdekodować, metoda awaryjna nigdy się nie uruchomi, a Auto nie zwróci żadnej wartości. Zdjęcia całych pudełek napotykają to, z naklejką o szerokości ok. 110 pikseli w kadrze 4000x3000 pikseli. Sprawdzić, czy poprawka agenta powtarza z OnlyBasicScan, gdy nie pojawia się żadna wartość.

@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.
Text

Pobrać każdy numer seryjny z wydruku IronQR i poprosić o polecenie, które go wyprodukowało.

Kolejność rogów zależy również od trybu. Kiedy model lokalizuje kod, cztery punkty biegną z góry z lewej, z góry z prawej, z dołu z lewej, z dołu z prawej, zgodnie z przewodnikiem trybów skanowania. OnlyBasicScan zwraca własne rogi kodu zgodnie z ruchem wskazówek zegara, obracane razem z naklejką. Oblicz kontury na podstawie współrzędnych, zamiast zakładać kolejność.

Jak napisać testy regresji dla odczytu kodów QR?

Testy, które porównują zdekodowane wartości ze znaną listą, przetrwają aktualizacje biblioteki, podczas gdy testy porównujące bajty obrazu mogą się nie powieść, gdy rendering się zmienia. Cloud Agent może uruchomić tę sugestię w izolowanym VM w chmurze. Dodaj IRONQR_LICENSE_KEY jako tajemnicę na desce rozdzielczej Cloud Agents przed uruchomieniem.

@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.
Text

Ostatnie stwierdzenie ma znaczenie dla naklejki, której cała wartość to adres bezpośredni. Odczytanie przykładowego obrazu z przewodnika trybów skanowania IronQR dało Value z http://en.m.wikipedia.org i Url, który wydrukowano z ukośnikiem na końcu, ponieważ Uri normalizuje adres. Z linkami jak te w tej usłudze, gdzie numer seryjny jest ostatnim segmentem ścieżki, stwierdzenie nie może się nie udać.

Przewodnik po asystentach kodowania AI IronQR wykonuje jedno zadanie IronQR od początku do końca według zdefiniowanych kryteriów zaliczenia.

Który pakiet IronQR wdrożyć?

IronQR.Slim zapewnia przestrzeń nazw IronQr i podstawowe skanowanie. Pełny pakiet IronQR dodaje detektor i środowisko uruchomieniowe ONNX. Przewodnik po pakietach NuGet IronQR mówi, że projekt z samym Slim wymaga także pakietu IronSoftware.ReaderInternals dla swojego systemu operacyjnego.

@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.
Text

Z samym IronQR.Slim, Auto nie ma modelu i przechodzi bezpośrednio do podstawowego skanowania, a OnlyDetectionModel rzuca wyjątkiem IronQrException. Dokumentacja API IronQR ostrzega, że odczyty bez modelu są wolniejsze i niższej jakości. Przetestować na własnych zdjęciach klientów przed zmianą pakietów.

Co wyprodukowały zapytania w rzeczywistym uruchomieniu?

Osiem zdań wysłano do Cursor w porządku względem przykładowego repozytorium przyjmowania zgłoszeń gwarancyjnych. Zawiera aplikację konsolową z czytnikiem ZXing.Net, projekt xUnit, który rysuje naklejki z QRCoder, i dwanaście zdjęć zgłoszeń z znanymi numerami seryjnymi. Reguła, zdjęcie etykiety kablowej i zdjęcia całych pudełek zostały dodane bezpośrednio przed sugestiami, które je wykorzystują. Klucz licencyjny ustawiono tylko w środowisku. Po uruchomieniu, świeże kompilacje wersji Release każdego commita z migracji ponownie odczytały foldery zdjęć i odtworzyły liczby dopasowań czytnika IronQR oraz poniżej wyniki testów.

  • Zdjęcia zgłoszeń odpowiadały 8 na 12 z czytnikiem ZXing.Net i 12 z 12 po przejściu na IronQR.
  • Odczytane po raz w trybie skanowania, zgłoszenie-0004 dało dwa kody z wartościami dla Auto i OnlyBasicScan, i dwa wyniki z pustymi wartościami dla OnlyDetectionModel.
  • Zmiana rMQR pozostawiła zdjęcia zgłoszeń na poziomie 13 z 13 przed i po.
  • Przed poprawką, Auto odczytało 0 z 4 zdjęć całych pudełek. OnlyDetectionModel znalazł 3, 1, 3 i 2 skrzynki bez wartości, podczas gdy OnlyBasicScan odczytał 4 z 4.
  • Po poprawce zdjęcia całych pudełek odczytano 4 z 4, a zdjęcia zgłoszeń 13 z 13.
  • Zestaw xUnit przeszedł 22 z 22 testów.
  • Publikacja dla win-x64 wyprodukowała 75 624 980 bajtów z IronQR i 19 510 306 z IronQR.Slim. Nasz przebudowywaniu dało 75 624 288 i 19 509 614.
  • Na IronQR.Slim czytnik nadal dopasowywał 13 z 13 zdjęć zgłoszeń i 4 z 4 zdjęć całych pudełek.
  • Każda wersja Release miała 0 błędów i nie wymagała ręcznych edycji.
  • Nie każdy krok przebiegł zgodnie z opisem tutaj. Sugestie wysyłano ręcznie, wspomnienia wklejano jako tekst, a Agent znalazł plik z regułami przez szukanie jego nazwy. Plan zatwierdzono przez wysłanie następnej sugestii, nigdy nie kliknięto Buduj, a sugestia Cloud Agent uruchomiona lokalnie w trybie Agenta.

Rekord uruchomienia zawiera wersje pakietów, model, czas i maszynę testową dla każdego przewodnika.


Rozwiązywanie problemów


Pytania?

Jeśli są jakiekolwiek pytania, należy skontaktować się z support@ironsoftware.com

Curtis Chau posiada tytuł licencjata z informatyki (Uniwersytet Carleton) i specjalizuje się w front-endowym rozwoju, z ekspertką w Node.js, TypeScript, JavaScript i React. Pasjonuje się tworzeniem intuicyjnych i estetycznie przyjemnych interfejsów użytkownika, Curtis cieszy się pracą z nowoczesnymi frameworkami i tworzeniem dobrze zorganizowanych, atrakcyjnych wizualnie podręczników.

Czytaj więcej

Gotowy, aby rozpocząć?

Pobrania z NuGet 82,442Wersja:2026.11właśnie wydane