如何使用 IronWord 與 Cursor

Curtis Chau
Curtis Chau
已更新: 2026年10月19日

本指南的範例庫使用 OpenXML SDK 程式碼讀取供應商表單,該程式碼可遍歷正文元素並讀取 InnerText。 通過從一個提取文本塊中解析每個標記值將讀取器移到 IronWord 失敗了。 在校準中,該版本正確讀取了 12 個表單中的 3 個,將五個註冊號碼連接到後面的標籤,並且對四個表格形式不返回註冊號。

Cursor 建立在 VS Code 程式碼庫上,並在編輯器旁邊提供了一個代理。 它的兩個功能,即代理讀取的文件鏈接和在 .cursor/rules 中提交的專案規則,決定了它是生成 IronWord 程式碼,還是遵循 OpenXML 讀取器模式的程式碼。 兩個功能都出現在供應商入職服務中,該服務會讀取供應商退回的 DOCX 表單。 該服務提取供應商名稱、註冊號碼、價格列表表格以及嵌入的徽標和簽名圖片,而它的讀取器從 OpenXML SDK 遷移到 IronWord。

有關 IronWord 讀取方法的詳細信息,請參閱文本提取指南和圖片提取指南。

快速開始
NuGet使用NuGet安裝

PM > Install-Package IronWord

在 NuGet 包管理器控制台中運行上述命令安裝 IronWord,或在 NuGet 包管理器中搜索該包。

在開啟的供應商採集庫中,將此提示粘貼到新的代理聊天中。

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

不要在聊天中輸入授權金鑰。 代理會編輯文件並運行 shell 命令,因此複製的金鑰會暴露在它寫入的每個文件、提交消息和構建日誌中。 在我們的測試中,IronWord 在沒有金鑰的情況下打開並讀取了每個表單,僅在保存文件時引發 LicensingException。 授權金鑰指南顯示了如何在代碼中、在 Web.config 或 在 appsettings.json 中設定金鑰。



哪個 Cursor 模型適合用於 IronWord 工作?

Composer是Cursor自己的代理模型。 模型選擇器還提供了Cursor共同開發的SpaceXAI的Grok模型以及來自OpenAI、Anthropic、Google和其他實驗室的模型。 下面的測試運行使用了Grok 4.7。

如何給 Cursor 提供 IronWord 文件?

在請求中加入 IronWord 的文檔鏈接,或將其存儲在整個團隊共享的規則中。 IronWord 的 llms.txt 列出了每個指南和 API 參考,llms-full.txt 將 46 頁文件壓縮成一個文件。截至 2026年 10 月,Cursor 的 @ 菜單附加了文件、文件夾、終端、聊天、Git 差異和瀏覽器,因此 IronWord 的文件作為鏈接發送給代理。

快速入門轉儲顯示了提取文本指南未描述的兩種行為。 對於 form-03,ExtractText 將正文段落文本連接為一個字符串,並省略了表單中兩個表格的所有文本。

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

如何編寫編碼 IronWord 約定的專案規則?

專案規則是存儲在 .cursor/rules 中的 .mdc 檔案,隨著倉儲進行版本控制,因此每次克隆都包含它。 Cursor 忽略該文件夾中的普通 .md 文件,因為沒有前言,它無法確定何時加載這些文件。

以下規則定義了 globs,並將 alwaysApply 設置為 false。 無論何時請求中包括表單讀取器或測試檔案,Cursor 都會加載它,否則不會。將其保存為 .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.
Markdown
請注意: Cursor也會讀取根目錄或任何子資料夾中的AGENTS.md。 該文件沒有前置說明和文件模式,因此IronWord規則,依賴其匹配模式,應位於.cursor/rules。

Cursor 的規則頁面聲明規則不會影響 Tab,而且使用者規則不應用於內聯編輯,因此 Tab 和內聯編輯建議需要手動檢查規則。

如何將 OpenXML SDK 調用映射到 IronWord?

指導模型使用 IronWord 不會告訴它哪個 IronWord 調用替換每個 OpenXML SDK 調用。 等價映射表提供了這種映射。

OpenXML SDKIronWord
WordprocessingDocument.Open從路徑、字節或流生成的 WordDocument 構造函數
正文段落及其內部文本Paragraphs,在每個上進行 ExtractText
正文表格、行和單元格Tables、Rows 和 Cells
Blip 元素和圖片部分流ExtractImages,通過 AnyBitmap 保存

兩行的行為與它們取代的 SDK 代碼不同。 段落列表包括表格單元格內的段落以及正文段落,因此 form-03 返回了 15 項目而 OpenXML SDK 讀取器僅遍歷了 5 個正文段落。單元格作為 ITableCell 返回,其中沒有文本方法,因此不轉型調用失敗並出現 CS1061。

IronWord 不參考 DocumentFormat.OpenXml package,並且一個同時引用了 IronWord 2026.10.4 及 DocumentFormat.OpenXml 3.5.1 的專案可以構建並運行。 因此,遷移可以按每次一個讀取器的步調進行。OpenXML 衝突頁面涵蓋了早於 2025.7.13 的 IronWord 構建。

將這些行添加到規則的末尾,將表表格放置在每次加載規則的請求中。

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

如何計劃並運行 IronWord 遷移?

在聊天輸入中按 Shift+Tab 直到選擇了計劃模式,然後發送下面的請求。 Cursor 將其計畫寫入一個可編輯的文件。

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

糾正計劃中的任何錯誤。 然後單擊構建或切換回代理並發送此請求。

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

@ironword-forms 提到是否應用規則,即使 Cursor 通過其球號已經附加它。

哪個 Cursor 功能適合每個變更?

