TUI file-reference autocomplete
TUI 文件引用自动补全
The TUI offered structured `@session` references but no dependable way to discover workspace paths while composing a prompt. Requiring users to remember exact paths made file-oriented requests unnecessarily awkward, while eagerly attaching every selected file would spend context before the model knew whether its contents were relevant and would hide the normal `read` observation from the tool transcript.
English
Problem
The TUI offered structured @session references but no dependable way to discover workspace paths while composing a prompt. Requiring users to remember exact paths made file-oriented requests unnecessarily awkward, while eagerly attaching every selected file would spend context before the model knew whether its contents were relevant and would hide the normal read observation from the tool transcript.
Decision
The TUI owns a bounded, cancellable host-workspace path index rooted at the active session's working directory. Typing @ at a token boundary fuzzy-matches files and directories; queries containing / list the named directory directly, accepting a directory continues completion, and paths containing whitespace use the @"path with spaces" form. Configuration controls result count, index size, and excluded directory basenames. The default exclusions are .git and node_modules; traversal does not follow directory symlinks or interpret ignore files.
Selecting a file changes only the editor text. The submitted user message retains the natural @path spelling and carries no injected contents, hidden context, or reference object. When the model-facing read tool is registered, the TUI contributes a stable system-prompt section that identifies @ paths as explicit user references, directs the model to call read when contents are needed, and forbids claiming inspection before that call. Tool results invalidate the reusable fuzzy index so subsequent interactions observe likely workspace mutations.
Structured session mentions keep their existing snapshot preparation. Unlike files, a referenced session has no general model-facing retrieval tool, so reducing @session to a path-like label would make its content unreachable.
Alternatives considered
Eagerly inject selected file contents. This spends tokens before relevance is known, can capture stale content before execution reaches the reference, and bypasses the auditable read call/result sequence.
Require an external file finder. Depending on fd, rg --files, or another executable would make baseline completion vary by host installation and complicate cancellation and cross-platform behavior.
Use the filesystem service's ordinary directory-list operation for discovery. That seam is optimized for exact model-facing filesystem operations and may represent a remote namespace; recursive fuzzy indexing would multiply provider round trips and couple editor latency to tool policy. Host-side discovery keeps the terminal interaction local, while the documented namespace-alignment limitation remains explicit for non-local deployments.
Add a new cross-package file-search capability. The TUI is the only current consumer and the behavior is editor presentation rather than a model capability, so a new interface, implementation, and consumer package set would split the seam prematurely.
Consequences
Users can discover and insert paths without making selection itself expensive or model-visible beyond the path. The model preserves agency over whether to inspect a file, and any inspection remains reconstructable through the logged tool transcript. The fixed instruction slightly enlarges TUI system prompts when read is present, and content-requiring requests take an additional tool round trip.
Completion is deliberately bounded and advisory: very large workspaces may omit paths beyond the configured index cap, ignored files may still appear, and remote or virtual filesystem deployments must align the TUI host working directory with the read namespace or supply a different completion surface. Package tests pin token grammar, ranking, bounds, cancellation, invalidation, path-only submission, the visible menu, and keyboard completion; a deployment shipping the TUI owns its Loader and PTY acceptance.
中文
问题
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 验收。