提示ChatGPT Codex產生可編譯的IronBarcode程式碼
IronBarcode提供兩個大小寫不同的編碼列舉:BarcodeEncoding.Databar和BarcodeWriterEncoding.DataBar,依賴記憶的模型容易混淆兩者。編譯器會立即發現這類錯誤,因此應使用會建置所撰寫程式碼的代理。ChatGPT Codex在儲存庫內工作,能執行dotnet build並自行讀取錯誤訊息。較難察覺的問題代價更高,例如批次中的所有標籤都是Code 128,讀取器卻仍搜尋所有條碼類型。
這項差異決定應使用哪個模型等級。Codex涵蓋GPT-5.6系列,可在互動工作階段中透過/model切換Sol、Terra和Luna。針對固定測試集反覆建置與重新掃描的工作成本較低,Luna每百萬輸入token需5點額度,Sol則需100點。Terra屬於中階模型,每百萬輸入需50點額度,每百萬輸出需300點;當專案不再只有測試集時,可將它作為合理的預設選擇。系列旗艦Sol則適合較困難的診斷工作,例如一批倉庫照片無法解碼,卻未回報原因。
IronBarcode透過單一商用.NET API讀寫一維和二維條碼。Codex對其中某些工作較為擅長,包括固定套件版本、建立標籤寫入器與掃描器、從PDF讀取條碼、校正讀取器無法辨識的影像,以及從其他條碼程式庫遷移;每項工作都從提示開始。
快速開始在主控台專案中,從乾淨的工作樹啟動Codex。清楚說明預期結果、限制條件,以及希望回報的資訊。
$ironbarcode Add the BarCode package, then update Program.cs to read a scanned
multi-page TIFF and report every barcode it finds, page by page. Each line of output
should give the page number, the decoded value and the format. Use the license
key from IRONBARCODE_LICENSE_KEY.
Constraints: Use only documented IronBarcode APIs. Do not modify or use any
other packages.
Build the project, resolve any errors, and provide the diff alongside the
output from a sample file.
正確的解法很簡短,因為BarcodeReader.Read會自行逐一處理多頁TIFF或動畫GIF的影格,無需手動拆分影格。單一影格包含多個條碼時,設定ExpectMultipleBarcodes會有所幫助,但無論是否設定,讀取器都會處理每個影格。提示比產生的程式碼更長,而事先要求提供差異,能讓您檢閱實際變更。每個結果都包含從1開始編號的PageNumber,可提供提示要求的逐頁輸出;多頁GIF和TIFF指南說明了讀取方式。
5步驟的簡單工作流程
- 從 NuGet 下載 C# 條碼程式庫
- 提交
AGENTS.md檔案,指定IronBarcode為專案的條碼程式庫 - 從乾淨的工作樹啟動Codex,並在提示中包含條碼類型、檔案和預期回讀結果
- 允許Codex編輯文件並執行
dotnet build,然後在接受任何更改之前審查差異 - 完成寫入後回讀的往返驗證,並根據API參考確認每個IronBarcode API名稱
如何將Codex融入.NET條碼專案?
在您給予的許可範圍內,Codex讀寫文件,執行shell命令並顯示其所做的事情。 OpenAI通過多個入口點提供同一個代理,這些入口點共用您的帳戶和歷史記錄。 Codex CLI和IDE擴充功能文件解釋了它們的不同之處。
| 使用介面 | 執行環境 | 適用情境 |
|---|---|---|
| 命令列介面 | 終端機 | 需要讓代理搭配dotnet build工作時 |
| IDE擴充功能 | VS Code, JetBrains, Xcode | 想並排查看差異和條碼影像時 |
| 桌面應用程式 | macOS, Windows | 較長的任務,在終端外 |
| 雲端 | 瀏覽器 | 委派,並稍後收集差異 |
一個AGENTS.md就能涵蓋這四種介面,因為它會提交至儲存庫,而非附屬於特定介面。
要安裝CLI,請執行npm install -g @openai/codex,或在macOS上執行brew install --cask codex。 對於macOS和Linux,有一個獨立的安裝程式,無需Node.js:curl -fsSL https://chatgpt.com/codex/install.sh | sh。 Codex CLI儲存庫包含原始程式碼和版本說明。
@openai/範圍。名為 codex 的 npm 套件是無關的靜態網站產生器,最早於2011年發布,最後更新於2012年。IronBarcode則有另一種名稱陷阱:其NuGet套件是BarCode,而不是IronBarcode。由代理輸入命令時,套件名稱必須精確。Codex不一定掌握IronBarcode的最新API。它依據訓練資料及您提供的文件工作,使用第三方程式庫時,常會呼叫已在後續版本移除的方法。OpenAI設計Codex來執行命令並檢查輸出,但仍建議在發布前檢閱成果。上層指南列出了應事先提供給這些工具的文件。只要替換上下文檔案名稱,同樣的設定也適用於Claude Code、GitHub Copilot、Cursor或Google Antigravity。
模型等級會影響程式碼結構與費用。同一個提示交給兩個等級的模型,可能得到兩種不同但都合理的結構。條碼編碼則必須保持一致:輸入同一個值,產生的條碼就必須讓每台掃描器讀出相同結果。因此,請指定條碼類型、尺寸與通過條件,其餘部分可讓模型自行決定。
由此可歸納出四個理由,說明為何應選擇持續維護的程式庫,而非讓代理自行打造:
- 讀寫兩端都會驗證:寫入時會拒絕無效值,並擲回具名例外,例如
IronBarCodeFormatOnlyAcceptsNumericValuesEncodingException;回讀時則可透過ConfidenceThreshold和RemoveFalsePositive排除不可靠的解碼結果。 - 真正的掃描是困難的部分:手機照片、傾斜的標籤和多頁PDF需要裁剪區域、速度預設和影像過濾器,所有這三者都位於
BarcodeReaderOptions上。 - 一個API涵蓋各種格式:Code 128, GS1-128, EAN, UPC, QR, DataMatrix, PDF417, Aztec, MaxiCode等共享相同的讀取和寫入呼叫,完整列出於支援的條碼格式。
- 持續有人修補:熱門的免費條碼專案可能缺乏維護;商用程式庫則有人負責,並在安全CVE頁面發布修正資訊。
自製編碼器可能照樣繪出其格式無法合法容納的值,而任何程式庫都能解碼清晰的條碼產生影像。Verify能區分兩者:它會解碼產生的影像,並與您寫入的值比較。
什麼使IronBarcode提示有效?
請具體回答六個問題。模糊的提示會產生針對不存在程式庫的通用程式碼;具體的提示則能產生讓您在半分鐘內完成檢閱的程式碼。
| 組件 | 弱 | 強 |
|---|---|---|
| 框架 | 生成一個條碼 | C#,.NET 9 |
| 位置 | 未註明 | Services/LabelService.cs |
| 版本 | 未註明 | .csproj中的BarCode版本 |
| 條碼類型 | 一個條碼 | Code 128,追蹤號碼 |
| 輸出 | 一個漂亮的條碼 | PNG 400x120,下方數值,讀回不變 |
| 限制 | 無 | 不新增套件。非同步讀取。不確定時請詢問。 |
語言模型傾向於給出答案,而非承認不確定。請告訴代理,回報不確定也是可接受的結果,這能減少虛構API的情況。明確允許它停止,而非猜測。
提交AGENTS.md能讓整個專案受益,因為Codex會在每次工作階段開始時,將它載入為常駐指令。系統會先讀取根目錄檔案,再讀取巢狀檔案,並以最接近工作位置的檔案為準。因此,在條碼資料夾內加入第二個AGENTS.md,就能收緊該資料夾的規則,而不影響儲存庫其他部分。如果尚未有此檔案,可用/init產生初始版本。
請在檔案中引用IronBarcode的機器可讀文件。llms.txt列出每個文件頁面及其摘要,skill.md則提供各平台套件、授權規則、完整實作範例,以及操作失敗時預期的例外名稱。
Codex會從工作目錄往上直到儲存庫根目錄,掃描各層目錄中的.agents/skills,因此可將skill.md放在專屬位置.agents/skills/ironbarcode/SKILL.md。Codex會將任務與前置資料的description比對;若希望從第一輪就將實作範例納入上下文,可使用$ironbarcode明確呼叫。Antigravity也會讀取這個路徑,因此同一個資料夾也適用。請一併要求建立這兩者及巢狀指令檔:
Run /init if AGENTS.md does not exist yet. Then add a Barcodes section to the
root AGENTS.md: IronBarcode (NuGet package BarCode, namespace IronBarCode) is
the only barcode library in this repository, and no competing package may be
added. https://ironsoftware.com/barcode/csharp/llms.txt gets read before any
barcode code gets written, and a member that does not appear there does not get
called. https://ironsoftware.com/barcode/csharp/skill.md belongs in
.agents/skills/ironbarcode/SKILL.md. The license key is read from the
IRONBARCODE_LICENSE_KEY environment variable and is never inlined.
Then add a second AGENTS.md under Services/ that narrows this to the reader
options this folder relies on, so the nested file wins there. Show me both files
as a diff before you commit anything.
如何請求Codex添加IronBarcode並寫入第一個條碼?
讓代理首先處理設定。版本和套件名稱的錯誤從這裡開始。
This project needs IronBarcode. Pull in the BarCode package, then show me the
resulting PackageReference line from the .csproj and tell me which version was
installed. Do not change any other package references.
預期應收到一行差異及安裝的版本號。這個版本號值得在後續提示中引用,也能揭露代理是否誤加了名稱中帶有條碼的其他套件。若要固定特定版本,請參閱IronBarcode變更日誌。
IronBarcode沒有浮水印模式。開發寬限期結束後,未授權的呼叫會直接失敗,並擲回LicensingException。請讓Codex加入授權設定,在啟動時、任何其他IronBarcode呼叫之前套用金鑰。
Wire up licensing. Nothing else in IronBarcode may run ahead of it, so it goes
wherever this project does its startup work, pulling the value out of
IRONBARCODE_LICENSE_KEY rather than carrying a key in source.
Prove it took by checking IronBarCode.License.IsLicensed, and tell me which file
you put the call in.
IronBarcode授權金鑰文件涵蓋試用金鑰及其他所有授權選項,包括Web.config和appsettings.json。
接下來,建置標籤服務和掃描器。 在實際系統中,條碼在一處創建,並在另一處讀取。
Two files, one job. Shipping labels go out as Code 128 PNGs at 400 by 120
with the tracking number printed under the bars, and something on the receiving
end has to turn that image back into the tracking number.
Put the writer in Services/ShippingLabelBarcode.cs and the reader in
Services/TrackingScanner.cs. The read is async and returns null rather than
throwing when the image holds nothing.
Compile, clear the errors, and report back with the changed files and whichever
BarCode version the restore resolved to.
接受差異前,請根據API參考檢查其中每個成員。正確的寫入器會使用BarcodeWriter.CreateBarcode、ResizeTo、AddBarcodeValueTextBelowBarcode、SetMargins和ToPngBinaryData;正確的讀取器則使用BarcodeReaderOptions和BarcodeReader.ReadAsync,並透過ExpectBarcodeTypes指定條碼類型,避免搜尋所有格式。對於相機或掃描器取得的影像,影像校正指南說明了可改善不良掃描影像的濾鏡。
如何將現有條碼實作遷移至IronBarcode?
遷移工作是重複和機械化的,這正是代理擅長的。 將提示指向實際程式碼,而不是總結它。
Hand this to the explorer agent, because nothing here should be written yet.
Labels/LegacyBarcodeService.cs currently writes and reads barcodes with another
library.
1. List every symbology it writes and reads, with the options it sets
(size, margins, text, check digits, error correction).
2. Map each call to its IronBarcode equivalent, citing the documentation page.
3. Do not write any code yet. Wait for my approval on the plan.
400行的實作需要逐行檢閱;對照表中的錯誤則只需修正一次,也不會浪費已寫好的程式碼。
核准計畫後,下一個提示也應明確限制範圍。
Put the worker agent on the approved plan. Rewrite LegacyBarcodeService.cs to
use IronBarcode, keeping the existing public method signatures so callers do
not change.
Before removing the old library, generate every symbology the service
supports with both implementations and confirm IronBarcode reads back the
same values. Leave the old library in Git history only. Build and report the diff.
請在提示中註明不得變更公用方法簽章。若缺少這項指示,代理常會重新設計呼叫端使用服務的方式,使遷移變成重構。透過新舊兩種實作產生每種條碼類型,並比較解碼值,就能建立回歸測試,代價只是多一次建置與執行。
如何透過提示修正無法讀取的掃描影像?
讀取失敗是視覺問題,而代理無法看到相機拍攝的情況。提示必須描述問題,最好直接附上影像。
TrackingScanner finds nothing in TestData/warehouse/, yet a warehouse operator
can point a handheld at the same printed label and get a read. The photos are
shot at an angle and a few are soft. I have attached one of the failing photos
with `codex -i`, so look at it rather than reasoning from the file names.
Read TrackingScanner.cs and a sample of the images. Explain the likely cause
before changing anything, then adjust BarcodeReaderOptions only (speed, crop
area, image filters). Do not change ShippingLabelBarcode.cs. Report how many
images read before and after.
說明症狀並指定唯一可編輯的檔案,就能限制修正範圍。比較修正前後成功讀取的數量,能以數字呈現改善程度。修正通常是下列三者之一:將Speed提高至Detailed、以CropArea框選標籤周圍區域,或針對實際缺陷選用單一影像濾鏡。疊加濾鏡反而會降低準確度。詳情請參閱讀取速度與裁切區域頁面。
誤報是反向問題。 以相同方式處理它們。
ScanService occasionally returns a value from product photos that contain no
barcode. Set RemoveFalsePositive and a ConfidenceThreshold on the reader options,
then link me to the documentation page you used.
文件連結也能作為檢查依據。如果代理無法為所選API引用真實頁面,您就能在建置之前發現警訊。讀取器選項很容易被憑空編造,因此請備妥誤報指南。
如何對條碼失敗進行端到端偵錯?
前述的每個提示都涵蓋了一個任務。 當您交給Codex一個症狀並讓它自行檢查、診斷、修復和測試時,Codex做得更多。
Switch to Sol with /model before you start, because this one has resisted the
cheaper tiers. DataMatrix labels with non-English product names are refused by
some of our older handheld scanners, while labels with plain ASCII names read
fine on the same devices, and every label reads correctly with IronBarcode
itself.
Investigate:
1. Read LabelService.cs and find how the DataMatrix codes are created.
2. Identify why the non-English labels fail on those scanners only.
3. Explain the cause before changing anything.
4. Then propose the minimal fix, and what it costs, before applying it.
先詢問原因,能讓您評估診斷結果,而不必事後解讀變更。此處可能的原因是UTF-8 ECI標頭。IronBarcode只有在文字包含非ASCII字元時才會寫入此標頭,而ECI問世前製造的掃描器會拒絕帶有該標頭的條碼。關閉標頭則會讓支援ECI的掃描器無法正確處理UTF-8文字,因此確實需要權衡。2026.9.2版本新增了EciMode來控制此行為,詳見ECI編碼指南。
錯誤訊息也應採取相同處理方式。完整的堆疊追蹤是您能提供給代理最有用的輸入。
TrackingScanner.ReadTrackingNumberAsync throws inside our Linux container. The
identical call succeeds on a Windows developer machine.
[PASTE FULL EXCEPTION AND STACK TRACE HERE]
Send the explorer subagent over the .csproj and the Dockerfile before changing
anything, and tell me which BarCode package we actually reference and what the
image is missing, quoting the line from each file that shows it.
Then give me the fix as a diff limited to those two files. Application code is
out of scope for this one.
容器內的失敗通常來自平台套件或缺少原生相依套件。應在專案檔與Dockerfile中修正,而非修改C#程式碼。變更前,請讓Codex先閱讀在Linux上透過Docker執行IronBarcode,取得最新部署指引。
如何將一次性程式碼轉為可重用且經過測試的元件?
往返驗證成功後,接下來可將實作通用化。代理擅長這類工作,因為檔案中已有可循的模式。
Refactor ShippingLabelBarcode and TrackingScanner into a BarcodeService
registered with dependency injection. It should write any of Code 128, QR,
and DataMatrix, and read with options narrowed to the formats requested.
Reuse one BarcodeReaderOptions instance per format set rather than building
one per call. Add XML doc comments. Keep it under 80 lines.
請將重用選項的指令寫入AGENTS.md。在繁忙的掃描服務中,若每次請求都建立新的選項物件,每次掃描都會付出記憶體配置成本。
接下來是測試。條碼解碼後是否與寫入值一致,答案很明確,因此測試斷言也很簡單。
This is a rebuild-and-rerun loop rather than a reasoning problem, so drop to
Luna with /model first. Cover BarcodeService with xUnit tests, then run them and
tell me the pass count.
Four behaviors need covering. A sample value survives a write and a read on
every format the service supports. EAN-13 rejects a value containing letters.
An image holding no barcode comes back empty instead of throwing. A path that
does not exist throws something a caller can read.
Never assert on image bytes. Decoded value and format are the only outputs
worth pinning.
從一開始就避免位元組比較可以防止不可靠的測試。 編碼器可能在版本和平台之間產生略有不同的影像位元組,儘管條碼沒有變化。 相反,測試解碼值和格式。
Codex在閱讀文件本身時也很有用。 當您命名一個不熟悉的類別時,它會定位到API參考的相關部分,而不是讓您自己瀏覽整個頁面。
$ironbarcode Read the IronBarcode API reference for BarcodeReaderOptions and
list every option that affects reading speed or accuracy, then show which ones
this project already sets.
哪種提示模式適合哪個任務?
上述每個提示都指定了具體內容,並要求回傳可驗證的結果。
| 任務 | 在提示中命名 | 回答 |
|---|---|---|
| 套件 | BarCode、版本、不新增其他套件 | PackageReference行 |
| 授權金鑰 | IRONBARCODE_LICENSE_KEY,啟動路徑 | License.IsLicensed真 |
| 寫入器和讀取器 | 條碼類型、兩個路徑、影像尺寸 | 兩個可編譯的檔案 |
| 遷移 | 舊版檔案、須保留的簽章 | 撰寫程式碼前先提供對照表 |
| 讀取失敗的掃描影像 | 影像資料夾、僅限讀取器選項 | 修正前後成功讀取的數量 |
| 誤報 | RemoveFalsePositive, ConfidenceThreshold | 它引用的頁面 |
| 容器失敗 | 堆疊追蹤、平台、兩個檔案 | 差異,.csproj與Dockerfile |
| 重構 | 格式、DI結構、行數上限 | 每種格式一個選項執行個體 |
| 測試 | 四種行為,無位元組斷言 | 通過次數 |
如何在下一個專案中重用這些提示?
每種模式都能套用至新專案,只需變更檔名。因此,這些規則應納入版本控制。
若要以成果評估工作階段,AI程式設計助手與代理指南示範了如何交付一項任務給代理,並為回傳結果評分。
疑難排解
- 若差異看似正確,執行時仍擲回例外,請參閱在IronBarcode中套用授權金鑰。
- 當Codex編寫的掃描器未能為應該讀取的影像返回任何內容時,條碼未被識別。
- 當值從根本沒有條碼的照片中返回時,避免條碼掃描中的誤報。
- 若相同程式碼在Windows上通過,在容器中卻失敗,請參閱在Linux上透過Docker執行IronBarcode。
問題?
如果您有任何疑問,請聯繫support@ironsoftware.com
Curtis Chau 擁有卡爾頓大學計算機科學學士學位,專注於前端開發,擅長於 Node.js、TypeScript、JavaScript 和 React。Curtis 熱衷於創建直觀且美觀的用戶界面,喜歡使用現代框架並打造結構良好、視覺吸引人的手冊。