如何使用IronZIP與Cursor

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

這份指南中的.NET 9服務ClientDrop,將每個客戶的文件資料夾打包成客戶下載的ZIP。 它使用System.IO.Compression構建這些包,其中無法設置密碼,並且合規性現在希望每個包都用AES-256保護。捆綁代碼必須移至IronZIP,並且由AI代理商所做的移動具有較少可見的風險。 IronZIP和System.IO.Compression在詳細信息上有分歧,儘管仍然編譯。System.IO.Compression保留每個打包文件的資料夾路徑,而IronZIP的Add僅保留文件名稱,因此來自不同月份的兩份聲明可能接收到同一個條目名稱。

端口使用了三個Cursor功能。 一個提交的專案規則命名了要放棄的System.IO.Compression習慣,在計畫模式中,代理會在任何文件更改之前將映射寫入計畫中,而提示中的文件和規則中的文檔鏈接會將代理引導到IronZIP的頁面。 每個ClientDrop包在構建時加密,使用該密碼解壓以證明它仍然握有所有文件,當測試計算其條目時,再次使用其密碼打開。

快速開始
NuGet使用NuGet安裝

PM > Install-Package IronZip

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

在Cursor中打開ClientDrop,將其粘貼到Agent中。 其兩次提及會附上包類和一個客戶的資料夾。

@src/ClientDrop/Bundles/BundleBuilder.cs @TestData/clients/C-1042/

Fetch https://ironsoftware.com/zip/csharp/llms.txt first and read it before any edit.
BundleBuilder packs a client folder with System.IO.Compression.
Run dotnet test once and report the result.

Then make these changes:
1. Add the IronZIP package, version 2026.10.2, to src/ClientDrop.
2. Give Program.cs an "inspect <zip> [password]" command that opens a bundle with IronZIP.
3. Have inspect print each entry's name, size and whether it is encrypted.
4. Assign License.LicenseKey the value of IRONZIP_LICENSE_KEY.
5. Keep the key out of all output, and don't list the environment variables.
6. Keep BundleBuilder.cs unchanged.

Bundle C-1042 with the current code, run inspect on out/C-1042.zip and show me the output.
Text

檢查命令讀取舊包並列出七個條目及其資料夾路徑,從根目錄的contract.pdf到statements/2026-05/statement.pdf,並且其中都未加密。

在每個提示中都不包含授權密鑰。 在Agent模式中,Cursor編寫代碼並執行終端命令,因此鍵入到對話中的密鑰可以複製到代碼或提交消息中。 改為設置IRONZIP_LICENSE_KEY環境變量。 IronZIP不會自行讀取該變量,這就是為何提示將代碼分配給License.LicenseKey的原因。 在設置變量且未分配的探測中,保存調用拋出了LicensingException,內容為"需要生產許可證"。 許可證金鑰指南涵蓋了IronZIP自行查找的位置,例如Git可以忽略的appsettings.json文件。



您應該使用哪種Cursor模型處理IronZIP工作?

Composer是Cursor自己的代理模型。 模型選擇器還提供了Cursor共同開發的SpaceXAI的Grok模型以及來自OpenAI、Anthropic、Google和其他實驗室的模型。 這份指南中使用的是Grok 4.7。無論您選擇哪種模型,都要在提示中命名文件、測試和預期計數。

如何提供IronZIP文檔給Cursor?

IronZIP的llms.txt是一個列出其示例和教程的單頁面,並對每個簡單總結。 截至2026年10月,Cursor中的@菜單提供瀏覽器、Git差異、終端、過去的聊天、文件和資料夾,沒有文檔條目,因此提示將IronZIP的文檔作為鏈接提供。

端口取決於資料夾路徑的去向以及IronZIP何時檢查密碼。 下一個提示要求Cursor從頁面回覆並說明何時沒有頁面涵蓋某一點。

@src/ClientDrop/Bundles/BundleBuilder.cs

Your only source is https://ironsoftware.com/zip/csharp/llms.txt plus the example pages it links.
Do not edit files.
List each System.IO.Compression call in BundleBuilder.
Next to each call, name the IronZIP member that would replace it.

Then answer three questions:
1. Does Add keep the folder path of the file it is given?
2. Which call encrypts a new archive with AES-256?
3. For an existing protected archive, is the password checked at the constructor or at extraction?

Cite the page URL behind every answer, and say plainly when no page covers a point.
Text

