Oparcie pracy Cursor na dokumentacji IronBarcode

Curtis Chau
Curtis Chau
Zaktualizowano: 21 września 2026

BarcodeReaderOptions.CropArea w IronBarcode przyjmuje IronSoftware.Drawing.Rectangle, a nie typ o tej samej nazwie System.Drawing, a model działający z pamięci sięga po ten znany. Nawyk pisania dotnet add package IronBarcode pozostaje, ale pakiet to BarCode, a przestrzeń nazw to IronBarCode.

Cursor rozwiązywał ten problem, indeksując witrynę dokumentacji dostępną przez wzmiankę @Docs. Ta wzmianka nie pojawia się już w dokumentacji Cursor. Na jej miejsce wchodzi link wklejony do promptu, który narzędzie sieciowe agenta pobiera, lub wskazówki zawarte w regule bądź umiejętności. Wszystkie trzy kierują agenta do rzeczywistych stron dokumentacji, a żadna z nich nie czeka na indeks.

Cursor jest edytorem zorientowanym na AI i jego agent działa w dwóch bardzo różnych zakresach:

  • Edytowanie w miejscu i Tab działają tam, gdzie jest kursor, z Ctrl+K (Cmd+K na Macu) określającą zmianę w jednym zdaniu, a Tab przewidującym następną edycję.
  • Tryb agenta planuje w wielu plikach, uruchamia kompilację, czyta błędy i iteruje, podczas gdy tryb planowania pozwala najpierw uzgodnić podejście.

Tab otwiera portal do innego pliku, gdy następna zmiana tam trafia, a edycja w miejscu pokazuje różnice w miejscu, aby można było je zaakceptować lub odrzucić.

Reguły docierają do trybu agenta i czatu, i nic więcej. Dokumentacja Cursor stwierdza jasno, że reguły nie wpływają na Cursor Tab ani inne funkcje AI. Zatem reguła, którą zatwierdzono, nie jest tam, gdy Tab sugeruje metodę.

Przygotowanie Cursor do pracy z kodami kreskowymi wymaga dwóch zatwierdzonych plików i linku wklejonego do promptu. Przygotowanie to ma największe znaczenie przy precyzyjnych zmianach, zawężaniu opcji czytnika, dodawaniu obszaru przycięcia, wybieraniu prędkości czytania lub identyfikacji jednej korekcji obrazu, która umożliwia odczyt partii skanów niskiej jakości.

Nic tutaj nie dotyczy oceniania pewności wewnątrz czytnika IronBarcode, który ma swój przykład praktyczny.

Szybki start
NuGetInstalacja z NuGet

PM > Install-Package BarCode

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

Otworzyć projekt C# w Cursor i dać agentowi stronę do przeczytania, zanim cokolwiek napisze.

In Program.cs, generate a Code 128 barcode for an asset tag and style it for a
printed label. Set the bar color and the background with ChangeBarCodeColor and
ChangeBackgroundColor, size it with ResizeTo, and print the value under the
bars. The license comes out of IRONBARCODE_LICENSE_KEY.

Work from https://ironsoftware.com/barcode/csharp/llms-full.txt, use only
members that appear in it, and tell me which page each styling call came from.
Text

Nazwy metod zmiany koloru i rozmiaru łatwo zapamiętać niedokładnie, dlatego prompt wysyła agenta najpierw na stronę. Przewodnik stylizacji kodu kreskowego dokładnie nazywa wszystkie trzy.

Uwaga: Każdy wklejony prompt jest zapisywany w sesji, więc klucz licencyjny wklejony do promptu to klucz opublikowany w historii edytora. Zamiast tego należy odczytać go ze środowiska, jak to zostało określone w przewodniku klucza licencyjnego.


Który model powinien obsłużyć sesję z kodami kreskowymi?

Cursor jest jedynym narzędziem w tej serii, gdzie można wybrać model. Composer, jego własny model agentowy, jest dostrojony do użycia narzędziowego, edycji plików i pracy terminalowej wewnątrz edytora, a jego szybka wersja jest domyślną opcją. Lista wyboru zawiera również najnowsze modele od OpenAI, Anthropic, Google i SpaceXAI. Tab działa poza tym wyborem i pracuje z ostatnimi edycjami, otaczającym kodem i błędami lintera.

