Blog

Codex CLI, structured JSON outputs, and cron-safe AI workers

บันทึกวิศวกรรม Naly: Codex CLI, JSON แบบมีโครงสร้าง และ AI Worker ที่ปลอดภัยใน Cron

บันทึกนี้อธิบายว่า Naly แปลง Codex CLI จากตัวแทนโค้ดดิ้งผ่านเทอร์มินัลให้กลายเป็น worker สำหรับ production ที่กำหนดผลลัพธ์ได้อย่างแน่นอน โดยผสมผสานการตั้งเวลา cron, สัญญา JSON ที่เข้มงวด และการจัดเก็บล็อกภายนอก พร้อมอธิบายว่าความน่าเชื่อถือเกิดจาก invariant ทางปฏิบัติการ—การล็อก การลองใหม่ และการตรวจสอบ—ในขณะที่โมเดลยังคงสามารถเปลี่ยนได้,,

June 25, 20269 sources

บทคัดย่อ

Naly ใช้ Codex CLI เป็น control plane สำหรับงาน AI ตามกำหนดเวลา โดยแต่ละบรรทัด cron รันสคริปต์ที่เช็คอินใน repository ซึ่งเรียกงานผู้ช่วยแบบมีขอบเขตที่กำหนดไว้อย่างชัดเจนพร้อม web search และสัญญาผลลัพธ์ที่เข้มงวด จากนั้นบันทึกไฟล์ JSON ที่ผ่านการตรวจสอบสำหรับงาน downstream อย่างการเผยแพร่ การ replay และการลองใหม่อีกครั้ง ทำให้การทำงานของโมเดลมีลักษณะเหมือน pipeline การปฏิบัติการ—คำสั่งเดิม, schema ที่ชัดเจน, artifacts ที่ชัดเจน—แทนที่จะเป็น workflow เชิงโต้ตอบที่แปรผันได้ง่าย ในวันที่ 25 มิถุนายน 2026 ความแตกต่างนี้คือความได้เปรียบด้านความน่าเชื่อถือสำหรับโครงสร้างพื้นฐานเนื้อหาสำคัญต่อการเติบโต

ตำแหน่งที่อยู่ใน Naly

Naly มีความสำคัญเชิง GST อยู่แล้วสำหรับงาน discovery, retention และ distribution และรูปแบบนี้เชื่อมเข้ากับชั้นการปฏิบัติการเหล่านั้นโดยตรง

  • งาน cron เรียก tsx สคริปต์เดียวต่อ use case เพื่อให้แต่ละรันคงอยู่ในโค้ดที่อยู่ในเวอร์ชันควบคุม ไม่ใช่ snippet shell ad hoc
  • Codex CLI ทำงานด้าน reasoning และ retrieval ในขณะที่ Naly ดูแลการ orchestration: การตั้งเวลา, การลองใหม่, การล็อก และการจัดเก็บ artifacts แบบถาวร
  • ผลลัพธ์แบบมีโครงสร้างถูกป้อนไปยังระบบ downstream ที่สร้างด้วย Next.js, React, Drizzle ORM และ Neon โดยไม่ต้องเดา schema ทาง downstream
  • บันทึก logs และ metadata ของการรันถูกเขียนไว้ที่ NALY_LOG_ROOT, ทำให้ post-mortem ทำซ้ำได้และไม่ขึ้นกับการบัฟเฟอร์ผลลัพธ์ของ process

แก่นของแนวคิดคือ: สำหรับการใช้งาน production คุณภาพของ LLM เป็นเพียงครึ่งหนึ่งของระบบ; ขอบเขตที่ deterministic รอบ ๆ LLM เท่านั้นที่เป็นอีกครึ่งหนึ่ง

กลไกทางเทคนิค

1) จุดเริ่มงาน worker แบบ Contract-first

แต่ละงานเริ่มจากอินพุตที่คงที่สามอย่าง

  • เทมเพลต prompt ที่กำหนดรูปแบบไว้แล้ว และเจตนางาน
  • schema การตอบกลับที่ต้องผ่านการตรวจสอบ
  • run envelope (run_id, source_query, attempt, env), ซึ่งถูกเก็บก่อนเรียก API

Naly เรียกใช้ Codex CLI ในโหมด batch จาก cron ไม่ใช่โหมด interactive Codex ถูกระบุว่าเป็น local coding agent และจัดจำหน่ายเป็น CLI สแตนด์อโลนแบบ open-source ที่มีการปล่อยเวอร์ชันอย่างต่อเนื่อง และสามารถรันในสภาพแวดล้อมแบบ scripted ได้ Codex CLI, OpenAI Codex repo.

