跳到主要內容
本機目錄

參照

參照讓 OpenCode 可以存取目前專案之外的目錄。您可以用它在工作時提供文件、共用函式庫、範例或其他儲存庫。

參照在 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 形式的參照以及 GitHub owner/repo 簡寫。選用的 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 或 GitHub owner/repo 值
branch否是選用的 Git 分支或 ref
description是是說明何時使用該參照的指引
hidden是是在 TUI 的 @ 自動完成中隱藏該參照

參照別名不能為空，也不能包含 /、空白字元、反引號或逗號。