Większość sesji kodu kreskowego jest tania i powtarzalna. Dodaje się format, ponownie kompiluje projekt, dekoduje zbiór testowy i dostraja ustawienia. Od czasu do czasu partia prawdziwych skanów się nie dekoduje i żaden błąd nie mówi dlaczego, i wtedy należy przełączyć się na model, który rozumuje dłużej przed edycją. Model także kształtuje kod, więc należy ustalić symbolikę, rozmiar wyjściowy i warunek odczytu zamiast zostawiać je jako domyślne.

Tutaj seria się nakłada. Po uruchomieniu modelu Claude w Cursor uwagi z przewodnika Claude Code dotyczą generowanych przez niego wyników. Model jest ten sam. Jedynie interfejs się różni.

Jak oprzeć pracę Cursor na dokumentacji IronBarcode?

Trzy uzupełniające się działania zastępują dawny indeks:

  • Wkleić link: wskazać llms-full.txt zamiast centrum dokumentacji, więc jeden URL umieszcza przewodniki, przykłady i nazwy członków przed agentem.
  • Zatwierdzić umiejętność: zapisać opublikowany plik skill.md IronBarcode jako .cursor/skills/ironbarcode/SKILL.md, ustawić name: ironbarcode, by pasowało do folderu, i zatwierdzić go.
  • Zatwierdzić regułę: następna sekcja omawia, co do niej należy.

Cursor ładuje umiejętności agenta z .cursor/skills/ i .agents/skills/, w głównym katalogu projektu lub w podkatalogu, każda umiejętność to folder zawierający SKILL.md, którego frontmatter zawiera name i description. Agent ładuje jedną z nich, gdy zadanie odpowiada jej zakresowi, a wpisanie /ironbarcode wywołuje ją bezpośrednio. Katalog .agents/skills/ to wspólna ścieżka dla tego samego pliku, więc Codex i Antigravity ładują go stamtąd również.

Pominięcie wszystkich trzech sprawi, że model odpowie z danych treningowych, które nigdy nie zostały sprawdzone względem aktualnego wydania. Najpierw pojawiają się błędy w nazwach metod. BarcodeScanner.DecodeImageFile() czyta się jak prawdziwe wywołanie i powoduje błąd kompilacji.

Mając stronę do pracy, pytania, które byłyby zgadywaniem, stają się zapytaniami.

Which options narrow a read to two symbologies inside a fixed region of a
larger image? Give me the exact class and property names, and quote the lines
you took them from in https://ironsoftware.com/barcode/csharp/llms-full.txt.
Text

Jeśli agent nie może zacytować strony dla sugerowanego API, należy zweryfikować to API przed wykorzystaniem go w kodzie.

Porady: Działa to w przypadku każdej nieznanej klasy. Mając plik w kontekście, można zadawać pytania o BarcodeReaderOptions zamiast przewijać dokumentację, a odpowiedź cytuje stronę dokumentacji API, z której pochodzi.

Jak pisać reguły projektów, które kodują konwencje IronBarcode?

Reguły projektów znajdują się w folderze .cursor/rules w głównym katalogu repozytorium. Są objęte kontrolą wersji, zatwierdzane z kodem, więc każdy deweloper uzyskuje takie samo działanie bez dodatkowej konfiguracji.

Każda reguła to plik .mdc, który jest plikiem Markdown z nagłówkiem YAML określającym description, globs i alwaysApply. Cursor przeszukuje folder rekurencyjnie, więc działają również podfoldery. Zwykły plik .md tam jest ignorowany, ponieważ nie ma nagłówka, aby go aktywować. Reguła IronBarcode wygląda tak.

---
description: IronBarcode conventions for barcode reading and writing in this project
globs: ["**/Services/**/*.cs", "**/Barcodes/**/*.cs"]
alwaysApply: false
---

# IronBarcode conventions

Applies to the barcode code in this folder only.

- IronBarcode (package BarCode, namespace IronBarCode) writes and reads every
  barcode here. Never reach for a second barcode package.
- Reader options are explicit: set ExpectBarcodeTypes to the formats this
  feature really reads, and reuse one BarcodeReaderOptions per format set
  rather than allocating per call.
- Reads on a request path are async.
- CropArea takes IronSoftware.Drawing.Rectangle, not System.Drawing.
- Verified recipes: https://ironsoftware.com/barcode/csharp/skill.md
- If you are unsure a member exists, say so and cite the page. Do not guess a
  method name that sounds plausible.
YAML

