# การอ้างอิง

> นี่คือเอกสารของ OpenCode V1 เอกสารล่าสุดสำหรับ OpenCode V2 อยู่ที่ https://opencode.ai/docs/llms.txt

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

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

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

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

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

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

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

```jsonc title="opencode.jsonc"
{
  "references": {
    "docs": "../docs",
  },
}
```

---

## ที่เก็บ Git

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

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

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

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

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

:::note
การอ้างอิง Git จะรีเฟรชแบบอะซิงโครนัส ที่เก็บที่เพิ่งกำหนดค่าอาจใช้เวลาสักครู่ในการโคลนหรืออัปเดตให้เสร็จ
:::

---

## อธิบายการใช้งาน

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

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

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

---

## ซ่อนรายการในการเติมข้อความอัตโนมัติ

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

```jsonc title="opencode.jsonc"
{
  "references": {
    "internal": {
      "path": "../internal",
      "description": "Use for internal implementation details",
      "hidden": true,
    },
  },
}
```

`hidden` มีผลเฉพาะกับการเติมข้อความอัตโนมัติ การอ้างอิงที่ซ่อนไว้แต่มีคำอธิบายจะยังคงรวมอยู่ในบริบทของเอเจนต์

---

## ใช้การอ้างอิง

การอ้างอิงที่กำหนดค่าไว้จะปรากฏในการเติมข้อความอัตโนมัติ `@` ของ TUI พิมพ์ `@alias` เพื่อแนบรูทของการอ้างอิง หรือพิมพ์ `@alias/` เพื่อค้นหาไฟล์ภายในนั้น

```text
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 |

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