如何使用 IronPPT 和 Cursor

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

当一个 AI 代理将一个 C# 报告幻灯片生成器从 Open XML SDK 转移到 IronPPT 时,通过直接翻译每个幻灯片调用,新幻灯片与旧幻灯片不同。 Open XML SDK 从一个空包开始。 一个新的 IronPPT PresentationDocument 已经包含一个幻灯片,所以直接迁移添加一个标题幻灯片和每个学生一个幻灯片,节省了一个第一张幻灯片为空的幻灯片。 在我们的测试中,同样的迁移也产生了 4:3 的幻灯片,而旧生成器写的是 16:9。

Cursor 是一个基于 VS Code 代码库构建的 AI 代码编辑器,带有一个编辑文件并运行命令的代理。 下面的迁移使用了它的两个功能,代理读取的文档链接和提交在 .cursor/rules 中的项目规则。 它将一个学校的报告幻灯片生成器转移到 IronPPT。 生成器从花名册文件中为每个班级构建一个学期报告幻灯片,包括一个标题幻灯片、每个学生一个幻灯片和一个结束幻灯片,迁移后的报告幻灯片必须保留学校签署的每一行文本。

有关涉及的调用,请参阅添加幻灯片指南和添加文本指南。

快速入门
NuGet使用NuGet安装

PM > Install-Package IronPPT

通过在 NuGet 包管理器控制台中运行上述命令安装 IronPPT,或在 NuGet 包管理器中搜索该包。

在打开 ReportDecks 存储库时,将此提示粘贴到新的 Agent 聊天中。

@src/ReportDecks/ @TestData/expected/

Add an inspect command to Program.cs that prints the outline of a deck.
It runs as `dotnet run --project src/ReportDecks -- inspect <deck.pptx>`.
Before you write it, check https://ironsoftware.com/ppt/csharp/llms.txt.
From there, open the guides on adding slides and on license keys.

The command opens the deck with IronPPT and prints one line per slide, in this form:
- The slide number, a colon and a space.
- The text of each non-empty paragraph on the slide, in order, joined with " | ".

The outlines in TestData/expected use the same form.

The program reads IRONPPT_LICENSE_KEY from the environment itself.
It sets License.LicenseKey from that value before it opens or saves a deck.
Never show the license key in output, and don't dump the environment variables.
Keep IronPPT on version 2026.10.1 and leave OpenXmlDeckWriter alone for now.

Then build the term report for TestData/classes/7B.json, inspect it and show me what it prints.
Text

不要将许可证密钥粘贴到聊天中,因为代理可以将其复制到源文件、提交或构建日志中。 IronPPT 2026.10.1 自身不会读取 IRONPPT_LICENSE_KEY。 它在环境或应用程序配置中查找名为 IronPPT.LicenseKey 的设置,这就是为什么在代码中设置 License.LicenseKey。 没有密钥时,在内存中构建幻灯片和读取幻灯片工作正常,Save 在写入文件前抛出 LicensingException。许可证密钥指南描述储存密钥的位置。



您应该为 IronPPT 工作使用哪种 Cursor 模型?

Composer是Cursor自己的代理模型。 模型选择器还提供Cursor共同开发的SpaceXAI的Grok模型,以及来自OpenAI,Anthropic,Google和其他实验室的模型。 下面的测试运行使用了 Composer 2.5。

您如何为 Cursor 提供 IronPPT 文档?

在请求中包含 IronPPT 的文档链接,或将其存储在整个团队共享的规则中。 IronPPT 的 llms.txt 列出了每个指南和 API 参考,llms-full.txt 将 16 页文档压缩成一个文件。截至 2026 年 10 月,Cursor 的 @ 菜单附加文件、文件夹、终端、聊天、Git 差异和浏览器,所以请求以链接形式给代理提供 IronPPT 的文档。

添加幻灯片指南指出一个新的演示文稿已经包含一个空白幻灯片。IronPPT 的 skill.md 称相同的对象为新的空白演示文稿,而没有页面链接到 llms.txt 声明新幻灯片的大小。

@src/ReportDecks/ParentEveningDeck.cs

Answer five questions about IronPPT, and don't change any files:
1. How many slides does a new PresentationDocument hold before AddSlide is called?
2. Where does AddSlide put the new slide, and what does it return?
3. Where does text passed to PresentationDocument.AddText end up?
4. Can IronPPT set the slide size, and what size does a new deck use?
5. Can IronPPT write speaker notes?

