什么是 Shelley 的 @ 文件补全

Shelley 是一个 web 端、移动端友好的编码 Agent（coding agent），它的聊天输入框内置了@ 文件补全功能：在输入框的单词开头输入@，就能对当前对话工作目录下的文件名、文件夹名做模糊搜索，并在 Git 仓库中同时搜索文件内容，帮你快速把某个项目文件以引用形式插入消息中。

对于动辄上万文件的大型项目，这个功能比手动敲完整路径高效得多——你只需要记住文件名的一两个片段，甚至文件里的一行代码。

📄 官方功能说明：FILE_COMPLETION.md

5秒上手：@ 补全基本操作

在聊天输入框中：

1. 在单词开头输入@，例如@readme；
2. 弹出候选列表，↑/↓选择结果，Enter或Tab插入，也可以直接鼠标点击；
3. 选中的文件/文件夹会以@相对路径的形式只替换光标处的@片段，周围的文字原样保留。

几个值得记住的细节：

• 文件夹带文件夹图标和结尾的/，选择它插入的是目录引用（而不是目录内容）；
• 补全只插入引用，不会读取或附带文件内容，Agent 后续是否读文件由它自己决定；
• 输入Escape可以关闭候选面板（不会让输入框失焦）；Shift+Enter仍会正常换行；
• 邮箱地址（如a@b.com）和 shell 模式（!开头）不会触发补全。

模糊搜索：多关键词 AND 匹配

@补全的命名搜索不是简单前缀匹配，而是多词 AND 模糊匹配：

• 查询按空白拆分为多个词，每个词都必须匹配路径，顺序任意。比如输入vm storage s3可以命中docs/vm-storage-s3-backup-design.md——这种"拆词找长文件名"的场景，普通前缀搜索做不到；
• 匹配字符会在候选行中高亮显示，让你一眼确认命中位置；
• 请求会防抖（debounce）并自动取消过期结果：你每敲一个键，旧请求立即作废，只展示最新结果，大目录下也不会卡顿。

服务端搜索逻辑位于 server/find_files.go，前端 token 解析与插入逻辑在 ui/src/utils/fileCompletion.ts。

Git 内容搜索：只记得一行代码也能定位文件

这是 @ 文件补全最"魔法"的部分：在 Git 仓库中，同样的词也会搜索文件内容。

• 内容命中会显示匹配行号 + 该行代码片段，并高亮命中词；
• 只匹配到内容、文件名不相关的文件，会排在所有名称匹配之后；
• 名字和内容同时命中的文件，会在名称行上附带代码片段作为上下文；
• 内容搜索基于git grep，会跳过二进制文件，也覆盖未跟踪（但未被忽略）的文件；
• 非 Git 目录只做名称搜索，内容搜索失败也绝不影响名称结果返回。

@storage ├── docs/vm-storage-s3-backup-design.md ← 名称匹配 ├── storage/manager.go │ L42: func NewStorage(...) ← 内容匹配（行号+片段） └── ...

两阶段并行搜索：为什么感觉"又快又全"

@ 补全复用了 Shelley 的findFiles接口（与Cmd/Ctrl+P文件查找器同源），采用两阶段并行策略：

两个请求并行发出、同生同死：名称结果先上屏，内容结果到达后再按路径合并（名称匹配保留优先位置，内容独占匹配追加在后）。任何一个词或上下文变化，两个请求都会被一起取消。

实现可参考：

• 前端编排：ui/src/vue/composables/fileCompletion.ts（防抖 120ms、AbortController取消、结果合并）
• 片段合并算法：ui/src/utils/fileSearch.ts 的mergeContentMatches
• 输入框集成：ui/src/vue/components/MessageInput.vue
• 服务端接口：server/find_files.go（/api/find-files，5 秒文件列表缓存 + 3 秒 grep 预算，保证每次击键不卡住）

进阶技巧：路径查询与引号

路径查询：从任意目录开始搜

如果输入的是一个显式路径前缀（/、~、./、../开头），搜索会以该目录为根：

• @./docs—— 直接把docs这个文件夹本身作为候选；
• @./docs/（带结尾斜杠）—— 改为浏览docs目录里面的内容；
• 输入一个已存在的文件路径（如工作目录下的notes.md），该文件会置顶锁定在结果第一位，即使它被.gitignore忽略也找得到。

⚠️ 注意：路径中间的斜杠（如docs/vm-storage）不是路径查询，而是普通的"部分路径"模糊匹配，作用于整棵树，不会限制到docs/目录。

引号：搜索含空格的文件名

• @"My Notes—— 双引号内可以包含空格和标点；
• 不加引号的查询遇到空白或散文标点（逗号、冒号、括号等）就结束，方便@file, 然后...这种"补全后直接接着写句子"的用法。

插入时路径会智能加引号：普通路径保持原样，含空格或分界标点的路径会被引号包裹并转义，例如@"My Notes.md"。

结果如何插入：只引用，不附件

选中结果后：

• 只替换光标所在的那个@token，其余文字不受影响；
• 插入的是相对当前对话工作目录的@引用（如@server/find_files.go）；
• 不会读取文件、不上传内容——这是引用语义，实际读取由 Agent 在处理消息时自行执行。

插入与引用格式的核心逻辑在 ui/src/utils/fileCompletion.ts 的insertFilePath与referenceForPath。

端到端测试：功能如何被验证

Shelley 为 @ 补全配备了两层测试：

• UI 单元测试（pnpm test，在 ui/ 下运行）：token 解析、插入、加引号、取消、过期响应等场景，见 ui/src/utils/fileCompletion.test.ts 与 ui/src/vue/composables/fileCompletion.test.ts；
• 浏览器端到端测试（LazyCue）：键盘/鼠标交互、文件夹选择、内容搜索、无结果场景，位于 test/lazycue_test.go 的TestNewPageFileCompletion*系列，构建 UI 后运行LAZYCUE_INTEGRATION=1 go test ./test/ -run TestNewPageFileCompletion -count=1即可。

服务端行为测试还有 server/find_files_test.go 和 server/find_files_cache_test.go。

常见问题速答

问：为什么候选列表先出来一部分、随后又"多"出几行？答：名称阶段先渲染，Git 内容搜索完成后追加内容命中。这是设计上的两阶段并行，保证首屏快、结果全。

问：在普通目录（非 Git 仓库）能用吗？答：可以，名称模糊搜索完全可用；内容搜索仅对 Git 仓库生效，缺失时静默降级，不影响其他功能。

问：搜索结果会超出多少？答：接口默认最多返回 100 条（上限 500），UI 默认展示前 20 行，超出会标记truncated。文件遍历有 50000 候选与 3 秒时间预算的保护，超大非 Git 目录也不会拖垮服务。

问：草稿恢复后 @ 补全搜的是哪个目录？答：新对话用当前选中的目录，重新打开的草稿会恢复其保存的目录；之后你在草稿中更改目录，补全会立即按新目录搜索，无需等待服务端持久化。

小结

Shelley 的 @ 文件补全把"找文件 + 插引用"压缩成一个键：

• @触发多词 AND 模糊搜索，命中高亮、防抖取消；
• Git 仓库内追加内容搜索，行号 + 代码片段帮你确认就是那个文件；
• 路径查询、引号查询覆盖目录浏览和含空格文件名两大进阶场景；
• 只插入@引用，不附带内容，轻量且语义清晰。

如果你经常在大项目中引用文件，这个功能值得第一时间用起来。