内容引用语法 [@ ] 使用指南

在正文里写 [@<内容ID>]，渲染时就会自动嵌入剪贴板文字、投票组件、图床图片或收藏夹卡片。 系统根据 ID 长度自动识别内容类型。

音频那一条是例外：它不按长度，而是写成 [@音频/<ID>] 这样一个带名字的形式 （ID 长度早被占满了，见「二、一览表」）。

能用的地方有四处：博客文章正文、云剪贴板正文、评论区、讨论区。四处支持的 引用类型不完全一样 —— 先照「一、三步上手」把最常用的走一遍，再用「二、一览表」查语法、 「三、四处地方，支持的不一样」看差异。

前置条件

• 需要已登录且通过邀请码认证（Core 用户及以上角色）
• 四种内容各有各的加载条件：剪贴板与图片需为公开状态，或你本人是作者；投票没有公开 / 私密之分，Core 及以上都能看到任意未删除的投票；收藏夹只能引用公开的（私密收藏夹没有对外 ID，见「三、四处地方，支持的不一样」）
• 单篇博客的显示上限是三档各自独立的：主循环最多替换 50 处（剪贴板 / 投票 / 图床图片共用这一个额度），收藏夹最多 3 张卡片，音频最多 3 个播放器 —— 收藏夹与音频不占主循环那 50 处
• 取数另有一道闸：需要取数的引用（剪贴板 / 投票 / 收藏夹）一轮最多取 50 个，图床图片与音频只拼地址、不占这个名额，同一个 id 引多次也只算一个。没排进这前 50 个候选的引用，连请求都不发、原样保留；已经排进候选、只是展开时排不上号的那些则可能已经取过数了
• 展开后还有长度闸：整篇正文（含替换进来的内容）封顶 50 万字符，装不下的那一条原样保留、不会被从中间截断
• 剪贴板引用不会再展开：一段剪贴板正文里若又写了 [@8位]，那一层原样显示。音频与收藏夹是合并后各跑一趟，不在这条之列 —— 从剪贴板带进来的音频引用仍会变成播放器

一、三步上手

三个最常用的动作，照抄即可。每一步背后的完整规则都在后面的分类型章节里。

1. 在博客里插一张图床图片

1. 打开 /image/，在图片卡片上复制它的 10 位 ID；

2. 在正文里就地写下这一行：

   [@AbCdEf1234]
   

3. 发布后打开文章详情页 —— 那一行会变成图片，点一下原地放大（不新开窗口）。

图片必须是公开的（或你自己就是上传者），否则别人看到的是一张裂图。 完整规则见「六、图床图片嵌入」。

2. 在博客里嵌入一段剪贴板

1. 打开 /clipboard/，复制那段的 8 位 ID（列表里、或详情页 URL /clipboard/<ID> 里都有）；
2. 正文里写 [@a1b2c3d4]；
3. 发布后，那段剪贴板的正文会被原样替换进来，其中的 Markdown 照常渲染 （标题、列表、代码块都生效）。

3. 在评论 / 讨论里发一张图

最省事的路是不用记 ID：点输入区的「从图床选择」，弹出你自己的图片列表，挑一张即可。 手打 [@AbCdEf1234] 一样有效。

⚠️ 评论与讨论里能展开的东西比博客少（投票、收藏夹都不展开，剪贴板只展开第一条）， 差别逐条列在「三、四处地方，支持的不一样」。

二、一览表

标题刻意不写「几种」：这张表加过行（表情、名片），而标题不会跟着动 —— 曾经就写着「三种」却列了五种。

ID 长度不在 6 或 8-10 之间的 [@...] 不会被处理，以原文形式保留。其中 6 位必须全是数字 —— [@abcdef] 这种 6 位字母不会被当成收藏夹，一样原样保留。8-10 位只认字母和数字，区分大小写。

收藏夹只能引用公开的。 私密收藏夹根本没有对外 ID（不是「有 ID 但不显示」）， 所以它既没有可写的 [@ID]，也生成不出二维码、读不到机器人接口。详见 收藏夹使用指南。

