如何使用IronWord与Cursor一起
本指南的示例库使用OpenXML SDK代码读取供应商表单,该代码遍历正文元素并读取InnerText。 通过使用正则表达式解析从一个提取文本块中标记的每个值,将该阅读器移至IronWord会失败。 在校准过程中,该版本正确读取了12个表单中的3个,将五个注册号码连接到以下标签,并且对四个表单表没有返回注册号码。
Cursor基于VS Code代码库构建,并在编辑器旁提供一个代理。 它的两个功能,即代理读取的文档链接和提交在.cursor/rules中的项目规则,决定了它生成IronWord代码还是遵循OpenXML阅读器模式的代码。 以下两项功能出现在供应商入职服务中,该服务读取供应商返回的DOCX表单。 该服务提取供应商名称、注册号码、价格列表表和嵌入的徽标及签名图像,并且其阅读器从OpenXML SDK转移到IronWord。
有关IronWord阅读方法的详细信息,请参阅文本提取指南和图像提取指南。
快速入门在供应商入库存储库打开的情况下,将此提示粘贴到一个新Agent聊天中。
@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.
请勿在聊天中输入许可证密钥。 代理会编辑文件并运行shell命令,因此粘贴的密钥会暴露在它编写的每个文件、提交消息和构建日志中。 在我们的测试中,IronWord打开并读取了每个表单而无需密钥,仅在保存文档时抛出LicensingException。 许可证密钥指南展示了如何在代码中、在Web.config中或在appsettings.json中设置密钥。
最小工作流程(5 个步骤)
- 从NuGet下载C# Word库
- 在.cursor/rules下面添加包含IronWord文档链接的项目规则
- 在规则中记录
ExtractText遗漏的内容 - 在每个请求中引用读取器文件和一个返回表单的文件夹
- 将每个提取的值与已知列表进行比较,然后在API参考中确认每个成员名称
您应该使用哪个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.
您如何编写编码您的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.
Cursor的规则页面声明规则不影响Tab,并且用户规则不应用于内联编辑,因此需要手动检查Tab和内联编辑建议是否违反规则。
您如何将OpenXML SDK调用映射到IronWord?
指示模型使用IronWord不会告诉它哪个IronWord调用替换每个OpenXML SDK调用。 等价表提供了这个映射。
| OpenXML SDK | IronWord |
|---|---|
WordprocessingDocument.Open | WordDocument构造函数,来自路径、字节或流 |
| 主体段落及其内部文本 | Paragraphs,每个上有ExtractText |
| 主体表格、行和单元格 | Tables, Rows和Cells |
| Blip元素和图像部分流 | ExtractImages,通过AnyBitmap保存 |
与它们替换的SDK代码行为不同的两行。 段落列表包含表格单元格内的段落以及正文段落,因此form-03返回15个条目,而OpenXML SDK阅读器遍历5个正文段落。返回的单元格为ITableCell,没有文本方法,因此不带转换的调用无法通过CS1061构建。
IronWord不引用DocumentFormat.OpenXml包,并且引用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).
您如何计划和运行迁移到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.
纠正计划中的任何错误。 然后点击构建或切换回Agent并发送此请求。
@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.
@ironword-forms提及应用规则名,无论Cursor是否已经通过其globs附加它。
Cursor功能适合哪个变化?
Tab完成在编辑器中已经可见的编辑,内联编辑(Ctrl+K)从一个句子指令重写选择。 跨多个文件的更改或需要构建的更改将发送到Agent。 当不正确的更改比编写计划花费更多精力撤销时,使用计划模式。云代理适合无人值守的工作。
一位新供应商返回了form-13,其价格表将一个项目单元合并到两个价格层次中。 突出显示FormReader中迭代价格行的循环,按Ctrl+Shift+L(在macOS上为Cmd+Shift+L)将突出显示的代码添加到聊天输入中,并在Agent中发送此请求。
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.
行长度检查解决了另一个方向的合并问题。 在单独的探测文件中,跨列合并的单元返回为一个单元,因此该行比其他行短。
您如何调试提取文本中缺失的值?
存储库的预检查使用正则表达式读取注册号码,以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.
九次失败的原因有两个。 在五个表单中,一个联系电子邮件段落跟随号码,因此表达式捕获GB-0012345Contact并且格式检查拒绝它。 另外四个将号码存储在公司详细信息表中,其中标签单元读取注册号码而没有冒号,值在下一个单元。 单独读取段落并从标签旁边的单元格中获取值解决了这两个问题。
IronWord遗留哪些DOCX部分?
我们对IronWord 2026.10.4进行的探测识别出图书馆未向表单阅读器返回的内容。
- 页眉:没有读取返回页眉文本,而
ExtractImages省略页眉图像。 页面设置暴露了页眉的高度但没有其任何内容。 - 内容控件和文本框:它们的文本既没有出现在段落中,也没有出现在提取文本中。
- 跟踪的变更:阅读过程省略了在启用跟踪时插入的文本。
- 遗留文件:加载Word 97-2003 .doc文件会抛出"数据损坏的文件"。
- 没有间距属性的嵌入图片:如果DOCX的嵌入图片省略distT, distB, distL和distR,无法加载并抛出InvalidOperationException。 python-docx省略了这些属性。
浮动图片和表格单元格内的图片按文档顺序提取。 如果供应商填写的表单带有内容控件,或者将注册号码放在页眉,请在依赖阅读器之前测试这些表单。
如何编写文档阅读的回归测试?
将提取的值与已知列表进行比较的测试检查入库服务的输出,而不考虑阅读器的内部实现。 云代理可以在其自己隔离的虚拟机中编写它们。 首先在云代理仪表盘下的秘密中存储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.
遗留文件断言不能引用IronWord的异常类型,因为它是内部的。 它派生自FormatException,因此接受派生类型的断言,如xUnit中的Assert.ThrowsAny<FormatException>,在抛出不同错误时仍能编译并失败。
AI编码助手指南包含一个IronWord任务,从头到尾按照编写的通过标准运行。
在实际运行中这些提示生成了什么?
七个提示以一个聊天的顺序发送给Cursor。 示例库持有一个OpenXML SDK阅读器、一个IronWord预检查、一个空xUnit项目、12个具有已知值的表单和两个边缘文件。
- 替换的OpenXML SDK阅读器和IronWord阅读器各自匹配所有12个表单。
- IronWord是应用程序及其测试中剩下的唯一DOCX包。
- 在添加form-13后,阅读器匹配13个中的12个,并从第二价格层次中丢弃了项目名称。
- 在合并单元格更改后,阅读器匹配了13个中的13个。
- 修复前预检查标记了13个中的9个,修复后没有标记。 每次都没有注册号码的边缘表单被标记。
- 保存的所有21张图像都有其列出的像素大小。
- form-03转储列出了两个表中的10个单元格和一个尺寸为108x36点和144x48像素的图像。
- 问及文档内容时,Cursor回答而不改变任何文件。
- 来自六种测试方法的全部42个用例都通过了,无论有没有许可证密钥。
- 在最终代码的副本中,删除合并单元格处理会导致2个用例失败。 恢复旧的预检查导致9个失败,跳过每个表单的一个图像导致13个失败。
- 遗留文件测试接受任何异常,并在文件删除时通过。 缩小到FormatException,它能在真正的文件中通过,而在没有它时失败。
- Cursor的第一个IronWord阅读器缺少行转换,无法通过CS1503构建。Cursor在下次构建之前添加了转换。
- 每个Release构建都有0个警告和0个错误,无需手动编辑。
- 有些步骤与页面中的运行不一样。 规则缺少行转换。合并单元格提示未请求行长度检查,Cursor没有添加。 测试提示只要求抛出异常。 提示,包括@提及,被粘贴到桌面应用程序中作为文本。 该计划在Agent中获得批准,而不是使用构建按钮。 云代理提示在Agent模式下本地运行,无需虚拟机。
Claude Code指南添加了一个只读子代理,它检查生成代码中的每个IronWord成员是否符合IronWord.xml。 ChatGPT Codex指南涵盖了写作方面,并衡量了文本替换改变的Word文档部分。
运行记录列出了这些结果的IronWord包、模型、时间和测试机器。
故障排除
- 当提取的文本中缺少表格内的值时从DOCX提取文本
- 当保存的图像需要检查其大小或格式时从DOCX提取图像
- 在迁移期间同时在一个项目中引用这两个包时IronWord与DocumentFormat.OpenXml
- 当生成的代码在保存时抛出许可异常时使用许可证密钥
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。