Jak korzystać z IronWord z Cursor
Przykładowe repozytorium dla tego przewodnika odczytuje formularze dostawców za pomocą kodu OpenXML SDK, który iteruje po elementach treści i odczytuje InnerText. Przeniesienie tego czytnika do IronWord poprzez parsowanie każdej oznaczonej wartości z jednego bloku wyodrębnionego tekstu za pomocą wyrażenia regularnego kończy się niepowodzeniem. Podczas kalibracji ta wersja prawidłowo odczytała 3 z 12 formularzy, łącząc pięć numerów rejestracyjnych z następującym etykietą i nie zwracając numeru rejestracyjnego dla czterech formularzy tabel.
Cursor jest zbudowany na bazie kodu VS Code i zapewnia agenta obok edytora. Dwa z jego funkcji, dokumentacja, którą agent odczytuje oraz zasady projektu zapisane w .cursor/rules, określają, czy produkowany jest kod IronWord, czy kod oparty na wzorcu czytnika OpenXML. Oba funkcje pojawiają się poniżej w usłudze onboardingowej dostawcy, która odczytuje formularze DOCX zwrócone przez dostawców. Usługa wyodrębnia nazwę dostawcy, numer rejestracyjny, tabelę cennika oraz osadzone obrazy logo i podpisu, a jej czytnik przechodzi z OpenXML SDK do IronWord.
Szczegółowe informacje o metodach odczytu IronWord znajdziesz w przewodniku po wyodrębnianiu tekstu i przewodniku po wyodrębnianiu obrazów.
Szybki startMając otwarte repozytorium przyjęć dostawców, należy wkleić tę komendę do nowego czatu Agenta.
@src/SupplierIntake/ @TestData/forms/
Don't write anything until you've fetched https://ironsoftware.com/word/csharp/llms.txt.
Read the extract text and extract images pages it links as well.
Then give Program.cs a dump command that opens one form with IronWord:
`dotnet run --project src/SupplierIntake -- dump <file.docx>`
Have the dump print what IronWord returns for that form:
- The ExtractText result, in quotes.
- Every entry of Paragraphs, with its index.
- Every table cell, with its table, row and column numbers.
- Each extracted image's Width and Height, and the pixel size of the AnyBitmap behind it.
The program should read IRONWORD_LICENSE_KEY itself when it's set.
At startup, assign the key to License.LicenseKey.
Never print the key, and keep environment variables out of the output.
Leave Forms/FormReader.cs and its DocumentFormat.OpenXml reference as they are.
Run the dump on TestData/forms/form-03.docx and show me the output.
Nie wprowadzaj klucza licencyjnego w czacie. Agent edytuje pliki i uruchamia polecenia powłoki, więc wklejony klucz jest narażony na każdy plik, wiadomość commit i dziennik budowy, które generuje. W naszych testach IronWord otwierał i odczytywał każdy formularz bez klucza i rzucał wyjątek LicensingException tylko podczas zapisywania dokumentu. Przewodnik po kluczu licencyjnym pokazuje, jak ustawić klucz w kodzie, w pliku Web.config lub w appsettings.json.
Minimalny proces (5 kroków)
- Pobierz bibliotekę Word C# z NuGet
- Dodanie zasady projektu w .cursor/rules, która zawiera link do dokumentacji IronWord.
- Opisanie w regule, co pomija
ExtractText. - W każdym żądaniu odwołać się do pliku czytnika i folderu zwróconych formularzy.
- Porównać każdą wyodrębnioną wartość z znaną listą, a następnie potwierdzić każdą nazwę członka w dokumentacji API.
Jakiego modelu Cursor użyć do pracy z IronWord?
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.
Jak dostarczyć Cursora dokumentację IronWord?
Dołączyć link do dokumentacji IronWord do żądania lub przechowywać go w zasadzie udostępnianej przez cały zespół. Plik llms.txt zawiera każdy przewodnik i dokumentację API, a llms-full.txt kondensuje 46 stron dokumentacji do jednego pliku. Od października 2026 roku menu @ Cursora dołącza pliki, foldery, terminale, czaty, różnice Git i przeglądarkę, więc dokumentacja IronWord idzie do agenta jako link.
Zrzut Quickstart pokazuje dwa zachowania, o których nie mówi przewodnik po wyodrębnianiu tekstu. Dla form-03 ExtractText zwrócił tekst akapitu zawartości złączony w jeden łańcuch i pominął cały tekst w dwóch tabelach formularza.
@src/SupplierIntake/Forms/RegistrationCheck.cs
Answer five questions about IronWord, without editing any files:
1. Does WordDocument.ExtractText include text from table cells?
2. What does it put between paragraphs?
3. Does the Paragraphs collection list the paragraphs inside table cells?
4. What does ExtractImages return, and what element type does the list hold?
5. What unit do the Width and Height of each result use?
Use the documentation at https://ironsoftware.com/word/csharp/llms.txt as your source.
The project rule doesn't count as one.
Check your answers against the form-03 dump from the last turn, where it shows them.
Cite the page each answer comes from.
Where no page states it, say the answer is measured, not documented.
Jak napisać zasady projektu kodujące konwencje IronWord?
Zasada projektu to plik .mdc przechowywany w .cursor/rules i wersjonowany razem z repozytorium, więc każdy klon obejmuje go. Cursor ignoruje zwykłe pliki .md w tym folderze, ponieważ bez metadanych nie można określić, kiedy je załadować.
Poniższa zasada definiuje globs i ustawia alwaysApply na false. Cursor ładuje ją, gdy tylko żądanie obejmuje czytnik formularzy lub plik testowy, a pomija ją w przeciwnym razie. Zapisać jako .cursor/rules/ironword-forms.mdc.
---
description: IronWord conventions for reading supplier forms
globs: src/SupplierIntake/Forms/**/*.cs, tests/**/*.cs
alwaysApply: false
---
Read and write DOCX files with IronWord only, under these package rules:
- The NuGet package is IronWord.
- Its types come from two namespaces, IronWord and IronWord.Models.
- AnyBitmap comes from IronSoftware.Drawing.
- Don't add DocX, NPOI or any other DOCX package.
- Add no new DocumentFormat.OpenXml code.
- The documentation index is https://ironsoftware.com/word/csharp/llms.txt
Keep license keys out of the code, and handle the key this way:
- Read it at run time from an environment variable named IRONWORD_LICENSE_KEY.
- Never print it.
WordDocument.ExtractText leaves out table cells and runs paragraphs together with no separator.
Use the paragraph and table collections instead:
- Read labeled values one paragraph at a time from doc.Paragraphs.
- Read tables through doc.Tables, Rows and Cells.
- doc.Paragraphs also returns the paragraphs inside table cells.
Table.Rows returns ITableRow, and a row's Cells returns ITableCell.
Two casts are needed:
- Cast a row to TableRow before you pass it to a method that takes a TableRow.
- Cast a cell to TableCell before you call ExtractText on it.
Don't invent IronWord members.
When you're unsure of one, say so and name the page you checked.
Strona zasad Cursora stwierdza, że zasady nie wpływają na Tab, a zasady użytkownika nie są stosowane do edycji w linii, więc sugestie Tab i edycji w linii wymagają ręcznego sprawdzenia pod kątem zasady.
Jak mapować wywołania OpenXML SDK na IronWord?
Instruowanie modelu, aby używał IronWord, nie mówi mu, które wywołanie IronWord zastępuje każde wywołanie OpenXML SDK. Tabela odpowiedników zapewnia to mapowanie.
| OpenXML SDK | IronWord |
|---|---|
WordprocessingDocument.Open | Konstruktor WordDocument, z ścieżki, bajtów lub strumienia |
| Akapity treści i ich wewnętrzny tekst | Paragraphs, z ExtractText na każdym z nich |
| Tabele treści, wiersze i komórki | Tables, Rows i Cells |
| Elementy Blip i strumienie części obrazów | ExtractImages, zapisane przez AnyBitmap |
Dwa wiersze zachowują się inaczej niż kod SDK, które zastępują. Lista akapitów zawiera akapity wewnątrz komórek tabeli, jak i same akapity treści, więc form-03 zwraca 15 wpisów, gdzie czytnik OpenXML SDK iterował po 5 akapitach treści. Komórki są zwracane jako ITableCell, które nie mają metody tekstowej, dlatego wywołanie bez rzutowania nie udaje się zbudować z CS1061.
IronWord nie odnosi się do pakietu DocumentFormat.OpenXml, a projekt, który odnosi się do IronWord 2026.10.4 i DocumentFormat.OpenXml 3.5.1, kompiluje się i działa. Migracja może więc postępować jeden czytnik naraz. Strona konfliktu OpenXML obejmuje budowy IronWord starsze niż 2025.7.13.
Dodanie tych linii na końcu zasady wstawiać tabelę do każdego żądania, które ładuje zasadę.
Translate OpenXML SDK code instead of porting it, with these equivalents:
- WordprocessingDocument.Open becomes new WordDocument(path).
- Body.Elements<Table>() becomes doc.Tables.
- Counting Blip elements becomes doc.ExtractImages().Count.
Save extracted images with ((AnyBitmap)image.Image).SaveAs(path).
Jak zaplanować i przeprowadzić migrację do IronWord?
Nacisnąć Shift+Tab w polu wejściowym czatu, aż zostanie wybrany tryb planowania, a następnie przesłać poniższą prośbę. Cursor zapisuje plan do pliku edytowalnego.
@src/SupplierIntake/Forms/ @TestData/forms/expected.csv
Plan the move of FormReader to IronWord so the project can drop DocumentFormat.OpenXml.
Write no code until I approve.
FormReader still reads supplier forms with the OpenXML SDK.
RegistrationCheck already uses IronWord, and the team wants a single DOCX library.
The plan has to cover these points:
- Every OpenXML SDK call, with its IronWord replacement and the file where the call lives.
- How the reader will find the price table.
- How it will find a registration number inside a table.
Keep SupplierForm and the public Read and SaveImages signatures unchanged.
Where something is unclear, state your assumption instead of asking.
Show me the plan when it's ready.
Popraw wszystkie błędy w planie. Następnie kliknąć Build lub wrócić do Agenta i wysłać to żądanie.
@ironword-forms
Carry out the approved plan.
Check the forms output against TestData/forms/expected.csv before and after the move.
A printed row counts as a match when its supplier, registration, items and images columns agree.
Work through it in this order:
1. Run `dotnet run --project src/SupplierIntake -- forms TestData/forms` and count the matches.
2. Migrate FormReader to IronWord.
3. Remove the DocumentFormat.OpenXml package reference.
4. Run dotnet build, then run the forms command again.
Tell me the match count for the OpenXML version and for the IronWord version.
Then show me the diff.
Wzmianka @ironword-forms stosuje zasadę według nazwy, niezależnie od tego, czy Cursor już ją dołączył przez swoje globy, czy nie.
Która funkcja Cursor pasuje do każdej zmiany?
Tab uzupełnia edycję, która jest już widoczna w edytorze, a edycja w linii (Ctrl+K) przepisuje zaznaczenie z jednozdaniowej instrukcji. Zmiany w wielu plikach lub zmiany, które wymagają budowy, idą do Agenta. Użyj Trybu Planu, kiedy niepoprawna zmiana wymaga więcej wysiłku do cofnięcia niż napisanie planu. Agent Chmury pasuje do pracy bez nadzoru.
Nowy dostawca zwraca form-13, którego tabela cenowa łączy jedną komórkę z dwóch poziomów cen. Podświetlić pętlę, która iteruje po wierszach cen w FormReader, nacisnąć Ctrl+Shift+L (Cmd+Shift+L na macOS), aby dodać podświetlony kod do czatu input, i wysłać to żądanie w Agencie.
Make FormReader.Read handle merged cells in the price rows:
- An Item cell that Word merged with the cell above comes back empty.
- For that row, reuse the item name from the previous row.
- Before you read a cell by its column position, check that the row has that many cells.
Then rerun the forms command over TestData/forms.
Tell me how many rows agree with expected.csv, which now lists 13 forms.
Sprawdzenie długości wiersza odnosi się do łączeń w przeciwnym kierunku. W osobnym pliku próbki, komórka scalona przez kolumny została zwrócona jako jedna komórka, więc ten wiersz był krótszy niż inne.
Jak debugować wartości brakujące w wyodrębnionym tekście?
Pre-check repozytorium odczytuje numer rejestracyjny za pomocą wyrażenia regularnego nad wynikiem ExtractText.
@src/SupplierIntake/Forms/RegistrationCheck.cs @TestData/forms/
Find out why the pre-check flags 9 of the 13 forms as missing a registration number.
FormReader finds one in all 13, and every number is visible in Word.
Before you edit anything, do these three things:
1. Run the check command on TestData/forms and on TestData/edge, and note what it flags.
2. Run the dump command on one flagged form.
3. Explain what the check reads that FormReader doesn't.
Then fix RegistrationCheck and keep it on IronWord.
Rerun the check on both folders.
Tell me how many forms it flags in TestData/forms and in TestData/edge, before and after the fix.
Dziewięć nieudanych przypadków ma dwie przyczyny. W pięciu formularzach akapit z e-mailem kontaktowym następuje po numerze, więc wyrażenie wychwytuje GB-0012345Contact i weryfikacja formatu go odrzuca. Pozostałe cztery przechowują numer w tabeli danych firmy, gdzie komórka etykiety czyta Numer rejestracyjny bez dwukropka, a wartość jest w kolejnej komórce. Czytanie pojedynczych akapitów i pobieranie wartości z komórki obok etykiety rozwiązuje oba problemy.
Które części DOCX pomija IronWord?
Nasze sondy przeciwko IronWord 2026.10.4 zidentyfikowały treści, które biblioteka nie zwraca do czytnika formularzy.
- Nagłówki: żaden odczyt nie zwraca tekstu nagłówka, a
ExtractImagespomija obrazy nagłówków. Ustawienia strony odsłaniają wysokość nagłówka, ale żadnej z jego treści. - Kontrolki zawartości i pola tekstowe: ich tekst jest nieobecny zarówno w akapitach, jak i w wyodrębnionym tekście.
- Śledzone zmiany: odczyty pomijają tekst wstawiony, gdy śledzenie było włączone.
- Pliki starszej wersji: plik Word 97-2003 .doc zgłasza "Plik zawiera uszkodzone dane" podczas ładowania.
- Obrazki w tekście bez atrybutów odstępów: DOCX, którego obrazki w tekście pomijają distT, distB, distL i distR, nie uda się załadować z InvalidOperationException. python-docx pomija te atrybuty.
Obrazy unoszące się w tekście i obrazy w komórkach tabeli są wyodrębniane według kolejności w dokumencie. Jeśli dostawcy wypełniają formularze zbudowane z kontrolek zawartości lub umieszczają numer rejestracyjny w nagłówku, przetestuj te formularze przed poleganiem na czytniku.
Jak napisać testy regresyjne dla odczytu dokumentów?
Testy, które porównują wyodrębnione wartości z listą znanych, sprawdzają wynik usługi przyjęcia, niezależnie od wewnętrznej implementacji czytnika. Agent Chmury może je napisać w swojej własnej izolowanej maszynie wirtualnej. Najpierw przechowywać IRONWORD_LICENSE_KEY pod sekrety w panelu Agenta Chmury.
@tests/SupplierIntake.Tests/ @TestData/
Write xUnit tests for FormReader and RegistrationCheck.
Each of these needs a test:
- Every row of TestData/forms/expected.csv matches.
- In form-13, both price tiers keep the item name.
- SaveImages writes one PNG per picture, with the pixel sizes listed in the image_sizes column.
- RegistrationCheck passes every form and flags TestData/edge/no-registration.docx.
- Reading TestData/edge/legacy.doc throws a FormatException or a type derived from it.
Copy TestData into the test output and run dotnet test.
Tell me the passed and failed counts.
Asersja dla pliku starszej wersji nie może odwołać się do typu wyjątku IronWord, ponieważ jest on wewnętrzny. Pochodzi od FormatException, więc asercja, która akceptuje typy potomne, takie jak Assert.ThrowsAny<FormatException> w xUnit, kompiluje się i wciąż kończy się niepowodzeniem, gdy zgłaszany jest inny błąd.
Przewodnik po asystentach kodowania AI zawiera jedno zadanie IronWord przeprowadzone end-to-end na tle ustalonych kryteriów zaliczania.
Co wyprodukowały zapytania w rzeczywistym uruchomieniu?
Siedem poleceń zostało wysłanych do Cursora w kolejności w jednym czacie. Przykładowe repozytorium zawierało czytnik OpenXML SDK, pre-check IronWord, pusty projekt xUnit, dwanaście formularzy o znanych wartościach i dwa pliki krawędziowe.
- Zarówno czytnik OpenXML SDK, jak i czytnik IronWord, który go zastąpił, dopasowały wszystkie 12 formularzy.
- IronWord był jedynym pakietem DOCX, który pozostał w aplikacji i jej testach.
- Po dodaniu form-13, czytnik dopasował 12 z 13 i pominął nazwę przedmiotu z drugiego poziomu cen.
- Po zmianie scalonych komórek, czytnik dopasował 13 z 13.
- Pre-check flagował 9 z 13 formularzy przed poprawką i żadnego po niej. Podwójnie flagował formularz krawędziowy bez numeru rejestracyjnego.
- Wszystkie zapisane 21 obrazów miało wymienione rozmiary pikseli.
- Zrzut form-03 wymieniał 10 komórek w dwóch tabelach i jeden obraz 108 na 36 punktów i 144 na 48 pikseli.
- Zapytany, co mówi dokumentacja, Cursor odpowiedział bez zmiany jakichkolwiek plików.
- Wszystkie 42 przypadki z sześciu metod testowych przeszło, z kluczem licencyjnym lub bez niego.
- W kopiach ostatecznego kodu usunięcie obsługi scalonych komórek nie przeszło 2 przypadków. Przywrócenie starego pre-check nie przeszło 9, a pomijanie jednego obrazu na formularz nie przeszło 13.
- Test pliku starszej wersji akceptował każdy wyjątek i przeszedł z plikiem usuniętym. Zawężony do FormatException, przeszedł z prawdziwym plikiem i nie przeszedł bez niego.
- Pierwszy czytnik IronWord Cursora brakowało rzutowania wiersza i nie udało się zbudować z CS1503. Cursor dodał rzutowanie przed następnym budowaniem.
- Każda budowa Release miała 0 ostrzeżeń i 0 błędów, bez ręcznych edycji.
- Niektóre kroki uruchomiono inaczej niż na stronie. Zasada brakowało rzutowania wiersza. Wskazówka scalonej komórki nie żądała sprawdzenia długości wiersza, i Cursor nie dodał żadnego. Wskazówka testowa wymagała jedynie, aby wyjątek został zgłoszony. Wskazówki, wspomnienia @ włącznie, zostały wklejone do aplikacji desktopowej jako tekst. Plan został zatwierdzony w Agencie, nie za pomocą przycisku Buduj. Wskazówka Agenta Chmury działała lokalnie w trybie Agenta, bez maszyny wirtualnej.
Przewodnik po Claude Code dodaje podagent tylko do odczytu, który sprawdza każdego członka IronWord w wygenerowanym kodzie z IronWord.xml. Przewodnik po ChatGPT Codex obejmuje stronę pisania i mierzy, które części dokumentu Word zmienia zastąpienie tekstu.
Rekord uruchomienia wymienia pakiet IronWord, model, czas i maszynę testową dla tych wyników.
Rozwiązywanie problemów
- Wyodrębnij tekst z DOCX, gdy wartości wewnątrz tabeli brakuje w wyodrębnionym tekście
- Wyodrębnij obrazy z DOCX, gdy zapisane obrazy wymagają sprawdzenia ich rozmiarów lub formatu
- IronWord z DocumentFormat.OpenXml, podczas gdy oba pakiety są referencjonowane w jednym projekcie podczas migracji
- Używanie kluczy licencyjnych, gdy wygenerowany kod zgłasza wyjątek licencyjny podczas zapisywania
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.