頁面將加密問題以兩部分回答。 密碼示例調用Encrypt與EncryptionMethods.Traditional,訪問示例則將同一調用切換到AES-256。沒有頁面說明Add如何處理資料夾路徑。 兩頁誤導。 訪問示例表示錯誤密碼導致操作失敗,僅在解壓時如此,添加文件示例使用FromFile打開現有ZIP,這會構建一個新存檔,將該ZIP作為單個條目保留。 IronZipArchive參考記錄了示例頁面未顯示的成員,例如SetPassword和RemoveEncryption。

請注意: IronZIP還發布了一個技能文件,其前欄名為ironzip。 保存為.cursor/skills/ironzip/SKILL.md,它會在Cursor啟動時被發現,在Agent中輸入/ironzip會將其附加到一則消息上。

如何撰寫編碼IronZIP習慣的專案規則?

專案規則為.cursor/rules下的.mdc文件,隨代碼一同提交,每個都為Markdown格式,帶有前欄塊。 規則系統會跳過.cursor/rules下的純.md文件,因為這樣的文件沒有前欄塊。 description、globs和alwaysApply欄位決定了Cursor何時應用此規則。

此規則以globs範圍設定,因此Cursor將其應用於有文件資料或測試的任何請求,@ironzip-bundles則按名稱附加它。 幾個模式可置於一行,用逗號分隔。 保存為.cursor/rules/ironzip-bundles.mdc。

---
description: Move ClientDrop bundle code from System.IO.Compression to IronZIP
globs: src/ClientDrop/**/*.cs, tests/ClientDrop.Tests/**/*.cs
alwaysApply: false
---

ClientDrop writes bundles with IronZIP and follows these rules:
- Use IronZIP only. Its package ID is IronZIP and its namespace is IronZip.
- Remove System.IO.Compression from src/ClientDrop.
- Do not add SharpZipLib, DotNetZip or another archive package.
- IronZIP's docs start at https://ironsoftware.com/zip/csharp/llms.txt.
- Set License.LicenseKey from IRONZIP_LICENSE_KEY.
- Never write a license key or a bundle password into code, tests or logs.
- Encrypt every bundle with EncryptionMethods.AES256 and BundleOptions.Password.
- Open an existing bundle with new IronZipArchive(path, password).
- FromFile, FromFiles and FromDirectory build a new archive instead.
- Do not invent IronZIP members. For a member no page documents, say so and cite the page searched.
Markdown

FromFile行存在的原因是用FromFile打開包不會引發錯誤,原始包保持不變。

此規則僅影響Agent請求。 根據Cursor規則頁面上的FAQ,Tab完成忽略規則,內嵌編輯(Ctrl+K)忽略用戶規則。

如何將System.IO.Compression調用映射到IronZIP?

僅說"使用IronZIP"的規則讓模型算出每次調用應變成什麼。 每個IronZIP結果都是用IronZIP 2026.10.2在客戶C-1042上測量的,其資料夾包含七個文件,其中三個命名為statement.pdf,兩個命名為invoice.pdf位於不同月份資料夾中。

System.IO.Compression調用期望IronZIP
ZipFile.CreateFromDirectory七個條目,保留資料夾FromDirectory(於技能文件中顯示),僅打包contract.pdf
每個文件的CreateEntryFromFile每個文件為一個條目Add在四個名稱下存儲了七個條目,解壓後留下四個文件
在更新模式下Delete和CreateEntryFromFile重新發行的文件保持其名稱ReplaceEntry按其給定的路徑命名新條目,這裡是ZipWork/cursor/repo-baseline/TestData/reissue/C-1042/contract.pdf
ZipFile.OpenRead在測試中每個條目可讀列出了AES條目,並讀取其中一個引發InvalidDataException "不支持的壓縮方法"

在重複名稱的捆綁包上,ReplaceEntry在任何重命名前失敗。 它因"已經添加了具有相同鍵的項目"的ArgumentException而拋出,針對兩個名為invoice.pdf的條目。 加密本身起作用了。 Encrypt與EncryptionMethods.AES256將所有七個條目標記為加密,並將資料夾以獨特的平面名稱進行分段拷貝,例如statements_2026-03_statement.pdf,解壓為七個匹配原始文件的文件。重複名稱是最難捕捉的問題,因為即使丟失聲明,包仍持有七個條目,因此計數檢查通過,而客戶下載了四個文件。

將翻譯追加到規則中。

The port translates System.IO.Compression habits this way:
- Add keeps only the file name.
- Copy each file to a staging folder under a name unique in the bundle, and add the copy.
- One such name is statements_2026-03_statement.pdf.
- ReplaceEntry names the new entry after the path it is given.
- To swap a document, Delete the entry and Add a staged copy named like the old entry.
- System.IO.Compression cannot read AES entries. Tests open bundles with IronZIP.
Markdown