Tab 補全了在編輯器中已經可見的編輯操作,內聯編輯(Ctrl+K)按照單句指令重寫選擇。 多個文件的變更或需要構建的變更發送到代理。 使用計劃模式時,錯誤變更所需的撤銷工作量大於編寫計畫所需。無人看管適合雲端代理。

一個新供應商返回了 form-13,其中價格表將一個項目單元格橫跨兩個價格層。 突出顯示 FormReader 中遍歷價格行的循環,按 Ctrl+Shift+L(macOS 上 Cmd+Shift+L) 將突出顯示的代碼添加到聊天輸入框,然後在代理中發送此請求。

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

行長度檢查解決了另一個方向的合併問題。 在一個單獨的測試文件中,合併跨列的單元格返回為一個單元格,因此該行比其他行短。

如何調試提取文本中缺少的值?

倉儲的預檢用正則表達式在 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.
Text

九次失敗有兩個原因。 在五個表單中,聯絡電郵的段落緊接在號碼之後,因此該表達式捕獲 GB-0012345Contact 並且格式檢查拒絕它。 其他四個將號碼存儲在公司詳細信息表中,標籤單元格讀取 註冊號碼 不帶冒號,值在下一個單元格中。 單獨讀取每個段落並從標籤旁邊的單元格中取得值可以解決這兩個問題。

IronWord 忽略 DOCX 哪些部分?

我們對 IronWord 2026.10.4 的測試識別出該程式庫未返回給表單讀取器的內容。

  • 頁眉: 沒有讀取返回頁眉文本,並且 ExtractImages 省略了頁眉圖片。 頁面設置公開了頁眉的高度,但沒有顯示其內容。
  • 內容控制和文本框: 它們的文本不存在於段落和提取的文本中。
  • 已跟蹤的變更: 讀取時未返回啟用跟蹤期間插入的文本。
  • 舊版文件: 載入 Word 97-2003 .doc 文件時引發“文件包含損壞的數據”。
  • 沒有間隔屬性的內聯圖片: DOCX 的內聯圖片省略了 distT、distB、distL 和 distR 並在載入時引發 InvalidOperationException。 python-docx 省略了這些屬性。

浮動圖片和表格單元格內的圖片按文件順序提取。 如果供應商完成了內置了內容控制的表單,或將註冊號碼放置在頁眉中,請在依賴讀取器之前測試這些表單。

如何為文檔讀取編寫回歸測試?

與已知列表比較提取值以檢查輸入服務的輸出,無論讀取器的內部實現如何。 雲端代理可以在其自己隔離的 VM 中寫入這些內容。 首先在雲代理儀錶板的 secrets 下儲存 IRONWORD_LICENSE_KEY。

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

舊版文件斷言不能引用 IronWord 的例外類型,因為它是內部的。 它派生自 FormatException,因此一個接受派生類型的斷言,如 xUnit 中的 Assert.ThrowsAny<FormatException>,編譯並在拋出不同錯誤時繼續失敗。

人工智慧編程助手指南 包括從端到端運行與書面通過標準比較的 IronWord 任務。

在實際運行中,這些提示產生了什麼結果?

七個提示按順序發送到 Cursor 的一個聊天中。 樣本庫包含了一個 OpenXML SDK 讀取器,一個 IronWord 預檢,一個空的 xUnit 專案,十二個已知值的表格和兩個邊緣文件。

  • OpenXML SDK 讀取器和替換它的 IronWord 讀取器都匹配所有 12 個表單。
  • IronWord 是應用和其測試中剩下的唯一 DOCX 類。
  • 添加 form-13 後,讀取器匹配 13 個中的 12 個並丟掉了第二價格層的項目名稱。
  • 在合併單元格更改之後,讀取器匹配 13 個中的 13 個。
  • 在修補之前預檢標記了 13 個中的 9 個表格,之後則沒有。 它兩次都將邊緣表單標記為沒有註冊號碼。
  • 所有 21 張保存的圖像都具有其列出的像素尺寸。
  • form-03 傾倒列表中有兩個表格中的 10 個單元格,以及一個 108 乘以 36 點和 144 乘以 48 像素的圖片。
  • 當詢問文件中有什麼內容時,Cursor 的答案沒有改變任何文件。
  • 六個測試方法的 42 個案例在有無授權金鑰的情況下都通過。
  • 在最終代碼的副本中,刪除合併單元格處理導致 2 個案例失敗。 恢復舊預檢失敗 9,並跳過每個表格中的一張圖像失敗 13。
  • 舊文件測試接受任何異常並當文件被刪除后通過。 縮小到 FormatException,它在真文件下通過而無文件時失敗。
  • Cursor 的首個 IronWord 讀取器缺少行轉型並在 CS1503 上構建失敗。在下一次構建之前,Cursor 添加了轉型。
  • 每次 Release 構建都有 0 警告和 0 錯誤,沒有手動編輯。
  • 一些步驟與頁面上運行的不同。 該規則缺少行轉型。合併單元格提示沒有請求行長度檢查,Cursor 沒有添加。 測試提示只要求拋出一個異常。 提示,包括 @ 提及,作為文本粘貼到桌面應用程式中。 計劃在代理中批准而不是使用構建按鈕。 雲代理提示在 Agent 模式下本地運行,無需 VM。

Claude Code 指南 添加了一個只讀子代理,該子代理在生成的代碼中檢查每個 IronWord 成員與 IronWord.xml。 ChatGPT Codex 指南 涵蓋編寫方,并衡量哪些 Word 文檔部分文字替換會更改。

運行記錄 列出這些結果的 IronWord package、模型、計時和測試機。


疑難排解


問題?

如果您有任何疑問,請聯繫support@ironsoftware.com

Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。

閱讀更多

準備好開始了嗎?

NuGet 下載次數 62,392版本:2026.11剛剛發布