ข้ามไปยังเนื้อหา
เอกสาร V1
ไดเรกทอรีในเครื่อง

การอ้างอิง

การอ้างอิงช่วยให้ OpenCode เข้าถึงไดเรกทอรีที่อยู่นอกโครงการปัจจุบันได้ ใช้เพื่อเปิดให้เข้าถึงเอกสาร ไลบรารีที่ใช้ร่วมกัน ตัวอย่าง หรือที่เก็บโค้ดอื่นขณะที่คุณทำงาน

การอ้างอิงกำหนดค่าตามชื่อแทน (alias) ใน opencode.json หรือ opencode.jsonc

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 เพื่ออ้างอิงไดเรกทอรีในเครื่อง

opencode.jsonc
{
  "references": {
    "docs": {
      "path": "../docs",
    },
  },
}

พาธสามารถเป็น:

  • พาธสัมพัทธ์กับไฟล์กำหนดค่าที่กำหนดการอ้างอิงนั้น
  • พาธสัมบูรณ์ เช่น /home/user/docs
  • พาธสัมพัทธ์กับโฮมไดเรกทอรีของคุณ เช่น ~/docs

คุณยังสามารถใช้รูปแบบสตริงแบบย่อได้:

opencode.jsonc
{
  "references": {
    "docs": "../docs",
  },
}

ใช้ repository เพื่ออ้างอิงที่เก็บ Git โดย OpenCode จะสร้างที่เก็บนั้นไว้ในแคชที่เก็บในเครื่อง และเปิดให้ใช้ซอร์สโค้ดที่เช็กเอาต์แล้วเป็นไดเรกทอรีอ้างอิง

opencode.jsonc
{
  "references": {
    "effect": {
      "repository": "Effect-TS/effect",
      "branch": "main",
    },
  },
}

repository รองรับ Git URL, การอ้างอิงแบบ host/path และรูปแบบย่อ owner/repo ของ GitHub ฟิลด์ branch ซึ่งเป็นตัวเลือกใช้เลือกสาขาหรือ ref หากไม่ระบุ branch OpenCode จะใช้สาขาเริ่มต้นของที่เก็บนั้น

คุณสามารถใช้รูปแบบสตริงแบบย่อเมื่อไม่ต้องการระบุสาขา คำอธิบาย หรือตัวเลือกอื่นๆ:

opencode.jsonc
{
  "references": {
    "effect": "Effect-TS/effect",
  },
}

เพิ่ม description เพื่ออธิบายว่าเอเจนต์ควรใช้การอ้างอิงเมื่อใด

opencode.jsonc
{
  "references": {
    "design-system": {
      "path": "../design-system",
      "description": "Use when implementing UI components or design tokens",
    },
  },
}

OpenCode จะรวมการอ้างอิงที่มีคำอธิบายไว้ในบริบทของเอเจนต์ คำอธิบายควรสั้นและเฉพาะเจาะจงพอที่จะแยกแยะการอ้างอิงที่มีเนื้อหาคล้ายกันได้ การอ้างอิงที่ไม่มีคำอธิบายยังคงใช้ได้ผ่านการเติมข้อความอัตโนมัติและการใช้งานโดยตรง แต่จะไม่ถูกแจ้งให้เอเจนต์ทราบ


ตั้งค่า hidden เป็น true เพื่อไม่ให้การอ้างอิงแสดงในการเติมข้อความอัตโนมัติ @ ใน TUI

opencode.jsonc
{
  "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

ชื่อแทนของการอ้างอิงต้องไม่ว่างเปล่า และต้องไม่มี / ช่องว่าง แบ็กทิก หรือเครื่องหมายจุลภาค