Full lab เรียนต่อด้วยตัวเองประมาณ 2 ชั่วโมง — เปลี่ยนข้อมูลจริงเป็นแผนภาพด้วย diagram-design

Lab นี้ใช้ skill diagram-design จากโครงการ cathrynlavery/diagram-design เพื่อสร้างแผนภาพภาษาไทยเป็น HTML ที่มี SVG อยู่ในไฟล์เดียว แล้วส่งออก SVG สำหรับใช้ในเอกสาร หลักสูตร และ slide โดยยังตรวจย้อนกลับได้ว่าทุกกล่องและลูกศรมาจากข้อมูลใด

นี่เป็น full lab สำหรับเรียนต่อด้วยตัวเองนอก workshop 2 วัน / 8 ชั่วโมง เมื่อใช้เวลาประมาณ 120 นาที ผู้เรียนควรทำได้สี่อย่าง:

• ติดตั้ง skill แบบ global ใน Codex และตรวจ SKILL.md ที่ host โหลดจริง
• เลือกชนิดภาพจากความหมาย เช่น flowchart สำหรับลำดับงานและการตัดสินใจ หรือ sequence สำหรับข้อความระหว่างผู้เกี่ยวข้อง
• แยก source facts, visual brief และ fidelity ledger เพื่อไม่ให้ภาพสวยแต่บิดข้อมูล
• ส่งมอบ HTML/SVG ที่อ่านภาษาไทยได้ พร้อมผล self-check และการตรวจด้วยตา

ตัวอย่างที่ใช้ใน Lab คือ วงจรสร้างแผนภาพ และ ลำดับการจองอุปกรณ์ ส่วน gallery แผนภาพทั้งหมด แสดงรูปแบบอื่นที่นำไปปรับใช้กับบทเรียนได้

0–15 นาที: ติดตั้ง global และตรวจสิ่งที่ติดตั้ง

วิธีที่พกพาได้ที่สุดคือให้ Codex เรียก skill installer ของ host เอง เปิด session ที่ต้องการติดตั้งแล้วส่ง prompt นี้:

$skill-installer
ติดตั้ง skill จาก https://github.com/cathrynlavery/diagram-design แบบ global สำหรับ Codex
เลือก path skills/diagram-design จาก repository นี้
ก่อนติดตั้งให้ตรวจว่า source มี SKILL.md และแจ้ง path ปลายทาง
ถ้ามี diagram-design อยู่แล้ว ห้ามเขียนทับทันที ให้เปรียบเทียบ source/version และรายงานก่อน
หลังติดตั้งให้เปิด SKILL.md จาก path ที่ Codex โหลดจริง ตรวจ name, version และ license
จากนั้นรายงาน command หรือหลักฐานที่ใช้ตรวจ โดยยังไม่สร้าง diagram และไม่ติดตั้ง plugin อื่น

diagram-design ชุดนี้เป็น standalone skill ไม่ใช่หลักฐานว่ามี plugin ชื่อเดียวกันติดตั้งแล้ว ในเครื่องที่ใช้สร้างหลักสูตร มีการเรียก helper ของ Codex โดยตรงดังนี้ คำสั่งนี้เป็น หลักฐานเฉพาะ host นี้ ไม่ใช่ path ที่ผู้เรียนทุกเครื่องต้องคัดลอก:

python3 /home/dev/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo cathrynlavery/diagram-design \
  --path skills/diagram-design \
  --dest /home/dev/.codex/skills

ใน Codex ที่ใช้ path มาตรฐาน ตรวจ global install โดยกำหนด path ชัดเจนใน terminal เดียวกัน:

DIAGRAM_SKILL="${CODEX_HOME:-$HOME/.codex}/skills/diagram-design"
test -f "$DIAGRAM_SKILL/SKILL.md"
sed -n '1,12p' "$DIAGRAM_SKILL/SKILL.md"
test -f "$DIAGRAM_SKILL/scripts/self_check.py"