Base every answer on https://ironsoftware.com/ppt/csharp/llms.txt or a page it links to.
Name the page each answer comes from.
If no page answers a question, tell me so rather than guess.
Text

如何编写编码您 IronPPT 约定的项目规则?

项目规则是一个存储在 .cursor/rules 中的 .mdc 文件,并与存储库版本化。 Cursor 在该文件夹中忽略一个普通的 .md 文件,因为没有前导物的文件无法让它决定何时加载规则。

以下规则在 globs 中列出它的文件模式,按照 Cursor 的规则页面指定的逗号分隔,并将 alwaysApply 设为 false。 然后,Cursor 在涉及幻灯片代码或测试的请求中加载它。 将其保存为 .cursor/rules/ironppt-decks.mdc。

---
description: IronPPT conventions for the report deck code
globs: src/ReportDecks/**/*.cs, tests/**/*.cs
alwaysApply: false
---

Follow these rules in the report deck code:
- Build decks with IronPPT 2026.10.1 from NuGet, namespace IronPPT.
- Don't add another presentation package.
- Look up IronPPT members in https://ironsoftware.com/ppt/csharp/llms.txt and its linked pages.
- The program reads the key from IRONPPT_LICENSE_KEY.
- Never write the key to output or files.
- A new PresentationDocument starts with one slide already, and AddSlide appends after it.
- Fill that first slide, or remove it once the deck has another slide.
- A new PresentationDocument is 4:3.
- For a 16:9 deck with the school's title slide, open TestData/templates/hollybrook-16x9.pptx.
- On slides you add, put the lines in one TextBox as Paragraphs.
- Each AddText call on a slide creates another text box of the same size, with no position.
- PresentationDocument.AddText joins its text to the last paragraph of the last slide.
- Don't use PresentationDocument.AddText.
- Check every deck you save with the inspect command against TestData/expected.
- If an IronPPT member isn't in the docs, say so and cite the page you searched.
Markdown
请注意: Cursor还会读取根目录或任何子文件夹中的AGENTS.md。 那个文件没有前置内容和文件模式,因此依赖于全局变量的规则应该放在.cursor/rules中。

规则适用于Agent请求。 Cursor 的规则页面声明规则不影响 Tab,并且用户规则不适用于内联编辑,因此需要手动根据规则审查这些建议。

如何映射 Open XML SDK 调用到 IronPPT?

Open XML SDK 部分地写入一个软件包,因此旧生成器也创建幻灯片母版、布局、主题和备注母版。 IronPPT 自行创建这些部分。

Open XML SDKIronPPT
PresentationDocument.Create 带演示文稿部分、母版、布局和主题new PresentationDocument(),或带模版路径的构造函数
一个添加到演示文稿部分并列在SlideIdList中的 SlidePartAddSlide(new Slide()),添加幻灯片
标题和正文占位符填充 A.Paragraph 和 A.Run用 TextBox 的 Slide.AddChild,每行一个 Paragraph
在现有占位符中的文本加载模板的幻灯片上的 Texts[i].Text
顺序排列的 SlideSize 值:12192000 × 6858000没有对应项,因此大小来自模板
每个幻灯片的 NotesSlidePart没有等效物
到文件的 Save 或任何 Stream只是一个文件路径的 Save(string)

IronPPT.dll 嵌入了其自己的 Open XML SDK 类型拷贝,所有都在内部,因此迁移期间使用两个包引用构建项目。

为什么新的 IronPPT 幻灯片从额外幻灯片开始?

一个新的 PresentationDocument 的内置幻灯片使用一个标题布局,其标题和副标题占位符是空的。 在其后添加 AddSlide 并返回给定的幻灯片,因此直接转移的每张幻灯片在签署的纲要中出现的顺序都向后推了一位。

太早移除该幻灯片会失败。 当它是唯一幻灯片时调用 Remove 会抛出 InvalidOperationException,表明演示文稿必须至少包含一张幻灯片。当存在第二张幻灯片时,相同的调用成功。

幻灯片大小是第二个差异。 一个新的幻灯片测量为 9144000 x 6858000 EMU,属于 4:3 幻灯片。API 参考文档中的 Slide.Width 和 Slide.Height 设置宽度为 960 点的示例,但没有属性改变幻灯片的大小。 将它们设为 960 x 540 点将 12192000 x 6858000 EMU 写入幻灯片的形状范围,并将幻灯片大小在 ppt/presentation.xml 中保持为 9144000 x 6858000 EMU。 从一个16:9文件加载的幻灯片通过保存保持其 12192000 x 6858000 EMU,保留其占位符和备注。 因此,存储库在 TestData/templates/hollybrook-16x9.pptx 中保留了学校的标题幻灯片。

