讓Cursor以IronBarcode文件為依據
IronBarcode中的BarcodeReaderOptions.CropArea接受的是IronSoftware.Drawing.Rectangle,而不是同名的System.Drawing型別;僅憑記憶作答的模型往往會選擇較熟悉的後者。同樣的習慣也會讓模型寫出dotnet add package IronBarcode,但正確的套件名稱是BarCode,namespace則是IronBarCode。
Cursor過去透過@Docs提及來索引文件網站,藉此解決這個問題。這項提及已不再出現在Cursor的文件中。現在可將連結貼入提示,讓代理的web工具擷取內容,或透過規則或技能提供指引。三種方式都讓代理參考實際頁面,無須等待建立索引。
Cursor是以AI為核心的編輯器,其代理可在兩種截然不同的範圍內工作:
- 內嵌編輯和Tab在游標所在的位置運作:使用
Ctrl+K(Mac上為Cmd+K)以一句話描述變更,Tab則預測下一次編輯。 - 代理模式會規劃跨檔案變更、執行建置、讀取錯誤並反覆修正;計畫模式則會先與您確認做法。
如果後續變更位於另一個檔案,Tab會開啟可跳至該檔案的入口;內嵌編輯則會在原處顯示差異,讓您接受或拒絕。
規則只適用於代理模式和聊天。Cursor文件明確指出,規則不影響Cursor Tab或其他AI功能。因此,Tab建議方法時,並不會參考您已提交的規則。
要讓Cursor在條碼工作中以IronBarcode文件為依據,需要提交兩個檔案,並在提示中貼入連結。進行精確變更時,這些準備尤其重要,例如限縮讀取器選項、新增裁切區域、選擇讀取速度,或找出能讓整批不良掃描成功解碼的單一影像校正設定。
本文不涉及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不受此選擇影響,而是依據最近的編輯、周圍的程式碼及linter錯誤提供建議。
大部分條碼工作成本低且重複性高:新增格式、重新建置、解碼測試資料集,再調整設定。偶爾會有一批實際掃描無法解碼,卻沒有錯誤訊息說明原因,此時就適合切換至編輯前會花更多時間推理的模型。模型也會影響程式碼,因此請明確指定條碼編碼類型、輸出尺寸及讀回驗證條件,避免由預設值決定。
本系列的內容在此互有關聯。如果您在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/載入Agent Skills。每個技能各有一個資料夾,內含SKILL.md,其frontmatter包含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引用文件頁面,請先驗證,再以該API繼續開發。
BarcodeReaderOptions的用法,無須捲動查找;答案也會引用資訊來源的API參考頁面。如何撰寫記錄IronBarcode慣例的專案規則?
專案規則位於儲存庫根目錄的.cursor/rules資料夾中。 它們在版本控制之下,與程式碼一同提交,因此每位開發人員都獲得相同的行為,而無需設定。
每個規則都是.mdc檔案,也就是透過YAML frontmatter設定description、globs和alwaysApply的Markdown檔案。Cursor會遞迴搜尋該資料夾,因此也支援子資料夾。放在其中的普通.md檔案會被忽略,因為它沒有用來啟用規則的frontmatter。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使用的檔案相同。它沒有frontmatter,因此也沒有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上的Docker中執行IronBarcode。
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。