如何使用 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 倉庫,將此提示粘貼到一個新的代理聊天中。

@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。 授權金鑰指南 描述了將金鑰存儲在其他位置的方法。



您應該使用哪個 Cursor 模型進行 IronPPT 工作?

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沒有等效物
到文件或任何 Stream 的 Save只有文件路徑的 Save(string)

IronPPT.dll 嵌入了自己版本的全內部 Open XML SDK 類型,因此在遷移期間項目同時引用了這兩個包。

為什麼新的 IronPPT 組以多出的一張幻燈片開始?

新的 PresentationDocument 的內置幻燈片使用的是標題佈局,標題和副標題占位符是空的。 AddSlide 在它之後附加並返回給定的幻燈片,因此直接移植的每一張幻燈片都會比批準的綱要中的幻燈片位置多一位。

過早移除該幻燈片會失敗。 當它是唯一一張幻燈片時調用 Remove 時,丟擲了 InvalidOperationException,表明一個演示文稿中至少要包含一張幻燈片。當存在第二張幻燈片時,同一個調用成功。

幻燈片尺寸是第二個不同之處。 新組尺寸為 9144000 乘以 6858000 EMU,一張4:3幻燈片。API 參考 @@Slide.Width 和 Slide.Height 配備一個設置寬度為 960 點的示例,但兩個屬性都不會改變組的幻燈片尺寸。 將它們設置為 960 乘以 540 點將 12192000 乘以 6858000 EMU 寫入到幻燈片形狀的範圍,而幻燈片尺寸在 ppt/presentation.xml 中保持在 9144000 乘以 6858000 EMU。 從16:9文件加載的組在保存過程中保持 12192000 乘以 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)。 代理處理多個文件的更改和需要構建的工作,而計劃模式在代理更改任何代碼之前添加計劃供審查。

在代理中發送此請求。 它命名需更改的方法,因此在編輯器中不需要選擇。

@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 如何放置幻燈片添加的文本?

在一張幻燈片上執行的五個 Slide.AddText 調用在相同的正文占位符上生成五個 1905000 乘以 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

輸出

下面的圖示顯示了修復前組中的一張會面幻燈片和修復後組中的一張。

修復前的家長晚會組第三張幻燈片,一張4:3幻燈片,包含兩個重疊的文本形狀

修復前的家長晚會組第三張幻燈片,從保存文件的 XML 繪製。4:3幻燈片在同一位置包含兩個文本形狀。圖示顯示的是存儲的幾何形狀,而非 PowerPoint 渲染。

修復後的家長晚會組第二張幻燈片,一張16:9幻燈片,具有一個小文本框

修復後的家長晚會組第二張幻燈片,從保存的文件 XML 繪製。16:9 幻燈片包含一個 1905000 乘以 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

在新的組和打開的16:9 組上,Slide.Width 和 Slide.Height 返回空值,因此尺寸測試讀取 ppt/presentation.xml。

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

下面的每個生成和檢查在每次更改代碼的提交的全新釋出生成上重複進行,並且每個保存的組由單獨的腳本讀取。

  • 在遷移前的 Open XML SDK 組匹配批准的綱要中的所有8行。
  • 遷移到 IronPPT 之後,學期報告組也匹配所有8行。
  • 遷移組在打開學校的模板時保持12192000 乘以 6858000 EMU 的16:9 幻燈片。
  • Cursor 填寫了模板的標題幻燈片,因此7B組持有8張幻燈片且沒有空白幻燈片。
  • 每個學生的幻燈片將其文本保留在一個 1905000 乘以 1270000 EMU 的文本框中,沒有自己的位置。
  • Open XML SDK 組持有 6 張註釋幻燈片,而 IronPPT 組則沒有。
  • 六條輔導員評論被記錄在 7B-term-report.comments.txt,每個學生一行,按名冊順序排列。
  • Cursor 回答了引用頁面上的五個文檔問題但未更改文件。
  • Cursor 找不到指出 PresentationDocument.AddText 將其文字置於何處的頁面。
  • 有關幻燈片尺寸,Cursor 引用了 Slide.Width 和 Slide.Height。 該答案是不正確的。
  • 輸出檢查拒絕了一個包含空學生條目的名冊,打印“幻燈片 2 無文字”並以代碼 3 退出。
  • 修正之前,晚間投影片符合 0 個 7 行並使用 4:3 幻燈片。
  • 在修復之後,晚會組在 16:9 幻燈片上匹配了 7 行中的 7 行。
  • Cursor 報告的匹配數和對兩組進行的獨立檢查一致。
  • xUnit 組合通過了 9 項測試中的 9 項,覆蓋了要求的七個案例。
  • 每個釋出生成中出現了 0 個錯誤,測試項目新增了 1 個 xUnit 分析器警告。
  • 一些步驟與頁面上運行的不同。 所有七個提示都通過 Cursor CLI 經過一次無頭會話。 CLI 跳過了 Cursor 在提示 03 上的演講者註解問題和在提示 05 上的錯誤輸出問題。在會話恢復期間,提示 05 到 07 在計劃模式中運行,因此後續消息,“構建計劃。”,執行了每個計劃。 對於提示 04 中的差異,Cursor 將綱要與預期文件進行比較,而不是顯示代碼更改。

GitHub Copilot 指南 將部分 IronPPT 約定限於具有路徑特定指導文件的源和測試項目,就像此處的通配符一樣。 Claude Code 指南 在撰寫組生成器之前也批准一個計劃。 運行記錄 列出了此運行的 Cursor 版本、模型和持續時間,以及測試機器。


疑難排解


問題?

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

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

閱讀更多

準備好開始了嗎?

NuGet 下載次數 7,110版本:2026.11剛剛發布