ผลของเครื่องหลักสูตรปัจจุบันคือ name: diagram-design, metadata version 2.6 และ license MIT Skill ที่ติดตั้งใหม่จะพร้อมใช้ใน turn ถัดไป หากยังไม่ปรากฏจึงค่อยตรวจ catalog/path และ reload session หาก host ใช้ directory อื่น ให้ใช้เมนู skills หรือเอกสารของ host หาไฟล์ที่โหลดจริง แล้วตั้ง DIAGRAM_SKILL เป็น directory นั้น อย่าแก้ปัญหาด้วยการคัดลอก skill ไปหลายตำแหน่งโดยไม่รู้ว่าตัวใดทำงานอยู่

อ่าน SKILL.md ให้ครบก่อนใช้ และอ่าน reference เฉพาะชนิดที่จะวาด เช่น references/type-flowchart.md หรือ references/type-sequence.md รวมทั้ง references/output-spec.md เมื่อกำหนด format/size/detail/audience

15–30 นาที: ตัดสินใจก่อนวาด

ถามก่อนว่า “ผู้อ่านเข้าใจได้ดีกว่าข้อความหรือตารางจริงหรือไม่” หากคำตอบคือไม่ ให้คงข้อความหรือตารางไว้ Skill นี้มีชนิดภาพจำนวนมาก แต่การเลือกเริ่มจากความหมาย ไม่ใช่จากหน้าตาที่ชอบ

ก่อนสร้าง ให้ระบุสี่ dial ที่ตรวจได้:

• format: html+svg
• size: doc-inline หรือ 960×600
• detail: balanced
• audience: mixed

จากนั้นบอกสิ่งที่จะตัดออกตาม complexity budget ภาพหนึ่งควรมี node ไม่เกิน 9 และลูกศรไม่เกิน 12 หากข้อมูลมากกว่านั้น ให้แยก overview กับ detail แทนการลดตัวอักษรจนอ่านไม่ได้

30–45 นาที: ทำ brand mapping ภาษาไทย

Lab นี้ใช้ DESIGN.md ที่ project root เป็น source of truth จึงปรับ skin จากค่าเริ่มต้นของ skill เป็น semantic roles ต่อไปนี้:

ใช้ Inter สำหรับข้อความละตินและ Noto Sans Thai สำหรับชื่อและคำอธิบายภาษาไทย โดยฝังหรือ host font ในโครงการเพื่อไม่เพิ่ม request ภายนอก ใช้ ui-monospace เฉพาะ endpoint, method, field หรือ command

โครงการนี้ใช้ marker .diagram-design เป็น profile: rawinnipa-ai-web-studio และ profile อยู่ที่ ~/.diagram-design/profiles/rawinnipa-ai-web-studio.md ตามกติกา marker-first สำเนาที่พกไปกับ source อยู่ใน design-system/diagrams/STYLE_GUIDE.md และค่าที่ generator อ่านอยู่ใน design-system/diagrams/tokens.json Marker ต้องมีเพียง profile: <slug> และต้องชี้ profile ที่มีอยู่; ห้ามเขียน marker ปลอมแล้วอ้างว่า profile ถูกสร้างแล้ว

45–80 นาที: สร้าง flowchart จาก source facts

เปิด Prompt สำหรับวงจรสร้างแผนภาพ แล้วส่งทั้ง block ให้ agent ผลลัพธ์อ้างอิงคือ:

คัดลอก prompt ฉบับเต็มนี้ได้โดยตรง:

$diagram-design
สร้างแผนภาพภาษาไทยอธิบายวงจรทำงาน “จาก brief ถึงแผนภาพที่ตรวจรับได้” สำหรับ AI Web Studio — ออกแบบและพัฒนาเว็บไซต์ด้วย AI ซึ่งเป็นหน่วยปฏิบัติส่วนหนึ่งของ 977-121 Module: Website Design and Development, Prince of Songkla University, Phuket Campus

