3.6 KiB
Agent Note: TUI 文件引用自动补全
Status: implemented Archived: 2026-08-04
English | 中文
问题
TUI 提供结构化的 @session 引用，但用户在编辑提示词时无法可靠地发现工作区路径。要求用户记住准确路径会给面向文件的请求带来不必要的麻烦；如果直接附加每个选中文件，则会在模型判断其内容是否相关之前占用上下文，并在工具 transcript（文本记录）中隐藏常规的 read 观察结果。
决策
TUI 维护一个有容量上限且可取消的主机工作区路径索引，以活跃会话的工作目录为根。在 token 边界输入 @ 会对文件和目录进行模糊匹配；查询包含 / 时会直接列出指定目录，接受目录后会继续补全，包含空白的路径采用 @"path with spaces" 形式。配置项控制结果数量、索引大小以及排除的目录基名。默认排除 .git 和 node_modules；遍历既不跟随目录符号链接，也不解析忽略文件。
选择文件只会改变编辑器文本。提交的用户消息保留自然的 @path 写法，不携带注入的内容、隐藏上下文或引用对象。注册面向模型的 read 工具时，TUI 会加入一个稳定的系统提示词段，说明 @ 路径是用户的显式引用，指示模型在需要内容时调用 read，并禁止模型在调用前声称已检查文件。工具结果会使可复用的模糊索引失效，后续交互因而能看到工作区中可能发生的变更。
结构化会话提及保留现有的快照准备方式。与文件不同，被引用的会话没有通用的模型侧检索工具；如果把 @session 简化为类似路径的标签，模型将无法获取其内容。
备选方案
直接注入选中文件的内容。 这种方式会在确定相关性前消耗 token，可能在执行到该引用前捕获到陈旧内容，并绕过可审计的 read 调用与结果序列。
要求使用外部文件查找器。 依赖 fd、rg --files 或其他可执行文件，会使基础补全行为随主机安装情况而变化，也会增加取消处理和跨平台支持的复杂度。
使用文件系统服务的常规目录列表操作进行发现。 该 seam 针对面向模型的准确文件系统操作进行了优化，并且可能表示远程命名空间；递归模糊索引会增加提供方往返次数，并使编辑器延迟与工具策略耦合。主机侧发现让终端交互保留在本地，同时文档仍明确说明非本地部署中的命名空间对齐限制。
新增跨包的文件搜索功能。 TUI 是目前唯一的消费方，而且该行为属于编辑器呈现而非模型功能；新增一组接口、实现和消费方包会过早拆分这条 seam。
影响
用户可以发现并插入路径，而选择操作本身不会带来高开销，对模型可见的内容也仅限路径。模型仍可自行决定是否检查文件，任何检查都能通过已记录的工具 transcript 重建。存在 read 时，固定指令会略微增大 TUI 系统提示词；需要文件内容的请求还会增加一次工具往返。
补全有意采用有界的提示性设计：超大型工作区可能省略超过配置索引上限的路径，被忽略的文件仍可能出现，远程或虚拟文件系统部署必须让 TUI 的主机工作目录与 read 命名空间对齐，否则需要提供不同的补全接口。包（package）测试固定 token 语法、排序、边界、取消、失效、仅提交路径的行为、可见菜单和键盘补全；交付 TUI 的部署负责其 Loader 与 PTY 验收。