表情包那一行是另一套语法：它不是 ID 而是「合集名 / 表情名」两个名字，允许中文， 用斜杠分隔。两种语法不会互相误伤 —— ID 只认字母数字，而表情 token 必含斜杠。

想展示这个语法本身（而不是让它生效）？把它写进代码块或行内代码（`[@a1b2c3d4]`）—— 代码里的引用一律不展开，四处都一样。 反过来也成立：ID 打错、或引用的内容不存在时，看到的也是原文那串字符，不会报错、也不会 弹出提示 —— 所以文章里出现一句光秃秃的 [@a1b2c3d4]，先核对那串 ID。

三、四处地方，支持的不一样

上面那张表说的是你自己写的时候能写什么。读者是谁还另有一层 —— 文章设为 「凭链接可读」或「对外公开」之后，没登录的人读到的正文里：图床图片、音频播放器、 以及公开的剪贴板照常展开；投票与收藏夹保留字面量（它们的数据接口要求核心用户， 对外视图不请求，也就渲染不出来）。私密剪贴板对访客一律不展开 —— 即使你把它引用进了一篇公开文章。这一条的判据是「这条引用的读口，匿名取不取得到」。

评论与讨论里刻意不支持投票：投票是个可点选的交互组件，塞进讨论气泡和楼中楼里既挤又容易误触，要看投票请把链接贴出来。

评论与讨论里也不展开收藏夹，但理由不同：收藏夹卡片是一份列表（标题 + 若干文章链接）， 塞进讨论气泡里会占掉半屏，而且讨论区没有「一篇正文慢慢读」的语境。所以在评论区与讨论区里 [@123456] 原样显示为字面量 —— 与投票同样是刻意的，不是漏了。

收藏夹在博客里也另有更紧的上限：最多 3 张卡片。 卡片是块级元素，比一段文字高得多， 插十几张会把文章冲成一片卡片墙；扫描出的第 4 张起原样保留 [@123456] 字面量。 收藏夹属于「需要取数」的一类，因此也占用上面那 50 个取数名额、并计入 50 万字符的展开总长度。

表情包（[@合集/表情]）反过来 —— 只在评论与讨论里能用，博客正文与剪贴板正文里 原样显示。它走的是另一套语法的形状（不是 ID 而是名字），详见 表情包使用指南。

用户名片（[@用户/<用户名>]）与表情同向 —— 也只在评论与讨论里能用，而且同样 不是 ID 而是名字。它渲染成一枚行内名片（带头像框的小头像 + 用户名），点进那个人的主页， 见本文第七节。

另外两处细节差异：

• 剪贴板引用在博客里可以写很多条；在评论 / 讨论里一条消息只展开第一条，多写的那些原样留在正文里（[@abc12345] 就那么显示着）。这是刻意的上限，避免一条 10 个字的短消息展开成几十万字。
• 剪贴板正文超过 2000 字时，在评论 / 讨论里会被截断，后面接一句「内容过长，已截断」和回原剪贴板的链接。博客正文里不截断。
• 整篇展开后有总长度预算：博客 / 剪贴板正文里所有引用展开后，正文合计封顶 50 万字符。装不下的那一条原样保留（[@…] 留在那里），但单条引用不会从中间被截断 —— 单条完整、整篇有预算。
• 剪贴板引用不会再展开：从剪贴板带进来的正文里若又写了 [@8位]，那一层原样显示，不会继续挖下去（免得两条互相引用的剪贴板来回放大）。音频与收藏夹是合并后各跑一趟，不在这条之列。

站外读者看到的引用（文章对外公开时）

文章可以设为「对外可见」（见 docs/architecture.md §6.11），站外读者没有账号。 那种情况下正文里的内容引用按「这条引用的读口，匿名取不取得到」分两类：

• 照常展开的：图床图片、音频播放器，以及公开的剪贴板正文。公开剪贴板 那部分由服务端在渲染前解析好、随页面数据下发；
• 原样保留字面量的：私密剪贴板、投票、收藏夹。私密剪贴板匿名读不到；投票与 收藏夹的数据接口要求核心用户，站外视图根本不请求，于是渲染不出来。你会看到 [@a1b2c3d4] 这几个字符原封不动地留在那里，而不是一张卡片、也不是一句失败文案。