Informowanie modelu, że niepewność jest akceptowalna, to to, co zatrzymuje wymyślone API, a reguła mówi o tym raz dla każdej kolejnej sesji.

Świadomie dobrać wiersz globs. Reguła z alwaysApply: true ładuje się do każdego żądania i zużywa kontekst na pracę, która nie ma w sobie kodów kreskowych. Ograniczenie reguły do folderów zawierających kod obsługi kodów kreskowych zapewnia jej właściwy zakres.

Uwaga: Cursor również czyta zwykły AGENTS.md, ten sam plik, którego używają ChatGPT Codex i Google Antigravity. Nie ma on nagłówka, a więc również nie zawiera globów, a Cursor czyta go w głównym katalogu projektu i w podkatalogach, więc gniazdowanie to jedyne ustalanie ograniczeń, które oferuje. Użyć .cursor/rules, gdy potrzebne są wzorce glob, i AGENTS.md, gdy jeden plik instrukcji ma służyć kilku narzędziom.

Który tryb najlepiej pasuje do zmiany?

Cursor oferuje więcej sposobów edycji niż jakiekolwiek inne narzędzie w tej serii. Wybrać według rozmiaru zmiany, od jednej linii do całego repozytorium:

TrybKiedy używaćPrzykład kodu kreskowego
TabNastępna edycja jest przewidywalnaPowtarzanie opcji czytnika
Edycja w miejscuJeden plik, jedno zdanieZawężanie odczytu do dwóch formatów
AgentPraca obejmuje pliki i potrzebuje pętli kompilacjiPunkt końcowy etykiet i punkt końcowy skanowania
Tryb planuPrzepisanie jest zbyt duże, aby przejrzeć potemMigrowanie z innej biblioteki kodu kreskowego
Agent chmurowyMoże działać bez nadzoruTesty zapisu i ponownego odczytu dla każdego formatu

Co zmienia wzmianka @?

Wzmianka @ przekazuje agentowi rzecz do przeczytania, która może być plikiem, folderem, terminalem, wcześniejszym czatem, różnicą Git lub przeglądarką. Odniesienie do pliku, który czyta kody kreskowe, jest skuteczniejsze niż jego opisywanie, ponieważ opis traci szczegóły, w których tkwi błąd.

@Services/ScanService.cs @TestData/depot/

Read https://ironsoftware.com/barcode/csharp/llms-full.txt for the options.

Half the photos in TestData/depot/ come back empty. The reader options are
where this gets fixed, not the label generator. Name the setting that was
missing, and give me a decode rate for the folder before your change and after
it.
Text

Wzmianka o folderze pasuje do pracy na poziomie modułu, a cały kod jest tam, gdy nie można wskazać, który plik ma znaczenie. Sparowanie kodu z dokumentacją pokrywa obie połowy pytania: plik pokazuje, co kod robi teraz, a strona pokazuje, co faktycznie dostarcza biblioteka.

Które ustawienie ratuje partię zdjęć, zależy od tego, jak są uszkodzone, a żaden opis nie zastąpi uruchomienia przez agenta odczytu tych obrazów. Strony prędkości czytania i korekcji obrazu omawiają poszczególne ustawienia.

Jak zaplanować i przeprowadzić migrację do IronBarcode?

Niezweryfikowane przepisanie kodu w wielu plikach staje się kosztowne podczas migracji, ponieważ jego cofnięcie jest trudniejsze niż napisanie. Do tego służy tryb planowania. Nacisnąć Shift+Tab w czacie, lub wybrać z listy rozwijanej trybu, a agent zadaje pytania doprecyzowujące, czyta kod projektu i tworzy plan, który edytuje się na czacie lub jako markdown przed pojawieniem się jakiegokolwiek kodu. Plany są zapisywane w katalogu domowym, a "Zapisz w przestrzeni roboczej" przenosi jeden do repozytorium do przeglądu przez zespół.

The barcode code in @Labels/ belongs to another library. Using
https://ironsoftware.com/barcode/csharp/llms-full.txt, work out what replacing
it with IronBarcode would actually involve. Which files change, what the
equivalent call is for each thing the folder does today, and where the
documentation says no clean equivalent exists.

Public method signatures are fixed. If the plan needs one to change, say so in
the plan rather than changing it.
Text

Przeczytać plan, poprawić go jednym lub dwoma zdaniami i odesłać do kompilacji. Tryb agenta następnie czyta kod, edytuje w wielu plikach, uruchamia polecenia, sprawdza wynik i iteruje, więc następny prompt może być krótki.

