ในการพัฒนาและจัดระเบียบระบบ Multi-Agent ด้วย OpenCode เมื่อโครงการเริ่มมีขนาดใหญ่ขึ้น การจัดเก็บไฟล์ Agent ไว้ที่ Root Directory ทั้งหมดอาจทำให้โปรเจกต์ดูวุ่นวาย การจัดโครงสร้างแบบ Subfolder จึงเป็นทางออกที่ดี แต่รู้หรือไม่ว่า OpenCode มีกลไกการค้นหาและอ้างอิงชื่อ (Name Resolution) ที่มีรายละเอียดสำคัญซึ่ง Dev ต้องควรรู้!
1. พฤติกรรมหลักในการค้นหา Agent (Discovery Behavior)
OpenCode จะสแกนหาไฟล์ .md แบบ Recursive ลึกลงไปในโฟลเดอร์หลัก .opencode/agents/ ไม่ว่าจะซ้อนโฟลเดอร์ย่อยกี่ชั้นก็ตาม โดยมีเกณฑ์การระบุชื่อเรียก (Name Resolution) ดังนี้:
- กรณีที่ 1 (อยู่ใน Subfolder โดยไม่ระบุ field name): หากเก็บไฟล์ไว้ที่
.opencode/agents/subagents/explorer.mdโดยไม่มีฟิลด์ name กำหนดไว้ OpenCode จะนำ Relative Path มาต่อเป็น Prefix ส่งผลให้ชื่อเรียกกลายเป็น@subagents/explorer - กรณีที่ 2 (วางไว้ที่ Root หรือกำหนด name ชัดเจน): หากวางไว้ที่ Root
.opencode/agents/explorer.mdหรือระบุฟิลด์ name กำกับไว้ใน Frontmatter ชื่อเรียกจะกลายเป็น@explorerเสมอ
2. วิธีบังคับใช้ชื่อสั้น (Custom Short Names) แม้อยู่ใน Subfolder
หากต้องการจัดระเบียบไฟล์ใส่โฟลเดอร์ย่อย เช่น .opencode/agents/subagents/explorer.md แต่อยากเรียกใช้สั้นๆ แค่ @explorer สามารถทำได้ง่ายๆ โดยการกำหนดฟิลด์ name: ใน Frontmatter ของไฟล์ดังนี้:
---
name: explorer
description: Read-Only Repository Discovery Subagent
mode: subagent
model: openai/gpt-4o-mini
---ข้อดี: การกำหนด Custom Short Name ช่วยให้การเขียนสั่งงาน (Delegation) ในไฟล์หลักอย่างlead.mdหรือtask-planner.mdสั้น กระชับ และอ่านง่ายขึ้นมาก
3. ข้อควรระวังและ Best Practices
- หลีกเลี่ยงชื่อซ้ำ (Name Collisions): ห้ามตั้งชื่อ Agent ซ้ำกันข้ามโฟลเดอร์ เช่น
team-a/tester.mdและteam-b/tester.mdเพราะจะเกิดการ Overwrite ทับกันทันที - ขอบเขตสิทธิ์ (Permission Scope): การกำหนดสิทธิ์ Read/Edit ภายในไฟล์
.mdของ Agent จะยังคงอ้างอิง Path จาก Root ของ Project เสมอ ไม่เกี่ยวกับตำแหน่งโฟลเดอร์ย่อยที่ไฟล์ Agent นั้นวางอยู่
สรุป: หากต้องการจัดโฟลเดอร์ย่อยเพื่อความสะอาดของโปรเจกต์ อย่าลืมใส่
name:ใน Frontmatter ทุกครั้ง เพื่อให้เรียกใช้งาน Subagent ได้สะดวก และป้องกันปัญหาเรื่อง Path ที่ซับซ้อนครับ
No comments:
Post a Comment