2) เหตุผลที่ผลลัพธ์แบบมีโครงสร้างไม่อาจต่อรองได้

คู่มือ Structured-output ของ OpenAI อธิบายการสกัด schema ที่ parser รองรับและพฤติกรรม strict mode ที่จำเป็นสำหรับ machine pipeline ใน Naly เอาต์พุตของโมเดลถูกมองเป็น artifact ระดับกลาง ไม่ใช่ความจริงสุดท้าย ดังนั้น contract ของ JSON จึงเป็นที่บังคับใช้ความน่าเชื่อถือหลัก

  • fields ที่ต้องมี (headline, evidence list, confidence, citations, failure reason)
  • fields ที่เป็นตัวเลือกพร้อมค่าเริ่มต้น
  • confidence เป็นตัวเลขและ enums ที่มีขอบเขตจำกัด
  • ความล้มเหลวของ parser ที่ชัดเจนถูกเผยต่อเป็น run error ไม่ใช่ถูกแก้ไขข้อความแบบเงียบ ๆ โดยอัตโนมัติ

3) วงจรการทำงาน Cron-to-agent พร้อมควบคุม concurrency

Cron ทำงานตามบรรทัดที่ตั้งเวลาโดยอิงฟิลด์เวลา 5 ช่องมาตรฐานและเรียกคำสั่งเมื่อเงื่อนไขตรงกัน crontab. เพื่อความปลอดภัยในการใช้งานจริง Naly เพิ่ม:

  • lock guard (รัน active เดี่ยวต่อหนึ่งงาน)
  • idempotent run key
  • นโยบาย retry ที่มีขอบเขตและ jitter
  • การจับ log ภายนอกในทุกช่วงเวลา
  • การอัปเดตสถานะหลังรันในตารางฐานข้อมูลที่ Drizzle/Neon จัดการ

flock ถูกออกแบบมาเพื่อกรอบกันชนนี้โดยตรง: รับ lock, รัน critical section, และออกอย่างสะอาดเมื่อมีคนล็อกอยู่แล้ว flock. เนื่องจากสถานะ lock อิงตาม file descriptors จึงปฏิเสธหน้าต่าง cron ที่ทับซ้อนกันแบบชัดแจ้ง แทนที่จะทำให้ state เสียหาย

4) เหตุผลที่ MCP สำคัญในรูปแบบนี้

Model Context Protocol formalizes สัญญา host/client/server ของเครื่องมือด้วย JSON-RPC, capability negotiation และการเรียกเครื่องมือแบบมีโครงสร้าง MCP. ใน Naly ขอบเขตแนว MCP ลด coupling โดยนัย: การค้นหาเว็บสามารถแทนด้วยอินเทอร์เฟซเครื่องมือที่ควบคุมได้พร้อม capabilities ที่ชัดเจนแทนพฤติกรรมแบบ free-form ระดับ shell

สิ่งที่งานวิจัยชี้แจง

งานวิจัยล่าสุดชี้ว่า reliability ไม่ได้เท่ากับ raw capability งาน AI Agent Reliability พบช่องว่างมากระหว่างความแม่นยำของงานกับความสอดคล้องของผลลัพธ์ระหว่างรัน และเสนอมิติความน่าเชื่อถือแบบชัดแจ้ง (consistency, robustness, predictability, safety) สำหรับการประเมินเชิงปฏิบัติ Towards a Science of AI Agent Reliabilityข้อสรุปนี้สนับสนุนการออกแบบแบบ run-state-first ของ Naly: ถ้ารันงานผ่านแต่ไม่สามารถทำซ้ำได้ด้วย artifact ที่ชัดเจน ก็ไม่ถือว่ามี production-grade

สำหรับการใช้ผลลัพธ์แบบมีโครงสร้าง ToolPRM ชี้ว่าพฤติกรรมการเรียกเครื่องมือแบบมีโครงสร้างต้องการการดูแลแบบ explicit และการปรับปรุงจะแข็งแรงขึ้นมากเมื่อแบบจำลองกระบวนการเรียกฟังก์ชันภายใน ไม่ใช่แค่ผลลัพธ์สุดท้าย ToolPRM: Fine-Grained Inference Scaling of Structured Outputs for Function Callingซึ่งสอดคล้องกับ loop รันแบบ schema-first ของ Naly โดยเกณฑ์คุณภาพอยู่ที่พรมแดน interface มากกว่าที่ความคล่องแคล่วของเนื้อหา