Carry out the plan we agreed. Compile it, clear whatever errors come up, and
satisfy yourself that every symbology the folder handles still comes back out
the same as it went in. Show me the diff at the end. BarCode is the only package
that may appear in the .csproj.
Text

Bez tych dwóch ograniczeń agenci przebudowują sposób wywoływania kodu podczas migracji.

Praca, która nie wymaga nadzoru, może pójść do agenta chmurowego, wcześniej agenta działającego w tle, podczas dalszej pracy w edytorze. Testy zapisu i ponownego odczytu pasują do tego, ponieważ ich asercje dotyczą zdekodowanych wartości zamiast szczegółów implementacji, więc ich pisanie nie czeka na migrację.

@Services/

Send this to a cloud agent while I keep working on the reader options.

Cover the migrated service with xUnit. Use a [Theory] over the symbologies it
supports rather than one [Fact] per format, so adding a format later costs one
line. Each case writes a sample value and reads it back, and the assertion is on
the decoded string and the decoded format together.

Then three edge cases as their own facts: an empty image returns no results
instead of throwing, a letters-only value is refused as EAN-13, and a missing
path fails with a readable message. Image bytes are off limits as an assertion
target.
Text

Wykluczenie porównań bajt po bajcie to to, co zapewnia stabilność zestawu testów między platformami.

Gdzie szukać przyczyn problemów z odczytem?

Nieczytelne kody kreskowe to najczęstsze pytanie IronBarcode, a odpowiedź prawie zawsze tkwi w opcjach czytnika, a nie w etykiecie. To, co dodaje Cursor, to fakt, że nie trzeba opisywać awarii. Wskazać usługę i folder z obrazami, których odczyt się nie powiódł, aby edytor korzystał z obu.

Photos of returns labels read fine on a handheld scanner but come back empty
from @Services/ScanService.cs, and a few product photos carrying no barcode at
all return a value. Samples of both are in @TestData/returns/.

Explain the cause of each before changing anything, then fix both in the reader
options.
Text

Wymaganie najpierw wyjaśnienia daje uzasadnienie do sprawdzenia zamiast zmiany, której sens trzeba odtwarzać. Tutaj dwa objawy wymagają przeciwnych rozwiązań. Nieudane odczyty wymagają węższego wykazu formatów, obszaru do przycięcia i właściwego filtru obrazu, co omawia przewodnik Nie rozpoznano kodu kreskowego. Fałszywe pozytywy wymagają RemoveFalsePositive i progu pewności opisanego w przewodniku fałszywych pozytywów.

Przyczyna błędu wdrożenia zwykle tkwi w .csproj lub w obrazie kontenera, a nie w pliku C#, a agent z dostępem do terminalu może przeczytać oba i sam uruchomić kompilację.

@Dockerfile @LabelScan.csproj @Terminals

Reading works on Windows but fails in our Linux container. The failing build is
in the terminal output above, so read it there rather than asking me to paste it.

Check which BarCode package the project references and whether the image has
the native dependencies IronBarcode needs on Linux. Explain the cause, then
propose the change. Don't modify C# code unless the cause is there.
Text

Wyraźnie zaznaczyć, że C# nie należy dotykać. Mając nieudane wywołanie i brak granic, agent sięgnie po try/catch i zgłosi problem jako rozwiązany. Przewodnik po Docker na Linuxie wymienia, czego obraz faktycznie potrzebuje.

Co należy skonfigurować najpierw?

Przygotowanie pliku umiejętności i jednej reguły o określonym zakresie zajmuje około piętnastu minut, a oba pliki mają zastosowanie we wszystkich kolejnych sesjach. Wklejanie linku do dokumentacji pozostaje nawykiem przy każdym prompcie i kosztuje jedną linię.

Po zmianie modelu używanego przez edytor nadal obowiązują trzy kontrole: kod kompiluje się, kod kreskowy dekoduje się i każdy użyty element API pojawia się w udokumentowanym API IronBarcode. Te trzy są dokładnie tym, co mierzy przewodnik dla asystentów AI i agentów kodowania. Osobne strony opisują Claude Code, ChatGPT Codex, GitHub Copilot i Google Antigravity.


Rozwiązywanie problemów


Pytania?

W przypadku jakichkolwiek pytań, 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 2,564,559Wersja:2026.11właśnie wydane