Chorus 里的工作很少孤立存在，它往往依托于你正在参照的官方文档、你想借鉴的某个代码仓库、提出问题的那条 issue 讨论，
或是启发了做法的一篇文章。一条**参考资料**就是把这类佐证记为一个链接：一个 URL、一个标题，以及一条可选的说明，
讲清它为什么重要。Chorus 只保存链接和你的备注，从不抓取、下载或快照 URL 背后的页面。

参考资料可以挂在**想法**、**提案**或**任务**上，让佐证紧挨着它所支撑的工作。当智能体接手一个任务时，你附加的参考资料
会随之一起送达；当智能体提出提案时，它也可以把参考过的来源一并附上，供你核对。

## 添加参考资料

打开一个想法、提案或任务，找到它的**参考资料**区块：在提案面板上是一张卡片，在任务和想法上是一个带标题的区段。
点击**添加参考资料**并填写：

- **类型**：四种之一，每种都有各自的图标和标签：
  - **文档**：官方文档。
  - **代码仓库**：参考实现或代码库。
  - **Issue / PR**：一条 issue 或 pull request 讨论。
  - **论文 / 博客**：一篇论文或博客文章。
- **链接**：网页 URL（`http://` 或 `https://`；不接受本地文件）。
- **标题**：给这条参考资料起一个简短的名字。
- **备注**：可选。用一句话说明它为什么相关。展示时会截断为两行，所以尽量精炼；完整内容可以悬停查看。

参考资料会立即出现在区块中。编辑或删除参考资料也在同一处进行。删除会把链接从 Chorus 中移除，且无法恢复。

## 阅读内联引用

描述、文档或评论可以在提出某个论断的地方直接引用一条参考资料。引用在正文中显示为一个带方括号的小数字，例如 **[1]**：

- **悬停或聚焦**它，可以看到这条参考资料当前的标题、类型、链接和备注。如果文字写成之后参考资料又被编辑过，你看到的是最新版本。
- **选择**它，会在新标签页中打开来源。
- **灰色**的引用无法打开。悬停或聚焦它即可看到原因：参考资料已不存在（**证据不存在**），详情仍在加载，或者加载失败；加载失败时，它会在你下次悬停或聚焦时重试。

引用可以指向你有权访问的任何参考资料，而不限于你正在阅读的条目上附加的那些。针对[想法](/zh/guides/capture-an-idea/#在开发之前请求调研)进行的调研，正是靠这种方式把每条发现与其来源关联起来。

## 智能体如何使用参考资料

智能体附加参考资料的方式和你一样，这正是一份提案能够一开始就带着来源送到你面前的原因。持有 `document:write` 权限的
智能体有三个工具，分别是 `chorus_add_reference`、`chorus_update_reference` 和 `chorus_remove_reference`；在创建想法、
提案或一组任务时，它也可以内联附上参考资料。任何人读一个实体时都能内联看到它的参考资料，无需额外权限。

智能体以普通 Markdown 链接的形式书写引用，链接目标是参考资料的 ID，例如 `[1](ref:<reference-uuid>)`，所用的 ID 就是附加或读取参考资料时 Chorus 返回的那个。与任何参考资料都不匹配的 ID 会显示为**证据不存在**，因此智能体应先附加或查找参考资料，绝不能凭空编造 ID。

值得让你的智能体养成标注来源的习惯：一份链接了它所针对的确切 API 文档的提案，远比一份要你凭空信任的提案
更容易验证。关于这些工具的权限要求如何融入整体权限模型，请参阅[认证与权限](/zh/reference/authentication/)；关于工具本身，
请参阅 [MCP 工具目录](/zh/reference/mcp-tools/)。