ก่อนลงมือ:
- หา project root ของ repository ปัจจุบัน แล้วอ่าน DESIGN.md และ SKILL.md ของ diagram-design จาก installed path ที่ Codex โหลดจริง
- อ่าน references/type-flowchart.md และ references/output-spec.md ของ skill
- ถ้ามี .diagram-design marker ให้ resolve ตาม references/profiles.md; ห้ามสร้าง profile/marker ปลอมหรือแก้ global style guide เอง
- สรุปแผนหนึ่งย่อหน้า ระบุ visual type, size preset และสิ่งที่ complexity budget บังคับให้ตัด แล้วดำเนินการต่อ

Source facts ที่ต้องรักษา:
1. ระบุสิ่งที่ผู้อ่านต้องเข้าใจจาก source ที่ตรวจแล้ว
2. เลือก semantic pattern เมื่อพฤติกรรมเป็นสาระ แล้วเลือก visual type กับสี่ output dials
3. อ่าน type reference และ resolve project profile/tokens ก่อนวาด
4. สร้าง self-contained HTML ที่มี inline SVG เป็น source of truth
5. extract SVG จาก HTML ห้ามสร้าง source คนละชุด
6. รัน diagram-design self_check.py และ browser/geometry review
7. ถ้าไม่ผ่านให้แก้ HTML แล้ว extract/check ใหม่; หากผ่านจึงส่งมอบ HTML, SVG, ledger และหลักฐาน

ให้ใช้ flowchart เพราะสาระหลักคือขั้นตอนและ artifact ที่ส่งต่อกัน การวนกลับเมื่อไม่ผ่านเป็น feedback edge ของกระบวนการ
Output dials:
- format: html+svg
- size: doc-inline, viewBox 0 0 960 600
- detail: balanced
- audience: mixed

Brand mapping จาก DESIGN.md และ Rawinnipa brandbook:
- digital canvas #0A0A0A, surface #1A1A1A, rule #2A2A2A
- ink #F7F7F7, muted/soft #9CA3AF, accent #3EDC81
- งานพิมพ์ใช้ paper #F7F7F7 กับ ink #0A0A0A ตาม light-canvas exception
- ใช้ accent เฉพาะ decision สำคัญหรือปลายทางเพียง 1 จุดต่อภาพ
- ใช้ Noto Sans Thai สำหรับข้อความไทย, Inter สำหรับอังกฤษ และ ui-monospace เฉพาะคำเทคนิค
- ห้ามโหลด Google Fonts หรือ remote asset; ฝัง CSS และ SVG ใน HTML เดียว

ข้อกำหนด layout และ accessibility:
- ขั้นตอนเรียงซ้ายไปขวาและแสดง artifact HTML → SVG → verification ชัดเจน
- ใช้ node treatment ต่างกันตามหน้าที่ และใช้ feedback edge จาก review กลับไปแก้โดยไม่ทับเส้นทางหลัก
- connector นอกแกนต้องเป็นมุมฉากโค้ง ห้ามเส้นเฉียง ห้ามเส้นทับกันหรือผ่านหลัง non-endpoint node
- label ของเส้นมี opaque mask และช่องว่างจาก stroke 6–10px
- วาด connector ก่อน node; ใช้ grid 4px; ไม่เกิน 9 nodes, 12 arrows
- SVG มี role="img" และ aria-labelledby ที่ชี้ title/desc ID เฉพาะ; title เป็น child แรกและ desc อธิบายลำดับงานกับ feedback edge
- ข้อความไทยไม่น้อยกว่า 12px และต้องไม่ถูกตัดเมื่อเปิดที่ความกว้างจริง
- static เท่านั้น ไม่มี animation และไม่มี script

ส่งไฟล์:
- public/diagrams/diagram-workflow.html เป็น HTML source of truth
- public/diagrams/diagram-workflow.svg ที่ export จาก HTML

หลังสร้าง:
- ตั้ง DIAGRAM_SKILL เป็น installed directory ที่ตรวจพบจริง
- รัน python3 "$DIAGRAM_SKILL/scripts/self_check.py" public/diagrams/diagram-workflow.html
- เปิด HTML และ SVG ตรวจด้วยตาที่ขนาด 960×600
- รายงาน type/dials, source facts, fidelity ledger, path ทั้งสองไฟล์, command และผล check จริง
- fidelity ledger ต้องระบุ kept/merged/collapsed/dropped/invented; ถ้าไม่มี invented ให้เขียน none
- ห้ามอ้างว่าตรวจด้วย browser หรือ geometry ผ่านถ้ายังไม่ได้รัน/ดูจริง

