# 实体引用与 @

> 一条引用记的是稳定身份：正文用右键连接，长文本用 @，自动识别只是淡提示。

Source: https://loomworld.cn/docs/references

## 一条引用里记了什么

全项目只有一套引用语法：一条引用保存协议版本、作用域、对象类型、稳定 ID 和显示文字。所以"指向谁"这件事在剧本、设定、时间线、伏笔和智能体对话里都是同一个答案，你不需要记五种页面的五种写法。

对象改名后引用仍指向原来那张卡；同名对象靠类型和稳定 ID 区分，别名只帮助搜索，不充当身份。项目里同时有人物"月华"和设定"月华"时，候选会显示成不同类型，选错不了。

## 什么时候值得连一条

当一段文字说的确实是项目里已存在的某张卡时。引用的价值不是把词染成颜色，而是让人和 AI 都知道"这里说的是哪一张卡"——续写时它能被准确装配，统计时它能被正确归属，回看时点一下就跳到那张卡。反过来，只是提一嘴、还没建档的东西不必连，也不必为了页面好看去连。

## 在正文里：右键「连接到…」

拖选一段文字后点右键。菜单上半是改写 / 扩写 / 缩写 / 润色与一句补充要求，下半是「连接到…」：搜索框里输关键词，可搜到项目全部内容——人物、地点、道具、设定、章节、场次、时空、正文行、时间线、伏笔和模块首页。没有可链接内容时会显示「暂无可链接内容」，输了没命中显示「没有匹配内容」。

你已确认要新建档案时，候选里会有「+ 新建人物“…”并连接」「+ 新建道具“…”并连接」这类明确选项——它是显式动作，不是系统猜的。

## 在长文本里：@ 的两条路径

- **两级选择**在设定描述、伏笔备注、时间线说明等长文本区输入 `@`，先选类别（人物 / 地点与地图 / 道具 / 设定 / 剧本结构 / 时间线 / 伏笔 / 模块入口），再在类别里选具体内容。类别内不截断候选，可以滚动看完并继续输入过滤。

- **直接搜**已经知道名字时，直接输入 @关键词 跨类型搜索，省掉一级选择。两条路径最终写入的是同一种稳定引用。

- **原位显示**选中后引用立刻在原位变成可识别标签，点击跳到那张卡；不再另开一个下方预览框。

搜索同时匹配正式名称和别名，完全命中优先于前缀和包含命中。名称与所在路径分开匹配，所以搜场次名不会把这一场里的每一行正文都列成结果。

## 连上之后会发生什么

- 剧本里的人物、道具、地点连接继续参与既有出场与使用识别；其他目标是信息型连接，只负责跳转和给 AI 当上下文，不会反向改写目标模块。
- 引用不会自动创建不存在的资料；也不会因为建立引用就把设定注入到 AI 上下文里——模块首页的引用只代表导航。
- 引用本身不授予任何写入权：AI 的写动作仍要过确认卡。

## 自动识别不等于正式引用

编辑器会在正文里认出人物、地点、道具、设定的名字，但只给很淡的点状提示，hover 时有比选区更浅的底色，点击也不会直接打开详情。人物与道具的提示点上去会出现「转为关联」——你确认后这段文字才变成真正的引用。角色行不参与这层识别，它本身已经指明了说话人。

只有已经连上的引用参与统计与 AI 装配；淡提示只帮你看见"这里好像提到过"。

## 限制与排错

- 旧的 [[名称]] 与旧剧本人物 / 道具写法仍可读取；旧名称只对应一个对象时正常显示，出现同名多义时标为歧义而不是静默选第一个，找不到则标为失效。
- 对象被删除后，引用保留原显示文字，不会拿别的内容冒充当前资料。
- 首期不支持跨项目引用；想跨项目搬运请用项目包导出导入。
- 在输入框里按 Tab 不会打开剧本的类型菜单——那是原生输入行为。

联动方向与副作用见 [跨模块联动](https://loomworld.cn/docs/cross-sync)。