ถ้าทีมกำลังนำรายชื่อลูกค้าเข้า ERP แล้ว AI บอกว่า “พร้อมนำเข้าแล้ว” ผมอยากเห็นมากกว่ารายงานว่ารันผ่านครับ ต้องรู้ว่ารายการไหนจะเพิ่ม รายการไหนซ้ำ และรายการไหนยังตัดสินใจไม่ได้ ก่อนให้โปรแกรมแตะข้อมูลจริง
บทนี้ต่อจาก Harness Engineering กับ Google Antigravity คราวนี้เราจะลงมือซ้อมด้วยข้อมูลลูกค้าสมมติ 6 แถว ตั้งขอบเขตการทำงาน ติดตั้งจุดตรวจก่อนรันคำสั่ง และตรวจรายงานที่ทำซ้ำได้
สิ่งที่จะได้คือแผนนำเข้าแบบ dry-run ซึ่งยังไม่เขียนเข้า ERP ชุดตัวอย่างใช้ Python standard library ไม่มีส่วนเชื่อม API ฐานข้อมูล หรือคำสั่งนำเข้าจริง เรียก Python เองได้ แม้ยังไม่ได้ติดตั้ง Antigravity
ดาวน์โหลด ชุดไฟล์แบบฝึกหัดและเช็กลิสต์ไทย–อังกฤษ ก่อนเริ่ม ข้อมูลทั้งหมดเป็นข้อมูลแต่งขึ้นสำหรับบทเรียน ไม่ใช่ข้อมูลลูกค้าจริง
1. กำหนดว่างานจบตรงไหน
ในเคสนี้ เจ้าของข้อมูลต้องการตรวจไฟล์ลูกค้าใหม่เทียบกับรายชื่อเดิม โดยใช้เลขประจำตัวผู้เสียภาษีเป็นกุญแจจับคู่ กติกาสำหรับการซ้อมคือ ชื่อและอีเมลตรงกันหลังปรับรูปแบบจึงข้ามรายการเดิมได้ ถ้าเลขเดียวกันแต่รายละเอียดขัดกันให้หยุดไว้ตรวจ คนต้องเป็นผู้ตัดสินใจว่าจะใช้ข้อมูลใด
กติกานี้เป็นนโยบายสมมติของบทเรียน เลข 13 หลักใช้ทดสอบรูปแบบเท่านั้น ไม่ได้ตรวจ checksum หรือยืนยันเลขภาษีจริง ไม่ได้ตรวจทะเบียนนิติบุคคล และไม่ได้ครอบคลุมสาขา หลายบริษัท คู่ค้าต่างประเทศ หรือข้อมูลบุคคลทุกประเภท
| สิ่งที่ต้องรู้ | หลักฐาน |
|---|---|
| แต่ละแถวจะเกิดอะไรขึ้น | plan.csv ระบุ create_proposal, skip หรือ reject |
| มีข้อมูลที่ยังตกลงไม่ได้หรือไม่ | rejected.csv และเหตุผลรายแถว |
| นับครบหรือไม่ | จำนวนรับเข้า = เสนอเพิ่ม + ข้าม + ปฏิเสธ |
| เขียนข้อมูลจริงแล้วหรือยัง | erp_writes = 0 และไม่มีตัวเชื่อมต่อ ERP |
2. เปิดโฟลเดอร์ทดลองแยกจากงานจริง
แตก ZIP ไปยังโฟลเดอร์ใหม่ เช่น erp-harness-lab แล้วเปิด Terminal ในโฟลเดอร์ที่มี AGENTS.md อย่าเปิดโฟลเดอร์บริษัททั้งก้อนหรือคัดลอกไฟล์ .env เข้ามา ชุดนี้ไม่ต้องใช้ข้อมูลเข้าสู่ระบบ ERP
python3 --version
python3 -m unittest discover -s tests -v
ใช้ Python 3.9 ขึ้นไปตาม README ของชุดไฟล์ ถ้าหา scripts/ หรือ tests/ ไม่เจอ ให้ตรวจว่าคุณอยู่ในโฟลเดอร์ชั้นในที่ถูกต้องก่อนแก้คำสั่ง
AGENTS.md
.agents/hooks.json
data/customers.csv
data/existing-customers.csv
hooks/pre_tool_use.py
scripts/dry_run.py
scripts/hook_probe.py
tests/
reports/
CSV ใช้หัวคอลัมน์ source_id,name,tax_id,email โดย source_id เป็นรหัสอ้างอิงแถวในชุดฝึก ยังไม่ใช่ Odoo External ID รายงานเก็บ hash ของไฟล์รับเข้าและรายชื่อเดิมเพื่อบอกว่าซ้อมกับข้อมูลชุดใด หากรายชื่อจริงเปลี่ยนหลังตรวจ ต้องซ้อมกับ snapshot ใหม่ก่อนนำไปออกแบบการเขียนจริง
อ่าน AGENTS.md และสคริปต์ก่อนให้เอเจนต์ทำงาน ไฟล์คำแนะนำอธิบายเป้าหมายและข้อห้าม แต่ไม่ได้บังคับสิทธิ์ของระบบด้วยตัวมันเอง และไฟล์ CSV ก็ถือเป็นข้อมูลที่จะตรวจ ไม่ใช่ข้อความที่มีสิทธิ์สั่งให้เอเจนต์เปลี่ยนกติกา
3. เปิด sandbox แล้วตรวจสถานะจริง
ติดตั้งและเข้าสู่ระบบ Antigravity ตาม คู่มือเริ่มต้นของ Google จากนั้นตรวจเวอร์ชันและคำสั่งที่เครื่องคุณรองรับ
agy --version
agy --help
agy --sandbox
ในหน้าสนทนา CLI เปิด /config ตรวจว่า Sandbox Mode ใช้งานได้จริง แล้วตั้ง Agent Mode เป็น default ตาม คู่มือ execution modes สำหรับแบบฝึกหัดนี้ไม่อนุมัติการออกนอก sandbox และไม่เพิ่มสิทธิ์เชื่อมต่อ ERP หรือปลายทางเครือข่าย ถ้าเครื่องมีสิทธิ์ที่เคยอนุมัติไว้กว้าง ๆ ให้แยกบัญชีหรือสภาพแวดล้อมทดลองที่ตรวจสิทธิ์ได้ก่อน
การใส่ --sandbox ไม่ได้พิสูจน์ว่ามีการแยกสภาพแวดล้อมแล้ว เอกสาร CLI ระบุว่าบนระบบที่ไม่รองรับ flag นี้อาจไม่มีผล จึงต้องตรวจสถานะและหยุดการทดลองแบบเอเจนต์หากยืนยันไม่ได้ ใช้ Python ซ้อมกับข้อมูลสมมติแยกต่างหากได้ รายละเอียด sandbox และข้อจำกัด
อย่าแก้ปัญหารันไม่ได้ด้วยการเพิ่มสิทธิ์กว้างหรือปิดการตรวจสอบ ในทีมจริง คนดูแลเครื่องควรทดสอบขอบเขตด้วยไฟล์และปลายทางทดสอบที่ไม่มีความลับ ก่อนเปิดให้ใช้ข้อมูลที่มีความอ่อนไหว
ถ้าต้องตั้งค่าถาวร ให้เทียบ cli-settings.example.json กับไฟล์ ~/.gemini/antigravity-cli/settings.json ของคุณแล้วรวมเฉพาะค่าที่ตั้งใจใช้ อย่าเขียนทับไฟล์เดิม ตัวอย่าง enableTerminalSandbox: true กับ toolPermission: "proceed-in-sandbox" ให้คำสั่งใน sandbox ทำงานได้ แต่ยังต้องตรวจ Agent Mode และสิทธิ์เดิมแยกกัน แบบฝึกนี้ใช้ default และไม่อนุมัติการออกนอก sandbox
4. ตั้ง hook ให้ตรวจก่อนรันคำสั่ง
ชุดไฟล์มี .agents/hooks.json อยู่แล้ว ตัวอย่างนี้ผูก PreToolUse กับ run_command แล้วเรียก hooks/pre_tool_use.py ไฟล์ตั้งค่าเป็นแบบ workspace ไม่ต้องย้ายไปปนกับการตั้งค่าส่วนกลาง
{
"erp-dry-run-gate": {
"PreToolUse": [{
"matcher": "run_command",
"hooks": [{
"type": "command",
"command": "python3 hooks/pre_tool_use.py",
"timeout": 10
}]
}]
}
}
เปิด session ใหม่จากโฟลเดอร์นี้ แล้วพิมพ์ /hooks เพื่อตรวจว่า hook โหลดและเปิดใช้งานจริง Hook รับ JSON ทาง stdin และส่งคำตัดสินทาง stdout ตามสัญญาของ Antigravity hooks คำสั่งในบทนี้ต้องรันจากรากโฟลเดอร์ตัวอย่าง หาก CLI ของคุณไม่โหลดไฟล์หรือส่งข้อมูลไม่ตรง schema ให้หยุดและตรวจเวอร์ชันก่อน
hook ของบทเรียนยอมรับเฉพาะรูปคำสั่งที่กำหนดไว้และโฟลเดอร์ที่ตรงกัน ข้อมูลไม่ครบหรือคำสั่งนอกขอบเขตให้ deny ส่วนคำสั่งที่ผ่านส่ง allow เพื่อให้กฎสิทธิ์ปกติตัดสินต่อ คำว่า allow จึงไม่ได้หมายถึงข้ามการตรวจสิทธิ์ทั้งหมด
ขอบเขตนี้ครอบคลุมเครื่องมือที่ matcher ระบุเท่านั้น เครื่องมือเขียนไฟล์หรือเครื่องมืออื่นอาจไม่ผ่าน hook นี้ และเอเจนต์ที่แก้สคริปต์หรือไฟล์ hook ได้ก็เปลี่ยนพฤติกรรมได้ ในทีมจริงต้องมีคนถือสิทธิ์แก้กฎ ตรวจ diff และใช้ข้อจำกัดของสภาพแวดล้อมร่วมด้วย
5. ทดสอบทั้งคำสั่งที่ผ่านและคำสั่งที่ต้องถูกบล็อก
python3 scripts/hook_probe.py
python3 scripts/hook_probe.py blocked
probe ส่ง payload จำลองเข้า hook โดยตรง กรณีแรกควรได้ allow กรณี blocked ควรได้ deny มันไม่ได้รันคำสั่งอันตรายที่ใช้เป็นตัวอย่าง การทดสอบนี้ตรวจโค้ด hook ส่วนการพิสูจน์ว่า Antigravity เรียก hook จริงต้องดู /hooks และผลการเสนอคำสั่งใน session อีกครั้ง
ทีมควรเพิ่มกรณีข้อมูล JSON เสีย ไม่ระบุโฟลเดอร์ และคำสั่งที่มีการต่อคำสั่งไว้ท้ายบรรทัด ตรวจในชุดทดสอบว่าไม่มีกรณีใดหลุดเป็น allow เพราะอ่านข้อมูลไม่สำเร็จ
6. รันไฟล์ที่มีปัญหา แล้วอ่านรายงานก่อนแก้
python3 scripts/dry_run.py --input data/customers.csv --existing data/existing-customers.csv --output reports
ไฟล์ตั้งต้นจงใจใส่ข้อมูลที่ต้องหยุดไว้ตรวจ โปรแกรมจบด้วย exit code 2 พร้อมรายงาน อย่าเปลี่ยนโค้ดให้คืน 0 เพียงเพื่อให้หน้าจอขึ้นว่าผ่าน
| สถานะ | จำนวน | ความหมาย |
|---|---|---|
| create_proposal | 2 | เสนอเพิ่ม Lotus และ Hill ยังไม่ได้บันทึก |
| skip | 2 | River ตรงกับข้อมูลเดิม และ Lotus ซ้ำในไฟล์ |
| reject | 2 | Forest มีอีเมลผิด และ River มีรายละเอียดขัดกัน |
| erp_writes | 0 | ไม่มีการเขียนเข้า ERP |
เปิด plan.csv ดูทั้ง 6 แถว เปิด rejected.csv ดูเหตุผล 2 แถว แล้วอ่าน reconciliation.json ตรวจสมการ 6 = 2 + 2 + 2 การนับครบช่วยจับแถวที่หายไประหว่างแปลงข้อมูล แต่ยังไม่ยืนยันว่ากติกาจับคู่ถูกสำหรับธุรกิจทุกกรณี

