Cómo usar IronQR con ChatGPT Codex
Las acumulaciones de códigos QR a menudo llegan como carpetas desorganizadas que contienen etiquetas de activos escaneadas, fotos tomadas con el teléfono in situ, copias de fax, archivos de cero bytes debido a errores del escáner y hojas de portada sin códigos. Un bucle ingenuo que procesa un archivo a la vez se detiene en el primer archivo corrupto y no rastrea cuáles imágenes fallaron o las razones del fallo.
ChatGPT Codex es el agente de codificación de OpenAI. Opera en terminales, IDEs, la aplicación de escritorio de ChatGPT y la nube, todo bajo un único inicio de sesión en ChatGPT. IronQR es la biblioteca .NET de códigos QR de Iron Software.
Cada prompt instruye a Codex para realizar la tarea y generar un archivo de resultados que contiene una fila por imagen. Dado que los trabajos por lotes pueden procesar archivos que no producen resultados, todos los conteos referenciados en esta guía se derivan de estos archivos de resultados, como se indica en los prompts.
Inicio rápidoInicia Codex dentro de un proyecto de consola .NET que contenga tu carpeta de imágenes y especifica los requisitos de procesamiento por lotes.
$ironqr Add the IronQR package to this console project, then make Program.cs
decode every file in Backlog/sample/ with QrReader.ReadAsync. Write
out/quickstart.csv with one row per file (name, decoded value or empty, QR
type, exception type if the file threw) and print the decoded, empty, and
threw counts by reading that CSV back. Load the key out of the
IRONQR_LICENSE_KEY variable. Call Dispose() on each QrImageInput yourself
instead of a using block, which throws in IronQR 2026.10.1. Run dotnet build
and dotnet run and fix whatever fails.
La mención $ironqr carga la habilidad de IronQR antes de que Codex escriba código.
Flujo de trabajo mínimo (5 pasos)
- Descarga la biblioteca de códigos QR C# desde NuGet
- Guarda la habilidad de IronQR como
.agents/skills/ironqr/SKILL.mdpara que$ironqrse resuelva - Confirma un
AGENTS.mdcon las reglas de decodificación de QR del repositorio - Pide un modo a la vez (secuencial,
Parallel.ForEach, luegoSemaphoreSlim) y compare cada archivo de resultados con el último - Busca cada miembro que Codex utilizó en la referencia API y verifica el archivo de resultados final contra tu verdad base
¿Qué es ChatGPT Codex y cómo se ajusta al trabajo con códigos QR en .NET?
Codex trabaja dentro de los permisos que le otorgas. Escribe el decodificador, lo ejecuta sobre las imágenes, lee la salida y corrige el código. Instala el CLI con npm install -g @openai/codex desde el repositorio CLI de Codex, y consulta la documentación CLI de Codex para el uso en terminal.
Una acumulación con verdad base hace que la revisión sea breve. Un miembro inventado falla la compilación, y una decodificación incorrecta aparece como una fila que no concuerda con Backlog/manifest.csv.
El agente puede estructurar cada lote de manera diferente, pero el decodificador debe devolver el mismo valor para una imagen dada en cualquier conteo de hilos. Esa consistencia pertenece a la biblioteca, y IronQR cubre las partes que una acumulación necesita.
- Fotos y escaneos en una llamada: el modo
QrScanMode.Autoejecuta el modelo de detección y, cuando el modelo no encuentra nada, reintenta con un escaneo básico. La guía de modos de escaneo lo compara con los dos modos de pasada única. - El tipo de símbolo en cada resultado:
QrResult.QrTypesepara el QR estándar (QrEncoding.QRCode) del Micro QR y rMQR, para que un validador pueda rechazar etiquetas que no son etiquetas de activos.
¿Cómo escribir un prompt de IronQR y configurar Codex para ello?
Un prompt de lote efectivo para IronQR declara seis cosas. Para esta acumulación, la entrada es cada PNG y JPEG en Backlog/images/, un SemaphoreSlim dimensionado por una opción --concurrency establece la concurrencia, y la salida es out/pipeline.csv con una fila por archivo. Un archivo que lance un error obtiene una fila mientras el lote continúa. La prueba es una coincidencia fila por fila con out/sequential.csv, y las restricciones son sin nuevos paquetes y Auto como predeterminado.
La investigación de OpenAI sobre alucinaciones encuentra que la capacitación y evaluación recompensan las conjeturas, y en un trabajo por lotes la conjetura suele ser un total en el resumen final.
Codex descubre habilidades en la carpeta .agents/skills del repositorio, y cada habilidad es una carpeta que contiene un SKILL.md con un nombre y una descripción en su frontmatter. Guarda el skill.md de IronQR como .agents/skills/ironqr/SKILL.md y la mención $ironqr se resuelve. Codex también puede elegir la habilidad sin la mención cuando una tarea coincide con su descripción.
AGENTS.md lleva las reglas con las que comienza cada sesión. Codex lee como máximo un archivo de cada directorio entre la raíz del repositorio y la carpeta en la que se inició, y un archivo más profundo anula la orientación por encima de él. El comando /init redacta uno. El prompt a continuación también nombra el índice llms.txt de IronQR como referencia API.
Create the repository's AGENTS.md with a section titled QR decoding. It
should say that IronQR (package IronQR, namespace IronQr) is the only QR
library here, that the ironqr skill in .agents/skills/ironqr/ and IronQR's
llms.txt documentation index are the API references, that the key is read
from IRONQR_LICENSE_KEY and never printed or written to a file, that
QrImageInput is disposed with an explicit Dispose() call and never a using
block, that Backlog/manifest.csv is ground truth and read-only, and that any
count, rate, or timing you report must come from a per-image results file
written in the same turn, named in your reply.
¿Cómo le pides a Codex que agregue IronQR y decodifique una primera carpeta?
Show me the IronQR PackageReference in AssetBacklog.csproj and the installed
version. Then run dotnet list package --include-transitive and quote the lines
for IronQR.Slim and Microsoft.ML.OnnxRuntime, since the detection model
depends on them. Change no package references.
El paquete IronQR trae IronQR.Slim para la API administrada, Microsoft.ML.OnnxRuntime para la detección, y los lectores nativos de Windows. Un proyecto solo en IronQR.Slim, que en Windows también necesita IronSoftware.ReaderInternals.Windows, sigue leyendo con el escaneo básico, pero no puede ejecutar el modelo de detección. El paquete es IronQR con una R mayúscula mientras que el namespace es IronQr, por lo que una directiva using IronQR falla al compilar. Revisa el registro de cambios de IronQR antes de fijar una versión.
IronQR no añade una marca de agua de prueba a las lecturas. Una primera lectura sin licencia lanza LicensingException con el mensaje 'Production License Required', y con ReadAsync, la excepción aparece cuando se espera a que finalice la tarea. En un lote, eso se convierte en una fila de fallo idéntica por imagen.
Move the license setup into a Startup.ApplyIronQrKey method called first in
Program.cs. If IRONQR_LICENSE_KEY is unset or License.IsLicensed is false,
exit with code 2 and one clear line on stderr before any image is opened,
because IronQR throws on the first read instead of degrading. Run the program
once as is and once with the variable removed for that single command, and
report both exit codes and what IsLicensed returned.
La página de claves de licencia cubre las claves de prueba y los archivos de configuración que IronQR también lee. El tipo de excepción es interno al ensamblado IronQr, por lo que capturar LicensingException por tipo falla al compilar con el error CS0122.
Un decodificador secuencial viene a continuación, y su archivo de resultados se convierte en la referencia para cada modo más rápido.
Create Services/BacklogDecoder.cs with DecodeAsync(string path) returning an
ImageOutcome record: file, status (Decoded, Empty, Unreadable), values, QR
types, exception type and message, and milliseconds. Open the file with
AnyBitmap.FromFile, read with QrScanMode.Auto, and never let one file stop
the batch. Add a --sequential mode that runs it over Backlog/images/ one file
at a time, writes out/sequential.csv, and starts out/runs.csv with the mode
and wall time. Report the status counts and the wall time from those files.
¿Cómo se decodifica una carpeta en paralelo con IronQR?
La guía de asincronía y multihilos llama a un lector separado por iteración, ya que IronQR no garantiza explícitamente la seguridad de hilo para una instancia compartida. El siguiente prompt hace que el agente explorador incorporado de Codex, un agente centrado en la lectura para la exploración del código, verifique eso contra la documentación antes de que cualquier cosa se ejecute en paralelo.
Ask the explorer agent to answer this without editing anything. Before the
decoder goes parallel, list every QrReader, QrImageInput, and AnyBitmap that
BacklogDecoder creates or keeps, say which could be shared across threads,
and back each answer with a quote from
https://ironsoftware.com/qr/csharp/how-to/async-multithreading/ or the
ironqr skill. Flag anything the documentation leaves unstated.
En calibración, compartir un lector entre 32 hilos produjo los mismos resultados que un lector por archivo. Un lanzamiento posterior puede diferir, y un lector por archivo cuesta poco.
El objeto de entrada también necesita cuidado. En la versión 2026.10.1, un bloque using alrededor de él lanza NotImplementedException al salir, incluso después de una lectura exitosa, por lo que un lote registraría cada imagen buena como un fallo. Revisa cada diff para uno.
Para la versión paralela, el prompt nombra al agente de trabajo incorporado, que ejecuta la edición en su propio hilo.
Have the worker agent add a --parallel mode with Parallel.ForEach,
MaxDegreeOfParallelism from a --threads option (default
Environment.ProcessorCount), and a new QrReader per file. Use the synchronous
Read inside the loop body, since Parallel.ForEach does not await an async
lambda. Write out/parallel.csv sorted by file name, then compare its status
and value columns with out/sequential.csv and fix any row that differs
before you finish. Append mode, thread count, and wall time to out/runs.csv.
Una lambda async pasada a Parallel.ForEach se compila como async void, por lo que el bucle regresa antes de que las lecturas terminen y el archivo de resultados sale incompleto. La comparación con el archivo secuencial lo detecta.
¿Cómo limitar las lecturas concurrentes con ReadAsync?
Un bucle paralelo bloquea un hilo por lectura. ReadAsync detrás de un SemaphoreSlim mantiene un número fijo de lecturas en vuelo y deja el hilo llamador libre, el patrón que la guía async da para lotes de alto volumen. Toma un IQrInput y no tiene sobrecarga para una ruta de archivo, por lo que cada tarea aún abre su propio bitmap.
Add a --pipeline mode: Task.WhenAll over every file, each task waiting on a
SemaphoreSlim sized by --concurrency and awaiting ReadAsync. Run it at
concurrency 2, 8, and Environment.ProcessorCount, writing
out/pipeline-c<N>.csv for each and appending to out/runs.csv. Confirm each
file matches out/sequential.csv row for row, then tell me which setting was
fastest according to runs.csv.
El modelo de detección ya extiende una lectura en varios núcleos, por lo que un límite más alto no necesita ejecutarse más rápido. Deja que runs.csv elija el límite para tu hardware, y mantén el semáforo para lo que hace de manera confiable, que es limitar el uso de memoria.
¿Qué modo de escaneo debe usar un lote?
El modelo de detección lee fotos que el pase básico omite, y también contribuye a la mayor parte del tiempo que toma cada lectura.
Measure what the machine learning detector costs on this backlog. Run the
pipeline at the fastest concurrency from runs.csv, first under
QrScanMode.Auto and then under QrScanMode.OnlyBasicScan, writing
out/mode-auto.csv and out/mode-basic.csv with per-image milliseconds. Join
both with the category column of Backlog/manifest.csv and report decoded
count and median milliseconds per category for each mode. If either mode
reads files the other misses, keep Auto as the default and build a single
OnlyBasicScan retry of its Empty files into the decoder for every later run.
Rerun to out/mode-fallback.csv and count the recoveries.
Ambos modos leen cada escaneo limpio y copia de fax, y cada uno omitió un puñado diferente de fotos de teléfono. En las fotos que solo el pase básico leyó, el modelo de detección localizó el código y no pudo decodificarlo, por lo que Auto nunca retrocedió. Reintentando los archivos vacíos con QrScanMode.OnlyBasicScan recuperó cada foto.
¿Cómo validar valores decodificados y reportar fallos?
Un lote enfrenta tres tipos de fallos, y cada uno se ve diferente en el código.
| Entrada | Resultado | Estado |
|---|---|---|
| Vacío, truncado o archivo no imagen | La carga de la imagen lanza un error antes de que IronQR se ejecute | Ilegible |
| Sin código, o daño más allá de la corrección de errores | Una colección vacía, nunca nula | Vacío |
| Cualquier código, leído en el modo solo detección | Puntos de esquina, un Value vacío, un QrType de QrEncoding.None | Vacío, no Decodificado |
La tercera fila es la peligrosa. Nuestro primer decodificador secuencial lo habría contado como Decodificado, porque solo verificaba si llegaba algún resultado.
Backlog/README.md defines a valid asset tag. Add Services/TagValidator.cs and
apply it after each read: a decode only counts when the symbol is a standard
QR code (QrEncoding.QRCode), the value matches the documented pattern, and
the Luhn check digit holds. Give the others the statuses WrongSymbol,
InvalidFormat, or BadCheckDigit. Rerun the pipeline to out/validated.csv and
list every file whose status disagrees with expected_status in the manifest.
Un dígito de verificación es parte de tus datos, por lo que IronQR no puede validarlo. La corrección de Reed-Solomon dentro de la lectura, que describe la guía de suma de comprobación y tolerancia a fallos, solo prueba que el símbolo se decodificó, y un resultado no lleva propiedad de confianza. Una etiqueta con un dígito de verificación incorrecto se escanea limpiamente y sigue siendo inválida.
La guía de mensajes de error de IronQR muestra el patrón de registro por archivo que la siguiente prompt aplica a toda la acumulación.
Every file that is not Decoded needs a recorded reason. Write one JSON line
per file to out/decode-log.jsonl (file, status, exception type, message,
milliseconds), send IronQR's own log to out/ironqr-debug.log through
IronQr.Logging.Logger, and generate out/failures.md from the JSONL only: one
section per status other than Decoded, a count, and every file name. Then
check the section counts against out/validated.csv.
En la versión 2026.10.1, el registro IronQr.Logging.Logger registra la ruta de escaneo que tomó cada lectura, como un escaneo de detección con el modelo de aprendizaje automático. Debido a que el informe se construye solo a partir del JSONL, una falla que el decodificador nunca registró aparece como un conteo que no concuerda con el archivo de resultados.
¿Cómo diagnosticar una imagen que no se decodifica?
Codex puede mirar una imagen. Adjunta el archivo con codex --image cuando inicies la sesión, o pégalo en el compositor.
I attached IMG_0018.png from Backlog/images/ with codex --image. The pipeline
marks it Empty. Look at the picture and tell me whether it is a damaged code,
a page with no code, or a capture problem a rescan would fix. Then test your
answer: read it with all three QrScanMode values and write
out/retry-IMG_0018.csv. Do not change the pipeline.
En nuestra ejecución, los tres modos regresaron vacíos para este archivo, y en calibración el modelo de detección no encontró nada que localizar. El código en sí está dañado, por lo que la pérdida supera lo que la corrección de errores recupera, y ni otra lectura ni un nuevo escaneo de la misma etiqueta cambiarán eso. La solución es una etiqueta de reemplazo y, si imprimes las etiquetas tú mismo, un nivel de corrección de errores más alto.
¿Cómo depurar una salida incorrecta de lote de principio a fin?
Send the explorer agent into Jobs/NightlyImport.cs and Logs/nightly-2026-10-06/
before anything is edited. That run reported six unreadable files and no other
failure, yet Backlog/archive-index-gaps.csv lists assets the archive never
received. Find what the missing assets have in common, explain why the job
counted them as successes, and propose the smallest fix together with the
command that would prove it. Put the findings in out/nightly-diagnosis.md and
change no code.
Aprueba el diagnóstico antes de cualquier arreglo. Uno bueno cita la línea que decide el éxito. Comprueba la solución propuesta contra out/mode-fallback.csv también.
¿Cómo convierte el código único en componentes reutilizables y probados?
Put the worker agent on folding the modes into a BacklogJob class. Add the
Microsoft.Extensions.DependencyInjection package, register the job with it,
and configure it with a BacklogOptions record (input folder, concurrency,
scan mode, output folder). Keep the validator, the basic-scan retry, and the
logging in it, stay under 160 lines, and add XML doc comments. Before
finishing, run it over Backlog/images/ into out/final.csv and confirm every
row agrees with the manifest's expected_status and expected_value.
Un refactor puede eliminar el validador, el reintento de escaneo básico o el lector por archivo sin un error de compilación. Solo una repetición completa contra la verdad base detecta eso.
Add an xUnit project, AssetBacklog.Tests, and cover BacklogJob with tests
that read real files from Backlog/images/: a clean scan decodes to its
manifest value, the zero-byte file comes back Unreadable without throwing, a
damaged image is Empty, a Micro QR label is WrongSymbol, a bad check digit is
BadCheckDigit, and a parallel run over 40 files matches a sequential one.
Assert on status and value. Run dotnet test and report the totals it prints.
El manifiesto corrige el estado y el valor, mientras que los tiempos cambian de ejecución en ejecución.
Mantén las preguntas recurrentes de IronQR en la habilidad del repositorio. La página prompts personalizados de OpenAI marca la carpeta ~/.codex/prompts más antigua como obsoleta en favor de las habilidades.
$ironqr Using the IronQR API reference, list every member of QrResult and say
whether IronQR reports a confidence or checksum score for a read. Then point
to the line in BacklogJob that decides a file is Decoded.
En nuestra ejecución, Codex enumeró los cuatro miembros de un resultado y rastreó Decodificado desde el trabajo a través del decodificador hasta la línea del validador que lo retorna.
¿Cómo reutilizar estos prompts en otra carpeta de imágenes?
Cambia las rutas, y cada prompt anterior se ejecuta tal como está escrito. La guía de asistentes de codificación AI ejecuta un prompt de aceptación único de principio a fin y publica el resultado.
¿Qué produjeron los prompts en una ejecución real?
Enviamos cada prompt anterior a Codex en orden, en un hilo, contra un repositorio de ejemplo. Contiene una aplicación de consola y una acumulación de 301 imágenes (escaneos limpios, fotos de teléfono, copias de fax, etiquetas dañadas, hojas de portada en blanco, etiquetas de estantería Micro QR, etiquetas inválidas y seis archivos que no son imágenes en absoluto), con un manifiesto del estado y valor esperado de cada una. Después de la sesión, reconstruimos el proyecto en Release y ejecutamos las pruebas. También decodificamos cada imagen de forma independiente para verificar los resultados a continuación.
- El reintento de escaneo básico elevó Decodificado de 256 a 264. Antes de eso, cada modo decodificó 256 de 301, y 16 archivos diferían entre los dos.
- Un escaneo limpio tomó una mediana de 360 ms bajo Auto y 35 ms bajo el escaneo básico, que ejecutó toda la acumulación en 7 s con límite de 2.
- El decodificador secuencial registró 256 Decodificados, 39 Vacíos y 6 Ilegibles en 71 s.
- El modo paralelo escribió las mismas 301 filas en 60 s con 32 hilos, y el pipeline las escribió en 55, 66 y 68 s con límites de 2, 8 y 32.
- En el inicio rápido, 9 de 12 filas fueron decodificadas, 2 regresaron vacías y un archivo de cero bytes falló.
- La validación coincidió con el manifiesto con 240 Decodificados, 31 Vacíos, 8 SímboloIncorrecto, 8 FormatoInválido, 8 DígitoVerificaciónIncorrecto y 6 Ilegibles.
- El informe de fallos contenía 61 registros, uno por archivo fallido.
- Después del refactor, el trabajo de 64 líneas coincidió con el manifiesto en 301 de 301 filas, y 6 de 6 pruebas pasaron, nuevamente en Release.
- Los 16 prompts se ejecutaron con cada compilación aprobando y sin ediciones manuales de código. Los prompts 13 a 16 alcanzaron el límite de uso del plan gratuito y se reanudaron en el mismo hilo después de que Codex iniciara sesión de nuevo.
- Antes del prompt de investigación, añadimos un trabajo nocturno con un fallo plantado, sus registros y una lista de brechas. Codex encontró el modo solo detección en los JPEG de foto y una verificación de éxito que acepta cualquier resultado.
La versión, modelo, tiempo y máquina de pruebas de Codex para esta ejecución están en el registro compartido de ejecución.
Solución de problemas
- Asincronía y Multihilos si una ejecución paralela escribe menos filas de las que hay imágenes
- Aplica una clave de licencia en IronQR si cada fila en el archivo de resultados muestra el mismo fallo de licencia
- Lee códigos QR con modos de escaneo si los resultados regresan con puntos de esquina y sin valores
- Excepción de copia en tiempos de ejecución si el modelo de detección no se carga después de una publicación
¿Preguntas?
Si tienes alguna pregunta, contacta a support@ironsoftware.com
Curtis Chau tiene una licenciatura en Ciencias de la Computación (Carleton University) y se especializa en el desarrollo front-end con experiencia en Node.js, TypeScript, JavaScript y React. Apasionado por crear interfaces de usuario intuitivas y estéticamente agradables, disfruta trabajando con frameworks modernos y creando manuales bien estructurados y visualmente atractivos.