ในการพัฒนาและจัดระเบียบระบบ Multi-Agent ด้วย OpenCode เมื่อโครงการเริ่มมีขนาดใหญ่ขึ้น การจัดเก็บไฟล์ Agent ไว้ที่ Root Directory ทั้งหมดอาจทำให้โปรเจกต์ดูวุ่นวาย การจัดโครงสร้างแบบ Subfolder จึงเป็นทางออกที่ดี แต่รู้หรือไม่ว่า OpenCode มีกลไกการค้นหาและอ้างอิงชื่อ (Name Resolution) ที่มีรายละเอียดสำคัญซึ่ง Dev ต้องควรรู้!
1. โครงสร้างและการค้นหา Agent (Discovery Behavior & Directory Tree)
OpenCode จะสแกนหาไฟล์ .md แบบ Recursive ลึกลงไปในโฟลเดอร์หลัก .opencode/agents/ ไม่ว่าจะซ้อนโฟลเดอร์ย่อยกี่ชั้นก็ตาม โดยจะใช้โครงสร้าง Relative Path มากำหนดชื่อเรียก (Name Resolution) โดยอัตโนมัติ ตัวอย่างเช่น:
.opencode/
└── agents/
├── lead.md # เรียกใช้ผ่าน @lead
└── subagents/
├── explorer.md # เรียกใช้ผ่าน @subagents/explorer
└── tester.md # เรียกใช้ผ่าน @subagents/testerหากวางไว้ที่ Root โครงสร้างชื่อจะเป็น @explorer เสมอ แต่ถ้าอยู่ในโฟลเดอร์ย่อย ชื่อเรียกจะถูกแปลงเป็น @subagents/explorer ตามพาธจริง
2. การอ้างอิงข้ามโฟลเดอร์ (Cross-folder Delegation)
เมื่อมีการแบ่งโฟลเดอร์ย่อยตามทีมหรือหน้าที่ การสั่งงาน (Delegation) ระหว่าง Agent จะต้องอ้างอิงตามชื่อพาธเต็มที่ระบบสแกนได้ เช่น หากไฟล์ lead.md ต้องการเรียกใช้งาน Subagent ในโฟลเดอร์ย่อย จะต้องระบุชื่อเต็มดังนี้:
กรุณาให้ @subagents/explorer ช่วยตรวจสอบโครงสร้างโปรเจกต์
และให้ @subagents/tester ช่วยรันชุดทดสอบต่อครับ3. ข้อควรระวังและ Best Practices
- ความยาวของ Path: ควรหลีกเลี่ยงการสร้างโฟลเดอร์ที่ซ้อนกันลึกเกินไป (Deep Nesting) เพราะจะทำให้ชื่อเรียกยาวและพิมพ์สั่งงานได้ยาก
- หลีกเลี่ยงชื่อซ้ำ (Name Collisions): แม้จะอยู่คนละโฟลเดอร์ การตั้งชื่อไฟล์ให้สื่อความหมายชัดเจนและไม่ซ้ำกันจะช่วยลดความสับสนในการอ้างอิง
- ขอบเขตสิทธิ์ (Permission Scope): การกำหนดสิทธิ์ Read/Edit ภายในไฟล์
.mdของ Agent จะยังคงอ้างอิง Path จาก Root ของ Project เสมอ ไม่เกี่ยวกับตำแหน่งโฟลเดอร์ย่อยที่ไฟล์ Agent นั้นวางอยู่
สรุป: ในเวอร์ชันปัจจุบัน OpenCode ใช้กลไกการสแกน Relative Path เป็นหลักในการอ้างอิงชื่อ Subagent โดยอัตโนมัติ การจัดระเบียบผ่าน Subfolder จึงช่วยให้โปรเจกต์เป็นระเบียบ แต่อย่าลืมตรวจสอบชื่อเรียกตามพาธจริงให้ถูกต้องก่อนใช้งานครับ
No comments:
Post a Comment