让Cursor以IronBarcode文档为依据
BarcodeReaderOptions.CropArea 在IronBarcode中接受IronSoftware.Drawing.Rectangle,而不是同名的System.Drawing类型,但依赖记忆的模型往往会选择熟悉的后者。同样的习惯也会让模型写出dotnet add package IronBarcode,但实际包名是BarCode,命名空间是IronBarCode。
Cursor过去通过@Docs引用已建立索引的文档网站来解决这类问题。如今,Cursor文档已不再提及这一引用方式。取而代之的是在提示中粘贴链接,让代理通过web工具获取页面,或通过规则、技能提供指导。这三种方式都让代理查阅真实页面,无需等待建立索引。
Cursor是一个AI优先的编辑器,其代理在两个非常不同的范围内工作:
- 内联编辑和Tab在您的光标处工作,
Ctrl+K(在Mac上为Cmd+K) 用一句话陈述更改,Tab预测下一个编辑。 - 代理模式跨文件计划,运行构建,读取错误,并迭代,而计划模式则先与您确定方法。
如果后续更改涉及另一个文件,Tab会打开跳转入口;内联编辑则在原位显示差异,供您接受或拒绝。
规则仅对代理模式和聊天生效。Cursor文档明确指出,规则不会影响Cursor Tab或其他AI功能。因此,即使规则已提交,Tab在建议方法时也不会使用它。
让Cursor在条形码开发中以文档为依据,需要提交两个文件,并在提示中粘贴一个链接。这对精确更改尤为重要,例如缩小读取器选项的范围、添加裁剪区域、选择读取速度,或确定哪项图像校正能让一批质量不佳的扫描件成功解码。
本文不涉及IronBarcode读取器内部的置信度评分,该功能另有完整示例。
快速入门在Cursor中打开一个C#项目,让代理先阅读文档页面,再编写代码。
In Program.cs, generate a Code 128 barcode for an asset tag and style it for a
printed label. Set the bar color and the background with ChangeBarCodeColor and
ChangeBackgroundColor, size it with ResizeTo, and print the value under the
bars. The license comes out of IRONBARCODE_LICENSE_KEY.
Work from https://ironsoftware.com/barcode/csharp/llms-full.txt, use only
members that appear in it, and tell me which page each styling call came from.
颜色和尺寸相关成员的名称很容易记不准确,因此提示要求代理先阅读页面。条形码样式指南列出了这三个成员的准确名称。
5个步骤的简化工作流
- 从NuGet下载C#条形码库
- 将IronBarcode的
llms-full.txt链接粘贴到编写条形码代码的任何提示中 - 将IronBarcode的
skill.md保存为.cursor/skills/ironbarcode/SKILL.md - 提交一个项目规则,固定BarCode版本和您的约定
- 构建,回读每个条形码,并根据API参考检查每个API名称
哪个模型应该运行您的条形码会话?
Cursor是本系列中唯一允许您选择模型的工具。其自有代理模型Composer针对编辑器内的工具使用、文件编辑和终端操作进行了优化,默认使用其快速版本。模型选择器还列出了OpenAI、Anthropic、Google和SpaceXAI的前沿模型。Tab不受这一选择影响,它依据最近的编辑、周围代码和静态检查错误提供建议。
条形码开发会话中的大多数操作成本低且重复性强:添加格式、重新构建、解码测试集,再进行微调。偶尔会遇到一批真实扫描件无法解码,且没有错误说明原因,这时可以切换到编辑前推理时间更长的模型。模型也会影响代码,因此应明确指定条形码制式、输出尺寸和回读条件,不要交给默认设置。
本系列的指南也有相通之处。在Cursor中运行Claude模型时,Claude Code指南中的说明同样适用于其输出,因为模型相同,只是界面不同。
如何让Cursor以IronBarcode文档为依据?
以下三项操作可替代旧的索引方式,并可配合使用:
- 粘贴链接:指向
llms-full.txt而不是文档中心,因此一个URL将指南、示例和成员名称置于代理面前。 - 提交技能:将IronBarcode已发布的
skill.md保存为.cursor/skills/ironbarcode/SKILL.md,设置name: ironbarcode以匹配文件夹,并提交。 - 提交规则:下一节将介绍其中的内容。
Cursor从项目根目录或子目录中的.cursor/skills/和.agents/skills/加载代理技能。每项技能都有一个文件夹,其中包含SKILL.md,其前置元数据包含name和description。当任务与技能相关时,代理会加载相应技能;输入/ironbarcode也可直接调用。.agents/skills/是可供多个工具共用的路径,因此Codex和Antigravity也能从那里加载同一文件。
如果这三项都不做,模型就会根据未经当前版本核验的训练数据回答。方法名最容易出错:BarcodeScanner.DecodeImageFile()看起来像真实调用,却会导致构建失败。
有了可供查阅的页面,原本需要猜测的问题就能通过查询解决。
Which options narrow a read to two symbologies inside a fixed region of a
larger image? Give me the exact class and property names, and quote the lines
you took them from in https://ironsoftware.com/barcode/csharp/llms-full.txt.
如果代理无法为建议的API引用文档页面,请先核实,再据此继续开发。
BarcodeReaderOptions的用法,无需滚动查找,回答也会引用其依据的API参考页面。如何编写体现IronBarcode开发约定的项目规则?
项目规则位于存储库根目录的.cursor/rules文件夹中。 它们在版本控制中,与代码一起提交,因此每个开发人员在零配置下获得相同的行为。
每条规则都是一个.mdc文件,即带有YAML前置元数据的Markdown文件,其中设置description、globs和alwaysApply。Cursor会递归搜索该文件夹,因此也支持子文件夹。其中的普通.md文件会被忽略,因为它没有用于激活规则的前置元数据。IronBarcode规则示例如下。
---
description: IronBarcode conventions for barcode reading and writing in this project
globs: ["**/Services/**/*.cs", "**/Barcodes/**/*.cs"]
alwaysApply: false
---
# IronBarcode conventions
Applies to the barcode code in this folder only.
- IronBarcode (package BarCode, namespace IronBarCode) writes and reads every
barcode here. Never reach for a second barcode package.
- Reader options are explicit: set ExpectBarcodeTypes to the formats this
feature really reads, and reuse one BarcodeReaderOptions per format set
rather than allocating per call.
- Reads on a request path are async.
- CropArea takes IronSoftware.Drawing.Rectangle, not System.Drawing.
- Verified recipes: https://ironsoftware.com/barcode/csharp/skill.md
- If you are unsure a member exists, say so and cite the page. Do not guess a
method name that sounds plausible.
明确允许模型承认不确定,可以防止它编造API。将这一要求写入规则一次,即可用于之后的每个会话。
复制globs行时,应根据项目有意设置匹配范围。设置为alwaysApply: true的规则会加载到每个请求中,即使工作与条形码无关,也会占用上下文。将规则限定到存放条形码代码的文件夹,才能让它只在相关任务中生效。
AGENTS.md,ChatGPT Codex和Google Antigravity使用的也是这一文件。它没有前置元数据,因此不支持glob匹配。Cursor会读取项目根目录及子目录中的该文件,所以只能通过目录嵌套限定作用范围。需要glob模式时使用.cursor/rules,希望多个工具共用一份指令文件时使用AGENTS.md。哪种模式适合这次更改?
Cursor提供的编辑方法比本系列中的任何其他工具都多。 按大小选择,从单一行到整个存储库:
| 模式 | 此时使用它 | 条形码示例 |
|---|---|---|
| Tab | 下一个编辑是可预测的 | 重复设置读取器选项 |
| 内联编辑 | 一个文件,一句话 | 将读取范围限定为两种格式 |
| 代理 | 工作跨越文件并需要一个构建循环 | 一个标签端点和一个扫描端点 |
| 计划模式 | 重写太大以至于事后无法审查 | 从另一个条形码库迁移 |
| 云代理 | 可以无监督运行 | 每种格式的往返测试 |
@ 提及会改变什么?
@提及会向代理提供要读取的内容,例如文件、文件夹、终端、先前的聊天、Git差异或浏览器。直接引用读取条形码的文件比描述它更有效,因为描述容易遗漏错误所在的细节。
@Services/ScanService.cs @TestData/depot/
Read https://ironsoftware.com/barcode/csharp/llms-full.txt for the options.
Half the photos in TestData/depot/ come back empty. The reader options are
where this gets fixed, not the label generator. Name the setting that was
missing, and give me a decode rate for the folder before your change and after
it.
文件夹提及适合模块范围的工作,当您无法确定哪个文件重要时,整个代码库都在那里。 将代码与文档配对涵盖问题的两个方面:文件显示您的代码现在在做什么,而页面展示库实际上提供什么。
哪些设置能让一批照片成功解码,取决于图像受损的方式。任何描述都无法替代代理对实际图像进行测试。读取速度和图像校正页面介绍了各项设置。
如何规划并执行向IronBarcode的迁移?
迁移时,未经审查就跨多个文件重写代码会带来高昂成本,因为撤销更改比编写更困难。计划模式正是为此设计的。在聊天输入框中按Shift+Tab,或从模式下拉菜单中选择计划模式,代理便会提问以澄清需求、阅读代码库并生成计划。在生成代码之前,您可以在聊天中或以Markdown形式修改计划。计划保存在主目录中,选择“保存到工作区”可将其移至存储库,供团队审阅。
The barcode code in @Labels/ belongs to another library. Using
https://ironsoftware.com/barcode/csharp/llms-full.txt, work out what replacing
it with IronBarcode would actually involve. Which files change, what the
equivalent call is for each thing the folder does today, and where the
documentation says no clean equivalent exists.
Public method signatures are fixed. If the plan needs one to change, say so in
the plan rather than changing it.
阅读计划,用一两句话说明需要调整的内容,再交给代理执行。随后,代理模式会读取代码、跨文件编辑、运行命令、检查输出并迭代,因此下一条提示可以很简短。
Carry out the plan we agreed. Compile it, clear whatever errors come up, and
satisfy yourself that every symbology the folder handles still comes back out
the same as it went in. Show me the diff at the end. BarCode is the only package
that may appear in the .csproj.
去掉这两个限制,代理在迁移时重新设计调用模式。
无需监督的工作可以交给云代理(原称后台代理),您则可以继续使用编辑器。往返测试套件适合这类任务,因为它对解码值而非实现细节进行断言,编写测试无需等待迁移完成。
@Services/
Send this to a cloud agent while I keep working on the reader options.
Cover the migrated service with xUnit. Use a [Theory] over the symbologies it
supports rather than one [Fact] per format, so adding a format later costs one
line. Each case writes a sample value and reads it back, and the assertion is on
the decoded string and the decoded format together.
Then three edge cases as their own facts: an empty image returns no results
instead of throwing, a letters-only value is refused as EAN-13, and a missing
path fails with a readable message. Image bytes are off limits as an assertion
target.
排除字节比较是保持套件在各平台上的稳定性的原因。
读取问题在哪里?
条形码无法读取是IronBarcode用户最常遇到的问题,解决办法几乎总是在读取器选项中,而非标签本身。Cursor的优势在于,您无需描述故障,只需引用服务和存放失败图像的文件夹,编辑器就能结合两者处理。
Photos of returns labels read fine on a handheld scanner but come back empty
from @Services/ScanService.cs, and a few product photos carrying no barcode at
all return a value. Samples of both are in @TestData/returns/.
Explain the cause of each before changing anything, then fix both in the reader
options.
坚持要求先解释原因,您就能核查其推理,而不必反推更改的意图。这里的两种症状需要不同方向的修复。漏读需要缩小格式列表、设置裁剪区域并使用合适的图像过滤器,条形码未识别指南对此有详细说明。误识别出的值则需要RemoveFalsePositive和置信度阈值,具体见误报指南。
部署失败通常源于.csproj或容器镜像,而不是C#文件。拥有终端访问权限的代理可以检查这两处并自行运行构建。
@Dockerfile @LabelScan.csproj @Terminals
Reading works on Windows but fails in our Linux container. The failing build is
in the terminal output above, so read it there rather than asking me to paste it.
Check which BarCode package the project references and whether the image has
the native dependencies IronBarcode needs on Linux. Explain the cause, then
propose the change. Don't modify C# code unless the cause is there.
明确要求不要修改C#代码。如果只提供失败的调用而不限定范围,代理可能会添加try/catch,然后报告问题已解决。Linux上的Docker指南列出了镜像实际需要的内容。
您应该先设置什么?
配置技能文件和一条限定作用范围的规则大约需要十五分钟,之后每个会话都能使用。每次编写提示时仍应粘贴文档链接,这只需增加一行。
即使更换编辑器使用的模型,仍须完成三项检查:代码能够编译、条形码能够解码、使用的每个成员都能在IronBarcode的API文档中找到。这正是AI编码助手和代理指南采用的三项评估标准。Claude Code、ChatGPT Codex、GitHub Copilot和Google Antigravity也各有专门页面。
故障排除
- 内联编辑后的代码能够编译却无法运行时,请参阅在IronBarcode中应用许可证密钥。
- 仍需调整读取器选项时,请参阅条形码未识别。
- 项目规则中的版本与
.csproj中的版本不一致时,请参阅IronBarcode NuGet包。 - 当本地读取成功而容器读取失败时,在Linux上运行IronBarcode Docker。
有问题吗?
如果您有任何问题,请联系support@ironsoftware.com
Curtis Chau 拥有卡尔顿大学的计算机科学学士学位,专注于前端开发,精通 Node.js、TypeScript、JavaScript 和 React。他热衷于打造直观且美观的用户界面,喜欢使用现代框架并创建结构良好、视觉吸引力强的手册。