04.3 上下文附件与建议系统

关注源码

  • src/context.ts
  • src/utils/attachments.ts
  • src/services/PromptSuggestion/promptSuggestion.ts

上下文不是只靠 messages

进入模型的内容除了对话消息，还包括大量动态注入的上下文和附件，例如：

  • git 状态
  • CLAUDE.md
  • 当前日期
  • memory files
  • agent list
  • task delta
  • MCP instructions delta
  • LSP diagnostics
  • 计划文件
  • IDE 选区

这些大多由 utils/attachments.ts 组织。

attachments.ts 的角色

这个文件本质上是“上下文编排器”，它会统一处理：

  • 文件类附件
  • 图片/document 附件
  • 任务附件
  • memory / CLAUDE.md 注入
  • toolSearch / MCP delta 注入
  • skill listing / agent listing 注入

也就是说，很多看似零散的上下文能力，最后都在这里汇合成可发送给模型的 message/attachment。

为什么附件层很重要

因为它决定了：

  • 模型到底看见哪些辅助信息
  • 信息是以内联文本、附件还是 delta 的形式出现
  • 哪些内容在 compact 后会被重新注入

它其实是 system prompt 之外的第二条上下文总线。

Prompt Suggestion

PromptSuggestion/promptSuggestion.ts 负责下一条 prompt 建议，触发时会检查：

  • 是否交互式会话
  • 是否 leader 而非 teammate
  • 是否被 settings / gate 关闭
  • 当前是否有 pending permission / elicitation
  • 当前是否处于 plan mode

真正生成建议时也走 forked agent，并复用 cache-safe params。

Suggestion 与 Speculation 的关系

Prompt suggestion 只负责“给出建议文本”。

如果 speculation 开启，则会在建议生成后进一步：

  • 预跑可能的后续结果
  • 把推测结果存进 AppState
  • 在用户接受建议时节省响应时间

因此 suggestion 是 UI 功能，但实现上仍然与 runtime/fork/cache 强耦合。

设计上的关键点

1. context 注入是统一编排，而不是多个模块各自写 prompt

这有助于控制缓存稳定性和上下文体积。

2. 建议系统建立在同一运行时之上

它不是简单模板匹配，而是复用 agent runtime 获取高质量建议。

3. attachment 层连接了记忆、任务、MCP、技能与 UI

很多系统把这些能力分散在不同 feature 中，这里则把它们统一成模型可消费的上下文入口。