• HTML ที่เปิดตรงใน browser
• SVG สำหรับเอกสารหรือโปรแกรม vector

Source facts ของภาพมีหกช่วง: ระบุสิ่งที่ผู้อ่านต้องเข้าใจ → เลือก pattern/type → อ่าน reference และ profile → สร้าง HTML → extract SVG → self-check กับ review หากไม่ผ่านจึงย้อนกลับแก้ Flowchart เหมาะเพราะแสดงลำดับ artifact และแยกผลตรวจ PASS ไปพร้อมใช้ ส่วน FAIL ย้อนกลับไปแก้ HTML อย่างชัดเจน

ก่อนรับงาน ตรวจสิ่งต่อไปนี้ด้วยตา:

1. ขั้นตอนเรียงตามงานจริงและบอก artifact จาก HTML ไป SVG ชัดเจน
2. ทางเชื่อมเยื้องแกนใช้มุมฉากโค้ง ไม่มีเส้นเฉียง
3. label ไม่ทับเส้น; มีพื้น mask และเว้น 6–10px
4. ลูกศรถูกวาดก่อนกล่อง ไม่มีเส้นวิ่งหลังกล่องที่ไม่ใช่ปลายทาง
5. สีน้ำเงินเด่นไม่เกินสองจุด และข้อความไทยยังอ่านได้ที่ขนาดแสดงจริง
6. SVG มี role="img", <title> เป็น child แรก, <desc> ไม่ว่าง และ aria-labelledby ชี้ ID เฉพาะของภาพ

80–100 นาที: สร้าง flowchart โดยรักษา contract ของระบบ

เปิด Prompt สำหรับ flowchart การจอง Prompt บังคับให้อ่านบท 06 และ source ก่อนวาด เพื่อให้ภาพสอดคล้องกับ contract จริง: availability เป็น preview, POST /api/rentals เป็น write path, D1 batch/trigger เป็น authority ของ capacity และผลสำเร็จคือ reserved-demo ไม่ใช่ payment confirmation

คัดลอก prompt ฉบับเต็มนี้ได้โดยตรง:

$diagram-design
สร้าง flowchart ภาษาไทยอธิบายความต่างระหว่าง availability preview และ write path ของการจองอุปกรณ์สาธิตในเว็บ “หยิบยืม” โดยยึด source ปัจจุบันของ repository นี้เท่านั้น

ก่อนลงมือ:
- หา project root ของ repository ปัจจุบัน แล้วอ่าน DESIGN.md
- อ่าน docs/lessons/06-rental-and-data.md, src/worker.ts และ migration ที่เกี่ยวกับ equipment, rentals, rental_days, capacity trigger และ idempotency จาก project root เดียวกัน
- อ่าน SKILL.md, references/type-flowchart.md และ references/output-spec.md จาก installed diagram-design skill ที่ Codex โหลดจริง
- หาก source กับข้อความด้านล่างขัดกัน ให้ source ปัจจุบันเป็นหลักและรายงานความต่าง ห้ามแต่ง endpoint, state หรือ payment flow
- สรุปแผนหนึ่งย่อหน้า ระบุ type, size preset, nodes, decision และสิ่งที่ตัด แล้วดำเนินการต่อ

เรื่องหลักที่ภาพต้องสื่อ:
- ผู้ใช้เลือก equipmentId, ช่วง [start,end) และ quantity ในหน้าเว็บ
- หน้าเว็บเรียก GET /api/availability เพื่อดู preview; ผลนี้ยังไม่ใช่ authority ของการจอง
- เมื่อผู้ใช้ยืนยัน หน้าเว็บส่ง POST /api/rentals พร้อม demo contact, consent และ Idempotency-Key
- Worker validate input และอ่านราคา/stock ฝั่ง server; client ไม่เป็น authority ของ price, stock หรือ status
- Worker ใช้ D1 batch และ rental_days capacity trigger เป็นจุดตัดสินตอน write
- เส้นทางสำเร็จตอบ 201 พร้อม status reserved-demo และ totalPrice จาก server
- เมื่อ capacity เพิ่งถูกใช้ ให้ตอบ 409 UNAVAILABLE และหน้าเว็บพาผู้ใช้กลับไปตรวจ availability ใหม่
- ไม่มี payment, contract, notification หรือการยืนยันเช่าจริงในภาพ

