上下文引用

上下文引用让你在一轮 Anyy 对话中显式附加本地文件、目录、URL、git 变更或之前的工具结果。它们写在消息正文里，语法是 @kind:target。

引用是单轮上下文。它们不会变成记忆，不会编辑 SOUL.md，也不会让工具集可见。展开后的内容会以带引用元数据的不可信运行时数据加入上下文。

支持的引用类型

语法	加载内容
@file:path	allowed root 下的文本文件，或运行时允许的绝对文本文件路径。
@file:path:10-40	文本文件的指定行范围。
@folder:path	排序后的单层目录列表。
@url:https://example.com/page	公开 HTTP(S) 页面文本。
@result:tool_result_id	当前会话中保存的工具结果。
@diff	会话工作目录的当前 git diff。
@staged	当前 staged git diff。
@git:3	最近带 patch 的 git commits，最多钳制到 10。

使用示例

Use @file:docs/plan.md and @diff to review the current docs changes.

Compare @file:cmd/anyy/browser.go:1-120 with @url:https://example.com/spec.

Summarize the top-level layout in @folder:internal/gateway.

解析器会在文本开头、空白字符后或常见分隔符后识别引用。

行范围

文件行范围使用 target 中最后一个冒号：

@file:internal/tools/artifact.go:1-120

范围必须是 start-end，两者都是正整数，且 end 必须大于等于 start。错误范围会变成 warning reference，而不是被静默忽略。

大小限制

默认展开限制：

限制	默认值
每轮引用数	8
单个引用字节数	64 KiB
总引用字节数	192 KiB
URL 内容字符数	12,000
Git capture 字节数	256 KiB

展开后，context builder 会估算 token 用量。如果引用超过上下文窗口的 25%，Anyy 会加入 warning；如果超过 50%，会拒绝展开后的引用块，并返回 warning reference。

安全

敏感路径阻断

Anyy 在加载本地文件、目录或 git 引用前会阻断明显的秘密路径和名称。示例包括 .ssh、.aws、.kube、.docker、.env、.npmrc、.netrc、credentials.json、私钥文件名，以及包含 credential、token、secret、api_key 等标记的路径片段。

路径穿越保护

相对目录和 git 引用会基于请求工作目录和 allowed root 解析。它们不能通过 .. 或符号链接逃出该 root。

文件引用也会拒绝相对 profile-home 解析中的父路径片段，并拒绝符号链接或非普通文件。

二进制文件检测

文件引用会拒绝包含 NUL 字节的二进制内容。大文本文件需要用行范围引用，或先缩小内容再附加。

URL 引用只获取公开 HTTP(S) 页面。私有/内网 URL 和不支持的 scheme 会被阻断。

平台可用性

上下文引用依赖提供 reference expander 的常驻运行时路径。它们可用于把用户文本和 reference roots 传给 prompt assembly 的 gateway 对话。

如果某个 surface 没有提供工作目录或 allowed root，folder、diff、staged 和 git 引用可能会失败，并返回 warning reference。

与记忆和压缩的关系

引用不是记忆。如果引用里包含长期用户偏好，请让 Anyy 保存一条简洁记忆，而不是依赖未来对话继续引用同一内容。

大引用会在 prompt assembly 前预算。当内容放不下时，Anyy 会附加 warning，而不是静默丢弃所有上下文。