# 實體引用與 @

> 一條引用記的是穩定身分：正文用右鍵連接，長文字用 @，自動辨識只是淡提示。

Source: https://loomworld.ai/zh-tw/docs/references

## 一條引用裡記了什麼

全專案只有一套引用語法：一條引用保存通訊協定版本、作用範圍、物件類型、穩定 ID 和顯示文字。所以「指向誰」這件事在劇本、設定、時間軸、伏筆和 AI 代理對話裡都是同一個答案，你不需要記五種頁面的五種寫法。

物件改名後引用仍指向原來那張卡；同名物件靠類型和穩定 ID 區分，別名只幫助搜尋，不充當身分。專案裡同時有人物「月華」和設定「月華」時，候選會顯示成不同類型，選錯不了。

## 什麼時候值得連一條

當一段文字說的確實是專案裡已存在的某張卡時。引用的價值不是把詞染成顏色，而是讓人和 AI 都知道「這裡說的是哪一張卡」——續寫時它能被準確裝配，統計時它能被正確歸屬，回看時點一下就跳到那張卡。反過來，只是提一嘴、還沒建檔的東西不必連，也不必為了頁面好看去連。

## 在正文裡：右鍵「連接到…」

拖選一段文字後點右鍵。選單上半是改寫／擴寫／縮寫／潤飾與一句補充要求，下半是「連接到…」：搜尋框裡輸關鍵字，可搜尋到專案全部內容——人物、地點、道具、設定、章節、場次、時空、正文行、時間軸、伏筆和模組首頁。沒有可連結內容時會顯示「暫無可連結內容」，輸了沒命中顯示「沒有符合內容」。

你已確認要新建檔案時，候選裡會有「+ 新建人物『…』並連接」「+ 新建道具『…』並連接」這類明確選項——它是顯式動作，不是系統猜的。

## 在長文字裡：@ 的兩條路徑

- **兩級選擇**在設定描述、伏筆備註、時間軸說明等長文字區輸入 `@`，先選類別（人物／地點與地圖／道具／設定／劇本結構／時間軸／伏筆／模組入口），再在類別裡選具體內容。類別內不截斷候選，可以捲動看完並繼續輸入篩選。

- **直接搜**已經知道名字時，直接輸入 @關鍵字 跨類型搜尋，省掉一級選擇。兩條路徑最終寫入的是同一種穩定引用。

- **原位顯示**選中後引用立刻在原位變成可識別標籤，點擊跳到那張卡；不再另開一個下方預覽框。

搜尋同時比對正式名稱和別名，完全符合優先於前綴和包含符合。名稱與所在路徑分開比對，所以搜場次名不會把這一場裡的每一行正文都列成結果。

## 連上之後會發生什麼

- 劇本裡的人物、道具、地點連接繼續參與既有出場與使用辨識；其他目標是資訊型連接，只負責跳轉和給 AI 當上下文，不會反向改寫目標模組。
- 引用不會自動建立不存在的資料；也不會因為建立引用就把設定注入到 AI 上下文裡——模組首頁的引用只代表導覽。
- 引用本身不授予任何寫入權：AI 的寫入動作仍要過確認卡。

## 自動辨識不等於正式引用

編輯器會在正文裡認出人物、地點、道具、設定的名字，但只給很淡的點狀提示，hover 時有比選取區更淺的底色，點擊也不會直接開啟詳情。人物與道具的提示點上去會出現「轉為關聯」——你確認後這段文字才變成真正的引用。角色行不參與這層辨識，它本身已經指明了說話者。

只有已經連上的引用參與統計與 AI 裝配；淡提示只幫你看見「這裡好像提到過」。

## 限制與排錯

- 舊的 [[名稱]] 與舊劇本人物／道具寫法仍可讀取；舊名稱只對應一個物件時正常顯示，出現同名多義時標為歧義而不是靜默選第一個，找不到則標為失效。
- 物件被刪除後，引用保留原顯示文字，不會拿別的內容冒充目前資料。
- 首期不支援跨專案引用；想跨專案搬運請用專案包匯出匯入。
- 在輸入框裡按 Tab 不會開啟劇本的類型選單——那是原生輸入行為。

連動方向與副作用見 [跨模組連動](https://loomworld.ai/zh-tw/docs/cross-sync)。