这是刻意的：站外视图不去调那三条要求核心用户的会话数据接口（剪贴板正文走服务端 下发，不请求 /api/clipboard/*）。但图床与音频的字节仍由浏览器按 URL 自己取 —— 这条说的是「站内的引用数据接口一个都不打」，不是「页面上一个请求都没有」。

服务端下发的那份公开剪贴板最多 50 条、合计 50 万字符，超出的原样保留 —— 这一步在服务端做完，不会把超量的内容随页面数据发给浏览器。

所以：如果你打算把一篇文章对外公开，并且希望站外读者也能看懂， 别把关键信息放在投票 / 收藏夹 / 私密剪贴板的引用里 —— 用普通的文字或图片写出来。

四、剪贴板嵌入（8 位 ID）

获取 ID

访问 /clipboard/，在列表中查看每个剪贴板的 8 位 ID，或从剪贴板详情页 URL /clipboard/<ID> 中获取。

使用方式

在正文中直接写入：

[@a1b2c3d4]

渲染行为

系统向后端请求剪贴板正文内容，将其原样替换 [@a1b2c3d4] 标记。剪贴板中的 Markdown 格式会正常参与后续渲染（标题、列表、代码块等均生效）。

错误处理

如果剪贴板不存在、非公开或无权限访问，该位置会显示：[剪贴板 a1b2c3d4 加载失败]

在站内这不算异常：剪贴板接口要求登录且 Core 以上，权限不够的人看到的就是那句 失败文案。你自己预览时若也看到它，先确认登录状态。

五、投票嵌入（9 位 ID）

⚠️ 只在博客正文与云剪贴板正文里生效。 评论区和讨论区不展开投票，[@vOtE12345] 会原样显示。

获取 ID

访问 /vote/ 查看你自己创建的投票列表（最新在前），或从投票详情页 URL /vote/<ID> 中获取。

列表只含你自己创建的投票。要打开别人的投票，用 /vote/ 顶部那栏「搜索跳转」：输入 ID 后点「前往」。

使用方式

[@vOtE12345]

渲染行为

系统请求投票数据并在文章内渲染一个投票小组件，形态随你的投票状态而变：

• 你还没投过、且投票未锁定：显示标题 + 可点击的选项 + 「投票」按钮，在文章里直接投票，无需离开本页。
• 你已投过票、或投票已被发起者锁定：显示结果视图 —— 每个选项的票数、百分比与进度条，顶部显示"共 X 票"，你投过的那项带 ✓ 高亮。
• 无论哪种状态，组件底部都有「查看详情」，新窗口打开投票详情页 /vote/<ID>。

投票后组件会重新拉取服务端的票数并就地刷新。

错误处理

如果投票数据加载失败，该位置会显示：[查看投票]（可点击跳转到投票页）

六、图床图片嵌入（10 位 ID）

获取 ID

访问 /image/ 查看你上传的图片列表，或在图片详情中获取 10 位 ID。

使用方式

[@AbCdEf1234]

渲染行为

系统把它换成图片地址 /api/images/AbCdEf1234/raw，四处都是这个地址。图片渲染后支持点击原地放大（不新开窗口）。

说明

图片嵌入不需要额外请求 API —— 系统直接拼接图片 URL，浏览器加载时自然请求 /api/images/<ID>/raw。如果 ID 对应图片不存在或已被删除，会显示为损坏图片。

⚠️ 图片必须是公开的（或者看图的人就是上传者本人）。私有图片只有作者与站长能取到，别人看到的是一张裂图 —— 这一点在四处都一样。

评论 / 讨论里发图还有一条更省事的路：点输入区的「从图床选择」，直接弹出你自己的图片列表挑一张，不用去翻 ID、也不用重新上传。

评论与讨论里手写 <img> 标签是显示不出图片的（会被当成普通文字）。能出来的图片只有 [@10位ID] 这一种形态 —— 这是防止有人贴外链图做跟踪像素。博客正文里手写 <img> 则允许。

七、用户名片嵌入（[@用户/<用户名>]）

⚠️ 只在评论区与讨论区生效。 博客正文与剪贴板正文里 [@用户/张三] 原样显示字面量。

在正文里写一个人的用户名，渲染出来是一枚行内名片：带头像（含头像框）的小头像

• 用户名，点一下进他的主页。

[@用户/张三]

这一条与其他引用都不一样：它认的是名字，不是 ID —— 你不用去翻谁的主页地址栏。 用户名在本站不可修改（注册之后没有任何改名的入口），所以今天写的名片明天还指得准。

怎么插入

评论区与讨论区的输入区工具栏上有一颗名片按钮：点开 → 搜用户名 → 选一个人， token 就落在光标处。不会替你发送（草稿还在，接着写完再发），也不会多带空格。

手打一样有效 —— 上面那行直接敲进去就行。

规则

• 一条消息最多 5 张名片，多出来的原样显示为 [@用户/…]。
• 名字打错 / 查无此人 → 原样显示字面量（不报错、不留半张卡）。所以看到原文 token 就是「这个人没找到」，不是页面坏了。
• 只认核心用户：输入区那个选择器搜得到的人是 core 及以上；非核心账号仍可以 手打 token 发名片，只是选择器搜不到。
• 不算 @ 提及：对方不会收到通知，铃铛与讨论红点都不动。想叫他就照常写 @张三 。
• 写在代码块 / 行内代码里的不展开（与其余引用一致）—— 想展示这个语法本身就这么写。
• 名片里的头像是站内那条恒定可推导的地址，所以「没上传过头像」的人也会有一张 （系统生成的图案），不会是裂图。

与表情的「用户」合集

[@用户/张三] 与表情 [@合集/表情] 形状完全一样，所以 用户 这个名字归名片 —— 站长的表情合集不能叫「用户」（那个目录会被扫盘跳过）。见 docs/guide/表情包使用指南.md。

八、注意事项

1. 非用户提及：[@ ] 语法不是 @用户 功能，不能用来提及或通知其他用户。
2. 数量限制：显示上限分三档 —— 主循环最多替换 50 处（剪贴板 / 投票 / 图床图片共用）、收藏夹最多 3 张、音频最多 3 个；取数上限是需要取数的剪贴板 / 投票 / 收藏夹一轮最多 50 个（图床图片与音频只拼地址、不占这个额度）；长度上限是整篇展开后的正文总长度封顶 50 万字符。超出的引用一律保留原文；其中没排进取数候选的连请求都不发。评论 / 讨论里剪贴板最多 1 条、图片最多 50 张。
3. 权限检查：私有剪贴板只有作者本人可以在文章中引用；其他人引用会加载失败。图片同理 —— 私有图对别人是裂图。
4. ID 大小写：ID 区分大小写（包含大小写字母和数字），请完整复制。
5. 编辑器里就能预览：写博客 / 剪贴板时右栏（窄屏是「预览」那一档）看到的就是展开后的样子 —— 它与发布后的详情页用的是同一台渲染器，不是另做的一份近似效果。两条例外：[@表情] 与 [@用户/…] 只在讨论区和评论区生效，正文里它们始终是普通文字（博客不支持这两类）。 预览是只读的：投票摆在那里但点不动，预览期间不会提交任何东西。写正文时也不需要手打 token —— 工具栏的「插入引用」面板可以挑一条直接插进来（图床 / 音频 / 剪贴板 / 投票 / 收藏夹），插进去的语法与手写完全一致。
6. 剪贴板内容为纯文本替换：嵌入的剪贴板 Markdown 会成为文章 Markdown 的一部分，注意避免引入破坏性的格式（如未闭合的代码块）。
7. 代码块里不展开：四处都一样 —— 想展示语法本身，就写进代码块或行内代码。
8. 剪贴板引用不递归：从剪贴板带进来的正文里若又写了 [@8位]，那一层不会再展开、原样显示 —— 免得两条互相引用的剪贴板来回放大。剪贴板引用自己、或两条剪贴板互相引用，都只展开一层。音频与收藏夹是合并后各跑一趟，不在这条之列。

本文只讲怎么用。为什么有四条管线、评论里的图片为什么走旁路这类实现细节属于开发文档， 见 docs/architecture.md §6.7。