如何計畫並運行IronZIP遷移?

在發送下一次提示前,用Shift+Tab將聊天輸入旋轉到計劃模式。 在計畫模式中,Agent可以在研究代碼時提出澄清問題。

@src/ClientDrop/ @tests/ClientDrop.Tests/ @ironzip-bundles

Plan the move of BundleBuilder from System.IO.Compression to IronZIP.
Every bundle is encrypted with AES-256 using BundleOptions.Password.
Map each System.IO.Compression call to the IronZIP member that replaces it.
For each call, name the file it lives in.
Public method signatures on BundleBuilder stay as they are.
No test is renamed or loses an assertion.
Write no code yet.

In the plan, tell me how each of these works:
- The three files called statement.pdf in different folders all survive.
- The tests read an encrypted bundle.
- Reissue swaps a document without renaming it.
Text

計劃是您可以編輯的Markdown文件,因此錯誤的映射可以在構建之前得到修正。 當計畫正確時,從計畫模式構建,或者回到Agent模式,下一個提示添加檢查。

Build the approved plan with @ironzip-bundles attached.
Remove every System.IO.Compression call from src/ClientDrop.
In the tests, change only BundleReader.
Set CLIENTDROP_BUNDLE_PASSWORD to a throwaway value inside each command you run.

After the build, carry out these steps in sequence:
1. Build and run the tests.
2. Run "bundle C-1042", then run "inspect" on the result with that password.
3. Extract that bundle with IronZIP to an empty folder.

Report how many tests pass now and how many passed at the start.
Also report how many files the client folder and the extracted folder each hold.
Text

在我們的校準中,將每次呼叫對應為最近的IronZIP成員的直接翻譯乾淨地編譯並通過了六項測試中的四項。 兩次失敗的是提取檢查和重新發行。 遵循規則的端口通過了所有六個。

如何從保護包中取出一份文件?

BundleBuilder還需要一種方式從未下載的包中移除一份文件。 在BundleBuilder.cs中高亮顯示整個Reissue方法,按Ctrl+Shift+L將其添加到開啟的聊天中,並在Agent模式中發送請求。

Below the highlighted Reissue, add Withdraw(string bundlePath, string entryName).
It takes one document out of an existing bundle and keeps the rest encrypted.
For a name the bundle lacks, it throws KeyNotFoundException, as Reissue does.
Add a "withdraw <zip> <entry>" command to Program.cs.
Try it on a fresh C-1042 bundle, with CLIENTDROP_BUNDLE_PASSWORD set inside each command.
Show me what each command prints.
Text

結果Withdraw是Contains的防護,然後是Delete,Encrypt與EncryptionMethods.AES256和Save,在用密碼打開的存檔上。 從C-1042中撤回contract.pdf留下了六個條目,皆已加密。 在我們的校準中,兩份文件的包保留了一份,然後編輯器無法打開該包。

為什麼一文件包拒絕自己的密碼?

IronZipArchive構造函數在受保護的存檔僅包含一個條目時拒絕正確的密碼。 在IronZIP 2026.10.2中,它因單條目存檔的AES-256、AES-128和傳統加密而拋出了"無效密碼!"的Exception,並且字節陣列重載和FromArchive也一樣。 ExtractArchiveToDirectory用相同密碼解壓文件沒有錯誤,且>=兩個條目正常開啟。

客戶C-1077有一份文件,一封歡迎信。 提及其資料夾、更正信和程序一起。

@TestData/clients/C-1077/ @TestData/reissue/C-1077/ @src/ClientDrop/Program.cs

Client C-1077 has a single document.
Set the same throwaway CLIENTDROP_BUNDLE_PASSWORD inside each command.

Run these three steps in order:
1. Run bundle C-1077.
2. Run list on out/C-1077.zip.
3. Reissue its welcome-letter.pdf from TestData/reissue/C-1077/.

If any step throws, find the cause and fix it in BundleBuilder.
Don't catch and hide the exception.
If a line of @ironzip-bundles led to it, change that line too.
Then run all three steps again.
Show me the error you hit and the list output after the reissue.
Text

在我們的校準中,包被寫入,然後列表和重新發行失敗,包命令本身也失敗,列出新包以打印其條目數。 通過將包提取到臨時資料夾中讀取包,並從該資料夾中再次寫入以重新發行或撤回,列出了2,643字節的信件並替換為已更正的信件。 將此塊附加在翻譯下方。

