description: "面向用户与维护者的本地工作区 @file 补全提供方，用于启用、调整规模或排查 ctx.fileReferences 的发现能力。" kind: "package-reference"

@xfcodeai/dsh-file-reference-local

English | 中文

概述

agent（智能体）及宿主 UI 可以用各 agent 本地工作区中经过排序的路径补全 @file mention；有界发现让大型仓库也能保持响应迅速。结果会在工具活动后刷新且不会阻塞补全，并且始终不会跟随目录符号链接。当 read 可用时，模型还会收到关于如何理解引用路径的稳定指引。当 read 使用 Harness 宿主文件系统时选择本包；远程或虚拟命名空间需要与之匹配的发现能力。

目录

• 使用本包
• 理解实现
• 进一步探索
• 模型体验
• 已知限制与延期工作
• 开发备注

使用本包

当 @file 补全应发现 Harness 宿主自身的文件系统——即随附 read 工具所操作的命名空间——时，挂载此提供方。每个 agent 的工作区从该会话的工作目录开始建立索引；会话没有工作目录时回退到宿主进程目录。

启用提供方

默认设置适合典型工作区，因此最小挂载无需任何配置：

- name: '@xfcodeai/dsh-file-reference-local'
  config:
    maxResults: 20

你能得到什么

在宿主 UI 中输入 @ 会为指定 agent 返回至多 maxResults 个排序路径候选。包含 / 的查询直接列出匹配目录的条目；裸查询对有界递归索引做模糊排序。目录候选以尾斜杠保持 mention 开放。任何工具结果之后，该 agent 的索引会被标记为陈旧：下一次查询仍由它作答，其替代品在后台构建，因此重建不会挡在光标前面。

配置

| 字段 | 默认值 | 含义 | |---|---|---| | maxResults | 20 | 单次查询返回的排序候选最大数量 | | maxEntries | 50000 | 每个 agent 工作区建立索引的文件与目录最大数量 | | excludedDirectories | ['.git', 'node_modules', 'dist', 'build', 'out', 'coverage', 'target', '.next', '.nuxt', '.turbo', '.venv', '__pycache__', '.pytest_cache', '.mypy_cache', '.gradle'] | 遍历与候选中排除的目录基名 |

所有数值都必须是正的安全整数，所有排除名都必须是不含 / 或 \ 的非空基名。

理解实现

本节解释提供方的设计；可观察行为见使用本包。

设计理念

提供方为每个 agent 维护一个可复用的 WorkspaceFileSearch，以该会话的 cwd 为根。目录范围查询（a/b/...）列出实时目录状态，裸模糊查询共享一次有界递归遍历。每个工作区仅首次裸查询会等待该遍历；tool/result 事件把已完成的条目标记为陈旧，下一次裸查询在替代品构建期间继续由它作答。模型指引是按 agent 的提示词段，仅在指定 agent 拥有 read 工具时贡献；agent dispose（资源释放）时会同时释放索引与提示词 fiber。

源码地图

| 文件 | 职责 | |---|---| | src/index.ts | LocalFileReferenceService：配置校验、按 agent 搜索、提示词安装 | | src/search.ts | WorkspaceFileSearch：遍历、排序、排除、陈旧标记与后台重建 | | — | 不发布运行时不变式伴生入口；按 agent 的 index 是私有 advisory cache，其失效与 dispose 行为通过服务测试直接观察。 |

主要流程

list(agent, query, signal) 要么列出某个目录的条目，要么读取共享的有界索引，对候选排序（精确、前缀、子串，再到子序列得分，目录有加成），并按确定性顺序返回至多 maxResults 个。tool/result 事件把指定 agent 的索引标记为陈旧；下一次裸查询仍从旧索引返回结果，同时在后台构建替代索引。不可读或已排除的子目录不贡献候选，而不可读的根目录则让该次遍历失败：一次瞬时故障不得用空索引覆盖仍然有效的条目。

进一步探索

包级约定不够用时阅读以下页面。它们从本提供方所实现的 seam 进入其候选所指向的工具。

• 文件引用 seam——本提供方所实现的服务约定与 @file 语法。
• 会话引用子系统——宿主 UI 背后的共享文件引用约定。
• 文件系统工具目录——发现能力必须匹配其命名空间的 read 工具。
• 上下文组地图——相邻的请求上下文包。

模型体验

read 可用时的文件引用指引

模型看到的内容

当指定 agent 有实际生效的 read 工具时，提供方会贡献以下稳定的系统提示词段：

文件引用指令

Tokens prefixed with @ are workspace paths the user explicitly referenced, relative to the workspace root. A trailing slash marks a directory: list it when its contents matter. Anything else is a file: use the read tool when its contents are needed, and do not claim to have inspected it before reading. @"..." quotes a path containing spaces.

Token 影响

该影响有条件且固定：只要 read 对指定 agent 可见，这一句就会存在；候选查询本身不增加 token，所选路径只会贡献普通用户消息中的对应字符。

KV Cache 影响

该稳定句子会加入系统提示词前缀。挂载或移除此提供方，或者改变 read 是否可见，都会改变该前缀；查询、候选项和索引陈旧标记不会改变前缀。

已知限制与延期工作

这些限制说明该提供方何时不合适。它们是当前包约束。

• 宿主本地命名空间：提供方扫描 Harness 宿主的文件系统，因此远程或虚拟 read 实现需要使用命名空间与该工具一致的提供方。
• 有界的提示性索引：超大型工作区可能省略 maxEntries 之后的路径；被排除或无法读取的目录不会出现。默认排除项只列没有任何生态用作源码目录的构建产物；lib 被刻意排除在外，因此构建进 lib 的工作区需通过 excludedDirectories 自行加上。
• 一次失效的陈旧窗口：紧接工具结果之后的裸查询反映的是上一次遍历时的目录树；下一次查询才看到重建结果。
• 没有忽略文件语义：.gitignore 和其他项目忽略文件不会影响发现；系统只排除已配置的目录基名。

开发备注

无。