您如何计划和运行迁移到 IronPPT?

在聊天输入中按 Shift+Tab,直到选择计划模式,然后发送下面的请求。 Cursor 将计划写为可编辑的 Markdown 文件。

@src/ReportDecks/OpenXmlDeckWriter.cs @TestData/expected/7B-term-report.txt

Plan how to move the term report deck from the Open XML SDK to IronPPT.
Don't write any code until I approve the plan.
Leave ParentEveningDeck out of it, since it already uses IronPPT.

The plan needs to answer these questions:
- Which IronPPT call replaces each Open XML SDK step the writer takes?
- How does the deck keep 16:9 slides and avoid an extra blank slide?
- Where do the tutor comments go, given that they're speaker notes today?
- How does the build command keep its arguments and its output path?

Roster.cs and DeckText.cs stay as they are.
End with a list of the assumptions you made.
Text

纠正计划中的任何错误。 然后在计划模式下构建计划,或切换回代理并发送此请求。

@ironppt-decks

Go ahead with the approved plan.

If IronPPT can't write speaker notes, the tutor comments go in a text file beside the deck:
- For out/7B-term-report.pptx, the file is out/7B-term-report.comments.txt.
- It holds one "Name: comment" line per pupil, in roster order.

Work through these steps in order:
1. Build and inspect the 7B term report.
2. Count the lines that match TestData/expected/7B-term-report.txt.
3. Replace OpenXmlDeckWriter with an IronPPT class named TermReportDeck.
4. Remove DocumentFormat.OpenXml from the project file.
5. Build the solution, then build, inspect and count again.

Tell me both match counts, before and after, and show me the diff.
Text

@ironppt-decks 提到按名称附加规则。

Cursor功能适合哪个变化?

根据更改范围选择一个功能。 Tab 补全开发人员已开始的编辑。 对于一句话可以描述的选择,使用内联编辑(Ctrl+K)。 代理处理跨多个文件的更改以及需要构建的工作,而计划模式在代理更改任何代码之前添加一个可以复审的计划。

在 Agent 中发送此请求。 它命名了它所更改的方法,因此在编辑器中不需要选择。

@src/ReportDecks/

Make TermReportDeck.Write check its own output once it saves the deck:
- Reopen the saved deck with IronPPT.
- Throw if the slide count isn't the pupil count plus 2.
- Throw if any slide has no text, with that slide's number in the message.

Have the build command print that message and exit with code 3.
Then build the decks for TestData/classes/7B.json and TestData/classes/8A.json.
Show me what each build prints.
Text

IronPPT 如何放置幻灯片添加的文本?

在同一个主体占位符上对一个幻灯片进行了 5 次 Slide.AddText 调用,产生了 5 个 1905000 x 1270000 EMU 形状。 AI 代理中心解释了为什么这些形状共享一个位置。 每行一个 Paragraph 的 TextBox 给出一个有顺序行的形状。 纲要检查不会检测到默认大小下留下的框,因为它只读取文本。

PresentationDocument.AddText 的表现与幻灯片方法不同。 它在最后一个幻灯片的最后段落末尾添加了一次新的运行,没有空格或换行符。 通过 Slide.Texts 回读,两个运行显示为单独的项目。 Slide.Paragraphs 返回观众所见的行,这就是为什么检查命令读取段落的原因。

如何调试 IronPPT 已写的幻灯片?

家长会幻灯片在迁移之前已经使用了 IronPPT。

@src/ReportDecks/ParentEveningDeck.cs @TestData/expected/7B-parents-evening.txt

Find out why none of the 7B evening deck's lines match 7B-parents-evening.txt.
The office also reports black bars at the sides when the hall screen shows it.

Diagnose it before you touch any code:
1. Build the evening deck, inspect it and compare it with the expected outline.
2. List each line that differs.
3. Explain what in ParentEveningDeck causes each difference.

After that, fix ParentEveningDeck and keep it on IronPPT.
Add the output check the term report has, with pupils plus 1 as the slide count.
Inspect the deck again and tell me how many lines match before and after the fix.
Text

输出

下面的图显示了修复前幻灯片中的一个预约幻灯片和修复后幻灯片中的一个。

家长会幻灯片的幻灯片 3,修复前为 4:3 幻灯片,包含两个重叠的文本形状

