第7篇：上下文引用——精准引用资料

这篇讲的是：如何用 @ 符号，把文件、代码、网页等内容“塞”进对话里，让 AI 精准理解你在说什么。

---

为什么需要“上下文引用”？

想象一下，你让 AI 帮你改作文，却只发一句“帮我改改第二段”——AI 根本不知道第二段在哪。
上下文引用就像给 AI 递上一支荧光笔，你划哪段，它就看哪段。

---

第1步：认识 @ 的几种“魔法口令”

在 Hermes 的交互式命令行（CLI）里，输入 @ 会自动弹出菜单。常用的有这些：

你输入	效果
@file:src/main.py	把整个文件内容贴进对话
@file:src/main.py:10-25	只贴第10到25行（精准切片）
@folder:src/components	列出文件夹里所有文件及大小
@diff	贴出当前未保存的代码改动
@staged	贴出已暂存（准备提交）的改动
@git:3	贴出最近3次提交记录（含补丁）
@url:https://example.com	抓取网页正文并贴入对话

---

第2步：组合使用，一次问多个

你可以一口气引用多个资料，结尾的逗号、句号、感叹号会被自动忽略，不用担心误伤：

检查 @file:main.py，顺便看看 @file:test.py。

---

第3步：用“行号切片”控制信息量

文件太大时，别整篇扔给 AI——指定行号更高效：

@file:src/auth.py:50-80    # 只看50到80行
@file:src/auth.py:42       # 只看第42行

行号从1开始数。如果范围写错了，AI 会默默忽略，返回整个文件。

---

第4步：了解“安全护栏”

Hermes 不会什么都给你看，防止泄露密码和密钥：

• 敏感文件直接拒绝：比如 ~/.ssh/id_rsa、~/.bashrc、.env 等。
• 敏感文件夹整体封锁：~/.ssh/、~/.aws/、~/.kube/ 等。
• 不能越界：只能引用当前工作目录内的文件，想 ../../etc/passwd？不行。
• 二进制文件自动拦截：图片、压缩包等非文本文件会收到警告。

---

第5步：注意“大小上限”

AI 的“脑子”（上下文窗口）是有限的，所以：

• 引用内容超过上下文长度的25%：会附加警告，但继续执行。
• 超过50%：直接拒绝，返回原消息。
• 文件夹最多显示200个文件，超出部分用 - ... 省略。
• @git: 最多要10条提交，写多了自动截断。

---

第6步：在聊天软件里怎么办？

注意：Telegram、Discord 等聊天平台不支持 @ 展开——消息会原样发给 AI。
但 AI 自己可以用 read_file、search_files 等工具去读文件，只是没有命令行那么方便。

---

实战小抄

# 代码审查
Review @diff 并检查安全问题

# 带上下文调试
测试失败了，这是测试 @file:tests/test_auth.py
和实现 @file:src/auth.py:50-80

# 项目探索
这个项目是干嘛的？@folder:src @file:README.md

---

总结

@ 引用 = 给 AI 递资料。学会用 @file: 切片、@diff 看改动、@url: 抓网页，你的提问会精准十倍。记住安全限制，别指望 AI 帮你读密钥文件。

下篇预告：当对话越来越长，AI 记不住前面说了啥怎么办？下一篇我们聊聊 “上下文压缩”——如何让 AI 在“失忆”边缘优雅地断舍离。