งานวิจัยชิ้นที่สามบนแนวหน้าเดียวกัน SLOT แสดงแนวทางทางเลือกเชิงปฏิบัติด้วยการเพิ่มชั้น shaping ผลลัพธ์ที่ไม่ผูกกับโมเดลบน LLM SLOT: Structuring the Output of Large Language Modelsซึ่งตอกย้ำหลักการเดียวกันว่า reliability ของโครงสร้างคือปัญหาวิศวกรรม แม้คุณภาพโมเดลพื้นฐานจะสูง

Trade-off การออกแบบ

  1. Strict schema vs. ความสามารถในการย้ายโมเดล: schema ที่เข้มงวดลดความคลุมเครือด้าน downstream แต่ทำให้เกิด parse churn เป็นครั้งคราวมากขึ้น เมื่อผู้ให้บริการตีความข้อจำกัดไม่เหมือนกัน
  2. Cron simplicity vs. queue elasticity: cron ใช้งานง่ายและมองเห็นได้ชัด แต่ workload ที่เกิดแบบ burst ต้องมี lock-aware backoff หรือชั้น queue เพื่อหลีกเลี่ยงรันซ้อนและพลาดช่วงเวลา
  3. การค้นหาเว็บขณะทำงาน vs. การ replay แบบ deterministic: web search แบบสดช่วยความทันสมัยแต่เพิ่มความผันผวนของแหล่งข้อมูล ดังนั้น Naly จึงเก็บข้อความ query รายการแหล่งที่มา และ reference ต้นทางใน artifacts ของแต่ละรัน
  4. External logs vs. DB-only logs: logs ใน filesystem รอดชีวิตได้แม้ process restart และต้นทุน ingest ต่ำ; logs ที่เก็บใน DB ทำ query ได้สะดวกกว่า แต่เสี่ยงเกิด open loops ได้ถ้า partition ไม่รัดกุม

โหมดความล้มเหลว

  • Schema drift: output จาก provider ผิด schema; การป้องกันคือการ validate แบบ fail-fast, pin เวอร์ชัน schema, และ run ที่ถูกส่งไป dead-letter
  • Overlapping cron executions: เขียนข้อมูลซ้ำหรือทำ action ภายนอกซ้ำ; การป้องกันคือ advisory lock ร่วมกับ process-exit guard
  • Search instability: ข้อความตอบจากเครื่องมือด้านบนเปลี่ยนแปลงระหว่างครั้ง; การป้องกันคือ จำกัดจำนวน retry, หน่วงแบบ exponential delay, และเก็บ reference ต้นทางที่คงไว้
  • Timing surprises: ความต่างของ DST และ timezone ของ host สามารถกระทบความหมายของ schedule; การป้องกันคือกำหนดนโยบาย UTC scheduling และตรวจสอบสภาพแวดล้อมอย่างชัดแจ้ง
  • Silent partial writes: parse ผ่านแต่การเขียน downstream ล้มเหลว; การป้องกันคือการจัดลำดับ persist แบบ transactional และ idempotent upsert
  • Security/context leakageเส้นทางของตัวแทนที่มีสิทธิ์ใช้เครื่องมือสามารถทำงานเกินขอบเขตได้ จึงต้องมีขอบเขตแบบ least-privilege ที่คล้าย MCP และสมมติฐาน consent/auth แบบชัดแจ้ง โดยเฉพาะเมื่อเส้นทางการรันเครื่องมือสัมผัสทรัพยากรเครือข่าย หมายเหตุด้านความปลอดภัยของ MCP.

หมายเหตุการนำไปใช้งาน

  • เก็บคำสั่ง worker หนึ่งคำสั่งต่อหนึ่งธุรกิจ task ใน scripts/ และให้ cron เรียกเพียง entrypoint นั้นเท่านั้น
  • เก็บ hash ของไฟล์ schema ใน run metadata เพื่อให้คาดหวังของ parser ตรวจสอบย้อนกลับได้หลังจากมีการอัปเกรดโมเดล
  • ตั้งค่า set -euo pipefailพฤติกรรมแบบ -style ในสคริปต์ wrapper และใส่ run IDs ในชื่อไฟล์ logs เสมอ
  • เขียน checkpoint สามจุดลง logs: started, codex_result_parsed, artifact_persisted.
  • ใช้ NALY_LOG_ROOT เพื่อให้ runtime traces ไม่ปนเปื้อนสถานะของ repository และคงอยู่แม้เกิด restart
  • จัดเก็บ attempt, exit_code, retry_reason และ validation_errors เพื่อให้ GST และแดชบอร์ด audit แยกความผิดพลาดของโครงสร้างพื้นฐานที่แกว่งออกไปจากการถดถอยของโมเดลที่แท้จริง

อ้างอิง

Sources