家长会幻灯片的幻灯片 3,修复前,从保存文件的 XML 绘制。4:3 幻灯片在同一位置包含两个文本形状。图显示的是存储的几何形状,而不是 PowerPoint 渲染。

家长会幻灯片的幻灯片 2,修复后为 16:9 幻灯片,包含一个小文本框

家长会幻灯片的幻灯片 2,修复后,从保存文件的 XML 绘制。16:9 幻灯片包含一个 1905000 x 1270000 EMU 的文本框。图显示的是存储的几何形状,而不是 PowerPoint 渲染。

如何为幻灯片编写回归测试?

@src/ReportDecks/ @TestData/

Write xUnit tests in tests/ReportDecks.Tests and add that project to the solution.

The tests cover these cases:
- The 7B term report matches every line of TestData/expected/7B-term-report.txt.
- The 7B evening deck matches every line of TestData/expected/7B-parents-evening.txt.
- Both decks are 16:9, which is 12192000 by 6858000 EMU in ppt/presentation.xml.
- Every slide after the first keeps its text in one text box.
- The 8A term report has 5 slides, with pupils in roster order.
- The comments file has one line per pupil, in roster order.
- The output check throws for a saved deck with an empty slide and names that slide.

If the output check has no method of its own that takes a saved deck, add one.
Write test decks to a temp folder, not to out/.
Run dotnet test, then give me the pass and fail totals.
Text

Slide.Width 和 Slide.Height 在新幻灯片和打开的 16:9 幻灯片上返回了空值,因此大小测试读取 ppt/presentation.xml。

在实际运行中这些提示生成了什么?

每个构建和检查如下在每个更改代码的提交的全新发布版本上重复,并且一个单独的脚本读取每个保存的幻灯片。

  • 移动前,Open XML SDK 幻灯片符合已签署纲要的所有 8 行。
  • 移动到 IronPPT 后,学期报告幻灯片也符合所有 8 行。
  • 迁移后的幻灯片通过打开学校的模板保持了 12192000 x 6858000 EMU 的 16:9 幻灯片。
  • Cursor 填充了模板的标题幻灯片,因此 7B 幻灯片包含 8 张幻灯片且没有空白幻灯片。
  • 每个学生幻灯片的文本都保留在一个单一的 1905000 x 1270000 EMU 文本框中,没有它自己的位置。
  • Open XML SDK 幻灯片持有 6 张备注幻灯片,而 IronPPT 幻灯片没有。
  • 六条导师评论被转移到 7B-term-report.comments.txt 中,每名学生一行按照花名册顺序。
  • Cursor 回答了来自引用页面的五个文档问题并没有更改文件。
  • Cursor 未找到任何说明 PresentationDocument.AddText 将文本放置在哪里的页面。
  • 对于幻灯片大小,Cursor 引用了 Slide.Width 和 Slide.Height。 这个答案是不正确的。
  • 输出检查拒绝了带有空学生项的名单,打印了“幻灯片 2 没有文本”并以代码 3 退出。
  • 修复前的家长会幻灯片匹配的7行中0行,并使用了 4:3 幻灯片。
  • 修复后,家长会幻灯片在 16:9 幻灯片上匹配 7 行中的 7 行。
  • Cursor 报告的匹配计数与对两个幻灯片的独立检查一致。
  • xUnit 套件通过了 9 次测试中的 9 次,涵盖了请求的七个案例。
  • 每个发行版本输出没有错误,测试项目添加了一个 xUnit 解析器警告。
  • 有些步骤与页面中的运行不一样。 所有七个提示通过一个无头会话进入 Cursor CLI。 CLI 在提示 03 中跳过了来自 Cursor 关于演讲者备注的问题,并在提示 05 中跳过了关于错误输出的问题。会话恢复后,提示 05 到 07 在计划模式下运行,因此一条后续信息“构建计划。”执行了每个计划。 对于提示 04 中的差异,Cursor 将纲要与预期文件进行比较,而不是显示代码更改。

GitHub Copilot 指南将其部分的 IronPPT 约定限制为源和测试项目,使用路径特定说明文件,如此处的 globalrule。 Claude Code 指南 也在其幻灯片生成器编写之前批准计划。 run record 列出了 Cursor 版本、模型和本次运行持续时间,并提供测试机。


故障排除


有问题吗?

如果您有任何问题,请联系support@ironsoftware.com

Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。

阅读更多

准备开始了吗?

NuGet 下载量 7,110版本:2026.11刚刚发布