feat: support prompt file references

[yuefengw]

Description

Add support for explicit @file references in user prompts so referenced local files are included as model context.

Related Issues

Fixes #31

Changes Made

• Added prompt file reference parsing for unquoted and quoted paths
• Resolve file references relative to the project root
• Validate missing files, directories, binary files, and oversized files before submission
• Attach referenced file contents to the OpenAI user message while keeping the visible session prompt clean
• Added tests for parsing, validation, file loading, and message rendering with referenced files

Checklist

• Changes tested locally
• Code reviewed
• Documentation updated (if necessary)
• Unit tests added (if applicable)

Additional Notes

This intentionally keeps the first version simple and explicit: it does not add indexing, directory expansion, or chunk/rerank behavior.

This PR focuses on explicit @file prompt references first. Autocomplete and directory expansion can be added later without changing the message pipeline.

[yuefengw]

哈喽~ 要合并嘛~

[qorzj]

这个PR暂时不能合并，因为涉及后端需要谨慎，我需要调研一下目前主流的agent(codex, cc等) 最新的策略是什么，以及背后的动机是什么？欢迎在PR里继续提供这一块的背景信息。

[yuefengw]

PR暂时不能合并，因为涉及到这个需要细节，我需要调研一下目前主流的代理(codex, cc等)最新的策略是什么，以及背后的动机是什么？欢迎在PR里继续提供这块的背景信息。

补充一下我调研后的背景和这个 PR 的取舍。

我看了一下目前主流coding agent的相关策略，大体趋势不是自动把大量文件塞进上下文，而是更偏向 用户显式指定 + 控制上下文体积 + 保持可追踪：

1. Claude Code
   Claude 官方帮助文档明确建议：如果用户已经知道相关文件，可以用 @path/to/file 指向文件，这样更快、也更省 token。它的动机是减少 agent 自己搜索代码库的成本，同时提升上下文相关性。
   参考：https://support.claude.com/en/articles/14553240-give-claude-context-claude-md-and-better-prompts

2. Cursor
   Cursor 的 @Files 也是显式 file reference。它会让用户选择/确认文件；遇到长文件时会做 chunk/rerank 或上下文管理。
   参考：https://docs.cursor.com/context/%40-symbols/%40-files

3. Codex
   Codex CLI 的公开文档更强调“本地运行、按需读取/修改/执行代码”，以及只发送用户 prompt、高层上下文和必要摘要。它的 AGENTS.md 机制也是受控地给 agent 提供项目上下文，而不是默认上传整个 repo。
   参考：https://developers.openai.com/codex/cli
   参考：https://github.com/openai/codex/blob/main/docs/agents_md.md

基于这些策略，我这个 PR 的实现刻意保持得比较保守：

• 只处理用户显式写出的 @file / @"file with spaces"，不会自动扫描目录或索引代码库。
• 不支持目录引用，避免一次性把大量文件注入上下文。
• 单文件和总大小都有上限，避免 prompt 膨胀。
• 二进制文件会被拒绝。
• 找不到文件、目录、过大文件都会在提交前阻止，而不是静默降级。
• 文件内容不会直接污染可见聊天历史，而是作为 message params 存储，在组装 OpenAI message 时才追加进用户文本。
• 格式上使用 <referenced_files><file path="..."><![CDATA[...]]></file></referenced_files>，让模型能清楚区分用户原始 prompt 和被引用文件内容。

背后的动机是：

• 用户明确知道相关文件时，@file 能减少 agent 盲目搜索和多轮 read 工具调用。
• 显式引用比自动注入更安全、可控，也更符合 CLI 场景。
• 尚未引入 chunk/rerank、目录 condensation、文件索引等复杂策略；这些可以后续在已有 message pipeline 上扩展。

如果有需要我可以根据您的指示作出修改，或者先合并，后续我将持续对此优化~

[qorzj]

@yuefengw Make sense! 但在PR的代码实现上，有两个阻塞级别的问题：

1. session.ts::SessionMessage是整个系统的核心类，它的contentParams字段目前是用于向LLM透传messages.content的，而meta字段目前用于控制UI逻辑。因此fileReferences我更倾向于直接放到contentParams的并列层级。

2. DeepCode的Read/Edit tool有一个重要特性，就是调用Edit工具必须要提供之前的Read工具返回的snippet_id，否则会要求调用Read工具读取整个文档。fileReferences如果不跟Read工具打通，那么上下文的内容就没办法对接Edit工具（也就是说，虽然LLM已经知道文档内容了，但如果要修改文档，还是需要调Read工具重读一遍）。我的建议是：不要自己实现把fileReferences的文档内容直接加载到system prompt/user prompt中，而是触发调用已有的Read tool，把Read tool的返回包装成一个visible为false的system prompt。

[yuefengw]

这版把 fileReferences 放到了 SessionMessage 顶层，和 contentParams 并列；同时移除了直接把文件内容拼进 prompt 的实现。现在 file reference 会触发已有 Read tool，Read 返回会包装成 visible: false 的 system message，因此 snippet/file state 会走原有 Read/Edit 链路，Edit 可以使用 Read 返回的 metadata.snippet.id。

已验证 typecheck、lint、file reference tests、Read/Edit tool tests。

[qorzj]

@yuefengw 再次思考后我认为file metion功能的意义在于：

1. 在前端可以帮助用户更快地补全输入，相当于把IDE的文件引用功能迁移到了TUI界面上
2. 在早先的agent模式中，会直接把文件全文塞进会话上下文(context)

在目前的LLM能力基线下重新审视，可以发现第2点的意义已经很小了。就如上面的回复中提到的，现在大体趋势不是自动把大量文件塞进上下文，而是依靠LLM自己判断读取全文还是读取片段。实际上，最稳妥的办法就是框架什么都不做，只要prompt中包含了被引用的文件路径，LLM自然就会调用Read工具去加载它。

对于Deep Code项目来说，这个PR的实现还有另一个问题，就是后端的改动太大了。虽然可能会引入一点好处，比如agent为了调用Read工具会消耗一些思考/推理的时间和token，但代价是：1）让框架调用Read工具不“智能”，可能会浪费上下文；2）Read工具从单纯的LLM agent tool变成一种被框架依赖的功能，这会导致后期维护难度显著变大。

PR的方案还有一个功能定义上模糊之处：当@快捷方式引用了文件的内容，但尚未提交时，如果删掉文件路径的一部分，按道理应该删除已挂载的文件内容，并且重新尝试挂载新的文件内容。例如：如果@docs/mcp.md触发挂载了mcp.md内容，但用户又往前删除了'd'，只剩下@docs/mcp.m，此时我们需要重新尝试挂载mcp.m的内容。如果输入框本身内容为@docs/mcp.md line 11...，然后用户删除了中间的空格，这时应该怎样处理？这个场景仔细思考下去，有点深不见底……

所以，file metion功能的最大意义反而在于前端的便利性。但这个PR反而没有实现前端的自动扫描目录或索引代码库。

因此。这个PR将会被关闭。并且，基于上面的分析，我已经在main分支实现了@唤起file metion的前端交互功能。欢迎在此基础上继续提PR优化。Thanks~