One-document bundles follow this rule:
- On a protected one-entry bundle, the IronZipArchive constructor rejects the correct password.
- List, reissue and withdraw such a bundle by extracting it with ExtractArchiveToDirectory.
- Then pack the extracted folder again.
Markdown

如何為包撰寫回歸測試?

雲代理可以撰寫回歸套件。它從您連接的源控制中克隆存儲庫,因此首先推送端口,然後將IRONZIP_LICENSE_KEY作為密碼添加到雲代理儀表板中。

@tests/ClientDrop.Tests/ @TestData/

Extend BundleBuilderTests for the IronZIP port with tests for these cases:
- The three statement.pdf documents from different C-1042 folders all survive a round trip.
- Those three documents keep distinct entry names.
- Every entry in the C-1042 bundle is encrypted.
- A wrong password fails when the bundle is extracted.
- A one-document bundle can be listed, reissued and extracted.
- Withdraw removes exactly one document.
- Withdraw throws KeyNotFoundException for an unknown name.

Compare extracted files by SHA-256, never archive bytes.
Run dotnet test and report how many tests pass and fail.
Text

錯誤密碼測試的責任是在包中提取。 在三個條目的包上,構建器接受了一個錯誤密碼而沒有錯誤,條目數、條目列表和名稱查找都回答如同它正確一樣。 ExtractArchiveToDirectory是第一個拒絕它的調用,提起ArgumentException "無效密碼!!"。 因此,列出條目的端口在第一次讀取時拒絕錯誤密碼。

IronZIP的AI編碼助理指南全程運行一項IronZIP任務,符合定義的通過標準。

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

這七個提示按順序發送到Cursor,在為這份指南製作的ClientDrop存儲庫副本上進行。副本包含了System.IO.Compression的BundleBuilder,六個xUnit測試讀取使用System.IO.Compression的包,以及客戶C-1042。規則文件和客戶C-1077在使用它們的提示之前立即添加,並且只有環境變量設置了許可金鑰。 下面的每個數據圖來自於聊天後提交代碼的構建和運行。

  • 在端口之前,所有6項測試都通過,之後同樣6項也通過。
  • 端口C-1042包以唯一平面名稱持有7個條目。
  • IronZIP從該包解壓7個文件,與客戶資料夾持有的數量相同。
  • pyzipper是一個不與IronZIP共享代碼的Python ZIP讀取器,發現所有7個條目都使用了AES-256加密。
  • 所有7個解壓的文件與客戶資料夾中的文件匹配,通過了SHA-256驗證。
  • 當詢問IronZIP在哪里檢查密碼時,Cursor稱構造函數並引用了訪問示例。
  • Withdraw因一個缺少的名稱在包中引發KeyNotFoundException。
  • 在修復之前,對於C-1077的包、列表和重新發行步驟每一個都因IronZipArchive構造函數引發Exception "無效密碼!"。
  • 修復後列表顯示2,643字節的welcome-letter.pdf,並在重新發行後顯示2,761字節。
  • pyzipper解壓的重新發行信與修正文件按SHA-256匹配。
  • 每個C-1077包還有一個空條目,名為__bundle_keep,解壓寫為第二個文件。
  • 在最終代碼中,從兩文件包中取出一個文件留下了一個條目,然後列表拋出"無效密碼!"。
  • 測試提示添加了6項測試,所有12項皆通過。
  • IronZIP 2026.10.2是服務中唯一的包,沒有剩下的System.IO.Compression呼叫。
  • 每個提示完成後的Release構建都沒有警告或錯誤。
  • 一些步驟與頁面上運行的不同。 在計畫模式中,Cursor在打開規則文件前搜尋了存儲庫外的資料夾尋找ironzip-bundles。對於C-1077,Cursor將__bundle_keep條目添加到單文件包中,在規則中寫入此內容,而不是通過提取讀取。 雲代理提示是以本地同一會話形式在Agent模式中發送的,而不是作為雲代理。

任何代碼之前的計劃批准也發生在Claude代碼指南中,在這裡計畫從提取副本重建每個存檔,因此處理了單個條目存檔。GitHub Copilot指南將其TAR規則限制在日誌存檔器及其測試中使用的applyTo值限制於特定路徑指示文件,此規則同樣用globs限制。 運行記錄命名了Cursor版和模型,並給出了總提示時間和測試機器的硬體。


疑難排解


問題?

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

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

閱讀更多

準備好開始了嗎?

NuGet 下載次數 25,383版本:2026.11剛剛發布