การอ้างอิง
การอ้างอิงช่วยให้ OpenCode เข้าถึงไดเรกทอรีที่อยู่นอกโครงการปัจจุบันได้ ใช้เพื่อเปิดให้เข้าถึงเอกสาร ไลบรารีที่ใช้ร่วมกัน ตัวอย่าง หรือที่เก็บโค้ดอื่นขณะที่คุณทำงาน
การอ้างอิงกำหนดค่าตามชื่อแทน (alias) ใน opencode.json หรือ opencode.jsonc
{
"$schema": "https://opencode.ai/config.json",
"references": {
"docs": {
"path": "../product-docs",
"description": "Use for product behavior and documentation conventions",
},
"sdk": {
"repository": "anomalyco/opencode-sdk-js",
"branch": "main",
"description": "Use for JavaScript SDK implementation details",
},
},
}ใช้ path เพื่ออ้างอิงไดเรกทอรีในเครื่อง
{
"references": {
"docs": {
"path": "../docs",
},
},
}พาธสามารถเป็น:
- พาธสัมพัทธ์กับไฟล์กำหนดค่าที่กำหนดการอ้างอิงนั้น
- พาธสัมบูรณ์ เช่น
/home/user/docs - พาธสัมพัทธ์กับโฮมไดเรกทอรีของคุณ เช่น
~/docs
คุณยังสามารถใช้รูปแบบสตริงแบบย่อได้:
{
"references": {
"docs": "../docs",
},
}ใช้ repository เพื่ออ้างอิงที่เก็บ Git โดย OpenCode จะสร้างที่เก็บนั้นไว้ในแคชที่เก็บในเครื่อง และเปิดให้ใช้ซอร์สโค้ดที่เช็กเอาต์แล้วเป็นไดเรกทอรีอ้างอิง
{
"references": {
"effect": {
"repository": "Effect-TS/effect",
"branch": "main",
},
},
}repository รองรับ Git URL, การอ้างอิงแบบ host/path และรูปแบบย่อ owner/repo ของ GitHub ฟิลด์ branch ซึ่งเป็นตัวเลือกใช้เลือกสาขาหรือ ref หากไม่ระบุ branch OpenCode จะใช้สาขาเริ่มต้นของที่เก็บนั้น
คุณสามารถใช้รูปแบบสตริงแบบย่อเมื่อไม่ต้องการระบุสาขา คำอธิบาย หรือตัวเลือกอื่นๆ:
{
"references": {
"effect": "Effect-TS/effect",
},
}เพิ่ม description เพื่ออธิบายว่าเอเจนต์ควรใช้การอ้างอิงเมื่อใด
{
"references": {
"design-system": {
"path": "../design-system",
"description": "Use when implementing UI components or design tokens",
},
},
}OpenCode จะรวมการอ้างอิงที่มีคำอธิบายไว้ในบริบทของเอเจนต์ คำอธิบายควรสั้นและเฉพาะเจาะจงพอที่จะแยกแยะการอ้างอิงที่มีเนื้อหาคล้ายกันได้ การอ้างอิงที่ไม่มีคำอธิบายยังคงใช้ได้ผ่านการเติมข้อความอัตโนมัติและการใช้งานโดยตรง แต่จะไม่ถูกแจ้งให้เอเจนต์ทราบ
ตั้งค่า hidden เป็น true เพื่อไม่ให้การอ้างอิงแสดงในการเติมข้อความอัตโนมัติ @ ใน TUI
{
"references": {
"internal": {
"path": "../internal",
"description": "Use for internal implementation details",
"hidden": true,
},
},
}hidden มีผลเฉพาะกับการเติมข้อความอัตโนมัติ การอ้างอิงที่ซ่อนไว้แต่มีคำอธิบายจะยังคงรวมอยู่ในบริบทของเอเจนต์
การอ้างอิงที่กำหนดค่าไว้จะปรากฏในการเติมข้อความอัตโนมัติ @ ของ TUI พิมพ์ @alias เพื่อแนบรูทของการอ้างอิง หรือพิมพ์ @alias/ เพื่อค้นหาไฟล์ภายในนั้น
Compare this implementation with @sdk/src/client.tsเอเจนต์ยังได้รับพาธที่แก้ไขแล้วและคำอธิบายของการอ้างอิงที่กำหนดค่าไว้และมีคำอธิบายในบริบทระบบด้วย จึงสามารถตรวจดูการอ้างอิงเมื่อเกี่ยวข้องได้โดยที่คุณไม่ต้องแนบเอง
OpenCode อนุญาตไดเรกทอรีอ้างอิงผ่านขอบเขตสิทธิ์ไดเรกทอรีภายนอกโดยอัตโนมัติ สิทธิ์ของเครื่องมือตามปกติยังคงมีผล ตัวอย่างเช่น เอเจนต์ที่แก้ไขไฟล์ไม่ได้จะไม่ได้รับสิทธิ์แก้ไขเพียงเพราะไดเรกทอรีถูกกำหนดค่าเป็นการอ้างอิง
| ฟิลด์ | ในเครื่อง | Git | คำอธิบาย |
|---|---|---|---|
path | ใช่ | ไม่ | ไดเรกทอรีอ้างอิงในเครื่อง |
repository | ไม่ | ใช่ | ค่า Git URL, host/path หรือ owner/repo ของ GitHub |
branch | ไม่ | ใช่ | สาขาหรือ ref ของ Git (ไม่บังคับ) |
description | ใช่ | ใช่ | คำแนะนำที่อธิบายว่าควรใช้การอ้างอิงเมื่อใด |
hidden | ใช่ | ใช่ | ซ่อนการอ้างอิงจากการเติมข้อความอัตโนมัติ @ ของ TUI |
ชื่อแทนของการอ้างอิงต้องไม่ว่างเปล่า และต้องไม่มี / ช่องว่าง แบ็กทิก หรือเครื่องหมายจุลภาค