如何在Cursor中使用IronZIP
.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捆绑包在构建时被加密,用那个密码提取以证明它仍包含每个文件,并在测试计算其条目时再次使用其密码打开。
快速入门当ClientDrop在Cursor中打开时,将此粘贴到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.
inspect命令读取旧的捆绑包,并列出七个带有其文件夹路径的条目,从根目录的contract.pdf到statements/2026-05/statement.pdf,没有一个被加密。
在每个提示中省略许可证密钥。 在Agent模式下,Cursor写入代码并执行终端命令,因此在对话中输入的键可以被复制到代码或提交消息中。 相反,设置IRONZIP_LICENSE_KEY环境变量。 IronZIP不会自行读取该变量,因此提示中有代码将其分配给License.LicenseKey。 在设置了变量并没有进行分配的探测中,保存调用抛出了LicensingException,内容为"需要生产许可证"。 许可证密钥指南涵盖了IronZIP自己查找的位置,例如一个Git可以忽略的appsettings.json文件。
最小工作流程(5 个步骤)
- 从NuGet下载C# ZIP库
- 在.cursor/rules下提交一个规则,该规则放弃System.IO.Compression并链接到IronZIP文档。
- 添加测量的文件名,重新发布并测试读者翻译到规则中。
- 在计划模式下商定端口,然后根据现有测试构建它
- 提取每个捆绑包并比较哈希,并检查成员名称在API参考中。
您应该为IronZIP工作使用哪种Cursor模型?
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.
页面将加密问题分成两半回答。 密码示例调用Encrypt搭配EncryptionMethods.Traditional,访问示例将同一调用切换为AES-256。没有页面说明Add对文件夹路径的作用。 两个页面误导。 访问示例称错误的密码使操作失败,这仅出现在提取中,并且添加文件示例使用FromFile打开现有ZIP,构建一个新归档,持有该ZIP作为一个单条目。 IronZipArchive参考记录了无示例页面展示的成员,例如SetPassword和RemoveEncryption。
ironzip。 以 .cursor/skills/ironzip/SKILL.md 保存,当 Cursor 启动时被发现,并在 Agent 中输入 /ironzip 时附加到一条消息。您如何编写编码IronZIP惯例的项目规则?
项目规则是.cursor/rules下的.mdc文件,与代码一起提交,均为带有前言块的Markdown文件。 规则系统跳过.cursor/rules下的纯.md文件,因为这样的文件没有前言。 description、globs和alwaysApply字段决定Cursor何时应用规则。
这个规则是用通配符范围定义的,所以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.
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在任何重命名之前失败。 对于两个invoice.pdf条目抛出了ArgumentException "已添加具有相同键的项目"。 加密本身有效。 Encrypt 搭配EncryptionMethods.AES256 将所有七个条目标记为加密,并在唯一平坦名称下对文件夹进行阶段性复制,如statements_2026-03_statement.pdf,提取成为七个文件,与原版通过SHA-256匹配。重复的名字是最难捕捉的问题,因为一个丢失了声明的捆绑仍有七个条目,所以一个计数检查通过,而客户端下载了四个文件。
将翻译附加到规则中。
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.
您如何计划和执行迁移到IronZIP?
在发送下一个提示之前用Shift+Tab将聊天输入旋转到计划模式。 在计划模式下,代理可以在研究代码时提出澄清问题。
@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.
计划是一个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.
在我们的校准中,直接将每个调用交换为其最近的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.
结果Withdraw是一个Contains保护,然后是Delete,Encrypt与EncryptionMethods.AES256和Save,在用其密码打开的归档上进行。 将contract.pdf从C-1042中取出后,留下六个条目,皆仍然加密。 在我们的校准中包含两个文件的捆绑保留一个,然后构造函数无法打开捆绑。
为何单文件捆绑拒绝自己的密码?
IronZipArchive构造函数在受保护归档正好包含一个条目时拒绝正确的密码。 在IronZIP 2026.10.2中,它在读取由AES-256、AES-128和传统加密加密的单条目归档时抛出了"密码无效!"的异常,字节数组重载和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.
在我们的校准中写入了捆绑,然后列表和再发布失败,捆绑命令本身也失败了,列出新捆绑以打印其条目数。 通过将其提取到临时文件夹中读取捆绑,然后从该文件夹中写回以进行再发布或撤回,列出了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.
您如何为捆绑包编写回归测试?
云代理可以编写回归套件。它从您连接的源控制克隆存储库,所以首先推送端口,并在开始一个之前将IRONZIP_LICENSE_KEY 添加为 Cloud Agents 仪表板中的秘密。
@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.
错误密码测试必须提取捆绑包。 在三条目的捆绑中,构造函数在没有错误的情况下接受了错误的密码,条目数、条目列表和名字查找的回答都像是正确的。 ExtractArchiveToDirectory 是第一个拒绝它的调用,抛出ArgumentException"无效密码!!"。 以提取方式列出条目的端口因此在第一次读取时拒绝错误密码。
IronZIP的AI编码助手指南针对定义的通过标准运行一个IronZIP任务从头到尾。
在实际运行中这些提示生成了什么?
七个提示按顺序发送到Cursor中,在一个聊天中,针对为本指南制作的ClientDrop存储库副本。副本包含了System.IO.Compression BundleBuilder、六个用System.IO.Compression阅读捆绑的xUnit测试,以及客服C-1042。规则文件和客户C-1077在使用它们的提示之前立即添加,许可证密钥仅作为环境变量设置。 以下每个图表皆来自聊天结束后提交代码的构建和运行。
- 所有 6 个测试在移植前通过,移植后同样 6 个测试也通过。
- 端口化的C-1042捆绑在唯一平坦的名称下包含7个条目。
- IronZIP从该捆绑包中提取了7个文件,与客户文件夹持有的文件数量相同。
- pyzipper,Python ZIP阅读器,与IronZIP不共享代码,发现了所有7个条目上的AES-256加密。
- 所有7个提取的文件通过SHA-256与客户端文件夹中的文件匹配。
- 问IronZIP何时检查密码,Cursor说程序员和访问示例。
- 对于捆绑中缺少名称的Withdraw引发了KeyNotFoundException。
- 修复之前,C-1077的捆绑、列表和再发布步骤均从IronZipArchive构造函数抛出异常"密码无效!"。
- 修复后,列表显示welcome-letter.pdf为2,643字节,再发布为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条目添加到单文件捆绑中,并将其写入规则中,而不是通过提取读取。 Cloud Agent提示在同一个聊天中以Agent模式本地发送,而不是作为Cloud Agent。
在任何代码之前的计划批准也会在Claude Code指南中发生,在该计划中从提取的副本重建每个归档并因此处理单一条目归档。GitHub Copilot指南限制其TAR规则到日志归档器及其测试通过路径特定指令文件的applyTo值,而通配符以同样的方式限制此规则。 运行记录列出了Cursor版本和模型,并给出了总提示时间和测试机器的硬件。
故障排除
- IronZIP许可证密钥当移植代码抛出LicensingException时
- 密码保护ZIP当捆绑需要AES-256时
- 访问受保护的ZIP当再发布必须用密码重新打开捆绑时
- 提取受保护的ZIP当单文件捆绑无法打开时
- IronZIP文件和归档大小限制针对超过4 GB或65,535个条目的捆绑
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。