เว็บแอดมินคือหน้าต่าง ไม่ใช่แหล่งข้อมูลที่ถูกต้องชุดที่สอง
แผงควบคุมเว็บแอดมินของ APX ไม่ใช่ศูนย์กลางของระบบ
การออกแบบนั้นมีความเข้มงวด Daemon เป็นเจ้าของสถานะ (state) ส่วน Web UI เป็นเพียงไคลเอนต์ในเครื่อง (local client) ความแตกต่างนี้มีความสำคัญ เพราะมันเป็นตัวกำหนดว่า "ความจริง" (truth) จะถูกจัดเก็บไว้ที่ไหน และข้อมูลจะเกิดการคลาดเคลื่อน (drift) ได้มากน้อยเพียงใด
APC ทำหน้าที่เป็นเลเยอร์บริบทที่พกพาได้ (portable context layer) ส่วน APX ทำหน้าที่เป็นเลเยอร์รันไทม์และเครื่องมือ (runtime and tooling layer) โดยเว็บแอดมินนั้นเป็นส่วนหนึ่งของ APX ซึ่งช่วยให้คุณตรวจสอบรันไทม์ผ่านเบราว์เซอร์ได้ แต่มันไม่ได้เก็บสำเนาของข้อมูลจริงของโปรเจกต์ไว้เอง
สถาปัตยกรรมทำงานดังนี้:
- Daemon รัน HTTP server ในเครื่อง
- ทุกส่วนติดต่อ (surface) สื่อสารกับ daemon ผ่าน HTTP
- เว็บแอดมินถูกให้บริการโดย daemon
- เบราว์เซอร์ดึง token จาก daemon
เบราว์เซอร์ไม่ใช่ฐานข้อมูลคู่ขนาน (peer database) แต่มันเป็นเพียงส่วนติดต่อหนึ่งเท่านั้น เมื่อใดก็ตามที่เว็บแผงควบคุมกลายเป็นแหล่งข้อมูลที่สอง เมื่อนั้นมันจะล้มเหลว
การมีสถานะ (state) สองชุดนำไปสู่ข้อผิดพลาด:
- CLI เขียนข้อมูลอย่างหนึ่ง แต่ UI แสดงผลอีกอย่างหนึ่ง
- เซสชันในเบราว์เซอร์แก้ไขการตั้งค่า (config) แต่ daemon ยังคงใช้ข้อมูลเก่า
- การรีโหลดแสดงโปรเจกต์หนึ่ง ในขณะที่แท็บอื่นแสดงข้อมูลที่ล้าสมัย (stale data)
- การแก้ไข UI ไม่ส่งผลไปถึงรันไทม์ที่ใช้งานจริง
APX หลีกเลี่ยงปัญหานี้ด้วยการทำให้เบราว์เซอร์ทำงานให้น้อยที่สุด (thin) โดย UI จะถาม daemon จากนั้น daemon จะถาม core และ core จะเป็นผู้ไปอ่านหรือเขียนข้อมูลลงใน backing store จริงๆ ห่วงโซ่นี้มีความเรียบง่าย และความเรียบง่ายคือสิ่งที่ดี
แผงควบคุมในเครื่องที่ดีควรทำสามสิ่งนี้:
- แสดงสถานะปัจจุบัน (live state)
- ส่งคำสั่ง (action) ขนาดเล็ก
- ตรวจสอบความถูกต้องใหม่ (revalidate) หลังจากการดำเนินการ
แผงควบคุมนี้ช่วยให้คุณเรียกดูโปรเจกต์, agents, routines, sessions, MCPs และการตั้งค่าต่างๆ มันคือมุมมองหนึ่งของระบบ ไม่ใช่การแยกตัว (fork) ออกมาจากระบบ
รายละเอียดการปรับใช้ (implementation) ช่วยให้ทุกอย่างทำงานในเครื่อง:
- Dev mode ใช้ Vite และทำ proxy ไปยัง daemon
- Production จะให้บริการแอปที่ build แล้วผ่าน daemon
- การใช้ Same origin ช่วยให้การทำ auth และ routing เรียบง่าย
- เบราว์เซอร์ไม่จำเป็นต้องมีสิทธิ์เขียนข้อมูลลงใน repo โดยตรง
ประโยชน์ที่ได้รับไม่ใช่ความสวยงามของหน้าตา แต่คือการที่ทุกการดำเนินการจะถูกจัดการผ่าน backend เพียงหนึ่งเดียว
หากคุณแก้ไขการตั้งค่าในแผงควบคุม แผงควบคุมจะส่งการเปลี่ยนแปลงนั้นไปยัง daemon จากนั้น daemon จะอัปเดต project store และการแสดงผล (render) ครั้งถัดไปจะอ่านข้อมูลจากแหล่งข้อมูลจริง (source of truth) ชุดเดียวกับที่ CLI อ่าน ระบบเดียว แต่มีหลายส่วนติดต่อ
UI สามารถหายไปได้โดยไม่ส่งผลเสียต่อโปรเจกต์ของคุณ คุณสามารถปิดแท็บหรือย้ายเครื่องได้ เพราะสถานะจะยังคงอยู่ใน daemon และในโฟลเดอร์ .apc/
โมเดลทางความคิด (mental model) นั้นเรียบง่าย:
- APC: คือสิ่งที่โปรเจกต์เป็น
- APX: คือวิธีที่โปรเจกต์ทำงาน
- Web admin: คือหน้าต่างหนึ่งที่ใช้มองเข้าไปในรันไทม์นั้น
รักษาขอบเขตนี้ให้ชัดเจน เพื่อให้ stack สามารถเปลี่ยนทดแทนได้ เบราว์เซอร์เป็นเพียงทางเลือก daemon ยังคงเป็นผู้มีอำนาจตัดสินใจ (authoritative) และโปรเจกต์ยังคงพกพาได้
Source: https://dev.to/agentprojectcontext/the-web-admin-is-a-window-not-a-second-source-of-truth-2aip
Optional learning community: https://t.me/GyaanSetuAi