รายงาน CSV เติมเครื่องหมาย apostrophe หน้าเซลล์ที่เริ่มด้วย = + - @ เพื่อลดโอกาสที่โปรแกรมตารางคำนวณจะตีความเป็นสูตร ไฟล์ต้นทางยังเดิม วิธีแสดงผลนี้เป็นอีกเหตุผลที่ไม่ควรนำรายงานไปใช้เป็นไฟล์นำเข้าจริง
7. ให้เอเจนต์ทำงานจากโจทย์ที่ตรวจรับได้
เมื่อ sandbox และ hook ผ่านการตรวจแล้ว ใช้ข้อความนี้ใน session ที่เปิดจากโฟลเดอร์ตัวอย่างได้ ตัวโจทย์กำหนดให้เอเจนต์รายงานสิ่งที่พบก่อน ไม่ให้แก้กฎเพื่อทำให้ผลดูดี
อ่าน AGENTS.md และ README ก่อน รันทดสอบที่อนุญาต แล้วซ้อมนำเข้าจาก data/customers.csv เทียบ data/existing-customers.csv ลง reports เท่านั้น อธิบายผลรายแถวและตรวจยอดรับเข้า = เสนอเพิ่ม + ข้าม + ปฏิเสธ ห้ามเชื่อม ERP ห้ามเพิ่มสิทธิ์เครือข่าย ห้ามแก้ hook กติกาจับคู่ หรือไฟล์ต้นทาง หากถูกบล็อกให้หยุดพร้อมเหตุผล สรุปคำสั่งที่รัน exit code ไฟล์รายงาน และประเด็นที่เจ้าของข้อมูลต้องตัดสินใจ
ถ้าเอเจนต์ขอแก้โค้ดก่อนอ่าน rejected.csv ให้กลับมาที่เหตุผลรายแถวก่อน ความผิดในข้อมูลกับความผิดในโปรแกรมต้องมีวิธีแก้คนละแบบ หากสคริปต์มีบั๊กจริง คนทบทวนโค้ดควรอนุมัติขอบเขตการแก้แล้วรันทดสอบใหม่
8. แก้ข้อมูลเป็นสำเนา แล้วซ้อมซ้ำ
อย่าเขียนทับไฟล์ตั้งต้น เจ้าของข้อมูลควรแก้อีเมลจากหลักฐานที่ตรวจได้ และตัดสินใจกรณีเลขภาษีเดียวกันแต่ชื่อไม่ตรง ในแบบฝึกหัดใช้ไฟล์ clean ที่ให้มาเป็นคำตอบสมมติ ไม่ใช่คำแนะนำให้ลบแถวที่มีปัญหาจริงทิ้ง
ไฟล์ data/customers-clean.csv เก็บ 6 แถวไว้ครบ โดยสมมติว่าเจ้าของข้อมูลยืนยันอีเมล SRC-005 เป็น team@forest.example และชื่อ SRC-006 เป็น River Demo Ltd แล้ว ผลที่คาดคือ 6 = 3 เสนอเพิ่ม + 3 ข้าม + 0 ปฏิเสธ ได้ exit code 0 และสถานะ ready_for_human_review ซึ่งแปลว่ารอคนตรวจ ยังไม่ใช่อนุญาตให้นำเข้าจริง
python3 scripts/dry_run.py --input data/customers-clean.csv --existing data/existing-customers.csv --output reports-clean
หลังตรวจผลแล้ว รันคำสั่งเดิมอีกครั้ง ผลการจัดประเภทและยอดควรเหมือนเดิมเมื่อข้อมูลและกติกาไม่เปลี่ยน การทดสอบนี้พิสูจน์เพียงความสม่ำเสมอของ dry-run ยังไม่ได้พิสูจน์ idempotency ของการเขียนจริง ซึ่งต้องมีตัวเชื่อม ERP และทดสอบการรันซ้ำที่ฐานข้อมูลอีกชุดหนึ่ง
9. แบ่งหน้าที่ก่อนส่งต่อไปทดสอบกับ ERP
- เจ้าของข้อมูล ยืนยันต้นทางและกติกาจับคู่
- ผู้ดูแลสภาพแวดล้อม ตรวจ sandbox สิทธิ์ และ hook
- เอเจนต์และผู้พัฒนา ซ้อมนำเข้าและส่งรายงาน
- ผู้ทบทวน ตรวจ diff ยอด และข้อยกเว้น
- ผู้อนุมัติ ตัดสินใจว่าจะเริ่มทดสอบกับ ERP แยกอีกงานหรือไม่
หากต่อยอดเป็น Odoo ต้องออกแบบการจับคู่ด้วย External ID หรือกุญแจที่ทีมตกลง ทดลองฐานข้อมูลแยก ตรวจสิทธิ์ผู้ใช้ ภาษี สาขา และข้อมูลเดิม รวมทั้งสำรองและซ้อมกู้คืน ประเด็นเหล่านี้ยังไม่ได้ทดสอบในชุดนี้ จึงไม่ควรนำ plan.csv ไปถือว่าเป็นไฟล์นำเข้า Odoo ที่พร้อมใช้ทันที
อาการที่ควรหยุดตรวจ
| อาการ | ตรวจอะไร |
|---|---|
| พบ exit code 2 | เปิด rejected.csv ก่อน อาจเป็นผลที่แบบฝึกหัดตั้งใจให้เกิด |
| hook ไม่ปรากฏ | ตำแหน่ง .agents/hooks.json เวอร์ชัน CLI และ session ที่เปิดใหม่ |
| คำสั่งถูก deny | คำสั่งและ Cwd ตรงกับรายการที่ตรวจไว้หรือไม่ อย่าขยายเป็น wildcard |
| หาไฟล์ไม่เจอ | อยู่ในรากโฟลเดอร์ตัวอย่างหรือไม่ และไฟล์ครบตาม ZIP หรือไม่ |
| sandbox ยืนยันไม่ได้ | หยุด session เอเจนต์ ให้ผู้ดูแลตรวจระบบ ใช้ Python กับข้อมูลสมมติแยกได้ |
| ยอดรายงานไม่ตรง | หยุดส่งต่อ ตรวจ header แถวที่ถูกตัด และ diff ของสคริปต์ |
เช็กลิสต์ก่อนจบแบบฝึกหัด
- ข้อมูลเป็นข้อมูลสมมติ และไม่มีรหัสผ่านหรือ token ในโฟลเดอร์
- ตรวจสถานะ sandbox และ hook จริงก่อนใช้เอเจนต์
- probe แบบยอมรับและแบบบล็อกให้ผลตามที่กำหนด
- อธิบายได้ว่าทำไมไฟล์ตั้งต้นได้ 2 เสนอเพิ่ม 2 ข้าม และ 2 ปฏิเสธ
- อ่านรายงานครบ ตรวจยอด และรักษาไฟล์ต้นทาง
- ซ้อมไฟล์ที่แก้แล้วและรันซ้ำได้ผลสม่ำเสมอ
- ผู้ทบทวนตรวจโค้ดและกติกาที่เปลี่ยน และยืนยันว่าไม่มีการเขียน ERP
สิ่งที่ตรวจแล้วและสิ่งที่ต้องตรวจบนเครื่องคุณ
ชุดไฟล์ผ่านการทดสอบ Python 12 ข้อและ probe ของ hook โดยตรงบน Python 3.9.6 รวมทั้งผลไฟล์ตั้งต้นและไฟล์ clean ตามยอดข้างต้น เครื่องที่จัดทำไม่มีคำสั่ง agy จึงยังไม่ได้รัน sandbox หรือทดสอบการดักคำสั่งผ่าน Antigravity จริง ขั้นตอนส่วนนั้นเป็นแนวทางตามเอกสารที่ผู้อ่านต้องตรวจบนเครื่องตัวเอง
เนื้อหาตรวจเอกสารเมื่อ 22 พฤศจิกายน 2569 พฤติกรรม CLI อาจต่างตามรุ่น บัญชี และระบบปฏิบัติการ หากของคุณไม่ตรง ให้ยึด schema และสถานะที่ตรวจได้ในรุ่นนั้น เก็บเลขเวอร์ชันไว้กับหลักฐานการทดลอง
อ่านต่อจากแหล่งต้นทาง
- Google Codelab: Practical Harness Engineering เป็นจุดเริ่มแนวคิด ส่วนข้อมูลสมมติ สคริปต์ และวิธีตรวจรับในบทนี้จัดทำขึ้นสำหรับแบบฝึกหัดนี้
- Antigravity Terminal sandbox สำหรับขอบเขตและระบบที่รองรับ
- Antigravity Hooks สำหรับไฟล์ตั้งค่า payload และคำตัดสิน