ใช้ flowchart ไม่เกิน 8 nodes: เลือกอุปกรณ์และวัน → GET availability เชิงแนะนำ → POST /api/rentals → อ่านราคาและ stock จาก D1 → D1 batch → capacity trigger decision → reserved-demo หรือ 409 conflict
ใช้ diamond เฉพาะ capacity trigger ซึ่งเป็นจุดแตกแขนง และติด label ให้ทางผ่าน/ไม่ผ่าน
จัดเส้นทางหลักไปตามลำดับการทำงานและใช้ connector มุมฉากโค้ง ห้ามวาด GET availability เป็น decision ที่ยืนยันการจอง

Output dials:
- format: html+svg
- size: doc-inline, viewBox 0 0 960 600
- detail: balanced
- audience: mixed

Brand mapping จาก DESIGN.md และ Rawinnipa brandbook:
- digital canvas #0A0A0A, surface #1A1A1A, rule #2A2A2A
- ink #F7F7F7, muted/soft #9CA3AF, accent #3EDC81
- งานพิมพ์ใช้ paper #F7F7F7 กับ ink #0A0A0A ตาม light-canvas exception
- accent เน้น capacity trigger และ critical path รวมไม่เกิน 1–2 focal elements
- ใช้ Noto Sans Thai กับชื่อ/คำอธิบายไทย, Inter กับอังกฤษ และ ui-monospace เฉพาะ GET, POST, endpoint, status และ field
- ห้าม remote assets; ฝัง CSS และ SVG ใน HTML เดียว

ข้อกำหนด layout และ accessibility:
- action เป็น rectangle และ capacity trigger เป็น diamond; ทางออกทุกเส้นจาก decision มี label
- จัด node บน 4px grid และเว้นระยะให้ข้อความไทยอ่านได้; label ต้องไม่ทับ arrow
- เส้นทาง reserved-demo และ 409 conflict แยกจาก decision อย่างชัดเจน
- ไม่มี connector ซ้อนกัน ไม่มีข้อความไทยเล็กกว่า 12px และไม่มี label ถูกตัด
- รวม node ไม่เกิน 8 และ arrows ไม่เกิน 12
- SVG มี role="img", title เป็น child แรก, desc ไม่ว่าง และ aria-labelledby ชี้ ID เฉพาะภาพ
- static เท่านั้น ไม่มี animation และไม่มี script

ส่งไฟล์:
- public/diagrams/rental-reservation.html เป็น HTML source of truth
- public/diagrams/rental-reservation.svg ที่ export จาก HTML

หลังสร้าง:
- รัน python3 "$DIAGRAM_SKILL/scripts/self_check.py" public/diagrams/rental-reservation.html โดยใช้ DIAGRAM_SKILL path ที่ตรวจพบจริง
- เปิด HTML และ SVG ตรวจด้วยตาที่ขนาด 960×600 และเทียบข้อความ/เส้นทางกับ source
- รายงาน fidelity ledger โดยระบุรายละเอียดที่ยุบหรือตัด เช่น validation ราย field, idempotency bookkeeping และ retention cleanup
- ระบุ path, command, exit/result, visual findings และข้อจำกัดที่ยังตรวจไม่ได้
- ห้ามเขียนว่า “จองสำเร็จ” โดยละคำว่า demo และห้ามสรุปว่า GET availability ยืนยัน capacity แล้ว

ผลลัพธ์อ้างอิงคือ:

• HTML flowchart
• SVG flowchart

ตรวจ source fidelity ด้วย ledger สั้น ๆ:

Detail: balanced · 8 nodes
Kept: GET availability preview, POST /api/rentals, D1 capacity decision, 201/409 outcomes
Collapsed: equipment lookup + daily rows + idempotency bookkeeping เป็น “D1 transaction + capacity trigger”
Dropped: contact-field validation และ retention cleanup เพราะไม่เปลี่ยนเรื่องหลักของภาพ
Invented: none

Ledger ไม่ใช่คำแก้ตัว แต่เป็นบันทึกว่าภาพย่ออะไร ผู้ตรวจควรเปิด docs/lessons/06-rental-and-data.md, src/worker.ts และ migration เพื่อยืนยันอีกครั้ง หาก source เปลี่ยน ต้อง regenerate และตรวจใหม่

100–115 นาที: สร้างซ้ำและตรวจผล

ไฟล์ตัวอย่างของหลักสูตรสร้างจาก source ที่มากับชุดดาวน์โหลดด้วย command นี้:

node scripts/build-diagrams.mjs

คำสั่งไม่ต้องเปิด local server และไม่ใช้ port จาก shared infrastructure เปิด HTML โดยตรงได้ จากนั้นตั้ง path ของ skill แล้วตรวจไฟล์สำคัญ:

DIAGRAM_SKILL="${CODEX_HOME:-$HOME/.codex}/skills/diagram-design"
python3 "$DIAGRAM_SKILL/scripts/self_check.py" public/diagrams/diagram-workflow.html
python3 "$DIAGRAM_SKILL/scripts/self_check.py" public/diagrams/rental-reservation.html
npm run check:diagrams

OK <path> พิสูจน์ accessible-SVG contract, การไม่ฝัง remote asset ที่ไม่ได้อนุญาต, script safety และ motion contract ที่ self-check รองรับ ส่วน npm run check:diagrams ตรวจแผนภาพทั้งชุดแบบ offline รวม embedded Thai fonts, SVG/XML, label bounds, prompt ที่ฝังอยู่, contrast และ browser geometry แล้วบันทึก artifacts/diagram-checks.json อย่างไรก็ตาม source fidelity ยังต้องเทียบ ledger กับไฟล์ต้นทางด้วยคน

ถ้าแก้เฉพาะไฟล์ .svg หลัง build ให้ถือว่า source diverge เพราะกติกาของ skill กำหนดให้ HTML เป็น source of truth และ SVG ต้อง export จาก HTML แก้ HTML/source generator แล้ว build ใหม่

115–120 นาที: ส่งหลักฐานและสะท้อนผล

ส่งมอบห้าอย่าง:

1. URL/repository และ metadata ของ skill ที่ติดตั้งจริง
2. source facts หรือ source files ที่อ่านก่อนวาด
3. prompt ฉบับเต็มพร้อมสี่ dial และ brand tokens
4. HTML, SVG, fidelity ledger และผล self_check.py
5. บันทึก visual review: type fit, connector, contrast, ภาษาไทย และสิ่งที่ต้องแก้

ตอบ retrospective: “ข้อมูลชิ้นใดถูกย่อหรือไม่ใส่ และถ้าใส่กลับจะช่วยความเข้าใจหรือเพียงเพิ่มความหนาแน่น?” คำตอบที่ดีระบุ trade-off และชี้ source ได้ ไม่ใช่บอกเพียงว่า “ภาพสวยและผ่าน check”

ข้อผิดพลาดที่พบบ่อย

แบบประเมิน

ผ่านเมื่อผู้เรียนสร้าง flowchart ของ workflow และการจองอย่างละหนึ่งภาพ, อธิบายเหตุผลเลือก type และสี่ dial, ชี้ได้ว่าข้อมูลทุก node/edge มาจากไหน, ส่ง fidelity ledger, รัน self-check ผ่าน และระบุข้อจำกัดที่ self-check ยังตรวจไม่ได้ ผู้เรียนไม่ผ่านหากอ้าง feature/state ที่ไม่มีใน source, ใช้ตัวอักษรเล็กจนอ่านไม่ได้ หรือส่งภาพโดยไม่มี HTML source of truth